@descix/frqtl-node 0.0.0-stage → 0.6.0-p0.1

package/dist/shim/bundle/frqnb.js

@@ -0,0 +1,112 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/bundle/frqnb.js — the `.frqnb` teaching/gallery projection of a
+ * recipe bundle (ws-experiments-walkthrough Bite 2).
+ *
+ * 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 Bite-2 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,
+        // Bite 5c: 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);
+}

package/dist/shim/bundle/index.js

@@ -0,0 +1,121 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/bundle/index.js — the recipe-bundle assembler + importer
+ * (ws-experiments-walkthrough Bite 2). The canonical owner of the bundle format
+ * (design §2): a folder that zips for download —
+ *
+ *   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
+ *
+ * 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.
+ *
+ * Layer 2 (physics): none — pure format/packaging.
+ */
+
+'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';
+
+// ── 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';
+
+/**
+ * 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 manifest = buildManifest(envelope, {
+        sdkVersion: opts.sdkVersion,
+        preview: preview ? FILE_PREVIEW_PNG : null
+    });
+
+    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) };
+}
+
+/**
+ * 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}}
+ */
+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; }
+
+    if (!byName[FILE_MANIFEST_JSON]) {
+        throw new Error('[bundle] importBundle: ' + FILE_MANIFEST_JSON + ' missing from the archive.');
+    }
+    if (!byName[FILE_EXPERIMENT_JS]) {
+        throw new Error('[bundle] importBundle: ' + FILE_EXPERIMENT_JS + ' missing from the archive.');
+    }
+
+    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));
+    }
+    var source = bytesText(byName[FILE_EXPERIMENT_JS]);
+    var envelope = manifestToEnvelope(manifest, source);
+    var previewPngBytes = byName[FILE_PREVIEW_PNG] || null;
+
+    return { envelope: envelope, previewPngBytes: previewPngBytes };
+}

package/dist/shim/bundle/indexHtml.js

@@ -0,0 +1,107 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/bundle/indexHtml.js — the standalone `index.html` projection of a
+ * recipe bundle.
+ *
+ * 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).
+ *
+ * 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.
+ *
+ * Layer 2 (physics): none — pure host projection.
+ */
+
+'use strict';
+
+import { pageImportMapFor, FRQTL_WEB_BOOT } from '../project/specifiers.js';
+import { cdnDistBaseFor } from '../engine/router.js';
+
+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. */
+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`.
+ */
+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).');
+    }
+    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>',
+        '<html lang="en">',
+        '<head>',
+        '  <meta charset="UTF-8">',
+        '  <meta name="viewport" content="width=device-width, initial-scale=1">',
+        '  <title>' + _escapeHtml(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;}',
+        '    #frqtl-mount{position:relative;width:100vw;height:100vh;}',
+        '    #frqtl-err{position:absolute;inset:0;padding:16px;white-space:pre-wrap;',
+        '      font:12px/1.5 ui-monospace,Menlo,Consolas,monospace;color:#ff6b6b;',
+        '      background:#1a0000;display:none;overflow:auto;}',
+        '  </style>',
+        '</head>',
+        '<body>',
+        '  <div id="frqtl-mount"></div>',
+        '  <pre id="frqtl-err"></pre>',
+        '  <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 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) + '.");',
+        '    } else {',
+        '      bootProject(mount, { url: new URL("./", location.href).href, entry: ' + JSON.stringify(recipeFile) + ' }, { renderState: RENDER_STATE })',
+        '        .catch((e) => fail("FRQTL project boot failed", String(e && e.stack || e)));',
+        '    }',
+        '  </script>',
+        '</body>',
+        '</html>',
+        ''
+    ].join('\n');
+}

package/dist/shim/bundle/manifest.js

@@ -0,0 +1,95 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/bundle/manifest.js — the bundle manifest as an ENVELOPE FERRY
+ * (ws-experiments-walkthrough Bite 2, CEO ruling E1).
+ *
+ * ── The rule (E1): manifest = the Module envelope minus `source` ─────────────
+ *
+ * The bundle is a projection of the `lib/shim/storage/modules.js` Module
+ * envelope. `experiment.js` = `module.source`. The manifest carries EVERYTHING
+ * ELSE from the envelope, ferried VERBATIM (`{...envelope}` minus `source`) plus
+ * a small set of bundle-only fields. Critically this module NEVER re-enumerates
+ * the envelope's field list (`{name: mod.name, renderState: mod.renderState, …}`)
+ * — that would be a schema mirror of modules.js. It spreads the whole envelope
+ * and deletes the ONE key (`source`) the sibling `experiment.js` file owns. Any
+ * field modules.js adds in future rides through automatically; `renderState`
+ * rides through as an ordinary envelope field, opaque (never parsed here).
+ *
+ * ── Bundle-only fields ───────────────────────────────────────────────────────
+ *
+ *   sdkVersion : string  — the `@descix/frqtl-web@<pin>` the index.html imports.
+ *                          A VALUE passed IN by the caller (the feature side
+ *                          DERIVES it from the built SDK's package.json at export
+ *                          time — truth-in-labeling; NEVER a literal in bundle
+ *                          code). REQUIRED — FAIL-LOUD when absent.
+ *   preview    : string|null — the preview image filename ref (e.g. 'preview.png'),
+ *                          or null when no preview was captured.
+ *   descix     : {}      — reserved inert publish block (DeSciX now-vs-later).
+ *
+ * Layer 2 (physics): none — pure metadata projection.
+ */
+
+'use strict';
+
+/** The envelope key the sibling `experiment.js` file owns (never in the manifest). */
+export var SOURCE_KEY = 'source';
+
+/** Bundle-only manifest keys (NOT envelope fields — stripped on import). */
+export var BUNDLE_ONLY_KEYS = ['sdkVersion', 'preview', 'descix'];
+
+/**
+ * Build the manifest object from a Module envelope + bundle-only inputs.
+ *
+ * @param {object} envelope   — a `lib/shim/storage/modules.js` Module envelope
+ *   (MUST carry `source`; every other field is ferried verbatim).
+ * @param {object} opts
+ * @param {string} opts.sdkVersion — REQUIRED; the CDN pin (e.g. '0.6.0-p0.1').
+ * @param {string|null} [opts.preview] — preview filename ref, or null/omitted.
+ * @returns {object} the manifest (JSON-serializable).
+ */
+export function buildManifest(envelope, opts) {
+    if (!envelope || typeof envelope !== 'object') {
+        throw new Error('[bundle/manifest] buildManifest(envelope): envelope must be an object.');
+    }
+    opts = opts || {};
+    if (typeof opts.sdkVersion !== 'string' || opts.sdkVersion.length === 0) {
+        throw new Error('[bundle/manifest] buildManifest: opts.sdkVersion is REQUIRED (a derived value, ' +
+            'never a literal) — the index.html CDN pin depends on it.');
+    }
+
+    // Ferry the WHOLE envelope minus `source` (no per-field re-enumeration).
+    var manifest = Object.assign({}, envelope);
+    delete manifest[SOURCE_KEY];
+
+    // Bundle-only fields.
+    manifest.sdkVersion = opts.sdkVersion;
+    manifest.preview = (opts.preview != null) ? opts.preview : null;
+    manifest.descix = {};   // reserved inert publish block
+
+    return manifest;
+}
+
+/**
+ * Recover the Module envelope from a manifest + the `experiment.js` source.
+ * Inverse of `buildManifest`: strips the bundle-only fields and re-attaches
+ * `source`. The result is a full Module envelope (validatable by modules.js).
+ *
+ * @param {object} manifest — the parsed manifest.json object.
+ * @param {string} source   — the `experiment.js` recipe source.
+ * @returns {object} the reconstructed Module envelope.
+ */
+export function manifestToEnvelope(manifest, source) {
+    if (!manifest || typeof manifest !== 'object') {
+        throw new Error('[bundle/manifest] manifestToEnvelope(manifest): manifest must be an object.');
+    }
+    if (typeof source !== 'string') {
+        throw new Error('[bundle/manifest] manifestToEnvelope: source (experiment.js) must be a string.');
+    }
+    var envelope = Object.assign({}, manifest);
+    for (var i = 0; i < BUNDLE_ONLY_KEYS.length; i++) {
+        delete envelope[BUNDLE_ONLY_KEYS[i]];
+    }
+    envelope[SOURCE_KEY] = source;
+    return envelope;
+}