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

package/dist/shim/project/identity.js

@@ -103,7 +103,9 @@ export async function projectIdentity(project) {
     for (const c of chunks) { stream.set(c, at); at += c.length; }
     const subtle = (typeof crypto !== 'undefined') ? crypto.subtle : null;
     if (!subtle || typeof subtle.digest !== 'function') {
-        _fail('crypto.subtle.digest is unavailable — the project identity is a content hash with no second hashing path.');
+        _fail('crypto.subtle is unavailable — this page is not a secure context (isSecureContext ' + String(typeof isSecureContext === 'undefined' ? undefined : isSecureContext) +
+            '): serve the folder from https or from localhost (e.g. npx serve). The project identity is a content hash with no second ' +
+            'hashing path.');
     }
     const view = new Uint8Array(await subtle.digest('SHA-256', stream));
     let hex = '';

package/dist/shim/project/link.js

@@ -47,11 +47,15 @@
  * is minted, each naming the file, the specifier and the reason: a relative specifier that climbs out of
  * the root (package internals have no public specifier), one that names a non-module path (not ".js" /
  * ".mjs": a data file, an extensionless name, frqtl.json), one that names no project file (never an HTTP
- * sibling), a @descix/frqtl-web specifier that is not a row of FRQTL_WEB_SPECIFIERS, any other specifier;
+ * sibling), a @descix/frqtl-web specifier that is not a row of FRQTL_WEB_SPECIFIERS, a part-internal row imported
+ * by any file but a part file (parts/*.js), any other specifier;
  * an import cycle among project files; a module file the entry never reaches; an invalid frqtl.json; a
  * served file that is not UTF-8; a missing or non-function default export of the entry, a missing entry,
  * an empty project. Every argument error REJECTS.
  *
+ * An error raised while the project EVALUATES (a duplicate kind, a throw at module top) is rethrown with every minted
+ * URL in its message named by its project path and every package file URL by its specifier (_namePaths).
+ *
  *   blobMint(text) → { url, release() }   a `blob:` module URL (a page), one per byte-identical text
  *   dataMint(text) → { url, release() }   a `data:` module URL (node)
  *
@@ -59,7 +63,7 @@
  * sketchProject(text) is that shape's one writer inside the tree (SKETCH_ENTRY its entry path).
  */
 
-import { libPathOf, FRQTL_WEB_PACKAGE, FRQTL_WEB_SPECIFIERS } from './specifiers.js';
+import { libPathOf, tierOf, specifierOfLibPath, FRQTL_WEB_PACKAGE, FRQTL_WEB_SPECIFIERS } from './specifiers.js';
 import { checkProjectPath, projectBytes } from './identity.js';
 import { MANIFEST_FILE, parseManifest } from './manifest.js';
 import { packageRoot } from '../../frqtl/compat/package-root.js';
@@ -134,6 +138,14 @@ function _publishedList() {
     return FRQTL_WEB_SPECIFIERS.map(function (r) { return r.specifier + (r.specifier.endsWith('/') ? '<file>' : ''); }).join(', ');
 }
 
+/** The tier a forked part's internals carry (specifiers.js SPECIFIER_TIERS). */
+const PART_INTERNAL = 'part-internal';
+
+/** A project file under parts/ (a part file: the only importer of a part-internal module). */
+function _isPartFile(p) {
+    return /^parts\/[^/]+\.m?js$/.test(p);
+}
+
 function _isPackage(spec) {
     return spec === FRQTL_WEB_PACKAGE || spec.startsWith(FRQTL_WEB_PACKAGE + '/');
 }
@@ -198,6 +210,10 @@ async function _walk(entry, sourceOf) {
                     _fail('"' + p + '" imports "' + imp.spec + '" — not a published specifier; the table ' +
                         '(lib/shim/project/specifiers.js FRQTL_WEB_SPECIFIERS) offers: ' + _publishedList() + '.');
                 }
+                if (tierOf(imp.spec) === PART_INTERNAL && !_isPartFile(p)) {
+                    _fail('"' + p + '" imports "' + imp.spec + '" — a part-internal module is imported by a part file ' +
+                        '(parts/*.js), never by a sketch — a sketch imports parts by @descix/frqtl-web/parts.');
+                }
                 list.push(Object.assign({ kind: 'package' }, imp));
             } else {
                 _fail('"' + p + '" imports "' + imp.spec + '" — a project file imports another project file by a ' +
@@ -463,7 +479,9 @@ export async function linkProject(project) {
             minted.push(m);
             urls[p] = m.url;
         }
-        const ns = await import(urls[entry]);
+        let ns;
+        try { ns = await import(urls[entry]); }
+        catch (err) { throw _namePaths(err, urls); }
         const held = { files: heldFiles, entry: entry, mint: mint };
         if (project.bare !== undefined) { held.bare = project.bare; }
         return { buildExperiment: _entryFunction(ns, entry), module: ns, manifest: manifest, files: bytes,
@@ -473,6 +491,28 @@ export async function linkProject(project) {
     }
 }
 
+/**
+ * An error raised while the project evaluates, with every minted URL in its message replaced by the project path
+ * it names (byte-identical files share one minted URL: all their paths), and every package file URL by its
+ * specifier — so a duplicate kind reads "kind "Wall" is already registered by @descix/frqtl-web/parts/Wall.js;
+ * parts/Wall2.js registers it again". The SAME error is rethrown (its stack kept): enrichment, never a catch.
+ */
+function _namePaths(err, urls) {
+    if (!err || typeof err.message !== 'string') { return err; }
+    const byUrl = new Map();
+    for (const p of Object.keys(urls)) { byUrl.set(urls[p], (byUrl.get(urls[p]) || []).concat(p)); }
+    let msg = err.message;
+    for (const [url, paths] of [...byUrl.entries()].sort(function (a, b) { return b[0].length - a[0].length; })) {
+        msg = msg.split(url).join(paths.join(' (= ') + (paths.length > 1 ? ', byte-identical)' : ''));
+    }
+    const root = packageRoot();
+    msg = msg.replace(new RegExp(root.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '([^\\s;,)\'"]+)', 'g'), function (m, lp) {
+        return specifierOfLibPath(lp) || m;
+    });
+    try { err.message = msg; } catch (_) { /* a frozen error keeps its own text */ }
+    return err;
+}
+
 /** The entry path of a one-string sketch held as a project. */
 export const SKETCH_ENTRY = 'sketch.js';
 

package/dist/shim/project/parts-writer.js

@@ -16,6 +16,10 @@
  *                                                     import line for Kind (after the last import statement;
  *                                                     `module` from parts-module.js moduleOfKind)
  *            | { op: 'remove', name }                 the entry's property node, its comma included
+ *            | { op: 'kind',   name, Kind, module }   within entry `name`, replace ONLY its Kind identifier's text, plus
+ *                                                     at most one import line for Kind (the add's line, after the last
+ *                                                     import); the entry's old import line is the author's and stays,
+ *                                                     even when nothing uses it now (a fork: exp.fork)
  *
  *   changes[i] = { op, name, key?, from?, to, literalized? }   from/to are source TEXT; `literalized: true`
  *                when the old value was an expression (its text is `from`), now its literal value
@@ -29,7 +33,8 @@
  *
  *   entryKeys(text, name) → string[]    the plain prop keys entry `name` spells (how an entry spells a value)
  *   entryLiteral(text, name, key) → { literal, value?, length? }   what a key declares when it is a literal
- *                                       (read-back); an array expression's element count otherwise
+ *                                       (read-back); an array expression's element count otherwise (none when
+ *                                       an element is a spread)
  *
  *   serializeValue(value, key) → text   THE one value serializer: numbers, strings (single-quoted),
  *                                       booleans, null, arrays inline, plain objects. Anything else THROWS
@@ -39,6 +44,14 @@
 import { parse } from '../../frqtl/assets/vendor/acorn.mjs';
 import { importSpecifierOf } from './parts-module.js';
 
+/**
+ * parseModule(text) → the acorn syntax tree of an ES module (latest syntax, source ranges) — the vendored parser's
+ * ONE entry point in the tree; every other reader of a project file's syntax (fork.js) parses through it.
+ */
+export function parseModule(text) {
+    return parse(text, { ecmaVersion: 'latest', sourceType: 'module' });
+}
+
 /** The export the writer patches. */
 export const PARTS_EXPORT = 'parts';
 
@@ -47,6 +60,14 @@ const _RESERVED = new Set(('break case catch class const continue debugger defau
     'false finally for function if import in instanceof new null return super switch this throw true try typeof ' +
     'var void while with yield let static enum await implements package protected interface private public').split(' '));
 
+/**
+ * isIdentifierName(s) → true when `s` can name a binding (an identifier that is not a reserved word) — the one
+ * test the writer and the fork transform share.
+ */
+export function isIdentifierName(s) {
+    return typeof s === 'string' && _IDENT.test(s) && !_RESERVED.has(s);
+}
+
 function _keyText(k) {
     return (_IDENT.test(k) && !_RESERVED.has(k)) ? k : _quote(k);
 }
@@ -230,7 +251,7 @@ export function patchParts(text, edits, opts) {
         throw new TypeError('[parts-writer] patchParts(text, edits): text is the sketch file (got ' + typeof text + '). (FAIL-LOUD.)');
     }
     if (!Array.isArray(edits)) {
-        throw new TypeError('[parts-writer] patchParts(text, edits): edits is an array of { op: set | add | remove }. (FAIL-LOUD.)');
+        throw new TypeError('[parts-writer] patchParts(text, edits): edits is an array of { op: set | add | remove | kind }. (FAIL-LOUD.)');
     }
     const changes = [];
     const refused = [];
@@ -317,6 +338,37 @@ export function patchParts(text, edits, opts) {
                 const ins = _appendProperty(text, obj, appended.join(_multiline(text, obj) ? ',\n' + _indentAt(text, (obj.properties[obj.properties.length - 1] || obj).start) : ', '));
                 patches.push(ins);
             }
+        } else if (e.op === 'kind') {
+            const p = entryOf(e);
+            if (!p) { continue; }
+            const v = p.value;
+            if (v.type !== 'ArrayExpression' || v.elements.length !== 2 || !v.elements[0] || v.elements[0].type !== 'Identifier') {
+                refuse(e, 'the entry "' + e.name + '" is not written as [Kind, { …props }] — the writer patches only that form.');
+                continue;
+            }
+            if (typeof e.Kind !== 'string' || !_IDENT.test(e.Kind)) {
+                throw new TypeError('[parts-writer] kind: Kind is the new kind\'s class name (got ' + JSON.stringify(e.Kind) + '). (FAIL-LOUD.)');
+            }
+            if (e.module === null || e.module === undefined) {
+                refuse(e, 'the kind ' + e.Kind + ' has no importable module, so a sketch cannot import it.');
+                continue;
+            }
+            const spec = importSpecifierOf(e.module, entry);
+            const b = bindings.get(e.Kind);
+            if (b && !(b.kind === 'import' && b.source === spec && b.imported === e.Kind)) {
+                refuse(e, 'the identifier ' + e.Kind + ' is already bound in this sketch to ' +
+                    (b.kind === 'import' ? '"' + (b.imported || '*') + '" from \'' + b.source + '\'' : 'its own declaration') +
+                    ' — the writer cannot import the kind ' + e.Kind + ' under that name.');
+                continue;
+            }
+            const id = v.elements[0];
+            if (id.name === e.Kind) { continue; }
+            patches.push({ start: id.start, end: id.end, text: e.Kind });
+            const line = 'import { ' + e.Kind + ' } from ' + _quote(spec) + ';';
+            if (!b && !importLines.some(function (l) { return l.Kind === e.Kind; })) {
+                importLines.push({ Kind: e.Kind, line: line });
+            }
+            changes.push({ op: 'kind', name: e.name, from: id.name, to: e.Kind, import: (!b ? line : null) });
         } else if (e.op === 'remove') {
             const p = entryOf(e);
             if (!p) { continue; }
@@ -353,7 +405,7 @@ export function patchParts(text, edits, opts) {
             changes.push({ op: 'add', name: e.name, from: null, to: _keyText(e.name) + ': [' + e.Kind + ', ' + lit + ']',
                 import: (!b ? 'import { ' + e.Kind + ' } from ' + _quote(spec) + ';' : null) });
         } else {
-            throw new TypeError('[parts-writer] unknown edit op ' + JSON.stringify(e.op) + ' — set | add | remove. (FAIL-LOUD.)');
+            throw new TypeError('[parts-writer] unknown edit op ' + JSON.stringify(e.op) + ' — set | add | remove | kind. (FAIL-LOUD.)');
         }
     }
     if (adds.length) {
@@ -450,8 +502,13 @@ export function entryLiteral(text, name, key) {
     for (const q of _entryProps(text, name, 'entryLiteral').properties) {
         if (_plainKey(q) !== key) { continue; }
         if (_isLiteral(q.value)) { return { literal: true, value: _literalValue(q.value) }; }
-        // An array expression still spells its arity (`center: [srcX, cy]` is two numbers).
-        return q.value.type === 'ArrayExpression' ? { literal: false, length: q.value.elements.length } : { literal: false };
+        // An array expression still spells its arity (`center: [srcX, cy]` is two numbers) — unless an element is a
+        // spread (`center: [...c]`), which spells no arity: the caller applies the live one.
+        const arr = q.value.type === 'ArrayExpression';
+        if (arr && !q.value.elements.some(function (x) { return x && x.type === 'SpreadElement'; })) {
+            return { literal: false, length: q.value.elements.length };
+        }
+        return { literal: false };
     }
     throw new Error('[parts-writer] entryLiteral: the entry "' + name + '" spells no key "' + key + '". (FAIL-LOUD.)');
 }

package/dist/shim/project/read-text.js

@@ -0,0 +1,43 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * read-text.js — THE reader of a text file by URL, for every host: a `file:` URL is read through node's fs
+ * (`process.getBuiltinModule`, Node 20.16+ / 22.3+); any other URL is fetched. The split is a CAPABILITY of the
+ * resolved URL, never a host sniff.
+ *
+ *   readText(url[, { fetch }]) → Promise<string>   REJECTS naming the URL: a file it cannot read ("reading <url>
+ *                                                   failed: …"), a non-200 ("GET <url> answered <status>"), no
+ *                                                   fs for a file: URL, no fetch. `fetch` is injectable (tests).
+ *
+ * Callers prefix their own subject: lib/shim/registry/scene-source.js (a registry scene's sketch) and
+ * RecipeContext.fork (a package part's exact bytes).
+ */
+
+/**
+ * @param {string} url
+ * @param {{fetch?: function}} [opts]
+ * @returns {Promise<string>}
+ */
+export function readText(url, opts) {
+    return Promise.resolve().then(function () {
+        if (typeof url !== 'string' || !url) { throw new TypeError('readText(url): a URL string (got ' + JSON.stringify(url) + ')'); }
+        if (url.indexOf('file:') === 0) {
+            var getBuiltin = (typeof process !== 'undefined' && process.getBuiltinModule) ? process.getBuiltinModule : null;
+            if (typeof getBuiltin !== 'function') {
+                throw new Error(url + ' is a file: URL; reading one needs node\'s process.getBuiltinModule (Node 20.16+ / ' +
+                    '22.3+). In a page, serve the package over http');
+            }
+            var fs = getBuiltin('node:fs');
+            var fileURLToPath = getBuiltin('node:url').fileURLToPath;
+            return fs.promises.readFile(fileURLToPath(url), 'utf8').catch(function (e) {
+                throw new Error('reading ' + url + ' failed: ' + (e && e.message));
+            });
+        }
+        var f = (opts && opts.fetch) || (typeof fetch === 'function' ? fetch : null);
+        if (!f) { throw new Error('no fetch available to load ' + url); }
+        return Promise.resolve(f(url)).then(function (res) {
+            if (!res || !res.ok) { throw new Error('GET ' + url + ' answered ' + (res ? res.status : 'nothing')); }
+            return res.text();
+        });
+    });
+}

package/dist/shim/project/specifiers.js

@@ -3,9 +3,16 @@
 /**
  * specifiers.js — THE one table of `@descix/frqtl-web/...` specifiers a sketch may import.
  *
- *   FRQTL_WEB_SPECIFIERS        rows { specifier, libPath, why } — a row whose specifier ends in `/`
- *                               is a PREFIX row (one part = one file under it)
+ *   FRQTL_WEB_SPECIFIERS        rows { specifier, libPath, why, tier } — a row whose specifier ends in `/`
+ *                               is a PREFIX row (one part = one file under it). `tier` is a key of SPECIFIER_TIERS:
+ *                               'scene' (a sketch imports it) or 'part-internal' (a forked part file under parts/
+ *                               imports it, never a sketch: the parts' own internal imports, one row per file —
+ *                               the set equals what the registering parts import, held by fork.test.mjs G-CENSUS)
+ *   SPECIFIER_TIERS             { scene, 'part-internal' } — the tier vocabulary and who may import each
  *   libPathOf(specifier)        → the lib-identity path it names; THROWS on an unknown specifier
+ *   tierOf(specifier)           → the row's tier; THROWS on an unknown specifier (libPathOf's rows)
+ *   specifierOfLibPath(libPath) → the specifier naming that lib-identity file, or null: libPathOf's inverse over
+ *                               the same rows (a prefix row answers for each file directly under it)
  *   importMapFor(libRootUrl)    → { imports } — the rows as an import map, every libPath appended to
  *                               the URL of the lib-identity root AS SEEN FROM THE PAGE: an absolute
  *                               URL or one starting with '/', './' or '../' (any other root THROWS —
@@ -20,32 +27,72 @@
  *
  * Inside lib/ the specifier is a SELF-REFERENCE — the package naming itself, the way node resolves a
  * package importing itself by name — not a lib→sdk edge. It is legal ONLY in sketch content
- * (lib/frqtl/scenes/**, codegen output, sketch and notebook text); closure modules import relatively
+ * (lib/frqtl/scenes/**, written sketches, sketch and notebook text); closure modules import relatively
  * (scripts/verify-arrows.mjs holds the scope). Consumers ferry this table and never restate it:
  * every page import map (importMapFor), the node resolve hook (node-specifier-hook.mjs) and the sdk
  * build's module closure (libPathOf).
  */
 
-/** The published surface a sketch imports. Every row is a public exports entry of both packages (sdk/_build/exports-contract.mjs derives them from this table). */
+/** Who imports a row of each tier. */
+export const SPECIFIER_TIERS = Object.freeze({
+    scene: Object.freeze({ id: 'scene', importedBy: 'any project file (a sketch imports it)' }),
+    'part-internal': Object.freeze({ id: 'part-internal', importedBy: 'a part file (parts/*.js) of a project — a forked part imports its parent part\'s internals; never a sketch' })
+});
+
+/** The published surface a project imports. Every row is a public exports entry of both packages (sdk/_build/exports-contract.mjs derives them from this table). */
 export const FRQTL_WEB_SPECIFIERS = Object.freeze([
     Object.freeze({ specifier: '@descix/frqtl-web/parts', libPath: 'frqtl/parts/index.js',
-        why: 'the parts barrel' }),
+        why: 'the parts barrel', tier: 'scene' }),
     Object.freeze({ specifier: '@descix/frqtl-web/parts/', libPath: 'frqtl/parts/',
-        why: 'one part = one file' }),
+        why: 'one part = one file', tier: 'scene' }),
     Object.freeze({ specifier: '@descix/frqtl-web/shim/controls/registry.js', libPath: 'shim/controls/registry.js',
-        why: 'knob registration (blackbody, circuit-sat, collision-matrix-3d, dse-tunnel-rebuild)' }),
+        why: 'knob registration (blackbody, circuit-sat, collision-matrix-3d, dse-tunnel-rebuild)', tier: 'scene' }),
     Object.freeze({ specifier: '@descix/frqtl-web/shim/render/sun-look.js', libPath: 'shim/render/sun-look.js',
-        why: "the one owner of the sun's FX bag (dse-tunnel-rebuild)" }),
+        why: "the one owner of the sun's FX bag (dse-tunnel-rebuild)", tier: 'scene' }),
     Object.freeze({ specifier: '@descix/frqtl-web/compat/renderer/display-slot.js', libPath: 'frqtl/compat/renderer/display-slot.js',
-        why: 'the booted display name before co-init (mirror-route, dse-tunnel-rebuild)' }),
+        why: 'the booted display name before co-init (mirror-route, dse-tunnel-rebuild)', tier: 'scene' }),
     Object.freeze({ specifier: '@descix/frqtl-web/compat/renderer/orbit-bag.js', libPath: 'frqtl/compat/renderer/orbit-bag.js',
-        why: 'hasAngularPose, THE 3D-ness predicate (atomic-model)' }),
+        why: 'hasAngularPose, THE 3D-ness predicate (atomic-model)', tier: 'scene' }),
     Object.freeze({ specifier: '@descix/frqtl-web/objects/setup/_collisionMatrixLanes.js', libPath: 'frqtl/objects/setup/_collisionMatrixLanes.js',
-        why: 'the one lane table (collision-matrix-3d)' }),
+        why: 'the one lane table (collision-matrix-3d)', tier: 'scene' }),
     Object.freeze({ specifier: '@descix/frqtl-web/compat/engine.js', libPath: 'frqtl/compat/engine.js',
-        why: 'the engine accessor (atomic-model builds its frames by hand)' }),
+        why: 'the engine accessor (atomic-model builds its frames by hand)', tier: 'scene' }),
     Object.freeze({ specifier: '@descix/frqtl-web/kinds', libPath: 'frqtl/objects/kinds-entry.js',
-        why: 'the kind registry: a composed fork registers its renamed class (registerKind, kindNamed, kindOf, registeredKinds)' })
+        why: 'the kind registry: a composed fork registers its renamed class (registerKind, kindNamed, kindOf, registeredKinds)', tier: 'scene' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/objects/tagger.js', libPath: 'frqtl/objects/objects/tagger.js',
+        why: 'imported by DetectorWall — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/schema/index.js', libPath: 'frqtl/objects/schema/index.js',
+        why: 'imported by DetectorWall, SlitScreen, Wall — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/shim/render/heat-colormap.js', libPath: 'shim/render/heat-colormap.js',
+        why: 'imported by GraphingDetectorWall — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/schema/valueNormalizer.js', libPath: 'frqtl/objects/schema/valueNormalizer.js',
+        why: 'imported by LiveChart, Wall — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/objects/Box.js', libPath: 'frqtl/objects/objects/Box.js',
+        why: 'imported by OvenBox — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/objects/QuantumEmitter.js', libPath: 'frqtl/objects/objects/QuantumEmitter.js',
+        why: 'imported by OvenBox — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/shim/expr/ast-schema.js', libPath: 'shim/expr/ast-schema.js',
+        why: 'imported by OvenBox, Tunnel — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/objects/actionCompiler.js', libPath: 'frqtl/objects/objects/actionCompiler.js',
+        why: 'imported by OvenBox, Tunnel — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/v1-replacements.js', libPath: 'frqtl/objects/v1-replacements.js',
+        why: 'imported by SlitLightSource — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/objects/slitLinerScatter.js', libPath: 'frqtl/objects/objects/slitLinerScatter.js',
+        why: 'imported by SlitScreen, Tunnel — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/setup/setupSphereEmitter3D.js', libPath: 'frqtl/objects/setup/setupSphereEmitter3D.js',
+        why: 'imported by SphereEmitter — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/objects/directedRedirectProgram.js', libPath: 'frqtl/objects/objects/directedRedirectProgram.js',
+        why: 'imported by Tunnel — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/compat/renderer/lo-drawn-center.js', libPath: 'frqtl/compat/renderer/lo-drawn-center.js',
+        why: 'imported by Tunnel — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/setup/setupTunnelPointExit.js', libPath: 'frqtl/objects/setup/setupTunnelPointExit.js',
+        why: 'imported by Tunnel — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/constants/WallBehaviors.js', libPath: 'frqtl/objects/constants/WallBehaviors.js',
+        why: 'imported by Wall — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/objects/absorbRadiation.js', libPath: 'frqtl/objects/objects/absorbRadiation.js',
+        why: 'imported by Wall — a forked copy imports it', tier: 'part-internal' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/geometry/SlabFace.js', libPath: 'frqtl/objects/geometry/SlabFace.js',
+        why: 'imported by Wall — a forked copy imports it', tier: 'part-internal' })
 ]);
 
 /** The scene doors a host page imports — the package's `./boot` export; never a sketch specifier. */
@@ -56,9 +103,11 @@ export const FRQTL_WEB_BOOT = Object.freeze({ specifier: '@descix/frqtl-web/boot
 export const FRQTL_WEB_HOST_SPECIFIERS = Object.freeze([
     FRQTL_WEB_BOOT,
     Object.freeze({ specifier: '@descix/frqtl-web/registry', libPath: 'shim/registry/index.js',
-        why: 'the walk-through rungs, the showcase roster, the experiment registry, projectOf' }),
+        why: 'the walk-through rungs, the showcase roster, the scene list (sceneGroups), projectOf' }),
     Object.freeze({ specifier: '@descix/frqtl-web/project', libPath: 'shim/project/index.js',
-        why: 'the specifier table, the link site, sketchProject and the project identity' })
+        why: 'the specifier table, the link site, sketchProject and the project identity' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/host-view', libPath: 'shim/host/index.js',
+        why: 'the DeSciX host-view declarer: a page declares its own view' })
 ]);
 
 /** The package a self-reference names. */
@@ -92,6 +141,46 @@ export function libPathOf(specifier) {
         '. (FAIL-LOUD.)');
 }
 
+/** The row naming `specifier` (libPathOf's rule: an exact row first, else a prefix row with a file under it), or null. */
+function _rowOf(specifier) {
+    for (const row of FRQTL_WEB_SPECIFIERS) {
+        if (!_isPrefix(row) && row.specifier === specifier) { return row; }
+    }
+    for (const row of FRQTL_WEB_SPECIFIERS) {
+        if (_isPrefix(row) && specifier.startsWith(row.specifier) && specifier.length > row.specifier.length) { return row; }
+    }
+    return null;
+}
+
+/**
+ * @param {string} specifier — a `@descix/frqtl-web/...` specifier
+ * @returns {string} its row's tier (a key of SPECIFIER_TIERS); THROWS on a specifier no row names
+ */
+export function tierOf(specifier) {
+    libPathOf(specifier);   // the one validation (and its refusal text)
+    return _rowOf(specifier).tier;
+}
+
+/**
+ * @param {string} libPath — a lib-identity path (e.g. 'frqtl/parts/Wall.js', 'frqtl/objects/schema/index.js')
+ * @returns {string|null} the specifier whose row names that file, or null when no row does
+ */
+export function specifierOfLibPath(libPath) {
+    if (typeof libPath !== 'string' || !libPath) {
+        throw new TypeError('[specifiers] specifierOfLibPath(libPath): a lib-identity path (got ' + JSON.stringify(libPath) + '). (FAIL-LOUD.)');
+    }
+    for (const row of FRQTL_WEB_SPECIFIERS) {
+        if (!_isPrefix(row) && row.libPath === libPath) { return row.specifier; }
+    }
+    for (const row of FRQTL_WEB_SPECIFIERS) {
+        if (_isPrefix(row) && libPath.startsWith(row.libPath)) {
+            const rest = libPath.slice(row.libPath.length);
+            if (rest && rest.indexOf('/') === -1) { return row.specifier + rest; }
+        }
+    }
+    return null;
+}
+
 /** An import map resolves an address only if it is an absolute URL or starts with '/', './' or '../'. */
 function _isMapAddress(url) {
     if (/^(\/|\.\/|\.\.\/)/.test(url)) { return true; }

package/dist/shim/registry/exhibits.js

@@ -8,9 +8,9 @@
  * EXHIBITS is the ONE source for the front-page tiles, their GYM deep links and the scene card:
  * nine rows in front-page order, each
  * `{ kind, id, mode, title, tile, what, why, how, controls, still }`.
- *   - `kind` is 'rung' (a walk-through rung, lib/shim/registry/walkthrough.js) or 'experiment'
- *     (a canonical experiment page, lib/shim/registry/experiments.js); `id` resolves there.
- *   - `mode` is a rung's declared mode (null for a single-mode rung and for an experiment).
+ *   - `kind` is 'rung' (a walk-through rung, lib/shim/registry/walkthrough.js); `id` resolves there. A row of
+ *     any other kind THROWS naming the rung form.
+ *   - `mode` is a rung's declared mode (null for a single-mode rung).
  *   - `title` is the tile's and the card's title; `tile` is the published one-sentence tile line.
  *   - `what` (What you are seeing), `why` (Why it is impossible the usual way) and `how` (How FRQTL
  *     gets it) are the card's copy, CARD_PARTS, every one REQUIRED on every row.
@@ -47,14 +47,13 @@
  * @module exhibits
  */
 
-import { EXPERIMENTS, experimentById, experimentIs3D } from './experiments.js';
 import {
     WALKTHROUGH, walkthroughById, walkthroughModes, defaultWalkthroughModeId, walkthroughIs3D, effectiveRenderState
 } from './walkthrough.js';
 import { assertCopyText, assertCopyParagraphs } from './copy-gate.js';
 
 /** The scene kinds a roster row (and a player deep link) can name. */
-export const EXHIBIT_KINDS = Object.freeze(['rung', 'experiment']);
+export const EXHIBIT_KINDS = Object.freeze(['rung']);
 
 /** The copy parts a run-once CARD shows, in order; every roster row carries all of them. */
 export const CARD_PARTS = Object.freeze(['what', 'why', 'how']);
@@ -287,15 +286,6 @@ function rungOrThrow(id) {
     return rung;
 }
 
-function experimentOrThrow(id) {
-    const entry = experimentById(id);
-    if (!entry) {
-        throw new Error('[exhibits] unknown experiment "' + id + '" — declared experiments: [' +
-            EXPERIMENTS.map((e) => e.id).join(', ') + ']. Add it to lib/shim/registry/experiments.js first.');
-    }
-    return entry;
-}
-
 /** A rung's effective mode: the declared one (validated), or null for a single-mode rung. */
 function rungMode(rung, modeId) {
     const eff = (modeId !== undefined && modeId !== null) ? modeId : defaultWalkthroughModeId(rung);
@@ -322,8 +312,8 @@ function assertNotPasted(part, where) {
 }
 
 /**
- * assertRoster — the load-time validator: every row's kind and id resolve in their registry, a
- * rung's mode is declared, an experiment carries none, no scene repeats, no unknown field, every
+ * assertRoster — the load-time validator: every row is a rung whose id resolves in the walk-through
+ * registry, its mode is declared, no scene repeats, no unknown field, every
  * row has a title, a tile line and every CARD_PARTS part, `controls` is non-empty when present, all
  * copy passes the copy gate, and no part pastes the invitation or an intro paragraph. Exported so a
  * test can show each refusal on a planted roster. @returns the normalized, frozen rows (with `order`).
@@ -337,17 +327,10 @@ export function assertRoster(rows) {
             }
         });
         if (EXHIBIT_KINDS.indexOf(row.kind) === -1) {
-            throw new Error('[exhibits] row ' + order + ' kind ' + JSON.stringify(row.kind) + ' — EXHIBIT_KINDS: ' + EXHIBIT_KINDS.join(', ') + '.');
-        }
-        let mode = null;
-        if (row.kind === 'rung') {
-            mode = rungMode(rungOrThrow(row.id), row.mode);
-        } else {
-            experimentOrThrow(row.id);
-            if (row.mode !== undefined) {
-                throw new Error('[exhibits] experiment row "' + row.id + '" names a mode — only a rung has modes.');
-            }
+            throw new Error('[exhibits] row ' + order + ' kind ' + JSON.stringify(row.kind) + ' — an exhibit is a walk-through rung: ' +
+                '{ kind: \'rung\', id: <a lib/shim/registry/walkthrough.js id>, mode? } (EXHIBIT_KINDS: ' + EXHIBIT_KINDS.join(', ') + ').');
         }
+        const mode = rungMode(rungOrThrow(row.id), row.mode);
         if (row.title === undefined || row.title === null) {
             throw new Error('[exhibits] row "' + row.id + '" has no title — every card is titled.');
         }
@@ -380,15 +363,14 @@ export function exhibitsOfKind(kind) {
  * The roster row for a scene, or null when the scene is not on the roster. A null is a DECLARED
  * outcome the caller records (the player plays such a scene with no card: 'not-offered-no-roster-row').
  * The scene itself must exist: an unknown kind, id or mode throws.
- * @param {{kind: 'rung'|'experiment', id: string, modeId?: string|null}} scene
+ * @param {{kind: 'rung', id: string, modeId?: string|null}} scene
  */
 export function exhibitFor(scene) {
     const kind = scene && scene.kind;
     if (EXHIBIT_KINDS.indexOf(kind) === -1) {
         throw new Error('[exhibits] unknown scene kind ' + JSON.stringify(kind) + ' — EXHIBIT_KINDS: ' + EXHIBIT_KINDS.join(', ') + '.');
     }
-    let mode = null;
-    if (kind === 'rung') { mode = rungMode(rungOrThrow(scene.id), scene.modeId); } else { experimentOrThrow(scene.id); }
+    const mode = rungMode(rungOrThrow(scene.id), scene.modeId);
     for (let i = 0; i < EXHIBITS.length; i++) {
         const e = EXHIBITS[i];
         if (e.kind === kind && e.id === scene.id && e.mode === mode) { return e; }
@@ -414,21 +396,20 @@ export const JOYSTICK_EXPLAINER = Object.freeze([
  * sceneKey — the run-once seen-key of a scene: kind, id and, for a multi-mode rung, its EFFECTIVE
  * mode (the one normalizer, rungMode); never a bare id, so it cannot collide with a tab key.
  * Throws for an unknown kind, id or mode.
- * @param {{kind: 'rung'|'experiment', id: string, modeId?: string|null}} scene
+ * @param {{kind: 'rung', id: string, modeId?: string|null}} scene
  */
 export function sceneKey(scene) {
     const kind = scene && scene.kind;
     if (EXHIBIT_KINDS.indexOf(kind) === -1) {
         throw new Error('[exhibits] unknown scene kind ' + JSON.stringify(kind) + ' — EXHIBIT_KINDS: ' + EXHIBIT_KINDS.join(', ') + '.');
     }
-    let mode = null;
-    if (kind === 'rung') { mode = rungMode(rungOrThrow(scene.id), scene.modeId); } else { experimentOrThrow(scene.id); }
+    const mode = rungMode(rungOrThrow(scene.id), scene.modeId);
     return 'scene-' + kind + '-' + scene.id + (mode ? '-' + mode : '');
 }
 
 /**
  * The run-once card of a ROSTER row: title, then `what`, `why`, `how`, `controls` when present, the
- * JOYSTICK_EXPLAINER on a 3D scene (3D read from walkthroughIs3D / experimentIs3D), and
+ * JOYSTICK_EXPLAINER on a 3D scene (3D read from walkthroughIs3D), and
  * SHOWCASE_INVITE last, by reference. Composed from the row and the showcase constants only: no
  * registry prose ever. The bag's { seenKey, title, paragraphs } is what lib/components/run-once-card
  * renders.
@@ -440,7 +421,7 @@ export function showcaseCard(row) {
         throw new Error('[exhibits] showcaseCard takes a roster row (an EXHIBITS element, e.g. exhibitFor(scene)); got ' +
             JSON.stringify(row && { kind: row.kind, id: row.id }) + '.');
     }
-    const is3D = row.kind === 'rung' ? walkthroughIs3D(row.id, row.mode) : experimentIs3D(row.id);
+    const is3D = walkthroughIs3D(row.id, row.mode);
     let paragraphs = CARD_PARTS.map((p) => Object.freeze([row[p]]));
     if (row.controls !== null) { paragraphs = paragraphs.concat([Object.freeze([row.controls])]); }
     if (is3D) { paragraphs = paragraphs.concat(JOYSTICK_EXPLAINER); }

package/dist/shim/registry/index.js

@@ -9,11 +9,11 @@
  *
  *   walkthrough.js   the walk-through rungs: walkthroughById, effectiveRenderState, modes
  *   exhibits.js      the showcase roster
- *   experiments.js   the experiment registry and its tiers
+ *   scene-roster.js  sceneGroups() — THE scene list both views show (the showcase, then the walk-through groups)
  *   scene-source.js  projectOf(id, { mode }) — a rung as a project folder + its renderState (fetch in a page, file read in node)
  */
 
 export * from './walkthrough.js';
 export * from './exhibits.js';
-export * from './experiments.js';
+export * from './scene-roster.js';
 export * from './scene-source.js';

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

@@ -0,0 +1,35 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * scene-roster.js — THE scene list both views show (the GYM's select and STUDIO's dropdown): one owner, read by
+ * both, so the two lists are the same rows in the same order.
+ *
+ *   SHOWCASE_GROUP   the label of the showcase group ('Impossible things')
+ *   sceneGroups()    → [{ label, rows: [{ id, title }] }] — the showcase roster first (EXHIBITS, in tile order,
+ *                      each row its exhibit title), then every walk-through rung in WALKTHROUGH order under its
+ *                      lab group (walkthroughGroup), with NO rung removed from its own group: a showcase rung
+ *                      appears twice, and both rows name the same rung (a deep link selects it either way).
+ *
+ * A row is a scene id a host opens by ?walkthrough=<id>. A host keeps its own non-scene rows (STUDIO's blank world
+ * and saved projects) around these groups; the GYM's default scene is the first row.
+ */
+
+import { EXHIBITS } from './exhibits.js';
+import { WALKTHROUGH, walkthroughGroup } from './walkthrough.js';
+
+/** The showcase group's label. */
+export const SHOWCASE_GROUP = 'Impossible things';
+
+/**
+ * @returns {Array<{label: string, rows: Array<{id: string, title: string}>}>} a new array on every call
+ */
+export function sceneGroups() {
+    var groups = [{ label: SHOWCASE_GROUP, rows: EXHIBITS.map(function (e) { return { id: e.id, title: e.title }; }) }];
+    WALKTHROUGH.forEach(function (r) {
+        var g = walkthroughGroup(r);
+        var last = groups[groups.length - 1];
+        if (groups.length === 1 || last.label !== g) { groups.push({ label: g, rows: [] }); last = groups[groups.length - 1]; }
+        last.rows.push({ id: r.id, title: r.title });
+    });
+    return groups;
+}