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

package/dist/shim/notebook/store.js

@@ -0,0 +1,159 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/notebook/store.js — NotebookDocumentStore.
+ *
+ * Thin CRUD helpers that persist a serialized <frqtl-notebook> document on top
+ * of any StorageProvider (lib/shim/storage/index.js) using the "notebooks"
+ * namespace.  Mirrors the shape of lib/shim/storage/modules.js and
+ * lib/shim/storage/projects.js — ONE persistent-store pattern across Studio
+ * projects, Studio modules, and Notebooks.
+ *
+ * ── Why this lives in lib/shim ──────────────────────────────────────────────
+ *
+ * The serialized text is owned by format.serialize (lib/shim/notebook/format.js)
+ * and the storage seam is owned by StorageProvider (lib/shim/storage/index.js).
+ * Both are host-neutral shim contracts.  The notebook-pane (lib/components)
+ * consumes this module and does not re-implement the store helpers.  Arrow is legal: lib/shim → lib/shim.
+ *
+ * ── Notebook envelope ────────────────────────────────────────────────────────
+ *
+ *   {
+ *     id:            string    — unique identifier (newNotebookId())
+ *     title:         string    — human-readable title (mirrors notebook.title)
+ *     html:          string    — the serialized <frqtl-notebook>…</frqtl-notebook>
+ *                                text produced by format.serialize().  The value
+ *                                the pane writes is the CANONICAL writer's output —
+ *                                never hand-assembled markup.
+ *     createdAt:     string    — ISO-8601 creation timestamp
+ *     updatedAt:     string    — ISO-8601 last-updated timestamp
+ *     schemaVersion: number    — integer version; currently 1
+ *   }
+ *
+ * ── Namespace ──────────────────────────────────────────────────────────────
+ *
+ *   All helpers use the "notebooks" namespace.  Keys are notebook ids.
+ *
+ * ── The ONE persistence contract (§2.4 of the spec) ────────────────────────
+ *
+ *   The web IDE drives:
+ *     provider.put('notebooks', id, { html: format.serialize(nb), … })
+ *
+ * ── Usage ──────────────────────────────────────────────────────────────────
+ *
+ *   import { newNotebookId, saveNotebook, loadNotebook,
+ *            listNotebooks, deleteNotebook } from 'lib/shim/notebook/store.js';
+ *   import { getProvider } from 'lib/shim/storage';
+ *
+ *   const provider = getProvider();
+ *
+ *   const id  = newNotebookId();
+ *   const html = serialize(notebook);           // format.serialize — sole writer
+ *   saveNotebook(provider, { id, title: 'My notebook', html,
+ *                             createdAt: now, updatedAt: now, schemaVersion: 1 });
+ *
+ *   const record = loadNotebook(provider, id);  // { id, title, html, … } | null
+ *   const all    = listNotebooks(provider);     // [{ id, title, updatedAt }]
+ *   deleteNotebook(provider, id);
+ */
+
+'use strict';
+
+import { makeNamespaceStore } from '../storage/make-namespace-store.js';
+
+/** @type {string} The storage namespace for all notebook records. */
+export var NOTEBOOKS_NAMESPACE = 'notebooks';
+
+/** @type {number} Current schema version.  Increment on breaking envelope changes. */
+export var NOTEBOOK_SCHEMA_VERSION = 1;
+
+// ── Envelope validation ──────────────────────────────────────────────────────
+
+function _validateRecord(record) {
+  if (!record || typeof record !== 'object') {
+    throw new Error('[notebook/store] record must be a non-null object');
+  }
+  if (typeof record.id !== 'string' || record.id.length === 0) {
+    throw new Error('[notebook/store] record.id must be a non-empty string');
+  }
+  if (typeof record.title !== 'string') {
+    throw new Error('[notebook/store] record.title must be a string');
+  }
+  if (typeof record.html !== 'string' || record.html.length === 0) {
+    throw new Error('[notebook/store] record.html must be a non-empty string; use format.serialize() to produce it');
+  }
+  if (typeof record.schemaVersion !== 'number') {
+    throw new Error('[notebook/store] record.schemaVersion must be a number');
+  }
+}
+
+// ── Summary projection ────────────────────────────────────────────────────────
+
+function _summaryFields(record) {
+  return {
+    id:        record.id,
+    title:     record.title || '',
+    updatedAt: record.updatedAt || '',
+  };
+}
+
+// ── Store instance ────────────────────────────────────────────────────────────
+
+var _store = makeNamespaceStore({
+  namespace:     NOTEBOOKS_NAMESPACE,
+  schemaVersion: NOTEBOOK_SCHEMA_VERSION,
+  idPrefix:      'nb_',
+  validate:      _validateRecord,
+  summaryFields: _summaryFields,
+});
+
+// ── Public API (names and signatures unchanged) ───────────────────────────────
+
+/**
+ * Generate a new unique notebook id.
+ * @returns {string}  e.g. "nb_lxyz0abc1234"
+ */
+export var newNotebookId = _store.newId;
+
+/**
+ * Save (create or update) a notebook record.
+ *
+ * The `html` field MUST be the output of `format.serialize()` — the single
+ * canonical writer.  This function does NOT call serialize itself; callers are
+ * responsible for producing the text first.
+ *
+ * `updatedAt` is NOT automatically set — callers must set it before passing.
+ *
+ * @param {import('../storage/index.js').StorageProvider} provider
+ * @param {object} record
+ * @throws {Error} on validation failure or provider write failure.
+ */
+export var saveNotebook = _store.save;
+
+/**
+ * Load a notebook record by id.
+ * @param {import('../storage/index.js').StorageProvider} provider
+ * @param {string} id
+ * @returns {object|null}  The Notebook envelope, or null if not found.
+ */
+export var loadNotebook = _store.load;
+
+/**
+ * List all notebooks, returning lightweight summary objects.
+ *
+ * Returns an array of { id, title, updatedAt } objects suitable for a notebook
+ * picker.  Records with a missing or malformed id are silently skipped.
+ * Sorted by updatedAt descending.
+ *
+ * @param {import('../storage/index.js').StorageProvider} provider
+ * @returns {Array<{id: string, title: string, updatedAt: string}>}
+ */
+export var listNotebooks = _store.list;
+
+/**
+ * Delete a notebook record by id.
+ * No-op if the record does not exist.
+ * @param {import('../storage/index.js').StorageProvider} provider
+ * @param {string} id
+ */
+export var deleteNotebook = _store['delete'];

package/dist/shim/notebook/vendor-importmap.js

@@ -0,0 +1,134 @@
+// Copyright 2023-2026 by Essam Abadir
+// lib/shim/notebook/vendor-importmap.js — the ONE pure import-map generator.
+//
+// WS-NOTEBOOK-VENDOR Phase 2a (§2a.3). Maps the committed vendor manifest
+// (lib/frqtl/assets/vendor/manifest.json) → a browser `<script type="importmap">`
+// payload `{ imports: { <spec>: <url> } }`, so a realm cell's builder/view module
+// can `import * as d3 from 'd3'` and the realm's native module loader resolves the
+// bare specifier to a PLACED /vendor artifact.
+//
+// PURE: no DOM, no Runtime, no engine import. Node-testable.
+//
+// PATH AUTHORITY (the canonical-stack DRY rule): `vendorBase` is supplied by the
+// caller from `router.vendorBase` (the single path authority — DEV_CORE_PROFILE /
+// DIST_PROFILE `__vendorBase`). This module NEVER hardcodes a `/vendor` literal; it
+// only joins the caller-provided base with each manifest entry.
+//
+// FAIL-LOUD (the slit-objects-hardcoded-list bug class): a malformed manifest (no
+// `.libs`, or a lib without `.entry`) THROWS — never silently drops a lib.
+
+import { buildFrqtlSetupsImportMap } from './frqtl-setups-importmap.js';
+import { importMapFor } from '../project/specifiers.js';
+
+/**
+ * @typedef {object} VendorManifest
+ * @property {number} [version]
+ * @property {Object<string, { entry: string }>} libs
+ *   bare-specifier → { entry: path RELATIVE TO THE VENDOR ROOT }.
+ */
+
+/**
+ * Build a browser import-map from the vendor manifest.
+ *
+ * @param {VendorManifest} manifest  parsed manifest.json (`{ libs: { spec: { entry } } }`).
+ * @param {string} vendorBase        router.vendorBase, e.g. `'/vendor'` (no trailing slash needed).
+ * @returns {{ imports: Object<string, string> }}
+ *   `{ imports: { <spec>: <vendorBase>/<entry> } }`.
+ * @throws {Error} FAIL-LOUD on a malformed manifest or a missing vendorBase.
+ *
+ * @example
+ *   buildImportMap({ libs: { d3: { entry: 'd3/dist/d3.min.js' } } }, '/vendor')
+ *   // → { imports: { d3: '/vendor/d3/dist/d3.min.js' } }
+ */
+export function buildImportMap(manifest, vendorBase) {
+    if (!manifest || typeof manifest !== 'object' || !manifest.libs || typeof manifest.libs !== 'object') {
+        throw new Error('[vendor-importmap] malformed manifest: missing `.libs` object (FAIL-LOUD).');
+    }
+    if (typeof vendorBase !== 'string' || vendorBase.length === 0) {
+        throw new Error('[vendor-importmap] vendorBase is required (read it from router.vendorBase) (FAIL-LOUD).');
+    }
+    // Normalise the base: strip a single trailing slash so the join is unambiguous.
+    var base = vendorBase.replace(/\/+$/, '');
+    var imports = {};
+    var specs = Object.keys(manifest.libs);
+    for (var i = 0; i < specs.length; i++) {
+        var spec = specs[i];
+        var rec = manifest.libs[spec];
+        if (!rec || typeof rec.entry !== 'string' || rec.entry.length === 0) {
+            throw new Error('[vendor-importmap] manifest lib "' + spec + '" has no `.entry` (FAIL-LOUD — a lib is never silently dropped).');
+        }
+        // entry is relative to the vendor root; strip any leading slash so the join is clean.
+        var entry = rec.entry.replace(/^\/+/, '');
+        imports[spec] = base + '/' + entry;
+    }
+    return { imports: imports };
+}
+
+/**
+ * The lib-identity root, as the document sees it, for a router: where `frqtl/parts/index.js` is
+ * placed, minus that path (every profile places the game layer at its lib/-relative path).
+ *
+ * @param {{resolve:Function}} router
+ * @returns {string} ending in '/'
+ * @throws {Error} FAIL-LOUD when the profile does not place the parts at their lib/-relative path.
+ */
+export function libRootOf(router) {
+    var parts = router.resolve('parts/index.js');
+    var tail = 'frqtl/parts/index.js';
+    if (parts.slice(-tail.length) !== tail) {
+        throw new Error('[vendor-importmap] the router places parts/index.js at "' + parts + '", not at its ' +
+            'lib/-relative placement (…/' + tail + ') — the document\'s lib root cannot be located (FAIL-LOUD).');
+    }
+    var root = parts.slice(0, -tail.length);
+    return root === '' ? './' : root;
+}
+
+/**
+ * The REALM import map — the ONE merged `{imports}` every host injects into a document:
+ * the vendor libs (`buildImportMap(manifest, router.vendorBase)`), the canonical
+ * setup-factory bare specifiers (`buildFrqtlSetupsImportMap(router)`) and the sketch's
+ * `@descix/frqtl-web/...` specifiers (lib/shim/project/specifiers.js importMapFor, at this
+ * router's lib root). A document may carry only ONE import map, so the fragments always travel
+ * together, resolved through the SAME router (never a vendor base from one profile and module
+ * URLs from another).
+ *
+ * @param {VendorManifest} manifest
+ * @param {{resolve:Function, vendorBase:string}} router  an engineRouter() instance.
+ * @returns {{ imports: Object<string, string> }}
+ * @throws {Error} FAIL-LOUD on a malformed manifest or a missing router.
+ */
+export function buildRealmImportMap(manifest, router) {
+    if (!router || typeof router.resolve !== 'function') {
+        throw new Error('[vendor-importmap] buildRealmImportMap(manifest, router) requires an engineRouter() instance (FAIL-LOUD).');
+    }
+    var vendorMap = buildImportMap(manifest, router.vendorBase);
+    var setupsMap = buildFrqtlSetupsImportMap(router);
+    var webMap = importMapFor(libRootOf(router));
+    return { imports: Object.assign({}, vendorMap.imports, setupsMap.imports, webMap.imports) };
+}
+
+/**
+ * Splice the realm import map into an HTML document as
+ * `<script type="importmap" data-frqtl-vendor-importmap>`, immediately BEFORE the first
+ * `<script type="module"` (a map added after module loading starts is ignored), else
+ * before `</head>`, else prepended. Idempotent: a document already carrying the
+ * `data-frqtl-vendor-importmap` tag is returned unchanged.
+ *
+ * The ONE splice for every host: the dev serve-time splice
+ * (lib/server/realm-html.js) and the static build-time bake (apps/ide/vite.config.js).
+ *
+ * @param {string} html
+ * @param {VendorManifest} manifest
+ * @param {{resolve:Function, vendorBase:string}} router  the host's engineRouter() instance.
+ * @returns {string}
+ */
+export function spliceRealmImportMap(html, manifest, router) {
+    if (/data-frqtl-vendor-importmap/.test(html)) { return html; }   // idempotent
+    var body = JSON.stringify(buildRealmImportMap(manifest, router));
+    var tag = '<script type="importmap" data-frqtl-vendor-importmap>' + body + '</script>\n    ';
+    var moduleIdx = html.search(/<script\s+type=["']module["']/i);
+    if (moduleIdx !== -1) { return html.slice(0, moduleIdx) + tag + html.slice(moduleIdx); }
+    var headIdx = html.search(/<\/head>/i);
+    if (headIdx !== -1) { return html.slice(0, headIdx) + '  ' + tag + html.slice(headIdx); }
+    return tag + html;
+}

package/dist/shim/notebook/view-builder.js

@@ -0,0 +1,189 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * view-builder — the SOLE authority that synthesizes the canonical VIEW-ENTRY source
+ * from a `view` cell's declarative configuration (WS-NOTEBOOK-VENDOR-VIEW Phase 2b).
+ *
+ * Named ESM export. PURE module — NO DOM / engine / Runtime / Bus import. It is
+ * host-neutral and node-testable: hosts (the notebook-pane in-app) import this one
+ * helper and NONE inlines the template (the §router single-path-authority rule applied to the view-entry
+ * template). It is the SIBLING of `setup-builder.js` for the generic `view` cell,
+ * and it REUSES setup-builder's export-resolution + module-resolution helpers (DRY —
+ * one single-export-else-FAIL-LOUD authority, one in-memory-module-set resolver).
+ *
+ * ── What it does ─────────────────────────────────────────────────────────────
+ *
+ * Given a view declaration — `module="<module-name>#<exportName>"` — and the
+ * notebook's user-code module SET (`{ name → source }`), it returns the canonical
+ * VIEW-ENTRY SOURCE STRING + the realm-internal output name. The entry imports the
+ * user render module by name and RETURNS its render export under the realm-internal
+ * output name:
+ *
+ *   import { <export> } from '<module>';
+ *   return { <outName>: <export> };
+ *
+ * `Runtime.runCell` runs THIS entry IN THE REALM (the SAME executor + module-compile
+ * path the declared canvas uses). The entry's `import { <export> } from '<module>'`
+ * resolves against the notebook's in-memory module closure; the USER module's OWN
+ * `import * as d3 from 'd3'` bare-specifier imports resolve via the realm's injected
+ * 2a import-map (bare specifiers pass through the blob-module rewrite verbatim — see
+ * module-resolver `rewriteRelativeToSiblingBlobs`, "bare → host loader"). The render
+ * export is returned as a LIVE realm-internal ref (NOT a kernel binding, NOT crossed
+ * over the data plane) — exactly as the declared-canvas synthesis returns a live
+ * `runner` ref. The HOST then invokes `renderExport(ctx)` with the view `ctx`
+ * (mount + frozen handle + binding seam) it assembles realm-side (see view-ctx.js).
+ *
+ * ── single-export resolution (FAIL-LOUD, never guess) ─────────────────────────
+ *
+ * `#export` may be omitted ONLY when the named module has EXACTLY ONE export. Zero or
+ * multiple exports → FAIL-LOUD with a precise message (never a guess). This reuses
+ * setup-builder's `moduleExportNames` + the same resolution discipline (C5 mirror).
+ *
+ * ── the import resolves against the in-memory module closure ──────────────────
+ *
+ * The emitted `import` uses the DECLARED module name (e.g. `'./views/d3-bars.js'`),
+ * resolved against the notebook's `moduleSet()` via the existing in-memory blob
+ * closure. An unknown/missing module → FAIL-LOUD HERE so the caller never ships an
+ * entry that 404s the relative import downstream.
+ */
+
+'use strict';
+
+import { canonKey } from './module-resolver.js';
+import { moduleExportNames } from './setup-builder.js';
+
+/* ── parse "<module-name>#<exportName>" ──────────────────────────────────────── */
+
+/**
+ * Split the view module declaration into `{ moduleName, exportName }`. The
+ * `exportName` is the substring after the FIRST '#'; absent → ''. The `moduleName`
+ * is verbatim (kept with its relative './…' prefix so the emitted import matches the
+ * module cell name the closure is keyed by).
+ *
+ * @param {string} moduleDecl — `"<module-name>#<exportName>"` (exportName optional).
+ * @returns {{ moduleName: string, exportName: string }}
+ * @throws {Error} FAIL-LOUD on an empty declaration or a declaration with no module name.
+ */
+export function parseViewDeclaration(moduleDecl) {
+    if (typeof moduleDecl !== 'string' || !moduleDecl.trim()) {
+        throw new Error(
+            '[view-builder] a `view` cell requires a `module="<module-name>#<exportName>"` ' +
+            'attribute (got: ' + JSON.stringify(moduleDecl) + '). (FAIL-LOUD.)'
+        );
+    }
+    var s = moduleDecl.trim();
+    var hash = s.indexOf('#');
+    var moduleName = (hash === -1) ? s : s.slice(0, hash);
+    var exportName = (hash === -1) ? '' : s.slice(hash + 1);
+    moduleName = moduleName.trim();
+    exportName = exportName.trim();
+    if (!moduleName) {
+        throw new Error(
+            '[view-builder] `module` declaration "' + moduleDecl + '" has no module name ' +
+            'before the "#". Expected "<module-name>#<exportName>". (FAIL-LOUD.)'
+        );
+    }
+    return { moduleName: moduleName, exportName: exportName };
+}
+
+/* ── resolve the module source from the module set ───────────────────────────── */
+
+// Look the declared module up in the module set, matching by canonical key so
+// './views/x.js' and 'views/x.js' resolve the same. FAIL-LOUD on absence.
+function _resolveModuleSource(moduleName, modules) {
+    var set = modules || {};
+    if (Object.prototype.hasOwnProperty.call(set, moduleName)) { return set[moduleName]; }
+    var wantKey = canonKey(moduleName);
+    var keys = Object.keys(set);
+    for (var i = 0; i < keys.length; i++) {
+        if (canonKey(keys[i]) === wantKey) { return set[keys[i]]; }
+    }
+    throw new Error(
+        '[view-builder] declared view module "' + moduleName + '" is not a ' +
+        '`type="module"` cell in this notebook (known modules: [' + keys.join(', ') +
+        ']). (FAIL-LOUD — the `view` cell references an editable in-notebook module ' +
+        'cell, never an opaque by-name load.)'
+    );
+}
+
+/* ── resolve the export name (single-export-else-FAIL-LOUD) ───────────────────── */
+
+// Return the export name to import: the explicit `exportName` when given (verified
+// present); otherwise the module's SOLE export. Zero or multiple exports with no
+// explicit `#export` → FAIL-LOUD (never guess). Mirrors setup-builder's C5 rule.
+function _resolveExportName(moduleName, exportName, source) {
+    var exports = moduleExportNames(source);
+    if (exportName) {
+        if (exports.indexOf(exportName) === -1) {
+            throw new Error(
+                '[view-builder] declared view export "' + exportName + '" is not exported ' +
+                'by module "' + moduleName + '" (its exports: [' + exports.join(', ') +
+                ']). (FAIL-LOUD.)'
+            );
+        }
+        return exportName;
+    }
+    if (exports.length === 1) { return exports[0]; }
+    if (exports.length === 0) {
+        throw new Error(
+            '[view-builder] view module "' + moduleName + '" has NO named export — ' +
+            'declare `module="' + moduleName + '#<exportName>"` once the module exports a ' +
+            'render function. (FAIL-LOUD — never guess.)'
+        );
+    }
+    throw new Error(
+        '[view-builder] view module "' + moduleName + '" has MULTIPLE exports [' +
+        exports.join(', ') + '] — the `#export` part of `module` is required to pick one ' +
+        '(e.g. module="' + moduleName + '#' + exports[0] + '"). (FAIL-LOUD — never guess.)'
+    );
+}
+
+/* ── the synthesis (SOLE authority) ──────────────────────────────────────────── */
+
+/**
+ * synthesizeViewEntrySource — turn a `view` cell declaration into the canonical
+ * VIEW-ENTRY source string + the realm-internal output name.
+ *
+ * @param {object} decl
+ * @param {string} decl.module — `"<module-name>#<exportName>"` (exportName optional).
+ * @param {Object<string,string>} decl.modules — the notebook module set `{ name → source }`,
+ *   used to resolve a single export + verify the module exists.
+ * @param {string} [decl.outName] — realm-internal output name; default `'_view'`.
+ * @returns {{ entryCode: string, outName: string, moduleName: string, exportName: string }}
+ * @throws {Error} FAIL-LOUD on a missing module / unknown export / zero-or-multiple
+ *   exports with no `#export`.
+ */
+export function synthesizeViewEntrySource(decl) {
+    decl = decl || {};
+    var parsed = parseViewDeclaration(decl.module);
+    var source = _resolveModuleSource(parsed.moduleName, decl.modules);
+    var exportName = _resolveExportName(parsed.moduleName, parsed.exportName, source);
+
+    // The realm-internal output name is emitted as an UNQUOTED object key in the
+    // synthesized `return { <outName>: <export> }`. Callers pass `cell.id + '_view'`,
+    // and notebook cell ids contain hyphens (e.g. `c-d3-view`) — a bare hyphen in a
+    // key is a SyntaxError. Sanitize to a valid JS identifier (it is realm-internal,
+    // never user-referenced, so the exact spelling does not matter — only that it is a
+    // legal key and that the value we RETURN as `outName` matches the key the template
+    // emits, so the caller's `result.outputs[outName]` lookup hits). Mirrors
+    // setup-builder's outName sanitization (the hyphen bug class).
+    var rawOutName = decl.outName || '_view';
+    var outName = String(rawOutName).replace(/[^A-Za-z0-9_$]/g, '_');
+    if (/^[0-9]/.test(outName)) { outName = '_' + outName; }
+
+    // The canonical VIEW-ENTRY template. The synthesized entry:
+    //   - imports the editable in-notebook view module's render export by name,
+    //   - returns it as a realm-internal LIVE ref (the host invokes it with the ctx).
+    // The USER module's OWN bare-specifier imports (e.g. `import * as d3 from 'd3'`)
+    // resolve via the realm's injected 2a import-map — they are not rewritten here.
+    var entryCode =
+        "import { " + exportName + " } from '" + parsed.moduleName + "';\n" +
+        "return { " + outName + ": " + exportName + " };\n";
+
+    return {
+        entryCode: entryCode,
+        outName: outName,
+        moduleName: parsed.moduleName,
+        exportName: exportName
+    };
+}

package/dist/shim/notebook/view-ctx.js

@@ -0,0 +1,100 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * view-ctx — the SOLE authority that assembles the `view` cell CONTEXT object handed
+ * to a user render module's export (WS-NOTEBOOK-VENDOR-VIEW Phase 2b).
+ *
+ * Named ESM export. PURE module — NO DOM / engine / Runtime / Bus import. It is a
+ * THIN convenience WRAPPER over the EXISTING frozen ViewHandle + the realm→kernel
+ * binding seam; it introduces NO new handle shape (the design's hard constraint). It
+ * is host-neutral + node-testable: a test passes a FAKE handle + a plain object as
+ * the `mount` + fake binding callbacks and asserts the ctx verbs delegate correctly
+ * and that `commit` enforces serializability (VETO-CLASS #1) — WITHOUT a DOM.
+ *
+ * The user render function is invoked as `render(ctx)` where `ctx` is:
+ *
+ *   {
+ *     mount,        // DOM element inside the realm host (the view's render target)
+ *     handle,       // the frozen ViewHandle for THIS realm (on/call/start/stop/step/dispose)
+ *     on,           // convenience = handle.on  (SAME-CELL local tick stream)
+ *     call,         // convenience = handle.call
+ *     getBinding,   // (name) → the kernel binding value for an `in` name (data IN)
+ *     commit,       // (name, value) → commit a `produces` value (data OUT, serializable-asserted)
+ *     imports,      // optional: pre-resolved blessed modules (e.g. { makeChartEnv } for liveChart)
+ *   }
+ *
+ * `mount`/`handle`/`on`/`call` are LIVE refs (the same realm trust zone the canvas
+ * builder runs in). `getBinding`/`commit` are the kernel binding seam: `getBinding`
+ * reads from a host-supplied resolver (the host pre-resolves `in` bindings before
+ * invoking render); `commit` routes a serializable value through a host-supplied
+ * commit callback (in-app: kernel.commitViewOutputs),
+ * asserting serializability HERE (FAIL-LOUD on a non-serializable commit — the same
+ * gate the frozen handle's data plane enforces).
+ */
+
+'use strict';
+
+import { assertSerializable } from './view-handle.js';
+
+/**
+ * makeViewCtx(opts) → ctx
+ *
+ * @param {object} opts
+ * @param {*} opts.mount — the view's DOM render target (a live element; opaque here).
+ * @param {object} opts.handle — the frozen ViewHandle for the booted realm (REQUIRED;
+ *   must expose `on` + `call`). The ctx NEVER reshapes it — it is passed through and
+ *   its `on`/`call` are surfaced as convenience refs.
+ * @param {(name: string) => *} [opts.getBinding] — resolve an `in` binding value by
+ *   name. Default: a resolver over `opts.bindings` (a plain `{ name → value }` map);
+ *   absent name → `undefined` (the host validated `in` presence before invoking).
+ * @param {Object<string,*>} [opts.bindings] — pre-resolved `in` bindings (used by the
+ *   default getBinding when no explicit resolver is supplied).
+ * @param {(name: string, value: *) => void} [opts.commit] — host commit callback
+ *   (in-app: kernel.commitViewOutputs). When absent,
+ *   `commit` FAILS LOUD (a view that declares `produces` requires a commit sink).
+ * @param {Object<string,*>} [opts.imports] — pre-resolved blessed modules.
+ * @returns {object} the view ctx.
+ * @throws {Error} FAIL-LOUD if `handle` is missing `on`/`call`.
+ */
+export function makeViewCtx(opts) {
+    opts = opts || {};
+    var mount = opts.mount;
+    var handle = opts.handle;
+    if (!handle || typeof handle.on !== 'function' || typeof handle.call !== 'function') {
+        throw new Error('[view-ctx] requires a frozen ViewHandle with on()/call(). (FAIL-LOUD.)');
+    }
+
+    var bindings = opts.bindings || {};
+    var getBinding = (typeof opts.getBinding === 'function')
+        ? opts.getBinding
+        : function (name) {
+            return Object.prototype.hasOwnProperty.call(bindings, name) ? bindings[name] : undefined;
+        };
+
+    var commitSink = (typeof opts.commit === 'function') ? opts.commit : null;
+    function commit(name, value) {
+        if (typeof name !== 'string' || !name) {
+            throw new Error('[view-ctx] commit: name must be a non-empty string. (FAIL-LOUD.)');
+        }
+        if (!commitSink) {
+            throw new Error('[view-ctx] commit("' + name + '"): no commit sink wired for this ' +
+                'view (declare a `produces` binding + supply a host commit callback). (FAIL-LOUD.)');
+        }
+        // VETO-CLASS #1: a committed value MUST be structured-clone-serializable (it
+        // crosses into the kernel binding store, which a marshalling host may carry).
+        assertSerializable(value, 'view commit("' + name + '") value');
+        commitSink(name, value);
+    }
+
+    return {
+        mount: mount,
+        handle: handle,
+        // convenience refs over the frozen handle — bind so a destructured `on`/`call`
+        // keeps the handle as `this` is irrelevant (the handle methods are closures).
+        on: function (event, cb) { return handle.on(event, cb); },
+        call: function (fn, args) { return handle.call(fn, args); },
+        getBinding: getBinding,
+        commit: commit,
+        imports: opts.imports || {}
+    };
+}