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

package/dist/frqtl/objects/record/Record.js

@@ -0,0 +1,346 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * Record.js — THE live owner of a Record (the sketch-projects design §6): its change rows, its own clock and
+ * its clips. Opened by the facade (`const rec = await exp.startRecord()`, RecipeContext); serialized by the one
+ * writer, lib/shim/project/record-format.js serializeRecordFolder.
+ *
+ *   rec.changes              READ-ONLY: the rows so far, a new deep-frozen copy per read (open or closed).
+ *   rec.tick                 READ-ONLY. The Record's OWN clock: 0 when it opens, +1 per world tick the runner
+ *                            delivers (runner.addTickListener, which survives a rebuild), so it climbs across
+ *                            every re-run inside the Record's world (setDeclared, restart) while the runner's
+ *                            own tick restarts at 0. Every row's tick and every clip span is on this clock.
+ *   await rec.film({ seconds, fps, everyTicks, stage? })
+ *                            ceil(seconds / 10) back-to-back FrqtlVision recordings of equal frame count, each
+ *                            CLIP_SECONDS long; seconds below CLIP_SECONDS.min are refused. Resolves the clip
+ *                            spans it filmed. The host keeps the world ticking (its loop, or a driver).
+ *   await rec.stop()         → { files, record, clips: [{ file, firstTick, lastTick }] } | { empty: true }.
+ *                            REJECTS (the Record stays open): a change and no clip, a change after the last
+ *                            clip ends, a clip still being filmed, any fault recordFolderFaults finds in its
+ *                            own folder.
+ *   rec.closed               a Promise that settles once, when the Record closes: the stop() value plus
+ *                            `closedBy: 'stop'`, or — when the facade's world is re-authored (a build of
+ *                            text that is not the held text) — the folder of the world before, with
+ *                            `closedBy: 'reauthor'` (rejected when that folder is refused, as stop() is).
+ *                            Both carry `droppedClips`: the clips still filming when the Record closed, which
+ *                            the close drops (0 on a stop, which refuses while a clip films); a refused
+ *                            re-author close carries it as err.droppedClips beside err.closedBy.
+ *                            A refused close nobody READ (the getter records the read) makes the facade's
+ *                            next exp.startRecord() reject, naming it.
+ *   err.record               every rejection of stop() and of `closed` carries { changes, clips } — the
+ *                            Record's rows and clip spans — so a host can name them unheld instead of losing them.
+ *
+ * `closedBy`, `droppedClips` and the clip spans are the host's (a lab's own `filmed` list); record.json never
+ * carries them.
+ *
+ * An act (toSketch, setDeclared, fork) is ADMITTED only while the Record is open and not stopping (`_admit`, asked
+ * before the act changes the held text): an act during an async stop() is refused naming "stopping", and the
+ * held text is unchanged.
+ *
+ * WHERE ITS PARTS COME FROM — nothing here captures a second time:
+ *   rows    the writer's own edits at act end (RecipeContext.toSketch / setDeclared call `_row`); only what
+ *           was WRITTEN makes a row;
+ *   clips   every FrqtlVision.record on this runner while the Record is open (FrqtlVision asks
+ *           `openRecordOf(runner)` and hands the recording to `_clipFor`); a recording whose frames / fps
+ *           falls outside CLIP_SECONDS is refused before it is encoded;
+ *   parts   parts.before / parts.after = linkProject(held text).module.parts at open / at close, each kind
+ *           by the name the kinds registry resolves (kindNamed);
+ *   project the held files at close, under project/.
+ */
+
+import { FrqtlVision } from '../../parts/FrqtlVision.js';
+import { linkProject } from '../../../shim/project/link.js';
+import { serializeRecordFolder, CLIP_SECONDS, BY, CHANGE_KEYS } from '../../../shim/project/record-format.js';
+import { kindNamed } from '../kinds.js';
+import { _setOpenRecord, openRecordOf } from './open-record.js';
+
+function _fail(msg) {
+    throw new Error('[Record] ' + msg + ' (FAIL-LOUD.)');
+}
+
+function _bytesOfBase64(b64) {
+    var bin = atob(b64);
+    var out = new Uint8Array(bin.length);
+    for (var i = 0; i < bin.length; i++) { out[i] = bin.charCodeAt(i); }
+    return out;
+}
+
+/** linkProject(held).module.parts → { name: [registered kind name, props] } in key order. */
+async function _partsOf(held) {
+    var linked = await linkProject(held);
+    var parts = linked.module && linked.module.parts;
+    if (!parts || typeof parts !== 'object') {
+        _fail('the held sketch exports no `parts` block — a Record writes parts.before/after from `export const parts`.');
+    }
+    var out = {};
+    Object.keys(parts).forEach(function (name) {
+        var e = parts[name];
+        var Kind = Array.isArray(e) ? e[0] : null;
+        if (typeof Kind !== 'function') { _fail('parts.' + name + ' carries no kind class.'); }
+        kindNamed(Kind.name);   // the name the registry resolves (THROWS naming an unregistered kind)
+        out[name] = [Kind.name, e[1]];
+    });
+    return out;
+}
+
+/** The held project's files, copied (text values). */
+function _heldFiles(held) {
+    return Object.assign({}, held.files);
+}
+
+/**
+ * @param {object} exp — the RecipeContext that opens it (its runner and its held project)
+ * @private — construct through exp.startRecord()
+ */
+function Record(exp) {
+    var self = this;
+    this._exp = exp;
+    this._runner = exp.runner;
+    this._tick = 0;
+    this._rows = [];
+    this._clips = [];
+    this._inflight = 0;
+    this._open = true;
+    this._stopping = false;
+    this._filmArm = null;
+    this._before = null;
+    this._closedSettle = null;
+    this._closedRead = false;
+    this._refused = null;
+    this._closed = new Promise(function (resolve, reject) { self._closedSettle = { resolve: resolve, reject: reject }; });
+    // Observed here so node does not crash on an unhandled rejection; a refused close nobody read is LOUD at the next
+    // act instead (RecipeContext.startRecord refuses until `rec.closed` has been read).
+    this._closed.then(null, function () {});
+    this._settled = this._closed.then(function () {}, function () {});
+    this._onTick = function () { self._tick += 1; };
+    this._off = this._runner.addTickListener(this._onTick);
+    _setOpenRecord(this._runner, this);
+}
+
+Object.defineProperty(Record.prototype, 'tick', { get: function () { return this._tick; } });
+/** A deep-frozen copy. */
+function _frozen(v) {
+    if (v === null || typeof v !== 'object') { return v; }
+    var o = Array.isArray(v) ? v.map(_frozen) : Object.keys(v).reduce(function (a, k) { a[k] = _frozen(v[k]); return a; }, {});
+    return Object.freeze(o);
+}
+/**
+ * rec.changes — the rows so far, a NEW deep-frozen copy per read (record.json's `changes` vocabulary), on an open or a
+ * closed Record. One act's rows: `const n = rec.changes.length; await exp.toSketch({ by }); rec.changes.slice(n)`.
+ */
+Object.defineProperty(Record.prototype, 'changes', { get: function () {
+    return _frozen(this._rows.map(function (r) { var o = {}; CHANGE_KEYS.forEach(function (k) { o[k] = r[k]; }); return o; }));
+} });
+/** rec.closed — reading it records that the host has heard how the Record closed. */
+Object.defineProperty(Record.prototype, 'closed', { get: function () { this._closedRead = true; return this._closed; } });
+
+/** Attach what the Record holds to a refusal — `err.record = { changes, clips }` — so a host can name it unheld. */
+Record.prototype._carry = function (err) {
+    var e = (err instanceof Error) ? err : new Error(String(err));
+    e.record = {
+        changes: this._rows.map(function (r) { return JSON.parse(JSON.stringify(r)); }),
+        clips: this._clips.map(function (c) { return { firstTick: c.firstTick, lastTick: c.lastTick }; })
+    };
+    return e;
+};
+
+/** Read parts.before (the held text at open). @private */
+Record.prototype._ready = async function (held) {
+    this._held = held;
+    this._before = await _partsOf(held);
+    return this;
+};
+
+/** Throws unless `by` is one of BY (while a Record is open, every act names who acted). */
+Record.requireBy = function (by, where) {
+    if (BY.indexOf(by) === -1) {
+        throw new TypeError('[' + where + '] a Record is open: the act names who acted — { by: ' + BY.map(function (b) {
+            return JSON.stringify(b); }).join(' | ') + ' } (record-format.js BY); got ' + JSON.stringify(by) + '. (FAIL-LOUD.)');
+    }
+    return by;
+};
+
+/**
+ * THE admission check: an act may write into this Record only while it is open and not stopping. The facade asks
+ * it BEFORE an act changes the held text (toSketch, setDeclared, fork), and `_row` asks it again: one predicate.
+ * @private
+ */
+Record.prototype._admit = function (where) {
+    var at = where ? where + ': ' : '';
+    if (!this._open) { _fail(at + 'this Record is closed — no row is written into it.'); }
+    if (this._stopping) { _fail(at + 'this Record is stopping — an act during stop() belongs to the next Record.'); }
+};
+
+/** One change row, at the Record's current tick, in the order acted. @private */
+Record.prototype._row = function (row) {
+    this._admit();
+    this._rows.push({ tick: this._tick, name: row.name, op: row.op, by: row.by, from: row.from, to: row.to });
+};
+
+/**
+ * The clip hook. FrqtlVision calls it with the normalized record() request, BEFORE it subscribes; it THROWS
+ * when the request cannot be a CLIP_SECONDS clip, and otherwise returns the recording's session:
+ *   sample(i)        called as frame i is sampled (inside the tick fan-out), reads this Record's tick
+ *   check(frames)    called before the encoder is finalized; THROWS outside CLIP_SECONDS
+ *   end(envelope)    the encoded clip joins the Record (ignored once the Record is closed)
+ *   drop()           the recording failed
+ * @private
+ */
+Record.prototype._clipFor = function (req) {
+    var self = this;
+    var span = CLIP_SECONDS.min + '–' + CLIP_SECONDS.max + ' s';
+    var advice = 'film inside an open Record with rec.film({ seconds, fps, everyTicks }), or record ' + span +
+        ' (frames / fps) per clip';
+    var planned = null;
+    if (req.stopAt.ticks !== undefined) { planned = Math.min(req.maxFrames, Math.floor(req.stopAt.ticks / req.everyTicks) + 1); }
+    var bound = planned === null ? req.maxFrames : planned;
+    var secs = function (n) { return n / req.fps; };
+    if ((planned !== null && (secs(planned) < CLIP_SECONDS.min || secs(planned) > CLIP_SECONDS.max)) ||
+        (planned === null && secs(bound) < CLIP_SECONDS.min)) {
+        _fail('a Record is open on this runner, so this recording is one of its clips, and a clip is ' + span +
+            ' long: this one is ' + (planned !== null ? secs(planned) : 'at most ' + secs(bound)) + ' s (' + bound +
+            ' frames at ' + req.fps + ' fps) — ' + advice + '.');
+    }
+    var arm = this._filmArm;
+    this._filmArm = null;
+    var ticks = [];
+    var done = false;
+    this._inflight += 1;
+    function settle() { if (!done) { done = true; self._inflight -= 1; } }
+    return {
+        sample: function (i) {
+            ticks[i] = self._tick;
+            if (arm && i === req.maxFrames - 1) { var next = arm.onLast; arm = null; next(); }
+        },
+        check: function (frames) {
+            if (secs(frames) < CLIP_SECONDS.min || secs(frames) > CLIP_SECONDS.max) {
+                settle();
+                _fail('a Record is open on this runner, so this recording is one of its clips, and a clip is ' + span +
+                    ' long: this one stopped at ' + secs(frames) + ' s (' + frames + ' frames at ' + req.fps + ' fps) — ' + advice + '.');
+            }
+        },
+        end: function (env) {
+            settle();
+            if (!self._open) { return; }
+            var n = env.track.frames.length;
+            self._clips.push({ bytes: _bytesOfBase64(env.encoded.bytes), firstTick: ticks[0], lastTick: ticks[n - 1] });
+        },
+        drop: function () { settle(); }
+    };
+};
+
+/**
+ * rec.film({ seconds, fps, everyTicks, stage? }) → Promise<[{ file?, firstTick, lastTick }]> — ceil(seconds/10)
+ * back-to-back segments of equal frame count. Each segment's recording is started INSIDE the previous one's last
+ * sampled tick (the tick fan-out dispatches a snapshot, so the next subscription fires from the next tick): the
+ * segments are contiguous on the world's clock whatever drives it. REFUSES: seconds below CLIP_SECONDS.min, a
+ * seconds × fps that does not split into equal whole-frame segments.
+ */
+Record.prototype.film = function (opts) {
+    var self = this;
+    try {
+        if (!this._open) { _fail('this Record is closed — open the next one (exp.startRecord()) to film.'); }
+        if (!opts || typeof opts !== 'object') { _fail('rec.film({ seconds, fps, everyTicks, stage? })'); }
+        Object.keys(opts).forEach(function (k) {
+            if (['seconds', 'fps', 'everyTicks', 'stage'].indexOf(k) === -1) { _fail('rec.film takes { seconds, fps, everyTicks, stage? }, not "' + k + '".'); }
+        });
+        var s = opts.seconds, fps = opts.fps, every = opts.everyTicks;
+        if (typeof s !== 'number' || !isFinite(s) || s < CLIP_SECONDS.min) {
+            _fail('rec.film: seconds is at least ' + CLIP_SECONDS.min + ' (CLIP_SECONDS), got ' + JSON.stringify(s) + '.');
+        }
+        if (!Number.isInteger(fps) || fps < 1) { _fail('rec.film: fps is a whole number ≥ 1 (the playback rate), got ' + JSON.stringify(fps) + '.'); }
+        if (!Number.isInteger(every) || every < 1) { _fail('rec.film: everyTicks is a whole number ≥ 1 (the capture cadence in ticks), got ' + JSON.stringify(every) + '.'); }
+        var n = Math.ceil(s / CLIP_SECONDS.max);
+        var total = s * fps;
+        if (!Number.isInteger(total) || total % n !== 0) {
+            _fail('rec.film: ' + s + ' s at ' + fps + ' fps is ' + total + ' frames, which does not split into ' + n +
+                ' equal whole-frame segments of at most ' + CLIP_SECONDS.max + ' s — choose seconds × fps divisible by ' + n + '.');
+        }
+        var f = total / n;
+        var req = { everyTicks: every, fps: fps, maxFrames: f, stopAt: { ticks: (f - 1) * every } };
+        if (opts.stage !== undefined) { req.stage = opts.stage; }
+        var vision = FrqtlVision.attach(this._runner);
+        var first = this._clips.length;
+        // One deferred per segment: segment k+1 exists once segment k sampled its last frame.
+        var segs = [];
+        for (var k = 0; k < n; k++) {
+            (function () { var d = {}; d.promise = new Promise(function (res, rej) { d.resolve = res; d.reject = rej; }); segs.push(d); })();
+        }
+        var started = [];
+        var start = function (k) {
+            started[k] = true;
+            self._filmArm = (k < n - 1) ? { onLast: function () { start(k + 1); } } : null;
+            var p = vision.record(req);
+            segs[k].resolve(p);
+            p.then(function () {
+                if (k + 1 < n && !started[k + 1]) {
+                    segs[k + 1].reject(new Error('[Record.film] segment ' + (k + 1) + ' of ' + n + ' ended without sampling its last frame, ' +
+                        'so segment ' + (k + 2) + ' never started. (FAIL-LOUD.)'));
+                }
+            }, function (e) {
+                self._filmArm = null;
+                for (var j = k + 1; j < n; j++) { if (!started[j]) { started[j] = true; segs[j].reject(e); } }
+            });
+        };
+        start(0);
+        return Promise.all(segs.map(function (d) { return d.promise; })).then(function () {
+            return self._clips.slice(first).map(function (c) { return { firstTick: c.firstTick, lastTick: c.lastTick }; });
+        });
+    } catch (e) { return Promise.reject(e); }
+};
+
+/** Serialize this Record's folder from `held` (the files it snapshots). @private */
+Record.prototype._folder = async function (held) {
+    var after = await _partsOf(held);
+    return serializeRecordFolder({
+        changes: this._rows.slice(), clips: this._clips.slice(),
+        partsBefore: this._before, partsAfter: after, project: _heldFiles(held)
+    });
+};
+
+/** Detach from the world (no row, tick or clip after this). @private */
+Record.prototype._detach = function () {
+    this._open = false;
+    if (this._off) { this._off(); this._off = null; }
+    _setOpenRecord(this._runner, null);
+    this._exp._record = null;
+};
+
+/** rec.stop() — see the module docstring. */
+Record.prototype.stop = async function () {
+    var self = this;
+    var refuse = function (msg) { try { _fail(msg); } catch (e) { throw self._carry(e); } };
+    if (!this._open) { refuse('this Record is already closed' + (this._closedBy ? ' (closedBy: ' + this._closedBy + ')' : '') + ' — read rec.closed.'); }
+    if (this._stopping) { refuse('stop() is already running.'); }
+    if (this._inflight) { refuse(this._inflight + ' clip(s) are still being filmed — await rec.film (or the record()) before stop().'); }
+    this._stopping = true;
+    var out;
+    try { out = await this._folder(this._exp._project); }
+    catch (e) { throw this._carry(e); }
+    finally { this._stopping = false; }
+    this._closedBy = 'stop';
+    this._detach();
+    this._closedSettle.resolve(Object.assign({}, out, { closedBy: 'stop', droppedClips: 0 }));
+    return out;
+};
+
+/**
+ * The facade re-authors its world: close with the folder of the world BEFORE (`held` = the held project before
+ * the build). Synchronous detach; the folder settles `closed`. @private
+ */
+Record.prototype._closeOnReauthor = function (held) {
+    var self = this;
+    var dropped = this._inflight;   // clips still filming: detaching drops them (their end() finds the Record closed)
+    this._closedBy = 'reauthor';
+    this._detach();
+    this._folder(held).then(function (out) {
+        self._closedSettle.resolve(Object.assign({}, out, { closedBy: 'reauthor', droppedClips: dropped }));
+    }, function (e) {
+        self._refused = self._carry(e);
+        self._refused.closedBy = 'reauthor';
+        self._refused.droppedClips = dropped;
+        self._closedSettle.reject(self._refused);
+    });
+};
+
+export { Record, openRecordOf };

package/dist/frqtl/objects/record/open-record.js

@@ -0,0 +1,22 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * open-record.js — which Record is open on a runner: the ONE store FrqtlVision asks (its clip hook) and the
+ * Record writes. One open Record per runner; a second open is refused by the facade (RecipeContext.startRecord).
+ *
+ *   openRecordOf(runner) → Record | null
+ */
+
+var _open = new WeakMap();
+
+/** @param {object} runner @returns {object|null} the Record open on it */
+function openRecordOf(runner) {
+    return (runner && _open.get(runner)) || null;
+}
+
+/** @private — Record.js only */
+function _setOpenRecord(runner, rec) {
+    if (rec) { _open.set(runner, rec); } else { _open.delete(runner); }
+}
+
+export { openRecordOf, _setOpenRecord };

package/dist/frqtl/objects/schema/engine-scopes.js

@@ -94,7 +94,7 @@ import * as FrameDataSchema from '../../../shim/frame-data/index.js';
                 engineVisible: true,
                 description: 'Frame center Z position (depth, physics pixels). ' +
                     'Default 0.0 when active_axes.z is false (2D mode). ' +
-                    'Bite 3 (ws-3d-discrete-walk): set by the 3D emitter; moved by the ' +
+                    'Set by the 3D emitter; moved by the ' +
                     'independent z yo-yo coin when active_axes.z is true. ' +
                     'Cube edge = w (spec §11 — no separate d field; cubes only).'
             },
@@ -322,7 +322,7 @@ import * as FrameDataSchema from '../../../shim/frame-data/index.js';
                 engineVisible: true,
                 description: 'Derived (scope-read): frame CENTER Z before this tick\'s move() ' +
                     '(physics pixels). Default 0.0 when active_axes.z is false. ' +
-                    'Bite 3 (ws-3d-discrete-walk): saved by Frame::move_frame alongside prev_x/prev_y. ' +
+                    'Saved by Frame::move_frame alongside prev_x/prev_y. ' +
                     'Read-only — write THROWS (engine-owned per-tick snapshot).'
             },
             // ── Forbidden: engine-owned topology ──────────────────────────────

package/dist/frqtl/objects/schema/scopes.js

@@ -273,7 +273,7 @@ export function shapeValuesMap() {
                 // existing scene is byte-identical. A live edit (updateObjectProperty) sets the
                 // per-instance override that _visibleLargeObjects reads.
                 description: 'When this object\'s visual shell renders (render-only): design = only ' +
-                    'while authoring (Bite-4b marker default); run = always visible (the "red light ' +
+                    'while authoring (the marker default); run = always visible (the "red light ' +
                     'bulb" opt-in); never = hidden. Generalizes the design-only marker suppression ' +
                     'at the single _visibleLargeObjects authority; engine collision is unaffected.'
             },
@@ -322,7 +322,7 @@ export function shapeValuesMap() {
                 // designer control — the raw JSON must never render in the STUDIO Inspector.
                 // `internal:true` is the ONE authority for "hide from the designer surface"
                 // (consumed by makeControlsForObject + AuthorView's renderInspector); the
-                // program is still engineVisible + captured for codegen/round-trip.
+                // program is still engineVisible + captured (the parts writer's round trip).
                 internal: true,
                 description: 'Op-program attached to this LO (§10.3 SLICE 3). ' +
                     'Shape: { on: "collision"|"tick", ops: [{ set: "<handle>.<prop>", to: ExprAST }] }. ' +

package/dist/frqtl/objects/setup/_worldInit.js

@@ -23,8 +23,7 @@
      *
      * The list is derived from what `initArgs()` below ACTUALLY reads. `interQuantumCollisions`
      * is in it because it is still ACCEPTED (inert — it fed a removed positional slot) and
-     * STUDIO codegen prints it into every saved recipe: dropping it from the vocabulary
-     * would make every saved scene throw.
+     * saved scenes carry it: dropping it from the vocabulary would make them throw.
      *
      * @type {Array<{key:string, effect:string}>}
      */

package/dist/frqtl/objects/setup/setupBlackbodySubstrate.js

@@ -34,8 +34,7 @@
  *   — as `lib/frqtl/scenes/blackbody.js` sets it.  ENGINE physics; no new
  *   op-programs.  Expected JS↔WASM divergence on parent-frame count (deferred §6).
  *
- * Set any flag to `false` only for progressive test isolation (L1/L2/L3 runs in
- * `experiments/blackbody-substrate/run.js`).  The default (all true) runs the
+ * Set any flag to `false` only for progressive test isolation (L1/L2/L3 runs).  The default (all true) runs the
  * scene's flags (brownian on, inter-quantum collisions on).
  *
  * ## Thermostat control loop (as-intended §2.1, Dispatch C2)

package/dist/frqtl/parts/CameraControls.js

@@ -177,6 +177,12 @@ import * as OrbitBag from '../compat/renderer/orbit-bag.js';
         if (mountEl && mountEl.__frqtlCameraHandle && mountEl.__frqtlCameraHandle.mounted) {
             return mountEl.__frqtlCameraHandle;
         }
+        // ...and per RUNNER: one runner has one camera controller. A host that mounted the pads before the scene
+        // could (STUDIO: the sizeless page builds before its runner has a control host), then a re-run in the same
+        // document (a fork, setDeclared) that reaches the scene's own attach with another container, gets the live one.
+        if (runner.__frqtlCameraHandle && runner.__frqtlCameraHandle.mounted) {
+            return runner.__frqtlCameraHandle;
+        }
 
         var doc = (mountEl && mountEl.ownerDocument) ? mountEl.ownerDocument
                 : (typeof document !== 'undefined' ? document : null);
@@ -581,6 +587,7 @@ import * as OrbitBag from '../compat/renderer/orbit-bag.js';
                 if (mountEl && mountEl.__frqtlCameraHandle === liveHandle) {
                     mountEl.__frqtlCameraHandle = null;
                 }
+                if (runner.__frqtlCameraHandle === liveHandle) { runner.__frqtlCameraHandle = null; }
                 if (rafId !== null) { cAF(rafId); rafId = null; }
                 // Force-release any in-flight joystick drag (detaches its doc listeners).
                 for (var i = 0; i < padCleanups.length; i++) {
@@ -617,6 +624,7 @@ import * as OrbitBag from '../compat/renderer/orbit-bag.js';
         };
         // F4: mark the container as owning this live instance (idempotency guard above).
         if (mountEl) { mountEl.__frqtlCameraHandle = liveHandle; }
+        runner.__frqtlCameraHandle = liveHandle;
         return liveHandle;
     }
 

package/dist/frqtl/parts/DetectorWall.js

@@ -111,7 +111,7 @@ import { registerKind } from '../objects/kinds.js';
         var depth = (opts.depth !== undefined && opts.depth !== null) ? opts.depth : null;
 
         this.universe = universe;
-        this._schemaKind = 'DetectorWall';
+        this._schemaKind = this.constructor.name;
 
         // The world rect, through the ONE normalizer (a zero-high detector counts nothing
         // and would report it as physics — so a missing dimension throws, never zeroes).

package/dist/frqtl/parts/FrqtlVision.js

@@ -183,6 +183,7 @@ import * as CaptureEnvelope from '../../shim/render/capture-envelope.js';
 import { CameraPath } from './CameraPath.js';
 import { FrqtlCaptureHost } from '../objects/instruments/capture-host.js';
 import { vendorUrl } from '../compat/vendor.js';
+import { openRecordOf } from '../objects/record/open-record.js';
 
 function _rgba8Format(RS) { return RS.STAGE_FORMATS[RS.finalStage()]; }
 
@@ -574,16 +575,24 @@ function _record(runner, RS, opts) {
             'localhost). The encoder is not optional — there is no second path');
     }
 
+    // THE CLIP HOOK: while a Record is open on this runner, every recording is one of its clips. The Record
+    // refuses a request that cannot be a CLIP_SECONDS clip (before anything subscribes) and keeps the clip's
+    // ticks and bytes; this recorder holds no Record state of its own (objects/record/Record.js _clipFor).
+    var openRec = openRecordOf(runner);
+    var clip = openRec ? openRec._clipFor(req) : null;
+
     // Everything that can THROW synchronously happens BEFORE the sampler subscribes: a
     // CameraPath refused at attach (no pose control, an undeclared pose field) must not leave
     // a subscribed sampler holding the clock behind a rejection nobody can reach.
     var path = null;
     if (req.stopAt.path) {
-        path = CameraPath.attach(runner, {
-            waypoints: req.stopAt.path.waypoints,
-            loop: !!req.stopAt.path.loop,
-            waypointTimeoutMs: req.stopAt.path.waypointTimeoutMs
-        });
+        try {
+            path = CameraPath.attach(runner, {
+                waypoints: req.stopAt.path.waypoints,
+                loop: !!req.stopAt.path.loop,
+                waypointTimeoutMs: req.stopAt.path.waypointTimeoutMs
+            });
+        } catch (e) { if (clip) { clip.drop(); } throw e; }
     }
     var frames = [];
     var inflight = [];
@@ -628,6 +637,7 @@ function _record(runner, RS, opts) {
                 _fail('record', 'the recording stopped before a single still was captured — nothing to ' +
                     'encode. Is the runner advancing ticks?');
             }
+            if (clip) { clip.check(frames.length); }
             return encodeChain;
         }).then(function (enc) {
             return enc.output.finalize().then(function () { return enc.output.getMimeType(); })
@@ -654,7 +664,11 @@ function _record(runner, RS, opts) {
                         truncated: truncated
                     });
                 });
-        }).then(settle.resolve, function (e) {
+        }).then(function (env) {
+            if (clip) { clip.end(env); }
+            settle.resolve(env);
+        }, function (e) {
+            if (clip) { clip.drop(); }
             encoderReady.then(function (enc) { return enc.output.cancel(); }).then(null, function () {});
             settle.reject(e);
         });
@@ -670,6 +684,7 @@ function _record(runner, RS, opts) {
             return true;
         },
         onStill: function (p, i) {
+            if (clip) { clip.sample(i); }
             var handled = p.then(function (still) {
                 if (i === 0) {
                     scene = still.scene;

package/dist/frqtl/parts/GraphingDetectorWall.js

@@ -24,8 +24,8 @@
  * so every Wall option, live method and property accessor applies verbatim.
  * When neither `preset` nor `collisionBehavior` is supplied it defaults to the
  * `detector-screen` preset (destroy + count) — the counting authority. Extra
- * options, all DECLARED descriptor fields (so a codegen Restart round-trip
- * rebuilds the heatmap wall from captured state — the W2 declared-field rule):
+ * options, all DECLARED descriptor fields (so the parts writer captures them and the
+ * sketch rebuilds the heatmap wall from that state — the W2 declared-field rule):
  *
  *   @param {number} [opts.binPx=12]     — face bin size in physics pixels. Bins
  *     are anchored at the FACE ORIGIN (its top / near-z corner), so the map runs
@@ -105,7 +105,7 @@ import { registerKind, kindOf } from '../objects/kinds.js';
      * painting of the only spatial information a 2D scene carries.
      *
      * @param {Array|Object} rect — the LO rect ([l,t,w,h] / [l,t,z,w,h,d] /
-     *   {left,top,w,h[,z,d]} — the shape a codegen round-trip captures).
+     *   {left,top,w,h[,z,d]} — the shape a live LO's rect reads as).
      * @param {number} binPx
      * @returns {{top:number,height:number,z0:number,depth:number,binPx:number,
      *            canvasW:number,canvasH:number}}
@@ -248,9 +248,9 @@ import { registerKind, kindOf } from '../objects/kinds.js';
             opts = merged;
         }
         WallCls.call(this, universe, opts);
-        this._schemaKind = 'GraphingDetectorWall';
+        this._schemaKind = this.constructor.name;
 
-        // Declared heatmap fields (own props → codegen captureProps round-trip).
+        // Declared heatmap fields (own props → the parts writer's captureProps).
         this.binPx     = _num(opts.binPx, 12);
         this.refreshMs = _num(opts.refreshMs, 100);
         this.heatBase  = _num(opts.heatBase, 0.35);
@@ -399,8 +399,8 @@ import { registerKind, kindOf } from '../objects/kinds.js';
      *
      * FIELDS ARE FERRIED FROM WallDescriptor (never re-listed — the
      * schema-mirror-drift discipline): this descriptor is Wall's field table plus
-     * the three heatmap fields. Every one is a DECLARED field, so a codegen
-     * Restart round-trip rebuilds the heatmap wall from captured state.
+     * the three heatmap fields. Every one is a DECLARED field, so the parts writer
+     * captures it and the sketch rebuilds the heatmap wall from that state.
      */
     var WallDescriptor = kindOf(WallCls).descriptor;
     var GraphingDetectorWallDescriptor = {

package/dist/frqtl/parts/LargeObject.js

@@ -35,7 +35,7 @@ import { SCOPE_DESCRIPTORS } from '../objects/schema/scopes.js';
      * Build a LargeObject `.rect` for the 2D (4-element) case: a REAL Rectangle instance
      * (is_centered=false) so a center write (`.x`/`.y`) auto-recomputes left/top and vice
      * versa (PR-1 — audit item 3). A non-enumerable `toJSON` is attached so JSON-serializing
-     * consumers (codegen `_jsonCopy`, bundle export, save-state) still produce the SAME plain
+     * consumers (bundle export, save-state, any JSON copy) still produce the SAME plain
      * `{left,top,w,h}` shape they always did — the Rectangle's own enumerable fields are
      * `_left/_x/...`, which WOULD drift; `toJSON` pins the wire shape. (`left/top/w/h` are read
      * via getters by every direct consumer, so those are unaffected.) 6-element z/d rects are
@@ -128,7 +128,7 @@ import { SCOPE_DESCRIPTORS } from '../objects/schema/scopes.js';
         collectCollided = collectCollided || false;
 
         this.universe = universe;
-        this._schemaKind = 'LargeObject';
+        this._schemaKind = this.constructor.name;
         // rect is [left, top, w, h] (legacy) or [left, top, z, w, h, d] (FRQTL-MAINT
         // 2026-07-01, explicit z/depth) — is_centered=false convention either way.
         var ra = rectToArray(rect);

package/dist/frqtl/parts/LiveChart.js

@@ -267,8 +267,8 @@ import { registerKind } from '../objects/kinds.js';
             };
             // Mirror the SERIALIZABLE chartSpec fields onto the LO under their DESCRIPTOR
             // names (restart-bug fix, 2026-07-25): captureProps(lo, LiveChartDescriptor)
-            // reads lo[field.name], so without these mirrors a codegen round-trip (Save /
-            // Restart evals the generated module) silently rebuilt every chart UNBOUND
+            // reads lo[field.name], so without these mirrors a captured chart (the parts writer's
+            // capture of a declared chart) would rebuild UNBOUND
             // with default projector/label ("detector"). The name string — never the live
             // sourceHandle — is the captured source (re-resolved here on rebuild).
             lo.source    = sourceName;

package/dist/frqtl/parts/LogicGate.js

@@ -219,7 +219,7 @@ import { registerKind } from '../objects/kinds.js';
     function LogicGate(universe, opts) {
         opts = opts || {};
         this.universe = universe;
-        this._schemaKind = 'LogicGate';
+        this._schemaKind = this.constructor.name;
 
         var TunnelCls = _Tunnel;
         var WallCls = _Wall;
@@ -705,8 +705,8 @@ import { registerKind } from '../objects/kinds.js';
             var gate = new GateCls(ctx.runner.universe, opts);
             gate._schemaKind = Class.name;
             // The comparator is a HOST tick-fn: subscribe it to the runner's per-tick
-            // fan-out here, off the DECLARED fields, so the switching survives
-            // codegen → Restart (a recipe-authored tick-fn would be lost). Idempotent.
+            // fan-out here, off the DECLARED fields, so the switching belongs to the declared
+            // object: every build of it (a sketch entry, a Restart) re-wires it. Idempotent.
             if (typeof gate.attachToRunner === 'function') { gate.attachToRunner(ctx.runner); }
             return gate;
         }

package/dist/frqtl/parts/OvenBox.js

@@ -199,7 +199,7 @@ import { registerKind } from '../objects/kinds.js';
         options = options || {};
 
         this.universe = universe;
-        this._schemaKind = 'OvenBox';
+        this._schemaKind = this.constructor.name;
         this.name = options.name || 'oven';   // its declared name (the Tunnel/LogicGate idiom)
         this.temperature = options.temperature || 300;
 

package/dist/frqtl/parts/PointSource.js

@@ -169,7 +169,7 @@ import { declaredCount } from '../objects/ObjectFactory.js';
         var zDepth = opts.zDepth !== undefined ? opts.zDepth : null;
 
         this.universe = universe;
-        this._schemaKind = 'PointSource';
+        this._schemaKind = this.constructor.name;
         this.x = x;
         this.y = y;
         this.diameter = diameter;