@umituz/web-dashboard 5.0.1 → 6.1.0

package/src/domains/onboarding/theme/tokens.ts

@@ -0,0 +1,122 @@
+/**
+ * Design Tokens - Single Source of Truth
+ * All visual values MUST be sourced from here.
+ * Per project rules: no hardcoded colors, spacing, or font sizes anywhere else.
+ */
+
+export const spacing = {
+  px: '1px',
+  0: '0',
+  0.5: '0.125rem',
+  1: '0.25rem',
+  1.5: '0.375rem',
+  2: '0.5rem',
+  2.5: '0.625rem',
+  3: '0.75rem',
+  3.5: '0.875rem',
+  4: '1rem',
+  5: '1.25rem',
+  6: '1.5rem',
+  7: '1.75rem',
+  8: '2rem',
+  10: '2.5rem',
+  12: '3rem',
+  16: '4rem',
+  20: '5rem',
+  24: '6rem',
+  32: '8rem',
+} as const;
+
+export const radius = {
+  none: '0',
+  sm: '0.25rem',
+  md: '0.5rem',
+  lg: '0.75rem',
+  xl: '1rem',
+  '2xl': '1.5rem',
+  '3xl': '2rem',
+  full: '9999px',
+} as const;
+
+export const typography = {
+  fontFamily: {
+    sans: 'var(--uob-font-sans, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif)',
+  },
+  fontSize: {
+    xs: ['0.75rem', { lineHeight: '1rem' }],
+    sm: ['0.875rem', { lineHeight: '1.25rem' }],
+    base: ['1rem', { lineHeight: '1.5rem' }],
+    lg: ['1.125rem', { lineHeight: '1.75rem' }],
+    xl: ['1.25rem', { lineHeight: '1.75rem' }],
+    '2xl': ['1.5rem', { lineHeight: '2rem' }],
+    '3xl': ['1.875rem', { lineHeight: '2.25rem' }],
+    '4xl': ['2.25rem', { lineHeight: '2.5rem' }],
+    '5xl': ['3rem', { lineHeight: '1.15' }],
+    '6xl': ['3.75rem', { lineHeight: '1.1' }],
+  },
+  fontWeight: {
+    normal: '400',
+    medium: '500',
+    semibold: '600',
+    bold: '700',
+  },
+} as const;
+
+export const zIndex = {
+  hide: -1,
+  base: 0,
+  raised: 10,
+  sticky: 20,
+  overlay: 30,
+  modal: 40,
+  toast: 50,
+} as const;
+
+export const motion = {
+  duration: {
+    fast: '150ms',
+    normal: '250ms',
+    slow: '400ms',
+    slower: '600ms',
+  },
+  easing: {
+    linear: 'linear',
+    in: 'cubic-bezier(0.4, 0, 1, 1)',
+    out: 'cubic-bezier(0, 0, 0.2, 1)',
+    inOut: 'cubic-bezier(0.4, 0, 0.2, 1)',
+  },
+} as const;
+
+export const breakpoint = {
+  sm: '640px',
+  md: '768px',
+  lg: '1024px',
+  xl: '1280px',
+  '2xl': '1536px',
+} as const;
+
+/**
+ * Semantic color tokens — referenced via CSS custom properties.
+ * Consumers override --uob-primary-500 etc. on `.uob-flow` to rebrand
+ * without code changes. Values are space-separated RGB triplets so they
+ * compose with `rgb(var(--x) / <alpha>)`.
+ */
+export const colorCssVar = {
+  primary50: 'var(--uob-primary-50, 238 242 255)',
+  primary100: 'var(--uob-primary-100, 224 231 255)',
+  primary500: 'var(--uob-primary-500, 99 102 241)',
+  primary600: 'var(--uob-primary-600, 79 70 229)',
+  primary700: 'var(--uob-primary-700, 67 56 202)',
+  surface: 'var(--uob-surface, 255 255 255)',
+  surfaceMuted: 'var(--uob-surface-muted, 249 250 251)',
+  textPrimary: 'var(--uob-text-primary, 17 24 39)',
+  textMuted: 'var(--uob-text-muted, 107 114 128)',
+  border: 'var(--uob-border, 229 231 235)',
+  success: 'var(--uob-success, 16 185 129)',
+  warning: 'var(--uob-warning, 245 158 11)',
+  error: 'var(--uob-error, 239 68 68)',
+} as const;
+
+export type SpacingToken = keyof typeof spacing;
+export type RadiusToken = keyof typeof radius;
+export type FontSizeToken = keyof typeof typography.fontSize;

package/src/domains/onboarding/types/config.ts

@@ -0,0 +1,68 @@
+import type { ReactNode } from 'react';
+import type { DemoConfig, OnboardingScreen, PaywallScreenConfig } from './screens';
+import type { OnboardingLabels } from './labels';
+
+export type { OnboardingLabels } from './labels';
+
+export type OnboardingCategory =
+  | 'health'
+  | 'art'
+  | 'video'
+  | 'security'
+  | 'education'
+  | 'platform'
+  | 'lifestyle';
+
+export type AnalyticsProvider = 'google-analytics' | 'amplitude' | 'mixpanel' | 'custom';
+
+export interface AnalyticsConfig {
+  trackEvents: boolean;
+  provider?: AnalyticsProvider;
+  /** Custom event sink used when provider === 'custom'. */
+  customTracker?: (event: OnboardingAnalyticsEvent) => void;
+}
+
+export type OnboardingAnalyticsEvent =
+  | { name: 'onboarding_started'; category: OnboardingCategory; timestamp: number }
+  | { name: 'onboarding_step_completed'; stepId: string; stepType: string; index: number; timestamp: number }
+  | { name: 'onboarding_step_skipped'; stepId: string; index: number; timestamp: number }
+  | { name: 'onboarding_completed'; durationMs: number; timestamp: number }
+  | { name: 'onboarding_abandoned'; lastStepId: string; durationMs: number; timestamp: number }
+  | { name: 'paywall_viewed'; stepId: string; timestamp: number }
+  | { name: 'paywall_accepted'; stepId: string; price: string; timestamp: number }
+  | { name: 'paywall_declined'; stepId: string; timestamp: number }
+  | { name: 'permission_requested'; permission: string; stepId: string; timestamp: number }
+  | { name: 'permission_granted'; permission: string; stepId: string; timestamp: number }
+  | { name: 'permission_denied'; permission: string; stepId: string; timestamp: number };
+
+export interface OnboardingConfig {
+  category: OnboardingCategory;
+  screens: ReadonlyArray<OnboardingScreen>;
+  demo?: DemoConfig;
+  paywall?: PaywallScreenConfig;
+  analytics?: AnalyticsConfig;
+  /**
+   * Override any user-facing string the library renders. English defaults
+   * apply to keys you omit. See `OnboardingLabels`.
+   */
+  labels?: Partial<OnboardingLabels>;
+  /** BCP-47 locale used for locale-aware formatting (e.g. "250.000" vs "250,000"). */
+  locale?: string;
+  /** Custom slot rendered above the flow (e.g. brand banner). */
+  headerSlot?: ReactNode;
+  /** Custom slot rendered below the flow. */
+  footerSlot?: ReactNode;
+  onComplete?: (data: OnboardingResult) => void;
+  onSkip?: () => void;
+  /** Persistence key — defaults to '@umituz/web-onboarding:progress'. */
+  storageKey?: string;
+}
+
+/** Collected data exposed to onComplete. Typed in place of `Record<string, any>`. */
+export interface OnboardingResult {
+  completedSteps: ReadonlyArray<string>;
+  /** Per-screen data captured during the run. */
+  collected: Record<string, unknown>;
+  durationMs: number;
+  finishedAt: Date;
+}

package/src/domains/onboarding/types/index.ts

@@ -0,0 +1,10 @@
+export type { OnboardingScreen, OnboardingScreenType, OnboardingOption } from './screens';
+export type {
+  OnboardingConfig,
+  OnboardingCategory,
+  AnalyticsConfig,
+  AnalyticsProvider,
+  OnboardingAnalyticsEvent,
+  OnboardingResult,
+  OnboardingLabels,
+} from './config';

package/src/domains/onboarding/types/labels.ts

@@ -0,0 +1,83 @@
+/**
+ * Every user-facing string the library renders lives here as an overridable
+ * label. Applications serving non-English markets pass a `labels` subset (and
+ * optionally a `locale`) via `OnboardingConfig`; anything not overridden falls
+ * back to the English defaults.
+ *
+ * Labels are flat, serializable strings — no functions — so they can be fed
+ * straight from any translation system (i18next, Lingui, a CMS, …).
+ * Pattern labels use `{placeholder}` interpolation, e.g. `"Step {current} of {total}"`.
+ */
+export interface OnboardingLabels {
+  /** Default CTA label when a screen defines no `cta`. */
+  continueAction: string;
+  /** Footer back affordance. */
+  back: string;
+  /** Footer skip affordance (the `skipLabel` prop takes precedence). */
+  skip: string;
+  /** Primary button label while `loading` is true. */
+  loading: string;
+  /** Progress bar label. `{current}`/`{total}` are interpolated. */
+  stepOfPattern: string;
+  /** Card counter label. `{current}`/`{total}` are interpolated. */
+  countOfPattern: string;
+
+  /** Question screens */
+  selectAllThatApply: string;
+  selectOne: string;
+  /** Multi-select hint with a cap. `{max}` is interpolated. */
+  pickUpToPattern: string;
+  /** Single-select hint for the pain-points screen. */
+  pickTheOne: string;
+  /** Preferences screen subtitle. */
+  tailorExperience: string;
+
+  /** Swipe / tinder screens */
+  agree: string;
+  disagree: string;
+  /** How to operate the swipe card (gesture + keyboard). */
+  swipeHint: string;
+  /** Shown when every card has been decided. */
+  allDone: string;
+
+  /** Comparison screen column headings */
+  withoutUs: string;
+  withUs: string;
+
+  /** Social proof carousel controls */
+  previous: string;
+  nextAction: string;
+
+  /** App demo screen CTA. */
+  continueWithResult: string;
+
+  /** Permission priming */
+  allowAccess: string;
+  permissionRequestFailed: string;
+
+  /** Account gate */
+  continueWithEmail: string;
+  continueWithGoogle: string;
+  continueWithApple: string;
+  continueWithGitHub: string;
+  skipForNow: string;
+  signInFailed: string;
+
+  /** Paywall */
+  couldNotStartTrial: string;
+  /** `{count}` interpolated, e.g. "7-day free trial". */
+  trialDaysPattern: string;
+  /** `{price}`/`{days}` interpolated, e.g. "$0.99 for the first 7 days". */
+  trialIntroPattern: string;
+  /** Reassurance line under the paywall CAs. */
+  cancelAnytimeNote: string;
+
+  /** Value delivery sharing */
+  share: string;
+  copied: string;
+
+  /** Error boundary default UI */
+  somethingWentWrong: string;
+  unexpectedError: string;
+  tryAgain: string;
+}

package/src/domains/onboarding/types/screens.ts

@@ -0,0 +1,193 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Discriminated union: every screen is one of 14 strictly-typed shapes.
+ * Eliminates `Record<string, any>` masking (project rule: no `any`).
+ */
+
+export interface BaseScreen<T extends string, D = unknown> {
+  id: string;
+  type: T;
+  title?: string;
+  subtitle?: string;
+  cta?: string;
+  onCta?: () => void;
+  data?: D;
+}
+
+export interface OnboardingOption {
+  id: string;
+  label: string;
+  description?: string;
+  iconName?: string; // lucide-react icon name; resolved by UI layer
+  image?: string;
+}
+
+export type WelcomeScreenConfig = BaseScreen<'welcome'> & {
+  heroIconName?: string;
+  highlight?: string;
+};
+
+export type GoalQuestionScreenConfig = BaseScreen<'goal-question', string[]> & {
+  question: string;
+  options: OnboardingOption[];
+  multiSelect?: boolean;
+  onChange: (selectedIds: string[]) => void;
+};
+
+export type PainPointsScreenConfig = BaseScreen<'pain-points', string[]> & {
+  title: string;
+  painPoints: OnboardingOption[];
+  multiSelect?: boolean;
+  maxSelect?: number;
+  onChange: (selectedIds: string[]) => void;
+};
+
+export type SocialProofScreenConfig = BaseScreen<'social-proof'> & {
+  testimonials: ReadonlyArray<{
+    name: string;
+    role: string;
+    content: string;
+    avatar?: string;
+    rating?: number;
+  }>;
+};
+
+export type TinderCardsScreenConfig = BaseScreen<'tinder-cards', string[]> & {
+  statements: ReadonlyArray<{
+    id: string;
+    text: string;
+    category: string;
+  }>;
+  onChange: (likedIds: string[]) => void;
+};
+
+export type PersonalizedSolutionScreenConfig = BaseScreen<'personalized-solution'> & {
+  solutions: ReadonlyArray<{
+    painPointId: string;
+    solution: string;
+    statistic?: string;
+  }>;
+  selectedPainPointIds: ReadonlyArray<string>;
+};
+
+export type ComparisonScreenConfig = BaseScreen<'comparison'> & {
+  before: ReadonlyArray<string>;
+  after: ReadonlyArray<string>;
+};
+
+export type PreferenceItem = {
+  id: string;
+  label: string;
+  type: 'select' | 'multi-select' | 'toggle' | 'slider';
+  options?: OnboardingOption[];
+  min?: number;
+  max?: number;
+  defaultValue?: string | number | string[] | boolean;
+};
+
+export type PreferencesScreenConfig = BaseScreen<
+  'preferences',
+  Record<string, string | number | string[] | boolean>
+> & {
+  title: string;
+  preferences: ReadonlyArray<PreferenceItem>;
+  onChange: (values: Record<string, string | number | string[] | boolean>) => void;
+};
+
+export type PermissionType = 'camera' | 'microphone' | 'location' | 'notifications' | 'photos' | 'contacts';
+
+export type PermissionPrimingScreenConfig = BaseScreen<'permission-priming', PermissionStatus> & {
+  permission: PermissionType;
+  description: string;
+  benefits: ReadonlyArray<string>;
+  iconName?: string;
+  onRequest: () => Promise<PermissionStatus>;
+};
+
+export type PermissionStatus = 'granted' | 'denied' | 'prompt' | 'unsupported';
+
+export type ProcessingScreenConfig = BaseScreen<'processing'> & {
+  title: string;
+  steps: ReadonlyArray<string>;
+  durationMs?: number;
+  onComplete: () => void;
+};
+
+export type DemoConfig<TProps = Record<string, unknown>, TResult = unknown> = {
+  component: React.ComponentType<TProps>;
+  props?: TProps;
+  onSave: (result: TResult) => void;
+  durationMs?: number;
+};
+
+export type AppDemoScreenConfig = BaseScreen<'app-demo', unknown> & {
+  demo: DemoConfig;
+};
+
+export type ValueDeliveryScreenConfig<TResult = unknown> = BaseScreen<
+  'value-delivery',
+  TResult
+> & {
+  title: string;
+  result: TResult;
+  /** Optional share affordance. Uses the Web Share API with a clipboard fallback. */
+  shareConfig?: {
+    text: string;
+    url?: string;
+  };
+};
+
+export type SignInMethod = 'email' | 'google' | 'apple' | 'github';
+
+export type AccountGateScreenConfig = BaseScreen<'account-gate', { signedIn: boolean; method?: SignInMethod }> & {
+  optional: boolean;
+  signInMethod?: SignInMethod;
+  skipText?: string;
+  onSignIn: (method: SignInMethod) => Promise<{ signedIn: boolean; method?: SignInMethod }>;
+};
+
+export type PaywallFeature = {
+  iconName: string; // lucide-react
+  text: string;
+  highlighted?: boolean;
+};
+
+export type PaywallScreenConfig = BaseScreen<
+  'paywall',
+  { accepted: boolean; trialStarted: boolean }
+> & {
+  subtitle: string;
+  price: string;
+  trialDays: number;
+  trialPrice?: string;
+  features: ReadonlyArray<PaywallFeature>;
+  socialProof?: {
+    text: string;
+    count: number;
+  };
+  cta: string;
+  secondaryCta?: string;
+  onSecondaryCta?: () => void;
+  onAccept: () => Promise<{ accepted: boolean; trialStarted: boolean }>;
+};
+
+export type OnboardingScreen =
+  | WelcomeScreenConfig
+  | GoalQuestionScreenConfig
+  | PainPointsScreenConfig
+  | SocialProofScreenConfig
+  | TinderCardsScreenConfig
+  | PersonalizedSolutionScreenConfig
+  | ComparisonScreenConfig
+  | PreferencesScreenConfig
+  | PermissionPrimingScreenConfig
+  | ProcessingScreenConfig
+  | AppDemoScreenConfig
+  | ValueDeliveryScreenConfig
+  | AccountGateScreenConfig
+  | PaywallScreenConfig;
+
+export type OnboardingScreenType = OnboardingScreen['type'];
+
+export type { ReactNode };

package/src/domains/onboarding/utils/analytics-dispatch.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { dispatchAnalyticsEvent, trackOnboardingEvent } from './analytics-dispatch';
+import type { OnboardingAnalyticsEvent } from '../types/config';
+
+const event: OnboardingAnalyticsEvent = {
+  name: 'onboarding_started',
+  category: 'health',
+  timestamp: 0,
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  delete (window as { gtag?: unknown }).gtag;
+  delete (window as { amplitude?: unknown }).amplitude;
+  delete (window as { mixpanel?: unknown }).mixpanel;
+});
+
+describe('analytics-dispatch — the "never throws" contract', () => {
+  it('routes to the custom tracker when provided', () => {
+    const tracker = vi.fn();
+    dispatchAnalyticsEvent(event, 'custom', tracker);
+    expect(tracker).toHaveBeenCalledExactlyOnceWith(event);
+  });
+
+  it('warns and drops (instead of throwing) for custom without a tracker', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    expect(() => dispatchAnalyticsEvent(event, 'custom', undefined)).not.toThrow();
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toContain('customTracker');
+  });
+
+  it('never throws when the custom tracker itself throws', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const tracker = () => {
+      throw new Error('tracker outage');
+    };
+    expect(() => dispatchAnalyticsEvent(event, 'custom', tracker)).not.toThrow();
+    expect(error).toHaveBeenCalledTimes(1);
+    expect(error.mock.calls[0][0]).toContain('dropped');
+  });
+
+  it('is a no-op without a provider', () => {
+    const tracker = vi.fn();
+    expect(() => dispatchAnalyticsEvent(event, undefined, tracker)).not.toThrow();
+    expect(tracker).not.toHaveBeenCalled();
+  });
+});
+
+describe('analytics-dispatch — provider routing', () => {
+  it('dispatches to gtag for google-analytics', () => {
+    const gtag = vi.fn();
+    (window as { gtag?: unknown }).gtag = gtag;
+    dispatchAnalyticsEvent(event, 'google-analytics', undefined);
+    expect(gtag).toHaveBeenCalledExactlyOnceWith('event', 'onboarding_started', event);
+  });
+
+  it('dispatches to amplitude via getInstance().logEvent', () => {
+    const logEvent = vi.fn();
+    (window as { amplitude?: unknown }).amplitude = {
+      getInstance: () => ({ logEvent }),
+    };
+    dispatchAnalyticsEvent(event, 'amplitude', undefined);
+    expect(logEvent).toHaveBeenCalledExactlyOnceWith('onboarding_started', event);
+  });
+
+  it('dispatches to mixpanel.track', () => {
+    const track = vi.fn();
+    (window as { mixpanel?: unknown }).mixpanel = { track };
+    dispatchAnalyticsEvent(event, 'mixpanel', undefined);
+    expect(track).toHaveBeenCalledExactlyOnceWith('onboarding_started', event);
+  });
+
+  it('survives a provider global that throws', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    (window as { gtag?: unknown }).gtag = () => {
+      throw new Error('gtag exploded');
+    };
+    expect(() => dispatchAnalyticsEvent(event, 'google-analytics', undefined)).not.toThrow();
+    expect(error).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('trackOnboardingEvent', () => {
+  it('forwards provider + tracker options', () => {
+    const tracker = vi.fn();
+    trackOnboardingEvent(event, { provider: 'custom', customTracker: tracker });
+    expect(tracker).toHaveBeenCalledExactlyOnceWith(event);
+  });
+
+  it('defaults to a silent no-op', () => {
+    expect(() => trackOnboardingEvent(event)).not.toThrow();
+  });
+});

package/src/domains/onboarding/utils/analytics-dispatch.ts

@@ -0,0 +1,92 @@
+/**
+ * Analytics dispatch service.
+ * Routes a typed onboarding event to the configured provider.
+ * Provider-specific dispatch is isolated here; callers stay provider-agnostic.
+ *
+ * Contract: dispatch NEVER throws. Analytics is an observation channel — a
+ * broken tracker must not take down the onboarding funnel. Failures are
+ * surfaced to the console (the library's documented error channel) and
+ * dropped.
+ */
+
+import type {
+  AnalyticsProvider,
+  OnboardingAnalyticsEvent,
+} from '../types/config';
+
+/** Provider globals are read through a LOCAL view of `window` — this package
+ * must never augment the global `Window` type for its consumers. */
+type AnalyticsWindow = Window & {
+  gtag?: (...args: unknown[]) => void;
+  amplitude?: {
+    getInstance: () => { logEvent: (name: string, props: Record<string, unknown>) => void };
+  };
+  mixpanel?: { track: (name: string, props: Record<string, unknown>) => void };
+};
+
+function dispatchToProvider(event: OnboardingAnalyticsEvent, provider: AnalyticsProvider): void {
+  if (typeof window === 'undefined') return; // SSR / non-browser: nothing to do.
+  const win = window as AnalyticsWindow;
+  switch (provider) {
+    case 'google-analytics':
+      win.gtag?.('event', event.name, event as unknown as Record<string, unknown>);
+      return;
+    case 'amplitude': {
+      const amp = win.amplitude?.getInstance();
+      amp?.logEvent(event.name, event as unknown as Record<string, unknown>);
+      return;
+    }
+    case 'mixpanel':
+      win.mixpanel?.track(event.name, event as unknown as Record<string, unknown>);
+      return;
+    case 'custom':
+      return; // Handled by the caller via the customTracker path.
+  }
+}
+
+function dispatchToCustomTracker(
+  event: OnboardingAnalyticsEvent,
+  customTracker: ((e: OnboardingAnalyticsEvent) => void) | undefined,
+): void {
+  if (typeof customTracker !== 'function') {
+     
+    console.warn(
+      '[web-onboarding] analytics provider is "custom" but no customTracker was provided; event dropped:',
+      event.name,
+    );
+    return;
+  }
+  customTracker(event);
+}
+
+/**
+ * Routes an event to the configured provider. Never throws: provider failures
+ * are logged and dropped so an analytics outage cannot break the flow UI.
+ */
+export function dispatchAnalyticsEvent(
+  event: OnboardingAnalyticsEvent,
+  provider: AnalyticsProvider | undefined,
+  customTracker: ((e: OnboardingAnalyticsEvent) => void) | undefined,
+): void {
+  try {
+    if (provider === 'custom') {
+      dispatchToCustomTracker(event, customTracker);
+      return;
+    }
+    if (!provider) return;
+    dispatchToProvider(event, provider);
+  } catch (error) {
+     
+    console.error('[web-onboarding] analytics dispatch failed; event dropped:', event.name, error);
+  }
+}
+
+export function trackOnboardingEvent(
+  event: OnboardingAnalyticsEvent,
+  options: {
+    provider?: AnalyticsProvider;
+    customTracker?: (e: OnboardingAnalyticsEvent) => void;
+  } = {},
+): void {
+  dispatchAnalyticsEvent(event, options.provider, options.customTracker);
+}

package/src/domains/onboarding/utils/default-storage-key.ts

@@ -0,0 +1,2 @@
+/** Default localStorage key for onboarding progress. */
+export const defaultStorageKey = '@umituz/web-onboarding:progress';

package/src/domains/onboarding/utils/index.ts

@@ -0,0 +1,13 @@
+export { trackOnboardingEvent, dispatchAnalyticsEvent } from './analytics-dispatch';
+export {
+  saveOnboardingProgress,
+  loadOnboardingProgress,
+  clearOnboardingProgress,
+  buildOnboardingResult,
+} from './local-storage-bridge';
+export type { RehydratedProgress } from './local-storage-bridge';
+export { queryPermissionStatus, requestPermission } from './permission-bridge';
+export { defaultStorageKey } from './default-storage-key';
+
+// Re-export validation for convenience (the public API treats validation as a util).
+export { checkFlowStructure, checkScreenConfig, checkStoredProgress } from '../validation';