@jarenjs/studio 0.34.0

package/README.md

@@ -0,0 +1,72 @@
+# @jarenjs/studio
+
+**The jaren project IDE — a jaren application as a multi-file project.**
+
+CodePen's model, for JSON-all-the-way-down: an application is a small tree
+of typed files (a view, the actions, the state, a schema, a data model,
+queries, a flow), each edited on its own, each validated against its own
+grammar, assembled into runnable artifacts, and — where the driver allows
+— run live. The same document the human edits is the document an AI
+authors; the studio is a controlled component whose value is that project.
+
+This package ships in two layers, the suite's convention:
+
+- **the engine** (`@jarenjs/studio`) — headless: parse a `jaren-project`
+  document, validate each file against its kind, assemble the runnable
+  artifacts, and classify a change as structural vs. state-only. Knows the
+  grammars, nothing of the DOM.
+- **the component** (`@jarenjs/studio/component`) — the IDE itself, a
+  `createStudioComponent()` factory (like `@jarenjs/calc`): the shell is a
+  **JSLT view** (file rail with add/delete, an editable file name, a
+  template gallery, editor, docked coded-error strip, run stage, layout
+  switcher) over a pure `projectViewModel`, plus the two hard-problem
+  policies (`hostPolicy` reboot-vs-hot-update, `reconcileBuffer`). The
+  chrome and its derivation render headlessly and are tested as such; the
+  host registers the DOM-touching islands — the live nested-app stage
+  (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, and files are
+  added, 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).
+
+```js
+import { parseProject, validateFile, assembleArtifacts, classifyChange, describe }
+  from '@jarenjs/studio';
+
+const project = parseProject({
+  project: '0.1',
+  files: [
+    { name: 'app.json',   kind: 'app',   text: '{ "view": [ … ], "state": { … } }' },
+    { name: 'npv.query',  kind: 'query', text: '{ "$npv": ["$.rate", "$.cf[*]"] }' },
+    { name: 'seed.data',  kind: 'data',  text: '{ "cf": [-1000, 300, 400] }' },
+  ],
+});
+
+describe(project);            // per-file kind / validity / role — the file rail
+validateFile(project.files[1]); // { valid, kind, total, errors: [{ code, message, docPath }] }
+assembleArtifacts(project);   // the runnable set
+```
+
+## Why per-file validation
+
+The published `jaren-query` / `jaren-jslt` grammars are *closed*, so a data
+query using a host-registered operator (`$npv`, `$sqrt`) can't be checked
+against them. The studio validates each file on **its own boundary** —
+`jslt`/`query` files are *compiled* with the operator packs mounted, so
+registered operators pass and a real mistake surfaces as its own coded
+error with a JSON Pointer. There is deliberately no single composed
+mega-schema; that is what lets a project mix an app, a store and a data
+query at once. See [PROJECT-FORMAT.md](docs/PROJECT-FORMAT.md).
+
+## Install
+
+```
+npm install @jarenjs/studio
+```
+
+Zero third-party runtime dependencies — only other `@jarenjs/*` packages.
+Node ≥ 24, ESM.

package/dist/types/assemble.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @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.
+ */
+/**
+ * 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 declare function assembleArtifacts(project: any): {
+    artifacts: Array<{
+        name: string;
+        kind: string;
+        role: string;
+        doc: any;
+        sourceFiles: string[];
+    }>;
+    errors: Array<{
+        file: string;
+        message: string;
+    }>;
+};
+/**
+ * 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 declare function classifyChange(prevProject: any, nextProject: any): {
+    overall: 'none' | 'state-only' | 'structural';
+    perArtifact: Record<string, 'none' | 'state-only' | 'structural'>;
+};
+/**
+ * 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 declare function describe(project: any, options?: {
+    operators?: {
+        toOptions: () => any;
+    };
+}): {
+    active: any;
+    layout: any;
+    files: any;
+};

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

@@ -0,0 +1,68 @@
+/**
+ * @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 declare function editorTextarea(options: {
+    value: any;
+    action: string;
+    inputAction?: string;
+    rows?: number;
+    readonly?: boolean;
+}): (string | {
+    class: string;
+    rows: number;
+    spellcheck: string;
+    autocapitalize: string;
+    autocorrect: string;
+    autocomplete: string;
+    value: any;
+    readonly?: string | undefined;
+    on: {
+        change: string;
+        input?: undefined;
+    } | {
+        input: string;
+        change: string;
+    };
+})[];
+/** One line of the docked error strip. */
+export declare function errorLine(content: any): any[];
+/**
+ * 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 declare const KIND_BADGE: Readonly<{
+    app: "view";
+    jslt: "view";
+    query: "query";
+    state: "json";
+    data: "json";
+    schema: "json";
+    model: "model";
+    fsm: "flow";
+    dag: "flow";
+}>;

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

@@ -0,0 +1,45 @@
+/**
+ * @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.
+ */
+/**
+ * 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 declare function hostPolicy(prevProject: any, nextProject: any): Record<string, 'reboot' | 'hot' | 'skip'>;
+/**
+ * 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 declare function reconcileBuffer(buffer: {
+    text: string;
+    dirty: boolean;
+}, incoming: string): {
+    text: string;
+    dirty: boolean;
+    conflict: {
+        incoming: string;
+    } | null;
+};

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

@@ -0,0 +1,262 @@
+/**
+ * @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 { 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 declare function createStudioComponent(options?: {
+    operators?: {
+        toOptions: () => any;
+    };
+}): {
+    mode: string;
+    rules: ({
+        match: string;
+        mode: string;
+        body: (string | (string | {
+            name: string;
+            class: string;
+            role: string;
+            'aria-orientation': string;
+            'aria-label': string;
+            'aria-valuemin': string;
+            'aria-valuemax': string;
+            'aria-valuenow': string;
+            tabindex: string;
+            props: {
+                ratio: string;
+                mode: string;
+            };
+        })[] | (string | any[] | {
+            class: string;
+            role: string;
+            'aria-label': string;
+        })[] | (string | {
+            $apply: string;
+        }[] | (string | (string | {
+            value: string;
+        })[] | {
+            class: string;
+            'aria-label': string;
+            value: string;
+            on: {
+                change: string;
+            };
+        })[] | {
+            class: string;
+            'aria-label': string;
+        })[] | (string | (string | {
+            class: string;
+        })[] | {
+            class: string;
+            $if?: undefined;
+        } | {
+            class?: undefined;
+            $if: ((string | (string | {
+                name: string;
+                props: string;
+            })[] | {
+                class: string;
+            })[] | {
+                $if?: undefined;
+                $eq: string[];
+            } | {
+                $if: ({
+                    $if?: undefined;
+                    $eq: string[];
+                } | {
+                    $eq?: undefined;
+                    $if: (string | (string | {
+                        $apply: string[];
+                    }[] | {
+                        class: string;
+                    })[])[];
+                } | {
+                    $eq?: undefined;
+                    $if: ((string | {
+                        class: string;
+                    })[] | {
+                        $eq: string[];
+                    })[];
+                })[];
+                $eq?: undefined;
+            })[];
+        })[] | (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;
+            spellcheck: string;
+            autocapitalize: string;
+            autocorrect: string;
+            autocomplete: string;
+            value: any;
+            readonly?: string | undefined;
+            on: {
+                change: string;
+                input?: undefined;
+            } | {
+                input: string;
+                change: string;
+            };
+        })[] | (string | (string | {
+            class: string;
+            value: string;
+            spellcheck: string;
+            autocapitalize: string;
+            autocomplete: string;
+            'aria-label': string;
+            on: {
+                input: string;
+                change: string;
+            };
+        })[] | (string | string[] | {
+            class: string;
+        })[] | {
+            class: string;
+        })[] | {
+            class: string;
+            $if?: undefined;
+        } | {
+            $if: (string | (string | {}[] | (string | {
+                type: string;
+                class: string;
+                title: string;
+                on: {
+                    click: string;
+                };
+            })[] | {
+                class: string;
+                role: string;
+            })[])[];
+            class?: undefined;
+        } | {
+            $if: (string | (string | {
+                $apply: string;
+            }[] | {
+                class: string;
+                role: string;
+            })[])[];
+            class?: undefined;
+        })[] | {
+            class: string;
+            'data-mode': string;
+            'data-pane': string;
+        })[];
+    } | {
+        match: string;
+        mode: string;
+        body: (string | (string | {
+            type: string;
+            class: string;
+            title: string;
+            'aria-label': string;
+            on: {
+                click: {
+                    action: string;
+                    with: string;
+                };
+            };
+        })[] | (string | (string | {
+            class: string;
+            'data-badge': string;
+        })[] | (string | {
+            class: string;
+        })[] | {
+            $if?: undefined;
+            type: string;
+            class: {
+                $if: string[];
+            };
+            title: string;
+            on: {
+                click: {
+                    action: string;
+                    with: string;
+                };
+            };
+        } | {
+            class?: undefined;
+            type?: undefined;
+            title?: undefined;
+            on?: undefined;
+            $if: (string | (string | {
+                class: string;
+                title: string;
+            })[])[];
+        })[] | {
+            class: string;
+        })[];
+    } | {
+        match: string;
+        mode: string;
+        body: (string | {}[] | {
+            class: string;
+            type: string;
+            on: {
+                click: {
+                    action: string;
+                    with: string;
+                };
+            };
+        })[];
+    })[];
+    modes: Readonly<{
+        project: {
+            unmatched: string;
+        };
+    }>;
+    /** The IDE view model for the `$.project` slice. */
+    viewModel: (state: any) => any;
+    hostPolicy: typeof hostPolicy;
+    reconcileBuffer: typeof reconcileBuffer;
+    describe: (project: any) => {
+        active: any;
+        layout: any;
+        files: any;
+    };
+    validateFile: (file: any) => {
+        valid: boolean;
+        kind: string;
+        total: number;
+        errors: Array<{
+            code: string | null;
+            message: string;
+            docPath?: string;
+        }>;
+    };
+    classifyChange: typeof classifyChange;
+    parseProject: typeof parseProject;
+};
+export { projectViewModel, projectRules, projectModes, PROJECT_MODE, PROJECT_BASE, hostPolicy, reconcileBuffer, editorTextarea, errorLine, KIND_BADGE, };