@patterkit/play-helpers 0.2.1 → 0.3.0

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   SAVE_SCHEMA: () => SAVE_SCHEMA,
   applyLiveBundle: () => applyLiveBundle,
   createAudioResolver: () => createAudioResolver,
+  createBundleInspector: () => createBundleInspector,
   createDebugLink: () => createDebugLink,
   createPropertyInspector: () => createPropertyInspector,
   createStateLogger: () => createStateLogger,
@@ -263,8 +264,8 @@ function sameValue(a, b) {
 function createPropertyInspector(engine, opts = {}) {
   const doc = opts.container?.ownerDocument ?? document;
   injectStyle(doc);
-  const el = doc.createElement("div");
-  el.className = "pp-insp";
+  const el2 = doc.createElement("div");
+  el2.className = "pp-insp";
   const heading = doc.createElement("h4");
   heading.textContent = opts.title ?? "Runtime state";
   const list = doc.createElement("div");
@@ -303,15 +304,15 @@ function createPropertyInspector(engine, opts = {}) {
     input.click();
   });
   io.append(saveBtn, loadBtn);
-  el.append(heading, io, list);
+  el2.append(heading, io, list);
   const rowRefreshers = [];
-  const buildRow = (row) => {
+  const buildRow = (row2) => {
     const r = doc.createElement("div");
     r.className = "pp-insp-row";
     const label = doc.createElement("span");
     label.className = "pp-insp-ref";
-    label.textContent = row.ref;
-    label.title = row.ref;
+    label.textContent = row2.ref;
+    label.title = row2.ref;
     const ctl = doc.createElement("div");
     ctl.className = "pp-insp-ctl";
     const reset = doc.createElement("button");
@@ -323,37 +324,37 @@ function createPropertyInspector(engine, opts = {}) {
     list.appendChild(r);
     let read;
     const commit = (v) => {
-      engine.setProperty(row.ref, v);
+      engine.setProperty(row2.ref, v);
       syncReset();
     };
     const focused = (node) => doc.activeElement === node;
     function syncReset() {
-      reset.disabled = sameValue(engine.getProperty(row.ref), row.default);
+      reset.disabled = sameValue(engine.getProperty(row2.ref), row2.default);
     }
     reset.addEventListener("click", () => {
-      engine.setProperty(row.ref, row.default);
+      engine.setProperty(row2.ref, row2.default);
       read();
       syncReset();
     });
-    if (row.type === "boolean") {
+    if (row2.type === "boolean") {
       const cb = doc.createElement("input");
       cb.type = "checkbox";
       cb.addEventListener("change", () => commit(cb.checked));
       ctl.appendChild(cb);
       read = () => {
-        if (!focused(cb)) cb.checked = engine.getProperty(row.ref) === true;
+        if (!focused(cb)) cb.checked = engine.getProperty(row2.ref) === true;
       };
-    } else if (row.type === "number") {
+    } else if (row2.type === "number") {
       const inp = doc.createElement("input");
       inp.type = "number";
       inp.addEventListener("change", () => commit(Number(inp.value)));
       ctl.appendChild(inp);
       read = () => {
-        if (!focused(inp)) inp.value = String(engine.getProperty(row.ref) ?? "");
+        if (!focused(inp)) inp.value = String(engine.getProperty(row2.ref) ?? "");
       };
-    } else if (row.type === "enum") {
+    } else if (row2.type === "enum") {
       const sel = doc.createElement("select");
-      for (const v of row.values ?? []) {
+      for (const v of row2.values ?? []) {
         const o = doc.createElement("option");
         o.value = v;
         o.textContent = v;
@@ -362,9 +363,9 @@ function createPropertyInspector(engine, opts = {}) {
       sel.addEventListener("change", () => commit(sel.value));
       ctl.appendChild(sel);
       read = () => {
-        if (!focused(sel)) sel.value = String(engine.getProperty(row.ref) ?? "");
+        if (!focused(sel)) sel.value = String(engine.getProperty(row2.ref) ?? "");
       };
-    } else if (row.type === "flags") {
+    } else if (row2.type === "flags") {
       const inp = doc.createElement("input");
       inp.type = "text";
       inp.placeholder = "comma, separated, flags";
@@ -372,7 +373,7 @@ function createPropertyInspector(engine, opts = {}) {
       ctl.appendChild(inp);
       read = () => {
         if (!focused(inp)) {
-          const v = engine.getProperty(row.ref);
+          const v = engine.getProperty(row2.ref);
           inp.value = Array.isArray(v) ? v.join(", ") : "";
         }
       };
@@ -382,7 +383,7 @@ function createPropertyInspector(engine, opts = {}) {
       inp.addEventListener("change", () => commit(inp.value));
       ctl.appendChild(inp);
       read = () => {
-        if (!focused(inp)) inp.value = String(engine.getProperty(row.ref) ?? "");
+        if (!focused(inp)) inp.value = String(engine.getProperty(row2.ref) ?? "");
       };
     }
     read();
@@ -399,21 +400,165 @@ function createPropertyInspector(engine, opts = {}) {
     empty.textContent = "No @patter properties.";
     list.appendChild(empty);
   } else {
-    for (const row of props) buildRow(row);
+    for (const row2 of props) buildRow(row2);
   }
   const refresh = () => {
     for (const fn of rowRefreshers) fn();
   };
-  opts.container?.appendChild(el);
+  opts.container?.appendChild(el2);
   const pollMs = opts.pollMs ?? 250;
   let timer;
   if (pollMs > 0) timer = setInterval(refresh, pollMs);
   return {
-    el,
+    el: el2,
     refresh,
     destroy() {
       if (timer !== void 0) clearInterval(timer);
-      el.remove();
+      el2.remove();
+    }
+  };
+}
+
+// src/bundle-inspector.ts
+var import_runtime2 = require("@patterkit/runtime");
+var STYLE_ID2 = "pp-bundle-style";
+var CSS2 = `
+.pp-bundle{font:13px/1.4 ui-sans-serif,system-ui,sans-serif;color:#15201e;background:#f4efe6;border:1px solid #cfc7b8;border-radius:10px;padding:.6rem .7rem;max-width:26rem;box-shadow:0 6px 20px rgba(21,32,30,.12)}
+.pp-bundle h4{margin:0 0 .4rem;font:600 .72rem/1 ui-sans-serif,system-ui,sans-serif;letter-spacing:.08em;text-transform:uppercase;color:#5c6b62}
+.pp-bundle details{border-top:1px solid #e3dccf;padding:.3rem 0}
+.pp-bundle details:first-of-type{border-top:0}
+.pp-bundle summary{cursor:pointer;font-weight:600;color:#214f4b;list-style:none}
+.pp-bundle summary::-webkit-details-marker{display:none}
+.pp-bundle summary::before{content:"\\25B8";display:inline-block;width:1rem;color:#8a9691}
+.pp-bundle details[open]>summary::before{content:"\\25BE"}
+.pp-bundle-count{color:#8a9691;font-weight:400}
+.pp-bundle-row{display:flex;gap:.4rem;margin:.16rem 0 .16rem 1rem}
+.pp-bundle-key{flex:0 0 8rem;color:#5c6b62}
+.pp-bundle-val,.pp-bundle-addr{font-family:ui-monospace,monospace;font-size:.78rem;color:#214f4b;word-break:break-all}
+.pp-bundle-sub{margin-left:2rem}
+.pp-bundle-empty{color:#8a9691;font-style:italic;margin-left:1rem}
+.pp-bundle-warn{color:#8a3a2f;font-weight:600}
+.pp-bundle-tag{font-size:.7rem;color:#5c6b62;border:1px solid #cfc7b8;border-radius:5px;padding:0 .25rem;margin-left:.3rem}
+`;
+function injectStyle2(doc) {
+  if (doc.getElementById(STYLE_ID2)) return;
+  const s = doc.createElement("style");
+  s.id = STYLE_ID2;
+  s.textContent = CSS2;
+  (doc.head ?? doc.documentElement).appendChild(s);
+}
+var el = (doc, tag, cls, text) => {
+  const e = doc.createElement(tag);
+  if (cls) e.className = cls;
+  if (text !== void 0) e.textContent = text;
+  return e;
+};
+function row(doc, key, value, valueClass = "pp-bundle-val") {
+  const r = el(doc, "div", "pp-bundle-row");
+  r.append(el(doc, "span", "pp-bundle-key", key), el(doc, "span", valueClass, value));
+  return r;
+}
+function propertyRow(doc, p) {
+  const r = el(doc, "div", "pp-bundle-row");
+  r.append(el(doc, "span", "pp-bundle-key pp-bundle-addr", p.name));
+  const meta = el(doc, "span", "pp-bundle-val", p.type);
+  if (!p.hasDefault) meta.append(el(doc, "span", "pp-bundle-tag", "no default"));
+  r.append(meta);
+  return r;
+}
+function section(doc, name, label, count, open) {
+  const d = doc.createElement("details");
+  d.dataset["section"] = name;
+  d.open = open;
+  const s = doc.createElement("summary");
+  s.textContent = label;
+  if (count !== null) s.append(el(doc, "span", "pp-bundle-count", ` ${count}`));
+  d.append(s);
+  return d;
+}
+function createBundleInspector(bundle, opts = {}) {
+  const doc = opts.container?.ownerDocument ?? document;
+  injectStyle2(doc);
+  const d = (0, import_runtime2.describeBundle)(bundle);
+  const open = new Set(opts.open ?? ["identity", "addresses"]);
+  const root = el(doc, "div", "pp-bundle");
+  root.append(el(doc, "h4", void 0, opts.title ?? "Bundle"));
+  const id = section(doc, "identity", d.identity.project || "(unnamed project)", null, open.has("identity"));
+  if (d.identity.version) id.append(row(doc, "version", d.identity.version));
+  id.append(row(doc, "schema", d.identity.schema));
+  id.append(row(doc, "locales", `${d.identity.defaultLocale}${d.identity.locales.length > 1 ? ` (+${d.identity.locales.length - 1})` : ""}`));
+  id.append(row(doc, "strings", d.identity.localisation));
+  if (d.identity.voiced) id.append(row(doc, "voiced", "yes"));
+  if (d.identity.hash) id.append(row(doc, "hash", d.identity.hash));
+  if (d.identity.structureHash) id.append(row(doc, "structure", d.identity.structureHash));
+  if (d.identity.sourceDebug) {
+    id.append(row(doc, "build", "SOURCE DEBUG - not shippable", "pp-bundle-val pp-bundle-warn"));
+  }
+  root.append(id);
+  const addr = section(doc, "addresses", "Addresses", d.addresses.length, open.has("addresses"));
+  if (!d.addresses.length) addr.append(el(doc, "div", "pp-bundle-empty", "no scenes"));
+  for (const a of d.addresses) {
+    const r = el(doc, "div", "pp-bundle-row");
+    r.append(el(doc, "span", "pp-bundle-key pp-bundle-addr", a.gameId), el(doc, "span", "pp-bundle-val", a.name));
+    addr.append(r);
+    for (const b of a.blocks) {
+      const br = el(doc, "div", "pp-bundle-row pp-bundle-sub");
+      br.append(el(doc, "span", "pp-bundle-key pp-bundle-addr", b.gameId), el(doc, "span", "pp-bundle-val", b.name));
+      addr.append(br);
+    }
+  }
+  root.append(addr);
+  const hostCount = d.hostScopes.reduce((n, s) => n + s.properties.length, 0);
+  const host = section(doc, "hostScopes", "Host properties", hostCount, open.has("hostScopes"));
+  if (!d.hostScopes.length) host.append(el(doc, "div", "pp-bundle-empty", "the game supplies nothing"));
+  for (const s of d.hostScopes) {
+    const head = el(doc, "div", "pp-bundle-row");
+    head.append(el(doc, "span", "pp-bundle-key pp-bundle-addr", `@${s.token}`));
+    const meta = el(doc, "span", "pp-bundle-val", s.opaque ? "any name, unchecked" : `${s.properties.length} declared`);
+    if (!s.writable) meta.append(el(doc, "span", "pp-bundle-tag", "read-only"));
+    head.append(meta);
+    host.append(head);
+    for (const p of s.properties) {
+      const pr = propertyRow(doc, p);
+      pr.classList.add("pp-bundle-sub");
+      host.append(pr);
+    }
+  }
+  root.append(host);
+  const ownedCount = d.properties.patter.length + d.properties.scene.reduce((n, s) => n + s.properties.length, 0);
+  const owned = section(doc, "properties", "Story properties", ownedCount, open.has("properties"));
+  if (!ownedCount) owned.append(el(doc, "div", "pp-bundle-empty", "none declared"));
+  for (const p of d.properties.patter) owned.append(propertyRow(doc, p));
+  for (const s of d.properties.scene) {
+    owned.append(row(doc, `@scene`, s.gameId, "pp-bundle-val pp-bundle-addr"));
+    for (const p of s.properties) {
+      const pr = propertyRow(doc, p);
+      pr.classList.add("pp-bundle-sub");
+      owned.append(pr);
+    }
+  }
+  root.append(owned);
+  if (d.gameData.length) {
+    const gd2 = section(doc, "gameData", "Game data", d.gameData.reduce((n, g) => n + g.fields.length, 0), open.has("gameData"));
+    for (const g of d.gameData) {
+      gd2.append(row(doc, "on", g.kind));
+      for (const f of g.fields) {
+        const fr = el(doc, "div", "pp-bundle-row pp-bundle-sub");
+        fr.append(el(doc, "span", "pp-bundle-key pp-bundle-addr", f.name), el(doc, "span", "pp-bundle-val", f.type));
+        gd2.append(fr);
+      }
+    }
+    root.append(gd2);
+  }
+  const counts = section(doc, "counts", "Counts", null, open.has("counts"));
+  for (const [key, value] of Object.entries(d.counts)) counts.append(row(doc, key, String(value)));
+  root.append(counts);
+  opts.container?.append(root);
+  return {
+    el: root,
+    description: d,
+    destroy() {
+      root.remove();
     }
   };
 }
@@ -436,6 +581,7 @@ function createAudioResolver(manifestJson, basePath) {
   SAVE_SCHEMA,
   applyLiveBundle,
   createAudioResolver,
+  createBundleInspector,
   createDebugLink,
   createPropertyInspector,
   createStateLogger,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { SaveGame, Engine, StepResult, Bundle } from '@patterkit/runtime';
+import { SaveGame, Engine, StepResult, Bundle as Bundle$1, BundleDescription } from '@patterkit/runtime';
 
 declare const SAVE_SCHEMA = "patter/save@0";
 interface SaveEnvelope {
@@ -107,7 +107,7 @@ interface LiveBundleResult {
     /** The engine to keep using: the same instance for a "text" swap, a replacement for "structure". */
     engine: Engine;
     /** The parsed pushed bundle - hold on to it for the next apply's comparison. */
-    bundle: Bundle;
+    bundle: Bundle$1;
     /** Which tier applied: "text" (strings-only, nothing restarted) or "structure" (full hot swap). */
     kind: "text" | "structure";
 }
@@ -117,7 +117,7 @@ interface LiveBundleResult {
  * unparseable JSON - a structural swap's edge cases are absorbed by the §9.8 drift policy inside
  * `hotSwap`, which never throws for ordinary edits.
  */
-declare function applyLiveBundle(engine: Engine, current: Bundle, data: string): LiveBundleResult;
+declare function applyLiveBundle(engine: Engine, current: Bundle$1, data: string): LiveBundleResult;
 
 interface PropertyInspectorOptions {
     /** Where to mount the panel. If omitted, append the returned `el` yourself. */
@@ -137,6 +137,341 @@ interface PropertyInspector {
 }
 declare function createPropertyInspector(engine: Engine, opts?: PropertyInspectorOptions): PropertyInspector;
 
+type BinaryOp = "==" | "!=" | ">" | ">=" | "<" | "<=" | "+" | "-" | "*" | "/" | "and" | "or";
+type UnaryOp = "not" | "neg";
+type AstNode = ["b", boolean] | ["n", number] | ["s", string] | ["sv", string, string] | ["u", UnaryOp, AstNode] | ["bin", BinaryOp, AstNode, AstNode] | ["call", string, ...AstNode[]] | ["fd", "+" | "-", string];
+
+type ScalarValue = boolean | number | string | string[];
+/** Developer-defined host metadata (spec §17). Opaque to Patter. */
+type GameData = Record<string, unknown>;
+/** A scene/block id, or the reserved "END". */
+type JumpTarget = string;
+interface Jump {
+    to: JumpTarget;
+    /** "jump" (one-way, default) or "call" (jump-and-return via the flow callstack). */
+    mode?: "jump" | "call";
+}
+interface LineBeat {
+    id: string;
+    kind: "line";
+    /** Speaker; must be a member of the project cast (validated). */
+    character?: string;
+    /** Performance direction, language-neutral (never localised). */
+    direction?: string;
+    gameData?: GameData;
+    /** Author-defined freeform tags (#215): a cross-cutting label layer that travels to the runtime.
+     *  At runtime a beat's tags are the UNION of its own and every ancestor's (scene → block → group(s) →
+     *  snippet → beat). Each tag is letters/digits/symbols with NO comma and NO whitespace; deduped. */
+    tags?: string[];
+}
+/**
+ * Authorial voice / narration - speaker-less prose (spec §2). Never voiced; its
+ * localised text always permits inline `{@name}` interpolation (spec §16). This
+ * is the on-screen-text role (e.g. "A door slams!") - distinct from a game-event
+ * beat, which is a pure engine instruction with no localised content.
+ */
+interface TextBeat {
+    id: string;
+    kind: "text";
+    gameData?: GameData;
+    /** Author tags (#215). See LineBeat.tags. */
+    tags?: string[];
+}
+/**
+ * A GAME EVENT (spec §2): a pure engine instruction with no player-facing text - just `gameData` the host
+ * reads when the beat plays (comments / docs attach via the authoring file by id). Named "game event"
+ * rather than "action" because a screenplay's "action" is prose, which is our text beat. Player-facing
+ * words are a line or text beat instead.
+ */
+interface GameEventBeat {
+    id: string;
+    kind: "gameEvent";
+    gameData?: GameData;
+    /** Author tags (#215). See LineBeat.tags. */
+    tags?: string[];
+}
+type Beat = LineBeat | TextBeat | GameEventBeat;
+type Selector = "run" | "branch" | "sequence" | "choice";
+/** How a `sequence` walks its children. `specificity` = **Best match**: pick the eligible
+ *  child whose condition most specifically fits the current state (the most atomic constraints
+ *  actively holding it true); equally-specific ties break by the seeded shuffle. A child with no
+ *  condition scores zero, so it acts as the filler that wins only when nothing more specific is
+ *  eligible. Composes with `exhaust`: `repeat` re-scores every visit (re-pickable, the Best-match
+ *  default), `once` uses each pick up so the group slides down to the filler (graceful degradation). */
+type SelectorOrder = "sequential" | "shuffle" | "specificity";
+/** What a `sequence` does after one full pass through its children. */
+type SelectorExhaust = "once" | "repeat" | "stick";
+/**
+ * `sequence` selector config (spec §4). One stateful picker with two orthogonal
+ * axes subsumes Ink's stopping / cycle / once / shuffle and their combinations.
+ * Defaults: `order: "sequential"`, `exhaust: "once"`. `shuffle` draws without
+ * replacement and never repeats a line back-to-back (built in).
+ */
+interface SequenceOptions {
+    order?: SelectorOrder;
+    exhaust?: SelectorExhaust;
+}
+/** An option's prompt beat (spec §5): a single line | text beat - the choice text. */
+type PromptBeat = LineBeat | TextBeat;
+type PropertyType = "boolean" | "number" | "string" | "flags" | "enum";
+interface PropertyDecl {
+    name: string;
+    type: PropertyType;
+    default?: ScalarValue;
+    /**
+     * The orthogonal *sharing* axis (spec §7): is this property's value shared across
+     * all flows (one world value) or kept per-flow? It does NOT change the reference
+     * syntax - sharing is set here, on the declaration, not by a different scope token.
+     * The default depends on the scope it is declared in: a **global** property
+     * (project `properties` -> `@patter`) defaults to **shared**; a **scene-local**
+     * property (scene `sceneProps` -> `@scene`) defaults to **not shared** (per-flow).
+     */
+    shared?: boolean;
+    /**
+     * Persistence axis, for **scene-local (`@scene`) properties** (spec §7). Default
+     * `false`: the value PERSISTS across scene re-entries (like every other property).
+     * `true`: the value is **reseeded to its default on every scene entry** - "fresh
+     * each playthrough" (Ink's `temp`). Orthogonal to `shared`. Ignored on global
+     * (`@patter`) properties, which always persist for the life of the piece.
+     */
+    temporary?: boolean;
+    /** For enum / flags. */
+    values?: string[];
+    /** Free-text author note documenting what this property is for (authoring only; shown as a hint). */
+    purpose?: string;
+}
+/**
+ * A property of a host / world scope (`@world`, `@game`, ...). The same shape the
+ * `@wildwinter/scoperegistry` `scopeRegistrySpec` uses, declared structurally here
+ * so the model stays free of a runtime dependency. `default` seeds the standalone
+ * runtime's self-backed bag (see `HostScopeSpec`); `writable: false` makes the
+ * property read-only to the story (validated at compile time).
+ */
+interface HostScopeDecl {
+    name: string;
+    type: PropertyType;
+    values?: string[];
+    default?: ScalarValue;
+    writable?: boolean;
+    /** Free-text author note documenting the property (authoring only; shown as a hint). */
+    purpose?: string;
+}
+/** One scope (`token`) in a project's host-scope registry. */
+interface HostScopeSpec {
+    /** The scope token after `@` (e.g. `"world"`). Must not collide with Patter's own
+     *  `patter` / `scene` / `flow`. */
+    token: string;
+    /** Scope-level read/write default for its declarations (default true). */
+    writable?: boolean;
+    /** Property declarations; omit for an opaque scope (any name, unchecked). */
+    declarations?: HostScopeDecl[];
+}
+/**
+ * A project's host-scope registry: the `scopeRegistrySpec` it OWNS (spec
+ * design/scope-registry.md §6). Makes `@world` (and any host scope) first-class
+ * in a standalone project: the compiler validates references into it, the runtime
+ * self-backs it from declaration defaults when no host resolver claims the token,
+ * and coverage drives its values. Structurally identical to scoperegistry's
+ * `ScopeRegistrySpec` so it threads straight through the compiler.
+ */
+interface HostScopeRegistry {
+    version: number;
+    scopes: HostScopeSpec[];
+}
+/** A character's grammatical gender, for localisation. Translators need it to inflect the speaker's own
+ *  lines in gendered languages (adjectives, participles, pronouns), which the source text alone often
+ *  cannot tell them. Absent means "not specified". Authoring-only: it never reaches the runtime bundle,
+ *  but it IS carried into the localisation handoff formats as translator context (spec §14).
+ *
+ *  Free text, not a closed set: real languages need more than three genders (common/utrum, animate/
+ *  inanimate, and so on) and translators name them differently. `COMMON_GENDERS` seeds the editor's
+ *  auto-suggest so the everyday values stay spelled consistently; anything else is still valid. */
+type GrammaticalGender = string;
+interface CastMember {
+    /** Canonical speaker name (matched by a beat's `character`); language-neutral key. */
+    name: string;
+    /** Localised player-facing name - a localisation id (project-level strings). */
+    displayName?: string;
+    /** Grammatical gender for translators (see `GrammaticalGender`); absent = not specified. */
+    gender?: GrammaticalGender;
+    /** Free-text production notes about the character (casting, voice, intent) - authoring only. */
+    notes?: string;
+    /** The voice actor cast for this character, if known - surfaced in the VO script export (spec §16).
+     *  Authoring-only (not shipped in the runtime bundle). */
+    actor?: string;
+    gameData?: GameData;
+}
+/** The cast as it reaches a compiled bundle: the player-facing fields only. `notes`, `actor` and
+ *  `gender` are authoring / production / translation context, and the compiler drops them, so a shipped
+ *  game never carries a real person's name or a writer's private notes. The compiler copies the shipping
+ *  fields across explicitly (an allow-list), which is what actually keeps a new authoring field out of
+ *  the bundle; this type states the resulting contract for anyone reading a bundle. */
+type BundleCastMember = Omit<CastMember, "notes" | "actor" | "gender">;
+/** A node TYPE that can carry author-defined gameData fields (the gameData schema, project-level).
+ *  Beat kinds map straight through: dialogue = `line`, narration = `text`, game event = `gameEvent`. */
+type GameDataNodeKind = "scene" | "block" | "snippet" | "line" | "text" | "gameEvent";
+/** The value type of a gameData field - the property-type vocabulary plus a multiline-text variant.
+ *  Drives the inspector's editor widget (text / textarea / number / toggle / enum dropdown). */
+type GameDataFieldType = "text" | "multiline" | "number" | "boolean" | "enum";
+/** One author-defined custom field on a node type (host-integration metadata, NOT expression state). */
+interface GameDataField {
+    /** Field key - also the key a node stores its value under in `gameData` (values are name-keyed). */
+    name: string;
+    type: GameDataFieldType;
+    /** The value used when a node sets nothing. Storage is SPARSE - nodes hold only their overrides, and
+     *  a reader falls back to this default (so changing it here propagates to every node that didn't set it). */
+    default?: ScalarValue;
+    /** Allowed values when `type` is "enum". */
+    values?: string[];
+    /** Free-text description of what the field is for - shown as a rollover hint in the inspector. */
+    purpose?: string;
+}
+/** Author-defined gameData fields, grouped by the node type they attach to (project-level schema). */
+type GameDataFields = Partial<Record<GameDataNodeKind, GameDataField[]>>;
+/** A compiled expression envelope: canonical source + pre-derived tagged-tuple AST. */
+interface Expression {
+    src: string;
+    ast: AstNode;
+}
+type CompiledEffect = {
+    kind: "set";
+    target: string;
+    value: Expression;
+};
+interface CompiledSnippet {
+    id: string;
+    type: "snippet";
+    condition?: Expression;
+    beats?: Beat[];
+    onEnter?: CompiledEffect[];
+    onExit?: CompiledEffect[];
+    gameData?: GameData;
+    tags?: string[];
+    jump?: Jump;
+    secretUntilEligible?: boolean;
+    /** Option-position: repeatable (spec §5). Default false = once-only. */
+    sticky?: boolean;
+    /** Option-position: the choice's fallback, auto-followed when last (spec §5). */
+    fallback?: boolean;
+}
+interface CompiledGroup {
+    id: string;
+    type: "group";
+    condition?: Expression;
+    /** Default (omitted) = `"run"`. */
+    selector?: Selector;
+    /** Selector cursor shared across flows (default false = per-flow). */
+    shared?: boolean;
+    options?: SequenceOptions;
+    children: Array<CompiledGroup | CompiledSnippet>;
+    gameData?: GameData;
+    tags?: string[];
+    /** Option-position fields (spec §5) - only when a direct child of a `choice`. */
+    prompt?: PromptBeat;
+    secretUntilEligible?: boolean;
+    /** Repeatable (spec §5). Default false = once-only. */
+    sticky?: boolean;
+    /** The choice's fallback, auto-followed when last (spec §5). */
+    fallback?: boolean;
+}
+interface CompiledBlock {
+    id: string;
+    type: "block";
+    name: string;
+    /** Host-facing address (spec §6); the runtime resolves it to `id`. Absent = derived from `name`. */
+    gameId?: string;
+    children: Array<CompiledGroup | CompiledSnippet>;
+    gameData?: GameData;
+    tags?: string[];
+}
+interface CompiledScene {
+    id: string;
+    type: "scene";
+    name: string;
+    /** Host-facing address (spec §6); the runtime resolves it to `id`. Absent = derived from `name`. */
+    gameId?: string;
+    gameData?: GameData;
+    tags?: string[];
+    onEntry?: CompiledEffect[];
+    sceneProps?: PropertyDecl[];
+    blocks: CompiledBlock[];
+}
+interface Bundle {
+    schema: string;
+    /** `hash` fingerprints the WHOLE bundle (binds saves, gates staleness); `structureHash` is the same
+     *  fingerprint with the string tables left out, so same structureHash + a different hash = a
+     *  text-only edit, safe to hot-swap in place (live bundle refresh). */
+    content: {
+        project: string;
+        version?: string;
+        hash?: string;
+        structureHash?: string;
+    };
+    voiced: boolean;
+    locales: {
+        default: string;
+        included: string[];
+    };
+    /** Player-facing cast only: the compiler strips notes / actor / gender (see `BundleCastMember`). */
+    cast?: BundleCastMember[];
+    properties?: PropertyDecl[];
+    /** Host / world scope declarations, baked from the project so the runtime can self-back a declared
+     *  scope (`@world`, ...) when no host resolver claims its token. Absent = no host scopes. */
+    scopeRegistry?: HostScopeRegistry;
+    gameDataFields?: GameDataFields;
+    scenes: Record<string, CompiledScene>;
+    /** locale -> (beatId -> text). In "embedded" localisation this carries every included locale; in "ids"
+     *  it is EMPTY (the runtime emits beat IDs), unless `localisation.sourceDebug` embedded the source locale
+     *  for debug playback. `content.hash` is computed over the FULL strings regardless, so the staleness gate
+     *  is unaffected. */
+    strings: Record<string, Record<string, string>>;
+    /** How strings ship + resolve (spec §11). Absent = "embedded" (back-compat default): the runtime resolves
+     *  `strings` per locale. "ids": the runtime emits beat IDs and the game localises them itself; `sourceDebug`
+     *  means the source locale is embedded purely for debug playback and the runtime should flag the build as
+     *  not shippable. */
+    localisation?: {
+        mode: "embedded" | "ids";
+        sourceDebug?: boolean;
+    };
+    /** Closed-caption delimiters baked from the project (#214). Absent = the default `(` / `)`; the
+     *  runtime strips spans between them from line text when a game disables captions. */
+    closedCaptions?: CaptionDelimiters;
+}
+/** Closed-caption configuration (#214). `open`/`close` wrap a caption cue inside a dialogue line (both
+ *  non-empty; they MAY be the same token, e.g. `*…*`). `character` names a cast member whose lines are a
+ *  pure caption: when captions are off, ALL of that character's dialogue (and its speaker label) is
+ *  omitted - delimiters or not - leaving a silent line that still fires (so audio plays). Absent / empty
+ *  `character` resolves to the default `SFX` (you "disable" it simply by never using that speaker). */
+interface CaptionDelimiters {
+    open: string;
+    close: string;
+    character?: string;
+}
+
+interface BundleInspectorOptions {
+    /** Where to mount the panel. If omitted, append the returned `el` yourself. */
+    container?: HTMLElement;
+    /** Panel heading. Default "Bundle". */
+    title?: string;
+    /** Sections open on mount. Default: identity and addresses, the two an
+     *  integrator reaches for first; the rest are a click away. */
+    open?: BundleSection[];
+}
+type BundleSection = "identity" | "addresses" | "hostScopes" | "properties" | "gameData" | "counts";
+interface BundleInspector {
+    /** The panel root (already inside `container` if you passed one). */
+    readonly el: HTMLElement;
+    /** The description the panel is showing, for a caller that wants the data too. */
+    readonly description: BundleDescription;
+    /** Remove the panel from the DOM. */
+    destroy(): void;
+}
+/**
+ * Build a read-only panel describing a compiled bundle: what it is, what game
+ * code may call on it, and what the host must supply.
+ */
+declare function createBundleInspector(bundle: Bundle, opts?: BundleInspectorOptions): BundleInspector;
+
 interface AudioResolver {
     /** The full path/URL of a beat's winning audio take, or null when it has none. */
     resolve(beatId: string): string | null;
@@ -148,4 +483,4 @@ interface AudioResolver {
  */
 declare function createAudioResolver(manifestJson: string, basePath: string): AudioResolver;
 
-export { type AudioResolver, type DebugLink, type DebugLinkOptions, type DebugSocketLike, type LiveBundleResult, type PropertyInspector, type PropertyInspectorOptions, type PropertyValue, SAVE_SCHEMA, type SaveEnvelope, type StateChange, type StateLogger, type StateLoggerOptions, type StateSnapshot, type StateValue, applyLiveBundle, createAudioResolver, createDebugLink, createPropertyInspector, createStateLogger, deserializeState, diffState, getProperty, loadState, saveState, serializeState, setProperties, setProperty, snapshotState };
+export { type AudioResolver, type BundleInspector, type BundleInspectorOptions, type BundleSection, type DebugLink, type DebugLinkOptions, type DebugSocketLike, type LiveBundleResult, type PropertyInspector, type PropertyInspectorOptions, type PropertyValue, SAVE_SCHEMA, type SaveEnvelope, type StateChange, type StateLogger, type StateLoggerOptions, type StateSnapshot, type StateValue, applyLiveBundle, createAudioResolver, createBundleInspector, createDebugLink, createPropertyInspector, createStateLogger, deserializeState, diffState, getProperty, loadState, saveState, serializeState, setProperties, setProperty, snapshotState };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SaveGame, Engine, StepResult, Bundle } from '@patterkit/runtime';
+import { SaveGame, Engine, StepResult, Bundle as Bundle$1, BundleDescription } from '@patterkit/runtime';
 
 declare const SAVE_SCHEMA = "patter/save@0";
 interface SaveEnvelope {
@@ -107,7 +107,7 @@ interface LiveBundleResult {
     /** The engine to keep using: the same instance for a "text" swap, a replacement for "structure". */
     engine: Engine;
     /** The parsed pushed bundle - hold on to it for the next apply's comparison. */
-    bundle: Bundle;
+    bundle: Bundle$1;
     /** Which tier applied: "text" (strings-only, nothing restarted) or "structure" (full hot swap). */
     kind: "text" | "structure";
 }
@@ -117,7 +117,7 @@ interface LiveBundleResult {
  * unparseable JSON - a structural swap's edge cases are absorbed by the §9.8 drift policy inside
  * `hotSwap`, which never throws for ordinary edits.
  */
-declare function applyLiveBundle(engine: Engine, current: Bundle, data: string): LiveBundleResult;
+declare function applyLiveBundle(engine: Engine, current: Bundle$1, data: string): LiveBundleResult;
 
 interface PropertyInspectorOptions {
     /** Where to mount the panel. If omitted, append the returned `el` yourself. */
@@ -137,6 +137,341 @@ interface PropertyInspector {
 }
 declare function createPropertyInspector(engine: Engine, opts?: PropertyInspectorOptions): PropertyInspector;
 
+type BinaryOp = "==" | "!=" | ">" | ">=" | "<" | "<=" | "+" | "-" | "*" | "/" | "and" | "or";
+type UnaryOp = "not" | "neg";
+type AstNode = ["b", boolean] | ["n", number] | ["s", string] | ["sv", string, string] | ["u", UnaryOp, AstNode] | ["bin", BinaryOp, AstNode, AstNode] | ["call", string, ...AstNode[]] | ["fd", "+" | "-", string];
+
+type ScalarValue = boolean | number | string | string[];
+/** Developer-defined host metadata (spec §17). Opaque to Patter. */
+type GameData = Record<string, unknown>;
+/** A scene/block id, or the reserved "END". */
+type JumpTarget = string;
+interface Jump {
+    to: JumpTarget;
+    /** "jump" (one-way, default) or "call" (jump-and-return via the flow callstack). */
+    mode?: "jump" | "call";
+}
+interface LineBeat {
+    id: string;
+    kind: "line";
+    /** Speaker; must be a member of the project cast (validated). */
+    character?: string;
+    /** Performance direction, language-neutral (never localised). */
+    direction?: string;
+    gameData?: GameData;
+    /** Author-defined freeform tags (#215): a cross-cutting label layer that travels to the runtime.
+     *  At runtime a beat's tags are the UNION of its own and every ancestor's (scene → block → group(s) →
+     *  snippet → beat). Each tag is letters/digits/symbols with NO comma and NO whitespace; deduped. */
+    tags?: string[];
+}
+/**
+ * Authorial voice / narration - speaker-less prose (spec §2). Never voiced; its
+ * localised text always permits inline `{@name}` interpolation (spec §16). This
+ * is the on-screen-text role (e.g. "A door slams!") - distinct from a game-event
+ * beat, which is a pure engine instruction with no localised content.
+ */
+interface TextBeat {
+    id: string;
+    kind: "text";
+    gameData?: GameData;
+    /** Author tags (#215). See LineBeat.tags. */
+    tags?: string[];
+}
+/**
+ * A GAME EVENT (spec §2): a pure engine instruction with no player-facing text - just `gameData` the host
+ * reads when the beat plays (comments / docs attach via the authoring file by id). Named "game event"
+ * rather than "action" because a screenplay's "action" is prose, which is our text beat. Player-facing
+ * words are a line or text beat instead.
+ */
+interface GameEventBeat {
+    id: string;
+    kind: "gameEvent";
+    gameData?: GameData;
+    /** Author tags (#215). See LineBeat.tags. */
+    tags?: string[];
+}
+type Beat = LineBeat | TextBeat | GameEventBeat;
+type Selector = "run" | "branch" | "sequence" | "choice";
+/** How a `sequence` walks its children. `specificity` = **Best match**: pick the eligible
+ *  child whose condition most specifically fits the current state (the most atomic constraints
+ *  actively holding it true); equally-specific ties break by the seeded shuffle. A child with no
+ *  condition scores zero, so it acts as the filler that wins only when nothing more specific is
+ *  eligible. Composes with `exhaust`: `repeat` re-scores every visit (re-pickable, the Best-match
+ *  default), `once` uses each pick up so the group slides down to the filler (graceful degradation). */
+type SelectorOrder = "sequential" | "shuffle" | "specificity";
+/** What a `sequence` does after one full pass through its children. */
+type SelectorExhaust = "once" | "repeat" | "stick";
+/**
+ * `sequence` selector config (spec §4). One stateful picker with two orthogonal
+ * axes subsumes Ink's stopping / cycle / once / shuffle and their combinations.
+ * Defaults: `order: "sequential"`, `exhaust: "once"`. `shuffle` draws without
+ * replacement and never repeats a line back-to-back (built in).
+ */
+interface SequenceOptions {
+    order?: SelectorOrder;
+    exhaust?: SelectorExhaust;
+}
+/** An option's prompt beat (spec §5): a single line | text beat - the choice text. */
+type PromptBeat = LineBeat | TextBeat;
+type PropertyType = "boolean" | "number" | "string" | "flags" | "enum";
+interface PropertyDecl {
+    name: string;
+    type: PropertyType;
+    default?: ScalarValue;
+    /**
+     * The orthogonal *sharing* axis (spec §7): is this property's value shared across
+     * all flows (one world value) or kept per-flow? It does NOT change the reference
+     * syntax - sharing is set here, on the declaration, not by a different scope token.
+     * The default depends on the scope it is declared in: a **global** property
+     * (project `properties` -> `@patter`) defaults to **shared**; a **scene-local**
+     * property (scene `sceneProps` -> `@scene`) defaults to **not shared** (per-flow).
+     */
+    shared?: boolean;
+    /**
+     * Persistence axis, for **scene-local (`@scene`) properties** (spec §7). Default
+     * `false`: the value PERSISTS across scene re-entries (like every other property).
+     * `true`: the value is **reseeded to its default on every scene entry** - "fresh
+     * each playthrough" (Ink's `temp`). Orthogonal to `shared`. Ignored on global
+     * (`@patter`) properties, which always persist for the life of the piece.
+     */
+    temporary?: boolean;
+    /** For enum / flags. */
+    values?: string[];
+    /** Free-text author note documenting what this property is for (authoring only; shown as a hint). */
+    purpose?: string;
+}
+/**
+ * A property of a host / world scope (`@world`, `@game`, ...). The same shape the
+ * `@wildwinter/scoperegistry` `scopeRegistrySpec` uses, declared structurally here
+ * so the model stays free of a runtime dependency. `default` seeds the standalone
+ * runtime's self-backed bag (see `HostScopeSpec`); `writable: false` makes the
+ * property read-only to the story (validated at compile time).
+ */
+interface HostScopeDecl {
+    name: string;
+    type: PropertyType;
+    values?: string[];
+    default?: ScalarValue;
+    writable?: boolean;
+    /** Free-text author note documenting the property (authoring only; shown as a hint). */
+    purpose?: string;
+}
+/** One scope (`token`) in a project's host-scope registry. */
+interface HostScopeSpec {
+    /** The scope token after `@` (e.g. `"world"`). Must not collide with Patter's own
+     *  `patter` / `scene` / `flow`. */
+    token: string;
+    /** Scope-level read/write default for its declarations (default true). */
+    writable?: boolean;
+    /** Property declarations; omit for an opaque scope (any name, unchecked). */
+    declarations?: HostScopeDecl[];
+}
+/**
+ * A project's host-scope registry: the `scopeRegistrySpec` it OWNS (spec
+ * design/scope-registry.md §6). Makes `@world` (and any host scope) first-class
+ * in a standalone project: the compiler validates references into it, the runtime
+ * self-backs it from declaration defaults when no host resolver claims the token,
+ * and coverage drives its values. Structurally identical to scoperegistry's
+ * `ScopeRegistrySpec` so it threads straight through the compiler.
+ */
+interface HostScopeRegistry {
+    version: number;
+    scopes: HostScopeSpec[];
+}
+/** A character's grammatical gender, for localisation. Translators need it to inflect the speaker's own
+ *  lines in gendered languages (adjectives, participles, pronouns), which the source text alone often
+ *  cannot tell them. Absent means "not specified". Authoring-only: it never reaches the runtime bundle,
+ *  but it IS carried into the localisation handoff formats as translator context (spec §14).
+ *
+ *  Free text, not a closed set: real languages need more than three genders (common/utrum, animate/
+ *  inanimate, and so on) and translators name them differently. `COMMON_GENDERS` seeds the editor's
+ *  auto-suggest so the everyday values stay spelled consistently; anything else is still valid. */
+type GrammaticalGender = string;
+interface CastMember {
+    /** Canonical speaker name (matched by a beat's `character`); language-neutral key. */
+    name: string;
+    /** Localised player-facing name - a localisation id (project-level strings). */
+    displayName?: string;
+    /** Grammatical gender for translators (see `GrammaticalGender`); absent = not specified. */
+    gender?: GrammaticalGender;
+    /** Free-text production notes about the character (casting, voice, intent) - authoring only. */
+    notes?: string;
+    /** The voice actor cast for this character, if known - surfaced in the VO script export (spec §16).
+     *  Authoring-only (not shipped in the runtime bundle). */
+    actor?: string;
+    gameData?: GameData;
+}
+/** The cast as it reaches a compiled bundle: the player-facing fields only. `notes`, `actor` and
+ *  `gender` are authoring / production / translation context, and the compiler drops them, so a shipped
+ *  game never carries a real person's name or a writer's private notes. The compiler copies the shipping
+ *  fields across explicitly (an allow-list), which is what actually keeps a new authoring field out of
+ *  the bundle; this type states the resulting contract for anyone reading a bundle. */
+type BundleCastMember = Omit<CastMember, "notes" | "actor" | "gender">;
+/** A node TYPE that can carry author-defined gameData fields (the gameData schema, project-level).
+ *  Beat kinds map straight through: dialogue = `line`, narration = `text`, game event = `gameEvent`. */
+type GameDataNodeKind = "scene" | "block" | "snippet" | "line" | "text" | "gameEvent";
+/** The value type of a gameData field - the property-type vocabulary plus a multiline-text variant.
+ *  Drives the inspector's editor widget (text / textarea / number / toggle / enum dropdown). */
+type GameDataFieldType = "text" | "multiline" | "number" | "boolean" | "enum";
+/** One author-defined custom field on a node type (host-integration metadata, NOT expression state). */
+interface GameDataField {
+    /** Field key - also the key a node stores its value under in `gameData` (values are name-keyed). */
+    name: string;
+    type: GameDataFieldType;
+    /** The value used when a node sets nothing. Storage is SPARSE - nodes hold only their overrides, and
+     *  a reader falls back to this default (so changing it here propagates to every node that didn't set it). */
+    default?: ScalarValue;
+    /** Allowed values when `type` is "enum". */
+    values?: string[];
+    /** Free-text description of what the field is for - shown as a rollover hint in the inspector. */
+    purpose?: string;
+}
+/** Author-defined gameData fields, grouped by the node type they attach to (project-level schema). */
+type GameDataFields = Partial<Record<GameDataNodeKind, GameDataField[]>>;
+/** A compiled expression envelope: canonical source + pre-derived tagged-tuple AST. */
+interface Expression {
+    src: string;
+    ast: AstNode;
+}
+type CompiledEffect = {
+    kind: "set";
+    target: string;
+    value: Expression;
+};
+interface CompiledSnippet {
+    id: string;
+    type: "snippet";
+    condition?: Expression;
+    beats?: Beat[];
+    onEnter?: CompiledEffect[];
+    onExit?: CompiledEffect[];
+    gameData?: GameData;
+    tags?: string[];
+    jump?: Jump;
+    secretUntilEligible?: boolean;
+    /** Option-position: repeatable (spec §5). Default false = once-only. */
+    sticky?: boolean;
+    /** Option-position: the choice's fallback, auto-followed when last (spec §5). */
+    fallback?: boolean;
+}
+interface CompiledGroup {
+    id: string;
+    type: "group";
+    condition?: Expression;
+    /** Default (omitted) = `"run"`. */
+    selector?: Selector;
+    /** Selector cursor shared across flows (default false = per-flow). */
+    shared?: boolean;
+    options?: SequenceOptions;
+    children: Array<CompiledGroup | CompiledSnippet>;
+    gameData?: GameData;
+    tags?: string[];
+    /** Option-position fields (spec §5) - only when a direct child of a `choice`. */
+    prompt?: PromptBeat;
+    secretUntilEligible?: boolean;
+    /** Repeatable (spec §5). Default false = once-only. */
+    sticky?: boolean;
+    /** The choice's fallback, auto-followed when last (spec §5). */
+    fallback?: boolean;
+}
+interface CompiledBlock {
+    id: string;
+    type: "block";
+    name: string;
+    /** Host-facing address (spec §6); the runtime resolves it to `id`. Absent = derived from `name`. */
+    gameId?: string;
+    children: Array<CompiledGroup | CompiledSnippet>;
+    gameData?: GameData;
+    tags?: string[];
+}
+interface CompiledScene {
+    id: string;
+    type: "scene";
+    name: string;
+    /** Host-facing address (spec §6); the runtime resolves it to `id`. Absent = derived from `name`. */
+    gameId?: string;
+    gameData?: GameData;
+    tags?: string[];
+    onEntry?: CompiledEffect[];
+    sceneProps?: PropertyDecl[];
+    blocks: CompiledBlock[];
+}
+interface Bundle {
+    schema: string;
+    /** `hash` fingerprints the WHOLE bundle (binds saves, gates staleness); `structureHash` is the same
+     *  fingerprint with the string tables left out, so same structureHash + a different hash = a
+     *  text-only edit, safe to hot-swap in place (live bundle refresh). */
+    content: {
+        project: string;
+        version?: string;
+        hash?: string;
+        structureHash?: string;
+    };
+    voiced: boolean;
+    locales: {
+        default: string;
+        included: string[];
+    };
+    /** Player-facing cast only: the compiler strips notes / actor / gender (see `BundleCastMember`). */
+    cast?: BundleCastMember[];
+    properties?: PropertyDecl[];
+    /** Host / world scope declarations, baked from the project so the runtime can self-back a declared
+     *  scope (`@world`, ...) when no host resolver claims its token. Absent = no host scopes. */
+    scopeRegistry?: HostScopeRegistry;
+    gameDataFields?: GameDataFields;
+    scenes: Record<string, CompiledScene>;
+    /** locale -> (beatId -> text). In "embedded" localisation this carries every included locale; in "ids"
+     *  it is EMPTY (the runtime emits beat IDs), unless `localisation.sourceDebug` embedded the source locale
+     *  for debug playback. `content.hash` is computed over the FULL strings regardless, so the staleness gate
+     *  is unaffected. */
+    strings: Record<string, Record<string, string>>;
+    /** How strings ship + resolve (spec §11). Absent = "embedded" (back-compat default): the runtime resolves
+     *  `strings` per locale. "ids": the runtime emits beat IDs and the game localises them itself; `sourceDebug`
+     *  means the source locale is embedded purely for debug playback and the runtime should flag the build as
+     *  not shippable. */
+    localisation?: {
+        mode: "embedded" | "ids";
+        sourceDebug?: boolean;
+    };
+    /** Closed-caption delimiters baked from the project (#214). Absent = the default `(` / `)`; the
+     *  runtime strips spans between them from line text when a game disables captions. */
+    closedCaptions?: CaptionDelimiters;
+}
+/** Closed-caption configuration (#214). `open`/`close` wrap a caption cue inside a dialogue line (both
+ *  non-empty; they MAY be the same token, e.g. `*…*`). `character` names a cast member whose lines are a
+ *  pure caption: when captions are off, ALL of that character's dialogue (and its speaker label) is
+ *  omitted - delimiters or not - leaving a silent line that still fires (so audio plays). Absent / empty
+ *  `character` resolves to the default `SFX` (you "disable" it simply by never using that speaker). */
+interface CaptionDelimiters {
+    open: string;
+    close: string;
+    character?: string;
+}
+
+interface BundleInspectorOptions {
+    /** Where to mount the panel. If omitted, append the returned `el` yourself. */
+    container?: HTMLElement;
+    /** Panel heading. Default "Bundle". */
+    title?: string;
+    /** Sections open on mount. Default: identity and addresses, the two an
+     *  integrator reaches for first; the rest are a click away. */
+    open?: BundleSection[];
+}
+type BundleSection = "identity" | "addresses" | "hostScopes" | "properties" | "gameData" | "counts";
+interface BundleInspector {
+    /** The panel root (already inside `container` if you passed one). */
+    readonly el: HTMLElement;
+    /** The description the panel is showing, for a caller that wants the data too. */
+    readonly description: BundleDescription;
+    /** Remove the panel from the DOM. */
+    destroy(): void;
+}
+/**
+ * Build a read-only panel describing a compiled bundle: what it is, what game
+ * code may call on it, and what the host must supply.
+ */
+declare function createBundleInspector(bundle: Bundle, opts?: BundleInspectorOptions): BundleInspector;
+
 interface AudioResolver {
     /** The full path/URL of a beat's winning audio take, or null when it has none. */
     resolve(beatId: string): string | null;
@@ -148,4 +483,4 @@ interface AudioResolver {
  */
 declare function createAudioResolver(manifestJson: string, basePath: string): AudioResolver;
 
-export { type AudioResolver, type DebugLink, type DebugLinkOptions, type DebugSocketLike, type LiveBundleResult, type PropertyInspector, type PropertyInspectorOptions, type PropertyValue, SAVE_SCHEMA, type SaveEnvelope, type StateChange, type StateLogger, type StateLoggerOptions, type StateSnapshot, type StateValue, applyLiveBundle, createAudioResolver, createDebugLink, createPropertyInspector, createStateLogger, deserializeState, diffState, getProperty, loadState, saveState, serializeState, setProperties, setProperty, snapshotState };
+export { type AudioResolver, type BundleInspector, type BundleInspectorOptions, type BundleSection, type DebugLink, type DebugLinkOptions, type DebugSocketLike, type LiveBundleResult, type PropertyInspector, type PropertyInspectorOptions, type PropertyValue, SAVE_SCHEMA, type SaveEnvelope, type StateChange, type StateLogger, type StateLoggerOptions, type StateSnapshot, type StateValue, applyLiveBundle, createAudioResolver, createBundleInspector, createDebugLink, createPropertyInspector, createStateLogger, deserializeState, diffState, getProperty, loadState, saveState, serializeState, setProperties, setProperty, snapshotState };

package/dist/index.js

@@ -223,8 +223,8 @@ function sameValue(a, b) {
 function createPropertyInspector(engine, opts = {}) {
   const doc = opts.container?.ownerDocument ?? document;
   injectStyle(doc);
-  const el = doc.createElement("div");
-  el.className = "pp-insp";
+  const el2 = doc.createElement("div");
+  el2.className = "pp-insp";
   const heading = doc.createElement("h4");
   heading.textContent = opts.title ?? "Runtime state";
   const list = doc.createElement("div");
@@ -263,15 +263,15 @@ function createPropertyInspector(engine, opts = {}) {
     input.click();
   });
   io.append(saveBtn, loadBtn);
-  el.append(heading, io, list);
+  el2.append(heading, io, list);
   const rowRefreshers = [];
-  const buildRow = (row) => {
+  const buildRow = (row2) => {
     const r = doc.createElement("div");
     r.className = "pp-insp-row";
     const label = doc.createElement("span");
     label.className = "pp-insp-ref";
-    label.textContent = row.ref;
-    label.title = row.ref;
+    label.textContent = row2.ref;
+    label.title = row2.ref;
     const ctl = doc.createElement("div");
     ctl.className = "pp-insp-ctl";
     const reset = doc.createElement("button");
@@ -283,37 +283,37 @@ function createPropertyInspector(engine, opts = {}) {
     list.appendChild(r);
     let read;
     const commit = (v) => {
-      engine.setProperty(row.ref, v);
+      engine.setProperty(row2.ref, v);
       syncReset();
     };
     const focused = (node) => doc.activeElement === node;
     function syncReset() {
-      reset.disabled = sameValue(engine.getProperty(row.ref), row.default);
+      reset.disabled = sameValue(engine.getProperty(row2.ref), row2.default);
     }
     reset.addEventListener("click", () => {
-      engine.setProperty(row.ref, row.default);
+      engine.setProperty(row2.ref, row2.default);
       read();
       syncReset();
     });
-    if (row.type === "boolean") {
+    if (row2.type === "boolean") {
       const cb = doc.createElement("input");
       cb.type = "checkbox";
       cb.addEventListener("change", () => commit(cb.checked));
       ctl.appendChild(cb);
       read = () => {
-        if (!focused(cb)) cb.checked = engine.getProperty(row.ref) === true;
+        if (!focused(cb)) cb.checked = engine.getProperty(row2.ref) === true;
       };
-    } else if (row.type === "number") {
+    } else if (row2.type === "number") {
       const inp = doc.createElement("input");
       inp.type = "number";
       inp.addEventListener("change", () => commit(Number(inp.value)));
       ctl.appendChild(inp);
       read = () => {
-        if (!focused(inp)) inp.value = String(engine.getProperty(row.ref) ?? "");
+        if (!focused(inp)) inp.value = String(engine.getProperty(row2.ref) ?? "");
       };
-    } else if (row.type === "enum") {
+    } else if (row2.type === "enum") {
       const sel = doc.createElement("select");
-      for (const v of row.values ?? []) {
+      for (const v of row2.values ?? []) {
         const o = doc.createElement("option");
         o.value = v;
         o.textContent = v;
@@ -322,9 +322,9 @@ function createPropertyInspector(engine, opts = {}) {
       sel.addEventListener("change", () => commit(sel.value));
       ctl.appendChild(sel);
       read = () => {
-        if (!focused(sel)) sel.value = String(engine.getProperty(row.ref) ?? "");
+        if (!focused(sel)) sel.value = String(engine.getProperty(row2.ref) ?? "");
       };
-    } else if (row.type === "flags") {
+    } else if (row2.type === "flags") {
       const inp = doc.createElement("input");
       inp.type = "text";
       inp.placeholder = "comma, separated, flags";
@@ -332,7 +332,7 @@ function createPropertyInspector(engine, opts = {}) {
       ctl.appendChild(inp);
       read = () => {
         if (!focused(inp)) {
-          const v = engine.getProperty(row.ref);
+          const v = engine.getProperty(row2.ref);
           inp.value = Array.isArray(v) ? v.join(", ") : "";
         }
       };
@@ -342,7 +342,7 @@ function createPropertyInspector(engine, opts = {}) {
       inp.addEventListener("change", () => commit(inp.value));
       ctl.appendChild(inp);
       read = () => {
-        if (!focused(inp)) inp.value = String(engine.getProperty(row.ref) ?? "");
+        if (!focused(inp)) inp.value = String(engine.getProperty(row2.ref) ?? "");
       };
     }
     read();
@@ -359,21 +359,165 @@ function createPropertyInspector(engine, opts = {}) {
     empty.textContent = "No @patter properties.";
     list.appendChild(empty);
   } else {
-    for (const row of props) buildRow(row);
+    for (const row2 of props) buildRow(row2);
   }
   const refresh = () => {
     for (const fn of rowRefreshers) fn();
   };
-  opts.container?.appendChild(el);
+  opts.container?.appendChild(el2);
   const pollMs = opts.pollMs ?? 250;
   let timer;
   if (pollMs > 0) timer = setInterval(refresh, pollMs);
   return {
-    el,
+    el: el2,
     refresh,
     destroy() {
       if (timer !== void 0) clearInterval(timer);
-      el.remove();
+      el2.remove();
+    }
+  };
+}
+
+// src/bundle-inspector.ts
+import { describeBundle } from "@patterkit/runtime";
+var STYLE_ID2 = "pp-bundle-style";
+var CSS2 = `
+.pp-bundle{font:13px/1.4 ui-sans-serif,system-ui,sans-serif;color:#15201e;background:#f4efe6;border:1px solid #cfc7b8;border-radius:10px;padding:.6rem .7rem;max-width:26rem;box-shadow:0 6px 20px rgba(21,32,30,.12)}
+.pp-bundle h4{margin:0 0 .4rem;font:600 .72rem/1 ui-sans-serif,system-ui,sans-serif;letter-spacing:.08em;text-transform:uppercase;color:#5c6b62}
+.pp-bundle details{border-top:1px solid #e3dccf;padding:.3rem 0}
+.pp-bundle details:first-of-type{border-top:0}
+.pp-bundle summary{cursor:pointer;font-weight:600;color:#214f4b;list-style:none}
+.pp-bundle summary::-webkit-details-marker{display:none}
+.pp-bundle summary::before{content:"\\25B8";display:inline-block;width:1rem;color:#8a9691}
+.pp-bundle details[open]>summary::before{content:"\\25BE"}
+.pp-bundle-count{color:#8a9691;font-weight:400}
+.pp-bundle-row{display:flex;gap:.4rem;margin:.16rem 0 .16rem 1rem}
+.pp-bundle-key{flex:0 0 8rem;color:#5c6b62}
+.pp-bundle-val,.pp-bundle-addr{font-family:ui-monospace,monospace;font-size:.78rem;color:#214f4b;word-break:break-all}
+.pp-bundle-sub{margin-left:2rem}
+.pp-bundle-empty{color:#8a9691;font-style:italic;margin-left:1rem}
+.pp-bundle-warn{color:#8a3a2f;font-weight:600}
+.pp-bundle-tag{font-size:.7rem;color:#5c6b62;border:1px solid #cfc7b8;border-radius:5px;padding:0 .25rem;margin-left:.3rem}
+`;
+function injectStyle2(doc) {
+  if (doc.getElementById(STYLE_ID2)) return;
+  const s = doc.createElement("style");
+  s.id = STYLE_ID2;
+  s.textContent = CSS2;
+  (doc.head ?? doc.documentElement).appendChild(s);
+}
+var el = (doc, tag, cls, text) => {
+  const e = doc.createElement(tag);
+  if (cls) e.className = cls;
+  if (text !== void 0) e.textContent = text;
+  return e;
+};
+function row(doc, key, value, valueClass = "pp-bundle-val") {
+  const r = el(doc, "div", "pp-bundle-row");
+  r.append(el(doc, "span", "pp-bundle-key", key), el(doc, "span", valueClass, value));
+  return r;
+}
+function propertyRow(doc, p) {
+  const r = el(doc, "div", "pp-bundle-row");
+  r.append(el(doc, "span", "pp-bundle-key pp-bundle-addr", p.name));
+  const meta = el(doc, "span", "pp-bundle-val", p.type);
+  if (!p.hasDefault) meta.append(el(doc, "span", "pp-bundle-tag", "no default"));
+  r.append(meta);
+  return r;
+}
+function section(doc, name, label, count, open) {
+  const d = doc.createElement("details");
+  d.dataset["section"] = name;
+  d.open = open;
+  const s = doc.createElement("summary");
+  s.textContent = label;
+  if (count !== null) s.append(el(doc, "span", "pp-bundle-count", ` ${count}`));
+  d.append(s);
+  return d;
+}
+function createBundleInspector(bundle, opts = {}) {
+  const doc = opts.container?.ownerDocument ?? document;
+  injectStyle2(doc);
+  const d = describeBundle(bundle);
+  const open = new Set(opts.open ?? ["identity", "addresses"]);
+  const root = el(doc, "div", "pp-bundle");
+  root.append(el(doc, "h4", void 0, opts.title ?? "Bundle"));
+  const id = section(doc, "identity", d.identity.project || "(unnamed project)", null, open.has("identity"));
+  if (d.identity.version) id.append(row(doc, "version", d.identity.version));
+  id.append(row(doc, "schema", d.identity.schema));
+  id.append(row(doc, "locales", `${d.identity.defaultLocale}${d.identity.locales.length > 1 ? ` (+${d.identity.locales.length - 1})` : ""}`));
+  id.append(row(doc, "strings", d.identity.localisation));
+  if (d.identity.voiced) id.append(row(doc, "voiced", "yes"));
+  if (d.identity.hash) id.append(row(doc, "hash", d.identity.hash));
+  if (d.identity.structureHash) id.append(row(doc, "structure", d.identity.structureHash));
+  if (d.identity.sourceDebug) {
+    id.append(row(doc, "build", "SOURCE DEBUG - not shippable", "pp-bundle-val pp-bundle-warn"));
+  }
+  root.append(id);
+  const addr = section(doc, "addresses", "Addresses", d.addresses.length, open.has("addresses"));
+  if (!d.addresses.length) addr.append(el(doc, "div", "pp-bundle-empty", "no scenes"));
+  for (const a of d.addresses) {
+    const r = el(doc, "div", "pp-bundle-row");
+    r.append(el(doc, "span", "pp-bundle-key pp-bundle-addr", a.gameId), el(doc, "span", "pp-bundle-val", a.name));
+    addr.append(r);
+    for (const b of a.blocks) {
+      const br = el(doc, "div", "pp-bundle-row pp-bundle-sub");
+      br.append(el(doc, "span", "pp-bundle-key pp-bundle-addr", b.gameId), el(doc, "span", "pp-bundle-val", b.name));
+      addr.append(br);
+    }
+  }
+  root.append(addr);
+  const hostCount = d.hostScopes.reduce((n, s) => n + s.properties.length, 0);
+  const host = section(doc, "hostScopes", "Host properties", hostCount, open.has("hostScopes"));
+  if (!d.hostScopes.length) host.append(el(doc, "div", "pp-bundle-empty", "the game supplies nothing"));
+  for (const s of d.hostScopes) {
+    const head = el(doc, "div", "pp-bundle-row");
+    head.append(el(doc, "span", "pp-bundle-key pp-bundle-addr", `@${s.token}`));
+    const meta = el(doc, "span", "pp-bundle-val", s.opaque ? "any name, unchecked" : `${s.properties.length} declared`);
+    if (!s.writable) meta.append(el(doc, "span", "pp-bundle-tag", "read-only"));
+    head.append(meta);
+    host.append(head);
+    for (const p of s.properties) {
+      const pr = propertyRow(doc, p);
+      pr.classList.add("pp-bundle-sub");
+      host.append(pr);
+    }
+  }
+  root.append(host);
+  const ownedCount = d.properties.patter.length + d.properties.scene.reduce((n, s) => n + s.properties.length, 0);
+  const owned = section(doc, "properties", "Story properties", ownedCount, open.has("properties"));
+  if (!ownedCount) owned.append(el(doc, "div", "pp-bundle-empty", "none declared"));
+  for (const p of d.properties.patter) owned.append(propertyRow(doc, p));
+  for (const s of d.properties.scene) {
+    owned.append(row(doc, `@scene`, s.gameId, "pp-bundle-val pp-bundle-addr"));
+    for (const p of s.properties) {
+      const pr = propertyRow(doc, p);
+      pr.classList.add("pp-bundle-sub");
+      owned.append(pr);
+    }
+  }
+  root.append(owned);
+  if (d.gameData.length) {
+    const gd2 = section(doc, "gameData", "Game data", d.gameData.reduce((n, g) => n + g.fields.length, 0), open.has("gameData"));
+    for (const g of d.gameData) {
+      gd2.append(row(doc, "on", g.kind));
+      for (const f of g.fields) {
+        const fr = el(doc, "div", "pp-bundle-row pp-bundle-sub");
+        fr.append(el(doc, "span", "pp-bundle-key pp-bundle-addr", f.name), el(doc, "span", "pp-bundle-val", f.type));
+        gd2.append(fr);
+      }
+    }
+    root.append(gd2);
+  }
+  const counts = section(doc, "counts", "Counts", null, open.has("counts"));
+  for (const [key, value] of Object.entries(d.counts)) counts.append(row(doc, key, String(value)));
+  root.append(counts);
+  opts.container?.append(root);
+  return {
+    el: root,
+    description: d,
+    destroy() {
+      root.remove();
     }
   };
 }
@@ -395,6 +539,7 @@ export {
   SAVE_SCHEMA,
   applyLiveBundle,
   createAudioResolver,
+  createBundleInspector,
   createDebugLink,
   createPropertyInspector,
   createStateLogger,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/play-helpers",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Thin game-integration helpers around @patterkit/runtime: save/load serialisation, runtime property setters, a state logger, the Patterpad Live Link client + hot reload, a property inspector, and audio resolution. The Patterplay JS companion.",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,6 @@
     "build": "tsup src/index.ts --format esm,cjs --dts --clean"
   },
   "dependencies": {
-    "@patterkit/runtime": "0.4.1"
+    "@patterkit/runtime": "0.4.3"
   }
 }