@vibecook/ice 0.1.0 → 0.2.0

package/dist/types/packages/core/src/settings/ground-config.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Ground-layer (P0) pass configs — CANONICAL home (2026-07-16, the @ice/ground
+ * extraction): plain data shared by the ground renderer, the react facade's
+ * `grid` prop, and apps. They live in core because core is the vocabulary
+ * package every layer may import (ground cannot import react; react cannot
+ * import ground — design-002 §6). Values are verbatim from the original
+ * renderers: GridConfig from v1 GridRenderer.ts:5-35 (tuned to Apple
+ * Freeform / FigJam), wires + snap-guides from their 2026 dom reflectors.
+ */
+export interface GridConfig {
+    /** World-unit spacings for up to 3 grid levels [fine, medium, coarse]. */
+    spacings: [number, number, number];
+    /** Dot RGB color as [r, g, b] in 0-1 range. */
+    dotColor: [number, number, number];
+    /** Base dot opacity multiplier (0-1). */
+    dotAlpha: number;
+    /** CSS-pixel range where a grid level fades in: [start, end]. */
+    fadeIn: [number, number];
+    /** CSS-pixel range where a grid level fades out: [start, end]. */
+    fadeOut: [number, number];
+    /** Dot radius range in CSS pixels [min, max]. Scaled by DPR internally. */
+    dotRadius: [number, number];
+    /** Per-level opacity weight: level i gets (base + i * step). */
+    levelWeight: [number, number];
+}
+/** Verbatim from v1 GridRenderer.ts:27-35 (Apple Freeform / FigJam feel). */
+export declare const DEFAULT_GRID_CONFIG: GridConfig;
+/** Minimal-neutral wire styling (design-004 §6: chrome is subdued; wires defer to content). */
+export interface WiresConfig {
+    /** Default wire stroke (CSS color). */
+    wireColor: string;
+    /** Accent stroke for a Selected wire. */
+    selectedColor: string;
+    wireWidth: number;
+    selectedWidth: number;
+    /** Materialized-port dot radius (CSS px) + colors (idle vs during a connect drag). */
+    portRadius: number;
+    portColor: string;
+    portActiveColor: string;
+}
+export declare const DEFAULT_WIRES_CONFIG: WiresConfig;
+/** v1 `DEFAULT_SNAP_GUIDE_CONFIG` (SnapGuideRenderer.ts), field for field. */
+export interface SnapGuidesConfig {
+    /** Guide line + spacing bar color as [r, g, b] in 0-1 range. */
+    color: [number, number, number];
+    /** Stroke width in screen px (constant across zoom). */
+    lineWidth: number;
+    /** Alignment-line alpha. */
+    guideAlpha: number;
+    /** Equal-spacing bar alpha. */
+    spacingAlpha: number;
+    /** End-tick half-length in screen px (v1 shader barHeight). */
+    tickPx: number;
+}
+export declare const DEFAULT_SNAP_GUIDES_CONFIG: SnapGuidesConfig;

package/dist/types/packages/core/src/systems/chrome.d.ts

@@ -7,6 +7,10 @@
  *   `Selected` set: ONE selection-box entity + 8 resize-handle entities. The box
  *   entity carries ONLY the `SelectionBox` value (x,y,w,h = the union bbox); the
  *   handles carry Position + Size + `HandleSpec{anchor}` + `VisualOf → box`.
+ *   Box policy (amended 2026-07-17): all-resizable selections get box + grips
+ *   (v1 parity); a MULTI-selection gets the box (group bbox) even when
+ *   non-resizable; a single non-resizable widget gets no engine chrome (the
+ *   app owns its selection look).
  *
  *   HANDLE PICKING (the point of the design): handles carry a world AABB, so the
  *   `react`-phase `spatialSync` indexes them automatically and `picking` resolves
@@ -43,6 +47,6 @@
  *   measure loop converges (§2). The stored w,h are the effective size at the
  *   tier transition (what the tier "was computed from").
  */
-import type { System, TickSystem, World } from "@vibecook/strata-ecs";
+import type { TickSystem, World } from "@vibecook/strata-ecs";
 export declare function createSelectionChromeSystem(world: World): TickSystem;
-export declare function createBreakpointSystem(_world: World): System;
+export declare function createBreakpointSystem(world: World): TickSystem;

package/dist/types/packages/core/src/systems/insert-ghost.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The insert-ghost reap (cleanup phase; catalog/insert.ts, 2026-07-19).
+ *
+ * Three exits for a tray-insert ghost, all owned here so nothing transient
+ * crosses frames unaccounted (design-002 §2 cleanup law):
+ *
+ *  - PROMOTED (`GhostCommitted`, set by moveBehavior at the create commit):
+ *    despawned ONE tick after the commit — the projected twin lands at the
+ *    NEXT sync, so waiting one tick makes the swap happen inside a single
+ *    reflect flush (twin mounts, ghost unmounts, same frame — no blink).
+ *    Selection rides the same beat: the doc sink parked the twin ids in its
+ *    out-of-ECS hand-off (`drainCreatedSelections`); they are drained on the
+ *    commit tick and applied HERE one tick later, when the projection is
+ *    alive — the select-on-grab the ghost held transfers to the real widget.
+ *
+ *  - RETIRING (`GhostRetiring`, cancel / rejected drop): despawned when the
+ *    fly-back `TransformTween` lands (camera-sim removes it on arrival).
+ *
+ *  - STRANDED (no Grab, no tween, no live recognizer still capturing it): a
+ *    clean click on a tray tile (the drag never formed), or an integrity
+ *    cancel that raced the claim. Despawned silently — it never left the
+ *    press point under the tray.
+ */
+import type { System, World } from "@vibecook/strata-ecs";
+export declare function createInsertGhostReap(world: World): System;

package/dist/types/packages/core/src/systems/l1-pick.d.ts

@@ -5,13 +5,26 @@
  *
  * `spatialSync` maintains the kernel `SpatialIndex` over every Position+Size
  * entity (widgets AND HandleSpec chrome — both carry a world AABB). It is a
- * TICK system (strata 0.5.0) so the body runs EVERY frame — it is the writer
- * that bumps
- * `SpatialVersion`, and its own writes have no version stamp to gate on
- * (design-002 §4), so it must run eagerly and stays cheap via a private
- * last-known cache: an entity is re-`upsert`ed only when its AABB actually
- * changed, and a cache-sweep removes entries no longer matched (despawns, or a
- * lost Position/Size). Materialized ports are M8 — skipped.
+ * TICK system so the body runs every frame — it is the writer that bumps
+ * `SpatialVersion` — but as of strata 0.7.0 (petition 7 LANDED) the body is
+ * O(delta), not O(N): a `world.changes` collector journals exactly which
+ * entities were touched (Position/Size writes, Active/WidgetEquipped flips,
+ * spawns, destroys — same-frame, drained INSIDE the pipeline), and each is
+ * re-checked against `isIndexable` → upsert or remove. The 2026-07-13 walk
+ * machinery (last-known AABB cache, compare-and-skip, generation sweep) is
+ * RETIRED — the collector knows; the system no longer has to discover.
+ *
+ * The FULL WALK survives as exactly what petition 7 said it should be:
+ *  - the SEED (a collector only journals writes made after its creation);
+ *  - the `reset` route (world.reset / replace import / nav `clearCaches`);
+ *  - the `coarse` fallback (some declared-raw-write system touched
+ *    Position/Size rows the journal cannot attribute — rescan, never miss).
+ * Nav gating rides the walk QUERIES at archetype level: widgets match
+ * `[Position, Size, WidgetEquipped, Active]`, chrome matches
+ * `[Position, Size, Not(WidgetEquipped)]` — the union is exactly
+ * `Position+Size ∧ (¬WidgetEquipped ∨ Active)`, and `isIndexable` is the
+ * same predicate entity-wise for the delta path. Materialized ports are M8 —
+ * skipped.
  *
  * `picking` runs the dual pick (design-003 §3), gated by a version guard over
  * `PointerVersion ∨ SpatialVersion`. `CameraVersion` does not exist — camera
@@ -24,10 +37,11 @@
  *                      dead-band (hover is forgiving; hold the current target
  *                      while the pointer stays within its expanded bounds).
  *   - `TouchesExact` = r=0 point pick (grab is precise; no dead-band).
- * Pick priority is plane priority: HandleSpec chrome first, then widgets by
- * StackZ descending, then the CanvasSurface entity as the guaranteed fallback
- * (design-001 §4). Relations are written change-only (design-002 §4 hygiene).
- * Wires/ports are M8 — skipped.
+ * Pick priority is plane priority: HandleSpec chrome first, then widgets
+ * topmost by sibling order (petition 8 — the shared SiblingOrderIndex feeds
+ * pickTopAt, so pick can never diverge from paint), then the CanvasSurface
+ * entity as the guaranteed fallback (design-001 §4). Relations are written
+ * change-only (design-002 §4 hygiene). Wires/ports are M8 — skipped.
  */
 import type { Entity, System, TickSystem, World } from "@vibecook/strata-ecs";
 import { SpatialIndex } from "@ice/kernel";

package/dist/types/packages/core/src/systems/l2-recognize.d.ts

@@ -13,10 +13,16 @@
  *                the same frame); field updates are immediate `edit().set`
  *                under declared `access.write`.
  *
- * All timing reads FrameInfo.now (the engine clock); all thresholds read
- * the GestureSettings RESOURCE (live-tunable, design-005 §4) with the
- * GESTURE_DEFAULTS constants as the unset fallback. Gesture math is screen-space totals + zoom-at-claim — never
- * live PointerWorld (design-002 §2 staleness rule).
+ * All timing reads FrameInfo.CLOCK — the accumulated CLAMPED-dt gesture clock
+ * (2026-07-17, supersedes both raw FrameInfo.now and the 2026-07-12
+ * event-timestamp anchor): rAF `now` lags wall time by up to SECONDS under
+ * throttling/headless/software rendering while event.timeStamp does not, so
+ * any window mixing the two evaluates garbage; `clock` is monotonic, stalls
+ * contribute ≤ dtClampMs (the stall-protection intent), and no event
+ * timestamp ever enters window math. All thresholds read the GestureSettings
+ * RESOURCE (live-tunable, design-005 §4) with the GESTURE_DEFAULTS constants
+ * as the unset fallback. Gesture math is screen-space totals + zoom-at-claim
+ * — never live PointerWorld (design-002 §2 staleness rule).
  */
 import type { World } from "@vibecook/strata-ecs";
 import { type System } from "@vibecook/strata-ecs";

package/dist/types/packages/core/src/systems/l3-behave.d.ts

@@ -5,15 +5,17 @@
  * ctl:claim; per frame (persistent `Active`) apply ABSOLUTE live writes from
  * rider origins + gesture totals; on `JustEnded` emit ONE commit (through the
  * CommitSink seam — M5 swaps in the doc transaction); on `JustCancelled`
- * restore from riders — Position AND StackZ (a forgotten StackZ restore leaves
- * the cell diverged forever); remove riders and gesture-scoped edges on every
- * terminal path. Discrete actions edge-trigger on `Just*` markers only.
+ * restore from riders — Position AND sibling order (petition 8: a forgotten
+ * order restore leaves the sequence diverged forever, the old StackZ law);
+ * remove riders and gesture-scoped edges on every terminal path. Discrete
+ * actions edge-trigger on `Just*` markers only.
  *
  * Move outcome tree (design-003 §5.5, three-way via dropSystem's signals):
  *   DropTarget + OverlapCandidate on the container → CONSUME (reparent intent);
  *   DropTarget without OverlapCandidate → FLY-BACK (no commit; TransformTween
  *     rider per widget — the tween HOLDS the claim, design-001 §3 amended);
- *   no DropTarget → COMMIT (final Position + StackZ per live Drags edge).
+ *   no DropTarget → COMMIT (final Position per live Drags edge + the sibling
+ *     placement as ORDER ops, so one gesture stays one transaction).
  * Without dropSystem installed no DropTarget ever exists ⇒ plain commits.
  */
 import type { System, World } from "@vibecook/strata-ecs";

package/dist/types/packages/core/src/systems/l3-claim.d.ts

@@ -7,9 +7,13 @@
  * claim-frame `read(w, Grab)` throws (design-003 review C1).
  *
  * `moveClaim` (JustActive × RoutedMove): select-on-grab, `Drags` edges over the
- * dragged set, `Grab` per widget with the CURRENT Position/Size/StackZ embedded
- * in the command payload, and the StackZ elevate (an immediate value write —
- * part of the gesture divergence, restored from `Grab.z` on cancel).
+ * dragged set, `Grab` per widget with the CURRENT Position/Size + the ORDER
+ * MEMO embedded (petition 8: ChildOf parent, nearest non-dragged predecessor
+ * sibling, original sibling index), and the sibling elevate — `moveRelation(w,
+ * ChildOf, "last")`, frame-scoped, equivalent to the old global-top within the
+ * frame; part of the gesture divergence, restored from the memo on cancel.
+ * Edge-less widgets (legacy/runtime world) skip both memo and elevate — the
+ * move would be a strata no-op and there is no sequence to restore.
  *
  * `resizeClaim` (JustActive × RoutedResize): `Drags` + `Grab` over the Selected
  * ∧ Resizable set; the anchor lives on the captured handle's `HandleSpec` — no

package/dist/types/packages/core/src/systems/l3-drop.d.ts

@@ -3,7 +3,9 @@
  * AFTER moveBehavior so it tests POST-move bounds).
  *
  * For Active `RoutedMove` drags: spatial-query the dragged union bounds for
- * `Container` widgets (∉dragged), pick the topmost by StackZ, and publish two
+ * `Container` widgets (∉dragged), pick the topmost by sibling order (petition
+ * 8 — compareStackOrder, the SAME comparator pick/paint use, so the drop
+ * candidate can never diverge from what the user sees on top), and publish two
  * signals the move-outcome tree consumes (l3-behave §5.5):
  *   - `DropTarget(recognizer → container)` — set for the container under the
  *     bounds REGARDLESS of an accepts-match (so the outcome tree can distinguish

package/dist/types/packages/core/src/systems/l3-resize.d.ts

@@ -7,7 +7,9 @@
  * zoomAtClaim`, resized about the FIXED opposite edge/corner of the grabbed
  * handle (`n`/`s` height-only, `e`/`w` width-only, corners both). Modifiers ride
  * the watched pointer's `PointerMods`: `alt` = resize about center, `shift` =
- * preserve aspect (corner handles). Min size clamps to 1×1. `JustEnded` emits ONE
+ * preserve aspect (corner handles). Min size clamps to the target widget's
+ * `defineWidget` `minSize` (via `PrefabId`), or 1×1 for non-widget resizables.
+ * `JustEnded` emits ONE
  * `resize` commit (Position+Size per live target); `JustCancelled`/`JustFailed`
  * restore from `Grab`. Every terminal path removes `Grab` and the `Drags` edges
  * (mirrors l3-behave's clearGestureState; resize has no DropTarget).

package/dist/types/packages/core/src/systems/l3-snap.d.ts

@@ -6,14 +6,32 @@
  * over the dragged widgets — NEVER last-applied `Position` (one frame stale ⇒
  * guide-chasing oscillation, design-003 §5.2 red-team; `Grab` is readable here
  * thanks to the ctl:claim settle point, §4.5). Candidates come from the SHARED
- * spatial index (rect query = intended bounds expanded by threshold, filtered to
- * `SnapTarget ∧ ∉dragged`; Visible filtering waits for cull). Threshold is
+ * spatial index (rect query = intended bounds ∪ VIEWPORT, expanded by
+ * threshold — design-003 §5.2: a distant same-axis edge IN VIEW must
+ * contribute a guide, the Figma behavior; the widgetlab field check 2026-07-16
+ * caught the intended-rect-only query never seeing a card 115px above the
+ * drag). Filtered to `SnapTarget ∧ ¬Culled ∧ ∉dragged` — ¬Culled is the
+ * design's "Visible" scoping in cull-less rigs too (no cull system ⇒ nothing
+ * is Culled ⇒ all candidates pass). Threshold is
  * `thresholdPx / zoomAtClaim` (screen-constant). The kernel `computeSnapGuides`
  * does the Figma math; we write `SnapState{dx,dy}` on the recognizer (moveBehavior
- * adds it to the absolute write). Guide CHROME entities (`GuideLine`) are deferred
- * to the chrome-reflector milestone — SnapState only here. SnapState clears to 0,0
- * when snap is off / no source / no candidate.
+ * adds it to the absolute write). SnapState clears to 0,0 when snap is off / no
+ * source / no candidate.
+ *
+ * GUIDE CHROME (design-003 §6, as-built 2026-07-16 — the once-deferred half):
+ * the kernel result's `guides`/`spacings` become pooled runtime `GuideLine` /
+ * `SpacingBar` entities the P0 snap-guides reflector draws (design-004 §1
+ * amendment: ground stratum, under content — James's call). Pool mechanics
+ * mirror selectionChrome: a TICK system (exactly one pass per frame — spawn/
+ * destroy are not idempotent, and the pool must reap on the frame the last
+ * snapping drag ENDS, when the recognizer query is empty), `ctx.spawn` on
+ * grow, `ctx.destroy` on shrink, change-only `edit().set` in steady state
+ * (same guide held across frames ⇒ zero writes). Alignment guides write
+ * `from = to = 0` — the full-viewport sentinel (v1's full-canvas lines);
+ * spacing indicators flatten one entity per segment (v1 `u_spacings` parity).
+ * No silent caps: the pool grows to whatever the kernel returns (v1's
+ * MAX_GUIDES=16 truncation is banned).
  */
-import type { Entity, System, World } from "@vibecook/strata-ecs";
+import type { Entity, TickSystem, World } from "@vibecook/strata-ecs";
 import { type SpatialIndex } from "@ice/kernel";
-export declare function createSnapSystem(world: World, index: SpatialIndex<Entity>): System;
+export declare function createSnapSystem(world: World, index: SpatialIndex<Entity>): TickSystem;

package/dist/types/packages/core/src/systems/nav-flight.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Nav-flight — the T1 camera-flight half of design-006 (portal zoom).
+ *
+ * CUT-FIRST, THEN FLY (§3): the nav ops perform the ECS cut synchronously
+ * (frame switch, membership resweep, index rebuild) and then hand presentation
+ * to this slice — `startNavFlight` snaps the camera to the continuity-solved
+ * start `c0` and arms the `NavTransition` resource; the `navFlight` tick
+ * system (simulate, beside cameraInertia) advances a closed-form critically-
+ * damped progress spring each frame and writes the camera along the log-zoom
+ * path until rest. The transition is PURE PRESENTATION: killing it at any
+ * moment leaves a fully consistent world in the destination frame.
+ *
+ * - `NavTransition` is a RESOURCE, not closure state (the CameraInertia
+ *   pattern: devtools sees it, no hidden singleton — design-003 §9). Resources
+ *   cannot be removed, so `active` is the liveness flag; `epoch` bumps on
+ *   every (re)start so the T2 reflector can distinguish retarget from resume.
+ * - Camera writes are UNCLAMPED (design-006 §3.1): flight paths transit far
+ *   outside the user-gesture zoom band; only the ARRIVAL camera (clamped by
+ *   the nav op) bounds where the flight rests.
+ * - Gestures always win (§4): any active camera gesture — `Camera.gesturing`,
+ *   stamped by cameraControl in ctl:behave, i.e. EARLIER this same frame —
+ *   deactivates the flight without touching the camera.
+ * - The portal affine (`as/aox/aoy`, departed-frame → destination-frame) and
+ *   `frozen` ride the resource for T2's departing-plane reflector; T1's camera
+ *   math only needs c0/c1.
+ */
+import type { TickSystem, World } from "@vibecook/strata-ecs";
+import type { CameraState, PortalAffine } from "@ice/kernel";
+/** The one in-flight nav transition (design-006 §3.1). Inactive = at rest. */
+export declare const NavTransition: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly active: import("@vibecook/strata-ecs").FieldSpec<"bool", true>;
+    readonly kind: import("@vibecook/strata-ecs").FieldSpec<import("@vibecook/strata-ecs").EnumType<"enter" | "exit">, true>;
+    /** Progress spring state (closed-form critically damped, kernel springStep). */
+    readonly p: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly v: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    /** Depth-capped flight — T2 presents it as a crossfade, not geometry (§5). */
+    readonly frozen: import("@vibecook/strata-ecs").FieldSpec<"bool", true>;
+    /** Bumps on every flight start; T2 distinguishes retarget from resume. */
+    readonly epoch: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+    /** Response multiplier from octave distance (locked at start; §4). */
+    readonly durMul: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly c0x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly c0y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly c0z: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly c1x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly c1y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly c1z: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    /** Portal affine A: departed-frame coords → destination-frame coords (T2). */
+    readonly as: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly aox: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly aoy: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+}>, {
+    readonly active: import("@vibecook/strata-ecs").FieldSpec<"bool", true>;
+    readonly kind: import("@vibecook/strata-ecs").FieldSpec<import("@vibecook/strata-ecs").EnumType<"enter" | "exit">, true>;
+    /** Progress spring state (closed-form critically damped, kernel springStep). */
+    readonly p: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly v: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    /** Depth-capped flight — T2 presents it as a crossfade, not geometry (§5). */
+    readonly frozen: import("@vibecook/strata-ecs").FieldSpec<"bool", true>;
+    /** Bumps on every flight start; T2 distinguishes retarget from resume. */
+    readonly epoch: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+    /** Response multiplier from octave distance (locked at start; §4). */
+    readonly durMul: import("@vibecook/strata-ecs").FieldSpec<"f32", true>;
+    readonly c0x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly c0y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly c0z: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly c1x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly c1y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly c1z: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    /** Portal affine A: departed-frame coords → destination-frame coords (T2). */
+    readonly as: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly aox: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly aoy: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+}>;
+/**
+ * Arm a flight from the already-cut world: continuity-solve was done by the
+ * caller (`exact` = c0 in destination-frame coords), the arrival `c1` is
+ * already clamped. Applies the depth cap (§5), snaps the camera to c0, and
+ * activates the resource. Callers guarantee a live Viewport — headless/no-
+ * viewport paths snap to the arrival instead and never reach here.
+ */
+export declare function startNavFlight(world: World, kind: "enter" | "exit", A: PortalAffine, exact: CameraState, c1: CameraState): void;
+/** Deactivate without touching the camera (integrity pops, gesture yields). */
+export declare function abortNavFlight(world: World): void;
+/**
+ * Is a nav flight driving the camera right now? THE gate for flight-time
+ * GPU/paint duty (design-006 §8.2, answered by field testing 2026-07-16):
+ * heavy-motion consumers treat `Camera.gesturing ∨ navFlightActive` as one
+ * "camera in transient motion" signal — composite DPR drop, band-repaint
+ * suppression, Hot-island freeze, breakpoint retier deferral. `gesturing`
+ * itself stays a pure user-gesture fact (the inertia precedent): flights
+ * never stamp it, consumers OR the two.
+ */
+export declare function navFlightActive(world: World): boolean;
+export declare function createNavFlight(world: World): TickSystem;

package/dist/types/packages/core/src/widget/define-widget.d.ts

@@ -20,6 +20,12 @@ export interface WidgetInteraction {
     readonly solid?: boolean;
     /** "longPress": hold-to-lift dragging (iOS home-screen model); default "press". */
     readonly dragOn?: "press" | "longPress";
+    /**
+     * UE-Blueprint comment-box drag (2026-07-18): a move claim on this widget
+     * also claims every widget FULLY INSIDE its bounds at claim time (spatial
+     * membership — never reparenting). Default false.
+     */
+    readonly sweepContained?: boolean;
 }
 export interface WidgetDef {
     readonly type: string;
@@ -34,6 +40,16 @@ export interface WidgetDef {
     readonly surface: WidgetSurface;
     /** Framework component (opaque to core — the react package narrows it). */
     readonly component: unknown;
+    /**
+     * GL only: a DOM chrome component portaled into the widget's CONTENT-plane
+     * host (P1), which stacks UNDER the GL canvas (P2) — v1's proven
+     * CardChrome-beneath-the-canvas sandwich. The island renders ONLY the 3D
+     * content; the card body (gradient, radius, ring, shadow, lift spring,
+     * hover/overlap glow) is DOM and shares the app's CSS with DOM widgets.
+     * Opaque to core — the react package narrows it. Ignored for dom-surface
+     * widgets (their component IS the chrome).
+     */
+    readonly chrome?: unknown;
     readonly sizeMode?: SizeMode;
     readonly defaultSize?: {
         readonly w: number;
@@ -57,6 +73,23 @@ export interface WidgetDef {
      * the compatibility key list the connect gesture checks.
      */
     readonly ports?: readonly WidgetPortDecl[];
+    /**
+     * Palette/tray preview (design-005 §2 amendment, 2026-07-19). ENGINE-FREE
+     * BY CONTRACT: a preview renders with no world, no entity, no ops — a pure
+     * picture the host mounts inert (that is what makes it portable: trays,
+     * docs sites, a widget store). Authored at `defaultSize`; hosts scale.
+     * Three tiers, least effort first:
+     *  - absent            → the REAL component mounts with default props in
+     *                        the framework's preview sandbox (dom surfaces;
+     *                        truthful by construction);
+     *  - `{ props: {…} }`  → same sandbox mount with curated props;
+     *  - a component, or `{ component }` → author-owned preview (a static
+     *    mockup, a live self-ticking clock — the author's call). In P1 all
+     *    declared previews are DOM components — the sanctioned escape hatch
+     *    for GL widgets too (P2 adds the r3f snapshot pipeline).
+     * Opaque to core — the react package narrows it (`component` precedent).
+     */
+    readonly preview?: unknown;
     readonly container?: {
         readonly accepts: readonly string[];
         readonly provides?: readonly string[];
@@ -96,6 +129,8 @@ export interface WidgetType {
     readonly propToGroup: Readonly<Record<string, string>>;
     readonly surface: WidgetSurface;
     readonly component: unknown;
+    /** GL widgets: DOM chrome under the canvas (see WidgetDef.chrome). */
+    readonly chrome: unknown;
     readonly sizeMode: SizeMode;
     readonly defaultSize: {
         readonly w: number;
@@ -112,6 +147,10 @@ export interface WidgetType {
     /** Runtime capability tags the equip system stamps at projection. */
     readonly capabilityTags: readonly Tag[];
     readonly migrate: Readonly<Record<number, (prev: Record<string, unknown>) => Record<string, unknown>>>;
+    /** Normalized author preview component (opaque; react narrows). null = none declared. */
+    readonly previewComponent: unknown;
+    /** Prop overrides for the default real-component preview mount (validated names). */
+    readonly previewProps?: Readonly<Record<string, unknown>>;
 }
 /** Stamped by the equip system once a projected widget carries its capability tags. */
 export declare const WidgetEquipped: Tag;

package/dist/types/packages/core/src/widget/mount-store.d.ts

@@ -4,19 +4,27 @@
  *
  * - `cullSystem` (derive): viewport test over equipped widgets' EFFECTIVE size
  *   (MeasuredSize where present, else Size), overscan scaled by zoom; flips
- *   Visible/Culled CHANGE-ONLY.
+ *   Visible/Culled CHANGE-ONLY. GATED (2026-07-15, the activeMembership
+ *   playbook): a real `runIf` — camera/viewport window compare as the `extra`
+ *   trigger (full pass; the window moved under everyone) ∨ a petition-7
+ *   collector on Position/Size/MeasuredSize + Active flips (delta pass —
+ *   drags/spawns/measures re-test only the journaled entities). Idle frames
+ *   skip; camera frames stay O(active) by the widgetQ Active scope.
  * - `mountSystem` (derive, after cull): maintains the mount list — every
  *   Visible widget is mounted; Culled widgets stay mounted-but-hidden
  *   (`display:none` at the host; React state preserved) within a count LRU
  *   budget (default RUNTIME_BUDGETS.keepMountedWidgets); beyond it the
  *   least-recently-visible unmount for real. Decisions are ENGINE-side; the
  *   dom host reflector and the React portal hook both consume the snapshot.
+ *   GATED the same way on Visible/Culled flips (+ destroys of tagged
+ *   widgets); LRU recency is stamped at the flip (identical eviction order —
+ *   "last tick seen visible" = the tick it stopped being visible).
  * - The store implements the `useSyncExternalStore` contract: `subscribe` /
  *   `getSnapshot` with snapshot identity changing IFF membership or a hidden
  *   flag changed. Listener notification is deferred to post-notify (the
  *   engine flush reflector) — never from inside the tick.
  */
-import { type Entity, type System, type TickSystem, type World } from "@vibecook/strata-ecs";
+import { type Entity, type TickSystem, type World } from "@vibecook/strata-ecs";
 import type { Engine } from "../engine/engine";
 import type { MeasureQueue } from "../input/measure-queue";
 export interface MountEntry {
@@ -30,7 +38,7 @@ export interface WidgetMountStore {
 }
 export interface WidgetRuntime {
     readonly store: WidgetMountStore;
-    readonly cullSystem: System;
+    readonly cullSystem: TickSystem;
     readonly mountSystem: TickSystem;
     /** Post-notify listener flush — install registers it as a reflector. */
     flush(): void;

package/dist/types/packages/core/src/widget/set-props.d.ts

@@ -0,0 +1,16 @@
+/**
+ * setWidgetProps — the paved-road widget prop UPDATE op (2026-07-13 review:
+ * spawn validated through each prop's Standard Schema, but the update path —
+ * raw `useCommit` writes — bypassed bounds/enum/json-shape checks entirely).
+ *
+ * Mirrors `widgetSpawnInits` semantics exactly: unknown prop names throw,
+ * each given value runs `spec["~standard"].validate` (an invalid value throws
+ * BEFORE anything is written), `p.json` values are validated as parsed shapes
+ * then serialized into their string cell. Writes are whole-group absolute
+ * values (the current cell merged with the validated updates — design-001
+ * §5.2 conflict-group granularity), one guardedTransaction = one undo step.
+ */
+import type { Entity, World } from "@vibecook/strata-ecs";
+import type { DurableStore } from "@vibecook/strata-ecs/durable";
+import { type GuardedTxOpts } from "../guards/guarded-tx";
+export declare function setWidgetProps(store: DurableStore, world: World, entity: Entity, props: Readonly<Record<string, unknown>>, opts?: GuardedTxOpts): void;

package/dist/types/packages/core/src/widget/spawn.d.ts

@@ -6,7 +6,7 @@
  * design-001 §5.2's conflict-group granularity). Validation runs through each
  * prop's Standard Schema before the write.
  */
-import type { Entity, World } from "@vibecook/strata-ecs";
+import type { Entity, OrderPlace, Relation, World } from "@vibecook/strata-ecs";
 import type { DurableStore } from "@vibecook/strata-ecs/durable";
 import { type ComponentInit } from "../schema/prefab";
 export interface SpawnWidgetOpts {
@@ -14,10 +14,30 @@ export interface SpawnWidgetOpts {
     readonly y: number;
     readonly w?: number;
     readonly h?: number;
+    /**
+     * Sibling placement in the spawn parent's `ChildOf` sequence (petition 8);
+     * default "last" = painted last = on top. "first" spawns UNDER everything in
+     * the frame (e.g. a comment box spawning behind its members).
+     */
+    readonly order?: OrderPlace;
+    /** Explicit `ChildOf` parent; default = the frame parent (nav frame ?? board root). */
+    readonly parent?: Entity;
     readonly props?: Readonly<Record<string, unknown>>;
     /** false ⇒ the spawn never enters the local undo stack (batch seeds). */
     readonly undoable?: boolean;
 }
+/**
+ * Hang the spawn's `ChildOf` edge (petition 8) — shared by `spawnWidget` and
+ * the doc sink's create-intent execution so frame placement can never diverge
+ * between the two spawn paths. A legacy world (no BoardRoot, no nav frame,
+ * no explicit parent) gets NO edge: the entity stays legacy-fallback-ordered.
+ */
+export declare function attachSpawnParent(tx: {
+    setRelation(e: Entity, r: Relation, target: Entity, place?: OrderPlace): void;
+}, world: World, spawned: Entity, opts?: {
+    readonly parent?: Entity;
+    readonly order?: OrderPlace;
+}): void;
 /**
  * The prefab-override list for a widget spawn (Position/Size + validated
  * whole-group prop values). Shared by `spawnWidget` and the doc sink's

package/dist/types/packages/devtools/src/attach.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @ice/devtools — strata's first-party tools, engine-flavored (rebuilt
+ * 2026-07-13, superseding the M10 hand-rolled 4-tab panel: the standing rule
+ * is observers/inspectors WRAP `@vibecook/strata-ecs/tools`, never
+ * re-implement them).
+ *
+ * `attachDevtools(engine)` = strata's observer panel + FPS profiler, plus the
+ * engine glue strata cannot know:
+ *
+ *   DESCRIBE        PrefabId → widget type; recognizers → kind + live phase;
+ *                   pointers/ports/wires/peers/chrome labeled as such.
+ *   DURABLE TAB     fed from the facade's CURRENT DocSession (docId, converged
+ *                   snapshot, attachment baseline) — the getter re-reads per
+ *                   poll, so it tracks docs.create/open/join/close live.
+ *   EPHEMERAL TAB   fed from an app-provided PresenceSession getter (the
+ *                   facade keeps presence private; collab demos pass theirs).
+ *   "reflect" LANE  the engine's post-notify reflector flush cost — the one
+ *                   frame slice strata's world hooks cannot see — reported
+ *                   into the profiler via an onPublish hook reading
+ *                   `lastFrame()` telemetry (one frame late by construction:
+ *                   publish runs before this frame's reflect).
+ *
+ * By default all three tools mount into ONE draggable dock (dock.ts —
+ * 2026-07-13, James: "make the 3 tools into one draggable panel"); pass
+ * `dock: false` for the classic scattered corners.
+ *
+ * Reads only, outside the tick (verified-unrestricted); never a reflector,
+ * never writes ECS. Nobody imports this package (depcruise-enforced leaf).
+ */
+import type { Entity, World } from "@vibecook/strata-ecs";
+import { type DescribeFn, type EntityDescription, type ObserverHandle, type ObserverOptions, type ProfilerHandle, type ProfilerOptions } from "@vibecook/strata-ecs/tools";
+import { type DockOptions } from "./dock";
+import { type GlPanelOptions, type GlPanelStats } from "./gl-panel";
+import { type CanvasEngine, type Engine, type PresenceSession } from "@ice/core";
+export interface DevtoolsOpts {
+    /** Where the dock (or, with `dock: false`, each panel) mounts (default: document.body). */
+    readonly container?: HTMLElement;
+    /**
+     * ONE draggable dock hosting all three tools (the default). `false` scatters
+     * them to their classic fixed corners; an object sets initial placement.
+     * The dock mounts lazily with the first tool that needs it.
+     */
+    readonly dock?: boolean | Pick<DockOptions, "corner" | "title" | "width">;
+    /** Observer panel: `false` to omit, or strata passthrough options. */
+    readonly observer?: boolean | Pick<ObserverOptions, "defaultTab" | "tab" | "recorderCap">;
+    /** Profiler HUD: `false` to omit, or strata passthrough options. */
+    readonly profiler?: boolean | Pick<ProfilerOptions, "budgetMs" | "windowSize" | "corner" | "expanded" | "lanes">;
+    /** GL metrics panel: `false` to omit, or placement/budget options. Mounts lazily on the first `glStats` push. */
+    readonly glPanel?: boolean | Pick<GlPanelOptions, "corner" | "budgetMs" | "expanded">;
+    /** Collab demos: the presence session whose store feeds the ephemeral tab. */
+    readonly presence?: () => PresenceSession | null | undefined;
+    /** Override entity labeling (default: the engine describe below). */
+    readonly describe?: DescribeFn;
+}
+export interface DevtoolsHandle {
+    readonly observer: ObserverHandle | null;
+    readonly profiler: ProfilerHandle | null;
+    /** Host-cost lane passthrough (paint, decode…); no-op when the profiler is off. */
+    lane(name: string, ms: number): void;
+    /**
+     * Feed one GL frame's metrics (wire `<GLViews onFrameStats>` here). The GL
+     * panel mounts on the first push — renderer counts, virtual-texture census,
+     * LOD banding, cull population. No-op when opts.glPanel === false.
+     */
+    glStats(stats: GlPanelStats): void;
+    /** Tear all panels + the telemetry hook down. Idempotent. */
+    detach(): void;
+}
+/**
+ * Engine-aware entity labeling for the observer's lists + timeline: identity
+ * off ROLE (widget type, recognizer kind + phase, pointer device), not off
+ * raw component-name composition. Falls back to strata's defaultDescribe.
+ */
+export declare function engineDescribe(world: World, e: Entity): EntityDescription;
+/** Accepts the facade (durable tab included) or a bare core engine. */
+export type DevtoolsEngine = CanvasEngine | Engine;
+export declare function attachDevtools(engine: DevtoolsEngine, opts?: DevtoolsOpts): DevtoolsHandle;