@jarenjs/play 0.34.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@jarenjs/play",
+  "private": false,
+  "version": "0.34.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./component": {
+      "types": "./dist/types/component/index.d.ts",
+      "default": "./src/component/index.js"
+    },
+    "./styles/play.css": "./styles/play.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/types/",
+    "src/",
+    "docs/",
+    "styles/"
+  ],
+  "description": "The jaren engine playground: pick a JSON engine (JSONPath, JSON Pointer, JSON Patch, query, JSLT, markdown, mermaid, …), feed it an input and one or more datasets from a curated example library, and watch it run. Understand an engine standalone before composing it in the studio. The engine is headless; the component is the playground UI.",
+  "author": "joham",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/jarenjs.git",
+    "directory": "components/play"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "jaren",
+    "json",
+    "playground",
+    "playground",
+    "examples",
+    "jsonpath",
+    "jslt",
+    "jsonquery",
+    "headless"
+  ],
+  "scripts": {
+    "build": "npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
+    "prepack": "npm run build:types"
+  },
+  "dependencies": {
+    "@jarenjs/core": "^0.34.0",
+    "@jarenjs/josl": "^0.34.0",
+    "@jarenjs/json": "^0.34.0",
+    "@jarenjs/validate": "^0.34.0"
+  }
+}

package/src/component/index.js

@@ -0,0 +1,53 @@
+//@ts-check
+/**
+ * @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 function createPlayComponent(options = {}) {
+  const seams = {};
+  if (options.operators !== undefined) seams.operators = options.operators;
+  if (options.renderers !== undefined) seams.renderers = options.renderers;
+  if (options.validate !== undefined) seams.validate = options.validate;
+  return {
+    mode: PLAY_MODE,
+    rules: playRules,
+    modes: playModes,
+    viewModel: playViewModel,
+    // the engine surface the host's run loop binds
+    engines: ENGINES,
+    examples: EXAMPLES,
+    engineIds,
+    runExample: (engineId, source, data, perCall = {}) =>
+      runExample(engineId, source, data, { ...seams, ...perCall }),
+    operators: options.operators,
+  };
+}
+
+export {
+  playViewModel, playRules, playModes, PLAY_MODE, PLAY_BASE,
+  ENGINES, EXAMPLES, engineIds, runExample,
+};

package/src/component/view.js

@@ -0,0 +1,318 @@
+//@ts-check
+/**
+ * @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 const PLAY_MODE = 'play';
+/** The slice the host mounts the view model at. */
+export const PLAY_BASE = '$.ui.play';
+/** The modes the host merges into the site stylesheet. */
+export const playModes = Object.freeze({ [PLAY_MODE]: { unmatched: 'error' } });
+
+/** One segment of the phone pane switcher — active when it is the live pane. */
+const paneButton = (pane, label) => ['button', {
+  type: 'button',
+  class: { $if: [{ $eq: ['$.mobilePane', pane] }, 'seg-btn active', 'seg-btn'] },
+  'aria-pressed': { $if: [{ $eq: ['$.mobilePane', pane] }, 'true', 'false'] },
+  on: { click: { action: 'play/mobile-pane', with: pane } },
+}, label];
+
+/** The shell (matches the whole slice): bar / rail | editors | split | stage. */
+const shell = {
+  match: PLAY_BASE, mode: PLAY_MODE,
+  body: ['div', { class: 'jplay', 'data-pane': '$.mobilePane' },
+    // ——— the IDE bar: engine title, session name, New/Save/Save As/Share,
+    // the Load dropdown, and the last share status (a play session is a
+    // saveable document) ———
+    ['div', { class: 'jplay-bar' },
+      ['strong', { class: 'jplay-title' }, '$.engine.label'],
+      // a NAME field, not a code editor: `.editor` paints the code-block
+      // background, which put a black hole in the middle of a light toolbar
+      ['input', {
+        class: 'jplay-name', value: '$.name', spellcheck: 'false',
+        autocapitalize: 'off', autocomplete: 'off', placeholder: 'name this session…',
+        'aria-label': 'session name', on: { input: 'play/name' },
+      }],
+      ['div', { class: 'jplay-actions' },
+        ['button', { class: 'btn small', type: 'button', on: { click: 'play/new' } }, 'New'],
+        ['button', {
+          class: 'btn small', type: 'button',
+          title: { $if: ['$.savedName',
+            { $concat: ['Overwrite “', '$.savedName', '”'] },
+            'Save this session under the name above'] },
+          on: { click: 'play/save' },
+        }, 'Save'],
+        ['button', {
+          class: 'btn small', type: 'button',
+          title: 'Save the name above as a SEPARATE session, keeping the original',
+          on: { click: 'play/save-as' },
+        }, 'Save As'],
+        // the way out of the browser, and back in: a session too large for
+        // a share link still has a file
+        ['button', {
+          class: 'btn small', type: 'button',
+          title: 'Download this session as a file',
+          on: { click: 'play/download' },
+        }, 'Download'],
+        ['button', {
+          class: 'btn small', type: 'button',
+          title: 'Open a downloaded session file',
+          on: { click: 'play/import' },
+        }, 'Import'],
+        ['button', { class: 'btn small', type: 'button', on: { click: 'play/share' } }, 'Share'],
+        // Delete the current named session (only meaningful once named+saved)
+        { $if: ['$.name',
+          ['button', { class: 'btn small', type: 'button', title: 'delete this saved session',
+            on: { click: { action: 'play/delete-session', with: '$.name' } } }, 'Delete'],
+          ''] },
+        // the Load dropdown appears once there is something saved
+        { $if: ['$.hasSaved',
+          ['select', { class: 'jplay-load editor line', 'aria-label': 'load a saved session', value: '', on: { change: 'play/open' } },
+            ['option', { value: '' }, 'Load…'],
+            [{ $apply: '$.names[*]' }]],
+          ''] },
+      ],
+      // the title has been edited away from the bound record: say which
+      // button does what, rather than letting Save silently overwrite the
+      // session the user opened under a name they have already changed
+      { $if: ['$.renamed',
+        ['span', { class: 'jplay-bound muted', role: 'status' },
+          'Save overwrites “', ['text', '$.savedName'], '” · Save As keeps both'],
+        ''] },
+      { $if: ['$.shared', ['span', { class: 'jplay-shared muted', role: 'status' }, '$.shared'], ''] },
+    ],
+    // ——— the phone pane switcher: below the breakpoint the rail | editors
+    // | result grid is ONE column, one pane at a time — a segmented bar
+    // instead of a tall stack (desktop hides this bar entirely). A pane
+    // is a grid area, not a `tabpanel`, so these are toggle buttons in a
+    // group with `aria-pressed`, not a `tablist` with `aria-selected`
+    // (the RESULT strip below is a real tablist and says so) ———
+    ['div', { class: 'jplay-mobilebar seg', role: 'group', 'aria-label': 'pane' },
+      paneButton('examples', 'Examples'),
+      paneButton('editor', 'Editor'),
+      paneButton('result', 'Result'),
+    ],
+    // ——— the example picker (a "file tree" grouped by engine) ———
+    ['nav', { class: 'jplay-rail', 'aria-label': 'examples' }, [{ $apply: '$.rail[*]' }]],
+    // ——— the source + data editors ———
+    ['div', { class: 'jplay-editors' },
+      ['div', { class: 'jplay-head' },
+        ['strong', { class: 'jplay-engine' }, '$.engine.label'],
+        ['span', { class: 'muted jplay-lead' }, '$.engine.lead'],
+      ],
+      // live mode selects (josl dialect, csv strict/repair) — empty for most
+      ['div', { class: 'jplay-options' }, [{ $apply: '$.optionPanes[*]' }]],
+      [{ $apply: '$.sourcePanes[*]' }],
+      { $if: ['$.hasSwitcher',
+        ['div', { class: 'jplay-datasets seg', role: 'group', 'aria-label': 'dataset' }, [{ $apply: '$.datasets[*]' }]],
+        ''] },
+      // the validate engine offers a JSON ↔ generated-form toggle on its data
+      { $if: ['$.hasForm',
+        ['div', { class: 'jplay-dataview seg', role: 'group', 'aria-label': 'data view' },
+          ['button', { type: 'button', class: { $if: [{ $eq: ['$.dataView', 'json'] }, 'seg-btn active', 'seg-btn'] },
+            on: { click: { action: 'play/data-view', with: 'json' } } }, 'JSON'],
+          ['button', { type: 'button', class: { $if: [{ $eq: ['$.dataView', 'form'] }, 'seg-btn active', 'seg-btn'] },
+            on: { click: { action: 'play/data-view', with: 'form' } } }, 'Form'],
+        ], ''] },
+      // form mode → the host-supplied generated form (a two-way seam); else
+      // the JSON data editor(s)
+      { $if: ['$.showForm',
+        ['div', { class: 'jplay-form' }, { $apply: ['$.dataForm', PLAY_MODE] }],
+        [{ $apply: '$.dataPanes[*]' }]] },
+    ],
+    // ——— the editors|result splitter (a pointer-capture widget; its host
+    // IS the grab bar — drives --jplay-ratio live, commits on pointer-up) ———
+    ['jaren-widget', {
+      name: 'play-splitter', class: 'jplay-split',
+      role: 'separator', 'aria-orientation': 'vertical',
+      'aria-label': 'Resize the editors and result',
+      'aria-valuemin': '10', 'aria-valuemax': '90', 'aria-valuenow': '$.ratioPct',
+      tabindex: '0',
+      props: { ratio: '$.ratio' },
+    }],
+    // ——— the run stage ———
+    ['div', { class: 'jplay-stage' },
+      ['div', { class: 'jplay-stage-head muted' }, 'Result'],
+      { $if: ['$.result.ran',
+        { $if: ['$.result.ok',
+          ['div', { class: { $if: ['$.result.deepOn', 'jplay-result deep-on', 'jplay-result'] } },
+            // the SIMPLE half — the calm answer (on a phone, the open
+            // drill-down swaps this half out entirely; see play.css)
+            ['div', { class: 'jplay-simple' },
+              { $if: ['$.result.timing', ['p', { class: 'muted jplay-timing' }, '$.result.timing'], ''] },
+              // >1 screen → a tab strip selecting the active one; 1 → no tabs
+              { $if: ['$.result.tabbed',
+                ['div', { class: 'jplay-tabs seg', role: 'tablist' }, [{ $apply: '$.result.tabs[*]' }]], ''] },
+              // the active panel body, rendered by its kind (a single object →
+              // the explicit [path, mode] apply form)
+              { $apply: [`$.result.activePanel`, PLAY_MODE] },
+            ],
+            // the DRILL-DOWN half — the engine's rich explainers, opt-in:
+            // a quiet affordance beneath the simple answer reveals the deep
+            // panels as an additional tab row (desktop) or a full-pane
+            // sub-view with a ← back (mobile)
+            { $if: ['$.result.hasDeep',
+              ['div', { class: 'jplay-deep' },
+                ['button', {
+                  type: 'button', class: 'jplay-deep-toggle',
+                  'aria-expanded': { $if: ['$.result.deepOn', 'true', 'false'] },
+                  on: { click: { action: 'play/deep', with: '$.result.deepNext' } },
+                }, '$.result.deepLabel'],
+                { $if: ['$.result.deepOn',
+                  ['div', { class: 'jplay-deep-body' },
+                    ['button', { type: 'button', class: 'jplay-deep-back', on: { click: { action: 'play/deep', with: '$.result.deepNext' } } }, '← Back to the result'],
+                    { $if: ['$.result.deepTabbed',
+                      ['div', { class: 'jplay-deep-tabs seg', role: 'tablist' }, [{ $apply: '$.result.deepTabs[*]' }]], ''] },
+                    { $apply: [`$.result.deepPanel`, PLAY_MODE] },
+                  ], ''] },
+              ], ''] },
+          ],
+          ['p', { class: 'error-line' }, ['strong', {}, '$.result.error.code'], ' ', '$.result.error.message']] },
+        ['p', { class: 'muted jplay-hint' }, 'Pick an example, or edit the source or data — it runs live.']] },
+    ],
+  ],
+};
+
+/** One engine group in the rail. */
+const railGroup = {
+  match: `${PLAY_BASE}.rail[*]`, mode: PLAY_MODE,
+  body: ['div', { class: { $if: ['$.active', 'jplay-group active', 'jplay-group'] } },
+    ['div', { class: 'jplay-group-head muted' }, '$.label'],
+    [{ $apply: '$.examples[*]' }],
+  ],
+};
+
+/** One example in a group — picking it loads its source + first dataset. */
+const railExample = {
+  match: `${PLAY_BASE}.rail[*].examples[*]`, mode: PLAY_MODE,
+  body: ['button', {
+    type: 'button',
+    class: { $if: ['$.active', 'jplay-ex active', 'jplay-ex'] },
+    on: { click: { action: 'play/example', with: '$.id' } },
+  }, '$.label'],
+};
+
+/** One source editor (a `text` control renders an input, else a textarea). */
+const sourcePane = {
+  match: `${PLAY_BASE}.sourcePanes[*]`, mode: PLAY_MODE,
+  body: ['label', { class: 'jplay-pane' },
+    ['span', { class: 'jplay-pane-label muted' }, '$.label'],
+    { $if: [{ $eq: ['$.control', 'text'] },
+      ['input', { type: 'text', class: 'editor line', spellcheck: 'false', value: '$.value',
+        on: { input: { action: 'play/source', with: { key: '$.key' } } } }],
+      ['textarea', { class: 'editor', rows: 6, spellcheck: 'false', value: '$.value',
+        on: { input: { action: 'play/source', with: { key: '$.key' } } } }]] },
+  ],
+};
+
+/** One data editor. */
+const dataPane = {
+  match: `${PLAY_BASE}.dataPanes[*]`, mode: PLAY_MODE,
+  body: ['label', { class: 'jplay-pane' },
+    ['span', { class: 'jplay-pane-label muted' }, '$.label'],
+    ['textarea', { class: 'editor', rows: 8, spellcheck: 'false', value: '$.value',
+      on: { input: { action: 'play/data', with: { key: '$.key' } } } }],
+  ],
+};
+
+/** One option pane — a live mode select (its value lives in host `config`). */
+const optionPane = {
+  match: `${PLAY_BASE}.optionPanes[*]`, mode: PLAY_MODE,
+  body: ['label', { class: 'jplay-option' },
+    ['span', { class: 'jplay-pane-label muted' }, '$.label'],
+    ['select', { class: 'editor line', on: { change: { action: 'play/option', with: { key: '$.key' } } } },
+      [{ $apply: '$.choices[*]' }]],
+  ],
+};
+
+/** One choice inside an option select. */
+const optionChoice = {
+  match: `${PLAY_BASE}.optionPanes[*].choices[*]`, mode: PLAY_MODE,
+  body: ['option', { value: '$.value', selected: '$.selected' }, '$.label'],
+};
+
+/** One dataset segment in the switcher. */
+const datasetOption = {
+  match: `${PLAY_BASE}.datasets[*]`, mode: PLAY_MODE,
+  body: ['button', {
+    type: 'button',
+    class: { $if: ['$.active', 'seg-btn active', 'seg-btn'] },
+    on: { click: { action: 'play/dataset', with: '$.index' } },
+  }, '$.label'],
+};
+
+/** One saved session in the Load dropdown. */
+const savedOption = {
+  match: `${PLAY_BASE}.names[*]`, mode: PLAY_MODE,
+  body: ['option', { value: '$.name' }, '$.name'],
+};
+
+/** One tab in the result strip (only shown when a result has >1 panel). */
+const resultTab = {
+  match: `${PLAY_BASE}.result.tabs[*]`, mode: PLAY_MODE,
+  body: ['button', {
+    type: 'button', role: 'tab',
+    class: { $if: ['$.active', 'seg-btn active', 'seg-btn'] },
+    'aria-selected': { $if: ['$.active', 'true', 'false'] },
+    on: { click: { action: 'play/panel', with: '$.id' } },
+  }, '$.label'],
+};
+
+/** One tab in the drill-down's own row (revealed by the depth toggle). */
+const deepTab = {
+  match: `${PLAY_BASE}.result.deepTabs[*]`, mode: PLAY_MODE,
+  body: ['button', {
+    type: 'button', role: 'tab',
+    class: { $if: ['$.active', 'seg-btn active', 'seg-btn'] },
+    'aria-selected': { $if: ['$.active', 'true', 'false'] },
+    on: { click: { action: 'play/deep-pick', with: '$.id' } },
+  }, '$.label'],
+};
+
+/** A result panel, rendered by its kind (code | view | table | note | cards) —
+ * one body, matched at both the simple and the deep panel slot. */
+const panelBody = { $if: ['$.isView', ['div', { class: 'jplay-view' }, '$.vnode'],
+  { $if: ['$.isTable',
+    ['div', { class: 'jplay-table-wrap' },
+      ['table', { class: 'jplay-table' },
+        ['thead', {}, ['tr', {}, [{ $apply: '$.columns[*]' }]]],
+        ['tbody', {}, [{ $apply: '$.rows[*]' }]]]],
+    { $if: ['$.isNote', ['p', { class: '$.noteClass' }, '$.text'],
+      { $if: ['$.isCards',
+        ['div', { class: 'jplay-cards' }, [{ $apply: '$.items[*]' }]],
+        ['pre', { class: 'code-block' }, ['code', {}, '$.text']]] }] }] }] };
+
+const activePanel = { match: `${PLAY_BASE}.result.activePanel`, mode: PLAY_MODE, body: panelBody };
+const deepPanel = { match: `${PLAY_BASE}.result.deepPanel`, mode: PLAY_MODE, body: panelBody };
+
+/** One stat card in a `cards` panel. */
+const cardBody = ['div', { class: 'jplay-card' },
+  ['span', { class: 'jplay-card-title muted' }, '$.title'],
+  ['strong', { class: 'jplay-card-value' }, '$.value'],
+  { $if: ['$.note', ['span', { class: 'jplay-card-note muted' }, '$.note'], ''] },
+];
+const activeCard = { match: `${PLAY_BASE}.result.activePanel.items[*]`, mode: PLAY_MODE, body: cardBody };
+const deepCard = { match: `${PLAY_BASE}.result.deepPanel.items[*]`, mode: PLAY_MODE, body: cardBody };
+
+/** A table header cell / body row / body cell — again at both slots. */
+const columnBody = ['th', {}, '$.label'];
+const rowBody = ['tr', {}, [{ $apply: '$.cells[*]' }]];
+const cellBody = ['td', {}, '$.text'];
+const tableColumn = { match: `${PLAY_BASE}.result.activePanel.columns[*]`, mode: PLAY_MODE, body: columnBody };
+const tableRow = { match: `${PLAY_BASE}.result.activePanel.rows[*]`, mode: PLAY_MODE, body: rowBody };
+const tableCell = { match: `${PLAY_BASE}.result.activePanel.rows[*].cells[*]`, mode: PLAY_MODE, body: cellBody };
+const deepTableColumn = { match: `${PLAY_BASE}.result.deepPanel.columns[*]`, mode: PLAY_MODE, body: columnBody };
+const deepTableRow = { match: `${PLAY_BASE}.result.deepPanel.rows[*]`, mode: PLAY_MODE, body: rowBody };
+const deepTableCell = { match: `${PLAY_BASE}.result.deepPanel.rows[*].cells[*]`, mode: PLAY_MODE, body: cellBody };
+
+/** The playground's JSLT rules — spread into the site stylesheet. */
+export const playRules = [
+  shell, railGroup, railExample, optionPane, optionChoice, sourcePane, dataPane, datasetOption,
+  savedOption, resultTab, deepTab, activePanel, deepPanel, activeCard, deepCard,
+  tableColumn, tableRow, tableCell, deepTableColumn, deepTableRow, deepTableCell,
+];

package/src/component/viewmodel.js

@@ -0,0 +1,181 @@
+//@ts-check
+/**
+ * @file `playViewModel(state)` — the playground's pure derivation. From
+ * the `state.play` slice it derives the example rail (the picker, grouped
+ * by engine — the "file-picker of sorts"), the active engine's source
+ * editors, the dataset switcher, the data editors, and the run result for
+ * the stage. Pure: nothing here is stored back in state.
+ */
+import { pickAllowed } from '@jarenjs/core/array';
+import { ENGINES, EXAMPLES } from '../index.js';
+import { formatMs } from '../format.js';
+
+/** The phone panes, in switcher order. */
+const MOBILE_PANES = ['examples', 'editor', 'result'];
+
+/**
+ * The timing line, built only from the phases that were actually measured.
+ * A `null` half means "no such phase" (patch merge has nothing to compile)
+ * or "the host did not report it" — either way it is omitted rather than
+ * printed as `0 ms`, which read as "rendering was free".
+ */
+function formatTiming(timing) {
+  if (!timing) return null;
+  const parts = [];
+  if (typeof timing.compileMs === 'number') parts.push(`compiled ${formatMs(timing.compileMs)}`);
+  if (typeof timing.runMs === 'number') parts.push(`ran ${formatMs(timing.runMs)}`);
+  return parts.length === 0 ? null : parts.join(' · ');
+}
+
+/**
+ * Shape one panel for the view: kind flags for the `$if` dispatch plus the
+ * per-kind content (a `table` becomes column/cell records the JSLT can walk).
+ */
+function shapePanel(p) {
+  const kind = p.kind;
+  const base = {
+    id: p.id, label: p.label ?? p.id, kind,
+    isCode: kind === 'code', isView: kind === 'view', isTable: kind === 'table',
+    isNote: kind === 'note', isCards: kind === 'cards',
+  };
+  if (kind === 'view') return { ...base, vnode: p.vnode ?? null };
+  if (kind === 'note') return { ...base, text: p.text ?? '', noteClass: `jplay-note ${p.tone ?? 'info'}` };
+  if (kind === 'table') return {
+    ...base,
+    columns: (p.columns ?? []).map((label) => ({ label: String(label) })),
+    rows: (p.rows ?? []).map((cells) => ({ cells: (cells ?? []).map((text) => ({ text: String(text) })) })),
+  };
+  if (kind === 'cards') return {
+    ...base,
+    items: (p.items ?? []).map((i) => ({ title: String(i.title), value: String(i.value), note: i.note ?? '' })),
+  };
+  return { ...base, text: p.text ?? '' }; // code
+}
+
+/**
+ * Derive the run result for the stage. The `simple` panels are the calm
+ * default: they become a tab strip (when >1) plus the single ACTIVE panel
+ * body. The `deep` panels — the engine's rich explainers — stay hidden
+ * until the student toggles the drill-down (`state.play.deep`); then they
+ * form their OWN tab row (`deepPick` selects among several). Each active
+ * panel is the one the host asked for when it still exists in this result,
+ * else the first — so a fresh result with different screens never strands
+ * the view on a tab that is gone.
+ */
+function deriveResult(r, wantedId, deepWanted, deepPick) {
+  const all = Array.isArray(r.panels) ? r.panels : [];
+  const panels = all.filter((p) => p.depth !== 'deep');
+  const deep = all.filter((p) => p.depth === 'deep');
+  const activeId = panels.some((p) => p.id === wantedId) ? wantedId : (panels[0]?.id ?? null);
+  const active = panels.find((p) => p.id === activeId) ?? null;
+  const hasDeep = deep.length > 0;
+  const deepOn = hasDeep && deepWanted === true;
+  const deepId = deep.some((p) => p.id === deepPick) ? deepPick : (deep[0]?.id ?? null);
+  const activeDeep = deep.find((p) => p.id === deepId) ?? null;
+  return {
+    ran: true,
+    ok: r.ok === true,
+    error: r.error ? { code: r.error.code ?? '', message: r.error.message ?? '' } : null,
+    timing: formatTiming(r.timing),
+    tabbed: panels.length > 1,
+    tabs: panels.map((p) => ({ id: p.id, label: p.label ?? p.id, active: p.id === activeId })),
+    activePanel: active ? shapePanel(active) : null,
+    // the drill-deeper half: the affordance, its state, and the deep screens
+    hasDeep,
+    deepOn,
+    deepNext: !deepOn,
+    deepLabel: deepOn ? 'Explain ▾' : 'Explain ▸',
+    deepTabbed: deep.length > 1,
+    deepTabs: deep.map((p) => ({ id: p.id, label: p.label ?? p.id, active: p.id === deepId })),
+    deepPanel: deepOn && activeDeep ? shapePanel(activeDeep) : null,
+  };
+}
+
+/**
+ * @param {{ play?: any }} state
+ * @returns {any}
+ */
+export function playViewModel(state) {
+  const s = state.play ?? {};
+  const engineId = s.engine ?? EXAMPLES[0]?.engine ?? '';
+  const engine = ENGINES[engineId] ?? null;
+
+  // the rail: examples grouped by engine (a folder per engine)
+  const groups = new Map();
+  for (const ex of EXAMPLES) {
+    if (!groups.has(ex.engine)) groups.set(ex.engine, []);
+    groups.get(ex.engine).push(ex);
+  }
+  const rail = [...groups.entries()].map(([id, exs]) => ({
+    engine: id,
+    label: ENGINES[id]?.label ?? id,
+    active: id === engineId,
+    examples: exs.map((ex) => ({ id: ex.id, label: ex.label, active: ex.id === s.exampleId })),
+  }));
+
+  const sourcePanes = (engine?.sourcePanes ?? []).map((p) => ({
+    key: p.key, label: p.label, control: p.control ?? 'code', value: s.source?.[p.key] ?? '',
+  }));
+  const dataPanes = (engine?.dataPanes ?? []).map((p) => ({
+    key: p.key, label: p.label, value: s.data?.[p.key] ?? '',
+  }));
+
+  // option panes: live mode selects (josl dialect, csv repair/headers/…);
+  // the selected value is the host config override or the pane's default
+  const config = s.config ?? {};
+  const optionPanes = (engine?.optionPanes ?? []).map((p) => ({
+    key: p.key, label: p.label,
+    choices: p.choices.map((c) => ({ value: c.value, label: c.label, selected: (config[p.key] ?? p.default) === c.value })),
+  }));
+
+  const active = EXAMPLES.find((e) => e.id === s.exampleId) ?? null;
+  const datasetIndex = s.datasetIndex ?? 0;
+  const datasets = (active?.datasets ?? []).map((ds, i) => ({ index: i, label: ds.label, active: i === datasetIndex }));
+
+  const r = s.result ?? null;
+  const result = r === null ? { ran: false } : deriveResult(r, s.panel, s.deep, s.deepPick);
+
+  // the IDE half: the saveable-session chrome
+  const names = Array.isArray(s.names) ? s.names : [];
+  const ratio = typeof s.ratio === 'number' ? s.ratio : 0.5;
+
+  // the generated-form half: the validate engine's data pane can
+  // swap the JSON textarea for a schema-generated form. The form tree itself
+  // (`dataForm`) is host-supplied (it needs @jarenjs/forms) — the package only
+  // decides WHEN to show it.
+  const hasForm = engineId === 'validate';
+  const dataView = s.dataView === 'form' ? 'form' : 'json';
+
+  return {
+    engine: { id: engineId, label: engine?.label ?? engineId, lead: engine?.lead ?? '' },
+    active: active ? { id: active.id, label: active.label } : null,
+    rail,
+    optionPanes,
+    sourcePanes,
+    dataPanes,
+    datasets,
+    hasSwitcher: datasets.length >= 2,
+    result,
+    // IDE chrome: the session name, the saved list, the last share status,
+    // and the editor|result split (the shared splitter reads `ratio`)
+    name: s.name ?? '',
+    names: names.map((n) => ({ name: n, active: n === s.name })),
+    hasSaved: names.length > 0,
+    // the record this session is bound to, and whether the title has been
+    // edited away from it. Without this the two save buttons look
+    // identical: the hint is what tells the reader that Save lands on the
+    // record they opened and Save As lands on the name they just typed.
+    savedName: s.savedName ?? null,
+    renamed: s.savedName != null && (s.name ?? '') !== s.savedName,
+    shared: s.shared ?? null,
+    ratio,
+    ratioPct: String(Math.round(ratio * 100)),
+    // the form/JSON toggle (validate only); `showForm` gates the form seam
+    hasForm,
+    dataView,
+    showForm: hasForm && dataView === 'form',
+    // the phone layout: one pane at a time behind a segmented switcher
+    // (Examples · Editor · Result); desktop ignores it (CSS)
+    mobilePane: pickAllowed(s.mobilePane, MOBILE_PANES, 'editor'),
+  };
+}