@vibecook/ice 0.6.0 → 0.7.0

package/dist/{chunk-ELCBCTKY.js → chunk-55QCOE74.js}

@@ -16,7 +16,7 @@ import {
   createSiblingOrderIndex,
   defineQuery,
   widgets
-} from "./chunk-JLXETATP.js";
+} from "./chunk-LATXYFMO.js";
 import {
   planeCssTransform,
   worldToScreen
@@ -1160,4 +1160,4 @@ export {
   wireMeasurement,
   DOM_VERSION
 };
-//# sourceMappingURL=chunk-ELCBCTKY.js.map
+//# sourceMappingURL=chunk-55QCOE74.js.map

package/dist/{chunk-BFT7YWS2.js → chunk-5OU3OWDH.js}

@@ -12,7 +12,7 @@ import {
   keyboardClaimOf,
   startRafLoop,
   wireMeasurement
-} from "./chunk-ELCBCTKY.js";
+} from "./chunk-55QCOE74.js";
 import {
   ActiveTool,
   DurableUndoStatus,
@@ -33,7 +33,7 @@ import {
   tools,
   widgets,
   writeRuntimeResource
-} from "./chunk-JLXETATP.js";
+} from "./chunk-LATXYFMO.js";
 
 // ../react/src/hooks.ts
 import { createContext, useCallback, useContext, useMemo, useRef, useSyncExternalStore } from "react";
@@ -673,4 +673,4 @@ export {
   InfiniteCanvas,
   REACT_VERSION
 };
-//# sourceMappingURL=chunk-BFT7YWS2.js.map
+//# sourceMappingURL=chunk-5OU3OWDH.js.map

package/dist/{chunk-JLXETATP.js → chunk-LATXYFMO.js}

@@ -843,6 +843,7 @@ function createGuestRegistry(world, opts) {
         },
         fault(err) {
           if (!entry.alive || disposed) return;
+          if (entry.suspended) return;
           entry.faultedThisFrame = true;
           entry.accrued = true;
           entry.consecutiveThrows++;
@@ -1733,6 +1734,102 @@ function validate(name, spec, phase2) {
     }
   }
 }
+function cloneJsonShape(shape) {
+  switch (shape.kind) {
+    case "string":
+    case "number":
+    case "boolean":
+      return { kind: shape.kind };
+    case "enum":
+      return { kind: "enum", options: [...shape.options] };
+    case "array":
+      return { kind: "array", item: cloneJsonShape(shape.item) };
+    case "object":
+      return {
+        kind: "object",
+        fields: Object.fromEntries(
+          Object.entries(shape.fields).map(([name, field15]) => [name, cloneJsonShape(field15)])
+        )
+      };
+  }
+}
+function describeProp(spec) {
+  switch (spec.kind) {
+    case "string":
+      return {
+        kind: "string",
+        ...spec.default === void 0 ? {} : { default: spec.default }
+      };
+    case "number":
+      return {
+        kind: "number",
+        ...spec.default === void 0 ? {} : { default: spec.default },
+        ...spec.min === void 0 ? {} : { min: spec.min },
+        ...spec.max === void 0 ? {} : { max: spec.max }
+      };
+    case "boolean":
+      return {
+        kind: "boolean",
+        ...spec.default === void 0 ? {} : { default: spec.default }
+      };
+    case "enum":
+      return {
+        kind: "enum",
+        options: [...spec.options],
+        ...spec.default === void 0 ? {} : { default: spec.default }
+      };
+    case "json":
+      return {
+        kind: "json",
+        inner: cloneJsonShape(spec.inner),
+        ...spec.default === void 0 ? {} : { default: spec.default }
+      };
+    case "entityKey":
+      return {
+        kind: "entityKey",
+        ...spec.default === void 0 ? {} : { default: spec.default }
+      };
+  }
+}
+var DESCRIPTION_HOOK_ORDER = [
+  "init",
+  "update",
+  "changed",
+  "tick",
+  "dispose"
+];
+function describeBehavior(behavior) {
+  const reads = [];
+  for (const read of behavior.reads) {
+    const description = classifyRead(read);
+    if (description !== void 0) reads.push(description);
+  }
+  const writes = [];
+  for (const component of behavior.writes) {
+    const meta = schemaMeta.component(component);
+    if (meta !== void 0) writes.push(meta.name);
+  }
+  return {
+    id: behavior.name,
+    store: behavior.store,
+    derived: behavior.derived,
+    deriveDuringGesture: behavior.deriveDuringGesture,
+    version: behavior.version,
+    phase: behavior.phase,
+    ...behavior.budgetMs === void 0 ? {} : { budgetMs: behavior.budgetMs },
+    tickWhile: behavior.tickWhile,
+    schema: Object.entries(behavior.schema).map(([name, spec]) => ({
+      name,
+      spec: describeProp(spec)
+    })),
+    reads,
+    writes,
+    migrationFrom: Object.keys(behavior.migrate).map(Number).sort((left, right) => left - right),
+    hooks: DESCRIPTION_HOOK_ORDER.filter(
+      (hook) => typeof behavior.on[hook] === "function"
+    )
+  };
+}
 function defineBehavior(name, spec) {
   const phase2 = spec.phase ?? BEHAVIOR_DEFAULT_PHASE[spec.store];
   if (devGuardsEnabled()) validate(name, spec, phase2);
@@ -7399,6 +7496,19 @@ function allowedQueryTerms(behavior, readComponents, readTags) {
 // ../core/src/behavior/runtime.ts
 var INSTANCE_THROW_LIMIT = 3;
 var SUPPRESSION_WARN_FRAMES = 600;
+function isThenable(value) {
+  return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
+}
+var BehaviorHookThenableError = class extends TypeError {
+};
+function invokeHook(behavior, hook, body) {
+  const result = body();
+  if (!isThenable(result)) return;
+  void Promise.resolve(result).catch(() => void 0);
+  throw new BehaviorHookThenableError(
+    `ice: behavior "${behavior}" ${hook} returned a thenable; behavior hooks are synchronous`
+  );
+}
 function isClaimed(world, e) {
   if (!world.isAlive(e)) return false;
   for (const claimant of world.getReverse(e, Captures)) {
@@ -7426,6 +7536,7 @@ function cellForBehavior(world, b, e, patch) {
 function createBehaviorRuntime(opts) {
   const { world } = opts;
   const nodes = /* @__PURE__ */ new Map();
+  let nextRegistrationSequence = 0;
   const onFault = opts.onFault ?? ((behavior, hook, entity, err) => {
     console.error(`[ice] behavior "${behavior}" ${hook}${entity === void 0 ? "" : ` on entity ${entity}`} threw`, err);
   });
@@ -7437,8 +7548,42 @@ function createBehaviorRuntime(opts) {
       for (const n of nodes.values()) n.markGeneration();
     }
   });
+  const publishOrder = [];
+  const pendingWithdrawals = [];
+  let publishHookRemover;
+  function ensurePublishHook() {
+    if (publishHookRemover !== void 0) return;
+    publishHookRemover = opts.engine.onPublish(() => {
+      if (pendingWithdrawals.length > 0) {
+        const jobs = pendingWithdrawals.splice(0, pendingWithdrawals.length);
+        for (const job of jobs) job();
+      }
+      if (publishOrder.length > 0) {
+        const pass = publishOrder.slice();
+        for (const node of pass) if (!node.isStopped()) node.runPublish();
+      }
+      if (publishOrder.length === 0 && pendingWithdrawals.length === 0) {
+        publishHookRemover?.();
+        publishHookRemover = void 0;
+      }
+    });
+  }
+  function installPublishNode(node) {
+    publishOrder.push(node);
+    ensurePublishHook();
+    return () => {
+      const i = publishOrder.indexOf(node);
+      if (i !== -1) publishOrder.splice(i, 1);
+    };
+  }
+  function deferWithdrawal(job) {
+    pendingWithdrawals.push(job);
+    ensurePublishHook();
+  }
   class Node {
     b;
+    orderKey;
+    registrationSequence;
     compiled;
     own;
     /** The same handle, typed for `readField`'s keyof-based field parameter. */
@@ -7449,6 +7594,19 @@ function createBehaviorRuntime(opts) {
     peersQuery;
     /** Ephemeral only: the local peer this node last published a facet on. */
     facetPeer;
+    /** The ephemeral singleton was quarantined THIS generation (I17). */
+    singletonQuarantined = false;
+    /** Uninstalled — a captured ctx.write closure must go inert (I17). */
+    stopped = false;
+    /** Per-FRAME strike dedupe (review finding 4): the ladder counts FRAMES,
+     *  not calls — 500 async instances must cost ONE strike, not write 500
+     *  into a ledger hosts persist across engine generations. Keyed by
+     *  FrameInfo.tick because no single pass entry point runs every frame
+     *  (the delivery system is runIf-gated off on no-churn frames while the
+     *  tick system keeps running). */
+    strikeFrame = -1;
+    thenableStruckPass = false;
+    spanStruckPass = false;
     /** The session whose version state has already been checked (§5.6). */
     checkedSession;
     /**
@@ -7519,8 +7677,10 @@ function createBehaviorRuntime(opts) {
     /** Set for the duration of a delivery/tick pass; see BehaviorWalker. */
     walker;
     ctx;
-    constructor(b) {
+    constructor(b, registration, registrationSequence) {
       this.b = b;
+      this.orderKey = registration.orderKey;
+      this.registrationSequence = registrationSequence;
       this.own = b.component;
       this.ownFields = b.component;
       this.schema = b.schema;
@@ -7543,6 +7703,7 @@ function createBehaviorRuntime(opts) {
       this.guest = opts.engine.guests.addDriven({
         id: `behavior:${b.name}`,
         ...b.budgetMs !== void 0 ? { budgetMs: b.budgetMs } : {},
+        ...registration.ledger === void 0 ? {} : { ledger: registration.ledger },
         busy: () => this.owed()
       });
       this.ctx = this.buildCtx();
@@ -7576,6 +7737,7 @@ function createBehaviorRuntime(opts) {
       this.readsCollector?.dispose();
       this.ownCollector = void 0;
       this.readsCollector = void 0;
+      this.withdrawFacet();
     }
     /**
      * Resumed. Fresh collectors journal from NOW, so everything that happened
@@ -7597,18 +7759,10 @@ function createBehaviorRuntime(opts) {
       if (this.compiled.readRelations.length > 0) {
         world.orderStamp(0, this.compiled.readRelations[0]);
       }
+    }
+    installExecution() {
       if (this.b.phase === "publish") {
-        this.removeSystems = opts.engine.onPublish(() => {
-          if (this.guest.suspended()) {
-            this.goCold();
-            return;
-          }
-          this.guest.run(() => {
-            if (this.b.store === "ephemeral") this.ensureFacet();
-            if (this.shouldDeliver()) this.runDeliver(publishWalker(world));
-            this.publishTick();
-          });
-        });
+        this.removeSystems = installPublishNode(this);
       } else {
         this.removeSystems = opts.engine.addSystems(
           this.b.phase,
@@ -7616,6 +7770,25 @@ function createBehaviorRuntime(opts) {
         );
       }
     }
+    /** The publish-slot body — driven by the runtime's one stable hook. */
+    runPublish() {
+      if (this.guest.suspended()) {
+        this.goCold();
+        return;
+      }
+      this.guest.run(() => {
+        if (this.b.store === "ephemeral") this.ensureFacet();
+        if (this.shouldDeliver()) this.runDeliver(publishWalker(world));
+        this.publishTick();
+      });
+    }
+    isStopped() {
+      return this.stopped;
+    }
+    uninstallExecution() {
+      this.removeSystems?.();
+      this.removeSystems = void 0;
+    }
     /** The version-marker surface for the current session, if it has one. */
     metaOf(session) {
       const snapshot = session?.store.snapshot;
@@ -7701,6 +7874,10 @@ function createBehaviorRuntime(opts) {
         this.facetPeer = void 0;
         return;
       }
+      if (this.singletonQuarantined) {
+        this.facetPeer = void 0;
+        return;
+      }
       if (peer === this.facetPeer && world.has(peer, this.own)) return;
       this.facetPeer = peer;
       if (!world.has(peer, this.own)) {
@@ -7711,6 +7888,48 @@ function createBehaviorRuntime(opts) {
         );
       }
     }
+    /**
+     * Withdraw the published facet (petition I17). An ephemeral facet is LIVE
+     * PUBLICATION — the local peer telling every remote peer "this value is
+     * current" — so every edge where the producer stops executing must reverse
+     * the publication too, or a disabled, suspended, or quarantined behavior
+     * keeps asserting its last value forever (remote peers have no TTL for a
+     * peer that is still connected). Idempotent by construction: presence
+     * absent, a dead peer (mid re-mint window), and an already-gone facet are
+     * all quiet no-ops. The removal goes through the PRESENCE writer, never
+     * `world.removeComponent`, because only the presence path encodes a
+     * tombstone remote projections honor.
+     */
+    withdrawFacet() {
+      if (this.b.store !== "ephemeral") return;
+      this.facetPeer = void 0;
+      const presence = opts.presence?.();
+      if (presence === void 0) return;
+      const peer = presence.localPeer;
+      if (!(world.isAlive(peer) && world.has(peer, this.own))) return;
+      const midTick = world.inImmediateProjectionUnsafeContext ?? false;
+      if (midTick) {
+        const behaviorName = this.b.name;
+        const own = this.own;
+        deferWithdrawal(() => {
+          const p2 = opts.presence?.();
+          if (p2 === void 0) return;
+          if (p2.localPeer !== peer) return;
+          if (!(world.isAlive(peer) && world.has(peer, own))) return;
+          try {
+            p2.eph.removeComponent(peer, own);
+          } catch (err) {
+            onFault(behaviorName, "withdraw", peer, err);
+          }
+        });
+        return;
+      }
+      try {
+        presence.eph.removeComponent(peer, this.own);
+      } catch (err) {
+        onFault(this.b.name, "withdraw", peer, err);
+      }
+    }
     /** The publish-slot twin of the tick SYSTEM (no query, no chunks). */
     publishTick() {
       const on = this.b.on;
@@ -7723,16 +7942,19 @@ function createBehaviorRuntime(opts) {
         const inst = this.instances.get(e);
         if (inst === void 0 || inst.failed || !inst.inited) continue;
         const data = this.dataOf(e);
-        this.callHook("tick", inst, faulted, () => {
-          on.tick?.(e, data, frame2, this.ctx);
-        });
+        this.callHook(
+          "tick",
+          inst,
+          faulted,
+          () => on.tick?.(e, data, frame2, this.ctx)
+        );
       }
       this.walker = void 0;
     }
     uninstall() {
+      this.stopped = true;
       this.endGeneration();
-      this.removeSystems?.();
-      this.removeSystems = void 0;
+      this.uninstallExecution();
       this.ownCollector?.dispose();
       this.readsCollector?.dispose();
       this.ownCollector = void 0;
@@ -7995,9 +8217,12 @@ function createBehaviorRuntime(opts) {
         for (const e of appeared) {
           const inst = this.instances.get(e);
           if (inst === void 0 || inst.failed) continue;
-          if (this.callHook("init", inst, faultedEntities, () => {
-            on.init?.(e, this.dataOf(e), this.ctx);
-          })) {
+          if (this.callHook(
+            "init",
+            inst,
+            faultedEntities,
+            () => on.init?.(e, this.dataOf(e), this.ctx)
+          )) {
             inst.inited = true;
           }
         }
@@ -8019,16 +8244,19 @@ function createBehaviorRuntime(opts) {
           if (valueEquals2(this.own, this.scratchCell, inst.prevCell)) continue;
           const data = this.viewOf(this.scratchCell, this.scratchData);
           const prev = this.viewOf(inst.prevCell, this.scratchPrevData);
-          this.callHook("update", inst, faultedEntities, () => {
-            on.update?.(e, data, prev, this.ctx);
-          });
+          this.callHook(
+            "update",
+            inst,
+            faultedEntities,
+            () => on.update?.(e, data, prev, this.ctx)
+          );
           this.copyInto(this.scratchCell, inst.prevCell);
         }
       }
       const anyVisible = this.visible.length > 0;
       if (on.changed !== void 0 && (full || (work?.readsFired ?? false) || lifted) && anyVisible) {
         try {
-          on.changed(this.ctx);
+          invokeHook(this.b.name, "changed", () => on.changed?.(this.ctx));
         } catch (err) {
           onFault(this.b.name, "changed", void 0, err);
           this.guest.fault(err);
@@ -8037,7 +8265,11 @@ function createBehaviorRuntime(opts) {
       if (on.dispose !== void 0) {
         for (const inst of departed) {
           try {
-            on.dispose(inst.e, this.ctx);
+            invokeHook(
+              this.b.name,
+              "dispose",
+              () => on.dispose?.(inst.e, this.ctx)
+            );
           } catch (err) {
             onFault(this.b.name, "dispose", inst.e, err);
           }
@@ -8062,9 +8294,12 @@ function createBehaviorRuntime(opts) {
         const inst = this.instances.get(e);
         if (inst === void 0 || inst.failed || !inst.inited) continue;
         const data = this.dataOf(e);
-        this.callHook("tick", inst, faulted, () => {
-          on.tick?.(e, data, frame2, this.ctx);
-        });
+        this.callHook(
+          "tick",
+          inst,
+          faulted,
+          () => on.tick?.(e, data, frame2, this.ctx)
+        );
       }
       this.walker = void 0;
     }
@@ -8076,15 +8311,33 @@ function createBehaviorRuntime(opts) {
      */
     callHook(hook, inst, faulted, body) {
       try {
-        body();
+        invokeHook(this.b.name, hook, body);
         inst.consecutiveThrows = 0;
         return true;
       } catch (err) {
         inst.consecutiveThrows++;
         onFault(this.b.name, hook, inst.e, err);
-        if (inst.consecutiveThrows >= INSTANCE_THROW_LIMIT) inst.failed = true;
+        if (inst.consecutiveThrows >= INSTANCE_THROW_LIMIT) {
+          inst.failed = true;
+          if (this.b.store === "ephemeral") this.singletonQuarantined = true;
+          this.withdrawFacet();
+        }
         faulted.add(inst.e);
-        if (faulted.size > 1) this.guest.fault(err);
+        const frameTick = world.getResource(FrameInfo)?.tick ?? -1;
+        if (frameTick !== this.strikeFrame) {
+          this.strikeFrame = frameTick;
+          this.thenableStruckPass = false;
+          this.spanStruckPass = false;
+        }
+        if (err instanceof BehaviorHookThenableError) {
+          if (!this.thenableStruckPass) {
+            this.thenableStruckPass = true;
+            this.guest.fault(err);
+          }
+        } else if (faulted.size > 1 && !this.spanStruckPass) {
+          this.spanStruckPass = true;
+          this.guest.fault(err);
+        }
         return false;
       }
     }
@@ -8094,14 +8347,19 @@ function createBehaviorRuntime(opts) {
       if (on.dispose !== void 0) {
         for (const inst of this.instances.values()) {
           try {
-            on.dispose(inst.e, this.ctx);
+            invokeHook(
+              this.b.name,
+              "dispose",
+              () => on.dispose?.(inst.e, this.ctx)
+            );
           } catch (err) {
             onFault(this.b.name, "dispose", inst.e, err);
           }
         }
       }
       this.instances.clear();
-      this.facetPeer = void 0;
+      this.withdrawFacet();
+      this.singletonQuarantined = false;
       this.suppressed.clear();
       this.suppressedFrames.clear();
       this.carry.clear();
@@ -8199,6 +8457,7 @@ function createBehaviorRuntime(opts) {
     }
     /** `ctx.write(patch)` for the ephemeral class — publish THIS peer's facet. */
     writeFacet(patch) {
+      if (this.stopped || this.cold || this.singletonQuarantined) return;
       const presence = opts.presence?.();
       if (presence === void 0) return;
       const peer = presence.localPeer;
@@ -8368,10 +8627,32 @@ function createBehaviorRuntime(opts) {
         instances: this.instances.size,
         failed,
         ticking: this.b.on.tick === void 0 ? 0 : this.instances.size - failed,
-        suspended: this.guest.suspended()
+        suspended: this.guest.suspended(),
+        quarantined: this.singletonQuarantined
       };
     }
   }
+  function orderedNodes() {
+    return [...nodes.values()].sort((left, right) => {
+      if (left.orderKey !== void 0 || right.orderKey !== void 0) {
+        if (left.orderKey === void 0) return 1;
+        if (right.orderKey === void 0) return -1;
+        if (left.orderKey < right.orderKey) return -1;
+        if (left.orderKey > right.orderKey) return 1;
+      }
+      return left.registrationSequence - right.registrationSequence;
+    });
+  }
+  function reorderExecution(inserted) {
+    const order = orderedNodes();
+    const at = order.indexOf(inserted);
+    if (at === order.length - 1) {
+      inserted.installExecution();
+      return;
+    }
+    for (let i = order.length - 1; i > at; i--) order[i]?.uninstallExecution();
+    for (let i = at; i < order.length; i++) order[i]?.installExecution();
+  }
   function safeParse(raw) {
     try {
       return JSON.parse(raw);
@@ -8380,13 +8661,17 @@ function createBehaviorRuntime(opts) {
     }
   }
   return {
-    register(b) {
+    register(b, options = {}) {
+      if (options.orderKey !== void 0 && (typeof options.orderKey !== "string" || options.orderKey.length === 0)) {
+        throw new TypeError("ice: behavior registration orderKey must be a non-empty string");
+      }
       if (nodes.has(b.name)) {
         throw new Error(`ice: behavior "${b.name}" is already registered with this engine.`);
       }
-      const node = new Node(b);
+      const node = new Node(b, options, nextRegistrationSequence++);
       nodes.set(b.name, node);
       node.install();
+      reorderExecution(node);
       return () => {
         if (nodes.get(b.name) !== node) return;
         nodes.delete(b.name);
@@ -8394,7 +8679,7 @@ function createBehaviorRuntime(opts) {
       };
     },
     registered() {
-      return [...nodes.values()].map((n) => n.b);
+      return orderedNodes().map((n) => n.b);
     },
     attach(e, b, data) {
       if (b.store === "durable") {
@@ -8427,12 +8712,18 @@ function createBehaviorRuntime(opts) {
       return cell;
     },
     list() {
-      return [...nodes.values()].map((n) => n.status());
+      return orderedNodes().map((n) => n.status());
     },
     dispose() {
       stopResetWatch();
       for (const n of nodes.values()) n.uninstall();
       nodes.clear();
+      if (pendingWithdrawals.length > 0) {
+        const jobs = pendingWithdrawals.splice(0, pendingWithdrawals.length);
+        for (const job of jobs) job();
+      }
+      publishHookRemover?.();
+      publishHookRemover = void 0;
     }
   };
 }
@@ -10030,7 +10321,10 @@ function createCanvasEngine(opts = {}) {
     }
   }
   const world = createWorld2();
-  const engine = createEngine(world);
+  const engine = createEngine(world, {
+    ...opts.onGuestFault === void 0 ? {} : { onGuestFault: opts.onGuestFault },
+    ...opts.onGuestNotice === void 0 ? {} : { onGuestNotice: opts.onGuestNotice }
+  });
   const sink = createForwardingSink();
   const stack = installInteractionStack(engine, { sink });
   const budgets = {
@@ -10205,7 +10499,9 @@ function createCanvasEngine(opts = {}) {
     // document, so this reads through per publish: an ephemeral behavior
     // installed before anyone joins simply lies dormant until there is a peer
     // for it to be.
-    presence: () => presence
+    presence: () => presence,
+    ...opts.onBehaviorFault === void 0 ? {} : { onFault: opts.onBehaviorFault },
+    ...opts.onBehaviorLog === void 0 ? {} : { onLog: opts.onBehaviorLog }
   });
   for (const b of opts.behaviors ?? []) behaviors2.register(b);
   const widgetQuery = () => {
@@ -10437,7 +10733,7 @@ import {
   Local as Local3
 } from "@vibecook/strata-ecs";
 import { DurableUndoStatus } from "@vibecook/strata-ecs/durable";
-var CORE_VERSION = "0.6.0";
+var CORE_VERSION = "0.7.0";
 
 export {
   defineSchemaOnce,
@@ -10579,6 +10875,7 @@ export {
   BEHAVIOR_PHASES,
   BEHAVIOR_DEFAULT_PHASE,
   behaviors,
+  describeBehavior,
   defineBehavior,
   isDurableEligible,
   compileBehavior,
@@ -10721,4 +11018,4 @@ export {
   Local3 as Local,
   DurableUndoStatus
 };
-//# sourceMappingURL=chunk-JLXETATP.js.map
+//# sourceMappingURL=chunk-LATXYFMO.js.map