@jarenjs/studio 0.83.3 → 0.84.3

package/src/component/host.js

@@ -9,7 +9,7 @@
  * is skipped.
  *
  * `reconcileBuffer` (editor buffer ↔ document): a CLEAN buffer adopts an
- * incoming write (share / undo / an AI edit lands); a DIRTY buffer whose
+ * incoming write (share / undo / an external 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.
@@ -38,7 +38,7 @@ export function hostPolicy(prevProject, nextProject) {
 
 /**
  * Reconcile the editor's local typing buffer against an incoming
- * committed text (a share/undo restore, or an AI write onto the same
+ * committed text (a share/undo restore, or an external 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

package/src/component/index.js

@@ -1,14 +1,8 @@
 //@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.
+ * The complete project editor and composable host pieces. A host can mount
+ * the editor directly, or compose the same actions, projections and controller
+ * into its application. Preview runners, templates and storage are injected.
  */
 
 import { describe, validateFile, classifyChange, parseProject } from '../index.js';
@@ -45,3 +39,19 @@ export {
   projectViewModel, projectRules, projectModes, PROJECT_MODE, PROJECT_BASE,
   hostPolicy, reconcileBuffer, editorTextarea, errorLine, KIND_BADGE,
 };
+
+export { createStudioDocumentHost } from './document.js';
+export { createProjectHost } from './project.js';
+export { p, cards, table, callout, code, errorMessage, error, details, chart, article, search, more } from './shared/nodes.js';
+export { tabRule, UI_RULES } from './shared/ui.js';
+export { memo1 } from './shared/memo.js';
+export { OUR_SCHEMA_OPTIONS } from './shared/schema-options.js';
+export { createHostWidget } from './shared/host-widget.js';
+
+export { PROJECT_ACTIONS } from './project-actions.js';
+export { createProjectState } from './project-state.js';
+export { createProjectController } from './project-controller.js';
+
+export { mountStudioEditor } from './mount.js';
+
+export { editorTextarea as sharedEditorTextarea, errorLine as editorErrorLine, paneSwitcher } from './shared/studio-kit.js';

package/src/component/mount.js

@@ -0,0 +1,43 @@
+import { createProjectFlowWidget } from './flow/project-widget.js';
+//@ts-check
+/** Mount the complete project chrome with the same transitions used by composed hosts. */
+import { createApp, formEventFields } from '@jarenjs/app';
+import { createProjectController } from './project-controller.js';
+import { createProjectState } from './project-state.js';
+import { PROJECT_ACTIONS } from './project-actions.js';
+import { UI_RULES } from './shared/ui.js';
+
+/**
+ * Execution, document rendering, seeds and private data ownership are host services.
+ * The returned surface publishes document operations; the app state stays private.
+ * @param {HTMLElement | null} node
+ * @param {{ project: object, host: any, projectData?: any, projectTemplate?: Function,
+ *   templates?: any[], widgets?: Record<string, any>, schedule?: (flush: () => void) => void,
+ *   debounceMs?: number, download?: Function, exportProject?: Function, onError?: (error: Error) => void }} options
+ */
+export function mountStudioEditor(node, options) {
+  let app;
+  const host = options.host, component = host.projectComponent;
+  const controller = createProjectController({ ...options, getApp: () => app });
+  app = createApp({
+    state: { project: createProjectState(options.project), ide: { shared: null } },
+    actions: { ...PROJECT_ACTIONS, 'ide/shared': { patch: [{ op: 'replace', path: '/ide/shared', value: '$payload' }] } },
+    view: { $jslt: '0.1', modes: { ...component.modes, ui: { unmatched: 'error' } }, rules: [
+      { match: '$', body: { $apply: ['$.ui.project', 'project'] } }, ...component.rules, ...UI_RULES,
+    ] },
+  }, {
+    node, document: node?.ownerDocument, schedule: options.schedule, onError: options.onError,
+    eventFields: formEventFields(), effects: controller.effects,
+    widgets: { 'studio-flow': createProjectFlowWidget({ schedule: options.schedule }),
+      ...(options.projectData ? { 'studio-data': options.projectData.widget } : {}),
+      'studio-stage': host.createProjectStageWidget({ schedule: options.schedule }),
+      'studio-splitter': host.createProjectSplitterWidget(), ...options.widgets },
+    viewModel: state => ({ ui: { project: { ...component.viewModel(state), templates: options.templates ?? [] } } }),
+  });
+  controller.attach(); controller.commit(); controller.runActive();
+  return {
+    read: controller.read, validate: controller.validate, replace: controller.replace,
+    apply: controller.apply, run: controller.run, subscribe: controller.subscribe,
+    dispose() { controller.dispose(); app.destroy(); },
+  };
+}

package/src/component/project-actions.js

@@ -0,0 +1,189 @@
+//@ts-check
+/** Project editor transitions, shared by every host. */
+export const PROJECT_ACTIONS = {
+  // the Project IDE (#/project, boundaries/project.js): a jaren-project
+  // edited as one document. The editor commits the ACTIVE file's text
+  // through the `project-edit` effect (it rewrites the file by name, in
+  // JS — an array index a patch path cannot compute); the changed
+  // `/project/files` feed then drives the debounced commit
+  // (`project/committed`) that folds in the last-good app stage.
+  // every keystroke publishes to the typing buffer. This is what the
+  // CONTROLLED editor is reasserted with: without it a render between the
+  // keystroke and the blur would rewrite the box with the still-stale
+  // committed text, clearing the browser's dirty-value flag so the commit
+  // never fires and the typing is lost. Cheap by construction — it touches
+  // no file, so nothing revalidates.
+  'project/buffer-text': {
+    patch: [{
+      op: 'replace',
+      path: '/project/buffer',
+      value: { file: '$.project.active', text: '$event.value', dirty: true },
+    }],
+  },
+  // resolve a conflict the human's way round: drop the buffer, so the
+  // incoming (committed) text is what the editor shows
+  'project/buffer-accept': {
+    patch: [{ op: 'replace', path: '/project/buffer', value: null }],
+  },
+  // the commit (blur): the buffer has served its purpose, so it clears
+  // here — on the HUMAN's own commit, never on `project/files-set`, which
+  // is also how an external write lands and must not drop a dirty buffer
+  'project/route-input': { effects: [{ run: 'project-route', with: { member: 'input', value: '$event.value' } }] },
+  'project/route-model': { effects: [{ run: 'project-route', with: { member: 'model', value: '$event.value' } }] },
+  'project/route-collection': { effects: [{ run: 'project-route', with: { member: 'collection', value: '$event.value' } }] },
+  'project/artifact-edit': { effects: [{ run: 'project-artifact-edit', with: '$payload' }] },
+  'project/file-text': {
+    patch: [{ op: 'replace', path: '/project/buffer', value: null }],
+    effects: [{ run: 'project-edit', with: { text: '$event.value' } }],
+  },
+  'project/files-set': {
+    patch: [
+      { op: 'replace', path: '/project/files', value: '$payload.files' },
+      { op: 'replace', path: '/project/dirty', value: true },
+    ],
+  },
+  // switching files drops the buffer: it belongs to the file you left
+  'project/active': {
+    patch: [
+      { op: 'replace', path: '/project/active', value: '$payload' },
+      { op: 'replace', path: '/project/buffer', value: null },
+      // picking a file in the rail — or an error line in the strip — is a
+      // request to EDIT it, and on a phone the rail is a different pane
+      // from the editor. Carry the user across (invisible on desktop).
+      { op: 'replace', path: '/project/mobilePane', value: 'editor' },
+    ],
+  },
+  // the debounced boundary reports the last-good app mount + reboot
+  // revision (an invalid edit keeps the previous — the stage never blanks)
+  'project/committed': {
+    patch: [
+      { op: 'replace', path: '/project/mount', value: '$payload.mount' },
+      { op: 'replace', path: '/project/revision', value: '$payload.revision' },
+      { op: 'replace', path: '/project/dirty', value: false },
+    ],
+  },
+  // explicit Run: force-commit + restart the app stage (or re-run a
+  // transform file). Pressing Run is a request to watch it happen, so on
+  // a phone the stage comes forward with it.
+  'project/execute': {
+    patch: [{ op: 'replace', path: '/project/mobilePane', value: 'stage' }],
+    effects: [{ run: 'project-editor-run', with: '$payload' }],
+  },
+  'project/run': {
+    patch: [{ op: 'replace', path: '/project/mobilePane', value: 'stage' }],
+    effects: [{ run: 'project-run' }],
+  },
+  'project/autorun': {
+    patch: [
+      { op: 'replace', path: '/project/layout/autorun', value: { $not: '$.project.layout.autorun' } },
+      { op: 'replace', path: '/project/dirty', value: true },
+    ],
+  },
+  // a transform file's run result (render nodes) — keyed by file name
+  'project/result': {
+    patch: [{ op: 'add', path: { $concat: ['/project/results/',
+      { $replace: [{ $replace: ['$payload.name', '~', '~0'] }, '/', '~1'] },
+    ] }, value: '$payload.result' }],
+  },
+  // file management: add (a kind from the rail select), delete (× per row),
+  // rename (the editor-head name field). Each rewrites the files array in
+  // JS (an effect), then a patch action lands the result; a name change
+  // resets the mount/results so the stage re-establishes cleanly.
+  'project/add-file': { effects: [{ run: 'project-add', with: { kind: '$event.value' } }] },
+  'project/delete': { effects: [{ run: 'project-delete', with: { name: '$payload' } }] },
+  // the name field's typing buffer — the sibling of `project/buffer-text`,
+  // and cheap the same way: it touches no file, so nothing revalidates
+  'project/rename-draft': {
+    patch: [{
+      op: 'replace',
+      path: '/project/renameDraft',
+      value: { file: '$.project.active', text: '$event.value' },
+    }],
+  },
+  // the commit (blur or Enter), shaped like `project/file-text`: the draft
+  // has served its purpose so it clears, and the effect reads the EVENT —
+  // the value the human actually committed, with no dependence on the
+  // keystroke's own transaction having drained first
+  'project/rename': {
+    patch: [{ op: 'replace', path: '/project/renameDraft', value: null }],
+    effects: [{ run: 'project-rename', with: { name: '$event.value' } }],
+  },
+  'project/added': {
+    patch: [
+      { op: 'replace', path: '/project/files', value: '$payload.files' },
+      { op: 'replace', path: '/project/active', value: '$payload.active' },
+      { op: 'replace', path: '/project/dirty', value: true },
+      { op: 'replace', path: '/project/buffer', value: null },
+    ],
+  },
+  'project/structural': {
+    patch: [
+      { op: 'replace', path: '/project/files', value: '$payload.files' },
+      { op: 'replace', path: '/project/active', value: '$payload.active' },
+      { op: 'replace', path: '/project/mount', value: null },
+      { op: 'replace', path: '/project/results', value: {} },
+      { op: 'replace', path: '/project/dirty', value: true },
+      { op: 'replace', path: '/project/buffer', value: null },
+    ],
+  },
+  // the nested app's own boot/runtime failure (the stage widget emits it)
+  'project/stage-error': { patch: [{ op: 'replace', path: '/project/stageError', value: '$payload' }] },
+  // open a whole project (a template card, or an inbound share token)
+  'project/open': {
+    patch: [
+      { op: 'replace', path: '/project/project', value: { $default: ['$payload.project', '0.1'] } },
+      { op: 'replace', path: '/project/name', value: '$payload.name' },
+      { op: 'replace', path: '/project/files', value: '$payload.files' },
+      { op: 'replace', path: '/project/active', value: '$payload.active' },
+      { op: 'replace', path: '/project/layout', value: '$payload.layout' },
+      { op: 'replace', path: '/project/mount', value: null },
+      { op: 'replace', path: '/project/revision', value: 0 },
+      { op: 'replace', path: '/project/dirty', value: false },
+      { op: 'replace', path: '/project/results', value: {} },
+      { op: 'replace', path: '/project/stageError', value: null },
+      { op: 'replace', path: '/project/buffer', value: null },
+      // opening a project is a request to SEE it — on a phone that means
+      // the stage, not the editor it happens to have activated (the same
+      // move `play/loaded` makes when an example is picked). Desktop
+      // shows every pane, so this patch is invisible there.
+      { op: 'replace', path: '/project/mobilePane', value: 'stage' },
+    ],
+  },
+  'project/template': { effects: [{ run: 'project-template', with: { id: '$payload' } }] },
+  // download the designated app file's document (the Studio's takeaway)
+  'project/download': { effects: [{ run: 'project-download' }] },
+  'project/eject': { effects: [{ run: 'project-eject' }] },
+  'project/export': { effects: [{ run: 'project-export' }] },
+  // the layout switcher (which grid mode) + the splitter (where the handle
+  // sits within that mode); the splitter widget commits on pointer-up
+  'project/layout-mode': { patch: [{ op: 'replace', path: '/project/layout/mode', value: '$payload' }] },
+  'project/layout-ratio': { patch: [{ op: 'replace', path: '/project/layout/ratio', value: '$payload' }] },
+  // the phone pane switcher (Files · Editor · Stage) — pure chrome, and
+  // deliberately NOT part of `layout`: `layout` is a jaren-project member
+  // that saves, shares and downloads with the document, and which pane a
+  // phone happened to be showing is not a property of the project
+  'project/pane': { patch: [{ op: 'replace', path: '/project/mobilePane', value: '$payload' }] },
+
+};
+
+/** Compare at the serialized app transition, including a queued manual edit. */
+PROJECT_ACTIONS['project/replace'] = {
+  $if: [
+    { $eq: [{
+      project: { $default: ['$.project.project', '0.1'] },
+      files: { $default: ['$.project.files', []] },
+      active: { $default: ['$.project.active', null] },
+      layout: '$.project.layout',
+      name: { $default: ['$.project.name', 'Untitled project'] },
+    }, '$payload.expected'] },
+    { patch: [
+      { op: 'replace', path: '/project/project', value: '$payload.document.project' },
+      { op: 'replace', path: '/project/name', value: '$payload.document.name' },
+      { op: 'replace', path: '/project/files', value: '$payload.document.files' },
+      { op: 'replace', path: '/project/active', value: '$payload.document.active' },
+      { op: 'replace', path: '/project/layout', value: '$payload.document.layout' },
+      { op: 'replace', path: '/project/dirty', value: true },
+    ], effects: [{ run: 'project-accepted', with: '$payload.requestId' }] },
+    { effects: [{ run: 'project-refused', with: '$payload.requestId' }] },
+  ],
+};

package/src/component/project-controller.js

@@ -0,0 +1,248 @@
+//@ts-check
+/** @typedef {{ document: any, revision: string, stageRevision: number }} ProjectSnapshot */
+/** @typedef {{ ok: boolean, document?: any, revision?: string, conflict?: boolean, error?: string,
+ * errors?: any[], valid?: boolean, total?: number, code?: string, result?: any, stale?: boolean, requested?: boolean }} EditorReceipt */
+/** Project actions, effects, change feeds and candidate publication share one controller. */
+import { semanticKey } from '@jarenjs/core/object';
+import { applyJSONPatch } from '@jarenjs/json/patch';
+import { renameProjectFile, writeProjectArtifact, resolveProjectFile, fileSkeleton } from '../index.js';
+
+/** @param {{ getApp: () => any, host: any, projectData?: any, projectTemplate?: Function, download?: Function, exportProject?: Function, debounceMs?: number }} env */
+export function createProjectController(env) {
+  const { projectSnapshot, projectAppFile, commitProject, runProjectFile } = env.host;
+  const projectData = env.projectData ?? { dispose() {}, sync() {} };
+  let stopped = false, detach = null, timer = null, requestId = 0;
+  const requests = new Map(), listeners = new Set();
+  const copy = value => JSON.parse(JSON.stringify(value));
+  /** @returns {ProjectSnapshot} */
+  function read() {
+    const document = projectSnapshot(env.getApp().getState().project);
+    return { document: copy(document), revision: semanticKey(document), stageRevision: env.getApp().getState().project.revision };
+  }
+  function validate(candidate) {
+    try {
+      const { name = 'Untitled project', ...envelope } = copy(candidate);
+      if (typeof name !== 'string') throw new TypeError('The project name must be a string.');
+      const document = env.host.projectComponent.parseProject(envelope);
+      const description = env.host.projectComponent.describe(document);
+      const errors = description.files.flatMap(file => file.errors.map(error => ({ ...error, file: file.name })));
+      return { valid: errors.length === 0, errors, total: errors.length, document: projectSnapshot({ ...document, name }) };
+    }
+    catch (error) { return { valid: false, errors: [{ code: error.code ?? 'JS0001', message: error.message, docPath: error.docPath ?? '' }], total: 1 }; }
+  }
+  function settle(id, ok) {
+    const resolve = requests.get(id);
+    if (!resolve) return;
+    requests.delete(id);
+    resolve({ ok, ...read(), ...(ok ? {} : { conflict: true, error: 'The project changed before the candidate could be applied.' }) });
+  }
+  /** Publish only a validated candidate against the caller's observed revision.
+   * @param {any} candidate
+   * @param {{ expectedRevision?: string }} [options]
+
+   * @returns {Promise<EditorReceipt>}
+   */
+  function replace(candidate, { expectedRevision } = {}) {
+    if (stopped) return Promise.resolve({ ok: false, error: 'The project editor is disposed.' });
+    const previous = read();
+    if (typeof expectedRevision !== 'string' || previous.revision !== expectedRevision)
+      return Promise.resolve({ ok: false, conflict: true, error: 'The project revision changed.', ...previous });
+    const checked = validate(candidate);
+    if (!checked.valid) return Promise.resolve({ ok: false, ...checked });
+    return new Promise(resolve => {
+      const id = ++requestId; requests.set(id, resolve);
+      try { env.getApp().dispatch('project/replace', { requestId: id, expected: previous.document, document: checked.document }); }
+      catch (error) { requests.delete(id); resolve({ ok: false, error: error.message }); }
+    });
+  }
+  /** @param {Parameters<typeof applyJSONPatch>[1]} patch @param {{ expectedRevision?: string }} [options]
+   * @returns {Promise<EditorReceipt>}
+   */
+  function apply(patch, options) {
+    try { return replace(applyJSONPatch(read().document, patch), options); }
+    catch (error) { return Promise.resolve({ ok: false, error: error.message, code: error.code }); }
+  }
+  /** Run a file through the shared host. Computational runs return their settled
+   * render result; interactive app files acknowledge their stage restart.
+   * `restart: false` commits an interactive app through its normal hot-update
+   * path, preserving local state when only document state changed.
+   * @param {string} [name] @param {{ restart?: boolean }} [options]
+   * @returns {Promise<EditorReceipt> | { error: string }} */
+  function run(name = env.getApp().getState().project.active, options = {}) {
+    if (stopped) return { error: 'The project editor is disposed.' };
+    const app = env.getApp();
+    if (!app.getState().project.files.some(file => file.name === name)) return { error: `Unknown project file '${name}'.` };
+    const before = read();
+    return new Promise(resolve => {
+      const id = ++requestId; requests.set(id, resolve);
+      app.dispatch('project/execute', { requestId: id, name, expectedRevision: before.revision, restart: options.restart !== false });
+    });
+  }
+  /** @param {(snapshot: ProjectSnapshot) => void} listener */
+  function subscribe(listener) {
+    if (stopped) return () => {};
+    listeners.add(listener); return () => listeners.delete(listener);
+  }
+  function commit() {
+    const app = env.getApp(), state = app?.getState().project;
+    if (!stopped && state) app.dispatch('project/committed', commitProject(state));
+  }
+  function runActive() {
+    const app = env.getApp(), state = app?.getState().project;
+    if (stopped || !state) return;
+    const file = state.files.find(f => f.name === state.active);
+    if (file && !file.model && ['query', 'jslt', 'schema', 'contract'].includes(file.kind))
+      app.dispatch('project/result', { name: state.active, result: runProjectFile(state, state.active) });
+  }
+  function attach() {
+    if (detach || stopped) return;
+    let revision = read().revision;
+    detach = env.getApp().subscribe((state, changes) => {
+      if (stopped || (changes !== null && !changes.some(path => path === '/project' || path.startsWith('/project/')))) return;
+      const current = read();
+      if (revision !== current.revision) { revision = current.revision; for (const listener of listeners) listener(current); }
+      if (changes === null) { projectData.sync(state.project, true); return; }
+      if (changes.some(path => path === '/project/files' || path.startsWith('/project/files/')))
+        projectData.sync(state.project, changes.includes('/project/project'));
+      if (!changes.some(path => path === '/project/files' || path.startsWith('/project/files/') || path === '/project/active' || path === '/project/layout/autorun')) return;
+      const run = () => { if (!stopped && env.getApp().getState().project.layout.autorun !== false) { commit(); runActive(); } };
+      if ((env.debounceMs ?? 250) === 0) run();
+      else { clearTimeout(timer); timer = setTimeout(run, env.debounceMs ?? 250); }
+    });
+  }
+  function dispose() {
+    if (stopped) return;
+    stopped = true; clearTimeout(timer); detach?.(); detach = null; projectData.dispose(); listeners.clear();
+    for (const resolve of requests.values()) resolve({ ok: false, error: 'The project editor is disposed.' });
+    requests.clear();
+  }
+  const effects = {
+    'project-accepted': id => settle(id, true),
+    'project-refused': id => settle(id, false),
+    'project-editor-run': async (props, dispatch) => {
+      const finish = outcome => { const resolve = requests.get(props.requestId); requests.delete(props.requestId); resolve?.(outcome); };
+      if (stopped) { finish({ ok: false, error: 'The project editor is disposed.' }); return; }
+      if (read().revision !== props.expectedRevision) { finish({ ok: false, conflict: true, ...read() }); return; }
+      const state = env.getApp().getState().project, file = state.files.find(f => f.name === props.name);
+      dispatch('project/active', props.name);
+      dispatch('project/pane', 'stage');
+      if (file?.kind === 'app') {
+        if (props.restart === false) dispatch('project/committed', commitProject(state));
+        else dispatch('project/run');
+        await Promise.resolve(); finish({ ok: true, requested: true, ...read() }); return;
+      }
+      try {
+        const result = await runProjectFile(state, props.name, { model: projectData.execute });
+        if (stopped) return;
+        if (result === null) { finish({ ok: false, error: `File '${props.name}' has no result runner in this host.` }); return; }
+        if (env.getApp().getState().project.files !== state.files) { finish({ ok: false, stale: true, result: copy(result) }); return; }
+        dispatch('project/result', { name: props.name, result });
+        finish({ ok: true, ...read(), result: copy(result) });
+      }
+      catch (error) { finish({ ok: false, error: error.message, code: error.code }); }
+    },
+    // the app-document download: the project's designated app file, under
+    // the name Studio downloads always carried
+    'project-download': (props, dispatch) => {
+      const file = projectAppFile(env.getApp().getState().project);
+      if (file === null) { dispatch('ide/shared', 'this project has no app document'); return; }
+      let doc;
+      try { doc = resolveProjectFile(env.getApp().getState().project, file.name).doc; }
+      catch { dispatch('ide/shared', 'the app document is not valid JSON'); return; }
+      const saved = env.download?.('jaren-studio-app.json', JSON.stringify(doc, null, 2));
+      dispatch('ide/shared', saved === true ? 'document downloaded' : 'download unavailable here');
+    },
+    'project-eject': async (props, dispatch) => {
+      try {
+        dispatch('ide/shared', 'Preparing offline project…');
+        const saved = await env.exportProject?.(projectSnapshot(env.getApp().getState().project));
+        dispatch('ide/shared', saved ? 'offline project downloaded' : 'offline export unavailable here');
+      }
+      catch (error) { dispatch('ide/shared', error.message); }
+    },
+    'project-export': (props, dispatch) => {
+      const snapshot = projectSnapshot(env.getApp().getState().project);
+      const saved = env.download?.('jaren-project.json', JSON.stringify(snapshot, null, 2));
+      dispatch('ide/shared', saved === true ? 'project downloaded' : 'download unavailable here');
+    },
+
+    // the Project IDE: the editor commits the ACTIVE file's text (rewriting
+    // it by name — an array index a patch path cannot compute); explicit
+    // Run force-restarts the app stage; a template card opens a project.
+    'project-route': (props, dispatch) => {
+      const p = env.getApp().getState().project;
+      const files = p.files.map((f) => {
+        if (f.name !== p.active) return f;
+        const next = { ...f };
+        if (props.value === '') delete next[props.member];
+        else next[props.member] = props.value;
+        if (props.member === 'model') delete next.collection;
+        return next;
+      });
+      dispatch('project/files-set', { files });
+    },
+    'project-artifact-edit': (props, dispatch) => {
+      const p = env.getApp().getState().project;
+      let files;
+      try { files = writeProjectArtifact(p, props.name, props.doc); }
+      catch (error) { dispatch('project/stage-error', error.message); return; }
+      dispatch('project/files-set', { files });
+    },
+    'project-edit': (props, dispatch) => {
+      const p = env.getApp().getState().project;
+      const files = p.files.map((f) => (f.name === p.active ? { ...f, text: props.text } : f));
+      dispatch('project/files-set', { files });
+    },
+    'project-run': Object.assign((props, dispatch) => {
+      const state = env.getApp().getState().project;
+      const active = state.files.find((f) => f.name === state.active);
+      const commit = commitProject(state);
+      const fragment = commit.mount?.sourceFiles?.includes(state.active) && commit.mount.name !== state.active;
+      // a transform / schema / contract file re-runs; an app file force-restarts
+      if (active !== undefined && !fragment && !active.model && (active.kind === 'query' || active.kind === 'jslt' || active.kind === 'schema'
+        || active.kind === 'contract')) {
+        dispatch('project/result', { name: state.active, result: runProjectFile(state, state.active) });
+        return;
+      }
+      const mount = commit.mount === null ? null : { ...commit.mount, revision: commit.mount.revision + 1 };
+      dispatch('project/committed', { mount, revision: mount === null ? commit.revision : mount.revision });
+    }, { dispose }),
+    'project-template': (props, dispatch) => {
+      const template = env.projectTemplate?.(props.id);
+      if (template === undefined) return;
+      dispatch('project/open', template);
+      // commit NOW, computed from the template itself: the debounced edit
+      // loop alone leaves a race where an edit inside the debounce window
+      // supersedes the opening commit — the "last good frame" then never
+      // existed and an invalid edit blanks the stage
+      dispatch('project/committed', commitProject(template));
+    },
+    // file management (the files array is an array — index-by-name lives in
+    // JS here, then a patch action lands the result)
+    'project-add': (props, dispatch) => {
+      const text = fileSkeleton(props.kind);
+      if (text === null || text === undefined) return;
+      const p = env.getApp().getState().project;
+      let n = 1;
+      let name = `${props.kind}-${n}.${props.kind}`;
+      while (p.files.some((f) => f.name === name)) { n += 1; name = `${props.kind}-${n}.${props.kind}`; }
+      dispatch('project/added', { files: [...p.files, { name, kind: props.kind, text }], active: name });
+    },
+    'project-delete': (props, dispatch) => {
+      const p = env.getApp().getState().project;
+      if (p.files.length <= 1) return; // never delete the last file
+      const files = p.files.filter((f) => f.name !== props.name);
+      if (files.length === p.files.length) return; // no such file
+      const active = p.active === props.name ? files[0].name : p.active;
+      dispatch('project/structural', { files, active });
+    },
+    'project-rename': (props, dispatch) => {
+      const p = env.getApp().getState().project;
+      const next = String(props.name ?? '').trim();
+      if (next === '' || next === p.active || p.files.some((f) => f.name === next)) return;
+      const files = renameProjectFile(p.files, p.active, next);
+      dispatch('project/structural', { files, active: next });
+    },
+  };
+  return { effects, attach, dispose, commit, runActive, read, validate, replace, apply, run, subscribe };
+}

package/src/component/project-state.js

@@ -0,0 +1,30 @@
+//@ts-check
+/** One independent project editor state over a host-supplied document. */
+import { parseProject } from '../project.js';
+
+export function createProjectState(project) {
+ const { name = 'Untitled project', ...envelope } = JSON.parse(JSON.stringify(project));
+ project = { ...parseProject(envelope), name };
+ return {
+      ...project,
+      mount: null,       // last-good { name, doc, revision } for the active app
+      revision: 0,       // reboot key — bumps only on a structural change
+      dirty: false,      // the editor has uncommitted text
+      // the editor's typing buffer ({ file, text, dirty } or null): every
+      // keystroke lands here, the commit lands on blur. It is what the
+      // controlled textarea is reasserted with, so a render mid-edit cannot
+      // overwrite the user; a write arriving on the same file while it is
+      // dirty raises a conflict instead of clobbering either side.
+      buffer: null,
+      // the file-name field's own buffer ({ file, text } or null). Separate
+      // from `buffer` because its commit is a RENAME: publishing every
+      // keystroke straight through would rename the file once per letter.
+      renameDraft: null,
+      results: {},       // file name -> a run result (query/jslt: later order)
+      stageError: null,  // the nested app's own boot/runtime failure, if any
+      // the phone layout: which single pane shows (files | editor | stage).
+      // Pure chrome — the panes stay mounted, CSS picks one, and the
+      // project/* re-run feed ignores this path by construction.
+      mobilePane: 'editor',
+    };
+}