@descix/frqtl-web 0.6.1-p3.3 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/CLAUDE.md +11 -13
  2. package/LICENSE.md +63 -79
  3. package/README.md +7 -9
  4. package/dist/artifact/double-slit.html +1 -1
  5. package/dist/dist-manifest.json +37 -42
  6. package/dist/frqtl/compat/providers/wasm-load-browser.js +1 -2
  7. package/dist/frqtl/compat/renderer/providers/godrays-layer.js +12 -301
  8. package/dist/frqtl/compat/renderer/providers/p5-provider.js +0 -6
  9. package/dist/frqtl/compat/renderer/providers/three-provider.js +17 -66
  10. package/dist/frqtl/objects/FrqtlApp.js +1 -17
  11. package/dist/frqtl/objects/RecipeContext.js +41 -38
  12. package/dist/frqtl/objects/objects/QuantumEmitter.js +1 -1
  13. package/dist/frqtl/objects/objects/sustainedSource.js +2 -2
  14. package/dist/frqtl/objects/record/Record.js +9 -4
  15. package/dist/frqtl/objects/setup/setupConeEmitter3D.js +3 -3
  16. package/dist/frqtl/objects/setup/setupSphereEmitter3D.js +6 -8
  17. package/dist/frqtl/parts/FrqtlVision.js +27 -158
  18. package/dist/frqtl/parts/GraphingDetectorWall.js +1 -1
  19. package/dist/frqtl/parts/LiveChart.js +1 -1
  20. package/dist/frqtl/parts/SphereEmitter.js +2 -2
  21. package/dist/frqtl/parts/Tunnel.js +1 -1
  22. package/dist/frqtl/parts/Wall.js +10 -97
  23. package/dist/frqtl/scenes/dse-tunnel-rebuild.js +22 -33
  24. package/dist/frqtl/scenes/mirror-route.js +6 -10
  25. package/dist/frqtl-web.min.js +51 -56
  26. package/dist/notebooks/notebooks.json +1 -1
  27. package/dist/sdk.html +2 -3
  28. package/dist/shim/controls/index.js +2 -2
  29. package/dist/shim/engine/router.js +30 -49
  30. package/dist/shim/field-descriptor/index.js +5 -5
  31. package/dist/shim/host/host-view.js +10 -7
  32. package/dist/shim/host/index.js +1 -2
  33. package/dist/shim/project/index.js +3 -13
  34. package/dist/shim/project/record-format.js +4 -96
  35. package/dist/shim/project/specifiers.js +3 -5
  36. package/dist/shim/registry/exhibits.js +11 -11
  37. package/dist/shim/registry/index.js +0 -6
  38. package/dist/shim/registry/walkthrough.js +90 -38
  39. package/dist/shim/render/capture-envelope.js +0 -21
  40. package/dist/shim/render/sun-look.js +11 -6
  41. package/llms.txt +8 -9
  42. package/package.json +2 -3
  43. package/dist/shim/engine/site-graph.js +0 -184
  44. package/dist/shim/host/device.js +0 -42
  45. package/dist/shim/project/parts-spelling.js +0 -77
  46. package/dist/shim/registry/showcase-link.js +0 -61
  47. package/dist/shim/registry/studio-landing.js +0 -70
@@ -53,9 +53,6 @@
53
53
  * - setDeclared refuses while a hand is unwritten (await exp.toSketch() first); its `kept` lists what it kept.
54
54
  * - restart() of a linked sketch re-links the CURRENT text (the retained replay) and returns a Promise.
55
55
  * exp.runner / .universe the runner the co-init call built
56
- * exp.sceneExports the named exports of the scene module the last build linked (its module
57
- * namespace — the module that built this world, never a second evaluation);
58
- * reading it THROWS when the scene was built from a function, which has none
59
56
  * exp.is3D world.renderer === 'three'
60
57
  *
61
58
  * FAIL-LOUD: every member that needs the world THROWS before the call; a second call in one
@@ -77,7 +74,6 @@ import { ObjectSchema } from './schema/index.js';
77
74
  import { kindOf } from './kinds.js';
78
75
  import { linkProject } from '../../shim/project/link.js';
79
76
  import { patchParts, PARTS_EXPORT, entryKeys, entryLiteral } from '../../shim/project/parts-writer.js';
80
- import { spellRect, spellCenter, captureCenter } from '../../shim/project/parts-spelling.js';
81
77
  import { moduleOfKind, PARTS_SPECIFIER } from '../../shim/project/parts-module.js';
82
78
  import { forkPartText, FORK_REFUSED } from '../../shim/project/fork.js';
83
79
  import { readText } from '../../shim/project/read-text.js';
@@ -129,7 +125,6 @@ import { Record, openRecordOf } from './record/Record.js';
129
125
  this._buildFn = null;
130
126
  this._project = null; // THE held project text: { files: {path: text}, entry, mint, bare? } (build(linked))
131
127
  this._urls = null; // the minted URL of each project file, from the last link
132
- this._module = null; // the entry module's namespace, from the last link (exp.sceneExports)
133
128
  this._parts = new Map(); // declared object → { key, baseline } — the objects in `parts`
134
129
  this._code = new Map(); // declared object → baseline — the code declarations at build end
135
130
  this._declaredOnce = false;
@@ -152,18 +147,6 @@ import { Record, openRecordOf } from './record/Record.js';
152
147
  Object.defineProperty(RecipeContext.prototype, 'is3D', {
153
148
  get: function () { _requireWorld(this); return this._world.renderer === 'three'; }
154
149
  });
155
- /** READ-ONLY: the named exports of the scene module the last build linked (the module that built this world). */
156
- Object.defineProperty(RecipeContext.prototype, 'sceneExports', {
157
- get: function () {
158
- _requireWorld(this);
159
- if (!this._module) {
160
- throw new Error('[RecipeContext] sceneExports: this world was built from a buildExperiment function, ' +
161
- 'not a linked scene module, so it has no module exports to read — build it from its text: ' +
162
- 'exp.build(await linkProject({ files, entry, mint })) (lib/shim/project/link.js). (FAIL-LOUD.)');
163
- }
164
- return this._module;
165
- }
166
- });
167
150
 
168
151
  // ── the co-init call ─────────────────────────────────────────────────────────────
169
152
 
@@ -364,22 +347,47 @@ import { Record, openRecordOf } from './record/Record.js';
364
347
  var _JSON = function (v) { return JSON.stringify(v); };
365
348
 
366
349
  /**
367
- * Spell a touched value in the entry's OWN form, reading the form off the held TEXT: the rule is
368
- * lib/shim/project/parts-spelling.js spellRect / spellCenter (applyRows asks the same rule of a parts block).
369
- * Each mutates and returns `props`.
350
+ * Spell a touched rect in the entry's OWN form (architect z addendum). A 6-tuple rect of a kind whose descriptor
351
+ * derives reads from it (ObjectSchema.derivedReads: Wall `z`, `depth`) is written as the 4-tuple plus each derived
352
+ * key whose value changed, when the entry spells any of those keys as plain properties (entryKeys); otherwise the
353
+ * 6-tuple stands. A 4-tuple equal to the baseline's is not written (no literalizing an untouched expression).
354
+ * Mutates and returns `props`.
370
355
  */
371
356
  function _spell(text, name, kind, props, baseline) {
372
- return spellRect(props, { kind: kind, baseline: baseline, entryKeys: function () { return entryKeys(text, name); } });
357
+ var derived = ObjectSchema.derivedReads(kind);
358
+ if (!derived.length) { return props; }
359
+ var spelled = entryKeys(text, name);
360
+ var R4 = ObjectSchema.RECT_TUPLE[4], R6 = ObjectSchema.RECT_TUPLE[6];
361
+ Object.keys(props).forEach(function (f) {
362
+ var v = props[f];
363
+ var rows = derived.filter(function (d) { return d.field === f && d.tuple === 6 && spelled.indexOf(d.name) !== -1; });
364
+ if (!rows.length || !Array.isArray(v) || v.length !== 6) { return; }
365
+ var b = Array.isArray(baseline[f]) && baseline[f].length === 6 ? baseline[f] : null;
366
+ var four = R4.map(function (k) { return v[R6.indexOf(k)]; });
367
+ if (b && _JSON(four) === _JSON(R4.map(function (k) { return b[R6.indexOf(k)]; }))) { delete props[f]; }
368
+ else { props[f] = four; }
369
+ rows.forEach(function (d) {
370
+ var nv = v[R6.indexOf(d.key)];
371
+ if (!b || nv !== b[R6.indexOf(d.key)]) { props[d.name] = nv; }
372
+ });
373
+ });
374
+ return props;
373
375
  }
374
376
 
377
+ /**
378
+ * Spell a touched `center` in the entry's OWN arity: two numbers when the entry
379
+ * spells two (a literal, or an array expression — entryLiteral's `length`) and the live z is 0; otherwise the
380
+ * live [x, y, z] (an entry spelled three, a 3D hand off z 0, an entry whose center is not an array). The
381
+ * read-back (_verifyWritten) guards every case. Mutates and returns `props`.
382
+ */
375
383
  function _spellCenter(text, name, props) {
376
- return spellCenter(props, {
377
- entryKeys: function () { return entryKeys(text, name); },
378
- centerLength: function () {
379
- var r = entryLiteral(text, name, 'center');
380
- return r.literal ? (Array.isArray(r.value) ? r.value.length : null) : (r.length === undefined ? null : r.length);
381
- }
382
- });
384
+ var v = props.center;
385
+ if (!Array.isArray(v) || v.length !== 3 || v[2] !== 0) { return props; }
386
+ if (entryKeys(text, name).indexOf('center') === -1) { return props; }
387
+ var r = entryLiteral(text, name, 'center');
388
+ var n = r.literal ? (Array.isArray(r.value) ? r.value.length : null) : r.length;
389
+ if (n === 2) { props.center = [v[0], v[1]]; }
390
+ return props;
383
391
  }
384
392
 
385
393
  /**
@@ -395,8 +403,8 @@ import { Record, openRecordOf } from './record/Record.js';
395
403
  Object.keys(written).forEach(function (k) {
396
404
  var r = entryLiteral(text, name, k);
397
405
  decl[k] = r.literal ? r.value : undefined;
398
- // A two-number center declares z 0: read it in its capture form through the one inverse.
399
- if (k === 'center' && Array.isArray(decl[k]) && decl[k].length === 2) { decl[k] = captureCenter(decl[k]); }
406
+ // A two-number center declares z 0 (the reading placeDeclaredAt gives an omitted z).
407
+ if (k === 'center' && Array.isArray(decl[k]) && decl[k].length === 2) { decl[k] = decl[k].concat([0]); }
400
408
  });
401
409
  function refuse(k, declared, liveV) {
402
410
  refused.push({ op: 'set', name: name, key: k, reason: 'the written text declares ' + _JSON(declared) + ' but the live object is ' +
@@ -643,9 +651,8 @@ import { Record, openRecordOf } from './record/Record.js';
643
651
  * `center` patch sets where the entry STARTS. The loop's run state is kept. REFUSES (throws) while a hand
644
652
  * made since the last toSketch is unwritten (write it first: await exp.toSketch()), and a `name` patch (the
645
653
  * key is the name). `from` and `to` are the patched keys' capture (ObjectSchema.captureProps) before and after the
646
- * re-run — one form on both sides (a z-slab wall's rect is 6 numbers even when the patch typed 4). The patch is
647
- * written in the entry's own spelling (a rect beside `z`/`depth` as 4 numbers plus those keys; a `center` in the
648
- * arity the entry spells, three numbers when z is not 0), as a hand's is. With a Record open, its `setDeclared` row carries the same `from`/`to`, written after the re-run.
654
+ * re-run — one form on both sides (a z-slab wall's rect is 6 numbers even when the patch typed 4); the patch as
655
+ * typed is in `files`. With a Record open, its `setDeclared` row carries the same `from`/`to`, written after the re-run.
649
656
  */
650
657
  RecipeContext.prototype.setDeclared = async function (name, patch, opts) {
651
658
  _requireWorld(this);
@@ -689,10 +696,7 @@ import { Record, openRecordOf } from './record/Record.js';
689
696
  from[k] = live[k] === undefined ? null : live[k];
690
697
  });
691
698
  var entry = this._project.entry;
692
- // The patch is written in the entry's own spelling, as a hand's is (toSketch's order: rect, then center).
693
699
  var spelled = _spell(this._project.files[entry], name, kind, _plain(patch), live);
694
- if (Array.isArray(spelled.center)) { spelled.center = captureCenter(spelled.center); }
695
- _spellCenter(this._project.files[entry], name, spelled);
696
700
  var r = patchParts(this._project.files[entry], [{ op: 'set', name: name, props: spelled }], { entry: entry });
697
701
  if (r.refused.length) {
698
702
  throw new Error('[RecipeContext.setDeclared] the sketch text refused the patch: ' +
@@ -712,7 +716,7 @@ import { Record, openRecordOf } from './record/Record.js';
712
716
  runner.cameraControl.setOrbit(pose);
713
717
  kept.push('cameraPose');
714
718
  }
715
- // `to` is what the re-run declared, in the capture form `from` is in (the text holds the entry's spelling).
719
+ // `to` is what the re-run declared, in the capture form `from` is in (the patch as typed is in the text).
716
720
  var rebuilt = null;
717
721
  this._parts.forEach(function (row, o) { if (row.key === name) { rebuilt = o; } });
718
722
  if (!rebuilt) {
@@ -909,7 +913,6 @@ import { Record, openRecordOf } from './record/Record.js';
909
913
  this._buildFn = sketch;
910
914
  this._project = linked ? linked.project : null;
911
915
  this._urls = linked ? (linked.urls || null) : null;
912
- this._module = linked ? linked.module : null;
913
916
  if (this._runner) { _teardownSceneForRebuild(this); }
914
917
  this._world = null;
915
918
  this._parts = new Map();
@@ -474,7 +474,7 @@ import { declaredCount } from '../ObjectFactory.js';
474
474
  * wavelength (Engine Invariant #6 `mass=max(1,capacity/wavelength)`) LIVE —
475
475
  * mirrors `setVelocity`/`setBurstSize`'s own "write every handle" discipline
476
476
  * exactly (real state lives in `emState`, mutated ONLY by a dedicated setter
477
- * — memory `reference_quantumemitter_no_generic_write_path`). A setup
477
+ * — there is no generic write path). A setup
478
478
  * factory's `sourceState.wavelength` accessor (see `setupLightSourceLab.js`)
479
479
  * wraps this so a page's wavelength slider works identically whether the
480
480
  * live source is a `sustainedSource` (particleWalk) or this emitter.
@@ -47,7 +47,7 @@
47
47
  * identity (`injectorTickFn._sourceInjector`) — the SAME idiom
48
48
  * `QuantumEmitter.prototype.dispose` and every prior lab-level injector already
49
49
  * used; see `FrqtlApp.prototype.setup()`'s own dispose-before-reinit
50
- * convention (`reference_frqtlapp_setup_canonical_teardown.md`).
50
+ * convention.
51
51
  *
52
52
  * @typedef {Object} SourceSpec
53
53
  * @property {number|null} wavelength - Per-frame wavelength override (Engine
@@ -263,7 +263,7 @@
263
263
 
264
264
  return {
265
265
  sourceState: sourceState,
266
- // CANONICAL TEARDOWN (see reference_frqtlapp_setup_canonical_teardown.md):
266
+ // CANONICAL TEARDOWN (FrqtlApp.setup()'s dispose-before-reinit convention):
267
267
  // tombstone (defense in depth) then physically splice the tick-fn out
268
268
  // of experimentTickFunctions by identity. Idempotent — a second call
269
269
  // is a safe no-op.
@@ -53,12 +53,18 @@ import { linkProject } from '../../../shim/project/link.js';
53
53
  import { serializeRecordFolder, CLIP_SECONDS, BY, CHANGE_KEYS } from '../../../shim/project/record-format.js';
54
54
  import { kindNamed } from '../kinds.js';
55
55
  import { _setOpenRecord, openRecordOf } from './open-record.js';
56
- import { base64ToBytes } from '../../../shim/render/capture-envelope.js';
57
56
 
58
57
  function _fail(msg) {
59
58
  throw new Error('[Record] ' + msg + ' (FAIL-LOUD.)');
60
59
  }
61
60
 
61
+ function _bytesOfBase64(b64) {
62
+ var bin = atob(b64);
63
+ var out = new Uint8Array(bin.length);
64
+ for (var i = 0; i < bin.length; i++) { out[i] = bin.charCodeAt(i); }
65
+ return out;
66
+ }
67
+
62
68
  /** linkProject(held).module.parts → { name: [registered kind name, props] } in key order. */
63
69
  async function _partsOf(held) {
64
70
  var linked = await linkProject(held);
@@ -217,7 +223,7 @@ Record.prototype._clipFor = function (req) {
217
223
  settle();
218
224
  if (!self._open) { return; }
219
225
  var n = env.track.frames.length;
220
- self._clips.push({ bytes: base64ToBytes(env.encoded.bytes), firstTick: ticks[0], lastTick: ticks[n - 1] });
226
+ self._clips.push({ bytes: _bytesOfBase64(env.encoded.bytes), firstTick: ticks[0], lastTick: ticks[n - 1] });
221
227
  },
222
228
  drop: function () { settle(); }
223
229
  };
@@ -251,8 +257,7 @@ Record.prototype.film = function (opts) {
251
257
  ' equal whole-frame segments of at most ' + CLIP_SECONDS.max + ' s — choose seconds × fps divisible by ' + n + '.');
252
258
  }
253
259
  var f = total / n;
254
- var b = FrqtlVision.recordBudget(f, every);
255
- var req = { everyTicks: every, fps: fps, maxFrames: b.maxFrames, stopAt: b.stopAt };
260
+ var req = { everyTicks: every, fps: fps, maxFrames: f, stopAt: { ticks: (f - 1) * every } };
256
261
  if (opts.stage !== undefined) { req.stage = opts.stage; }
257
262
  var vision = FrqtlVision.attach(this._runner);
258
263
  var first = this._clips.length;
@@ -63,8 +63,8 @@
63
63
  * `makeLeafFrame` + `injectFrame`, then stamped via `setFrameProperty` with a
64
64
  * constant forward `vz` and a radial (vx,vy) scaled by the live `spread` knob
65
65
  * — the SAME `leafV`/`ringLeaves` construction verified as canonical-bench
66
- * `S2`/`S3` (re-applying vx/vy/vz AFTER inject is the documented safe idiom,
67
- * `feedback_pkgnode_verification_script_gotchas.md` — omitting it silently
66
+ * `S2`/`S3` (re-applying vx/vy/vz AFTER inject is the documented safe idiom;
67
+ * omitting it silently
68
68
  * no-ops the velocity write on some engine builds).
69
69
  *
70
70
  * `spread=0` reproduces S2 exactly: radial extent stays bounded near the
@@ -90,7 +90,7 @@
90
90
  * is no sink here, so `quantum_limit`-style population bounding is left to the
91
91
  * page/GYM run duration, matching `particle-walk-3d`'s own precedent (no sink,
92
92
  * `wrap:false`-equivalent — leaves simply exit `universe_rect` and stop
93
- * appearing, per `reference_population_bounded_by_universe_edge_not_only_sink.md`).
93
+ * appearing).
94
94
  */
95
95
 
96
96
  import { assertSetupOptions as _assertSetupOptions, requireWorldRect as _requireWorldRect } from './_setupOptions.js';
@@ -233,8 +233,8 @@
233
233
  * already-emitted leaves keep whatever mass they were stamped with, M5).
234
234
  * Clamped to `[1, MAX_USEFUL_WAVELENGTH]` (=capacity at the CURRENT
235
235
  * `fundamentalDimension`) — beyond that ceiling `mass` saturates at 1 and
236
- * the slider's upper half goes dead (`feedback_mass_ceiling_saturation_
237
- * wavelength_param.md`). At `fundamentalDimension=0` (capacity=1) ANY
236
+ * the slider's upper half goes dead.
237
+ * At `fundamentalDimension=0` (capacity=1) ANY
238
238
  * wavelength>=1 forces mass=1 regardless — this knob is a documented NO-OP
239
239
  * until `fundamentalDimension` is raised, exactly the SU1 opt-in-safety
240
240
  * property that keeps the sun/laser/drum presets' default look untouched.
@@ -336,8 +336,7 @@
336
336
  * hook, no native emit-spec). Fast-path regime: no
337
337
  * `withInterQuantumCollisions`, no `brownianMotion`, no top-down frame-gen
338
338
  * auto-spawn ladder. No sink — leaves drift forever (M5) until they exit
339
- * `universe_rect` (population bounded by the universe edge, per
340
- * `reference_population_bounded_by_universe_edge_not_only_sink.md`).
339
+ * `universe_rect` (population bounded by the universe edge).
341
340
  */
342
341
 
343
342
  import { assertSetupOptions as _assertSetupOptions, requireWorldRect as _requireWorldRect } from './_setupOptions.js';
@@ -629,8 +628,7 @@ import { FrqtlWorldInit } from './_worldInit.js';
629
628
  burstSize: 0, // derived below (preset-aware default) — placeholder here
630
629
  // Per-leaf wavelength (mass=capacity/wavelength) — null = engine
631
630
  // default mass=capacity, BYTE-IDENTICAL to every pre-existing
632
- // caller. Clamped to [1,maxWavelength] whenever a number is set
633
- // (feedback_mass_ceiling_saturation_wavelength_param.md).
631
+ // caller. Clamped to [1,maxWavelength] whenever a number is set.
634
632
  wavelength: (options.wavelength !== undefined && options.wavelength !== null)
635
633
  ? clamp(options.wavelength, 1, maxWavelength) : null,
636
634
  // Per-leaf CHARGE mode (drives the transverse oscillation quadrant —
@@ -902,8 +900,8 @@ import { FrqtlWorldInit } from './_worldInit.js';
902
900
  // 'negative' are deterministic (NO draw) so the default 'positive' path is
903
901
  // byte-identical to the pre-existing hardcoded 0.
904
902
  // MUST draw in JS and pass an integer 0/1 — passing null coerces to 0 at the
905
- // wasm-bindgen ABI, NOT a random-draw sentinel (reference_wasm_null_charge_
906
- // coercion_bug.md), so `chargeMode:'random'` cannot be delegated to makeLeafFrame.
903
+ // wasm-bindgen ABI, NOT a random-draw sentinel;
904
+ // so `chargeMode:'random'` cannot be delegated to makeLeafFrame.
907
905
  function sampleCharge() {
908
906
  if (state.chargeMode === 'random') { return (universe.random() < 0.5) ? 0 : 1; }
909
907
  return (state.chargeMode === 'negative') ? 1 : 0;
@@ -37,10 +37,8 @@
37
37
  * getScene():Promise<object>, // the run-invariant SceneRecord + its content id
38
38
  * getStill(stage?):Promise<object>, // stage omitted → the FULL composed stack
39
39
  * getStream({stage?, everyTicks}):AsyncIterable<object>, // stills at a TICK cadence
40
- * record({seconds?, fps?, signal?}) // THE DEFAULT: up to 60 s of what the viewer sees, wall-clock timed
41
- * :Promise<object>, // an encoded video: CaptureEnvelope.videoEnvelope
42
40
  * record({everyTicks, stopAt, maxFrames, fps, stage?, bitrate?, keyFrameInterval?, signal?})
43
- * :Promise<object>, // the ADVANCED tick-sampling form (corpus rows, flights)
41
+ * :Promise<object>, // an encoded video: CaptureEnvelope.videoEnvelope
44
42
  * stages:string[], // the FERRIED RenderStages.RENDER_STAGES list
45
43
  * finalStage():string, // the ferried final-stage derivation
46
44
  * toDataURL(still):string, // the BROWSER PNG encoder (data URL)
@@ -167,12 +165,8 @@
167
165
  * var still = await vision.getStill(); // the whole composed stack
168
166
  * var field = await vision.getStill('field'); // the render-free numeric channel
169
167
  *
170
- * // A video of what the viewer sees (the default form): up to 60 s at 30 fps; Stop = abort.
171
- * var stop = new AbortController();
172
- * var env = await vision.record({ seconds: 20, signal: stop.signal });
173
- *
174
- * // ADVANCED — tick sampling: 1 still per 2 ticks until tick 600, played back at 30 fps.
175
- * var env2 = await vision.record({ everyTicks: 2, stopAt: { tick: 600 }, maxFrames: 400, fps: 30 });
168
+ * // A video: 1 still per 2 ticks until tick 600, played back at 30 fps.
169
+ * var env = await vision.record({ everyTicks: 2, stopAt: { tick: 600 }, maxFrames: 400, fps: 30 });
176
170
  *
177
171
  * // Aligned multi-channel corpus row: capture BETWEEN ticks and assert equal tick stamps —
178
172
  * // the tick equality IS the co-registration guard; `scene` ties them to one header.
@@ -468,43 +462,33 @@ function _getStream(runner, RS, opts) {
468
462
  }
469
463
 
470
464
  /** The recorder's declared options. @private */
471
- var RECORD_OPTIONS = ['seconds', 'everyTicks', 'stopAt', 'maxFrames', 'fps', 'stage', 'bitrate', 'keyFrameInterval', 'signal'];
472
- /** The keys only the advanced TICK form takes; any of them selects it. @private */
473
- var TICK_FORM_KEYS = ['everyTicks', 'stopAt', 'maxFrames'];
474
- /**
475
- * The default — HUMAN — form's defaults and cap: a recording of what the viewer sees, `seconds` long (at most
476
- * RECORD_DEFAULTS.seconds), played back at `fps`.
477
- */
478
- var RECORD_DEFAULTS = Object.freeze({ seconds: 60, fps: 30 });
479
- var HUMAN_SHAPE = '{seconds?, fps?, signal?, stage?, bitrate?, keyFrameInterval?} (the default: seconds of what the viewer sees)';
480
- var TICK_SHAPE = '{everyTicks, stopAt, maxFrames, fps, stage?, bitrate?, keyFrameInterval?, signal?} (the advanced tick-sampling form)';
465
+ var RECORD_OPTIONS = ['everyTicks', 'stopAt', 'maxFrames', 'fps', 'stage', 'bitrate', 'keyFrameInterval', 'signal'];
481
466
  var STOP_AT_FORMS = ['tick', 'ticks', 'path'];
482
467
  var PATH_OPTIONS = ['waypoints', 'loop', 'waypointTimeoutMs'];
483
468
 
484
- /**
485
- * THE length budget of a recording (one owner: the human form and Record.film both take it): `frames` pictures at
486
- * `everyTicks` end `(frames − 1) × everyTicks` ticks after the first capture, ON the last picture — so reaching the
487
- * end is truncated:false (a stop at `frames × everyTicks` would ask for one picture past the bound and report a
488
- * truncation). The math of maxi-record.js::segmentTicks.
489
- * @param {number} frames
490
- * @param {number} everyTicks
491
- * @returns {{maxFrames:number, stopAt:{ticks:number}}}
492
- */
493
- function recordBudget(frames, everyTicks) {
494
- return { maxFrames: frames, stopAt: { ticks: (frames - 1) * everyTicks } };
495
- }
496
-
497
- /** The stage/signal/encoder options both forms share, validated once. @private */
498
- function _sharedRecordOptions(RS, opts, req, who) {
499
- req.stage = (opts.stage === undefined) ? RS.finalStage() : RS.assertStage(opts.stage);
500
- req.bitrate = (opts.bitrate === undefined) ? null : _requirePosInt(opts.bitrate, 'bitrate (bits per second)', who);
501
- req.keyFrameInterval = (opts.keyFrameInterval === undefined) ? 1 : _requirePosInt(opts.keyFrameInterval, 'keyFrameInterval (frames)', who);
502
- req.signal = null;
469
+ /** Validate a record() request; returns the normalized request. @private */
470
+ function _normalizeRecord(RS, opts) {
471
+ var who = 'record';
472
+ if (!opts || typeof opts !== 'object') {
473
+ _fail(who, 'expected {everyTicks, stopAt, maxFrames, fps, stage?, bitrate?, keyFrameInterval?, signal?}, got ' + String(opts));
474
+ }
475
+ _assertKnownKeys(opts, RECORD_OPTIONS, 'record', who);
476
+ var req = {
477
+ everyTicks: _requirePosInt(opts.everyTicks, 'everyTicks (the capture cadence in TICKS — there is no wall-clock cadence)', who),
478
+ maxFrames: _requirePosInt(opts.maxFrames, 'maxFrames (the memory bound; hitting it reports truncated:true)', who),
479
+ fps: _requirePosInt(opts.fps, 'fps (the PLAYBACK rate — it has no physical meaning)', who),
480
+ stage: (opts.stage === undefined) ? RS.finalStage() : RS.assertStage(opts.stage),
481
+ bitrate: (opts.bitrate === undefined) ? null : _requirePosInt(opts.bitrate, 'bitrate (bits per second)', who),
482
+ keyFrameInterval: (opts.keyFrameInterval === undefined) ? 1
483
+ : _requirePosInt(opts.keyFrameInterval, 'keyFrameInterval (frames)', who),
484
+ stopAt: null,
485
+ signal: null
486
+ };
503
487
  if (opts.signal !== undefined) {
504
488
  var sig = opts.signal;
505
489
  if (!sig || typeof sig.aborted !== 'boolean' || typeof sig.addEventListener !== 'function') {
506
490
  _fail(who, 'signal must be an AbortSignal (new AbortController().signal) — it is how a recording ' +
507
- 'stops before its end; got ' + String(sig));
491
+ 'stops before its stopAt; got ' + String(sig));
508
492
  }
509
493
  req.signal = sig;
510
494
  }
@@ -514,92 +498,6 @@ function _sharedRecordOptions(RS, opts, req, who) {
514
498
  'plausible-looking movie of nothing. Read the numbers with getStream({stage: ' +
515
499
  JSON.stringify(req.stage) + ', everyTicks})');
516
500
  }
517
- return req;
518
- }
519
-
520
- /**
521
- * recordRefusal(runner) → null when the default (human) form of record() can start on this runner NOW, else
522
- * `{ reason, message }`: reason 'paused' (no tick will arrive to film) or 'rate-unmeasured' (runner.getRates().tps is
523
- * not yet a positive number — FrqtlApp resets it on every start and reports after its first second running). The ONE
524
- * owner of when the default form refuses: record() fails with `message`, and a host that offers a Record control
525
- * enables it on `null` (reading this on the live runner, never a polled copy of its rates).
526
- * @param {object} runner
527
- * @returns {null|{reason:string, message:string}}
528
- */
529
- function recordRefusal(runner) {
530
- if (!runner || typeof runner.getRates !== 'function') {
531
- throw new TypeError('[FrqtlVision] recordRefusal(runner): runner is a live FrqtlApp (it reads isRunning and getRates()). (FAIL-LOUD.)');
532
- }
533
- if (!runner.isRunning) {
534
- return { reason: 'paused', message: 'the world is paused, so no tick will arrive to film (a recording samples by ' +
535
- 'TICK, never by the clock) — resume first' };
536
- }
537
- var tps = runner.getRates().tps;
538
- if (typeof tps !== 'number' || !isFinite(tps) || tps <= 0) {
539
- return { reason: 'rate-unmeasured', message: 'the runner has not measured its tick rate yet (runner.getRates().tps = ' +
540
- String(tps) + '; it reports after its first second running), and the default form samples at most fps pictures ' +
541
- 'a second of it. Record once it has run a second, or name the cadence with the tick form ' + TICK_SHAPE };
542
- }
543
- return null;
544
- }
545
-
546
- /** The HUMAN form: {seconds?, fps?} — the tick cadence is derived from the live runner when recording starts. @private */
547
- function _normalizeHumanRecord(RS, opts, who) {
548
- var req = {
549
- form: 'human',
550
- seconds: (opts.seconds === undefined) ? RECORD_DEFAULTS.seconds : _requirePosInt(opts.seconds, 'seconds (playback seconds)', who),
551
- fps: (opts.fps === undefined) ? RECORD_DEFAULTS.fps : _requirePosInt(opts.fps, 'fps (the PLAYBACK rate)', who),
552
- everyTicks: null, stopAt: null, maxFrames: null
553
- };
554
- if (req.seconds > RECORD_DEFAULTS.seconds) {
555
- _fail(who, 'seconds ' + req.seconds + ' is over the cap of ' + RECORD_DEFAULTS.seconds + ' s (the recording is held ' +
556
- 'in memory until it ends). A longer capture is the tick form: ' + TICK_SHAPE);
557
- }
558
- return _sharedRecordOptions(RS, opts, req, who);
559
- }
560
-
561
- /**
562
- * The human form's request, from the LIVE runner when recording starts. Its TIME is the wall clock: every picture is
563
- * stamped with its wall-clock time since the first one (_record), and the recording ends on its own once `seconds` of
564
- * wall clock have been filmed — so the file lasts as long as the viewer watched, whatever the tick rate does while
565
- * recording (a 1:1-locked scene slows when the recorder draws). The cadence is only a SAMPLING-RATE CEILING: the runner
566
- * ticks `tps` a second (its own measured rate, runner.getRates().tps), and sampling every
567
- * everyTicks = max(1, ceil(tps / fps)) ticks never films faster than `fps` at that rate (round or floor would, and a
568
- * picture closer than 1/fps to the last one has to be pushed later than its wall time). The memory bound is
569
- * recordBudget(seconds × fps, everyTicks).maxFrames; reaching it (the scene sped up) is truncated:true. @private
570
- */
571
- function _deriveHumanRecord(runner, req) {
572
- var refusal = recordRefusal(runner);
573
- if (refusal) { _fail('record', refusal.message); }
574
- var tps = runner.getRates().tps;
575
- req.everyTicks = Math.max(1, Math.ceil(tps / req.fps));
576
- req.maxFrames = recordBudget(req.seconds * req.fps, req.everyTicks).maxFrames;
577
- req.stopAt = {}; // no tick stop: the wall clock ends it (_record)
578
- return req;
579
- }
580
-
581
- /** Validate a record() request; returns the normalized request. @private */
582
- function _normalizeRecord(RS, opts) {
583
- var who = 'record';
584
- if (opts === undefined) { opts = {}; }
585
- if (!opts || typeof opts !== 'object') {
586
- _fail(who, 'expected ' + HUMAN_SHAPE + ' or ' + TICK_SHAPE + ', got ' + String(opts));
587
- }
588
- _assertKnownKeys(opts, RECORD_OPTIONS, 'record', who);
589
- var tickKeys = TICK_FORM_KEYS.filter(function (k) { return opts[k] !== undefined; });
590
- if (opts.seconds !== undefined && tickKeys.length) {
591
- _fail(who, 'a call mixes the two shapes (seconds with ' + tickKeys.join(', ') + '). Pass EITHER ' + HUMAN_SHAPE +
592
- ' OR ' + TICK_SHAPE);
593
- }
594
- if (!tickKeys.length) { return _normalizeHumanRecord(RS, opts, who); }
595
- var req = {
596
- form: 'tick',
597
- everyTicks: _requirePosInt(opts.everyTicks, 'everyTicks (the capture cadence in TICKS — there is no wall-clock cadence)', who),
598
- maxFrames: _requirePosInt(opts.maxFrames, 'maxFrames (the memory bound; hitting it reports truncated:true)', who),
599
- fps: _requirePosInt(opts.fps, 'fps (the PLAYBACK rate — it has no physical meaning)', who),
600
- stopAt: null
601
- };
602
- _sharedRecordOptions(RS, opts, req, who);
603
501
  var s = opts.stopAt;
604
502
  if (!s || typeof s !== 'object') {
605
503
  _fail(who, 'stopAt is REQUIRED — exactly one of {tick: T}, {ticks: K}, {path: {waypoints, loop?, ' +
@@ -677,8 +575,6 @@ function _record(runner, RS, opts) {
677
575
  'localhost). The encoder is not optional — there is no second path');
678
576
  }
679
577
 
680
- if (req.form === 'human') { _deriveHumanRecord(runner, req); }
681
-
682
578
  // THE CLIP HOOK: while a Record is open on this runner, every recording is one of its clips. The Record
683
579
  // refuses a request that cannot be a CLIP_SECONDS clip (before anything subscribes) and keeps the clip's
684
580
  // ticks and bytes; this recorder holds no Record state of its own (objects/record/Record.js _clipFor).
@@ -704,12 +600,6 @@ function _record(runner, RS, opts) {
704
600
  var closing = false;
705
601
  var failure = null;
706
602
  var stopTick = (req.stopAt.tick !== undefined) ? req.stopAt.tick : null;
707
- // The human form's clock: picture i's wall time since picture 0 as a SLOT of the 1/fps grid the muxer writes
708
- // (whole numbers, so two pictures can never share a slot: a picture landing in or before the last one's slot
709
- // takes the next), and whether it is the last one the `seconds` of wall clock admit.
710
- var human = (req.form === 'human');
711
- var wallT0 = null;
712
- var slotOf = [];
713
603
  var session = null;
714
604
  var onAbort = null;
715
605
  var dims = null;
@@ -795,14 +685,6 @@ function _record(runner, RS, opts) {
795
685
  },
796
686
  onStill: function (p, i) {
797
687
  if (clip) { clip.sample(i); }
798
- var lastByWall = false;
799
- if (human) {
800
- var now = performance.now();
801
- if (i === 0) { wallT0 = now; }
802
- var slot = Math.round((now - wallT0) / 1000 * req.fps);
803
- slotOf[i] = (i === 0) ? 0 : Math.max(slot, slotOf[i - 1] + 1);
804
- lastByWall = slotOf[i] + 1 >= req.seconds * req.fps;
805
- }
806
688
  var handled = p.then(function (still) {
807
689
  if (i === 0) {
808
690
  scene = still.scene;
@@ -817,7 +699,7 @@ function _record(runner, RS, opts) {
817
699
  encodeChain = encodeChain.then(function (enc) {
818
700
  var sample = new enc.MB.VideoSample(still.data, {
819
701
  format: 'RGBA', codedWidth: still.width, codedHeight: still.height,
820
- timestamp: (human ? slotOf[i] : i) / req.fps, duration: 1 / req.fps
702
+ timestamp: i / req.fps, duration: 1 / req.fps
821
703
  });
822
704
  return Promise.resolve(enc.source.add(sample)).then(function () {
823
705
  sample.close();
@@ -827,7 +709,6 @@ function _record(runner, RS, opts) {
827
709
  // Handled at close; a rejected encode must not surface as unhandled meanwhile.
828
710
  encodeChain.then(null, function (e) { close(e); });
829
711
  if (stopTick !== null && still.tick + req.everyTicks > stopTick) { close(null); }
830
- if (lastByWall) { close(null); }
831
712
  }, function (e) { close(e); });
832
713
  inflight.push(handled);
833
714
  return handled;
@@ -906,19 +787,8 @@ function attach(runner) {
906
787
  */
907
788
  getStream: function (opts) { return _getStream(runner, RS, opts); },
908
789
  /**
909
- * record(opts?) → Promise<VideoEnvelope> — film what the viewer sees, encode an MP4.
910
- *
911
- * THE DEFAULT (human) FORM — record({seconds?, fps?, signal?, stage?, bitrate?, keyFrameInterval?}):
912
- * seconds default and cap RECORD_DEFAULTS.seconds (60) — the recording ends on its own
913
- * after this many seconds of WALL CLOCK (truncated:false)
914
- * fps default RECORD_DEFAULTS.fps (30) — the most pictures a second it films
915
- * signal an AbortSignal: abort is Stop — what was filmed, truncated:true
916
- * Each picture is stamped with its wall-clock time since the first, so the file lasts as long as the
917
- * viewer watched whatever the tick rate does; picture i is NOT tick i / fps in this form (the tick form
918
- * keeps that). Refused on a paused runner, or before the runner has measured its rate (FrqtlVision.recordRefusal).
790
+ * record(opts) → Promise<VideoEnvelope> — sample like `getStream`, encode an MP4.
919
791
  *
920
- * THE ADVANCED (tick) FORM — any of everyTicks/stopAt/maxFrames selects it; mixing it with
921
- * `seconds` throws naming both shapes:
922
792
  * everyTicks REQUIRED — capture cadence in TICKS (sampling starts at the first
923
793
  * tick after this call, then every `everyTicks`)
924
794
  * stopAt REQUIRED — exactly one of `{tick: T}` (absolute, inclusive),
@@ -928,7 +798,7 @@ function attach(runner) {
928
798
  * waypoint)
929
799
  * maxFrames REQUIRED — the memory bound; reaching it before `stopAt` stops the
930
800
  * recording and reports `truncated: true`
931
- * fps REQUIRED — PLAYBACK rate only; frame i is timestamped i/fps (tick-exact timing)
801
+ * fps REQUIRED — PLAYBACK rate only; frame i is timestamped i/fps
932
802
  * stage default `finalStage()`; must be an rgba8 stage
933
803
  * signal an AbortSignal: abort ends the recording early with the stills
934
804
  * captured so far and `truncated: true` (rejects if none yet)
@@ -953,8 +823,7 @@ function attach(runner) {
953
823
 
954
824
  // ── Export ────────────────────────────────────────────────────────────────────
955
825
 
956
- var FrqtlVision = { attach: attach, toDataURL: toDataURL, toPNG: toPNG, RECORD_DEFAULTS: RECORD_DEFAULTS, recordBudget: recordBudget,
957
- recordRefusal: recordRefusal };
826
+ var FrqtlVision = { attach: attach, toDataURL: toDataURL, toPNG: toPNG };
958
827
 
959
828
  // The capture-host KIND's in-page recorder is THIS face: registered here, so capture-host
960
829
  // never names FrqtlVision (the import runs one way: FrqtlVision → capture-host).
@@ -36,7 +36,7 @@
36
36
  * colour washed under the bins, so an un-hit face still reads as a plate and
37
37
  * intensity rises monotonically from empty through every bin.
38
38
  *
39
- * Readouts: `getCollisionHistogram()` / `resetHistogram()` / `getArrivals()` —
39
+ * Readouts: `getCollisionHistogram()` / `resetHistogram()` / `getLiveCount()` —
40
40
  * inherited from `Wall`, UNCHANGED. `heatCanvas()` returns the ferry canvas.
41
41
  *
42
42
  * ── ESTIMATION BEFORE RUNNING: when will this plate have counted anything? ───
@@ -76,7 +76,7 @@ import { registerKind } from '../objects/kinds.js';
76
76
  'source fails loud.',
77
77
  // STUDIO UX: a chart panel has a real draggable/resizable extent, and it is
78
78
  // VISIBLE during Run (its whole point), so shellRender:'run' (NOT a Design-only
79
- // marker).
79
+ // marker). 2D drag; 3D reposition via the camera.
80
80
  ux: {
81
81
  resizable: true,
82
82
  draggable: { '2d': true },
@@ -617,8 +617,8 @@ import { CollisionTypes } from './CollisionTypes.js';
617
617
  // UX_DRAGGABLE_MODES / UX_SHELL_RENDER); this block is read via
618
618
  // ObjectSchema.ux('SphereEmitter'). resizable:false — a SphereEmitter has
619
619
  // TWO radii (inner+outer); a single-box resize gesture is ambiguous, so
620
- // it is NOT resizable (individually, per object). handles: ['move'] — the
621
- // Hand only moves it (2D and 3D), never scales it.
620
+ // it is NOT resizable (individually, per object). draggable 2D (a 3D
621
+ // scene never cursor-drags). handles: ['move'] — it only moves, never scales.
622
622
  // shellRender:'design' — the marker paints only while authoring (the
623
623
  // default; the "red light bulb" flips a per-instance shellRender override).
624
624
  ux: {
@@ -800,7 +800,7 @@ import { setupTunnelPointExit } from '../objects/setup/setupTunnelPointExit.js';
800
800
  'reflects off the two facing mirrors and stays collimated (no random scatter, ' +
801
801
  'no leak through the walls). The group is the single author-surface entity; ' +
802
802
  'the two mirror Walls it composes carry its `_owner` up-link. Zero physics of its own.',
803
- // A tunnel has a genuine draggable/resizable extent (like a Wall).
803
+ // A tunnel has a genuine draggable/resizable extent (like a Wall). 2D drag only.
804
804
  ux: {
805
805
  resizable: true,
806
806
  draggable: { '2d': true },