@urbicon-ui/blocks 6.8.0 → 6.8.1

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

@@ -127,6 +127,9 @@ export interface GuideNavigationSource {
      * 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;
 }

package/dist/utils/guide.svelte.js

@@ -93,6 +93,20 @@ export function createBrowserNavigationSource() {
 }
 /** 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() {
@@ -157,6 +171,21 @@ export class GuideController {
     #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. */
@@ -406,6 +435,12 @@ export class GuideController {
         }
         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') {
@@ -421,6 +456,9 @@ export class GuideController {
                 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
@@ -435,9 +473,10 @@ export class GuideController {
         this.#clearRouteTargetWarning();
     }
     /**
-     * React to a navigation observed while a route-using tour runs. A navigation matching the pending
-     * `expectedRoute` is the tour's own → clear the flag and keep running (the ring lands via the
-     * surface's `reapplyStepHighlight`). Any other navigation is foreign — the user left, or a
+     * 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) {
@@ -446,15 +485,36 @@ export class GuideController {
         if (path === this.#knownPath)
             return; // no pathname change (e.g. a hash/query update) — ignore
         this.#knownPath = path;
-        if (this.#expectedRoute !== null && path === this.#expectedRoute) {
-            // The tour's own navigation landed — keep running. 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.)
+        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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/blocks",
-  "version": "6.8.0",
+  "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.8.0",
-    "@urbicon-ui/shared-types": "6.8.0",
+    "@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",