@descix/frqtl-node 0.6.1-p3.4 → 0.7.0-p1

package/dist/shim/engine/site-assemble.mjs

@@ -0,0 +1,268 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * site-assemble.mjs — the ONE assembler of a static FRQTL site from the published packages' dists. NODE-ONLY
+ * (it writes files): published as `@descix/frqtl-web/site-assemble`, whose browser condition is a refusal. Every
+ * consumer runs this one function: FRAQTL's `make static-assemble` (scripts/assemble-static-deploy.mjs, a caller that
+ * adds its own gates after it) and a publisher's ship step.
+ *
+ *   assembleSite({ out, build, rosterHref, webDist, mathDist })
+ *       writes the site at `out` in the shape lib/shim/engine/site-graph.js names, and proves it (G-GRAPH):
+ *         <out>/STATIC_APP_PAGE + its assets   ← webDist/SITE_STUDIO_DIR/ (STUDIO), with the site's facts written in:
+ *                                               the build stamp, the baked import map, the roster <link>
+ *         <out>/pub/<build>/<row.dir>/          ← each SITE_PLACEMENTS row's dist, unmodified (STUDIO and the entry
+ *                                               pages moved out of it)
+ *         <out>/pub/<entry>                     ← each entry page of the dists (site-graph.js::isSiteEntry), its
+ *                                               relative URLs re-anchored into pub/<build>/
+ *   stampSiteBuild(html, build)    the ONE writer of the build stamp (its one reader: site-graph.js::siteBuildStampOf)
+ *   writeRosterLink(html, href)    the ONE writer of `<link rel="frqtl-roster" href="…">` (the assembler and the dev
+ *                                  server, lib/server/plugin.js)
+ *   placeEntryHtml(html, page, build, graphHas)
+ *                                  an entry page of a dist (graph at the dist root) re-anchored for the site (graph
+ *                                  under pub/<build>/)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+    SITE_GRAPH_DIR, SITE_BUILD_ATTR, SITE_BUILD_ID_RE, STATIC_APP_PAGE, SITE_STUDIO_DIR, SITE_PLACEMENTS, isSiteEntry,
+    siteGraphFaults,
+} from './site-graph.js';
+import { engineRouter, staticSdkBase } from './router.js';
+import { spliceRealmImportMap } from '../notebook/vendor-importmap.js';
+// The roster link's rel and its href rule have one owner each (lib/shim/registry): this module writes what they read.
+import { ROSTER_LINK_REL, rosterLinksOfHtml } from '../registry/roster-link.js';
+import { rosterHrefRefusalOf } from '../registry/roster.js';
+/** A dist's integrity record (sdk/_build/dist-manifest.cjs writes it at every dist root). */
+const DIST_MANIFEST_FILE = 'dist-manifest.json';
+
+const sha256 = (abs) => crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex');
+
+/**
+ * The document with its <html> element stamped <html SITE_BUILD_ATTR="<build>">. THROWS on an invalid build id,
+ * a document with no <html> element, or one already stamped. The ONE writer of the stamp.
+ * @param {string} html
+ * @param {string} build
+ * @returns {string}
+ */
+export function stampSiteBuild(html, build) {
+    if (typeof build !== 'string' || !SITE_BUILD_ID_RE.test(build)) {
+        throw new Error('[site-assemble] stampSiteBuild: the build id must match ' + SITE_BUILD_ID_RE + ', got ' + JSON.stringify(build) + '.');
+    }
+    if (!/<html\b/i.test(html) || html.includes(SITE_BUILD_ATTR + '=')) {
+        throw new Error('[site-assemble] stampSiteBuild: the document must carry exactly one unstamped <html> element');
+    }
+    return html.replace(/<html\b/i, '<html ' + SITE_BUILD_ATTR + '="' + build + '"');
+}
+
+/** THROWS, naming `where` and the rule (roster.js::rosterHrefRefusalOf), unless `href` can be a roster URL. */
+function refuseRosterHref(href, where) {
+    const why = rosterHrefRefusalOf(href);
+    if (why) { throw new Error('[site-assemble] ' + where + ': ' + why); }
+}
+
+/**
+ * The document with `<link rel="frqtl-roster" href="<href>">` written before </head>. THROWS on a bad href
+ * (roster.js::rosterHrefRefusalOf), a document that already carries a roster link, or one without exactly one </head>.
+ * @param {string} html
+ * @param {string} href  absolute
+ * @returns {string}
+ */
+export function writeRosterLink(html, href) {
+    refuseRosterHref(href, 'writeRosterLink(html, href)');
+    if (rosterLinksOfHtml(html).length) {
+        throw new Error('[site-assemble] writeRosterLink: the document already carries a <link rel="' + ROSTER_LINK_REL + '"> — one roster per document.');
+    }
+    if ((html.match(/<\/head>/gi) || []).length !== 1) {
+        throw new Error('[site-assemble] writeRosterLink: the document must carry exactly one </head>.');
+    }
+    const esc = href.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+    return html.replace(/<\/head>/i, '    <link rel="' + ROSTER_LINK_REL + '" href="' + esc + '">\n</head>');
+}
+
+// ── Entry pages ──────────────────────────────────────────────────────────────
+
+/** A src=/href= value, or a quoted string literal that starts with ./ or ../ (an import, a map address, a URL). */
+const RELATIVE_REF = /(\b(?:src|href)=")([^"]*)(")|(["'])(\.\.?\/[^"'\s]*)\4/g;
+const HTML_COMMENT = /<!--[\s\S]*?-->/g;
+
+/**
+ * An ENTRY page of a dist (its graph at the dist root) re-anchored for a site whose graph sits under
+ * `<build>/` beside it: every relative URL the page carries outside HTML comments — src=/href= values, import-map
+ * addresses, module specifiers, `new URL("…")` literals — that resolves to a graph file or directory is pointed into
+ * `<build>/`; one that resolves to another entry page is kept; absolute, fragment and query-only URLs are kept.
+ * THROWS on a relative URL leaving the dist root or naming nothing the graph holds.
+ *
+ * @param {string} html
+ * @param {string} page     the page's dist-root-relative path ('sdk.html', 'experiments/empty/index.html')
+ * @param {string} build    the build id (the graph's directory name under SITE_GRAPH_DIR/)
+ * @param {(distRel: string) => boolean} graphHas  does the graph hold this dist-relative file or directory?
+ * @returns {string}
+ */
+export function placeEntryHtml(html, page, build, graphHas) {
+    if (!SITE_BUILD_ID_RE.test(build)) {
+        throw new Error('[site-assemble] placeEntryHtml: the build id must match ' + SITE_BUILD_ID_RE + ', got ' + JSON.stringify(build) + '.');
+    }
+    const pageDir = path.posix.dirname(page);
+    const place = (url) => {
+        if (url === '' || /^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith('/') || url[0] === '#' || url[0] === '?') { return url; }
+        const cut = url.search(/[?#]/);
+        const p = cut === -1 ? url : url.slice(0, cut);
+        const suffix = cut === -1 ? '' : url.slice(cut);
+        const distRel = path.posix.normalize(path.posix.join(pageDir, p));
+        const bare = distRel.replace(/\/$/, '');
+        if (bare === '..' || bare.startsWith('../')) {
+            throw new Error('[site-assemble] entry ' + page + ' references "' + url + '", outside the dist root.');
+        }
+        if (isSiteEntry(bare)) { return url; }
+        if (!graphHas(bare)) {
+            throw new Error('[site-assemble] entry ' + page + ' references "' + url + '" (' + bare + '), which is neither an ' +
+                'entry page nor a file or directory the graph holds — cannot place it.');
+        }
+        let rel = path.posix.relative(pageDir, build + '/' + bare) + (distRel.endsWith('/') ? '/' : '');
+        if (url.startsWith('./') && !rel.startsWith('.')) { rel = './' + rel; }
+        return rel + suffix;
+    };
+    let out = '';
+    let last = 0;
+    for (const m of html.matchAll(HTML_COMMENT)) {
+        out += html.slice(last, m.index).replace(RELATIVE_REF, (whole, a, url, z, q, rel) =>
+            (a !== undefined ? a + place(url) + z : q + place(rel) + q)) + m[0];
+        last = m.index + m[0].length;
+    }
+    return out + html.slice(last).replace(RELATIVE_REF, (whole, a, url, z, q, rel) =>
+        (a !== undefined ? a + place(url) + z : q + place(rel) + q));
+}
+
+// ── The assembly ─────────────────────────────────────────────────────────────
+
+function walkFiles(dir, skip) {
+    const out = [];
+    (function walk(rel) {
+        for (const d of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+            const r = rel ? rel + '/' + d.name : d.name;
+            if (skip && skip(r)) { continue; }
+            if (d.isDirectory()) { walk(r); continue; }
+            if (!d.isFile()) { throw new Error('[site-assemble] ' + path.join(dir, r) + ' is neither a file nor a directory. (FAIL-LOUD.)'); }
+            out.push(r);
+        }
+    })('');
+    return out.sort();
+}
+
+function readDistManifest(dist, pkg) {
+    const file = path.join(dist, DIST_MANIFEST_FILE);
+    if (!fs.existsSync(file)) {
+        throw new Error('[site-assemble] ' + dist + ' has no ' + DIST_MANIFEST_FILE + ' — it is not a built ' + pkg + ' dist.');
+    }
+    const m = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (m.name !== pkg) {
+        throw new Error('[site-assemble] ' + dist + ' is the dist of ' + JSON.stringify(m.name) + ', not ' + pkg + '.');
+    }
+    return { manifest: m, sha256: sha256(file) };
+}
+
+/**
+ * Assemble the static site at `out` (wiped first) and prove it. THROWS on a bad argument, a missing STUDIO or
+ * vendor manifest in the web dist, an entry page that cannot be placed, or any G-GRAPH fault
+ * (site-graph.js::siteGraphFaults — the same rule a publisher runs on a served site).
+ *
+ * @param {object} o
+ * @param {string} o.out         absolute path of the site directory to write
+ * @param {string} o.build       the build id (SITE_BUILD_ID_RE): the graph's directory and the stamp
+ * @param {string} o.rosterHref  the roster's ABSOLUTE URL, written as the STUDIO page's `<link rel="frqtl-roster">`
+ * @param {string} o.webDist     absolute path of a built @descix/frqtl-web dist
+ * @param {string} o.mathDist    absolute path of a built @descix/egpt-math-sdk dist
+ * @returns {{ out: string, build: string, graphFiles: number, entries: string[], appFiles: string[], releases: string[] }}
+ */
+export function assembleSite(o) {
+    const { out, build, rosterHref, webDist, mathDist } = o || {};
+    // STUDIO reads every scene row through <link rel="frqtl-roster" href>, which this call writes.
+    refuseRosterHref(rosterHref, 'assembleSite needs `rosterHref`, the roster\'s URL written into STUDIO\'s <link rel="' +
+        ROSTER_LINK_REL + '">');
+    if (typeof build !== 'string' || !SITE_BUILD_ID_RE.test(build)) {
+        throw new Error('[site-assemble] assembleSite: `build` must match ' + SITE_BUILD_ID_RE + ' (got ' + JSON.stringify(build) + ').');
+    }
+    for (const [k, v] of [['out', out], ['webDist', webDist], ['mathDist', mathDist]]) {
+        if (typeof v !== 'string' || !path.isAbsolute(v)) {
+            throw new Error('[site-assemble] assembleSite: `' + k + '` must be an absolute path (got ' + JSON.stringify(v) + ').');
+        }
+    }
+    const distOf = { '@descix/frqtl-web': webDist, '@descix/egpt-math-sdk': mathDist };
+    const placed = SITE_PLACEMENTS.map((row) => {
+        const dist = distOf[row.package];
+        if (!dist) { throw new Error('[site-assemble] SITE_PLACEMENTS names ' + row.package + ', which assembleSite is not given a dist for.'); }
+        return { row, dist, ...readDistManifest(dist, row.package) };
+    });
+    const studioDir = path.join(webDist, SITE_STUDIO_DIR);
+    if (!fs.existsSync(path.join(studioDir, STATIC_APP_PAGE))) {
+        throw new Error('[site-assemble] ' + webDist + ' carries no ' + SITE_STUDIO_DIR + '/' + STATIC_APP_PAGE + ' — STUDIO is built ' +
+            'into the @descix/frqtl-web dist by its build (node build.js in sdk/frqtl-web).');
+    }
+
+    const outUrl = pathToFileURL(out + path.sep).href;
+    const graphDir = fileURLToPath(staticSdkBase(outUrl, build));
+    const entryDir = path.dirname(graphDir);
+    fs.rmSync(out, { recursive: true, force: true });
+    fs.mkdirSync(out, { recursive: true });
+
+    // 1. STUDIO → the site root.
+    fs.cpSync(studioDir, out, { recursive: true });
+    // 2. Each placed dist → pub/<build>/<row.dir>, unmodified; the graph-root row first, so a nested row lands inside it.
+    for (const p of placed.slice().sort((a, b) => a.row.dir.length - b.row.dir.length)) {
+        fs.cpSync(p.dist, p.row.dir ? path.join(graphDir, p.row.dir) : graphDir, { recursive: true });
+    }
+    fs.rmSync(path.join(graphDir, SITE_STUDIO_DIR), { recursive: true, force: true });
+    // 3. Entry pages → pub/<entry>, re-anchored into the graph; the graph keeps no entry copy.
+    const graphHas = (rel) => fs.existsSync(path.join(graphDir, rel));
+    const entries = walkFiles(graphDir).filter(isSiteEntry);
+    for (const rel of entries) {
+        const dest = path.join(entryDir, rel);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, placeEntryHtml(fs.readFileSync(path.join(graphDir, rel), 'utf8'), rel, build, graphHas));
+    }
+    for (const rel of entries) { fs.rmSync(path.join(graphDir, rel)); }
+    (function prune(dir) {
+        for (const d of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!d.isDirectory()) { continue; }
+            const p = path.join(dir, d.name);
+            prune(p);
+            if (fs.readdirSync(p).length === 0) { fs.rmdirSync(p); }
+        }
+    })(graphDir);
+    // 4. The site's facts in STUDIO's page: the build stamp, the import map (every address through the static router,
+    //    document-relative, over the PLACED vendor manifest), the roster link.
+    const appPage = path.join(out, STATIC_APP_PAGE);
+    const vendorManifest = fileURLToPath(engineRouter({ mode: 'static', documentBaseURI: outUrl, build }).vendorBase + '/manifest.json');
+    if (!fs.existsSync(vendorManifest)) {
+        throw new Error('[site-assemble] the placed graph has no vendor manifest at ' + vendorManifest + ' — the web dist is incomplete.');
+    }
+    let html = stampSiteBuild(fs.readFileSync(appPage, 'utf8'), build);
+    html = spliceRealmImportMap(html, JSON.parse(fs.readFileSync(vendorManifest, 'utf8')),
+        engineRouter({ mode: 'static', documentRelative: true, build }));
+    html = writeRosterLink(html, rosterHref);
+    fs.writeFileSync(appPage, html);
+
+    // 5. G-GRAPH: the graph, the entries and the site root are the placed releases' bytes.
+    const graph = {};
+    for (const rel of walkFiles(graphDir)) { graph[rel] = sha256(path.join(graphDir, rel)); }
+    const graphName = path.basename(graphDir);
+    const entrySet = new Set(walkFiles(entryDir, (r) => r === graphName));
+    const app = {};
+    for (const rel of walkFiles(out, (r) => r === SITE_GRAPH_DIR)) { app[rel] = sha256(path.join(out, rel)); }
+    const releases = placed.map((p) => ({
+        dir: p.row.dir, name: p.manifest.name, version: p.manifest.version, files: p.manifest.files,
+        manifest: { file: DIST_MANIFEST_FILE, sha256: p.sha256 },
+    }));
+    const faults = siteGraphFaults({ graph, entries: entrySet, app }, releases);
+    if (faults.length) {
+        throw new Error('[site-assemble] G-GRAPH: ' + faults.length + ' fault(s) — the site at ' + out + ' is not the placed ' +
+            'releases\' bytes:\n  ' + faults.join('\n  '));
+    }
+    return {
+        out, build, graphFiles: Object.keys(graph).length, entries: [...entrySet].sort(), appFiles: Object.keys(app).sort(),
+        releases: releases.map((r) => r.name + '@' + r.version),
+    };
+}

package/dist/shim/engine/site-graph.js

@@ -14,21 +14,25 @@
  *   SITE_BUILD_ID_RE    a <build>: the 8-hex-digit short sha of the commit the bundle was built from
  *   siteBuildStampOf    the ONE reader of that stamp
  *   STATIC_APP_PAGE     the IDE bundle's entry document, beside the publisher's front page
+ *   SITE_STUDIO_DIR     the @descix/frqtl-web dist directory holding STUDIO (STATIC_APP_PAGE + its assets): the site
+ *                       places it at the site ROOT, beside the front page, never in the graph
  *   HOST_PROVIDED_ATTR  the attribute declaring a file host-provided (the publisher vendors it beside the page)
  *   SITE_PLACEMENTS     each published package placed in the graph, and the graph directory it is placed at
  *   SITE_ENTRY_PAGES, isSiteEntry
  *                       the @descix/frqtl-web dist's HTML ENTRIES (reached by navigation or iframe, never loaded as a
  *                       resource): the site keeps them at fixed URLs under SITE_GRAPH_DIR/, outside the stamped graph
- *   siteGraphFaults     the served graph against the placed releases' dist-manifest.json records (empty = faithful)
+ *   siteGraphFaults     the served graph and site root against the placed releases' dist-manifest.json records
+ *                       (empty = faithful)
  *   SITE_GRAPH_EXPORTS  the published names (the parity gate holds both packages' ./site-graph to this table)
  *
- * Host-neutral ESM with no imports: it loads unchanged in node and in a page.
+ * Host-neutral ESM with no imports: it loads unchanged in node and in a page. The node-only assembler that WRITES a
+ * site to this shape is lib/shim/engine/site-assemble.mjs (`@descix/frqtl-web/site-assemble`).
  */
 
 /** The names `./site-graph` publishes. */
 export const SITE_GRAPH_EXPORTS = Object.freeze([
-    'SITE_GRAPH_DIR', 'SITE_BUILD_ATTR', 'SITE_BUILD_ID_RE', 'siteBuildStampOf', 'STATIC_APP_PAGE', 'HOST_PROVIDED_ATTR',
-    'SITE_PLACEMENTS', 'SITE_ENTRY_PAGES', 'isSiteEntry', 'siteGraphFaults',
+    'SITE_GRAPH_DIR', 'SITE_BUILD_ATTR', 'SITE_BUILD_ID_RE', 'siteBuildStampOf', 'STATIC_APP_PAGE', 'SITE_STUDIO_DIR',
+    'HOST_PROVIDED_ATTR', 'SITE_PLACEMENTS', 'SITE_ENTRY_PAGES', 'isSiteEntry', 'siteGraphFaults',
 ]);
 
 /** The static site's graph directory name (the entries sit in it, the graph under its build-stamped child). */
@@ -60,9 +64,17 @@ export function siteBuildStampOf(html) {
  */
 export const STATIC_APP_PAGE = 'app.html';
 
+/**
+ * The @descix/frqtl-web dist directory holding STUDIO (its `./studio` export: STATIC_APP_PAGE and its assets). A site
+ * places its contents at the site ROOT, beside the front page — never in the graph — and writes the site's facts (the
+ * build stamp, the import map, the roster link) into STATIC_APP_PAGE, so that one file is the only one whose bytes
+ * differ from the release.
+ */
+export const SITE_STUDIO_DIR = 'studio';
+
 /**
  * The attribute that declares a file host-provided, on the element that consumes it, in the bytes the browser
- * executes (the static build writes it: apps/ide/vite.config.js). Both the bundle gate (the file must be ABSENT from
+ * executes (the STUDIO build writes it: sdk/frqtl-web/studio.vite.config.js). Both the bundle gate (the file must be ABSENT from
  * the bundle) and the publisher (the file must be PRESENT beside the page) read the set from this attribute.
  */
 export const HOST_PROVIDED_ATTR = 'data-frqtl-host-provided';
@@ -81,7 +93,7 @@ export const SITE_PLACEMENTS = Object.freeze([
  * The @descix/frqtl-web dist's HTML entry pages written by its entry writer (dist-root-relative). The experiment pages
  * (experiments/{id}/index.html) are entries too; isSiteEntry names both.
  */
-export const SITE_ENTRY_PAGES = Object.freeze(['sdk.html', 'artifact/sun.html', 'artifact/double-slit.html']);
+export const SITE_ENTRY_PAGES = Object.freeze(['sdk.html']);
 const EXPERIMENT_ENTRY = /^experiments\/[^/]+\/index\.html$/;
 
 /**
@@ -94,11 +106,12 @@ export function isSiteEntry(rel) {
 }
 
 /**
- * Is a served site graph the placed releases' bytes? PURE: the caller enumerates and hashes.
+ * Is a served site the placed releases' bytes? PURE: the caller enumerates and hashes.
  *
- * @param {{graph: Object<string,string>, entries: Set<string>}} served
+ * @param {{graph: Object<string,string>, entries: Set<string>, app: Object<string,string>}} served
  *   graph    graph-relative path → sha256 hex, for EVERY file under SITE_GRAPH_DIR/<build>/
  *   entries  the paths present under SITE_GRAPH_DIR/ outside the stamped directory (SITE_GRAPH_DIR-relative)
+ *   app      site-root-relative path → sha256 hex, for every file at the site root outside SITE_GRAPH_DIR/
  * @param {Array<{dir: string, name: string, version: string, files: Object<string,string>,
  *                manifest: {file: string, sha256: string}}>} releases
  *   one per SITE_PLACEMENTS row: its `dir`, the release's dist-manifest.json `name`, `version` and `files`, and the
@@ -108,14 +121,19 @@ export function isSiteEntry(rel) {
  *   - a graph file with no owning placement (longest dir prefix), not listed by its owner, or of another sha256;
  *   - a placement's manifest absent from the graph, or not the release's bytes;
  *   - a listed file absent from the graph, unless it is an entry (isSiteEntry) present among `entries`;
- *   - an entry still inside the graph (each entry has ONE URL).
+ *   - an entry still inside the graph (each entry has ONE URL);
+ *   - a SITE_STUDIO_DIR file of the graph-root placement still inside the graph, absent from the site root, or (any
+ *     file but STATIC_APP_PAGE, which the assembly writes into) of other bytes than the release lists.
  */
 export function siteGraphFaults(served, releases) {
     const graph = served && served.graph;
     const entries = served && served.entries;
-    if (!graph || typeof graph !== 'object' || !(entries instanceof Set) || !Array.isArray(releases) || releases.length === 0) {
-        throw new Error('[site-graph] siteGraphFaults({graph: {path: sha256}, entries: Set}, releases[]) — got ' +
-            JSON.stringify({ graph: typeof graph, entries: Object.prototype.toString.call(entries), releases: Array.isArray(releases) ? releases.length : typeof releases }) + '.');
+    const app = served && served.app;
+    if (!graph || typeof graph !== 'object' || !(entries instanceof Set) || !app || typeof app !== 'object' ||
+        !Array.isArray(releases) || releases.length === 0) {
+        throw new Error('[site-graph] siteGraphFaults({graph: {path: sha256}, entries: Set, app: {path: sha256}}, releases[]) — got ' +
+            JSON.stringify({ graph: typeof graph, entries: Object.prototype.toString.call(entries), app: typeof app,
+                releases: Array.isArray(releases) ? releases.length : typeof releases }) + '.');
     }
     for (const r of releases) {
         if (!r || typeof r.dir !== 'string' || !r.files || typeof r.files !== 'object' || !r.manifest ||
@@ -165,14 +183,24 @@ export function siteGraphFaults(served, releases) {
         }
     }
 
-    // 3. Every listed file is served: in the graph, or (an entry) at its fixed URL and NOT in the graph.
+    // 3. Every listed file is served: in the graph, (an entry) at its fixed URL, or (STUDIO) at the site root — the
+    //    last two NOT in the graph.
+    const studioPrefix = SITE_STUDIO_DIR + '/';
     for (const r of releases) {
         const m = placed(r, r.manifest.file);
         if (!Object.prototype.hasOwnProperty.call(graph, m)) { faults.push(label(r) + '\'s ' + r.manifest.file + ' is absent from the graph'); }
         for (const key of Object.keys(r.files).sort()) {
             const rel = placed(r, key);
             const inGraph = Object.prototype.hasOwnProperty.call(graph, rel);
-            if (isSiteEntry(rel)) {
+            if (r.dir === '' && key.startsWith(studioPrefix)) {
+                const appRel = key.slice(studioPrefix.length);
+                if (inGraph) { faults.push('STUDIO file ' + rel + ' (' + label(r) + ') is inside the graph — STUDIO is placed at the site root'); }
+                if (!Object.prototype.hasOwnProperty.call(app, appRel)) {
+                    faults.push('STUDIO file ' + key + ' (' + label(r) + ') is absent from the site root (' + appRel + ')');
+                } else if (appRel !== STATIC_APP_PAGE && app[appRel] !== r.files[key]) {
+                    faults.push('site-root file ' + appRel + ' is ' + app[appRel] + ', ' + label(r) + ' lists ' + key + ' as ' + r.files[key]);
+                }
+            } else if (isSiteEntry(rel)) {
                 if (inGraph) { faults.push('entry ' + rel + ' (' + label(r) + ') is still inside the graph — an entry has one URL, at ' + SITE_GRAPH_DIR + '/' + rel); }
                 if (!entries.has(rel)) { faults.push('entry ' + rel + ' (' + label(r) + ') is absent from ' + SITE_GRAPH_DIR + '/'); }
             } else if (!inGraph) {

package/dist/shim/host/device.js

@@ -12,7 +12,7 @@
  *                         matchMedia THROWS: every browser has it, so its absence is a caller passing the wrong object.
  *
  * Its three consumers ask it once each, at load:
- *   - the host-view call site (apps/ide/src/host-view-entry.js) asks the shell for NoChrome on a phone, CodeSite
+ *   - the host-view call site (lib/features/ide/studio/host-view-entry.js) asks the shell for NoChrome on a phone, CodeSite
  *     elsewhere;
  *   - STUDIO (lib/features/ide/AuthorView.jsx) opens with its side panels collapsed on a phone and puts its Hand tool
  *     between the camera joysticks (the phone toolbar Move | Hand | Look), and words its mirror "try it" for that

package/dist/shim/index.js

@@ -7,7 +7,9 @@
  * FAIL-LOUD load error — no window.Common* ambient globals.
  *
  * Usage (under vite with alias 'lib' → repo-root/lib):
- *   import { Bus, Runtime, sceneGroups, engineRouter } from 'lib/shim';
+ *   import { Bus, Runtime, engineRouter } from 'lib/shim';
+ *
+ * The scene registry (the roster contract, its loader and readers) has its own door, ./registry/index.js.
  *
  * Usage (direct relative path):
  *   import { Bus } from '../../lib/shim/index.js';
@@ -15,12 +17,6 @@
 
 export { Bus }           from './bus.js';
 export { Runtime }       from './runtime/index.js';
-export { sceneGroups, SHOWCASE_GROUP } from './registry/scene-roster.js';
-export { WALKTHROUGH, walkthroughIs3D, walkthroughModes, walkthroughGroup,
-         walkthroughById,
-         FIRST_CONTACT_WALKTHROUGH_ID,
-         defaultWalkthroughModeId, effectiveRenderState } from './registry/walkthrough.js';
-export { projectOf, scenePath, EMPTY_SCENE } from './registry/scene-source.js';
 // The host-side experiment-iframe guard (the false-200 trap). Exported from the
 // barrel so every host that frames an experiment page (lib/features/ide's GYM)
 // asserts against the SAME contract.

package/dist/shim/notebook/catalog.js

@@ -5,8 +5,8 @@
  *
  * The catalog (lib/notebooks/notebooks.json) owns the notebook roster AND, beside it, the
  * `firstContact` id: the notebook FAT opens on when no `?notebook=` is named (the
- * Entropy-Log Bijection). Declared beside the roster, as the walkthrough registry
- * declares FIRST_CONTACT_WALKTHROUGH_ID beside its rungs. A deep link naming a notebook wins;
+ * Entropy-Log Bijection). Declared beside the roster, as a scene roster declares its
+ * `firstContact` (lib/shim/registry/roster.js). A deep link naming a notebook wins;
  * that branch never reaches this reader.
  *
  * Callers: NotebookBrowserView (the served catalog, at open), scripts/assemble-static-deploy.mjs

package/dist/shim/notebook/format.js

@@ -133,7 +133,7 @@ export const PROSE_CELL_TYPES = Object.freeze(['markdown']);
  *   For `canvas` cells: OPTIONAL render-INTENT knob assignments parsed from
  *   `"key=value,…"` (gym-controls-as-sugar fix-loop #6 Finding B, 2026-07-04) —
  *   the notebook-cell channel for the SAME render-intent writes a scene file states
- *   itself (e.g. lib/frqtl/scenes/collision-matrix-3d.js's
+ *   itself (e.g. a 3D sketch's
  *   `exp.render({ shape: 'sphere', colorScheme: 'roygbiv' })`, a ferry to
  *   `runner.setRenderOptions`). PURE PARSE — reuses the identical `_parseOpts`/
  *   `_joinOpts` machinery as `opts` (same `kind:'opts'`), but is a DISTINCT,

package/dist/shim/notebook/knob.js

@@ -15,7 +15,7 @@
  * an out-of-range value, or a spec that defines no knob THROWS — never a silent
  * ignore (that would be the hint-only/lie-in-surface class the gate forbids).
  *
- * ── Why this lives in lib/shim (not the pane, not exhibits.js) ────────────────
+ * ── Why this lives in lib/shim (not the pane, not the scene registry) ─────────
  *
  * The knob SCHEMA lives ONCE, notebook-scoped, in the sibling module
  * lib/shim/notebook/notebook-knobs.js (NOTEBOOK_KNOBS). A canvas cell's live

package/dist/shim/notebook/notebook-knobs.js

@@ -18,7 +18,7 @@
  * not to the Impossible Gallery exhibit card (a separate public-site curation
  * surface). Keeping the schema here — a lib/shim sibling of knob.js — makes the
  * notebook path self-contained: knob.js reads this table directly (a same-layer
- * read), with no upward dependency on lib/shim/registry/exhibits.js.
+ * read), with no upward dependency on lib/shim/registry.
  *
  * knob.js remains the MECHANISM owner (validate + param→factory-option map);
  * this module is only the DECLARATION. One authority, no mirror.

package/dist/shim/project/specifiers.js

@@ -27,7 +27,7 @@
  *
  * 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/**, written sketches, sketch and notebook text); closure modules import relatively
+ * (a host's scene files, 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).
@@ -46,17 +46,17 @@ export const FRQTL_WEB_SPECIFIERS = Object.freeze([
     Object.freeze({ specifier: '@descix/frqtl-web/parts/', libPath: 'frqtl/parts/',
         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)', tier: 'scene' }),
+        why: 'knob registration (registerControls): a scene declares its own sliders and toggles', 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)", tier: 'scene' }),
+        why: "the one owner of the sun's FX bag (SunLook)", 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)', tier: 'scene' }),
+        why: 'the booted display name a dual-mode scene reads before its co-init call', 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)', tier: 'scene' }),
+        why: 'hasAngularPose, THE 3D-ness predicate of a camera pose', 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)', tier: 'scene' }),
+        why: 'the one collision-lane table (density lanes of a collision scene)', 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)', tier: 'scene' }),
+        why: 'the engine accessor (a scene that 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)', tier: 'scene' }),
     Object.freeze({ specifier: '@descix/frqtl-web/objects/objects/tagger.js', libPath: 'frqtl/objects/objects/tagger.js',
@@ -103,7 +103,7 @@ 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 scene list (sceneGroups), projectOf, showcaseHref + showcaseUrl + SHOWCASE_SITE, STUDIO\'s deep-link landing record' }),
+        why: 'the roster contract and its readers (normalizeRoster, sceneGroups, showcaseCard, showcaseHref), the roster loader (loadRoster), projectOf + emptyProjectOf, STUDIO\'s deep-link landing record' }),
     Object.freeze({ specifier: '@descix/frqtl-web/project', libPath: 'shim/project/index.js',
         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',

package/dist/shim/registry/copy-gate.js

@@ -3,8 +3,8 @@
 /**
  * copy-gate.js — the ONE owner of what shipped copy may look like: the placeholder rules and the
  * segment shape. Every table of viewer-facing copy validates through it at load:
- * lib/shim/registry/exhibits.js (the showcase roster, SHOWCASE_INTRO, SHOWCASE_THROUGH_LINE,
- * SHOWCASE_INVITE) and lib/features/ide/presets.js (PRESET_EXPLAINERS).
+ * lib/shim/registry/roster.js (a host roster's showcase copy: cards, the intro, the invite and the through-line) and
+ * lib/features/ide/presets.js (PRESET_EXPLAINERS).
  *
  *   assertCopyText(text, where)                        → text   (non-empty, no placeholder)
  *   assertCopyParagraphs(paragraphs, where, { table }) → paragraphs
@@ -98,7 +98,7 @@ export function assertCopyParagraphs(paragraphs, where, opts) {
         }
         if (para && typeof para === 'object' && has(para, 'table')) {
             if (!opts.table) {
-                throw new Error(at + ' is a table paragraph — a table is allowed only in the run-once intro (SHOWCASE_INTRO); ' +
+                throw new Error(at + ' is a table paragraph — a table is allowed only in a showcase intro (roster.js ROSTER_KEYS.intro); ' +
                     'this copy is plain paragraphs.');
             }
             walkLeaves(para.table, at);

package/dist/shim/registry/index.js

@@ -3,23 +3,20 @@
 /**
  * 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.
+ * Each module below owns its own surface; this file only ferries them. The package holds no scene rows: a host
+ * declares them in its roster, and every reader takes the loaded bag first.
  * 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
- *   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)
- *   showcase-link.js showcaseHref(row), showcaseUrl(row), SHOWCASE_SITE — a showcase tile's link (relative, absolute)
- *                    and the site that serves it; `row` is an element of THIS barrel's EXHIBITS
+ *   roster.js         THE roster contract (ROSTER_KEYS, normalizeRoster) and its readers: scene rows, modes,
+ *                     effectiveRenderState, sceneGroups, firstContactOf, the showcase cards and links, sceneUrlOf
+ *   roster-link.js    THE loader: rosterHrefOf(document), loadRoster(href), sceneOriginRefusalOf
+ *   scene-source.js   projectOf(roster, id, { mode }) and emptyProjectOf({ router }) — a scene as a project folder
  *   studio-landing.js STUDIO_LANDING_ATTR, STUDIO_LANDING_OUTCOMES, recordStudioLanding — how STUDIO resolved the deep
- *                    link it opened with, recorded on <html> (what a gate following a tile reads)
+ *                     link it opened with, recorded on <html> (what a gate following a tile reads)
  */
 
-export * from './walkthrough.js';
-export * from './exhibits.js';
-export * from './scene-roster.js';
+export * from './roster.js';
+export * from './roster-link.js';
 export * from './scene-source.js';
-export * from './showcase-link.js';
 export * from './studio-landing.js';