@jarenjs/studio 0.83.3 → 0.84.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/studio",
   "private": false,
-  "version": "0.83.3",
+  "version": "0.84.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -18,21 +18,34 @@
     "./schemas/*": "./schemas/*",
     "./styles/studio.css": "./styles/studio.css",
     "./package.json": "./package.json",
-    "./author": {
-      "types": "./dist/types/author.d.ts",
-      "default": "./src/author.js"
-    },
     "./export": {
       "types": "./dist/types/export.d.ts",
       "default": "./src/export.js"
-    }
+    },
+    "./flow": {
+      "types": "./dist/types/component/flow/index.d.ts",
+      "default": "./src/component/flow/index.js"
+    },
+    "./styles/flow.css": "./styles/flow.css",
+    "./styles/editor.css": "./styles/editor.css",
+    "./data": {
+      "types": "./dist/types/component/data/index.d.ts",
+      "default": "./src/component/data/index.js"
+    },
+    "./data/host": {
+      "types": "./dist/types/data/host.d.ts",
+      "default": "./src/data/host.js"
+    },
+    "./contracts/data.contract.json": "./contracts/data.contract.json",
+    "./styles/data.css": "./styles/data.css"
   },
   "files": [
     "dist/types/",
     "src/",
     "docs/",
     "schemas/",
-    "styles/"
+    "styles/",
+    "contracts/"
   ],
   "description": "The jaren project IDE: a multi-file project (schema, view, actions, model, queries, flow) is one document; each file is validated against its own grammar, assembled into runnable artifacts, and edited/hosted by the studio widget. The engine is headless; the component layer is the IDE.",
   "author": "joham",
@@ -67,13 +80,17 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.83.3",
-    "@jarenjs/validate": "^0.83.3",
-    "@jarenjs/json": "^0.83.3",
-    "@jarenjs/app": "^0.83.3",
-    "@jarenjs/flow": "^0.83.3",
-    "@jarenjs/db": "^0.83.3",
-    "@jarenjs/contract": "^0.83.3",
-    "@jarenjs/ai": "^0.83.3"
+    "@jarenjs/core": "^0.84.3",
+    "@jarenjs/validate": "^0.84.3",
+    "@jarenjs/json": "^0.84.3",
+    "@jarenjs/app": "^0.84.3",
+    "@jarenjs/flow": "^0.84.3",
+    "@jarenjs/db": "^0.84.3",
+    "@jarenjs/contract": "^0.84.3",
+    "@jarenjs/view": "^0.84.3",
+    "@jarenjs/forms": "^0.84.3",
+    "@jarenjs/formats": "^0.84.3",
+    "@jarenjs/charts": "^0.84.3",
+    "@jarenjs/mermaid": "^0.84.3"
   }
 }

package/src/component/data/actions.js

@@ -0,0 +1,138 @@
+//@ts-check
+/** Shared Data transitions for composed and independently mounted editors. */
+export const DATA_ACTIONS = {
+  // the data studio (boundaries/data.js): boot the owner worker, edit
+  // the model/query panes, run + explain, insert, live-event, migrate.
+  // A patch-only action carries its changed paths to the O(k) renderer.
+  'data/boot': { effects: [{ run: 'data-boot' }] },
+  'data/seed': {
+    patch: [
+      { op: 'replace', path: '/data/modelText', value: '$payload.modelText' },
+      { op: 'replace', path: '/data/queryText', value: '$payload.queryText' },
+      { op: 'replace', path: '/data/trip/csv', value: '$payload.tripCsv' },
+    ],
+  },
+  // the phone pane switcher (Store · Query · Live) — pure chrome; the
+  // store, its live query and its worker are untouched by it
+  'data/pane': { patch: [{ op: 'replace', path: '/data/mobilePane', value: '$payload' }] },
+  'data/model-text': { patch: [{ op: 'replace', path: '/data/modelText', value: '$event.value' }] },
+  'data/query-text': { patch: [{ op: 'replace', path: '/data/queryText', value: '$event.value' }] },
+  'data/open': { effects: [{ run: 'data-open', with: { text: '$.data.modelText' } }] },
+  'data/run': { effects: [{ run: 'data-run', with: { text: '$.data.queryText' } }] },
+  // the title is published per keystroke and read back from state, not
+  // from the commit event: a live-query render lands between typing and
+  // blurring, and a controlled input whose buffer is not in state is
+  // reset to it — silently, taking the insert with it
+  'data/insert-draft': { patch: [{ op: 'replace', path: '/data/insertDraft', value: '$event.value' }] },
+  'data/insert': {
+    patch: [{ op: 'replace', path: '/data/insertDraft', value: '' }],
+    effects: [{ run: 'data-insert', with: { title: '$event.value' } }],
+  },
+  // one stored document removed, by the key its own model declares
+  'data/delete': { effects: [{ run: 'data-delete', with: { key: '$payload' } }] },
+  'data/migrate': { effects: [{ run: 'data-migrate' }] },
+  // the third runner of the spatial corpus, driven from the store pane;
+  // the report replaces the last one, and `running` is what shows while
+  // the entries are still crossing the worker
+  'data/oracle-run': { effects: [{ run: 'data-oracle' }] },
+  'data/oracle': { patch: [{ op: 'replace', path: '/data/oracle', value: '$payload' }] },
+  // the spatial round trip, driven from the fourth card: the CSV is the
+  // editable input, the report replaces the last one, and `running`
+  // shows while the throwaway store is crossing the worker
+  'data/trip-csv': { patch: [{ op: 'replace', path: '/data/trip/csv', value: '$event.value' }] },
+  'data/trip-run': { effects: [{ run: 'data-trip', with: { csv: '$.data.trip.csv' } }] },
+  'data/trip': { patch: [{ op: 'replace', path: '/data/trip/report', value: '$payload' }] },
+  'data/status': {
+    patch: [
+      { op: 'replace', path: '/data/topology', value: '$payload.topology' },
+      { op: 'replace', path: '/data/vfs', value: '$payload.vfs' },
+      { op: 'replace', path: '/data/version', value: { $default: ['$payload.version', ''] } },
+      { op: 'replace', path: '/data/refusal', value: { $default: ['$payload.refusal', null] } },
+    ],
+  },
+  'data/opened': {
+    patch: [
+      { op: 'replace', path: '/data/status', value: 'ready' },
+      // a reopen may have moved the studio onto another model's first
+      // collection; the boot open stays on the seed model's
+      { op: 'replace', path: '/data/collection',
+        value: { $default: ['$payload.collection', '$.data.collection'] } },
+      { op: 'replace', path: '/data/keyPointer',
+        value: { $default: ['$payload.keyPointer', '$.data.keyPointer'] } },
+      { op: 'replace', path: '/data/capture', value: '$payload.capabilities.capture' },
+      { op: 'replace', path: '/data/version', value: '$payload.capabilities.version' },
+      { op: 'replace', path: '/data/operators',
+        value: { $default: ['$payload.capabilities.operators', []] } },
+      { op: 'replace', path: '/data/pushableOperators',
+        value: { $default: ['$payload.capabilities.pushableOperators', []] } },
+    ],
+  },
+  'data/rows': { patch: [{ op: 'replace', path: '/data/rows', value: '$payload.rows' }] },
+  'data/results': {
+    patch: [
+      { op: 'replace', path: '/data/results', value: '$payload.results' },
+      { op: 'replace', path: '/data/explain', value: '$payload.explain' },
+      { op: 'replace', path: '/data/error', value: null },
+    ],
+  },
+  'data/live': {
+    patch: [
+      { op: 'replace', path: '/data/live/rows', value: '$payload.rows' },
+      { op: 'replace', path: '/data/live/seq', value: null },
+    ],
+  },
+  'data/live-event': {
+    patch: [
+      { op: 'replace', path: '/data/live/rows', value: '$payload.rows' },
+      { op: 'replace', path: '/data/live/seq', value: '$payload.seq' },
+    ],
+  },
+  // the owner's live-registration count (data.lives), refreshed by the
+  // boundary after each of its own live events — how a departed tab's
+  // released subscription becomes visible
+  'data/lives': { patch: [{ op: 'replace', path: '/data/live/regs', value: '$payload.count' }] },
+  'data/migrated': { patch: [{ op: 'replace', path: '/data/migration', value: '$payload.report' }] },
+  'data/error': { patch: [{ op: 'replace', path: '/data/error', value: '$payload.message' }] },
+  // the boot protocol's two terminal states beside `data/opened` (an
+  // owner's or a memory tab's first open): a CLIENT tab is ready once it
+  // is attached, and a failed stage is the named, stable error record
+  'data/ready': { patch: [{ op: 'replace', path: '/data/status', value: 'ready' }] },
+  'data/boot-error': {
+    patch: [
+      { op: 'replace', path: '/data/status', value: 'error' },
+      { op: 'replace', path: '/data/boot', value: '$payload' },
+      { op: 'replace', path: '/data/error', value: '$payload.message' },
+      // nothing about the store is known after a failed boot
+      { op: 'replace', path: '/data/topology', value: '—' },
+      { op: 'replace', path: '/data/vfs', value: '—' },
+      { op: 'replace', path: '/data/refusal', value: null },
+    ],
+  },
+  'data/retry': {
+    patch: [
+      { op: 'replace', path: '/data/status', value: 'boot' },
+      { op: 'replace', path: '/data/boot', value: null },
+      { op: 'replace', path: '/data/error', value: null },
+      { op: 'replace', path: '/data/topology', value: '—' },
+      { op: 'replace', path: '/data/vfs', value: '—' },
+      { op: 'replace', path: '/data/refusal', value: null },
+    ],
+    effects: [{ run: 'data-retry' }],
+  },
+
+};
+
+DATA_ACTIONS['data/resume'] = { patch: [{ op: 'replace', path: '/data/status', value: 'boot' }], effects: [{ run: 'data-resume' }] };
+
+DATA_ACTIONS['data/replace'] = { $if: [
+  { $eq: [{ modelText: '$.data.modelText', queryText: '$.data.queryText' }, '$payload.expected'] },
+  { patch: [
+    { op: 'replace', path: '/data/modelText', value: '$payload.modelText' },
+    { op: 'replace', path: '/data/queryText', value: '$payload.queryText' },
+  ], effects: [{ run: 'data-accepted', with: '$payload.requestId' }] },
+  { effects: [{ run: 'data-refused', with: '$payload.requestId' }] },
+] };
+DATA_ACTIONS['data/execute'] = { effects: [{ run: 'data-editor-run', with: {
+  requestId: '$payload.requestId', operation: '$payload.operation', externals: '$payload.externals',
+  text: { $if: [{ $eq: ['$payload.operation', 'open'] }, '$.data.modelText', '$.data.queryText'] },
+} }] };

package/src/component/data/index.js

@@ -0,0 +1,10 @@
+//@ts-check
+export { createTransport } from '../../data/transport.js';
+export { createDataRuntime } from '../../data/runtime.js';
+export { createDataState } from '../../data/state.js';
+export { DATA_ACTIONS } from './actions.js';
+export { DATA_RULES } from './views.js';
+export { dataViewModel, oracleSummary } from './viewmodel.js';
+export { createProjectDataRuntime } from './project-widget.js';
+export { createDataController } from '../../data/editor.js';
+export { mountDataEditor } from './mount.js';

package/src/component/data/mount.js

@@ -0,0 +1,63 @@
+//@ts-check
+/** Mount the same Data component used by composed hosts, with an injected transport. */
+import { createApp, formEventFields } from '@jarenjs/app';
+import { createDataRuntime } from '../../data/runtime.js';
+import { createDataController } from '../../data/editor.js';
+import { createDataState } from '../../data/state.js';
+import { DATA_ACTIONS } from './actions.js';
+import { DATA_RULES } from './views.js';
+import { dataViewModel } from './viewmodel.js';
+
+/**
+ * @param {HTMLElement|null} node
+ * @param {{ model: any, query: any, transport: () => ReturnType<typeof import('../../data/transport.js').createTransport>,
+ *   seeds?: any[], createRow?: (text: string) => any, migration?: (model: any, collection: string) => { to: any, id: string },
+ *   trip?: any, corpus?: () => Promise<any>, executor?: string, operators?: { toOptions: () => any }, lifecycleTarget?: any,
+ *   schedule?: (flush: () => void) => void, onError?: (error: Error) => void }} options
+ */
+export function mountDataEditor(node, options) {
+  let app, settleReady, disposed = false, active = true;
+  /** @type {Promise<{ ok: boolean, error?: string | { code: string, stage: string, message: string } }>} */
+  let ready = new Promise(resolve => { settleReady = resolve; });
+  const runtime = createDataRuntime(options), controller = createDataController({ ...options, getApp: () => app, runtime });
+  app = createApp({
+    state: { active: true, data: createDataState() }, actions: { ...DATA_ACTIONS,
+      'data/active': { patch: [{ op: 'replace', path: '/active', value: '$payload' },
+        { op: 'replace', path: '/data/status', value: { $if: ['$payload', 'boot', '$.data.status'] } }] },
+    }, subs: [{ run: 'data-owner', when: '$.active' }],
+    view: { $jslt: '0.1', modes: { data: { unmatched: 'error' } }, rules: [
+      { match: '$', body: { $apply: ['$.ui.data', 'data'] } }, ...DATA_RULES,
+    ] },
+  }, {
+    node, document: node?.ownerDocument, schedule: options.schedule, onError: options.onError,
+    eventFields: formEventFields(), effects: { ...runtime.effects, ...controller.effects },
+    subs: { 'data-owner': runtime.ownerSub }, viewModel: state => ({ ui: { data: dataViewModel(state, options) } }),
+  });
+  const stopReady = app.subscribe(state => {
+    if (!state.active) return;
+    if (state.data.status === 'ready') settleReady({ ok: true });
+    else if (state.data.status === 'error') settleReady({ ok: false, error: state.data.boot });
+  });
+  controller.attach();
+  return { get ready() { return ready; }, read: controller.read, validate: controller.validate, replace: controller.replace,
+    apply: controller.apply,
+    /** @param {Parameters<typeof controller.run>[0]} [options] */
+    run(options = {}) { return active && !disposed ? controller.run(options)
+      : Promise.resolve({ ok: false, error: disposed ? 'The Data editor is disposed.' : 'The Data editor is inactive.' }); },
+    subscribe: controller.subscribe,
+    /** Release ownership on route exit while retaining every raw editing buffer.
+     * Reactivation reopens the last accepted model and never seeds over typing.
+     * @param {boolean} next */
+    setActive(next) {
+      if (disposed) return Promise.resolve({ ok: false, error: 'The Data editor is disposed.' });
+      if (next === active) return ready;
+      active = next;
+      settleReady({ ok: false, error: 'The Data editor is inactive.' });
+      ready = next ? new Promise(resolve => { settleReady = resolve; })
+        : Promise.resolve({ ok: false, error: 'The Data editor is inactive.' });
+      app.dispatch('data/active', next);
+      return ready;
+    },
+    dispose() { if (disposed) return; disposed = true; settleReady({ ok: false, error: 'The Data editor is disposed.' }); stopReady(); controller.dispose(); app.destroy(); },
+  };
+}

package/src/component/data/project-widget.js

@@ -0,0 +1,164 @@
+//@ts-check
+/** Project-owned model workers. File switches release views/subscriptions;
+ * model changes, deletion, project replacement and app teardown release stores. */
+import { openPortClient } from '@jarenjs/contract/port';
+import { createDomRenderer } from '@jarenjs/view';
+import { semanticKey } from '@jarenjs/core/object';
+import { applyJSONPatch } from '@jarenjs/json/patch';
+import { resolveProjectFile, projectFileContext } from '../../index.js';
+import { dataContract as contract } from '../../data/contract.js';
+
+const SCAN = [{ $for: { row: '$[*]' }, $return: '$row' }];
+const unwrap = (outcome) => {
+  if (outcome.ok) return outcome.value;
+  throw Object.assign(new Error(outcome.error.details?.message ?? outcome.error.message), {
+    code: outcome.error.details?.code ?? outcome.error.code,
+  });
+};
+
+export function createProjectDataRuntime(options = {}) {
+  const workers = new Map();
+  const retire = (name) => {
+    const entry = workers.get(name);
+    if (!entry) return;
+    workers.delete(name);
+    entry.client.close(); entry.worker.terminate();
+  };
+  const dispose = () => { for (const name of [...workers.keys()]) retire(name); };
+  const sync = (project, reset = false) => {
+    if (reset) { dispose(); return; }
+    for (const name of workers.keys()) {
+      if (!project.files.some((f) => f.name === name && f.kind === 'model')) retire(name);
+    }
+  };
+  const acquire = (project, file) => {
+    const route = projectFileContext(project, file);
+    const modelFile = file.kind === 'model' ? file : route.model;
+    if (!modelFile) throw new Error('Choose a model file for this query.');
+    const model = resolveProjectFile(project, modelFile.name).doc;
+    const names = Object.keys(model.collections ?? {});
+    const collection = route.collection ?? (names.length === 1 ? names[0] : null);
+    if (collection === null || !names.includes(collection))
+      throw new Error('Choose a collection from the model in the file routing controls.');
+    let seed = null;
+    if (modelFile.input !== undefined) {
+      const source = projectFileContext(project, modelFile).input;
+      seed = JSON.parse(source.text);
+      if (!seed || typeof seed !== 'object' || Array.isArray(seed)
+        || Object.entries(seed).some(([name, rows]) => !names.includes(name) || !Array.isArray(rows)))
+        throw new Error('A model seed must be an object mapping collection names to arrays of documents.');
+    }
+    const key = semanticKey({ model, seed });
+    let entry = workers.get(modelFile.name);
+    if (entry && entry.key !== key) { retire(modelFile.name); entry = null; }
+    if (!entry) {
+      if (!options.createWorker) throw new Error('This project host has no model worker factory.');
+      const worker = options.createWorker();
+      const client = openPortClient(contract, { channel: worker, timeoutMs: 15_000 });
+      const request = async (op, args) => unwrap(await client.invoke(op, args));
+      entry = { worker, client, key, request, ready: null };
+      workers.set(modelFile.name, entry);
+      const owned = entry;
+      entry.ready = request('data.init', null).then(async () => {
+        const opened = await request('data.open', { model });
+        for (const [collection, rows] of Object.entries(seed ?? {}))
+          for (const doc of rows) await request('data.insert', { collection, doc });
+        return opened;
+      })
+        .catch((error) => {
+          if (workers.get(modelFile.name) === owned) retire(modelFile.name);
+          throw error;
+        });
+    }
+    return { entry, collection, modelName: modelFile.name };
+  };
+
+  const draw = (h) => {
+    if (h.dead) return;
+    h.render(['section', { class: 'project-data' },
+      ['p', {}, 'Private SQLite store · ', h.modelName ?? '',
+        ' · rows last until the model or seed changes, or the project closes.'],
+      ['p', { role: 'status', class: 'project-data-status' }, h.status],
+      ['label', {}, 'Insert document (JSON)', ['textarea', {
+        class: 'editor project-data-insert', 'aria-label': 'Insert document (JSON)',
+        value: h.draft, on: { input: 'draft' }, rows: 4,
+      }]],
+      ['button', { class: 'btn', type: 'button', on: { click: 'insert' }, disabled: !h.ready }, 'Insert row'],
+      ['label', {}, 'Delete key (JSON)', ['input', {
+        class: 'editor line', 'aria-label': 'Delete key (JSON)', value: h.deleteDraft, on: { input: 'delete-draft' },
+      }]],
+      ['button', { class: 'btn', type: 'button', on: { click: 'delete' }, disabled: !h.ready }, 'Delete row'],
+      ['h3', {}, 'Result'], ['pre', { class: 'project-data-result' }, JSON.stringify(h.result, null, 2)],
+      ['h3', {}, 'Live result'], ['pre', { class: 'project-data-live' }, JSON.stringify(h.live, null, 2)],
+      ['details', {}, ['summary', {}, 'Query plan'],
+        ['pre', { class: 'project-data-plan' }, JSON.stringify(h.plan, null, 2)]],
+    ]);
+  };
+  const start = async (h, props) => {
+    h.subscription?.stop();
+    const generation = ++h.generation;
+    const current = () => !h.dead && h.generation === generation;
+    h.props = props; h.ready = false; h.status = 'Opening SQLite…'; draw(h);
+    try {
+      const project = { files: props.files };
+      const file = props.files.find((f) => f.name === props.name);
+      const { entry, collection, modelName } = acquire(project, file);
+      h.modelName = modelName;
+      await entry.ready;
+      if (!current()) return;
+      h.entry = entry; h.collection = collection;
+      const document = file.kind === 'model' ? SCAN : resolveProjectFile(project, file.name).doc;
+      const args = { collection, document };
+      const result = await entry.request('data.execute', args);
+      const plan = await entry.request('data.explain', args);
+      if (!current()) return;
+      h.result = result; h.plan = plan; h.ready = true; h.status = 'Ready'; draw(h);
+      h.subscription = entry.client.subscribe('data.live', args, {
+        onSnapshot: (value) => { if (current()) { h.live = value; draw(h); } },
+        onPatch: ({ patch }) => { if (current()) { h.live = applyJSONPatch(h.live, patch); draw(h); } },
+        onError: (outcome) => {
+          if (current()) { h.status = `Live query: ${outcome.error.details?.message ?? outcome.error.message}`; draw(h); }
+        },
+        onEnd: ({ reason }) => { if (current()) { h.status = `Live query ended: ${reason}`; draw(h); } },
+      });
+    }
+    catch (error) { if (current()) { h.status = String(error.message ?? error); draw(h); } }
+  };
+  const widget = {
+    mount(host, props) {
+      const h = { dead: false, generation: 0, draft: '{"id":"n1","title":"New note","points":20}',
+        deleteDraft: '"n1"', result: null, plan: null, live: null, props };
+      h.render = createDomRenderer(host, { onEvent: async (binding, event) => {
+        if (binding === 'draft') { h.draft = event.target.value; return; }
+        if (binding === 'delete-draft') { h.deleteDraft = event.target.value; return; }
+        if (!h.ready) return;
+        const generation = h.generation;
+        try {
+          const value = JSON.parse(binding === 'insert' ? h.draft : h.deleteDraft);
+          await h.entry.request(binding === 'insert' ? 'data.insert' : 'data.delete', {
+            collection: h.collection, ...(binding === 'insert' ? { doc: value } : { key: value }),
+          });
+          if (h.dead || h.generation !== generation) return;
+          h.status = 'Committed'; draw(h);
+        }
+        catch (error) { if (!h.dead && h.generation === generation) { h.status = error.message; draw(h); } }
+      } });
+      void start(h, props); return h;
+    },
+    update(h, props) {
+      if (h.props.files === props.files && h.props.name === props.name && h.props.revision === props.revision) return;
+      void start(h, props);
+    },
+    unmount(h) { h.dead = true; h.generation++; h.subscription?.stop(); h.render.destroy(); },
+  };
+  const execute = async (project, name) => {
+    const file = project.files.find((f) => f.name === name);
+    const { entry, collection } = acquire(project, file);
+    await entry.ready;
+    const document = file.kind === 'model' ? SCAN : resolveProjectFile(project, name).doc;
+    const args = { collection, document };
+    const result = await entry.request('data.execute', args);
+    return { result, plan: await entry.request('data.explain', args) };
+  };
+  return { widget, sync, dispose, acquire, execute };
+}

package/src/component/data/viewmodel.js

@@ -0,0 +1,185 @@
+//@ts-check
+import { pickAllowed } from '@jarenjs/core/array';
+import { compileJSONPointer, JSONPOINTER_NOTHING } from '@jarenjs/json/pointer';
+const DATA_PANES = ['store', 'query', 'live', 'trip'];
+/** One compiled key getter per pointer the models have named: the row
+ * list is rebuilt on every live event, and compiling per render would
+ * pay for the pointer over and over. */
+const keyGetters = new Map();
+
+/** @param {string} pointer */
+function keyGetter(pointer) {
+  let get = keyGetters.get(pointer);
+  if (get === undefined) {
+    get = compileJSONPointer(pointer);
+    keyGetters.set(pointer, get);
+  }
+  return get;
+}
+
+/**
+ * The stored documents as a deletable list. The key comes from the
+ * pointer the MODEL declares, not from a member name written here, so a
+ * reader who renames the key in the model pane still gets rows they can
+ * remove. A document the pointer misses is listed without a key and its
+ * control is left out — a delete with nothing to address would be a
+ * button that quietly does nothing.
+ * @param {any[]} rows
+ * @param {string} pointer
+ */
+function rowList(rows, pointer) {
+  const get = keyGetter(pointer);
+  return rows.map((doc, index) => {
+    const key = get(doc);
+    const found = key !== JSONPOINTER_NOTHING;
+    return {
+      index,
+      text: JSON.stringify(doc),
+      ...(found ? { key } : {}),
+    };
+  });
+}
+
+/**
+ * The oracle's verdict, as one line: what ran, what agreed, what was
+ * left out by its marker — or why there is no verdict.
+ * @param {any} oracle
+ * @returns {string}
+ */
+export function oracleSummary(oracle) {
+  if (oracle === null || oracle === undefined) return '';
+  if (oracle.status === 'running') return 'running the spatial corpus through this tab\u2019s store\u2026';
+  if (oracle.status === 'error') return `the spatial corpus could not run here: ${oracle.message}`;
+  const verdict = oracle.agreed === oracle.ran
+    ? `${oracle.executor} agreed with the engine on every entry: ${oracle.agreed} / ${oracle.ran}`
+    : `${oracle.executor} DISAGREED with the engine on ${oracle.ran - oracle.agreed} of ${oracle.ran}`;
+  return `${verdict} (${oracle.entries} entries \u00d7 ${oracle.mappings.join(', ')});`
+    + ` ${oracle.skipped.length} engine-only entries left out by their marker`;
+}
+
+/**
+ * The page's view model — the boundary-exports convention.
+ * @param {any} state
+ * @param {any} [options]
+ */
+export function dataViewModel(state, options = {}) {
+  const TRIP_TEXTS = options.trip?.texts ?? {}, TRIP_CHAIN_TEXT = options.trip?.chainText ?? "";
+  const tripSummary = options.trip?.summary ?? (() => ""), tripMap = options.trip?.map ?? (() => null);
+  const data = state.data;
+  return {
+    collection: data.collection,
+    insertPlaceholder: options.createRow ? `new ${data.collection} title… (enter inserts)` : 'new document as JSON… (enter inserts)',
+    tripAvailable: !!options.trip,
+    oracleAvailable: typeof options.corpus === 'function' || options.features?.oracle === true,
+    migrationAvailable: typeof options.migration === 'function',
+    status: data.status,
+    boot: data.boot,
+    // an operational error line shows beside a booted studio; a boot
+    // failure is rendered by its own card instead
+    plainError: data.status === 'error' ? null : data.error,
+    topology: data.topology,
+    vfs: data.vfs,
+    version: data.version,
+    capture: data.capture,
+    operators: data.operators,
+    pushableOperators: data.pushableOperators,
+    operatorSummary: data.operators.length > 0
+      ? `${data.operators.length} registered · ${data.pushableOperators.length} pushed to SQLite as UDFs`
+      : data.topology === 'client' && data.capture === '—' ? 'the owner\'s (awaiting capabilities)'
+        : data.status === 'ready' ? 'none registered' : '—',
+    operatorList: data.operators.join(' ') || '—',
+    // a copyable query that exercises both paths: $sqrt is a pushable
+    // scalar (a wasm UDF — watch explain() show jaren_p_ in the SQL),
+    // $mean folds a series in the residual (explain names it)
+    operatorSample: JSON.stringify({
+      $for: { it: '$[*]' },
+      $where: { $gt: [{ $sqrt: '$it.points' }, 4] },
+      $return: '$it',
+    }, null, 2),
+    refusal: data.refusal,
+    // a verdict only once the topology is known: during the boot, and
+    // after a boot failure, nothing about OPFS has been learned
+    liveNote: data.vfs === 'indexeddb-snapshot' ? 'Live queries are unavailable while writes await durable snapshots. The Store pane refreshes after each write.' : '',
+    durability: data.vfs === 'opfs-sab'
+      ? 'persistent (OPFS with SharedArrayBuffer and cross-origin isolation)'
+      : data.vfs === 'indexeddb-snapshot'
+        ? 'persistent (atomic IndexedDB snapshots; writes await storage)'
+        : data.vfs === 'opfs-sahpool'
+      ? 'persistent (OPFS access-handle pool, no special headers)'
+      : data.vfs === 'memory' ? 'in-memory (non-durable — persistent storage is unavailable; data lives until reload)'
+        : 'not decided yet — the store has not booted',
+    modelText: data.modelText,
+    queryText: data.queryText,
+    rows: data.rows,
+    rowCount: data.rows.length,
+    rowList: rowList(data.rows, data.keyPointer),
+    rowSummary: `${data.rows.length} stored in ${data.collection}`,
+    results: data.results,
+    resultsJson: JSON.stringify(data.results, null, 1),
+    explain: data.explain === null ? null : {
+      sql: data.explain.sql,
+      params: JSON.stringify(data.explain.params),
+      indexes: data.explain.indexes.join(', ') || '(none)',
+      residual: data.explain.residual === null
+        ? 'none — fully pushed to SQL'
+        : JSON.stringify(data.explain.residual.reasons?.map((reason) => reason.construct)),
+    },
+    live: data.live,
+    liveSummary: `${data.live.rows.length} rows, seq ${data.live.seq ?? 0}`,
+    liveRegs: data.live.regs === null ? '—' : String(data.live.regs),
+    liveJson: JSON.stringify(data.live.rows, null, 1),
+    insertDraft: data.insertDraft,
+    migration: data.migration,
+    migrationSteps: data.migration === null ? ''
+      : data.migration.planned.join('\n'),
+    migrationSummary: data.migration === null ? ''
+      : `applied: ${data.migration.applied.length}`
+        + (data.migration.note ? ` — ${data.migration.note}` : ''),
+    // the spatial-corpus run: its verdict as one line, the disagreements
+    // as lines that name the executor, the entry and the query, and every
+    // answer as JSON for the reader (and the e2e spec) to check
+    oracle: data.oracle,
+    oracleDone: data.oracle?.status === 'done',
+    oracleDisagreed: (data.oracle?.disagreements?.length ?? 0) > 0,
+    oracleSummary: oracleSummary(data.oracle),
+    oracleDisagreements: (data.oracle?.disagreements ?? []).join('\n'),
+    oracleResultsJson: data.oracle?.status === 'done' ? JSON.stringify({
+      executor: data.oracle.executor,
+      vfs: data.vfs,
+      source: data.oracle.source,
+      ran: data.oracle.ran,
+      agreed: data.oracle.agreed,
+      skipped: data.oracle.skipped,
+      results: data.oracle.results,
+    }) : '',
+    // the spatial round trip: the editable CSV, the constant halves a
+    // reader can open (the stylesheet, the model, the chain and the
+    // document it emits), and the report — its explain() members named
+    // one by one so the two stages are legible, and the map drawn
+    // through the geojson format's preview hint
+    tripCsv: data.trip.csv,
+    tripStylesheet: TRIP_TEXTS.stylesheet,
+    tripModel: TRIP_TEXTS.model,
+    tripChain: TRIP_CHAIN_TEXT,
+    tripQuery: TRIP_TEXTS.query,
+    tripRegion: TRIP_TEXTS.region,
+    trip: data.trip.report,
+    tripStatus: data.trip.report?.status ?? 'idle',
+    tripDone: data.trip.report?.status === 'done',
+    tripSummary: tripSummary(data.trip.report),
+    tripResultsJson: data.trip.report?.status === 'done'
+      ? JSON.stringify(data.trip.report.results, null, 1) : '',
+    tripExplainSql: data.trip.report?.explain?.sql ?? '',
+    tripPrefilters: JSON.stringify(data.trip.report?.explain?.prefilters ?? []),
+    tripNarrative: data.trip.report?.explain?.scanNarrative ?? '',
+    tripIndexes: (data.trip.report?.explain?.indexes ?? []).join(', ') || '(none)',
+    tripResidual: data.trip.report?.explain === undefined || data.trip.report?.explain === null ? ''
+      : data.trip.report.explain.residual === null
+        ? 'none \u2014 fully pushed to SQL'
+        : JSON.stringify(data.trip.report.explain.residual.reasons?.map((reason) => reason.construct)),
+    tripMap: tripMap(data.trip.report),
+    error: data.error,
+    // the phone pane (Store · Query · Live · Round trip)
+    mobilePane: pickAllowed(data.mobilePane, DATA_PANES, 'query'),
+  };
+}