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

package/dist/shim/registry/experiments.js

@@ -0,0 +1,215 @@
+/* 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;
+}

package/dist/shim/registry/index.js

@@ -0,0 +1,19 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * The registry barrel — the module `@descix/frqtl-web/registry` and `@descix/frqtl-node/registry` resolve
+ * to (dist/shim/registry/index.js). Host-neutral ESM: it runs unchanged in node and in a page.
+ * Each module below owns its own surface; this file only ferries them.
+ * lib/shim/package.json {"type":"module"} is why every loader (node, Playwright's transform, bundlers)
+ * agrees the tree is ESM, rather than each sniffing the syntax.
+ *
+ *   walkthrough.js   the walk-through rungs: walkthroughById, effectiveRenderState, modes
+ *   exhibits.js      the showcase roster
+ *   experiments.js   the experiment registry and its tiers
+ *   scene-source.js  loadSceneSource(id) — a rung's sketch text (fetch in a page, file read in node)
+ */
+
+export * from './walkthrough.js';
+export * from './exhibits.js';
+export * from './experiments.js';
+export * from './scene-source.js';

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

@@ -0,0 +1,157 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * scene-source.js — the ONE reader of a scene's sketch file, in a page AND in node.
+ *
+ * A scene is ONE file, `lib/frqtl/scenes/<file>.js`: a dual-mode `buildExperiment(exp)`
+ * module holding the whole scene (world, parts, render intent). A registry row carries
+ * its frqtl-relative PATH (`source: 'scenes/<file>.js'`), never its text. Every consumer
+ * that needs the text (the GYM's rung frame, STUDIO, the hero, a package consumer of
+ * `@descix/frqtl-web/registry`) asks here, so the id → path → URL → text chain exists once.
+ *
+ *   scenePath(rung)                → 'scenes/<file>.js'   (THROWS on any other shape)
+ *   loadSceneSource(scene, opts?)  → Promise<string>      (the file's text)
+ *
+ * `scene` is a rung id (resolved by `walkthroughById`; an unknown id REJECTS naming the
+ * declared ids) or a row (`{id, source}`, e.g. `EMPTY_SCENE`). The URL comes from a router,
+ * the one path authority (lib/shim/engine/router.js, `scenes/` profile key):
+ *   - `opts.router` — the host's own (the IDE's engineRouter); a host always passes it.
+ *   - 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.
+ *
+ * FAIL-LOUD: an unknown id, a row without a scenes/ path, 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.
+ *
+ * Zero physics: this moves text. The scene's physics is whatever its file composes.
+ */
+
+'use strict';
+
+import { WALKTHROUGH, walkthroughById } from './walkthrough.js';
+import { engineRouter } from '../engine/router.js';
+
+/** The one path prefix a scene file lives under (the router's `scenes/` profile key). */
+export var SCENES_PREFIX = 'scenes/';
+
+/**
+ * Where the package's dist root sits relative to this module once shipped: build.js places
+ * lib/shim/ at dist/shim/ (sdk/_build/lib-dist-placement.cjs), so this file is
+ * dist/shim/registry/scene-source.js. verify-publish-surface reads every rung through it on the
+ * built dist, so a moved placement fails there.
+ */
+var PACKAGE_ROOT_FROM_HERE = '../../';
+
+/**
+ * The blank world — STUDIO's "Empty Universe" — is itself a scene file (the empty page states no
+ * world of its own). A row-shaped handle so it reads through the same `loadSceneSource`.
+ */
+export var EMPTY_SCENE = Object.freeze({ id: 'empty', source: 'scenes/empty.js' });
+
+var OPT_KEYS = ['router', 'fetch'];
+
+/**
+ * @param {{id?:string, source?:string}} rung — a registry row.
+ * @returns {string} the frqtl-relative scene path.
+ */
+export function scenePath(rung) {
+    var src = rung && rung.source;
+    if (typeof src !== 'string' || src.indexOf(SCENES_PREFIX) !== 0 || !/\.js$/.test(src)) {
+        throw new Error('[scene-source] rung "' + (rung && rung.id) + '" declares source ' +
+            JSON.stringify(src) + ' — a scene row carries the path of its sketch file, ' +
+            "'scenes/<file>.js' (lib/frqtl/scenes/). (FAIL-LOUD.)");
+    }
+    return src;
+}
+
+function _rowOf(scene) {
+    if (typeof scene === 'string') {
+        var rung = walkthroughById(scene);
+        if (!rung) {
+            throw new Error('[scene-source] unknown rung id "' + scene + '" — declared ids: [' +
+                WALKTHROUGH.map(function (r) { return r.id; }).join(', ') + ']. (FAIL-LOUD.)');
+        }
+        return rung;
+    }
+    if (!scene || typeof scene !== 'object') {
+        throw new Error('[scene-source] loadSceneSource takes a rung id or a registry row, got ' +
+            JSON.stringify(scene) + '. (FAIL-LOUD.)');
+    }
+    return scene;
+}
+
+function _packageRouter() {
+    var root = new URL(PACKAGE_ROOT_FROM_HERE, import.meta.url).href.replace(/\/$/, '');
+    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();
+    });
+}
+
+/**
+ * Read a scene file's text through a router's path authority.
+ * @param {string|{id:string, source:string}} scene — a rung id, or a registry row.
+ * @param {{router?:{resolve:function(string):string}, fetch?:function}} [opts]
+ *   router — the host's engineRouter (absent: the package's own dist root);
+ *   fetch  — the fetch used for a non-file URL (defaults to the global; injectable for tests).
+ * @returns {Promise<string>}
+ */
+export function loadSceneSource(scene, opts) {
+    return Promise.resolve().then(function () {
+        opts = opts || {};
+        Object.keys(opts).forEach(function (k) {
+            if (OPT_KEYS.indexOf(k) === -1) {
+                throw new Error('[scene-source] loadSceneSource has no option "' + k + '" — options: ' +
+                    OPT_KEYS.join(', ') + '. (FAIL-LOUD.)');
+            }
+        });
+        var row = _rowOf(scene);
+        var rel = scenePath(row);
+        var router = opts.router || _packageRouter();
+        if (typeof router.resolve !== 'function') {
+            throw new Error('[scene-source] opts.router has no resolve() — pass an engineRouter ' +
+                '(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) {
+            if (typeof t !== 'string' || !t.trim()) {
+                throw new Error('[scene-source] scene "' + row.id + '" — ' + url +
+                    ' has an empty body. (FAIL-LOUD.)');
+            }
+            return t;
+        });
+    });
+}