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

package/CLAUDE.md

@@ -2,7 +2,7 @@
 
 A discrete cellular-automata physics engine (compiled Rust → WASM) for node: the same modules as
 `@descix/frqtl-web` (one source, built twice), plus the node engine door `bootNode` and the hosted eyes.
-`0.6.1-p3.2` (npm dist-tag `next`). Node ≥ 22.12.
+`0.6.1-p3.3` (npm dist-tag `next`). Node ≥ 22.12.
 
 ## Install
   npm install @descix/frqtl-node

package/README.md

@@ -4,7 +4,7 @@ FRQTL for node: a discrete cellular-automata physics engine (compiled Rust → W
 local per-pixel rules — a frame moves one pixel per tick, single occupancy, momentum — rather than force
 equations. Interference, blackbody spectra and atom-like binding emerge from the automaton.
 
-`0.6.1-p3.2` (npm dist-tag `next`). Node ≥ 22.12.
+`0.6.1-p3.3` (npm dist-tag `next`). Node ≥ 22.12.
 
 ## Install
 

package/dist/dist-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/frqtl-node",
-  "version": "0.6.1-p3.2",
+  "version": "0.6.1-p3.3",
   "files": {
     "eyes/index.js": "b3563421030bb7fdd277eb697959fbe9107463cbb5478160edc7d887daa67be3",
     "fat/pkg-node/egpt_wasm.js": "5e6af1f6725c93c0e9ad7386f1785cbe639ce596a4caa19ca85729c1f2bea04d",
@@ -26,21 +26,21 @@
     "frqtl/compat/renderer/display-slot.js": "8a2e99836dcc2f95155f2cd8ffeb9267054e3848c2e8f2ce320ebaca22f80a9e",
     "frqtl/compat/renderer/lo-drawn-center.js": "5d285c8e6b0775db336de559855d28d752aed7544610f0430d8a389c530673cc",
     "frqtl/compat/renderer/orbit-bag.js": "b6671d3b35fcf5f79e228934a8032e729309e62b66920602f34c834f3f911681",
-    "frqtl/compat/renderer/providers/godrays-layer.js": "be76fb8e69c74dd9bd0fb9aa6189a816d0ed29b9f4e04b60277be375b93d606c",
+    "frqtl/compat/renderer/providers/godrays-layer.js": "fdfde9469cdeefce87785a648b77ed46ead22de46369b3b70212446ef3cbb850",
     "frqtl/compat/renderer/providers/index.js": "fa669158a082a0081125c81694ca79962639caf86a575ee198a815f3e13a19e7",
-    "frqtl/compat/renderer/providers/p5-provider.js": "39aa68c2232b123ed52ca235f264cfb57993f46a41d4b0ed8139bffbac2f64ac",
+    "frqtl/compat/renderer/providers/p5-provider.js": "d247d81c785b1d45b863a9e4081b2b85302106ddc0de75aece0f9a9553dabbc9",
     "frqtl/compat/renderer/providers/three-camera-contract.js": "644c1cc5e381cd2af897e69762216f84716808eeb5948efb989f48c47696bc60",
     "frqtl/compat/renderer/providers/three-camera-geometry.js": "a741f72c34005fc47fb4d53cc7ef2d2df4bfa7e8eecc9a0252b1083b3d5e301a",
-    "frqtl/compat/renderer/providers/three-provider.js": "08410c488dcf3290d0a950331f33d8ba6882a391308d4d4598d9cb9aa96a4c9a",
+    "frqtl/compat/renderer/providers/three-provider.js": "30fc893f303144cd6fff66092c2e42e9880f7dc2da4fe6a27878d9b5b0c2e8dc",
     "frqtl/compat/renderer/renderCapabilities-common.js": "4e4bf31a8ab5b4b938fdbd517e30d28e9c8e90251b6fe1dbaafd575bf2d4ccf3",
     "frqtl/compat/renderer/renderer-provider-contract.js": "295574c6b10ce4c335b7c9a83941f3c1723b412c21f0004501add45e533bdb5a",
     "frqtl/compat/renderer/unprojectStill.js": "43c4286c124eaa238d963fe3ae5551a1c87727809d5245a129f368a117863c45",
     "frqtl/compat/vendor.js": "2393ada71cdbe750d409174e1ba9b098148796efdff746b315d706a0b32e58e8",
     "frqtl/experiments/_shared/boot-failure.js": "1a92e85b06acdefede5613f2fac7cd4e61d2aba590820f1bfa92f6829fcbbdd4",
     "frqtl/node-entry.js": "a401039b4fcf53ac620edbd80985aa4448122f2e3caaeaf4d5595f5e9d512b60",
-    "frqtl/objects/FrqtlApp.js": "e3232b09eb576427df2a52393a5603b4c084d6edba5667b03afb161fd6d76b9b",
+    "frqtl/objects/FrqtlApp.js": "bc4b4b2206588cd91fc8454b058a11d4b8b797fa3064e32af12be81d2d927d6e",
     "frqtl/objects/ObjectFactory.js": "a8f050ce61b7ab9c9b4f81e9eeaebf05c3cc0b532c741ce93d6e952489772b11",
-    "frqtl/objects/RecipeContext.js": "4d53e1d8a48f4567aeb882abac6f46cd649a51a3af4b543a6bec7ce74e77d7a8",
+    "frqtl/objects/RecipeContext.js": "4dafe289b2a5f768529d340e0d3876ddd8c72b4c295a37c00f77efe02912fc7c",
     "frqtl/objects/collectors/DataCollector.js": "8736d6cb77eec36ce2adcf2bc3b0d2436eeb70a73b77182ff053efdc6ca071df",
     "frqtl/objects/constants/WallBehaviors.js": "a05c6e06923962e2cc2cf7204131e5d20bf83c5c8e85fbb13867872040345e40",
     "frqtl/objects/geometry/SlabFace.js": "847921b124d3bc1692e88c363c087d392a1baa7c652a3a61e381d0f8a8342e57",
@@ -73,7 +73,7 @@
     "frqtl/objects/objects/slitLinerScatter.js": "9413cc7efa2132c68d7b4d5030af28d92e8d085e127d5c8e1568d0028da2fc13",
     "frqtl/objects/objects/sustainedSource.js": "0c324cef1583226d090b4d1014c2576ef8237f1bad47c1511bed3c3f81e04206",
     "frqtl/objects/objects/tagger.js": "e2a5ef9ae68466afb6b157ca6d7ce03a6f126d8c91c9f9d4be6dba8e928535eb",
-    "frqtl/objects/record/Record.js": "5555c62e278654d1d54e2e3d89da4100de2d0ccae9563e62dfe4082ec7b543ba",
+    "frqtl/objects/record/Record.js": "fea53f9ae9c72e216f1e9ca7e2035c093e3135ccd132918ff6abd299fac6057b",
     "frqtl/objects/record/open-record.js": "2da2abcccd3ad5bc39eb7fcfb764601cd031dd0afa9b3c9cb96b0669621827df",
     "frqtl/objects/schema/engine-scopes.js": "d9d07914f748f9e7f86cc68e4d49da3b07d2bce37fea5280a88e6862ef3bb619",
     "frqtl/objects/schema/index.js": "74ba0b6a6e057cfd40edf2ce41fcce7206c0204e90eeee4a8db3b711f10ffd33",
@@ -112,21 +112,21 @@
     "frqtl/parts/DetectorWall.js": "d39ab88056fa28c322863430f8bad9704879e5d8149f1ac65adf1add057996f5",
     "frqtl/parts/FrqtlControlOverlay.js": "f862b1529265224aa96878b56b0c1c6e65683ba3fd6b517df86e17e92147f9c4",
     "frqtl/parts/FrqtlControlsPanel.js": "792d03dea218bdc335ba7e04362be620edbfa331bed9de087d61942299728cc1",
-    "frqtl/parts/FrqtlVision.js": "118d0874249fa55783b196fd01297b3347951267a4add93381433a72c46e8622",
+    "frqtl/parts/FrqtlVision.js": "217472e195ccd588cccd8be9fe9419836b66c96c20509fa7d4320a57116bb0b3",
     "frqtl/parts/GraphingDetectorWall.js": "a2fef24c2ef00416792c4b46a09c9544601e45e84593fa2287d2311f27a1bcee",
     "frqtl/parts/LargeObject.js": "d6cae738b30965f3eba4be4399fb4410f17afc3267b51e3ad9e1ba7423e17922",
     "frqtl/parts/LightColor.js": "8637e5a09bbad3a4fdd2034ccb44dfc1fda743e29b12b4c685a64b9e1df28daa",
-    "frqtl/parts/LiveChart.js": "8bd0b862d2f7a4e818ae9cfc47e5e0f56eb97ea0a00fb836bba3f2374c12a1ce",
+    "frqtl/parts/LiveChart.js": "5d31947db9909e7a85dcbd99560e49b3f24ad60aea13f24b736a04d45998f060",
     "frqtl/parts/LogicGate.js": "05716711db1794ce9e29027ea16af083e5a1cc8b0657dce853cb6d2f6ee1fc02",
     "frqtl/parts/OvenBox.js": "7e393dd736c6ae410d85e5fe3edbea8677e5834bd1fe7b19d4e8f46af13764ac",
     "frqtl/parts/PointSource.js": "57b3b8353cba8c5ebfff6653e39948c9f0ee240449b4af08247687d3d9d9f092",
     "frqtl/parts/Rectangle.js": "8be4cae13135c3cb185d025dfd10d3a03b21d5627bfa92363c2faa021f751571",
     "frqtl/parts/SlitLightSource.js": "89a17aaade03e2e961af4181e6c3fd479d31c2c3298c46abc477a13f26d7a07a",
     "frqtl/parts/SlitScreen.js": "bdcaa761d0aa68c415a06ab2c523a8d4553a4c48cee00fe33d5df994adcf599a",
-    "frqtl/parts/SphereEmitter.js": "645664f5a20924b777d9b4ad6fef6338e7de251d62c7f8a4c93e6b0f97b47d4a",
+    "frqtl/parts/SphereEmitter.js": "bf801404c67ff26dbf61353ea617fcefcff5a546c2e62f4d4afb95e9781c7a5e",
     "frqtl/parts/Trace.js": "f9d91bb9435bc5fabfd7bfdbfbf3f3ae34e2338090251d9e9d6c11abc2ed25fb",
-    "frqtl/parts/Tunnel.js": "66bfca3d3d88ebf9a8cb7aa248b92cfc7d78a278449830b03e6b2700a21df891",
-    "frqtl/parts/Wall.js": "34f8e4f5143925b42e42561eb54e93b0c1244debeb5c07a914beba3e8c4c75fd",
+    "frqtl/parts/Tunnel.js": "7a7c3e52caa5f018178c596d735e6062c4cac1545d014216d3027ba9f457d07d",
+    "frqtl/parts/Wall.js": "7af7a41f7c8348deee1237a20e37e9c0e69cd3669ab315efaa8eeac03fbbccb8",
     "frqtl/parts/index.js": "70b8e227e09663889f4c7942d385f843d977579765723f829880fd6e9868ac53",
     "frqtl/scenes/absorbing-wall-3d.js": "722bb433142833f03150052b95039686aba0d9db510a5ff13fad95b5f17e0cf8",
     "frqtl/scenes/absorbing-wall.js": "0a47ca64e56481841339cd5882cf0e54ec7c14d87a4306d016ead1ff26591197",
@@ -141,13 +141,13 @@
     "frqtl/scenes/dse-one-emitter.js": "619892663838e0f018b9ade83c9994fb0709b9ed9904c92e41470a7b7fdd396f",
     "frqtl/scenes/dse-one-slit.js": "7bf299e3cc64dd3d1f8df805eec63d98d36b8592d55e3ef478d46c38bf674812",
     "frqtl/scenes/dse-photoelectric.js": "e0402c4508a4d97d3d9461f889b10a49da82ef5f232d81455c5e482db8b0bda6",
-    "frqtl/scenes/dse-tunnel-rebuild.js": "c662bff31fb66c1f136b6f35d18943c58e97456b61fbab9f4cdb812e3acb2630",
+    "frqtl/scenes/dse-tunnel-rebuild.js": "c2721b4460dbe2f38e7e3bcff6f8498fd798c3404b807931b288ae2ccd43eec5",
     "frqtl/scenes/dse-two-emitters.js": "74cf1d4b226b0ce4e337697a0327de9b95190159b2554f53e629d89525321877",
     "frqtl/scenes/dse-two-slits.js": "f303a848d9c463a5a9443c380b257795b19127b122bdd2fcb28855841b219939",
     "frqtl/scenes/empty.js": "f3c2161f7bbc1be2d7fba0f117ac16b9e60966d9448877ead4037e3cb4fee678",
     "frqtl/scenes/laser-buildup.js": "f4b29b2eeeca730642f5adf2f499f6594b73f6e51ba6aa9a237f4ee643c5cf23",
     "frqtl/scenes/mirror-3d.js": "79ac794dfbc608037936908a9fe58ca34be93be6263d5940bb38129d55bb7943",
-    "frqtl/scenes/mirror-route.js": "007af9eb382a1392eb22b6d81f7c3e40bffe7ba6ac53363ce7726ccb62b838c4",
+    "frqtl/scenes/mirror-route.js": "1407dd7a39c0efcd5ea0f028d67299c1ca4153c1c0cab2bb36d10416f1129931",
     "frqtl/scenes/mirror.js": "c7bcd440e9a78e333fd81d906b3788a62342910f46cf98de860098fcc1e0ba91",
     "frqtl/scenes/omni-3d.js": "d420a7aae9fdfd394b9288ce1f0256416e1b07f70bc570a928a4592c32a47c27",
     "frqtl/scenes/omni-source.js": "4f9aaa0e0ccbf4d18908d1628688dbeae376b535318f0cf969d61d8ea8f90b83",
@@ -166,13 +166,13 @@
     "shim/engine/artifact-shell.js": "f23c327500f8174b12d464868f6ec9c1701e7a9a5faa1c43a2ddafc3191dc38c",
     "shim/engine/boot-phases.js": "c6e12e12824bcf6f1a289f46e41c898a5416c80c131594525145aae9a3eefbfa",
     "shim/engine/engine-stack-boot.js": "0abf57dcff2ca2bb025c787a17875d49d54d9218ac08c78cb9c678dbb6118d08",
-    "shim/engine/router.js": "1c8bed954aecfcd06d1344051d8489f0f040967f9d0879ec7e7a0d1e58045d2c",
+    "shim/engine/router.js": "a2582ce456f5cee9ac4d9d2117afdf4dce59e7e3e009f483dbd0f8d0a4c3cb8e",
     "shim/engine/site-graph.js": "b0d2569c67516d08bba17a152d5d3bfa0b036666eda7f11df74b4d68854e1b93",
     "shim/experiment-frame/index.js": "5a0219aaa225d8f808c405b08623ce85ada37d83fb4f55f983db3303e431e47f",
     "shim/expr/ast-schema.js": "4f1133b887639bbd86fab976292323bf4a955cdc873ff7ca8e8a8eb3b416923f",
-    "shim/field-descriptor/index.js": "6647d57d1523519114adc0a5cb66335ec5121c39ab294b9c97bdfb9e5d7f61e0",
+    "shim/field-descriptor/index.js": "050091a9cab0bd37b32b5d8a52fc9bca3b42a089c188d7e49a11cf88b5c069f7",
     "shim/frame-data/index.js": "df6957b0b4a8e0ee0035bc970647b90089b421ae7f05911cc047d48457164be6",
-    "shim/host/device.js": "85470e7c787398cb91516b724e884ac50104d56330ba7ff876308b6fb4b7b532",
+    "shim/host/device.js": "7dd8d069463141e4f8bdc8827d747c0a9e27ad7ec1d2c6feaaad6e58f0bed512",
     "shim/host/host-view.js": "feec2f5fdc318e75cd01768c24891f85d2694a269696fcfffd9567d31983cf43",
     "shim/host/index.js": "fade4b171218965570aa2e67e841920ebb3d972ff15e1cfa0394fd3fa123d82c",
     "shim/index.js": "96165c6161ffddbace0be0cde0b3a83943298531537dd2cc9c6e281b8274ff19",
@@ -210,19 +210,19 @@
     "shim/project/register-node.mjs": "9b408da7dc1b11d16237cd62caca281c823ea80173d386ad35e41ea17c34857f",
     "shim/project/specifiers.js": "288e5e06e53b873449190f6f85855177a72e52623bd11eef016acafb8095d829",
     "shim/registry/copy-gate.js": "cfbf52669c849b8837b326f2743458f1ead0720cad51a6c6d409c9bd6c7f9495",
-    "shim/registry/exhibits.js": "e137951429929dae6c38e996546b66dd19b575ee4f0aafbddf28096c847a27fc",
+    "shim/registry/exhibits.js": "5a2f085c8a6b012114796897ec284f2bdd5081936b4e474d6227318c67dfb48a",
     "shim/registry/index.js": "3a96c6b8790058663bb3157f6daecbcc199c2472d096b413e1766dd279832c05",
     "shim/registry/scene-roster.js": "318fe373f71b1c58d05425693f2fad4bd5368f6095b65817c6d637430a0bfb73",
     "shim/registry/scene-source.js": "c9c4b48c24d4b1ebee1549a7891a1ba708909b94b9403ce28eefbd902cacf49f",
     "shim/registry/showcase-link.js": "daf5c1426aeb3c578bace5e0edea9ba2538cd82336d2cdc944e5fed6decd7551",
     "shim/registry/studio-landing.js": "bd81ad9333332de4a29b3121f963edd354450c75c97f4f43170a98c2dcceb7f3",
-    "shim/registry/walkthrough.js": "8f8b6f59e9e81c67c9c62f8fb271eee2e4d6e1fba6e116b227a2f1e3f9930230",
+    "shim/registry/walkthrough.js": "439e03fc6c85e5982a98049118dc89f33c498778c1f3349bbbe8f60d64761071",
     "shim/render-state/apply.js": "94a9e60cb1722c9a82aa00f2f161fd65e6f438147333856a786e42a4ad5b7064",
     "shim/render-state/index.js": "72a6a3dcd8037893cb8fbd7ef32b126770e7efaec70847f8e4f2915ddb690b43",
-    "shim/render/capture-envelope.js": "2667a355169bb124fd8117e9cbf1d630085257b9f6fa537362f12d0aa649da2d",
+    "shim/render/capture-envelope.js": "74db53dbc8c87d1b52452bcb858b1cc5210593062fec0b98609cd59cab63777a",
     "shim/render/heat-colormap.js": "0eadc758179024734c45eaeffd8f5b44e7c4102b7042767a4a5b66541b3bbd7c",
     "shim/render/render-stages.js": "baf674c205df7638af53e51ac77152a448fe6bf6d4ea51d58ac565556cd38da7",
-    "shim/render/sun-look.js": "f8f23f0853a9c22459fff866ccf59ab00332697d48fd529fca5c2e8554a2d83d",
+    "shim/render/sun-look.js": "95cf56ee8a5c8da107323bf0dd33568e68e2a8bb2d9a5d61a3453a1b9d28ba2c",
     "shim/rpc/index.js": "56af3afeed22e8d718cd2f7a8ad70db8745f54dbc139af9d71f1d73e2ca37698",
     "shim/runtime/index.js": "92bb4d8b5f203f949e441781b864efe5c6748df14a3a8f306e4c0bc11c7f6d35",
     "shim/storage/boot.js": "689504e15dc075e32d08abf61c75a45b1d565c09f086b42400dae40d8186c411",

package/dist/frqtl/compat/renderer/providers/godrays-layer.js

@@ -2,7 +2,7 @@
 
 /**
  * godrays-layer.js — the three provider's god-rays layer: WHAT the rays are computed from
- * (the source rule), the light position, and the radial march + composite passes.
+ * (the source rule, `godraySource`), HOW (`godrayMode`: streak | field | radial), and the passes.
  *
  * God-rays are a render effect computed from the density of the LIGHT particles: by default
  * (`godraySource: 'leaf'`) the frames of the fundamental (lowest) layer. A parent frame at a higher layer is drawn in the scene
@@ -96,6 +96,140 @@
         return out;
     }
 
+    /**
+     * The `godrayMode` render option — the ONE owner of its values and default. HOW the rays are
+     * computed from the source frames:
+     *   'streak' (default) — each source frame trails a short streak BEHIND it along its own
+     *                        projected direction of travel (FrameData vx,vy,vz: the mean axis);
+     *   'field'            — every source frame's projected direction is splatted into a
+     *                        direction grid; each pixel's march steps UPSTREAM along the local
+     *                        direction, so the shafts extend ahead of the light and bend with the flow;
+     *   'radial'           — every pixel marches toward ONE light point (`lightUV`).
+     * `godrayDensity` is the reach in every mode: the march's fraction of the distance to the
+     * light (radial), the streak length (streak), the march length (field).
+     */
+    var GODRAY_MODES = ['streak', 'field', 'radial'];
+    var GODRAY_MODE_DEFAULT = 'streak';
+
+    /**
+     * The effective mode for a bag value: unset → the default; anything not declared THROWS.
+     * @param {*} value — opts.godrayMode
+     * @returns {'streak'|'field'|'radial'}
+     */
+    function resolveGodrayMode(value) {
+        if (value === undefined || value === null) { return GODRAY_MODE_DEFAULT; }
+        if (GODRAY_MODES.indexOf(value) === -1) {
+            throw new Error('GodraysLayer: godrayMode ' + JSON.stringify(value) + ' is not one of [' +
+                GODRAY_MODES.join(', ') + '] (default ' + JSON.stringify(GODRAY_MODE_DEFAULT) + ').');
+        }
+        return value;
+    }
+
+    // Screen-fraction scales (of the screen's SHORT side) the density knob multiplies.
+    var STREAK_REACH = 0.06;      // streak length = godrayDensity × this
+    var STREAK_WIDTH = 0.004;     // streak width (floor 1.5 physical px)
+    var STREAK_GAIN  = 0.6;       // streak brightness relative to the source pixel at the head
+    var FIELD_REACH  = 0.25;      // field march length = godrayDensity × this
+    var FIELD_CELLS  = 96;        // direction-grid columns along the LONG side
+    var FIELD_RADIUS = 3;         // splat radius in grid cells (tent weight)
+    var MARCH_SAMPLES = 50;       // steps per pixel in the radial and field marches
+
+    /**
+     * Each frame's head in screen UV and its projected direction of travel as a UNIT vector in
+     * PIXEL space (aspect-corrected). The direction is the projection of (pos + d̂) minus the
+     * projection of pos, d̂ = normalize(vx,vy,vz). A frame with no direction, one whose direction
+     * projects to under 1e-6 px (along the view axis), or one outside the clip volume yields NO
+     * entry: it still draws in the scene as itself, a dot with no streak and no flow.
+     * @param {Array<object>} frames — FrameData (rect.x, rect.y, z, vx, vy, vz)
+     * @param {Function} project — (x,y,z) → NDC {x,y,z}
+     * @param {number} w @param {number} h — the target's pixel size
+     * @returns {{count:number, u:Float32Array, v:Float32Array, dx:Float32Array, dy:Float32Array}}
+     */
+    function screenDirections(frames, project, w, h) {
+        var n = frames.length;
+        var out = { count: 0, u: new Float32Array(n), v: new Float32Array(n), dx: new Float32Array(n), dy: new Float32Array(n) };
+        for (var i = 0; i < n; i++) {
+            var f = frames[i];
+            var vx = f.vx || 0, vy = f.vy || 0, vz = f.vz || 0;
+            var len = Math.sqrt(vx * vx + vy * vy + vz * vz);
+            if (len === 0) { continue; }
+            var x = f.rect.x, y = f.rect.y, z = f.z || 0;
+            var p0 = project(x, y, z), x0 = p0.x, y0 = p0.y, z0 = p0.z;
+            if (!(Math.abs(x0) <= 1 && Math.abs(y0) <= 1 && Math.abs(z0) <= 1)) { continue; }
+            var p1 = project(x + vx / len, y + vy / len, z + vz / len);
+            var px = (p1.x - x0) * w / 2, py = (p1.y - y0) * h / 2;
+            var pl = Math.sqrt(px * px + py * py);
+            if (!(pl > 1e-6)) { continue; }
+            var k = out.count++;
+            out.u[k] = x0 * 0.5 + 0.5; out.v[k] = y0 * 0.5 + 0.5;
+            out.dx[k] = px / pl; out.dy[k] = py / pl;
+        }
+        return out;
+    }
+
+    /**
+     * Screen-space streak quads (two triangles each), in NDC: the head at the frame, the tail
+     * `lengthPx` BEHIND it (opposite its direction), `widthPx` wide. Per vertex: `head` (the head's
+     * UV, where the colour is sampled) and `fade` (1 at the head, 0 at the tail).
+     * @param {object} dirs — screenDirections(...)
+     * @returns {{count:number, position:Float32Array, head:Float32Array, fade:Float32Array}}
+     */
+    function streakQuads(dirs, lengthPx, widthPx, w, h) {
+        var n = dirs.count, pos = new Float32Array(n * 18), head = new Float32Array(n * 12), fade = new Float32Array(n * 6);
+        var sx = 2 / w, sy = 2 / h, half = widthPx / 2;
+        for (var i = 0; i < n; i++) {
+            var hx = dirs.u[i] * 2 - 1, hy = dirs.v[i] * 2 - 1, dx = dirs.dx[i], dy = dirs.dy[i];
+            var tx = hx - dx * lengthPx * sx, ty = hy - dy * lengthPx * sy;
+            var nx = -dy * half * sx, ny = dx * half * sy;
+            // head+n, head-n, tail+n ; tail+n, head-n, tail-n
+            var vs = [hx + nx, hy + ny, 1, hx - nx, hy - ny, 1, tx + nx, ty + ny, 0,
+                      tx + nx, ty + ny, 0, hx - nx, hy - ny, 1, tx - nx, ty - ny, 0];
+            for (var j = 0; j < 6; j++) {
+                var o = i * 6 + j;
+                pos[o * 3] = vs[j * 3]; pos[o * 3 + 1] = vs[j * 3 + 1]; pos[o * 3 + 2] = 0;
+                fade[o] = vs[j * 3 + 2];
+                head[o * 2] = dirs.u[i]; head[o * 2 + 1] = dirs.v[i];
+            }
+        }
+        return { count: n * 6, position: pos, head: head, fade: fade };
+    }
+
+    /**
+     * The direction field: a `gw × gh` RGBA grid (row 0 = bottom, UV v = 0). Each direction is
+     * splatted with a tent weight over `radius` cells; a cell stores its normalized mean direction
+     * in R,G (0.5 + 0.5·d̂) and in B the strength a = coherence × coverage (coherence = |mean|,
+     * 0 where opposed flows cancel; coverage = min(1, Σweight)). Decode: d = (RG·2 − 1)·B.
+     * @param {object} dirs — screenDirections(...)
+     * @returns {{width:number, height:number, data:Uint8Array}}
+     */
+    function buildDirectionField(dirs, gw, gh, radius) {
+        var cells = gw * gh, sx = new Float32Array(cells), sy = new Float32Array(cells), sw = new Float32Array(cells);
+        for (var i = 0; i < dirs.count; i++) {
+            var cx = dirs.u[i] * gw - 0.5, cy = dirs.v[i] * gh - 0.5;
+            var i0 = Math.max(0, Math.ceil(cx - radius)), i1 = Math.min(gw - 1, Math.floor(cx + radius));
+            var j0 = Math.max(0, Math.ceil(cy - radius)), j1 = Math.min(gh - 1, Math.floor(cy + radius));
+            for (var j = j0; j <= j1; j++) {
+                for (var ii = i0; ii <= i1; ii++) {
+                    var ex = ii - cx, ey = j - cy, wt = 1 - Math.sqrt(ex * ex + ey * ey) / (radius + 1);
+                    if (wt <= 0) { continue; }
+                    var c = j * gw + ii;
+                    sx[c] += dirs.dx[i] * wt; sy[c] += dirs.dy[i] * wt; sw[c] += wt;
+                }
+            }
+        }
+        var data = new Uint8Array(cells * 4);
+        for (var k = 0; k < cells; k++) {
+            var r = 0.5, g = 0.5, a = 0;
+            if (sw[k] > 0) {
+                var mx = sx[k] / sw[k], my = sy[k] / sw[k], m = Math.sqrt(mx * mx + my * my);
+                if (m > 1e-6) { r = 0.5 + 0.5 * mx / m; g = 0.5 + 0.5 * my / m; a = m * Math.min(1, sw[k]); }
+            }
+            data[k * 4] = Math.round(r * 255); data[k * 4 + 1] = Math.round(g * 255);
+            data[k * 4 + 2] = Math.round(a * 255); data[k * 4 + 3] = 255;
+        }
+        return { width: gw, height: gh, data: data };
+    }
+
     // R4-B god-rays — radial light-scattering march (adapted from abberg's
     // VolumetericLightShader / GPU Gems 3). For each pixel it steps TOWARD the
     // projected light position, accumulating SOURCE brightness with exponential
@@ -110,7 +244,7 @@
         'uniform float uWeight;',
         'uniform float uExposure;',
         'varying vec2 vTexCoord;',
-        'const int SAMPLES = 50;',
+        'const int SAMPLES = ' + MARCH_SAMPLES + ';',
         'void main() {',
         '  vec2 tc = vTexCoord;',
         '  vec2 delta = (tc - uLightPos) * (1.0 / float(SAMPLES)) * uDensity;',
@@ -126,6 +260,64 @@
         '}'
     ].join('\n');
 
+    // The 'field' march: the radial march's accumulation (same decay/weight/exposure), but each
+    // step reads the LOCAL direction from the field and steps upstream along it, so a pixel
+    // collects the light that flowed into it. An empty cell (strength 0) does not step.
+    var GODRAY_FIELD_FRAG = [
+        'uniform sampler2D uScene;',
+        'uniform sampler2D uField;',
+        'uniform vec2  uStepUV;',     // one step's length in UV per unit pixel-space direction
+        'uniform float uDecay;',
+        'uniform float uWeight;',
+        'uniform float uExposure;',
+        'varying vec2 vTexCoord;',
+        'const int SAMPLES = ' + MARCH_SAMPLES + ';',
+        'void main() {',
+        '  vec2 tc = vTexCoord;',
+        '  vec3 rays = vec3(0.0);',
+        '  float decay = 1.0;',
+        '  for (int i = 0; i < SAMPLES; i++) {',
+        '    vec3 f = texture2D(uField, tc).rgb;',
+        '    tc -= (f.rg * 2.0 - 1.0) * f.b * uStepUV;',
+        '    vec3 s = texture2D(uScene, tc).rgb;',
+        '    rays += s * decay * uWeight;',
+        '    decay *= uDecay;',
+        '  }',
+        '  gl_FragColor = vec4(rays * uExposure, 1.0);',
+        '}'
+    ].join('\n');
+
+    // The 'streak' quads: positions are NDC already; colour = the source image AT THE HEAD,
+    // fading to black at the tail, added (additive blending) into a black rays target.
+    var GODRAY_STREAK_VERT = [
+        'attribute vec2 aHead;',
+        'attribute float aFade;',
+        'varying vec2 vHead;',
+        'varying float vFade;',
+        'void main() {',
+        '  vHead = aHead; vFade = aFade;',
+        '  gl_Position = vec4(position.xy, 0.0, 1.0);',
+        '}'
+    ].join('\n');
+    // The head colour is the brightest texel of the 3×3 around the head: a sub-pixel quantum lands
+    // between texels, so a single tap at its centre reads it dimmed.
+    var GODRAY_STREAK_FRAG = [
+        'uniform sampler2D uSource;',
+        'uniform vec2  uTexel;',
+        'uniform float uGain;',
+        'varying vec2 vHead;',
+        'varying float vFade;',
+        'void main() {',
+        '  vec3 c = vec3(0.0);',
+        '  for (int i = -1; i <= 1; i++) {',
+        '    for (int j = -1; j <= 1; j++) {',
+        '      c = max(c, texture2D(uSource, vHead + vec2(float(i), float(j)) * uTexel).rgb);',
+        '    }',
+        '  }',
+        '  gl_FragColor = vec4(c * vFade * uGain, 1.0);',
+        '}'
+    ].join('\n');
+
     // R4-B composite — unblurred scene + additive rays * intensity knob.
     var GODRAY_COMP_FRAG = [
         'uniform sampler2D uScene;',
@@ -140,17 +332,19 @@
     ].join('\n');
 
     /**
-     * The live passes, created lazily by the provider on first activation.
+     * The live passes, created lazily by the provider on first activation. Every mode ends in the
+     * same composite (sceneRT + rays × intensity → screen); they differ in how rtRays is made.
      * @param {object} THREE
      * @param {string} quadVert — the provider's full-screen-quad vertex shader
      * @param {number} w @param {number} h — the provider's physical size
-     * @returns {{rtSource:object, setSize:Function, lightUV:Function, march:Function}}
+     * @returns {{rtSource:object, setSize:Function, lightUV:Function, march:Function, streak:Function, field:Function}}
      */
     function makeGodrayPasses(THREE, quadVert, w, h) {
         var fxScene = new THREE.Scene();
         var fxQuad  = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), null);
         fxScene.add(fxQuad);
-        var vLight = new THREE.Vector3();
+        var vLight = new THREE.Vector3(), vProj = new THREE.Vector3(), clearKeep = new THREE.Color();
+        var size = { w: w, h: h };
         var blurMat = new THREE.ShaderMaterial({
             uniforms: {
                 uScene:    { value: null },
@@ -166,9 +360,49 @@
             uniforms: { uScene: { value: null }, uRays: { value: null }, uIntensity: { value: 1.0 } },
             vertexShader: quadVert, fragmentShader: GODRAY_COMP_FRAG, depthWrite: false, depthTest: false
         });
+        var fieldMat = new THREE.ShaderMaterial({
+            uniforms: {
+                uScene:    { value: null },
+                uField:    { value: null },
+                uStepUV:   { value: new THREE.Vector2(0, 0) },
+                uDecay:    blurMat.uniforms.uDecay,      // the SAME accumulation as the radial march
+                uWeight:   blurMat.uniforms.uWeight,
+                uExposure: blurMat.uniforms.uExposure
+            },
+            vertexShader: quadVert, fragmentShader: GODRAY_FIELD_FRAG, depthWrite: false, depthTest: false
+        });
+        var fieldTex = null;
+
+        var streakScene = new THREE.Scene();
+        var streakGeo = new THREE.BufferGeometry(), streakCap = 0;
+        var streakMat = new THREE.ShaderMaterial({
+            uniforms: { uSource: { value: null }, uTexel: { value: new THREE.Vector2(1 / w, 1 / h) }, uGain: { value: STREAK_GAIN } },
+            vertexShader: GODRAY_STREAK_VERT, fragmentShader: GODRAY_STREAK_FRAG,
+            blending: THREE.AdditiveBlending, transparent: true, depthWrite: false, depthTest: false,
+            side: THREE.DoubleSide   // a quad's winding follows its direction; never cull it
+        });
+        var streakMesh = new THREE.Mesh(streakGeo, streakMat);
+        streakMesh.frustumCulled = false;
+        streakScene.add(streakMesh);
+
+        function composite(renderer, quadCamera, sceneRT, rtRays, intensity) {
+            compMat.uniforms.uScene.value = sceneRT.texture;
+            compMat.uniforms.uRays.value  = rtRays.texture;
+            compMat.uniforms.uIntensity.value = intensity;
+            fxQuad.material = compMat;
+            renderer.setRenderTarget(null);
+            renderer.render(fxScene, quadCamera);
+        }
+        // The reach in every mode is the density knob; unset → the value the radial march holds.
+        function densityOf(density) { return (typeof density === 'number') ? density : blurMat.uniforms.uDensity.value; }
+        function directionsOf(frames, camera) {
+            return screenDirections(frames, function (x, y, z) { return vProj.set(x, y, z).project(camera); }, size.w, size.h);
+        }
+        function shortSide() { return Math.min(size.w, size.h); }
+
         var passes = {
             rtSource: new THREE.WebGLRenderTarget(w, h),   // the SOURCE image the provider renders into
-            setSize: function (sw, sh) { passes.rtSource.setSize(sw, sh); },
+            setSize: function (sw, sh) { size.w = sw; size.h = sh; passes.rtSource.setSize(sw, sh); },
             // Light position in [0,1] screen UV: the fullness-weighted centroid of the SOURCE
             // frames, projected through `camera` (2D ortho + 3D persp); screen centre when none.
             lightUV: function (tickData, camera, source) {
@@ -183,7 +417,7 @@
                 vLight.set(sx / sw, sy / sw, sz / sw).project(camera);   // → NDC [-1,1]
                 return new THREE.Vector2(vLight.x * 0.5 + 0.5, vLight.y * 0.5 + 0.5);
             },
-            // Pass 2: march sourceRT → rtRays. Pass 3: sceneRT + rays × intensity → screen.
+            // 'radial' — Pass 2: march sourceRT toward lightUV → rtRays. Pass 3: composite.
             march: function (renderer, quadCamera, sceneRT, sourceRT, rtRays, lightUV, density, intensity) {
                 blurMat.uniforms.uScene.value = sourceRT.texture;
                 blurMat.uniforms.uLightPos.value.copy(lightUV);
@@ -191,12 +425,61 @@
                 fxQuad.material = blurMat;
                 renderer.setRenderTarget(rtRays);
                 renderer.render(fxScene, quadCamera);
-                compMat.uniforms.uScene.value = sceneRT.texture;
-                compMat.uniforms.uRays.value  = rtRays.texture;
-                compMat.uniforms.uIntensity.value = intensity;
-                fxQuad.material = compMat;
-                renderer.setRenderTarget(null);
+                composite(renderer, quadCamera, sceneRT, rtRays, intensity);
+            },
+            // 'streak' — rtRays cleared to black, one fading quad per moving source frame trailing
+            // behind it (colour = sourceRT at its head), then the composite.
+            streak: function (renderer, quadCamera, sceneRT, sourceRT, rtRays, frames, camera, density, intensity) {
+                var q = streakQuads(directionsOf(frames, camera), densityOf(density) * STREAK_REACH * shortSide(),
+                    Math.max(1.5, STREAK_WIDTH * shortSide()), size.w, size.h);
+                if (q.count > streakCap) {
+                    streakCap = Math.max(q.count, streakCap * 2, 600);
+                    streakGeo.setAttribute('position', new THREE.BufferAttribute(new Float32Array(streakCap * 3), 3));
+                    streakGeo.setAttribute('aHead', new THREE.BufferAttribute(new Float32Array(streakCap * 2), 2));
+                    streakGeo.setAttribute('aFade', new THREE.BufferAttribute(new Float32Array(streakCap), 1));
+                }
+                if (q.count > 0) {
+                    streakGeo.attributes.position.array.set(q.position);
+                    streakGeo.attributes.aHead.array.set(q.head);
+                    streakGeo.attributes.aFade.array.set(q.fade);
+                    streakGeo.attributes.position.needsUpdate = true;
+                    streakGeo.attributes.aHead.needsUpdate = true;
+                    streakGeo.attributes.aFade.needsUpdate = true;
+                }
+                streakGeo.setDrawRange(0, q.count);
+                streakMat.uniforms.uSource.value = sourceRT.texture;
+                streakMat.uniforms.uTexel.value.set(1 / size.w, 1 / size.h);
+                renderer.getClearColor(clearKeep);
+                var alphaKeep = renderer.getClearAlpha();
+                renderer.setClearColor(0x000000, 1);
+                renderer.setRenderTarget(rtRays);
+                renderer.clear();
+                if (q.count > 0) { renderer.render(streakScene, quadCamera); }
+                renderer.setClearColor(clearKeep, alphaKeep);
+                composite(renderer, quadCamera, sceneRT, rtRays, intensity);
+            },
+            // 'field' — the source frames' directions → a grid texture; march sourceRT along it →
+            // rtRays; then the composite.
+            field: function (renderer, quadCamera, sceneRT, sourceRT, rtRays, frames, camera, density, intensity) {
+                var long = Math.max(size.w, size.h);
+                var gw = Math.max(8, Math.round(FIELD_CELLS * size.w / long)), gh = Math.max(8, Math.round(FIELD_CELLS * size.h / long));
+                var grid = buildDirectionField(directionsOf(frames, camera), gw, gh, FIELD_RADIUS);
+                if (!fieldTex || fieldTex.image.width !== gw || fieldTex.image.height !== gh) {
+                    if (fieldTex) { fieldTex.dispose(); }
+                    fieldTex = new THREE.DataTexture(grid.data, gw, gh, THREE.RGBAFormat);
+                    fieldTex.minFilter = THREE.LinearFilter; fieldTex.magFilter = THREE.LinearFilter;
+                } else {
+                    fieldTex.image.data.set(grid.data);
+                }
+                fieldTex.needsUpdate = true;
+                var stepPx = densityOf(density) * FIELD_REACH * shortSide() / MARCH_SAMPLES;
+                fieldMat.uniforms.uScene.value = sourceRT.texture;
+                fieldMat.uniforms.uField.value = fieldTex;
+                fieldMat.uniforms.uStepUV.value.set(stepPx / size.w, stepPx / size.h);
+                fxQuad.material = fieldMat;
+                renderer.setRenderTarget(rtRays);
                 renderer.render(fxScene, quadCamera);
+                composite(renderer, quadCamera, sceneRT, rtRays, intensity);
             }
         };
         return passes;
@@ -209,5 +492,11 @@ export {
     GODRAY_SOURCES,
     GODRAY_SOURCE_DEFAULT,
     resolveGodraySource,
+    GODRAY_MODES,
+    GODRAY_MODE_DEFAULT,
+    resolveGodrayMode,
+    screenDirections,
+    streakQuads,
+    buildDirectionField,
     makeGodrayPasses
 };

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

@@ -491,6 +491,12 @@ import * as RendererProviderContract from '../renderer-provider-contract.js';
             var prog = compileProgram(gl, VERT_SRC, fragSrc);
             if (!prog) return { skip: true };
 
+            // Both uploads (the scene canvas and FieldBuilder's field) are TOP row first, and
+            // vTexCoord has its origin at the BOTTOM-left (Filters.js convention). Flip on upload,
+            // once for this context, or the composite draws the whole picture upside down while
+            // screenToWorld (and every hand on the canvas) stays right side up.
+            gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+
             var quadBuf = gl.createBuffer();
             gl.bindBuffer(gl.ARRAY_BUFFER, quadBuf);
             gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1,-1, 1,-1, -1,1, 1,1]), gl.STATIC_DRAW);