@vibecook/ice 0.8.1 → 0.10.0

package/dist/types/packages/ground/src/index.d.ts

@@ -11,6 +11,8 @@
 import type { GridConfig, SnapGuidesConfig, WirePreviewBuffer, WiresConfig, World } from "../../core/src/index";
 import { type GroundLayerHost, type GroundReflector } from "./layer";
 import type { GroundPass } from "./pass";
+import type { ReadSpatial } from "./passes/magnet-collect";
+import type { PoleSource } from "./poles";
 import { type GroundRendererLike } from "./renderer";
 export type { GroundFrame, GroundPass } from "./pass";
 export type { GroundReflector } from "./layer";
@@ -18,12 +20,20 @@ export type { GroundRendererLike } from "./renderer";
 export { SoupBuilder, parseCssColor, type Rgba, type TriSoup } from "./passes/soup-collect";
 export { collectGuides } from "./passes/guides-collect";
 export { collectWires } from "./passes/wires-collect";
-export { DEFAULT_GRID_CONFIG, DEFAULT_SNAP_GUIDES_CONFIG, DEFAULT_WIRES_CONFIG, type GridConfig, type SnapGuidesConfig, type WiresConfig, } from "../../core/src/index";
+export { cursorVisualPoles, localPointerPoles, type Pole, type PoleSource } from "./poles";
+export { collectMagnetLevels, collectMagnetSources, magnetFieldScale, resolveMagnet, MAX_MAGNET_SOURCES, type MagnetLevel, type ReadSpatial, } from "./passes/magnet-collect";
+export { DEFAULT_GRID_CONFIG, DEFAULT_GRID_MAGNET_CONFIG, DEFAULT_SNAP_GUIDES_CONFIG, DEFAULT_WIRES_CONFIG, type GridConfig, type GridMagnetConfig, type SnapGuidesConfig, type WiresConfig, } from "../../core/src/index";
 export interface GroundContext {
     readonly host: GroundLayerHost;
     readonly world: World;
     /** Connect-drag preview reader (graph boards); omit on boards without wires. */
     readonly readWirePreview?: () => WirePreviewBuffer;
+    /**
+     * Broad-phase reader over the ONE spatial index (design-010 §3.2, the
+     * readWirePreview precedent) — the magnet grid's widget sources. Facades
+     * wire `stack.index.search`; omit ⇒ magnet renders a pole-only field.
+     */
+    readonly readSpatial?: ReadSpatial;
 }
 export interface GroundLayer {
     readonly reflector: GroundReflector;
@@ -35,6 +45,13 @@ export interface GroundOptions {
     readonly grid?: Partial<GridConfig>;
     readonly wires?: Partial<WiresConfig>;
     readonly guides?: Partial<SnapGuidesConfig>;
+    /**
+     * Magnet pole sources (design-010 §3.3) — live app-authored objects, so they
+     * live HERE, not in the plain-data GridConfig. Nothing wired ⇒ the magnet
+     * field (if enabled) is widget-only; with magnet off they cost one gated
+     * no-op subscription each.
+     */
+    readonly poles?: PoleSource | readonly PoleSource[];
     /** Extra app passes, rendered after the built-ins (renderOrder ≥ 3 is yours). */
     readonly passes?: readonly GroundPass[];
     /** Force the WebGL2 backend (debug / e2e A-B runs). */

package/dist/types/packages/ground/src/passes/grid-classic.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The CLASSIC dot-grid renderer — extracted VERBATIM from grid.ts when the
+ * magnet mode arrived (design-010 D1: classic stays the default and the
+ * pixel-exact baseline; the pass facade in grid.ts owns mode switching).
+ *
+ * TSL port of the raw-WebGL grid (itself verbatim from v1 GridRenderer.ts;
+ * the fragment math below is that shader re-expressed as a node graph, level
+ * loop unrolled in JS). Screen-space: a fullscreen triangle whose vertex
+ * stage passes clip coords through; the fragment reconstructs world position
+ * from `screenCoordinate` (top-left device px on BOTH backends — three
+ * normalizes, so the old manual y-flip is gone) + camera uniforms.
+ *
+ * One deliberate re-expression: the GLSL if/else fade ladder became the
+ * closed form `clamp(min(rise, fall), 0, 1)` — identical piecewise output
+ * (rise 0→1 across fadeIn, plateau 1, fall 1→0 across fadeOut) with no
+ * branching. Everything else (fract-distance dots, 0.5-device-px AA,
+ * max-composited levels) matches term for term.
+ */
+import type { GridConfig } from "../../../core/src/index";
+import { Mesh } from "three/webgpu";
+import type { GroundFrame } from "../pass";
+export interface ClassicGridRenderer {
+    readonly mesh: Mesh;
+    /** Layer-written each collect. */
+    setCamera(frame: GroundFrame): void;
+    /** Config-written (the configure seam). */
+    configure(cfg: GridConfig): void;
+    dispose(): void;
+}
+export declare function createClassicGrid(cfg: GridConfig): ClassicGridRenderer;

package/dist/types/packages/ground/src/passes/grid-magnet.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The MAGNET grid renderer — TSL port of vibe-field draft/magnet-grid's
+ * `magnet.wgsl` (design-010 §5). Three instanced-quad meshes (one per lattice
+ * level) whose vertex stage reconstructs sites from `instanceIndex`, evaluates
+ * the field (superposition of rounded-box SDF sources; poles are DEGENERATE
+ * boxes with half = 0, r = 0 — D3), and shapes the glyph (needle orients
+ * along the field; dot swells with |field|).
+ *
+ * Deltas from the WGSL, per design-010:
+ *  - ONE source buffer (storage, read-only, `setPBO` for the WebGL fallback —
+ *    D4); the mouse uniform / `mouseOn` branch are deleted.
+ *  - fade ladder, level weight and dotAlpha are CPU-baked into ONE per-level
+ *    alpha (they are per-level constants per frame — magnet-collect owns them).
+ *  - dot rest radius comes from `GridConfig.dotRadius[0]` (config continuity
+ *    with the classic grid), not the WGSL's hardcoded `halfLen·0.16`.
+ *  - coincidence skip (§5.4): sites shared with a visible coarser level drop
+ *    out (integer spacing ratios), replicating the classic max-composite look.
+ *  - NDC is computed from CSS-px directly (the WGSL path) — glyph sizes are
+ *    CSS px, DPR rides the viewport; the layer's ortho camera is bypassed.
+ */
+import type { GridConfig, GridMagnetConfig } from "../../../core/src/index";
+import { Group } from "three/webgpu";
+import type { GroundFrame } from "../pass";
+import { type MagnetLevel } from "./magnet-collect";
+export interface MagnetGridRenderer {
+    readonly group: Group;
+    /** Rewrite every uniform + the source buffer from this frame's collect. */
+    update(frame: GroundFrame, cfg: GridConfig, magnet: GridMagnetConfig, levels: readonly MagnetLevel[], sources: Float32Array, sourceCount: number): void;
+    dispose(): void;
+}
+export declare function createMagnetGrid(): MagnetGridRenderer;

package/dist/types/packages/ground/src/passes/grid.d.ts

@@ -1,21 +1,28 @@
 /**
- * The dot-grid pass — TSL port of the raw-WebGL grid (itself verbatim from v1
- * GridRenderer.ts; the fragment math below is that shader re-expressed as a
- * node graph, level loop unrolled in JS). Screen-space: a fullscreen triangle
- * whose vertex stage passes clip coords through; the fragment reconstructs
- * world position from `screenCoordinate` (top-left device px on BOTH backends
- * — three normalizes, so the old manual y-flip is gone) + camera uniforms.
+ * The grid pass — a MODE FACADE since design-010: the classic analytic dot
+ * grid (grid-classic.ts, the default — byte-identical to pre-magnet builds)
+ * and the magnet field lattice (grid-magnet.ts + magnet-collect.ts) behind
+ * ONE `GridPass` contract. `configure` deep-merges the `magnet` key one level
+ * (§3.1) so partial re-tunes never clobber the block.
  *
- * One deliberate re-expression: the GLSL if/else fade ladder became the
- * closed form `clamp(min(rise, fall), 0, 1)` — identical piecewise output
- * (rise 0→1 across fadeIn, plateau 1, fall 1→0 across fadeOut) with no
- * branching. Everything else (fract-distance dots, 0.5-device-px AA,
- * max-composited levels) matches term for term.
+ * Wake graph (all magnet wakes gated on `enabled` — the idle-scene zero-frame
+ * guarantee is untouched when off): camera/resize are layer-owned;
+ * `SpatialVersion` re-collects widget sources (gated on `widgets` too);
+ * injected pole sources wake through their own subscriptions (D5 — the pass
+ * observes no pointer/cursor/presence vocabulary). The magnet renderer is
+ * built LAZILY on first enable: classic-only apps pay zero magnet cost.
  */
 import { type GridConfig } from "../../../core/src/index";
 import type { GroundPass } from "../pass";
+import type { PoleSource } from "../poles";
+import { type ReadSpatial } from "./magnet-collect";
 export interface GridPass extends GroundPass {
     /** Live re-tune (the react `grid` prop seam) — partial merge over current values. */
     configure(cfg: Partial<GridConfig>): void;
 }
-export declare function createGridPass(initial?: Partial<GridConfig>): GridPass;
+/** Injected magnet inputs (design-010 §3.2) — absent pieces disable their sources. */
+export interface GridPassDeps {
+    readonly poles?: readonly PoleSource[];
+    readonly readSpatial?: ReadSpatial;
+}
+export declare function createGridPass(initial?: Partial<GridConfig>, deps?: GridPassDeps): GridPass;

package/dist/types/packages/ground/src/passes/magnet-collect.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Magnet-grid collector — the pure ECS→packed-sources half of the magnet pass
+ * (design-010 §4; the `*-collect.ts` convention: imports ONLY core/kernel so
+ * it unit-tests under happy-dom with no GPU and no three import).
+ *
+ * Ported from vibe-field draft/magnet-grid `main.js` (latticeWindow,
+ * packCards) with the design-010 upgrades the experiment lacked:
+ *  - rbush broad-phase over the ONE spatial index instead of an all-cards
+ *    walk (D2 — document size becomes irrelevant by construction);
+ *  - N poles from injected sources, packed as DEGENERATE rounded boxes
+ *    (half = 0, r = 0 — reduces exactly to the point-charge formula, D3);
+ *  - `maxSources` prioritization (largest screen area, then nearest to the
+ *    viewport center; poles pack first and are never evicted);
+ *  - `fadeZoom` — the field quiets below a zoom threshold (scale 0 skips the
+ *    spatial query entirely: the cheap valve is also the right look).
+ */
+import { type Entity, type GridConfig, type GridMagnetConfig, type World } from "../../../core/src/index";
+import { type AABB, type SpatialEntry } from "../../../kernel/src/index";
+import type { GroundFrame } from "../pass";
+import type { Pole } from "../poles";
+/** Floats per packed source: [cx, cy, hx, hy] + [r, strength, 0, 0] (screen px). */
+export declare const MAGNET_SOURCE_FLOATS = 8;
+/** Source-buffer capacity — the scratch array and GPU buffer are sized to this. */
+export declare const MAX_MAGNET_SOURCES = 256;
+/** Per-level instance guard (vibe-field main.js:621 — a level beyond it draws nothing). */
+export declare const MAX_MAGNET_INSTANCES = 220000;
+/** The broad-phase reader over the shared spatial index (ctx seam, design-010 §3.2). */
+export type ReadSpatial = (bounds: AABB) => readonly SpatialEntry<Entity>[];
+/** Resolve the partial config block over the defaults — the ONE resolution point. */
+export declare function resolveMagnet(cfg: GridConfig): GridMagnetConfig;
+/** Closed-form fade ladder (grid.ts:72-74 re-expressed in JS for level skip). */
+export declare function fadeOpacity(cssSpacing: number, fadeIn: readonly [number, number], fadeOut: readonly [number, number]): number;
+/**
+ * The field zoom valve: 1 at `zoom ≥ fadeZoom`, lerping to 0 across
+ * [0.7·fadeZoom, fadeZoom]. 0 disables the valve entirely.
+ */
+export declare function magnetFieldScale(zoom: number, fadeZoom: number): number;
+/** One lattice level's visible window + fade (vibe-field main.js:81-91 port). */
+export interface MagnetLevel {
+    /** Integer lattice coords of the window origin. */
+    readonly i0: number;
+    readonly j0: number;
+    readonly cols: number;
+    readonly rows: number;
+    /** Instances to draw; 0 = level skipped (faded out or over the guard). */
+    readonly count: number;
+    /** Fade-ladder opacity × level weight (CPU-baked; the shader gets one alpha). */
+    readonly alpha: number;
+    /**
+     * Coincidence skip (design-010 §5.4): when the NEXT level up is visible and
+     * its spacing is an integer multiple m of this one, sites whose absolute
+     * lattice index is ≡ 0 (mod m) on both axes drop out — replicating the
+     * classic shader's max-composite look. 0 = no skip.
+     */
+    readonly skipModulo: number;
+}
+export declare function collectMagnetLevels(frame: GroundFrame, cfg: GridConfig): MagnetLevel[];
+/**
+ * Pack field sources into `out` (stride {@link MAGNET_SOURCE_FLOATS}, screen
+ * CSS px). Returns the packed count. `fieldScale` multiplies every strength
+ * (the zoom valve); 0 short-circuits to an empty buffer — no spatial query.
+ */
+export declare function collectMagnetSources(world: World, frame: GroundFrame, magnet: GridMagnetConfig, fieldScale: number, poles: readonly Pole[], readSpatial: ReadSpatial | undefined, out: Float32Array): number;

package/dist/types/packages/ground/src/passes/wires-collect.d.ts

@@ -15,7 +15,8 @@
  * - Materialized port dots: triangle-fan discs, active color while any
  *   connect drag is routed.
  */
-import { type WirePreviewBuffer, type WiresConfig, type World } from "../../../core/src/index";
+import { type Entity, type WirePreviewBuffer, type WiresConfig, type World } from "../../../core/src/index";
+import { type Rect } from "../../../kernel/src/index";
 import type { GroundFrame } from "../pass";
 import { type TriSoup } from "./soup-collect";
 export declare const wireQ: import("@vibecook/strata-ecs").Query;
@@ -28,4 +29,7 @@ export declare const routedConnectQ: import("@vibecook/strata-ecs").Query;
 export declare const connectDragQ: import("@vibecook/strata-ecs").Query;
 /** Nav churn signal: Active membership flips re-collect (scope filter below). */
 export declare const activeQ: import("@vibecook/strata-ecs").Query;
+/** Effective widget rect: non-zero MeasuredSize over Size (design-004 §2).
+ *  Exported for the magnet collector (design-010 §4) — ONE rect-reading rule. */
+export declare function readWidgetRect(world: World, e: Entity): Rect | undefined;
 export declare function collectWires(world: World, frame: GroundFrame, config?: WiresConfig, preview?: WirePreviewBuffer): TriSoup;

package/dist/types/packages/ground/src/poles.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Magnet pole sources (design-010 §3.3, decision D5): the grid pass is
+ * CURSOR-AGNOSTIC — point field sources enter through this injected protocol,
+ * never through pass-known vocabulary. No source wired ⇒ no subscription, no
+ * reads, widget-only field. The canned helpers below are where any cursor
+ * dependency lives; the pass imports NEITHER — apps compose what fits
+ * (vibe-field wraps its own `Cur` halo the same way, in its own repo).
+ */
+import { type World } from "../../core/src/index";
+/**
+ * One point field source. Packed as a degenerate rounded-box SDF (half = 0,
+ * r = 0), which reduces exactly to the point-charge formula (design-010 D3).
+ * `space` defaults to "world"; "screen" is CSS px — zero-conversion for
+ * screen-space cursors (field evaluation is screen-space anyway).
+ */
+export interface Pole {
+    readonly x: number;
+    readonly y: number;
+    /** Relative field strength; ≤ 0 poles are skipped at pack time. */
+    readonly strength: number;
+    readonly space?: "world" | "screen";
+}
+export interface PoleSource {
+    /** Called during collect — read-only world access (GroundPass.collect rules). */
+    read(world: World): readonly Pole[];
+    /**
+     * Called during arm — `wake` marks the grid pass dirty (the pass gates it on
+     * `magnet.enabled`, so idle scenes stay at zero frames). Returns unsubscriber.
+     */
+    subscribe(world: World, wake: () => void): () => void;
+}
+/**
+ * Poles from the local pointer entity (`LocalPointer` + `PointerWorld`) — the
+ * raw-cursor wiring for apps without their own cursor visual. World-space; one
+ * pole per local pointer (multi-touch yields one per finger while pressed).
+ */
+export declare function localPointerPoles(opts?: {
+    readonly strength?: number;
+}): PoleSource;
+/**
+ * Poles from cursor-visual entities (`Position` + `CursorVisual`) — presence
+ * apps: remote collaborators' pooled cursors (core `remote-cursors.ts`) drive
+ * the field. This helper is where the CursorVisual dependency lives (D5).
+ */
+export declare function cursorVisualPoles(opts?: {
+    readonly strength?: number;
+}): PoleSource;

package/dist/types/packages/react/src/infinite-canvas.d.ts

@@ -35,7 +35,7 @@
  *    `createCanvasEngine({ measureQueue })` (ingest side) and this component's
  *    `measureQueue` prop (ResizeObserver side). Absent ⇒ measurement is skipped.
  */
-import { type CanvasEngine, type GridConfig, type MeasureQueue, type ReflectorDef, type WirePreviewBuffer, type World } from "../../core/src/index";
+import { type CanvasEngine, type Entity, type GridConfig, type MeasureQueue, type ReflectorDef, type WirePreviewBuffer, type World } from "../../core/src/index";
 import { type CanvasHost, type GLRoute, type Planes, type WidgetFocusHandle } from "../../dom/src/index";
 import { type CSSProperties, type ReactElement, type ReactNode } from "react";
 import { type KeymapEntry } from "./keymap";
@@ -72,6 +72,23 @@ export type GroundLayerFactory = (ctx: {
     };
     readonly world: World;
     readonly readWirePreview: () => WirePreviewBuffer;
+    /**
+     * Broad-phase rect query over the interaction stack's spatial index (the
+     * magnet grid's widget sources, design-010 §3.2). Structural mirror of
+     * `@ice/ground`'s ReadSpatial — kernel AABB/SpatialEntry shapes inlined.
+     */
+    readonly readSpatial: (bounds: {
+        readonly minX: number;
+        readonly minY: number;
+        readonly maxX: number;
+        readonly maxY: number;
+    }) => ReadonlyArray<{
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+        id: Entity;
+    }>;
 }) => GroundLayerHandle;
 export interface InfiniteCanvasProps {
     /** A constructed engine (`createCanvasEngine(...)`); NOT disposed on unmount. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecook/ice",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "ICE — infinite canvas engine. Figma-grade infinite-canvas UX as a framework: defineWidget turns React/R3F components into canvas citizens — selectable, movable, resizable, wired into node graphs, CRDT-synced, undoable per gesture.",
   "license": "MIT",
   "author": "James Yong <me@jamesyong42.com>",