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

package/dist/esm/core/guidance/GuidanceContext.js

@@ -11,7 +11,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * - Real-time sync via EventBus
  */
 import { createContext, useContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { GuidanceFlowScope, GuidanceRenderMode, GUIDANCE_SCOPE_TO_RESOURCE, OnboardingTriggerType, OnboardingStatus, ProgressionScope, PROGRESSION_SCOPE_TO_RESOURCE, LifecycleStage, LifecycleScope, LIFECYCLE_SCOPE_TO_RESOURCE, createInitialLifecycleState, hasReachedStage as hasReachedStageUtil, MilestoneRewardType, CelebrationDisplayMode, CoreResourceOperation, ResourceOperationVariantType, ResourcesConfig_OperationPathUtils, isWildoBackendError, } from '@wildo-ai/saas-models';
+import { GuidanceFlowScope, GuidanceRenderMode, GUIDANCE_SCOPE_TO_RESOURCE, OnboardingTriggerType, OnboardingStatus, isTerminalOnboardingStatus, ProgressionScope, PROGRESSION_SCOPE_TO_RESOURCE, LifecycleStage, LifecycleScope, LIFECYCLE_SCOPE_TO_RESOURCE, GuidanceStateUtils, hasReachedStage as hasReachedStageUtil, MilestoneRewardType, CelebrationDisplayMode, CoreResourceOperation, ResourceOperationVariantType, ResourcesConfig_OperationPathUtils, } from '@wildo-ai/saas-models';
 import { compileResourceGuidance } from './guidance-resource-compiler.shared.utils.js';
 import { ApplicationContext } from '../../core/runtime/ApplicationContext.shared.js';
 import { useEventBus } from '../../core/events/useEventBus.js';
@@ -23,6 +23,9 @@ import { useResourceRegistry } from '../../core/resources/useResourceRegistry.js
 import { FeaturesContext } from '../../core/features/FeaturesContext.js';
 import { buildFeaturePolicyRoles } from '../../core/features/feature-unavailability.frontend.utils.js';
 import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
+import { errorManagement } from '../../core/errors/error-management.frontend.service.js';
+import { useEmitLoadingScope } from '../../core/loading/useEmitLoadingScope.js';
+import { ContextLoadingIdentifier } from '../../core/loading/loading-types.frontend.schemas.js';
 import { evaluateGuidanceAudience, } from './guidance-audience.frontend.utils.js';
 // ─── Context ────────────────────────────────────────────────────
 // Note: useGuidance / useLifecycle / useProgression hooks are in useGuidance.ts for React Fast Refresh compatibility.
@@ -68,6 +71,7 @@ export const GUIDANCE_FALLBACK = {
     skipFlow: () => { },
     isFlowActive: () => false,
     isFlowCompleted: () => false,
+    isFlowPersistable: () => false,
     isLoading: false,
     progression: PROGRESSION_DEFAULTS,
     lifecycle: LIFECYCLE_DEFAULTS,
@@ -78,7 +82,10 @@ function findApiCallOperation(registry, resourceType, operationId) {
     if (!config)
         return null;
     return config.operations.find((o) => o.operationIdentifier === operationId
-        && o.variantType === ResourceOperationVariantType.API_CALL) ?? null;
+        && o.isOperationDefault === true
+        && o.isBulkOperation !== true
+        && (o.variantType === ResourceOperationVariantType.API_CALL
+            || o.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK)) ?? null;
 }
 async function fetchGuidanceState(scope, doOperation, registry) {
     const resourceType = GUIDANCE_SCOPE_TO_RESOURCE[scope];
@@ -87,11 +94,11 @@ async function fetchGuidanceState(scope, doOperation, registry) {
         return { flows: {} };
     const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
     try {
-        const result = await doOperation(operationPath, { contextualParameters: {} });
+        const result = await doOperation(operationPath, { contextualParameters: {} }, { silent: true });
         return result ?? { flows: {} };
     }
     catch (err) {
-        if (isWildoBackendError(err) && err.statusCode === 404)
+        if (errorManagement.isNotFoundError(err))
             return null;
         return { flows: {} };
     }
@@ -106,7 +113,7 @@ async function createGuidanceState(scope, doOperation, registry) {
         const result = await doOperation(operationPath, {
             contextualParameters: {},
             requestData: { flows: {} },
-        });
+        }, { silent: true });
         return result ?? { flows: {} };
     }
     catch {
@@ -127,7 +134,7 @@ async function persistGuidanceState(scope, state, doOperation, registry) {
         await doOperation(operationPath, { contextualParameters: {}, requestData: state });
     }
     catch {
-        /* Best-effort persistence */
+        /* Best-effort persistence — ScopedResourceRegistryProvider injects scope params */
     }
 }
 async function fetchProgressionState(scope, doOperation, registry) {
@@ -137,11 +144,11 @@ async function fetchProgressionState(scope, doOperation, registry) {
         return null;
     const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
     try {
-        const result = await doOperation(operationPath, { contextualParameters: {} });
+        const result = await doOperation(operationPath, { contextualParameters: {} }, { silent: true });
         return result ?? { milestonesAchieved: {}, operationCounts: {}, totalPoints: 0, categoriesProgress: {} };
     }
     catch (err) {
-        if (isWildoBackendError(err) && err.statusCode === 404)
+        if (errorManagement.isNotFoundError(err))
             return null;
         return { milestonesAchieved: {}, operationCounts: {}, totalPoints: 0, categoriesProgress: {} };
     }
@@ -169,7 +176,7 @@ async function fetchLifecycleState(scope, doOperation, registry) {
         return null;
     const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
     try {
-        const result = await doOperation(operationPath, { contextualParameters: {} });
+        const result = await doOperation(operationPath, { contextualParameters: {} }, { silent: true });
         return result ?? null;
     }
     catch {
@@ -211,6 +218,28 @@ export const GuidanceContextProvider = ({ children }) => {
     const appScope = useAppScopeSafe();
     const resourceRegistry = useResourceRegistry();
     const featuresCtx = useContext(FeaturesContext);
+    // Latest-value ref for the resource registry, read from inside the async
+    // initialization effects below (guidance / progression / lifecycle).
+    //
+    // WHY A REF INSTEAD OF A DEP: `resourceRegistry` (and `userOrgs`) are
+    // stable-INTENT service handles, but their memoized context-value identity
+    // legitimately changes several times during app boot — e.g. `useUserOrgs()`
+    // re-memoizes as `user`, `permissions`, `privacy`, and `organizations` resolve
+    // at independent times, none of which change `applicableScopes`. If these
+    // handles are listed directly in an init effect's dependency array, every such
+    // identity change re-runs the effect MID-FETCH: the previous run's cleanup sets
+    // `cancelled = true` (so its `if (cancelled) return` guard drops the in-flight
+    // commit), while the re-run immediately hits the `initRef` re-entry guard —
+    // which is only reset by the M9 scope-change effect, NOT by a handle-identity
+    // change — so no replacement fetch ever starts. The net effect is that the
+    // fetched guidance/progression state is silently never committed to state:
+    // `flowStates` stays empty, onboarding/guidance re-appear on every load, and
+    // the next user action full-replaces the persisted document. Reading the
+    // registry through this render-synced ref lets each init effect depend ONLY on
+    // its genuine fetch inputs (the applicable scope set + the auth gate) while
+    // still using the latest handle at call time.
+    const resourceRegistryRef = useRef(resourceRegistry);
+    resourceRegistryRef.current = resourceRegistry;
     const logger = useMemo(() => LoggerFrontendService.getLogger(), []);
     const logDebug = useMemo(() => {
         const debugFn = logger.debugByType('GuidanceContext');
@@ -241,6 +270,11 @@ export const GuidanceContextProvider = ({ children }) => {
         }
         return [...appFlows, ...resourceFlows];
     }, [appContext?.frontendConfiguration, resourceRegistry]);
+    // flowRegistry — guidance flows ONLY. Used by the trigger engine
+    // (`tryActivateFlow`), which needs the full `GuidanceFlowDefinition`
+    // (audience / renderMode / trigger). Onboarding views are deliberately NOT
+    // here, so they never auto-activate and `GuidanceRenderer` never renders them
+    // as overlays (they are rendered explicitly via `<EmbedOnboarding/>`).
     const flowRegistry = useMemo(() => {
         const map = new Map();
         for (const flow of flowDefinitions) {
@@ -248,20 +282,71 @@ export const GuidanceContextProvider = ({ children }) => {
         }
         return map;
     }, [flowDefinitions]);
+    // Onboarding views declared in app config (`<EmbedOnboarding/>` / OnboardingView
+    // surfaces). They are NOT guidance flows — explicitly embedded, never triggered —
+    // but they DO get a first-class persistence identity so an embedded wizard's
+    // dismiss / complete / skip sticks under the view's OWN ref (no parallel
+    // guidance flow required).
+    const onboardingViewDefinitions = useMemo(() => appContext?.frontendConfiguration?.onboardingViews ?? [], [appContext?.frontendConfiguration]);
+    // persistenceRegistry — SUPERSET of flowRegistry that also includes onboarding
+    // views, projected into the minimal `PersistenceFlowEntry` shape. Used ONLY by
+    // the lifecycle guards (completeElement / completeFlow / dismissFlow / skipFlow)
+    // + scope resolution + the init gate — deliberately NOT by the trigger engine,
+    // `activeFlows`, or `GuidanceRenderer`.
+    const persistenceRegistry = useMemo(() => {
+        const map = new Map();
+        for (const flow of flowDefinitions) {
+            map.set(flow.ref, {
+                ref: flow.ref,
+                scope: flow.scope ?? GuidanceFlowScope.USER,
+                elements: flow.elements,
+                renderMode: flow.renderMode,
+            });
+        }
+        for (const view of onboardingViewDefinitions) {
+            // First registration wins so an explicit guidance flow with the same ref is
+            // never shadowed. Onboarding views persist under USER scope (personal
+            // "dismissed" state); `renderMode: undefined` marks them as non-flows so the
+            // guards suppress `GUIDANCE_FLOW_*` events for them.
+            if (!map.has(view.ref)) {
+                map.set(view.ref, {
+                    ref: view.ref,
+                    scope: GuidanceFlowScope.USER,
+                    elements: view.elements,
+                    renderMode: undefined,
+                });
+            }
+        }
+        return map;
+    }, [flowDefinitions, onboardingViewDefinitions]);
+    // True when there is anything whose persisted state must be loaded (guidance
+    // flows OR onboarding views). Gates guidance-state loading + init so an app
+    // with onboarding views but zero guidance flows still hydrates its state.
+    const hasPersistableFlows = persistenceRegistry.size > 0;
     const flowScopeMap = useMemo(() => {
         const map = {};
-        for (const flow of flowDefinitions) {
-            map[flow.ref] = flow.scope ?? GuidanceFlowScope.USER;
+        for (const entry of persistenceRegistry.values()) {
+            map[entry.ref] = entry.scope;
         }
         return map;
-    }, [flowDefinitions]);
+    }, [persistenceRegistry]);
     // ─── State ──────────────────────────────────────────────────
     const [scopedStates, setScopedStates] = useState({});
+    const scopedStatesRef = useRef({});
     const [activeFlowRefs, setActiveFlowRefs] = useState(new Set());
     const [isLoading, setIsLoading] = useState(true);
     const initRef = useRef(false);
     const delayTimersRef = useRef(new Map());
     const pendingFeatureActivationRefsRef = useRef(new Set());
+    const commitScopedStates = useCallback((nextStates) => {
+        scopedStatesRef.current = nextStates;
+        setScopedStates(nextStates);
+        return nextStates;
+    }, []);
+    const updateScopedStates = useCallback((updater) => {
+        const nextStates = updater(scopedStatesRef.current);
+        return commitScopedStates(nextStates);
+    }, [commitScopedStates]);
     // Progression state (Phase 4)
     const [progressionScopedStates, setProgressionScopedStates] = useState({ ...EMPTY_SCOPED_PROGRESSION });
     const [progressionIsLoading, setProgressionIsLoading] = useState(true);
@@ -278,10 +363,36 @@ export const GuidanceContextProvider = ({ children }) => {
     const isAuthenticated = !!userOrgs.auth.accessToken;
     const analyticsEnabled = !!appContext?.appConfig?.analytics?.enabled;
     const featuresAreLoading = featuresCtx?.isLoading ?? false;
-    const guidanceIsBootstrapping = isAuthenticated && flowDefinitions.length > 0 && !initRef.current;
+    const guidanceIsBootstrapping = isAuthenticated && hasPersistableFlows && !initRef.current;
     const guidanceIsLoading = isAuthenticated
-        ? (flowDefinitions.length > 0 ? (isLoading || guidanceIsBootstrapping) : false)
+        ? (hasPersistableFlows ? (isLoading || guidanceIsBootstrapping) : false)
         : false;
+    // L-2.b: publish progression + lifecycle loading lifecycles to LoadingContext
+    // so unrelated components can observe via `useComponentLoading({
+    // customIdentifier: ContextLoadingIdentifier.PROGRESSION | .LIFECYCLE })`.
+    // Local boolean state is still exposed for direct consumers (back-compat).
+    //
+    // `hasLoadedOnce` is intentionally **omitted** here: the progression and
+    // lifecycle subsystems do not have a granular "refresh existing data"
+    // path — every transition that flips `isLoading` back to `true` (auth
+    // change, scope change, org switch) ALSO resets the underlying scoped
+    // states to empty in the same render commit (see the auth-switch effect
+    // and the scope-change effect above). A "refresh" with stale data on
+    // screen never happens, so the hook's default `INITIAL` phase is the
+    // correct semantic. Reading `progressionInitRef.current` /
+    // `lifecycleInitRef.current` here would be misleading: those refs flip
+    // to `true` at the **start** of init (as a re-entry guard), not on
+    // success — they would always read `false` at emission time anyway,
+    // because they're reset to `false` in the same commit that flips
+    // `isLoading` back to `true`.
+    useEmitLoadingScope({
+        identifier: ContextLoadingIdentifier.PROGRESSION,
+        isLoading: progressionIsLoading,
+    });
+    useEmitLoadingScope({
+        identifier: ContextLoadingIdentifier.LIFECYCLE,
+        isLoading: lifecycleIsLoading,
+    });
     // Derive applicable scopes from current user context
     const applicableScopes = useMemo(() => {
         const scopes = [GuidanceFlowScope.USER];
@@ -290,6 +401,9 @@ export const GuidanceContextProvider = ({ children }) => {
         }
         return scopes;
     }, [appScope?.currentOrganizationId]);
+    useEffect(() => {
+        scopedStatesRef.current = scopedStates;
+    }, [scopedStates]);
     // M9: Reset init refs and org-scoped caches when applicable scopes change.
     const prevScopesRef = useRef(applicableScopes);
     useEffect(() => {
@@ -299,7 +413,7 @@ export const GuidanceContextProvider = ({ children }) => {
             lifecycleInitRef.current = false;
             pendingFeatureActivationRefsRef.current.clear();
             prevScopesRef.current = applicableScopes;
-            if (isAuthenticated && flowDefinitions.length > 0) {
+            if (isAuthenticated && hasPersistableFlows) {
                 setIsLoading(true);
             }
             if (isAuthenticated) {
@@ -308,7 +422,7 @@ export const GuidanceContextProvider = ({ children }) => {
             if (isAuthenticated && lifecycleEnabled) {
                 setLifecycleIsLoading(true);
             }
-            setScopedStates(prev => {
+            updateScopedStates(prev => {
                 if (!(GuidanceFlowScope.ORGANIZATION in prev)) {
                     return prev;
                 }
@@ -334,7 +448,7 @@ export const GuidanceContextProvider = ({ children }) => {
                 return next;
             });
         }
-    }, [applicableScopes, flowDefinitions, isAuthenticated, lifecycleEnabled]);
+    }, [applicableScopes, flowDefinitions, hasPersistableFlows, isAuthenticated, lifecycleEnabled, updateScopedStates]);
     const previousAuthStateRef = useRef({
         isAuthenticated,
         userId: currentUserId,
@@ -360,15 +474,15 @@ export const GuidanceContextProvider = ({ children }) => {
         progressionInitRef.current = false;
         lifecycleInitRef.current = false;
         pendingFeatureActivationRefsRef.current.clear();
-        setScopedStates({});
+        commitScopedStates({});
         setActiveFlowRefs(new Set());
         setProgressionScopedStates({ ...EMPTY_SCOPED_PROGRESSION });
         setMilestoneDefinitions(EMPTY_MILESTONE_DEFINITIONS);
         setLifecycleScopedStates({ ...EMPTY_SCOPED_LIFECYCLE });
-        setIsLoading(isAuthenticated && flowDefinitions.length > 0);
+        setIsLoading(isAuthenticated && hasPersistableFlows);
         setProgressionIsLoading(isAuthenticated);
         setLifecycleIsLoading(isAuthenticated && lifecycleEnabled);
-    }, [currentUserId, flowDefinitions.length, isAuthenticated, lifecycleEnabled]);
+    }, [commitScopedStates, currentUserId, hasPersistableFlows, isAuthenticated, lifecycleEnabled]);
     // Flatten all flow states across scopes into a single record
     const flowStates = useMemo(() => {
         const merged = {};
@@ -414,17 +528,19 @@ export const GuidanceContextProvider = ({ children }) => {
     // ─── Initialization ─────────────────────────────────────────
     // H3-8: Abort guard prevents setState on unmounted/stale effect
     useEffect(() => {
-        if (initRef.current || flowDefinitions.length === 0 || !userOrgs.isAuthenticated())
+        if (initRef.current || !hasPersistableFlows || !isAuthenticated)
             return;
         initRef.current = true;
         let cancelled = false;
         const initialize = async () => {
-            logDebug('Initializing guidance state', { scopes: applicableScopes, flowCount: flowDefinitions.length });
+            // Read the latest registry handle at call time (see resourceRegistryRef).
+            const registry = resourceRegistryRef.current;
+            logDebug('Initializing guidance state', { scopes: applicableScopes, flowCount: persistenceRegistry.size });
             const stateResults = await Promise.allSettled(applicableScopes.map(async (scope) => {
-                let state = await fetchGuidanceState(scope, resourceRegistry.doOperation, resourceRegistry.registry);
+                let state = await fetchGuidanceState(scope, registry.doOperation, registry.registry);
                 if (state === null) {
                     logDebug(`Auto-creating guidance state for scope ${scope}`);
-                    state = await createGuidanceState(scope, resourceRegistry.doOperation, resourceRegistry.registry);
+                    state = await createGuidanceState(scope, registry.doOperation, registry.registry);
                 }
                 return { scope, state };
             }));
@@ -437,13 +553,18 @@ export const GuidanceContextProvider = ({ children }) => {
                 }
             }
             // M7: Functional updater — merge with any concurrent WS updates
-            setScopedStates(prev => ({ ...prev, ...newStates }));
+            updateScopedStates(prev => ({ ...prev, ...newStates }));
             setIsLoading(false);
             logDebug('Guidance state loaded', { scopeCount: Object.keys(newStates).length });
         };
         initialize();
         return () => { cancelled = true; };
-    }, [flowDefinitions.length, applicableScopes, logDebug, userOrgs, resourceRegistry]);
+        // Deps are the genuine fetch inputs ONLY: the applicable scope set + the
+        // auth gate + the persistable-flows gate. Service handles (resourceRegistry)
+        // are read via ref so their boot-time identity churn cannot cancel the
+        // in-flight fetch before it commits. logDebug / updateScopedStates are stable
+        // (useMemo/useCallback with stable deps).
+    }, [hasPersistableFlows, applicableScopes, isAuthenticated, logDebug, updateScopedStates]);
     // ─── Progression Initialization (Phase 4) ──────────────────
     const progressionApplicableScopes = useMemo(() => {
         const scopes = [ProgressionScope.USER];
@@ -454,15 +575,17 @@ export const GuidanceContextProvider = ({ children }) => {
     }, [appScope?.currentOrganizationId]);
     // H3-8: Abort guard for progression init
     useEffect(() => {
-        if (progressionInitRef.current || !userOrgs.isAuthenticated())
+        if (progressionInitRef.current || !isAuthenticated)
             return;
         progressionInitRef.current = true;
         let cancelled = false;
         const initializeProgression = async () => {
+            // Read the latest registry handle at call time (see resourceRegistryRef).
+            const registry = resourceRegistryRef.current;
             logDebug('Initializing progression state', { scopes: progressionApplicableScopes });
             const [stateResults, definitions] = await Promise.all([
                 Promise.allSettled(progressionApplicableScopes.map(async (scope) => {
-                    const state = await fetchProgressionState(scope, resourceRegistry.doOperation, resourceRegistry.registry);
+                    const state = await fetchProgressionState(scope, registry.doOperation, registry.registry);
                     return { scope, state };
                 })),
                 fetchMilestoneDefinitions(analyticsEnabled),
@@ -488,7 +611,10 @@ export const GuidanceContextProvider = ({ children }) => {
         };
         initializeProgression();
         return () => { cancelled = true; };
-    }, [analyticsEnabled, progressionApplicableScopes, logDebug, userOrgs, resourceRegistry, appContext]);
+        // Genuine fetch inputs ONLY (scope set + analytics gate + auth gate).
+        // resourceRegistry read via ref; appContext dropped (only its derived
+        // `analyticsEnabled` boolean is used, and it is already a dep).
+    }, [analyticsEnabled, progressionApplicableScopes, isAuthenticated, logDebug]);
     // ─── Lifecycle Initialization (Phase 5) ─────────────────────
     const lifecycleApplicableScopes = useMemo(() => {
         if (!lifecycleEnabled)
@@ -501,17 +627,19 @@ export const GuidanceContextProvider = ({ children }) => {
     }, [lifecycleEnabled, appScope?.currentOrganizationId]);
     // H3-8: Abort guard for lifecycle init
     useEffect(() => {
-        if (lifecycleInitRef.current || !userOrgs.isAuthenticated() || !lifecycleEnabled) {
+        if (lifecycleInitRef.current || !isAuthenticated || !lifecycleEnabled) {
             return;
         }
         lifecycleInitRef.current = true;
         let cancelled = false;
         const initializeLifecycle = async () => {
+            // Read the latest registry handle at call time (see resourceRegistryRef).
+            const registry = resourceRegistryRef.current;
             setLifecycleIsLoading(true);
             logDebug('Initializing lifecycle state', { scopes: lifecycleApplicableScopes });
             const stateResults = await Promise.allSettled(lifecycleApplicableScopes.map(async (scope) => {
-                const state = await fetchLifecycleState(scope, resourceRegistry.doOperation, resourceRegistry.registry);
-                return { scope, state: state ?? createInitialLifecycleState() };
+                const state = await fetchLifecycleState(scope, registry.doOperation, registry.registry);
+                return { scope, state: state ?? GuidanceStateUtils.createInitialLifecycleState() };
             }));
             if (cancelled)
                 return;
@@ -528,30 +656,42 @@ export const GuidanceContextProvider = ({ children }) => {
         };
         initializeLifecycle();
         return () => { cancelled = true; };
-    }, [lifecycleApplicableScopes, logDebug, userOrgs, lifecycleEnabled, resourceRegistry]);
+        // Genuine fetch inputs ONLY (scope set + lifecycle gate + auth gate).
+        // resourceRegistry read via ref so boot-time identity churn cannot cancel
+        // the in-flight fetch before it commits.
+    }, [lifecycleApplicableScopes, isAuthenticated, lifecycleEnabled, logDebug]);
     // ─── State Mutation Helpers ─────────────────────────────────
-    // H5: Persist AFTER the state update (outside the updater — safe for React 18 StrictMode)
-    const updateFlowState = useCallback((flowRef, updater) => {
-        const scope = flowScopeMap[flowRef] ?? GuidanceFlowScope.USER;
-        let newScopeState = null;
-        setScopedStates(prev => {
-            const scopeState = prev[scope] ?? { flows: {} };
-            const currentFlowState = scopeState.flows[flowRef] ?? {
-                status: OnboardingStatus.NOT_STARTED,
-                elements: {},
-                triggerCount: 0,
-            };
-            const updatedFlowState = updater(currentFlowState);
-            newScopeState = {
-                ...scopeState,
-                flows: { ...scopeState.flows, [flowRef]: updatedFlowState },
-            };
-            return { ...prev, [scope]: newScopeState };
+    const resolveFlowStateScope = useCallback((flowRef, candidateStates = scopedStatesRef.current) => {
+        const matchingScopes = [GuidanceFlowScope.USER, GuidanceFlowScope.ORGANIZATION].filter((scope) => candidateStates[scope]?.flows?.[flowRef] !== undefined);
+        const activeScope = matchingScopes.find((scope) => candidateStates[scope]?.flows?.[flowRef]?.status === OnboardingStatus.IN_PROGRESS);
+        return activeScope
+            ?? matchingScopes[0]
+            ?? flowScopeMap[flowRef]
+            ?? GuidanceFlowScope.USER;
+    }, [flowScopeMap]);
+    // H5: Compute the persisted state synchronously from the latest committed ref.
+    // React may defer functional state updaters, so deriving persistence payloads
+    // from inside `setState(...)` can skip writes entirely at runtime.
+    const updateFlowState = useCallback((flowRef, updater, options) => {
+        const currentScopedStates = scopedStatesRef.current;
+        const scope = options?.scopeOverride ?? resolveFlowStateScope(flowRef, currentScopedStates);
+        const scopeState = currentScopedStates[scope] ?? { flows: {} };
+        const currentFlowState = scopeState.flows[flowRef] ?? {
+            status: OnboardingStatus.NOT_STARTED,
+            elements: {},
+            triggerCount: 0,
+        };
+        const updatedFlowState = updater(currentFlowState);
+        const nextScopeState = {
+            ...scopeState,
+            flows: { ...scopeState.flows, [flowRef]: updatedFlowState },
+        };
+        commitScopedStates({
+            ...currentScopedStates,
+            [scope]: nextScopeState,
         });
-        if (newScopeState) {
-            persistGuidanceState(scope, newScopeState, resourceRegistry.doOperation, resourceRegistry.registry);
-        }
-    }, [flowScopeMap, resourceRegistry]);
+        void persistGuidanceState(scope, nextScopeState, resourceRegistry.doOperation, resourceRegistry.registry);
+    }, [commitScopedStates, resolveFlowStateScope, resourceRegistry]);
     // ─── Trigger Engine ─────────────────────────────────────────
     const tryActivateFlow = useCallback((flowRef) => {
         const flow = flowRegistry.get(flowRef);
@@ -565,12 +705,8 @@ export const GuidanceContextProvider = ({ children }) => {
             return;
         }
         const state = flowStates[flowRef];
-        // H3-4: Block DISMISSED/SKIPPED flows from re-activating
-        if (state?.status === OnboardingStatus.DISMISSED)
-            return;
-        if (state?.status === OnboardingStatus.SKIPPED)
-            return;
-        if (state?.status === OnboardingStatus.COMPLETED)
+        // H3-4: Block terminal (completed / dismissed / skipped) flows from re-activating
+        if (isTerminalOnboardingStatus(state?.status))
             return;
         if (state?.status === OnboardingStatus.IN_PROGRESS && activeFlowRefs.has(flowRef))
             return;
@@ -704,8 +840,8 @@ export const GuidanceContextProvider = ({ children }) => {
         tryActivateFlow(ref);
     }, [tryActivateFlow, guidanceIsLoading]);
     const completeElement = useCallback((flowRef, elementRef, data) => {
-        // H3-6: Guard — unknown flow no-op
-        if (!flowRegistry.has(flowRef))
+        // H3-6: Guard — unknown flow OR onboarding view no-op
+        if (!persistenceRegistry.has(flowRef))
             return;
         // L18: Validate survey answers against schema before persisting
         let validatedSurveyAnswers;
@@ -734,9 +870,10 @@ export const GuidanceContextProvider = ({ children }) => {
                 },
             },
         }));
-        const flow = flowRegistry.get(flowRef);
-        if (flow) {
-            const element = flow.elements.find(e => e.ref === elementRef);
+        // GUIDANCE_* events are flow-only: skip for onboarding views (no renderMode).
+        const entry = persistenceRegistry.get(flowRef);
+        if (entry?.renderMode) {
+            const element = entry.elements.find(e => e.ref === elementRef);
             if (element) {
                 emit(FrontendEvents.GUIDANCE_ELEMENT_COMPLETED, {
                     flowRef,
@@ -746,16 +883,18 @@ export const GuidanceContextProvider = ({ children }) => {
             }
         }
         logDebug(`Element completed: ${flowRef}/${elementRef}`);
-    }, [updateFlowState, flowRegistry, emit, logDebug]);
+    }, [updateFlowState, persistenceRegistry, emit, logDebug]);
     const completeFlow = useCallback((flowRef) => {
-        // H3-6: Guard — unknown flow no-op
-        if (!flowRegistry.has(flowRef))
+        // H3-6: Guard — unknown flow OR onboarding view no-op
+        if (!persistenceRegistry.has(flowRef))
             return;
-        // H3-7: State transition validation — only complete from IN_PROGRESS
+        // H3-7: State transition validation — block only from a terminal state.
+        // A flow shown by a direct renderer (standalone OnboardingView) may still be
+        // NOT_STARTED/undefined when the user completes it (it is never routed through
+        // the trigger engine), so allow any non-terminal status to reach COMPLETED —
+        // mirrors dismiss/skip and keeps the four lifecycle guards aligned.
         const currentState = flowStates[flowRef];
-        if (currentState?.status === OnboardingStatus.COMPLETED)
-            return;
-        if (currentState?.status !== OnboardingStatus.IN_PROGRESS)
+        if (isTerminalOnboardingStatus(currentState?.status))
             return;
         updateFlowState(flowRef, (prev) => ({
             ...prev,
@@ -767,25 +906,30 @@ export const GuidanceContextProvider = ({ children }) => {
             next.delete(flowRef);
             return next;
         });
-        const flow = flowRegistry.get(flowRef);
-        const scope = flowScopeMap[flowRef] ?? GuidanceFlowScope.USER;
-        if (flow) {
+        // Flow-only event: onboarding views (no renderMode) persist silently.
+        const entry = persistenceRegistry.get(flowRef);
+        const scope = resolveFlowStateScope(flowRef);
+        if (entry?.renderMode) {
             emit(FrontendEvents.GUIDANCE_FLOW_COMPLETED, {
                 flowRef,
-                renderMode: flow.renderMode,
+                renderMode: entry.renderMode,
                 triggerSource: 'frontend',
                 scope,
             });
         }
         logDebug(`Flow completed: ${flowRef}`);
-    }, [updateFlowState, flowRegistry, flowStates, flowScopeMap, emit, logDebug]);
+    }, [updateFlowState, persistenceRegistry, flowStates, resolveFlowStateScope, emit, logDebug]);
     const dismissFlow = useCallback((flowRef) => {
-        // H3-6: Guard — unknown flow no-op
-        if (!flowRegistry.has(flowRef))
+        // H3-6: Guard — unknown flow OR onboarding view no-op
+        if (!persistenceRegistry.has(flowRef))
             return;
-        // H3-7: State transition validation — only dismiss from IN_PROGRESS
+        // H3-7: State transition validation — block only from a terminal state.
+        // A standalone OnboardingView persists its dismiss through this flow ref
+        // without ever activating the flow, so it is typically NOT_STARTED/undefined
+        // at first dismiss; allow any non-terminal status to be dismissed (mirrors
+        // skip) so the dismissal is actually persisted to the backend.
         const currentState = flowStates[flowRef];
-        if (currentState?.status !== OnboardingStatus.IN_PROGRESS)
+        if (isTerminalOnboardingStatus(currentState?.status))
             return;
         updateFlowState(flowRef, (prev) => ({
             ...prev,
@@ -797,25 +941,27 @@ export const GuidanceContextProvider = ({ children }) => {
             next.delete(flowRef);
             return next;
         });
-        const flow = flowRegistry.get(flowRef);
-        const scope = flowScopeMap[flowRef] ?? GuidanceFlowScope.USER;
-        if (flow) {
+        // Flow-only event: onboarding views (no renderMode) persist silently.
+        const entry = persistenceRegistry.get(flowRef);
+        const scope = resolveFlowStateScope(flowRef);
+        if (entry?.renderMode) {
             emit(FrontendEvents.GUIDANCE_FLOW_DISMISSED, {
                 flowRef,
-                renderMode: flow.renderMode,
+                renderMode: entry.renderMode,
                 triggerSource: 'frontend',
                 scope,
             });
         }
         logDebug(`Flow dismissed: ${flowRef}`);
-    }, [updateFlowState, flowRegistry, flowStates, flowScopeMap, emit, logDebug]);
+    }, [updateFlowState, persistenceRegistry, flowStates, resolveFlowStateScope, emit, logDebug]);
     const skipFlow = useCallback((flowRef) => {
-        // H3-6: Guard — unknown flow no-op
-        if (!flowRegistry.has(flowRef))
+        // H3-6: Guard — unknown flow OR onboarding view no-op
+        if (!persistenceRegistry.has(flowRef))
             return;
-        // H3-7: State transition validation — only skip from IN_PROGRESS or NOT_STARTED
+        // H3-7: State transition validation — block only from a terminal state
+        // (mirrors complete/dismiss via the shared predicate).
         const currentState = flowStates[flowRef];
-        if (currentState?.status !== OnboardingStatus.IN_PROGRESS && currentState?.status !== OnboardingStatus.NOT_STARTED && currentState !== undefined)
+        if (isTerminalOnboardingStatus(currentState?.status))
             return;
         updateFlowState(flowRef, (prev) => ({
             ...prev,
@@ -827,13 +973,17 @@ export const GuidanceContextProvider = ({ children }) => {
             return next;
         });
         logDebug(`Flow skipped: ${flowRef}`);
-    }, [updateFlowState, flowRegistry, flowStates, logDebug]);
+    }, [updateFlowState, persistenceRegistry, flowStates, logDebug]);
     const isFlowActive = useCallback((ref) => {
         return activeFlowRefs.has(ref);
     }, [activeFlowRefs]);
     const isFlowCompleted = useCallback((ref) => {
         return flowStates[ref]?.status === OnboardingStatus.COMPLETED;
     }, [flowStates]);
+    // True for guidance flows AND app-config onboarding views — see persistenceRegistry.
+    const isFlowPersistable = useCallback((ref) => {
+        return persistenceRegistry.has(ref);
+    }, [persistenceRegistry]);
     // ─── WS / EventBus Subscriptions ───────────────────────────
     // Listen for backend-pushed guidance events
     useEffect(() => {
@@ -850,7 +1000,7 @@ export const GuidanceContextProvider = ({ children }) => {
                     status: OnboardingStatus.IN_PROGRESS,
                     startedAt: prev.startedAt ?? new Date(),
                     triggerCount: (prev.triggerCount ?? 0) + 1,
-                }));
+                }), { scopeOverride: payload.scope });
             }
         });
         const unsubCompleted = on(FrontendEvents.GUIDANCE_FLOW_COMPLETED, (payload) => {
@@ -865,7 +1015,7 @@ export const GuidanceContextProvider = ({ children }) => {
                     ...prev,
                     status: OnboardingStatus.COMPLETED,
                     completedAt: new Date(),
-                }));
+                }), { scopeOverride: payload.scope });
             }
         });
         const unsubDismissed = on(FrontendEvents.GUIDANCE_FLOW_DISMISSED, (payload) => {
@@ -880,7 +1030,7 @@ export const GuidanceContextProvider = ({ children }) => {
                     ...prev,
                     status: OnboardingStatus.DISMISSED,
                     dismissedAt: new Date(),
-                }));
+                }), { scopeOverride: payload.scope });
             }
         });
         return () => {
@@ -948,8 +1098,28 @@ export const GuidanceContextProvider = ({ children }) => {
                 });
             }
         });
+        // Progression progress (non-achievement): merge the authoritative
+        // post-increment operationCounts so in-progress milestone bars advance live
+        // (e.g. 8/10 → 9/10) without waiting for achievement or a page reload. The
+        // MILESTONE_ACHIEVED handler above owns milestonesAchieved / categories /
+        // celebration; here we only refresh counts + totalPoints.
+        const unsubProgressionUpdate = on(FrontendEvents.PROGRESSION_UPDATED, (payload) => {
+            const scope = payload.scope;
+            setProgressionScopedStates(prev => {
+                const current = prev[scope] ?? { milestonesAchieved: {}, operationCounts: {}, totalPoints: 0, categoriesProgress: {} };
+                return {
+                    ...prev,
+                    [scope]: {
+                        ...current,
+                        operationCounts: payload.operationCounts,
+                        totalPoints: payload.totalPoints,
+                    },
+                };
+            });
+        });
         return () => {
             unsubMilestone();
+            unsubProgressionUpdate();
         };
     }, [on, logDebug, emit, featuresCtx]);
     // ─── Lifecycle WS Subscription (Phase 5) ────────────────────
@@ -960,7 +1130,7 @@ export const GuidanceContextProvider = ({ children }) => {
             logDebug(`Lifecycle stage changed: ${payload.previousStage} → ${payload.newStage} (scope: ${payload.scope})`);
             const scope = payload.scope;
             setLifecycleScopedStates(prev => {
-                const current = prev[scope] ?? createInitialLifecycleState(new Date(payload.changedAt));
+                const current = prev[scope] ?? GuidanceStateUtils.createInitialLifecycleState(new Date(payload.changedAt));
                 const changedAtDate = new Date(payload.changedAt);
                 const updatedHistory = [...current.stageHistory];
                 if (updatedHistory.length > 0 && !updatedHistory[0].exitedAt) {
@@ -1092,6 +1262,7 @@ export const GuidanceContextProvider = ({ children }) => {
         skipFlow,
         isFlowActive,
         isFlowCompleted,
+        isFlowPersistable,
         isLoading: guidanceIsLoading,
         progression: progressionSlice,
         lifecycle: lifecycleSlice,
@@ -1105,10 +1276,11 @@ export const GuidanceContextProvider = ({ children }) => {
         skipFlow,
         isFlowActive,
         isFlowCompleted,
+        isFlowPersistable,
         guidanceIsLoading,
         progressionSlice,
         lifecycleSlice,
     ]);
     return (_jsx(GuidanceContext.Provider, { value: contextValue, children: children }));
 };
-//# sourceMappingURL=GuidanceContext.js.map
+//# sourceMappingURL=GuidanceContext.js.map