@patterkit/compiler 0.1.0

package/dist/index.cjs

@@ -0,0 +1,367 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  compileExpression: () => compileExpression,
+  exportBundle: () => exportBundle,
+  hostScopesToSpec: () => import_dialect3.hostScopesToSpec,
+  validateConditions: () => validateConditions,
+  validateInterpolation: () => validateInterpolation
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/expressions.ts
+var import_expr = require("@wildwinter/expr");
+var import_dialect = require("@patterkit/dialect");
+var import_model = require("@patterkit/model");
+function compileExpression(src, foreign) {
+  return (0, import_expr.compile)(src, (0, import_dialect.dialectWithForeignScopes)(foreign));
+}
+function validateConditions(input, options = {}) {
+  const issues = [];
+  const foreign = options.foreignScopes;
+  const dialect = (0, import_dialect.dialectWithForeignScopes)(foreign);
+  const readOnly = readOnlyForeignTargets(foreign);
+  const opaqueForeign = opaqueForeignTokens(foreign);
+  const isScopeToken = scopeTokenTest(foreign);
+  const nodeIds = collectNodeIds(input.scenes);
+  const checkVisitIds = (node, nodeId, field, src) => {
+    if (node.kind === "call") {
+      if (VISIT_FNS.has(node.name)) {
+        const arg = node.args[0];
+        if (arg && arg.kind === "string" && !nodeIds.has(arg.value)) {
+          issues.push({ nodeId, field, src, severity: "error", message: `${node.name}(): unknown node id '${arg.value}'` });
+        }
+      }
+      for (const a of node.args) checkVisitIds(a, nodeId, field, src);
+    } else if (node.kind === "binary") {
+      checkVisitIds(node.left, nodeId, field, src);
+      checkVisitIds(node.right, nodeId, field, src);
+    } else if (node.kind === "unary") {
+      checkVisitIds(node.operand, nodeId, field, src);
+    }
+  };
+  const validateElement = (blocks, sceneProps, onEntry, elementId) => {
+    const schema = (0, import_dialect.buildSchema)(input.project, sceneProps, foreign);
+    const check = (nodeId, field, src) => {
+      let ast;
+      try {
+        ast = (0, import_expr.parse)(src, dialect);
+      } catch (e) {
+        issues.push({ nodeId, field, src, severity: "error", message: e instanceof Error ? e.message : String(e) });
+        return;
+      }
+      for (const iss of (0, import_expr.validateExpr)(ast, schema, dialect)) {
+        issues.push({ nodeId, field, src, severity: iss.severity, message: iss.message });
+      }
+      checkVisitIds(ast, nodeId, field, src);
+    };
+    const checkTarget = (nodeId, field, target) => {
+      if (!TARGET_REF.test(target)) {
+        issues.push({
+          nodeId,
+          field,
+          src: target,
+          severity: "error",
+          message: `set target must be a property reference (@name / @scope.name), got '${target}'`
+        });
+        return;
+      }
+      if (readOnly.has(refKey(target))) {
+        issues.push({
+          nodeId,
+          field,
+          src: target,
+          severity: "error",
+          message: `cannot assign to read-only property '${target}'`
+        });
+        return;
+      }
+      const { scope, name } = (0, import_dialect.splitRef)(target, isScopeToken);
+      if (opaqueForeign.has(scope)) return;
+      if (!schema.properties.get(scope)?.has(name)) {
+        issues.push({
+          nodeId,
+          field,
+          src: target,
+          severity: "error",
+          message: `set target '${target}' is not a declared property`
+        });
+      }
+    };
+    const checkEffects = (nodeId, list, label) => {
+      for (const e of list ?? []) {
+        checkTarget(nodeId, `${label}.set`, e.target);
+        check(nodeId, `${label}.set`, e.value);
+      }
+    };
+    checkEffects(elementId, onEntry, "onEntry");
+    for (const block of blocks) {
+      (0, import_model.walkNodes)(block.children, (node) => {
+        if (node.condition) check(node.id, "condition", node.condition);
+        if (node.type === "snippet") {
+          checkEffects(node.id, node.onEnter, "onEnter");
+          checkEffects(node.id, node.onExit, "onExit");
+        }
+      });
+    }
+  };
+  for (const scene of input.scenes) validateElement(scene.blocks, scene.sceneProps, scene.onEntry, scene.id);
+  return issues;
+}
+function validateInterpolation(input, options = {}) {
+  const issues = [];
+  const voiced = input.project.voiced ?? false;
+  const tables = (input.locales ?? []).map((l) => ({ locale: l.locale, strings: l.strings }));
+  const defaultLocale = input.project.locales.default;
+  const opaqueForeign = opaqueForeignTokens(options.foreignScopes);
+  const isScopeToken = scopeTokenTest(options.foreignScopes);
+  for (const scene of input.scenes) {
+    const schema = (0, import_dialect.buildSchema)(input.project, scene.sceneProps, options.foreignScopes);
+    const known = (ref) => {
+      const { scope, name } = (0, import_dialect.splitRef)(ref, isScopeToken);
+      if (opaqueForeign.has(scope)) return true;
+      return schema.properties.get(scope)?.has(name) ?? false;
+    };
+    const checkString = (nodeId, id, voicedLine) => {
+      for (const t of tables) {
+        const text = t.strings[id];
+        if (text === void 0) continue;
+        const field = `text[${t.locale}]`;
+        for (const slot of (0, import_dialect.extractSlots)(text)) {
+          if (voicedLine) {
+            issues.push({
+              nodeId,
+              field,
+              src: slot.raw,
+              severity: "error",
+              message: `voiced line beats cannot contain interpolation ${slot.raw} (spec \xA716)`
+            });
+            continue;
+          }
+          if (!slot.ref) {
+            issues.push({
+              nodeId,
+              field,
+              src: slot.raw,
+              severity: "error",
+              message: `interpolation slot holds a bare property reference only, got '${slot.inner}' (spec \xA716)`
+            });
+            continue;
+          }
+          if (!known(slot.ref)) {
+            issues.push({
+              nodeId,
+              field,
+              src: slot.raw,
+              severity: "error",
+              message: `unknown property in interpolation slot: '${slot.ref}'`
+            });
+          }
+        }
+      }
+    };
+    const checkBeat = (beat) => {
+      if (beat.kind === "gameEvent") return;
+      checkString(beat.id, beat.id, beat.kind === "line" && voiced);
+    };
+    for (const block of scene.blocks) {
+      (0, import_model.walkNodes)(block.children, (node) => {
+        if (node.type === "snippet") {
+          for (const beat of node.beats ?? []) checkBeat(beat);
+          return;
+        }
+        if (node.prompt) checkBeat(node.prompt);
+      });
+    }
+  }
+  return issues;
+}
+var VISIT_FNS = /* @__PURE__ */ new Set(["visits", "seen", "patter_visits", "patter_seen"]);
+var TARGET_REF = /^@[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)?$/;
+function collectNodeIds(scenes) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const scene of scenes) {
+    ids.add(scene.id);
+    for (const block of scene.blocks) {
+      ids.add(block.id);
+      (0, import_model.walkNodes)(block.children, (n) => ids.add(n.id));
+    }
+  }
+  return ids;
+}
+function opaqueForeignTokens(spec) {
+  return new Set((spec?.scopes ?? []).filter((s) => !s.declarations?.length).map((s) => s.token));
+}
+function scopeTokenTest(spec) {
+  const foreign = new Set((spec?.scopes ?? []).map((s) => s.token));
+  return (t) => t === "patter" || t === "scene" || foreign.has(t);
+}
+function refKey(ref) {
+  return ref.replace(/^@/, "").toLowerCase();
+}
+function readOnlyForeignTargets(spec) {
+  const out = /* @__PURE__ */ new Set();
+  for (const scope of spec?.scopes ?? []) {
+    const scopeWritable = scope.writable ?? true;
+    for (const d of scope.declarations ?? []) {
+      const writable = d.writable ?? scopeWritable;
+      if (!writable) out.add(`${scope.token}.${d.name}`.toLowerCase());
+    }
+  }
+  return out;
+}
+
+// src/index.ts
+var import_dialect3 = require("@patterkit/dialect");
+
+// src/export.ts
+var import_core = require("@patterkit/core");
+var import_dialect2 = require("@patterkit/dialect");
+function compileEffect(e, foreign) {
+  return { kind: "set", target: e.target, value: compileExpression(e.value, foreign) };
+}
+function compileNode(node, foreign) {
+  if (node.type === "group") {
+    return {
+      id: node.id,
+      type: "group",
+      condition: node.condition !== void 0 ? compileExpression(node.condition, foreign) : void 0,
+      selector: node.selector,
+      shared: node.shared,
+      options: node.options,
+      children: node.children.map((c) => compileNode(c, foreign)),
+      gameData: node.gameData,
+      tags: node.tags,
+      // author tags (#215), accumulated at runtime
+      prompt: node.prompt,
+      // option-position only (spec §5)
+      secretUntilEligible: node.secretUntilEligible,
+      sticky: node.sticky,
+      fallback: node.fallback
+    };
+  }
+  return {
+    id: node.id,
+    type: "snippet",
+    condition: node.condition !== void 0 ? compileExpression(node.condition, foreign) : void 0,
+    beats: node.beats,
+    onEnter: node.onEnter?.map((e) => compileEffect(e, foreign)),
+    onExit: node.onExit?.map((e) => compileEffect(e, foreign)),
+    gameData: node.gameData,
+    tags: node.tags,
+    // author tags (#215)
+    jump: node.jump,
+    secretUntilEligible: node.secretUntilEligible,
+    sticky: node.sticky,
+    fallback: node.fallback
+  };
+}
+function compileBlock(block, foreign) {
+  return {
+    id: block.id,
+    type: "block",
+    name: block.name,
+    ...block.gameId ? { gameId: block.gameId } : {},
+    // host-facing address; runtime falls back to the name slug
+    children: block.children.map((c) => compileNode(c, foreign)),
+    gameData: block.gameData,
+    tags: block.tags
+    // author tags (#215)
+  };
+}
+function compileScene(scene, foreign) {
+  return {
+    id: scene.id,
+    type: "scene",
+    name: scene.name,
+    ...scene.gameId ? { gameId: scene.gameId } : {},
+    // host-facing address; runtime falls back to the name slug
+    gameData: scene.gameData,
+    tags: scene.tags,
+    // author tags (#215)
+    onEntry: scene.onEntry?.map((e) => compileEffect(e, foreign)),
+    sceneProps: scene.sceneProps,
+    blocks: scene.blocks.map((b) => compileBlock(b, foreign))
+  };
+}
+function exportBundle(input) {
+  const { project, scenes, locales = [], includeLocales } = input;
+  const foreignScopes = input.foreignScopes ?? (0, import_dialect2.hostScopesToSpec)(project.scopeRegistry);
+  const scenesOut = {};
+  for (const scene of scenes) scenesOut[scene.id] = compileScene(scene, foreignScopes);
+  const strings = {};
+  for (const loc of locales) {
+    if (includeLocales && !includeLocales.includes(loc.locale)) continue;
+    const table = strings[loc.locale] ??= {};
+    for (const [key, text] of Object.entries(loc.strings)) {
+      if (key in table && table[key] !== text) {
+        throw new Error(`duplicate string key '${key}' in locale '${loc.locale}' with differing text`);
+      }
+      table[key] = text;
+    }
+  }
+  return {
+    schema: "patter/bundle@0",
+    content: {
+      project: project.project.id,
+      // Binds saves to the content they were taken against, and gates bundle
+      // staleness (schema §10.5). A stable strict-JSON fingerprint - independent
+      // of the source-form trailing-comma policy.
+      // `scopeRegistry` is folded in only when present, so projects without host scopes keep their exact
+      // prior hash (no ripple to existing bundles / the conformance corpus).
+      hash: (0, import_core.hash32)((0, import_core.canonicalStringify)({
+        scenes: scenesOut,
+        strings,
+        properties: project.properties ?? [],
+        ...foreignScopes ? { scopeRegistry: foreignScopes } : {}
+      }, { trailingComma: false })),
+      // Structure-only fingerprint (live bundle refresh): the same hash with the string tables left
+      // out. Same structureHash + a different hash = a text-only edit, safe to swap in place with
+      // `engine.replaceStrings()`; a changed structureHash needs the full save/load hot swap.
+      structureHash: (0, import_core.hash32)((0, import_core.canonicalStringify)({
+        scenes: scenesOut,
+        properties: project.properties ?? [],
+        ...foreignScopes ? { scopeRegistry: foreignScopes } : {}
+      }, { trailingComma: false }))
+    },
+    voiced: project.voiced ?? false,
+    locales: { default: project.locales.default, included: Object.keys(strings) },
+    cast: project.cast?.map(({ notes, ...c }) => c),
+    // strip authoring-only notes from the runtime
+    properties: project.properties,
+    scopeRegistry: project.scopeRegistry,
+    gameDataFields: project.gameDataFields,
+    // Closed-caption delimiters ride along only when the project pins a non-default pair (#214); the
+    // runtime falls back to `[` / `]` when absent, so default projects keep their exact prior bundle.
+    ...project.closedCaptions ? { closedCaptions: project.closedCaptions } : {},
+    scenes: scenesOut,
+    strings
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  compileExpression,
+  exportBundle,
+  hostScopesToSpec,
+  validateConditions,
+  validateInterpolation
+});

package/dist/index.d.cts

@@ -0,0 +1,74 @@
+import { ScopeRegistrySpec } from '@wildwinter/scoperegistry';
+import { Expression, ProjectFile, Scene, LocaleFile, Bundle } from '@patterkit/model';
+export { hostScopesToSpec } from '@patterkit/dialect';
+
+/**
+ * Compile a condition/effect `src` string to the bundle `{ src, ast }` envelope.
+ * Pass `foreign` to allow references into another owner's imported scopes (e.g.
+ * a storylet's `@world`); the parser needs every referenced scope registered.
+ */
+declare function compileExpression(src: string, foreign?: ScopeRegistrySpec): Expression;
+interface ConditionIssue {
+    /** Id of the node whose expression has the issue. */
+    nodeId: string;
+    /** Where on the node: "condition" / "onEnter.set" / "onExit.set" / ... */
+    field: string;
+    /** The offending source expression. */
+    src: string;
+    message: string;
+    /** "error" blocks a clean build; "warning" is advisory. Condition issues carry the expr
+     *  validator's own severity; the compiler's own structural pushes are always errors. */
+    severity: "error" | "warning";
+}
+/**
+ * Parse + validate every condition and effect expression in a project's scenes.
+ * Uses the Patter dialect and a per-scene ExpressionSchema (global properties +
+ * the scene's scene-local properties). Pass `options.foreignScopes` (another
+ * owner's `scopeRegistrySpec`) to permit + validate references into imported
+ * scopes; writes (`set` effects) that target a read-only foreign property are
+ * reported. Returns an empty array when all are valid.
+ */
+declare function validateConditions(input: {
+    project: ProjectFile;
+    scenes: Scene[];
+}, options?: {
+    foreignScopes?: ScopeRegistrySpec;
+}): ConditionIssue[];
+/**
+ * Validate inline `{@ref}` interpolation slots in a project's localised strings
+ * (spec §16). Enforces the VO-safety guarantee - **a voiced project rejects any
+ * slot in a line beat** - plus the committed surface (a slot holds a bare
+ * property reference only) and that the referenced property is declared. Text
+ * beats and CHOICE LABELS always interpolate (labels are on-screen text even in
+ * voiced projects); game-event beats carry no localised content. Also flags an
+ * option `prompt` id with no string in the default locale (the runtime would
+ * display the raw id). Pass `options.foreignScopes` so slots into imported
+ * scopes (`{@world.x}`) resolve instead of reporting unknown. Returns an empty
+ * array when all are valid.
+ */
+declare function validateInterpolation(input: {
+    project: ProjectFile;
+    scenes: Scene[];
+    locales?: LocaleFile[];
+}, options?: {
+    foreignScopes?: ScopeRegistrySpec;
+}): ConditionIssue[];
+
+interface ExportInput {
+    project: ProjectFile;
+    scenes: Scene[];
+    /** Locale files to assemble (one or more per locale). */
+    locales?: LocaleFile[];
+    /** Assemble only these locales (schema §10.1 "selected locales"); default: all provided. */
+    includeLocales?: string[];
+    /**
+     * Another owner's `scopeRegistrySpec` (e.g. a storylet's), to permit compiling
+     * references into its imported scopes (`@world.x`). The parser rejects an
+     * unregistered scope token, so cross-engine refs need this.
+     */
+    foreignScopes?: ScopeRegistrySpec;
+}
+/** Compile a project's source into the runtime bundle. */
+declare function exportBundle(input: ExportInput): Bundle;
+
+export { type ConditionIssue, type ExportInput, compileExpression, exportBundle, validateConditions, validateInterpolation };

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import { ScopeRegistrySpec } from '@wildwinter/scoperegistry';
+import { Expression, ProjectFile, Scene, LocaleFile, Bundle } from '@patterkit/model';
+export { hostScopesToSpec } from '@patterkit/dialect';
+
+/**
+ * Compile a condition/effect `src` string to the bundle `{ src, ast }` envelope.
+ * Pass `foreign` to allow references into another owner's imported scopes (e.g.
+ * a storylet's `@world`); the parser needs every referenced scope registered.
+ */
+declare function compileExpression(src: string, foreign?: ScopeRegistrySpec): Expression;
+interface ConditionIssue {
+    /** Id of the node whose expression has the issue. */
+    nodeId: string;
+    /** Where on the node: "condition" / "onEnter.set" / "onExit.set" / ... */
+    field: string;
+    /** The offending source expression. */
+    src: string;
+    message: string;
+    /** "error" blocks a clean build; "warning" is advisory. Condition issues carry the expr
+     *  validator's own severity; the compiler's own structural pushes are always errors. */
+    severity: "error" | "warning";
+}
+/**
+ * Parse + validate every condition and effect expression in a project's scenes.
+ * Uses the Patter dialect and a per-scene ExpressionSchema (global properties +
+ * the scene's scene-local properties). Pass `options.foreignScopes` (another
+ * owner's `scopeRegistrySpec`) to permit + validate references into imported
+ * scopes; writes (`set` effects) that target a read-only foreign property are
+ * reported. Returns an empty array when all are valid.
+ */
+declare function validateConditions(input: {
+    project: ProjectFile;
+    scenes: Scene[];
+}, options?: {
+    foreignScopes?: ScopeRegistrySpec;
+}): ConditionIssue[];
+/**
+ * Validate inline `{@ref}` interpolation slots in a project's localised strings
+ * (spec §16). Enforces the VO-safety guarantee - **a voiced project rejects any
+ * slot in a line beat** - plus the committed surface (a slot holds a bare
+ * property reference only) and that the referenced property is declared. Text
+ * beats and CHOICE LABELS always interpolate (labels are on-screen text even in
+ * voiced projects); game-event beats carry no localised content. Also flags an
+ * option `prompt` id with no string in the default locale (the runtime would
+ * display the raw id). Pass `options.foreignScopes` so slots into imported
+ * scopes (`{@world.x}`) resolve instead of reporting unknown. Returns an empty
+ * array when all are valid.
+ */
+declare function validateInterpolation(input: {
+    project: ProjectFile;
+    scenes: Scene[];
+    locales?: LocaleFile[];
+}, options?: {
+    foreignScopes?: ScopeRegistrySpec;
+}): ConditionIssue[];
+
+interface ExportInput {
+    project: ProjectFile;
+    scenes: Scene[];
+    /** Locale files to assemble (one or more per locale). */
+    locales?: LocaleFile[];
+    /** Assemble only these locales (schema §10.1 "selected locales"); default: all provided. */
+    includeLocales?: string[];
+    /**
+     * Another owner's `scopeRegistrySpec` (e.g. a storylet's), to permit compiling
+     * references into its imported scopes (`@world.x`). The parser rejects an
+     * unregistered scope token, so cross-engine refs need this.
+     */
+    foreignScopes?: ScopeRegistrySpec;
+}
+/** Compile a project's source into the runtime bundle. */
+declare function exportBundle(input: ExportInput): Bundle;
+
+export { type ConditionIssue, type ExportInput, compileExpression, exportBundle, validateConditions, validateInterpolation };

package/dist/index.js

@@ -0,0 +1,336 @@
+// src/expressions.ts
+import { compile, parse, validateExpr } from "@wildwinter/expr";
+import { dialectWithForeignScopes, buildSchema, extractSlots, splitRef } from "@patterkit/dialect";
+import { walkNodes } from "@patterkit/model";
+function compileExpression(src, foreign) {
+  return compile(src, dialectWithForeignScopes(foreign));
+}
+function validateConditions(input, options = {}) {
+  const issues = [];
+  const foreign = options.foreignScopes;
+  const dialect = dialectWithForeignScopes(foreign);
+  const readOnly = readOnlyForeignTargets(foreign);
+  const opaqueForeign = opaqueForeignTokens(foreign);
+  const isScopeToken = scopeTokenTest(foreign);
+  const nodeIds = collectNodeIds(input.scenes);
+  const checkVisitIds = (node, nodeId, field, src) => {
+    if (node.kind === "call") {
+      if (VISIT_FNS.has(node.name)) {
+        const arg = node.args[0];
+        if (arg && arg.kind === "string" && !nodeIds.has(arg.value)) {
+          issues.push({ nodeId, field, src, severity: "error", message: `${node.name}(): unknown node id '${arg.value}'` });
+        }
+      }
+      for (const a of node.args) checkVisitIds(a, nodeId, field, src);
+    } else if (node.kind === "binary") {
+      checkVisitIds(node.left, nodeId, field, src);
+      checkVisitIds(node.right, nodeId, field, src);
+    } else if (node.kind === "unary") {
+      checkVisitIds(node.operand, nodeId, field, src);
+    }
+  };
+  const validateElement = (blocks, sceneProps, onEntry, elementId) => {
+    const schema = buildSchema(input.project, sceneProps, foreign);
+    const check = (nodeId, field, src) => {
+      let ast;
+      try {
+        ast = parse(src, dialect);
+      } catch (e) {
+        issues.push({ nodeId, field, src, severity: "error", message: e instanceof Error ? e.message : String(e) });
+        return;
+      }
+      for (const iss of validateExpr(ast, schema, dialect)) {
+        issues.push({ nodeId, field, src, severity: iss.severity, message: iss.message });
+      }
+      checkVisitIds(ast, nodeId, field, src);
+    };
+    const checkTarget = (nodeId, field, target) => {
+      if (!TARGET_REF.test(target)) {
+        issues.push({
+          nodeId,
+          field,
+          src: target,
+          severity: "error",
+          message: `set target must be a property reference (@name / @scope.name), got '${target}'`
+        });
+        return;
+      }
+      if (readOnly.has(refKey(target))) {
+        issues.push({
+          nodeId,
+          field,
+          src: target,
+          severity: "error",
+          message: `cannot assign to read-only property '${target}'`
+        });
+        return;
+      }
+      const { scope, name } = splitRef(target, isScopeToken);
+      if (opaqueForeign.has(scope)) return;
+      if (!schema.properties.get(scope)?.has(name)) {
+        issues.push({
+          nodeId,
+          field,
+          src: target,
+          severity: "error",
+          message: `set target '${target}' is not a declared property`
+        });
+      }
+    };
+    const checkEffects = (nodeId, list, label) => {
+      for (const e of list ?? []) {
+        checkTarget(nodeId, `${label}.set`, e.target);
+        check(nodeId, `${label}.set`, e.value);
+      }
+    };
+    checkEffects(elementId, onEntry, "onEntry");
+    for (const block of blocks) {
+      walkNodes(block.children, (node) => {
+        if (node.condition) check(node.id, "condition", node.condition);
+        if (node.type === "snippet") {
+          checkEffects(node.id, node.onEnter, "onEnter");
+          checkEffects(node.id, node.onExit, "onExit");
+        }
+      });
+    }
+  };
+  for (const scene of input.scenes) validateElement(scene.blocks, scene.sceneProps, scene.onEntry, scene.id);
+  return issues;
+}
+function validateInterpolation(input, options = {}) {
+  const issues = [];
+  const voiced = input.project.voiced ?? false;
+  const tables = (input.locales ?? []).map((l) => ({ locale: l.locale, strings: l.strings }));
+  const defaultLocale = input.project.locales.default;
+  const opaqueForeign = opaqueForeignTokens(options.foreignScopes);
+  const isScopeToken = scopeTokenTest(options.foreignScopes);
+  for (const scene of input.scenes) {
+    const schema = buildSchema(input.project, scene.sceneProps, options.foreignScopes);
+    const known = (ref) => {
+      const { scope, name } = splitRef(ref, isScopeToken);
+      if (opaqueForeign.has(scope)) return true;
+      return schema.properties.get(scope)?.has(name) ?? false;
+    };
+    const checkString = (nodeId, id, voicedLine) => {
+      for (const t of tables) {
+        const text = t.strings[id];
+        if (text === void 0) continue;
+        const field = `text[${t.locale}]`;
+        for (const slot of extractSlots(text)) {
+          if (voicedLine) {
+            issues.push({
+              nodeId,
+              field,
+              src: slot.raw,
+              severity: "error",
+              message: `voiced line beats cannot contain interpolation ${slot.raw} (spec \xA716)`
+            });
+            continue;
+          }
+          if (!slot.ref) {
+            issues.push({
+              nodeId,
+              field,
+              src: slot.raw,
+              severity: "error",
+              message: `interpolation slot holds a bare property reference only, got '${slot.inner}' (spec \xA716)`
+            });
+            continue;
+          }
+          if (!known(slot.ref)) {
+            issues.push({
+              nodeId,
+              field,
+              src: slot.raw,
+              severity: "error",
+              message: `unknown property in interpolation slot: '${slot.ref}'`
+            });
+          }
+        }
+      }
+    };
+    const checkBeat = (beat) => {
+      if (beat.kind === "gameEvent") return;
+      checkString(beat.id, beat.id, beat.kind === "line" && voiced);
+    };
+    for (const block of scene.blocks) {
+      walkNodes(block.children, (node) => {
+        if (node.type === "snippet") {
+          for (const beat of node.beats ?? []) checkBeat(beat);
+          return;
+        }
+        if (node.prompt) checkBeat(node.prompt);
+      });
+    }
+  }
+  return issues;
+}
+var VISIT_FNS = /* @__PURE__ */ new Set(["visits", "seen", "patter_visits", "patter_seen"]);
+var TARGET_REF = /^@[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)?$/;
+function collectNodeIds(scenes) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const scene of scenes) {
+    ids.add(scene.id);
+    for (const block of scene.blocks) {
+      ids.add(block.id);
+      walkNodes(block.children, (n) => ids.add(n.id));
+    }
+  }
+  return ids;
+}
+function opaqueForeignTokens(spec) {
+  return new Set((spec?.scopes ?? []).filter((s) => !s.declarations?.length).map((s) => s.token));
+}
+function scopeTokenTest(spec) {
+  const foreign = new Set((spec?.scopes ?? []).map((s) => s.token));
+  return (t) => t === "patter" || t === "scene" || foreign.has(t);
+}
+function refKey(ref) {
+  return ref.replace(/^@/, "").toLowerCase();
+}
+function readOnlyForeignTargets(spec) {
+  const out = /* @__PURE__ */ new Set();
+  for (const scope of spec?.scopes ?? []) {
+    const scopeWritable = scope.writable ?? true;
+    for (const d of scope.declarations ?? []) {
+      const writable = d.writable ?? scopeWritable;
+      if (!writable) out.add(`${scope.token}.${d.name}`.toLowerCase());
+    }
+  }
+  return out;
+}
+
+// src/index.ts
+import { hostScopesToSpec as hostScopesToSpec2 } from "@patterkit/dialect";
+
+// src/export.ts
+import { canonicalStringify, hash32 } from "@patterkit/core";
+import { hostScopesToSpec } from "@patterkit/dialect";
+function compileEffect(e, foreign) {
+  return { kind: "set", target: e.target, value: compileExpression(e.value, foreign) };
+}
+function compileNode(node, foreign) {
+  if (node.type === "group") {
+    return {
+      id: node.id,
+      type: "group",
+      condition: node.condition !== void 0 ? compileExpression(node.condition, foreign) : void 0,
+      selector: node.selector,
+      shared: node.shared,
+      options: node.options,
+      children: node.children.map((c) => compileNode(c, foreign)),
+      gameData: node.gameData,
+      tags: node.tags,
+      // author tags (#215), accumulated at runtime
+      prompt: node.prompt,
+      // option-position only (spec §5)
+      secretUntilEligible: node.secretUntilEligible,
+      sticky: node.sticky,
+      fallback: node.fallback
+    };
+  }
+  return {
+    id: node.id,
+    type: "snippet",
+    condition: node.condition !== void 0 ? compileExpression(node.condition, foreign) : void 0,
+    beats: node.beats,
+    onEnter: node.onEnter?.map((e) => compileEffect(e, foreign)),
+    onExit: node.onExit?.map((e) => compileEffect(e, foreign)),
+    gameData: node.gameData,
+    tags: node.tags,
+    // author tags (#215)
+    jump: node.jump,
+    secretUntilEligible: node.secretUntilEligible,
+    sticky: node.sticky,
+    fallback: node.fallback
+  };
+}
+function compileBlock(block, foreign) {
+  return {
+    id: block.id,
+    type: "block",
+    name: block.name,
+    ...block.gameId ? { gameId: block.gameId } : {},
+    // host-facing address; runtime falls back to the name slug
+    children: block.children.map((c) => compileNode(c, foreign)),
+    gameData: block.gameData,
+    tags: block.tags
+    // author tags (#215)
+  };
+}
+function compileScene(scene, foreign) {
+  return {
+    id: scene.id,
+    type: "scene",
+    name: scene.name,
+    ...scene.gameId ? { gameId: scene.gameId } : {},
+    // host-facing address; runtime falls back to the name slug
+    gameData: scene.gameData,
+    tags: scene.tags,
+    // author tags (#215)
+    onEntry: scene.onEntry?.map((e) => compileEffect(e, foreign)),
+    sceneProps: scene.sceneProps,
+    blocks: scene.blocks.map((b) => compileBlock(b, foreign))
+  };
+}
+function exportBundle(input) {
+  const { project, scenes, locales = [], includeLocales } = input;
+  const foreignScopes = input.foreignScopes ?? hostScopesToSpec(project.scopeRegistry);
+  const scenesOut = {};
+  for (const scene of scenes) scenesOut[scene.id] = compileScene(scene, foreignScopes);
+  const strings = {};
+  for (const loc of locales) {
+    if (includeLocales && !includeLocales.includes(loc.locale)) continue;
+    const table = strings[loc.locale] ??= {};
+    for (const [key, text] of Object.entries(loc.strings)) {
+      if (key in table && table[key] !== text) {
+        throw new Error(`duplicate string key '${key}' in locale '${loc.locale}' with differing text`);
+      }
+      table[key] = text;
+    }
+  }
+  return {
+    schema: "patter/bundle@0",
+    content: {
+      project: project.project.id,
+      // Binds saves to the content they were taken against, and gates bundle
+      // staleness (schema §10.5). A stable strict-JSON fingerprint - independent
+      // of the source-form trailing-comma policy.
+      // `scopeRegistry` is folded in only when present, so projects without host scopes keep their exact
+      // prior hash (no ripple to existing bundles / the conformance corpus).
+      hash: hash32(canonicalStringify({
+        scenes: scenesOut,
+        strings,
+        properties: project.properties ?? [],
+        ...foreignScopes ? { scopeRegistry: foreignScopes } : {}
+      }, { trailingComma: false })),
+      // Structure-only fingerprint (live bundle refresh): the same hash with the string tables left
+      // out. Same structureHash + a different hash = a text-only edit, safe to swap in place with
+      // `engine.replaceStrings()`; a changed structureHash needs the full save/load hot swap.
+      structureHash: hash32(canonicalStringify({
+        scenes: scenesOut,
+        properties: project.properties ?? [],
+        ...foreignScopes ? { scopeRegistry: foreignScopes } : {}
+      }, { trailingComma: false }))
+    },
+    voiced: project.voiced ?? false,
+    locales: { default: project.locales.default, included: Object.keys(strings) },
+    cast: project.cast?.map(({ notes, ...c }) => c),
+    // strip authoring-only notes from the runtime
+    properties: project.properties,
+    scopeRegistry: project.scopeRegistry,
+    gameDataFields: project.gameDataFields,
+    // Closed-caption delimiters ride along only when the project pins a non-default pair (#214); the
+    // runtime falls back to `[` / `]` when absent, so default projects keep their exact prior bundle.
+    ...project.closedCaptions ? { closedCaptions: project.closedCaptions } : {},
+    scenes: scenesOut,
+    strings
+  };
+}
+export {
+  compileExpression,
+  exportBundle,
+  hostScopesToSpec2 as hostScopesToSpec,
+  validateConditions,
+  validateInterpolation
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@patterkit/compiler",
+  "version": "0.1.0",
+  "description": "Patter compiler: compile condition/effect expressions, validate them, and export source to the runtime bundle.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ian Thomas",
+  "homepage": "https://patterkit.dev",
+  "repository": { "type": "git", "url": "git+https://github.com/patterkit/patter.git", "directory": "packages/compiler" },
+  "bugs": "https://github.com/patterkit/patter/issues",
+  "publishConfig": { "access": "public" },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean"
+  },
+  "dependencies": {
+    "@patterkit/model": "0.1.0",
+    "@patterkit/core": "0.1.0",
+    "@patterkit/dialect": "0.1.0",
+    "@wildwinter/expr": "^0.3.0",
+    "@wildwinter/scoperegistry": "^0.1.0"
+  }
+}