@storylet-studio/play-helpers 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -210,18 +210,17 @@ type LiveBundleResult =
     error: string;
 };
 /**
- * Apply a bundle the editor pushed over the Live Link: `new Engine(parsed,
- * opts)` then `loadGame(engine.saveGame())`, returning the new engine. Never
- * throws; a failure (unparseable JSON, a bundle the runtime rejects, a
- * different project) comes back as `{ ok: false, error }` and the old engine
- * is untouched.
+ * Apply a bundle the editor pushed over the Live Link through the engine's own
+ * `hotSwap`, returning the replacement. Never throws; a failure (unparseable
+ * JSON, a bundle the runtime rejects, a different project) comes back as
+ * `{ ok: false, error }` and the old engine is left as it was.
  *
- * `opts` are the options the old engine was created with. An engine does
- * not expose its seed, and it does not matter here: the save envelope carries
- * each flow's PRNG state, so `loadGame` resumes the draw sequences exactly
- * where they were and `seed` only shapes fresh flows. `log` does matter (the
- * retained log is per flow), and so does `world` (the host's binding does not
- * ride the envelope), so pass them if you had them.
+ * Works whether the engine made its own registry or was given the game's: on
+ * the game's registry the old engine hands its keys to the replacement, which a
+ * plain save and load into a second engine cannot do (the two would clash).
+ *
+ * The engine remembers the options it was built with (seed, log, world,
+ * registry), so `opts` is only for overriding one of them for the replacement.
  */
 declare function applyLiveBundle(engine: Engine, bundleJson: string, opts?: EngineOptions): LiveBundleResult;
 

package/dist/index.d.ts

@@ -210,18 +210,17 @@ type LiveBundleResult =
     error: string;
 };
 /**
- * Apply a bundle the editor pushed over the Live Link: `new Engine(parsed,
- * opts)` then `loadGame(engine.saveGame())`, returning the new engine. Never
- * throws; a failure (unparseable JSON, a bundle the runtime rejects, a
- * different project) comes back as `{ ok: false, error }` and the old engine
- * is untouched.
+ * Apply a bundle the editor pushed over the Live Link through the engine's own
+ * `hotSwap`, returning the replacement. Never throws; a failure (unparseable
+ * JSON, a bundle the runtime rejects, a different project) comes back as
+ * `{ ok: false, error }` and the old engine is left as it was.
  *
- * `opts` are the options the old engine was created with. An engine does
- * not expose its seed, and it does not matter here: the save envelope carries
- * each flow's PRNG state, so `loadGame` resumes the draw sequences exactly
- * where they were and `seed` only shapes fresh flows. `log` does matter (the
- * retained log is per flow), and so does `world` (the host's binding does not
- * ride the envelope), so pass them if you had them.
+ * Works whether the engine made its own registry or was given the game's: on
+ * the game's registry the old engine hands its keys to the replacement, which a
+ * plain save and load into a second engine cannot do (the two would clash).
+ *
+ * The engine remembers the options it was built with (seed, log, world,
+ * registry), so `opts` is only for overriding one of them for the replacement.
  */
 declare function applyLiveBundle(engine: Engine, bundleJson: string, opts?: EngineOptions): LiveBundleResult;
 

package/dist/index.js

@@ -93,6 +93,13 @@ var PropertyBag = class _PropertyBag {
   get(name) {
     return this.values[this.norm(name)];
   }
+  /** A name as this bag keys it: its normalisation policy applied. The registry
+   *  uses it to key quality ladders and the validation schema the bag's own way,
+   *  so a case-significant (identity) bag is not quietly folded to lower case
+   *  one layer up. */
+  normalise(name) {
+    return this.norm(name);
+  }
   /** Write a property. Engine writes (the default) notify subscribers;
    *  pass `silent: true` for a host write, which reaches only the audit
    *  hook. Throws on a read-only property unless the caller says it is the
@@ -234,7 +241,8 @@ function createStateLogger2(engine, flow, opts = {}) {
 }
 
 // ../model/src/index.ts
-var SAVE_SCHEMA = "storylets/save@1";
+var SAVE_SCHEMA = "storylets/save@2";
+var SAVE_SCHEMA_V1 = "storylets/save@1";
 var SAVEFILE_SCHEMA = "storylets/savefile@1";
 
 // src/save.ts
@@ -249,7 +257,7 @@ function saveState(engine, world) {
   };
 }
 function loadState(engine, file) {
-  if (!file || typeof file !== "object" || file.schema !== SAVEFILE_SCHEMA || file.engine?.schema !== SAVE_SCHEMA) {
+  if (!file || typeof file !== "object" || file.schema !== SAVEFILE_SCHEMA || file.engine?.schema !== SAVE_SCHEMA && file.engine?.schema !== SAVE_SCHEMA_V1) {
     throw new Error(`not a storylets save (expected schema "${SAVEFILE_SCHEMA}")`);
   }
   engine.loadGame(file.engine);
@@ -333,8 +341,9 @@ function formatLogBody(e, flow) {
     }
     case "evict":
       return `${stamp}evict ${e.card} from ${e.hand} (${e.reason})`;
+    // A card played with none ("") has no outcome to name.
     case "play":
-      return `${stamp}play ${e.card} -> ${e.outcome}`;
+      return `${stamp}play ${e.card}${e.outcome === "" ? "" : ` -> ${e.outcome}`}`;
     case "write":
       return `${stamp}write ${e.path}: ${showVal(e.prev)} -> ${showVal(e.value)}`;
     case "turns":
@@ -944,7 +953,7 @@ function createLiveLink(opts) {
 }
 
 // src/refresh.ts
-import { Engine } from "@storylet-studio/runtime";
+import "@storylet-studio/runtime";
 function applyLiveBundle(engine, bundleJson, opts = {}) {
   let bundle;
   try {
@@ -953,8 +962,7 @@ function applyLiveBundle(engine, bundleJson, opts = {}) {
     return { ok: false, error: "pushed bundle is not valid JSON" };
   }
   try {
-    const next = new Engine(bundle, opts);
-    next.loadGame(engine.saveGame());
+    const { engine: next } = engine.hotSwap(bundle, opts);
     return { ok: true, engine: next, bundle };
   } catch (e) {
     return { ok: false, error: e instanceof Error ? e.message : String(e) };