@fundamental-engine/elements 0.7.0 → 0.9.0

package/custom-elements.json

@@ -368,7 +368,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 }, ]",
+              "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 }, ]",
               "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."
             },
             {
@@ -388,6 +388,16 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "reflecting",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "guard: true while an imperative setter is reflecting its value back to an attribute, so the\nresulting attributeChangedCallback skips re-applying it (no double-apply / feedback loop) — #541."
+            },
             {
               "kind": "field",
               "name": "overlayCanvas",
@@ -465,7 +475,7 @@
               "type": {
                 "text": "'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'none'"
               },
-              "description": "render mode (§20.6); `none` = the signals-only engine — simulate + feed back, never draw (#297).",
+              "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
             },
             {
@@ -549,6 +559,130 @@
               "description": "`depth` — optional z-volume; undefined (engine default 0, the flat field) if absent/invalid.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "gridWarp",
+              "type": {
+                "text": "number | undefined"
+              },
+              "description": "`grid-warp` — `grid` overlay distortion multiplier; undefined (engine default 1) if absent/invalid.\n`0` is valid (a flat, undistorted lattice).",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "gridIntensity",
+              "type": {
+                "text": "number | undefined"
+              },
+              "description": "`grid-intensity` — `grid` overlay stroke opacity ∈ [0,1]; undefined (engine default 0.16, the faint\ndiagnostic) if absent/invalid. Raise it (≈0.5) to make the warped lattice a visual centerpiece.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "separation",
+              "type": {
+                "text": "number | undefined"
+              },
+              "description": "`separation` — particle-to-particle separation force strength ∈ [0,1]; undefined if absent/invalid.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "theme",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "`theme` — ambient palette preset (`warm` (default) | `cool` | `mono`); undefined if absent (#529).",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "gradientCool",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "`gradient-cool` — hex for the cool end of the heat ramp; overrides the theme (#529).",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "gradientWarm",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "`gradient-warm` — hex for the warm end of the heat ramp; overrides the theme (#529).",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "waveBaseline",
+              "type": {
+                "text": "readonly string[] | undefined"
+              },
+              "description": "`wave-baseline` — space-separated hex stops for the wave baseline; overrides the theme (#529).",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "waveStyle",
+              "type": {
+                "text": "'linear' | 'circular'"
+              },
+              "description": "`wave-style` — wave layout style: `'linear'` | `'circular'`",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "waveCenter",
+              "type": {
+                "text": "{ x: number; y: number } | null"
+              },
+              "description": "`wave-center` — coordinates string space-separated e.g. \"200 300\"",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "formation",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "`formation` — the global formation (§7), applied live; undefined if absent. Unlike the other\nattributes this is post-construction (set via `setFormation`), but it round-trips: the attribute\ndrives the field and `setFormation` reflects back to it (#541).",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "handle",
+              "type": {
+                "text": "FieldHandle | undefined"
+              },
+              "description": "the live `FieldHandle` this element drives, or `undefined` before mount / after teardown (#542).\nEvery method below is forwarded for convenience, but `.handle` is the escape hatch for the full\nsurface and for passing the field to `bindData` / `applyRecipe` (both from `@fundamental-engine/dom`):\n`import { bindData } from '@fundamental-engine/dom'; bindData(el.handle, rows, spec);`",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "reflect",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "attr",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "value",
+                  "type": {
+                    "text": "string | null"
+                  }
+                }
+              ],
+              "description": "reflect an imperative setter's value back to its attribute, so attribute-based debugging shows the\nLIVE state (the bug from #541 was a stale `render=\"none\"` after `setRender`). Guarded so the\nresulting attributeChangedCallback does not re-apply it. Pass `null` to remove the attribute."
+            },
             {
               "kind": "method",
               "name": "scan",
@@ -623,6 +757,60 @@
               ],
               "description": "switch the global formation (§7)."
             },
+            {
+              "kind": "method",
+              "name": "setWaveStyle",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "style",
+                  "type": {
+                    "text": "'linear' | 'circular'"
+                  }
+                }
+              ],
+              "description": "switch the wave current layout style."
+            },
+            {
+              "kind": "method",
+              "name": "setWaveCenter",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "center",
+                  "type": {
+                    "text": "{ x: number; y: number } | (() => { x: number; y: number }) | null"
+                  }
+                }
+              ],
+              "description": "set the custom wave center coordinate (or function)."
+            },
+            {
+              "kind": "method",
+              "name": "setSeparation",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "strength",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "set particle-to-particle separation/repulsion force strength."
+            },
             {
               "kind": "method",
               "name": "setAttention",
@@ -713,6 +901,24 @@
               ],
               "description": "lower/raise the backing-store DPR ceiling at runtime (the dominant fill-rate lever)."
             },
+            {
+              "kind": "method",
+              "name": "setQualityTier",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "tier",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "apply an adaptive quality tier 0–3 (#413) — the platform runtime forwards the governor's tier."
+            },
             {
               "kind": "method",
               "name": "setRender",
@@ -1175,6 +1381,43 @@
               ],
               "description": "subscribe to a discrete field event (absorb/release/settle); a no-op unsubscribe until the field starts."
             },
+            {
+              "kind": "field",
+              "name": "version",
+              "type": {
+                "text": "string"
+              },
+              "description": "the running engine version (`FIELD_VERSION`) — available before mount too.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "scrollV",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "description": "the page's scroll velocity the engine tracks (drives `--field-scroll-v`); 0 before mount."
+            },
+            {
+              "kind": "method",
+              "name": "setVisible",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "on",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "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": "start",
@@ -1228,8 +1471,38 @@
             {
               "name": "dpr-cap"
             },
+            {
+              "name": "grid-warp"
+            },
+            {
+              "name": "grid-intensity"
+            },
+            {
+              "name": "theme"
+            },
+            {
+              "name": "gradient-cool"
+            },
+            {
+              "name": "gradient-warm"
+            },
+            {
+              "name": "wave-baseline"
+            },
+            {
+              "name": "wave-style"
+            },
+            {
+              "name": "wave-center"
+            },
+            {
+              "name": "separation"
+            },
             {
               "name": "background"
+            },
+            {
+              "name": "formation"
             }
           ],
           "superclass": {
@@ -1341,26 +1614,251 @@
                 "module": "src/index.ts"
               }
             },
+            {
+              "name": "grid-warp",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "name": "grid-intensity",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "name": "theme",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "name": "gradient-cool",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "name": "gradient-warm",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "name": "wave-baseline",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "name": "wave-style",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "name": "wave-center",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "name": "separation",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "name": "background",
               "inheritedFrom": {
                 "name": "FieldField",
                 "module": "src/index.ts"
               }
-            }
-          ],
-          "members": [
+            },
+            {
+              "name": "formation",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "OPTIONS",
+              "type": {
+                "text": "ReadonlyArray<{\n    key: keyof FieldOptions;\n    attr: string;\n    read: (el: FieldField) => unknown;\n  }>"
+              },
+              "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 }, ]",
+              "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",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "canvas",
+              "type": {
+                "text": "HTMLCanvasElement"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "field",
+              "type": {
+                "text": "FieldHandle | undefined"
+              },
+              "privacy": "private",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "reflecting",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "guard: true while an imperative setter is reflecting its value back to an attribute, so the\nresulting attributeChangedCallback skips re-applying it (no double-apply / feedback loop) — #541.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "overlayCanvas",
+              "type": {
+                "text": "HTMLCanvasElement | undefined"
+              },
+              "privacy": "private",
+              "description": "Field Surfaces: the optional front overlay surface (light-DOM, above content).",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "visibilityObserver",
+              "type": {
+                "text": "IntersectionObserver | undefined"
+              },
+              "privacy": "private",
+              "description": "element-level visibility: pages can hide the field (display:none) — skip draw work then.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "fieldVisible",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "true",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "platformRuntime",
+              "type": {
+                "text": "PlatformRuntime | undefined"
+              },
+              "description": "experimental platform runtime (Phase D); present only when the flag is on.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "platform",
+              "type": {
+                "text": "FieldPlatform | undefined"
+              },
+              "description": "The live `@fundamental-engine/dom` instance backing this field (Phase D default), or `undefined` on\nthe legacy path. Read-only introspection for tools like the Inspector — the registries here are\nthe real running state (measurements, state, feedback bindings, relationships, overlays, lint).\nRead with `measure.last()` etc.; don't call `measure.measure()` off the read phase.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "accent",
+              "type": {
+                "text": "string"
+              },
+              "description": "the travelling accent (§9); defaults to the first palette color.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "density",
+              "type": {
+                "text": "number"
+              },
+              "description": "particle-count multiplier (§2.5).",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "waves",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "draw the background Currents (§24).",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "kind": "field",
-              "name": "OPTIONS",
+              "name": "renderMode",
               "type": {
-                "text": "ReadonlyArray<{\n    key: keyof FieldOptions;\n    attr: string;\n    read: (el: FieldField) => unknown;\n  }>"
+                "text": "'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'none'"
               },
-              "privacy": "private",
-              "static": true,
+              "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,
-              "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 }, ]",
-              "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",
                 "module": "src/index.ts"
@@ -1368,11 +1866,11 @@
             },
             {
               "kind": "field",
-              "name": "canvas",
+              "name": "background",
               "type": {
-                "text": "HTMLCanvasElement"
+                "text": "'opaque' | 'transparent'"
               },
-              "privacy": "private",
+              "description": "substrate background: `transparent` (present and not `\"false\"`) clears to transparent so the\nunderlay composites over light content; default `opaque` paints the near-black substrate.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1381,11 +1879,12 @@
             },
             {
               "kind": "field",
-              "name": "field",
+              "name": "overlay",
               "type": {
-                "text": "FieldHandle | undefined"
+                "text": "OverlayInput"
               },
-              "privacy": "private",
+              "description": "Field Surfaces: the overlay reading(s) — one mode or a space-separated additive stack. Default `off`.",
+              "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
                 "module": "src/index.ts"
@@ -1393,12 +1892,12 @@
             },
             {
               "kind": "field",
-              "name": "overlayCanvas",
+              "name": "palette",
               "type": {
-                "text": "HTMLCanvasElement | undefined"
+                "text": "string | undefined"
               },
-              "privacy": "private",
-              "description": "Field Surfaces: the optional front overlay surface (light-DOM, above content).",
+              "description": "color template name for the travelling accent (§9), or undefined for `ours`.",
+              "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
                 "module": "src/index.ts"
@@ -1406,12 +1905,12 @@
             },
             {
               "kind": "field",
-              "name": "visibilityObserver",
+              "name": "attention",
               "type": {
-                "text": "IntersectionObserver | undefined"
+                "text": "boolean"
               },
-              "privacy": "private",
-              "description": "element-level visibility: pages can hide the field (display:none) — skip draw work then.",
+              "description": "conserved attention (§2.4): present and not `\"false\"` → one finite strength budget.",
+              "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
                 "module": "src/index.ts"
@@ -1419,12 +1918,12 @@
             },
             {
               "kind": "field",
-              "name": "fieldVisible",
+              "name": "causality",
               "type": {
                 "text": "boolean"
               },
-              "privacy": "private",
-              "default": "true",
+              "description": "cross-boundary causality (Concept 4): present and not `\"false\"` → density spills.",
+              "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
                 "module": "src/index.ts"
@@ -1432,11 +1931,12 @@
             },
             {
               "kind": "field",
-              "name": "platformRuntime",
+              "name": "mass",
               "type": {
-                "text": "PlatformRuntime | undefined"
+                "text": "boolean"
               },
-              "description": "experimental platform runtime (Phase D); present only when the flag is on.",
+              "description": "first-class mass (§21.3): present and not `\"false\"` → particle mass ∝ size.",
+              "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
                 "module": "src/index.ts"
@@ -1444,11 +1944,11 @@
             },
             {
               "kind": "field",
-              "name": "platform",
+              "name": "heatmap",
               "type": {
-                "text": "FieldPlatform | undefined"
+                "text": "boolean"
               },
-              "description": "The live `@fundamental-engine/dom` instance backing this field (Phase D default), or `undefined` on\nthe legacy path. Read-only introspection for tools like the Inspector — the registries here are\nthe real running state (measurements, state, feedback bindings, relationships, overlays, lint).\nRead with `measure.last()` etc.; don't call `measure.measure()` off the read phase.",
+              "description": "density heatmap (field-systems H1): present and not `\"false\"` → the pooling glow underlay.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1457,11 +1957,11 @@
             },
             {
               "kind": "field",
-              "name": "accent",
+              "name": "dprCap",
               "type": {
-                "text": "string"
+                "text": "number | undefined"
               },
-              "description": "the travelling accent (§9); defaults to the first palette color.",
+              "description": "`dpr-cap` — backing-store DPR ceiling (#410); undefined (engine default 2) if absent/invalid.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1470,11 +1970,11 @@
             },
             {
               "kind": "field",
-              "name": "density",
+              "name": "depth",
               "type": {
-                "text": "number"
+                "text": "number | undefined"
               },
-              "description": "particle-count multiplier (§2.5).",
+              "description": "`depth` — optional z-volume; undefined (engine default 0, the flat field) if absent/invalid.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1483,11 +1983,11 @@
             },
             {
               "kind": "field",
-              "name": "waves",
+              "name": "gridWarp",
               "type": {
-                "text": "boolean"
+                "text": "number | undefined"
               },
-              "description": "draw the background Currents (§24).",
+              "description": "`grid-warp` — `grid` overlay distortion multiplier; undefined (engine default 1) if absent/invalid.\n`0` is valid (a flat, undistorted lattice).",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1496,11 +1996,11 @@
             },
             {
               "kind": "field",
-              "name": "renderMode",
+              "name": "gridIntensity",
               "type": {
-                "text": "'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'none'"
+                "text": "number | undefined"
               },
-              "description": "render mode (§20.6); `none` = the signals-only engine — simulate + feed back, never draw (#297).",
+              "description": "`grid-intensity` — `grid` overlay stroke opacity ∈ [0,1]; undefined (engine default 0.16, the faint\ndiagnostic) if absent/invalid. Raise it (≈0.5) to make the warped lattice a visual centerpiece.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1509,11 +2009,11 @@
             },
             {
               "kind": "field",
-              "name": "background",
+              "name": "separation",
               "type": {
-                "text": "'opaque' | 'transparent'"
+                "text": "number | undefined"
               },
-              "description": "substrate background: `transparent` (present and not `\"false\"`) clears to transparent so the\nunderlay composites over light content; default `opaque` paints the near-black substrate.",
+              "description": "`separation` — particle-to-particle separation force strength ∈ [0,1]; undefined if absent/invalid.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1522,11 +2022,11 @@
             },
             {
               "kind": "field",
-              "name": "overlay",
+              "name": "theme",
               "type": {
-                "text": "OverlayInput"
+                "text": "string | undefined"
               },
-              "description": "Field Surfaces: the overlay reading(s) — one mode or a space-separated additive stack. Default `off`.",
+              "description": "`theme` — ambient palette preset (`warm` (default) | `cool` | `mono`); undefined if absent (#529).",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1535,11 +2035,11 @@
             },
             {
               "kind": "field",
-              "name": "palette",
+              "name": "gradientCool",
               "type": {
                 "text": "string | undefined"
               },
-              "description": "color template name for the travelling accent (§9), or undefined for `ours`.",
+              "description": "`gradient-cool` — hex for the cool end of the heat ramp; overrides the theme (#529).",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1548,11 +2048,11 @@
             },
             {
               "kind": "field",
-              "name": "attention",
+              "name": "gradientWarm",
               "type": {
-                "text": "boolean"
+                "text": "string | undefined"
               },
-              "description": "conserved attention (§2.4): present and not `\"false\"` → one finite strength budget.",
+              "description": "`gradient-warm` — hex for the warm end of the heat ramp; overrides the theme (#529).",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1561,11 +2061,11 @@
             },
             {
               "kind": "field",
-              "name": "causality",
+              "name": "waveBaseline",
               "type": {
-                "text": "boolean"
+                "text": "readonly string[] | undefined"
               },
-              "description": "cross-boundary causality (Concept 4): present and not `\"false\"` → density spills.",
+              "description": "`wave-baseline` — space-separated hex stops for the wave baseline; overrides the theme (#529).",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1574,11 +2074,11 @@
             },
             {
               "kind": "field",
-              "name": "mass",
+              "name": "waveStyle",
               "type": {
-                "text": "boolean"
+                "text": "'linear' | 'circular'"
               },
-              "description": "first-class mass (§21.3): present and not `\"false\"` → particle mass ∝ size.",
+              "description": "`wave-style` — wave layout style: `'linear'` | `'circular'`",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1587,11 +2087,11 @@
             },
             {
               "kind": "field",
-              "name": "heatmap",
+              "name": "waveCenter",
               "type": {
-                "text": "boolean"
+                "text": "{ x: number; y: number } | null"
               },
-              "description": "density heatmap (field-systems H1): present and not `\"false\"` → the pooling glow underlay.",
+              "description": "`wave-center` — coordinates string space-separated e.g. \"200 300\"",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1600,11 +2100,11 @@
             },
             {
               "kind": "field",
-              "name": "dprCap",
+              "name": "formation",
               "type": {
-                "text": "number | undefined"
+                "text": "string | undefined"
               },
-              "description": "`dpr-cap` — backing-store DPR ceiling (#410); undefined (engine default 2) if absent/invalid.",
+              "description": "`formation` — the global formation (§7), applied live; undefined if absent. Unlike the other\nattributes this is post-construction (set via `setFormation`), but it round-trips: the attribute\ndrives the field and `setFormation` reflects back to it (#541).",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
@@ -1613,17 +2113,46 @@
             },
             {
               "kind": "field",
-              "name": "depth",
+              "name": "handle",
               "type": {
-                "text": "number | undefined"
+                "text": "FieldHandle | undefined"
               },
-              "description": "`depth` — optional z-volume; undefined (engine default 0, the flat field) if absent/invalid.",
+              "description": "the live `FieldHandle` this element drives, or `undefined` before mount / after teardown (#542).\nEvery method below is forwarded for convenience, but `.handle` is the escape hatch for the full\nsurface and for passing the field to `bindData` / `applyRecipe` (both from `@fundamental-engine/dom`):\n`import { bindData } from '@fundamental-engine/dom'; bindData(el.handle, rows, spec);`",
               "readonly": true,
               "inheritedFrom": {
                 "name": "FieldField",
                 "module": "src/index.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "reflect",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "attr",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "value",
+                  "type": {
+                    "text": "string | null"
+                  }
+                }
+              ],
+              "description": "reflect an imperative setter's value back to its attribute, so attribute-based debugging shows the\nLIVE state (the bug from #541 was a stale `render=\"none\"` after `setRender`). Guarded so the\nresulting attributeChangedCallback does not re-apply it. Pass `null` to remove the attribute.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "scan",
@@ -1718,6 +2247,72 @@
                 "module": "src/index.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "setWaveStyle",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "style",
+                  "type": {
+                    "text": "'linear' | 'circular'"
+                  }
+                }
+              ],
+              "description": "switch the wave current layout style.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "setWaveCenter",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "center",
+                  "type": {
+                    "text": "{ x: number; y: number } | (() => { x: number; y: number }) | null"
+                  }
+                }
+              ],
+              "description": "set the custom wave center coordinate (or function).",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "setSeparation",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "strength",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "set particle-to-particle separation/repulsion force strength.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "setAttention",
@@ -1828,6 +2423,28 @@
                 "module": "src/index.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "setQualityTier",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "tier",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "apply an adaptive quality tier 0–3 (#413) — the platform runtime forwards the governor's tier.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "setRender",
@@ -2382,6 +2999,55 @@
                 "module": "src/index.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "version",
+              "type": {
+                "text": "string"
+              },
+              "description": "the running engine version (`FIELD_VERSION`) — available before mount too.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "scrollV",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "description": "the page's scroll velocity the engine tracks (drives `--field-scroll-v`); 0 before mount.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "setVisible",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "on",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "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.",
+              "inheritedFrom": {
+                "name": "FieldField",
+                "module": "src/index.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "start",
@@ -2544,6 +3210,14 @@
             "name": "RegisterBodyDetail",
             "package": "@fundamental-engine/core"
           }
+        },
+        {
+          "kind": "js",
+          "name": "FIELD_VERSION",
+          "declaration": {
+            "name": "FIELD_VERSION",
+            "package": "@fundamental-engine/core"
+          }
         }
       ]
     },