Vector Field 3D component

[bewuwy]

Like #458 but in 3D!

[bewuwy]

This was generated by AI during triage.

Agent Brief

Category: enhancement (new reusable 3D primitive component)
State: ready-for-agent
Label: none — library component, not an applet (same rationale as #458).

Summary: Add a VectorField3D (3D quiver) component — the 3D twin of #458. Samples f(x,y,z) → (u,v,w) on a regular 3D grid and draws an arrow (or line) per non-zero vector.

Current behavior:
No 3D vector-field / quiver component exists. The building block is Vector3D (threlte), whose props mirror the 2D Vector2D exactly: color, origin, direction, length, hideHead, noNormalise. Unlike 2D, the 3D layer works in world units directly (no scale2D context).

Desired behavior:
Mirror the #458 VectorField2D design in 3D. Keep the prop shape parallel to #458 so the two APIs stay consistent.

Interface (behavioral, names indicative):

• f: (x, y, z) => [number, number, number] | Vector3 — required. Returns (u,v,w) at (x,y,z).
• Grid: xMin/xMax/yMin/yMax/zMin/zMax + stepSize. Sample f at each 3D grid node. See performance defaults below.
• scale: boolean — default true.
  • true: length = |(u,v,w)| × scaleLength via Vector3D's noNormalise (true magnitude; no auto-normalize to max).
  • false: fixed length 0.4 × stepSize (normalized direction).
• scaleLength: number — default 1 (applied only when scale=true).
• isArrow: boolean — default true; false → lines (Vector3D hideHead).
• anchor: 'start' | 'middle' | 'end' — default 'start':
  • start: origin = (x,y,z) (node = tail)
  • middle: origin = node − dir·length/2
  • end: origin = node − dir·length (arrowhead on node)
• color: ColorString — default a PrimeColor.
• colorFn?: (u, v, w, x, y, z) => ColorString — optional per-arrow color; off by default.
• Zero vectors: |(u,v,w)| ≈ 0 → render nothing at that node.

Performance (the 3D-specific concern):

• A 3D grid is cubic — node count grows as (ranges/stepSize)³. The 2D default (stepSize=1, ±GRID_SIZE_2D) would produce thousands of meshes and tank the frame rate.
• Coarse defaults: default stepSize=2 and modest default ranges (smaller than ±GRID_SIZE_2D — pick a sensible 3D default, e.g. a small symmetric box) so the out-of-the-box grid is light.
• Node-count cap: clamp the total number of rendered vectors to a sane maximum (e.g. ~2000–4000). Above the cap, do not render the full field — either skip rendering with a dev warning or coarsen the grid — so a careless range can't freeze the scene. The exact cap is tunable; the requirement is that there is one.

Implementation notes:

• One Vector3D per grid node; origin/direction/length per the rules; hideHead from isArrow; noNormalise when scale=true.
• Keep the API parallel to VectorField2D (2D Vector Field Component #458) — same prop names/semantics plus the z range and the perf cap.

Acceptance criteria:

• Given f(x,y,z), arrows render on a regular 3D grid over the x/y/z ranges at stepSize spacing.
• scale=true: arrow length ∝ |(u,v,w)| × scaleLength; scale=false: uniform 0.4·stepSize direction arrows.
• isArrow=false draws lines without heads.
• anchor places the node at tail / center / head; default tail.
• Near-zero vectors produce no mark.
• color uniform; colorFn overrides per-arrow.
• Default grid is performant (coarse stepSize, modest ranges); exceeding the node-count cap does not render an unbounded number of meshes.
• A Storybook story demonstrates it (e.g. a 3D rotational field and a radial source), covering scale on/off, isArrow on/off, colorFn.

Out of scope:

• 2D vector field (2D Vector Field Component #458) — keep the API parallel.
• Streamlines / field-line integration.
• Explicit points[] override — grid sampling from f only.

Decisions recorded (triage): inherits #458's grilled decisions (grid-from-ranges+stepSize, scale magnitude vs fixed 0.4·stepSize, scaleLength=1, anchor default start, colorFn included, zero-skip); 3D-specific additions = zMin/zMax, coarse defaults (stepSize=2, modest ranges), and a node-count cap to guard the cubic blow-up.