@vibecook/ice 0.4.0 → 0.6.0

package/dist/types/packages/core/src/behavior/world-view.d.ts

@@ -0,0 +1,36 @@
+import type { Component, Entity, Query, Relation, Resource, SystemCtx, Tag, World } from "@vibecook/strata-ecs";
+import type { AnyBehaviorDef, BehaviorQuery, BehaviorQuerySpec, BehaviorWorld } from "./types";
+export declare function createBehaviorWorld(world: World): BehaviorWorld;
+/**
+ * The compiled-query cache for one behavior. Keyed on the term identity list,
+ * so the common case (a behavior calling `ctx.query` with the same spec every
+ * frame) compiles ONCE — `defineQuery` identity is strata's own cache key for
+ * the matched-archetype list, so re-compiling per call would defeat two caches.
+ */
+export declare function createQueryScope(behavior: AnyBehaviorDef, allowed: ReadonlySet<Component | Tag>): (walker: BehaviorWalker, spec: BehaviorQuerySpec) => BehaviorQuery;
+/**
+ * Where a behavior's walks and structural ops go, which depends on WHERE it is
+ * running — and the difference is not cosmetic.
+ *
+ * In a pipeline phase the behavior is inside a system: walks go through
+ * `SystemCtx` (attributed — strata's enforced read path), and structural ops
+ * are DEFERRED to the phase boundary because immediate `world.*` structural
+ * mutation throws at iteration depth > 0.
+ *
+ * At the publish slot there is no running system and no iteration bracket:
+ * walks are plain `world.query` (unattributed — nothing to attribute them to),
+ * and structural ops are immediate and legal. Ephemeral behaviors live here,
+ * which is exactly why eph structural writes are legal for them and illegal
+ * for everyone else.
+ */
+export interface BehaviorWalker {
+    each(q: Query, fn: (e: Entity) => void): void;
+    first(q: Query): Entity | undefined;
+    addComponent(e: Entity, c: Component, v: unknown): void;
+    removeComponent(e: Entity, c: Component): void;
+}
+export declare function systemWalker(ctx: SystemCtx): BehaviorWalker;
+export declare function publishWalker(world: World): BehaviorWalker;
+/** The term set a behavior may query: its own component ∪ declared components/tags. */
+export declare function allowedQueryTerms(behavior: AnyBehaviorDef, readComponents: readonly Component[], readTags: readonly Tag[]): ReadonlySet<Component | Tag>;
+export type { Relation, Resource };

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

@@ -5,6 +5,12 @@
  *     setFrameInfo        FrameInfo resource — value write, pre-tick
  *     world.sync()        durable + presence drains land; projections place
  *     world.tick(...)     the phase-group pipeline (pipeline.ts)
+ *     guests              [2026-08-15, petition I14] the NAMED guest slot:
+ *                         plugin/host frame work under a circuit breaker
+ *                         (guests.ts). BEFORE publish so derived state has
+ *                         settled when presence I/O reads it, and before
+ *                         notify so the same frame reflects it. Guests are
+ *                         fault-ISOLATED — the one tier here that is.
  *     publish hooks       POST-TICK, PRE-NOTIFY: presence I/O home — eph
  *                         structural ops are illegal for the whole tick, this
  *                         step is theirs; `world.*` is legal here (outside the
@@ -22,6 +28,7 @@
 import type { World } from "@vibecook/strata-ecs";
 import type { AnySystem } from "./pipeline";
 import { type FrameControl } from "./frame-control";
+import { type GuestRegistry } from "./guests";
 import { type PhaseGroup } from "./pipeline";
 import { type ReflectorDef } from "./reflectors";
 export type PublishHook = (world: World) => void;
@@ -38,10 +45,29 @@ export interface FrameTelemetry {
     readonly systems: readonly SystemRunRecord[];
     readonly phaseFlushMicros: ReadonlyMap<string, number>;
     readonly reflectorsFlushed: readonly string[];
+    /**
+     * Total reflector-flush cost, µs (post-notify — OUTSIDE the tick, which is
+     * why it can never appear in `phaseFlushMicros`: that map is keyed by strata
+     * PHASE names and reflect is not a phase. Devtools' "reflect" lane read that
+     * map until 2026-08-15 and therefore never reported at all).
+     */
+    readonly reflectMicros: number;
+    /** Per-reflector flush cost, µs, for the same frame (registration order). */
+    readonly reflectorMicros: ReadonlyMap<string, number>;
 }
 export interface EngineOpts {
     /** Reflector fault sink (default: console.error, skip this frame). */
     readonly onReflectorFault?: (name: string, err: unknown) => void;
+    /** Guest fault sink (default: console.error). A guest throwing is contained
+     *  by the breaker; hosts route this to their own diagnostics. */
+    readonly onGuestFault?: (id: string, err: unknown) => void;
+    /**
+     * Guest breaker notices — suspensions and lenient-mode overruns (default:
+     * console.warn). Hosts SHOULD route this: a suspended derived guest means
+     * derived state silently stops updating, which reads to a user as a broken
+     * document rather than a broken plugin (design-009 §7).
+     */
+    readonly onGuestNotice?: (message: string) => void;
 }
 export interface Engine {
     readonly world: World;
@@ -53,6 +79,13 @@ export interface Engine {
     reflectorNames(): readonly string[];
     /** Register a publish-step hook (post-tick, pre-notify presence I/O). Returns a remover. */
     onPublish(hook: PublishHook): () => void;
+    /**
+     * The guest runtime (petition I14): frame-cadence work the engine did not
+     * write — plugin systems, host derived-state jobs, compiled behaviors — run
+     * in a named slot between the tick and the publish hooks, each fault-isolated
+     * and budgeted by a circuit breaker (guests.ts).
+     */
+    readonly guests: GuestRegistry;
     /** Run one full frame. `now` in ms (rAF timestamp or a test counter). */
     step(now: number): void;
     /**
@@ -65,8 +98,12 @@ export interface Engine {
      * hand exactly as before.
      */
     readonly frame: FrameControl;
-    /** Arm per-system run/skip + µs collection (idempotent; costs timer calls per system). */
+    /** Arm per-system run/skip + µs collection (idempotent; costs timer calls per system).
+     *  Also puts the guest breaker in LENIENT mode — devtools attached means a
+     *  debugger breakpoint must not suspend a healthy guest. */
     enableTelemetry(): void;
+    /** Tear down guest instances (the facade calls this from `dispose()`). */
+    disposeGuests(): void;
     /** The most recent completed frame's readout (undefined until telemetry armed + one step). */
     lastFrame(): FrameTelemetry | undefined;
 }

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, 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 { 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/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";
@@ -37,6 +38,16 @@ export interface WidgetRenameEntry {
     /** 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;
@@ -153,6 +164,21 @@ export interface WidgetDef {
      * 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).
@@ -203,6 +229,8 @@ export interface WidgetType {
     /** 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). */

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

@@ -17,6 +17,15 @@
  * 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.
+ *
+ * THE LOOP OUTLIVES A THROWING STEP (2026-08-15, petition I14). Until this fix
+ * the reschedule sat on the line AFTER `engine.step(now)`, so ONE throw from a
+ * publish hook (which propagate loudly by design — engine.ts) escaped the rAF
+ * callback, left `handle` un-renewed, and killed the canvas PERMANENTLY: with
+ * `parked` still false, `wake` early-returns forever, so even freeze/thaw could
+ * not restart it. Recovery needed a fresh `startRafLoop`. The next frame is now
+ * scheduled in a `finally`, so a faulting frame is loud but survivable — the
+ * throw still reaches the browser's error handler; only the death is gone.
  */
 import type { Engine } from "@ice/core";
 export declare function startRafLoop(engine: Engine): () => void;