@descix/frqtl-node 0.6.1-p3.2 → 0.6.1-p3.3

package/dist/frqtl/compat/renderer/providers/three-provider.js

@@ -258,6 +258,13 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
                 description: "What the god-rays are computed from: 'leaf' = the fundamental-layer frames " +
                     "(LOs only occlude), 'all' = the whole lit scene (every frame of every layer and every LO)."
             }),
+            normalizeFieldDescriptor({
+                name: 'godrayMode', type: 'enum', default: GodraysLayer.GODRAY_MODE_DEFAULT,
+                constraint: { values: GodraysLayer.GODRAY_MODES.reduce(function (m, v) { m[v] = v; return m; }, {}) },
+                description: "How the god-rays are computed: 'streak' = each source frame trails a streak behind " +
+                    "its direction of travel, 'field' = each pixel marches along the local direction of travel, " +
+                    "'radial' = each pixel marches toward one light point (the source frames' centroid)."
+            }),
             normalizeFieldDescriptor({
                 name: 'glowIntensity', type: 'number', unit: 'intensity', default: 0,
                 constraint: { min: 0, max: 3, integer: false },
@@ -614,6 +621,9 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
         // ── R4-B god-rays layer (GodraysLayer.makeGodrayPasses; created lazily on first activation) ──
         var _godrays = null;
         var _cubeSourceCount = 0;      // cube instances [0, n) are god-rays source frames
+        // The particle objects LAID this tick but hidden from the lit picture (Particles OFF while
+        // god rays consume the particle layer): the source pass shows them, the lit scene never does.
+        var _particlesLaidHidden = [];
 
         var _initialized = false;
         var _lastTickData = null;
@@ -1260,14 +1270,14 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
         // Position one clone of the loaded mesh per frame (reusing a pool). The loaded scene is
         // unit-normalized; each clone is scaled to the frame's voxel size (w) and placed at the
         // frame's (x,y,z) — the SAME physics coords the cube/points paths use. Extra clones hide.
-        function _layoutMeshClones(entry, frameData, drawParticles, scaleMul, assetId) {
+        function _layoutMeshClones(entry, frameData, lay, scaleMul, assetId) {
             if (!_meshGroup) { _meshGroup = new THREE.Group(); _meshGroup.frustumCulled = false; _scene.add(_meshGroup); }
             // Per-ASSET clone sub-pool (spec §2): one pool per asset id so concurrent assets never
             // fight over slots. Callers: the scene-wide useMesh branch (assetId = resolvedMesh) and
             // the per-frame mesh siphon in the Points path (one call per stamped asset).
             var pool = _meshClonesByAsset[assetId] || (_meshClonesByAsset[assetId] = []);
             var mul = (typeof scaleMul === 'number' && scaleMul > 0) ? scaleMul : 1;
-            var n = (drawParticles && frameData) ? frameData.length : 0;
+            var n = (lay && frameData) ? frameData.length : 0;
             for (var i = 0; i < n; i++) {
                 var f = frameData[i];
                 var clone = pool[i];
@@ -1491,10 +1501,19 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
 
         // The god-rays SOURCE image → _godrays.rtSource: same scene/camera/paint, ONLY the fundamental-layer
         // frames drawn. LOs write depth but no colour (they shadow, never shine). All flags restored.
-        function _renderGodraySource(tickData) {
+        function _renderGodraySource(tickData, leaf) {
             var gs = GodraysLayer, fund = gs.fundamentalLayerOf(tickData);
             var hidden = [], cubeCount = null, colourOff = [];
             function hide(o) { if (o && o.visible) { o.visible = false; hidden.push(o); } }
+            // The rays read the PARTICLE LAYER whether or not the lit picture draws it.
+            for (var p = 0; p < _particlesLaidHidden.length; p++) { _particlesLaidHidden[p].visible = true; }
+            if (!leaf) {
+                // 'all': the lit scene WITH its particles (only reached when Particles are OFF).
+                _renderer.setRenderTarget(_godrays.rtSource);
+                _renderer.render(_scene, _camera);
+                for (var pa = 0; pa < _particlesLaidHidden.length; pa++) { _particlesLaidHidden[pa].visible = false; }
+                return;
+            }
             for (var k in _dimLayers) {
                 if (_dimLayers.hasOwnProperty(k) && !gs.isGodraySource(_dimLayers[k].layer, fund)) { hide(_dimLayers[k].mesh); }
             }
@@ -1522,19 +1541,36 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
             for (var h = 0; h < hidden.length; h++) { hidden[h].visible = true; }
             if (cubeCount !== null) { _cubeMesh.count = cubeCount; }
             for (var c = 0; c < colourOff.length; c++) { colourOff[c].colorWrite = true; }
+            for (var q = 0; q < _particlesLaidHidden.length; q++) { _particlesLaidHidden[q].visible = false; }
         }
 
-        // God-rays to screen: the march reads the SOURCE image (fundamental-layer frames, LOs
-        // depth-only) and adds its rays over the full lit scene. Cost paid ONLY when on.
-        // `godraySource` 'all' marches the lit scene itself (every frame, every LO).
+        // Are god rays on? THE one predicate: the final composite dispatch and the particle-layer
+        // gate (rays consume the particle layer as their source) both ask it.
+        function _wantGodrays(opts) { return opts.godrays > 0; }
+
+        // God-rays to screen: the rays read the SOURCE image (fundamental-layer frames, LOs
+        // depth-only) and add over the full lit scene. Cost paid ONLY when on.
+        // `godraySource` 'all' reads the lit scene itself (every frame, every LO); `godrayMode`
+        // picks the pass (GodraysLayer owns both values and defaults).
         function _renderGodrays(opts, tickData) {
             var gl = GodraysLayer, leaf = gl.resolveGodraySource(opts.godraySource) === 'leaf';
+            var mode = gl.resolveGodrayMode(opts.godrayMode);
             if (!_godrays) { _godrays = gl.makeGodrayPasses(THREE, QUAD_VERT, _physW(), _physH()); }
             _renderer.setRenderTarget(_rtA);                 // Pass 1: lit scene → _rtA
             _renderer.render(_scene, _camera);
-            if (leaf) { _renderGodraySource(tickData); }     // Pass 1b: source → rtSource
-            _godrays.march(_renderer, _quadCamera, _rtA, leaf ? _godrays.rtSource : _rtA, _rtB,
-                _godrays.lightUV(tickData, _camera, opts.godraySource), opts.godrayDensity, opts.godrays);
+            // Pass 1b: source → rtSource. 'leaf' always; 'all' only when the lit scene lacks its
+            // particles (Particles OFF) — otherwise the lit scene IS the 'all' source.
+            var ownSource = leaf || _particlesLaidHidden.length > 0;
+            if (ownSource) { _renderGodraySource(tickData, leaf); }
+            var src = ownSource ? _godrays.rtSource : _rtA;
+            if (mode === 'radial') {
+                _godrays.march(_renderer, _quadCamera, _rtA, src, _rtB,
+                    _godrays.lightUV(tickData, _camera, opts.godraySource), opts.godrayDensity, opts.godrays);
+            } else {
+                var pass = (mode === 'streak') ? _godrays.streak : _godrays.field;
+                pass(_renderer, _quadCamera, _rtA, src, _rtB,
+                    gl.godraySourceFrames(tickData, opts.godraySource), _camera, opts.godrayDensity, opts.godrays);
+            }
         }
 
         // ── Aim feedback layer update ─────────────────────────────────────────────────
@@ -1729,7 +1765,10 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
             // built ONLY when a consumer (a queued filter) is active — never unconditionally (that was one sugar object hijacking the
             // render loop). Each flag comes from the render OPTIONS bag (setRenderOption).
             var opts          = options || {};
-            var drawParticles = opts.renderBaseCanvas !== false;          // Particles layer
+            var drawParticles = opts.renderBaseCanvas !== false;          // Particles layer (the lit picture)
+            // The particle layer is LAID when drawn OR consumed: god rays read it as their source,
+            // so Particles OFF + god rays ON lays it out hidden and the rays still shine.
+            var layParticles  = drawParticles || _wantGodrays(opts);
             // SNAPSHOT, not the reference: _renderOptsWithFeedback() returns
             // this._renderOptions ITSELF when there is no aim-feedback bag, so retaining
             // `opts` would let a setRenderOption between ticks silently change what
@@ -1783,7 +1822,7 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
                 var _me = _meshCache[resolvedMesh];
                 var _sceneLaid = 0;
                 if (_me && _me.status === 'ready') {
-                    _sceneLaid = _layoutMeshClones(_me, tickData.frameData, opts.renderBaseCanvas !== false, opts.meshScale, resolvedMesh);
+                    _sceneLaid = _layoutMeshClones(_me, tickData.frameData, layParticles, opts.meshScale, resolvedMesh);
                 }
                 _hideMeshClonesExcept([resolvedMesh]);           // drop any stale per-frame/other-asset clones
                 if (_meshGroup) { _meshGroup.visible = _sceneLaid > 0; }   // loading/empty → hidden (error already overlaid)
@@ -1795,7 +1834,7 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
                 // bright; back/bottom are dark — so the cube reads as a solid 3D object.
                 _hideAllDimLayers();
 
-                if (drawParticles && tickData && tickData.frameData) {
+                if (layParticles && tickData && tickData.frameData) {
                     var fdC = tickData.frameData;
                     var totalC = fdC.length;
                     var defaultColorSchemeC = opts.colorScheme || 'warmcool';
@@ -1847,7 +1886,7 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
                     _cubeMesh.count = cubeCount;
                     _cubeMesh.instanceMatrix.needsUpdate = true;
                     if (_cubeMesh.instanceColor) { _cubeMesh.instanceColor.needsUpdate = true; }
-                    _cubeMesh.visible = drawParticles && cubeCount > 0;
+                    _cubeMesh.visible = cubeCount > 0;
                 } else {
                     if (_cubeMesh) { _cubeMesh.visible = false; }
                 }
@@ -1858,7 +1897,7 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
                 if (_cubeMesh) { _cubeMesh.visible = false; }
                 _hideAllDimLayers();
 
-                if (drawParticles && tickData && tickData.frameData) {
+                if (layParticles && tickData && tickData.frameData) {
                     var fd = tickData.frameData;
                     var total = fd.length;
 
@@ -2039,7 +2078,7 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
                         }
 
                         entry.centroid.x = cx / n; entry.centroid.y = cy / n; entry.centroid.z = cz / n;
-                        entry.mesh.visible = drawParticles;
+                        entry.mesh.visible = true;
                     }
 
                     // ── Camera-distance sort (painter's algorithm) — farthest
@@ -2070,7 +2109,7 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
                         _ensureMeshLoaded(_aid);
                         var _pfMe = _meshCache[_aid];
                         if (_pfMe && _pfMe.status === 'ready') {
-                            _pfMeshLaid += _layoutMeshClones(_pfMe, meshByAsset[_aid], drawParticles, opts.meshScale, _aid);
+                            _pfMeshLaid += _layoutMeshClones(_pfMe, meshByAsset[_aid], layParticles, opts.meshScale, _aid);
                         }
                     }
                     _hideMeshClonesExcept(_pfMeshAssets);
@@ -2078,6 +2117,16 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
                 }
             }
 
+            // ── Particles OFF: what was laid (for the god-rays source) leaves the lit picture ──
+            _particlesLaidHidden = [];
+            if (!drawParticles) {
+                var laid = [_cubeMesh, _meshGroup];
+                for (var lk in _dimLayers) { if (_dimLayers.hasOwnProperty(lk)) { laid.push(_dimLayers[lk].mesh); } }
+                for (var li = 0; li < laid.length; li++) {
+                    if (laid[li] && laid[li].visible) { laid[li].visible = false; _particlesLaidHidden.push(laid[li]); }
+                }
+            }
+
             // ── Field layer — build the heightfield ONLY when consumed ──
             if (fieldConsumed) { _updateFieldTex(tickData); }
 
@@ -2098,7 +2147,7 @@ import * as ThreeCameraGeometry from './three-camera-geometry.js';
             opts = opts || {};
             // godrays is a final-composite layer (a declared render option). It owns the final pass when on; it and the 2D water-fx
             // filter are alternative final composites (concurrent use is a phase-2 item).
-            var wantGodrays = opts.godrays > 0;
+            var wantGodrays = _wantGodrays(opts);
             var time = _filters.length > 0
                 ? RendererProviderContract.filterTime(tickData) : null;
             _lastFilterTime = time;   // capture provenance (§1a.4)

package/dist/frqtl/objects/FrqtlApp.js

@@ -2010,6 +2010,19 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
         return [x, y];
     };
 
+    /**
+     * isPointable(d) → whether declared object `d` can be under a pointer on the canvas: at least one of
+     * its members is not hidden by its own `visible:false`. The ONE rule both canvas picks read — the 3D
+     * pick below (per member) and the host's 2D box hit-test (per object).
+     */
+    FrqtlApp.prototype.isPointable = function (d) {
+        var ms = this.membersOf(d);
+        for (var i = 0; i < ms.length; i++) { if (_memberPointable(ms[i])) { return true; } }
+        return false;
+    };
+    /** A member is under the pointer unless its own `visible:false` hides it. */
+    function _memberPointable(lo) { return lo.visible !== false; }
+
     /** Screen radius (in the caller's screen units) inside which a click picks an object. */
     FrqtlApp.PICK_RADIUS_PX = 32;
     /** A center-bearing (drivable) object's pick distance is divided by this, so in a dense scene
@@ -2024,7 +2037,9 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
      * anisotropic on screen and different per plane, which let a wall behind the emitter win inside
      * the emitter's own footprint. A drivable object's distance is divided by PICK_DRIVE_PRIORITY.
      * Objects-layer; consumed downward by AuthorView. Null (fail-soft) with no screenToWorld
-     * capability — the host falls back to the Layers panel.
+     * capability — the host falls back to the Layers panel. A member its own `visible:false` hides
+     * is never under the pointer (isPointable): an invisible counter spanning the scene would
+     * otherwise answer every press. The Layers panel still selects it.
      */
     FrqtlApp.prototype.pickObjectAtScreen = function (cssX, cssY, cssW, cssH) {
         var r = this.renderer;
@@ -2035,6 +2050,7 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
             var lo = los[i];
             var owner = this.declaredOf(lo);
             if (!owner) { continue; }   // a primitive-surface object is never picked
+            if (!_memberPointable(lo)) { continue; }   // hidden: not under the pointer (isPointable)
             var c = this._objectCentroid(lo);
             if (!c) { continue; }
             var sp = this.screenPointOf(c, cssW, cssH, [cssX, cssY]);

package/dist/frqtl/objects/RecipeContext.js

@@ -53,6 +53,9 @@
  *   - 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.sceneExports              the named exports of the scene module the last build linked (its module
+ *                                 namespace — the module that built this world, never a second evaluation);
+ *                                 reading it THROWS when the scene was built from a function, which has none
  *   exp.is3D                      world.renderer === 'three'
  *
  * FAIL-LOUD: every member that needs the world THROWS before the call; a second call in one
@@ -126,6 +129,7 @@ import { Record, openRecordOf } from './record/Record.js';
         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._module  = null;   // the entry module's namespace, from the last link (exp.sceneExports)
         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;
@@ -148,6 +152,18 @@ import { Record, openRecordOf } from './record/Record.js';
     Object.defineProperty(RecipeContext.prototype, 'is3D', {
         get: function () { _requireWorld(this); return this._world.renderer === 'three'; }
     });
+    /** READ-ONLY: the named exports of the scene module the last build linked (the module that built this world). */
+    Object.defineProperty(RecipeContext.prototype, 'sceneExports', {
+        get: function () {
+            _requireWorld(this);
+            if (!this._module) {
+                throw new Error('[RecipeContext] sceneExports: this world was built from a buildExperiment function, ' +
+                    'not a linked scene module, so it has no module exports to read — build it from its text: ' +
+                    'exp.build(await linkProject({ files, entry, mint })) (lib/shim/project/link.js). (FAIL-LOUD.)');
+            }
+            return this._module;
+        }
+    });
 
     // ── the co-init call ─────────────────────────────────────────────────────────────
 
@@ -893,6 +909,7 @@ import { Record, openRecordOf } from './record/Record.js';
             this._buildFn = sketch;
             this._project = linked ? linked.project : null;
             this._urls = linked ? (linked.urls || null) : null;
+            this._module = linked ? linked.module : null;
             if (this._runner) { _teardownSceneForRebuild(this); }
             this._world = null;
             this._parts = new Map();

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

@@ -53,18 +53,12 @@ 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';
+import { base64ToBytes } from '../../../shim/render/capture-envelope.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);
@@ -223,7 +217,7 @@ Record.prototype._clipFor = function (req) {
             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] });
+            self._clips.push({ bytes: base64ToBytes(env.encoded.bytes), firstTick: ticks[0], lastTick: ticks[n - 1] });
         },
         drop: function () { settle(); }
     };
@@ -257,7 +251,8 @@ Record.prototype.film = function (opts) {
                 ' 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 } };
+        var b = FrqtlVision.recordBudget(f, every);
+        var req = { everyTicks: every, fps: fps, maxFrames: b.maxFrames, stopAt: b.stopAt };
         if (opts.stage !== undefined) { req.stage = opts.stage; }
         var vision = FrqtlVision.attach(this._runner);
         var first = this._clips.length;

package/dist/frqtl/parts/FrqtlVision.js

@@ -37,8 +37,10 @@
  *     getScene():Promise<object>,        // the run-invariant SceneRecord + its content id
  *     getStill(stage?):Promise<object>,  // stage omitted → the FULL composed stack
  *     getStream({stage?, everyTicks}):AsyncIterable<object>,   // stills at a TICK cadence
- *     record({everyTicks, stopAt, maxFrames, fps, stage?, bitrate?, keyFrameInterval?, signal?})
+ *     record({seconds?, fps?, signal?})  // THE DEFAULT: up to 60 s of what the viewer sees, wall-clock timed
  *         :Promise<object>,              // an encoded video: CaptureEnvelope.videoEnvelope
+ *     record({everyTicks, stopAt, maxFrames, fps, stage?, bitrate?, keyFrameInterval?, signal?})
+ *         :Promise<object>,              // the ADVANCED tick-sampling form (corpus rows, flights)
  *     stages:string[],                   // the FERRIED RenderStages.RENDER_STAGES list
  *     finalStage():string,               // the ferried final-stage derivation
  *     toDataURL(still):string,           // the BROWSER PNG encoder (data URL)
@@ -165,8 +167,12 @@
  *   var still  = await vision.getStill();         // the whole composed stack
  *   var field  = await vision.getStill('field');  // the render-free numeric channel
  *
- *   // A video: 1 still per 2 ticks until tick 600, played back at 30 fps.
- *   var env = await vision.record({ everyTicks: 2, stopAt: { tick: 600 }, maxFrames: 400, fps: 30 });
+ *   // A video of what the viewer sees (the default form): up to 60 s at 30 fps; Stop = abort.
+ *   var stop = new AbortController();
+ *   var env = await vision.record({ seconds: 20, signal: stop.signal });
+ *
+ *   // ADVANCED — tick sampling: 1 still per 2 ticks until tick 600, played back at 30 fps.
+ *   var env2 = await vision.record({ everyTicks: 2, stopAt: { tick: 600 }, maxFrames: 400, fps: 30 });
  *
  *   // Aligned multi-channel corpus row: capture BETWEEN ticks and assert equal tick stamps —
  *   // the tick equality IS the co-registration guard; `scene` ties them to one header.
@@ -462,33 +468,43 @@ function _getStream(runner, RS, opts) {
 }
 
 /** The recorder's declared options. @private */
-var RECORD_OPTIONS = ['everyTicks', 'stopAt', 'maxFrames', 'fps', 'stage', 'bitrate', 'keyFrameInterval', 'signal'];
+var RECORD_OPTIONS = ['seconds', 'everyTicks', 'stopAt', 'maxFrames', 'fps', 'stage', 'bitrate', 'keyFrameInterval', 'signal'];
+/** The keys only the advanced TICK form takes; any of them selects it. @private */
+var TICK_FORM_KEYS = ['everyTicks', 'stopAt', 'maxFrames'];
+/**
+ * The default — HUMAN — form's defaults and cap: a recording of what the viewer sees, `seconds` long (at most
+ * RECORD_DEFAULTS.seconds), played back at `fps`.
+ */
+var RECORD_DEFAULTS = Object.freeze({ seconds: 60, fps: 30 });
+var HUMAN_SHAPE = '{seconds?, fps?, signal?, stage?, bitrate?, keyFrameInterval?} (the default: seconds of what the viewer sees)';
+var TICK_SHAPE = '{everyTicks, stopAt, maxFrames, fps, stage?, bitrate?, keyFrameInterval?, signal?} (the advanced tick-sampling form)';
 var STOP_AT_FORMS = ['tick', 'ticks', 'path'];
 var PATH_OPTIONS = ['waypoints', 'loop', 'waypointTimeoutMs'];
 
-/** Validate a record() request; returns the normalized request. @private */
-function _normalizeRecord(RS, opts) {
-    var who = 'record';
-    if (!opts || typeof opts !== 'object') {
-        _fail(who, 'expected {everyTicks, stopAt, maxFrames, fps, stage?, bitrate?, keyFrameInterval?, signal?}, got ' + String(opts));
-    }
-    _assertKnownKeys(opts, RECORD_OPTIONS, 'record', who);
-    var req = {
-        everyTicks: _requirePosInt(opts.everyTicks, 'everyTicks (the capture cadence in TICKS — there is no wall-clock cadence)', who),
-        maxFrames:  _requirePosInt(opts.maxFrames, 'maxFrames (the memory bound; hitting it reports truncated:true)', who),
-        fps:        _requirePosInt(opts.fps, 'fps (the PLAYBACK rate — it has no physical meaning)', who),
-        stage:      (opts.stage === undefined) ? RS.finalStage() : RS.assertStage(opts.stage),
-        bitrate:    (opts.bitrate === undefined) ? null : _requirePosInt(opts.bitrate, 'bitrate (bits per second)', who),
-        keyFrameInterval: (opts.keyFrameInterval === undefined) ? 1
-            : _requirePosInt(opts.keyFrameInterval, 'keyFrameInterval (frames)', who),
-        stopAt: null,
-        signal: null
-    };
+/**
+ * THE length budget of a recording (one owner: the human form and Record.film both take it): `frames` pictures at
+ * `everyTicks` end `(frames − 1) × everyTicks` ticks after the first capture, ON the last picture — so reaching the
+ * end is truncated:false (a stop at `frames × everyTicks` would ask for one picture past the bound and report a
+ * truncation). The math of maxi-record.js::segmentTicks.
+ * @param {number} frames
+ * @param {number} everyTicks
+ * @returns {{maxFrames:number, stopAt:{ticks:number}}}
+ */
+function recordBudget(frames, everyTicks) {
+    return { maxFrames: frames, stopAt: { ticks: (frames - 1) * everyTicks } };
+}
+
+/** The stage/signal/encoder options both forms share, validated once. @private */
+function _sharedRecordOptions(RS, opts, req, who) {
+    req.stage = (opts.stage === undefined) ? RS.finalStage() : RS.assertStage(opts.stage);
+    req.bitrate = (opts.bitrate === undefined) ? null : _requirePosInt(opts.bitrate, 'bitrate (bits per second)', who);
+    req.keyFrameInterval = (opts.keyFrameInterval === undefined) ? 1 : _requirePosInt(opts.keyFrameInterval, 'keyFrameInterval (frames)', who);
+    req.signal = null;
     if (opts.signal !== undefined) {
         var sig = opts.signal;
         if (!sig || typeof sig.aborted !== 'boolean' || typeof sig.addEventListener !== 'function') {
             _fail(who, 'signal must be an AbortSignal (new AbortController().signal) — it is how a recording ' +
-                'stops before its stopAt; got ' + String(sig));
+                'stops before its end; got ' + String(sig));
         }
         req.signal = sig;
     }
@@ -498,6 +514,92 @@ function _normalizeRecord(RS, opts) {
             'plausible-looking movie of nothing. Read the numbers with getStream({stage: ' +
             JSON.stringify(req.stage) + ', everyTicks})');
     }
+    return req;
+}
+
+/**
+ * recordRefusal(runner) → null when the default (human) form of record() can start on this runner NOW, else
+ * `{ reason, message }`: reason 'paused' (no tick will arrive to film) or 'rate-unmeasured' (runner.getRates().tps is
+ * not yet a positive number — FrqtlApp resets it on every start and reports after its first second running). The ONE
+ * owner of when the default form refuses: record() fails with `message`, and a host that offers a Record control
+ * enables it on `null` (reading this on the live runner, never a polled copy of its rates).
+ * @param {object} runner
+ * @returns {null|{reason:string, message:string}}
+ */
+function recordRefusal(runner) {
+    if (!runner || typeof runner.getRates !== 'function') {
+        throw new TypeError('[FrqtlVision] recordRefusal(runner): runner is a live FrqtlApp (it reads isRunning and getRates()). (FAIL-LOUD.)');
+    }
+    if (!runner.isRunning) {
+        return { reason: 'paused', message: 'the world is paused, so no tick will arrive to film (a recording samples by ' +
+            'TICK, never by the clock) — resume first' };
+    }
+    var tps = runner.getRates().tps;
+    if (typeof tps !== 'number' || !isFinite(tps) || tps <= 0) {
+        return { reason: 'rate-unmeasured', message: 'the runner has not measured its tick rate yet (runner.getRates().tps = ' +
+            String(tps) + '; it reports after its first second running), and the default form samples at most fps pictures ' +
+            'a second of it. Record once it has run a second, or name the cadence with the tick form ' + TICK_SHAPE };
+    }
+    return null;
+}
+
+/** The HUMAN form: {seconds?, fps?} — the tick cadence is derived from the live runner when recording starts. @private */
+function _normalizeHumanRecord(RS, opts, who) {
+    var req = {
+        form: 'human',
+        seconds: (opts.seconds === undefined) ? RECORD_DEFAULTS.seconds : _requirePosInt(opts.seconds, 'seconds (playback seconds)', who),
+        fps: (opts.fps === undefined) ? RECORD_DEFAULTS.fps : _requirePosInt(opts.fps, 'fps (the PLAYBACK rate)', who),
+        everyTicks: null, stopAt: null, maxFrames: null
+    };
+    if (req.seconds > RECORD_DEFAULTS.seconds) {
+        _fail(who, 'seconds ' + req.seconds + ' is over the cap of ' + RECORD_DEFAULTS.seconds + ' s (the recording is held ' +
+            'in memory until it ends). A longer capture is the tick form: ' + TICK_SHAPE);
+    }
+    return _sharedRecordOptions(RS, opts, req, who);
+}
+
+/**
+ * The human form's request, from the LIVE runner when recording starts. Its TIME is the wall clock: every picture is
+ * stamped with its wall-clock time since the first one (_record), and the recording ends on its own once `seconds` of
+ * wall clock have been filmed — so the file lasts as long as the viewer watched, whatever the tick rate does while
+ * recording (a 1:1-locked scene slows when the recorder draws). The cadence is only a SAMPLING-RATE CEILING: the runner
+ * ticks `tps` a second (its own measured rate, runner.getRates().tps), and sampling every
+ * everyTicks = max(1, ceil(tps / fps)) ticks never films faster than `fps` at that rate (round or floor would, and a
+ * picture closer than 1/fps to the last one has to be pushed later than its wall time). The memory bound is
+ * recordBudget(seconds × fps, everyTicks).maxFrames; reaching it (the scene sped up) is truncated:true. @private
+ */
+function _deriveHumanRecord(runner, req) {
+    var refusal = recordRefusal(runner);
+    if (refusal) { _fail('record', refusal.message); }
+    var tps = runner.getRates().tps;
+    req.everyTicks = Math.max(1, Math.ceil(tps / req.fps));
+    req.maxFrames = recordBudget(req.seconds * req.fps, req.everyTicks).maxFrames;
+    req.stopAt = {};   // no tick stop: the wall clock ends it (_record)
+    return req;
+}
+
+/** Validate a record() request; returns the normalized request. @private */
+function _normalizeRecord(RS, opts) {
+    var who = 'record';
+    if (opts === undefined) { opts = {}; }
+    if (!opts || typeof opts !== 'object') {
+        _fail(who, 'expected ' + HUMAN_SHAPE + ' or ' + TICK_SHAPE + ', got ' + String(opts));
+    }
+    _assertKnownKeys(opts, RECORD_OPTIONS, 'record', who);
+    var tickKeys = TICK_FORM_KEYS.filter(function (k) { return opts[k] !== undefined; });
+    if (opts.seconds !== undefined && tickKeys.length) {
+        _fail(who, 'a call mixes the two shapes (seconds with ' + tickKeys.join(', ') + '). Pass EITHER ' + HUMAN_SHAPE +
+            ' OR ' + TICK_SHAPE);
+    }
+    if (!tickKeys.length) { return _normalizeHumanRecord(RS, opts, who); }
+    var req = {
+        form: 'tick',
+        everyTicks: _requirePosInt(opts.everyTicks, 'everyTicks (the capture cadence in TICKS — there is no wall-clock cadence)', who),
+        maxFrames:  _requirePosInt(opts.maxFrames, 'maxFrames (the memory bound; hitting it reports truncated:true)', who),
+        fps:        _requirePosInt(opts.fps, 'fps (the PLAYBACK rate — it has no physical meaning)', who),
+        stopAt: null
+    };
+    _sharedRecordOptions(RS, opts, req, who);
     var s = opts.stopAt;
     if (!s || typeof s !== 'object') {
         _fail(who, 'stopAt is REQUIRED — exactly one of {tick: T}, {ticks: K}, {path: {waypoints, loop?, ' +
@@ -575,6 +677,8 @@ function _record(runner, RS, opts) {
             'localhost). The encoder is not optional — there is no second path');
     }
 
+    if (req.form === 'human') { _deriveHumanRecord(runner, req); }
+
     // 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).
@@ -600,6 +704,12 @@ function _record(runner, RS, opts) {
     var closing = false;
     var failure = null;
     var stopTick = (req.stopAt.tick !== undefined) ? req.stopAt.tick : null;
+    // The human form's clock: picture i's wall time since picture 0 as a SLOT of the 1/fps grid the muxer writes
+    // (whole numbers, so two pictures can never share a slot: a picture landing in or before the last one's slot
+    // takes the next), and whether it is the last one the `seconds` of wall clock admit.
+    var human = (req.form === 'human');
+    var wallT0 = null;
+    var slotOf = [];
     var session = null;
     var onAbort = null;
     var dims = null;
@@ -685,6 +795,14 @@ function _record(runner, RS, opts) {
         },
         onStill: function (p, i) {
             if (clip) { clip.sample(i); }
+            var lastByWall = false;
+            if (human) {
+                var now = performance.now();
+                if (i === 0) { wallT0 = now; }
+                var slot = Math.round((now - wallT0) / 1000 * req.fps);
+                slotOf[i] = (i === 0) ? 0 : Math.max(slot, slotOf[i - 1] + 1);
+                lastByWall = slotOf[i] + 1 >= req.seconds * req.fps;
+            }
             var handled = p.then(function (still) {
                 if (i === 0) {
                     scene = still.scene;
@@ -699,7 +817,7 @@ function _record(runner, RS, opts) {
                 encodeChain = encodeChain.then(function (enc) {
                     var sample = new enc.MB.VideoSample(still.data, {
                         format: 'RGBA', codedWidth: still.width, codedHeight: still.height,
-                        timestamp: i / req.fps, duration: 1 / req.fps
+                        timestamp: (human ? slotOf[i] : i) / req.fps, duration: 1 / req.fps
                     });
                     return Promise.resolve(enc.source.add(sample)).then(function () {
                         sample.close();
@@ -709,6 +827,7 @@ function _record(runner, RS, opts) {
                 // Handled at close; a rejected encode must not surface as unhandled meanwhile.
                 encodeChain.then(null, function (e) { close(e); });
                 if (stopTick !== null && still.tick + req.everyTicks > stopTick) { close(null); }
+                if (lastByWall) { close(null); }
             }, function (e) { close(e); });
             inflight.push(handled);
             return handled;
@@ -787,8 +906,19 @@ function attach(runner) {
          */
         getStream: function (opts) { return _getStream(runner, RS, opts); },
         /**
-         * record(opts) → Promise<VideoEnvelope> — sample like `getStream`, encode an MP4.
+         * record(opts?) → Promise<VideoEnvelope> — film what the viewer sees, encode an MP4.
+         *
+         * THE DEFAULT (human) FORM — record({seconds?, fps?, signal?, stage?, bitrate?, keyFrameInterval?}):
+         *   seconds           default and cap RECORD_DEFAULTS.seconds (60) — the recording ends on its own
+         *                     after this many seconds of WALL CLOCK (truncated:false)
+         *   fps               default RECORD_DEFAULTS.fps (30) — the most pictures a second it films
+         *   signal            an AbortSignal: abort is Stop — what was filmed, truncated:true
+         * Each picture is stamped with its wall-clock time since the first, so the file lasts as long as the
+         * viewer watched whatever the tick rate does; picture i is NOT tick i / fps in this form (the tick form
+         * keeps that). Refused on a paused runner, or before the runner has measured its rate (FrqtlVision.recordRefusal).
          *
+         * THE ADVANCED (tick) FORM — any of everyTicks/stopAt/maxFrames selects it; mixing it with
+         * `seconds` throws naming both shapes:
          *   everyTicks        REQUIRED — capture cadence in TICKS (sampling starts at the first
          *                     tick after this call, then every `everyTicks`)
          *   stopAt            REQUIRED — exactly one of `{tick: T}` (absolute, inclusive),
@@ -798,7 +928,7 @@ function attach(runner) {
          *                     waypoint)
          *   maxFrames         REQUIRED — the memory bound; reaching it before `stopAt` stops the
          *                     recording and reports `truncated: true`
-         *   fps               REQUIRED — PLAYBACK rate only; frame i is timestamped i/fps
+         *   fps               REQUIRED — PLAYBACK rate only; frame i is timestamped i/fps (tick-exact timing)
          *   stage             default `finalStage()`; must be an rgba8 stage
          *   signal            an AbortSignal: abort ends the recording early with the stills
          *                     captured so far and `truncated: true` (rejects if none yet)
@@ -823,7 +953,8 @@ function attach(runner) {
 
 // ── Export ────────────────────────────────────────────────────────────────────
 
-var FrqtlVision = { attach: attach, toDataURL: toDataURL, toPNG: toPNG };
+var FrqtlVision = { attach: attach, toDataURL: toDataURL, toPNG: toPNG, RECORD_DEFAULTS: RECORD_DEFAULTS, recordBudget: recordBudget,
+                    recordRefusal: recordRefusal };
 
 // The capture-host KIND's in-page recorder is THIS face: registered here, so capture-host
 // never names FrqtlVision (the import runs one way: FrqtlVision → capture-host).

package/dist/frqtl/parts/LiveChart.js

@@ -76,7 +76,7 @@ import { registerKind } from '../objects/kinds.js';
             'source fails loud.',
         // STUDIO UX: a chart panel has a real draggable/resizable extent, and it is
         // VISIBLE during Run (its whole point), so shellRender:'run' (NOT a Design-only
-        // marker). 2D drag; 3D reposition via the camera.
+        // marker).
         ux: {
             resizable: true,
             draggable: { '2d': true },

package/dist/frqtl/parts/SphereEmitter.js

@@ -617,8 +617,8 @@ import { CollisionTypes } from './CollisionTypes.js';
         // UX_DRAGGABLE_MODES / UX_SHELL_RENDER); this block is read via
         // ObjectSchema.ux('SphereEmitter'). resizable:false — a SphereEmitter has
         // TWO radii (inner+outer); a single-box resize gesture is ambiguous, so
-        // it is NOT resizable (individually, per object). draggable 2D (a 3D
-        // scene never cursor-drags). handles: ['move'] — it only moves, never scales.
+        // it is NOT resizable (individually, per object). handles: ['move'] — the
+        // Hand only moves it (2D and 3D), never scales it.
         // shellRender:'design' — the marker paints only while authoring (the
         // default; the "red light bulb" flips a per-instance shellRender override).
         ux: {

package/dist/frqtl/parts/Tunnel.js

@@ -800,7 +800,7 @@ import { setupTunnelPointExit } from '../objects/setup/setupTunnelPointExit.js';
             'reflects off the two facing mirrors and stays collimated (no random scatter, ' +
             'no leak through the walls). The group is the single author-surface entity; ' +
             'the two mirror Walls it composes carry its `_owner` up-link. Zero physics of its own.',
-        // A tunnel has a genuine draggable/resizable extent (like a Wall). 2D drag only.
+        // A tunnel has a genuine draggable/resizable extent (like a Wall).
         ux: {
             resizable: true,
             draggable: { '2d': true },