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

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

@@ -0,0 +1,453 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * parts-writer.js — THE text patcher of a sketch's `export const parts = {…}` literal.
+ *
+ *   patchParts(text, edits[, { entry }]) → { text, changes, refused }
+ *
+ * The sketch is parsed once (acorn, vendored: lib/frqtl/assets/vendor/acorn.mjs) into a syntax tree with
+ * source ranges. Only the ranges an edit touches are replaced; every other byte of the file — untouched
+ * entries, untouched properties, expressions, spreads, comments, the author's code — is the input's byte.
+ *
+ *   edits[i] = { op: 'set',    name, props }          within entry `name`'s props object, replace ONLY the
+ *                                                     value text of each named property; a property the
+ *                                                     literal lacks is appended last in that entry
+ *            | { op: 'add',    name, Kind, module, props }   a new entry as the LAST key, plus at most one
+ *                                                     import line for Kind (after the last import statement;
+ *                                                     `module` from parts-module.js moduleOfKind)
+ *            | { op: 'remove', name }                 the entry's property node, its comma included
+ *
+ *   changes[i] = { op, name, key?, from?, to, literalized? }   from/to are source TEXT; `literalized: true`
+ *                when the old value was an expression (its text is `from`), now its literal value
+ *   refused[i] = { op, name, key?, reason }           every edit not applied, with why. Never silent.
+ *
+ * REFUSED (named, into `refused`): a sketch with no `export const parts = { … }` object literal (every edit);
+ * a touched entry whose value is not `[Identifier, { … }]`; a touched name the literal does not hold as a
+ * plain key while it carries a spread or a computed key (the name may come from either); an added Kind whose
+ * identifier is already bound in the file to something else; an added Kind with `module === null`; a value
+ * the serializer cannot write (a function, NaN/Infinity, undefined, a class instance), naming its key.
+ *
+ *   entryKeys(text, name) → string[]    the plain prop keys entry `name` spells (how an entry spells a value)
+ *   entryLiteral(text, name, key) → { literal, value? }   what a key declares when it is a literal (read-back)
+ *
+ *   serializeValue(value, key) → text   THE one value serializer: numbers, strings (single-quoted),
+ *                                       booleans, null, arrays inline, plain objects. Anything else THROWS
+ *                                       naming the key.
+ */
+
+import { parse } from '../../frqtl/assets/vendor/acorn.mjs';
+import { importSpecifierOf } from './parts-module.js';
+
+/** The export the writer patches. */
+export const PARTS_EXPORT = 'parts';
+
+const _IDENT = /^[A-Za-z_$][\w$]*$/;
+const _RESERVED = new Set(('break case catch class const continue debugger default delete do else export extends ' +
+    'false finally for function if import in instanceof new null return super switch this throw true try typeof ' +
+    'var void while with yield let static enum await implements package protected interface private public').split(' '));
+
+function _keyText(k) {
+    return (_IDENT.test(k) && !_RESERVED.has(k)) ? k : _quote(k);
+}
+
+function _quote(s) {
+    return '\'' + s.replace(/\\/g, '\\\\').replace(/'/g, '\\\'').replace(/\n/g, '\\n').replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029') + '\'';
+}
+
+/**
+ * @param {*} v
+ * @param {string} key — named in a refusal
+ * @returns {string}
+ */
+export function serializeValue(v, key) {
+    if (v === null) { return 'null'; }
+    const t = typeof v;
+    if (t === 'number') {
+        if (!Number.isFinite(v)) { throw new Error('"' + key + '" is ' + String(v) + ' — the writer writes finite numbers only.'); }
+        return Object.is(v, -0) ? '0' : String(v);
+    }
+    if (t === 'string') { return _quote(v); }
+    if (t === 'boolean') { return v ? 'true' : 'false'; }
+    if (Array.isArray(v)) {
+        return '[' + v.map(function (x, i) { return serializeValue(x, key + '[' + i + ']'); }).join(', ') + ']';
+    }
+    if (t === 'object') {
+        const proto = Object.getPrototypeOf(v);
+        if (proto !== Object.prototype && proto !== null) {
+            throw new Error('"' + key + '" is a ' + ((v.constructor && v.constructor.name) || 'class') +
+                ' instance — the writer writes numbers, strings, booleans, null, arrays and plain objects.');
+        }
+        const ks = Object.keys(v);
+        if (!ks.length) { return '{}'; }
+        return '{ ' + ks.map(function (k) { return _keyText(k) + ': ' + serializeValue(v[k], key + '.' + k); }).join(', ') + ' }';
+    }
+    throw new Error('"' + key + '" is ' + (t === 'undefined' ? 'undefined' : 'a ' + t) +
+        ' — the writer writes numbers, strings, booleans, null, arrays and plain objects.');
+}
+
+/** A node whose text IS its value: a literal (not a regex), a negated number, or arrays/objects of those. */
+function _isLiteral(n) {
+    if (!n) { return false; }
+    if (n.type === 'Literal') { return !n.regex && typeof n.value !== 'bigint'; }
+    if (n.type === 'UnaryExpression' && n.operator === '-') { return n.argument.type === 'Literal' && typeof n.argument.value === 'number'; }
+    if (n.type === 'ArrayExpression') { return n.elements.every(function (e) { return e && _isLiteral(e); }); }
+    if (n.type === 'ObjectExpression') {
+        return n.properties.every(function (p) {
+            return p.type === 'Property' && !p.computed && p.kind === 'init' && !p.method && !p.shorthand && _isLiteral(p.value);
+        });
+    }
+    return false;
+}
+
+/** The plain (non-computed) key of a Property node, else null. */
+function _plainKey(p) {
+    if (p.type !== 'Property' || p.computed) { return null; }
+    if (p.key.type === 'Identifier') { return p.key.name; }
+    if (p.key.type === 'Literal' && (typeof p.key.value === 'string' || typeof p.key.value === 'number')) { return String(p.key.value); }
+    return null;
+}
+
+/** The `parts` ObjectExpression: `export const parts = { … }`, else null. */
+function _partsLiteral(ast) {
+    for (const s of ast.body) {
+        if (s.type !== 'ExportNamedDeclaration' || !s.declaration || s.declaration.type !== 'VariableDeclaration') { continue; }
+        for (const d of s.declaration.declarations) {
+            if (d.id.type === 'Identifier' && d.id.name === PARTS_EXPORT) {
+                return (d.init && d.init.type === 'ObjectExpression') ? d.init : null;
+            }
+        }
+    }
+    return null;
+}
+
+/** Module-top bindings: name → { kind: 'import', source, imported } | { kind: 'decl' }. */
+function _topBindings(ast) {
+    const out = new Map();
+    for (const s of ast.body) {
+        if (s.type === 'ImportDeclaration') {
+            for (const sp of s.specifiers) {
+                out.set(sp.local.name, { kind: 'import', source: s.source.value,
+                    imported: sp.type === 'ImportSpecifier' ? (sp.imported.name || sp.imported.value) : null });
+            }
+            continue;
+        }
+        const decl = (s.type === 'ExportNamedDeclaration' || s.type === 'ExportDefaultDeclaration') ? s.declaration : s;
+        if (!decl) { continue; }
+        if (decl.type === 'VariableDeclaration') {
+            for (const d of decl.declarations) { _patternNames(d.id).forEach(function (n) { out.set(n, { kind: 'decl' }); }); }
+        } else if ((decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') && decl.id) {
+            out.set(decl.id.name, { kind: 'decl' });
+        }
+    }
+    return out;
+}
+
+function _patternNames(p) {
+    if (!p) { return []; }
+    if (p.type === 'Identifier') { return [p.name]; }
+    if (p.type === 'ObjectPattern') { return p.properties.flatMap(function (q) { return _patternNames(q.type === 'RestElement' ? q.argument : q.value); }); }
+    if (p.type === 'ArrayPattern') { return p.elements.flatMap(_patternNames); }
+    if (p.type === 'RestElement') { return _patternNames(p.argument); }
+    if (p.type === 'AssignmentPattern') { return _patternNames(p.left); }
+    return [];
+}
+
+/** The whitespace that starts the line holding offset `at`. */
+function _indentAt(text, at) {
+    const ls = text.lastIndexOf('\n', at - 1) + 1;
+    const m = /^[ \t]*/.exec(text.slice(ls));
+    return m[0];
+}
+
+/** Is `obj` (an ObjectExpression) written across lines? */
+function _multiline(text, obj) {
+    return text.slice(obj.start, obj.end).indexOf('\n') !== -1;
+}
+
+/**
+ * The insertion that appends `prop` (a `key: value` text) as the LAST property of ObjectExpression `obj`.
+ * Matches the literal's own layout: one line → `, k: v` / `{ k: v }`; multi-line → a new line at the last
+ * property's indent, keeping a trailing comma the literal already writes.
+ */
+function _appendProperty(text, obj, prop) {
+    const close = obj.end - 1;   // the '}'
+    const last = obj.properties[obj.properties.length - 1];
+    if (!last) {
+        const inner = text.slice(obj.start + 1, close);
+        if (inner.indexOf('\n') !== -1) {
+            const ind = _indentAt(text, close);
+            return { start: obj.start + 1, end: close, text: '\n' + ind + '  ' + prop + ',\n' + ind };
+        }
+        return { start: obj.start + 1, end: close, text: ' ' + prop + ' ' };
+    }
+    const between = text.slice(last.end, close);
+    const comma = between.indexOf(',');
+    if (_multiline(text, obj)) {
+        const ind = _indentAt(text, last.start);
+        if (comma !== -1) { return { start: last.end + comma + 1, end: last.end + comma + 1, text: '\n' + ind + prop + ',' }; }
+        return { start: last.end, end: last.end, text: ',\n' + ind + prop };
+    }
+    if (comma !== -1) { return { start: last.end + comma + 1, end: last.end + comma + 1, text: ' ' + prop + ',' }; }
+    return { start: last.end, end: last.end, text: ', ' + prop };
+}
+
+/** The removal of Property `p` from ObjectExpression `obj`, its comma (and, when it owns whole lines, those lines) included. */
+function _removeProperty(text, obj, p) {
+    const i = obj.properties.indexOf(p);
+    const next = obj.properties[i + 1];
+    const stop = next ? next.start : obj.end - 1;
+    const after = text.slice(p.end, stop);
+    const comma = after.indexOf(',');
+    let start = p.start;
+    let end = comma !== -1 ? p.end + comma + 1 : p.end;
+    if (comma === -1 && i > 0) {
+        // the last property with no trailing comma: the comma before it goes
+        const prev = obj.properties[i - 1];
+        const pc = text.slice(prev.end, p.start).indexOf(',');
+        if (pc !== -1) { start = prev.end + pc; }
+    }
+    // An entry that owns its lines (only whitespace before it on its first line, only whitespace after its
+    // comma on its last) leaves no blank line behind.
+    const ls = text.lastIndexOf('\n', start - 1) + 1;
+    const le = text.indexOf('\n', end);
+    if (/^[ \t]*$/.test(text.slice(ls, start)) && le !== -1 && /^[ \t]*$/.test(text.slice(end, le))) {
+        start = ls; end = le + 1;
+    }
+    return { start: start, end: end, text: '' };
+}
+
+/**
+ * @param {string} text — the sketch file's text
+ * @param {object[]} edits — see the file header
+ * @param {{entry?: string}} [opts] — the sketch's project path (default 'sketch.js'), for a fork's relative import
+ * @returns {{text: string, changes: object[], refused: object[]}}
+ */
+export function patchParts(text, edits, opts) {
+    const entry = (opts && opts.entry) || 'sketch.js';
+    if (typeof text !== 'string') {
+        throw new TypeError('[parts-writer] patchParts(text, edits): text is the sketch file (got ' + typeof text + '). (FAIL-LOUD.)');
+    }
+    if (!Array.isArray(edits)) {
+        throw new TypeError('[parts-writer] patchParts(text, edits): edits is an array of { op: set | add | remove }. (FAIL-LOUD.)');
+    }
+    const changes = [];
+    const refused = [];
+    if (!edits.length) { return { text: text, changes: changes, refused: refused }; }
+    function refuse(e, reason, key) {
+        const r = { op: e.op, name: e.name, reason: reason };
+        if (key !== undefined) { r.key = key; }
+        refused.push(r);
+    }
+    let ast;
+    try { ast = parse(text, { ecmaVersion: 'latest', sourceType: 'module' }); }
+    catch (err) {
+        edits.forEach(function (e) { refuse(e, 'the sketch does not parse (' + err.message + ') — fix it, then Run.'); });
+        return { text: text, changes: changes, refused: refused };
+    }
+    const parts = _partsLiteral(ast);
+    if (!parts) {
+        edits.forEach(function (e) {
+            refuse(e, 'this sketch has no `export const ' + PARTS_EXPORT + ' = { … }` object literal — the writer writes ' +
+                'only into that literal; declare the parts there (exp.declare(' + PARTS_EXPORT + ')) to make them editable.');
+        });
+        return { text: text, changes: changes, refused: refused };
+    }
+    const byName = new Map();
+    let opaque = false;   // a spread or a computed key: a name may come from it
+    for (const p of parts.properties) {
+        const k = _plainKey(p);
+        if (k === null) { opaque = true; continue; }
+        byName.set(k, p);   // a duplicated key: the last one wins, as in the language
+    }
+    const bindings = _topBindings(ast);
+    const patches = [];
+    const importLines = [];   // { Kind, line }
+    const entryOf = function (e) {
+        const p = byName.get(e.name);
+        if (!p) {
+            refuse(e, opaque
+                ? 'no plain key "' + e.name + '" in the parts literal, which carries a spread or a computed key — a name that ' +
+                  'comes from either is not writable here; write the entry as a plain key.'
+                : 'the parts literal has no entry "' + e.name + '".');
+            return null;
+        }
+        return p;
+    };
+    const adds = [];
+    for (const e of edits) {
+        if (!e || typeof e !== 'object' || typeof e.name !== 'string' || !e.name) {
+            throw new TypeError('[parts-writer] an edit is { op, name, … } with a non-empty name (got ' + JSON.stringify(e) + '). (FAIL-LOUD.)');
+        }
+        if (e.op === 'set') {
+            const p = entryOf(e);
+            if (!p) { continue; }
+            const v = p.value;
+            if (v.type !== 'ArrayExpression' || v.elements.length !== 2 || !v.elements[0] || v.elements[0].type !== 'Identifier' ||
+                !v.elements[1] || v.elements[1].type !== 'ObjectExpression') {
+                refuse(e, 'the entry "' + e.name + '" is not written as [Kind, { …props }] — the writer patches only that form.');
+                continue;
+            }
+            const obj = v.elements[1];
+            const own = new Map();
+            for (const q of obj.properties) { const k = _plainKey(q); if (k !== null) { own.set(k, q); } }
+            const appended = [];
+            for (const key of Object.keys(e.props || {})) {
+                let lit;
+                try { lit = serializeValue(e.props[key], key); }
+                catch (err) { refuse(e, err.message, key); continue; }
+                const q = own.get(key);
+                if (q && !q.shorthand) {
+                    const old = text.slice(q.value.start, q.value.end);
+                    if (old === lit) { continue; }
+                    patches.push({ start: q.value.start, end: q.value.end, text: lit });
+                    const c = { op: 'set', name: e.name, key: key, from: old, to: lit };
+                    if (!_isLiteral(q.value)) { c.literalized = true; }
+                    changes.push(c);
+                } else if (q && q.shorthand) {
+                    patches.push({ start: q.start, end: q.end, text: _keyText(key) + ': ' + lit });
+                    changes.push({ op: 'set', name: e.name, key: key, from: key, to: lit, literalized: true });
+                } else {
+                    appended.push(_keyText(key) + ': ' + lit);
+                    changes.push({ op: 'set', name: e.name, key: key, from: null, to: lit });
+                }
+            }
+            if (appended.length) {
+                const ins = _appendProperty(text, obj, appended.join(_multiline(text, obj) ? ',\n' + _indentAt(text, (obj.properties[obj.properties.length - 1] || obj).start) : ', '));
+                patches.push(ins);
+            }
+        } else if (e.op === 'remove') {
+            const p = entryOf(e);
+            if (!p) { continue; }
+            patches.push(_removeProperty(text, parts, p));
+            changes.push({ op: 'remove', name: e.name, from: text.slice(p.start, p.end), to: null });
+        } else if (e.op === 'add') {
+            if (byName.has(e.name) || adds.some(function (a) { return a.name === e.name; })) {
+                refuse(e, 'the parts literal already has an entry "' + e.name + '" — a declared name is one key.');
+                continue;
+            }
+            if (typeof e.Kind !== 'string' || !_IDENT.test(e.Kind)) {
+                throw new TypeError('[parts-writer] add: Kind is the kind\'s class name (got ' + JSON.stringify(e.Kind) + '). (FAIL-LOUD.)');
+            }
+            if (e.module === null || e.module === undefined) {
+                refuse(e, 'the kind ' + e.Kind + ' has no importable module (an internal kind, not a part of ' +
+                    '@descix/frqtl-web/parts nor a project file), so a sketch cannot import it — declare it in code.');
+                continue;
+            }
+            const spec = importSpecifierOf(e.module, entry);
+            const b = bindings.get(e.Kind);
+            if (b && !(b.kind === 'import' && b.source === spec && b.imported === e.Kind)) {
+                refuse(e, 'the identifier ' + e.Kind + ' is already bound in this sketch to ' +
+                    (b.kind === 'import' ? '"' + (b.imported || '*') + '" from \'' + b.source + '\'' : 'its own declaration') +
+                    ' — the writer cannot import the kind ' + e.Kind + ' under that name.');
+                continue;
+            }
+            let lit;
+            try { lit = serializeValue(e.props || {}, e.name); }
+            catch (err) { refuse(e, err.message); continue; }
+            if (!b && !importLines.some(function (l) { return l.Kind === e.Kind; })) {
+                importLines.push({ Kind: e.Kind, line: 'import { ' + e.Kind + ' } from ' + _quote(spec) + ';' });
+            }
+            adds.push({ name: e.name, text: _keyText(e.name) + ': [' + e.Kind + ', ' + lit + ']' });
+            changes.push({ op: 'add', name: e.name, from: null, to: _keyText(e.name) + ': [' + e.Kind + ', ' + lit + ']',
+                import: (!b ? 'import { ' + e.Kind + ' } from ' + _quote(spec) + ';' : null) });
+        } else {
+            throw new TypeError('[parts-writer] unknown edit op ' + JSON.stringify(e.op) + ' — set | add | remove. (FAIL-LOUD.)');
+        }
+    }
+    if (adds.length) {
+        const joined = adds.map(function (a) { return a.text; });
+        if (_multiline(text, parts) || parts.properties.length === 0) {
+            if (parts.properties.length === 0) {
+                const ind = _indentAt(text, parts.start);
+                patches.push({ start: parts.start + 1, end: parts.end - 1,
+                    text: '\n' + joined.map(function (t) { return ind + '  ' + t + ','; }).join('\n') + '\n' + ind });
+            } else {
+                const ind = _indentAt(text, parts.properties[parts.properties.length - 1].start);
+                const last = parts.properties[parts.properties.length - 1];
+                const comma = text.slice(last.end, parts.end - 1).indexOf(',');
+                if (comma !== -1) {
+                    patches.push({ start: last.end + comma + 1, end: last.end + comma + 1,
+                        text: joined.map(function (t) { return '\n' + ind + t + ','; }).join('') });
+                } else {
+                    patches.push({ start: last.end, end: last.end, text: joined.map(function (t) { return ',\n' + ind + t; }).join('') });
+                }
+            }
+        } else {
+            patches.push(_appendProperty(text, parts, joined.join(', ')));
+        }
+    }
+    if (importLines.length) {
+        const imports = ast.body.filter(function (s) { return s.type === 'ImportDeclaration'; });
+        let at;
+        if (imports.length) {
+            const lastImp = imports[imports.length - 1];
+            const nl = text.indexOf('\n', lastImp.end);
+            at = nl === -1 ? text.length : nl + 1;
+            const block = importLines.map(function (l) { return l.line + '\n'; }).join('');
+            patches.push({ start: at, end: at, text: nl === -1 ? '\n' + block : block });
+        } else {
+            const first = ast.body[0];
+            at = first ? text.lastIndexOf('\n', first.start - 1) + 1 : text.length;
+            patches.push({ start: at, end: at, text: importLines.map(function (l) { return l.line + '\n'; }).join('') + '\n' });
+        }
+    }
+    patches.sort(function (a, b) { return b.start - a.start || b.end - a.end; });
+    for (let i = 1; i < patches.length; i++) {
+        if (patches[i].end > patches[i - 1].start) {
+            throw new Error('[parts-writer] two edits touch overlapping text — one edit per property. (FAIL-LOUD.)');
+        }
+    }
+    let out = text;
+    for (const p of patches) { out = out.slice(0, p.start) + p.text + out.slice(p.end); }
+    return { text: out, changes: changes, refused: refused };
+}
+
+/** The props ObjectExpression of entry `name` in the parsed `parts` literal; THROWS naming what is missing. */
+function _entryProps(text, name, who) {
+    const ast = parse(text, { ecmaVersion: 'latest', sourceType: 'module' });
+    const parts = _partsLiteral(ast);
+    if (!parts) {
+        throw new Error('[parts-writer] ' + who + ': the sketch has no `export const ' + PARTS_EXPORT + ' = { … }` object literal. (FAIL-LOUD.)');
+    }
+    let p = null;
+    for (const q of parts.properties) { if (_plainKey(q) === name) { p = q; } }
+    const v = p && p.value;
+    if (!v || v.type !== 'ArrayExpression' || v.elements.length !== 2 || !v.elements[1] || v.elements[1].type !== 'ObjectExpression') {
+        throw new Error('[parts-writer] ' + who + ': the parts literal has no entry "' + name + '" written as [Kind, { …props }]. (FAIL-LOUD.)');
+    }
+    return v.elements[1];
+}
+
+function _literalValue(n) {
+    if (n.type === 'Literal') { return n.value; }
+    if (n.type === 'UnaryExpression') { return -n.argument.value; }
+    if (n.type === 'ArrayExpression') { return n.elements.map(_literalValue); }
+    const o = {};
+    for (const p of n.properties) { o[_plainKey(p)] = _literalValue(p.value); }
+    return o;
+}
+
+/**
+ * entryKeys(text, name) → string[] — the plain prop keys entry `name` spells in the parsed `parts` literal, in
+ * source order (a spread or a computed key is not a plain key). The writer asks it how an entry spells a value
+ * (e.g. `rect` alone, or `rect` beside `z` / `depth`), never a regex over the text. THROWS on no such entry.
+ */
+export function entryKeys(text, name) {
+    const out = [];
+    for (const q of _entryProps(text, name, 'entryKeys').properties) { const k = _plainKey(q); if (k !== null) { out.push(k); } }
+    return out;
+}
+
+/**
+ * entryLiteral(text, name, key) → { literal: true, value } | { literal: false } — what entry `name`'s `key`
+ * declares when its value is a literal (the read-back after a write: the text a patch produced, parsed again).
+ * THROWS on no such entry or no such key.
+ */
+export function entryLiteral(text, name, key) {
+    for (const q of _entryProps(text, name, 'entryLiteral').properties) {
+        if (_plainKey(q) !== key) { continue; }
+        return _isLiteral(q.value) ? { literal: true, value: _literalValue(q.value) } : { literal: false };
+    }
+    throw new Error('[parts-writer] entryLiteral: the entry "' + name + '" spells no key "' + key + '". (FAIL-LOUD.)');
+}

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, loadSceneSource' }),
+    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/walkthrough.js

@@ -46,17 +46,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

package/dist/shim/render-state/apply.js

@@ -31,13 +31,14 @@
  *                  `runner.updateObjectProperty(lo, 'visible', v)`, backdrop:v. An ABSENT
  *                  `backdropVisible` (null after normalizing) is not written — the scene's own
  *                  `addBackdrop(…, {visible})` rules — and reports backdrop:null, as does no backdrop LO.
- *       `pageControls` are NOT applied here: they are STUDIO's host-specific override.
+ *       Page controls are not state: a sketch declares them in its own code.
  *
  *   backdropOf(runner)                   — THE answer to "which LO is the backdrop" for a host: the
  *                                          census LO marked `backdrop === true`, or null. STUDIO's
  *                                          save captures its visibility through it, so capture and
  *                                          replay read one fact.
- *   normalizeSavedRenderState(raw)       — tolerant normalizer for a LOADED bag (never throws).
+ *   normalizeSavedRenderState(raw)       — tolerant normalizer for a LOADED bag; THROWS only on a bag
+ *                                          that carries page controls (they are author code now).
  *   pickCameraReplay(saved)              — pure decision: named preset over raw orbit.
  *   partitionRenderRows(rows, declared, known) — apply / retain / throw, before anything is written.
  *   renderRowsFromBag(bag)               — a { key: value } render-option bag as ordered rows.
@@ -83,12 +84,18 @@ function pickCameraReplay(saved) {
  *   seed: string|null,
  *   backdropVisible: boolean|null,
  *   camera: {orbit:object|null, preset:string|null}|null,
- *   render: {key:string, value:*}[],
- *   pageControls: {id:string, value:*, bind:{object:string,prop:string}|null}[]
+ *   render: {key:string, value:*}[]
  * }}
+ * @throws {Error} a bag whose `pageControls` holds a row — page controls are declared in the sketch's own
+ *   code, so a saved bag never carries them; migrate the project (move the controls into its sketch).
  */
 function normalizeSavedRenderState(raw) {
     var r = _isPlainObject(raw) ? raw : {};
+    if (Array.isArray(r.pageControls) && r.pageControls.length > 0) {
+        throw new Error('[render-state] this saved project carries page controls (renderState.pageControls: ' +
+            r.pageControls.map(function (row) { return _isPlainObject(row) ? String(row.id) : '?'; }).join(', ') +
+            ') — page controls are declared in the sketch\'s own code; move them into the sketch and save again. (FAIL-LOUD.)');
+    }
     var camera = null;
     if (_isPlainObject(r.camera)) {
         camera = {
@@ -105,16 +112,6 @@ function normalizeSavedRenderState(raw) {
         camera: camera,
         render: Array.isArray(r.render) ? r.render.filter(function (row) {
             return _isPlainObject(row) && typeof row.key === 'string' && row.key.length > 0;
-        }) : [],
-        pageControls: Array.isArray(r.pageControls) ? r.pageControls.filter(function (row) {
-            return _isPlainObject(row) && typeof row.id === 'string' && row.id.length > 0;
-        }).map(function (row) {
-            return {
-                id: row.id,
-                value: row.value,
-                bind: (_isPlainObject(row.bind) && typeof row.bind.object === 'string' &&
-                       typeof row.bind.prop === 'string') ? { object: row.bind.object, prop: row.bind.prop } : null
-            };
         }) : []
     };
 }

package/llms.txt

@@ -1,12 +1,12 @@
 # @descix/frqtl-node
 
 > The FRQTL physics engine (compiled Rust → WASM) for node: the same modules as @descix/frqtl-web, plus
-> `bootNode` and the hosted eyes. Pre-release 0.6.0-p0.2 on npm dist-tag `next`. Node ≥ 22.12.
+> `bootNode` and the hosted eyes. Pre-release 0.6.0-p1.1 on npm dist-tag `next`. Node ≥ 22.12.
 
 - Install: `npm install @descix/frqtl-node@next`
 - `import { bootNode, Wall } from '@descix/frqtl-node'` (require() works too); `await bootNode()` → the engine handle.
 - `./eyes`: `openHostedEyes({ sceneRecord, sceneSource: { kind: 'project', files, entry }, pageUrl })`.
 - `./project`: `linkProject` links a scene file against this package's own copy.
 - `./register`: `node --import @descix/frqtl-node/register scene.mjs` resolves a scene's `@descix/frqtl-web/...` imports to this package.
-- Full agent guide: https://cdn.jsdelivr.net/npm/@descix/frqtl-node@0.6.0-p0.2/CLAUDE.md
+- Full agent guide: https://cdn.jsdelivr.net/npm/@descix/frqtl-node@0.6.0-p1.1/CLAUDE.md
 - Acceptance is visual; no CLI ships. No account, credits or tokens are needed.