@patterkit/model 0.8.0 → 0.10.0

package/README.md

@@ -0,0 +1,35 @@
+# @patterkit/model
+
+The TypeScript types that describe Patter's data: the shape every other `@patterkit` package agrees on.
+Types only, with no behaviour.
+
+Most people won't need to install this directly. To play Patter dialogue in a game or web page, use
+[`@patterkit/runtime`](https://www.npmjs.com/package/@patterkit/runtime); to work with Patter projects from
+a terminal or a build script, use [`@patterkit/cli`](https://www.npmjs.com/package/@patterkit/cli).
+
+## What's in it
+
+- **The source format**: scenes and their flow tree (blocks, groups, snippets, beats, and jumps), the
+  project file, locale files, and the authoring file that holds comments, suggestions, and writing status.
+- **The compiled bundle**: the `.patterc` a game loads, as written by the compiler and read by every runtime.
+- **Shared helpers for addressing**: the game-facing ids (`gameIdify`, `isValidGameId`, `effectiveGameId`).
+
+Conditions and effects are kept as source strings here; the expression language itself is
+[`@wildwinter/expr`](https://www.npmjs.com/package/@wildwinter/expr). The format is described in
+[the specification](https://patterkit.dev/specification/).
+
+```sh
+npm install @patterkit/model
+```
+
+## Part of Patter
+
+[Patter](https://patterkit.dev/) is a branching dialogue format with its own editor (Patterpad), command line
+tool (`patter`), and runtimes for JavaScript, Unity, Unreal, and Godot. This package is one layer of the
+JavaScript tooling, and the other `@patterkit` packages build on it. [How it fits
+together](https://patterkit.dev/architecture/) shows where each piece sits, and the source is in the
+[patter repository](https://github.com/patterkit/patter).
+
+## Licence
+
+MIT

package/dist/index.cjs

@@ -20,19 +20,24 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AUTHORING_SCHEMA: () => AUTHORING_SCHEMA,
   COMMON_GENDERS: () => COMMON_GENDERS,
   DEFAULT_CAPTION_CHARACTER: () => DEFAULT_CAPTION_CHARACTER,
   DEFAULT_CAPTION_DELIMITERS: () => DEFAULT_CAPTION_DELIMITERS,
   DEFAULT_DOCUMENTATION_CLASSES: () => DEFAULT_DOCUMENTATION_CLASSES,
+  DEFAULT_LAYOUT: () => DEFAULT_LAYOUT,
   DEFAULT_RECORDING_STATUSES: () => DEFAULT_RECORDING_STATUSES,
   DEFAULT_WRITING_STATUSES: () => DEFAULT_WRITING_STATUSES,
+  FLOW_SCHEMA: () => FLOW_SCHEMA,
   HANDOFF_SCHEMA: () => HANDOFF_SCHEMA,
   PROJECT_LOCALE_SCENE: () => PROJECT_LOCALE_SCENE,
+  PROJECT_SCHEMA: () => PROJECT_SCHEMA,
   RERECORD_STATUS: () => RERECORD_STATUS,
   RERECORD_STATUS_DECL: () => RERECORD_STATUS_DECL,
   RESERVED_PROPERTY_NAMES: () => import_expr.RESERVED_PROPERTY_NAMES,
   SAVE_SCHEMA: () => SAVE_SCHEMA,
   SAVE_VERSION: () => SAVE_VERSION,
+  STRINGS_SCHEMA: () => STRINGS_SCHEMA,
   castStringKey: () => castStringKey,
   deriveRecordingFolders: () => deriveRecordingFolders,
   effectiveGameId: () => effectiveGameId,
@@ -41,6 +46,7 @@ __export(index_exports, {
   isContentlessBeat: () => isContentlessBeat,
   isValidGameId: () => isValidGameId,
   isValidPropertyName: () => import_expr.isValidPropertyName,
+  projectLayout: () => projectLayout,
   propertyNameify: () => import_expr.propertyNameify,
   walkNodes: () => walkNodes
 });
@@ -121,21 +127,34 @@ 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/" };
+function projectLayout(project) {
+  return { ...DEFAULT_LAYOUT, ...project.layout };
+}
+var FLOW_SCHEMA = "patter/flow@0";
+var PROJECT_SCHEMA = "patter/project@0";
+var STRINGS_SCHEMA = "patter/strings@0";
+var AUTHORING_SCHEMA = "patter/authoring@0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AUTHORING_SCHEMA,
   COMMON_GENDERS,
   DEFAULT_CAPTION_CHARACTER,
   DEFAULT_CAPTION_DELIMITERS,
   DEFAULT_DOCUMENTATION_CLASSES,
+  DEFAULT_LAYOUT,
   DEFAULT_RECORDING_STATUSES,
   DEFAULT_WRITING_STATUSES,
+  FLOW_SCHEMA,
   HANDOFF_SCHEMA,
   PROJECT_LOCALE_SCENE,
+  PROJECT_SCHEMA,
   RERECORD_STATUS,
   RERECORD_STATUS_DECL,
   RESERVED_PROPERTY_NAMES,
   SAVE_SCHEMA,
   SAVE_VERSION,
+  STRINGS_SCHEMA,
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,
@@ -144,6 +163,7 @@ var SAVE_VERSION = 3;
   isContentlessBeat,
   isValidGameId,
   isValidPropertyName,
+  projectLayout,
   propertyNameify,
   walkNodes
 });

package/dist/index.d.cts

@@ -533,7 +533,7 @@ interface ProjectFile {
         authoring?: string;
     };
     /** `bundle`: the compiled `.patterc` output path (relative to the project root,
-     *  or absolute); default `dist/<project-file-stem>.patterc` (spec §11).
+     *  or absolute); default `../patter-dist/<project-file-stem>.patterc`, beside the project (spec §11).
      *  `localisation`: how strings ship + are resolved (spec §11).
      *    - "embedded" (default): every locale's strings live INSIDE the `.patterc`; the runtime resolves
      *      them and can switch locale live (`setLocale`).
@@ -1017,6 +1017,12 @@ interface FlowCursor {
     /** The chosen option owning a prompt still to be replayed (a save taken between choose + advance).
      *  Optional / null in older saves -> no pending prompt. */
     pendingPromptOwnerId?: string | null;
+    /** The prompt still to be replayed, exactly as the choice SHOWED it (text and speaker fields, the same
+     *  shape as a saved option's `prompt`), so the replay after a load says what the player saw. Written only
+     *  alongside a `pendingPromptOwnerId` (the choose -> advance window, with `replayPromptOnChoose`), and
+     *  absent otherwise. A save without it (written before Patterplay 0.18.0) resolves the owner's prompt beat
+     *  when it is delivered, as before. */
+    pendingPrompt?: SavedChoicePrompt;
     /** This flow's (non-shared) selector cursors, keyed by group id. */
     selectors: Record<string, SelectorSnapshot>;
 }
@@ -1061,5 +1067,29 @@ interface SaveGameV2 {
     stageBags: Record<string, Record<string, ScalarValue>>;
     flows: Record<string, FlowSnapshotV2>;
 }
+/** Where a project keeps its shards unless its `layout` says otherwise, relative to the project root. */
+declare const DEFAULT_LAYOUT: {
+    readonly flow: "scenes/";
+    readonly strings: "loc/";
+    readonly authoring: "authoring/";
+};
+/** 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;
+    };
+}): {
+    flow: string;
+    strings: string;
+    authoring: string;
+};
+/** 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";
 
-export { type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, 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_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type FlowSnapshotV2, 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, PROJECT_LOCALE_SCENE, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, 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 StackFrame, type Suggestion, type SuggestionSource, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, walkNodes };
+export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, 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_RECORDING_STATUSES, 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 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, 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, 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 StackFrame, type Suggestion, type SuggestionSource, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, projectLayout, walkNodes };

package/dist/index.d.ts

@@ -533,7 +533,7 @@ interface ProjectFile {
         authoring?: string;
     };
     /** `bundle`: the compiled `.patterc` output path (relative to the project root,
-     *  or absolute); default `dist/<project-file-stem>.patterc` (spec §11).
+     *  or absolute); default `../patter-dist/<project-file-stem>.patterc`, beside the project (spec §11).
      *  `localisation`: how strings ship + are resolved (spec §11).
      *    - "embedded" (default): every locale's strings live INSIDE the `.patterc`; the runtime resolves
      *      them and can switch locale live (`setLocale`).
@@ -1017,6 +1017,12 @@ interface FlowCursor {
     /** The chosen option owning a prompt still to be replayed (a save taken between choose + advance).
      *  Optional / null in older saves -> no pending prompt. */
     pendingPromptOwnerId?: string | null;
+    /** The prompt still to be replayed, exactly as the choice SHOWED it (text and speaker fields, the same
+     *  shape as a saved option's `prompt`), so the replay after a load says what the player saw. Written only
+     *  alongside a `pendingPromptOwnerId` (the choose -> advance window, with `replayPromptOnChoose`), and
+     *  absent otherwise. A save without it (written before Patterplay 0.18.0) resolves the owner's prompt beat
+     *  when it is delivered, as before. */
+    pendingPrompt?: SavedChoicePrompt;
     /** This flow's (non-shared) selector cursors, keyed by group id. */
     selectors: Record<string, SelectorSnapshot>;
 }
@@ -1061,5 +1067,29 @@ interface SaveGameV2 {
     stageBags: Record<string, Record<string, ScalarValue>>;
     flows: Record<string, FlowSnapshotV2>;
 }
+/** Where a project keeps its shards unless its `layout` says otherwise, relative to the project root. */
+declare const DEFAULT_LAYOUT: {
+    readonly flow: "scenes/";
+    readonly strings: "loc/";
+    readonly authoring: "authoring/";
+};
+/** 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;
+    };
+}): {
+    flow: string;
+    strings: string;
+    authoring: string;
+};
+/** 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";
 
-export { type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, 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_RECORDING_STATUSES, DEFAULT_WRITING_STATUSES, type DocLine, type DocumentationClass, type EditRecord, type Effect, type EngineSave, type EstimatingConfig, type Expression, type FlowCursor, type FlowFile, type FlowNode, type FlowSnapshot, type FlowSnapshotV2, 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, PROJECT_LOCALE_SCENE, type ProjectDictionary, type ProjectFile, type PromptBeat, type PropertyDecl, type PropertyType, RERECORD_STATUS, RERECORD_STATUS_DECL, type RecordingFolder, type RecordingStatusDecl, SAVE_SCHEMA, SAVE_VERSION, 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 StackFrame, type Suggestion, type SuggestionSource, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, walkNodes };
+export { AUTHORING_SCHEMA, type AuthoringFile, type Beat, type Block, type Bundle, type BundleCastMember, 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_RECORDING_STATUSES, 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 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, 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, 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 StackFrame, type Suggestion, type SuggestionSource, type TextBeat, type VcsKind, type WritingStatusDecl, castStringKey, deriveRecordingFolders, effectiveGameId, gameIdify, isContentlessBeat, isValidGameId, projectLayout, walkNodes };

package/dist/index.js

@@ -80,20 +80,33 @@ 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/" };
+function projectLayout(project) {
+  return { ...DEFAULT_LAYOUT, ...project.layout };
+}
+var FLOW_SCHEMA = "patter/flow@0";
+var PROJECT_SCHEMA = "patter/project@0";
+var STRINGS_SCHEMA = "patter/strings@0";
+var AUTHORING_SCHEMA = "patter/authoring@0";
 export {
+  AUTHORING_SCHEMA,
   COMMON_GENDERS,
   DEFAULT_CAPTION_CHARACTER,
   DEFAULT_CAPTION_DELIMITERS,
   DEFAULT_DOCUMENTATION_CLASSES,
+  DEFAULT_LAYOUT,
   DEFAULT_RECORDING_STATUSES,
   DEFAULT_WRITING_STATUSES,
+  FLOW_SCHEMA,
   HANDOFF_SCHEMA,
   PROJECT_LOCALE_SCENE,
+  PROJECT_SCHEMA,
   RERECORD_STATUS,
   RERECORD_STATUS_DECL,
   RESERVED_PROPERTY_NAMES,
   SAVE_SCHEMA,
   SAVE_VERSION,
+  STRINGS_SCHEMA,
   castStringKey,
   deriveRecordingFolders,
   effectiveGameId,
@@ -102,6 +115,7 @@ export {
   isContentlessBeat,
   isValidGameId,
   isValidPropertyName,
+  projectLayout,
   propertyNameify,
   walkNodes
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/model",
-  "version": "0.8.0",
+  "version": "0.10.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",