@patterkit/core 0.1.0

package/dist/index.cjs

@@ -0,0 +1,468 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  canonicalStringify: () => canonicalStringify,
+  effectiveGameId: () => import_model3.effectiveGameId,
+  gameIdify: () => import_model3.gameIdify,
+  hash32: () => hash32,
+  hash4: () => hash4,
+  isValidGameId: () => import_model3.isValidGameId,
+  newId: () => newId,
+  parseSource: () => parseSource,
+  slug: () => slug,
+  validateProject: () => validateProject
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/ids.ts
+var ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+function newId(prefix = "", length = 8) {
+  const limit = 256 - 256 % ALPHABET.length;
+  let token = "";
+  while (token.length < length) {
+    const bytes = new Uint8Array(length * 2);
+    globalThis.crypto.getRandomValues(bytes);
+    for (const b of bytes) {
+      if (b >= limit) continue;
+      token += ALPHABET[b % ALPHABET.length];
+      if (token.length === length) break;
+    }
+  }
+  return prefix ? `${prefix}_${token}` : token;
+}
+
+// src/handle.ts
+function slug(name) {
+  const s = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return s || "_";
+}
+function fnv32(input) {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function hash4(input) {
+  return fnv32(input).toString(36).slice(-4).padStart(4, "0");
+}
+function hash32(input) {
+  return fnv32(input).toString(36).padStart(7, "0");
+}
+
+// src/index.ts
+var import_model3 = require("@patterkit/model");
+
+// src/serialize.ts
+var import_json5 = __toESM(require("json5"), 1);
+function parseSource(text) {
+  const body = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+  return import_json5.default.parse(body);
+}
+function canonicalStringify(value, opts) {
+  return write(value, "", opts?.trailingComma ?? true) + "\n";
+}
+function write(v, indent, tc) {
+  if (v === null || typeof v === "boolean" || typeof v === "number") return JSON.stringify(v);
+  if (typeof v === "string") return JSON.stringify(v);
+  const tail = tc ? "," : "";
+  if (Array.isArray(v)) {
+    if (v.length === 0) return "[]";
+    const next = indent + "  ";
+    const items = v.map((x) => next + write(x, next, tc));
+    return `[
+${items.join(",\n")}${tail}
+${indent}]`;
+  }
+  if (typeof v === "object") {
+    const obj = v;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+    if (keys.length === 0) return "{}";
+    const next = indent + "  ";
+    const entries = keys.map((k) => `${next}${JSON.stringify(k)}: ${write(obj[k], next, tc)}`);
+    return `{
+${entries.join(",\n")}${tail}
+${indent}}`;
+  }
+  return "null";
+}
+
+// src/validate.ts
+var import_model = require("@patterkit/model");
+var import_model2 = require("@patterkit/model");
+function choiceLoopsBack(choice, ...targets) {
+  const back = new Set(targets.filter((s) => typeof s === "string" && s.length > 0));
+  const hits = (n) => n.type === "snippet" ? !!n.jump && back.has(n.jump.to) : (n.children ?? []).some(hits);
+  return (choice.children ?? []).some(hits);
+}
+function isContentlessNode(node) {
+  if (node.type === "snippet") return (node.beats?.length ?? 0) === 0 && !node.jump;
+  if (node.prompt) return false;
+  return Array.isArray(node.children) && node.children.every(isContentlessNode);
+}
+function validateProject(input) {
+  const { project, scenes } = input;
+  const issues = [];
+  const allIds = /* @__PURE__ */ new Map();
+  const addressable = /* @__PURE__ */ new Set();
+  const sceneGameIds = /* @__PURE__ */ new Map();
+  const jumps = [];
+  const castNames = new Set((project.cast ?? []).map((c) => c.name));
+  const checkTags = (tags, where, id) => {
+    for (const t of tags ?? []) {
+      if (typeof t !== "string" || t.length === 0 || /[\s,]/.test(t)) {
+        issues.push({ code: "invalid-tag", message: `${where} has an invalid tag '${String(t)}' (no spaces or commas, and not empty)`, id });
+      }
+    }
+  };
+  const seeId = (id, kind, where) => {
+    if (typeof id !== "string" || id.length === 0) {
+      issues.push({ code: "missing-id", message: `${kind} in ${where} has no id` });
+      return false;
+    }
+    const existing = allIds.get(id);
+    if (existing !== void 0) {
+      issues.push({ code: "duplicate-id", message: `duplicate id '${id}' (${kind} and ${existing})`, id });
+    } else {
+      allIds.set(id, kind);
+    }
+    return true;
+  };
+  validateProjectFile(project, issues);
+  for (const scene of scenes) {
+    seeId(scene.id, "scene", "project");
+    const where = `scene '${scene.id}'`;
+    if (typeof scene.id === "string") addressable.add(scene.id);
+    if (!scene.name?.trim()) {
+      issues.push({ code: "missing-name", message: `${where} has no name`, id: scene.id });
+    }
+    if (scene.gameId && !(0, import_model2.isValidGameId)(scene.gameId)) {
+      issues.push({ code: "invalid-gameid", message: `${where} address '${scene.gameId}' is invalid (lowercase letters, digits, hyphens; no leading/trailing hyphen)`, id: scene.id });
+    }
+    const sgid = (0, import_model2.effectiveGameId)(scene);
+    if (sgid) {
+      const prev = sceneGameIds.get(sgid);
+      if (prev && prev !== scene.id) issues.push({ code: "duplicate-gameid", message: `${where} address '${sgid}' is already used by scene '${prev}'`, id: scene.id });
+      else sceneGameIds.set(sgid, scene.id);
+    }
+    const blockGameIds = /* @__PURE__ */ new Map();
+    checkTags(scene.tags, where, scene.id);
+    checkDecls(scene.sceneProps, `${where} sceneProps`, issues);
+    for (const decl of scene.sceneProps ?? []) {
+      if (decl.temporary && (decl.shared ?? false)) {
+        issues.push({
+          code: "invalid-temporary",
+          message: `${where} property '${decl.name}': 'temporary' cannot be combined with 'shared'`,
+          id: scene.id
+        });
+      }
+    }
+    if (!Array.isArray(scene.blocks)) {
+      issues.push({ code: "malformed-node", message: `${where} has no blocks array`, id: scene.id });
+      continue;
+    }
+    if (scene.blocks.length === 0) {
+      issues.push({ code: "empty-scene", message: `${where} has no blocks`, id: scene.id });
+    }
+    for (const block of scene.blocks) {
+      seeId(block.id, "block", where);
+      checkTags(block.tags, `block '${block.id}'`, block.id);
+      if (typeof block.id === "string") addressable.add(block.id);
+      if (!block.name?.trim()) {
+        issues.push({ code: "missing-name", message: `block '${block.id}' has no name`, id: block.id });
+      }
+      if (block.gameId && !(0, import_model2.isValidGameId)(block.gameId)) {
+        issues.push({ code: "invalid-gameid", message: `block '${block.id}' address '${block.gameId}' is invalid (lowercase letters, digits, hyphens; no leading/trailing hyphen)`, id: block.id });
+      }
+      const bgid = (0, import_model2.effectiveGameId)(block);
+      if (bgid) {
+        const prev = blockGameIds.get(bgid);
+        if (prev && prev !== block.id) issues.push({ code: "duplicate-gameid", message: `block '${block.id}' address '${bgid}' is already used by block '${prev}' in ${where}`, id: block.id });
+        else blockGameIds.set(bgid, block.id);
+      }
+      if (!Array.isArray(block.children)) {
+        issues.push({ code: "malformed-node", message: `block '${block.id}' in ${where} has no children array`, id: block.id });
+        continue;
+      }
+      const inBlockOf = `block '${block.id}'`;
+      const reportEmpty = (nodes) => {
+        for (const n of nodes) {
+          if (isContentlessNode(n)) {
+            if (n.type === "group") {
+              issues.push({ code: "empty-container", message: `group '${n.id}' in ${inBlockOf} is empty`, id: n.id });
+            } else {
+              issues.push({ code: "empty-snippet", message: `snippet '${n.id}' has no beats and no jump`, id: n.id });
+            }
+          } else if (n.type === "group" && Array.isArray(n.children)) {
+            reportEmpty(n.children);
+          }
+        }
+      };
+      if (block.children.length === 0 || block.children.every(isContentlessNode)) {
+        issues.push({ code: "empty-container", message: `block '${block.id}' in ${where} is empty`, id: block.id });
+      } else {
+        reportEmpty(block.children);
+      }
+      (0, import_model.walkNodes)(block.children, (node) => {
+        const inBlock = `block '${block.id}'`;
+        checkTags(node.tags, `${node.type} '${node.id}'`, node.id);
+        if (node.type === "group") {
+          seeId(node.id, "group", inBlock);
+          if (!Array.isArray(node.children)) {
+            issues.push({ code: "malformed-node", message: `group '${node.id}' in ${inBlock} has no children array`, id: node.id });
+          }
+          if (node.selector === "choice") {
+            let fallbacks = 0;
+            let hasSticky = false;
+            for (const opt of node.children ?? []) {
+              if (opt.fallback === true) fallbacks++;
+              if (opt.sticky === true) hasSticky = true;
+              if (opt.type !== "group") continue;
+              const p = opt.prompt;
+              if (!p) {
+                issues.push({ code: "missing-prompt", message: `choice option '${opt.id}' in ${inBlock} has no prompt`, id: opt.id });
+              } else {
+                if (p.kind !== "line" && p.kind !== "text") {
+                  issues.push({ code: "invalid-prompt", message: `choice option '${opt.id}' prompt must be a line or text beat`, id: opt.id });
+                }
+                seeId(p.id, "prompt", `choice option '${opt.id}'`);
+                checkTags(p.tags, `prompt '${p.id}'`, p.id);
+                if (p.kind === "line" && p.character && !castNames.has(p.character)) {
+                  issues.push({ code: "unknown-character", message: `prompt '${p.id}' speaker '${p.character}' is not in the project cast`, id: p.id });
+                }
+              }
+            }
+            if (fallbacks > 1) {
+              issues.push({ code: "multiple-fallbacks", message: `choice '${node.id}' in ${inBlock} has ${fallbacks} fallback options (at most one allowed)`, id: node.id });
+            }
+            const hasUnconditionalEscape = (node.children ?? []).some((opt) => !opt.condition);
+            if ((node.children?.length ?? 0) > 0 && !hasUnconditionalEscape) {
+              issues.push({ code: "choice-can-empty", message: `choice '${node.id}' in ${inBlock} has no unconditional option or fallback - it runs dry (falls through) if every condition fails`, id: node.id });
+            } else if (!hasSticky && fallbacks === 0 && choiceLoopsBack(node, block.id, bgid, scene.id, sgid)) {
+              issues.push({ code: "choice-can-empty", message: `choice '${node.id}' in ${inBlock} can be re-entered but every option is once-only with no fallback - it will run dry`, id: node.id });
+            }
+          }
+          return;
+        }
+        seeId(node.id, "snippet", inBlock);
+        for (const beat of node.beats ?? []) {
+          seeId(beat.id, "beat", `snippet '${node.id}'`);
+          checkTags(beat.tags, `beat '${beat.id}'`, beat.id);
+          if (beat.kind === "line" && beat.character && !castNames.has(beat.character)) {
+            issues.push({
+              code: "unknown-character",
+              message: `beat '${beat.id}' speaker '${beat.character}' is not in the project cast`,
+              id: beat.id
+            });
+          }
+        }
+        if (node.jump) jumps.push({ to: node.jump.to, from: node.id });
+      });
+    }
+  }
+  if (input.authoring) validateAuthoring(input.authoring, project, allIds, issues);
+  for (const d of jumps) {
+    if (d.to === "END") continue;
+    if (!allIds.has(d.to)) {
+      issues.push({ code: "dangling-jump", message: `jump in '${d.from}' targets unknown id '${d.to}'`, id: d.from });
+    } else if (!addressable.has(d.to)) {
+      issues.push({
+        code: "jump-into-non-addressable",
+        message: `jump in '${d.from}' targets '${d.to}' (${allIds.get(d.to)}); jumps may only target a scene, block, or END`,
+        id: d.from
+      });
+    }
+  }
+  return issues;
+}
+function validateProjectFile(project, issues) {
+  checkDecls(project.properties, "project properties", issues);
+  for (const decl of project.properties ?? []) {
+    if (decl.temporary) {
+      issues.push({
+        code: "invalid-temporary",
+        message: `global property '${decl.name}': 'temporary' applies only to scene-local (@scene) properties`
+      });
+    }
+  }
+  if (project.locales && !project.locales.all.includes(project.locales.default)) {
+    issues.push({
+      code: "invalid-locales",
+      message: `default locale '${project.locales.default}' is not in locales.all [${project.locales.all.join(", ")}]`
+    });
+  }
+  const cc = project.closedCaptions;
+  if (cc && (cc.open.length === 0 || cc.close.length === 0)) {
+    issues.push({
+      code: "invalid-captions",
+      message: "closed-caption delimiters must both be non-empty"
+    });
+  }
+  const writing = project.writingStatuses;
+  if (writing) {
+    checkLadderNames(writing.map((s) => s.name), "writingStatuses", issues);
+    for (const marker of ["readyToRecord", "readyToShip"]) {
+      const count = writing.filter((s) => s[marker]).length;
+      if (count !== 1) {
+        issues.push({
+          code: "invalid-status-ladder",
+          message: `writingStatuses must declare '${marker}' on exactly one status (found ${count})`
+        });
+      }
+    }
+  }
+  if (project.recordingStatuses) {
+    checkLadderNames(project.recordingStatuses.map((s) => s.name), "recordingStatuses", issues);
+  }
+  for (const [kind, fields] of Object.entries(project.gameDataFields ?? {})) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const f of fields ?? []) {
+      const key = f.name.trim().toLowerCase();
+      if (!f.name.trim()) issues.push({ code: "invalid-gamedata-field", message: `${kind} gameData field has no name` });
+      else if (seen.has(key)) issues.push({ code: "invalid-gamedata-field", message: `${kind} gameData field '${f.name}' is declared more than once` });
+      else seen.add(key);
+      if (f.type === "enum" && !(f.values && f.values.length)) {
+        issues.push({ code: "invalid-gamedata-field", message: `${kind} gameData field '${f.name}' is an enum but lists no values` });
+      }
+    }
+  }
+}
+function validateAuthoring(files, project, allIds, issues) {
+  const writingLadder = new Set((project.writingStatuses ?? import_model.DEFAULT_WRITING_STATUSES).map((s) => s.name));
+  const recordingLadder = new Set((project.recordingStatuses ?? import_model.DEFAULT_RECORDING_STATUSES).map((s) => s.name));
+  const docClasses = new Set((project.documentationClasses ?? import_model.DEFAULT_DOCUMENTATION_CLASSES).map((c) => c.name));
+  const checkLines = (lines, where) => {
+    if (lines !== void 0 && (typeof lines !== "number" || !Number.isFinite(lines) || lines < 0)) {
+      issues.push({ code: "invalid-status-value", message: `${where}: estimate lines must be a non-negative number, got ${JSON.stringify(lines)}` });
+    }
+  };
+  const est = project.estimating;
+  if (est) {
+    if (est.thresholdStatus !== void 0 && !writingLadder.has(est.thresholdStatus)) {
+      issues.push({ code: "invalid-status-value", message: `estimating: threshold status '${est.thresholdStatus}' is not in the writing ladder` });
+    }
+    checkLines(est.defaultLines, "estimating default");
+    for (const tg of est.tagEstimates ?? []) checkLines(tg.lines, `estimating tag '${tg.tag}'`);
+  }
+  for (const file of files) {
+    for (const [id, value] of Object.entries(file.writing ?? {})) {
+      if (!allIds.has(id)) issues.push({ code: "unknown-status-id", message: `writing status set on unknown id '${id}'`, id });
+      if (!writingLadder.has(value)) {
+        issues.push({ code: "invalid-status-value", message: `writing status '${value}' on '${id}' is not in the project ladder`, id });
+      }
+    }
+    for (const [id, value] of Object.entries(file.recording ?? {})) {
+      if (!allIds.has(id)) issues.push({ code: "unknown-status-id", message: `recording status set on unknown id '${id}'`, id });
+      if (!recordingLadder.has(value)) {
+        issues.push({ code: "invalid-status-value", message: `recording status '${value}' on '${id}' is not in the project ladder`, id });
+      }
+    }
+    for (const id of Object.keys(file.cut ?? {})) {
+      if (!allIds.has(id)) issues.push({ code: "unknown-status-id", message: `cut flag set on unknown id '${id}'`, id });
+    }
+    for (const [id, lines] of Object.entries(file.documentation ?? {})) {
+      if (!allIds.has(id)) issues.push({ code: "unknown-status-id", message: `documentation set on unknown id '${id}'`, id });
+      for (const line of lines) {
+        if (line.type !== void 0 && !docClasses.has(line.type)) {
+          issues.push({ code: "unknown-doc-class", message: `documentation class '${line.type}' on '${id}' is not declared (project documentationClasses)`, id });
+        }
+      }
+    }
+  }
+}
+function checkLadderNames(names, where, issues) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    if (!name?.trim()) {
+      issues.push({ code: "invalid-status-ladder", message: `${where} has an empty status name` });
+      continue;
+    }
+    if (seen.has(name)) {
+      issues.push({ code: "invalid-status-ladder", message: `${where} declares '${name}' more than once` });
+    }
+    seen.add(name);
+  }
+}
+function checkDecls(decls, where, issues) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const decl of decls ?? []) {
+    const name = decl.name?.toLowerCase();
+    if (!name) {
+      issues.push({ code: "invalid-declaration", message: `${where}: a property declaration has no name` });
+      continue;
+    }
+    if (seen.has(name)) {
+      issues.push({ code: "invalid-declaration", message: `${where}: duplicate property '${decl.name}'` });
+    }
+    seen.add(name);
+    if ((decl.type === "enum" || decl.type === "flags") && !decl.values?.length) {
+      issues.push({
+        code: "invalid-declaration",
+        message: `${where}: '${decl.name}' is ${decl.type} but declares no values`
+      });
+    }
+    if (decl.default !== void 0 && !defaultMatchesType(decl.default, decl)) {
+      issues.push({
+        code: "invalid-declaration",
+        message: `${where}: '${decl.name}' default ${JSON.stringify(decl.default)} does not match type '${decl.type}'`
+      });
+    }
+  }
+}
+function defaultMatchesType(value, decl) {
+  switch (decl.type) {
+    case "boolean":
+      return typeof value === "boolean";
+    case "number":
+      return typeof value === "number";
+    case "string":
+      return typeof value === "string";
+    case "enum":
+      return typeof value === "string" && (decl.values?.includes(value) ?? true);
+    case "flags":
+      return Array.isArray(value) && value.every((v) => typeof v === "string" && (decl.values?.includes(v) ?? true));
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  canonicalStringify,
+  effectiveGameId,
+  gameIdify,
+  hash32,
+  hash4,
+  isValidGameId,
+  newId,
+  parseSource,
+  slug,
+  validateProject
+});

package/dist/index.d.cts

@@ -0,0 +1,40 @@
+import { ProjectFile, Scene, AuthoringFile } from '@patterkit/model';
+export { effectiveGameId, gameIdify, isValidGameId } from '@patterkit/model';
+
+/** Generate a new opaque id, e.g. `newId("scn") -> "scn_8f3kq2z1"`. */
+declare function newId(prefix?: string, length?: number): string;
+
+/** Slugify an author name into a filename- / address-safe segment. */
+declare function slug(name: string): string;
+/** Deterministic 4-char base-36 hash of a string (FNV-1a 32-bit). */
+declare function hash4(input: string): string;
+/** Deterministic 7-char base-36 hash of a string (full FNV-1a 32-bit width) - e.g. content hashes. */
+declare function hash32(input: string): string;
+
+/** Parse JSON5 source text (a leading BOM is tolerated). Throws on malformed input. */
+declare function parseSource(text: string): unknown;
+/** Options for {@link canonicalStringify}. */
+interface StringifyOptions {
+    /** Emit a trailing comma after the last item/entry (the canonical SOURCE form).
+     *  Defaults to `true`; the compiled bundle passes `false` to stay strict JSON. */
+    trailingComma?: boolean;
+}
+/** Serialise a value to the canonical form (UTF-8, LF, sorted keys, final newline). */
+declare function canonicalStringify(value: unknown, opts?: StringifyOptions): string;
+
+interface ValidationIssue {
+    code: "duplicate-id" | "missing-id" | "malformed-node" | "missing-name" | "empty-scene" | "empty-snippet" | "empty-container" | "dangling-jump" | "jump-into-non-addressable" | "invalid-gameid" | "duplicate-gameid" | "unknown-character" | "invalid-temporary" | "invalid-declaration" | "invalid-status-ladder" | "invalid-locales" | "invalid-captions" | "missing-prompt" | "invalid-prompt" | "multiple-fallbacks" | "choice-can-empty" | "invalid-status-value" | "unknown-status-id" | "unknown-doc-class" | "invalid-tag" | "invalid-gamedata-field";
+    message: string;
+    /** Id of the offending node/beat, where applicable. */
+    id?: string;
+}
+interface ProjectInput {
+    project: ProjectFile;
+    scenes: Scene[];
+    /** Authoring shards, when loaded - status values are checked against the project ladders (spec section 13). */
+    authoring?: AuthoringFile[];
+}
+/** Validate a project's structural invariants. Returns an empty array when valid. */
+declare function validateProject(input: ProjectInput): ValidationIssue[];
+
+export { type ProjectInput, type StringifyOptions, type ValidationIssue, canonicalStringify, hash32, hash4, newId, parseSource, slug, validateProject };

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { ProjectFile, Scene, AuthoringFile } from '@patterkit/model';
+export { effectiveGameId, gameIdify, isValidGameId } from '@patterkit/model';
+
+/** Generate a new opaque id, e.g. `newId("scn") -> "scn_8f3kq2z1"`. */
+declare function newId(prefix?: string, length?: number): string;
+
+/** Slugify an author name into a filename- / address-safe segment. */
+declare function slug(name: string): string;
+/** Deterministic 4-char base-36 hash of a string (FNV-1a 32-bit). */
+declare function hash4(input: string): string;
+/** Deterministic 7-char base-36 hash of a string (full FNV-1a 32-bit width) - e.g. content hashes. */
+declare function hash32(input: string): string;
+
+/** Parse JSON5 source text (a leading BOM is tolerated). Throws on malformed input. */
+declare function parseSource(text: string): unknown;
+/** Options for {@link canonicalStringify}. */
+interface StringifyOptions {
+    /** Emit a trailing comma after the last item/entry (the canonical SOURCE form).
+     *  Defaults to `true`; the compiled bundle passes `false` to stay strict JSON. */
+    trailingComma?: boolean;
+}
+/** Serialise a value to the canonical form (UTF-8, LF, sorted keys, final newline). */
+declare function canonicalStringify(value: unknown, opts?: StringifyOptions): string;
+
+interface ValidationIssue {
+    code: "duplicate-id" | "missing-id" | "malformed-node" | "missing-name" | "empty-scene" | "empty-snippet" | "empty-container" | "dangling-jump" | "jump-into-non-addressable" | "invalid-gameid" | "duplicate-gameid" | "unknown-character" | "invalid-temporary" | "invalid-declaration" | "invalid-status-ladder" | "invalid-locales" | "invalid-captions" | "missing-prompt" | "invalid-prompt" | "multiple-fallbacks" | "choice-can-empty" | "invalid-status-value" | "unknown-status-id" | "unknown-doc-class" | "invalid-tag" | "invalid-gamedata-field";
+    message: string;
+    /** Id of the offending node/beat, where applicable. */
+    id?: string;
+}
+interface ProjectInput {
+    project: ProjectFile;
+    scenes: Scene[];
+    /** Authoring shards, when loaded - status values are checked against the project ladders (spec section 13). */
+    authoring?: AuthoringFile[];
+}
+/** Validate a project's structural invariants. Returns an empty array when valid. */
+declare function validateProject(input: ProjectInput): ValidationIssue[];
+
+export { type ProjectInput, type StringifyOptions, type ValidationIssue, canonicalStringify, hash32, hash4, newId, parseSource, slug, validateProject };

package/dist/index.js

@@ -0,0 +1,422 @@
+// src/ids.ts
+var ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+function newId(prefix = "", length = 8) {
+  const limit = 256 - 256 % ALPHABET.length;
+  let token = "";
+  while (token.length < length) {
+    const bytes = new Uint8Array(length * 2);
+    globalThis.crypto.getRandomValues(bytes);
+    for (const b of bytes) {
+      if (b >= limit) continue;
+      token += ALPHABET[b % ALPHABET.length];
+      if (token.length === length) break;
+    }
+  }
+  return prefix ? `${prefix}_${token}` : token;
+}
+
+// src/handle.ts
+function slug(name) {
+  const s = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return s || "_";
+}
+function fnv32(input) {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function hash4(input) {
+  return fnv32(input).toString(36).slice(-4).padStart(4, "0");
+}
+function hash32(input) {
+  return fnv32(input).toString(36).padStart(7, "0");
+}
+
+// src/index.ts
+import { gameIdify, isValidGameId as isValidGameId2, effectiveGameId as effectiveGameId2 } from "@patterkit/model";
+
+// src/serialize.ts
+import JSON5 from "json5";
+function parseSource(text) {
+  const body = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+  return JSON5.parse(body);
+}
+function canonicalStringify(value, opts) {
+  return write(value, "", opts?.trailingComma ?? true) + "\n";
+}
+function write(v, indent, tc) {
+  if (v === null || typeof v === "boolean" || typeof v === "number") return JSON.stringify(v);
+  if (typeof v === "string") return JSON.stringify(v);
+  const tail = tc ? "," : "";
+  if (Array.isArray(v)) {
+    if (v.length === 0) return "[]";
+    const next = indent + "  ";
+    const items = v.map((x) => next + write(x, next, tc));
+    return `[
+${items.join(",\n")}${tail}
+${indent}]`;
+  }
+  if (typeof v === "object") {
+    const obj = v;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+    if (keys.length === 0) return "{}";
+    const next = indent + "  ";
+    const entries = keys.map((k) => `${next}${JSON.stringify(k)}: ${write(obj[k], next, tc)}`);
+    return `{
+${entries.join(",\n")}${tail}
+${indent}}`;
+  }
+  return "null";
+}
+
+// src/validate.ts
+import { walkNodes, DEFAULT_WRITING_STATUSES, DEFAULT_RECORDING_STATUSES, DEFAULT_DOCUMENTATION_CLASSES } from "@patterkit/model";
+import { isValidGameId, effectiveGameId } from "@patterkit/model";
+function choiceLoopsBack(choice, ...targets) {
+  const back = new Set(targets.filter((s) => typeof s === "string" && s.length > 0));
+  const hits = (n) => n.type === "snippet" ? !!n.jump && back.has(n.jump.to) : (n.children ?? []).some(hits);
+  return (choice.children ?? []).some(hits);
+}
+function isContentlessNode(node) {
+  if (node.type === "snippet") return (node.beats?.length ?? 0) === 0 && !node.jump;
+  if (node.prompt) return false;
+  return Array.isArray(node.children) && node.children.every(isContentlessNode);
+}
+function validateProject(input) {
+  const { project, scenes } = input;
+  const issues = [];
+  const allIds = /* @__PURE__ */ new Map();
+  const addressable = /* @__PURE__ */ new Set();
+  const sceneGameIds = /* @__PURE__ */ new Map();
+  const jumps = [];
+  const castNames = new Set((project.cast ?? []).map((c) => c.name));
+  const checkTags = (tags, where, id) => {
+    for (const t of tags ?? []) {
+      if (typeof t !== "string" || t.length === 0 || /[\s,]/.test(t)) {
+        issues.push({ code: "invalid-tag", message: `${where} has an invalid tag '${String(t)}' (no spaces or commas, and not empty)`, id });
+      }
+    }
+  };
+  const seeId = (id, kind, where) => {
+    if (typeof id !== "string" || id.length === 0) {
+      issues.push({ code: "missing-id", message: `${kind} in ${where} has no id` });
+      return false;
+    }
+    const existing = allIds.get(id);
+    if (existing !== void 0) {
+      issues.push({ code: "duplicate-id", message: `duplicate id '${id}' (${kind} and ${existing})`, id });
+    } else {
+      allIds.set(id, kind);
+    }
+    return true;
+  };
+  validateProjectFile(project, issues);
+  for (const scene of scenes) {
+    seeId(scene.id, "scene", "project");
+    const where = `scene '${scene.id}'`;
+    if (typeof scene.id === "string") addressable.add(scene.id);
+    if (!scene.name?.trim()) {
+      issues.push({ code: "missing-name", message: `${where} has no name`, id: scene.id });
+    }
+    if (scene.gameId && !isValidGameId(scene.gameId)) {
+      issues.push({ code: "invalid-gameid", message: `${where} address '${scene.gameId}' is invalid (lowercase letters, digits, hyphens; no leading/trailing hyphen)`, id: scene.id });
+    }
+    const sgid = effectiveGameId(scene);
+    if (sgid) {
+      const prev = sceneGameIds.get(sgid);
+      if (prev && prev !== scene.id) issues.push({ code: "duplicate-gameid", message: `${where} address '${sgid}' is already used by scene '${prev}'`, id: scene.id });
+      else sceneGameIds.set(sgid, scene.id);
+    }
+    const blockGameIds = /* @__PURE__ */ new Map();
+    checkTags(scene.tags, where, scene.id);
+    checkDecls(scene.sceneProps, `${where} sceneProps`, issues);
+    for (const decl of scene.sceneProps ?? []) {
+      if (decl.temporary && (decl.shared ?? false)) {
+        issues.push({
+          code: "invalid-temporary",
+          message: `${where} property '${decl.name}': 'temporary' cannot be combined with 'shared'`,
+          id: scene.id
+        });
+      }
+    }
+    if (!Array.isArray(scene.blocks)) {
+      issues.push({ code: "malformed-node", message: `${where} has no blocks array`, id: scene.id });
+      continue;
+    }
+    if (scene.blocks.length === 0) {
+      issues.push({ code: "empty-scene", message: `${where} has no blocks`, id: scene.id });
+    }
+    for (const block of scene.blocks) {
+      seeId(block.id, "block", where);
+      checkTags(block.tags, `block '${block.id}'`, block.id);
+      if (typeof block.id === "string") addressable.add(block.id);
+      if (!block.name?.trim()) {
+        issues.push({ code: "missing-name", message: `block '${block.id}' has no name`, id: block.id });
+      }
+      if (block.gameId && !isValidGameId(block.gameId)) {
+        issues.push({ code: "invalid-gameid", message: `block '${block.id}' address '${block.gameId}' is invalid (lowercase letters, digits, hyphens; no leading/trailing hyphen)`, id: block.id });
+      }
+      const bgid = effectiveGameId(block);
+      if (bgid) {
+        const prev = blockGameIds.get(bgid);
+        if (prev && prev !== block.id) issues.push({ code: "duplicate-gameid", message: `block '${block.id}' address '${bgid}' is already used by block '${prev}' in ${where}`, id: block.id });
+        else blockGameIds.set(bgid, block.id);
+      }
+      if (!Array.isArray(block.children)) {
+        issues.push({ code: "malformed-node", message: `block '${block.id}' in ${where} has no children array`, id: block.id });
+        continue;
+      }
+      const inBlockOf = `block '${block.id}'`;
+      const reportEmpty = (nodes) => {
+        for (const n of nodes) {
+          if (isContentlessNode(n)) {
+            if (n.type === "group") {
+              issues.push({ code: "empty-container", message: `group '${n.id}' in ${inBlockOf} is empty`, id: n.id });
+            } else {
+              issues.push({ code: "empty-snippet", message: `snippet '${n.id}' has no beats and no jump`, id: n.id });
+            }
+          } else if (n.type === "group" && Array.isArray(n.children)) {
+            reportEmpty(n.children);
+          }
+        }
+      };
+      if (block.children.length === 0 || block.children.every(isContentlessNode)) {
+        issues.push({ code: "empty-container", message: `block '${block.id}' in ${where} is empty`, id: block.id });
+      } else {
+        reportEmpty(block.children);
+      }
+      walkNodes(block.children, (node) => {
+        const inBlock = `block '${block.id}'`;
+        checkTags(node.tags, `${node.type} '${node.id}'`, node.id);
+        if (node.type === "group") {
+          seeId(node.id, "group", inBlock);
+          if (!Array.isArray(node.children)) {
+            issues.push({ code: "malformed-node", message: `group '${node.id}' in ${inBlock} has no children array`, id: node.id });
+          }
+          if (node.selector === "choice") {
+            let fallbacks = 0;
+            let hasSticky = false;
+            for (const opt of node.children ?? []) {
+              if (opt.fallback === true) fallbacks++;
+              if (opt.sticky === true) hasSticky = true;
+              if (opt.type !== "group") continue;
+              const p = opt.prompt;
+              if (!p) {
+                issues.push({ code: "missing-prompt", message: `choice option '${opt.id}' in ${inBlock} has no prompt`, id: opt.id });
+              } else {
+                if (p.kind !== "line" && p.kind !== "text") {
+                  issues.push({ code: "invalid-prompt", message: `choice option '${opt.id}' prompt must be a line or text beat`, id: opt.id });
+                }
+                seeId(p.id, "prompt", `choice option '${opt.id}'`);
+                checkTags(p.tags, `prompt '${p.id}'`, p.id);
+                if (p.kind === "line" && p.character && !castNames.has(p.character)) {
+                  issues.push({ code: "unknown-character", message: `prompt '${p.id}' speaker '${p.character}' is not in the project cast`, id: p.id });
+                }
+              }
+            }
+            if (fallbacks > 1) {
+              issues.push({ code: "multiple-fallbacks", message: `choice '${node.id}' in ${inBlock} has ${fallbacks} fallback options (at most one allowed)`, id: node.id });
+            }
+            const hasUnconditionalEscape = (node.children ?? []).some((opt) => !opt.condition);
+            if ((node.children?.length ?? 0) > 0 && !hasUnconditionalEscape) {
+              issues.push({ code: "choice-can-empty", message: `choice '${node.id}' in ${inBlock} has no unconditional option or fallback - it runs dry (falls through) if every condition fails`, id: node.id });
+            } else if (!hasSticky && fallbacks === 0 && choiceLoopsBack(node, block.id, bgid, scene.id, sgid)) {
+              issues.push({ code: "choice-can-empty", message: `choice '${node.id}' in ${inBlock} can be re-entered but every option is once-only with no fallback - it will run dry`, id: node.id });
+            }
+          }
+          return;
+        }
+        seeId(node.id, "snippet", inBlock);
+        for (const beat of node.beats ?? []) {
+          seeId(beat.id, "beat", `snippet '${node.id}'`);
+          checkTags(beat.tags, `beat '${beat.id}'`, beat.id);
+          if (beat.kind === "line" && beat.character && !castNames.has(beat.character)) {
+            issues.push({
+              code: "unknown-character",
+              message: `beat '${beat.id}' speaker '${beat.character}' is not in the project cast`,
+              id: beat.id
+            });
+          }
+        }
+        if (node.jump) jumps.push({ to: node.jump.to, from: node.id });
+      });
+    }
+  }
+  if (input.authoring) validateAuthoring(input.authoring, project, allIds, issues);
+  for (const d of jumps) {
+    if (d.to === "END") continue;
+    if (!allIds.has(d.to)) {
+      issues.push({ code: "dangling-jump", message: `jump in '${d.from}' targets unknown id '${d.to}'`, id: d.from });
+    } else if (!addressable.has(d.to)) {
+      issues.push({
+        code: "jump-into-non-addressable",
+        message: `jump in '${d.from}' targets '${d.to}' (${allIds.get(d.to)}); jumps may only target a scene, block, or END`,
+        id: d.from
+      });
+    }
+  }
+  return issues;
+}
+function validateProjectFile(project, issues) {
+  checkDecls(project.properties, "project properties", issues);
+  for (const decl of project.properties ?? []) {
+    if (decl.temporary) {
+      issues.push({
+        code: "invalid-temporary",
+        message: `global property '${decl.name}': 'temporary' applies only to scene-local (@scene) properties`
+      });
+    }
+  }
+  if (project.locales && !project.locales.all.includes(project.locales.default)) {
+    issues.push({
+      code: "invalid-locales",
+      message: `default locale '${project.locales.default}' is not in locales.all [${project.locales.all.join(", ")}]`
+    });
+  }
+  const cc = project.closedCaptions;
+  if (cc && (cc.open.length === 0 || cc.close.length === 0)) {
+    issues.push({
+      code: "invalid-captions",
+      message: "closed-caption delimiters must both be non-empty"
+    });
+  }
+  const writing = project.writingStatuses;
+  if (writing) {
+    checkLadderNames(writing.map((s) => s.name), "writingStatuses", issues);
+    for (const marker of ["readyToRecord", "readyToShip"]) {
+      const count = writing.filter((s) => s[marker]).length;
+      if (count !== 1) {
+        issues.push({
+          code: "invalid-status-ladder",
+          message: `writingStatuses must declare '${marker}' on exactly one status (found ${count})`
+        });
+      }
+    }
+  }
+  if (project.recordingStatuses) {
+    checkLadderNames(project.recordingStatuses.map((s) => s.name), "recordingStatuses", issues);
+  }
+  for (const [kind, fields] of Object.entries(project.gameDataFields ?? {})) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const f of fields ?? []) {
+      const key = f.name.trim().toLowerCase();
+      if (!f.name.trim()) issues.push({ code: "invalid-gamedata-field", message: `${kind} gameData field has no name` });
+      else if (seen.has(key)) issues.push({ code: "invalid-gamedata-field", message: `${kind} gameData field '${f.name}' is declared more than once` });
+      else seen.add(key);
+      if (f.type === "enum" && !(f.values && f.values.length)) {
+        issues.push({ code: "invalid-gamedata-field", message: `${kind} gameData field '${f.name}' is an enum but lists no values` });
+      }
+    }
+  }
+}
+function validateAuthoring(files, project, allIds, issues) {
+  const writingLadder = new Set((project.writingStatuses ?? DEFAULT_WRITING_STATUSES).map((s) => s.name));
+  const recordingLadder = new Set((project.recordingStatuses ?? DEFAULT_RECORDING_STATUSES).map((s) => s.name));
+  const docClasses = new Set((project.documentationClasses ?? DEFAULT_DOCUMENTATION_CLASSES).map((c) => c.name));
+  const checkLines = (lines, where) => {
+    if (lines !== void 0 && (typeof lines !== "number" || !Number.isFinite(lines) || lines < 0)) {
+      issues.push({ code: "invalid-status-value", message: `${where}: estimate lines must be a non-negative number, got ${JSON.stringify(lines)}` });
+    }
+  };
+  const est = project.estimating;
+  if (est) {
+    if (est.thresholdStatus !== void 0 && !writingLadder.has(est.thresholdStatus)) {
+      issues.push({ code: "invalid-status-value", message: `estimating: threshold status '${est.thresholdStatus}' is not in the writing ladder` });
+    }
+    checkLines(est.defaultLines, "estimating default");
+    for (const tg of est.tagEstimates ?? []) checkLines(tg.lines, `estimating tag '${tg.tag}'`);
+  }
+  for (const file of files) {
+    for (const [id, value] of Object.entries(file.writing ?? {})) {
+      if (!allIds.has(id)) issues.push({ code: "unknown-status-id", message: `writing status set on unknown id '${id}'`, id });
+      if (!writingLadder.has(value)) {
+        issues.push({ code: "invalid-status-value", message: `writing status '${value}' on '${id}' is not in the project ladder`, id });
+      }
+    }
+    for (const [id, value] of Object.entries(file.recording ?? {})) {
+      if (!allIds.has(id)) issues.push({ code: "unknown-status-id", message: `recording status set on unknown id '${id}'`, id });
+      if (!recordingLadder.has(value)) {
+        issues.push({ code: "invalid-status-value", message: `recording status '${value}' on '${id}' is not in the project ladder`, id });
+      }
+    }
+    for (const id of Object.keys(file.cut ?? {})) {
+      if (!allIds.has(id)) issues.push({ code: "unknown-status-id", message: `cut flag set on unknown id '${id}'`, id });
+    }
+    for (const [id, lines] of Object.entries(file.documentation ?? {})) {
+      if (!allIds.has(id)) issues.push({ code: "unknown-status-id", message: `documentation set on unknown id '${id}'`, id });
+      for (const line of lines) {
+        if (line.type !== void 0 && !docClasses.has(line.type)) {
+          issues.push({ code: "unknown-doc-class", message: `documentation class '${line.type}' on '${id}' is not declared (project documentationClasses)`, id });
+        }
+      }
+    }
+  }
+}
+function checkLadderNames(names, where, issues) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    if (!name?.trim()) {
+      issues.push({ code: "invalid-status-ladder", message: `${where} has an empty status name` });
+      continue;
+    }
+    if (seen.has(name)) {
+      issues.push({ code: "invalid-status-ladder", message: `${where} declares '${name}' more than once` });
+    }
+    seen.add(name);
+  }
+}
+function checkDecls(decls, where, issues) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const decl of decls ?? []) {
+    const name = decl.name?.toLowerCase();
+    if (!name) {
+      issues.push({ code: "invalid-declaration", message: `${where}: a property declaration has no name` });
+      continue;
+    }
+    if (seen.has(name)) {
+      issues.push({ code: "invalid-declaration", message: `${where}: duplicate property '${decl.name}'` });
+    }
+    seen.add(name);
+    if ((decl.type === "enum" || decl.type === "flags") && !decl.values?.length) {
+      issues.push({
+        code: "invalid-declaration",
+        message: `${where}: '${decl.name}' is ${decl.type} but declares no values`
+      });
+    }
+    if (decl.default !== void 0 && !defaultMatchesType(decl.default, decl)) {
+      issues.push({
+        code: "invalid-declaration",
+        message: `${where}: '${decl.name}' default ${JSON.stringify(decl.default)} does not match type '${decl.type}'`
+      });
+    }
+  }
+}
+function defaultMatchesType(value, decl) {
+  switch (decl.type) {
+    case "boolean":
+      return typeof value === "boolean";
+    case "number":
+      return typeof value === "number";
+    case "string":
+      return typeof value === "string";
+    case "enum":
+      return typeof value === "string" && (decl.values?.includes(value) ?? true);
+    case "flags":
+      return Array.isArray(value) && value.every((v) => typeof v === "string" && (decl.values?.includes(v) ?? true));
+  }
+}
+export {
+  canonicalStringify,
+  effectiveGameId2 as effectiveGameId,
+  gameIdify,
+  hash32,
+  hash4,
+  isValidGameId2 as isValidGameId,
+  newId,
+  parseSource,
+  slug,
+  validateProject
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@patterkit/core",
+  "version": "0.1.0",
+  "description": "Patter core: stable id generation, readable-handle computation, canonical (de)serialisation, and the structural validator.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ian Thomas",
+  "homepage": "https://patterkit.dev",
+  "repository": { "type": "git", "url": "git+https://github.com/patterkit/patter.git", "directory": "packages/core" },
+  "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",
+    "json5": "^2.2.3"
+  }
+}