@jarenjs/studio 0.83.3 → 0.85.0

package/src/component/project.js

@@ -0,0 +1,308 @@
+//@ts-check
+/** Complete project-stage behavior over injected execution and preview services. */
+import { resolveProjectFile, projectFileContext } from '../index.js';
+import { contentKey, semanticKey } from '@jarenjs/core/object';
+import { createSplitterWidget } from '@jarenjs/app';
+import { createStudioComponent } from './index.js';
+
+import { compileFsm, compileDag } from '@jarenjs/flow';
+import { compileContract } from '@jarenjs/contract';
+import { toOpenApi } from '@jarenjs/contract/project';
+
+import { errorMessage, cards, error, code } from './shared/nodes.js';
+import { Float64 } from '@jarenjs/core/math';
+const formatMsUnscaled = value => `${Float64.roundToPrecision(value, 3)} ms`;
+
+
+/** @param {{ operators?: any, loadDocument: Function, runQuery: Function, runJslt: Function, runValidation: Function }} options */
+export function createProjectHost(options) {
+const { operators: operatorRegistry, loadDocument: loadStudioDocument, runQuery, runJslt, runValidation } = options;
+/** The component, with the site's math/finance/stats packs mounted. */
+const projectComponent = createStudioComponent({ operators: operatorRegistry });
+
+/** A normalized project view of the live slice (for the engine calls). */
+function projectOf(slice) {
+  return {
+    project: slice.project ?? '0.1',
+    files: slice.files ?? [],
+    active: slice.active ?? (slice.files?.[0]?.name ?? null),
+    layout: slice.layout,
+  };
+}
+
+/**
+ * The live slice as a persistable `jaren-project` document — what a save
+ * or a share token carries (the IDE-only fields — mount, results, dirty —
+ * stay behind).
+ * @param {any} slice - the `state.project` slice
+ */
+function projectSnapshot(slice) {
+  return { ...projectOf(slice), name: slice.name ?? 'Untitled project' };
+}
+
+/**
+ * The project's designated `app` file — the one the Studio contracts
+ * (external document operations, the app download) operate on: the
+ * active file when it is an app, else the first app file, else null.
+ * @param {any} slice - the `state.project` slice
+ * @returns {{ name: string, kind: string, text: string } | null}
+ */
+function projectAppFile(slice) {
+  const files = slice.files ?? [];
+  const active = files.find((f) => f.name === slice.active);
+  if (active !== undefined && active.kind === 'app') return active;
+  return files.find((f) => f.kind === 'app') ?? null;
+}
+
+/**
+ * The edit loop's pure step: fold the live slice into the last-good
+ * `{ mount, revision }` for the active `app` file. A valid structural
+ * change bumps the revision (the widget reboots); a valid state-only
+ * change keeps the revision but swaps the document (the widget
+ * hot-updates); an invalid edit — or a non-app active file — keeps the
+ * previous mount untouched (the last good frame stays on the stage).
+ * @param {any} slice - the `state.project` slice
+ * @returns {{ mount: any, revision: number }}
+ */
+function commitProject(slice) {
+  const mount = slice.mount ?? null;
+  const revision = slice.revision ?? 0;
+  const project = projectOf(slice);
+  let active = project.active;
+  let activeFile = project.files.find((f) => f.name === active);
+  if (!activeFile) return { mount, revision };
+  // Editing an imported fragment keeps its owning app visible and live.
+  if (!['app', 'fsm', 'dag', 'model'].includes(activeFile.kind) && !activeFile.model) {
+    const owners = project.files.filter((f) => f.kind === 'app' && f.imports
+      && Object.values(f.imports).includes(active));
+    if (owners.length !== 1) return { mount, revision };
+    activeFile = owners[0]; active = activeFile.name;
+  }
+  let resolved;
+  try { resolved = resolveProjectFile(project, active); }
+  catch { return { mount, revision }; }
+  const assembledFile = { ...activeFile, text: JSON.stringify(resolved.doc) };
+  const verdicts = projectComponent.describe(project).files;
+  if (!verdicts.find((f) => f.name === active)?.valid) return { mount, revision };
+  let input = null;
+  let context;
+  try {
+    context = projectFileContext(project, activeFile);
+    if (context.model && !verdicts.find((f) => f.name === context.model.name)?.valid) return { mount, revision };
+    const usesInput = ['fsm', 'dag'].includes(activeFile.kind)
+      || (activeFile.kind === 'model' && activeFile.input !== undefined);
+    if (context.input && usesInput)
+      input = JSON.parse(context.input.text);
+  }
+  catch { return { mount, revision }; }
+  const isStore = activeFile.kind === 'model' || activeFile.model !== undefined;
+  const doc = resolved.doc;
+  const prevProject = mount && mount.name === active
+    ? { files: [{ name: mount.name, kind: mount.kind ?? 'app', text: JSON.stringify(mount.doc) }] }
+    : { files: [] };
+  const nextProject = { files: [{ name: active, kind: activeFile.kind, text: assembledFile.text }] };
+  const policy = projectComponent.hostPolicy(prevProject, nextProject)[active] ?? 'reboot';
+  if (policy === 'skip' && mount && mount.name === active
+    && (!isStore || mount.files === project.files) && semanticKey(mount.input ?? null) === semanticKey(input))
+    return { mount, revision };
+  const nextRevision = policy === 'reboot' ? revision + 1 : revision;
+  return { mount: { name: active, kind: activeFile.kind, doc, input,
+    sourceFiles: resolved.sourceFiles, ...(isStore ? { files: project.files, store: true } : {}),
+    revision: nextRevision }, revision: nextRevision };
+}
+
+/**
+ * Run a transform file (`jslt` / `query`): pair it with the project's
+ * input (the first `data` file, else a `state` file) and hand it to the
+ * shared transform runners — so registered operators ($npv, $sqrt, …)
+ * work here exactly as in play. Returns `{ nodes }` (render nodes for
+ * the `ui` mode), or null for a kind that is not a runnable transform.
+ * The runners catch their own errors into error nodes, so this never
+ * throws.
+ * @param {any} slice - the `state.project` slice
+ * @param {string} name - the file to run
+ * @param {{ model?: (project: any, name: string) => Promise<any> }} [options]
+ * @returns {{ nodes: any[] } | Promise<{ nodes: any[] }> | null}
+ */
+function runProjectFile(slice, name, options = {}) {
+  const project = projectOf(slice);
+  const file = project.files.find((f) => f.name === name);
+  if (file === undefined) return null;
+  if (file.kind === 'model' || file.model !== undefined) {
+    if (!options.model) return null;
+    return options.model(project, name).then((result) => ({ nodes: [
+      code('Result', JSON.stringify(result.result, null, 2)), code('Query plan', JSON.stringify(result.plan, null, 2)),
+    ] }), (err) => ({ nodes: [error(err, 'Model run')] }));
+  }
+  let input;
+  try { ({ input } = projectFileContext(project, file)); }
+  catch (err) { return { nodes: [error(err, 'Project reference')] }; }
+  const dataText = input ? input.text : 'null';
+  if (file.kind === 'fsm' || file.kind === 'dag') {
+    try {
+      const doc = resolveProjectFile(project, name).doc;
+      const data = JSON.parse(dataText);
+      if (file.kind === 'dag') return compileDag(doc).run(data).then(
+        (output) => ({ nodes: [code('DAG output', JSON.stringify(output, null, 2) ?? '(empty sequence)')] }),
+        (err) => ({ nodes: [error(err, 'DAG run')] }));
+      const machine = compileFsm(doc);
+      let state = machine.initial;
+      const trace = [];
+      for (const event of data?.events ?? []) {
+        const result = machine.step(state, typeof event === 'string' ? event : event.event,
+          { context: data?.context ?? null, payload: typeof event === 'string' ? null : event.payload });
+        trace.push(result); state = result.state;
+      }
+      return { nodes: [code('Machine run', JSON.stringify({ state, events: state === null ? [] : machine.events(state), trace }, null, 2))] };
+    }
+    catch (err) { return { nodes: [error(err, 'Flow run')] }; }
+  }
+  if (file.kind === 'query') return { nodes: runQuery({ query: file.text, data: dataText, externals: '' }) };
+  if (file.kind === 'jslt') return { nodes: runJslt({ stylesheet: file.text, data: dataText }) };
+  if (file.kind === 'schema') return { nodes: validateNodes(file.text, dataText) };
+  if (file.kind === 'contract') return { nodes: contractNodes(file.text) };
+  return null;
+}
+
+/**
+ * A `contract` file's stage: compile it and show the projections a
+ * consumer reads — `describe()` (resolved bindings + policy) and the
+ * OpenAPI 3.1 document. A compile refusal renders as the coded error
+ * node with its `JC00xx` and docPath (the same diagnosis the file rail
+ * shows), never a throw.
+ * @param {string} text - the contract file's text
+ */
+function contractNodes(text) {
+  let doc;
+  try { doc = JSON.parse(text); }
+  catch (err) { return [error({ message: errorMessage(err) }, 'Invalid JSON')]; }
+  let contract;
+  try { contract = compileContract(doc); }
+  catch (err) { return [error(/** @type {any} */ (err), 'Contract refusal')]; }
+  const description = contract.describe();
+  // lenient: a keyword the OpenAPI dialect cannot carry is dropped and
+  // COUNTED (the card says so) instead of refusing the whole pane — the
+  // strict mode is the CLI's job, the stage's job is to show the file
+  const openapi = toOpenApi(contract, {
+    lenient: true,
+    info: {
+      title: typeof doc.id === 'string' ? doc.id : 'contract',
+      version: typeof doc.version === 'string' ? doc.version : '0',
+    },
+  });
+  return [
+    cards([
+      { title: 'Operations', value: String(description.operations.length) },
+      ...(openapi.dropped.length > 0 ? [{ title: 'OpenAPI dropped', value: String(openapi.dropped.length) }] : []),
+    ]),
+    code('describe()', JSON.stringify(description, null, 2)),
+    code('OpenAPI 3.1', JSON.stringify(openapi.document, null, 2)),
+  ];
+}
+
+/** Validate a data file against a schema file and render the report on
+ * the stage: a valid/invalid summary plus each error as its own coded
+ * node. */
+function validateNodes(schemaText, dataText) {
+  let data;
+  try { data = JSON.parse(dataText); }
+  catch (err) { return [error({ message: `data: ${errorMessage(err)}` }, 'Invalid JSON')]; }
+  const r = runValidation(schemaText, data);
+  if (r.schemaError !== null) return [error({ message: r.schemaError }, 'Schema error')];
+  const nodes = [cards([
+    { title: r.valid ? 'Valid' : 'Invalid', value: r.valid ? '✓' : `${r.errors.length} error${r.errors.length === 1 ? '' : 's'}` },
+    { title: 'Draft', value: r.draft },
+    { title: 'Compile', value: formatMsUnscaled(r.compileMs) },
+    { title: 'Validate', value: formatMsUnscaled(r.validateMs) },
+  ])];
+  for (const e of r.errors) {
+    nodes.push(error({
+      message: e.message,
+      dataPath: e.instancePath === '' ? '(root)' : e.instancePath,
+      code: e.keyword !== '' ? e.keyword : undefined,
+    }, 'Validation error'));
+  }
+  return nodes;
+}
+
+/**
+ * The live stage host widget (`studio-stage`): boot the active app file's
+ * assembled document as an isolated nested app, then apply the
+ * reboot-vs-hot-update policy on every commit.
+ * @param {{ schedule?: (flush: () => void) => void }} [env]
+ */
+function createProjectStageWidget(env = {}) {
+  const stateKeyOf = (doc) => (doc && typeof doc === 'object' ? contentKey(doc.state ?? null) : null);
+  // the document minus its state — the same datum classifyChange keys on.
+  // The widget re-derives it defensively: two commits can race in at the
+  // SAME revision with different documents (a project/open interleaving
+  // with a route-arrival commit), and hot-dispatching one document's
+  // state into another document's running view renders garbage.
+  const shapeKeyOf = (doc) => (doc && typeof doc === 'object' ? contentKey({ ...doc, state: null }) : null);
+
+  const boot = (handle, mount) => {
+    handle.emit({ action: 'project/stage-error', with: null });
+    const result = loadStudioDocument(mount.doc, {
+      node: handle.host,
+      document: handle.host.ownerDocument,
+      schedule: env.schedule,
+      onError: (err) => handle.emit({ action: 'project/stage-error', with: errorMessage(err) }),
+    });
+    handle.app = result.ok ? result.app : null;
+    handle.revision = mount.revision;
+    handle.stateKey = stateKeyOf(mount.doc);
+    handle.shapeKey = shapeKeyOf(mount.doc);
+    if (!result.ok) handle.emit({ action: 'project/stage-error', with: result.message });
+  };
+  const destroy = (handle) => {
+    try { handle.app?.destroy(); }
+    catch (err) { handle.emit({ action: 'project/stage-error', with: errorMessage(err) }); }
+    handle.app = null;
+  };
+
+  return {
+    mount(host, props, emit) {
+      const handle = { host, emit, app: null, revision: null, stateKey: null, shapeKey: null };
+      boot(handle, props);
+      return handle;
+    },
+    update(handle, props, prevProps) {
+      if (props === prevProps) return;
+      // a structural change bumped the revision — or a raced-in commit
+      // swapped the document's shape at the same revision → destroy + reboot
+      if (props.revision !== handle.revision || shapeKeyOf(props.doc) !== handle.shapeKey) {
+        destroy(handle);
+        boot(handle, props);
+        return;
+      }
+      // same revision, same shape, new document → a state-only edit →
+      // hot-dispatch it into the RUNNING app (no reboot: scroll, focus and
+      // uncontrolled inputs survive the diff re-render)
+      const key = stateKeyOf(props.doc);
+      if (handle.app !== null && key !== handle.stateKey) {
+        handle.app.setState(props.doc.state);
+        handle.stateKey = key;
+      }
+    },
+    unmount(handle) {
+      destroy(handle);
+    },
+  };
+}
+
+/**
+ * The Studio's drag splitter (`studio-splitter`): the shared
+ * `createSplitterWidget` bound to the studio grid — a handle over the
+ * editor|stage boundary that drives `--js-ratio` live during a drag and
+ * commits `project/layout-ratio` on pointer-UP (keyboard-resizable as an
+ * ARIA separator). The reusable widget lives in `@jarenjs/app`; play binds
+ * the same factory to its own grid.
+ */
+function createProjectSplitterWidget() {
+  return createSplitterWidget({
+    grid: '.jstudio', rail: '.js-rail', cssVar: '--js-ratio', action: 'project/layout-ratio',
+  });
+}
+
+return { projectComponent, projectSnapshot, projectAppFile, commitProject, runProjectFile, createProjectStageWidget, createProjectSplitterWidget };
+}

package/src/component/shared/host-widget.js

@@ -0,0 +1,35 @@
+//@ts-check
+/**
+ * @file The shared host-widget lifecycle (the third studio forced the
+ * extraction): mount boots a nested app into the host node, update
+ * reboots ONLY when the document or its revision changed, unmount
+ * destroys. The `mount`/`update`/`unmount` trio was byte-identical
+ * between the Studio and Flow boundaries; the `destroy` halves
+ * differed DELIBERATELY (Studio reports teardown failures, Flow
+ * swallows them), so the factory takes both halves as parameters and
+ * reconciles nothing by averaging — one factory, three callers, each
+ * keeping its own policy.
+ */
+
+/**
+ * @param {{ boot: (handle: any, props: any) => void,
+ *   destroy: (handle: any) => void }} lifecycle
+ * @returns {{ mount: Function, update: Function, unmount: Function }}
+ */
+export function createHostWidget({ boot, destroy }) {
+  return {
+    mount(host, props, emit) {
+      const handle = { host, emit, app: null };
+      boot(handle, props);
+      return handle;
+    },
+    update(handle, props, prevProps) {
+      if (props.doc === prevProps.doc && props.revision === prevProps.revision) return;
+      destroy(handle);
+      boot(handle, props);
+    },
+    unmount(handle) {
+      destroy(handle);
+    },
+  };
+}

package/src/component/shared/memo.js

@@ -0,0 +1,28 @@
+//@ts-check
+/**
+ * Single-entry memoization on argument identity. The viewModel wraps
+ * its derivations with this so an unchanged input slice returns the
+ * PREVIOUS node by reference — which makes the JSLT memo (and through
+ * it the renderer's === fast path) fire for the whole subtree.
+ * Only successful calls populate the memo; a throwing call keeps the
+ * previous successful entry available.
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn
+ * @returns {F}
+ */
+export function memo1(fn) {
+  /** @type {any[] | null} */
+  let lastArgs = null;
+  /** @type {any} */
+  let lastResult;
+  return /** @type {F} */ ((...args) => {
+    if (lastArgs !== null && lastArgs.length === args.length
+      && lastArgs.every((value, i) => value === args[i])) {
+      return lastResult;
+    }
+    const result = fn(...args);
+    lastArgs = args;
+    lastResult = result;
+    return lastResult;
+  });
+}

package/src/component/shared/nodes.js

@@ -0,0 +1,94 @@
+//@ts-check
+/**
+ * Builders for the kind-tagged render-node vocabulary. Boundaries emit
+ * these plain-JSON nodes; the 'ui' view mode renders each kind with one
+ * generic rule. This is the site's component library — as data.
+ */
+
+/** A paragraph of prose. */
+export const p = (text) => ({ kind: 'p', text });
+
+/** A row of stat cards. */
+export const cards = (items) => ({
+  kind: 'cards',
+  items: items.map((i) => ({ kind: 'card', ...i, note: i.note ?? null })),
+});
+
+/** A titled table; rows are `{ cells: string[], strong?: boolean }`. */
+export const table = (title, head, rows, note) => ({
+  kind: 'table', title, head, note: note ?? null,
+  rows: rows.map((r) => ({ kind: 'row', strong: false, ...r })),
+});
+
+/** An informational block with an optional link button. */
+export const callout = (title, text, href, link) =>
+  ({ kind: 'callout', title, text, href: href ?? null, link: link ?? null });
+
+/** A code block; `badge` renders next to the title. */
+export const code = (title, text, badge) =>
+  ({ kind: 'code', title: title ?? null, text, badge: badge ?? null });
+
+/**
+ * One error → one display string. Coded errors compose their own
+ * message (`code: reason at path` per the @jarenjs/core contract), so
+ * this never prefixes anything — prefixing again is how the same suite
+ * used to show one error two different ways on two pages.
+ * @param {unknown} err
+ * @returns {string}
+ */
+export const errorMessage = (err) =>
+  (typeof (/** @type {any} */ (err))?.message === 'string'
+    ? /** @type {any} */ (err).message
+    : String(err));
+
+/** An error block in the engine-error shape (code/docPath/dataPath/position). */
+export function error(err, fallbackTitle) {
+  const parts = [];
+  // A coded error (it carries `reason`) already renders its code and
+  // its location inside `message` — the detail line repeats only what
+  // the message does NOT contain.
+  const composed = typeof err.reason === 'string';
+  if (!composed) {
+    if (err.code) parts.push(`code: ${err.code}`);
+    if (err.docPath !== undefined && err.docPath !== null) {
+      parts.push(`docPath: ${err.docPath === '' ? '"" (document root)' : err.docPath}`);
+    }
+    if (err.dataPath !== undefined && err.dataPath !== null) {
+      parts.push(`dataPath: ${err.dataPath === '' ? '"" (document root)' : err.dataPath}`);
+    }
+  }
+  if (typeof err.position === 'number') parts.push(`position: ${err.position}`);
+  if (typeof err.line === 'number') parts.push(`line: ${err.line}`);
+  if (typeof err.column === 'number') parts.push(`column: ${err.column}`);
+  if (err.hint) parts.push(`hint: ${err.hint}`);
+  return {
+    kind: 'error',
+    title: err.code ?? fallbackTitle ?? err.name ?? 'Error',
+    message: errorMessage(err),
+    detail: parts.length > 0 ? parts.join(' · ') : null,
+  };
+}
+
+/** A collapsible section of further nodes. */
+export const details = (summary, items) => ({ kind: 'details', summary, items });
+
+/** An SVG chart card: `vnode` is @jarenjs/charts' projection (charts
+ * carry their own internal title; `title` adds a card heading only when
+ * the SVG has none). */
+export const chart = (title, vnode, note) =>
+  ({ kind: 'chart', title: title ?? null, vnode, note: note ?? null });
+
+/**
+ * A rendered Markdown article: `vnode` is the @jarenjs/md component's
+ * projection, spliced in verbatim exactly as a chart's SVG is. The
+ * site's own sections are kind-nodes; a section a PACKAGE owns arrives
+ * as markdown, and this is the one node that carries it.
+ */
+export const article = (vnode) => ({ kind: 'article', vnode });
+
+/** A live search input bound to the given action. */
+export const search = (action, value, placeholder) =>
+  ({ kind: 'search', action, value, placeholder });
+
+/** A "show more" button bound to the given action. */
+export const more = (action, label) => ({ kind: 'more', action, label });

package/src/component/shared/schema-options.js

@@ -0,0 +1,30 @@
+//@ts-check
+/**
+ * The validator options every surface uses when it compiles a schema
+ * the component ships — the engine grammars, the chart definition, the
+ * app meta-schema.
+ *
+ * `unknownFormats: 'error'` is the point of the file. `@jarenjs/validate`
+ * defaults to `'ignore'`, because the specification requires that an
+ * unknown `format` be treated as an annotation rather than an assertion
+ * failure, and a library has to be able to compile a stranger's schema.
+ * The component schemas are not a stranger's: a `format` in one of them names a
+ * check we intend to happen, so a name with no registered compiler is a
+ * missing `addFormats` call, and the alternative to failing is a keyword
+ * that silently validates everything. That is how the published grammars
+ * came to declare `format: "json-path"` for a long time without anything
+ * ever checking one.
+ *
+ * The line is deliberate and worth keeping: a schema the USER supplied —
+ * the validator playground's input, a project file in the studio — keeps
+ * the library default, because refusing to compile a stranger's valid
+ * schema over a format we happen not to implement would be our problem
+ * presented as theirs.
+ */
+
+/** Options for compiling a schema this project ships. */
+export const OUR_SCHEMA_OPTIONS = Object.freeze({
+  skipErrors: false,
+  collectErrors: true,
+  unknownFormats: /** @type {'error'} */ ('error'),
+});

package/src/component/shared/studio-kit.js

@@ -0,0 +1,59 @@
+//@ts-check
+/** Shared editor controls and accessible phone pane switching. */
+
+/**
+ * The editor textarea; live buffers publish input before unrelated renders.
+ * @param {{ value: string, action: string, rows?: number,
+ *   readonly?: boolean, live?: boolean }} options
+ */
+export function editorTextarea(options) {
+  return ['textarea', {
+    class: 'editor',
+    rows: options.rows ?? 22,
+    spellcheck: 'false',
+    value: options.value,
+    ...(options.readonly === true ? { readonly: '' } : {}),
+    on: { change: options.action, ...(options.live ? { input: options.action } : {}) },
+  }];
+}
+
+/**
+ * The error line.
+ * @param {any} content - a query expression or literal text
+ */
+export function errorLine(content) {
+  return ['p', { class: 'error-line' }, content];
+}
+
+/**
+ * The phone pane switcher — a segmented bar that shows ONE pane at a
+ * time below the breakpoint, the pattern `@jarenjs/play` established.
+ *
+ * The protocol is three parts, and every surface implements all three:
+ * the pane container carries `data-pane` (the live pane id), this bar
+ * carries the studio's own `-panebar` class plus the shared `seg`
+ * control classes, and the studio's stylesheet hides the unselected
+ * panes inside its `@media (max-width: 1024px)` block. Switching is a
+ * SINGLE attribute write on the container — the panes stay mounted, so
+ * a hidden editor keeps its caret, its scroll and its undo stack, and
+ * nothing re-renders but the bar's two changed buttons.
+ *
+ * The segments are toggle buttons in a group, not a `tablist`: a pane
+ * is a grid area, not a `tabpanel`, so `aria-pressed` states the truth
+ * that `aria-selected` would overclaim.
+ *
+ * @param {{ pane: string, action: string, class: string,
+ *   panes: [string, string][] }} options - `pane` is the query
+ *   expression holding the live pane id, `panes` the `[id, label]`
+ *   pairs in bar order
+ */
+export function paneSwitcher(options) {
+  return ['div', { class: `${options.class} seg`, role: 'group', 'aria-label': 'pane' },
+    ...options.panes.map(([id, label]) => ['button', {
+      type: 'button',
+      class: { $if: [{ $eq: [options.pane, id] }, 'seg-btn active', 'seg-btn'] },
+      'aria-pressed': { $if: [{ $eq: [options.pane, id] }, 'true', 'false'] },
+      on: { click: { action: options.action, with: id } },
+    }, label]),
+  ];
+}