@umituz/web-dashboard 6.0.0 → 6.2.0

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,73 @@
+import type {
+  AnalyticsProvider,
+  OnboardingAnalyticsEvent,
+} from '../types/config';
+
+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;   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;   }
+}
+
+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);
+}
+
+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 @@
+export const defaultStorageKey = '@umituz/web-onboarding:progress';

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

@@ -0,0 +1,12 @@
+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';
+
+export { checkFlowStructure, checkScreenConfig, checkStoredProgress } from '../validation';

package/src/domains/onboarding/utils/local-storage-bridge.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  buildOnboardingResult,
+  clearOnboardingProgress,
+  loadOnboardingProgress,
+  saveOnboardingProgress,
+} from './local-storage-bridge';
+import { defaultStorageKey } from './default-storage-key';
+
+beforeEach(() => {
+  window.localStorage.clear();
+});
+
+describe('local-storage-bridge round-trip', () => {
+  it('saves and loads progress under the default key', () => {
+    const startedAt = new Date('2026-01-01T10:00:00.000Z');
+    const ok = saveOnboardingProgress(undefined, {
+      currentStep: 2,
+      completedSteps: ['a', 'b'],
+      collected: { a: { selected: ['x'] } },
+      startedAt,
+      lastUpdated: new Date('2026-01-01T10:01:00.000Z'),
+    });
+    expect(ok).toBe(true);
+    expect(localStorage.getItem(defaultStorageKey)).toContain('"version":1');
+
+    const restored = loadOnboardingProgress(undefined);
+    expect(restored).not.toBeNull();
+    expect(restored?.currentStep).toBe(2);
+    expect(restored?.completedSteps).toEqual(['a', 'b']);
+    expect(restored?.collected).toEqual({ a: { selected: ['x'] } });
+    expect(restored?.startedAt.toISOString()).toBe('2026-01-01T10:00:00.000Z');
+  });
+
+  it('honors a custom storage key without touching the default one', () => {
+    saveOnboardingProgress('my-app:onboarding', {
+      currentStep: 1,
+      completedSteps: ['a'],
+      collected: {},
+      startedAt: new Date(),
+      lastUpdated: new Date(),
+    });
+    expect(localStorage.getItem('my-app:onboarding')).not.toBeNull();
+    expect(localStorage.getItem(defaultStorageKey)).toBeNull();
+  });
+
+  it('returns null and discards corrupt payloads so future saves start clean', () => {
+    localStorage.setItem(defaultStorageKey, '{corrupt');
+    expect(loadOnboardingProgress(undefined)).toBeNull();
+    expect(localStorage.getItem(defaultStorageKey)).toBeNull();
+  });
+
+  it('returns null when nothing is stored', () => {
+    expect(loadOnboardingProgress(undefined)).toBeNull();
+  });
+
+  it('clears the stored payload safely', () => {
+    saveOnboardingProgress(undefined, {
+      currentStep: 0,
+      completedSteps: [],
+      collected: {},
+      startedAt: new Date(),
+      lastUpdated: new Date(),
+    });
+    clearOnboardingProgress(undefined);
+    expect(localStorage.getItem(defaultStorageKey)).toBeNull();
+    expect(() => clearOnboardingProgress(undefined)).not.toThrow();
+  });
+});
+
+describe('buildOnboardingResult', () => {
+  it('computes the duration from start to finish', () => {
+    const result = buildOnboardingResult({
+      completedSteps: ['a', 'b'],
+      collected: { a: 1 },
+      startedAt: new Date('2026-01-01T10:00:00.000Z'),
+      finishedAt: new Date('2026-01-01T10:02:30.000Z'),
+    });
+    expect(result.durationMs).toBe(150_000);
+    expect(result.completedSteps).toEqual(['a', 'b']);
+    expect(result.collected).toEqual({ a: 1 });
+  });
+
+  it('clamps negative durations to zero', () => {
+    const result = buildOnboardingResult({
+      completedSteps: [],
+      collected: {},
+      startedAt: new Date('2026-01-01T10:02:30.000Z'),
+      finishedAt: new Date('2026-01-01T10:00:00.000Z'),
+    });
+    expect(result.durationMs).toBe(0);
+  });
+});

package/src/domains/onboarding/utils/local-storage-bridge.ts

@@ -0,0 +1,84 @@
+import { elapsedMillis } from '../calc/elapsed-millis';
+import { isLocalStorageAvailable } from '../predicates/storage-available';
+import { checkStoredProgress } from '../validation/stored-progress-check';
+import { defaultStorageKey } from './default-storage-key';
+import type { OnboardingResult } from '../types/config';
+
+export interface RehydratedProgress {
+  currentStep: number;
+  completedSteps: string[];
+  collected: Record<string, unknown>;
+  startedAt: Date;
+  lastUpdated: Date;
+}
+
+function buildKey(customKey: string | undefined): string {
+  return customKey ?? defaultStorageKey;
+}
+
+export function saveOnboardingProgress(
+  key: string | undefined,
+  payload: {
+    currentStep: number;
+    completedSteps: ReadonlyArray<string>;
+    collected: Record<string, unknown>;
+    startedAt: Date;
+    lastUpdated: Date;
+  },
+): boolean {
+  if (!isLocalStorageAvailable()) return false;
+  try {
+    const serialized = JSON.stringify({
+      version: 1,
+      currentStep: payload.currentStep,
+      completedSteps: [...payload.completedSteps],
+      collected: { ...payload.collected },
+      startedAt: payload.startedAt.toISOString(),
+      lastUpdated: payload.lastUpdated.toISOString(),
+    });
+    window.localStorage.setItem(buildKey(key), serialized);
+    return true;
+  } catch (error) {
+     
+    console.error('[web-onboarding] failed to persist progress', error);
+    return false;
+  }
+}
+
+export function loadOnboardingProgress(key: string | undefined): RehydratedProgress | null {
+  if (!isLocalStorageAvailable()) return null;
+  const raw = window.localStorage.getItem(buildKey(key));
+  const checked = checkStoredProgress(raw);
+  if (!checked.ok) {
+    if (raw !== null) {
+            window.localStorage.removeItem(buildKey(key));
+    }
+    return null;
+  }
+  return {
+    currentStep: checked.data.currentStep,
+    completedSteps: checked.data.completedSteps,
+    collected: checked.data.collected,
+    startedAt: new Date(checked.data.startedAt),
+    lastUpdated: new Date(checked.data.lastUpdated),
+  };
+}
+
+export function clearOnboardingProgress(key: string | undefined): void {
+  if (!isLocalStorageAvailable()) return;
+  window.localStorage.removeItem(buildKey(key));
+}
+
+export function buildOnboardingResult(input: {
+  completedSteps: ReadonlyArray<string>;
+  collected: Record<string, unknown>;
+  startedAt: Date;
+  finishedAt: Date;
+}): OnboardingResult {
+  return {
+    completedSteps: input.completedSteps,
+    collected: input.collected,
+    durationMs: elapsedMillis(input.startedAt, input.finishedAt),
+    finishedAt: input.finishedAt,
+  };
+}

package/src/domains/onboarding/utils/permission-bridge.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { queryPermissionStatus, requestPermission } from './permission-bridge';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe('queryPermissionStatus', () => {
+  it('maps photos to prompt and contacts to unsupported (no web-standard API)', async () => {
+    await expect(queryPermissionStatus('photos')).resolves.toBe('prompt');
+    await expect(queryPermissionStatus('contacts')).resolves.toBe('unsupported');
+  });
+
+  it('reads Notification.permission for notifications', async () => {
+    vi.stubGlobal('Notification', { permission: 'granted' });
+    await expect(queryPermissionStatus('notifications')).resolves.toBe('granted');
+  });
+
+  it('normalizes the browser "default" state to prompt', async () => {
+    vi.stubGlobal('Notification', { permission: 'default' });
+    await expect(queryPermissionStatus('notifications')).resolves.toBe('prompt');
+  });
+
+  it('returns unsupported when Notification is missing', async () => {
+    const original = (globalThis as { Notification?: unknown }).Notification;
+    vi.stubGlobal('Notification', undefined);
+    try {
+      await expect(queryPermissionStatus('notifications')).resolves.toBe('unsupported');
+    } finally {
+      if (original !== undefined) vi.stubGlobal('Notification', original);
+    }
+  });
+});
+
+describe('requestPermission — never throws', () => {
+  it('resolves granted when the user accepts notifications', async () => {
+    vi.stubGlobal('Notification', {
+      permission: 'default',
+      requestPermission: () => Promise.resolve('granted'),
+    });
+    await expect(requestPermission('notifications')).resolves.toBe('granted');
+  });
+
+  it('resolves denied when the user rejects notifications', async () => {
+    vi.stubGlobal('Notification', {
+      permission: 'default',
+      requestPermission: () => Promise.resolve('denied'),
+    });
+    await expect(requestPermission('notifications')).resolves.toBe('denied');
+  });
+
+  it('maps a throwing requestPermission to denied, not a rejection', async () => {
+    vi.stubGlobal('Notification', {
+      permission: 'default',
+      requestPermission: () => Promise.reject(new Error('blocked')),
+    });
+    await expect(requestPermission('notifications')).resolves.toBe('denied');
+  });
+
+  it('returns unsupported for permission types without a web API', async () => {
+    await expect(requestPermission('contacts')).resolves.toBe('unsupported');
+  });
+});

package/src/domains/onboarding/utils/permission-bridge.ts

@@ -0,0 +1,87 @@
+import {
+  doesBrowserSupportMediaCapture,
+  doesBrowserSupportGeolocation,
+  doesBrowserSupportNotifications,
+} from '../predicates/permission-supports';
+import { normalizePermissionStatus } from '../validation/permission-status-check';
+import type { PermissionStatus, PermissionType } from '../types/screens';
+
+const GEOLOCATION_TIMEOUT_MS = 5000;
+
+export async function queryPermissionStatus(permission: PermissionType): Promise<PermissionStatus> {
+  if (typeof window === 'undefined' || typeof navigator === 'undefined') return 'unsupported';
+
+  try {
+    switch (permission) {
+      case 'notifications': {
+        if (!doesBrowserSupportNotifications()) return 'unsupported';
+        return normalizePermissionStatus(window.Notification.permission);
+      }
+      case 'camera':
+      case 'microphone': {
+        if (!doesBrowserSupportMediaCapture()) return 'unsupported';
+        if (!navigator.permissions?.query) return 'unsupported';
+        const status = await navigator.permissions.query({
+          name: permission === 'camera' ? 'camera' : 'microphone',
+        });
+        return normalizePermissionStatus(status.state);
+      }
+      case 'location': {
+        if (!doesBrowserSupportGeolocation()) return 'unsupported';
+        if (!navigator.permissions?.query) return 'unsupported';
+        const status = await navigator.permissions.query({ name: 'geolocation' });
+        return normalizePermissionStatus(status.state);
+      }
+      case 'photos':
+        return 'prompt';
+      case 'contacts':
+        return 'unsupported';
+      default:
+        return 'unsupported';
+    }
+  } catch {
+    return 'unsupported';
+  }
+}
+
+export async function requestPermission(permission: PermissionType): Promise<PermissionStatus> {
+  if (typeof window === 'undefined' || typeof navigator === 'undefined') return 'unsupported';
+
+  try {
+    switch (permission) {
+      case 'notifications': {
+        if (!doesBrowserSupportNotifications()) return 'unsupported';
+        const result = await window.Notification.requestPermission();
+        return normalizePermissionStatus(result);
+      }
+      case 'camera':
+      case 'microphone': {
+        if (!doesBrowserSupportMediaCapture()) return 'unsupported';
+        const constraints: MediaStreamConstraints =
+          permission === 'camera' ? { video: true } : { audio: true };
+        const stream = await navigator.mediaDevices.getUserMedia(constraints);
+        stream.getTracks().forEach((track) => track.stop());
+        return 'granted';
+      }
+      case 'location': {
+        if (!doesBrowserSupportGeolocation()) return 'unsupported';
+        return new Promise<PermissionStatus>((resolve) => {
+          navigator.geolocation.getCurrentPosition(
+            () => resolve('granted'),
+            (err) =>
+              resolve(err.code === err.PERMISSION_DENIED ? 'denied' : 'unsupported'),
+            { timeout: GEOLOCATION_TIMEOUT_MS },
+          );
+        });
+      }
+      case 'photos':
+        return 'prompt';
+      case 'contacts':
+        return 'unsupported';
+      default:
+        return 'unsupported';
+    }
+  } catch {
+    return 'denied';
+  }
+}

package/src/domains/onboarding/validation/flow-structure-check.ts

@@ -0,0 +1,22 @@
+import type { OnboardingScreen } from '../types/screens';
+import { checkScreenConfig } from './screen-config-check';
+
+export type ValidationOutcome = { ok: true } | { ok: false; reason: string };
+
+const MIN_FLOW_LENGTH = 1;
+
+export function checkFlowStructure(screens: ReadonlyArray<OnboardingScreen>): ValidationOutcome {
+  if (!Array.isArray(screens) || screens.length < MIN_FLOW_LENGTH) {
+    return { ok: false, reason: 'flow must contain at least one screen' };
+  }
+  const seen = new Set<string>();
+  for (const screen of screens) {
+    const result = checkScreenConfig(screen);
+    if (!result.ok) return result;
+    if (seen.has(screen.id)) {
+      return { ok: false, reason: `duplicate step id: "${screen.id}"` };
+    }
+    seen.add(screen.id);
+  }
+  return { ok: true };
+}

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

@@ -0,0 +1,9 @@
+export { checkFlowStructure } from './flow-structure-check';
+export type { ValidationOutcome } from './flow-structure-check';
+export { checkScreenConfig, getRecognizedScreenTypes } from './screen-config-check';
+export { checkStoredProgress } from './stored-progress-check';
+export type { StoredProgressShape, StoredProgressOutcome } from './stored-progress-check';
+export {
+  isRecognizedPermissionStatus,
+  normalizePermissionStatus,
+} from './permission-status-check';

package/src/domains/onboarding/validation/permission-status-check.ts

@@ -0,0 +1,18 @@
+import type { PermissionStatus } from '../types/screens';
+
+const RECOGNIZED_STATUSES: ReadonlySet<PermissionStatus> = new Set<PermissionStatus>([
+  'granted',
+  'denied',
+  'prompt',
+  'unsupported',
+]);
+
+export function isRecognizedPermissionStatus(value: unknown): value is PermissionStatus {
+  return typeof value === 'string' && RECOGNIZED_STATUSES.has(value as PermissionStatus);
+}
+
+export function normalizePermissionStatus(rawValue: string | null | undefined): PermissionStatus {
+  if (rawValue === 'granted' || rawValue === 'denied') return rawValue;
+  if (rawValue === 'default' || rawValue === 'prompt') return 'prompt';
+  return 'unsupported';
+}

package/src/domains/onboarding/validation/screen-config-check.ts

@@ -0,0 +1,100 @@
+import type {
+  OnboardingScreen,
+  OnboardingScreenType,
+} from '../types/screens';
+import type { ValidationOutcome } from './flow-structure-check';
+
+const RECOGNIZED_SCREEN_TYPES: ReadonlySet<OnboardingScreenType> = new Set<OnboardingScreenType>([
+  'welcome',
+  'goal-question',
+  'pain-points',
+  'social-proof',
+  'tinder-cards',
+  'personalized-solution',
+  'comparison',
+  'preferences',
+  'permission-priming',
+  'processing',
+  'app-demo',
+  'value-delivery',
+  'account-gate',
+  'paywall',
+]);
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function checkGoalQuestion(screen: OnboardingScreen): ValidationOutcome {
+  const options = (screen as { options?: unknown }).options;
+  if (!Array.isArray(options) || options.length === 0) {
+    return { ok: false, reason: 'goal-question screen requires non-empty options' };
+  }
+  return { ok: true };
+}
+
+function checkPainPoints(screen: OnboardingScreen): ValidationOutcome {
+  const points = (screen as { painPoints?: unknown }).painPoints;
+  if (!Array.isArray(points) || points.length === 0) {
+    return { ok: false, reason: 'pain-points screen requires non-empty painPoints' };
+  }
+  return { ok: true };
+}
+
+function checkTinderCards(screen: OnboardingScreen): ValidationOutcome {
+  const statements = (screen as { statements?: unknown }).statements;
+  if (!Array.isArray(statements) || statements.length === 0) {
+    return { ok: false, reason: 'tinder-cards screen requires non-empty statements' };
+  }
+  return { ok: true };
+}
+
+function checkPermissionPriming(screen: OnboardingScreen): ValidationOutcome {
+  const permission = (screen as { permission?: unknown }).permission;
+  if (typeof permission !== 'string') {
+    return { ok: false, reason: 'permission-priming screen requires a permission identifier' };
+  }
+  return { ok: true };
+}
+
+function checkPaywall(screen: OnboardingScreen): ValidationOutcome {
+  const price = (screen as { price?: unknown }).price;
+  const trialDays = (screen as { trialDays?: unknown }).trialDays;
+  if (typeof price !== 'string' || typeof trialDays !== 'number') {
+    return { ok: false, reason: 'paywall screen requires price and trialDays' };
+  }
+  return { ok: true };
+}
+
+export function checkScreenConfig(screen: OnboardingScreen): ValidationOutcome {
+  if (!isPlainObject(screen)) {
+    return { ok: false, reason: 'screen must be an object' };
+  }
+  const id = (screen as { id?: unknown }).id;
+  if (typeof id !== 'string' || id.length === 0) {
+    return { ok: false, reason: 'screen.id must be a non-empty string' };
+  }
+  const type = (screen as { type?: unknown }).type;
+  if (typeof type !== 'string' || !RECOGNIZED_SCREEN_TYPES.has(type as OnboardingScreenType)) {
+    return { ok: false, reason: `screen.type "${String(type)}" is not a recognized screen type` };
+  }
+
+  switch (type) {
+    case 'goal-question':
+      return checkGoalQuestion(screen);
+    case 'pain-points':
+      return checkPainPoints(screen);
+    case 'tinder-cards':
+      return checkTinderCards(screen);
+    case 'permission-priming':
+      return checkPermissionPriming(screen);
+    case 'paywall':
+      return checkPaywall(screen);
+    default:
+      return { ok: true };
+  }
+}
+
+export function getRecognizedScreenTypes(): ReadonlySet<OnboardingScreenType> {
+  return RECOGNIZED_SCREEN_TYPES;
+}