@vibecook/ice 0.1.0 → 0.3.0

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

@@ -21,6 +21,7 @@
  */
 import type { World } from "@vibecook/strata-ecs";
 import type { AnySystem } from "./pipeline";
+import { type FrameControl } from "./frame-control";
 import { type PhaseGroup } from "./pipeline";
 import { type ReflectorDef } from "./reflectors";
 export type PublishHook = (world: World) => void;
@@ -54,6 +55,16 @@ export interface Engine {
     onPublish(hook: PublishHook): () => void;
     /** Run one full frame. `now` in ms (rAF timestamp or a test counter). */
     step(now: number): 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
+     * governs, so every host gets it without a new argument — and so a
+     * subsystem holding only the `Engine` (the GL compositor) can report itself
+     * busy. `step()` itself stays unconditional: the gate governs the loop, not
+     * the primitive, which keeps headless hosts and traces driving frames by
+     * hand exactly as before.
+     */
+    readonly frame: FrameControl;
     /** Arm per-system run/skip + µs collection (idempotent; costs timer calls per system). */
     enableTelemetry(): void;
     /** The most recent completed frame's readout (undefined until telemetry armed + one step). */

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

@@ -0,0 +1,71 @@
+/**
+ * The frame gate (design-002 §1 amendment, 2026-08-04) — the frozen-world mode
+ * design-005 §7 named and deliberately left unbuilt.
+ *
+ * Stage holds are PRESENTATION policy: `StageMode.backgroundHolds` freezes the
+ * compositor on its retained textures while the world keeps stepping, which is
+ * exactly what makes a hold safe under a PARTIAL overlay — a menu panel floats
+ * over a still-live canvas, undo reflects, collab applies, tweens land. The
+ * rev-2 decision recorded that a stricter mode "would be a SEPARATE concept".
+ * This is that concept: while a freeze is held the host loop stops calling
+ * `step` at all — no systems, no publish, no notify, no reflectors, no rAF
+ * callback. It is for chrome that COVERS the canvas outright, where every
+ * frame drawn behind it is work nobody can see.
+ *
+ * THE SETTLE — why a freeze does not park on the spot. Parking the instant a
+ * freeze is taken would strand the canvas mid-churn: a cancelled gesture that
+ * has not reached its commit tick, islands still owed a first paint, a
+ * reflector holding a write that landed this frame. So a freeze walks the loop
+ * to QUIET — every registered settle reporter idle — then takes ONE further
+ * step so the quiet state itself reflects, and only then closes the gate. The
+ * walk is bounded by {@link SETTLE_CAP}: a reporter that never goes quiet makes
+ * a freeze park LATE, never never.
+ *
+ * Core stays scheduler-free (design-002 §1). This module owns no timer and
+ * starts nothing — it answers {@link FrameControl.claimStep} and announces
+ * 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.
+ */
+import type { World } from "@vibecook/strata-ecs";
+/**
+ * Frames a freeze may spend walking to quiet before it parks regardless.
+ * Two seconds at 60 Hz: comfortably longer than a cancelled gesture's path to
+ * its commit tick or a cold board's first paints, short enough that a wedged
+ * reporter reads as a hiccup rather than a hang.
+ */
+export declare const SETTLE_CAP = 120;
+export interface FrameControl {
+    /**
+     * Take a named freeze. Returns an IDEMPOTENT thaw — the disposer pattern
+     * that makes overlay lifecycles leak-proof (release on unmount), the name
+     * that makes "why is the engine parked?" answerable. Refcounted: the loop
+     * resumes when the LAST freeze thaws.
+     */
+    freeze(name: string): () => void;
+    /** A freeze is held — the loop is settling or already parked. */
+    isFrozen(): boolean;
+    /** The settle finished and the gate closed: no further steps are being run. */
+    isParked(): boolean;
+    /** Live freeze names, in take order (debug/devtools). */
+    holds(): readonly string[];
+    /**
+     * Register a settle reporter: while `busy()` is true, a taken freeze keeps
+     * stepping instead of parking. This is how a subsystem that owes visible
+     * work — the GL compositor's pending first paints, a gesture walking to its
+     * commit — keeps a freeze from landing on a half-finished image. Returns an
+     * idempotent unregister.
+     */
+    settleWhile(name: string, busy: () => boolean): () => void;
+    /** Reporters answering busy right now ("why hasn't it parked yet?"). */
+    settling(): readonly string[];
+    /**
+     * The loop gate. CONSUMING — each call advances the settle walk, so it is
+     * for frame hosts only, never a predicate to poll. Use {@link isFrozen} /
+     * {@link isParked} to ask questions.
+     */
+    claimStep(): boolean;
+    /** Wake on any freeze/thaw transition (the host loop restarts here). */
+    onChange(fn: () => void): () => void;
+}
+export declare function createFrameControl(world: World): FrameControl;

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

@@ -1,13 +1,28 @@
 import type { World } from "@vibecook/strata-ecs";
-/** { tick, dt ≤ dtClampMs (ms), now (ms timeline of the caller's clock) }. */
+/**
+ * { tick, dt ≤ dtClampMs (ms), now (ms timeline of the caller's clock),
+ *   clock (accumulated CLAMPED dt — the gesture clock) }.
+ *
+ * `clock` exists because `now` cannot be trusted for HUMAN timing windows:
+ * rAF timestamps are the compositor's frame clock, and under throttling
+ * (occluded window, headless BeginFrame control, software rendering) they lag
+ * wall time by 100s of ms to SECONDS (measured 0.3–5.8s, 2026-07-17) — and
+ * event.timeStamp does NOT lag, so any `now − eventTs` mixes two clocks and
+ * tap/long-press windows evaluate garbage. `clock` is monotonic, advances by
+ * the clamped dt each frame (a 640ms stall counts 64ms — the 2026-07-12
+ * "stall must not eat the window" intent), and is never compared against
+ * event timestamps.
+ */
 export declare const FrameInfo: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
     readonly tick: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
     readonly dt: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
     readonly now: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly clock: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
 }>, {
     readonly tick: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
     readonly dt: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
     readonly now: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly clock: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
 }>;
 /**
  * Advance the frame clock. First frame gets dt 0 (no previous `now` to diff

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

@@ -20,8 +20,11 @@
  */
 import type { Entity, World } from "@vibecook/strata-ecs";
 import { type Engine } from "../engine/engine";
+import type { FrameControl } from "../engine/frame-control";
 import { type InteractionStack } from "../interaction/install";
-import { type NestedCanvas } from "../nav/nested-canvas";
+import { type NavOpts, type NestedCanvas } from "../nav/nested-canvas";
+import { type ArrangeOpts } from "../ops/arrange";
+import { type InsertByDragOpts } from "../ops/insert";
 import { type WidgetRuntime } from "../widget/mount-store";
 import { type SpawnWidgetOpts } from "../widget/spawn";
 import { type Tool } from "../tools/define-tool";
@@ -29,6 +32,7 @@ import { type DocSession, type DocSessionOpts, type OpenDocResult } from "../doc
 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 PresenceSession } from "../presence/presence-kit";
 import type { MeasureQueue } from "../input/measure-queue";
 import { GESTURE_DEFAULTS, POINTER_DEFAULTS } from "../settings/defaults";
 export interface CanvasEngineOpts {
@@ -53,6 +57,10 @@ export interface CanvasEngineOpts {
             readonly enabled?: boolean;
             readonly thresholdPx?: number;
         };
+        /** Selection-chrome knobs: liftScale = the app's visual drag-lift scale (union box wraps it). */
+        readonly chrome?: {
+            readonly liftScale?: number;
+        };
     };
     readonly policy?: {
         /** The gate verdict a "migrate"-classified doc downgrades to when migration is off/fails. */
@@ -65,40 +73,96 @@ export interface CanvasOps {
     /** cancel active gestures → switch (design-003 §8; the strata-example lesson). */
     setTool(id: string): void;
     spawnWidget(type: string, opts: SpawnWidgetOpts): Entity;
+    /**
+     * Tray adoption (2026-07-19): DRAFT-spawn a runtime ghost of `type` centered
+     * under the pressing pointer and enqueue one synthetic down — the ordinary
+     * drag stack takes over (lift, snap, drop targets, folder consume). Release
+     * promotes it through ONE `create` tx (selected, one undo step); cancel or a
+     * rejected drop flies it back to the tray press point and despawns it with
+     * zero undo footprint. Call from the tray tile's `pointerdown` AFTER
+     * `stopPropagation()` (the down must not double-land via the adapter).
+     */
+    insertByDrag(type: string, opts: InsertByDragOpts): Entity;
+    /** Validated prop update: Standard-Schema-checked, json serialized, ONE tx (2026-07-13 review). */
+    setWidgetProps(entity: Entity, props: Readonly<Record<string, unknown>>): void;
     deleteSelection(): void;
     /** Twin spawns offset +16/+16; the clones become the selection. */
     duplicateSelection(): Entity[];
     setSelection(ids: readonly Entity[], mode?: "replace" | "add" | "toggle"): void;
     clearSelection(): void;
     selectAll(): void;
-    /** StackZ sweep, one tx: selection (or ids) to top/bottom. */
+    /** Sibling-sequence sweep, one tx: the ids to the frame top/bottom (petition 8). */
     reorder(ids: readonly Entity[], mode: "top" | "bottom"): void;
+    /**
+     * Desktop-style Clean Up (kernel packLayout): tidy reading-order rows, one
+     * undo step, 240ms glide (durationMs: 0 snaps). Scope: ids > selection ≥2 >
+     * current nav frame. Returns the movers (empty = already tidy).
+     */
+    arrange(opts?: ArrangeOpts): Entity[];
     zoomToFit(ids?: readonly Entity[]): void;
+    /**
+     * The natural DEFAULT framing (2026-07-18): zoom-to-fit the current
+     * frame's widgets inside the FIT_DEFAULTS band (never past 100%, never
+     * below 50%, ∩ settings.zoom) — same band as the folder arrival camera.
+     * Returns false (camera untouched) until a real viewport AND content
+     * exist, so boot code can retry. zoomToFit stays the uncapped explicit
+     * "show me everything".
+     */
+    frameContent(): boolean;
     zoomTo(zoom: number, anchor?: {
         x: number;
         y: number;
     }): void;
     panTo(x: number, y: number): void;
-    enterContainer(container: Entity): void;
-    exitContainer(): void;
+    enterContainer(container: Entity, opts?: NavOpts): void;
+    exitContainer(opts?: NavOpts): void;
+    /** Pop several levels in ONE transition (breadcrumb jumps; design-006 §5). */
+    exitTo(targetDepth: number, opts?: NavOpts): void;
     cancelActiveGestures(): void;
 }
 export interface CanvasDocs {
     create(opts?: DocSessionOpts): DocSession;
     open(bytes: Uint8Array, opts?: DocSessionOpts): OpenDocResult;
-    /** §6.5 bootstrap + optional presence sugar over the same channel. */
-    join(channel: ByteChannel, opts?: Omit<JoinDocOpts, "presence"> & {
+    /**
+     * §6.5 bootstrap + optional presence sugar over the same channel. `signal`/
+     * `onSession` are facade-owned (supersede + re-bootstrap wiring) — track the
+     * live session through `docs.current()`. Rejects if another document is
+     * opened while the join is in flight.
+     */
+    join(channel: ByteChannel, opts?: Omit<JoinDocOpts, "presence" | "signal" | "onSession"> & {
         readonly presence?: {
             name: string;
             color: string;
         };
     }): Promise<JoinResult>;
     current(): DocSession | undefined;
+    /**
+     * The live presence session (the `join({presence})` sugar's attachment), or
+     * undefined when doc-less / presence-less. An INSPECTION seam — the devtools
+     * dock's ephemeral tab reads `presence().eph` (DevtoolsOpts.presence) —
+     * never a sync path; same contract as `DocSession.attachment`. Swaps with
+     * the doc lifecycle exactly like `current()`: set by join, cleared by close.
+     */
+    presence(): PresenceSession | undefined;
     close(): void;
     undo(): boolean;
     redo(): boolean;
     autosave(storage: AutosaveStorageWrite, opts?: Omit<AutosaveOpts, "storage" | "world">): Autosave;
 }
+/**
+ * Stage presentation control (StageMode resource, 2026-07-19): app chrome
+ * that covers/recedes the canvas takes a refcounted, NAMED background hold —
+ * the disposer pattern makes overlay lifecycles leak-proof (release on
+ * unmount), the name makes "why isn't the canvas animating?" answerable.
+ * Rendering policy only — input/interactability stays the overlay's concern.
+ */
+export interface StageControl {
+    /** Take a named background hold. Returns an IDEMPOTENT release. */
+    background(name: string): () => void;
+    isBackgrounded(): boolean;
+    /** Live hold names, in take order (debug/devtools). */
+    holds(): readonly string[];
+}
 export interface CanvasEngine {
     readonly world: World;
     readonly engine: Engine;
@@ -109,6 +173,15 @@ export interface CanvasEngine {
     readonly nav: NestedCanvas;
     readonly ops: CanvasOps;
     readonly docs: CanvasDocs;
+    readonly stage: StageControl;
+    /**
+     * The frame gate (2026-08-04) — `stage`'s stricter sibling. A background
+     * hold is presentation policy over a LIVE world; a freeze stops the host
+     * loop outright. Reach for `stage` when chrome RECEDES the canvas, `frame`
+     * when chrome COVERS it. Passthrough of `engine.frame`, so there is one gate
+     * whether you hold the facade or the raw engine.
+     */
+    readonly frame: FrameControl;
     readonly budgets: {
         readonly keepMounted: number;
         readonly fboBytes: number;

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

@@ -11,7 +11,7 @@
  * Tags are not eligibility-checked in M2 (essential tags spawn with the
  * prefab; optional-tag modeling is future work — documented).
  */
-import type { Component, Entity, Relation, Resource, Tag, World } from "@vibecook/strata-ecs";
+import type { Component, Entity, OrderPlace, Relation, Resource, Tag, World } from "@vibecook/strata-ecs";
 import type { Mutator } from "@vibecook/strata-ecs/durable";
 import { type ComponentInit, type Prefab } from "../schema/prefab";
 export interface GuardedTx {
@@ -26,9 +26,11 @@ export interface GuardedTx {
     };
     addTag(e: Entity, t: Tag): void;
     removeTag(e: Entity, t: Tag): void;
-    setRelation(e: Entity, r: Relation, target: Entity): void;
+    setRelation(e: Entity, r: Relation, target: Entity, place?: OrderPlace): void;
     addRelation(e: Entity, r: Relation, target: Entity): void;
     removeRelation(e: Entity, r: Relation, target?: Entity): void;
+    /** Reorder within the current parent's sibling sequence — ordered relations only (petition 8). */
+    moveRelation(e: Entity, r: Relation, place: OrderPlace): void;
     setResource<S>(res: Resource<S>, v: S): void;
 }
 interface GuardedEditor {

package/dist/types/packages/core/src/helpers/churn-guard.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Churn guard — the `runIf` half of the petition-7 gating pattern
+ * (design-002 §4 "guards live in runIf, never the body" × strata 0.7.0
+ * `world.changes`).
+ *
+ * `activeMembership` gates by draining a collector INSIDE its tick body
+ * (legal there: it declares no writes, so an early-out stamps nothing).
+ * Systems that DECLARE `access.write` cannot use that shape — strata
+ * blanket-stamps declared writes for any system that RUNS, even one that
+ * early-outs (see helpers/version-stamps.ts) — so their gate must be a real
+ * `runIf`. But a naive collector-in-runIf would LOSE the drained delta when
+ * the body runs: this guard drains in `runIf`, stashes the delta, and hands
+ * it to the body via `take()` in the same frame.
+ *
+ * Contract:
+ *  - `runIf` drains the collector every frame (collector creation is lazy —
+ *    a guard whose system is never installed never journals) and evaluates
+ *    the optional `extra` trigger (a value-compare closure, e.g. "camera
+ *    zoom changed"; it is called every frame so it can keep its own cache
+ *    current). Returns true iff there is work.
+ *  - `take()` (body, same frame) returns the work: `full` means rebuild
+ *    everything (first run, `world.reset`, coarse writes, or `extra` fired);
+ *    otherwise `changed`/`removed` are the journaled entities. The arrays
+ *    alias the collector's internal buffers — valid until the next drain,
+ *    i.e. for the body that runs this frame; do not retain them.
+ */
+import type { CollectOptions, Entity, World } from "@vibecook/strata-ecs";
+export interface ChurnWork {
+    /** Rebuild everything: first run, reset, coarse writes, or `extra` fired. */
+    readonly full: boolean;
+    readonly changed: readonly Entity[];
+    readonly removed: readonly Entity[];
+}
+export interface ChurnGuard {
+    /** Drop into a system's `runIf`. */
+    readonly runIf: () => boolean;
+    /** The work stashed by this frame's `runIf` (undefined if it returned false). */
+    take(): ChurnWork | undefined;
+}
+export declare function makeChurnGuard(world: World, collect: CollectOptions, extra?: () => boolean): ChurnGuard;

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

@@ -3,10 +3,10 @@
  * scene systems · doc kit · publish step · engine facade · reflector registry.
  * Import wall: strata-ecs + @ice/kernel ONLY — never react/dom/three (enforced).
  */
-export declare const CORE_VERSION = "0.0.0";
+export declare const CORE_VERSION = "0.1.0";
 export { defineSchemaOnce, hmrInvalidateOnSchemaChange } from "./boot/hmr";
 export { All, Any, Not, Related, createWorld, defineQuery, defineSystem, defineTickSystem, enumOf, field, Local, } from "@vibecook/strata-ecs";
-export type { Batch, Component, Condition, Entity, Pipeline, Query, Relation, Resource, System, SystemCtx, Tag, TickSystem, World, } from "@vibecook/strata-ecs";
+export type { Batch, Component, Condition, Entity, OrderPlace, Pipeline, Query, Relation, Resource, System, SystemCtx, Tag, TickSystem, World, } from "@vibecook/strata-ecs";
 export { defineComponent, defineRelation, defineResource, defineTag, schemaMeta, type ComponentMeta, type RawSchema, type RelationMeta, type ResourceMeta, } from "./schema/meta";
 export { definePrefab, init, PrefabId, prefabs, type ComponentInit, type FieldWrite, type Prefab, type PrefabClass, type PrefabDef, } from "./schema/prefab";
 export { instantiate, type EphSpawner, type SpawnTarget } from "./engine/instantiate";
@@ -14,6 +14,7 @@ export { FrameInfo, setFrameInfo } from "./engine/frame-info";
 export { createPipelineRegistry, PHASE_GROUPS, type AnySystem, type PhaseGroup, type PipelineRegistry } from "./engine/pipeline";
 export { createReflectorRegistry, type ReflectorDef, type ReflectorObserve, type ReflectorQuerySpec, type ReflectorRegistry, } from "./engine/reflectors";
 export { createEngine, type Engine, type EngineOpts, type FrameTelemetry, type PublishHook, type SystemRunRecord, } from "./engine/engine";
+export { createFrameControl, SETTLE_CAP, type FrameControl } from "./engine/frame-control";
 export { devGuardsEnabled, setDevGuards } from "./guards/dev";
 export { createLiveWriter, type LiveWriter, type LiveWriterOpts } from "./guards/live-writer";
 export { guardedTransaction, type GuardedTx, type GuardedTxOpts } from "./guards/guarded-tx";
@@ -21,14 +22,18 @@ export { writeRuntimeResource } from "./guards/resource-writer";
 export * from "./catalog";
 export * from "./helpers/phase-set";
 export * from "./helpers/version-stamps";
+export * from "./ops/arrange";
 export * from "./ops/selection";
 export * from "./ops/cascade";
 export * from "./ops/claims";
 export * from "./ops/gestures";
 export * from "./ops/point-pick";
+export * from "./ops/sibling-order";
+export { portSlots, portSlotOf } from "./ops/port-geometry";
 export { createInputQueue, NO_MODS, type InputEvent, type InputEventKind, type InputMods, type InputQueue } from "./input/queue";
-export { createRecordingCommitSink, type CommitIntent, type CommitCreate, type CommitReparent, type CommitSink, type CommitWrite, } from "./engine/commit-sink";
+export { createRecordingCommitSink, type CommitIntent, type CommitCreate, type CommitOrder, type CommitReparent, type CommitSink, type CommitWrite, } from "./engine/commit-sink";
 export { ensureCanvasSurface, installInteractionCore, installInteractionStack, type InteractionCore, type InteractionCoreOpts, type InteractionStack, } from "./interaction/install";
+export { anyGestureNonTerminal, isMidGesture } from "./interaction/gesture-status";
 export type { MarqueeBuffer } from "./systems/l3-marquee";
 export { DEFAULT_SPAWN_PROFILES, type SingleKindName, type SpawnProfiles } from "./systems/l2-recognize";
 export { createCursorSync } from "./systems/l4-cursor";
@@ -45,19 +50,22 @@ export { runMigrations, type MigrationCtx, type MigrationOutcome } from "./doc/m
 export { p, type JsonShape, type PropSpec, type PropsDecl, type StandardSchemaV1 } from "./widget/props";
 export { WidgetEquipped, defineWidget, widgets, type SizeMode, type WidgetDef, type WidgetGroup, type WidgetInteraction, type WidgetPortDecl, type WidgetSurface, type WidgetType, } from "./widget/define-widget";
 export { createWidgetEquipSystem } from "./widget/equip";
-export { spawnWidget, widgetSpawnInits, type SpawnWidgetOpts } from "./widget/spawn";
+export { attachSpawnParent, spawnWidget, widgetSpawnInits, type SpawnWidgetOpts } from "./widget/spawn";
+export { setWidgetProps } from "./widget/set-props";
 export { createWidgetRuntime, installWidgetRuntime, type MountEntry, type WidgetMountStore, type WidgetRuntime, } from "./widget/mount-store";
 export * from "./settings/defaults";
+export * from "./settings/ground-config";
 export { CameraInertia, createCameraSystems, type CameraSystems } from "./systems/camera-sim";
 export { restoreAutosave, startAutosave, type Autosave, type AutosaveOpts, type AutosaveState, type AutosaveStatus, type AutosaveStorageRead, type AutosaveStorageWrite, type CancelScheduled, type RestoreResult, } from "./doc/autosave";
 export { attachBroadcastRelay, type BroadcastRelay, type BroadcastRelayOpts, type RelayChannel, } from "./doc/broadcast-relay";
 export { createMeasureQueue, type MeasureEvent, type MeasureQueue } from "./input/measure-queue";
 export { createMeasureIngest } from "./systems/measure-ingest";
 export { createBreakpointSystem, createSelectionChromeSystem } from "./systems/chrome";
-export { createNestedCanvas, currentNavEntry, currentNavFrame, type NestedCanvas, type NestedCanvasOpts, } from "./nav/nested-canvas";
+export { createActiveMembership, createNestedCanvas, currentNavEntry, currentNavFrame, type NavOpts, type NestedCanvas, type NestedCanvasOpts, } from "./nav/nested-canvas";
+export { abortNavFlight, createNavFlight, navFlightActive, NavTransition, startNavFlight, } from "./systems/nav-flight";
 export { attachPresence, createPresencePublish, createRemoteCursorsSystem, DEFAULT_PRESENCE_TTL_MS, installPresence, type InstallPresenceOpts, type PresenceOpts, type PresencePublishOpts, type PresenceSession, } from "./presence";
-export { joinDoc, type BootstrapClock, type JoinDocOpts, type JoinResult, } from "./doc/bootstrap";
+export { joinDoc, offerBase, type BootstrapClock, type JoinDocOpts, type JoinResult, } from "./doc/bootstrap";
 export { broadcastChannelByteChannel, webSocketByteChannel, type ByteChannel, type OwnedByteChannel, type WebSocketLike, } from "./doc/channels";
 export { createDrawTool, defineTool, tools, type CanvasDragRoute, type Tool, type ToolDef, type ToolGates, type ToolRoute, type WidgetDragRoute, } from "./tools/define-tool";
-export { createCanvasEngine, type CanvasDocs, type CanvasEngine, type CanvasEngineOpts, type CanvasOps, } from "./facade/create-canvas-engine";
+export { createCanvasEngine, type CanvasDocs, type CanvasEngine, type CanvasEngineOpts, type StageControl, type CanvasOps, } from "./facade/create-canvas-engine";
 export { createDrawBehavior } from "./systems/l3-draw";

package/dist/types/packages/core/src/input/queue.d.ts

@@ -40,6 +40,17 @@ export interface InputEvent {
     };
     /** GL-island opt-out (pinned widget-event contract, design-002 §8): fact still lands, recognizers skip. */
     readonly surfaceHandled?: boolean;
+    /**
+     * Hover-time widget-boundary fact (design-002 §8 amendment, 2026-07-18): the
+     * pointer is currently over content that would opt a down out — a native
+     * interactive / `[data-canvas-interactive]` (DOM) or claim-capable island
+     * content (GL). Stamped on down/move by adapters that track it; ABSENT means
+     * "no hover information this event" (wheel, key, blur-cancel) — ingest keeps
+     * the pointer's `OverInteractive` tag unchanged, it never treats absent as
+     * false. Presentation-grade truth (cursor affordances), never a gesture gate:
+     * recognizers keep reading `surfaceHandled`/`HandledByWidget` only.
+     */
+    readonly overInteractive?: boolean;
     /**
      * Event timestamp (DOMHighResTimeStamp — the same clock rAF hands
      * `engine.step`). Gesture timing anchors on THIS, not the processing frame:

package/dist/types/packages/core/src/interaction/gesture-status.d.ts

@@ -0,0 +1,13 @@
+import type { World } from "@vibecook/strata-ecs";
+/**
+ * Any recognizer NOT in a terminal phase ⇒ a gesture is in flight (mirrors the
+ * cleanup.ts terminal definition: Failed/Cancelled/Ended, plus Recognized-Tap).
+ */
+export declare function anyGestureNonTerminal(world: World): boolean;
+/**
+ * The full mid-interaction read: a live camera gesture (pan/zoom, which writes
+ * `Camera.gesturing` without a recognizer entity of its own) OR any recognizer
+ * still walking its phases. Either means runtime edits are outstanding and the
+ * durable transaction that will carry them has not been sealed yet.
+ */
+export declare function isMidGesture(world: World): boolean;

package/dist/types/packages/core/src/nav/nested-canvas.d.ts

@@ -7,10 +7,25 @@
  *   (at root: no container ancestor at all). Children of a deeper container
  *   are that container's content — not Active until you enter it.
  * - `activeMembership` (derive tick, before cull): recomputes membership and
- *   flips Active/Visible/Culled CHANGE-ONLY. A nav switch is O(frame
- *   content) tag flips — bounded, rare, migration-free. Boards without
- *   containers converge to "everything Active" on the first pass and never
- *   write again (M3–M7 demos unaffected).
+ *   flips Active/Visible/Culled CHANGE-ONLY, gated per design-004 §7
+ *   (`runIf: nav-change ∨ ChildOf churn`) as a drain-and-early-return tick
+ *   body — the spatialSync shape (petition 7 ChangeCollector; a `runIf`
+ *   cannot drain, and this system declares no writes so an early-out
+ *   blanket-stamps nothing). Idle frames cost one drain + one nav compare.
+ *   Full resweeps run on seed / reset / coarse / NAV CHANGE / container
+ *   despawn; everything else is delta-driven: a journaled entity whose
+ *   membership INPUTS (ChildOf edge, Container-ness) are unchanged is
+ *   skipped (drag frames journal Position every tick — O(1) each), a real
+ *   reparent/container-flip reclassifies its re-anchored subtree.
+ *   MEMBERSHIP-CHURN SIGNAL (why Position is the reparent proxy): relations
+ *   are not collector-journalable (strata CollectOptions = components +
+ *   tags), but coordinates are FRAME-LOCAL (design-001 §5.1) — a reparent
+ *   that does not rewrite Position into the new frame's space is already a
+ *   bug, and every real path co-writes: the doc sink commits reparent +
+ *   Position in ONE tx (doc-commit-sink.ts), and undo/redo/remote imports
+ *   project both rows of that tx. A bare runtime `world.setRelation(e,
+ *   ChildOf, …)` with no Position write on a pre-existing entity is OUTSIDE
+ *   the contract and goes stale until the next resweep.
  * - Nav stack = SESSION entities: `NavEntry` rows carry NavDepth + NavCamera
  *   (the camera to restore on exit) + NavFrame(entry→container). Root =
  *   empty stack. Current frame = deepest live entry's NavFrame target.
@@ -23,11 +38,20 @@
  *   container died (undo/remote — NavFrame edge auto-cleared), pop to the
  *   nearest LIVE ancestor entry (skipping dead ones) or root, restore that
  *   camera, rebuild. The recognizer-integrity pattern applied to nav.
- * - Camera memory: enter saves the live camera on the pushed entry
- *   (NavCamera) and applies the container's `ContainerCamera` rider (else
- *   zoom-to-fit over the frame's content, else identity); exit writes the
- *   rider back (per-user view memory; lost on undo-despawn — accepted) and
- *   restores the entry's NavCamera.
+ * - Camera policy (design-006, amending design-004 §7; James 2026-07-15):
+ *   enter saves the live camera on the pushed entry (NavCamera) and ALWAYS
+ *   lands on the DEFAULT framing — zoom-to-fit over the frame's content, else
+ *   identity. The `ContainerCamera` rider is neither read nor written by the
+ *   engine anymore (per-canvas view memory made re-entry unpredictable); the
+ *   component stays in the catalog for userland. Exit restores the entry's
+ *   NavCamera — "back where you came from" is the nav stack, not view memory.
+ * - Transitions (design-006 T1): with a live Viewport and `transition` not
+ *   "none", enter/exit CUT exactly as before and then FLY — the camera snaps
+ *   to the continuity-solved start and `navFlight` springs it to the arrival
+ *   (systems/nav-flight.ts). `exitTo(depth)` pops multi-level in ONE flight
+ *   through the composed portals (rebuilt from CURRENT container rects — a
+ *   collaborator may have moved a card). Headless (no Viewport) or opted-out
+ *   calls snap, preserving the pre-T1 behavior exactly.
  */
 import type { Entity, TickSystem, World } from "@vibecook/strata-ecs";
 import type { SpatialIndex } from "@ice/kernel";
@@ -35,11 +59,17 @@ import type { SpatialIndex } from "@ice/kernel";
 export declare function currentNavEntry(world: World): Entity | undefined;
 /** The container the user is inside, or undefined at root. */
 export declare function currentNavFrame(world: World): Entity | undefined;
+/** Per-op transition choice (design-006 §3.1); default is the portal zoom. */
+export interface NavOpts {
+    readonly transition?: "zoom" | "none";
+}
 export interface NestedCanvas {
     readonly activeMembership: TickSystem;
     readonly navIntegrity: TickSystem;
-    enterContainer(container: Entity): void;
-    exitContainer(): void;
+    enterContainer(container: Entity, opts?: NavOpts): void;
+    exitContainer(opts?: NavOpts): void;
+    /** Pop to `targetDepth` in ONE transition (breadcrumb jumps; design-006 §5). */
+    exitTo(targetDepth: number, opts?: NavOpts): void;
     /** Depth of the nav stack (0 = root). */
     depth(): number;
 }
@@ -57,6 +87,12 @@ export interface NestedCanvasOpts {
  * The membership stamper alone — installed by `installWidgetRuntime` (before
  * cull) so EVERY app partitions correctly, containers or not: a board with no
  * containers converges to all-Active on the first pass and never writes again.
+ *
+ * Gated per design-004 §7 (see the file header): the tick body drains a
+ * petition-7 collector and early-returns on idle frames; membership work runs
+ * only on nav change or membership-input churn. Baseline before this gate
+ * (bench/membership-scale.test.ts, 2026-07-15): the full scan cost 19.0 ms
+ * PER IDLE FRAME at 100k widgets nested 8 deep.
  */
 export declare function createActiveMembership(world: World): TickSystem;
 export declare function createNestedCanvas(world: World, opts: NestedCanvasOpts): NestedCanvas;

package/dist/types/packages/core/src/ops/arrange.d.ts

@@ -0,0 +1,15 @@
+import type { Entity, World } from "@vibecook/strata-ecs";
+import type { DurableStore } from "@vibecook/strata-ecs/durable";
+import type { LiveWriter } from "../guards/live-writer";
+export interface ArrangeOpts {
+    /** Explicit scope; wins over selection/frame resolution. */
+    readonly ids?: readonly Entity[];
+    /** Min separation between packed widgets (default 24). */
+    readonly gutter?: number;
+    /** Row wrap width; default = packLayout's near-square derivation. */
+    readonly maxWidth?: number;
+    /** Glide duration; 0 snaps instantly (tests/headless). Default 240ms. */
+    readonly durationMs?: number;
+}
+/** Returns the entities that actually moved (empty = already tidy). */
+export declare function arrangeWidgets(store: DurableStore, liveWriter: LiveWriter, world: World, opts?: ArrangeOpts): Entity[];

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

@@ -0,0 +1,62 @@
+/**
+ * insertByDrag — the tray-adoption op (2026-07-19, James: the widget tray).
+ *
+ * Called from the app's tray-tile `pointerdown` (which `stopPropagation`s the
+ * native down — the sanctioned widget-content boundary, design-002 §8). Two
+ * event-time moves, then the ENGINE owns everything:
+ *
+ *  1. DRAFT-spawn the ghost (design-001 §3; instantiate `{ draft: true }`) —
+ *     a runtime instance of the widget prefab centered under the pointer,
+ *     equipped + Active + top-of-frame IMMEDIATELY (the equip system runs in
+ *     `derive`, AFTER this tick's pick — the down below must find the ghost
+ *     indexed and topmost in the SAME tick, so the op stamps what equip
+ *     would). Two capability tags are deliberately withheld:
+ *     - `LongPressDrag`: a tray insert is always instant-drag — nobody holds
+ *       500ms over a palette;
+ *     - `SweepsContained`: a comment ghost at the tray's world point must not
+ *       sweep the widgets resting under the tray into the insert.
+ *     The projected twin gets the FULL tag set from the equip system.
+ *
+ *  2. Enqueue ONE synthetic un-flagged `down` (Law 2 — this op is an adapter
+ *     here, it only enqueues; the GL router precedent). Next tick: spatialSync
+ *     indexes the ghost, targeting resolves it topmost, the Drag recognizer
+ *     captures it — and the ordinary L0–L4 stack runs the whole drag: lift,
+ *     snap, drop targets, folder consume. moveBehavior's ghost terminals
+ *     promote (one `create` tx) or fly the ghost home and reap it.
+ */
+import type { Entity, World } from "@vibecook/strata-ecs";
+import { type InputQueue } from "../input/queue";
+export interface InsertByDragOpts {
+    /** The press point in canvas-container CSS px (the kernel screen space). */
+    readonly screenX: number;
+    readonly screenY: number;
+    /** Prop overrides for the eventual create (validated by widgetSpawnInits). */
+    readonly props?: Readonly<Record<string, unknown>>;
+    /** Adapter pointer id of the pressing pointer (default "mouse"). */
+    readonly pointerId?: string;
+    readonly device?: "mouse" | "touch" | "pen";
+    /** PointerEvent.buttons at the press (default 1 = primary). */
+    readonly buttons?: number;
+    /**
+     * Fly-back HOME in screen px (default: the press point). Apps that adopt
+     * the drag AWAY from the tray (the deferred-spawn proxy pattern — the ghost
+     * spawns at the tray-EXIT point) aim the cancel/reject return at the
+     * persistent chrome (the toolbar) instead of a spot in open canvas.
+     */
+    readonly home?: {
+        readonly x: number;
+        readonly y: number;
+    };
+    /**
+     * Proportional GRAB POINT (0–1 within the widget rect; default center).
+     * The grab point is the drag's INVARIANT (2026-07-19 polish): the spot
+     * under the finger in the tray tile stays the same spot of the spawned
+     * widget — the proxy→widget morph then composes as a pure scale about the
+     * cursor, with no re-anchoring snap.
+     */
+    readonly anchor?: {
+        readonly u: number;
+        readonly v: number;
+    };
+}
+export declare function insertByDrag(world: World, queue: InputQueue, type: string, opts: InsertByDragOpts): Entity;