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

package/dist/shim/notebook/knob.js

@@ -0,0 +1,151 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * Notebook knob — the SINGLE authority for the canvas-cell driving knob
+ * (WS-NOTEBOOK-D GAP2).
+ *
+ * A canvas cell may carry an `opts="<key>=<value>,…"` attribute (parsed to a
+ * `{key: Number}` map by lib/shim/notebook/format.js — a pure module that does
+ * NOT validate). This module is the ONE place that:
+ *
+ *   1. validates each opts key against the exhibit knob SCHEMA, and
+ *   2. maps the manifest knob param name → the setup-factory option key,
+ *
+ * then returns the factory-option object the pane threads into
+ * GraphicsPane.loadExperiment(setupFn, opts). It is FAIL-LOUD: an unknown key,
+ * an out-of-range value, or a spec that defines no knob THROWS — never a silent
+ * ignore (that would be the hint-only/lie-in-surface class the gate forbids).
+ *
+ * ── Why this lives in lib/shim (not the pane, not exhibits.js) ────────────────
+ *
+ * The knob SCHEMA lives ONCE, notebook-scoped, in the sibling module
+ * lib/shim/notebook/notebook-knobs.js (NOTEBOOK_KNOBS). A canvas cell's live
+ * knob is a NOTEBOOK feature, so its declaration belongs with the notebook, not
+ * on the public-site Impossible Gallery exhibit card. This module reads that
+ * same-layer table (no upward dependency on lib/frqtl) and owns the MECHANISM:
+ * validation + the param→factory-option map.
+ *
+ * The param→factory-option map (e.g. quanta → quantumLimit) lives HERE and
+ * ONLY here, so the notebook canvas path and the (future) public-iframe
+ * set-param path cannot diverge.
+ *
+ * Named ESM export. Imports ONLY the sibling knob declaration; no Runtime, no
+ * Bus, no DOM, no engine path.
+ */
+
+'use strict';
+
+import { NOTEBOOK_KNOBS } from './notebook-knobs.js';
+
+/* ── The ONE param → setup-factory-option map ────────────────────────────────
+ *
+ * The exhibit manifest knob `param` is the human/URL-facing name ('quanta').
+ * The setup factory reads a different option key ('quantumLimit' in
+ * setupWaveInterference). This map is the SINGLE bridge between the two
+ * vocabularies. A param present in an exhibit knob MUST have an entry here, or
+ * mapping FAILS LOUD (a knob with no wire is a hint-only knob — forbidden).
+ *
+ * Keyed by manifest param name → factory option key. */
+var PARAM_TO_FACTORY_OPTION = {
+    // wave-interference: quanta = max quanta per source = setupWaveInterference's
+    // `quantumLimit` option (setupWaveInterference.js:64). More quanta → denser
+    // emission → an observably different fringe build-up.
+    quanta: 'quantumLimit'
+};
+
+/* Index the notebook-scoped declaration by the setup-factory `spec` name (the
+ * value the builder cell threads into frqtl.knob). NOTEBOOK_KNOBS is keyed by
+ * notebook id; each entry names its `spec`. FAIL-LOUD on a duplicate spec so two
+ * notebooks cannot silently declare divergent knobs for one factory. */
+var _knobBySpec = (function () {
+    var map = Object.create(null);
+    var ids = Object.keys(NOTEBOOK_KNOBS);
+    for (var i = 0; i < ids.length; i++) {
+        var entry = NOTEBOOK_KNOBS[ids[i]];
+        if (!entry || !entry.spec || !entry.knob) { continue; }
+        if (map[entry.spec]) {
+            throw new Error(
+                '[notebook/knob] duplicate knob spec "' + entry.spec + '" across notebooks ' +
+                '(' + ids[i] + ' collides with an earlier entry). (FAIL-LOUD.)'
+            );
+        }
+        map[entry.spec] = entry.knob;
+    }
+    return map;
+})();
+
+/**
+ * knobSchemaFor(specName) → the exhibit knob schema for a canvas cell `spec`
+ * (setup factory name), or null when the spec defines no knob.
+ *
+ * @param {string} specName
+ * @returns {{label:string, param:string, min:number, max:number, step:number, defaultValue:number}|null}
+ */
+export function knobSchemaFor(specName) {
+    if (!specName) { return null; }
+    // The cell spec may be an ordered dependency list whose LAST member is the
+    // factory (notebook-pane._runRealmCell convention). Use the last segment.
+    var name = String(specName).split(',').pop().trim();
+    return _knobBySpec[name] || null;
+}
+
+/**
+ * validateAndMap(specName, optsMap) → factory-option object, or THROWS.
+ *
+ * FAIL-LOUD on:
+ *   - optsMap has a key, but `specName` defines no knob at all.
+ *   - a key that is not the spec's knob `param`.
+ *   - a value out of the schema [min, max] range.
+ *   - a knob `param` with no PARAM_TO_FACTORY_OPTION wire (a hint-only knob).
+ *
+ * Returns {} when optsMap is empty/absent (no knob requested — not an error).
+ *
+ * @param {string} specName            — the canvas cell `spec` (setup factory name)
+ * @param {Object<string,number>} optsMap — parsed opts (format.js), {} when absent
+ * @returns {Object<string,number>}    — { <factoryOption>: <value> }
+ */
+export function validateAndMap(specName, optsMap) {
+    var keys = optsMap ? Object.keys(optsMap) : [];
+    if (keys.length === 0) { return {}; }
+
+    var schema = knobSchemaFor(specName);
+    if (!schema) {
+        throw new Error(
+            '[notebook/knob] cell spec "' + specName + '" defines NO knob, but opts ' +
+            'declares ' + JSON.stringify(keys) + '. (FAIL-LOUD — no silent ignore.)'
+        );
+    }
+
+    var out = {};
+    for (var i = 0; i < keys.length; i++) {
+        var key = keys[i];
+        if (key !== schema.param) {
+            throw new Error(
+                '[notebook/knob] unknown knob key "' + key + '" for spec "' + specName +
+                '" — the only knob is "' + schema.param + '". (FAIL-LOUD; not silently ignored.)'
+            );
+        }
+        var value = optsMap[key];
+        if (typeof value !== 'number' || !isFinite(value)) {
+            throw new Error(
+                '[notebook/knob] knob "' + key + '" value is not a finite number: ' +
+                JSON.stringify(value) + '. (FAIL-LOUD.)'
+            );
+        }
+        if (value < schema.min || value > schema.max) {
+            throw new Error(
+                '[notebook/knob] knob "' + key + '"=' + value + ' is out of range [' +
+                schema.min + ', ' + schema.max + '] for spec "' + specName + '". (FAIL-LOUD.)'
+            );
+        }
+        var factoryOption = PARAM_TO_FACTORY_OPTION[key];
+        if (!factoryOption) {
+            throw new Error(
+                '[notebook/knob] knob param "' + key + '" has NO factory-option wire in ' +
+                'PARAM_TO_FACTORY_OPTION — a hint-only knob is forbidden. (FAIL-LOUD.)'
+            );
+        }
+        out[factoryOption] = value;
+    }
+    return out;
+}

package/dist/shim/notebook/module-resolver.js

@@ -0,0 +1,260 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * Notebook cell-as-module resolver — the IN-MEMORY blob closure (WS-NOTEBOOK-IMPORT
+ * B2; architect build-gate ruling C + VETO-CLASS constraint #1).
+ *
+ * Named ESM export. PURE module — NO Runtime/Bus/DOM/engine imports. It is
+ * host-neutral (it must NOT assume CodeEditorPane or any pane exists — model-gate
+ * ruling 6): the blob-minting + dynamic-import are injected by the caller
+ * (Runtime.runCell in the browser; a test stub in node).
+ *
+ * ── What it does ─────────────────────────────────────────────────────────────
+ *
+ * Given a notebook's user-code module SET (`{ name → source }`, the `type="module"`
+ * cells keyed by their relative path) and a builder cell body that `import`s some
+ * of them, it builds the dependency closure ENTIRELY IN MEMORY:
+ *
+ *   - every module member becomes its OWN blob whose relative `./x.js` specifiers
+ *     are rewritten to its SIBLINGS' blob URLs (a topological create so a
+ *     referenced module's blob URL exists before the referencer is rewritten);
+ *   - the entry (builder cell) keeps its top-level imports verbatim (relative
+ *     specifiers rewritten to the sibling blob URLs) and wraps the rest in an
+ *     exported `default async (caps, inputs) => {…}` so `caps`/`inputs` stay
+ *     INJECTED (they are NOT imports) — the caller invokes the default export with
+ *     the injected objects.
+ *
+ * ── THE VETO-CLASS CONSTRAINT (#1) THIS HOLDS ────────────────────────────────
+ *
+ * A relative specifier NEVER resolves to an HTTP sibling on a scoped mount — that
+ * is the Phase-A blob-rewriter 404 trap (a blob module has no hierarchical base,
+ * so statically-served siblings hit the native loader and relative sub-imports
+ * 404). Here a relative `./x.js` ONLY ever resolves to an in-memory sibling blob
+ * URL; an unresolved relative specifier FAILS LOUD. Bare specifiers (no leading
+ * `.`) pass through verbatim for the host's native loader (third-party / host
+ * resolution). There is NO network round-trip per relative import.
+ */
+
+'use strict';
+
+/* ── path math (pure) ─────────────────────────────────────────────────────── */
+
+// Canonicalize a module path into a stable key: drop '.' and '' segments, fold
+// '..'. So './setups/x.js', 'setups/x.js' canonicalize identically, and a
+// sat.js-relative './setupCircuitBasic.js' folds to the same key the module set
+// is keyed by.
+export function canonKey(p) {
+    var parts = String(p).split('/');
+    var out = [];
+    for (var i = 0; i < parts.length; i++) {
+        var seg = parts[i];
+        if (seg === '' || seg === '.') { continue; }
+        if (seg === '..') { out.pop(); continue; }
+        out.push(seg);
+    }
+    return out.join('/');
+}
+
+// Resolve a relative `specifier` against the DIRECTORY of `fromName`, returning a
+// canonical key. (Both inputs are relative notebook-local paths.)
+export function resolveRelativeKey(specifier, fromName) {
+    var fromParts = canonKey(fromName).split('/');
+    fromParts.pop(); // drop the file segment → directory
+    var base = fromParts.join('/');
+    var joined = base ? (base + '/' + specifier) : specifier;
+    return canonKey(joined);
+}
+
+/* ── import-detection + body split (pure) ─────────────────────────────────── */
+
+// Does the source contain a real top-level `import` statement?
+export function hasImport(code) {
+    return /(^|\n)\s*import\s/.test(String(code));
+}
+
+// Split a cell body into ITS TOP-LEVEL IMPORTS and the REST. The cell author
+// writes imports at (or near) the top, possibly interleaved with leading comment
+// lines and blanks (the notebook convention). ES modules require `import` at the
+// top level, so we must HOIST every top-level import above the
+// `async (caps, inputs) => {…}` wrapper. We collect:
+//   - leading blank lines + full-line comments (// … or /* … */ on one line) AND
+//     every top-level `import …` (single- or multi-line) into the PREAMBLE,
+//   - everything from the first line of real (non-import) code onward into BODY.
+// A `// import x` comment is NOT an import (it is stripped of leading whitespace,
+// so the `^import` test fails on the `//`). Returns { imports, body }.
+export function splitImportsAndBody(code) {
+    var lines = String(code).split('\n');
+    var preamble = [];   // blanks + leading comments + import statements
+    var bodyStart = 0;
+    var inImport = false;
+    for (var i = 0; i < lines.length; i++) {
+        var trimmed = lines[i].replace(/^\s+/, '');
+        if (inImport) {
+            preamble.push(lines[i]);
+            bodyStart = i + 1;
+            if (/from\s+['"][^'"]+['"]/.test(lines[i]) || /;\s*$/.test(lines[i])) { inImport = false; }
+            continue;
+        }
+        if (trimmed === '') { preamble.push(lines[i]); bodyStart = i + 1; continue; }
+        // A single-line comment or a single-line block comment — part of the
+        // leading preamble (so a comment ABOVE the import does not strand the
+        // import inside the body). A multi-line /* … */ that does not close on
+        // this line ends the preamble (rare in a cell header; treat as body).
+        if (/^\/\//.test(trimmed) || /^\/\*.*\*\/\s*$/.test(trimmed)) {
+            preamble.push(lines[i]); bodyStart = i + 1; continue;
+        }
+        if (/^import\s/.test(trimmed)) {
+            preamble.push(lines[i]);
+            bodyStart = i + 1;
+            if (!/from\s+['"][^'"]+['"]/.test(lines[i]) && !/;\s*$/.test(lines[i])) { inImport = true; }
+            continue;
+        }
+        break; // first line of real (non-import) code → body begins here
+    }
+    return { imports: preamble.join('\n'), body: lines.slice(bodyStart).join('\n') };
+}
+
+/* ── specifier rewrite (pure) ─────────────────────────────────────────────── */
+
+// Rewrite every relative specifier in `source` to the blob URL of the resolved
+// sibling (looked up in blobUrlByKey) — BOTH static `from '…'` clauses (import/
+// export) AND dynamic `import('…')` call expressions (WS gym-controls-as-sugar
+// Bite 0a REMEDIATION, Finding 2: the synthesized builder now DEFERS its
+// module-cell import to a dynamic `await import(...)` placed AFTER
+// `frqtl.ensureEngine()` — see setup-builder.js — so the relative specifier
+// this rewrite must resolve can appear inside the function BODY, not only the
+// header). Bare specifiers pass through verbatim (host loader). An unresolved
+// relative specifier FAILS LOUD in either form.
+export function rewriteRelativeToSiblingBlobs(source, ownName, blobUrlByKey) {
+    function resolveOrThrow(specifier) {
+        var key = resolveRelativeKey(specifier, ownName);
+        var blobUrl = blobUrlByKey[key];
+        if (!blobUrl) {
+            throw new Error(
+                '[module-resolver] relative import "' + specifier + '" (from "' + ownName +
+                '") resolves to "' + key + '", which is NOT a notebook-local module cell. ' +
+                'Add a <cell type="module" name="' + specifier + '">, or fix the path. ' +
+                '(FAIL-LOUD — never an HTTP sibling fetch.)'
+            );
+        }
+        return blobUrl;
+    }
+    var out = String(source).replace(/from\s+(['"])([^'"]+)\1/g, function (match, quote, specifier) {
+        if (specifier.charAt(0) !== '.') { return match; } // bare → host loader
+        return 'from ' + quote + resolveOrThrow(specifier) + quote;
+    });
+    out = out.replace(/import\(\s*(['"])([^'"]+)\1\s*\)/g, function (match, quote, specifier) {
+        if (specifier.charAt(0) !== '.') { return match; } // bare → host loader
+        return 'import(' + quote + resolveOrThrow(specifier) + quote + ')';
+    });
+    return out;
+}
+
+// The relative dependency keys a module source imports.
+function _relativeDepKeys(name, source) {
+    var deps = [];
+    String(source).replace(/from\s+(['"])([^'"]+)\1/g, function (m, q, spec) {
+        if (spec.charAt(0) === '.') { deps.push(resolveRelativeKey(spec, name)); }
+        return m;
+    });
+    return deps;
+}
+
+/* ── the in-memory closure ────────────────────────────────────────────────── */
+
+/**
+ * buildModuleClosure(modules, mintBlobUrl) → { blobUrlByKey, revoke }
+ *
+ * Mints one blob per module member (via the injected `mintBlobUrl(source)` →
+ * url), each rewritten so its relative specifiers point at sibling blob URLs.
+ * Topological create (a referenced module's blob URL exists before the referencer
+ * is rewritten); FAIL-LOUD on a missing member or a dependency cycle.
+ *
+ * @param {Object<string,string>} modules — { name → source }
+ * @param {(source:string)=>string} mintBlobUrl — host-injected blob URL minter.
+ * @returns {{ blobUrlByKey: Object<string,string>, revoke: () => void }}
+ *          revoke is a no-op here (the caller owns URL lifetime via a revokeAll it
+ *          accumulates); we return the created URL list through revoke for symmetry.
+ */
+export function buildModuleClosure(modules, mintBlobUrl) {
+    if (typeof mintBlobUrl !== 'function') {
+        throw new Error('[module-resolver] buildModuleClosure requires a mintBlobUrl(source) function.');
+    }
+    var byKey = Object.create(null);
+    var keys = Object.keys(modules || {});
+    for (var i = 0; i < keys.length; i++) {
+        byKey[canonKey(keys[i])] = { name: keys[i], source: modules[keys[i]] };
+    }
+
+    var blobUrlByKey = Object.create(null);
+    var created = [];
+
+    var remaining = Object.keys(byKey);
+    var guard = 0;
+    while (remaining.length > 0) {
+        if (guard++ > 100000) {
+            throw new Error('[module-resolver] module closure did not converge (cycle?). (FAIL-LOUD.)');
+        }
+        var madeProgress = false;
+        var still = [];
+        for (var r = 0; r < remaining.length; r++) {
+            var key = remaining[r];
+            var entry = byKey[key];
+            var deps = _relativeDepKeys(entry.name, entry.source);
+            var ready = true;
+            for (var d = 0; d < deps.length; d++) {
+                if (!blobUrlByKey[deps[d]]) {
+                    if (!byKey[deps[d]]) {
+                        throw new Error(
+                            '[module-resolver] module "' + entry.name + '" imports "' + deps[d] +
+                            '" which is not in the notebook module set. (FAIL-LOUD.)'
+                        );
+                    }
+                    ready = false; break;
+                }
+            }
+            if (!ready) { still.push(key); continue; }
+            var rewritten = rewriteRelativeToSiblingBlobs(entry.source, entry.name, blobUrlByKey);
+            var url = mintBlobUrl(rewritten);
+            blobUrlByKey[key] = url;
+            created.push(url);
+            madeProgress = true;
+        }
+        remaining = still;
+        if (!madeProgress && remaining.length > 0) {
+            throw new Error(
+                '[module-resolver] unresolvable module closure (dependency cycle among ' +
+                remaining.join(', ') + '). (FAIL-LOUD.)'
+            );
+        }
+    }
+
+    return { blobUrlByKey: blobUrlByKey, created: created };
+}
+
+/**
+ * compileEntryModuleSource(code, entryName, blobUrlByKey) → string
+ *
+ * Build the entry (builder cell) module SOURCE: its top-level imports kept
+ * verbatim (relative specifiers rewritten to sibling blob URLs), the remaining
+ * statements wrapped in an exported `default async (caps, inputs) => {…}` so
+ * caps/inputs stay INJECTED. The caller mints the blob + dynamic-imports it +
+ * invokes `mod.default(caps, inputs)`.
+ *
+ * The rewrite runs on the FULL `code` (imports AND body) BEFORE splitting —
+ * WS gym-controls-as-sugar Bite 0a REMEDIATION, Finding 2: the synthesized
+ * builder's module-cell reference is now a DYNAMIC `await import('<module>')`
+ * placed inside the body (after `frqtl.ensureEngine()`, deliberately deferring
+ * evaluation — see setup-builder.js), so a relative specifier needing
+ * blob-URL rewrite can live in the body, not only the header. Rewriting first
+ * then splitting is behavior-preserving for the header-only case (the
+ * structural blank/comment/import scan in splitImportsAndBody does not
+ * inspect specifier CONTENT) and additionally catches body-level dynamic
+ * imports.
+ */
+export function compileEntryModuleSource(code, entryName, blobUrlByKey) {
+    var rewritten = rewriteRelativeToSiblingBlobs(code, entryName, blobUrlByKey);
+    var split = splitImportsAndBody(rewritten);
+    return split.imports + '\n' +
+        'export default async (caps, inputs) => {\n' + split.body + '\n};\n';
+}

package/dist/shim/notebook/notebook-knobs.js

@@ -0,0 +1,65 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * NOTEBOOK_KNOBS — the canonical, notebook-scoped declaration of every live
+ * canvas-cell driving knob.
+ *
+ * This is the SINGLE home for the driving-knob SCHEMA. It is keyed by NOTEBOOK
+ * ID (the notebooks.json `id`, e.g. 'gallery-wave-interference'); each entry
+ * names the setup-factory export it binds (`spec`) and carries the knob schema
+ * shape ({ label, param, min, max, step, defaultValue }).
+ *
+ * ── Why the declaration lives HERE (not on the exhibit card) ──────────────────
+ *
+ * A canvas cell's live knob is a NOTEBOOK feature: the gallery notebook declares
+ * a canvas with `opts="<param>=<value>"`, and the shim validates + maps that
+ * param to a setup-factory option at run time (lib/shim/notebook/knob.js →
+ * frqtl.knob). The knob therefore belongs to the notebook that hosts the canvas,
+ * not to the Impossible Gallery exhibit card (a separate public-site curation
+ * surface). Keeping the schema here — a lib/shim sibling of knob.js — makes the
+ * notebook path self-contained: knob.js reads this table directly (a same-layer
+ * read), with no upward dependency on lib/shim/registry/exhibits.js.
+ *
+ * knob.js remains the MECHANISM owner (validate + param→factory-option map);
+ * this module is only the DECLARATION. One authority, no mirror.
+ *
+ * Named ESM export. No Runtime, no Bus, no DOM, no engine path.
+ */
+
+'use strict';
+
+/**
+ * @typedef {Object} KnobSchema
+ * @property {string} label        — human/UI label for the slider.
+ * @property {string} param        — the URL/opts-facing knob name (e.g. 'quanta').
+ * @property {number} min
+ * @property {number} max
+ * @property {number} step
+ * @property {number} defaultValue
+ */
+
+/**
+ * @typedef {Object} NotebookKnobEntry
+ * @property {string} spec         — the setup-factory export name the knob drives
+ *                                   (e.g. 'setupWaveInterference'); this is the
+ *                                   `spec` the builder cell passes to frqtl.knob.
+ * @property {KnobSchema} knob      — the knob schema.
+ */
+
+/** @type {Object<string, NotebookKnobEntry>} keyed by notebook id. */
+export const NOTEBOOK_KNOBS = {
+    // gallery-wave-interference: the `quanta` knob = max quanta per source =
+    // setupWaveInterference's `quantumLimit` option (setupWaveInterference.js).
+    // More quanta → denser emission → an observably different fringe build-up.
+    'gallery-wave-interference': {
+        spec: 'setupWaveInterference',
+        knob: {
+            label: 'Particles',
+            param: 'quanta',
+            min: 100,
+            max: 2000,
+            step: 100,
+            defaultValue: 800,
+        },
+    },
+};

package/dist/shim/notebook/produced-bindings.js

@@ -0,0 +1,67 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * produced-bindings — the PURE derive-the-serializable-binding helper for the
+ * realm→kernel binding seam (WS-NOTEBOOK-REALM-KERNEL-BINDING). NO DOM / engine /
+ * Runtime / Bus import, so a test exercises it with a fake handle WITHOUT a browser.
+ *
+ * A DECLARED canvas commits its `produces` binding(s) by DERIVING each value from the
+ * live realm-internal runner via the FROZEN handle (`handle.call(produceVia)`), then
+ * asserting it serializable before it crosses any authority boundary (the in-app pane
+ * commit, the realm-entry `realm:binding` post). It reuses the ONE existing projector
+ * (`detectorHistogram`, via `handle.call('detectorHistogram')`) — it invents none.
+ *
+ *   deriveProducedBindings(handle, produces, produceVia) → [{ name, value }, …]
+ *
+ * FAIL-LOUD: a missing handle, an empty produces with no names (→ []), a `handle.call`
+ * that throws (unknown produceVia / no detector) PROPAGATES (the caller surfaces it as a
+ * `realm:error` / pane overlay and commits NOTHING), and a non-serializable derived value
+ * THROWS via `assertSerializable` (a live runner/handle/function can never cross the seam).
+ */
+
+'use strict';
+
+import { assertSerializable } from './view-handle.js';
+
+var DEFAULT_PRODUCE_VIA = 'detectorHistogram';
+
+/**
+ * Derive the serializable `{ name, value }` bindings a declared canvas commits.
+ *
+ * @param {object} handle — the FROZEN view-handle (must expose `call(fn, args)`).
+ * @param {string[]} produces — the declared `produces` binding names (canvas-only).
+ * @param {string} [produceVia] — the frozen-handle call name; defaults to `'detectorHistogram'`.
+ * @returns {Promise<Array<{name:string, value:*}>>} one entry per produced name (empty when none declared).
+ * @throws {Error} FAIL-LOUD on a missing/invalid handle, a throwing `handle.call`, or a
+ *   non-serializable derived value (VETO-CLASS #1 — never commit a live ref).
+ *
+ * ASYNC: the frozen handle is async-shaped (`call()` returns a Promise on every
+ * transport). The derived
+ * value MUST be AWAITED before `assertSerializable` — otherwise a Promise (never
+ * structured-clone-serializable) reaches the seam and FAILS LOUD spuriously.
+ */
+export async function deriveProducedBindings(handle, produces, produceVia) {
+    var names = Array.isArray(produces) ? produces : [];
+    if (!names.length) { return []; }
+    if (!handle || typeof handle.call !== 'function') {
+        throw new Error('[produced-bindings] deriveProducedBindings requires a frozen view-handle ' +
+            'with call(). (FAIL-LOUD.)');
+    }
+    var via = (typeof produceVia === 'string' && produceVia) ? produceVia : DEFAULT_PRODUCE_VIA;
+    var out = [];
+    for (var i = 0; i < names.length; i++) {
+        var name = names[i];
+        // DERIVE from the live runner via the frozen handle — the SOLE source of the value
+        // (truth-in-labeling: the author never hand-writes the histogram). C11: one
+        // `produceVia` per canvas, so every name derives from the same call in this WS.
+        // AWAIT it: `handle.call` is async-shaped, so the value is a Promise until resolved.
+        var value = await handle.call(via, []);
+        // VETO-CLASS #1 at the realm boundary: a non-serializable value (a live runner /
+        // function / DOM node) FAILS LOUD here — it is never posted/committed (C2).
+        assertSerializable(value, 'produces("' + name + '") from realm canvas');
+        out.push({ name: name, value: value });
+    }
+    return out;
+}
+
+export { DEFAULT_PRODUCE_VIA };

package/dist/shim/notebook/realm-registry.js

@@ -0,0 +1,121 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * @module realm-registry
+ * @description
+ * The ONE authority for notebook webview-realm pre-loads.
+ *
+ * A notebook webview output cell is a managed scriptable *realm*. `frqtl canvas`,
+ * `chart`, and BYO realms are NOT different cell TYPES — they are different PRE-LOADS
+ * of the SAME realm primitive. Adding a new realm = registering a pre-load descriptor,
+ * NEVER a new cell type (VETO-CLASS #2).
+ *
+ * A pre-load descriptor shape:
+ * ```js
+ * { boot(hostEl, transport) → ViewHandle | Promise<ViewHandle> }
+ * ```
+ *
+ * The registry is module-level (process-global like `MathBackendRegistry`). Blessed
+ * pre-loads (`frqtl`, `chart`) self-register when their descriptor module is imported.
+ * A BYO realm must call `register('my-realm', descriptor)` before a notebook
+ * referencing it loads.
+ *
+ * @example
+ * import { register, get, has } from 'lib/shim/notebook/realm-registry.js';
+ *
+ * // Register a BYO realm pre-load:
+ * register('my-realm', {
+ *   boot(hostEl, transport) {
+ *     // set up the realm DOM, return a ViewHandle
+ *     return makeViewHandle({ ... });
+ *   }
+ * });
+ *
+ * // Resolve at notebook-pane mount time:
+ * const descriptor = get('my-realm'); // FAIL-LOUD if not registered
+ * const handle = await descriptor.boot(containerEl, transport);
+ */
+
+'use strict';
+
+// Realm-name → pre-load descriptor. Module-level (the realm catalog is one
+// process-global authority — mirrors MathBackendRegistry's single-instance shape).
+var _realms = Object.create(null);
+
+function _isValidName(name) {
+    return typeof name === 'string' && name.length > 0 && /^[a-z][a-z0-9-]*$/.test(name);
+}
+
+/**
+ * Add a realm pre-load descriptor to the catalog.
+ *
+ * @param {string} name
+ *   Realm name (lowercase kebab; e.g. `'frqtl'`, `'chart'`, `'my-realm'`).
+ * @param {{ boot: (hostEl: HTMLElement, transport: object) => (ViewHandle|Promise<ViewHandle>) }} descriptor
+ *   A pre-load descriptor whose `boot(hostEl, transport)` returns (or resolves to)
+ *   a frozen `ViewHandle`. FAIL-LOUD if `boot` is not a function or `name` is invalid.
+ * @returns {void}
+ * @throws {Error} on an invalid name or a descriptor without `boot`.
+ *
+ * @example
+ * register('my-realm', {
+ *   boot(hostEl, transport) {
+ *     // mount the realm into hostEl, return/resolve a ViewHandle
+ *     return makeViewHandle({ ... });
+ *   }
+ * });
+ */
+export function register(name, descriptor) {
+    if (!_isValidName(name)) {
+        throw new Error('[realm-registry] register: invalid realm name "' + String(name) +
+            '" (expect lowercase-kebab, e.g. "frqtl"). (FAIL-LOUD.)');
+    }
+    if (!descriptor || typeof descriptor.boot !== 'function') {
+        throw new Error('[realm-registry] register("' + name + '"): descriptor must have a ' +
+            'boot(hostEl, transport) function. (FAIL-LOUD.)');
+    }
+    _realms[name] = descriptor;
+}
+
+/**
+ * Resolve a registered pre-load descriptor.
+ *
+ * FAIL-LOUD on an unknown name: a cell referencing an unregistered realm surfaces
+ * the error, never renders empty.
+ *
+ * @param {string} name — realm name (must match a prior `register()` call).
+ * @returns {{ boot: Function }} the pre-load descriptor.
+ * @throws {Error} if no descriptor is registered for `name`.
+ *
+ * @example
+ * const descriptor = get('frqtl');        // throws if frqtl pre-load not imported
+ * const handle = await descriptor.boot(el, transport);
+ */
+export function get(name) {
+    var d = _realms[name];
+    if (!d) {
+        throw new Error('[realm-registry] get: no realm registered for "' + String(name) +
+            '". Registered: [' + names().join(', ') + ']. ' +
+            '(Blessed realms register at import; a BYO realm must register() first.) (FAIL-LOUD.)');
+    }
+    return d;
+}
+
+/** has(name) — non-throwing presence check. */
+export function has(name) {
+    return !!_realms[name];
+}
+
+/** names() — the registered realm names (diagnostics / docs). */
+export function names() {
+    return Object.keys(_realms);
+}
+
+/**
+ * _resetForTest() — clear the catalog (test isolation ONLY; not part of the
+ * runtime contract). The module-level catalog is process-global, so a test that
+ * exercises register/get FAIL-LOUD must be able to start from empty.
+ */
+export function _resetForTest() {
+    _realms = Object.create(null);
+}