@wildo-ai/saas-frontend-lib 1.1.2 → 1.1.4

package/dist/esm/core/loading/loading-types.frontend.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"loading-types.frontend.schemas.js","sourceRoot":"","sources":["../../../../../src/core/loading/loading-types.frontend.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,MAAM,CAAN,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC9B,+CAA+C;IAC/C,+CAAuB,CAAA;IACvB,yDAAyD;IACzD,qEAA6C,CAAA;AAC/C,CAAC,EALW,oBAAoB,KAApB,oBAAoB,QAK/B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAN,IAAY,wBASX;AATD,WAAY,wBAAwB;IAClC,oDAAoD;IACpD,+DAAmC,CAAA;IACnC,kEAAkE;IAClE,6DAAiC,CAAA;IACjC,oEAAoE;IACpE,2DAA+B,CAAA;IAC/B,6DAA6D;IAC7D,uDAA2B,CAAA;AAC7B,CAAC,EATW,wBAAwB,KAAxB,wBAAwB,QASnC;AAED,4CAA4C;AAC5C,MAAM,CAAN,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,4EAA4E;IAC5E,0CAA2B,CAAA;IAC3B,4EAA4E;IAC5E,sCAAuB,CAAA;AACzB,CAAC,EALW,WAAW,KAAX,WAAW,QAKtB;AAED,iEAAiE;AACjE,MAAM,CAAN,IAAY,YAGX;AAHD,WAAY,YAAY;IACtB,mCAAmB,CAAA;IACnB,mCAAmB,CAAA;AACrB,CAAC,EAHW,YAAY,KAAZ,YAAY,QAGvB;AAED;;;;;GAKG;AACH,MAAM,CAAN,IAAY,gBAeX;AAfD,WAAY,gBAAgB;IAC1B,0EAA0E;IAC1E,yCAAqB,CAAA;IACrB,uEAAuE;IACvE,uCAAmB,CAAA;IACnB,wEAAwE;IACxE,uDAAmC,CAAA;IACnC,gDAAgD;IAChD,qCAAiB,CAAA;IACjB,wDAAwD;IACxD,2CAAuB,CAAA;IACvB,uEAAuE;IACvE,+CAA2B,CAAA;IAC3B,gEAAgE;IAChE,qCAAiB,CAAA;AACnB,CAAC,EAfW,gBAAgB,KAAhB,gBAAgB,QAe3B","sourcesContent":["/**\n * Loading System Type Definitions\n *\n * Foundation types for the 3-tier loading architecture.\n * See .cursor/plans/loading-system-architecture.md for full design.\n *\n * Tier 1 (APPLICATION): Gates the entire UI — init steps, language change, org switch.\n * Tier 2 (COMPONENT): Per-scope loading managed centrally — enables cross-component awareness.\n * Tier 3 (ACTION): Local to the component — button spinners, inline saves. Not tracked here.\n */\n\n/**\n * Well-known custom loading identifiers for Tier 1 (APPLICATION) events.\n *\n * Used as `customIdentifier` in LoadingScope and as `identifier` in\n * LOADING_CUSTOM_START/END event payloads.\n */\nexport enum AppLoadingIdentifier {\n  /** Initial translations load on app startup */\n  INIT_I18N = 'init:i18n',\n  /** Translations reload triggered by a language change */\n  I18N_LANGUAGE_CHANGE = 'i18n:language-change',\n}\n\n/**\n * Well-known custom loading identifiers for Tier 2 (COMPONENT) **context**\n * providers — i.e. high-level frontend-lib contexts (billing, flows-actors,\n * progression, lifecycle, …) that own their own fetch lifecycle but want to\n * publish that lifecycle through `LoadingContext` so unrelated components can\n * observe it via `useComponentLoading({ customIdentifier })`.\n *\n * **L-2.b decision (2026-04-21): emit via the LoadingContext event bus**\n * rather than expose ad-hoc `useXxxLoadingScope()` hooks. Rationale:\n * - `LoadingContext` is already the single source of truth for both\n *   `LoadingGate` and `useComponentLoading`; parallel hooks would fragment\n *   the model and force every cross-cutting consumer to learn N adapters.\n * - The infrastructure already exists (LOADING_CUSTOM_*` events with\n *   `tier: COMPONENT`); no schema change needed.\n * - Contexts keep exposing their own `isLoading` for direct consumers\n *   (back-compat), but ALSO call `fireLoading`/`endLoading` so that\n *   downstream sites can wrap content in a `LoadingGate`/`useComponentLoading`\n *   without coupling to the context.\n *\n * Naming convention: `app:<domain>` (lowercase, kebab-case for multi-word).\n * Add a new entry here when promoting a context to publish its loading state.\n */\nexport enum ContextLoadingIdentifier {\n  /** BillingContext: billing-state fetch lifecycle */\n  BILLING_STATE = 'app:billing:state',\n  /** FlowsActorsContext: flows + actors registry fetch lifecycle */\n  FLOWS_ACTORS = 'app:flows-actors',\n  /** GuidanceContext: progression / guidance graph fetch lifecycle */\n  PROGRESSION = 'app:progression',\n  /** ExecutionRuntimeContext: lifecycle/runtime state fetch */\n  LIFECYCLE = 'app:lifecycle',\n}\n\n/** Which tier a loading event belongs to */\nexport enum LoadingTier {\n  /** App-level: gates the entire application (init steps, language change) */\n  APPLICATION = 'application',\n  /** Component-level: managed centrally, enables cross-component awareness */\n  COMPONENT = 'component',\n}\n\n/** Whether this is a first load or a refresh of existing data */\nexport enum LoadingPhase {\n  INITIAL = 'initial',\n  REFRESH = 'refresh',\n}\n\n/**\n * Visual treatment for loading states.\n *\n * Used by LoadingPolicy to determine what the user sees while content loads.\n * SKELETON and OPACITY_OVERLAY preserve layout stability; SPINNER and FULL_SCREEN do not.\n */\nexport enum LoadingTreatment {\n  /** Placeholder shapes matching content layout — best for initial loads */\n  SKELETON = 'SKELETON',\n  /** Centered spinner — use when layout is unknown or for short waits */\n  SPINNER = 'SPINNER',\n  /** Semi-transparent overlay on existing content — best for refreshes */\n  OPACITY_OVERLAY = 'OPACITY_OVERLAY',\n  /** display: none — component hidden entirely */\n  HIDDEN = 'HIDDEN',\n  /** visibility: hidden — space reserved but invisible */\n  INVISIBLE = 'INVISIBLE',\n  /** Full-screen overlay blocking all interaction — app-level loading */\n  FULL_SCREEN = 'FULL_SCREEN',\n  /** Custom renderer provided via LoadingPolicy.customRenderer */\n  CUSTOM = 'CUSTOM',\n}\n\n/**\n * Identifies what is loading — resource operation or custom identifier.\n *\n * At least one of `resourceType`+`operation` or `customIdentifier` must be provided.\n * The scope is serialized to a string key via `buildLoadingScopeKey()` for Map lookups.\n */\nexport interface LoadingScope {\n  resourceType?: string;\n  operation?: string;\n  /** Distinguishes multiple instances of the same resource+operation (e.g., inline editors) */\n  discriminator?: string;\n  /** For non-resource loading (e.g., 'init:auth', 'init:i18n') */\n  customIdentifier?: string;\n}\n\n/**\n * Policy that determines how loading is rendered.\n *\n * Resolved by resolveLoadingPolicy — 2-layer for day 1:\n * 1. Category defaults (resource lists → SKELETON, actions → SPINNER, etc.)\n * 2. Explicit override via LoadingGate props\n */\nexport interface LoadingPolicy {\n  initialLoad: LoadingTreatment;\n  refresh?: LoadingTreatment;\n  customRenderer?: (context: LoadingRenderContext) => import('react').ReactNode;\n  disableInteraction?: boolean;\n  skeletonSchema?: unknown;\n}\n\n/** Context passed to custom loading renderers */\nexport interface LoadingRenderContext {\n  phase: LoadingPhase;\n  scope: LoadingScope;\n}\n\n/** Context passed to error renderers on LoadingGate */\nexport interface LoadingErrorContext {\n  failedScopes: LoadingScope[];\n  reason: 'timeout' | 'error';\n  retry: () => void;\n  error?: unknown;\n}\n\n/**\n * Internal state for a single loading scope in the LoadingContext aggregator.\n *\n * activeCount tracks concurrent requests for the same scope (e.g., rapid LIST refreshes).\n * isLoading is true when activeCount > 0.\n */\nexport interface ComponentLoadingState {\n  hasLoadedOnce: boolean;\n  isLoading: boolean;\n  phase: LoadingPhase;\n  activeCount: number;\n}\n\n/** Active app-level loading source — exposed for debugging and UI display */\nexport interface LoadingSource {\n  identifier: string;\n  tier: LoadingTier;\n  startedAt: number;\n}\n"]}
+{"version":3,"file":"loading-types.frontend.schemas.js","sourceRoot":"","sources":["../../../../src/core/loading/loading-types.frontend.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,MAAM,CAAN,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC9B,+CAA+C;IAC/C,+CAAuB,CAAA;IACvB,yDAAyD;IACzD,qEAA6C,CAAA;AAC/C,CAAC,EALW,oBAAoB,KAApB,oBAAoB,QAK/B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAN,IAAY,wBASX;AATD,WAAY,wBAAwB;IAClC,oDAAoD;IACpD,+DAAmC,CAAA;IACnC,kEAAkE;IAClE,6DAAiC,CAAA;IACjC,oEAAoE;IACpE,2DAA+B,CAAA;IAC/B,6DAA6D;IAC7D,uDAA2B,CAAA;AAC7B,CAAC,EATW,wBAAwB,KAAxB,wBAAwB,QASnC;AAED,4CAA4C;AAC5C,MAAM,CAAN,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,4EAA4E;IAC5E,0CAA2B,CAAA;IAC3B,4EAA4E;IAC5E,sCAAuB,CAAA;AACzB,CAAC,EALW,WAAW,KAAX,WAAW,QAKtB;AAED,iEAAiE;AACjE,MAAM,CAAN,IAAY,YAGX;AAHD,WAAY,YAAY;IACtB,mCAAmB,CAAA;IACnB,mCAAmB,CAAA;AACrB,CAAC,EAHW,YAAY,KAAZ,YAAY,QAGvB;AAED;;;;;GAKG;AACH,MAAM,CAAN,IAAY,gBAeX;AAfD,WAAY,gBAAgB;IAC1B,0EAA0E;IAC1E,yCAAqB,CAAA;IACrB,uEAAuE;IACvE,uCAAmB,CAAA;IACnB,wEAAwE;IACxE,uDAAmC,CAAA;IACnC,gDAAgD;IAChD,qCAAiB,CAAA;IACjB,wDAAwD;IACxD,2CAAuB,CAAA;IACvB,uEAAuE;IACvE,+CAA2B,CAAA;IAC3B,gEAAgE;IAChE,qCAAiB,CAAA;AACnB,CAAC,EAfW,gBAAgB,KAAhB,gBAAgB,QAe3B","sourcesContent":["/**\n * Loading System Type Definitions\n *\n * Foundation types for the 3-tier loading architecture.\n * See .cursor/plans/loading-system-architecture.md for full design.\n *\n * Tier 1 (APPLICATION): Gates the entire UI — init steps, language change, org switch.\n * Tier 2 (COMPONENT): Per-scope loading managed centrally — enables cross-component awareness.\n * Tier 3 (ACTION): Local to the component — button spinners, inline saves. Not tracked here.\n */\n\n/**\n * Well-known custom loading identifiers for Tier 1 (APPLICATION) events.\n *\n * Used as `customIdentifier` in LoadingScope and as `identifier` in\n * LOADING_CUSTOM_START/END event payloads.\n */\nexport enum AppLoadingIdentifier {\n  /** Initial translations load on app startup */\n  INIT_I18N = 'init:i18n',\n  /** Translations reload triggered by a language change */\n  I18N_LANGUAGE_CHANGE = 'i18n:language-change',\n}\n\n/**\n * Well-known custom loading identifiers for Tier 2 (COMPONENT) **context**\n * providers — i.e. high-level frontend-lib contexts (billing, flows-actors,\n * progression, lifecycle, …) that own their own fetch lifecycle but want to\n * publish that lifecycle through `LoadingContext` so unrelated components can\n * observe it via `useComponentLoading({ customIdentifier })`.\n *\n * **L-2.b decision (2026-04-21): emit via the LoadingContext event bus**\n * rather than expose ad-hoc `useXxxLoadingScope()` hooks. Rationale:\n * - `LoadingContext` is already the single source of truth for both\n *   `LoadingGate` and `useComponentLoading`; parallel hooks would fragment\n *   the model and force every cross-cutting consumer to learn N adapters.\n * - The infrastructure already exists (LOADING_CUSTOM_*` events with\n *   `tier: COMPONENT`); no schema change needed.\n * - Contexts keep exposing their own `isLoading` for direct consumers\n *   (back-compat), but ALSO call `fireLoading`/`endLoading` so that\n *   downstream sites can wrap content in a `LoadingGate`/`useComponentLoading`\n *   without coupling to the context.\n *\n * Naming convention: `app:<domain>` (lowercase, kebab-case for multi-word).\n * Add a new entry here when promoting a context to publish its loading state.\n */\nexport enum ContextLoadingIdentifier {\n  /** BillingContext: billing-state fetch lifecycle */\n  BILLING_STATE = 'app:billing:state',\n  /** FlowsActorsContext: flows + actors registry fetch lifecycle */\n  FLOWS_ACTORS = 'app:flows-actors',\n  /** GuidanceContext: progression / guidance graph fetch lifecycle */\n  PROGRESSION = 'app:progression',\n  /** ExecutionRuntimeContext: lifecycle/runtime state fetch */\n  LIFECYCLE = 'app:lifecycle',\n}\n\n/** Which tier a loading event belongs to */\nexport enum LoadingTier {\n  /** App-level: gates the entire application (init steps, language change) */\n  APPLICATION = 'application',\n  /** Component-level: managed centrally, enables cross-component awareness */\n  COMPONENT = 'component',\n}\n\n/** Whether this is a first load or a refresh of existing data */\nexport enum LoadingPhase {\n  INITIAL = 'initial',\n  REFRESH = 'refresh',\n}\n\n/**\n * Visual treatment for loading states.\n *\n * Used by LoadingPolicy to determine what the user sees while content loads.\n * SKELETON and OPACITY_OVERLAY preserve layout stability; SPINNER and FULL_SCREEN do not.\n */\nexport enum LoadingTreatment {\n  /** Placeholder shapes matching content layout — best for initial loads */\n  SKELETON = 'SKELETON',\n  /** Centered spinner — use when layout is unknown or for short waits */\n  SPINNER = 'SPINNER',\n  /** Semi-transparent overlay on existing content — best for refreshes */\n  OPACITY_OVERLAY = 'OPACITY_OVERLAY',\n  /** display: none — component hidden entirely */\n  HIDDEN = 'HIDDEN',\n  /** visibility: hidden — space reserved but invisible */\n  INVISIBLE = 'INVISIBLE',\n  /** Full-screen overlay blocking all interaction — app-level loading */\n  FULL_SCREEN = 'FULL_SCREEN',\n  /** Custom renderer provided via LoadingPolicy.customRenderer */\n  CUSTOM = 'CUSTOM',\n}\n\n/**\n * Identifies what is loading — resource operation or custom identifier.\n *\n * At least one of `resourceType`+`operation` or `customIdentifier` must be provided.\n * The scope is serialized to a string key via `buildLoadingScopeKey()` for Map lookups.\n */\nexport interface LoadingScope {\n  resourceType?: string;\n  operation?: string;\n  /** Distinguishes multiple instances of the same resource+operation (e.g., inline editors) */\n  discriminator?: string;\n  /** For non-resource loading (e.g., 'init:auth', 'init:i18n') */\n  customIdentifier?: string;\n}\n\n/**\n * Policy that determines how loading is rendered.\n *\n * Resolved by resolveLoadingPolicy — 2-layer for day 1:\n * 1. Category defaults (resource lists → SKELETON, actions → SPINNER, etc.)\n * 2. Explicit override via LoadingGate props\n */\nexport interface LoadingPolicy {\n  initialLoad: LoadingTreatment;\n  refresh?: LoadingTreatment;\n  customRenderer?: (context: LoadingRenderContext) => import('react').ReactNode;\n  disableInteraction?: boolean;\n  skeletonSchema?: unknown;\n}\n\n/** Context passed to custom loading renderers */\nexport interface LoadingRenderContext {\n  phase: LoadingPhase;\n  scope: LoadingScope;\n}\n\n/** Context passed to error renderers on LoadingGate */\nexport interface LoadingErrorContext {\n  failedScopes: LoadingScope[];\n  reason: 'timeout' | 'error';\n  retry: () => void;\n  error?: unknown;\n}\n\n/**\n * Internal state for a single loading scope in the LoadingContext aggregator.\n *\n * activeCount tracks concurrent requests for the same scope (e.g., rapid LIST refreshes).\n * isLoading is true when activeCount > 0.\n */\nexport interface ComponentLoadingState {\n  hasLoadedOnce: boolean;\n  isLoading: boolean;\n  phase: LoadingPhase;\n  activeCount: number;\n}\n\n/** Active app-level loading source — exposed for debugging and UI display */\nexport interface LoadingSource {\n  identifier: string;\n  tier: LoadingTier;\n  startedAt: number;\n}\n"]}

package/dist/esm/core/loading/resolveLoadingPolicy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveLoadingPolicy.d.ts","sourceRoot":"","sources":["../../../../../src/core/loading/resolveLoadingPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAItE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,iBAAiB,EAAE,yBAAyB,EAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAChC,aAAa,CASf"}
+{"version":3,"file":"resolveLoadingPolicy.d.ts","sourceRoot":"","sources":["../../../../src/core/loading/resolveLoadingPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAItE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,iBAAiB,EAAE,yBAAyB,EAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAChC,aAAa,CASf"}

package/dist/esm/core/loading/resolveLoadingPolicy.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolveLoadingPolicy.js","sourceRoot":"","sources":["../../../../../src/core/loading/resolveLoadingPolicy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAClC,iBAA4C,EAC5C,QAAiC;IAEjC,MAAM,eAAe,GAAG,yBAAyB,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC;IAC3E,OAAO;QACL,WAAW,EAAE,QAAQ,EAAE,WAAW,IAAI,eAAe,CAAC,WAAW,IAAI,gBAAgB,CAAC,QAAQ;QAC9F,OAAO,EAAE,QAAQ,EAAE,OAAO,IAAI,eAAe,CAAC,OAAO,IAAI,gBAAgB,CAAC,eAAe;QACzF,cAAc,EAAE,QAAQ,EAAE,cAAc,IAAI,eAAe,CAAC,cAAc;QAC1E,kBAAkB,EAAE,QAAQ,EAAE,kBAAkB,IAAI,eAAe,CAAC,kBAAkB;QACtF,cAAc,EAAE,QAAQ,EAAE,cAAc,IAAI,eAAe,CAAC,cAAc;KAC3E,CAAC;AACJ,CAAC","sourcesContent":["import type { FrontendComponentCategory } from '@wildo-ai/presets-components-models';\nimport type { LoadingPolicy } from './loading-types.frontend.schemas';\nimport { LoadingTreatment } from './loading-types.frontend.schemas';\nimport { CATEGORY_LOADING_DEFAULTS } from './loading-policy.frontend.schemas';\n\n/**\n * Resolves a `LoadingPolicy` via 2-layer resolution:\n *   1. Category defaults (from `CATEGORY_LOADING_DEFAULTS`)\n *   2. Explicit override (preset code or instance props)\n *\n * Categories without defaults (LOW_LEVEL, APP_LAYOUTS, GUIDANCE, PROGRESSION,\n * LIFECYCLE) fall through to framework defaults (SKELETON + OPACITY_OVERLAY).\n * Presets in those categories should always provide explicit overrides.\n *\n * @param componentCategory - The category to look up defaults for\n * @param override - Explicit overrides from the preset or instance\n */\nexport function resolveLoadingPolicy(\n  componentCategory: FrontendComponentCategory,\n  override?: Partial<LoadingPolicy>\n): LoadingPolicy {\n  const categoryDefault = CATEGORY_LOADING_DEFAULTS[componentCategory] ?? {};\n  return {\n    initialLoad: override?.initialLoad ?? categoryDefault.initialLoad ?? LoadingTreatment.SKELETON,\n    refresh: override?.refresh ?? categoryDefault.refresh ?? LoadingTreatment.OPACITY_OVERLAY,\n    customRenderer: override?.customRenderer ?? categoryDefault.customRenderer,\n    disableInteraction: override?.disableInteraction ?? categoryDefault.disableInteraction,\n    skeletonSchema: override?.skeletonSchema ?? categoryDefault.skeletonSchema,\n  };\n}\n"]}
+{"version":3,"file":"resolveLoadingPolicy.js","sourceRoot":"","sources":["../../../../src/core/loading/resolveLoadingPolicy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAClC,iBAA4C,EAC5C,QAAiC;IAEjC,MAAM,eAAe,GAAG,yBAAyB,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC;IAC3E,OAAO;QACL,WAAW,EAAE,QAAQ,EAAE,WAAW,IAAI,eAAe,CAAC,WAAW,IAAI,gBAAgB,CAAC,QAAQ;QAC9F,OAAO,EAAE,QAAQ,EAAE,OAAO,IAAI,eAAe,CAAC,OAAO,IAAI,gBAAgB,CAAC,eAAe;QACzF,cAAc,EAAE,QAAQ,EAAE,cAAc,IAAI,eAAe,CAAC,cAAc;QAC1E,kBAAkB,EAAE,QAAQ,EAAE,kBAAkB,IAAI,eAAe,CAAC,kBAAkB;QACtF,cAAc,EAAE,QAAQ,EAAE,cAAc,IAAI,eAAe,CAAC,cAAc;KAC3E,CAAC;AACJ,CAAC","sourcesContent":["import type { FrontendComponentCategory } from '@wildo-ai/presets-components-models';\nimport type { LoadingPolicy } from './loading-types.frontend.schemas';\nimport { LoadingTreatment } from './loading-types.frontend.schemas';\nimport { CATEGORY_LOADING_DEFAULTS } from './loading-policy.frontend.schemas';\n\n/**\n * Resolves a `LoadingPolicy` via 2-layer resolution:\n *   1. Category defaults (from `CATEGORY_LOADING_DEFAULTS`)\n *   2. Explicit override (preset code or instance props)\n *\n * Categories without defaults (LOW_LEVEL, APP_LAYOUTS, GUIDANCE, PROGRESSION,\n * LIFECYCLE) fall through to framework defaults (SKELETON + OPACITY_OVERLAY).\n * Presets in those categories should always provide explicit overrides.\n *\n * @param componentCategory - The category to look up defaults for\n * @param override - Explicit overrides from the preset or instance\n */\nexport function resolveLoadingPolicy(\n  componentCategory: FrontendComponentCategory,\n  override?: Partial<LoadingPolicy>\n): LoadingPolicy {\n  const categoryDefault = CATEGORY_LOADING_DEFAULTS[componentCategory] ?? {};\n  return {\n    initialLoad: override?.initialLoad ?? categoryDefault.initialLoad ?? LoadingTreatment.SKELETON,\n    refresh: override?.refresh ?? categoryDefault.refresh ?? LoadingTreatment.OPACITY_OVERLAY,\n    customRenderer: override?.customRenderer ?? categoryDefault.customRenderer,\n    disableInteraction: override?.disableInteraction ?? categoryDefault.disableInteraction,\n    skeletonSchema: override?.skeletonSchema ?? categoryDefault.skeletonSchema,\n  };\n}\n"]}

package/dist/esm/core/loading/useAppLoading.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAppLoading.d.ts","sourceRoot":"","sources":["../../../../../src/core/loading/useAppLoading.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEtE;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI;IAAE,YAAY,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,aAAa,EAAE,CAAA;CAAE,CAInF"}
+{"version":3,"file":"useAppLoading.d.ts","sourceRoot":"","sources":["../../../../src/core/loading/useAppLoading.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEtE;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI;IAAE,YAAY,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,aAAa,EAAE,CAAA;CAAE,CAInF"}

package/dist/esm/core/loading/useAppLoading.js.map

@@ -1 +1 @@
-{"version":3,"file":"useAppLoading.js","sourceRoot":"","sources":["../../../../../src/core/loading/useAppLoading.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACrF,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,iBAAiB,EAAE,CAAC;AACpF,CAAC","sourcesContent":["/**\n * useAppLoading Hook — Tier 1: Application-Level Loading State\n *\n * Separated from LoadingContext.tsx for React Fast Refresh compatibility.\n */\n\nimport { useContext } from 'react';\nimport { LoadingContext } from './LoadingContext';\nimport type { LoadingSource } from './loading-types.frontend.schemas';\n\n/**\n * Tier 1: Application-level loading state.\n * Returns true when any app-level loading is active (init steps, language change).\n *\n * Use this to gate the entire application UI — show a full-screen loading\n * overlay when the app is initializing or switching languages/orgs.\n *\n * @throws Error if used outside of LoadingProvider\n */\nexport function useAppLoading(): { isAppLoading: boolean; sources: LoadingSource[] } {\n  const context = useContext(LoadingContext);\n  if (!context) throw new Error('useAppLoading must be used within a LoadingProvider');\n  return { isAppLoading: context.isAppLoading, sources: context.appLoadingSources };\n}\n"]}
+{"version":3,"file":"useAppLoading.js","sourceRoot":"","sources":["../../../../src/core/loading/useAppLoading.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACrF,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,iBAAiB,EAAE,CAAC;AACpF,CAAC","sourcesContent":["/**\n * useAppLoading Hook — Tier 1: Application-Level Loading State\n *\n * Separated from LoadingContext.tsx for React Fast Refresh compatibility.\n */\n\nimport { useContext } from 'react';\nimport { LoadingContext } from './LoadingContext';\nimport type { LoadingSource } from './loading-types.frontend.schemas';\n\n/**\n * Tier 1: Application-level loading state.\n * Returns true when any app-level loading is active (init steps, language change).\n *\n * Use this to gate the entire application UI — show a full-screen loading\n * overlay when the app is initializing or switching languages/orgs.\n *\n * @throws Error if used outside of LoadingProvider\n */\nexport function useAppLoading(): { isAppLoading: boolean; sources: LoadingSource[] } {\n  const context = useContext(LoadingContext);\n  if (!context) throw new Error('useAppLoading must be used within a LoadingProvider');\n  return { isAppLoading: context.isAppLoading, sources: context.appLoadingSources };\n}\n"]}

package/dist/esm/core/loading/useComponentLoading.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useComponentLoading.d.ts","sourceRoot":"","sources":["../../../../../src/core/loading/useComponentLoading.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAGrE;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE;IAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC;IACD,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B,CAqBA"}
+{"version":3,"file":"useComponentLoading.d.ts","sourceRoot":"","sources":["../../../../src/core/loading/useComponentLoading.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAGrE;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE;IAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC;IACD,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B,CAqBA"}

package/dist/esm/core/loading/useComponentLoading.js.map

@@ -1 +1 @@
-{"version":3,"file":"useComponentLoading.js","sourceRoot":"","sources":["../../../../../src/core/loading/useComponentLoading.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAEtE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAmB,EACnB,OAAyC;IAOzC,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAE3F,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAEzD,MAAM,SAAS,GAAG,KAAK,EAAE,SAAS,IAAI,KAAK,CAAC;IAC5C,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC;IAEnF,MAAM,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC;IACjD,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE;QACpC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC,EAAE,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC,CAAC;IAEpC,OAAO;QACL,aAAa,EAAE,SAAS,IAAI,CAAC,aAAa;QAC1C,YAAY,EAAE,SAAS,IAAI,aAAa;QACxC,SAAS;QACT,YAAY;KACb,CAAC;AACJ,CAAC","sourcesContent":["/**\n * useComponentLoading Hook — Tier 2: Component-Level Loading State\n *\n * Separated from LoadingContext.tsx for React Fast Refresh compatibility.\n */\n\nimport { useContext, useCallback } from 'react';\nimport { LoadingContext } from './LoadingContext';\nimport type { LoadingScope } from './loading-types.frontend.schemas';\nimport { buildLoadingScopeKey } from './loading-scope.frontend.utils';\n\n/**\n * Tier 2: Component-level loading state for a specific scope.\n * Derives isInitialLoad vs isRefreshing from the LoadedOnceCache.\n *\n * - `isInitialLoad`: Loading AND this scope has never been loaded before → show skeleton\n * - `isRefreshing`: Loading AND this scope was loaded before → show opacity overlay\n * - `isLoading`: Either of the above\n * - `markRendered`: Call after first successful render to record in LoadedOnceCache\n *\n * @param scope - What is being loaded (resource+operation or custom identifier)\n * @param options.refreshThresholdMs - TTL for hasLoadedOnce (default 5 min)\n * @throws Error if used outside of LoadingProvider\n */\nexport function useComponentLoading(\n  scope: LoadingScope,\n  options?: { refreshThresholdMs?: number }\n): {\n  isInitialLoad: boolean;\n  isRefreshing: boolean;\n  isLoading: boolean;\n  markRendered: () => void;\n} {\n  const context = useContext(LoadingContext);\n  if (!context) throw new Error('useComponentLoading must be used within a LoadingProvider');\n\n  const scopeKey = buildLoadingScopeKey(scope);\n  const state = context.getComponentLoadingState(scopeKey);\n\n  const isLoading = state?.isLoading ?? false;\n  const hasLoadedOnce = context.hasLoadedOnce(scopeKey, options?.refreshThresholdMs);\n\n  const contextMarkRendered = context.markRendered;\n  const markRendered = useCallback(() => {\n    contextMarkRendered(scopeKey);\n  }, [contextMarkRendered, scopeKey]);\n\n  return {\n    isInitialLoad: isLoading && !hasLoadedOnce,\n    isRefreshing: isLoading && hasLoadedOnce,\n    isLoading,\n    markRendered,\n  };\n}\n"]}
+{"version":3,"file":"useComponentLoading.js","sourceRoot":"","sources":["../../../../src/core/loading/useComponentLoading.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAEtE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAmB,EACnB,OAAyC;IAOzC,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAE3F,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAEzD,MAAM,SAAS,GAAG,KAAK,EAAE,SAAS,IAAI,KAAK,CAAC;IAC5C,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC;IAEnF,MAAM,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC;IACjD,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE;QACpC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC,EAAE,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC,CAAC;IAEpC,OAAO;QACL,aAAa,EAAE,SAAS,IAAI,CAAC,aAAa;QAC1C,YAAY,EAAE,SAAS,IAAI,aAAa;QACxC,SAAS;QACT,YAAY;KACb,CAAC;AACJ,CAAC","sourcesContent":["/**\n * useComponentLoading Hook — Tier 2: Component-Level Loading State\n *\n * Separated from LoadingContext.tsx for React Fast Refresh compatibility.\n */\n\nimport { useContext, useCallback } from 'react';\nimport { LoadingContext } from './LoadingContext';\nimport type { LoadingScope } from './loading-types.frontend.schemas';\nimport { buildLoadingScopeKey } from './loading-scope.frontend.utils';\n\n/**\n * Tier 2: Component-level loading state for a specific scope.\n * Derives isInitialLoad vs isRefreshing from the LoadedOnceCache.\n *\n * - `isInitialLoad`: Loading AND this scope has never been loaded before → show skeleton\n * - `isRefreshing`: Loading AND this scope was loaded before → show opacity overlay\n * - `isLoading`: Either of the above\n * - `markRendered`: Call after first successful render to record in LoadedOnceCache\n *\n * @param scope - What is being loaded (resource+operation or custom identifier)\n * @param options.refreshThresholdMs - TTL for hasLoadedOnce (default 5 min)\n * @throws Error if used outside of LoadingProvider\n */\nexport function useComponentLoading(\n  scope: LoadingScope,\n  options?: { refreshThresholdMs?: number }\n): {\n  isInitialLoad: boolean;\n  isRefreshing: boolean;\n  isLoading: boolean;\n  markRendered: () => void;\n} {\n  const context = useContext(LoadingContext);\n  if (!context) throw new Error('useComponentLoading must be used within a LoadingProvider');\n\n  const scopeKey = buildLoadingScopeKey(scope);\n  const state = context.getComponentLoadingState(scopeKey);\n\n  const isLoading = state?.isLoading ?? false;\n  const hasLoadedOnce = context.hasLoadedOnce(scopeKey, options?.refreshThresholdMs);\n\n  const contextMarkRendered = context.markRendered;\n  const markRendered = useCallback(() => {\n    contextMarkRendered(scopeKey);\n  }, [contextMarkRendered, scopeKey]);\n\n  return {\n    isInitialLoad: isLoading && !hasLoadedOnce,\n    isRefreshing: isLoading && hasLoadedOnce,\n    isLoading,\n    markRendered,\n  };\n}\n"]}

package/dist/esm/core/loading/useEmitLoadingScope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useEmitLoadingScope.d.ts","sourceRoot":"","sources":["../../../../../src/core/loading/useEmitLoadingScope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,EACL,wBAAwB,EAGzB,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,UAAU,EAAE,wBAAwB,CAAC;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,IAAI,CAyCP"}
+{"version":3,"file":"useEmitLoadingScope.d.ts","sourceRoot":"","sources":["../../../../src/core/loading/useEmitLoadingScope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,EACL,wBAAwB,EAGzB,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,UAAU,EAAE,wBAAwB,CAAC;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,IAAI,CAyCP"}

package/dist/esm/core/loading/useEmitLoadingScope.js.map

@@ -1 +1 @@
-{"version":3,"file":"useEmitLoadingScope.js","sourceRoot":"","sources":["../../../../../src/core/loading/useEmitLoadingScope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,EAEL,YAAY,EACZ,WAAW,GACZ,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAInC;IACC,sEAAsE;IACtE,qEAAqE;IACrE,wEAAwE;IACxE,mEAAmE;IACnE,oEAAoE;IACpE,oEAAoE;IACpE,qCAAqC;IACrC,MAAM,UAAU,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,UAAU,EAAE,WAAW,CAAC;IAC5C,MAAM,UAAU,GAAG,UAAU,EAAE,UAAU,CAAC;IAE1C,MAAM,aAAa,GAAG,MAAM,CAAU,KAAK,CAAC,CAAC;IAE7C,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,WAAW,IAAI,CAAC,UAAU;YAAE,OAAO;QAExC,MAAM,KAAK,GAAG,wBAAwB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC1D,MAAM,IAAI,GAAG,WAAW,CAAC,SAAS,CAAC;QAEnC,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC;YAC/C,WAAW,CAAC,KAAK,EAAE;gBACjB,IAAI;gBACJ,KAAK,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO;aAC1E,CAAC,CAAC;YACH,aAAa,CAAC,OAAO,GAAG,IAAI,CAAC;QAC/B,CAAC;aAAM,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,aAAa,CAAC,OAAO,EAAE,CAAC;YACtD,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5B,aAAa,CAAC,OAAO,GAAG,KAAK,CAAC;QAChC,CAAC;IACH,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,aAAa,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;IAEzF,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,GAAG,EAAE;YACV,IAAI,aAAa,CAAC,OAAO,IAAI,UAAU,EAAE,CAAC;gBACxC,MAAM,KAAK,GAAG,wBAAwB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;gBAC1D,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC;gBACnD,aAAa,CAAC,OAAO,GAAG,KAAK,CAAC;YAChC,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;AACtC,CAAC","sourcesContent":["/**\n * useEmitLoadingScope — Tier-2 context loading emitter (L-2.b)\n *\n * Ergonomic wrapper around `LoadingContext.fireLoading`/`endLoading` for the\n * \"context publishes its lifecycle\" use-case. Handles three things consumers\n * would otherwise reinvent:\n *\n * 1. **Tier defaulting** — always emits as `LoadingTier.COMPONENT` (Tier-1\n *    `APPLICATION` is reserved for app-init / language-change events).\n * 2. **Phase derivation** — accepts a single `isLoading` boolean and figures\n *    out whether to emit START or END (and with which phase).\n * 3. **Cleanup** — guarantees an `endLoading` is fired on unmount, so an\n *    in-flight scope can never leak past the provider's lifetime.\n *\n * The hook does **not** own the loading state — the calling context still\n * tracks `isLoading` locally for its own consumers and back-compat. It just\n * mirrors that state to the LoadingContext event bus so unrelated components\n * can observe it via `useComponentLoading({ customIdentifier })` or wrap\n * content in `<LoadingGate scopes={[...]}>`.\n */\n\nimport { useContext, useEffect, useRef } from 'react';\nimport { LoadingContext } from './LoadingContext';\nimport { buildContextLoadingScope } from './loading-scope.frontend.utils';\nimport {\n  ContextLoadingIdentifier,\n  LoadingPhase,\n  LoadingTier,\n} from './loading-types.frontend.schemas';\n\n/**\n * Mirror a context's local `isLoading` boolean onto the LoadingContext event\n * bus under a typed `ContextLoadingIdentifier`.\n *\n * Usage:\n *\n * ```tsx\n * // Inside BillingContext\n * useEmitLoadingScope({\n *   identifier: ContextLoadingIdentifier.BILLING_STATE,\n *   isLoading,\n *   hasLoadedOnce: billingState !== null,\n * });\n * ```\n *\n * Downstream observers:\n *\n * ```tsx\n * const { isInitialLoad } = useComponentLoading({\n *   customIdentifier: ContextLoadingIdentifier.BILLING_STATE,\n * });\n * ```\n *\n * @param params.identifier — typed scope identifier\n * @param params.isLoading — current loading boolean from the context\n * @param params.hasLoadedOnce — distinguishes INITIAL vs REFRESH phase. Pass\n *   `true` once the first successful payload has arrived. Optional; defaults\n *   to `false` (always treats as INITIAL) which is acceptable for contexts\n *   whose first load is the only \"skeleton-worthy\" wait.\n */\nexport function useEmitLoadingScope(params: {\n  identifier: ContextLoadingIdentifier;\n  isLoading: boolean;\n  hasLoadedOnce?: boolean;\n}): void {\n  // Resilience: emission is **opt-in observability**, NOT load-bearing.\n  // A context that calls this hook must remain functional when mounted\n  // outside a `LoadingProvider` (the calling context's own `isLoading` is\n  // still the source of truth for direct consumers). This keeps test\n  // harnesses, isolated story rigs, and minimal-shell apps from being\n  // forced to add `LoadingProvider` just because a downstream context\n  // wants to publish lifecycle events.\n  const loadingCtx = useContext(LoadingContext);\n  const fireLoading = loadingCtx?.fireLoading;\n  const endLoading = loadingCtx?.endLoading;\n\n  const wasLoadingRef = useRef<boolean>(false);\n\n  useEffect(() => {\n    if (!fireLoading || !endLoading) return;\n\n    const scope = buildContextLoadingScope(params.identifier);\n    const tier = LoadingTier.COMPONENT;\n\n    if (params.isLoading && !wasLoadingRef.current) {\n      fireLoading(scope, {\n        tier,\n        phase: params.hasLoadedOnce ? LoadingPhase.REFRESH : LoadingPhase.INITIAL,\n      });\n      wasLoadingRef.current = true;\n    } else if (!params.isLoading && wasLoadingRef.current) {\n      endLoading(scope, { tier });\n      wasLoadingRef.current = false;\n    }\n  }, [params.identifier, params.isLoading, params.hasLoadedOnce, fireLoading, endLoading]);\n\n  useEffect(() => {\n    return () => {\n      if (wasLoadingRef.current && endLoading) {\n        const scope = buildContextLoadingScope(params.identifier);\n        endLoading(scope, { tier: LoadingTier.COMPONENT });\n        wasLoadingRef.current = false;\n      }\n    };\n  }, [params.identifier, endLoading]);\n}\n"]}
+{"version":3,"file":"useEmitLoadingScope.js","sourceRoot":"","sources":["../../../../src/core/loading/useEmitLoadingScope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,EAEL,YAAY,EACZ,WAAW,GACZ,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAInC;IACC,sEAAsE;IACtE,qEAAqE;IACrE,wEAAwE;IACxE,mEAAmE;IACnE,oEAAoE;IACpE,oEAAoE;IACpE,qCAAqC;IACrC,MAAM,UAAU,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,UAAU,EAAE,WAAW,CAAC;IAC5C,MAAM,UAAU,GAAG,UAAU,EAAE,UAAU,CAAC;IAE1C,MAAM,aAAa,GAAG,MAAM,CAAU,KAAK,CAAC,CAAC;IAE7C,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,WAAW,IAAI,CAAC,UAAU;YAAE,OAAO;QAExC,MAAM,KAAK,GAAG,wBAAwB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC1D,MAAM,IAAI,GAAG,WAAW,CAAC,SAAS,CAAC;QAEnC,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC;YAC/C,WAAW,CAAC,KAAK,EAAE;gBACjB,IAAI;gBACJ,KAAK,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO;aAC1E,CAAC,CAAC;YACH,aAAa,CAAC,OAAO,GAAG,IAAI,CAAC;QAC/B,CAAC;aAAM,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,aAAa,CAAC,OAAO,EAAE,CAAC;YACtD,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5B,aAAa,CAAC,OAAO,GAAG,KAAK,CAAC;QAChC,CAAC;IACH,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,aAAa,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;IAEzF,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,GAAG,EAAE;YACV,IAAI,aAAa,CAAC,OAAO,IAAI,UAAU,EAAE,CAAC;gBACxC,MAAM,KAAK,GAAG,wBAAwB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;gBAC1D,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC;gBACnD,aAAa,CAAC,OAAO,GAAG,KAAK,CAAC;YAChC,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;AACtC,CAAC","sourcesContent":["/**\n * useEmitLoadingScope — Tier-2 context loading emitter (L-2.b)\n *\n * Ergonomic wrapper around `LoadingContext.fireLoading`/`endLoading` for the\n * \"context publishes its lifecycle\" use-case. Handles three things consumers\n * would otherwise reinvent:\n *\n * 1. **Tier defaulting** — always emits as `LoadingTier.COMPONENT` (Tier-1\n *    `APPLICATION` is reserved for app-init / language-change events).\n * 2. **Phase derivation** — accepts a single `isLoading` boolean and figures\n *    out whether to emit START or END (and with which phase).\n * 3. **Cleanup** — guarantees an `endLoading` is fired on unmount, so an\n *    in-flight scope can never leak past the provider's lifetime.\n *\n * The hook does **not** own the loading state — the calling context still\n * tracks `isLoading` locally for its own consumers and back-compat. It just\n * mirrors that state to the LoadingContext event bus so unrelated components\n * can observe it via `useComponentLoading({ customIdentifier })` or wrap\n * content in `<LoadingGate scopes={[...]}>`.\n */\n\nimport { useContext, useEffect, useRef } from 'react';\nimport { LoadingContext } from './LoadingContext';\nimport { buildContextLoadingScope } from './loading-scope.frontend.utils';\nimport {\n  ContextLoadingIdentifier,\n  LoadingPhase,\n  LoadingTier,\n} from './loading-types.frontend.schemas';\n\n/**\n * Mirror a context's local `isLoading` boolean onto the LoadingContext event\n * bus under a typed `ContextLoadingIdentifier`.\n *\n * Usage:\n *\n * ```tsx\n * // Inside BillingContext\n * useEmitLoadingScope({\n *   identifier: ContextLoadingIdentifier.BILLING_STATE,\n *   isLoading,\n *   hasLoadedOnce: billingState !== null,\n * });\n * ```\n *\n * Downstream observers:\n *\n * ```tsx\n * const { isInitialLoad } = useComponentLoading({\n *   customIdentifier: ContextLoadingIdentifier.BILLING_STATE,\n * });\n * ```\n *\n * @param params.identifier — typed scope identifier\n * @param params.isLoading — current loading boolean from the context\n * @param params.hasLoadedOnce — distinguishes INITIAL vs REFRESH phase. Pass\n *   `true` once the first successful payload has arrived. Optional; defaults\n *   to `false` (always treats as INITIAL) which is acceptable for contexts\n *   whose first load is the only \"skeleton-worthy\" wait.\n */\nexport function useEmitLoadingScope(params: {\n  identifier: ContextLoadingIdentifier;\n  isLoading: boolean;\n  hasLoadedOnce?: boolean;\n}): void {\n  // Resilience: emission is **opt-in observability**, NOT load-bearing.\n  // A context that calls this hook must remain functional when mounted\n  // outside a `LoadingProvider` (the calling context's own `isLoading` is\n  // still the source of truth for direct consumers). This keeps test\n  // harnesses, isolated story rigs, and minimal-shell apps from being\n  // forced to add `LoadingProvider` just because a downstream context\n  // wants to publish lifecycle events.\n  const loadingCtx = useContext(LoadingContext);\n  const fireLoading = loadingCtx?.fireLoading;\n  const endLoading = loadingCtx?.endLoading;\n\n  const wasLoadingRef = useRef<boolean>(false);\n\n  useEffect(() => {\n    if (!fireLoading || !endLoading) return;\n\n    const scope = buildContextLoadingScope(params.identifier);\n    const tier = LoadingTier.COMPONENT;\n\n    if (params.isLoading && !wasLoadingRef.current) {\n      fireLoading(scope, {\n        tier,\n        phase: params.hasLoadedOnce ? LoadingPhase.REFRESH : LoadingPhase.INITIAL,\n      });\n      wasLoadingRef.current = true;\n    } else if (!params.isLoading && wasLoadingRef.current) {\n      endLoading(scope, { tier });\n      wasLoadingRef.current = false;\n    }\n  }, [params.identifier, params.isLoading, params.hasLoadedOnce, fireLoading, endLoading]);\n\n  useEffect(() => {\n    return () => {\n      if (wasLoadingRef.current && endLoading) {\n        const scope = buildContextLoadingScope(params.identifier);\n        endLoading(scope, { tier: LoadingTier.COMPONENT });\n        wasLoadingRef.current = false;\n      }\n    };\n  }, [params.identifier, endLoading]);\n}\n"]}

package/dist/esm/core/loading/useLoading.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLoading.d.ts","sourceRoot":"","sources":["../../../../../src/core/loading/useLoading.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3E;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,QAAO,kBAM7B,CAAC"}
+{"version":3,"file":"useLoading.d.ts","sourceRoot":"","sources":["../../../../src/core/loading/useLoading.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3E;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,QAAO,kBAM7B,CAAC"}

package/dist/esm/core/loading/useLoading.js.map

@@ -1 +1 @@
-{"version":3,"file":"useLoading.js","sourceRoot":"","sources":["../../../../../src/core/loading/useLoading.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,EAAE,cAAc,EAA2B,MAAM,kBAAkB,CAAC;AAE3E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,GAAuB,EAAE;IACjD,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC","sourcesContent":["import { useContext } from 'react';\nimport { LoadingContext, type LoadingContextType } from './LoadingContext';\n\n/**\n * useLoading Hook\n *\n * Separated from LoadingContext.tsx for React Fast Refresh compatibility.\n * Prefer useAppLoading() for Tier 1 or useComponentLoading() for Tier 2 when\n * only those concerns are needed.\n *\n * @returns LoadingContextType with fireLoading, endLoading, and state access\n * @throws Error if used outside of LoadingProvider\n */\nexport const useLoading = (): LoadingContextType => {\n  const context = useContext(LoadingContext);\n  if (!context) {\n    throw new Error('useLoading must be used within a LoadingProvider');\n  }\n  return context;\n};\n\n"]}
+{"version":3,"file":"useLoading.js","sourceRoot":"","sources":["../../../../src/core/loading/useLoading.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,EAAE,cAAc,EAA2B,MAAM,kBAAkB,CAAC;AAE3E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,GAAuB,EAAE;IACjD,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC","sourcesContent":["import { useContext } from 'react';\nimport { LoadingContext, type LoadingContextType } from './LoadingContext';\n\n/**\n * useLoading Hook\n *\n * Separated from LoadingContext.tsx for React Fast Refresh compatibility.\n * Prefer useAppLoading() for Tier 1 or useComponentLoading() for Tier 2 when\n * only those concerns are needed.\n *\n * @returns LoadingContextType with fireLoading, endLoading, and state access\n * @throws Error if used outside of LoadingProvider\n */\nexport const useLoading = (): LoadingContextType => {\n  const context = useContext(LoadingContext);\n  if (!context) {\n    throw new Error('useLoading must be used within a LoadingProvider');\n  }\n  return context;\n};\n\n"]}

package/dist/esm/core/mode/AppModeContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AppModeContext.d.ts","sourceRoot":"","sources":["../../../../../src/core/mode/AppModeContext.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAA+E,MAAM,OAAO,CAAC;AACpG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iEAAiE,CAAC;AAQzG,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,kFAAkF;IAClF,cAAc,EAAE,iBAAiB,EAAE,CAAC;IACpC,8DAA8D;IAC9D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,2EAA2E;IAC3E,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,sDAAsD;IACtD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAkED,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CA6D1D,CAAC;AAMF;;GAEG;AACH,wBAAgB,UAAU,IAAI,mBAAmB,CAMhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,mBAAmB,GAAG,IAAI,CAE3D"}
+{"version":3,"file":"AppModeContext.d.ts","sourceRoot":"","sources":["../../../../src/core/mode/AppModeContext.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAA+E,MAAM,OAAO,CAAC;AACpG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iEAAiE,CAAC;AAQzG,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,kFAAkF;IAClF,cAAc,EAAE,iBAAiB,EAAE,CAAC;IACpC,8DAA8D;IAC9D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,2EAA2E;IAC3E,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,sDAAsD;IACtD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAkED,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CA6D1D,CAAC;AAMF;;GAEG;AACH,wBAAgB,UAAU,IAAI,mBAAmB,CAMhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,mBAAmB,GAAG,IAAI,CAE3D"}

package/dist/esm/core/mode/AppModeContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"AppModeContext.js","sourceRoot":"","sources":["../../../../../src/core/mode/AppModeContext.tsx"],"names":[],"mappings":"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","sourcesContent":["/**\n * AppModeContext — manages the active application mode.\n *\n * Modes represent UI activities (explorer, search, admin, etc.) that control\n * which sidebar sections are visible. The `ACTIVITY_BAR` component renders\n * available modes; this context manages the selection state.\n *\n * Mode resolution cascade on mount:\n *   1. localStorage (persisted from last session)\n *   2. validate persisted mode is still available\n *   3. `isDefault` mode\n *   4. first available mode\n *   5. null (no modes configured)\n *\n * Auto-persists `activeMode` in localStorage keyed by `appName`.\n *\n * @see component-taxonomy-deep-review.md §7.3, §7.5\n * @see app-shell-implementation-plan.md Step 6\n */\n\nimport React, { createContext, useContext, useMemo, useState, useCallback, useEffect } from 'react';\nimport type { ReactNode } from 'react';\nimport type { AppModeDefinition } from '~wildo-frontend-lib/core/config/launcher-items.frontend.schemas';\nimport { useApplication } from '~wildo-frontend-lib/core/runtime/useApplication';\nimport { useResolvedAuthConfig } from '~wildo-frontend-lib/core/security/useResolvedAuthConfig';\n\n// ════════════════════════════════════════════════════════════════\n// Context Value\n// ════════════════════════════════════════════════════════════════\n\nexport interface AppModeContextValue {\n  /** All declared app modes (before user type filtering). */\n  allModes: AppModeDefinition[];\n  /** Modes available to the current user (after `visibleToUserTypes` filtering). */\n  availableModes: AppModeDefinition[];\n  /** Currently active mode ref, or `null` if no mode system. */\n  activeMode: string | null;\n  /** Switch to a different mode. No-op if ref is not in `availableModes`. */\n  setActiveMode: (modeRef: string) => void;\n  /** Whether the app has any available modes at all. */\n  hasModes: boolean;\n}\n\nconst AppModeContext = createContext<AppModeContextValue | undefined>(undefined);\n\n// ════════════════════════════════════════════════════════════════\n// localStorage Persistence\n// ════════════════════════════════════════════════════════════════\n\nconst STORAGE_KEY_PREFIX = 'wildo:appMode:';\n\nfunction buildStorageKey(appName: string | undefined, userId: string | undefined): string {\n  return `${STORAGE_KEY_PREFIX}${appName ?? 'default'}:${userId ?? 'anon'}`;\n}\n\nfunction readPersistedMode(storageKey: string): string | null {\n  try {\n    return localStorage.getItem(storageKey);\n  } catch {\n    return null;\n  }\n}\n\nfunction persistMode(storageKey: string, modeRef: string): void {\n  try {\n    localStorage.setItem(storageKey, modeRef);\n  } catch {\n    // localStorage may be unavailable (SSR, incognito quota)\n  }\n}\n\n// ════════════════════════════════════════════════════════════════\n// Mode Resolution\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Resolve the initial active mode using the cascade:\n * localStorage → validate → isDefault → first → null\n */\nfunction resolveInitialMode(\n  availableModes: AppModeDefinition[],\n  storageKey: string,\n): string | null {\n  if (availableModes.length === 0) return null;\n\n  const availableRefs = new Set(availableModes.map(m => m.ref));\n\n  // 1. Try persisted mode\n  const persisted = readPersistedMode(storageKey);\n  if (persisted && availableRefs.has(persisted)) {\n    return persisted;\n  }\n\n  // 2. Try isDefault mode\n  const defaultMode = availableModes.find(m => m.isDefault);\n  if (defaultMode) {\n    return defaultMode.ref;\n  }\n\n  // 3. First available\n  return availableModes[0].ref;\n}\n\n// ════════════════════════════════════════════════════════════════\n// Provider\n// ════════════════════════════════════════════════════════════════\n\ninterface AppModeProviderProps {\n  children: ReactNode;\n}\n\nexport const AppModeProvider: React.FC<AppModeProviderProps> = ({ children }) => {\n  const { frontendConfiguration, appConfig } = useApplication();\n  const { resolvedUserType } = useResolvedAuthConfig();\n\n  const allModes: AppModeDefinition[] = useMemo(\n    () => frontendConfiguration?.appModes ?? [],\n    [frontendConfiguration?.appModes],\n  );\n\n  const availableModes: AppModeDefinition[] = useMemo(() => {\n    if (!resolvedUserType) return allModes;\n    return allModes.filter(mode => {\n      if (!mode.visibleToUserTypes || mode.visibleToUserTypes.length === 0) return true;\n      return mode.visibleToUserTypes.includes(resolvedUserType);\n    });\n  }, [allModes, resolvedUserType]);\n\n  const storageKey = useMemo(\n    () => buildStorageKey(\n      appConfig?.appIdentity?.appName,\n      undefined, // userId is not available at this provider level; keyed by appName only\n    ),\n    [appConfig?.appIdentity?.appName],\n  );\n\n  const [activeMode, setActiveModeInternal] = useState<string | null>(() =>\n    resolveInitialMode(availableModes, storageKey),\n  );\n\n  // Re-resolve when available modes change (e.g., user type resolved after async auth)\n  useEffect(() => {\n    if (availableModes.length === 0) {\n      setActiveModeInternal(null);\n      return;\n    }\n    const availableRefs = new Set(availableModes.map(m => m.ref));\n    if (activeMode && availableRefs.has(activeMode)) return;\n    const resolved = resolveInitialMode(availableModes, storageKey);\n    setActiveModeInternal(resolved);\n  }, [availableModes, storageKey]); // eslint-disable-line react-hooks/exhaustive-deps\n\n  const setActiveMode = useCallback((modeRef: string) => {\n    const isValid = availableModes.some(m => m.ref === modeRef);\n    if (!isValid) return;\n    setActiveModeInternal(modeRef);\n    persistMode(storageKey, modeRef);\n  }, [availableModes, storageKey]);\n\n  const contextValue: AppModeContextValue = useMemo(() => ({\n    allModes,\n    availableModes,\n    activeMode,\n    setActiveMode,\n    hasModes: availableModes.length > 0,\n  }), [allModes, availableModes, activeMode, setActiveMode]);\n\n  return (\n    <AppModeContext.Provider value={contextValue}>\n      {children}\n    </AppModeContext.Provider>\n  );\n};\n\n// ════════════════════════════════════════════════════════════════\n// Hooks\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Access the app mode context. Throws if used outside `AppModeProvider`.\n */\nexport function useAppMode(): AppModeContextValue {\n  const ctx = useContext(AppModeContext);\n  if (!ctx) {\n    throw new Error('useAppMode must be used within an AppModeProvider');\n  }\n  return ctx;\n}\n\n/**\n * Access the app mode context without throwing if the provider is missing.\n * Returns `null` when used outside `AppModeProvider`.\n */\nexport function useAppModeSafe(): AppModeContextValue | null {\n  return useContext(AppModeContext) ?? null;\n}\n"]}
+{"version":3,"file":"AppModeContext.js","sourceRoot":"","sources":["../../../../src/core/mode/AppModeContext.tsx"],"names":[],"mappings":"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","sourcesContent":["/**\n * AppModeContext — manages the active application mode.\n *\n * Modes represent UI activities (explorer, search, admin, etc.) that control\n * which sidebar sections are visible. The `ACTIVITY_BAR` component renders\n * available modes; this context manages the selection state.\n *\n * Mode resolution cascade on mount:\n *   1. localStorage (persisted from last session)\n *   2. validate persisted mode is still available\n *   3. `isDefault` mode\n *   4. first available mode\n *   5. null (no modes configured)\n *\n * Auto-persists `activeMode` in localStorage keyed by `appName`.\n *\n * @see component-taxonomy-deep-review.md §7.3, §7.5\n * @see app-shell-implementation-plan.md Step 6\n */\n\nimport React, { createContext, useContext, useMemo, useState, useCallback, useEffect } from 'react';\nimport type { ReactNode } from 'react';\nimport type { AppModeDefinition } from '~wildo-frontend-lib/core/config/launcher-items.frontend.schemas';\nimport { useApplication } from '~wildo-frontend-lib/core/runtime/useApplication';\nimport { useResolvedAuthConfig } from '~wildo-frontend-lib/core/security/useResolvedAuthConfig';\n\n// ════════════════════════════════════════════════════════════════\n// Context Value\n// ════════════════════════════════════════════════════════════════\n\nexport interface AppModeContextValue {\n  /** All declared app modes (before user type filtering). */\n  allModes: AppModeDefinition[];\n  /** Modes available to the current user (after `visibleToUserTypes` filtering). */\n  availableModes: AppModeDefinition[];\n  /** Currently active mode ref, or `null` if no mode system. */\n  activeMode: string | null;\n  /** Switch to a different mode. No-op if ref is not in `availableModes`. */\n  setActiveMode: (modeRef: string) => void;\n  /** Whether the app has any available modes at all. */\n  hasModes: boolean;\n}\n\nconst AppModeContext = createContext<AppModeContextValue | undefined>(undefined);\n\n// ════════════════════════════════════════════════════════════════\n// localStorage Persistence\n// ════════════════════════════════════════════════════════════════\n\nconst STORAGE_KEY_PREFIX = 'wildo:appMode:';\n\nfunction buildStorageKey(appName: string | undefined, userId: string | undefined): string {\n  return `${STORAGE_KEY_PREFIX}${appName ?? 'default'}:${userId ?? 'anon'}`;\n}\n\nfunction readPersistedMode(storageKey: string): string | null {\n  try {\n    return localStorage.getItem(storageKey);\n  } catch {\n    return null;\n  }\n}\n\nfunction persistMode(storageKey: string, modeRef: string): void {\n  try {\n    localStorage.setItem(storageKey, modeRef);\n  } catch {\n    // localStorage may be unavailable (SSR, incognito quota)\n  }\n}\n\n// ════════════════════════════════════════════════════════════════\n// Mode Resolution\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Resolve the initial active mode using the cascade:\n * localStorage → validate → isDefault → first → null\n */\nfunction resolveInitialMode(\n  availableModes: AppModeDefinition[],\n  storageKey: string,\n): string | null {\n  if (availableModes.length === 0) return null;\n\n  const availableRefs = new Set(availableModes.map(m => m.ref));\n\n  // 1. Try persisted mode\n  const persisted = readPersistedMode(storageKey);\n  if (persisted && availableRefs.has(persisted)) {\n    return persisted;\n  }\n\n  // 2. Try isDefault mode\n  const defaultMode = availableModes.find(m => m.isDefault);\n  if (defaultMode) {\n    return defaultMode.ref;\n  }\n\n  // 3. First available\n  return availableModes[0].ref;\n}\n\n// ════════════════════════════════════════════════════════════════\n// Provider\n// ════════════════════════════════════════════════════════════════\n\ninterface AppModeProviderProps {\n  children: ReactNode;\n}\n\nexport const AppModeProvider: React.FC<AppModeProviderProps> = ({ children }) => {\n  const { frontendConfiguration, appConfig } = useApplication();\n  const { resolvedUserType } = useResolvedAuthConfig();\n\n  const allModes: AppModeDefinition[] = useMemo(\n    () => frontendConfiguration?.appModes ?? [],\n    [frontendConfiguration?.appModes],\n  );\n\n  const availableModes: AppModeDefinition[] = useMemo(() => {\n    if (!resolvedUserType) return allModes;\n    return allModes.filter(mode => {\n      if (!mode.visibleToUserTypes || mode.visibleToUserTypes.length === 0) return true;\n      return mode.visibleToUserTypes.includes(resolvedUserType);\n    });\n  }, [allModes, resolvedUserType]);\n\n  const storageKey = useMemo(\n    () => buildStorageKey(\n      appConfig?.appIdentity?.appName,\n      undefined, // userId is not available at this provider level; keyed by appName only\n    ),\n    [appConfig?.appIdentity?.appName],\n  );\n\n  const [activeMode, setActiveModeInternal] = useState<string | null>(() =>\n    resolveInitialMode(availableModes, storageKey),\n  );\n\n  // Re-resolve when available modes change (e.g., user type resolved after async auth)\n  useEffect(() => {\n    if (availableModes.length === 0) {\n      setActiveModeInternal(null);\n      return;\n    }\n    const availableRefs = new Set(availableModes.map(m => m.ref));\n    if (activeMode && availableRefs.has(activeMode)) return;\n    const resolved = resolveInitialMode(availableModes, storageKey);\n    setActiveModeInternal(resolved);\n  }, [availableModes, storageKey]); // eslint-disable-line react-hooks/exhaustive-deps\n\n  const setActiveMode = useCallback((modeRef: string) => {\n    const isValid = availableModes.some(m => m.ref === modeRef);\n    if (!isValid) return;\n    setActiveModeInternal(modeRef);\n    persistMode(storageKey, modeRef);\n  }, [availableModes, storageKey]);\n\n  const contextValue: AppModeContextValue = useMemo(() => ({\n    allModes,\n    availableModes,\n    activeMode,\n    setActiveMode,\n    hasModes: availableModes.length > 0,\n  }), [allModes, availableModes, activeMode, setActiveMode]);\n\n  return (\n    <AppModeContext.Provider value={contextValue}>\n      {children}\n    </AppModeContext.Provider>\n  );\n};\n\n// ════════════════════════════════════════════════════════════════\n// Hooks\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Access the app mode context. Throws if used outside `AppModeProvider`.\n */\nexport function useAppMode(): AppModeContextValue {\n  const ctx = useContext(AppModeContext);\n  if (!ctx) {\n    throw new Error('useAppMode must be used within an AppModeProvider');\n  }\n  return ctx;\n}\n\n/**\n * Access the app mode context without throwing if the provider is missing.\n * Returns `null` when used outside `AppModeProvider`.\n */\nexport function useAppModeSafe(): AppModeContextValue | null {\n  return useContext(AppModeContext) ?? null;\n}\n"]}

package/dist/esm/core/mode/section-visibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"section-visibility.d.ts","sourceRoot":"","sources":["../../../../../src/core/mode/section-visibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,iEAAiE,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uDAAuD,CAAC;AAO3F;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,oBAAoB,EAAE,oBAAoB,GACzC,OAAO,CAmBT;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,cAAc,EAAE,EAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,oBAAoB,EAAE,oBAAoB,EAC1C,aAAa,GAAE,OAAe,GAC7B,cAAc,EAAE,CAwBlB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EAC7C,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,cAAc,EAAE,iBAAiB,EAAE,GAClC,oBAAoB,CAMtB;AAgBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,cAAc,EAAE,EAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,oBAAoB,EAAE,oBAAoB,GACzC,IAAI,CAwCN"}
+{"version":3,"file":"section-visibility.d.ts","sourceRoot":"","sources":["../../../../src/core/mode/section-visibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,iEAAiE,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uDAAuD,CAAC;AAO3F;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,oBAAoB,EAAE,oBAAoB,GACzC,OAAO,CAmBT;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,cAAc,EAAE,EAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,oBAAoB,EAAE,oBAAoB,EAC1C,aAAa,GAAE,OAAe,GAC7B,cAAc,EAAE,CAwBlB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EAC7C,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,cAAc,EAAE,iBAAiB,EAAE,GAClC,oBAAoB,CAMtB;AAgBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,cAAc,EAAE,EAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,oBAAoB,EAAE,oBAAoB,GACzC,IAAI,CAwCN"}

package/dist/esm/core/mode/section-visibility.js.map

@@ -1 +1 @@
-{"version":3,"file":"section-visibility.js","sourceRoot":"","sources":["../../../../../src/core/mode/section-visibility.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Section Visibility Logic\n *\n * Pure functions for evaluating whether a sidebar section should be visible\n * based on the current mode and scope state. Also provides a DEV-mode\n * visibility debugger that logs a console table showing each section's\n * filter results.\n *\n * @see component-taxonomy-deep-review.md §7.6\n * @see app-shell-implementation-plan.md Steps 6, 8\n */\n\nimport type {\n  SidebarSection,\n  ScopeConditionParams,\n  AppModeDefinition,\n} from '~wildo-frontend-lib/core/config/launcher-items.frontend.schemas';\nimport type { AppScopeValue } from '~wildo-frontend-lib/core/scope/scope.frontend.schemas';\nimport { SidebarSectionContentKind } from '~wildo-frontend-lib/core/config/launcher-items.frontend.schemas';\n\n// ════════════════════════════════════════════════════════════════\n// Section Visibility Evaluation\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Determines whether a sidebar section should be visible given the\n * current mode and scope state.\n *\n * Evaluation order:\n *   1. `visibleInModes` — if set, section is only visible when\n *      `activeMode` is in the list. If the list is empty or absent,\n *      the section is visible in all modes.\n *   2. `scopeCondition` — if set, the predicate is called with\n *      the current scope parameters. Must return `true` for the\n *      section to be visible.\n *   3. Both must pass for the section to be visible.\n */\nexport function isSectionVisible(\n  section: SidebarSection,\n  activeMode: string | null,\n  scopeConditionParams: ScopeConditionParams,\n): boolean {\n  // Mode filter\n  if (section.visibleInModes && section.visibleInModes.length > 0) {\n    if (!activeMode || !section.visibleInModes.includes(activeMode)) {\n      return false;\n    }\n  }\n\n  // Scope condition\n  if (section.scopeCondition) {\n    try {\n      return section.scopeCondition(scopeConditionParams);\n    } catch {\n      // Defensive: malformed scopeCondition should not crash the sidebar\n      return false;\n    }\n  }\n\n  return true;\n}\n\n/**\n * Filters a list of sidebar sections to only those visible in the\n * current mode and scope state.\n *\n * Also includes a DEV-mode warning if all sections are hidden and\n * no `GUIDANCE_WIDGET` covers the empty state.\n */\nexport function filterVisibleSections(\n  sections: SidebarSection[],\n  activeMode: string | null,\n  scopeConditionParams: ScopeConditionParams,\n  isDevelopment: boolean = false,\n): SidebarSection[] {\n  const visible = sections.filter(s =>\n    isSectionVisible(s, activeMode, scopeConditionParams),\n  );\n\n  if (isDevelopment && visible.length === 0 && sections.length > 0) {\n    // Only suppress the warning if a GUIDANCE_WIDGET exists that could actually\n    // render — i.e., one without mode restrictions (always visible regardless of\n    // which mode hides the other sections).\n    const hasUnconditionalGuidance = sections.some(\n      s => s.contentKind === SidebarSectionContentKind.GUIDANCE_WIDGET &&\n           (!s.visibleInModes || s.visibleInModes.length === 0),\n    );\n    if (!hasUnconditionalGuidance) {\n      console.warn(\n        '[AppMode] All sidebar sections are hidden and no unconditionally-visible ' +\n        'GUIDANCE_WIDGET section covers the empty state. Consider adding a ' +\n        'GUIDANCE_WIDGET section without visibleInModes restrictions and a ' +\n        'scopeCondition that activates when other sections are hidden.',\n      );\n    }\n  }\n\n  return visible;\n}\n\n/**\n * Builds `ScopeConditionParams` from the current app state.\n * Used by `useSidebarBehavior` to construct the params for `isSectionVisible`.\n */\nexport function buildScopeConditionParams(\n  appScopeValues: Record<string, AppScopeValue>,\n  activeMode: string | null,\n  availableModes: AppModeDefinition[],\n): ScopeConditionParams {\n  return {\n    appScopeValues,\n    activeMode,\n    availableModes,\n  };\n}\n\n// ════════════════════════════════════════════════════════════════\n// DEV Visibility Debugger\n// ════════════════════════════════════════════════════════════════\n\ninterface SectionVisibilityDebugRow {\n  ref: string;\n  contentKind: string;\n  modeFilter: string;\n  modeMatch: boolean | 'N/A';\n  hasScopeCondition: boolean;\n  scopeMatch: boolean | 'N/A';\n  visible: boolean;\n}\n\n/**\n * Logs a console table showing each sidebar section's visibility state.\n * Useful for diagnosing why sections are hidden/shown.\n *\n * Call from browser DevTools or wire into a debug flag:\n * ```typescript\n * if (window.__WILDO_DEBUG_SIDEBAR__) {\n *   debugSectionVisibility(sections, activeMode, scopeParams);\n * }\n * ```\n *\n * @see app-shell-implementation-plan.md Step 8.3\n */\nexport function debugSectionVisibility(\n  sections: SidebarSection[],\n  activeMode: string | null,\n  scopeConditionParams: ScopeConditionParams,\n): void {\n  const rows: SectionVisibilityDebugRow[] = sections.map(section => {\n    const hasModeFilter = !!(section.visibleInModes && section.visibleInModes.length > 0);\n    let modeMatch: boolean | 'N/A' = 'N/A';\n\n    if (hasModeFilter) {\n      modeMatch = !!activeMode && section.visibleInModes!.includes(activeMode);\n    }\n\n    const hasScopeCondition = !!section.scopeCondition;\n    let scopeMatch: boolean | 'N/A' = 'N/A';\n\n    if (hasScopeCondition) {\n      try {\n        scopeMatch = section.scopeCondition!(scopeConditionParams);\n      } catch {\n        scopeMatch = false;\n      }\n    }\n\n    const visible = isSectionVisible(section, activeMode, scopeConditionParams);\n\n    return {\n      ref: section.ref,\n      contentKind: section.contentKind,\n      modeFilter: hasModeFilter ? section.visibleInModes!.join(', ') : '(all)',\n      modeMatch,\n      hasScopeCondition,\n      scopeMatch,\n      visible,\n    };\n  });\n\n  console.group(\n    `[SidebarVisibility] activeMode=\"${activeMode ?? 'none'}\" | ` +\n    `${rows.filter(r => r.visible).length}/${rows.length} sections visible`,\n  );\n  console.table(rows);\n  console.log('Scope params:', scopeConditionParams);\n  console.groupEnd();\n}\n"]}
+{"version":3,"file":"section-visibility.js","sourceRoot":"","sources":["../../../../src/core/mode/section-visibility.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Section Visibility Logic\n *\n * Pure functions for evaluating whether a sidebar section should be visible\n * based on the current mode and scope state. Also provides a DEV-mode\n * visibility debugger that logs a console table showing each section's\n * filter results.\n *\n * @see component-taxonomy-deep-review.md §7.6\n * @see app-shell-implementation-plan.md Steps 6, 8\n */\n\nimport type {\n  SidebarSection,\n  ScopeConditionParams,\n  AppModeDefinition,\n} from '~wildo-frontend-lib/core/config/launcher-items.frontend.schemas';\nimport type { AppScopeValue } from '~wildo-frontend-lib/core/scope/scope.frontend.schemas';\nimport { SidebarSectionContentKind } from '~wildo-frontend-lib/core/config/launcher-items.frontend.schemas';\n\n// ════════════════════════════════════════════════════════════════\n// Section Visibility Evaluation\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Determines whether a sidebar section should be visible given the\n * current mode and scope state.\n *\n * Evaluation order:\n *   1. `visibleInModes` — if set, section is only visible when\n *      `activeMode` is in the list. If the list is empty or absent,\n *      the section is visible in all modes.\n *   2. `scopeCondition` — if set, the predicate is called with\n *      the current scope parameters. Must return `true` for the\n *      section to be visible.\n *   3. Both must pass for the section to be visible.\n */\nexport function isSectionVisible(\n  section: SidebarSection,\n  activeMode: string | null,\n  scopeConditionParams: ScopeConditionParams,\n): boolean {\n  // Mode filter\n  if (section.visibleInModes && section.visibleInModes.length > 0) {\n    if (!activeMode || !section.visibleInModes.includes(activeMode)) {\n      return false;\n    }\n  }\n\n  // Scope condition\n  if (section.scopeCondition) {\n    try {\n      return section.scopeCondition(scopeConditionParams);\n    } catch {\n      // Defensive: malformed scopeCondition should not crash the sidebar\n      return false;\n    }\n  }\n\n  return true;\n}\n\n/**\n * Filters a list of sidebar sections to only those visible in the\n * current mode and scope state.\n *\n * Also includes a DEV-mode warning if all sections are hidden and\n * no `GUIDANCE_WIDGET` covers the empty state.\n */\nexport function filterVisibleSections(\n  sections: SidebarSection[],\n  activeMode: string | null,\n  scopeConditionParams: ScopeConditionParams,\n  isDevelopment: boolean = false,\n): SidebarSection[] {\n  const visible = sections.filter(s =>\n    isSectionVisible(s, activeMode, scopeConditionParams),\n  );\n\n  if (isDevelopment && visible.length === 0 && sections.length > 0) {\n    // Only suppress the warning if a GUIDANCE_WIDGET exists that could actually\n    // render — i.e., one without mode restrictions (always visible regardless of\n    // which mode hides the other sections).\n    const hasUnconditionalGuidance = sections.some(\n      s => s.contentKind === SidebarSectionContentKind.GUIDANCE_WIDGET &&\n           (!s.visibleInModes || s.visibleInModes.length === 0),\n    );\n    if (!hasUnconditionalGuidance) {\n      console.warn(\n        '[AppMode] All sidebar sections are hidden and no unconditionally-visible ' +\n        'GUIDANCE_WIDGET section covers the empty state. Consider adding a ' +\n        'GUIDANCE_WIDGET section without visibleInModes restrictions and a ' +\n        'scopeCondition that activates when other sections are hidden.',\n      );\n    }\n  }\n\n  return visible;\n}\n\n/**\n * Builds `ScopeConditionParams` from the current app state.\n * Used by `useSidebarBehavior` to construct the params for `isSectionVisible`.\n */\nexport function buildScopeConditionParams(\n  appScopeValues: Record<string, AppScopeValue>,\n  activeMode: string | null,\n  availableModes: AppModeDefinition[],\n): ScopeConditionParams {\n  return {\n    appScopeValues,\n    activeMode,\n    availableModes,\n  };\n}\n\n// ════════════════════════════════════════════════════════════════\n// DEV Visibility Debugger\n// ════════════════════════════════════════════════════════════════\n\ninterface SectionVisibilityDebugRow {\n  ref: string;\n  contentKind: string;\n  modeFilter: string;\n  modeMatch: boolean | 'N/A';\n  hasScopeCondition: boolean;\n  scopeMatch: boolean | 'N/A';\n  visible: boolean;\n}\n\n/**\n * Logs a console table showing each sidebar section's visibility state.\n * Useful for diagnosing why sections are hidden/shown.\n *\n * Call from browser DevTools or wire into a debug flag:\n * ```typescript\n * if (window.__WILDO_DEBUG_SIDEBAR__) {\n *   debugSectionVisibility(sections, activeMode, scopeParams);\n * }\n * ```\n *\n * @see app-shell-implementation-plan.md Step 8.3\n */\nexport function debugSectionVisibility(\n  sections: SidebarSection[],\n  activeMode: string | null,\n  scopeConditionParams: ScopeConditionParams,\n): void {\n  const rows: SectionVisibilityDebugRow[] = sections.map(section => {\n    const hasModeFilter = !!(section.visibleInModes && section.visibleInModes.length > 0);\n    let modeMatch: boolean | 'N/A' = 'N/A';\n\n    if (hasModeFilter) {\n      modeMatch = !!activeMode && section.visibleInModes!.includes(activeMode);\n    }\n\n    const hasScopeCondition = !!section.scopeCondition;\n    let scopeMatch: boolean | 'N/A' = 'N/A';\n\n    if (hasScopeCondition) {\n      try {\n        scopeMatch = section.scopeCondition!(scopeConditionParams);\n      } catch {\n        scopeMatch = false;\n      }\n    }\n\n    const visible = isSectionVisible(section, activeMode, scopeConditionParams);\n\n    return {\n      ref: section.ref,\n      contentKind: section.contentKind,\n      modeFilter: hasModeFilter ? section.visibleInModes!.join(', ') : '(all)',\n      modeMatch,\n      hasScopeCondition,\n      scopeMatch,\n      visible,\n    };\n  });\n\n  console.group(\n    `[SidebarVisibility] activeMode=\"${activeMode ?? 'none'}\" | ` +\n    `${rows.filter(r => r.visible).length}/${rows.length} sections visible`,\n  );\n  console.table(rows);\n  console.log('Scope params:', scopeConditionParams);\n  console.groupEnd();\n}\n"]}

package/dist/esm/core/monitoring/analytics/AnalyticsContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsContext.d.ts","sourceRoot":"","sources":["../../../../../../src/core/monitoring/analytics/AnalyticsContext.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAuF,MAAM,OAAO,CAAC;AAE5G,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,yCAAyC,CAAC;AAUlG,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACpE,wBAAwB;IACxB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACnE,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,qDAAqD;IACrD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,gFAAgF;IAChF,kBAAkB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD;;;;;OAKG;IACH,WAAW,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;CAC5G;AAKD,eAAO,MAAM,gBAAgB,sCAAoD,CAAC;AAkBlF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACxC;AAED,eAAO,MAAM,wBAAwB,EAAE,KAAK,CAAC,EAAE,CAAC,6BAA6B,CAwO5E,CAAC"}
+{"version":3,"file":"AnalyticsContext.d.ts","sourceRoot":"","sources":["../../../../../src/core/monitoring/analytics/AnalyticsContext.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAuF,MAAM,OAAO,CAAC;AAE5G,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,yCAAyC,CAAC;AAUlG,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACpE,wBAAwB;IACxB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACnE,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,qDAAqD;IACrD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,gFAAgF;IAChF,kBAAkB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD;;;;;OAKG;IACH,WAAW,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;CAC5G;AAKD,eAAO,MAAM,gBAAgB,sCAAoD,CAAC;AAkBlF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACxC;AAED,eAAO,MAAM,wBAAwB,EAAE,KAAK,CAAC,EAAE,CAAC,6BAA6B,CAwO5E,CAAC"}

package/dist/esm/core/monitoring/analytics/AnalyticsContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsContext.js","sourceRoot":"","sources":["../../../../../../src/core/monitoring/analytics/AnalyticsContext.tsx"],"names":[],"mappings":"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","sourcesContent":["/**\n * Analytics Context Provider\n * \n * Provides analytics tracking, value moment achievement persistence,\n * consent gating, and provider lifecycle management.\n */\n\nimport React, { createContext, useContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport { DataProcessingConsent, type AnalyticsConfig, ANALYTICS_ACHIEVED_STORAGE_KEY_PREFIX } from '@wildo-ai/saas-models';\nimport type { IAnalyticsProvider, AnalyticsEvent } from './analytics-provider.frontend.interface';\nimport { AnalyticsProviderRegistry } from './analytics-provider-registry.frontend.service';\nimport { ApplicationContext } from '~wildo-frontend-lib/core/runtime/ApplicationContext.shared';\nimport { useEventBus } from '~wildo-frontend-lib/core/events/useEventBus';\nimport { FrontendEvents } from '~wildo-frontend-lib/core/events/events.frontend.schemas';\nimport { getManualCallsHttpClient } from '~wildo-frontend-lib/core/requests/wildo-http-client-manual-calls.frontend.service';\nimport { AnalyticsEventBridge } from './AnalyticsEventBridge';\n\n// ─── Context Value Interface ────────────────────────────────────\n\nexport interface AnalyticsContextValue {\n  /** Track a custom event (app-custom usage) */\n  track: (name: string, properties?: Record<string, unknown>) => void;\n  /** Track a page view */\n  page: (path: string, properties?: Record<string, unknown>) => void;\n  /** Whether analytics is active (enabled + consent granted) */\n  isActive: boolean;\n  /** Session start timestamp (for TTFV computation) */\n  sessionStartTimestamp: number;\n  /** Set of achieved value moment identifiers (scope-aware, persisted) */\n  achievedMoments: Set<string>;\n  /** Mark a value moment as achieved (persists to localStorage + backend sync) */\n  markMomentAchieved: (identifier: string) => void;\n  /**\n   * Internal: ref for track() call interception (used by AnalyticsEventBridge).\n   * The bridge registers a callback on mount to evaluate CUSTOM_EVENT and\n   * FEATURE_ACCESS signals when track() is called.\n   * @internal\n   */\n  _onTrackRef: React.MutableRefObject<((name: string, properties?: Record<string, unknown>) => void) | null>;\n}\n\n// ─── Context ────────────────────────────────────────────────────\n\n// Note: useAnalytics hook is in a separate file (useAnalytics.ts) for React Fast Refresh compatibility.\nexport const AnalyticsContext = createContext<AnalyticsContextValue | null>(null);\n\n// ─── Consent order for comparison ───────────────────────────────\n\nconst CONSENT_ORDER = [\n  DataProcessingConsent.NONE,\n  DataProcessingConsent.BASIC,\n  DataProcessingConsent.ANALYTICS,\n  DataProcessingConsent.MARKETING,\n  DataProcessingConsent.FULL,\n];\n\n// ─── Provider Registry (singleton) ──────────────────────────────\n\nconst providerRegistry = new AnalyticsProviderRegistry();\n\n// ─── Provider Component ─────────────────────────────────────────\n\nexport interface AnalyticsContextProviderProps {\n  children: React.ReactNode;\n  customProviders?: IAnalyticsProvider[];\n}\n\nexport const AnalyticsContextProvider: React.FC<AnalyticsContextProviderProps> = ({\n  children,\n  customProviders,\n}) => {\n  const appContext = useContext(ApplicationContext);\n  const { on } = useEventBus();\n  const providersRef = useRef<IAnalyticsProvider[]>([]);\n  const [isActive, setIsActive] = useState(false);\n\n  // Session start: captured once at mount\n  const sessionStartTimestamp = useRef(Date.now()).current;\n\n  // Resolve analytics config from ApplicationContext\n  const analyticsConfig = useMemo<AnalyticsConfig | undefined>(\n    () => appContext?.appConfig?.analytics,\n    [appContext?.appConfig?.analytics],\n  );\n\n  // ─── Consent gating ─────────────────────────────────────────\n\n  const [consent, setConsent] = useState<DataProcessingConsent>(DataProcessingConsent.NONE);\n\n  useEffect(() => {\n    return on(FrontendEvents.USER_PREFERENCES_CHANGED, (payload) => {\n      const newConsent = payload.privacy?.dataProcessingConsent;\n      if (newConsent) {\n        setConsent(newConsent);\n      }\n    });\n  }, [on]);\n\n  // Initialize/teardown providers based on config + consent\n  useEffect(() => {\n    if (!analyticsConfig?.enabled) {\n      setIsActive(false);\n      return;\n    }\n\n    const requiredConsent = analyticsConfig.requiredConsent ?? DataProcessingConsent.ANALYTICS;\n    const hasConsent = CONSENT_ORDER.indexOf(consent) >= CONSENT_ORDER.indexOf(requiredConsent);\n\n    if (!hasConsent) {\n      providersRef.current.forEach(p => p.reset());\n      setIsActive(false);\n      return;\n    }\n\n    let aborted = false;\n\n    const httpClient = getManualCallsHttpClient();\n    const builtInProviders = providerRegistry.resolveFromConfig(\n      analyticsConfig.providers ?? [],\n      httpClient,\n    );\n    const allProviders = [...builtInProviders, ...(customProviders ?? [])];\n\n    Promise.all(\n      allProviders.map(p =>\n        p.initialize(analyticsConfig.providers?.find(c => c.providerType === p.name)?.config).catch(err => {\n          console.warn(`[Analytics] Failed to initialize provider \"${p.name}\":`, err);\n        })\n      )\n    ).then(() => {\n      if (aborted) return;\n      providersRef.current = allProviders;\n      setIsActive(true);\n    });\n\n    return () => {\n      aborted = true;\n      allProviders.forEach(p => p.shutdown().catch(() => {}));\n      providersRef.current = [];\n    };\n  }, [analyticsConfig, consent, customProviders]);\n\n  // Identify user on login\n  useEffect(() => {\n    return on(FrontendEvents.USER_LOGIN, (payload) => {\n      providersRef.current.forEach(p =>\n        p.identify({ userId: payload.userId })\n      );\n    });\n  }, [on]);\n\n  // Reset on logout\n  useEffect(() => {\n    return on(FrontendEvents.USER_LOGOUT, () => {\n      providersRef.current.forEach(p => p.reset());\n    });\n  }, [on]);\n\n  // ─── Achieved moments persistence ─────────────────────────────\n\n  // userId is set by the USER_LOGIN event for scope-aware persistence.\n  const [loggedInUserId, setLoggedInUserId] = useState<string | null>(null);\n\n  useEffect(() => {\n    return on(FrontendEvents.USER_LOGIN, (payload) => {\n      setLoggedInUserId(payload.userId);\n    });\n  }, [on]);\n\n  useEffect(() => {\n    return on(FrontendEvents.USER_LOGOUT, () => {\n      setLoggedInUserId(null);\n    });\n  }, [on]);\n\n  const storageKey = useMemo(\n    () => loggedInUserId ? `${ANALYTICS_ACHIEVED_STORAGE_KEY_PREFIX}${loggedInUserId}` : null,\n    [loggedInUserId],\n  );\n\n  const [achievedMoments, setAchievedMoments] = useState<Set<string>>(new Set());\n\n  // Helper: persist to localStorage\n  const persistToStorage = useCallback((moments: Set<string>) => {\n    if (!storageKey) return;\n    try {\n      localStorage.setItem(storageKey, JSON.stringify([...moments]));\n    } catch {\n      /* quota exceeded — best effort */\n    }\n  }, [storageKey]);\n\n  // Load from localStorage on mount + fetch from backend if backendSync\n  useEffect(() => {\n    if (!analyticsConfig?.enabled || !storageKey) return;\n\n    // Load from localStorage\n    try {\n      const stored = localStorage.getItem(storageKey);\n      if (stored) {\n        setAchievedMoments(new Set(JSON.parse(stored)));\n      }\n    } catch {\n      /* corrupt storage — start fresh */\n    }\n\n    // Fetch from backend if backendSync enabled\n    if (analyticsConfig?.persistence?.backendSync) {\n      let aborted = false;\n      getManualCallsHttpClient()\n        .getAnalyticsMomentsAchieved()\n        .then((response: unknown) => {\n          if (aborted) return;\n          const res = response as { moments?: string[] };\n          if (res.moments) {\n            setAchievedMoments(prev => {\n              const merged = new Set([...prev, ...res.moments!]);\n              persistToStorage(merged);\n              return merged;\n            });\n          }\n        })\n        .catch(() => {\n          /* Backend unavailable — use localStorage only */\n        });\n\n      return () => { aborted = true; };\n    }\n  }, [analyticsConfig?.enabled, analyticsConfig?.persistence?.backendSync, storageKey, persistToStorage]);\n\n  // Subscribe to ANALYTICS_MOMENT_ACHIEVED events (backend-pushed via WS)\n  useEffect(() => {\n    return on(FrontendEvents.ANALYTICS_MOMENT_ACHIEVED, (payload) => {\n      setAchievedMoments(prev => {\n        const next = new Set(prev);\n        next.add(payload.momentIdentifier);\n        persistToStorage(next);\n        return next;\n      });\n    });\n  }, [on, persistToStorage]);\n\n  const markMomentAchieved = useCallback((identifier: string) => {\n    setAchievedMoments(prev => {\n      const next = new Set(prev);\n      next.add(identifier);\n      persistToStorage(next);\n      return next;\n    });\n    // Sync to backend if enabled\n    if (analyticsConfig?.persistence?.backendSync) {\n      getManualCallsHttpClient()\n        .postAnalyticsMomentsAchieved({ momentIdentifier: identifier })\n        .catch(() => {\n          /* Best-effort sync */\n        });\n    }\n  }, [analyticsConfig?.persistence?.backendSync, persistToStorage]);\n\n  // ─── Track interceptor ref ────────────────────────────────────\n\n  const onTrackRef = useRef<((name: string, properties?: Record<string, unknown>) => void) | null>(null);\n\n  const track = useCallback((name: string, properties?: Record<string, unknown>) => {\n    if (!isActive) return;\n    const event: AnalyticsEvent = { name, properties, timestamp: Date.now() };\n    providersRef.current.forEach(p => p.track(event));\n    // Forward to bridge interceptor for CUSTOM_EVENT / FEATURE_ACCESS signal evaluation\n    onTrackRef.current?.(name, properties);\n  }, [isActive]);\n\n  const page = useCallback((path: string, properties?: Record<string, unknown>) => {\n    if (!isActive) return;\n    providersRef.current.forEach(p => p.page(path, properties));\n  }, [isActive]);\n\n  // ─── Render ───────────────────────────────────────────────────\n\n  const contextValue = useMemo<AnalyticsContextValue>(() => ({\n    track,\n    page,\n    isActive,\n    sessionStartTimestamp,\n    achievedMoments,\n    markMomentAchieved,\n    _onTrackRef: onTrackRef,\n  }), [track, page, isActive, sessionStartTimestamp, achievedMoments, markMomentAchieved]);\n\n  return (\n    <AnalyticsContext.Provider value={contextValue}>\n      {isActive && analyticsConfig && (\n        <AnalyticsEventBridge\n          config={analyticsConfig.autoInstrumentation}\n          valueMoments={analyticsConfig.valueMoments} \n        />\n      )}\n      {children}\n    </AnalyticsContext.Provider>\n  );\n};\n"]}
+{"version":3,"file":"AnalyticsContext.js","sourceRoot":"","sources":["../../../../../src/core/monitoring/analytics/AnalyticsContext.tsx"],"names":[],"mappings":"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","sourcesContent":["/**\n * Analytics Context Provider\n * \n * Provides analytics tracking, value moment achievement persistence,\n * consent gating, and provider lifecycle management.\n */\n\nimport React, { createContext, useContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport { DataProcessingConsent, type AnalyticsConfig, ANALYTICS_ACHIEVED_STORAGE_KEY_PREFIX } from '@wildo-ai/saas-models';\nimport type { IAnalyticsProvider, AnalyticsEvent } from './analytics-provider.frontend.interface';\nimport { AnalyticsProviderRegistry } from './analytics-provider-registry.frontend.service';\nimport { ApplicationContext } from '~wildo-frontend-lib/core/runtime/ApplicationContext.shared';\nimport { useEventBus } from '~wildo-frontend-lib/core/events/useEventBus';\nimport { FrontendEvents } from '~wildo-frontend-lib/core/events/events.frontend.schemas';\nimport { getManualCallsHttpClient } from '~wildo-frontend-lib/core/requests/wildo-http-client-manual-calls.frontend.service';\nimport { AnalyticsEventBridge } from './AnalyticsEventBridge';\n\n// ─── Context Value Interface ────────────────────────────────────\n\nexport interface AnalyticsContextValue {\n  /** Track a custom event (app-custom usage) */\n  track: (name: string, properties?: Record<string, unknown>) => void;\n  /** Track a page view */\n  page: (path: string, properties?: Record<string, unknown>) => void;\n  /** Whether analytics is active (enabled + consent granted) */\n  isActive: boolean;\n  /** Session start timestamp (for TTFV computation) */\n  sessionStartTimestamp: number;\n  /** Set of achieved value moment identifiers (scope-aware, persisted) */\n  achievedMoments: Set<string>;\n  /** Mark a value moment as achieved (persists to localStorage + backend sync) */\n  markMomentAchieved: (identifier: string) => void;\n  /**\n   * Internal: ref for track() call interception (used by AnalyticsEventBridge).\n   * The bridge registers a callback on mount to evaluate CUSTOM_EVENT and\n   * FEATURE_ACCESS signals when track() is called.\n   * @internal\n   */\n  _onTrackRef: React.MutableRefObject<((name: string, properties?: Record<string, unknown>) => void) | null>;\n}\n\n// ─── Context ────────────────────────────────────────────────────\n\n// Note: useAnalytics hook is in a separate file (useAnalytics.ts) for React Fast Refresh compatibility.\nexport const AnalyticsContext = createContext<AnalyticsContextValue | null>(null);\n\n// ─── Consent order for comparison ───────────────────────────────\n\nconst CONSENT_ORDER = [\n  DataProcessingConsent.NONE,\n  DataProcessingConsent.BASIC,\n  DataProcessingConsent.ANALYTICS,\n  DataProcessingConsent.MARKETING,\n  DataProcessingConsent.FULL,\n];\n\n// ─── Provider Registry (singleton) ──────────────────────────────\n\nconst providerRegistry = new AnalyticsProviderRegistry();\n\n// ─── Provider Component ─────────────────────────────────────────\n\nexport interface AnalyticsContextProviderProps {\n  children: React.ReactNode;\n  customProviders?: IAnalyticsProvider[];\n}\n\nexport const AnalyticsContextProvider: React.FC<AnalyticsContextProviderProps> = ({\n  children,\n  customProviders,\n}) => {\n  const appContext = useContext(ApplicationContext);\n  const { on } = useEventBus();\n  const providersRef = useRef<IAnalyticsProvider[]>([]);\n  const [isActive, setIsActive] = useState(false);\n\n  // Session start: captured once at mount\n  const sessionStartTimestamp = useRef(Date.now()).current;\n\n  // Resolve analytics config from ApplicationContext\n  const analyticsConfig = useMemo<AnalyticsConfig | undefined>(\n    () => appContext?.appConfig?.analytics,\n    [appContext?.appConfig?.analytics],\n  );\n\n  // ─── Consent gating ─────────────────────────────────────────\n\n  const [consent, setConsent] = useState<DataProcessingConsent>(DataProcessingConsent.NONE);\n\n  useEffect(() => {\n    return on(FrontendEvents.USER_PREFERENCES_CHANGED, (payload) => {\n      const newConsent = payload.privacy?.dataProcessingConsent;\n      if (newConsent) {\n        setConsent(newConsent);\n      }\n    });\n  }, [on]);\n\n  // Initialize/teardown providers based on config + consent\n  useEffect(() => {\n    if (!analyticsConfig?.enabled) {\n      setIsActive(false);\n      return;\n    }\n\n    const requiredConsent = analyticsConfig.requiredConsent ?? DataProcessingConsent.ANALYTICS;\n    const hasConsent = CONSENT_ORDER.indexOf(consent) >= CONSENT_ORDER.indexOf(requiredConsent);\n\n    if (!hasConsent) {\n      providersRef.current.forEach(p => p.reset());\n      setIsActive(false);\n      return;\n    }\n\n    let aborted = false;\n\n    const httpClient = getManualCallsHttpClient();\n    const builtInProviders = providerRegistry.resolveFromConfig(\n      analyticsConfig.providers ?? [],\n      httpClient,\n    );\n    const allProviders = [...builtInProviders, ...(customProviders ?? [])];\n\n    Promise.all(\n      allProviders.map(p =>\n        p.initialize(analyticsConfig.providers?.find(c => c.providerType === p.name)?.config).catch(err => {\n          console.warn(`[Analytics] Failed to initialize provider \"${p.name}\":`, err);\n        })\n      )\n    ).then(() => {\n      if (aborted) return;\n      providersRef.current = allProviders;\n      setIsActive(true);\n    });\n\n    return () => {\n      aborted = true;\n      allProviders.forEach(p => p.shutdown().catch(() => {}));\n      providersRef.current = [];\n    };\n  }, [analyticsConfig, consent, customProviders]);\n\n  // Identify user on login\n  useEffect(() => {\n    return on(FrontendEvents.USER_LOGIN, (payload) => {\n      providersRef.current.forEach(p =>\n        p.identify({ userId: payload.userId })\n      );\n    });\n  }, [on]);\n\n  // Reset on logout\n  useEffect(() => {\n    return on(FrontendEvents.USER_LOGOUT, () => {\n      providersRef.current.forEach(p => p.reset());\n    });\n  }, [on]);\n\n  // ─── Achieved moments persistence ─────────────────────────────\n\n  // userId is set by the USER_LOGIN event for scope-aware persistence.\n  const [loggedInUserId, setLoggedInUserId] = useState<string | null>(null);\n\n  useEffect(() => {\n    return on(FrontendEvents.USER_LOGIN, (payload) => {\n      setLoggedInUserId(payload.userId);\n    });\n  }, [on]);\n\n  useEffect(() => {\n    return on(FrontendEvents.USER_LOGOUT, () => {\n      setLoggedInUserId(null);\n    });\n  }, [on]);\n\n  const storageKey = useMemo(\n    () => loggedInUserId ? `${ANALYTICS_ACHIEVED_STORAGE_KEY_PREFIX}${loggedInUserId}` : null,\n    [loggedInUserId],\n  );\n\n  const [achievedMoments, setAchievedMoments] = useState<Set<string>>(new Set());\n\n  // Helper: persist to localStorage\n  const persistToStorage = useCallback((moments: Set<string>) => {\n    if (!storageKey) return;\n    try {\n      localStorage.setItem(storageKey, JSON.stringify([...moments]));\n    } catch {\n      /* quota exceeded — best effort */\n    }\n  }, [storageKey]);\n\n  // Load from localStorage on mount + fetch from backend if backendSync\n  useEffect(() => {\n    if (!analyticsConfig?.enabled || !storageKey) return;\n\n    // Load from localStorage\n    try {\n      const stored = localStorage.getItem(storageKey);\n      if (stored) {\n        setAchievedMoments(new Set(JSON.parse(stored)));\n      }\n    } catch {\n      /* corrupt storage — start fresh */\n    }\n\n    // Fetch from backend if backendSync enabled\n    if (analyticsConfig?.persistence?.backendSync) {\n      let aborted = false;\n      getManualCallsHttpClient()\n        .getAnalyticsMomentsAchieved()\n        .then((response: unknown) => {\n          if (aborted) return;\n          const res = response as { moments?: string[] };\n          if (res.moments) {\n            setAchievedMoments(prev => {\n              const merged = new Set([...prev, ...res.moments!]);\n              persistToStorage(merged);\n              return merged;\n            });\n          }\n        })\n        .catch(() => {\n          /* Backend unavailable — use localStorage only */\n        });\n\n      return () => { aborted = true; };\n    }\n  }, [analyticsConfig?.enabled, analyticsConfig?.persistence?.backendSync, storageKey, persistToStorage]);\n\n  // Subscribe to ANALYTICS_MOMENT_ACHIEVED events (backend-pushed via WS)\n  useEffect(() => {\n    return on(FrontendEvents.ANALYTICS_MOMENT_ACHIEVED, (payload) => {\n      setAchievedMoments(prev => {\n        const next = new Set(prev);\n        next.add(payload.momentIdentifier);\n        persistToStorage(next);\n        return next;\n      });\n    });\n  }, [on, persistToStorage]);\n\n  const markMomentAchieved = useCallback((identifier: string) => {\n    setAchievedMoments(prev => {\n      const next = new Set(prev);\n      next.add(identifier);\n      persistToStorage(next);\n      return next;\n    });\n    // Sync to backend if enabled\n    if (analyticsConfig?.persistence?.backendSync) {\n      getManualCallsHttpClient()\n        .postAnalyticsMomentsAchieved({ momentIdentifier: identifier })\n        .catch(() => {\n          /* Best-effort sync */\n        });\n    }\n  }, [analyticsConfig?.persistence?.backendSync, persistToStorage]);\n\n  // ─── Track interceptor ref ────────────────────────────────────\n\n  const onTrackRef = useRef<((name: string, properties?: Record<string, unknown>) => void) | null>(null);\n\n  const track = useCallback((name: string, properties?: Record<string, unknown>) => {\n    if (!isActive) return;\n    const event: AnalyticsEvent = { name, properties, timestamp: Date.now() };\n    providersRef.current.forEach(p => p.track(event));\n    // Forward to bridge interceptor for CUSTOM_EVENT / FEATURE_ACCESS signal evaluation\n    onTrackRef.current?.(name, properties);\n  }, [isActive]);\n\n  const page = useCallback((path: string, properties?: Record<string, unknown>) => {\n    if (!isActive) return;\n    providersRef.current.forEach(p => p.page(path, properties));\n  }, [isActive]);\n\n  // ─── Render ───────────────────────────────────────────────────\n\n  const contextValue = useMemo<AnalyticsContextValue>(() => ({\n    track,\n    page,\n    isActive,\n    sessionStartTimestamp,\n    achievedMoments,\n    markMomentAchieved,\n    _onTrackRef: onTrackRef,\n  }), [track, page, isActive, sessionStartTimestamp, achievedMoments, markMomentAchieved]);\n\n  return (\n    <AnalyticsContext.Provider value={contextValue}>\n      {isActive && analyticsConfig && (\n        <AnalyticsEventBridge\n          config={analyticsConfig.autoInstrumentation}\n          valueMoments={analyticsConfig.valueMoments} \n        />\n      )}\n      {children}\n    </AnalyticsContext.Provider>\n  );\n};\n"]}

package/dist/esm/core/monitoring/analytics/AnalyticsEventBridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsEventBridge.d.ts","sourceRoot":"","sources":["../../../../../../src/core/monitoring/analytics/AnalyticsEventBridge.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAkD,MAAM,OAAO,CAAC;AACvE,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,WAAW,EAajB,MAAM,uBAAuB,CAAC;AAQ/B,UAAU,yBAAyB;IACjC,MAAM,CAAC,EAAE,eAAe,CAAC,qBAAqB,CAAC,CAAC;IAChD,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;CAC9B;AAID,eAAO,MAAM,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,yBAAyB,CAmcpE,CAAC"}
+{"version":3,"file":"AnalyticsEventBridge.d.ts","sourceRoot":"","sources":["../../../../../src/core/monitoring/analytics/AnalyticsEventBridge.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAkD,MAAM,OAAO,CAAC;AACvE,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,WAAW,EAajB,MAAM,uBAAuB,CAAC;AAQ/B,UAAU,yBAAyB;IACjC,MAAM,CAAC,EAAE,eAAe,CAAC,qBAAqB,CAAC,CAAC;IAChD,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;CAC9B;AAID,eAAO,MAAM,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,yBAAyB,CAmcpE,CAAC"}