@patterkit/runtime 0.4.0 → 0.4.2

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { ScalarValue } from '@wildwinter/expr';
 import { ScopeResolver, ScopeRegistry, ScopeDeclaration } from '@wildwinter/scoperegistry';
-import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, PropertyType, GameDataField, GameDataNodeKind } from '@patterkit/model';
+import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
 export { Bundle } from '@patterkit/model';
 
 type SelectableNode = CompiledGroup | CompiledSnippet;
@@ -705,6 +705,143 @@ declare class Flow {
     private seedScene;
 }
 
+/** Which bundle this is: identity, staleness fingerprints, and how it ships. */
+interface BundleIdentity {
+    /** The bundle schema tag ("patter/bundle@0"). */
+    schema: string;
+    /** The project name. A save must agree with this. */
+    project: string;
+    /** The authored bundle version, if the project stamps one. */
+    version?: string;
+    /** Fingerprint over the WHOLE bundle: what binds saves and gates staleness. */
+    hash?: string;
+    /** The same fingerprint with the string tables left out. Equal structureHash
+     *  plus a different hash means a TEXT-ONLY edit, which is what makes a live
+     *  hot-swap safe. Showing both lets an integrator tell those apart at sight. */
+    structureHash?: string;
+    /** Project-wide VO mode. */
+    voiced: boolean;
+    defaultLocale: string;
+    locales: string[];
+    /** How strings ship: "embedded" (the runtime resolves text) or "ids" (the
+     *  runtime emits beat IDs and the game localises them itself). */
+    localisation: "embedded" | "ids";
+    /** True when the source locale was embedded purely for debug playback. Such a
+     *  build is NOT shippable, which is worth saying loudly in an inspector. */
+    sourceDebug: boolean;
+}
+/** One scene, and the addresses game code may aim at inside it. */
+interface AddressSummary {
+    /** The host-facing scene address: what `runFlow` / `goto` take. Derived from
+     *  the name when the author set no explicit gameId, exactly as the runtime
+     *  resolves it, so this list is the truth rather than an approximation. */
+    gameId: string;
+    /** The authored scene name, for recognising the row. */
+    name: string;
+    /** Block addresses within this scene. A block address is SCENE-SCOPED: the
+     *  pair is the address, which is why these are nested rather than flattened. */
+    blocks: {
+        gameId: string;
+        name: string;
+    }[];
+}
+/** One author-defined gameData field: part of the host-facing data surface. */
+interface GameDataFieldSummary {
+    name: string;
+    type: string;
+    /** Whether the schema carries a fallback. Sparse storage means a node that
+     *  sets nothing reads this, so a field with no default can arrive absent. */
+    hasDefault: boolean;
+    /** Allowed values for an enum field: the set host code switches on. */
+    values?: string[];
+    purpose?: string;
+}
+/** The gameData fields declared for one kind of node. */
+interface GameDataSummary {
+    kind: GameDataNodeKind;
+    fields: GameDataFieldSummary[];
+}
+/** One declared property. `hasDefault` rather than the value itself: an
+ *  inspector wants to know whether the host MUST supply something. */
+interface PropertySummary {
+    name: string;
+    type: PropertyType;
+    hasDefault: boolean;
+    default?: ScalarValue$1;
+    /** Shared across all flows, or kept per-flow. Defaults differ by scope
+     *  (`@patter` shared, `@scene` per-flow), so it is resolved here. */
+    shared: boolean;
+}
+/** A host scope (`@world` and friends): what the GAME must supply.
+ *
+ *  The highest-value section of the whole description. Today an integrator
+ *  discovers a missing world property when a condition silently reads a
+ *  self-backed default and a branch never fires. */
+interface HostScopeSummary {
+    /** The token after `@`, e.g. "world". */
+    token: string;
+    /** Scope-level read/write default for its declarations. */
+    writable: boolean;
+    /** An OPAQUE scope declares no names: any name is accepted, unchecked. The
+     *  host contract is then "anything", which is worth showing as such rather
+     *  than as an empty property list. */
+    opaque: boolean;
+    properties: PropertySummary[];
+}
+/** Story-owned declarations, for orientation rather than for calling. */
+interface OwnedProperties {
+    /** Project-level (`@patter`). */
+    patter: PropertySummary[];
+    /** Per scene (`@scene`), keyed by the scene's host address. */
+    scene: {
+        gameId: string;
+        properties: PropertySummary[];
+    }[];
+}
+/** "Is this the right build?" at a glance. */
+interface BundleCounts {
+    scenes: number;
+    blocks: number;
+    groups: number;
+    snippets: number;
+    /** Snippet beats. This is the SAME population `Engine.getBeatSequence` walks, deliberately, so a
+     *  tool that lists beats and an inspector that counts them never disagree. Choice prompts are not
+     *  in it - see `prompts`. */
+    beats: number;
+    /** Choice-option prompts: beats that live on a group rather than in a snippet.
+     *
+     *  Counted separately rather than folded into `beats` because folding them in would make this
+     *  number disagree with `getBeatSequence`, and leaving them out entirely would understate a
+     *  choice-heavy story - a branching script could report a handful of beats and look like the wrong
+     *  build. Neither silence nor a redefinition; a second row. */
+    prompts: number;
+    /** Beats that fire a game event rather than producing player-facing words. */
+    gameEvents: number;
+    /** Cast members the bundle carries (player-facing only; the compiler strips
+     *  the authoring fields). */
+    cast: number;
+}
+interface BundleDescription {
+    identity: BundleIdentity;
+    /** Everything game code may aim at, in bundle order. */
+    addresses: AddressSummary[];
+    /** What the host must supply. */
+    hostScopes: HostScopeSummary[];
+    /** What the story owns. */
+    properties: OwnedProperties;
+    /** The author-defined data surface, grouped by node kind. */
+    gameData: GameDataSummary[];
+    counts: BundleCounts;
+}
+/**
+ * Describe a compiled bundle: what it is, and what a game may call on it.
+ *
+ * Pure and allocation-light. Safe to call from an editor inspector on every
+ * selection, though a details panel should still build its rows once rather
+ * than per repaint.
+ */
+declare function describeBundle(bundle: Bundle): BundleDescription;
+
 /** The author-defined gameData fields declared for a node TYPE in a bundle (empty when none). */
 declare function gameDataFields(bundle: Bundle, kind: GameDataNodeKind): GameDataField[];
 /** One node's effective value for a field: its sparse OVERRIDE if present, else the field's declared
@@ -722,4 +859,4 @@ declare function effectiveGameData(fields: GameDataField[], node: GameData | und
  */
 declare function buildTagIndex(bundle: Bundle): Map<string, string[]>;
 
-export { type AdvanceToStopResult, type BeatInfo, type ChoiceOption, Engine, type EngineOptions, type EngineSave, type FlatBeat, Flow, type FlowSnapshot, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type PropertyRow, type SaveGame, type SavedChoice, type SelectorSnapshot, type StackFrame, type StepResult, type WorldResolver, buildTagIndex, effectiveGameData, gameDataFields, gameDataValue };
+export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, type ChoiceOption, Engine, type EngineOptions, type EngineSave, type FlatBeat, Flow, type FlowSnapshot, type GameDataFieldSummary, type GameDataSummary, type HostScopeSummary, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PropertyRow, type PropertySummary, type SaveGame, type SavedChoice, type SelectorSnapshot, type StackFrame, type StepResult, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { ScalarValue } from '@wildwinter/expr';
 import { ScopeResolver, ScopeRegistry, ScopeDeclaration } from '@wildwinter/scoperegistry';
-import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, PropertyType, GameDataField, GameDataNodeKind } from '@patterkit/model';
+import { GameData, Bundle, CompiledGroup, CompiledSnippet, CompiledBlock, PropertyType, ScalarValue as ScalarValue$1, GameDataNodeKind, GameDataField } from '@patterkit/model';
 export { Bundle } from '@patterkit/model';
 
 type SelectableNode = CompiledGroup | CompiledSnippet;
@@ -705,6 +705,143 @@ declare class Flow {
     private seedScene;
 }
 
+/** Which bundle this is: identity, staleness fingerprints, and how it ships. */
+interface BundleIdentity {
+    /** The bundle schema tag ("patter/bundle@0"). */
+    schema: string;
+    /** The project name. A save must agree with this. */
+    project: string;
+    /** The authored bundle version, if the project stamps one. */
+    version?: string;
+    /** Fingerprint over the WHOLE bundle: what binds saves and gates staleness. */
+    hash?: string;
+    /** The same fingerprint with the string tables left out. Equal structureHash
+     *  plus a different hash means a TEXT-ONLY edit, which is what makes a live
+     *  hot-swap safe. Showing both lets an integrator tell those apart at sight. */
+    structureHash?: string;
+    /** Project-wide VO mode. */
+    voiced: boolean;
+    defaultLocale: string;
+    locales: string[];
+    /** How strings ship: "embedded" (the runtime resolves text) or "ids" (the
+     *  runtime emits beat IDs and the game localises them itself). */
+    localisation: "embedded" | "ids";
+    /** True when the source locale was embedded purely for debug playback. Such a
+     *  build is NOT shippable, which is worth saying loudly in an inspector. */
+    sourceDebug: boolean;
+}
+/** One scene, and the addresses game code may aim at inside it. */
+interface AddressSummary {
+    /** The host-facing scene address: what `runFlow` / `goto` take. Derived from
+     *  the name when the author set no explicit gameId, exactly as the runtime
+     *  resolves it, so this list is the truth rather than an approximation. */
+    gameId: string;
+    /** The authored scene name, for recognising the row. */
+    name: string;
+    /** Block addresses within this scene. A block address is SCENE-SCOPED: the
+     *  pair is the address, which is why these are nested rather than flattened. */
+    blocks: {
+        gameId: string;
+        name: string;
+    }[];
+}
+/** One author-defined gameData field: part of the host-facing data surface. */
+interface GameDataFieldSummary {
+    name: string;
+    type: string;
+    /** Whether the schema carries a fallback. Sparse storage means a node that
+     *  sets nothing reads this, so a field with no default can arrive absent. */
+    hasDefault: boolean;
+    /** Allowed values for an enum field: the set host code switches on. */
+    values?: string[];
+    purpose?: string;
+}
+/** The gameData fields declared for one kind of node. */
+interface GameDataSummary {
+    kind: GameDataNodeKind;
+    fields: GameDataFieldSummary[];
+}
+/** One declared property. `hasDefault` rather than the value itself: an
+ *  inspector wants to know whether the host MUST supply something. */
+interface PropertySummary {
+    name: string;
+    type: PropertyType;
+    hasDefault: boolean;
+    default?: ScalarValue$1;
+    /** Shared across all flows, or kept per-flow. Defaults differ by scope
+     *  (`@patter` shared, `@scene` per-flow), so it is resolved here. */
+    shared: boolean;
+}
+/** A host scope (`@world` and friends): what the GAME must supply.
+ *
+ *  The highest-value section of the whole description. Today an integrator
+ *  discovers a missing world property when a condition silently reads a
+ *  self-backed default and a branch never fires. */
+interface HostScopeSummary {
+    /** The token after `@`, e.g. "world". */
+    token: string;
+    /** Scope-level read/write default for its declarations. */
+    writable: boolean;
+    /** An OPAQUE scope declares no names: any name is accepted, unchecked. The
+     *  host contract is then "anything", which is worth showing as such rather
+     *  than as an empty property list. */
+    opaque: boolean;
+    properties: PropertySummary[];
+}
+/** Story-owned declarations, for orientation rather than for calling. */
+interface OwnedProperties {
+    /** Project-level (`@patter`). */
+    patter: PropertySummary[];
+    /** Per scene (`@scene`), keyed by the scene's host address. */
+    scene: {
+        gameId: string;
+        properties: PropertySummary[];
+    }[];
+}
+/** "Is this the right build?" at a glance. */
+interface BundleCounts {
+    scenes: number;
+    blocks: number;
+    groups: number;
+    snippets: number;
+    /** Snippet beats. This is the SAME population `Engine.getBeatSequence` walks, deliberately, so a
+     *  tool that lists beats and an inspector that counts them never disagree. Choice prompts are not
+     *  in it - see `prompts`. */
+    beats: number;
+    /** Choice-option prompts: beats that live on a group rather than in a snippet.
+     *
+     *  Counted separately rather than folded into `beats` because folding them in would make this
+     *  number disagree with `getBeatSequence`, and leaving them out entirely would understate a
+     *  choice-heavy story - a branching script could report a handful of beats and look like the wrong
+     *  build. Neither silence nor a redefinition; a second row. */
+    prompts: number;
+    /** Beats that fire a game event rather than producing player-facing words. */
+    gameEvents: number;
+    /** Cast members the bundle carries (player-facing only; the compiler strips
+     *  the authoring fields). */
+    cast: number;
+}
+interface BundleDescription {
+    identity: BundleIdentity;
+    /** Everything game code may aim at, in bundle order. */
+    addresses: AddressSummary[];
+    /** What the host must supply. */
+    hostScopes: HostScopeSummary[];
+    /** What the story owns. */
+    properties: OwnedProperties;
+    /** The author-defined data surface, grouped by node kind. */
+    gameData: GameDataSummary[];
+    counts: BundleCounts;
+}
+/**
+ * Describe a compiled bundle: what it is, and what a game may call on it.
+ *
+ * Pure and allocation-light. Safe to call from an editor inspector on every
+ * selection, though a details panel should still build its rows once rather
+ * than per repaint.
+ */
+declare function describeBundle(bundle: Bundle): BundleDescription;
+
 /** The author-defined gameData fields declared for a node TYPE in a bundle (empty when none). */
 declare function gameDataFields(bundle: Bundle, kind: GameDataNodeKind): GameDataField[];
 /** One node's effective value for a field: its sparse OVERRIDE if present, else the field's declared
@@ -722,4 +859,4 @@ declare function effectiveGameData(fields: GameDataField[], node: GameData | und
  */
 declare function buildTagIndex(bundle: Bundle): Map<string, string[]>;
 
-export { type AdvanceToStopResult, type BeatInfo, type ChoiceOption, Engine, type EngineOptions, type EngineSave, type FlatBeat, Flow, type FlowSnapshot, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type PropertyRow, type SaveGame, type SavedChoice, type SelectorSnapshot, type StackFrame, type StepResult, type WorldResolver, buildTagIndex, effectiveGameData, gameDataFields, gameDataValue };
+export { type AddressSummary, type AdvanceToStopResult, type BeatInfo, type BundleCounts, type BundleDescription, type BundleIdentity, type ChoiceOption, Engine, type EngineOptions, type EngineSave, type FlatBeat, Flow, type FlowSnapshot, type GameDataFieldSummary, type GameDataSummary, type HostScopeSummary, type OpenFlowOptions, type OutlineBlock, type OutlineNode, type OutlineScene, type OwnedProperties, type PropertyRow, type PropertySummary, type SaveGame, type SavedChoice, type SelectorSnapshot, type StackFrame, type StepResult, type WorldResolver, buildTagIndex, describeBundle, effectiveGameData, gameDataFields, gameDataValue };

package/dist/index.js

@@ -1380,12 +1380,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);
     }
   };
 }
@@ -1411,6 +1412,109 @@ function truthy(v) {
   return v.length > 0;
 }
 
+// src/describe.ts
+import { effectiveGameId as effectiveGameId2 } from "@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 = effectiveGameId2(scene);
+    addresses.push({
+      gameId,
+      name: scene.name,
+      blocks: scene.blocks.map((b) => ({ gameId: effectiveGameId2(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] ?? [];
@@ -1432,6 +1536,7 @@ export {
   Engine,
   Flow,
   buildTagIndex,
+  describeBundle,
   effectiveGameData,
   gameDataFields,
   gameDataValue