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

package/dist/frqtl/objects/RecipeContext.js

@@ -74,7 +74,12 @@ import { ObjectSchema } from './schema/index.js';
 import { kindOf } from './kinds.js';
 import { linkProject } from '../../shim/project/link.js';
 import { patchParts, PARTS_EXPORT, entryKeys, entryLiteral } from '../../shim/project/parts-writer.js';
-import { moduleOfKind } from '../../shim/project/parts-module.js';
+import { moduleOfKind, PARTS_SPECIFIER } from '../../shim/project/parts-module.js';
+import { forkPartText, FORK_REFUSED } from '../../shim/project/fork.js';
+import { readText } from '../../shim/project/read-text.js';
+import { packageRoot } from '../compat/package-root.js';
+import { MANIFEST_FILE } from '../../shim/project/manifest.js';
+import { Record, openRecordOf } from './record/Record.js';
 
     /** The world-init contract (objects/setup/_worldInit.js). */
     function _worldInit() {
@@ -123,6 +128,8 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
         this._parts   = new Map();   // declared object → { key, baseline } — the objects in `parts`
         this._code    = new Map();   // declared object → baseline — the code declarations at build end
         this._declaredOnce = false;
+        this._record  = null;   // the open Record (exp.startRecord), or null
+        this._reauthored = null;   // the Record the last re-authoring closed (startRecord checks its close was heard)
     }
 
     function _requireWorld(self) {
@@ -195,6 +202,7 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
         }
         // A (re-)inited world has no declared objects; the recipe re-declares what it builds.
         self._runner.clearDeclared();
+        self._runner.beginWorld();   // a (re-)inited world has not stepped
         W.applyPreInit(cfg, u);   // pre-init world keys (iframeIntervalSeconds) — the engine reads them at init
         u.init.apply(u, args);
         self._world = Object.freeze({ renderer: renderer, w: w, h: h, d: renderer === 'three' ? d : null,
@@ -300,7 +308,7 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
             }
             var obj = self.addObject(Kind, Object.assign({ name: key }, _plain(props)));
             self._runner._adoptIntoParts(obj);
-            self._parts.set(obj, { key: key, baseline: _capture(self, obj) });
+            self._parts.set(obj, { key: key, baseline: _capture(self, obj), kind: self._runner.kindOf(obj) });
             out[key] = obj;
         });
         return Object.freeze(out);
@@ -366,6 +374,22 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
         return props;
     }
 
+    /**
+     * Spell a touched `center` in the entry's OWN arity: two numbers when the entry
+     * spells two (a literal, or an array expression — entryLiteral's `length`) and the live z is 0; otherwise the
+     * live [x, y, z] (an entry spelled three, a 3D hand off z 0, an entry whose center is not an array). The
+     * read-back (_verifyWritten) guards every case. Mutates and returns `props`.
+     */
+    function _spellCenter(text, name, props) {
+        var v = props.center;
+        if (!Array.isArray(v) || v.length !== 3 || v[2] !== 0) { return props; }
+        if (entryKeys(text, name).indexOf('center') === -1) { return props; }
+        var r = entryLiteral(text, name, 'center');
+        var n = r.literal ? (Array.isArray(r.value) ? r.value.length : null) : r.length;
+        if (n === 2) { props.center = [v[0], v[1]]; }
+        return props;
+    }
+
     /**
      * The post-patch check: what the patched text now declares for entry `name`, read back (entryLiteral) for every
      * written key and folded with the baseline for every unwritten one, must equal the live capture — `rect` in its
@@ -379,6 +403,8 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
         Object.keys(written).forEach(function (k) {
             var r = entryLiteral(text, name, k);
             decl[k] = r.literal ? r.value : undefined;
+            // A two-number center declares z 0 (the reading placeDeclaredAt gives an omitted z).
+            if (k === 'center' && Array.isArray(decl[k]) && decl[k].length === 2) { decl[k] = decl[k].concat([0]); }
         });
         function refuse(k, declared, liveV) {
             refused.push({ op: 'set', name: name, key: k, reason: 'the written text declares ' + _JSON(declared) + ' but the live object is ' +
@@ -436,9 +462,11 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
      *   changes  patchParts' changes (a `literalized` set names the expression it replaced)
      *   refused  every hand not written, { op, name, key?, reason }
      */
-    RecipeContext.prototype.toSketch = async function () {
+    RecipeContext.prototype.toSketch = async function (opts) {
         _requireWorld(this);
         _requireHeld(this, 'toSketch');
+        var by = this._record ? Record.requireBy(opts && opts.by, 'RecipeContext.toSketch') : null;
+        if (this._record) { this._record._admit('RecipeContext.toSketch'); }
         var self = this;
         var runner = this._runner;
         var declared = runner.declared;
@@ -447,7 +475,7 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
         var adopted = [];
         var hands = runner._takeHandTouched();
         this._parts.forEach(function (row, obj) {
-            if (declared.indexOf(obj) === -1) { edits.push({ op: 'remove', name: row.key }); return; }
+            if (declared.indexOf(obj) === -1) { edits.push({ op: 'remove', name: row.key, kind: row.kind, baseline: row.baseline }); return; }
             if (!hands.has(obj)) { return; }
             var kind = runner.kindOf(obj);
             var t = _touched(kind, row.baseline, _capture(self, obj));
@@ -459,8 +487,10 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
                 refused.push({ op: 'set', name: row.key, key: k, reason: 'the live object no longer reports "' + k + '" — there is no value to write.' });
             });
             if (Object.keys(t.props).length) {
+                var raw = _plain(t.props);   // the capture form, before the entry's spelling (the Record's row values)
                 _spell(self._project.files[self._project.entry], row.key, kind, t.props, row.baseline);
-                if (Object.keys(t.props).length) { edits.push({ op: 'set', name: row.key, props: t.props, obj: obj, kind: kind, baseline: row.baseline }); }
+                _spellCenter(self._project.files[self._project.entry], row.key, t.props);
+                if (Object.keys(t.props).length) { edits.push({ op: 'set', name: row.key, props: t.props, obj: obj, kind: kind, baseline: row.baseline, raw: raw }); }
             }
         });
         this._code.forEach(function (baseline, obj) {
@@ -487,7 +517,9 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
         });
         var entry = this._project.entry;
         var r = patchParts(this._project.files[entry], edits.map(function (e) {
-            return e.op === 'set' ? { op: 'set', name: e.name, props: e.props } : e;
+            if (e.op === 'set') { return { op: 'set', name: e.name, props: e.props }; }
+            if (e.op === 'remove') { return { op: 'remove', name: e.name }; }
+            return { op: 'add', name: e.name, Kind: e.Kind, module: e.module, props: e.props };
         }), { entry: entry });
         // Never decide it succeeded without asking: read the patched text back against each moved object.
         edits.forEach(function (e) {
@@ -511,11 +543,76 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
             var key = obj.name || runner.kindOf(obj);
             if (refusedAdd[key]) { return; }
             runner._adoptIntoParts(obj);
-            self._parts.set(obj, { key: key, baseline: _capture(self, obj) });
+            self._parts.set(obj, { key: key, baseline: _capture(self, obj), kind: runner.kindOf(obj) });
         });
-        return { files: Object.assign({}, files), changes: r.changes, refused: refused.concat(r.refused) };
+        var allRefused = refused.concat(r.refused);
+        if (this._record) { _recordRows(this, edits, allRefused, by); }
+        return { files: Object.assign({}, files), changes: r.changes, refused: allRefused };
     };
 
+    /**
+     * The Record's rows for one toSketch, from the writer's own edits as WRITTEN (a refused edit, or a refused key
+     * of one, makes no row), in edit order (R3). A `set` whose touched keys include the part's position authority
+     * (runner._placementAuthority: `center`, or `rect` with its derivedFrom reads) is a `move` with that ONE key in
+     * its capture form; its other touched keys are one `setDeclared` row. `add` → [kind, props as written];
+     * `remove` → [kind, the baseline's writable props].
+     */
+    function _recordRows(self, edits, refused, by) {
+        var runner = self._runner;
+        var rec = self._record;
+        function refusedKeys(name, op) {
+            var keys = {};
+            var all = false;
+            refused.forEach(function (x) {
+                if (x.name !== name || x.op !== op) { return; }
+                if (x.key === undefined) { all = true; } else { keys[x.key] = true; }
+            });
+            return all ? null : keys;
+        }
+        function writableProps(kind, bag) {
+            var w = _writable(kind);
+            var out = {};
+            Object.keys(bag).forEach(function (k) { if (w[k] && k !== 'name') { out[k] = _plain(bag[k]); } });
+            return out;
+        }
+        edits.forEach(function (e) {
+            if (e.op === 'add') {
+                if (refusedKeys(e.name, 'add') === null) { return; }
+                rec._row({ name: e.name, op: 'add', by: by, from: null, to: [e.Kind, _plain(e.props)] });
+                return;
+            }
+            if (e.op === 'remove') {
+                if (refusedKeys(e.name, 'remove') === null) { return; }
+                rec._row({ name: e.name, op: 'remove', by: by, from: [e.kind, writableProps(e.kind, e.baseline)], to: null });
+                return;
+            }
+            var bad = refusedKeys(e.name, 'set');
+            if (bad === null) { return; }
+            var raw = e.raw;
+            var auth = (raw.center !== undefined || raw.rect !== undefined) ? runner._placementAuthority(e.obj) : null;
+            var authReads = {};
+            if (auth) {
+                authReads[auth] = true;
+                ObjectSchema.derivedReads(e.kind).forEach(function (d) { if (d.field === auth) { authReads[d.name] = true; } });
+            }
+            var moveRefused = Object.keys(bad).some(function (k) { return authReads[k]; });
+            if (auth && raw[auth] !== undefined && !moveRefused) {
+                var from = {}, to = {};
+                from[auth] = _plain(e.baseline[auth]);
+                to[auth] = _plain(raw[auth]);
+                rec._row({ name: e.name, op: 'move', by: by, from: from, to: to });
+            }
+            var pf = {}, pt = {}, any = false;
+            Object.keys(raw).forEach(function (k) {
+                if (k === auth || bad[k]) { return; }
+                pf[k] = e.baseline[k] === undefined ? null : _plain(e.baseline[k]);
+                pt[k] = _plain(raw[k]);
+                any = true;
+            });
+            if (any) { rec._row({ name: e.name, op: 'setDeclared', by: by, from: pf, to: pt }); }
+        });
+    }
+
     /** The names of declared objects a hand marked whose live capture differs from their baseline (not yet written). */
     function _unwrittenHands(self) {
         var runner = self._runner;
@@ -553,11 +650,15 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
      * setOrbit) are kept; `kept` lists 'cameraPose' only when a pose was captured and re-applied. A `rect` /
      * `center` patch sets where the entry STARTS. The loop's run state is kept. REFUSES (throws) while a hand
      * made since the last toSketch is unwritten (write it first: await exp.toSketch()), and a `name` patch (the
-     * key is the name).
+     * key is the name). `from` and `to` are the patched keys' capture (ObjectSchema.captureProps) before and after the
+     * re-run — one form on both sides (a z-slab wall's rect is 6 numbers even when the patch typed 4); the patch as
+     * typed is in `files`. With a Record open, its `setDeclared` row carries the same `from`/`to`, written after the re-run.
      */
-    RecipeContext.prototype.setDeclared = async function (name, patch) {
+    RecipeContext.prototype.setDeclared = async function (name, patch, opts) {
         _requireWorld(this);
         _requireHeld(this, 'setDeclared');
+        var by = this._record ? Record.requireBy(opts && opts.by, 'RecipeContext.setDeclared') : null;
+        if (this._record) { this._record._admit('RecipeContext.setDeclared'); }
         var runner = this._runner;
         var obj = null;
         this._parts.forEach(function (row, o) { if (row.key === name) { obj = o; } });
@@ -615,7 +716,117 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
             runner.cameraControl.setOrbit(pose);
             kept.push('cameraPose');
         }
-        return { set: name, from: from, to: _plain(patch), tick: 0, kept: kept, files: Object.assign({}, files) };
+        // `to` is what the re-run declared, in the capture form `from` is in (the patch as typed is in the text).
+        var rebuilt = null;
+        this._parts.forEach(function (row, o) { if (row.key === name) { rebuilt = o; } });
+        if (!rebuilt) {
+            throw new Error('[RecipeContext.setDeclared] the re-run declared no "' + name + '" — the patched text dropped the entry. (FAIL-LOUD.)');
+        }
+        var after = _capture(this, rebuilt);
+        var to = {};
+        Object.keys(patch).forEach(function (k) { to[k] = after[k] === undefined ? null : _plain(after[k]); });
+        if (this._record) { this._record._row({ name: name, op: 'setDeclared', by: by, from: _plain(from), to: _plain(to) }); }
+        return { set: name, from: from, to: to, tick: 0, kept: kept, files: Object.assign({}, files) };
+    };
+
+    /**
+     * exp.fork(name, NewKind[, { by }]) → Promise<{ fork, file, from, files }> — copy the part file of `inParts` object
+     * `name`'s kind into the project as `parts/<NewKind>.js` (lib/shim/project/fork.js forkPartText: the class renamed,
+     * its imports rewritten to package specifiers, every other byte the source's), point the entry at the fork (the
+     * parts writer's `kind` edit: the Kind identifier and one import line), and re-run the scene IN THIS DOCUMENT
+     * through the one restart door, as setDeclared does: the seed and the camera pose are kept, the loop's run state
+     * is kept. The source text is the exact bytes the kind's `from` names: a package part's file (read through
+     * read-text.js readText), or a project fork's held file. The held project is updated BEFORE the re-run, so an open
+     * Record stays open; with one open, `by` is required and its `fork` row ({ from: <kind>, to: { kind, file } }) is
+     * written after the re-run. REFUSES (throws, the held text unchanged): a name that is not an `inParts` object, a
+     * hand made since the last toSketch that is unwritten, a kind with no file a fork can copy, every forkPartText
+     * refusal, a writer refusal, and a re-run whose entry is not the fork.
+     */
+    /**
+     * The fork's plan for `inParts` object `name`, before any read: { obj, from, row, module }. THROWS the refusal
+     * fork() and forkRefusal() both name: not an `inParts` object, an unwritten hand, a kind FORK_REFUSED names
+     * (lib/shim/project/fork.js, the census reason), a kind with no part file a fork can copy.
+     */
+    function _forkPlan(self, name) {
+        var runner = self._runner;
+        var obj = null;
+        self._parts.forEach(function (row, o) { if (row.key === name) { obj = o; } });
+        if (!obj || runner.declared.indexOf(obj) === -1) {
+            throw new Error('[RecipeContext.fork] "' + name + '" is not an object of this sketch\'s `parts` block' +
+                (self._code.size ? ' (code declarations: ' + Array.from(self._code.keys()).map(function (o) { return o.name; }).join(', ') +
+                    ' — ' + OUTSIDE_PARTS + ')' : '') + '. (FAIL-LOUD.)');
+        }
+        var unwritten = _unwrittenHands(self);
+        if (unwritten.length) {
+            throw new Error('[RecipeContext.fork] "' + unwritten.join('", "') + '" carries a hand the sketch text does ' +
+                'not hold yet — write the hand first: await exp.toSketch(). (FAIL-LOUD.)');
+        }
+        var from = runner.kindOf(obj);
+        if (Object.prototype.hasOwnProperty.call(FORK_REFUSED, from)) {
+            throw new Error('[RecipeContext.fork] ' + from + ' (the kind of "' + name + '") is not forkable — ' + FORK_REFUSED[from] + '. (FAIL-LOUD.)');
+        }
+        var row = kindOf(from);
+        var module = row ? moduleOfKind(row.from, self._urls) : null;
+        if (module !== PARTS_SPECIFIER && !(module && Object.prototype.hasOwnProperty.call(self._project.files, module))) {
+            throw new Error('[RecipeContext.fork] ' + from + ' (the kind of "' + name + '") has no part file a fork can copy — a fork ' +
+                'copies a part of @descix/frqtl-web/parts or a part file of this project. (FAIL-LOUD.)');
+        }
+        return { obj: obj, from: from, row: row, module: module };
+    }
+
+    /**
+     * exp.forkRefusal(name) → null when exp.fork(name, …) may run, else the refusal it would throw (one sentence). A
+     * host's "Fork into project" control reads it for its disabled state and title; fork() runs the same plan.
+     */
+    RecipeContext.prototype.forkRefusal = function (name) {
+        _requireWorld(this);
+        _requireHeld(this, 'forkRefusal');
+        try { _forkPlan(this, name); return null; }
+        catch (err) { return String(err && err.message).replace(/^\[RecipeContext\.fork\] /, '').replace(/ \(FAIL-LOUD\.\)$/, ''); }
+    };
+
+    RecipeContext.prototype.fork = async function (name, NewKind, opts) {
+        _requireWorld(this);
+        _requireHeld(this, 'fork');
+        var by = this._record ? Record.requireBy(opts && opts.by, 'RecipeContext.fork') : null;
+        if (this._record) { this._record._admit('RecipeContext.fork'); }
+        var runner = this._runner;
+        var plan = _forkPlan(this, name);
+        var from = plan.from, row = plan.row, module = plan.module;
+        var text, libPath;
+        if (module === PARTS_SPECIFIER) {
+            libPath = row.from.slice(packageRoot().length);
+            try { text = await readText(row.from); }
+            catch (err) { throw new Error('[RecipeContext.fork] the part file of ' + from + ': ' + ((err && err.message) || err) + '. (FAIL-LOUD.)'); }
+        } else {
+            libPath = module;
+            text = this._project.files[module];
+        }
+        var forked = forkPartText(text, { from: from, to: NewKind, libPath: libPath, files: this._project.files });
+        var file = 'parts/' + NewKind + '.js';
+        var entry = this._project.entry;
+        var r = patchParts(this._project.files[entry], [{ op: 'kind', name: name, Kind: NewKind, module: file }], { entry: entry });
+        if (r.refused.length) {
+            throw new Error('[RecipeContext.fork] the sketch text refused the fork: ' +
+                r.refused.map(function (x) { return x.reason; }).join('; ') + ' (FAIL-LOUD.)');
+        }
+        var files = Object.assign({}, this._project.files);
+        files[file] = forked.text;
+        files[entry] = r.text;
+        this._project = Object.assign({}, this._project, { files: files });
+        var pose = _cameraPose(runner);
+        var wasRunning = !!runner._isLooping;
+        await runner.restart();
+        if (!wasRunning) { runner.stop(); }
+        if (pose && runner.cameraControl && typeof runner.cameraControl.setOrbit === 'function') { runner.cameraControl.setOrbit(pose); }
+        var rebuilt = null;
+        this._parts.forEach(function (row2, o) { if (row2.key === name) { rebuilt = o; } });
+        if (!rebuilt || runner.kindOf(rebuilt) !== NewKind) {
+            throw new Error('[RecipeContext.fork] the re-run declared "' + name + '" as ' + (rebuilt ? runner.kindOf(rebuilt) : 'nothing') +
+                ', not the fork ' + NewKind + '. (FAIL-LOUD.)');
+        }
+        if (this._record) { this._record._row({ name: name, op: 'fork', by: by, from: from, to: { kind: NewKind, file: file } }); }
+        return { fork: NewKind, file: file, from: from, files: Object.assign({}, files) };
     };
 
     RecipeContext.prototype.addTickFunction = function (fn) {
@@ -683,8 +894,8 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
         var linked = null;
         if (sketch && typeof sketch === 'object' && typeof sketch.buildExperiment === 'function') {
             if (!sketch.project || typeof sketch.project !== 'object' || !sketch.project.files || typeof sketch.project.entry !== 'string') {
-                throw new TypeError('[RecipeContext.build] build(linked): linked is linkProject\'s result { buildExperiment, files, ' +
-                    'urls, project } (lib/shim/project/link.js). (FAIL-LOUD.)');
+                throw new TypeError('[RecipeContext.build] build(linked): linked is linkProject\'s result (its contract: ' +
+                    'lib/shim/project/link.js). (FAIL-LOUD.)');
             }
             linked = sketch;
             sketch = linked.buildExperiment;
@@ -693,6 +904,12 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
                 'linkProject\'s result (got ' + typeof sketch + '). (FAIL-LOUD.)');
         }
         if (typeof sketch === 'function') {
+            // ONE Record per booted world: a build of text that is not the held text re-authors it, and closes the
+            // open Record with the world before (a rebuild of the same text — restart, setDeclared's re-run — does not).
+            if (this._record && !(linked && this._project && _sameFiles(linked.project.files, this._project.files))) {
+                this._reauthored = this._record;
+                this._record._closeOnReauthor(this._project);
+            }
             this._buildFn = sketch;
             this._project = linked ? linked.project : null;
             this._urls = linked ? (linked.urls || null) : null;
@@ -719,6 +936,60 @@ import { moduleOfKind } from '../../shim/project/parts-module.js';
         return this;
     };
 
+    /** Two file maps hold the same paths with byte-equal text. */
+    function _sameFiles(a, b) {
+        var ka = Object.keys(a), kb = Object.keys(b);
+        if (ka.length !== kb.length) { return false; }
+        return ka.every(function (k) { return Object.prototype.hasOwnProperty.call(b, k) && a[k] === b[k]; });
+    }
+
+    /**
+     * exp.startRecord() → Promise<Record> — open a Record (lib/frqtl/objects/record/Record.js) on this facade's world.
+     * REFUSES (rejects): a second open Record (one per facade, one per runner); a held project with no frqtl.json
+     * (a Record snapshots a folder); a hand the sketch text does not hold yet (as setDeclared). While it is open,
+     * toSketch({ by }) and setDeclared(name, patch, { by }) name who acted.
+     */
+    RecipeContext.prototype.startRecord = async function () {
+        _requireWorld(this);
+        _requireHeld(this, 'startRecord');
+        if (this._record) {
+            throw new Error('[RecipeContext.startRecord] a Record is already open on this facade (one per booted world) — ' +
+                'await rec.stop() first. (FAIL-LOUD.)');
+        }
+        // A re-authoring closed the previous Record; if that close was REFUSED and nobody read it, its rows would be lost
+        // without a word: refuse until the host reads `rec.closed` (the rejection carries err.record).
+        var last = this._reauthored;
+        if (last) {
+            await last._settled;
+            if (last._refused && !last._closedRead) {
+                var err = new Error('[RecipeContext.startRecord] the previous Record of this facade was closed by a re-authoring and ' +
+                    'REFUSED (' + last._refused.message + ') — nobody read rec.closed, so its ' + last._refused.record.changes.length +
+                    ' row(s) would be lost: read rec.closed (its rejection carries err.record = { changes, clips }) first. (FAIL-LOUD.)');
+                err.record = last._refused.record;
+                throw err;
+            }
+            this._reauthored = null;
+        }
+        if (openRecordOf(this._runner)) {
+            throw new Error('[RecipeContext.startRecord] another facade holds an open Record on this runner. (FAIL-LOUD.)');
+        }
+        if (!Object.prototype.hasOwnProperty.call(this._project.files, MANIFEST_FILE)) {
+            throw new Error('[RecipeContext.startRecord] a Record snapshots a folder; boot it as one — the held project carries ' +
+                'no ' + MANIFEST_FILE + ': add files[\'' + MANIFEST_FILE + '\'] = serializeManifest(manifestFor({ name, entry: SKETCH_ENTRY })) ' +
+                '(all from ./project) to the files you boot. (FAIL-LOUD.)');
+        }
+        var unwritten = _unwrittenHands(this);
+        if (unwritten.length) {
+            throw new Error('[RecipeContext.startRecord] "' + unwritten.join('", "') + '" carries a hand the sketch text does ' +
+                'not hold yet — write the hand first: await exp.toSketch(). (FAIL-LOUD.)');
+        }
+        var rec = new Record(this);
+        this._record = rec;
+        try { await rec._ready(this._project); }
+        catch (e) { rec._detach(); throw e; }
+        return rec;
+    };
+
     RecipeContext.prototype.run = function (buildFn) {
         if (buildFn && typeof buildFn === 'function' && !this._built) { this.build(buildFn); }
         _requireWorld(this);

package/dist/frqtl/objects/constants/WallBehaviors.js

@@ -128,7 +128,7 @@ import { compileWallV2 } from '../objects/actionCompiler.js';
     }
 
     // ── Presets (B6) — pure CONSTRUCTION sugar expanding to the v2 descriptor fields.
-    // The recipe/codegen round-trips the EXPANDED fields (never the preset name).
+    // The parts writer captures the EXPANDED fields (never the preset name).
     //
     // THE NAMING RULE: a preset's NAME MUST ASSERT ITS BEHAVIOR.
     // `collisionBehavior:'nothing'` (pass-through) belongs ONLY on a preset whose name SAYS

package/dist/frqtl/objects/instruments/capture.js

@@ -71,29 +71,6 @@ import { loadedWasmSha256 } from '../../compat/providers/wasm-load-browser.js';
 import * as FrqtlDisplay from '../../compat/renderer/display-slot.js';
 
 
-    /**
-     * The experiment identity the page ALREADY carries, ferried — not a second authority.
-     *
-     * The experiments registry DEFINES an experiment id as "the directory name under
-     * experiments/" (`experimentById`), and a canonical page is served from
-     * `…/experiments/<id>/index.html`. So the path segment IS the registry id, and reading it
-     * ferries the existing identity rather than minting a parallel one. The registry module
-     * is a registry, not a page fact, which is why the id is taken from the URL the registry's
-     * own ids are defined by.
-     *
-     * Fails SOFT to null (no DOM, a notebook realm, an ad-hoc page): `sourceRef: null` is the
-     * honest "this scene has no authored identity" value, and the corpus row then carries the
-     * code itself. A caller with a better identity overrides via `setSourceRef()`.
-     * @private
-     */
-    function _defaultSourceRef() {
-        try {
-            if (typeof location === 'undefined' || !location) { return null; }
-            var m = String(location.pathname).match(/\/experiments\/([^/]+)\//);
-            return (m && m[1]) ? m[1] : null;
-        } catch (e) { return null; }
-    }
-
     /**
      * The RASTER PATH pin — which GL backend this browser actually rasters with.
      *
@@ -207,7 +184,7 @@ import * as FrqtlDisplay from '../../compat/renderer/display-slot.js';
         // harness via setSourceRef(). null is HONEST (an ad-hoc universe); the corpus row then
         // carries the code itself. Never per-capture caller-supplied provenance.
         this._sourceRef = (identity.sourceRef === undefined || identity.sourceRef === null)
-            ? _defaultSourceRef() : String(identity.sourceRef);
+            ? null : String(identity.sourceRef);
         // The code identity (setSourceSha256) — null until a door that linked a project registers it.
         this._sourceSha256 = null;
         // Memo for the content-addressed SceneRecord — see sceneRecord().