@storylet-studio/runtime 0.3.0 → 0.4.1

package/dist/index.d.cts

@@ -24,6 +24,16 @@ interface EngineOptions {
      * once, each engine saves its own envelope (design/flows.md).
      */
     world?: ScopeResolver;
+    /**
+     * Diagnostics hook (opt-in, dev tooling only): fired when `openFlow` REPLACES
+     * a flow that still had cards dealt, with the flow id and how many. The
+     * behaviour is unchanged - replacing is deliberate and the same in Patter -
+     * this only makes it observable, because the case it catches is a host
+     * calling `openFlow` straight after `loadGame` to "re-take" its handle and
+     * silently discarding the hand the save just restored (`getFlow` is the
+     * call). Zero cost when unset; leave it unset in shipped games.
+     */
+    onReplacedFlow?: (id: string, dealt: number) => void;
 }
 interface OpenFlowOptions {
     /** Seed for this flow's PRNG (defaults to the engine's `seed`). */
@@ -224,6 +234,9 @@ interface Internals {
     shared: Partition;
     /** @world: the host's resolver, or the self-backed bag's. */
     worldResolver: ScopeResolver;
+    /** @world names declared `writable: false`: the story's promise, kept at
+     *  runtime as the compiler keeps it at publish (Reboot.md 10). */
+    worldReadOnly: Set<string>;
     /** `turn` is the box clock the event happened on, where the caller knows it
      *  - the same stamp the flow's own log carries. Unity and Unreal passed it
      *  from the start; JS and Godot dropped it, so their examiners printed "[-]"
@@ -235,6 +248,7 @@ interface Internals {
 declare class Engine {
     private readonly internals;
     private readonly seed;
+    private readonly onReplacedFlow;
     private readonly flowsById;
     private readonly engineTraceHandlers;
     /** The host's @world binding, if the engine was built with one: it

package/dist/index.d.ts

@@ -24,6 +24,16 @@ interface EngineOptions {
      * once, each engine saves its own envelope (design/flows.md).
      */
     world?: ScopeResolver;
+    /**
+     * Diagnostics hook (opt-in, dev tooling only): fired when `openFlow` REPLACES
+     * a flow that still had cards dealt, with the flow id and how many. The
+     * behaviour is unchanged - replacing is deliberate and the same in Patter -
+     * this only makes it observable, because the case it catches is a host
+     * calling `openFlow` straight after `loadGame` to "re-take" its handle and
+     * silently discarding the hand the save just restored (`getFlow` is the
+     * call). Zero cost when unset; leave it unset in shipped games.
+     */
+    onReplacedFlow?: (id: string, dealt: number) => void;
 }
 interface OpenFlowOptions {
     /** Seed for this flow's PRNG (defaults to the engine's `seed`). */
@@ -224,6 +234,9 @@ interface Internals {
     shared: Partition;
     /** @world: the host's resolver, or the self-backed bag's. */
     worldResolver: ScopeResolver;
+    /** @world names declared `writable: false`: the story's promise, kept at
+     *  runtime as the compiler keeps it at publish (Reboot.md 10). */
+    worldReadOnly: Set<string>;
     /** `turn` is the box clock the event happened on, where the caller knows it
      *  - the same stamp the flow's own log carries. Unity and Unreal passed it
      *  from the start; JS and Godot dropped it, so their examiners printed "[-]"
@@ -235,6 +248,7 @@ interface Internals {
 declare class Engine {
     private readonly internals;
     private readonly seed;
+    private readonly onReplacedFlow;
     private readonly flowsById;
     private readonly engineTraceHandlers;
     /** The host's @world binding, if the engine was built with one: it

package/dist/index.js

@@ -603,6 +603,7 @@ var loadPartition = (p, values) => {
 var Engine = class {
   internals;
   seed;
+  onReplacedFlow;
   flowsById = /* @__PURE__ */ new Map();
   engineTraceHandlers = /* @__PURE__ */ new Set();
   /** The host's @world binding, if the engine was built with one: it
@@ -611,6 +612,7 @@ var Engine = class {
   hostWorld;
   constructor(bundle, opts = {}) {
     this.seed = opts.seed ?? 0;
+    this.onReplacedFlow = opts.onReplacedFlow;
     if (opts.world !== void 0) this.hostWorld = opts.world;
     const internals = {
       bundle,
@@ -631,6 +633,7 @@ var Engine = class {
       flowDecls: { story: [], box: /* @__PURE__ */ new Map(), deck: /* @__PURE__ */ new Map(), hand: /* @__PURE__ */ new Map(), value: /* @__PURE__ */ new Map() },
       shared: void 0,
       worldResolver: void 0,
+      worldReadOnly: /* @__PURE__ */ new Set(),
       emitEngine: (flow, event, turn) => {
         if (this.internals.logCap !== void 0) {
           this.engineLog.push({ ...event, flow, seq: this.engineSeq++, ...turn !== void 0 ? { turn } : {} });
@@ -688,6 +691,7 @@ var Engine = class {
   initShared(hostWorld) {
     const internals = this.internals;
     internals.shared = buildPartition(internals, sharedHalf);
+    internals.worldReadOnly = new Set(internals.bundle.world.properties.filter((d) => d.writable === false).map((d) => d.name));
     if (hostWorld !== void 0) {
       internals.worldResolver = hostWorld;
     } else {
@@ -731,7 +735,12 @@ var Engine = class {
    *  state; shared state is untouched. There is no default flow: "main" is
    *  a caller convention, not an engine rule. */
   openFlow(id, opts = {}) {
-    this.flowsById.get(id)?.markClosed();
+    const existing = this.flowsById.get(id);
+    if (existing) {
+      const dealt = existing.heldCardIds().length;
+      if (dealt > 0) this.onReplacedFlow?.(id, dealt);
+      existing.markClosed();
+    }
     const flow = new Flow(this, this.internals, id, opts.seed ?? this.seed);
     this.flowsById.set(id, flow);
     return flow;
@@ -1697,6 +1706,7 @@ var Flow = class {
       case "world": {
         const resolver = this.internals.worldResolver;
         if (!resolver.set) throw new Error(`@world.${name} cannot be written: the host bound @world read-only`);
+        if (this.internals.worldReadOnly.has(name)) throw new Error(`'@world.${name}' is read-only (writable: false)`);
         const prev = resolver.get(name);
         resolver.set(name, value);
         return { path: `world.${name}`, ...prev !== void 0 ? { prev } : {} };