@flamingo-stack/openframe-frontend-core 0.0.678 → 0.0.679-snapshot.20260929011258

package/src/components/chat/__tests__/embeddable-chat-composer-scope.test.tsx

@@ -0,0 +1,234 @@
+/**
+ * The composer belongs to the conversation on screen — pinned.
+ *
+ * `ChatInput` is an uncontrolled contenteditable that owns its draft, and the
+ * slash-command menu is derived from that draft (`/` at the start keeps it
+ * open). The panel already dropped the staged context chips on a dialog
+ * change, but the text stayed, so opening another conversation — from the
+ * list, or from a notification the host resolves straight into the store —
+ * landed with the previous one's half-typed `/` and its menu still open over
+ * the new thread. The composer is now keyed on the conversation: leaving one
+ * remounts it fresh in the same commit.
+ *
+ * The one id change that must NOT reset it: a send from the new-chat surface
+ * creates the dialog, and the id the panel then lands on is this conversation
+ * being named. The editor stays typable while that first turn streams, so a
+ * follow-up already being typed has to survive.
+ */
+
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { createRef } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Identity + every other authed fetch: a promise that never settles keeps the
+// panel offline and free of state updates landing outside `act`.
+vi.mock('../../../utils/embed-authed-fetch', () => ({
+  embedAuthedFetch: vi.fn(() => new Promise(() => {})),
+}));
+
+// One canned command, so `/` opens a real suggestions menu.
+vi.mock('../hooks/use-slash-commands', async importOriginal => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return {
+    ...actual,
+    fetchSlashCommands: vi.fn(() =>
+      Promise.resolve([
+        {
+          id: 'roadmap',
+          label: 'ClickUp Roadmap',
+          description: 'Browse the public ClickUp roadmap',
+          argumentHint: '[task id or name]',
+          actions: [{ id: 'recent', label: 'Recent' }],
+        },
+      ]),
+    ),
+  };
+});
+
+import { ChatRuntimeContext, type ChatRuntime } from '../../../contexts/chat-runtime-context';
+import { EmbeddableChat, type EmbeddableChatHandle } from '../embeddable-chat';
+import type { UnifiedChatState } from '../types/unified-chat-state.types';
+
+const runtime: ChatRuntime = {
+  endpoints: {
+    chatStreamUrl: '/api/docs/chat',
+    approvalToolUrl: '/api/chat/agent/confirm-tool',
+    commandsUrl: '/api/docs/commands',
+    buildListUrl: () => null,
+    attachmentUploadUrl: '/api/storage/generate-upload-url',
+    attachmentViewUrlPrefix: '/api/storage/view/chat-attachments/',
+    identityUrl: '/api/chat/identity',
+  },
+  navigation: { mode: 'host' },
+};
+
+const MESSAGE: UnifiedChatState['messages'][number] = {
+  id: 'm-1',
+  role: 'user',
+  content: 'hello',
+  timestamp: new Date('2026-01-01T00:00:00Z'),
+};
+
+/** The injected-state path (`mingoState`): the panel renders this object and
+ *  opens no transport, so the test drives `activeDialogId` by re-rendering. */
+function createState(overrides: Partial<UnifiedChatState>): UnifiedChatState {
+  const noop = () => {};
+  const asyncNoop = async () => {};
+  return {
+    messages: [],
+    isLoading: false,
+    streamingPhase: 'idle',
+    sendMessage: asyncNoop,
+    stopMessage: noop,
+    clearMessages: noop,
+    discussRef: noop,
+    displayRef: noop,
+    currentProvider: 'anthropic',
+    currentModelLabel: 'Claude',
+    currentContextWindowMaxTokens: null,
+    currentInputTokens: null,
+    currentOutputTokens: null,
+    currentCacheHitRatePct: null,
+    currentUsageBreakdown: null,
+    dialogs: [
+      { id: 'd-1', title: 'First' },
+      { id: 'd-2', title: 'Second' },
+    ],
+    activeDialogId: null,
+    selectDialog: noop,
+    startNewDialog: () => Promise.resolve(null),
+    deleteDialog: asyncNoop,
+    renameDialog: asyncNoop,
+    archiveDialog: asyncNoop,
+    isDialogsLoading: false,
+    dialogsError: false,
+    reloadDialogs: noop,
+    isMessagesLoading: false,
+    hasMoreDialogs: false,
+    loadMoreDialogs: asyncNoop,
+    hasMoreMessages: false,
+    loadMoreMessages: asyncNoop,
+    approveRequest: asyncNoop,
+    rejectRequest: asyncNoop,
+    dialogTokenUsage: null,
+    connectionState: 'connected',
+    ...overrides,
+  };
+}
+
+function Harness({ state, handleRef }: { state: UnifiedChatState; handleRef?: React.Ref<EmbeddableChatHandle> }) {
+  return (
+    <ChatRuntimeContext.Provider value={runtime}>
+      <DialogPrimitive.Root open>
+        <EmbeddableChat
+          ref={handleRef}
+          shell="none"
+          defaultOpen
+          defaultActiveMode="mingo"
+          showInternalTrigger={false}
+          mingoState={state}
+          mingoDialogCapabilities={{ canRename: true, canArchive: true }}
+        />
+      </DialogPrimitive.Root>
+    </ChatRuntimeContext.Provider>
+  );
+}
+
+function renderPanel(state: UnifiedChatState, handleRef?: React.Ref<EmbeddableChatHandle>) {
+  const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  const view = render(
+    <QueryClientProvider client={client}>
+      <Harness state={state} handleRef={handleRef} />
+    </QueryClientProvider>,
+  );
+  return {
+    ...view,
+    rerender: (next: UnifiedChatState) =>
+      view.rerender(
+        <QueryClientProvider client={client}>
+          <Harness state={next} handleRef={handleRef} />
+        </QueryClientProvider>,
+      ),
+  };
+}
+
+const editor = () => screen.getByRole('textbox', { name: 'Ask a question...' });
+
+/** Type into the uncontrolled editor the way the browser does: mutate the DOM,
+ *  then fire `input` so the component reads it back. */
+function type(text: string) {
+  const el = editor();
+  el.textContent = `${el.textContent ?? ''}${text}`;
+  fireEvent.input(el);
+}
+
+const menu = () => screen.queryByRole('menu', { name: 'Slash command suggestions' });
+
+beforeEach(() => {
+  vi.useRealTimers();
+});
+
+describe('EmbeddableChat — the composer belongs to the conversation on screen', () => {
+  it('opening another dialog drops the draft and the slash menu it kept open', async () => {
+    const { rerender } = renderPanel(createState({ activeDialogId: 'd-1', messages: [MESSAGE] }));
+
+    type('/');
+    expect(await screen.findByRole('menu', { name: 'Slash command suggestions' })).toBeInTheDocument();
+    expect(editor()).toHaveTextContent('/');
+
+    rerender(createState({ activeDialogId: 'd-2', messages: [MESSAGE] }));
+
+    expect(menu()).not.toBeInTheDocument();
+    expect(editor()).toHaveTextContent('');
+  });
+
+  it('opening a dialog from the new-chat surface drops the draft typed there', async () => {
+    const handle = createRef<EmbeddableChatHandle>();
+    const { rerender } = renderPanel(createState({ activeDialogId: null }), handle);
+    // Narrow layout: the list has no composer; the compose view does.
+    act(() => handle.current?.startNewChat());
+
+    type('/');
+    expect(await screen.findByRole('menu', { name: 'Slash command suggestions' })).toBeInTheDocument();
+
+    rerender(createState({ activeDialogId: 'd-1', messages: [MESSAGE] }));
+
+    expect(menu()).not.toBeInTheDocument();
+    expect(editor()).toHaveTextContent('');
+  });
+
+  it('a new chat being named by its first send keeps the follow-up already being typed', async () => {
+    let settleSend: () => void = () => {};
+    const sendMessage = vi.fn<UnifiedChatState['sendMessage']>(
+      () =>
+        new Promise<void>(resolve => {
+          settleSend = resolve;
+        }),
+    );
+    const handle = createRef<EmbeddableChatHandle>();
+    const { rerender } = renderPanel(createState({ activeDialogId: null, sendMessage }), handle);
+    act(() => handle.current?.startNewChat());
+
+    type('first question');
+    fireEvent.keyDown(editor(), { key: 'Enter' });
+    expect(sendMessage.mock.calls[0]?.[0]).toBe('first question');
+    expect(editor()).toHaveTextContent('');
+
+    // The host is creating the dialog; the user is already typing the next one.
+    type('and also');
+    rerender(createState({ activeDialogId: 'd-new', messages: [MESSAGE], sendMessage }));
+    expect(editor()).toHaveTextContent('and also');
+
+    await act(async () => {
+      settleSend();
+      await Promise.resolve();
+    });
+    expect(editor()).toHaveTextContent('and also');
+
+    // A real switch afterwards still resets.
+    rerender(createState({ activeDialogId: 'd-1', messages: [MESSAGE], sendMessage }));
+    expect(editor()).toHaveTextContent('');
+  });
+});

package/src/components/chat/embeddable-chat.tsx

@@ -95,7 +95,11 @@ import { SourceActionButton } from './source-action-button';
 import type { ChatInputRef, SlashCommandActionId } from './types/component.types';
 import type { ChatContextItem, ChatContextPickerConfig } from './types/context-item.types';
 import type { MessageSegment, Message } from './types/message.types';
-import type { ChatDialogCapabilities, UnifiedChatState } from './types/unified-chat-state.types';
+import type {
+  ChatDialogCapabilities,
+  UnifiedChatState,
+  UnifiedSendMessageOptions,
+} from './types/unified-chat-state.types';
 import { formatChatAttachmentMarkdownForBubble } from './utils/chat-attachment-markdown';
 import { resolveHrefForRuntime } from './utils/chat-nav-resolution';
 import { chatChipClass } from './utils/chip-styles';
@@ -1215,7 +1219,7 @@ function EmbeddableChatInner({
   const {
     messages: rawMessages,
     isLoading: chatLoading,
-    sendMessage,
+    sendMessage: sendMessageRaw,
     discussRef,
     stopMessage,
     clearMessages,
@@ -1257,6 +1261,29 @@ function EmbeddableChatInner({
   // adapters already know whether they own a list. Absent = single-thread.
   const historyListMode = dialogCapabilities !== undefined;
 
+  // A send from the new-chat surface asks the host to create the dialog, and
+  // the id the panel then lands on is THIS conversation being named — not the
+  // user leaving it. The editor stays typable while the first turn streams, so
+  // a follow-up already being typed has to survive that transition; the
+  // composer-scope reset below reads this flag to tell the two apart. Armed in
+  // the send's own event (one batch with the composer's own clear, so it is
+  // set by the render the id lands in) and dropped once the send settles either
+  // way: a create that failed would otherwise leave it armed for the next real
+  // switch. Every send path goes through here — the composer, a clarification
+  // card, a quick-action chip, the Guide launcher prompt.
+  const [namingNewChat, setNamingNewChat] = useState(false);
+  const sendMessage = useCallback(
+    async (text: string, options?: UnifiedSendMessageOptions) => {
+      if (activeDialogId == null) setNamingNewChat(true);
+      try {
+        return await sendMessageRaw(text, options);
+      } finally {
+        setNamingNewChat(false);
+      }
+    },
+    [activeDialogId, sendMessageRaw],
+  );
+
   // Non-optional view of the same object for the JSX below. `canRename` /
   // `canArchive` default OFF: the ⋯ menu must never advertise an action
   // nothing has wired.
@@ -1333,25 +1360,42 @@ function EmbeddableChatInner({
   // Source of truth = the input text — deleting a token's chip drops its item.
   const mentionKeysRef = useRef<Set<string>>(new Set());
 
-  // Staged picker selection is per-conversation and Mingo-only. Clear it (and the
-  // mention bookkeeping) whenever the active dialog changes or the mode toggles,
-  // so unsent chips can't bleed into another conversation — or into a Guide send,
-  // where the SSE transport silently drops `contextItems`. Mirrors the post-send
-  // reset in `handleSend`.
-  // The two STATE halves are adjusted while rendering (React's documented
-  // pattern for a reset the render already has the answer to) — the composer
-  // draws its chips from `contextItems`, so clearing from an effect committed
-  // one frame of the previous conversation's chips under the new one. The ref
-  // bookkeeping stays in an effect: a ref must not be written during render.
-  const [contextClearedFor, setContextClearedFor] = useState({ activeDialogId, activeMode });
-  if (contextClearedFor.activeDialogId !== activeDialogId || contextClearedFor.activeMode !== activeMode) {
-    setContextClearedFor({ activeDialogId, activeMode });
-    setContextItems(NO_CONTEXT_ITEMS);
-    setMentionQuery(null);
+  // The composer belongs to the conversation on screen. Leaving it — another
+  // dialog opened from the list, a notification or a link, back to the list, a
+  // new chat, the Mingo ⇄ Guide toggle — drops everything unsent: the draft
+  // text (and with it the slash-command menu that text keeps open), the staged
+  // context chips and the `@` / `+` picker, and the staged uploads. Nothing
+  // typed for one conversation may bleed into another — or into a Guide send,
+  // where the SSE transport silently drops `contextItems`. Mirrors the
+  // post-send reset in `handleSend`.
+  // The draft lives in an UNCONTROLLED contenteditable, so it is dropped the
+  // React way: `composerKey` remounts the composer subtree, in the same commit
+  // the new conversation renders in. An effect-time `clear()` painted one frame
+  // of the old draft — menu open — under the new conversation, and so did
+  // clearing the chips from an effect. So the STATE halves are adjusted while
+  // rendering (React's documented pattern for a reset the render already has
+  // the answer to); the ref and attachment bookkeeping stays in an effect: a ref
+  // must not be written during render, and aborting uploads is a side effect.
+  // The one id change that is NOT a switch: `null → id` while a send from the
+  // new-chat surface is naming it (`namingNewChat` above).
+  const scopeDialogId = activeDialogId ?? null;
+  const [composerScope, setComposerScope] = useState({ dialogId: scopeDialogId, mode: activeMode });
+  const [composerKey, setComposerKey] = useState(0);
+  if (composerScope.dialogId !== scopeDialogId || composerScope.mode !== activeMode) {
+    const named =
+      namingNewChat && composerScope.dialogId == null && scopeDialogId != null && composerScope.mode === activeMode;
+    setComposerScope({ dialogId: scopeDialogId, mode: activeMode });
+    if (!named) {
+      setComposerKey(k => k + 1);
+      setContextItems(NO_CONTEXT_ITEMS);
+      setContextPickerOpen(false);
+      setMentionQuery(null);
+    }
   }
   useEffect(() => {
     mentionKeysRef.current.clear();
-  }, [activeDialogId, activeMode]);
+    clearAttachments();
+  }, [composerKey, clearAttachments]);
 
   // Map each entity type to its backend mention marker (host-declared on the
   // entity type). Drives the committed `@marker:id` token; missing markers fall
@@ -2661,6 +2705,7 @@ function EmbeddableChatInner({
                       />
 
                       <ChatComposer
+                        key={composerKey}
                         archived={isViewingArchived}
                         lock={composerLock}
                         inputRef={chatInputRef}

package/src/components/chat/hooks/use-chat-attachments.ts

@@ -204,7 +204,10 @@ export function useChatAttachments(): UseChatAttachmentsApi {
   const clear = useCallback(() => {
     for (const ctrl of controllersRef.current.values()) ctrl.abort();
     controllersRef.current.clear();
-    setAttachments([]);
+    // Same array back when there is nothing staged, so React bails out of the
+    // update: the composer-scope effect calls this on mount and on every
+    // conversation switch, and an empty strip must not cost a render.
+    setAttachments(prev => (prev.length === 0 ? prev : []));
   }, []);
 
   const uploadOne = useCallback(

package/src/components/shared/onboarding/onboarding-walkthrough.tsx

@@ -9,6 +9,14 @@ import { OnboardingStepCard } from './onboarding-step-card';
 
 export interface OnboardingWalkthroughProps {
   steps: OnboardingStepConfig[];
+  /** Heading above the steps. Defaults to "Get Started". */
+  title?: string;
+  /**
+   * What to render once the walkthrough is dismissed. Receives `restart`,
+   * which clears every completed/skipped step and shows the walkthrough
+   * again. Omitted: a dismissed walkthrough renders nothing.
+   */
+  renderDismissed?: (restart: () => void) => React.ReactNode;
   onDismiss?: () => void;
   storageKey?: string;
   className?: string;
@@ -26,6 +34,8 @@ export interface OnboardingWalkthroughProps {
 
 export function OnboardingWalkthrough({
   steps,
+  title = 'Get Started',
+  renderDismissed,
   onDismiss,
   storageKey = 'openframe-onboarding-state',
   className,
@@ -38,6 +48,7 @@ export function OnboardingWalkthrough({
     markComplete,
     markSkipped,
     dismissOnboarding,
+    resetOnboarding,
     isStepComplete,
     isStepSkipped,
     allStepsComplete,
@@ -63,8 +74,11 @@ export function OnboardingWalkthrough({
     // Skip if no completion status
     if (!completionStatus) return;
 
-    // Create a stable key from completion status to detect actual changes
-    const statusKey = JSON.stringify(completionStatus);
+    // Create a stable key from completion status to detect actual changes.
+    // An empty state (first load, or after a restart) is keyed by when it was
+    // written, so a restart applies the same status again.
+    const isFreshState = state.completedSteps.length === 0 && state.skippedSteps.length === 0;
+    const statusKey = `${JSON.stringify(completionStatus)}|${isFreshState ? state.lastUpdated : ''}`;
 
     // Skip if we've already processed this exact status
     if (lastCompletionStatusRef.current === statusKey) return;
@@ -86,7 +100,6 @@ export function OnboardingWalkthrough({
       // Mark as in progress to prevent concurrent calls
       autoMarkingInProgressRef.current = true;
 
-      console.log('📊 Auto-marking steps as complete from hook data:', completedStepIds);
       markMultipleComplete(completedStepIds);
 
       // Update the last processed status key
@@ -101,14 +114,20 @@ export function OnboardingWalkthrough({
       // Even if no steps to mark, update the status key to prevent re-processing
       lastCompletionStatusRef.current = statusKey;
     }
-  }, [completionStatus, isLoadingCompletion, state.completedSteps, markMultipleComplete]);
+  }, [
+    completionStatus,
+    isLoadingCompletion,
+    state.completedSteps,
+    state.skippedSteps,
+    state.lastUpdated,
+    markMultipleComplete,
+  ]);
 
   // useCallback must be called unconditionally (before any early returns)
   const handleStepAction = useCallback(
     async (step: OnboardingStepConfig) => {
       // Prevent duplicate action handling for the same step
       if (actionInProgressRef.current.has(step.id)) {
-        console.log(`⏳ Action already in progress for "${step.id}", skipping`);
         return;
       }
 
@@ -120,13 +139,11 @@ export function OnboardingWalkthrough({
 
         // Skip if already completed (could have been auto-marked while action was running)
         if (state.completedSteps.includes(step.id)) {
-          console.log(`✓ Step "${step.id}" already completed, skipping mark`);
           return;
         }
 
         // Auto-mark Knowledge Base as complete (no verification needed)
         if (step.id === 'knowledge-base') {
-          console.log(`🎯 Auto-completing Knowledge Base`);
           markComplete(step.id);
           return;
         }
@@ -135,7 +152,6 @@ export function OnboardingWalkthrough({
         if (step.checkComplete) {
           try {
             const isComplete = await step.checkComplete();
-            console.log(`🔍 Post-action check for "${step.id}": isComplete=${isComplete}`);
 
             // Double-check it wasn't completed while we were checking
             if (isComplete && !state.completedSteps.includes(step.id)) {
@@ -166,7 +182,7 @@ export function OnboardingWalkthrough({
   // ALL hooks have been called above - now safe to do conditional returns
   // Don't render if dismissed
   if (state.dismissed) {
-    return null;
+    return renderDismissed ? <>{renderDismissed(resetOnboarding)}</> : null;
   }
 
   const isAllComplete = allStepsComplete(steps);
@@ -175,7 +191,7 @@ export function OnboardingWalkthrough({
     <div className={cn('w-full space-y-4', className)}>
       {/* Header - responsive: stacks on mobile */}
       <div className="flex flex-col items-start justify-between gap-3 md:flex-row md:items-center md:gap-0">
-        <h2 className={SECTION_HEADING_CLASS}>Get Started</h2>
+        <h2 className={SECTION_HEADING_CLASS}>{title}</h2>
 
         {isLoadingCompletion ? (
           <div className="h-[48px] w-full animate-pulse rounded-[6px] bg-ods-border md:w-[160px]" />

package/src/hooks/ui/use-onboarding-state.ts

@@ -8,6 +8,7 @@ import {
   markStepSkipped as storageMarkSkipped,
   dismissOnboarding as storageDismiss,
   markMultipleComplete as storageMarkMultiple,
+  resetOnboardingState as storageReset,
   type OnboardingState,
 } from '../../utils/onboarding-storage';
 import { readLocalStorageUpdateDetail } from '../../utils/storage-event';
@@ -42,7 +43,6 @@ export function useOnboardingState(storageKey: string = 'openframe-onboarding-st
       const newState = loadOnboardingState(storageKey);
       setState(newState);
       forceUpdate(prev => prev + 1);
-      console.log('🔄 State updated from storage event:', newState);
     };
 
     window.addEventListener('localStorageUpdate', handleStorageUpdate);
@@ -53,7 +53,6 @@ export function useOnboardingState(storageKey: string = 'openframe-onboarding-st
 
   const markComplete = useCallback(
     (stepId: string) => {
-      console.log(`🎯 markComplete called for: "${stepId}"`);
       const newState = storageMarkComplete(storageKey, stepId);
       setState(newState);
       forceUpdate(prev => prev + 1);
@@ -63,7 +62,6 @@ export function useOnboardingState(storageKey: string = 'openframe-onboarding-st
 
   const markSkipped = useCallback(
     (stepId: string) => {
-      console.log(`⏭️ markSkipped called for: "${stepId}"`);
       const newState = storageMarkSkipped(storageKey, stepId);
       setState(newState);
       forceUpdate(prev => prev + 1);
@@ -72,19 +70,22 @@ export function useOnboardingState(storageKey: string = 'openframe-onboarding-st
   );
 
   const dismissOnboarding = useCallback(() => {
-    console.log(`🚫 dismissOnboarding called`);
     const newState = storageDismiss(storageKey);
     setState(newState);
     forceUpdate(prev => prev + 1);
   }, [storageKey]);
 
+  const resetOnboarding = useCallback(() => {
+    const newState = storageReset(storageKey);
+    setState(newState);
+    forceUpdate(prev => prev + 1);
+  }, [storageKey]);
+
   const markMultipleComplete = useCallback(
     (stepIds: string[]) => {
-      console.log(`🎯 markMultipleComplete called for:`, stepIds);
       const newState = storageMarkMultiple(storageKey, stepIds);
       setState(newState);
       forceUpdate(prev => prev + 1);
-      console.log(`📝 State after batch:`, newState);
     },
     [storageKey],
   );
@@ -115,6 +116,7 @@ export function useOnboardingState(storageKey: string = 'openframe-onboarding-st
     markComplete,
     markSkipped,
     dismissOnboarding,
+    resetOnboarding,
     isStepComplete,
     isStepSkipped,
     allStepsComplete,

package/src/utils/__tests__/onboarding-storage.test.ts

@@ -0,0 +1,42 @@
+/**
+ * The reset that brings a dismissed walkthrough back, round-tripped through
+ * real localStorage: reading the state back is the only proof the write stuck.
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  dismissOnboarding,
+  loadOnboardingState,
+  markStepComplete,
+  markStepSkipped,
+  resetOnboardingState,
+} from '../onboarding-storage';
+
+const KEY = 'onboarding-storage-test';
+
+afterEach(() => localStorage.clear());
+
+describe('resetOnboardingState', () => {
+  it('clears completed and skipped steps and undoes a dismissal', () => {
+    markStepComplete(KEY, 'install');
+    markStepSkipped(KEY, 'video');
+    dismissOnboarding(KEY);
+    expect(loadOnboardingState(KEY).dismissed).toBe(true);
+
+    const reset = resetOnboardingState(KEY);
+
+    expect(reset).toMatchObject({ completedSteps: [], skippedSteps: [], dismissed: false });
+    expect(loadOnboardingState(KEY)).toMatchObject({ completedSteps: [], skippedSteps: [], dismissed: false });
+  });
+
+  it('tells other hook instances through the localStorageUpdate event', () => {
+    const seen: string[] = [];
+    const listener = (event: Event) => seen.push((event as CustomEvent<{ key: string }>).detail.key);
+    window.addEventListener('localStorageUpdate', listener);
+    try {
+      resetOnboardingState(KEY);
+    } finally {
+      window.removeEventListener('localStorageUpdate', listener);
+    }
+    expect(seen).toEqual([KEY]);
+  });
+});

package/src/utils/onboarding-storage.ts

@@ -26,7 +26,6 @@ export function saveOnboardingState(key: string, state: OnboardingState): void {
 
   try {
     localStorage.setItem(key, JSON.stringify(state));
-    console.log('💾 Saved onboarding state:', state);
 
     // Dispatch custom event for cross-tab sync
     if (typeof window !== 'undefined') {
@@ -110,6 +109,21 @@ export function dismissOnboarding(key: string): OnboardingState {
   return newState;
 }
 
+/**
+ * Reset the walkthrough to its initial state: no step completed or skipped,
+ * not dismissed. How a dismissed walkthrough is brought back.
+ */
+export function resetOnboardingState(key: string): OnboardingState {
+  const newState: OnboardingState = {
+    completedSteps: [],
+    skippedSteps: [],
+    dismissed: false,
+    lastUpdated: new Date().toISOString(),
+  };
+  saveOnboardingState(key, newState);
+  return newState;
+}
+
 /**
  * Check if a step is complete
  */