srcdev-nuxt-components 9.5.4 → 9.5.6

package/.claude/skills/components/action-menu.md

@@ -8,7 +8,7 @@
 Clicking it opens an anchored menu list populated via indexed dynamic slots (`item-{n}`). Each slot
 should contain a single `ActionMenuItem` — either a `<button>` (for actions) or a link (for
 navigation). The popover API and CSS anchor positioning handle positioning and dismiss behaviour
-natively; no JavaScript click-outside logic is needed.
+natively, with a JS fallback for older Safari (see Notes).
 
 **Location**: `app/components/02.molecules/action-menu/`
 
@@ -16,7 +16,7 @@ natively; no JavaScript click-outside logic is needed.
 
 ## Components
 
-### ActionMenu
+### `ActionMenu`
 
 | Prop | Type | Default | Notes |
 |---|---|---|---|
@@ -24,7 +24,7 @@ natively; no JavaScript click-outside logic is needed.
 | `triggerIcon` | `string` | `"lucide:ellipsis"` | Icon on the trigger button. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes on the root `<div>`. |
 
-**Slots**
+#### Slots
 
 | Slot | When used |
 |---|---|
@@ -32,7 +32,7 @@ natively; no JavaScript click-outside logic is needed.
 
 ---
 
-### ActionMenuItem
+### `ActionMenuItem`
 
 | Prop | Type | Default | Notes |
 |---|---|---|---|
@@ -41,19 +41,20 @@ natively; no JavaScript click-outside logic is needed.
 | `arrowIcon` | `string` | `"lucide:arrow-right"` | Decorative trailing arrow icon. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes on the root element. |
 
-**Slots**
+#### Slots
 
 | Slot | Content |
 |---|---|
 | `#icon` | Optional left icon (e.g. `<Icon name="lucide:pencil" />`). Wrapped in `aria-hidden` span. |
 
-**Emits**
+#### Emits
 
 | Event | Payload | Notes |
 |---|---|---|
 | `click` | `MouseEvent` | Fired on every click regardless of whether the item is a button or link. |
 
-**Notes on routing**
+#### Notes on routing
+
 - Internal paths (`/…`) resolve to `<NuxtLink>` via `resolveComponent`.
 - External URLs or relative paths without a leading `/` render as plain `<a>`.
 - `type="button"` is set automatically on `<button>` elements to prevent accidental form submission.
@@ -63,7 +64,7 @@ natively; no JavaScript click-outside logic is needed.
 ## Basic usage
 
 ```vue
-<ActionMenu :item-count="3" label="Row actions">
+<ActionMenu label="Row actions">
   <template #item-0>
     <ActionMenuItem label="Edit" @click="handleEdit">
       <template #icon><Icon name="lucide:pencil" /></template>
@@ -122,13 +123,18 @@ Quick reference:
 
 ## Notes
 
-- **Popover API + CSS anchor positioning** — the menu uses the `popover` attribute (broadly supported)
-  and `position-anchor` (newer: Chromium 125+, Safari 26+). Without anchor positioning the popover
-  still opens, just not anchored to the trigger. No polyfill is included.
-- **Auto-close** — clicking any `<li>` row fires `hidePopover()` on the menu. The `ActionMenuItem`
-  emitting `click` triggers normally before the menu closes.
-- **Focus management** — on open the `toggle` event fires `handleToggle`, which moves focus to the
-  first `[role="menuitem"]` inside the popover.
+- **Popover API + CSS anchor positioning, with fallbacks** — open/close and positioning go through
+  the shared `useAnchoredPopover` composable, same as `SelectMenu`. Without anchor
+  positioning (Safari 17–18) JS measures the trigger and writes `--_anchor-*` px values
+  for the `@supports not (anchor-name: --a)` block. Without the Popover API (Safari 16) the trigger
+  toggles `isOpen`, `.action-menu-popover-open` shows the menu, outside pointerdown and Escape
+  close it, and `--action-menu-popover-z-index` (default `999999`) applies. See the `select-menu`
+  skill doc for the details and the `:popover-open` selector-list caveat.
+- **`aria-expanded`** on the trigger tracks the open state in every browser (added 2026-10-05).
+- **Auto-close** — clicking any `<li>` row calls the composable's `hide()` (native `hidePopover()`
+  or the fallback). The `ActionMenuItem` emitting `click` triggers normally before the menu closes.
+- **Focus management** — on open (the `toggle` event, or after render in the fallback), focus moves
+  to the first `[role="menuitem"]` inside the popover.
 - **Keyboard navigation `currentIndex === -1` guard** — `handleKeydown` computes the current
   position via `items.indexOf(document.activeElement)`. When focus is outside the menu this returns
   `-1`. Always guard explicitly before applying wrap-around math: `ArrowDown` should focus

package/.claude/skills/components/deep-expanding-menu.md

@@ -13,12 +13,12 @@ type: reference
 anchor-positioning (`anchor-name`/`position-anchor`/`anchor()`) and the native Popover API
 (`popover`/`popovertarget`).
 
-**Browser support caveat:** CSS anchor-positioning and the Popover API are both comparatively
-recent — check current browser support before shipping this on a page that must work everywhere,
-same caution as `ExpandingPanel`'s `::details-content` gap (CLAUDE.md pitfall #19). If broad
-support is a hard requirement, use [`DeepExpandingMenuClassic`](deep-expanding-menu-classic.md)
-instead — same API and visual result, built on `<details>`/`<summary>` +
-`onClickOutside` instead.
+**Browser support:** since 2026-10-05 open/close and positioning go through the shared
+`useAnchoredPopover` composable (see `composable-anchored-popover.md`), so the menu also works
+without anchor positioning (Safari 17–18: JS-measured `position: fixed`) and without the Popover
+API (Safari 16: JS open/close, outside click and Escape). Before that, panels never opened on
+Safari 16. [`DeepExpandingMenuClassic`](deep-expanding-menu-classic.md) is still the alternative
+built on `<details>`/`<summary>`: same API and visual result, with no popover layer involved.
 
 ## Props
 
@@ -82,6 +82,18 @@ See `CONSUMER-STYLING.md` for the full token API and what's not tokenised.
 - Auto-imported in Nuxt — no manual import needed.
 - Anchor names and popover target ids are generated per-instance via `useId()`, so multiple
   instances on one page don't collide.
+- One `useAnchoredPopover` instance serves every group: `activeKey` tracks the open group, and the
+  composable's `triggerRef`/`popoverRef` are computeds over per-group element maps (filled by
+  function refs). Native `toggle` events for two auto popovers can arrive in either order (B opens,
+  then A closes), so a close event is ignored unless it's for the active group.
+- Each group toggle has `aria-expanded`; the caret flip keys off it rather than
+  `:has(:popover-open)`, so it works in the fallback too.
+- Panels have no ARIA role: this is the disclosure-navigation pattern (a toggle with
+  `aria-expanded` revealing ordinary links), not an ARIA menu. `role="menu"` was removed 2026-10-05
+  because it requires `menuitem` children and arrow-key handling the panels don't have, so screen
+  readers announced a menu that didn't behave like one. Don't add it back.
+- 2026-10-05: removed two never-referenced `@position-try` blocks (`--anchor-left`, and an invalid
+  `@position-try-fallbacks --anchor-right` at-rule).
 - 2026-09-07 migration: moved from an unplaced top-level folder into
   `02.molecules/navigation/deep-expanding-menu/`; converted options-style `defineProps` to
   `interface Props` + `withDefaults`; the previous hardcoded `nav-1` anchor/popover id prefix

package/.claude/skills/components/display-tooltip-defined.md

@@ -10,7 +10,8 @@ type: reference
 
 `DisplayTooltipDefined` composes [`DisplayTooltip`](display-tooltip.md), supplying a structured
 title/body/action content shape (each rendered with a consumer-chosen tag) plus a built-in close
-button wired to the popover's `popovertarget`. Use this when you want the standard tooltip content
+button wired to the popover's `popovertarget` and to `DisplayTooltip`'s scoped `close()`, so it also
+closes the tooltip on Safari 16 (no Popover API). Use this when you want the standard tooltip content
 layout without hand-building the `tooltipContent` slot markup each time; use plain `DisplayTooltip`
 directly when you need full control over the popover's content.
 

package/.claude/skills/components/display-tooltip.md

@@ -14,9 +14,11 @@ the native Popover API (`popover`/`popovertarget`) and CSS anchor-positioning
 with a built-in close button, see [`DisplayTooltipDefined`](display-tooltip-defined.md), which
 composes this component.
 
-**Browser support caveat:** CSS anchor-positioning and the Popover API are both comparatively
-recent — check current browser support before relying on this where broad support is a hard
-requirement, same caution as `DeepExpandingMenu`'s equivalent gap.
+**Browser support:** since 2026-10-05 open/close and positioning go through the shared
+`useAnchoredPopover` composable (`side: "right"`, see `composable-anchored-popover.md`). Without
+anchor positioning (Safari 17–18) the panel is placed from the trigger's measured position, flipping
+to the left when there's no room on the right. Without the Popover API (Safari 16) it opens and
+closes in JS, with outside-click and Escape dismissal. The trigger has `aria-expanded`.
 
 ## Props
 
@@ -32,7 +34,7 @@ requirement, same caution as `DeepExpandingMenu`'s equivalent gap.
 | Slot | Description |
 |------|-------------|
 | `triggerContent` | Optional content rendered before the trigger button (e.g. a label the tooltip icon sits next to). |
-| `tooltipContent` | Content rendered inside the popover panel. |
+| `tooltipContent` | Content rendered inside the popover panel. Scoped prop `close()` hides the panel in every browser: wire your own close button to it (`#tooltipContent="{ close }"`), since `popovertargetaction="hide"` alone does nothing without the Popover API. |
 
 ## Basic usage
 
@@ -54,6 +56,10 @@ popover width/colours/radius, and the close-button tokens `DisplayTooltipDefined
 
 ## Notes
 
+- Slotted content: direct children of `tooltipContent` get `margin-block: 0` (in `:where()`, so
+  consumer margins win) and the panel sets `--display-tooltip-popover-font-size` (`1.4rem`) and
+  `-line-height` (`1.4`), so a bare `<p>` reads as tooltip text without extra styling.
+
 - Auto-imported in Nuxt — no manual import needed.
 - `tooltipId` is only reactive at mount — changing it after mount does not regenerate the linked
   `popovertarget`/`id` pair reactively beyond Vue's normal re-render, since both derive from the

package/.claude/skills/components/pop-over.md

@@ -15,9 +15,12 @@ with fully consumer-supplied content, built on the native Popover API
 text) or `ActionMenu` (menu semantics with arrow-key navigation), `PopOver` makes no assumption
 about what the trigger or content look like, and always renders its own visible close button.
 
-**Browser support caveat:** CSS anchor-positioning and the Popover API are both comparatively
-recent — check current browser support before relying on this where broad support is a hard
-requirement, same caution as `DisplayTooltip`/`DeepExpandingMenu`'s equivalent gap.
+**Browser support:** since 2026-10-05 open/close and positioning go through the shared
+`useAnchoredPopover` composable, with `side` following the `placement` prop (see
+`composable-anchored-popover.md`). Without anchor positioning (Safari 17–18) the panel is placed
+from the trigger's measured position on the `placement` side, flipping to the opposite side when
+there's no room. Without the Popover API (Safari 16) it opens and closes in JS, with outside-click
+and Escape dismissal.
 
 ## Props
 
@@ -72,11 +75,11 @@ the only source of space above/below the slotted content — a plain `<p>` doesn
 
 ## Behaviour
 
-- Opening/closing is handled natively by the Popover API: clicking the trigger toggles the panel,
-  clicking the close button or pressing Escape hides it, and focus returns to the trigger
-  automatically on close.
-- On open, focus moves to the close button (`handleToggle`, driven by the popover's native
-  `toggle` event) so keyboard users land inside the panel immediately.
+- Clicking the trigger toggles the panel; the close button, Escape or an outside click hides it,
+  and focus returns to the trigger. Natively this is the Popover API; on Safari 16 the composable
+  does the same in JS. The trigger has `aria-expanded` in every browser.
+- On open, focus moves to the close button (the composable's `onOpen`) so keyboard users land
+  inside the panel immediately.
 
 ## CSS custom properties
 

package/.claude/skills/components/select-menu.md

@@ -171,11 +171,22 @@ Quick reference:
 
 ## Notes
 
-- **Popover API + CSS anchor positioning** — same mechanism as `ActionMenu`. The Popover API is
-  broadly supported (Chrome 114+, Firefox 125+, Safari 17+), but CSS anchor positioning is much
-  newer (Chromium 125+, Safari 26+), and without it the popover isn't placed under the trigger. No
-  polyfill or fallback is included, so check support before using this where older devices
-  matter; a native `<select>` (`InputSelect`) is the safer choice there.
+- **Popover API + CSS anchor positioning, with fallbacks** — same mechanism as `ActionMenu`, both
+  via the shared `useAnchoredPopover` composable (`app/composables/useAnchoredPopover.ts`). The
+  Popover API arrived in Safari 17 and CSS anchor positioning in Safari 26, so:
+  - No anchor positioning (Safari 17–18): JS measures the trigger and writes `--_anchor-*` px values for the
+    `@supports not (anchor-name: --a)` block, re-measuring on scroll/resize and flipping above
+    (`data-placement="top"`) when there's no room below.
+  - No Popover API (Safari 16, e.g. first-generation iPad Pros that can't update): the trigger's
+    `@click` toggles `isOpen`, `.select-menu-popover-open` shows the list, and document listeners
+    close it on outside pointerdown and Escape. Not top-layer here, hence
+    `--select-menu-popover-z-index` (default `999999`).
+  - Detection runs in `onMounted` (`typeof HTMLElement.prototype.showPopover`, `CSS.supports`), so
+    SSR markup is identical everywhere. Every close goes through the composable's `hide()`, never
+    `hidePopover()` directly, so it works in both modes.
+  - Never put `:popover-open` in a selector list with the fallback class: browsers without it
+    drop the whole rule.
+  Confirmed broken on a Safari 16 iPad before this (trigger rendered, menu never opened).
 - **Left-aligned popover** (`left: anchor(left)`) — unlike `ActionMenu` which right-aligns. Matches
   native `<select>` dropdown behaviour. Flips above the trigger near the bottom of the viewport.
 - **Keyboard navigation** follows the WAI-ARIA listbox pattern: `ArrowDown`/`ArrowUp` move between
@@ -188,9 +199,18 @@ Quick reference:
   `[role="option"]` if one exists (in `multiple` mode, the first checked item), otherwise the first
   option (unlike `ActionMenu`, which always focuses the first item since it has no selection state).
 - **`aria-multiselectable="true"`** is set on the listbox only when `multiple` is `true`.
-- **Chevron rotation is pure CSS** via `:has(.select-menu-popover:popover-open)` on the root — no
-  JS state drives the visual. `isOpen` is still tracked internally, but only to set `aria-expanded`
-  on the trigger.
+- **Selected rows are tinted** via `[aria-selected="true"]` (`--select-menu-item-surface-selected`,
+  default `--theme-surface-subtle`), in both single and multiple mode. Hover/focus is declared after
+  it at equal specificity, so the hover surface still shows on a selected row. Selected text colour,
+  font weight and border colour have their own `-selected` tokens falling back to the resting ones.
+  The row border width (`--select-menu-item-border-width`, default `0`) applies to every row with a
+  transparent resting colour, so a selected border never shifts layout. A hidden `::after` carrying
+  `data-label` in the selected weight reserves the label column's width, so a bolder selected
+  weight doesn't resize the popover. Hover/focus has `-text-color-hover` and `-border-hover`, which
+  fall back to the row's *current* state (selected or resting), not always to resting. There's no
+  hover font-weight token on purpose: the width reserve only covers one alternate weight.
+- **Chevron rotation** keys off the trigger's `aria-expanded` (from the composable's `isOpen`), not
+  `:has(...:popover-open)`, so it also works without the Popover API (changed 2026-10-05).
 - **No native `<select>`/`appearance: base-select` involved** — this is a from-scratch popover
   listbox, not a styled native select, so it doesn't inherit `InputSelectCore`'s WebKit
   `appearance: base-select` constraints.

package/.claude/skills/components/triple-toggle-switch.md

@@ -28,7 +28,7 @@ for that for a theme switch; use `TripleToggleSwitch` directly for any other thr
 | `name` | `string` | `"triple-toggle-switch"` | Shared radio `name`. Give each instance on a page its own. |
 | `aria-label` | `string` | `""` | Accessible name for the `role="radiogroup"`. Omitted from the DOM when empty. Always pass one. |
 | `theme` | `FormUiTheme` | `"default"` | Rendered as `data-theme`. |
-| `step-animation-duration` | `string` | `"250ms"` | Marker slide duration. Ignored under `prefers-reduced-motion`. |
+| `step-animation-duration` | `string` | `"250ms"` | Marker slide duration; also times the icon colour swap (see Behaviour). Ignored under `prefers-reduced-motion`. |
 | `style-class-passthrough` | `string \| string[]` | `[]` | Classes on the root. |
 
 Option `id`s are used as element ids (and as a class on each icon), so they must be unique on the
@@ -66,6 +66,12 @@ const options = ref<IFormMultipleOptions>({
 - The marker is measured from the first option's width on mount and fades in after ~250ms. It
   isn't re-measured on resize, so changing the icon-size/padding tokens after mount (e.g. toggling
   a class) leaves the marker at its old size.
+- Icon colour swaps are timed to the marker: the newly active icon waits half of
+  `stepAnimationDuration`, then fades to the active colour over the other half, so it lands as the
+  marker arrives rather than turning white on the bare track. The previous icon fades back straight
+  away. The marker takes the same time whatever the distance, so no per-index delay is needed.
+- Option circles are sized by their content (1em icon + equal padding) with `place-items: center`,
+  not `aspect-ratio`; older iPad Safari mis-centred the icons under the `aspect-ratio` version.
 - Marker gradients only exist for the values `system`, `light` and `dark`; other values get the
   plain `--triple-toggle-switch-marker-surface` background.
 

package/.claude/skills/components/ui-block-decorated.md

@@ -42,6 +42,13 @@ short: `--ui-block-decorated-border-1` .. `-6`, `--ui-block-decorated-shadow-1`
 `--ui-block-decorated-inner-shadow-1` .. `-4`, and `--ui-block-decorated-inner-shadow-highlight`
 (layered on top of every inner shadow level).
 
+To recolour every level at once (added 2026-10-05): `--ui-block-decorated-border-colour` (default
+`var(--theme-border)`), `--ui-block-decorated-shadow-colour` (default `#000`) and
+`--ui-block-decorated-inner-shadow-colour` (default: the shadow colour). Each shadow level mixes the
+colour with its own opacity via `color-mix()` (8% .. 18%), so defaults render exactly as before.
+The per-level tokens still override the whole value. The story has colour pickers for all three,
+plus story-only background and text colour controls for checking contrast.
+
 ## Notes
 
 - 2026-09-16 migration: previously used options-style `defineProps` and referenced six families of

package/.claude/skills/composable-anchored-popover.md

@@ -0,0 +1,108 @@
+# useAnchoredPopover
+
+`app/composables/useAnchoredPopover.ts`. Open/close state and positioning for a trigger + `popover`
+element anchored with CSS anchor positioning, with fallbacks for browsers that lack either
+feature. Used by `ActionMenu`, `SelectMenu`, `DeepExpandingMenu` (all `side: "bottom"`, the default)
+`DisplayTooltip` (`side: "right"`) and `PopOver` (`side: () => props.placement`). Use it for any new anchored popover instead of calling `showPopover()`/`hidePopover()`
+directly.
+
+Several popovers where only one is open at a time (e.g. `DeepExpandingMenu`'s groups) can share
+one instance: keep an `activeKey`, pass computeds over per-item element maps as `triggerRef`/
+`popoverRef` (the options accept readonly refs), and ignore a `toggle` close event that isn't for
+the active item, since auto popovers' open and close events can arrive in either order.
+
+## Why
+
+- The Popover API arrived in Safari 17; CSS anchor positioning only in Safari 26.
+- Safari 16 (e.g. first-generation iPad Pros, which can't update past iPadOS 16) has neither: the
+  trigger renders but the menu never opens.
+- Safari 17–18 has the Popover API but no anchor positioning: the menu opens in the wrong place.
+
+## Modes (detected in `onMounted`, so SSR markup is the same everywhere)
+
+| Support | Behaviour |
+|---|---|
+| Popover API + anchor positioning | Fully native. The composable only tracks `isOpen` from `toggle`. |
+| Popover API, no anchor positioning | JS measures the trigger on `beforetoggle`/`toggle` and on scroll/resize, and writes the trigger's edges as `--_anchor-*` px values (see below); flips to the opposite side (`data-placement`) when the preferred side has no room and the opposite side does. |
+| No Popover API | Also opens/closes in JS: trigger `@click` toggles `isOpen`, document `pointerdown` outside the root and `Escape` close it, and `hide()` returns focus to the trigger when focus was inside the popover, as native popovers do. The component shows the popover from a fallback class. |
+
+## API
+
+```ts
+const {
+  isOpen,              // Ref<boolean>, accurate in every mode; bind to aria-expanded
+  usesFallbackPopover, // Ref<boolean>, true without the Popover API
+  needsPositioning,    // Ref<boolean>, true without anchor positioning
+  positionStyle,       // bind to the popover's :style (undefined when not needed)
+  popoverPlacement,    // bind to :data-placement: the resolved side, or undefined when native
+  show, hide,          // always use these, never showPopover()/hidePopover() directly
+  handleTriggerClick,  // trigger @click (no-op where popovertarget works)
+  handleBeforeToggle,  // popover @beforetoggle
+  handleToggle,        // popover @toggle
+} = useAnchoredPopover({ rootRef, triggerRef, popoverRef, side: "bottom", onOpen: focusFirstItem });
+```
+
+`rootRef` must contain both the trigger and the popover (outside-click detection). `onOpen` runs
+after the popover is visible, so it can move focus into it.
+
+`side` (`"bottom"` default, `"top"`, `"right"`, `"left"`, or a ref/getter of one, e.g. `() => props.placement`) is the preferred side for the fallback
+flip; it doesn't affect native anchor positioning, which the component's own CSS controls.
+
+### Fallback position variables
+
+They mirror `anchor()`: `--_anchor-{top|bottom|left|right}` is the trigger edge in viewport px, for
+the `top`/`left` properties (`top: anchor(bottom)` becomes `top: var(--_anchor-bottom)`).
+`--_anchor-{edge}-inverse` is the same edge measured from the viewport's bottom/right, for the
+`bottom`/`right` properties (`right: anchor(left)` becomes `right: var(--_anchor-left-inverse)`).
+All eight are always written, so CSS picks what each side needs.
+
+## Component wiring
+
+```vue
+<div ref="rootRef" class="x-menu">
+  <button ref="triggerRef" :popovertarget="id" :aria-expanded="isOpen" @click="handleTriggerClick">…</button>
+  <div
+    :id="id"
+    ref="popoverRef"
+    popover
+    class="x-menu-popover"
+    :class="{ 'x-menu-popover-open': usesFallbackPopover && isOpen }"
+    :style="positionStyle"
+    :data-placement="popoverPlacement"
+    @beforetoggle="handleBeforeToggle"
+    @toggle="handleToggle"
+  >…</div>
+</div>
+```
+
+```css
+.x-menu-popover {
+  &:popover-open { display: block; }
+  /* Separate rule: a selector list containing :popover-open is dropped whole where unsupported. */
+  &.x-menu-popover-open { display: block; }
+
+  @supports not (anchor-name: --a) {
+    position: fixed;
+    top: calc(var(--_anchor-bottom, 0px) + var(--x-menu-block-distance, 0.4rem));
+    left: var(--_anchor-left, 0px);
+    z-index: var(--x-menu-popover-z-index, 999999);
+
+    &[data-placement="top"] {
+      top: auto;
+      bottom: calc(var(--_anchor-top-inverse, 0px) + var(--x-menu-block-distance, 0.4rem));
+    }
+  }
+}
+```
+
+Drive any "open" visuals (e.g. a chevron) from `[aria-expanded="true"]` on the trigger, not
+`:has(:popover-open)`.
+
+## Caveats
+
+- In the no-Popover-API mode the popover isn't in the top layer: give it a public z-index token
+  (default `999999`, pitfall #17), and an ancestor with `transform`/`filter`/`contain` becomes its
+  containing block and can misplace it.
+- Tests: happy-dom has no Popover API and its `CSS.supports` can't be spied on. Define/undefine
+  `HTMLElement.prototype.showPopover` and swap `globalThis.CSS` (restore it in `afterEach`); see
+  `app/composables/tests/useAnchoredPopover.spec.ts`.

package/.claude/skills/composable-tooltips-guide.md

@@ -8,7 +8,7 @@
 
 ## Prerequisites
 
-- Uses the native HTML Popover API — supported in all modern browsers (Chrome 114+, Firefox 125+, Safari 17+)
+- Built around the native Popover API (Chrome 114+, Firefox 125+, Safari 17+). With `DisplayTooltip`/`DisplayTooltipDefined` it also works on Safari 16, because those components fall back to JS open/close (`useAnchoredPopover`) and the guide drives them through their trigger buttons. Hand-written raw `[popover]` markup like the example below still needs the Popover API.
 - Popovers must have `id` attributes and corresponding trigger buttons with `popovertarget` and `popovertargetaction="toggle"` attributes
 - Close buttons inside each popover must have `popovertargetaction="hide"`
 
@@ -74,6 +74,8 @@ await startGuide()
 2. If `autoStart` is `true`, calls `startGuide()` which iterates the popovers in DOM order.
 3. For each popover: finds the `[popovertarget][popovertargetaction="toggle"]` trigger button and clicks it to open the popover, then waits for the `[popovertargetaction="hide"]` button to be clicked before advancing.
 4. After the last popover is dismissed, `autoRunGuide` is set to `false` and `isGuideRunning` becomes `false`.
+5. With no close button, a step ends when the trigger's `aria-expanded` turns `"false"` (a `MutationObserver`), or on the popover's `toggle` event with `newState: "closed"` when there's no trigger either.
+6. `stopGuide()`/`restartGuide()` close an open step by clicking its trigger when `aria-expanded="true"`, or with `hidePopover()` where `:popover-open` is supported. They never call `togglePopover()` or match `:popover-open` unguarded, both of which throw on Safari 16.
 
 ## API reference
 

package/.claude/skills/index.md

@@ -66,6 +66,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── composable-tooltips-guide.md      — useTooltipsGuide: sequential popover guide with auto-start, dismiss-to-advance, manual controls
 ├── composable-cookie-consent.md      — useCookieConsent: unset/granted/denied state, cookie persistence, wraps @nuxt/scripts' useScriptTriggerConsent
 ├── composable-analytics.md           — useAnalytics: provider-agnostic trackEvent/page-view tracking (google-analytics only implemented), consent-gated, single call site for setup + firing events
+├── composable-anchored-popover.md    — useAnchoredPopover: popover + anchor positioning with JS fallbacks for Safari 16 (no Popover API) and 17–18 (no anchor positioning); used by ActionMenu/SelectMenu/DeepExpandingMenu/DisplayTooltip/PopOver
 └── components/
     ├── alert-content.md          — AlertContent + AlertContentInner: themed alert panel (icon/title/content/actions/dismiss) under DisplayToast, DisplayPrompt and AlertMaskedContent; showIcon, #actions row, --alert-content-* tokens, app.config icon map
     ├── alert-mask-core.md      — AlertMaskCore: SVG border/background mask sized to slotted content via ResizeObserver, config-prop-driven geometry/colour (no CSS token API)

package/app/assets/styles/setup/06.utility-classes/animations/_animation-scroller-x.css

@@ -14,8 +14,10 @@
 /* Used to scroll scale elements when scrolling x-axis like a carousel. */
 
 @media (prefers-reduced-motion: no-preference) {
-  .animation-scroller-x {
-    animation: scroller linear both;
-    animation-timeline: view(x);
+  @supports (animation-timeline: view()) {
+    .animation-scroller-x {
+      animation: scroller linear both;
+      animation-timeline: view(x);
+    }
   }
 }

package/app/assets/styles/setup/06.utility-classes/animations/_auto-rotate.css

@@ -8,8 +8,10 @@
 }
 
 @media (prefers-reduced-motion: no-preference) {
-  .auto-rotate {
-    animation: autoRotateAnimation;
-    animation-timeline: view();
+  @supports (animation-timeline: view()) {
+    .auto-rotate {
+      animation: autoRotateAnimation;
+      animation-timeline: view();
+    }
   }
 }

package/app/assets/styles/setup/06.utility-classes/animations/_entry-exit-blur.css

@@ -1,7 +1,9 @@
 @media (prefers-reduced-motion: no-preference) {
-  .entry-exit-blur {
-    animation: entryExitBlurAnimation linear both;
-    animation-timeline: view();
+  @supports (animation-timeline: view()) {
+    .entry-exit-blur {
+      animation: entryExitBlurAnimation linear both;
+      animation-timeline: view();
+    }
   }
 }
 @keyframes entryExitBlurAnimation {

package/app/assets/styles/setup/06.utility-classes/animations/_entry-slide-in.css

@@ -8,8 +8,10 @@
 }
 
 @media (prefers-reduced-motion: no-preference) {
-  .entry-slide-in {
-    animation: entrySlideInAnimation forwards;
-    animation-timeline: view(70% 5%);
+  @supports (animation-timeline: view()) {
+    .entry-slide-in {
+      animation: entrySlideInAnimation forwards;
+      animation-timeline: view(70% 5%);
+    }
   }
 }

package/app/assets/styles/setup/06.utility-classes/animations/_entry-zoom-reveal.css

@@ -10,8 +10,10 @@
 }
 
 @media (prefers-reduced-motion: no-preference) {
-  .entry-zoom-reveal {
-    animation: entryZoomRevealAnimation both;
-    animation-timeline: view(70% 5%);
+  @supports (animation-timeline: view()) {
+    .entry-zoom-reveal {
+      animation: entryZoomRevealAnimation both;
+      animation-timeline: view(70% 5%);
+    }
   }
 }

package/app/components/01.atoms/animations/entry/CONSUMER-STYLING.md

@@ -31,8 +31,12 @@ any passthrough classes.
 ## Motion
 
 - All three classes only animate inside `@media (prefers-reduced-motion: no-preference)`.
-- They use `animation-timeline: view(...)` (scroll-driven). In a browser without scroll-driven
-  animation support the animation completes immediately, so the content just appears in place.
+- They use `animation-timeline: view(...)` (scroll-driven), inside an
+  `@supports (animation-timeline: view())` guard, so a browser without scroll-driven animations
+  (Safari before 26, Firefox) shows the content in place with no animation.
+
+> Changed 2026-10-05: the guard is new. Before it, an unsupported browser ran the animation with a
+> zero duration and kept its end keyframe, which for `entry-exit-blur` left the content blurred.
 
 ---
 

package/app/components/01.atoms/display-tooltip/CONSUMER-STYLING.md

@@ -17,6 +17,8 @@
 | `--display-tooltip-popover-width` | `30rem` | Popover panel width |
 | `--display-tooltip-popover-padding` | `1.2rem` | Popover panel content padding |
 | `--display-tooltip-popover-content-gap` | `1.2rem` | Gap between stacked children in the `tooltipContent` slot |
+| `--display-tooltip-popover-font-size` | `1.4rem` | Popover text size (`DisplayTooltipDefined` sets its own per-element sizes) |
+| `--display-tooltip-popover-line-height` | `1.4` | Popover text line height |
 | `--display-tooltip-popover-outline-width` | `0.1rem` | Popover panel outline (border) width |
 | `--display-tooltip-popover-outline-colour` | `var(--slate-02)` | Popover panel outline (border) colour |
 | `--display-tooltip-popover-text-colour` | `var(--slate-09)` | Popover panel text colour |
@@ -24,6 +26,7 @@
 | `--display-tooltip-popover-border-radius` | `0.8rem` | Popover panel corner radius |
 | `--display-tooltip-popover-shadow` | `0 0.4rem 1.6rem rgba(0,0,0,.12)` | Popover panel elevation shadow |
 | `--display-tooltip-popover-offset` | `0.1rem` | Gap between the trigger and the popover panel |
+| `--display-tooltip-popover-z-index` | `999999` | Panel stacking order in browsers without CSS anchor positioning. Ignored where the panel renders in the top layer |
 | `--display-tooltip-close-button-colour` | `var(--slate-09)` | Close button text colour (used by `DisplayTooltipDefined`) |
 | `--display-tooltip-close-button-border-width` | `0.1rem` | Close button border width |
 | `--display-tooltip-close-button-border-colour` | `var(--slate-03)` | Close button border colour |
@@ -61,13 +64,22 @@ Set the tokens above on an element you own (a page or section class, or a class
 
 ## Notes
 
+- Direct children of the `tooltipContent` slot have their block margins reset to `0` (inside
+  `:where()`, so any margin you set on them still wins): the gap token is the only spacing between
+  them. Before 2026-10-05 a slotted `<p>` kept its browser `1em` margins on top of the padding.
+
 - The trigger button is vertically centred on the first line of `triggerContent` text, using
   `--display-tooltip-trigger-icon-box-size`, `-padding` and `-border-width` to work out its height.
   Give `--display-tooltip-trigger-padding` a single length (e.g. `0.4rem`): a two-value shorthand
   breaks that calculation, and the button is square anyway.
-- Built on the native Popover API (`popover`/`popovertarget`) and CSS anchor-positioning
-  (`anchor-name`/`position-anchor`/`anchor()`) — check current browser support before relying on
-  it where broad support is a hard requirement.
+- Built on the native Popover API and CSS anchor positioning, with fallbacks: without anchor
+  positioning (e.g. Safari 17–18) the panel is placed with `position: fixed` from the trigger's
+  measured position and flips left (`.display-tooltip-popover[data-placement="left"]`) when there's
+  no room on the right. Without the Popover API (Safari 16) it opens and closes in JS, shows via
+  `.display-tooltip-popover-open` (style it in a separate rule from `:popover-open`: a selector list
+  containing `:popover-open` is dropped whole where unsupported), isn't in the top layer (so the
+  z-index token applies), and an ancestor with `transform`, `filter` or `contain` can misplace it.
+  The trigger's `aria-expanded` tracks the open state in every browser.
 - The `.display-tooltip-close-button` styled here is rendered by `DisplayTooltipDefined`, not this
   component directly — `DisplayTooltip` only provides the `tooltipContent` slot, so a plain
   `DisplayTooltip` usage supplies its own close affordance if it wants one (give it