@urbicon-ui/blocks 6.24.0 → 6.26.0

package/dist/style/foundation.css

@@ -52,11 +52,20 @@
   --color-warm-neutral-900: oklch(0.2 0.008 45);
   --color-warm-neutral-950: oklch(0.12 0.006 45);
 
-  /* Darkened *-500 / *-600 / *-700 so text-on-primary (white) passes WCAG
-     AA (4.5:1) on the solid intent backgrounds. Previous values had
-     L=0.65 which produced ~3:1 contrast — below AA. Warning keeps its
-     yellow hue at L=0.75 because it pairs with text-on-surface (dark),
-     not white. */
+  /* Darkened *-500 / *-600 / *-700 so text-on-primary (white in light mode)
+     passes WCAG AA (4.5:1) on the solid intent backgrounds **in light
+     mode**, where --color-<intent> resolves to the -500/-600 shades.
+     Previous values had L=0.65 which produced ~3:1 contrast — below AA.
+     Warning is the one inverted ramp: its fill stays light in both modes
+     (500 keeps its yellow at L=0.75) and pairs with the dark,
+     non-mode-aware `text-on-warning` (= warning-950), not white.
+
+     In dark mode --color-<intent> resolves to the *lighter* -400/-300/-200
+     shades and pairs with the dark branch of the mode-aware
+     `text-on-primary` (semantic.css, 2026-07-14). Both directions are
+     measured across all six themes by style/contrast.test.ts. Do not
+     lighten these ramps to "help" dark mode; light mode is the branch
+     these stops guarantee. */
   --color-success-50: oklch(0.95 0.03 140);
   --color-success-100: oklch(0.9 0.05 140);
   --color-success-200: oklch(0.82 0.08 140);
@@ -76,7 +85,14 @@
   --color-warning-400: oklch(0.66 0.14 80);
   --color-warning-500: oklch(0.75 0.15 80);
   --color-warning-600: oklch(0.65 0.15 80);
-  --color-warning-700: oklch(0.55 0.13 80);
+  /* L=0.59, not the ramp's usual 0.55: warning-700 is the light-mode press
+     fill (--color-warning-active) under the dark `text-on-warning`
+     (warning-950). Warning's ramp is inverted — pressing moves TOWARD the
+     dark label — and at L=0.55 the press state measured 3.90–4.05:1, under
+     AA. 0.59 is the lowest 0.01 step at which every themed hue clears
+     4.5:1 (0.58 still fails forest's hue 60 at 4.46:1). Mirrored by the
+     forest/sunset ramps; guarded by contrast.test.ts. */
+  --color-warning-700: oklch(0.59 0.13 80);
   --color-warning-800: oklch(0.45 0.11 80);
   --color-warning-900: oklch(0.25 0.08 80);
   --color-warning-950: oklch(0.15 0.05 80);
@@ -101,13 +117,31 @@
   --color-info-200: oklch(0.84 0.075 220);
   --color-info-300: oklch(0.76 0.105 220);
   --color-info-400: oklch(0.66 0.13 220);
-  --color-info-500: oklch(0.55 0.14 220);
+  /* L=0.54, not 0.55: hue 220 is luminous enough that 0.55 measures 4.41:1
+     against text-on-primary (white) — below AA, despite the promise above.
+     0.54 is the smallest step that clears it (4.58:1) and keeps the ramp's
+     0.12 step down from info-400. Guarded by contrast.test.ts. */
+  --color-info-500: oklch(0.54 0.14 220);
   --color-info-600: oklch(0.48 0.13 220);
   --color-info-700: oklch(0.4 0.11 220);
   --color-info-800: oklch(0.32 0.09 220);
   --color-info-900: oklch(0.24 0.07 220);
   --color-info-950: oklch(0.16 0.05 220);
 
+  /* Sub-xs Type Scale — extends Tailwind's own `--text-*` namespace downwards.
+     Tailwind bottoms out at --text-xs (12px), but dense data marks (chart axis
+     labels, mini-calendar day cells, kbd hints) need 10–11px. Defining them here
+     rather than hardcoding `text-[11px]` at the call site is what makes those
+     sizes reachable by a consumer's own @theme override.
+
+     Deliberately size-only: NO paired `--text-*--line-height`. Tailwind emits
+     `line-height` for a scale entry only when the paired key exists, so adding
+     one would inject a line-height into every call site that today inherits it
+     from the cascade — a rendering change, not a refactor. Consumers who want
+     one can add the paired key in their own @theme; the utility picks it up. */
+  --text-2xs: 0.6875rem;
+  --text-3xs: 0.625rem;
+
   /* Border Radius Scale — physical sizes */
   --radius-xs: 0.125rem;
   --radius-sm: 0.25rem;

package/dist/style/interaction.css

@@ -98,8 +98,8 @@
      transitions, so they read these through the JS mirror in
      `utils/overlay-tokens.ts` (`getOverlayMotion`) — Svelte transitions need
      numeric input. Tooltip runs a deliberately faster CSS opacity fade off its
-     own `--blocks-tooltip-*` tokens below; Popover has no enter/exit motion yet
-     (ACC-3 follow-up).
+     own `--blocks-tooltip-*` tokens below; Popover (and Menu through it) runs a
+     CSS-native fade/scale off the `--blocks-popover-*` tokens below.
 
      Override globally with a `BlocksProvider` style block, or per instance via
      the component's `transitionDuration` / `transitionEasing` props.
@@ -130,6 +130,23 @@
   --blocks-tooltip-duration: var(--blocks-duration-fast);
   --blocks-tooltip-easing: var(--blocks-ease-confident);
 
+  /* === POPOVER MOTION TOKENS (ACC-3 rest) ===
+     The CSS-native enter/exit fade+scale for Popover (and Menu, which passes
+     the same motion fragment to its inner Popover). Anchored panels should
+     feel snappier than the 200ms modal overlays but calmer than an instant
+     toggle, so they share the tooltip's `fast`/`confident` pairing. Enter is
+     driven by `@starting-style` (the panel un-hides via `showPopover()`, so a
+     plain transition has no before-state); exit relies on
+     `transition-behavior: allow-discrete` on `display`/`overlay` to keep the
+     panel painted in the top layer while it fades. Both default through
+     `--blocks-duration-fast`, so `prefers-reduced-motion` below collapses them
+     to 1ms for free. Override globally here, or per instance via Popover's
+     `transitionDuration` / `transitionEasing` props (which set these inline +
+     carry a `motion-reduce` guard, since an inline duration can't see the
+     media query). */
+  --blocks-popover-duration: var(--blocks-duration-fast);
+  --blocks-popover-easing: var(--blocks-ease-confident);
+
   /* === COLLAPSE ANIMATION TOKENS (ACC-3) ===
      The CSS-driven grid-template-rows collapse shared by Accordion +
      Collapsible (and their chevron spin). Default to the normal/smooth

package/dist/style/semantic.css

@@ -54,8 +54,43 @@
   --color-text-tertiary: light-dark(var(--color-neutral-600), var(--color-neutral-300));
   --color-text-quaternary: light-dark(var(--color-neutral-500), var(--color-neutral-400));
   --color-text-disabled: light-dark(var(--color-neutral-300), var(--color-neutral-600));
+  /* The on-colors below pair text with a *fill* rather than a surface.
+     text-on-dark and text-on-primary answer fills that are dark in light
+     mode and light in dark mode, so the label has to travel the opposite
+     way — white, then near-black. They are deliberately NOT aliased to one
+     another (`text-on-primary: var(--color-text-on-dark)`), even though
+     they carry the same value today — they answer to different fills and
+     must stay independently overridable:
+
+       - text-on-dark is the partner of the avatar identity palette, whose 12
+         slots hold ONE lightness per mode (0.45 / 0.72) by construction.
+       - text-on-primary is the partner of the intent fills, whose ramps every
+         theme re-tunes, and which move again on hover/active.
+
+     Aliasing would couple them asymmetrically: a consumer re-tuning the avatar
+     palette's on-color would silently repaint every filled Button/Badge label.
+     Their equality is a consequence of both fill families straddling the same
+     lightness midpoint — not a definition. */
   --color-text-on-dark: light-dark(var(--color-neutral-0), var(--color-neutral-900));
-  --color-text-on-primary: var(--color-neutral-0);
+  /* Dark mode pairs the *lighter* -400/-500 intent fills with dark text (the
+     Material-3 `onPrimary` pattern). White here was unconditional until
+     2026-07-14, which put 125 of the 126 dark-mode intent fills under WCAG AA
+     — down to 1.51:1, and getting *worse* on press. The mode-aware branch
+     clears all 108 fills this token governs; `warning` is not one of them —
+     its fill is light in BOTH modes, so it carries its own non-mode-aware
+     on-color below (`--color-text-on-warning`). */
+  --color-text-on-primary: light-dark(var(--color-neutral-0), var(--color-neutral-900));
+  /* Warning's own on-color. Warning is the one intent whose fill stays a
+     light amber in BOTH modes (base/hover/active ride L 0.59–0.82), so unlike
+     text-on-primary this token is deliberately NOT mode-aware — the label is
+     a warm dark in both modes. It rides the warning ramp's own 950 stop
+     rather than a neutral, so theme re-hues (forest 60, sunset 92) flow
+     through and the label reads as part of the swatch instead of soot on top
+     of it. Until 2026-07-20 filled warning paired with `text-on-surface` — a
+     *surface* token that flips light in dark mode — which put all 18
+     dark-mode warning fills at 1.51–2.80:1. Measured across every theme ×
+     mode × state by style/contrast.test.ts. */
+  --color-text-on-warning: var(--color-warning-950);
   --color-text-on-surface: light-dark(var(--color-neutral-900), var(--color-neutral-100));
 
   /* === PRIMARY INTENT ===
@@ -152,6 +187,54 @@
   --color-chart-5: light-dark(var(--color-info-500), var(--color-info-400));
   --color-chart-6: light-dark(var(--color-danger-500), var(--color-danger-400));
 
+  /* === AVATAR IDENTITY PALETTE ===
+     An *unordered* identity palette: Avatar's `randomColor` hashes a name to a
+     fixed slot, so the same person always keeps the same hue. Deliberately NOT
+     the chart palette and NOT the intent tokens:
+
+       - chart-* only has 6 slots and derives from the intent ramps, so a brand
+         that retunes `secondary` would silently reshuffle people's identities.
+         Its dark values are the *-400 tints (L≈0.66) — light enough that white
+         initials drop to ~2.6:1, below AA. Charts colour marks; avatars carry
+         text on top, which is a different contrast contract.
+       - intent tokens are semantic (a person is not "danger").
+
+     Construction: a single lightness per mode, 12 hues at an even 30° spacing.
+     Because OKLCH lightness is perceptual, holding L constant means every slot
+     shares one guaranteed contrast partner — `--color-text-on-dark`, which
+     flips white → neutral-900 with the mode exactly as these fills flip dark →
+     light. So legibility is a property of the construction, not 12 separate
+     checks. Even spacing also beats the 15 hardcoded hex values this replaced,
+     which clustered (red/orange/amber/yellow within ~20°) and blurred when
+     avatars sat side by side.
+
+     L=0.45 (light) / L=0.72 (dark) mirror the foundation ramps' *-700 / *-300
+     steps, so the palette reads as part of the same chassis. Rebrand by
+     overriding these 12 tokens; the text partner follows automatically. */
+  --color-avatar-1: light-dark(oklch(0.45 0.13 25), oklch(0.72 0.12 25));
+  --color-avatar-2: light-dark(oklch(0.45 0.13 55), oklch(0.72 0.12 55));
+  --color-avatar-3: light-dark(oklch(0.45 0.13 85), oklch(0.72 0.12 85));
+  --color-avatar-4: light-dark(oklch(0.45 0.13 115), oklch(0.72 0.12 115));
+  --color-avatar-5: light-dark(oklch(0.45 0.13 145), oklch(0.72 0.12 145));
+  --color-avatar-6: light-dark(oklch(0.45 0.13 175), oklch(0.72 0.12 175));
+  --color-avatar-7: light-dark(oklch(0.45 0.13 205), oklch(0.72 0.12 205));
+  --color-avatar-8: light-dark(oklch(0.45 0.13 235), oklch(0.72 0.12 235));
+  --color-avatar-9: light-dark(oklch(0.45 0.13 265), oklch(0.72 0.12 265));
+  --color-avatar-10: light-dark(oklch(0.45 0.13 295), oklch(0.72 0.12 295));
+  --color-avatar-11: light-dark(oklch(0.45 0.13 325), oklch(0.72 0.12 325));
+  --color-avatar-12: light-dark(oklch(0.45 0.13 355), oklch(0.72 0.12 355));
+
+  /* === LIVE / "NOW" ACCENT ===
+     Single-purpose accent for live/now markers — the Calendar current-time
+     line and dot, and future live/recording indicators. Red is the
+     convention (Google Calendar et al.), but the *purpose* is not `danger`:
+     a now-line states "you are here", not "something is wrong", and the two
+     must stay independently themeable. Defaults ride the danger foundation
+     ramp, so dark mode and per-theme danger re-tunes flow through
+     automatically; override `--color-live` alone to restyle live indicators
+     without touching error styling. */
+  --color-live: light-dark(var(--color-danger-500), var(--color-danger-400));
+
   /* === BORDERS ===
      border-hairline is the quietest tier — structural
      trennlinien (row dividers, Card header/footer separators, inline

package/dist/style/themes/forest.css

@@ -86,7 +86,9 @@
   --color-warning-400: oklch(0.66 0.14 60);
   --color-warning-500: oklch(0.75 0.15 60);
   --color-warning-600: oklch(0.65 0.15 60);
-  --color-warning-700: oklch(0.55 0.13 60);
+  /* 0.59 mirrors foundation.css: light-mode press fill under the dark
+     text-on-warning — hue 60 is the binding case (0.58 = 4.46:1, under AA). */
+  --color-warning-700: oklch(0.59 0.13 60);
   --color-warning-800: oklch(0.45 0.11 60);
   --color-warning-900: oklch(0.25 0.08 60);
   --color-warning-950: oklch(0.15 0.05 60);

package/dist/style/themes/neutral.css

@@ -17,7 +17,16 @@
   --color-primary-200: oklch(0.84 0.008 240);
   --color-primary-300: oklch(0.76 0.01 240);
   --color-primary-400: oklch(0.65 0.012 240);
-  --color-primary-500: oklch(0.53 0.012 240);
+  /* L 0.58, not the 0.53 this ramp's spacing would suggest: primary-500 is the
+     dark-mode `--color-primary` fill, and dark mode carries dark text on it
+     (`--color-text-on-primary`). At 0.53 this grey measured 3.74:1 against
+     neutral-900 — the one intent fill in the whole system that missed AA after
+     the on-color became mode-aware, because a desaturated mid-grey is the
+     hardest case: no lightness clears AA against BOTH white and neutral-900
+     (proved in style/contrast.test.ts). 0.58 is the lowest step on this
+     ramp's 0.01 grid that clears it (4.59:1; the true crossing is 0.574 =
+     4.50:1, i.e. no margin at all). Monotonicity holds (0.65 > 0.58 > 0.43). */
+  --color-primary-500: oklch(0.58 0.012 240);
   --color-primary-600: oklch(0.43 0.012 240);
   --color-primary-700: oklch(0.36 0.01 240);
   --color-primary-800: oklch(0.29 0.008 240);

package/dist/style/themes/ocean.css

@@ -26,7 +26,11 @@
   --color-secondary-200: oklch(0.82 0.08 190);
   --color-secondary-300: oklch(0.74 0.11 190);
   --color-secondary-400: oklch(0.66 0.13 190);
-  --color-secondary-500: oklch(0.55 0.12 190);
+  /* L=0.54, not the foundation ramp's 0.55: at hue 190 (teal) the same
+     lightness measures 4.39:1 against text-on-primary (white) — below AA.
+     Lightness is not contrast-neutral across hues in OKLCH. Guarded by
+     contrast.test.ts. */
+  --color-secondary-500: oklch(0.54 0.12 190);
   --color-secondary-600: oklch(0.48 0.12 190);
   --color-secondary-700: oklch(0.4 0.1 190);
   --color-secondary-800: oklch(0.32 0.08 190);

package/dist/style/themes/sunset.css

@@ -73,7 +73,9 @@
   --color-warning-400: oklch(0.66 0.14 92);
   --color-warning-500: oklch(0.75 0.15 92);
   --color-warning-600: oklch(0.65 0.15 92);
-  --color-warning-700: oklch(0.55 0.13 92);
+  /* 0.59 mirrors foundation.css: light-mode press fill under the dark
+     text-on-warning (AA floor across all themed hues). */
+  --color-warning-700: oklch(0.59 0.13 92);
   --color-warning-800: oklch(0.45 0.11 92);
   --color-warning-900: oklch(0.25 0.08 92);
   --color-warning-950: oklch(0.15 0.05 92);

package/dist/utils/compose-handlers.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `composeHandlers` — run a component's own DOM event handler *and* a
+ * consumer-supplied one that arrived through `restProps`.
+ *
+ * ## Why this exists
+ *
+ * The library's `restProps` contract (see docs/COMPONENT-API-CONVENTIONS.md)
+ * spreads `{...restProps}` **first**, so the component's own attributes win: a
+ * consumer can't silently cancel state the component owns. Applied naively to
+ * event handlers that rule would go too far in the other direction — a
+ * `restProps`-first spread makes the component's `onkeydown` clobber the
+ * *consumer's*, which is just the original bug pointed the other way.
+ *
+ * Neither side should lose. Handlers are additive by nature (the DOM itself
+ * allows many listeners per event), so the component destructures the handler
+ * out of `restProps` and composes it: **internal first, consumer second**.
+ *
+ * ## Ordering: internal first
+ *
+ * 1. The component's behaviour is then unconditional — it cannot be skipped by
+ *    a consumer handler that throws, which is exactly what "internal wins"
+ *    has to mean for a dismiss/focus-trap path.
+ * 2. The consumer observes the event *after* the component reacted, so
+ *    `event.defaultPrevented` tells them whether the component claimed it
+ *    (e.g. Dialog preventDefaults `Escape` when it closes on it).
+ *
+ * ## `preventDefault` is deliberately NOT a veto
+ *
+ * The consumer's handler runs after the internal one, so calling
+ * `event.preventDefault()` there cannot suppress the component's behaviour —
+ * by design. Overloading `preventDefault` as "also disable this component's
+ * dismissal" would re-create the silent-disable bug through a different door:
+ * `preventDefault` has an established DOM meaning (suppress the *browser's*
+ * default action), and a consumer calling it for that reason would lose
+ * dismissal without ever asking to. Opting out of a behaviour is spelled with
+ * the named, discoverable prop that already exists for it — `closeOnEscape`,
+ * `closeOnBackdropClick` — not with a magic event side-effect.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   let { onkeydown: onkeydownProp, ...restProps }: Props = $props();
+ *   function handleKeydown(event: KeyboardEvent) { ... }
+ * </script>
+ *
+ * <dialog {...restProps} onkeydown={composeHandlers(handleKeydown, onkeydownProp)}>
+ * ```
+ */
+/**
+ * Structural mirror of svelte/elements' internal `EventHandler` type, which is
+ * declared there but not exported. Matching the shape keeps the composed result
+ * assignable to the `on*` props of `HTMLAttributes` (`MouseEventHandler<T>`,
+ * `KeyboardEventHandler<T>`, …).
+ */
+type DomEventHandler<TEvent extends Event, TElement extends EventTarget> = (event: TEvent & {
+    currentTarget: EventTarget & TElement;
+}) => unknown;
+/**
+ * Combine an internal handler with an optional consumer handler from `restProps`.
+ *
+ * The internal handler always runs first and always runs; the consumer handler
+ * runs afterwards when present. See the module doc for the ordering and
+ * `preventDefault` rationale.
+ *
+ * @param internal The component's own handler. Runs first, unconditionally.
+ * @param consumer The consumer's handler from `restProps`. May be `null`/`undefined`.
+ * @returns A handler assignable to the element's `on*` attribute.
+ */
+export declare function composeHandlers<TEvent extends Event, TElement extends EventTarget = Element>(internal: (event: TEvent & {
+    currentTarget: EventTarget & TElement;
+}) => unknown, consumer: DomEventHandler<TEvent, TElement> | null | undefined): DomEventHandler<TEvent, TElement>;
+export {};

package/dist/utils/compose-handlers.js

@@ -0,0 +1,65 @@
+/**
+ * `composeHandlers` — run a component's own DOM event handler *and* a
+ * consumer-supplied one that arrived through `restProps`.
+ *
+ * ## Why this exists
+ *
+ * The library's `restProps` contract (see docs/COMPONENT-API-CONVENTIONS.md)
+ * spreads `{...restProps}` **first**, so the component's own attributes win: a
+ * consumer can't silently cancel state the component owns. Applied naively to
+ * event handlers that rule would go too far in the other direction — a
+ * `restProps`-first spread makes the component's `onkeydown` clobber the
+ * *consumer's*, which is just the original bug pointed the other way.
+ *
+ * Neither side should lose. Handlers are additive by nature (the DOM itself
+ * allows many listeners per event), so the component destructures the handler
+ * out of `restProps` and composes it: **internal first, consumer second**.
+ *
+ * ## Ordering: internal first
+ *
+ * 1. The component's behaviour is then unconditional — it cannot be skipped by
+ *    a consumer handler that throws, which is exactly what "internal wins"
+ *    has to mean for a dismiss/focus-trap path.
+ * 2. The consumer observes the event *after* the component reacted, so
+ *    `event.defaultPrevented` tells them whether the component claimed it
+ *    (e.g. Dialog preventDefaults `Escape` when it closes on it).
+ *
+ * ## `preventDefault` is deliberately NOT a veto
+ *
+ * The consumer's handler runs after the internal one, so calling
+ * `event.preventDefault()` there cannot suppress the component's behaviour —
+ * by design. Overloading `preventDefault` as "also disable this component's
+ * dismissal" would re-create the silent-disable bug through a different door:
+ * `preventDefault` has an established DOM meaning (suppress the *browser's*
+ * default action), and a consumer calling it for that reason would lose
+ * dismissal without ever asking to. Opting out of a behaviour is spelled with
+ * the named, discoverable prop that already exists for it — `closeOnEscape`,
+ * `closeOnBackdropClick` — not with a magic event side-effect.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   let { onkeydown: onkeydownProp, ...restProps }: Props = $props();
+ *   function handleKeydown(event: KeyboardEvent) { ... }
+ * </script>
+ *
+ * <dialog {...restProps} onkeydown={composeHandlers(handleKeydown, onkeydownProp)}>
+ * ```
+ */
+/**
+ * Combine an internal handler with an optional consumer handler from `restProps`.
+ *
+ * The internal handler always runs first and always runs; the consumer handler
+ * runs afterwards when present. See the module doc for the ordering and
+ * `preventDefault` rationale.
+ *
+ * @param internal The component's own handler. Runs first, unconditionally.
+ * @param consumer The consumer's handler from `restProps`. May be `null`/`undefined`.
+ * @returns A handler assignable to the element's `on*` attribute.
+ */
+export function composeHandlers(internal, consumer) {
+    return (event) => {
+        internal(event);
+        consumer?.(event);
+    };
+}

package/dist/utils/figma-token-export.js

@@ -99,7 +99,7 @@ const foundationColors = {
         '400': 'oklch(0.66 0.14 80)',
         '500': 'oklch(0.75 0.15 80)',
         '600': 'oklch(0.65 0.15 80)',
-        '700': 'oklch(0.55 0.13 80)',
+        '700': 'oklch(0.59 0.13 80)',
         '800': 'oklch(0.45 0.11 80)',
         '900': 'oklch(0.25 0.08 80)',
         '950': 'oklch(0.15 0.05 80)'
@@ -123,7 +123,7 @@ const foundationColors = {
         '200': 'oklch(0.84 0.075 220)',
         '300': 'oklch(0.76 0.105 220)',
         '400': 'oklch(0.66 0.13 220)',
-        '500': 'oklch(0.55 0.14 220)',
+        '500': 'oklch(0.54 0.14 220)',
         '600': 'oklch(0.48 0.13 220)',
         '700': 'oklch(0.4 0.11 220)',
         '800': 'oklch(0.32 0.09 220)',
@@ -155,6 +155,10 @@ const semanticTokens = {
         disabled: { value: '{color.neutral.300}', description: 'Disabled text' },
         'on-dark': { value: '{color.neutral.0}', description: 'Text on dark surfaces' },
         'on-primary': { value: '{color.neutral.0}', description: 'Text on primary color bg' },
+        'on-warning': {
+            value: '{color.warning.950}',
+            description: 'Text on the warning fill (warm dark in both modes)'
+        },
         'on-surface': { value: '{color.neutral.900}', description: 'Text on tinted surfaces' }
     },
     border: {

package/dist/utils/guide.svelte.js

@@ -96,10 +96,12 @@ const ROUTE_TARGET_TIMEOUT_MS = 4000;
 /**
  * Heuristic: does `landed` look like a router-normalized form of `route` — a trailing slash
  * (`/expenses/`) or a base/locale prefix (`/de/expenses`) — rather than an unrelated redirect target
- * (`/login`)? Used ONLY to decide whether a *synchronous* own-navigation landing on a non-exact path
- * deserves a DEV diagnostic, never to change tour behavior, so a wrong guess merely over- or
- * under-warns in DEV. `route` is a normalized pathname (leading `/`), so the suffix test lands on a
- * real segment boundary — `/myexpenses` does not end with `/expenses`.
+ * (`/login`)? On the *synchronous* (re-entrant) path it only tunes DEV diagnostics — `#selfNavigating`
+ * is the causal signal there. On the *asynchronous* path (the default source) there is no causal
+ * signal, so this heuristic decides own-vs-foreign for a pending navigation: a normalized-looking
+ * landing keeps the tour running (DEV-warned, since it is a guess), an unrelated one stops it.
+ * `route` is a normalized pathname (leading `/`), so the suffix test lands on a real segment
+ * boundary — `/myexpenses` does not end with `/expenses`.
  */
 function looksLikeNormalizedRoute(landed, route) {
     const stripSlash = (s) => (s.length > 1 && s.endsWith('/') ? s.slice(0, -1) : s);
@@ -191,9 +193,9 @@ export class GuideController {
      * `true` only while our own injected `#navigate()` call is on the stack. A `navigationSource` that
      * reports its location change **synchronously, re-entrant** during that call (SvelteKit's
      * `afterNavigate` fires inside `goto`) IS that very navigation — never a foreign one. This is the
-     * exact signal; the `path === #expectedRoute` check in `#onLocationChange` is only an async-source
-     * proxy for the same thing and breaks the moment the router reports a normalized path
-     * (trailing slash, base/locale prefix) that doesn't equal the raw `step.route`.
+     * exact signal; the `#expectedRoute` matching in `#onLocationChange` (exact path, or a
+     * `looksLikeNormalizedRoute` landing for a router that normalizes) is only an async-source proxy
+     * for the same thing.
      *
      * A boolean (not a depth counter) is enough: the sole re-entrant callee of a sync source is
      * `#onLocationChange`, which never calls `#maybeNavigate`. A `navigate` hook that *synchronously*
@@ -202,6 +204,16 @@ export class GuideController {
      * never open, so it can't keep a genuinely foreign navigation alive.
      */
     #selfNavigating = false;
+    /**
+     * Own navigations superseded before their report arrived — a rapid `next()`/`prev()` while the
+     * previous step's navigation was still in flight moves its `#expectedRoute` here instead of
+     * dropping it, so the late report is still recognized as the tour's own (not a foreign stop).
+     * Entries live only until the *current* navigation settles (report, or target resolve) or the
+     * tour tears down — bounding the window in which a genuinely foreign visit to one of these paths
+     * would be misread as ours. A plain `Set` — pure bookkeeping, never rendered, so the `SvelteSet`
+     * rule doesn't apply.
+     */
+    #supersededRoutes = new Set();
     /** Last path the tour is known to be on — set at start, updated on each handled navigation. */
     #knownPath = '';
     /** Unsubscribe from the navigation source; non-null only while a route-using tour runs. */
@@ -487,8 +499,14 @@ export class GuideController {
      */
     #maybeNavigate() {
         // Each step starts with a clean slate — no navigation is pending until we trigger one below.
-        // (A step that doesn't navigate must not inherit the previous step's `expectedRoute`.)
-        this.#expectedRoute = null;
+        // (A step that doesn't navigate must not inherit the previous step's `expectedRoute`.) A
+        // pending navigation superseded here (rapid next/prev while it was still in flight) is
+        // remembered: its report may land *after* this step activates, and must still be read as the
+        // tour's own navigation — not a foreign one that stops the tour (async epoch race).
+        if (this.#expectedRoute !== null) {
+            this.#supersededRoutes.add(this.#expectedRoute);
+            this.#expectedRoute = null;
+        }
         const route = this.currentStep?.route;
         if (route == null)
             return;
@@ -539,27 +557,53 @@ export class GuideController {
         this.#expectedRoute = null;
         this.#clearRouteTargetWarning();
     }
+    /** Does `path` look like `route`'s landing — exact, or a router-normalized form of it? */
+    #isOwnLanding(path, route) {
+        return path === route || looksLikeNormalizedRoute(path, route);
+    }
     /**
      * React to a navigation observed while a route-using tour runs. A navigation that is the tour's own
-     * — reported synchronously during our `#navigate()` call (`#selfNavigating`), or matching the
-     * pending `#expectedRoute` — keeps it running (the ring lands via the surface's
+     * — reported synchronously during our `#navigate()` call (`#selfNavigating`), matching the pending
+     * `#expectedRoute` (exactly, or as a router-normalized landing), or matching a navigation this tour
+     * triggered and then superseded — keeps it running (the ring lands via the surface's
      * `reapplyStepHighlight`). Any other navigation is foreign — the user left, or a
      * youngest-gesture-wins race — and tears the tour down, analytics-silent (`stopTour`).
      */
     #onLocationChange(path) {
         if (!this.#activeTour)
             return;
-        if (path === this.#knownPath)
-            return; // no pathname change (e.g. a hash/query update) — ignore
+        if (path === this.#knownPath) {
+            // No pathname change (a hash/query update, or a re-report of the path we're already on).
+            // A same-path report can still BE the pending navigation's landing: two consecutive steps on
+            // the same logical route under a normalizing router re-navigate without the pathname ever
+            // changing. A *targetless* step settles on landing, so clear its expectation here too —
+            // skipping that (the pre-fix behavior) armed a misleading "navigated toward …" DEV warning
+            // on the next genuine foreign navigation. (A *targeted* step keeps the expectation until its
+            // target resolves, exactly like the main own-navigation branch below.)
+            if (this.#expectedRoute !== null &&
+                this.currentStep?.target == null &&
+                (this.#selfNavigating || this.#isOwnLanding(path, this.#expectedRoute))) {
+                this.#expectedRoute = null;
+            }
+            return;
+        }
         this.#knownPath = path;
-        const matchesExpected = this.#expectedRoute !== null && path === this.#expectedRoute;
-        // A location report is the tour's OWN navigation in two cases: it matches the pending
-        // `#expectedRoute` (the async-source proxy, for a report landing a tick after the hook returns),
-        // or it arrives synchronously, re-entrant, during our injected `#navigate()` call
+        const expected = this.#expectedRoute;
+        const matchesExpected = expected !== null && path === expected;
+        // With an *async* source (the default) `#selfNavigating` is already false by the time the report
+        // lands, so recognizing the tour's own navigation falls to path matching. Exact-only matching
+        // false-stopped the tour on a router-normalized landing (`/expenses/`, `/de/expenses`) for a raw
+        // `step.route` — the async form of #41 — so a normalized-looking landing for the pending route
+        // counts as ours too (a heuristic, hence DEV-warned below; the sync path has the causal signal
+        // and stays silent).
+        const matchesNormalized = expected !== null && !matchesExpected && looksLikeNormalizedRoute(path, expected);
+        // A location report is the tour's OWN navigation when it matches the pending `#expectedRoute`
+        // (exactly or normalized — the async-source proxy, for a report landing a tick after the hook
+        // returns), or when it arrives synchronously, re-entrant, during our injected `#navigate()` call
         // (`#selfNavigating`). The latter is a *causal* signal — our navigate produced this report,
-        // whatever path it carries — so it covers a router-normalized landing (trailing slash,
-        // base/locale prefix) that an exact match would miss. Either keeps the tour running.
-        if (this.#selfNavigating || matchesExpected) {
+        // whatever path it carries — so it also covers a synchronous redirect an exact or normalized
+        // match would miss. Either keeps the tour running.
+        if (this.#selfNavigating || matchesExpected || matchesNormalized) {
             // A *synchronous* report on a path that isn't the expected route is still causally ours, but it
             // landed somewhere unexpected: a normalized variant of `step.route` (fine — the target anchors
             // once it mounts) or a genuine redirect off the route (an auth guard → `/login`). We keep
@@ -569,11 +613,20 @@ export class GuideController {
             // bubble is otherwise invisible in both DEV and PROD.)
             if (this.#dev &&
                 this.#selfNavigating &&
-                this.#expectedRoute !== null &&
+                expected !== null &&
                 !matchesExpected &&
-                !looksLikeNormalizedRoute(path, this.#expectedRoute)) {
-                console.warn(`[Guide] tour "${this.#activeTour?.id}" navigated toward "${this.#expectedRoute}" but synchronously landed on "${path}" — keeping the tour running as its own navigation. If this was a redirect off the step's route (not a normalized form of it), stop the tour explicitly from your router guard.`);
+                !matchesNormalized) {
+                console.warn(`[Guide] tour "${this.#activeTour?.id}" navigated toward "${expected}" but synchronously landed on "${path}" — keeping the tour running as its own navigation. If this was a redirect off the step's route (not a normalized form of it), stop the tour explicitly from your router guard.`);
             }
+            else if (this.#dev && !this.#selfNavigating && matchesNormalized) {
+                // The async normalized match is a guess (no causal signal) — keep running, but surface it so
+                // the consumer can make the match exact.
+                console.warn(`[Guide] tour "${this.#activeTour?.id}" navigated toward "${expected}" and landed on "${path}" — treating it as the router's normalized form of the step route and keeping the tour running. Set step.route to the router's actual landed path to make the match exact.`);
+            }
+            // The current navigation reported → any older superseded navigation can no longer report
+            // (navigation reports arrive in order), so drop those epochs — a later *foreign* visit to one
+            // of their paths must stop the tour again.
+            this.#supersededRoutes.clear();
             // For a *targeted* step, keep `#expectedRoute` set until the target settles
             // (`#applyStepHighlight`) so a redirecting / multi-hop source (the Navigation API emitting one
             // event per hop) firing a *second* event for the redirect target is still recognized as a
@@ -586,12 +639,20 @@ export class GuideController {
                 this.#expectedRoute = null;
             return;
         }
-        // Any other navigation stops the tour (analytics-silent). When one was pending, a landed path
-        // that doesn't match is most often a normalized `step.route` (trailing slash, base/locale
-        // prefix) rather than a genuine foreign nav — so surface it instead of a silent teardown on a
-        // one-character mismatch. (The strict stop is kept either way: better than running on a wrong page.)
-        if (this.#dev && this.#expectedRoute !== null) {
-            console.warn(`[Guide] tour "${this.#activeTour?.id}" navigated toward "${this.#expectedRoute}" but landed on "${path}" — stopping as a foreign navigation. If "${path}" is just a normalized form of the step's route (trailing slash, base/locale prefix), set step.route to the router's actual path.`);
+        // A late report of a navigation this tour triggered and then superseded (rapid next/prev while
+        // it was still in flight) is causally ours — keep running and keep waiting for the *current*
+        // navigation's own report. Silent: the route was recorded causally in `#maybeNavigate`; only
+        // its normalization is heuristic. (Trade-off, bounded by the in-flight window: a genuinely
+        // foreign visit to one of these paths during that window is misread as ours.)
+        for (const superseded of this.#supersededRoutes) {
+            if (this.#isOwnLanding(path, superseded))
+                return;
+        }
+        // Any other navigation stops the tour (analytics-silent). When one was pending, surface the
+        // mismatch in DEV instead of tearing down silently — with normalized landings recognized above,
+        // reaching this with a pending route means a genuinely unrelated landing (e.g. a redirect).
+        if (this.#dev && expected !== null) {
+            console.warn(`[Guide] tour "${this.#activeTour?.id}" navigated toward "${expected}" but landed on "${path}" — stopping as a foreign navigation (the landed path is not a normalized form of the step's route either).`);
         }
         this.#expectedRoute = null;
         this.stopTour();
@@ -640,6 +701,7 @@ export class GuideController {
         this.#navUnsub?.();
         this.#navUnsub = null;
         this.#expectedRoute = null;
+        this.#supersededRoutes.clear();
         this.clearHighlight();
         this.#tourUnregister?.();
         this.#tourUnregister = null;
@@ -691,6 +753,7 @@ export class GuideController {
             this.highlight(step.target, { scroll: true });
             this.#clearRouteTargetWarning(); // target landed → no "never appeared" warning needed
             this.#expectedRoute = null; // the navigated-to target resolved → navigation fully settled
+            this.#supersededRoutes.clear(); // …and with it every older, superseded navigation epoch
         }
         else {
             this.clearHighlight();