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

package/dist/shim/render-state/apply.js

@@ -31,13 +31,14 @@
  *                  `runner.updateObjectProperty(lo, 'visible', v)`, backdrop:v. An ABSENT
  *                  `backdropVisible` (null after normalizing) is not written — the scene's own
  *                  `addBackdrop(…, {visible})` rules — and reports backdrop:null, as does no backdrop LO.
- *       `pageControls` are NOT applied here: they are STUDIO's host-specific override.
+ *       Page controls are not state: a sketch declares them in its own code.
  *
  *   backdropOf(runner)                   — THE answer to "which LO is the backdrop" for a host: the
  *                                          census LO marked `backdrop === true`, or null. STUDIO's
  *                                          save captures its visibility through it, so capture and
  *                                          replay read one fact.
- *   normalizeSavedRenderState(raw)       — tolerant normalizer for a LOADED bag (never throws).
+ *   normalizeSavedRenderState(raw)       — tolerant normalizer for a LOADED bag; THROWS only on a bag
+ *                                          that carries page controls (they are author code now).
  *   pickCameraReplay(saved)              — pure decision: named preset over raw orbit.
  *   partitionRenderRows(rows, declared, known) — apply / retain / throw, before anything is written.
  *   renderRowsFromBag(bag)               — a { key: value } render-option bag as ordered rows.
@@ -83,12 +84,18 @@ function pickCameraReplay(saved) {
  *   seed: string|null,
  *   backdropVisible: boolean|null,
  *   camera: {orbit:object|null, preset:string|null}|null,
- *   render: {key:string, value:*}[],
- *   pageControls: {id:string, value:*, bind:{object:string,prop:string}|null}[]
+ *   render: {key:string, value:*}[]
  * }}
+ * @throws {Error} a bag whose `pageControls` holds a row — page controls are declared in the sketch's own
+ *   code, so a saved bag never carries them; migrate the project (move the controls into its sketch).
  */
 function normalizeSavedRenderState(raw) {
     var r = _isPlainObject(raw) ? raw : {};
+    if (Array.isArray(r.pageControls) && r.pageControls.length > 0) {
+        throw new Error('[render-state] this saved project carries page controls (renderState.pageControls: ' +
+            r.pageControls.map(function (row) { return _isPlainObject(row) ? String(row.id) : '?'; }).join(', ') +
+            ') — page controls are declared in the sketch\'s own code; move them into the sketch and save again. (FAIL-LOUD.)');
+    }
     var camera = null;
     if (_isPlainObject(r.camera)) {
         camera = {
@@ -105,16 +112,6 @@ function normalizeSavedRenderState(raw) {
         camera: camera,
         render: Array.isArray(r.render) ? r.render.filter(function (row) {
             return _isPlainObject(row) && typeof row.key === 'string' && row.key.length > 0;
-        }) : [],
-        pageControls: Array.isArray(r.pageControls) ? r.pageControls.filter(function (row) {
-            return _isPlainObject(row) && typeof row.id === 'string' && row.id.length > 0;
-        }).map(function (row) {
-            return {
-                id: row.id,
-                value: row.value,
-                bind: (_isPlainObject(row.bind) && typeof row.bind.object === 'string' &&
-                       typeof row.bind.prop === 'string') ? { object: row.bind.object, prop: row.bind.prop } : null
-            };
         }) : []
     };
 }

package/dist/shim/storage/codec-chains.js

@@ -0,0 +1,88 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/storage/codec-chains.js — THE owner of a ROSETTA codec chain saved in browser storage.
+ *
+ * A codec chain is one module text (the codec page's `chainToModule` output) under a name. It is not a sketch
+ * project (frqtl.json is "kind": "scene"), so it has its own small store:
+ *
+ *   CODEC_CHAINS_NAMESPACE = 'codec-chains'
+ *   CODEC_CHAIN_KEYS       = ['name', 'source']   the stored row, keyed by `name`
+ *
+ *   saveChain(provider, row)              → name   Save: write under its own name (overwrites)
+ *   saveChainAs(provider, row, newName)   → newName Save As: REFUSED when newName is taken
+ *   loadChain(provider, name)             → row | null
+ *   listChains(provider)                  → [{ name }] ascending
+ *   deleteChain(provider, name)
+ *
+ * The name follows the storage seam's key rule (index.js checkStorageKey), as a project folder's does. The
+ * codec page's deep link `?module=<name>` is a key of this namespace.
+ *
+ * FAIL-LOUD. Layer 2 (physics): none.
+ */
+
+'use strict';
+
+import { checkStorageKey } from './index.js';
+
+export var CODEC_CHAINS_NAMESPACE = 'codec-chains';
+export var CODEC_CHAIN_KEYS = Object.freeze(['name', 'source']);
+
+function _fail(msg) {
+    throw new Error('[codec-chains] ' + msg + ' (FAIL-LOUD.)');
+}
+
+/** @returns {Readonly<{name: string, source: string}>} */
+export function normalizeChainRow(row) {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) {
+        _fail('a codec chain row is { ' + CODEC_CHAIN_KEYS.join(', ') + ' } (got ' + (row === null ? 'null' : typeof row) + ').');
+    }
+    var unknown = Object.keys(row).filter(function (k) { return CODEC_CHAIN_KEYS.indexOf(k) === -1; });
+    if (unknown.length) {
+        _fail('unknown key ' + unknown.map(function (k) { return JSON.stringify(k); }).join(', ') +
+            ' — a codec chain row holds exactly CODEC_CHAIN_KEYS: ' + CODEC_CHAIN_KEYS.join(', ') + '.');
+    }
+    checkStorageKey(row.name, 'a codec chain name');
+    if (typeof row.source !== 'string' || row.source.length === 0) {
+        _fail('"source" is the chain\'s module text, a non-empty string.');
+    }
+    return Object.freeze({ name: row.name, source: row.source });
+}
+
+export function saveChain(provider, row) {
+    var n = normalizeChainRow(row);
+    provider.put(CODEC_CHAINS_NAMESPACE, n.name, { name: n.name, source: n.source });
+    return n.name;
+}
+
+export function saveChainAs(provider, row, newName) {
+    checkStorageKey(newName, 'a codec chain name');
+    var n = normalizeChainRow(Object.assign({}, row, { name: newName }));
+    if (provider.get(CODEC_CHAINS_NAMESPACE, newName) !== null) {
+        _fail('a codec chain named "' + newName + '" is already saved — Save As takes a name no saved chain has.');
+    }
+    provider.put(CODEC_CHAINS_NAMESPACE, n.name, { name: n.name, source: n.source });
+    return n.name;
+}
+
+export function loadChain(provider, name) {
+    checkStorageKey(name, 'a codec chain name');
+    var raw = provider.get(CODEC_CHAINS_NAMESPACE, name);
+    if (raw === null || raw === undefined) { return null; }
+    var row;
+    try { row = normalizeChainRow(raw); }
+    catch (e) { _fail('the saved chain "' + name + '" is not a codec chain row: ' + ((e && e.message) || e)); }
+    if (row.name !== name) { _fail('the saved chain under "' + name + '" names itself "' + row.name + '".'); }
+    return row;
+}
+
+export function listChains(provider) {
+    return provider.list(CODEC_CHAINS_NAMESPACE).map(function (e) { return e.key; }).sort().map(function (k) {
+        return { name: k };
+    });
+}
+
+export function deleteChain(provider, name) {
+    checkStorageKey(name, 'a codec chain name');
+    provider['delete'](CODEC_CHAINS_NAMESPACE, name);
+}

package/dist/shim/storage/folders.js

@@ -0,0 +1,205 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/storage/folders.js — THE owner of a project saved in browser storage: one project = one folder.
+ *
+ * A project is a folder of files: `frqtl.json` (its owner is
+ * lib/shim/project/manifest.js), the entry sketch it names, and whatever else the author keeps beside them.
+ * The stored ROW is the folder plus the host's boot bag, and nothing else:
+ *
+ *   FOLDER_ROW_KEYS = ['files', 'renderState']
+ *     files        { path: text } — text only (a binary value is refused by name); every path through
+ *                  lib/shim/project/identity.js checkProjectPath, the one path rule; a root `index.html` is
+ *                  refused (EXPORT_PAGE: the Export writes it); `frqtl.json` is required and read by its owner.
+ *     renderState  the host's boot bag (STUDIO's capture, a rung's effectiveRenderState), normalized by its one
+ *                  owner (lib/shim/render-state normalizeSavedRenderState) and ferried — never re-listed here.
+ *                  Boot facts live beside the folder, never in frqtl.json.
+ *
+ * The key is the manifest `name`, in FOLDERS_NAMESPACE. Exports:
+ *
+ *   normalizeFolderRow(row)                    → the frozen row (the one validation every reader and writer uses)
+ *   folderNameOf(row)                          → its frqtl.json name
+ *   saveFolder(provider, row)                  → name   Save: write the folder under its own name (overwrites)
+ *   saveFolderAs(provider, row, newName)       → newName Save As: frqtl.json's name rewritten through
+ *                                                serializeManifest; REFUSED when newName is taken
+ *   copyFolder(provider, name, newName)        → newName a stored folder copied (saveFolderAs over loadFolder)
+ *   loadFolder(provider, name)                 → row | null
+ *   listFolders(provider)                      → [{ name }] in ascending name order
+ *   deleteFolder(provider, name)
+ *
+ * Retired saves (DESCIX IS NOT LIVE; there is no migration tool): the namespaces RETIRED_NAMESPACES (owned by
+ * the storage seam, index.js, which refuses a write into one) held the v4 module envelope and the design
+ * envelope. They are never read and never converted:
+ *
+ *   retiredSaves(provider)                     → [{ namespace, key }] — every key in a retired namespace
+ *   deleteRetiredSaves(provider, saves)        → the count deleted — EXACTLY the listed keys (each must be in a
+ *                                                retired namespace); nothing else is touched
+ *
+ * FAIL-LOUD: every refusal names the rule it applies. Layer 2 (physics): none — this stores text.
+ */
+
+'use strict';
+
+import { RETIRED_NAMESPACES, checkStorageKey } from './index.js';
+import { checkProjectPath } from '../project/identity.js';
+import { MANIFEST_FILE, parseManifest, serializeManifest } from '../project/manifest.js';
+import { normalizeSavedRenderState } from '../render-state/index.js';
+
+export { RETIRED_NAMESPACES };
+
+/** The storage namespace every project folder is saved under. */
+export var FOLDERS_NAMESPACE = 'project-folders';
+
+/** The stored row's keys — the folder and the host's boot bag. */
+export var FOLDER_ROW_KEYS = Object.freeze(['files', 'renderState']);
+
+/** The root page the Export generates (lib/shim/bundle) — reserved, so a folder never holds one. */
+export var EXPORT_PAGE = 'index.html';
+
+function _fail(msg) {
+    throw new Error('[folders] ' + msg + ' (FAIL-LOUD.)');
+}
+
+function _isPlainObject(v) { return !!v && typeof v === 'object' && !Array.isArray(v); }
+
+/**
+ * @param {{files: Object<string,string>, renderState?: object|null}} row
+ * @returns {Readonly<{files: Readonly<Object<string,string>>, renderState: object}>}
+ */
+export function normalizeFolderRow(row) {
+    if (!_isPlainObject(row)) {
+        _fail('a project folder row is { ' + FOLDER_ROW_KEYS.join(', ') + ' } (got ' +
+            (row === null ? 'null' : Array.isArray(row) ? 'an array' : typeof row) + ').');
+    }
+    var unknown = Object.keys(row).filter(function (k) { return FOLDER_ROW_KEYS.indexOf(k) === -1; });
+    if (unknown.length) {
+        _fail('unknown key ' + unknown.map(function (k) { return JSON.stringify(k); }).join(', ') +
+            ' — a project folder row holds exactly FOLDER_ROW_KEYS (lib/shim/storage/folders.js): ' +
+            FOLDER_ROW_KEYS.join(', ') + '.');
+    }
+    var files = row.files;
+    if (!_isPlainObject(files) || Object.keys(files).length === 0) {
+        _fail('"files" is the folder { path: text } with at least ' + MANIFEST_FILE + ' (got ' +
+            (_isPlainObject(files) ? 'an empty map' : typeof files) + ').');
+    }
+    var out = {};
+    Object.keys(files).forEach(function (p) {
+        checkProjectPath(p);
+        if (p === EXPORT_PAGE) {
+            _fail('"' + EXPORT_PAGE + '" at the folder root is reserved — the Export generates it (the host page ' +
+                'that carries the boot bag); a project folder never holds one.');
+        }
+        if (typeof files[p] !== 'string') {
+            _fail('"' + p + '" is not text (got ' + (files[p] instanceof Uint8Array ? 'bytes' : typeof files[p]) +
+                ') — a project folder holds text files only.');
+        }
+        out[p] = files[p];
+    });
+    if (typeof out[MANIFEST_FILE] !== 'string') {
+        _fail('the folder carries no ' + MANIFEST_FILE + ' — a project folder is named and entered by its manifest ' +
+            '(lib/shim/project/manifest.js manifestFor({ name, entry }) writes one).');
+    }
+    var name = parseManifest(out[MANIFEST_FILE]).name;
+    checkStorageKey(name, 'a project folder name (frqtl.json "name")');
+    return Object.freeze({ files: Object.freeze(out), renderState: normalizeSavedRenderState(row.renderState) });
+}
+
+/** @param {object} row @returns {string} the folder's frqtl.json name */
+export function folderNameOf(row) {
+    return parseManifest(normalizeFolderRow(row).files[MANIFEST_FILE]).name;
+}
+
+function _stored(row) {
+    return { files: Object.assign({}, row.files), renderState: row.renderState };
+}
+
+/**
+ * Save: write the folder under its own frqtl.json name, overwriting that name's folder.
+ * @returns {string} the name
+ */
+export function saveFolder(provider, row) {
+    var n = normalizeFolderRow(row);
+    var name = parseManifest(n.files[MANIFEST_FILE]).name;
+    provider.put(FOLDERS_NAMESPACE, name, _stored(n));
+    return name;
+}
+
+/**
+ * Save As: the folder under `newName` — frqtl.json's name rewritten through serializeManifest (the one writer).
+ * REFUSED when a folder named `newName` is already saved.
+ * @returns {string} newName
+ */
+export function saveFolderAs(provider, row, newName) {
+    checkStorageKey(newName, 'a project folder name');
+    var n = normalizeFolderRow(row);
+    if (provider.get(FOLDERS_NAMESPACE, newName) !== null) {
+        _fail('a project named "' + newName + '" is already saved — Save As takes a name no saved project has ' +
+            '(choose another, or delete the saved one first).');
+    }
+    var files = Object.assign({}, n.files);
+    files[MANIFEST_FILE] = serializeManifest(Object.assign({}, parseManifest(n.files[MANIFEST_FILE]), { name: newName }));
+    var renamed = normalizeFolderRow({ files: files, renderState: n.renderState });
+    provider.put(FOLDERS_NAMESPACE, newName, _stored(renamed));
+    return newName;
+}
+
+/** A stored folder copied under `newName` (frqtl.json's name rewritten); refuses a taken name or a missing source. */
+export function copyFolder(provider, name, newName) {
+    var row = loadFolder(provider, name);
+    if (!row) { _fail('no saved project named "' + name + '" to copy.'); }
+    return saveFolderAs(provider, row, newName);
+}
+
+/** @returns {Readonly<object>|null} the normalized row, or null when no folder has that name */
+export function loadFolder(provider, name) {
+    checkStorageKey(name, 'a project folder name');
+    var raw = provider.get(FOLDERS_NAMESPACE, name);
+    if (raw === null || raw === undefined) { return null; }
+    var row;
+    try { row = normalizeFolderRow(raw); }
+    catch (e) { _fail('the saved project "' + name + '" is not a project folder row: ' + ((e && e.message) || e)); }
+    var stored = parseManifest(row.files[MANIFEST_FILE]).name;
+    if (stored !== name) {
+        _fail('the saved project under "' + name + '" names itself "' + stored + '" in ' + MANIFEST_FILE +
+            ' — a folder is keyed by its manifest name.');
+    }
+    return row;
+}
+
+/** @returns {Array<{name: string}>} every saved folder, ascending by name */
+export function listFolders(provider) {
+    return provider.list(FOLDERS_NAMESPACE).map(function (e) { return e.key; }).sort().map(function (k) {
+        return { name: k };
+    });
+}
+
+export function deleteFolder(provider, name) {
+    checkStorageKey(name, 'a project folder name');
+    provider['delete'](FOLDERS_NAMESPACE, name);
+}
+
+/** @returns {Array<{namespace: string, key: string}>} every key in a retired namespace (never read) */
+export function retiredSaves(provider) {
+    var out = [];
+    RETIRED_NAMESPACES.forEach(function (ns) {
+        provider.list(ns).forEach(function (e) { out.push({ namespace: ns, key: e.key }); });
+    });
+    return out;
+}
+
+/**
+ * Delete exactly `saves` (retiredSaves' rows); a row outside a retired namespace is refused before anything
+ * is deleted.
+ * @returns {number} the count deleted
+ */
+export function deleteRetiredSaves(provider, saves) {
+    if (!Array.isArray(saves)) { _fail('deleteRetiredSaves(provider, saves): saves is retiredSaves(provider)\'s list.'); }
+    saves.forEach(function (s) {
+        if (!s || RETIRED_NAMESPACES.indexOf(s.namespace) === -1 || typeof s.key !== 'string') {
+            _fail('deleteRetiredSaves deletes only retired saves ({ namespace in [' + RETIRED_NAMESPACES.join(', ') +
+                '], key }) — got ' + JSON.stringify(s) + '.');
+        }
+    });
+    saves.forEach(function (s) { provider['delete'](s.namespace, s.key); });
+    return saves.length;
+}

package/dist/shim/storage/index.js

@@ -45,16 +45,27 @@
  *   // Then anywhere in the IDE:
  *   import { getProvider } from 'lib/shim/storage';
  *   const storage = getProvider();
- *   storage.put('projects', 'abc123', { name: 'My project' });
- *   const saved = storage.get('projects', 'abc123');
- *   const all   = storage.list('projects');
- *   storage.delete('projects', 'abc123');
+ *   storage.put('explainers', 'gym', { seen: true });
+ *   const saved = storage.get('explainers', 'gym');
+ *   const all   = storage.list('explainers');
+ *   storage.delete('explainers', 'gym');
  *
  * ── Contract validation ─────────────────────────────────────────────────────
  *
  *   validateProvider(provider) — throws if provider does not implement the
  *     contract.  Called by setActiveProvider; consumers may also call it.
  *
+ * ── Retired namespaces ──────────────────────────────────────────────────────
+ *
+ *   RETIRED_NAMESPACES — the namespaces of the retired save formats ('files': the v4 module
+ *     envelope STUDIO and ROSETTA wrote; 'projects': the opaque design envelope). The project
+ *     folder (folders.js) and the codec chain (codec-chains.js) replaced them. The active provider
+ *     (getProvider) REFUSES a write into one, naming the replacement; reads, lists and deletes go
+ *     through, so the retired-saves strip can name them and delete exactly them (folders.js
+ *     retiredSaves / deleteRetiredSaves). Nothing reads or converts their rows.
+ *   checkStorageKey(key, what) — THE key rule of a store keyed by a name (a project folder's
+ *     frqtl.json name, a codec chain's name): a non-empty string with no "/" (reserved).
+ *
  * ── Server-side seam ───────────────────────────────────────────────────────
  *
  *   The matching server routes are defined in lib/server/mounts.js under
@@ -69,6 +80,49 @@
 
 /** @type {StorageProvider|null} */
 var _activeProvider = null;
+/** @type {StorageProvider|null} the active provider behind the retired-namespace write guard */
+var _activeGuard = null;
+
+/** The namespaces of the retired save formats — written by nothing (see the header). */
+export var RETIRED_NAMESPACES = Object.freeze(['files', 'projects']);
+
+var _RETIRED_BY = Object.freeze({
+  files:    'the project folder (lib/shim/storage/folders.js, namespace "project-folders") for a STUDIO save, ' +
+            'the codec chain (lib/shim/storage/codec-chains.js, namespace "codec-chains") for a ROSETTA save',
+  projects: 'the project folder (lib/shim/storage/folders.js, namespace "project-folders")'
+});
+
+/**
+ * THE key rule of a store keyed by a name: a non-empty string with no "/" (reserved by the contract).
+ * @param {*} key
+ * @param {string} what — the store's noun, for the message (e.g. 'a project folder name')
+ * @throws {Error}
+ */
+export function checkStorageKey(key, what) {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new Error('[StorageProvider] ' + what + ' is a non-empty string (got ' + JSON.stringify(key) + '). (FAIL-LOUD.)');
+  }
+  if (key.indexOf('/') !== -1) {
+    throw new Error('[StorageProvider] ' + what + ' ' + JSON.stringify(key) + ' contains "/" — "/" is reserved ' +
+      'in a storage key; name it without one. (FAIL-LOUD.)');
+  }
+}
+
+function _guarded(provider) {
+  return Object.freeze({
+    get: function (namespace, key) { return provider.get(namespace, key); },
+    put: function (namespace, key, value) {
+      if (RETIRED_NAMESPACES.indexOf(namespace) !== -1) {
+        throw new Error('[StorageProvider] a write into the retired namespace "' + namespace + '" (key ' +
+          JSON.stringify(key) + ') is refused — that save format is retired; ' + _RETIRED_BY[namespace] +
+          ' replaced it. (FAIL-LOUD.)');
+      }
+      return provider.put(namespace, key, value);
+    },
+    'delete': function (namespace, key) { return provider['delete'](namespace, key); },
+    list: function (namespace) { return provider.list(namespace); }
+  });
+}
 
 // ── Contract typedefs ──────────────────────────────────────────────────────
 
@@ -129,10 +183,11 @@ export function validateProvider(provider) {
 export function setActiveProvider(provider) {
   validateProvider(provider);
   _activeProvider = provider;
+  _activeGuard = _guarded(provider);
 }
 
 /**
- * Retrieve the active storage driver.
+ * Retrieve the active storage driver, behind the retired-namespace write guard (RETIRED_NAMESPACES).
  * FAIL-LOUD: throws if no provider has been registered.
  *
  * @returns {StorageProvider}
@@ -146,18 +201,18 @@ export function getProvider() {
       'for a non-browser driver.'
     );
   }
-  return _activeProvider;
+  return _activeGuard;
 }
 
 /**
- * Return the active provider, or null if none has been registered.
+ * Return the active provider (behind the same guard), or null if none has been registered.
  * Use this instead of getProvider() when a nil-safe check is appropriate
  * (e.g. during test setup before a provider is wired).
  *
  * @returns {StorageProvider|null}
  */
 export function peekProvider() {
-  return _activeProvider;
+  return _activeGuard;
 }
 
 /**
@@ -166,4 +221,5 @@ export function peekProvider() {
  */
 export function resetProvider() {
   _activeProvider = null;
+  _activeGuard = null;
 }

package/dist/shim/storage/make-namespace-store.js

@@ -3,9 +3,9 @@
 /**
  * lib/shim/storage/make-namespace-store.js — Generic namespace-CRUD factory.
  *
- * Factors out the byte-identical pattern shared by modules.js, projects.js,
- * and lib/shim/notebook/store.js.  Each of those files is a thin config call
- * over this factory; the public-API exports they expose are unchanged.
+ * The id-keyed record store lib/shim/notebook/store.js is a thin config call
+ * over. (A project folder and a codec chain are keyed by NAME and have their
+ * own owners: folders.js, codec-chains.js.)
  *
  * ── Signature ──────────────────────────────────────────────────────────────
  *
@@ -13,12 +13,12 @@
  *
  * ── Config ─────────────────────────────────────────────────────────────────
  *
- *   namespace      {string}    — StorageProvider namespace key (e.g. 'files').
+ *   namespace      {string}    — StorageProvider namespace key (e.g. 'notebooks').
  *   schemaVersion  {number}    — Current schema version integer (stamped on save
  *                                by callers; used here only in the returned
  *                                constant — actual stamping is the caller's job,
  *                                as in the originals).
- *   idPrefix       {string}    — Prefix for generated ids (e.g. 'mod_').
+ *   idPrefix       {string}    — Prefix for generated ids (e.g. 'nb_').
  *   validate       {function}  — validate(record): throws on invalid envelope.
  *   summaryFields  {function}  — summaryFields(record) → summary object, or
  *                                returns null to silently skip the record.

package/llms.txt

@@ -1,12 +1,12 @@
 # @descix/frqtl-node
 
 > The FRQTL physics engine (compiled Rust → WASM) for node: the same modules as @descix/frqtl-web, plus
-> `bootNode` and the hosted eyes. Pre-release 0.6.0-p0.2 on npm dist-tag `next`. Node ≥ 22.12.
+> `bootNode` and the hosted eyes. Pre-release 0.6.0-p4.1 on npm dist-tag `next`. Node ≥ 22.12.
 
 - Install: `npm install @descix/frqtl-node@next`
 - `import { bootNode, Wall } from '@descix/frqtl-node'` (require() works too); `await bootNode()` → the engine handle.
 - `./eyes`: `openHostedEyes({ sceneRecord, sceneSource: { kind: 'project', files, entry }, pageUrl })`.
 - `./project`: `linkProject` links a scene file against this package's own copy.
 - `./register`: `node --import @descix/frqtl-node/register scene.mjs` resolves a scene's `@descix/frqtl-web/...` imports to this package.
-- Full agent guide: https://cdn.jsdelivr.net/npm/@descix/frqtl-node@0.6.0-p0.2/CLAUDE.md
+- Full agent guide: https://cdn.jsdelivr.net/npm/@descix/frqtl-node@0.6.0-p4.1/CLAUDE.md
 - Acceptance is visual; no CLI ships. No account, credits or tokens are needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/frqtl-node",
-  "version": "0.6.0-p0.2",
+  "version": "0.6.0-p4.1",
   "description": "FRQTL for node \u2014 the discrete fractal physics engine (compiled Rust \u2192 WASM), its parts as ES modules, the node engine door (bootNode) and the hosted eyes.",
   "type": "module",
   "engines": {

package/dist/shim/bundle/frqnb.js

@@ -1,112 +0,0 @@
-/* Copyright 2023-2026 by Essam Abadir */
-
-/**
- * lib/shim/bundle/frqnb.js — the `.frqnb` teaching/gallery projection of a
- * recipe bundle.
- *
- * Builds a notebook OBJECT (never hand-emitted `<cell>` markup) and serializes
- * it THROUGH `lib/shim/notebook/format.js` `serialize` — the ONE notebook
- * serializer (no second serializer, no CELL_ATTRS mirror). The projection is:
- *
- *   1. markdown prose cell — title + teaching blurb.
- *   2. module cell (name './experiment.js') — carries the recipe source verbatim.
- *   3. canvas cell — wired to '<module>' (a recipe is the module's default export), carrying the render
- *      intent (stage/seed/render3d/cameraPreset/renderOptions) ferried from the
- *      normalized renderState bag.
- *
- * Because it serializes through format.js, ANY new CELL_ATTR added there flows
- * through this projection automatically — the conformance gate asserts it.
- *
- * The canvas cell carries `shape="recipe"` (the CELL_ATTRS discriminator owned by format.js):
- * the module's default export is a RecipeContext recipe (its co-init call + `exp.addObject`), and
- * the shim's setup-builder synthesizes `frqtl.RecipeContext` + `exp.build(buildExperiment)` for it.
- *
- * Layer 2 (physics): none — pure notebook projection.
- */
-
-'use strict';
-
-import { serialize } from '../notebook/format.js';
-
-var MODULE_NAME = './experiment.js';
-var CANVAS_ID   = 'c-recipe';
-
-/**
- * Fold a normalized renderState `render` array ([{key,value}]) into a plain
- * `{key: value}` bag for the canvas cell's `renderOptions` (CELL_ATTRS 'opts' kind).
- * @param {{key:string,value:*}[]} render
- * @returns {object}
- */
-function _renderOptionsBag(render) {
-    var bag = {};
-    if (Array.isArray(render)) {
-        for (var i = 0; i < render.length; i++) {
-            var row = render[i];
-            if (row && typeof row.key === 'string' && row.key.length > 0) {
-                bag[row.key] = row.value;
-            }
-        }
-    }
-    return bag;
-}
-
-/**
- * Build the `.frqnb` notebook string for a recipe bundle.
- *
- * @param {object} args
- * @param {string} args.name          — human-readable project name (notebook title + markdown heading).
- * @param {string} args.source        — the `experiment.js` recipe source (module cell body).
- * @param {object} [args.renderState] — a NORMALIZED renderState bag (from
- *   `lib/shim/render-state` normalizeSavedRenderState). Render intent is ferried
- *   onto the canvas cell; absent → the canvas carries stage/seed defaults only.
- * @param {string} [args.stage='600x400'] — canvas stage '<W>x<H>'.
- * @param {string} [args.prose]       — optional teaching blurb appended under the heading.
- * @returns {string} the serialized `.frqnb` notebook.
- */
-export function buildFrqnb(args) {
-    args = args || {};
-    if (typeof args.source !== 'string' || args.source.length === 0) {
-        throw new Error('[bundle/frqnb] buildFrqnb: args.source (experiment.js) is required.');
-    }
-    var name = (typeof args.name === 'string' && args.name.length > 0) ? args.name : 'FRQTL Recipe';
-    var rs = args.renderState || {};
-    var stage = (typeof args.stage === 'string' && args.stage.length > 0) ? args.stage : '600x400';
-    var seed = (rs.seed != null && rs.seed !== '') ? String(rs.seed) : '42';
-
-    var markdownBody = '# ' + name + '\n\n' +
-        (typeof args.prose === 'string' && args.prose.length > 0
-            ? args.prose
-            : 'A FRQTL recipe. The module cell below is the `experiment.js` source of truth; ' +
-              'the canvas runs it live.');
-
-    var canvasCell = {
-        type: 'canvas',
-        id: CANVAS_ID,
-        setup: MODULE_NAME,
-        // The module's DEFAULT export is a `buildExperiment(exp)` RECIPE (RecipeContext
-        // form), NOT a `(frqtl,universe,options)` setup factory — declare it so the
-        // shim synthesizes the RecipeContext path (a recipe canvas names no export).
-        shape: 'recipe',
-        stage: stage,
-        seed: seed
-    };
-    // Ferry render intent from the normalized renderState bag onto the canvas cell.
-    if (rs.renderer === 'three') { canvasCell.render3d = true; }   // three IS the 3D display
-    if (rs.camera && typeof rs.camera.preset === 'string' && rs.camera.preset.length > 0) {
-        canvasCell.cameraPreset = rs.camera.preset;
-    }
-    var renderOptions = _renderOptionsBag(rs.render);
-    if (Object.keys(renderOptions).length > 0) { canvasCell.renderOptions = renderOptions; }
-
-    var notebook = {
-        version: '1',
-        title: name,
-        cells: [
-            { type: 'markdown', body: markdownBody },
-            { type: 'module', name: MODULE_NAME, body: args.source },
-            canvasCell
-        ]
-    };
-
-    return serialize(notebook);
-}