@patterkit/runtime 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.5.1
+
+### Patch Changes
+
+- Updated dependencies [f97f6eb]
+  - @patterkit/model@0.4.0
+  - @patterkit/dialect@0.1.6
+
 ## 0.4.1
 
 ### Patch Changes
@@ -25,6 +33,16 @@ version number always means the same runtime behaviour. This package is versione
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-08-25
+
+### Added
+
+- **The `quality` property type: a story stage as an ordered ladder of named stages.** The value is a
+  stage name; ordering operators compare by ladder POSITION, `advance(@q)` steps to the next stage
+  saturating at the last, and a save carries the stage by name - so a stage inserted mid-production
+  shifts nothing. Declared with `stages` on the property; seeds at the first stage. Corpus-locked
+  across all four runtimes (gating, stepping, and the insertion story through a live hot swap).
+
 ## [0.5.0] - 2026-08-21
 
 ### Added
@@ -33,7 +51,7 @@ version number always means the same runtime behaviour. This package is versione
   project declares, the speakers of a scene, and the speakers of one block. Scene and block refs take
   an internal id or a gameId address. The result is the character token a line beat carries, deduped
   and ordered by first appearance, and it is derived from the AUTHORED structure, so a speaker behind a
-  condition, inside a group, or voicing a choice prompt is included: it answers who *can* speak, not
+  condition, inside a group, or voicing a choice prompt is included: it answers who _can_ speak, not
   who a given playthrough heard. Held across all four runtimes by the conformance corpus.
   `engine.getCast()`, `engine.castForScene(sceneRef)`, `engine.castForBlock(sceneRef, blockRef)`.
 

package/dist/index.cjs

@@ -525,6 +525,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)
     }));
@@ -657,9 +658,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) {
@@ -1421,7 +1441,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;
@@ -1434,12 +1454,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;
@@ -1454,6 +1476,8 @@ function hostScopeDefault(decl) {
       return [];
     case "enum":
       return decl.values?.[0] ?? "";
+    case "quality":
+      return decl.stages?.[0] ?? "";
   }
 }
 function selfBackedResolver(decls) {
@@ -1480,6 +1504,8 @@ function sceneDefault(decl) {
       return [];
     case "enum":
       return decl.values?.[0] ?? "";
+    case "quality":
+      return decl.stages?.[0] ?? "";
   }
 }
 function truthy(v) {