@patterkit/runtime 0.16.0 → 0.17.0

package/dist/index.d.cts

@@ -459,6 +459,10 @@ declare class Engine {
      *
      * Contrast {@link runFlow}, which REUSES a flow of the same name instead of replacing it - that is the
      * call to reach for when you want a speaker's variation state to carry on.
+     *
+     * THROWS on an address that does not resolve (an unknown scene, or a block that is not in the named
+     * scene), before anything changes: nothing is opened, and a flow already open under `id` carries on
+     * exactly as it was.
      */
     openFlow(id: string, opts?: OpenFlowOptions): Flow;
     /**
@@ -490,6 +494,13 @@ declare class Engine {
      *  it opens (or the save as it loads), before anything changes. By then a game has built all of its
      *  engines, whatever order it built them in. The same message on every runtime. */
     private assertExternalScopes;
+    /**
+     * `openFlow`'s address as internal ids, or a throw when it does not resolve. With a scene, the block is
+     * scene-scoped exactly as {@link Flow.goto} resolves it (a gameId address in that scene, or the internal
+     * id of a block in that scene), so a block from another scene does not resolve. With no scene, the block
+     * is an internal id from any scene. Neither: the bundle's first scene. The same rule on every runtime.
+     */
+    private resolveOpenAddress;
     /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
     private resolveSceneRef;
     /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */

package/dist/index.d.ts

@@ -459,6 +459,10 @@ declare class Engine {
      *
      * Contrast {@link runFlow}, which REUSES a flow of the same name instead of replacing it - that is the
      * call to reach for when you want a speaker's variation state to carry on.
+     *
+     * THROWS on an address that does not resolve (an unknown scene, or a block that is not in the named
+     * scene), before anything changes: nothing is opened, and a flow already open under `id` carries on
+     * exactly as it was.
      */
     openFlow(id: string, opts?: OpenFlowOptions): Flow;
     /**
@@ -490,6 +494,13 @@ declare class Engine {
      *  it opens (or the save as it loads), before anything changes. By then a game has built all of its
      *  engines, whatever order it built them in. The same message on every runtime. */
     private assertExternalScopes;
+    /**
+     * `openFlow`'s address as internal ids, or a throw when it does not resolve. With a scene, the block is
+     * scene-scoped exactly as {@link Flow.goto} resolves it (a gameId address in that scene, or the internal
+     * id of a block in that scene), so a block from another scene does not resolve. With no scene, the block
+     * is an internal id from any scene. Neither: the bundle's first scene. The same rule on every runtime.
+     */
+    private resolveOpenAddress;
     /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
     private resolveSceneRef;
     /** Resolve a block reference (a scene-scoped gameId OR an internal id) to its internal id. */

package/dist/index.js

@@ -299,11 +299,14 @@ var Engine = class _Engine {
    *
    * Contrast {@link runFlow}, which REUSES a flow of the same name instead of replacing it - that is the
    * call to reach for when you want a speaker's variation state to carry on.
+   *
+   * THROWS on an address that does not resolve (an unknown scene, or a block that is not in the named
+   * scene), before anything changes: nothing is opened, and a flow already open under `id` carries on
+   * exactly as it was.
    */
   openFlow(id, opts = {}) {
     this.assertExternalScopes();
-    const sceneId = this.resolveSceneRef(opts.scene);
-    const blockId = this.resolveBlockRef(sceneId, opts.block);
+    const { sceneId, blockId } = this.resolveOpenAddress(opts.scene, opts.block);
     const prior = this.flowsById.get(id);
     const journal = this.host.journal;
     if (journal && prior && !prior.isClosed) throw new Error(`openFlow would replace the open flow '${id}', which can't be undone while a checkpoint is open`);
@@ -364,6 +367,28 @@ var Engine = class _Engine {
       }
     }
   }
+  /**
+   * `openFlow`'s address as internal ids, or a throw when it does not resolve. With a scene, the block is
+   * scene-scoped exactly as {@link Flow.goto} resolves it (a gameId address in that scene, or the internal
+   * id of a block in that scene), so a block from another scene does not resolve. With no scene, the block
+   * is an internal id from any scene. Neither: the bundle's first scene. The same rule on every runtime.
+   */
+  resolveOpenAddress(scene, block) {
+    if (scene !== void 0) {
+      const sceneId = this.resolveSceneRef(scene);
+      if (!this.host.bundle.scenes[sceneId]) throw new Error(`unknown scene: ${scene}`);
+      if (block === void 0) return { sceneId };
+      const blockId = this.blockGameIdToId.get(sceneId)?.get(block) ?? (this.host.blockIndex.get(block)?.sceneId === sceneId ? block : void 0);
+      if (blockId === void 0) throw new Error(`unknown block: ${block}`);
+      return { sceneId, blockId };
+    }
+    if (block !== void 0) {
+      if (!this.host.blockIndex.has(block)) throw new Error(`unknown block: ${block}`);
+      return { blockId: block };
+    }
+    if (Object.keys(this.host.bundle.scenes).length === 0) throw new Error("no scenes in bundle");
+    return {};
+  }
   /** Resolve a scene reference (a gameId address OR an internal id) to its internal id. */
   resolveSceneRef(ref) {
     if (ref == null) return void 0;