@wildo-ai/saas-frontend-lib 1.0.1

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

@@ -0,0 +1,1114 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Guidance Context Provider
+ *
+ * Central frontend context for managing guidance flows (onboarding, tooltips,
+ * tours, banners, surveys, checklists). Provides:
+ * - Multi-scope state management (USER / ORGANIZATION)
+ * - 5 trigger types (FIRST_VISIT, ROUTE_MATCH, EVENT, DELAYED, MANUAL)
+ * - Audience evaluation (roles, features, completed flows, creation date)
+ * - Coexistence rules (max 1 overlay, max 1 checklist, N inline)
+ * - 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 { compileResourceGuidance } from './guidance-resource-compiler.shared.utils.js';
+import { ApplicationContext } from '../../core/runtime/ApplicationContext.shared.js';
+import { useEventBus } from '../../core/events/useEventBus.js';
+import { FrontendEvents } from '../../core/events/events.frontend.schemas.js';
+import { getManualCallsHttpClient } from '../../core/requests/wildo-http-client-manual-calls.frontend.service.js';
+import { useUserOrgs } from '../../core/security/useUserOrgs.js';
+import { useAppScopeSafe } from '../../core/scope/useAppScope.js';
+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 { evaluateGuidanceAudience, } from './guidance-audience.frontend.utils.js';
+// ─── Context ────────────────────────────────────────────────────
+// Note: useGuidance / useLifecycle / useProgression hooks are in useGuidance.ts for React Fast Refresh compatibility.
+export const GuidanceContext = createContext(null);
+const EMPTY_ACTIVE_FLOWS = [];
+const EMPTY_FLOW_STATES = {};
+const EMPTY_MILESTONE_DEFINITIONS = [];
+const EMPTY_SCOPED_PROGRESSION = {
+    [ProgressionScope.USER]: null,
+    [ProgressionScope.ORGANIZATION]: null,
+};
+export const PROGRESSION_DEFAULTS = {
+    scopedStates: EMPTY_SCOPED_PROGRESSION,
+    isMilestoneAchieved: () => false,
+    getMilestoneAchievement: () => undefined,
+    getCategoryProgress: () => undefined,
+    totalPoints: 0,
+    milestoneDefinitions: EMPTY_MILESTONE_DEFINITIONS,
+    isLoading: false,
+};
+export const LIFECYCLE_DEFAULTS = {
+    currentStage: null,
+    stageEnteredAt: null,
+    isEnabled: false,
+    isLoading: false,
+    hasReachedStage: () => false,
+    activationProgress: {
+        criteriaMet: {},
+        criteria: [],
+        totalCriteria: 0,
+        metCriteria: 0,
+        isFullyActivated: false,
+    },
+};
+// H3-10: Module-level stable fallback — prevents new object on every render outside provider
+export const GUIDANCE_FALLBACK = {
+    activeFlows: EMPTY_ACTIVE_FLOWS,
+    flowStates: EMPTY_FLOW_STATES,
+    activateFlow: () => { },
+    completeElement: () => { },
+    completeFlow: () => { },
+    dismissFlow: () => { },
+    skipFlow: () => { },
+    isFlowActive: () => false,
+    isFlowCompleted: () => false,
+    isLoading: false,
+    progression: PROGRESSION_DEFAULTS,
+    lifecycle: LIFECYCLE_DEFAULTS,
+};
+// ─── State Persistence Helpers ──────────────────────────────────
+function findApiCallOperation(registry, resourceType, operationId) {
+    const config = registry.resourceConfigurations[resourceType];
+    if (!config)
+        return null;
+    return config.operations.find((o) => o.operationIdentifier === operationId
+        && o.variantType === ResourceOperationVariantType.API_CALL) ?? null;
+}
+async function fetchGuidanceState(scope, doOperation, registry) {
+    const resourceType = GUIDANCE_SCOPE_TO_RESOURCE[scope];
+    const operation = findApiCallOperation(registry, resourceType, CoreResourceOperation.READ);
+    if (!operation)
+        return { flows: {} };
+    const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
+    try {
+        const result = await doOperation(operationPath, { contextualParameters: {} });
+        return result ?? { flows: {} };
+    }
+    catch (err) {
+        if (isWildoBackendError(err) && err.statusCode === 404)
+            return null;
+        return { flows: {} };
+    }
+}
+async function createGuidanceState(scope, doOperation, registry) {
+    const resourceType = GUIDANCE_SCOPE_TO_RESOURCE[scope];
+    const operation = findApiCallOperation(registry, resourceType, CoreResourceOperation.CREATE);
+    if (!operation)
+        return { flows: {} };
+    const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
+    try {
+        const result = await doOperation(operationPath, {
+            contextualParameters: {},
+            requestData: { flows: {} },
+        });
+        return result ?? { flows: {} };
+    }
+    catch {
+        // M14: Another tab may have created it — retry read
+        const existingState = await fetchGuidanceState(scope, doOperation, registry);
+        if (existingState)
+            return existingState;
+        return { flows: {} };
+    }
+}
+async function persistGuidanceState(scope, state, doOperation, registry) {
+    const resourceType = GUIDANCE_SCOPE_TO_RESOURCE[scope];
+    const operation = findApiCallOperation(registry, resourceType, CoreResourceOperation.UPDATE);
+    if (!operation)
+        return;
+    const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
+    try {
+        await doOperation(operationPath, { contextualParameters: {}, requestData: state });
+    }
+    catch {
+        /* Best-effort persistence */
+    }
+}
+async function fetchProgressionState(scope, doOperation, registry) {
+    const resourceType = PROGRESSION_SCOPE_TO_RESOURCE[scope];
+    const operation = findApiCallOperation(registry, resourceType, CoreResourceOperation.READ);
+    if (!operation)
+        return null;
+    const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
+    try {
+        const result = await doOperation(operationPath, { contextualParameters: {} });
+        return result ?? { milestonesAchieved: {}, operationCounts: {}, totalPoints: 0, categoriesProgress: {} };
+    }
+    catch (err) {
+        if (isWildoBackendError(err) && err.statusCode === 404)
+            return null;
+        return { milestonesAchieved: {}, operationCounts: {}, totalPoints: 0, categoriesProgress: {} };
+    }
+}
+async function fetchMilestoneDefinitions(analyticsEnabled) {
+    if (!analyticsEnabled) {
+        return [];
+    }
+    try {
+        const response = await getManualCallsHttpClient().getMilestoneDefinitions({ silent: true });
+        return response?.definitions ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+const EMPTY_SCOPED_LIFECYCLE = {
+    [LifecycleScope.USER]: null,
+    [LifecycleScope.ORGANIZATION]: null,
+};
+async function fetchLifecycleState(scope, doOperation, registry) {
+    const resourceType = LIFECYCLE_SCOPE_TO_RESOURCE[scope];
+    const operation = findApiCallOperation(registry, resourceType, CoreResourceOperation.READ);
+    if (!operation)
+        return null;
+    const operationPath = ResourcesConfig_OperationPathUtils.buildOperationPathKeyFromOperation(operation);
+    try {
+        const result = await doOperation(operationPath, { contextualParameters: {} });
+        return result ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Audience Evaluator ─────────────────────────────────────────
+// ─── Coexistence Enforcer ───────────────────────────────────────
+function enforceCoexistence(eligible) {
+    const sorted = [...eligible].sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+    const result = [];
+    let hasOverlay = false;
+    let hasChecklist = false;
+    for (const flow of sorted) {
+        switch (flow.renderMode) {
+            case GuidanceRenderMode.OVERLAY:
+                if (!hasOverlay) {
+                    result.push(flow);
+                    hasOverlay = true;
+                }
+                break;
+            case GuidanceRenderMode.CHECKLIST:
+                if (!hasChecklist) {
+                    result.push(flow);
+                    hasChecklist = true;
+                }
+                break;
+            case GuidanceRenderMode.INLINE:
+                result.push(flow);
+                break;
+        }
+    }
+    return result;
+}
+export const GuidanceContextProvider = ({ children }) => {
+    const appContext = useContext(ApplicationContext);
+    const { on, emit } = useEventBus();
+    const userOrgs = useUserOrgs();
+    const appScope = useAppScopeSafe();
+    const resourceRegistry = useResourceRegistry();
+    const featuresCtx = useContext(FeaturesContext);
+    const logger = useMemo(() => LoggerFrontendService.getLogger(), []);
+    const logDebug = useMemo(() => {
+        const debugFn = logger.debugByType('GuidanceContext');
+        logger.setDebugTypeLogging('GuidanceContext', false);
+        return debugFn;
+    }, [logger]);
+    // ─── Flow Registry ──────────────────────────────────────────
+    const flowDefinitions = useMemo(() => {
+        const appFlows = [];
+        const frontendConfig = appContext?.frontendConfiguration;
+        if (frontendConfig?.guidanceFlows) {
+            appFlows.push(...frontendConfig.guidanceFlows);
+        }
+        // Compile resource-level guidance declarations into standard GuidanceFlowDefinition objects
+        const resourceFlows = [];
+        if (resourceRegistry?.registry) {
+            for (const resourceType of resourceRegistry.getAvailableResourceTypes()) {
+                const config = resourceRegistry.getResourceConfiguration(resourceType);
+                const guidanceDeclarations = config?.frontendConfiguration?.guidance;
+                if (guidanceDeclarations && Array.isArray(guidanceDeclarations) && guidanceDeclarations.length > 0) {
+                    const compiled = compileResourceGuidance({
+                        resourceType,
+                        guidanceFlows: guidanceDeclarations,
+                    });
+                    resourceFlows.push(...compiled);
+                }
+            }
+        }
+        return [...appFlows, ...resourceFlows];
+    }, [appContext?.frontendConfiguration, resourceRegistry]);
+    const flowRegistry = useMemo(() => {
+        const map = new Map();
+        for (const flow of flowDefinitions) {
+            map.set(flow.ref, flow);
+        }
+        return map;
+    }, [flowDefinitions]);
+    const flowScopeMap = useMemo(() => {
+        const map = {};
+        for (const flow of flowDefinitions) {
+            map[flow.ref] = flow.scope ?? GuidanceFlowScope.USER;
+        }
+        return map;
+    }, [flowDefinitions]);
+    // ─── State ──────────────────────────────────────────────────
+    const [scopedStates, setScopedStates] = useState({});
+    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());
+    // Progression state (Phase 4)
+    const [progressionScopedStates, setProgressionScopedStates] = useState({ ...EMPTY_SCOPED_PROGRESSION });
+    const [progressionIsLoading, setProgressionIsLoading] = useState(true);
+    const progressionInitRef = useRef(false);
+    const [milestoneDefinitions, setMilestoneDefinitions] = useState(EMPTY_MILESTONE_DEFINITIONS);
+    // ─── Lifecycle State (Phase 5) ────────────────────────────────
+    const lifecycleConfig = appContext?.appConfig?.lifecycle;
+    const lifecycleEnabled = !!lifecycleConfig?.enabled;
+    const [lifecycleScopedStates, setLifecycleScopedStates] = useState({ ...EMPTY_SCOPED_LIFECYCLE });
+    const [lifecycleIsLoading, setLifecycleIsLoading] = useState(lifecycleEnabled);
+    const lifecycleInitRef = useRef(false);
+    const lifecycleActivationCriteria = useMemo(() => lifecycleConfig?.activationCriteria, [lifecycleConfig?.activationCriteria]);
+    const currentUserId = userOrgs.user?._id ?? null;
+    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 guidanceIsLoading = isAuthenticated
+        ? (flowDefinitions.length > 0 ? (isLoading || guidanceIsBootstrapping) : false)
+        : false;
+    // Derive applicable scopes from current user context
+    const applicableScopes = useMemo(() => {
+        const scopes = [GuidanceFlowScope.USER];
+        if (appScope?.currentOrganizationId) {
+            scopes.push(GuidanceFlowScope.ORGANIZATION);
+        }
+        return scopes;
+    }, [appScope?.currentOrganizationId]);
+    // M9: Reset init refs and org-scoped caches when applicable scopes change.
+    const prevScopesRef = useRef(applicableScopes);
+    useEffect(() => {
+        if (prevScopesRef.current !== applicableScopes) {
+            initRef.current = false;
+            progressionInitRef.current = false;
+            lifecycleInitRef.current = false;
+            pendingFeatureActivationRefsRef.current.clear();
+            prevScopesRef.current = applicableScopes;
+            if (isAuthenticated && flowDefinitions.length > 0) {
+                setIsLoading(true);
+            }
+            if (isAuthenticated) {
+                setProgressionIsLoading(true);
+            }
+            if (isAuthenticated && lifecycleEnabled) {
+                setLifecycleIsLoading(true);
+            }
+            setScopedStates(prev => {
+                if (!(GuidanceFlowScope.ORGANIZATION in prev)) {
+                    return prev;
+                }
+                const next = { ...prev };
+                delete next[GuidanceFlowScope.ORGANIZATION];
+                return next;
+            });
+            setProgressionScopedStates(prev => ({
+                ...prev,
+                [ProgressionScope.ORGANIZATION]: null,
+            }));
+            setLifecycleScopedStates(prev => ({
+                ...prev,
+                [LifecycleScope.ORGANIZATION]: null,
+            }));
+            setActiveFlowRefs(prev => {
+                const next = new Set(prev);
+                for (const flow of flowDefinitions) {
+                    if ((flow.scope ?? GuidanceFlowScope.USER) === GuidanceFlowScope.ORGANIZATION) {
+                        next.delete(flow.ref);
+                    }
+                }
+                return next;
+            });
+        }
+    }, [applicableScopes, flowDefinitions, isAuthenticated, lifecycleEnabled]);
+    const previousAuthStateRef = useRef({
+        isAuthenticated,
+        userId: currentUserId,
+    });
+    useEffect(() => {
+        const previousAuthState = previousAuthStateRef.current;
+        const loggedOut = previousAuthState.isAuthenticated && !isAuthenticated;
+        const switchedUsers = previousAuthState.userId !== null
+            && currentUserId !== null
+            && previousAuthState.userId !== currentUserId;
+        previousAuthStateRef.current = {
+            isAuthenticated,
+            userId: currentUserId,
+        };
+        if (!loggedOut && !switchedUsers) {
+            return;
+        }
+        for (const timer of delayTimersRef.current.values()) {
+            clearTimeout(timer);
+        }
+        delayTimersRef.current.clear();
+        initRef.current = false;
+        progressionInitRef.current = false;
+        lifecycleInitRef.current = false;
+        pendingFeatureActivationRefsRef.current.clear();
+        setScopedStates({});
+        setActiveFlowRefs(new Set());
+        setProgressionScopedStates({ ...EMPTY_SCOPED_PROGRESSION });
+        setMilestoneDefinitions(EMPTY_MILESTONE_DEFINITIONS);
+        setLifecycleScopedStates({ ...EMPTY_SCOPED_LIFECYCLE });
+        setIsLoading(isAuthenticated && flowDefinitions.length > 0);
+        setProgressionIsLoading(isAuthenticated);
+        setLifecycleIsLoading(isAuthenticated && lifecycleEnabled);
+    }, [currentUserId, flowDefinitions.length, isAuthenticated, lifecycleEnabled]);
+    // Flatten all flow states across scopes into a single record
+    const flowStates = useMemo(() => {
+        const merged = {};
+        for (const scope of applicableScopes) {
+            const state = scopedStates[scope];
+            if (state?.flows) {
+                Object.assign(merged, state.flows);
+            }
+        }
+        return merged;
+    }, [scopedStates, applicableScopes]);
+    // Build audience context for evaluations
+    const audienceContext = useMemo(() => {
+        const completedRefs = new Set();
+        for (const [ref, state] of Object.entries(flowStates)) {
+            if (state.status === OnboardingStatus.COMPLETED) {
+                completedRefs.add(ref);
+            }
+        }
+        const userRoles = buildFeaturePolicyRoles(userOrgs.permissions, appScope?.currentOrganizationId)
+            .filter(Boolean);
+        // H3-3: Collect user features from FeaturesContext (resolved features from backend)
+        const userFeatures = featuresCtx?.resolvedFeatures?.features ?? [];
+        const featureLimits = featuresCtx?.resolvedFeatures?.limits ?? {};
+        const currentUsage = featuresCtx?.resolvedFeatures?.currentUsage ?? {};
+        return {
+            userRoles,
+            userFeatures,
+            featureLimits,
+            currentUsage,
+            completedFlowRefs: completedRefs,
+            userCreatedAt: userOrgs.user?.createdAt ? new Date(userOrgs.user.createdAt) : undefined,
+        };
+    }, [
+        flowStates,
+        userOrgs.permissions,
+        appScope?.currentOrganizationId,
+        userOrgs.user?.createdAt,
+        featuresCtx?.resolvedFeatures?.features,
+        featuresCtx?.resolvedFeatures?.limits,
+        featuresCtx?.resolvedFeatures?.currentUsage,
+    ]);
+    // ─── Initialization ─────────────────────────────────────────
+    // H3-8: Abort guard prevents setState on unmounted/stale effect
+    useEffect(() => {
+        if (initRef.current || flowDefinitions.length === 0 || !userOrgs.isAuthenticated())
+            return;
+        initRef.current = true;
+        let cancelled = false;
+        const initialize = async () => {
+            logDebug('Initializing guidance state', { scopes: applicableScopes, flowCount: flowDefinitions.length });
+            const stateResults = await Promise.allSettled(applicableScopes.map(async (scope) => {
+                let state = await fetchGuidanceState(scope, resourceRegistry.doOperation, resourceRegistry.registry);
+                if (state === null) {
+                    logDebug(`Auto-creating guidance state for scope ${scope}`);
+                    state = await createGuidanceState(scope, resourceRegistry.doOperation, resourceRegistry.registry);
+                }
+                return { scope, state };
+            }));
+            if (cancelled)
+                return;
+            const newStates = {};
+            for (const result of stateResults) {
+                if (result.status === 'fulfilled' && result.value.state) {
+                    newStates[result.value.scope] = result.value.state;
+                }
+            }
+            // M7: Functional updater — merge with any concurrent WS updates
+            setScopedStates(prev => ({ ...prev, ...newStates }));
+            setIsLoading(false);
+            logDebug('Guidance state loaded', { scopeCount: Object.keys(newStates).length });
+        };
+        initialize();
+        return () => { cancelled = true; };
+    }, [flowDefinitions.length, applicableScopes, logDebug, userOrgs, resourceRegistry]);
+    // ─── Progression Initialization (Phase 4) ──────────────────
+    const progressionApplicableScopes = useMemo(() => {
+        const scopes = [ProgressionScope.USER];
+        if (appScope?.currentOrganizationId) {
+            scopes.push(ProgressionScope.ORGANIZATION);
+        }
+        return scopes;
+    }, [appScope?.currentOrganizationId]);
+    // H3-8: Abort guard for progression init
+    useEffect(() => {
+        if (progressionInitRef.current || !userOrgs.isAuthenticated())
+            return;
+        progressionInitRef.current = true;
+        let cancelled = false;
+        const initializeProgression = async () => {
+            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);
+                    return { scope, state };
+                })),
+                fetchMilestoneDefinitions(analyticsEnabled),
+            ]);
+            if (cancelled)
+                return;
+            const newStates = { ...EMPTY_SCOPED_PROGRESSION };
+            for (const result of stateResults) {
+                if (result.status === 'fulfilled' && result.value.state) {
+                    newStates[result.value.scope] = result.value.state;
+                }
+            }
+            // M7: Functional updater — merge with concurrent WS updates
+            setProgressionScopedStates(prev => ({ ...prev, ...newStates }));
+            if (definitions.length > 0) {
+                setMilestoneDefinitions(definitions);
+            }
+            setProgressionIsLoading(false);
+            logDebug('Progression state loaded', {
+                scopeCount: Object.values(newStates).filter(Boolean).length,
+                milestoneDefinitionCount: definitions.length,
+            });
+        };
+        initializeProgression();
+        return () => { cancelled = true; };
+    }, [analyticsEnabled, progressionApplicableScopes, logDebug, userOrgs, resourceRegistry, appContext]);
+    // ─── Lifecycle Initialization (Phase 5) ─────────────────────
+    const lifecycleApplicableScopes = useMemo(() => {
+        if (!lifecycleEnabled)
+            return [];
+        const scopes = [LifecycleScope.USER];
+        if (appScope?.currentOrganizationId) {
+            scopes.push(LifecycleScope.ORGANIZATION);
+        }
+        return scopes;
+    }, [lifecycleEnabled, appScope?.currentOrganizationId]);
+    // H3-8: Abort guard for lifecycle init
+    useEffect(() => {
+        if (lifecycleInitRef.current || !userOrgs.isAuthenticated() || !lifecycleEnabled) {
+            return;
+        }
+        lifecycleInitRef.current = true;
+        let cancelled = false;
+        const initializeLifecycle = async () => {
+            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() };
+            }));
+            if (cancelled)
+                return;
+            const newStates = { ...EMPTY_SCOPED_LIFECYCLE };
+            for (const result of stateResults) {
+                if (result.status === 'fulfilled' && result.value.state) {
+                    newStates[result.value.scope] = result.value.state;
+                }
+            }
+            // M7: Functional updater — merge with concurrent WS updates
+            setLifecycleScopedStates(prev => ({ ...prev, ...newStates }));
+            setLifecycleIsLoading(false);
+            logDebug('Lifecycle state loaded', { scopeCount: Object.values(newStates).filter(Boolean).length });
+        };
+        initializeLifecycle();
+        return () => { cancelled = true; };
+    }, [lifecycleApplicableScopes, logDebug, userOrgs, lifecycleEnabled, resourceRegistry]);
+    // ─── 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 };
+        });
+        if (newScopeState) {
+            persistGuidanceState(scope, newScopeState, resourceRegistry.doOperation, resourceRegistry.registry);
+        }
+    }, [flowScopeMap, resourceRegistry]);
+    // ─── Trigger Engine ─────────────────────────────────────────
+    const tryActivateFlow = useCallback((flowRef) => {
+        const flow = flowRegistry.get(flowRef);
+        if (!flow)
+            return;
+        const scope = flowScopeMap[flowRef] ?? GuidanceFlowScope.USER;
+        if (!applicableScopes.includes(scope))
+            return;
+        if (featuresAreLoading && flow.audience?.requiredFeatures) {
+            pendingFeatureActivationRefsRef.current.add(flowRef);
+            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)
+            return;
+        if (state?.status === OnboardingStatus.IN_PROGRESS && activeFlowRefs.has(flowRef))
+            return;
+        if (!evaluateGuidanceAudience(flow.audience, audienceContext))
+            return;
+        logDebug(`Activating flow: ${flowRef}`);
+        setActiveFlowRefs(prev => {
+            const next = new Set(prev);
+            next.add(flowRef);
+            return next;
+        });
+        // H3-1 + H3-2: Set IN_PROGRESS and increment triggerCount
+        updateFlowState(flowRef, prev => ({
+            ...prev,
+            status: OnboardingStatus.IN_PROGRESS,
+            startedAt: prev.startedAt ?? new Date(),
+            triggerCount: (prev.triggerCount ?? 0) + 1,
+        }));
+        emit(FrontendEvents.GUIDANCE_FLOW_ACTIVATED, {
+            flowRef,
+            renderMode: flow.renderMode,
+            triggerSource: 'frontend',
+            scope,
+        });
+    }, [flowRegistry, flowStates, activeFlowRefs, audienceContext, flowScopeMap, applicableScopes, emit, logDebug, updateFlowState, featuresAreLoading]);
+    // FIRST_VISIT trigger: run after each relevant state load boundary.
+    useEffect(() => {
+        if (guidanceIsLoading || featuresAreLoading || flowDefinitions.length === 0)
+            return;
+        for (const flow of flowDefinitions) {
+            if (flow.trigger.type !== OnboardingTriggerType.FIRST_VISIT)
+                continue;
+            const state = flowStates[flow.ref];
+            if (!state || state.triggerCount === 0) {
+                tryActivateFlow(flow.ref);
+            }
+        }
+        // Re-run after load boundaries or scope changes, but not on every flow-state mutation.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [guidanceIsLoading, featuresAreLoading, applicableScopes]);
+    useEffect(() => {
+        if (featuresAreLoading || pendingFeatureActivationRefsRef.current.size === 0) {
+            return;
+        }
+        const pendingFlowRefs = Array.from(pendingFeatureActivationRefsRef.current);
+        pendingFeatureActivationRefsRef.current.clear();
+        for (const flowRef of pendingFlowRefs) {
+            tryActivateFlow(flowRef);
+        }
+    }, [featuresAreLoading, tryActivateFlow]);
+    // H3-11: Pre-compile route-match regexes to avoid ReDoS on every navigation event
+    const routeFlowsCompiled = useMemo(() => flowDefinitions
+        .filter(f => f.trigger.type === OnboardingTriggerType.ROUTE_MATCH && f.trigger.routePattern)
+        .map(f => {
+        try {
+            return { ...f, _compiledPattern: new RegExp(f.trigger.routePattern) };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((f) => f !== null), [flowDefinitions]);
+    // ROUTE_MATCH trigger: subscribe to navigation pane changes
+    useEffect(() => {
+        if (guidanceIsLoading || routeFlowsCompiled.length === 0)
+            return;
+        return on(FrontendEvents.NAVIGATION_ZONE_CHANGED, (payload) => {
+            const currentPath = payload.currentContent?.urlPath;
+            if (!currentPath)
+                return;
+            for (const flow of routeFlowsCompiled) {
+                if (flow._compiledPattern.test(currentPath)) {
+                    tryActivateFlow(flow.ref);
+                }
+            }
+        });
+    }, [guidanceIsLoading, routeFlowsCompiled, on, tryActivateFlow]);
+    // EVENT trigger: subscribe to resource success events
+    useEffect(() => {
+        if (guidanceIsLoading || flowDefinitions.length === 0)
+            return;
+        const eventFlows = flowDefinitions.filter(f => f.trigger.type === OnboardingTriggerType.EVENT && f.trigger.eventName);
+        if (eventFlows.length === 0)
+            return;
+        return on(FrontendEvents.NOTIFY_RESOURCE_SUCCESS, (payload) => {
+            const eventName = `${payload.resourceType}:${payload.operationIdentifier}`;
+            for (const flow of eventFlows) {
+                if (flow.trigger.eventName === eventName || flow.trigger.eventName === payload.operationIdentifier) {
+                    tryActivateFlow(flow.ref);
+                }
+            }
+        });
+    }, [guidanceIsLoading, flowDefinitions, on, tryActivateFlow]);
+    // H4: Stable ref for tryActivateFlow — prevents DELAYED timers from restarting on every state change
+    const tryActivateFlowRef = useRef(tryActivateFlow);
+    useEffect(() => { tryActivateFlowRef.current = tryActivateFlow; }, [tryActivateFlow]);
+    // DELAYED trigger: start timers after state loads
+    useEffect(() => {
+        if (guidanceIsLoading || flowDefinitions.length === 0)
+            return;
+        const delayedFlows = flowDefinitions.filter(f => f.trigger.type === OnboardingTriggerType.DELAYED && f.trigger.delayMs);
+        if (delayedFlows.length === 0)
+            return;
+        for (const flow of delayedFlows) {
+            if (delayTimersRef.current.has(flow.ref))
+                continue;
+            const timer = setTimeout(() => {
+                tryActivateFlowRef.current(flow.ref);
+                delayTimersRef.current.delete(flow.ref);
+            }, flow.trigger.delayMs);
+            delayTimersRef.current.set(flow.ref, timer);
+        }
+        return () => {
+            for (const timer of delayTimersRef.current.values()) {
+                clearTimeout(timer);
+            }
+            delayTimersRef.current.clear();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [guidanceIsLoading, flowDefinitions]);
+    // ─── Active Flows (with coexistence enforcement) ────────────
+    const activeFlows = useMemo(() => {
+        const eligible = flowDefinitions.filter(f => activeFlowRefs.has(f.ref));
+        return enforceCoexistence(eligible);
+    }, [flowDefinitions, activeFlowRefs]);
+    // ─── Public API ─────────────────────────────────────────────
+    // H3-9: Guard activateFlow against pre-init — no-op while loading
+    const activateFlow = useCallback((ref) => {
+        if (guidanceIsLoading)
+            return;
+        tryActivateFlow(ref);
+    }, [tryActivateFlow, guidanceIsLoading]);
+    const completeElement = useCallback((flowRef, elementRef, data) => {
+        // H3-6: Guard — unknown flow no-op
+        if (!flowRegistry.has(flowRef))
+            return;
+        // L18: Validate survey answers against schema before persisting
+        let validatedSurveyAnswers;
+        if (data?.surveyAnswers) {
+            const sanitized = {};
+            for (const [key, value] of Object.entries(data.surveyAnswers)) {
+                if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                    sanitized[key] = value;
+                }
+                else if (Array.isArray(value) && value.every(v => typeof v === 'string')) {
+                    sanitized[key] = value;
+                }
+            }
+            validatedSurveyAnswers = sanitized;
+        }
+        updateFlowState(flowRef, (prev) => ({
+            ...prev,
+            status: prev.status === OnboardingStatus.NOT_STARTED ? OnboardingStatus.IN_PROGRESS : prev.status,
+            elements: {
+                ...prev.elements,
+                [elementRef]: {
+                    status: OnboardingStatus.COMPLETED,
+                    completedAt: new Date(),
+                    surveyAnswers: validatedSurveyAnswers,
+                    lastStepIndex: data?.lastStepIndex,
+                },
+            },
+        }));
+        const flow = flowRegistry.get(flowRef);
+        if (flow) {
+            const element = flow.elements.find(e => e.ref === elementRef);
+            if (element) {
+                emit(FrontendEvents.GUIDANCE_ELEMENT_COMPLETED, {
+                    flowRef,
+                    elementRef,
+                    elementType: element.type,
+                });
+            }
+        }
+        logDebug(`Element completed: ${flowRef}/${elementRef}`);
+    }, [updateFlowState, flowRegistry, emit, logDebug]);
+    const completeFlow = useCallback((flowRef) => {
+        // H3-6: Guard — unknown flow no-op
+        if (!flowRegistry.has(flowRef))
+            return;
+        // H3-7: State transition validation — only complete from IN_PROGRESS
+        const currentState = flowStates[flowRef];
+        if (currentState?.status === OnboardingStatus.COMPLETED)
+            return;
+        if (currentState?.status !== OnboardingStatus.IN_PROGRESS)
+            return;
+        updateFlowState(flowRef, (prev) => ({
+            ...prev,
+            status: OnboardingStatus.COMPLETED,
+            completedAt: new Date(),
+        }));
+        setActiveFlowRefs(prev => {
+            const next = new Set(prev);
+            next.delete(flowRef);
+            return next;
+        });
+        const flow = flowRegistry.get(flowRef);
+        const scope = flowScopeMap[flowRef] ?? GuidanceFlowScope.USER;
+        if (flow) {
+            emit(FrontendEvents.GUIDANCE_FLOW_COMPLETED, {
+                flowRef,
+                renderMode: flow.renderMode,
+                triggerSource: 'frontend',
+                scope,
+            });
+        }
+        logDebug(`Flow completed: ${flowRef}`);
+    }, [updateFlowState, flowRegistry, flowStates, flowScopeMap, emit, logDebug]);
+    const dismissFlow = useCallback((flowRef) => {
+        // H3-6: Guard — unknown flow no-op
+        if (!flowRegistry.has(flowRef))
+            return;
+        // H3-7: State transition validation — only dismiss from IN_PROGRESS
+        const currentState = flowStates[flowRef];
+        if (currentState?.status !== OnboardingStatus.IN_PROGRESS)
+            return;
+        updateFlowState(flowRef, (prev) => ({
+            ...prev,
+            status: OnboardingStatus.DISMISSED,
+            dismissedAt: new Date(),
+        }));
+        setActiveFlowRefs(prev => {
+            const next = new Set(prev);
+            next.delete(flowRef);
+            return next;
+        });
+        const flow = flowRegistry.get(flowRef);
+        const scope = flowScopeMap[flowRef] ?? GuidanceFlowScope.USER;
+        if (flow) {
+            emit(FrontendEvents.GUIDANCE_FLOW_DISMISSED, {
+                flowRef,
+                renderMode: flow.renderMode,
+                triggerSource: 'frontend',
+                scope,
+            });
+        }
+        logDebug(`Flow dismissed: ${flowRef}`);
+    }, [updateFlowState, flowRegistry, flowStates, flowScopeMap, emit, logDebug]);
+    const skipFlow = useCallback((flowRef) => {
+        // H3-6: Guard — unknown flow no-op
+        if (!flowRegistry.has(flowRef))
+            return;
+        // H3-7: State transition validation — only skip from IN_PROGRESS or NOT_STARTED
+        const currentState = flowStates[flowRef];
+        if (currentState?.status !== OnboardingStatus.IN_PROGRESS && currentState?.status !== OnboardingStatus.NOT_STARTED && currentState !== undefined)
+            return;
+        updateFlowState(flowRef, (prev) => ({
+            ...prev,
+            status: OnboardingStatus.SKIPPED,
+        }));
+        setActiveFlowRefs(prev => {
+            const next = new Set(prev);
+            next.delete(flowRef);
+            return next;
+        });
+        logDebug(`Flow skipped: ${flowRef}`);
+    }, [updateFlowState, flowRegistry, flowStates, logDebug]);
+    const isFlowActive = useCallback((ref) => {
+        return activeFlowRefs.has(ref);
+    }, [activeFlowRefs]);
+    const isFlowCompleted = useCallback((ref) => {
+        return flowStates[ref]?.status === OnboardingStatus.COMPLETED;
+    }, [flowStates]);
+    // ─── WS / EventBus Subscriptions ───────────────────────────
+    // Listen for backend-pushed guidance events
+    useEffect(() => {
+        const unsubActivated = on(FrontendEvents.GUIDANCE_FLOW_ACTIVATED, (payload) => {
+            if (payload.triggerSource === 'backend') {
+                logDebug(`Backend activated flow: ${payload.flowRef}`);
+                setActiveFlowRefs(prev => {
+                    const next = new Set(prev);
+                    next.add(payload.flowRef);
+                    return next;
+                });
+                updateFlowState(payload.flowRef, (prev) => ({
+                    ...prev,
+                    status: OnboardingStatus.IN_PROGRESS,
+                    startedAt: prev.startedAt ?? new Date(),
+                    triggerCount: (prev.triggerCount ?? 0) + 1,
+                }));
+            }
+        });
+        const unsubCompleted = on(FrontendEvents.GUIDANCE_FLOW_COMPLETED, (payload) => {
+            if (payload.triggerSource === 'backend') {
+                logDebug(`Backend completed flow: ${payload.flowRef}`);
+                setActiveFlowRefs(prev => {
+                    const next = new Set(prev);
+                    next.delete(payload.flowRef);
+                    return next;
+                });
+                updateFlowState(payload.flowRef, (prev) => ({
+                    ...prev,
+                    status: OnboardingStatus.COMPLETED,
+                    completedAt: new Date(),
+                }));
+            }
+        });
+        const unsubDismissed = on(FrontendEvents.GUIDANCE_FLOW_DISMISSED, (payload) => {
+            if (payload.triggerSource === 'backend') {
+                logDebug(`Backend dismissed flow: ${payload.flowRef}`);
+                setActiveFlowRefs(prev => {
+                    const next = new Set(prev);
+                    next.delete(payload.flowRef);
+                    return next;
+                });
+                updateFlowState(payload.flowRef, (prev) => ({
+                    ...prev,
+                    status: OnboardingStatus.DISMISSED,
+                    dismissedAt: new Date(),
+                }));
+            }
+        });
+        return () => {
+            unsubActivated();
+            unsubCompleted();
+            unsubDismissed();
+        };
+    }, [on, logDebug, updateFlowState]);
+    // ─── Progression WS Subscription (Phase 4) ────────────────
+    useEffect(() => {
+        const unsubMilestone = on(FrontendEvents.MILESTONE_ACHIEVED, (payload) => {
+            logDebug(`Milestone achieved: ${payload.milestoneRef} (scope: ${payload.scope})`);
+            const scope = payload.scope;
+            setProgressionScopedStates(prev => {
+                const current = prev[scope] ?? { milestonesAchieved: {}, operationCounts: {}, totalPoints: 0, categoriesProgress: {} };
+                return {
+                    ...prev,
+                    [scope]: {
+                        ...current,
+                        milestonesAchieved: {
+                            ...current.milestonesAchieved,
+                            [payload.milestoneRef]: {
+                                achievedAt: new Date(),
+                                count: 1,
+                            },
+                        },
+                        totalPoints: payload.totalPoints,
+                        categoriesProgress: {
+                            ...current.categoriesProgress,
+                            [payload.category]: {
+                                completedCount: (current.categoriesProgress[payload.category]?.completedCount ?? 0) + 1,
+                                totalPoints: (current.categoriesProgress[payload.category]?.totalPoints ?? 0) + (payload.points ?? 0),
+                            },
+                        },
+                    },
+                };
+            });
+            // M11: Re-fetch features + notify user when a feature is unlocked
+            if (payload.reward?.type === MilestoneRewardType.FEATURE_UNLOCK) {
+                featuresCtx?.refetch();
+                emit(FrontendEvents.NOTIFY_CUSTOM_SUCCESS, {
+                    identifier: `milestone.feature_unlock.${payload.milestoneRef}`,
+                    data: {
+                        milestoneRef: payload.milestoneRef,
+                        featureRef: payload.reward.featureRef,
+                    },
+                });
+            }
+            // C3: Trigger celebration overlay for celebration-type rewards
+            if (payload.reward?.type === MilestoneRewardType.CELEBRATION && payload.reward?.celebrationLevel) {
+                const levelToMode = {
+                    low: CelebrationDisplayMode.CONFETTI,
+                    medium: CelebrationDisplayMode.OVERLAY,
+                    high: CelebrationDisplayMode.LOTTIE,
+                };
+                const mode = levelToMode[payload.reward.celebrationLevel] ?? CelebrationDisplayMode.CONFETTI;
+                emit(FrontendEvents.NOTIFY_CUSTOM_SUCCESS, {
+                    identifier: `milestone.${payload.milestoneRef}`,
+                    data: {
+                        frontendDisplayHints: { celebration: { mode } },
+                        milestoneRef: payload.milestoneRef,
+                        category: payload.category,
+                        points: payload.points,
+                    },
+                });
+            }
+        });
+        return () => {
+            unsubMilestone();
+        };
+    }, [on, logDebug, emit, featuresCtx]);
+    // ─── Lifecycle WS Subscription (Phase 5) ────────────────────
+    useEffect(() => {
+        if (!lifecycleEnabled)
+            return;
+        const unsubLifecycle = on(FrontendEvents.LIFECYCLE_STAGE_CHANGED, (payload) => {
+            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 changedAtDate = new Date(payload.changedAt);
+                const updatedHistory = [...current.stageHistory];
+                if (updatedHistory.length > 0 && !updatedHistory[0].exitedAt) {
+                    updatedHistory[0] = { ...updatedHistory[0], exitedAt: changedAtDate };
+                }
+                updatedHistory.unshift({
+                    stage: payload.newStage,
+                    enteredAt: changedAtDate,
+                    trigger: payload.trigger,
+                });
+                return {
+                    ...prev,
+                    [scope]: {
+                        ...current,
+                        currentStage: payload.newStage,
+                        stageEnteredAt: changedAtDate,
+                        stageHistory: updatedHistory,
+                        ...(payload.activationCriteriaMet ? { activationCriteriaMet: payload.activationCriteriaMet } : {}),
+                    },
+                };
+            });
+        });
+        return () => {
+            unsubLifecycle();
+        };
+    }, [on, logDebug, lifecycleEnabled]);
+    // ─── Progression Context Slice (Phase 4) ───────────────────
+    const progressionSlice = useMemo(() => {
+        const isMilestoneAchieved = (milestoneRef) => {
+            for (const scope of Object.values(ProgressionScope)) {
+                const state = progressionScopedStates[scope];
+                if (state?.milestonesAchieved[milestoneRef])
+                    return true;
+            }
+            return false;
+        };
+        const getMilestoneAchievement = (milestoneRef) => {
+            for (const scope of Object.values(ProgressionScope)) {
+                const state = progressionScopedStates[scope];
+                const achievement = state?.milestonesAchieved[milestoneRef];
+                if (achievement)
+                    return achievement;
+            }
+            return undefined;
+        };
+        const getCategoryProgress = (category) => {
+            let merged;
+            for (const scope of Object.values(ProgressionScope)) {
+                const state = progressionScopedStates[scope];
+                const catProgress = state?.categoriesProgress[category];
+                if (catProgress) {
+                    if (!merged) {
+                        merged = { completedCount: 0, totalPoints: 0 };
+                    }
+                    merged.completedCount += catProgress.completedCount;
+                    merged.totalPoints += catProgress.totalPoints;
+                }
+            }
+            return merged;
+        };
+        let totalPoints = 0;
+        for (const scope of Object.values(ProgressionScope)) {
+            const state = progressionScopedStates[scope];
+            if (state) {
+                totalPoints += state.totalPoints;
+            }
+        }
+        return {
+            scopedStates: progressionScopedStates,
+            isMilestoneAchieved,
+            getMilestoneAchievement,
+            getCategoryProgress,
+            totalPoints,
+            milestoneDefinitions,
+            isLoading: progressionIsLoading,
+        };
+    }, [progressionScopedStates, progressionIsLoading, milestoneDefinitions]);
+    // ─── Lifecycle Context Slice (Phase 5) ─────────────────────
+    const lifecycleSlice = useMemo(() => {
+        if (!lifecycleEnabled)
+            return LIFECYCLE_DEFAULTS;
+        // Use USER scope as the primary lifecycle state (most common)
+        const primaryState = lifecycleScopedStates[LifecycleScope.USER];
+        const currentStage = primaryState?.currentStage ?? null;
+        const stageEnteredAt = primaryState?.stageEnteredAt ? new Date(primaryState.stageEnteredAt) : null;
+        const hasReachedStage = (stage) => {
+            if (!primaryState)
+                return false;
+            return hasReachedStageUtil(primaryState, stage);
+        };
+        // Build activation progress from criteria config + state
+        const criteriaMet = primaryState?.activationCriteriaMet ?? {};
+        const criteria = lifecycleActivationCriteria?.criteria ?? [];
+        const totalCriteria = criteria.length;
+        const metCriteria = Object.values(criteriaMet).filter(Boolean).length;
+        return {
+            currentStage,
+            stageEnteredAt,
+            isEnabled: true,
+            isLoading: lifecycleIsLoading,
+            hasReachedStage,
+            activationProgress: {
+                criteriaMet,
+                criteria,
+                totalCriteria,
+                metCriteria,
+                isFullyActivated: totalCriteria > 0 ? metCriteria >= totalCriteria : currentStage !== LifecycleStage.SIGNED_UP,
+            },
+        };
+    }, [lifecycleEnabled, lifecycleScopedStates, lifecycleIsLoading, lifecycleActivationCriteria]);
+    // ─── Context Value ──────────────────────────────────────────
+    // M8/L19: Context re-render isolation analysis
+    // The context value depends on 13 values — any change creates a new value and re-renders all consumers.
+    // Options considered:
+    // 1. Split into separate contexts (GuidanceContext, ProgressionContext, LifecycleContext) — most effective
+    // 2. useSyncExternalStore with granular subscriptions — less invasive
+    // 3. Accept current behavior + optimize consumers with React.memo
+    // Decision: Option 3 for v1. The provider-level useMemo on progressionSlice and lifecycleSlice
+    // ensures reference stability for the most commonly-used slices. Hook-level useMemo in
+    // useLifecycle() and useProgression() provides additional stability.
+    // Revisit if profiling shows re-render performance issues.
+    const contextValue = useMemo(() => ({
+        activeFlows,
+        flowStates,
+        activateFlow,
+        completeElement,
+        completeFlow,
+        dismissFlow,
+        skipFlow,
+        isFlowActive,
+        isFlowCompleted,
+        isLoading: guidanceIsLoading,
+        progression: progressionSlice,
+        lifecycle: lifecycleSlice,
+    }), [
+        activeFlows,
+        flowStates,
+        activateFlow,
+        completeElement,
+        completeFlow,
+        dismissFlow,
+        skipFlow,
+        isFlowActive,
+        isFlowCompleted,
+        guidanceIsLoading,
+        progressionSlice,
+        lifecycleSlice,
+    ]);
+    return (_jsx(GuidanceContext.Provider, { value: contextValue, children: children }));
+};
+//# sourceMappingURL=GuidanceContext.js.map