@wildo-ai/saas-frontend-lib 1.0.1

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

@@ -0,0 +1,1015 @@
+/**
+ * useNavigationController Hook
+ *
+ * The main hook for triggering navigation in the application.
+ * Components (sidebar, toolbar, list items, etc.) use this to navigate.
+ *
+ * The controller:
+ * 1. Receives navigation requests
+ * 2. Resolves the navigation target using NavigationPolicyResolver
+ * 3. Emits appropriate navigation events (PUSH, REPLACE, etc.)
+ * 4. Optionally updates the browser URL for addressable operations
+ *
+ * Also includes URL-to-state synchronization (merged from RouterNavigationSync):
+ * - useRouterSync hook syncs external URL changes with navigation state
+ * - Uses NavigationSource to track origin and avoid sync loops
+ */
+import { useCallback, useMemo, useEffect, useRef } from 'react';
+import { useNavigate, 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 { useUserOrgs } from '../../core/security/useUserOrgs.js';
+import { useAppScopeSafe } from '../../core/scope/useAppScope.js';
+import { ScopeUtilsService } from '../../core/scope/scope.utils.frontend.service.js';
+import { buildChartRouteUrlPath, extractChartRouteContextResourceIdentifiers, extractChartRouteUrlParamValues, } from '../../core/config/chart-view.frontend.schemas.js';
+import { buildCompositeRouteUrlPath, extractCompositeRouteContextResourceIdentifiers, } from '../../core/config/composite-view.schemas.js';
+import { buildExecutionRouteUrlPath, extractExecutionRouteContextResourceIdentifiers, resolveExecutionViewDefinition, } from '../../core/config/execution-view.schemas.js';
+import { FrontendEvents, } from '../../core/events/events.frontend.schemas.js';
+import { NavigationZone, NavigationContentType, NAVIGATION_STRUCTURAL_ZONES, APP_LEVEL_NAVIGATION_SOURCE, } from './navigation.schemas.js';
+import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
+import { NavigationTransition, NavigationZoneName, CoreResourceOperation, ResourcesConfigOperationsUrlsBuilderUtils, } from '@wildo-ai/saas-models';
+import { useResourceRegistry } from '../../core/resources/useResourceRegistry.js';
+import { navigationPolicyResolver } from './navigation-policy-resolver.service.js';
+import { NavigationSource } from './navigation.schemas.js';
+import { NavigationUtils } from './navigation.utils.js';
+import { emitFreshStartNavigationCleanup } from './navigation-clean-break.frontend.utils.js';
+import { useTransactionAwareSyncRetry } from './useTransactionAwareSyncRetry.js';
+import { FrontendResourceUtils, frontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
+import { resolveEffectiveCoreOperationFromOperation } from '../../core/resources/operation-semantics.frontend.utils.js';
+const logger = LoggerFrontendService.getLogger();
+const logDebug = logger.debugByType('useNavigationController');
+logger.setDebugTypeLogging('useNavigationController', false);
+/**
+ * Update browser URL using React Router's navigate function.
+ * This ensures React Router's useLocation hook updates, which is needed for proper isActive detection in the sidebar.
+ *
+ * IMPORTANT: The URL update is deferred using requestAnimationFrame to allow
+ * React's state updates from navigation events to complete first. This prevents a race condition where URL change triggers re-renders before navigation state is updated.
+ */
+function updateBrowserUrl(routerNavigate, urlPath, replace = false) {
+    // Defer URL update to after React's render cycle completes - requestAnimationFrame ensures we wait until after paint
+    requestAnimationFrame(() => {
+        routerNavigate(urlPath, { replace });
+    });
+}
+// ================================
+// Cascading Orchestrator
+// ================================
+/**
+ * Auto-populate ancestor zones when navigating to SECONDARY or COMPANION.
+ *
+ * When a resource is placed in SECONDARY or COMPANION, its ancestor resources
+ * should be visible in the zones above it. This function checks which
+ * ancestor zones are empty and populates them with the appropriate content.
+ *
+ * Rules:
+ * - Only cascades for resource operations (not views)
+ * - Only populates EMPTY zones (never overwrites user-navigated content)
+ * - Uses `parentResourcesRequirements` to determine ancestor chain
+ * - Stops at primary scope ancestors (org/user level)
+ * - Maximum 2 ancestor zones (PRIMARY + SECONDARY for a COMPANION target)
+ */
+function cascadeAncestorZones(targetContent, resolvedZone, registry, contextIdentifiers, emit, routerNavigate, getZoneState, options) {
+    const parentRequirements = targetContent.resourceContext.parentResourcesRequirements;
+    if (!parentRequirements || parentRequirements.length === 0)
+        return;
+    // Determine which zones need population.
+    // Order matters: zonesToPopulate[i] maps to ancestors[i] (nearest parent first).
+    // For COMPANION target: nearest parent → SECONDARY (adjacent), furthest → PRIMARY (root).
+    // This maintains the master-detail-detail convention: PRIMARY=broadest, COMPANION=most specific.
+    const zonesToPopulate = [];
+    if (resolvedZone === NavigationZoneName.SECONDARY) {
+        zonesToPopulate.push(NavigationZoneName.PRIMARY);
+    }
+    else if (resolvedZone === NavigationZoneName.COMPANION) {
+        zonesToPopulate.push(NavigationZoneName.SECONDARY, NavigationZoneName.PRIMARY);
+    }
+    if (zonesToPopulate.length === 0)
+        return;
+    // parentResourcesRequirements is ordered root → leaf (closest ancestor last).
+    // Reverse to process nearest parent first — nearest maps to adjacent zone.
+    const ancestors = [...parentRequirements].reverse();
+    const targetResourceType = targetContent.resourceContext.resourceType;
+    for (let i = 0; i < zonesToPopulate.length && i < ancestors.length; i++) {
+        const zone = zonesToPopulate[i];
+        const ancestor = ancestors[i];
+        // Skip primary scope ancestors (org, user) — these don't get a zone
+        if (ancestor.isPrimaryScope)
+            continue;
+        // Controller-driven cascade keeps existing user context intact, but URL-first
+        // reconstruction is allowed to replace ancestor zones so the visible stack
+        // matches the authoritative browser URL again.
+        const zoneState = getZoneState(zone);
+        if (!options?.overwriteExisting && zoneState.stack.length > 0)
+            continue;
+        // Get ancestor resource config
+        const ancestorResourceType = ancestor.resourceType;
+        const ancestorConfig = registry.resourceConfigurations?.[ancestorResourceType];
+        if (!ancestorConfig)
+            continue;
+        // Find relationship between ancestor and target (or intermediate child)
+        const childType = ancestor.childResourceType
+            ?? (i === 0 ? targetResourceType : ancestors[i - 1].resourceType);
+        const relationship = NavigationUtils.findRelationshipBetween(ancestorResourceType, childType, registry, ancestor.foreignKeyField);
+        // Resolve which operation to show in the ancestor zone
+        const opConfig = NavigationUtils.resolveAncestorOperationConfig(relationship, ancestorConfig);
+        if (!opConfig)
+            continue;
+        const ancestorOp = resolveEffectiveCoreOperationFromOperation(opConfig);
+        // Build parent requirements for the ancestor itself:
+        // The ancestor's parents are those ABOVE it in the chain (root → leaf ordering).
+        // Using slice(0, index) ensures we only include entries before the ancestor,
+        // not entries below it (which are its children/grandchildren, not parents).
+        // Previously used filter(req => req.resourceType !== ancestorResourceType) which
+        // incorrectly kept descendants as parents for non-adjacent ancestors (Bug #1).
+        // `ancestors` is reversed (nearest parent first) but `parentRequirements`
+        // stays root → leaf, so convert back by position instead of looking up by
+        // resource type. Position-based slicing is what keeps repeated/self-ref
+        // parent types from collapsing onto the first matching entry.
+        const ancestorIndex = parentRequirements.length - 1 - i;
+        const ancestorParentReqs = ancestorIndex > 0
+            ? parentRequirements.slice(0, ancestorIndex)
+            : [];
+        // Build ancestor resource context
+        const ancestorContextIdentifiers = {};
+        for (const req of ancestorParentReqs) {
+            const contextKey = req.foreignKeyField ?? req.resourceType;
+            // Prefer the FK-keyed slot when present. Same-type parent chains store the
+            // parent id under the FK field so the resource-type key can continue to
+            // represent the current record.
+            const id = contextIdentifiers[contextKey] ?? contextIdentifiers[req.resourceType];
+            if (id) {
+                ancestorContextIdentifiers[contextKey] = id;
+            }
+        }
+        // Also include the ancestor's own ID if it's a READ operation
+        const ancestorSelfId = contextIdentifiers[ancestorResourceType];
+        if (ancestorSelfId && ancestorOp === CoreResourceOperation.READ) {
+            ancestorContextIdentifiers[ancestorResourceType] = ancestorSelfId;
+        }
+        const ancestorResourceContext = frontendResourceUtils.createFrontendResourceOperationContextFromOperation({
+            resourceType: ancestorResourceType,
+            operation: opConfig,
+            contextResourceIdentifiers: ancestorContextIdentifiers,
+            parentResourcesRequirements: ancestorParentReqs,
+        });
+        const ancestorContent = {
+            contentType: NavigationContentType.RESOURCE_OPERATION,
+            resourceContext: ancestorResourceContext,
+        };
+        // Resolve URL for ancestor
+        let ancestorUrl;
+        const resolved = NavigationUtils.resolveResourceUrl(ancestorConfig, opConfig, ancestorContextIdentifiers, registry.allResourceFieldIdentifiers, ancestorParentReqs);
+        if (resolved?.resolvedUrl) {
+            ancestorUrl = resolved.resolvedUrl;
+        }
+        const stackEntryId = NavigationUtils.generateStackEntryId();
+        logDebug('cascadeAncestorZones: populating ancestor zone', {
+            zone,
+            ancestorResourceType,
+            ancestorOp,
+            ancestorUrl,
+        });
+        emit(FrontendEvents.NAVIGATION_REPLACE, {
+            zone,
+            content: ancestorContent,
+            urlPath: ancestorUrl,
+            stackEntryId,
+            initiator: { sourceZone: zone },
+            navigationSource: NavigationSource.CONTROLLER,
+            transition: NavigationTransition.REPLACE,
+        });
+        // Update URL only for PRIMARY zone ancestor (the URL bar shows PRIMARY)
+        // Skip URL update when routerNavigate is null (reverse cascade from URL sync)
+        if (zone === NavigationZoneName.PRIMARY && ancestorUrl && routerNavigate) {
+            updateBrowserUrl(routerNavigate, ancestorUrl, true);
+        }
+    }
+}
+/**
+ * Hook to control navigation in the application
+ */
+export function useNavigationController() {
+    const { emit } = useEventBus();
+    const { resourceRelationshipDepth: currentResourceRelationshipDepth, getZoneDepth, getZoneState } = useNavigationState();
+    const { navigationLayout, currentBreakpoint, compositeViews, fullCustomViews, flowsActorsViews } = useUI();
+    const { user } = useUserOrgs();
+    const appScope = useAppScopeSafe();
+    const { registry, getOperationContextNeeds, evaluateOperationEnabled } = useResourceRegistry();
+    const routerNavigate = useNavigate();
+    const latestNavigateRequestIdRef = useRef(0);
+    // Note: Context identifiers are now computed per-navigation call with scope filtering
+    // to prevent border effects where unrelated identifiers leak into the navigation chain
+    /**
+     * Main navigate function
+     * Navigation target is determined purely by the NavigationPolicy - no overrides allowed.
+     *
+     * contextResourceIdentifiers are merged with global scope identifiers from AppScope:
+     * - Global identifiers (organizationId, userId, applicationId, etc.) are injected automatically
+     * - Explicit contextResourceIdentifiers override the global values
+     *
+     * IMPORTANT: The merged identifiers are also injected into the content's resourceContext
+     * so that list/read/etc. components have access to parent resource IDs for API calls.
+     */
+    const navigate = useCallback((options) => {
+        const requestId = ++latestNavigateRequestIdRef.current;
+        void (async () => {
+            let { content, initiator, urlPath, contextResourceIdentifiers, relationshipTransition, replaceBrowserHistory, } = options;
+            try {
+                logDebug('navigate() called', { contentType: content.contentType, sourceZone: initiator.sourceZone, urlPath });
+                if (!navigationLayout) {
+                    logDebug('navigate() aborted: no navigationLayout');
+                    return;
+                }
+                // Extract primaryScope from target content to filter context identifiers
+                // This prevents border effects where identifiers from one scope leak into another
+                const targetPrimaryScope = ScopeUtilsService.extractPrimaryScopeFromContent(content, registry, compositeViews, fullCustomViews, flowsActorsViews);
+                // Get scope-filtered global identifiers - only inject identifiers relevant to target's primaryScope
+                const primaryScopeInitiatorIds = ScopeUtilsService.buildInitiatorIds({
+                    userId: appScope?.currentUserId,
+                    organizationId: appScope?.currentOrganizationId,
+                    applicationId: appScope?.currentApplicationId,
+                    anonymousUserId: appScope?.currentAnonymousUserId,
+                });
+                const scopeFilteredGlobalIdentifiers = ScopeUtilsService.primaryScopeToContextIdentifiers(primaryScopeInitiatorIds, targetPrimaryScope);
+                // Custom scope identifiers (resourceType-keyed) from AppScopeContext.
+                // Duplicate resourceType declarations are rejected during config validation
+                // and AppScopeContext initialization, so this map stays semantically unique.
+                const appScopeIdentifiers = appScope?.buildContextResourceIdentifiers() ?? {};
+                // Candidate identifiers for route-path selection (strict relevance applied after selection).
+                // Explicit identifiers override everything else.
+                const contentProvidedContextIdentifiers = NavigationUtils.isResourceOperationContent(content)
+                    ? (content.resourceContext.contextResourceIdentifiers ?? {})
+                    : {};
+                const candidateContextIdentifiers = {
+                    ...scopeFilteredGlobalIdentifiers,
+                    ...appScopeIdentifiers,
+                    ...contentProvidedContextIdentifiers,
+                    ...contextResourceIdentifiers,
+                };
+                // Normalize candidate identifiers for URL building / route matching
+                // (context identifiers may be objects like { fieldIdentifier, resourceId }).
+                const normalizedCandidateContextIdentifiers = {};
+                for (const [resType, rawValue] of Object.entries(candidateContextIdentifiers)) {
+                    const resourceId = frontendResourceUtils.getResourceId(rawValue);
+                    if (resourceId) {
+                        normalizedCandidateContextIdentifiers[resType] = resourceId;
+                        const explicitFieldIdentifier = frontendResourceUtils.getFieldIdentifier(rawValue);
+                        if (explicitFieldIdentifier) {
+                            normalizedCandidateContextIdentifiers[explicitFieldIdentifier] = resourceId;
+                        }
+                    }
+                }
+                let isAddressable = false;
+                let operationOverrides;
+                let selectedRoutePathParameters;
+                let selectedRouteTemplateUrl = urlPath;
+                let selectedResolvedUrl;
+                // Create a copy of content with merged context identifiers injected
+                // This ensures list/read components have access to parent resource IDs
+                let enrichedContent = content;
+                if (NavigationUtils.isResourceOperationContent(content)) {
+                    const operation = content.resourceContext.operation;
+                    isAddressable = operation?.operationFrontendConfig?.isAddressable ?? false;
+                    operationOverrides = operation?.operationFrontendConfig?.navigationOverrides;
+                    // Use unified URL resolver to select the best route path
+                    const resourceType = content.resourceContext.resourceType;
+                    const resourceConfig = registry.resourceConfigurations?.[resourceType];
+                    if (resourceConfig) {
+                        const resolved = NavigationUtils.resolveResourceUrl(resourceConfig, operation, normalizedCandidateContextIdentifiers, registry.allResourceFieldIdentifiers, content.resourceContext.parentResourcesRequirements);
+                        if (resolved) {
+                            selectedRouteTemplateUrl = resolved.templateUrl;
+                            selectedRoutePathParameters = resolved.routePathParameters;
+                            selectedResolvedUrl = resolved.resolvedUrl;
+                        }
+                    }
+                    // Strict relevance for navigation context:
+                    // only inject identifiers that the selected route path actually depends on,
+                    // plus explicit identifiers (and the resource self identifier if present).
+                    const allowedResourceTypes = new Set((selectedRoutePathParameters ?? []).map(p => p.resourceType));
+                    // ─── enabledCondition Guard (navigation-time) ───────────────
+                    // Guard is only evaluated when it does NOT require objectContext fetching.
+                    // If objectContext is required, the guard must be handled at UI/action level (async data dependency).
+                    if ('enabledCondition' in operation && operation.enabledCondition) {
+                        const needs = getOperationContextNeeds(operation);
+                        if (needs.needsUserContext && !user) {
+                            console.warn('[useNavigationController] Navigation blocked: enabledCondition requires user context but user is missing', {
+                                resourceType,
+                                operationIdentifier: operation.operationIdentifier,
+                            });
+                            return;
+                        }
+                        if (!needs.needsObjectContext) {
+                            // Provide an IDs-only objectContext built from the explicit parent
+                            // requirements first so FK-keyed self-ref context is preserved.
+                            const parents = {};
+                            const explicitParentRequirements = content.resourceContext.parentResourcesRequirements ?? [];
+                            if (explicitParentRequirements.length > 0) {
+                                for (const requirement of explicitParentRequirements) {
+                                    const contextKey = requirement.foreignKeyField ?? requirement.resourceType;
+                                    const id = normalizedCandidateContextIdentifiers[contextKey]
+                                        ?? normalizedCandidateContextIdentifiers[requirement.resourceType];
+                                    if (id) {
+                                        parents[contextKey] = { _id: id };
+                                    }
+                                }
+                            }
+                            else {
+                                // Fallback: keep the previous route-param relevance filter when no
+                                // explicit parent chain is available.
+                                for (const [type, id] of Object.entries(normalizedCandidateContextIdentifiers)) {
+                                    if (allowedResourceTypes.size === 0 || allowedResourceTypes.has(type)) {
+                                        parents[type] = { _id: id };
+                                    }
+                                }
+                            }
+                            const isEnabled = await evaluateOperationEnabled({
+                                operation: operation,
+                                resourceType: resourceType,
+                                userContext: user ?? undefined,
+                                initiatorIds: ScopeUtilsService.buildInitiatorIds({
+                                    userId: appScope?.currentUserId,
+                                    organizationId: appScope?.currentOrganizationId,
+                                    applicationId: appScope?.currentApplicationId,
+                                    anonymousUserId: appScope?.currentAnonymousUserId,
+                                }),
+                                objectContext: { parents, children: {} },
+                            });
+                            if (requestId !== latestNavigateRequestIdRef.current) {
+                                logDebug('navigate() aborted: stale async navigation result', {
+                                    requestId,
+                                    latestRequestId: latestNavigateRequestIdRef.current,
+                                    resourceType,
+                                    operationIdentifier: operation.operationIdentifier,
+                                    sourceZone: initiator.sourceZone,
+                                });
+                                return;
+                            }
+                            if (isEnabled !== true) {
+                                console.warn('[useNavigationController] Navigation blocked by enabledCondition', {
+                                    resourceType,
+                                    operationIdentifier: operation.operationIdentifier,
+                                });
+                                return;
+                            }
+                        }
+                    }
+                    if (requestId !== latestNavigateRequestIdRef.current) {
+                        logDebug('navigate() aborted: superseded before state mutation', {
+                            requestId,
+                            latestRequestId: latestNavigateRequestIdRef.current,
+                            sourceZone: initiator.sourceZone,
+                        });
+                        return;
+                    }
+                    const relevantInjected = {};
+                    for (const [resType, value] of Object.entries({
+                        ...scopeFilteredGlobalIdentifiers,
+                        ...appScopeIdentifiers,
+                    })) {
+                        if (allowedResourceTypes.size === 0 || allowedResourceTypes.has(resType)) {
+                            relevantInjected[resType] = value;
+                        }
+                    }
+                    const selfIdentifier = content.resourceContext.contextResourceIdentifiers?.[resourceType];
+                    enrichedContent = {
+                        ...content,
+                        resourceContext: {
+                            ...content.resourceContext,
+                            contextResourceIdentifiers: {
+                                ...relevantInjected,
+                                ...contextResourceIdentifiers,
+                                ...(selfIdentifier ? { [resourceType]: selfIdentifier } : {}),
+                                ...content.resourceContext.contextResourceIdentifiers,
+                            },
+                        },
+                    };
+                }
+                else if (content.contentType === NavigationContentType.COMPOSITE_VIEW
+                    || content.contentType === NavigationContentType.CHART_VIEW
+                    || content.contentType === NavigationContentType.FULL_CUSTOM_VIEW
+                    || content.contentType === NavigationContentType.EXECUTION_VIEW
+                    || content.contentType === NavigationContentType.FLOWS_ACTORS_VIEW) {
+                    // Custom views derive ambient primary scope live from AppScope at render time.
+                    // Only explicit navigation-time identifiers should be persisted on the stack.
+                    const mergedContextIdentifiers = {
+                        ...(content.contextResourceIdentifiers ?? {}),
+                        ...contextResourceIdentifiers,
+                    };
+                    enrichedContent = {
+                        ...content,
+                        contextResourceIdentifiers: Object.keys(mergedContextIdentifiers).length > 0
+                            ? mergedContextIdentifiers
+                            : undefined,
+                    };
+                }
+                else if (content.contentType === NavigationContentType.CUSTOM_COMPONENT) {
+                    const mergedContextIdentifiers = {
+                        ...scopeFilteredGlobalIdentifiers,
+                        ...appScopeIdentifiers,
+                        ...(content.contextResourceIdentifiers ?? {}),
+                        ...contextResourceIdentifiers,
+                    };
+                    enrichedContent = {
+                        ...content,
+                        contextResourceIdentifiers: Object.keys(mergedContextIdentifiers).length > 0
+                            ? mergedContextIdentifiers
+                            : undefined,
+                    };
+                }
+                // ─── APP_LEVEL Clean Break ────────────────────────────────
+                // Sidebar/toolbar/command-palette navigation is a "fresh start."
+                // Clear dependent zones and overlay state within a transaction before placing
+                // new content.
+                if (initiator.sourceZone === APP_LEVEL_NAVIGATION_SOURCE) {
+                    emitFreshStartNavigationCleanup(emit, 'app_level_navigation');
+                    logDebug('APP_LEVEL clean break: cleared SECONDARY + COMPANION + OVERLAY');
+                }
+                // Compute resource relationship depth from parent chain (hierarchy-based, not stack-based)
+                const resourceRelationshipDepth = NavigationUtils.isResourceOperationContent(enrichedContent)
+                    ? NavigationUtils.calculateResourceRelationshipDepth(enrichedContent.resourceContext.parentResourcesRequirements)
+                    : 0;
+                // Compute zone occupancy for SPLIT target heuristic
+                const zoneOccupancy = {};
+                for (const zone of NAVIGATION_STRUCTURAL_ZONES) {
+                    zoneOccupancy[zone] = getZoneState(zone).stack.length > 0;
+                }
+                // Derive source zone for resolution context — map initiator.sourceZone
+                // to the resolver's expected discriminant (NavigationZoneName | 'appLevel' | 'overlay')
+                const sourceZone = initiator.sourceZone;
+                // Extract operation identifier for policy resolution
+                const operationIdentifier = NavigationUtils.isResourceOperationContent(enrichedContent)
+                    ? (enrichedContent.resourceContext.operation?.operationIdentifier ?? CoreResourceOperation.LIST)
+                    : CoreResourceOperation.LIST;
+                const effectiveOperation = NavigationUtils.isResourceOperationContent(enrichedContent)
+                    ? resolveEffectiveCoreOperationFromOperation(enrichedContent.resourceContext.operation)
+                    : CoreResourceOperation.LIST;
+                // Extract target resource type for resolution context
+                const targetResourceType = NavigationUtils.isResourceOperationContent(enrichedContent)
+                    ? enrichedContent.resourceContext.resourceType
+                    : undefined;
+                // Derive focusedZone — only meaningful when sourceZone is a structural zone
+                const focusedZone = (sourceZone !== APP_LEVEL_NAVIGATION_SOURCE && sourceZone !== NavigationZone.OVERLAY)
+                    ? sourceZone
+                    : undefined;
+                // Build v3 resolution context — target is determined by policy, not caller
+                const resolutionContext = {
+                    sourceZone: sourceZone,
+                    operation: operationIdentifier,
+                    effectiveOperation,
+                    resourceType: targetResourceType,
+                    isAddressable,
+                    operationOverrides: operationOverrides,
+                    relationshipTransition,
+                    viewport: currentBreakpoint,
+                    zoneOccupancy,
+                    focusedZone,
+                };
+                // collapsed is available in the result for Phase 3E (NavigationContentAreas rendering)
+                const resolution = navigationPolicyResolver.resolve(resolutionContext, navigationLayout);
+                logDebug('Policy resolved', { targetZone: resolution.targetZone, transition: resolution.transition, appearance: resolution.appearance, collapsed: resolution.collapsed, ephemeral: resolution.ephemeral });
+                // ─── PROMOTE Clean Break ─────────────────────────────────
+                // When PROMOTE is resolved, the target is outside PRIMARY's subtree.
+                // Clear dependent zones and overlay state — the content is "breaking out"
+                // of the current flow.
+                if (resolution.transition === NavigationTransition.PROMOTE) {
+                    emitFreshStartNavigationCleanup(emit, 'promote_navigation');
+                    logDebug('PROMOTE clean break: cleared SECONDARY + COMPANION + OVERLAY');
+                }
+                // ─── Cascading Orchestrator ───────────────────────────────
+                // When the resolved zone is SECONDARY or COMPANION, auto-populate ancestor
+                // zones that are currently empty so the user sees proper context.
+                if ((resolution.targetZone === NavigationZoneName.SECONDARY || resolution.targetZone === NavigationZoneName.COMPANION)
+                    && NavigationUtils.isResourceOperationContent(enrichedContent)) {
+                    cascadeAncestorZones(enrichedContent, resolution.targetZone, registry, normalizedCandidateContextIdentifiers, emit, routerNavigate, getZoneState);
+                }
+                const stackEntryId = NavigationUtils.generateStackEntryId();
+                // The URL was already resolved by resolveResourceUrl above (stored in selectedResolvedUrl).
+                // For non-resource content, fall back to the explicitly provided urlPath.
+                const resolvedUrlPath = selectedResolvedUrl ?? urlPath;
+                // URL update: addressable content in structural zones gets a URL
+                const isStructuralZone = resolution.targetZone !== NavigationZone.OVERLAY;
+                const isAddressableExecutionView = enrichedContent.contentType === NavigationContentType.EXECUTION_VIEW
+                    ? (() => {
+                        const executionView = resolveExecutionViewDefinition({
+                            viewRef: enrichedContent.viewRef,
+                            registry,
+                        });
+                        return executionView?.isAddressable === true;
+                    })()
+                    : false;
+                const isRoutableNonResourceContent = enrichedContent.contentType === NavigationContentType.COMPOSITE_VIEW
+                    || enrichedContent.contentType === NavigationContentType.CHART_VIEW
+                    || enrichedContent.contentType === NavigationContentType.FULL_CUSTOM_VIEW
+                    || isAddressableExecutionView
+                    || enrichedContent.contentType === NavigationContentType.FLOWS_ACTORS_VIEW
+                    || enrichedContent.contentType === NavigationContentType.ENGINE_PAGE;
+                const shouldUpdateUrl = isStructuralZone && Boolean(resolvedUrlPath) && (isAddressable || isRoutableNonResourceContent);
+                const finalUrlPath = shouldUpdateUrl
+                    ? (enrichedContent.contentType === NavigationContentType.COMPOSITE_VIEW
+                        ? buildCompositeRouteUrlPath(enrichedContent.viewRef, enrichedContent.contextResourceIdentifiers)
+                        : enrichedContent.contentType === NavigationContentType.CHART_VIEW
+                            ? buildChartRouteUrlPath(enrichedContent.viewRef, enrichedContent.contextResourceIdentifiers, enrichedContent.urlParamValues)
+                            : enrichedContent.contentType === NavigationContentType.EXECUTION_VIEW
+                                ? buildExecutionRouteUrlPath(enrichedContent.viewRef, enrichedContent.contextResourceIdentifiers)
+                                : resolvedUrlPath)
+                    : undefined;
+                const eventPayload = {
+                    zone: resolution.targetZone,
+                    content: enrichedContent,
+                    urlPath: finalUrlPath,
+                    stackEntryId,
+                    initiator,
+                    navigationSource: NavigationSource.CONTROLLER,
+                    transition: resolution.transition,
+                    appearance: resolution.appearance,
+                    ephemeral: resolution.ephemeral,
+                };
+                logDebug('Emitting navigation event', { event: resolution.transition === NavigationTransition.PUSH ? 'PUSH' : 'REPLACE', zone: resolution.targetZone, finalUrlPath });
+                if (resolution.transition === NavigationTransition.PUSH) {
+                    emit(FrontendEvents.NAVIGATION_PUSH, eventPayload);
+                }
+                else {
+                    // PROMOTE, REPLACE, SPLIT, INPLACE, OVERLAY all emit as REPLACE
+                    emit(FrontendEvents.NAVIGATION_REPLACE, eventPayload);
+                }
+                // Update browser URL for addressable operations in structural zones
+                if (shouldUpdateUrl && finalUrlPath) {
+                    const isReplaceLike = replaceBrowserHistory === true
+                        || resolution.transition === NavigationTransition.REPLACE
+                        || resolution.transition === NavigationTransition.PROMOTE;
+                    updateBrowserUrl(routerNavigate, finalUrlPath, isReplaceLike);
+                }
+            }
+            catch (error) {
+                logger.error('useNavigationController navigation failed', {
+                    error,
+                    requestId,
+                    sourceZone: initiator.sourceZone,
+                    contentType: content.contentType,
+                    urlPath,
+                    resourceType: NavigationUtils.isResourceOperationContent(content)
+                        ? content.resourceContext.resourceType
+                        : undefined,
+                    operationIdentifier: NavigationUtils.isResourceOperationContent(content)
+                        ? content.resourceContext.operation?.operationIdentifier
+                        : undefined,
+                });
+            }
+        })();
+    }, [
+        emit,
+        navigationLayout,
+        currentBreakpoint,
+        user,
+        appScope,
+        registry,
+        compositeViews,
+        fullCustomViews,
+        flowsActorsViews,
+        getOperationContextNeeds,
+        evaluateOperationEnabled,
+        routerNavigate,
+        getZoneState,
+    ]);
+    const navigateToResource = useCallback((resourceContext, initiator, urlPath) => {
+        const content = {
+            contentType: NavigationContentType.RESOURCE_OPERATION,
+            resourceContext,
+        };
+        navigate({ content, initiator, urlPath });
+    }, [navigate]);
+    /**
+     * Go back in a specific zone's stack.
+     */
+    const goBack = useCallback((zone = NavigationZoneName.PRIMARY) => {
+        const zoneState = getZoneState(zone);
+        if (zoneState.stack.length > 1) {
+            emit(FrontendEvents.NAVIGATION_POP, { zone });
+            const previousEntry = zoneState.stack[zoneState.stack.length - 2];
+            if (previousEntry?.urlPath) {
+                updateBrowserUrl(routerNavigate, previousEntry.urlPath, true);
+            }
+        }
+        else if (zone !== NavigationZoneName.PRIMARY) {
+            emit(FrontendEvents.NAVIGATION_POP, { zone });
+            const primaryState = getZoneState(NavigationZoneName.PRIMARY);
+            const secondaryState = getZoneState(NavigationZoneName.SECONDARY);
+            const fallbackUrl = zone === NavigationZoneName.COMPANION
+                ? secondaryState.stack[secondaryState.stack.length - 1]?.urlPath
+                    ?? primaryState.stack[primaryState.stack.length - 1]?.urlPath
+                : primaryState.stack[primaryState.stack.length - 1]?.urlPath;
+            if (fallbackUrl) {
+                updateBrowserUrl(routerNavigate, fallbackUrl, true);
+            }
+        }
+    }, [emit, getZoneState, routerNavigate]);
+    /**
+     * Close the top overlay entry.
+     */
+    const closeOverlay = useCallback(() => {
+        emit(FrontendEvents.NAVIGATION_CLOSE, { zone: NavigationZone.OVERLAY });
+    }, [emit]);
+    /**
+     * Check if a zone's stack has entries to go back to.
+     */
+    const canGoBack = useCallback((zone) => {
+        return getZoneDepth(zone) > 1;
+    }, [getZoneDepth]);
+    return useMemo(() => ({ navigate, navigateToResource, goBack, closeOverlay, canGoBack, resourceRelationshipDepth: currentResourceRelationshipDepth }), [navigate, navigateToResource, goBack, closeOverlay, canGoBack, currentResourceRelationshipDepth]);
+}
+// ================================
+// 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 urlParameters = useParams();
+    const { registry } = useResourceRegistry();
+    const { emit } = useEventBus();
+    const { getZoneState } = useNavigationState();
+    const appScope = useAppScopeSafe();
+    const { navigationLayout: resolvedNavigationLayout } = 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();
+        // 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 targetZone = NavigationUtils.resolveResourceTargetZone(depth, {
+            hasSecondary,
+            hasCompanion,
+        });
+        const routeOwner = NavigationUtils.findStructuralRouteOwner(currentBrowserUrl, getZoneState);
+        logDebug('useRouterSync: checking guards', {
+            currentBrowserUrl,
+            targetZone,
+            routeOwnerZone: routeOwner?.zone,
+            routeOwnerSource: routeOwner?.entry.navigationSource,
+            routeOwnerUrlPath: routeOwner?.entry.urlPath,
+        });
+        if (routeOwner?.zone === targetZone) {
+            logDebug('useRouterSync: SKIP — target zone already owns current URL', {
+                targetZone,
+                navigationSource: routeOwner.entry.navigationSource,
+            });
+            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');
+        }
+        emit(FrontendEvents.NAVIGATION_REPLACE, {
+            zone: targetZone,
+            content,
+            urlPath: currentBrowserUrl,
+            stackEntryId,
+            initiator: { sourceZone: targetZone },
+            navigationSource: NavigationSource.URL_SYNC,
+            transition: NavigationTransition.REPLACE,
+        });
+        // Populate ancestor panes for depth 1+ resources
+        if (depth >= 1) {
+            // Normalize context identifiers to plain strings for cascading
+            const normalizedForCascade = {};
+            for (const [key, val] of Object.entries(mergedContextIdentifiers)) {
+                const id = frontendResourceUtils.getResourceId(val);
+                if (id)
+                    normalizedForCascade[key] = id;
+            }
+            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,
+        urlParameters,
+        resourceType,
+        operation,
+        registry,
+        emit,
+        getZoneState,
+        appScope?.currentUserId,
+        appScope?.currentOrganizationId,
+        appScope?.currentApplicationId,
+        appScope?.currentAnonymousUserId,
+        liveAppScopeContextIdentifiersKey,
+        routePathParameters,
+        resourceRoutePatterns,
+        resolvedNavigationLayout,
+        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 { 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();
+        // Skip if already synced
+        if (lastSyncedPath.current === currentUrl)
+            return;
+        const routeOwner = NavigationUtils.findStructuralRouteOwner(currentUrl, getZoneState);
+        if (routeOwner?.zone === NavigationZoneName.PRIMARY) {
+            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,
+                    flowsActorsSystemRefs: flowsActorsView.systemRefs,
+                };
+                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,
+            urlPath: currentUrl,
+            stackEntryId,
+            initiator: { sourceZone: NavigationZoneName.PRIMARY },
+            navigationSource: NavigationSource.URL_SYNC,
+            transition: NavigationTransition.REPLACE,
+        });
+        lastSyncedPath.current = currentUrl;
+    }, [viewRef, contentType, emit, getZoneState, fullCustomViews, flowsActorsViews, registry, currentUrl, 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 { 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();
+        if (lastSyncedPath.current === currentUrl)
+            return;
+        const routeOwner = NavigationUtils.findStructuralRouteOwner(currentUrl, getZoneState);
+        if (routeOwner?.zone === NavigationZoneName.PRIMARY) {
+            lastSyncedPath.current = currentUrl;
+            return;
+        }
+        const stackEntryId = NavigationUtils.generateStackEntryId();
+        emit(FrontendEvents.NAVIGATION_REPLACE, {
+            zone: NavigationZoneName.PRIMARY,
+            content: {
+                contentType: NavigationContentType.ENGINE_PAGE,
+                pageRef,
+            },
+            urlPath: currentUrl,
+            stackEntryId,
+            initiator: { sourceZone: NavigationZoneName.PRIMARY },
+            navigationSource: NavigationSource.URL_SYNC,
+            transition: NavigationTransition.REPLACE,
+        });
+        lastSyncedPath.current = currentUrl;
+    }, [pageRef, emit, getZoneState, currentUrl, retryTick, scheduleTransactionRetry, clearTransactionRetry]);
+}
+//# sourceMappingURL=useNavigationController.js.map