@patterkit/dialect 0.1.0

package/dist/index.cjs

@@ -0,0 +1,374 @@
+"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, {
+  buildSchema: () => buildSchema,
+  dialectWithForeignScopes: () => dialectWithForeignScopes,
+  extractSlots: () => extractSlots,
+  hostScopesToSpec: () => hostScopesToSpec,
+  interpolate: () => interpolate,
+  patterDialect: () => patterDialect,
+  renderSlotValue: () => renderSlotValue,
+  splitRef: () => splitRef,
+  stripCaptions: () => stripCaptions
+});
+module.exports = __toCommonJS(index_exports);
+var import_expr = require("@wildwinter/expr");
+function host(h) {
+  return h.ctx.host ?? {};
+}
+var patterDialect = {
+  defaultScope: "patter",
+  scopes: [
+    { token: "patter" },
+    // global / world state (graceful-false on miss); bare @name
+    { token: "scene" }
+    // scene-local (per-flow or shared, per the property's `shared` flag)
+  ],
+  functions: {
+    random: {
+      minArgs: 2,
+      maxArgs: 2,
+      returnType: "number",
+      eval(args, h) {
+        if (args.length !== 2) throw new import_expr.EvalError("random(a, b) requires exactly 2 arguments");
+        const next = host(h).nextRandom;
+        if (!next) throw new import_expr.EvalError("random() called without a PRNG in context");
+        const a = h.evaluate(args[0]), b = h.evaluate(args[1]);
+        if (typeof a !== "number" || typeof b !== "number") throw new import_expr.EvalError("random(a, b) arguments must be numbers");
+        if (!Number.isInteger(a) || !Number.isInteger(b)) throw new import_expr.EvalError("random(a, b) arguments must be integers");
+        const lo = Math.min(a, b), hi = Math.max(a, b);
+        return Math.floor(next() * (hi - lo + 1)) + lo;
+      }
+    },
+    check_flags: {
+      minArgs: 1,
+      returnType: "boolean",
+      flagDeltaArgs: true,
+      validate: flagsCall("check_flags"),
+      eval(args, h) {
+        const flags = readFlags(args[0], h, "check_flags");
+        for (let i = 1; i < args.length; i++) {
+          const arg = args[i];
+          if (arg.kind !== "flagdelta") throw new import_expr.EvalError("check_flags() flag args must be +flagName or -flagName");
+          if (arg.sign === "+" ? !flags.includes(arg.name) : flags.includes(arg.name)) return false;
+        }
+        return true;
+      }
+    },
+    set_flags: {
+      minArgs: 1,
+      returnType: "flags",
+      flagDeltaArgs: true,
+      validate: flagsCall("set_flags"),
+      eval(args, h) {
+        const result = [...readFlags(args[0], h, "set_flags")];
+        for (let i = 1; i < args.length; i++) {
+          const arg = args[i];
+          if (arg.kind !== "flagdelta") throw new import_expr.EvalError("set_flags() flag args must be +flagName or -flagName");
+          if (arg.sign === "+") {
+            if (!result.includes(arg.name)) result.push(arg.name);
+          } else {
+            const idx = result.indexOf(arg.name);
+            if (idx >= 0) result.splice(idx, 1);
+          }
+        }
+        return result;
+      }
+    },
+    // Visit counts (spec §7): how many times a scene / block / node has been
+    // *entered*. `visits` / `seen` are this flow's count (flow-local); the
+    // `patter_` variants are the world-wide (@patter / shared) count. The arg is a
+    // node id - the same id a jump targets.
+    visits: {
+      minArgs: 1,
+      maxArgs: 1,
+      returnType: "number",
+      validate: idArg("visits"),
+      eval: (args, h) => host(h).visits?.(nodeId(args, h, "visits")) ?? 0
+    },
+    seen: {
+      minArgs: 1,
+      maxArgs: 1,
+      returnType: "boolean",
+      validate: idArg("seen"),
+      eval: (args, h) => (host(h).visits?.(nodeId(args, h, "seen")) ?? 0) > 0
+    },
+    patter_visits: {
+      minArgs: 1,
+      maxArgs: 1,
+      returnType: "number",
+      validate: idArg("patter_visits"),
+      eval: (args, h) => host(h).patterVisits?.(nodeId(args, h, "patter_visits")) ?? 0
+    },
+    patter_seen: {
+      minArgs: 1,
+      maxArgs: 1,
+      returnType: "boolean",
+      validate: idArg("patter_seen"),
+      eval: (args, h) => (host(h).patterVisits?.(nodeId(args, h, "patter_seen")) ?? 0) > 0
+    }
+  }
+};
+function dialectWithForeignScopes(spec) {
+  if (!spec || spec.scopes.length === 0) return patterDialect;
+  const known = new Set(patterDialect.scopes.map((s) => s.token));
+  const extra = spec.scopes.filter((s) => !known.has(s.token)).map((s) => ({ token: s.token }));
+  if (extra.length === 0) return patterDialect;
+  return { ...patterDialect, scopes: [...patterDialect.scopes, ...extra] };
+}
+function splitRef(ref, isScope) {
+  const parts = ref.replace(/^@/, "").split(".");
+  if (parts.length === 2 && isScope(parts[0])) {
+    return { scope: parts[0], name: parts[1].toLowerCase() };
+  }
+  return { scope: "patter", name: parts.join(".").toLowerCase() };
+}
+function nodeId(args, h, fn) {
+  const v = h.evaluate(args[0]);
+  if (typeof v !== "string") throw new import_expr.EvalError(`${fn}(id) requires a string node id`);
+  return v;
+}
+function idArg(fnName) {
+  return (args, h) => {
+    const first = args[0];
+    if (first && first.kind !== "string") {
+      h.report({
+        path: [...h.path, "args", 0],
+        kind: "wrong-arg-type",
+        severity: "error",
+        message: `${fnName}(id): the argument must be a string id literal (a scene / block / node id)`
+      });
+    }
+  };
+}
+function readFlags(arg, h, fn) {
+  if (!arg) throw new import_expr.EvalError(`${fn}() requires at least one argument (the flags variable)`);
+  const v = h.evaluate(arg);
+  if (Array.isArray(v)) return v;
+  if (v === false || v === null || v === void 0) return [];
+  throw new import_expr.EvalError(`${fn}() first argument must be a flags property`);
+}
+function flagsCall(fnName) {
+  return (args, h) => {
+    if (args.length === 0) return;
+    const first = args[0];
+    if (first.kind !== "scopedvar") {
+      h.report({
+        path: [...h.path, "args", 0],
+        kind: "wrong-arg-type",
+        severity: "error",
+        message: `${fnName}(): first argument must be a flags property reference (@name or @scope.name)`
+      });
+      return;
+    }
+    const meta = h.schema.properties.get(first.scope)?.get(first.name);
+    if (meta && meta.type !== "flags") {
+      const ref = first.scope === h.defaultScope ? first.name : `${first.scope}.${first.name}`;
+      h.report({
+        path: [...h.path, "args", 0],
+        kind: "wrong-arg-type",
+        severity: "error",
+        message: `${fnName}(): '@${ref}' is not a flags property (got ${meta.type})`
+      });
+      return;
+    }
+    for (let i = 1; i < args.length; i++) {
+      const arg = args[i];
+      if (arg.kind !== "flagdelta") {
+        h.report({
+          path: [...h.path, "args", i],
+          kind: "wrong-arg-type",
+          severity: "error",
+          message: `${fnName}(): argument ${i + 1} must be +flagName or -flagName`
+        });
+      } else if (meta?.type === "flags" && meta.enumValues && !meta.enumValues.includes(arg.name)) {
+        h.report({
+          path: [...h.path, "args", i],
+          kind: "unknown-flag-name",
+          severity: "error",
+          message: `${fnName}(): unknown flag '${arg.name}'`,
+          reference: arg.name
+        });
+      }
+    }
+  };
+}
+function hostScopesToSpec(reg) {
+  if (!reg) return void 0;
+  return {
+    version: reg.version,
+    scopes: reg.scopes.map((s) => ({
+      token: s.token,
+      ...s.writable === false ? { writable: false } : {},
+      ...s.declarations ? {
+        declarations: s.declarations.map((d) => ({
+          name: d.name,
+          type: d.type,
+          ...d.values ? { values: d.values } : {},
+          ...d.default !== void 0 ? { default: d.default } : {},
+          ...d.writable === false ? { writable: false } : {}
+        }))
+      } : {}
+    }))
+  };
+}
+function buildSchema(project, sceneProps = [], foreign) {
+  const properties = /* @__PURE__ */ new Map();
+  const put = (scope, decl) => {
+    let m = properties.get(scope);
+    if (!m) {
+      m = /* @__PURE__ */ new Map();
+      properties.set(scope, m);
+    }
+    m.set(decl.name.toLowerCase(), { type: decl.type, enumValues: decl.values });
+  };
+  for (const decl of project.properties ?? []) put("patter", decl);
+  for (const decl of sceneProps) put("scene", decl);
+  const known = new Set(patterDialect.scopes.map((s) => s.token));
+  for (const scope of foreign?.scopes ?? []) {
+    if (known.has(scope.token)) continue;
+    if (!scope.declarations?.length) continue;
+    const m = /* @__PURE__ */ new Map();
+    for (const d of scope.declarations) m.set(d.name.toLowerCase(), { type: d.type, enumValues: d.values });
+    properties.set(scope.token, m);
+  }
+  return { properties };
+}
+var BARE_REF = /^@[A-Za-z0-9_.]+$/;
+function* tokenise(text) {
+  let buf = "";
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (c === "{" && text[i + 1] === "{") {
+      buf += "{";
+      i += 2;
+      continue;
+    }
+    if (c === "}" && text[i + 1] === "}") {
+      buf += "}";
+      i += 2;
+      continue;
+    }
+    if (c === "{") {
+      const close = text.indexOf("}", i + 1);
+      if (close !== -1) {
+        const raw = text.slice(i, close + 1);
+        const inner = text.slice(i + 1, close).trim();
+        if (inner.startsWith("@")) {
+          if (buf) {
+            yield { kind: "text", value: buf };
+            buf = "";
+          }
+          yield { kind: "slot", raw, inner, ref: BARE_REF.test(inner) ? inner : void 0 };
+          i = close + 1;
+          continue;
+        }
+        buf += raw;
+        i = close + 1;
+        continue;
+      }
+    }
+    buf += c;
+    i += 1;
+  }
+  if (buf) yield { kind: "text", value: buf };
+}
+function extractSlots(text) {
+  const out = [];
+  for (const tok of tokenise(text)) {
+    if (tok.kind === "slot") out.push({ raw: tok.raw, inner: tok.inner, ref: tok.ref });
+  }
+  return out;
+}
+function renderSlotValue(v) {
+  if (Array.isArray(v)) return v.join(", ");
+  if (typeof v === "boolean") return v ? "true" : "false";
+  return String(v);
+}
+function isCaptionWs(c) {
+  return c === " " || c === "	" || c === "\n" || c === "\r" || c === "\f" || c === "\v";
+}
+function collapseCaptionWs(s) {
+  let out = "";
+  let pendingSpace = false;
+  for (const c of s) {
+    if (isCaptionWs(c)) {
+      pendingSpace = true;
+      continue;
+    }
+    if (pendingSpace && out.length > 0) out += " ";
+    pendingSpace = false;
+    out += c;
+  }
+  return out;
+}
+function stripCaptions(text, open, close) {
+  if (open.length === 0 || text.indexOf(open) < 0) return text;
+  let out = "";
+  let i = 0;
+  let removed = false;
+  while (i < text.length) {
+    if (text.startsWith(open, i)) {
+      const end = text.indexOf(close, i + open.length);
+      if (end >= 0) {
+        i = end + close.length;
+        removed = true;
+        continue;
+      }
+      out += text.slice(i);
+      break;
+    }
+    out += text[i];
+    i += 1;
+  }
+  return removed ? collapseCaptionWs(out) : text;
+}
+function interpolate(text, resolve) {
+  if (text.indexOf("{") < 0) return text;
+  let out = "";
+  for (const tok of tokenise(text)) {
+    if (tok.kind === "text") {
+      out += tok.value;
+      continue;
+    }
+    if (!tok.ref) {
+      out += tok.raw;
+      continue;
+    }
+    const v = resolve(tok.ref);
+    out += v === void 0 ? "" : renderSlotValue(v);
+  }
+  return out;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildSchema,
+  dialectWithForeignScopes,
+  extractSlots,
+  hostScopesToSpec,
+  interpolate,
+  patterDialect,
+  renderSlotValue,
+  splitRef,
+  stripCaptions
+});

package/dist/index.d.cts

@@ -0,0 +1,84 @@
+import { ExpressionSchema, Dialect, ScalarValue } from '@wildwinter/expr';
+import { ScopeRegistrySpec } from '@wildwinter/scoperegistry';
+import { ProjectFile, PropertyDecl, HostScopeRegistry } from '@patterkit/model';
+
+/** The Patter dialect: scopes patter/scene + built-in functions. */
+declare const patterDialect: Dialect;
+/**
+ * A Patter dialect extended with FOREIGN scope tokens imported from another
+ * owner's `scopeRegistrySpec` (e.g. a storylet's `@world` / `@player` / `@system`).
+ * The parser needs every referenced scope token registered, so authoring tools
+ * that allow cross-engine references must compile/validate with this dialect.
+ * Foreign scopes use the default missing policy (graceful-false). With no spec
+ * (or an empty one) this returns the base `patterDialect` unchanged.
+ */
+declare function dialectWithForeignScopes(spec?: ScopeRegistrySpec): Dialect;
+/**
+ * Split a property ref ("@name" / "@scope.name") into scope + name - THE one
+ * ref grammar, shared by the compiler's validators and the runtime so they
+ * cannot drift. `isScope` says which tokens are scopes in the caller's context
+ * (dialect tokens, plus any foreign tokens); anything else - including a bare
+ * `@name` and a dotted name whose head is not a scope - is a `patter` property.
+ */
+declare function splitRef(ref: string, isScope: (token: string) => boolean): {
+    scope: string;
+    name: string;
+};
+/**
+ * Project the model's host-scope registry (`@world`, ...) onto the
+ * `scopeRegistrySpec` the compiler / validator consume. Patter's property types
+ * are now the same vocabulary as expr's, so this is a structural pass-through
+ * that drops authoring-only fields (`purpose`) and omits unset `writable`;
+ * returns undefined for an absent registry so callers can pass it straight through.
+ */
+declare function hostScopesToSpec(reg?: HostScopeRegistry): ScopeRegistrySpec | undefined;
+/**
+ * Build an ExpressionSchema for validating a scene's expressions: global
+ * properties (`@patter`) plus that scene's scene-local properties (`@scene`),
+ * plus any FOREIGN scopes imported from another owner's `scopeRegistrySpec`.
+ * Scope mapping:
+ *   global (project.properties)   -> @patter
+ *   scene-local (scene.sceneProps)-> @scene
+ *   foreign (spec)                -> its own token (e.g. @world)
+ * The `shared` flag is orthogonal - it does not affect validation (both shared
+ * and not-shared globals are `@patter`; both scene props are `@scene`). A foreign
+ * scope with no declarations is left opaque (omitted) - matching `ScopeRegistry.toSchema`.
+ */
+declare function buildSchema(project: ProjectFile, sceneProps?: PropertyDecl[], foreign?: ScopeRegistrySpec): ExpressionSchema;
+/** A `{ ... }` candidate whose trimmed body starts with `@`. */
+interface Slot {
+    /** The whole matched text including braces, e.g. "{@gold}". */
+    raw: string;
+    /** The trimmed inner body, e.g. "@gold" or (malformed) "@gold + 1". */
+    inner: string;
+    /** The bare property ref ("@gold") when well-formed; undefined if malformed. */
+    ref?: string;
+}
+/**
+ * Find interpolation slots in a localised string. Only `{ ... }` whose trimmed
+ * body begins with `@` is a slot; a slot whose body is not a bare ref is returned
+ * with `ref` undefined (so the validator can flag it - the committed surface is a
+ * bare property reference only). Escaped `{{ }}` braces are not slots.
+ */
+declare function extractSlots(text: string): Slot[];
+/** Render a resolved slot value as display text. */
+declare function renderSlotValue(v: ScalarValue): string;
+/**
+ * Closed-caption stripping (#214): with captions OFF, remove every `open`…`close` span (delimiters
+ * included) from a dialogue line and collapse the surrounding whitespace -
+ * `Oh dear. (sigh) What now?` -> `Oh dear. What now?`. A string that contains NO cue is returned
+ * unchanged (its original whitespace preserved); only a string we actually edited is whitespace-
+ * normalised. `open` and `close` may be the same token (e.g. `*…*`); an unclosed `open` keeps the
+ * remainder verbatim. An empty `open` is a no-op. Identical across every Patterplay runtime - part of
+ * the conformance contract.
+ */
+declare function stripCaptions(text: string, open: string, close: string): string;
+/**
+ * Expand `{@ref}` slots in a string using `resolve` (a property lookup).
+ * Well-formed slots become their rendered value (undefined -> empty string);
+ * malformed slots and non-slot braces are left verbatim; `{{`/`}}` unescape to
+ * literal `{`/`}`.
+ */
+declare function interpolate(text: string, resolve: (ref: string) => ScalarValue | undefined): string;
+
+export { type Slot, buildSchema, dialectWithForeignScopes, extractSlots, hostScopesToSpec, interpolate, patterDialect, renderSlotValue, splitRef, stripCaptions };

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import { ExpressionSchema, Dialect, ScalarValue } from '@wildwinter/expr';
+import { ScopeRegistrySpec } from '@wildwinter/scoperegistry';
+import { ProjectFile, PropertyDecl, HostScopeRegistry } from '@patterkit/model';
+
+/** The Patter dialect: scopes patter/scene + built-in functions. */
+declare const patterDialect: Dialect;
+/**
+ * A Patter dialect extended with FOREIGN scope tokens imported from another
+ * owner's `scopeRegistrySpec` (e.g. a storylet's `@world` / `@player` / `@system`).
+ * The parser needs every referenced scope token registered, so authoring tools
+ * that allow cross-engine references must compile/validate with this dialect.
+ * Foreign scopes use the default missing policy (graceful-false). With no spec
+ * (or an empty one) this returns the base `patterDialect` unchanged.
+ */
+declare function dialectWithForeignScopes(spec?: ScopeRegistrySpec): Dialect;
+/**
+ * Split a property ref ("@name" / "@scope.name") into scope + name - THE one
+ * ref grammar, shared by the compiler's validators and the runtime so they
+ * cannot drift. `isScope` says which tokens are scopes in the caller's context
+ * (dialect tokens, plus any foreign tokens); anything else - including a bare
+ * `@name` and a dotted name whose head is not a scope - is a `patter` property.
+ */
+declare function splitRef(ref: string, isScope: (token: string) => boolean): {
+    scope: string;
+    name: string;
+};
+/**
+ * Project the model's host-scope registry (`@world`, ...) onto the
+ * `scopeRegistrySpec` the compiler / validator consume. Patter's property types
+ * are now the same vocabulary as expr's, so this is a structural pass-through
+ * that drops authoring-only fields (`purpose`) and omits unset `writable`;
+ * returns undefined for an absent registry so callers can pass it straight through.
+ */
+declare function hostScopesToSpec(reg?: HostScopeRegistry): ScopeRegistrySpec | undefined;
+/**
+ * Build an ExpressionSchema for validating a scene's expressions: global
+ * properties (`@patter`) plus that scene's scene-local properties (`@scene`),
+ * plus any FOREIGN scopes imported from another owner's `scopeRegistrySpec`.
+ * Scope mapping:
+ *   global (project.properties)   -> @patter
+ *   scene-local (scene.sceneProps)-> @scene
+ *   foreign (spec)                -> its own token (e.g. @world)
+ * The `shared` flag is orthogonal - it does not affect validation (both shared
+ * and not-shared globals are `@patter`; both scene props are `@scene`). A foreign
+ * scope with no declarations is left opaque (omitted) - matching `ScopeRegistry.toSchema`.
+ */
+declare function buildSchema(project: ProjectFile, sceneProps?: PropertyDecl[], foreign?: ScopeRegistrySpec): ExpressionSchema;
+/** A `{ ... }` candidate whose trimmed body starts with `@`. */
+interface Slot {
+    /** The whole matched text including braces, e.g. "{@gold}". */
+    raw: string;
+    /** The trimmed inner body, e.g. "@gold" or (malformed) "@gold + 1". */
+    inner: string;
+    /** The bare property ref ("@gold") when well-formed; undefined if malformed. */
+    ref?: string;
+}
+/**
+ * Find interpolation slots in a localised string. Only `{ ... }` whose trimmed
+ * body begins with `@` is a slot; a slot whose body is not a bare ref is returned
+ * with `ref` undefined (so the validator can flag it - the committed surface is a
+ * bare property reference only). Escaped `{{ }}` braces are not slots.
+ */
+declare function extractSlots(text: string): Slot[];
+/** Render a resolved slot value as display text. */
+declare function renderSlotValue(v: ScalarValue): string;
+/**
+ * Closed-caption stripping (#214): with captions OFF, remove every `open`…`close` span (delimiters
+ * included) from a dialogue line and collapse the surrounding whitespace -
+ * `Oh dear. (sigh) What now?` -> `Oh dear. What now?`. A string that contains NO cue is returned
+ * unchanged (its original whitespace preserved); only a string we actually edited is whitespace-
+ * normalised. `open` and `close` may be the same token (e.g. `*…*`); an unclosed `open` keeps the
+ * remainder verbatim. An empty `open` is a no-op. Identical across every Patterplay runtime - part of
+ * the conformance contract.
+ */
+declare function stripCaptions(text: string, open: string, close: string): string;
+/**
+ * Expand `{@ref}` slots in a string using `resolve` (a property lookup).
+ * Well-formed slots become their rendered value (undefined -> empty string);
+ * malformed slots and non-slot braces are left verbatim; `{{`/`}}` unescape to
+ * literal `{`/`}`.
+ */
+declare function interpolate(text: string, resolve: (ref: string) => ScalarValue | undefined): string;
+
+export { type Slot, buildSchema, dialectWithForeignScopes, extractSlots, hostScopesToSpec, interpolate, patterDialect, renderSlotValue, splitRef, stripCaptions };

package/dist/index.js

@@ -0,0 +1,341 @@
+// src/index.ts
+import { EvalError } from "@wildwinter/expr";
+function host(h) {
+  return h.ctx.host ?? {};
+}
+var patterDialect = {
+  defaultScope: "patter",
+  scopes: [
+    { token: "patter" },
+    // global / world state (graceful-false on miss); bare @name
+    { token: "scene" }
+    // scene-local (per-flow or shared, per the property's `shared` flag)
+  ],
+  functions: {
+    random: {
+      minArgs: 2,
+      maxArgs: 2,
+      returnType: "number",
+      eval(args, h) {
+        if (args.length !== 2) throw new EvalError("random(a, b) requires exactly 2 arguments");
+        const next = host(h).nextRandom;
+        if (!next) throw new EvalError("random() called without a PRNG in context");
+        const a = h.evaluate(args[0]), b = h.evaluate(args[1]);
+        if (typeof a !== "number" || typeof b !== "number") throw new EvalError("random(a, b) arguments must be numbers");
+        if (!Number.isInteger(a) || !Number.isInteger(b)) throw new EvalError("random(a, b) arguments must be integers");
+        const lo = Math.min(a, b), hi = Math.max(a, b);
+        return Math.floor(next() * (hi - lo + 1)) + lo;
+      }
+    },
+    check_flags: {
+      minArgs: 1,
+      returnType: "boolean",
+      flagDeltaArgs: true,
+      validate: flagsCall("check_flags"),
+      eval(args, h) {
+        const flags = readFlags(args[0], h, "check_flags");
+        for (let i = 1; i < args.length; i++) {
+          const arg = args[i];
+          if (arg.kind !== "flagdelta") throw new EvalError("check_flags() flag args must be +flagName or -flagName");
+          if (arg.sign === "+" ? !flags.includes(arg.name) : flags.includes(arg.name)) return false;
+        }
+        return true;
+      }
+    },
+    set_flags: {
+      minArgs: 1,
+      returnType: "flags",
+      flagDeltaArgs: true,
+      validate: flagsCall("set_flags"),
+      eval(args, h) {
+        const result = [...readFlags(args[0], h, "set_flags")];
+        for (let i = 1; i < args.length; i++) {
+          const arg = args[i];
+          if (arg.kind !== "flagdelta") throw new EvalError("set_flags() flag args must be +flagName or -flagName");
+          if (arg.sign === "+") {
+            if (!result.includes(arg.name)) result.push(arg.name);
+          } else {
+            const idx = result.indexOf(arg.name);
+            if (idx >= 0) result.splice(idx, 1);
+          }
+        }
+        return result;
+      }
+    },
+    // Visit counts (spec §7): how many times a scene / block / node has been
+    // *entered*. `visits` / `seen` are this flow's count (flow-local); the
+    // `patter_` variants are the world-wide (@patter / shared) count. The arg is a
+    // node id - the same id a jump targets.
+    visits: {
+      minArgs: 1,
+      maxArgs: 1,
+      returnType: "number",
+      validate: idArg("visits"),
+      eval: (args, h) => host(h).visits?.(nodeId(args, h, "visits")) ?? 0
+    },
+    seen: {
+      minArgs: 1,
+      maxArgs: 1,
+      returnType: "boolean",
+      validate: idArg("seen"),
+      eval: (args, h) => (host(h).visits?.(nodeId(args, h, "seen")) ?? 0) > 0
+    },
+    patter_visits: {
+      minArgs: 1,
+      maxArgs: 1,
+      returnType: "number",
+      validate: idArg("patter_visits"),
+      eval: (args, h) => host(h).patterVisits?.(nodeId(args, h, "patter_visits")) ?? 0
+    },
+    patter_seen: {
+      minArgs: 1,
+      maxArgs: 1,
+      returnType: "boolean",
+      validate: idArg("patter_seen"),
+      eval: (args, h) => (host(h).patterVisits?.(nodeId(args, h, "patter_seen")) ?? 0) > 0
+    }
+  }
+};
+function dialectWithForeignScopes(spec) {
+  if (!spec || spec.scopes.length === 0) return patterDialect;
+  const known = new Set(patterDialect.scopes.map((s) => s.token));
+  const extra = spec.scopes.filter((s) => !known.has(s.token)).map((s) => ({ token: s.token }));
+  if (extra.length === 0) return patterDialect;
+  return { ...patterDialect, scopes: [...patterDialect.scopes, ...extra] };
+}
+function splitRef(ref, isScope) {
+  const parts = ref.replace(/^@/, "").split(".");
+  if (parts.length === 2 && isScope(parts[0])) {
+    return { scope: parts[0], name: parts[1].toLowerCase() };
+  }
+  return { scope: "patter", name: parts.join(".").toLowerCase() };
+}
+function nodeId(args, h, fn) {
+  const v = h.evaluate(args[0]);
+  if (typeof v !== "string") throw new EvalError(`${fn}(id) requires a string node id`);
+  return v;
+}
+function idArg(fnName) {
+  return (args, h) => {
+    const first = args[0];
+    if (first && first.kind !== "string") {
+      h.report({
+        path: [...h.path, "args", 0],
+        kind: "wrong-arg-type",
+        severity: "error",
+        message: `${fnName}(id): the argument must be a string id literal (a scene / block / node id)`
+      });
+    }
+  };
+}
+function readFlags(arg, h, fn) {
+  if (!arg) throw new EvalError(`${fn}() requires at least one argument (the flags variable)`);
+  const v = h.evaluate(arg);
+  if (Array.isArray(v)) return v;
+  if (v === false || v === null || v === void 0) return [];
+  throw new EvalError(`${fn}() first argument must be a flags property`);
+}
+function flagsCall(fnName) {
+  return (args, h) => {
+    if (args.length === 0) return;
+    const first = args[0];
+    if (first.kind !== "scopedvar") {
+      h.report({
+        path: [...h.path, "args", 0],
+        kind: "wrong-arg-type",
+        severity: "error",
+        message: `${fnName}(): first argument must be a flags property reference (@name or @scope.name)`
+      });
+      return;
+    }
+    const meta = h.schema.properties.get(first.scope)?.get(first.name);
+    if (meta && meta.type !== "flags") {
+      const ref = first.scope === h.defaultScope ? first.name : `${first.scope}.${first.name}`;
+      h.report({
+        path: [...h.path, "args", 0],
+        kind: "wrong-arg-type",
+        severity: "error",
+        message: `${fnName}(): '@${ref}' is not a flags property (got ${meta.type})`
+      });
+      return;
+    }
+    for (let i = 1; i < args.length; i++) {
+      const arg = args[i];
+      if (arg.kind !== "flagdelta") {
+        h.report({
+          path: [...h.path, "args", i],
+          kind: "wrong-arg-type",
+          severity: "error",
+          message: `${fnName}(): argument ${i + 1} must be +flagName or -flagName`
+        });
+      } else if (meta?.type === "flags" && meta.enumValues && !meta.enumValues.includes(arg.name)) {
+        h.report({
+          path: [...h.path, "args", i],
+          kind: "unknown-flag-name",
+          severity: "error",
+          message: `${fnName}(): unknown flag '${arg.name}'`,
+          reference: arg.name
+        });
+      }
+    }
+  };
+}
+function hostScopesToSpec(reg) {
+  if (!reg) return void 0;
+  return {
+    version: reg.version,
+    scopes: reg.scopes.map((s) => ({
+      token: s.token,
+      ...s.writable === false ? { writable: false } : {},
+      ...s.declarations ? {
+        declarations: s.declarations.map((d) => ({
+          name: d.name,
+          type: d.type,
+          ...d.values ? { values: d.values } : {},
+          ...d.default !== void 0 ? { default: d.default } : {},
+          ...d.writable === false ? { writable: false } : {}
+        }))
+      } : {}
+    }))
+  };
+}
+function buildSchema(project, sceneProps = [], foreign) {
+  const properties = /* @__PURE__ */ new Map();
+  const put = (scope, decl) => {
+    let m = properties.get(scope);
+    if (!m) {
+      m = /* @__PURE__ */ new Map();
+      properties.set(scope, m);
+    }
+    m.set(decl.name.toLowerCase(), { type: decl.type, enumValues: decl.values });
+  };
+  for (const decl of project.properties ?? []) put("patter", decl);
+  for (const decl of sceneProps) put("scene", decl);
+  const known = new Set(patterDialect.scopes.map((s) => s.token));
+  for (const scope of foreign?.scopes ?? []) {
+    if (known.has(scope.token)) continue;
+    if (!scope.declarations?.length) continue;
+    const m = /* @__PURE__ */ new Map();
+    for (const d of scope.declarations) m.set(d.name.toLowerCase(), { type: d.type, enumValues: d.values });
+    properties.set(scope.token, m);
+  }
+  return { properties };
+}
+var BARE_REF = /^@[A-Za-z0-9_.]+$/;
+function* tokenise(text) {
+  let buf = "";
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (c === "{" && text[i + 1] === "{") {
+      buf += "{";
+      i += 2;
+      continue;
+    }
+    if (c === "}" && text[i + 1] === "}") {
+      buf += "}";
+      i += 2;
+      continue;
+    }
+    if (c === "{") {
+      const close = text.indexOf("}", i + 1);
+      if (close !== -1) {
+        const raw = text.slice(i, close + 1);
+        const inner = text.slice(i + 1, close).trim();
+        if (inner.startsWith("@")) {
+          if (buf) {
+            yield { kind: "text", value: buf };
+            buf = "";
+          }
+          yield { kind: "slot", raw, inner, ref: BARE_REF.test(inner) ? inner : void 0 };
+          i = close + 1;
+          continue;
+        }
+        buf += raw;
+        i = close + 1;
+        continue;
+      }
+    }
+    buf += c;
+    i += 1;
+  }
+  if (buf) yield { kind: "text", value: buf };
+}
+function extractSlots(text) {
+  const out = [];
+  for (const tok of tokenise(text)) {
+    if (tok.kind === "slot") out.push({ raw: tok.raw, inner: tok.inner, ref: tok.ref });
+  }
+  return out;
+}
+function renderSlotValue(v) {
+  if (Array.isArray(v)) return v.join(", ");
+  if (typeof v === "boolean") return v ? "true" : "false";
+  return String(v);
+}
+function isCaptionWs(c) {
+  return c === " " || c === "	" || c === "\n" || c === "\r" || c === "\f" || c === "\v";
+}
+function collapseCaptionWs(s) {
+  let out = "";
+  let pendingSpace = false;
+  for (const c of s) {
+    if (isCaptionWs(c)) {
+      pendingSpace = true;
+      continue;
+    }
+    if (pendingSpace && out.length > 0) out += " ";
+    pendingSpace = false;
+    out += c;
+  }
+  return out;
+}
+function stripCaptions(text, open, close) {
+  if (open.length === 0 || text.indexOf(open) < 0) return text;
+  let out = "";
+  let i = 0;
+  let removed = false;
+  while (i < text.length) {
+    if (text.startsWith(open, i)) {
+      const end = text.indexOf(close, i + open.length);
+      if (end >= 0) {
+        i = end + close.length;
+        removed = true;
+        continue;
+      }
+      out += text.slice(i);
+      break;
+    }
+    out += text[i];
+    i += 1;
+  }
+  return removed ? collapseCaptionWs(out) : text;
+}
+function interpolate(text, resolve) {
+  if (text.indexOf("{") < 0) return text;
+  let out = "";
+  for (const tok of tokenise(text)) {
+    if (tok.kind === "text") {
+      out += tok.value;
+      continue;
+    }
+    if (!tok.ref) {
+      out += tok.raw;
+      continue;
+    }
+    const v = resolve(tok.ref);
+    out += v === void 0 ? "" : renderSlotValue(v);
+  }
+  return out;
+}
+export {
+  buildSchema,
+  dialectWithForeignScopes,
+  extractSlots,
+  hostScopesToSpec,
+  interpolate,
+  patterDialect,
+  renderSlotValue,
+  splitRef,
+  stripCaptions
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@patterkit/dialect",
+  "version": "0.1.0",
+  "description": "The Patter dialect for @wildwinter/expr (scopes shared/scene/flow, built-in functions), an ExpressionSchema builder from property declarations, and the inline {@ref} interpolation helpers (spec §16).",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ian Thomas",
+  "homepage": "https://patterkit.dev",
+  "repository": { "type": "git", "url": "git+https://github.com/patterkit/patter.git", "directory": "packages/dialect" },
+  "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",
+    "@wildwinter/expr": "^0.3.0",
+    "@wildwinter/scoperegistry": "^0.1.0"
+  }
+}