onboardme-sdk 0.0.1

package/src/__tests__/week2-day3.test.ts

@@ -0,0 +1,128 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { getShadowRoot } from '../components/shadow-host.js';
+import { renderModal, showModal, hideModal } from '../components/modal.js';
+import type { FlowStep } from '@onboardme/types';
+
+const PRODUCT_ID = 'test-product';
+const SESSION_KEY = `onboardme_modal_shown_${PRODUCT_ID}`;
+
+function makeStep(overrides: Partial<FlowStep> = {}): FlowStep {
+  return {
+    id: 'step-1',
+    type: 'modal',
+    order: 1,
+    title: 'Welcome',
+    body: 'Let us show you around.',
+    trigger: { type: 'page_load' },
+    dismissible: true,
+    ...overrides,
+  };
+}
+
+describe('Week 2 Day 3 — Modal show/hide logic (modal.ts)', () => {
+  let shadow: ShadowRoot;
+
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    sessionStorage.clear();
+    shadow = getShadowRoot();
+  });
+
+  // --- showModal: session guard ---
+
+  it('showModal renders the modal for a fresh session', () => {
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).not.toBeNull();
+  });
+
+  it('showModal sets the sessionStorage flag', () => {
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    expect(sessionStorage.getItem(SESSION_KEY)).not.toBeNull();
+  });
+
+  it('showModal is a no-op if the session flag is already set', () => {
+    sessionStorage.setItem(SESSION_KEY, '1');
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+
+  it('calling showModal twice only renders one modal', () => {
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    expect(shadow.querySelectorAll('[data-onboardme="overlay"]').length).toBe(1);
+  });
+
+  // --- hideModal ---
+
+  it('hideModal removes the overlay from the shadow root', () => {
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    hideModal(shadow);
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+
+  it('hideModal does NOT clear the sessionStorage flag', () => {
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    hideModal(shadow);
+    expect(sessionStorage.getItem(SESSION_KEY)).not.toBeNull();
+  });
+
+  it('hideModal is safe to call when no modal is present (no throw)', () => {
+    expect(() => hideModal(shadow)).not.toThrow();
+  });
+
+  // --- Keyboard: Escape ---
+
+  it('pressing Escape closes the modal', () => {
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+
+  it('pressing a non-Escape key does not close the modal', () => {
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).not.toBeNull();
+  });
+
+  it('Escape closes modal even when dismissible is false', () => {
+    showModal(makeStep({ dismissible: false }), shadow, PRODUCT_ID, 'test-flow');
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+
+  it('keyboard listener is removed after hideModal (Escape no longer fires)', () => {
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    hideModal(shadow);
+    // Re-render a fresh modal manually (bypassing session guard) to have something to check
+    renderModal(makeStep(), shadow);
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    // Listener was removed — overlay should still be present
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).not.toBeNull();
+  });
+
+  // --- Click handlers ---
+
+  it('clicking the primary CTA closes the modal', () => {
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    const btn = shadow.querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]');
+    btn?.click();
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+
+  it('clicking the skip button closes the modal', () => {
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    const btn = shadow.querySelector<HTMLButtonElement>('[data-onboardme="skip-cta"]');
+    btn?.click();
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+
+  // --- Focus ---
+
+  it('showModal moves focus to the primary CTA button', () => {
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    const primaryCta = shadow.querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]');
+    // Inside a Shadow DOM, document.activeElement returns the shadow HOST.
+    // shadow.activeElement returns the focused element within the shadow root.
+    expect(shadow.activeElement).toBe(primaryCta);
+  });
+});

package/src/__tests__/week2-day4.test.ts

@@ -0,0 +1,177 @@
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { runSDK, _resetSDK } from '../core/sdk.js';
+import OnboardMe, { _resetIndex } from '../index.js';
+import type { FlowConfig } from '@onboardme/types';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeFlow(overrides: Partial<FlowConfig> = {}): FlowConfig {
+  return {
+    id: 'flow-1',
+    name: 'Onboarding',
+    completionGoal: 'goal_reached',
+    priority: 1,
+    steps: [
+      {
+        id: 'step-modal',
+        type: 'modal',
+        order: 1,
+        title: 'Welcome',
+        body: 'Let us show you around.',
+        trigger: { type: 'page_load' },
+        dismissible: true,
+      },
+    ],
+    ...overrides,
+  };
+}
+
+const PRODUCT_ID = 'w2d4-product';
+
+beforeEach(() => {
+  localStorage.clear();
+  sessionStorage.clear();
+  document.body.innerHTML = '';
+  _resetSDK();
+  _resetIndex();
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('Week 2 Day 4 — Modal wired into SDK orchestrator (sdk.ts)', () => {
+
+  // --- New user: modal deferred show ---
+
+  it('schedules showModal via setTimeout for a new user with a modal step', () => {
+    const spy = vi.spyOn(globalThis, 'setTimeout');
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    expect(spy).toHaveBeenCalledWith(expect.any(Function), 0);
+  });
+
+  it('modal is NOT in DOM immediately after runSDK (deferred)', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    const shadow = document.getElementById('onboardme-root')?.shadowRoot;
+    // Shadow root may not exist yet — either way no overlay should be present
+    expect(shadow?.querySelector('[data-onboardme="overlay"]') ?? null).toBeNull();
+  });
+
+  it('modal appears in DOM after timers flush (new user)', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')?.shadowRoot;
+    expect(shadow?.querySelector('[data-onboardme="overlay"]')).not.toBeNull();
+  });
+
+  it('modal title matches the first modal step', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')?.shadowRoot;
+    expect(shadow?.querySelector('.om-modal__title')?.textContent).toBe('Welcome');
+  });
+
+  // --- Returning user: no modal ---
+
+  it('does not schedule showModal for a returning user', () => {
+    localStorage.setItem(`onboardme_seen_${PRODUCT_ID}`, '1');
+    const spy = vi.spyOn(globalThis, 'setTimeout');
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    // setTimeout may be called by other code; ensure modal never appears
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')?.shadowRoot;
+    expect(shadow?.querySelector('[data-onboardme="overlay"]') ?? null).toBeNull();
+  });
+
+  // --- No modal step ---
+
+  it('logs and skips when no modal step exists in any flow', () => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const flowWithNoModal = makeFlow({
+      steps: [
+        {
+          id: 'step-tooltip',
+          type: 'tooltip',
+          order: 1,
+          title: 'Tip',
+          body: 'Some tip.',
+          trigger: { type: 'page_load' },
+        },
+      ],
+    });
+    runSDK({ productId: PRODUCT_ID, flows: [flowWithNoModal] });
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')?.shadowRoot;
+    expect(shadow?.querySelector('[data-onboardme="overlay"]') ?? null).toBeNull();
+  });
+
+  it('does not throw when flows array is empty', () => {
+    expect(() => {
+      runSDK({ productId: PRODUCT_ID, flows: [] });
+      vi.runAllTimers();
+    }).not.toThrow();
+  });
+
+  // --- Double-init guard ---
+
+  it('runSDK returns null on second call (initialised guard)', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    const second = runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    expect(second).toBeNull();
+  });
+
+  it('modal appears only once when runSDK is called twice', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')?.shadowRoot;
+    const overlays = shadow?.querySelectorAll('[data-onboardme="overlay"]') ?? [];
+    expect(overlays.length).toBe(1);
+  });
+
+  it('OnboardMe.init() called twice shows modal only once', () => {
+    OnboardMe.init({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    OnboardMe.init({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')?.shadowRoot;
+    const overlays = shadow?.querySelectorAll('[data-onboardme="overlay"]') ?? [];
+    expect(overlays.length).toBe(1);
+  });
+
+  // --- First modal step selection ---
+
+  it('picks the step with the lowest order when multiple modal steps exist', () => {
+    const flowWithTwo = makeFlow({
+      steps: [
+        {
+          id: 'step-b',
+          type: 'modal',
+          order: 2,
+          title: 'Second Modal',
+          body: 'B',
+          trigger: { type: 'page_load' },
+        },
+        {
+          id: 'step-a',
+          type: 'modal',
+          order: 1,
+          title: 'First Modal',
+          body: 'A',
+          trigger: { type: 'page_load' },
+        },
+      ],
+    });
+    runSDK({ productId: PRODUCT_ID, flows: [flowWithTwo] });
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')?.shadowRoot;
+    expect(shadow?.querySelector('.om-modal__title')?.textContent).toBe('First Modal');
+  });
+});

package/src/__tests__/week2-day5.test.ts

@@ -0,0 +1,294 @@
+/**
+ * Week 2 Day 5 — Full integration tests + Week 2 verification checklist
+ *
+ * Exercises every item on the Week 2 checklist end-to-end:
+ *   ✓ New user  → modal appears (deferred via setTimeout)
+ *   ✓ Returning user → nothing rendered
+ *   ✓ CTA click → modal closes, session flag set
+ *   ✓ Escape key → modal closes
+ *   ✓ Same-tab reload → modal does not reappear (sessionStorage guard)
+ *   ✓ New tab → modal appears again (fresh sessionStorage)
+ *   ✓ dismissible: false → skip button hidden; Escape still works
+ *   ✓ Host page styles → zero bleed into shadow root
+ *   ✓ pnpm test → all unit tests pass (this file is the final gate)
+ *
+ * These tests wire together everything built in Days 1–4 and validate
+ * the system as a whole.
+ */
+
+import { beforeEach, afterEach, describe, expect, it } from 'vitest';
+import { vi } from 'vitest';
+import { runSDK, _resetSDK } from '../core/sdk.js';
+import OnboardMe, { _resetIndex } from '../index.js';
+import { getShadowRoot } from '../components/shadow-host.js';
+import { renderModal, showModal, hideModal } from '../components/modal.js';
+import type { FlowConfig, FlowStep } from '@onboardme/types';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const PRODUCT_ID = 'w2-checklist';
+const SESSION_KEY = `onboardme_modal_shown_${PRODUCT_ID}`;
+
+function makeStep(overrides: Partial<FlowStep> = {}): FlowStep {
+  return {
+    id: 'step-welcome',
+    type: 'modal',
+    order: 1,
+    title: 'Welcome to the app',
+    body: 'Here is a quick tour.',
+    trigger: { type: 'page_load' },
+    dismissible: true,
+    ...overrides,
+  };
+}
+
+function makeFlow(stepOverrides: Partial<FlowStep> = {}): FlowConfig {
+  return {
+    id: 'flow-welcome',
+    name: 'Welcome flow',
+    completionGoal: 'tour_completed',
+    priority: 1,
+    steps: [makeStep(stepOverrides)],
+  };
+}
+
+beforeEach(() => {
+  localStorage.clear();
+  sessionStorage.clear();
+  document.body.innerHTML = '';
+  _resetSDK();
+  _resetIndex();
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Checklist item 1: New user (fresh localStorage) → modal appears within 500ms
+// ---------------------------------------------------------------------------
+
+describe('Checklist: new user → modal appears', () => {
+  it('modal is absent immediately after init (deferred)', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    const shadow = document.getElementById('onboardme-root')?.shadowRoot;
+    expect(shadow?.querySelector('[data-onboardme="overlay"]') ?? null).toBeNull();
+  });
+
+  it('modal appears after timer flush (well within 500ms)', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')!.shadowRoot!;
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).not.toBeNull();
+  });
+
+  it('modal displays the correct title and body text', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')!.shadowRoot!;
+    expect(shadow.querySelector('.om-modal__title')?.textContent).toBe('Welcome to the app');
+    expect(shadow.querySelector('.om-modal__body')?.textContent).toBe('Here is a quick tour.');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Checklist item 2: Returning user → nothing rendered
+// ---------------------------------------------------------------------------
+
+describe('Checklist: returning user → no modal', () => {
+  it('no modal rendered for a returning user (localStorage seen flag set)', () => {
+    localStorage.setItem(`onboardme_seen_${PRODUCT_ID}`, '1');
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')?.shadowRoot;
+    expect(shadow?.querySelector('[data-onboardme="overlay"]') ?? null).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Checklist item 3: CTA click → modal closes, session flag set
+// ---------------------------------------------------------------------------
+
+describe('Checklist: CTA click → modal closes + session flag', () => {
+  it('clicking primary CTA removes the modal from the DOM', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')!.shadowRoot!;
+    shadow.querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]')!.click();
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+
+  it('session flag is set after CTA click', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')!.shadowRoot!;
+    shadow.querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]')!.click();
+    expect(sessionStorage.getItem(SESSION_KEY)).not.toBeNull();
+  });
+
+  it('clicking skip button also closes the modal', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')!.shadowRoot!;
+    shadow.querySelector<HTMLButtonElement>('[data-onboardme="skip-cta"]')!.click();
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Checklist item 4: Escape key → modal closes
+// ---------------------------------------------------------------------------
+
+describe('Checklist: Escape key → modal closes', () => {
+  it('pressing Escape removes the modal overlay', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    const shadow = document.getElementById('onboardme-root')!.shadowRoot!;
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+
+  it('pressing a non-Escape key does not close the modal', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', bubbles: true }));
+    const shadow = document.getElementById('onboardme-root')!.shadowRoot!;
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).not.toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Checklist item 5: Same-tab "reload" → modal does not reappear
+// (simulated by calling showModal twice with the session flag already set)
+// ---------------------------------------------------------------------------
+
+describe('Checklist: same-tab session guard → modal does not reappear', () => {
+  it('showModal is a no-op when sessionStorage flag already set', () => {
+    const shadow = getShadowRoot();
+    sessionStorage.setItem(SESSION_KEY, '1');
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+
+  it('session flag survives hideModal — second showModal is still blocked', () => {
+    const shadow = getShadowRoot();
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    hideModal(shadow);
+    // Session flag is still set — re-showing should be blocked
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Checklist item 6: New tab → modal appears again
+// (sessionStorage is per-tab; simulated by clearing it before showModal)
+// ---------------------------------------------------------------------------
+
+describe('Checklist: new tab (fresh session) → modal appears again', () => {
+  it('modal shows when sessionStorage is clear (fresh tab)', () => {
+    const shadow = getShadowRoot();
+    sessionStorage.clear(); // simulates a new browser tab
+    showModal(makeStep(), shadow, PRODUCT_ID, 'test-flow');
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).not.toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Checklist item 7: dismissible: false → skip hidden; Escape still works
+// ---------------------------------------------------------------------------
+
+describe('Checklist: dismissible: false', () => {
+  it('skip button is not rendered when dismissible is false', () => {
+    const shadow = getShadowRoot();
+    showModal(makeStep({ dismissible: false }), shadow, PRODUCT_ID, 'test-flow');
+    expect(shadow.querySelector('[data-onboardme="skip-cta"]')).toBeNull();
+  });
+
+  it('Escape still closes the modal when dismissible is false', () => {
+    const shadow = getShadowRoot();
+    showModal(makeStep({ dismissible: false }), shadow, PRODUCT_ID, 'test-flow');
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Checklist item 8: Host page styles → zero bleed into shadow root
+// ---------------------------------------------------------------------------
+
+describe('Checklist: style isolation', () => {
+  it('modal CSS classes do not exist on the host document body', () => {
+    runSDK({ productId: PRODUCT_ID, flows: [makeFlow()] });
+    vi.runAllTimers();
+    expect(document.body.querySelector('.om-overlay')).toBeNull();
+    expect(document.body.querySelector('.om-modal')).toBeNull();
+  });
+
+  it('modal CSS is injected into shadow root only, not document.head', () => {
+    const shadow = getShadowRoot();
+    renderModal(makeStep(), shadow);
+    const headStyles = Array.from(document.head.querySelectorAll('style'));
+    const leaked = headStyles.some((s) => s.textContent?.includes('.om-overlay'));
+    expect(leaked).toBe(false);
+  });
+
+  it('shadow root style contains om-overlay and om-modal rules', () => {
+    const shadow = getShadowRoot();
+    renderModal(makeStep(), shadow);
+    const shadowStyle = shadow.querySelector<HTMLStyleElement>('style[data-onboardme="styles"]');
+    expect(shadowStyle?.textContent).toContain('.om-overlay');
+    expect(shadowStyle?.textContent).toContain('.om-modal');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Checklist item 9: CTA / skip defaults
+// ---------------------------------------------------------------------------
+
+describe('Checklist: CTA label defaults', () => {
+  it('primary CTA defaults to "Get started" when primaryCta is absent', () => {
+    const shadow = getShadowRoot();
+    renderModal(makeStep(), shadow);
+    expect(
+      shadow.querySelector('[data-onboardme="primary-cta"]')?.textContent,
+    ).toBe('Get started');
+  });
+
+  it('skip link defaults to "Skip for now" when secondaryCta is absent', () => {
+    const shadow = getShadowRoot();
+    renderModal(makeStep(), shadow);
+    expect(
+      shadow.querySelector('[data-onboardme="skip-cta"]')?.textContent,
+    ).toBe('Skip for now');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Full end-to-end: OnboardMe.init() → modal shown → dismissed → gone
+// ---------------------------------------------------------------------------
+
+describe('End-to-end: full init → show → dismiss flow', () => {
+  it('complete lifecycle: init, timer flush, CTA click, modal gone', () => {
+    OnboardMe.init({ productId: PRODUCT_ID, flows: [makeFlow()] });
+
+    // After init — not yet visible
+    expect(document.getElementById('onboardme-root')?.shadowRoot?.querySelector('[data-onboardme="overlay"]') ?? null).toBeNull();
+
+    // After timer flush — visible
+    vi.runAllTimers();
+    const shadow = document.getElementById('onboardme-root')!.shadowRoot!;
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).not.toBeNull();
+
+    // CTA click — gone
+    shadow.querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]')!.click();
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).toBeNull();
+
+    // Session flag remains — would not reappear in same tab
+    expect(sessionStorage.getItem(SESSION_KEY)).not.toBeNull();
+  });
+});