@oicl/openbridge-webcomponents 2.0.0-next.170 → 2.0.0-next.171

package/custom-elements.json

@@ -1548,6 +1548,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Expanded-group presentation state, applied by the owning group composition while the button is shown inside an expanded `obc-poi-group` and during its collapse animations. Consumers should not set it directly.",
               "attribute": "inExpandedGroup",
               "inheritedFrom": {
                 "name": "ObcPoiButton",
@@ -1604,6 +1605,15 @@
                 "module": "src/ar/poi-button/poi-button.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "handleLightSlotChange",
+              "privacy": "private",
+              "inheritedFrom": {
+                "name": "ObcPoiButton",
+                "module": "src/ar/poi-button/poi-button.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "setupHeaderContentObserver",
@@ -1911,6 +1921,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Expanded-group presentation state, applied by the owning group composition while the button is shown inside an expanded `obc-poi-group` and during its collapse animations. Consumers should not set it directly.",
               "fieldName": "inExpandedGroup",
               "inheritedFrom": {
                 "name": "ObcPoiButton",
@@ -2188,6 +2199,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Expanded-group presentation state, applied by the owning group composition while the button is shown inside an expanded `obc-poi-group` and during its collapse animations. Consumers should not set it directly.",
               "attribute": "inExpandedGroup",
               "inheritedFrom": {
                 "name": "ObcPoiButton",
@@ -2244,6 +2256,15 @@
                 "module": "src/ar/poi-button/poi-button.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "handleLightSlotChange",
+              "privacy": "private",
+              "inheritedFrom": {
+                "name": "ObcPoiButton",
+                "module": "src/ar/poi-button/poi-button.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "setupHeaderContentObserver",
@@ -2544,6 +2565,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Expanded-group presentation state, applied by the owning group composition while the button is shown inside an expanded `obc-poi-group` and during its collapse animations. Consumers should not set it directly.",
               "fieldName": "inExpandedGroup",
               "inheritedFrom": {
                 "name": "ObcPoiButton",
@@ -2838,6 +2860,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Expanded-group presentation state, applied by the owning group composition while the button is shown inside an expanded `obc-poi-group` and during its collapse animations. Consumers should not set it directly.",
               "attribute": "inExpandedGroup",
               "inheritedFrom": {
                 "name": "ObcPoiButton",
@@ -2894,6 +2917,15 @@
                 "module": "src/ar/poi-button/poi-button.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "handleLightSlotChange",
+              "privacy": "private",
+              "inheritedFrom": {
+                "name": "ObcPoiButton",
+                "module": "src/ar/poi-button/poi-button.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "setupHeaderContentObserver",
@@ -3201,6 +3233,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Expanded-group presentation state, applied by the owning group composition while the button is shown inside an expanded `obc-poi-group` and during its collapse animations. Consumers should not set it directly.",
               "fieldName": "inExpandedGroup",
               "inheritedFrom": {
                 "name": "ObcPoiButton",
@@ -3299,7 +3332,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<obc-poi-button>` - Marker button component that renders an icon target with optional header and data rows.\n\n## Overview\nUse this component when you need a button-style marker that can show stateful framing and optional metric rows.\nKeywords/synonyms: marker button, target button, icon target, POI button.\n\n## Features/Variants\n- `type` (default `button`): `button` or `enhanced` size.\n- `layout` (default `anchored`): `anchored` or `inline`.\n- `value` (default `unchecked`): `unchecked`, `checked`, `activated`, `overlapped`.\n- `overlapOpaque` (default `false`): controls overlapped opacity mode (`false` = translucent, `true` = opaque).\n- `state` (default `enabled`): `enabled`, `caution`, `warning`, `alarm`, `level-critical`, `level-high`, `level-medium`, `level-low`, `level-diagnostic`.\n- `selected` (default `false`): shows selection frame in anchored layout.\n- `relativeDirection` (default `0`): rotates default-slot icon content in degrees.\n- `data` (default `[]`): when non-empty, renders value/label/unit rows.\n- `hasHeader` + `header` slot: renders a header area and syncs slotted `obc-poi-header` state.\n- `hasRelation` (default `false`): enables optional relation content in data mode.\n- `inExpandedGroup` (default `false`): applies `expanded` CSS class.\n- TODO(designer): Confirm intended UX semantics for `inExpandedGroup` beyond styling.\n\n## Usage Guidelines\n- Use `layout=\"anchored\"` for standalone marker buttons.\n- Use `layout=\"inline\"` when this component is embedded in a larger marker composition.\n- Provide `data` for metric display variants.\n- Enable `hasRelation` only when relation slot content is provided.\n\n## Slots/Content\n- Default slot: Icon/content rendered inside `obc-poi-object`.\n- `header`: Optional header content rendered above the marker body.\n- `relation`: Optional relation icon/content rendered when `hasRelation` is true in data mode.\n\n## Events\nThis component emits no custom events. A standard `click` bubbles from the\ninternal `<button>` (`onClick` in the framework wrappers).\n\n## Best Practices\n- Keep `value`, `state`, and `selected` synchronized to avoid conflicting visual states.\n- Prefer enum values for `type`, `layout`, `state`, and `value`.\n\n## Example\n```html\n<obc-poi-button type=\"button\" layout=\"anchored\" value=\"checked\" selected>\n  <obi-placeholder></obi-placeholder>\n  <obc-poi-header slot=\"header\" content=\"1\"></obc-poi-header>\n</obc-poi-button>\n```",
+          "description": "`<obc-poi-button>` - Marker button component that renders an icon target with optional header and data rows.\n\n## Overview\nUse this component when you need a button-style marker that can show stateful framing and optional metric rows.\nKeywords/synonyms: marker button, target button, icon target, POI button.\n\n## Features/Variants\n- `type` (default `button`): `button` or `enhanced` size.\n- `layout` (default `anchored`): `anchored` or `inline`.\n- `value` (default `unchecked`): `unchecked`, `checked`, `activated`, `overlapped`.\n- `overlapOpaque` (default `false`): controls overlapped opacity mode (`false` = translucent, `true` = opaque).\n- `state` (default `enabled`): `enabled`, `caution`, `warning`, `alarm`, `level-critical`, `level-high`, `level-medium`, `level-low`, `level-diagnostic`.\n- `selected` (default `false`): shows selection frame in anchored layout.\n- `relativeDirection` (default `0`): rotates default-slot icon content in degrees.\n- `data` (default `[]`): when non-empty, renders value/label/unit rows.\n- `hasHeader` + `header` slot: renders a header area and syncs slotted `obc-poi-header` state.\n- `hasRelation` (default `false`): enables optional relation content in data mode.\n- `inExpandedGroup` (default `false`): expanded-group presentation state, applied by the owning group composition during expand/collapse orchestration; consumers should not set it directly.\n\n## Usage Guidelines\n- Use `layout=\"anchored\"` for standalone marker buttons.\n- Use `layout=\"inline\"` when this component is embedded in a larger marker composition.\n- Provide `data` for metric display variants.\n- Enable `hasRelation` only when relation slot content is provided.\n\n## Slots/Content\n- Default slot: Icon/content rendered inside `obc-poi-object`.\n- `header`: Optional header content rendered above the marker body.\n- `relation`: Optional relation icon/content rendered when `hasRelation` is true in data mode.\n\n## Events\nThis component emits no custom events. A standard `click` bubbles from the\ninternal `<button>` (`onClick` in the framework wrappers).\n\n## Best Practices\n- Keep `value`, `state`, and `selected` synchronized to avoid conflicting visual states.\n- Prefer enum values for `type`, `layout`, `state`, and `value`.\n\n## Example\n```html\n<obc-poi-button type=\"button\" layout=\"anchored\" value=\"checked\" selected>\n  <obi-placeholder></obi-placeholder>\n  <obc-poi-header slot=\"header\" content=\"1\"></obc-poi-header>\n</obc-poi-button>\n```",
           "name": "ObcPoiButton",
           "slots": [
             {
@@ -3388,6 +3421,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Expanded-group presentation state, applied by the owning group composition while the button is shown inside an expanded `obc-poi-group` and during its collapse animations. Consumers should not set it directly.",
               "attribute": "inExpandedGroup"
             },
             {
@@ -3424,6 +3458,11 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "handleLightSlotChange",
+              "privacy": "private"
+            },
             {
               "kind": "method",
               "name": "setupHeaderContentObserver",
@@ -3615,6 +3654,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Expanded-group presentation state, applied by the owning group composition while the button is shown inside an expanded `obc-poi-group` and during its collapse animations. Consumers should not set it directly.",
               "fieldName": "inExpandedGroup"
             },
             {
@@ -3950,8 +3990,26 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<obc-poi-card>` - Content card container with optional pointer arrow, header variants, and interactive click handling.\n\n## Overview\nUse this component to wrap contextual marker details in a card with optional directional anchoring.\nKeywords/synonyms: detail card, marker card, anchored card, popover card.\n\n## Features/Variants\n- `pointerDirection` (default `none`): `none`, `top`, `bottom`, `left`, `right`.\n- `fixedSize` (default `false`): toggles fixed `256x256` sizing instead of content-based sizing.\n- Header options:\n  - `showHeader` controls whether the header area is visible.\n  - `headerVariant` controls header layout (`tag`, `condensed`, `regular`, `detailed`).\n  - `index`, `cardTitle`, `description`, `source`, `timestamp` are forwarded to `obc-poi-card-header`.\n  - `hasLeadingIcon` and `hasCloseButton` gate header affordances.\n- `interactive` (default `false`): enables keyboard activation and `card-click` dispatch.\n- `hasAlert` (default `false`): shows alert ring layer when `interactive` is enabled.\n\n## Usage Guidelines\n- Use `pointerDirection` when the card should visually point to an anchor target.\n- Keep `interactive` off for read-only cards.\n- Use the header slots only when the selected `headerVariant` renders them.\n\n## Slots/Content\n- Default slot: Main card body content.\n- `leading-icon`: Optional icon used by the regular header variant.\n- `poi-icon`: Optional icon used by the detailed header variant.\n\n## Events\n- `card-click`: Fired when the card surface is activated in interactive mode.\n\n## Best Practices\n- Keep `index` stable so event payloads remain predictable.\n- Pair `hasAlert` with meaningful alert state in surrounding UI logic.\n\n## Example\n```html\n<obc-poi-card pointerDirection=\"bottom\" index=\"1\" cardTitle=\"Target\" interactive>\n  <obi-placeholder slot=\"leading-icon\"></obi-placeholder>\n  <div>Custom card content</div>\n</obc-poi-card>\n```",
+          "description": "`<obc-poi-card>` - Content card container with optional pointer arrow, header variants, and interactive click handling.\n\n## Overview\nUse this component to wrap contextual marker details in a card with optional directional anchoring.\nKeywords/synonyms: detail card, marker card, anchored card, popover card.\n\n## Features/Variants\n- `pointerDirection` (default `none`): `none`, `top`, `bottom`, `left`, `right`.\n- `fixedSize` (default `false`): toggles fixed `256x256` sizing instead of content-based sizing.\n- Header options:\n  - `showHeader` controls whether the header area is visible.\n  - `headerVariant` controls header layout (`tag`, `condensed`, `regular`, `detailed`).\n  - `index`, `cardTitle`, `description`, `source`, `timestamp` are forwarded to `obc-poi-card-header`.\n  - `hasLeadingIcon` and `hasCloseButton` gate header affordances.\n- `interactive` (default `false`): enables keyboard activation and `card-click` dispatch.\n- `hasAlert` (default `false`): shows alert ring layer when `interactive` is enabled.\n\n## Usage Guidelines\n- Use `pointerDirection` when the card should visually point to an anchor target.\n- Keep `interactive` off for read-only cards.\n- Use the header slots only when the selected `headerVariant` renders them.\n\n## Slots/Content\n- Default slot: Main card body content.\n- `leading-icon`: Optional icon used by the regular header variant.\n- `poi-icon`: Optional icon used by the detailed header variant.\n\n## Events\n- `card-click`: Fired when the card surface is activated in interactive mode.\n- `close-click`: Fired when the header close button is pressed (`hasCloseButton` with the detailed header variant).\n\n## CSS Parts\n- `wrapper`: Outer layout wrapper holding the pointer arrows and the card surface.\n- `content-box`: Card surface with background, border, and rounded corners.\n- `header`: The `obc-poi-card-header` element, rendered when `showHeader` is true.\n- `content`: Body area wrapping the default slot.\n\n## Best Practices\n- Keep `index` stable so event payloads remain predictable.\n- Pair `hasAlert` with meaningful alert state in surrounding UI logic.\n\n## Example\n```html\n<obc-poi-card pointerDirection=\"bottom\" index=\"1\" cardTitle=\"Target\" interactive>\n  <obi-placeholder slot=\"leading-icon\"></obi-placeholder>\n  <div>Custom card content</div>\n</obc-poi-card>\n```",
           "name": "ObcPoiCard",
+          "cssParts": [
+            {
+              "description": "Outer layout wrapper holding the pointer arrows and the card surface.",
+              "name": "wrapper"
+            },
+            {
+              "description": "Card surface with background, border, and rounded corners.",
+              "name": "content-box"
+            },
+            {
+              "description": "The `obc-poi-card-header` element, rendered when `showHeader` is true.",
+              "name": "header"
+            },
+            {
+              "description": "Body area wrapping the default slot.",
+              "name": "content"
+            }
+          ],
           "slots": [
             {
               "description": "Main card body content.",
@@ -4194,7 +4252,7 @@
               "type": {
                 "text": "CustomEvent<void>"
               },
-              "description": "Passed on from the header when its close button is pressed (`hasCloseButton`).",
+              "description": "Passed on from the header when its close button is pressed (`hasCloseButton` with the detailed header variant).",
               "name": "close-click"
             }
           ],
@@ -4345,7 +4403,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<obc-poi-controller>` — Maps detection data onto POI markers over a video or image.\n\nTakes detection coordinates in media pixel space (e.g. x,y in a 1920x1080 frame),\nprojects them to screen space using the media's rendered size and fit mode, and\ncreates/updates `obc-poi-data` targets inside a layer stack.\n\n## Quick Start\n\nThe media slot accepts a `<video>` (live stream, HLS, file) or `<img>` element.\n\n```html\n<obc-poi-controller fit=\"cover\">\n  <video slot=\"media\" src=\"stream.mp4\" autoplay muted></video>\n  <obc-poi-layer-stack slot=\"stack\" selection-mode=\"multi\">\n    <obc-poi-layer is-selected></obc-poi-layer>\n    <obc-poi-layer data-controller-layer=\"background\"></obc-poi-layer>\n  </obc-poi-layer-stack>\n</obc-poi-controller>\n```\n\nThen set detections from your data source (WebSocket, API, etc.):\n\n```js\nconst controller = document.querySelector('obc-poi-controller');\ncontroller.detections = [\n  { id: 'track-1', x: 400, y: 800, box_width: 50, box_height: 40, heading: -15 },\n  { id: 'track-2', x: 900, y: 750, box_width: 35, box_height: 30, heading: 45 },\n];\n```\n\n## Framework Usage\n\n**Lit:**\n```html\n<obc-poi-controller .detections=${detections} fit=\"cover\">\n```\n\n**Vue:**\n```html\n<obc-poi-controller :detections=\"detections\" fit=\"cover\">\n```\n\n**Svelte:**\n```html\n<obc-poi-controller detections={detections} fit=\"cover\">\n```\n\n**React 18** (needs ref for array props):\n```tsx\nconst ref = useRef(null);\nuseEffect(() => { ref.current.detections = detections; }, [detections]);\n<obc-poi-controller ref={ref} fit=\"cover\">\n```\n\n**React 19+** (native custom element support):\n```tsx\n<obc-poi-controller detections={detections} fit=\"cover\">\n```\n\n## Coordinate Model\n\nDetection `x` and `y` are in **media pixel space** (e.g. 0-1920 for a 1920x1080 video).\nThe controller projects them to screen space using the `fit` mode (`contain` or `cover`)\nand the media element's rendered dimensions.\n\nThe Y coordinate maps to the line length from the layer's top edge down to the\ndetection point. The button sits at the top of the layer; the line extends downward.\n\n## Detection Data\n\nEach detection can include:\n- `x`, `y` (required) — position in media pixel space\n- `id` — stable identity key (prevents marker churn when array order changes)\n- `box_width`, `box_height` — bounding box size; determines button type (regular vs enhanced)\n- `heading` or `direction` — rotation angle for the icon arrow (degrees)\n- `confidence` — filtered by `confidenceMin`\n- `class` — filtered by `classFilter`\n\n## Layer Setup\n\nThe stack needs at least two layers:\n1. A **selected layer** (`is-selected`) — targets jump here when clicked\n2. A **background layer** (`data-controller-layer=\"background\"`) — where the controller places targets\n\nIf no `data-controller-layer=\"background\"` is set, the controller uses the first non-selected layer.\n\n## Selection\n\nClicking a target moves it to the selected layer with a FLIP animation.\nThe controller does not interfere with selected targets — it only manages\ntargets in the background layer. The layer-stack owns selection state.\n\n## CSS Custom Properties\n\n- `--obc-poi-controller-stack-top` (default `15%`) — vertical position of the stack\n- `--obc-poi-controller-stack-height` (default `50%`) — height of the stack\n- `--obc-poi-controller-stack-gap` (default `8px`) — gap between layers",
+          "description": "`<obc-poi-controller>` — Maps detection data onto POI markers over a video or image.\n\nTakes detection coordinates in media pixel space (e.g. x,y in a 1920x1080 frame),\nprojects them to screen space using the media's rendered size and fit mode, and\ncreates/updates POI targets inside a layer stack (`obc-poi-data` by default;\n`obc-poi-vessel`/`obc-poi-aton` via each detection's `variant`, with optional\nper-detection `icon`, `state`, and `data`).\n\n## Quick Start\n\nThe media slot accepts a `<video>` (live stream, HLS, file) or `<img>` element.\n\n```html\n<obc-poi-controller fit=\"cover\">\n  <video slot=\"media\" src=\"stream.mp4\" autoplay muted></video>\n  <obc-poi-layer-stack slot=\"stack\" selection-mode=\"multi\">\n    <obc-poi-layer is-selected></obc-poi-layer>\n    <obc-poi-layer data-controller-layer=\"background\"></obc-poi-layer>\n  </obc-poi-layer-stack>\n</obc-poi-controller>\n```\n\nThen set detections from your data source (WebSocket, API, etc.):\n\n```js\nconst controller = document.querySelector('obc-poi-controller');\ncontroller.detections = [\n  { id: 'track-1', x: 400, y: 800, box_width: 50, box_height: 40, heading: -15 },\n  { id: 'track-2', x: 900, y: 750, box_width: 35, box_height: 30, heading: 45 },\n];\n```\n\n## Framework Usage\n\n**Lit:**\n```html\n<obc-poi-controller .detections=${detections} fit=\"cover\">\n```\n\n**Vue:**\n```html\n<obc-poi-controller :detections=\"detections\" fit=\"cover\">\n```\n\n**Svelte:**\n```html\n<obc-poi-controller detections={detections} fit=\"cover\">\n```\n\n**React 18** (needs ref for array props):\n```tsx\nconst ref = useRef(null);\nuseEffect(() => { ref.current.detections = detections; }, [detections]);\n<obc-poi-controller ref={ref} fit=\"cover\">\n```\n\n**React 19+** (native custom element support):\n```tsx\n<obc-poi-controller detections={detections} fit=\"cover\">\n```\n\n## Framework Notes\n\nBoth paths are safe for declarative renderers (React, Vue, Lit): the\n`detections` API creates and owns the resulting `obc-poi-data` elements,\nand manually slotted POI children are never moved, re-parented, or\nmodified structurally by the library — selection is rendered by CSS\nprojection and auto-grouping happens inside the layer's shadow root via\nslot assignment. Frameworks can manage POI children as ordinary\nframework-owned elements.\n\n## Coordinate Model\n\nDetection `x` and `y` are in **media pixel space** (e.g. 0-1920 for a 1920x1080 video).\nThe controller projects them to screen space using the `fit` mode (`contain` or `cover`)\nand the media element's rendered dimensions.\n\nThe Y coordinate maps to the line length from the layer's top edge down to the\ndetection point. The button sits at the top of the layer; the line extends downward.\n\n## Detection Data\n\nEach detection can include:\n- `x`, `y` (required) — position in media pixel space\n- `id` — stable identity key (prevents marker churn when array order changes)\n- `box_width`, `box_height` — bounding box size; determines button type (regular vs enhanced)\n- `heading` or `direction` — rotation angle for the icon arrow (degrees)\n- `confidence` — filtered by `confidenceMin`\n- `class` — filtered by `classFilter`\n\n## Layer Setup\n\nThe stack needs at least two layers:\n1. A **selected layer** (`is-selected`) — targets jump here when clicked\n2. A **background layer** (`data-controller-layer=\"background\"`) — where the controller places targets\n\nIf no `data-controller-layer=\"background\"` is set, the controller uses the first non-selected layer.\n\n## Selection\n\nClicking a target moves it to the selected layer with a FLIP animation.\nThe controller does not interfere with selected targets — it only manages\ntargets in the background layer. The layer-stack owns selection state.\n\n## CSS Custom Properties\n\n- `--obc-poi-controller-stack-top` (default `15%`) — vertical position of the stack\n- `--obc-poi-controller-stack-height` (default `50%`) — height of the stack\n- `--obc-poi-controller-stack-gap` (default `8px`) — gap between layers",
           "name": "ObcPoiController",
           "slots": [
             {
@@ -4419,6 +4477,26 @@
               },
               "default": "null"
             },
+            {
+              "kind": "field",
+              "name": "xFilterCutoffHz",
+              "type": {
+                "text": "number | null"
+              },
+              "default": "null",
+              "description": "Forwarded to every controller-owned target's `xFilterCutoffHz`; `null` leaves the targets on their default.",
+              "attribute": "x-filter-cutoff-hz"
+            },
+            {
+              "kind": "field",
+              "name": "yFilterCutoffHz",
+              "type": {
+                "text": "number | null"
+              },
+              "default": "null",
+              "description": "Forwarded to every controller-owned target's `yFilterCutoffHz`; `null` leaves the targets on their default.",
+              "attribute": "y-filter-cutoff-hz"
+            },
             {
               "kind": "field",
               "name": "mediaWidth",
@@ -4510,7 +4588,7 @@
               "kind": "field",
               "name": "controllerTargets",
               "privacy": "private",
-              "default": "new Map<string, ObcPoiData>()"
+              "default": "new Map<string, PoiBase>()"
             },
             {
               "kind": "field",
@@ -4635,6 +4713,16 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "computeCurrentProjection",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "MediaProjection | null"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "mapDetection",
@@ -4650,6 +4738,13 @@
                   "type": {
                     "text": "PoiDetection"
                   }
+                },
+                {
+                  "name": "projection",
+                  "default": "this.computeCurrentProjection()",
+                  "type": {
+                    "text": "MediaProjection | null"
+                  }
                 }
               ]
             },
@@ -4706,6 +4801,24 @@
               },
               "default": "null",
               "fieldName": "classFilter"
+            },
+            {
+              "name": "x-filter-cutoff-hz",
+              "type": {
+                "text": "number | null"
+              },
+              "default": "null",
+              "description": "Forwarded to every controller-owned target's `xFilterCutoffHz`; `null` leaves the targets on their default.",
+              "fieldName": "xFilterCutoffHz"
+            },
+            {
+              "name": "y-filter-cutoff-hz",
+              "type": {
+                "text": "number | null"
+              },
+              "default": "null",
+              "description": "Forwarded to every controller-owned target's `yFilterCutoffHz`; `null` leaves the targets on their default.",
+              "fieldName": "yFilterCutoffHz"
             }
           ],
           "superclass": {
@@ -4717,6 +4830,22 @@
         }
       ],
       "exports": [
+        {
+          "kind": "js",
+          "name": "POI_CONTROLLER_LAYER_ATTR",
+          "declaration": {
+            "name": "POI_CONTROLLER_LAYER_ATTR",
+            "module": "src/ar/poi-controller/poi-controller.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "POI_CONTROLLER_BACKGROUND_LAYER",
+          "declaration": {
+            "name": "POI_CONTROLLER_BACKGROUND_LAYER",
+            "module": "src/ar/poi-controller/poi-controller.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "ObcPoiController",
@@ -4741,7 +4870,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<obc-poi-group>` - A POI cluster component that collapses overlapping targets into one trigger and expands them into a spread list.\n\nThis component wraps multiple `obc-poi-data` elements and manages their collapsed/expanded presentation as a single interactive unit.\nUse it when nearby targets should be presented as one grouped control until the user expands the group.\n\n### Features\n- Expand/collapse state: Controlled by `expand`; collapse animation state is exposed through `collapsing`.\n- Automatic wrapper sizing: Computes collapsed wrapper width/height from slotted target button bounds.\n- Front-target handling: Keeps one front target visually prioritized while collapsing other targets into overlap state.\n- Backdrop interaction: Shows a backdrop while expanded and collapses on backdrop click.\n- Dynamic ordering: `internalSwapping` enables reordering while expanded based on current horizontal positions.\n- Vertical placement: `positionVertical` sets the wrapper/group top offset used for collapsed positioning.\n\n### Usage Guidelines\n- Slot only `obc-poi-data` items that should behave as one grouped target set.\n- Control expand/collapse via the `expand` property, or let the built-in wrapper button toggle expansion.\n- Use the `expand` event detail to synchronize nearby standalone targets (for example, set outside targets to overlapped while this group is open).\n- Treat `collapsing` as component-managed runtime state unless you have a specific orchestration need.\n- **TODO(designer):** Confirm whether external consumers should set `collapsing` directly, or if it should remain fully internal.\n\n### Slots\n| Slot | Renders When... | Purpose |\n| --- | --- | --- |\n| default | Always | Contains grouped `obc-poi-data` targets managed by this component. |\n\n### Events\n- `expand` - Fired when expand state changes. Detail: `{ expand: boolean }`.\n- `collapse-finished` - Fired when the collapse animation has fully completed.\n\n### Best Practices\n- Keep grouped targets positioned consistently so wrapper bounds and front-target selection remain stable.\n- Prefer one `obc-poi-group` per overlap cluster rather than nesting groups.\n- Use `internalSwapping` only when live target crossing should reorder expanded items.\n\n### Example\n```html\n<obc-poi-group positionVertical=\"240px\">\n  <obc-poi-data x=\"300\" button-y=\"240\" y=\"240\"></obc-poi-data>\n  <obc-poi-data x=\"320\" button-y=\"240\" y=\"240\"></obc-poi-data>\n  <obc-poi-data x=\"340\" button-y=\"240\" y=\"240\"></obc-poi-data>\n</obc-poi-group>\n```",
+          "description": "`<obc-poi-group>` - A POI cluster component that collapses overlapping targets into one trigger and expands them into a spread list.\n\nThis component wraps multiple `obc-poi-data` elements and manages their collapsed/expanded presentation as a single interactive unit.\nUse it when nearby targets should be presented as one grouped control until the user expands the group.\n\n### Features\n- Expand/collapse state: Controlled by `expand`; collapse animation state is exposed through `collapsing`.\n- Automatic wrapper sizing: Computes collapsed wrapper width/height from slotted target button bounds.\n- Front-target handling: Keeps one front target visually prioritized while collapsing other targets into overlap state.\n- Backdrop interaction: Shows a backdrop while expanded and collapses on backdrop click.\n- Dynamic ordering: `internalSwapping` enables reordering while expanded based on current horizontal positions.\n- Vertical placement: `positionVertical` (attribute `position-vertical`) sets the wrapper/group top offset used for collapsed positioning.\n\n### Usage Guidelines\n- Slot only `obc-poi-data` items that should behave as one grouped target set.\n- Control expand/collapse via the `expand` property, or let the built-in wrapper button toggle expansion.\n- Use the `expand` event detail to synchronize nearby standalone targets (for example, set outside targets to overlapped while this group is open).\n- Treat `collapsing` as orchestration state: it is set by the group itself and by coordinating containers such as `obc-poi-layer-stack` during collapse animations. Do not set it directly.\n- `internalSwapping` is usually set via `obc-poi-layer`'s `internal-swapping` attribute, which forwards it to auto-created groups; set it directly only on manually managed groups.\n\n### Slots\n| Slot | Renders When... | Purpose |\n| --- | --- | --- |\n| default | Always | Contains grouped `obc-poi-data` targets managed by this component. |\n\n### Events\n- `expand` - Fired when expand state changes. Detail: `{ expand: boolean }`.\n- `collapse-finished` - Fired when the collapse animation has fully completed.\n- `obc-poi-group-target-released` - Fired after `releaseTarget()` returns a target to the group's parent context: re-parented for consumer-managed groups, re-assigned to the layer's main slot for layer-created auto groups. Detail: `{ target: Poi }`.\n\n### Best Practices\n- Keep grouped targets positioned consistently so wrapper bounds and front-target selection remain stable.\n- Prefer one `obc-poi-group` per overlap cluster rather than nesting groups.\n- Use `internalSwapping` only when live target crossing should reorder expanded items.\n\n### Example\n```html\n<obc-poi-group position-vertical=\"240px\">\n  <obc-poi-data x=\"300\" button-y=\"240\" y=\"240\"></obc-poi-data>\n  <obc-poi-data x=\"320\" button-y=\"240\" y=\"240\"></obc-poi-data>\n  <obc-poi-data x=\"340\" button-y=\"240\" y=\"240\"></obc-poi-data>\n</obc-poi-group>\n```",
           "name": "ObcPoiGroup",
           "slots": [
             {
@@ -4766,6 +4895,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Collapse-animation state. Set by the group itself and by coordinating containers such as `obc-poi-layer-stack` during collapse orchestration; do not set it directly.",
               "attribute": "collapsing"
             },
             {
@@ -4775,7 +4905,7 @@
                 "text": "string"
               },
               "default": "'0px'",
-              "attribute": "positionVertical"
+              "attribute": "position-vertical"
             },
             {
               "kind": "field",
@@ -4784,6 +4914,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Reorders expanded targets when their horizontal positions cross. Usually set via `obc-poi-layer`'s `internal-swapping` attribute, which forwards it to auto-created groups; set it directly only on manually managed groups.",
               "attribute": "internal-swapping"
             },
             {
@@ -4946,6 +5077,49 @@
               "name": "onSlotChange",
               "privacy": "private"
             },
+            {
+              "kind": "method",
+              "name": "isMember",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "child",
+                  "type": {
+                    "text": "HTMLElement"
+                  }
+                }
+              ],
+              "description": "Membership check that works for both light-DOM children (manual groups)\nand slot-assigned members (layer-created auto groups, where the member\nstays in the consumer's light DOM and is assigned into this group's\nmember slot)."
+            },
+            {
+              "kind": "method",
+              "name": "getMemberSlot",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HTMLSlotElement | null"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "bringChildToFront",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "frontChild",
+                  "type": {
+                    "text": "Poi"
+                  }
+                }
+              ],
+              "description": "Paint the front child on top. For light-DOM members this reorders the\nchildren; for slot-assigned members it re-assigns the member slot, which\nchanges flattened-tree order without touching the consumer's DOM."
+            },
             {
               "kind": "method",
               "name": "ensureFrontChildOnTop",
@@ -5316,7 +5490,7 @@
               "type": {
                 "text": "CustomEvent<{target: Poi}>"
               },
-              "description": "Fired after a target leaves the group and has been re-inserted before it in the parent. Bubbles and is composed."
+              "description": "Fired after `releaseTarget()` returns a target to the group's parent context (re-parented for consumer-managed groups, re-assigned for auto groups) — immediately when the group is collapsed, or once the collapse animation completes. Bubbles and is composed."
             }
           ],
           "attributes": [
@@ -5334,10 +5508,11 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Collapse-animation state. Set by the group itself and by coordinating containers such as `obc-poi-layer-stack` during collapse orchestration; do not set it directly.",
               "fieldName": "collapsing"
             },
             {
-              "name": "positionVertical",
+              "name": "position-vertical",
               "type": {
                 "text": "string"
               },
@@ -5350,6 +5525,7 @@
                 "text": "boolean"
               },
               "default": "false",
+              "description": "Reorders expanded targets when their horizontal positions cross. Usually set via `obc-poi-layer`'s `internal-swapping` attribute, which forwards it to auto-created groups; set it directly only on manually managed groups.",
               "fieldName": "internalSwapping"
             }
           ],
@@ -5386,7 +5562,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<obc-poi-layer-stack>` coordinates multiple POI layers and manages\nselection behavior across stacked layers.\n\nUse `selection-mode` to control whether targets can be selected across the\nstack (`none`, `single`, or `multi`).\n\n### Slots\n- Default slot for `obc-poi-layer` elements that participate in the stack.\n\n### Example\n```html\n<obc-poi-layer-stack selection-mode=\"single\">\n  <obc-poi-layer label=\"Radar\" .isSelected=${true}></obc-poi-layer>\n  <obc-poi-layer label=\"AIS\"></obc-poi-layer>\n</obc-poi-layer-stack>\n```",
+          "description": "`<obc-poi-layer-stack>` coordinates multiple POI layers and manages\nselection behavior across stacked layers.\n\nUse `selection-mode` to control whether targets can be selected across the\nstack (`none`, `single`, or `multi`).\n\n### Required Setup\n1. Place the stack in `obc-poi-controller`'s `slot=\"stack\"`, or manage the\n   stack's height and media geometry yourself.\n2. Give exactly one child `obc-poi-layer` the `is-selected` attribute — the\n   stack projects selected targets' buttons into it and resets all\n   selection state if no selected layer exists.\n3. Mark the background/default layer with\n   `data-controller-layer=\"background\"` when the stack is used inside\n   `obc-poi-controller`.\n4. Set `--obc-poi-layer-min-height` on layers that can start empty, so they\n   do not collapse to 0px height.\n\n### DOM Ownership\nThe stack never moves, creates, or removes consumer-owned DOM. Selection is\nrendered by projecting the target's button into the selected layer via CSS\ncustom properties (`--obc-poi-button-projection-y` /\n`--obc-poi-target-projection-y`); the target element stays where the\nconsumer put it. Declarative renderers (React, Vue, Lit) can manage POI\nchildren as ordinary framework-owned elements.\n\n### Selection API\nSelection state is fully reachable without DOM inspection:\n- `selectedTargets` — the currently selected POI targets.\n- `selectTarget(target, {selectionId?})` — select programmatically;\n  `selectionId` presets the stack-managed badge id.\n- `deselectTarget(target)` / `clearSelection()` — deselect one/all.\n- `selection-change` event — fired on every selection mutation\n  (user click, programmatic call, or bootstrap seeding) with\n  `{selected, added, removed}` in `detail`.\n\n### Slots\n- Default slot for `obc-poi-layer` elements that participate in the stack.\n\n### Example\n```html\n<obc-poi-layer-stack selection-mode=\"single\">\n  <obc-poi-layer label=\"Radar\" .isSelected=${true}></obc-poi-layer>\n  <obc-poi-layer label=\"AIS\"></obc-poi-layer>\n</obc-poi-layer-stack>\n```",
           "name": "ObcPoiLayerStack",
           "slots": [
             {
@@ -5449,7 +5625,14 @@
               "kind": "field",
               "name": "selectionMap",
               "privacy": "private",
-              "default": "new Map< Poi, { originLayer: ObcPoiLayer; previousAnimatePosition: boolean; keepInSelectedLayer: boolean; } >()"
+              "default": "new Map<Poi, SelectionRecord>()"
+            },
+            {
+              "kind": "field",
+              "name": "displacedTargets",
+              "privacy": "private",
+              "default": "new Map<Poi, SelectionRecord>()",
+              "description": "Deselected targets that live in one layer but render in another (targets\nauthored inside the selected layer whose logical origin is a different\nlayer). Their projections are refreshed on every placement pass so layer\nresizes do not leave stale pixel offsets."
             },
             {
               "kind": "field",
@@ -5490,6 +5673,112 @@
                 }
               ]
             },
+            {
+              "kind": "field",
+              "name": "selectedTargets",
+              "type": {
+                "text": "Poi[]"
+              },
+              "description": "Currently selected POI targets.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "selectTarget",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "Poi"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "{selectionId?: string}"
+                  }
+                }
+              ],
+              "description": "Programmatically select a target, following the same flow as a user\nclick. `options.selectionId` presets the badge id shown in the\nstack-managed header; without it the id auto-increments. Returns\n`false` when selection is disabled, the target is mid-transition or\nalready selected, or no layer can host the selection."
+            },
+            {
+              "kind": "method",
+              "name": "deselectTarget",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "Poi"
+                  }
+                }
+              ],
+              "description": "Programmatically deselect a target. Returns `false` when it is not\nselected."
+            },
+            {
+              "kind": "method",
+              "name": "clearSelection",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Deselect all targets."
+            },
+            {
+              "kind": "method",
+              "name": "performSelection",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "Poi"
+                  }
+                },
+                {
+                  "name": "selectionId",
+                  "optional": true,
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "dispatchSelectionChange",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "added",
+                  "type": {
+                    "text": "Poi | null"
+                  }
+                },
+                {
+                  "name": "removed",
+                  "type": {
+                    "text": "Poi | null"
+                  }
+                }
+              ]
+            },
             {
               "kind": "method",
               "name": "getPoiTargetFromEvent",
@@ -5739,7 +6028,7 @@
             },
             {
               "kind": "method",
-              "name": "getTargetButtonProjectionOffset",
+              "name": "getInlineVarPx",
               "privacy": "private",
               "return": {
                 "type": {
@@ -5752,12 +6041,18 @@
                   "type": {
                     "text": "Poi"
                   }
+                },
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string"
+                  }
                 }
               ]
             },
             {
               "kind": "method",
-              "name": "getLayerProjectionOffset",
+              "name": "layerBottomDelta",
               "privacy": "private",
               "return": {
                 "type": {
@@ -5766,94 +6061,84 @@
               },
               "parameters": [
                 {
-                  "name": "originLayer",
+                  "name": "from",
                   "type": {
                     "text": "ObcPoiLayer"
                   }
                 },
                 {
-                  "name": "destinationLayer",
+                  "name": "to",
                   "type": {
-                    "text": "ObcPoiLayer | null"
+                    "text": "ObcPoiLayer"
                   }
                 }
-              ]
+              ],
+              "description": "Pixel delta between two layers' bottom edges (`to.bottom - from.bottom`)."
             },
             {
               "kind": "method",
-              "name": "getTargetProjectionOffset",
+              "name": "setProjectionVar",
               "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "number"
-                }
-              },
               "parameters": [
                 {
-                  "name": "originLayer",
+                  "name": "target",
                   "type": {
-                    "text": "ObcPoiLayer"
+                    "text": "Poi"
                   }
                 },
                 {
-                  "name": "selectedLayer",
+                  "name": "name",
                   "type": {
-                    "text": "ObcPoiLayer | null"
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "valuePx",
+                  "type": {
+                    "text": "number"
                   }
                 }
               ]
             },
             {
               "kind": "method",
-              "name": "detachTargetFromCurrentGroup",
+              "name": "applyTargetProjection",
               "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "ObcPoiLayer | null"
-                }
-              },
               "parameters": [
                 {
                   "name": "target",
                   "type": {
                     "text": "Poi"
                   }
-                }
-              ]
-            },
-            {
-              "kind": "method",
-              "name": "applySelectedTargetProjectionState",
-              "privacy": "private",
-              "parameters": [
+                },
                 {
-                  "name": "target",
+                  "name": "buttonOffsetPx",
                   "type": {
-                    "text": "Poi"
+                    "text": "number"
                   }
-                }
-              ]
-            },
-            {
-              "kind": "method",
-              "name": "clearTargetProjectionStyles",
-              "privacy": "private",
-              "parameters": [
+                },
                 {
-                  "name": "target",
+                  "name": "targetOffsetPx",
                   "type": {
-                    "text": "Poi"
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "animate",
+                  "type": {
+                    "text": "boolean"
                   }
                 }
-              ]
+              ],
+              "description": "Render the target at the given projection offsets without touching its\nDOM position. When `animate` is set and an offset actually changes, the\njump is FLIP-animated via the Web Animations API."
             },
             {
               "kind": "method",
-              "name": "getAnimationElements",
+              "name": "getContainingGroup",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "{\n    button: HTMLElement | null;\n    line: HTMLElement | null;\n  }"
+                  "text": "ObcPoiGroup | null"
                 }
               },
               "parameters": [
@@ -5864,15 +6149,15 @@
                   }
                 }
               ],
-              "description": "Find the button and line elements inside the POI's shadow DOM."
+              "description": "The group a target currently belongs to — a light-DOM parent for\nconsumer-managed groups, or the shadow group whose member slot the\ntarget is assigned to for layer-created auto groups."
             },
             {
               "kind": "method",
-              "name": "animateLayerJump",
+              "name": "detachTargetFromCurrentGroup",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "Promise<void>"
+                  "text": "ObcPoiLayer | null"
                 }
               },
               "parameters": [
@@ -5881,25 +6166,12 @@
                   "type": {
                     "text": "Poi"
                   }
-                },
-                {
-                  "name": "beforeButtonRect",
-                  "type": {
-                    "text": "DOMRect | null"
-                  }
-                },
-                {
-                  "name": "beforeLineRect",
-                  "type": {
-                    "text": "DOMRect | null"
-                  }
                 }
-              ],
-              "description": "Animate a layer jump using Web Animations API.\nfill:'forwards' overrides ALL CSS/Lit styles during animation.\nAfter cancel(), Lit's final-state styles take over."
+              ]
             },
             {
               "kind": "method",
-              "name": "moveTargetIntoSelectedLayer",
+              "name": "applySelectedTargetProjectionState",
               "privacy": "private",
               "parameters": [
                 {
@@ -5907,28 +6179,12 @@
                   "type": {
                     "text": "Poi"
                   }
-                },
-                {
-                  "name": "_originLayer",
-                  "type": {
-                    "text": "ObcPoiLayer"
-                  }
-                },
-                {
-                  "name": "selectedLayer",
-                  "type": {
-                    "text": "ObcPoiLayer"
-                  }
-                },
-                {
-                  "name": "animate",
-                  "default": "true"
                 }
               ]
             },
             {
               "kind": "method",
-              "name": "moveTrackedTargetToSelectedLayer",
+              "name": "clearTargetProjectionStyles",
               "privacy": "private",
               "parameters": [
                 {
@@ -5936,60 +6192,37 @@
                   "type": {
                     "text": "Poi"
                   }
-                },
-                {
-                  "name": "record",
-                  "type": {
-                    "text": "{\n      originLayer: ObcPoiLayer;\n      previousAnimatePosition: boolean;\n      keepInSelectedLayer: boolean;\n    }"
-                  }
-                },
-                {
-                  "name": "selectedLayer",
-                  "type": {
-                    "text": "ObcPoiLayer"
-                  }
-                },
-                {
-                  "name": "animateProjection",
-                  "type": {
-                    "text": "boolean"
-                  }
                 }
               ]
             },
             {
               "kind": "method",
-              "name": "syncTargetProjection",
+              "name": "getAnimationElements",
               "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{\n    button: HTMLElement | null;\n    line: HTMLElement | null;\n  }"
+                }
+              },
               "parameters": [
                 {
                   "name": "target",
                   "type": {
                     "text": "Poi"
                   }
-                },
-                {
-                  "name": "originLayer",
-                  "type": {
-                    "text": "ObcPoiLayer"
-                  }
-                },
-                {
-                  "name": "selectedLayer",
-                  "type": {
-                    "text": "ObcPoiLayer | null"
-                  }
-                },
-                {
-                  "name": "animate",
-                  "default": "true"
                 }
-              ]
+              ],
+              "description": "Find the button and line elements inside the POI's shadow DOM."
             },
             {
               "kind": "method",
-              "name": "animateTargetReturnToOrigin",
+              "name": "animateLayerJump",
               "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<void>"
+                }
+              },
               "parameters": [
                 {
                   "name": "target",
@@ -5998,16 +6231,23 @@
                   }
                 },
                 {
-                  "name": "record",
+                  "name": "beforeButtonRect",
+                  "type": {
+                    "text": "DOMRect | null"
+                  }
+                },
+                {
+                  "name": "beforeLineRect",
                   "type": {
-                    "text": "{\n      originLayer: ObcPoiLayer;\n      previousAnimatePosition: boolean;\n      keepInSelectedLayer: boolean;\n    }"
+                    "text": "DOMRect | null"
                   }
                 }
-              ]
+              ],
+              "description": "Animate a layer jump using Web Animations API.\nfill:'forwards' overrides ALL CSS/Lit styles during animation.\nAfter cancel(), Lit's final-state styles take over."
             },
             {
               "kind": "method",
-              "name": "setSelectedTargetInteractivity",
+              "name": "animateTargetReturnToOrigin",
               "privacy": "private",
               "parameters": [
                 {
@@ -6017,16 +6257,16 @@
                   }
                 },
                 {
-                  "name": "selected",
+                  "name": "record",
                   "type": {
-                    "text": "boolean"
+                    "text": "SelectionRecord"
                   }
                 }
               ]
             },
             {
               "kind": "method",
-              "name": "trackSelectionTarget",
+              "name": "setSelectedTargetInteractivity",
               "privacy": "private",
               "parameters": [
                 {
@@ -6036,14 +6276,10 @@
                   }
                 },
                 {
-                  "name": "originLayer",
+                  "name": "selected",
                   "type": {
-                    "text": "ObcPoiLayer"
+                    "text": "boolean"
                   }
-                },
-                {
-                  "name": "keepInSelectedLayer",
-                  "default": "true"
                 }
               ]
             },
@@ -6061,7 +6297,7 @@
                 {
                   "name": "record",
                   "type": {
-                    "text": "{\n      originLayer: ObcPoiLayer;\n      previousAnimatePosition: boolean;\n      keepInSelectedLayer: boolean;\n    }"
+                    "text": "SelectionRecord"
                   }
                 },
                 {
@@ -6109,7 +6345,7 @@
                   "name": "record",
                   "optional": true,
                   "type": {
-                    "text": "{\n      originLayer: ObcPoiLayer;\n      previousAnimatePosition: boolean;\n      keepInSelectedLayer: boolean;\n    }"
+                    "text": "SelectionRecord"
                   }
                 }
               ]
@@ -6159,6 +6395,21 @@
               "kind": "method",
               "name": "syncSelectedLayerTargets",
               "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "refreshDisplacedTargets",
+              "privacy": "private",
+              "description": "Keep deselected targets that render outside their DOM layer (targets\nauthored in the selected layer whose logical origin is another layer)\nprojected at up-to-date offsets across layer resizes."
+            }
+          ],
+          "events": [
+            {
+              "name": "selection-change",
+              "type": {
+                "text": "CustomEvent<{selected: Poi[]; added: Poi | null; removed: Poi | null}>"
+              },
+              "description": "Fired whenever the selection set changes (user click, programmatic call, or bootstrap seeding). Bubbles and is composed."
             }
           ],
           "attributes": [
@@ -6203,7 +6454,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<obc-poi-layer>` - A POI layout container that resolves overlapping targets by grouping or crossing strategies.\n\nThis component watches slotted POI targets, applies overlap state/visual rules, and coordinates automatic `obc-poi-group` creation when needed.\nUse it as the main layer container when you want centralized overlap behavior plus layer height updates for parent layout systems.\n\n### Features\n- Overlap strategies: `overlapMode=\"grouping\"` builds overlap clusters; `overlapMode=\"crossing\"` continuously adjusts horizontal offsets to reduce crossings.\n- Auto-group lifecycle: Creates/removes auto groups and preserves front/behind/pre-group states during transitions.\n- Manual group support: Respects existing `obc-poi-group` elements and can optionally join nearby targets while a group is expanded (`joinWhileExpanded`).\n- Dynamic observation: Reacts to slot changes, target style/position mutations, and target size changes to recompute grouping and layer height.\n- Layer diagnostics: `debug` shows a label overlay using `label`.\n- Selection flag: `isSelected` reflects to attribute but has no direct runtime layout logic in this class.\n- Group ordering option: `internalSwapping` is forwarded to groups to allow expanded ordering updates based on movement.\n\n### Usage Guidelines\n- Place `obc-poi-data` targets (and optional `obc-poi-group`) in the default slot.\n- Choose `overlapMode` based on behavior:\n  - `grouping`: best when overlaps should collapse into expandable clusters.\n  - `crossing`: best when targets stay independent but should separate horizontally.\n- Listen for `layer-resize` to keep parent containers in sync with computed layer height.\n- Enable `joinWhileExpanded` only when targets should be able to join an already expanded auto-group.\n- **TODO(designer):** Confirm intended user-visible behavior for `isSelected`, since it currently reflects an attribute but is not consumed by the layer logic here.\n\n### Slots\n| Slot | Renders When... | Purpose |\n| --- | --- | --- |\n| default | Always | Hosts POI targets (`obc-poi-data*`) and optional manual `obc-poi-group` elements. |\n\n### Events\n- `layer-resize` - Fired when computed layer height changes. Detail: `{ height: number, label: string }`.\n\n### Best Practices\n- Keep POI targets as direct descendants when possible to reduce grouping ambiguity.\n- Use stable `x`/`y` updates for animated scenarios so grouping and crossing calculations remain predictable.\n- Avoid adding non-POI interactive wrappers inside the layer unless needed, as layer observers track POI-related descendants.\n\n### Example\n```html\n<obc-poi-layer label=\"Targets\" overlapMode=\"grouping\" debug>\n  <obc-poi-data x=\"180\" y=\"110\"></obc-poi-data>\n  <obc-poi-data x=\"205\" y=\"90\"></obc-poi-data>\n  <obc-poi-data x=\"230\" y=\"100\"></obc-poi-data>\n</obc-poi-layer>\n```",
+          "description": "`<obc-poi-layer>` - A POI layout container that resolves overlapping targets by grouping or crossing strategies.\n\nThis component watches slotted POI targets, applies overlap state/visual rules, and coordinates automatic `obc-poi-group` creation when needed.\nUse it as the main layer container when you want centralized overlap behavior plus layer height updates for parent layout systems.\n\n### Features\n- Overlap strategies: `overlapMode=\"grouping\"` builds overlap clusters; `overlapMode=\"crossing\"` continuously adjusts horizontal offsets to reduce crossings.\n- Auto-group lifecycle: Creates/removes auto groups as shadow-internal chrome — the consumer's light DOM is never modified; members are placed via manual slot assignment. Reach the group elements through the `autoGroups` accessor.\n- Manual group support: Respects existing `obc-poi-group` elements and can optionally join nearby targets while a group is expanded (`joinWhileExpanded`).\n- Dynamic observation: Reacts to slot changes, target style/position mutations, and target size changes to recompute grouping and layer height.\n- Layer diagnostics: `debug` shows a label overlay using `label`.\n- Selection flag: `isSelected` reflects to attribute but has no direct runtime layout logic in this class.\n- Group ordering option: `internalSwapping` is forwarded to groups to allow expanded ordering updates based on movement.\n\n### Usage Guidelines\n- Place `obc-poi-data` targets (and optional `obc-poi-group`) in the default slot.\n- Choose `overlapMode` based on behavior:\n  - `grouping`: best when overlaps should collapse into expandable clusters.\n  - `crossing`: best when targets stay independent but should separate horizontally.\n- Handle `layer-resize` only when using the layer standalone; inside `obc-poi-layer-stack` / `obc-poi-controller` the container handles height syncing. Example: `layer.addEventListener('layer-resize', (e) => { host.style.height = e.detail.height + 'px'; })`.\n- After imperatively adding, removing, or moving POI children outside the layer's own observers, call the public `requestGroupingUpdate()` method to force a recompute; it is the supported hook for imperative DOM mutations.\n- Set `--obc-poi-layer-min-height` when the layer starts empty, otherwise the layer collapses to 0px height until targets exist.\n- Enable `joinWhileExpanded` only when targets should be able to join an already expanded auto-group.\n- **TODO(designer):** Confirm intended user-visible behavior for `isSelected`, since it has no runtime layout logic in this class — it only reflects the attribute and notifies containers via `layer-selection-changed` (consumed by `obc-poi-layer-stack` to pick the selected layer).\n\n### Slots\n| Slot | Renders When... | Purpose |\n| --- | --- | --- |\n| default | Always | Hosts POI targets (`obc-poi-data*`) and optional manual `obc-poi-group` elements. |\n\n### Events\n- `layer-resize` - Fired when computed layer height changes. Detail: `{ height: number, label: string }`.\n- `grouping-change` - Fired when grouping membership or front/behind/pre-group state changes. Detail: `{ clusters: Poi[][], front: Poi[], behind: Poi[], pregrouped: Poi[] }`. Subscribe to this instead of observing the layer's internal `data-*` attributes.\n\n### CSS Custom Properties\n| Property | Default | Purpose |\n| --- | --- | --- |\n| `--obc-poi-layer-overlap-enter` | `10px` | Max horizontal gap at which ungrouped targets start grouping. |\n| `--obc-poi-layer-overlap-exit` | `18px` | Gap at which grouped targets leave their group. Clamped to at least the enter threshold; keep it larger than enter so jittery positions do not oscillate in and out of groups. |\n| `--obc-poi-layer-overlap-pre` | `16px` | Gap at which targets get the pre-grouped visual state. |\n| `--obc-poi-layer-overlap-behind` | `10px` | Gap at which the shortest target gets the behind visual state. |\n| `--obc-poi-layer-exit-delay-ms` | `140` | Delay before exiting targets lose their exit visual state. |\n| `--obc-poi-layer-group-removal-delay-ms` | `250` | Delay before a dissolved auto-group element is removed. |\n| `--obc-poi-layer-exit-lock-duration-ms` | `500` | Duration a target is locked out of pre-group/behind states after leaving a group. |\n\n### Best Practices\n- Keep POI targets as direct descendants when possible to reduce grouping ambiguity.\n- Targets may update `x`/`y` every animation frame; grouping stays stable as long as the horizontal gap between targets does not oscillate across the enter/exit band faster than the group lifecycle delays (~0.5s). Smooth noisy input coordinates or widen the enter/exit band to compensate.\n- Avoid adding non-POI interactive wrappers inside the layer unless needed, as layer observers track POI-related descendants.\n\n### Example\n```html\n<obc-poi-layer label=\"Targets\" overlapMode=\"grouping\" debug>\n  <obc-poi-data x=\"180\" y=\"110\"></obc-poi-data>\n  <obc-poi-data x=\"205\" y=\"90\"></obc-poi-data>\n  <obc-poi-data x=\"230\" y=\"100\"></obc-poi-data>\n</obc-poi-layer>\n```",
           "name": "ObcPoiLayer",
           "slots": [
             {
@@ -6212,6 +6463,16 @@
             }
           ],
           "members": [
+            {
+              "kind": "field",
+              "name": "shadowRootOptions",
+              "type": {
+                "text": "ShadowRootInit"
+              },
+              "static": true,
+              "default": "{ ...LitElement.shadowRootOptions, slotAssignment: 'manual', }",
+              "description": "Manual slot assignment lets the layer place consumer-owned targets into\nshadow-internal auto-group chrome (and back) without ever re-parenting\nthem: grouping only changes which internal slot a target is assigned to."
+            },
             {
               "kind": "field",
               "name": "label",
@@ -6307,6 +6568,30 @@
               "privacy": "private",
               "default": "false"
             },
+            {
+              "kind": "field",
+              "name": "lastGroupingSignature",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "''"
+            },
+            {
+              "kind": "field",
+              "name": "groupingIds",
+              "privacy": "private",
+              "default": "new WeakMap<Poi, number>()"
+            },
+            {
+              "kind": "field",
+              "name": "nextGroupingId",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "1"
+            },
             {
               "kind": "field",
               "name": "targetObservers",
@@ -6594,90 +6879,236 @@
             },
             {
               "kind": "method",
-              "name": "scheduleGrouping",
-              "privacy": "private"
+              "name": "getMainSlot",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HTMLSlotElement | null"
+                }
+              }
             },
             {
               "kind": "method",
-              "name": "scheduleCrossingMode",
-              "privacy": "private"
+              "name": "syncSlotAssignments",
+              "privacy": "private",
+              "description": "Assign every light-DOM child that is not currently placed in an\nauto-group member slot to the main slot. With `slotAssignment: 'manual'`\nnothing renders unless explicitly assigned, so this runs after render,\non child-list mutations, and after every grouping change."
+            },
+            {
+              "kind": "field",
+              "name": "autoGroups",
+              "type": {
+                "text": "HTMLElement[]"
+              },
+              "privacy": "public",
+              "description": "The auto-created `obc-poi-group` elements currently managed by this\nlayer. Auto groups are shadow-internal chrome (they never appear in the\nconsumer's light DOM); use this accessor — typically after a\n`grouping-change` event — to reach them, e.g. to expand a group\nprogrammatically.",
+              "readonly": true
             },
             {
               "kind": "method",
-              "name": "updateCrossingMode",
+              "name": "getAutoGroups",
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "boolean"
+                  "text": "PoiButtonGroupElement[]"
                 }
               }
             },
             {
               "kind": "method",
-              "name": "toggleGroupLayerHook",
+              "name": "getAutoGroupMemberSlot",
               "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HTMLSlotElement | null"
+                }
+              },
               "parameters": [
                 {
                   "name": "group",
                   "type": {
                     "text": "HTMLElement"
                   }
-                },
-                {
-                  "name": "hasTargets",
-                  "type": {
-                    "text": "boolean"
-                  }
                 }
               ]
             },
             {
               "kind": "method",
-              "name": "updateGrouping",
-              "privacy": "private"
-            },
-            {
-              "kind": "method",
-              "name": "tryJoinExpandedGroup",
+              "name": "getAutoGroupOf",
               "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HTMLElement | null"
+                }
+              },
               "parameters": [
                 {
-                  "name": "group",
-                  "type": {
-                    "text": "PoiButtonGroupElement"
-                  }
-                },
-                {
-                  "name": "targets",
-                  "type": {
-                    "text": "Poi[]"
-                  }
-                },
-                {
-                  "name": "rects",
-                  "type": {
-                    "text": "Map<Poi, DOMRect>"
-                  }
-                },
-                {
-                  "name": "enterThreshold",
+                  "name": "target",
                   "type": {
-                    "text": "number"
+                    "text": "Poi"
                   }
                 }
-              ]
+              ],
+              "description": "The auto group a target is currently assigned into, if any."
             },
             {
               "kind": "method",
-              "name": "applyStandaloneVisualState",
+              "name": "getGroupMembers",
               "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Poi[]"
+                }
+              },
               "parameters": [
                 {
-                  "name": "target",
+                  "name": "group",
                   "type": {
-                    "text": "Poi"
+                    "text": "ParentNode"
                   }
-                },
+                }
+              ],
+              "description": "Members of a group in either mode: slot-assigned (shadow auto groups) or\nlight-DOM children (consumer-managed manual groups)."
+            },
+            {
+              "kind": "method",
+              "name": "scheduleGrouping",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "scheduleCrossingMode",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "updateCrossingMode",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getGroupingId",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "Poi"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "notifyGroupingChange",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "clusters",
+                  "type": {
+                    "text": "Poi[][]"
+                  }
+                },
+                {
+                  "name": "frontTargets",
+                  "type": {
+                    "text": "Set<Poi>"
+                  }
+                },
+                {
+                  "name": "behindTargets",
+                  "type": {
+                    "text": "Set<Poi>"
+                  }
+                },
+                {
+                  "name": "preGrouped",
+                  "type": {
+                    "text": "Set<Poi>"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "toggleGroupLayerHook",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "group",
+                  "type": {
+                    "text": "HTMLElement"
+                  }
+                },
+                {
+                  "name": "hasTargets",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "updateGrouping",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "tryJoinExpandedGroup",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Poi | null"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "group",
+                  "type": {
+                    "text": "PoiButtonGroupElement"
+                  }
+                },
+                {
+                  "name": "targets",
+                  "type": {
+                    "text": "Poi[]"
+                  }
+                },
+                {
+                  "name": "rects",
+                  "type": {
+                    "text": "Map<Poi, DOMRect>"
+                  }
+                },
+                {
+                  "name": "enterThreshold",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "applyStandaloneVisualState",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "Poi"
+                  }
+                },
                 {
                   "name": "overlap",
                   "type": {
@@ -6978,6 +7409,13 @@
               },
               "description": "Fired when the layer height changes."
             },
+            {
+              "name": "grouping-change",
+              "type": {
+                "text": "CustomEvent<{clusters:Poi[][],front:Poi[],behind:Poi[],pregrouped:Poi[]}>"
+              },
+              "description": "Fired when grouping membership or overlap state changes. Bubbles and is composed."
+            },
             {
               "name": "layer-selection-changed",
               "type": {
@@ -7831,13 +8269,163 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/ar/poi-projection/poi-projection.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "computeMediaProjection",
+          "return": {
+            "type": {
+              "text": "MediaProjection | null"
+            }
+          },
+          "parameters": [
+            {
+              "name": "input",
+              "type": {
+                "text": "MediaProjectionInput"
+              }
+            }
+          ],
+          "description": "Compute the projection for the given dimensions, or `null` when any\ndimension is non-finite or zero (media not measured yet)."
+        },
+        {
+          "kind": "function",
+          "name": "projectPoint",
+          "return": {
+            "type": {
+              "text": "{x: number; y: number}"
+            }
+          },
+          "parameters": [
+            {
+              "name": "projection",
+              "type": {
+                "text": "MediaProjection"
+              }
+            },
+            {
+              "name": "x",
+              "type": {
+                "text": "number"
+              }
+            },
+            {
+              "name": "y",
+              "type": {
+                "text": "number"
+              }
+            }
+          ],
+          "description": "Project a point from media pixel space into rendered space."
+        },
+        {
+          "kind": "function",
+          "name": "projectPointToLayer",
+          "return": {
+            "type": {
+              "text": "{x: number; y: number}"
+            }
+          },
+          "parameters": [
+            {
+              "name": "projection",
+              "type": {
+                "text": "MediaProjection"
+              }
+            },
+            {
+              "name": "x",
+              "type": {
+                "text": "number"
+              }
+            },
+            {
+              "name": "y",
+              "type": {
+                "text": "number"
+              }
+            },
+            {
+              "name": "layerBottom",
+              "type": {
+                "text": "number"
+              }
+            }
+          ],
+          "description": "Project a media-space anchor point into `obc-poi-data` layer\ncoordinates.\n\n`layerBottom` is the POI layer's bottom edge measured in the same\nrendered coordinate space as the projection container (e.g.\n`layerRect.bottom - containerRect.top`). The returned `y` is the\nconnector line length extending downward from the layer to the\ntarget point, clamped to `0` (matches how `obc-poi-controller`\npositions its detection targets)."
+        },
+        {
+          "kind": "function",
+          "name": "projectBoxSize",
+          "return": {
+            "type": {
+              "text": "number | null"
+            }
+          },
+          "parameters": [
+            {
+              "name": "projection",
+              "type": {
+                "text": "MediaProjection"
+              }
+            },
+            {
+              "name": "size",
+              "type": {
+                "text": "number | null | undefined"
+              }
+            }
+          ],
+          "description": "Scale a media-space box dimension into rendered px, or `null`."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "computeMediaProjection",
+          "declaration": {
+            "name": "computeMediaProjection",
+            "module": "src/ar/poi-projection/poi-projection.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "projectPoint",
+          "declaration": {
+            "name": "projectPoint",
+            "module": "src/ar/poi-projection/poi-projection.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "projectPointToLayer",
+          "declaration": {
+            "name": "projectPointToLayer",
+            "module": "src/ar/poi-projection/poi-projection.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "projectBoxSize",
+          "declaration": {
+            "name": "projectBoxSize",
+            "module": "src/ar/poi-projection/poi-projection.ts"
+          }
+        }
+      ],
+      "summary": "POI Projection",
+      "description": "Media-projection helpers for POI overlays.\n\nMaps points from media pixel space (video/image natural resolution) to\nrendered screen space, accounting for `cover`/`contain` letterboxing.\nThis is the same math `obc-poi-controller` applies to its\ndetections-driven targets, exported as pure functions so applications\nthat manage their own POI elements can project coordinates without\nre-implementing the transform.\n\n### Usage Guidelines\n- Build a {@link MediaProjection} once per resize/metadata change via\n  {@link computeMediaProjection}; reuse it for every point in a frame.\n- `renderWidth`/`renderHeight` come from the media element's\n  `getBoundingClientRect()`; `mediaWidth`/`mediaHeight` from\n  `videoWidth`/`videoHeight` (video) or `naturalWidth`/`naturalHeight`\n  (image).\n- {@link projectPointToLayer} additionally converts a projected\n  point into `obc-poi-data` layer coordinates (`x` center px,\n  `y` line length from the layer's bottom anchor), given the layer's\n  bottom offset inside the projection container.\n\n### Fit modes\n- `cover`: media fills the container; overflow is cropped.\n- `contain`: media letterboxes inside the container.\n\nThe Storybook demo draws the rendered container (outer box), the scaled\nmedia content region (shaded), and a marker at the projected point."
+    },
     {
       "kind": "javascript-module",
       "path": "src/ar/poi/poi-aton.ts",
       "declarations": [
         {
           "kind": "class",
-          "description": "`<obc-poi-aton>` - AtoN marker variant with layout positioning and layer integration.\n\nExtends `PoiBase` to provide the \"aton\" variant of the POI system.\nRenders `<obc-poi>` with a slotted `<obc-poi-button-aton>`.",
+          "description": "`<obc-poi-aton>` - AtoN marker variant with layout positioning and layer integration.\n\nExtends `PoiBase` to provide the \"aton\" variant of the POI system.\nRenders `<obc-poi>` with a slotted `<obc-poi-button-aton>`.\nSee the \"Coordinate Model\" section in `PoiBase` (poi-base.ts) for how `x`, `y`, and `buttonY` position the marker.",
           "name": "ObcPoiAton",
           "slots": [
             {
@@ -8129,10 +8717,7 @@
             {
               "kind": "field",
               "name": "y",
-              "type": {
-                "text": "number"
-              },
-              "default": "192",
+              "default": "DEFAULT_LINE_LENGTH_PX",
               "attribute": "y",
               "inheritedFrom": {
                 "name": "PoiBase",
@@ -8152,6 +8737,34 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "xFilterCutoffHz",
+              "default": "16",
+              "description": "Cutoff frequency (Hz) of the built-in low-pass filter applied to `x`. Lower values smooth noisy input more aggressively; `0` or a negative value disables filtering so `x` is applied directly.",
+              "attribute": "x-filter-cutoff-hz",
+              "type": {
+                "text": "number"
+              },
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "yFilterCutoffHz",
+              "default": "16",
+              "description": "Cutoff frequency (Hz) of the built-in low-pass filter applied to `y`. Lower values smooth noisy input more aggressively; `0` or a negative value disables filtering so `y` is applied directly.",
+              "attribute": "y-filter-cutoff-hz",
+              "type": {
+                "text": "number"
+              },
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "fixedTarget",
@@ -8319,6 +8932,97 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "resolvedXFilterCutoffHz",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "filteredY",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "yFilterTarget",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "yFilterInitialized",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "lastYFilterTimestampMs",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "yFilterRaf",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "resolvedYFilterCutoffHz",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "dispatchLayoutChange",
@@ -8329,8 +9033,43 @@
               }
             },
             {
-              "kind": "field",
-              "name": "stepXFilter",
+              "kind": "field",
+              "name": "stepXFilter",
+              "privacy": "private",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "syncXFilterTarget",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "nextX",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "stepYFilter",
+              "privacy": "private",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "applyFilteredY",
               "privacy": "private",
               "inheritedFrom": {
                 "name": "PoiBase",
@@ -8339,11 +9078,11 @@
             },
             {
               "kind": "method",
-              "name": "syncXFilterTarget",
+              "name": "syncYFilterTarget",
               "privacy": "private",
               "parameters": [
                 {
-                  "name": "nextX",
+                  "name": "nextY",
                   "type": {
                     "text": "number"
                   }
@@ -8565,7 +9304,7 @@
                 "text": "number"
               },
               "privacy": "protected",
-              "description": "Public `y` normalized as the target Y input.",
+              "description": "Public `y` normalized as the target Y input, after the y filter.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "PoiBase",
@@ -8600,49 +9339,11 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
-            {
-              "kind": "field",
-              "name": "resolvedHeaderState",
-              "type": {
-                "text": "ObcPoiHeaderState"
-              },
-              "privacy": "protected",
-              "readonly": true,
-              "inheritedFrom": {
-                "name": "PoiBase",
-                "module": "src/ar/poi/poi-base.ts"
-              }
-            },
             {
               "kind": "method",
               "name": "syncHeaderContent",
               "privacy": "private",
-              "inheritedFrom": {
-                "name": "PoiBase",
-                "module": "src/ar/poi/poi-base.ts"
-              }
-            },
-            {
-              "kind": "method",
-              "name": "applyHeaderState",
-              "privacy": "private",
-              "parameters": [
-                {
-                  "name": "root",
-                  "type": {
-                    "text": "ParentNode"
-                  }
-                }
-              ],
-              "inheritedFrom": {
-                "name": "PoiBase",
-                "module": "src/ar/poi/poi-base.ts"
-              }
-            },
-            {
-              "kind": "method",
-              "name": "syncHeaderState",
-              "privacy": "private",
+              "description": "Auto-enable `hasHeader` when the consumer slots header content directly\n(outside a stack, which manages `hasHeader` itself). Header elements stay\nin the consumer's light DOM and reach the inner button through the\n`<slot name=\"header\">` forwarding chain; their `state` is synced by\n`obc-poi-button`.",
               "inheritedFrom": {
                 "name": "PoiBase",
                 "module": "src/ar/poi/poi-base.ts"
@@ -8844,10 +9545,7 @@
             },
             {
               "name": "y",
-              "type": {
-                "text": "number"
-              },
-              "default": "192",
+              "default": "DEFAULT_LINE_LENGTH_PX",
               "fieldName": "y",
               "inheritedFrom": {
                 "name": "PoiBase",
@@ -8866,6 +9564,26 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
+            {
+              "name": "x-filter-cutoff-hz",
+              "default": "X_FILTER_CUTOFF_HZ",
+              "description": "Cutoff frequency (Hz) of the built-in low-pass filter applied to `x`. Lower values smooth noisy input more aggressively; `0` or a negative value disables filtering so `x` is applied directly.",
+              "fieldName": "xFilterCutoffHz",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "name": "y-filter-cutoff-hz",
+              "default": "Y_FILTER_CUTOFF_HZ",
+              "description": "Cutoff frequency (Hz) of the built-in low-pass filter applied to `y`. Lower values smooth noisy input more aggressively; `0` or a negative value disables filtering so `y` is applied directly.",
+              "fieldName": "yFilterCutoffHz",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
             {
               "name": "fixed-target",
               "type": {
@@ -9006,7 +9724,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<obc-poi-data>` - Data-oriented marker variant with layout positioning and layer integration.\n\nExtends `PoiBase` to provide the \"data\" variant of the POI system.\nRenders `<obc-poi>` with a slotted `<obc-poi-button-data>`.",
+          "description": "`<obc-poi-data>` - Data-oriented marker variant with layout positioning and layer integration.\n\nExtends `PoiBase` to provide the \"data\" variant of the POI system.\nRenders `<obc-poi>` with a slotted `<obc-poi-button-data>`.\nSee the \"Coordinate Model\" section in `PoiBase` (poi-base.ts) for how `x`, `y`, and `buttonY` position the marker.",
           "name": "ObcPoiData",
           "slots": [
             {
@@ -9290,10 +10008,7 @@
             {
               "kind": "field",
               "name": "y",
-              "type": {
-                "text": "number"
-              },
-              "default": "192",
+              "default": "DEFAULT_LINE_LENGTH_PX",
               "attribute": "y",
               "inheritedFrom": {
                 "name": "PoiBase",
@@ -9313,6 +10028,34 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "xFilterCutoffHz",
+              "default": "16",
+              "description": "Cutoff frequency (Hz) of the built-in low-pass filter applied to `x`. Lower values smooth noisy input more aggressively; `0` or a negative value disables filtering so `x` is applied directly.",
+              "attribute": "x-filter-cutoff-hz",
+              "type": {
+                "text": "number"
+              },
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "yFilterCutoffHz",
+              "default": "16",
+              "description": "Cutoff frequency (Hz) of the built-in low-pass filter applied to `y`. Lower values smooth noisy input more aggressively; `0` or a negative value disables filtering so `y` is applied directly.",
+              "attribute": "y-filter-cutoff-hz",
+              "type": {
+                "text": "number"
+              },
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "fixedTarget",
@@ -9480,6 +10223,97 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "resolvedXFilterCutoffHz",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "filteredY",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "yFilterTarget",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "yFilterInitialized",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "lastYFilterTimestampMs",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "yFilterRaf",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "resolvedYFilterCutoffHz",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "dispatchLayoutChange",
@@ -9515,6 +10349,41 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "stepYFilter",
+              "privacy": "private",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "applyFilteredY",
+              "privacy": "private",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "syncYFilterTarget",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "nextY",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "markXMoving",
@@ -9726,7 +10595,7 @@
                 "text": "number"
               },
               "privacy": "protected",
-              "description": "Public `y` normalized as the target Y input.",
+              "description": "Public `y` normalized as the target Y input, after the y filter.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "PoiBase",
@@ -9761,49 +10630,11 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
-            {
-              "kind": "field",
-              "name": "resolvedHeaderState",
-              "type": {
-                "text": "ObcPoiHeaderState"
-              },
-              "privacy": "protected",
-              "readonly": true,
-              "inheritedFrom": {
-                "name": "PoiBase",
-                "module": "src/ar/poi/poi-base.ts"
-              }
-            },
             {
               "kind": "method",
               "name": "syncHeaderContent",
               "privacy": "private",
-              "inheritedFrom": {
-                "name": "PoiBase",
-                "module": "src/ar/poi/poi-base.ts"
-              }
-            },
-            {
-              "kind": "method",
-              "name": "applyHeaderState",
-              "privacy": "private",
-              "parameters": [
-                {
-                  "name": "root",
-                  "type": {
-                    "text": "ParentNode"
-                  }
-                }
-              ],
-              "inheritedFrom": {
-                "name": "PoiBase",
-                "module": "src/ar/poi/poi-base.ts"
-              }
-            },
-            {
-              "kind": "method",
-              "name": "syncHeaderState",
-              "privacy": "private",
+              "description": "Auto-enable `hasHeader` when the consumer slots header content directly\n(outside a stack, which manages `hasHeader` itself). Header elements stay\nin the consumer's light DOM and reach the inner button through the\n`<slot name=\"header\">` forwarding chain; their `state` is synced by\n`obc-poi-button`.",
               "inheritedFrom": {
                 "name": "PoiBase",
                 "module": "src/ar/poi/poi-base.ts"
@@ -9998,23 +10829,40 @@
             },
             {
               "name": "y",
+              "default": "DEFAULT_LINE_LENGTH_PX",
+              "fieldName": "y",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "name": "button-y",
               "type": {
-                "text": "number"
+                "text": "number | null"
               },
-              "default": "192",
-              "fieldName": "y",
+              "default": "0",
+              "fieldName": "buttonY",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "name": "x-filter-cutoff-hz",
+              "default": "X_FILTER_CUTOFF_HZ",
+              "description": "Cutoff frequency (Hz) of the built-in low-pass filter applied to `x`. Lower values smooth noisy input more aggressively; `0` or a negative value disables filtering so `x` is applied directly.",
+              "fieldName": "xFilterCutoffHz",
               "inheritedFrom": {
                 "name": "PoiBase",
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
             {
-              "name": "button-y",
-              "type": {
-                "text": "number | null"
-              },
-              "default": "0",
-              "fieldName": "buttonY",
+              "name": "y-filter-cutoff-hz",
+              "default": "Y_FILTER_CUTOFF_HZ",
+              "description": "Cutoff frequency (Hz) of the built-in low-pass filter applied to `y`. Lower values smooth noisy input more aggressively; `0` or a negative value disables filtering so `y` is applied directly.",
+              "fieldName": "yFilterCutoffHz",
               "inheritedFrom": {
                 "name": "PoiBase",
                 "module": "src/ar/poi/poi-base.ts"
@@ -10168,7 +11016,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<obc-poi-vessel>` - Vessel marker variant with layout positioning and layer integration.\n\nExtends `PoiBase` to provide the \"vessel\" variant of the POI system.\nRenders `<obc-poi>` with a slotted `<obc-poi-button-vessel>`.",
+          "description": "`<obc-poi-vessel>` - Vessel marker variant with layout positioning and layer integration.\n\nExtends `PoiBase` to provide the \"vessel\" variant of the POI system.\nRenders `<obc-poi>` with a slotted `<obc-poi-button-vessel>`.\nSee the \"Coordinate Model\" section in `PoiBase` (poi-base.ts) for how `x`, `y`, and `buttonY` position the marker.",
           "name": "ObcPoiVessel",
           "slots": [
             {
@@ -10468,10 +11316,7 @@
             {
               "kind": "field",
               "name": "y",
-              "type": {
-                "text": "number"
-              },
-              "default": "192",
+              "default": "DEFAULT_LINE_LENGTH_PX",
               "attribute": "y",
               "inheritedFrom": {
                 "name": "PoiBase",
@@ -10491,6 +11336,34 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "xFilterCutoffHz",
+              "default": "16",
+              "description": "Cutoff frequency (Hz) of the built-in low-pass filter applied to `x`. Lower values smooth noisy input more aggressively; `0` or a negative value disables filtering so `x` is applied directly.",
+              "attribute": "x-filter-cutoff-hz",
+              "type": {
+                "text": "number"
+              },
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "yFilterCutoffHz",
+              "default": "16",
+              "description": "Cutoff frequency (Hz) of the built-in low-pass filter applied to `y`. Lower values smooth noisy input more aggressively; `0` or a negative value disables filtering so `y` is applied directly.",
+              "attribute": "y-filter-cutoff-hz",
+              "type": {
+                "text": "number"
+              },
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "fixedTarget",
@@ -10658,6 +11531,97 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "resolvedXFilterCutoffHz",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "filteredY",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "yFilterTarget",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "yFilterInitialized",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "lastYFilterTimestampMs",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "yFilterRaf",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "resolvedYFilterCutoffHz",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "dispatchLayoutChange",
@@ -10693,6 +11657,41 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "stepYFilter",
+              "privacy": "private",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "applyFilteredY",
+              "privacy": "private",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "syncYFilterTarget",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "nextY",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "markXMoving",
@@ -10904,7 +11903,7 @@
                 "text": "number"
               },
               "privacy": "protected",
-              "description": "Public `y` normalized as the target Y input.",
+              "description": "Public `y` normalized as the target Y input, after the y filter.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "PoiBase",
@@ -10939,49 +11938,11 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
-            {
-              "kind": "field",
-              "name": "resolvedHeaderState",
-              "type": {
-                "text": "ObcPoiHeaderState"
-              },
-              "privacy": "protected",
-              "readonly": true,
-              "inheritedFrom": {
-                "name": "PoiBase",
-                "module": "src/ar/poi/poi-base.ts"
-              }
-            },
             {
               "kind": "method",
               "name": "syncHeaderContent",
               "privacy": "private",
-              "inheritedFrom": {
-                "name": "PoiBase",
-                "module": "src/ar/poi/poi-base.ts"
-              }
-            },
-            {
-              "kind": "method",
-              "name": "applyHeaderState",
-              "privacy": "private",
-              "parameters": [
-                {
-                  "name": "root",
-                  "type": {
-                    "text": "ParentNode"
-                  }
-                }
-              ],
-              "inheritedFrom": {
-                "name": "PoiBase",
-                "module": "src/ar/poi/poi-base.ts"
-              }
-            },
-            {
-              "kind": "method",
-              "name": "syncHeaderState",
-              "privacy": "private",
+              "description": "Auto-enable `hasHeader` when the consumer slots header content directly\n(outside a stack, which manages `hasHeader` itself). Header elements stay\nin the consumer's light DOM and reach the inner button through the\n`<slot name=\"header\">` forwarding chain; their `state` is synced by\n`obc-poi-button`.",
               "inheritedFrom": {
                 "name": "PoiBase",
                 "module": "src/ar/poi/poi-base.ts"
@@ -11183,10 +12144,7 @@
             },
             {
               "name": "y",
-              "type": {
-                "text": "number"
-              },
-              "default": "192",
+              "default": "DEFAULT_LINE_LENGTH_PX",
               "fieldName": "y",
               "inheritedFrom": {
                 "name": "PoiBase",
@@ -11205,6 +12163,26 @@
                 "module": "src/ar/poi/poi-base.ts"
               }
             },
+            {
+              "name": "x-filter-cutoff-hz",
+              "default": "X_FILTER_CUTOFF_HZ",
+              "description": "Cutoff frequency (Hz) of the built-in low-pass filter applied to `x`. Lower values smooth noisy input more aggressively; `0` or a negative value disables filtering so `x` is applied directly.",
+              "fieldName": "xFilterCutoffHz",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
+            {
+              "name": "y-filter-cutoff-hz",
+              "default": "Y_FILTER_CUTOFF_HZ",
+              "description": "Cutoff frequency (Hz) of the built-in low-pass filter applied to `y`. Lower values smooth noisy input more aggressively; `0` or a negative value disables filtering so `y` is applied directly.",
+              "fieldName": "yFilterCutoffHz",
+              "inheritedFrom": {
+                "name": "PoiBase",
+                "module": "src/ar/poi/poi-base.ts"
+              }
+            },
             {
               "name": "fixed-target",
               "type": {
@@ -11345,7 +12323,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "`<obc-poi>` - Composite marker component that renders a target button with connector and pointer visuals.\n\n## Overview\nCombines `obc-poi-button`, `obc-poi-line`, and optional pointer visuals to display\ninteractive marker/callout targets in line, offset, point, or outside modes.\nKeywords: marker, callout, pin, label, target, pointer.\n\n## Features/Variants\n\nConfiguration defaults and behavior:\n- `type` (default: `line`):\n  - `line`: renders a vertical connector line from button to target.\n  - `offset`: renders a bent connector using `targetOffsetX - buttonOffsetX`.\n  - `point`: suppresses long connector behavior (line can collapse/skip based on state).\n  - `outside`: suppresses connector line; outside arrow is rendered when `hasPointer` is true.\n- `value` (default: `unchecked`):\n  - `unchecked`: default visual state.\n  - `checked`: selected-like visual and pointer behavior.\n  - `activated`: activated button visual state with selected-like pointer behavior.\n  - `overlapped`: compact overlap visual state.\n- `overlapOpaque` (default: `false`): controls overlapped opacity mode (`false` = translucent, `true` = opaque).\n- `state` (default: `enabled`):\n  - `enabled`: neutral alert ring and regular line style.\n  - `caution`/`warning`/`alarm`: applies alert-specific button/line styling.\n  - In `enabled`, pointer type resolution defaults to point.\n- `selected` (default: `false`): enables selected emphasis semantics (for example selected line style when not in alert state).\n- `hasPointer` (default: `false`):\n  - For `line`/`offset`/`point`, pointer visuals are shown when `hasPointer` is true.\n  - Checked-like values also force inline pointer visuals for non-`outside` types.\n  - For `outside`, `hasPointer` controls outside-arrow visibility.\n- `pointerType` (default: `null`, enum `point | button | camera`):\n  - Used when not in checked-like state and not `enabled`.\n  - Otherwise resolves to `point` for consistent selected/enabled behavior.\n- `pointerState` (default: `null`, enum `regular | selected | active | uncertain`):\n  - Checked-like non-`outside` values resolve to `selected`.\n  - Otherwise falls back to provided `pointerState` or `regular`.\n\nMotion and layout notes:\n- `animatePosition` (default: `false`): when true, enables short position transition timing for line/pointer movement.\n- `x` (default: `0`): host horizontal position; sets `--obc-poi-x` as `${x}px`.\n- `y` (default: `96`): absolute local target Y; non-finite values fall back to `0` in geometry calculations.\n- `buttonY` (default: `0`): when `fixedTarget=false`, anchors the button at its local Y while the target is derived below it from `y`; when `fixedTarget=true`, preserves the legacy host-anchor behavior.\n- `buttonOffsetX`/`targetOffsetX` (defaults: `0`/`0`): define connector bend delta via `targetOffsetX - buttonOffsetX`.\n- `boxWidth`/`boxHeight` (defaults: `null`/`null`): optional pointer frame size extras; invalid/non-finite values are ignored.\n- `outsideAngle` (default: `315`): controls outside-arrow direction in `outside` mode.\n\n## Usage Guidelines\n\n- Use `type=\"line\"` or `type=\"offset\"` when the button should connect to a remote target.\n- Use `type=\"point\"` for near-target placements where connector emphasis should be minimal.\n- Use `type=\"outside\"` with `hasPointer` for off-screen or directional guidance.\n- Keep `value`, `state`, and `selected` aligned with domain state so visual semantics stay consistent.\n- Provide finite numbers for layout props (`x`, `y`, `buttonY`, offsets) for predictable placement.\n\n## Slots/Content\n\n- Default slot: Main icon/content rendered inside `obc-poi-button`.\n- `button`: Optional custom button element replacing the default `obc-poi-button`.\n- `header`: Optional header content. Relocated into the inner `obc-poi-button` at runtime by a `MutationObserver` (there is no `<slot name=\"header\">` element).\n\n## Events\n\nThis component does not emit custom events.\n\n## Best Practices\n\n- Pass finite numeric values for layout properties to avoid fallback-to-zero behavior.\n- Enable `animatePosition` only for intentional motion transitions and moving targets.\n- Prefer enum values for `type`, `value`, `state`, `pointerType`, and `pointerState`.\n\n## Example\n\n```html\n<obc-poi type=\"line\" value=\"unchecked\" state=\"enabled\">\n  <obi-placeholder></obi-placeholder>\n</obc-poi>\n```",
+          "description": "`<obc-poi>` - Composite marker component that renders a target button with connector and pointer visuals.\n\n## Overview\nCombines `obc-poi-button`, `obc-poi-line`, and optional pointer visuals to display\ninteractive marker/callout targets in line, offset, point, or outside modes.\nKeywords: marker, callout, pin, label, target, pointer.\n\n## Features/Variants\n\nConfiguration defaults and behavior:\n- `type` (default: `line`):\n  - `line`: renders a vertical connector line from button to target.\n  - `offset`: renders a bent connector using `targetOffsetX - buttonOffsetX`.\n  - `point`: suppresses long connector behavior (line can collapse/skip based on state).\n  - `outside`: suppresses connector line; outside arrow is rendered when `hasPointer` is true.\n- `value` (default: `unchecked`):\n  - `unchecked`: default visual state.\n  - `checked`: selected-like visual and pointer behavior.\n  - `activated`: activated button visual state with selected-like pointer behavior.\n  - `overlapped`: compact overlap visual state.\n- `overlapOpaque` (default: `false`): controls overlapped opacity mode (`false` = translucent, `true` = opaque).\n- `state` (default: `enabled`):\n  - `enabled`: neutral alert ring and regular line style.\n  - `caution`/`warning`/`alarm`: applies alert-specific button/line styling.\n  - In `enabled`, pointer type resolution defaults to point.\n- `selected` (default: `false`): enables selected emphasis semantics (for example selected line style when not in alert state).\n- `hasPointer` (default: `false`):\n  - For `line`/`offset`/`point`, pointer visuals are shown when `hasPointer` is true.\n  - Checked-like values also force inline pointer visuals for non-`outside` types.\n  - For `outside`, `hasPointer` controls outside-arrow visibility.\n- `pointerType` (default: `null`, enum `point | button | camera`):\n  - Used when not in checked-like state and not `enabled`.\n  - Otherwise resolves to `point` for consistent selected/enabled behavior.\n- `pointerState` (default: `null`, enum `regular | selected | active | uncertain`):\n  - Checked-like non-`outside` values resolve to `selected`.\n  - Otherwise falls back to provided `pointerState` or `regular`.\n\nMotion and layout notes:\n- `animatePosition` (default: `false`): when true, enables short position transition timing for line/pointer movement.\n- `x` (default: `0`): host horizontal position; sets `--obc-poi-x` as `${x}px`.\n- `y` (default: `192`): absolute local target Y; non-finite values fall back to `0` in geometry calculations. The default is shared with the top-level POI variants (`DEFAULT_LINE_LENGTH_PX`).\n- `buttonY` (default: `0`): when `fixedTarget=false`, anchors the button at its local Y while the target is derived below it from `y`; when `fixedTarget=true`, preserves the legacy host-anchor behavior.\n- `buttonOffsetX`/`targetOffsetX` (defaults: `0`/`0`): define connector bend delta via `targetOffsetX - buttonOffsetX`.\n- `boxWidth`/`boxHeight` (defaults: `null`/`null`): optional pointer frame size extras; invalid/non-finite values are ignored.\n- `outsideAngle` (default: `315`): controls outside-arrow direction in `outside` mode.\n\n## Usage Guidelines\n\n- Use `type=\"line\"` or `type=\"offset\"` when the button should connect to a remote target.\n- Use `type=\"point\"` for near-target placements where connector emphasis should be minimal.\n- Use `type=\"outside\"` with `hasPointer` for off-screen or directional guidance.\n- Keep `value`, `state`, and `selected` aligned with domain state so visual semantics stay consistent.\n- Provide finite numbers for layout props (`x`, `y`, `buttonY`, offsets) for predictable placement.\n\n## Slots/Content\n\n- Default slot: Main icon/content rendered inside `obc-poi-button`.\n- `button`: Optional custom button element replacing the default `obc-poi-button`.\n- `header`: Optional header content, forwarded into the default `obc-poi-button` through a `<slot name=\"header\">` chain. Content stays in the consumer's light DOM. When a custom `button` is slotted, place header content directly inside it instead.\n\n## Events\n\nThis component does not emit custom events.\n\n## Best Practices\n\n- Pass finite numeric values for layout properties to avoid fallback-to-zero behavior.\n- Enable `animatePosition` only for intentional motion transitions and moving targets.\n- Prefer enum values for `type`, `value`, `state`, `pointerType`, and `pointerState`.\n\n## Example\n\n```html\n<obc-poi type=\"line\" value=\"unchecked\" state=\"enabled\">\n  <obi-placeholder></obi-placeholder>\n</obc-poi>\n```",
           "name": "ObcPoi",
           "slots": [
             {
@@ -11357,7 +12335,7 @@
               "name": "button"
             },
             {
-              "description": "Optional header content, relocated into the inner `obc-poi-button` at runtime.",
+              "description": "Optional header content, forwarded into the default `obc-poi-button` via a `<slot name=\"header\">` chain.",
               "name": "header"
             }
           ],
@@ -11499,7 +12477,7 @@
             {
               "kind": "field",
               "name": "y",
-              "default": "96",
+              "default": "192",
               "attribute": "y",
               "type": {
                 "text": "number"
@@ -11581,19 +12559,6 @@
               "default": "false",
               "attribute": "animate-position"
             },
-            {
-              "kind": "field",
-              "name": "headerObserver",
-              "type": {
-                "text": "MutationObserver | undefined"
-              },
-              "privacy": "private"
-            },
-            {
-              "kind": "method",
-              "name": "setupHeaderObserver",
-              "privacy": "private"
-            },
             {
               "kind": "method",
               "name": "updatePosition",
@@ -11626,15 +12591,6 @@
               "privacy": "protected",
               "readonly": true
             },
-            {
-              "kind": "field",
-              "name": "resolvedHeaderState",
-              "type": {
-                "text": "ObcPoiHeaderState"
-              },
-              "privacy": "private",
-              "readonly": true
-            },
             {
               "kind": "field",
               "name": "lineStyle",
@@ -11791,29 +12747,6 @@
                 }
               ]
             },
-            {
-              "kind": "method",
-              "name": "syncFallbackButtonHeaderContent",
-              "privacy": "private"
-            },
-            {
-              "kind": "method",
-              "name": "applyHeaderState",
-              "privacy": "private",
-              "parameters": [
-                {
-                  "name": "root",
-                  "type": {
-                    "text": "ParentNode"
-                  }
-                }
-              ]
-            },
-            {
-              "kind": "method",
-              "name": "syncAttachedHeaderState",
-              "privacy": "private"
-            },
             {
               "kind": "method",
               "name": "syncSlottedButtonProps",
@@ -12035,6 +12968,14 @@
             "module": "src/ar/poi/poi.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "DEFAULT_LINE_LENGTH_PX",
+          "declaration": {
+            "name": "DEFAULT_LINE_LENGTH_PX",
+            "module": "src/ar/poi/poi.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "ObcPoi",