@proophboard/exploration-runtime 0.0.0-stage → 0.1.0

package/dist/playFunction/clock.js

@@ -0,0 +1,104 @@
+/**
+ * clock — the deterministic system clock + helpers for Exploration handlers
+ * (Exploration R31, R32, draft §4.5.1).
+ *
+ * Reproducibility is anchored by ONE human-meaningful system clock: a fixed base
+ * datetime (from scenario initial state, defaulting to run-start `now()`). All
+ * non-deterministic helpers read from it, never the wall clock, so the same
+ * scenario + model yields identical events, IDs, and timestamps on every replay.
+ *
+ *   now()               → the clock's CURRENT value (base + ticks/advances so far)
+ *   today()             → 'YYYY-MM-DD' derived from the same clock
+ *   uuid()              → deterministic sequence seeded from the clock + call index
+ *   advanceClock(dur)   → move the clock explicitly (opt-in, "3 days later")
+ *
+ * The clock AUTO-TICKS a small fixed amount per produced event by default (A), so
+ * each event's timestamp is distinct and increases with index with zero modeler
+ * effort; `advanceClock` (B) is the opt-in for scenarios that are *about* elapsed
+ * time.
+ *
+ * This module is pure/stateful-by-instance (no globals): the fold creates one
+ * `DeterministicClock` per replay and injects its helper surface into handlers.
+ */
+/** Milliseconds the clock auto-advances per produced event (default tick). */
+export const AUTO_TICK_MS = 1000;
+/** Parse a duration like '1h', '30m', '2d', '45s', '500ms' into milliseconds. */
+export function parseDuration(duration) {
+    if (typeof duration === 'number')
+        return duration;
+    const m = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)\s*$/.exec(duration);
+    if (!m) {
+        throw new Error(`advanceClock: invalid duration "${duration}" (use e.g. "30s", "15m", "2h", "3d", "500ms")`);
+    }
+    const value = parseFloat(m[1]);
+    const unit = m[2];
+    const factor = unit === 'ms' ? 1 :
+        unit === 's' ? 1000 :
+            unit === 'm' ? 60000 :
+                unit === 'h' ? 3600000 :
+                    /* 'd' */ 86400000;
+    return Math.round(value * factor);
+}
+export class DeterministicClock {
+    /**
+     * @param baseISO fixed base datetime (ISO). Defaults to wall-clock now() only
+     *   at construction — callers should pass the scenario clock for reproducibility.
+     */
+    constructor(baseISO) {
+        this.uuidCounter = 0;
+        const parsed = baseISO ? Date.parse(baseISO) : Date.now();
+        this.currentMs = Number.isNaN(parsed) ? Date.now() : parsed;
+    }
+    /** Current clock value as ISO string. */
+    now() {
+        return new Date(this.currentMs).toISOString();
+    }
+    /** Current clock date as 'YYYY-MM-DD'. */
+    today() {
+        return new Date(this.currentMs).toISOString().slice(0, 10);
+    }
+    /**
+     * Deterministic UUID (v4-shaped) seeded from the clock value + call index, so
+     * the Nth uuid() in a replay is always identical. NOT random.
+     */
+    uuid() {
+        const seed = `${this.currentMs}-${this.uuidCounter++}`;
+        // Deterministic 128-bit-ish hex from the seed via a simple xorshift fill.
+        let h = 0x811c9dc5;
+        const bytes = [];
+        for (let i = 0; i < 16; i++) {
+            for (let j = 0; j < seed.length; j++) {
+                h ^= seed.charCodeAt(j) + i * 131;
+                h = Math.imul(h, 0x01000193) >>> 0;
+            }
+            bytes.push(h & 0xff);
+        }
+        const hex = bytes.map((b) => b.toString(16).padStart(2, '0'));
+        // Shape as a v4 UUID (version/variant nibbles fixed for familiarity).
+        hex[6] = (parseInt(hex[6], 16) & 0x0f | 0x40).toString(16).padStart(2, '0');
+        hex[8] = (parseInt(hex[8], 16) & 0x3f | 0x80).toString(16).padStart(2, '0');
+        return (hex.slice(0, 4).join('') + '-' +
+            hex.slice(4, 6).join('') + '-' +
+            hex.slice(6, 8).join('') + '-' +
+            hex.slice(8, 10).join('') + '-' +
+            hex.slice(10, 16).join(''));
+    }
+    /** Auto-tick: advance by the default per-event amount. Called by the fold. */
+    tick() {
+        this.currentMs += AUTO_TICK_MS;
+    }
+    /** Opt-in explicit advance (R32). Exposed to handlers as advanceClock(). */
+    advanceClock(duration) {
+        this.currentMs += parseDuration(duration);
+    }
+    /** The handler-facing helper surface (bound to this instance). */
+    surface() {
+        return {
+            now: () => this.now(),
+            today: () => this.today(),
+            uuid: () => this.uuid(),
+            advanceClock: (d) => this.advanceClock(d),
+        };
+    }
+}
+//# sourceMappingURL=clock.js.map

package/dist/playFunction/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/playFunction/clock.ts"],"names":[],"mappings":"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"}

package/dist/playFunction/modelTypes.d.ts

@@ -0,0 +1,74 @@
+/**
+ * modelTypes — generate a per-chapter `.d.ts` for the Play Function Monaco editor
+ * so authored handlers get MODEL-DERIVED autocomplete and checking, inferred from
+ * the current chapter (no schema parsing yet — just names/contexts/keys):
+ *
+ *   • CommandName — a union of every command element name in the chapter.
+ *   • EventName   — a union of every event element name.
+ *   • ContextName — a union of every context used by any element.
+ *   • RuntimeState projection keys — for each Information element, a typed path
+ *     `state.<ContextKey>.<ElementKey>` (keys via toClassName), so the editor
+ *     autocompletes `state.TodoManagement.Todo` and stops flagging the hops.
+ *   • Name-keyed PAYLOAD maps — for each command/event/ui/information element that
+ *     declares a `playType`, a member in CommandPayloads/EventPayloads/UiInputs (or
+ *     the Information projection shape). The base dts looks these up by `.name` to
+ *     narrow `RuntimeCommand.payload` / `RuntimeEvent(Input).payload` / interact's
+ *     `storage`; an element without a `playType` is absent from the map and falls
+ *     back to the permissive payload (`Record<string, unknown>` / `any`).
+ *
+ * This MERGES with the static base dts (`ambientTypes.ts`) via TypeScript
+ * declaration merging:
+ *   - a second `interface RuntimeState { … }` adds the known projection keys on
+ *     top of the base's `$events` + `[context: string]: any` index signature, so
+ *     unknown keys still resolve to `any`.
+ *   - `CommandName` / `EventName` / `ContextName` are STRICT literal unions of the
+ *     modeled names. The base dts wires them into `RuntimeCommand.name`,
+ *     `RuntimeEventInput.name`, `RuntimeEvent.name` and the `.context` fields, so
+ *     a typo'd/unknown name is flagged by the editor (the deliberate trade-off:
+ *     catch mistakes over accepting arbitrary strings). Draw the element first,
+ *     then its handler — authoring a new element extends the union.
+ *
+ * Pure: `buildModelDts(chapter) → string`. Registered under its own stable extra-
+ * lib path and refreshed whenever the chapter's command/event/information shape
+ * changes.
+ */
+import type { Chapter, Element } from '../types/eventModel.js';
+/** Virtual file name the model extraLib is registered under (stable for dedupe). */
+export declare const MODEL_TYPES_PATH = "ts:exploration-model.d.ts";
+/**
+ * Build the per-chapter model dts. Returns a `declare global { … } export {};`
+ * block that merges with the base ambient types.
+ */
+export declare function buildModelDts(chapter: Chapter | undefined): string;
+/**
+ * Virtual file name the PER-ELEMENT extraLib is registered under. Stable across
+ * element switches (the content changes; the path stays) so Monaco replaces
+ * rather than accumulates it.
+ */
+export declare const PER_ELEMENT_TYPES_PATH = "ts:exploration-element.d.ts";
+/**
+ * Build the per-element `.d.ts` for the Play Function editor. Its job is to
+ * declare the handlers whose parameter type depends on WHICH element is being
+ * edited, pinned to THAT element's declared payload so the author gets a typed
+ * parameter WITHOUT a `.name` guard:
+ *
+ *   • interact(storage) — storage pinned to this UI element's input (UiInputs[name])
+ *   • decide(command)   — command pinned to this command element (name + payload)
+ *   • apply(event)      — event pinned to this event element (name + payload)
+ *
+ * These are declared HERE (not in the base ambient dts) so each parameter can vary
+ * per element without a duplicate-identifier clash. A handler authored on a command
+ * element gets a `decide` whose `command.payload` is exactly this command's declared
+ * type — it does NOT matter whether other (untyped) commands exist, because the
+ * parameter is the single element's type, not the `RuntimeCommand` union.
+ *
+ * The payload lookup uses the ELEMENT NAME as the key (matching CommandPayloads /
+ * EventPayloads / UiInputs in buildModelDts). When the element declares no
+ * `playType`, the name is absent from the map, so we fall back to the permissive
+ * `Record<string, unknown>` rather than emitting `Map["<name>"]` (which would error
+ * on a missing key). For element types that don't match a given handler, that
+ * handler's parameter falls back to the generic runtime union so the global surface
+ * stays complete regardless of the edited element.
+ */
+export declare function buildPerElementDts(element: Pick<Element, 'type' | 'name' | 'playType'> | undefined): string;
+//# sourceMappingURL=modelTypes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"modelTypes.d.ts","sourceRoot":"","sources":["../../src/playFunction/modelTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAG/D,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAwE5D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAwKlE;AAGD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,gCAAgC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC,GAAG,SAAS,GAC/D,MAAM,CAoDR"}

package/dist/playFunction/modelTypes.js

@@ -0,0 +1,345 @@
+/**
+ * modelTypes — generate a per-chapter `.d.ts` for the Play Function Monaco editor
+ * so authored handlers get MODEL-DERIVED autocomplete and checking, inferred from
+ * the current chapter (no schema parsing yet — just names/contexts/keys):
+ *
+ *   • CommandName — a union of every command element name in the chapter.
+ *   • EventName   — a union of every event element name.
+ *   • ContextName — a union of every context used by any element.
+ *   • RuntimeState projection keys — for each Information element, a typed path
+ *     `state.<ContextKey>.<ElementKey>` (keys via toClassName), so the editor
+ *     autocompletes `state.TodoManagement.Todo` and stops flagging the hops.
+ *   • Name-keyed PAYLOAD maps — for each command/event/ui/information element that
+ *     declares a `playType`, a member in CommandPayloads/EventPayloads/UiInputs (or
+ *     the Information projection shape). The base dts looks these up by `.name` to
+ *     narrow `RuntimeCommand.payload` / `RuntimeEvent(Input).payload` / interact's
+ *     `storage`; an element without a `playType` is absent from the map and falls
+ *     back to the permissive payload (`Record<string, unknown>` / `any`).
+ *
+ * This MERGES with the static base dts (`ambientTypes.ts`) via TypeScript
+ * declaration merging:
+ *   - a second `interface RuntimeState { … }` adds the known projection keys on
+ *     top of the base's `$events` + `[context: string]: any` index signature, so
+ *     unknown keys still resolve to `any`.
+ *   - `CommandName` / `EventName` / `ContextName` are STRICT literal unions of the
+ *     modeled names. The base dts wires them into `RuntimeCommand.name`,
+ *     `RuntimeEventInput.name`, `RuntimeEvent.name` and the `.context` fields, so
+ *     a typo'd/unknown name is flagged by the editor (the deliberate trade-off:
+ *     catch mistakes over accepting arbitrary strings). Draw the element first,
+ *     then its handler — authoring a new element extends the union.
+ *
+ * Pure: `buildModelDts(chapter) → string`. Registered under its own stable extra-
+ * lib path and refreshed whenever the chapter's command/event/information shape
+ * changes.
+ */
+import { toClassName } from '../lib/toClassName.js';
+/** Virtual file name the model extraLib is registered under (stable for dedupe). */
+export const MODEL_TYPES_PATH = 'ts:exploration-model.d.ts';
+/** Distinct, sorted display names of a given element type. */
+function distinctNames(chapter, type) {
+    const set = new Set();
+    for (const el of chapter.elements) {
+        if (el.type === type && el.name.trim().length > 0)
+            set.add(el.name);
+    }
+    return [...set].sort();
+}
+/** Distinct, sorted contexts across all elements (defaulting empty → 'App'). */
+function distinctContexts(chapter) {
+    const set = new Set();
+    for (const el of chapter.elements)
+        set.add(el.context || 'App');
+    return [...set].sort();
+}
+/**
+ * A STRICT string-literal union of the modeled names: `"A" | "B"`. Unknown names
+ * (typos, or names not yet drawn) are flagged by the editor — the deliberate
+ * trade-off for catching mistakes. Falls back to `string` only when there are NO
+ * names, so an empty/early chapter doesn't error on every annotation.
+ *
+ * (We previously used `… | (string & {})` to also accept arbitrary strings, but
+ * that silently allowed typos — the opposite of what authors want here. In Event
+ * Modeling you draw the element first, then write its handler, so an unknown name
+ * is almost always a typo. Author a new element to extend the union.)
+ */
+function nameUnion(names) {
+    if (names.length === 0)
+        return 'string';
+    return names.map((n) => JSON.stringify(n)).join(' | ');
+}
+/**
+ * Collect `element.name → playType` for every element of `type` whose `playType`
+ * is a non-empty string. The display NAME is the key (it is the discriminant used
+ * by RuntimeCommand/RuntimeEventInput/RuntimeEvent `.name`), so a declared payload
+ * narrows on `.name`. Last-write-wins on duplicate names (sorted for stability).
+ */
+function payloadsByName(chapter, type) {
+    const map = new Map();
+    for (const el of chapter.elements) {
+        if (el.type !== type)
+            continue;
+        const name = el.name.trim();
+        const expr = el.playType?.trim();
+        if (name.length === 0 || !expr)
+            continue;
+        map.set(name, expr);
+    }
+    return map;
+}
+/**
+ * Emit a name-keyed payload interface (`interface <Name> { "<element>": <type>; }`)
+ * from a display-name → type-expression map, or `null` when the map is empty (so
+ * callers can omit the block entirely and let the permissive fallback apply).
+ *
+ * Members are quoted display names (they contain spaces), each mapped to the
+ * author's verbatim `playType` expression. The interface is intentionally CLOSED
+ * (no index signature): the ambient wiring looks a name up and falls back to the
+ * permissive payload when the name is absent, so undeclared names stay permissive
+ * WITHOUT every map needing an `any` catch-all (which would defeat the narrowing).
+ */
+function payloadInterface(name, byName, doc) {
+    if (byName.size === 0)
+        return null;
+    const members = [...byName.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([elName, expr]) => `    ${JSON.stringify(elName)}: ${expr};`)
+        .join('\n');
+    return `  /** ${doc} */\n  interface ${name} {\n${members}\n  }\n`;
+}
+/**
+ * Build the per-chapter model dts. Returns a `declare global { … } export {};`
+ * block that merges with the base ambient types.
+ */
+export function buildModelDts(chapter) {
+    if (!chapter) {
+        // Minimal, still-valid aliases so references don't error on an empty editor.
+        return `declare global {
+  /** Command names in this chapter (none yet). */
+  type CommandName = string;
+  /** Event names in this chapter (none yet). */
+  type EventName = string;
+  /** Contexts in this chapter (none yet). */
+  type ContextName = string;
+  /** Declared command payloads (none yet). */
+  interface CommandPayloads {}
+  /** Declared event payloads (none yet). */
+  interface EventPayloads {}
+  /** Declared UI input shapes (none yet). */
+  interface UiInputs {}
+  /** The return shape of \`apply\` (none modeled yet — any object). */
+  type ProjectionPatch = Record<string, Record<string, unknown>>;
+}
+export {};
+`;
+    }
+    const commandNames = distinctNames(chapter, 'command');
+    const eventNames = distinctNames(chapter, 'event');
+    const contexts = distinctContexts(chapter);
+    // Build nested projection shape grouped by context className → element className.
+    // Each element carries its declared `playType` (the STORED projection shape) when
+    // present, else null (⇒ permissive `any`/`unknown`). This single structure feeds
+    // both the RuntimeState augmentation and the ProjectionPatch return type.
+    const projByCtx = new Map();
+    for (const el of chapter.elements) {
+        if (el.type !== 'information')
+            continue;
+        const ctxKey = toClassName(el.context || 'App');
+        const elKey = toClassName(el.name);
+        if (!ctxKey || !elKey)
+            continue;
+        if (!projByCtx.has(ctxKey))
+            projByCtx.set(ctxKey, new Map());
+        const shape = el.playType?.trim();
+        projByCtx.get(ctxKey).set(elKey, shape && shape.length > 0 ? shape : null);
+    }
+    // Each known Information projection is typed by its declared `playType` (the
+    // stored shape) when the modeler provided one, else `any` so handlers can
+    // deep-access objects AND spread/iterate list projections (e.g. `[...state.Ctx.List]`)
+    // without a cast; the base index signature covers unknown keys.
+    const projectionMembers = [...projByCtx.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([ctxKey, elKeys]) => {
+        const members = [...elKeys.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([elKey, shape]) => `    /** Projection: state.${ctxKey}.${elKey} (${shape ? 'declared shape' : 'object, list, or scalar'}) */\n    ${elKey}: ${shape ?? 'any'};`)
+            .join('\n');
+        return `  /** Context "${ctxKey}" projections. */\n  ${ctxKey}: {\n${members}\n    [element: string]: any;\n  };`;
+    })
+        .join('\n');
+    // Namespace RuntimeState — mirrors the interface augmentation so authors can
+    // write `type Payload = RuntimeState.TodoManagement.Todo` in the Type editor
+    // (and in Function handlers). Namespace members use the same shape as the
+    // interface: declared `playType` when present, else `any` (permissive).
+    // Each context-level namespace also carries a catch-all `[element: string]: any`
+    // so undeclared element names resolve to `any` rather than error.
+    const namespaceParts = [...projByCtx.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([ctxKey, elKeys]) => {
+        const members = [...elKeys.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([elKey, shape]) => `      type ${elKey} = ${shape ?? 'any'};`)
+            .join('\n');
+        return `    namespace ${ctxKey} {\n${members}\n    }`;
+    })
+        .join('\n');
+    const stateNamespace = namespaceParts
+        ? `  /**
+   * Namespace mirror of RuntimeState projections. Allows dotted-path type
+   * references in the Type editor:  type Payload = RuntimeState.TodoManagement.Todo
+   */
+  namespace RuntimeState {
+${namespaceParts}
+  }
+`
+        : '';
+    const stateAugment = projectionMembers
+        ? `  /**
+   * Model-derived projection keys (from this chapter's Information elements).
+   * Merges with the base RuntimeState: known contexts/elements autocomplete,
+   * unknown keys still resolve to \`any\` via the base index signature. Where an
+   * Information element declares a payload type, its projection is strictly typed.
+   */
+  interface RuntimeState {
+${projectionMembers}
+  }
+${stateNamespace}`
+        : '';
+    // ProjectionPatch — the typed return of `apply`. Shape: a PARTIAL map of known
+    // contexts → PARTIAL map of that context's known Information elements → patch
+    // VALUE. The value is the element's declared `playType` when present (so a typed
+    // patch is checked field-by-field), else `unknown` (object, list, or scalar — R13
+    // replaces lists/scalars wholesale, leaf-merges objects), so only the context/
+    // element KEY names are checked. Being `Partial` lets a handler write any subset;
+    // the absence of an inner index signature means a typo'd key is flagged by the
+    // excess-property check on the returned object literal. Falls back to a permissive
+    // map when no Information is modeled.
+    const patchContexts = [...projByCtx.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([ctxKey, elKeys]) => {
+        const members = [...elKeys.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([elKey, shape]) => `    ${elKey}?: ${shape ? `Partial<${shape}>` : 'unknown'};`)
+            .join('\n');
+        return `  ${ctxKey}?: {\n${members}\n  };`;
+    })
+        .join('\n');
+    const projectionPatchType = patchContexts
+        ? `  /**
+   * The return shape of \`apply\`. Known contexts/elements are checked — a typo'd
+   * context or Information name is flagged. Every key is optional (write a subset).
+   */
+  interface ProjectionPatch {
+${patchContexts}
+  }
+`
+        : `  /** The return shape of \`apply\` (no Information modeled yet — any object). */
+  type ProjectionPatch = Record<string, Record<string, unknown>>;
+`;
+    // Name-keyed payload maps (display name → declared `playType`). Each is emitted
+    // as an interface the base ambient dts references to narrow `.payload`/`storage`
+    // by `.name`. An element WITHOUT a `playType` is simply absent from the map, so
+    // the ambient wiring's conditional lookup falls back to the permissive payload.
+    // We ALWAYS emit the interface (empty when nothing is declared) so the base dts
+    // can reference it unconditionally — an empty interface narrows nothing, which is
+    // exactly the permissive fallback.
+    const commandPayloads = payloadInterface('CommandPayloads', payloadsByName(chapter, 'command'), "Declared command payloads, keyed by command name. Narrows RuntimeCommand.payload on `.name`.")
+        ?? `  /** Declared command payloads (none yet). */\n  interface CommandPayloads {}\n`;
+    const eventPayloads = payloadInterface('EventPayloads', payloadsByName(chapter, 'event'), "Declared event payloads, keyed by event name. Narrows RuntimeEvent(Input).payload on `.name`.")
+        ?? `  /** Declared event payloads (none yet). */\n  interface EventPayloads {}\n`;
+    const uiInputs = payloadInterface('UiInputs', payloadsByName(chapter, 'ui'), "Declared UI input shapes, keyed by UI element name. Pins interact's `storage` per element.")
+        ?? `  /** Declared UI input shapes (none yet). */\n  interface UiInputs {}\n`;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- doc only
+    return `declare global {
+  /** Command names authored in this chapter. Unknown names are flagged (typos). */
+  type CommandName = ${nameUnion(commandNames)};
+
+  /** Event names authored in this chapter. Unknown names are flagged (typos). */
+  type EventName = ${nameUnion(eventNames)};
+
+  /** Contexts used in this chapter. Unknown contexts are flagged (typos). */
+  type ContextName = ${nameUnion(contexts)};
+
+${commandPayloads}
+${eventPayloads}
+${uiInputs}
+${projectionPatchType}
+${stateAugment}}
+export {};
+`;
+}
+/**
+ * Virtual file name the PER-ELEMENT extraLib is registered under. Stable across
+ * element switches (the content changes; the path stays) so Monaco replaces
+ * rather than accumulates it.
+ */
+export const PER_ELEMENT_TYPES_PATH = 'ts:exploration-element.d.ts';
+/**
+ * Build the per-element `.d.ts` for the Play Function editor. Its job is to
+ * declare the handlers whose parameter type depends on WHICH element is being
+ * edited, pinned to THAT element's declared payload so the author gets a typed
+ * parameter WITHOUT a `.name` guard:
+ *
+ *   • interact(storage) — storage pinned to this UI element's input (UiInputs[name])
+ *   • decide(command)   — command pinned to this command element (name + payload)
+ *   • apply(event)      — event pinned to this event element (name + payload)
+ *
+ * These are declared HERE (not in the base ambient dts) so each parameter can vary
+ * per element without a duplicate-identifier clash. A handler authored on a command
+ * element gets a `decide` whose `command.payload` is exactly this command's declared
+ * type — it does NOT matter whether other (untyped) commands exist, because the
+ * parameter is the single element's type, not the `RuntimeCommand` union.
+ *
+ * The payload lookup uses the ELEMENT NAME as the key (matching CommandPayloads /
+ * EventPayloads / UiInputs in buildModelDts). When the element declares no
+ * `playType`, the name is absent from the map, so we fall back to the permissive
+ * `Record<string, unknown>` rather than emitting `Map["<name>"]` (which would error
+ * on a missing key). For element types that don't match a given handler, that
+ * handler's parameter falls back to the generic runtime union so the global surface
+ * stays complete regardless of the edited element.
+ */
+export function buildPerElementDts(element) {
+    const name = element?.name ?? '';
+    const hasType = typeof element?.playType === 'string' && element.playType.trim().length > 0;
+    const nameLit = JSON.stringify(name);
+    // interact → this UI element's input shape (else permissive).
+    const storageType = element?.type === 'ui' && hasType ? `UiInputs[${nameLit}]` : 'Record<string, unknown>';
+    // decide → this command element pinned to its own name + payload (else generic union).
+    const commandType = element?.type === 'command'
+        ? `{ name: ${nameLit}; context: ContextName; payload: ${hasType ? `CommandPayloads[${nameLit}]` : 'Record<string, unknown>'} }`
+        : 'RuntimeCommand';
+    // apply → this event element pinned to its own name + payload (else generic union).
+    const eventType = element?.type === 'event'
+        ? `{ name: ${nameLit}; context: ContextName; payload: ${hasType ? `EventPayloads[${nameLit}]` : 'Record<string, unknown>'}; index: number; timestamp: string }`
+        : 'RuntimeEvent';
+    return `declare global {
+  /**
+   * The captured UI input shape for the element currently being edited. Pinned to
+   * this UI element's declared payload type when it has one, else permissive.
+   */
+  type ThisUiStorage = ${storageType};
+
+  /**
+   * This command, pinned to the edited command element's name + declared payload,
+   * so \`command.payload\` is typed directly — no \`.name\` guard needed.
+   */
+  type ThisCommand = ${commandType};
+
+  /**
+   * This event, pinned to the edited event element's name + declared payload, so
+   * \`event.payload\` is typed directly — no \`.name\` guard needed.
+   */
+  type ThisEvent = ${eventType};
+
+  /** UI handler: collected input + state → commands. \`storage\` is this element's input shape. */
+  function interact(storage: ThisUiStorage, state: RuntimeState): RuntimeCommand[];
+
+  /** Command handler: this command + state → events (or reject()). \`command\` is this element. */
+  function decide(command: ThisCommand, state: RuntimeState): RuntimeEventInput[];
+
+  /** Event handler: this event + state → projection patches. \`event\` is this element. */
+  function apply(event: ThisEvent, state: RuntimeState): ProjectionPatch;
+}
+export {};
+`;
+}
+//# sourceMappingURL=modelTypes.js.map

package/dist/playFunction/modelTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelTypes.js","sourceRoot":"","sources":["../../src/playFunction/modelTypes.ts"],"names":[],"mappings":"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"}

package/dist/playFunction/playLog.d.ts

@@ -0,0 +1,29 @@
+/**
+ * playLog — permanent, colored debug logging for the Exploration Play runtime.
+ *
+ * Two sources, tagged in every message:
+ *   [Play]        — main-thread orchestration (useExplorationRuntime / the worker
+ *                   hook lifecycle: fast-path vs worker, dispatch, resolve/settle).
+ *   [PlayWorker]  — work done inside the Web Worker AND the pure fold it runs
+ *                   (handler execution per kind, emitted events, pending commands,
+ *                   errors). The fold also runs on the main thread for the sync
+ *                   fast-path; there it logs under [Play] via the `source` arg.
+ *
+ * Coloring: each handler KIND gets its own color so a flow is scannable at a
+ * glance. Uses `%c` CSS styling, which both the window console and the
+ * DedicatedWorker console support. No-ops safely if `console` is unavailable.
+ *
+ * These logs are intentionally PERMANENT (not stripped in prod) — Exploration is
+ * a modeling/debugging surface where seeing the handler flow is the point.
+ */
+export type PlaySource = 'Play' | 'PlayWorker';
+/** The six handler kinds plus flow/event/error channels, each with a color. */
+export type PlayChannel = 'interact' | 'decide' | 'apply' | 'read' | 'react' | 'process' | 'event' | 'input' | 'pending' | 'flow' | 'error';
+/**
+ * Log one line. `source` tags the thread, `channel` picks the color/label.
+ * Extra args are passed through verbatim (objects stay inspectable in devtools).
+ */
+export declare function playLog(source: PlaySource, channel: PlayChannel, message: string, ...args: unknown[]): void;
+/** Convenience factory bound to a source, so call-sites read `log('decide', …)`. */
+export declare function makePlayLogger(source: PlaySource): (channel: PlayChannel, message: string, ...args: unknown[]) => void;
+//# sourceMappingURL=playLog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"playLog.d.ts","sourceRoot":"","sources":["../../src/playFunction/playLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,YAAY,CAAC;AAE/C,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GACnB,UAAU,GACV,QAAQ,GACR,OAAO,GACP,MAAM,GACN,OAAO,GACP,SAAS,GACT,OAAO,GACP,OAAO,GACP,SAAS,GACT,MAAM,GACN,OAAO,CAAC;AAyBZ;;;GAGG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,MAAM,EACf,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,IAAI,CAcN;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,IACvC,SAAS,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,OAAO,EAAE,UAElE"}

package/dist/playFunction/playLog.js

@@ -0,0 +1,64 @@
+/**
+ * playLog — permanent, colored debug logging for the Exploration Play runtime.
+ *
+ * Two sources, tagged in every message:
+ *   [Play]        — main-thread orchestration (useExplorationRuntime / the worker
+ *                   hook lifecycle: fast-path vs worker, dispatch, resolve/settle).
+ *   [PlayWorker]  — work done inside the Web Worker AND the pure fold it runs
+ *                   (handler execution per kind, emitted events, pending commands,
+ *                   errors). The fold also runs on the main thread for the sync
+ *                   fast-path; there it logs under [Play] via the `source` arg.
+ *
+ * Coloring: each handler KIND gets its own color so a flow is scannable at a
+ * glance. Uses `%c` CSS styling, which both the window console and the
+ * DedicatedWorker console support. No-ops safely if `console` is unavailable.
+ *
+ * These logs are intentionally PERMANENT (not stripped in prod) — Exploration is
+ * a modeling/debugging surface where seeing the handler flow is the point.
+ */
+/** Per-channel label color (hex; readable on both light and dark consoles). */
+const CHANNEL_COLOR = {
+    interact: '#8b5cf6', // violet  — UI
+    decide: '#2563eb', // blue    — command
+    apply: '#ea580c', // orange  — event projection
+    read: '#16a34a', // green   — information view
+    react: '#db2777', // pink    — automation reaction
+    process: '#c026d3', // fuchsia — automation job
+    event: '#f59e0b', // amber   — emitted event
+    input: '#0891b2', // cyan    — captured UI input ($input)
+    pending: '#0d9488', // teal    — deferred command
+    flow: '#64748b', // slate   — orchestration
+    error: '#dc2626', // red     — failure
+};
+/** Source badge background (so [Play] vs [PlayWorker] are distinguishable). */
+const SOURCE_BG = {
+    Play: '#1e293b', // slate-800
+    PlayWorker: '#312e81', // indigo-900
+};
+const hasConsole = typeof console !== 'undefined';
+/**
+ * Log one line. `source` tags the thread, `channel` picks the color/label.
+ * Extra args are passed through verbatim (objects stay inspectable in devtools).
+ */
+export function playLog(source, channel, message, ...args) {
+    if (!hasConsole)
+        return;
+    const color = CHANNEL_COLOR[channel];
+    const srcBg = SOURCE_BG[source];
+    // Two styled segments: a source badge, then a colored channel label.
+    const prefix = `%c[${source}]%c ${channel}`;
+    const srcStyle = `background:${srcBg};color:#fff;padding:1px 4px;border-radius:3px;font-weight:600`;
+    const chStyle = `color:${color};font-weight:600`;
+    try {
+        // eslint-disable-next-line no-console
+        console.log(prefix, srcStyle, chStyle, message, ...args);
+    }
+    catch {
+        /* no-op: never let logging break the runtime */
+    }
+}
+/** Convenience factory bound to a source, so call-sites read `log('decide', …)`. */
+export function makePlayLogger(source) {
+    return (channel, message, ...args) => playLog(source, channel, message, ...args);
+}
+//# sourceMappingURL=playLog.js.map