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

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

@@ -4,7 +4,12 @@
  * Shared utility functions for the navigation system.
  * Centralized to avoid duplication across navigation modules.
  */
-import { CascadeDirection, CoreResourceOperation, coreResourceShared_FieldIdentifier, NavigationZoneName, ParentDisplay, ResourcesConfigOperationsUrlsBuilderUtils, ResourceRelationshipCardinality, Resources_SharedUtils, } from '@wildo-ai/saas-models';
+import { CascadeDirection, CoreResourceOperation, coreResourceShared_FieldIdentifier, NavigationTransition, NavigationZoneName, ParentDisplay, ResourcesConfigOperationsUrlsBuilderUtils, ResourceRelationshipCardinality, Resources_SharedUtils, } from '@wildo-ai/saas-models';
+import { COMPOSITE_ROUTE_CONTEXT_QUERY_PARAM_PREFIX } from '../../core/config/composite-view.schemas.js';
+import { CHART_ROUTE_CONTEXT_QUERY_PARAM_PREFIX, CHART_ROUTE_PATH_PREFIX } from '../../core/config/chart-view.frontend.schemas.js';
+import { HOSTED_PANE_QUERY_PARAM } from './hosted-pane.constants.js';
+import { EXECUTION_ROUTE_CONTEXT_QUERY_PARAM_PREFIX } from '../../core/config/execution-view.schemas.js';
+import { isOperationAddressable } from '../../core/resources/resources.frontend.schemas.js';
 import { frontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
 import { pickPreferredOperationForCoreSemantic, resolveEffectiveCoreOperationFromOperation, } from '../../core/resources/operation-semantics.frontend.utils.js';
 import { pickPreferredOperationForCoreSemanticAddressability } from '../../core/resources/resource-addressability.frontend.utils.js';
@@ -58,6 +63,48 @@ export class NavigationUtils {
     static _transactionActive = false;
     static _transactionSource = null;
     static _transactionAutoCommitTimer = null;
+    /**
+     * Monotonic counter, bumped every time a navigation transaction ENDS.
+     *
+     * The transaction is GLOBAL — a static flag — but the mechanism that waited for it to close used to
+     * be per-instance: each route-mounted sync hook set its own `setTimeout(0)` and re-read the flag.
+     * A hook that unmounted before its timer fired took the retry with it, and the reconstruction it was
+     * deferring simply never happened (#212). That is not a rare race: clearing the structural zones
+     * REMOUNTS the route element, so the instance that scheduled the retry is routinely not the instance
+     * that needs it.
+     *
+     * A global signal cannot be lost that way. It is an EPOCH rather than an event, so a hook that mounts
+     * after the commit is not waiting for a notification that already fired — it reads the current value
+     * and, finding no active transaction, proceeds immediately.
+     */
+    static _transactionEpoch = 0;
+    static _transactionListeners = new Set();
+    /** Subscribe to transaction ENDINGS. Returns an unsubscribe. */
+    static subscribeToTransactionState(listener) {
+        NavigationUtils._transactionListeners.add(listener);
+        return () => {
+            NavigationUtils._transactionListeners.delete(listener);
+        };
+    }
+    /** The current epoch — changes exactly when a transaction ends. */
+    static getTransactionEpoch() {
+        return NavigationUtils._transactionEpoch;
+    }
+    /**
+     * End the transaction and tell everyone waiting on it.
+     *
+     * One private door for all three endings — auto-commit, explicit commit, and the 5s safety net — so a
+     * future fourth cannot end a transaction without waking the hooks that deferred to it. That is
+     * exactly how the per-instance timer failed: the ending and the waiting were wired separately.
+     */
+    static endTransactionAndNotify() {
+        NavigationUtils._transactionActive = false;
+        NavigationUtils._transactionSource = null;
+        NavigationUtils._transactionEpoch += 1;
+        for (const listener of [...NavigationUtils._transactionListeners]) {
+            listener();
+        }
+    }
     static _transactionSafetyTimer = null;
     /**
      * Begin a navigation transaction.
@@ -87,8 +134,7 @@ export class NavigationUtils {
         NavigationUtils._transactionAutoCommitTimer = setTimeout(() => {
             if (NavigationUtils._transactionActive) {
                 logDebug('beginTransaction: AUTO-COMMIT (setTimeout(0))', { source: NavigationUtils._transactionSource });
-                NavigationUtils._transactionActive = false;
-                NavigationUtils._transactionSource = null;
+                NavigationUtils.endTransactionAndNotify();
             }
             NavigationUtils._transactionAutoCommitTimer = null;
         }, 0);
@@ -96,8 +142,7 @@ export class NavigationUtils {
         NavigationUtils._transactionSafetyTimer = setTimeout(() => {
             if (NavigationUtils._transactionActive) {
                 console.warn('[NavigationUtils] Transaction safety timeout — force committing after 5s', { source: NavigationUtils._transactionSource });
-                NavigationUtils._transactionActive = false;
-                NavigationUtils._transactionSource = null;
+                NavigationUtils.endTransactionAndNotify();
             }
             NavigationUtils._transactionSafetyTimer = null;
         }, 5000);
@@ -114,8 +159,7 @@ export class NavigationUtils {
             return;
         }
         logDebug('commitTransaction: COMMITTED', { source: NavigationUtils._transactionSource });
-        NavigationUtils._transactionActive = false;
-        NavigationUtils._transactionSource = null;
+        NavigationUtils.endTransactionAndNotify();
         // Clear pending timers
         if (NavigationUtils._transactionAutoCommitTimer) {
             clearTimeout(NavigationUtils._transactionAutoCommitTimer);
@@ -143,22 +187,17 @@ export class NavigationUtils {
         return NavigationUtils._transactionSource;
     }
     /**
-     * Build the canonical browser URL string used by navigation ownership checks.
-     *
-     * We compare full addressable URLs (`pathname + search`) rather than mixing
-     * pathname-only and query-bearing variants across different runtime entry
-     * points. This keeps URL-first reconstruction truthful for views that encode
-     * meaningful state in query params.
+     * The canonical browser URL string (`pathname + search`) every ownership check and every stamp
+     * starts from. The query string is kept because part of it is ADDRESS (see
+     * {@link isAddressQueryParam}); which part is decided at comparison time, never here.
      */
     static buildBrowserUrl(pathname, search = '') {
         return search ? `${pathname}${search}` : pathname;
     }
     /**
-     * Normalize a stored URL before route-owner comparisons.
-     *
-     * We intentionally preserve query parameters because they participate in
-     * addressable navigation state, but drop hash fragments because the runtime
-     * does not model them as navigation ownership signals.
+     * Normalize a URL before it is compared or decomposed: the hash fragment is dropped because the
+     * runtime does not model it. The query string is kept — {@link urlsAddressSameDestination} is what
+     * decides which of its keys count.
      */
     static normalizeComparableUrl(urlPath) {
         if (!urlPath) {
@@ -167,19 +206,230 @@ export class NavigationUtils {
         const [withoutHash] = urlPath.split('#');
         return withoutHash || undefined;
     }
+    // ──────────────────────────────────────────────────────────────
+    // URL identity: DESTINATION versus VIEW STATE
+    // ──────────────────────────────────────────────────────────────
+    /**
+     * Whether a query-string key is part of a destination's ADDRESS rather than its view state.
+     *
+     * The framework itself writes three families of address params — a view route's context
+     * identifiers (`composite_ctx_*`, `chart_ctx_*`, `execution_ctx_*`) — and the hosted-pane param.
+     * A CHART route is the exception that keeps every param: `extractChartRouteUrlParamValues` reads
+     * all non-context keys as the chart's url-param VALUES, so for that route they are address too.
+     *
+     * Everything else — `?section=`, `?dataMode=`, a filter a view mirrors — is view state: it changes
+     * WHAT a destination shows, not WHICH destination is shown. Route ownership used to compare the
+     * whole URL string, so every such change made the URL "owned by nobody" and the back/forward
+     * reconciler tore every zone down to rebuild the very destination still on screen (measured on the
+     * workbench creation board: each tab click remounted the board).
+     */
+    static isAddressQueryParam(pathname, key) {
+        if (key === HOSTED_PANE_QUERY_PARAM)
+            return true;
+        if (pathname.startsWith(CHART_ROUTE_PATH_PREFIX))
+            return true;
+        return key.startsWith(COMPOSITE_ROUTE_CONTEXT_QUERY_PARAM_PREFIX)
+            || key.startsWith(CHART_ROUTE_CONTEXT_QUERY_PARAM_PREFIX)
+            || key.startsWith(EXECUTION_ROUTE_CONTEXT_QUERY_PARAM_PREFIX);
+    }
+    /** `pathname` and parsed `search` of a browser-style URL path; the hash is dropped. */
+    static splitUrlPath(urlPath) {
+        const [withoutHash = ''] = urlPath.split('#');
+        const questionMark = withoutHash.indexOf('?');
+        if (questionMark < 0) {
+            return { pathname: withoutHash, params: new URLSearchParams() };
+        }
+        return {
+            pathname: withoutHash.slice(0, questionMark),
+            params: new URLSearchParams(withoutHash.slice(questionMark + 1)),
+        };
+    }
+    /** Reassemble a `splitUrlPath` result; an empty query yields the bare pathname. */
+    static joinUrlPath(pathname, params) {
+        const search = params.toString();
+        return search.length > 0 ? `${pathname}?${search}` : pathname;
+    }
+    /**
+     * The DESTINATION a URL addresses: its pathname plus its address params, in a canonical order.
+     * Two URLs with the same key show the same destination and may differ only in view state.
+     */
+    static getUrlDestinationKey(urlPath) {
+        if (!urlPath)
+            return undefined;
+        const { pathname, params } = NavigationUtils.splitUrlPath(urlPath);
+        const addressEntries = [...params.entries()]
+            .filter(([key]) => NavigationUtils.isAddressQueryParam(pathname, key))
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return NavigationUtils.joinUrlPath(pathname, new URLSearchParams(addressEntries));
+    }
+    static urlsAddressSameDestination(a, b) {
+        const keyA = NavigationUtils.getUrlDestinationKey(a);
+        return keyA !== undefined && keyA === NavigationUtils.getUrlDestinationKey(b);
+    }
+    // ──────────────────────────────────────────────────────────────
+    // Hosted panes: a SECONDARY destination carried by a non-derivable PRIMARY's URL
+    // ──────────────────────────────────────────────────────────────
+    /**
+     * Whether a reload could rebuild this PRIMARY content from a resource URL alone.
+     *
+     * A RESOURCE_OPERATION can: a flat detail's URL implies its own list (#203) and a nested one names
+     * its ancestors. Every other kind — a composite view, a canvas, a chart, an engine page — has an
+     * address of its own that no resource URL implies, so a pane opened beside it must not take the
+     * URL over. An EMPTY primary is "derivable" too: there is nothing to host.
+     */
+    static primaryContentIsUrlDerivable(content) {
+        return content === undefined || content.contentType === NavigationContentType.RESOURCE_OPERATION;
+    }
+    /** `hostUrl` is the browser URL without the pane param; `paneUrl` the pane's own address, if any. */
+    static decomposeHostedPaneBrowserUrl(browserUrl) {
+        const { pathname, params } = NavigationUtils.splitUrlPath(browserUrl);
+        const paneUrl = params.get(HOSTED_PANE_QUERY_PARAM) ?? undefined;
+        params.delete(HOSTED_PANE_QUERY_PARAM);
+        const hostUrl = NavigationUtils.joinUrlPath(pathname, params);
+        return paneUrl && paneUrl.length > 0 ? { hostUrl, paneUrl } : { hostUrl };
+    }
+    /** The host's URL (its own pane param, if any, replaced) carrying `paneUrl` as the hosted pane. */
+    static composeHostedPaneBrowserUrl(hostUrl, paneUrl) {
+        const { pathname, params } = NavigationUtils.splitUrlPath(hostUrl);
+        params.delete(HOSTED_PANE_QUERY_PARAM);
+        params.set(HOSTED_PANE_QUERY_PARAM, paneUrl);
+        return NavigationUtils.joinUrlPath(pathname, params);
+    }
     /**
-     * Resolve which structural zone currently owns a URL.
+     * The browser URL to write when `zone`'s visible entry is (or becomes) `entryUrlPath`.
+     *
+     * ONE composer for every write site — `navigate()`, `goBack()` in either zone — because the
+     * composed form has to be produced identically wherever a URL leaves the controller, and two
+     * hand-written compositions are how the pane's address and the host's would drift apart.
      *
-     * URL-first reconstruction must only trust the visible top entry of a zone,
-     * never a stale entry buried deeper in a backstack. We therefore scan the
-     * structural zones from deepest to shallowest and only match against each
-     * zone's current top entry.
+     * - SECONDARY beside a NON-derivable primary → the host's address carrying the pane. The host part
+     *   is taken from the LIVE browser URL when that URL still addresses the primary's destination (it
+     *   carries the freshest view state, `?section=` included), and from the primary entry's own
+     *   `urlPath` otherwise.
+     * - SECONDARY beside a derivable primary → the entry's own URL, the pre-existing model (#203).
+     * - PRIMARY, or a secondary that has just emptied → the entry's own URL; a hosted pane is closed by
+     *   the URL reconciler the moment the `pane` param is gone.
+     * - COMPANION is not hosted: no layout opens a companion beside a non-resource primary, and a
+     *   second parameter would be invented for nothing. It keeps the entry's own URL.
+     */
+    static resolveBrowserUrlForZoneEntry(params) {
+        const { zone, entryUrlPath, currentBrowserUrl, getZoneState } = params;
+        const primaryTop = NavigationUtils.getTopEntry(getZoneState(NavigationZoneName.PRIMARY));
+        const hosted = zone === NavigationZoneName.SECONDARY
+            && primaryTop?.urlPath !== undefined
+            && !NavigationUtils.primaryContentIsUrlDerivable(primaryTop.content);
+        if (!hosted) {
+            return entryUrlPath;
+        }
+        const { hostUrl: liveHostUrl } = NavigationUtils.decomposeHostedPaneBrowserUrl(currentBrowserUrl);
+        const hostUrl = NavigationUtils.urlsAddressSameDestination(liveHostUrl, primaryTop.urlPath)
+            ? liveHostUrl
+            : primaryTop.urlPath;
+        return entryUrlPath ? NavigationUtils.composeHostedPaneBrowserUrl(hostUrl, entryUrlPath) : hostUrl;
+    }
+    /**
+     * What "go back" means for a zone — the POP to emit and the browser URL to write.
+     *
+     * ONE resolver, because "go back" is reached from four places: the controller's `goBack`, the
+     * router error boundary's "back" action, the feature-route guard's dismiss, and (through the
+     * controller) every back affordance in the presets. The first fix for hosted panes was applied in
+     * the controller only, and the two boundaries — each carrying its own copy of the same stack walk
+     * — went on writing a hosted pane's BARE address, which the URL reconciler cannot claim and so
+     * rebuilds into primary: the original defect, re-entered through an error page.
+     *
+     * `zone` defaults to the zone that owns the browser URL (a hosted pane under a composed URL),
+     * then PRIMARY. Returns `null` when there is nothing to go back to in that zone — the caller's own
+     * fallback (browser history, home) applies.
+     *
+     * The URL follows {@link resolveBrowserUrlForZoneEntry}: a pop inside a hosted pane reveals the
+     * previous pane under the LIVE host; closing the last pane returns to the live host without it.
+     */
+    static resolveGoBackTarget(params) {
+        const { currentBrowserUrl, getZoneState } = params;
+        const zone = params.zone
+            ?? NavigationUtils.findStructuralRouteOwner(currentBrowserUrl, getZoneState)?.zone
+            ?? NavigationZoneName.PRIMARY;
+        const zoneState = getZoneState(zone);
+        if (zoneState.stack.length > 1) {
+            const previousEntry = zoneState.stack[zoneState.stack.length - 2];
+            return {
+                zone,
+                browserUrl: previousEntry?.urlPath
+                    ? NavigationUtils.resolveBrowserUrlForZoneEntry({ zone, entryUrlPath: previousEntry.urlPath, currentBrowserUrl, getZoneState })
+                    : undefined,
+            };
+        }
+        if (zone === NavigationZoneName.PRIMARY) {
+            return null;
+        }
+        const primaryTopUrl = NavigationUtils.getTopEntry(getZoneState(NavigationZoneName.PRIMARY))?.urlPath;
+        const secondaryTopUrl = NavigationUtils.getTopEntry(getZoneState(NavigationZoneName.SECONDARY))?.urlPath;
+        const fallbackUrl = zone === NavigationZoneName.COMPANION
+            ? secondaryTopUrl ?? primaryTopUrl
+            : primaryTopUrl;
+        if (!fallbackUrl) {
+            return { zone, browserUrl: undefined };
+        }
+        /*
+         * Closing the last pane beside a non-derivable primary returns to the host's LIVE URL (its view
+         * state intact), not to the stamp the primary entry took when it was placed — the pane simply
+         * leaves the query string. Everywhere else the fallback is the entry's own URL.
+         */
+        const { hostUrl } = NavigationUtils.decomposeHostedPaneBrowserUrl(currentBrowserUrl);
+        const browserUrl = zone === NavigationZoneName.SECONDARY && NavigationUtils.urlsAddressSameDestination(hostUrl, fallbackUrl)
+            ? hostUrl
+            : fallbackUrl;
+        return { zone, browserUrl };
+    }
+    /**
+     * Whether `zone`'s visible entry is what the browser URL shows for that zone.
+     *
+     * Pane-aware: under a composed URL the PRIMARY is asked about the HOST part and the SECONDARY
+     * about the PANE part, so each route-mounted sync hook can ask about its own zone without either
+     * mistaking the other's half of the URL for a destination it has to rebuild. A hosted pane never
+     * claims a BARE URL — its address is reachable only in the composed form.
+     */
+    static zoneOwnsBrowserUrl(zone, browserUrl, getZoneState) {
+        const { hostUrl, paneUrl } = NavigationUtils.decomposeHostedPaneBrowserUrl(browserUrl);
+        const topEntry = NavigationUtils.getTopEntry(getZoneState(zone));
+        if (!topEntry)
+            return false;
+        if (zone === NavigationZoneName.SECONDARY && topEntry.hostedPane) {
+            return paneUrl !== undefined && NavigationUtils.urlsAddressSameDestination(topEntry.urlPath, paneUrl);
+        }
+        if (zone === NavigationZoneName.PRIMARY) {
+            return NavigationUtils.urlsAddressSameDestination(topEntry.urlPath, hostUrl);
+        }
+        return paneUrl === undefined && NavigationUtils.urlsAddressSameDestination(topEntry.urlPath, browserUrl);
+    }
+    /**
+     * The structural entry whose VISIBLE content the browser URL addresses, by DESTINATION.
+     *
+     * `searchDiffers` reports that the URL moved only in view state — the caller refreshes the entry's
+     * `urlPath` in place rather than rebuilding. Under a composed URL the owner is the hosted pane,
+     * and only when the primary addresses the host part as well: half a match is no match, because a
+     * pane addressed beside the wrong host is exactly what a rebuild exists to correct.
      */
     static findStructuralRouteOwner(urlPath, getZoneState) {
         const comparableTargetUrl = NavigationUtils.normalizeComparableUrl(urlPath);
         if (!comparableTargetUrl) {
             return null;
         }
+        const { hostUrl, paneUrl } = NavigationUtils.decomposeHostedPaneBrowserUrl(comparableTargetUrl);
+        if (paneUrl !== undefined) {
+            const secondaryTop = NavigationUtils.getTopEntry(getZoneState(NavigationZoneName.SECONDARY));
+            const primaryTop = NavigationUtils.getTopEntry(getZoneState(NavigationZoneName.PRIMARY));
+            if (secondaryTop?.hostedPane
+                && NavigationUtils.urlsAddressSameDestination(secondaryTop.urlPath, paneUrl)
+                && NavigationUtils.urlsAddressSameDestination(primaryTop?.urlPath, hostUrl)) {
+                return {
+                    zone: NavigationZoneName.SECONDARY,
+                    entry: secondaryTop,
+                    searchDiffers: secondaryTop.urlPath !== paneUrl || primaryTop?.urlPath !== hostUrl,
+                };
+            }
+            return null;
+        }
         const zonePriority = [
             NavigationZoneName.COMPANION,
             NavigationZoneName.SECONDARY,
@@ -187,33 +437,58 @@ export class NavigationUtils {
         ];
         for (const zone of zonePriority) {
             const topEntry = NavigationUtils.getTopEntry(getZoneState(zone));
-            if (NavigationUtils.normalizeComparableUrl(topEntry?.urlPath) === comparableTargetUrl) {
-                return { zone, entry: topEntry };
+            if (!topEntry || topEntry.hostedPane)
+                continue;
+            if (NavigationUtils.urlsAddressSameDestination(topEntry.urlPath, comparableTargetUrl)) {
+                return {
+                    zone,
+                    entry: topEntry,
+                    searchDiffers: NavigationUtils.normalizeComparableUrl(topEntry.urlPath) !== comparableTargetUrl,
+                };
             }
         }
         return null;
     }
     /**
-     * Resolve which structural zone entry owns a URL, scanning the FULL stack of
-     * each zone (not just the top).
+     * The structural entry — visible or buried in a backstack — that the browser URL addresses.
      *
-     * Unlike {@link findStructuralRouteOwner} (which only trusts the visible top
-     * entry, for URL-first *reconstruction* decisions), this is used by the
-     * browser back/forward reconciler to decide whether the URL the user navigated
-     * to via history is a previously-visited entry still sitting lower in a zone's
-     * backstack. When it is, the reconciler can restore it with a pure stack POP
-     * (preserving that entry's live state) instead of rebuilding it from the URL.
+     * Used by the browser back/forward reconciler: a URL that names an entry still sitting LOWER in a
+     * zone's backstack is restored with a pure POP (preserving that entry's live state) rather than
+     * rebuilt. Scans deepest zone first (COMPANION → SECONDARY → PRIMARY); within a zone the deepest
+     * matching entry wins so a genuine "go back N" lands on the right historical entry. `isTop` reports
+     * that the match is already the zone's visible top.
      *
-     * Scans deepest zone first (COMPANION → SECONDARY → PRIMARY); within a zone the
-     * deepest matching entry wins so a genuine "go back N" lands on the correct
-     * historical entry. `isTop` reports whether the match is already that zone's
-     * visible top (i.e. the zone already renders this URL — nothing to do).
+     * Same destination rule and same pane rule as {@link findStructuralRouteOwner}; the difference is
+     * that a buried entry counts, which is what turns a browser back into a POP that preserves the
+     * revealed entry's live state instead of rebuilding it. Under a composed URL the search runs the
+     * SECONDARY stack for the pane while the primary's visible entry must already address the host:
+     * a pane can be popped back to, a host cannot be popped to underneath a pane.
      */
     static findStructuralStackEntryOwningUrl(urlPath, getZoneState) {
         const comparableTargetUrl = NavigationUtils.normalizeComparableUrl(urlPath);
         if (!comparableTargetUrl) {
             return null;
         }
+        const { hostUrl, paneUrl } = NavigationUtils.decomposeHostedPaneBrowserUrl(comparableTargetUrl);
+        if (paneUrl !== undefined) {
+            const primaryTop = NavigationUtils.getTopEntry(getZoneState(NavigationZoneName.PRIMARY));
+            if (!NavigationUtils.urlsAddressSameDestination(primaryTop?.urlPath, hostUrl)) {
+                return null;
+            }
+            const stack = getZoneState(NavigationZoneName.SECONDARY).stack;
+            for (let index = stack.length - 1; index >= 0; index--) {
+                const entry = stack[index];
+                if (entry?.hostedPane && NavigationUtils.urlsAddressSameDestination(entry.urlPath, paneUrl)) {
+                    return {
+                        zone: NavigationZoneName.SECONDARY,
+                        entry,
+                        isTop: index === stack.length - 1,
+                        searchDiffers: entry.urlPath !== paneUrl || primaryTop?.urlPath !== hostUrl,
+                    };
+                }
+            }
+            return null;
+        }
         const zonePriority = [
             NavigationZoneName.COMPANION,
             NavigationZoneName.SECONDARY,
@@ -223,38 +498,100 @@ export class NavigationUtils {
             const stack = getZoneState(zone).stack;
             for (let index = stack.length - 1; index >= 0; index--) {
                 const entry = stack[index];
-                if (NavigationUtils.normalizeComparableUrl(entry?.urlPath) === comparableTargetUrl) {
-                    return { zone, entry, isTop: index === stack.length - 1 };
+                if (!entry || entry.hostedPane)
+                    continue;
+                if (NavigationUtils.urlsAddressSameDestination(entry.urlPath, comparableTargetUrl)) {
+                    return {
+                        zone,
+                        entry,
+                        isTop: index === stack.length - 1,
+                        searchDiffers: NavigationUtils.normalizeComparableUrl(entry.urlPath) !== comparableTargetUrl,
+                    };
                 }
             }
         }
         return null;
     }
     /**
-     * Check if a URL pattern matches a pathname (exact match).
-     * Patterns use :paramName format (e.g., /organizations/:organizationId/api-keys)
-     * and pathnames have actual values (e.g., /organizations/abc123/api-keys).
-     *
-     * @param pattern - URL pattern with :paramName placeholders
-     * @param pathname - Actual URL pathname with resolved values
-     * @returns true if the pattern matches the pathname
+     * Match a `:param` route pattern against a pathname and return the captured parameters, or
+     * `undefined` when it does not match. The capturing twin of {@link matchUrlPattern}.
      */
-    static matchUrlPattern(pattern, pathname) {
-        // First replace :paramName with a placeholder that won't be escaped
-        // Then escape special regex chars, then restore the placeholder as regex group
+    static extractUrlPatternParams(pattern, pathname) {
         const PLACEHOLDER = '___PARAM___';
         const paramNames = [];
-        // Extract :paramName patterns and replace with placeholder
         const withPlaceholders = pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_match, paramName) => {
             paramNames.push(paramName);
             return PLACEHOLDER;
         });
-        // Escape special regex characters
         const escaped = withPlaceholders.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        // Replace placeholders with regex capture groups
         const regexPattern = escaped.replace(new RegExp(PLACEHOLDER, 'g'), '([^/]+)');
-        const regex = new RegExp(`^${regexPattern}$`);
-        return regex.test(pathname);
+        const match = new RegExp(`^${regexPattern}$`).exec(pathname);
+        if (!match)
+            return undefined;
+        const params = {};
+        paramNames.forEach((name, index) => {
+            params[name] = decodeURIComponent(match[index + 1] ?? '');
+        });
+        return params;
+    }
+    /**
+     * The ADDRESSABLE resource operation a URL path names, with its captured route parameters.
+     *
+     * The URL→state reconstruction the route elements perform (`useRouterSync`) gets its resource,
+     * operation and parameters from React Router, which has already matched the route. A hosted pane
+     * is NOT the router's route — the browser URL is the host's — so its address has to be matched
+     * here, against the same route table `AppRouter` registers: every addressable operation's
+     * frontend route paths. The most specific matching pattern wins, exactly as the router would rank
+     * a static segment above a parameter.
+     */
+    static resolveResourceRouteForUrl(urlPath, registry) {
+        const { pathname } = NavigationUtils.splitUrlPath(urlPath);
+        let best;
+        for (const resourceConfig of Object.values(registry.resourceConfigurations ?? {})) {
+            const operations = Array.isArray(resourceConfig.operations) ? resourceConfig.operations : [];
+            for (const operation of operations) {
+                if (!isOperationAddressable(operation.operationFrontendConfig))
+                    continue;
+                let routePaths;
+                try {
+                    routePaths = ResourcesConfigOperationsUrlsBuilderUtils.buildOperationFrontendRoutePaths(resourceConfig, operation, registry.allResourceFieldIdentifiers);
+                }
+                catch {
+                    continue;
+                }
+                for (const routePath of routePaths ?? []) {
+                    const urlParameters = NavigationUtils.extractUrlPatternParams(routePath.url, pathname);
+                    if (!urlParameters)
+                        continue;
+                    const score = NavigationUtils.routeSpecificityScore(routePath.url);
+                    if (!best || score > best.score) {
+                        best = {
+                            score,
+                            resourceType: resourceConfig.resourceIdentifier,
+                            operation,
+                            routePathParameters: routePath.parameters ?? [],
+                            urlParameters,
+                        };
+                    }
+                }
+            }
+        }
+        if (!best)
+            return undefined;
+        const { score: _score, ...route } = best;
+        return route;
+    }
+    /**
+     * Check if a URL pattern matches a pathname (exact match).
+     * Patterns use :paramName format (e.g., /organizations/:organizationId/api-keys)
+     * and pathnames have actual values (e.g., /organizations/abc123/api-keys).
+     *
+     * @param pattern - URL pattern with :paramName placeholders
+     * @param pathname - Actual URL pathname with resolved values
+     * @returns true if the pattern matches the pathname
+     */
+    static matchUrlPattern(pattern, pathname) {
+        return NavigationUtils.extractUrlPatternParams(pattern, pathname) !== undefined;
     }
     /**
      * Check if pathname matches pattern or is a child of it.
@@ -505,7 +842,7 @@ export class NavigationUtils {
             });
         }
         else if (target.viewRef && target.contentType) {
-            const content = NavigationUtils.buildNavigationContentForResolvedView(target.viewRef, target.contentType, target.fullCustomComponentRef, target.flowsActorsSystemRefs, target.contextResourceIdentifiers, target.urlParamValues, target.requiredFeatures);
+            const content = NavigationUtils.buildNavigationContentForResolvedView(target.viewRef, target.contentType, target.fullCustomComponentRef, target.flowsActorsSystemRef, target.contextResourceIdentifiers, target.urlParamValues, target.requiredFeatures);
             navigate({
                 content,
                 initiator: NavigationUtils.createAppLevelInitiator(launcher),
@@ -555,7 +892,7 @@ export class NavigationUtils {
      * Mirrors `buildNavigationContentForViewItem` but operates on loose fields
      * from `ResolvedNavigationTarget` instead of `ViewNavigationItem`.
      */
-    static buildNavigationContentForResolvedView(viewRef, contentType, fullCustomComponentRef, flowsActorsSystemRefs, contextResourceIdentifiers, urlParamValues, requiredFeatures) {
+    static buildNavigationContentForResolvedView(viewRef, contentType, fullCustomComponentRef, flowsActorsSystemRef, contextResourceIdentifiers, urlParamValues, requiredFeatures) {
         switch (contentType) {
             case NavigationContentType.COMPOSITE_VIEW:
                 return {
@@ -588,7 +925,7 @@ export class NavigationUtils {
                 return {
                     contentType: NavigationContentType.FLOWS_ACTORS_VIEW,
                     viewRef,
-                    flowsActorsSystemRefs: flowsActorsSystemRefs ?? [],
+                    flowsActorsSystemRef: flowsActorsSystemRef ?? '',
                     contextResourceIdentifiers,
                 };
             default:
@@ -668,6 +1005,17 @@ export class NavigationUtils {
      * the page props and the live navigation stack cannot disagree about whether a
      * deep-linked resource belongs to PRIMARY, SECONDARY, or COMPANION.
      */
+    /** Does the layout resolve this operation to a SPLIT out of PRIMARY? (#203) */
+    static layoutSplitsOperationFromPrimary(layout, operation) {
+        if (operation.isBulkOperation === true)
+            return false;
+        const semantic = resolveEffectiveCoreOperationFromOperation(operation);
+        if (!semantic)
+            return false;
+        const transition = layout?.zones?.primary?.transitions?.[semantic];
+        const verb = typeof transition === 'string' ? transition : transition?.transition;
+        return verb === NavigationTransition.SPLIT;
+    }
     static resolveResourceTargetZone(depth, options) {
         const hasSecondary = !!options?.hasSecondary;
         const hasCompanion = !!options?.hasCompanion;
@@ -675,7 +1023,9 @@ export class NavigationUtils {
             ? NavigationZoneName.COMPANION
             : depth === 1
                 ? NavigationZoneName.SECONDARY
-                : NavigationZoneName.PRIMARY;
+                : options?.prefersAdjacentZoneForDetail
+                    ? NavigationZoneName.SECONDARY
+                    : NavigationZoneName.PRIMARY;
         if (!hasCompanion && targetZone === NavigationZoneName.COMPANION) {
             targetZone = hasSecondary ? NavigationZoneName.SECONDARY : NavigationZoneName.PRIMARY;
         }
@@ -871,7 +1221,7 @@ export class NavigationUtils {
                 return {
                     contentType: NavigationContentType.FLOWS_ACTORS_VIEW,
                     viewRef: item.viewRef,
-                    flowsActorsSystemRefs: item.flowsActorsSystemRefs ?? [],
+                    flowsActorsSystemRef: item.flowsActorsSystemRef ?? '',
                     contextResourceIdentifiers: item.contextResourceIdentifiers,
                 };
             default:
@@ -1034,6 +1384,20 @@ export class NavigationUtils {
      * @param primaryContent - Current top content in PRIMARY zone
      * @returns true if the dependent content is still relevant to the primary
      */
+    /**
+     * Does this operation address a COLLECTION rather than one record?
+     *
+     * LIST and SEARCH both do. Used to recognise the list-detail pairing, where the collection is the
+     * context its own detail belongs beside — not a parent, which is why the parent-requirement rule
+     * cannot answer it.
+     */
+    static isCollectionOperationContext(resourceContext) {
+        const operation = resourceContext.operation;
+        if (!operation)
+            return false;
+        const semantic = resolveEffectiveCoreOperationFromOperation(operation);
+        return semantic === CoreResourceOperation.LIST || semantic === CoreResourceOperation.SEARCH;
+    }
     static isContentRelevantToParent(dependentContent, primaryContent) {
         // Views are not relationship-aware → always stale on PRIMARY change
         if (dependentContent.contentType !== NavigationContentType.RESOURCE_OPERATION) {
@@ -1045,6 +1409,26 @@ export class NavigationUtils {
         }
         const primaryResourceType = primaryContent.resourceContext.resourceType;
         const primaryResourceId = frontendResourceUtils.getPrimaryResourceIdentifier(primaryContent.resourceContext);
+        /*
+         * SAME-RESOURCE LIST → DETAIL is relevant, and it is checked BEFORE the parent-requirement rule
+         * below because that rule cannot see it (#203).
+         *
+         * A flat resource's detail has no parent requirements — it is a root resource — so the rule below
+         * calls it "not dependent on PRIMARY" and the zone-dependency cleanup clears it. The premise is
+         * true and the conclusion does not follow: a detail sitting beside its OWN collection is not
+         * stale, it is the entire list-detail pattern. `NAVIGATION_LAYOUT_SPLIT` exists to produce exactly
+         * this pairing.
+         *
+         * It never surfaced on the CLICK path, because there primary keeps the list and its top entry
+         * never changes, so the cleanup does not run. It surfaces on URL restoration, where primary goes
+         * from empty to the list and that counts as a change — the detail was then cleared one tick after
+         * being placed, with no CLEAR_ZONE event to find it by, because this cleanup calls
+         * `clearZoneEntries` directly rather than through the bus.
+         */
+        if (primaryContent.resourceContext.resourceType === dependentContent.resourceContext.resourceType
+            && NavigationUtils.isCollectionOperationContext(primaryContent.resourceContext)) {
+            return true;
+        }
         const parentReqs = dependentContent.resourceContext.parentResourcesRequirements;
         // If dependent has no parent requirements → it's a root resource, not dependent on PRIMARY
         if (!parentReqs || parentReqs.length === 0) {