annotate-kit 0.1.0

package/src/ScreenshotEditor.tsx

@@ -0,0 +1,195 @@
+// A tiny markup editor: draw pen / rectangle / arrow strokes onto a captured screenshot, then copy or
+// download the flattened image. Self-contained — one <canvas>, no dependencies beyond React + icons.
+import { useEffect, useRef, useState, type PointerEvent as ReactPointerEvent } from 'react'
+import { X, Pencil, Square, ArrowUpRight, Undo2, Trash2, Copy, Download } from 'lucide-react'
+
+type Tool = 'pen' | 'rect' | 'arrow'
+type Pt = { x: number; y: number }
+type Shape =
+  | { tool: 'pen'; color: string; pts: Pt[] }
+  | { tool: 'rect' | 'arrow'; color: string; x: number; y: number; x2: number; y2: number }
+
+const COLORS = ['#ef4444', '#f59e0b', '#22c55e', '#3b82f6', '#111827', '#ffffff']
+
+function drawShape(ctx: CanvasRenderingContext2D, s: Shape) {
+  ctx.strokeStyle = s.color
+  ctx.fillStyle = s.color
+  ctx.lineWidth = Math.max(3, ctx.canvas.width / 400)
+  ctx.lineJoin = 'round'
+  ctx.lineCap = 'round'
+  if (s.tool === 'pen') {
+    ctx.beginPath()
+    s.pts.forEach((p, i) => (i ? ctx.lineTo(p.x, p.y) : ctx.moveTo(p.x, p.y)))
+    ctx.stroke()
+  } else if (s.tool === 'rect') {
+    ctx.strokeRect(Math.min(s.x, s.x2), Math.min(s.y, s.y2), Math.abs(s.x2 - s.x), Math.abs(s.y2 - s.y))
+  } else {
+    ctx.beginPath(); ctx.moveTo(s.x, s.y); ctx.lineTo(s.x2, s.y2); ctx.stroke()
+    const ang = Math.atan2(s.y2 - s.y, s.x2 - s.x)
+    const h = Math.max(12, ctx.lineWidth * 4)
+    ctx.beginPath(); ctx.moveTo(s.x2, s.y2)
+    ctx.lineTo(s.x2 - h * Math.cos(ang - Math.PI / 6), s.y2 - h * Math.sin(ang - Math.PI / 6))
+    ctx.lineTo(s.x2 - h * Math.cos(ang + Math.PI / 6), s.y2 - h * Math.sin(ang + Math.PI / 6))
+    ctx.closePath(); ctx.fill()
+  }
+}
+
+const TOOLS: { key: Tool; Icon: typeof Pencil; label: string }[] = [
+  { key: 'pen', Icon: Pencil, label: 'Draw' },
+  { key: 'rect', Icon: Square, label: 'Box' },
+  { key: 'arrow', Icon: ArrowUpRight, label: 'Arrow' },
+]
+
+export function ScreenshotEditor({ blob, onToast, onClose }: {
+  blob: Blob
+  onToast: (kind: 'success' | 'error', msg: string) => void
+  onClose: () => void
+}) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null)
+  const imgRef = useRef<HTMLImageElement | null>(null)
+  const drawingRef = useRef<Shape | null>(null)
+  const panelRef = useRef<HTMLDivElement | null>(null)
+  const [tool, setTool] = useState<Tool>('pen')
+  const [color, setColor] = useState(COLORS[0])
+  const [shapes, setShapes] = useState<Shape[]>([])
+  const [ready, setReady] = useState(false)
+
+  useEffect(() => {
+    const url = URL.createObjectURL(blob)
+    const img = new Image()
+    img.onload = () => { imgRef.current = img; setReady(true) }
+    img.src = url
+    return () => URL.revokeObjectURL(url)
+  }, [blob])
+
+  const redraw = () => {
+    const canvas = canvasRef.current
+    const img = imgRef.current
+    if (!canvas || !img) return
+    if (canvas.width !== img.naturalWidth) canvas.width = img.naturalWidth
+    if (canvas.height !== img.naturalHeight) canvas.height = img.naturalHeight
+    const ctx = canvas.getContext('2d')
+    if (!ctx) return
+    ctx.clearRect(0, 0, canvas.width, canvas.height)
+    ctx.drawImage(img, 0, 0)
+    const all = drawingRef.current ? [...shapes, drawingRef.current] : shapes
+    for (const s of all) drawShape(ctx, s)
+  }
+  useEffect(() => { redraw() }, [ready, shapes])   // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    const h = (e: KeyboardEvent) => { if (e.key === 'Escape') { e.stopPropagation(); onClose() } }
+    window.addEventListener('keydown', h, true)   // capture — Escape closes only the editor, not the host panel
+    return () => window.removeEventListener('keydown', h, true)
+  }, [onClose])
+
+  // focus trap (a11y)
+  useEffect(() => {
+    const el = panelRef.current
+    if (!el) return
+    const SEL = 'a[href],button:not([disabled]),input:not([disabled]),[tabindex]:not([tabindex="-1"])'
+    const list = () => Array.from(el.querySelectorAll<HTMLElement>(SEL)).filter((x) => x.offsetParent !== null)
+    ;(list()[0] ?? el).focus()
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return
+      const f = list()
+      if (!f.length) return
+      const first = f[0], last = f[f.length - 1]
+      if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus() }
+      else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus() }
+    }
+    el.addEventListener('keydown', onKey)
+    return () => el.removeEventListener('keydown', onKey)
+  }, [])
+
+  const toCanvas = (e: ReactPointerEvent): Pt => {
+    const canvas = canvasRef.current!
+    const r = canvas.getBoundingClientRect()
+    // map to the content box (exclude the 1px border via clientLeft/Top + clientWidth/Height)
+    return {
+      x: (e.clientX - r.left - canvas.clientLeft) * (canvas.width / canvas.clientWidth),
+      y: (e.clientY - r.top - canvas.clientTop) * (canvas.height / canvas.clientHeight),
+    }
+  }
+  const onDown = (e: ReactPointerEvent) => {
+    e.preventDefault()
+    const p = toCanvas(e)
+    drawingRef.current = tool === 'pen' ? { tool: 'pen', color, pts: [p] } : { tool, color, x: p.x, y: p.y, x2: p.x, y2: p.y }
+    try { (e.target as HTMLElement).setPointerCapture(e.pointerId) } catch { /* noop */ }
+  }
+  const onMove = (e: ReactPointerEvent) => {
+    const d = drawingRef.current
+    if (!d) return
+    const p = toCanvas(e)
+    if (d.tool === 'pen') d.pts.push(p)
+    else { d.x2 = p.x; d.y2 = p.y }
+    redraw()
+  }
+  const onUp = () => {
+    const d = drawingRef.current
+    if (d) { setShapes((s) => [...s, d]); drawingRef.current = null }
+  }
+
+  const exportBlob = (): Promise<Blob | null> =>
+    new Promise((res) => (canvasRef.current ? canvasRef.current.toBlob((b) => res(b), 'image/png') : res(null)))
+
+  const copy = async () => {
+    const b = await exportBlob()
+    if (b && navigator.clipboard && typeof window.ClipboardItem === 'function') {
+      try { await navigator.clipboard.write([new window.ClipboardItem({ 'image/png': b })]); onToast('success', 'Marked-up image copied — paste anywhere'); onClose(); return } catch { /* fall through */ }
+    }
+    onToast('error', 'Clipboard blocked — use Download')
+  }
+  const download = async () => {
+    const b = await exportBlob()
+    if (!b) return
+    const url = URL.createObjectURL(b)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = `markup-${new Date().toISOString().slice(0, 19).replace(/[:T]/g, '-')}.png`
+    a.click()
+    setTimeout(() => URL.revokeObjectURL(url), 1000)
+    onToast('success', 'Marked-up image downloaded')
+    onClose()
+  }
+
+  const btn = 'inline-flex items-center gap-1 rounded-input px-2.5 py-1.5 text-xs font-semibold transition'
+
+  return (
+    <div data-annot-ui role="dialog" aria-modal="true" aria-label="Mark up screenshot"
+      className="fixed inset-0 z-[10002] flex flex-col bg-fg/70 p-3" onClick={onClose}>
+      <div ref={panelRef} tabIndex={-1} className="mx-auto flex w-full max-w-4xl flex-col overflow-hidden rounded-modal border border-line bg-surface shadow-e4 outline-none" onClick={(e) => e.stopPropagation()}>
+        {/* toolbar */}
+        <div className="flex flex-wrap items-center gap-1.5 border-b border-line px-3 py-2">
+          {TOOLS.map(({ key, Icon, label }) => (
+            <button key={key} type="button" title={label} aria-label={label} onClick={() => setTool(key)}
+              className={btn + ' ' + (tool === key ? 'bg-brand text-white' : 'text-fg-muted hover:bg-row-alt')}>
+              <Icon size={14} /> {label}
+            </button>
+          ))}
+          <span className="mx-1 flex items-center gap-1">
+            {COLORS.map((c) => (
+              <button key={c} type="button" aria-label={`Colour ${c}`} onClick={() => setColor(c)} style={{ background: c }}
+                className={'h-5 w-5 rounded-full border-2 ' + (color === c ? 'scale-110 border-fg-secondary' : 'border-line')} />
+            ))}
+          </span>
+          <button type="button" onClick={() => setShapes((s) => s.slice(0, -1))} disabled={!shapes.length} title="Undo"
+            className={btn + ' text-fg-muted hover:bg-row-alt disabled:opacity-40'}><Undo2 size={14} /></button>
+          <button type="button" onClick={() => setShapes([])} disabled={!shapes.length} title="Clear all"
+            className={btn + ' text-fg-muted hover:bg-row-alt disabled:opacity-40'}><Trash2 size={14} /></button>
+          <div className="ml-auto flex items-center gap-1.5">
+            <button type="button" onClick={download} className={btn + ' border border-line text-fg-secondary hover:bg-row-alt'}><Download size={14} /> Download</button>
+            <button type="button" onClick={copy} className={btn + ' bg-brand text-white'}><Copy size={14} /> Copy</button>
+            <button type="button" onClick={onClose} title="Close" aria-label="Close" className="rounded-input p-1.5 text-fg-muted hover:bg-row-alt"><X size={16} /></button>
+          </div>
+        </div>
+        {/* canvas */}
+        <div className="grid max-h-[78vh] place-items-center overflow-auto bg-sunken p-3">
+          <canvas ref={canvasRef} onPointerDown={onDown} onPointerMove={onMove} onPointerUp={onUp} onPointerCancel={onUp}
+            style={{ maxWidth: '100%', maxHeight: '72vh', touchAction: 'none', cursor: 'crosshair' }}
+            className="rounded-input border border-line shadow-e2" />
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/adapter.ts

@@ -0,0 +1,31 @@
+// The one seam between the overlay and your backend. Implement these 9 methods for any store
+// (Supabase / Firebase / your own API) and the entire Annotate UI works unchanged. Ready-made
+// adapters ship at `annotate-kit/supabase` and `annotate-kit/firebase`.
+import type { Annotation, NewAnnotation, AnnotationPatch, AnnotateAccess, AnnVisibility } from './types'
+
+export interface StorageAdapter {
+  /** Who is looking + what they may do. Called on mount (and after toggling access). */
+  getAccess(): Promise<AnnotateAccess>
+  /** Flip the global "visible to all users" toggle (ADMIN only). */
+  setAccess(enabled: boolean): Promise<{ message?: string }>
+  /** All marks the viewer may see, each with `screenshot_url` resolved for display. */
+  list(): Promise<Annotation[]>
+  /** Persist a new mark; returns its new id. */
+  save(input: NewAnnotation): Promise<{ id: number }>
+  /** Patch a mark (status/note/type/priority) by id. */
+  update(patch: AnnotationPatch): Promise<void>
+  /** Delete a mark (and its screenshot) by id. */
+  remove(id: number): Promise<void>
+  /** Append a follow-up reply to a mark. */
+  addReply(id: number, note: string): Promise<void>
+  /** Delete every done/dismissed mark (ADMIN/see-all cleanup). */
+  clearResolved(): Promise<{ message?: string }>
+  /** Upload a screenshot; returns the storage path stored on the row (list() turns it into a URL).
+   *  `visibility` decides where the file lives: a 'public' mark's screenshot is readable by any
+   *  authenticated user, a 'private' one only by its owner/admin. Defaults to 'private'. */
+  uploadScreenshot(file: File, opts?: { visibility?: AnnVisibility }): Promise<{ path: string }>
+  /** Optional: subscribe to live changes and call `onChange` when marks may have changed.
+   *  Return an unsubscribe function. When present, the overlay updates in real time (with a slow
+   *  poll as a safety net) instead of polling only while open. */
+  subscribe?(onChange: () => void): () => void
+}

package/src/adapters/firebase.ts

@@ -0,0 +1,197 @@
+// Firebase storage adapter — Firestore for marks, Cloud Storage for screenshots.
+// Apply backend/firebase/firestore.rules + storage.rules once, then create this adapter.
+// Security rules are the real gate; this is just the client.
+import type { Firestore } from 'firebase/firestore'
+import {
+  collection, doc, getDoc, getDocs, setDoc, updateDoc, deleteDoc, query, where, orderBy, limit,
+  arrayUnion, runTransaction, onSnapshot,
+} from 'firebase/firestore'
+import type { FirebaseStorage } from 'firebase/storage'
+import { ref, uploadBytes, getDownloadURL, deleteObject } from 'firebase/storage'
+import type { Auth } from 'firebase/auth'
+import type { StorageAdapter } from '../adapter'
+import type { Annotation, NewAnnotation, AnnotationPatch, AnnotateAccess, AnnVisibility } from '../types'
+
+export type ResolvedUser = { email?: string; name?: string; role?: string }
+
+export type FirebaseAdapterConfig = {
+  firestore: Firestore
+  storage: FirebaseStorage
+  /** Firebase Auth — used to resolve the current user + admin claim (unless currentUser/isAdmin given). */
+  auth?: Auth
+  /** Firestore collection for marks (default 'annotations'). */
+  collectionPath?: string
+  /** Firestore doc holding the global toggle, as 'collection/doc' (default: 'annotate_settings/global'). */
+  settingsPath?: string
+  /** Storage folder for screenshots (default 'annotations'). */
+  storagePath?: string
+  /** Max docs fetched per list() call (default 1000). Keeps polling bounded on busy projects. */
+  listLimit?: number
+  /** Is the current viewer an admin? boolean or predicate.
+   *  Default: the auth user's custom claim `admin === true` or `role === 'admin'`
+   *  (must match backend/firebase/firestore.rules isAdmin()). */
+  isAdmin?: boolean | ((user: ResolvedUser) => boolean | Promise<boolean>)
+  /** Override current-user resolution (default: auth.currentUser + its ID-token claims). */
+  currentUser?: () => Promise<ResolvedUser | null>
+}
+
+// Firestore rejects `undefined` field values — strip them (deeply) before writing.
+function prune<T>(o: T): T {
+  if (Array.isArray(o)) return o.map((v) => prune(v)) as unknown as T
+  if (o && typeof o === 'object') {
+    const out: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(o as Record<string, unknown>)) if (v !== undefined) out[k] = prune(v)
+    return out as T
+  }
+  return o
+}
+
+export function createFirebaseAdapter(config: FirebaseAdapterConfig): StorageAdapter {
+  const db = config.firestore
+  const storage = config.storage
+  const auth = config.auth
+  const collPath = config.collectionPath ?? 'annotations'
+  const settingsFullPath = config.settingsPath ?? 'annotate_settings/global'
+  if (settingsFullPath.split('/').filter(Boolean).length % 2 !== 0) {
+    throw new Error(`annotate: settingsPath must be a document path like 'collection/doc' (got '${settingsFullPath}')`)
+  }
+  const storageDir = config.storagePath ?? 'annotations'
+  const listLimit = config.listLimit ?? 1000
+  const col = collection(db, collPath)
+  const settingsRef = doc(db, settingsFullPath)
+  const urlCache = new Map<string, string>()   // download URLs are long-lived; cache per session
+
+  async function claims(): Promise<Record<string, unknown>> {
+    if (!auth?.currentUser) return {}
+    try { return (await auth.currentUser.getIdTokenResult()).claims as Record<string, unknown> } catch { return {} }
+  }
+  async function resolveUser(): Promise<ResolvedUser> {
+    if (config.currentUser) return (await config.currentUser()) ?? {}
+    const u = auth?.currentUser
+    if (!u) return {}
+    const c = await claims()
+    return { email: u.email ?? undefined, name: u.displayName ?? u.email ?? undefined, role: (c.role as string) || undefined }
+  }
+  async function resolveIsAdmin(user: ResolvedUser): Promise<boolean> {
+    if (typeof config.isAdmin === 'boolean') return config.isAdmin
+    if (typeof config.isAdmin === 'function') return !!(await config.isAdmin(user))
+    const c = await claims()
+    return c.admin === true || c.role === 'admin'
+  }
+  async function urlFor(path?: string | null): Promise<string | null> {
+    if (!path) return null
+    const hit = urlCache.get(path)
+    if (hit) return hit
+    try { const u = await getDownloadURL(ref(storage, path)); urlCache.set(path, u); return u } catch { return null }
+  }
+
+  return {
+    async getAccess(): Promise<AnnotateAccess> {
+      const me = await resolveUser()
+      const isAdmin = await resolveIsAdmin(me)
+      let enabled = false
+      try {
+        const snap = await getDoc(settingsRef)
+        if (snap.exists() && typeof snap.data().enabled === 'boolean') enabled = snap.data().enabled
+      } catch { /* missing → treat as disabled (admin-only) */ }
+      return { enabled, isAdmin, canUse: enabled || isAdmin, seeAll: isAdmin, me }
+    },
+
+    async setAccess(enabled: boolean) {
+      await setDoc(settingsRef, { enabled }, { merge: true })
+      return { message: enabled ? 'Enabled for all users' : 'ADMIN-only' }
+    },
+
+    async list(): Promise<Annotation[]> {
+      const me = await resolveUser()
+      const isAdmin = await resolveIsAdmin(me)
+      const seen = new Map<number, Annotation>()
+      const collect = (docs: { id: string; data: () => Record<string, unknown> }[]) => {
+        for (const d of docs) {
+          const data = d.data()
+          const id = typeof data.id === 'number' ? data.id : Number(d.id)
+          seen.set(id, { ...(data as Annotation), id })
+        }
+      }
+      if (isAdmin) {
+        const s = await getDocs(query(col, orderBy('id', 'desc'), limit(listLimit)))
+        collect(s.docs)
+      } else {
+        const [pub, mine] = await Promise.all([
+          getDocs(query(col, where('visibility', '==', 'public'), orderBy('id', 'desc'), limit(listLimit))),
+          me.email ? getDocs(query(col, where('created_by', '==', me.email), orderBy('id', 'desc'), limit(listLimit))) : Promise.resolve({ docs: [] as never[] }),
+        ])
+        collect(pub.docs); collect(mine.docs)
+      }
+      const rows = [...seen.values()].sort((a, b) => b.id - a.id)
+      await Promise.all(rows.map(async (r) => { if (r.screenshot_path) r.screenshot_url = await urlFor(r.screenshot_path) }))
+      return rows
+    },
+
+    async save(input: NewAnnotation) {
+      const me = await resolveUser()
+      const base = {
+        ...input, status: 'open',
+        created_by: me.email ?? '', created_by_name: me.name ?? me.email ?? '', created_by_role: me.role ?? null,
+        created_at: new Date().toISOString(),
+      }
+      // Allocate a collision-free numeric id transactionally (never overwrite an existing mark).
+      let id = 0
+      await runTransaction(db, async (tx) => {
+        for (let i = 0; i < 6; i++) {
+          const cand = Date.now() * 1000 + Math.floor(Math.random() * 1000)
+          const dref = doc(col, String(cand))
+          const snap = await tx.get(dref)
+          if (!snap.exists()) { id = cand; tx.set(dref, prune({ ...base, id }) as Record<string, unknown>); return }
+        }
+        throw new Error('annotate: could not allocate a unique id — retry')
+      })
+      return { id }
+    },
+
+    async update(patch: AnnotationPatch) {
+      const { id, ...rest } = patch
+      await updateDoc(doc(col, String(id)), { ...prune(rest), updated_at: new Date().toISOString() })
+    },
+
+    async remove(id: number) {
+      const snap = await getDoc(doc(col, String(id)))
+      const path = snap.exists() ? (snap.data().screenshot_path as string | undefined) : undefined
+      await deleteDoc(doc(col, String(id)))
+      if (path) { urlCache.delete(path); try { await deleteObject(ref(storage, path)) } catch (e) { console.warn('[annotate] screenshot delete failed', e) } }
+    },
+
+    async addReply(id: number, note: string) {
+      const me = await resolveUser()
+      const reply = { note: note.slice(0, 2000), author: me.name ?? me.email ?? '', at: new Date().toISOString() }
+      // atomic append — no read-modify-write race
+      await updateDoc(doc(col, String(id)), { replies: arrayUnion(reply), updated_at: new Date().toISOString() })
+    },
+
+    async clearResolved() {
+      const s = await getDocs(query(col, where('status', 'in', ['done', 'dismissed'])))
+      await Promise.all(s.docs.map(async (d) => {
+        const path = d.data().screenshot_path as string | undefined
+        await deleteDoc(d.ref)
+        if (path) { urlCache.delete(path); try { await deleteObject(ref(storage, path)) } catch (e) { console.warn('[annotate] screenshot delete failed', e) } }
+      }))
+      return { message: `Cleared ${s.docs.length} resolved` }
+    },
+
+    async uploadScreenshot(file: File, opts?: { visibility?: AnnVisibility }) {
+      const vis = opts?.visibility === 'public' ? 'public' : 'private'
+      const uid = auth?.currentUser?.uid
+      if (!uid) throw new Error('annotate: must be signed in to upload a screenshot')
+      const rand = Math.random().toString(36).slice(2, 8)
+      const path = `${storageDir}/${vis}/${uid}/${Date.now()}-${rand}.png`
+      await uploadBytes(ref(storage, path), file, { contentType: file.type || 'image/png' })
+      return { path }
+    },
+
+    subscribe(onChange: () => void) {
+      // Live for public marks (any signed-in user may read them); the overlay's slow safety poll
+      // covers own/admin-only changes.
+      return onSnapshot(query(col, where('visibility', '==', 'public')), () => onChange(), () => { /* ignore */ })
+    },
+  }
+}

package/src/adapters/idb.ts

@@ -0,0 +1,181 @@
+// IndexedDB adapter — zero-backend like `annotate-kit/local`, but with real capacity: marks live in
+// an object store and screenshots are kept as native Blobs (no base64 bloat, no ~5MB localStorage cap).
+// Ideal for demos, offline, or single-user setups that take many/large screenshots.
+//
+//   import { createIdbAdapter } from 'annotate-kit/idb'
+//   <Annotate adapter={createIdbAdapter()} />
+//
+// SECURITY: like the local adapter, this is single-browser storage with NO multi-user boundary — it is
+// fully visible to whoever uses that browser. Use it for one user / demos, not shared data.
+import type { StorageAdapter } from '../adapter'
+import type { Annotation, NewAnnotation, AnnotationPatch, AnnotateAccess, AnnVisibility, AnnReply } from '../types'
+
+export type IdbAdapterConfig = {
+  /** Database name (default 'annotate-kit'). */
+  dbName?: string
+  /** The single local user shown as author. */
+  me?: { email?: string; name?: string; role?: string }
+  /** IndexedDB factory (default globalThis.indexedDB). Inject a fake for tests / non-browser envs. */
+  factory?: IDBFactory
+}
+
+const MARKS = 'marks'
+const SHOTS = 'shots'
+const SETTINGS = 'settings'
+
+export function createIdbAdapter(config: IdbAdapterConfig = {}): StorageAdapter {
+  const dbName = config.dbName ?? 'annotate-kit'
+  const me = config.me ?? { email: 'you@local', name: 'You' }
+  const idb = config.factory ?? (typeof indexedDB !== 'undefined' ? indexedDB : undefined)
+  // Do NOT throw at construction — it must be SSR-safe (e.g. inline `createIdbAdapter()` on the server).
+  const now = () => new Date().toISOString()
+  const canObjectUrl = typeof URL !== 'undefined' && typeof URL.createObjectURL === 'function'
+  const urlCache = new Map<string, string>()
+
+  let dbp: Promise<IDBDatabase> | null = null
+  function db(): Promise<IDBDatabase> {
+    if (!idb) return Promise.reject(new Error('annotate: IndexedDB is unavailable — pass config.factory or use another adapter'))
+    if (!dbp) dbp = new Promise((resolve, reject) => {
+      const req = idb.open(dbName, 1)
+      req.onupgradeneeded = () => {
+        const d = req.result
+        if (!d.objectStoreNames.contains(MARKS)) d.createObjectStore(MARKS, { keyPath: 'id', autoIncrement: true })
+        if (!d.objectStoreNames.contains(SHOTS)) d.createObjectStore(SHOTS)
+        if (!d.objectStoreNames.contains(SETTINGS)) d.createObjectStore(SETTINGS)
+      }
+      req.onsuccess = () => resolve(req.result)
+      req.onerror = () => reject(req.error)
+    })
+    return dbp
+  }
+  // Run a transaction whose body issues its requests synchronously (so the tx never goes inactive),
+  // resolving with `out.value` once the tx commits.
+  function run<T>(stores: string[], mode: IDBTransactionMode, body: (t: IDBTransaction, out: { value?: T }) => void): Promise<T | undefined> {
+    return db().then((d) => new Promise<T | undefined>((resolve, reject) => {
+      const t = d.transaction(stores, mode)
+      const out: { value?: T } = {}
+      try { body(t, out) } catch (e) { reject(e); try { t.abort() } catch { /* noop */ } return }
+      t.oncomplete = () => resolve(out.value)
+      t.onerror = () => reject(t.error)
+      t.onabort = () => reject(t.error)
+    }))
+  }
+
+  return {
+    async getAccess(): Promise<AnnotateAccess> {
+      const enabled = await run<boolean>([SETTINGS], 'readonly', (t, out) => {
+        const g = t.objectStore(SETTINGS).get('enabled')
+        g.onsuccess = () => { out.value = g.result === undefined ? true : !!g.result }
+      })
+      return { enabled: enabled ?? true, isAdmin: true, canUse: true, seeAll: true, me }
+    },
+    async setAccess(enabled: boolean) {
+      await run([SETTINGS], 'readwrite', (t) => { t.objectStore(SETTINGS).put(enabled, 'enabled') })
+      return { message: enabled ? 'Enabled' : 'Disabled' }
+    },
+    async list(): Promise<Annotation[]> {
+      const rows = await run<Annotation[]>([MARKS, SHOTS], 'readonly', (t, out) => {
+        const shots = t.objectStore(SHOTS)
+        const ga = t.objectStore(MARKS).getAll()
+        ga.onsuccess = () => {
+          const all = (ga.result || []) as Annotation[]
+          for (const r of all) {
+            if (r.screenshot_path && canObjectUrl) {
+              const cached = urlCache.get(r.screenshot_path)
+              if (cached) r.screenshot_url = cached
+              else {
+                const sr = shots.get(r.screenshot_path)
+                sr.onsuccess = () => { const b = sr.result as Blob | undefined; if (b) { const u = URL.createObjectURL(b); urlCache.set(r.screenshot_path!, u); r.screenshot_url = u } }
+              }
+            }
+          }
+          out.value = all
+        }
+      })
+      return (rows ?? []).sort((a, b) => b.id - a.id)
+    },
+    async save(input: NewAnnotation) {
+      const row = {
+        ...input, status: 'open',
+        created_by: me.email ?? '', created_by_name: me.name ?? me.email ?? '', created_by_role: me.role ?? null,
+        created_at: now(), updated_at: now(),
+      }
+      const id = await run<number>([MARKS], 'readwrite', (t, out) => {
+        const add = t.objectStore(MARKS).add(row)   // autoIncrement fills row.id in the stored value
+        add.onsuccess = () => { out.value = Number(add.result) }
+      })
+      return { id: id ?? 0 }
+    },
+    async update(patch: AnnotationPatch) {
+      const { id, ...rest } = patch
+      await run([MARKS], 'readwrite', (t) => {
+        const store = t.objectStore(MARKS)
+        const g = store.get(id)
+        g.onsuccess = () => { const row = g.result; if (row) { Object.assign(row, rest, { updated_at: now() }); store.put(row) } }
+      })
+    },
+    async remove(id: number) {
+      await run([MARKS, SHOTS], 'readwrite', (t) => {
+        const marks = t.objectStore(MARKS)
+        const g = marks.get(id)
+        g.onsuccess = () => {
+          const row = g.result as Annotation | undefined
+          marks.delete(id)
+          if (row?.screenshot_path) {
+            t.objectStore(SHOTS).delete(row.screenshot_path)
+            const u = urlCache.get(row.screenshot_path); if (u && canObjectUrl) URL.revokeObjectURL(u)
+            urlCache.delete(row.screenshot_path)
+          }
+        }
+      })
+    },
+    async addReply(id: number, note: string) {
+      await run([MARKS], 'readwrite', (t) => {
+        const store = t.objectStore(MARKS)
+        const g = store.get(id)
+        g.onsuccess = () => {
+          const row = g.result as Annotation | undefined
+          if (row) {
+            const reply: AnnReply = { note: note.slice(0, 2000), author: me.name ?? me.email ?? '', at: now() }
+            row.replies = [...(Array.isArray(row.replies) ? row.replies : []), reply]
+            row.updated_at = now()
+            store.put(row)
+          }
+        }
+      })
+    },
+    async clearResolved() {
+      const removed = await run<number>([MARKS, SHOTS], 'readwrite', (t, out) => {
+        const marks = t.objectStore(MARKS)
+        const shots = t.objectStore(SHOTS)
+        const ga = marks.getAll()
+        ga.onsuccess = () => {
+          const all = (ga.result || []) as Annotation[]
+          let n = 0
+          const referenced = new Set<string>()
+          for (const r of all) {
+            if (r.status === 'done' || r.status === 'dismissed') {
+              marks.delete(r.id); n++
+              if (r.screenshot_path) { const u = urlCache.get(r.screenshot_path); if (u && canObjectUrl) URL.revokeObjectURL(u); urlCache.delete(r.screenshot_path) }
+            } else if (r.screenshot_path) referenced.add(r.screenshot_path)
+          }
+          // reclaim every shot no longer referenced by a surviving mark (incl. abandoned uploads)
+          const gk = shots.getAllKeys()
+          gk.onsuccess = () => {
+            for (const k of (gk.result || []) as IDBValidKey[]) {
+              const key = String(k)
+              if (!referenced.has(key)) { shots.delete(k); const u = urlCache.get(key); if (u && canObjectUrl) URL.revokeObjectURL(u); urlCache.delete(key) }
+            }
+          }
+          out.value = n
+        }
+      })
+      return { message: `Cleared ${removed ?? 0} resolved` }
+    },
+    async uploadScreenshot(file: File, _opts?: { visibility?: AnnVisibility }) {
+      const path = `shot-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+      await run([SHOTS], 'readwrite', (t) => { t.objectStore(SHOTS).put(file, path) })
+      return { path }
+    },
+  }
+}