prev-cli 0.24.20 → 0.25.0

package/src/theme/Preview.tsx

@@ -10,6 +10,7 @@ interface PreviewProps {
   title?: string
   mode?: 'wasm' | 'legacy'
   showHeader?: boolean // Show full header with back button and devtools
+  state?: string | null // Optional state name for screen previews
 }
 
 type DeviceMode = 'mobile' | 'tablet' | 'desktop'
@@ -20,7 +21,7 @@ const DEVICE_WIDTHS: Record<DeviceMode, number | '100%'> = {
   desktop: '100%',
 }
 
-export function Preview({ src, height = 400, title, mode = 'wasm', showHeader = false }: PreviewProps) {
+export function Preview({ src, height = 400, title, mode = 'wasm', showHeader = false, state = null }: PreviewProps) {
   const [isFullscreen, setIsFullscreen] = useState(false)
   // Default to 'mobile' device mode on mobile viewports to match user's actual environment
   const [deviceMode, setDeviceMode] = useState<DeviceMode>(() => {
@@ -42,14 +43,19 @@ export function Preview({ src, height = 400, title, mode = 'wasm', showHeader =
 
   // In production, always use pre-built static previews
   // In dev, use WASM runtime for live bundling
-  const isDev = import.meta.env?.DEV ?? false
+  const isDev = import.meta.env.DEV ?? false
   const effectiveMode = isDev ? mode : 'legacy'
 
   // Get base URL for proper subpath deployment support
-  const baseUrl = (import.meta.env?.BASE_URL ?? '/').replace(/\/$/, '')
+  const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/$/, '')
 
   // URL depends on mode - wasm mode needs src param, legacy uses pre-built files
-  const previewUrl = effectiveMode === 'wasm' ? `/_preview-runtime?src=${src}` : `${baseUrl}/_preview/${src}/`
+  // Include state parameter if provided (for screen previews with multiple states)
+  const stateParam = state ? `&state=${state}` : ''
+  const stateUrlPart = state ? `?state=${state}` : ''
+  const previewUrl = effectiveMode === 'wasm'
+    ? `/_preview-runtime?src=${src}${stateParam}`
+    : `${baseUrl}/_preview/${src}/${stateUrlPart}`
   const displayTitle = title || src
 
   // Calculate current width

package/src/theme/Toolbar.tsx

@@ -1,7 +1,7 @@
 import React, { useState, useRef, useEffect } from 'react'
 import { Link, useLocation } from '@tanstack/react-router'
 import type { PageTree } from 'fumadocs-core/server'
-import { previews } from 'virtual:prev-previews'
+import { previewUnits } from 'virtual:prev-previews'
 import { Icon } from './icons'
 import { useDevTools } from './DevToolsContext'
 import './Toolbar.css'
@@ -76,7 +76,7 @@ export function Toolbar({ tree, onThemeToggle, onWidthToggle, isDark, isFullWidt
         <Icon name="menu" size={18} />
       </button>
 
-      {previews && previews.length > 0 && (
+      {previewUnits && previewUnits.length > 0 && (
         <Link to="/previews" className={`toolbar-btn ${isOnPreviews ? 'active' : ''}`} title="Previews">
           <Icon name="grid" size={18} />
         </Link>

package/src/theme/entry.tsx

@@ -15,8 +15,8 @@ import {
 import { MDXProvider } from '@mdx-js/react'
 import { pages, sidebar } from 'virtual:prev-pages'
 import { pageModules } from 'virtual:prev-page-modules'
-import { previews, previewUnits } from 'virtual:prev-previews'
-import type { PreviewUnit, PreviewType } from '../vite/preview-types'
+import { previewUnits } from 'virtual:prev-previews'
+import type { PreviewUnit, PreviewType } from '../content/preview-types'
 import { Preview } from './Preview'
 import { TokensPage } from './previews/TokensPage'
 import { useDiagrams } from './diagrams'
@@ -24,6 +24,9 @@ import { Layout } from './Layout'
 import { MetadataBlock } from './MetadataBlock'
 import { mdxComponents } from './mdx-components'
 import { DevToolsProvider } from './DevToolsContext'
+import { StatusBadge } from './previews/StatusBadge'
+import { useApprovalStatus } from './hooks/useApprovalStatus'
+import { SnapshotCompare } from './previews/SnapshotCompare'
 import './styles.css'
 
 // PageTree types (simplified from fumadocs-core)
@@ -110,15 +113,10 @@ const CATEGORY_META: Record<PreviewType, { label: string; icon: string; descript
     icon: '⇢',
     description: 'Multi-step user journeys',
   },
-  atlas: {
-    label: 'Atlas',
-    icon: '◎',
-    description: 'Information architecture maps',
-  },
 }
 
 // Category display order
-const CATEGORY_ORDER: PreviewType[] = ['component', 'screen', 'flow', 'atlas']
+const CATEGORY_ORDER: PreviewType[] = ['component', 'screen', 'flow']
 
 // Group previews by type
 function groupByType(units: PreviewUnit[]): Map<PreviewType, PreviewUnit[]> {
@@ -130,50 +128,55 @@ function groupByType(units: PreviewUnit[]): Map<PreviewType, PreviewUnit[]> {
   return grouped
 }
 
-// Category section component
+// Category section component with carousel navigation
 function CategorySection({ type, units }: { type: PreviewType; units: PreviewUnit[] }) {
   const meta = CATEGORY_META[type]
+  const scrollRef = React.useRef<HTMLDivElement>(null)
+
+  const scroll = (direction: 'left' | 'right') => {
+    const container = scrollRef.current
+    if (!container) return
+    const cardWidth = 280 + 16 // card width + gap
+    const scrollAmount = direction === 'left' ? -cardWidth : cardWidth
+    container.scrollBy({ left: scrollAmount, behavior: 'smooth' })
+  }
 
   return (
-    <section style={{ marginBottom: '32px' }}>
-      <div style={{
-        display: 'flex',
-        alignItems: 'center',
-        gap: '10px',
-        marginBottom: '16px',
-        paddingBottom: '12px',
-        borderBottom: '1px solid var(--fd-border)',
-      }}>
-        <span style={{ fontSize: '20px' }}>{meta.icon}</span>
-        <div>
-          <h2 style={{
-            fontSize: '18px',
-            fontWeight: '600',
-            margin: 0,
-            color: 'var(--fd-foreground)',
-          }}>
+    <section className="category-section">
+      <div className="category-header">
+        <span className="category-icon">{meta.icon}</span>
+        <div className="category-info">
+          <h2 className="category-title">
             {meta.label}
-            <span style={{
-              marginLeft: '8px',
-              fontSize: '14px',
-              fontWeight: '400',
-              color: 'var(--fd-muted-foreground)',
-            }}>
-              ({units.length})
-            </span>
+            <span className="category-count">({units.length})</span>
           </h2>
-          <p style={{
-            fontSize: '13px',
-            color: 'var(--fd-muted-foreground)',
-            margin: 0,
-          }}>
-            {meta.description}
-          </p>
+          <p className="category-description">{meta.description}</p>
+        </div>
+        <div className="category-nav">
+          <button
+            type="button"
+            className="category-nav-btn"
+            onClick={() => scroll('left')}
+            aria-label="Previous"
+          >
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+              <path d="M15 18l-6-6 6-6" />
+            </svg>
+          </button>
+          <button
+            type="button"
+            className="category-nav-btn"
+            onClick={() => scroll('right')}
+            aria-label="Next"
+          >
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+              <path d="M9 18l6-6-6-6" />
+            </svg>
+          </button>
         </div>
       </div>
-      <div className="previews-grid">
+      <div className="previews-grid" ref={scrollRef}>
         {units.map((unit) => {
-          // Extract full path name from route (e.g., "/_preview/components/button" -> "components/button")
           const fullName = unit.route.replace(/^\/_preview\//, '')
           return (
             <PreviewCard
@@ -181,6 +184,7 @@ function CategorySection({ type, units }: { type: PreviewType; units: PreviewUni
               name={fullName}
               title={unit.config?.title}
               status={unit.config?.status}
+              type={unit.type}
             />
           )
         })}
@@ -191,21 +195,9 @@ function CategorySection({ type, units }: { type: PreviewType; units: PreviewUni
 
 // Previews catalog - Storybook-like gallery with categorized sections
 function PreviewsCatalog() {
-  // Use previewUnits for categorization, fall back to legacy previews
   const units = previewUnits || []
-  const legacyPreviews = previews || []
-
-  // If no units but have legacy previews, convert them
-  const allUnits: PreviewUnit[] = units.length > 0 ? units : legacyPreviews.map((p: { name: string; route: string }) => ({
-    type: 'component' as PreviewType,
-    name: p.name,
-    path: '',
-    route: p.route,
-    config: null,
-    files: { index: '' },
-  }))
-
-  if (allUnits.length === 0) {
+
+  if (units.length === 0) {
     return (
       <div style={{ padding: '40px 20px', textAlign: 'center' }}>
         <h1 style={{ fontSize: '24px', fontWeight: 'bold', marginBottom: '16px' }}>
@@ -227,19 +219,16 @@ function PreviewsCatalog() {
     )
   }
 
-  const grouped = groupByType(allUnits)
-  const totalCount = allUnits.length
+  const grouped = groupByType(units)
+  const totalCount = units.length
 
   return (
     <div className="previews-catalog">
       {/* Header */}
-      <div style={{ marginBottom: '32px' }}>
-        <h1 style={{ fontSize: '28px', fontWeight: 'bold', marginBottom: '8px' }}>
-          Previews
-        </h1>
-        <p style={{ color: 'var(--fd-muted-foreground)', margin: 0 }}>
-          {totalCount} preview{totalCount !== 1 ? 's' : ''} across {grouped.size} categor{grouped.size !== 1 ? 'ies' : 'y'}.
-          Click any preview to open it.
+      <div className="catalog-header">
+        <h1 className="catalog-title">Previews</h1>
+        <p className="catalog-subtitle">
+          {totalCount} preview{totalCount !== 1 ? 's' : ''} across {grouped.size} categor{grouped.size !== 1 ? 'ies' : 'y'}
         </p>
       </div>
 
@@ -250,19 +239,11 @@ function PreviewsCatalog() {
         return <CategorySection key={type} type={type} units={units} />
       })}
 
-      {/* Tip */}
-      <div style={{
-        marginTop: '32px',
-        padding: '14px 16px',
-        backgroundColor: 'var(--fd-muted)',
-        border: '1px solid var(--fd-border)',
-        borderRadius: '10px',
-      }}>
-        <p style={{ margin: 0, fontSize: '14px', color: 'var(--fd-muted-foreground)' }}>
-          <strong style={{ color: 'var(--fd-foreground)' }}>Tip:</strong> Embed any preview in your MDX docs with{' '}
-          <code style={{ backgroundColor: 'var(--fd-accent)', padding: '2px 6px', borderRadius: '4px', fontFamily: 'var(--fd-font-mono)' }}>
-            {'<Preview src="name" />'}
-          </code>
+      {/* Tip - hidden on mobile */}
+      <div className="catalog-tip">
+        <p>
+          <strong>Tip:</strong> Embed any preview in your MDX docs with{' '}
+          <code>{'<Preview src="name" />'}</code>
         </p>
       </div>
     </div>
@@ -272,38 +253,36 @@ function PreviewsCatalog() {
 // Individual preview card - clickable thumbnail with WASM preview communication
 import type { PreviewConfig, PreviewMessage } from '../preview-runtime/types'
 
-function PreviewCard({ name, title, status }: { name: string; title?: string; status?: 'draft' | 'stable' | 'deprecated' }) {
+function PreviewCard({ name, title, status, type }: { name: string; title?: string; status?: 'draft' | 'stable' | 'deprecated'; type?: PreviewType }) {
+  const { status: approvalStatus } = useApprovalStatus(name)
+  // Config-only types (flow) have no JS entry point — show a styled placeholder instead of iframe
+  const isConfigOnly = type === 'flow'
+
   const iframeRef = React.useRef<HTMLIFrameElement>(null)
-  const [isLoaded, setIsLoaded] = React.useState(false)
+  // In production, start as loaded since static files are fast
+  const isDev = import.meta.env.DEV ?? false
+  const [isLoaded, setIsLoaded] = React.useState(!isDev || isConfigOnly)
   const [loadError, setLoadError] = React.useState(false)
 
-  // In production, use pre-built static files; in dev, use WASM runtime
-  const isDev = import.meta.env?.DEV ?? false
-  const baseUrl = (import.meta.env?.BASE_URL ?? '/').replace(/\/$/, '')
-  const previewUrl = isDev ? `/_preview-runtime?src=${name}` : `${baseUrl}/_preview/${name}/`
+  const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/$/, '')
+  const previewUrl = isConfigOnly ? '' : (isDev ? `/_preview-runtime?src=${name}` : `${baseUrl}/_preview/${name}/`)
 
-  // Timeout for loading - show placeholder if too slow
+  // Timeout for loading - only needed in dev mode
   React.useEffect(() => {
+    if (!isDev || isConfigOnly) return
+
     const timeout = setTimeout(() => {
       if (!isLoaded) {
         setLoadError(true)
       }
-    }, 5000) // 5 second timeout
+    }, 5000)
 
     return () => clearTimeout(timeout)
-  }, [isLoaded])
+  }, [isLoaded, isDev, isConfigOnly])
 
   // Set up WASM preview communication for thumbnail (dev mode only)
   React.useEffect(() => {
-    if (!isDev) {
-      // In production, just mark as loaded when iframe loads
-      const iframe = iframeRef.current
-      if (iframe) {
-        iframe.onload = () => setIsLoaded(true)
-        iframe.onerror = () => setLoadError(true)
-      }
-      return
-    }
+    if (!isDev || isConfigOnly) return
 
     const iframe = iframeRef.current
     if (!iframe) return
@@ -346,35 +325,46 @@ function PreviewCard({ name, title, status }: { name: string; title?: string; st
     <Link to={`/previews/${name}`} className="preview-card">
       {/* Thumbnail preview */}
       <div className="preview-card-thumbnail">
-        {/* Loading state */}
-        {!isLoaded && !loadError && (
-          <div className="preview-card-loading">
-            <div className="preview-card-spinner" />
-          </div>
-        )}
-        {/* Error/timeout placeholder */}
-        {loadError && (
-          <div className="preview-card-placeholder">
-            <svg width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
-              <rect x="3" y="3" width="18" height="18" rx="2" />
-              <path d="M9 9l6 6m0-6l-6 6" />
-            </svg>
-            <span>Preview</span>
+        {isConfigOnly ? (
+          /* Config-only types: styled placeholder with category icon */
+          <div className="preview-card-placeholder" style={{ opacity: 1 }}>
+            <span style={{ fontSize: '32px' }}>⇢</span>
+            <span>Flow</span>
           </div>
+        ) : (
+          <>
+            {/* Loading state */}
+            {!isLoaded && !loadError && (
+              <div className="preview-card-loading">
+                <div className="preview-card-spinner" />
+              </div>
+            )}
+            {/* Error/timeout placeholder */}
+            {loadError && (
+              <div className="preview-card-placeholder">
+                <svg width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
+                  <rect x="3" y="3" width="18" height="18" rx="2" />
+                  <path d="M9 9l6 6m0-6l-6 6" />
+                </svg>
+                <span>Preview</span>
+              </div>
+            )}
+            <iframe
+              ref={iframeRef}
+              src={previewUrl}
+              className="preview-card-iframe"
+              style={{ opacity: isLoaded && !loadError ? 1 : 0 }}
+              title={name}
+              loading="lazy"
+            />
+          </>
         )}
-        <iframe
-          ref={iframeRef}
-          src={previewUrl}
-          className="preview-card-iframe"
-          style={{ opacity: isLoaded && !loadError ? 1 : 0 }}
-          title={name}
-          loading="lazy"
-        />
       </div>
       {/* Card footer */}
       <div className="preview-card-footer">
         <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
           <h3 className="preview-card-title">{title || name}</h3>
+          <StatusBadge status={approvalStatus} compact />
           {status && status !== 'stable' && (
             <span style={{
               fontSize: '10px',
@@ -396,18 +386,132 @@ function PreviewCard({ name, title, status }: { name: string; title?: string; st
 }
 
 // Individual preview page - full view with devtools in toolbar
+// Uses specialized component for flow, generic Preview for components/screens
+import { FlowPreview } from './previews/FlowPreview'
+
+// Standalone preview embed (for iframe thumbnails in production)
+// Renders just the preview content without Layout wrapper
+function PreviewEmbed() {
+  const params = useParams({ strict: false })
+  const name = (params as any)['_splat'] || (params as any)['*'] || ''
+
+  // In production, always use pre-built static files
+  const isDev = import.meta.env.DEV ?? false
+  const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/$/, '')
+
+  // Parse type from name (e.g., "flows/checkout" -> type="flow", unitName="checkout")
+  const match = name.match(/^(components|screens|flows)\/(.+)$/)
+  if (!match) {
+    // Fallback for legacy preview paths without type prefix
+    const previewUrl = isDev ? `/_preview-runtime?src=${name}` : `${baseUrl}/_preview/${name}/`
+    return (
+      <iframe
+        src={previewUrl}
+        style={{ width: '100%', height: '100vh', border: 'none' }}
+        title={name}
+      />
+    )
+  }
+
+  const [, typeFolder, unitName] = match
+  const type = typeFolder === 'flows' ? 'flow' : typeFolder.slice(0, -1)
+
+  // Find the preview unit
+  const unit = previewUnits.find(u => u.type === type && u.name === unitName)
+
+  if (!unit) {
+    return (
+      <div style={{ padding: '32px', textAlign: 'center', color: '#888' }}>
+        Preview not found: {name}
+      </div>
+    )
+  }
+
+  // For flows, render the specialized component
+  if (unit.type === 'flow') {
+    return <FlowPreview unit={unit} />
+  }
+
+  // For components and screens, use iframe to load static HTML
+  const previewUrl = isDev ? `/_preview-runtime?src=${name}` : `${baseUrl}/_preview/${name}/`
+  return (
+    <iframe
+      src={previewUrl}
+      style={{ width: '100%', height: '100vh', border: 'none' }}
+      title={name}
+    />
+  )
+}
+
 function PreviewPage() {
   const params = useParams({ strict: false })
+  const location = useLocation()
   // Splat param captures the full path after /previews/
   const name = (params as any)['_splat'] || (params as any)['*'] || params.name as string
 
+  // Read deep link params from URL search
+  const searchParams = new URLSearchParams(location.search)
+  const urlState = searchParams.get('state')
+  const urlStep = searchParams.get('step')
+
+  const [selectedState, setSelectedState] = React.useState<string | null>(urlState)
+
   if (!name) {
     return <Navigate to="/previews" />
   }
 
+  // Find the preview unit to determine the type
+  const unit = previewUnits.find(u => {
+    // Match by route suffix (e.g., "flows/onboarding" matches route "/_preview/flows/onboarding")
+    return u.route.endsWith(`/${name}`) || `${u.type}s/${u.name}` === name
+  })
+
+  // For flows, use the specialized component
+  if (unit?.type === 'flow') {
+    return (
+      <div className="preview-detail-page">
+        <FlowPreview unit={unit} initialStep={urlStep || undefined} />
+      </div>
+    )
+  }
+
+  // Get states for screens
+  const states = unit?.files?.states || []
+  const hasStates = states.length > 0
+
+  // For components and screens, use the generic Preview with iframe
   return (
     <div className="preview-detail-page">
-      <Preview src={name} height="100%" showHeader />
+      {/* State selector for screens with multiple states */}
+      {hasStates && (
+        <div className="preview-state-selector">
+          <span className="preview-state-label">State:</span>
+          <div className="preview-state-buttons">
+            <button
+              type="button"
+              className={`preview-state-btn ${selectedState === null ? 'active' : ''}`}
+              onClick={() => setSelectedState(null)}
+            >
+              Default
+            </button>
+            {states.map((stateFile: string) => {
+              const stateName = stateFile.replace(/\.(tsx|jsx)$/, '')
+              const isSelected = selectedState === stateName
+              return (
+                <button
+                  key={stateFile}
+                  type="button"
+                  className={`preview-state-btn ${isSelected ? 'active' : ''}`}
+                  onClick={() => setSelectedState(stateName)}
+                >
+                  {stateName.replace(/[-_]/g, ' ')}
+                </button>
+              )
+            })}
+          </div>
+        </div>
+      )}
+      <Preview src={name} state={selectedState} height="100%" showHeader />
     </div>
   )
 }
@@ -469,6 +573,14 @@ const tokensRoute = createRoute({
   component: TokensPage,
 })
 
+// Standalone preview embed route (handles /_preview/flows/checkout, /_preview/atlas/app, etc.)
+// This is used when thumbnails load as iframes - the 404.html serves the SPA which matches this route
+const previewEmbedRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/_preview/$',
+  component: PreviewEmbed,
+})
+
 // Check if we have an index page (route '/')
 const hasIndexPage = pages.some((page: { route: string }) => page.route === '/')
 const firstPage = pages[0] as { route: string; file: string; title?: string; description?: string; frontmatter?: Record<string, unknown> } | undefined
@@ -502,20 +614,34 @@ function NotFoundPage() {
 }
 
 // Create router with notFoundRoute
+// Snapshot compare route
+function ComparePageComponent() {
+  const params = new URLSearchParams(window.location.search)
+  return <SnapshotCompare leftId={params.get('left') || undefined} rightId={params.get('right') || undefined} />
+}
+
+const compareRoute = createRoute({
+  getParentRoute: () => previewsLayoutRoute,
+  path: '_compare',
+  component: ComparePageComponent,
+})
+
 // Previews routes: layout with catalog (index) and detail (splat) children
 const previewsRouteWithChildren = previewsLayoutRoute.addChildren([
   previewsCatalogRoute,
+  compareRoute,
   previewDetailRoute,
 ])
 
 const routeTree = rootRoute.addChildren([
   previewsRouteWithChildren,
   tokensRoute,
+  previewEmbedRoute,
   ...(indexRedirectRoute ? [indexRedirectRoute] : []),
   ...pageRoutes,
 ])
 // Get base path for subpath deployments (e.g., GitHub Pages)
-const basepath = (import.meta.env?.BASE_URL ?? '/').replace(/\/$/, '') || '/'
+const basepath = (import.meta.env.BASE_URL ?? '/').replace(/\/$/, '') || '/'
 
 const router = createRouter({
   routeTree,

package/src/theme/hooks/useAnnotations.ts

@@ -0,0 +1,77 @@
+import { useState, useCallback } from 'react'
+import { storage } from '../storage'
+import type { Annotation, AnnotationComment, AnnotationCategory, UserIdentity } from '../types'
+
+export function useAnnotations(previewName: string, stateOrStep: string) {
+  const storageKey = `annotations:${previewName}`
+
+  const [annotations, setAnnotations] = useState<Annotation[]>(
+    () => storage.get<Annotation[]>(storageKey) ?? []
+  )
+
+  const persist = (updated: Annotation[]) => {
+    storage.set(storageKey, updated)
+    setAnnotations(updated)
+  }
+
+  const getUser = (): string => {
+    const user = storage.get<UserIdentity>('user')
+    return user?.name || 'Anonymous'
+  }
+
+  const createAnnotation = useCallback((
+    x: number,
+    y: number,
+    category: AnnotationCategory,
+    text: string,
+  ) => {
+    const now = new Date().toISOString()
+    const annotation: Annotation = {
+      id: crypto.randomUUID(),
+      previewName,
+      stateOrStep,
+      x,
+      y,
+      category,
+      resolved: false,
+      createdAt: now,
+      comments: [{
+        id: crypto.randomUUID(),
+        author: getUser(),
+        text,
+        createdAt: now,
+      }],
+    }
+    const current = storage.get<Annotation[]>(storageKey) ?? []
+    persist([...current, annotation])
+  }, [previewName, stateOrStep, storageKey])
+
+  const addComment = useCallback((annotationId: string, text: string) => {
+    const current = storage.get<Annotation[]>(storageKey) ?? []
+    const comment: AnnotationComment = {
+      id: crypto.randomUUID(),
+      author: getUser(),
+      text,
+      createdAt: new Date().toISOString(),
+    }
+    persist(current.map(a =>
+      a.id === annotationId
+        ? { ...a, comments: [...a.comments, comment] }
+        : a
+    ))
+  }, [storageKey])
+
+  const resolveAnnotation = useCallback((annotationId: string) => {
+    const current = storage.get<Annotation[]>(storageKey) ?? []
+    persist(current.map(a =>
+      a.id === annotationId ? { ...a, resolved: !a.resolved } : a
+    ))
+  }, [storageKey])
+
+  const deleteAnnotation = useCallback((annotationId: string) => {
+    const current = storage.get<Annotation[]>(storageKey) ?? []
+    persist(current.filter(a => a.id !== annotationId))
+  }, [storageKey])
+
+  return { annotations, createAnnotation, addComment, resolveAnnotation, deleteAnnotation }
+}