@jarenjs/studio 0.75.0 → 0.83.3

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

@@ -4,37 +4,105 @@
   "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"],
+  "required": [
+    "project",
+    "files"
+  ],
   "additionalProperties": false,
   "properties": {
-    "project": { "enum": ["0.1"] },
+    "project": {
+      "enum": [
+        "0.1"
+      ]
+    },
     "files": {
       "type": "array",
-      "items": { "$ref": "#/definitions/file" }
+      "items": {
+        "$ref": "#/definitions/file"
+      }
+    },
+    "active": {
+      "type": "string"
     },
-    "active": { "type": "string" },
-    "layout": { "$ref": "#/definitions/layout" }
+    "layout": {
+      "$ref": "#/definitions/layout"
+    }
   },
   "definitions": {
     "file": {
       "type": "object",
-      "required": ["name", "kind", "text"],
+      "required": [
+        "name",
+        "kind",
+        "text"
+      ],
       "additionalProperties": false,
       "properties": {
-        "name": { "type": "string", "minLength": 1 },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
         "kind": {
-          "enum": ["app", "jslt", "query", "state", "data", "schema", "fsm", "dag", "model", "contract"]
+          "enum": [
+            "app",
+            "jslt",
+            "query",
+            "state",
+            "data",
+            "schema",
+            "fsm",
+            "dag",
+            "model",
+            "contract"
+          ]
         },
-        "text": { "type": "string" }
+        "text": {
+          "type": "string"
+        },
+        "imports": {
+          "type": "object",
+          "description": "Top-level artifact member to project file name; replaces an absent member with the entire source JSON value.",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "input": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Explicit data/state input file."
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Model file whose worker store executes this query."
+        },
+        "collection": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Collection in the referenced model; required when ambiguous."
+        }
       }
     },
     "layout": {
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "mode": { "enum": ["classic", "right", "top"] },
-        "ratio": { "type": "number", "minimum": 0, "maximum": 1 },
-        "autorun": { "type": "boolean" }
+        "mode": {
+          "enum": [
+            "classic",
+            "right",
+            "top"
+          ]
+        },
+        "ratio": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "autorun": {
+          "type": "boolean"
+        }
       }
     }
   }

package/schemas/jaren-project.schema.json

@@ -2,45 +2,109 @@
   "$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.",
+  "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 \u2014 so a data file may use host-registered operators the closed grammars forbid.",
   "type": "object",
-  "required": ["project", "files"],
+  "required": [
+    "project",
+    "files"
+  ],
   "additionalProperties": false,
   "properties": {
-    "project": { "const": "0.1" },
+    "project": {
+      "const": "0.1"
+    },
     "files": {
       "type": "array",
       "description": "The project's files, each a named unit of one concern.",
-      "items": { "$ref": "#/$defs/file" }
+      "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" }
+    "layout": {
+      "$ref": "#/$defs/layout"
+    }
   },
   "$defs": {
     "file": {
       "type": "object",
-      "required": ["name", "kind", "text"],
+      "required": [
+        "name",
+        "kind",
+        "text"
+      ],
       "additionalProperties": false,
       "properties": {
-        "name": { "type": "string", "minLength": 1 },
+        "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", "contract"]
+          "enum": [
+            "app",
+            "jslt",
+            "query",
+            "state",
+            "data",
+            "schema",
+            "fsm",
+            "dag",
+            "model",
+            "contract"
+          ]
+        },
+        "text": {
+          "type": "string"
         },
-        "text": { "type": "string" }
+        "imports": {
+          "type": "object",
+          "description": "Top-level artifact member to project file name; replaces an absent member with the entire source JSON value.",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "input": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Explicit data/state input file."
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Model file whose worker store executes this query."
+        },
+        "collection": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Collection in the referenced model; required when ambiguous."
+        }
       }
     },
     "layout": {
       "type": "object",
-      "description": "The IDE arrangement — frozen so it survives a share link and the eject.",
+      "description": "The IDE arrangement \u2014 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" }
+        "mode": {
+          "enum": [
+            "classic",
+            "right",
+            "top"
+          ]
+        },
+        "ratio": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "autorun": {
+          "type": "boolean"
+        }
       }
     }
   }

package/src/assemble.js

@@ -4,17 +4,14 @@
  * 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
@@ -23,6 +20,7 @@
 
 import { semanticKey, setObjectMember } from '@jarenjs/core/object';
 import { validateFile } from './validate.js';
+import { resolveProjectFile, projectFileContext } from './resolve.js';
 
 /** Kinds that are runnable artifacts on their own (vs. `state`/`data`
  * inputs). */
@@ -35,8 +33,12 @@ const ROLE = Object.freeze({
   contract: 'contract',
 });
 
+// Keep assembled validation inputs stable across chrome/buffer renders.
+// A new immutable file list invalidates its dependencies as one snapshot.
+const assembledFiles = new WeakMap();
+
 /**
- * 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 }> }}
@@ -46,14 +48,14 @@ export function assembleArtifacts(project) {
   const errors = [];
   for (const file of project.files) {
     if (!RUNNABLE.has(file.kind)) continue;
-    let doc;
-    try { doc = JSON.parse(file.text); }
+    let resolved;
+    try { resolved = resolveProjectFile(project, file.name); }
     catch (err) {
-      errors.push({ file: file.name, message: `not valid JSON: ${String(/** @type {any} */ (err)?.message ?? err)}` });
+      errors.push({ file: file.name, message: String(/** @type {any} */ (err)?.message ?? err) });
       continue;
     }
     artifacts.push({
-      name: file.name, kind: file.kind, role: ROLE[file.kind], doc, sourceFiles: [file.name],
+      name: file.name, kind: file.kind, role: ROLE[file.kind], ...resolved,
     });
   }
   return { artifacts, errors };
@@ -63,7 +65,7 @@ export function assembleArtifacts(project) {
  * (its `state` excluded); everything else in full. */
 function structuralKey(artifact) {
   return artifact.kind === 'app'
-    ? semanticKey({ view: artifact.doc.view, actions: artifact.doc.actions, subs: artifact.doc.subs })
+    ? semanticKey({ ...artifact.doc, state: null })
     : semanticKey(artifact.doc);
 }
 
@@ -115,7 +117,25 @@ export function describe(project, options = {}) {
     active: project.active,
     layout: project.layout,
     files: project.files.map((file) => {
-      const v = validateFile(file, options);
+      let v;
+      try {
+        projectFileContext(project, file);
+        let effective = file;
+        if (file.imports) {
+          let byFile = assembledFiles.get(project.files);
+          if (!byFile) { byFile = new Map(); assembledFiles.set(project.files, byFile); }
+          effective = byFile.get(file);
+          if (!effective) {
+            effective = { ...file, text: JSON.stringify(resolveProjectFile(project, file.name).doc) };
+            byFile.set(file, effective);
+          }
+        }
+        v = validateFile(effective, options);
+      }
+      catch (error) {
+        v = { valid: false, total: 1, errors: [{ code: error.code ?? null,
+          message: error.message, docPath: error.docPath ?? '' }] };
+      }
       return {
         name: file.name,
         kind: file.kind,

package/src/author.js

@@ -0,0 +1,55 @@
+//@ts-check
+/** Constrain one file's generation, then apply the full grammar/compiler.
+ * This helper returns a candidate; the host owns conflict-safe publication. */
+import { createStructuredOutput } from '@jarenjs/ai';
+import { validateFile } from './validate.js';
+import { resolveProjectFile } from './resolve.js';
+import app from '@jarenjs/app/schemas/jaren-app.authoring.schema.json' with { type: 'json' };
+import query from '@jarenjs/json/schemas/jaren-query.authoring.schema.json' with { type: 'json' };
+import jslt from '@jarenjs/json/schemas/jaren-jslt.authoring.schema.json' with { type: 'json' };
+import fsm from '@jarenjs/flow/schemas/jaren-fsm.authoring.schema.json' with { type: 'json' };
+import dag from '@jarenjs/flow/schemas/jaren-dag.authoring.schema.json' with { type: 'json' };
+import model from '@jarenjs/db/schemas/jaren-model.authoring.schema.json' with { type: 'json' };
+
+export const AUTHORABLE_KINDS = Object.freeze(['app', 'query', 'jslt', 'fsm', 'dag', 'model', 'schema', 'state', 'data', 'contract']);
+const PROFILES = { app, query, jslt, fsm, dag, model,
+  schema: { anyOf: [{ type: 'object' }, { type: 'boolean' }] },
+  state: {}, data: {}, contract: { type: 'object' },
+};
+
+/** @param {{ client: any, operators?: any, maxRepairs?: number }} options */
+export function createStudioFileAuthor(options) {
+  return {
+    /** @param {{ project: any, name: string, kind?: string, prompt: string }} request
+     * @param {{ signal?: AbortSignal }} [hooks] */
+    async author(request, hooks = {}) {
+      const original = request.project.files.find((f) => f.name === request.name);
+      const kind = request.kind ?? original?.kind;
+      if (!AUTHORABLE_KINDS.includes(kind)) throw new TypeError('choose an authorable file kind');
+      // Imported destinations are authored as fragments, never expanded into
+      // duplicated members. Their assembled artifact is the acceptance gate.
+      const profile = original?.imports ? { type: 'object' } : PROFILES[kind];
+      const check = (doc) => {
+        try {
+          const file = { ...original, name: request.name, kind, text: JSON.stringify(doc) };
+          const project = { files: [...request.project.files.filter((f) => f.name !== file.name), file] };
+          const assembled = resolveProjectFile(project, file.name).doc;
+          const verdict = validateFile({ ...file, text: JSON.stringify(assembled) }, { operators: options.operators });
+          if (!verdict.valid) return verdict;
+          return true;
+        }
+        catch (error) { return { valid: false, errors: [{ code: error.code ?? null,
+          docPath: error.docPath ?? '', message: error.reason ?? error.message }] }; }
+      };
+      const generator = createStructuredOutput({ client: options.client, schema: profile,
+        name: `studio_${kind}`, strict: false, validator: check, maxRepairs: options.maxRepairs ?? 2 });
+      const result = await generator.generate([
+        { role: 'system', content: `Author exactly one ${kind} file named ${request.name}. Return its JSON value only. Do not return a project envelope. Files available: ${JSON.stringify(request.project.files.map((f) => ({ name: f.name, kind: f.kind })))}.${original?.imports ? ` Imported members are supplied by ${JSON.stringify(original.imports)}; omit these members from your output.` : ''}` },
+        ...(original ? [{ role: 'user', content: `Current file:\n${original.text}` }] : []),
+        { role: 'user', content: request.prompt },
+      ], hooks);
+      if (!('value' in result)) return result;
+      return { ...result, file: { ...original, name: request.name, kind, text: JSON.stringify(result.value, null, 2) } };
+    },
+  };
+}

package/src/component/view.js

@@ -14,6 +14,7 @@
  * kind badge rides `data-badge`.
  */
 
+import { ADDABLE_KINDS } from '../skeletons.js';
 import { editorTextarea } from './editor.js';
 
 /** The one mode this view uses. */
@@ -85,13 +86,7 @@ const shell = {
     ['nav', { class: 'js-rail', 'aria-label': 'files' },
       ['select', { class: 'js-addfile', 'aria-label': 'add a file', value: '', on: { change: 'project/add-file' } },
         ['option', { value: '' }, '+ add file…'],
-        ['option', { value: 'app' }, 'app'],
-        ['option', { value: 'jslt' }, 'jslt'],
-        ['option', { value: 'query' }, 'query'],
-        ['option', { value: 'state' }, 'state'],
-        ['option', { value: 'data' }, 'data'],
-        ['option', { value: 'schema' }, 'schema'],
-        ['option', { value: 'contract' }, 'contract'],
+        ...ADDABLE_KINDS.map((kind) => ['option', { value: kind }, kind]),
       ],
       [{ $apply: '$.rail[*]' }]],
     // ——— editor ———
@@ -124,6 +119,17 @@ const shell = {
           }, 'Take theirs'],
         ],
         ''] },
+      { $if: ['$.routing', ['div', { class: 'js-routing' },
+        { $if: ['$.routing.hasInput', ['label', {}, 'Input ', ['select', { 'aria-label': 'Input file', value: '$.routing.input', on: { change: { action: 'project/route-input' } } },
+          ['option', { value: '' }, 'Default data file'],
+          [{ $for: { name: '$.routing.inputs[*]' }, $return: ['option', { value: '$name' }, '$name'] }]]], ''] },
+        { $if: ['$.routing.canModel', ['label', {}, 'Model ',
+          ['select', { 'aria-label': 'Model file', value: '$.routing.model', on: { change: 'project/route-model' } },
+            ['option', { value: '' }, 'In-memory input'],
+            [{ $for: { name: '$.routing.models[*]' }, $return: ['option', { value: '$name' }, '$name'] }]]], ''] },
+        { $if: ['$.routing.hasCollection', ['label', {}, 'Collection ', ['input', { 'aria-label': 'Collection', defaultValue: '$.routing.collection',
+          key: '$.active', placeholder: 'Only collection', on: { change: 'project/route-collection' } }]], ''] },
+      ], ''] },
       editorTextarea({
         value: '$.editorValue',
         action: 'project/file-text',
@@ -147,7 +153,7 @@ const shell = {
       ['div', { class: 'js-stage-head' }, 'Stage'],
       { $if: ['$.stageError', ['div', { class: 'js-stage-error js-stage-fail', role: 'status' }, '$.stageError'], ''] },
       { $if: [{ $eq: ['$.stage.kind', 'app'] },
-        ['div', { class: 'js-stage-mount' }, ['jaren-widget', { name: 'studio-stage', props: '$.stage.mount' }]],
+        ['div', { class: 'js-stage-mount' }, ['jaren-widget', { name: { $default: ['$.stage.widget', 'studio-stage'] }, props: '$.stage.mount' }]],
         { $if: [{ $eq: ['$.stage.kind', 'result'] },
           { $if: ['$.stage.ran',
             ['div', { class: 'js-stage-result' }, [{ $apply: ['$.stage.nodes[*]', 'ui'] }]],

package/src/component/viewmodel.js

@@ -21,13 +21,14 @@ const MOBILE_PANES = ['files', 'editor', 'stage'];
 /** The stage the active file drives. */
 function deriveStage(project, activeMeta, results, revision, committed) {
   if (activeMeta === null) return { kind: 'empty', note: 'Add a file to begin.' };
-  if (activeMeta.kind === 'app') {
+  if (committed?.store) return { kind: 'app', widget: 'studio-data', mount: committed };
+  if (committed?.kind === 'app' || ['app', 'fsm', 'dag'].includes(activeMeta.kind)) {
     // A host that runs the app live commits the LAST-GOOD assembled
     // document (with its own reboot revision). That wins over the current
     // text: a parse error in the editor must never blank the stage — the
     // last good frame stays until the next VALID commit replaces it.
     if (committed !== null && committed.doc) {
-      return { kind: 'app', mount: { doc: committed.doc, revision: committed.revision } };
+      return { kind: 'app', widget: (committed.kind ?? activeMeta.kind) === 'app' ? 'studio-stage' : 'studio-flow', mount: committed };
     }
     const artifact = assembleArtifacts(project).artifacts.find((a) => a.name === activeMeta.name);
     if (artifact === undefined || !activeMeta.valid) {
@@ -35,7 +36,7 @@ function deriveStage(project, activeMeta, results, revision, committed) {
     }
     // the reference-stable mount is memoized by the host at wiring time;
     // here it is the data: the assembled document + the reboot revision
-    return { kind: 'app', mount: { doc: artifact.doc, revision } };
+    return { kind: 'app', widget: activeMeta.kind === 'app' ? 'studio-stage' : 'studio-flow', mount: { name: activeMeta.name, kind: activeMeta.kind, doc: artifact.doc, revision } };
   }
   if (activeMeta.kind === 'jslt' || activeMeta.kind === 'query' || activeMeta.kind === 'schema'
     || activeMeta.kind === 'contract') {
@@ -49,10 +50,7 @@ function deriveStage(project, activeMeta, results, revision, committed) {
   if (activeMeta.kind === 'state' || activeMeta.kind === 'data') {
     return { kind: 'inert', note: 'An input — edit it as text; it feeds the app, a query or a validation.' };
   }
-  // fsm / dag / model validate and assemble, but have no editor and no
-  // runner here yet — the flow canvas and the worker-backed store still
-  // live on their own website surfaces (both are tracked in ROADMAP.md)
-  return { kind: 'inert', note: `The ${activeMeta.role} editor is not built yet; edit it as text meanwhile.` };
+  return { kind: 'inert', note: `Press Run to open the ${activeMeta.role}.` };
 }
 
 /**
@@ -100,7 +98,7 @@ export function projectViewModel(state, options = {}) {
   // used only while it is the active file — a reference-stable document
   // the stage widget reboots (revision change) or hot-updates (same
   // revision, new state) against
-  const committed = (slice.mount && slice.mount.name === activeName) ? slice.mount : null;
+  const committed = (slice.mount && (slice.mount.name === activeName || slice.mount.sourceFiles?.includes(activeName))) ? slice.mount : null;
 
   // The editor's value is the typing BUFFER reconciled against the file's
   // committed text, never the committed text alone: the buffer is what the
@@ -134,6 +132,13 @@ export function projectViewModel(state, options = {}) {
       ? slice.renameDraft.text
       : activeName,
     activeKind: activeMeta?.kind ?? null,
+    routing: activeFile && ['query', 'jslt', 'schema', 'fsm', 'dag', 'model'].includes(activeFile.kind) ? {
+      input: activeFile.input ?? '', model: activeFile.model ?? '', collection: activeFile.collection ?? '',
+      canModel: activeFile.kind === 'query',
+      hasInput: !activeFile.model, hasCollection: activeFile.kind === 'model' || !!activeFile.model,
+      inputs: project.files.filter((f) => ['data', 'state'].includes(f.kind)).map((f) => f.name),
+      models: project.files.filter((f) => f.kind === 'model').map((f) => f.name),
+    } : null,
     activeValid: activeMeta?.valid ?? true,
     activeErrors: activeMeta?.errors ?? [],
     editorValue,

package/src/errors.js

@@ -17,6 +17,7 @@ import { CodedError } from '@jarenjs/core/errors';
 export const STUDIO_CODES = Object.freeze({
   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. */

package/src/export.js

@@ -0,0 +1,66 @@
+//@ts-check
+/** A deterministic ZIP export. Dependencies are supplied as local bundled
+ * bytes, never silently replaced with mutable CDN URLs. */
+import { parseProject } from './project.js';
+
+const utf8 = new TextEncoder();
+const crc32 = (bytes) => {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit++) crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+};
+
+/** ZIP method 0 (stored), UTF-8 names, fixed DOS epoch, no ZIP64.
+ * @param {Record<string, string | Uint8Array>} files @returns {Uint8Array} */
+export function createProjectZip(files) {
+  const entries = Object.entries(files).map(([name, content]) => {
+    if (!name || name.startsWith('/') || name.includes('\\') || [...name].some((char) => char.charCodeAt(0) < 32)
+      || name.split('/').some((part) => part === '..' || part === '.' || part === ''))
+      throw new TypeError(`unsafe archive path '${name}'`);
+    const path = utf8.encode(name);
+    if (path.length > 65535) throw new RangeError('archive path is too long');
+    return { path, bytes: typeof content === 'string' ? utf8.encode(content) : content, offset: 0 };
+  });
+  const size = entries.reduce((n, e) => n + 76 + e.path.length * 2 + e.bytes.length, 22);
+  if (entries.length > 65535 || size > 0xffffffff) throw new RangeError('ZIP64 is not supported');
+  const out = new Uint8Array(size);
+  const data = new DataView(out.buffer);
+  let cursor = 0;
+  const u16 = (value) => { data.setUint16(cursor, value, true); cursor += 2; };
+  const u32 = (value) => { data.setUint32(cursor, value, true); cursor += 4; };
+  const bytes = (value) => { out.set(value, cursor); cursor += value.length; };
+  for (const entry of entries) {
+    entry.offset = cursor;
+    u32(0x04034b50); u16(20); u16(0x800); u16(0); u16(0); u16(33);
+    u32(crc32(entry.bytes)); u32(entry.bytes.length); u32(entry.bytes.length);
+    u16(entry.path.length); u16(0); bytes(entry.path); bytes(entry.bytes);
+  }
+  const directory = cursor;
+  for (const entry of entries) {
+    u32(0x02014b50); u16(20); u16(20); u16(0x800); u16(0); u16(0); u16(33);
+    u32(crc32(entry.bytes)); u32(entry.bytes.length); u32(entry.bytes.length);
+    u16(entry.path.length); u16(0); u16(0); u16(0); u16(0); u32(0); u32(entry.offset); bytes(entry.path);
+  }
+  const directorySize = cursor - directory;
+  u32(0x06054b50); u16(0); u16(0); u16(entries.length); u16(entries.length);
+  u32(directorySize); u32(directory); u16(0);
+  return out;
+}
+
+/** @param {any} project @param {Record<string, string | Uint8Array>} assets */
+export function exportProject(project, assets) {
+  const normalized = parseProject({ project: project.project, files: project.files,
+    ...(project.active ? { active: project.active } : {}), layout: project.layout });
+  if (!Object.hasOwn(assets, 'runtime.js')) throw new TypeError('a bundled runtime.js is required');
+  const files = {
+    'index.html': '<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Jaren project</title><link rel="stylesheet" href="runtime/runtime.css"><body><main id="app"></main><script type="module" src="runtime/runtime.js"></script></body></html>',
+    'project.json': JSON.stringify(normalized, null, 2),
+    'README.md': '# Jaren offline project\n\nUnzip, then serve this directory locally:\n\n    python3 -m http.server 8080 --bind 127.0.0.1\n\nOpen http://127.0.0.1:8080. No package installation or internet connection is needed.\n\nDependency policy: the runtime, worker, SQLite WASM and CSS are bundled from the exporting build, with versions in runtime/versions.json. There are no CDN dependencies. Application-authored external links/assets still require their own hosts. The host grants no application effects or subscriptions; flow effects are logged. Unknown DAG tasks are refused.\n\nproject.json preserves every file, reference, and layout. files/ contains verbatim source text in project order; numeric names preserve arbitrary original names safely in an archive. The runner selects any project file. Model stores are private in-memory SQLite and last until reload; database rows are runtime state and are not included in this source export.\n',
+  };
+  normalized.files.forEach((file, i) => { files[`files/${String(i + 1).padStart(4, '0')}.json`] = file.text; });
+  for (const [name, bytes] of Object.entries(assets)) files[`runtime/${name}`] = bytes;
+  return createProjectZip(files);
+}

package/src/index.js

@@ -18,3 +18,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/src/project.js

@@ -65,7 +65,7 @@ export function parseProject(input) {
     : (doc.files[0]?.name ?? null);
   return Object.freeze({
     project: doc.project,
-    files: Object.freeze(doc.files.map((f) => Object.freeze({ ...f }))),
+    files: Object.freeze(doc.files.map((f) => Object.freeze({ ...f, ...(f.imports ? { imports: Object.freeze({ ...f.imports }) } : {}) }))),
     active,
     layout: Object.freeze({ ...LAYOUT_DEFAULT, ...doc.layout }),
   });