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

package/dist/shim/project/record-format.js

@@ -0,0 +1,345 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * record-format.js — THE owner of the Record folder's shape (the sketch-projects design §6), and its ONE writer.
+ *
+ * A Record is its own folder, and it contains the project it recorded:
+ *
+ *   record.json          { tickRange: [first, last], clips: ['clip-01.mp4', …], changes: [{tick, name, op, by, from, to}] }
+ *   clip-01.mp4 …        the FrqtlVision footage, one file per CLIP_SECONDS segment, in the order filmed
+ *   parts.before.json    { "<name>": ["<registered kind name>", {props}] } at Record start, in key order
+ *   parts.after.json     the same at stop; their diff IS the code change
+ *   project/…            the project's files at stop (frqtl.json, sketch.js, parts/*, README), replayable
+ *                        through bootProject
+ *
+ * A host's own files (a lab's lab.json) may sit beside these; this module never reads or checks them.
+ *
+ *   RECORD_FILES         the folder's §6 paths (record, partsBefore, partsAfter, project)
+ *   RECORD_KEYS          record.json's keys, exactly — there is no record-level who
+ *   CHANGE_KEYS          one change row's keys, exactly
+ *   OPS                  the change ops: a placement is `move` whatever hand made it
+ *   BY                   who acted, per row
+ *   CLIP_SECONDS         { min, max } — the length of one clip, in seconds of playback
+ *   CLIP_NAME            the clip file pattern; clipName(n) → 'clip-NN.mp4' (n from 1)
+ *   jsonText(v)          JSON.stringify(v, null, 2) + '\n' — every JSON file of the folder
+ *   recordFolderFaults(files) → string[]   [] for a complete §6 folder, every fault by name otherwise
+ *   serializeRecordFolder(parts) → { files, record, clips } | { empty: true }   THE writer (Record.js calls it;
+ *                        it runs recordFolderFaults on its own output and THROWS on any fault)
+ *
+ * `files` is a tree { path → string | Uint8Array }: JSON and project text as strings (or UTF-8 bytes), clips
+ * as bytes. Values in §6 files are strict JSON, in record.json's own vocabulary; a placeholder ("*",
+ * {unavailable}) never sits in a §6 field.
+ */
+
+import { MANIFEST_FILE } from './manifest.js';
+import { entryOf } from './link.js';
+
+/** The folder's §6 paths. */
+export const RECORD_FILES = Object.freeze({
+    record: 'record.json',
+    partsBefore: 'parts.before.json',
+    partsAfter: 'parts.after.json',
+    project: 'project/'
+});
+
+/** record.json's keys, exactly. */
+export const RECORD_KEYS = Object.freeze(['tickRange', 'clips', 'changes']);
+
+/** One change row's keys, exactly. */
+export const CHANGE_KEYS = Object.freeze(['tick', 'name', 'op', 'by', 'from', 'to']);
+
+/** The change ops. */
+export const OPS = Object.freeze(['move', 'setDeclared', 'add', 'remove', 'fork']);
+
+/** Who acted (each row's `by`). */
+export const BY = Object.freeze(['human', 'maxi']);
+
+/** The length of one clip, in seconds of playback (frames / fps). */
+export const CLIP_SECONDS = Object.freeze({ min: 5, max: 10 });
+
+/** The clip file pattern. */
+export const CLIP_NAME = /^clip-(\d{2})\.mp4$/;
+
+/** @param {number} n 1-based @returns {string} 'clip-NN.mp4' */
+export function clipName(n) {
+    if (!Number.isInteger(n) || n < 1 || n > 99) {
+        throw new Error('[record-format] a clip number is a whole number 1–99, got ' + JSON.stringify(n) + '. (FAIL-LOUD.)');
+    }
+    return 'clip-' + String(n).padStart(2, '0') + '.mp4';
+}
+
+/** THE text of every JSON file of a Record folder. */
+export function jsonText(v) {
+    return JSON.stringify(v, null, 2) + '\n';
+}
+
+// ── value shapes ────────────────────────────────────────────────────────────────
+
+const POSITION_KEYS = Object.freeze({ center: [3], rect: [4, 6] });
+const FORK_FILE = /^parts\/[^/]+\.js$/;
+
+function _isPlain(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) &&
+        (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+}
+
+/** The first path inside `v` that is not strict JSON (a function, NaN, undefined, a class instance …), else null. */
+function _strictJsonFault(v, at) {
+    if (v === null || typeof v === 'string' || typeof v === 'boolean') { return null; }
+    if (typeof v === 'number') { return Number.isFinite(v) ? null : at + ' is ' + String(v); }
+    if (Array.isArray(v)) {
+        for (let i = 0; i < v.length; i++) { const f = _strictJsonFault(v[i], at + '[' + i + ']'); if (f) { return f; } }
+        return null;
+    }
+    if (_isPlain(v)) {
+        for (const k of Object.keys(v)) { const f = _strictJsonFault(v[k], at + '.' + k); if (f) { return f; } }
+        return null;
+    }
+    return at + ' is ' + (v === undefined ? 'undefined' : typeof v === 'object' ? 'a ' + ((v.constructor && v.constructor.name) || 'class') + ' instance' : 'a ' + typeof v);
+}
+
+/** Every placeholder inside `v`: an {unavailable} object or a "*" string. */
+function _placeholders(v, at, out) {
+    if (v === '*') { out.push(at + ' is the placeholder "*"'); return out; }
+    if (Array.isArray(v)) { v.forEach(function (x, i) { _placeholders(x, at + '[' + i + ']', out); }); return out; }
+    if (v && typeof v === 'object') {
+        if (Object.prototype.hasOwnProperty.call(v, 'unavailable')) { out.push(at + ' is the placeholder {unavailable}'); return out; }
+        Object.keys(v).forEach(function (k) { _placeholders(v[k], at + '.' + k, out); });
+    }
+    return out;
+}
+
+function _isEntry(e) {
+    return Array.isArray(e) && e.length === 2 && typeof e[0] === 'string' && e[0].length > 0 && _isPlain(e[1]) && !_strictJsonFault(e[1], '');
+}
+
+/** { key, length } of a move value `{center: [3]}` / `{rect: [4|6]}`, else null. */
+function _placement(v) {
+    if (!_isPlain(v)) { return null; }
+    const ks = Object.keys(v);
+    if (ks.length !== 1 || !POSITION_KEYS[ks[0]]) { return null; }
+    const a = v[ks[0]];
+    if (!Array.isArray(a) || POSITION_KEYS[ks[0]].indexOf(a.length) === -1 || !a.every(function (n) { return typeof n === 'number' && Number.isFinite(n); })) { return null; }
+    return { key: ks[0], length: a.length };
+}
+
+const MOVE_SHAPE = 'move carries from/to as ONE key, {center: [x, y, z]} or {rect: [4 numbers flat | 6 with a z-extent]}, the same key and length in both';
+
+/** The faults of one change row against its op. */
+function _rowFaults(c, at) {
+    const bad = [];
+    if (!_isPlain(c)) { return [at + ' is not a change {' + CHANGE_KEYS.join(', ') + '}']; }
+    const keys = Object.keys(c);
+    if (keys.length !== CHANGE_KEYS.length || !CHANGE_KEYS.every(function (k) { return keys.indexOf(k) !== -1; })) {
+        bad.push(at + ' carries exactly {' + CHANGE_KEYS.join(', ') + '}, got {' + keys.join(', ') + '}');
+    }
+    if (!Number.isInteger(c.tick) || c.tick < 0) { bad.push(at + '.tick is a whole tick ≥ 0, got ' + JSON.stringify(c.tick)); }
+    if (typeof c.name !== 'string' || !c.name) { bad.push(at + '.name is the declared name, got ' + JSON.stringify(c.name)); }
+    if (BY.indexOf(c.by) === -1) { bad.push(at + '.by is one of ' + BY.join('|') + ', got ' + JSON.stringify(c.by)); }
+    ['from', 'to'].forEach(function (k) {
+        const f = _strictJsonFault(c[k], at + '.' + k);
+        if (f) { bad.push(f + ' — from/to are strict JSON'); }
+    });
+    if (c.op === 'move') {
+        const a = _placement(c.from), b = _placement(c.to);
+        if (!a || !b || a.key !== b.key || a.length !== b.length) { bad.push(at + ': ' + MOVE_SHAPE + ', got ' + JSON.stringify([c.from, c.to])); }
+        else if (JSON.stringify(c.from) === JSON.stringify(c.to)) { bad.push(at + ' is a zero move of "' + c.name + '" — an act that moved nothing writes no row'); }
+    } else if (c.op === 'setDeclared') {
+        if (!_isPlain(c.from) || !_isPlain(c.to) || !Object.keys(c.to).length ||
+            JSON.stringify(Object.keys(c.from).sort()) !== JSON.stringify(Object.keys(c.to).sort())) {
+            bad.push(at + ': setDeclared carries from/to as {key: value} of the patched keys, the same keys before and after, got ' + JSON.stringify([c.from, c.to]));
+        }
+    } else if (c.op === 'add') {
+        if (c.from !== null || !_isEntry(c.to)) { bad.push(at + ': add carries from: null and to: ["<registered kind name>", {props}], got ' + JSON.stringify([c.from, c.to])); }
+    } else if (c.op === 'remove') {
+        if (c.to !== null || !_isEntry(c.from)) { bad.push(at + ': remove carries from: ["<registered kind name>", {props}] and to: null, got ' + JSON.stringify([c.from, c.to])); }
+    } else if (c.op === 'fork') {
+        const ok = typeof c.from === 'string' && c.from.length > 0 && _isPlain(c.to) &&
+            JSON.stringify(Object.keys(c.to).sort()) === '["file","kind"]' &&
+            typeof c.to.kind === 'string' && c.to.kind.length > 0 && typeof c.to.file === 'string' && FORK_FILE.test(c.to.file);
+        if (!ok) { bad.push(at + ': fork carries from: "<source kind name>" and to: {"kind": "<new kind name>", "file": "parts/<File>.js"}, got ' + JSON.stringify([c.from, c.to])); }
+    } else {
+        bad.push(at + '.op ' + JSON.stringify(c.op) + ' is not one of ' + OPS.join('|') + ' (a placement is "move" whatever hand made it)');
+    }
+    return bad;
+}
+
+function _text(v) {
+    return typeof v === 'string' ? v : new TextDecoder('utf-8', { fatal: true }).decode(v);
+}
+
+function _isBytes(v) { return v instanceof Uint8Array; }
+
+/** Parse a JSON file of the tree: { value } | { fault }. */
+function _json(files, path) {
+    if (!Object.prototype.hasOwnProperty.call(files, path)) { return { fault: 'the folder has no ' + path }; }
+    try { return { value: JSON.parse(_text(files[path])) }; }
+    catch (e) { return { fault: path + ' is not JSON: ' + ((e && e.message) || String(e)) }; }
+}
+
+/**
+ * recordFolderFaults(files) → string[] — [] for a COMPLETE §6 Record folder, otherwise every fault by name.
+ * §6 checks only: record.json's keys and value shapes; each row against its op (the fork shape included);
+ * ticks inside tickRange and never decreasing; no zero move; one shape per name's moves; `clips` equal to the
+ * clip files present, in order; the parts.*.json entries; `project/frqtl.json` naming an entry present under
+ * project/. A host's own files (lab.json …) are never read.
+ * @param {Object<string, string|Uint8Array>} files
+ * @returns {string[]}
+ */
+export function recordFolderFaults(files) {
+    if (!_isPlain(files)) { return ['a Record folder is a tree { path: string | Uint8Array }']; }
+    const bad = [];
+    Object.keys(files).forEach(function (p) {
+        if (typeof files[p] !== 'string' && !_isBytes(files[p])) { bad.push(p + ' is neither text nor bytes'); }
+    });
+    // record.json
+    const r = _json(files, RECORD_FILES.record);
+    if (r.fault) { bad.push(r.fault); }
+    const rec = r.value;
+    let range = null;
+    let clips = [];
+    if (rec !== undefined) {
+        if (!_isPlain(rec)) { bad.push(RECORD_FILES.record + ' is an object {' + RECORD_KEYS.join(', ') + '}'); }
+        else {
+            const keys = Object.keys(rec);
+            if (keys.length !== RECORD_KEYS.length || !RECORD_KEYS.every(function (k) { return keys.indexOf(k) !== -1; })) {
+                bad.push(RECORD_FILES.record + ' carries exactly {' + RECORD_KEYS.join(', ') + '} (no record-level who: each change names its `by`), got {' + keys.join(', ') + '}');
+            }
+            _placeholders(rec, RECORD_FILES.record, []).forEach(function (f) { bad.push(f + ' — a placeholder never sits in a §6 field'); });
+            const tr = rec.tickRange;
+            if (!Array.isArray(tr) || tr.length !== 2 || !tr.every(function (t) { return Number.isInteger(t) && t >= 0; }) || tr[1] < tr[0]) {
+                bad.push(RECORD_FILES.record + ' tickRange is [first, last] whole ticks, first ≤ last, got ' + JSON.stringify(tr));
+            } else { range = tr; }
+            if (!Array.isArray(rec.clips)) { bad.push(RECORD_FILES.record + ' clips is the list of clip files, got ' + JSON.stringify(rec.clips)); }
+            else {
+                clips = rec.clips;
+                clips.forEach(function (c, i) {
+                    const want = clipName(i + 1);
+                    if (c !== want) { bad.push(RECORD_FILES.record + ' clips[' + i + '] is ' + JSON.stringify(c) + ', not ' + want + ' (clips in the order filmed)'); }
+                    else if (!_isBytes(files[c]) || !files[c].length) { bad.push(c + ' is listed in ' + RECORD_FILES.record + ' clips but is not in the folder as bytes'); }
+                });
+            }
+            if (!Array.isArray(rec.changes)) { bad.push(RECORD_FILES.record + ' changes is the list of change rows, got ' + JSON.stringify(rec.changes)); }
+            else {
+                const shapeOf = {};
+                let last = -Infinity;
+                rec.changes.forEach(function (c, i) {
+                    const at = RECORD_FILES.record + ' changes[' + i + ']';
+                    _rowFaults(c, at).forEach(function (f) { bad.push(f); });
+                    if (!_isPlain(c)) { return; }
+                    if (Number.isInteger(c.tick)) {
+                        if (range && (c.tick < range[0] || c.tick > range[1])) { bad.push(at + ' at tick ' + c.tick + ' lies outside tickRange ' + JSON.stringify(range)); }
+                        if (c.tick < last) { bad.push(at + ' at tick ' + c.tick + ' comes after a row at tick ' + last + ' — rows are in the order acted, so ticks only climb'); }
+                        last = Math.max(last, c.tick);
+                    }
+                    if (c.op === 'move') {
+                        const p = _placement(c.from);
+                        if (p) {
+                            const s = p.key + '/' + p.length;
+                            if (shapeOf[c.name] && shapeOf[c.name] !== s) {
+                                bad.push(at + ' moves "' + c.name + '" as {' + p.key + ': ' + p.length + ' numbers} after a row that moved it as {' +
+                                    shapeOf[c.name].replace('/', ': ') + ' numbers} — one part moves in the one shape of its position authority');
+                            }
+                            shapeOf[c.name] = shapeOf[c.name] || s;
+                        }
+                    }
+                });
+            }
+        }
+    }
+    Object.keys(files).filter(function (f) { return CLIP_NAME.test(f) && clips.indexOf(f) === -1; }).sort().forEach(function (f) {
+        bad.push(f + ' is in the folder but not listed in ' + RECORD_FILES.record + ' clips');
+    });
+    // parts.before.json / parts.after.json
+    [RECORD_FILES.partsBefore, RECORD_FILES.partsAfter].forEach(function (p) {
+        const j = _json(files, p);
+        if (j.fault) { bad.push(j.fault); return; }
+        if (!_isPlain(j.value)) { bad.push(p + ' is {"<name>": ["<registered kind name>", {props}]}, got ' + JSON.stringify(j.value)); return; }
+        _placeholders(j.value, p, []).forEach(function (f) { bad.push(f + ' — a placeholder never sits in a §6 field'); });
+        Object.keys(j.value).forEach(function (n) {
+            if (!_isEntry(j.value[n])) { bad.push(p + ' "' + n + '" is not ["<registered kind name>", {props}]: ' + JSON.stringify(j.value[n])); }
+        });
+    });
+    // project/
+    const mp = RECORD_FILES.project + MANIFEST_FILE;
+    if (!Object.prototype.hasOwnProperty.call(files, mp)) { bad.push('project/ has no ' + MANIFEST_FILE + ' naming its entry (a Record snapshots a project folder)'); }
+    else {
+        let entry = null;
+        try { entry = entryOf({ [MANIFEST_FILE]: _text(files[mp]) }); }
+        catch (e) { bad.push(mp + ' is refused by the entry rule (link.js entryOf): ' + ((e && e.message) || String(e))); }
+        if (entry !== null && !Object.prototype.hasOwnProperty.call(files, RECORD_FILES.project + entry)) {
+            bad.push('project/ has no ' + entry + ' (the entry ' + MANIFEST_FILE + ' names)');
+        }
+    }
+    return bad;
+}
+
+// ── the writer ──────────────────────────────────────────────────────────────────
+
+/** A parts block → its §6 JSON value, refusing a value that is not strict JSON by name. */
+function _partsValue(block, which) {
+    if (!_isPlain(block)) { throw new TypeError('[record-format] ' + which + ' is { "<name>": ["<registered kind name>", {props}] }. (FAIL-LOUD.)'); }
+    const out = {};
+    Object.keys(block).forEach(function (n) {
+        const e = block[n];
+        if (!Array.isArray(e) || e.length !== 2 || typeof e[0] !== 'string' || !e[0] || !_isPlain(e[1])) {
+            throw new TypeError('[record-format] ' + which + ' "' + n + '" is not ["<registered kind name>", {props}]. (FAIL-LOUD.)');
+        }
+        const f = _strictJsonFault(e[1], n);
+        if (f) {
+            throw new TypeError('[record-format] ' + which + ': ' + f + ' — a Record writes props as strict JSON; declare that value ' +
+                'as a literal in `parts`. (FAIL-LOUD.)');
+        }
+        out[n] = [e[0], JSON.parse(JSON.stringify(e[1]))];
+    });
+    return out;
+}
+
+export const FILM_AFTER_LAST_CHANGE = 'film after your last change: the footage must show every change';
+
+/**
+ * serializeRecordFolder({ changes, clips, partsBefore, partsAfter, project }) — THE writer of a Record folder.
+ *   changes      the rows, in the order acted
+ *   clips        [{ bytes: Uint8Array, firstTick, lastTick }], in the order filmed (Record ticks)
+ *   partsBefore / partsAfter   { name: [registered kind name, props] }
+ *   project      { path: text } — the held files at stop
+ * → { empty: true } when there is no change and no clip (a state, with no folder);
+ * → { files, record, clips: [{ file, firstTick, lastTick }] } otherwise.
+ * REFUSES (throws): a change and no clip, or a change after the last clip ends (FILM_AFTER_LAST_CHANGE); a
+ * props value that is not strict JSON (naming its key); and any recordFolderFaults of its own output.
+ */
+export function serializeRecordFolder(p) {
+    const changes = p.changes, clips = p.clips;
+    if (!changes.length && !clips.length) { return { empty: true }; }
+    if (!clips.length) {
+        throw new Error('[record-format] this Record has ' + changes.length + ' change(s) and no clip — ' + FILM_AFTER_LAST_CHANGE + '. (FAIL-LOUD.)');
+    }
+    const end = clips[clips.length - 1].lastTick;
+    const late = changes.filter(function (c) { return c.tick > end; });
+    if (late.length) {
+        throw new Error('[record-format] ' + late.length + ' change(s) after the last clip ends (Record tick ' + end + '): ' +
+            late.map(function (c) { return c.op + ' ' + c.name + ' at tick ' + c.tick; }).join('; ') + ' — ' + FILM_AFTER_LAST_CHANGE + '. (FAIL-LOUD.)');
+    }
+    const first = changes.reduce(function (m, c) { return Math.min(m, c.tick); }, clips[0].firstTick);
+    const record = {
+        tickRange: [first, end],
+        clips: clips.map(function (c, i) { return clipName(i + 1); }),
+        changes: changes.map(function (c) { const o = {}; CHANGE_KEYS.forEach(function (k) { o[k] = c[k]; }); return o; })
+    };
+    // Check the rows as HELD, before any text: JSON.stringify writes NaN/Infinity as null and drops an undefined key,
+    // so a check of the written text would read a different value from the one the Record held.
+    const held = [];
+    record.changes.forEach(function (c, i) { held.push.apply(held, _rowFaults(c, 'changes[' + i + ']')); });
+    if (held.length) { throw new Error('[record-format] a change row is not strict JSON: ' + held.join('; ') + ' (FAIL-LOUD.)'); }
+    const files = {};
+    files[RECORD_FILES.record] = jsonText(record);
+    clips.forEach(function (c, i) { files[clipName(i + 1)] = c.bytes; });
+    files[RECORD_FILES.partsBefore] = jsonText(_partsValue(p.partsBefore, RECORD_FILES.partsBefore));
+    files[RECORD_FILES.partsAfter] = jsonText(_partsValue(p.partsAfter, RECORD_FILES.partsAfter));
+    Object.keys(p.project).sort().forEach(function (f) { files[RECORD_FILES.project + f] = p.project[f]; });
+    const faults = recordFolderFaults(files);
+    if (faults.length) {
+        throw new Error('[record-format] the Record folder this producer wrote is not a complete §6 Record:\n- ' + faults.join('\n- ') + '\n(FAIL-LOUD.)');
+    }
+    return { files: files, record: record, clips: clips.map(function (c, i) { return { file: clipName(i + 1), firstTick: c.firstTick, lastTick: c.lastTick }; }) };
+}

package/dist/shim/project/specifiers.js

@@ -7,14 +7,16 @@
  *                               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.
+ *                               the URL of the lib-identity root AS SEEN FROM THE PAGE: an absolute
+ *                               URL or one starting with '/', './' or '../' (any other root THROWS —
+ *                               an import map ignores such a value as a bare specifier); prefix rows
+ *                               stay prefixes. No filesystem computation, so a vendored dist root
+ *                               takes the same call.
+ *   FRQTL_WEB_HOST_SPECIFIERS   rows { specifier, libPath, why } a HOST PAGE imports and a sketch never does:
+ *                               ./boot (FRQTL_WEB_BOOT, the scene doors), ./registry and ./project. libPathOf
+ *                               refuses every one of them, so a sketch cannot boot a page.
+ *   pageImportMapFor(libRootUrl) → importMapFor(libRootUrl) plus every FRQTL_WEB_HOST_SPECIFIERS 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
@@ -47,7 +49,17 @@ export const FRQTL_WEB_SPECIFIERS = Object.freeze([
 ]);
 
 /** 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' });
+export const FRQTL_WEB_BOOT = Object.freeze({ specifier: '@descix/frqtl-web/boot', libPath: 'frqtl/experiments/_shared/doors.js',
+    why: 'the scene doors (bootScene, bootProject)' });
+
+/** What a host page imports beside its sketches. Every row is a public exports entry of @descix/frqtl-web. */
+export const FRQTL_WEB_HOST_SPECIFIERS = Object.freeze([
+    FRQTL_WEB_BOOT,
+    Object.freeze({ specifier: '@descix/frqtl-web/registry', libPath: 'shim/registry/index.js',
+        why: 'the walk-through rungs, the showcase roster, the experiment registry, projectOf' }),
+    Object.freeze({ specifier: '@descix/frqtl-web/project', libPath: 'shim/project/index.js',
+        why: 'the specifier table, the link site, sketchProject and the project identity' })
+]);
 
 /** The package a self-reference names. */
 export const FRQTL_WEB_PACKAGE = '@descix/frqtl-web';
@@ -80,9 +92,15 @@ export function libPathOf(specifier) {
         '. (FAIL-LOUD.)');
 }
 
+/** 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; }
+    try { new URL(url); return true; } catch (e) { return false; }
+}
+
 /**
- * @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/')
+ * @param {string} libRootUrl — the lib-identity root as seen from the page, ending in `/`: an absolute
+ *   URL or one starting with '/', './' or '../' (e.g. '../../', '/pub/abc123/', './vendor/frqtl-web/0.6.0/dist/')
  * @returns {{imports: Object<string, string>}}
  */
 export function importMapFor(libRootUrl) {
@@ -90,6 +108,12 @@ export function importMapFor(libRootUrl) {
         throw new TypeError('[specifiers] importMapFor(libRootUrl): the lib-identity root URL as seen from the page, ' +
             'ending in "/" (got ' + JSON.stringify(libRootUrl) + '). (FAIL-LOUD.)');
     }
+    if (!_isMapAddress(libRootUrl)) {
+        throw new TypeError('[specifiers] importMapFor(libRootUrl): ' + JSON.stringify(libRootUrl) + ' is neither an ' +
+            'absolute URL nor a path starting with "/", "./" or "../", so a browser reads every row built on it as a ' +
+            'bare specifier and ignores it. Write it as ' + JSON.stringify('./' + libRootUrl) + ' (relative to the page) ' +
+            'or ' + JSON.stringify('/' + libRootUrl) + ' (from the origin root). (FAIL-LOUD.)');
+    }
     const imports = {};
     for (const row of FRQTL_WEB_SPECIFIERS) { imports[row.specifier] = libRootUrl + row.libPath; }
     return { imports: imports };
@@ -97,10 +121,14 @@ export function importMapFor(libRootUrl) {
 
 /**
  * @param {string} libRootUrl — as importMapFor's
- * @returns {{imports: Object<string, string>}} importMapFor(libRootUrl) plus the FRQTL_WEB_BOOT row
+ * @returns {{imports: Object<string, string>}} importMapFor(libRootUrl) plus every FRQTL_WEB_HOST_SPECIFIERS row
+ *
+ * The map carries no dist-manifest.json row: the manifest is a fact of a PACKAGE dist, and this map is also
+ * rendered for lib roots that are not one (the static site's graph has none). A host reads it from the root
+ * it already holds: `new URL('dist-manifest.json', root)`.
  */
 export function pageImportMapFor(libRootUrl) {
     const map = importMapFor(libRootUrl);
-    map.imports[FRQTL_WEB_BOOT.specifier] = libRootUrl + FRQTL_WEB_BOOT.libPath;
+    for (const row of FRQTL_WEB_HOST_SPECIFIERS) { map.imports[row.specifier] = libRootUrl + row.libPath; }
     return map;
 }

package/dist/shim/registry/index.js

@@ -10,7 +10,7 @@
  *   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-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';

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

@@ -1,38 +1,46 @@
 /* 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 a CAPABILITY split on the resolved URL, never a host sniff: a `file:` URL is read through
+ * node's fs (`process.getBuiltinModule`), anything else is fetched.
  *
- * FAIL-LOUD: an unknown id, a row without a scenes/ path, a non-200 response, an unreadable
- * file or an empty body REJECTS naming the scene and the URL. A blank scene is never a result.
+ * 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';
 
 /** The one path prefix a scene file lives under (the router's `scenes/` profile key). */
 export var SCENES_PREFIX = 'scenes/';
@@ -47,11 +55,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 +85,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;
@@ -119,24 +127,26 @@ function _fetchText(url, id, fetchImpl) {
 }
 
 /**
- * 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 ' +
@@ -151,7 +161,11 @@ export function loadSceneSource(scene, opts) {
                 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)
@@ -46,17 +47,17 @@
  * is the config-mirror anti-pattern this contract exists to kill. Every mode delta
  * must be expressible as DECLARED descriptor fields (emitter `is2D`, Wall/Tunnel
  * `z`/`depth`, ordinary Walls for the z-collimators, camera on the renderState) so
- * a built scene codegens to concrete, mode-PINNED state and survives Restart.
+ * a built scene's declared parts hold concrete, mode-PINNED state and survive Restart.
  *
- * ── The recipe form (addObject, codegen-round-trippable) ──────────────────────
+ * ── The recipe form (a parts block, written back by the parts writer) ─────────
  * Rungs are OBJECT recipes: each body states the WORLD first, in its co-init call
- * (`exp.createCanvas(W, H, setupSphereEmitter3D.worldCfg(SRC))`) and then calls
- * `exp.addObject('SphereEmitter', SRC)` with the SAME bag — a PART never inits the
- * world, the sketch does, once, before any part. Because the emitter is now a real
- * authored object (a NONE-collision visual marker + the host emit tick-fn), a loaded
- * rung is DRAGGABLE / INSPECTABLE and CODEGEN-ROUND-TRIPPABLE: a STUDIO grab/drag →
- * Save re-emits the SAME addObject recipe (SphereEmitter imports setupSphereEmitter3D, so no
- * per-rung script injection is needed).
+ * (`exp.createCanvas(…)` / `exp.createScene(…)`), then declares its parts —
+ * `const p = exp.declare(parts)` over the module's `export const parts = { name: [Kind, props] }`
+ * block — a PART never inits the world, the sketch does, once, before any part. Every
+ * declared part is a real authored object, so a loaded rung is DRAGGABLE / INSPECTABLE,
+ * and a STUDIO hand (grab/drag, Inspector, knob, visibility) is written into the SAME
+ * sketch text by the parts writer, `await exp.toSketch()`: it patches the touched
+ * entries of the parts block in place and leaves every other line of the file as authored.
  *
  * ── Layer 2: physics behavior ────────────────────────────────────────────────
  * Zero new physics (canonical-bench SU1) — every rung composes already-goldened