@startsimpli/hooks 0.4.11 → 0.4.15

package/src/__tests__/useWorkflows.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, vi } from 'vitest'
+import { renderHook, act, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import React from 'react'
+import {
+  useWorkflows,
+  useWorkflow,
+  useWorkflowNodeTypes,
+  useCreateWorkflow,
+  useUpdateWorkflow,
+  useDeleteWorkflow,
+  useExecuteWorkflow,
+  useWorkflowExecution,
+  useWorkflowExecutions,
+  useCancelExecution,
+  useRetryExecution,
+  executionRefetchInterval,
+} from '../useWorkflows'
+import type { WorkflowsApi } from '@startsimpli/api'
+
+function mkClient() {
+  return new QueryClient({
+    defaultOptions: { mutations: { retry: false }, queries: { retry: false } },
+  })
+}
+function wrap(qc: QueryClient) {
+  return ({ children }: { children: React.ReactNode }) =>
+    React.createElement(QueryClientProvider, { client: qc }, children)
+}
+function trackInvalidations(qc: QueryClient): unknown[][] {
+  const calls: unknown[][] = []
+  const orig = qc.invalidateQueries.bind(qc)
+  qc.invalidateQueries = ((arg: { queryKey: unknown[] }) => {
+    calls.push(arg.queryKey)
+    return orig(arg)
+  }) as typeof qc.invalidateQueries
+  return calls
+}
+function fakeApi(overrides: Partial<WorkflowsApi> = {}): WorkflowsApi {
+  return {
+    listWorkflows: vi.fn().mockResolvedValue({ results: [], count: 0 }),
+    getWorkflow: vi.fn().mockResolvedValue({ id: 'w1', name: 'Onboarding' }),
+    createWorkflow: vi.fn().mockResolvedValue({ id: 'w1' }),
+    updateWorkflow: vi.fn().mockResolvedValue({ id: 'w1', name: 'New' }),
+    deleteWorkflow: vi.fn().mockResolvedValue(undefined),
+    getNodeTypes: vi.fn().mockResolvedValue([{ slug: 'http', category: 'action', label: 'HTTP' }]),
+    executeWorkflow: vi.fn().mockResolvedValue({ executionId: 'e1', status: 'running' }),
+    getExecution: vi.fn().mockResolvedValue({ status: 'running', state: {}, nodeExecutions: [] }),
+    listExecutions: vi.fn().mockResolvedValue({ results: [], count: 0 }),
+    cancelExecution: vi.fn().mockResolvedValue({ id: 'e1', status: 'cancelled' }),
+    retryExecution: vi.fn().mockResolvedValue({ executionId: 'e2', status: 'pending' }),
+    ...overrides,
+  } as unknown as WorkflowsApi
+}
+
+describe('workflow query hooks', () => {
+  it('useWorkflows fetches the workflow list', async () => {
+    const api = fakeApi()
+    const { result } = renderHook(() => useWorkflows(api, { page: 1 }), { wrapper: wrap(mkClient()) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(api.listWorkflows).toHaveBeenCalledWith({ page: 1 })
+  })
+
+  it('useWorkflow fetches one workflow and is disabled without an id', async () => {
+    const api = fakeApi()
+    const { result } = renderHook(() => useWorkflow(api, ''), { wrapper: wrap(mkClient()) })
+    expect(result.current.fetchStatus).toBe('idle')
+    expect(api.getWorkflow).not.toHaveBeenCalled()
+  })
+
+  it('useWorkflowNodeTypes fetches the node-type registry', async () => {
+    const api = fakeApi()
+    const { result } = renderHook(() => useWorkflowNodeTypes(api), { wrapper: wrap(mkClient()) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(api.getNodeTypes).toHaveBeenCalled()
+  })
+
+  it('useWorkflowExecution fetches the execution detail and is disabled without an id', async () => {
+    const api = fakeApi()
+    const { result } = renderHook(() => useWorkflowExecution(api, ''), { wrapper: wrap(mkClient()) })
+    expect(result.current.fetchStatus).toBe('idle')
+    expect(api.getExecution).not.toHaveBeenCalled()
+  })
+
+  it('useWorkflowExecutions fetches executions for a workflow', async () => {
+    const api = fakeApi()
+    const { result } = renderHook(() => useWorkflowExecutions(api, 'w1', { page: 1 }), {
+      wrapper: wrap(mkClient()),
+    })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(api.listExecutions).toHaveBeenCalledWith('w1', { page: 1 })
+  })
+})
+
+describe('workflow mutation hooks invalidate the right queries', () => {
+  it('useCreateWorkflow invalidates the workflows list', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useCreateWorkflow(fakeApi()), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate({ name: 'Onboarding' }) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(expect.arrayContaining([['workflows', 'list']]))
+  })
+
+  it('useUpdateWorkflow invalidates the workflow detail', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useUpdateWorkflow(fakeApi(), 'w1'), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate({ name: 'New' }) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(expect.arrayContaining([['workflows', 'detail', 'w1']]))
+  })
+
+  it('useDeleteWorkflow invalidates the workflows list', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useDeleteWorkflow(fakeApi()), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate('w1') })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(expect.arrayContaining([['workflows', 'list']]))
+  })
+
+  it('useExecuteWorkflow surfaces the executionId', async () => {
+    const qc = mkClient()
+    const api = fakeApi()
+    const { result } = renderHook(() => useExecuteWorkflow(api, 'w1'), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate({ foo: 'bar' }) })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(api.executeWorkflow).toHaveBeenCalledWith('w1', { foo: 'bar' })
+    expect(result.current.data?.executionId).toBe('e1')
+  })
+
+  it('useCancelExecution invalidates the execution query key', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useCancelExecution(fakeApi()), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate('e1') })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(expect.arrayContaining([['workflows', 'execution', 'e1']]))
+  })
+
+  it('useRetryExecution invalidates the execution query key', async () => {
+    const qc = mkClient()
+    const seen = trackInvalidations(qc)
+    const { result } = renderHook(() => useRetryExecution(fakeApi()), { wrapper: wrap(qc) })
+    await act(async () => { result.current.mutate('e1') })
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+    expect(seen).toEqual(expect.arrayContaining([['workflows', 'execution', 'e1']]))
+  })
+})
+
+describe('executionRefetchInterval', () => {
+  it('polls while running/pending/waiting and stops when terminal', () => {
+    expect(executionRefetchInterval('running')).toBeGreaterThan(0)
+    expect(executionRefetchInterval('pending')).toBeGreaterThan(0)
+    expect(executionRefetchInterval('waiting')).toBeGreaterThan(0)
+    expect(executionRefetchInterval('completed')).toBe(false)
+    expect(executionRefetchInterval('failed')).toBe(false)
+    expect(executionRefetchInterval('cancelled')).toBe(false)
+    expect(executionRefetchInterval(undefined)).toBe(false)
+  })
+})

package/src/index.ts

@@ -68,3 +68,23 @@ export type {
 } from './useCSV'
 export { useAsyncOptions } from './useAsyncOptions'
 export type { UseAsyncOptionsResult } from './useAsyncOptions'
+
+// Vault — environments, secrets, access keys, audit (startsim-d30.3.2)
+export {
+  useEnvironments,
+  useEnvironment,
+  useCreateEnvironment,
+  useUpdateEnvironment,
+  useDeleteEnvironment,
+  useSecrets,
+  useCreateSecret,
+  useUpdateSecret,
+  useDeleteSecret,
+  useRevealSecret,
+  useAccessKeys,
+  useCreateAccessKey,
+  useDeleteAccessKey,
+  useAuditLog,
+} from './useVault'
+export * from './usePresentations'
+export * from './useWorkflows'

package/src/useCSV-core.ts

@@ -0,0 +1,144 @@
+import { useState, useCallback } from 'react'
+
+export interface CSVColumnMapping {
+  csvColumn: string
+  targetField: string
+}
+
+export interface CSVPreviewResult<TField extends string = string> {
+  columns: string[]
+  sampleRows: Record<string, string>[]
+  suggestedMappings?: CSVColumnMapping[]
+  totalRows?: number
+}
+
+export interface CSVImportResult {
+  totalRows: number
+  successful: number
+  failed: number
+  errors: Array<{ row: number; message: string }>
+}
+
+export type CSVImportStep = 'upload' | 'mapping' | 'importing' | 'complete'
+
+export interface UseCSVImportOptions<TField extends string = string> {
+  previewFn: (file: File) => Promise<CSVPreviewResult<TField>>
+  importFn: (file: File, mappings: CSVColumnMapping[]) => Promise<CSVImportResult>
+  onSuccess?: (result: CSVImportResult) => void
+}
+
+export interface UseCSVImportState {
+  step: CSVImportStep
+  file: File | null
+  preview: CSVPreviewResult | null
+  mappings: CSVColumnMapping[]
+  result: CSVImportResult | null
+  isLoading: boolean
+  error: string | null
+  handleFileSelect: (file: File) => Promise<void>
+  updateMapping: (csvColumn: string, targetField: string) => void
+  startImport: () => Promise<void>
+  reset: () => void
+  goBack: () => void
+}
+
+/**
+ * Platform-neutral CSV import state machine.
+ *
+ * The actual file reading is delegated to the caller-provided previewFn/importFn,
+ * so this hook never touches the DOM — `File` is used only as a type. It is safe
+ * on web and React Native alike, which is why it lives in the shared core rather
+ * than the platform-specific useCSV entries.
+ */
+export function useCSVImport<TField extends string = string>({
+  previewFn,
+  importFn,
+  onSuccess,
+}: UseCSVImportOptions<TField>): UseCSVImportState {
+  const [step, setStep] = useState<CSVImportStep>('upload')
+  const [file, setFile] = useState<File | null>(null)
+  const [preview, setPreview] = useState<CSVPreviewResult | null>(null)
+  const [mappings, setMappings] = useState<CSVColumnMapping[]>([])
+  const [result, setResult] = useState<CSVImportResult | null>(null)
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const handleFileSelect = useCallback(
+    async (selectedFile: File) => {
+      setFile(selectedFile)
+      setError(null)
+      setIsLoading(true)
+      try {
+        const previewData = await previewFn(selectedFile)
+        setPreview(previewData)
+        setMappings(previewData.suggestedMappings ?? [])
+        setStep('mapping')
+      } catch {
+        setError('Failed to preview CSV file')
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [previewFn]
+  )
+
+  const updateMapping = useCallback((csvColumn: string, targetField: string) => {
+    setMappings((prev) => {
+      const existing = prev.find((m) => m.csvColumn === csvColumn)
+      if (existing) {
+        return prev.map((m) =>
+          m.csvColumn === csvColumn ? { ...m, targetField: targetField } : m
+        )
+      }
+      return [...prev, { csvColumn: csvColumn, targetField: targetField }]
+    })
+  }, [])
+
+  const startImport = useCallback(async () => {
+    if (!file) return
+    setStep('importing')
+    setError(null)
+    try {
+      const importResult = await importFn(file, mappings)
+      setResult(importResult)
+      setStep('complete')
+      onSuccess?.(importResult)
+    } catch {
+      setError('Failed to import CSV')
+      setStep('mapping')
+    }
+  }, [file, mappings, importFn, onSuccess])
+
+  const reset = useCallback(() => {
+    setStep('upload')
+    setFile(null)
+    setPreview(null)
+    setMappings([])
+    setResult(null)
+    setError(null)
+  }, [])
+
+  const goBack = useCallback(() => {
+    if (step === 'mapping') setStep('upload')
+  }, [step])
+
+  return {
+    step,
+    file,
+    preview,
+    mappings,
+    result,
+    isLoading,
+    error,
+    handleFileSelect,
+    updateMapping,
+    startImport,
+    reset,
+    goBack,
+  }
+}
+
+export interface UseCSVExportOptions {
+  exportFn: () => Promise<Blob | string>
+  filename?: string
+}

package/src/useCSV.native.ts

@@ -0,0 +1,26 @@
+import { useState, useCallback } from 'react'
+import type { UseCSVExportOptions } from './useCSV-core'
+
+// Types + the platform-neutral useCSVImport state machine live in the core.
+export * from './useCSV-core'
+
+/**
+ * useCSVExport — React Native stub.
+ *
+ * The web version triggers a browser file download (Blob + anchor click), which
+ * has no direct React Native equivalent. Rather than silently no-op, exportCSV
+ * fails loud so callers wire up a native save/share flow (expo-file-system +
+ * expo-sharing) explicitly. Metro resolves this file over useCSV.ts on native.
+ */
+export function useCSVExport({ exportFn: _exportFn, filename: _filename }: UseCSVExportOptions) {
+  const [isExporting] = useState(false)
+
+  const exportCSV = useCallback(async () => {
+    throw new Error(
+      'useCSVExport: browser-download export is web-only. On React Native, ' +
+        'save the CSV with expo-file-system and share it via expo-sharing.'
+    )
+  }, [])
+
+  return { exportCSV, isExporting }
+}

package/src/useCSV.ts

@@ -1,140 +1,16 @@
 import { useState, useCallback } from 'react'
-
-export interface CSVColumnMapping {
-  csvColumn: string
-  targetField: string
-}
-
-export interface CSVPreviewResult<TField extends string = string> {
-  columns: string[]
-  sampleRows: Record<string, string>[]
-  suggestedMappings?: CSVColumnMapping[]
-  totalRows?: number
-}
-
-export interface CSVImportResult {
-  totalRows: number
-  successful: number
-  failed: number
-  errors: Array<{ row: number; message: string }>
-}
-
-export type CSVImportStep = 'upload' | 'mapping' | 'importing' | 'complete'
-
-export interface UseCSVImportOptions<TField extends string = string> {
-  previewFn: (file: File) => Promise<CSVPreviewResult<TField>>
-  importFn: (file: File, mappings: CSVColumnMapping[]) => Promise<CSVImportResult>
-  onSuccess?: (result: CSVImportResult) => void
-}
-
-export interface UseCSVImportState {
-  step: CSVImportStep
-  file: File | null
-  preview: CSVPreviewResult | null
-  mappings: CSVColumnMapping[]
-  result: CSVImportResult | null
-  isLoading: boolean
-  error: string | null
-  handleFileSelect: (file: File) => Promise<void>
-  updateMapping: (csvColumn: string, targetField: string) => void
-  startImport: () => Promise<void>
-  reset: () => void
-  goBack: () => void
-}
-
-export function useCSVImport<TField extends string = string>({
-  previewFn,
-  importFn,
-  onSuccess,
-}: UseCSVImportOptions<TField>): UseCSVImportState {
-  const [step, setStep] = useState<CSVImportStep>('upload')
-  const [file, setFile] = useState<File | null>(null)
-  const [preview, setPreview] = useState<CSVPreviewResult | null>(null)
-  const [mappings, setMappings] = useState<CSVColumnMapping[]>([])
-  const [result, setResult] = useState<CSVImportResult | null>(null)
-  const [isLoading, setIsLoading] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-
-  const handleFileSelect = useCallback(
-    async (selectedFile: File) => {
-      setFile(selectedFile)
-      setError(null)
-      setIsLoading(true)
-      try {
-        const previewData = await previewFn(selectedFile)
-        setPreview(previewData)
-        setMappings(previewData.suggestedMappings ?? [])
-        setStep('mapping')
-      } catch {
-        setError('Failed to preview CSV file')
-      } finally {
-        setIsLoading(false)
-      }
-    },
-    [previewFn]
-  )
-
-  const updateMapping = useCallback((csvColumn: string, targetField: string) => {
-    setMappings((prev) => {
-      const existing = prev.find((m) => m.csvColumn === csvColumn)
-      if (existing) {
-        return prev.map((m) =>
-          m.csvColumn === csvColumn ? { ...m, targetField: targetField } : m
-        )
-      }
-      return [...prev, { csvColumn: csvColumn, targetField: targetField }]
-    })
-  }, [])
-
-  const startImport = useCallback(async () => {
-    if (!file) return
-    setStep('importing')
-    setError(null)
-    try {
-      const importResult = await importFn(file, mappings)
-      setResult(importResult)
-      setStep('complete')
-      onSuccess?.(importResult)
-    } catch {
-      setError('Failed to import CSV')
-      setStep('mapping')
-    }
-  }, [file, mappings, importFn, onSuccess])
-
-  const reset = useCallback(() => {
-    setStep('upload')
-    setFile(null)
-    setPreview(null)
-    setMappings([])
-    setResult(null)
-    setError(null)
-  }, [])
-
-  const goBack = useCallback(() => {
-    if (step === 'mapping') setStep('upload')
-  }, [step])
-
-  return {
-    step,
-    file,
-    preview,
-    mappings,
-    result,
-    isLoading,
-    error,
-    handleFileSelect,
-    updateMapping,
-    startImport,
-    reset,
-    goBack,
-  }
-}
-
-export interface UseCSVExportOptions {
-  exportFn: () => Promise<Blob | string>
-  filename?: string
-}
-
+import type { UseCSVExportOptions } from './useCSV-core'
+
+// Types + the platform-neutral useCSVImport state machine live in the core.
+export * from './useCSV-core'
+
+/**
+ * useCSVExport — web implementation.
+ *
+ * Builds a Blob and triggers a browser download via an anchor click. This is
+ * inherently DOM-bound; React Native resolves useCSV.native.ts instead (which
+ * throws, since downloading a file has no direct RN equivalent).
+ */
 export function useCSVExport({ exportFn, filename = 'export.csv' }: UseCSVExportOptions) {
   const [isExporting, setIsExporting] = useState(false)
 

package/src/usePresentations.ts

@@ -0,0 +1,120 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import type {
+  PresentationsApi,
+  DeckInput,
+  DeckListParams,
+  DeckStatus,
+  GenerateDeckInput,
+  RegenerateSlideInput,
+  SlideInput,
+} from '@startsimpli/api'
+
+/** TanStack Query hooks over PresentationsApi (epic startsim-3ks).
+ *
+ * Each hook takes the PresentationsApi instance (e.g. `api.presentations`),
+ * matching the useVault / useMessages convention. Generation + compile are
+ * async on the backend, so the deck detail and the lightweight status query
+ * are invalidated together and the status query self-polls while in flight.
+ */
+
+const DECKS_KEY = ['presentations', 'decks'] as const
+const deckKey = (id: string) => ['presentations', 'deck', id]
+const deckStatusKey = (id: string) => ['presentations', 'deck-status', id]
+
+const POLL_MS = 1500
+
+/** Refetch interval for the status query: poll while work is in flight. */
+export function deckStatusRefetchInterval(status: DeckStatus | undefined): number | false {
+  return status === 'generating' || status === 'draft' ? POLL_MS : false
+}
+
+function invalidateDeck(qc: ReturnType<typeof useQueryClient>, id: string) {
+  qc.invalidateQueries({ queryKey: deckKey(id) })
+  qc.invalidateQueries({ queryKey: deckStatusKey(id) })
+  qc.invalidateQueries({ queryKey: DECKS_KEY })
+}
+
+// --- Decks ---
+export function useDecks(api: PresentationsApi, params?: DeckListParams) {
+  return useQuery({
+    queryKey: ['presentations', 'decks', params],
+    queryFn: () => api.listDecks(params),
+  })
+}
+
+export function useDeck(api: PresentationsApi, id: string) {
+  return useQuery({
+    queryKey: deckKey(id),
+    queryFn: () => api.getDeck(id),
+    enabled: !!id,
+  })
+}
+
+/** Self-polling per-slide generation status; stops when ready/error. */
+export function useDeckStatus(api: PresentationsApi, id: string, enabled = true) {
+  return useQuery({
+    queryKey: deckStatusKey(id),
+    queryFn: () => api.getDeckStatus(id),
+    enabled: enabled && !!id,
+    refetchInterval: (query) => deckStatusRefetchInterval(query.state.data?.status),
+  })
+}
+
+export function useCreateDeck(api: PresentationsApi) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (data: DeckInput) => api.createDeck(data),
+    onSuccess: () => qc.invalidateQueries({ queryKey: DECKS_KEY }),
+  })
+}
+
+export function useUpdateDeck(api: PresentationsApi, id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (data: Partial<DeckInput>) => api.updateDeck(id, data),
+    onSuccess: () => invalidateDeck(qc, id),
+  })
+}
+
+export function useDeleteDeck(api: PresentationsApi) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => api.deleteDeck(id),
+    onSuccess: () => qc.invalidateQueries({ queryKey: DECKS_KEY }),
+  })
+}
+
+// --- Generation pipeline ---
+export function useGenerateDeck(api: PresentationsApi, id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (data?: GenerateDeckInput) => api.generateDeck(id, data),
+    onSuccess: () => invalidateDeck(qc, id),
+  })
+}
+
+export function useRegenerateSlide(api: PresentationsApi, id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: ({ slideNumber, ...data }: { slideNumber: number } & RegenerateSlideInput) =>
+      api.regenerateSlide(id, slideNumber, data),
+    onSuccess: () => invalidateDeck(qc, id),
+  })
+}
+
+export function useUpdateSlide(api: PresentationsApi, id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: ({ slideNumber, ...data }: { slideNumber: number } & SlideInput) =>
+      api.updateSlide(id, slideNumber, data),
+    onSuccess: () => invalidateDeck(qc, id),
+  })
+}
+
+export function useCompileDeck(api: PresentationsApi, id: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: () => api.compileDeck(id),
+    onSuccess: () => invalidateDeck(qc, id),
+  })
+}

package/src/useRecentlyViewed.native.ts

@@ -0,0 +1,56 @@
+import { useState, useCallback, useEffect } from 'react'
+
+interface StoredItem<T> {
+  item: T
+  viewedAt: number
+}
+
+/**
+ * useRecentlyViewed — React Native implementation.
+ *
+ * Web persists to localStorage. React Native has no synchronous storage, so this
+ * keeps an in-memory store keyed by storageKey at module scope — which mirrors
+ * localStorage's app-wide sharing within a session but does NOT survive an app
+ * restart. Persistence across launches needs an async backend (AsyncStorage);
+ * tracked as a follow-up (startsim-sw1.5 notes). Metro resolves this file over
+ * useRecentlyViewed.ts on native builds.
+ */
+const memoryStore = new Map<string, StoredItem<unknown>[]>()
+
+export function useRecentlyViewed<T extends { id: string }>(
+  storageKey: string,
+  maxItems: number = 5
+) {
+  const [items, setItems] = useState<StoredItem<T>[]>(
+    () => (memoryStore.get(storageKey) as StoredItem<T>[]) ?? []
+  )
+
+  // Re-sync if the key changes.
+  useEffect(() => {
+    setItems((memoryStore.get(storageKey) as StoredItem<T>[]) ?? [])
+  }, [storageKey])
+
+  const trackView = useCallback(
+    (item: T) => {
+      setItems((prev) => {
+        const deduped = prev.filter((entry) => entry.item.id !== item.id)
+        const updated = [{ item, viewedAt: Date.now() }, ...deduped].slice(0, maxItems)
+        memoryStore.set(storageKey, updated as StoredItem<unknown>[])
+        return updated
+      })
+    },
+    [maxItems, storageKey]
+  )
+
+  const clear = useCallback(() => {
+    setItems([])
+    memoryStore.delete(storageKey)
+  }, [storageKey])
+
+  return {
+    items: items.map((entry) => entry.item),
+    timestamps: items.map((entry) => ({ id: entry.item.id, viewedAt: entry.viewedAt })),
+    trackView,
+    clear,
+  }
+}