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

package/dist/esm/core/execution/useExecution.js

@@ -0,0 +1,743 @@
+import { useCallback, useContext, useMemo, useRef } from 'react';
+import { CoreResourceOperation, ErrorCustomMessageReference, ResourcesConfig_OperationPathUtils, ResourcesConfigOperationsUrlsBuilderUtils, } from '@wildo-ai/saas-models';
+import { ExecutionNavigationHandlingMode, resolveExecutionNavigationHandlingMode, } from '../../core/config/execution-view.schemas.js';
+import { useEventBus } from '../../core/events/useEventBus.js';
+import { NavigationContentType } from '../../core/navigation/navigation.schemas.js';
+import { NavigationUtils } from '../../core/navigation/navigation.utils.js';
+import { WebSocketContext } from '../../core/requests/websockets/WebSocketContext.js';
+import { frontendResourceUtils, FrontendResourceUtils, } from '../../core/resources/frontend-resource.utils.js';
+import { mergeBulkSelectionIntoRequestData } from '../../core/resources/operation-semantics.frontend.utils.js';
+import { useResourceRegistry } from '../../core/resources/useResourceRegistry.js';
+import { emitResourceOperationOutcome } from './execution-outcome-emission.utils.js';
+import { buildExecutionFailedAction, isErrorMarkedByHttpClient, } from './execution-failure-handling.utils.js';
+import { errorManagement } from '../../core/errors/error-management.frontend.service.js';
+import { buildExecutionParticipationContextIdentifier, buildExecutionParticipationContextualParameters, buildExecutionParticipationHandle, getExecutionParticipationResourceType, } from './execution-participation.utils.js';
+import { assertExecutionRuntimeContext, ExecutionFailedActionScope, ExecutionRuntimeContext, } from './ExecutionRuntimeContext.js';
+import { useExecutionResourceOperationContextBuilder } from './useExecutionResourceOperationContextBuilder.js';
+/**
+ * Opaque, collision-resistant id for a shell-tracked pending action.
+ *
+ * Kept private to the execution runtime — `actionRuntimeId` is surfaced via
+ * the public `ExecutionPendingAction` type but its *generation* is a
+ * framework detail so consumers cannot reach past the `execute()` verb to
+ * push their own entries.
+ */
+function createExecutionActionRuntimeId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return `execution-action-${crypto.randomUUID()}`;
+    }
+    return `execution-action-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+ * Opaque, collision-resistant id for a captured execution failure entry.
+ *
+ * Distinct namespace from `actionRuntimeId` so a failed action and its
+ * originating pending action have different ids and a re-attempt of the same
+ * action produces a fresh failure entry rather than mutating the prior one
+ * (failure-handling-contract invariant #5).
+ */
+function createExecutionFailureRuntimeId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return `execution-failure-${crypto.randomUUID()}`;
+    }
+    return `execution-failure-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+ * Single public execution renderer hook.
+ *
+ * This is the one business-facing entry point custom execution renderers should
+ * consume. It exposes the mounted execution runtime plus the common derived
+ * helpers renderers actually need, so app code does not have to compose a dozen
+ * tiny selector hooks just to understand one execution surface.
+ *
+ * Internal low-level seams can still exist where React hook composition truly
+ * requires them, but they are implementation details rather than the public
+ * renderer API.
+ */
+export function useExecution() {
+    const executionRuntime = assertExecutionRuntimeContext(useContext(ExecutionRuntimeContext));
+    const { registry } = useResourceRegistry();
+    const { buildResourceOperationContext } = useExecutionResourceOperationContextBuilder();
+    // Canonical outcome-emission bridge: wire `.execute()` into the app
+    // EventBus as a `RESOURCE_OPERATION_EXECUTED` / `RESOURCE_REFRESH` producer.
+    // Anchored at `saas.frontend.execution-view.outcome-emission-contract` in
+    // `ExecutionRuntimeContext.tsx`. Refs keep the closure capture stable so
+    // `buildExecutionOperationAction`'s `useCallback` does not re-memo on every
+    // WS-flip or bus-identity change.
+    const { emit } = useEventBus();
+    const webSocket = useContext(WebSocketContext);
+    const isWebSocketConnected = webSocket?.isConnected ?? false;
+    const emitRef = useRef(emit);
+    const isWebSocketConnectedRef = useRef(isWebSocketConnected);
+    emitRef.current = emit;
+    isWebSocketConnectedRef.current = isWebSocketConnected;
+    // Slice G — reactive-but-stable trick. The per-action `status` snapshot
+    // (and the `clearMyFailures` / `clearMyDirty` sugar) must always read the
+    // *latest* `runtimeState`, but we **must not** include `runtimeState` in
+    // any `useCallback`/`useMemo` deps that the public `actions` value
+    // depends on — doing so would flip `actions` identity on every
+    // `setPendingActions` / `setFailedActions` / `setDirtyMarkers` commit,
+    // and any downstream consumer wrapping `loadXxx` in a
+    // `useEffect([...ops])` (the canonical multi-action workflow pattern,
+    // see `TodoListFlowExecutionView`) would re-fire on the very state
+    // mutation it caused — an infinite loop. Same shape of trap that Slice F
+    // dodged by depending on the stable `navigation` ref instead of the
+    // whole `executionContext` value (see G11 regression test). The ref is
+    // updated on every render so reads from inside the action see the
+    // freshly-committed state, while the `useCallback` identity for
+    // `buildExecutionOperationAction` stays pinned to the structural deps
+    // (navigation, participations, viewDefinition, registry — all stable
+    // across action invocations).
+    const runtimeStateRef = useRef(executionRuntime.runtimeState);
+    runtimeStateRef.current = executionRuntime.runtimeState;
+    const participations = useMemo(() => (Object.fromEntries(Object.entries(executionRuntime.participations).map(([ref, participation]) => [
+        ref,
+        buildExecutionParticipationHandle({
+            participation,
+            registry,
+        }),
+    ]))), [executionRuntime.participations, registry]);
+    const participation = useCallback((ref) => (participations[ref]), [participations]);
+    const requireParticipation = useCallback((ref) => {
+        const resolvedParticipation = participations[ref];
+        if (!resolvedParticipation) {
+            throw new Error(`Execution participation "${ref}" is required by view "${executionRuntime.viewDefinition.ref}" but was not resolved.`);
+        }
+        return resolvedParticipation;
+    }, [executionRuntime.viewDefinition.ref, participations]);
+    const requireParticipations = useCallback((refs) => {
+        return Object.fromEntries(refs.map((ref) => [ref, requireParticipation(ref)]));
+    }, [requireParticipation]);
+    const subjectsRequire = useCallback((refOrRefs) => {
+        if (Array.isArray(refOrRefs)) {
+            return requireParticipations(refOrRefs);
+        }
+        return requireParticipation(refOrRefs);
+    }, [requireParticipation, requireParticipations]);
+    const buildContextualParameters = useCallback((participationRefs) => {
+        if (participationRefs.length === 0) {
+            return {};
+        }
+        return buildExecutionParticipationContextualParameters({
+            participationRefs,
+            participations: executionRuntime.participations,
+            registry,
+        });
+    }, [executionRuntime.participations, registry]);
+    const buildExecutionOperationAction = useCallback((target) => {
+        const derivedContextResourceIdentifiers = (target.contextParticipationRefs ?? []).reduce((acc, ref) => {
+            const participation = executionRuntime.participations[ref];
+            if (!participation) {
+                throw new Error(`Execution action target references unknown context participation "${ref}" on view "${executionRuntime.viewDefinition.ref}".`);
+            }
+            const contextIdentifier = buildExecutionParticipationContextIdentifier({
+                participation,
+                registry,
+            });
+            if (!contextIdentifier) {
+                return acc;
+            }
+            // Canonical `contextResourceIdentifiers` shape (see
+            // `FrontendResourceUtils.buildContextualParameters`) is `ResourceType → id`.
+            // Keying by the FK-alias field identifier would shadow downstream
+            // addressability lookups, which read `contextResourceIdentifiers[resourceType]`.
+            // The FK-alias survives inside the value's `fieldIdentifier` slot, so
+            // `buildContextualParameters` still emits FK-keyed entries.
+            const contextKey = getExecutionParticipationResourceType(participation);
+            const existingContextIdentifier = acc[contextKey];
+            if (existingContextIdentifier) {
+                const existingResourceId = frontendResourceUtils.getResourceId(existingContextIdentifier);
+                const nextResourceId = frontendResourceUtils.getResourceId(contextIdentifier);
+                const existingFieldIdentifier = frontendResourceUtils.getFieldIdentifier(existingContextIdentifier);
+                const nextFieldIdentifier = frontendResourceUtils.getFieldIdentifier(contextIdentifier);
+                if (existingResourceId !== nextResourceId
+                    || existingFieldIdentifier !== nextFieldIdentifier) {
+                    throw FrontendResourceUtils.buildConfigurationError(ErrorCustomMessageReference.CONFIGURATION, {
+                        component: 'useExecution.actions.operation',
+                        message: `Execution action target resolved conflicting context participations for "${contextKey}".`,
+                        contextKey,
+                        existingContextIdentifier,
+                        nextContextIdentifier: contextIdentifier,
+                        participationRef: ref,
+                        executionViewRef: executionRuntime.viewDefinition.ref,
+                    });
+                }
+            }
+            acc[contextKey] = contextIdentifier;
+            return acc;
+        }, {});
+        const resolvedTarget = {
+            ...target,
+            contextResourceIdentifiers: {
+                ...derivedContextResourceIdentifiers,
+                ...(target.contextResourceIdentifiers ?? {}),
+            },
+        };
+        const resourceContext = buildResourceOperationContext(resolvedTarget);
+        const { resourceType, operation } = resourceContext;
+        const operationId = String(operation.operationIdentifier);
+        const resourceConfig = registry.resourceConfigurations[resourceType];
+        const contextualParameters = FrontendResourceUtils.buildContextualParameters(resourceContext.contextResourceIdentifiers, registry);
+        const navigationHandlingMode = resolveExecutionNavigationHandlingMode({
+            viewDefinition: executionRuntime.viewDefinition,
+            resourceType,
+            operation,
+        });
+        const defaultNavigationInitiator = NavigationUtils.createOperationInitiator(executionRuntime.navigationZone, operationId);
+        const mergedNavigationInitiator = {
+            ...defaultNavigationInitiator,
+            ...(target.navigationInitiator ?? {}),
+        };
+        const embeddableContent = {
+            contentType: NavigationContentType.RESOURCE_OPERATION,
+            resourceContext,
+        };
+        const embed = () => {
+            executionRuntime.navigation.openEmbeddedContent({
+                content: embeddableContent,
+                navigationInitiator: mergedNavigationInitiator,
+            });
+            return true;
+        };
+        const navigate = () => {
+            if (navigationHandlingMode === ExecutionNavigationHandlingMode.EMBED_LOCALLY) {
+                return embed();
+            }
+            const routePaths = resourceConfig
+                ? ResourcesConfigOperationsUrlsBuilderUtils.buildOperationFrontendRoutePaths(resourceConfig, operation, registry.allResourceFieldIdentifiers)
+                : [];
+            const urlPath = resourceConfig && routePaths.length > 0
+                ? frontendResourceUtils.selectMatchingRoutePath(routePaths, resourceContext.contextResourceIdentifiers, resourceType, resourceConfig.resourceFieldIdentifier, resourceContext.parentResourcesRequirements).url
+                : undefined;
+            executionRuntime.navigation.delegateToParent({
+                content: embeddableContent,
+                urlPath,
+                relationshipTransition: target.relationshipTransition,
+                initiator: {
+                    ...target.navigationInitiator,
+                    sourceOperation: mergedNavigationInitiator.sourceOperation,
+                    ...(mergedNavigationInitiator.sourceRelationship
+                        ? { sourceRelationship: mergedNavigationInitiator.sourceRelationship }
+                        : {}),
+                    ...(mergedNavigationInitiator.launcher
+                        ? { launcher: mergedNavigationInitiator.launcher }
+                        : {}),
+                },
+            });
+            return true;
+        };
+        // Hoisted so cross-tier sugar (`status`, `clearMyFailures`, `retry`)
+        // and the `execute` closure can share the same correlation key.
+        const operationPathKey = ResourcesConfig_OperationPathUtils.createOperationPathKeyFromOperation(operation);
+        const execute = async (requestData) => {
+            const effectiveRequestData = mergeBulkSelectionIntoRequestData({
+                operation,
+                requestData,
+                additionalContext: resourceContext.additionalContext,
+            });
+            const pendingAction = {
+                actionRuntimeId: createExecutionActionRuntimeId(),
+                operationPathKey,
+                resourceType,
+                operationId,
+                startedAt: Date.now(),
+            };
+            executionRuntime.navigation.beginPendingAction(pendingAction);
+            try {
+                const result = await executionRuntime.doOperation(operationPathKey, {
+                    contextualParameters,
+                    parentResourcesRequirements: resourceContext.parentResourcesRequirements,
+                    ...(effectiveRequestData ? { requestData: effectiveRequestData } : {}),
+                });
+                // Canonical outcome emission — see `emitResourceOperationOutcome` for
+                // the contract. Fires before the finally clause clears the pending
+                // entry so `execution.loading.isBusy` is still true at emission time.
+                emitResourceOperationOutcome({
+                    emit: emitRef.current,
+                    resourceConfig,
+                    registry,
+                    resourceType,
+                    operation,
+                    resourceContext,
+                    isWebSocketConnected: isWebSocketConnectedRef.current,
+                    result,
+                });
+                return result;
+            }
+            catch (error) {
+                // Failure-handling contract (Slice E):
+                // 1. Capture the failure into shell-tracked `failedActions` so
+                //    consumer error UX can read it from `execution.errors`.
+                // 2. Bridge to the canonical `ERROR_OCCURED` bus at most once. HTTP
+                //    rejections carry `error.wildoError` (stamped by
+                //    `wildo-http-client.handleHttpError`); when present, the shell
+                //    defers to that upstream processing rather than re-emitting,
+                //    even if the upstream policy decided to stay silent. See the
+                //    failure-handling-contract anchor in `ExecutionRuntimeContext`.
+                // 3. Re-throw the original error so consumer `.catch()` handlers
+                //    still observe it — the shell augments, never swallows.
+                const markedByHttpClient = isErrorMarkedByHttpClient(error);
+                const bridgedByExecutionShell = !markedByHttpClient;
+                if (bridgedByExecutionShell) {
+                    errorManagement.handleError(error, {
+                        source: 'promise',
+                        resourceType,
+                        operationIdentifier: operationId,
+                        additionalContext: {
+                            executionRuntimeInstanceId: executionRuntime.runtimeInstanceId,
+                            executionViewRef: executionRuntime.viewDefinition.ref,
+                            operationPathKey,
+                        },
+                    });
+                }
+                // Thread the per-action `failureScope` opt-in (Slice J) into the
+                // capture payload. The base fields are shared across all three
+                // discriminator branches; the scope-specific suffix narrows the
+                // input shape so `buildExecutionFailedAction` can keep its
+                // discriminated-union assertion (`paneId` is required for
+                // `LOCAL_PANE`, forbidden elsewhere) at compile time. When no
+                // `failureScope` is set we fall through to `CUSTOM` exactly as
+                // before — the default contract is preserved bit-for-bit so
+                // pre-Slice-J consumers see no behavior change.
+                const baseFailureInput = {
+                    failureRuntimeId: createExecutionFailureRuntimeId(),
+                    originatingActionRuntimeId: pendingAction.actionRuntimeId,
+                    operationPathKey,
+                    resourceType,
+                    operationId,
+                    startedAt: pendingAction.startedAt,
+                    error,
+                    markedByHttpClient,
+                    bridgedByExecutionShell,
+                };
+                let failureBuildInput;
+                if (target.failureScope?.scope === ExecutionFailedActionScope.LOCAL_PANE) {
+                    failureBuildInput = {
+                        ...baseFailureInput,
+                        scope: target.failureScope.scope,
+                        paneId: target.failureScope.paneId,
+                    };
+                }
+                else if (target.failureScope?.scope === ExecutionFailedActionScope.EMBEDDED_CONTENT) {
+                    failureBuildInput = {
+                        ...baseFailureInput,
+                        scope: target.failureScope.scope,
+                    };
+                }
+                else {
+                    failureBuildInput = {
+                        ...baseFailureInput,
+                        scope: ExecutionFailedActionScope.CUSTOM,
+                    };
+                }
+                const failedAction = buildExecutionFailedAction(failureBuildInput);
+                executionRuntime.navigation.captureFailedAction(failedAction);
+                throw error;
+            }
+            finally {
+                executionRuntime.navigation.endPendingAction(pendingAction.actionRuntimeId);
+            }
+        };
+        const navigateToRead = () => {
+            try {
+                return buildExecutionOperationAction({
+                    resourceType: target.resourceType,
+                    resourceId: target.resourceId,
+                    participationRef: target.participationRef,
+                    contextParticipationRefs: target.contextParticipationRefs,
+                    contextResourceIdentifiers: target.contextResourceIdentifiers,
+                    relationshipFieldOverrides: target.relationshipFieldOverrides,
+                    additionalContext: target.additionalContext,
+                    navigationInitiator: target.navigationInitiator,
+                    relationshipTransition: target.relationshipTransition,
+                    operationLike: CoreResourceOperation.READ,
+                    requireAddressable: true,
+                }).navigate();
+            }
+            catch {
+                return false;
+            }
+        };
+        // ----- Per-action status snapshot (Slice G) -----
+        //
+        // Computed **lazily** off `runtimeStateRef.current` so that:
+        //
+        // 1. The enclosing `buildExecutionOperationAction` `useCallback` does
+        //    not need `runtimeState` in its deps — keeping `actions` identity
+        //    stable across `setPendingActions` / `setFailedActions` /
+        //    `setDirtyMarkers` commits (see the runtimeStateRef comment at the
+        //    top of `useExecution`, and the G11 regression test for the loop
+        //    this dodges).
+        // 2. Repeated `action.status.X` accesses inside one render commit
+        //    return the same cached object (so a `useEffect` keyed on
+        //    `[action.status.latestFailure]` does not fire spuriously when
+        //    the consumer reads it twice). The cache key is the runtimeState
+        //    object identity itself; a new commit produces a new
+        //    `runtimeState` reference (see `ExecutionView`'s
+        //    `useMemo<ExecutionRuntimeState>` deps), invalidating the cache
+        //    on the next access.
+        // 3. Across renders, the consumer component re-renders whenever any
+        //    of `loading` / `errors` / `dirty` (the public aggregator tiers)
+        //    flips identity, because the top-level `ExecutionValue` `useMemo`
+        //    lists all three as deps. On that re-render the consumer either
+        //    re-invokes `actions.operation(target)` (fresh action, fresh
+        //    cache) or accesses `action.status` again (cache invalidates
+        //    against the new `runtimeStateRef.current`).
+        let cachedStatusFor = null;
+        let cachedStatus = null;
+        const computeStatus = () => {
+            const live = runtimeStateRef.current;
+            if (cachedStatusFor === live && cachedStatus !== null) {
+                return cachedStatus;
+            }
+            const matchingPendingActions = [];
+            for (const pending of Object.values(live.pendingActions)) {
+                if (pending.operationPathKey === operationPathKey) {
+                    matchingPendingActions.push(pending);
+                }
+            }
+            const matchingFailedActions = [];
+            for (const failed of Object.values(live.failedActions)) {
+                if (failed.operationPathKey === operationPathKey) {
+                    matchingFailedActions.push(failed);
+                }
+            }
+            const matchingDirtyMarkers = [];
+            if (target.dirtyPredicate) {
+                for (const marker of Object.values(live.dirtyMarkers)) {
+                    if (target.dirtyPredicate(marker)) {
+                        matchingDirtyMarkers.push(marker);
+                    }
+                }
+            }
+            // `latestFailure` = max-by capturedAt. Encapsulates the manual reduce
+            // pattern repeated in every inline-error UX. Returning the full entry
+            // (not just the error) preserves the originating action runtime id
+            // and bridge flags for richer per-button retry UX.
+            let latestFailure;
+            for (const candidate of matchingFailedActions) {
+                if (!latestFailure || candidate.capturedAt > latestFailure.capturedAt) {
+                    latestFailure = candidate;
+                }
+            }
+            cachedStatus = {
+                pendingActions: matchingPendingActions,
+                failedActions: matchingFailedActions,
+                dirtyMarkers: matchingDirtyMarkers,
+                isPending: matchingPendingActions.length > 0,
+                isErrored: matchingFailedActions.length > 0,
+                isDirty: matchingDirtyMarkers.length > 0,
+                latestFailure,
+            };
+            cachedStatusFor = live;
+            return cachedStatus;
+        };
+        // ----- Cross-tier sugar (Slice G, G-max) -----
+        //
+        // `clearMyFailures` / `clearMyDirty` read the **live** registries at
+        // call time (not a build-time snapshot) so a stale memoized action
+        // can still cleanly clear failures / dirty markers that landed
+        // *after* it was built. Race semantics: `clear*` against an unknown
+        // id is tolerated by the shell as a no-op, so an entry being added
+        // concurrently with the iteration is safely skipped (it just won't
+        // be cleared this turn — the consumer can call again, or the next
+        // render's status will surface it).
+        const clearMyFailures = () => {
+            const live = runtimeStateRef.current;
+            for (const failed of Object.values(live.failedActions)) {
+                if (failed.operationPathKey === operationPathKey) {
+                    executionRuntime.navigation.clearFailedAction(failed.failureRuntimeId);
+                }
+            }
+        };
+        const clearMyDirty = () => {
+            if (!target.dirtyPredicate) {
+                return;
+            }
+            const live = runtimeStateRef.current;
+            for (const marker of Object.values(live.dirtyMarkers)) {
+                if (target.dirtyPredicate(marker)) {
+                    executionRuntime.navigation.clearDirty(marker.markerId);
+                }
+            }
+        };
+        const retry = async (requestData) => {
+            // Clear *before* re-executing so subscribers reading
+            // `execution.errors` during the new execute() see a clean slate.
+            // The captured rejection from the new execute() will be appended to
+            // the (now-empty-for-this-action) registry — typical "Retry" UX.
+            clearMyFailures();
+            return execute(requestData);
+        };
+        return {
+            target: resolvedTarget,
+            resourceContext,
+            resourceType,
+            operation,
+            operationId,
+            operationPathKey,
+            contextualParameters,
+            navigationHandlingMode,
+            get status() {
+                return computeStatus();
+            },
+            execute,
+            embed,
+            navigate,
+            navigateToRead,
+            retry,
+            clearMyFailures,
+            clearMyDirty,
+        };
+    }, [
+        buildResourceOperationContext,
+        executionRuntime.doOperation,
+        executionRuntime.navigation,
+        executionRuntime.participations,
+        executionRuntime.viewDefinition,
+        registry,
+    ]);
+    const subjects = useMemo(() => ({
+        all: participations,
+        get: participation,
+        require: subjectsRequire,
+    }), [
+        participation,
+        participations,
+        subjectsRequire,
+    ]);
+    const buildActionDictionary = useCallback((definitions) => {
+        return Object.fromEntries(Object.entries(definitions).map(([key, baseTarget]) => {
+            const mergeAndResolve = (overrides) => {
+                const mergedTarget = {
+                    ...baseTarget,
+                    ...overrides,
+                    contextResourceIdentifiers: {
+                        ...(baseTarget.contextResourceIdentifiers ?? {}),
+                        ...(overrides?.contextResourceIdentifiers ?? {}),
+                    },
+                    additionalContext: {
+                        ...(baseTarget.additionalContext ?? {}),
+                        ...(overrides?.additionalContext ?? {}),
+                    },
+                    navigationInitiator: {
+                        ...(baseTarget.navigationInitiator ?? {}),
+                        ...(overrides?.navigationInitiator ?? {}),
+                    },
+                };
+                return buildExecutionOperationAction(mergedTarget);
+            };
+            const prepared = {
+                execute: (overrides, requestData) => mergeAndResolve(overrides).execute(requestData),
+                embed: (overrides) => mergeAndResolve(overrides).embed(),
+                navigate: (overrides) => mergeAndResolve(overrides).navigate(),
+                navigateToRead: (overrides) => mergeAndResolve(overrides).navigateToRead(),
+                bind: (overrides) => mergeAndResolve(overrides),
+            };
+            return [key, prepared];
+        }));
+    }, [buildExecutionOperationAction]);
+    const actions = useMemo(() => ({
+        operation: buildExecutionOperationAction,
+        dictionary: buildActionDictionary,
+    }), [buildActionDictionary, buildExecutionOperationAction]);
+    const embeddedContent = useMemo(() => ({
+        open: executionRuntime.navigation.openEmbeddedContent,
+        close: executionRuntime.navigation.closeEmbeddedContent,
+        openResource: (target) => buildExecutionOperationAction(target).embed(),
+    }), [
+        buildExecutionOperationAction,
+        executionRuntime.navigation.closeEmbeddedContent,
+        executionRuntime.navigation.openEmbeddedContent,
+    ]);
+    const loading = useMemo(() => {
+        const pendingActions = Object.values(executionRuntime.runtimeState.pendingActions);
+        const participationPrefetchActions = Object.values(executionRuntime.runtimeState.participationPrefetchActions);
+        const isAnyPending = pendingActions.length > 0;
+        const isAnyParticipationPrefetching = participationPrefetchActions.length > 0;
+        const isBusy = isAnyPending || isAnyParticipationPrefetching;
+        return {
+            pendingActions,
+            participationPrefetchActions,
+            isBusy,
+            isAnyPending,
+            isPending: (predicate) => {
+                if (!predicate) {
+                    return isAnyPending;
+                }
+                return pendingActions.some(predicate);
+            },
+            isAnyParticipationPrefetching,
+            isParticipationPrefetching: (predicate) => {
+                if (!predicate) {
+                    return isAnyParticipationPrefetching;
+                }
+                return participationPrefetchActions.some(predicate);
+            },
+        };
+    }, [
+        executionRuntime.runtimeState.pendingActions,
+        executionRuntime.runtimeState.participationPrefetchActions,
+    ]);
+    const dirty = useMemo(() => {
+        const markers = Object.values(executionRuntime.runtimeState.dirtyMarkers);
+        const isAnyDirty = markers.length > 0;
+        return {
+            markers,
+            isAnyDirty,
+            isDirty: (predicate) => {
+                if (!predicate) {
+                    return isAnyDirty;
+                }
+                return markers.some(predicate);
+            },
+            mark: executionRuntime.navigation.markDirty,
+            clear: executionRuntime.navigation.clearDirty,
+            clearAll: executionRuntime.navigation.clearAllDirty,
+        };
+    }, [
+        executionRuntime.navigation.clearAllDirty,
+        executionRuntime.navigation.clearDirty,
+        executionRuntime.navigation.markDirty,
+        executionRuntime.runtimeState.dirtyMarkers,
+    ]);
+    // Stable refs so `capture` does not re-memoize on every navigation/runtime
+    // identity flip — its identity is part of the `errors` value, which feeds
+    // into the top-level memo of `ExecutionValue`.
+    const captureFailedActionRef = useRef(executionRuntime.navigation.captureFailedAction);
+    const runtimeInstanceIdRef = useRef(executionRuntime.runtimeInstanceId);
+    const viewDefinitionRefRef = useRef(executionRuntime.viewDefinition.ref);
+    captureFailedActionRef.current = executionRuntime.navigation.captureFailedAction;
+    runtimeInstanceIdRef.current = executionRuntime.runtimeInstanceId;
+    viewDefinitionRefRef.current = executionRuntime.viewDefinition.ref;
+    const captureFailureFromConsumer = useCallback((input) => {
+        const markedByHttpClient = isErrorMarkedByHttpClient(input.error);
+        // The shell only bridges when the consumer hasn't opted out AND the
+        // error is not already marked by `wildo-http-client` (which means
+        // upstream already classified and decided whether to emit).
+        const bridgedByExecutionShell = (input.bridgeToCanonicalBus ?? true) && !markedByHttpClient;
+        if (bridgedByExecutionShell) {
+            errorManagement.handleError(input.error, {
+                source: 'manual',
+                resourceType: input.resourceType,
+                operationIdentifier: input.operationId,
+                additionalContext: {
+                    executionRuntimeInstanceId: runtimeInstanceIdRef.current,
+                    executionViewRef: viewDefinitionRefRef.current,
+                    ...(input.operationPathKey ? { operationPathKey: input.operationPathKey } : {}),
+                },
+            });
+        }
+        // Narrow on the discriminant `input.scope` so TypeScript carries the
+        // `paneId` requirement into the LOCAL_PANE branch without a cast.
+        // Mirrors the symmetric pattern in `buildExecutionFailedAction` — same
+        // discriminated-union shape on both sides of the consumer-facing seam.
+        const baseBuildInput = {
+            failureRuntimeId: createExecutionFailureRuntimeId(),
+            operationPathKey: input.operationPathKey,
+            resourceType: input.resourceType,
+            operationId: input.operationId,
+            error: input.error,
+            label: input.label,
+            markedByHttpClient,
+            bridgedByExecutionShell,
+        };
+        let failedAction;
+        if (input.scope === ExecutionFailedActionScope.LOCAL_PANE) {
+            failedAction = buildExecutionFailedAction({
+                ...baseBuildInput,
+                scope: input.scope,
+                paneId: input.paneId,
+            });
+        }
+        else if (input.scope === ExecutionFailedActionScope.EMBEDDED_CONTENT) {
+            failedAction = buildExecutionFailedAction({
+                ...baseBuildInput,
+                scope: input.scope,
+            });
+        }
+        else if (input.scope === ExecutionFailedActionScope.PARTICIPATION_PREFETCH) {
+            failedAction = buildExecutionFailedAction({
+                ...baseBuildInput,
+                scope: input.scope,
+                prefetchKey: input.prefetchKey,
+            });
+        }
+        else {
+            failedAction = buildExecutionFailedAction({
+                ...baseBuildInput,
+                scope: ExecutionFailedActionScope.CUSTOM,
+            });
+        }
+        captureFailedActionRef.current(failedAction);
+        return failedAction;
+    }, []);
+    const errors = useMemo(() => {
+        const failedActions = Object.values(executionRuntime.runtimeState.failedActions);
+        const isAnyErrored = failedActions.length > 0;
+        return {
+            failedActions,
+            isAnyErrored,
+            isErrored: (predicate) => {
+                if (!predicate) {
+                    return isAnyErrored;
+                }
+                return failedActions.some(predicate);
+            },
+            capture: captureFailureFromConsumer,
+            clear: executionRuntime.navigation.clearFailedAction,
+            clearAll: executionRuntime.navigation.clearAllFailedActions,
+        };
+    }, [
+        captureFailureFromConsumer,
+        executionRuntime.navigation.clearAllFailedActions,
+        executionRuntime.navigation.clearFailedAction,
+        executionRuntime.runtimeState.failedActions,
+    ]);
+    return useMemo(() => ({
+        view: executionRuntime.viewDefinition,
+        anchor: executionRuntime.anchor,
+        state: executionRuntime.runtimeState,
+        contextResourceIdentifiers: executionRuntime.contextResourceIdentifiers,
+        runtimeInstanceId: executionRuntime.runtimeInstanceId,
+        navigationZone: executionRuntime.navigationZone,
+        doOperation: executionRuntime.doOperation,
+        delegateToParent: executionRuntime.navigation.delegateToParent,
+        localPane: {
+            open: executionRuntime.navigation.openLocalPane,
+            close: executionRuntime.navigation.closeLocalPane,
+        },
+        embeddedContent,
+        loading,
+        dirty,
+        errors,
+        participations,
+        participation,
+        requireParticipation,
+        subjects,
+        buildContextualParameters,
+        buildResourceOperationContext,
+        actions,
+    }), [
+        actions,
+        buildContextualParameters,
+        buildResourceOperationContext,
+        executionRuntime.anchor,
+        executionRuntime.contextResourceIdentifiers,
+        executionRuntime.doOperation,
+        executionRuntime.navigation,
+        executionRuntime.navigationZone,
+        executionRuntime.runtimeInstanceId,
+        executionRuntime.runtimeState,
+        executionRuntime.viewDefinition,
+        embeddedContent,
+        loading,
+        dirty,
+        errors,
+        participation,
+        participations,
+        requireParticipation,
+        subjects,
+    ]);
+}
+//# sourceMappingURL=useExecution.js.map