@jarenjs/studio 0.75.0 → 0.83.2

package/README.md

@@ -26,14 +26,19 @@ This package ships in two layers, the suite's convention:
   (hot-update via `app.setState`) and the drag splitter — which are
   browser-verified. Mounted live at the website's `#/project`, where `app`
   files boot, `jslt`/`query` files run against a data file, `contract`
-  files render their `describe()`/OpenAPI projections, and files are
-  added, renamed, deleted and opened from templates.
+  files render their `describe()`/OpenAPI projections, `fsm`/`dag` files
+  mount the Flow editor, and collection models run in private SQLite workers
+  with query plans and live results. All ten file kinds can be created,
+  renamed, deleted and opened from templates.
 
 ## The project document
 
 A thin envelope over typed files — the full contract is
 [PROJECT-FORMAT.md](docs/PROJECT-FORMAT.md).
 
+`KINDS` lists all ten file kinds; `ADDABLE_KINDS` and `fileSkeleton` supply
+the creation menu and starter text from one shared table.
+
 ```js
 import { parseProject, validateFile, assembleArtifacts, classifyChange, describe }
   from '@jarenjs/studio';
@@ -52,6 +57,24 @@ validateFile(project.files[1]); // { valid, kind, total, errors: [{ code, messag
 assembleArtifacts(project);   // the runnable set
 ```
 
+Files can import named members from other files: an app's `view`, `actions`
+and `state` can each live in their own editor. The assembler checks references,
+tracks dependencies and writes diagram edits back into their source files.
+Explicit `input`, `model` and `collection` metadata route queries and model
+seeds; the [format](docs/PROJECT-FORMAT.md) specifies ownership and lifetimes.
+
+`@jarenjs/studio/author` exposes `createStudioFileAuthor({ client })`: generate
+one file under its authoring profile, validate with the full engine, and repair
+bounded failures before returning a candidate. The website assistant uses this
+path and protects edits made while generation is running. No provider quality
+claim is inferred from the mocked generation tests.
+
+`@jarenjs/studio/export` exposes `exportProject(project, assets)` and
+`createProjectZip(files)`. The website's **Offline ZIP** includes a standalone
+runner and the installed runtime dependencies, including SQLite and fonts.
+It runs from a local HTTP server without an install or external network.
+Runtime rows remain transient; explicit seed files travel with the project.
+
 ## Why per-file validation
 
 The published `jaren-query` / `jaren-jslt` grammars are *closed*, so a data
@@ -77,6 +100,8 @@ Every subpath a consumer can import, derived from the manifest by
 | `@jarenjs/studio/schemas/jaren-project.schema.json` | schema | — |
 | `@jarenjs/studio/styles/studio.css` | asset | — |
 | `@jarenjs/studio/package.json` | metadata | — |
+| `@jarenjs/studio/author` | JavaScript | declared |
+| `@jarenjs/studio/export` | JavaScript | declared |
 <!--/fact-->
 
 ## Install

package/dist/types/assemble.d.ts

@@ -3,24 +3,21 @@
  * 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.
+ * A runnable file can import named members from other project files;
+ * `sourceFiles` records the complete dependency chain. `state`/`data`
+ * files are inputs, not standalone artifacts.
  *
  * `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's `view`, `actions` and `subs`) via the suite's own
+ * STRUCTURAL key (all app members except `state`) via the suite's own
  * `semanticKey` — the collision-free identity, not the memo-grade
  * `contentKey` fingerprint: a classification decides whether a running
  * app reboots, so a fingerprint collision would read a changed document
  * as unchanged. The artifacts are parsed JSON, so the identity is total.
  */
 /**
- * Compose the project's files into runnable artifacts (whole-document).
+ * Compose the project's files into runnable artifacts, resolving imports.
  * @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 }> }}

package/dist/types/author.d.ts

@@ -0,0 +1,27 @@
+export declare const AUTHORABLE_KINDS: readonly string[];
+/** @param {{ client: any, operators?: any, maxRepairs?: number }} options */
+export declare function createStudioFileAuthor(options: {
+    client: any;
+    operators?: any;
+    maxRepairs?: number;
+}): {
+    /** @param {{ project: any, name: string, kind?: string, prompt: string }} request
+     * @param {{ signal?: AbortSignal }} [hooks] */
+    author(request: {
+        project: any;
+        name: string;
+        kind?: string;
+        prompt: string;
+    }, hooks?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        errors: any[];
+        raw: string;
+        attempts: number;
+    } | {
+        value: any;
+        raw: string;
+        attempts: number;
+        file: any;
+    }>;
+};

package/dist/types/component/index.d.ts

@@ -83,7 +83,9 @@ export declare function createStudioComponent(options?: {
         } | {
             class?: undefined;
             $if: ((string | (string | {
-                name: string;
+                name: {
+                    $default: string[];
+                };
                 props: string;
             })[] | {
                 class: string;
@@ -111,6 +113,33 @@ export declare function createStudioComponent(options?: {
                 })[];
                 $eq?: undefined;
             })[];
+        })[] | (string | (string | {
+            class: string;
+            type: string;
+            'aria-pressed': {
+                $if: string[];
+            };
+            on: {
+                click: string;
+            };
+        })[] | (string | {
+            class: string;
+            type: string;
+            on: {
+                click: string;
+            };
+        })[] | (string | any[] | {
+            class: string;
+            role: string;
+            'aria-label': string;
+        })[] | (string | {
+            $apply: string;
+        }[] | (string | {
+            class: string;
+        })[] | {
+            class: string;
+        })[] | {
+            class: string;
         })[] | (string | (string | {
             class: string;
             rows: number;
@@ -158,6 +187,21 @@ export declare function createStudioComponent(options?: {
                 role: string;
             })[])[];
             class?: undefined;
+        } | {
+            $if: (string | (string | {
+                class: string;
+                $if?: undefined;
+            } | {
+                $if: (string | {}[])[];
+                class?: undefined;
+            } | {
+                $if: (string | {}[])[];
+                class?: undefined;
+            } | {
+                $if: (string | {}[])[];
+                class?: undefined;
+            })[])[];
+            class?: undefined;
         } | {
             $if: (string | (string | {
                 $apply: string;
@@ -166,33 +210,6 @@ export declare function createStudioComponent(options?: {
                 role: string;
             })[])[];
             class?: undefined;
-        })[] | (string | (string | {
-            class: string;
-            type: string;
-            'aria-pressed': {
-                $if: string[];
-            };
-            on: {
-                click: string;
-            };
-        })[] | (string | {
-            class: string;
-            type: string;
-            on: {
-                click: string;
-            };
-        })[] | (string | any[] | {
-            class: string;
-            role: string;
-            'aria-label': string;
-        })[] | (string | {
-            $apply: string;
-        }[] | (string | {
-            class: string;
-        })[] | {
-            class: string;
-        })[] | {
-            class: string;
         })[] | {
             class: string;
             'data-mode': string;
@@ -231,8 +248,8 @@ export declare function createStudioComponent(options?: {
                 };
             };
         } | {
-            class?: undefined;
             type?: undefined;
+            class?: undefined;
             title?: undefined;
             on?: undefined;
             $if: (string | (string | {

package/dist/types/component/view.d.ts

@@ -81,7 +81,9 @@ export declare const projectRules: ({
     } | {
         class?: undefined;
         $if: ((string | (string | {
-            name: string;
+            name: {
+                $default: string[];
+            };
             props: string;
         })[] | {
             class: string;
@@ -109,6 +111,33 @@ export declare const projectRules: ({
             })[];
             $eq?: undefined;
         })[];
+    })[] | (string | (string | {
+        class: string;
+        type: string;
+        'aria-pressed': {
+            $if: string[];
+        };
+        on: {
+            click: string;
+        };
+    })[] | (string | {
+        class: string;
+        type: string;
+        on: {
+            click: string;
+        };
+    })[] | (string | any[] | {
+        class: string;
+        role: string;
+        'aria-label': string;
+    })[] | (string | {
+        $apply: string;
+    }[] | (string | {
+        class: string;
+    })[] | {
+        class: string;
+    })[] | {
+        class: string;
     })[] | (string | (string | {
         class: string;
         rows: number;
@@ -156,6 +185,21 @@ export declare const projectRules: ({
             role: string;
         })[])[];
         class?: undefined;
+    } | {
+        $if: (string | (string | {
+            class: string;
+            $if?: undefined;
+        } | {
+            $if: (string | {}[])[];
+            class?: undefined;
+        } | {
+            $if: (string | {}[])[];
+            class?: undefined;
+        } | {
+            $if: (string | {}[])[];
+            class?: undefined;
+        })[])[];
+        class?: undefined;
     } | {
         $if: (string | (string | {
             $apply: string;
@@ -164,33 +208,6 @@ export declare const projectRules: ({
             role: string;
         })[])[];
         class?: undefined;
-    })[] | (string | (string | {
-        class: string;
-        type: string;
-        'aria-pressed': {
-            $if: string[];
-        };
-        on: {
-            click: string;
-        };
-    })[] | (string | {
-        class: string;
-        type: string;
-        on: {
-            click: string;
-        };
-    })[] | (string | any[] | {
-        class: string;
-        role: string;
-        'aria-label': string;
-    })[] | (string | {
-        $apply: string;
-    }[] | (string | {
-        class: string;
-    })[] | {
-        class: string;
-    })[] | {
-        class: string;
     })[] | {
         class: string;
         'data-mode': string;

package/dist/types/errors.d.ts

@@ -14,6 +14,7 @@ import { CodedError } from '@jarenjs/core/errors';
 export declare const STUDIO_CODES: Readonly<{
     JS0001: "the project document is invalid";
     JS0002: "a file name is duplicated in the project";
+    JS0003: "a project file reference cannot be resolved";
 }>;
 /** A studio-envelope error. */
 export declare class StudioError extends CodedError {

package/dist/types/export.d.ts

@@ -0,0 +1,5 @@
+/** ZIP method 0 (stored), UTF-8 names, fixed DOS epoch, no ZIP64.
+ * @param {Record<string, string | Uint8Array>} files @returns {Uint8Array} */
+export declare function createProjectZip(files: Record<string, string | Uint8Array>): Uint8Array;
+/** @param {any} project @param {Record<string, string | Uint8Array>} assets */
+export declare function exportProject(project: any, assets: Record<string, string | Uint8Array>): Uint8Array<ArrayBufferLike>;

package/dist/types/index.d.ts

@@ -16,3 +16,5 @@ export { KINDS, LAYOUT_DEFAULT, parseProject, fileOf } from './project.js';
 export { validateFile } from './validate.js';
 export { assembleArtifacts, classifyChange, describe } from './assemble.js';
 export { STUDIO_CODES, StudioError } from './errors.js';
+export { resolveProjectFile, projectFileContext, renameProjectFile, writeProjectArtifact } from './resolve.js';
+export { ADDABLE_KINDS, fileSkeleton } from './skeletons.js';

package/dist/types/resolve.d.ts

@@ -0,0 +1,27 @@
+/** Resolve one file and its transitive sources. Imported members must be
+ * absent locally; a typo, cycle or collision is a refusal, never a fallback.
+ * @param {any} project @param {string} name
+ * @returns {{ doc: any, sourceFiles: string[] }} */
+export declare function resolveProjectFile(project: any, name: string): {
+    doc: any;
+    sourceFiles: string[];
+};
+/** Resolve a query/transform/validation input or a worker store route.
+ * Explicit references never fall back when broken. Multiple models require
+ * a choice; adding an unrelated model cannot silently reroute a query.
+ * @param {any} project @param {any} file
+ * @returns {{ input: any, model: any, collection: string | null }} */
+export declare function projectFileContext(project: any, file: any): {
+    input: any;
+    model: any;
+    collection: string | null;
+};
+/** Rename references together with their target, preserving every other
+ * file member. A delete deliberately leaves references visibly broken.
+ * @param {any[]} files @param {string} before @param {string} after */
+export declare function renameProjectFile(files: any[], before: string, after: string): any[];
+/** Write an assembled artifact back into its source files. Imported
+ * members stay in their own files; conflicting writes to a shared source
+ * are refused atomically. Unchanged files keep their identity and text.
+ * @param {any} project @param {string} name @param {any} doc */
+export declare function writeProjectArtifact(project: any, name: string, doc: any): any;

package/dist/types/skeletons.d.ts

@@ -0,0 +1,6 @@
+/** Creation kinds derive from the valid starter table and are shared by
+ * the component menu, website host and assistant. */
+export declare const ADDABLE_KINDS: readonly string[];
+/** The starter text for a freshly added file of `kind`, or null if the
+ * kind is not addable. */
+export declare function fileSkeleton(kind: any): any;

package/dist/types/validate.d.ts

@@ -11,7 +11,7 @@
  *               so host-registered operators ($npv, $sqrt) validate and a
  *               real error comes back as its own coded `JQ`/`JT` code with
  *               a docPath — the closed grammar would reject the operators;
- *  - `fsm` / `dag` / `model` → their published grammar (structural);
+ *  - `fsm` / `dag` / `model` → their grammar plus compiler/planner checks;
  *  - `contract` → COMPILED by `compileContract`, so a refusal comes back
  *               as its stable `JC00xx` code with the docPath of the
  *               member at fault — richer than the grammar alone;

package/docs/PROJECT-FORMAT.md

@@ -39,8 +39,9 @@ strip reads.
 | `query` | a query document | **compiled** by the engine with the operator registry |
 | `state` / `data` | any JSON value (an input) | structural JSON only |
 | `schema` | a JSON Schema | must be an object/boolean and compile |
-| `fsm` / `dag` | a `jaren-fsm` / `jaren-dag` machine | its published flow grammar |
-| `model` | a `jaren-model` store definition | the `jaren-model` grammar |
+| `fsm` / `dag` | a `jaren-fsm` / `jaren-dag` machine | its grammar and compiler; named tasks are checked without execution |
+| `model` | a `jaren-model` store definition | its grammar, normalization and SQLite collection/entity planning |
+| `contract` | a `jaren-contract` document | `compileContract`, with coded diagnostics |
 
 **Why per-file, not one composed schema.** The published `jaren-query` /
 `jaren-jslt` grammars are *closed* — their operator vocabulary is
@@ -56,15 +57,74 @@ design, not a compromise. A host embeds its own vocabulary with
 
 ## Assembly — files → runnable artifacts
 
-`assembleArtifacts(project)` composes the files into the runnable set. v0.1
-ships the **whole-document** contract: a runnable file (`app`, `fsm`,
-`dag`, `model`, `jslt`, `query`, `schema`) is its own artifact
-(`{ name, kind, role, doc, sourceFiles }`); `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 (a future `sourceFiles` will list more
-than one name).
+`assembleArtifacts(project)` returns `{ artifacts, errors }`. Each runnable
+file (`app`, `fsm`, `dag`, `model`, `jslt`, `query`, `schema`, `contract`)
+produces `{ name, kind, role, doc, sourceFiles }`; `state`/`data` are inputs.
+Assembly resolves JSON and references; `describe(project)` additionally
+validates assembled documents and reports each file's errors.
+
+A file can supply absent top-level members through `imports`, an object
+mapping member names to exact project filenames. For example:
+
+```json
+{
+  "name": "app.json", "kind": "app", "text": "{}",
+  "imports": { "view": "app.view", "actions": "app.actions", "state": "app.state" }
+}
+```
+
+Each source's entire JSON value becomes the destination member. Sources may
+themselves import members. The allowed destination members are:
+
+| Destination kind | Importable members |
+|---|---|
+| `app` | `view`, `actions`, `state`, `subs` |
+| `fsm` | `states`, `transitions`, `initial` |
+| `dag` | `nodes`, `edges`, `output` |
+| `model` | `collections`, `entities` |
+
+`resolveProjectFile(project, name)` returns `{ doc, sourceFiles }`, with
+dependencies in traversal order, deduplicated. Missing sources, cycles,
+unsupported members and a member supplied both locally and by import raise
+`JS0003`. Source files are never mutated. `renameProjectFile` updates all
+references atomically. `writeProjectArtifact` writes edits back into their
+source files, preserving untouched text and refusing conflicting writes to a
+shared source. Deletion leaves dependent files with explicit reference errors.
+
+The website keeps an app visible while editing a fragment directly imported
+by exactly one app. Imported state changes hot-update that app; structural
+changes reboot it. Ambiguous owners require selecting the intended app.
+
+## Input and model routing
+
+Optional file members `input`, `model` and `collection` select execution inputs.
+`input` names a `data` or `state` file; absent it, pure runners use the first
+`data` file, then the first `state` file, then JSON null. `model` explicitly
+names a model file for a query. It never implicitly selects the first store.
+`collection` chooses a collection; a model with exactly one collection can
+omit it. `projectFileContext` resolves these references and refuses wrong
+kinds or missing names. The IDE exposes selectors beside the editor.
+
+The website runs collection models in private in-memory SQLite workers, one
+owner per model filename. Queries referencing that model share its rows;
+other models and the separate data page do not. Switching files stops the
+view's live subscription but retains the worker. Committing a changed model
+or seed recreates its store; deleting a model, replacing a project or
+destroying the app releases its worker. Invalid drafts retain the committed
+stage. Runtime rows are transient and are not saved or shared.
+
+A model's **explicit** `input` is a seed object mapping collection names to
+arrays of documents, inserted before the first query. No implicit data file
+seeds a store. The stage supports inserts, deletes, query results, SQL plans
+and live query results. Entity-only models validate and can be authored, but
+the website's execution controls currently require a collection.
+
+FSM and DAG files mount the Flow diagram editor, including palette,
+inspector, undo/redo and run controls. Diagram edits write back through
+assembly. FSM effects are recorded, not dispatched to host services; only
+the editor's registered local DAG tasks execute. Teardown cancels pending
+runs and ignores late completions. The standalone `#/flow` route remains
+available using the same editor.
 
 ## `layout` is frozen
 
@@ -80,14 +140,25 @@ vertically in `top`; pointer cancellation restores the previous ratio.
 **Download** exports the complete `jaren-project` envelope, including every
 file and the active file/layout, and works for projects without an app.
 **App JSON** separately exports the designated app document and reports
-when none exists. A runnable offline folder/ZIP is a future export format.
+when none exists, resolving any imported members first. **Offline ZIP**
+exports a standalone runner, `project.json`, every original file's text, and
+bundled runtime, fonts and SQLite assets. Unzip and serve the directory over
+localhost (the included README gives a Python command); no package install
+or internet connection is required. Runtime versions come from the exporting
+build and are recorded in `runtime/versions.json`. Authored external asset
+URLs remain external. Live rows and host credentials are excluded.
+
+The headless `@jarenjs/studio/export` entry accepts the host's runtime asset
+bytes and produces a deterministic ZIP. It refuses unsafe archive paths;
+source filenames are represented in `project.json` and mapped to numbered
+files, so arbitrary project names cannot escape the archive directory.
 
 ## `classifyChange` — reboot vs. hot-update
 
 `classifyChange(prev, next)` reports, **per artifact**, whether a change
 is `structural`, `state-only`, or `none`. A change of artifact kind is
 structural even when the JSON text stays the same. It compares an app's
-`view`, `actions` and `subs` (other artifacts' whole documents) via the
+entire document except `state` (other artifacts' whole documents) via the
 suite's collision-free `semanticKey`; a remaining document change is
 `state-only`. Every filename, including `__proto__`, is an own member of
 the result map.
@@ -98,13 +169,14 @@ widget, is deliberate.
 
 ## Errors
 
-Only the envelope raises a coded `StudioError`; a single file's grammar
-problem is reported by `validateFile`, never thrown.
+Envelope and reference operations raise coded `StudioError`s. `validateFile`
+and `describe` report file problems as diagnostics.
 
 | code | meaning |
 |---|---|
 | `JS0001` | the project document is invalid (bad JSON, or fails the envelope schema) |
 | `JS0002` | a file name is duplicated in the project |
+| `JS0003` | an import or execution reference cannot be resolved, or an artifact write conflicts |
 
 ## Status
 
@@ -114,13 +186,16 @@ 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.
 
-Still open, and tracked with their constraints in
-[ROADMAP.md](../../../docs/ROADMAP.md): the `fsm`/`dag`/`model` kinds
-validate but have no editor or runner, so they cannot be added from the
-IDE; fragment assembly (one artifact from several files) is unbuilt;
-the assistant authors files as free-form tool arguments rather than under
-constrained decoding; and a runnable offline `.zip` eject is unbuilt.
+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.
+
 The stage displays the nested app's latest boot/runtime failure and clears
-it on restart. Syntax highlighting stays a
-non-goal — the editor is a plain `<textarea>` so the whole IDE remains a
-JSLT document with no imperative chrome.
+it on restart. Remaining constraints live in
+[ROADMAP.md](../../../docs/ROADMAP.md). The editor remains a plain
+`<textarea>` with no syntax highlighting or imperative editor chrome.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/studio",
   "private": false,
-  "version": "0.75.0",
+  "version": "0.83.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -17,7 +17,15 @@
     },
     "./schemas/*": "./schemas/*",
     "./styles/studio.css": "./styles/studio.css",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./author": {
+      "types": "./dist/types/author.d.ts",
+      "default": "./src/author.js"
+    },
+    "./export": {
+      "types": "./dist/types/export.d.ts",
+      "default": "./src/export.js"
+    }
   },
   "files": [
     "dist/types/",
@@ -59,12 +67,13 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.75.0",
-    "@jarenjs/validate": "^0.75.0",
-    "@jarenjs/json": "^0.75.0",
-    "@jarenjs/app": "^0.75.0",
-    "@jarenjs/flow": "^0.75.0",
-    "@jarenjs/db": "^0.75.0",
-    "@jarenjs/contract": "^0.75.0"
+    "@jarenjs/core": "^0.83.2",
+    "@jarenjs/validate": "^0.83.2",
+    "@jarenjs/json": "^0.83.2",
+    "@jarenjs/app": "^0.83.2",
+    "@jarenjs/flow": "^0.83.2",
+    "@jarenjs/db": "^0.83.2",
+    "@jarenjs/contract": "^0.83.2",
+    "@jarenjs/ai": "^0.83.2"
   }
 }