@fundamental-engine/elements 0.9.1 → 0.9.3

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 }, ]",
+              "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,6 +668,33 @@
               "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, `'velocity-verlet'` into the second-order Verlet scheme\n(#659); anything else (incl. absent) is the default `'legacy'`.",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "theme",
@@ -931,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'"
                   }
                 }
               ],
@@ -1267,6 +1376,108 @@
               },
               "description": "kinetic/thermal/total energy snapshot for the current frame."
             },
+            {
+              "kind": "method",
+              "name": "query",
+              "return": {
+                "type": {
+                  "text": "FieldQueryResult"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "q",
+                  "optional": true,
+                  "type": {
+                    "text": "FieldQuery"
+                  }
+                }
+              ],
+              "description": "Ask the live field a structured question (bodies/metrics/relationships/influences) — read-only.\nReturns an empty reading before the field starts. See FieldHandle.query. EXPERIMENTAL."
+            },
+            {
+              "kind": "method",
+              "name": "snapshot",
+              "return": {
+                "type": {
+                  "text": "FieldSnapshot"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "opts",
+                  "optional": true,
+                  "type": {
+                    "text": "FieldSnapshotOptions"
+                  }
+                }
+              ],
+              "description": "Capture field state — a portable, versioned FieldSnapshot. Empty before start. EXPERIMENTAL."
+            },
+            {
+              "kind": "method",
+              "name": "diff",
+              "return": {
+                "type": {
+                  "text": "FieldDiff"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "a",
+                  "type": {
+                    "text": "FieldSnapshot"
+                  }
+                },
+                {
+                  "name": "b",
+                  "type": {
+                    "text": "FieldSnapshot"
+                  }
+                }
+              ],
+              "description": "Compare two snapshots — pure (works before the field starts). See FieldHandle.diff. EXPERIMENTAL."
+            },
+            {
+              "kind": "method",
+              "name": "replay",
+              "return": {
+                "type": {
+                  "text": "CausalReplay"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "a",
+                  "type": {
+                    "text": "FieldSnapshot"
+                  }
+                },
+                {
+                  "name": "b",
+                  "type": {
+                    "text": "FieldSnapshot"
+                  }
+                },
+                {
+                  "name": "opts",
+                  "optional": true,
+                  "type": {
+                    "text": "ReplayOptions"
+                  }
+                }
+              ],
+              "description": "Explain how the field changed between two snapshots — pure (works before start). See FieldHandle.replay. EXPERIMENTAL."
+            },
+            {
+              "kind": "field",
+              "name": "projections",
+              "type": {
+                "text": "ProjectionRegistry"
+              },
+              "description": "The field's projection registry — a no-op registry before the field starts. See FieldHandle.projections. EXPERIMENTAL.",
+              "readonly": true
+            },
             {
               "kind": "method",
               "name": "sample",
@@ -1418,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",
@@ -1498,6 +1720,15 @@
             {
               "name": "separation"
             },
+            {
+              "name": "ambient-orbit"
+            },
+            {
+              "name": "ambient-wander"
+            },
+            {
+              "name": "integrator"
+            },
             {
               "name": "background"
             },
@@ -1677,6 +1908,27 @@
                 "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": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "name": "background",
               "inheritedFrom": {
@@ -1702,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 }, ]",
+              "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",
@@ -1787,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",
@@ -1844,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",
@@ -1855,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,
@@ -2020,6 +2286,45 @@
                 "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, `'velocity-verlet'` into the second-order Verlet scheme\n(#659); anything else (incl. absent) is the default `'legacy'`.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "theme",
@@ -2457,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'"
                   }
                 }
               ],
@@ -2865,6 +3170,128 @@
                 "module": "src/index.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "query",
+              "return": {
+                "type": {
+                  "text": "FieldQueryResult"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "q",
+                  "optional": true,
+                  "type": {
+                    "text": "FieldQuery"
+                  }
+                }
+              ],
+              "description": "Ask the live field a structured question (bodies/metrics/relationships/influences) — read-only.\nReturns an empty reading before the field starts. See FieldHandle.query. EXPERIMENTAL.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "snapshot",
+              "return": {
+                "type": {
+                  "text": "FieldSnapshot"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "opts",
+                  "optional": true,
+                  "type": {
+                    "text": "FieldSnapshotOptions"
+                  }
+                }
+              ],
+              "description": "Capture field state — a portable, versioned FieldSnapshot. Empty before start. EXPERIMENTAL.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "diff",
+              "return": {
+                "type": {
+                  "text": "FieldDiff"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "a",
+                  "type": {
+                    "text": "FieldSnapshot"
+                  }
+                },
+                {
+                  "name": "b",
+                  "type": {
+                    "text": "FieldSnapshot"
+                  }
+                }
+              ],
+              "description": "Compare two snapshots — pure (works before the field starts). See FieldHandle.diff. EXPERIMENTAL.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "replay",
+              "return": {
+                "type": {
+                  "text": "CausalReplay"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "a",
+                  "type": {
+                    "text": "FieldSnapshot"
+                  }
+                },
+                {
+                  "name": "b",
+                  "type": {
+                    "text": "FieldSnapshot"
+                  }
+                },
+                {
+                  "name": "opts",
+                  "optional": true,
+                  "type": {
+                    "text": "ReplayOptions"
+                  }
+                }
+              ],
+              "description": "Explain how the field changed between two snapshots — pure (works before start). See FieldHandle.replay. EXPERIMENTAL.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "projections",
+              "type": {
+                "text": "ProjectionRegistry"
+              },
+              "description": "The field's projection registry — a no-op registry before the field starts. See FieldHandle.projections. EXPERIMENTAL.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "sample",
@@ -3048,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",
@@ -3501,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"
+          }
+        }
+      ]
     }
   ]
 }