@jarenjs/studio 0.83.3 → 0.85.0

package/README.md

@@ -31,6 +31,19 @@ This package ships in two layers, the suite's convention:
   with query plans and live results. All ten file kinds can be created,
   renamed, deleted and opened from templates.
 
+## Complete reusable editors
+
+`mountStudioEditor`, `mountFlowEditor` and `mountDataEditor` provide the same
+project, Flow and Data interfaces used by the website. Each exposes document
+reads, validation, revision-checked replacement/patching, execution, change
+subscriptions and disposal. Hosts supply rendering, templates, task execution
+and storage through explicit services.
+
+Use `/component`, `/flow`, `/data` and `/data/host`, with their exported styles
+and operation contract. The [host guide](docs/EDITORS.md) describes the complete
+API, worker initialization, storage identity and lifecycle. A packed independent
+host exercises all three editors without importing website source.
+
 ## The project document
 
 A thin envelope over typed files — the full contract is
@@ -63,11 +76,7 @@ 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.
+Hosts can propose validated candidates through the shared editor controllers. Model-assisted authoring is provided by [Tangle’s Jaren integration](https://github.com/jklarenbeek/tangleai/blob/main/packages/jaren/README.md).
 
 `@jarenjs/studio/export` exposes `exportProject(project, assets)` and
 `createProjectZip(files)`. The website's **Offline ZIP** includes a standalone
@@ -100,8 +109,14 @@ 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 |
+| `@jarenjs/studio/flow` | JavaScript | declared |
+| `@jarenjs/studio/styles/flow.css` | asset | — |
+| `@jarenjs/studio/styles/editor.css` | asset | — |
+| `@jarenjs/studio/data` | JavaScript | declared |
+| `@jarenjs/studio/data/host` | JavaScript | declared |
+| `@jarenjs/studio/contracts/data.contract.json` | asset | — |
+| `@jarenjs/studio/styles/data.css` | asset | — |
 <!--/fact-->
 
 ## Install

package/contracts/data.contract.json

@@ -0,0 +1,243 @@
+{
+  "$contract": "0.1",
+  "id": "jaren-data-studio",
+  "version": "1",
+  "$defs": {
+    "DbError": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "description": "The store or host code as a string (including numeric DOMException codes), null for an uncoded fault.",
+          "type": ["string", "null"]
+        },
+        "message": { "type": "string" }
+      }
+    },
+    "Collection": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "operations": {
+    "data.init": {
+      "kind": "command",
+      "output": {
+        "type": "object",
+        "required": ["topology", "vfs", "version"],
+        "properties": {
+          "topology": { "enum": ["owner", "client", "memory"] },
+          "vfs": { "type": "string" },
+          "version": { "type": "string" },
+          "refusal": { "$ref": "#/$defs/DbError" },
+          "durable": { "type": "boolean" },
+          "failures": { "type": "array", "items": { "type": "object", "required": ["vfs", "reason"], "properties": { "vfs": { "type": "string" }, "reason": { "type": "string" } } } }
+        }
+      },
+      "errors": { "db": { "schema": { "$ref": "#/$defs/DbError" } } },
+      "doc": "Load the SQLite wasm build and decide the topology: owner (holds the selected durable storage), client (another context owns it — talk over the channel), or visibly non-durable memory. Probe order: isolated SharedArrayBuffer OPFS, SAH-pool OPFS, atomic IndexedDB snapshots, memory. failures names each rejected rung; refusal carries the visible downgrade."
+    },
+    "data.open": {
+      "kind": "command",
+      "input": {
+        "type": "object",
+        "required": ["model"],
+        "properties": {
+          "model": { "type": "object" },
+          "reset": { "type": "boolean" }
+        }
+      },
+      "output": {
+        "type": "object",
+        "required": ["vfs", "capabilities"],
+        "properties": {
+          "vfs": { "type": "string" },
+          "capabilities": { "type": "object" },
+          "model": { "type": "object" },
+          "collection": { "$ref": "#/$defs/Collection" },
+          "keyPointer": { "type": "string" }
+        }
+      },
+      "errors": { "db": { "schema": { "$ref": "#/$defs/DbError" } } },
+      "doc": "Open (or recreate, with reset) the store from a jaren-model document. Return its active model, collection, key pointer and capabilities. On the client channel, a non-reset open only attaches to the existing store and ignores the supplied model; reset is refused with the db failure."
+    },
+    "data.insert": {
+      "kind": "command",
+      "input": {
+        "type": "object",
+        "required": ["collection", "doc"],
+        "properties": {
+          "collection": { "$ref": "#/$defs/Collection" },
+          "doc": { "type": "object" }
+        }
+      },
+      "output": true,
+      "errors": { "db": { "schema": { "$ref": "#/$defs/DbError" } } },
+      "doc": "Insert one document. The output is the store's own insert result — the driver decides its shape, so it is deliberately open."
+    },
+    "data.delete": {
+      "kind": "command",
+      "input": {
+        "type": "object",
+        "required": ["collection", "key"],
+        "properties": {
+          "collection": { "$ref": "#/$defs/Collection" },
+          "key": true
+        }
+      },
+      "output": true,
+      "errors": { "db": { "schema": { "$ref": "#/$defs/DbError" } } },
+      "doc": "Delete by key. Keys may be strings, numbers or the model's own key shape, so the member is deliberately open, like the output."
+    },
+    "data.rows": {
+      "kind": "read",
+      "input": {
+        "type": "object",
+        "required": ["collection"],
+        "properties": {
+          "collection": { "$ref": "#/$defs/Collection" }
+        }
+      },
+      "output": { "type": "array" },
+      "errors": { "db": { "schema": { "$ref": "#/$defs/DbError" } } },
+      "doc": "Every document of the collection, as the canonical scan query returns them."
+    },
+    "data.execute": {
+      "kind": "read",
+      "input": {
+        "type": "object",
+        "required": ["collection", "document"],
+        "properties": {
+          "collection": { "$ref": "#/$defs/Collection" },
+          "document": true,
+          "externals": { "type": "object" }
+        }
+      },
+      "output": true,
+      "errors": { "db": { "schema": { "$ref": "#/$defs/DbError" } } },
+      "doc": "Run a query document. The query decides the output shape — an array pack answers rows, a bare FLWOR a sequence, an aggregate a scalar — so the output is deliberately open."
+    },
+    "data.explain": {
+      "kind": "read",
+      "input": {
+        "type": "object",
+        "required": ["collection", "document"],
+        "properties": {
+          "collection": { "$ref": "#/$defs/Collection" },
+          "document": true,
+          "externals": { "type": "object" }
+        }
+      },
+      "output": {
+        "type": "object",
+        "properties": {
+          "sql": { "type": "string" },
+          "params": { "type": "array" },
+          "indexes": { "type": "array" },
+          "residual": { "type": ["object", "null"] }
+        }
+      },
+      "errors": { "db": { "schema": { "$ref": "#/$defs/DbError" } } },
+      "doc": "The store's explain record for a query document: the SQL pushed down, its parameters, the indexes chosen and the residual (null when fully pushed)."
+    },
+    "data.oracle": {
+      "kind": "read",
+      "input": {
+        "type": "object",
+        "required": ["model", "collection", "documents", "query"],
+        "properties": {
+          "model": { "type": "object" },
+          "collection": { "$ref": "#/$defs/Collection" },
+          "documents": { "type": "array", "items": { "type": "object" } },
+          "query": true,
+          "externals": { "type": "object" },
+          "explain": {
+            "description": "Also answer the store's explain record for the query — the SQL pushed down, the pre-filters and the database's own scan narrative — so a reader can see the plan the throwaway store ran, not only its answer.",
+            "type": "boolean"
+          }
+        }
+      },
+      "output": {
+        "type": "object",
+        "required": ["answer", "empty"],
+        "properties": {
+          "answer": true,
+          "empty": {
+            "description": "The query answered the empty sequence, which JSON cannot spell and null must not stand in for — answer is null then, and means nothing.",
+            "type": "boolean"
+          },
+          "explain": {
+            "description": "Present only when asked for: the same record data.explain answers, over the throwaway store.",
+            "type": "object",
+            "properties": {
+              "sql": { "type": "string" },
+              "params": { "type": "array" },
+              "indexes": { "type": "array" },
+              "prefilters": { "type": "array" },
+              "residual": { "type": ["object", "null"] },
+              "scanNarrative": { "type": "string" }
+            }
+          }
+        }
+      },
+      "errors": { "db": { "schema": { "$ref": "#/$defs/DbError" } } },
+      "doc": "Run one query over a THROWAWAY store: a fresh in-memory store on the model, the documents inserted, the query executed (and explained, when explain is asked for), the store closed — whatever happened. The store this context holds is untouched: no registration, no announcement, and it works with no store open at all. It is how a second executor is held to the spatial corpus from a real browser tab, in every engine: the corpus needs execution, not persistence, so a tab whose OPFS pool is absent answers it exactly as an owner does."
+    },
+    "data.live": {
+      "kind": "subscribe",
+      "input": {
+        "type": "object",
+        "required": ["collection", "document"],
+        "properties": {
+          "collection": { "$ref": "#/$defs/Collection" },
+          "document": true,
+          "externals": { "type": "object" }
+        }
+      },
+      "output": {
+        "type": "object",
+        "required": ["rows"],
+        "properties": {
+          "rows": { "type": "array" }
+        }
+      },
+      "errors": { "db": { "schema": { "$ref": "#/$defs/DbError" } } },
+      "doc": "Subscribe to a live query: the snapshot is LIVE's result document and every committed write follows as a { patch, seq } emission over the stream binding — RFC 6902 end to end. Unsubscribing is the wire's (the port unsubscribe frame)."
+    },
+    "data.lives": {
+      "kind": "read",
+      "output": {
+        "type": "object",
+        "required": ["count"],
+        "properties": {
+          "count": { "type": "integer", "minimum": 0 }
+        }
+      },
+      "errors": { "db": { "schema": { "$ref": "#/$defs/DbError" } } },
+      "doc": "The number of live registrations this store currently holds — the studio's status surface, and how a test observes that a departed tab's subscription was released."
+    },
+    "data.migrate": {
+      "kind": "command",
+      "input": {
+        "type": "object",
+        "required": ["to"],
+        "properties": {
+          "to": { "type": "object" },
+          "id": { "type": "string" }
+        }
+      },
+      "output": {
+        "type": "object",
+        "required": ["planned", "losses", "applied"],
+        "properties": {
+          "planned": { "type": "array", "items": { "type": "string" } },
+          "losses": { "type": "array" },
+          "applied": { "type": "array", "items": { "type": "string" } },
+          "note": { "type": "string" }
+        }
+      },
+      "errors": { "db": { "schema": { "$ref": "#/$defs/DbError" } } },
+      "doc": "From the owning context, plan a migration to a new model, shadow-verify and apply it (memory stores recreate instead — note says so), and reopen the store on the new model. A refused migration reopens the baseline. Both paths announce the active model so every tab resubscribes. Client-channel migrations are refused with the db failure."
+    }
+  }
+}

package/dist/types/component/data/actions.d.ts

@@ -0,0 +1,234 @@
+/** Shared Data transitions for composed and independently mounted editors. */
+export declare const DATA_ACTIONS: {
+    'data/boot': {
+        effects: {
+            run: string;
+        }[];
+    };
+    'data/seed': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/pane': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/model-text': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/query-text': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/open': {
+        effects: {
+            run: string;
+            with: {
+                text: string;
+            };
+        }[];
+    };
+    'data/run': {
+        effects: {
+            run: string;
+            with: {
+                text: string;
+            };
+        }[];
+    };
+    'data/insert-draft': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/insert': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+        effects: {
+            run: string;
+            with: {
+                title: string;
+            };
+        }[];
+    };
+    'data/delete': {
+        effects: {
+            run: string;
+            with: {
+                key: string;
+            };
+        }[];
+    };
+    'data/migrate': {
+        effects: {
+            run: string;
+        }[];
+    };
+    'data/oracle-run': {
+        effects: {
+            run: string;
+        }[];
+    };
+    'data/oracle': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/trip-csv': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/trip-run': {
+        effects: {
+            run: string;
+            with: {
+                csv: string;
+            };
+        }[];
+    };
+    'data/trip': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/status': {
+        patch: ({
+            op: string;
+            path: string;
+            value: string;
+        } | {
+            op: string;
+            path: string;
+            value: {
+                $default: (string | null)[];
+            };
+        })[];
+    };
+    'data/opened': {
+        patch: ({
+            op: string;
+            path: string;
+            value: string;
+        } | {
+            op: string;
+            path: string;
+            value: {
+                $default: (string | never[])[];
+            };
+        })[];
+    };
+    'data/rows': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/results': {
+        patch: ({
+            op: string;
+            path: string;
+            value: string;
+        } | {
+            op: string;
+            path: string;
+            value: null;
+        })[];
+    };
+    'data/live': {
+        patch: ({
+            op: string;
+            path: string;
+            value: string;
+        } | {
+            op: string;
+            path: string;
+            value: null;
+        })[];
+    };
+    'data/live-event': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/lives': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/migrated': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/error': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/ready': {
+        patch: {
+            op: string;
+            path: string;
+            value: string;
+        }[];
+    };
+    'data/boot-error': {
+        patch: ({
+            op: string;
+            path: string;
+            value: string;
+        } | {
+            op: string;
+            path: string;
+            value: null;
+        })[];
+    };
+    'data/retry': {
+        patch: ({
+            op: string;
+            path: string;
+            value: string;
+        } | {
+            op: string;
+            path: string;
+            value: null;
+        })[];
+        effects: {
+            run: string;
+        }[];
+    };
+};

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

@@ -0,0 +1,9 @@
+export { createTransport } from '../../data/transport.js';
+export { createDataRuntime } from '../../data/runtime.js';
+export { createDataState } from '../../data/state.js';
+export { DATA_ACTIONS } from './actions.js';
+export { DATA_RULES } from './views.js';
+export { dataViewModel, oracleSummary } from './viewmodel.js';
+export { createProjectDataRuntime } from './project-widget.js';
+export { createDataController } from '../../data/editor.js';
+export { mountDataEditor } from './mount.js';

package/dist/types/component/data/mount.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @param {HTMLElement|null} node
+ * @param {{ model: any, query: any, transport: () => ReturnType<typeof import('../../data/transport.js').createTransport>,
+ *   seeds?: any[], createRow?: (text: string) => any, migration?: (model: any, collection: string) => { to: any, id: string },
+ *   trip?: any, corpus?: () => Promise<any>, executor?: string, operators?: { toOptions: () => any }, lifecycleTarget?: any,
+ *   schedule?: (flush: () => void) => void, onError?: (error: Error) => void }} options
+ */
+export declare function mountDataEditor(node: HTMLElement | null, options: {
+    model: any;
+    query: any;
+    transport: () => ReturnType<typeof import('../../data/transport.js').createTransport>;
+    seeds?: any[];
+    createRow?: (text: string) => any;
+    migration?: (model: any, collection: string) => {
+        to: any;
+        id: string;
+    };
+    trip?: any;
+    corpus?: () => Promise<any>;
+    executor?: string;
+    operators?: {
+        toOptions: () => any;
+    };
+    lifecycleTarget?: any;
+    schedule?: (flush: () => void) => void;
+    onError?: (error: Error) => void;
+}): {
+    readonly ready: Promise<{
+        ok: boolean;
+        error?: string | {
+            code: string;
+            stage: string;
+            message: string;
+        };
+    }>;
+    read: () => import("../../data/editor.js").DataSnapshot;
+    validate: (candidate: {
+        model: any;
+        query: any;
+    }) => {
+        valid: boolean;
+        total: number;
+        errors: {
+            code: string | null;
+            message: string;
+            docPath?: string;
+            member: string;
+        }[];
+    } | {
+        valid: boolean;
+        total: number;
+        errors: {
+            code: any;
+            message: any;
+        }[];
+    };
+    replace: (candidate: {
+        model: any;
+        query: any;
+    }, options?: {
+        expectedRevision?: string;
+    }) => Promise<import("../../data/editor.js").EditorReceipt>;
+    apply: (patch: Parameters<typeof import("@jarenjs/json").applyJSONPatch>[1], options?: {
+        expectedRevision?: string;
+    }) => Promise<import("../../data/editor.js").EditorReceipt>;
+    /** @param {Parameters<typeof controller.run>[0]} [options] */
+    run(options?: Parameters<(options?: {
+        operation?: 'query' | 'open';
+        externals?: Record<string, any>;
+    }) => Promise<import("../../data/editor.js").EditorReceipt>>[0]): Promise<import("../../data/editor.js").EditorReceipt> | Promise<{
+        ok: boolean;
+        error: string;
+    }>;
+    subscribe: (listener: (snapshot: import("../../data/editor.js").DataSnapshot) => void) => () => void;
+    /** Release ownership on route exit while retaining every raw editing buffer.
+     * Reactivation reopens the last accepted model and never seeds over typing.
+     * @param {boolean} next */
+    setActive(next: boolean): Promise<{
+        ok: boolean;
+        error?: string | {
+            code: string;
+            stage: string;
+            message: string;
+        };
+    }>;
+    dispose(): void;
+};

package/dist/types/component/data/project-widget.d.ts

@@ -0,0 +1,27 @@
+export declare function createProjectDataRuntime(options?: {}): {
+    widget: {
+        mount(host: any, props: any): {
+            dead: boolean;
+            generation: number;
+            draft: string;
+            deleteDraft: string;
+            result: null;
+            plan: null;
+            live: null;
+            props: any;
+        };
+        update(h: any, props: any): void;
+        unmount(h: any): void;
+    };
+    sync: (project: any, reset?: boolean) => void;
+    dispose: () => void;
+    acquire: (project: any, file: any) => {
+        entry: any;
+        collection: string;
+        modelName: any;
+    };
+    execute: (project: any, name: any) => Promise<{
+        result: any;
+        plan: any;
+    }>;
+};