@vibecook/ice 0.3.0 → 0.6.0

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

@@ -0,0 +1,196 @@
+/**
+ * The guest runtime (petition I14 — the literal PA-28 "spine scheduler").
+ *
+ * A GUEST is frame-cadence work the engine did not write: a plugin's declared
+ * system, a host's derived-state job, and (from design-009) every compiled
+ * behavior. Guests get a NAMED slot in the frame contract — design-002 §1 as
+ * amended 2026-08-15:
+ *
+ *     setFrameInfo → sync → tick → GUESTS → publish hooks → notify → reflect
+ *
+ * Guests run BEFORE the publish hooks so derived state has settled by the time
+ * presence I/O reads it, and before `notify()` so the same frame reflects their
+ * writes. Three properties the engine owes anything it hosts here:
+ *
+ * 1. **Fault isolation.** A throwing guest is caught, struck, and skipped — it
+ *    never kills the loop, its neighbours, or the frame. (Engine systems and
+ *    publish hooks keep propagating loudly by design; guests are the untrusted
+ *    tier, and the breaker below is what makes hosting them honest.)
+ * 2. **The snapshot rule.** `runAll` iterates a snapshot with a liveness check,
+ *    so a guest that adds or removes guests mid-run never skips a neighbour —
+ *    the bug this same release fixed in the publish-hook and reflector loops.
+ *    A guest added during a run starts NEXT frame.
+ * 3. **A circuit breaker, named honestly.** A main-thread body cannot be
+ *    preempted: by the time we measure, the frame is already spent. What the
+ *    breaker guarantees is that no guest hurts the canvas TWICE sustained.
+ *
+ * GENERATIONS. `make(gen)` builds a per-generation instance; the generation
+ * boundary in ICE is `world.reset()` (doc close/switch — the world is reset in
+ * place, so systems, observers and this registry all survive while every entity
+ * dies). On reset we mark the generation dirty and rebuild at the TOP of the
+ * next guest step — never inside the observer emit, where structural writes are
+ * illegal and user code has no business running. `gen.signal` aborts when the
+ * generation ends or the guest is removed.
+ *
+ * THE LEDGER IS HOST-INJECTABLE. Downstream (VibeField) an engine is per-doc, so
+ * a registry-local ledger would reset on every doc switch and hand chronic
+ * offenders a fresh probation forever. `add({ledger})` seeds prior state and
+ * `onLedgerChange` reports every transition, so the host persists across
+ * generations it owns.
+ */
+import type { World } from "@vibecook/strata-ecs";
+/** Frame facts a guest may read (FrameInfo, pre-read by the engine). */
+export interface GuestFrame {
+    readonly dtMs: number;
+    readonly tick: number;
+    /** Accumulated CLAMPED dt — under-reports across freezes; never accumulate
+     *  wall time from it (frame-info.ts). */
+    readonly clock: number;
+}
+export type GuestRun = (frame: GuestFrame) => void;
+export interface GuestInstance {
+    run: GuestRun;
+    dispose?: () => void;
+    /**
+     * "I still owe visible work." Feeds the frame gate's settle walk, so a
+     * freeze taken mid-derive parks only AFTER the guest has caught up — the
+     * canvas is never photographed between a structural change and its reflow.
+     * A guest with no owed-work notion simply omits it (the frame gate then
+     * treats it as quiet, which is the honest default).
+     */
+    busy?: () => boolean;
+}
+export interface GuestGeneration {
+    readonly world: World;
+    /** Aborts at generation teardown (world reset), removal, or engine dispose. */
+    readonly signal: AbortSignal;
+}
+export type GuestFactory = (gen: GuestGeneration) => GuestInstance | GuestRun;
+/** The persistable half of a guest's breaker state. */
+export interface GuestLedgerRecord {
+    /** Cumulative over-budget/fault strikes (never reset by resume — honesty). */
+    readonly strikes: number;
+    readonly suspended: boolean;
+}
+export interface GuestSpec {
+    /** Stable id — the ledger key, the profiler lane name, the doctor's row. */
+    readonly id: string;
+    readonly make: GuestFactory;
+    /** Per-invocation budget request; the effective budget is
+     *  `min(budgetMs, seamCapMs)` — no single guest may claim the whole seam. */
+    readonly budgetMs?: number;
+    /** RESERVED. v1 hosts the publish slot only; pipeline-group values arrive
+     *  with the behavior framework (design-009 M13a), wrapped by this breaker. */
+    readonly phase?: "publish";
+    /** Seed prior breaker state (host-persisted across engine generations). */
+    readonly ledger?: GuestLedgerRecord;
+}
+export interface GuestStatus {
+    readonly id: string;
+    readonly status: "running" | "suspended" | "failed";
+    /** Last invocation, ms. */
+    readonly lastMs: number;
+    /** p95 over the rolling window, ms. */
+    readonly p95Ms: number;
+    readonly strikes: number;
+    readonly budgetMs: number;
+}
+/**
+ * A guest whose CADENCE its owner drives (design-009 §7): compiled behaviors
+ * run as ordinary pipeline systems, in their declared phase, inside the tick —
+ * so nothing here can call their bodies. What they still need is everything
+ * ELSE a guest gets: one breaker, one ledger, one doctor row, one seam total.
+ * That is what this handle is — the breaker, detached from the scheduler.
+ */
+export interface DrivenGuest {
+    /** Breaker verdict. Cheap and never throws — poll it from a system `runIf`. */
+    suspended(): boolean;
+    /**
+     * Run `body` inside this guest's fault domain, ACCRUING its cost into the
+     * current frame's charge. Returns false when the guest is suspended (the
+     * body did not run) or the body threw (contained).
+     *
+     * Accrual, not per-call recording, is what makes the budget mean "per frame"
+     * for a CHUNKED body: a tick system's body runs once per matching chunk, and
+     * recording each chunk as its own invocation would compare a 2ms frame budget
+     * against a fraction of the work it was meant to bound. The accrued total is
+     * closed as ONE invocation at the guest slot, every frame.
+     */
+    run(body: () => void): boolean;
+    /**
+     * Report a fault the caller already CONTAINED — a per-instance hook throw
+     * that the delivery loop caught so one bad node cannot kill a 1000-node
+     * behavior (BF-D18). It takes the ordinary throw ladder.
+     */
+    fault(err: unknown): void;
+    /** Idempotent. */
+    remove(): void;
+}
+export interface DrivenGuestSpec {
+    readonly id: string;
+    readonly budgetMs?: number;
+    readonly ledger?: GuestLedgerRecord;
+    /** Owed-work reporter for the frame gate's settle walk. */
+    readonly busy?: () => boolean;
+}
+export interface GuestRegistry {
+    /** Register a guest. Returns a remover (idempotent; disposes the instance). */
+    add(spec: GuestSpec): () => void;
+    /**
+     * Register a guest the registry does NOT call (see {@link DrivenGuest}).
+     * Its cost still lands in this frame's seam total, its strikes in the same
+     * ledger, and its row in `list()`.
+     */
+    addDriven(spec: DrivenGuestSpec): DrivenGuest;
+    /** Live status for devtools/doctor — never throws, safe to poll. */
+    list(): readonly GuestStatus[];
+    /** Fires whenever a guest's persistable breaker state changes. */
+    onLedgerChange(cb: (id: string, record: GuestLedgerRecord) => void): () => void;
+    /** Clear a suspension (the doctor's explicit action). Cumulative strikes
+     *  survive; the rolling window is cleared so probation starts fresh. */
+    resume(id: string): void;
+}
+/** The engine-facing half (step drives it; hosts never see these). */
+export interface GuestRegistryInternal extends GuestRegistry {
+    runAll(frame: GuestFrame): void;
+    /** Any live guest reporting owed work — the engine's settle reporter. */
+    anyBusy(): boolean;
+    dispose(): void;
+}
+/**
+ * Breaker constants (design-009 §12 / door ED-D3). Exported so tests and the
+ * downstream doctor cite ONE source rather than re-deriving thresholds.
+ */
+export declare const GUEST_BUDGET: {
+    /** Default per-invocation budget when a guest declares none. */
+    readonly defaultBudgetMs: 2;
+    /** The whole guest seam's sustained budget — also the per-guest ceiling. */
+    readonly seamCapMs: 8;
+    /** Rolling window length, in invocations. */
+    readonly window: 120;
+    /** Trip: more than this many of the last `window` invocations over budget. */
+    readonly overBudgetTrip: 30;
+    /** Trip: this many CONSECUTIVE invocations at ≥ `heavyFactor` × budget. */
+    readonly consecutiveHeavy: 3;
+    readonly heavyFactor: 4;
+    /** Trip: this many CONSECUTIVE invocations over `stallMs` (one GC pause or
+     *  debugger breakpoint must never suspend — hence 2, not 1). */
+    readonly consecutiveStall: 2;
+    readonly stallMs: 50;
+    /** Trip: this many consecutive throws. */
+    readonly consecutiveThrows: 3;
+    /** Frames the whole seam may sit over `seamCapMs` before the worst offender
+     *  is suspended. */
+    readonly seamOverFrames: 3;
+};
+export interface GuestRegistryOpts {
+    /**
+     * Dev leniency: while true, TIMING strikes log and never suspend (the throw
+     * ladder still bites). Wired to `engine.enableTelemetry()` — i.e. devtools
+     * attached — so stepping in a debugger cannot suspend a healthy guest.
+     */
+    readonly lenient?: () => boolean;
+    readonly onFault?: (id: string, err: unknown) => void;
+    readonly onNotice?: (message: string) => void;
+}
+export declare function createGuestRegistry(world: World, opts?: GuestRegistryOpts): GuestRegistryInternal;

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

@@ -50,6 +50,14 @@ export interface ReflectorRegistry {
     /** Every registered reflector, registration order (devtools enumeration —
      *  independent of telemetry; a reflector idle since boot still lists). */
     names(): readonly string[];
+    /** Arm flush timing (idempotent). Costs one `performance.now()` pair per
+     *  flushed reflector per frame, so it rides `engine.enableTelemetry()` and is
+     *  off by default — the same opt-in posture as per-system timing. */
+    armTelemetry(): void;
+    /** Total µs of the most recent `flushAll` (0 until armed). */
+    lastFlushMicros(): number;
+    /** Per-reflector µs of the most recent `flushAll` (empty until armed). */
+    lastFlushDetail(): ReadonlyMap<string, number>;
 }
 export declare function createReflectorRegistry(world: World, opts?: {
     onFault?: (name: string, err: unknown) => void;

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

@@ -19,6 +19,8 @@
  * remain reviewed constants (RUNTIME_BUDGETS) in v1 — recorded.
  */
 import type { Entity, World } from "@vibecook/strata-ecs";
+import { type BehaviorRuntime } from "../behavior/runtime";
+import type { AnyBehaviorDef } from "../behavior/types";
 import { type Engine } from "../engine/engine";
 import type { FrameControl } from "../engine/frame-control";
 import { type InteractionStack } from "../interaction/install";
@@ -42,6 +44,13 @@ export interface CanvasEngineOpts {
     }[];
     /** Registered tools (definition happens at defineTool; validated). */
     readonly tools?: readonly Tool[];
+    /**
+     * Behaviors this engine runs (design-009). Definition is the import
+     * side-effect; listing them here COMPILES and installs them — a behavior that
+     * is defined but never registered costs nothing and does nothing, which is
+     * what makes "a plugin declared it" and "this engine runs it" separable.
+     */
+    readonly behaviors?: readonly AnyBehaviorDef[];
     readonly budgets?: {
         readonly keepMounted?: number;
         readonly fboBytes?: number;
@@ -166,6 +175,13 @@ export interface StageControl {
 export interface CanvasEngine {
     readonly world: World;
     readonly engine: Engine;
+    /**
+     * The behavior runtime (design-009 §6): attach/detach/has/read for
+     * runtime-class behaviors, plus `list()` for devtools and the doctor.
+     * DURABLE attachment is deliberately absent — it is a document op and goes
+     * through `tx.attach` inside a transaction, so it syncs and undoes.
+     */
+    readonly behaviors: BehaviorRuntime;
     readonly stack: InteractionStack;
     readonly runtime: WidgetRuntime & {
         uninstall(): void;

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

@@ -14,6 +14,7 @@
 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";
+import type { LiveWriter } from "./live-writer";
 export interface GuardedTx {
     spawnPrefab(prefab: Prefab, overrides?: readonly ComponentInit[]): Entity;
     /** Raw spawn — entity is unknown to the guard (prefer spawnPrefab). */
@@ -32,6 +33,29 @@ export interface GuardedTx {
     /** 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;
+    /**
+     * Animation-integrated write (petition I15): ONE commit owns the capture, the
+     * durable final, and the glide. `from` is read AT CALL TIME (pre-commit by
+     * construction), the final lands in THIS transaction — inheriting its
+     * `undoable` — and after a successful seal the tail installs the verified
+     * public-surface glide: `TransformTween` (which GRANTS the divergence) then a
+     * live rewind to `from`. One commit, one undo entry, no double-write.
+     *
+     * `animateMs` absent/0 = snap (no tween attached at all). A `Grab`-held
+     * entity is SKIPPED — the gesture owns its divergence. An entity already
+     * tweening is RETARGETED (its `toX/toY` rewritten) rather than restarted, so
+     * a re-layout mid-glide re-aims instead of completing at a stale target.
+     *
+     * Requires `opts.live` (the session's LiveWriter) — without it the rewind
+     * could not be divergence-guarded, so the call refuses rather than writing
+     * around the guard.
+     */
+    move(e: Entity, to: {
+        x: number;
+        y: number;
+    }, opts?: {
+        animateMs?: number;
+    }): void;
 }
 interface GuardedEditor {
     set<S>(c: Component<S>, v: S): GuardedEditor;
@@ -39,6 +63,7 @@ interface GuardedEditor {
 interface TxDoc {
     transaction(fn: (tx: Mutator) => void, opts?: {
         undoable?: boolean;
+        meta?: Record<string, unknown>;
     }): void;
 }
 export interface GuardedTxOpts {
@@ -48,6 +73,38 @@ export interface GuardedTxOpts {
      * first-⌘Z-removes-a-seed quirk). Default true: one tx = one undo step.
      */
     readonly undoable?: boolean;
+    /**
+     * The session's live writer. Required by {@link GuardedTx.move} (its
+     * post-commit rewind is a live write to a doc cell, legal only under the
+     * tween grant) and by the post-seal retarget sweep below.
+     */
+    readonly live?: LiveWriter;
+    /** Optional entity → doc-key probe; when absent every entity is treated as
+     *  durable-if-Position-eligible. Used to skip runtime-only movers' tx write. */
+    readonly keyOf?: (e: Entity) => string | undefined;
+    /**
+     * Per-commit PROVENANCE (strata 0.12.0, petition 9): a small record carried
+     * in-CRDT with the batch, so a receiving peer can say who wrote this and why.
+     * The behavior framework stamps `{ behavior, label }` on every `ctx.commit`
+     * (design-009 §4.4 — `label` is a stable machine id, never display text).
+     * Note that shallow saves erase provenance below the compaction boundary, so
+     * it is diagnostics, never a data dependency.
+     */
+    readonly meta?: Record<string, unknown>;
 }
 export declare function guardedTransaction(doc: TxDoc, world: World, run: (tx: GuardedTx) => void, opts?: GuardedTxOpts): void;
+/**
+ * Retarget every live tween onto its DURABLE truth — the undo/redo chokepoint
+ * (petition I15). Undo does not pass through {@link guardedTransaction}: it is
+ * strata's own local batch, so a glide in flight when ⌘Z lands would otherwise
+ * complete at the pre-undo target and strand the cell exactly as above.
+ *
+ * `durablePositionOf` reads the committed value (the doc's, not the runtime's).
+ * A tween whose entity has no durable Position is left alone — nothing to
+ * reconcile against.
+ */
+export declare function retargetTweensToDoc(world: World, entities: Iterable<Entity>, durablePositionOf: (e: Entity) => {
+    x: number;
+    y: number;
+} | undefined): void;
 export {};

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

@@ -3,7 +3,7 @@
  * 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.1.0";
+export declare const CORE_VERSION = "0.6.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, OrderPlace, Pipeline, Query, Relation, Resource, System, SystemCtx, Tag, TickSystem, World, } from "@vibecook/strata-ecs";
@@ -15,6 +15,12 @@ export { createPipelineRegistry, PHASE_GROUPS, type AnySystem, type PhaseGroup,
 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 { createGuestRegistry, GUEST_BUDGET, type GuestFactory, type GuestFrame, type GuestGeneration, type GuestInstance, type GuestLedgerRecord, type GuestRegistry, type GuestRegistryOpts, type GuestRun, type GuestSpec, type GuestStatus, } from "./engine/guests";
+export { behaviors, defineBehavior } from "./behavior/define-behavior";
+export { BEHAVIOR_DEFAULT_PHASE, BEHAVIOR_PHASES, type AnyBehaviorAttachSpec, type AnyBehaviorDef, type BehaviorAttachSpec, type BehaviorChanges, type BehaviorCtxBase, type BehaviorCtxFor, type BehaviorFrame, type BehaviorHandle, type BehaviorHooks, type BehaviorPhase, type BehaviorQuery, type BehaviorQuerySpec, type BehaviorRead, type BehaviorSchema, type BehaviorSpec, type BehaviorStore, type BehaviorTx, type BehaviorWorld, type DataOf, type DurableBehaviorCtx, type EphemeralBehaviorCtx, type PeerFacet, type RuntimeBehaviorCtx, } from "./behavior/types";
+export { compileBehavior, isDurableEligible, type CompiledBehavior } from "./behavior/compile";
+export { behaviorMarkerKey, classifyBehaviorVersion, docBehaviorVersion, stampBehaviorMarker, BEHAVIOR_MARKER_PREFIX, type BehaviorMeta, type BehaviorVerdict, } from "./behavior/migrate";
+export { createBehaviorHarness, type BehaviorHarness, type BehaviorHarnessOpts, type HarnessCommit, } from "./behavior/harness";
 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";
@@ -22,6 +28,7 @@ export { writeRuntimeResource } from "./guards/resource-writer";
 export * from "./catalog";
 export * from "./helpers/phase-set";
 export * from "./helpers/version-stamps";
+export * from "./helpers/churn-guard";
 export * from "./ops/arrange";
 export * from "./ops/selection";
 export * from "./ops/cascade";
@@ -48,9 +55,9 @@ 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 WidgetBehaviorDecl, type WidgetBehaviorEntry, 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 { attachSpawnBehaviors, 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";

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/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

@@ -1,4 +1,5 @@
 import type { Component, Tag } from "@vibecook/strata-ecs";
+import type { AnyBehaviorAttachSpec, AnyBehaviorDef } from "../behavior/types";
 import { type Prefab } from "../schema/prefab";
 import type { PropSpec, PropsDecl } from "./props";
 export type WidgetSurface = "dom" | "gl";
@@ -11,6 +12,42 @@ 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[];
+}
+/**
+ * A behavior pre-attachment on a widget type: the bare handle for defaults, or
+ * `Behavior.with({...})` for a starting value (design-009 §6).
+ */
+export type WidgetBehaviorDecl = AnyBehaviorDef | AnyBehaviorAttachSpec;
+/** Normalized pre-attachment (registry truth for the spawn + equip paths). */
+export interface WidgetBehaviorEntry {
+    readonly behavior: AnyBehaviorDef;
+    readonly data: Readonly<Record<string, unknown>>;
+}
 export interface WidgetInteraction {
     readonly selectable?: boolean;
     readonly movable?: boolean;
@@ -26,6 +63,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 +157,28 @@ 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[];
+    /**
+     * Behaviors every instance of this type carries (design-009 §6). The store
+     * class routes HOW, exactly as it routes everything else:
+     *  - `durable` behaviors are attached as post-spawn `addComponent` calls in
+     *    the SAME spawn transaction — document truth, so they sync and undo with
+     *    the widget. (Not spawn-init overrides: those hit the prefab's
+     *    all-builds eligibility throw in `instantiate.ts`.)
+     *  - `runtime` behaviors are stamped at PROJECTION by the equip system,
+     *    beside the capability tags. That is the only mechanism that also equips
+     *    a widget arriving from a remote peer or a restored file, which a rider
+     *    attached at spawn time would miss on every peer but the author's.
+     * Ephemeral behaviors are refused: an ephemeral instance IS the local
+     * presence peer, so it cannot ride a widget at all.
+     */
+    readonly behaviors?: readonly WidgetBehaviorDecl[];
     /**
      * fromVersion → idempotent absolute transform (M9's `runMigrations` runs the
      * chain at open; `prev`/return are flat prop records spanning every group).
@@ -146,7 +224,13 @@ 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>>>;
+    /** Pre-attached behaviors, normalized (spawn tx for durable, equip for runtime). */
+    readonly behaviors: readonly WidgetBehaviorEntry[];
     /** Normalized author preview component (opaque; react narrows). null = none declared. */
     readonly previewComponent: unknown;
     /** Prop overrides for the default real-component preview mount (validated names). */
@@ -158,6 +242,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/core/src/widget/props.d.ts

@@ -25,7 +25,7 @@ export interface StandardSchemaV1<Input = unknown, Output = Input> {
         };
     };
 }
-export type PropSpec = StringSpec | NumberSpec | BooleanSpec | EnumSpec | JsonSpec;
+export type PropSpec = StringSpec | NumberSpec | BooleanSpec | EnumSpec | JsonSpec | EntityKeySpec;
 export interface StringSpec extends StandardSchemaV1<unknown, string> {
     readonly kind: "string";
     readonly default?: string;
@@ -52,6 +52,19 @@ export interface JsonSpec extends StandardSchemaV1<unknown, unknown> {
     /** Serialized default (derived from the inner root when not given). */
     readonly default?: string;
 }
+/**
+ * A DURABLE entity reference (design-009 §4.2): the doc key of another entity,
+ * stored as a plain string cell. This is the ONLY legal cross-entity reference
+ * in behavior data — Law 7 bans `eid` from durable cells because a runtime
+ * handle means nothing to the peer that receives it, while a doc key survives
+ * the wire, the file, and a reload. Empty string = no reference; resolution is
+ * `ctx.entityFor(key)`, which may legitimately return undefined while the
+ * target is not yet projected.
+ */
+export interface EntityKeySpec extends StandardSchemaV1<unknown, string> {
+    readonly kind: "entityKey";
+    readonly default?: string;
+}
 /** Shapes legal only INSIDE p.json (validation-only, never components). */
 export type JsonShape = {
     readonly kind: "string";
@@ -91,8 +104,29 @@ export declare const p: {
     json(inner: JsonShape, opts?: {
         default?: unknown;
     }): JsonSpec;
+    /**
+     * A durable reference to another entity by DOC KEY (design-009 §4.2).
+     * Behavior-facing: `defineWidget` props have no use for it (a widget's
+     * references are relations), but nothing rejects it there either — it is an
+     * ordinary string cell with a declared meaning.
+     */
+    entityKey(opts?: {
+        default?: string;
+    }): EntityKeySpec;
     array(item: JsonShape): JsonShape;
     object(fields: Readonly<Record<string, JsonShape>>): JsonShape;
 };
 /** A widget props declaration: top-level named specs (the compiler's input). */
 export type PropsDecl = Readonly<Record<string, PropSpec>>;
+/**
+ * The CELL default for a spec — the value a whole-component write fills in for
+ * an untouched field, and the value a generated strata field declares.
+ *
+ * One function, three callers (widget spawn defaults, `defineWidget`'s
+ * essential set, `defineBehavior`'s attach defaults): each used to carry its
+ * own else-if chain over `spec.kind`, and each chain had to be found and
+ * amended when `p.entityKey` was added — one of them by inspection rather than
+ * by a type error, since the chains end in a catch-all `else`. It lives here,
+ * beside the specs whose shape it reads.
+ */
+export declare function defaultValueOf(spec: PropSpec): string | number | boolean;

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

@@ -8,7 +8,9 @@
  */
 import type { Entity, OrderPlace, Relation, World } from "@vibecook/strata-ecs";
 import type { DurableStore } from "@vibecook/strata-ecs/durable";
+import { type GuardedTx } from "../guards/guarded-tx";
 import { type ComponentInit } from "../schema/prefab";
+import { type WidgetType } from "./define-widget";
 export interface SpawnWidgetOpts {
     readonly x: number;
     readonly y: number;
@@ -47,4 +49,16 @@ export declare function widgetSpawnInits(type: string, opts: SpawnWidgetOpts): {
     prefab: import("../schema/prefab").Prefab;
     overrides: ComponentInit[];
 };
+/**
+ * Attach a widget type's DURABLE pre-attached behaviors (design-009 §6), as
+ * post-spawn `addComponent` calls inside the spawn transaction.
+ *
+ * Post-spawn rather than spawn-init overrides: `instantiate` checks every
+ * override against the prefab's eligible set, and a behavior is eligible on
+ * every entity by definition (BF-D6) — it is not in any prefab's set and never
+ * will be. Runtime pre-attachments are NOT here: they ride projection (the
+ * equip system), which is the only path that also equips a widget arriving
+ * from a peer or a restored file.
+ */
+export declare function attachSpawnBehaviors(tx: GuardedTx, widget: WidgetType, e: Entity): void;
 export declare function spawnWidget(store: DurableStore, world: World, type: string, opts: SpawnWidgetOpts): Entity;

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";