@vibecook/ice 0.1.0

package/dist/types/packages/core/src/tools/define-tool.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `defineTool` — tools are PURE CONFIGURATION (design-005 §3): a tool
+ * introduces no new code paths, it only parameterizes L2 spawn (which
+ * recognizer kinds a pointer-down mints), L4 cursor, the L3 dragRoute
+ * policy, and capability gates. Custom behaviors register systems via the
+ * engine's extension slot — same contract as built-ins (design-003 §5.0).
+ *
+ * Built-ins ship as configs of this same primitive:
+ *  - select: tap/longPress/drag; canvas drag → marquee (pan on touch /
+ *    space / middle-button — device conventions, honored ABOVE tool policy).
+ *  - pan: hand cursor; every drag pans.
+ *  - connect: crosshair; widget/port drags connect (design-003 §5.8).
+ *  - draw(widgetType): factory — canvas drag creates ONE widget from the
+ *    drag rect at JustEnded (one tx via the create intent; min-size floor;
+ *    drag preview is recorded polish, not v1 — design-001 §3's full
+ *    draft→promote protocol remains the vNext shape).
+ *
+ * Switching tools runs `cancelActiveGestures()` first (design-003 §8) —
+ * `ops.setTool` owns that; nothing here touches the world.
+ */
+import type { SingleKindName } from "../systems/l2-recognize";
+export type CanvasDragRoute = "marquee" | "pan" | "connect" | "draw" | "none";
+export type WidgetDragRoute = "move" | "pan" | "connect" | "none";
+export interface ToolRoute {
+    /** Drag starting on empty canvas (after device overrides: touch/space/middle → pan). */
+    readonly canvasDrag?: CanvasDragRoute;
+    /** Drag starting on a widget body. */
+    readonly widgetDrag?: WidgetDragRoute;
+    /** Drag starting on a port entity ("connect" | "none"). */
+    readonly portDrag?: "connect" | "none";
+}
+export interface ToolGates {
+    /** false ⇒ widget drags never route to move while this tool is active. */
+    readonly movable?: boolean;
+    /** false ⇒ resize-handle grabs are suppressed while this tool is active. */
+    readonly resizable?: boolean;
+}
+export interface ToolDef {
+    readonly id: string;
+    /** L4 cursor while active (OS cursor string; design-003 §7). */
+    readonly cursor?: string;
+    /** Recognizer kinds minted per pointer-down (design-003 §4.1). */
+    readonly spawnProfile?: readonly SingleKindName[];
+    readonly route?: ToolRoute;
+    readonly gates?: ToolGates;
+    /** Default keymap entry (the react keymap consumes; app-overridable). */
+    readonly shortcut?: string;
+    /** draw tools: the widget type the drag rect creates. */
+    readonly draw?: {
+        readonly widgetType: string;
+    };
+}
+export interface Tool extends Required<Pick<ToolDef, "id">> {
+    readonly cursor: string | undefined;
+    readonly spawnProfile: readonly SingleKindName[];
+    readonly route: Required<ToolRoute>;
+    readonly gates: Required<ToolGates>;
+    readonly shortcut: string | undefined;
+    readonly draw: {
+        readonly widgetType: string;
+    } | undefined;
+}
+export declare function defineTool(def: ToolDef): Tool;
+export declare const tools: {
+    get(id: string): Tool | undefined;
+    all(): Tool[];
+    /** The active tool's policy, with select semantics for unknown ids. */
+    resolve(id: string): Tool;
+};
+/** TEST-ONLY wipe (mirrors __resetWidgetsForTests; not on the barrel). */
+export declare function __resetToolsForTests(): void;
+/** Idempotent — runs at module load (built-ins are the engine's canonical
+ *  vocabulary, DEFAULT_SPAWN_PROFILES precedent); safe under HMR. */
+export declare function registerBuiltinTools(): void;
+/** Factory (design-005 §3): a drag on canvas creates `widgetType` from the rect. */
+export declare function createDrawTool(widgetType: string, opts?: {
+    id?: string;
+    shortcut?: string;
+}): Tool;

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

@@ -0,0 +1,124 @@
+import type { Component, Tag } from "@vibecook/strata-ecs";
+import { type Prefab } from "../schema/prefab";
+import type { PropSpec, PropsDecl } from "./props";
+export type WidgetSurface = "dom" | "gl";
+export type SizeMode = "fixed" | "auto-height" | "auto";
+export interface WidgetPortDecl {
+    readonly id: string;
+    readonly side: "n" | "e" | "s" | "w";
+    /** Slot index along the side (0-based; anchor spacing is the kernel's). */
+    readonly index?: number;
+    /** Compatibility keys (empty = connects to anything). */
+    readonly accepts?: readonly string[];
+}
+export interface WidgetInteraction {
+    readonly selectable?: boolean;
+    readonly movable?: boolean;
+    readonly resizable?: boolean;
+    readonly snap?: "source" | "target" | "both" | "none";
+    /** Drop-REJECTING target: widgets dropped onto this one fly back (v1 iOS-card contract). */
+    readonly solid?: boolean;
+    /** "longPress": hold-to-lift dragging (iOS home-screen model); default "press". */
+    readonly dragOn?: "press" | "longPress";
+}
+export interface WidgetDef {
+    readonly type: string;
+    readonly version?: number;
+    /** Top-level props: a plain record, or the DSL's `p.object(...)` result. */
+    readonly props?: PropsDecl | {
+        readonly kind: "object";
+        readonly fields: Readonly<Record<string, unknown>>;
+    };
+    /** Conflict groups: group name → prop names. Ungrouped props → "props". */
+    readonly groups?: Readonly<Record<string, readonly string[]>>;
+    readonly surface: WidgetSurface;
+    /** Framework component (opaque to core — the react package narrows it). */
+    readonly component: unknown;
+    readonly sizeMode?: SizeMode;
+    readonly defaultSize?: {
+        readonly w: number;
+        readonly h: number;
+    };
+    readonly minSize?: {
+        readonly w: number;
+        readonly h: number;
+    };
+    /**
+     * GL only: the island repaints every frame while visible (design-004 §3
+     * animation contract — the EXPLICIT opt-in; plain `useFrame` inside a
+     * portal cannot be attributed to an island, so it never drives repaints;
+     * content-driven animation goes through `useIslandFrame`).
+     */
+    readonly animated?: boolean;
+    readonly interaction?: WidgetInteraction;
+    /**
+     * Node-editor port schema (design-005 §2; design-001 §5.3): wires bind to
+     * widget + port ID — port ENTITIES are runtime and on-demand. `accepts` is
+     * the compatibility key list the connect gesture checks.
+     */
+    readonly ports?: readonly WidgetPortDecl[];
+    readonly container?: {
+        readonly accepts: readonly string[];
+        readonly provides?: readonly string[];
+    };
+    /**
+     * Provides-keys WITHOUT container semantics (nodeboard field finding): a
+     * leaf that only offers itself to containers must not become a Container
+     * (drop target + Enter affordance). Ignored when `container` is present
+     * (its `provides` wins).
+     */
+    readonly provides?: readonly string[];
+    /**
+     * fromVersion → idempotent absolute transform (M9's `runMigrations` runs the
+     * chain at open; `prev`/return are flat prop records spanning every group).
+     *
+     * No parallel `legacy` schema field is needed for field-level changes: strata
+     * is field-tolerant within a known component name (extra stored fields dropped,
+     * missing default-filled — every generated field carries a default), so a v1
+     * cell projects into the v2 group component of the same name and the transform
+     * reads the already-v2-shaped value. See doc/migrate.ts for the as-built note;
+     * migrating data out of a group REMOVED wholesale in v2 is vNext (design-005
+     * §6.4 cross-schema movement).
+     */
+    readonly migrate?: Readonly<Record<number, (prev: Record<string, unknown>) => Record<string, unknown>>>;
+}
+export interface WidgetGroup {
+    readonly name: string;
+    readonly component: Component;
+    /** prop name → spec (field order = component field order). */
+    readonly fields: Readonly<Record<string, PropSpec>>;
+}
+export interface WidgetType {
+    readonly type: string;
+    readonly version: number;
+    readonly prefab: Prefab;
+    readonly groups: readonly WidgetGroup[];
+    readonly propToGroup: Readonly<Record<string, string>>;
+    readonly surface: WidgetSurface;
+    readonly component: unknown;
+    readonly sizeMode: SizeMode;
+    readonly defaultSize: {
+        readonly w: number;
+        readonly h: number;
+    };
+    readonly minSize: {
+        readonly w: number;
+        readonly h: number;
+    };
+    /** GL islands: repaint every visible frame (design-004 §3). */
+    readonly animated: boolean;
+    /** Node-editor ports (empty when not a node). */
+    readonly ports: readonly WidgetPortDecl[];
+    /** Runtime capability tags the equip system stamps at projection. */
+    readonly capabilityTags: readonly Tag[];
+    readonly migrate: Readonly<Record<number, (prev: Record<string, unknown>) => Record<string, unknown>>>;
+}
+/** Stamped by the equip system once a projected widget carries its capability tags. */
+export declare const WidgetEquipped: Tag;
+export declare const widgets: {
+    get(type: string): WidgetType | undefined;
+    all(): WidgetType[];
+};
+export declare function defineWidget(def: WidgetDef): WidgetType;
+/** TEST-ONLY wipe (mirrors __resetPrefabsForTests; not on the barrel). */
+export declare function __resetWidgetsForTests(): void;

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

@@ -0,0 +1,14 @@
+/**
+ * The widget equip system (design-005 §2 "capability-tag stamping recipe",
+ * design-001 reconciled catalog).
+ *
+ * Capability tags are RUNTIME state — a restored/remote document carries only
+ * durable cells, so every projected widget entity gets its type's tags stamped
+ * here, once (`WidgetEquipped` makes the query zero-match at steady state:
+ * row-filtered, nothing runs, nothing stamps). Runs in `derive`; new
+ * projections from this frame's sync() are visible by then.
+ *
+ * This generalizes the graybox demo's equipSceneBoxes into the engine.
+ */
+import { type System } from "@vibecook/strata-ecs";
+export declare function createWidgetEquipSystem(): System;

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

@@ -0,0 +1,47 @@
+/**
+ * Widget lifecycle: cull → keep-mounted LRU → the external mount store
+ * (design-004 §2).
+ *
+ * - `cullSystem` (derive): viewport test over equipped widgets' EFFECTIVE size
+ *   (MeasuredSize where present, else Size), overscan scaled by zoom; flips
+ *   Visible/Culled CHANGE-ONLY.
+ * - `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.
+ * - 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 { Engine } from "../engine/engine";
+import type { MeasureQueue } from "../input/measure-queue";
+export interface MountEntry {
+    readonly entity: Entity;
+    /** Culled-but-kept-mounted: host hides, React state survives. */
+    readonly hidden: boolean;
+}
+export interface WidgetMountStore {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): readonly MountEntry[];
+}
+export interface WidgetRuntime {
+    readonly store: WidgetMountStore;
+    readonly cullSystem: System;
+    readonly mountSystem: TickSystem;
+    /** Post-notify listener flush — install registers it as a reflector. */
+    flush(): void;
+}
+export declare function createWidgetRuntime(world: World, opts?: {
+    keepMounted?: number;
+}): WidgetRuntime;
+/** Install cull + mount + the post-notify listener flush on an engine. */
+export declare function installWidgetRuntime(engine: Engine, opts?: {
+    keepMounted?: number;
+    measureQueue?: MeasureQueue;
+}): WidgetRuntime & {
+    uninstall(): void;
+};

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

@@ -0,0 +1,98 @@
+/**
+ * The engine props DSL (design-005 §2, amending design-001 §5.2).
+ *
+ * Standard Schema is validation-only — it exposes `validate()` but no
+ * introspectable shape, so arbitrary schemas cannot compile to typed
+ * components. This DSL is the compiler's input: it (a) maps 1:1 onto strata
+ * field types plus explicit `p.json` string cells, (b) implements the
+ * Standard Schema v1 interface so it plugs into ecosystem tooling, and
+ * (c) enforces the definition-time rules — every top-level field defaulted
+ * (json derives an empty default from its root shape), enums additive-only
+ * across versions (checked by the M9 migrator against pack history; recorded
+ * here), `p.json` as the ONLY nesting escape hatch (visibly conflict-coarse:
+ * one string cell, last-writer-wins whole-value).
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => {
+            value: Output;
+        } | {
+            issues: readonly {
+                message: string;
+            }[];
+        };
+    };
+}
+export type PropSpec = StringSpec | NumberSpec | BooleanSpec | EnumSpec | JsonSpec;
+export interface StringSpec extends StandardSchemaV1<unknown, string> {
+    readonly kind: "string";
+    readonly default?: string;
+}
+export interface NumberSpec extends StandardSchemaV1<unknown, number> {
+    readonly kind: "number";
+    readonly default?: number;
+    readonly min?: number;
+    readonly max?: number;
+}
+export interface BooleanSpec extends StandardSchemaV1<unknown, boolean> {
+    readonly kind: "boolean";
+    readonly default?: boolean;
+}
+export interface EnumSpec extends StandardSchemaV1<unknown, string> {
+    readonly kind: "enum";
+    readonly options: readonly string[];
+    readonly default?: string;
+}
+/** One conflict-coarse string cell; `inner` validates the PARSED value. */
+export interface JsonSpec extends StandardSchemaV1<unknown, unknown> {
+    readonly kind: "json";
+    readonly inner: JsonShape;
+    /** Serialized default (derived from the inner root when not given). */
+    readonly default?: string;
+}
+/** Shapes legal only INSIDE p.json (validation-only, never components). */
+export type JsonShape = {
+    readonly kind: "string";
+} | {
+    readonly kind: "number";
+} | {
+    readonly kind: "boolean";
+} | {
+    readonly kind: "enum";
+    readonly options: readonly string[];
+} | {
+    readonly kind: "array";
+    readonly item: JsonShape;
+} | {
+    readonly kind: "object";
+    readonly fields: Readonly<Record<string, JsonShape>>;
+};
+export interface ObjectSpec {
+    readonly kind: "object";
+    readonly fields: Readonly<Record<string, PropSpec>>;
+}
+export declare const p: {
+    string(opts?: {
+        default?: string;
+    }): StringSpec;
+    number(opts?: {
+        default?: number;
+        min?: number;
+        max?: number;
+    }): NumberSpec;
+    boolean(opts?: {
+        default?: boolean;
+    }): BooleanSpec;
+    enum(options: readonly string[], opts?: {
+        default?: string;
+    }): EnumSpec;
+    json(inner: JsonShape, opts?: {
+        default?: unknown;
+    }): JsonSpec;
+    array(item: JsonShape): JsonShape;
+    object(fields: Readonly<Record<string, JsonShape>>): JsonShape;
+};
+/** A widget props declaration: top-level named specs (the compiler's input). */
+export type PropsDecl = Readonly<Record<string, PropSpec>>;

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

@@ -0,0 +1,30 @@
+/**
+ * spawnWidget — the paved-road widget creation op (app handler, design-005 §2).
+ *
+ * One guardedTransaction: spawnPrefab with Position (+Size) overrides and any
+ * prop overrides folded into their group components (whole-group values —
+ * 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 { DurableStore } from "@vibecook/strata-ecs/durable";
+import { type ComponentInit } from "../schema/prefab";
+export interface SpawnWidgetOpts {
+    readonly x: number;
+    readonly y: number;
+    readonly w?: number;
+    readonly h?: number;
+    readonly props?: Readonly<Record<string, unknown>>;
+    /** false ⇒ the spawn never enters the local undo stack (batch seeds). */
+    readonly undoable?: boolean;
+}
+/**
+ * The prefab-override list for a widget spawn (Position/Size + validated
+ * whole-group prop values). Shared by `spawnWidget` and the doc sink's
+ * create-intent execution (draw tool) so the two can never diverge.
+ */
+export declare function widgetSpawnInits(type: string, opts: SpawnWidgetOpts): {
+    prefab: import("../schema/prefab").Prefab;
+    overrides: ComponentInit[];
+};
+export declare function spawnWidget(store: DurableStore, world: World, type: string, opts: SpawnWidgetOpts): Entity;

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

@@ -0,0 +1,8 @@
+/**
+ * @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).
+ */
+export declare const DEVTOOLS_VERSION = "0.0.0";
+export { attachDevtools, type DevtoolsHandle, type DevtoolsOpts } from "./panel";

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

@@ -0,0 +1,48 @@
+/**
+ * The engine devtools panel (design-005 §4, M10).
+ *
+ * A standalone, dependency-free DOM panel that reads the world OUTSIDE the tick
+ * — a verified-unrestricted read (reads are never gated; only writes are) — on a
+ * fixed interval (250ms default). It is deliberately NOT a reflector: it never
+ * registers with the reflector registry, never writes ECS, and refreshes on its
+ * own timer rather than post-notify. Four engine tabs (design-005 §4):
+ *
+ *   POINTERS      live L0 pointers + L2 recognizers (kind, phase, watches, claims, routes)
+ *   PLANES        reflectors flushed last frame + key entity-class counts
+ *   SOVEREIGNTY   per-prefab store class + live count; a selected type's per-component badges
+ *   LOOP          per-system run/skip/µs from engine telemetry, sorted by cost
+ *
+ * Telemetry: attach arms `engine.enableTelemetry()` by default (idempotent). The
+ * LOOP tab and the PLANES reflector-flushed list both read `engine.lastFrame()`,
+ * which is only populated once telemetry is armed and one step has run. Pass
+ * `{ telemetry: false }` to leave it off — those two feeds then read as empty.
+ *
+ * Rendering is intentionally un-optimized: each refresh rebuilds the active tab's
+ * content from scratch (via createElement + textContent — never innerHTML, since
+ * pointer/prefab ids and component names are user/pack strings) once per 250ms.
+ * That churn is a non-issue for a dev panel and keeps the reconcile trivial.
+ *
+ * Doc-sovereignty seams: the panel never imports doc internals. `keyOf` maps an
+ * entity to its durable key (shown in the sovereignty detail header) and
+ * `cellInDoc` reports whether a given component cell is actually committed to the
+ * doc (badge "doc"); without them the badge falls back to the prefab registry's
+ * static eligible set ("doc?" vs "rt").
+ */
+import { type Component, type Engine, type Entity } from "@ice/core";
+export interface DevtoolsOpts {
+    /** Where to mount the panel (default: document.body). */
+    readonly container?: HTMLElement;
+    /** Refresh cadence in ms (default: 250). */
+    readonly intervalMs?: number;
+    /** Entity → durable key, for the sovereignty detail header (no doc import needed). */
+    readonly keyOf?: (e: Entity) => unknown;
+    /** True when component `c`'s cell on `e` is actually committed to the doc (badge "doc"). */
+    readonly cellInDoc?: (e: Entity, c: Component) => boolean;
+    /** Arm engine telemetry on attach (default: true — the LOOP/PLANES feeds need it). */
+    readonly telemetry?: boolean;
+}
+export interface DevtoolsHandle {
+    /** Remove the panel from the DOM and stop the refresh timer. */
+    detach(): void;
+}
+export declare function attachDevtools(engine: Engine, opts?: DevtoolsOpts): DevtoolsHandle;

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

@@ -0,0 +1,24 @@
+/**
+ * The DOM canvas host (design-004 §1, host pipeline — M3 slice).
+ *
+ * M3 stands up ONE content plane: an absolutely-positioned div whose single CSS
+ * transform (written by the plane-transform reflector) applies the camera to
+ * every world-positioned child at once (design-002 §5 `planeTransform`; kernel
+ * `planeCssTransform`). The full six-plane model (background/content/overlay/
+ * chrome/HUD/nav + the FBO compositor) arrives in M6 — this file is deliberately
+ * the minimum that lets a reflector paint into a camera-transformed space.
+ *
+ * The container is styled to be a stable, gesture-clean viewport: `relative` so
+ * the absolute plane anchors to it, `overflow:hidden` to clip the infinite
+ * plane, `touch-action:none` + `user-select:none` so browser scroll/zoom and
+ * text selection never fight the interaction stack.
+ */
+export interface CanvasHost {
+    /** The app-provided viewport element (styled, not created, by the host). */
+    readonly container: HTMLElement;
+    /** The single camera-transformed plane; world-positioned children mount here. */
+    readonly contentPlane: HTMLDivElement;
+    /** Remove the plane and clear the inline styles the host wrote. */
+    dispose(): void;
+}
+export declare function createCanvasHost(container: HTMLElement): CanvasHost;

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

@@ -0,0 +1,19 @@
+/**
+ * @ice/dom — DOM planes, pointer adapters (events→queue ONLY), built-in DOM reflectors.
+ * Import wall: @ice/core + @ice/kernel down only — never react/three (enforced).
+ */
+export declare const DOM_VERSION = "0.0.0";
+export { createCanvasHost, type CanvasHost } from "./host";
+export { createPlanes, type Planes } from "./planes";
+export { createPlaneTransformReflector, type CameraPlanes } from "./reflectors/plane-transform";
+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 { 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

@@ -0,0 +1,11 @@
+/**
+ * The rAF frame loop (design-002 §1: core is scheduler-free — the DOM package
+ * owns the loop; core never touches the platform).
+ *
+ * Drives `engine.step(now)` once per animation frame, threading the rAF
+ * 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.
+ */
+import type { Engine } from "@ice/core";
+export declare function startRafLoop(engine: Engine): () => void;

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

@@ -0,0 +1,31 @@
+/**
+ * The measurement adapter (design-004 §2 host pipeline; measure side).
+ *
+ * Wraps a `ResizeObserver` over auto-sized widgets' CONTENT elements and pushes
+ * `{ entity, w, h }` samples into the engine's {@link MeasureQueue} — the
+ * adapter-only path (Law 2: adapters ONLY enqueue; `measureIngest` turns samples
+ * into `MeasuredSize` facts inside the frame contract). It resolves an entity's
+ * content element on demand via the caller's `hostFor` (the widget host reflector
+ * owns the element↔entity mapping).
+ *
+ * §2 hidden-measure rule: a `display:none` host collapses to `0×0`, and a
+ * full→0 sample would pass any dead-band and corrupt bounds/cull on re-entry —
+ * so the adapter NEVER enqueues while the host is hidden (computed `display:none`
+ * / no `offsetParent`), and also drops a literal `0×0`. It is the CALLER's job to
+ * re-`observe` (or otherwise force a remeasure) on re-show — a `ResizeObserver`
+ * does not re-fire for an element that was hidden and shown at the same box size.
+ *
+ * One shared `ResizeObserver` multiplexes every observed element (fewer objects,
+ * identical semantics to one-per-element); `element → entity` maps a callback
+ * entry back to its widget.
+ */
+import type { Entity, MeasureQueue } from "@ice/core";
+export interface MeasureAdapter {
+    /** Begin observing the entity's content element (no-op if `hostFor` yields none). */
+    observe(entity: Entity): void;
+    /** Stop observing the entity's content element. */
+    unobserve(entity: Entity): void;
+    /** Disconnect the observer and drop all mappings. */
+    dispose(): void;
+}
+export declare function attachMeasureAdapter(hostFor: (e: Entity) => HTMLElement | undefined, queue: MeasureQueue): MeasureAdapter;

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

@@ -0,0 +1,49 @@
+/**
+ * Measurement wiring (design-004 §2 host pipeline; measure side, the store half).
+ *
+ * `attachMeasureAdapter` owns the `ResizeObserver` and the element→entity
+ * mapping; THIS module owns *when* to observe/unobserve, driven by the engine's
+ * widget mount store. It subscribes and reconciles each snapshot diff into four
+ * transitions (design-004 §2 / decision 4):
+ *
+ *  - **fresh mount + visible** → `observe` (the RO fires its own first sample);
+ *  - **visible → hidden** (culled-but-kept-mounted) → `unobserve` (disconnect on
+ *    hide — a `display:none` host measures `0×0` and a full→0 sample corrupts
+ *    bounds/cull on re-entry);
+ *  - **hidden → shown** → re-`observe` AND a FORCED synchronous re-measure: a
+ *    `ResizeObserver` does not re-fire for an element hidden and shown at the
+ *    same box size, so the reconnect alone would leave the rider stale;
+ *  - **unmount** (exits the snapshot) → `unobserve`.
+ *
+ * Ordering note: the mount store notifies from the widget-runtime flush
+ * reflector, which is registered BEFORE the `domWidgets` host reflector — so at
+ * notify time the host `<div>` for a just-mounted (or just-shown) widget may not
+ * exist / may still be `display:none`. Like the React portal hook (which defers
+ * via its own scheduler), this defers the reconcile to a microtask so it runs
+ * AFTER the whole synchronous reflector pass, by which point `domWidgets` has
+ * created/unhidden the host and `hostFor` + the forced re-measure see a real box.
+ *
+ * Law 2 holds: everything here only enqueues (through the adapter or the forced
+ * sample) — no world writes, no ECS reads.
+ */
+import type { Entity, MeasureQueue, WidgetMountStore } from "@ice/core";
+/** The element source (the `domWidgets` reflector supplies this via `hostFor`). */
+export interface MeasureWiringHosts {
+    hostFor(entity: Entity): HTMLElement | undefined;
+}
+export interface MeasureWiringOpts {
+    /**
+     * Border-box read for the forced re-measure on show. Defaults to
+     * `getBoundingClientRect`; tests inject a deterministic stub.
+     */
+    readonly measure?: (el: HTMLElement) => {
+        w: number;
+        h: number;
+    };
+}
+/**
+ * Begin observing auto-sized widget hosts against `store`, pushing measurements
+ * into `queue` (drained by `measureIngest`). Returns a teardown that
+ * unsubscribes and disposes the underlying `ResizeObserver`.
+ */
+export declare function wireMeasurement(store: WidgetMountStore, hosts: MeasureWiringHosts, queue: MeasureQueue, opts?: MeasureWiringOpts): () => void;

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

@@ -0,0 +1,33 @@
+/**
+ * The lifted plane (design-004 §1, planes P1/P3 — M6 slice).
+ *
+ * M3 stood up ONE camera-transformed content plane (`host.ts`, P1). M6 adds P3,
+ * the **lifted** plane: a second transform-origin-0-0 div appended to the
+ * container AFTER the content plane, so it stacks ABOVE it (P3 over P1) with no
+ * z-index bookkeeping — DOM order is the strata order (§1: "stacking is
+ * stratified"). Both planes take the SAME single camera transform (the
+ * plane-transform reflector writes both), so a promoted widget re-parented
+ * content→lifted keeps its world position; it just paints above the content
+ * layer for the duration of the drag.
+ *
+ * `createCanvasHost` is intentionally untouched: the content plane it owns is
+ * the P1 authority. `createPlanes` is additive — it borrows that content plane
+ * and mints the lifted sibling next to it.
+ */
+import type { CanvasHost } from "./host";
+/** The two DOM planes M6 addresses: P1 content (host-owned) + P3 lifted. */
+export interface Planes {
+    /** P1: the host's camera-transformed content plane; world-positioned hosts mount here. */
+    readonly content: HTMLDivElement;
+    /** P3: camera-transformed, stacked above content; promoted (dragged) hosts re-parent here. */
+    readonly lifted: HTMLDivElement;
+    /** Remove the lifted plane (the content plane is the host's — host.dispose reaps it). */
+    dispose(): void;
+}
+/**
+ * Mint the lifted plane next to the host's content plane. The lifted div is
+ * appended to the container AFTER the content plane, so it renders above it
+ * (P3 > P1). Returns both planes for the plane-transform reflector (writes both)
+ * and the dom-widgets reflector (re-parents hosts between them on drag-promote).
+ */
+export declare function createPlanes(host: CanvasHost): Planes;