@vibecook/ice 0.1.0 → 0.3.0

package/dist/types/packages/core/src/widget/mount-store.d.ts

@@ -4,19 +4,27 @@
  *
  * - `cullSystem` (derive): viewport test over equipped widgets' EFFECTIVE size
  *   (MeasuredSize where present, else Size), overscan scaled by zoom; flips
- *   Visible/Culled CHANGE-ONLY.
+ *   Visible/Culled CHANGE-ONLY. GATED (2026-07-15, the activeMembership
+ *   playbook): a real `runIf` — camera/viewport window compare as the `extra`
+ *   trigger (full pass; the window moved under everyone) ∨ a petition-7
+ *   collector on Position/Size/MeasuredSize + Active flips (delta pass —
+ *   drags/spawns/measures re-test only the journaled entities). Idle frames
+ *   skip; camera frames stay O(active) by the widgetQ Active scope.
  * - `mountSystem` (derive, after cull): maintains the mount list — every
  *   Visible widget is mounted; Culled widgets stay mounted-but-hidden
  *   (`display:none` at the host; React state preserved) within a count LRU
  *   budget (default RUNTIME_BUDGETS.keepMountedWidgets); beyond it the
  *   least-recently-visible unmount for real. Decisions are ENGINE-side; the
  *   dom host reflector and the React portal hook both consume the snapshot.
+ *   GATED the same way on Visible/Culled flips (+ destroys of tagged
+ *   widgets); LRU recency is stamped at the flip (identical eviction order —
+ *   "last tick seen visible" = the tick it stopped being visible).
  * - The store implements the `useSyncExternalStore` contract: `subscribe` /
  *   `getSnapshot` with snapshot identity changing IFF membership or a hidden
  *   flag changed. Listener notification is deferred to post-notify (the
  *   engine flush reflector) — never from inside the tick.
  */
-import { type Entity, type System, type TickSystem, type World } from "@vibecook/strata-ecs";
+import { type Entity, type TickSystem, type World } from "@vibecook/strata-ecs";
 import type { Engine } from "../engine/engine";
 import type { MeasureQueue } from "../input/measure-queue";
 export interface MountEntry {
@@ -30,7 +38,7 @@ export interface WidgetMountStore {
 }
 export interface WidgetRuntime {
     readonly store: WidgetMountStore;
-    readonly cullSystem: System;
+    readonly cullSystem: TickSystem;
     readonly mountSystem: TickSystem;
     /** Post-notify listener flush — install registers it as a reflector. */
     flush(): void;

package/dist/types/packages/core/src/widget/set-props.d.ts

@@ -0,0 +1,16 @@
+/**
+ * setWidgetProps — the paved-road widget prop UPDATE op (2026-07-13 review:
+ * spawn validated through each prop's Standard Schema, but the update path —
+ * raw `useCommit` writes — bypassed bounds/enum/json-shape checks entirely).
+ *
+ * Mirrors `widgetSpawnInits` semantics exactly: unknown prop names throw,
+ * each given value runs `spec["~standard"].validate` (an invalid value throws
+ * BEFORE anything is written), `p.json` values are validated as parsed shapes
+ * then serialized into their string cell. Writes are whole-group absolute
+ * values (the current cell merged with the validated updates — design-001
+ * §5.2 conflict-group granularity), one guardedTransaction = one undo step.
+ */
+import type { Entity, World } from "@vibecook/strata-ecs";
+import type { DurableStore } from "@vibecook/strata-ecs/durable";
+import { type GuardedTxOpts } from "../guards/guarded-tx";
+export declare function setWidgetProps(store: DurableStore, world: World, entity: Entity, props: Readonly<Record<string, unknown>>, opts?: GuardedTxOpts): void;

package/dist/types/packages/core/src/widget/spawn.d.ts

@@ -6,7 +6,7 @@
  * design-001 §5.2's conflict-group granularity). Validation runs through each
  * prop's Standard Schema before the write.
  */
-import type { Entity, World } from "@vibecook/strata-ecs";
+import type { Entity, OrderPlace, Relation, World } from "@vibecook/strata-ecs";
 import type { DurableStore } from "@vibecook/strata-ecs/durable";
 import { type ComponentInit } from "../schema/prefab";
 export interface SpawnWidgetOpts {
@@ -14,10 +14,30 @@ export interface SpawnWidgetOpts {
     readonly y: number;
     readonly w?: number;
     readonly h?: number;
+    /**
+     * Sibling placement in the spawn parent's `ChildOf` sequence (petition 8);
+     * default "last" = painted last = on top. "first" spawns UNDER everything in
+     * the frame (e.g. a comment box spawning behind its members).
+     */
+    readonly order?: OrderPlace;
+    /** Explicit `ChildOf` parent; default = the frame parent (nav frame ?? board root). */
+    readonly parent?: Entity;
     readonly props?: Readonly<Record<string, unknown>>;
     /** false ⇒ the spawn never enters the local undo stack (batch seeds). */
     readonly undoable?: boolean;
 }
+/**
+ * Hang the spawn's `ChildOf` edge (petition 8) — shared by `spawnWidget` and
+ * the doc sink's create-intent execution so frame placement can never diverge
+ * between the two spawn paths. A legacy world (no BoardRoot, no nav frame,
+ * no explicit parent) gets NO edge: the entity stays legacy-fallback-ordered.
+ */
+export declare function attachSpawnParent(tx: {
+    setRelation(e: Entity, r: Relation, target: Entity, place?: OrderPlace): void;
+}, world: World, spawned: Entity, opts?: {
+    readonly parent?: Entity;
+    readonly order?: OrderPlace;
+}): void;
 /**
  * The prefab-override list for a widget spawn (Position/Size + validated
  * whole-group prop values). Shared by `spawnWidget` and the doc sink's

package/dist/types/packages/devtools/src/attach.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @ice/devtools — strata's first-party tools, engine-flavored (rebuilt
+ * 2026-07-13, superseding the M10 hand-rolled 4-tab panel: the standing rule
+ * is observers/inspectors WRAP `@vibecook/strata-ecs/tools`, never
+ * re-implement them).
+ *
+ * `attachDevtools(engine)` = strata's observer panel + FPS profiler, plus the
+ * engine glue strata cannot know:
+ *
+ *   DESCRIBE        PrefabId → widget type; recognizers → kind + live phase;
+ *                   pointers/ports/wires/peers/chrome labeled as such.
+ *   DURABLE TAB     fed from the facade's CURRENT DocSession (docId, converged
+ *                   snapshot, attachment baseline) — the getter re-reads per
+ *                   poll, so it tracks docs.create/open/join/close live.
+ *   EPHEMERAL TAB   fed from an app-provided PresenceSession getter (the
+ *                   facade keeps presence private; collab demos pass theirs).
+ *   "reflect" LANE  the engine's post-notify reflector flush cost — the one
+ *                   frame slice strata's world hooks cannot see — reported
+ *                   into the profiler via an onPublish hook reading
+ *                   `lastFrame()` telemetry (one frame late by construction:
+ *                   publish runs before this frame's reflect).
+ *
+ * By default all three tools mount into ONE draggable dock (dock.ts —
+ * 2026-07-13, James: "make the 3 tools into one draggable panel"); pass
+ * `dock: false` for the classic scattered corners.
+ *
+ * Reads only, outside the tick (verified-unrestricted); never a reflector,
+ * never writes ECS. Nobody imports this package (depcruise-enforced leaf).
+ */
+import type { Entity, World } from "@vibecook/strata-ecs";
+import { type DescribeFn, type EntityDescription, type ObserverHandle, type ObserverOptions, type ProfilerHandle, type ProfilerOptions } from "@vibecook/strata-ecs/tools";
+import { type DockOptions } from "./dock";
+import { type GlPanelOptions, type GlPanelStats } from "./gl-panel";
+import { type CanvasEngine, type Engine, type PresenceSession } from "@ice/core";
+export interface DevtoolsOpts {
+    /** Where the dock (or, with `dock: false`, each panel) mounts (default: document.body). */
+    readonly container?: HTMLElement;
+    /**
+     * ONE draggable dock hosting all three tools (the default). `false` scatters
+     * them to their classic fixed corners; an object sets initial placement.
+     * The dock mounts lazily with the first tool that needs it.
+     */
+    readonly dock?: boolean | Pick<DockOptions, "corner" | "title" | "width">;
+    /** Observer panel: `false` to omit, or strata passthrough options. */
+    readonly observer?: boolean | Pick<ObserverOptions, "defaultTab" | "tab" | "recorderCap">;
+    /** Profiler HUD: `false` to omit, or strata passthrough options. */
+    readonly profiler?: boolean | Pick<ProfilerOptions, "budgetMs" | "windowSize" | "corner" | "expanded" | "lanes">;
+    /** GL metrics panel: `false` to omit, or placement/budget options. Mounts lazily on the first `glStats` push. */
+    readonly glPanel?: boolean | Pick<GlPanelOptions, "corner" | "budgetMs" | "expanded">;
+    /** Collab demos: the presence session whose store feeds the ephemeral tab. */
+    readonly presence?: () => PresenceSession | null | undefined;
+    /** Override entity labeling (default: the engine describe below). */
+    readonly describe?: DescribeFn;
+}
+export interface DevtoolsHandle {
+    readonly observer: ObserverHandle | null;
+    readonly profiler: ProfilerHandle | null;
+    /** Host-cost lane passthrough (paint, decode…); no-op when the profiler is off. */
+    lane(name: string, ms: number): void;
+    /**
+     * Feed one GL frame's metrics (wire `<GLViews onFrameStats>` here). The GL
+     * panel mounts on the first push — renderer counts, virtual-texture census,
+     * LOD banding, cull population. No-op when opts.glPanel === false.
+     */
+    glStats(stats: GlPanelStats): void;
+    /** Tear all panels + the telemetry hook down. Idempotent. */
+    detach(): void;
+}
+/**
+ * Engine-aware entity labeling for the observer's lists + timeline: identity
+ * off ROLE (widget type, recognizer kind + phase, pointer device), not off
+ * raw component-name composition. Falls back to strata's defaultDescribe.
+ */
+export declare function engineDescribe(world: World, e: Entity): EntityDescription;
+/** Accepts the facade (durable tab included) or a bare core engine. */
+export type DevtoolsEngine = CanvasEngine | Engine;
+export declare function attachDevtools(engine: DevtoolsEngine, opts?: DevtoolsOpts): DevtoolsHandle;

package/dist/types/packages/devtools/src/dock.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The devtools dock — ONE draggable window hosting all three tools
+ * (2026-07-13, James: "make the 3 tools into one draggable panel").
+ *
+ * strata's observer + profiler and our GL panel each mount `position: fixed`
+ * into their own corner. The dock does NOT re-implement any of them (standing
+ * rule: wrap first-party tools): it is a fixed, draggable shell with three
+ * stacked slots; each tool mounts into its slot via its own `container`
+ * option, and dock-scoped CSS de-windows them (`position: static`, full
+ * width, no border/shadow) so they read as sections of one panel. Their own
+ * behavior is untouched — the observer keeps its tabs/collapse/vertical
+ * resize (its header drag goes inert: left/top are ignored at static), the
+ * profiler + GL strips keep their click-to-expand.
+ *
+ * Slot order is fixed by the dock, not by mount order: profiler and GL are
+ * one-line summary strips, the observer is the deep-dive — strips on top.
+ * Layout (x/y/width/open) persists to localStorage, same as the observer:
+ * schema edits full-reload the page by design; the dock must stay put.
+ */
+export type DockCorner = "tl" | "tr" | "bl" | "br";
+export type DockSlotId = "profiler" | "gl" | "observer";
+export interface DockOptions {
+    /** Where the dock mounts (default: document.body). */
+    readonly container?: HTMLElement;
+    /** Initial corner when nothing is persisted yet (default "tr"). */
+    readonly corner?: DockCorner;
+    /** Header title (default "ice devtools"). */
+    readonly title?: string;
+    /** Initial width in px when nothing is persisted yet (default 420). */
+    readonly width?: number;
+}
+export interface Dock {
+    readonly el: HTMLElement;
+    /** The mount element for one tool. Empty slots are display:none via CSS. */
+    slot(id: DockSlotId): HTMLElement;
+    dispose(): void;
+}
+export declare function createDock(opts?: DockOptions): Dock;

package/dist/types/packages/devtools/src/gl-panel.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The GL metrics panel — the engine-specific renderer readout strata has no
+ * counterpart for (2026-07-13, James: "comprehensive r3f profiler ... and our
+ * engine specific optimization metrics ... with nice visuals").
+ *
+ * Pure DOM, strata's visual language (same palette/typography as the observer
+ * + profiler HUD so the three read as one toolset). Fed by pushes of
+ * `GlPanelStats` — the STRUCTURAL MIRROR of @ice/r3f's `GlFrameStats`
+ * (devtools cannot import r3f under the walls; keep the shapes aligned):
+ *
+ *   head      fps · gpu ms + a gpu sparkline against the frame budget
+ *   frame     cpu / gpu bars vs budget, with session maxima
+ *   render    draw calls · triangles · points/lines · programs · geoms · textures
+ *   virtual   live render targets + total resolution, FBO bytes vs budget,
+ *   textures  the island phase census as a segmented bar, repaint/evict counters
+ *   lod       zoom → hysteresis band → effective DPR, live targets per band
+ *   widgets   Visible vs Culled population
+ *
+ * All values land via `textContent` (never innerHTML with data). Rendering is
+ * throttled — pushes arrive per composited frame, the DOM refreshes at ~8 Hz.
+ */
+/** Mirror of @ice/r3f `GlFrameStats` (structural — see the header). */
+export interface GlPanelStats {
+    readonly cpuMs: number;
+    readonly gpuMs: number;
+    readonly fps: number;
+    readonly drawCalls: number;
+    readonly triangles: number;
+    readonly points: number;
+    readonly lines: number;
+    readonly programs: number;
+    readonly geometries: number;
+    readonly textures: number;
+    readonly renderTargets: number;
+    readonly renderMegaPixels: number;
+    readonly fboBytes: number;
+    readonly fboBudgetBytes: number;
+    readonly islands: {
+        readonly total: number;
+        readonly hot: number;
+        readonly warm: number;
+        readonly waking: number;
+        readonly cold: number;
+        readonly dormant: number;
+    };
+    readonly bandHistogram: Readonly<Record<string, number>>;
+    readonly repainted: number;
+    readonly pendingPaints: number;
+    readonly evicted: number;
+    readonly zoom: number;
+    readonly band: number;
+    readonly effectiveDpr: number;
+    readonly visibleWidgets: number;
+    readonly culledWidgets: number;
+}
+export type GlPanelCorner = "tl" | "tr" | "bl" | "br";
+export interface GlPanelOptions {
+    readonly container?: HTMLElement;
+    readonly corner?: GlPanelCorner;
+    /** Frame budget in ms — the sparkline's reference line (default 16.7). */
+    readonly budgetMs?: number;
+    /** Start with the detail body open (default false). */
+    readonly expanded?: boolean;
+}
+export interface GlPanel {
+    push(stats: GlPanelStats): void;
+    dispose(): void;
+}
+export declare function createGlPanel(opts?: GlPanelOptions): GlPanel;

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

@@ -1,8 +1,10 @@
 /**
- * @ice/devtools — the engine devtools panel (design-005 §4): pointers/recognizers,
- * planes, sovereignty badges, loop telemetry. A standalone DOM panel that reads
- * the world outside the tick — it is NOT a reflector and writes no ECS.
- * Import wall: @ice/core (+kernel) only; nobody imports us (depcruise-enforced).
+ * @ice/devtools — strata's observer panel + FPS profiler, engine-flavored
+ * (describe/durable/ephemeral/reflect-lane glue). Reads the world outside the
+ * tick; never a reflector, never writes ECS. Nobody imports us
+ * (depcruise-enforced leaf).
  */
-export declare const DEVTOOLS_VERSION = "0.0.0";
-export { attachDevtools, type DevtoolsHandle, type DevtoolsOpts } from "./panel";
+export declare const DEVTOOLS_VERSION = "0.1.0";
+export { attachDevtools, engineDescribe, type DevtoolsEngine, type DevtoolsHandle, type DevtoolsOpts, } from "./attach";
+export { createDock, type Dock, type DockCorner, type DockOptions, type DockSlotId } from "./dock";
+export { createGlPanel, type GlPanel, type GlPanelCorner, type GlPanelOptions, type GlPanelStats } from "./gl-panel";

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

@@ -9,11 +9,9 @@ export { createPlaneTransformReflector, type CameraPlanes } from "./reflectors/p
 export { createGrayboxReflector } from "./reflectors/graybox";
 export { createDomWidgetsReflector, type DomWidgetsHost, type DomWidgetsReflector, } from "./reflectors/dom-widgets";
 export { startRafLoop } from "./loop";
-export { attachPointerAdapter, type GLRoute, type PointerAdapterOpts } from "./pointer-adapter";
+export { attachPointerAdapter, type GLRoute, type GLRouteVerdict, type PointerAdapterOpts } from "./pointer-adapter";
 export { createCursorReflector } from "./reflectors/cursor";
 export { createRemoteCursorsReflector, type RemoteCursorsReflector } from "./reflectors/remote-cursors";
-export { createGridReflector, DEFAULT_GRID_CONFIG, type GridConfig } from "./reflectors/grid";
-export { createWiresReflector, DEFAULT_WIRES_CONFIG, type WirePreview, type WiresConfig, type WiresReflector, } from "./reflectors/wires";
 export { createChromeReflector } from "./reflectors/chrome";
 export { attachMeasureAdapter, type MeasureAdapter } from "./measure-adapter";
 export { wireMeasurement, type MeasureWiringHosts, type MeasureWiringOpts } from "./measure-wiring";

package/dist/types/packages/dom/src/loop.d.ts

@@ -6,6 +6,17 @@
  * timestamp straight into the frame clock (so FrameInfo.dt is real wall time,
  * clamped in core). The returned stop fn cancels the pending frame AND latches
  * so a frame already in flight cannot re-schedule — calling it is idempotent.
+ *
+ * THE FREEZE GATE (2026-08-04). Before each frame the loop claims a step from
+ * `engine.frame`. While a freeze is held the gate walks its settle and then
+ * refuses, at which point the loop PARKS: it stops scheduling rAF at all
+ * rather than spinning a callback that does nothing — "the engine is stopped"
+ * should mean the browser has no work queued for it either. Thaw arrives
+ * through the gate's change subscription, which schedules the next frame.
+ *
+ * The dt clamp is what makes resume safe: a freeze that lasted an hour hands
+ * `step` an enormous `now`, and core clamps the delta (frame-info.ts), so
+ * tweens advance by one ordinary frame instead of teleporting to their end.
  */
 import type { Engine } from "@ice/core";
 export declare function startRafLoop(engine: Engine): () => void;

package/dist/types/packages/dom/src/measure-wiring.d.ts

@@ -33,8 +33,8 @@ export interface MeasureWiringHosts {
 }
 export interface MeasureWiringOpts {
     /**
-     * Border-box read for the forced re-measure on show. Defaults to
-     * `getBoundingClientRect`; tests inject a deterministic stub.
+     * Border-box read for the forced re-measure on show. Defaults to layout
+     * `offsetWidth`/`offsetHeight`; tests inject a deterministic stub.
      */
     readonly measure?: (el: HTMLElement) => {
         w: number;

package/dist/types/packages/dom/src/pointer-adapter.d.ts

@@ -28,6 +28,15 @@
  * through L0). `stopPropagation()` inside widget content is the OTHER boundary:
  * a stopped event never reaches the container listener, so it never becomes a
  * canvas fact at all — that is the design, not a gap.
+ *
+ * Hover-time amendment (design-002 §8, 2026-07-18): down/move facts ALSO carry
+ * `overInteractive` — the same `crossesInteractive` check, run at hover time,
+ * OR'd with the GL router's hover verdict — so the world can telegraph the
+ * opt-out BEFORE a down (cursor affordances). It never gates gestures:
+ * `surfaceHandled` stays down-only and keeps its exact meaning. During a
+ * container-captured drag every event retargets to the container, so
+ * `overInteractive` reads false mid-gesture — correct: the gesture owns the
+ * pointer, not the widget under it.
  */
 import { type InputQueue } from "@ice/core";
 import type { CanvasHost } from "./host";
@@ -41,7 +50,18 @@ import type { CanvasHost } from "./host";
  * recognizers skip it via `HandledByWidget` — the same contract as the
  * native-interactive opt-out.
  */
-export type GLRoute = (kind: "down" | "move" | "up" | "cancel", screenX: number, screenY: number, native: PointerEvent) => boolean;
+export type GLRoute = (kind: "down" | "move" | "up" | "cancel", screenX: number, screenY: number, native: PointerEvent) => boolean | GLRouteVerdict;
+/**
+ * The richer GL verdict (hover-time amendment, 2026-07-18): `handled` keeps the
+ * boolean's exact meaning (island content claimed the event); `overInteractive`
+ * adds the hover fact — the pick chain holds claim-capable content (a mesh with
+ * a down/click handler), so a down HERE would be the island's. Plain `boolean`
+ * returns stay legal (≡ `{ handled }`), so existing routes never break.
+ */
+export interface GLRouteVerdict {
+    readonly handled: boolean;
+    readonly overInteractive?: boolean;
+}
 export interface PointerAdapterOpts {
     readonly glRoute?: GLRoute;
 }

package/dist/types/packages/dom/src/reflectors/dom-widgets.d.ts

@@ -24,6 +24,11 @@
  *    dedicated observer; the note below is historical:
  *    picked up on the next Position/Size stamp or membership change; the ResizeObserver
  *    measurement path — a later slice — will arm its own dirt.)
+ *  - **opacity**: a private observer on `[Opacity]` (attach/detach/value) sets a
+ *    dirty flag; the change-only pass writes `style.opacity` on the host (absent
+ *    component = 1 = property cleared). The GL twin is the composite quad's
+ *    `uOpacity` — a gl widget's host here carries only its DOM chrome, so the
+ *    two halves fade from the same cell.
  *  - **drag-promote** (P3): a private observer on `[Grab]` membership sets a dirty
  *    flag; a host whose entity holds `Grab` re-parents content→lifted plane and back
  *    on release. Re-parenting MOVES the host node (with its content child), which

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

@@ -0,0 +1,52 @@
+/**
+ * @ice/ground — the P0 ground stratum as ONE WebGPU canvas (design-004 §1
+ * as-built amendment, 2026-07-16). three's WebGPURenderer + TSL, WebGL2
+ * fallback automatic. Off the react chain: react receives the layer as an
+ * OPAQUE factory (`<InfiniteCanvas ground={ground(...)}>`); imperative apps
+ * register `layer.reflector` themselves. Passes: dot grid, wires, snap
+ * guides — future ground shaders/effects join the same pass registry.
+ * (Selection chrome moved OFF the ground 2026-07-17: rings live with the
+ * cards, the multi-select union box is P4 dom chrome — always on top.)
+ */
+import type { GridConfig, SnapGuidesConfig, WirePreviewBuffer, WiresConfig, World } from "@ice/core";
+import { type GroundLayerHost, type GroundReflector } from "./layer";
+import type { GroundPass } from "./pass";
+import { type GroundRendererLike } from "./renderer";
+export type { GroundFrame, GroundPass } from "./pass";
+export type { GroundReflector } from "./layer";
+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 "@ice/core";
+export interface GroundContext {
+    readonly host: GroundLayerHost;
+    readonly world: World;
+    /** Connect-drag preview reader (graph boards); omit on boards without wires. */
+    readonly readWirePreview?: () => WirePreviewBuffer;
+}
+export interface GroundLayer {
+    readonly reflector: GroundReflector;
+    /** Live grid re-tune (the react `grid` prop forwards here). */
+    configureGrid(cfg: Partial<GridConfig>): void;
+    dispose(): void;
+}
+export interface GroundOptions {
+    readonly grid?: Partial<GridConfig>;
+    readonly wires?: Partial<WiresConfig>;
+    readonly guides?: Partial<SnapGuidesConfig>;
+    /** 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). */
+    readonly forceWebGL?: boolean;
+    /** TEST seam: inject a fake renderer (headless orchestration tests). */
+    readonly rendererOverride?: GroundRendererLike;
+}
+export type GroundFactory = (ctx: GroundContext) => GroundLayer;
+/**
+ * Build the ground layer factory. Usage:
+ *   react apps:      <InfiniteCanvas ground={ground({ grid: {...} })} …>
+ *   imperative apps: const layer = ground()( { host, world, readWirePreview } );
+ *                    engine.registerReflector(layer.reflector);
+ */
+export declare function ground(opts?: GroundOptions): GroundFactory;

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

@@ -0,0 +1,40 @@
+/**
+ * The ground LAYER — one reflector, one canvas, one render (design-004 §1
+ * as-built 2026-07-16: P0 consolidated from three stacked canvases into a
+ * single WebGPU canvas; grid, wires and snap-guides are now PASSES of this
+ * layer, and future ground effects join the same registry).
+ *
+ * Coordinate model: the layer renders in SCREEN CSS-px space — an ortho
+ * camera maps [0..w]×[0..h] (y-down) to clip, and passes build their geometry
+ * through the kernel `worldToScreen` seam per collect (the proven 2D-canvas
+ * semantics: geometry rebuilds on the same dirt that re-stroked the old
+ * canvases; the grid stays a per-pixel screen-space shader). The Y-flip
+ * question never arises here — `worldToScreen` IS the one conversion (L13).
+ *
+ * Reflector contract (design-002 §5): post-notify, output-only, never reads
+ * layout in flush (the ResizeObserver owns sizing), never writes ECS.
+ * `always: true` with a private dirty union — an idle scene renders zero
+ * frames; ANY dirty pass re-renders the whole canvas (one draw, same cost
+ * class as a pan frame under the old grid). WebGPU init is async: flushes
+ * before ready are deferred (flags stay armed), the first ready flush paints.
+ */
+import { type ReflectorDef, type World } from "@ice/core";
+import type { GroundPass } from "./pass";
+import type { GroundRendererLike } from "./renderer";
+export interface GroundLayerHost {
+    readonly container: HTMLElement;
+    readonly contentPlane: HTMLElement;
+}
+export interface GroundReflector extends ReflectorDef {
+    /** False while init is pending or after a device/context failure. */
+    available(): boolean;
+    /** Whole-canvas renders so far (the churn instrument — 0 on an idle scene). */
+    redraws(): number;
+}
+export interface GroundLayerInternals {
+    reflector: GroundReflector;
+    /** Wake every pass + render (config changes, external invalidation). */
+    invalidateAll(): void;
+    dispose(): void;
+}
+export declare function createLayer(host: GroundLayerHost, world: World, renderer: GroundRendererLike, passes: readonly GroundPass[]): GroundLayerInternals;

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

@@ -0,0 +1,41 @@
+/**
+ * The ground-pass contract (design-004 §1, as-built 2026-07-16: P0 is ONE
+ * WebGPU canvas; passes are its draw layers).
+ *
+ * A pass owns a scene `object` (mesh/group with a TSL node material), arms its
+ * own dirty observers, and rebuilds its geometry/uniforms in `collect` — PURE
+ * world reads in the layer's SCREEN-px coordinate space (the ortho camera maps
+ * CSS px → clip; world→screen goes through the kernel `worldToScreen` seam,
+ * Law 13). Heavy per-pass math (tessellation, triangle-soup emission) lives in
+ * sibling `*-collect.ts` modules that import ONLY core/kernel, so collectors
+ * unit-test under happy-dom with no GPU and no three import.
+ */
+import type { World } from "@ice/core";
+import type { Object3D } from "three/webgpu";
+/** Per-flush frame facts every pass collects against. */
+export interface GroundFrame {
+    /** CSS-px viewport size. */
+    readonly width: number;
+    readonly height: number;
+    readonly dpr: number;
+    /** Engine camera: world top-left + zoom (grid.ts P0 contract). */
+    readonly camera: {
+        readonly x: number;
+        readonly y: number;
+        readonly zoom: number;
+    };
+}
+export interface GroundPass {
+    readonly name: string;
+    /** The pass's scene object; the layer adds it once and disposes with the pass. */
+    readonly object: Object3D;
+    /**
+     * Arm dirty observers on the world; `wake()` marks this pass for a
+     * re-collect on the next flush. Camera/resize dirt is LAYER-owned (it wakes
+     * every pass) — arm only pass-specific sources here. Returns unsubscribers.
+     */
+    arm(world: World, wake: () => void): Array<() => void>;
+    /** Rebuild geometry/uniforms from the world (read-only; screen-px space). */
+    collect(world: World, frame: GroundFrame): void;
+    dispose(): void;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ *
+ * 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 "@ice/core";
+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;

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

@@ -0,0 +1,14 @@
+/**
+ * Snap-guides collector — the pure ECS→triangles half of the guides pass
+ * (v1 SnapGuideRenderer look, carried over from the 2D-canvas reflector it
+ * replaces): full-viewport magenta alignment lines (`GuideLine.from == to` ⇒
+ * full span — design-003 §6), bounded spans, and equal-spacing bars with 4px
+ * end ticks. Screen-px output via the kernel `worldToScreen` seam. NO guide
+ * count caps (the pool grows; so does the soup).
+ */
+import { type SnapGuidesConfig, type World } from "@ice/core";
+import type { GroundFrame } from "../pass";
+import { type TriSoup } from "./soup-collect";
+export declare const guideQ: import("@vibecook/strata-ecs").Query;
+export declare const barQ: import("@vibecook/strata-ecs").Query;
+export declare function collectGuides(world: World, frame: GroundFrame, config?: SnapGuidesConfig): TriSoup;

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

@@ -0,0 +1,3 @@
+import { type SnapGuidesConfig } from "@ice/core";
+import type { GroundPass } from "../pass";
+export declare function createGuidesPass(initial?: Partial<SnapGuidesConfig>): GroundPass;

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

@@ -0,0 +1,35 @@
+/**
+ * Triangle-soup builders — the PURE half of the geometry passes (no three
+ * import; unit-tested under happy-dom). Collectors emit screen-px triangles
+ * with per-vertex rgba into a growable soup; the three-side `soup-mesh`
+ * uploads them. MSAA (renderer antialias) smooths edges, matching the old 2D
+ * canvases' stroke AA closely enough at 1–2 px widths.
+ */
+export interface TriSoup {
+    /** xyz per vertex (z = 0 — the layer renders flat in screen space). */
+    positions: Float32Array;
+    /** rgba per vertex, 0-1. */
+    colors: Float32Array;
+    vertexCount: number;
+}
+export type Rgba = readonly [number, number, number, number];
+export declare class SoupBuilder {
+    private pos;
+    private col;
+    private vert;
+    /** Axis-aligned rect (two triangles). */
+    rect(x: number, y: number, w: number, h: number, c: Rgba): void;
+    /** Stroke segment (a→b) of `width`, flat caps — a quad across the segment normal. */
+    segment(ax: number, ay: number, bx: number, by: number, width: number, c: Rgba): void;
+    /** Stroke a polyline (interleaved xy) as per-segment quads (smooth-curve joins). */
+    polyline(points: ArrayLike<number>, width: number, c: Rgba): void;
+    /** Filled disc as a triangle fan (MSAA smooths the rim; 16 segs ≈ round at ≤8 px). */
+    disc(cx: number, cy: number, r: number, c: Rgba, segments?: number): void;
+    build(): TriSoup;
+}
+/**
+ * `rgba(r, g, b, a)` / `rgb(…)` / `#rrggbb` → [r,g,b,a] 0-1 (the WiresConfig
+ * colors are CSS strings — v1/2D-canvas heritage). Unknown formats fall back
+ * to opaque mid-gray rather than throwing in a reflector path.
+ */
+export declare function parseCssColor(css: string): Rgba;

package/dist/types/packages/ground/src/passes/soup-mesh.d.ts

@@ -0,0 +1,8 @@
+import { Mesh } from "three/webgpu";
+import type { TriSoup } from "./soup-collect";
+export interface SoupMesh {
+    readonly mesh: Mesh;
+    update(soup: TriSoup): void;
+    dispose(): void;
+}
+export declare function createSoupMesh(renderOrder: number): SoupMesh;