@vibecook/ice 0.2.0 → 0.4.0

package/dist/react.js

@@ -13,6 +13,7 @@ import {
   useBreakpoint,
   useCanvasEngine,
   useCommit,
+  useFrameFreeze,
   useOps,
   usePresencePeers,
   useSelected,
@@ -23,9 +24,9 @@ import {
   useWidgetProps,
   useWorld,
   useWorldComponent
-} from "./chunk-5SJYHQI4.js";
-import "./chunk-IASTQMU5.js";
-import "./chunk-DXU3RZZS.js";
+} from "./chunk-ENMRSITH.js";
+import "./chunk-3PHPWRB2.js";
+import "./chunk-7LZAXQAO.js";
 import "./chunk-OR5FNVUE.js";
 export {
   EngineProvider,
@@ -42,6 +43,7 @@ export {
   useBreakpoint,
   useCanvasEngine,
   useCommit,
+  useFrameFreeze,
   useOps,
   usePresencePeers,
   useSelected,

package/dist/types/packages/core/src/catalog/camera-derived.d.ts

@@ -39,12 +39,36 @@ export declare const ActiveTool: import("@vibecook/strata-ecs").Resource<import(
  * NOT a full step-pause: a menu panel floats over a still-visible canvas,
  * and a frozen world would leave undo/collab visually stale (rev-2 decision,
  * recorded — a stricter frozen-world mode would be a separate concept).
+ * That separate concept is now BUILT (2026-08-04): see {@link FrameMode}.
+ * Holds keep their exact meaning — nothing here stretched.
  */
 export declare const StageMode: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
     readonly backgroundHolds: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
 }>, {
     readonly backgroundHolds: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
 }>;
+/**
+ * Frame gate mirror (2026-08-04) — the stricter sibling {@link StageMode}'s
+ * rev-2 decision named and left for later.
+ *
+ * A background hold is presentation policy over a LIVE world. A freeze
+ * (`engine.frame.freeze(name)`) stops the host loop outright: no step, so no
+ * systems, no publish, no notify, no reflectors, no rAF — for chrome that
+ * COVERS the canvas, where every frame drawn behind it is work nobody can see.
+ * This resource is the world-truth mirror of that refcount; the tokens live on
+ * the control, out of ECS, exactly as stage holds do.
+ *
+ * Reading it tells you the engine is frozen. It cannot tell you a frame is
+ * coming, because while the count is non-zero none is — and for the same
+ * reason nothing can OBSERVE it while frozen (a parked world fires no
+ * observers). It exists for inspection: devtools, tests, and consumers that
+ * want the fact in hand on thaw.
+ */
+export declare const FrameMode: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly freezeHolds: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+}>, {
+    readonly freezeHolds: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+}>;
 /** Global snap toggle + threshold in screen px (scaled by zoom at use, design-003 §5.2). */
 export declare const SnapConfig: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
     readonly enabled: import("@vibecook/strata-ecs").FieldSpec<"bool", true>;
@@ -101,9 +125,9 @@ export declare const SelectionBox: import("@vibecook/strata-ecs").Component<impo
 }>;
 /** A resize handle's anchor (the one chrome kind behaviors capture). */
 export declare const HandleSpec: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{
-    readonly anchor: import("@vibecook/strata-ecs").EnumType<"s" | "w" | "n" | "e" | "nw" | "ne" | "se" | "sw">;
+    readonly anchor: import("@vibecook/strata-ecs").EnumType<"s" | "w" | "nw" | "n" | "ne" | "e" | "se" | "sw">;
 }>, {
-    readonly anchor: import("@vibecook/strata-ecs").EnumType<"s" | "w" | "n" | "e" | "nw" | "ne" | "se" | "sw">;
+    readonly anchor: import("@vibecook/strata-ecs").EnumType<"s" | "w" | "nw" | "n" | "ne" | "e" | "se" | "sw">;
 }>;
 /** A snap guide line along one axis. `from == to` ⇒ full-viewport line (v1's full-canvas alignment look — design-003 §6). */
 export declare const GuideLine: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{

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

@@ -115,7 +115,7 @@ export declare const WheelZoom: import("@vibecook/strata-ecs").Component<import(
  * `Sequence`/`RequiresFail` edge. NEVER reaped; exempt from integrity's watched-pointer
  * count (a pending multi-tap legitimately outlives its lifted touch pointer).
  */
-export declare const GesturePhases: import("..").PhaseSet<"Possible" | "Active" | "Pending" | "Recognized" | "Ended" | "Failed" | "Cancelled">;
+export declare const GesturePhases: import("..").PhaseSet<"Active" | "Possible" | "Pending" | "Recognized" | "Ended" | "Failed" | "Cancelled">;
 /** Recognizer alive, not yet claiming. */
 export declare const GesturePossible: import("@vibecook/strata-ecs").Tag;
 /** Continuous kinds' claiming phase + per-frame work gate. */

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

@@ -66,6 +66,17 @@ export declare const WentUp: import("@vibecook/strata-ecs").Tag;
 export declare const WentCancelled: import("@vibecook/strata-ecs").Tag;
 /** The down was consumed by a widget's own DOM handler — recognizers skip it. */
 export declare const HandledByWidget: import("@vibecook/strata-ecs").Tag;
+/**
+ * ONE-TICK: this tick's wheel deltas were ceded to scrollable widget content
+ * (design-007 §3.5, petition I4) — the adapter let native scroll proceed and
+ * flagged the fact `wheelHandled`. Deliberately NOT the shared `HandledByWidget`
+ * latch: that tag rides the persistent mouse-pointer entity, and a same-tick
+ * wheel-over-widget + down-over-canvas collision would silently drop the
+ * legitimate canvas gesture (design-007 F6). Both wheel consumers honor it —
+ * `wheelSpawn` skips the tick, `wheelSystem` treats it as wheel silence.
+ * Cleared in cleanup like the Went* transition tags.
+ */
+export declare const WheelHandled: import("@vibecook/strata-ecs").Tag;
 /**
  * PERSISTENT (not one-tick): the pointer is hovering content that would opt a
  * down out — a native interactive / `[data-canvas-interactive]` (DOM) or

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

@@ -12,6 +12,16 @@ export declare const SnapTarget: import("@vibecook/strata-ecs").Tag;
  * path). Drag a member out and it simply stops being inside.
  */
 export declare const SweepsContained: import("@vibecook/strata-ecs").Tag;
+/**
+ * `interaction.keyboard: "exclusive"` (design-007 §3.1, petitions I1/I4): while
+ * a node inside this widget holds browser focus, the engine's keyboard surfaces
+ * (keymap shortcuts, the adapter's Space pan modifier) stand down. The ROUTING
+ * truth is the DOM — the dom-widgets reflector writes a `data-canvas-keyboard`
+ * marker on the widget host and the keymap/adapter read the event-target chain
+ * against `document.activeElement`; this tag is the ECS-side mirror of the
+ * declaration (queryable by devtools/presence), never a routing input.
+ */
+export declare const KeyboardExclusive: import("@vibecook/strata-ecs").Tag;
 /**
  * Marks an ephemeral presence-peer entity (design-001 §5.6). Rides the presence
  * blob so remote peers project it — a peer query is `[PresencePeer, Not(Local)]`

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

@@ -1,3 +1,37 @@
+/**
+ * The autosave kit (design-005 §6.6; design-001 §6.5 envelope-at-rest).
+ *
+ * Persists a `DocSession` to app-owned storage on a debounce (default 800 ms)
+ * with a max-wait ceiling (default 10 s), DEFERRED while the user is mid-gesture
+ * so a save never captures a half-applied interaction. What it writes is an
+ * ENVELOPE (`session.exportEnvelope(savedAt)`) — never raw Loro bytes — so the
+ * restore path can read the header and gate/quarantine BEFORE any import.
+ *
+ * CHANGE-SUBSCRIPTION SURFACE: two triggers, plus an initial arm.
+ * - `DurableStore.subscribeOutbound` (durable-store.ts) fires SYNCHRONOUSLY on
+ *   each sealed LOCAL commit and never on remote imports.
+ * - `DocSession.subscribeRemote` (doc-kit) fires after each successful
+ *   `applyRemote`. The original design left remote changes to "whichever peer
+ *   originated them" — but that peer persists to ITS storage, not this one's:
+ *   a joiner that received edits and closed restored a STALE local backup
+ *   (2026-07-13 review). Local autosave must reflect the last-seen document.
+ * - Autosave starts DIRTY: state that predates startAutosave() (a seeded or
+ *   freshly-joined doc) reaches storage after the first debounce, not only
+ *   after the next edit (same review — a seeded doc could close unsaved).
+ * No polling — the design's `store.exportSnapshot()` length/frontier poll is
+ * the last-resort fallback and is not needed here.
+ *
+ * Clock and scheduler are injectable so tests are deterministic with NO real
+ * timers; the design's `requestIdleCallback` optimization is just an alternate
+ * `schedule` an app can pass. `flush()` forces an awaited save; `close()`
+ * captures and durably serializes the final revision; `stop()` explicitly
+ * discards pending state.
+ *
+ * RESTORE (`restoreAutosave`): reads storage → `openDocSession`. Incompatible or
+ * corrupt bytes NEVER throw and NEVER brick boot (the M5 exit criterion) —
+ * they come back as `{ status: "quarantined", reason, bytes }` so the app can
+ * stash the bytes aside and start fresh.
+ */
 import type { World } from "@vibecook/strata-ecs";
 import { type DocSession, type DocSessionOpts } from "./doc-kit";
 import type { DocVersionReport } from "./version-gate";

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

@@ -0,0 +1,3 @@
+import type { World } from "@vibecook/strata-ecs";
+import type { DurableStore } from "@vibecook/strata-ecs/durable";
+export declare function armRenameSweep(world: World, store: DurableStore): () => void;

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

@@ -0,0 +1,7 @@
+import type { MigrationCtx } from "./migrate";
+import type { DocVersionReport } from "./version-gate";
+export interface RenameOutcome {
+    /** Old ids folded and tombstoned this open (marker-only docs still stamp). */
+    readonly renamed: string[];
+}
+export declare function runRenames(ctx: MigrationCtx, report: DocVersionReport): RenameOutcome;

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

@@ -36,6 +36,14 @@ export interface DocVersionReport {
     readonly newerInDoc: readonly string[];
     /** Prefab ids whose doc marker is OLDER than local (M9 migration input). */
     readonly olderInDoc: readonly string[];
+    /**
+     * Old ids with a REGISTERED rename, present in the doc and not yet
+     * tombstoned → the doc pack version their markers carry (design-008 §4).
+     * The rename runner's exact input; non-empty forces at least "migrate".
+     * Meta has no delete, so a stale old marker without this classification
+     * would brick the doc `readOnly` via `newerInDoc` — the I5 failure mode.
+     */
+    readonly renamedInDoc: Readonly<Record<string, number>>;
 }
 export type GateVerdict = "ok" | "readOnly" | "migrate" | "reject";
 /**
@@ -46,7 +54,12 @@ export type GateVerdict = "ok" | "readOnly" | "migrate" | "reject";
 export declare function stampEngineMeta(store: DurableStore): void;
 /** Read the marker keys off a raw (imported, unattached) doc and compare. */
 export declare function readDocVersionReport(doc: LoroDoc): DocVersionReport;
-/** Build the same comparison report from an envelope header, before Loro import. */
+/**
+ * Build the same comparison report from an envelope header, before Loro
+ * import. The header carries no meta, so no tombstone knowledge here —
+ * registry aliasing only. This preflight is coarse by design; the
+ * authoritative in-document gate re-runs right after import.
+ */
 export declare function readEnvelopeVersionReport(header: EnvelopeHeader): DocVersionReport;
 /** The default M5 policy. A facade policy hook may override (design-005 §6.3). */
 export declare function gateVerdict(report: DocVersionReport): GateVerdict;

package/dist/types/packages/core/src/engine/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/facade/create-canvas-engine.d.ts

@@ -20,6 +20,7 @@
  */
 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 NavOpts, type NestedCanvas } from "../nav/nested-canvas";
 import { type ArrangeOpts } from "../ops/arrange";
@@ -173,6 +174,14 @@ export interface CanvasEngine {
     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/index.d.ts

@@ -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";
@@ -32,6 +33,7 @@ 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 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";
@@ -46,7 +48,7 @@ export type { DurableUndoStatusValue } from "@vibecook/strata-ecs/durable";
 export { createDocSession, openDocSession, type DocSession, type DocSessionOpts, type OpenDocResult, } from "./doc/doc-kit";
 export { runMigrations, type MigrationCtx, type MigrationOutcome } from "./doc/migrate";
 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 { WidgetEquipped, defineWidget, renames, widgets, type SizeMode, type WidgetDef, type WidgetGroup, type WidgetInteraction, type WidgetPortDecl, type WidgetRename, type WidgetRenameEntry, type WidgetSurface, type WidgetType, } from "./widget/define-widget";
 export { createWidgetEquipSystem } from "./widget/equip";
 export { attachSpawnParent, spawnWidget, widgetSpawnInits, type SpawnWidgetOpts } from "./widget/spawn";
 export { setWidgetProps } from "./widget/set-props";

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

@@ -40,6 +40,15 @@ export interface InputEvent {
     };
     /** GL-island opt-out (pinned widget-event contract, design-002 §8): fact still lands, recognizers skip. */
     readonly surfaceHandled?: boolean;
+    /**
+     * Wheel-only opt-out (design-007 §3.5, petition I4): this wheel's deltas were
+     * ceded to scrollable widget content — the adapter skipped `preventDefault`
+     * and native scroll consumed them. The fact still lands (one input path);
+     * ingest stamps the one-tick `WheelHandled` tag so the wheel recognizers skip
+     * the tick. DISTINCT from `surfaceHandled` on purpose: the shared latch on
+     * the persistent mouse pointer would collide with a same-tick canvas down.
+     */
+    readonly wheelHandled?: 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

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/schema/meta.d.ts

@@ -28,6 +28,18 @@ export interface ResourceMeta {
     durable: boolean;
 }
 export declare function defineComponent<const Sch extends RawSchema>(name: string, schema: Sch): ReturnType<typeof strataDefineComponent<Sch>>;
+/**
+ * Reuse-or-define by NAME (design-008 §3.1): strata's schema registry throws
+ * on duplicate identifiers (its registry.ts:38), and rename legacy components
+ * (`<oldType>:<group>`) can legitimately re-enter the process — a test that
+ * defined the old widget before resetting ice registries, or a hot-reload
+ * double-eval — while strata's global registry survives. An existing
+ * SAME-SHAPED component is the same component: reuse its handle. A mismatched
+ * shape under the same name is a real collision: throw. The shape compare is
+ * JSON-stringify over the recorded raw schema — sound here because both sides
+ * are built by the same `strataFieldOf` constructors in the same field order.
+ */
+export declare function ensureComponent<const Sch extends RawSchema>(name: string, schema: Sch): Component;
 export declare function defineTag(name: string): Tag;
 export declare function defineRelation(name: string, opts?: {
     arity?: "one" | "many";

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

@@ -11,6 +11,32 @@ export interface WidgetPortDecl {
     /** Compatibility keys (empty = connects to anything). */
     readonly accepts?: readonly string[];
 }
+/**
+ * A prior durable id of this widget type (design-008 §3, petition I5). Docs
+ * written under the old id fold to this type at open (doc/rename.ts) and via
+ * the live zombie sweep (doc/rename-sweep.ts) — replicas converge through
+ * ordinary CRDT delivery, retiring offline byte surgery. Declares group-NAME
+ * continuity at the rename boundary (the pack runner's existing fence).
+ */
+export interface WidgetRename {
+    /** The old durable type id (`PrefabId.id` in pre-rename docs). */
+    readonly type: string;
+    /**
+     * The pack version old-build writers of `type` were at (default 1). Only
+     * the SWEEP consumes it — a late old-shape delivery carries no marker, so
+     * its values chain-fold from here; the open-path runner reads the version
+     * off the doc's own markers instead (design-008 §6.3).
+     */
+    readonly atVersion?: number;
+}
+/** A rename registry entry (doc/rename runner + sweep input). */
+export interface WidgetRenameEntry {
+    readonly widget: WidgetType;
+    readonly oldType: string;
+    readonly atVersion: number;
+    /** Legacy `<oldType>:<group>` components, index-aligned with `widget.groups`. */
+    readonly legacyGroups: readonly Component[];
+}
 export interface WidgetInteraction {
     readonly selectable?: boolean;
     readonly movable?: boolean;
@@ -26,6 +52,25 @@ export interface WidgetInteraction {
      * membership — never reparenting). Default false.
      */
     readonly sweepContained?: boolean;
+    /**
+     * Keyboard claim (design-007 §3.1, petitions I1/I4). `"exclusive"`: while a
+     * node inside this widget holds browser focus, the engine keymap and the
+     * adapter's Space pan modifier stand down — keys flow to the widget's own
+     * handlers (the engine stops competing; it never delivers behavior). The
+     * dom-widgets reflector marks the host `data-canvas-keyboard` + `tabindex=-1`
+     * so a click anywhere in the widget acquires focus, and plain wheel over the
+     * widget's scrollable content cedes to native scroll (ctrl/pinch stays
+     * canvas zoom always). Default `"shared"` — today's behavior, byte-identical.
+     */
+    readonly keyboard?: "shared" | "exclusive";
+    /**
+     * Escape ownership under an exclusive claim (design-007 §3.3 / §7-Q1).
+     * `"release"` (default): Escape is the engine-reserved release gesture — it
+     * blurs the widget; the NEXT Escape, with focus gone, cancels gestures.
+     * `"widget"`: even Escape flows to the widget (vim-grade terminals); release
+     * is click-away or `blurFocus()`. Ignored unless `keyboard: "exclusive"`.
+     */
+    readonly keyboardEscape?: "release" | "widget";
 }
 export interface WidgetDef {
     readonly type: string;
@@ -101,6 +146,13 @@ export interface WidgetDef {
      * (its `provides` wins).
      */
     readonly provides?: readonly string[];
+    /**
+     * Prior durable ids folded to this type (design-008; petition I5). Additive:
+     * registers read-only LEGACY group components under the old names so
+     * pre-rename cells project, gates pre-rename docs "migrate" instead of
+     * read-only, and arms the live zombie sweep on every writable session.
+     */
+    readonly renamedFrom?: readonly WidgetRename[];
     /**
      * fromVersion → idempotent absolute transform (M9's `runMigrations` runs the
      * chain at open; `prev`/return are flat prop records spanning every group).
@@ -146,6 +198,10 @@ export interface WidgetType {
     readonly ports: readonly WidgetPortDecl[];
     /** Runtime capability tags the equip system stamps at projection. */
     readonly capabilityTags: readonly Tag[];
+    /** Keyboard claim (design-007): the dom layer reads THIS (registry truth), not the tag. */
+    readonly keyboard: "shared" | "exclusive";
+    /** Escape ownership under an exclusive claim ("release" = engine-reserved). */
+    readonly keyboardEscape: "release" | "widget";
     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;
@@ -158,6 +214,11 @@ export declare const widgets: {
     get(type: string): WidgetType | undefined;
     all(): WidgetType[];
 };
+/** The rename registry (design-008 §3): old durable id → fold target. */
+export declare const renames: {
+    get(oldType: string): WidgetRenameEntry | undefined;
+    all(): WidgetRenameEntry[];
+};
 export declare function defineWidget(def: WidgetDef): WidgetType;
 /** TEST-ONLY wipe (mirrors __resetPrefabsForTests; not on the barrel). */
 export declare function __resetWidgetsForTests(): void;

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

@@ -10,6 +10,8 @@ export { createGrayboxReflector } from "./reflectors/graybox";
 export { createDomWidgetsReflector, type DomWidgetsHost, type DomWidgetsReflector, } from "./reflectors/dom-widgets";
 export { startRafLoop } from "./loop";
 export { attachPointerAdapter, type GLRoute, type GLRouteVerdict, type PointerAdapterOpts } from "./pointer-adapter";
+export { CLAIM_OWNS_ESCAPE, KEYBOARD_CLAIM_ATTR, isEditableTarget, keyboardClaimOf, wheelCede, type KeyboardClaim, } from "./input-ownership";
+export { FOCUS_PROXY_ATTR, attachWidgetFocus, type FocusHostLookup, type WidgetFocusHandle, } from "./widget-focus";
 export { createCursorReflector } from "./reflectors/cursor";
 export { createRemoteCursorsReflector, type RemoteCursorsReflector } from "./reflectors/remote-cursors";
 export { createChromeReflector } from "./reflectors/chrome";

package/dist/types/packages/dom/src/input-ownership.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Input-ownership predicates (design-007 §4 — one predicate FAMILY, not one
+ * predicate; petitions I1/I4). "Does the widget own input here" is answered
+ * per-surface at the right scope, sharing the DOM-walk mechanics:
+ *
+ *  - `isEditableTarget` — the 4-class editable gate (keymap default + the
+ *    adapter's Space-types fix). Kept narrow so UNDECLARED widgets behave
+ *    exactly as before (design-007 F5).
+ *  - `keyboardClaimOf` — the `data-canvas-keyboard` claim marker written by the
+ *    dom-widgets reflector for `interaction.keyboard: "exclusive"` widgets.
+ *    Read UNBOUNDED (page-global) on purpose: `document.activeElement` is one
+ *    per page, so engine B's keymap must stand down while you type into engine
+ *    A's claiming widget (design-007 F2 — only the DOM is page-global).
+ *  - `wheelCede` — the NARROW, DYNAMIC scroll opt-out (design-007 §3.4/§4):
+ *    plain wheel cedes to native scroll only when a scroller WITH ROOM in the
+ *    wheel's dominant axis sits inside a claim-marked / `data-canvas-
+ *    interactive` / editable subtree. At the scroll bounds the predicate turns
+ *    false and the wheel falls through to canvas pan/zoom — the familiar
+ *    nested-scroll feel — which also keeps scroll-chaining from ever reaching
+ *    the page. Deliberately NOT the full `crossesInteractive` set: hovering a
+ *    bare `<button>` must not kill canvas zoom (design-007 F4).
+ *
+ * The keymap (`@ice/react`) imports these — the two historically disagreeing
+ * guards now share one implementation (the I1 unification).
+ */
+/** The claim marker the dom-widgets reflector writes on an exclusive widget's host. */
+export declare const KEYBOARD_CLAIM_ATTR = "data-canvas-keyboard";
+/** Marker value for `keyboardEscape: "widget"` (the widget receives even Escape). */
+export declare const CLAIM_OWNS_ESCAPE = "escape";
+export interface KeyboardClaim {
+    /** The event-target chain crosses a claim marker (⇒ engine keyboard stands down). */
+    readonly claimed: boolean;
+    /** The claiming widget owns Escape too (`keyboardEscape: "widget"`). */
+    readonly ownsEscape: boolean;
+}
+/** The keymap's editable gate — exactly INPUT/TEXTAREA/SELECT/contentEditable. */
+export declare function isEditableTarget(target: EventTarget | null): boolean;
+/**
+ * Resolve the keyboard claim for an event target (keydown targets ARE
+ * `document.activeElement`, so this reads browser focus — the single source of
+ * truth, design-007 §2.1). Unbounded `closest` by design (see header).
+ */
+export declare function keyboardClaimOf(target: EventTarget | null): KeyboardClaim;
+/**
+ * Should this plain (non-pinch) wheel be ceded to native widget scroll?
+ * Walks target → container: remembers any scroller-with-room, cedes on the
+ * first opt-out root at or above it. Walking up meets scrollers BEFORE their
+ * widget's marker (the marker sits on the host), so "a scroller inside an
+ * opt-out subtree" is exactly "saw a scroller by the time the marker matches".
+ * ctrl/pinch wheels never reach this — they are ALWAYS the canvas's zoom.
+ */
+export declare function wheelCede(target: EventTarget | null, container: HTMLElement, dx: number, dy: number): boolean;

package/dist/types/packages/dom/src/loop.d.ts

@@ -6,6 +6,17 @@
  * timestamp straight into the frame clock (so FrameInfo.dt is real wall time,
  * clamped in core). The returned stop fn cancels the pending frame AND latches
  * so a frame already in flight cannot re-schedule — calling it is idempotent.
+ *
+ * THE FREEZE GATE (2026-08-04). Before each frame the loop claims a step from
+ * `engine.frame`. While a freeze is held the gate walks its settle and then
+ * refuses, at which point the loop PARKS: it stops scheduling rAF at all
+ * rather than spinning a callback that does nothing — "the engine is stopped"
+ * should mean the browser has no work queued for it either. Thaw arrives
+ * through the gate's change subscription, which schedules the next frame.
+ *
+ * The dt clamp is what makes resume safe: a freeze that lasted an hour hands
+ * `step` an enormous `now`, and core clamps the delta (frame-info.ts), so
+ * tweens advance by one ordinary frame instead of teleporting to their end.
  */
 import type { Engine } from "@ice/core";
 export declare function startRafLoop(engine: Engine): () => void;

package/dist/types/packages/dom/src/pointer-adapter.d.ts

@@ -13,9 +13,22 @@
  *  - `setPointerCapture` on down so a drag keeps delivering outside the element;
  *  - Space is the pan modifier (design-003 §4.4): tracked here and threaded onto
  *    every event's `mods.space`; keydown/keyup emit a `key` fact only when the
- *    modifier tuple actually changes, and Space `preventDefault`s to stop page scroll;
- *  - wheel `preventDefault`s: a ctrl-wheel / trackpad pinch becomes `wheel.pinch`
- *    (the zoom signal), a plain wheel becomes dx/dy (deltaMode lines → px ×16);
+ *    modifier tuple actually changes. Space's preventDefault/latch is OWNERSHIP-
+ *    AWARE (design-007 §3.4, petition I1): into an editable it neither latches
+ *    nor preventDefaults (Space must TYPE — the §1.6 live-bug fix); into a
+ *    `data-canvas-keyboard` claim it cedes the pan SEMANTICS but keeps killing
+ *    the page-scroll default (the key still reaches the widget's own listener —
+ *    preventDefault is not stopPropagation); elsewhere it pans, as ever;
+ *  - wheel: ctrl-wheel / trackpad pinch is ALWAYS `preventDefault` + the canvas
+ *    zoom signal (`wheel.pinch`) — a browser page-zoom over a widget is
+ *    catastrophic, claimed or not. A PLAIN wheel over a scroller-with-room
+ *    inside a claim/`data-canvas-interactive`/editable subtree (`wheelCede`,
+ *    design-007 §3.4/§3.5) is ceded: NO preventDefault (native scroll
+ *    proceeds), the fact still lands flagged `wheelHandled` so ingest stamps
+ *    the one-tick `WheelHandled` and the wheel recognizers skip the tick. At
+ *    the scroll bounds the predicate flips and the wheel falls through to
+ *    canvas pan/zoom. Everything else: `preventDefault`, dx/dy (deltaMode
+ *    lines → px ×16) — unchanged;
  *  - window blur enqueues a synthetic `cancel` for every pointer still down
  *    (design-003 §8) — the browser will not send the pointerups.
  *