@jarenjs/studio 0.34.0

package/src/assemble.js

@@ -0,0 +1,127 @@
+//@ts-check
+/**
+ * @file Files → runnable artifacts, and the change-classification the IDE
+ * needs to decide reboot-vs-hot-update.
+ *
+ * `assembleArtifacts` composes the project's files into the runnable set.
+ * This order ships the WHOLE-DOCUMENT contract: a runnable file (`app`,
+ * `fsm`, `dag`, `model`, `jslt`, `query`, `schema`) is its own artifact;
+ * `state`/`data` files are inputs, not artifacts. Fragment assembly —
+ * composing separate `state` + `view` + `actions` files into ONE
+ * `jaren-app` document (the true HTML/CSS/JS split) — is the model's
+ * headline enhancement and layers on top without changing this contract.
+ *
+ * `classifyChange` is the load-bearing UX datum: a `state`-only edit must
+ * HOT-DISPATCH into a running app (no reboot, the user keeps scroll and
+ * inputs), while a `view`/`actions` change must reboot. It compares a
+ * STRUCTURAL key (an app doc minus its `state`) via the suite's own
+ * `contentKey`, so the policy in the widget reads clean, tested data.
+ */
+
+import { contentKey } from '@jarenjs/core/object';
+import { validateFile } from './validate.js';
+
+/** Kinds that are runnable artifacts on their own (vs. `state`/`data`
+ * inputs). */
+const RUNNABLE = new Set(['app', 'jslt', 'query', 'schema', 'fsm', 'dag', 'model']);
+
+/** A human role per kind, for the file rail's legibility. */
+const ROLE = Object.freeze({
+  app: 'application', jslt: 'transform', query: 'query', state: 'state',
+  data: 'data', schema: 'schema', fsm: 'state machine', dag: 'dataflow', model: 'data store',
+});
+
+/**
+ * Compose the project's files into runnable artifacts (whole-document).
+ * @param {any} project - a normalized project (from `parseProject`)
+ * @returns {{ artifacts: Array<{ name: string, kind: string, role: string,
+ *   doc: any, sourceFiles: string[] }>, errors: Array<{ file: string, message: string }> }}
+ */
+export function assembleArtifacts(project) {
+  const artifacts = [];
+  const errors = [];
+  for (const file of project.files) {
+    if (!RUNNABLE.has(file.kind)) continue;
+    let doc;
+    try { doc = JSON.parse(file.text); }
+    catch (err) {
+      errors.push({ file: file.name, message: `not valid JSON: ${String(/** @type {any} */ (err)?.message ?? err)}` });
+      continue;
+    }
+    artifacts.push({
+      name: file.name, kind: file.kind, role: ROLE[file.kind], doc, sourceFiles: [file.name],
+    });
+  }
+  return { artifacts, errors };
+}
+
+/** The structural identity of an artifact — an `app`'s view/actions/subs
+ * (its `state` excluded); everything else in full. */
+function structuralKey(artifact) {
+  return artifact.kind === 'app'
+    ? contentKey({ view: artifact.doc.view, actions: artifact.doc.actions, subs: artifact.doc.subs })
+    : contentKey(artifact.doc);
+}
+
+const RANK = { none: 0, 'state-only': 1, structural: 2 };
+
+/**
+ * Classify what changed between two projects, PER artifact — the datum
+ * the widget's reboot-vs-hot-update policy consumes. `state-only` means
+ * an app's state moved but its structure did not (hot-dispatch it);
+ * `structural` means reboot; `none` means nothing changed.
+ * @param {any} prevProject
+ * @param {any} nextProject
+ * @returns {{ overall: 'none' | 'state-only' | 'structural',
+ *   perArtifact: Record<string, 'none' | 'state-only' | 'structural'> }}
+ */
+export function classifyChange(prevProject, nextProject) {
+  const prev = new Map(assembleArtifacts(prevProject).artifacts.map((a) => [a.name, a]));
+  const next = new Map(assembleArtifacts(nextProject).artifacts.map((a) => [a.name, a]));
+  /** @type {Record<string, 'none' | 'state-only' | 'structural'>} */
+  const perArtifact = {};
+  let overall = /** @type {'none' | 'state-only' | 'structural'} */ ('none');
+  const bump = (c) => { if (RANK[c] > RANK[overall]) overall = c; };
+
+  for (const [name, a] of next) {
+    const b = prev.get(name);
+    let c;
+    if (b === undefined) c = 'structural';
+    else if (structuralKey(b) !== structuralKey(a)) c = 'structural';
+    else if (contentKey(b.doc) !== contentKey(a.doc)) c = 'state-only';
+    else c = 'none';
+    perArtifact[name] = c;
+    bump(c);
+  }
+  for (const name of prev.keys()) {
+    if (!next.has(name)) { perArtifact[name] = 'structural'; bump('structural'); }
+  }
+  return { overall, perArtifact };
+}
+
+/**
+ * Per-file metadata for the IDE file rail and the AI `list_files` tool:
+ * kind, validity, size, its role, and which runnable artifact it is (a
+ * `state`/`data` input is not itself an artifact).
+ * @param {any} project - a normalized project
+ * @param {{ operators?: { toOptions: () => any } }} [options]
+ */
+export function describe(project, options = {}) {
+  return {
+    active: project.active,
+    layout: project.layout,
+    files: project.files.map((file) => {
+      const v = validateFile(file, options);
+      return {
+        name: file.name,
+        kind: file.kind,
+        role: ROLE[file.kind] ?? file.kind,
+        size: file.text.length,
+        valid: v.valid,
+        total: v.total,
+        errors: v.errors,
+        artifact: RUNNABLE.has(file.kind) ? file.name : null,
+      };
+    }),
+  };
+}

package/src/component/editor.js

@@ -0,0 +1,59 @@
+//@ts-check
+/**
+ * @file The editor + rail vnode primitives — the baseline IDE, graduated
+ * from the site's studio-kit. Everything is a plain `@jarenjs/view` vnode
+ * (a tagged array), so the whole IDE renders through the same JSLT engine
+ * the rest of the suite uses; no imperative editor widget, no syntax
+ * highlighting (a later concern). The concrete kind→badge map lives here;
+ * its colours are in `styles/studio.css`.
+ */
+
+/**
+ * A baseline code editor: a `<textarea>` with the ergonomics that keep it
+ * from fighting the shell (no browser resize — the splitter owns width;
+ * spell/autocap/autocorrect off so a mobile keyboard does not rewrite
+ * JSON keys). Tab-to-indent and the debounce live in the shell's edit
+ * loop; the value is bound to the active file.
+ *
+ * `inputAction` is load-bearing, not a convenience: this is a CONTROLLED
+ * textarea, and the renderer reasserts a control's authoritative value
+ * after every settled render. If the document only learned about an edit
+ * on `change` (blur), any render in between would rewrite the box with
+ * the still-stale text — and writing `.value` clears the browser's
+ * dirty-value flag, so `change` would then never fire and the typing
+ * would vanish. Publishing each keystroke to the typing buffer keeps the
+ * authoritative value equal to what the user typed, so the reassert is a
+ * no-op and the caret survives.
+ * @param {{ value: any, action: string, inputAction?: string, rows?: number,
+ *   readonly?: boolean }} options
+ */
+export function editorTextarea(options) {
+  return ['textarea', {
+    class: 'js-editor-input',
+    rows: options.rows ?? 20,
+    spellcheck: 'false',
+    autocapitalize: 'off',
+    autocorrect: 'off',
+    autocomplete: 'off',
+    value: options.value,
+    ...(options.readonly === true ? { readonly: '' } : {}),
+    on: options.inputAction === undefined
+      ? { change: options.action }
+      : { input: options.inputAction, change: options.action },
+  }];
+}
+
+/** One line of the docked error strip. */
+export function errorLine(content) {
+  return ['p', { class: 'js-errorline' }, content];
+}
+
+/**
+ * The five concrete kind badge classes (colours are CONSTANTS in
+ * studio.css, not aliased status tokens): view (blue), query (cyan),
+ * json (slate), model (green), flow (amber).
+ */
+export const KIND_BADGE = Object.freeze({
+  app: 'view', jslt: 'view', query: 'query', state: 'json',
+  data: 'json', schema: 'json', model: 'model', fsm: 'flow', dag: 'flow',
+});

package/src/component/host.js

@@ -0,0 +1,53 @@
+//@ts-check
+/**
+ * @file The two hard-problem POLICIES, pure and tested — the DOM
+ * mechanics that consume them live in the widget.
+ *
+ * `hostPolicy` (reboot vs. hot-update): a `state-only` edit hot-dispatches
+ * the new state into the RUNNING nested app (the user keeps scroll and
+ * inputs, no reboot); a `structural` edit reboots; an unchanged artifact
+ * is skipped.
+ *
+ * `reconcileBuffer` (editor buffer ↔ document): a CLEAN buffer adopts an
+ * incoming write (share / undo / an AI edit lands); a DIRTY buffer whose
+ * text differs from the incoming write keeps the human's text and records
+ * the write as a recoverable draft — never a silent clobber, never a
+ * hidden write.
+ */
+
+import { classifyChange } from '../assemble.js';
+
+/**
+ * Per-artifact action a stage host should take between two project
+ * revisions: `reboot` (destroy + boot), `hot` (dispatch new state into
+ * the running app), or `skip` (nothing changed).
+ * @param {any} prevProject
+ * @param {any} nextProject
+ * @returns {Record<string, 'reboot' | 'hot' | 'skip'>}
+ */
+export function hostPolicy(prevProject, nextProject) {
+  const { perArtifact } = classifyChange(prevProject, nextProject);
+  /** @type {Record<string, 'reboot' | 'hot' | 'skip'>} */
+  const out = {};
+  for (const [name, change] of Object.entries(perArtifact)) {
+    out[name] = change === 'structural' ? 'reboot' : change === 'state-only' ? 'hot' : 'skip';
+  }
+  return out;
+}
+
+/**
+ * Reconcile the editor's local typing buffer against an incoming
+ * committed text (a share/undo restore, or an AI write onto the same
+ * file). A clean buffer adopts; a dirty buffer that already matches the
+ * incoming text simply clears (the commit landed); a dirty buffer that
+ * differs keeps the human's text and surfaces the incoming version as a
+ * recoverable `conflict`.
+ * @param {{ text: string, dirty: boolean }} buffer
+ * @param {string} incoming - the file's committed text
+ * @returns {{ text: string, dirty: boolean, conflict: { incoming: string } | null }}
+ */
+export function reconcileBuffer(buffer, incoming) {
+  if (!buffer.dirty) return { text: incoming, dirty: false, conflict: null };
+  if (buffer.text === incoming) return { text: incoming, dirty: false, conflict: null };
+  return { text: buffer.text, dirty: true, conflict: { incoming } };
+}

package/src/component/index.js

@@ -0,0 +1,47 @@
+//@ts-check
+/**
+ * @file The Studio COMPONENT — the IDE. Following the suite's component
+ * convention (`createXComponent`), `createStudioComponent(options)` hands
+ * the host the pieces it composes into the site's `@jarenjs/app` document:
+ * the JSLT view (`rules` + `mode`), the derivation (`viewModel`), the two
+ * hard-problem policies (`hostPolicy`, `reconcileBuffer`), and the engine
+ * surface. The reducer `project/*` actions, the DOM stage/splitter
+ * widgets, and the live site mount are wired at the host; the chrome and
+ * its derivation — everything renderable without a DOM — live here and
+ * are tested headlessly.
+ */
+
+import { describe, validateFile, classifyChange, parseProject } from '../index.js';
+import { projectViewModel } from './viewmodel.js';
+import { projectRules, projectModes, PROJECT_MODE, PROJECT_BASE } from './view.js';
+import { hostPolicy, reconcileBuffer } from './host.js';
+import { editorTextarea, errorLine, KIND_BADGE } from './editor.js';
+
+/**
+ * Build the Studio component.
+ * @param {{ operators?: { toOptions: () => any } }} [options] - a host
+ *   operator registry threaded to every per-file validator/derivation
+ */
+export function createStudioComponent(options = {}) {
+  const operators = options.operators;
+  return {
+    mode: PROJECT_MODE,
+    rules: projectRules,
+    modes: projectModes,
+    /** The IDE view model for the `$.project` slice. */
+    viewModel: (state) => projectViewModel(state, { operators }),
+    // the two hard-problem policies the stage host / editor consume
+    hostPolicy,
+    reconcileBuffer,
+    // the engine surface a host binds at mount time
+    describe: (project) => describe(project, { operators }),
+    validateFile: (file) => validateFile(file, { operators }),
+    classifyChange,
+    parseProject,
+  };
+}
+
+export {
+  projectViewModel, projectRules, projectModes, PROJECT_MODE, PROJECT_BASE,
+  hostPolicy, reconcileBuffer, editorTextarea, errorLine, KIND_BADGE,
+};

package/src/component/view.js

@@ -0,0 +1,198 @@
+//@ts-check
+/**
+ * @file The IDE shell as a JSLT view — the chrome is a document, rendered
+ * by the same engine as the rest of the suite (no imperative chrome, no
+ * syntax highlighting). Following the suite's rule convention: one mode
+ * (`project`), rules matched by their ABSOLUTE slice path, `$apply` and
+ * body references RELATIVE to the matched node. The host mounts the view
+ * model at `$.ui.project`.
+ *
+ * The stage's live nested app and the drag splitter are the only
+ * imperative islands — `jaren-widget`s the host registers. The layout
+ * mode rides a `data-mode` attribute so the grid switches in CSS with no
+ * computed class; the phone pane rides `data-pane` the same way, and a
+ * kind badge rides `data-badge`.
+ */
+
+import { editorTextarea } from './editor.js';
+
+/** The one mode this view uses. */
+export const PROJECT_MODE = 'project';
+/** The slice the host mounts the view model at. */
+export const PROJECT_BASE = '$.ui.project';
+
+/** The modes the host merges into the site stylesheet. */
+export const projectModes = Object.freeze({ [PROJECT_MODE]: { unmatched: 'error' } });
+
+/** One segment of the layout switcher — active when it is the live mode. */
+const layoutButton = (mode, label, title) => ['button', {
+  type: 'button', title,
+  class: { $if: [{ $eq: ['$.layout.mode', mode] }, 'seg-btn active', 'seg-btn'] },
+  on: { click: { action: 'project/layout-mode', with: mode } },
+}, label];
+
+/**
+ * One segment of the phone pane switcher. Below the breakpoint the rail
+ * | editor | stage grid shows ONE pane at a time and this bar picks it;
+ * above the breakpoint the bar does not exist (CSS) and the layout
+ * switcher beside it is what the user reaches for instead.
+ *
+ * A pane is a grid area, not a `tabpanel`, so these are toggle buttons
+ * in a group with `aria-pressed` — not a `tablist` with `aria-selected`.
+ */
+const paneButton = (pane, label) => ['button', {
+  type: 'button',
+  class: { $if: [{ $eq: ['$.mobilePane', pane] }, 'seg-btn active', 'seg-btn'] },
+  'aria-pressed': { $if: [{ $eq: ['$.mobilePane', pane] }, 'true', 'false'] },
+  on: { click: { action: 'project/pane', with: pane } },
+}, label];
+
+/** The shell (matches the whole slice). */
+const shell = {
+  match: PROJECT_BASE, mode: PROJECT_MODE,
+  body: ['div', { class: 'jstudio', 'data-mode': '$.layout.mode', 'data-pane': '$.mobilePane' },
+    // ——— the phone pane switcher (its own grid row; display:none above
+    // the breakpoint, so on a desktop it costs one hidden element) ———
+    ['div', { class: 'js-panebar seg', role: 'group', 'aria-label': 'pane' },
+      paneButton('files', 'Files'),
+      paneButton('editor', 'Editor'),
+      paneButton('stage', 'Stage'),
+    ],
+    // ——— pen bar ———
+    ['div', { class: 'js-penbar' },
+      ['strong', { class: 'js-penname' }, '$.name'],
+      ['span', { class: 'js-savestate' }, '$.saveState'],
+      // the template gallery — opening one replaces the project (host
+      // provides `$.templates`; absent → renders nothing)
+      ['div', { class: 'js-gallery' }, ['span', { class: 'muted' }, 'New'], [{ $apply: '$.templates[*]' }]],
+      ['span', { class: 'js-spacer' }],
+      ['span', { class: 'js-filecount muted' }, ['text', '$.fileCount'], ' files'],
+      // the layout switcher: the three grid modes, riding `layout.mode` →
+      // the `data-mode` attribute the grid switches on (the drag splitter
+      // below drives `layout.ratio` within the chosen mode)
+      ['div', { class: 'js-layout seg', role: 'group', 'aria-label': 'layout' },
+        layoutButton('classic', 'Side', 'Editor beside the stage'),
+        layoutButton('right', 'Swap', 'Stage beside the editor'),
+        layoutButton('top', 'Stack', 'Editor over the stage'),
+      ],
+      ['button', { class: 'btn small', type: 'button', on: { click: 'project/run' } }, 'Run'],
+    ],
+    // ——— file rail ———
+    ['nav', { class: 'js-rail', 'aria-label': 'files' },
+      ['select', { class: 'js-addfile', 'aria-label': 'add a file', value: '', on: { change: 'project/add-file' } },
+        ['option', { value: '' }, '+ add file…'],
+        ['option', { value: 'app' }, 'app'],
+        ['option', { value: 'jslt' }, 'jslt'],
+        ['option', { value: 'query' }, 'query'],
+        ['option', { value: 'state' }, 'state'],
+        ['option', { value: 'data' }, 'data'],
+        ['option', { value: 'schema' }, 'schema'],
+      ],
+      [{ $apply: '$.rail[*]' }]],
+    // ——— editor ———
+    ['div', { class: 'js-editor' },
+      ['div', { class: 'js-editor-head' },
+        // The active file name is editable here → project/rename on commit.
+        // It needs the SAME two-action shape as the editor textarea and for
+        // the same reason (see `editorTextarea`): a controlled value is
+        // reasserted after every settled render, so a rename typed while the
+        // debounced edit loop fires was rewritten mid-word and the commit
+        // then never came. The draft is a separate buffer rather than the
+        // committed value because a rename per keystroke would rename the
+        // file once per letter.
+        ['input', { class: 'js-editor-name', value: '$.renameDraft', spellcheck: 'false',
+          autocapitalize: 'off', autocomplete: 'off', 'aria-label': 'file name',
+          on: { input: 'project/rename-draft', change: 'project/rename' } }],
+        ['span', { class: 'js-editor-kind muted' }, '$.activeKind'],
+        ['span', { class: 'js-spacer' }],
+        ['span', { class: 'js-linecount' }, ['text', '$.lineCount'], ' lines'],
+      ],
+      // a write landed on this file while the buffer was dirty: the human's
+      // text stays in the box, the incoming version stays one click away
+      { $if: ['$.conflict',
+        ['div', { class: 'js-conflict', role: 'status' },
+          ['span', {}, 'This file changed while you were editing — your text is kept.'],
+          ['button', {
+            type: 'button', class: 'js-conflict-take',
+            title: 'Discard your edit and take the version that arrived',
+            on: { click: 'project/buffer-accept' },
+          }, 'Take theirs'],
+        ],
+        ''] },
+      editorTextarea({
+        value: '$.editorValue',
+        action: 'project/file-text',
+        inputAction: 'project/buffer-text',
+      }),
+      { $if: ['$.problemCount',
+        ['div', { class: 'js-errorstrip', role: 'status' }, [{ $apply: '$.problems[*]' }]],
+        ''] },
+    ],
+    // ——— splitter (a pointer-capture widget; its host IS the grab bar) ———
+    ['jaren-widget', {
+      name: 'studio-splitter', class: 'js-split',
+      role: 'separator', 'aria-orientation': 'vertical',
+      'aria-label': 'Resize the editor and stage',
+      'aria-valuemin': '10', 'aria-valuemax': '90', 'aria-valuenow': '$.ratioPct',
+      tabindex: '0',
+      props: { ratio: '$.layout.ratio', mode: '$.layout.mode' },
+    }],
+    // ——— stage ———
+    ['div', { class: 'js-stage' },
+      ['div', { class: 'js-stage-head' }, 'Stage'],
+      { $if: [{ $eq: ['$.stage.kind', 'app'] },
+        ['div', { class: 'js-stage-mount' }, ['jaren-widget', { name: 'studio-stage', props: '$.stage.mount' }]],
+        { $if: [{ $eq: ['$.stage.kind', 'result'] },
+          { $if: ['$.stage.ran',
+            ['div', { class: 'js-stage-result' }, [{ $apply: ['$.stage.nodes[*]', 'ui'] }]],
+            ['p', { class: 'muted js-stage-note' }, 'Edit — this file runs live against the data file here.']] },
+          { $if: [{ $eq: ['$.stage.kind', 'boot-failed'] },
+            ['div', { class: 'js-stage-fail card' }, '$.stage.note'],
+            ['p', { class: 'muted js-stage-note' }, '$.stage.note']] }] }] },
+    ],
+  ],
+};
+
+/** One file-rail row: the select button + a delete affordance. */
+const fileRow = {
+  match: `${PROJECT_BASE}.rail[*]`, mode: PROJECT_MODE,
+  body: ['div', { class: 'js-file-row' },
+    ['button', {
+      type: 'button',
+      class: { $if: ['$.active', 'js-file active', 'js-file'] },
+      title: '$.role',
+      on: { click: { action: 'project/active', with: '$.name' } },
+    },
+    ['span', { class: 'js-badge', 'data-badge': '$.badge' }, '$.kind'],
+    ['span', { class: 'js-file-name' }, '$.name'],
+    { $if: ['$.valid', '', ['span', { class: 'js-file-warn', title: 'this file has errors' }, '●']] },
+    ],
+    ['button', {
+      type: 'button', class: 'js-file-del', title: 'delete this file',
+      'aria-label': 'delete file',
+      on: { click: { action: 'project/delete', with: '$.name' } },
+    }, '×'],
+  ],
+};
+
+/** One template-gallery card — opening it replaces the whole project. */
+const templateRow = {
+  match: `${PROJECT_BASE}.templates[*]`, mode: PROJECT_MODE,
+  body: ['button', {
+    type: 'button', class: 'js-template', title: '$.lead',
+    on: { click: { action: 'project/template', with: '$.id' } },
+  }, '$.title'],
+};
+
+/** One error-strip line — a problem prefixed by its file; click activates it. */
+const errorRow = {
+  match: `${PROJECT_BASE}.problems[*]`, mode: PROJECT_MODE,
+  body: ['button', {
+    class: 'js-errorline', type: 'button',
+    on: { click: { action: 'project/active', with: '$.file' } },
+  },
+  ['strong', {}, '$.file'], ' ', ['code', {}, '$.code'], ' — ', '$.message'],
+};
+
+/** The studio's JSLT rules — spread into the site stylesheet. */
+export const projectRules = [shell, fileRow, templateRow, errorRow];

package/src/component/viewmodel.js

@@ -0,0 +1,150 @@
+//@ts-check
+/**
+ * @file `projectViewModel(state)` — the IDE's derivation boundary. Given
+ * the `state.project` slice it derives everything the JSLT shell renders:
+ * the file rail (from the engine's `describe`), the active file's editor
+ * value and its coded errors, the docked error strip across every file,
+ * and the stage — an assembled app document to mount, a run result to
+ * show, or an inert note for a kind that has no editor of its own yet.
+ * Pure: nothing here is stored back in state.
+ */
+
+import { pickAllowed } from '@jarenjs/core/array';
+import { LAYOUT_DEFAULT } from '../project.js';
+import { describe, assembleArtifacts } from '../assemble.js';
+import { reconcileBuffer } from './host.js';
+import { KIND_BADGE } from './editor.js';
+
+/** The phone panes, in switcher order. */
+const MOBILE_PANES = ['files', 'editor', 'stage'];
+
+/** The stage the active file drives. */
+function deriveStage(project, activeMeta, results, revision, committed) {
+  if (activeMeta === null) return { kind: 'empty', note: 'Add a file to begin.' };
+  if (activeMeta.kind === 'app') {
+    // A host that runs the app live commits the LAST-GOOD assembled
+    // document (with its own reboot revision). That wins over the current
+    // text: a parse error in the editor must never blank the stage — the
+    // last good frame stays until the next VALID commit replaces it.
+    if (committed !== null && committed.doc) {
+      return { kind: 'app', mount: { doc: committed.doc, revision: committed.revision } };
+    }
+    const artifact = assembleArtifacts(project).artifacts.find((a) => a.name === activeMeta.name);
+    if (artifact === undefined || !activeMeta.valid) {
+      return { kind: 'boot-failed', note: `${activeMeta.name} does not boot yet — fix the file (the last good render stays).` };
+    }
+    // the reference-stable mount is memoized by the host at wiring time;
+    // here it is the data: the assembled document + the reboot revision
+    return { kind: 'app', mount: { doc: artifact.doc, revision } };
+  }
+  if (activeMeta.kind === 'jslt' || activeMeta.kind === 'query' || activeMeta.kind === 'schema') {
+    // the host runs the file (a transform, or a schema validating the data
+    // file) and stores its render nodes; the stage renders them in `ui`
+    // mode, or a hint until the first run lands
+    const result = results[activeMeta.name] ?? null;
+    return { kind: 'result', ran: result !== null, nodes: result?.nodes ?? [] };
+  }
+  if (activeMeta.kind === 'state' || activeMeta.kind === 'data') {
+    return { kind: 'inert', note: 'An input — edit it as text; it feeds the app, a query or a validation.' };
+  }
+  // fsm / dag / model validate and assemble, but have no editor and no
+  // runner here yet — the flow canvas and the worker-backed store still
+  // live on their own website surfaces (both are tracked in ROADMAP.md)
+  return { kind: 'inert', note: `The ${activeMeta.role} editor is not built yet; edit it as text meanwhile.` };
+}
+
+/**
+ * Derive the IDE view model from `state.project`.
+ * @param {{ project: any }} state - the site state carrying the `project` slice
+ * @param {{ operators?: { toOptions: () => any } }} [options]
+ * @returns {any}
+ */
+export function projectViewModel(state, options = {}) {
+  const slice = state.project ?? {};
+  const project = {
+    project: slice.project ?? '0.1',
+    files: slice.files ?? [],
+    active: slice.active ?? (slice.files?.[0]?.name ?? null),
+    layout: { ...LAYOUT_DEFAULT, ...slice.layout },
+  };
+  const results = slice.results ?? {};
+  const revision = slice.revision ?? 0;
+
+  const d = describe(project, options);
+  const activeName = project.active;
+  const activeMeta = d.files.find((f) => f.name === activeName) ?? null;
+  const activeFile = project.files.find((f) => f.name === activeName) ?? null;
+
+  const rail = d.files.map((f) => ({
+    name: f.name,
+    kind: f.kind,
+    role: f.role,
+    badge: KIND_BADGE[f.kind] ?? 'json',
+    valid: f.valid,
+    active: f.name === activeName,
+    artifact: f.artifact,
+  }));
+
+  // the docked strip: every file's coded errors, prefixed by file name,
+  // so a broken file anywhere is visible and one click reaches it
+  const problems = [];
+  for (const f of d.files) {
+    for (const e of f.errors) {
+      problems.push({ file: f.name, code: e.code ?? '', message: e.message, docPath: e.docPath ?? '' });
+    }
+  }
+
+  // the host's last-good committed app mount ({ name, doc, revision }),
+  // used only while it is the active file — a reference-stable document
+  // the stage widget reboots (revision change) or hot-updates (same
+  // revision, new state) against
+  const committed = (slice.mount && slice.mount.name === activeName) ? slice.mount : null;
+
+  // The editor's value is the typing BUFFER reconciled against the file's
+  // committed text, never the committed text alone: the buffer is what the
+  // user has typed but not yet committed (the commit lands on blur), and a
+  // controlled textarea must be reasserted with THAT or the renderer
+  // overwrites the user mid-edit. A write that lands on the file while the
+  // buffer is dirty keeps the human's text and surfaces the incoming
+  // version as a recoverable conflict — never a silent clobber, never a
+  // hidden write.
+  const committedText = activeFile ? activeFile.text : '';
+  const buffer = (slice.buffer !== null && slice.buffer !== undefined
+    && slice.buffer.file === activeName)
+    ? { text: slice.buffer.text, dirty: slice.buffer.dirty === true }
+    : { text: committedText, dirty: false };
+  const reconciled = reconcileBuffer(buffer, committedText);
+  const editorValue = reconciled.text;
+  return {
+    name: slice.name ?? 'Untitled project',
+    // the incoming text a conflicting write carried, or null
+    conflict: reconciled.conflict === null ? null : reconciled.conflict.incoming,
+    layout: project.layout,
+    // the splitter's committed handle position, as an integer percent for
+    // aria-valuenow (the widget updates it live during a drag)
+    ratioPct: Math.round((project.layout.ratio ?? 0.5) * 100),
+    active: activeName,
+    // the name field's own typing buffer, defaulting to the committed name.
+    // It follows the active file, so switching files shows that file's name
+    // rather than a half-typed rename of the previous one.
+    renameDraft: (slice.renameDraft !== null && slice.renameDraft !== undefined
+      && slice.renameDraft.file === activeName)
+      ? slice.renameDraft.text
+      : activeName,
+    activeKind: activeMeta?.kind ?? null,
+    activeValid: activeMeta?.valid ?? true,
+    activeErrors: activeMeta?.errors ?? [],
+    editorValue,
+    lineCount: editorValue === '' ? 0 : editorValue.split('\n').length,
+    rail,
+    fileCount: project.files.length,
+    problems,
+    problemCount: problems.length,
+    stage: deriveStage(project, activeMeta, results, revision, committed),
+    saveState: (slice.dirty === true || reconciled.dirty) ? 'Unsaved ●' : 'Saved',
+    // the phone pane (Files · Editor · Stage). This is host chrome, not a
+    // project member: `layout` travels with the saved document, which pane
+    // a phone was showing does not.
+    mobilePane: pickAllowed(slice.mobilePane, MOBILE_PANES, 'editor'),
+  };
+}

package/src/errors.js

@@ -0,0 +1,33 @@
+//@ts-check
+/**
+ * @file Coded errors for `@jarenjs/studio`, on `@jarenjs/core`'s coded
+ * contract: a stable `code` (JS0xxx compile/parse time), a bare
+ * `reason`, and — where a position in the project exists — a `docPath`.
+ *
+ * Only the ENVELOPE raises these: a malformed project document, or a
+ * duplicate file name. A single FILE's grammar problem is never thrown —
+ * it is REPORTED by {@link module:validate.validateFile} as the file
+ * kind's own coded errors (`JQ`/`JA`/`JD`…) with their docPaths, so the
+ * IDE can show them without stopping the world.
+ */
+
+import { CodedError } from '@jarenjs/core/errors';
+
+/** The code table (kept in sync with docs/PROJECT-FORMAT.md). */
+export const STUDIO_CODES = Object.freeze({
+  JS0001: 'the project document is invalid',
+  JS0002: 'a file name is duplicated in the project',
+});
+
+/** A studio-envelope error. */
+export class StudioError extends CodedError {
+  /**
+   * @param {keyof typeof STUDIO_CODES} code
+   * @param {string} reason
+   * @param {string | { docPath?: string }} [location]
+   * @param {{ cause?: unknown }} [options]
+   */
+  constructor(code, reason, location = undefined, options = undefined) {
+    super('StudioError', code, reason, location, options);
+  }
+}