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

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

@@ -1,294 +1,60 @@
 /**
- * useNavigationController Hook
+ * The navigation CONTROLLER: what a click does.
  *
- * The main hook for triggering navigation in the application.
- * Components (sidebar, toolbar, list items, etc.) use this to navigate.
+ * `navigate()` resolves a navigation request through `navigationPolicyResolver`, applies the
+ * outcome (clean breaks, in-place hand-off, promote, the cascade) and emits the placement. It is the
+ * click path; the URL path lives in `useNavigationRouterSync.ts`.
  *
- * 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
+ * ## The split, 2026-09-25
  *
- * 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
+ * This module was 2,322 lines holding click resolution, URL reconciliation, the ancestor cascade,
+ * clean breaks, dismiss and the emit bridge. The seam was measured rather than guessed: the
+ * router-sync half used exactly THREE symbols from the controller half — `logDebug` and the two
+ * cascade functions — so it came out at a cost of two shared modules and no behaviour change.
+ *
+ * | module | answers |
+ * |---|---|
+ * | this one | what a CLICK does |
+ * | `useNavigationRouterSync.ts` | what a URL means — deep links, back/forward, hosted panes |
+ * | `navigation-cascade.ts` | what fills the zones nobody clicked |
+ * | `navigation-controller-internals.ts` | the debug channel and the browser-URL write |
  */
-import { createContext, useCallback, useContext, useMemo, useEffect, useRef } from 'react';
-import { useNavigate, useLocation, useParams } from 'react-router-dom';
+import { createContext, useCallback, useContext, useMemo, useRef, } from 'react';
+import { useNavigate, useLocation, } 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 { buildChartRouteUrlPath, } from '../../core/config/chart-view.frontend.schemas.js';
+import { buildCompositeRouteUrlPath, } from '../../core/config/composite-view.schemas.js';
+import { buildExecutionRouteUrlPath, 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, OverlayAppearance, SplitAppearance, CoreResourceOperation, ResourceOperationFrontendSurface, ResourcesConfigOperationsUrlsBuilderUtils, } from '@wildo-ai/saas-models';
+import { NavigationTransition, NavigationZoneName, CoreResourceOperation, ResourceOperationFrontendSurface, } from '@wildo-ai/saas-models';
 import { useResourceRegistry } from '../../core/resources/useResourceRegistry.js';
-import { navigationPolicyResolver, resolveViewportDiscriminated } from './navigation-policy-resolver.service.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 { emitFreshStartNavigationCleanup, emitOverlayBreakoutCleanup } from './navigation-clean-break.frontend.utils.js';
 import { CommonRoutePaths } from '../../core/runtime/routes.frontend.definitions.js';
-import { FrontendResourceUtils, frontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
-import { isOperationAddressable } from '../../core/resources/resources.frontend.schemas.js';
-import { normalizeContextResourceIdentifiersForTransport } from '../../core/resources/context-resource-identifiers.frontend.utils.js';
-import { resolveActionPresentationTransition, resolveEffectiveCoreOperationFromOperation, resolveResourceOperationActionPresentation, getOperationsForCoreSemantic, pickPreferredOperationForCoreSemantic, } from '../../core/resources/operation-semantics.frontend.utils.js';
+import { frontendResourceUtils, } from '../../core/resources/frontend-resource.utils.js';
+import { resolveActionPresentationTransition, resolveEffectiveCoreOperationFromOperation, resolveResourceOperationActionPresentation, } from '../../core/resources/operation-semantics.frontend.utils.js';
 import { InPlaceOperationTargetKind, useInPlaceOperation, } from '../../core/resources/in-place/InPlaceOperationContext.js';
 const logger = LoggerFrontendService.getLogger();
-const logDebug = logger.debugByType('useNavigationController');
-logger.setDebugTypeLogging('useNavigationController', false);
-/**
- * Update the browser URL via React Router's navigate function, so React Router's
- * `useLocation` hook updates. Everything derived from `useLocation` depends on
- * this: deep-link shareability, back-button state, and the sidebar's
- * most-specific-active highlight (`useSidebarBehavior` reads `useLocation`).
- *
- * ORDERING (why the transaction): the URL→state reconstruction hooks
- * (`useRouterSync`, `useViewRouterSync`, `useEnginePageRouterSync`,
- * `useSettingsHubOverlaySync`) observe `location` changes and rebuild zone state
- * from the URL — UNLESS the target zone already owns the URL, OR a navigation
- * transaction is active. A controller-driven navigation emits the zone-state
- * entry (event bus → `setState`) and THEN changes the URL; if the URL change is
- * observed before that state has committed, those hooks would re-derive stale
- * content (the race the old code papered over). We therefore open (or extend) a
- * navigation transaction so they skip during the commit window and re-validate
- * via their transaction-aware retry once state has committed — by then the
- * emitted entry owns the URL, so they no-op. This mirrors
- * `navigatePathWithFreshStart` / `emitFreshStartNavigationCleanup`, which already
- * pair `beginTransaction` with a synchronous `routerNavigate`.
- *
- * NOT PAINT-GATED (why not requestAnimationFrame): rAF callbacks are throttled to
- * ~0fps in occluded / backgrounded / throttled tabs, so a deferred
- * `routerNavigate` could be stranded indefinitely — zone content (event bus →
- * state) swaps instantly while the URL, sidebar highlight, and back-button state
- * lag until the tab is refocused (reproduced live: composite-view content visible
- * while `location.pathname` stayed stale for 8+ seconds, converging only on tab
- * activation). The transaction guard fills the ordering role rAF was standing in
- * for, without the paint dependency.
- */
 /**
- * Only a resource operation DECLARED `ADDRESSABLE` owns a browser URL.
- *
- * The URL builders are surface-blind — `resolveResourceUrl` happily produces a
- * pattern URL for any URL-bearing variant, including EMBEDDED (notAddressable)
- * ones — but `AppRouter` registers routes for ADDRESSABLE operations only, so
- * writing such a URL to the browser strands refresh / deep-link on the router
- * 404 (seen live 2026-08-19: a breadcrumb click on the EMBEDDED organizations
- * READ rewrote the URL to `/organizations/:id`, a route that does not exist).
- * EMBEDDED content navigates as pure zone/overlay content instead.
+ * Resource+operation pairs whose escalated SPLIT has already been reported.
  *
- * An `undefined` surface (synthetic/legacy operation objects that never passed
- * through the registry's Step-2.5 posture resolution) keeps the historical
- * URL-writing behavior — only an EXPLICIT non-addressable declaration opts out.
+ * Module-level on purpose: the report is about a DECLARATION, which does not change while the page
+ * is loaded, so one line per authored mistake is the useful volume — a fifty-row listing that warned
+ * per click would be noise nobody reads.
  */
-function resourceOperationOwnsBrowserUrl(operation) {
-    const surface = operation?.operationFrontendConfig?.surface;
-    return surface !== ResourceOperationFrontendSurface.EMBEDDED
-        && surface !== ResourceOperationFrontendSurface.API_ONLY;
-}
-function updateBrowserUrl(routerNavigate, urlPath, replace = false) {
-    // Preserve an in-flight transaction's source label (e.g. 'app_level_navigation'
-    // opened by the APP_LEVEL clean break in navigate()) — only open a fresh window
-    // when none is active (zone-level drill, goBack, non-app-level cascade). The
-    // transaction auto-commits on setTimeout(0), after React has committed the
-    // preceding zone-state emit.
-    if (!NavigationUtils.isInTransaction()) {
-        NavigationUtils.beginTransaction('controller_url_update');
-    }
-    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)
- */
-/** Put a flat resource's LIST into PRIMARY beside a detail restored into SECONDARY (#203). */
-function cascadeSiblingListIntoPrimary(params) {
-    const { resourceType, contextResourceIdentifiers, parentResourcesRequirements, registry, emit, getZoneState } = params;
-    if (getZoneState(NavigationZoneName.PRIMARY).stack.length > 0)
-        return;
-    const resourceConfig = registry.resourceConfigurations?.[resourceType];
-    if (!resourceConfig)
-        return;
-    const listContextIdentifiers = { ...contextResourceIdentifiers };
-    delete listContextIdentifiers[resourceType];
-    /*
-     * The DEFAULT addressable LIST, picked WITHOUT the context-addressability check.
-     * `pickPreferredOperationForCoreSemanticAddressability` asks "reachable given the PARENT context",
-     * which a flat STANDALONE resource can never satisfy — it answers false for an operation that is
-     * plainly addressable and reachable from the sidebar. `allowBulk` is required too: a LIST addresses
-     * a COLLECTION and the semantic filter drops bulk operations by default.
-     */
-    const listOperation = pickPreferredOperationForCoreSemantic(getOperationsForCoreSemantic(resourceConfig.operations ?? [], CoreResourceOperation.LIST, { allowBulk: true })
-        .filter((candidate) => isOperationAddressable(candidate.operationFrontendConfig)), CoreResourceOperation.LIST, { allowBulk: true });
-    if (!listOperation)
-        return;
-    emit(FrontendEvents.NAVIGATION_REPLACE, {
-        zone: NavigationZoneName.PRIMARY,
-        content: {
-            contentType: NavigationContentType.RESOURCE_OPERATION,
-            resourceContext: frontendResourceUtils.createFrontendResourceOperationContextFromOperation({
-                resourceType, operation: listOperation,
-                contextResourceIdentifiers: listContextIdentifiers,
-                parentResourcesRequirements,
-            }),
-        },
-        // No urlPath: the browser URL belongs to the DETAIL in secondary.
-        stackEntryId: NavigationUtils.generateStackEntryId(),
-        initiator: { sourceZone: NavigationZoneName.PRIMARY },
-        navigationSource: NavigationSource.URL_SYNC,
-        transition: NavigationTransition.REPLACE,
-    });
-}
-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);
-        // 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;
-            }
-        }
-        const ancestorSelfId = contextIdentifiers[ancestorResourceType];
-        const ancestorSelectionContextIdentifiers = ancestorSelfId
-            ? {
-                ...ancestorContextIdentifiers,
-                [ancestorResourceType]: ancestorSelfId,
-            }
-            : ancestorContextIdentifiers;
-        const opConfig = NavigationUtils.resolveAncestorOperationConfig(relationship, ancestorConfig, {
-            registry,
-            contextResourceIdentifiers: ancestorSelectionContextIdentifiers,
-            contextualParameters: FrontendResourceUtils.buildContextualParameters(ancestorSelectionContextIdentifiers, registry),
-        });
-        if (!opConfig)
-            continue;
-        const ancestorOp = resolveEffectiveCoreOperationFromOperation(opConfig);
-        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 — only when the ancestor operation actually
-        // owns a browser URL (declared ADDRESSABLE). Same surface gate as the main
-        // navigate() path: an EMBEDDED ancestor read must not stamp an unroutable
-        // URL onto the revealed zone entry or the browser.
-        let ancestorUrl;
-        if (resourceOperationOwnsBrowserUrl(opConfig)) {
-            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);
-        }
-    }
-}
+const reportedSplitEscalations = new Set();
+import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
+import { NavigationPlacementAdjustment } from './navigation.schemas.js';
+import { logDebug, resourceOperationOwnsBrowserUrl, updateBrowserUrl } from './navigation-controller-internals.js';
+import { cascadeAncestorZones } from './navigation-cascade.js';
 /**
  * Scoped override for {@link useNavigationController}.
  *
@@ -311,7 +77,7 @@ export const ScopedNavigationControllerContext = createContext(null);
  */
 export function useGlobalNavigationController() {
     const { emit } = useEventBus();
-    const { resourceRelationshipDepth: currentResourceRelationshipDepth, getZoneDepth, getZoneState } = useNavigationState();
+    const { resourceRelationshipDepth: currentResourceRelationshipDepth, getZoneDepth, getZoneState, contentAreaWidth } = useNavigationState();
     const { navigationLayout, currentBreakpoint, compositeViews, fullCustomViews, flowsActorsViews } = useUI();
     const { user } = useUserOrgs();
     const appScope = useAppScopeSafe();
@@ -344,6 +110,42 @@ export function useGlobalNavigationController() {
      * 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.
      */
+    /**
+     * Go back in a specific zone's stack.
+     */
+    const goBack = useCallback((zone = NavigationZoneName.PRIMARY) => {
+        const zoneState = getZoneState(zone);
+        /*
+         * The ONE go-back resolver, shared with the router error boundary and the feature-route guard,
+         * so a hosted pane's URL is composed under its host everywhere "back" can be reached. The POP
+         * is emitted whenever there is something to pop; the URL is written only when the resolver
+         * produced one (a previous entry with no address of its own leaves the URL alone, as before).
+         */
+        if (zoneState.stack.length === 0)
+            return;
+        /*
+         * The OVERLAY layer is not URL-addressed, so there is no browser URL to compose for it — popping
+         * is the whole gesture. `resolveGoBackTarget` is typed for STRUCTURAL zones and reached here
+         * through an `as NavigationZoneName` cast, which is a lie for this argument: with one entry left
+         * it would have asked `resolveZoneDismissUrl` — a HOSTED-PANE composer — about the overlay layer.
+         * Harmless only because an overlay entry carries no `urlPath`; the branch is what should say so.
+         */
+        if (zone === NavigationZone.OVERLAY) {
+            emit(FrontendEvents.NAVIGATION_POP, { zone });
+            return;
+        }
+        const target = NavigationUtils.resolveGoBackTarget({
+            zone,
+            currentBrowserUrl: currentBrowserUrlRef.current,
+            getZoneState,
+        });
+        if (!target)
+            return;
+        emit(FrontendEvents.NAVIGATION_POP, { zone });
+        if (target.browserUrl) {
+            updateBrowserUrl(routerNavigate, target.browserUrl, true);
+        }
+    }, [emit, getZoneState, routerNavigate]);
     const navigate = useCallback((options) => {
         const requestId = ++latestNavigateRequestIdRef.current;
         void (async () => {
@@ -611,6 +413,8 @@ export function useGlobalNavigationController() {
                     relationshipTransition,
                     relationshipMaxDepth,
                     viewport: currentBreakpoint,
+                    // The space the panes must actually fit in — see `NavigationResolutionContext.contentAreaWidth`.
+                    contentAreaWidth,
                     zoneOccupancy,
                     zoneDepth,
                     focusedZone,
@@ -622,7 +426,67 @@ export function useGlobalNavigationController() {
                  * never arrived, so for as long as the flag existed nothing acted on it (#411).
                  */
                 let resolution = navigationPolicyResolver.resolve(resolutionContext, navigationLayout);
-                logDebug('Policy resolved', { targetZone: resolution.targetZone, transition: resolution.transition, appearance: resolution.appearance, collapsed: resolution.collapsed, collapsedFromZone: resolution.collapsedFromZone, ephemeral: resolution.ephemeral });
+                /*
+                 * `decidedBy` / `authoredAs` / `adjustments` are the whole answer to "why did it land THERE",
+                 * and they are the reason this line is worth reading. Seven tiers of the chain can each answer
+                 * `PUSH`, so before `provenance` existed (2026-09-25) this log said what came out and nothing
+                 * about who said it — every diagnosis re-simulated the chain by hand against the layout.
+                 */
+                /*
+                 * ─── An escalated SPLIT is REPORTED, once, where it happens ─────────────────────────────────
+                 *
+                 * `collectNavigationLayoutDiagnostics` catches a `SPLIT` declared in the LAYOUT with no adjacent
+                 * zone. It cannot catch one declared on a RESOURCE — `navigationOverrides`, a relationship
+                 * transition, an action presentation — because none of those is in the layout, and the only real
+                 * instance in this repository is exactly that shape: Wonder Todos' `todos.READ` declared
+                 * `SPLIT` against a single-zone layout and every drill-in became a dialog, for the whole life of
+                 * the declaration, with the boot check reporting clean.
+                 *
+                 * Re-deriving the population statically would mean a second enumeration of every tier that can
+                 * produce a SPLIT. The resolver has ALREADY decided; reporting at the decision covers every tier
+                 * by construction and cannot drift from it. Deduplicated per resource+operation so a listing of
+                 * fifty rows warns once, and at `warn` because the application still works — it is the wrong
+                 * shape, not a broken one.
+                 */
+                const escalatedFromPersistentSplit = resolution.provenance.adjustments
+                    .includes(NavigationPlacementAdjustment.PERSISTENT_SPLIT_ESCALATED_NO_COMPANION);
+                if (escalatedFromPersistentSplit
+                    || resolution.provenance.adjustments.includes(NavigationPlacementAdjustment.SPLIT_ESCALATED_NO_ADJACENT_ZONE)) {
+                    const escalationKey = `${targetResourceType ?? 'view'}:${operationIdentifier}`;
+                    if (!reportedSplitEscalations.has(escalationKey)) {
+                        reportedSplitEscalations.add(escalationKey);
+                        /*
+                         * TWO branches raise this adjustment and they need DIFFERENT remedies. A `persistent` split
+                         * targets COMPANION specifically and does not fall back to secondary, so it escalates even
+                         * in a layout that declares a perfectly good pane — and telling that author to "declare
+                         * `zones.secondary`" sends them to change something they already have. The first version of
+                         * this message said exactly that, for both branches, and shipped the same false sentence
+                         * into the skill reference.
+                         */
+                        logger.warn(escalatedFromPersistentSplit
+                            ? 'Navigation: a PERSISTENT split was declared for this operation and the layout declares no `companion` zone — a persistent split targets `companion` specifically and does not fall back to `secondary`, so it opened as an overlay.'
+                            : 'Navigation: a SPLIT was declared for this operation and the layout declares no `secondary` or `companion` zone — it opened as an overlay instead of beside its source.', {
+                            resourceType: targetResourceType,
+                            operation: operationIdentifier,
+                            decidedBy: resolution.provenance.transitionSource,
+                            remedy: escalatedFromPersistentSplit
+                                ? 'Declare `zones.companion` in the navigation layout, or drop `persistent` so the split may use `secondary`.'
+                                : 'Declare `zones.secondary` in the navigation layout, or change this operation\'s transition to PUSH, REPLACE or OVERLAY.',
+                        });
+                    }
+                }
+                logDebug('Policy resolved', {
+                    targetZone: resolution.targetZone,
+                    transition: resolution.transition,
+                    decidedBy: resolution.provenance.transitionSource,
+                    authoredAs: resolution.provenance.authoredTransition,
+                    adjustments: resolution.provenance.adjustments,
+                    appearance: resolution.appearance,
+                    collapsed: resolution.collapsed,
+                    collapsedFromZone: resolution.collapsedFromZone,
+                    ephemeral: resolution.ephemeral,
+                    persistent: resolution.persistent,
+                });
                 // ─── INPLACE is NOT a zone outcome — hand it to the element-level host ────────────────────────
                 //
                 // Every other transition places content in a ZONE, and for as long as `INPLACE` was treated as
@@ -652,7 +516,7 @@ export function useGlobalNavigationController() {
                         hasTarget: Boolean(inPlaceTarget),
                         hostAvailable: inPlaceHost.isAvailable,
                     });
-                    resolution = navigationPolicyResolver.resolve({ ...resolutionContext, operationOverrides: [{ transition: NavigationTransition.OVERLAY }] }, navigationLayout);
+                    resolution = navigationPolicyResolver.degradeInPlaceToOverlay(resolutionContext, navigationLayout, resolution);
                 }
                 // ─── PROMOTE Clean Break ─────────────────────────────────
                 // When PROMOTE is resolved, the target is outside PRIMARY's subtree.
@@ -662,6 +526,22 @@ export function useGlobalNavigationController() {
                     emitFreshStartNavigationCleanup(emit, 'promote_navigation');
                     logDebug('PROMOTE clean break: cleared SECONDARY + COMPANION + OVERLAY');
                 }
+                // ─── OVERLAY Breakout ─────────────────────────────────────
+                // Content launched from INSIDE the overlay that resolves to a structural zone has left the
+                // overlay behind — so the overlay must not stay open over it. Only the overlay closes; the
+                // zones underneath are the context the person is returning to. See #1511 and
+                // `emitOverlayBreakoutCleanup` for the measurement.
+                //
+                // PROMOTE is excluded: it has already performed the stronger reset above.
+                if (initiator.sourceZone === NavigationZone.OVERLAY
+                    && resolution.targetZone !== NavigationZone.OVERLAY
+                    && resolution.transition !== NavigationTransition.PROMOTE) {
+                    emitOverlayBreakoutCleanup(emit, 'overlay_breakout_navigation');
+                    logDebug('OVERLAY breakout: closed the overlay it was launched from', {
+                        targetZone: resolution.targetZone,
+                        transition: resolution.transition,
+                    });
+                }
                 // ─── Cascading Orchestrator ───────────────────────────────
                 // When the resolved zone is SECONDARY or COMPANION, auto-populate ancestor
                 // zones that are currently empty so the user sees proper context.
@@ -715,14 +595,19 @@ export function useGlobalNavigationController() {
                  */
                 const primaryTopForHosting = NavigationUtils.getTopEntry(getZoneState(NavigationZoneName.PRIMARY));
                 const hostedPane = resolution.targetZone === NavigationZoneName.SECONDARY
-                    && NavigationUtils.isResourceOperationContent(enrichedContent)
                     // Only an ADDRESSABLE pane can be hosted: an entry with no URL of its own has nothing to ride
                     // the host's URL as, and flagging it would make the pane reconciler read the next view-state
-                    // change ("no `pane` in the URL") as the pane having been closed.
+                    // change ("no `pane` in the URL") as the pane having been closed. This half stays HERE because
+                    // it is about the navigation being performed rather than about the two contents.
                     && shouldUpdateUrl
                     && finalUrlPath !== undefined
-                    && primaryTopForHosting?.urlPath !== undefined
-                    && !NavigationUtils.primaryContentIsUrlDerivable(primaryTopForHosting.content);
+                    /*
+                     * The content half is `NavigationUtils.hostedPaneApplies` — the same call the URL composer
+                     * makes. It used to be spelled out here and differently there, so a non-resource pane got a
+                     * composed `?pane=` URL and an entry flagged not-hosted, and `zoneOwnsBrowserUrl` (which reads
+                     * the flag) then denied that the zone owned the URL composed for it.
+                     */
+                    && NavigationUtils.hostedPaneApplies({ paneContent: enrichedContent, primaryTop: primaryTopForHosting });
                 const eventPayload = {
                     zone: resolution.targetZone,
                     content: enrichedContent,
@@ -734,6 +619,7 @@ export function useGlobalNavigationController() {
                     appearance: resolution.appearance,
                     overlayBehavior: resolution.overlayBehavior,
                     ephemeral: resolution.ephemeral,
+                    persistent: resolution.persistent,
                     ...(hostedPane ? { hostedPane: true } : {}),
                     /*
                      * Only present when the resolver RETARGETED this placement because the authored zone is
@@ -742,12 +628,63 @@ export function useGlobalNavigationController() {
                      */
                     ...(resolution.collapsedFromZone ? { collapsedFromZone: resolution.collapsedFromZone } : {}),
                 };
-                logDebug('Emitting navigation event', { event: resolution.transition === NavigationTransition.PUSH ? 'PUSH' : 'REPLACE', zone: resolution.targetZone, finalUrlPath, hostedPane });
-                if (resolution.transition === NavigationTransition.PUSH) {
+                /*
+                 * ─── An overlay opened FROM an overlay STACKS ───────────────────────────────────────────────
+                 *
+                 * "PROMOTE, REPLACE, SPLIT, INPLACE, OVERLAY all emit as REPLACE" is right for a structural
+                 * zone, where REPLACE and PUSH are the two things a zone can do. On the OVERLAY it conflated two
+                 * different acts: OPENING an overlay, which has nothing beneath it, and opening one FROM an
+                 * overlay, which has. `NAVIGATION_REPLACE` on the overlay replaces the TOP, so the stack never
+                 * passed one entry and Back had nothing to return to.
+                 *
+                 * Measured on the workbench, 2026-09-25: an aspect popup's own references open the next aspect
+                 * as a popup, and the back arrow beside the title CLOSED the sheet instead of returning to the
+                 * previous aspect — because `canGoBack(OVERLAY)` reads a depth that was always 1, and the pop
+                 * then took the only entry with it.
+                 *
+                 * Everything else was already built: `pushOverlay` appends, `NAVIGATION_POP` pops the overlay,
+                 * `getZoneDepth` reports its depth and `canGoBack` reads that. Only nothing ever pushed.
+                 *
+                 * Narrow on purpose — the SOURCE must already be an overlay. An overlay opened from the page is
+                 * still a REPLACE, which on an empty stack is the same placement, so opening a popup, closing it
+                 * and opening another cannot accumulate.
+                 */
+                const stacksOnOverlay = resolution.targetZone === NavigationZone.OVERLAY
+                    && initiator.sourceZone === NavigationZone.OVERLAY;
+                const emitsPush = resolution.transition === NavigationTransition.PUSH || stacksOnOverlay;
+                /*
+                 * ─── A PUSH to the record directly BENEATH is a Back ────────────────────────────────────────
+                 *
+                 * Every "go to this record" affordance — a breadcrumb segment, a reference chip, a parent link —
+                 * ends here, and the one that names the entry the reader just came from must return to it. A
+                 * push stacked a SECOND copy: on Wonder Todos a task opened inside its todo, whose breadcrumb
+                 * named that todo, left the pane at `[todo, task, todo]` with one more history entry, and the
+                 * reader walked back through the task to leave (#1943). Deciding it here gives every affordance
+                 * the same answer. `ResourceLayout_Read.handleNavigateToParent` keeps its own check (#1749)
+                 * because a parent's READ may resolve to a SPLIT rather than a PUSH, which this rule does not see.
+                 *
+                 * Narrow on purpose: a structural zone, a real PUSH, the SAME destination as the entry directly
+                 * beneath, and not a TABBED zone — there the other entries are parallel tabs, not history.
+                 */
+                const targetZoneState = isStructuralZone ? getZoneState(resolution.targetZone) : undefined;
+                const entryBeneath = targetZoneState && targetZoneState.activeTabId === undefined
+                    ? targetZoneState.stack[targetZoneState.stack.length - 2]
+                    : undefined;
+                if (resolution.transition === NavigationTransition.PUSH
+                    && finalUrlPath !== undefined
+                    && entryBeneath?.urlPath
+                    && NavigationUtils.urlsAddressSameDestination(entryBeneath.urlPath, finalUrlPath)) {
+                    logDebug('PUSH names the entry beneath — going back instead', { zone: resolution.targetZone, finalUrlPath });
+                    goBack(resolution.targetZone);
+                    return;
+                }
+                logDebug('Emitting navigation event', { event: emitsPush ? 'PUSH' : 'REPLACE', zone: resolution.targetZone, finalUrlPath, hostedPane, stacksOnOverlay });
+                if (emitsPush) {
                     emit(FrontendEvents.NAVIGATION_PUSH, eventPayload);
                 }
                 else {
-                    // PROMOTE, REPLACE, SPLIT, INPLACE, OVERLAY all emit as REPLACE
+                    // PROMOTE, REPLACE, SPLIT and INPLACE all emit as REPLACE; so does an OVERLAY opened from a
+                    // structural zone, which is the first entry of an empty stack.
                     emit(FrontendEvents.NAVIGATION_REPLACE, eventPayload);
                 }
                 // Update browser URL for addressable operations in structural zones
@@ -755,10 +692,17 @@ export function useGlobalNavigationController() {
                     const isReplaceLike = replaceBrowserHistory === true
                         || resolution.transition === NavigationTransition.REPLACE
                         || resolution.transition === NavigationTransition.PROMOTE;
-                    const browserUrl = hostedPane
+                    /*
+                     * The composer decides for the two zones whose address depends on ANOTHER zone: a hosted
+                     * SECONDARY rides on the host's URL, and a COMPANION beside a hosted secondary must not
+                     * overwrite that URL — it used to write its own bare address, which dropped `?pane=` and made
+                     * the pane reconciler clear the secondary the moment the companion opened.
+                     */
+                    const browserUrl = hostedPane || resolution.targetZone === NavigationZoneName.COMPANION
                         ? NavigationUtils.resolveBrowserUrlForZoneEntry({
-                            zone: NavigationZoneName.SECONDARY,
+                            zone: resolution.targetZone,
                             entryUrlPath: finalUrlPath,
+                            paneContent: enrichedContent,
                             currentBrowserUrl: currentBrowserUrlRef.current,
                             getZoneState,
                         }) ?? finalUrlPath
@@ -795,7 +739,9 @@ export function useGlobalNavigationController() {
         getOperationContextNeeds,
         routerNavigate,
         getZoneState,
+        contentAreaWidth,
         inPlaceHost,
+        goBack,
     ]);
     const navigateToResource = useCallback((resourceContext, initiator, urlPath, transitionOverride) => {
         const content = {
@@ -813,43 +759,60 @@ export function useGlobalNavigationController() {
         navigate({ content, initiator, urlPath, relationshipTransition: transitionOverride });
     }, [navigate]);
     /**
-     * Go back in a specific zone's stack.
+     * Close the top overlay entry.
      */
-    const goBack = useCallback((zone = NavigationZoneName.PRIMARY) => {
-        const zoneState = getZoneState(zone);
-        /*
-         * The ONE go-back resolver, shared with the router error boundary and the feature-route guard,
-         * so a hosted pane's URL is composed under its host everywhere "back" can be reached. The POP
-         * is emitted whenever there is something to pop; the URL is written only when the resolver
-         * produced one (a previous entry with no address of its own leaves the URL alone, as before).
-         */
-        if (zoneState.stack.length === 0)
+    const closeOverlay = useCallback(() => {
+        const topOverlay = NavigationUtils.getTopEntry(getZoneState(NavigationZone.OVERLAY));
+        if (!topOverlay)
             return;
-        const target = NavigationUtils.resolveGoBackTarget({
-            zone: zone,
+        emit(FrontendEvents.NAVIGATION_CLOSE, { zone: NavigationZone.OVERLAY, stackEntryId: topOverlay.id });
+    }, [emit, getZoneState]);
+    /**
+     * DISMISS an adjacent structural zone — close the pane, not one step of it.
+     *
+     * ## Why this is not `goBack`
+     *
+     * `goBack` pops ONE entry. A reader who drilled three records deep into a pane and wants their
+     * width back would have to press it three times, and the first two presses look like the control
+     * doing nothing. Dismiss clears the zone's whole stack in one gesture, which is what "close this
+     * pane" means everywhere else it exists.
+     *
+     * ## Why the URL is written, and why it is the SAME url `goBack` writes
+     *
+     * A pane that leaves the layout must leave the address too, or a reload reopens it — measured on
+     * the workbench (2026-09-22) when a pop wrote nothing and `?pane=` survived. Both gestures leave
+     * the same layout behind, so `resolveZoneDismissUrl` owns the answer for both; a second copy of
+     * that walk is how one of them comes to write a pane's bare address, which the reconciler cannot
+     * claim and therefore rebuilds into primary.
+     *
+     * The URL is resolved BEFORE the zone is cleared, because the answer is read off the zone states
+     * as they stand while the pane is still there.
+     *
+     * OVERLAY is not dismissable this way — it has `closeOverlay`, its own stack semantics and its own
+     * URL rules — and PRIMARY is not dismissable at all: there is no layout left after it.
+     */
+    const dismissZone = useCallback((zone) => {
+        if (zone === NavigationZoneName.PRIMARY)
+            return;
+        if (getZoneState(zone).stack.length === 0)
+            return;
+        const browserUrl = NavigationUtils.resolveZoneDismissUrl({
+            zone,
             currentBrowserUrl: currentBrowserUrlRef.current,
             getZoneState,
         });
-        if (!target)
-            return;
-        emit(FrontendEvents.NAVIGATION_POP, { zone });
-        if (target.browserUrl) {
-            updateBrowserUrl(routerNavigate, target.browserUrl, true);
+        emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone });
+        if (browserUrl) {
+            updateBrowserUrl(routerNavigate, browserUrl, 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]);
+    return useMemo(() => ({ navigate, navigateToResource, goBack, closeOverlay, dismissZone, canGoBack, resourceRelationshipDepth: currentResourceRelationshipDepth }), [navigate, navigateToResource, goBack, closeOverlay, dismissZone, canGoBack, currentResourceRelationshipDepth]);
 }
 /**
  * Hook to control navigation in the application.
@@ -890,800 +853,4 @@ export function useNavigationController() {
     const globalController = useGlobalNavigationController();
     return scopedController ?? globalController;
 }
-// ================================
-// 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 prefersAdjacentZoneForDetail = depth === 0
-            && hasSecondary
-            && operation !== undefined
-            && NavigationUtils.layoutSplitsOperationFromPrimary(resolvedNavigationLayout, operation);
-        const targetZone = NavigationUtils.resolveResourceTargetZone(depth, {
-            hasSecondary,
-            hasCompanion,
-            prefersAdjacentZoneForDetail,
-        });
-        /*
-         * 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;
-        }
-        // 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,
-        });
-        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,
-        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;
-        // 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, 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;
-        // 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, 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 (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() {
-    const location = useLocation();
-    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 reconstruct on their transaction-aware retry.
-        }
-        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.
- *
- * Never writes the URL — the browser owns it; this only brings the zone up to match.
- */
-export function useHostedPaneRouteSync() {
-    const location = useLocation();
-    const { emit } = useEventBus();
-    const { getZoneState } = useNavigationState();
-    const { registry } = useResourceRegistry();
-    const appScope = useAppScopeSafe();
-    const { navigationLayout, currentBreakpoint } = useUI();
-    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;
-        }
-        // (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,
-        });
-        // The split appearance a click from PRIMARY would have resolved — the pane is the same pane
-        // whether it arrived by click or by URL.
-        const appearance = (currentBreakpoint !== undefined
-            ? resolveViewportDiscriminated(navigationLayout?.zones?.primary?.appearance?.split, currentBreakpoint)
-            : undefined) ?? SplitAppearance.PANEL;
-        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,
-            appearance,
-            hostedPane: true,
-        });
-        lastSyncedPath.current = currentUrl;
-    }, [
-        currentUrl,
-        location.pathname,
-        emit,
-        getZoneState,
-        registry,
-        appScope?.currentUserId,
-        appScope?.currentOrganizationId,
-        appScope?.currentApplicationId,
-        appScope?.currentAnonymousUserId,
-        liveAppScopeContextIdentifiers,
-        navigationLayout,
-        currentBreakpoint,
-        retryTick,
-        scheduleRetry,
-        clearRetry,
-    ]);
-}
-/**
- * Matches the unified Settings Hub URL family.
- * `/settings` → `{ isSettings: true }`; `/settings/:sectionRef` →
- * `{ isSettings: true, sectionRef }`.
- */
-function matchSettingsHubPath(pathname) {
-    if (pathname === CommonRoutePaths.settings)
-        return { isSettings: true };
-    const prefix = `${CommonRoutePaths.settings}/`;
-    if (pathname.startsWith(prefix)) {
-        const sectionRef = pathname.slice(prefix.length);
-        return { isSettings: true, sectionRef: sectionRef.length > 0 ? sectionRef : 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 = useLocation();
-    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 } = matchSettingsHubPath(location.pathname);
-        const overlayStack = state.overlay;
-        const topEntry = overlayStack.length > 0 ? overlayStack[overlayStack.length - 1] : undefined;
-        let topIsHub = false;
-        let topSectionRef;
-        if (topEntry && topEntry.content.contentType === NavigationContentType.SETTINGS_HUB) {
-            topIsHub = true;
-            topSectionRef = topEntry.content.sectionRef;
-        }
-        if (isSettings) {
-            // Already showing the hub at the requested section → converged, nothing to do.
-            if (topIsHub && topSectionRef === sectionRef) {
-                lastEmitRef.current = null;
-                return;
-            }
-            const action = topIsHub ? FrontendEvents.NAVIGATION_REPLACE : FrontendEvents.NAVIGATION_PUSH;
-            const emitKey = `${action}|${location.pathname}|${sectionRef ?? ''}|${overlayStack.length}`;
-            if (lastEmitRef.current === emitKey)
-                return;
-            lastEmitRef.current = emitKey;
-            emit(action, {
-                zone: NavigationZone.OVERLAY,
-                content: { contentType: NavigationContentType.SETTINGS_HUB, sectionRef },
-                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=useNavigationController.js.map