@jarenjs/studio 0.83.3 → 0.85.0

package/src/component/shared/ui.js

@@ -0,0 +1,134 @@
+//@ts-check
+/**
+ * The generic render-node vocabulary — mode 'ui'. Boundaries (and the
+ * docs content) emit kind-tagged JSON nodes; one rule per kind turns
+ * them into vnodes. This is the site's component library, as data:
+ * cards, tables, callouts, code blocks, error blocks, bar charts,
+ * collapsibles, rendered Markdown articles, a search box and a
+ * show-more button.
+ */
+
+/**
+ * The rule for one deep-linkable tab in a `nav.tabs` strip. Each page
+ * holds its tab entries (`{ href, label, active }`) at a different
+ * location, hence the match parameter.
+ * @param {string} match - the JSONPath to the tab entries.
+ * @param {string} mode - the page's dispatch mode.
+ */
+export const tabRule = (match, mode) => ({
+  match, mode,
+  body: ['a', {
+    href: '$.href',
+    class: { $if: ['$.active', 'tab active', 'tab'] },
+  }, '$.label'],
+});
+
+export const UI_RULES = [
+  {
+    match: "$..[?@.kind == 'p']", mode: 'ui',
+    body: ['p', { class: 'doc-p' }, '$.text'],
+  },
+  {
+    match: "$..[?@.kind == 'cards']", mode: 'ui',
+    body: ['div', { class: 'cards' }, [{ $apply: '$.items[*]' }]],
+  },
+  {
+    match: "$..[?@.kind == 'card']", mode: 'ui',
+    body: ['div', { class: 'stat-card' },
+      ['p', { class: 'stat-title' }, '$.title'],
+      ['p', { class: 'stat-value' }, '$.value'],
+      { $if: ['$.note', ['p', { class: 'stat-note' }, '$.note']] },
+    ],
+  },
+  {
+    match: "$..[?@.kind == 'table']", mode: 'ui',
+    body: ['div', { class: 'table-card' },
+      ['h3', {}, '$.title'],
+      ['div', { class: 'table-scroll' },
+        ['table', {},
+          ['thead', {}, ['tr', {}, [{ $apply: '$.head[*]' }]]],
+          ['tbody', {}, [{ $apply: '$.rows[*]' }]],
+        ],
+      ],
+      { $if: ['$.note', ['p', { class: 'table-note' }, '$.note']] },
+    ],
+  },
+  {
+    match: "$..[?@.kind == 'table']..head[*]", mode: 'ui',
+    body: ['th', {}, '$'],
+  },
+  {
+    match: "$..[?@.kind == 'row']", mode: 'ui',
+    body: ['tr', { class: { $if: ['$.strong', 'strong', ''] } }, [{ $apply: '$.cells[*]' }]],
+  },
+  {
+    match: "$..[?@.kind == 'row']..cells[*]", mode: 'ui',
+    body: ['td', {}, '$'],
+  },
+  {
+    match: "$..[?@.kind == 'callout']", mode: 'ui',
+    body: ['div', { class: 'callout' },
+      ['h3', {}, '$.title'],
+      ['p', {}, '$.text'],
+      { $if: ['$.href', ['a', { href: '$.href', class: 'btn' }, '$.link']] },
+    ],
+  },
+  {
+    match: "$..[?@.kind == 'code']", mode: 'ui',
+    body: ['div', { class: 'code-card' },
+      { $if: [{ $or: ['$.title', '$.badge'] },
+        ['div', { class: 'code-head' },
+          { $if: ['$.title', ['span', { class: 'code-title' }, '$.title']] },
+          { $if: ['$.badge', ['span', { class: 'code-badge' }, '$.badge']] },
+        ]] },
+      ['pre', { class: 'code-block' }, ['code', {}, '$.text']],
+    ],
+  },
+  {
+    match: "$..[?@.kind == 'error']", mode: 'ui',
+    body: ['div', { class: 'error-card' },
+      ['p', { class: 'error-title' }, '$.title'],
+      ['p', { class: 'error-message' }, '$.message'],
+      { $if: ['$.detail', ['p', { class: 'error-detail' }, '$.detail']] },
+    ],
+  },
+  {
+    match: "$..[?@.kind == 'details']", mode: 'ui',
+    body: ['details', { class: 'details-card' },
+      ['summary', {}, '$.summary'],
+      [{ $apply: '$.items[*]' }],
+    ],
+  },
+  {
+    // The chart card embeds a ready-made SVG vnode from
+    // @jarenjs/charts — the value splices in verbatim, no dispatch.
+    match: "$..[?@.kind == 'chart']", mode: 'ui',
+    body: ['div', { class: 'chart-card' },
+      { $if: ['$.title', ['h3', {}, '$.title']] },
+      '$.vnode',
+      { $if: ['$.note', ['p', { class: 'table-note' }, '$.note']] },
+    ],
+  },
+  {
+    // A package-owned section: the md component has already produced the
+    // vnode, so it splices in verbatim — no dispatch, exactly like a chart.
+    match: "$..[?@.kind == 'article']", mode: 'ui',
+    body: ['div', { class: 'doc-md' }, '$.vnode'],
+  },
+  {
+    match: "$..[?@.kind == 'search']", mode: 'ui',
+    body: ['input', {
+      type: 'search',
+      class: 'search-input',
+      placeholder: '$.placeholder',
+      value: '$.value',
+      on: { input: '$.action' },
+    }],
+  },
+  {
+    match: "$..[?@.kind == 'more']", mode: 'ui',
+    body: ['div', { class: 'more-row' },
+      ['button', { type: 'button', class: 'btn', on: { click: '$.action' } }, '$.label'],
+    ],
+  },
+];

package/src/data/boot-stages.js

@@ -0,0 +1,202 @@
+//@ts-check
+/**
+ * @file The data studio's boot as a closed, finite protocol. A browser
+ * store boots through five stages — the worker starting, the SQLite
+ * wasm build initializing, the OPFS pool being acquired, the topology
+ * being decided, the first store open — and every one of them finishes
+ * as a success or as a STABLE, NAMED failure: `{ code: 'DATA_BOOT',
+ * stage, message }`. An outer deadline can say only that something
+ * stopped; a named stage says which resource must be released and what
+ * a consumer can report. So each stage carries its own budget, a stage
+ * that overruns it fails under its own name, and a stage that settles
+ * late changes nothing.
+ *
+ * This module is the pure half: the stage names, the budgets, the error
+ * shape and the runner that attaches a timer to a stage and clears it
+ * on either outcome. The page's transport and the worker announce their
+ * stages through it; the browser-shaped work (a `Worker`, a
+ * `BroadcastChannel`, the wasm module) stays in the boundary and the
+ * worker, where Node cannot follow — which is why the runner takes its
+ * timers as an injection and a test drives it with millisecond budgets.
+ */
+
+/** The five stages, in the order a boot passes through them. */
+export const BOOT_STAGES = Object.freeze(['worker-start', 'sqlite-init', 'vfs-acquire', 'topology', 'store-open']);
+
+/** The code every boot failure carries, whatever its stage. */
+export const BOOT_ERROR_CODE = 'DATA_BOOT';
+
+/**
+ * The production budgets, in milliseconds: the wasm build and the first
+ * store open are real work and get room; the pool install is bounded
+ * where an engine has been seen never to settle it; a topology decision
+ * is a lock probe or a ping window.
+ * @type {Readonly<Record<string, number>>}
+ */
+export const DEFAULT_BOOT_BUDGETS = Object.freeze({
+  'worker-start': 15_000,
+  'sqlite-init': 30_000,
+  'vfs-acquire': 8_000,
+  'topology': 5_000,
+  'store-open': 30_000,
+});
+
+/**
+ * The one failure shape a boot can end in: the stage that failed, the
+ * cause's message, and the fixed code.
+ */
+export class DataBootError extends Error {
+  /**
+   * @param {string} stage - one of {@link BOOT_STAGES}
+   * @param {string} message - what happened, for a person
+   * @param {unknown} [cause]
+   */
+  constructor(stage, message, cause = undefined) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'DataBootError';
+    /** @type {typeof BOOT_ERROR_CODE} */
+    this.code = BOOT_ERROR_CODE;
+    /** @type {string} */
+    this.stage = stage;
+  }
+
+  /** The page-visible record: exactly `{ code, stage, message }`. */
+  toJSON() {
+    return { code: this.code, stage: this.stage, message: this.message };
+  }
+}
+
+/**
+ * Any failure as a boot failure under `stage`: a `DataBootError` keeps
+ * the stage it already names, anything else is wrapped with its message.
+ * @param {string} stage
+ * @param {unknown} error
+ * @returns {DataBootError}
+ */
+export function bootFailure(stage, error) {
+  if (error instanceof DataBootError) return error;
+  const raised = /** @type {any} */ (error);
+  const message = typeof raised?.message === 'string' && raised.message.length > 0
+    ? raised.message : String(error);
+  return new DataBootError(stage, message, error);
+}
+
+/**
+ * Resolve the budgets a boot runs under: the defaults, overridden per
+ * stage by a positive finite number; anything else is ignored rather than
+ * turned into a zero budget nobody meant.
+ * @param {unknown} overrides - a partial `{ stage: ms }` record, or not
+ * @returns {Readonly<Record<string, number>>}
+ */
+export function resolveBootBudgets(overrides) {
+  const budgets = { ...DEFAULT_BOOT_BUDGETS };
+  if (overrides !== null && typeof overrides === 'object') {
+    for (const stage of BOOT_STAGES) {
+      const value = /** @type {any} */ (overrides)[stage];
+      if (typeof value === 'number' && Number.isFinite(value) && value > 0) budgets[stage] = value;
+    }
+  }
+  return Object.freeze(budgets);
+}
+
+/**
+ * The stage runner. `run(stage, work)` starts `stage`'s timer, calls
+ * `work(advance)` and settles ONCE: with the work's value, with the
+ * work's failure named under the stage current at that moment, or —
+ * when the current stage's budget runs out first — with a
+ * `DataBootError` naming that stage. `advance(next)` moves the run to
+ * a later stage: the previous timer is cleared and the next stage's
+ * budget starts, so a multi-stage piece of work (the worker's init,
+ * which announces its stages as it passes them) is bounded per stage
+ * from the page. The timer is cleared on every outcome, and a late
+ * settlement after a timeout is dropped: the failure a consumer saw is
+ * the failure it keeps.
+ *
+ * @param {{ budgets?: Readonly<Record<string, number>>,
+ *   setTimer?: (fn: () => void, ms: number) => any,
+ *   clearTimer?: (handle: any) => void }} [options] - budgets per stage
+ *   and the timer pair (the platform's by default)
+ */
+export function createStageRunner(options = {}) {
+  const budgets = options.budgets ?? DEFAULT_BOOT_BUDGETS;
+  const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+  const pending = new Set();
+  let disposed = false;
+
+  /**
+   * @param {string} stage
+   * @param {(advance: (next: string) => void) => any} work
+   * @returns {Promise<any>}
+   */
+  const run = (stage, work) => new Promise((resolve, reject) => {
+    if (disposed) { reject(new DataBootError(stage, 'the boot runner is disposed')); return; }
+    if (!BOOT_STAGES.includes(stage)) {
+      reject(new TypeError(`a boot stage is one of ${BOOT_STAGES.join(', ')}, not '${stage}'`));
+      return;
+    }
+    let current = stage;
+    let settled = false;
+    /** @type {any} */
+    let timer = null;
+    const stop = () => {
+      if (timer !== null) {
+        clearTimer(timer);
+        timer = null;
+      }
+    };
+    const cancel = () => {
+      if (settled) return;
+      settled = true; stop(); pending.delete(cancel);
+      reject(new DataBootError(current, 'the boot was cancelled'));
+    };
+    pending.add(cancel);
+    const arm = () => {
+      stop();
+      const budget = budgets[current];
+      timer = setTimer(() => {
+        timer = null;
+        if (settled) return;
+        settled = true;
+        pending.delete(cancel);
+        reject(new DataBootError(current, `${current} did not finish within ${budget} ms`));
+      }, budget);
+    };
+    const advance = (/** @type {string} */ next) => {
+      if (settled) return;
+      if (!BOOT_STAGES.includes(next)) return;
+      current = next;
+      arm();
+    };
+    arm();
+    let out;
+    try {
+      out = work(advance);
+    }
+    catch (error) {
+      settled = true;
+      pending.delete(cancel);
+      stop();
+      reject(bootFailure(current, error));
+      return;
+    }
+    Promise.resolve(out).then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        pending.delete(cancel);
+        stop();
+        resolve(value);
+      },
+      (error) => {
+        if (settled) return;
+        settled = true;
+        pending.delete(cancel);
+        stop();
+        reject(bootFailure(current, error));
+      });
+  });
+
+  const dispose = () => { disposed = true; for (const cancel of [...pending]) cancel(); };
+  return Object.freeze({ run, budgets, dispose });
+}

package/src/data/browser-worker.js

@@ -0,0 +1,247 @@
+//@ts-check
+/** Shared owner/client worker protocol. Hosts supply the concrete initializer and storage identity. */
+import { wasmDriver, sqlite3Handle, indexedDbSnapshotHandle, openSnapshotStorage } from '@jarenjs/db/wasm';
+import { servePort } from '@jarenjs/contract/port';
+import { selectBrowserStorage, discoverStorageOwner } from './storage.js';
+import { createDataHandlers } from './handlers.js';
+import { dataContract } from './contract.js';
+/**
+ * The SQLite module is injected, like the handle consumed by @jarenjs/db/wasm.
+ * No package import or worker URL is chosen by this component.
+ * @param {{ initialize: () => Promise<any>, scope: any, createChannel: (name: string) => any,
+ *   identity: { channel: string, pool: string, database: string, snapshots: string, lock: string }, operators?: any }} env
+ * @returns {{ dispose: () => Promise<void> }}
+ */
+export function createBrowserDataWorker(env) {
+const { channel: CHANNEL, pool: POOL, database: DB_NAME, snapshots: SNAPSHOTS, lock: OWNER_LOCK } = env.identity;
+if ([CHANNEL, POOL, DB_NAME, SNAPSHOTS, OWNER_LOCK].some(value => typeof value !== 'string' || value.length === 0))
+  throw new TypeError('Data storage requires explicit channel, pool, database, snapshots and lock identities.');
+const OPERATORS = env.operators;
+const context = {
+  /** @type {any} */ sqlite3: null,
+  /** @type {any} */ poolUtil: null,
+  vfs: 'memory',
+  isOwner: false,
+  locked: false,
+  releaseOwner: null,
+  handle: null,
+  unlink: null,
+};
+
+const channel = env.createChannel(CHANNEL);
+let disposed = false, peerServer = null, initial = null;
+const pings = new Set();
+const current = () => { if (disposed) throw new Error('The Data worker is disposed.'); };
+
+/** Announce the boot stage this worker is entering (`lib/boot-stages.js`):
+ * the page bounds each stage from its side and names it on a timeout, so
+ * an install some engines never settle fails as `vfs-acquire` — never as
+ * an OPFS absence, which is a different answer with a different remedy. */
+const enter = stage => { current(); env.scope.postMessage({ boot: stage }); };
+
+/** Ask the channel whether an OPFS owner already exists — the fallback
+ * for a host with no `LockManager`. A running owner answers its pong;
+ * silence means only that no owner answered in this window. Without Web
+ * Locks the storage-acquisition refusal and a longer retry decide the
+ * next step; a busy owner cannot answer while SQLite runs synchronously. */
+function pingForOwner(ms = 600) {
+  return new Promise((resolve) => {
+    const token = `ping-${env.scope.crypto.randomUUID()}`;
+    const onPong = (event) => {
+      if (event.data?.pong === token) {
+        finish({ vfs: event.data.vfs });
+      }
+    };
+    let timer;
+    const finish = value => { clearTimeout(timer); channel.removeEventListener('message', onPong); pings.delete(stop); resolve(value); };
+    const stop = () => finish(false); pings.add(stop);
+    channel.addEventListener('message', onPong);
+    timer = setTimeout(stop, ms);
+    channel.postMessage({ ping: token });
+  });
+}
+
+/** The host's lock manager, where it has one. */
+const locks = () => env.scope.navigator?.locks;
+
+/** Acquire the browser-owned lock before selecting any durable storage. */
+function holdOwnerLock() {
+  const manager = locks();
+  if (manager === undefined) return Promise.resolve(true);
+  return new Promise((resolve, reject) => {
+    manager.request(OWNER_LOCK, { ifAvailable: true }, (lock) => {
+      if (lock === null) { resolve(false); return; }
+      if (disposed) { resolve(false); return; }
+      context.locked = true;
+      resolve(true);
+      return new Promise((release) => { context.releaseOwner = release; });
+    }).catch(reject);
+  });
+}
+
+/** A disposable write/close/reopen proves the selected VFS, not its name. */
+async function probeVfs(DbClass, vfs, unlink) {
+  const path = `${DB_NAME}.probe`;
+  let db;
+  try {
+    db = new DbClass(path, 'c');
+    if (!context.sqlite3.capi.sqlite3_js_db_uses_vfs(db.pointer, vfs))
+      throw new Error(`the opened database did not use ${vfs}`);
+    db.exec('CREATE TABLE IF NOT EXISTS probe(n); DELETE FROM probe; INSERT INTO probe VALUES(73)');
+    db.close();
+    db = new DbClass(path, 'r');
+    if (db.selectValue('SELECT n FROM probe') !== 73) throw new Error('VFS reopen did not preserve the probe');
+  }
+  finally { db?.close(); await unlink(path); }
+}
+
+async function initialize() {
+  current();
+  enter('sqlite-init');
+  context.sqlite3 = await env.initialize();
+  current();
+  enter('vfs-acquire');
+  if (!(await holdOwnerLock())) {
+    enter('topology');
+    const owner = await pingForOwner();
+    return { topology: 'client', vfs: owner?.vfs ?? 'owner-selected',
+      version: context.sqlite3.version.libVersion,
+      refusal: { code: 'JD2061', message: 'another context owns the database; this tab uses its connection over a BroadcastChannel' } };
+  }
+  current();
+  const sqlite3 = context.sqlite3;
+  const selected = await selectBrowserStorage({
+    isolated: env.scope.crossOriginIsolated === true,
+    sharedArrayBuffer: typeof env.scope.SharedArrayBuffer === 'function',
+    sab: async () => {
+      if (!sqlite3.capi.sqlite3_vfs_find('opfs') || typeof sqlite3.oo1.OpfsDb !== 'function')
+        throw new Error('the SharedArrayBuffer OPFS VFS is not registered');
+      const root = await env.scope.navigator.storage.getDirectory();
+      // The pinned build removes its private sqlite3.opfs helper after
+      // initialization. Delete closed files through the public storage API.
+      const unlink = async (path) => {
+        for (const suffix of ['', '-journal', '-wal', '-shm']) {
+          try { await root.removeEntry(path.replace(/^\//, '') + suffix); }
+          catch (error) { if (error.name !== 'NotFoundError') throw error; }
+        }
+      };
+      await probeVfs(sqlite3.oo1.OpfsDb, 'opfs', unlink);
+      return { handle: sqlite3Handle(sqlite3, { DbClass: sqlite3.oo1.OpfsDb }), unlink };
+    },
+    sah: async () => {
+      context.poolUtil = await sqlite3.installOpfsSAHPoolVfs({ name: POOL });
+      if (disposed) context.poolUtil.pauseVfs?.();
+      current();
+      const unlink = (path) => context.poolUtil.unlink(path);
+      await probeVfs(context.poolUtil.OpfsSAHPoolDb, context.poolUtil.vfsName, unlink);
+      return { handle: sqlite3Handle(sqlite3, { DbClass: context.poolUtil.OpfsSAHPoolDb }), unlink };
+    },
+    indexedDB: async () => {
+      if (!context.locked) throw new Error('IndexedDB snapshots require an observed exclusive Web Lock');
+      const handle = indexedDbSnapshotHandle(sqlite3, { name: SNAPSHOTS });
+      const driver = wasmDriver(handle);
+      const path = `${DB_NAME}.probe`;
+      let db;
+      const unlink = async (key) => {
+        const storage = await openSnapshotStorage(env.scope.indexedDB, SNAPSHOTS);
+        try { await storage.remove(key); } finally { storage.close(); }
+      };
+      try {
+        db = await driver.open(path);
+        await db.exec('CREATE TABLE IF NOT EXISTS probe(n); DELETE FROM probe; INSERT INTO probe VALUES(73)');
+        await db.close();
+        db = await driver.open(path);
+        if ((await (await db.prepare('SELECT n FROM probe')).get()).n !== 73)
+          throw new Error('IndexedDB reopen did not preserve the probe');
+      }
+      finally { await db?.close(); await unlink(path); }
+      return { handle, unlink };
+    },
+  });
+  current();
+  enter('topology');
+  if (selected.held || (!selected.durable && !context.locked)) {
+    const owner = await discoverStorageOwner(selected, pingForOwner);
+    if (owner) {
+      context.releaseOwner?.();
+      context.locked = false;
+      return { topology: 'client', vfs: owner.vfs, version: sqlite3.version.libVersion,
+        refusal: { code: 'JD2061', message: 'another context answered as the database owner; this tab uses its connection over a BroadcastChannel' } };
+    }
+  }
+  context.vfs = selected.vfs;
+  context.handle = selected.handle ?? sqlite3Handle(sqlite3);
+  context.unlink = selected.unlink ?? (() => {});
+  context.isOwner = selected.durable;
+  if (context.isOwner) serveChannel();
+  else { context.releaseOwner?.(); context.locked = false; }
+  const fallback = selected.failures.map((entry) => `${entry.vfs}: ${entry.reason}`).join('; ');
+  return { topology: selected.durable ? 'owner' : 'memory', vfs: selected.vfs,
+    durable: selected.durable, failures: selected.failures, version: sqlite3.version.libVersion,
+    ...(fallback ? { refusal: { code: 'JD2061', message: `${fallback}. Selected ${selected.vfs}`
+      + (selected.durable ? ' (persistent).' : ' (non-durable; data lasts until reload).') } } : {}) };
+}
+
+/** Every reopen drops the live registrations of every tab, so every tab
+ * is told. The notice travels beside the contract frames on both
+ * transports and is distinguishable by shape, exactly as the
+ * owner-discovery frames are. */
+function announce(notice) {
+  const message = { ...notice, channel: CHANNEL };
+  channel.postMessage(message);
+  env.scope.postMessage(message);
+}
+
+const table = createDataHandlers({
+  init: () => initial ??= initialize(),
+  makeDriver: () => wasmDriver(context.handle),
+  // the oracle's throwaway store is always a plain in-memory database,
+  // whichever VFS this context settled on: the pool's class is for the
+  // one database it holds, and the corpus needs execution, not persistence
+  makeScratchDriver: () => wasmDriver(sqlite3Handle(context.sqlite3)),
+  path: () => (context.vfs === 'memory' ? ':memory:' : DB_NAME),
+  vfs: () => context.vfs,
+  durable: () => context.vfs !== 'memory',
+  unlink: () => context.unlink(DB_NAME),
+  announce,
+  operators: OPERATORS,
+});
+
+// the owning tab's own requests arrive on the worker channel
+const directServer = servePort(dataContract, table.handlers, { channel: env.scope });
+
+let channelServed = false;
+/** Client tabs reach the owner here — registered exactly once, on
+ * becoming the owner; their subscriptions push back on this channel. */
+function serveChannel() {
+  if (channelServed) return;
+  channelServed = true;
+  peerServer = servePort(dataContract, table.clientHandlers, { channel });
+}
+
+// answer an owner-discovery ping (§11) only while actually owning; the
+// contract frames on this channel belong to servePort's own listener
+const onMessage = (event) => {
+  const message = event.data;
+  if (message === null || typeof message !== 'object') return;
+  if (message.ping !== undefined && context.isOwner) {
+    channel.postMessage({ pong: message.ping, vfs: context.vfs });
+  }
+};
+
+channel.addEventListener('message', onMessage);
+env.scope.postMessage({ ready: true });
+let disposal = null;
+return { dispose() {
+  if (disposal) return disposal;
+  disposed = true; context.isOwner = false;
+  for (const stop of [...pings]) stop();
+  directServer.close(); peerServer?.close(); channel.removeEventListener('message', onMessage); channel.close();
+  disposal = table.dispose().finally(() => {
+    try { context.poolUtil?.pauseVfs?.(); }
+    finally { context.releaseOwner?.(); context.locked = false; }
+  });
+  return disposal;
+} };
+
+}

package/src/data/contract.js

@@ -0,0 +1,7 @@
+//@ts-check
+import { compileContract } from '@jarenjs/contract';
+import document from '@jarenjs/studio/contracts/data.contract.json' with { type: 'json' };
+/** @type {ReturnType<typeof compileContract>} */
+export const dataContract = compileContract(document);
+/** @type {{ $contract: string, id: string, operations: Record<string, object> } & Record<string, unknown>} */
+export const dataContractDocument = document;

package/src/data/editor.js

@@ -0,0 +1,95 @@
+//@ts-check
+/** @typedef {{ document: { model: any, query: any }, buffers: { modelText: string, queryText: string }, revision: string, result: any, explain: any }} DataSnapshot */
+/** @typedef {{ ok: boolean, document?: any, revision?: string, conflict?: boolean, error?: string,
+ * errors?: any[], valid?: boolean, total?: number, code?: string, result?: any, explain?: any, model?: any }} EditorReceipt */
+/** Data document publication and execution use the same queued actions as the UI. */
+import { semanticKey } from '@jarenjs/core/object';
+import { applyJSONPatch } from '@jarenjs/json/patch';
+import { validateFile } from '../validate.js';
+
+/** @param {{ getApp: () => any, runtime: any, operators?: { toOptions: () => any } }} env */
+export function createDataController(env) {
+  let disposed = false, detach = null, sequence = 0;
+  const pending = new Map(), listeners = new Set();
+  const parse = text => { try { return JSON.parse(text); } catch { return null; } };
+  /** @returns {DataSnapshot} */
+  function read() {
+    const data = env.getApp().getState().data;
+    const buffers = { modelText: data.modelText, queryText: data.queryText };
+    return { document: { model: parse(data.modelText), query: parse(data.queryText) }, buffers,
+      revision: semanticKey(buffers), result: structuredClone(data.results), explain: structuredClone(data.explain) };
+  }
+  /** @param {{ model: any, query: any }} candidate */
+  function validate(candidate) {
+    try {
+      if (candidate === null || typeof candidate !== 'object' || !Object.hasOwn(candidate, 'model') || !Object.hasOwn(candidate, 'query'))
+        throw new TypeError('A Data document contains model and query members.');
+      const errors = ['model', 'query'].flatMap(kind => validateFile({ kind, text: JSON.stringify(candidate[kind]) }, { operators: env.operators })
+        .errors.map(error => ({ ...error, member: kind })));
+      return { valid: errors.length === 0, total: errors.length, errors };
+    }
+    catch (error) { return { valid: false, total: 1, errors: [{ code: error.code ?? null, message: error.message }] }; }
+  }
+  function settle(id, outcome) { const resolve = pending.get(id); pending.delete(id); resolve?.({ ...read(), ...outcome }); }
+  /** @param {{ model: any, query: any }} candidate @param {{ expectedRevision?: string }} [options]
+   * @returns {Promise<EditorReceipt>}
+   */
+  function replace(candidate, options = {}) {
+    if (disposed) return Promise.resolve({ ok: false, error: 'The Data editor is disposed.' });
+    const before = read();
+    if (before.revision !== options.expectedRevision) return Promise.resolve({ ok: false, conflict: true, ...before });
+    const checked = validate(candidate);
+    if (!checked.valid) return Promise.resolve({ ok: false, ...checked });
+    return new Promise(resolve => {
+      const id = ++sequence; pending.set(id, resolve);
+      env.getApp().dispatch('data/replace', { requestId: id, expected: before.buffers,
+        modelText: JSON.stringify(candidate.model, null, 2), queryText: JSON.stringify(candidate.query, null, 2) });
+    });
+  }
+  /** @param {Parameters<typeof applyJSONPatch>[1]} patch @param {{ expectedRevision?: string }} [options]
+   * @returns {Promise<EditorReceipt>}
+   */
+  function apply(patch, options) {
+    try { return replace(applyJSONPatch(read().document, patch), options); }
+    catch (error) { return Promise.resolve({ ok: false, error: error.message, code: error.code }); }
+  }
+  /** Query the open store, or explicitly recreate it through the owning host.
+   * @param {{ operation?: 'query'|'open', externals?: Record<string, any> }} [options]
+   * @returns {Promise<EditorReceipt>}
+   */
+  function run(options = {}) {
+    if (disposed) return Promise.resolve({ ok: false, error: 'The Data editor is disposed.' });
+    const operation = options.operation ?? 'query';
+    if (!['query', 'open'].includes(operation)) return Promise.resolve({ ok: false, error: 'The Data operation must be query or open.' });
+    return new Promise(resolve => {
+      const id = ++sequence; pending.set(id, resolve);
+      env.getApp().dispatch('data/execute', { requestId: id, operation, externals: options.externals ?? {} });
+    });
+  }
+  /** @param {(snapshot: DataSnapshot) => void} listener */
+  function subscribe(listener) { if (disposed) return () => {}; listeners.add(listener); return () => listeners.delete(listener); }
+  function attach() {
+    if (disposed || detach) return;
+    let revision = read().revision;
+    detach = env.getApp().subscribe(() => {
+      const value = read();
+      if (revision !== value.revision) { revision = value.revision; for (const listener of listeners) listener(value); }
+    });
+  }
+  function dispose() {
+    if (disposed) return;
+    disposed = true; detach?.(); detach = null; listeners.clear(); env.runtime.dispose();
+    for (const resolve of pending.values()) resolve({ ok: false, error: 'The Data editor is disposed.' });
+    pending.clear();
+  }
+  const effects = {
+    'data-accepted': id => settle(id, { ok: true }),
+    'data-refused': id => settle(id, { ok: false, conflict: true }),
+    'data-editor-run': Object.assign(async (props, dispatch) => {
+      if (disposed) { settle(props.requestId, { ok: false, error: 'The Data editor is disposed.' }); return; }
+      const result = await env.runtime.effects[props.operation === 'open' ? 'data-open' : 'data-run'](props, dispatch);
+      settle(props.requestId, result);
+    }, { dispose }),
+  };
+  return { read, validate, replace, apply, run, subscribe, attach, effects, dispose };
+}