@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.1

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

@@ -14,7 +14,7 @@
  * - 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 { createContext, useCallback, useContext, 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';
@@ -28,30 +28,80 @@ import { buildExecutionRouteUrlPath, extractExecutionRouteContextResourceIdentif
 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 { NavigationTransition, NavigationZoneName, OverlayAppearance, CoreResourceOperation, ResourceOperationFrontendSurface, 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 { CommonRoutePaths } from '../../core/runtime/routes.frontend.definitions.js';
 import { FrontendResourceUtils, frontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
-import { resolveEffectiveCoreOperationFromOperation } from '../../core/resources/operation-semantics.frontend.utils.js';
+import { normalizeContextResourceIdentifiersForTransport } from '../../core/resources/context-resource-identifiers.frontend.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 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.
+ * 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`).
  *
- * 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.
+ * 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.
+ *
+ * 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.
+ */
+function resourceOperationOwnsBrowserUrl(operation) {
+    const surface = operation?.operationFrontendConfig?.surface;
+    return surface !== ResourceOperationFrontendSurface.EMBEDDED
+        && surface !== ResourceOperationFrontendSurface.API_ONLY;
+}
 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 });
-    });
+    // 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
@@ -112,11 +162,6 @@ function cascadeAncestorZones(targetContent, resolvedZone, registry, contextIden
         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,
@@ -143,8 +188,21 @@ function cascadeAncestorZones(targetContent, resolvedZone, registry, contextIden
                 ancestorContextIdentifiers[contextKey] = id;
             }
         }
-        // Also include the ancestor's own ID if it's a READ operation
         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;
         }
@@ -158,11 +216,16 @@ function cascadeAncestorZones(targetContent, resolvedZone, registry, contextIden
             contentType: NavigationContentType.RESOURCE_OPERATION,
             resourceContext: ancestorResourceContext,
         };
-        // Resolve URL for ancestor
+        // 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;
-        const resolved = NavigationUtils.resolveResourceUrl(ancestorConfig, opConfig, ancestorContextIdentifiers, registry.allResourceFieldIdentifiers, ancestorParentReqs);
-        if (resolved?.resolvedUrl) {
-            ancestorUrl = resolved.resolvedUrl;
+        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', {
@@ -188,17 +251,37 @@ function cascadeAncestorZones(targetContent, resolvedZone, registry, contextIden
     }
 }
 /**
- * Hook to control navigation in the application
+ * Scoped override for {@link useNavigationController}.
+ *
+ * When a provider supplies a controller here (e.g. the Settings Hub's
+ * per-section navigation host), `useNavigationController()` returns IT instead of
+ * the global controller — so resource surfaces rendered inside that provider
+ * drill / go back / run post-action navigation **within** the host's own stack
+ * rather than escaping to the global zones (which, for an overlay-hosted surface,
+ * means leaving the hub and 404-ing on unregistered routes). `null` (the default)
+ * means "use the global controller", so every consumer outside such a provider is
+ * byte-for-byte unchanged.
  */
-export function useNavigationController() {
+export const ScopedNavigationControllerContext = createContext(null);
+/**
+ * Builds the global navigation controller — the app-level zone/URL navigation
+ * pipeline. Most code should call {@link useNavigationController} (which returns a
+ * scoped override when one is in context); call this directly only from
+ * navigation-runtime internals that must always target the global zones, or from
+ * a scoped provider that needs the global controller to delegate to.
+ */
+export function useGlobalNavigationController() {
     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 { registry, getOperationContextNeeds } = useResourceRegistry();
     const routerNavigate = useNavigate();
     const latestNavigateRequestIdRef = useRef(0);
+    // The element-level host, read from context so the NEAREST collection wins — see the INPLACE
+    // branch in navigateToResource. UNAVAILABLE (never undefined) on every surface that has none.
+    const inPlaceHost = useInPlaceOperation();
     // Note: Context identifiers are now computed per-navigation call with scope filtering
     // to prevent border effects where unrelated identifiers leak into the navigation chain
     /**
@@ -218,6 +301,16 @@ export function useNavigationController() {
             let { content, initiator, urlPath, contextResourceIdentifiers, relationshipTransition, replaceBrowserHistory, } = options;
             try {
                 logDebug('navigate() called', { contentType: content.contentType, sourceZone: initiator.sourceZone, urlPath });
+                // The Settings Hub is URL-driven: it reconstructs into the overlay from its
+                // route via `useSettingsHubRouterSync`. Zone resolution would push it into a
+                // structural zone (the controller never updates the URL for overlay entries
+                // — see `isStructuralZone` below), so instead navigate to its route and let
+                // the route sync own the overlay. Every launcher caller that dispatches
+                // SETTINGS_HUB content therefore converges on one URL-first path.
+                if (content.contentType === NavigationContentType.SETTINGS_HUB) {
+                    routerNavigate(urlPath ?? CommonRoutePaths.settings);
+                    return;
+                }
                 if (!navigationLayout) {
                     logDebug('navigate() aborted: no navigationLayout');
                     return;
@@ -262,7 +355,11 @@ export function useNavigationController() {
                     }
                 }
                 let isAddressable = false;
+                let operationSurface;
                 let operationOverrides;
+                let actionPresentation;
+                let actionPresentationTransition;
+                let actionPresentationIsAuthored = false;
                 let selectedRoutePathParameters;
                 let selectedRouteTemplateUrl = urlPath;
                 let selectedResolvedUrl;
@@ -271,8 +368,30 @@ export function useNavigationController() {
                 let enrichedContent = content;
                 if (NavigationUtils.isResourceOperationContent(content)) {
                     const operation = content.resourceContext.operation;
-                    isAddressable = operation?.operationFrontendConfig?.isAddressable ?? false;
                     operationOverrides = operation?.operationFrontendConfig?.navigationOverrides;
+                    operationSurface = operation?.operationFrontendConfig?.surface;
+                    // The action-presentation ALIAS, read from the same place as the two lines above rather than
+                    // threaded in by the caller. Navigation is reached from several action surfaces (the item bar,
+                    // the bulk bar, the collection toolbar, a breadcrumb, a picker) and a parameter would have to
+                    // be passed correctly by every one of them; reading it off the operation means it cannot be
+                    // forgotten at a call site.
+                    actionPresentation = resolveResourceOperationActionPresentation(operation);
+                    actionPresentationTransition = resolveActionPresentationTransition(actionPresentation);
+                    actionPresentationIsAuthored = operation?.operationFrontendConfig?.actionPresentation !== undefined;
+                    // ─── F4: headless content is not navigable — refuse loud ─────────
+                    // An API_ONLY operation has NO rendered interface by contract; pushing
+                    // it as zone content produces a broken page. Callers are supposed to
+                    // pre-filter (action bars, breadcrumb, pickers all do), but the
+                    // chokepoint must not depend on N callers remembering — refuse here,
+                    // with an error the author can act on, and navigate nothing.
+                    if (operationSurface === ResourceOperationFrontendSurface.API_ONLY) {
+                        logger.error('[useNavigationController] refused navigation to API_ONLY (headless) operation — it has no rendered interface', {
+                            resourceType: content.resourceContext.resourceType,
+                            operationIdentifier: String(operation?.operationIdentifier),
+                            sourceZone: initiator.sourceZone,
+                        });
+                        return;
+                    }
                     // Use unified URL resolver to select the best route path
                     const resourceType = content.resourceContext.resourceType;
                     const resourceConfig = registry.resourceConfigurations?.[resourceType];
@@ -284,6 +403,11 @@ export function useNavigationController() {
                             selectedResolvedUrl = resolved.resolvedUrl;
                         }
                     }
+                    // Declared-surface gate first: an EMBEDDED/API_ONLY operation never
+                    // claims addressability, however resolvable its pattern URL is. This
+                    // both suppresses the browser-URL write (see shouldUpdateUrl below) and
+                    // keeps the policy resolver's `isAddressable` input truthful.
+                    isAddressable = resourceOperationOwnsBrowserUrl(operation) && Boolean(selectedResolvedUrl ?? urlPath);
                     // 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).
@@ -300,60 +424,25 @@ export function useNavigationController() {
                             });
                             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;
-                            }
-                        }
+                        // We deliberately do NOT re-evaluate `enabledCondition` here from
+                        // navigation-time data. The navigation layer has no access to the
+                        // operation's `currentObject` (it is never threaded through navigate()),
+                        // so a condition that reads the record's own fields — e.g. todos
+                        // `change_status`: `currentObject.assignedToUserId === me &&
+                        // currentObject.status !== COMPLETED` — would be evaluated against an
+                        // empty object and spuriously block a navigation the action bar already
+                        // validated against the REAL loaded object. (`needsObjectContext` only
+                        // tracks parent/child context, not the object's own fields, so
+                        // object-centric conditions were slipping into this block and failing.)
+                        //
+                        // enabledCondition stays enforced in the two places that have complete,
+                        // authoritative inputs: the action bar / display gate (evaluates the
+                        // full condition with the loaded `currentObject` before enabling the
+                        // action) and the backend (rejects the operation on execution). Object-
+                        // dependent conditions are therefore deferred here exactly like
+                        // objectContext-dependent ones already were — re-deriving them from
+                        // incomplete data only produced false negatives (change_status
+                        // regression, 2026-07).
                     }
                     if (requestId !== latestNavigateRequestIdRef.current) {
                         logDebug('navigate() aborted: superseded before state mutation', {
@@ -459,16 +548,49 @@ export function useNavigationController() {
                     operation: operationIdentifier,
                     effectiveOperation,
                     resourceType: targetResourceType,
-                    isAddressable,
+                    operationSurface,
                     operationOverrides: operationOverrides,
+                    actionPresentationTransition,
+                    actionPresentationIsAuthored,
                     relationshipTransition,
                     viewport: currentBreakpoint,
                     zoneOccupancy,
                     focusedZone,
                 };
                 // collapsed is available in the result for Phase 3E (NavigationContentAreas rendering)
-                const resolution = navigationPolicyResolver.resolve(resolutionContext, navigationLayout);
+                let resolution = navigationPolicyResolver.resolve(resolutionContext, navigationLayout);
                 logDebug('Policy resolved', { targetZone: resolution.targetZone, transition: resolution.transition, appearance: resolution.appearance, collapsed: resolution.collapsed, ephemeral: resolution.ephemeral });
+                // ─── 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
+                // one it fell through to the emit below and left as `NAVIGATION_REPLACE` — swapping the whole
+                // zone, which is precisely what its own contract says it is not ("operates at the element level,
+                // not the zone level", "surrounding items remain visible", "the zone stack is unchanged"). The
+                // preset inline-edit kit has shipped that since it was written.
+                //
+                // The host is read through REACT CONTEXT rather than reached by an event, and that choice is
+                // load-bearing: the nearest provider wins automatically, so a nested child list transforms ITS
+                // row and not the parent list's row of the same resource type. An event would have to carry
+                // enough identity to disambiguate two mounted collections and would still be guessing.
+                //
+                // When there is no host — a breadcrumb, a picker, a detail page, any surface with no collection
+                // above it — it degrades to an OVERLAY. Note it must NOT degrade to the zone replace it did
+                // before: that is the defect, not the fallback.
+                if (resolution.transition === NavigationTransition.INPLACE) {
+                    const inPlaceTarget = NavigationUtils.isResourceOperationContent(enrichedContent)
+                        ? resolveInPlaceTargetForContent(enrichedContent, effectiveOperation)
+                        : undefined;
+                    if (inPlaceTarget && inPlaceHost.isAvailable) {
+                        logDebug('INPLACE resolved to the element-level host', { kind: inPlaceTarget.kind });
+                        inPlaceHost.open(inPlaceTarget);
+                        return;
+                    }
+                    logDebug('INPLACE has no element-level host here — degrading to overlay', {
+                        hasTarget: Boolean(inPlaceTarget),
+                        hostAvailable: inPlaceHost.isAvailable,
+                    });
+                    resolution = navigationPolicyResolver.resolve({ ...resolutionContext, operationOverrides: [{ transition: NavigationTransition.OVERLAY }] }, navigationLayout);
+                }
                 // ─── 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"
@@ -569,16 +691,24 @@ export function useNavigationController() {
         fullCustomViews,
         flowsActorsViews,
         getOperationContextNeeds,
-        evaluateOperationEnabled,
         routerNavigate,
         getZoneState,
+        inPlaceHost,
     ]);
-    const navigateToResource = useCallback((resourceContext, initiator, urlPath) => {
+    const navigateToResource = useCallback((resourceContext, initiator, urlPath, transitionOverride) => {
         const content = {
             contentType: NavigationContentType.RESOURCE_OPERATION,
             resourceContext,
         };
-        navigate({ content, initiator, urlPath });
+        // `transitionOverride` is a caller-forced transition that wins over the
+        // source-zone policy (it feeds the resolver's high-priority caller-transition
+        // channel — see `NavigateOptions.relationshipTransition`). The canonical use
+        // is a breakout: a mutation hosted in an OVERLAY (create/update dialog) that,
+        // on success, must reveal the resulting record in a structural zone via
+        // PROMOTE — otherwise the follow-up navigation resolves through
+        // `fromOverlay.transitions` and stacks the record *inside* the transient
+        // dialog, leaving the popup stuck open.
+        navigate({ content, initiator, urlPath, relationshipTransition: transitionOverride });
     }, [navigate]);
     /**
      * Go back in a specific zone's stack.
@@ -619,6 +749,45 @@ export function useNavigationController() {
     }, [getZoneDepth]);
     return useMemo(() => ({ navigate, navigateToResource, goBack, closeOverlay, canGoBack, resourceRelationshipDepth: currentResourceRelationshipDepth }), [navigate, navigateToResource, goBack, closeOverlay, canGoBack, currentResourceRelationshipDepth]);
 }
+/**
+ * Hook to control navigation in the application.
+ *
+ * Returns the scoped controller from {@link ScopedNavigationControllerContext}
+ * when one is in context (the Settings Hub section host installs one so in-hub
+ * related actions stay within the section panel), otherwise the global
+ * controller. Both hooks run unconditionally — the global builder is
+ * effect-free, so building it even when the scoped controller wins costs nothing
+ * (and is exactly what every one of the ~27 existing call sites already does).
+ */
+/**
+ * What an `INPLACE` resolution should hand the element-level host, or `undefined` when this content
+ * cannot be hosted in one.
+ *
+ * `CREATE` is the shape that has no element yet: the collection materialises a NEW one to collect
+ * the input, which is what the transition's own docstring describes ("a create form appears inline
+ * in the list"). Everything else must name the element it transforms, and content that cannot
+ * resolve one is not hostable — the caller degrades rather than transforming an arbitrary row.
+ */
+function resolveInPlaceTargetForContent(content, effectiveOperation) {
+    const resourceContext = content.resourceContext;
+    const operation = resourceContext.operation;
+    if (!operation) {
+        return undefined;
+    }
+    if (effectiveOperation === CoreResourceOperation.CREATE
+        || effectiveOperation === CoreResourceOperation.CREATE_MANY) {
+        return { kind: InPlaceOperationTargetKind.CREATE, operation, resourceContext };
+    }
+    const elementId = frontendResourceUtils.getResourceId(resourceContext.contextResourceIdentifiers?.[resourceContext.resourceType]);
+    return elementId
+        ? { kind: InPlaceOperationTargetKind.ELEMENT, elementId, operation, resourceContext }
+        : undefined;
+}
+export function useNavigationController() {
+    const scopedController = useContext(ScopedNavigationControllerContext);
+    const globalController = useGlobalNavigationController();
+    return scopedController ?? globalController;
+}
 // ================================
 // Router Sync Hook (merged from RouterNavigationSync)
 // ================================
@@ -792,12 +961,7 @@ export function useRouterSync(resourceType, operation, routePathParameters) {
         // 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;
-            }
+            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)
@@ -1012,4 +1176,219 @@ export function useEnginePageRouterSync(pageRef) {
         lastSyncedPath.current = currentUrl;
     }, [pageRef, emit, getZoneState, currentUrl, retryTick, scheduleTransactionRetry, clearTransactionRetry]);
 }
-//# sourceMappingURL=useNavigationController.js.map
+/**
+ * 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 is already the visible top of a structural zone → no-op
+ *     (controller nav / deep-link reconstruction already landed it correctly).
+ *  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.
+ *  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 reconcile.
+        if (owner?.isTop) {
+            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]);
+}
+/**
+ * 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