@vibecook/ice 0.1.0

package/dist/types/packages/core/src/catalog/selection-presence.d.ts

@@ -0,0 +1,53 @@
+/** Runtime selection rider on widgets. */
+export declare const Selected: import("@vibecook/strata-ecs").Tag;
+export declare const Selectable: import("@vibecook/strata-ecs").Tag;
+export declare const Movable: import("@vibecook/strata-ecs").Tag;
+export declare const Resizable: import("@vibecook/strata-ecs").Tag;
+export declare const SnapSource: import("@vibecook/strata-ecs").Tag;
+export declare const SnapTarget: import("@vibecook/strata-ecs").Tag;
+/**
+ * Marks an ephemeral presence-peer entity (design-001 §5.6). Rides the presence
+ * blob so remote peers project it — a peer query is `[PresencePeer, Not(Local)]`
+ * (remote peers) or `[PresencePeer, Local]` (self). `Local` is strata-owned and
+ * auto-applied by the ephemeral store on spawn (never transmitted); this is the
+ * ONLY presence tag the engine mints, so pack differences can't corrupt it.
+ */
+export declare const PresencePeer: import("@vibecook/strata-ecs").Tag;
+/** Peer display identity. */
+export declare const PresenceInfo: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{
+    readonly name: "string";
+    readonly color: "string";
+}>, {
+    readonly name: "string";
+    readonly color: "string";
+}>;
+/** Peer cursor in world coords. */
+export declare const PresenceCursor: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{
+    readonly x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly device: import("@vibecook/strata-ecs").EnumType<"mouse" | "touch" | "pen">;
+}>, {
+    readonly x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly device: import("@vibecook/strata-ecs").EnumType<"mouse" | "touch" | "pen">;
+}>;
+/**
+ * Selection broadcast: count + combined bbox + a JSON key list capped at 32 (peers outline the
+ * listed widgets; beyond the cap they render the bbox only). Facet semantics: present only while the
+ * selection is non-empty.
+ */
+export declare const SelectionSummary: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{
+    readonly count: import("@vibecook/strata-ecs").FieldSpec<"u16", true>;
+    readonly x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly w: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly h: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly keys: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+}>, {
+    readonly count: import("@vibecook/strata-ecs").FieldSpec<"u16", true>;
+    readonly x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly w: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly h: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly keys: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+}>;

package/dist/types/packages/core/src/catalog/settings-resources.d.ts

@@ -0,0 +1,46 @@
+/** Recognizer timing/slop live mirror (design-003 §4.2 kind table; inertia constants §5 item 9). */
+export declare const GestureSettings: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly tapMaxMs: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly tapSlopPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly longPressMs: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly longPressSlopPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly dragSlopPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly pinchSlopPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly wheelEndSilenceMs: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly inertiaMinVelocityPxPerS: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly inertiaDecayMs: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly multiTapWindowMs: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly multiTapSlopPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+}>, {
+    readonly tapMaxMs: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly tapSlopPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly longPressMs: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly longPressSlopPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly dragSlopPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly pinchSlopPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly wheelEndSilenceMs: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly inertiaMinVelocityPxPerS: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly inertiaDecayMs: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly multiTapWindowMs: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly multiTapSlopPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+}>;
+/** Pick radii + retarget dead-band live mirror (design-003 §3 L1 targeting). */
+export declare const PointerSettings: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly radiusMousePx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly radiusTouchPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly radiusPenPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly hoverReleaseDeadBandPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+}>, {
+    readonly radiusMousePx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly radiusTouchPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly radiusPenPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly hoverReleaseDeadBandPx: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+}>;
+/** Zoom clamp live mirror (design-005 §4 `settings.zoom`; camera-sim consumes). */
+export declare const CameraLimits: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly minZoom: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly maxZoom: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+}>, {
+    readonly minZoom: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly maxZoom: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+}>;

package/dist/types/packages/core/src/doc/autosave.d.ts

@@ -0,0 +1,69 @@
+import type { World } from "@vibecook/strata-ecs";
+import { type DocSession, type DocSessionOpts } from "./doc-kit";
+import type { DocVersionReport } from "./version-gate";
+/** The app-owned write side of storage (localStorage, IndexedDB, fs, cloud — WHERE is app-owned). */
+export interface AutosaveStorageWrite {
+    put(bytes: Uint8Array): Promise<void> | void;
+}
+/** The app-owned read side of storage (restore path). */
+export interface AutosaveStorageRead {
+    get(): Promise<Uint8Array | undefined> | Uint8Array | undefined;
+}
+/** Cancels a scheduled callback (the return of an injected `schedule`). */
+export type CancelScheduled = () => void;
+export interface AutosaveOpts {
+    readonly storage: AutosaveStorageWrite;
+    /** The session's world — read for the gesture-deferral gate (never written). */
+    readonly world: World;
+    /** Quiet-period before a save (default 800 ms). */
+    readonly debounceMs?: number;
+    /** Hard ceiling from the first unsaved change to a forced save (default 10 s). */
+    readonly maxWaitMs?: number;
+    /** Wall-clock source; the engine never reads a clock itself (default `Date.now`). */
+    readonly now?: () => number;
+    /** Timer factory; return a canceller (default `setTimeout`/`clearTimeout`). */
+    readonly schedule?: (fn: () => void, ms: number) => CancelScheduled;
+}
+export type AutosaveStatus = "idle" | "pending" | "deferred" | "saving" | "saved" | "error";
+export interface AutosaveState {
+    readonly status: AutosaveStatus;
+    /** Wall-clock ms of the last successful save (via the injected `now`), or undefined. */
+    readonly lastSavedAt: number | undefined;
+    /** True while there are unsaved changes (a timer is armed or deferred). */
+    readonly pending: boolean;
+}
+export interface Autosave {
+    /** Force a save of the current document now and await it (beforeunload / explicit save). */
+    flush(): Promise<void>;
+    /** Unsubscribe and cancel any pending timer. Idempotent. */
+    stop(): void;
+    /** A pull-based status read for a per-frame HUD (design demo). */
+    state(): AutosaveState;
+}
+/**
+ * Begin autosaving `session` to `opts.storage`. Debounced with a max-wait
+ * ceiling, deferred while a gesture (or `Camera.gesturing`) is live. Returns the
+ * control surface; call `stop()` at teardown.
+ */
+export declare function startAutosave(session: DocSession, opts: AutosaveOpts): Autosave;
+/** The outcome of a restore attempt — a tagged union; nothing here ever throws. */
+export type RestoreResult = {
+    readonly status: "restored";
+    readonly session: DocSession;
+} | {
+    readonly status: "empty";
+} | {
+    readonly status: "quarantined";
+    readonly reason: string;
+    readonly bytes: Uint8Array;
+    readonly report?: DocVersionReport;
+};
+/**
+ * Load the autosaved document into `world`. Missing/empty storage ⇒
+ * `{ status: "empty" }` (the app creates fresh). A successful open ⇒
+ * `{ status: "restored", session }` (may be read-only per the version gate).
+ * Corrupt or incompatible bytes ⇒ `{ status: "quarantined", reason, bytes }` —
+ * NEVER a throw, NEVER a bricked boot (M5 exit criterion): the app stashes the
+ * bytes aside and starts fresh.
+ */
+export declare function restoreAutosave(world: World, storage: AutosaveStorageRead, opts?: DocSessionOpts): Promise<RestoreResult>;

package/dist/types/packages/core/src/doc/bootstrap.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The transport/bootstrap kit (design-005 §6.5) — the engine-provided join state
+ * machine; the app provides the byte channel (channels.ts).
+ *
+ * `joinDoc` runs the LOCKED §6.5 protocol:
+ *   join = broadcast hello → buffer inbound → import addressed snapshot as causal
+ *   base → re-broadcast own base → drain buffer; ~800 ms silence ⇒ first peer ⇒
+ *   seed. Reconnect = the caller calls `joinDoc` again (streams are never
+ *   resumed). A strata `PendingImportError` on a live update ⇒ automatic internal
+ *   re-bootstrap (one retry, then surfaced via `onError`).
+ *
+ * ── THE FRAME PROTOCOL (1-byte kind + payload) ──
+ *   HELLO(1)          payload = joinerId (UTF-8). "I'm joining; send me a base."
+ *   SNAPSHOT_OFFER(2) payload = an ENVELOPE-framed doc snapshot (header + loro
+ *                     bytes). An UNaddressed base broadcast — the post-import
+ *                     "re-broadcast own base" step; a buffering peer OPENS it (the
+ *                     gate runs), an active peer unwraps + merges it (dedupes).
+ *   SNAPSHOT(3)       payload = idLen(u16 LE) ++ targetId(UTF-8) ++ ENVELOPE. An
+ *                     addressed answer to a HELLO — only the peer whose id ==
+ *                     targetId adopts it as its causal base (others unwrap/merge).
+ *   UPDATE(4)         payload = a sealed local commit's incremental (raw) loro bytes.
+ *   PRESENCE(5)       payload = ephemeral presence bytes — rides the same channel,
+ *                     applied immediately (independent of the doc handshake).
+ *
+ * ── STATES ──
+ *   BUFFERING: helloed, no base yet. UPDATE frames are BUFFERED; the first snapshot
+ *     (offer, or addressed to us) triggers `becomeJoiner`; the hello-timeout triggers
+ *     `becomeSeeder`. PRESENCE flows immediately; HELLOs are ignored (nothing to offer).
+ *   ACTIVE: session live (either role). Answers HELLOs with an addressed snapshot,
+ *     merges snapshots/offers, applies updates, relays presence. Local commits ride
+ *     `store.subscribeOutbound` → UPDATE frames (remote-origin imports never re-fire it,
+ *     so an imported change is never rebroadcast — the origin IS the feedback guard).
+ *
+ * Two cold joiners with no existing doc BOTH time out and seed (split-brain) — the
+ * design's "first peer seeds" assumes a joiner arrives after a seeder exists; a
+ * simultaneous-cold-start tie-break is out of scope for M9 and noted here.
+ */
+import type { World } from "@vibecook/strata-ecs";
+import type { ByteChannel } from "./channels";
+import { type DocSession, type DocSessionOpts } from "./doc-kit";
+import type { PresenceSession } from "../presence/presence-kit";
+/** Injectable timer surface (autosave's clock precedent) so the hello-timeout is deterministic in tests. */
+export interface BootstrapClock {
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface JoinDocOpts {
+    /** Passed to create/open (maxUndoSteps, etc.). */
+    readonly docOpts?: DocSessionOpts;
+    /** Version-gate override, forwarded to `openDocSession` (a non-"ok" verdict ⇒ a read-only joiner). */
+    readonly onGate?: DocSessionOpts["onGate"];
+    /** Injected timer surface (tests). Default: global setTimeout/clearTimeout. */
+    readonly clock?: BootstrapClock;
+    /** Silence window before the lone/first peer seeds (design §6.5, default 800 ms). */
+    readonly helloTimeoutMs?: number;
+    /** Populate the fresh document — runs on the SEEDER path only, before it goes active. */
+    readonly seed?: (session: DocSession) => void;
+    /** Presence session to relay over the same channel (kind PRESENCE). Optional. */
+    readonly presence?: PresenceSession;
+    /** Surfaced when a re-bootstrap (after a PendingImportError) itself fails, or a base import fails post-join. */
+    readonly onError?: (err: unknown) => void;
+}
+export interface JoinResult {
+    /** "seeder" = we created the doc (timed out); "joiner" = we imported a peer's base. */
+    readonly role: "seeder" | "joiner";
+    readonly session: DocSession;
+    /** Stop relaying, unsubscribe the channel, and close the session. Idempotent. */
+    leave(): void;
+}
+/**
+ * Join (or found) the room's document over `channel`. Resolves once we go active —
+ * as a "joiner" (imported a peer's base) or a "seeder" (timed out and created one).
+ */
+export declare function joinDoc(world: World, channel: ByteChannel, opts?: JoinDocOpts): Promise<JoinResult>;

package/dist/types/packages/core/src/doc/broadcast-relay.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The dumb snapshot relay (design-005 §6.5 M5 stopgap; §6, decision "relay is
+ * dumb — inventory §1.3).
+ *
+ * M5 ONLY: broadcasts the WHOLE converged document on every local change and
+ * imports whole documents it receives. Loro imports dedupe, so a full snapshot
+ * is a valid (if wasteful) relay — this is deliberately the simplest thing that
+ * converges two tabs. M9 REPLACES it with the transport/bootstrap protocol
+ * (hello → addressed-snapshot base → increment stream); do not grow this into
+ * that — it is the throwaway.
+ *
+ * CHANGE-SUBSCRIPTION SURFACE + FEEDBACK GUARD: rides the same
+ * `DurableStore.subscribeOutbound` as the autosave kit, which fires ONLY on
+ * sealed LOCAL commits (durable-store.ts `onLocalBatch` early-returns on
+ * `origin !== "local"`). That origin filter IS the feedback-loop guard: applying
+ * a peer's snapshot via `applyRemote` produces remote-origin batches, which do
+ * NOT re-fire `subscribeOutbound`, so an imported change is never rebroadcast.
+ * No `applying` flag is needed — the subscription tells us the origin.
+ *
+ * LATE-JOINER SEED: on attach we post our snapshot (best-effort seed) AND a
+ * `hello`; peers answer a `hello` with their snapshot, so a tab opened second
+ * converges up to the first. BroadcastChannel never delivers a message to the
+ * instance that posted it, so hello/answer never self-loops.
+ */
+import type { DocSession } from "./doc-kit";
+/**
+ * The minimal channel surface the relay needs — structurally satisfied by the
+ * global `BroadcastChannel` and by test fakes. Anything carrying a `Uint8Array`
+ * through `postMessage` works (design-005 §6.5).
+ */
+export interface RelayChannel {
+    postMessage(message: unknown): void;
+    addEventListener(type: "message", listener: (ev: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", listener: (ev: {
+        data: unknown;
+    }) => void): void;
+    close?(): void;
+}
+export interface BroadcastRelayOpts {
+    /** Channel name; used to construct a `BroadcastChannel` when `channel` is absent. */
+    readonly channelName: string;
+    /** Injected channel (tests). When omitted, a `new BroadcastChannel(channelName)` is created and owned. */
+    readonly channel?: RelayChannel;
+}
+export interface BroadcastRelay {
+    /** Unsubscribe from the store, detach the listener, and close an owned channel. Idempotent. */
+    stop(): void;
+}
+/** Attach a dumb snapshot relay to `session` over a `BroadcastChannel` (or injected channel). */
+export declare function attachBroadcastRelay(session: DocSession, opts: BroadcastRelayOpts): BroadcastRelay;

package/dist/types/packages/core/src/doc/channels.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Byte-channel adapters for the bootstrap kit (design-005 §6.5: "provided
+ * adapters for BroadcastChannel and WebSocket byte relays; anything carrying a
+ * Uint8Array works").
+ *
+ * A `ByteChannel` is the whole transport contract the bootstrap state machine
+ * needs: `send(bytes)` out, `subscribe(fn)` in. The engine stays transport-free —
+ * the app owns the socket lifecycle and hands the instance in.
+ *
+ * Both adapters interact through STRUCTURAL types (no DOM lib dependency beyond
+ * what core already uses — the broadcast-relay precedent), so a test double or an
+ * alternative runtime satisfies them without the platform's exact event types.
+ */
+/** The transport contract: bytes out, bytes in. Structurally satisfied by both adapters + test fakes. */
+export interface ByteChannel {
+    send(bytes: Uint8Array): void;
+    /** Deliver every inbound frame to `fn`. Returns an unsubscribe. */
+    subscribe(fn: (bytes: Uint8Array) => void): () => void;
+}
+/** A `ByteChannel` that owns a resource (a BroadcastChannel) and can release it. */
+export interface OwnedByteChannel extends ByteChannel {
+    close(): void;
+}
+/** The slice of `WebSocket` we use (structural — the app supplies the instance). */
+export interface WebSocketLike {
+    binaryType: string;
+    readyState: number;
+    send(data: ArrayBufferLike | ArrayBufferView): void;
+    addEventListener(type: string, listener: (ev: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: string, listener: (ev: {
+        data: unknown;
+    }) => void): void;
+}
+/**
+ * A `ByteChannel` over a `BroadcastChannel` (same-origin tab-to-tab). Uint8Array
+ * is structured-cloneable, so it rides `postMessage` directly. A BroadcastChannel
+ * never delivers a message to the instance that posted it, so a peer never hears
+ * its own frames. `close()` releases the owned channel.
+ */
+export declare function broadcastChannelByteChannel(name: string): OwnedByteChannel;
+/**
+ * A `ByteChannel` over a caller-supplied WebSocket. Sets `binaryType =
+ * "arraybuffer"` (so inbound frames arrive as `ArrayBuffer`), and QUEUES outbound
+ * frames until the socket is OPEN, flushing on the `open` event. The app owns the
+ * socket (construction, reconnection, close).
+ */
+export declare function webSocketByteChannel(ws: WebSocketLike): ByteChannel;

package/dist/types/packages/core/src/doc/doc-commit-sink.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The doc-backed CommitSink — the M5 half of the commit seam (design-001 §3
+ * step 3a; design-002 decision 4).
+ *
+ * One intent = ONE `guardedTransaction` = one undo step. Behaviors already
+ * filtered their write sets to live `Drags` edges; the sink re-guards anyway —
+ * the doc is the authority (design-001 §3: `keyOf(w) === undefined ⇒ skip` —
+ * one dead widget must not roll back the gesture). Value writes go through
+ * `tx.edit().set` on PRE-EXISTING cells (the synchronous agreement point);
+ * consume's reparent is a relation write in the SAME transaction.
+ *
+ * Read-only sessions (version gate) swap in `createReadOnlyCommitSink`: the
+ * gesture still runs (runtime feels live) but nothing commits — the runtime
+ * cells reconverge with the baseline at the next remote sweep, exactly like a
+ * cancel, and a DEV warn says why.
+ */
+import type { DurableStore } from "@vibecook/strata-ecs/durable";
+import type { World } from "@vibecook/strata-ecs";
+import type { CommitSink } from "../engine/commit-sink";
+export declare function createDocCommitSink(store: DurableStore, world: World): CommitSink;
+/** The version-gate's read-only posture: gestures run, nothing commits. */
+export declare function createReadOnlyCommitSink(): CommitSink;

package/dist/types/packages/core/src/doc/doc-kit.d.ts

@@ -0,0 +1,50 @@
+import type { World } from "@vibecook/strata-ecs";
+import type { DurableStore } from "@vibecook/strata-ecs/durable";
+import type { CommitSink } from "../engine/commit-sink";
+import { type LiveWriter } from "../guards/live-writer";
+import { type DocVersionReport, type GateVerdict } from "./version-gate";
+export interface DocSessionOpts {
+    readonly maxUndoSteps?: number;
+    /** Override the default gate policy (design-005 §6.3 facade hook). */
+    readonly onGate?: (report: DocVersionReport, verdict: GateVerdict) => GateVerdict;
+    /**
+     * Run the M9 read-repair migrator on a "migrate" verdict (design-005 §6.4).
+     * Default TRUE: the doc attaches writable, the migrator upgrades older packs
+     * in place, and the session re-gates. Set false to keep M5 behavior (a
+     * "migrate" verdict attaches read-only, no upgrade).
+     */
+    readonly migrate?: boolean;
+}
+export interface DocSession {
+    readonly store: DurableStore;
+    readonly sink: CommitSink;
+    readonly readOnly: boolean;
+    /**
+     * The design-001 §3 step-2 DEV guard, wired to THIS doc: userland live
+     * writes to doc cells go through it (throws without a claim/tween;
+     * cellInDoc is exact via store.getComponent). Engine behaviors stay on
+     * ctx — they hold claims by construction.
+     */
+    readonly liveWriter: LiveWriter;
+    /** Present on the open path (the gate's evidence). */
+    readonly report?: DocVersionReport;
+    /** Envelope-framed snapshot for storage (autosave kit consumes this). */
+    exportEnvelope(savedAt?: number): Uint8Array;
+    /** Relay passthroughs (M5 dumb relay; M9 brings the bootstrap protocol). */
+    exportSnapshot(): Uint8Array;
+    applyRemote(bytes: Uint8Array): void;
+    /** cancel gestures → detach → world reset in place → respawn the anchor. */
+    close(): void;
+}
+export type OpenDocResult = {
+    readonly ok: true;
+    readonly session: DocSession;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly report?: DocVersionReport;
+};
+/** Create + attach a fresh document (local-first by construction, design-001 §6.3). */
+export declare function createDocSession(world: World, opts?: DocSessionOpts): DocSession;
+/** Open an envelope: gate BEFORE attach; quarantine is a return value, never a throw. */
+export declare function openDocSession(world: World, bytes: Uint8Array, opts?: DocSessionOpts): OpenDocResult;

package/dist/types/packages/core/src/doc/envelope.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The file envelope — the engine-owned at-rest format (design-001 §6.5,
+ * design-005 §6.2).
+ *
+ * A document at rest is NEVER raw Loro bytes: it is an engine-versioned frame
+ * read BEFORE any import, so the version gate and the autosave quarantine have
+ * a hook point that cannot brick boot. Layout (little-endian):
+ *
+ *   bytes 0..3   magic "ICE1"
+ *   byte  4      envelope version (1)
+ *   bytes 5..8   u32 header length
+ *   ...          header JSON: { engineSchema, prefabVersions, savedAt? }
+ *   ...          payload: Loro snapshot bytes (opaque here)
+ *
+ * WHERE bytes go (fs/IndexedDB/cloud) is app-owned; WHAT they are is this file.
+ */
+export declare const ENVELOPE_MAGIC = "ICE1";
+export declare const ENVELOPE_VERSION = 1;
+/** The document-format version this build writes (gate compares against it). */
+export declare const ENGINE_SCHEMA_VERSION = 1;
+export interface EnvelopeHeader {
+    readonly engineSchema: number;
+    /** Per-prefab pack versions at save time ({ [prefabId]: version }). */
+    readonly prefabVersions: Readonly<Record<string, number>>;
+    /** App-supplied wall-clock ms (the engine never reads a clock). */
+    readonly savedAt?: number;
+}
+export declare class EnvelopeError extends Error {
+    readonly reason: "magic" | "version" | "truncated" | "header";
+    constructor(message: string, reason: "magic" | "version" | "truncated" | "header");
+}
+export declare function encodeEnvelope(header: EnvelopeHeader, payload: Uint8Array): Uint8Array;
+export declare function decodeEnvelope(bytes: Uint8Array): {
+    header: EnvelopeHeader;
+    payload: Uint8Array;
+};

package/dist/types/packages/core/src/doc/migrate.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The M9 migration runner — read-repair at open (design-005 §6.4).
+ *
+ * A migration is NOT an offline byte transform: the document is already
+ * attached, its old cells projected into the runtime, and we upgrade them in
+ * place. For each durable type whose doc-side pack marker is OLDER than the
+ * local registry (`report.olderInDoc`) and whose widget carries a `migrate`
+ * chain covering the gap, `runMigrations`:
+ *   1. reads each entity's current group values from the runtime (already
+ *      canonicalised to the LOCAL schema — see the field-tolerance note below),
+ *   2. folds the chain `docV → docV+1 → … → localV-1` over a flat prop record,
+ *   3. writes the absolute per-group result back in ONE
+ *      `store.transaction(fn, { undoable: false })` — the commit never enters
+ *      the user's undo stack, history hooks skip it, a pending redo survives,
+ *   4. stamps the new `engine.pack.<id>.<localV>` write-once marker via
+ *      `store.metaTransaction` (excluded from undo, invisible to observers).
+ *
+ * WHY NO LEGACY-SCHEMA REGISTRATION (the as-built finding — design-005 §6.4 is
+ * conservative here): design-005 says "the compiler keeps legacy group
+ * components registered for every version covered by the migrate chain" because
+ * "strata skips unknown inbound components at projection." That is TRUE at the
+ * COMPONENT-NAME granularity — an unknown component name is never projected
+ * (strata-ecs binding.ts:390-392, 804; "unknown component — never projected").
+ * But it is field-TOLERANT within a known name: `canon(C, v)` iterates the
+ * LOCAL schema's `C.fields` (strata-ecs substrate/canon.ts:57-64), so a stored
+ * cell that carries EXTRA fields (a v2 that dropped a field) has them dropped,
+ * and one MISSING fields (a v2 that added a field) gets them default-filled by
+ * `encodeComponentValue`. Because `defineWidget` gives EVERY generated field a
+ * default (define-widget.ts strataFieldOf), a v1 cell projects cleanly into a
+ * v2 group component of the SAME name with no legacy registration — the
+ * transform reads the already-v2-shaped runtime value. Legacy registration
+ * would only be needed to migrate data OUT of a group REMOVED wholesale in v2
+ * (its component name unregistered → never projected); that coincides with the
+ * cross-schema data movement design-005 §6.4 already defers to vNext, so the
+ * `migrate` API stays the doc's `{ fromVersion: (prev) => next }` shape with no
+ * parallel legacy field. The `migrate.test.ts` "field tolerance" case proves
+ * the v1→v2 projection empirically (a v1 cell missing a v2-added field).
+ *
+ * Idempotence / convergence: writes are ABSOLUTE (whole-group values computed
+ * from v1), so two peers that migrate the same v1 doc independently produce
+ * identical cells that merge by last-writer-wins, and the marker is a
+ * first-writer-wins ADD. Re-opening an already-migrated doc reads the v2 marker
+ * → the type is no longer `olderInDoc` → the runner skips it. The runner must
+ * therefore run once per open against the open-time report (the caller re-gates
+ * after it, never re-invokes it against the same report).
+ */
+import type { World } from "@vibecook/strata-ecs";
+import type { DurableStore } from "@vibecook/strata-ecs/durable";
+import type { DocVersionReport } from "./version-gate";
+/** What the runner needs: the doc store to write through, the world to read from. */
+export interface MigrationCtx {
+    readonly store: DurableStore;
+    readonly world: World;
+}
+export interface MigrationOutcome {
+    /** Type ids whose entities were upgraded and whose v-local marker was stamped. */
+    readonly migrated: string[];
+    /** Type ids left as-is (no widget, no/gappy chain) — they stay read-only per the re-gate. */
+    readonly skipped: string[];
+}
+/**
+ * Run every applicable per-type migration against an ATTACHED doc. Reads happen
+ * before the write transaction opens (a clean read snapshot → compute → one
+ * absolute write pass); each type stamps its new marker in its own
+ * `metaTransaction` after its data transaction commits. Never throws for a
+ * merely-un-migratable type (missing widget / gappy chain → skipped); a genuine
+ * fault (a throwing transform) propagates so the caller can fall back read-only.
+ */
+export declare function runMigrations(ctx: MigrationCtx, report: DocVersionReport): MigrationOutcome;

package/dist/types/packages/core/src/doc/version-gate.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The document version gate (design-001 §6.1/§5.2, design-005 §6.3).
+ *
+ * Version state lives in the doc's reserved `meta` root map as WRITE-ONCE
+ * MARKER KEYS — a monotone key SET, never a mutated cell (sidestepping
+ * first-writer-wins): `engine.schema.<n>` and `engine.pack.<type>.<v>` are
+ * presence markers. Reading needs no strata API: the gate reads
+ * `doc.getMap("meta")` on the RAW LoroDoc after import, BEFORE
+ * `createDurableStore`/`attachDurable` — an incompatible doc never projects.
+ *
+ * Stamps go through `store.metaTransaction` (strata 0.4.0 — petition 3b
+ * LANDED): the commit is properly tagged (peers no longer warn about an
+ * untagged foreign writer), excluded from undo/redo, and invisible to
+ * observers. Same underlying `meta` root map and raw keys as the pre-0.4.0
+ * raw-doc stamps, so docs stamped by either path read identically here —
+ * and importers also stopped warning about metadata-only commits from
+ * before the API, so legacy docs are quiet too.
+ *
+ * M5 gate policy: exact schema + no doc-side pack NEWER than local ⇒ ok;
+ * anything else ⇒ readOnly (or reject via policy). The migrate verdict (older
+ * doc packs with a migrate chain) lands at M9 — the gate's verdict surface
+ * already carries it so the facade policy hook is stable.
+ */
+import type { LoroDoc } from "loro-crdt";
+import type { DurableStore } from "@vibecook/strata-ecs/durable";
+export interface DocVersionReport {
+    /** Highest engine.schema.<n> marker present (0 = unstamped/pre-engine doc). */
+    readonly docSchema: number;
+    readonly localSchema: number;
+    /** Highest engine.pack.<id>.<v> per prefab id present in the doc. */
+    readonly docPacks: Readonly<Record<string, number>>;
+    /** Local registry versions for DURABLE prefabs. */
+    readonly localPacks: Readonly<Record<string, number>>;
+    /** Prefab ids whose doc marker is NEWER than local (built by a newer app). */
+    readonly newerInDoc: readonly string[];
+    /** Prefab ids whose doc marker is OLDER than local (M9 migration input). */
+    readonly olderInDoc: readonly string[];
+}
+export type GateVerdict = "ok" | "readOnly" | "migrate" | "reject";
+/**
+ * Stamp the engine markers through the store's sanctioned meta path (create
+ * path; idempotent write-once; callable BEFORE attach — the order is
+ * `createDurableStore(doc)` first, then stamp, then `attachDurable`).
+ */
+export declare function stampEngineMeta(store: DurableStore): void;
+/** Read the marker keys off a raw (imported, unattached) doc and compare. */
+export declare function readDocVersionReport(doc: LoroDoc): DocVersionReport;
+/** The default M5 policy. A facade policy hook may override (design-005 §6.3). */
+export declare function gateVerdict(report: DocVersionReport): GateVerdict;

package/dist/types/packages/core/src/engine/commit-sink.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The commit seam (design-001 §3 gesture protocol × implementation-plan M4/M5).
+ *
+ * Behaviors end a gesture with ONE commit (design-002 decision 4). Until the
+ * durable layer lands (M5), commits are recorded as INTENTS through this seam:
+ * the M4 frame traces assert runtime state + commit intents, and M5 swaps in a
+ * doc-backed sink that turns an intent into one `guardedTransaction` per
+ * gesture (liveness guards re-checked inside the tx via live edges + keyOf —
+ * the intent carries the already-liveness-filtered write set, but the doc sink
+ * re-guards because the doc is the authority).
+ *
+ * The seam is deliberately dumb data: no callbacks into behaviors, no partial
+ * application — a whole gesture outcome in one value.
+ */
+import type { Component, Entity } from "@vibecook/strata-ecs";
+/** One absolute component write inside a commit (whole-value, design-001 §2). */
+export interface CommitWrite {
+    readonly entity: Entity;
+    readonly component: Component<any>;
+    readonly value: Record<string, unknown>;
+}
+/** A structural reparent riding a consume outcome (design-003 §5.5). */
+export interface CommitReparent {
+    readonly entity: Entity;
+    readonly container: Entity;
+}
+/**
+ * A wire creation riding a connect outcome (design-003 §5.8; design-001
+ * §5.3): wires bind WIDGET entities + port IDS — never port entities.
+ */
+export interface CommitWireSpawn {
+    readonly from: Entity;
+    readonly to: Entity;
+    readonly fromPort: string;
+    readonly toPort: string;
+}
+/** A widget creation riding a create outcome (draw tool, design-005 §3). */
+export interface CommitCreate {
+    readonly type: string;
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface CommitIntent {
+    /** Outcome kind — traces assert on it. */
+    readonly kind: "move" | "consume" | "resize" | "connect" | "create" | "delete";
+    /** The recognizer (or op source) that owned the gesture. */
+    readonly gesture: Entity;
+    readonly writes: readonly CommitWrite[];
+    readonly reparents?: readonly CommitReparent[];
+    readonly wires?: readonly CommitWireSpawn[];
+    readonly creates?: readonly CommitCreate[];
+}
+export interface CommitSink {
+    commit(intent: CommitIntent): void;
+}
+/** The M4 default: record intents for traces/devtools; commit nothing. */
+export declare function createRecordingCommitSink(): CommitSink & {
+    readonly intents: CommitIntent[];
+};