@descix/frqtl-web 0.6.0-p4.1 → 0.6.0

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 (69) hide show
  1. package/CLAUDE.md +15 -11
  2. package/README.md +26 -6
  3. package/dist/artifact/double-slit.html +2 -2
  4. package/dist/dist-manifest.json +61 -60
  5. package/dist/experiments/empty/index.html +22 -7
  6. package/dist/frqtl/compat/providers/wasm-engine.js +3 -4
  7. package/dist/frqtl/compat/renderer/providers/p5-provider.js +1 -1
  8. package/dist/frqtl/objects/FrqtlApp.js +5 -5
  9. package/dist/frqtl/objects/RecipeContext.js +106 -1
  10. package/dist/frqtl/objects/constants/WallBehaviors.js +1 -1
  11. package/dist/frqtl/objects/instruments/capture.js +1 -24
  12. package/dist/frqtl/objects/instruments/hosted-eyes.js +17 -1
  13. package/dist/frqtl/objects/objects/makeControlsForObject.js +5 -5
  14. package/dist/frqtl/objects/record/Record.js +25 -5
  15. package/dist/frqtl/objects/schema/engine-scopes.js +2 -2
  16. package/dist/frqtl/objects/schema/scopes.js +2 -2
  17. package/dist/frqtl/objects/setup/_worldInit.js +1 -2
  18. package/dist/frqtl/objects/setup/setupBlackbodySubstrate.js +1 -2
  19. package/dist/frqtl/parts/CameraControls.js +8 -0
  20. package/dist/frqtl/parts/DetectorWall.js +1 -1
  21. package/dist/frqtl/parts/GraphingDetectorWall.js +7 -7
  22. package/dist/frqtl/parts/LargeObject.js +2 -2
  23. package/dist/frqtl/parts/LiveChart.js +2 -2
  24. package/dist/frqtl/parts/LogicGate.js +3 -3
  25. package/dist/frqtl/parts/OvenBox.js +1 -1
  26. package/dist/frqtl/parts/PointSource.js +1 -1
  27. package/dist/frqtl/parts/SlitLightSource.js +1 -1
  28. package/dist/frqtl/parts/SlitScreen.js +1 -1
  29. package/dist/frqtl/parts/SphereEmitter.js +12 -12
  30. package/dist/frqtl/parts/Trace.js +1 -1
  31. package/dist/frqtl/parts/Tunnel.js +11 -11
  32. package/dist/frqtl/parts/Wall.js +20 -10
  33. package/dist/frqtl/scenes/circuit-sat.js +1 -0
  34. package/dist/frqtl/scenes/dse-one-emitter.js +32 -34
  35. package/dist/frqtl/scenes/dse-two-emitters.js +33 -34
  36. package/dist/frqtl/scenes/mirror-route.js +96 -79
  37. package/dist/frqtl-web.min.js +54 -54
  38. package/dist/sdk.html +2 -2
  39. package/dist/shim/bundle/index.js +6 -0
  40. package/dist/shim/controls/index.js +1 -1
  41. package/dist/shim/engine/artifact-shell.js +1 -1
  42. package/dist/shim/engine/router.js +3 -3
  43. package/dist/shim/host/host-view.js +228 -0
  44. package/dist/shim/host/index.js +18 -0
  45. package/dist/shim/index.js +2 -4
  46. package/dist/shim/notebook/kernel.js +1 -1
  47. package/dist/shim/notebook/setup-builder.js +2 -2
  48. package/dist/shim/package.json +1 -0
  49. package/dist/shim/page-params/index.js +2 -30
  50. package/dist/shim/project/fork.js +293 -0
  51. package/dist/shim/project/identity.js +3 -1
  52. package/dist/shim/project/link.js +43 -3
  53. package/dist/shim/project/parts-writer.js +62 -5
  54. package/dist/shim/project/read-text.js +43 -0
  55. package/dist/shim/project/specifiers.js +104 -15
  56. package/dist/shim/registry/exhibits.js +15 -34
  57. package/dist/shim/registry/index.js +2 -2
  58. package/dist/shim/registry/scene-roster.js +35 -0
  59. package/dist/shim/registry/scene-source.js +6 -36
  60. package/dist/shim/registry/walkthrough.js +2 -3
  61. package/dist/shim/render-state/apply.js +66 -31
  62. package/dist/shim/render-state/index.js +6 -2
  63. package/dist/shim/runtime/index.js +4 -4
  64. package/llms.txt +9 -7
  65. package/package.json +20 -2
  66. package/dist/frqtl/experiments/_shared/fx-experiment.js +0 -449
  67. package/dist/js/models/flamingo-draco.glb +0 -0
  68. package/dist/js/models/flamingo.glb +0 -0
  69. package/dist/shim/registry/experiments.js +0 -215
@@ -133,7 +133,7 @@ var _renderObj = {
133
133
  * naming the global and the gate, rather than yielding undefined or null. A soft
134
134
  * return is exactly what turns a boot-ordering defect into an opaque
135
135
  * property-access TypeError one frame later ("Cannot read properties of null
136
- * (reading 'build')" — FRAQTL #73); the throw names what was unavailable instead.
136
+ * (reading 'build')"); the throw names what was unavailable instead.
137
137
  * That covers the constructor members (`FrqtlApp`, `RecipeContext`) and every getter generated from
138
138
  * the member table (CAPS_FRQTL_MEMBERS): there is no soft residual.
139
139
  *
@@ -441,7 +441,7 @@ function _runMath(code, fileId, sourceUrl) {
441
441
  * handle minted before the call is dead — a later use throws
442
442
  * `arena:stale-handle`. For `js-reference` it is a no-op.
443
443
  *
444
- * THE SCOPE RULE (FRAQTL issue #67): a math scope is one RUN, and the caller
444
+ * THE SCOPE RULE: a math scope is one RUN, and the caller
445
445
  * that knows what a run is owns the boundary. Two run units exist, each stated
446
446
  * once: the `run()` lane's unit is one code buffer (it calls this in its own
447
447
  * `finally`); a notebook's unit is one notebook run, so `NotebookKernel` calls
@@ -576,7 +576,7 @@ function _runMathModule(code, sdk, sourceUrl) {
576
576
  * - _ensureMathSdk() (resolved SDK + backend select)
577
577
  * - the stashed-console tee (the 7cc5520 lesson — observers never re-emit)
578
578
  *
579
- * It does NOT end the math scope: a cell is not a run (FRAQTL issue #67). Its
579
+ * It does NOT end the math scope: a cell is not a run. Its
580
580
  * declared outputs are committed into the caller's binding store and must stay
581
581
  * usable in later cells, so the scope boundary belongs to whoever owns that
582
582
  * store — see `resetMathScope()`.
@@ -839,7 +839,7 @@ function runCell(spec) {
839
839
  // NO math-scope reset here. A cell is not a run: the values this cell
840
840
  // just returned are about to be committed into the caller's binding
841
841
  // store, and draining the arena would make every one of them a stale
842
- // handle before the next cell could read it (FRAQTL issue #67). The
842
+ // handle before the next cell could read it. The
843
843
  // scope boundary is the binding store's — see resetMathScope().
844
844
  });
845
845
  }).catch(function (e) {
package/llms.txt CHANGED
@@ -2,20 +2,22 @@
2
2
 
3
3
  > A discrete cellular-automata physics engine (compiled Rust → WASM) for the browser: interference,
4
4
  > blackbody spectra and binding emerge from per-pixel rules (1 px/tick, single occupancy, momentum).
5
- > Pre-release 0.6.0-p4.1 on npm dist-tag `next`. Node twin: @descix/frqtl-node.
5
+ > 0.6.0 on npm dist-tag `latest`. Node twin: @descix/frqtl-node.
6
6
 
7
- - Install: `npm install @descix/frqtl-web@next`
8
- - Live page (claude.ai artifact-safe): https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p4.1/dist/artifact/double-slit.html
9
- - One-file form (global FRQTL): https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p4.1/dist/frqtl-web.min.js — example https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p4.1/dist/artifact/sun.html
7
+ - Install: `npm install @descix/frqtl-web`
8
+ - Live page (claude.ai artifact-safe): https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0/dist/artifact/double-slit.html
9
+ - One-file form (global FRQTL): https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0/dist/frqtl-web.min.js — example https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0/dist/artifact/sun.html
10
10
  - A scene is an ES module: `export default function buildExperiment(exp)`, first statement
11
11
  `exp.createCanvas(w, h, cfg)` (2D, p5) or `exp.createScene(w, h, d, cfg)` (3D, three); parts from
12
- `@descix/frqtl-web/parts`. Example: https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p4.1/dist/frqtl/scenes/double-slit.js
12
+ `@descix/frqtl-web/parts`. Example: https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0/dist/frqtl/scenes/double-slit.js
13
13
  - Doors (`@descix/frqtl-web/boot`): `bootScene(mount, buildExperiment, opts)`;
14
14
  `bootProject(mount, { files: { 'sketch.js': text }, entry: 'sketch.js' }, opts)` or `{ url, entry }`; a folder whose
15
15
  `frqtl.json` names its entry boots as `{ files }` or `{ url }` with no `entry`.
16
16
  - `./project`: `FRQTL_WEB_SPECIFIERS`, `libPathOf`, `importMapFor`, `pageImportMapFor`, `FRQTL_WEB_HOST_SPECIFIERS`, `linkProject`, `sketchProject`, `SKETCH_ENTRY`, `projectIdentity`, `MANIFEST_FILE`, `MANIFEST_KEYS`, `normalizeManifest`, `parseManifest`, `serializeManifest`, `manifestFor` (the owner of `frqtl.json`), `RECORD_FILES`, `RECORD_KEYS`, `CHANGE_KEYS`, `OPS`, `BY`, `CLIP_SECONDS`, `CLIP_NAME`, `clipName`, `jsonText`, `recordFolderFaults` (the owner of a Record folder's shape; `recordFolderFaults(files)` is `[]` for a complete Record).
17
17
  - `./registry`: walk-through rungs and `projectOf(id, { mode })` → `{ manifest, files, renderState }` (boot it with `bootProject(mount, { files }, { renderState })`).
18
18
  - `./kinds`: `registerKind`, `kindNamed`, `kindOf`, `registeredKinds` (a composed fork registers its renamed class).
19
- - API reference: https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p4.1/dist/sdk.html
20
- - Full agent guide: https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p4.1/CLAUDE.md
19
+ - `./host-view`: `declareHostView`, `HOST_VIEW_OUTCOMES`, `CONTRACT_VIOLATIONS`, `HOST_SDK_SCRIPT` (an app asks its DeSciX shell for a view, once: `declareHostView({ sdk: window.DeSciX, mode, fallback })`; the outcome is on the html element's dataset).
20
+ - `await recipeContext.fork(name, NewKind, { by })`: copies the `parts` entry's part file into the folder as `parts/<NewKind>.js` (class renamed, imports rewritten to package specifiers) and re-runs the scene in place.
21
+ - API reference: https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0/dist/sdk.html
22
+ - Full agent guide: https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0/CLAUDE.md
21
23
  - Acceptance is visual; no CLI ships. No account, credits or tokens are needed.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@descix/frqtl-web",
3
- "version": "0.6.0-p4.1",
3
+ "version": "0.6.0",
4
4
  "description": "FRQTL for the browser \u2014 the discrete fractal physics engine (compiled Rust \u2192 WASM), its parts as ES modules, the scene doors (bootScene, bootProject) and frqtl-web.min.js.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -16,6 +16,7 @@
16
16
  "./parts/*": "./dist/frqtl/parts/*",
17
17
  "./project": "./dist/shim/project/index.js",
18
18
  "./registry": "./dist/shim/registry/index.js",
19
+ "./host-view": "./dist/shim/host/index.js",
19
20
  "./shim/controls/registry.js": "./dist/shim/controls/registry.js",
20
21
  "./shim/render/sun-look.js": "./dist/shim/render/sun-look.js",
21
22
  "./compat/renderer/display-slot.js": "./dist/frqtl/compat/renderer/display-slot.js",
@@ -23,10 +24,27 @@
23
24
  "./objects/setup/_collisionMatrixLanes.js": "./dist/frqtl/objects/setup/_collisionMatrixLanes.js",
24
25
  "./compat/engine.js": "./dist/frqtl/compat/engine.js",
25
26
  "./kinds": "./dist/frqtl/objects/kinds-entry.js",
27
+ "./objects/objects/tagger.js": "./dist/frqtl/objects/objects/tagger.js",
28
+ "./objects/schema/index.js": "./dist/frqtl/objects/schema/index.js",
29
+ "./shim/render/heat-colormap.js": "./dist/shim/render/heat-colormap.js",
30
+ "./objects/schema/valueNormalizer.js": "./dist/frqtl/objects/schema/valueNormalizer.js",
31
+ "./objects/objects/Box.js": "./dist/frqtl/objects/objects/Box.js",
32
+ "./objects/objects/QuantumEmitter.js": "./dist/frqtl/objects/objects/QuantumEmitter.js",
33
+ "./shim/expr/ast-schema.js": "./dist/shim/expr/ast-schema.js",
34
+ "./objects/objects/actionCompiler.js": "./dist/frqtl/objects/objects/actionCompiler.js",
35
+ "./objects/v1-replacements.js": "./dist/frqtl/objects/v1-replacements.js",
36
+ "./objects/objects/slitLinerScatter.js": "./dist/frqtl/objects/objects/slitLinerScatter.js",
37
+ "./objects/setup/setupSphereEmitter3D.js": "./dist/frqtl/objects/setup/setupSphereEmitter3D.js",
38
+ "./objects/objects/directedRedirectProgram.js": "./dist/frqtl/objects/objects/directedRedirectProgram.js",
39
+ "./compat/renderer/lo-drawn-center.js": "./dist/frqtl/compat/renderer/lo-drawn-center.js",
40
+ "./objects/setup/setupTunnelPointExit.js": "./dist/frqtl/objects/setup/setupTunnelPointExit.js",
41
+ "./objects/constants/WallBehaviors.js": "./dist/frqtl/objects/constants/WallBehaviors.js",
42
+ "./objects/objects/absorbRadiation.js": "./dist/frqtl/objects/objects/absorbRadiation.js",
43
+ "./objects/geometry/SlabFace.js": "./dist/frqtl/objects/geometry/SlabFace.js",
26
44
  "./dist-manifest.json": "./dist/dist-manifest.json",
27
45
  "./package.json": "./package.json"
28
46
  },
29
- "exportsNotes": "Every target is a file the build places at its lib-identity path (dist/frqtl/..., dist/shim/...), the same module a page imports by URL: one module, one URL. `.` is the parts barrel + the scene doors + the shared package core (lib/frqtl/boot-entry.js). `./boot` is the scene doors alone (doors.js); its node condition refuses, naming @descix/frqtl-node. `./parts` and `./parts/*` are the parts directory (one part = one file). `./project` is the specifier table, the link site, the project identity and the frqtl.json owner (lib/shim/project/index.js). `./registry` is the walk-through rungs, the showcase roster and the experiment registry. `./dist-manifest.json` is the per-file sha256 record a self-hosting consumer checks its copy against. dist/frqtl-web.min.js is a FILE, not an export: the esbuild IIFE of the same entry, global FRQTL. The expected shape of this map is owned by sdk/_build/exports-contract.mjs.",
47
+ "exportsNotes": "Every target is a file the build places at its lib-identity path (dist/frqtl/..., dist/shim/...), the same module a page imports by URL: one module, one URL. `.` is the parts barrel + the scene doors + the shared package core (lib/frqtl/boot-entry.js). `./boot` is the scene doors alone (doors.js); its node condition refuses, naming @descix/frqtl-node. `./parts` and `./parts/*` are the parts directory (one part = one file). `./project` is the specifier table, the link site, the project identity and the frqtl.json owner (lib/shim/project/index.js). `./registry` is the walk-through rungs, the showcase roster and the scene list. `./dist-manifest.json` is the per-file sha256 record a self-hosting consumer checks its copy against. dist/frqtl-web.min.js is a FILE, not an export: the esbuild IIFE of the same entry, global FRQTL. The expected shape of this map is owned by sdk/_build/exports-contract.mjs.",
30
48
  "files": [
31
49
  "dist",
32
50
  "README.md",
@@ -1,449 +0,0 @@
1
- /* Copyright 2023-2026 by Essam Abadir */
2
-
3
- /**
4
- * fx-experiment.js — shared driver for the render-effect demo experiments.
5
- *
6
- * The render effects (R4/R5: glow, god-rays, smoke puffs) are render OPTIONS the
7
- * three.js provider DECLARES through renderCapabilities() (driven via
8
- * runner.setRenderOptions — see lib/frqtl/compat/renderer/providers/three-provider.js).
9
- * Each fx-* experiment page is identical boilerplate EXCEPT a small config; this
10
- * module is the single source of that boilerplate (DRY — no per-page copy of the
11
- * runner / camera-control / boot dance).
12
- *
13
- * A page imports this module and its setup factory, and boots with the setup this file builds:
14
- * bootPage({ renderer: 'three', setup: fxExperimentSetup({
15
- * title: 'FX — Glow',
16
- * setup: setupParticleWalk3D, // the setup factory (imported by the page)
17
- * setupOpts: {}, // forwarded to the factory
18
- * renderDefaults: { glowIntensity: 2.2, heat: 0.6 }, // applied via setRenderOptions after setup;
19
- * // ALSO drives which effect sliders this page
20
- * // gets (see "RETIRED: controls" below — a page
21
- * // no longer separately declares a controls array).
22
- * presets: [ { name:'Comet', render:{...}, orbit:{azimuth,elevation,distance} }, ... ],
23
- * cameraPreset: 'down-barrel' // OPTIONAL: the experiment's DEFAULT
24
- * // camera view (a runner.cameraControl.presets
25
- * // name) — applied BEFORE the orbit sliders are
26
- * // seeded, so they reflect the actual starting
27
- * // view. Unset = current behavior (byte-identical).
28
- * loopTicks: 720 // OPTIONAL: default tick-length for the
29
- * // always-present loop control (see below).
30
- * // Unset -> 720 (the default).
31
- * }) });
32
- *
33
- * Surfaces it provides:
34
- * - In-page control bar (sliders + preset buttons) — visible when viewing the page
35
- * directly. Hidden by chrome=canvas (the GYM embeds the canvas only).
36
- * - runner.fxPresets = config.presets — the CAPABILITY the GYM (CompareView)
37
- * capability-CHECKS to render its own preset row (the page chrome is hidden there).
38
- * - runner.fxControls = config.controls — same, for the GYM's effect sliders.
39
- * - Loop control (ALWAYS present, no cfg opt-in needed — mirrors the always-present
40
- * camera-control-if-capable idiom): a checkbox + tick-count input that, when on,
41
- * re-runs `runner.setup(setupFn, cfg.setupOpts)` every N ticks — reuses the SAME
42
- * reset semantic `EGPTUniverse.init()` already provides (a fresh WASM instance
43
- * from the same seed), driven by the pre-existing per-tick `onTick` hook (never
44
- * `universe.experimentTickFunctions`, which is NOT cleared by `init()` and would
45
- * duplicate on every reset).
46
- * - `runner.loopControl` (the GYM is the visual-verification surface, so a tool that
47
- * exists only on the standalone page is NOT done): the SAME live object that
48
- * drives the in-page DOM above, published on the runner exactly like fxPresets/
49
- * fxControls/cameraControl — two renderers of ONE state, zero parallel state.
50
- * `runner.loopControl` = the `_buildLoopControl` state object,
51
- * extended with `setEnabled(v)`/`setTicks(n)` methods that ALSO update the
52
- * in-page checkbox/number-input (two-way sync — the GYM and the standalone page
53
- * agree because both mutate/read the SAME object). `loopControl` is always present
54
- * (mirrors the always-present in-page control).
55
- *
56
- * Effects are render-only. Every renderDefaults / preset key must be declared by the
57
- * active renderer: on a renderer that does not declare it (p5 declares no godrays) the
58
- * write THROWS naming the declared list. No renderer-sniffing anywhere.
59
- *
60
- * ── RETIRED: cfg.controls / runner.fxControls (Studio Controls Realignment) ─────
61
- *
62
- * Every fx-* page USED to hand-declare its own `controls: [{key,label,min,max,
63
- * step}, ...]` array — a bespoke vocabulary that duplicated `lib/shim/controls`'s
64
- * `scalar` kind shape one file over (the exact schema-mirror-drift class this
65
- * workstream exists to kill: the SAME shape, re-derived by hand, per page).
66
- * `_buildControls` (below) now MECHANICALLY derives the effect-slider set from
67
- * the active provider's `renderCapabilities()` (via
68
- * `MakeControlsForRenderSurface.makeControlsForRenderSurface`), filtered down
69
- * to the keys a page actually seeds via its OWN `cfg.renderDefaults` — so the
70
- * VISIBLE slider set is UNCHANGED per page (same keys, same min/max/step,
71
- * verified against every value every fx-glow/fx-godrays/fx-smoke page
72
- * hardcoded
73
- * before this migration; `CAPABILITY_LABELS` below preserves the SAME short
74
- * display text). `runner.fxControls` is still published (nothing external
75
- * reads it today — confirmed dead per `lib/features/ide/CompareView.jsx`'s own
76
- * "GYM un-hide" comment — but the capability name is kept for back-compat) —
77
- * its VALUE now comes from the SAME derived list, never a hand-authored one.
78
- */
79
-
80
- import { FrqtlApp } from '../../objects/FrqtlApp.js';
81
- import { MakeControlsForRenderSurface } from '../../objects/objects/makeControlsForRenderSurface.js';
82
- import * as OrbitBag from '../../compat/renderer/orbit-bag.js';
83
- import * as FrqtlDisplay from '../../compat/renderer/display-slot.js';
84
- import { KEYS } from '../../../shim/page-params/index.js';
85
- import { ExperimentMetrics } from './experiment-metrics.js';
86
- import { p5FrameRate } from '../../compat/vendor.js';
87
-
88
-
89
- // Short display labels for a handful of render capabilities whose fx-*
90
- // page sliders historically showed a terser word than the
91
- // capability's own name (§7 r2 item 3(b) retirement note above — COSMETIC
92
- // TEXT ONLY, not a second shape/bounds vocabulary; the shape/bounds
93
- // themselves come exclusively from renderCapabilities() now). One entry,
94
- // 'smoke' -> 'smoke', is the ONE deliberate, documented cosmetic delta:
95
- // fx-smoke's single slider previously said "puff" for this same capability —
96
- // every other page already said "smoke" for it, so this migration
97
- // standardizes on that shared label rather than inventing a THIRD per-page
98
- // label table.
99
- var CAPABILITY_LABELS = {
100
- godrays: 'rays',
101
- smoke: 'smoke',
102
- glowIntensity: 'glow',
103
- heat: 'heat',
104
- godrayDensity: 'spread'
105
- };
106
-
107
- // THE 3D-ness predicate (OrbitBag.hasAngularPose, lib/frqtl/compat/renderer/orbit-bag.js,
108
- // renderer phase): is the scene's camera angular? Asked of the handle's own poseFields — the
109
- // 2D p5 camera is a real handle too, so handle presence is never the test.
110
- function _sceneIs3D(runner) {
111
- return OrbitBag.hasAngularPose(runner.cameraControl);
112
- }
113
-
114
- // Deterministic seed passthrough: ?seed=<n> on the
115
- // PAGE URL overrides the FrqtlApp seed passed to the canonical seeding
116
- // surface (`FrqtlApp({seed})` -> `EGPTUniverse` constructor's `seed` param,
117
- // `lib/frqtl/objects/FrqtlApp.js:78,120` / `lib/frqtl/compat/providers/
118
- // wasm-engine.js:218,230,383`) — the SAME `URLSearchParams(window.location.search)`
119
- // idiom the boot module uses for `?engine=` (reused, not invented). Absent
120
- // or non-numeric `?seed=` -> falls back to 42, the EXISTING hardcoded default below
121
- // — byte-identical for every fx-* page that doesn't pass the param. This lives here
122
- // (not inside a setup factory) because the universe is CONSTRUCTED by
123
- // `new FrqtlApp(...)` — with its seed already baked in — BEFORE any setup
124
- // factory (e.g. `setupFxSmoke`) ever runs; a setup factory receives an
125
- // ALREADY-SEEDED universe and has no seeding surface of its own to reuse.
126
- function _readSeedFromUrl() {
127
- var raw = new URLSearchParams(location.search).get(KEYS.SEED);
128
- if (raw === null) { return 42; }
129
- var n = parseInt(raw, 10);
130
- return isNaN(n) ? 42 : n;
131
- }
132
-
133
- // Applies a {render:{...}, orbit:{...}} preset to the runner. `orbit` is an ANGULAR
134
- // framing — applied only on a camera that has angular axes (a partial angular framing on
135
- // the 2D camera would be a different framing, not a lesser one).
136
- function _applyPreset(runner, preset) {
137
- if (!preset) { return; }
138
- if (preset.render) { runner.setRenderOptions(preset.render); }
139
- if (preset.orbit && _sceneIs3D(runner)) {
140
- runner.cameraControl.setOrbit(preset.orbit);
141
- }
142
- }
143
-
144
- // Derives this page's effect-slider descriptor list from renderCapabilities()
145
- // (Studio Controls Realignment §7 r2 item 3(b) retirement — see the file
146
- // docstring's "RETIRED: cfg.controls" section). Filters the FULL provider
147
- // capability list down to the `scalar`-kind entries whose bind.prop is a key
148
- // this page ALREADY seeds via `cfg.renderDefaults` — so each page keeps
149
- // EXACTLY the slider set it always had (no page gains an unrequested godrays/
150
- // heat/smoke slider it never declared). Returns `[]` (never throws) when the
151
- // renderer declares no capabilities or the page has no renderDefaults.
152
- function _deriveEffectControls(runner, cfg) {
153
- var declaredKeys = cfg.renderDefaults ? Object.keys(cfg.renderDefaults) : [];
154
- if (!declaredKeys.length) { return []; }
155
- var renderSurface = MakeControlsForRenderSurface.makeControlsForRenderSurface({ runner: runner });
156
- return renderSurface.controls.filter(function (c) {
157
- return c.kind === 'scalar' && c.bind && declaredKeys.indexOf(c.bind.prop) !== -1;
158
- });
159
- }
160
-
161
- // Builds the in-page effect control bar (sliders + preset buttons) into the
162
- // existing .experiment-controls element. No-op pieces if the bits are absent.
163
- // Returns the derived effect-control list (published as runner.fxControls by
164
- // window.setup below — see the file docstring's retirement note).
165
- function _buildControls(runner, cfg) {
166
- var effectControls = _deriveEffectControls(runner, cfg);
167
-
168
- var bar = document.querySelector('.experiment-controls');
169
- if (!bar) { return effectControls; }
170
-
171
- // Effect sliders — one per derived control, seeded from renderDefaults.
172
- effectControls.forEach(function (d) {
173
- var key = d.bind.prop;
174
- var wrap = document.createElement('label');
175
- wrap.title = key;
176
- var startVal = (cfg.renderDefaults && typeof cfg.renderDefaults[key] === 'number')
177
- ? cfg.renderDefaults[key] : d.value;
178
- var labelText = CAPABILITY_LABELS[key] || key;
179
- wrap.appendChild(document.createTextNode(labelText + ' '));
180
- var input = document.createElement('input');
181
- input.type = 'range';
182
- input.min = d.min; input.max = d.max; input.step = d.step;
183
- input.value = startVal;
184
- var val = document.createElement('span');
185
- val.className = 'val'; val.textContent = startVal;
186
- input.addEventListener('input', function () {
187
- var v = Number(input.value);
188
- val.textContent = v;
189
- runner.setRenderOption(key, v);
190
- });
191
- wrap.appendChild(input); wrap.appendChild(val);
192
- bar.appendChild(wrap);
193
- });
194
-
195
- // Preset buttons (from cfg.presets) → apply + reflect into the sliders.
196
- if (cfg.presets && cfg.presets.length) {
197
- var presetWrap = document.createElement('span');
198
- presetWrap.appendChild(document.createTextNode('preset: '));
199
- cfg.presets.forEach(function (p) {
200
- var btn = document.createElement('button');
201
- btn.type = 'button'; btn.className = 'cam-preset'; btn.textContent = p.name;
202
- btn.addEventListener('click', function () {
203
- _applyPreset(runner, p);
204
- // Reflect the preset's render values back into the effect sliders.
205
- var inputs = bar.querySelectorAll('input[type="range"]');
206
- effectControls.forEach(function (d, i) {
207
- var key = d.bind.prop;
208
- if (p.render && typeof p.render[key] === 'number' && inputs[i]) {
209
- inputs[i].value = p.render[key];
210
- var sib = inputs[i].nextSibling;
211
- if (sib && sib.className === 'val') { sib.textContent = p.render[key]; }
212
- }
213
- });
214
- });
215
- presetWrap.appendChild(btn);
216
- });
217
- bar.appendChild(presetWrap);
218
- }
219
-
220
- return effectControls;
221
- }
222
-
223
- // ── Loop control (the in-page walkthrough tool) ───────────────────────────────
224
- // Re-run the simulation every X ticks (default 720), continuous — a fixed seed
225
- // gives an identical replay flipbook. GENERIC (every fx-* page gets it, not just
226
- // one page — capability-free, no cfg opt-in needed, mirrors the always-present
227
- // camera-control-if-capable idiom). Reuses the SAME reset semantic the GYM's own
228
- // "Reset" button relies on at bottom: `runner.setup(setupFn, opts)` re-runs the
229
- // setup factory, which calls `universe.init(...)` again — `EGPTUniverse.init()`
230
- // constructs a FRESH WASM instance from the SAME `_params.seed` each time
231
- // (`wasm-engine.js:308-409`, esp. `this._wasm = new _WasmUniverse(config)` at
232
- // line ~393) — an in-place, page-level restart with NO reload/hash-change (the
233
- // GYM's own Reset button instead bumps a React key to remount the WHOLE iframe —
234
- // a heavier, page-external mechanism; this loop control reuses the UNDERLYING
235
- // reset semantic `runner.setup()` already provides, not that outer mechanism,
236
- // since a tick-driven in-page loop can't remount its own iframe from the inside).
237
- // Registered via the ALREADY-EXISTING per-tick `onTick` callback (a page-level,
238
- // FrqtlApp-construction-time hook — chosen over `universe.
239
- // experimentTickFunctions.push(...)` specifically because THAT array is never
240
- // cleared by `init()`, so pushing a loop tick-fn there would duplicate on every
241
- // reset; `onTick` is registered exactly ONCE, at FrqtlApp construction,
242
- // and survives re-`setup()` calls cleanly).
243
- function _buildLoopControl(cfg) {
244
- var bar = document.querySelector('.experiment-controls');
245
- var cb = null; // set below IF the in-page control bar exists
246
- var numInput = null;
247
- var state = { enabled: false, ticks: (typeof cfg.loopTicks === 'number' && cfg.loopTicks > 0) ? cfg.loopTicks : 720 };
248
- // GYM capability methods (lib/features/ide/CompareView.jsx, chrome=canvas hides
249
- // this in-page control bar there): mutate the SAME `state` object the onTick
250
- // hook reads AND mirror into the in-page DOM when present — two-way sync, so
251
- // the GYM and the standalone page never disagree about the live loop state.
252
- state.setEnabled = function (v) {
253
- state.enabled = !!v;
254
- if (cb) { cb.checked = state.enabled; }
255
- };
256
- state.setTicks = function (n) {
257
- if (typeof n === 'number' && n > 0) {
258
- state.ticks = n;
259
- if (numInput) { numInput.value = n; }
260
- }
261
- };
262
- if (!bar) { return state; }
263
-
264
- var wrap = document.createElement('label');
265
- wrap.title = 'loop';
266
- wrap.appendChild(document.createTextNode('loop '));
267
- cb = document.createElement('input');
268
- cb.type = 'checkbox';
269
- cb.addEventListener('change', function () { state.enabled = cb.checked; });
270
- wrap.appendChild(cb);
271
- numInput = document.createElement('input');
272
- numInput.type = 'number';
273
- numInput.min = '1';
274
- numInput.style.cssText = 'width:60px; margin-left:4px;';
275
- numInput.value = state.ticks;
276
- numInput.addEventListener('change', function () {
277
- var n = parseInt(numInput.value, 10);
278
- if (!isNaN(n) && n > 0) { state.ticks = n; }
279
- });
280
- wrap.appendChild(numInput);
281
- bar.appendChild(wrap);
282
-
283
- return state;
284
- }
285
-
286
- // Wires the camera orbit sliders + presets + layer toggles IF the page declares them
287
- // (same id contract as particle-walk-3d) AND the camera is angular (az/el/dist sliders).
288
- function _wireCamera(runner) {
289
- var cam = runner.cameraControl;
290
- var host = document.getElementById('camera-controls');
291
- if (!host || !_sceneIs3D(runner)) { return; }
292
- host.style.display = 'inline-flex';
293
- var o = cam.getOrbit();
294
- function _set(id, v) { var el = document.getElementById(id); if (el) { el.textContent = v; } }
295
- var azEl = document.getElementById('cam-azimuth');
296
- var elEl = document.getElementById('cam-elevation');
297
- var diEl = document.getElementById('cam-distance');
298
- if (azEl) { azEl.value = Math.round(o.azimuth); _set('cam-azimuth-val', azEl.value); }
299
- if (elEl) { elEl.value = Math.round(o.elevation); _set('cam-elevation-val', elEl.value); }
300
- if (diEl) { diEl.value = Math.round(o.distance); _set('cam-distance-val', diEl.value); }
301
- function _wire(inputEl, labelId, key) {
302
- if (!inputEl) { return; }
303
- inputEl.addEventListener('input', function () {
304
- var v = parseInt(inputEl.value, 10);
305
- _set(labelId, v);
306
- var spec = {}; spec[key] = v; cam.setOrbit(spec);
307
- });
308
- }
309
- _wire(azEl, 'cam-azimuth-val', 'azimuth');
310
- _wire(elEl, 'cam-elevation-val', 'elevation');
311
- _wire(diEl, 'cam-distance-val', 'distance');
312
- function _sync() {
313
- var n = cam.getOrbit();
314
- if (azEl) { azEl.value = Math.round(n.azimuth); _set('cam-azimuth-val', azEl.value); }
315
- if (elEl) { elEl.value = Math.round(n.elevation); _set('cam-elevation-val', elEl.value); }
316
- if (diEl) { diEl.value = Math.round(n.distance); _set('cam-distance-val', diEl.value); }
317
- }
318
- (cam.presets || []).forEach(function (name) {
319
- var btn = document.getElementById('cam-preset-' + name);
320
- if (btn) { btn.addEventListener('click', function () { cam.setPreset(name); _sync(); }); }
321
- });
322
- }
323
-
324
- /**
325
- * The page's setup, built from its config (the file docstring) — bootPage({ setup }) runs it once
326
- * engine + renderer are live.
327
- * @param {object} cfg
328
- * @returns {function} setup
329
- */
330
- function fxExperimentSetup(cfg) {
331
- cfg = cfg || {};
332
- var setupFn = cfg.setup;
333
- if (typeof setupFn !== 'function') {
334
- throw new Error('[fx-experiment] fxExperimentSetup(cfg): cfg.setup is the setup FACTORY the page imports ' +
335
- '(e.g. import { setupParticleWalk3D } from "../../objects/setup/setupParticleWalk3D.js"), got ' +
336
- JSON.stringify(cfg.setup) + '. (FAIL-LOUD.)');
337
- }
338
- return function setup() { _runFx(cfg, setupFn); };
339
- }
340
-
341
- function _runFx(cfg, setupFn) {
342
- var metrics = null;
343
- var tick = 0;
344
-
345
- // Tick-based cinematic scheduler. Beats are keyed to the SIMULATION tick (which only
346
- // advances while the runner is actually running) — NOT wall-clock setTimeout. This keeps
347
- // a director's timeline aligned with the sim: it can't run ahead during a paused load
348
- // (e.g. the GYM starts paused) or while the user switches camera views, so the emitter
349
- // never gets cut before the user hits Run. `schedule(atTick, fn)` is passed to the director.
350
- var _beats = [];
351
- function schedule(atTick, fn) { _beats.push({ at: atTick, fn: fn, fired: false }); }
352
-
353
- // Filled in AFTER runner.setup() below (needs the built DOM to exist first) —
354
- // declared here so the onTick closure can see it.
355
- var loopState = null; // set by _buildLoopControl(cfg) — {enabled, ticks}
356
-
357
- var runner = new FrqtlApp({
358
- // The fx pages boot the three display (bootPage({ renderer: 'three' })), which IS the 3D
359
- // display: the provider is told so at init.
360
- is3D: FrqtlDisplay.name() === 'three',
361
- canvasParentId: 'canvas-wrapper',
362
- canvasW: 600,
363
- canvasH: 600,
364
- seed: _readSeedFromUrl(),
365
- onTick: function (tickData) {
366
- tick++;
367
- // Fire any cinematic beats now due (tick-based, not wall-clock).
368
- for (var b = 0; b < _beats.length; b++) {
369
- if (!_beats[b].fired && tick >= _beats[b].at) {
370
- _beats[b].fired = true;
371
- try { _beats[b].fn(); } catch (e) { console.error('[fx-experiment] beat threw:', e); }
372
- }
373
- }
374
- if (metrics) {
375
- var frames = (tickData && tickData.frameData) ? tickData.frameData : [];
376
- metrics.update({ 'Active Quanta': frames.length, 'Tick': tick });
377
- }
378
- // Loop control: "re-run the simulation every X ticks, continuous" — fixed
379
- // seed means every loop iteration replays the IDENTICAL physics stream.
380
- // Checked LAST so this tick's beats/metrics still reflect the run
381
- // that just completed before the reset takes effect on the NEXT tick.
382
- if (loopState && loopState.enabled && tick >= loopState.ticks) {
383
- tick = 0;
384
- _beats.forEach(function (bt) { bt.fired = false; });
385
- runner.setup(setupFn, cfg.setupOpts || {});
386
- }
387
- }
388
- });
389
-
390
- runner.createCanvas();
391
- runner.setup(setupFn, cfg.setupOpts || {});
392
-
393
- // Metrics panel (optional — only when the page has the panel element).
394
- if (document.getElementById('metrics-panel')) {
395
- metrics = new ExperimentMetrics('metrics-panel', [
396
- { name: 'Active Quanta', expected: null, format: function (v) { return String(Math.round(v)); } },
397
- { name: 'Tick', expected: null, format: function (v) { return String(v); } }
398
- ]);
399
- }
400
-
401
- // Apply the effect's render defaults — one validated batch.
402
- if (cfg.renderDefaults) { runner.setRenderOptions(cfg.renderDefaults); }
403
-
404
- // Expose presets so the GYM (CompareView) — which hides the page chrome —
405
- // can render its own preset row by capability-CHECKING the runner.
406
- runner.fxPresets = cfg.presets || [];
407
-
408
- // Optional per-experiment DEFAULT camera view (down-barrel = the DEFAULT
409
- // view). Declared ONCE on the config's cameraPreset
410
- // (a preset name from runner.cameraControl.presets, e.g. 'down-barrel') — applied
411
- // BEFORE _wireCamera() seeds the orbit sliders, so the sliders reflect the ACTUAL
412
- // starting view rather than the renderer's generic fallback orbit. A 3D preset name,
413
- // so applied only on an angular camera (no-op in 2D / when unset) — every existing
414
- // fx-* page that doesn't declare this field is byte-identical.
415
- if (cfg.cameraPreset && _sceneIs3D(runner)) {
416
- runner.cameraControl.setPreset(cfg.cameraPreset);
417
- }
418
-
419
- _wireCamera(runner);
420
- // fxControls is now published from the SAME derived list _buildControls
421
- // renders sliders from — never a hand-authored cfg.controls array (§7 r2
422
- // item 3(b) retirement; see the file docstring).
423
- runner.fxControls = _buildControls(runner, cfg);
424
- // The generic loop control (every fx-* page gets it — the in-page walkthrough tool),
425
- // published as a runner capability exactly like fxPresets/fxControls/cameraControl.
426
- loopState = _buildLoopControl(cfg);
427
- runner.loopControl = loopState;
428
-
429
- // 3D experiments default to a VIEWING cadence (capped TPS → smooth FPS).
430
- if (_sceneIs3D(runner)) { runner.setRateLimits({ fpsLimit: 0, tpsLimit: 120 }); }
431
-
432
- runner.start();
433
- p5FrameRate(60);
434
-
435
- // OPTIONAL director — a cinematic timeline. Called once AFTER start with the runner +
436
- // the setup factory's return handles (runner.setupResult: { emitter, … }).
437
- // It schedules the beats (setRenderOption changes, emitter stop, LO reveal) over time.
438
- // Opt-in for a cinematic experiment; absent on the plain fx-* demos.
439
- if (typeof cfg.director === 'function') {
440
- // director(runner, handles, schedule): schedule(atTick, fn) for one-shot tick-based beats
441
- // (robust to the GYM's paused-then-Run model), NOT setTimeout. Continuous per-tick control
442
- // (e.g. an emission ramp) belongs in the SETUP factory as an experimentTickFunctions
443
- // tick-fn — the same contract Blackbody's thermostat + the Bullet use.
444
- try { cfg.director(runner, runner.setupResult, schedule); }
445
- catch (e) { console.error('[fx-experiment] director threw:', e); }
446
- }
447
- }
448
-
449
- export { fxExperimentSetup };
Binary file
Binary file