@patterkit/runtime 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [614eaa8]
+  - @patterkit/model@0.3.0
+  - @patterkit/dialect@0.1.5
+
 ## 0.2.1
 
 ### Patch Changes
@@ -20,6 +28,7 @@ version number always means the same runtime behaviour. This package is versione
 ## [0.4.0] - 2026-07-30
 
 ### Added
+
 - **State logger** (parity: previously JS-only). Watches the mutable runtime state - `@patter`
   globals, per-scene `@scene` props, and visit counts (shared + per-flow) - and reports what changed
   between captures, plus a per-step trace including `gameData`. Built on the engine's save-game, so
@@ -27,18 +36,21 @@ version number always means the same runtime behaviour. This package is versione
   every runtime.
 
 ### Fixed
+
 - The download now includes the **MIT `LICENSE` file**; previously the zip shipped with no licence
   text at all.
 
 ## [0.3.1] - 2026-07-22
 
 ### Changed
+
 - Version bump only, to keep the four Patterplay runtimes in lockstep. This release fixes
   Unreal-only build issues (see the Unreal changelog and #25); the JavaScript runtime is unchanged.
 
 ## [0.3.0] - 2026-07-21
 
 ### Added
+
 - **Host navigation.** `flow.goto(scene, block?)` sends a running flow to a Game ID address, behaving
   exactly like an authored `go` jump: the target scene's `onEntry` runs, arriving counts as a visit, and
   the callstack is replaced (pending call-returns discarded). Being a host action it lands immediately -
@@ -54,6 +66,7 @@ version number always means the same runtime behaviour. This package is versione
   (they were JS-only).
 
 ### Changed
+
 - Dropping a flow now FINISHES it. `closeFlow`, `engine.reset()` and re-opening a name all leave the old
   `Flow` inert (`advance()` reports the end, `goto()` refuses), so a stale reference a game still holds
   can no longer keep running scene entry effects and moving shared state. Re-opening a name still
@@ -62,6 +75,7 @@ version number always means the same runtime behaviour. This package is versione
 ## [0.2.2] - 2026-07-13
 
 ### Changed
+
 - Internal: the Best match (`specificity`) selection metric now uses the shared
   `@wildwinter/expr-specificity` package instead of a per-engine inline copy. Behaviour is
   unchanged and conformance-verified across all four engines.

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   Engine: () => Engine,
   Flow: () => Flow,
   buildTagIndex: () => buildTagIndex,
+  describeBundle: () => describeBundle,
   effectiveGameData: () => effectiveGameData,
   gameDataFields: () => gameDataFields,
   gameDataValue: () => gameDataValue
@@ -1411,12 +1412,13 @@ function hostScopeDefault(decl) {
   }
 }
 function selfBackedResolver(decls) {
+  const key = (name) => name.toLowerCase();
   const bag = /* @__PURE__ */ new Map();
-  for (const d of decls) bag.set(d.name, hostScopeDefault(d));
+  for (const d of decls) bag.set(key(d.name), hostScopeDefault(d));
   return {
-    get: (name) => bag.get(name),
+    get: (name) => bag.get(key(name)),
     set: (name, value) => {
-      bag.set(name, value);
+      bag.set(key(name), value);
     }
   };
 }
@@ -1442,6 +1444,109 @@ function truthy(v) {
   return v.length > 0;
 }
 
+// src/describe.ts
+var import_model2 = require("@patterkit/model");
+var isShared = (d, scopeDefault) => d.shared ?? scopeDefault;
+function summariseProperty(d, scopeDefault) {
+  return {
+    name: d.name,
+    type: d.type,
+    hasDefault: d.default !== void 0,
+    ...d.default !== void 0 ? { default: d.default } : {},
+    shared: isShared(d, scopeDefault)
+  };
+}
+function summariseField(f) {
+  return {
+    name: f.name,
+    type: f.type,
+    hasDefault: f.default !== void 0,
+    ...f.values ? { values: [...f.values] } : {},
+    ...f.purpose ? { purpose: f.purpose } : {}
+  };
+}
+function countBlock(block, counts) {
+  counts.blocks++;
+  const stack = [...block.children];
+  while (stack.length) {
+    const node = stack.pop();
+    if (node.type === "group") {
+      counts.groups++;
+      if (node.prompt) counts.prompts++;
+      stack.push(...node.children);
+      continue;
+    }
+    counts.snippets++;
+    for (const beat of node.beats ?? []) {
+      counts.beats++;
+      if (beat.kind === "gameEvent") counts.gameEvents++;
+    }
+  }
+}
+function describeBundle(bundle) {
+  const counts = {
+    scenes: 0,
+    blocks: 0,
+    groups: 0,
+    snippets: 0,
+    beats: 0,
+    prompts: 0,
+    gameEvents: 0,
+    cast: bundle.cast?.length ?? 0
+  };
+  const addresses = [];
+  const sceneProps = [];
+  for (const scene of Object.values(bundle.scenes)) {
+    counts.scenes++;
+    const gameId = (0, import_model2.effectiveGameId)(scene);
+    addresses.push({
+      gameId,
+      name: scene.name,
+      blocks: scene.blocks.map((b) => ({ gameId: (0, import_model2.effectiveGameId)(b), name: b.name }))
+    });
+    for (const block of scene.blocks) countBlock(block, counts);
+    if (scene.sceneProps?.length) {
+      sceneProps.push({ gameId, properties: scene.sceneProps.map((d) => summariseProperty(d, false)) });
+    }
+  }
+  const hostScopes = (bundle.scopeRegistry?.scopes ?? []).map((s) => ({
+    token: s.token,
+    writable: s.writable ?? true,
+    opaque: s.declarations === void 0,
+    // A host scope's values live outside the story, so "shared" is not a choice
+    // its declarations make; they are world-wide by nature.
+    properties: (s.declarations ?? []).map((d) => summariseProperty(d, true))
+  }));
+  const gameData = Object.entries(bundle.gameDataFields ?? {}).filter(([, fields]) => (fields?.length ?? 0) > 0).map(([kind, fields]) => ({
+    kind,
+    fields: (fields ?? []).map(summariseField)
+  }));
+  return {
+    identity: {
+      schema: bundle.schema,
+      project: bundle.content.project,
+      ...bundle.content.version !== void 0 ? { version: bundle.content.version } : {},
+      ...bundle.content.hash !== void 0 ? { hash: bundle.content.hash } : {},
+      ...bundle.content.structureHash !== void 0 ? { structureHash: bundle.content.structureHash } : {},
+      voiced: bundle.voiced,
+      defaultLocale: bundle.locales.default,
+      locales: [...bundle.locales.included],
+      // Absent means "embedded": the back-compat default a bundle written before
+      // the field existed relies on.
+      localisation: bundle.localisation?.mode ?? "embedded",
+      sourceDebug: bundle.localisation?.sourceDebug ?? false
+    },
+    addresses,
+    hostScopes,
+    properties: {
+      patter: (bundle.properties ?? []).map((d) => summariseProperty(d, true)),
+      scene: sceneProps
+    },
+    gameData,
+    counts
+  };
+}
+
 // src/gamedata.ts
 function gameDataFields(bundle, kind) {
   return bundle.gameDataFields?.[kind] ?? [];
@@ -1464,6 +1569,7 @@ function effectiveGameData(fields, node) {
   Engine,
   Flow,
   buildTagIndex,
+  describeBundle,
   effectiveGameData,
   gameDataFields,
   gameDataValue