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

package/dist/frqtl/objects/RecipeContext.js

@@ -19,12 +19,39 @@
  * explicit depth d.
  *
  *   exp.world                     the ONE readable answer: frozen {renderer, w, h, d, cfg}
- *   exp.addObject(kind, config)   ObjectFactory.create(kind, config, ctx) sugar
+ *   exp.addObject(kind, config)   ObjectFactory.create(kind, config, ctx) sugar (a kind by name or class)
+ *   exp.declare(parts)            the sketch's `export const parts = { name: [Kind, props] }`, in key order;
+ *                                 returns the frozen build-time map { key: handle }
  *   exp.addTickFunction(fn)       universe.experimentTickFunctions.push
  *   exp.render(bag)               runner.setRenderOptions(bag)
- *   exp.build(buildFn)            run the recipe WITHOUT starting the loop (a sketch held as
- *                                 TEXT is a project, linked first: lib/shim/project/link.js linkProject)
+ *   exp.build(sketch)             run the recipe WITHOUT starting the loop; `sketch` is a buildExperiment
+ *                                 function or linkProject's result (lib/shim/project/link.js) — then the
+ *                                 facade HOLDS that project's text
+ *   exp.toSketch()                write the hands into the held text's `parts` block → { files, changes, refused }
+ *   exp.setDeclared(name, patch)  patch one parts entry and re-run in this document
  *   exp.run(buildFn)              build (if needed) + start the loop
+ *
+ * THE WRITER CONTRACT. The facade that linked a sketch is the ONE owner of its current text: the text it
+ * linked, then every toSketch / setDeclared result.
+ *   - exp.declare(parts) calls exp.addObject(Kind, { name: key, ...props }) per own key (zero physics). It
+ *     refuses a string Kind (naming the import form), an unregistered class, a props.name (the key IS the
+ *     name) and a second call in one build. Each object it declares is an `inParts` row of runner.declared;
+ *     its capture right after construction (ObjectSchema.captureProps) is the writer's baseline. It returns
+ *     the frozen build-time map { key: handle } (`const p = exp.declare(parts); … p.screen`).
+ *   - toSketch is a HOST call at the END of an act (STUDIO: a hand's release; a lab: the end of a hand),
+ *     never per placement. It writes, through lib/shim/project/parts-writer.js patchParts, only what a
+ *     hand did since the last call (the runner's hand mark): an inParts object's touched writable keys
+ *     (`set`), a declared object added since the build (`add`, the last key, plus one import line), an
+ *     inParts object no longer live (`remove`). A hand on a code declaration is refused by name. It
+ *     adopts its result and resets every baseline, so a second call with no hand between is a no-op.
+ *   - setDeclared validates each key against the kind's descriptor (writable, its own validator),
+ *     patches the held text and re-runs through the one restart door in THIS document; the seed (the
+ *     sketch's own co-init cfg) and the camera pose (its poseFields, re-applied through setOrbit) are kept.
+ *   - A hand is a write through runner.updateObjectProperty or runner.placeDeclaredAt; a host that calls a
+ *     part's own setter is driving the run, and the writer does not write it. A hand never renames: the key is
+ *     the name, so a touched `name` is refused (toSketch) or thrown (setDeclared).
+ *   - setDeclared refuses while a hand is unwritten (await exp.toSketch() first); its `kept` lists what it kept.
+ *   - restart() of a linked sketch re-links the CURRENT text (the retained replay) and returns a Promise.
  *   exp.runner / .universe        the runner the co-init call built
  *   exp.is3D                      world.renderer === 'three'
  *
@@ -43,6 +70,11 @@ import { ObjectFactory } from './ObjectFactory.js';
 import { FrqtlWorldInit } from './setup/_worldInit.js';
 import * as FrqtlDisplay from '../compat/renderer/display-slot.js';
 import { refuseRetiredDoors } from '../compat/engine.js';
+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';
 
     /** The world-init contract (objects/setup/_worldInit.js). */
     function _worldInit() {
@@ -86,6 +118,11 @@ import { refuseRetiredDoors } from '../compat/engine.js';
         this._world  = null;    // set by the co-init call; reset by build()
         this._built  = false;
         this._buildFn = null;
+        this._project = null;   // THE held project text: { files: {path: text}, entry, mint, bare? } (build(linked))
+        this._urls    = null;   // the minted URL of each project file, from the last link
+        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;
     }
 
     function _requireWorld(self) {
@@ -148,6 +185,8 @@ import { refuseRetiredDoors } from '../compat/engine.js';
             self._runner = new FrqtlApp(ropts);
             if (!self._opts.deferCanvas) { self._runner.createCanvas(); }
         }
+        // The census maps a declared kind's module against the project files this facade linked (FrqtlApp.declare).
+        self._runner._projectUrls = self._urls;
         var u = self._runner.universe;
         var args = W.initArgs(cfg);
         if (renderer === 'three') {
@@ -190,6 +229,7 @@ import { refuseRetiredDoors } from '../compat/engine.js';
 
     // ── parts, tick-fns, render ──────────────────────────────────────────────────────
 
+    /** exp.addObject(kind, config) — a kind by name (a host's JSON) or by its class. */
     RecipeContext.prototype.addObject = function (kind, config) {
         _requireWorld(this);
         var x = (config && config.x != null) ? config.x : 0;
@@ -198,6 +238,386 @@ import { refuseRetiredDoors } from '../compat/engine.js';
         return ObjectFactory.create(kind, config, ctx);
     };
 
+    // ── the parts block ───────────────────────────────────────────────────────────────
+
+    var IMPORT_FORM = 'import { <Kind> } from \'@descix/frqtl-web/parts\'';
+
+    /** A deep copy of arrays and plain objects (the module-level literal is never shared with a part). */
+    function _plain(v) {
+        if (v === null || typeof v !== 'object') { return v; }
+        if (Array.isArray(v)) { return v.map(_plain); }
+        var proto = Object.getPrototypeOf(v);
+        if (proto !== Object.prototype && proto !== null) { return v; }
+        var out = {};
+        Object.keys(v).forEach(function (k) { out[k] = _plain(v[k]); });
+        return out;
+    }
+
+    /**
+     * exp.declare(parts) — seed the declared parts of `export const parts = { name: [Kind, props], … }`, in key
+     * order: `exp.addObject(Kind, { name: key, ...props })` per own key. Packaging, zero physics. Each object
+     * declared here is an `inParts` object of the census, and its capture right after construction is the
+     * writer's baseline (toSketch diffs against it).
+     * RETURNS the build-time map `Object.freeze({ <key>: handle, … })`, in key order — each value the object
+     * exp.addObject returned (the same identity as its runner.declared row), so later scene code reads a part
+     * as `const p = exp.declare(parts); … p.screen`. A hand add or remove after the build does not update it.
+     * REFUSES (throws): a string Kind (name the import form), a Kind that is not a registered class, a
+     * `props.name` (the key IS the name), a second declare in one build, an entry not written [Kind, props].
+     */
+    RecipeContext.prototype.declare = function (parts) {
+        _requireWorld(this);
+        if (this._declaredOnce) {
+            throw new Error('[RecipeContext.declare] exp.declare(parts) runs ONCE per build — the scene\'s one `export const ' +
+                PARTS_EXPORT + '` block is its declared parts. (FAIL-LOUD.)');
+        }
+        if (!parts || typeof parts !== 'object' || Array.isArray(parts)) {
+            throw new TypeError('[RecipeContext.declare] exp.declare(parts): parts is the sketch\'s `export const ' + PARTS_EXPORT +
+                ' = { name: [Kind, { …props }] }` object. (FAIL-LOUD.)');
+        }
+        this._declaredOnce = true;
+        var self = this;
+        var out = {};
+        Object.keys(parts).forEach(function (key) {
+            var entry = parts[key];
+            if (!Array.isArray(entry) || entry.length !== 2 || !entry[1] || typeof entry[1] !== 'object' || Array.isArray(entry[1])) {
+                throw new TypeError('[RecipeContext.declare] parts.' + key + ' is not [Kind, { …props }]. (FAIL-LOUD.)');
+            }
+            var Kind = entry[0], props = entry[1];
+            if (typeof Kind === 'string') {
+                throw new TypeError('[RecipeContext.declare] parts.' + key + ' names its kind by the string "' + Kind + '" — in ' +
+                    '`parts` a kind is the imported class: ' + IMPORT_FORM.replace('<Kind>', Kind) + '. (exp.addObject(name, ' +
+                    'props) still takes a string.) (FAIL-LOUD.)');
+            }
+            if (typeof Kind !== 'function' || !kindOf(Kind)) {
+                throw new TypeError('[RecipeContext.declare] parts.' + key + ': ' + (typeof Kind === 'function'
+                    ? 'the class ' + (Kind.name || '(anonymous)') + ' is not a registered kind in this realm'
+                    : 'the kind is ' + (Kind === null ? 'null' : typeof Kind) + ', not a registered class') +
+                    ' — ' + IMPORT_FORM + ', or register a forked part\'s renamed class (@descix/frqtl-web/kinds). (FAIL-LOUD.)');
+            }
+            if (Object.prototype.hasOwnProperty.call(props, 'name')) {
+                throw new TypeError('[RecipeContext.declare] parts.' + key + ' carries name ' + JSON.stringify(props.name) +
+                    ' — in `parts` the KEY is the name ("' + key + '"); delete the name prop. (FAIL-LOUD.)');
+            }
+            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) });
+            out[key] = obj;
+        });
+        return Object.freeze(out);
+    };
+
+    function _capture(self, obj) {
+        return ObjectSchema.captureProps(obj, self._runner.kindOf(obj));
+    }
+
+    /** The fields a hand or setDeclared may write: the descriptor's, minus write-only adapters and readonly reads. */
+    function _writable(kind) {
+        var d = ObjectSchema.get(kind);
+        var out = {};
+        ((d && d.fields) || []).forEach(function (f) {
+            if (f.writeOnly !== true && f.type !== 'readonly') { out[f.name] = f; }
+        });
+        return out;
+    }
+
+    /** The writable keys whose live value differs from the baseline (JSON-equal = untouched). */
+    function _touched(kind, baseline, live) {
+        var w = _writable(kind);
+        var out = {};
+        var lost = [];
+        Object.keys(w).forEach(function (k) {
+            var a = baseline[k], b = live[k];
+            if (JSON.stringify(a) === JSON.stringify(b)) { return; }
+            if (b === undefined) { lost.push(k); return; }
+            out[k] = b;
+        });
+        return { props: out, lost: lost };
+    }
+
+    var RENAME = FrqtlApp.RENAME_REFUSAL;
+
+    var _JSON = function (v) { return JSON.stringify(v); };
+
+    /**
+     * Spell a touched rect in the entry's OWN form (architect z addendum). A 6-tuple rect of a kind whose descriptor
+     * derives reads from it (ObjectSchema.derivedReads: Wall `z`, `depth`) is written as the 4-tuple plus each derived
+     * key whose value changed, when the entry spells any of those keys as plain properties (entryKeys); otherwise the
+     * 6-tuple stands. A 4-tuple equal to the baseline's is not written (no literalizing an untouched expression).
+     * Mutates and returns `props`.
+     */
+    function _spell(text, name, kind, props, baseline) {
+        var derived = ObjectSchema.derivedReads(kind);
+        if (!derived.length) { return props; }
+        var spelled = entryKeys(text, name);
+        var R4 = ObjectSchema.RECT_TUPLE[4], R6 = ObjectSchema.RECT_TUPLE[6];
+        Object.keys(props).forEach(function (f) {
+            var v = props[f];
+            var rows = derived.filter(function (d) { return d.field === f && d.tuple === 6 && spelled.indexOf(d.name) !== -1; });
+            if (!rows.length || !Array.isArray(v) || v.length !== 6) { return; }
+            var b = Array.isArray(baseline[f]) && baseline[f].length === 6 ? baseline[f] : null;
+            var four = R4.map(function (k) { return v[R6.indexOf(k)]; });
+            if (b && _JSON(four) === _JSON(R4.map(function (k) { return b[R6.indexOf(k)]; }))) { delete props[f]; }
+            else { props[f] = four; }
+            rows.forEach(function (d) {
+                var nv = v[R6.indexOf(d.key)];
+                if (!b || nv !== b[R6.indexOf(d.key)]) { props[d.name] = nv; }
+            });
+        });
+        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
+     * capture form, through the descriptor's derivedFrom rows. Each mismatch is a refusal naming the key.
+     */
+    function _verifyWritten(text, name, kind, written, baseline, live) {
+        var refused = [];
+        var R4 = ObjectSchema.RECT_TUPLE[4], R6 = ObjectSchema.RECT_TUPLE[6];
+        var derived = ObjectSchema.derivedReads(kind);
+        var decl = {};
+        Object.keys(written).forEach(function (k) {
+            var r = entryLiteral(text, name, k);
+            decl[k] = r.literal ? r.value : undefined;
+        });
+        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 ' +
+                _JSON(liveV) + ' — the hand is not in the text.' });
+        }
+        var asDerived = {};
+        derived.forEach(function (d) { asDerived[d.name] = d; });
+        Object.keys(written).forEach(function (k) {
+            if (asDerived[k]) { return; }
+            var lv = live[k];
+            if (Array.isArray(lv) && lv.length === 6 && derived.some(function (d) { return d.field === k; })) { return; }
+            if (_JSON(decl[k]) !== _JSON(lv)) { refuse(k, decl[k], lv); }
+        });
+        var fields = {};
+        derived.forEach(function (d) { fields[d.field] = true; });
+        Object.keys(fields).forEach(function (f) {
+            var lv = live[f];
+            if (!Array.isArray(lv) || lv.length !== 6) { return; }
+            var touched = written[f] !== undefined || derived.some(function (d) { return d.field === f && written[d.name] !== undefined; });
+            if (!touched) { return; }
+            var six = Array.isArray(baseline[f]) && baseline[f].length === 6 ? baseline[f].slice() : null;
+            var d0 = decl[f];
+            if (Array.isArray(d0) && d0.length === 6) { six = d0.slice(); }
+            else if (Array.isArray(d0) && d0.length === 4 && six) { R4.forEach(function (k, i) { six[R6.indexOf(k)] = d0[i]; }); }
+            derived.forEach(function (d) {
+                if (d.field === f && six && decl[d.name] !== undefined) { six[R6.indexOf(d.key)] = decl[d.name]; }
+            });
+            if (_JSON(six) !== _JSON(lv)) { refuse(f, six, lv); }
+        });
+        return refused;
+    }
+
+    var OUTSIDE_PARTS = 'this sketch declares its parts outside `parts`; STUDIO can run it but cannot write hand edits ' +
+        'into it — declare them in `export const parts` to make it editable.';
+
+    function _requireHeld(self, where) {
+        if (!self._project) {
+            throw new Error('[RecipeContext.' + where + '] this scene was not built from linked text — the writer writes the ' +
+                'text a facade linked: exp.build(await linkProject({ files, entry, mint })) (lib/shim/project/link.js). (FAIL-LOUD.)');
+        }
+    }
+
+    /**
+     * exp.toSketch() → Promise<{ files, changes, refused }> — write the hands into the sketch's `parts` literal.
+     * A HOST call at the END of an act (a drop, a drag end, a delete; a lab's end of a hand), never per
+     * placement. For each declared object a hand wrote since the last call (the runner's hand mark: a device
+     * door — updateObjectProperty, placeDeclaredAt — wrote it; a part the scene's own code moves is the run,
+     * not a hand), it diffs the `inParts` object's live capture against its baseline (touched keys only →
+     * `set`), writes each declared object added since the build (`add`, as the last key, plus its import line)
+     * and each removed `inParts` object (`remove`), through lib/shim/project/parts-writer.js patchParts on the
+     * HELD text. A code-declared object a hand touched (or removed) is refused by name. On return the patched
+     * text IS the held text and every baseline is the live capture, so a second call with no hand between
+     * returns byte-identical files and no changes.
+     *   files    { path: text } — the whole project as now held
+     *   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 () {
+        _requireWorld(this);
+        _requireHeld(this, 'toSketch');
+        var self = this;
+        var runner = this._runner;
+        var declared = runner.declared;
+        var edits = [];
+        var refused = [];
+        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 (!hands.has(obj)) { return; }
+            var kind = runner.kindOf(obj);
+            var t = _touched(kind, row.baseline, _capture(self, obj));
+            if (Object.prototype.hasOwnProperty.call(t.props, 'name')) {
+                refused.push({ op: 'set', name: row.key, key: 'name', reason: RENAME });
+                delete t.props.name;
+            }
+            t.lost.forEach(function (k) {
+                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) {
+                _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 }); }
+            }
+        });
+        this._code.forEach(function (baseline, obj) {
+            var name = obj.name || runner.kindOf(obj);
+            if (declared.indexOf(obj) === -1) {
+                refused.push({ op: 'remove', name: name, reason: '"' + name + '" is declared in code: ' + OUTSIDE_PARTS });
+                return;
+            }
+            if (!hands.has(obj)) { return; }
+            var t = _touched(runner.kindOf(obj), baseline, _capture(self, obj));
+            if (Object.keys(t.props).length || t.lost.length) {
+                refused.push({ op: 'set', name: name, reason: '"' + name + '" is declared in code: ' + OUTSIDE_PARTS });
+            }
+        });
+        declared.forEach(function (obj) {
+            if (self._parts.has(obj) || self._code.has(obj)) { return; }
+            var kind = runner.kindOf(obj);
+            var row = kindOf(kind);
+            var props = _capture(self, obj);
+            var w = _writable(kind);
+            Object.keys(props).forEach(function (k) { if (!w[k] || k === 'name') { delete props[k]; } });
+            edits.push({ op: 'add', name: obj.name || kind, Kind: kind, module: row ? moduleOfKind(row.from, self._urls) : null, props: props });
+            adopted.push(obj);
+        });
+        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;
+        }), { entry: entry });
+        // Never decide it succeeded without asking: read the patched text back against each moved object.
+        edits.forEach(function (e) {
+            if (e.op !== 'set') { return; }
+            if (r.refused.some(function (x) { return x.op === 'set' && x.name === e.name; })) { return; }
+            refused.push.apply(refused, _verifyWritten(r.text, e.name, e.kind, e.props, e.baseline, _capture(self, e.obj)));
+        });
+        var refusedAdd = {};
+        r.refused.forEach(function (x) { if (x.op === 'add') { refusedAdd[x.name] = true; } });
+        var files = Object.assign({}, this._project.files);
+        files[entry] = r.text;
+        this._project = Object.assign({}, this._project, { files: files });
+        // Adopt: the written text is held; baselines follow the live objects.
+        var removedRefused = {};
+        r.refused.forEach(function (x) { if (x.op === 'remove') { removedRefused[x.name] = true; } });
+        this._parts.forEach(function (row, obj) {
+            if (declared.indexOf(obj) === -1) { if (!removedRefused[row.key]) { self._parts.delete(obj); } return; }
+            row.baseline = _capture(self, obj);
+        });
+        adopted.forEach(function (obj) {
+            var key = obj.name || runner.kindOf(obj);
+            if (refusedAdd[key]) { return; }
+            runner._adoptIntoParts(obj);
+            self._parts.set(obj, { key: key, baseline: _capture(self, obj) });
+        });
+        return { files: Object.assign({}, files), changes: r.changes, refused: refused.concat(r.refused) };
+    };
+
+    /** 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;
+        var marks = runner._handTouched;
+        if (!marks || !marks.size) { return []; }
+        var out = [];
+        marks.forEach(function (obj) {
+            if (runner.declared.indexOf(obj) === -1) { return; }
+            var row = self._parts.get(obj);
+            var baseline = row ? row.baseline : self._code.get(obj);
+            if (!baseline) { return; }
+            var t = _touched(runner.kindOf(obj), baseline, _capture(self, obj));
+            if (Object.keys(t.props).length || t.lost.length) { out.push(row ? row.key : (obj.name || runner.kindOf(obj))); }
+        });
+        return out;
+    }
+
+    /** The camera pose the runner's camera declares (poseFields), or null with no camera. */
+    function _cameraPose(runner) {
+        var cam = runner.cameraControl;
+        if (!cam || typeof cam.getOrbit !== 'function' || !Array.isArray(cam.poseFields)) { return null; }
+        var orbit = cam.getOrbit() || {};
+        var pose = {};
+        cam.poseFields.forEach(function (f) { if (orbit[f.name] !== undefined) { pose[f.name] = _plain(orbit[f.name]); } });
+        return pose;
+    }
+
+    /**
+     * exp.setDeclared(name, patch) → Promise<{ set, from, to, tick: 0, kept, files }> — change
+     * an `inParts` object's declaration and re-run the scene IN THIS DOCUMENT. `patch` keys must be writable fields
+     * of the kind's descriptor and each value must pass the descriptor's own validator (ObjectSchema.normalizeValue);
+     * otherwise it refuses (throws) naming the key. The held text is patched (patchParts `set`), then the one restart
+     * door (runner.restart → the retained replay re-links the held text) re-runs it: the seed (the sketch's own
+     * createScene/createCanvas) and the camera pose (captured through the camera's poseFields, re-applied through
+     * 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).
+     */
+    RecipeContext.prototype.setDeclared = async function (name, patch) {
+        _requireWorld(this);
+        _requireHeld(this, 'setDeclared');
+        var runner = this._runner;
+        var obj = null;
+        this._parts.forEach(function (row, o) { if (row.key === name) { obj = o; } });
+        if (!obj || runner.declared.indexOf(obj) === -1) {
+            throw new Error('[RecipeContext.setDeclared] "' + name + '" is not an object of this sketch\'s `parts` block' +
+                (this._code.size ? ' (code declarations: ' + Array.from(this._code.keys()).map(function (o) { return o.name; }).join(', ') +
+                    ' — ' + OUTSIDE_PARTS + ')' : '') + '. (FAIL-LOUD.)');
+        }
+        if (!patch || typeof patch !== 'object' || Array.isArray(patch) || !Object.keys(patch).length) {
+            throw new TypeError('[RecipeContext.setDeclared] patch is { <field>: value, … } with at least one field. (FAIL-LOUD.)');
+        }
+        if (Object.prototype.hasOwnProperty.call(patch, 'name')) {
+            throw new TypeError('[RecipeContext.setDeclared] "name": ' + RENAME + ' (FAIL-LOUD.)');
+        }
+        // A hand made since the last toSketch is not in the held text, and the re-run would drop it without a
+        // word: refuse, naming the object, until the host writes it (a placement and a setDeclared are two changes).
+        var unwritten = _unwrittenHands(this);
+        if (unwritten.length) {
+            throw new Error('[RecipeContext.setDeclared] "' + unwritten.join('", "') + '" carries a hand the sketch text does ' +
+                'not hold yet — write the hand first: await exp.toSketch(). (FAIL-LOUD.)');
+        }
+        var kind = runner.kindOf(obj);
+        var w = _writable(kind);
+        var live = _capture(this, obj);
+        var from = {};
+        Object.keys(patch).forEach(function (k) {
+            if (!w[k]) {
+                throw new TypeError('[RecipeContext.setDeclared] "' + k + '" is not a writable field of ' + kind + ' (writable: ' +
+                    Object.keys(w).join(', ') + '). (FAIL-LOUD.)');
+            }
+            try { ObjectSchema.normalizeValue(w[k], patch[k], kind); }
+            catch (err) {
+                throw new TypeError('[RecipeContext.setDeclared] "' + k + '": ' + String((err && err.message) || err) + ' (FAIL-LOUD.)');
+            }
+            from[k] = live[k] === undefined ? null : live[k];
+        });
+        var entry = this._project.entry;
+        var spelled = _spell(this._project.files[entry], name, kind, _plain(patch), live);
+        var r = patchParts(this._project.files[entry], [{ op: 'set', name: name, props: spelled }], { entry: entry });
+        if (r.refused.length) {
+            throw new Error('[RecipeContext.setDeclared] the sketch text refused the patch: ' +
+                r.refused.map(function (x) { return (x.key ? x.key + ': ' : '') + x.reason; }).join('; ') + ' (FAIL-LOUD.)');
+        }
+        var files = Object.assign({}, this._project.files);
+        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(); }
+        // `kept` is what WAS kept: the seed by construction (the sketch's own co-init cfg); the camera pose only
+        // when one was captured and re-applied (a 2D scene with no pose camera has none).
+        var kept = ['seed'];
+        if (pose && runner.cameraControl && typeof runner.cameraControl.setOrbit === 'function') {
+            runner.cameraControl.setOrbit(pose);
+            kept.push('cameraPose');
+        }
+        return { set: name, from: from, to: _plain(patch), tick: 0, kept: kept, files: Object.assign({}, files) };
+    };
+
     RecipeContext.prototype.addTickFunction = function (fn) {
         _requireWorld(this);
         var fns = this._runner.universe.experimentTickFunctions;
@@ -259,19 +679,41 @@ import { refuseRetiredDoors } from '../compat/engine.js';
      * replay on the runner (`runner.retainSceneReplay`), so `runner.restart()` — and a sketch's
      * declared `restart` control — replays this build on the same runner and canvas.
      */
-    RecipeContext.prototype.build = function (buildFn) {
-        if (buildFn && typeof buildFn === 'function') {
-            this._buildFn = buildFn;
+    RecipeContext.prototype.build = function (sketch) {
+        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.)');
+            }
+            linked = sketch;
+            sketch = linked.buildExperiment;
+        } else if (sketch !== undefined && sketch !== null && typeof sketch !== 'function') {
+            throw new TypeError('[RecipeContext.build] build(sketch): sketch is the scene\'s buildExperiment(exp) function or ' +
+                'linkProject\'s result (got ' + typeof sketch + '). (FAIL-LOUD.)');
+        }
+        if (typeof sketch === 'function') {
+            this._buildFn = sketch;
+            this._project = linked ? linked.project : null;
+            this._urls = linked ? (linked.urls || null) : null;
             if (this._runner) { _teardownSceneForRebuild(this); }
             this._world = null;
-            buildFn(this);
+            this._parts = new Map();
+            this._code = new Map();
+            this._declaredOnce = false;
+            sketch(this);
             if (!this._world) {
                 throw new Error('[RecipeContext.build] the scene never created its world — its first statement ' +
                     'must be ' + COINIT + '. (FAIL-LOUD.)');
             }
             this._built = true;
             var self = this;
-            this._runner.retainSceneReplay(function () { return self.build(self._buildFn); });
+            this._runner.declared.forEach(function (obj) {
+                if (!self._parts.has(obj)) { self._code.set(obj, _capture(self, obj)); }
+            });
+            this._runner.retainSceneReplay(this._project
+                ? function () { return linkProject(self._project).then(function (l) { return self.build(l); }); }
+                : function () { return self.build(self._buildFn); });
         }
         setPageExperiment(this);
         return this;
@@ -298,7 +740,7 @@ import { refuseRetiredDoors } from '../compat/engine.js';
     var RETIRED_RECIPE_DOORS = Object.freeze({
         buildSource: '[RecipeContext] exp.buildSource(src) is retired — a sketch held as text is a project: boot it ' +
             'with bootProject(mount, { files: { "sketch.js": src }, entry: "sketch.js" }) (@descix/frqtl-web/boot), or ' +
-            're-scene a booted facade with exp.build((await linkProject({ files, entry, mint })).buildExperiment) ' +
+            're-scene a booted facade with exp.build(await linkProject({ files, entry, mint })) ' +
             '(lib/shim/project/link.js). (FAIL-LOUD.)'
     });
     refuseRetiredDoors(RecipeContext.prototype, RETIRED_RECIPE_DOORS);