@jarenjs/studio 0.34.0

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

@@ -0,0 +1,232 @@
+/**
+ * @file The IDE shell as a JSLT view — the chrome is a document, rendered
+ * by the same engine as the rest of the suite (no imperative chrome, no
+ * syntax highlighting). Following the suite's rule convention: one mode
+ * (`project`), rules matched by their ABSOLUTE slice path, `$apply` and
+ * body references RELATIVE to the matched node. The host mounts the view
+ * model at `$.ui.project`.
+ *
+ * The stage's live nested app and the drag splitter are the only
+ * imperative islands — `jaren-widget`s the host registers. The layout
+ * mode rides a `data-mode` attribute so the grid switches in CSS with no
+ * computed class; the phone pane rides `data-pane` the same way, and a
+ * kind badge rides `data-badge`.
+ */
+/** The one mode this view uses. */
+export declare const PROJECT_MODE = "project";
+/** The slice the host mounts the view model at. */
+export declare const PROJECT_BASE = "$.ui.project";
+/** The modes the host merges into the site stylesheet. */
+export declare const projectModes: Readonly<{
+    project: {
+        unmatched: string;
+    };
+}>;
+/** The studio's JSLT rules — spread into the site stylesheet. */
+export declare const projectRules: ({
+    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;
+            };
+        };
+    })[];
+})[];

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

@@ -0,0 +1,22 @@
+/**
+ * @file `projectViewModel(state)` — the IDE's derivation boundary. Given
+ * the `state.project` slice it derives everything the JSLT shell renders:
+ * the file rail (from the engine's `describe`), the active file's editor
+ * value and its coded errors, the docked error strip across every file,
+ * and the stage — an assembled app document to mount, a run result to
+ * show, or an inert note for a kind that has no editor of its own yet.
+ * Pure: nothing here is stored back in state.
+ */
+/**
+ * Derive the IDE view model from `state.project`.
+ * @param {{ project: any }} state - the site state carrying the `project` slice
+ * @param {{ operators?: { toOptions: () => any } }} [options]
+ * @returns {any}
+ */
+export declare function projectViewModel(state: {
+    project: any;
+}, options?: {
+    operators?: {
+        toOptions: () => any;
+    };
+}): any;

package/dist/types/errors.d.ts

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

package/dist/types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file `@jarenjs/studio` — the ENGINE (part one of the two-layer
+ * package). Headless: it parses a `jaren-project` document, validates
+ * each file against its own kind grammar, assembles the runnable
+ * artifacts, and classifies a change as structural vs. state-only. It
+ * knows the suite's grammars (validate/json/app/flow/db) but nothing of
+ * the DOM, `@jarenjs/view` or `@jarenjs/app`'s runtime — the component
+ * layer (`./component`) imports the engine, never the reverse.
+ *
+ * The project is a THIN envelope over typed files; there is deliberately
+ * no single composed meta-schema, so a data file may use host-registered
+ * operators the closed grammars forbid — the per-file validators are the
+ * honest boundary.
+ */
+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';

package/dist/types/project.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @file The project document model: the closed file-kind vocabulary, the
+ * frozen IDE `layout` shape, and `parseProject` — validate a candidate
+ * against the `jaren-project` envelope schema, reject duplicate file
+ * names, and return a NORMALIZED, frozen project (layout defaulted,
+ * `active` resolved to a real file). Only the ENVELOPE is gated here; a
+ * file's `text` is a string until its kind validator runs (`validate.js`).
+ */
+/** The closed set of file kinds (matches the schema `kind` enum). */
+export declare const KINDS: readonly string[];
+/** The default IDE layout — the frozen `{ mode, ratio, autorun }` shape
+ * that rides the share link and the eject, so it must not drift. */
+export declare const LAYOUT_DEFAULT: Readonly<{
+    mode: "classic";
+    ratio: 0.5;
+    autorun: true;
+}>;
+/**
+ * Parse and normalize a project: JSON text or an object in; a frozen,
+ * normalized project out. A malformed envelope is `JS0001`; a duplicate
+ * file name is `JS0002`.
+ * @param {string | object} input
+ * @returns {any}
+ */
+export declare function parseProject(input: string | object): any;
+/**
+ * The file with this name, or `null`.
+ * @param {any} project
+ * @param {string} name
+ */
+export declare function fileOf(project: any, name: string): any;

package/dist/types/validate.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @file Per-file validation — the honest heart of the per-file design.
+ * `validateFile(file)` dispatches on the file's kind and validates its
+ * `text` against THAT kind's grammar (never one composed mega-schema):
+ *
+ *  - `app`    → the composed jaren-app meta-schema (which `$ref`s the
+ *               query + JSLT grammars) PLUS a headless render audit (a
+ *               document that validates but throws on its first frame is
+ *               still broken);
+ *  - `jslt` / `query` → COMPILED by the engine WITH the operator registry,
+ *               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);
+ *  - `schema` → compiled as a JSON Schema (is it well-formed?);
+ *  - `state` / `data` → any JSON (structural only).
+ *
+ * Every result is `{ valid, kind, total, errors: [{ code, message,
+ * docPath }] }` — the shape the IDE's docked error strip reads.
+ */
+/**
+ * Validate ONE file against its kind's grammar. Memoized on the file's
+ * identity; pass a fresh object to force a re-check.
+ * @param {{ name?: string, kind: string, text: string }} file
+ * @param {{ operators?: { toOptions: () => any } }} [options] - a host
+ *   operator registry for the `jslt`/`query` kinds (defaults to the
+ *   built-in math/finance/stats packs)
+ * @returns {{ valid: boolean, kind: string, total: number,
+ *   errors: Array<{ code: string | null, message: string, docPath?: string }> }}
+ */
+export declare function validateFile(file: {
+    name?: string;
+    kind: string;
+    text: string;
+}, options?: {
+    operators?: {
+        toOptions: () => any;
+    };
+}): {
+    valid: boolean;
+    kind: string;
+    total: number;
+    errors: Array<{
+        code: string | null;
+        message: string;
+        docPath?: string;
+    }>;
+};

package/docs/PROJECT-FORMAT.md

@@ -0,0 +1,112 @@
+# PROJECT-FORMAT.md — the `jaren-project` document (v0.1)
+
+A **project** is a jaren application seen as an IDE would see it: a small
+tree of typed files, each one concern — a view, the actions, the state,
+a schema, a data model, queries, a flow machine — the way HTML, CSS and
+JavaScript are separate files. The document is a **thin envelope**; each
+file's meaning lives in its own grammar, not in the envelope.
+
+```jsonc
+{
+  "project": "0.1",
+  "files": [
+    { "name": "app.json",      "kind": "app",   "text": "…a jaren-app document…" },
+    { "name": "series.query",  "kind": "query", "text": "{ \"$npv\": [\"$.rate\", \"$.cf[*]\"] }" },
+    { "name": "seed.data",     "kind": "data",  "text": "{ \"cf\": [-1000, 300, 400] }" }
+  ],
+  "active": "app.json",
+  "layout": { "mode": "classic", "ratio": 0.5, "autorun": true }
+}
+```
+
+The envelope is published as a JSON Schema (`schemas/jaren-project.schema.json`
++ a draft-07 twin) and validated by `parseProject`, which returns a
+frozen, normalized project (the layout defaulted, `active` resolved to a
+real file).
+
+## The file kinds
+
+Each file declares a `kind`; its `text` is a JSON document validated
+against **that kind's grammar at its own boundary** — never composed into
+one meta-schema. `validateFile(file)` returns `{ valid, kind, total,
+errors: [{ code, message, docPath }] }` — the shape an editor's error
+strip reads.
+
+| kind | the file is | validated by |
+|---|---|---|
+| `app` | a `jaren-app` document | the composed app meta-schema (jslt + query by `$ref`) **plus a headless render audit** — a document that validates but throws on its first frame is still broken |
+| `jslt` | a JSLT stylesheet | **compiled** by the engine with the operator registry |
+| `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 |
+
+**Why per-file, not one composed schema.** The published `jaren-query` /
+`jaren-jslt` grammars are *closed* — their operator vocabulary is
+enumerated. A data query that uses a host-registered operator (`$npv`,
+`$sqrt`) validates only when the studio's operator packs are mounted, so
+`jslt`/`query` files are **compiled with the registry** rather than checked
+against the closed grammar: registered operators pass, and a real mistake
+comes back as its own coded code with a JSON Pointer (`JQ0002 — at /x:
+unknown operator '$flter'`). Composing every file into one gate would make
+that impossible; keeping each file on its own boundary is the honest
+design, not a compromise. A host embeds its own vocabulary with
+`validateFile(file, { operators })`.
+
+## 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).
+
+## `layout` is frozen
+
+`layout` is `{ mode: "classic" | "right" | "top", ratio: number,
+autorun: boolean }`, defaulted to `{ classic, 0.5, true }`. It rides the
+share link and the eject, so its shape is fixed at v0.1.
+
+## `classifyChange` — reboot vs. hot-update
+
+`classifyChange(prev, next)` reports, **per artifact**, whether a change
+is `structural`, `state-only`, or `none`. It compares a structural key —
+an `app` document *minus its `state`* — via the suite's own `contentKey`.
+An IDE reads it to decide: a `state-only` edit hot-dispatches into a
+running app (the user keeps scroll and inputs); a `structural` edit
+reboots. Keeping this datum in the tested engine, and the policy in the
+widget, is deliberate.
+
+## Errors
+
+Only the envelope raises a coded `StudioError`; a single file's grammar
+problem is reported by `validateFile`, never thrown.
+
+| code | meaning |
+|---|---|
+| `JS0001` | the project document is invalid (bad JSON, or fails the envelope schema) |
+| `JS0002` | a file name is duplicated in the project |
+
+## Status
+
+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.
+
+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; there is no whole-project export (`.zip` eject);
+`layout.autorun` is declared and never read; and the stage collects a
+nested app's failures without showing them. Syntax highlighting stays a
+non-goal — the editor is a plain `<textarea>` so the whole IDE remains a
+JSLT document with no imperative chrome.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@jarenjs/studio",
+  "private": false,
+  "version": "0.34.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./component": {
+      "types": "./dist/types/component/index.d.ts",
+      "default": "./src/component/index.js"
+    },
+    "./schemas/*": "./schemas/*",
+    "./styles/studio.css": "./styles/studio.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/types/",
+    "src/",
+    "docs/",
+    "schemas/",
+    "styles/"
+  ],
+  "description": "The jaren project IDE: a multi-file project (schema, view, actions, model, queries, flow) is one document; each file is validated against its own grammar, assembled into runnable artifacts, and edited/hosted by the studio widget. The engine is headless; the component layer is the IDE.",
+  "author": "joham",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/jarenjs.git",
+    "directory": "components/studio"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "jaren",
+    "json",
+    "ide",
+    "studio",
+    "project",
+    "editor",
+    "codepen",
+    "playground",
+    "document",
+    "headless"
+  ],
+  "scripts": {
+    "build": "npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
+    "prepack": "npm run build:types"
+  },
+  "dependencies": {
+    "@jarenjs/core": "^0.34.0",
+    "@jarenjs/validate": "^0.34.0",
+    "@jarenjs/json": "^0.34.0",
+    "@jarenjs/app": "^0.34.0",
+    "@jarenjs/flow": "^0.34.0",
+    "@jarenjs/db": "^0.34.0"
+  }
+}

package/schemas/jaren-project.draft-07.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://jarenjs.dev/schemas/jaren-project/0.1/draft-07",
+  "title": "jaren-project (draft-07)",
+  "description": "The draft-07 twin of jaren-project, for tools pinned to draft-07. Mechanically equivalent to the 2020-12 canonical artifact.",
+  "type": "object",
+  "required": ["project", "files"],
+  "additionalProperties": false,
+  "properties": {
+    "project": { "enum": ["0.1"] },
+    "files": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/file" }
+    },
+    "active": { "type": "string" },
+    "layout": { "$ref": "#/definitions/layout" }
+  },
+  "definitions": {
+    "file": {
+      "type": "object",
+      "required": ["name", "kind", "text"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "kind": {
+          "enum": ["app", "jslt", "query", "state", "data", "schema", "fsm", "dag", "model"]
+        },
+        "text": { "type": "string" }
+      }
+    },
+    "layout": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "enum": ["classic", "right", "top"] },
+        "ratio": { "type": "number", "minimum": 0, "maximum": 1 },
+        "autorun": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schemas/jaren-project.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-project/0.1",
+  "title": "jaren-project",
+  "description": "A jaren studio project: a thin envelope over a list of typed files. The envelope is schema-gated; each file's `text` is validated against ITS OWN kind grammar at its boundary, never composed into one mega-schema — so a data file may use host-registered operators the closed grammars forbid.",
+  "type": "object",
+  "required": ["project", "files"],
+  "additionalProperties": false,
+  "properties": {
+    "project": { "const": "0.1" },
+    "files": {
+      "type": "array",
+      "description": "The project's files, each a named unit of one concern.",
+      "items": { "$ref": "#/$defs/file" }
+    },
+    "active": {
+      "type": "string",
+      "description": "The name of the file the editor shows (falls back to the first file)."
+    },
+    "layout": { "$ref": "#/$defs/layout" }
+  },
+  "$defs": {
+    "file": {
+      "type": "object",
+      "required": ["name", "kind", "text"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "kind": {
+          "description": "The file's grammar/role; its `text` is validated against this kind, not the envelope.",
+          "enum": ["app", "jslt", "query", "state", "data", "schema", "fsm", "dag", "model"]
+        },
+        "text": { "type": "string" }
+      }
+    },
+    "layout": {
+      "type": "object",
+      "description": "The IDE arrangement — frozen so it survives a share link and the eject.",
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "enum": ["classic", "right", "top"] },
+        "ratio": { "type": "number", "minimum": 0, "maximum": 1 },
+        "autorun": { "type": "boolean" }
+      }
+    }
+  }
+}