@jarenjs/play 0.34.0

package/README.md

@@ -0,0 +1,55 @@
+# @jarenjs/play
+
+**A JSON-engine playground — understand an engine before you compose it.**
+
+Pick an engine (JSONPath, JSON Pointer, JSON Patch, `$query`, JSLT,
+markdown, mermaid, …), feed it a source input and one or more datasets from
+a curated example library, and watch it run. Where `@jarenjs/studio` is for
+building an application out of many files, `@jarenjs/play` is for
+learning one engine standalone — a reference bench you experiment on first.
+
+Two layers, the suite's convention:
+
+- **the engine** (`@jarenjs/play`) — headless: an engine registry, a
+  curated example library, and a pure `runExample(engineId, source, data)
+  → { ok, panels, timing, error }`. Wraps the real shipped compilers; knows
+  nothing of the DOM.
+- **the component** (`@jarenjs/play/component`) — the playground UI, a
+  `createPlayComponent()` factory (like `@jarenjs/calc`): a JSLT view
+  (example rail, source editors, a dataset switcher, the run stage) the
+  host composes.
+
+Play is a **student tool**: it opens calm — one clean result per run — and
+drills deeper on demand. An engine's rich explainers (match cards, the
+compiled program, a geometry-free AST, a canonical round-trip) are `deep`
+result panels behind a quiet **"Explain ▸"** depth toggle: revealed beside
+the answer on desktop, as a full-pane swap with a ← back on a phone.
+
+## The model
+
+An engine's inputs are heterogeneous — a selector needs one JSON document,
+a patch needs a target, markdown needs no data at all. Each engine is a
+**descriptor** (the panes it consumes + a pure `run`); each **example**
+presets those panes plus a **list of datasets**:
+
+```js
+{ engine: 'path',
+  source:   { selector: '$.store.book[*].title' },
+  datasets: [ { label: 'store',   data: { data: '{ … }' } },
+              { label: 'catalog', data: { data: '{ … }' } } ] }
+```
+
+The datasets list length is the whole story: **0** → the engine takes no
+data (markdown/mermaid); **1** → one dataset; **N** → a switcher that runs
+the *same* source over each shape. Adding an engine is a descriptor plus
+examples — the picker, panes and switcher all derive from the descriptor.
+See [docs/PLAY-FORMAT.md](docs/PLAY-FORMAT.md).
+
+## Install
+
+```
+npm install @jarenjs/play
+```
+
+Zero third-party runtime dependencies — only other `@jarenjs/*` packages.
+Node ≥ 24, ESM.

package/dist/types/component/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file The playground COMPONENT — `createPlayComponent(options)`, the
+ * suite's factory convention (like `@jarenjs/calc` / `@jarenjs/studio`). It
+ * hands the host the JSLT view (`rules` + `mode` + `modes`), the pure
+ * derivation (`viewModel`), and the headless engine surface its run loop
+ * binds (`runExample`, the registry, the example library). The reducer
+ * `play/*` actions and the debounced live-run are wired at the host.
+ */
+import { ENGINES, EXAMPLES, engineIds, runExample } from '../index.js';
+import { playViewModel } from './viewmodel.js';
+import { playRules, playModes, PLAY_MODE, PLAY_BASE } from './view.js';
+/**
+ * Build the playground component.
+ *
+ * The three host seams are configured ONCE here and become defaults for
+ * every `runExample` call the returned component makes; a per-call option
+ * of the same name still wins, so a caller can vary one run. Configuring
+ * them at the factory and having them silently ignored is the trap this
+ * shape exists to close — a host that registered its operator packs here
+ * would otherwise watch `$mean` and `$npv` go missing at run time.
+ *
+ * @param {{ operators?: { toOptions: () => any },
+ *   renderers?: Record<string, Function>, validate?: Function }} [options]
+ *   `operators` reaches the query/jslt engines, `renderers` the visual
+ *   engines (markdown/mermaid/charts/mdx), `validate` the JSON Schema one
+ */
+export declare function createPlayComponent(options?: {
+    operators?: {
+        toOptions: () => any;
+    };
+    renderers?: Record<string, Function>;
+    validate?: Function;
+}): {
+    mode: string;
+    rules: ({
+        match: string;
+        mode: string;
+        body: {
+            $if: (string | (string | {
+                class: string;
+            })[] | {
+                $if: (string | (string | (string | {}[] | {}[] | {
+                    class: string;
+                })[] | {
+                    class: string;
+                })[] | {
+                    $if: (string | (string | {
+                        class: string;
+                    })[] | {
+                        $if: (string | (string | {
+                            $apply: string;
+                        }[] | {
+                            class: string;
+                        })[] | (string | {}[] | {
+                            class: string;
+                        })[])[];
+                    })[];
+                })[];
+            })[];
+        };
+    } | {
+        match: string;
+        mode: string;
+        body: {}[];
+    })[];
+    modes: Readonly<{
+        play: {
+            unmatched: string;
+        };
+    }>;
+    viewModel: typeof playViewModel;
+    engines: Readonly<Record<string, import("../index.js").EngineDescriptor>>;
+    examples: readonly import("../index.js").PlayExample[];
+    engineIds: typeof engineIds;
+    runExample: (engineId: any, source: any, data: any, perCall?: {}) => import("../index.js").PlayResult;
+    operators: {
+        toOptions: () => any;
+    } | undefined;
+};
+export { playViewModel, playRules, playModes, PLAY_MODE, PLAY_BASE, ENGINES, EXAMPLES, engineIds, runExample, };

package/dist/types/component/view.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @file The playground as a JSLT view — the chrome is a document, rendered
+ * by the same engine as the rest of the suite. One `play` mode, rules
+ * matched by their ABSOLUTE slice path (`$.ui.play`), `$apply` and body
+ * references RELATIVE to the matched node. The host mounts the view model
+ * at `$.ui.play`. No imperative islands — the whole playground is data.
+ */
+/** The one mode this view uses. */
+export declare const PLAY_MODE = "play";
+/** The slice the host mounts the view model at. */
+export declare const PLAY_BASE = "$.ui.play";
+/** The modes the host merges into the site stylesheet. */
+export declare const playModes: Readonly<{
+    play: {
+        unmatched: string;
+    };
+}>;
+/** The playground's JSLT rules — spread into the site stylesheet. */
+export declare const playRules: ({
+    match: string;
+    mode: string;
+    body: {
+        $if: (string | (string | {
+            class: string;
+        })[] | {
+            $if: (string | (string | (string | {}[] | {}[] | {
+                class: string;
+            })[] | {
+                class: string;
+            })[] | {
+                $if: (string | (string | {
+                    class: string;
+                })[] | {
+                    $if: (string | (string | {
+                        $apply: string;
+                    }[] | {
+                        class: string;
+                    })[] | (string | {}[] | {
+                        class: string;
+                    })[])[];
+                })[];
+            })[];
+        })[];
+    };
+} | {
+    match: string;
+    mode: string;
+    body: {}[];
+})[];

package/dist/types/component/viewmodel.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {{ play?: any }} state
+ * @returns {any}
+ */
+export declare function playViewModel(state: {
+    play?: any;
+}): any;

package/dist/types/engines.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file The playground's engine descriptors — each wraps a real shipped
+ * `@jarenjs` compiler into a pure `run(source, data, options) → PlayResult`.
+ * `sourcePanes` are the engine input(s); `dataPanes` are the JSON it runs
+ * against (empty for source-only engines, which land in a later order).
+ * Registered operators reach the `query`/`jslt` engines through
+ * `options.operators` (a `.toOptions()` registry) — the host opt-in.
+ */
+/** @type {import('./index.js').EngineDescriptor[]} */
+export declare const ENGINE_LIST: import('./index.js').EngineDescriptor[];

package/dist/types/examples.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file The playground's curated example library — the canonical home for
+ * the suite's engine examples (folded from the website + more). Each
+ * example presets its engine's source pane(s) and a LIST of datasets: one
+ * dataset shows a single run; several turn on a switcher, so the same
+ * source runs over each shape (see the `-shapes` / `-inputs` examples).
+ */
+/** @type {import('./index.js').PlayExample[]} */
+export declare const EXAMPLE_LIST: import('./index.js').PlayExample[];

package/dist/types/format.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file Display formatting shared by the engine layer (the deep "how it
+ * ran" stat cards) and the component layer (the stage's timing line).
+ */
+/**
+ * A measured duration as a stage label. Anything that is not a number —
+ * including the `null` an engine reports for a phase it does not have, or
+ * one the host never measured — is an em dash rather than a fabricated
+ * `0`, which would read as "ran in no time" instead of "not measured".
+ * Sub-hundredth-millisecond work prints as a floor: two decimals is the
+ * resolution the cards claim, and `0.00 ms` would over-claim it.
+ * @param {unknown} ms
+ * @returns {string}
+ */
+export declare function formatMs(ms: unknown): string;

package/dist/types/index.d.ts

@@ -0,0 +1,272 @@
+/**
+ * @file `@jarenjs/play` — a JSON-engine playground. Pick an engine, feed
+ * it a source input and one or more datasets, and watch it run — a way to
+ * understand an engine standalone before composing it in the studio.
+ *
+ * The model (PLAY-FORMAT.md): each engine is a DESCRIPTOR — the panes it
+ * consumes (`sourcePanes` = the input; `dataPanes` = the JSON it runs
+ * against, possibly none) plus a pure `run`. Each EXAMPLE presets those
+ * source panes plus a LIST of datasets: 0 = the engine takes no data
+ * (markdown/mermaid), 1 = one dataset, N = a dataset switcher (the same
+ * source over several shapes). The engine registry and the example library
+ * fill in over the next orders; this is the headless core the component
+ * renders.
+ */
+export type EnginePane = {
+    /**
+     * - the pane's id (e.g. 'selector', 'data')
+     */
+    key: string;
+    label: string;
+    control?: 'code' | 'text';
+};
+export type OptionPane = {
+    key: string;
+    label: string;
+    choices: Array<{
+        value: string;
+        label: string;
+    }>;
+    /**
+     * - the value used until the user picks another
+     */
+    default: string;
+};
+export type Panel = {
+    /**
+     * - unique within the result (the tab key)
+     */
+    id: string;
+    /**
+     * - the tab label (defaults to `id`)
+     */
+    label?: string;
+    kind: 'code' | 'view' | 'table' | 'note' | 'cards';
+    /**
+     * - `deep` panels are the engine's rich
+     * explainers, hidden until the student drills in via the depth toggle;
+     * defaults to `simple` (the calm default view)
+     */
+    depth?: 'simple' | 'deep';
+    /**
+     * - `code` / `note`: the text body
+     */
+    text?: string;
+    /**
+     * - `view`: a host-rendered vnode, spliced verbatim
+     */
+    vnode?: any;
+    /**
+     * - `table`: the header labels
+     */
+    columns?: string[];
+    /**
+     * - `table`: cells, row-major
+     */
+    rows?: Array<Array<any>>;
+    /**
+     * - `note`: the callout tone
+     */
+    tone?: 'ok' | 'warn' | 'info';
+    /**
+     * `cards`: a row of stat cards (matches, compile/run timings, …)
+     */
+    items?: Array<{
+        title: string;
+        value: string;
+        note?: string;
+    }>;
+};
+export type PlayResult = {
+    ok: boolean;
+    timing: {
+        compileMs: number;
+        runMs: number;
+    } | null;
+    error: {
+        message: string;
+        code?: string;
+        path?: string;
+    } | null;
+    /**
+     * - the result screens (`[]` on error); a single
+     * `code` panel for most engines, several for the richer ones
+     */
+    panels: Panel[];
+};
+export type EngineDescriptor = {
+    id: string;
+    label: string;
+    /**
+     * - one line describing the engine
+     */
+    lead?: string;
+    /**
+     * - the engine INPUT pane(s)
+     */
+    sourcePanes: EnginePane[];
+    /**
+     * - the JSON it runs against (may be [])
+     */
+    dataPanes: EnginePane[];
+    /**
+     * - live mode selects (may be absent)
+     */
+    optionPanes?: OptionPane[];
+    run: (source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult;
+};
+export type RunOptions = {
+    /**
+     * - a host operator registry ({ toOptions() }) for query/jslt/jtlt
+     */
+    operators?: any;
+    /**
+     * - the current option-pane values
+     */
+    config?: Record<string, string>;
+    /**
+     * host-injected vnode renderers keyed by engine id — the visual engines
+     * (markdown/mermaid/charts) delegate their rendering here (the hybrid seam),
+     * so the package owns the descriptors + examples but stays dependency-light.
+     * A renderer receives the source text plus its second argument — the
+     * option-pane config for the visual engines, the PARSED data document for
+     * `mdx` — and returns the preview vnode, or `{ vnode, deep }` where `deep`
+     * is extra `Panel`s (AST, canonical round-trip) the host derives — shown
+     * only behind the depth toggle
+     */
+    renderers?: Record<string, (source: string, config?: any) => any>;
+    /**
+     * host-injected JSON Schema validator (the same seam) — the `validate`
+     * engine delegates here so
+     */
+    validate?: (schemaText: string, data: any, locale: string) => {
+        schemaError: string | null;
+        draft: string;
+        compileMs: number | null;
+        validateMs: number | null;
+        valid: boolean | null;
+        errors: any[];
+    };
+};
+export type PlayExample = {
+    id: string;
+    label: string;
+    /**
+     * - an engine id
+     */
+    engine: string;
+    /**
+     * - presets the source pane(s)
+     */
+    source: Record<string, string>;
+    /**
+     *   the JSON to run against — `[]` for a source-only engine (josl/csv/md),
+     *   one for a single run, several for a switcher
+     */
+    datasets: Array<{
+        label: string;
+        data: Record<string, string>;
+    }>;
+    /**
+     * - presets option-pane values
+     */
+    config?: Record<string, string>;
+};
+/**
+ * @typedef {Object} EnginePane
+ * @property {string} key - the pane's id (e.g. 'selector', 'data')
+ * @property {string} label
+ * @property {'code' | 'text'} [control]
+ */
+/**
+ * @typedef {Object} OptionPane
+ * A live select above the editors — a mode an engine runs in (JOSL vs TOML,
+ * CSV strict vs repair). Its value lives in the host's `config` slice.
+ * @property {string} key
+ * @property {string} label
+ * @property {Array<{ value: string, label: string }>} choices
+ * @property {string} default - the value used until the user picks another
+ */
+/**
+ * @typedef {Object} Panel
+ * A single result SCREEN. Every ok run yields at least one; a multi-screen
+ * engine (CSV: a summary note, the parsed table, the CSV round-trip) yields
+ * several, which the component shows behind a tab strip.
+ * @property {string} id - unique within the result (the tab key)
+ * @property {string} [label] - the tab label (defaults to `id`)
+ * @property {'code' | 'view' | 'table' | 'note' | 'cards'} kind
+ * @property {'simple' | 'deep'} [depth] - `deep` panels are the engine's rich
+ *   explainers, hidden until the student drills in via the depth toggle;
+ *   defaults to `simple` (the calm default view)
+ * @property {string} [text] - `code` / `note`: the text body
+ * @property {any} [vnode] - `view`: a host-rendered vnode, spliced verbatim
+ * @property {string[]} [columns] - `table`: the header labels
+ * @property {Array<Array<any>>} [rows] - `table`: cells, row-major
+ * @property {'ok' | 'warn' | 'info'} [tone] - `note`: the callout tone
+ * @property {Array<{ title: string, value: string, note?: string }>} [items]
+ *   `cards`: a row of stat cards (matches, compile/run timings, …)
+ */
+/**
+ * @typedef {Object} PlayResult
+ * @property {boolean} ok
+ * @property {{ compileMs: number, runMs: number } | null} timing
+ * @property {{ message: string, code?: string, path?: string } | null} error
+ * @property {Panel[]} panels - the result screens (`[]` on error); a single
+ *   `code` panel for most engines, several for the richer ones
+ */
+/**
+ * @typedef {Object} EngineDescriptor
+ * @property {string} id
+ * @property {string} label
+ * @property {string} [lead] - one line describing the engine
+ * @property {EnginePane[]} sourcePanes - the engine INPUT pane(s)
+ * @property {EnginePane[]} dataPanes - the JSON it runs against (may be [])
+ * @property {OptionPane[]} [optionPanes] - live mode selects (may be absent)
+ * @property {(source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult} run
+ */
+/**
+ * @typedef {Object} RunOptions
+ * @property {any} [operators] - a host operator registry ({ toOptions() }) for query/jslt/jtlt
+ * @property {Record<string, string>} [config] - the current option-pane values
+ * @property {Record<string, (source: string, config?: any) => any>} [renderers]
+ *   host-injected vnode renderers keyed by engine id — the visual engines
+ *   (markdown/mermaid/charts) delegate their rendering here (the hybrid seam),
+ *   so the package owns the descriptors + examples but stays dependency-light.
+ *   A renderer receives the source text plus its second argument — the
+ *   option-pane config for the visual engines, the PARSED data document for
+ *   `mdx` — and returns the preview vnode, or `{ vnode, deep }` where `deep`
+ *   is extra `Panel`s (AST, canonical round-trip) the host derives — shown
+ *   only behind the depth toggle
+ * @property {(schemaText: string, data: any, locale: string) => { schemaError: string|null, draft: string, compileMs: number|null, validateMs: number|null, valid: boolean|null, errors: any[] }} [validate]
+ *   host-injected JSON Schema validator (the same seam) — the `validate`
+ *   engine delegates here so @jarenjs/validate + the locale packs stay in the host
+ */
+/**
+ * @typedef {Object} PlayExample
+ * @property {string} id
+ * @property {string} label
+ * @property {string} engine - an engine id
+ * @property {Record<string, string>} source - presets the source pane(s)
+ * @property {Array<{ label: string, data: Record<string, string> }>} datasets
+ *   the JSON to run against — `[]` for a source-only engine (josl/csv/md),
+ *   one for a single run, several for a switcher
+ * @property {Record<string, string>} [config] - presets option-pane values
+ */
+/** The registered engines, by id. */
+export declare const ENGINES: Readonly<Record<string, EngineDescriptor>>;
+/** The ids of the registered engines, in registration order. */
+export declare function engineIds(): string[];
+/** The curated example library (the canonical home for the suite's engine
+ * examples). */
+export declare const EXAMPLES: readonly PlayExample[];
+/**
+ * Run one engine over a source + data. An unknown engine (or a throwing
+ * runner) yields an error Result — this never throws.
+ * @param {string} engineId
+ * @param {Record<string, string>} source
+ * @param {Record<string, string>} data
+ * @param {RunOptions} [options] - operators (query/jslt), the option-pane
+ *   config, and host renderers (markdown/mermaid/charts)
+ * @returns {PlayResult}
+ */
+export declare function runExample(engineId: string, source: Record<string, string>, data: Record<string, string>, options?: RunOptions): PlayResult;

package/docs/PLAY-FORMAT.md

@@ -0,0 +1,156 @@
+# PLAY-FORMAT — the engine descriptor and example contract
+
+`@jarenjs/play` models every engine the same way, so the playground UI
+(the example picker, the source panes, the dataset switcher, the run stage)
+is engine-agnostic and adding an engine is data, not UI code.
+
+## §1 The engine descriptor
+
+```
+EngineDescriptor = {
+  id:          string,        // 'path' | 'pointer' | 'query' | 'jslt' | …
+  label:       string,
+  lead?:       string,        // one line describing the engine
+  sourcePanes: EnginePane[],  // the engine INPUT (usually one)
+  dataPanes:   EnginePane[],  // the JSON it runs against (may be empty)
+  run:         (source, data) => PlayResult,
+}
+EnginePane = { key: string, label: string, control?: 'code' | 'text' }
+```
+
+- `sourcePanes` are the engine's input(s): a JSONPath `selector`, a JSLT
+  `stylesheet`, a JSON `patch`, a query + its `externals`, a markdown
+  `source`. Editable in the playground.
+- `dataPanes` are the JSON the engine runs against: usually one `data`; a
+  patch's is its `target`; markdown / mermaid / charts have **none** — the
+  source is everything.
+- `run(source, data)` is PURE and NEVER throws: it wraps the real shipped
+  compiler and returns a `PlayResult`. `source` / `data` are maps keyed
+  by the pane `key`s, holding the raw text.
+
+## §2 The result
+
+```
+PlayResult = {
+  ok:     boolean,
+  // EITHER half may be null: an engine with no compile step (patch merge
+  // and diff) and a phase the host did not report are both "no number",
+  // and the stage omits that clause rather than printing `0 ms` — which
+  // read as "it was free". Only measured phases are ever shown.
+  timing: { compileMs: number | null, runMs: number | null } | null,
+  error:  { message: string, code?, path? } | null,
+  panels: Panel[],                                 // the result SCREENS ([] on error)
+}
+
+Panel = {
+  id:     string,                                  // unique in the result (the tab key)
+  label?: string,                                  // the tab label (defaults to id)
+  kind:   'code' | 'view' | 'table' | 'note' | 'cards',
+  depth?: 'simple' | 'deep',                       // 'deep' → hidden behind the depth toggle
+  // per kind:
+  text?:    string,                                // code / note body
+  vnode?:   any,                                   // view: a host-rendered vnode, spliced verbatim
+  columns?: string[],  rows?: any[][],             // table
+  tone?:    'ok' | 'warn' | 'info',                // note callout tone
+  items?:   Array<{ title, value, note? }>,        // cards: a row of stat cards
+}
+```
+
+Every ok run yields **at least one** panel — most engines a single `code`
+panel. The `simple` panels are the calm default: the component shows one
+inline, or — for more than one — a tab strip above the active panel body.
+The `deep` panels are the engine's rich explainers (match cards, a
+geometry-free AST, a compiled program, a canonical round-trip): they stay
+hidden until the learner opens the **depth toggle** ("Explain ▸"), which
+reveals them as their own tab row beside the answer on desktop and as a
+full-pane swap (with a ← back) on a phone. **CSV** is the richest example:
+a `note` summary is the calm answer; the parsed `table`, the dialect and
+repairs tables and the round-trip `code` ride behind the toggle. The
+playground owns this small render vocabulary (code block, spliced vnode,
+table, callout, stat cards, coded error line), so it never depends on a
+host's node helpers.
+
+## §3 The example, and the dataset problem
+
+```
+PlayExample = {
+  id:       string,
+  label:    string,
+  engine:   string,                                // an engine id
+  source:   Record<paneKey, string>,               // presets the source pane(s)
+  datasets: Array<{ label: string, data: Record<paneKey, string> }>,
+}
+```
+
+An example presets the source, and carries a **list** of named datasets.
+The list length is the answer to "one data or many":
+
+- **0 datasets** — the engine takes no data (markdown / mermaid): no data
+  pane, no switcher.
+- **1 dataset** — one data pane, no switcher.
+- **N datasets** — a **dataset switcher** appears: run the same source over
+  dataset A vs. B vs. C without touching the source (e.g. one JSONPath
+  selector across three document shapes). Switching keeps the source;
+  editing a dataset re-runs.
+
+## §4 Extending
+
+A new engine is one `EngineDescriptor` (registered in `ENGINES`) plus its
+`PlayExample`s (added to `EXAMPLES`). No UI changes: the picker groups
+examples by engine, the panes render from `sourcePanes`/`dataPanes`, and
+the switcher appears whenever an example has ≥ 2 datasets.
+
+## §5 Host-injected seams (the dependency-light contract)
+
+Engines whose real work is heavy or opinionated keep the package free of that
+weight by delegating to a host-injected function on `RunOptions`, the same
+shape for each:
+
+- `renderers[id]` — the visual engines (markdown / mermaid / charts / mdx)
+  hand their source to a host renderer that returns a spliced `view` vnode —
+  or `{ vnode, deep, compileMs?, runMs? }`, where `deep` is extra panels only
+  the host can derive (the JSON AST, the canonical round-trip), shown behind
+  the depth toggle — so the package never imports `@jarenjs/md`, `/mermaid`
+  or `/charts`. The renderer's second argument is the option-pane config,
+  except `mdx`, which receives the PARSED data document (markdown × data is
+  a two-input engine). A renderer that reports `compileMs`/`runMs` is
+  believed; one that does not leaves the package holding a single
+  wall-clock number for the whole call, which it attributes to the RUN and
+  leaves the compile `null` — it never invents a figure it did not measure.
+- `validate` — the JSON Schema engine hands `(schemaText, data, locale)` to a
+  host validator that returns `{ valid, errors, draft, compileMs, validateMs,
+  schemaError }` (errors already localized), so the compiled validator and the
+  `@jarenjs/locales` packs stay in the host.
+- `operators` — a registry threaded to the `query`/`jslt`/`jtlt` engines.
+
+A missing seam is an honest error Result (`PLAY_NO_RENDERER` /
+`PLAY_NO_VALIDATOR`), never a throw. Read-only result panels are
+self-contained; interactive panels (a generated form) are host-wired.
+
+## §6 The session file
+
+A session is saveable, shareable and — because a share link has a length
+ceiling — **downloadable**. The file is a small self-describing envelope:
+
+```
+PlaySessionFile = {
+  $play:   '0.1',
+  name:    string,                                 // the session title
+  session: { engine, exampleId, source, data, config },
+}
+```
+
+Two rules make the round trip safe. Reading is **liberal**: a bare
+`session` object loads too, because that is what a share token decodes to
+and what a hand-written file is likely to be. Reading is also
+**untrusting**: every field goes through the same coercion a share token
+does, so a foreign or hostile document lands as safe defaults rather than
+reaching an engine, and a document naming no engine is refused outright —
+the session in progress survives a bad file instead of being replaced by
+it.
+
+The host supplies the two capabilities (a download and a file picker); a
+host that has neither still runs the surface, and the affordances say so
+rather than failing silently. This is the path that makes the oversized-
+share refusal honest: the link is declined, and the same session is
+offered as a file the import side can read back.