@descix/frqtl-node 0.6.0-p4.1 → 0.6.0

package/dist/shim/registry/scene-source.js

@@ -26,8 +26,8 @@
  *   - absent — the PACKAGE's: the dist layout anchored at the dist root this module ships in
  *     (`PACKAGE_ROOT_FROM_HERE`, dist/shim/registry/ → dist/). This is the `@descix/frqtl-web/registry`
  *     door's reader; in the source tree it names a file that is not there and rejects.
- * The read is a CAPABILITY split on the resolved URL, never a host sniff: a `file:` URL is read through
- * node's fs (`process.getBuiltinModule`), anything else is fetched.
+ * The read is lib/shim/project/read-text.js readText (a capability split on the resolved URL: a `file:` URL
+ * through node's fs, anything else fetched).
  *
  * FAIL-LOUD: an unknown id, a row without a scenes/ path, an undeclared mode, a non-200 response, an
  * unreadable file or an empty body REJECTS naming the scene and the URL. A blank scene is never a result.
@@ -41,6 +41,7 @@ import { WALKTHROUGH, walkthroughById, effectiveRenderState } from './walkthroug
 import { engineRouter } from '../engine/router.js';
 import { MANIFEST_FILE, manifestFor, serializeManifest } from '../project/manifest.js';
 import { SKETCH_ENTRY } from '../project/link.js';
+import { readText } from '../project/read-text.js';
 
 /** The one path prefix a scene file lives under (the router's `scenes/` profile key). */
 export var SCENES_PREFIX = 'scenes/';
@@ -96,36 +97,6 @@ function _packageRouter() {
     return engineRouter({ mode: 'cdn', base: root });
 }
 
-function _readFileUrl(url, id) {
-    var proc = globalThis.process;
-    var getBuiltin = proc && proc.getBuiltinModule;
-    if (typeof getBuiltin !== 'function') {
-        throw new Error('[scene-source] scene "' + id + '" resolves to ' + url + ', a file: URL; reading ' +
-            'one needs node\'s process.getBuiltinModule (Node 20.16+ / 22.3+). In a page, serve the ' +
-            'package over http. (FAIL-LOUD.)');
-    }
-    var fs = getBuiltin('node:fs');
-    var fileURLToPath = getBuiltin('node:url').fileURLToPath;
-    return fs.promises.readFile(fileURLToPath(url), 'utf8').catch(function (e) {
-        throw new Error('[scene-source] scene "' + id + '" — reading ' + url + ' failed: ' +
-            (e && e.message) + '. (FAIL-LOUD.)');
-    });
-}
-
-function _fetchText(url, id, fetchImpl) {
-    var f = fetchImpl || (typeof fetch === 'function' ? fetch : null);
-    if (!f) {
-        throw new Error('[scene-source] no fetch available to load ' + url + '.');
-    }
-    return Promise.resolve(f(url)).then(function (res) {
-        if (!res || !res.ok) {
-            throw new Error('[scene-source] scene "' + id + '" — GET ' + url + ' answered ' +
-                (res ? res.status : 'nothing') + '. (FAIL-LOUD.)');
-        }
-        return res.text();
-    });
-}
-
 /**
  * A registry scene as the project folder a host boots, with the host's boot bag beside it.
  * @param {string|{id:string, source:string}} scene — a rung id, or a registry row.
@@ -153,10 +124,9 @@ export function projectOf(scene, opts) {
                 '(lib/shim/engine/router.js) to resolve ' + rel + '. (FAIL-LOUD.)');
         }
         var url = router.resolve(rel);
-        var text = url.indexOf('file:') === 0
-            ? _readFileUrl(url, row.id)
-            : _fetchText(url, row.id, opts.fetch);
-        return Promise.resolve(text).then(function (t) {
+        return readText(url, { fetch: opts.fetch }).catch(function (e) {
+            throw new Error('[scene-source] scene "' + row.id + '" — ' + ((e && e.message) || e) + '. (FAIL-LOUD.)');
+        }).then(function (t) {
             if (typeof t !== 'string' || !t.trim()) {
                 throw new Error('[scene-source] scene "' + row.id + '" — ' + url +
                     ' has an empty body. (FAIL-LOUD.)');

package/dist/shim/registry/walkthrough.js

@@ -774,8 +774,7 @@ export function walkthroughById(id) {
 });
 
 // ── is3D normalization (E-W0a; mode-aware S3/W2) ─────────────────────────────
-// STUDIO must read ONE `is3D` field for a selection regardless of whether it came
-// from the gallery registry (experiments.js `is3D`) or a walkthrough rung. A rung's
+// STUDIO reads ONE `is3D` field for a selection. A rung's
 // 3D-ness is ALREADY declared by its (possibly mode-merged) `renderState.renderer` —
 // three IS the 3D renderer, the ONE display fact the load path threads — so `is3D` here is
 // DERIVED through `effectiveRenderState` for the rung's DEFAULT mode, never a
@@ -787,7 +786,7 @@ WALKTHROUGH.forEach(function (rung) {
 
 /**
  * walkthroughIs3D(id, modeId) — the ONE mount-time 3D predicate for a walkthrough
- * rung, the peer of experiments.js `experimentIs3D`. Derived through
+ * rung. Derived through
  * `effectiveRenderState` (the single derivation point) for the given mode, or the
  * rung's default mode when `modeId` is omitted. Returns false for an unknown id;
  * THROWS (via effectiveRenderState) for a known id with an undeclared mode.

package/dist/shim/render-state/apply.js

@@ -5,7 +5,7 @@
  * that applies a renderState bag to a booted runner.
  *
  * A renderState bag (renderer/seed load-time selections + render rows + camera + backdrop
- * visibility + page controls) is replayed by every host: the GYM rung frame, STUDIO, the bundle's
+ * visibility) is replayed by every host: the GYM rung frame, STUDIO, the bundle's
  * `bootRecipe`, the hosted eyes. They all come through `RenderState.apply` — directly (the bundle,
  * which is its own page) or through the blank page's door `FrqtlPage.applyRenderState`
  * (lib/frqtl/experiments/empty/index.html). A host never restates the procedure.
@@ -37,8 +37,13 @@
  *                                          census LO marked `backdrop === true`, or null. STUDIO's
  *                                          save captures its visibility through it, so capture and
  *                                          replay read one fact.
- *   normalizeSavedRenderState(raw)       — tolerant normalizer for a LOADED bag; THROWS only on a bag
- *                                          that carries page controls (they are author code now).
+ *   RENDER_STATE_KEYS                    — THE key table of a bag, in the order the normalized bag is written;
+ *                                          each row normalizes its own value.
+ *   RENDER_STATE_VERSION                 — 1, the one version a bag may declare.
+ *   normalizeSavedRenderState(raw)       — a bag (or null: no boot bag) → the full bag off RENDER_STATE_KEYS.
+ *                                          THROWS on a key outside the table (naming it and the table), on
+ *                                          another version, on page controls (author code now), and on a
+ *                                          value that is neither a plain object nor null.
  *   pickCameraReplay(saved)              — pure decision: named preset over raw orbit.
  *   partitionRenderRows(rows, declared, known) — apply / retain / throw, before anything is written.
  *   renderRowsFromBag(bag)               — a { key: value } render-option bag as ordered rows.
@@ -70,13 +75,42 @@ function pickCameraReplay(saved) {
     return null;
 }
 
+/** The one version a renderState bag may declare (an absent version is this one). */
+var RENDER_STATE_VERSION = 1;
+
+/**
+ * THE key table of a renderState bag, in the order the normalized bag is written. Each row's `normalize(value)`
+ * takes the raw value (undefined when the key is absent) to the stored form; an absent or malformed value is the
+ * neutral one (null / []), which `apply` writes nothing for.
+ * @type {ReadonlyArray<{key: string, normalize: function(*): *}>}
+ */
+var RENDER_STATE_KEYS = Object.freeze([
+    { key: 'version', normalize: function (v) {
+        if (v === undefined || v === RENDER_STATE_VERSION) { return RENDER_STATE_VERSION; }
+        throw new Error('[render-state] renderState.version ' + JSON.stringify(v) + ' — this owner reads version ' +
+            RENDER_STATE_VERSION + ' only. (FAIL-LOUD.)');
+    } },
+    { key: 'renderer', normalize: function (v) { return (typeof v === 'string' && v.length > 0) ? v : null; } },
+    { key: 'engine', normalize: function (v) { return (typeof v === 'string' && v.length > 0) ? v : null; } },
+    { key: 'seed', normalize: function (v) { return (v !== undefined && v !== null && v !== '') ? String(v) : null; } },
+    { key: 'backdropVisible', normalize: function (v) { return (typeof v === 'boolean') ? v : null; } },
+    { key: 'camera', normalize: function (v) {
+        if (!_isPlainObject(v)) { return null; }
+        return { orbit: _isPlainObject(v.orbit) ? v.orbit : null, preset: (typeof v.preset === 'string') ? v.preset : null };
+    } },
+    { key: 'render', normalize: function (v) {
+        return Array.isArray(v) ? v.filter(function (row) {
+            return _isPlainObject(row) && typeof row.key === 'string' && row.key.length > 0;
+        }) : [];
+    } }
+].map(Object.freeze));
+
 /**
- * Tolerant normalizer for a saved module's `renderState` field — a stored record may be
- * `undefined` (a pre-S6 legacy module), `null`, or a shape from another `version` — NEVER throws;
- * every missing/malformed field degrades to a NEUTRAL default (empty array / null), one `apply`
- * writes nothing for.
+ * The full renderState bag of `raw`, built off RENDER_STATE_KEYS: a bag (a host's capture, a registry rung's, a
+ * stored folder row's, an export's boot bag) or `null` (no boot bag — the one-file Import) → every key, in table
+ * order. An owner refuses what is not in its contract: a silent drop would be a silent fallback.
  *
- * @param {*} raw
+ * @param {object|null} raw
  * @returns {{
  *   version: number,
  *   renderer: string|null,
@@ -86,34 +120,33 @@ function pickCameraReplay(saved) {
  *   camera: {orbit:object|null, preset:string|null}|null,
  *   render: {key:string, value:*}[]
  * }}
- * @throws {Error} a bag whose `pageControls` holds a row — page controls are declared in the sketch's own
- *   code, so a saved bag never carries them; migrate the project (move the controls into its sketch).
+ * @throws {Error} a key outside RENDER_STATE_KEYS (named, beside the table); a version other than
+ *   RENDER_STATE_VERSION; a bag carrying `pageControls` — page controls are declared in the sketch's own code, so a
+ *   saved bag never carries them (migrate the project: move the controls into its sketch); and a value that is
+ *   neither a plain object nor null (`undefined` included: a caller with no bag passes null).
  */
 function normalizeSavedRenderState(raw) {
-    var r = _isPlainObject(raw) ? raw : {};
-    if (Array.isArray(r.pageControls) && r.pageControls.length > 0) {
+    if (raw !== null && !_isPlainObject(raw)) {
+        throw new Error('[render-state] a renderState is a bag (a plain object) or null for none — got ' +
+            (raw === undefined ? 'undefined' : Array.isArray(raw) ? 'an array' : typeof raw) + '. (FAIL-LOUD.)');
+    }
+    var r = raw || {};
+    if (Object.prototype.hasOwnProperty.call(r, 'pageControls')) {
+        var rows = Array.isArray(r.pageControls) ? r.pageControls : [];
         throw new Error('[render-state] this saved project carries page controls (renderState.pageControls: ' +
-            r.pageControls.map(function (row) { return _isPlainObject(row) ? String(row.id) : '?'; }).join(', ') +
+            (rows.map(function (row) { return _isPlainObject(row) ? String(row.id) : '?'; }).join(', ') || 'an empty list') +
             ') — page controls are declared in the sketch\'s own code; move them into the sketch and save again. (FAIL-LOUD.)');
     }
-    var camera = null;
-    if (_isPlainObject(r.camera)) {
-        camera = {
-            orbit: _isPlainObject(r.camera.orbit) ? r.camera.orbit : null,
-            preset: (typeof r.camera.preset === 'string') ? r.camera.preset : null
-        };
-    }
-    return {
-        version: (typeof r.version === 'number') ? r.version : 1,
-        renderer: (typeof r.renderer === 'string' && r.renderer.length > 0) ? r.renderer : null,
-        engine: (typeof r.engine === 'string' && r.engine.length > 0) ? r.engine : null,
-        seed: (r.seed !== undefined && r.seed !== null && r.seed !== '') ? String(r.seed) : null,
-        backdropVisible: (typeof r.backdropVisible === 'boolean') ? r.backdropVisible : null,
-        camera: camera,
-        render: Array.isArray(r.render) ? r.render.filter(function (row) {
-            return _isPlainObject(row) && typeof row.key === 'string' && row.key.length > 0;
-        }) : []
-    };
+    var known = RENDER_STATE_KEYS.map(function (row) { return row.key; });
+    Object.keys(r).forEach(function (k) {
+        if (known.indexOf(k) === -1) {
+            throw new Error('[render-state] renderState has no key "' + k + '" — its keys (RENDER_STATE_KEYS): ' +
+                known.join(', ') + '. (FAIL-LOUD.)');
+        }
+    });
+    var out = {};
+    RENDER_STATE_KEYS.forEach(function (row) { out[row.key] = row.normalize(r[row.key]); });
+    return out;
 }
 
 /**
@@ -252,6 +285,8 @@ function apply(runner, bag, env) {
 export {
     apply,
     backdropOf,
+    RENDER_STATE_KEYS,
+    RENDER_STATE_VERSION,
     normalizeSavedRenderState,
     pickCameraReplay,
     partitionRenderRows,

package/dist/shim/render-state/index.js

@@ -11,7 +11,9 @@
  * ── Layer 1: API contract ────────────────────────────────────────────────────
  *
  *   RenderState                        — the owner object: RenderState.apply(runner, bag, env).
- *   normalizeSavedRenderState(raw)     — tolerant normalizer for a LOADED bag (never throws).
+ *   RENDER_STATE_KEYS, RENDER_STATE_VERSION — the bag's key table and its one version.
+ *   normalizeSavedRenderState(raw)     — a bag or null → the full bag; THROWS on a key outside the table, another
+ *                                        version, page controls, or a non-bag.
  *   pickCameraReplay(saved)            — pure decision: named preset over raw orbit.
  *   partitionRenderRows(rows, declared, known)
  *                                      — resolve render rows against the TARGET renderer.
@@ -29,7 +31,7 @@
 
 // The one owner of the renderState contract and its apply procedure.
 import * as RenderState from './apply.js';
-import { normalizeSavedRenderState, pickCameraReplay, partitionRenderRows, renderRowsFromBag } from './apply.js';
+import { RENDER_STATE_KEYS, RENDER_STATE_VERSION, normalizeSavedRenderState, pickCameraReplay, partitionRenderRows, renderRowsFromBag } from './apply.js';
 
 // ── applySavedUrlOverrides ───────────────────────────────────────────────────
 
@@ -65,6 +67,8 @@ function applySavedUrlOverrides(src, overrides) {
 // ── Export ────────────────────────────────────────────────────────────────────
 
 export {
+    RENDER_STATE_KEYS,
+    RENDER_STATE_VERSION,
     RenderState,
     normalizeSavedRenderState,
     pickCameraReplay,

package/dist/shim/runtime/index.js

@@ -133,7 +133,7 @@ var _renderObj = {
  * naming the global and the gate, rather than yielding undefined or null. A soft
  * return is exactly what turns a boot-ordering defect into an opaque
  * property-access TypeError one frame later ("Cannot read properties of null
- * (reading 'build')" — FRAQTL #73); the throw names what was unavailable instead.
+ * (reading 'build')"); the throw names what was unavailable instead.
  * That covers the constructor members (`FrqtlApp`, `RecipeContext`) and every getter generated from
  * the member table (CAPS_FRQTL_MEMBERS): there is no soft residual.
  *
@@ -441,7 +441,7 @@ function _runMath(code, fileId, sourceUrl) {
  * handle minted before the call is dead — a later use throws
  * `arena:stale-handle`. For `js-reference` it is a no-op.
  *
- * THE SCOPE RULE (FRAQTL issue #67): a math scope is one RUN, and the caller
+ * THE SCOPE RULE: a math scope is one RUN, and the caller
  * that knows what a run is owns the boundary. Two run units exist, each stated
  * once: the `run()` lane's unit is one code buffer (it calls this in its own
  * `finally`); a notebook's unit is one notebook run, so `NotebookKernel` calls
@@ -576,7 +576,7 @@ function _runMathModule(code, sdk, sourceUrl) {
  *   - _ensureMathSdk()                          (resolved SDK + backend select)
  *   - the stashed-console tee (the 7cc5520 lesson — observers never re-emit)
  *
- * It does NOT end the math scope: a cell is not a run (FRAQTL issue #67). Its
+ * It does NOT end the math scope: a cell is not a run. Its
  * declared outputs are committed into the caller's binding store and must stay
  * usable in later cells, so the scope boundary belongs to whoever owns that
  * store — see `resetMathScope()`.
@@ -839,7 +839,7 @@ function runCell(spec) {
             // NO math-scope reset here. A cell is not a run: the values this cell
             // just returned are about to be committed into the caller's binding
             // store, and draining the arena would make every one of them a stale
-            // handle before the next cell could read it (FRAQTL issue #67). The
+            // handle before the next cell could read it. The
             // scope boundary is the binding store's — see resetMathScope().
         });
     }).catch(function (e) {

package/llms.txt

@@ -1,12 +1,13 @@
 # @descix/frqtl-node
 
 > The FRQTL physics engine (compiled Rust → WASM) for node: the same modules as @descix/frqtl-web, plus
-> `bootNode` and the hosted eyes. Pre-release 0.6.0-p4.1 on npm dist-tag `next`. Node ≥ 22.12.
+> `bootNode` and the hosted eyes. 0.6.0 on npm dist-tag `latest`. Node ≥ 22.12.
 
-- Install: `npm install @descix/frqtl-node@next`
+- Install: `npm install @descix/frqtl-node`
 - `import { bootNode, Wall } from '@descix/frqtl-node'` (require() works too); `await bootNode()` → the engine handle.
 - `./eyes`: `openHostedEyes({ sceneRecord, sceneSource: { kind: 'project', files, entry }, pageUrl })`.
 - `./project`: `linkProject` links a scene file against this package's own copy.
+- `./host-view`: `declareHostView`, `HOST_VIEW_OUTCOMES`, `CONTRACT_VIOLATIONS`, `HOST_SDK_SCRIPT` — the same declarer as @descix/frqtl-web/host-view, pure, for a node test of a call site.
 - `./register`: `node --import @descix/frqtl-node/register scene.mjs` resolves a scene's `@descix/frqtl-web/...` imports to this package.
-- Full agent guide: https://cdn.jsdelivr.net/npm/@descix/frqtl-node@0.6.0-p4.1/CLAUDE.md
+- Full agent guide: https://cdn.jsdelivr.net/npm/@descix/frqtl-node@0.6.0/CLAUDE.md
 - Acceptance is visual; no CLI ships. No account, credits or tokens are needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/frqtl-node",
-  "version": "0.6.0-p4.1",
+  "version": "0.6.0",
   "description": "FRQTL for node \u2014 the discrete fractal physics engine (compiled Rust \u2192 WASM), its parts as ES modules, the node engine door (bootNode) and the hosted eyes.",
   "type": "module",
   "engines": {
@@ -13,6 +13,7 @@
     "./parts/*": "./dist/frqtl/parts/*",
     "./project": "./dist/shim/project/index.js",
     "./registry": "./dist/shim/registry/index.js",
+    "./host-view": "./dist/shim/host/index.js",
     "./register": "./dist/shim/project/register-node.mjs",
     "./shim/controls/registry.js": "./dist/shim/controls/registry.js",
     "./shim/render/sun-look.js": "./dist/shim/render/sun-look.js",
@@ -21,6 +22,23 @@
     "./objects/setup/_collisionMatrixLanes.js": "./dist/frqtl/objects/setup/_collisionMatrixLanes.js",
     "./compat/engine.js": "./dist/frqtl/compat/engine.js",
     "./kinds": "./dist/frqtl/objects/kinds-entry.js",
+    "./objects/objects/tagger.js": "./dist/frqtl/objects/objects/tagger.js",
+    "./objects/schema/index.js": "./dist/frqtl/objects/schema/index.js",
+    "./shim/render/heat-colormap.js": "./dist/shim/render/heat-colormap.js",
+    "./objects/schema/valueNormalizer.js": "./dist/frqtl/objects/schema/valueNormalizer.js",
+    "./objects/objects/Box.js": "./dist/frqtl/objects/objects/Box.js",
+    "./objects/objects/QuantumEmitter.js": "./dist/frqtl/objects/objects/QuantumEmitter.js",
+    "./shim/expr/ast-schema.js": "./dist/shim/expr/ast-schema.js",
+    "./objects/objects/actionCompiler.js": "./dist/frqtl/objects/objects/actionCompiler.js",
+    "./objects/v1-replacements.js": "./dist/frqtl/objects/v1-replacements.js",
+    "./objects/objects/slitLinerScatter.js": "./dist/frqtl/objects/objects/slitLinerScatter.js",
+    "./objects/setup/setupSphereEmitter3D.js": "./dist/frqtl/objects/setup/setupSphereEmitter3D.js",
+    "./objects/objects/directedRedirectProgram.js": "./dist/frqtl/objects/objects/directedRedirectProgram.js",
+    "./compat/renderer/lo-drawn-center.js": "./dist/frqtl/compat/renderer/lo-drawn-center.js",
+    "./objects/setup/setupTunnelPointExit.js": "./dist/frqtl/objects/setup/setupTunnelPointExit.js",
+    "./objects/constants/WallBehaviors.js": "./dist/frqtl/objects/constants/WallBehaviors.js",
+    "./objects/objects/absorbRadiation.js": "./dist/frqtl/objects/objects/absorbRadiation.js",
+    "./objects/geometry/SlabFace.js": "./dist/frqtl/objects/geometry/SlabFace.js",
     "./dist-manifest.json": "./dist/dist-manifest.json",
     "./package.json": "./package.json"
   },

package/dist/shim/registry/experiments.js

@@ -1,215 +0,0 @@
-/* Copyright 2023-2026 by Essam Abadir */
-
-/**
- * EXPERIMENTS — canonical experiment registry.
- *
- * Single ESM named export. Replaces the dual window.EXPERIMENTS + CommonJS export.
- * Consumed by lib/features/ide via import; SimPane reads experiments from the prop.
- *
- * id      : the directory name under frqtl/experiments/{id}/index.html
- * title   : human-readable label
- * cat     : category label
- * jsOnly  : true if the experiment requires JS-engine-only APIs
- *
- * Ordering (G1):
- *   Experiments listed in the exhibit manifest appear FIRST, in manifest order.
- *   Remaining experiments follow in their original declaration order.
- *   This ordering is consumed by SimPane's dropdown via the existing prop path
- *   (zero SimPane changes required).
- *
- * The manifest import is done lazily via a factory to avoid circular dependency
- * (exhibits.js imports EXPERIMENTS from here; we cannot import exhibits.js at
- * the top level of this file). The ordered list is computed once on first access.
- */
-
-/**
- * EXPERIMENT_TIERS — the tier vocabulary and what each tier means for PUBLIC
- * SURFACING. This table is the contract; consumers never hardcode a tier string.
- *
- *   - A row with NO `tier` is public (absence = public; there is deliberately no
- *     `tier:'public'` literal to maintain on every row).
- *   - A row whose tier resolves `public:false` is dropped from the public
- *     experiment choosers by `isPublicExperiment()` / `publicExperiments()`.
- *   - An UNKNOWN tier value FAILS LOUD (`isPublicExperiment` throws) — a typo'd
- *     tier must never silently publish a lab.
- *   - Tier gates the CURATED public chooser (STUDIO Templates). The GYM lists
- *     `internalExperiments()` instead — see that function's doc.
- *
- * Visibility only: a non-public tier NEVER affects loadability, deep-linking,
- * ordering, `is3D`, or the label lookup. Those all read the full EXPERIMENTS list
- * / `experimentById()`. `sdk/frqtl-web/build.js` ships `publicExperiments()` +
- * the named infra ids: a dev-tier page is absent from the npm/CDN package, but
- * present in the GYM (both the dev IDE and the shipped static deploy).
- *
- * ── The public set is the NEW-SUGAR content ONLY ─────────────────────────────
- * EVERY row below is `tier:'dev'`: none of these pages has been rebuilt on the
- * current sugar objects (SphereEmitter / v2 `Wall` / `Tunnel` / LiveChart /
- * GraphingDetectorWall), so none is public and none ships. The PUBLIC gallery
- * content is the WALK-THROUGH rung registry (`./walkthrough.js`), which is built
- * entirely on those objects; `sdk/frqtl-web/src/index.html` is its dist surface.
- * An unmigrated page FAILING LOUD in a dist context is the DESIRED signal — it is
- * the list of what remains to migrate. A row returns to the public set by being
- * REBUILT on the new objects and having its `tier` dropped — never by exception.
- *
- * @type {Readonly<Record<string, Readonly<{id:string, public:boolean, label:string}>>>}
- */
-export const EXPERIMENT_TIERS = Object.freeze({
-    dev: Object.freeze({
-        id:     'dev',
-        public: false,
-        label:  'Developer isolation lab / demo',
-    }),
-});
-
-/** @type {Array<{id:string, title:string, cat:string, jsOnly?:boolean, wasmOnly?:boolean, is3D?:boolean, tier?:string}>}
- *  jsOnly  : requires JS-engine-only APIs (no WASM build) — filtered out of Compare.
- *  tier    : a key of EXPERIMENT_TIERS (above). `tier:'dev'` marks a DEVELOPER-tier
- *            isolation lab / demo: fully registered and BOOTABLE by id (direct
- *            experiment-page URL + STUDIO deep link — the dev surface), HIDDEN from
- *            the PUBLIC experiment chooser (STUDIO Templates). It stays LISTED in
- *            the GYM (reads `internalExperiments()`), which is what driving these
- *            labs is for. Omit `tier` for a public experiment.
- *  wasmOnly: 3D experiment; the JS reference is a frozen 2D fixture, so Compare runs
- *            WASM-only (JS-reference pane disabled). See CompareView filter.
- *  is3D    : the ONE mount-time 3D-render authority (E-W0a). TRUE iff
- *            the experiment page unconditionally boots a 3D display — its runner is
- *            `new FrqtlApp({ is3D: true, … })` on the three display — the ground-truth
- *            signal, NOT wasmOnly (orthogonal: collision-matrix is wasmOnly+2D). STUDIO
- *            reads THIS field pre-boot to light up the camera strip + MOVE/LOOK drive for a
- *            template-loaded 3D experiment. A gate test (experiment-is3d-agreement.test.mjs)
- *            asserts THIS field ↔ the page's runner `is3D: true` — a hand-typed drift is a
- *            CI failure (mirror kill). A page that switches 3D only via a `?renderer=three`
- *            reinit toggle (single-source-interference) is 2D-DEFAULT → is3D omitted/false. */
-const _EXPERIMENTS_BASE = [
-    { id: 'g1-lo-race',        title: 'G1: LO races a quantum',     cat: 'Engine Tests', wasmOnly: true, is3D: true, tier: 'dev' },
-    { id: 'g2-lo-sweep',       title: 'G2: moving LO sweeps a field', cat: 'Engine Tests', wasmOnly: true, tier: 'dev' },
-    { id: 'g3-lo-collide',     title: 'G3: Collision Lab (box-of-balls)', cat: 'Engine Tests', wasmOnly: true, tier: 'dev' },
-    { id: 'collision-matrix',    title: 'Collision Matrix (density sweep)',    cat: 'Engine Tests', wasmOnly: true, tier: 'dev' },
-    { id: 'tunnel-lab',          title: 'Tunnel Lab (DirectedTunnel isolation)', cat: 'Engine Tests', wasmOnly: true, is3D: true, tier: 'dev' },
-    { id: 'lightsource-lab',     title: 'LightSource Lab (LightSource isolation)', cat: 'Engine Tests', wasmOnly: true, is3D: true, tier: 'dev' },
-    { id: 'mesh-demo',           title: 'render.mesh demo (external glTF)',    cat: 'Render Effects', wasmOnly: true, is3D: true, tier: 'dev' },
-    { id: 'cone-emitter-3d',   title: 'Cone Emitter 3D (laser ↔ flashlight)', cat: 'Wave Mechanics', wasmOnly: true, is3D: true, tier: 'dev' },
-    { id: 'sphere-emitter-3d', title: 'Sphere Emitter 3D (sun / laser / drum)', cat: 'Wave Mechanics', wasmOnly: true, is3D: true, tier: 'dev' },
-    { id: 'single-source-interference', title: 'Single-Source Self-Interference (omni, 2D)', cat: 'Wave Mechanics', wasmOnly: true, tier: 'dev' },
-    { id: 'tunnel-point-exit',   title: 'Tunnel Point-Exit (collapsed mouth, 2D)', cat: 'Wave Mechanics', wasmOnly: true, tier: 'dev' },
-    { id: 'fx-glow',           title: 'FX: Glow',                   cat: 'Render Effects', wasmOnly: true, is3D: true, tier: 'dev' },
-    { id: 'fx-godrays',        title: 'FX: God-rays',               cat: 'Render Effects', wasmOnly: true, is3D: true, tier: 'dev' },
-    { id: 'fx-smoke',          title: 'FX: Smoke',                  cat: 'Render Effects', wasmOnly: true, is3D: true, tier: 'dev' },
-    { id: 'blackbody-substrate',    title: 'Blackbody Substrate (L1+L2+L3+L4)', cat: 'Thermodynamics', tier: 'dev' },
-    { id: 'circuit-basic',     title: 'Circuit: Series Resistor',   cat: 'Computing',          tier: 'dev' },
-    { id: 'trace-circuit',     title: 'Trace: the wire part',       cat: 'Computing', wasmOnly: true, tier: 'dev' },
-    { id: 'oscillator',        title: 'Quantum Oscillator',         cat: 'Structure & Forces', tier: 'dev' }
-];
-
-/**
- * The flat experiment list, in declaration order. (The showcase roster — the front-page tiles — is
- * scene files, lib/shim/registry/exhibits.js; no experiment page is a tile.)
- *
- * @type {Array<{id:string, title:string, cat:string, jsOnly?:boolean, wasmOnly?:boolean}>}
- */
-export const EXPERIMENTS = _EXPERIMENTS_BASE;
-
-/**
- * isPublicExperiment(entry) — THE tier-visibility predicate. Resolves an entry's
- * `tier` against the EXPERIMENT_TIERS contract: no tier ⇒ public; a known tier ⇒
- * that tier's `public` flag; an unknown tier ⇒ THROWS (fail loud — a typo must
- * never silently publish a dev lab).
- *
- * This is the ONE place the tier→visibility rule lives. Any surface that lists
- * experiments to the public FERRIES this predicate (or `publicExperiments()`
- * below) — re-writing `e.tier !== 'dev'` in a consumer is the schema-mirror
- * anti-pattern and will drift the moment a second non-public tier is added.
- *
- * @param {{id?:string, tier?:string}} entry — an EXPERIMENTS row.
- * @returns {boolean} true if the entry belongs in a public experiment chooser.
- * @throws {Error} if `entry.tier` is not a key of EXPERIMENT_TIERS.
- */
-export function isPublicExperiment(entry) {
-    if (!entry || !entry.tier) { return true; }
-    var tier = EXPERIMENT_TIERS[entry.tier];
-    if (!tier) {
-        throw new Error(
-            '[experiments] unknown tier "' + entry.tier + '" on experiment "' +
-            (entry.id || '?') + '". Known tiers: ' +
-            Object.keys(EXPERIMENT_TIERS).join(', ') + ' (omit `tier` for public).'
-        );
-    }
-    return tier.public === true;
-}
-
-/**
- * publicExperiments() — the EXPERIMENTS a PUBLIC chooser should list, filtered by
- * `isPublicExperiment`. The single filtered view both public experiment-chooser
- * surfaces (STUDIO Templates via ExperimentDropdown, the GYM/Compare select)
- * consume, so the dev-tier hide is declared ONCE. Non-public experiments remain
- * registered and bootable by id (direct experiment-page URL, STUDIO deep link) —
- * they are only hidden from these curated lists.
- *
- * @returns {Array<{id:string, title:string, cat:string}>}
- */
-export function publicExperiments() {
-    return EXPERIMENTS.filter(isPublicExperiment);
-}
-
-/**
- * internalExperiments() — the roster an INTERNAL-ONLY experiment chooser lists.
- *
- * ── Layer 1: API contract ────────────────────────────────────────────────────
- * Every registered row, tier-independent, in registry order. This is the peer of
- * `publicExperiments()`, and the split is by SURFACE AUDIENCE, not by taste:
- *
- *   - `publicExperiments()` — for a chooser a STRANGER can reach (STUDIO
- *     Templates). Tier gates it, because tier means "has this page been rebuilt
- *     on the current sugar and is it fit to publish".
- *   - `internalExperiments()` — for the GYM (`preset='compare'`), which drives
- *     dev-tier isolation labs directly by id and so needs the full roster
- *     regardless of tier.
- *
- * WHY THIS EXISTS (2026-07-28): with the whole legacy roster moved to `tier:'dev'`,
- * `publicExperiments()` is legitimately EMPTY. A surface that lists it therefore
- * offers nothing — which is correct for a public chooser (the public content set
- * is the WALK-THROUGH registry) and wrong for the maintainer's driving
- * instrument. Passing the audience question through the tier table was the
- * conflation; naming the two rosters separately is the fix.
- *
- * A consumer picks the roster that matches ITS audience and derives everything
- * else (its default selection included) from that ONE list — never a second
- * hardcoded id.
- *
- * @returns {Array<{id:string, title:string, cat:string}>} registry rows BY REFERENCE.
- */
-export function internalExperiments() {
-    return EXPERIMENTS.slice();
-}
-
-/**
- * experimentById(id) — THE id→entry resolution for the registry. Reads the FULL
- * EXPERIMENTS list, tier-independent: a dev-tier experiment resolves exactly like
- * a public one, which is what keeps it reachable by direct URL / deep link while
- * hidden from the public choosers.
- *
- * @param {string} id — an experiment id (directory name under experiments/).
- * @returns {{id:string, title:string, cat:string}|null} the entry, or null if unknown.
- */
-export function experimentById(id) {
-    for (var i = 0; i < EXPERIMENTS.length; i++) {
-        if (EXPERIMENTS[i].id === id) { return EXPERIMENTS[i]; }
-    }
-    return null;
-}
-
-/**
- * experimentIs3D(id) — the ONE mount-time 3D-render predicate for a gallery
- * experiment (E-W0a). Reads the declarative `is3D` field off the registry entry
- * (the single authority; see the `is3D` doc on `_EXPERIMENTS_BASE`). Returns
- * false for an unknown id or a 2D-default experiment. STUDIO consults this pre-boot
- * for a template-loaded experiment — the axis the walkthrough path derives from
- * `renderState.renderer`. Never sniffs a page or a runner: 3D-ness is DATA here.
- *
- * @param {string} id — an experiment id (directory name under experiments/).
- * @returns {boolean}
- */
-export function experimentIs3D(id) {
-    var entry = experimentById(id);
-    return !!entry && entry.is3D === true;
-}