@jarenjs/studio 0.83.3 → 0.84.3

package/src/component/data/views.js

@@ -0,0 +1,241 @@
+//@ts-check
+/**
+ * The data studio — mode 'data', dispatched with `$.ui.data` (derived
+ * by boundaries/data.js — the boundary-exports convention). The THIRD
+ * studio, built on the extracted kit: both editors are the kit's
+ * `editorTextarea`, errors are its `errorLine`. Left: the model
+ * document and the store's honest status (topology, VFS, durability).
+ * Middle: the query document with results and `explain()` — the
+ * pushdown made visible. Right: a live query maintaining as rows are
+ * inserted, and the worked migration with its shadow verification.
+ * Fourth: the spatial round trip — CSV to a map through the stylesheet,
+ * the meta-schema, a throwaway store with derived spatial indexes, a
+ * linq `$within` and its `explain()`, in this tab.
+ *
+ * Below the breakpoint those four become one pane at a time behind the
+ * shared segmented switcher (Store · Query · Live · Round trip),
+ * defaulting to the query — the pane a reader of this page came for.
+ */
+import { editorTextarea, errorLine, paneSwitcher } from '../shared/studio-kit.js';
+
+const ownerDisabled = { $or: [{ $ne: ['$.topology', 'owner'] }, { $ne: ['$.status', 'ready'] }] };
+const ownerReason = { $if: [{ $ne: ['$.topology', 'owner'] },
+  ['p', { class: 'muted data-owner-reason' }, 'Only the owning tab can recreate or migrate the store.']] };
+
+const statusCard =
+  ['div', { class: 'card pg-card data-status' },
+    ['h3', {}, 'Store'],
+    ['p', { class: 'data-badges' },
+      ['span', { class: 'badge' }, 'topology: ', ['strong', { class: 'data-topology' }, '$.topology']],
+      ['span', { class: 'badge' }, 'vfs: ', ['strong', { class: 'data-vfs' }, '$.vfs']],
+      ['span', { class: 'badge' }, 'capture: ', ['strong', {}, '$.capture']],
+      ['span', { class: 'badge' }, 'sqlite ', '$.version'],
+      ['span', { class: 'badge' }, 'operators: ', ['strong', { class: 'data-operators' }, '$.operatorSummary']],
+    ],
+    ['p', { class: 'muted data-durability' }, '$.durability'],
+    { $if: ['$.oracleAvailable', ['details', { class: 'details-card data-oracle' },
+      ['summary', {}, 'Spatial agreement \u2014 the same plans as Node'],
+      ['p', { class: 'muted' },
+        'This store runs the same spatial plans as Node. The committed spatial corpus \u2014 the entries the JavaScript engine recorded its answers for \u2014 runs here through SQLite compiled to wasm, one throwaway in-memory store per entry, with and without the derived spatial indexes, and every answer is compared with the recorded one. The same corpus holds the Node driver to the engine in the test suite; this tab is the third executor, and the test suite drives this button in Chromium, Firefox and WebKit. It proves execution, not durability: where OPFS is absent the store is in-memory, which is a property of the host, not of the suite.'],
+      ['button', { class: 'btn small data-oracle-run', type: 'button', on: { click: 'data/oracle-run' } },
+        'Run the spatial corpus'],
+      { $if: ['$.oracle',
+        ['div', { class: 'data-oracle-report', 'data-status': '$.oracle.status' },
+          ['p', { class: 'data-oracle-summary' }, '$.oracleSummary'],
+          { $if: ['$.oracleDisagreed',
+            ['pre', { class: 'code-block clamp data-oracle-disagreements' },
+              ['code', {}, '$.oracleDisagreements']]] },
+          { $if: ['$.oracleDone',
+            ['details', { class: 'details-card' },
+              ['summary', {}, 'Every answer, as JSON'],
+              ['pre', { class: 'code-block clamp data-oracle-results' },
+                ['code', {}, '$.oracleResultsJson']]]] },
+        ]] },
+    ]] },
+    ['details', { class: 'details-card' },
+      ['summary', {}, 'Registered operators (host opt-in)'],
+      ['p', { class: 'muted' }, 'This studio mounts the math / finance / stats packs, so queries here may use $sqrt, $npv, $mean, $stddev, $percentile and more. The pushable-scalar subset (math) runs inside SQLite as deterministic UDFs; finance and stats fold a series in the query residual — explain() shows which.'],
+      ['pre', { class: 'code-block clamp' }, ['code', {}, '$.operatorList']],
+    ],
+    { $if: ['$.refusal',
+      ['p', { class: 'muted data-refusal' },
+        ['code', {}, '$.refusal.code'], ' — ', '$.refusal.message']] },
+    ['details', { class: 'details-card', open: true },
+      ['summary', {}, 'Model (jaren-model JSON)'],
+      editorTextarea({ value: '$.modelText', action: 'data/model-text', rows: 14, live: true }),
+      ['button', { class: 'btn small', type: 'button', disabled: ownerDisabled, on: { click: 'data/open' } },
+        'Recreate store from model'],
+      ownerReason,
+      ['p', { class: 'muted' },
+        'Recreating unlinks the database the owning tab holds, so only that tab can do it: a client tab is refused, with the store\u2019s own coded message.'],
+    ],
+    ['details', { class: 'details-card', open: true },
+      ['summary', {}, 'Documents'],
+      ['p', { class: 'muted data-row-summary' }, '$.rowSummary'],
+      ['ul', { class: 'data-rows' }, [{ $apply: '$.rowList[*]' }]],
+    ],
+  ];
+
+/** One stored document: what it holds, and the delete the live pane
+ * shows arriving as an RFC 6902 remove. A row whose key pointer found
+ * nothing carries no control — there would be nothing to address. */
+const documentRow = {
+  match: '$.ui.data.rowList[*]', mode: 'data',
+  body: ['li', { class: 'data-row' },
+    ['code', {}, '$.text'],
+    { $if: [{ $exists: '$.key' },
+      ['button', {
+        type: 'button', class: 'btn small data-row-delete', title: 'Delete this document',
+        on: { click: { action: 'data/delete', with: '$.key' } },
+      }, '\u00d7']] },
+  ],
+};
+
+const queryCard =
+  ['div', { class: 'card pg-card data-query' },
+    ['h3', {}, 'Query'],
+    editorTextarea({ value: '$.queryText', action: 'data/query-text', rows: 8, live: true }),
+    ['p', {},
+      ['button', {
+        class: 'btn small primary', type: 'button',
+        disabled: { $ne: ['$.status', 'ready'] }, on: { click: 'data/run' },
+      },
+        'Run + explain'],
+      // every keystroke is published, then Enter or blur commits: this
+      // page re-renders on each live-query event, and a controlled input
+      // whose buffer is not in state is reset by that render mid-typing
+      ['input', {
+        class: 'data-insert-title', type: 'text',
+        value: '$.insertDraft', placeholder: '$.insertPlaceholder',
+        disabled: { $ne: ['$.status', 'ready'] },
+        on: { input: 'data/insert-draft', change: 'data/insert' },
+      }]],
+    { $if: ['$.explain',
+      ['details', { class: 'details-card', open: true },
+        ['summary', {}, 'explain() — the pushdown, visible'],
+        ['pre', { class: 'code-block data-explain-sql' }, ['code', {}, '$.explain.sql']],
+        ['p', { class: 'muted' }, 'params: ', ['code', {}, '$.explain.params']],
+        ['p', { class: 'muted' }, 'indexes: ', ['code', { class: 'data-explain-indexes' }, '$.explain.indexes']],
+        ['p', { class: 'muted' }, 'residual: ', ['code', {}, '$.explain.residual']],
+      ]] },
+    ['details', { class: 'details-card', open: true },
+      ['summary', {}, 'Results'],
+      ['pre', { class: 'code-block clamp data-results' }, ['code', {}, '$.resultsJson']],
+    ],
+    ['details', { class: 'details-card' },
+      ['summary', {}, 'Try a registered operator'],
+      ['p', { class: 'muted' }, 'The sqrt operator is a pushable scalar — paste this, Run, and watch explain() show a jaren_p_ UDF in the SQL (SQLite does the filtering). A finance or stats operator, such as mean over a series, runs in the residual instead, and explain() names it.'],
+      ['pre', { class: 'code-block' }, ['code', {}, '$.operatorSample']],
+    ],
+  ];
+
+const liveCard =
+  ['div', { class: 'card pg-card data-live' },
+    ['h3', {}, 'Live query'],
+    { $if: ['$.liveNote', ['p', { class: 'muted data-live-note' }, '$.liveNote']] },
+    ['p', { class: 'muted' },
+      'A subscribe operation over the contract stream binding: the snapshot, then RFC 6902 patches as writes commit — one diff format end to end.'],
+    ['p', { class: 'data-live-count' }, '$.liveSummary'],
+    ['p', { class: 'muted data-live-regs' }, 'live registrations on the store: ', ['strong', {}, '$.liveRegs']],
+    ['pre', { class: 'code-block clamp data-live-rows' }, ['code', {}, '$.liveJson']],
+    ['h3', {}, 'Migration'],
+    ['p', { class: 'muted' },
+      'Plan a model change, verify it on a SHADOW database, apply it — in the browser.'],
+    { $if: ['$.migrationAvailable', ['div', {},
+    ['button', { class: 'btn small', type: 'button', disabled: ownerDisabled, on: { click: 'data/migrate' } },
+      'Add a title index (plan → shadow → apply)'],
+    ownerReason,
+    ]] },
+    { $if: ['$.migration',
+      ['div', { class: 'data-migration' },
+        ['p', {}, 'planned steps:'],
+        ['pre', { class: 'code-block clamp data-migration-steps' },
+          ['code', {}, '$.migrationSteps']],
+        ['p', { class: 'data-migration-applied' }, '$.migrationSummary'],
+      ]] },
+  ];
+
+/**
+ * The round trip, where a reader can watch it: every stage is a
+ * document the page prints, the store stage is explained beside its
+ * answer, and the answer is drawn. The map is what the `geojson`
+ * format's preview hint asks a host for; this host has a renderer.
+ */
+const tripCard =
+  ['div', { class: 'card pg-card data-trip' },
+    ['h3', {}, 'Round trip'],
+    ['p', { class: 'muted' },
+      'CSV in, a map out, in this tab. The rows become a FeatureCollection through a JSLT stylesheet, the collection is judged by the GeoJSON meta-schema, stored in a throwaway collection with derived spatial indexes, queried with a $within written through @jarenjs/linq, and explain() shows the two-stage plan \u2014 the bounding box the index seeks and the exact refinement the engine keeps \u2014 before the result is drawn.'],
+    editorTextarea({ value: '$.tripCsv', action: 'data/trip-csv', rows: 7, live: true }),
+    ['p', {},
+      ['button', { class: 'btn small primary data-trip-run', type: 'button', on: { click: 'data/trip-run' } },
+        'Run the round trip']],
+    { $if: ['$.trip',
+      ['div', { class: 'data-trip-report', 'data-status': '$.tripStatus' },
+        ['p', { class: 'data-trip-summary' }, '$.tripSummary'],
+        { $if: ['$.tripDone',
+          ['div', {},
+            ['details', { class: 'details-card', open: true },
+              ['summary', {}, 'explain() \u2014 the two-stage spatial plan'],
+              ['pre', { class: 'code-block data-trip-sql' }, ['code', {}, '$.tripExplainSql']],
+              ['p', { class: 'muted' }, 'pre-filters: ', ['code', { class: 'data-trip-prefilters' }, '$.tripPrefilters']],
+              ['p', { class: 'muted' }, 'scan narrative: ', ['code', { class: 'data-trip-narrative' }, '$.tripNarrative']],
+              ['p', { class: 'muted' }, 'indexes: ', ['code', { class: 'data-trip-indexes' }, '$.tripIndexes']],
+              ['p', { class: 'muted' }, 'residual: ', ['code', { class: 'data-trip-residual' }, '$.tripResidual']],
+            ],
+            { $if: ['$.tripMap', ['div', { class: 'chart-card data-trip-map' }, '$.tripMap']] },
+            ['details', { class: 'details-card' },
+              ['summary', {}, 'The result \u2014 the features inside the region, as stored'],
+              ['pre', { class: 'code-block clamp data-trip-results' }, ['code', {}, '$.tripResultsJson']]],
+          ]] },
+      ]] },
+    ['details', { class: 'details-card' },
+      ['summary', {}, 'The stylesheet \u2014 CSV rows to a FeatureCollection, no code'],
+      ['pre', { class: 'code-block clamp' }, ['code', {}, '$.tripStylesheet']]],
+    ['details', { class: 'details-card' },
+      ['summary', {}, 'The model \u2014 derived spatial indexes over the geometry'],
+      ['pre', { class: 'code-block clamp' }, ['code', {}, '$.tripModel']]],
+    ['details', { class: 'details-card' },
+      ['summary', {}, 'The query \u2014 written through @jarenjs/linq'],
+      ['pre', { class: 'code-block' }, ['code', {}, '$.tripChain']],
+      ['p', { class: 'muted' }, 'emits this document, with the region bound as an external:'],
+      ['pre', { class: 'code-block data-trip-query' }, ['code', {}, '$.tripQuery']],
+      ['pre', { class: 'code-block clamp' }, ['code', {}, '$.tripRegion']]],
+  ];
+
+const dataPaneSwitcher = paneSwitcher({
+          class: 'data-panebar', pane: '$.mobilePane', action: 'data/pane',
+          panes: [['store', 'Store'], ['query', 'Query'], ['live', 'Live'], ['trip', 'Round trip']],
+        });
+dataPaneSwitcher[dataPaneSwitcher.length - 1] = { $if: ['$.tripAvailable', dataPaneSwitcher.at(-1)] };
+
+export const DATA_RULES = [
+  documentRow,
+  {
+    match: '$.ui.data', mode: 'data',
+    // `container` for the gutters the other studios have: without it this
+    // page ran edge-to-edge, into the notch, at every width
+    body: ['section', { class: 'jaren-data-editor' },
+      { $if: [{ $eq: ['$.status', 'boot'] },
+        ['p', { class: 'muted data-booting' }, 'Loading the SQLite wasm build…']] },
+      // the boot's terminal failure: the stage that failed is what a
+      // reader can report, and the retry starts the protocol over
+      { $if: [{ $eq: ['$.status', 'error'] },
+        ['div', { class: 'card pg-card data-boot-error', role: 'alert' },
+          ['p', {},
+            ['strong', {}, 'The store did not boot.'], ' Stage ',
+            ['code', { class: 'data-boot-stage' }, '$.boot.stage'], ' failed: ',
+            ['span', { class: 'data-boot-message' }, '$.boot.message']],
+          ['button', { class: 'btn small data-boot-retry', type: 'button', on: { click: 'data/retry' } },
+            'Retry the boot']]] },
+      { $if: ['$.plainError', errorLine('$.plainError')] },
+      ['div', { class: 'data-grid', 'data-pane': '$.mobilePane' },
+        dataPaneSwitcher,
+        statusCard,
+        queryCard,
+        liveCard,
+        { $if: ['$.tripAvailable', tripCard] },
+      ],
+    ],
+  },
+];

package/src/component/document.js

@@ -0,0 +1,344 @@
+//@ts-check
+/** Validate, audit and mount isolated app documents with explicit render services. */
+import { JarenValidator } from '@jarenjs/validate';
+import { jsonFormats } from '@jarenjs/formats';
+import { OUR_SCHEMA_OPTIONS } from './shared/schema-options.js';
+import { createTypeTestCompiler } from '@jarenjs/validate/query';
+import { createApp, createFormView, formEventFields } from '@jarenjs/app';
+import { createDomRenderer } from '@jarenjs/view';
+import { compileJsltStylesheet } from '@jarenjs/json/jslt';
+import { buildFormModel, buildFormViewModel } from '@jarenjs/forms';
+import { compileChart } from '@jarenjs/charts';
+import { errorMessage } from './shared/nodes.js';
+import appSchema from '@jarenjs/app/schemas/jaren-app.schema.json' with { type: 'json' };
+import querySchema from '@jarenjs/json/schemas/jaren-query.schema.json' with { type: 'json' };
+import jsltSchema from '@jarenjs/json/schemas/jaren-jslt.schema.json' with { type: 'json' };
+
+
+
+/** @param {{ markdown: (source: string) => any, diagram: (source: string) => any, templates?: any[] }} options */
+export function createStudioDocumentHost(options) {
+const { markdown, diagram, templates: STUDIO_TEMPLATES = [] } = options;
+/** Schema errors kept per report: enough to repair, bounded for state. */
+const MAX_ERRORS = 20;
+
+// the meta-schema composes the published query and JSLT grammars by
+// reference — register those artifacts alongside it (APP-FORMAT §2)
+const validateApp = new JarenValidator(OUR_SCHEMA_OPTIONS)
+  .addFormats(jsonFormats)
+  .addSchema(querySchema)
+  .addSchema(jsltSchema)
+  .compile(appSchema);
+
+const message = errorMessage;
+
+/**
+ * Validate a candidate document against the jaren-app meta-schema.
+ * @param {any} doc
+ * @returns {{ valid: boolean, errors: Array<{ instancePath: string, keyword: string, message: string }>, total: number }}
+ */
+function validateAppDocument(doc) {
+  const outcome = validateApp(doc);
+  const valid = typeof outcome === 'object' && outcome !== null ? outcome.valid : outcome === true;
+  if (valid) return { valid: true, errors: [], total: 0 };
+  const raw = (typeof outcome === 'object' && outcome !== null ? outcome.errors : null) ?? [];
+  return {
+    valid: false,
+    total: raw.length,
+    errors: raw.slice(0, MAX_ERRORS).map((e) => ({
+      instancePath: e.instancePath ?? '',
+      keyword: e.keyword ?? '',
+      message: e.message ?? 'invalid',
+    })),
+  };
+}
+
+//#region the document's render-capability widgets
+
+/**
+ * A pure props→vnode widget: its own mini renderer into the host, and
+ * every `on` binding inside the projection emits back into the hosting
+ * app's dispatch (VIEW-FORMAT §7) — the widget renders, the document's
+ * actions own the state transitions.
+ * @param {(props: any) => any} view
+ * @returns {{ mount: (host: HTMLElement, props: any, emit: (binding: any, event: Event) => void) => { render: ReturnType<typeof createDomRenderer> }, update: (handle: { render: ReturnType<typeof createDomRenderer> }, props: any) => void, unmount: (handle: { render: ReturnType<typeof createDomRenderer> }) => void }}
+ */
+function vnodeWidget(view) {
+  return {
+    mount(host, props, emit) {
+      const render = createDomRenderer(host, {
+        document: host.ownerDocument,
+        onEvent: (binding, event) => emit(binding, event),
+      });
+      render(view(props));
+      return { render };
+    },
+    update(handle, props) {
+      handle.render(view(props));
+    },
+    unmount(handle) {
+      handle.render.destroy?.();
+    },
+  };
+}
+
+// the standard forms stylesheet, compiled once: the form widget renders
+// any `buildFormViewModel` tree; its bindings dispatch the standard
+// form actions the document embeds (createFormActions output is JSON)
+const formStylesheet = compileJsltStylesheet({
+  $jslt: '0.1',
+  rules: [
+    { match: '$', body: { $apply: '$.form' } },
+    ...createFormView(),
+  ],
+}, { memo: true });
+
+/** Form models memoized per schema value identity (state is immutable). */
+const formModels = new WeakMap();
+
+function formVnode(props) {
+  try {
+    const schema = props?.schema;
+    if (schema === null || typeof schema !== 'object') {
+      return ['p', { class: 'error-line' }, 'form: props.schema must be a JSON Schema object'];
+    }
+    let model = formModels.get(schema);
+    if (model === undefined) {
+      model = buildFormModel(schema);
+      formModels.set(schema, model);
+    }
+    return formStylesheet({
+      form: buildFormViewModel(model, props.data ?? null, { validateFields: true }),
+    });
+  }
+  catch (err) {
+    return ['p', { class: 'error-line' }, `form: ${message(err)}`];
+  }
+}
+
+function chartVnode(props) {
+  try {
+    // inline definitions carry their own data (the charts engine's
+    // static path); theme 'host' keeps light/dark live (docs/DESIGN.md §7)
+    return ['div', { class: 'studio-chart' },
+      compileChart(props.config, props.config, { theme: 'host' }).toVnode()];
+  }
+  catch (err) {
+    return ['p', { class: 'error-line' }, `chart: ${message(err)}`];
+  }
+}
+
+const markdownVnode = (props) => markdown(String(props?.source ?? ''));
+const mermaidVnode = (props) => diagram(String(props?.source ?? ''));
+
+/**
+ * The render capabilities a studio document may name (and nothing else).
+ * A composed host can register the same chart/mermaid/markdown/form widgets
+ * in its own view.
+ */
+const STUDIO_WIDGETS = {
+  form: vnodeWidget(formVnode),
+  chart: vnodeWidget(chartVnode),
+  markdown: vnodeWidget(markdownVnode),
+  mermaid: vnodeWidget(mermaidVnode),
+};
+
+//#endregion
+
+// $valid/$assert/$as and schema matches are compile-time capabilities
+// of the document grammars (pure, no side channel) — granted, unlike
+// effects and subs
+const compileTypeTest = createTypeTestCompiler();
+
+//#region the headless render audit
+
+/** Render problems reported per audit: enough to repair, bounded. */
+const MAX_RENDER_PROBLEMS = 8;
+
+/**
+ * A tag `createElement` accepts: a letter, then letters, digits or
+ * hyphens. One-element arrays like `["hr"]` are valid void elements —
+ * the defect class is invalid tag NAMES, not array arity.
+ */
+const VALID_TAG = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+
+/**
+ * Walk one rendered vnode with the renderer's own shape rules (text,
+ * skipped, `[tag, props?, ...children]`, non-string-head arrays splice
+ * as lists) and collect what a live mount would host: the widgets it
+ * names, and the shapes that render as junk even though the meta-schema
+ * accepted the document.
+ * @param {any} node
+ * @param {string} path - a JSON-pointer-ish trail into the rendered tree
+ * @param {{ widgets: string[], problems: string[] }} out
+ */
+function walkRenderedVnode(node, path, out) {
+  if (out.problems.length >= MAX_RENDER_PROBLEMS) return;
+  if (node == null || node === true || node === false) return; // skipped
+  if (typeof node === 'string' || typeof node === 'number') return; // text
+  if (!Array.isArray(node)) {
+    out.problems.push(`${path}: a bare object is not a vnode — it renders as nothing (expected ["tag", props, ...children] or text)`);
+    return;
+  }
+  if (typeof node[0] !== 'string') {
+    // a list: each item renders in place
+    for (let i = 0; i < node.length; i++) walkRenderedVnode(node[i], `${path}/${i}`, out);
+    return;
+  }
+  if (!VALID_TAG.test(node[0])) {
+    // this is a boot-stopper, not a cosmetic problem: the nested app
+    // dies on createElement and the whole stage ends empty
+    out.problems.push(`${path}: '${node[0]}' is not a valid element tag name — the app fails to boot on it (text belongs directly in the children, not wrapped in an array)`);
+    return;
+  }
+  if (node[0] === 'jaren-widget') {
+    const props = (node[1] !== null && typeof node[1] === 'object' && !Array.isArray(node[1])) ? node[1] : {};
+    const name = props.name;
+    out.widgets.push(String(name));
+    if (STUDIO_WIDGETS[name] === undefined) {
+      out.problems.push(`${path}: unknown widget '${String(name)}' — available: ${Object.keys(STUDIO_WIDGETS).join(', ')}`);
+    }
+    else if (name === 'form' && (props.props?.schema === null || typeof props.props?.schema !== 'object')) {
+      out.problems.push(`${path}: the form widget's props.schema did not resolve to a JSON Schema object — the form renders an error instead of fields`);
+    }
+    else if (name === 'chart' && (props.props?.config === null || typeof props.props?.config !== 'object')) {
+      out.problems.push(`${path}: the chart widget's props.config did not resolve to a chart definition object`);
+    }
+    if (name === 'form' && typeof props.props?.schema?.title === 'string' && props.props.schema.title !== '') {
+      out.formTitles.push(props.props.schema.title);
+    }
+    return;
+  }
+  if (node[0] === 'h1' || node[0] === 'h2' || node[0] === 'h3') {
+    const start = (node.length > 1 && node[1] !== null && typeof node[1] === 'object' && !Array.isArray(node[1])) ? 2 : 1;
+    let text = '';
+    for (let i = start; i < node.length; i++) {
+      if (typeof node[i] === 'string') text += node[i];
+    }
+    if (text.trim() !== '') out.headings.push(text.trim());
+  }
+  const start = (node.length > 1 && node[1] !== null && typeof node[1] === 'object' && !Array.isArray(node[1])) ? 2 : 1;
+  for (let i = start; i < node.length; i++) walkRenderedVnode(node[i], `${path}/${i}`, out);
+}
+
+/**
+ * The seed templates' rendered headings, each mapped to the form
+ * titles that seed legitimately pairs them with — the reference for
+ * the stale-heading note below. Built lazily from the templates
+ * themselves so it can never drift from the seed library.
+ * @type {Map<string, Set<string>> | null}
+ */
+let seedHeadings = null;
+
+function getSeedHeadings() {
+  if (seedHeadings === null) {
+    seedHeadings = new Map();
+    for (const template of STUDIO_TEMPLATES) {
+      /** @type {{ widgets: string[], problems: string[], headings: string[], formTitles: string[] }} */
+      const out = { widgets: [], problems: [], headings: [], formTitles: [] };
+      try {
+        walkRenderedVnode(
+          compileJsltStylesheet(template.doc.view, { compileTypeTest, memo: false })(template.doc.state),
+          '', out);
+      }
+      catch {
+        continue; // a seed that fails to render simply contributes nothing
+      }
+      for (const heading of out.headings) {
+        const titles = seedHeadings.get(heading) ?? new Set();
+        for (const title of out.formTitles) titles.add(title);
+        seedHeadings.set(heading, titles);
+      }
+    }
+  }
+  return seedHeadings;
+}
+
+/**
+ * Render the document's first frame headlessly — the same stylesheet
+ * compiler and state the live host boots with — and report the widgets
+ * it hosts plus any render problems the meta-schema cannot see. "It
+ * validates" is not "it renders": a valid document can still name an
+ * unknown widget, hand the form widget a non-object schema, or place a
+ * bare object where a vnode belongs.
+ *
+ * `notes` are soft semantic observations, not failures — today one
+ * rule: a SEED template's heading still on screen while the form's
+ * schema title has moved on (the repurposed-template leftover). The
+ * rule deliberately keys on the seed headings so a pristine template,
+ * or an authored heading of the user's own, never trips it.
+ * @param {any} doc
+ * @returns {{ widgets: string[], problems: string[], notes: string[] }}
+ */
+function auditDocumentRender(doc) {
+  /** @type {{ widgets: string[], problems: string[], headings: string[], formTitles: string[] }} */
+  const out = { widgets: [], problems: [], headings: [], formTitles: [] };
+  let vnode;
+  try {
+    vnode = compileJsltStylesheet(doc.view, { compileTypeTest, memo: false })(doc.state);
+  }
+  catch (err) {
+    out.problems.push(`the view failed to render its first frame: ${message(err)}`);
+    return { widgets: out.widgets, problems: out.problems, notes: [] };
+  }
+  walkRenderedVnode(vnode, '', out);
+
+  /** @type {string[]} */
+  const notes = [];
+  const markers = getSeedHeadings();
+  for (const heading of out.headings) {
+    const seedTitles = markers.get(heading);
+    if (seedTitles === undefined) continue;
+    const departed = out.formTitles.find((title) => !seedTitles.has(title)
+      && !heading.toLowerCase().includes(title.toLowerCase()));
+    if (departed !== undefined) {
+      notes.push(`the heading "${heading}" is still the seed template's while the form is now titled "${departed}" — patch the heading to match the repurposed form`);
+      break;
+    }
+  }
+  return { widgets: out.widgets, problems: out.problems, notes };
+}
+
+//#endregion
+
+/**
+ * Validate a document against the meta-schema and boot it as an
+ * isolated app: no effects, no subs, its own `onError` sink, the
+ * render-capability widgets, and the runtime's atomic-boot guarantee.
+ * @param {any} doc
+ * @param {{ node?: any, document?: any, schedule?: (flush: () => void) => void,
+ *   onError?: (err: Error) => void }} env
+ * @returns {{ ok: true, app: any } | { ok: false, errors: any[], total: number, message: string }}
+ */
+function loadStudioDocument(doc, env = {}) {
+  const report = validateAppDocument(doc);
+  if (!report.valid) {
+    return {
+      ok: false,
+      errors: report.errors,
+      total: report.total,
+      message: `the document does not validate against the jaren-app meta-schema (${report.total} error${report.total === 1 ? '' : 's'})`,
+    };
+  }
+  try {
+    const app = createApp(doc, {
+      node: env.node,
+      document: env.document,
+      schedule: env.schedule,
+      widgets: STUDIO_WIDGETS,
+      compileTypeTest,
+      // the form widget's typed selects and json editor decode here
+      eventFields: { ...formEventFields() },
+      onError: env.onError,
+      // deliberately absent: effects, subs — the isolation boundary
+    });
+    return { ok: true, app };
+  }
+  catch (err) {
+    // JA0007: boot rolled back atomically, the container ends empty
+    return { ok: false, errors: [], total: 0, message: message(err) };
+  }
+}
+
+return { validateAppDocument, STUDIO_WIDGETS, auditDocumentRender, loadStudioDocument };
+}