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

package/dist/shim/controls/registry.js

@@ -0,0 +1,274 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/controls/registry — the runtime-registerable instance registry
+ * ("Instance addressing").
+ *
+ * Sugar objects (`SphereEmitter`, `Tube`, a future `*Layer` class, …) and their
+ * declared control descriptors (`lib/shim/controls/index.js` shapes) need a
+ * NAMED, runtime-addressable catalog: a page may host MULTIPLE same-kind
+ * instances (two `SphereEmitter`s, two `Tube`s) and must add objects/controls
+ * dynamically (not only at `setup()` time) — named lookup + enumeration,
+ * FAIL-LOUD on an id collision or an unknown-id lookup (never a silent
+ * overwrite or a silent `undefined`).
+ *
+ * ── FACTORY, not a singleton ─────────────────────────────────────────────────
+ *
+ * Unlike `lib/shim/notebook/realm-registry.js` (a process-global singleton —
+ * appropriate there because there is conceptually ONE catalog of realm KINDS
+ * for the whole session), `makeControlRegistry()` is a FACTORY: each call
+ * returns an ISOLATED registry instance. A page hosting two independent
+ * experiment runners side-by-side (e.g. the Physics Compare / GYM view, which
+ * runs a JS engine and a WASM engine simultaneously) must not have one
+ * runner's object named `"tube"` collide with the other runner's own `"tube"` —
+ * each runner/experiment owns its OWN registry instance (mirrors the
+ * `makeFrqtlHandle`/`makeChartHandle`/`makeViewHandle` factory precedent in
+ * `lib/shim/notebook/`, not the single-catalog `realm-registry.js` precedent —
+ * the difference being INSTANCES-per-scene vs KINDS-for-the-session).
+ *
+ * Two independent catalogs share one registry instance: OBJECTS (sugar object
+ * instances) and CONTROLS (their declared control-descriptor arrays,
+ * normalized via `normalizeControlDescriptor`). A name may be registered in
+ * either catalog, both, or neither — an object without controls, or a bare
+ * control array with no backing object instance, are both legal.
+ *
+ * Usage:
+ *   import { makeControlRegistry } from 'lib/shim/controls/registry.js';
+ *   const registry = makeControlRegistry();
+ *   registry.registerObject('source', sphereEmitter, 'SphereEmitter');
+ *   registry.registerControls('source', sphereEmitter.controls);
+ *   // … later, dynamically, from anywhere holding `registry`:
+ *   registry.getObject('muzzleEmitter').setActive(false);
+ *   registry.getControls('muzzleEmitter').forEach(c => host.render(c));
+ */
+
+import * as ControlsSchema from './index.js';
+
+
+
+    function _isValidName(name) {
+        return typeof name === 'string' && name.length > 0;
+    }
+
+    /**
+     * makeControlRegistry() → a fresh, isolated registry instance.
+     *
+     * @returns {{
+     *   registerObject: (name:string, instance:*, kind?:string) => void,
+     *   getObject: (name:string) => *,
+     *   getObjectKind: (name:string) => string|null,
+     *   hasObject: (name:string) => boolean,
+     *   objectNames: () => string[],
+     *   unregisterObject: (name:string) => void,
+     *   registerControls: (name:string, descriptors:object[]) => object[],
+     *   getControls: (name:string) => object[],
+     *   hasControls: (name:string) => boolean,
+     *   controlNames: () => string[],
+     *   unregisterControls: (name:string) => void,
+     *   allControls: () => Object<string, object[]>
+     * }}
+     */
+    function makeControlRegistry() {
+        // name -> { instance, kind } — the OBJECT catalog.
+        var _objects = Object.create(null);
+        // name -> normalized descriptor[] — the CONTROLS catalog.
+        var _controls = Object.create(null);
+
+        // ── Objects ──────────────────────────────────────────────────────────
+
+        /**
+         * Register a sugar-object instance under a name.
+         *
+         * @param {string} name — a non-empty, registry-unique addressing key.
+         * @param {*} instance — the live object (a SphereEmitter, Tube, LargeObject, …).
+         * @param {string} [kind] — a free-form label (e.g. 'SphereEmitter') for
+         *   diagnostics/enumeration; not validated against any closed vocabulary
+         *   (sugar-object KINDS are open-ended, unlike control-descriptor KINDS).
+         * @throws {Error} FAIL-LOUD on an invalid/empty name, a missing instance,
+         *   or a name already registered (never a silent overwrite).
+         */
+        function registerObject(name, instance, kind) {
+            if (!_isValidName(name)) {
+                throw new Error('[controls/registry] registerObject: name must be a non-empty ' +
+                    'string; got ' + JSON.stringify(name) + '. (FAIL-LOUD.)');
+            }
+            if (instance === undefined || instance === null) {
+                throw new Error('[controls/registry] registerObject("' + name +
+                    '"): instance must not be null/undefined. (FAIL-LOUD.)');
+            }
+            if (_objects[name]) {
+                throw new Error('[controls/registry] registerObject: id collision — "' + name +
+                    '" is already registered (existing kind: "' + (_objects[name].kind || 'unknown') +
+                    '"). Call unregisterObject("' + name + '") first, or choose a different name. ' +
+                    '(FAIL-LOUD — never a silent overwrite.)');
+            }
+            _objects[name] = { instance: instance, kind: kind || null };
+        }
+
+        /**
+         * Resolve a registered object instance.
+         * @throws {Error} FAIL-LOUD if `name` is not registered.
+         */
+        function getObject(name) {
+            var rec = _objects[name];
+            if (!rec) {
+                throw new Error('[controls/registry] getObject: no object registered for "' +
+                    String(name) + '". Registered: [' + objectNames().join(', ') + ']. (FAIL-LOUD.)');
+            }
+            return rec.instance;
+        }
+
+        /**
+         * Resolve a registered object's `kind` label (gym-controls-as-sugar
+         * binds+ControlSync FINAL design — objects-side bind execution needs BOTH
+         * the instance (`getObject`, unchanged) AND its kind, to route a scalar
+         * descriptor's `bind.object` to the correct property-accessor family
+         * (Frame → getFrameProperty/setFrameProperty; LargeObject → updateObjectProperty).
+         * Additive — `getObject` keeps returning the bare instance, unchanged, for
+         * every existing caller.
+         * @throws {Error} FAIL-LOUD if `name` is not registered (mirrors `getObject`).
+         */
+        function getObjectKind(name) {
+            var rec = _objects[name];
+            if (!rec) {
+                throw new Error('[controls/registry] getObjectKind: no object registered for "' +
+                    String(name) + '". Registered: [' + objectNames().join(', ') + ']. (FAIL-LOUD.)');
+            }
+            return rec.kind;
+        }
+
+        /** hasObject(name) — non-throwing presence check. */
+        function hasObject(name) { return !!_objects[name]; }
+
+        /** objectNames() — registered object names (diagnostics/enumeration). */
+        function objectNames() { return Object.keys(_objects); }
+
+        /**
+         * Remove a registered object (frees the name for re-registration).
+         * @throws {Error} FAIL-LOUD if `name` is not registered — an unregister of
+         *   an unknown name is a caller bug, never a silent no-op.
+         */
+        function unregisterObject(name) {
+            if (!_objects[name]) {
+                throw new Error('[controls/registry] unregisterObject: no object registered ' +
+                    'for "' + String(name) + '". (FAIL-LOUD.)');
+            }
+            delete _objects[name];
+        }
+
+        // ── Controls ─────────────────────────────────────────────────────────
+
+        /**
+         * Register a named array of control descriptors. Each descriptor is
+         * normalized via `normalizeControlDescriptor` (throw-or-apply — a
+         * malformed descriptor anywhere in the array fails the WHOLE call,
+         * nothing partial is committed).
+         *
+         * @param {string} name — a non-empty, registry-unique addressing key
+         *   (independent of the OBJECTS catalog's namespace — an object and its
+         *   controls conventionally share the same name, but this is
+         *   convention, not enforced).
+         * @param {object[]} descriptors — candidate control descriptors (see
+         *   `lib/shim/controls/index.js` KINDS for the accepted shapes).
+         * @returns {object[]} the normalized descriptor array (NOT the same
+         *   array reference as the input — mirrors normalizeControlDescriptor's
+         *   never-mutate-the-input discipline).
+         * @throws {Error} FAIL-LOUD on an invalid/empty name, a name already
+         *   registered, a non-array `descriptors`, a duplicate `id` WITHIN the
+         *   array, or any descriptor that fails `normalizeControlDescriptor`.
+         */
+        function registerControls(name, descriptors) {
+            if (!_isValidName(name)) {
+                throw new Error('[controls/registry] registerControls: name must be a ' +
+                    'non-empty string; got ' + JSON.stringify(name) + '. (FAIL-LOUD.)');
+            }
+            if (_controls[name]) {
+                throw new Error('[controls/registry] registerControls: id collision — "' + name +
+                    '" already has controls registered. Call unregisterControls("' + name +
+                    '") first, or choose a different name. (FAIL-LOUD — never a silent overwrite.)');
+            }
+            if (!Array.isArray(descriptors)) {
+                throw new Error('[controls/registry] registerControls("' + name +
+                    '"): descriptors must be an array. (FAIL-LOUD.)');
+            }
+            var normalized = [];
+            var seenIds = Object.create(null);
+            for (var i = 0; i < descriptors.length; i++) {
+                var bag = ControlsSchema.normalizeControlDescriptor(descriptors[i]);
+                if (seenIds[bag.id]) {
+                    throw new Error('[controls/registry] registerControls("' + name +
+                        '"): duplicate control id "' + bag.id + '" within the same array at ' +
+                        'index ' + i + '. (FAIL-LOUD.)');
+                }
+                seenIds[bag.id] = true;
+                normalized.push(bag);
+            }
+            _controls[name] = normalized;
+            return normalized;
+        }
+
+        /**
+         * Resolve a registered controls array.
+         * @throws {Error} FAIL-LOUD if `name` is not registered.
+         */
+        function getControls(name) {
+            var arr = _controls[name];
+            if (!arr) {
+                throw new Error('[controls/registry] getControls: no controls registered ' +
+                    'for "' + String(name) + '". Registered: [' + controlNames().join(', ') +
+                    ']. (FAIL-LOUD.)');
+            }
+            return arr;
+        }
+
+        /** hasControls(name) — non-throwing presence check. */
+        function hasControls(name) { return !!_controls[name]; }
+
+        /** controlNames() — registered control-array names (diagnostics/enumeration). */
+        function controlNames() { return Object.keys(_controls); }
+
+        /**
+         * Remove a registered controls array (frees the name for re-registration).
+         * @throws {Error} FAIL-LOUD if `name` is not registered.
+         */
+        function unregisterControls(name) {
+            if (!_controls[name]) {
+                throw new Error('[controls/registry] unregisterControls: no controls ' +
+                    'registered for "' + String(name) + '". (FAIL-LOUD.)');
+            }
+            delete _controls[name];
+        }
+
+        /**
+         * allControls() — a snapshot map `{ name: descriptor[] }` of every
+         * registered controls array (for a future host that enumerates
+         * everything without knowing names ahead of time — e.g. the
+         * control panel).
+         * @returns {Object<string, object[]>}
+         */
+        function allControls() {
+            var out = {};
+            var names = controlNames();
+            for (var i = 0; i < names.length; i++) { out[names[i]] = _controls[names[i]]; }
+            return out;
+        }
+
+        return {
+            registerObject:     registerObject,
+            getObject:          getObject,
+            getObjectKind:      getObjectKind,
+            hasObject:          hasObject,
+            objectNames:        objectNames,
+            unregisterObject:   unregisterObject,
+            registerControls:   registerControls,
+            getControls:        getControls,
+            hasControls:        hasControls,
+            controlNames:       controlNames,
+            unregisterControls: unregisterControls,
+            allControls:        allControls
+        };
+    }
+
+    // ── Export ────────────────────────────────────────────────────────────────
+
+export { makeControlRegistry };

package/dist/shim/engine/artifact-shell.js

@@ -0,0 +1,211 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * artifact-shell.js — pure generator for the claude.ai Artifact host shell.
+ *
+ * The "artifact host shell" is a SINGLE self-contained HTML file a user pastes
+ * into a claude.ai chat as an Artifact. It has no server, no build step, no
+ * relative-file dependencies of its own — every asset it needs is fetched from
+ * `cdn.jsdelivr.net/npm/` (the ONLY non-`self` script-src origin this shell
+ * needs; see §1 of the design doc for the full captured CSP).
+ *
+ * This module is PURE (no DOM, no browser globals) and node-testable. It has
+ * exactly two responsibilities, kept separate so the "never hand-drifted"
+ * requirement is mechanically enforced rather than asserted in prose:
+ *
+ *   buildArtifactImportMap()   — the ONE import-map entry the shell embeds,
+ *                                 derived from router.js's CDN_BASE (the single
+ *                                 CDN path authority — never a second hand-typed
+ *                                 jsdelivr URL literal).
+ *   renderArtifactShellHtml()  — the full HTML document text, calling
+ *                                 buildArtifactImportMap() internally (so the
+ *                                 embedded `<script type="importmap">` can never
+ *                                 drift from the generator — a conformance test
+ *                                 asserts this by construction, see
+ *                                 lib/shim/engine/test/artifact-shell.test.mjs).
+ *
+ * WHAT the import map holds (and why it never lists engine/renderer files): the shell's inline
+ * `<script type="module">` imports `bootScene` from `'@descix/frqtl-web/boot'` (the package's scene doors,
+ * lib/frqtl/experiments/_shared/doors.js) — everything the boot loads (engine, renderer, game layer)
+ * resolves relative to that module's own URL — and the embedded scene imports its parts by the
+ * published self-reference. Both come from the ONE specifier table (`pageImportMapFor`). Growing this
+ * map by hand per script would re-enumerate the module graph by hand — the schema-mirror-drift
+ * anti-pattern.
+ *
+ * CSP notes baked into the generated HTML (never re-derive elsewhere):
+ *   - NO `blob:` module imports (forbidden by the captured CSP's script-src).
+ *   - NO script/style/font origin outside the allowlist in the design doc §1
+ *     (jsdelivr/npm, cdnjs, claudeusercontent, tailwindcss CDN, jquery CDN) —
+ *     this shell in fact uses ONLY jsdelivr/npm plus inline scripts/styles
+ *     ('unsafe-inline' is granted), so it is a strict subset of the allowlist.
+ *   - The inline `<script type="module">` and the `<script type="importmap">`
+ *     are both confirmed-PASS under this exact CSP (Step 0, design doc §1).
+ */
+
+'use strict';
+
+import { CDN_BASE } from './router.js';
+import { pageImportMapFor, FRQTL_WEB_BOOT } from '../project/specifiers.js';
+
+/**
+ * The bare-specifier import map the artifact shell embeds: the ONE table, `pageImportMapFor(<the dist
+ * root>/)` (lib/shim/project/specifiers.js) — the scene doors (`@descix/frqtl-web/boot`) and the sketch's
+ * self-reference rows, at their lib-identity paths under the dist root, so the embedded scene's imports
+ * resolve to the SAME module URLs the boot loads.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.base] - The dist base (default `CDN_BASE` from router.js): the absolute URL
+ *   (no trailing slash) of an unmodified copy of the package's dist/ tree. The PUBLISHED shell
+ *   (`sdk/frqtl-web/build.js`) never passes it; the local mirror
+ *   (`sdk/frqtl-web/scripts/serve-local-cdn-mirror.mjs`) does.
+ * @returns {{imports: Object<string,string>}}
+ */
+export function buildArtifactImportMap(opts) {
+    opts = opts || {};
+    var base = opts.base !== undefined ? opts.base : CDN_BASE;
+    return pageImportMapFor(base + '/');
+}
+
+/**
+ * The scene the artifact shell boots — a frqtl-relative scene file (lib/frqtl/<ARTIFACT_SCENE>).
+ * The generator is pure: its caller reads this file and hands the TEXT in (`opts.sceneSource`),
+ * and the page embeds it verbatim. The scene is its one home; its constants are its knobs.
+ */
+export var ARTIFACT_SCENE = 'scenes/double-slit.js';
+
+/**
+ * The bounded wait an artifact page gives its boot before it FAILS LOUD. An SDK entry that never
+ * loads (a 404, an unreachable CDN, an unpublished pin) runs NO code, so nothing inside the module
+ * can report it — without this deadline the page sits on "booting FRQTL…" forever. The authored
+ * sdk/frqtl-web/src/artifact/sun.html carries BOOT_DEADLINE_MARKER, where the build splices
+ * bootDeadlineScript() — one script, one number.
+ */
+export var ARTIFACT_BOOT_DEADLINE_MS = 30000;
+
+/** Where an AUTHORED artifact page (sun.html) takes the deadline script: the build splices it here. */
+export var BOOT_DEADLINE_MARKER = '<!-- FRQTL:BOOT-DEADLINE -->';
+
+/**
+ * The classic deadline script (runs whether or not the module ever loads). On expiry with no live
+ * boot it stamps `data-egpt-boot-timeout="1"` on #frqtl-status, names the entry the page boots from
+ * (the import map's `@descix/frqtl-web/boot` row, else the frqtl-web.min.js <script>), and logs it. The module sets `window.__frqtlLive = true` once the boot resolves.
+ * @returns {string} a `<script>…</script>` element
+ */
+export function bootDeadlineScript() {
+    return (
+'<script>\n' +
+'  /* BOOT DEADLINE — lib/shim/engine/artifact-shell.js ARTIFACT_BOOT_DEADLINE_MS. */\n' +
+'  setTimeout(function () {\n' +
+'    if (window.__frqtlLive) { return; }\n' +
+'    var map = document.querySelector(\'script[type="importmap"]\');\n' +
+'    var min = document.querySelector(\'script[src$="frqtl-web.min.js"]\');\n' +
+'    var entry = min ? min.src : \'(no import map)\';\n' +
+'    try { if (map) { entry = new URL(JSON.parse(map.textContent).imports[\'' + FRQTL_WEB_BOOT.specifier + '\'], document.baseURI).href; } } catch (e) { /* the message names the absence */ }\n' +
+'    var msg = \'FRQTL BOOT TIMEOUT — not live after \' + (' + ARTIFACT_BOOT_DEADLINE_MS + ' / 1000) + \' s: the SDK entry \' + entry +\n' +
+'      \' did not load, or its boot never reached a first tick.\';\n' +
+'    var el = document.getElementById(\'frqtl-status\');\n' +
+'    if (el) { el.textContent = msg; el.setAttribute(\'data-egpt-boot-timeout\', \'1\'); }\n' +
+'    if (window.console && console.error) { console.error(\'[frqtl-artifact]\', msg); }\n' +
+'  }, ' + ARTIFACT_BOOT_DEADLINE_MS + ');\n' +
+'</script>\n'
+    );
+}
+
+/**
+ * Render the complete, self-contained artifact host shell HTML.
+ *
+ * The document boots the scene file's sketch (ARTIFACT_SCENE, embedded VERBATIM) via
+ * `bootScene()` — the scene doors (lib/frqtl/experiments/_shared/doors.js) — into a mount div.
+ * FAIL-LOUD: `bootScene`'s own promise rejection is caught here and surfaced in the status
+ * line; `bootScene` itself paints a detailed error overlay inside the mount div on any
+ * load/compile/engine failure (never a silent blank canvas).
+ *
+ * The shell writes NO size: the mount is `width:fit-content`, sized by the canvas the scene's
+ * co-init call creates.
+ *
+ * WHERE THE PACKAGE COMES FROM (`opts.host`):
+ *   'cdn'  (default) — the import map is the jsdelivr pin (buildArtifactImportMap; `opts.base`
+ *          re-anchors it): the self-contained page a user pastes into a claude.ai Artifact.
+ *   'dist' — the import map is page-relative, `pageImportMapFor('../')` (placed by the build like
+ *          sun.html's): the page the package ships boots against WHATEVER dist serves it.
+ * Either way the doors locate every file they load relative to their own URL, and the page carries a
+ * bounded boot DEADLINE (bootDeadlineScript): a silent hang fails loud.
+ *
+ * @param {object} opts
+ * @param {string} opts.sceneSource     - REQUIRED: the text of lib/frqtl/<ARTIFACT_SCENE>, a sketch
+ *   module (`export default function buildExperiment(exp)`), inlined into the page's module script —
+ *   its imports resolve through the page's import map. Missing, or defining no buildExperiment, THROWS.
+ * @param {number} [opts.seed=42]        - RNG seed.
+ * @param {string} [opts.base]           - Forwarded to `buildArtifactImportMap` (a 'cdn' page re-anchored
+ *   at a self-hosted dist root). Omitted by the published shell.
+ * @returns {string} the full `<!DOCTYPE html>...</html>` document text.
+ */
+export function renderArtifactShellHtml(opts) {
+    opts = opts || {};
+    var sceneSource = opts.sceneSource;
+    if (typeof sceneSource !== 'string' || !sceneSource.trim()) {
+        throw new Error('[artifact-shell] renderArtifactShellHtml needs opts.sceneSource — the text of lib/frqtl/' +
+            ARTIFACT_SCENE + ' (the caller reads the file; this generator is pure). (FAIL-LOUD.)');
+    }
+    if (!/function buildExperiment\s*\(/.test(sceneSource)) {
+        throw new Error('[artifact-shell] opts.sceneSource defines no `function buildExperiment(exp)` — it must be the ' +
+            'scene file ' + ARTIFACT_SCENE + '. (FAIL-LOUD.)');
+    }
+    var seed       = opts.seed !== undefined ? opts.seed : 42;
+    var host = opts.host === undefined ? 'cdn' : opts.host;
+    if (host !== 'cdn' && host !== 'dist') {
+        throw new Error('[artifact-shell] opts.host must be "cdn" or "dist" (got ' + JSON.stringify(host) + '). (FAIL-LOUD.)');
+    }
+    if (host === 'dist' && opts.base) {
+        throw new Error('[artifact-shell] opts.base re-anchors the CDN pin; a "dist" page anchors at its own entry. (FAIL-LOUD.)');
+    }
+    var importMapJson = JSON.stringify(host === 'dist' ? pageImportMapFor('../') : buildArtifactImportMap(opts));
+
+    return (
+'<!DOCTYPE html>\n' +
+'<!-- Copyright 2023-2026 by Essam Abadir -->\n' +
+'<!-- FRQTL — claude.ai Artifact host shell (ws-artifact-showcase Bite A2).\n' +
+'     Generated by lib/shim/engine/artifact-shell.js — DO NOT hand-edit.\n' +
+'     Paste this ENTIRE file into a claude.ai chat as an Artifact (type: HTML). -->\n' +
+'<html lang="en">\n' +
+'<head>\n' +
+'<meta charset="UTF-8">\n' +
+'<meta name="viewport" content="width=device-width, initial-scale=1">\n' +
+'<title>FRQTL — Double-Slit (live)</title>\n' +
+'<style>\n' +
+'  html,body{margin:0;padding:0;background:#0b0b0b;color:#c9c9c9;font-family:ui-monospace,Menlo,Consolas,monospace;}\n' +
+'  #frqtl-status{text-align:center;font-size:12px;color:#888;padding:10px 0 4px;}\n' +
+'  #frqtl-mount{width:fit-content;margin:0 auto 24px;position:relative;}\n' +
+'</style>\n' +
+'</head>\n' +
+'<body>\n' +
+'<div id="frqtl-status" data-role="frqtl-artifact-status">booting FRQTL…</div>\n' +
+'<div id="frqtl-mount" data-role="frqtl-artifact-mount"></div>\n' +
+'<script type="importmap">' + importMapJson + '</script>\n' +
+bootDeadlineScript() +
+'<script type="module">\n' +
+'  import { bootScene } from \'' + FRQTL_WEB_BOOT.specifier + '\';\n' +
+'  var statusEl = document.getElementById(\'frqtl-status\');\n' +
+'  var tickCount = 0;\n' +
+sceneSource.replace(/\s*$/, '') + '\n' +
+'  bootScene(\'frqtl-mount\', buildExperiment, {\n' +
+'    seed: ' + seed + ',\n' +
+'    onTick: function () {\n' +
+'      tickCount++;\n' +
+'      if (tickCount % 20 === 0) {\n' +
+'        statusEl.textContent = \'FRQTL double-slit — live — tick \' + tickCount;\n' +
+'      }\n' +
+'    }\n' +
+'  }).then(function () {\n' +
+'    window.__frqtlLive = true;\n' +
+'    statusEl.textContent = \'FRQTL double-slit — live\';\n' +
+'  }).catch(function (err) {\n' +
+'    window.__frqtlLive = true;   // failed LOUDLY already — the deadline has nothing to add\n' +
+'    statusEl.textContent = \'FRQTL boot FAILED — see overlay below.\';\n' +
+'    if (window.console && console.error) { console.error(\'[frqtl-artifact]\', err); }\n' +
+'  });\n' +
+'</script>\n' +
+'</body>\n' +
+'</html>\n'
+    );
+}

package/dist/shim/engine/boot-phases.js

@@ -0,0 +1,44 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * boot-phases.js — THE vocabulary of a FRQTL page boot, in order.
+ *
+ * The boot record (lib/frqtl/experiments/_shared/boot.js `createBootRecord`) is written in these
+ * phases; a progress UI (lib/components/run-once-card, lib/features/ide/frame-boot-progress.js)
+ * draws one segment per phase and captions it with `means`. Every phase is 0/1: it completes when
+ * its promise settles (the boot imports modules — there is no script list to count).
+ *
+ *   modules       the parts barrel imported (every published kind registered)
+ *   engine-ready  the WASM engine booted (compat/engine.js bootEngine)
+ *   renderer      the vendor renderer loaded and its provider registered in the display slot
+ *   sketch        the page's scene built
+ *
+ * Consumers:
+ *   - lib/frqtl/experiments/_shared/boot.js — creates the record with BOOT_PHASE_IDS.
+ *   - lib/features/ide/frame-boot-progress.js — the host-side watcher; hands BOOT_PHASES to the card.
+ */
+
+export const BOOT_PHASES = Object.freeze([
+    { id: 'modules', means: 'Loading the scene objects' },
+    { id: 'engine-ready', means: 'Starting the WASM engine' },
+    { id: 'renderer', means: 'Loading the renderer' },
+    { id: 'sketch', means: 'Building the scene' },
+].map(Object.freeze));
+
+/** The ids, in order — what the boot record is created with. */
+export const BOOT_PHASE_IDS = Object.freeze(BOOT_PHASES.map((p) => p.id));
+
+/** The event the boot record dispatches on the document (and its frame element). */
+export const BOOT_PHASE_EVENT = 'frqtl:boot-phase';
+
+/**
+ * The phase row for `id`, or a thrown error naming every legal id.
+ * @param {string} id
+ */
+export function bootPhase(id) {
+    const row = BOOT_PHASES.find((p) => p.id === id);
+    if (!row) {
+        throw new Error(`boot-phases: "${id}" is not a boot phase — ${BOOT_PHASE_IDS.join(', ')}.`);
+    }
+    return row;
+}

package/dist/shim/engine/engine-stack-boot.js

@@ -0,0 +1,59 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * ensureEngineStack — boot the canonical engine + game layer in THIS realm and hand back the realm's
+ * own module instances a builder cell needs (the parts, FrqtlApp, RecipeContext, the engine accessor).
+ *
+ * Named ESM export. Lives in lib/shim so the runtime builtin `frqtl.ensureEngine` can boot the engine
+ * WITHOUT importing GraphicsPane (the upward-arrow veto) and WITHOUT importing lib/frqtl (the
+ * cross-arrow veto). It imports THE boot module (`experiments/_shared/boot.js`) from the served tree
+ * through the caller's router — the same module instance GraphicsPane.boot() and every experiment page
+ * boot through — awaits `bootRealm()`, then imports each REALM_MODULES row through the SAME router, so
+ * every module is the instance the boot loaded (one module, one URL). ONE boot authority; no second
+ * loader.
+ *
+ *   REALM_MODULES                 key → router-relative module path (the one table of what a realm hands out)
+ *   ensureEngineStack(router) → Promise<Object<key, namespace>>   frozen; latched by the boot module for
+ *       the document, so a later call returns the same instances, and a failed engine boot stays failed:
+ *       recovering from one takes a fresh document.
+ *
+ * @param {object} router — an engineRouter() instance (needs .resolve)
+ */
+
+'use strict';
+
+/** The realm's module instances a builder cell reads, by router-relative path. */
+export const REALM_MODULES = Object.freeze({
+    parts:          'parts/index.js',
+    app:            'objects/FrqtlApp.js',
+    recipe:         'objects/RecipeContext.js',
+    engine:         'compat/engine.js',
+    display:        'compat/renderer/display-slot.js',
+    QuantumEmitter: 'objects/objects/QuantumEmitter.js',
+    Box:            'objects/objects/Box.js',
+    CircuitGate:    'objects/objects/CircuitGate.js',
+    CircuitProbe:   'objects/objects/CircuitProbe.js'
+});
+
+export function ensureEngineStack(router) {
+    if (!router || typeof router.resolve !== 'function') {
+        return Promise.reject(new Error(
+            '[engine-stack-boot] ensureEngineStack requires a router (an engineRouter() instance with ' +
+            '.resolve, not a bare resolve function). (FAIL-LOUD.)'
+        ));
+    }
+    function url(rel) { return new URL(router.resolve(rel), document.baseURI).href; }
+    return Promise.all([import(/* @vite-ignore */ url('experiments/_shared/boot.js')),
+        import(/* @vite-ignore */ url('experiments/_shared/page-door.js'))]).then(function (mods) {
+        mods[1].refuseRetiredGlobals();   // an in-tree realm: a retired page global throws its repoint
+        return mods[0].bootRealm();
+    }).then(function () {
+        var keys = Object.keys(REALM_MODULES);
+        return Promise.all(keys.map(function (k) { return import(/* @vite-ignore */ url(REALM_MODULES[k])); }))
+            .then(function (mods) {
+                var out = {};
+                keys.forEach(function (k, i) { out[k] = mods[i]; });
+                return Object.freeze(out);
+            });
+    });
+}