@vibecook/ice 0.1.0 → 0.2.0

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

@@ -21,7 +21,9 @@
 import type { Entity, World } from "@vibecook/strata-ecs";
 import { type Engine } from "../engine/engine";
 import { type InteractionStack } from "../interaction/install";
-import { type NestedCanvas } from "../nav/nested-canvas";
+import { type 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 +31,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 +56,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 +72,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 +172,7 @@ export interface CanvasEngine {
     readonly nav: NestedCanvas;
     readonly ops: CanvasOps;
     readonly docs: CanvasDocs;
+    readonly stage: StageControl;
     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";
@@ -21,13 +21,16 @@ 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 type { MarqueeBuffer } from "./systems/l3-marquee";
 export { DEFAULT_SPAWN_PROFILES, type SingleKindName, type SpawnProfiles } from "./systems/l2-recognize";
@@ -45,19 +48,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/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;

package/dist/types/packages/core/src/ops/point-pick.d.ts

@@ -6,11 +6,13 @@
  * the tick are verified-unrestricted). One implementation so the two can
  * never disagree on ordering.
  *
- * Priority: HandleSpec chrome first (nearest edge), then widgets by StackZ
- * descending. Deliberately NOT plane-stratified: cross-plane z is stratified
- * visually (P2 GL composites above P1 DOM), but pick order is StackZ across
- * all surfaces — design-004 §1 names the mixed-overlap consequence and
- * accepts it; do not "fix" it here.
+ * Priority: HandleSpec chrome first (nearest edge), then widgets topmost by
+ * SIBLING ORDER (petition 8: the frame parent's ChildOf sequence, legacy
+ * (StackZ, entity) fallback for edge-less entities — compareStackOrder is the
+ * ONE comparator paint and pick share). Deliberately NOT plane-stratified:
+ * cross-plane z is stratified visually (P2 GL composites above P1 DOM), but
+ * pick order is sibling order across all surfaces — design-004 §1 names the
+ * mixed-overlap consequence and accepts it; do not "fix" it here.
  */
 import type { Component, Entity } from "@vibecook/strata-ecs";
 import type { Cubic, SpatialIndex } from "@ice/kernel";
@@ -33,10 +35,12 @@ export declare function distPointToBox(px: number, py: number, minX: number, min
  * Top pick under a world point within `rWorld` (point-in-box when 0).
  * Tier order (design-003 §3, amended for M8): HandleSpec chrome → PORT
  * entities (interaction affordances sit atop their widget edge) → widgets by
- * StackZ → WIRES (render in P0 under content; pick below widgets, above
+ * sibling order (topmost = compareStackOrder max; `ordinals` is the caller's
+ * frame ordinal map — SiblingOrderIndex — so paint and pick share one order)
+ * → WIRES (render in P0 under content; pick below widgets, above
  * canvas — render order and pick order agree). The canvas fallback stays the
  * caller's. Wires narrow-phase against their cached cubic (`wires` source;
  * without one, wire entries are skipped — coarse AABB hits would make fat
  * bounding boxes steal canvas taps).
  */
-export declare function pickTopAt(reader: PickReader, index: SpatialIndex<Entity>, wx: number, wy: number, rWorld: number, wires?: WirePickSource): Entity | undefined;
+export declare function pickTopAt(reader: PickReader, index: SpatialIndex<Entity>, wx: number, wy: number, rWorld: number, wires?: WirePickSource, ordinals?: ReadonlyMap<Entity, number>): Entity | undefined;

package/dist/types/packages/core/src/ops/sibling-order.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Sibling order — THE per-frame stacking source (petition 8; design-004 §1
+ * amendment). Within a frame, paint/pick/drop order IS the frame parent's
+ * ordered `ChildOf` sibling sequence: index 0 paints first (bottom), the tail
+ * paints last (top). The frame parent is `currentNavFrame(world) ?? BoardRoot`
+ * — every renderer/pick consumer shares this module so the orders can never
+ * diverge (the point-pick lesson, extended to the comparator).
+ *
+ * LEGACY FALLBACK (must keep working): when the `BoardRoot` resource is absent
+ * (a pre-schema-2 doc opened read-only, or a doc-less runtime world) OR an
+ * entity carries no `ChildOf` edge (bare runtime spawns), stacking falls back
+ * to the legacy `(StackZ.z asc, entity asc)` comparator. This module is the
+ * ONLY sanctioned StackZ reader outside the schema migration.
+ *
+ * Mixed frames — some entities ordinal-mapped, some fallback — are nominally
+ * impossible (the 1→2 migration hangs an edge on every durable widget, and a
+ * pre-schema-2 read-only doc has no BoardRoot at all, so it is all-fallback).
+ * The comparator still totals them: ordinal-mapped entities sort BELOW the
+ * fallback set (ordinals first in paint order), each group internally ordered
+ * by its own rule — documented so a stray bare spawn lands somewhere stable
+ * rather than somewhere random.
+ *
+ * Invalidation is PULL-ONLY, the strata 0.8.0 contract: `world.orderStamp
+ * (parent, ChildOf)` is a monotonic per-parent version consumers poll after a
+ * reactive wake; the wake itself is an `observeQuery` whose grammar names the
+ * relation (`Related(ChildOf)` — pure reorders turn it over).
+ */
+import type { Component, Entity, World } from "@vibecook/strata-ecs";
+/** Structural read both `World` and `SystemCtx` provide — all the comparator needs. */
+export interface StackOrderReader {
+    get<S>(e: Entity, c: Component<S>): S | undefined;
+}
+/**
+ * The frame parent — the entity whose `ChildOf` sibling sequence is the
+ * current frame's stacking order: the nav frame when inside a container, else
+ * the document's board root. `undefined` = a legacy world (pre-schema-2
+ * read-only doc / doc-less runtime) — everything is fallback-ordered.
+ */
+export declare function frameParent(world: World): Entity | undefined;
+/** `parent`'s sibling sequence as entity → position (the renderers' sort key). */
+export declare function buildOrdinals(world: World, parent: Entity): Map<Entity, number>;
+/**
+ * THE stacking comparator (ascending = paint order; the pick tier takes the
+ * max). Ordinal-mapped entities order by sibling position; entities missing
+ * from the map use the legacy `(StackZ asc, entity asc)` fallback among
+ * themselves and sort ABOVE the ordinal-mapped set (see the header note on
+ * nominally-impossible mixed frames).
+ */
+export declare function compareStackOrder(reader: StackOrderReader, ordinals: ReadonlyMap<Entity, number>, a: Entity, b: Entity): number;
+export interface SiblingOrderIndex {
+    /** The frame parent backing the current ordinal map (undefined = legacy world). */
+    parent(): Entity | undefined;
+    /** The stamp-checked ordinal map — rebuilt only when the frame parent or its `orderStamp` moved. */
+    ordinals(): ReadonlyMap<Entity, number>;
+    /** True when the next `ordinals()` would rebuild (cheap pull; no rebuild). */
+    stale(): boolean;
+    /**
+     * Arm the reorder wake: an `observeQuery` naming `ChildOf` (`Related`
+     * grammar — pure reorders and edge turnover both fire it). Callers pair it
+     * with `stale()`/`ordinals()` so other-frame churn stays a no-op.
+     */
+    observe(cb: () => void): () => void;
+}
+/**
+ * A pull-based ordinal cache over the CURRENT frame parent's sibling sequence.
+ * Consumers each hold their own instance (the cache is a cheap `getReverse`
+ * walk); correctness is shared through {@link compareStackOrder} and the
+ * stamp, never through instance identity.
+ */
+export declare function createSiblingOrderIndex(world: World): SiblingOrderIndex;

package/dist/types/packages/core/src/schema/meta.d.ts

@@ -31,6 +31,7 @@ export declare function defineComponent<const Sch extends RawSchema>(name: strin
 export declare function defineTag(name: string): Tag;
 export declare function defineRelation(name: string, opts?: {
     arity?: "one" | "many";
+    ordered?: boolean;
 }): Relation;
 export declare function defineResource<const Sch extends RawSchema>(name: string, schema: Sch, opts?: {
     durable?: boolean;

package/dist/types/packages/core/src/settings/defaults.d.ts

@@ -15,6 +15,8 @@ export declare const GESTURE_DEFAULTS: {
     readonly inertiaDecayMs: 325;
     readonly multiTapWindowMs: 280;
     readonly multiTapSlopPx: 20;
+    readonly wheelZoomSensitivity: 0.01;
+    readonly wheelZoomMaxStep: 10;
 };
 /** Pick radii + retarget dead-band (design-003 §3 L1 targeting). */
 export declare const POINTER_DEFAULTS: {
@@ -39,12 +41,55 @@ export declare const SNAP_DEFAULTS: {
     readonly enabled: true;
     readonly thresholdPx: 5;
 };
+/**
+ * Selection-chrome knobs (2026-07-17). `liftScale` mirrors the app's visual
+ * drag-lift scale (widgetlab CardShell: 1.05) so the union box can inflate a
+ * grabbed member's rect and keep WRAPPING the card it sees; 1 = no lift
+ * visual, no inflation.
+ */
+export declare const CHROME_DEFAULTS: {
+    readonly liftScale: 1;
+};
 /** Zoom clamp (design-003 §5 item 9 cameraControl) and frame dt clamp (design-002 §1). */
 export declare const CAMERA_DEFAULTS: {
     readonly minZoom: 0.1;
     readonly maxZoom: 5;
     readonly dtClampMs: 64;
 };
+/**
+ * The natural auto-framing band (2026-07-18, James: "not super zoomed in
+ * nor super zoomed out, should feel natural"): every DEFAULT framing —
+ * `ops.frameContent` at boot, the folder arrival camera, and the folder
+ * minis' portal affine (widgetlab keeps its preview in lockstep) — fits
+ * content via kernel `fitCamera` but never lands outside
+ * [fitMinZoom, fitMaxZoom], intersected with the session's hard
+ * CameraLimits. `ops.zoomToFit` stays UNCAPPED: an explicit "show me
+ * everything" beats natural.
+ */
+export declare const FIT_DEFAULTS: {
+    readonly pad: 80;
+    readonly minZoom: 0.5;
+    readonly maxZoom: 1;
+};
+/**
+ * Nav-transition motion constants (design-006 §4/§5, tuned in the approved
+ * 2026-07-15 mock). `responseMs` is the critically-damped spring response for
+ * ENTER; exit runs at `exitResponseFactor ×` (returning is lighter). Response
+ * scales `durationPerOctave` per zoom-octave beyond `baseOctaves` (Apple's
+ * duration-with-distance). Beyond `freezeOctaves` a flight cannot be presented
+ * geometrically (Chromium raster-scale swing — design-006 §5): the start depth
+ * caps at `capFactor ×` arrival and the transition presents as a crossfade.
+ */
+export declare const NAV_TRANSITION_DEFAULTS: {
+    readonly responseMs: 420;
+    readonly exitResponseFactor: 0.8;
+    readonly durationPerOctave: 0.12;
+    readonly baseOctaves: 3.5;
+    readonly freezeOctaves: 4.2;
+    readonly capFactor: 10;
+    readonly settleP: 0.999;
+    readonly settleV: 0.02;
+};
 /** Widget/FBO/port budgets (design-004 §2 host pipeline, §3 FBO pool, §6 port materialization; ported into design-005 §4 engine facade). */
 export declare const RUNTIME_BUDGETS: {
     readonly keepMountedWidgets: 256;