@jarenjs/studio 0.83.3 → 0.85.0

package/dist/types/data/handlers.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @file The data studio's handler table, apart from the browser that
+ * hosts it.
+ *
+ * `db-worker.js` is the OWNER context: it loads the SQLite wasm build,
+ * claims the OPFS access-handle pool and serves two transports. None of
+ * that is testable outside a browser, and none of it is where the
+ * studio's behaviour lives — so the behaviour is here, over an injected
+ * host, and the worker supplies the real one. The same table then runs
+ * under a Node driver in the test suite, which is how the store rules
+ * below are held to anything at all.
+ *
+ * What the table owns, and the worker deliberately does not:
+ *
+ *  - **The live registry.** Every `data.live` registration is held in a
+ *    set, and `data.lives` reports its SIZE. A count kept as a number
+ *    beside the registrations drifts the moment a reopen zeroes it while
+ *    subscriptions are still held — under-reporting forever, and going
+ *    negative on the next release, at which point the count fails its own
+ *    output schema and freezes at its last good value. A frozen count
+ *    reads exactly like a healthy one, which is why this is a set.
+ *  - **Reopening releases.** Closing the store releases every registration
+ *    it fed, so the count comes back to zero because the subscriptions
+ *    ended, not because someone assigned zero.
+ *  - **A refused migration does not advance the model.** `state.model`
+ *    moves only when `migrate()` returned; a store reopened after a
+ *    refusal is reopened on the model it still has, and the refusal
+ *    crosses as the declared `db` failure.
+ *  - **Peers are told.** Any reopen — open, recreate, migrate — drops the
+ *    live registrations of every tab, so the worker announces it and the
+ *    boundaries resubscribe. Silence would leave every live pane showing
+ *    its last rows forever while looking live.
+ *  - **Recreating is owner-only.** `reset` unlinks the database the owner
+ *    holds; a client tab asking for it is refused rather than served, so
+ *    the control that is honest in the owning tab cannot be destructive
+ *    from another one.
+ *  - **The oracle's store is throwaway.** `data.oracle` opens a fresh
+ *    in-memory store on the model it is handed, answers one query over
+ *    the documents it is handed (with its plan, when asked), and closes
+ *    it — the store this context holds, its registrations and its peers
+ *    are untouched. That is what
+ *    lets the committed spatial corpus hold SQLite-in-wasm to the
+ *    JavaScript engine from any tab, including one with no OPFS at all.
+ */
+export type DataHost = {
+    /**
+     * - Decide the topology and prepare
+     * this context; resolves to the `data.init` answer.
+     */
+    init: () => Promise<any>;
+    /**
+     * - A fresh driver over a fresh handle.
+     */
+    makeDriver: () => any;
+    /**
+     * - A driver over a throwaway
+     * in-memory handle: the oracle's store, opened and closed per call,
+     * never the database this context holds.
+     */
+    makeScratchDriver: () => any;
+    /**
+     * - The database path for this context.
+     */
+    path: () => string;
+    /**
+     * - The VFS this context settled on.
+     */
+    vfs: () => string;
+    /**
+     * - Whether a migration can be applied
+     * here at all; a memory store recreates instead.
+     */
+    durable: () => boolean;
+    /**
+     * - Drop the persistent database.
+     */
+    unlink: () => void;
+    /**
+     * - Tell every peer the store
+     * was reopened under them.
+     */
+    announce: (notice: any) => void;
+    /**
+     * - The operator registry the store mounts.
+     */
+    operators: any;
+};
+/**
+ * The host the table runs over: everything that differs between a
+ * browser worker holding an OPFS pool and a test holding a file.
+ * @typedef {Object} DataHost
+ * @property {() => Promise<any>} init - Decide the topology and prepare
+ *   this context; resolves to the `data.init` answer.
+ * @property {() => any} makeDriver - A fresh driver over a fresh handle.
+ * @property {() => any} makeScratchDriver - A driver over a throwaway
+ *   in-memory handle: the oracle's store, opened and closed per call,
+ *   never the database this context holds.
+ * @property {() => string} path - The database path for this context.
+ * @property {() => string} vfs - The VFS this context settled on.
+ * @property {() => boolean} durable - Whether a migration can be applied
+ *   here at all; a memory store recreates instead.
+ * @property {() => void} unlink - Drop the persistent database.
+ * @property {(notice: any) => void} announce - Tell every peer the store
+ *   was reopened under them.
+ * @property {any} operators - The operator registry the store mounts.
+ */
+/**
+ * The details of the declared `db` failure: the store's own coded refusal
+ * and its message.
+ *
+ * The contract carries string codes, including numeric DOMException
+ * codes converted to strings. The host's message survives unchanged.
+ * @param {unknown} error
+ * @returns {{ code: string | null, message: string }}
+ */
+export declare function wireError(error: unknown): {
+    code: string | null;
+    message: string;
+};
+/**
+ * The studio's handler table over an injected host.
+ * @param {DataHost} host
+ * @returns {{ handlers: Record<string, any>, clientHandlers: Record<string, any>, state: any, dispose: () => Promise<void> }}
+ */
+export declare function createDataHandlers(host: DataHost): {
+    handlers: Record<string, any>;
+    clientHandlers: Record<string, any>;
+    state: any;
+    dispose: () => Promise<void>;
+};

package/dist/types/data/host.d.ts

@@ -0,0 +1,8 @@
+export { createDataHandlers, wireError } from './handlers.js';
+export { dataContract, dataContractDocument } from './contract.js';
+export { BOOT_STAGES, BOOT_ERROR_CODE, DEFAULT_BOOT_BUDGETS, DataBootError, bootFailure, resolveBootBudgets, createStageRunner } from './boot-stages.js';
+export { selectBrowserStorage, discoverStorageOwner } from './storage.js';
+export type DataHost = import('./handlers.js').DataHost;
+/** @typedef {import('./handlers.js').DataHost} DataHost */
+export { createBrowserDataWorker } from './browser-worker.js';
+export { createProjectDataWorker } from './project-worker.js';

package/dist/types/data/project-worker.d.ts

@@ -0,0 +1,8 @@
+/** @param {{ initialize: () => Promise<any>, scope: any, operators?: any }} env */
+export declare function createProjectDataWorker(env: {
+    initialize: () => Promise<any>;
+    scope: any;
+    operators?: any;
+}): {
+    dispose(): Promise<void>;
+};

package/dist/types/data/runtime.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The runtime: effects plus the exported view model.
+ * @param {any} env - explicit seed documents, transport, lifecycle and optional worked examples.
+ */
+export declare function createDataRuntime(env?: any): {
+    effects: {
+        'data-boot': (_props: any, dispatch: any) => Promise<void>;
+        'data-retry': (_props: any, dispatch: any) => Promise<void>;
+        'data-resume': (_props: any, dispatch: any) => Promise<void>;
+        'data-open': (props: any, dispatch: any) => Promise<{
+            ok: boolean;
+            error: string | undefined;
+        }> | Promise<{
+            ok: boolean;
+            model: any;
+        } | {
+            ok: boolean;
+            error: string;
+            code: any;
+        }> | undefined;
+        'data-insert': (props: any, dispatch: any) => void;
+        'data-delete': (props: any, dispatch: any) => void;
+        'data-run': (props: any, dispatch: any) => Promise<{
+            ok: boolean;
+            error: string | undefined;
+        }> | Promise<{
+            ok: boolean;
+            result: any;
+            explain: {
+                sql: any;
+                params: any;
+                indexes: any;
+                residual: any;
+            };
+        } | {
+            ok: boolean;
+            error: string;
+            code: any;
+        }>;
+        'data-oracle': (_props: any, dispatch: any) => void;
+        'data-trip': (props: any, dispatch: any) => void;
+        'data-migrate': (_props: any, dispatch: any) => Promise<any> | undefined;
+    };
+    ownerSub: (_props: any, dispatch: any) => (() => void) | undefined;
+    dispose: () => void;
+};

package/dist/types/data/state.d.ts

@@ -0,0 +1,33 @@
+/** Isolated Data state; the boot operation seeds the editable documents. */
+export declare function createDataState(): {
+    status: string;
+    boot: null;
+    topology: string;
+    vfs: string;
+    version: string;
+    capture: string;
+    operators: never[];
+    pushableOperators: never[];
+    refusal: null;
+    modelText: string;
+    queryText: string;
+    collection: string;
+    keyPointer: string;
+    rows: never[];
+    results: never[];
+    explain: null;
+    live: {
+        rows: never[];
+        seq: null;
+        regs: null;
+    };
+    insertDraft: string;
+    migration: null;
+    oracle: null;
+    trip: {
+        csv: string;
+        report: null;
+    };
+    error: null;
+    mobilePane: string;
+};

package/dist/types/data/storage.d.ts

@@ -0,0 +1,26 @@
+/** The browser storage ladder reports every observed fallback. */
+/** @param {{ isolated: boolean, sharedArrayBuffer: boolean,
+ *   sab: () => Promise<any>, sah: () => Promise<any>, indexedDB: () => Promise<any> }} probes
+ * @returns {Promise<any>}
+ */
+export declare function selectBrowserStorage(probes: {
+    isolated: boolean;
+    sharedArrayBuffer: boolean;
+    sab: () => Promise<any>;
+    sah: () => Promise<any>;
+    indexedDB: () => Promise<any>;
+}): Promise<any>;
+/** Discover a peer after storage acquisition failed without a Web Lock.
+ * Silence says only that no peer answered in time. When OPFS reported a
+ * held handle, it cannot authorize a private memory fallback.
+ * @param {{ held?: boolean }} selected
+ * @param {(ms: number) => Promise<false | { vfs: string }>} ping
+ * @returns {Promise<false | { vfs: string }>}
+ */
+export declare function discoverStorageOwner(selected: {
+    held?: boolean;
+}, ping: (ms: number) => Promise<false | {
+    vfs: string;
+}>): Promise<false | {
+    vfs: string;
+}>;

package/dist/types/data/transport.d.ts

@@ -0,0 +1,69 @@
+export type TransportDeps = {
+    /**
+     * - a fresh owner worker
+     */
+    spawnWorker: () => any;
+    /**
+     * - a port client over a channel
+     */
+    openClient?: (channel: any) => any;
+    /**
+     * - the shared tab channel
+     */
+    openChannel: () => any;
+    /**
+     * - per-stage budgets
+     */
+    budgets?: Readonly<Record<string, number>>;
+    setTimer?: (fn: () => void, ms: number) => any;
+    clearTimer?: (handle: any) => void;
+};
+/**
+ * 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 declare function createTransport(deps?: TransportDeps): {
+    boot: () => Promise<any>;
+    bounded: (name: string, work: (advance: (next: string) => void) => any) => Promise<any>;
+    request: (op: any, args: any) => Promise<any>;
+    subscribe: (input: any, callbacks: any) => any;
+    close: () => void;
+    /** The stage the last boot reached (for a failure outside a run). */
+    stage: () => string;
+    /** @param {(notice: any) => void} cb */
+    notices: (cb: (notice: any) => void) => void;
+    /** @param {(fault: { message: string }) => void} cb - a worker that
+     * fails after the boot settled */
+    faults: (cb: (fault: {
+        message: string;
+    }) => void) => void;
+    settled: () => void;
+};

package/dist/types/flow-document.d.ts

@@ -0,0 +1,19 @@
+export declare const validateDagDoc: import("@jarenjs/validate").CompiledCollector;
+/** @param {'fsm'|'dag'} kind @param {any} document */
+export declare function validateFlowDocument(kind: 'fsm' | 'dag', document: any): {
+    valid: boolean;
+    kind: string;
+    total: number;
+    errors: Array<{
+        code: string | null;
+        message: string;
+        docPath?: string;
+    }>;
+} | {
+    valid: boolean;
+    errors: {
+        code: any;
+        message: any;
+        docPath: any;
+    }[];
+};

package/dist/types/flow-editor.d.ts

@@ -0,0 +1,88 @@
+export type FlowSnapshot = {
+    kind: 'fsm' | 'dag' | null;
+    document: any;
+    revision: string;
+    result: any;
+};
+export type EditorReceipt = {
+    ok: boolean;
+    document?: any;
+    revision?: string;
+    conflict?: boolean;
+    error?: string;
+    errors?: any[];
+    valid?: boolean;
+    total?: number;
+    code?: string;
+    output?: any;
+    started?: boolean;
+};
+import { applyJSONPatch } from '@jarenjs/json/patch';
+/** @param {{ kind?: 'fsm'|'dag'|null, document?: any, input?: any }} [options] */
+export declare function createFlowState(options?: {
+    kind?: 'fsm' | 'dag' | null;
+    document?: any;
+    input?: any;
+}): {
+    kind: "dag" | "fsm" | null;
+    doc: any;
+    selection: null;
+    connect: null;
+    tab: string;
+    parseError: null;
+    history: {
+        past: never[];
+        future: never[];
+    };
+    run: null;
+    runContext: any;
+    dagInput: string;
+    revision: number;
+    mobilePane: string;
+};
+/** @param {{ getApp: () => any, runtime: any }} env */
+export declare function createFlowController(env: {
+    getApp: () => any;
+    runtime: any;
+}): {
+    read: () => FlowSnapshot;
+    validate: (candidate: any, kind?: 'fsm' | 'dag') => {
+        valid: boolean;
+        kind: string;
+        total: number;
+        errors: Array<{
+            code: string | null;
+            message: string;
+            docPath?: string;
+        }>;
+    } | {
+        valid: boolean;
+        errors: {
+            code: any;
+            message: any;
+            docPath: any;
+        }[];
+    };
+    replace: (candidate: any, options?: {
+        expectedRevision?: string;
+        kind?: 'fsm' | 'dag';
+    }) => Promise<EditorReceipt>;
+    apply: (patch: Parameters<typeof applyJSONPatch>[1], options?: {
+        expectedRevision?: string;
+        kind?: 'fsm' | 'dag';
+    }) => Promise<EditorReceipt>;
+    run: (options?: {
+        input?: any;
+        event?: string;
+    }) => Promise<EditorReceipt>;
+    subscribe: (listener: (snapshot: FlowSnapshot) => void) => () => void;
+    attach: () => void;
+    effects: {
+        'flow-accepted': (id: any) => void;
+        'flow-refused': (id: any) => void;
+        'flow-editor-run': ((props: any, dispatch: any) => Promise<void>) & {
+            dispose: () => void;
+        };
+    };
+    dispose: () => void;
+};

package/docs/EDITORS.md

@@ -0,0 +1,158 @@
+# Shared editors and host services
+
+Studio publishes the complete project, Flow and Data editors used by the Jaren
+website. Their actions, views, controllers and resource lifetimes have one
+implementation. A host supplies its own page, templates and execution services.
+The root `@jarenjs/studio` entry remains a headless project engine.
+
+| Public entry | What the host receives |
+| --- | --- |
+| `@jarenjs/studio/component` | Project mount, document/render host, project host, actions, controller and view pieces |
+| `@jarenjs/studio/flow` | Flow mount, actions, diagram/text/inspector projections, controller, machine/DAG runtime and project-file widget |
+| `@jarenjs/studio/data` | Data mount, actions, projections, controller, bounded transport and project-model worker ownership |
+| `@jarenjs/studio/data/host` | Compiled operation contract, handler table, boot stages, storage selection and injected browser/project worker hosts |
+| `@jarenjs/studio/contracts/data.contract.json` | The unchanged `jaren-data-studio` operation document |
+| `@jarenjs/studio/styles/studio.css` | Project chrome, shared controls and embedded Flow styles |
+| `@jarenjs/studio/styles/flow.css` | Standalone Flow chrome and shared controls |
+| `@jarenjs/studio/styles/data.css` | Standalone Data chrome and shared controls |
+| `@jarenjs/studio/styles/editor.css` | Scoped common controls and generated-form chrome |
+
+The installed-host fixture in `test/consumer/studio-installed.js` composes all
+three editors using public imports. The packed consumer gate runs it with real
+Node and Bun SQLite drivers and bundles a separate browser host with private
+SQLite initialization. It imports no website source.
+
+## Operations and revisions
+
+Every mount returns `read`, `validate`, `replace`, `apply`, `run`, `subscribe` and
+`dispose`. Data additionally returns `ready`, which resolves to an actual boot
+success or failure. The app that implements each editor stays private.
+
+`read()` returns an isolated document and a string `revision`. Revisions describe
+the current document, rather than a counter incremented by unrelated rendering.
+`subscribe(listener)` observes document changes and returns an unsubscribe
+function. Disposing twice is safe; disposal ends subscriptions, pending work and
+owned runtimes. A disposed editor refuses publication and execution.
+
+`validate(candidate)` uses the existing document validators and returns a
+verdict and errors. `replace(candidate, { expectedRevision })` validates and then
+checks the observed revision again inside the same queued transition used by
+manual edits. A stale revision returns `{ ok: false, conflict: true }`. Invalid or
+stale candidates preserve documents, results and typing buffers.
+`apply(patch, { expectedRevision })` applies an RFC 6902 patch to the read document
+and follows that same replacement path. Keep the returned candidate and errors
+when publication is refused; obtain a fresh revision before trying again.
+
+Project documents include the project name, files, active file and layout.
+Uncommitted typing remains a separate buffer: an external file replacement keeps
+that draft and the existing conflict UI. `run(name?)` selects the requested file
+and uses the same host runners and result actions as the controls. It returns
+settled transform, flow and model results, refusing stale results after edits.
+An interactive app file acknowledges its requested stage restart. The injected
+`projectData.execute(project, name)` owns model-query execution.
+
+Flow documents are the `jaren-fsm` or `jaren-dag` value. Replacement retains an
+undo entry, invalidates the previous run and clears structural selection. The
+kind stays fixed while a document is open; templates open a new document.
+`run({ input, event? })` uses the injected task registry or the mounted machine.
+A DAG returns its settled output or failure. `event` sends a machine event
+through the same sandbox used by the run controls.
+
+Data documents contain `{ model, query }`. `read()` also returns `buffers`
+(`modelText` and `queryText`), results and the query plan. Its revision includes
+both raw buffers, so even an unfinished JSON edit prevents a stale replacement.
+Replacing the document edits those buffers. It does not recreate a database.
+`run({ operation: 'query', externals })` executes and explains against the open
+store. `run({ operation: 'open' })` explicitly recreates the model through the
+existing owner-only operation. A client or memory topology retains the same
+recreation refusal as the manual UI. Data accepts JSON row input by default;
+a host can inject its existing `createRow(text)` convenience function.
+
+## Project and Flow hosts
+
+`createStudioDocumentHost({ markdown, diagram, templates? })` validates and audits
+app documents and provides the form/chart/Markdown/diagram render widgets. The
+host supplies its Markdown and diagram rendering policy.
+`createProjectHost({ loadDocument, runQuery, runJslt, runValidation, operators? })`
+provides the stage, splitter and project engine integration.
+
+Pass that host to `mountStudioEditor(node, { project, host, ... })`. Optional
+services include template lookup, template cards, downloads, offline export,
+scheduling and a `projectData` runtime. The mount includes the shared embedded
+Flow widget; a supplied project Data runtime contributes its model/query widget.
+`createProjectDataRuntime({ createWorker })` owns one worker per committed model
+and seed identity. Switching files releases the view subscription, while model
+changes, deletion, replacement and disposal retire the owning worker.
+
+`mountFlowEditor(node, { kind, document, input?, tasks?, template?, templates? })`
+uses the same diagram, inspector, text round-trip policy, history and run runtime
+as the project-file widget. Task functions are explicit host services. Document
+machine effects are recorded by the sandbox, rather than acquiring host effects.
+Both mounts accept scheduling and error-reporting services.
+
+## Data transport, initialization and identity
+
+`mountDataEditor(node, { model, query, transport, ... })` accepts a factory that
+creates a fresh transport. `createTransport({ spawnWorker, openChannel,
+openClient?, budgets?, setTimer?, clearTimer? })` implements the operation port,
+five bounded boot stages, owner-to-client handoff, live stream and cleanup.
+Its default port client uses the exported Data contract. It chooses no worker
+URL or channel name. Failed boots release their resources; retries start fresh.
+Leaving a composed route releases its transport; returning resumes without
+re-seeding the text buffers. Lifecycle listeners are removed on disposal.
+
+The browser host imports its chosen SQLite initializer and calls
+`createBrowserDataWorker({ initialize, scope, createChannel, identity, operators? })`.
+The published code does not import that initializer. `initialize()` returns the
+SQLite module accepted by the existing `@jarenjs/db/wasm` adapters.
+The `identity` record explicitly names **all five** storage resources:
+`channel`, `pool`, `database`, `snapshots` and `lock`. Use the same identity only
+for tabs intentionally sharing a store. Independent applications and datasets
+must supply distinct identities. The host factory proves durable VFS candidates
+with a write/close/reopen probe and retains visible fallback/refusal reporting.
+Its disposal pauses an acquired pool without deleting stored files.
+
+`createProjectDataWorker({ initialize, scope, operators? })` serves the same
+contract over an isolated in-memory store. It acquires no shared database,
+channel or storage identity. The public handler constructor remains
+`createDataHandlers(DataHost)`, so Node, Bun and other driver hosts can serve the
+operation contract directly without a browser or a SQLite WASM initializer.
+
+The Jaren website keeps its existing `jaren-data-studio` channel,
+`jaren-data` pool, `/jaren-data-studio.db` database,
+`jaren-data-studio-snapshots` snapshots and `jaren-data-studio-owner` lock.
+Its private app owns `@sqlite.org/sqlite-wasm` and Vite asset handling. Another
+private app must explicitly provide and declare that bootstrap dependency;
+Studio's published dependency graph contains only Jaren packages.
+
+Optional `corpus`, `trip`, `migration` and `createRow` services carry host examples.
+The corresponding controls appear when configured. Their data and preview
+functions remain host-owned. A corpus report names the configured `executor`
+(default `sqlite`); a host using the browser adapter can name `sqlite-wasm`.
+
+## Composing and styling
+
+Existing app hosts can merge the exported actions, view rules and viewmodels
+and attach the corresponding controller to their app lifecycle. They use the
+same component implementations as the mount helpers. Their private app handles
+routing; external callers receive only the controller's document operations.
+
+Import the styles explicitly. Flow and Data selectors are scoped to each
+editor; project selectors retain the existing `jstudio`/`js-*` vocabulary.
+Controls inherit the host's color, font, spacing and motion tokens and provide
+standalone fallbacks. The host owns page gutters, theme tokens, worker assets
+and the available viewport height. The established 1024/760 breakpoints,
+44px phone controls and reduced-motion behavior travel with the editors.
+
+A mounted Data editor also exposes `setActive(boolean)`. Await
+`setActive(false)` when a host route leaves to release its worker, live query
+and ownership without losing incomplete model/query text. `setActive(true)`
+reopens the last accepted model, preserves the raw editing buffers and resolves
+when boot settles; `ready` always refers to that activation. Repeated activation
+is idempotent, inactive runs return a refusal, and `dispose()` is terminal.
+
+Data model, query and round-trip text buffers publish every input event. Live
+store updates cannot replace uncommitted typing; model recreation and query
+execution still require their explicit operations.
+
+Project snapshots expose both a semantic document `revision` for candidate publication and a numeric `stageRevision` for the mounted app. `run(name)` explicitly restarts an interactive app; `run(name, { restart: false })` uses normal commit behavior, preserving the stage for state-only edits and rebuilding it after structural changes.

package/docs/PROJECT-FORMAT.md

@@ -183,17 +183,7 @@ and `describe` report file problems as diagnostics.
 v0.1 is the headless **engine** — parse, per-file validate, assemble,
 classify — plus the IDE **component** that mounts it: the file rail, the
 debounced editor with its typing buffer, the run stage, the three layout
-modes with a drag splitter, the phone pane switcher, save/load/share, and
-an assistant that can list, read, write and run a project's files.
-
-The creation menu and assistant share the engine's ten-kind vocabulary and
-valid starter files. `@jarenjs/studio/author` uses one authoring profile per
-file, then the full file validation gate with bounded repair rounds. The
-website's `jaren_project_author` tool rejects stale publication if the project
-changed during generation, returning the candidate for recovery. Generic
-JSON/schema/contract files and imported destinations use broad JSON profiles;
-their acceptance still depends on the full local validation gate. The exact
-`jaren_project_write` tool remains available for supplied text.
+modes with a drag splitter, the phone pane switcher, save/load/share, and complete file validation and export. The creation menu shares the engine’s ten-kind vocabulary and valid starter files. External authoring integrations publish through the same revision-checked public editor controllers.
 
 The stage displays the nested app's latest boot/runtime failure and clears
 it on restart. Remaining constraints live in