@wildo-ai/saas-frontend-lib 1.1.5 → 1.1.6

package/dist/esm/core/navigation/useNavigationRouterSync.js

@@ -0,0 +1,977 @@
+/**
+ * URL RECONCILIATION: what a browser URL means for the zone state.
+ *
+ * Six hooks, one invariant — **the URL names exactly one zone's content, and the zones around it are
+ * reconstructed from that**. They cover the deep link and refresh (`useRouterSync`,
+ * `useViewRouterSync`, `useEnginePageRouterSync`), the browser's own back and forward across
+ * structural zones (`useStructuralZoneBackForwardSync`), the `?pane=` hosted pane
+ * (`useHostedPaneRouteSync`) and the settings-hub overlay (`useSettingsHubOverlaySync`).
+ *
+ * Split out of `useNavigationController.ts` on 2026-09-25. That module held the click path and this
+ * one in 2,322 lines, and reasoning about either in isolation meant holding both; the seam was
+ * measured rather than guessed — this half used exactly THREE symbols from the other (`logDebug` and
+ * the two cascade functions), which is what made the split worth doing.
+ *
+ * Nothing here decides a PLACEMENT POLICY. Where content goes is `navigationPolicyResolver`'s
+ * answer, read through `NavigationUtils.resolveResourceTargetZone`; these hooks decide only which
+ * content the URL is currently naming and what has to be rebuilt around it.
+ */
+import { useMemo, useEffect, useRef, } from 'react';
+import { useLocation, useParams, } from 'react-router-dom';
+import { useEventBus } from '../../core/events/useEventBus.js';
+import { useNavigationState } from './useNavigationState.js';
+import { useUI } from '../../core/ui/useUI.js';
+import { useAppScopeSafe } from '../../core/scope/useAppScope.js';
+import { ScopeUtilsService } from '../../core/scope/scope.utils.frontend.service.js';
+import { extractChartRouteContextResourceIdentifiers, extractChartRouteUrlParamValues, } from '../../core/config/chart-view.frontend.schemas.js';
+import { extractCompositeRouteContextResourceIdentifiers, } from '../../core/config/composite-view.schemas.js';
+import { extractExecutionRouteContextResourceIdentifiers, resolveExecutionViewDefinition, } from '../../core/config/execution-view.schemas.js';
+import { FrontendEvents, } from '../../core/events/events.frontend.schemas.js';
+import { NavigationZone, NavigationContentType, NAVIGATION_STRUCTURAL_ZONES, } from './navigation.schemas.js';
+import { NavigationTransition, NavigationZoneName, OverlayAppearance, ResourcesConfigOperationsUrlsBuilderUtils, } from '@wildo-ai/saas-models';
+import { useResourceRegistry } from '../../core/resources/useResourceRegistry.js';
+import { NavigationSource } from './navigation.schemas.js';
+import { NavigationUtils } from './navigation.utils.js';
+import { useTransactionAwareSyncRetry } from './useTransactionAwareSyncRetry.js';
+import { useRouterLocationAheadOfCommit, useSynchronousBrowserLocation } from './useSynchronousBrowserLocation.js';
+import { CommonRoutePaths } from '../../core/runtime/routes.frontend.definitions.js';
+import { FrontendResourceUtils, frontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
+import { normalizeContextResourceIdentifiersForTransport } from '../../core/resources/context-resource-identifiers.frontend.utils.js';
+import { adjacentZoneUsableAtViewport } from './zone-collapse.js';
+import { logDebug } from './navigation-controller-internals.js';
+import { cascadeAncestorZones, cascadeSiblingListIntoPrimary } from './navigation-cascade.js';
+// ================================
+// Router Sync Hook (merged from RouterNavigationSync)
+// ================================
+/**
+ * Hook to sync React Router URL changes with navigation state.
+ *
+ * When a user navigates via URL (bookmark, direct link, refresh),
+ * this hook ensures the navigation state is updated accordingly.
+ *
+ * Uses NavigationSource to detect controller-initiated navigation:
+ * - If top entry has source=CONTROLLER and matches current URL, skip sync
+ * - Otherwise, this is an external URL change, sync it with source=URL_SYNC
+ *
+ * @param resourceType - The resource type for the current route
+ * @param operation - The operation configuration
+ * @param routePathParameters - Route path parameters with relationship info for deterministic URL selection
+ */
+export function useRouterSync(resourceType, operation, routePathParameters) {
+    const location = useLocation();
+    const routerLocationAhead = useRouterLocationAheadOfCommit(location);
+    const urlParameters = useParams();
+    const { registry } = useResourceRegistry();
+    const { emit } = useEventBus();
+    const { getZoneState, contentAreaWidth } = useNavigationState();
+    const appScope = useAppScopeSafe();
+    const { navigationLayout: resolvedNavigationLayout, currentBreakpoint } = useUI();
+    const currentBrowserUrl = useMemo(() => NavigationUtils.buildBrowserUrl(location.pathname, location.search), [location.pathname, location.search]);
+    const liveAppScopeContextIdentifiers = useMemo(() => appScope?.buildContextResourceIdentifiers?.() ?? {}, [appScope]);
+    const liveAppScopeContextIdentifiersKey = useMemo(() => FrontendResourceUtils.buildContextResourceIdentifiersKey(liveAppScopeContextIdentifiers), [liveAppScopeContextIdentifiers]);
+    // Track the last synced path to avoid duplicate updates
+    const lastSyncedPath = useRef(null);
+    const { retryTick, scheduleRetry: scheduleTransactionRetry, clearRetry: clearTransactionRetry, } = useTransactionAwareSyncRetry(currentBrowserUrl);
+    // Pre-compute this resource's route patterns (memoized) so the effect can
+    // cheaply verify that the current URL actually belongs to this resource.
+    // This prevents re-populating the navigation stack when the Outlet briefly
+    // mounts this ResourcePageWrapper during a route transition (e.g., Home '/').
+    const resourceRoutePatterns = useMemo(() => {
+        if (!resourceType || !operation)
+            return [];
+        const resourceConfig = registry.resourceConfigurations?.[resourceType];
+        if (!resourceConfig)
+            return [];
+        return ResourcesConfigOperationsUrlsBuilderUtils.buildOperationFrontendRoutePaths(resourceConfig, operation, registry.allResourceFieldIdentifiers).map(rp => rp.url);
+    }, [resourceType, operation, registry]);
+    useEffect(() => {
+        if (!resourceType || !operation)
+            return;
+        logDebug('useRouterSync: effect fired', {
+            resourceType,
+            operationId: operation.operationIdentifier,
+            locationPathname: location.pathname,
+            lastSyncedPath: lastSyncedPath.current,
+            routePatternsCount: resourceRoutePatterns.length,
+        });
+        // Guard: A NavigationTransaction is active (e.g., home click, org switch, cascading).
+        // The Outlet briefly mounts this ResourcePageWrapper before React Router commits
+        // the route change (startTransition = low-priority).  Skip sync to prevent
+        // re-populating the stack with stale content.
+        if (NavigationUtils.isInTransaction()) {
+            logDebug('useRouterSync: SKIP — navigation transaction active', { source: NavigationUtils.getTransactionSource() });
+            scheduleTransactionRetry();
+            return;
+        }
+        clearTransactionRetry();
+        // Guard: the router already left the URL this route committed with. The transaction above ends on
+        // `setTimeout(0)`, but a location transition can still be pending after it — so the committed URL here
+        // names the page the browser LEFT. Rebuilding from it re-pushes that page, and the always-mounted
+        // reconciler (reading the router) clears it again: the ping-pong measured on an organization switch.
+        // The effect re-runs when the committed location catches up. See `useRouterLocationAheadOfCommit`.
+        if (routerLocationAhead) {
+            logDebug('useRouterSync: SKIP — the router is ahead of the committed location', { committedUrl: currentBrowserUrl });
+            return;
+        }
+        // Skip if we've already synced this path
+        if (lastSyncedPath.current === currentBrowserUrl) {
+            logDebug('useRouterSync: SKIP — already synced this path', { currentBrowserUrl });
+            return;
+        }
+        // Guard: verify the current URL actually matches one of this resource's route patterns.
+        // When navigating to a non-resource route (e.g., Home '/'), the Outlet may briefly
+        // mount this ResourcePageWrapper before React Router unmounts it. Without this guard,
+        // useRouterSync would re-populate the PRIMARY stack with stale content, preventing
+        // the target route (Home) from ever rendering.
+        if (resourceRoutePatterns.length > 0) {
+            const isUrlRelevant = resourceRoutePatterns.some(pattern => NavigationUtils.matchUrlPattern(pattern, location.pathname));
+            if (!isUrlRelevant) {
+                logDebug('useRouterSync: SKIP — URL does not match any resource route pattern', {
+                    pathname: location.pathname,
+                    patterns: resourceRoutePatterns,
+                });
+                lastSyncedPath.current = currentBrowserUrl;
+                return;
+            }
+        }
+        // Get the target resource's primaryScope to filter global identifiers
+        // This prevents border effects from URL sync
+        const targetPrimaryScope = registry.resourceConfigurations?.[resourceType]?.resourcePrimaryScope;
+        // Build parentResourcesRequirements from route path parameters if available
+        const parentResourcesRequirements = routePathParameters
+            ? frontendResourceUtils.buildParentResourcesRequirementsFromRouteParams(routePathParameters, resourceType, registry)
+            : [];
+        // Reverse reconstruction must only trust the current top owner of the URL.
+        // A stale match buried elsewhere in a stack should not suppress rebuild.
+        const zones = resolvedNavigationLayout?.zones;
+        const hasSecondary = !!zones?.secondary;
+        const hasCompanion = !!zones?.companion;
+        const depth = NavigationUtils.calculateResourceRelationshipDepth(parentResourcesRequirements);
+        const prefersAdjacentZoneForDetail = depth === 0
+            && hasSecondary
+            && operation !== undefined
+            // The viewport goes in so a VIEWPORT-scoped override is reconstructed the way the click
+            // resolved it. `undefined` until the first measurement, which matches only the unconditional
+            // overrides — an unknown viewport is not a particular one.
+            && NavigationUtils.layoutSplitsOperationFromPrimary(resolvedNavigationLayout, operation, currentBreakpoint);
+        /*
+         * ─── The viewport decides here too, and until 2026-09-25 it did not ─────────────────────────
+         *
+         * `resolveResourceTargetZone` took no viewport, so a depth ≥ 1 resource went to SECONDARY at any
+         * width — and the content areas render PRIMARY and nothing else on a phone. A bookmarked or
+         * refreshed nested record therefore showed its PARENT (the ancestor the cascade puts in primary)
+         * with no error. The CLICK path was correct throughout, because the resolver applies collapse,
+         * which is exactly what made it invisible: the same content reached the right place when clicked
+         * and the wrong place when linked to.
+         *
+         * `adjacentZoneUsableAtViewport` is the resolver's own predicate, so the two paths cannot
+         * disagree. Note the viewport was ALREADY threaded into `prefersAdjacentZoneForDetail` just
+         * above — one invariant, two sites, one of them done.
+         */
+        const preferredZone = NavigationUtils.resolveResourceTargetZone(depth, {
+            hasSecondary,
+            hasCompanion,
+            prefersAdjacentZoneForDetail,
+        });
+        const targetZone = adjacentZoneUsableAtViewport({
+            zone: preferredZone,
+            layout: resolvedNavigationLayout,
+            viewport: currentBreakpoint,
+            contentAreaWidth,
+        })
+            ? preferredZone
+            : NavigationZoneName.PRIMARY;
+        if (targetZone !== preferredZone) {
+            logDebug('useRouterSync: adjacent zone is collapsed at this viewport — restoring into PRIMARY', {
+                preferredZone, viewport: currentBreakpoint, contentAreaWidth,
+            });
+        }
+        /*
+         * Ownership is asked per ZONE and by DESTINATION: the entry the target zone shows must address
+         * this URL, and a view-state query difference (`?dataMode=`) is not a different destination.
+         * The always-mounted reconciler refreshes the entry's `urlPath` for such a change; this hook's
+         * only job is to not rebuild what is already there.
+         */
+        const targetZoneOwnsUrl = NavigationUtils.zoneOwnsBrowserUrl(targetZone, currentBrowserUrl, getZoneState);
+        logDebug('useRouterSync: checking guards', {
+            currentBrowserUrl,
+            targetZone,
+            targetZoneOwnsUrl,
+            targetZoneTopUrlPath: NavigationUtils.getTopEntry(getZoneState(targetZone))?.urlPath,
+        });
+        if (targetZoneOwnsUrl) {
+            logDebug('useRouterSync: SKIP — target zone already owns current URL', { targetZone });
+            lastSyncedPath.current = currentBrowserUrl;
+            return;
+        }
+        /*
+         * ─── ANOTHER structural zone may already be showing this destination ────────────────────────
+         *
+         * The ownership question above is asked of the zone THIS HOOK computed, and that zone is
+         * derived from the URL alone — depth, plus whether the layout splits this operation out of
+         * primary. It cannot see where the content actually IS, so a record placed in a pane BY A CLICK
+         * and addressed by a bare URL is invisible to it: the hook computes PRIMARY, asks PRIMARY, is
+         * told no, and rebuilds the record there. Primary's top entry then changes, which makes the
+         * zone-dependency cleanup clear SECONDARY — so the pane the reader was using disappears and the
+         * record they opened in it is on the left instead.
+         *
+         * Measured on Wonder CRM (2026-09-24), and it is the defect reported as "click a linked
+         * resource inside the pane and it goes on the left, not on the right": a `contact` opened from
+         * inside a deal's pane lands in SECONDARY correctly (the pane's own `transitions.read` is
+         * `PUSH`, so `getStructuralSourceZone` keeps it there) and writes `/contact/:id` as the browser
+         * URL, because primary holds a deals LIST and is therefore URL-derivable — no hosted pane, no
+         * `?pane=`. That bare URL is what this hook then reconstructs from.
+         *
+         * `findStructuralRouteOwner` is the question worth asking instead — "which structural zone's
+         * VISIBLE entry does this URL address?" — and it already exists, scanning COMPANION → SECONDARY
+         * → PRIMARY by destination. If any zone owns the URL, the application is already showing what
+         * the URL names and there is nothing to reconstruct. A view-state-only difference
+         * (`searchDiffers`) is likewise not a rebuild: the always-mounted reconciler refreshes the
+         * entry's `urlPath` in place.
+         *
+         * This does NOT subsume the check above — that one is what lets the target zone REBUILD when it
+         * holds a different destination — it is the missing half: the other zones get a veto they never
+         * had.
+         */
+        const structuralOwner = NavigationUtils.findStructuralRouteOwner(currentBrowserUrl, getZoneState);
+        if (structuralOwner && structuralOwner.zone !== targetZone) {
+            logDebug('useRouterSync: SKIP — another structural zone already shows this destination', {
+                owningZone: structuralOwner.zone,
+                targetZone,
+                currentBrowserUrl,
+            });
+            lastSyncedPath.current = currentBrowserUrl;
+            return;
+        }
+        // Build resource context from URL params
+        // Pass routePathParameters for accurate FK field mapping (e.g., assignedToUserId → USERS)
+        const urlContextIdentifiers = frontendResourceUtils.extractResourceIdentifiersFromUrlParams(urlParameters, registry, routePathParameters);
+        const mergedContextIdentifiers = ScopeUtilsService.buildResourceOperationContextIdentifiers({
+            currentUserId: appScope?.currentUserId,
+            currentOrganizationId: appScope?.currentOrganizationId,
+            currentApplicationId: appScope?.currentApplicationId,
+            currentAnonymousUserId: appScope?.currentAnonymousUserId,
+            primaryScope: targetPrimaryScope,
+            liveAppScopeContextResourceIdentifiers: liveAppScopeContextIdentifiers,
+            explicitContextResourceIdentifiers: urlContextIdentifiers,
+        });
+        const resourceContext = frontendResourceUtils.createFrontendResourceOperationContextFromOperation({
+            resourceType,
+            operation,
+            contextResourceIdentifiers: mergedContextIdentifiers,
+            parentResourcesRequirements,
+        });
+        // Create navigation content
+        const content = {
+            contentType: NavigationContentType.RESOURCE_OPERATION,
+            resourceContext,
+        };
+        // Generate stack entry ID
+        const stackEntryId = NavigationUtils.generateStackEntryId();
+        // ─── Reverse Cascade: place content in the correct zone ──────────
+        // On page refresh / deep link, the URL-synced resource should land in the
+        // zone matching its relationship depth, not always PRIMARY.
+        // depth 0 → PRIMARY, depth 1 → SECONDARY, depth 2+ → COMPANION.
+        // Ancestor zones are then populated via cascadeAncestorZones.
+        //
+        logDebug('useRouterSync: EMITTING NAVIGATION_REPLACE (URL_SYNC)', {
+            resourceType,
+            operationId: operation.operationIdentifier,
+            currentBrowserUrl,
+            mergedContextIdentifiers,
+            depth,
+            targetZone,
+        });
+        // For deep resources (depth >= 1), wrap in a transaction so cascading
+        // events don't cause useRouterSync to re-fire mid-reconstruction.
+        if (depth >= 1) {
+            NavigationUtils.beginTransaction('url_reverse_cascade');
+        }
+        /*
+         * ─── Restoring a pane's record at a width where the pane is collapsed ──────────────────────
+         *
+         * It lands in PRIMARY — but it must land the way a CLICK at that width lands: the list beneath
+         * it, and stamped with the pane it belongs to. It used to REPLACE into primary with neither, so
+         * Back had nothing to return to and, with no `collapsedFromZone`, widening the window could
+         * never send the record to its pane: it stayed full-width beside an empty one. The stamp is what
+         * `zone-collapse-migration.ts` reads to take it home; the cascade runs FIRST so the record is
+         * pushed on top of the list rather than replacing it.
+         */
+        const collapsedIntoPrimary = targetZone !== preferredZone;
+        if (collapsedIntoPrimary && prefersAdjacentZoneForDetail && preferredZone === NavigationZoneName.SECONDARY) {
+            cascadeSiblingListIntoPrimary({
+                resourceType: resourceType,
+                contextResourceIdentifiers: mergedContextIdentifiers,
+                parentResourcesRequirements, registry, emit, getZoneState,
+            });
+        }
+        emit(collapsedIntoPrimary ? FrontendEvents.NAVIGATION_PUSH : FrontendEvents.NAVIGATION_REPLACE, {
+            zone: targetZone,
+            content,
+            urlPath: currentBrowserUrl,
+            stackEntryId,
+            initiator: { sourceZone: targetZone },
+            navigationSource: NavigationSource.URL_SYNC,
+            transition: NavigationTransition.REPLACE,
+            ...(collapsedIntoPrimary ? { collapsedFromZone: preferredZone } : {}),
+        });
+        if (prefersAdjacentZoneForDetail && targetZone === NavigationZoneName.SECONDARY) {
+            cascadeSiblingListIntoPrimary({
+                resourceType: resourceType,
+                contextResourceIdentifiers: mergedContextIdentifiers,
+                parentResourcesRequirements, registry, emit, getZoneState,
+            });
+        }
+        // Populate ancestor panes for depth 1+ resources
+        if (depth >= 1) {
+            // Normalize context identifiers to plain strings for cascading
+            const normalizedForCascade = normalizeContextResourceIdentifiersForTransport(mergedContextIdentifiers);
+            cascadeAncestorZones(content, targetZone, registry, normalizedForCascade, emit, null, // No URL update needed — browser already has the correct URL
+            getZoneState, { overwriteExisting: true });
+            // Transaction auto-commits via setTimeout(0)
+        }
+        lastSyncedPath.current = currentBrowserUrl;
+    }, [
+        location.pathname,
+        location.search,
+        routerLocationAhead,
+        urlParameters,
+        resourceType,
+        operation,
+        registry,
+        emit,
+        getZoneState,
+        appScope?.currentUserId,
+        appScope?.currentOrganizationId,
+        appScope?.currentApplicationId,
+        appScope?.currentAnonymousUserId,
+        liveAppScopeContextIdentifiersKey,
+        routePathParameters,
+        resourceRoutePatterns,
+        resolvedNavigationLayout,
+        currentBreakpoint,
+        currentBrowserUrl,
+        retryTick,
+        scheduleTransactionRetry,
+        clearTransactionRetry,
+    ]);
+}
+// ================================
+// View Router Sync Hook
+// ================================
+/**
+ * Hook to sync view routes (composite, chart, custom, flows-actors) with navigation state.
+ *
+ * Unlike useRouterSync (which handles resource operations), this handles non-resource
+ * content types that only need a viewRef and contentType. Views are always depth 0
+ * (placed in PRIMARY zone), have no parent chain, and no cascading.
+ *
+ * On refresh / deep link, this hook populates the PRIMARY zone's navigation stack
+ * with the correct view content so that:
+ * - ZoneContentRenderer renders the view
+ * - Sidebar active state reflects the current view
+ * - goBack() works correctly
+ *
+ * @param viewRef - The view reference from the URL
+ * @param contentType - The navigation content type (COMPOSITE_VIEW, CHART_VIEW, etc.)
+ */
+export function useViewRouterSync(viewRef, contentType) {
+    const location = useLocation();
+    const routerLocationAhead = useRouterLocationAheadOfCommit(location);
+    const { emit } = useEventBus();
+    const { getZoneState } = useNavigationState();
+    const { registry } = useResourceRegistry();
+    const { fullCustomViews, flowsActorsViews } = useUI();
+    const lastSyncedPath = useRef(null);
+    const currentUrl = NavigationUtils.buildBrowserUrl(location.pathname, location.search);
+    const { retryTick, scheduleRetry: scheduleTransactionRetry, clearRetry: clearTransactionRetry, } = useTransactionAwareSyncRetry(currentUrl);
+    useEffect(() => {
+        if (!viewRef)
+            return;
+        // Guard: transaction active
+        if (NavigationUtils.isInTransaction()) {
+            scheduleTransactionRetry();
+            return;
+        }
+        clearTransactionRetry();
+        // Guard: the router already left the URL this route committed with (a pending location transition).
+        // Rebuilding from it would restore the page the browser left. See `useRouterLocationAheadOfCommit`.
+        if (routerLocationAhead)
+            return;
+        // Skip if already synced
+        if (lastSyncedPath.current === currentUrl)
+            return;
+        // Asked about PRIMARY's half of the URL: under a composed URL the HOST is this view and the
+        // `pane` parameter belongs to the secondary zone's own reconciler. A view-state change
+        // (`?section=`) on the same view is owned too — the reconciler refreshes the stamp in place.
+        if (NavigationUtils.zoneOwnsBrowserUrl(NavigationZoneName.PRIMARY, currentUrl, getZoneState)) {
+            lastSyncedPath.current = currentUrl;
+            return;
+        }
+        // Deep-link sync should rebuild the same typed view payload, but ambient
+        // primary scope is derived live from AppScope by the view itself.
+        let content;
+        const compositeRouteContextResourceIdentifiers = contentType === NavigationContentType.COMPOSITE_VIEW
+            ? extractCompositeRouteContextResourceIdentifiers(new URLSearchParams(location.search))
+            : undefined;
+        const chartRouteContextResourceIdentifiers = contentType === NavigationContentType.CHART_VIEW
+            ? extractChartRouteContextResourceIdentifiers(new URLSearchParams(location.search))
+            : undefined;
+        const chartRouteUrlParamValues = contentType === NavigationContentType.CHART_VIEW
+            ? extractChartRouteUrlParamValues(new URLSearchParams(location.search))
+            : undefined;
+        const executionRouteContextResourceIdentifiers = contentType === NavigationContentType.EXECUTION_VIEW
+            ? extractExecutionRouteContextResourceIdentifiers(new URLSearchParams(location.search))
+            : undefined;
+        const fullCustomView = contentType === NavigationContentType.FULL_CUSTOM_VIEW
+            ? fullCustomViews?.find(view => view.ref === viewRef)
+            : undefined;
+        const flowsActorsView = contentType === NavigationContentType.FLOWS_ACTORS_VIEW
+            ? flowsActorsViews?.find(view => view.ref === viewRef)
+            : undefined;
+        const executionView = contentType === NavigationContentType.EXECUTION_VIEW
+            ? resolveExecutionViewDefinition({
+                viewRef,
+                registry,
+            })
+            : undefined;
+        switch (contentType) {
+            case NavigationContentType.COMPOSITE_VIEW:
+                content = {
+                    contentType: NavigationContentType.COMPOSITE_VIEW,
+                    viewRef,
+                    contextResourceIdentifiers: compositeRouteContextResourceIdentifiers,
+                };
+                break;
+            case NavigationContentType.CHART_VIEW:
+                content = {
+                    contentType: NavigationContentType.CHART_VIEW,
+                    viewRef,
+                    contextResourceIdentifiers: chartRouteContextResourceIdentifiers,
+                    urlParamValues: chartRouteUrlParamValues,
+                };
+                break;
+            case NavigationContentType.FULL_CUSTOM_VIEW:
+                if (!fullCustomView) {
+                    return;
+                }
+                content = {
+                    contentType: NavigationContentType.FULL_CUSTOM_VIEW,
+                    viewRef,
+                    fullCustomComponentRef: fullCustomView.componentRef,
+                };
+                break;
+            case NavigationContentType.FLOWS_ACTORS_VIEW:
+                if (!flowsActorsView) {
+                    return;
+                }
+                content = {
+                    contentType: NavigationContentType.FLOWS_ACTORS_VIEW,
+                    viewRef,
+                    flowsActorsSystemRef: flowsActorsView.systemRef,
+                };
+                break;
+            case NavigationContentType.EXECUTION_VIEW:
+                if (!executionView
+                    || executionView.isAddressable !== true) {
+                    return;
+                }
+                content = {
+                    contentType: NavigationContentType.EXECUTION_VIEW,
+                    viewRef,
+                    contextResourceIdentifiers: executionRouteContextResourceIdentifiers,
+                };
+                break;
+            default:
+                return;
+        }
+        const stackEntryId = NavigationUtils.generateStackEntryId();
+        logDebug('useViewRouterSync: EMITTING NAVIGATION_REPLACE (URL_SYNC)', {
+            viewRef,
+            contentType,
+            locationPathname: location.pathname,
+            locationSearch: location.search,
+        });
+        emit(FrontendEvents.NAVIGATION_REPLACE, {
+            zone: NavigationZoneName.PRIMARY,
+            content,
+            // The view's OWN address: under a composed URL the `pane` half belongs to the secondary
+            // entry, and stamping it here would make the host look like a different destination the
+            // moment the pane changed.
+            urlPath: NavigationUtils.decomposeHostedPaneBrowserUrl(currentUrl).hostUrl,
+            stackEntryId,
+            initiator: { sourceZone: NavigationZoneName.PRIMARY },
+            navigationSource: NavigationSource.URL_SYNC,
+            transition: NavigationTransition.REPLACE,
+        });
+        lastSyncedPath.current = currentUrl;
+    }, [viewRef, contentType, emit, getZoneState, fullCustomViews, flowsActorsViews, registry, currentUrl, routerLocationAhead, retryTick, scheduleTransactionRetry, clearTransactionRetry]);
+}
+/**
+ * Router sync for typed engine pages.
+ *
+ * Engine pages are app-level routes that should still populate the PRIMARY stack
+ * so launcher active-state and back-navigation remain coherent after refresh or
+ * direct URL entry.
+ */
+export function useEnginePageRouterSync(pageRef) {
+    const location = useLocation();
+    const routerLocationAhead = useRouterLocationAheadOfCommit(location);
+    const { emit } = useEventBus();
+    const { getZoneState } = useNavigationState();
+    const lastSyncedPath = useRef(null);
+    const currentUrl = NavigationUtils.buildBrowserUrl(location.pathname, location.search);
+    const { retryTick, scheduleRetry: scheduleTransactionRetry, clearRetry: clearTransactionRetry, } = useTransactionAwareSyncRetry(currentUrl);
+    useEffect(() => {
+        if (!pageRef)
+            return;
+        if (NavigationUtils.isInTransaction()) {
+            scheduleTransactionRetry();
+            return;
+        }
+        clearTransactionRetry();
+        // Guard: the router already left the URL this route committed with (a pending location transition).
+        // Rebuilding from it would restore the page the browser left. See `useRouterLocationAheadOfCommit`.
+        if (routerLocationAhead)
+            return;
+        if (lastSyncedPath.current === currentUrl)
+            return;
+        // Same per-zone, destination-based ownership as the view sync above.
+        if (NavigationUtils.zoneOwnsBrowserUrl(NavigationZoneName.PRIMARY, currentUrl, getZoneState)) {
+            lastSyncedPath.current = currentUrl;
+            return;
+        }
+        const stackEntryId = NavigationUtils.generateStackEntryId();
+        emit(FrontendEvents.NAVIGATION_REPLACE, {
+            zone: NavigationZoneName.PRIMARY,
+            content: {
+                contentType: NavigationContentType.ENGINE_PAGE,
+                pageRef,
+            },
+            urlPath: NavigationUtils.decomposeHostedPaneBrowserUrl(currentUrl).hostUrl,
+            stackEntryId,
+            initiator: { sourceZone: NavigationZoneName.PRIMARY },
+            navigationSource: NavigationSource.URL_SYNC,
+            transition: NavigationTransition.REPLACE,
+        });
+        lastSyncedPath.current = currentUrl;
+    }, [pageRef, emit, getZoneState, currentUrl, routerLocationAhead, retryTick, scheduleTransactionRetry, clearTransactionRetry]);
+}
+/**
+ * Persistent, always-mounted reconciler that maps browser **back/forward**
+ * (history popstate) onto the STRUCTURAL zone stacks (PRIMARY / SECONDARY /
+ * COMPANION).
+ *
+ * ── Why this exists (the gap it closes) ────────────────────────────────────
+ * Structural-zone content is rendered from the navigation **stack state**, not
+ * from the router `<Outlet/>`: `ZoneContentRenderer` renders `routerChildren`
+ * (the Outlet, which hosts `useRouterSync` / `useViewRouterSync` /
+ * `useEnginePageRouterSync`) ONLY when a zone's stack is empty. In-session the
+ * PRIMARY stack is never empty, so the Outlet — and with it the per-route
+ * URL→state sync hooks — is unmounted. Controller-driven navigation (sidebar,
+ * links, Home) mutates the stack directly via events, so it is unaffected. But
+ * a browser back/forward only changes `location`; with no mounted sync hook
+ * observing it, the stack was never reconciled — the URL (and the
+ * `useLocation`-derived sidebar highlight) moved while the rendered content
+ * stayed on the previous entry. This is the structural-zone analogue of what
+ * {@link useSettingsHubOverlaySync} already does for the overlay, and it is
+ * mounted the same way: exactly once, at the navigation-runtime level.
+ *
+ * ── Contract ───────────────────────────────────────────────────────────────
+ * On every `location` change — read from the data router synchronously, so a URL the
+ * transition-committed location context coalesced away is still observed — (deferred while
+ * a navigation transaction is mid-flight, so controller-driven URL updates are not double-handled):
+ *  1. Settings-hub URLs (`/settings*`) are owned by {@link useSettingsHubOverlaySync}
+ *     (overlay layer) — skip them entirely so we never clobber the structural
+ *     content sitting beneath the hub.
+ *  2. If the URL addresses the DESTINATION already at the visible top of a
+ *     structural zone → no rebuild. When it differs only in VIEW STATE
+ *     (`?section=`), the entry's `urlPath` is refreshed in place through
+ *     `NAVIGATION_URL_PATH_UPDATED` — same id, same content. Under a composed
+ *     URL (`?pane=`, see `useHostedPaneRouteSync`) the host's stamp on PRIMARY
+ *     and the pane's on SECONDARY are both refreshed.
+ *  3. If the URL matches an entry still sitting LOWER in a zone's backstack →
+ *     restore it with a pure `NAVIGATION_POP` to that entry. This is the common
+ *     back-button case; popping preserves the revealed entry's live state
+ *     (scroll, expanded rows) instead of rebuilding it. A composed URL is
+ *     matched against the SECONDARY backstack while PRIMARY addresses the host.
+ *  4. Otherwise the URL is not in any structural stack (forward to a
+ *     previously-popped entry, or a manual URL edit without reload) → clear the
+ *     structural zones inside a transaction so the Outlet fallback remounts and
+ *     the existing route-mounted sync hooks reconstruct from the URL. This
+ *     reuses the single URL→state derivation rather than duplicating it here,
+ *     matching the documented URL-first reconstruction model.
+ *
+ * We never call `routerNavigate` here — the browser already owns the URL; this
+ * hook only brings zone state up to match it, so there is no URL-write loop.
+ */
+export function useStructuralZoneBackForwardSync() {
+    // The router's own location, not the transition-committed one: a coalesced intermediate URL is what
+    // left `lastSyncedPath` behind and turned browser back into a no-op. See `useSynchronousBrowserLocation`.
+    const location = useSynchronousBrowserLocation();
+    const { emit } = useEventBus();
+    const { getZoneState } = useNavigationState();
+    const lastSyncedPath = useRef(null);
+    const currentUrl = NavigationUtils.buildBrowserUrl(location.pathname, location.search);
+    const { retryTick, scheduleRetry, clearRetry } = useTransactionAwareSyncRetry(currentUrl);
+    useEffect(() => {
+        // Defer while a controller-driven navigation transaction is committing; the
+        // retry tick re-runs this reconciler once the emitted entry owns the URL, so
+        // step 2 below no-ops instead of us fighting the controller.
+        if (NavigationUtils.isInTransaction()) {
+            scheduleRetry();
+            return;
+        }
+        clearRetry();
+        if (lastSyncedPath.current === currentUrl)
+            return;
+        // (1) Settings-hub URLs belong to the overlay reconciler — leave the
+        // structural stack beneath the hub untouched.
+        if (matchSettingsHubPath(location.pathname).isSettings) {
+            lastSyncedPath.current = currentUrl;
+            return;
+        }
+        const owner = NavigationUtils.findStructuralStackEntryOwningUrl(currentUrl, getZoneState);
+        // (2) Already the visible top of its zone — nothing to REBUILD. When the URL moved only in
+        // VIEW STATE (`?section=` on a board, `?dataMode=` on a list) the entry's stamp is refreshed in
+        // place, id and content untouched, so the next comparison sees the URL it will actually get.
+        // Under a composed URL both halves are refreshed: the host's stamp on PRIMARY, the pane's on
+        // SECONDARY. This is the branch that used to fall through to (4) and tear every zone down for
+        // a tab click.
+        if (owner?.isTop) {
+            if (owner.searchDiffers) {
+                const { hostUrl, paneUrl } = NavigationUtils.decomposeHostedPaneBrowserUrl(currentUrl);
+                const refreshes = paneUrl !== undefined
+                    ? [
+                        { zone: NavigationZoneName.PRIMARY, entry: NavigationUtils.getTopEntry(getZoneState(NavigationZoneName.PRIMARY)), urlPath: hostUrl },
+                        { zone: NavigationZoneName.SECONDARY, entry: owner.entry, urlPath: paneUrl },
+                    ]
+                    : [{ zone: owner.zone, entry: owner.entry, urlPath: currentUrl }];
+                for (const refresh of refreshes) {
+                    if (refresh.entry && refresh.entry.urlPath !== refresh.urlPath) {
+                        logDebug('useStructuralZoneBackForwardSync: refreshing entry urlPath for a view-state change', {
+                            zone: refresh.zone,
+                            stackEntryId: refresh.entry.id,
+                            from: refresh.entry.urlPath,
+                            to: refresh.urlPath,
+                        });
+                        emit(FrontendEvents.NAVIGATION_URL_PATH_UPDATED, {
+                            zone: refresh.zone,
+                            stackEntryId: refresh.entry.id,
+                            urlPath: refresh.urlPath,
+                        });
+                    }
+                }
+            }
+            lastSyncedPath.current = currentUrl;
+            return;
+        }
+        // (3) Previously-visited entry still in the backstack — restore via POP.
+        if (owner) {
+            logDebug('useStructuralZoneBackForwardSync: POP to backstack entry', {
+                zone: owner.zone,
+                toStackEntryId: owner.entry.id,
+                currentUrl,
+            });
+            emit(FrontendEvents.NAVIGATION_POP, {
+                zone: owner.zone,
+                toStackEntryId: owner.entry.id,
+            });
+            lastSyncedPath.current = currentUrl;
+            return;
+        }
+        // (4) URL is not anywhere in the structural stacks. If a stack is currently
+        // non-empty the Outlet (and its sync hooks) is unmounted, so clear the
+        // structural zones inside a transaction and let the Outlet fallback rebuild
+        // from the URL. When every structural stack is already empty (cold load /
+        // deep-link) the Outlet is mounted and owns reconstruction — do nothing.
+        const anyStructuralContent = NAVIGATION_STRUCTURAL_ZONES.some((zone) => getZoneState(zone).stack.length > 0);
+        if (anyStructuralContent) {
+            logDebug('useStructuralZoneBackForwardSync: clearing structural zones for URL rebuild', { currentUrl });
+            NavigationUtils.beginTransaction('backforward_url_rebuild');
+            for (const zone of NAVIGATION_STRUCTURAL_ZONES) {
+                emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone });
+            }
+            // Transaction auto-commits (setTimeout(0)); the route-mounted sync hooks skip while it is
+            // active, and also while the router is ahead of their committed location
+            // (`useRouterLocationAheadOfCommit`). They rebuild when both have cleared: the transaction
+            // epoch or the committed location changing re-runs their effects.
+        }
+        lastSyncedPath.current = currentUrl;
+    }, [currentUrl, location.pathname, emit, getZoneState, retryTick, scheduleRetry, clearRetry]);
+}
+/**
+ * Persistent, always-mounted reconciler that keeps a HOSTED PANE in step with the URL.
+ *
+ * A hosted pane is a SECONDARY resource destination opened beside a primary whose own address no
+ * resource URL implies — a composite view, a canvas, a chart, an engine page. The browser URL is
+ * the host's, carrying the pane as `?pane=` (see `HOSTED_PANE_QUERY_PARAM`), so the pane is never
+ * the router's route and no route element ever mounts a sync hook for it. This hook is that sync,
+ * mounted once at the navigation-runtime level like the two reconcilers beside it.
+ *
+ * Contract, on every `location` change (deferred while a transaction is committing; settings-hub
+ * URLs are left to the overlay reconciler, the structural zones beneath the hub untouched):
+ *  1. No `pane` in the URL and the secondary shows a hosted pane → the pane left the URL (browser
+ *     back, the host's `goBack`) → clear SECONDARY.
+ *  2. The pane addresses what the secondary already shows → nothing to do (a view-state change
+ *     was refreshed by the back/forward reconciler).
+ *  3. The pane addresses an entry lower in the secondary backstack → POP to it.
+ *  4. Otherwise resolve the pane's URL against the same route table `AppRouter` registers, build
+ *     its resource context exactly as `useRouterSync` would from the router's params, and place
+ *     it in SECONDARY as a SPLIT flagged `hostedPane`. Placed regardless of whether PRIMARY has
+ *     landed yet: the dependency cleanup keeps a hosted pane beside a non-resource primary, so
+ *     the two halves of a deep link may arrive in either order.
+ *
+ * Placed into SECONDARY even when SECONDARY is collapsed at this width. This hook read the layout
+ * and the breakpoint and used them only as effect dependencies, which looked like collapse handling
+ * and was none: a narrow reload put the pane where nothing draws it. Collapse is now enforced for
+ * EVERY path by `useResponsiveZoneMigration` ("a collapsed zone holds nothing"), which moves the
+ * pane into PRIMARY the same way a click at that width would be placed — so this hook no longer
+ * needs to know the width, and does not pretend to. What it must know is case 2's extension: a pane
+ * held in PRIMARY on the collapsed secondary's behalf is still the pane, or every later URL change
+ * would place it again and the migration would stack a duplicate.
+ *
+ * Never writes the URL — the browser owns it; this only brings the zone up to match.
+ */
+export function useHostedPaneRouteSync() {
+    const location = useSynchronousBrowserLocation();
+    const { emit } = useEventBus();
+    const { getZoneState } = useNavigationState();
+    const { registry } = useResourceRegistry();
+    const appScope = useAppScopeSafe();
+    const lastSyncedPath = useRef(null);
+    const currentUrl = NavigationUtils.buildBrowserUrl(location.pathname, location.search);
+    const { retryTick, scheduleRetry, clearRetry } = useTransactionAwareSyncRetry(currentUrl);
+    const liveAppScopeContextIdentifiers = useMemo(() => appScope?.buildContextResourceIdentifiers?.() ?? {}, [appScope]);
+    useEffect(() => {
+        if (NavigationUtils.isInTransaction()) {
+            scheduleRetry();
+            return;
+        }
+        clearRetry();
+        if (lastSyncedPath.current === currentUrl)
+            return;
+        // Settings-hub URLs belong to the overlay reconciler; the structural zones beneath the hub —
+        // a hosted pane included — are left exactly as they are, the same exemption the back/forward
+        // reconciler makes. Without it, opening Settings read as "the pane left the URL".
+        if (matchSettingsHubPath(location.pathname).isSettings) {
+            lastSyncedPath.current = currentUrl;
+            return;
+        }
+        const { paneUrl } = NavigationUtils.decomposeHostedPaneBrowserUrl(currentUrl);
+        const secondaryState = getZoneState(NavigationZoneName.SECONDARY);
+        const secondaryTop = NavigationUtils.getTopEntry(secondaryState);
+        // (1) The pane left the URL.
+        if (paneUrl === undefined) {
+            if (secondaryTop?.hostedPane) {
+                logDebug('useHostedPaneRouteSync: pane left the URL — clearing SECONDARY', { currentUrl });
+                emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone: NavigationZoneName.SECONDARY });
+            }
+            lastSyncedPath.current = currentUrl;
+            return;
+        }
+        // (2) Already showing it.
+        if (secondaryTop?.hostedPane && NavigationUtils.urlsAddressSameDestination(secondaryTop.urlPath, paneUrl)) {
+            lastSyncedPath.current = currentUrl;
+            return;
+        }
+        const heldForCollapsedSecondary = NavigationUtils.getTopEntry(getZoneState(NavigationZoneName.PRIMARY));
+        if (NavigationUtils.isHeldHostedPane(heldForCollapsedSecondary)
+            && NavigationUtils.urlsAddressSameDestination(heldForCollapsedSecondary?.urlPath, paneUrl)) {
+            lastSyncedPath.current = currentUrl;
+            return;
+        }
+        // (3) Lower in the backstack — a browser back between two panes under one host.
+        const buried = [...secondaryState.stack].reverse().find((entry) => entry.hostedPane && NavigationUtils.urlsAddressSameDestination(entry.urlPath, paneUrl));
+        if (buried) {
+            logDebug('useHostedPaneRouteSync: POP to a buried pane', { toStackEntryId: buried.id, paneUrl });
+            emit(FrontendEvents.NAVIGATION_POP, { zone: NavigationZoneName.SECONDARY, toStackEntryId: buried.id });
+            lastSyncedPath.current = currentUrl;
+            return;
+        }
+        // (4) Rebuild the pane from its own address.
+        const route = NavigationUtils.resolveResourceRouteForUrl(paneUrl, registry);
+        if (!route) {
+            logDebug('useHostedPaneRouteSync: pane URL matches no addressable resource route — ignored', { paneUrl });
+            lastSyncedPath.current = currentUrl;
+            return;
+        }
+        const parentResourcesRequirements = frontendResourceUtils.buildParentResourcesRequirementsFromRouteParams(route.routePathParameters, route.resourceType, registry);
+        const urlContextIdentifiers = frontendResourceUtils.extractResourceIdentifiersFromUrlParams(route.urlParameters, registry, route.routePathParameters);
+        const targetPrimaryScope = registry.resourceConfigurations?.[route.resourceType]?.resourcePrimaryScope;
+        const contextResourceIdentifiers = ScopeUtilsService.buildResourceOperationContextIdentifiers({
+            currentUserId: appScope?.currentUserId,
+            currentOrganizationId: appScope?.currentOrganizationId,
+            currentApplicationId: appScope?.currentApplicationId,
+            currentAnonymousUserId: appScope?.currentAnonymousUserId,
+            primaryScope: targetPrimaryScope,
+            liveAppScopeContextResourceIdentifiers: liveAppScopeContextIdentifiers,
+            explicitContextResourceIdentifiers: urlContextIdentifiers,
+        });
+        const resourceContext = frontendResourceUtils.createFrontendResourceOperationContextFromOperation({
+            resourceType: route.resourceType,
+            operation: route.operation,
+            contextResourceIdentifiers,
+            parentResourcesRequirements,
+        });
+        logDebug('useHostedPaneRouteSync: EMITTING NAVIGATION_REPLACE (URL_SYNC) for the hosted pane', {
+            paneUrl,
+            resourceType: route.resourceType,
+            operationId: route.operation.operationIdentifier,
+        });
+        emit(FrontendEvents.NAVIGATION_REPLACE, {
+            zone: NavigationZoneName.SECONDARY,
+            content: { contentType: NavigationContentType.RESOURCE_OPERATION, resourceContext },
+            urlPath: paneUrl,
+            stackEntryId: NavigationUtils.generateStackEntryId(),
+            initiator: { sourceZone: NavigationZoneName.PRIMARY },
+            navigationSource: NavigationSource.URL_SYNC,
+            transition: NavigationTransition.SPLIT,
+            hostedPane: true,
+        });
+        lastSyncedPath.current = currentUrl;
+    }, [
+        currentUrl,
+        location.pathname,
+        emit,
+        getZoneState,
+        registry,
+        appScope?.currentUserId,
+        appScope?.currentOrganizationId,
+        appScope?.currentApplicationId,
+        appScope?.currentAnonymousUserId,
+        liveAppScopeContextIdentifiers,
+        retryTick,
+        scheduleRetry,
+        clearRetry,
+    ]);
+}
+/**
+ * Matches the unified Settings Hub URL family.
+ * `/settings` → `{ isSettings: true }`; `/settings/:sectionRef` →
+ * `{ isSettings: true, sectionRef }`; `/settings/:sectionRef/:subTabRef` →
+ * `{ isSettings: true, sectionRef, subTabRef }`.
+ *
+ * The remainder is SPLIT rather than taken whole, which it was until 2026-09-17. That mattered
+ * before sub-tabs were addressable: `/settings/a/b` produced the section ref `"a/b"`, which
+ * matches no destination, so the hub silently fell back to its default section — a deep link with
+ * one segment too many opened Profile and said nothing. Splitting makes the second segment mean
+ * what it looks like it means, and anything beyond the second is still ignored.
+ */
+function matchSettingsHubPath(pathname) {
+    if (pathname === CommonRoutePaths.settings)
+        return { isSettings: true };
+    const prefix = `${CommonRoutePaths.settings}/`;
+    if (pathname.startsWith(prefix)) {
+        const [sectionRef, subTabRef] = pathname.slice(prefix.length).split('/');
+        return {
+            isSettings: true,
+            sectionRef: sectionRef && sectionRef.length > 0 ? sectionRef : undefined,
+            subTabRef: subTabRef && subTabRef.length > 0 ? subTabRef : undefined,
+        };
+    }
+    return { isSettings: false };
+}
+/**
+ * Persistent, idempotent reconciler that keeps the Settings Hub overlay in sync
+ * with the URL. The hub is overlay-rendered but URL-addressable, and the URL is
+ * its single source of truth.
+ *
+ * Mounted ONCE at the navigation-runtime level (NOT per-route, NOT in the
+ * `/settings` route element). This is deliberate: a route-mounted sync that
+ * pushed on mount and tore down on unmount would, under React StrictMode, have
+ * its unmount-teardown double-invoked and close the just-pushed overlay during
+ * in-session navigation — the exact "refresh works, in-session click does not"
+ * failure mode. A persistent reconciler reads the current URL + overlay state
+ * and converges to the correct state on every run, so StrictMode double-invokes
+ * and the `state.overlay` dependency re-running are both harmless no-ops.
+ *
+ * Contract:
+ * - On `/settings` / `/settings/:sectionRef`: ensure the overlay top is a
+ *   `SETTINGS_HUB` at that section (push when absent, replace on section change,
+ *   no-op when already correct).
+ * - Off the settings URL: close the hub if it is the top overlay — covers
+ *   dismiss-driven navigation, browser back/forward, and app-level navigation
+ *   away from settings, all through one URL-driven path.
+ *
+ * The PRIMARY surface beneath the hub is the route element's render (home as the
+ * `routerChildren` fallback on a cold deep-link) or the persisted PRIMARY stack
+ * (in-session) — see `NavigationContentAreas`'
+ * `ZoneContentRenderer fallback={routerChildren}`.
+ */
+export function useSettingsHubOverlaySync() {
+    const location = useSynchronousBrowserLocation();
+    const { emit } = useEventBus();
+    const { state } = useNavigationState();
+    const { retryTick, scheduleRetry, clearRetry } = useTransactionAwareSyncRetry(location.pathname);
+    // Dedupes the asynchronous overlay reconciliation emit. The reconciler reacts
+    // to `state.overlay`, but PUSH/REPLACE/CLOSE land asynchronously (event →
+    // setState), so the effect can re-run — including React StrictMode's
+    // intentional setup/cleanup/setup double-invoke — and observe the SAME
+    // pre-emit overlay before the previous emit has applied, stacking a duplicate
+    // hub. Keying the emit on (action, path, section, observed stack length) makes
+    // a repeat emit against an unchanged observation a no-op; it is cleared the
+    // instant the overlay reaches the desired (converged / closed) state, so a
+    // genuinely new transition still emits.
+    const lastEmitRef = useRef(null);
+    useEffect(() => {
+        // Defer while a navigation transaction is mid-flight; the retry tick re-runs
+        // this reconciler once it commits.
+        if (NavigationUtils.isInTransaction()) {
+            scheduleRetry();
+            return;
+        }
+        clearRetry();
+        const { isSettings, sectionRef, subTabRef } = matchSettingsHubPath(location.pathname);
+        const overlayStack = state.overlay;
+        const topEntry = overlayStack.length > 0 ? overlayStack[overlayStack.length - 1] : undefined;
+        let topIsHub = false;
+        let topSectionRef;
+        let topSubTabRef;
+        if (topEntry && topEntry.content.contentType === NavigationContentType.SETTINGS_HUB) {
+            topIsHub = true;
+            topSectionRef = topEntry.content.sectionRef;
+            topSubTabRef = topEntry.content.subTabRef;
+        }
+        if (isSettings) {
+            // Already showing the hub at the requested section AND sub-tab → converged, nothing to do.
+            // The sub-tab participates in convergence as well as the section: without it, moving between
+            // two tabs of the same section leaves the reconciler believing it is already correct, so the
+            // URL changes and the panel does not — which is the same class of inertness the section-level
+            // `config`-in-deps bug produced in the hub itself.
+            if (topIsHub && topSectionRef === sectionRef && topSubTabRef === subTabRef) {
+                lastEmitRef.current = null;
+                return;
+            }
+            const action = topIsHub ? FrontendEvents.NAVIGATION_REPLACE : FrontendEvents.NAVIGATION_PUSH;
+            const emitKey = `${action}|${location.pathname}|${sectionRef ?? ''}|${subTabRef ?? ''}|${overlayStack.length}`;
+            if (lastEmitRef.current === emitKey)
+                return;
+            lastEmitRef.current = emitKey;
+            emit(action, {
+                zone: NavigationZone.OVERLAY,
+                content: { contentType: NavigationContentType.SETTINGS_HUB, sectionRef, subTabRef },
+                urlPath: NavigationUtils.buildBrowserUrl(location.pathname, location.search),
+                stackEntryId: NavigationUtils.generateStackEntryId(),
+                initiator: { sourceZone: NavigationZone.OVERLAY },
+                navigationSource: NavigationSource.URL_SYNC,
+                transition: NavigationTransition.OVERLAY,
+                appearance: OverlayAppearance.DIALOG,
+                ephemeral: false,
+            });
+            return;
+        }
+        // Off the settings URL: if the hub is still the top overlay, the URL departed
+        // (dismiss, browser back, app-level nav) → close it.
+        if (topIsHub) {
+            const emitKey = `${FrontendEvents.NAVIGATION_CLOSE}|${overlayStack.length}`;
+            if (lastEmitRef.current === emitKey)
+                return;
+            lastEmitRef.current = emitKey;
+            emit(FrontendEvents.NAVIGATION_CLOSE, { zone: NavigationZone.OVERLAY });
+            return;
+        }
+        lastEmitRef.current = null;
+    }, [location.pathname, location.search, emit, state.overlay, retryTick, scheduleRetry, clearRetry]);
+}
+//# sourceMappingURL=useNavigationRouterSync.js.map