@patterkit/runtime 0.4.5 → 0.5.1

package/dist/index.d.cts

@@ -236,6 +236,8 @@ interface PropertyRow {
     value: ScalarValue | undefined;
     default: ScalarValue;
     values?: string[];
+    /** A quality's ordered stage ladder (lets an inspector offer stages instead of free text). */
+    stages?: string[];
 }
 /** Options for opening a flow. */
 interface OpenFlowOptions {
@@ -439,6 +441,23 @@ declare class Engine {
     tagsForScene(sceneRef: string): string[];
     /** A block's accumulated tags (scene + block), by scene + block ref (id or gameId). Empty when none / unknown. */
     tagsForBlock(sceneRef: string, blockRef: string): string[];
+    /**
+     * Every cast member the PROJECT declares, in authored order - the same list `describeBundle` counts.
+     * A superset of any scene's cast: the validator holds a beat's `character` to a declared member, so
+     * {@link castForScene} and {@link castForBlock} only ever return names that appear here.
+     */
+    getCast(): string[];
+    /**
+     * A scene's cast: the `character` token of every speaker with a line anywhere in it, deduped, in
+     * first-appearance order. Static, like {@link getOutline}: it walks the authored structure, so a
+     * speaker behind a condition, inside any group, or voicing a choice prompt counts - this is who CAN
+     * speak in the scene, not who a given playthrough heard. Empty for an unknown ref, or a scene with no
+     * dialogue. Tokens, not display names: resolve those through the delivered step (`characterName`),
+     * which is what follows `setLocale`.
+     */
+    castForScene(sceneRef: string): string[];
+    /** One block's cast, by scene + block ref (id or gameId). {@link castForScene} scoped to a block. */
+    castForBlock(sceneRef: string, blockRef: string): string[];
     /**
      * The authored structure as a nested tree: scenes -> blocks -> children (groups + snippets, groups
      * preserved) -> a snippet's beats. Static (no flow / play state); per-beat data is read at the source
@@ -516,6 +535,9 @@ declare class Flow {
     private readonly sceneResolver;
     private readonly evalCtx;
     constructor(id: string, host: FlowHost, seed: number);
+    /** The stage ladder of `@scope.name` when it is a declared quality, else undefined. Names compare
+     *  lowercase, as the compiler emits references (the selfBackedResolver lesson). */
+    private stagesFor;
     /** Begin this flow at a scene (and optionally a specific block within it). */
     start(sceneId?: string, blockId?: string): void;
     /**

package/dist/index.d.ts

@@ -236,6 +236,8 @@ interface PropertyRow {
     value: ScalarValue | undefined;
     default: ScalarValue;
     values?: string[];
+    /** A quality's ordered stage ladder (lets an inspector offer stages instead of free text). */
+    stages?: string[];
 }
 /** Options for opening a flow. */
 interface OpenFlowOptions {
@@ -439,6 +441,23 @@ declare class Engine {
     tagsForScene(sceneRef: string): string[];
     /** A block's accumulated tags (scene + block), by scene + block ref (id or gameId). Empty when none / unknown. */
     tagsForBlock(sceneRef: string, blockRef: string): string[];
+    /**
+     * Every cast member the PROJECT declares, in authored order - the same list `describeBundle` counts.
+     * A superset of any scene's cast: the validator holds a beat's `character` to a declared member, so
+     * {@link castForScene} and {@link castForBlock} only ever return names that appear here.
+     */
+    getCast(): string[];
+    /**
+     * A scene's cast: the `character` token of every speaker with a line anywhere in it, deduped, in
+     * first-appearance order. Static, like {@link getOutline}: it walks the authored structure, so a
+     * speaker behind a condition, inside any group, or voicing a choice prompt counts - this is who CAN
+     * speak in the scene, not who a given playthrough heard. Empty for an unknown ref, or a scene with no
+     * dialogue. Tokens, not display names: resolve those through the delivered step (`characterName`),
+     * which is what follows `setLocale`.
+     */
+    castForScene(sceneRef: string): string[];
+    /** One block's cast, by scene + block ref (id or gameId). {@link castForScene} scoped to a block. */
+    castForBlock(sceneRef: string, blockRef: string): string[];
     /**
      * The authored structure as a nested tree: scenes -> blocks -> children (groups + snippets, groups
      * preserved) -> a snippet's beats. Static (no flow / play state); per-beat data is read at the source
@@ -516,6 +535,9 @@ declare class Flow {
     private readonly sceneResolver;
     private readonly evalCtx;
     constructor(id: string, host: FlowHost, seed: number);
+    /** The stage ladder of `@scope.name` when it is a declared quality, else undefined. Names compare
+     *  lowercase, as the compiler emits references (the selfBackedResolver lesson). */
+    private stagesFor;
     /** Begin this flow at a scene (and optionally a specific block within it). */
     start(sceneId?: string, blockId?: string): void;
     /**

package/dist/index.js

@@ -328,6 +328,42 @@ var Engine = class _Engine {
     const id = this.resolveBlockRef(sceneId, blockRef);
     return (id != null ? this.host.tagIndex.get(id) : void 0) ?? [];
   }
+  /**
+   * Every cast member the PROJECT declares, in authored order - the same list `describeBundle` counts.
+   * A superset of any scene's cast: the validator holds a beat's `character` to a declared member, so
+   * {@link castForScene} and {@link castForBlock} only ever return names that appear here.
+   */
+  getCast() {
+    const names = [];
+    for (const c of this.host.bundle.cast ?? []) if (c?.name) names.push(c.name);
+    return names;
+  }
+  /**
+   * A scene's cast: the `character` token of every speaker with a line anywhere in it, deduped, in
+   * first-appearance order. Static, like {@link getOutline}: it walks the authored structure, so a
+   * speaker behind a condition, inside any group, or voicing a choice prompt counts - this is who CAN
+   * speak in the scene, not who a given playthrough heard. Empty for an unknown ref, or a scene with no
+   * dialogue. Tokens, not display names: resolve those through the delivered step (`characterName`),
+   * which is what follows `setLocale`.
+   */
+  castForScene(sceneRef) {
+    const id = this.resolveSceneRef(sceneRef);
+    const scene = id != null ? this.host.bundle.scenes[id] : void 0;
+    if (!scene) return [];
+    const out = /* @__PURE__ */ new Set();
+    for (const block of scene.blocks) collectCast(block.children, out);
+    return [...out];
+  }
+  /** One block's cast, by scene + block ref (id or gameId). {@link castForScene} scoped to a block. */
+  castForBlock(sceneRef, blockRef) {
+    const sceneId = this.resolveSceneRef(sceneRef);
+    const id = this.resolveBlockRef(sceneId, blockRef);
+    const block = id != null ? this.host.blockById.get(id) : void 0;
+    if (!block) return [];
+    const out = /* @__PURE__ */ new Set();
+    collectCast(block.children, out);
+    return [...out];
+  }
   /**
    * The authored structure as a nested tree: scenes -> blocks -> children (groups + snippets, groups
    * preserved) -> a snippet's beats. Static (no flow / play state); per-beat data is read at the source
@@ -457,6 +493,7 @@ var Engine = class _Engine {
       ref: `@${d.name}`,
       type: d.type,
       values: d.values,
+      stages: d.stages,
       value: this.getProperty(`@${d.name}`),
       default: declDefault(d)
     }));
@@ -589,9 +626,28 @@ var Flow = class {
         nextRandom: this.rng,
         visits: (id2) => this.visitCounts.get(id2) ?? 0,
         patterVisits: (id2) => this.host.sharedVisits.get(id2) ?? 0
-      }
+      },
+      // The quality channel (expr 0.4.0): hands the evaluator a property's stage ladder, which is what
+      // makes ordering compare by position and advance() step. Wired by hand because this context takes
+      // only the registry's SCOPES (the patter/scene resolvers here are the flow's own merged views),
+      // and because @scene declarations belong to whichever scene the flow is in RIGHT NOW.
+      qualities: (scope, name) => this.stagesFor(scope, name)
     };
   }
+  /** The stage ladder of `@scope.name` when it is a declared quality, else undefined. Names compare
+   *  lowercase, as the compiler emits references (the selfBackedResolver lesson). */
+  stagesFor(scope, name) {
+    const key = name.toLowerCase();
+    const fromDecls = (decls) => decls?.find((d) => d.name.toLowerCase() === key && d.type === "quality")?.stages;
+    if (scope === "patter") {
+      return fromDecls(this.host.patterSharedDecls) ?? fromDecls(this.host.patterLocalDecls);
+    }
+    if (scope === "scene") {
+      const scene = this.currentSceneId != null ? this.host.bundle.scenes[this.currentSceneId] : void 0;
+      return fromDecls(scene?.sceneProps);
+    }
+    return fromDecls(this.host.bundle.scopeRegistry?.scopes.find((s) => s.token === scope)?.declarations);
+  }
   // -- Host API -------------------------------------------------------------
   /** Begin this flow at a scene (and optionally a specific block within it). */
   start(sceneId, blockId) {
@@ -1321,6 +1377,15 @@ var Flow = class {
     }
   }
 };
+function collectCast(nodes, out) {
+  walkNodes(nodes, (n) => {
+    if (n.type === "group") {
+      if (n.prompt?.kind === "line" && n.prompt.character) out.add(n.prompt.character);
+      return;
+    }
+    for (const beat of n.beats ?? []) if (beat.kind === "line" && beat.character) out.add(beat.character);
+  });
+}
 function serialiseSelectors(map) {
   const out = {};
   for (const [id, st] of map) {
@@ -1344,7 +1409,7 @@ function deserialiseSelectors(rec) {
   return map;
 }
 function toDecl(decl) {
-  return { name: decl.name, type: decl.type, values: decl.values, default: decl.default };
+  return { name: decl.name, type: decl.type, values: decl.values, stages: decl.stages, default: decl.default };
 }
 function declDefault(d) {
   if (d.default !== void 0) return d.default;
@@ -1357,12 +1422,14 @@ function declDefault(d) {
       return [];
     case "enum":
       return d.values?.[0] ?? "";
+    case "quality":
+      return d.stages?.[0] ?? "";
     default:
       return false;
   }
 }
 function toForeignDecl(decl) {
-  return { name: decl.name, type: decl.type, values: decl.values, default: decl.default, writable: decl.writable };
+  return { name: decl.name, type: decl.type, values: decl.values, stages: decl.stages, default: decl.default, writable: decl.writable };
 }
 function hostScopeDefault(decl) {
   if (decl.default !== void 0) return decl.default;
@@ -1377,6 +1444,8 @@ function hostScopeDefault(decl) {
       return [];
     case "enum":
       return decl.values?.[0] ?? "";
+    case "quality":
+      return decl.stages?.[0] ?? "";
   }
 }
 function selfBackedResolver(decls) {
@@ -1403,6 +1472,8 @@ function sceneDefault(decl) {
       return [];
     case "enum":
       return decl.values?.[0] ?? "";
+    case "quality":
+      return decl.stages?.[0] ?? "";
   }
 }
 function truthy(v) {