@urbicon-ui/blocks 6.7.2 → 6.8.1

package/dist/components/Guide/GuideProvider.svelte

@@ -3,14 +3,15 @@
   import type { GuideProviderProps } from './index';
   import { setGuideContext } from './guide.context';
 
-  let { storage, controller, children }: GuideProviderProps = $props();
+  let { storage, navigate, controller, children }: GuideProviderProps = $props();
 
   // Use a consumer-supplied controller (for programmatic access from outside the provider)
   // or create one. Built once from the initial props — a stable controller/adapter is
   // expected, so later prop changes are intentionally ignored. SSR-safe: the default
-  // adapter only touches localStorage inside load/save.
+  // adapter only touches localStorage inside load/save. `storage`/`navigate` are ignored
+  // when a `controller` is supplied (it already carries them).
   // svelte-ignore state_referenced_locally
-  const instance = controller ?? new GuideController({ storage });
+  const instance = controller ?? new GuideController({ storage, navigate });
   setGuideContext(instance);
 </script>
 

package/dist/components/Guide/index.d.ts

@@ -30,10 +30,17 @@ import type { GuideArticleSlots, GuideBeaconSlots, GuideBeaconVariants, GuideHin
 export interface GuideProviderProps {
     /** Persistence adapter for "seen" state (tours/hints). @default localStorage-backed adapter */
     storage?: GuideStorageAdapter;
+    /**
+     * Navigation hook for declarative cross-route tours, forwarded to the internally created
+     * controller. A SvelteKit consumer wires `(route) => goto(route)`; a step's `route` then
+     * navigates before its spotlight. Ignored when a `controller` is supplied (set it there).
+     * @default undefined
+     */
+    navigate?: (route: string) => void | Promise<void>;
     /**
      * Supply a pre-created `GuideController` for programmatic access from outside the provider
      * (start tours, open the panel, query `hasSeen`). When omitted, the provider creates one
-     * internally and shares it via context. When supplied, `storage` is ignored.
+     * internally and shares it via context. When supplied, `storage` and `navigate` are ignored.
      */
     controller?: GuideController;
     /** App subtree wired to the Guide context. */

package/dist/i18n/index.d.ts

@@ -343,177 +343,7 @@ declare const blocksTranslations: {
         };
     };
 };
-export declare const blocksI18n: import("@urbicon-ui/i18n").PackageI18n<{
-    readonly accessibility: {
-        readonly avatar: "Avatar";
-        readonly clearInput: "Clear input";
-        readonly clearSearch: "Clear search";
-        readonly clearSelection: "Clear selection";
-        readonly closeDialog: "Close dialog";
-        readonly closeDrawer: "Close drawer";
-        readonly dismiss: "Dismiss";
-        readonly fileUpload: "File upload";
-        readonly loading: "Loading";
-        readonly maximum: "Maximum";
-        readonly minimum: "Minimum";
-        readonly pagination: "Page navigation";
-        readonly progress: "Progress";
-        readonly slider: "Slider";
-        readonly toggle: "Toggle";
-        readonly toggleOptions: "Toggle options";
-        readonly removableBadge: "Removable badge";
-        readonly removeBadge: "Remove badge";
-        readonly removeFile: "Remove {{name}}";
-    };
-    readonly button: {
-        readonly close: "Close";
-        readonly apply: "Apply";
-        readonly cancel: "Cancel";
-        readonly confirm: "Confirm";
-    };
-    readonly menu: {
-        readonly placeholder: "Select an option...";
-    };
-    readonly common: {
-        readonly loading: "Loading...";
-    };
-    readonly languages: {
-        readonly de: "Deutsch";
-        readonly en: "English";
-        readonly es: "Español";
-        readonly fr: "Français";
-        readonly it: "Italiano";
-        readonly nl: "Nederlands";
-    };
-    readonly localeSwitcher: {
-        readonly ariaLabel: "Language selection";
-        readonly placeholder: "Select language...";
-    };
-    readonly pagination: {
-        readonly next: "Next";
-        readonly first: "First";
-        readonly last: "Last";
-        readonly page: "Page";
-        readonly previous: "Previous";
-    };
-    readonly calendar: {
-        readonly recurring: "Recurring event";
-        readonly previousMonth: "Previous month";
-        readonly nextMonth: "Next month";
-        readonly previousWeek: "Previous week";
-        readonly nextWeek: "Next week";
-        readonly previousDay: "Previous day";
-        readonly nextDay: "Next day";
-        readonly previousYear: "Previous year";
-        readonly nextYear: "Next year";
-        readonly today: "Today";
-        readonly calendarGrid: "Calendar";
-        readonly weekdays: "Weekdays";
-        readonly weekNumber: "Week number";
-        readonly events: "Events";
-        readonly noEvents: "No events";
-        readonly showMore: "{{count}} more";
-        readonly legend: "Legend";
-        readonly yearView: "Year overview";
-        readonly weekView: "Week view";
-        readonly dayView: "Day view";
-        readonly monthView: "Month view";
-        readonly viewMonth: "Month";
-        readonly viewYear: "Year";
-        readonly viewWeek: "Week";
-        readonly viewDay: "Day";
-        readonly multiDayLabel: "Day {{current}} of {{total}}";
-        readonly agendaView: "Agenda view";
-        readonly viewAgenda: "Agenda";
-        readonly viewSwitcher: "View mode";
-    };
-    readonly planner: {
-        readonly previousWeek: "Previous week";
-        readonly nextWeek: "Next week";
-        readonly previousMonth: "Previous month";
-        readonly nextMonth: "Next month";
-        readonly previousRange: "Previous range";
-        readonly nextRange: "Next range";
-        readonly today: "Today";
-        readonly grid: "Planner";
-        readonly weekNumber: "Week number";
-        readonly itemCount: "{{count}} items";
-    };
-    readonly commandPalette: {
-        readonly noResults: "No results found.";
-        readonly search: "Search...";
-        readonly hints: {
-            readonly navigate: "Navigate";
-            readonly select: "Select";
-            readonly close: "Close";
-        };
-    };
-    readonly compositionBar: {
-        readonly total: "Total";
-        readonly summary: "Composition: {{total}} ({{count}} shares) — {{parts}}";
-        readonly share: "Share";
-        readonly value: "Value";
-        readonly percent: "Percent";
-        readonly remaining: "remaining";
-    };
-    readonly guide: {
-        readonly next: "Next";
-        readonly previous: "Back";
-        readonly skip: "Skip tour";
-        readonly done: "Done";
-        readonly step: "Step {{current}} of {{total}}";
-        readonly tour: "Guided tour";
-        readonly close: "Close";
-        readonly openHelp: "Help";
-        readonly backToList: "All topics";
-        readonly info: "More information";
-        readonly infoAbout: "More information about {{label}}";
-        readonly dismiss: "Dismiss hint";
-        readonly startTour: "Start the guided tour";
-        readonly actionRequired: "Complete the highlighted action to continue";
-        readonly filterPlaceholder: "Filter topics…";
-        readonly noResults: "No matching topics";
-    };
-    readonly datepicker: {
-        readonly placeholder: "Select a date...";
-        readonly rangePlaceholder: "Select a date range...";
-        readonly clear: "Clear selection";
-        readonly openCalendar: "Open calendar";
-        readonly invalidDate: "Invalid date";
-        readonly outOfRange: "Date is outside the allowed range";
-        readonly invalidRange: "Invalid date range";
-    };
-    readonly fileUpload: {
-        readonly exists: "File already added";
-        readonly invalidType: "File type {{type}} is not allowed";
-        readonly tooLarge: "File exceeds {{size}} limit";
-        readonly tooMany: "Maximum {{count}} files allowed";
-        readonly tooSmall: "File must be at least {{size}}";
-    };
-    readonly sankey: {
-        readonly summary: "Sankey diagram: {{nodes}} nodes, {{links}} links — {{flows}}";
-        readonly source: "Source";
-        readonly target: "Target";
-        readonly value: "Value";
-    };
-    readonly slider: {
-        readonly rangeStatus: {
-            readonly insideRecommended: "In recommended range";
-            readonly insideValid: "In valid range";
-            readonly insideValidOnly: "Outside recommended range, but valid";
-            readonly outsideValid: "Outside valid range";
-        };
-    };
-    readonly themeSwitcher: {
-        readonly lightMode: "Light mode";
-        readonly darkMode: "Dark mode";
-        readonly systemTheme: "System theme";
-    };
-    readonly time: {
-        readonly ago: "{{value}} {{unit}} ago";
-        readonly now: "now";
-    };
-}>;
+export declare const blocksI18n: import("@urbicon-ui/i18n").PackageI18n<import("@urbicon-ui/i18n").Translations>;
 /**
  * Context-scoped translation hook for the blocks package. Call during component
  * initialisation, then use the returned `t` (conventionally aliased `bt`):
@@ -526,177 +356,7 @@ export declare const blocksI18n: import("@urbicon-ui/i18n").PackageI18n<{
  * Resolves against the nearest `<I18nProvider>`'s locale (or the base locale
  * when none is mounted) and re-renders reactively on locale change.
  */
-export declare const useBlocksI18n: () => import("@urbicon-ui/i18n").TypedTranslationFunction<{
-    readonly accessibility: {
-        readonly avatar: "Avatar";
-        readonly clearInput: "Clear input";
-        readonly clearSearch: "Clear search";
-        readonly clearSelection: "Clear selection";
-        readonly closeDialog: "Close dialog";
-        readonly closeDrawer: "Close drawer";
-        readonly dismiss: "Dismiss";
-        readonly fileUpload: "File upload";
-        readonly loading: "Loading";
-        readonly maximum: "Maximum";
-        readonly minimum: "Minimum";
-        readonly pagination: "Page navigation";
-        readonly progress: "Progress";
-        readonly slider: "Slider";
-        readonly toggle: "Toggle";
-        readonly toggleOptions: "Toggle options";
-        readonly removableBadge: "Removable badge";
-        readonly removeBadge: "Remove badge";
-        readonly removeFile: "Remove {{name}}";
-    };
-    readonly button: {
-        readonly close: "Close";
-        readonly apply: "Apply";
-        readonly cancel: "Cancel";
-        readonly confirm: "Confirm";
-    };
-    readonly menu: {
-        readonly placeholder: "Select an option...";
-    };
-    readonly common: {
-        readonly loading: "Loading...";
-    };
-    readonly languages: {
-        readonly de: "Deutsch";
-        readonly en: "English";
-        readonly es: "Español";
-        readonly fr: "Français";
-        readonly it: "Italiano";
-        readonly nl: "Nederlands";
-    };
-    readonly localeSwitcher: {
-        readonly ariaLabel: "Language selection";
-        readonly placeholder: "Select language...";
-    };
-    readonly pagination: {
-        readonly next: "Next";
-        readonly first: "First";
-        readonly last: "Last";
-        readonly page: "Page";
-        readonly previous: "Previous";
-    };
-    readonly calendar: {
-        readonly recurring: "Recurring event";
-        readonly previousMonth: "Previous month";
-        readonly nextMonth: "Next month";
-        readonly previousWeek: "Previous week";
-        readonly nextWeek: "Next week";
-        readonly previousDay: "Previous day";
-        readonly nextDay: "Next day";
-        readonly previousYear: "Previous year";
-        readonly nextYear: "Next year";
-        readonly today: "Today";
-        readonly calendarGrid: "Calendar";
-        readonly weekdays: "Weekdays";
-        readonly weekNumber: "Week number";
-        readonly events: "Events";
-        readonly noEvents: "No events";
-        readonly showMore: "{{count}} more";
-        readonly legend: "Legend";
-        readonly yearView: "Year overview";
-        readonly weekView: "Week view";
-        readonly dayView: "Day view";
-        readonly monthView: "Month view";
-        readonly viewMonth: "Month";
-        readonly viewYear: "Year";
-        readonly viewWeek: "Week";
-        readonly viewDay: "Day";
-        readonly multiDayLabel: "Day {{current}} of {{total}}";
-        readonly agendaView: "Agenda view";
-        readonly viewAgenda: "Agenda";
-        readonly viewSwitcher: "View mode";
-    };
-    readonly planner: {
-        readonly previousWeek: "Previous week";
-        readonly nextWeek: "Next week";
-        readonly previousMonth: "Previous month";
-        readonly nextMonth: "Next month";
-        readonly previousRange: "Previous range";
-        readonly nextRange: "Next range";
-        readonly today: "Today";
-        readonly grid: "Planner";
-        readonly weekNumber: "Week number";
-        readonly itemCount: "{{count}} items";
-    };
-    readonly commandPalette: {
-        readonly noResults: "No results found.";
-        readonly search: "Search...";
-        readonly hints: {
-            readonly navigate: "Navigate";
-            readonly select: "Select";
-            readonly close: "Close";
-        };
-    };
-    readonly compositionBar: {
-        readonly total: "Total";
-        readonly summary: "Composition: {{total}} ({{count}} shares) — {{parts}}";
-        readonly share: "Share";
-        readonly value: "Value";
-        readonly percent: "Percent";
-        readonly remaining: "remaining";
-    };
-    readonly guide: {
-        readonly next: "Next";
-        readonly previous: "Back";
-        readonly skip: "Skip tour";
-        readonly done: "Done";
-        readonly step: "Step {{current}} of {{total}}";
-        readonly tour: "Guided tour";
-        readonly close: "Close";
-        readonly openHelp: "Help";
-        readonly backToList: "All topics";
-        readonly info: "More information";
-        readonly infoAbout: "More information about {{label}}";
-        readonly dismiss: "Dismiss hint";
-        readonly startTour: "Start the guided tour";
-        readonly actionRequired: "Complete the highlighted action to continue";
-        readonly filterPlaceholder: "Filter topics…";
-        readonly noResults: "No matching topics";
-    };
-    readonly datepicker: {
-        readonly placeholder: "Select a date...";
-        readonly rangePlaceholder: "Select a date range...";
-        readonly clear: "Clear selection";
-        readonly openCalendar: "Open calendar";
-        readonly invalidDate: "Invalid date";
-        readonly outOfRange: "Date is outside the allowed range";
-        readonly invalidRange: "Invalid date range";
-    };
-    readonly fileUpload: {
-        readonly exists: "File already added";
-        readonly invalidType: "File type {{type}} is not allowed";
-        readonly tooLarge: "File exceeds {{size}} limit";
-        readonly tooMany: "Maximum {{count}} files allowed";
-        readonly tooSmall: "File must be at least {{size}}";
-    };
-    readonly sankey: {
-        readonly summary: "Sankey diagram: {{nodes}} nodes, {{links}} links — {{flows}}";
-        readonly source: "Source";
-        readonly target: "Target";
-        readonly value: "Value";
-    };
-    readonly slider: {
-        readonly rangeStatus: {
-            readonly insideRecommended: "In recommended range";
-            readonly insideValid: "In valid range";
-            readonly insideValidOnly: "Outside recommended range, but valid";
-            readonly outsideValid: "Outside valid range";
-        };
-    };
-    readonly themeSwitcher: {
-        readonly lightMode: "Light mode";
-        readonly darkMode: "Dark mode";
-        readonly systemTheme: "System theme";
-    };
-    readonly time: {
-        readonly ago: "{{value}} {{unit}} ago";
-        readonly now: "now";
-    };
-}>;
+export declare const useBlocksI18n: any;
 export declare const hasBlocksTranslation: (key: string) => boolean, getBlocksLocales: () => import("@urbicon-ui/i18n").Locale[];
 export type BlocksTranslationKey = keyof typeof enTranslations;
 export { blocksTranslations };

package/dist/utils/guide.svelte.d.ts

@@ -15,6 +15,18 @@ export interface GuideTopicMeta {
 export interface GuideStep {
     /** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
     target?: string;
+    /**
+     * Optional route this step lives on — declarative cross-route touring. When set and different
+     * from the current location, the controller calls its injected `navigate` hook to go there
+     * **before** the spotlight, then re-anchors once the target appears on the new page (via the
+     * surface's existing `reapplyStepHighlight`). Such a tour-internal navigation keeps the tour
+     * running; a *foreign* navigation (the user leaving on their own) still stops it. Compared
+     * against `window.location.pathname` by default, so use a normalized path (no query/hash);
+     * inject a {@link GuideControllerOptions.navigationSource} for a custom router or base path.
+     * A `route` step with no `navigate` hook wired logs a DEV warning and stays put (no crash).
+     * @see GuideControllerOptions.navigate
+     */
+    route?: string;
     /** Step heading. */
     title?: string;
     /** Step body text. */
@@ -103,12 +115,48 @@ export interface GuideOverlayStackLike {
     /** Number of modal overlays currently open — drives the non-modal hide (§3.4). */
     readonly depth: number;
 }
+/**
+ * Source of the current route and navigation notifications the controller needs for cross-route
+ * tours (injectable for tests and custom routers). The default {@link createBrowserNavigationSource}
+ * reads `window.location.pathname` and subscribes via the Navigation API, falling back to `popstate`.
+ */
+export interface GuideNavigationSource {
+    /** The current path, compared against a step's `route` (e.g. `"/expenses"`). `''` on the server. */
+    current(): string;
+    /**
+     * Subscribe to navigations; `onNavigate` receives the new path. Returns an unsubscribe. The
+     * controller subscribes only while a tour with at least one `route` step is active, so a tour
+     * that never declares a route observes no navigation (preserving the manual-`goto` recipe).
+     * `onNavigate` may be invoked **synchronously, re-entrant** during the controller's own `navigate`
+     * hook (a SvelteKit `afterNavigate` source fires inside `goto`); the controller recognizes that as
+     * the tour's own navigation and keeps it running, so the source needs no `queueMicrotask` deferral.
+     */
+    subscribe(onNavigate: (path: string) => void): () => void;
+}
 /** Options for {@link GuideController}; every dependency is injectable for testing. */
 export interface GuideControllerOptions {
     /** Persistence adapter. @default localStorage-backed adapter */
     storage?: GuideStorageAdapter;
     /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
     overlayStack?: GuideOverlayStackLike;
+    /**
+     * Navigation hook for declarative cross-route tours. When a step's `route` differs from the
+     * current location, the controller calls this to navigate there before spotlighting the step.
+     * Framework-agnostic by injection — a SvelteKit consumer wires `(route) => goto(route)`. May be
+     * sync or async; a thrown/rejected navigation is swallowed (DEV-warned). A `route` step with no
+     * hook wired logs a DEV warning and stays on the current route (no crash). @default undefined
+     */
+    navigate?: (route: string) => void | Promise<void>;
+    /**
+     * Source for the current path + navigation events, used to decide whether a step's `route`
+     * needs navigating and to tell a tour-internal navigation from a foreign one (which stops the
+     * tour). @default a browser source reading `window.location.pathname` and listening via the
+     * Navigation API. Where that API is unavailable it falls back to `popstate` (back/forward only,
+     * not `pushState`), so a foreign *forward* navigation may go unobserved — inject a router-backed
+     * source (SvelteKit: `afterNavigate` + the `page` store; see docs/GUIDE.md §9) for reliable
+     * detection, or to handle a configured base path / custom router.
+     */
+    navigationSource?: GuideNavigationSource;
     /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
     dev?: boolean;
 }
@@ -117,6 +165,13 @@ export interface GuideControllerOptions {
  * resilient to private-mode / quota failures (mirrors `persistent-state`).
  */
 export declare function createLocalStorageAdapter(key?: string): GuideStorageAdapter;
+/**
+ * The default {@link GuideNavigationSource}: reads `window.location.pathname` and observes SPA
+ * navigations through the Navigation API when available — catching link clicks, programmatic
+ * navigation (`goto`), and back/forward — falling back to `popstate` (back/forward only) where it
+ * is not. SSR-safe: `current()` returns `''` and `subscribe()` is a no-op without a `window`.
+ */
+export declare function createBrowserNavigationSource(): GuideNavigationSource;
 /**
  * Headless engine for the Guide system — the UI-free state machine behind every
  * Guide surface (Panel, Marker, Mention, Hint, Tour).

package/dist/utils/guide.svelte.js

@@ -42,6 +42,71 @@ export function createLocalStorageAdapter(key = SEEN_STORAGE_KEY) {
         }
     };
 }
+/**
+ * The default {@link GuideNavigationSource}: reads `window.location.pathname` and observes SPA
+ * navigations through the Navigation API when available — catching link clicks, programmatic
+ * navigation (`goto`), and back/forward — falling back to `popstate` (back/forward only) where it
+ * is not. SSR-safe: `current()` returns `''` and `subscribe()` is a no-op without a `window`.
+ */
+export function createBrowserNavigationSource() {
+    let warnedFallback = false;
+    return {
+        current() {
+            return BROWSER ? window.location.pathname : '';
+        },
+        subscribe(onNavigate) {
+            if (!BROWSER)
+                return () => { };
+            const nav = window.navigation;
+            if (nav && typeof nav.addEventListener === 'function') {
+                const handler = (event) => {
+                    if (event.downloadRequest != null)
+                        return; // a download is not a route change
+                    const url = event.destination?.url;
+                    if (typeof url !== 'string')
+                        return;
+                    let path;
+                    try {
+                        path = new URL(url).pathname;
+                    }
+                    catch {
+                        return; // opaque/cross-origin destination — not a same-app route
+                    }
+                    onNavigate(path);
+                };
+                nav.addEventListener('navigate', handler);
+                return () => nav.removeEventListener('navigate', handler);
+            }
+            // `popstate` only catches back/forward, not `pushState` (a SvelteKit `goto` / intercepted
+            // link click), so a foreign *forward* navigation goes unobserved and the tour won't stop.
+            // Warn once so a degraded-detection browser is diagnosable; inject a router-backed
+            // navigationSource for reliable detection (docs/GUIDE.md §9).
+            if (import.meta.env?.DEV && !warnedFallback) {
+                warnedFallback = true;
+                console.warn('[Guide] the Navigation API is unavailable; cross-route foreign-navigation detection falls back to popstate and will miss pushState navigations (link clicks, goto). Inject a router-backed navigationSource for reliable detection — see docs/GUIDE.md §9.');
+            }
+            const onPop = () => onNavigate(window.location.pathname);
+            window.addEventListener('popstate', onPop);
+            return () => window.removeEventListener('popstate', onPop);
+        }
+    };
+}
+/** DEV-only: grace period for a navigated-to `route` step's target before warning it never showed. */
+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`.
+ */
+function looksLikeNormalizedRoute(landed, route) {
+    const stripSlash = (s) => (s.length > 1 && s.endsWith('/') ? s.slice(0, -1) : s);
+    const l = stripSlash(landed);
+    const r = stripSlash(route);
+    return l === r || l.endsWith(r);
+}
 let tourIdCounter = 0;
 /** Opaque id for overlay-stack registration. Never SSR-rendered, so no hydration risk. */
 function nextOverlayId() {
@@ -101,6 +166,32 @@ export class GuideController {
     // independently of #activeTour (today they always change in lockstep).
     #tourOverlayId = $state(null);
     #tourUnregister = null;
+    // ── Cross-route touring ─────────────────────────────────
+    #navigate;
+    #navSource;
+    /** The path a tour-internal navigation is heading to; distinguishes our own nav from a foreign one. */
+    #expectedRoute = null;
+    /**
+     * `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`.
+     *
+     * 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*
+     * re-enters `next`/`prev`/`startTour` is out of contract — its inner `#maybeNavigate` `finally`
+     * would clear this early; that only ever fails *closed* (a later own report read as foreign → stop),
+     * never open, so it can't keep a genuinely foreign navigation alive.
+     */
+    #selfNavigating = false;
+    /** 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. */
+    #navUnsub = null;
+    /** DEV-only timer that warns when a navigated-to step's target never appears. */
+    #routeTargetTimer = null;
     // ── Highlight (shared by tour steps + Mention→UI, Direction B) ──
     #highlightedId = $state(null);
     // ── Panel state (UI in Phase 3) ─────────────────────────
@@ -112,6 +203,8 @@ export class GuideController {
     constructor(options = {}) {
         this.#storage = options.storage ?? createLocalStorageAdapter();
         this.#overlayStack = options.overlayStack ?? overlayStack;
+        this.#navigate = options.navigate;
+        this.#navSource = options.navigationSource ?? createBrowserNavigationSource();
         // `import.meta.env?.DEV` is `boolean | undefined` (undefined outside Vite);
         // `?? false` keeps `#dev` a strict boolean and means non-Vite consumers
         // simply get no dev warnings (rather than a crash).
@@ -240,8 +333,14 @@ export class GuideController {
         this.#stepIndex = 0;
         this.#tourOverlayId = nextOverlayId();
         this.#tourUnregister = this.#overlayStack.register(this.#tourOverlayId, () => this.skip());
-        this.#applyStepHighlight();
-        this.#emitStep('start');
+        // Observe navigation only for tours that declare a step route. This keeps the manual-`goto`
+        // recipe (consumer navigates in `onStep`, no `step.route`) untouched, where a navigation is
+        // the consumer's own and must NOT be read as a foreign one that stops the tour.
+        this.#knownPath = this.#navSource.current();
+        if (tour.steps.some((s) => typeof s.route === 'string')) {
+            this.#navUnsub = this.#navSource.subscribe((path) => this.#onLocationChange(path));
+        }
+        this.#activateStep('start');
         return true;
     }
     /** Advance to the next step, or finish the tour if on the last step. */
@@ -253,16 +352,14 @@ export class GuideController {
             return;
         }
         this.#stepIndex += 1;
-        this.#applyStepHighlight();
-        this.#emitStep('next');
+        this.#activateStep('next');
     }
     /** Go back one step. No-op on the first step. */
     prev() {
         if (!this.#activeTour || this.isFirstStep)
             return;
         this.#stepIndex -= 1;
-        this.#applyStepHighlight();
-        this.#emitStep('prev');
+        this.#activateStep('prev');
     }
     /** Dismiss the tour without completing it — marks it seen, fires `onSkip`. */
     skip() {
@@ -304,6 +401,163 @@ export class GuideController {
         if (this.#activeTour)
             this.#applyStepHighlight();
     }
+    // ─── Cross-route touring ──────────────────────────────────────────────────
+    /**
+     * Make the now-current step active: trigger its cross-route navigation (if any), apply the
+     * highlight, then fire `onStep`. Shared by `startTour`/`next`/`prev`, so every entry point
+     * navigates symmetrically — including `prev()` stepping back across a route boundary.
+     */
+    #activateStep(via) {
+        this.#clearRouteTargetWarning();
+        this.#maybeNavigate();
+        this.#applyStepHighlight();
+        this.#emitStep(via);
+    }
+    /**
+     * If the active step lives on a different route, navigate there via the injected hook and record
+     * it as the `expectedRoute`, so the resulting navigation is recognized as the tour's own rather
+     * than a foreign one. Already on the route → nothing to do. No hook wired → DEV warning, stay put.
+     */
+    #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;
+        const route = this.currentStep?.route;
+        if (route == null)
+            return;
+        if (route === this.#navSource.current())
+            return;
+        if (!this.#navigate) {
+            if (this.#dev) {
+                console.warn(`[Guide] tour "${this.#activeTour?.id}" step ${this.#stepIndex}: step has route "${route}" but no navigate hook was provided to the GuideController — staying on the current route.`);
+            }
+            return;
+        }
+        this.#expectedRoute = route;
+        this.#scheduleRouteTargetWarning();
+        // Mark the window during which a synchronous (re-entrant) location report from the
+        // navigationSource is unambiguously our own navigation. Reset in `finally` the instant the
+        // (sync part of the) hook returns — an *async* report (the default Navigation-API source, or a
+        // microtask-deferred one) then falls through to the normal `#expectedRoute` matching, so the
+        // async path is unchanged.
+        this.#selfNavigating = true;
+        try {
+            const result = this.#navigate(route);
+            if (result && typeof result.then === 'function') {
+                result.catch((err) => {
+                    if (this.#dev)
+                        console.warn('[Guide] navigate hook rejected:', err);
+                    this.#abortPendingNavigation(route);
+                });
+            }
+        }
+        catch (err) {
+            if (this.#dev)
+                console.warn('[Guide] navigate hook threw:', err);
+            this.#abortPendingNavigation(route);
+        }
+        finally {
+            this.#selfNavigating = false;
+        }
+    }
+    /**
+     * Roll back the bookkeeping for a navigation that failed (hook threw/rejected) — but only if it
+     * is still the pending one, so a newer step's navigation (the user clicked Next while this hook
+     * was in flight) is never clobbered by a late rejection. Clears the now-meaningless "target never
+     * appeared" timer too, so it can't later fire a misleading warning for a navigation that never ran.
+     */
+    #abortPendingNavigation(route) {
+        if (this.#expectedRoute !== route)
+            return;
+        this.#expectedRoute = null;
+        this.#clearRouteTargetWarning();
+    }
+    /**
+     * 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
+     * `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
+        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
+        // (`#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) {
+            // 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
+            // running either way — stopping would re-break the normalized case this fix exists for — but a
+            // landing that doesn't even look like a normalized variant is most likely a redirect, so
+            // surface it in DEV. (A targetless step has no "target never appeared" timer, so an off-route
+            // bubble is otherwise invisible in both DEV and PROD.)
+            if (this.#dev &&
+                this.#selfNavigating &&
+                this.#expectedRoute !== 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.`);
+            }
+            // 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
+            // mismatch (and DEV-warned) instead of silently stopping. A *targetless* route step has no
+            // target to wait for — it is settled on landing, so clear now; otherwise a later foreign
+            // navigation would misfire the "navigated toward …" warning. (`#maybeNavigate` also resets it
+            // on the next step. Clearing here can't move into `#applyStepHighlight`, which runs
+            // synchronously in `#activateStep` before the nav lands — it would mis-read our own nav.)
+            if (this.currentStep?.target == null)
+                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.`);
+        }
+        this.#expectedRoute = null;
+        this.stopTour();
+    }
+    /**
+     * DEV-only: after navigating for a `route` step, warn if its target never appears so the spotlight
+     * can't land (the step still renders, centered over the scrim — it never hangs). Browser-gated, so
+     * no timer is ever scheduled under SSR or in node tests.
+     */
+    #scheduleRouteTargetWarning() {
+        if (!this.#dev || !BROWSER)
+            return;
+        const step = this.currentStep;
+        if (!step?.target)
+            return;
+        this.#clearRouteTargetWarning();
+        const index = this.#stepIndex;
+        const targetId = step.target;
+        const route = step.route;
+        this.#routeTargetTimer = setTimeout(() => {
+            this.#routeTargetTimer = null;
+            if (this.#stepIndex === index && !this.resolveTarget(targetId)) {
+                console.warn(`[Guide] tour "${this.#activeTour?.id}" step ${index}: navigated to "${route}" but target "${targetId}" never appeared — showing the step without a spotlight ring.`);
+            }
+        }, ROUTE_TARGET_TIMEOUT_MS);
+    }
+    /** Cancel a pending route-target warning (target appeared, the step changed, or teardown). */
+    #clearRouteTargetWarning() {
+        if (this.#routeTargetTimer !== null) {
+            clearTimeout(this.#routeTargetTimer);
+            this.#routeTargetTimer = null;
+        }
+    }
     #endTour() {
         const tour = this.#activeTour;
         this.#teardownTour();
@@ -313,8 +567,12 @@ export class GuideController {
         if (tour && tour.once !== false)
             this.markSeen(tour.id);
     }
-    /** Reset all tour state and release the overlay-stack registration. No persistence. */
+    /** Reset all tour state and release the overlay-stack + navigation registrations. No persistence. */
     #teardownTour() {
+        this.#clearRouteTargetWarning();
+        this.#navUnsub?.();
+        this.#navUnsub = null;
+        this.#expectedRoute = null;
         this.clearHighlight();
         this.#tourUnregister?.();
         this.#tourUnregister = null;
@@ -364,10 +622,16 @@ export class GuideController {
             // Unlike Direction-B hover (which never scrolls), a tour drives the viewport —
             // the scroll is reduced-motion-aware inside `highlight`.
             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
         }
         else {
             this.clearHighlight();
-            if (this.#dev) {
+            // A step bound to another route legitimately has no target on the current page — during the
+            // navigation gap, or when no navigate hook is wired — so don't warn "not found" there; the
+            // missing-hook and never-appeared paths own those diagnostics instead.
+            const offRoute = step.route != null && step.route !== this.#navSource.current();
+            if (this.#dev && !offRoute) {
                 console.warn(`[Guide] tour "${this.#activeTour?.id}" step ${this.#stepIndex}: target "${step.target}" not found in DOM.`);
             }
         }

package/dist/utils/index.d.ts

@@ -2,7 +2,7 @@ export * from './date.js';
 export * from './draggable.js';
 export * from './figma-token-export.js';
 export { arrow, autoUpdate, type ComputePositionReturn, computePosition, flip, type Middleware, offset, type Placement, type Strategy, shift, size } from './floating.js';
-export { createLocalStorageAdapter, GuideController, type GuideControllerOptions, type GuideDirection, type GuideEndEvent, type GuideOverlayStackLike, type GuideStep, type GuideStepEvent, type GuideStorageAdapter, type GuideTopicMeta, type GuideTour } from './guide.svelte.js';
+export { createBrowserNavigationSource, createLocalStorageAdapter, GuideController, type GuideControllerOptions, type GuideDirection, type GuideEndEvent, type GuideNavigationSource, type GuideOverlayStackLike, type GuideStep, type GuideStepEvent, type GuideStorageAdapter, type GuideTopicMeta, type GuideTour } from './guide.svelte.js';
 export * from './id.js';
 export { observeTargetResolution } from './observe-target.js';
 export { createOptionalContext } from './optional-context.js';

package/dist/utils/index.js

@@ -2,7 +2,7 @@ export * from './date.js';
 export * from './draggable.js';
 export * from './figma-token-export.js';
 export { arrow, autoUpdate, computePosition, flip, offset, shift, size } from './floating.js';
-export { createLocalStorageAdapter, GuideController } from './guide.svelte.js';
+export { createBrowserNavigationSource, createLocalStorageAdapter, GuideController } from './guide.svelte.js';
 export * from './id.js';
 export { observeTargetResolution } from './observe-target.js';
 export { createOptionalContext } from './optional-context.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/blocks",
-  "version": "6.7.2",
+  "version": "6.8.1",
   "description": "Svelte 5 UI component library with Tailwind CSS 4, OKLCH design tokens and zero runtime dependencies",
   "license": "MIT",
   "repository": {
@@ -91,8 +91,8 @@
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@tailwindcss/vite": "^4.3.1",
-    "@urbicon-ui/i18n": "6.7.2",
-    "@urbicon-ui/shared-types": "6.7.2",
+    "@urbicon-ui/i18n": "6.8.1",
+    "@urbicon-ui/shared-types": "6.8.1",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",