@vibecook/ice 0.1.0 → 0.3.0

package/dist/types/packages/core/src/catalog/gesture.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Recognizers & gestures — the L2 runtime recognizer prefabs (design-001 §5.5,
+ * design-003 §4).
+ *
+ * Identity is the KIND component (its presence is the kind; its fields are the
+ * working value). Phase is a tag-of-set flipped by the engine PhaseSet helper
+ * (strata has no one-of primitive; `Pending` was dropped as dead machinery). All
+ * in-flight state lives on the recognizer entity or the grabbed widgets — no
+ * singleton trackers — so N concurrent same-kind gestures are structural.
+ *
+ * Field set for each kind matches design-003 §4.2's revised table (which adds
+ * `zoomAtClaim` to Drag and Pinch over design-001 §5.5).
+ *
+ * Defaults policy (see catalog/index.ts): kind components and per-frame working
+ * riders are runtime scratch spawned/written by systems, so they carry full
+ * zero/identity defaults (ergonomic `ctx.spawn`). Origin-latch riders that MUST
+ * carry real values (Grab, Down) stay bare so a defaulted origin can't silently
+ * corrupt a cancel-restore.
+ */
+import { type Entity } from "@vibecook/strata-ecs";
 /** Continuous drag. Origin from dead-zone exit; totals/velocities accumulate; `zoomAtClaim` anchors widget-move math. */
 export declare const Drag: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{
     readonly startX: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
@@ -95,7 +115,7 @@ export declare const WheelZoom: import("@vibecook/strata-ecs").Component<import(
  * `Sequence`/`RequiresFail` edge. NEVER reaped; exempt from integrity's watched-pointer
  * count (a pending multi-tap legitimately outlives its lifted touch pointer).
  */
-export declare const GesturePhases: import("..").PhaseSet<"Possible" | "Active" | "Pending" | "Recognized" | "Ended" | "Failed" | "Cancelled">;
+export declare const GesturePhases: import("..").PhaseSet<"Active" | "Possible" | "Pending" | "Recognized" | "Ended" | "Failed" | "Cancelled">;
 /** Recognizer alive, not yet claiming. */
 export declare const GesturePossible: import("@vibecook/strata-ecs").Tag;
 /** Continuous kinds' claiming phase + per-frame work gate. */
@@ -168,23 +188,39 @@ export declare const Drags: import("@vibecook/strata-ecs").Relation;
 export declare const ClaimedBy: import("@vibecook/strata-ecs").Relation;
 /** recognizer → candidate container under the dragged bounds (design-003 §5 dropSystem). */
 export declare const DropTarget: import("@vibecook/strata-ecs").Relation;
+/**
+ * "None" sentinel for Grab's eid fields — strata's reserved null handle
+ * (entity 0 is never live; generations start at 1).
+ */
+export declare const NO_ENTITY: Entity;
 /**
  * Per-dragged-widget origin, attached at claim time with the CURRENT transform embedded
  * (design-001 §3, design-003 §4.5). Bare on purpose: a defaulted zero origin would corrupt
- * the cancel-restore of Position/StackZ.
+ * the cancel-restore of Position and sibling order.
+ *
+ * `parent`/`prev`/`ord` are the ORDER MEMO (petition 8) — the claim-time
+ * elevate is `moveRelation(w, ChildOf, "last")`, so cancel/fly-back must
+ * remember where the widget SAT: its `ChildOf` parent (NO_ENTITY = no edge —
+ * legacy world, nothing to restore), its nearest non-dragged predecessor
+ * sibling (NO_ENTITY = it was first), and its original sibling index (`ord` —
+ * the members' relative order at reinsert; see l3-behave's restore walk).
  */
 export declare const Grab: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{
     readonly x: "f64";
     readonly y: "f64";
     readonly w: "f32";
     readonly h: "f32";
-    readonly z: "f64";
+    readonly parent: "eid";
+    readonly prev: "eid";
+    readonly ord: "f64";
 }>, {
     readonly x: "f64";
     readonly y: "f64";
     readonly w: "f32";
     readonly h: "f32";
-    readonly z: "f64";
+    readonly parent: "eid";
+    readonly prev: "eid";
+    readonly ord: "f64";
 }>;
 /** Snap offset — in the Drag prefab's essential set (present from spawn, zeroed — writers never race an attach). */
 export declare const SnapState: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{

package/dist/types/packages/core/src/catalog/graph.d.ts

@@ -15,11 +15,11 @@ export declare const WirePorts: import("@vibecook/strata-ecs").Component<import(
 /** A widget port descriptor — spawned only for interaction (connect tool / hover proximity). */
 export declare const Port: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{
     readonly id: "string";
-    readonly side: import("@vibecook/strata-ecs").EnumType<"w" | "n" | "e" | "s">;
+    readonly side: import("@vibecook/strata-ecs").EnumType<"s" | "w" | "n" | "e">;
     readonly index: import("@vibecook/strata-ecs").FieldSpec<"u8", true>;
 }>, {
     readonly id: "string";
-    readonly side: import("@vibecook/strata-ecs").EnumType<"w" | "n" | "e" | "s">;
+    readonly side: import("@vibecook/strata-ecs").EnumType<"s" | "w" | "n" | "e">;
     readonly index: import("@vibecook/strata-ecs").FieldSpec<"u8", true>;
 }>;
 /** port → widget. */
@@ -47,9 +47,10 @@ export declare const Provides: import("@vibecook/strata-ecs").Component<import("
     readonly list: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
 }>;
 /**
- * The durable wire prefab (design-001 §5.3): PrefabId "wire" + WirePorts;
- * Wire tag + WireFrom/WireTo edges ride the spawn (doc commit sink executes
- * connect intents). Registered here so the version gate stamps
- * `engine.pack.wire.<v>` like every durable pack.
+ * The durable wire prefab (design-001 §5.3): WirePorts + the Wire tag +
+ * eligible WireFrom/WireTo edges — the COMPLETE contract, so the doc commit
+ * sink spawns through the paved `tx.spawnPrefab` path instead of a raw spawn
+ * that bypassed eligibility checks (2026-07-13 review). Registered here so the
+ * version gate stamps `engine.pack.wire.<v>` like every durable pack.
  */
 export declare const WirePrefab: import("..").Prefab;

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

@@ -27,6 +27,7 @@ export * from "./scene";
 export * from "./graph";
 export * from "./pointer";
 export * from "./gesture";
+export * from "./insert";
 export * from "./selection-presence";
 export * from "./camera-derived";
 export * from "./settings-resources";

package/dist/types/packages/core/src/catalog/insert.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The ghost marker + its promote payload, attached at `ops.insertByDrag`:
+ * `type`/`props` (JSON) rebuild the widget in the commit's `CommitCreate`;
+ * `screenX/screenY` remember the tray press point IN SCREEN SPACE so the
+ * cancel fly-back re-projects it through the CURRENT camera — the ghost
+ * returns to the tray on screen even if the user zoomed mid-drag.
+ */
+export declare const InsertGhost: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{
+    readonly type: "string";
+    readonly props: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly screenX: "f32";
+    readonly screenY: "f32";
+}>, {
+    readonly type: "string";
+    readonly props: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly screenX: "f32";
+    readonly screenY: "f32";
+}>;
+/**
+ * Set by moveBehavior when the ghost's gesture committed its `create` intent.
+ * The reap system despawns the ghost ONE tick later — the projected twin lands
+ * at the next sync, so the swap happens inside a single reflect flush (no
+ * one-frame blink of neither).
+ */
+export declare const GhostCommitted: import("@vibecook/strata-ecs").Tag;
+/**
+ * Set on the cancel / rejected-drop paths together with the fly-back
+ * `TransformTween`: the reap system despawns the ghost when the tween lands
+ * (component removed on arrival — camera-sim).
+ */
+export declare const GhostRetiring: import("@vibecook/strata-ecs").Tag;

package/dist/types/packages/core/src/catalog/pointer.d.ts

@@ -66,6 +66,17 @@ export declare const WentUp: import("@vibecook/strata-ecs").Tag;
 export declare const WentCancelled: import("@vibecook/strata-ecs").Tag;
 /** The down was consumed by a widget's own DOM handler — recognizers skip it. */
 export declare const HandledByWidget: import("@vibecook/strata-ecs").Tag;
+/**
+ * PERSISTENT (not one-tick): the pointer is hovering content that would opt a
+ * down out — a native interactive / `[data-canvas-interactive]` (DOM) or
+ * claim-capable island content (GL). Written change-only by ingest from the
+ * adapters' hover-time `overInteractive` fact (design-002 §8 amendment,
+ * 2026-07-18) and held across ticks with no fresh hover information (wheel,
+ * blur). Presentation-grade truth — cursor affordances telegraph "the widget
+ * owns your input here" BEFORE the down; recognizers never read it (the
+ * gesture gate stays `HandledByWidget`).
+ */
+export declare const OverInteractive: import("@vibecook/strata-ecs").Tag;
 /** Marks the local device's pointer(s) (vs. presence projections). */
 export declare const LocalPointer: import("@vibecook/strata-ecs").Tag;
 /** Derive-owned world position — screen × camera, recomputed every tick. */

package/dist/types/packages/core/src/catalog/scene.d.ts

@@ -20,15 +20,48 @@ export declare const Rotation: import("@vibecook/strata-ecs").Component<import("
 }>, {
     readonly r: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
 }>;
-/** Fractional stacking order — z-reorder is one cell write; midpoints jittered, ties break by key. */
+/**
+ * Optional-eligible widget opacity, 0..1 (design-004 §3: `{opacity}` is the
+ * neutral composite's WHOLE per-widget fact). Reflected by the dom host
+ * (style.opacity) and the gl composite quad (uOpacity) alike; absent = 1.
+ * Identity default so a bare attach is ergonomic.
+ */
+export declare const Opacity: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{
+    readonly a: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+}>, {
+    readonly a: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+}>;
+/**
+ * LEGACY (petition 8, engineSchema 2): scalar stacking order, superseded by ordered `ChildOf`
+ * sibling sequences. Stays REGISTERED so v1 docs' z cells keep projecting — the schema
+ * migration sorts by them, and a v1 doc opened read-only still paints z-correct through the
+ * renderers' legacy fallback. Never written for new entities; no new reader outside the
+ * migration and the read-only sort fallback.
+ */
 export declare const StackZ: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{
     readonly z: "f64";
 }>, {
     readonly z: "f64";
 }>;
 /**
- * child → parent frame (durable-eligible). Replaces the ParentFrame/ContainerChildren triad:
- * children-of-x = `Related(ChildOf, x)`; ancestor walk = forward `getRelation`; engine cascade
- * walks `getReverse(e, ChildOf)` (see ops/cascade.ts).
+ * child → parent frame (durable-eligible), ORDERED (petition 8): each parent's `getReverse` is
+ * its children in SIBLING ORDER — paint/pick order within a frame IS this sequence (the
+ * per-frame sibling-order law; design-004 §1 amendment). Placement rides
+ * `setRelation(child, ChildOf, parent, place)` / `moveRelation`; order converges
+ * collaboratively (CRDT movable list). Children-of-x = `Related(ChildOf, x)`; ancestor walk =
+ * forward `getRelation`; engine cascade walks `getReverse(e, ChildOf)` (see ops/cascade.ts).
  */
 export declare const ChildOf: import("@vibecook/strata-ecs").Relation;
+/**
+ * The BOARD ROOT (petition 8): the componentless durable entity every root-level widget hangs
+ * its `ChildOf` edge on, so the root frame has a sibling sequence like any container. Minted
+ * once per document (key recorded first-writer-wins in the meta map, `engine.boardRoot`);
+ * componentless BY LAW — it must dodge every widget/pick/cull query. This RUNTIME resource
+ * names it post-attach; absent = a pre-schema-2 read-only doc (renderers fall back to the
+ * legacy StackZ sort).
+ */
+export declare const BoardRoot: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly root: "eid";
+}>, {
+    readonly root: "eid";
+}>;

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

@@ -5,6 +5,13 @@ 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;
+/**
+ * Comment-box group drag (2026-07-18, James: the UE-Blueprint comment): a
+ * move claim on this widget ALSO claims every widget fully inside its bounds
+ * at claim time — spatial membership, never reparenting (that's the folder
+ * path). Drag a member out and it simply stops being inside.
+ */
+export declare const SweepsContained: 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)]`

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

@@ -1,3 +1,14 @@
+/**
+ * Selection-chrome live mirror (2026-07-17): `liftScale` = the app's visual
+ * drag-lift scale factor; `selectionChrome` inflates a Grab-bed member's rect
+ * by it (about the rect center) so the union box always wraps the card the
+ * user SEES, not just its ECS footprint.
+ */
+export declare const ChromeSettings: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly liftScale: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+}>, {
+    readonly liftScale: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+}>;
 /** 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>;
@@ -11,6 +22,8 @@ export declare const GestureSettings: import("@vibecook/strata-ecs").Resource<im
     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 wheelZoomSensitivity: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly wheelZoomMaxStep: 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>;
@@ -23,6 +36,8 @@ export declare const GestureSettings: import("@vibecook/strata-ecs").Resource<im
     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 wheelZoomSensitivity: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly wheelZoomMaxStep: 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<{
@@ -44,3 +59,9 @@ export declare const CameraLimits: import("@vibecook/strata-ecs").Resource<impor
     readonly minZoom: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
     readonly maxZoom: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
 }>;
+/** Nav-transition spring response live mirror (design-006 §4; navFlight consumes). */
+export declare const NavTransitionSettings: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly responseMs: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+}>, {
+    readonly responseMs: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+}>;

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

@@ -1,9 +1,46 @@
+/**
+ * The autosave kit (design-005 §6.6; design-001 §6.5 envelope-at-rest).
+ *
+ * Persists a `DocSession` to app-owned storage on a debounce (default 800 ms)
+ * with a max-wait ceiling (default 10 s), DEFERRED while the user is mid-gesture
+ * so a save never captures a half-applied interaction. What it writes is an
+ * ENVELOPE (`session.exportEnvelope(savedAt)`) — never raw Loro bytes — so the
+ * restore path can read the header and gate/quarantine BEFORE any import.
+ *
+ * CHANGE-SUBSCRIPTION SURFACE: two triggers, plus an initial arm.
+ * - `DurableStore.subscribeOutbound` (durable-store.ts) fires SYNCHRONOUSLY on
+ *   each sealed LOCAL commit and never on remote imports.
+ * - `DocSession.subscribeRemote` (doc-kit) fires after each successful
+ *   `applyRemote`. The original design left remote changes to "whichever peer
+ *   originated them" — but that peer persists to ITS storage, not this one's:
+ *   a joiner that received edits and closed restored a STALE local backup
+ *   (2026-07-13 review). Local autosave must reflect the last-seen document.
+ * - Autosave starts DIRTY: state that predates startAutosave() (a seeded or
+ *   freshly-joined doc) reaches storage after the first debounce, not only
+ *   after the next edit (same review — a seeded doc could close unsaved).
+ * No polling — the design's `store.exportSnapshot()` length/frontier poll is
+ * the last-resort fallback and is not needed here.
+ *
+ * Clock and scheduler are injectable so tests are deterministic with NO real
+ * timers; the design's `requestIdleCallback` optimization is just an alternate
+ * `schedule` an app can pass. `flush()` forces an awaited save; `close()`
+ * captures and durably serializes the final revision; `stop()` explicitly
+ * discards pending state.
+ *
+ * RESTORE (`restoreAutosave`): reads storage → `openDocSession`. Incompatible or
+ * corrupt bytes NEVER throw and NEVER brick boot (the M5 exit criterion) —
+ * they come back as `{ status: "quarantined", reason, bytes }` so the app can
+ * stash the bytes aside and start fresh.
+ */
 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;
+    /** Optional opaque Loro-update journal. `put` replaces the checkpoint and
+     * clears its journal; `append` durably extends the current checkpoint. */
+    append?(bytes: Uint8Array): Promise<void> | void;
 }
 /** The app-owned read side of storage (restore path). */
 export interface AutosaveStorageRead {
@@ -23,6 +60,10 @@ export interface AutosaveOpts {
     readonly now?: () => number;
     /** Timer factory; return a canceller (default `setTimeout`/`clearTimeout`). */
     readonly schedule?: (fn: () => void, ms: number) => CancelScheduled;
+    /** Compact after this many journal records (default 64). */
+    readonly checkpointEvery?: number;
+    /** Compact before the journal exceeds this many bytes (default 4 MiB). */
+    readonly maxJournalBytes?: number;
 }
 export type AutosaveStatus = "idle" | "pending" | "deferred" | "saving" | "saved" | "error";
 export interface AutosaveState {
@@ -33,9 +74,15 @@ export interface AutosaveState {
     readonly pending: boolean;
 }
 export interface Autosave {
-    /** Force a save of the current document now and await it (beforeunload / explicit save). */
+    /** Force a save of the current document now and await it. Rejects when persistence fails. */
     flush(): Promise<void>;
-    /** Unsubscribe and cancel any pending timer. Idempotent. */
+    /**
+     * Capture the final document synchronously, serialize it behind any in-flight
+     * write, and stop only after storage acknowledges it. Rejects on failure and
+     * may be retried; no document mutation should occur after close begins.
+     */
+    close(): Promise<void>;
+    /** Discard pending state immediately. Idempotent; never use for a normal close. */
     stop(): void;
     /** A pull-based status read for a per-frame HUD (design demo). */
     state(): AutosaveState;

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

@@ -59,14 +59,43 @@ export interface JoinDocOpts {
     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;
+    /**
+     * Abort the join: tears the room down (channel unsubscribed, session closed)
+     * and rejects the promise if it hasn't resolved yet. The facade aborts its
+     * pending join when another document supersedes it — a resolution-time check
+     * alone cannot stop a mid-handshake join from attaching to the world.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Live-session transitions: fired at every activation (including the first,
+     * just before the promise resolves) and with `undefined` when an internal
+     * re-bootstrap tears the quarantined session down. The facade re-targets its
+     * forwarding sink here — without it, callers keep committing into a session
+     * `rebootstrap()` already closed.
+     */
+    readonly onSession?: (session: DocSession | undefined) => void;
 }
 export interface JoinResult {
     /** "seeder" = we created the doc (timed out); "joiner" = we imported a peer's base. */
     readonly role: "seeder" | "joiner";
+    /** LIVE (a getter): after an internal re-bootstrap this is the replacement session. */
     readonly session: DocSession;
     /** Stop relaying, unsubscribe the channel, and close the session. Idempotent. */
     leave(): void;
 }
+/**
+ * Re-offer this session's document to the room (design-005 §6.5 amendment,
+ * 2026-07-20 — the lossy-transport repair). Broadcasts the base as an
+ * UN-addressed SNAPSHOT_OFFER — exactly the frame a joiner broadcasts after
+ * importing its base — so the protocol already defines every receiver's move:
+ * an ACTIVE peer MERGES it (loro dedupes; increments the outage dropped are
+ * subsumed by the full document), a BUFFERING peer OPENS it as its causal base.
+ * Call it when a lossy transport BEHIND a still-live channel heals (an Electron
+ * main's mesh link bounced; the IPC channel object never died). A channel that
+ * itself died (a closed socket) needs a fresh `joinDoc` instead — offers ride
+ * the channel, and a dead one drops them silently.
+ */
+export declare function offerBase(channel: ByteChannel, session: DocSession): 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).

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

@@ -16,6 +16,15 @@ export interface ByteChannel {
     send(bytes: Uint8Array): void;
     /** Deliver every inbound frame to `fn`. Returns an unsubscribe. */
     subscribe(fn: (bytes: Uint8Array) => void): () => void;
+    /**
+     * OPTIONAL readiness: resolves once the transport can actually transmit,
+     * rejects if it never will. `joinDoc` gates its hello + the seed-silence
+     * window on this — a queue-until-open transport otherwise lets a slow
+     * connect elapse the window and seed a DIVERGENT second doc offline
+     * (2026-07-13 review). Synchronous transports (BroadcastChannel, in-memory
+     * buses) simply omit it.
+     */
+    ready?(): Promise<void>;
 }
 /** A `ByteChannel` that owns a resource (a BroadcastChannel) and can release it. */
 export interface OwnedByteChannel extends ByteChannel {

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

@@ -15,8 +15,9 @@
  * cancel, and a DEV warn says why.
  */
 import type { DurableStore } from "@vibecook/strata-ecs/durable";
-import type { World } from "@vibecook/strata-ecs";
+import type { Entity, World } from "@vibecook/strata-ecs";
 import type { CommitSink } from "../engine/commit-sink";
+export declare function drainCreatedSelections(world: World): Entity[];
 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

@@ -1,5 +1,5 @@
 import type { World } from "@vibecook/strata-ecs";
-import type { DurableStore } from "@vibecook/strata-ecs/durable";
+import type { Attachment, 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";
@@ -18,6 +18,12 @@ export interface DocSessionOpts {
 export interface DocSession {
     readonly store: DurableStore;
     readonly sink: CommitSink;
+    /**
+     * The strata attachment — a read-only INSPECTION seam: its `baseline` feeds
+     * the observer devtools' durable tab (runtime-vs-baseline = the un-agreed
+     * sync delta). Never a sync path; `close()` owns its lifecycle.
+     */
+    readonly attachment: Attachment;
     readonly readOnly: boolean;
     /**
      * The design-001 §3 step-2 DEV guard, wired to THIS doc: userland live
@@ -33,6 +39,15 @@ export interface DocSession {
     /** Relay passthroughs (M5 dumb relay; M9 brings the bootstrap protocol). */
     exportSnapshot(): Uint8Array;
     applyRemote(bytes: Uint8Array): void;
+    /**
+     * Fires after each successful `applyRemote` on THIS session (strata's
+     * `subscribeOutbound` is local-commits-only by design, so remote imports are
+     * otherwise unobservable). Autosave rides this so a peer's local backup
+     * reflects the last-seen document, not just what it authored (2026-07-13
+     * review). A transport writing through `store.applyRemote` directly bypasses
+     * it — engine paths (bootstrap, broadcast relay) all go through the session.
+     */
+    subscribeRemote(fn: (bytes: Uint8Array) => void): () => void;
     /** cancel gestures → detach → world reset in place → respawn the anchor. */
     close(): void;
 }

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

@@ -16,8 +16,9 @@
  */
 export declare const ENVELOPE_MAGIC = "ICE1";
 export declare const ENVELOPE_VERSION = 1;
+export declare const MAX_ENVELOPE_HEADER_BYTES: number;
 /** The document-format version this build writes (gate compares against it). */
-export declare const ENGINE_SCHEMA_VERSION = 1;
+export declare const ENGINE_SCHEMA_VERSION = 2;
 export interface EnvelopeHeader {
     readonly engineSchema: number;
     /** Per-prefab pack versions at save time ({ [prefabId]: version }). */

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

@@ -59,11 +59,13 @@ export interface MigrationOutcome {
     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.
+ * Run every applicable per-type migration against an ATTACHED doc. ALL types
+ * are planned (read + transform-fold) BEFORE anything is written — a throwing
+ * transform on the Nth type therefore aborts with the document untouched,
+ * never with types 1..N-1 permanently migrated and the rest old (2026-07-13
+ * review). Each type then writes one non-undoable transaction and stamps its
+ * marker. 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/schema-migrate.d.ts

@@ -0,0 +1,50 @@
+/**
+ * STRUCTURAL schema migrations (petition 8; engineSchema 1 → 2).
+ *
+ * The per-prefab runner (migrate.ts) folds per-entity group values — it cannot spawn entities,
+ * see siblings, write relations, or stamp `engine.schema`, so a schema-version bump used to
+ * leave old docs read-only FOREVER (the gate re-ran, saw docSchema < local, and nothing ever
+ * advanced it). This module is the missing half: whole-document transforms keyed by the schema
+ * version they migrate FROM, run at open on a "migrate" verdict BEFORE the pack runner, each
+ * stamping `engine.schema.<n+1>` on success.
+ *
+ * SINGLE-WRITER LAW: a structural migration may only run when this peer is the document's sole
+ * occupant — the local open path (autosave restore, file open). A LIVE-ROOM JOINER MUST NOT
+ * migrate (bootstrap passes `migrate: false`): the room's peers are still writing the old
+ * shape, sync never re-gates, and a mid-room migration split-brains the doc (old peers write
+ * scalar z the new shape ignores, and vice versa). An old-schema doc joined live is read-only
+ * until it is opened solo by a current build.
+ *
+ * Step 1→2 — ordered relations:
+ *  1. BOARD ROOT: mint the componentless durable entity root-level widgets hang `ChildOf` on
+ *     ({@link ensureBoardRoot}); its key is recorded first-writer-wins in the meta map.
+ *  2. StackZ → sibling order: every durable widget is grouped by parent scope (existing
+ *     `ChildOf` target, else the board root), each group sorted by `(z asc, entityKey asc)`,
+ *     and re-linked in that order with `tx.setRelation(e, ChildOf, parent, "last")` — a
+ *     same-target re-set WITH a place is a move, so applying in sorted order lands the sorted
+ *     sequence; root-level widgets gain their first edge the same way. ONE non-undoable
+ *     transaction; absolute, idempotent, convergent (same doc → same sort → same sequence).
+ *  3. The legacy `StackZ` CELLS ARE KEPT: an old build opening the migrated doc read-only
+ *     (docSchema newer than local) still paints z-correct from them. New entities never write
+ *     StackZ; the cells are simply never read by current builds outside the legacy fallback.
+ */
+import type { Entity, World } from "@vibecook/strata-ecs";
+import type { DurableStore } from "@vibecook/strata-ecs/durable";
+import type { MigrationCtx } from "./migrate";
+import type { DocVersionReport } from "./version-gate";
+/**
+ * Resolve the document's board root, minting it if absent (create path + step 1→2). The mint
+ * is a componentless `tx.spawn()` in a non-undoable transaction; the key is recorded in meta
+ * first-writer-wins and re-read after the write so a raced winner is honored (the single-writer
+ * law makes a race unreachable in practice — belt and braces). Returns the LIVE handle.
+ */
+export declare function ensureBoardRoot(world: World, store: DurableStore): Entity;
+/** Read the board-root handle WITHOUT minting — read-only opens and post-attach lookups. */
+export declare function resolveBoardRoot(world: World, store: DurableStore): Entity | undefined;
+/**
+ * Run the structural chain `docSchema → … → localSchema`, stamping `engine.schema.<n+1>` after
+ * each step. A gap (missing step) stops the walk — the caller's re-gate keeps the doc
+ * read-only, exactly like a gappy pack chain. A docSchema of 0 is the gate's "reject" domain
+ * and never reaches here. Returns true when the doc reached the local schema version.
+ */
+export declare function runSchemaMigrations(ctx: MigrationCtx, report: DocVersionReport): boolean;

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

@@ -23,6 +23,7 @@
  */
 import type { LoroDoc } from "loro-crdt";
 import type { DurableStore } from "@vibecook/strata-ecs/durable";
+import { type EnvelopeHeader } from "./envelope";
 export interface DocVersionReport {
     /** Highest engine.schema.<n> marker present (0 = unstamped/pre-engine doc). */
     readonly docSchema: number;
@@ -45,5 +46,7 @@ export type GateVerdict = "ok" | "readOnly" | "migrate" | "reject";
 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;
+/** Build the same comparison report from an envelope header, before Loro import. */
+export declare function readEnvelopeVersionReport(header: EnvelopeHeader): 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

@@ -12,7 +12,7 @@
  * 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";
+import type { Component, Entity, OrderPlace } from "@vibecook/strata-ecs";
 /** One absolute component write inside a commit (whole-value, design-001 §2). */
 export interface CommitWrite {
     readonly entity: Entity;
@@ -24,6 +24,17 @@ export interface CommitReparent {
     readonly entity: Entity;
     readonly container: Entity;
 }
+/**
+ * An ordered-relation placement riding a commit (petition 8): the gesture's
+ * final sibling position lands IN the gesture's single transaction — one
+ * gesture stays one undo step. `parent` is re-asserted absolutely (a
+ * same-target `setRelation` WITH a place is a move, never a duplicate).
+ */
+export interface CommitOrder {
+    readonly entity: Entity;
+    readonly parent: Entity;
+    readonly place: OrderPlace;
+}
 /**
  * A wire creation riding a connect outcome (design-003 §5.8; design-001
  * §5.3): wires bind WIDGET entities + port IDS — never port entities.
@@ -34,13 +45,23 @@ export interface CommitWireSpawn {
     readonly fromPort: string;
     readonly toPort: string;
 }
-/** A widget creation riding a create outcome (draw tool, design-005 §3). */
+/**
+ * A widget creation riding a create outcome (draw tool, design-005 §3;
+ * tray-insert promote, 2026-07-19). `props`/`parent` extend the draw shape for
+ * ghost promotes: prop overrides rebuild the tray instance, `parent` lands a
+ * consume-into-container insert (x/y are container-LOCAL then, matching the
+ * reparent convention). `select` asks the sink to hand the projected twin to
+ * the reap system's selection transfer — the tray's select-on-drop.
+ */
 export interface CommitCreate {
     readonly type: string;
     readonly x: number;
     readonly y: number;
     readonly w: number;
     readonly h: number;
+    readonly props?: Readonly<Record<string, unknown>>;
+    readonly parent?: Entity;
+    readonly select?: boolean;
 }
 export interface CommitIntent {
     /** Outcome kind — traces assert on it. */
@@ -49,6 +70,7 @@ export interface CommitIntent {
     readonly gesture: Entity;
     readonly writes: readonly CommitWrite[];
     readonly reparents?: readonly CommitReparent[];
+    readonly orders?: readonly CommitOrder[];
     readonly wires?: readonly CommitWireSpawn[];
     readonly creates?: readonly CommitCreate[];
 }