@vibecook/ice 0.9.0 → 0.11.0

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]` (shared config
+ *    continuity), 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,10 @@
 /**
- * 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.
+ * Production grid wiring — BUILD-TIME selection, not a runtime mode facade.
  *
- * 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.
+ * Keep this module intentionally tiny and import exactly one implementation.
+ * The unselected renderer then has no path from the package entry graph and
+ * is absent from the production bundle. To restore the classic grid, change
+ * only the implementation path below to `./grid-classic-pass`.
  */
-import { type GridConfig } from "../../../core/src/index";
-import type { GroundPass } from "../pass";
-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;
+export { createGridPass } from "./grid-magnet-pass";
+export type { GridPass, GridPassDeps, GridPassFactory } from "./grid-contract";

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 wired magnet grid dirty. The classic
+     * implementation never subscribes. Returns an 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.9.0",
+  "version": "0.11.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>",