@patterkit/model 0.15.0 → 0.16.0

package/dist/index.cjs

@@ -31,10 +31,15 @@ __export(index_exports, {
   DEFAULT_RECORDING_STATUSES: () => DEFAULT_RECORDING_STATUSES,
   DEFAULT_SPEAKER_PATTERN: () => DEFAULT_SPEAKER_PATTERN,
   DEFAULT_WRITING_STATUSES: () => DEFAULT_WRITING_STATUSES,
+  EXTENSIONS_DIR: () => EXTENSIONS_DIR,
+  EXTENSION_SCHEMA: () => EXTENSION_SCHEMA,
+  EXTENSION_SHARD: () => EXTENSION_SHARD,
   FLOW_SCHEMA: () => FLOW_SCHEMA,
   HANDOFF_SCHEMA: () => HANDOFF_SCHEMA,
+  MANIFEST_EXTENSION: () => MANIFEST_EXTENSION,
   PAD_AFTER_MAX: () => PAD_AFTER_MAX,
   PAD_AFTER_MIN: () => PAD_AFTER_MIN,
+  PROJECT_EXTENSION_STEM: () => PROJECT_EXTENSION_STEM,
   PROJECT_LOCALE_SCENE: () => PROJECT_LOCALE_SCENE,
   PROJECT_SCHEMA: () => PROJECT_SCHEMA,
   RERECORD_STATUS: () => RERECORD_STATUS,
@@ -44,6 +49,7 @@ __export(index_exports, {
   SAVE_VERSION: () => SAVE_VERSION,
   SPEAKER_PATTERN_KEY: () => SPEAKER_PATTERN_KEY,
   STRINGS_SCHEMA: () => STRINGS_SCHEMA,
+  UNRESOLVED_KEY: () => UNRESOLVED_KEY,
   castStringKey: () => castStringKey,
   deriveRecordingFolders: () => deriveRecordingFolders,
   effectiveGameId: () => effectiveGameId,
@@ -199,7 +205,7 @@ var DEFAULT_CAPTION_DELIMITERS = { open: "[", close: "]" };
 var DEFAULT_CAPTION_CHARACTER = "SFX";
 var SAVE_SCHEMA = "patter/save@0";
 var SAVE_VERSION = 3;
-var DEFAULT_LAYOUT = { flow: "scenes/", strings: "loc/", authoring: "authoring/" };
+var DEFAULT_LAYOUT = { flow: "scenes/", strings: "loc/", authoring: "authoring/", extensions: "extensions/" };
 function projectLayout(project) {
   return { ...DEFAULT_LAYOUT, ...project.layout };
 }
@@ -207,6 +213,12 @@ var FLOW_SCHEMA = "patter/flow@0";
 var PROJECT_SCHEMA = "patter/project@0";
 var STRINGS_SCHEMA = "patter/strings@0";
 var AUTHORING_SCHEMA = "patter/authoring@0";
+var EXTENSION_SCHEMA = "patter/extension@0";
+var EXTENSION_SHARD = ".patterextension";
+var PROJECT_EXTENSION_STEM = "_project";
+var MANIFEST_EXTENSION = ".extension.json";
+var EXTENSIONS_DIR = "extensions";
+var UNRESOLVED_KEY = "unresolved";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AUTHORING_SCHEMA,
@@ -220,10 +232,15 @@ var AUTHORING_SCHEMA = "patter/authoring@0";
   DEFAULT_RECORDING_STATUSES,
   DEFAULT_SPEAKER_PATTERN,
   DEFAULT_WRITING_STATUSES,
+  EXTENSIONS_DIR,
+  EXTENSION_SCHEMA,
+  EXTENSION_SHARD,
   FLOW_SCHEMA,
   HANDOFF_SCHEMA,
+  MANIFEST_EXTENSION,
   PAD_AFTER_MAX,
   PAD_AFTER_MIN,
+  PROJECT_EXTENSION_STEM,
   PROJECT_LOCALE_SCENE,
   PROJECT_SCHEMA,
   RERECORD_STATUS,
@@ -233,6 +250,7 @@ var AUTHORING_SCHEMA = "patter/authoring@0";
   SAVE_VERSION,
   SPEAKER_PATTERN_KEY,
   STRINGS_SCHEMA,
+  UNRESOLVED_KEY,
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,

package/dist/index.d.cts

@@ -33,6 +33,10 @@ interface LineBeat {
      *  Never negative on a snippet's last line or text beat: the runtime clamps it to zero there. */
     padAfter?: number;
     gameData?: GameData;
+    /** Bundle only: this node's extension values, by extension id, raw as authored (editor-only fields
+     *  stripped). Source keeps them in extension shards (`.patterextension`), never here. Absent when the
+     *  node has none. */
+    extensions?: NodeExtensions;
     /** Author-defined freeform tags (#215): a cross-cutting label layer that travels to the runtime.
      *  At runtime a beat's tags are the UNION of its own and every ancestor's (scene → block → group(s) →
      *  snippet → beat). Each tag is letters/digits/symbols with NO comma and NO whitespace; deduped. */
@@ -53,6 +57,10 @@ interface TextBeat {
      *  Never negative on a snippet's last line or text beat: the runtime clamps it to zero there. */
     padAfter?: number;
     gameData?: GameData;
+    /** Bundle only: this node's extension values, by extension id, raw as authored (editor-only fields
+     *  stripped). Source keeps them in extension shards (`.patterextension`), never here. Absent when the
+     *  node has none. */
+    extensions?: NodeExtensions;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
 }
@@ -66,6 +74,10 @@ interface GameEventBeat {
     id: string;
     kind: "gameEvent";
     gameData?: GameData;
+    /** Bundle only: this node's extension values, by extension id, raw as authored (editor-only fields
+     *  stripped). Source keeps them in extension shards (`.patterextension`), never here. Absent when the
+     *  node has none. */
+    extensions?: NodeExtensions;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
 }
@@ -400,8 +412,10 @@ interface BundleQualifier {
  *  the bundle; this type states the resulting contract for anyone reading a bundle. */
 type BundleCastMember = Omit<CastMember, "notes" | "actor" | "gender">;
 /** A node TYPE that can carry author-defined gameData fields (the gameData schema, project-level).
- *  Beat kinds map straight through: dialogue = `line`, narration = `text`, game event = `gameEvent`. */
-type GameDataNodeKind = "scene" | "block" | "snippet" | "line" | "text" | "gameEvent";
+ *  Beat kinds map straight through: dialogue = `line`, narration = `text`, game event = `gameEvent`.
+ *  `option` is a choice's option: a group that is a direct child of a `choice` group, whose gameData the
+ *  host reads off the option `getChoices` hands it. Any other group's gameData stays undeclared. */
+type GameDataNodeKind = "scene" | "block" | "snippet" | "line" | "text" | "gameEvent" | "option";
 /** The value type of a gameData field: the family's one field-type list, shared with Storylets' card and
  *  outcome fields (patterkit design/family-parity-2026-10.md item 9, patter-qualities.md section 1). Drives
  *  the inspector's editor widget (text / textarea / number / toggle / enum dropdown / flags checklist /
@@ -604,6 +618,7 @@ interface ProjectFile {
         flow?: string;
         strings?: string;
         authoring?: string;
+        extensions?: string;
     };
     /** `bundle`: the compiled `.patterc` output path (relative to the project root,
      *  or absolute); default `../patter-dist/<project-file-stem>.patterc`, beside the project (spec §11).
@@ -648,6 +663,14 @@ interface ProjectFile {
      *  Absent = `DEFAULT_PAD_AFTER`. */
     padAfterDefault?: number;
     gameDataFields?: GameDataFields;
+    /**
+     * The Patter extensions this project takes, by id (ruled 2026-10-18: the project opts in), each pinned to a
+     * version, with its settings (the host fields its claims present, by setting name). The manifest itself
+     * sits in `extensions/<id>.extension.json`, and the data in `.patterextension` shards. Authoring config:
+     * the bundle carries each one's compiled declarations and values, never this block. An extension named
+     * here whose manifest is missing is a warning, and its data is left untouched.
+     */
+    extensions?: Record<string, ProjectExtension>;
     /** Ordered writing-status ladder (not-done -> done); default `DEFAULT_WRITING_STATUSES`. */
     writingStatuses?: WritingStatusDecl[];
     /** Ordered recording-status ladder (not-done -> done); default `DEFAULT_RECORDING_STATUSES`. */
@@ -951,6 +974,8 @@ interface CompiledSnippet {
     onExit?: CompiledEffect[];
     padAfterDefault?: number;
     gameData?: GameData;
+    /** This node's extension values, by extension id (editor-only fields stripped). Absent when it has none. */
+    extensions?: NodeExtensions;
     tags?: string[];
     jump?: Jump;
     secretUntilEligible?: boolean;
@@ -971,6 +996,8 @@ interface CompiledGroup {
     children: Array<CompiledGroup | CompiledSnippet>;
     padAfterDefault?: number;
     gameData?: GameData;
+    /** This node's extension values, by extension id (editor-only fields stripped). Absent when it has none. */
+    extensions?: NodeExtensions;
     tags?: string[];
     /** Option-position fields (spec §5) - only when a direct child of a `choice`. */
     prompt?: PromptBeat;
@@ -989,6 +1016,8 @@ interface CompiledBlock {
     children: Array<CompiledGroup | CompiledSnippet>;
     padAfterDefault?: number;
     gameData?: GameData;
+    /** This node's extension values, by extension id (editor-only fields stripped). Absent when it has none. */
+    extensions?: NodeExtensions;
     tags?: string[];
 }
 interface CompiledScene {
@@ -999,6 +1028,8 @@ interface CompiledScene {
     gameId?: string;
     padAfterDefault?: number;
     gameData?: GameData;
+    /** This node's extension values, by extension id (editor-only fields stripped). Absent when it has none. */
+    extensions?: NodeExtensions;
     tags?: string[];
     onEntry?: CompiledEffect[];
     sceneProps?: PropertyDecl[];
@@ -1039,6 +1070,13 @@ interface Bundle {
      *  one. Absent when none. */
     externalScopes?: string[];
     gameDataFields?: GameDataFields;
+    /**
+     * The extensions the project takes, by id: each one's version and its compiled declarations by node kind,
+     * every default resolved (what `extensionDecls` reads), and the project node's own values. A node's values
+     * sit on the node, under `extensions`. Absent when the project takes none, so a bundle without them is
+     * byte for byte what it was.
+     */
+    extensions?: Record<string, BundleExtension>;
     scenes: Record<string, CompiledScene>;
     /** locale -> (beatId -> text). In "embedded" localisation this carries every included locale; in "ids"
      *  it is EMPTY (the runtime emits beat IDs), unless `localisation.sourceDebug` embedded the source locale
@@ -1211,24 +1249,109 @@ declare const DEFAULT_LAYOUT: {
     readonly flow: "scenes/";
     readonly strings: "loc/";
     readonly authoring: "authoring/";
+    readonly extensions: "extensions/";
 };
-/** A project's layout with the defaults filled in: the one place they are written down (the loader,
- *  validate, localisation, the scene scaffold, and Patterpad each had a copy). */
-declare function projectLayout(project: {
-    layout?: {
-        flow?: string;
-        strings?: string;
-        authoring?: string;
-    };
-}): {
+/** Where a project keeps each kind of shard, relative to the project root (`ProjectFile.layout`). */
+interface ProjectLayout {
     flow: string;
     strings: string;
     authoring: string;
-};
+    extensions: string;
+}
+/** A project's layout with the defaults filled in: the one place they are written down (the loader,
+ *  validate, localisation, the scene scaffold, and Patterpad each had a copy). */
+declare function projectLayout(project: {
+    layout?: Partial<ProjectLayout>;
+}): ProjectLayout;
 /** The source shards' schema tags (spec §10), written by every tool that makes one. */
 declare const FLOW_SCHEMA = "patter/flow@0";
 declare const PROJECT_SCHEMA = "patter/project@0";
 declare const STRINGS_SCHEMA = "patter/strings@0";
 declare const AUTHORING_SCHEMA = "patter/authoring@0";
+/** An extension data shard's schema. */
+declare const EXTENSION_SCHEMA = "patter/extension@0";
+/** An extension data shard's file suffix: one per extension per scene
+ *  (`<layout.extensions>/<extension id>/<scene file stem>.patterextension`), and one for project-level
+ *  data (`<layout.extensions>/<extension id>/_project.patterextension`). Its own shard because a tool's
+ *  pass and a writer's edit must not collide on one file. */
+declare const EXTENSION_SHARD = ".patterextension";
+/** The stem of an extension's project-level data shard, beside its scene shards. */
+declare const PROJECT_EXTENSION_STEM = "_project";
+/**
+ * An extension's manifest, as a project keeps it: `extensions/<id>.extension.json` at the project root
+ * (`@wildwinter/toolkit/extensions`' `MANIFEST_FILE_SUFFIX`). Not a shard: JSON the extension ships, never
+ * written by the tools nor put in the canonical form, but source all the same, so a pack carries it and a
+ * project compiles from it.
+ */
+declare const MANIFEST_EXTENSION = ".extension.json";
+/** Where a project keeps its extensions' manifests, relative to the root. Fixed, unlike the data shards'
+ *  folder, so a merge driver handed one shard's path can always find the manifest. */
+declare const EXTENSIONS_DIR = "extensions";
+/**
+ * The extensions a project takes (`ProjectFile.extensions`), one each: the version it is pinned to and its
+ * settings (the host fields its claims present, by setting name).
+ */
+interface ProjectExtension {
+    version: string;
+    settings?: Record<string, string>;
+}
+/**
+ * One extension's data for one scene, or for the project (`scene: "@project"`).
+ *
+ * `entries` is the extension's, by node kind (`scene`, `block`, `snippet`, `line`, `text`, `gameEvent`,
+ * `option`, `project`) and then node id, and the canonical form never reorders anything inside it: its
+ * lists are the extension's, in the extension's order. The values are raw, as a tool wrote them; the
+ * extension's manifest says their types.
+ */
+interface ExtensionShard {
+    schema: typeof EXTENSION_SCHEMA;
+    /** The extension's id: the same as the folder the shard sits in. */
+    extension: string;
+    /** The scene this shard's entries belong to, or `PROJECT_LOCALE_SCENE` (`"@project"`) for the project's. */
+    scene: string;
+    entries: Record<string, Record<string, Record<string, unknown>>>;
+}
+/**
+ * The reserved key a merged shard carries an unresolved merge under, in every shard type
+ * (`@wildwinter/toolkit/extensions`' `UNRESOLVED_KEY`, ruled 2026-10-18 in both formats): the clashes, each
+ * with its path, its kind and the three values, ours being what the shard now holds. Validation, export
+ * and pack refuse a shard carrying it; resolving removes it.
+ */
+declare const UNRESOLVED_KEY = "unresolved";
+/** One extension as the bundle carries it. */
+interface BundleExtension {
+    version: string;
+    /** Compiled declarations by node kind: no editor-only fields, no editor words. */
+    fields: Record<string, ExtensionFieldDecl[]>;
+    /** The project node's values, raw, when it has any. */
+    project?: Record<string, unknown>;
+}
+/**
+ * A compiled extension field declaration (`@wildwinter/toolkit/extensions`' FieldDecl, less the editor's
+ * words). Its `default` is always present. Structured types carry their parts: `fields` for a record,
+ * `key` and `of` for a map, `of` and `id` for a list, `to` for a reference.
+ */
+interface ExtensionFieldDecl {
+    name: string;
+    type: string;
+    default: unknown;
+    values?: string[];
+    stages?: string[];
+    to?: string;
+    fields?: ExtensionFieldDecl[];
+    key?: {
+        type: string;
+        to?: string;
+    };
+    of?: Omit<ExtensionFieldDecl, "name" | "default"> & {
+        default?: unknown;
+    };
+    id?: string;
+    min?: number;
+    max?: number;
+    required?: boolean;
+}
+/** A node's extension values in a bundle: extension id -> field -> value, raw. */
+type NodeExtensions = Record<string, Record<string, unknown>>;
 
-export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type BundleQualifier, COMMON_GENDERS, type CaptionDelimiters, type CastMember, type Comment, type CommentMessage, type CommentRange, type CompiledBlock, type CompiledEffect, type CompiledGroup, type CompiledScene, type CompiledSnippet, type CoverageDriver, DEFAULT_CAPTION_CHARACTER, DEFAULT_CAPTION_DELIMITERS, DEFAULT_DOCUMENTATION_CLASSES, DEFAULT_LAYOUT, DEFAULT_PAD_AFTER, DEFAULT_QUALIFIERS, DEFAULT_RECORDING_STATUSES, DEFAULT_SPEAKER_PATTERN, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, FLOW_SCHEMA, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type FlowSnapshotV2, type FlowState, type FlowValues, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, HANDOFF_SCHEMA, type HandoffFile, type HandoffImport, type HandoffLine, type HandoffRow, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PAD_AFTER_MAX, PAD_AFTER_MIN, PROJECT_LOCALE_SCENE, PROJECT_SCHEMA, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, SPEAKER_PATTERN_KEY, STRINGS_SCHEMA, type SaveEnvelope, type SaveGame, type SaveGameV2, type SavedChoice, type SavedChoiceOption, type SavedChoicePrompt, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SelectorSnapshot, type SequenceOptions, type Snippet, type SpeakerQualifier, type StackFrame, type Suggestion, type SuggestionSource, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, formatSpeakerLabel, gameIdify, isContentlessBeat, isValidGameId, projectLayout, projectQualifiers, qualifierStringKey, speakerLabelKey, usedQualifiers, usedSpeakerPairs, walkNodes };
+export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type BundleExtension, type BundleQualifier, COMMON_GENDERS, type CaptionDelimiters, type CastMember, type Comment, type CommentMessage, type CommentRange, type CompiledBlock, type CompiledEffect, type CompiledGroup, type CompiledScene, type CompiledSnippet, type CoverageDriver, DEFAULT_CAPTION_CHARACTER, DEFAULT_CAPTION_DELIMITERS, DEFAULT_DOCUMENTATION_CLASSES, DEFAULT_LAYOUT, DEFAULT_PAD_AFTER, DEFAULT_QUALIFIERS, DEFAULT_RECORDING_STATUSES, DEFAULT_SPEAKER_PATTERN, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, EXTENSIONS_DIR, EXTENSION_SCHEMA, EXTENSION_SHARD, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, type ExtensionFieldDecl, type ExtensionShard, FLOW_SCHEMA, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type FlowSnapshotV2, type FlowState, type FlowValues, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, HANDOFF_SCHEMA, type HandoffFile, type HandoffImport, type HandoffLine, type HandoffRow, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, MANIFEST_EXTENSION, type NodeExtensions, PAD_AFTER_MAX, PAD_AFTER_MIN, PROJECT_EXTENSION_STEM, PROJECT_LOCALE_SCENE, PROJECT_SCHEMA, type ProjectDictionary, type ProjectExtension, type ProjectFile, type ProjectLayout, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, SPEAKER_PATTERN_KEY, STRINGS_SCHEMA, type SaveEnvelope, type SaveGame, type SaveGameV2, type SavedChoice, type SavedChoiceOption, type SavedChoicePrompt, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SelectorSnapshot, type SequenceOptions, type Snippet, type SpeakerQualifier, type StackFrame, type Suggestion, type SuggestionSource, type TextBeat, UNRESOLVED_KEY, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, formatSpeakerLabel, gameIdify, isContentlessBeat, isValidGameId, projectLayout, projectQualifiers, qualifierStringKey, speakerLabelKey, usedQualifiers, usedSpeakerPairs, walkNodes };

package/dist/index.d.ts

@@ -33,6 +33,10 @@ interface LineBeat {
      *  Never negative on a snippet's last line or text beat: the runtime clamps it to zero there. */
     padAfter?: number;
     gameData?: GameData;
+    /** Bundle only: this node's extension values, by extension id, raw as authored (editor-only fields
+     *  stripped). Source keeps them in extension shards (`.patterextension`), never here. Absent when the
+     *  node has none. */
+    extensions?: NodeExtensions;
     /** Author-defined freeform tags (#215): a cross-cutting label layer that travels to the runtime.
      *  At runtime a beat's tags are the UNION of its own and every ancestor's (scene → block → group(s) →
      *  snippet → beat). Each tag is letters/digits/symbols with NO comma and NO whitespace; deduped. */
@@ -53,6 +57,10 @@ interface TextBeat {
      *  Never negative on a snippet's last line or text beat: the runtime clamps it to zero there. */
     padAfter?: number;
     gameData?: GameData;
+    /** Bundle only: this node's extension values, by extension id, raw as authored (editor-only fields
+     *  stripped). Source keeps them in extension shards (`.patterextension`), never here. Absent when the
+     *  node has none. */
+    extensions?: NodeExtensions;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
 }
@@ -66,6 +74,10 @@ interface GameEventBeat {
     id: string;
     kind: "gameEvent";
     gameData?: GameData;
+    /** Bundle only: this node's extension values, by extension id, raw as authored (editor-only fields
+     *  stripped). Source keeps them in extension shards (`.patterextension`), never here. Absent when the
+     *  node has none. */
+    extensions?: NodeExtensions;
     /** Author tags (#215). See LineBeat.tags. */
     tags?: string[];
 }
@@ -400,8 +412,10 @@ interface BundleQualifier {
  *  the bundle; this type states the resulting contract for anyone reading a bundle. */
 type BundleCastMember = Omit<CastMember, "notes" | "actor" | "gender">;
 /** A node TYPE that can carry author-defined gameData fields (the gameData schema, project-level).
- *  Beat kinds map straight through: dialogue = `line`, narration = `text`, game event = `gameEvent`. */
-type GameDataNodeKind = "scene" | "block" | "snippet" | "line" | "text" | "gameEvent";
+ *  Beat kinds map straight through: dialogue = `line`, narration = `text`, game event = `gameEvent`.
+ *  `option` is a choice's option: a group that is a direct child of a `choice` group, whose gameData the
+ *  host reads off the option `getChoices` hands it. Any other group's gameData stays undeclared. */
+type GameDataNodeKind = "scene" | "block" | "snippet" | "line" | "text" | "gameEvent" | "option";
 /** The value type of a gameData field: the family's one field-type list, shared with Storylets' card and
  *  outcome fields (patterkit design/family-parity-2026-10.md item 9, patter-qualities.md section 1). Drives
  *  the inspector's editor widget (text / textarea / number / toggle / enum dropdown / flags checklist /
@@ -604,6 +618,7 @@ interface ProjectFile {
         flow?: string;
         strings?: string;
         authoring?: string;
+        extensions?: string;
     };
     /** `bundle`: the compiled `.patterc` output path (relative to the project root,
      *  or absolute); default `../patter-dist/<project-file-stem>.patterc`, beside the project (spec §11).
@@ -648,6 +663,14 @@ interface ProjectFile {
      *  Absent = `DEFAULT_PAD_AFTER`. */
     padAfterDefault?: number;
     gameDataFields?: GameDataFields;
+    /**
+     * The Patter extensions this project takes, by id (ruled 2026-10-18: the project opts in), each pinned to a
+     * version, with its settings (the host fields its claims present, by setting name). The manifest itself
+     * sits in `extensions/<id>.extension.json`, and the data in `.patterextension` shards. Authoring config:
+     * the bundle carries each one's compiled declarations and values, never this block. An extension named
+     * here whose manifest is missing is a warning, and its data is left untouched.
+     */
+    extensions?: Record<string, ProjectExtension>;
     /** Ordered writing-status ladder (not-done -> done); default `DEFAULT_WRITING_STATUSES`. */
     writingStatuses?: WritingStatusDecl[];
     /** Ordered recording-status ladder (not-done -> done); default `DEFAULT_RECORDING_STATUSES`. */
@@ -951,6 +974,8 @@ interface CompiledSnippet {
     onExit?: CompiledEffect[];
     padAfterDefault?: number;
     gameData?: GameData;
+    /** This node's extension values, by extension id (editor-only fields stripped). Absent when it has none. */
+    extensions?: NodeExtensions;
     tags?: string[];
     jump?: Jump;
     secretUntilEligible?: boolean;
@@ -971,6 +996,8 @@ interface CompiledGroup {
     children: Array<CompiledGroup | CompiledSnippet>;
     padAfterDefault?: number;
     gameData?: GameData;
+    /** This node's extension values, by extension id (editor-only fields stripped). Absent when it has none. */
+    extensions?: NodeExtensions;
     tags?: string[];
     /** Option-position fields (spec §5) - only when a direct child of a `choice`. */
     prompt?: PromptBeat;
@@ -989,6 +1016,8 @@ interface CompiledBlock {
     children: Array<CompiledGroup | CompiledSnippet>;
     padAfterDefault?: number;
     gameData?: GameData;
+    /** This node's extension values, by extension id (editor-only fields stripped). Absent when it has none. */
+    extensions?: NodeExtensions;
     tags?: string[];
 }
 interface CompiledScene {
@@ -999,6 +1028,8 @@ interface CompiledScene {
     gameId?: string;
     padAfterDefault?: number;
     gameData?: GameData;
+    /** This node's extension values, by extension id (editor-only fields stripped). Absent when it has none. */
+    extensions?: NodeExtensions;
     tags?: string[];
     onEntry?: CompiledEffect[];
     sceneProps?: PropertyDecl[];
@@ -1039,6 +1070,13 @@ interface Bundle {
      *  one. Absent when none. */
     externalScopes?: string[];
     gameDataFields?: GameDataFields;
+    /**
+     * The extensions the project takes, by id: each one's version and its compiled declarations by node kind,
+     * every default resolved (what `extensionDecls` reads), and the project node's own values. A node's values
+     * sit on the node, under `extensions`. Absent when the project takes none, so a bundle without them is
+     * byte for byte what it was.
+     */
+    extensions?: Record<string, BundleExtension>;
     scenes: Record<string, CompiledScene>;
     /** locale -> (beatId -> text). In "embedded" localisation this carries every included locale; in "ids"
      *  it is EMPTY (the runtime emits beat IDs), unless `localisation.sourceDebug` embedded the source locale
@@ -1211,24 +1249,109 @@ declare const DEFAULT_LAYOUT: {
     readonly flow: "scenes/";
     readonly strings: "loc/";
     readonly authoring: "authoring/";
+    readonly extensions: "extensions/";
 };
-/** A project's layout with the defaults filled in: the one place they are written down (the loader,
- *  validate, localisation, the scene scaffold, and Patterpad each had a copy). */
-declare function projectLayout(project: {
-    layout?: {
-        flow?: string;
-        strings?: string;
-        authoring?: string;
-    };
-}): {
+/** Where a project keeps each kind of shard, relative to the project root (`ProjectFile.layout`). */
+interface ProjectLayout {
     flow: string;
     strings: string;
     authoring: string;
-};
+    extensions: string;
+}
+/** A project's layout with the defaults filled in: the one place they are written down (the loader,
+ *  validate, localisation, the scene scaffold, and Patterpad each had a copy). */
+declare function projectLayout(project: {
+    layout?: Partial<ProjectLayout>;
+}): ProjectLayout;
 /** The source shards' schema tags (spec §10), written by every tool that makes one. */
 declare const FLOW_SCHEMA = "patter/flow@0";
 declare const PROJECT_SCHEMA = "patter/project@0";
 declare const STRINGS_SCHEMA = "patter/strings@0";
 declare const AUTHORING_SCHEMA = "patter/authoring@0";
+/** An extension data shard's schema. */
+declare const EXTENSION_SCHEMA = "patter/extension@0";
+/** An extension data shard's file suffix: one per extension per scene
+ *  (`<layout.extensions>/<extension id>/<scene file stem>.patterextension`), and one for project-level
+ *  data (`<layout.extensions>/<extension id>/_project.patterextension`). Its own shard because a tool's
+ *  pass and a writer's edit must not collide on one file. */
+declare const EXTENSION_SHARD = ".patterextension";
+/** The stem of an extension's project-level data shard, beside its scene shards. */
+declare const PROJECT_EXTENSION_STEM = "_project";
+/**
+ * An extension's manifest, as a project keeps it: `extensions/<id>.extension.json` at the project root
+ * (`@wildwinter/toolkit/extensions`' `MANIFEST_FILE_SUFFIX`). Not a shard: JSON the extension ships, never
+ * written by the tools nor put in the canonical form, but source all the same, so a pack carries it and a
+ * project compiles from it.
+ */
+declare const MANIFEST_EXTENSION = ".extension.json";
+/** Where a project keeps its extensions' manifests, relative to the root. Fixed, unlike the data shards'
+ *  folder, so a merge driver handed one shard's path can always find the manifest. */
+declare const EXTENSIONS_DIR = "extensions";
+/**
+ * The extensions a project takes (`ProjectFile.extensions`), one each: the version it is pinned to and its
+ * settings (the host fields its claims present, by setting name).
+ */
+interface ProjectExtension {
+    version: string;
+    settings?: Record<string, string>;
+}
+/**
+ * One extension's data for one scene, or for the project (`scene: "@project"`).
+ *
+ * `entries` is the extension's, by node kind (`scene`, `block`, `snippet`, `line`, `text`, `gameEvent`,
+ * `option`, `project`) and then node id, and the canonical form never reorders anything inside it: its
+ * lists are the extension's, in the extension's order. The values are raw, as a tool wrote them; the
+ * extension's manifest says their types.
+ */
+interface ExtensionShard {
+    schema: typeof EXTENSION_SCHEMA;
+    /** The extension's id: the same as the folder the shard sits in. */
+    extension: string;
+    /** The scene this shard's entries belong to, or `PROJECT_LOCALE_SCENE` (`"@project"`) for the project's. */
+    scene: string;
+    entries: Record<string, Record<string, Record<string, unknown>>>;
+}
+/**
+ * The reserved key a merged shard carries an unresolved merge under, in every shard type
+ * (`@wildwinter/toolkit/extensions`' `UNRESOLVED_KEY`, ruled 2026-10-18 in both formats): the clashes, each
+ * with its path, its kind and the three values, ours being what the shard now holds. Validation, export
+ * and pack refuse a shard carrying it; resolving removes it.
+ */
+declare const UNRESOLVED_KEY = "unresolved";
+/** One extension as the bundle carries it. */
+interface BundleExtension {
+    version: string;
+    /** Compiled declarations by node kind: no editor-only fields, no editor words. */
+    fields: Record<string, ExtensionFieldDecl[]>;
+    /** The project node's values, raw, when it has any. */
+    project?: Record<string, unknown>;
+}
+/**
+ * A compiled extension field declaration (`@wildwinter/toolkit/extensions`' FieldDecl, less the editor's
+ * words). Its `default` is always present. Structured types carry their parts: `fields` for a record,
+ * `key` and `of` for a map, `of` and `id` for a list, `to` for a reference.
+ */
+interface ExtensionFieldDecl {
+    name: string;
+    type: string;
+    default: unknown;
+    values?: string[];
+    stages?: string[];
+    to?: string;
+    fields?: ExtensionFieldDecl[];
+    key?: {
+        type: string;
+        to?: string;
+    };
+    of?: Omit<ExtensionFieldDecl, "name" | "default"> & {
+        default?: unknown;
+    };
+    id?: string;
+    min?: number;
+    max?: number;
+    required?: boolean;
+}
+/** A node's extension values in a bundle: extension id -> field -> value, raw. */
+type NodeExtensions = Record<string, Record<string, unknown>>;
 
-export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type BundleQualifier, COMMON_GENDERS, type CaptionDelimiters, type CastMember, type Comment, type CommentMessage, type CommentRange, type CompiledBlock, type CompiledEffect, type CompiledGroup, type CompiledScene, type CompiledSnippet, type CoverageDriver, DEFAULT_CAPTION_CHARACTER, DEFAULT_CAPTION_DELIMITERS, DEFAULT_DOCUMENTATION_CLASSES, DEFAULT_LAYOUT, DEFAULT_PAD_AFTER, DEFAULT_QUALIFIERS, DEFAULT_RECORDING_STATUSES, DEFAULT_SPEAKER_PATTERN, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, FLOW_SCHEMA, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type FlowSnapshotV2, type FlowState, type FlowValues, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, HANDOFF_SCHEMA, type HandoffFile, type HandoffImport, type HandoffLine, type HandoffRow, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, PAD_AFTER_MAX, PAD_AFTER_MIN, PROJECT_LOCALE_SCENE, PROJECT_SCHEMA, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, SPEAKER_PATTERN_KEY, STRINGS_SCHEMA, type SaveEnvelope, type SaveGame, type SaveGameV2, type SavedChoice, type SavedChoiceOption, type SavedChoicePrompt, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SelectorSnapshot, type SequenceOptions, type Snippet, type SpeakerQualifier, type StackFrame, type Suggestion, type SuggestionSource, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, formatSpeakerLabel, gameIdify, isContentlessBeat, isValidGameId, projectLayout, projectQualifiers, qualifierStringKey, speakerLabelKey, usedQualifiers, usedSpeakerPairs, walkNodes };
+export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, type BundleExtension, type BundleQualifier, COMMON_GENDERS, type CaptionDelimiters, type CastMember, type Comment, type CommentMessage, type CommentRange, type CompiledBlock, type CompiledEffect, type CompiledGroup, type CompiledScene, type CompiledSnippet, type CoverageDriver, DEFAULT_CAPTION_CHARACTER, DEFAULT_CAPTION_DELIMITERS, DEFAULT_DOCUMENTATION_CLASSES, DEFAULT_LAYOUT, DEFAULT_PAD_AFTER, DEFAULT_QUALIFIERS, DEFAULT_RECORDING_STATUSES, DEFAULT_SPEAKER_PATTERN, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, EXTENSIONS_DIR, EXTENSION_SCHEMA, EXTENSION_SHARD, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, type ExtensionFieldDecl, type ExtensionShard, FLOW_SCHEMA, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type FlowSnapshotV2, type FlowState, type FlowValues, type GameData, type GameDataField, type GameDataFieldType, type GameDataFields, type GameDataNodeKind, type GameEventBeat, type GrammaticalGender, type Group, HANDOFF_SCHEMA, type HandoffFile, type HandoffImport, type HandoffLine, type HandoffRow, type HostScopeDecl, type HostScopeRegistry, type HostScopeSpec, type Jump, type JumpTarget, type LineBeat, type LocaleFile, MANIFEST_EXTENSION, type NodeExtensions, PAD_AFTER_MAX, PAD_AFTER_MIN, PROJECT_EXTENSION_STEM, PROJECT_LOCALE_SCENE, PROJECT_SCHEMA, type ProjectDictionary, type ProjectExtension, type ProjectFile, type ProjectLayout, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, SPEAKER_PATTERN_KEY, STRINGS_SCHEMA, type SaveEnvelope, type SaveGame, type SaveGameV2, type SavedChoice, type SavedChoiceOption, type SavedChoicePrompt, type ScalarValue, type Scene, type Selector, type SelectorExhaust, type SelectorOrder, type SelectorSnapshot, type SequenceOptions, type Snippet, type SpeakerQualifier, type StackFrame, type Suggestion, type SuggestionSource, type TextBeat, UNRESOLVED_KEY, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, formatSpeakerLabel, gameIdify, isContentlessBeat, isValidGameId, projectLayout, projectQualifiers, qualifierStringKey, speakerLabelKey, usedQualifiers, usedSpeakerPairs, walkNodes };

package/dist/index.js

@@ -140,7 +140,7 @@ var DEFAULT_CAPTION_DELIMITERS = { open: "[", close: "]" };
 var DEFAULT_CAPTION_CHARACTER = "SFX";
 var SAVE_SCHEMA = "patter/save@0";
 var SAVE_VERSION = 3;
-var DEFAULT_LAYOUT = { flow: "scenes/", strings: "loc/", authoring: "authoring/" };
+var DEFAULT_LAYOUT = { flow: "scenes/", strings: "loc/", authoring: "authoring/", extensions: "extensions/" };
 function projectLayout(project) {
   return { ...DEFAULT_LAYOUT, ...project.layout };
 }
@@ -148,6 +148,12 @@ var FLOW_SCHEMA = "patter/flow@0";
 var PROJECT_SCHEMA = "patter/project@0";
 var STRINGS_SCHEMA = "patter/strings@0";
 var AUTHORING_SCHEMA = "patter/authoring@0";
+var EXTENSION_SCHEMA = "patter/extension@0";
+var EXTENSION_SHARD = ".patterextension";
+var PROJECT_EXTENSION_STEM = "_project";
+var MANIFEST_EXTENSION = ".extension.json";
+var EXTENSIONS_DIR = "extensions";
+var UNRESOLVED_KEY = "unresolved";
 export {
   AUTHORING_SCHEMA,
   COMMON_GENDERS,
@@ -160,10 +166,15 @@ export {
   DEFAULT_RECORDING_STATUSES,
   DEFAULT_SPEAKER_PATTERN,
   DEFAULT_WRITING_STATUSES,
+  EXTENSIONS_DIR,
+  EXTENSION_SCHEMA,
+  EXTENSION_SHARD,
   FLOW_SCHEMA,
   HANDOFF_SCHEMA,
+  MANIFEST_EXTENSION,
   PAD_AFTER_MAX,
   PAD_AFTER_MIN,
+  PROJECT_EXTENSION_STEM,
   PROJECT_LOCALE_SCENE,
   PROJECT_SCHEMA,
   RERECORD_STATUS,
@@ -173,6 +184,7 @@ export {
   SAVE_VERSION,
   SPEAKER_PATTERN_KEY,
   STRINGS_SCHEMA,
+  UNRESOLVED_KEY,
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/model",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Patter data-model types: source (scene/block/group/snippet/beat/jump), project, locale, authoring. The shape source-of-truth.",
   "type": "module",
   "license": "MIT",