@jarenjs/studio 0.83.3 → 0.85.0

package/src/data/transport.js

@@ -0,0 +1,215 @@
+//@ts-check
+import { openPortClient } from '@jarenjs/contract/port';
+import { dataContract } from './contract.js';
+import { createStageRunner, bootFailure, BOOT_STAGES } from './boot-stages.js';
+
+/**
+ * The browser-shaped dependencies of a transport: how a worker is
+ * spawned, how a port client is opened over a channel, how the shared
+ * channel is opened, and the stage budgets. The page supplies the
+ * platform's; a Node test supplies fakes and millisecond budgets.
+ * @typedef {Object} TransportDeps
+ * @property {() => any} spawnWorker - a fresh owner worker
+ * @property {(channel: any) => any} [openClient] - a port client over a channel
+ * @property {() => any} openChannel - the shared tab channel
+ * @property {Readonly<Record<string, number>>} [budgets] - per-stage budgets
+ * @property {(fn: () => void, ms: number) => any} [setTimer]
+ * @property {(handle: any) => void} [clearTimer]
+ */
+
+/**
+ * The transport: a contract PORT client over the own worker (owner) or
+ * the shared channel (client). `request` unwraps the binding's D6
+ * outcome into the value-or-throw shape the effects consume — a
+ * declared `db` failure surfaces the store's own code and message from
+ * its details; `subscribe` is the client's stream half, passed through.
+ *
+ * `boot()` is the closed protocol of `lib/boot-stages.js`: the worker
+ * starting (its `ready` frame, or its `error` event), then the worker's
+ * own `data.init` under the three stages it announces as it passes them
+ * (`sqlite-init`, `vfs-acquire`, `topology`) — each bounded from here,
+ * so a stage the worker never finishes fails under its own name and
+ * never masquerades as an OPFS absence. `bounded('store-open', …)` is
+ * the fifth stage, run by the boot effect around the first open.
+ * `close()` releases everything this transport created — the client,
+ * the worker, the shared channel, the listeners — exactly once, so a
+ * failed boot leaves nothing behind and a retry starts clean.
+ * @param {TransportDeps} [deps]
+ */
+export function createTransport(deps) {
+  const openClient = deps.openClient ?? (channel => openPortClient(dataContract, { channel, timeoutMs: 30_000 }));
+  const runner = createStageRunner({ budgets: deps.budgets, setTimer: deps.setTimer, clearTimer: deps.clearTimer });
+  /** @type {any} */
+  let client = null;
+  /** @type {any} */
+  let worker = null;
+  /** @type {any} */
+  let shared = null;
+  /** @type {{ target: any, type: string, fn: any }[]} */
+  const listeners = [];
+  let closed = false;
+  /** The stage a boot is in, for a failure that arrives outside a run. */
+  let stage = BOOT_STAGES[0];
+
+  /** @param {any} outcome */
+  const unwrap = (outcome) => {
+    if (outcome.ok) return outcome.value;
+    const details = outcome.error.details;
+    const dbError = details !== null && typeof details === 'object' && typeof details.message === 'string';
+    const error = new Error(dbError ? details.message : outcome.error.message);
+    /** @type {any} */ (error).code = dbError ? details.code : outcome.error.code;
+    throw error;
+  };
+
+  const request = async (op, args) => {
+    if (client === null) throw new Error('the data transport is closed');
+    return unwrap(await client.invoke(op, args));
+  };
+
+  /** @param {any} input @param {any} callbacks */
+  const subscribe = (input, callbacks) => client.subscribe('data.live', input, callbacks);
+
+  /** @type {((notice: any) => void) | null} */
+  let onNotice = null;
+  /** @type {((stage: string) => void) | null} */
+  let onStage = null;
+  /** @type {((fault: { message: string }) => void) | null} */
+  let onFault = null;
+  /** Whether the boot has settled: a worker `error` after that is a fault
+   * of a running store, not of a boot stage, and is reported as one. */
+  let booted = false;
+  /** Attach a listener this transport will detach on close. */
+  const on = (/** @type {any} */ target, /** @type {string} */ type, /** @type {any} */ fn) => {
+    target.addEventListener(type, fn);
+    listeners.push({ target, type, fn });
+  };
+  /** The owner's store-changed notices and the worker's boot-stage
+   * announcements travel beside the contract frames on whichever
+   * transport this tab ended up on, and are told apart by shape — the
+   * same arrangement the owner-discovery frames use. */
+  const listen = (/** @type {any} */ target) => {
+    on(target, 'message', (/** @type {any} */ event) => {
+      const message = event.data;
+      if (message === null || typeof message !== 'object') return;
+      if (typeof message.boot === 'string') {
+        // only the five stages are stages: a foreign frame on the shared
+        // channel cannot rename the failure this tab reports
+        if (BOOT_STAGES.includes(message.boot)) {
+          stage = message.boot;
+          onStage?.(message.boot);
+        }
+        return;
+      }
+      if (message.store !== undefined) onNotice?.(message);
+    });
+  };
+
+  /** Release everything created here, once; a second close is a no-op. */
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    runner.dispose();
+    for (const { target, type, fn } of listeners) {
+      try {
+        target.removeEventListener(type, fn);
+      }
+      catch { /* a terminated worker may refuse; nothing to release then */ }
+    }
+    listeners.length = 0;
+    try {
+      client?.close();
+    }
+    catch { /* already closed */ }
+    client = null;
+    try {
+      worker?.terminate();
+    }
+    catch { /* already gone */ }
+    worker = null;
+    try {
+      shared?.close();
+    }
+    catch { /* already closed */ }
+    shared = null;
+    onNotice = null;
+    onStage = null;
+    onFault = null;
+  };
+
+  /**
+   * One bounded stage. A failure inside it — the work's, or its budget
+   * running out — is the named boot failure, and never something else.
+   * @param {string} name @param {(advance: (next: string) => void) => any} work
+   */
+  const bounded = (name, work) => {
+    stage = name;
+    return runner.run(name, work);
+  };
+
+  /** The worker has started when its module posts `{ ready: true }`; a
+   * module that fails to load fires `error` instead. */
+  const workerStart = () => new Promise((resolve, reject) => {
+    on(worker, 'message', (/** @type {any} */ event) => {
+      if (event.data !== null && typeof event.data === 'object' && event.data.ready === true) resolve(true);
+    });
+    on(worker, 'error', (/** @type {any} */ event) => {
+      const message = typeof event?.message === 'string' && event.message.length > 0
+        ? event.message : 'the data worker failed';
+      if (booted) {
+        // the store was up: the page must not go on reading `ready`
+        onFault?.({ message: `the data worker stopped: ${message}` });
+        return;
+      }
+      reject(bootFailure('worker-start', new Error(message)));
+    });
+  });
+
+  const boot = async () => {
+    if (closed) throw bootFailure('worker-start', new Error('the data transport is closed'));
+    worker = deps.spawnWorker();
+    client = openClient(worker);
+    listen(worker);
+    await bounded('worker-start', () => workerStart());
+    // the worker's init announces its own stages as it passes them; each
+    // announcement moves the budget to the next stage
+    const status = await bounded('sqlite-init', (advance) => {
+      onStage = advance;
+      return request('data.init', null);
+    });
+    onStage = null;
+    if (status.topology !== 'client') {
+      // 'owner' (holds the OPFS pool) or 'memory' (OPFS absent — a
+      // standalone in-memory store): either way this worker IS the
+      // connection; an owner also serves the channel for client tabs.
+      return status;
+    }
+    // another context owns the pool: downgrade to a CLIENT over the
+    // channel; this direct worker has nothing to hold, so it dies.
+    client.close();
+    worker.terminate();
+    client = null;
+    worker = null;
+    shared = deps.openChannel();
+    listen(shared);
+    client = openClient(shared);
+    return status;
+  };
+  /** The boot settled: later worker faults are the running store's. */
+  const settled = () => { booted = true; };
+
+  return {
+    boot,
+    bounded,
+    request,
+    subscribe,
+    close,
+    /** The stage the last boot reached (for a failure outside a run). */
+    stage: () => stage,
+    /** @param {(notice: any) => void} cb */
+    notices: (cb) => { onNotice = cb; },
+    /** @param {(fault: { message: string }) => void} cb - a worker that
+     * fails after the boot settled */
+    faults: (cb) => { onFault = cb; },
+    settled,
+  };
+}

package/src/flow-document.js

@@ -0,0 +1,24 @@
+//@ts-check
+/** Validation shared by text commits and revision-checked publication. */
+import { validateFile } from './validate.js';
+import { JarenValidator } from '@jarenjs/validate';
+import { jsonFormats } from '@jarenjs/formats';
+import { OUR_SCHEMA_OPTIONS } from './component/shared/schema-options.js';
+import dagSchema from '@jarenjs/flow/schemas/jaren-dag.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' };
+export const validateDagDoc = new JarenValidator(OUR_SCHEMA_OPTIONS)
+  .addFormats(jsonFormats)
+  .addSchema(querySchema)
+  .addSchema(jsltSchema)
+  .compile(dagSchema);
+
+
+/** @param {'fsm'|'dag'} kind @param {any} document */
+export function validateFlowDocument(kind, document) {
+  try {
+    if (kind !== 'fsm' && kind !== 'dag') throw new TypeError('The Flow kind must be fsm or dag.');
+    return validateFile({ kind, text: JSON.stringify(document) });
+  }
+  catch (error) { return { valid: false, errors: [{ code: error.code ?? 'JF0001', message: error.message, docPath: error.docPath ?? '' }] }; }
+}

package/src/flow-editor.js

@@ -0,0 +1,98 @@
+//@ts-check
+/** @typedef {{ kind: 'fsm'|'dag'|null, document: any, revision: string, result: any }} FlowSnapshot */
+/** @typedef {{ ok: boolean, document?: any, revision?: string, conflict?: boolean, error?: string,
+ * errors?: any[], valid?: boolean, total?: number, code?: string, output?: any, started?: boolean }} EditorReceipt */
+/** Revision-checked Flow publication over the editor's own queued actions. */
+import { semanticKey } from '@jarenjs/core/object';
+import { applyJSONPatch } from '@jarenjs/json/patch';
+import { validateFlowDocument } from './flow-document.js';
+
+/** @param {{ kind?: 'fsm'|'dag'|null, document?: any, input?: any }} [options] */
+export function createFlowState(options = {}) {
+  return {
+    kind: options.kind ?? null, doc: options.document == null ? null : structuredClone(options.document),
+    selection: null, connect: null, tab: 'diagram', parseError: null, history: { past: [], future: [] },
+    run: null, runContext: structuredClone(options.input ?? null),
+    dagInput: options.input === undefined ? '' : JSON.stringify(options.input), revision: 0, mobilePane: 'diagram',
+  };
+}
+
+/** @param {{ getApp: () => any, runtime: any }} env */
+export function createFlowController(env) {
+  let stopped = false, detach = null, sequence = 0;
+  const requests = new Map(), listeners = new Set();
+  const copy = value => structuredClone(value);
+  /** @returns {FlowSnapshot} */
+  function read() {
+    const { kind, doc, run } = env.getApp().getState().flow;
+    return { kind, document: copy(doc), revision: semanticKey({ kind, doc }), result: copy(run) };
+  }
+  /** @param {any} candidate @param {'fsm'|'dag'} [kind] */
+  function validate(candidate, kind = env.getApp().getState().flow.kind) { return validateFlowDocument(kind, candidate); }
+  function settle(id, result) { const resolve = requests.get(id); requests.delete(id); resolve?.({ ...read(), ...result }); }
+  /** @param {any} candidate @param {{ expectedRevision?: string, kind?: 'fsm'|'dag' }} [options]
+   * @returns {Promise<EditorReceipt>}
+   */
+  function replace(candidate, options = {}) {
+    if (stopped) return Promise.resolve({ ok: false, error: 'The Flow editor is disposed.' });
+    const before = read(), kind = options.kind ?? before.kind;
+    if (before.kind !== null && kind !== before.kind) return Promise.resolve({ ok: false, error: 'A replacement must keep the current Flow kind; open a new document to change it.' });
+    if (options.expectedRevision !== before.revision) return Promise.resolve({ ok: false, conflict: true, ...before });
+    const checked = validate(candidate, kind);
+    if (!checked.valid) return Promise.resolve({ ok: false, ...checked });
+    return new Promise(resolve => {
+      const id = ++sequence; requests.set(id, resolve);
+      env.getApp().dispatch('flow/replace', { requestId: id, expected: { kind: before.kind, doc: before.document }, kind, doc: copy(candidate) });
+    });
+  }
+  /** @param {Parameters<typeof applyJSONPatch>[1]} patch @param {{ expectedRevision?: string, kind?: 'fsm'|'dag' }} [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 }); }
+  }
+  /** Execute with the host's task registry and explicit input; return the settled DAG result or machine start receipt.
+   * @param {{ input?: any, event?: string }} [options]
+   * @returns {Promise<EditorReceipt>}
+   */
+  function run(options = {}) {
+    if (stopped) return Promise.resolve({ ok: false, error: 'The Flow editor is disposed.' });
+    const state = env.getApp().getState().flow;
+    if (state.doc === null) return Promise.resolve({ ok: false, error: 'No Flow document is open.' });
+    return new Promise(resolve => {
+      const id = ++sequence; requests.set(id, resolve);
+      env.getApp().dispatch('flow/execute', { requestId: id, input: options.input ?? state.runContext,
+        inputText: options.input === undefined ? state.dagInput : JSON.stringify(options.input), event: options.event ?? null });
+    });
+  }
+  /** @param {(snapshot: FlowSnapshot) => void} listener */
+  function subscribe(listener) { if (stopped) return () => {}; listeners.add(listener); return () => listeners.delete(listener); }
+  function attach() {
+    if (stopped || detach) return;
+    let revision = read().revision;
+    detach = env.getApp().subscribe(() => {
+      const current = read();
+      if (current.revision !== revision) { revision = current.revision; for (const listener of listeners) listener(current); }
+    });
+  }
+  function dispose() {
+    if (stopped) return;
+    stopped = true; detach?.(); detach = null; listeners.clear(); env.runtime.dispose();
+    for (const resolve of requests.values()) resolve({ ok: false, error: 'The Flow editor is disposed.' });
+    requests.clear();
+  }
+  const effects = {
+    'flow-accepted': id => { env.runtime.effects['flow-dag-abort'](); settle(id, { ok: true }); },
+    'flow-refused': id => settle(id, { ok: false, conflict: true }),
+    'flow-editor-run': Object.assign(async (props, dispatch) => {
+      if (stopped) { settle(props.requestId, { ok: false, error: 'The Flow editor is disposed.' }); return; }
+      if (props.kind === 'fsm') {
+        dispatch(props.event === null ? 'flow/run' : 'flow/send', props.event);
+        settle(props.requestId, { ok: true, started: props.event === null });
+      }
+      else settle(props.requestId, await env.runtime.effects['flow-dag-run'](props, dispatch));
+    }, { dispose }),
+  };
+  return { read, validate, replace, apply, run, subscribe, attach, effects, dispose };
+}

package/styles/data.css

@@ -0,0 +1,53 @@
+@import './editor.css';
+/* Complete Data editor layout and responsive panes, scoped to each mount. */
+
+:where(.jaren-data-editor) .data-panebar { display: none; }
+@media (max-width: 1024px) {
+  :where(.jaren-data-editor) .data-grid { padding-bottom: var(--kb-inset, 0px); }
+}
+@media (max-width: 1024px) {
+  :where(.jaren-data-editor) .data-panebar { display: flex; }
+}
+@media (max-width: 1024px) {
+  :where(.jaren-data-editor) .data-panebar .seg-btn { flex: 1; }
+}
+@media (max-width: 1024px) {
+  :where(.jaren-data-editor) .data-panebar,
+:where(.jaren-data-editor) .data-grid > .card { grid-column: 1 / -1; }
+}
+@media (max-width: 1024px) {
+
+  :where(.jaren-data-editor) .data-grid[data-pane='store'] .data-query,
+:where(.jaren-data-editor) .data-grid[data-pane='store'] .data-live,
+:where(.jaren-data-editor) .data-grid[data-pane='store'] .data-trip,
+:where(.jaren-data-editor) .data-grid[data-pane='query'] .data-status,
+:where(.jaren-data-editor) .data-grid[data-pane='query'] .data-live,
+:where(.jaren-data-editor) .data-grid[data-pane='query'] .data-trip,
+:where(.jaren-data-editor) .data-grid[data-pane='live']  .data-status,
+:where(.jaren-data-editor) .data-grid[data-pane='live']  .data-query,
+:where(.jaren-data-editor) .data-grid[data-pane='live']  .data-trip,
+:where(.jaren-data-editor) .data-grid[data-pane='trip']  .data-status,
+:where(.jaren-data-editor) .data-grid[data-pane='trip']  .data-query,
+:where(.jaren-data-editor) .data-grid[data-pane='trip']  .data-live { display: none; }
+}
+@media (max-width: 1024px) {
+  :where(.jaren-data-editor) .data-grid .btn,
+:where(.jaren-data-editor) .data-grid .seg-btn { min-height: 44px; }
+}
+:where(.jaren-data-editor) .data-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(22rem, 1fr));
+  gap: var(--space-4, 1rem);
+  align-items: start;
+}
+:where(.jaren-data-editor) .data-rows { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: var(--space-2, 0.5rem); }
+:where(.jaren-data-editor) .data-row {
+  display: flex; align-items: center; gap: var(--space-2, 0.5rem);
+  border: 1px solid var(--border, hsl(220 14% 88%)); border-radius: var(--radius-sm, 8px);
+  background: var(--bg, hsl(0 0% 100%)); padding: var(--space-1, 0.25rem) var(--space-2, 0.5rem);
+}
+:where(.jaren-data-editor) .data-row code { flex: 1; min-width: 0; overflow-x: auto; white-space: nowrap; font-size: 0.8rem; }
+:where(.jaren-data-editor) .data-row-delete { flex: none; color: var(--muted, hsl(220 12% 45%)); }
+:where(.jaren-data-editor) .data-row-delete:hover { color: var(--fail, hsl(0 68% 46%)); border-color: var(--fail, hsl(0 68% 46%)); }
+:where(.jaren-data-editor) .data-trip-map { margin-block: var(--space-3, 0.75rem); padding: 0; border: 0; background: transparent; }
+:where(.jaren-data-editor) .data-trip-narrative { word-break: break-word; }

package/styles/editor.css

@@ -0,0 +1,150 @@
+/* Shared editor primitives inherit host design tokens, with usable standalone defaults. */
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) { min-width: 0; color: var(--fg, hsl(224 20% 14%)); font-family: var(--font, 'Inter', ui-sans-serif, system-ui, sans-serif); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio), :where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) * { box-sizing: border-box; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) button, :where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) input, :where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) textarea, :where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) select { font: inherit; }
+
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .editor { font-family: var(--mono, 'JetBrains Mono', ui-monospace, 'Cascadia Code', monospace); font-size: 0.86em; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .muted { color: var(--muted, hsl(220 12% 45%)); font-size: 0.85rem; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .card p,
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .doc-p,
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) td,
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) th { overflow-wrap: anywhere; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .btn {
+  display: inline-block; border: 1px solid var(--border, hsl(220 14% 88%)); border-radius: var(--radius-sm, 8px);
+  padding: var(--space-2, 0.5rem) var(--space-4, 1rem); color: var(--fg, hsl(224 20% 14%)); font-size: 0.92rem;
+  background: var(--surface, hsl(220 20% 98%)); cursor: pointer;
+}
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .btn:hover { text-decoration: none; border-color: var(--accent, hsl(221 83% 53%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .btn.primary { background: var(--accent, hsl(221 83% 53%)); border-color: var(--accent, hsl(221 83% 53%)); color: var(--accent-fg, hsl(0 0% 100%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .btn.primary:hover { background: var(--accent-hover, hsl(221 83% 47%)); border-color: var(--accent-hover, hsl(221 83% 47%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) :where(.seg) { display: flex; flex-wrap: wrap; gap: var(--space-1, 0.25rem); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .seg-btn {
+  border: 1px solid var(--border, hsl(220 14% 88%)); background: transparent; color: var(--muted, hsl(220 12% 45%));
+  padding: var(--space-1, 0.25rem) var(--space-3, 0.75rem); border-radius: var(--radius-sm, 8px); font-size: 0.8rem;
+  cursor: pointer;
+}
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .seg-btn.active { background: var(--accent-soft, hsl(214 95% 93%)); color: var(--accent, hsl(221 83% 53%)); border-color: var(--accent, hsl(221 83% 53%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .card {
+  background: var(--surface, hsl(220 20% 98%)); border: 1px solid var(--border, hsl(220 14% 88%));
+  border-radius: var(--radius, 10px); padding: var(--space-4, 1rem) var(--space-5, 1.25rem);
+}
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .card-head {
+  display: flex; align-items: center; justify-content: space-between; gap: var(--space-4, 1rem);
+  flex-wrap: wrap; margin-bottom: var(--space-3, 0.75rem);
+}
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .card-head h3 { margin: 0; min-width: 0; flex: 1 1 auto; overflow-wrap: anywhere; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .card-head > :last-child { margin-left: auto; }
+
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .callout {
+  background: var(--surface, hsl(220 20% 98%)); border: 1px solid var(--border, hsl(220 14% 88%));
+  border-left: 4px solid var(--accent, hsl(221 83% 53%)); border-radius: var(--radius, 10px);
+  padding: var(--space-4, 1rem) var(--space-5, 1.25rem); margin: var(--space-4, 1rem) 0;
+}
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .callout.accent { background: var(--accent-soft, hsl(214 95% 93%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .callout.wide { max-width: 60rem; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .cards {
+  display: grid; grid-template-columns: repeat(auto-fit, minmax(13rem, 1fr));
+  gap: var(--space-4, 1rem); margin: var(--space-4, 1rem) 0;
+}
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .stat-card {
+  background: var(--surface, hsl(220 20% 98%)); border: 1px solid var(--border, hsl(220 14% 88%));
+  border-radius: var(--radius, 10px); padding: var(--space-4, 1rem) var(--space-5, 1.25rem);
+}
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .stat-title { margin: 0; font-size: 0.78rem; text-transform: uppercase; letter-spacing: 0.05em; color: var(--muted, hsl(220 12% 45%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .stat-value { margin: 0.2rem 0 0; font-weight: 700; font-size: 1.05rem; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .stat-note { margin: 0.1rem 0 0; font-size: 0.8rem; color: var(--muted, hsl(220 12% 45%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .table-scroll { overflow-x: auto; min-width: 0; border: 1px solid var(--border, hsl(220 14% 88%)); border-radius: var(--radius, 10px); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) table { width: 100%; border-collapse: collapse; font-size: 0.88rem; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .table-scroll th,
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .table-scroll td {
+  overflow-wrap: normal;
+  word-break: normal;
+}
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) th,
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) td { text-align: left; padding: var(--space-2, 0.5rem) var(--space-4, 1rem); border-bottom: 1px solid var(--border, hsl(220 14% 88%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) th { background: var(--surface, hsl(220 20% 98%)); font-size: 0.78rem; text-transform: uppercase; letter-spacing: 0.04em; color: var(--muted, hsl(220 12% 45%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) tbody tr:last-child td { border-bottom: none; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) tr.strong td { font-weight: 700; color: var(--accent, hsl(221 83% 53%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .table-note { color: var(--muted, hsl(220 12% 45%)); font-size: 0.82rem; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .editor {
+  width: 100%; resize: vertical; border: 1px solid var(--border, hsl(220 14% 88%)); border-radius: var(--radius-sm, 8px);
+  background: var(--code-bg, hsl(224 25% 12%)); color: var(--code-fg, hsl(210 30% 90%)); padding: var(--space-3, 0.75rem); line-height: 1.5;
+}
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .badge {
+  display: inline-block; border-radius: 999px; padding: var(--space-1, 0.25rem) var(--space-3, 0.75rem);
+  font-size: 0.82rem; font-weight: 600;
+}
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .badge.ok { background: var(--ok-soft, hsl(150 60% 94%)); color: var(--ok, hsl(150 65% 34%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .badge.fail { background: var(--fail-soft, hsl(0 80% 96%)); color: var(--fail, hsl(0 68% 46%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .error-line { color: var(--fail, hsl(0 68% 46%)); font-size: 0.85rem; font-family: var(--mono, 'JetBrains Mono', ui-monospace, 'Cascadia Code', monospace); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .code-block {
+  background: var(--code-bg, hsl(224 25% 12%)); color: var(--code-fg, hsl(210 30% 90%)); border-radius: var(--radius-sm, 8px);
+  padding: var(--space-3, 0.75rem) var(--space-4, 1rem); overflow-x: auto; margin: 0;
+  line-height: 1.5; white-space: pre-wrap; word-break: break-word;
+}
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .code-block.clamp { max-height: 14rem; overflow-y: auto; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .details-card {
+  border: 1px solid var(--border, hsl(220 14% 88%)); border-radius: var(--radius, 10px);
+  padding: var(--space-2, 0.5rem) var(--space-4, 1rem); margin: var(--space-3, 0.75rem) 0; background: var(--surface, hsl(220 20% 98%));
+}
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .details-card summary { cursor: pointer; font-weight: 600; font-size: 0.9rem; color: var(--muted, hsl(220 12% 45%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .details-card[open] summary { margin-bottom: 0.4rem; color: var(--fg, hsl(224 20% 14%)); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .btn.small { padding: var(--space-1, 0.25rem) var(--space-3, 0.75rem); font-size: 0.82rem; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .field { display: block; margin-bottom: var(--space-3, 0.75rem); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .field-title { display: block; font-size: 0.8rem; font-weight: 700; color: var(--muted, hsl(220 12% 45%)); text-transform: uppercase; letter-spacing: 0.04em; margin-bottom: var(--space-1, 0.25rem); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .editor.line { min-height: auto; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .doc-p { color: var(--fg, hsl(224 20% 14%)); max-width: 44rem; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .example-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(20rem, 1fr)); gap: var(--space-4, 1rem); }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .example-card { display: flex; flex-direction: column; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) .example-card .code-block { flex: 1; font-size: 0.75rem; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) :focus-visible { outline: 2px solid var(--accent, hsl(221 83% 53%)); outline-offset: 2px; }
+:where(.jaren-flow-editor, .jaren-data-editor, .project-data, .studio-root, .jstudio) button:disabled { cursor: default; opacity: 0.6; }
+
+/* Standard generated forms and document-result chrome. */
+
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form { border: none; padding: 0; margin: 0; }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-title { display: none; }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-field { margin-bottom: var(--space-3, 0.75rem); }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-field label { display: block; font-size: 0.85rem; font-weight: 600; }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-field input[type="text"],
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-field input[type="email"],
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-field input[type="url"],
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-field input[type="password"],
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-field input[type="number"],
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-field input[type="date"],
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-field select,
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-field textarea {
+  display: block; width: 100%; margin-top: var(--space-1, 0.25rem);
+  border: 1px solid var(--border, hsl(220 14% 88%)); border-radius: var(--radius-sm, 8px); background: var(--bg, hsl(0 0% 100%)); color: var(--fg, hsl(224 20% 14%));
+  padding: var(--space-2, 0.5rem) var(--space-3, 0.75rem); font-size: 0.9rem; font-family: var(--font, 'Inter', ui-sans-serif, system-ui, sans-serif);
+}
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-field input[type="checkbox"] { margin-left: var(--space-2, 0.5rem); }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-required { color: var(--fail, hsl(0 68% 46%)); }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-description { color: var(--muted, hsl(220 12% 45%)); font-size: 0.78rem; margin: 0.15rem 0 0; }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-error { color: var(--fail, hsl(0 68% 46%)); font-size: 0.78rem; margin: 0.2rem 0 0; }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-group,
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-array {
+  border: 1px solid var(--border, hsl(220 14% 88%)); border-radius: var(--radius-sm, 8px);
+  padding: var(--space-3, 0.75rem) var(--space-4, 1rem); margin: var(--space-3, 0.75rem) 0;
+}
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-group legend,
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-array legend {
+  font-size: 0.8rem; font-weight: 700; color: var(--muted, hsl(220 12% 45%)); padding: 0 0.3rem;
+}
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-add,
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-remove {
+  border: 1px solid var(--border, hsl(220 14% 88%)); background: var(--surface, hsl(220 20% 98%)); color: var(--muted, hsl(220 12% 45%));
+  border-radius: 6px; cursor: pointer; font-size: 0.8rem; padding: 0.1rem 0.55rem;
+  margin-top: 0.3rem;
+}
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-add:hover,
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .jaren-form-remove:hover { color: var(--accent, hsl(221 83% 53%)); border-color: var(--accent, hsl(221 83% 53%)); }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .code-card { margin: var(--space-3, 0.75rem) 0; }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .code-head { display: flex; align-items: center; gap: var(--space-2, 0.5rem); margin-bottom: var(--space-1, 0.25rem); }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .code-title { font-size: 0.8rem; font-weight: 700; color: var(--muted, hsl(220 12% 45%)); text-transform: uppercase; letter-spacing: 0.04em; }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .details-card {
+  border: 1px solid var(--border, hsl(220 14% 88%)); border-radius: var(--radius, 10px);
+  padding: var(--space-2, 0.5rem) var(--space-4, 1rem); margin: var(--space-3, 0.75rem) 0; background: var(--surface, hsl(220 20% 98%));
+}
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .details-card summary { cursor: pointer; font-weight: 600; font-size: 0.9rem; color: var(--muted, hsl(220 12% 45%)); }
+:where(.jstudio, .jaren-flow-editor, .jaren-data-editor) .details-card[open] summary { margin-bottom: 0.4rem; color: var(--fg, hsl(224 20% 14%)); }

package/styles/flow.css

@@ -0,0 +1,99 @@
+@import './editor.css';
+/* Complete Flow editor: scoped layout, interaction and reduced-motion support. */
+
+:where(.jaren-flow-editor) .flow-panebar { display: none; }
+@media (max-width: 1024px) {
+  :where(.jaren-flow-editor) .flow-grid { padding-bottom: var(--kb-inset, 0px); }
+}
+@media (max-width: 1024px) {
+  :where(.jaren-flow-editor) .flow-panebar { display: flex; }
+}
+@media (max-width: 1024px) {
+  :where(.jaren-flow-editor) .flow-panebar .seg-btn { flex: 1; }
+}
+@media (max-width: 1024px) {
+  :where(.jaren-flow-editor) .flow-panebar,
+:where(.jaren-flow-editor) .flow-grid > .card,
+:where(.jaren-flow-editor) .flow-side { grid-column: 1 / -1; }
+}
+@media (max-width: 1024px) {
+
+  :where(.jaren-flow-editor) .flow-grid[data-pane='diagram']   .flow-side,
+:where(.jaren-flow-editor) .flow-grid[data-pane='inspector'] .flow-canvas-card,
+:where(.jaren-flow-editor) .flow-grid[data-pane='inspector'] .flow-run,
+:where(.jaren-flow-editor) .flow-grid[data-pane='run']       .flow-canvas-card,
+:where(.jaren-flow-editor) .flow-grid[data-pane='run']       .flow-inspector { display: none; }
+}
+@media (max-width: 1024px) {
+  :where(.jaren-flow-editor) .flow-grid .btn,
+:where(.jaren-flow-editor) .flow-grid .seg-btn { min-height: 44px; }
+}
+
+:where(.jaren-flow-editor) .flow-grid {
+  display: grid;
+  grid-template-columns: minmax(0, 3fr) minmax(0, 2fr);
+  gap: var(--space-4, 1rem);
+  align-items: start;
+}
+:where(.jaren-flow-editor) .flow-side { display: grid; gap: var(--space-4, 1rem); }
+:where(.jaren-flow-editor) .flow-palette { display: flex; flex-wrap: wrap; gap: var(--space-2, 0.5rem); }
+:where(.jaren-flow-editor) .flow-tabs { display: flex; gap: var(--space-2, 0.5rem); margin-block: var(--space-2, 0.5rem); }
+:where(.jaren-flow-editor) .flow-canvas { overflow: auto; }
+:where(.jaren-flow-editor) .flow-canvas svg { max-width: 100%; height: auto; }
+:where(.jaren-flow-editor) .flow-text { width: 100%; }
+:where(.jaren-flow-editor) .flow-dag-input { width: 100%; }
+:where(.jaren-flow-editor) .flow-log {
+  list-style: none;
+  margin: var(--space-2, 0.5rem) 0 0;
+  padding: 0;
+  max-height: 12rem;
+  overflow: auto;
+}
+:where(.jaren-flow-editor) .flow-log-line {
+  font-family: var(--font-mono, 'JetBrains Mono', ui-monospace, 'Cascadia Code', monospace);
+  font-size: 0.78rem;
+  padding-block: 1px;
+  border-block-end: 1px solid var(--border, hsl(220 14% 88%));
+  overflow-wrap: anywhere;
+}
+:where(.jaren-flow-editor) .flow-run-head { display: flex; flex-wrap: wrap; gap: var(--space-2, 0.5rem); align-items: center; margin-block: var(--space-2, 0.5rem); }
+:where(.jaren-flow-editor) .flow-run-buttons { display: flex; flex-wrap: wrap; gap: var(--space-2, 0.5rem); }
+:where(.jaren-flow-editor) .flow-run-mount { border: 1px dashed var(--border, hsl(220 14% 88%)); border-radius: 8px; padding: var(--space-2, 0.5rem); }
+:where(.jaren-flow-editor) .flow-output { max-height: 12rem; overflow: auto; }
+:where(.jaren-flow-editor) .btn.flow-armed { outline: 2px solid var(--accent, hsl(221 83% 53%)); }
+:where(.jaren-flow-editor) .mm-pick { cursor: pointer; }
+:where(.jaren-flow-editor) .mm-selected .mm-node-shape,
+:where(.jaren-flow-editor) .mm-selected .mm-edge-line { stroke-width: 2.5; }
+:where(.jaren-flow-editor) .mm-armed .mm-node-shape { stroke-dasharray: 4 3; stroke-width: 2.5; }
+:where(.jaren-flow-editor) .mm-active .mm-node-shape {
+  stroke: var(--accent, hsl(221 83% 53%));
+  stroke-width: 2.5;
+  transform-box: fill-box;
+  transform-origin: center;
+  filter: drop-shadow(0 0 6px var(--accent, hsl(221 83% 53%)));
+}
+:where(.jaren-flow-editor) .mm-fired .mm-edge-line {
+  stroke: var(--accent, hsl(221 83% 53%));
+  stroke-width: 2.5;
+  stroke-dasharray: 6 4;
+}
+:where(.jaren-flow-editor) .mm-fired .mm-edge-label { fill: var(--accent, hsl(221 83% 53%)); font-weight: 600; }
+:where(.jaren-flow-editor) .mm-run-ok .mm-node-shape { stroke: var(--ok, #16a34a); stroke-width: 2.5; }
+:where(.jaren-flow-editor) .mm-run-error .mm-node-shape { stroke: var(--danger, #dc2626); stroke-width: 2.5; }
+:where(.jaren-flow-editor) .mm-run-aborted .mm-node-shape { opacity: 0.5; }
+@media (prefers-reduced-motion: no-preference) {
+  :where(.jaren-flow-editor) .mm-active .mm-node-shape { animation: mm-pulse 1.5s var(--motion-ease-loop, ease-in-out) infinite; }
+}
+@media (prefers-reduced-motion: no-preference) {
+  :where(.jaren-flow-editor) .mm-fired .mm-edge-line { animation: mm-flow 0.7s linear infinite; }
+}
+@media (prefers-reduced-motion: no-preference) {
+  :where(.jaren-flow-editor) .mm-run-error .mm-node-shape { animation: mm-pulse 1s var(--motion-ease-loop, ease-in-out) infinite; }
+}
+@keyframes mm-pulse {
+  0%, 100% { filter: drop-shadow(0 0 2px var(--accent, hsl(221 83% 53%))); }
+  50%      { filter: drop-shadow(0 0 9px var(--accent, hsl(221 83% 53%))); }
+}
+@keyframes mm-flow {
+  to { stroke-dashoffset: -20; }
+}

package/styles/studio.css

@@ -1,3 +1,4 @@
+@import './flow.css';
 /* @jarenjs/studio — the IDE shell stylesheet.
  *
  * DESIGN.md-conformant: minmax(0,1fr) tracks with min-width:0 on every