@vibecook/ice 0.1.0

package/dist/types/packages/core/src/engine/engine.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The engine facade — owner of the outer frame (design-002 §1):
+ *
+ *   step(now):
+ *     setFrameInfo        FrameInfo resource — value write, pre-tick
+ *     world.sync()        durable + presence drains land; projections place
+ *     world.tick(...)     the phase-group pipeline (pipeline.ts)
+ *     publish hooks       POST-TICK, PRE-NOTIFY: presence I/O home — eph
+ *                         structural ops are illegal for the whole tick, this
+ *                         step is theirs; `world.*` is legal here (outside the
+ *                         tick). Hooks throw LOUDLY (unlike reflectors) — a
+ *                         broken publish pre-notify must not be silently
+ *                         half-applied.
+ *     notify()            THE settled point — observers fire once per frame
+ *     reflect             reflector registry flush (post-notify, output-only)
+ *
+ * The engine is scheduler-free: `step(now)` is the whole surface, and the DOM
+ * package owns the rAF loop (core never touches the platform). Telemetry is
+ * opt-in — `world.observe` costs a `performance.now()` pair per system when
+ * armed, so benches leave it off.
+ */
+import type { World } from "@vibecook/strata-ecs";
+import type { AnySystem } from "./pipeline";
+import { type PhaseGroup } from "./pipeline";
+import { type ReflectorDef } from "./reflectors";
+export type PublishHook = (world: World) => void;
+export interface SystemRunRecord {
+    readonly phase: string;
+    readonly system: string;
+    readonly ran: boolean;
+    readonly micros: number;
+}
+/** One frame's run/skip + timing readout (design-002 §4: F1's honest telemetry). */
+export interface FrameTelemetry {
+    readonly tick: number;
+    readonly totalMicros: number;
+    readonly systems: readonly SystemRunRecord[];
+    readonly phaseFlushMicros: ReadonlyMap<string, number>;
+    readonly reflectorsFlushed: readonly string[];
+}
+export interface EngineOpts {
+    /** Reflector fault sink (default: console.error, skip this frame). */
+    readonly onReflectorFault?: (name: string, err: unknown) => void;
+}
+export interface Engine {
+    readonly world: World;
+    /** Register systems into a canonical phase group. Returns a remover. */
+    addSystems(group: PhaseGroup, ...systems: readonly AnySystem[]): () => void;
+    /** Register a post-notify output reflector (design-002 §5). Returns an unregister. */
+    registerReflector(def: ReflectorDef): () => void;
+    /** All registered reflector names (devtools; telemetry-independent). */
+    reflectorNames(): readonly string[];
+    /** Register a publish-step hook (post-tick, pre-notify presence I/O). Returns a remover. */
+    onPublish(hook: PublishHook): () => void;
+    /** Run one full frame. `now` in ms (rAF timestamp or a test counter). */
+    step(now: number): void;
+    /** Arm per-system run/skip + µs collection (idempotent; costs timer calls per system). */
+    enableTelemetry(): void;
+    /** The most recent completed frame's readout (undefined until telemetry armed + one step). */
+    lastFrame(): FrameTelemetry | undefined;
+}
+export declare function createEngine(world: World, opts?: EngineOpts): Engine;

package/dist/types/packages/core/src/engine/frame-info.d.ts

@@ -0,0 +1,16 @@
+import type { World } from "@vibecook/strata-ecs";
+/** { tick, dt ≤ dtClampMs (ms), now (ms timeline of the caller's clock) }. */
+export declare const FrameInfo: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly tick: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+    readonly dt: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly now: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+}>, {
+    readonly tick: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+    readonly dt: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly now: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+}>;
+/**
+ * Advance the frame clock. First frame gets dt 0 (no previous `now` to diff
+ * against); negative deltas (clock adjustment) clamp to 0.
+ */
+export declare function setFrameInfo(world: World, now: number): void;

package/dist/types/packages/core/src/engine/instantiate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Prefab instantiation — THE spawn routing (design-001 §2: the class is the
+ * spawn path). Durable → tx · runtime → world/ctx · ephemeral → eph.
+ * Every spawn stamps `PrefabId` (uniform identity for guards + devtools;
+ * for durable prefabs it is the document identity stamp, §2 rule 5).
+ */
+import type { Entity, SystemCtx, Tag, World } from "@vibecook/strata-ecs";
+import type { Mutator } from "@vibecook/strata-ecs/durable";
+import { type ComponentInit, type Prefab } from "../schema/prefab";
+/** Structural shape of the ephemeral store's write surface (components+tags only). */
+export interface EphSpawner {
+    spawn(init?: {
+        components?: readonly ComponentInit[];
+    }): Entity;
+    addTag(e: Entity, t: Tag): void;
+}
+export type SpawnTarget = {
+    into: "world";
+    world: World;
+} | {
+    into: "ctx";
+    ctx: SystemCtx;
+} | {
+    into: "tx";
+    tx: Mutator;
+} | {
+    into: "eph";
+    eph: EphSpawner;
+};
+export interface InstantiateOpts {
+    /**
+     * DRAFT spawn (design-001 §3, two-phase promote): a durable prefab spawned
+     * into the runtime store — its cells are plain session data (not in the doc,
+     * live writes free) until `promote` commits a durable twin. Explicit opt-in:
+     * without it, durable→world/ctx throws (never a silent downgrade, §6.3).
+     */
+    draft?: boolean;
+    overrides?: readonly ComponentInit[];
+}
+/**
+ * Spawn a prefab into the correct store. Wrong-store spawns fail loudly —
+ * notably: a durable prefab without an attached doc/tx has NO fallback
+ * (design-001 §6.3: never a silent world.spawn downgrade).
+ */
+export declare function instantiate(prefab: Prefab, target: SpawnTarget, opts?: InstantiateOpts | readonly ComponentInit[]): Entity;

package/dist/types/packages/core/src/engine/pipeline.d.ts

@@ -0,0 +1,17 @@
+import type { Pipeline, System, TickSystem } from "@vibecook/strata-ecs";
+/** Either system form (strata 0.5.0): chunk-bodied or once-per-dispatch tick. */
+export type AnySystem = System | TickSystem;
+/** The eleven strata phases, in run order (design-002 §2 table). */
+export declare const PHASE_GROUPS: readonly ["input", "react", "ctl:spawn", "ctl:recognize", "ctl:arbitrate", "ctl:claim", "ctl:behave", "simulate", "derive", "present", "cleanup"];
+export type PhaseGroup = (typeof PHASE_GROUPS)[number];
+export interface PipelineRegistry {
+    /** Append systems to a group (run order = registration order). Returns a remover (HMR). */
+    add(group: PhaseGroup, ...systems: readonly AnySystem[]): () => void;
+    /**
+     * The pipeline value for this frame (design-002 §1: "pipeline is a value,
+     * rebuilt per frame"). Cached until the registry changes; empty groups are
+     * omitted (an empty phase would flush nothing anyway).
+     */
+    assemble(): Pipeline;
+}
+export declare function createPipelineRegistry(): PipelineRegistry;

package/dist/types/packages/core/src/engine/reflectors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The reflector registry (design-002 §5).
+ *
+ * Reflectors are the ONLY writers of DOM/GL/R3F, run AFTER `notify()`, and
+ * never write ECS (L10). The registry arms strata observers ONCE per reflector
+ * at registration; observer fires during `notify()` coalesce into a per-
+ * reflector dirty flag; `flushAll()` (called by `engine.step()` post-notify)
+ * flushes dirty (or `always`) reflectors in registration order.
+ *
+ * - **First paint**: every reflector registers dirty, so its first `flushAll`
+ *   paints unconditionally — `observeResource` has no `immediate` option and a
+ *   world populated before registration never stamps for it (same seed
+ *   `observeQuery`'s `immediate` would give, applied uniformly).
+ * - **Fault isolation**: a throwing reflector is skipped this frame (its dirty
+ *   flag clears — a faulty reflector must not re-fire hot on a static scene);
+ *   system throws, by contrast, propagate loudly out of `world.tick()`.
+ * - **Write ban**: strata's emit-flag rejects ECS writes inside observer
+ *   callbacks, but reflector `flush` runs after the emit window — DEV
+ *   enforcement of the reflect write-ban is deferred (design-002 §8);
+ *   the contract still binds.
+ * - Arming any observer permanently arms reactivity stamping (+17–28% on
+ *   write-heavy paths — design-002 §4, budgeted).
+ */
+import type { Component, Query, Resource, World } from "@vibecook/strata-ecs";
+export interface ReflectorQuerySpec {
+    readonly q: Query;
+    /** Narrow the Tier-1 wake set to these value columns (plus membership). */
+    readonly cols?: readonly Component[];
+}
+export interface ReflectorObserve {
+    readonly queries?: readonly ReflectorQuerySpec[];
+    readonly resources?: readonly Resource<any>[];
+}
+export interface ReflectorDef {
+    /** Display name (telemetry, fault reports). */
+    readonly name: string;
+    readonly observe?: ReflectorObserve;
+    /** Flush every frame regardless of dirt (cheap-overlay style, v1 lesson). */
+    readonly always?: boolean;
+    /** Batched output writes; NEVER write ECS, never read layout (L10). */
+    readonly flush: (world: World) => void;
+}
+export interface ReflectorRegistry {
+    /** Arm observers and enroll; returns an unregister (unsubscribes, removes). */
+    register(def: ReflectorDef): () => void;
+    /** Post-notify: flush dirty/`always` reflectors in registration order. */
+    flushAll(): void;
+    /** Names flushed on the most recent `flushAll` (telemetry). */
+    lastFlushed(): readonly string[];
+    /** Every registered reflector, registration order (devtools enumeration —
+     *  independent of telemetry; a reflector idle since boot still lists). */
+    names(): readonly string[];
+}
+export declare function createReflectorRegistry(world: World, opts?: {
+    onFault?: (name: string, err: unknown) => void;
+}): ReflectorRegistry;

package/dist/types/packages/core/src/facade/create-canvas-engine.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `createCanvasEngine` — THE published construction path (design-005 §4).
+ *
+ * Construction wires: world + engine + the FULL interaction stack + the
+ * widget runtime + nested canvas + settings resources, doc-less. A document
+ * attaches later through `engine.docs.*` (doc-attached remains the default
+ * POSTURE: `docs.create()` is the first call of every editor app) — the
+ * commit seam is a FORWARDING sink whose target swaps per session, so the
+ * stack never rebuilds across doc open/close.
+ *
+ * `ops.*` is the catalog of engine-owned write paths (design-005 §4 table):
+ * app handlers call ops between frames (design-002 §3); each op is one
+ * transaction / one resource write / one tag sweep. Nothing here adds a
+ * write path that didn't already exist — ops BIND existing primitives to
+ * the current session.
+ *
+ * Budgets: `keepMounted` feeds the widget runtime; `fboBytes` is carried
+ * for the GL layer (GLViews reads it via the react facade). Port budgets
+ * remain reviewed constants (RUNTIME_BUDGETS) in v1 — recorded.
+ */
+import type { Entity, World } from "@vibecook/strata-ecs";
+import { type Engine } from "../engine/engine";
+import { type InteractionStack } from "../interaction/install";
+import { type NestedCanvas } from "../nav/nested-canvas";
+import { type WidgetRuntime } from "../widget/mount-store";
+import { type SpawnWidgetOpts } from "../widget/spawn";
+import { type Tool } from "../tools/define-tool";
+import { type DocSession, type DocSessionOpts, type OpenDocResult } from "../doc/doc-kit";
+import { type JoinDocOpts, type JoinResult } from "../doc/bootstrap";
+import type { ByteChannel } from "../doc/channels";
+import { type Autosave, type AutosaveOpts, type AutosaveStorageWrite } from "../doc/autosave";
+import type { MeasureQueue } from "../input/measure-queue";
+import { GESTURE_DEFAULTS, POINTER_DEFAULTS } from "../settings/defaults";
+export interface CanvasEngineOpts {
+    /** Registered widget types (definition happens at defineWidget; this list is validated). */
+    readonly widgets?: readonly {
+        readonly type: string;
+    }[];
+    /** Registered tools (definition happens at defineTool; validated). */
+    readonly tools?: readonly Tool[];
+    readonly budgets?: {
+        readonly keepMounted?: number;
+        readonly fboBytes?: number;
+    };
+    readonly settings?: {
+        readonly zoom?: {
+            readonly min?: number;
+            readonly max?: number;
+        };
+        readonly gestures?: Partial<Record<keyof typeof GESTURE_DEFAULTS, number>>;
+        readonly pointers?: Partial<Record<keyof typeof POINTER_DEFAULTS, number>>;
+        readonly snap?: {
+            readonly enabled?: boolean;
+            readonly thresholdPx?: number;
+        };
+    };
+    readonly policy?: {
+        /** The gate verdict a "migrate"-classified doc downgrades to when migration is off/fails. */
+        readonly versionGate?: "reject" | "readOnly" | "migrate";
+    };
+    /** The dom measure adapter's queue (wireMeasurement provides; optional headless). */
+    readonly measureQueue?: MeasureQueue;
+}
+export interface CanvasOps {
+    /** cancel active gestures → switch (design-003 §8; the strata-example lesson). */
+    setTool(id: string): void;
+    spawnWidget(type: string, opts: SpawnWidgetOpts): Entity;
+    deleteSelection(): void;
+    /** Twin spawns offset +16/+16; the clones become the selection. */
+    duplicateSelection(): Entity[];
+    setSelection(ids: readonly Entity[], mode?: "replace" | "add" | "toggle"): void;
+    clearSelection(): void;
+    selectAll(): void;
+    /** StackZ sweep, one tx: selection (or ids) to top/bottom. */
+    reorder(ids: readonly Entity[], mode: "top" | "bottom"): void;
+    zoomToFit(ids?: readonly Entity[]): void;
+    zoomTo(zoom: number, anchor?: {
+        x: number;
+        y: number;
+    }): void;
+    panTo(x: number, y: number): void;
+    enterContainer(container: Entity): void;
+    exitContainer(): void;
+    cancelActiveGestures(): void;
+}
+export interface CanvasDocs {
+    create(opts?: DocSessionOpts): DocSession;
+    open(bytes: Uint8Array, opts?: DocSessionOpts): OpenDocResult;
+    /** §6.5 bootstrap + optional presence sugar over the same channel. */
+    join(channel: ByteChannel, opts?: Omit<JoinDocOpts, "presence"> & {
+        readonly presence?: {
+            name: string;
+            color: string;
+        };
+    }): Promise<JoinResult>;
+    current(): DocSession | undefined;
+    close(): void;
+    undo(): boolean;
+    redo(): boolean;
+    autosave(storage: AutosaveStorageWrite, opts?: Omit<AutosaveOpts, "storage" | "world">): Autosave;
+}
+export interface CanvasEngine {
+    readonly world: World;
+    readonly engine: Engine;
+    readonly stack: InteractionStack;
+    readonly runtime: WidgetRuntime & {
+        uninstall(): void;
+    };
+    readonly nav: NestedCanvas;
+    readonly ops: CanvasOps;
+    readonly docs: CanvasDocs;
+    readonly budgets: {
+        readonly keepMounted: number;
+        readonly fboBytes: number;
+    };
+    /** step(now) passthrough — the app's rAF loop drives this. */
+    step(now: number): void;
+    dispose(): void;
+}
+export declare function createCanvasEngine(opts?: CanvasEngineOpts): CanvasEngine;

package/dist/types/packages/core/src/guards/dev.d.ts

@@ -0,0 +1,2 @@
+export declare function setDevGuards(on: boolean): void;
+export declare function devGuardsEnabled(): boolean;

package/dist/types/packages/core/src/guards/guarded-tx.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Eligibility-guarded transactions (design-001 §2 rule 3): `tx.*` structural
+ * writes are validated against the target entity's prefab — a component
+ * outside the eligible set, a relation outside the eligible relations, or a
+ * runtime-declared resource in a tx is a DEV error.
+ *
+ * Prefab resolution: entities spawned in THIS tx via `spawnPrefab` are known
+ * from a tx-local map; pre-existing durable entities resolve via their
+ * projected `PrefabId`. Entities from raw `tx.spawn` are unknown → checks
+ * skip (the guard is best-effort by design; `spawnPrefab` is the paved road).
+ * Tags are not eligibility-checked in M2 (essential tags spawn with the
+ * prefab; optional-tag modeling is future work — documented).
+ */
+import type { Component, Entity, Relation, Resource, Tag, World } from "@vibecook/strata-ecs";
+import type { Mutator } from "@vibecook/strata-ecs/durable";
+import { type ComponentInit, type Prefab } from "../schema/prefab";
+export interface GuardedTx {
+    spawnPrefab(prefab: Prefab, overrides?: readonly ComponentInit[]): Entity;
+    /** Raw spawn — entity is unknown to the guard (prefer spawnPrefab). */
+    spawn: Mutator["spawn"];
+    destroy(e: Entity): void;
+    addComponent<S>(e: Entity, c: Component<S>, v: S): void;
+    removeComponent(e: Entity, c: Component): void;
+    edit(e: Entity): {
+        set<S>(c: Component<S>, v: S): GuardedEditor;
+    };
+    addTag(e: Entity, t: Tag): void;
+    removeTag(e: Entity, t: Tag): void;
+    setRelation(e: Entity, r: Relation, target: Entity): void;
+    addRelation(e: Entity, r: Relation, target: Entity): void;
+    removeRelation(e: Entity, r: Relation, target?: Entity): void;
+    setResource<S>(res: Resource<S>, v: S): void;
+}
+interface GuardedEditor {
+    set<S>(c: Component<S>, v: S): GuardedEditor;
+}
+interface TxDoc {
+    transaction(fn: (tx: Mutator) => void, opts?: {
+        undoable?: boolean;
+    }): void;
+}
+export interface GuardedTxOpts {
+    /**
+     * strata 0.3.0 passthrough: `false` excludes this commit from the LOCAL
+     * undo stack (batch seeds, janitorial writes — retires the cardboard
+     * first-⌘Z-removes-a-seed quirk). Default true: one tx = one undo step.
+     */
+    readonly undoable?: boolean;
+}
+export declare function guardedTransaction(doc: TxDoc, world: World, run: (tx: GuardedTx) => void, opts?: GuardedTxOpts): void;
+export {};

package/dist/types/packages/core/src/guards/live-writer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The per-cell gesture guard (design-001 §2 rule 4 + §3), as the engine's
+ * live-write path. strata worlds can't intercept writes, so behaviors write
+ * doc-SENSITIVE values through this facade:
+ *
+ *   a world value-write to a cell that exists in the doc for that entity is
+ *   legal iff the entity is currently allowed to diverge — an Active
+ *   recognizer Captures/Drags it, or it carries a live TransformTween
+ *   (fly-back holds the claim; design-003 review M3).
+ *
+ * "Cell in doc" is approximated conservatively from public API: entity is
+ * doc-bound (keyOf defined) AND the component is durable-eligible for its
+ * prefab. Eligible-but-uncommitted optionals are guarded too (documented).
+ * The divergence predicate is injected — M4 wires claims + tween; tests stub.
+ */
+import type { Component, Entity, World } from "@vibecook/strata-ecs";
+export interface LiveWriterOpts {
+    /** `doc.keyOf` when a doc is attached; absent doc = nothing is doc-bound. */
+    keyOf: (e: Entity) => unknown;
+    /** May this entity's doc cells diverge right now? (claims ∪ tween) */
+    mayDiverge: (e: Entity) => boolean;
+    /**
+     * Exact "is this cell in the doc?" (e.g. wired to `doc.getComponent`).
+     * When absent, the guard falls back to the eligibility approximation —
+     * stricter than design-001 §2 rule 4's letter: an eligible-but-uncommitted
+     * optional is guarded too (fails safe; matrix finding #2).
+     */
+    cellInDoc?: (e: Entity, c: Component) => boolean;
+}
+export interface LiveWriter {
+    set<S>(e: Entity, component: Component<S>, value: S): void;
+}
+export declare function createLiveWriter(world: World, opts: LiveWriterOpts): LiveWriter;

package/dist/types/packages/core/src/guards/resource-writer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The paved-road runtime-resource write (design-001 §2 rule 7) — the mirror
+ * image of guarded-tx's `tx.setResource` check. A resource declares its write
+ * path once at `defineResource` (`durable` vs `runtime`), and the two ends
+ * enforce it symmetrically: `tx.setResource` rejects a RUNTIME resource inside
+ * a transaction; `writeRuntimeResource` rejects a DURABLE resource on the
+ * runtime world. Systems have no `ctx` resource API, so they write runtime
+ * resources through the closed-over `world.setResource` (design-002 §3) — this
+ * facade is that write, made DEV-checked.
+ *
+ * Unknown resources — anything not defined through `../schema/meta`'s
+ * `defineResource` wrapper — carry no schemaMeta, so the check finds nothing
+ * and the write passes untouched. The guard is best-effort by design, exactly
+ * like guarded-tx's prefab-eligibility checks.
+ */
+import type { Resource, World } from "@vibecook/strata-ecs";
+export declare function writeRuntimeResource<S>(world: World, res: Resource<S>, v: S): void;

package/dist/types/packages/core/src/helpers/phase-set.d.ts

@@ -0,0 +1,70 @@
+/**
+ * PhaseSet — an exclusive tag-encoded state machine with one-tick transition markers
+ * (design-003 §4.2, design-002 §2/§3).
+ *
+ * A phase set is a small, fixed list of mutually-exclusive phases (e.g. a recognizer's
+ * `Possible → Active → Ended`). For each phase it mints two tags via the schema wrapper,
+ * named by PLAIN CONCATENATION so the doc vocabulary holds (design-001 §5.5: the catalog's
+ * gesture set is definePhaseSet("Gesture", ["Possible", …]) → "GesturePossible"):
+ *   - a persistent phase tag   `${name}${phase}`     — "the entity is in this phase"
+ *   - a one-tick `Just` marker `${name}Just${phase}` — "the entity ENTERED this phase this frame"
+ *
+ * Why two tags: terminal phases persist through the reap window (design-003 §4.1), so a
+ * behavior that acted on the persistent tag would fire on every frame the tag lingers.
+ * Behaviors therefore **edge-trigger on the `Just*` markers only** — discrete actions and
+ * terminal handling fire exactly once (design-003 §4.2: shift-tap toggles once, commits
+ * never double). The persistent tag is for per-frame work that legitimately repeats.
+ *
+ * Transition timing: `set` mutates through the caller's structural writer. When that writer
+ * is a {@link SystemCtx} the add/remove are DEFERRED to the current strata-phase flush
+ * (design-002 §3); consumers in a LATER sub-phase see the new phase the same frame, and
+ * that ordering is guaranteed by the sub-phase pipeline layout (design-002 §2), never by
+ * immediate application. When the writer is the `World` (app handlers / setup) the writes
+ * are immediate. The one-tick markers are cleared by the cleanup phase via
+ * {@link PhaseSet.clearMarkers} over {@link PhaseSet.allMarkerTags}.
+ */
+import type { Entity, Tag } from "@vibecook/strata-ecs";
+/**
+ * The minimal structural-write surface `set`/`clearMarkers` need. Both `SystemCtx` (deferred
+ * to the phase flush) and `World` (immediate) satisfy it structurally — the transition is
+ * agnostic to which, and the timing follows from the writer (see the module doc).
+ */
+export interface StructuralTagWriter {
+    addTag(e: Entity, t: Tag): void;
+    removeTag(e: Entity, t: Tag): void;
+}
+/** The minimal read surface `current` needs — again satisfied by both `SystemCtx` and `World`. */
+export interface TagReader {
+    hasTag(e: Entity, t: Tag): boolean;
+}
+/** The handle returned by {@link definePhaseSet}. `P` is the literal union of phase names. */
+export interface PhaseSet<P extends string> {
+    /** The set name — the prefix of every minted tag. */
+    readonly name: string;
+    /** The phases in declaration order (the scan order of {@link PhaseSet.current}). */
+    readonly phases: readonly P[];
+    /** Persistent phase tags, keyed by phase name. */
+    readonly tags: Readonly<Record<P, Tag>>;
+    /** One-tick `Just<Phase>` marker tags, keyed by phase name. */
+    readonly justTags: Readonly<Record<P, Tag>>;
+    /** Every marker tag — the cleanup phase clears these once the frame's edges are consumed. */
+    readonly allMarkerTags: readonly Tag[];
+    /**
+     * Transition `e` into `next`: drop the current phase tag + its now-stale marker and add
+     * `next` + its fresh `Just` marker (exclusivity is enforced by clearing every phase tag,
+     * so a mis-set entity converges). Unknown `next` throws. A transition to the phase the
+     * entity is already in is a no-op with a DEV warn (detected only when `m` can also read —
+     * `SystemCtx`/`World` both can).
+     */
+    set(m: StructuralTagWriter, e: Entity, next: P): void;
+    /** The entity's current phase, or `undefined` if it holds none. Small-N `hasTag` scan. */
+    current(world: TagReader, e: Entity): P | undefined;
+    /** Clear every one-tick marker off `e` (the cleanup-phase step). */
+    clearMarkers(m: StructuralTagWriter, e: Entity): void;
+}
+/**
+ * Define an exclusive PhaseSet: one persistent tag + one one-tick `Just` marker per phase.
+ * Handles are process-global schema constants (hold them as module constants). See the module
+ * doc for transition timing and the edge-trigger contract.
+ */
+export declare function definePhaseSet<const P extends string>(name: string, phases: readonly P[]): PhaseSet<P>;

package/dist/types/packages/core/src/helpers/version-stamps.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Version-stamp resources + the runIf guard built on them (design-002 §4).
+ *
+ * These are the same-tick laziness lever: a writing system bumps a version as a plain value
+ * write (v1's callback back-channels become world state — Laws 1/4), and a downstream system
+ * gates on {@link makeVersionGuard} in its `runIf`. The guard rule (design-002 §4): guards
+ * live in `runIf`, never the body — a `runIf`-skipped system runs no body and so blanket-stamps
+ * NONE of its declared writes (strata over-fires stampWrites for any system that RUNS, even one
+ * that early-outs). Bump/guard therefore form the "writer stamps → reader skips wholesale" pair.
+ *
+ * Resources are runtime (not durable): they are derived engine state, never persisted.
+ */
+import type { Resource, World } from "@vibecook/strata-ecs";
+/** The shared shape of every version stamp — a wrap-around unsigned tick counter. */
+export interface VersionValue {
+    v: number;
+}
+/** A resource carrying a {@link VersionValue}. */
+export type VersionResource = Resource<VersionValue>;
+/** Bumped by `pointerIngest` when the input queue drained anything (design-003 §2). */
+export declare const PointerVersion: Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly v: "u32";
+}>, {
+    readonly v: "u32";
+}>;
+/** Bumped by `setSelection`/selection edits (design-003 §5). */
+export declare const SelectionVersion: Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly v: "u32";
+}>, {
+    readonly v: "u32";
+}>;
+/** Bumped when the spatial index changes (inserts/moves/removes). */
+export declare const SpatialVersion: Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly v: "u32";
+}>, {
+    readonly v: "u32";
+}>;
+/**
+ * Increment a version stamp as a value write. Unset counts as 0, so the first bump lands 1.
+ * Wraps at 2^32 via `>>> 0` — a wrapped counter still compares unequal frame-to-frame, which
+ * is all the guard needs. Systems write resources through the closed-over `world.setResource`
+ * (there is no `ctx` resource API — design-002 §3).
+ */
+export declare function bumpVersion(world: World, res: VersionResource): void;
+/**
+ * A `runIf`-compatible guard. Returns `true` iff any watched version differs from the value it
+ * last observed, and records the new values each call. The first invocation always returns
+ * `true` (it establishes the baseline — the gated system runs once at startup). A skipped system
+ * stamps nothing, so pairing this guard with narrow `access.write` is the whole laziness win.
+ *
+ * Typed `() => boolean` so callers (and tests) can invoke it directly; it is width-assignable to
+ * strata's `Condition` (`(ctx) => boolean`), so it drops straight into `runIf`.
+ */
+export type VersionGuard = () => boolean;
+export declare function makeVersionGuard(world: World, resources: readonly VersionResource[]): VersionGuard;

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

@@ -0,0 +1,63 @@
+/**
+ * @ice/core — schema+prefabs+sovereignty · phase groups/pipeline · L0–L4 systems ·
+ * scene systems · doc kit · publish step · engine facade · reflector registry.
+ * Import wall: strata-ecs + @ice/kernel ONLY — never react/dom/three (enforced).
+ */
+export declare const CORE_VERSION = "0.0.0";
+export { defineSchemaOnce, hmrInvalidateOnSchemaChange } from "./boot/hmr";
+export { All, Any, Not, Related, createWorld, defineQuery, defineSystem, defineTickSystem, enumOf, field, Local, } from "@vibecook/strata-ecs";
+export type { Batch, Component, Condition, Entity, Pipeline, Query, Relation, Resource, System, SystemCtx, Tag, TickSystem, World, } from "@vibecook/strata-ecs";
+export { defineComponent, defineRelation, defineResource, defineTag, schemaMeta, type ComponentMeta, type RawSchema, type RelationMeta, type ResourceMeta, } from "./schema/meta";
+export { definePrefab, init, PrefabId, prefabs, type ComponentInit, type FieldWrite, type Prefab, type PrefabClass, type PrefabDef, } from "./schema/prefab";
+export { instantiate, type EphSpawner, type SpawnTarget } from "./engine/instantiate";
+export { FrameInfo, setFrameInfo } from "./engine/frame-info";
+export { createPipelineRegistry, PHASE_GROUPS, type AnySystem, type PhaseGroup, type PipelineRegistry } from "./engine/pipeline";
+export { createReflectorRegistry, type ReflectorDef, type ReflectorObserve, type ReflectorQuerySpec, type ReflectorRegistry, } from "./engine/reflectors";
+export { createEngine, type Engine, type EngineOpts, type FrameTelemetry, type PublishHook, type SystemRunRecord, } from "./engine/engine";
+export { devGuardsEnabled, setDevGuards } from "./guards/dev";
+export { createLiveWriter, type LiveWriter, type LiveWriterOpts } from "./guards/live-writer";
+export { guardedTransaction, type GuardedTx, type GuardedTxOpts } from "./guards/guarded-tx";
+export { writeRuntimeResource } from "./guards/resource-writer";
+export * from "./catalog";
+export * from "./helpers/phase-set";
+export * from "./helpers/version-stamps";
+export * from "./ops/selection";
+export * from "./ops/cascade";
+export * from "./ops/claims";
+export * from "./ops/gestures";
+export * from "./ops/point-pick";
+export { createInputQueue, NO_MODS, type InputEvent, type InputEventKind, type InputMods, type InputQueue } from "./input/queue";
+export { createRecordingCommitSink, type CommitIntent, type CommitCreate, type CommitReparent, type CommitSink, type CommitWrite, } from "./engine/commit-sink";
+export { ensureCanvasSurface, installInteractionCore, installInteractionStack, type InteractionCore, type InteractionCoreOpts, type InteractionStack, } from "./interaction/install";
+export type { MarqueeBuffer } from "./systems/l3-marquee";
+export { DEFAULT_SPAWN_PROFILES, type SingleKindName, type SpawnProfiles } from "./systems/l2-recognize";
+export { createCursorSync } from "./systems/l4-cursor";
+export { createWireSync, type WireSyncSystem } from "./systems/l1-wires";
+export { createPortMaterialize } from "./systems/l3-ports";
+export { createConnectSystems, type ConnectSystems, type WirePreviewBuffer, } from "./systems/l3-connect";
+export { ENGINE_SCHEMA_VERSION, ENVELOPE_MAGIC, ENVELOPE_VERSION, EnvelopeError, decodeEnvelope, encodeEnvelope, type EnvelopeHeader, } from "./doc/envelope";
+export { gateVerdict, readDocVersionReport, stampEngineMeta, type DocVersionReport, type GateVerdict, } from "./doc/version-gate";
+export { createDocCommitSink, createReadOnlyCommitSink } from "./doc/doc-commit-sink";
+export { DurableUndoStatus } from "@vibecook/strata-ecs/durable";
+export type { DurableUndoStatusValue } from "@vibecook/strata-ecs/durable";
+export { createDocSession, openDocSession, type DocSession, type DocSessionOpts, type OpenDocResult, } from "./doc/doc-kit";
+export { runMigrations, type MigrationCtx, type MigrationOutcome } from "./doc/migrate";
+export { p, type JsonShape, type PropSpec, type PropsDecl, type StandardSchemaV1 } from "./widget/props";
+export { WidgetEquipped, defineWidget, widgets, type SizeMode, type WidgetDef, type WidgetGroup, type WidgetInteraction, type WidgetPortDecl, type WidgetSurface, type WidgetType, } from "./widget/define-widget";
+export { createWidgetEquipSystem } from "./widget/equip";
+export { spawnWidget, widgetSpawnInits, type SpawnWidgetOpts } from "./widget/spawn";
+export { createWidgetRuntime, installWidgetRuntime, type MountEntry, type WidgetMountStore, type WidgetRuntime, } from "./widget/mount-store";
+export * from "./settings/defaults";
+export { CameraInertia, createCameraSystems, type CameraSystems } from "./systems/camera-sim";
+export { restoreAutosave, startAutosave, type Autosave, type AutosaveOpts, type AutosaveState, type AutosaveStatus, type AutosaveStorageRead, type AutosaveStorageWrite, type CancelScheduled, type RestoreResult, } from "./doc/autosave";
+export { attachBroadcastRelay, type BroadcastRelay, type BroadcastRelayOpts, type RelayChannel, } from "./doc/broadcast-relay";
+export { createMeasureQueue, type MeasureEvent, type MeasureQueue } from "./input/measure-queue";
+export { createMeasureIngest } from "./systems/measure-ingest";
+export { createBreakpointSystem, createSelectionChromeSystem } from "./systems/chrome";
+export { createNestedCanvas, currentNavEntry, currentNavFrame, type NestedCanvas, type NestedCanvasOpts, } from "./nav/nested-canvas";
+export { attachPresence, createPresencePublish, createRemoteCursorsSystem, DEFAULT_PRESENCE_TTL_MS, installPresence, type InstallPresenceOpts, type PresenceOpts, type PresencePublishOpts, type PresenceSession, } from "./presence";
+export { joinDoc, type BootstrapClock, type JoinDocOpts, type JoinResult, } from "./doc/bootstrap";
+export { broadcastChannelByteChannel, webSocketByteChannel, type ByteChannel, type OwnedByteChannel, type WebSocketLike, } from "./doc/channels";
+export { createDrawTool, defineTool, tools, type CanvasDragRoute, type Tool, type ToolDef, type ToolGates, type ToolRoute, type WidgetDragRoute, } from "./tools/define-tool";
+export { createCanvasEngine, type CanvasDocs, type CanvasEngine, type CanvasEngineOpts, type CanvasOps, } from "./facade/create-canvas-engine";
+export { createDrawBehavior } from "./systems/l3-draw";