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

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, loadSceneSource' }),
+        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-source.js  loadSceneSource(id) — a rung's sketch text (fetch in a page, file read in node)
+ *   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;
+}

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

@@ -1,38 +1,47 @@
 /* Copyright 2023-2026 by Essam Abadir */
 
 /**
- * scene-source.js — the ONE reader of a scene's sketch file, in a page AND in node.
+ * scene-source.js — the ONE reader of a registry scene as a PROJECT, 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.
+ * A scene is ONE sketch file, `lib/frqtl/scenes/<file>.js`: a module whose default export is
+ * `buildExperiment(exp)`, 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
+ * scene (the GYM's rung frame, STUDIO, the hero, a package consumer of `@descix/frqtl-web/registry`) asks
+ * here, so the id → path → URL → project chain exists once.
  *
- *   scenePath(rung)                → 'scenes/<file>.js'   (THROWS on any other shape)
- *   loadSceneSource(scene, opts?)  → Promise<string>      (the file's text)
+ *   scenePath(rung)                         → 'scenes/<file>.js'   (THROWS on any other shape)
+ *   projectOf(scene, { router?, fetch?, mode? })
+ *                                           → Promise<{ manifest, files, renderState }>
+ *       files       { 'frqtl.json': serializeManifest(manifestFor({ name: row.id, entry: 'sketch.js' })),
+ *                     'sketch.js': <the scene file's text> } — the folder a host boots
+ *                     (bootProject(mount, { files, mint }, { renderState }), no entry needed)
+ *       manifest    that frqtl.json's normalized bag
+ *       renderState effectiveRenderState(row, mode) — the registry's one derivation, ferried BESIDE the folder
+ *                   (boot facts never enter frqtl.json or the project identity)
  *
- * `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):
+ * `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.
+ *   - 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 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, 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.
+ * 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.
  *
  * Zero physics: this moves text. The scene's physics is whatever its file composes.
  */
 
 'use strict';
 
-import { WALKTHROUGH, walkthroughById } from './walkthrough.js';
+import { WALKTHROUGH, walkthroughById, effectiveRenderState } from './walkthrough.js';
 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/';
@@ -47,11 +56,11 @@ 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`.
+ * world of its own). A row-shaped handle so it reads through the same `projectOf`.
  */
 export var EMPTY_SCENE = Object.freeze({ id: 'empty', source: 'scenes/empty.js' });
 
-var OPT_KEYS = ['router', 'fetch'];
+var OPT_KEYS = ['router', 'fetch', 'mode'];
 
 /**
  * @param {{id?:string, source?:string}} rung — a registry row.
@@ -77,7 +86,7 @@ function _rowOf(scene) {
         return rung;
     }
     if (!scene || typeof scene !== 'object') {
-        throw new Error('[scene-source] loadSceneSource takes a rung id or a registry row, got ' +
+        throw new Error('[scene-source] projectOf takes a rung id or a registry row, got ' +
             JSON.stringify(scene) + '. (FAIL-LOUD.)');
     }
     return scene;
@@ -88,70 +97,45 @@ 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();
-    });
-}
-
 /**
- * Read a scene file's text through a router's path authority.
+ * 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.
- * @param {{router?:{resolve:function(string):string}, fetch?:function}} [opts]
+ * @param {{router?:{resolve:function(string):string}, fetch?:function, mode?:string|null}} [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>}
+ *   fetch  — the fetch used for a non-file URL (defaults to the global; injectable for tests);
+ *   mode   — a declared walk-through mode (absent: the rung's default) for the renderState.
+ * @returns {Promise<{manifest: object, files: Object<string,string>, renderState: object}>}
  */
-export function loadSceneSource(scene, opts) {
+export function projectOf(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: ' +
+                throw new Error('[scene-source] projectOf has no option "' + k + '" — options: ' +
                     OPT_KEYS.join(', ') + '. (FAIL-LOUD.)');
             }
         });
         var row = _rowOf(scene);
         var rel = scenePath(row);
+        var renderState = effectiveRenderState(row, opts.mode);   // an undeclared mode rejects before the read
         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) {
+        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.)');
             }
-            return t;
+            var manifest = manifestFor({ name: row.id, entry: SKETCH_ENTRY });
+            var files = {};
+            files[MANIFEST_FILE] = serializeManifest(manifest);
+            files[SKETCH_ENTRY] = t;
+            return { manifest: manifest, files: files, renderState: renderState };
         });
     });
 }

package/dist/shim/registry/walkthrough.js

@@ -11,9 +11,10 @@
  *
  * A rung row carries the PATH of its scene, never its text: each scene is ONE sketch
  * file, `lib/frqtl/scenes/<file>.js` — a dual-mode `buildExperiment(exp)` module that
- * holds the whole scene. Its text is read through `loadSceneSource(id | rung, opts)`
- * (./scene-source.js: a fetch in a page, a file read in node; FAIL-LOUD on an unknown id,
- * a non-200 or an empty body). Rungs that share one physics name the SAME file.
+ * holds the whole scene. A host reads it as a project through `projectOf(id | rung, opts)`
+ * (./scene-source.js: frqtl.json + sketch.js, with effectiveRenderState beside it; a fetch in a
+ * page, a file read in node; FAIL-LOUD on an unknown id, a non-200 or an empty body). Rungs
+ * that share one physics name the SAME file.
  *
  * ── Rung descriptor ──────────────────────────────────────────────────────────
  *   id      : stable dropdown id (the `walkthrough:<id>` selection value)
@@ -773,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
@@ -786,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.