@proophboard/exploration-runtime 0.0.0-stage → 0.1.0

package/dist/playFunction/playLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playLog.js","sourceRoot":"","sources":["../../src/playFunction/playLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAkBH,+EAA+E;AAC/E,MAAM,aAAa,GAAgC;IACjD,QAAQ,EAAE,SAAS,EAAE,eAAe;IACpC,MAAM,EAAI,SAAS,EAAE,oBAAoB;IACzC,KAAK,EAAK,SAAS,EAAE,6BAA6B;IAClD,IAAI,EAAM,SAAS,EAAE,6BAA6B;IAClD,KAAK,EAAK,SAAS,EAAE,gCAAgC;IACrD,OAAO,EAAG,SAAS,EAAE,2BAA2B;IAChD,KAAK,EAAK,SAAS,EAAE,0BAA0B;IAC/C,KAAK,EAAK,SAAS,EAAE,uCAAuC;IAC5D,OAAO,EAAG,SAAS,EAAE,6BAA6B;IAClD,IAAI,EAAM,SAAS,EAAE,0BAA0B;IAC/C,KAAK,EAAK,SAAS,EAAE,oBAAoB;CAC1C,CAAC;AAEF,+EAA+E;AAC/E,MAAM,SAAS,GAA+B;IAC5C,IAAI,EAAE,SAAS,EAAQ,YAAY;IACnC,UAAU,EAAE,SAAS,EAAE,aAAa;CACrC,CAAC;AAEF,MAAM,UAAU,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC;AAElD;;;GAGG;AACH,MAAM,UAAU,OAAO,CACrB,MAAkB,EAClB,OAAoB,EACpB,OAAe,EACf,GAAG,IAAe;IAElB,IAAI,CAAC,UAAU;QAAE,OAAO;IACxB,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAChC,qEAAqE;IACrE,MAAM,MAAM,GAAG,MAAM,MAAM,OAAO,OAAO,EAAE,CAAC;IAC5C,MAAM,QAAQ,GAAG,cAAc,KAAK,+DAA+D,CAAC;IACpG,MAAM,OAAO,GAAG,SAAS,KAAK,kBAAkB,CAAC;IACjD,IAAI,CAAC;QACH,sCAAsC;QACtC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,gDAAgD;IAClD,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,MAAkB;IAC/C,OAAO,CAAC,OAAoB,EAAE,OAAe,EAAE,GAAG,IAAe,EAAE,EAAE,CACnE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;AAC/C,CAAC"}

package/dist/playFunction/playType.d.ts

@@ -0,0 +1,52 @@
+/**
+ * playType — helpers for the Play Function "Type" sub-editor (author-defined
+ * payload types, Exploration).
+ *
+ * STORAGE CONTRACT: `element.playType` holds a BARE TypeScript type EXPRESSION
+ * (e.g. `{ title: string; due?: string }`) — no alias, no name. It slots directly
+ * into the generated payload maps as `"<element>": <expr>;` (see modelTypes.ts).
+ *
+ * EDITOR CONTRACT: the author edits a VISIBLE, valid-standalone alias so Monaco
+ * type-checks it as a real type (not a statement block):
+ *
+ *   type Payload = {
+ *     title: string;
+ *   };
+ *
+ * On save we strip the `type Payload =` wrapper (and optional trailing `;`) and
+ * store the inner expression; on load we re-wrap it. The fixed alias name
+ * (`Payload`) keeps extraction a deterministic prefix-strip — no AST parse, no
+ * name handling.
+ */
+/** The fixed alias name the Type editor wraps the payload expression in. */
+export declare const PLAY_TYPE_ALIAS = "Payload";
+/**
+ * Wrap a stored bare type expression into the editable alias form. An empty/absent
+ * expression seeds an empty object body so the author has a valid starting point.
+ */
+export declare function wrapPlayType(expr: string | undefined): string;
+/** Result of validating/extracting the Type editor buffer on save. */
+export type PlayTypeParse = {
+    ok: true;
+    value: string | undefined;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validate the Type editor buffer and extract the bare expression.
+ *
+ * Lightweight guard (as requested): the buffer MUST declare `type Payload = …`.
+ * We do NOT deep-validate the body — Monaco already type-checks it live. An empty
+ * body (`type Payload = {}` with nothing meaningful, or a blank buffer) resolves
+ * to `undefined` so absence ⇒ the permissive payload fallback.
+ */
+export declare function parsePlayType(buffer: string): PlayTypeParse;
+/**
+ * A prefill for the Type editor, element-type-aware so the author gets a sensible
+ * starting shape. Returns the WRAPPED alias form (what the editor shows).
+ */
+export declare function prefillPlayType(elementType: string): string;
+/** Which element types support an author-defined payload type (Type editor shown). */
+export declare function hasPlayType(elementType: string): boolean;
+//# sourceMappingURL=playType.d.ts.map

package/dist/playFunction/playType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playType.d.ts","sourceRoot":"","sources":["../../src/playFunction/playType.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,eAAe,YAAY,CAAC;AAYzC;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM7D;AAED,sEAAsE;AACtE,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACvC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAsB3D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAa3D;AAED,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAOxD"}

package/dist/playFunction/playType.js

@@ -0,0 +1,94 @@
+/**
+ * playType — helpers for the Play Function "Type" sub-editor (author-defined
+ * payload types, Exploration).
+ *
+ * STORAGE CONTRACT: `element.playType` holds a BARE TypeScript type EXPRESSION
+ * (e.g. `{ title: string; due?: string }`) — no alias, no name. It slots directly
+ * into the generated payload maps as `"<element>": <expr>;` (see modelTypes.ts).
+ *
+ * EDITOR CONTRACT: the author edits a VISIBLE, valid-standalone alias so Monaco
+ * type-checks it as a real type (not a statement block):
+ *
+ *   type Payload = {
+ *     title: string;
+ *   };
+ *
+ * On save we strip the `type Payload =` wrapper (and optional trailing `;`) and
+ * store the inner expression; on load we re-wrap it. The fixed alias name
+ * (`Payload`) keeps extraction a deterministic prefix-strip — no AST parse, no
+ * name handling.
+ */
+/** The fixed alias name the Type editor wraps the payload expression in. */
+export const PLAY_TYPE_ALIAS = 'Payload';
+/** Matches a leading `type Payload =` wrapper, tolerating whitespace. */
+const ALIAS_PREFIX_RE = new RegExp(`^type\\s+${PLAY_TYPE_ALIAS}\\s*=\\s*`);
+/** Strip `//` line and `/* *\/` block comments (so validation sees real code). */
+function stripComments(text) {
+    return text
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/(^|[^:])\/\/.*$/gm, '$1');
+}
+/**
+ * Wrap a stored bare type expression into the editable alias form. An empty/absent
+ * expression seeds an empty object body so the author has a valid starting point.
+ */
+export function wrapPlayType(expr) {
+    const body = (expr ?? '').trim();
+    if (body.length === 0) {
+        return `type ${PLAY_TYPE_ALIAS} = {\n  \n};\n`;
+    }
+    return `type ${PLAY_TYPE_ALIAS} = ${body};\n`;
+}
+/**
+ * Validate the Type editor buffer and extract the bare expression.
+ *
+ * Lightweight guard (as requested): the buffer MUST declare `type Payload = …`.
+ * We do NOT deep-validate the body — Monaco already type-checks it live. An empty
+ * body (`type Payload = {}` with nothing meaningful, or a blank buffer) resolves
+ * to `undefined` so absence ⇒ the permissive payload fallback.
+ */
+export function parsePlayType(buffer) {
+    const code = stripComments(buffer).trim();
+    // A fully blank buffer ⇒ no declared type (permissive fallback).
+    if (code.length === 0)
+        return { ok: true, value: undefined };
+    if (!ALIAS_PREFIX_RE.test(code)) {
+        return {
+            ok: false,
+            error: `The type must be declared as \`type ${PLAY_TYPE_ALIAS} = …\`.`,
+        };
+    }
+    // Strip the wrapper and the optional trailing semicolon.
+    const inner = code.replace(ALIAS_PREFIX_RE, '').replace(/;\s*$/, '').trim();
+    // `type Payload =` with an empty / `{}` body ⇒ nothing declared (permissive).
+    if (inner.length === 0 || /^\{\s*\}$/.test(inner)) {
+        return { ok: true, value: undefined };
+    }
+    return { ok: true, value: inner };
+}
+/**
+ * A prefill for the Type editor, element-type-aware so the author gets a sensible
+ * starting shape. Returns the WRAPPED alias form (what the editor shows).
+ */
+export function prefillPlayType(elementType) {
+    switch (elementType) {
+        case 'command':
+            return `type ${PLAY_TYPE_ALIAS} = {\n  // the fields this command carries\n  id: string;\n};\n`;
+        case 'event':
+            return `type ${PLAY_TYPE_ALIAS} = {\n  // the facts this event records\n  id: string;\n};\n`;
+        case 'information':
+            return `type ${PLAY_TYPE_ALIAS} = {\n  // the stored shape of this information\n  id: string;\n};\n`;
+        case 'ui':
+            return `type ${PLAY_TYPE_ALIAS} = {\n  // the input this screen captures\n};\n`;
+        default:
+            return wrapPlayType(undefined);
+    }
+}
+/** Which element types support an author-defined payload type (Type editor shown). */
+export function hasPlayType(elementType) {
+    return (elementType === 'command' ||
+        elementType === 'event' ||
+        elementType === 'information' ||
+        elementType === 'ui');
+}
+//# sourceMappingURL=playType.js.map

package/dist/playFunction/playType.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playType.js","sourceRoot":"","sources":["../../src/playFunction/playType.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC;AAEzC,yEAAyE;AACzE,MAAM,eAAe,GAAG,IAAI,MAAM,CAAC,YAAY,eAAe,WAAW,CAAC,CAAC;AAE3E,kFAAkF;AAClF,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAI;SACR,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC;SAChC,OAAO,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAwB;IACnD,MAAM,IAAI,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,QAAQ,eAAe,gBAAgB,CAAC;IACjD,CAAC;IACD,OAAO,QAAQ,eAAe,MAAM,IAAI,KAAK,CAAC;AAChD,CAAC;AAOD;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAE1C,iEAAiE;IACjE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAE7D,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,uCAAuC,eAAe,SAAS;SACvE,CAAC;IACJ,CAAC;IAED,yDAAyD;IACzD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAE5E,8EAA8E;IAC9E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACxC,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,WAAmB;IACjD,QAAQ,WAAW,EAAE,CAAC;QACpB,KAAK,SAAS;YACZ,OAAO,QAAQ,eAAe,iEAAiE,CAAC;QAClG,KAAK,OAAO;YACV,OAAO,QAAQ,eAAe,8DAA8D,CAAC;QAC/F,KAAK,aAAa;YAChB,OAAO,QAAQ,eAAe,sEAAsE,CAAC;QACvG,KAAK,IAAI;YACP,OAAO,QAAQ,eAAe,iDAAiD,CAAC;QAClF;YACE,OAAO,YAAY,CAAC,SAAS,CAAC,CAAC;IACnC,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,WAAW,CAAC,WAAmB;IAC7C,OAAO,CACL,WAAW,KAAK,SAAS;QACzB,WAAW,KAAK,OAAO;QACvB,WAAW,KAAK,aAAa;QAC7B,WAAW,KAAK,IAAI,CACrB,CAAC;AACJ,CAAC"}

package/dist/playFunction/runtimeFold.d.ts

@@ -0,0 +1,51 @@
+/**
+ * runtimeFold — the pure, environment-independent Exploration fold that executes
+ * AUTHORED play functions (4b), falling back to the built-in defaults (R11) when
+ * an element has no `playFunction`.
+ *
+ * This is deliberately NOT a hook and touches no DOM/worker API, so it is:
+ *   - unit-testable directly (the Web Worker can't be exercised under jsdom), and
+ *   - usable both inside the Worker (handlerWorker.ts) and on the main-thread
+ *     synchronous fast-path (when no element has a playFunction).
+ *
+ * Contract parity: with no authored handlers this reproduces `runReplay`'s exact
+ * default behaviour (so the M1–M3 runtime contract/tests still hold). Authored
+ * handlers extend it with: six handler kinds (interact/decide/apply/read/react/
+ * process), ordered multi-event commands, sequential apply, two-level leaf-replace
+ * merge, non-object Information shapes (via apply), deterministic clock + uuid(),
+ * the per-step cascade budget, and reject().
+ *
+ * Handler sources arrive PRE-TRANSPILED (TS→JS done by the caller/worker), so the
+ * fold stays synchronous. Compilation (`new Function`) is cached per source.
+ */
+import { Chapter } from '../types/eventModel.js';
+import { ImplicitScenario, RuntimeResultV2 } from '../types/exploration.js';
+import { RuntimeStep } from './runtimeSteps.js';
+import { CascadeLimits } from './cascadeBudget.js';
+import { PlaySource } from './playLog.js';
+/** Pre-transpiled handler sources keyed by element id (JS, type-erased). */
+export type TranspiledHandlers = Record<string, string>;
+export interface FoldInput {
+    chapter: Chapter;
+    steps: RuntimeStep[];
+    scenario: ImplicitScenario;
+    playheadIndex: number;
+    /** Per-step live/collected UI input (R25), keyed by step index. */
+    liveStorage?: Record<number, Record<string, unknown>>;
+    /** element.id → transpiled JS handler source. Absent id ⇒ use default. */
+    handlers: TranspiledHandlers;
+    cascadeLimits?: CascadeLimits;
+    /** Which thread this fold runs on — tags debug logs ([Play] vs [PlayWorker]). */
+    logSource?: PlaySource;
+}
+/** Test seam. */
+export declare function __clearCompiledCache(): void;
+/** Does any element in the chapter carry an authored play function? */
+export declare function hasAnyPlayFunction(chapter: Chapter | undefined): boolean;
+/**
+ * Run the authored-handler fold. Pure: `(input) → RuntimeResultV2`.
+ */
+export declare function runFold(input: FoldInput): RuntimeResultV2;
+/** Convenience: derive steps + run the fold in one call (used by the worker). */
+export declare function foldChapter(chapter: Chapter | undefined, scenario: ImplicitScenario, playheadIndex: number, handlers: TranspiledHandlers, liveStorage?: Record<number, Record<string, unknown>>, cascadeLimits?: CascadeLimits, logSource?: PlaySource): RuntimeResultV2;
+//# sourceMappingURL=runtimeFold.d.ts.map

package/dist/playFunction/runtimeFold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeFold.d.ts","sourceRoot":"","sources":["../../src/playFunction/runtimeFold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,OAAO,EAAW,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAKhB,eAAe,EAGhB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAIL,WAAW,EAEZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAiE,aAAa,EAA0B,MAAM,oBAAoB,CAAC;AAS1I,OAAO,EAAkB,UAAU,EAAE,MAAM,cAAc,CAAC;AAS1D,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAExD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACtD,0EAA0E;IAC1E,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,iFAAiF;IACjF,SAAS,CAAC,EAAE,UAAU,CAAC;CACxB;AAaD,iBAAiB;AACjB,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAGxE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,eAAe,CA4iBzD;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CACzB,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,QAAQ,EAAE,gBAAgB,EAC1B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,kBAAkB,EAC5B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACrD,aAAa,CAAC,EAAE,aAAa,EAC7B,SAAS,CAAC,EAAE,UAAU,GACrB,eAAe,CAOjB"}