@vibecook/ice 0.11.0 → 0.14.0

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

@@ -1,8 +1,11 @@
 import type { World } from "@vibecook/strata-ecs";
 import type { Attachment, DurableStore } from "@vibecook/strata-ecs/durable";
-import type { CommitSink } from "../engine/commit-sink";
+import { type CanvasTypeIdentity } from "../canvas/define-canvas-type";
+import type { EngineCatalog } from "../canvas/engine-catalog";
+import type { CommitIntent, CommitSink } from "../engine/commit-sink";
+import { type CommitExtender } from "./doc-commit-sink";
 import { type LiveWriter } from "../guards/live-writer";
-import { type DocVersionReport, type GateVerdict } from "./version-gate";
+import { type DocVersionScope, type DocVersionReport, type GateVerdict } from "./version-gate";
 export interface DocSessionOpts {
     readonly maxUndoSteps?: number;
     /** Override the default gate policy (design-005 §6.3 facade hook). */
@@ -14,6 +17,16 @@ export interface DocSessionOpts {
      * "migrate" verdict attaches read-only, no upgrade).
      */
     readonly migrate?: boolean;
+    /** Low-level engine-scoped pack authority; the facade always supplies this. */
+    readonly versionScope?: DocVersionScope;
+    /** New-document identity only. Existing documents always use their stored value. */
+    readonly rootCanvas?: CanvasTypeIdentity;
+    /** Engine-owned final mutation guard; low-level unscoped sessions may omit it. */
+    readonly commitGuard?: (intent: CommitIntent) => CommitIntent | undefined;
+    /** The layers' word on a gesture's landing, inside its transaction (the facade fans its registered extenders through this). */
+    readonly commitExtend?: CommitExtender;
+    /** Engine-scoped CanvasType definitions used by solo semantic migration. */
+    readonly canvasCatalog?: EngineCatalog;
 }
 export interface DocSession {
     readonly store: DurableStore;
@@ -25,6 +38,8 @@ export interface DocSession {
      */
     readonly attachment: Attachment;
     readonly readOnly: boolean;
+    /** Authoritative stored root identity, absent only for malformed legacy/read-only data. */
+    readonly rootCanvas?: CanvasTypeIdentity;
     /**
      * 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;
@@ -34,6 +49,10 @@ export interface DocSession {
     readonly liveWriter: LiveWriter;
     /** Present on the open path (the gate's evidence). */
     readonly report?: DocVersionReport;
+    /** Re-read current monotone requirements after remote/capability changes. */
+    versionReport(): DocVersionReport;
+    /** Solo/local capability grant: requirement markers land before any content. */
+    upgradePacks(packs: Readonly<Record<string, number>>): boolean;
     /** Envelope-framed snapshot for storage (autosave kit consumes this). */
     exportEnvelope(savedAt?: number): Uint8Array;
     /** Relay passthroughs (M5 dumb relay; M9 brings the bootstrap protocol). */

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

@@ -9,20 +9,23 @@
  *   bytes 0..3   magic "ICE1"
  *   byte  4      envelope version (1)
  *   bytes 5..8   u32 header length
- *   ...          header JSON: { engineSchema, prefabVersions, savedAt? }
+ *   ...          header JSON: { engineSchema, prefabVersions, rootCanvas?, savedAt? }
  *   ...          payload: Loro snapshot bytes (opaque here)
  *
  * WHERE bytes go (fs/IndexedDB/cloud) is app-owned; WHAT they are is this file.
  */
+import type { CanvasTypeIdentity } from "../canvas/define-canvas-type";
 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 = 2;
+export declare const ENGINE_SCHEMA_VERSION = 3;
 export interface EnvelopeHeader {
     readonly engineSchema: number;
     /** Per-prefab pack versions at save time ({ [prefabId]: version }). */
     readonly prefabVersions: Readonly<Record<string, number>>;
+    /** Coarse pre-import mirror; in-document ice:rootCanvas remains authoritative. */
+    readonly rootCanvas?: CanvasTypeIdentity;
     /** App-supplied wall-clock ms (the engine never reads a clock). */
     readonly savedAt?: number;
 }

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

@@ -1,5 +1,5 @@
 /**
- * STRUCTURAL schema migrations (petition 8; engineSchema 1 → 2).
+ * STRUCTURAL schema migrations (engineSchema 1 → current).
  *
  * 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

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 CanvasTypeIdentity } from "../canvas/define-canvas-type";
 import { type EnvelopeHeader } from "./envelope";
 export interface DocVersionReport {
     /** Highest engine.schema.<n> marker present (0 = unstamped/pre-engine doc). */
@@ -44,6 +45,23 @@ export interface DocVersionReport {
      * would brick the doc `readOnly` via `newerInDoc` — the I5 failure mode.
      */
     readonly renamedInDoc: Readonly<Record<string, number>>;
+    /** Authoritative semantic identity for the document's BoardRoot. */
+    readonly rootCanvas?: CanvasTypeIdentity;
+    /** A schema-3 root invariant failure. It can never be overridden into writable. */
+    readonly rootIssue?: string;
+    /**
+     * Missing exact semantic dependency markers for otherwise-current packs.
+     * Evaluated only on a CURRENT-schema document — see {@link dependencyIssues}.
+     */
+    readonly dependencyIssues?: readonly string[];
+}
+/** Engine-scoped definition authority used by stamping and comparison. */
+export interface DocVersionScope {
+    /** Every pack/version this engine can understand while opening a document. */
+    readonly localPacks: Readonly<Record<string, number>>;
+    /** Exact capability manifest stamped on a newly created document. */
+    readonly initialPacks?: Readonly<Record<string, number>>;
+    readonly packDependencies?: Readonly<Record<string, Readonly<Record<string, number>>>>;
 }
 export type GateVerdict = "ok" | "readOnly" | "migrate" | "reject";
 /**
@@ -51,15 +69,15 @@ export type GateVerdict = "ok" | "readOnly" | "migrate" | "reject";
  * path; idempotent write-once; callable BEFORE attach — the order is
  * `createDurableStore(doc)` first, then stamp, then `attachDurable`).
  */
-export declare function stampEngineMeta(store: DurableStore): void;
+export declare function stampEngineMeta(store: DurableStore, scope?: DocVersionScope, rootCanvas?: CanvasTypeIdentity): void;
 /** Read the marker keys off a raw (imported, unattached) doc and compare. */
-export declare function readDocVersionReport(doc: LoroDoc): DocVersionReport;
+export declare function readDocVersionReport(doc: LoroDoc, scope?: DocVersionScope): DocVersionReport;
 /**
  * Build the same comparison report from an envelope header, before Loro
  * import. The header carries no meta, so no tombstone knowledge here —
  * registry aliasing only. This preflight is coarse by design; the
  * authoritative in-document gate re-runs right after import.
  */
-export declare function readEnvelopeVersionReport(header: EnvelopeHeader): DocVersionReport;
+export declare function readEnvelopeVersionReport(header: EnvelopeHeader, scope?: DocVersionScope): 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

@@ -62,6 +62,13 @@ export interface CommitCreate {
     readonly props?: Readonly<Record<string, unknown>>;
     readonly parent?: Entity;
     readonly select?: boolean;
+    /** Where the widget joins its parent's sibling sequence (default: last — on top). An ⌥-drag's copy goes `{ before: original }` (D4a). */
+    readonly order?: OrderPlace;
+}
+/** Generation key captured by an interactive commit before final validation. */
+export interface CommitScope {
+    readonly documentEpoch: number;
+    readonly canvasEpoch: number;
 }
 export interface CommitIntent {
     /** Outcome kind — traces assert on it. */
@@ -73,9 +80,11 @@ export interface CommitIntent {
     readonly orders?: readonly CommitOrder[];
     readonly wires?: readonly CommitWireSpawn[];
     readonly creates?: readonly CommitCreate[];
+    readonly scope?: CommitScope;
 }
 export interface CommitSink {
-    commit(intent: CommitIntent): void;
+    /** `false` asks gesture behavior to restore/fly back its runtime draft. */
+    commit(intent: CommitIntent): boolean | void;
 }
 /** The M4 default: record intents for traces/devtools; commit nothing. */
 export declare function createRecordingCommitSink(): CommitSink & {

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

@@ -88,6 +88,12 @@ export interface Engine {
     readonly guests: GuestRegistry;
     /** Run one full frame. `now` in ms (rAF timestamp or a test counter). */
     step(now: number): void;
+    /**
+     * Register a hook that runs right AFTER every `step` — outside the tick, after the reflectors
+     * (design-015 §9, D2b): where an op a system asked for inside the tick is applied (the facade's
+     * nav intent), whichever `step` a host drives. Returns a remover.
+     */
+    afterStep(hook: () => void): () => void;
     /**
      * The frame gate (2026-08-04): freeze/thaw plus the settle protocol a host
      * loop consults before each frame. It lives HERE, next to the step it

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

@@ -26,6 +26,24 @@
  * transitions. The DOM package's rAF loop is what actually parks and restarts;
  * `engine.step(now)` itself stays callable by hand (headless hosts, traces),
  * because the gate governs the LOOP, not the primitive.
+ *
+ * THE SLEEP (2026-09-27, ICE M21 K7a — design-015 §2.4 idle-zero, §11.4's
+ * ≤ 0.1 ms of main thread a second at rest). A freeze is taken; a sleep is
+ * FALLEN INTO: a host loop that opts in (`startRafLoop(…, { sleep: true })`,
+ * the desk host's default) asks {@link FrameControl.nextStep} after every step
+ * and stops scheduling frames once the engine is QUIET — no wake pending, no
+ * registered wake due, no settle reporter busy, for {@link SLEEP_TAIL} steps
+ * in a row (the tail lets a one-tick protocol — a cleared one-tick tag, a
+ * reaped recognizer, a commit at `JustEnded` — finish without a reporter of
+ * its own). Nothing is polled at rest: what can change the frame from outside
+ * a step says so — the world's outside doors (engine.ts: a write made outside
+ * a step), the input queue, the document's and the room's arrivals (the
+ * facade), a desk's own flux and its assets (`wake`) — and what is next live at
+ * a TIME says when (`wakeWhen`: a flight, a caret's blink, a layer let go,
+ * midnight). A step a sleeping loop takes for a registered time alone is
+ * {@link FrameControl.settled}: a host that polls its parts (the desk's kinds)
+ * asks only the parts that are due. A wake taken INSIDE a step asks for one
+ * more frame and restarts no tail (a kind's wanted frame is not an outside event).
  */
 import type { World } from "@vibecook/strata-ecs";
 /**
@@ -35,6 +53,28 @@ import type { World } from "@vibecook/strata-ecs";
  * reporter reads as a hiccup rather than a hang.
  */
 export declare const SETTLE_CAP = 120;
+/**
+ * Quiet steps a sleeping loop takes after the last outside wake (or the last
+ * busy step) before it sleeps (K7a): enough for the interaction stack's
+ * one-tick protocols — a pointer's up processed, its recognizer ended, the
+ * one-tick tags cleared and the recognizer reaped a tick later — to land
+ * without each needing a reporter. Three steps ≈ 50 ms at 60 Hz, once per
+ * outside event; a registered time's step takes none.
+ */
+export declare const SLEEP_TAIL = 3;
+/** What the sleep has done since the control was made (the rigs' and the units' instrument). */
+export interface SleepStats {
+    /** The host loop sleeps now (no frame scheduled; a wake or a registered time restarts it). */
+    readonly asleep: boolean;
+    /** Times the loop fell asleep. */
+    readonly sleeps: number;
+    /** Outside wakes by reason (`world`, `input`, `doc`, `presence`, `desk:…`, …) — each call counted, asleep or not. */
+    readonly wakes: Readonly<Record<string, number>>;
+    /** Steps a registered time started (the loop's own timer, nothing else pending). */
+    readonly timed: number;
+    /** Steps since the control was made (entered through the engine's `step`). */
+    readonly steps: number;
+}
 export interface FrameControl {
     /**
      * Take a named freeze. Returns an IDEMPOTENT thaw — the disposer pattern
@@ -67,5 +107,39 @@ export interface FrameControl {
     claimStep(): boolean;
     /** Wake on any freeze/thaw transition (the host loop restarts here). */
     onChange(fn: () => void): () => void;
+    /**
+     * Something happened that the next frame must see — an input, a write from outside a step, a document's or a room's
+     * arrival, an asset landing, a desk's flux: outside a step it restarts a sleeping loop and the tail; inside one it asks
+     * for one more frame. Counted by `reason`.
+     */
+    wake(reason: string): void;
+    /**
+     * A REGISTERED WAKE: after every step the host asks each source when it is next due, on `performance.now()`'s clock —
+     * at or before `now`: the next frame (it still moves); a later time: then (a sleeping loop sets a timer); `Infinity`:
+     * never on its own (only a `wake` brings it back). Returns an idempotent unregister.
+     */
+    wakeWhen(name: string, due: (now: number) => number): () => void;
+    /** The sources due at `now` or before (debug/devtools: "why is the loop awake?") — settle reporters busy included. */
+    due(now: number): readonly string[];
+    /**
+     * For frame hosts, once after every step: when the next step must run — `≤ now`: the next frame; a later time: then;
+     * `Infinity`: only on a wake. CONSUMING (it counts the quiet steps of the tail), never a predicate to poll.
+     */
+    nextStep(now: number): number;
+    /** The host loop fell asleep (`true`) or woke (`false`, `timed`: for a registered time alone) — bookkeeping for the stats. */
+    sleeping(asleep: boolean, timed?: boolean): void;
+    /** A wake arrived while the host sleeps: restart here (the host loop's subscription). Returns an unsubscribe. */
+    onWake(fn: () => void): () => void;
+    /**
+     * The step in progress began SETTLED — nothing pending, the tail long run: a sleeping loop's step for a registered time
+     * alone (or a headless host's step with nothing new). A host that polls its parts asks only those that are due.
+     */
+    settled(): boolean;
+    /** The engine's `step` entered and left (engine.ts): wakes inside a step ask for a frame, never a tail. */
+    enterStep(): void;
+    leaveStep(): void;
+    /** Inside the engine's `step` right now. */
+    stepping(): boolean;
+    sleepStats(): SleepStats;
 }
 export declare function createFrameControl(world: World): FrameControl;

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

@@ -56,7 +56,10 @@ export interface GuestInstance {
      * freeze taken mid-derive parks only AFTER the guest has caught up — the
      * canvas is never photographed between a structural change and its reflow.
      * A guest with no owed-work notion simply omits it (the frame gate then
-     * treats it as quiet, which is the honest default).
+     * treats it as quiet, which is the honest default). The same answer keeps a
+     * SLEEPING loop awake (K7a, frame-control.ts): a guest runs on the frames the
+     * engine steps — after a wake — and one that animates on its own clock says
+     * so here, or it runs only when something else wakes the loop.
      */
     busy?: () => boolean;
 }

package/dist/types/packages/core/src/engine/world-doors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * THE WORLD'S OUTSIDE DOORS (2026-09-27, ICE M21 K7a — frame-control.ts's sleep). A write made OUTSIDE a step — an app's
+ * command, a rig's camera, the host's viewport sync, a document's transaction projected, a reset or an import — must wake a
+ * sleeping loop, or the frame that shows it never comes. Every state-changing method strata names (`WorldMutatorName`,
+ * petition 4's exhaustive list, which strata's own devwrite drift test keeps whole) is wrapped ONCE on the world instance
+ * to tell its listeners after it returns; the step's own doors (`sync`, `tick`) are not wrapped. A listener decides what a
+ * write means — the engine's asks the frame for a wake, which a write INSIDE a step (a system's, a publish hook's, an
+ * after-step hook's) never is. The type below fails the build the day strata names a mutator this list does not.
+ */
+import type { World } from "@vibecook/strata-ecs";
+/** Tell `fn` after every write through one of `world`'s doors. Returns an idempotent unwatch. */
+export declare function watchWrites(world: World, fn: () => void): () => void;

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

@@ -14,11 +14,21 @@
  * 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.
+ * Budgets: the frame preview's (children, bytes). Port budgets remain reviewed
+ * constants (RUNTIME_BUDGETS) in v1 — recorded. `keepMounted` and `fboBytes`
+ * left at design-015 D5b with the mount LRU and the GL ledger.
  */
 import type { Entity, World } from "@vibecook/strata-ecs";
+import { type CanvasCatalogContribution, type CanvasType } from "../canvas/define-canvas-type";
+import { type EngineCatalog } from "../canvas/engine-catalog";
+import { type PlacementAuthority } from "../canvas/placement";
+import { type CanvasSessionValue } from "../canvas/session";
+import type { CanvasRuntimeExtension, FrameBehavior } from "../canvas/extensions";
+import type { FrameProjection } from "../canvas/frame-projection";
+import { type CanvasDiagnostic } from "../canvas/diagnostics";
+import { type FramePreviewStore } from "../canvas/frame-preview";
+import { type PresentationTransitionCoordinator } from "../canvas/presentation-transition";
+import type { CanvasCatalogSection } from "../canvas/define-canvas-type";
 import { type BehaviorRuntime } from "../behavior/runtime";
 import type { AnyBehaviorDef } from "../behavior/types";
 import { type Engine } from "../engine/engine";
@@ -31,12 +41,13 @@ 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 { CommitExtender } from "../doc/doc-commit-sink";
 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 PresenceOpts, type PresenceSession } from "../presence/presence-kit";
-import type { MeasureQueue } from "../input/measure-queue";
-import { GESTURE_DEFAULTS, POINTER_DEFAULTS } from "../settings/defaults";
+import type { EngineGpu } from "../surface/gpu-device";
+import { GESTURE_DEFAULTS, POINTER_DEFAULTS, type WheelMode } from "../settings/defaults";
 export interface CanvasEngineOpts {
     /** Registered widget types (definition happens at defineWidget; this list is validated). */
     readonly widgets?: readonly {
@@ -44,6 +55,20 @@ export interface CanvasEngineOpts {
     }[];
     /** Registered tools (definition happens at defineTool; validated). */
     readonly tools?: readonly Tool[];
+    /** Explicit Canvas SDK definitions. Supplying any typed field enables typed mode. */
+    readonly canvasTypes?: readonly CanvasType[];
+    /** New-document root only; existing documents retain their durable identity. */
+    readonly rootCanvas?: CanvasType;
+    /** Presentation-only fallback for unknown/incompatible document semantics. */
+    readonly presentationFallback?: CanvasType;
+    /** Presentation-only sections merged deterministically at compilation. */
+    readonly catalogContributions?: readonly CanvasCatalogContribution[];
+    /** Governed current-frame runtime definitions compiled by this engine. */
+    readonly canvasRuntimeExtensions?: readonly CanvasRuntimeExtension[];
+    /** Governed view-independent semantic frame definitions compiled by this engine. */
+    readonly frameBehaviors?: readonly FrameBehavior[];
+    /** Bounded read-only instance-preview projections compiled by this engine. */
+    readonly frameProjections?: readonly FrameProjection[];
     /**
      * Behaviors this engine runs (design-009). Definition is the import
      * side-effect; listing them here COMPILES and installs them — a behavior that
@@ -53,6 +78,11 @@ export interface CanvasEngineOpts {
     readonly behaviors?: readonly AnyBehaviorDef[];
     /** Generic guest breaker routing for hosts that use the published facade. */
     readonly onGuestFault?: (id: string, error: unknown) => void;
+    /**
+     * A reflector that threw (design-015 D7): the flush contains it — that frame is skipped — and routes it here (default:
+     * `console.error`). A host that counts its faults (apps/desk's `window.__desk.faults`, the rigs' "no page errors") passes it.
+     */
+    readonly onReflectorFault?: (name: string, error: unknown) => void;
     readonly onGuestNotice?: (message: string) => void;
     /** Behavior-specific routing preserves hook and entity provenance. The two
      *  pairs are COMPLEMENTARY, not alternatives: a fault that also strikes the
@@ -62,31 +92,63 @@ export interface CanvasEngineOpts {
     readonly onBehaviorFault?: (behavior: string, hook: string, entity: Entity | undefined, error: unknown) => void;
     readonly onBehaviorLog?: (behavior: string, message: string, rest: readonly unknown[]) => void;
     readonly budgets?: {
-        readonly keepMounted?: number;
-        readonly fboBytes?: number;
+        /** Portal-preview limits may be lowered from 128 children / 256 KiB. */
+        readonly framePreviewChildren?: number;
+        readonly framePreviewBytes?: number;
     };
     readonly settings?: {
+        /**
+         * The CameraLimits clamp. The desk's is infinite: `{ min: 1e-8, max: 1e8 }`
+         * (design-015 §9) — every camera path holds finite and invertible there.
+         */
         readonly zoom?: {
             readonly min?: number;
             readonly max?: number;
         };
-        readonly gestures?: Partial<Record<keyof typeof GESTURE_DEFAULTS, number>>;
+        /**
+         * GestureSettings seeds. `wheel` is a plain wheel's job (design-015 §9,
+         * D-D11): "pan" (default) or the desk's "zoom" about the pointer by
+         * `zoom · exp(−Δ · wheelZoomRate)` (default rate 0.0016, the prototype's).
+         */
+        readonly gestures?: Partial<Record<Exclude<keyof typeof GESTURE_DEFAULTS, "wheel">, number>> & {
+            readonly wheel?: WheelMode;
+        };
         readonly pointers?: Partial<Record<keyof typeof POINTER_DEFAULTS, number>>;
         readonly snap?: {
             readonly enabled?: boolean;
             readonly thresholdPx?: number;
         };
-        /** Selection-chrome knobs: liftScale = the app's visual drag-lift scale (union box wraps it). */
+        /** Selection-chrome knob: liftScale = the app's visual drag-lift scale (the resize handles wrap it). */
         readonly chrome?: {
             readonly liftScale?: number;
         };
+        /**
+         * Nav seeds (design-015 §9 — D2b). `zoomThrough`: a wheel zoom that leaves a container's
+         * face covering the view by `in` CSS px cuts into it, one that leaves the current frame's
+         * face `out` px short cuts back out — off unless `enabled` (the desk's is on); `gate` is the
+         * face's short side (CSS px) across which a live inside comes in (a face enters only at 1).
+         */
+        readonly nav?: {
+            readonly zoomThrough?: {
+                readonly enabled?: boolean;
+                readonly in?: number;
+                readonly out?: number;
+                readonly gate?: readonly [number, 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;
+    /**
+     * The engine's GPU device (design-012 §4; the device door since design-015 D5b): acquire it with
+     * `acquireCompositorDevice()` before constructing the engine and pass it here. ONE device per engine
+     * (D7): the desk's layer draws with it — `createDeskHost` hands it through the layer context — and never
+     * acquires its own, so its `errors()` sees the desk's uncaptured GPU errors; the app owns its end of life.
+     * Absent — the common case, and every headless engine — the desk acquires its own device.
+     */
+    readonly compositorDevice?: EngineGpu;
 }
 export interface CanvasOps {
     /** cancel active gestures → switch (design-003 §8; the strata-example lesson). */
@@ -112,6 +174,15 @@ export interface CanvasOps {
     selectAll(): void;
     /** Sibling-sequence sweep, one tx: the ids to the frame top/bottom (petition 8). */
     reorder(ids: readonly Entity[], mode: "top" | "bottom"): void;
+    /**
+     * Tape widgets down, or lift the tape (design-015 §5.1, *Marks on the Mat*
+     * Q-e): writes the durable `Locked` tag on every id that is a widget of the
+     * current frame whose state differs, in ONE transaction (one undo step; no
+     * transaction at all when nothing changes). A taped widget is never moved or
+     * resized by a gesture and the marquee passes over it; it stays selectable,
+     * pickable and openable. Refuses on a read-only document like every write op.
+     */
+    setLocked(ids: readonly Entity[], locked: boolean): void;
     /**
      * Desktop-style Clean Up (kernel packLayout): tidy reading-order rows, one
      * undo step, 240ms glide (durationMs: 0 snaps). Scope: ids > selection ≥2 >
@@ -138,6 +209,32 @@ export interface CanvasOps {
     /** Pop several levels in ONE transition (breadcrumb jumps; design-006 §5). */
     exitTo(targetDepth: number, opts?: NavOpts): void;
     cancelActiveGestures(): void;
+    /**
+     * Pick an object up into the hand (design-015 §8, D4b): the ONE writer of the runtime `Held`
+     * tag (with a fresh `HeldView`) — no camera moves, the renderer lifts the object to its reading
+     * size and the desk behind goes out of focus. The object is selected as it is picked up (it
+     * stays selected when put down, so ⏎ opens it again) and any live gesture is cancelled. Refused
+     * — an Error, like `enterContainer` on a non-container — for an entity that is not a live object
+     * of the current frame whose type declares `openable` (its kind has an `open` binding), and while
+     * another object is held (put that one down first). Never a document write. The object's tool in
+     * hand (`HeldTool`, D3t-a) comes with it: its type's `heldTool` of its props, else its first mode.
+     */
+    open(entity: Entity): void;
+    /** Put the held object down (design-015 §8): `Held`, `HeldView` and `HeldTool` leave; the renderer flies it home. Nothing held: no-op. */
+    putDown(): void;
+    /**
+     * Use a tool of the held bar (design-015 §8; D3t-a — widget/held-tools.ts): a `mode` becomes the held object's ACTIVE
+     * tool (`HeldTool` — a runtime write, the user's fact; a `toggle` mode chosen again hands back the one before it), an
+     * `action` runs its op once (its transaction, the document's undo or redo). False when nothing is held, the held type
+     * names no such tool, or the tool is declared only.
+     */
+    useHeldTool(id: string): boolean;
+    /**
+     * Run a SELECTION MENU act (design-016 §5 · K-L2, K8a — widget/menu-actions.ts): the act `id` of the selected objects' types, each
+     * declaring type's `run` handed its own selected objects. False when nothing selected declares it (the menu shows an act only when
+     * every selected object's type does; an app's key reaches the ones that do).
+     */
+    runMenuAction(id: string): boolean;
 }
 export interface CanvasDocs {
     create(opts?: DocSessionOpts): DocSession;
@@ -155,6 +252,16 @@ export interface CanvasDocs {
         };
     }): Promise<JoinResult>;
     current(): DocSession | undefined;
+    /**
+     * A layer's word on a gesture's landing: `extend` runs INSIDE every gesture's committing transaction (a move, a consume,
+     * a resize, a create…), after the gesture's own writes, with the intent that made them — so what it adds is the gesture's
+     * undo step, not a second one (the desk sticks a note to a calendar's day this way: the pin and the slot land with the
+     * move, one ⌘Z takes the whole drop back). A cancelled gesture commits nothing and so reaches no extender. Registered on
+     * the engine, not a session: it serves every document this engine opens until the returned function is called.
+     */
+    extendCommits(extend: CommitExtender): () => void;
+    /** Add compiled widget capability requirements before creating their content. */
+    upgradeCapabilities(widgetTypeIds: readonly string[]): boolean;
     /**
      * Attach facade presence to an ALREADY-live document (petition I18) — for
      * hosts that own their document lifecycle (`create()`/`open()` + their own
@@ -204,9 +311,27 @@ export interface StageControl {
     /** Live hold names, in take order (debug/devtools). */
     holds(): readonly string[];
 }
+/** Headless current-canvas surface consumed by trays, keymaps, and adapters. */
+export interface CurrentCanvasScope {
+    current(): CanvasSessionValue;
+    type(): CanvasType;
+    catalog(): readonly CanvasCatalogSection[];
+    tools(): readonly Tool[];
+    /** Stable, locally derived compatibility/policy diagnostics for the attached document. */
+    diagnostics(): readonly CanvasDiagnostic[];
+    subscribe(onChange: () => void): () => void;
+}
 export interface CanvasEngine {
     readonly world: World;
     readonly engine: Engine;
+    /** Immutable definition authority for this engine instance. */
+    readonly catalog: EngineCatalog;
+    /** The one semantic authority used by all local placement paths. */
+    readonly placement: PlacementAuthority;
+    /** Resource-backed current CanvasType/catalog/tool projection. */
+    readonly canvas: CurrentCanvasScope;
+    /** Demand-driven semantic projections for visible container previews. */
+    readonly previews: FramePreviewStore;
     /**
      * The behavior runtime (design-009 §6): attach/detach/has/read for
      * runtime-class behaviors, plus `list()` for devtools and the doctor.
@@ -218,6 +343,8 @@ export interface CanvasEngine {
     readonly runtime: WidgetRuntime & {
         uninstall(): void;
     };
+    /** Trusted cross-package retention seam for cut-first canvas transitions. */
+    readonly transitions: PresentationTransitionCoordinator;
     readonly nav: NestedCanvas;
     readonly ops: CanvasOps;
     readonly docs: CanvasDocs;
@@ -230,9 +357,15 @@ export interface CanvasEngine {
      * whether you hold the facade or the raw engine.
      */
     readonly frame: FrameControl;
+    /**
+     * The app-owned GPU device when the app passed one (design-012 §4); undefined
+     * otherwise. `dispose()` deliberately does NOT destroy it: the device outlives
+     * layers by design, and its owner is the app that acquired it.
+     */
+    readonly compositorDevice?: EngineGpu;
     readonly budgets: {
-        readonly keepMounted: number;
-        readonly fboBytes: number;
+        readonly framePreviewChildren: number;
+        readonly framePreviewBytes: number;
     };
     /** step(now) passthrough — the app's rAF loop drives this. */
     step(now: number): void;