@descix/frqtl-node 0.6.0-p0.2 → 0.6.0-p4.1

package/dist/frqtl/scenes/sun.js

@@ -5,7 +5,7 @@
  *
  * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world
  * (its co-init call, `exp.createCanvas` / `exp.createScene` — the one place its size is written),
- * the parts (`exp.addObject`) and the render intent are all here; the sugar
+ * the parts (`export const parts` + `exp.declare`, or `exp.addObject`) and the render intent are all here; the sugar
  * objects, renderer and engine are imports. Registered by lib/shim/registry/walkthrough.js
  * (rung r8-sun).
  */
@@ -21,18 +21,21 @@
 
 import { CameraControls, SphereEmitter } from '@descix/frqtl-web/parts';
 
+export const parts = {
+  source: [SphereEmitter, {
+    preset: 'spherical', emissionBoxSide: 0, is2D: false,
+    chargeMode: 'random', fundamentalDimension: 2,
+    wavelength: 1, fundamentalWaveLength: 64, emitEveryTicks: 1
+  }],
+};
+
 export default function buildExperiment(exp) {
   // Rung 8 (Sun) — the sun.png panel regime: a 3D omni POINT source, virtual mass 16
   // (fullness 1) via wavelength:1, λ scale 16 via fundamentalWaveLength:64, emit every 1.
   // The sphere shape + god-rays + glow FX ride the renderState (three-only capabilities).
   // The sun's yellow is the NATURAL fullness->color (mass=capacity, fullness 1); no forced color.
-  var SRC = {
-    preset: 'spherical', emissionBoxSide: 0, is2D: false,
-    chargeMode: 'random', fundamentalDimension: 2,
-    wavelength: 1, fundamentalWaveLength: 64, emitEveryTicks: 1
-  };
-  exp.createScene(600, 400, 600, SphereEmitter.worldCfg(SRC));   // THE WORLD: a 3D scene + universe, 600x400x600 — first, then parts
-  exp.addObject('SphereEmitter', SRC);
+  exp.createScene(600, 400, 600, SphereEmitter.worldCfg(parts.source[1]));   // THE WORLD: a 3D scene + universe, 600x400x600 — first, then parts
+  exp.declare(parts);
   if (typeof document !== 'undefined' && exp.runner) {
     if (exp.runner.controlHost) { CameraControls.attach(exp.runner, exp.runner.controlHost); }
   }

package/dist/frqtl/scenes/two-source.js

@@ -5,7 +5,7 @@
  *
  * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world
  * (its co-init call, `exp.createCanvas` / `exp.createScene` — the one place its size is written),
- * the parts (`exp.addObject`) and the render intent are all here; the sugar
+ * the parts (`export const parts` + `exp.declare`, or `exp.addObject`) and the render intent are all here; the sugar
  * objects, renderer and engine are imports. Registered by lib/shim/registry/walkthrough.js
  * (rungs r6a-two-source, r6b-two-fountains, r6c-plasma-fusion).
  */
@@ -16,22 +16,27 @@
 
 import { SphereEmitter } from '@descix/frqtl-web/parts';
 
+// The classic self-interference config called TWICE, centered ±32px from canvas
+// center (64px apart = 1×fundamentalWaveLength, i.e. λ_eff/4 since λ_eff = 4×fWL).
+// The world is init'd ONCE, then TWO parts are constructed on it — no flag, no
+// re-init, no stacking. The
+// lattice BETWEEN the two visible sources is EMERGENT density superposition (SU1).
+const W = 600, H = 400;   // THE WORLD this scene states (its co-init call below)
+const cx = Math.floor(W / 2), cy = Math.floor(H / 2);
+const CFG = {
+  is2D: true, preset: 'spherical',
+  emissionShell: 'surface', innerR: 16,
+  fundamentalDimension: 2, wavelength: 32,
+  chargeMode: 'random', fundamentalWaveLength: 64,
+  burstSize: 72, emitEveryTicks: 1
+};
+
+export const parts = {
+  left: [SphereEmitter, { ...CFG, center: [cx - 32, cy] }],
+  right: [SphereEmitter, { ...CFG, center: [cx + 32, cy] }],
+};
+
 export default function buildExperiment(exp) {
-  // The classic self-interference config called TWICE, centered ±32px from canvas
-  // center (64px apart = 1×fundamentalWaveLength, i.e. λ_eff/4 since λ_eff = 4×fWL).
-  // The world is init'd ONCE, then TWO parts are constructed on it — no flag, no
-  // re-init, no stacking. The
-  // lattice BETWEEN the two visible sources is EMERGENT density superposition (SU1).
-  var W = 600, H = 400;   // THE WORLD this scene states (its co-init call below)
-  var cx = Math.floor(W / 2), cy = Math.floor(H / 2);
-  var CFG = {
-    is2D: true, preset: 'spherical',
-    emissionShell: 'surface', innerR: 16,
-    fundamentalDimension: 2, wavelength: 32,
-    chargeMode: 'random', fundamentalWaveLength: 64,
-    burstSize: 72, emitEveryTicks: 1
-  };
   exp.createCanvas(W, H, SphereEmitter.worldCfg(CFG));   // THE WORLD: a 2D canvas + universe — first, then parts
-  exp.addObject('SphereEmitter', Object.assign({}, CFG, { center: [cx - 32, cy] }));
-  exp.addObject('SphereEmitter', Object.assign({}, CFG, { center: [cx + 32, cy] }));
+  exp.declare(parts);
 }

package/dist/frqtl/scenes/wave.js

@@ -5,22 +5,25 @@
  *
  * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world
  * (its co-init call, `exp.createCanvas` / `exp.createScene` — the one place its size is written),
- * the parts (`exp.addObject`) and the render intent are all here; the sugar
+ * the parts (`export const parts` + `exp.declare`, or `exp.addObject`) and the render intent are all here; the sugar
  * objects, renderer and engine are imports. Registered by lib/shim/registry/walkthrough.js
  * (rung r2-wave).
  */
 
 import { SphereEmitter } from '@descix/frqtl-web/parts';
 
+export const parts = {
+  source: [SphereEmitter, {
+    preset: 'particle-walk', is2D: true,
+    fundamentalDimension: 2, wavelength: 8
+  }],
+};
+
 export default function buildExperiment(exp) {
   // Rung 2 — Rung 1 + raise the leaf dimension to 2 (WAVELENGTH_DEMO_DIMENSION):
   // wavelength is a NO-OP at dim 0 (capacity=1 saturates mass), so raising the
   // fundamental gives the wavelength arg leverage. wavelength:8 -> mass 2 ->
   // transverse period grows from ~16px (Rung 1) to a visible ~128px snake.
-  var SRC = {
-    preset: 'particle-walk', is2D: true,
-    fundamentalDimension: 2, wavelength: 8
-  };
-  exp.createCanvas(600, 400, SphereEmitter.worldCfg(SRC));   // THE WORLD: a 2D canvas + universe — first, then parts
-  exp.addObject('SphereEmitter', SRC);
+  exp.createCanvas(600, 400, SphereEmitter.worldCfg(parts.source[1]));   // THE WORLD: a 2D canvas + universe — first, then parts
+  exp.declare(parts);
 }

package/dist/shim/bundle/index.js

@@ -1,121 +1,137 @@
 /* Copyright 2023-2026 by Essam Abadir */
 
 /**
- * lib/shim/bundle/index.js — the recipe-bundle assembler + importer
- * The canonical owner of the bundle format
- * (design §2): a folder that zips for download —
+ * lib/shim/bundle/index.js — Export and Import of a project folder.
  *
- *   experiment.js      ← THE source of truth (the buildExperiment(exp) recipe)
- *   experiment.frqnb   ← teaching/gallery projection (notebook/format.serialize)
- *   index.html         ← standalone host (@descix/frqtl-web bootProject over the served folder)
- *   manifest.json      ← Module envelope minus `source` + bundle-only fields (E1)
- *   preview.png        ← optional golden screenshot
+ * A project is a folder (the stored row's owner is
+ * lib/shim/storage/folders.js). The Export IS the folder, zipped, plus the host page that boots it:
  *
- * PURE + DOM-free: emits/consumes `Uint8Array`. STUDIO's export button and any
- * future DeSciX publisher CONSUME this — passing the generated `experiment.js`
- * source + envelope + renderState DOWN (this module never imports codegen/
- * save-state — those live above the shim; the arrow stays one-way). The browser
- * `Blob`+`a.click` download trigger is a THIN feature-side helper.
+ *   exportFolder(files, renderState, { sdkVersion }) → zipBytes
+ *       the zip holds EXACTLY the folder's files plus a generated `index.html` (indexHtml.js: bootProject over the
+ *       served folder, frqtl.json naming the entry, the boot bag inlined by its one writer).
+ *   importArchive(bytes, fileName) → { files, renderState }   (a normalized folder row)
+ *       a zip      → its files minus `index.html`, whose boot bag (indexHtml.js readBootBag) becomes renderState;
+ *                    it must carry frqtl.json at its root (an archive with no index.html imports with
+ *                    renderState null)
+ *       one `.js`  → the one-file project { 'sketch.js': text, 'frqtl.json': manifestFor({ name: <basename>,
+ *                    entry: 'sketch.js' }) }, renderState null — a 3D sketch then fails loud at boot on the
+ *                    renderer (the existing named refusal); nothing guesses a display
+ *       REFUSED, naming the migration: a zip carrying `experiment.js` or `manifest.json`, or a JSON v4 module
+ *       envelope — the retired export format. REFUSED by rule: a one-file `.mjs` (frqtl.json's entry rule admits a
+ *       `.js` entry only), anything else.
  *
- * Layer 2 (physics): none — pure format/packaging.
+ * PURE + DOM-free (Uint8Array in and out). The browser download and file read are lib/features/ide/bundle-export.js.
+ * zip.js (the STORE zip) is imported by the Record too; its API is frozen. Layer 2 (physics): none.
  */
 
 'use strict';
 
-import { buildManifest, manifestToEnvelope } from './manifest.js';
-import { buildFrqnb } from './frqnb.js';
-import { buildIndexHtml } from './indexHtml.js';
-import { zipStore, unzipStore, textBytes, bytesText } from './zip.js';
-import { normalizeSavedRenderState } from '../render-state/index.js';
+import { zipStore, unzipStore, textBytes } from './zip.js';
+import { buildIndexHtml, readBootBag } from './indexHtml.js';
+import { normalizeFolderRow, EXPORT_PAGE } from '../storage/folders.js';
+import { MANIFEST_FILE, MANIFEST_KEYS, parseManifest, serializeManifest, manifestFor } from '../project/manifest.js';
 
-// ── Canonical bundle file names ──────────────────────────────────────────────
-export var FILE_EXPERIMENT_JS   = 'experiment.js';
-export var FILE_EXPERIMENT_FRQNB = 'experiment.frqnb';
-export var FILE_INDEX_HTML       = 'index.html';
-export var FILE_MANIFEST_JSON    = 'manifest.json';
-export var FILE_PREVIEW_PNG      = 'preview.png';
+/** The files of the retired export format (the v4 envelope's bundle). */
+export var RETIRED_ARCHIVE_FILES = Object.freeze(['experiment.js', 'manifest.json']);
 
-/**
- * Assemble a recipe bundle from a Module envelope + bundle inputs.
- *
- * Conceptually the dispatch's `(source, envelopeMeta, renderState, previewPngBytes,
- * sdkVersion)`: here `source` + `renderState` + `envelopeMeta` arrive together AS
- * the Module envelope (the exact shape STUDIO's Save path already builds), so the
- * bundle↔envelope round-trip is a clean identity. `manifest` ferries the envelope
- * minus `source` (E1) — no field re-enumeration.
- *
- * @param {object} envelope — a `lib/shim/storage/modules.js` Module envelope
- *   (`{id,name,source,renderState,…}`; `source` = the recipe, REQUIRED).
- * @param {object} opts
- * @param {string} opts.sdkVersion — REQUIRED CDN pin (derived, never a literal).
- * @param {Uint8Array|null} [opts.previewPngBytes] — preview image bytes, or null.
- * @param {string} [opts.stage='600x400'] — canvas stage for the .frqnb projection.
- * @param {string} [opts.prose] — optional teaching blurb for the .frqnb markdown.
- * @returns {{files: {name:string, bytes:Uint8Array}[], zipBytes: Uint8Array}}
- */
-export function assembleBundle(envelope, opts) {
-    if (!envelope || typeof envelope !== 'object') {
-        throw new Error('[bundle] assembleBundle(envelope): envelope must be an object.');
-    }
-    if (typeof envelope.source !== 'string' || envelope.source.length === 0) {
-        throw new Error('[bundle] assembleBundle: envelope.source (the recipe) is required.');
-    }
-    opts = opts || {};
-    var preview = (opts.previewPngBytes instanceof Uint8Array && opts.previewPngBytes.length > 0)
-        ? opts.previewPngBytes : null;
+var RETIRED = 'this is the retired export format; the project folder replaced it (frqtl.json + sketch.js)';
+var SKETCH = 'sketch.js';
 
-    var manifest = buildManifest(envelope, {
-        sdkVersion: opts.sdkVersion,
-        preview: preview ? FILE_PREVIEW_PNG : null
-    });
+var _strict = new TextDecoder('utf-8', { fatal: true });
 
-    var normalizedRs = normalizeSavedRenderState(envelope.renderState);
-
-    var files = [
-        { name: FILE_EXPERIMENT_JS,    bytes: textBytes(envelope.source) },
-        { name: FILE_EXPERIMENT_FRQNB, bytes: textBytes(buildFrqnb({
-            name: envelope.name, source: envelope.source,
-            renderState: normalizedRs, stage: opts.stage, prose: opts.prose
-        })) },
-        { name: FILE_INDEX_HTML,       bytes: textBytes(buildIndexHtml({
-            name: envelope.name, sdkVersion: opts.sdkVersion, renderState: normalizedRs,
-            scripts: Array.isArray(envelope.scripts) ? envelope.scripts : []   // the envelope's setup-factory delta
-        })) },
-        { name: FILE_MANIFEST_JSON,    bytes: textBytes(JSON.stringify(manifest, null, 2)) }
-    ];
-    if (preview) { files.push({ name: FILE_PREVIEW_PNG, bytes: preview }); }
-
-    return { files: files, zipBytes: zipStore(files) };
+function _fail(msg) {
+    throw new Error('[bundle] ' + msg + ' (FAIL-LOUD.)');
 }
 
 /**
- * Import a recipe bundle: recover the Module envelope (source re-attached from
- * `experiment.js` per E1) + the preview bytes.
- *
- * @param {Uint8Array} zipBytes — a bundle `.zip` (from `assembleBundle`).
- * @returns {{envelope: object, previewPngBytes: Uint8Array|null}}
+ * @param {Object<string,string>} files — the folder (frqtl.json + its files)
+ * @param {object|null} renderState — the host's boot bag (normalized by its owner through the folder row)
+ * @param {{sdkVersion: string}} opts — the `@descix/frqtl-web` pin the page imports (derived, never a literal)
+ * @returns {Uint8Array} the zip
  */
-export function importBundle(zipBytes) {
-    var entries = unzipStore(zipBytes);
-    var byName = Object.create(null);
-    for (var i = 0; i < entries.length; i++) { byName[entries[i].name] = entries[i].bytes; }
+export function exportFolder(files, renderState, opts) {
+    var row = normalizeFolderRow({ files: files, renderState: renderState });
+    var sdkVersion = opts && opts.sdkVersion;
+    var name = parseManifest(row.files[MANIFEST_FILE]).name;
+    var entries = Object.keys(row.files).map(function (p) { return { name: p, bytes: textBytes(row.files[p]) }; });
+    entries.push({ name: EXPORT_PAGE, bytes: textBytes(buildIndexHtml({ name: name, sdkVersion: sdkVersion, renderState: row.renderState })) });
+    return zipStore(entries);
+}
+
+function _isZip(bytes) {
+    return bytes.length >= 4 && bytes[0] === 0x50 && bytes[1] === 0x4b &&
+        ((bytes[2] === 0x03 && bytes[3] === 0x04) || (bytes[2] === 0x05 && bytes[3] === 0x06));
+}
 
-    if (!byName[FILE_MANIFEST_JSON]) {
-        throw new Error('[bundle] importBundle: ' + FILE_MANIFEST_JSON + ' missing from the archive.');
+function _text(bytes, what) {
+    try { return _strict.decode(bytes); }
+    catch (e) { _fail(what + ' is not UTF-8 text — a project folder holds text files only.'); }
+}
+
+function _baseName(fileName) {
+    var base = String(fileName).split(/[\\/]/).pop();
+    return base;
+}
+
+function _fromZip(bytes) {
+    var entries = unzipStore(bytes).filter(function (e) { return !/\/$/.test(e.name); });
+    var names = entries.map(function (e) { return e.name; });
+    var retired = RETIRED_ARCHIVE_FILES.filter(function (f) { return names.indexOf(f) !== -1; });
+    if (retired.length) {
+        _fail('the archive carries ' + retired.join(' and ') + ': ' + RETIRED + '.');
     }
-    if (!byName[FILE_EXPERIMENT_JS]) {
-        throw new Error('[bundle] importBundle: ' + FILE_EXPERIMENT_JS + ' missing from the archive.');
+    if (names.indexOf(MANIFEST_FILE) === -1) {
+        _fail('the archive carries no ' + MANIFEST_FILE + ' at its root — a project archive is the folder zipped ' +
+            '(frqtl.json + sketch.js + …), as an Export writes it.');
     }
+    var files = {};
+    var renderState = null;
+    entries.forEach(function (e) {
+        var text = _text(e.bytes, '"' + e.name + '"');
+        if (e.name === EXPORT_PAGE) { renderState = readBootBag(text); return; }
+        files[e.name] = text;
+    });
+    return normalizeFolderRow({ files: files, renderState: renderState });
+}
 
-    var manifest;
-    try {
-        manifest = JSON.parse(bytesText(byName[FILE_MANIFEST_JSON]));
-    } catch (e) {
-        throw new Error('[bundle] importBundle: ' + FILE_MANIFEST_JSON + ' is not valid JSON — ' + (e && e.message));
+function _fromJson(text) {
+    var raw;
+    try { raw = JSON.parse(text); }
+    catch (e) { _fail('the file is neither a project archive (.zip) nor a sketch (.js), and not valid JSON either.'); }
+    if (raw && typeof raw === 'object' && ('schemaVersion' in raw || 'scripts' in raw) && 'source' in raw) {
+        _fail('the file is a v4 module envelope: ' + RETIRED + '.');
     }
-    var source = bytesText(byName[FILE_EXPERIMENT_JS]);
-    var envelope = manifestToEnvelope(manifest, source);
-    var previewPngBytes = byName[FILE_PREVIEW_PNG] || null;
+    _fail('the JSON file is not a project — Import takes a project archive (.zip) or one sketch (.js).');
+}
+
+function _fromSketch(text, fileName) {
+    var base = _baseName(fileName);
+    var name = base.replace(/\.js$/, '');
+    if (!name) { _fail('the sketch file "' + base + '" has no name before ".js".'); }
+    var files = {};
+    files[MANIFEST_FILE] = serializeManifest(manifestFor({ name: name, entry: SKETCH }));
+    files[SKETCH] = text;
+    return normalizeFolderRow({ files: files, renderState: null });
+}
 
-    return { envelope: envelope, previewPngBytes: previewPngBytes };
+/**
+ * @param {Uint8Array} bytes
+ * @param {string} fileName — the imported file's name (a one-file sketch's basename is its project name)
+ * @returns {Readonly<{files: Object<string,string>, renderState: object}>}
+ */
+export function importArchive(bytes, fileName) {
+    if (!(bytes instanceof Uint8Array)) { _fail('importArchive(bytes, fileName): bytes is a Uint8Array.'); }
+    if (typeof fileName !== 'string' || fileName.length === 0) { _fail('importArchive(bytes, fileName): the file\'s name.'); }
+    if (_isZip(bytes)) { return _fromZip(bytes); }
+    var base = _baseName(fileName);
+    if (/\.mjs$/i.test(base)) {
+        var entryRule = MANIFEST_KEYS.filter(function (r) { return r.key === 'entry'; })[0].rule;
+        _fail('"' + base + '" is a .mjs module — a one-file Import takes a .js sketch, because a project\'s entry is ' +
+            entryRule + ' (frqtl.json, lib/shim/project/manifest.js MANIFEST_KEYS). Rename it to .js and import it again.');
+    }
+    var text = _text(bytes, '"' + base + '"');
+    if (/\.js$/.test(base)) { return _fromSketch(text, base); }
+    if (/\.json$/i.test(base) || /^\s*\{/.test(text)) { return _fromJson(text); }
+    _fail('"' + base + '" is not a project — Import takes a project archive (.zip, as an Export writes it) or one ' +
+        'sketch (.js).');
 }

package/dist/shim/bundle/indexHtml.js

@@ -1,21 +1,24 @@
 /* Copyright 2023-2026 by Essam Abadir */
 
 /**
- * lib/shim/bundle/indexHtml.js — the standalone `index.html` projection of a
- * recipe bundle.
+ * lib/shim/bundle/indexHtml.js — the generated `index.html` of an exported project folder: the HOST PAGE,
+ * and the ONE writer + ONE parser of the boot bag it carries.
  *
- * A byte-template host that boots the bundle folder as a SERVED PROJECT: `bootProject(mount,
- * { url: './', entry: 'experiment.js' }, { renderState })` from `@descix/frqtl-web@<pin>` on the CDN. The
- * recipe is a sketch module whose imports name the published self-reference (`@descix/frqtl-web/...`);
- * the page's import map carries those rows and the scene doors' row, rendered by the ONE table
- * (`pageImportMapFor(<the pinned dist root>/)`, lib/shim/project/specifiers.js), so the sketch resolves
- * to the SAME module URLs the boot loads. The pinned dist root is the router's one spelling
- * (`cdnDistBaseFor`); the `@<pin>` is the passed-in `sdkVersion` (DERIVED at export time — never a
- * literal here).
+ *   buildIndexHtml({ name, sdkVersion, renderState }) → the page text
+ *   readBootBag(html)                                  → the renderState it carries (the import's one reader)
+ *   BOOT_BAG_ID                                        'frqtl-boot' — the bag's element id
  *
- * DRY: `experiment.js` stays the ONE source of truth — the page links it where it is served rather than
- * embedding a second copy. `renderState` (small, manifest-derived) is embedded inline as JSON. A page
- * opened via `file://` cannot fetch the project: the error says to serve the folder over http.
+ * The page boots the folder it sits in as a SERVED PROJECT: `bootProject(mount, { url: './' }, { renderState })`
+ * from `@descix/frqtl-web@<pin>` on the CDN. `frqtl.json` names the entry (P2a: the linker reads it first), so
+ * the page names no file. The import map is the ONE table's (`pageImportMapFor(<the pinned dist root>/)`,
+ * lib/shim/project/specifiers.js), so a sketch's `@descix/frqtl-web/...` imports resolve to the same module URLs
+ * the boot loads. The pinned dist root is the router's one spelling (`cdnDistBaseFor`); the pin is the passed-in
+ * `sdkVersion` (derived at export time, never a literal here).
+ *
+ * The boot bag — the host's renderState, which never enters frqtl.json or the project identity — is embedded as
+ * `<script type="application/json" id="frqtl-boot">`, `<` escaped so no payload closes the element. The page reads
+ * it from that element; an Import reads it back with readBootBag and drops the page. A page opened via `file://`
+ * cannot fetch the folder: it says to serve the folder over http.
  *
  * Layer 2 (physics): none — pure host projection.
  */
@@ -25,41 +28,38 @@
 import { pageImportMapFor, FRQTL_WEB_BOOT } from '../project/specifiers.js';
 import { cdnDistBaseFor } from '../engine/router.js';
 
+/** The boot bag's element id. */
+export var BOOT_BAG_ID = 'frqtl-boot';
+
+var _BAG_OPEN = '<script type="application/json" id="' + BOOT_BAG_ID + '">';
+var _BAG_CLOSE = '</script>';
+
 function _escapeHtml(s) {
     return String(s == null ? '' : s)
         .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 
-/** Safe inline-JSON: escape `<` so a `</script>`-like payload can't break out. */
+/** Safe inline JSON: `<` escaped so a `</script>`-like payload cannot break out. */
 function _inlineJson(obj) {
     return JSON.stringify(obj == null ? null : obj).replace(/</g, '\\u003c');
 }
 
 /**
- * Build the standalone `index.html` for a recipe bundle.
- *
  * @param {object} args
- * @param {string} args.name        — project name (page title).
- * @param {string} args.sdkVersion  — the `@descix/frqtl-web@<pin>` version (REQUIRED).
- * @param {object} [args.renderState] — normalized renderState bag (inlined as JSON;
- *                                     forwarded to bootProject's `{renderState}`).
- * @param {string[]} [args.scripts] — the v4 envelope's setup-factory delta (inlined as JSON): nothing
- *                                     classic is left to load, so the page REFUSES a non-empty list at boot,
- *                                     naming the fix (import the factory in the sketch).
- * @param {string} [args.recipeFile='experiment.js'] — the project's entry file.
- * @returns {string} the complete `index.html`.
+ * @param {string} args.name        — the project's name (frqtl.json `name`; the page title)
+ * @param {string} args.sdkVersion  — the `@descix/frqtl-web@<pin>` version (REQUIRED)
+ * @param {object|null} args.renderState — the normalized boot bag (null boots with the page's defaults)
+ * @returns {string} the complete `index.html`
  */
 export function buildIndexHtml(args) {
     args = args || {};
     if (typeof args.sdkVersion !== 'string' || args.sdkVersion.length === 0) {
-        throw new Error('[bundle/indexHtml] buildIndexHtml: args.sdkVersion is REQUIRED (the CDN pin).');
+        throw new Error('[bundle/indexHtml] buildIndexHtml: args.sdkVersion is REQUIRED (the CDN pin). (FAIL-LOUD.)');
+    }
+    if (typeof args.name !== 'string' || args.name.length === 0) {
+        throw new Error('[bundle/indexHtml] buildIndexHtml: args.name is the project\'s frqtl.json name. (FAIL-LOUD.)');
     }
-    var name = (typeof args.name === 'string' && args.name.length > 0) ? args.name : 'FRQTL Recipe';
-    var recipeFile = (typeof args.recipeFile === 'string' && args.recipeFile.length > 0)
-        ? args.recipeFile : 'experiment.js';
     var importMapJson = _inlineJson(pageImportMapFor(cdnDistBaseFor(args.sdkVersion) + '/'));
-    var renderStateJson = _inlineJson(args.renderState || null);
-    var scriptsJson = _inlineJson(Array.isArray(args.scripts) ? args.scripts : []);
 
     return [
         '<!DOCTYPE html>',
@@ -67,7 +67,7 @@ export function buildIndexHtml(args) {
         '<head>',
         '  <meta charset="UTF-8">',
         '  <meta name="viewport" content="width=device-width, initial-scale=1">',
-        '  <title>' + _escapeHtml(name) + ' — FRQTL</title>',
+        '  <title>' + _escapeHtml(args.name) + ' — FRQTL</title>',
         '  <style>',
         '    html,body{margin:0;height:100%;background:#0b0b0f;color:#ddd;',
         '      font:14px/1.5 ui-sans-serif,system-ui,sans-serif;}',
@@ -80,23 +80,21 @@ export function buildIndexHtml(args) {
         '<body>',
         '  <div id="frqtl-mount"></div>',
         '  <pre id="frqtl-err"></pre>',
+        '  ' + _BAG_OPEN + _inlineJson(args.renderState) + _BAG_CLOSE,
         '  <script type="importmap">' + importMapJson + '</script>',
         '  <script type="module">',
         '    import { bootProject } from ' + JSON.stringify(FRQTL_WEB_BOOT.specifier) + ';',
-        '    const RENDER_STATE = ' + renderStateJson + ';',
-        '    const SCRIPTS = ' + scriptsJson + ';',
+        '    const renderState = JSON.parse(document.getElementById(' + JSON.stringify(BOOT_BAG_ID) + ').textContent);',
         '    const mount = document.getElementById("frqtl-mount");',
         '    const errBox = document.getElementById("frqtl-err");',
         '    function fail(title, detail){',
         '      errBox.style.display = "block";',
         '      errBox.textContent = title + "\\n\\n" + detail;',
         '    }',
-        '    if (SCRIPTS.length > 0) {',
-        '      fail("FRQTL project boot refused", "scripts " + JSON.stringify(SCRIPTS) + " is a classic setup-factory delta, and nothing classic is left to load — import the factory in the sketch (it imports what it uses from @descix/frqtl-web/...).");',
-        '    } else if (location.protocol === "file:") {',
-        '      fail("Serve this folder over http", "e.g. `npx serve` — a file:// page cannot fetch ' + _escapeHtml(recipeFile) + '.");',
+        '    if (location.protocol === "file:") {',
+        '      fail("Serve this folder over http", "e.g. `npx serve` — a file:// page cannot fetch the project files.");',
         '    } else {',
-        '      bootProject(mount, { url: new URL("./", location.href).href, entry: ' + JSON.stringify(recipeFile) + ' }, { renderState: RENDER_STATE })',
+        '      bootProject(mount, { url: new URL("./", location.href).href }, { renderState: renderState })',
         '        .catch((e) => fail("FRQTL project boot failed", String(e && e.stack || e)));',
         '    }',
         '  </script>',
@@ -105,3 +103,32 @@ export function buildIndexHtml(args) {
         ''
     ].join('\n');
 }
+
+/**
+ * THE parser of the boot bag: the renderState an exported page carries (null when it carries none).
+ * THROWS when the page holds no bag element, or more than one, or one that is not JSON.
+ * @param {string} html
+ * @returns {object|null}
+ */
+export function readBootBag(html) {
+    if (typeof html !== 'string') {
+        throw new Error('[bundle/indexHtml] readBootBag(html): the page text (got ' + typeof html + '). (FAIL-LOUD.)');
+    }
+    var at = html.indexOf(_BAG_OPEN);
+    if (at === -1) {
+        throw new Error('[bundle/indexHtml] the index.html carries no boot bag (<script type="application/json" id="' +
+            BOOT_BAG_ID + '">) — it is not the page an Export writes. (FAIL-LOUD.)');
+    }
+    if (html.indexOf(_BAG_OPEN, at + 1) !== -1) {
+        throw new Error('[bundle/indexHtml] the index.html carries two boot bags — an Export writes one. (FAIL-LOUD.)');
+    }
+    var start = at + _BAG_OPEN.length;
+    var end = html.indexOf(_BAG_CLOSE, start);
+    if (end === -1) {
+        throw new Error('[bundle/indexHtml] the boot bag element is not closed. (FAIL-LOUD.)');
+    }
+    try { return JSON.parse(html.slice(start, end)); }
+    catch (e) {
+        throw new Error('[bundle/indexHtml] the boot bag is not valid JSON: ' + ((e && e.message) || e) + '. (FAIL-LOUD.)');
+    }
+}

package/dist/shim/engine/router.js

@@ -148,7 +148,7 @@ var DIST_PROFILE = buildDistProfile('../..');
 // lib/shim/engine/test/router.test.mjs asserts them against the two
 // package.json#version fields so a forgotten bump fails `make verify`, not a
 // silent stale-CDN-URL bug.
-var CDN_SDK_VERSION = '0.6.0-p0.2';  // sdk/frqtl-web/package.json#version (the ONE version owner) — bound by router.test.mjs
+var CDN_SDK_VERSION = '0.6.0-p4.1';  // sdk/frqtl-web/package.json#version (the ONE version owner) — bound by router.test.mjs
 var CDN_MATH_SDK_VERSION = '0.3.2';  // sdk/egpt-math-sdk/package.json#version — bound by router.test.mjs; bumped with each npm publish
 
 /**
@@ -507,7 +507,7 @@ var _assertProfileParity = (function () {
  * // CDN mode (static hosting — the artifact host shell has no server, no page anchor):
  * const cdnRouter = engineRouter({ mode: 'cdn', engine: 'wasm' });
  * console.log(cdnRouter.resolve('compat/engine.js'));
- * // 'https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p0.2/dist/frqtl/compat/engine.js'
+ * // 'https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p4.1/dist/frqtl/compat/engine.js'
  *
  * // CDN mode, self-hosted: a copy of dist/ served from the consumer's own origin:
  * const selfHosted = engineRouter({ mode: 'cdn', engine: 'wasm', base: 'https://example.org/vendor/frqtl-web/dist' });

package/dist/shim/index.js

@@ -22,7 +22,7 @@ export { WALKTHROUGH, walkthroughIs3D, walkthroughModes, walkthroughGroup,
          walkthroughById,
          FIRST_CONTACT_WALKTHROUGH_ID,
          defaultWalkthroughModeId, effectiveRenderState } from './registry/walkthrough.js';
-export { loadSceneSource, scenePath, EMPTY_SCENE } from './registry/scene-source.js';
+export { projectOf, scenePath, EMPTY_SCENE } from './registry/scene-source.js';
 // The host-side experiment-iframe guard (the false-200 trap). Exported from the
 // barrel so every host that frames an experiment page (lib/features/ide's GYM)
 // asserts against the SAME contract.

package/dist/shim/notebook/format.js

@@ -99,7 +99,7 @@ export const PROSE_CELL_TYPES = Object.freeze(['markdown']);
  *       e.g. `setupDoubleSlit`). Absent → `'factory'`, so every existing notebook is
  *       byte-identical.
  *     - `'recipe'`: the module's DEFAULT export is a `buildExperiment(exp)` RECIPE (a single
- *       RecipeContext arg — the sketch form codegen / `buildFrqnb` / the scene files
+ *       RecipeContext arg — the sketch form the scene files
  *       write). The shim builds a
  *       `frqtl.RecipeContext` and runs `exp.build(buildExperiment)` (the canonical
  *       co-init call + `addObject()` recipe path), NOT the factory signature.

package/dist/shim/notebook/store.js

@@ -5,9 +5,8 @@
  *
  * Thin CRUD helpers that persist a serialized <frqtl-notebook> document on top
  * of any StorageProvider (lib/shim/storage/index.js) using the "notebooks"
- * namespace.  Mirrors the shape of lib/shim/storage/modules.js and
- * lib/shim/storage/projects.js — ONE persistent-store pattern across Studio
- * projects, Studio modules, and Notebooks.
+ * namespace, through the shared namespace-CRUD factory
+ * (lib/shim/storage/make-namespace-store.js).
  *
  * ── Why this lives in lib/shim ──────────────────────────────────────────────
  *

package/dist/shim/page-params/index.js

@@ -185,8 +185,8 @@ var HOST_TOKENS = Object.freeze([
         why: 'chrome is a HOST-COMPOSITION decision (whether the experiment\'s own ' +
              'control chrome DOM renders), never a per-experiment physics/render ' +
              'parameter; forwarding it from an outer host URL into an embedded ' +
-             'iframe would reintroduce the hidden-experiment-chrome bug fixed in ' +
-             'WS gym-controls-as-sugar Bite 2 (the GYM must always show the ' +
+             'iframe would reintroduce the hidden-experiment-chrome bug (the GYM ' +
+             'must always show the ' +
              'experiment\'s own full chrome, never chrome=canvas — see the ' +
              '"WHEN should a host set chrome=canvas" doc above for the general ' +
              'criterion, not just the GYM\'s specific answer to it)'