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

package/dist/shim/project/link.js

@@ -0,0 +1,402 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * link.js — THE link site: a project (one or more ES module files held as text, or a served folder)
+ * becomes imported modules, and its entry's default export is the scene.
+ *
+ *   linkProject(project) → Promise<{ buildExperiment, files }>   files: { path: Uint8Array } — the bytes linked
+ *     project = { files: { 'sketch.js': text, 'parts/X.js': text, … }, entry, mint, bare? }
+ *             | { url: '<served folder>/', entry, mint?, bare? }
+ *       url    absolute, or relative to the document's base URL in a page ('./'); ends in "/"
+ *       entry  REQUIRED — the root-relative path of the file whose default export is
+ *              `function buildExperiment(exp)`
+ *       mint   REQUIRED — the host's (text, path) → { url, release? }: `blobMint` in a page, `dataMint` in
+ *              node. Hosts differ ONLY here. A served folder is minted too: each file is fetched ONCE, as
+ *              bytes; those bytes are the identity, and the same bytes, decoded once (UTF-8, fatal), are
+ *              the text that runs. Nothing is fetched a second time.
+ *       bare   (spec) → URL for a `@descix/frqtl-web/...` specifier; default: the specifier's
+ *              lib-identity path (specifiers.js libPathOf) under THIS copy's package root
+ *              (compat/package-root.js), so a project links against the very modules its boot loaded.
+ *              A host whose modules are not served one file per URL (frqtl-web.min.js) passes its own.
+ *     resolves { buildExperiment, files } — files is the project's BYTES by path (fetched, for a served
+ *       folder; the UTF-8 encoding of each text, for a file map), the input of projectIdentity (identity.js).
+ *
+ * In a project, a file imports another project file by a RELATIVE specifier, and the package by
+ * `@descix/frqtl-web/...`; nothing else. Relative specifiers are rewritten to the minted URLs of the files
+ * they name, in topological order (a file is minted after everything it imports). REFUSED before anything
+ * 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 no project file (never an HTTP
+ * sibling), a @descix/frqtl-web specifier that is not a row of FRQTL_WEB_SPECIFIERS, any other specifier;
+ * an import cycle among project files; a file-map entry the entry never reaches (a project is exactly the
+ * module graph its entry reaches, so every host hashes one set); 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.
+ *
+ *   blobMint(text) → { url, release() }   a `blob:` module URL (a page)
+ *   dataMint(text) → { url, release() }   a `data:` module URL (node)
+ *
+ * A one-string sketch is the one-file project: `{ files: { 'sketch.js': text }, entry: 'sketch.js' }` —
+ * 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 { checkProjectPath, projectBytes } from './identity.js';
+import { packageRoot } from '../../frqtl/compat/package-root.js';
+
+const SKETCH_FORM = 'export default function buildExperiment(exp) { … }';
+
+/** THE decoder of served bytes: invalid UTF-8 throws; a BOM is stripped from the text (never from the identity bytes). */
+const _UTF8 = new TextDecoder('utf-8', { fatal: true });
+
+function _fail(msg) {
+    throw new Error('[link] ' + msg + ' (FAIL-LOUD.)');
+}
+
+/**
+ * The text with every comment blanked to spaces (newlines kept), so offsets into it are offsets into
+ * the text. String and template literals are skipped, so a '//' inside a string is not a comment.
+ * @param {string} text
+ * @returns {string}
+ */
+function _blankComments(text) {
+    const out = text.split('');
+    let i = 0;
+    const n = text.length;
+    while (i < n) {
+        const c = text[i];
+        if (c === '/' && text[i + 1] === '/') {
+            while (i < n && text[i] !== '\n') { out[i] = ' '; i++; }
+        } else if (c === '/' && text[i + 1] === '*') {
+            const end = text.indexOf('*/', i + 2);
+            const stop = end === -1 ? n : end + 2;
+            for (; i < stop; i++) { if (text[i] !== '\n') { out[i] = ' '; } }
+        } else if (c === '\'' || c === '"' || c === '`') {
+            i++;
+            while (i < n && text[i] !== c) { if (text[i] === '\\') { i++; } i++; }
+            i++;
+        } else {
+            i++;
+        }
+    }
+    return out.join('');
+}
+
+const _IMPORT_RE = /(?:^|[;\n}])\s*(?:import|export)\b[^'";]*?\bfrom\s*(['"])([^'"\n]+)\1|(?:^|[;\n}])\s*import\s*(['"])([^'"\n]+)\3|\bimport\s*\(\s*(['"])([^'"\n]+)\5\s*\)/dg;
+
+/**
+ * Every static import / export-from / side-effect import / literal dynamic import of `text`.
+ * @param {string} text
+ * @returns {{spec: string, start: number, end: number}[]} start/end bracket the specifier's characters
+ */
+function _imports(text) {
+    const code = _blankComments(text);
+    const out = [];
+    let m;
+    _IMPORT_RE.lastIndex = 0;
+    while ((m = _IMPORT_RE.exec(code))) {
+        const g = m[2] !== undefined ? 2 : (m[4] !== undefined ? 4 : 6);
+        out.push({ spec: m[g], start: m.indices[g][0], end: m.indices[g][1] });
+    }
+    return out;
+}
+
+function _isRelative(spec) {
+    return spec.startsWith('./') || spec.startsWith('../');
+}
+
+/** A row of FRQTL_WEB_SPECIFIERS names it (libPathOf, the table's one reader). */
+function _isPublished(spec) {
+    try { libPathOf(spec); return true; } catch (_) { return false; }
+}
+
+function _publishedList() {
+    return FRQTL_WEB_SPECIFIERS.map(function (r) { return r.specifier + (r.specifier.endsWith('/') ? '<file>' : ''); }).join(', ');
+}
+
+function _isPackage(spec) {
+    return spec === FRQTL_WEB_PACKAGE || spec.startsWith(FRQTL_WEB_PACKAGE + '/');
+}
+
+/** The project path a relative specifier names from `fromPath`, or null when it climbs out of the root. */
+function _resolveRelative(fromPath, spec) {
+    const segs = fromPath.split('/');
+    segs.pop();
+    for (const s of spec.split('/')) {
+        if (s === '.' || s === '') { continue; }
+        if (s === '..') {
+            if (segs.length === 0) { return null; }
+            segs.pop();
+        } else {
+            segs.push(s);
+        }
+    }
+    return segs.join('/');
+}
+
+/**
+ * The project's import graph from `entry`: each file's imports, classified and checked.
+ * @param {string} entry
+ * @param {function(string): Promise<{text: string, bytes: Uint8Array}>} sourceOf — path → its text and bytes
+ *   (throws naming a file it lacks)
+ * @returns {Promise<{order: string[], files: Object<string,string>, bytes: Object<string,Uint8Array>, edges: Object<string, object[]>}>}
+ */
+async function _walk(entry, sourceOf) {
+    const files = {};
+    const bytes = {};
+    const edges = {};
+    const order = [];
+    const state = {};   // path → 'visiting' | 'done'
+    async function visit(p, stack, spec) {
+        if (state[p] === 'done') { return; }
+        if (state[p] === 'visiting') {
+            const loop = stack.slice(stack.indexOf(p)).concat(p);
+            _fail('the project files import each other in a cycle: ' + loop.join(' → ') + ' — a project file graph ' +
+                'is acyclic (each file is minted after everything it imports).');
+        }
+        state[p] = 'visiting';
+        const src = await sourceOf(p, stack[stack.length - 1], spec);
+        const text = src.text;
+        files[p] = text;
+        bytes[p] = src.bytes;
+        const list = [];
+        for (const imp of _imports(text)) {
+            if (_isRelative(imp.spec)) {
+                const target = _resolveRelative(p, imp.spec);
+                if (target === null) {
+                    _fail('"' + p + '" imports "' + imp.spec + '" — outside the project; package internals have no ' +
+                        'public specifier (a project file imports the package by a @descix/frqtl-web/... row).');
+                }
+                list.push(Object.assign({ kind: 'file', target: target }, imp));
+            } else if (_isPackage(imp.spec)) {
+                if (!_isPublished(imp.spec)) {
+                    _fail('"' + p + '" imports "' + imp.spec + '" — not a published specifier; the table ' +
+                        '(lib/shim/project/specifiers.js FRQTL_WEB_SPECIFIERS) offers: ' + _publishedList() + '.');
+                }
+                list.push(Object.assign({ kind: 'package' }, imp));
+            } else {
+                _fail('"' + p + '" imports "' + imp.spec + '" — a project file imports another project file by a ' +
+                    'relative specifier (./X.js) and the package by @descix/frqtl-web/...; nothing else.');
+            }
+        }
+        edges[p] = list;
+        for (const e of list) {
+            if (e.kind === 'file') { await visit(e.target, stack.concat(p), e.spec); }
+        }
+        state[p] = 'done';
+        order.push(p);
+    }
+    await visit(entry, []);
+    return { order: order, files: files, bytes: bytes, edges: edges };
+}
+
+/**
+ * The served folder's absolute URL: an absolute `url` as given; a relative one ('./', as a project's own
+ * index.html writes it) against the document's base URL. A host with no document REJECTS a relative one.
+ * @param {string} url
+ * @returns {string}
+ */
+function _folderUrl(url) {
+    try { return new URL(url).href; } catch (_) { /* relative: resolved below */ }
+    if (typeof document === 'undefined' || !document || typeof document.baseURI !== 'string') {
+        _fail('linkProject({ url }): ' + JSON.stringify(url) + ' is relative and this host has no document to ' +
+            'resolve it against — pass the absolute folder URL (e.g. new URL(\'./proj/\', import.meta.url).href).');
+    }
+    return new URL(url, document.baseURI).href;
+}
+
+/** Rewrite each import specifier of `text` through `urlOf(edge)`, escaped for the literal's own quote. */
+function _rewrite(text, list, urlOf) {
+    let out = text;
+    for (const e of list.slice().sort((a, b) => b.start - a.start)) {
+        const quote = text[e.start - 1];
+        const lit = String(urlOf(e)).replace(/\\/g, '\\\\').split(quote).join('\\' + quote);
+        out = out.slice(0, e.start) + lit + out.slice(e.end);
+    }
+    return out;
+}
+
+/**
+ * A project is EXACTLY the module graph its entry reaches, so every host hashes one set: a served folder is
+ * that set by construction, and a file map may hold nothing else. REFUSES a file-map entry the walk did not
+ * reach, naming it.
+ */
+function _refuseUnreached(project, g) {
+    if (project.files === undefined) { return; }
+    const unused = Object.keys(project.files).filter(function (p) { return !Object.prototype.hasOwnProperty.call(g.files, p); });
+    if (unused.length) {
+        _fail('unused project file "' + unused[0] + '" — a project holds the files its entry imports' +
+            (unused.length > 1 ? ' (also unused: ' + unused.slice(1).join(', ') + ')' : '') + '.');
+    }
+}
+
+function _defaultBare(spec) {
+    return new URL(libPathOf(spec), packageRoot()).href;
+}
+
+function _entryFunction(ns, entry) {
+    if (typeof ns.default !== 'function') {
+        _fail('the entry "' + entry + '" has no default export function — its form is ' + SKETCH_FORM +
+            ' (a classic sketch\'s `window.buildExperiment` tail is retired: write the ES module form).');
+    }
+    return ns.default;
+}
+
+/**
+ * @param {object} project — see the file header
+ * @returns {Promise<{buildExperiment: function, files: Object<string, string>}>}
+ */
+export async function linkProject(project) {
+    if (!project || typeof project !== 'object') {
+        _fail('linkProject(project): project is { files, entry, mint } or { url, entry } (got ' + typeof project + ').');
+    }
+    const entry = project.entry;
+    if (typeof entry !== 'string' || !entry) {
+        _fail('linkProject: `entry` is REQUIRED — the path of the file whose default export is the scene ' +
+            '(a one-string sketch: { files: { "sketch.js": text }, entry: "sketch.js" }).');
+    }
+    checkProjectPath(entry);
+    const hasFiles = project.files !== undefined;
+    const hasUrl = project.url !== undefined;
+    if (hasFiles === hasUrl) {
+        _fail('linkProject: a project is EITHER { files, entry } OR { url, entry } (got ' +
+            (hasFiles ? 'both' : 'neither') + ').');
+    }
+    const mint = project.mint;
+    if (typeof mint !== 'function') {
+        _fail('linkProject: mint is REQUIRED — the host\'s (text, path) → { url, release? } (blobMint in a page, ' +
+            'dataMint in node; lib/shim/project/link.js). A served folder is minted from the bytes it fetched.');
+    }
+    const bare = project.bare === undefined ? _defaultBare : project.bare;
+    if (typeof bare !== 'function') {
+        _fail('linkProject: bare is (specifier) → URL for a @descix/frqtl-web/... specifier.');
+    }
+
+    let sourceOf;
+    let base = null;
+    if (hasFiles) {
+        const files = project.files;
+        if (!files || typeof files !== 'object' || Object.keys(files).length === 0) {
+            _fail('linkProject: project.files is the map { path: text } and has no files.');
+        }
+        for (const p of Object.keys(files)) {
+            checkProjectPath(p);
+            if (typeof files[p] !== 'string') { _fail('linkProject: file "' + p + '" is not text.'); }
+        }
+        const encoded = projectBytes(files);
+        sourceOf = async function (p, from, spec) {
+            if (!Object.prototype.hasOwnProperty.call(files, p)) {
+                _fail(from === undefined
+                    ? 'the entry "' + p + '" is not a project file (files: ' + Object.keys(files).join(', ') + ').'
+                    : '"' + from + '" imports "' + spec + '" (' + p + '), which is not a project file (files: ' +
+                      Object.keys(files).join(', ') + ') — a relative specifier names a file in the project, never an HTTP ' +
+                      'sibling; package internals have no public specifier.');
+            }
+            const t = files[p];
+            if (!t.trim()) { _fail('the project file "' + p + '" is empty.'); }
+            return { text: t, bytes: encoded[p] };
+        };
+    } else {
+        if (typeof project.url !== 'string' || !project.url.endsWith('/')) {
+            _fail('linkProject({ url }): url is the served project folder, ending in "/" (got ' + JSON.stringify(project.url) + ').');
+        }
+        base = _folderUrl(project.url);
+        sourceOf = async function (p, from, spec) {
+            const u = new URL(p, base).href;
+            let res;
+            try { res = await fetch(u); }
+            catch (e) { _fail('fetching "' + p + '" (' + u + ') failed: ' + String((e && e.message) || e) + '.'); }
+            if (!res.ok) {
+                _fail((from === undefined ? 'the entry "' + p + '"' : '"' + from + '" imports "' + spec + '" (' + p + '), which') +
+                    ' is not served at ' + u + ' (HTTP ' + res.status + ')' +
+                    (from === undefined ? '.' : ' — a relative specifier names a file in the project; package internals have no public specifier.'));
+            }
+            const raw = new Uint8Array(await res.arrayBuffer());
+            let text;
+            try { text = _UTF8.decode(raw); }
+            catch (e) { _fail('"' + p + '" is not valid UTF-8 (' + u + ') — a project file is a UTF-8 text module.'); }
+            if (!text.trim()) { _fail('the project file "' + p + '" is empty.'); }
+            return { text: text, bytes: raw };
+        };
+    }
+
+    const g = await _walk(entry, sourceOf);
+    _refuseUnreached(project, g);
+
+    const urls = {};
+    const minted = [];
+    try {
+        for (const p of g.order) {
+            const text = _rewrite(g.files[p], g.edges[p], function (e) {
+                return e.kind === 'file' ? urls[e.target] : bare(e.spec);
+            });
+            const m = mint(text, p);
+            if (!m || typeof m.url !== 'string') { _fail('mint(text, path) must return { url, release? } (for "' + p + '").'); }
+            minted.push(m);
+            urls[p] = m.url;
+        }
+        const ns = await import(urls[entry]);
+        return { buildExperiment: _entryFunction(ns, entry), files: g.bytes };
+    } finally {
+        for (const m of minted) { if (typeof m.release === 'function') { m.release(); } }
+    }
+}
+
+/** The entry path of a one-string sketch held as a project. */
+export const SKETCH_ENTRY = 'sketch.js';
+
+/**
+ * The one-file project of a sketch held as one string.
+ * @param {string} text
+ * @returns {{files: Object<string, string>, entry: string}}
+ */
+export function sketchProject(text) {
+    if (typeof text !== 'string') {
+        _fail('sketchProject(text): the sketch module text (got ' + typeof text + ').');
+    }
+    const files = {};
+    files[SKETCH_ENTRY] = text;
+    return { files: files, entry: SKETCH_ENTRY };
+}
+
+/** A `blob:` module URL for `text` (a page). */
+export function blobMint(text) {
+    const url = URL.createObjectURL(new Blob([text], { type: 'text/javascript' }));
+    return { url: url, release: function () { URL.revokeObjectURL(url); } };
+}
+
+/**
+ * The `bare` of a host whose modules are NOT served one file per URL (frqtl-web.min.js): a
+ * `@descix/frqtl-web/...` specifier resolves to a minted module that re-exports the namespace this
+ * host already evaluated for libPathOf(spec), read through `readExpr` (a global expression the minted
+ * module can reach, e.g. 'FRQTL.modules'). One minted URL per module, kept for the page's lifetime,
+ * so every project links against the same instances. A specifier whose module the host does not carry
+ * THROWS naming it.
+ * @param {Object<string, object>} modules — lib-relative path → module namespace
+ * @param {string} readExpr — the expression that evaluates to `modules` in a minted module
+ * @param {function(string): {url: string}} mint
+ * @returns {function(string): string}
+ */
+export function namespaceBare(modules, readExpr, mint) {
+    const urls = {};
+    return function bare(spec) {
+        const libPath = libPathOf(spec);
+        if (urls[libPath]) { return urls[libPath]; }
+        const ns = modules[libPath];
+        if (!ns) {
+            _fail('"' + spec + '" names ' + libPath + ', which this host does not carry (it carries: ' +
+                Object.keys(modules).join(', ') + ').');
+        }
+        const lines = ['const ns = ' + readExpr + '[' + JSON.stringify(libPath) + '];'];
+        for (const k of Object.keys(ns)) {
+            if (k === 'default') { lines.push('export default ns.default;'); }
+            else if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k)) { lines.push('export const ' + k + ' = ns.' + k + ';'); }
+            else { _fail(libPath + ' exports "' + k + '", which is not an identifier.'); }
+        }
+        urls[libPath] = mint(lines.join('\n') + '\n').url;
+        return urls[libPath];
+    };
+}
+
+/** A `data:` module URL for `text` (node). */
+export function dataMint(text) {
+    return { url: 'data:text/javascript;charset=utf-8,' + encodeURIComponent(text), release: function () {} };
+}

package/dist/shim/project/node-specifier-hook.mjs

@@ -0,0 +1,35 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * node-specifier-hook.mjs — node resolves a sketch's `@descix/frqtl-web/...` self-reference through
+ * ONE hook, mapped by the ONE table (specifiers.js libPathOf) to this tree's lib-identity files.
+ *
+ *   registerFrqtlWebSpecifiers()   install the hook in this process (idempotent). Call it once
+ *                                  before importing a scene file; the scene realm, the digest
+ *                                  harness and the engine-at-eval gate do.
+ *   resolve(specifier, context, next)   the hook itself (module.register's resolve export)
+ *
+ * In a package, the hook maps into that package's own dist (this file sits at dist/shim/project/); the published
+ * door is `@descix/frqtl-node/register` (register-node.mjs). Node ≥ 20.6 (module.register).
+ */
+
+import { register } from 'node:module';
+import { libPathOf, FRQTL_WEB_PACKAGE } from './specifiers.js';
+
+const LIB_ROOT = new URL('../../', import.meta.url);   // lib/ in the tree, dist/ in a package (this file is <root>/shim/project/)
+
+/** The module.register resolve hook. */
+export async function resolve(specifier, context, nextResolve) {
+    if (specifier === FRQTL_WEB_PACKAGE || specifier.startsWith(FRQTL_WEB_PACKAGE + '/')) {
+        return { url: new URL(libPathOf(specifier), LIB_ROOT).href, shortCircuit: true };
+    }
+    return nextResolve(specifier, context);
+}
+
+let _registered = false;
+/** Install the hook in this process (once). */
+export function registerFrqtlWebSpecifiers() {
+    if (_registered) { return; }
+    register(import.meta.url);
+    _registered = true;
+}

package/dist/shim/project/register-node.mjs

@@ -0,0 +1,17 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * register-node.mjs — `@descix/frqtl-node/register`: importing it installs the resolve hook for a sketch's
+ * `@descix/frqtl-web/...` imports in this node process (node-specifier-hook.mjs), mapped by the one table to
+ * this package's own files.
+ *
+ *     node --import @descix/frqtl-node/register my-scene.mjs
+ *     // or, before the first import of a sketch:  import '@descix/frqtl-node/register';
+ */
+
+import { registerFrqtlWebSpecifiers } from './node-specifier-hook.mjs';
+
+registerFrqtlWebSpecifiers();
+
+/** Re-exported for a host that registers explicitly (idempotent: importing this module already did). */
+export { registerFrqtlWebSpecifiers };

package/dist/shim/project/specifiers.js

@@ -0,0 +1,106 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * 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)
+ *   libPathOf(specifier)        → the lib-identity path it names; THROWS on an unknown specifier
+ *   importMapFor(libRootUrl)    → { imports } — the rows as an import map, every libPath appended to
+ *                               the URL (relative or absolute) of the lib-identity root AS SEEN FROM
+ *                               THE PAGE; prefix rows stay prefixes. No filesystem computation, so
+ *                               a vendored dist root takes the same call.
+ *   FRQTL_WEB_BOOT              { specifier: '@descix/frqtl-web/boot', libPath } — the scene doors a HOST
+ *                               PAGE imports (the package's `./boot`). Not a sketch specifier: libPathOf
+ *                               refuses it, so a sketch cannot boot a page.
+ *   pageImportMapFor(libRootUrl) → importMapFor(libRootUrl) plus the FRQTL_WEB_BOOT row: the map of a page
+ *                               that boots a scene through the doors and runs sketches beside it.
+ *
+ * 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
+ * (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). */
+export const FRQTL_WEB_SPECIFIERS = Object.freeze([
+    Object.freeze({ specifier: '@descix/frqtl-web/parts', libPath: 'frqtl/parts/index.js',
+        why: 'the parts barrel' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/parts/', libPath: 'frqtl/parts/',
+        why: 'one part = one file' }),
+    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)' }),
+    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)" }),
+    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)' }),
+    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)' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/objects/setup/_collisionMatrixLanes.js', libPath: 'frqtl/objects/setup/_collisionMatrixLanes.js',
+        why: 'the one lane table (collision-matrix-3d)' }),
+    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)' }),
+    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)' })
+]);
+
+/** The scene doors a host page imports — the package's `./boot` export; never a sketch specifier. */
+export const FRQTL_WEB_BOOT = Object.freeze({ specifier: '@descix/frqtl-web/boot', libPath: 'frqtl/experiments/_shared/doors.js' });
+
+/** The package a self-reference names. */
+export const FRQTL_WEB_PACKAGE = '@descix/frqtl-web';
+
+function _isPrefix(row) { return row.specifier.endsWith('/'); }
+
+/**
+ * @param {string} specifier — a `@descix/frqtl-web/...` specifier
+ * @returns {string} the lib-identity path (e.g. 'frqtl/parts/Wall.js')
+ */
+export function libPathOf(specifier) {
+    if (typeof specifier !== 'string') {
+        throw new TypeError('[specifiers] libPathOf(specifier): a string specifier (got ' + typeof specifier + '). (FAIL-LOUD.)');
+    }
+    for (const row of FRQTL_WEB_SPECIFIERS) {
+        if (!_isPrefix(row) && row.specifier === specifier) { return row.libPath; }
+    }
+    for (const row of FRQTL_WEB_SPECIFIERS) {
+        if (_isPrefix(row) && specifier.startsWith(row.specifier) && specifier.length > row.specifier.length) {
+            const rest = specifier.slice(row.specifier.length);
+            if (rest.split('/').indexOf('..') !== -1) {
+                throw new Error('[specifiers] "' + specifier + '" climbs out of its prefix row (' + row.specifier + '). (FAIL-LOUD.)');
+            }
+            return row.libPath + rest;
+        }
+    }
+    throw new Error('[specifiers] "' + specifier + '" is not a @descix/frqtl-web specifier — the table ' +
+        '(lib/shim/project/specifiers.js FRQTL_WEB_SPECIFIERS) offers: ' +
+        FRQTL_WEB_SPECIFIERS.map(function (r) { return r.specifier + (_isPrefix(r) ? '<file>' : ''); }).join(', ') +
+        '. (FAIL-LOUD.)');
+}
+
+/**
+ * @param {string} libRootUrl — the lib-identity root as seen from the page, ending in `/`
+ *   (e.g. '../../', '/pub/abc123/', 'vendor/frqtl-web/0.6.0/dist/')
+ * @returns {{imports: Object<string, string>}}
+ */
+export function importMapFor(libRootUrl) {
+    if (typeof libRootUrl !== 'string' || !libRootUrl.endsWith('/')) {
+        throw new TypeError('[specifiers] importMapFor(libRootUrl): the lib-identity root URL as seen from the page, ' +
+            'ending in "/" (got ' + JSON.stringify(libRootUrl) + '). (FAIL-LOUD.)');
+    }
+    const imports = {};
+    for (const row of FRQTL_WEB_SPECIFIERS) { imports[row.specifier] = libRootUrl + row.libPath; }
+    return { imports: imports };
+}
+
+/**
+ * @param {string} libRootUrl — as importMapFor's
+ * @returns {{imports: Object<string, string>}} importMapFor(libRootUrl) plus the FRQTL_WEB_BOOT row
+ */
+export function pageImportMapFor(libRootUrl) {
+    const map = importMapFor(libRootUrl);
+    map.imports[FRQTL_WEB_BOOT.specifier] = libRootUrl + FRQTL_WEB_BOOT.libPath;
+    return map;
+}