@fundamental-engine/elements 0.9.2 → 0.9.4

package/README.md

@@ -49,9 +49,10 @@ each frame — style with them (`var(--field-density)`, etc.) to make content re
 ## `<field-root>` attributes
 
 `accent` · `density` · `waves` · `render` (`dots` / `trails` / `links` / `streamlines` / `metaballs` /
-`voronoi`) · `palette` (`ours` / `heatmap` / `infrared` / `spectrum`) · `mass` · `attention` ·
-`causality`. The engine ships 16 render modes in all (including `field-lines`, `heatmap`, and the
-diagnostics); the others are reached through `setRender()` / the core, not this attribute.
+`voronoi` / `knockout` / `redshift` / `blackbody` / `depth`) · `palette` (`ours` / `heatmap` /
+`infrared` / `spectrum`) · `mass` · `attention` · `causality`. The engine ships 20 render modes in
+all (including `field-lines`, `heatmap`, and the diagnostics); the others are reached through
+`setRender()` / the core, not this attribute.
 
 ## Methods — the `FieldHandle`, proxied onto the element
 
@@ -95,6 +96,14 @@ const field = mountField({ render: 'trails', accent: '#2dd4bf' });
 formation inside a frame), separate from the page-wide `<field-root>`. It runs a deliberately
 simplified in-frame model, not the canonical engine math.
 
+> **Boundary statement — `<field-cell>` is a demo pool, not the engine.** A cell owns its own
+> particle pool, canvas, and lifecycle, seeded with the host's local `Math.random()`. It carries
+> **none of the core guarantees**: no determinism, no snapshot/causal replay, no cross-plane
+> conformance, and no physics parity with `@fundamental-engine/core` or the Swift/Kotlin ports. Its
+> numbers are illustrative, not a source of truth — never assert against a cell in a conformance or
+> replay test. When you need the real engine (deterministic, replayable, parity-held), use
+> `<field-root>` or `createField()`, not `<field-cell>`.
+
 ## Framework use
 
 The custom elements work unchanged in React, Vue, Svelte, Solid, Angular, or plain HTML — register once

package/custom-elements.json

@@ -84,7 +84,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<field-cell force=\"swirl\" color=\"#2dd4bf\">` — an in-frame field surface (§25.1).\n\nA standalone field sized to its container that renders *one* force, with its own\nlightweight particle pool, its own pointer interaction, and a lifecycle that pauses\nwhen off-screen. It is **not** the §-engine: it's a lighter \"demo/poster\" engine,\ncompletely separate from the page `<field-root>` and the core field loop.\n\n- `ResizeObserver` re-fits the canvas (DPR-aware) and rebuilds the pool.\n- `IntersectionObserver` gates the rAF loop — paused when off-screen.\n- Honours `prefers-reduced-motion`: renders one static frame, no animation.",
+          "description": "`<field-cell force=\"swirl\" color=\"#2dd4bf\">` — an in-frame field surface (§25.1).\n\nA standalone field sized to its container that renders *one* force, with its own\nlightweight particle pool, its own pointer interaction, and a lifecycle that pauses\nwhen off-screen. It is **not** the §-engine: it's a lighter \"demo/poster\" engine,\ncompletely separate from the page `<field-root>` and the core field loop.\n\n- `ResizeObserver` re-fits the canvas (DPR-aware) and rebuilds the pool.\n- `IntersectionObserver` gates the rAF loop — paused when off-screen.\n- Honours `prefers-reduced-motion`: renders one static frame, no animation.\n\n**Budgets & isolation (shadow-dom.md §31.19).** Each cell owns its *own* pool, so\nmany cells on a docs page never share or starve one budget. Hard caps keep that\nbudget cheap: `max-particles` clamps the pool ceiling (over both the auto-size and an\nexplicit `count`), and `fps` throttles the animation loop to a target framerate. Both\ncaps are enforced per instance — a saturating cell cannot spill particles or frame\ncost into a neighbour.",
           "name": "FieldCell",
           "members": [
             {
@@ -177,6 +177,16 @@
               "privacy": "private",
               "default": "null"
             },
+            {
+              "kind": "field",
+              "name": "lastStepTs",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "rAF timestamp of the last rendered frame — drives the `fps` throttle (§31.19)."
+            },
             {
               "kind": "field",
               "name": "onPointerMove",
@@ -199,7 +209,7 @@
               "kind": "field",
               "name": "tick",
               "type": {
-                "text": "() => void"
+                "text": "(ts?: number) => void"
               },
               "privacy": "private",
               "readonly": true
@@ -231,6 +241,24 @@
               "description": "particle count; `0` (default) means auto-size to the frame area.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "maxParticles",
+              "type": {
+                "text": "number"
+              },
+              "description": "Hard ceiling on the pool size (§31.19 scoped local-cell budget); `0` (default) means\nno cap. Clamps *both* the auto-size and an explicit `count`, so a cell can never\nexceed its declared budget no matter how large its frame grows.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "fps",
+              "type": {
+                "text": "number"
+              },
+              "description": "Target frames per second for the animation loop (§31.19); `0` (default) means run at\nthe display's native rAF cadence. A positive value throttles the loop so a page full\nof demo cells stays cheap — each cell keeps its own frame budget.",
+              "readonly": true
+            },
             {
               "kind": "method",
               "name": "isPrefersReducedMotion",
@@ -241,6 +269,36 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "rafNow",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "description": "A monotonic timestamp for the fps throttle, in ms (rAF-timestamp compatible)."
+            },
+            {
+              "kind": "method",
+              "name": "shouldRenderFrame",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "now",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The per-cell frame-budget gate (§31.19). With no `fps` (0), every frame renders. With a\npositive `fps`, a frame renders only once its `1000/fps` ms interval has elapsed since the\nlast render; renders advance `lastStepTs`. Each cell keeps its own budget — one cell's rate\nnever affects another's."
+            },
             {
               "kind": "method",
               "name": "fit",
@@ -261,7 +319,7 @@
                   "text": "void"
                 }
               },
-              "description": "Build the particle pool sized to the frame area."
+              "description": "Build the particle pool sized to the frame area, capped by the cell's budget (§31.19)."
             },
             {
               "kind": "method",
@@ -320,6 +378,20 @@
                 "text": "number"
               },
               "description": "Number of particles in the cell's pool."
+            },
+            {
+              "name": "max-particles",
+              "type": {
+                "text": "number"
+              },
+              "description": "Hard ceiling on the pool size (§31.19); caps both the auto-size and an explicit `count`."
+            },
+            {
+              "name": "fps",
+              "type": {
+                "text": "number"
+              },
+              "description": "Target frames per second for the animation loop (§31.19); throttles rAF so many cells stay cheap."
             }
           ],
           "superclass": {
@@ -368,7 +440,7 @@
               "privacy": "private",
               "static": true,
               "readonly": true,
-              "default": "[ { key: 'density', attr: 'density', read: (el) => el.density }, { key: 'waves', attr: 'waves', read: (el) => el.waves }, { key: 'depth', attr: 'depth', read: (el) => el.depth }, { key: 'background', attr: 'background', read: (el) => el.background }, { key: 'render', attr: 'render', read: (el) => el.renderMode }, { key: 'overlay', attr: 'overlay', read: (el) => el.overlay }, { key: 'palette', attr: 'palette', read: (el) => el.palette }, { key: 'mass', attr: 'mass', read: (el) => el.mass }, { key: 'attention', attr: 'attention', read: (el) => el.attention }, { key: 'causality', attr: 'causality', read: (el) => el.causality }, { key: 'heatmap', attr: 'heatmap', read: (el) => el.heatmap }, { key: 'dprCap', attr: 'dpr-cap', read: (el) => el.dprCap }, { key: 'gridWarp', attr: 'grid-warp', read: (el) => el.gridWarp }, { key: 'gridIntensity', attr: 'grid-intensity', read: (el) => el.gridIntensity }, { key: 'theme', attr: 'theme', read: (el) => el.theme }, { key: 'gradientCool', attr: 'gradient-cool', read: (el) => el.gradientCool }, { key: 'gradientWarm', attr: 'gradient-warm', read: (el) => el.gradientWarm }, { key: 'waveBaseline', attr: 'wave-baseline', read: (el) => el.waveBaseline }, { key: 'waveStyle', attr: 'wave-style', read: (el) => el.waveStyle }, { key: 'waveCenter', attr: 'wave-center', read: (el) => el.waveCenter }, { key: 'separation', attr: 'separation', read: (el) => el.separation }, { key: 'integrator', attr: 'integrator', read: (el) => el.integrator }, ]",
+              "default": "[ { key: 'density', attr: 'density', read: (el) => el.density }, { key: 'waves', attr: 'waves', read: (el) => el.waves }, { key: 'depth', attr: 'depth', read: (el) => el.depth }, { key: 'background', attr: 'background', read: (el) => el.background }, { key: 'render', attr: 'render', read: (el) => el.renderMode }, { key: 'overlay', attr: 'overlay', read: (el) => el.overlay }, { key: 'palette', attr: 'palette', read: (el) => el.palette }, { key: 'mass', attr: 'mass', read: (el) => el.mass }, { key: 'attention', attr: 'attention', read: (el) => el.attention }, { key: 'causality', attr: 'causality', read: (el) => el.causality }, { key: 'heatmap', attr: 'heatmap', read: (el) => el.heatmap }, { key: 'dprCap', attr: 'dpr-cap', read: (el) => el.dprCap }, { key: 'gridWarp', attr: 'grid-warp', read: (el) => el.gridWarp }, { key: 'gridIntensity', attr: 'grid-intensity', read: (el) => el.gridIntensity }, { key: 'theme', attr: 'theme', read: (el) => el.theme }, { key: 'gradientCool', attr: 'gradient-cool', read: (el) => el.gradientCool }, { key: 'gradientWarm', attr: 'gradient-warm', read: (el) => el.gradientWarm }, { key: 'waveBaseline', attr: 'wave-baseline', read: (el) => el.waveBaseline }, { key: 'waveStyle', attr: 'wave-style', read: (el) => el.waveStyle }, { key: 'waveCenter', attr: 'wave-center', read: (el) => el.waveCenter }, { key: 'separation', attr: 'separation', read: (el) => el.separation }, { key: 'ambientOrbit', attr: 'ambient-orbit', read: (el) => el.ambientOrbit }, { key: 'ambientWander', attr: 'ambient-wander', read: (el) => el.ambientWander }, { key: 'integrator', attr: 'integrator', read: (el) => el.integrator }, ]",
               "description": "The engine options `<field-root>` forwards to `createBrowserField`, as ONE declarative table —\nthe single source of truth for the option object built in `start()`, so a new forwarded\n`FieldOption` can never be silently dropped from forwarding the way `depth` once was. `accent`\n(raw passthrough so a `palette` with no `accent` adopts the palette stop) and\n`overlayCanvas`/`feedbackSink` (managed internally) are special-cased in `start()` and absent here.\n\n`observedAttributes` stays an explicit literal below — the Custom-Elements-Manifest analyzer reads\nit statically and can't enumerate a computed array — but the `option-attrs-observed` test pins it\nto this table (every `attr` here must be observed), so the two lists can't drift apart."
             },
             {
@@ -425,6 +497,16 @@
               "privacy": "private",
               "default": "true"
             },
+            {
+              "kind": "field",
+              "name": "fieldActiveMarked",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "SSR pre-registration queue bookkeeping: true while this element counts as a live field, so a\nrebuild (start() after a destroy) does not double-count the active-field tally (#683)."
+            },
             {
               "kind": "field",
               "name": "platformRuntime",
@@ -466,14 +548,14 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "draw the background Currents (§24).",
+              "description": "draw the background Currents (§24). OPT-IN (#979, mirrors the core default): the attribute\nmust be PRESENT (and not `\"false\"`) to build the waves — same semantics as `attention` /\n`causality` / `mass`. Absent = the bare field, no carrier waves.",
               "readonly": true
             },
             {
               "kind": "field",
               "name": "renderMode",
               "type": {
-                "text": "'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'none'"
+                "text": "| 'dots'\n    | 'trails'\n    | 'links'\n    | 'metaballs'\n    | 'voronoi'\n    | 'streamlines'\n    | 'flow'\n    | 'knockout'\n    | 'redshift'\n    | 'blackbody'\n    | 'depth'\n    | 'none'"
               },
               "description": "render mode (§20.6); the DEFAULT is `none` (#538) — the signals-only engine: simulate + feed back,\nnever draw (#297). Set `render=\"dots\"` (or another drawing mode) to get a visible surface.",
               "readonly": true
@@ -586,13 +668,31 @@
               "description": "`separation` — particle-to-particle separation force strength ∈ [0,1]; undefined if absent/invalid.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "ambientOrbit",
+              "type": {
+                "text": "number | undefined"
+              },
+              "description": "`ambient-orbit` — DECLARED resting-formation swirl on attract (#978); undefined (engine default\n0.1, the historical hardcoded value) if absent/invalid. `0` is valid (a purely radial attract).",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "ambientWander",
+              "type": {
+                "text": "number | undefined"
+              },
+              "description": "`ambient-wander` — DECLARED resting-formation drift (#978); undefined (engine default 1.0, the\nhistorical hardcoded value) if absent/invalid. `0` is valid (a still resting field).",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "integrator",
               "type": {
                 "text": "IntegratorMode | undefined"
               },
-              "description": "`integrator` — the integration scheme (substrate doc 04 §Step 3); `'fixed'` opts into the\nframe-rate-independent integrator, anything else (incl. absent) is the default `'legacy'`.",
+              "description": "`integrator` — the integration scheme (substrate doc 04 §Step 3); `'fixed'` opts into the\nframe-rate-independent integrator, `'velocity-verlet'` into the second-order Verlet scheme\n(#659); anything else (incl. absent) is the default `'legacy'`.",
               "readonly": true
             },
             {
@@ -940,7 +1040,7 @@
                 {
                   "name": "mode",
                   "type": {
-                    "text": "'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'none'"
+                    "text": "| 'dots'\n      | 'trails'\n      | 'links'\n      | 'metaballs'\n      | 'voronoi'\n      | 'streamlines'\n      | 'flow'\n      | 'knockout'\n      | 'redshift'\n      | 'blackbody'\n      | 'depth'\n      | 'none'"
                   }
                 }
               ],
@@ -1529,6 +1629,17 @@
               ],
               "description": "pause/resume drawing (the simulation keeps running) — the element also does this automatically\nfrom its IntersectionObserver, so a manual call is for explicit control."
             },
+            {
+              "kind": "method",
+              "name": "ensureOverlayCanvas",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HTMLCanvasElement | null"
+                }
+              },
+              "description": "Field Surfaces: lazily create + attach the front overlay surface (light DOM — the shadow host is\nz-index:0, behind content). A fixed, full-viewport, click-through, mix-blend canvas above content;\ncore sizes its backing store and draws the overlay mode onto it. Created ONCE, on the first overlay\nthat actually goes active (#676) — core invokes this as `overlayCanvasProvider` — and reused across\nrebuilds. Idempotent: returns the existing canvas on every later call, never a second element."
+            },
             {
               "kind": "method",
               "name": "start",
@@ -1609,6 +1720,12 @@
             {
               "name": "separation"
             },
+            {
+              "name": "ambient-orbit"
+            },
+            {
+              "name": "ambient-wander"
+            },
             {
               "name": "integrator"
             },
@@ -1791,6 +1908,20 @@
                 "module": "src/index.ts"
               }
             },
+            {
+              "name": "ambient-orbit",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "name": "ambient-wander",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "name": "integrator",
               "inheritedFrom": {
@@ -1823,7 +1954,7 @@
               "privacy": "private",
               "static": true,
               "readonly": true,
-              "default": "[ { key: 'density', attr: 'density', read: (el) => el.density }, { key: 'waves', attr: 'waves', read: (el) => el.waves }, { key: 'depth', attr: 'depth', read: (el) => el.depth }, { key: 'background', attr: 'background', read: (el) => el.background }, { key: 'render', attr: 'render', read: (el) => el.renderMode }, { key: 'overlay', attr: 'overlay', read: (el) => el.overlay }, { key: 'palette', attr: 'palette', read: (el) => el.palette }, { key: 'mass', attr: 'mass', read: (el) => el.mass }, { key: 'attention', attr: 'attention', read: (el) => el.attention }, { key: 'causality', attr: 'causality', read: (el) => el.causality }, { key: 'heatmap', attr: 'heatmap', read: (el) => el.heatmap }, { key: 'dprCap', attr: 'dpr-cap', read: (el) => el.dprCap }, { key: 'gridWarp', attr: 'grid-warp', read: (el) => el.gridWarp }, { key: 'gridIntensity', attr: 'grid-intensity', read: (el) => el.gridIntensity }, { key: 'theme', attr: 'theme', read: (el) => el.theme }, { key: 'gradientCool', attr: 'gradient-cool', read: (el) => el.gradientCool }, { key: 'gradientWarm', attr: 'gradient-warm', read: (el) => el.gradientWarm }, { key: 'waveBaseline', attr: 'wave-baseline', read: (el) => el.waveBaseline }, { key: 'waveStyle', attr: 'wave-style', read: (el) => el.waveStyle }, { key: 'waveCenter', attr: 'wave-center', read: (el) => el.waveCenter }, { key: 'separation', attr: 'separation', read: (el) => el.separation }, { key: 'integrator', attr: 'integrator', read: (el) => el.integrator }, ]",
+              "default": "[ { key: 'density', attr: 'density', read: (el) => el.density }, { key: 'waves', attr: 'waves', read: (el) => el.waves }, { key: 'depth', attr: 'depth', read: (el) => el.depth }, { key: 'background', attr: 'background', read: (el) => el.background }, { key: 'render', attr: 'render', read: (el) => el.renderMode }, { key: 'overlay', attr: 'overlay', read: (el) => el.overlay }, { key: 'palette', attr: 'palette', read: (el) => el.palette }, { key: 'mass', attr: 'mass', read: (el) => el.mass }, { key: 'attention', attr: 'attention', read: (el) => el.attention }, { key: 'causality', attr: 'causality', read: (el) => el.causality }, { key: 'heatmap', attr: 'heatmap', read: (el) => el.heatmap }, { key: 'dprCap', attr: 'dpr-cap', read: (el) => el.dprCap }, { key: 'gridWarp', attr: 'grid-warp', read: (el) => el.gridWarp }, { key: 'gridIntensity', attr: 'grid-intensity', read: (el) => el.gridIntensity }, { key: 'theme', attr: 'theme', read: (el) => el.theme }, { key: 'gradientCool', attr: 'gradient-cool', read: (el) => el.gradientCool }, { key: 'gradientWarm', attr: 'gradient-warm', read: (el) => el.gradientWarm }, { key: 'waveBaseline', attr: 'wave-baseline', read: (el) => el.waveBaseline }, { key: 'waveStyle', attr: 'wave-style', read: (el) => el.waveStyle }, { key: 'waveCenter', attr: 'wave-center', read: (el) => el.waveCenter }, { key: 'separation', attr: 'separation', read: (el) => el.separation }, { key: 'ambientOrbit', attr: 'ambient-orbit', read: (el) => el.ambientOrbit }, { key: 'ambientWander', attr: 'ambient-wander', read: (el) => el.ambientWander }, { key: 'integrator', attr: 'integrator', read: (el) => el.integrator }, ]",
               "description": "The engine options `<field-root>` forwards to `createBrowserField`, as ONE declarative table —\nthe single source of truth for the option object built in `start()`, so a new forwarded\n`FieldOption` can never be silently dropped from forwarding the way `depth` once was. `accent`\n(raw passthrough so a `palette` with no `accent` adopts the palette stop) and\n`overlayCanvas`/`feedbackSink` (managed internally) are special-cased in `start()` and absent here.\n\n`observedAttributes` stays an explicit literal below — the Custom-Elements-Manifest analyzer reads\nit statically and can't enumerate a computed array — but the `option-attrs-observed` test pins it\nto this table (every `attr` here must be observed), so the two lists can't drift apart.",
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1908,6 +2039,20 @@
                 "module": "src/index.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "fieldActiveMarked",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "SSR pre-registration queue bookkeeping: true while this element counts as a live field, so a\nrebuild (start() after a destroy) does not double-count the active-field tally (#683).",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "platformRuntime",
@@ -1965,7 +2110,7 @@
               "type": {
                 "text": "boolean"
               },
-              "description": "draw the background Currents (§24).",
+              "description": "draw the background Currents (§24). OPT-IN (#979, mirrors the core default): the attribute\nmust be PRESENT (and not `\"false\"`) to build the waves — same semantics as `attention` /\n`causality` / `mass`. Absent = the bare field, no carrier waves.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1976,7 +2121,7 @@
               "kind": "field",
               "name": "renderMode",
               "type": {
-                "text": "'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'none'"
+                "text": "| 'dots'\n    | 'trails'\n    | 'links'\n    | 'metaballs'\n    | 'voronoi'\n    | 'streamlines'\n    | 'flow'\n    | 'knockout'\n    | 'redshift'\n    | 'blackbody'\n    | 'depth'\n    | 'none'"
               },
               "description": "render mode (§20.6); the DEFAULT is `none` (#538) — the signals-only engine: simulate + feed back,\nnever draw (#297). Set `render=\"dots\"` (or another drawing mode) to get a visible surface.",
               "readonly": true,
@@ -2141,13 +2286,39 @@
                 "module": "src/index.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "ambientOrbit",
+              "type": {
+                "text": "number | undefined"
+              },
+              "description": "`ambient-orbit` — DECLARED resting-formation swirl on attract (#978); undefined (engine default\n0.1, the historical hardcoded value) if absent/invalid. `0` is valid (a purely radial attract).",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "ambientWander",
+              "type": {
+                "text": "number | undefined"
+              },
+              "description": "`ambient-wander` — DECLARED resting-formation drift (#978); undefined (engine default 1.0, the\nhistorical hardcoded value) if absent/invalid. `0` is valid (a still resting field).",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "integrator",
               "type": {
                 "text": "IntegratorMode | undefined"
               },
-              "description": "`integrator` — the integration scheme (substrate doc 04 §Step 3); `'fixed'` opts into the\nframe-rate-independent integrator, anything else (incl. absent) is the default `'legacy'`.",
+              "description": "`integrator` — the integration scheme (substrate doc 04 §Step 3); `'fixed'` opts into the\nframe-rate-independent integrator, `'velocity-verlet'` into the second-order Verlet scheme\n(#659); anything else (incl. absent) is the default `'legacy'`.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -2591,7 +2762,7 @@
                 {
                   "name": "mode",
                   "type": {
-                    "text": "'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'none'"
+                    "text": "| 'dots'\n      | 'trails'\n      | 'links'\n      | 'metaballs'\n      | 'voronoi'\n      | 'streamlines'\n      | 'flow'\n      | 'knockout'\n      | 'redshift'\n      | 'blackbody'\n      | 'depth'\n      | 'none'"
                   }
                 }
               ],
@@ -3304,6 +3475,21 @@
                 "module": "src/index.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "ensureOverlayCanvas",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HTMLCanvasElement | null"
+                }
+              },
+              "description": "Field Surfaces: lazily create + attach the front overlay surface (light DOM — the shadow host is\nz-index:0, behind content). A fixed, full-viewport, click-through, mix-blend canvas above content;\ncore sizes its backing store and draws the overlay mode onto it. Created ONCE, on the first overlay\nthat actually goes active (#676) — core invokes this as `overlayCanvasProvider` — and reused across\nrebuilds. Idempotent: returns the existing canvas on every later call, never a second element.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "start",
@@ -3757,6 +3943,140 @@
           }
         }
       ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/preregistration-queue.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "installPreRegistrationQueue",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "description": "Install the capturing document listeners — idempotent, SSR-guarded. Called from the custom\nelement's constructor so it runs on the client before the element upgrades its peers, and never on\nthe server (no `document`). Capturing (`{ capture: true }`) so the queue sees the event on the way\ndown, independent of any later-added bubble-phase field listener."
+        },
+        {
+          "kind": "function",
+          "name": "markFieldActive",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "description": "Mark that a field has become live. The first live field is what makes subsequent registration\nevents skip the queue and reach the field directly. Paired with markFieldInactive."
+        },
+        {
+          "kind": "function",
+          "name": "markFieldInactive",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "description": "Mark that a live field has torn down. When the last field goes away the queue resumes buffering, so\nan element that (re)connects during a field-less window is captured for the next field that boots."
+        },
+        {
+          "kind": "function",
+          "name": "flushPreRegistrationQueue",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "description": "Replay every buffered registration event on its source element, then clear the buffer. Called by a\nfield immediately after it wires its body-event listeners, so the events bubble (composed) to the\ndocument and the field registers them through its normal, idempotent path. Safe to call with an\nempty queue (the common client-only case) — it does nothing."
+        },
+        {
+          "kind": "function",
+          "name": "pendingRegistrationCount",
+          "return": {
+            "type": {
+              "text": "number"
+            }
+          },
+          "description": "Test-only: the number of events currently buffered (0 once drained)."
+        },
+        {
+          "kind": "function",
+          "name": "resetPreRegistrationQueue",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "description": "Test-only: reset all module state (queue, active-field count, install flag) between tests."
+        },
+        {
+          "kind": "function",
+          "name": "isBuffering",
+          "return": {
+            "type": {
+              "text": "boolean"
+            }
+          },
+          "description": "Whether the queue is currently buffering (no field live). Test/introspection helper."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "installPreRegistrationQueue",
+          "declaration": {
+            "name": "installPreRegistrationQueue",
+            "module": "src/preregistration-queue.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "markFieldActive",
+          "declaration": {
+            "name": "markFieldActive",
+            "module": "src/preregistration-queue.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "markFieldInactive",
+          "declaration": {
+            "name": "markFieldInactive",
+            "module": "src/preregistration-queue.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "flushPreRegistrationQueue",
+          "declaration": {
+            "name": "flushPreRegistrationQueue",
+            "module": "src/preregistration-queue.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "pendingRegistrationCount",
+          "declaration": {
+            "name": "pendingRegistrationCount",
+            "module": "src/preregistration-queue.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "resetPreRegistrationQueue",
+          "declaration": {
+            "name": "resetPreRegistrationQueue",
+            "module": "src/preregistration-queue.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "isBuffering",
+          "declaration": {
+            "name": "isBuffering",
+            "module": "src/preregistration-queue.ts"
+          }
+        }
+      ]
     }
   ]
 }

package/dist/field-cell.d.ts

@@ -11,11 +11,20 @@ import { HTMLElementBase } from './base.ts';
  * - `IntersectionObserver` gates the rAF loop — paused when off-screen.
  * - Honours `prefers-reduced-motion`: renders one static frame, no animation.
  *
+ * **Budgets & isolation (shadow-dom.md §31.19).** Each cell owns its *own* pool, so
+ * many cells on a docs page never share or starve one budget. Hard caps keep that
+ * budget cheap: `max-particles` clamps the pool ceiling (over both the auto-size and an
+ * explicit `count`), and `fps` throttles the animation loop to a target framerate. Both
+ * caps are enforced per instance — a saturating cell cannot spill particles or frame
+ * cost into a neighbour.
+ *
  * @summary A standalone, in-frame demo field that renders one force with its own
  * particle pool, in-view-gated. Registered as `<field-cell>`.
  * @attr {string} force - The single force token rendered: `attract` | `repel` | `swirl` | `gravity` | `stream` | `buoyancy` | `tether`.
  * @attr {string} color - Accent color (hex) for the cell's particles.
  * @attr {number} count - Number of particles in the cell's pool.
+ * @attr {number} max-particles - Hard ceiling on the pool size (§31.19); caps both the auto-size and an explicit `count`.
+ * @attr {number} fps - Target frames per second for the animation loop (§31.19); throttles rAF so many cells stay cheap.
  */
 export declare class FieldCell extends HTMLElementBase {
     static readonly observedAttributes: string[];
@@ -31,6 +40,8 @@ export declare class FieldCell extends HTMLElementBase {
     /** cursor in frame-local CSS px, or null when absent. */
     private cursorX;
     private cursorY;
+    /** rAF timestamp of the last rendered frame — drives the `fps` throttle (§31.19). */
+    private lastStepTs;
     private readonly onPointerMove;
     private readonly onPointerLeave;
     private readonly tick;
@@ -41,13 +52,34 @@ export declare class FieldCell extends HTMLElementBase {
     get color(): string;
     /** particle count; `0` (default) means auto-size to the frame area. */
     get count(): number;
-    attributeChangedCallback(): void;
+    /**
+     * Hard ceiling on the pool size (§31.19 scoped local-cell budget); `0` (default) means
+     * no cap. Clamps *both* the auto-size and an explicit `count`, so a cell can never
+     * exceed its declared budget no matter how large its frame grows.
+     */
+    get maxParticles(): number;
+    /**
+     * Target frames per second for the animation loop (§31.19); `0` (default) means run at
+     * the display's native rAF cadence. A positive value throttles the loop so a page full
+     * of demo cells stays cheap — each cell keeps its own frame budget.
+     */
+    get fps(): number;
+    attributeChangedCallback(name: string): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
     private isPrefersReducedMotion;
+    /** A monotonic timestamp for the fps throttle, in ms (rAF-timestamp compatible). */
+    private rafNow;
+    /**
+     * The per-cell frame-budget gate (§31.19). With no `fps` (0), every frame renders. With a
+     * positive `fps`, a frame renders only once its `1000/fps` ms interval has elapsed since the
+     * last render; renders advance `lastStepTs`. Each cell keeps its own budget — one cell's rate
+     * never affects another's.
+     */
+    private shouldRenderFrame;
     /** Fit the canvas to the element box (DPR-aware) and rebuild the pool. */
     private fit;
-    /** Build the particle pool sized to the frame area. */
+    /** Build the particle pool sized to the frame area, capped by the cell's budget (§31.19). */
     private buildPool;
     private start;
     private stop;

package/dist/field-cell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field-cell.d.ts","sourceRoot":"","sources":["../src/field-cell.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAa5C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,SAAU,SAAQ,eAAe;IAC5C,MAAM,CAAC,QAAQ,CAAC,kBAAkB,WAA+B;IAEjE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,GAAG,CAAyC;IAEpD,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,oBAAoB,CAAC,CAAuB;IAEpD,0DAA0D;IAC1D,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,IAAI,CAAK;IAEjB,yDAAyD;IACzD,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,OAAO,CAAuB;IAEtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAa;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;;IA2BlC,gDAAgD;IAChD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,iBAAiB;IACjB,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,uEAAuE;IACvE,IAAI,KAAK,IAAI,MAAM,CAGlB;IAED,wBAAwB,IAAI,IAAI;IAKhC,iBAAiB,IAAI,IAAI;IAqBzB,oBAAoB,IAAI,IAAI;IAU5B,OAAO,CAAC,sBAAsB;IAO9B,0EAA0E;IAC1E,OAAO,CAAC,GAAG;IAmBX,uDAAuD;IACvD,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,KAAK;IASb,OAAO,CAAC,IAAI;IAKZ,kCAAkC;IAClC,OAAO,CAAC,IAAI;CAwDb;AAMD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,YAAY,EAAE,SAAS,CAAC;KACzB;CACF"}
+{"version":3,"file":"field-cell.d.ts","sourceRoot":"","sources":["../src/field-cell.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAa5C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,SAAU,SAAQ,eAAe;IAC5C,MAAM,CAAC,QAAQ,CAAC,kBAAkB,WAAuD;IAEzF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,GAAG,CAAyC;IAEpD,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,oBAAoB,CAAC,CAAuB;IAEpD,0DAA0D;IAC1D,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,IAAI,CAAK;IAEjB,yDAAyD;IACzD,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,OAAO,CAAuB;IAEtC,qFAAqF;IACrF,OAAO,CAAC,UAAU,CAAK;IAEvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAa;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;;IA8B7C,gDAAgD;IAChD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,iBAAiB;IACjB,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,uEAAuE;IACvE,IAAI,KAAK,IAAI,MAAM,CAGlB;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,MAAM,CAGzB;IAED;;;;OAIG;IACH,IAAI,GAAG,IAAI,MAAM,CAGhB;IAED,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAU5C,iBAAiB,IAAI,IAAI;IAqBzB,oBAAoB,IAAI,IAAI;IAU5B,OAAO,CAAC,sBAAsB;IAO9B,oFAAoF;IACpF,OAAO,CAAC,MAAM;IAMd;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAYzB,0EAA0E;IAC1E,OAAO,CAAC,GAAG;IAmBX,6FAA6F;IAC7F,OAAO,CAAC,SAAS;IAkBjB,OAAO,CAAC,KAAK;IAWb,OAAO,CAAC,IAAI;IAKZ,kCAAkC;IAClC,OAAO,CAAC,IAAI;CAwDb;AAMD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,YAAY,EAAE,SAAS,CAAC;KACzB;CACF"}