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

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.
+ *
+ * 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);
+}

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
+ * 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
+ * (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.2').
+ * @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;
+}

package/dist/shim/bundle/zip.js

@@ -0,0 +1,243 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/bundle/zip.js — a hand-rolled STORE-only ZIP writer + reader
+ * (R2).
+ *
+ * ── Why hand-rolled + STORE-only ─────────────────────────────────────────────
+ *
+ * A bundle folder must download as ONE `.zip`. `jszip` was REJECTED (any dep
+ * reachable from features ships in the sdk dist — supply-chain surface in the
+ * lean shim). STORE (no compression, method 0) needs no deflate implementation,
+ * is trivially readable by every standard unzip, and bundles are small text
+ * files + one PNG. This module is PURE + DOM-free: it emits/consumes
+ * `Uint8Array` only. The browser download trigger (`Blob` + `a.click`) is a THIN
+ * feature-side helper (`lib/features/ide` — shim = bytes, feature = browser UX).
+ *
+ * ── Contract ─────────────────────────────────────────────────────────────────
+ *
+ *   zipStore(entries) → Uint8Array
+ *     entries: [{ name: string, bytes: Uint8Array }]  (name = archive path)
+ *
+ *   unzipStore(bytes) → [{ name: string, bytes: Uint8Array }]
+ *     Reads a STORE-only archive (throws FAIL-LOUD on a compressed entry, a bad
+ *     signature, or a CRC mismatch — never silently returns wrong bytes).
+ *
+ *   textBytes(str) / bytesText(u8)   — UTF-8 encode/decode helpers (a text
+ *                                      bundle file's bytes ARE its UTF-8 encoding).
+ *
+ * Layer 2 (physics): none — pure byte format.
+ */
+
+'use strict';
+
+var _enc = new TextEncoder();
+var _dec = new TextDecoder();
+
+/** @param {string} s @returns {Uint8Array} */
+export function textBytes(s) { return _enc.encode(s == null ? '' : String(s)); }
+
+/** @param {Uint8Array} u8 @returns {string} */
+export function bytesText(u8) { return _dec.decode(u8); }
+
+// ── CRC-32 (IEEE 802.3, standard ZIP polynomial 0xEDB88320) ──────────────────
+
+var _CRC_TABLE = (function () {
+    var t = new Uint32Array(256);
+    for (var n = 0; n < 256; n++) {
+        var c = n;
+        for (var k = 0; k < 8; k++) {
+            c = (c & 1) ? (0xEDB88320 ^ (c >>> 1)) : (c >>> 1);
+        }
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {number} unsigned 32-bit CRC.
+ */
+export function crc32(bytes) {
+    var crc = 0xFFFFFFFF;
+    for (var i = 0; i < bytes.length; i++) {
+        crc = (crc >>> 8) ^ _CRC_TABLE[(crc ^ bytes[i]) & 0xFF];
+    }
+    return (crc ^ 0xFFFFFFFF) >>> 0;
+}
+
+// ── little-endian writers ────────────────────────────────────────────────────
+
+function _u16(v) { return [v & 0xFF, (v >>> 8) & 0xFF]; }
+function _u32(v) {
+    v = v >>> 0;
+    return [v & 0xFF, (v >>> 8) & 0xFF, (v >>> 16) & 0xFF, (v >>> 24) & 0xFF];
+}
+
+function _concat(chunks) {
+    var total = 0, i;
+    for (i = 0; i < chunks.length; i++) { total += chunks[i].length; }
+    var out = new Uint8Array(total);
+    var off = 0;
+    for (i = 0; i < chunks.length; i++) { out.set(chunks[i], off); off += chunks[i].length; }
+    return out;
+}
+
+// ── little-endian readers ────────────────────────────────────────────────────
+
+function _readU16(b, o) { return b[o] | (b[o + 1] << 8); }
+function _readU32(b, o) { return (b[o] | (b[o + 1] << 8) | (b[o + 2] << 16) | (b[o + 3] << 24)) >>> 0; }
+
+var LOCAL_SIG   = 0x04034b50;
+var CENTRAL_SIG = 0x02014b50;
+var EOCD_SIG    = 0x06054b50;
+
+/**
+ * Build a STORE-only ZIP archive from a list of named byte entries.
+ *
+ * @param {{name:string, bytes:Uint8Array}[]} entries
+ * @returns {Uint8Array} the complete `.zip` bytes.
+ */
+export function zipStore(entries) {
+    if (!Array.isArray(entries)) {
+        throw new Error('[bundle/zip] zipStore(entries): entries must be an array.');
+    }
+    var localChunks = [];
+    var centralChunks = [];
+    var offset = 0;   // running offset of each local header
+
+    for (var i = 0; i < entries.length; i++) {
+        var e = entries[i];
+        if (!e || typeof e.name !== 'string' || !(e.bytes instanceof Uint8Array)) {
+            throw new Error('[bundle/zip] zipStore: entry ' + i + ' must be {name:string, bytes:Uint8Array}.');
+        }
+        var nameBytes = textBytes(e.name);
+        var data = e.bytes;
+        var crc = crc32(data);
+        var size = data.length;
+
+        // Local file header.
+        var local = _concat([
+            new Uint8Array(_u32(LOCAL_SIG)),
+            new Uint8Array(_u16(20)),           // version needed to extract (2.0)
+            new Uint8Array(_u16(0)),            // general purpose bit flag
+            new Uint8Array(_u16(0)),            // compression method: 0 = STORE
+            new Uint8Array(_u16(0)),            // last mod time (fixed 0 — deterministic)
+            new Uint8Array(_u16(0)),            // last mod date (fixed 0 — deterministic)
+            new Uint8Array(_u32(crc)),
+            new Uint8Array(_u32(size)),         // compressed size (== uncompressed for STORE)
+            new Uint8Array(_u32(size)),         // uncompressed size
+            new Uint8Array(_u16(nameBytes.length)),
+            new Uint8Array(_u16(0)),            // extra field length
+            nameBytes,
+            data
+        ]);
+        localChunks.push(local);
+
+        // Central directory record (references this local header's offset).
+        var central = _concat([
+            new Uint8Array(_u32(CENTRAL_SIG)),
+            new Uint8Array(_u16(20)),           // version made by
+            new Uint8Array(_u16(20)),           // version needed
+            new Uint8Array(_u16(0)),            // flags
+            new Uint8Array(_u16(0)),            // method: STORE
+            new Uint8Array(_u16(0)),            // time
+            new Uint8Array(_u16(0)),            // date
+            new Uint8Array(_u32(crc)),
+            new Uint8Array(_u32(size)),
+            new Uint8Array(_u32(size)),
+            new Uint8Array(_u16(nameBytes.length)),
+            new Uint8Array(_u16(0)),            // extra length
+            new Uint8Array(_u16(0)),            // comment length
+            new Uint8Array(_u16(0)),            // disk number start
+            new Uint8Array(_u16(0)),            // internal attrs
+            new Uint8Array(_u32(0)),            // external attrs
+            new Uint8Array(_u32(offset)),       // local header offset
+            nameBytes
+        ]);
+        centralChunks.push(central);
+
+        offset += local.length;
+    }
+
+    var localBlob = _concat(localChunks);
+    var centralBlob = _concat(centralChunks);
+    var eocd = _concat([
+        new Uint8Array(_u32(EOCD_SIG)),
+        new Uint8Array(_u16(0)),                    // disk number
+        new Uint8Array(_u16(0)),                    // disk with central dir
+        new Uint8Array(_u16(entries.length)),       // CD records on this disk
+        new Uint8Array(_u16(entries.length)),       // total CD records
+        new Uint8Array(_u32(centralBlob.length)),   // central dir size
+        new Uint8Array(_u32(localBlob.length)),     // central dir offset (== size of all local records)
+        new Uint8Array(_u16(0))                     // comment length
+    ]);
+
+    return _concat([localBlob, centralBlob, eocd]);
+}
+
+/**
+ * Read a STORE-only ZIP archive. Walks the central directory (the canonical
+ * index), resolves each entry's local header, and extracts its stored bytes.
+ *
+ * FAIL-LOUD: throws on a missing EOCD, a bad central/local signature, a
+ * non-STORE compression method, or a CRC-32 mismatch — never returns wrong bytes.
+ *
+ * @param {Uint8Array} bytes
+ * @returns {{name:string, bytes:Uint8Array}[]}
+ */
+export function unzipStore(bytes) {
+    if (!(bytes instanceof Uint8Array)) {
+        throw new Error('[bundle/zip] unzipStore(bytes): bytes must be a Uint8Array.');
+    }
+    // Locate the End Of Central Directory record (scan backward for its signature).
+    var eocd = -1;
+    for (var p = bytes.length - 22; p >= 0; p--) {
+        if (_readU32(bytes, p) === EOCD_SIG) { eocd = p; break; }
+    }
+    if (eocd === -1) {
+        throw new Error('[bundle/zip] unzipStore: End Of Central Directory record not found (not a ZIP).');
+    }
+    var count   = _readU16(bytes, eocd + 10);
+    var cdOffset = _readU32(bytes, eocd + 16);
+
+    var out = [];
+    var o = cdOffset;
+    for (var i = 0; i < count; i++) {
+        if (_readU32(bytes, o) !== CENTRAL_SIG) {
+            throw new Error('[bundle/zip] unzipStore: bad central directory signature at record ' + i + '.');
+        }
+        var method    = _readU16(bytes, o + 10);
+        var crcStored = _readU32(bytes, o + 16);
+        var compSize  = _readU32(bytes, o + 20);
+        var nameLen   = _readU16(bytes, o + 28);
+        var extraLen  = _readU16(bytes, o + 30);
+        var commentLen = _readU16(bytes, o + 32);
+        var localOff  = _readU32(bytes, o + 42);
+        var name = bytesText(bytes.subarray(o + 46, o + 46 + nameLen));
+
+        if (method !== 0) {
+            throw new Error('[bundle/zip] unzipStore: entry "' + name + '" uses compression method ' +
+                method + ' — this reader is STORE-only (method 0).');
+        }
+
+        // Resolve the local header to find the data start (its own name/extra lengths).
+        if (_readU32(bytes, localOff) !== LOCAL_SIG) {
+            throw new Error('[bundle/zip] unzipStore: bad local header signature for "' + name + '".');
+        }
+        var lNameLen  = _readU16(bytes, localOff + 26);
+        var lExtraLen = _readU16(bytes, localOff + 28);
+        var dataStart = localOff + 30 + lNameLen + lExtraLen;
+        var data = bytes.slice(dataStart, dataStart + compSize);
+
+        var crcActual = crc32(data);
+        if (crcActual !== crcStored) {
+            throw new Error('[bundle/zip] unzipStore: CRC-32 mismatch for "' + name +
+                '" (stored ' + crcStored + ', computed ' + crcActual + ').');
+        }
+        out.push({ name: name, bytes: data });
+
+        o += 46 + nameLen + extraLen + commentLen;
+    }
+    return out;
+}