promptslide 0.3.15 → 0.3.17

package/src/core/annotations/annotation-overlay.tsx

@@ -1,9 +1,11 @@
 import { useCallback, useEffect, useRef, useState } from "react"
+
 import type { SlideConfig } from "../types"
+import type { Annotation, AnnotationTarget } from "./types"
+
 import { AnnotationForm } from "./annotation-form"
 import { AnnotationPin } from "./annotation-pin"
 import { buildElementTarget, resolveTarget } from "./selectors"
-import type { Annotation, AnnotationTarget } from "./types"
 
 interface AnnotationOverlayProps {
   slides: SlideConfig[]
@@ -11,10 +13,17 @@ interface AnnotationOverlayProps {
   /** Ref to the slide container element (the div wrapping SlideRenderer) */
   slideContainerRef: React.RefObject<HTMLDivElement | null>
   selectedId: string | null
+  hoveredId: string | null
   onSelectId: (id: string | null) => void
   onShowPanel: () => void
   slideAnnotations: Annotation[]
-  addAnnotation: (slideIndex: number, slideTitle: string, target: AnnotationTarget, body: string) => void
+  addAnnotation: (
+    slideIndex: number,
+    slideTitle: string,
+    target: AnnotationTarget,
+    body: string,
+    slideId?: string
+  ) => void
 }
 
 interface PendingAnnotation {
@@ -23,7 +32,17 @@ interface PendingAnnotation {
   yPercent: number
 }
 
-export function AnnotationOverlay({ slides, currentSlide, slideContainerRef, selectedId, onSelectId, onShowPanel, slideAnnotations, addAnnotation }: AnnotationOverlayProps) {
+export function AnnotationOverlay({
+  slides,
+  currentSlide,
+  slideContainerRef,
+  selectedId,
+  hoveredId,
+  onSelectId,
+  onShowPanel,
+  slideAnnotations,
+  addAnnotation
+}: AnnotationOverlayProps) {
   const [pending, setPending] = useState<PendingAnnotation | null>(null)
   const [hoveredElement, setHoveredElement] = useState<DOMRect | null>(null)
   const overlayRef = useRef<HTMLDivElement>(null)
@@ -34,19 +53,31 @@ export function AnnotationOverlay({ slides, currentSlide, slideContainerRef, sel
   const resolvedAnnotations = slideAnnotations.map((a, i) => {
     const container = slideContainerRef.current
     if (!container) {
-      return { annotation: a, xPercent: a.target.position.xPercent, yPercent: a.target.position.yPercent, number: i + 1 }
+      return {
+        annotation: a,
+        xPercent: a.target.position.xPercent,
+        yPercent: a.target.position.yPercent,
+        number: i + 1
+      }
     }
 
     const { element } = resolveTarget(a.target, container)
     if (element) {
       const rect = element.getBoundingClientRect()
       const containerRect = container.getBoundingClientRect()
-      const xPercent = ((rect.left + rect.width / 2 - containerRect.left) / containerRect.width) * 100
-      const yPercent = ((rect.top + rect.height / 2 - containerRect.top) / containerRect.height) * 100
+      const xPercent =
+        ((rect.left + rect.width / 2 - containerRect.left) / containerRect.width) * 100
+      const yPercent =
+        ((rect.top + rect.height / 2 - containerRect.top) / containerRect.height) * 100
       return { annotation: a, xPercent, yPercent, number: i + 1 }
     }
 
-    return { annotation: a, xPercent: a.target.position.xPercent, yPercent: a.target.position.yPercent, number: i + 1 }
+    return {
+      annotation: a,
+      xPercent: a.target.position.xPercent,
+      yPercent: a.target.position.yPercent,
+      number: i + 1
+    }
   })
 
   const handleOverlayClick = useCallback(
@@ -68,7 +99,11 @@ export function AnnotationOverlay({ slides, currentSlide, slideContainerRef, sel
 
       // Pick the most specific meaningful element (skip tiny text nodes, pick their parent)
       let target = elementUnder
-      if (target.tagName === "SPAN" && target.parentElement && container.contains(target.parentElement)) {
+      if (
+        target.tagName === "SPAN" &&
+        target.parentElement &&
+        container.contains(target.parentElement)
+      ) {
         // For inline spans, prefer their parent for a more meaningful target
         const parent = target.parentElement
         if (parent.tagName !== "DIV" || parent.children.length <= 3) {
@@ -90,11 +125,11 @@ export function AnnotationOverlay({ slides, currentSlide, slideContainerRef, sel
   const handleSubmit = useCallback(
     (text: string) => {
       if (!pending) return
-      addAnnotation(currentSlide, slideTitle, pending.target, text)
+      addAnnotation(currentSlide, slideTitle, pending.target, text, slides[currentSlide]?.id)
       setPending(null)
       onShowPanel()
     },
-    [pending, currentSlide, slideTitle, addAnnotation, onShowPanel]
+    [pending, currentSlide, slideTitle, slides, addAnnotation, onShowPanel]
   )
 
   // Track hover for element highlighting
@@ -116,12 +151,14 @@ export function AnnotationOverlay({ slides, currentSlide, slideContainerRef, sel
       if (elementUnder && container.contains(elementUnder) && elementUnder !== container) {
         const containerRect = container.getBoundingClientRect()
         const elRect = elementUnder.getBoundingClientRect()
+        const scaleX = containerRect.width / container.offsetWidth
+        const scaleY = containerRect.height / container.offsetHeight
         setHoveredElement(
           new DOMRect(
-            elRect.left - containerRect.left,
-            elRect.top - containerRect.top,
-            elRect.width,
-            elRect.height
+            (elRect.left - containerRect.left) / scaleX,
+            (elRect.top - containerRect.top) / scaleY,
+            elRect.width / scaleX,
+            elRect.height / scaleY
           )
         )
       } else {
@@ -159,29 +196,38 @@ export function AnnotationOverlay({ slides, currentSlide, slideContainerRef, sel
         role="button"
         tabIndex={0}
         className="absolute inset-0 z-20"
-        style={{ cursor: `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' fill='none'%3E%3Ccircle cx='12' cy='12' r='8' stroke='%23FF6B35' stroke-width='2' opacity='0.8'/%3E%3Ccircle cx='12' cy='12' r='2' fill='%23FF6B35'/%3E%3C/svg%3E") 12 12, crosshair` }}
+        style={{
+          cursor: `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' fill='none'%3E%3Ccircle cx='12' cy='12' r='8' stroke='%23FF6B35' stroke-width='2' opacity='0.8'/%3E%3Ccircle cx='12' cy='12' r='2' fill='%23FF6B35'/%3E%3C/svg%3E") 12 12, crosshair`
+        }}
         onClick={handleOverlayClick}
-        onKeyDown={e => { if (e.key === "Escape") { setPending(null); onSelectId(null) } }}
+        onKeyDown={e => {
+          if (e.key === "Escape") {
+            setPending(null)
+            onSelectId(null)
+          }
+        }}
         onMouseMove={handleMouseMove}
         onMouseLeave={() => setHoveredElement(null)}
       />
 
       {/* Annotation pins */}
-      {resolvedAnnotations.map(({ annotation, xPercent, yPercent, number }) => (
-        <AnnotationPin
-          key={annotation.id}
-          number={number}
-          status={annotation.status}
-          xPercent={xPercent}
-          yPercent={yPercent}
-          isSelected={annotation.id === selectedId}
-          onClick={() => {
-            onSelectId(annotation.id === selectedId ? null : annotation.id)
-            onShowPanel()
-            setPending(null)
-          }}
-        />
-      ))}
+      {resolvedAnnotations
+        .filter(({ annotation }) => annotation.status === "open" || annotation.id === hoveredId)
+        .map(({ annotation, xPercent, yPercent, number }) => (
+          <AnnotationPin
+            key={annotation.id}
+            number={number}
+            status={annotation.status}
+            xPercent={xPercent}
+            yPercent={yPercent}
+            isSelected={annotation.id === selectedId}
+            onClick={() => {
+              onSelectId(annotation.id === selectedId ? null : annotation.id)
+              onShowPanel()
+              setPending(null)
+            }}
+          />
+        ))}
 
       {/* New annotation form */}
       {pending && (
@@ -192,7 +238,6 @@ export function AnnotationOverlay({ slides, currentSlide, slideContainerRef, sel
           onCancel={() => setPending(null)}
         />
       )}
-
     </>
   )
 }

package/src/core/annotations/annotation-panel.tsx

@@ -1,44 +1,51 @@
-import { MessageCircle, Trash2, X } from "lucide-react"
+import { Check, Pencil, PanelRightClose, RotateCcw, Trash2 } from "lucide-react"
+import { useEffect, useRef, useState } from "react"
+
 import type { Annotation } from "./types"
 
 interface AnnotationPanelProps {
   annotations: Annotation[]
+  unlinkedAnnotations?: Annotation[]
   selectedId: string | null
   onSelect: (id: string) => void
+  onHover: (id: string | null) => void
   onDelete: (id: string) => void
+  onUpdate: (id: string, patch: Partial<Pick<Annotation, "body" | "status">>) => void
   onClose: () => void
 }
 
-export function AnnotationPanel({ annotations, selectedId, onSelect, onDelete, onClose }: AnnotationPanelProps) {
+export function AnnotationPanel({
+  annotations,
+  unlinkedAnnotations = [],
+  selectedId,
+  onSelect,
+  onHover,
+  onDelete,
+  onUpdate,
+  onClose
+}: AnnotationPanelProps) {
   const open = annotations.filter(a => a.status === "open")
   const resolved = annotations.filter(a => a.status === "resolved")
+  const total = annotations.length + unlinkedAnnotations.length
+  const numberFor = (annotation: Annotation) =>
+    annotations.findIndex(a => a.id === annotation.id) + 1
 
   return (
-    <div className="flex h-full w-80 flex-shrink-0 flex-col border-l border-white/[0.06] bg-neutral-950/95 backdrop-blur-2xl">
-      <div className="flex items-center justify-between px-4 py-3.5">
-        <div className="flex items-center gap-2.5">
-          <div className="flex h-6 w-6 items-center justify-center rounded-lg bg-[#FF6B35]/15">
-            <MessageCircle className="h-3.5 w-3.5 text-[#FF6B35]" />
-          </div>
-          <span className="text-sm font-medium text-white">Annotations</span>
-          {open.length > 0 && (
-            <span className="flex h-5 min-w-5 items-center justify-center rounded-full bg-[#FF6B35]/15 px-1.5 text-[11px] font-semibold text-[#FF6B35]">
-              {open.length}
-            </span>
-          )}
-        </div>
+    <div className="flex h-full w-80 max-w-[90vw] flex-shrink-0 flex-col border-l border-neutral-800 bg-neutral-950 text-white">
+      <div className="flex items-center justify-between border-b border-neutral-800 px-3 py-2">
         <button
           onClick={onClose}
-          className="rounded-lg p-1.5 text-neutral-500 transition-colors hover:bg-white/[0.06] hover:text-neutral-300"
+          className="rounded p-2 text-neutral-400 hover:bg-neutral-800 hover:text-white"
+          aria-label="Hide comments"
+          title="Hide comments (C)"
         >
-          <X className="h-4 w-4" />
+          <PanelRightClose className="h-4 w-4" />
         </button>
+        <span className="text-right text-sm font-semibold">Comments ({total})</span>
       </div>
 
-      <div className="h-px bg-gradient-to-r from-transparent via-white/[0.06] to-transparent" />
-
-      <div className="flex-1 overflow-y-auto p-2">
-        {annotations.length === 0 && (
+      <div className="min-h-0 flex-1 overflow-y-auto p-3">
+        {annotations.length === 0 && unlinkedAnnotations.length === 0 && (
           <div className="flex flex-col gap-4 px-3 py-6">
             <WorkflowHint />
           </div>
@@ -49,14 +56,16 @@ export function AnnotationPanel({ annotations, selectedId, onSelect, onDelete, o
             <div className="mb-1.5 px-2 pt-1 text-[11px] font-medium tracking-wider text-neutral-500 uppercase">
               Open
             </div>
-            {open.map((a, i) => (
+            {open.map(a => (
               <AnnotationItem
                 key={a.id}
                 annotation={a}
-                number={i + 1}
+                number={numberFor(a)}
                 isSelected={a.id === selectedId}
                 onSelect={() => onSelect(a.id)}
+                onHover={hovered => onHover(hovered ? a.id : null)}
                 onDelete={() => onDelete(a.id)}
+                onUpdate={patch => onUpdate(a.id, patch)}
               />
             ))}
           </div>
@@ -67,23 +76,46 @@ export function AnnotationPanel({ annotations, selectedId, onSelect, onDelete, o
             <div className="mb-1.5 px-2 pt-1 text-[11px] font-medium tracking-wider text-neutral-500 uppercase">
               Resolved
             </div>
-            {resolved.map((a, i) => (
+            {resolved.map(a => (
               <AnnotationItem
                 key={a.id}
                 annotation={a}
-                number={open.length + i + 1}
+                number={numberFor(a)}
                 isSelected={a.id === selectedId}
                 onSelect={() => onSelect(a.id)}
+                onHover={hovered => onHover(hovered ? a.id : null)}
                 onDelete={() => onDelete(a.id)}
+                onUpdate={patch => onUpdate(a.id, patch)}
               />
             ))}
           </div>
         )}
+        {unlinkedAnnotations.length > 0 && (
+          <div className="mt-3">
+            <div className="mb-1.5 px-2 pt-1 text-[11px] font-medium tracking-wider text-neutral-500 uppercase">
+              Removed slides
+            </div>
+            {unlinkedAnnotations.map((a, i) => (
+              <div key={a.id}>
+                <p className="px-2 text-[11px] text-neutral-500">{a.slideTitle || a.slideId}</p>
+                <AnnotationItem
+                  annotation={a}
+                  number={i + 1}
+                  isSelected={a.id === selectedId}
+                  onSelect={() => onSelect(a.id)}
+                  onHover={hovered => onHover(hovered ? a.id : null)}
+                  onDelete={() => onDelete(a.id)}
+                  onUpdate={patch => onUpdate(a.id, patch)}
+                />
+              </div>
+            ))}
+          </div>
+        )}
       </div>
 
-      {annotations.length > 0 && (
+      {annotations.length + unlinkedAnnotations.length > 0 && (
         <>
-          <div className="h-px bg-gradient-to-r from-transparent via-white/[0.06] to-transparent" />
+          <div className="border-t border-neutral-800" />
           <div className="px-3 py-3">
             <WorkflowHint />
           </div>
@@ -98,16 +130,24 @@ function WorkflowHint() {
     <div className="flex flex-col gap-2">
       <p className="text-[11px] font-medium tracking-wider text-neutral-500 uppercase">Workflow</p>
       <div className="flex items-start gap-2.5">
-        <div className="mt-0.5 flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-full bg-[#FF6B35]/15 text-[10px] font-semibold text-[#FF6B35]">1</div>
-        <p className="text-[12px] leading-snug text-neutral-400">Annotate everything you want to fix</p>
+        <div className="mt-0.5 flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-full bg-[#FF6B35]/15 text-[10px] font-semibold text-[#FF6B35]">
+          1
+        </div>
+        <p className="text-[12px] leading-snug text-neutral-400">
+          Comment on everything you want to fix
+        </p>
       </div>
       <div className="flex items-start gap-2.5">
-        <div className="mt-0.5 flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-full bg-[#FF6B35]/15 text-[10px] font-semibold text-[#FF6B35]">2</div>
+        <div className="mt-0.5 flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-full bg-[#FF6B35]/15 text-[10px] font-semibold text-[#FF6B35]">
+          2
+        </div>
         <p className="text-[12px] leading-snug text-neutral-400">Switch to your coding agent</p>
       </div>
       <div className="flex items-start gap-2.5">
-        <div className="mt-0.5 flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-full bg-[#FF6B35]/15 text-[10px] font-semibold text-[#FF6B35]">3</div>
-        <p className="text-[12px] leading-snug text-neutral-400">"Fix open annotations"</p>
+        <div className="mt-0.5 flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-full bg-[#FF6B35]/15 text-[10px] font-semibold text-[#FF6B35]">
+          3
+        </div>
+        <p className="text-[12px] leading-snug text-neutral-400">"Fix open comments"</p>
       </div>
     </div>
   )
@@ -118,35 +158,89 @@ function AnnotationItem({
   number,
   isSelected,
   onSelect,
-  onDelete
+  onHover,
+  onDelete,
+  onUpdate
 }: {
   annotation: Annotation
   number: number
   isSelected: boolean
   onSelect: () => void
+  onHover: (hovered: boolean) => void
   onDelete: () => void
+  onUpdate: (patch: Partial<Pick<Annotation, "body" | "status">>) => void
 }) {
+  const [isEditing, setIsEditing] = useState(false)
+  const [draft, setDraft] = useState(annotation.body)
+  const editRef = useRef<HTMLTextAreaElement>(null)
+  useEffect(() => {
+    if (isEditing) editRef.current?.focus()
+  }, [isEditing])
+  const saveEdit = () => {
+    const body = draft.trim()
+    if (!body) return
+    if (body !== annotation.body) onUpdate({ body })
+    setIsEditing(false)
+  }
+
   return (
     <div
       role="button"
       tabIndex={0}
       onClick={onSelect}
-      onKeyDown={e => { if (e.key === "Enter" || e.key === " ") onSelect() }}
+      onMouseEnter={() => onHover(true)}
+      onMouseLeave={() => onHover(false)}
+      onKeyDown={e => {
+        if (e.target === e.currentTarget && (e.key === "Enter" || e.key === " ")) onSelect()
+      }}
       className={`group relative mb-0.5 cursor-pointer rounded-xl p-2.5 transition-all duration-150 ${
-        isSelected
-          ? "bg-[#FF6B35]/10 ring-1 ring-[#FF6B35]/20"
-          : "hover:bg-white/[0.04]"
+        isSelected ? "bg-[#FF6B35]/10 ring-1 ring-[#FF6B35]/20" : "hover:bg-white/[0.04]"
       }`}
     >
-      <button
-        onClick={e => {
-          e.stopPropagation()
-          onDelete()
-        }}
-        className="absolute top-2 right-2 rounded-lg p-1 text-neutral-600 opacity-0 transition-all hover:bg-white/[0.08] hover:text-neutral-300 group-hover:opacity-100"
-      >
-        <Trash2 className="h-3 w-3" />
-      </button>
+      <div className="absolute top-2 right-2 z-10 flex gap-0.5 rounded-full border border-neutral-700 bg-neutral-900/70 p-0.5 opacity-0 backdrop-blur-sm transition-opacity group-hover:opacity-100 group-focus-within:opacity-100">
+        <button
+          type="button"
+          title="Edit comment"
+          aria-label="Edit comment"
+          onClick={e => {
+            e.stopPropagation()
+            setDraft(annotation.body)
+            setIsEditing(true)
+          }}
+          className="rounded-full p-1 text-neutral-400 hover:bg-white/[0.08] hover:text-white"
+        >
+          <Pencil className="h-3.5 w-3.5" />
+        </button>
+        <button
+          type="button"
+          title={annotation.status === "open" ? "Resolve comment" : "Reopen comment"}
+          aria-label={annotation.status === "open" ? "Resolve comment" : "Reopen comment"}
+          onClick={e => {
+            e.stopPropagation()
+            onHover(false)
+            onUpdate({ status: annotation.status === "open" ? "resolved" : "open" })
+          }}
+          className="rounded-full p-1 text-neutral-400 hover:bg-white/[0.08] hover:text-white"
+        >
+          {annotation.status === "open" ? (
+            <Check className="h-3.5 w-3.5" />
+          ) : (
+            <RotateCcw className="h-3.5 w-3.5" />
+          )}
+        </button>
+        <button
+          type="button"
+          title="Delete comment"
+          aria-label="Delete comment"
+          onClick={e => {
+            e.stopPropagation()
+            onDelete()
+          }}
+          className="rounded-full p-1 text-neutral-400 hover:bg-white/[0.08] hover:text-white"
+        >
+          <Trash2 className="h-3.5 w-3.5" />
+        </button>
+      </div>
       <div className="flex items-start gap-2.5">
         <div
           className={`mt-0.5 flex h-5 w-5 flex-shrink-0 items-center justify-center rounded-full text-[11px] font-semibold ${
@@ -157,17 +251,56 @@ function AnnotationItem({
         >
           {number}
         </div>
-        <div className="min-w-0 pr-4">
-          <p className="text-[13px] leading-relaxed text-neutral-200">{annotation.body}</p>
+        <div className="min-w-0 flex-1 pr-4">
+          {isEditing ? (
+            <div>
+              <textarea
+                ref={editRef}
+                value={draft}
+                onClick={e => e.stopPropagation()}
+                onChange={e => setDraft(e.target.value)}
+                onKeyDown={e => {
+                  if (e.key === "Escape") setIsEditing(false)
+                  if ((e.metaKey || e.ctrlKey) && e.key === "Enter") saveEdit()
+                }}
+                className="w-full resize-y rounded border border-neutral-700 bg-neutral-900 p-2 text-[13px] text-white outline-none focus:border-[#FF6B35]"
+                rows={3}
+                maxLength={4096}
+              />
+              <div className="mt-1 flex gap-2 text-xs">
+                <button
+                  type="button"
+                  onClick={e => {
+                    e.stopPropagation()
+                    saveEdit()
+                  }}
+                  disabled={!draft.trim()}
+                  className="text-[#FF6B35] disabled:opacity-40"
+                >
+                  Save
+                </button>
+                <button
+                  type="button"
+                  onClick={e => {
+                    e.stopPropagation()
+                    setIsEditing(false)
+                  }}
+                  className="text-neutral-400"
+                >
+                  Cancel
+                </button>
+              </div>
+            </div>
+          ) : (
+            <p className="text-[13px] leading-relaxed text-neutral-200">{annotation.body}</p>
+          )}
           {annotation.target.contentNearPin && (
             <p className="mt-1 truncate text-[11px] text-neutral-600">
               {annotation.target.contentNearPin}
             </p>
           )}
           {annotation.resolution && (
-            <p className="mt-1.5 text-[11px] text-emerald-400/80 italic">
-              {annotation.resolution}
-            </p>
+            <p className="mt-1.5 text-[11px] text-emerald-400/80 italic">{annotation.resolution}</p>
           )}
         </div>
       </div>

package/src/core/annotations/types.ts

@@ -18,6 +18,8 @@ export interface Annotation {
   id: string
   /** Slide index (0-based, matching deck-config order) */
   slideIndex: number
+  /** Stable slide identity, when available. Takes precedence over slideIndex. */
+  slideId?: string
   /** Slide title from SlideConfig (informational, for agent readability) */
   slideTitle: string
   /** Target element identification */
@@ -42,6 +44,9 @@ export interface AnnotationStorageAdapter {
   load(): Promise<Annotation[]>
   add(annotation: Annotation): Promise<void>
   remove(id: string): Promise<void>
+  update?(id: string, patch: Pick<Annotation, "body" | "status">): Promise<void>
+  /** Persist a migration of legacy index-based annotations. */
+  replaceAll?(annotations: Annotation[]): Promise<void>
   /** Optional: subscribe to external state updates (e.g. postMessage from parent) */
   subscribe?(onUpdate: (annotations: Annotation[]) => void): () => void
 }

package/src/core/annotations/use-annotations.ts

@@ -1,22 +1,50 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react"
-import { createHttpAdapter } from "./adapters/http"
+
+import type { SlideConfig } from "../types"
 import type { Annotation, AnnotationStorageAdapter, AnnotationTarget } from "./types"
 
-export function useAnnotations(adapter?: AnnotationStorageAdapter) {
-  const adapterRef = useRef(adapter ?? createHttpAdapter())
+import { createHttpAdapter } from "./adapters/http"
+
+export function useAnnotations(
+  slidesOrAdapter?: SlideConfig[] | AnnotationStorageAdapter,
+  adapter?: AnnotationStorageAdapter
+) {
+  const slides = Array.isArray(slidesOrAdapter) ? slidesOrAdapter : undefined
+  const storage = Array.isArray(slidesOrAdapter) ? adapter : (slidesOrAdapter ?? adapter)
+  const adapterRef = useRef(storage ?? createHttpAdapter())
+  const slidesRef = useRef(slides)
+  slidesRef.current = slides
   const [annotations, setAnnotations] = useState<Annotation[]>([])
 
   // Load on mount and subscribe to external updates
   useEffect(() => {
-    adapterRef.current.load().then(setAnnotations)
+    adapterRef.current.load().then(loaded => {
+      const configuredSlides = slidesRef.current
+      const migrated = loaded.map(annotation => {
+        if (annotation.slideId || !configuredSlides) return annotation
+        const id = configuredSlides[annotation.slideIndex]?.id
+        return id ? { ...annotation, slideId: id } : annotation
+      })
+      setAnnotations(migrated)
+      if (migrated.some((annotation, index) => annotation !== loaded[index])) {
+        void adapterRef.current.replaceAll?.(migrated)
+      }
+    })
     return adapterRef.current.subscribe?.(setAnnotations)
   }, [])
 
   const addAnnotation = useCallback(
-    (slideIndex: number, slideTitle: string, target: AnnotationTarget, body: string) => {
+    (
+      slideIndex: number,
+      slideTitle: string,
+      target: AnnotationTarget,
+      body: string,
+      slideId?: string
+    ) => {
       const annotation: Annotation = {
         id: crypto.randomUUID(),
         slideIndex,
+        ...(slideId && { slideId }),
         slideTitle,
         target,
         body,
@@ -34,17 +62,39 @@ export function useAnnotations(adapter?: AnnotationStorageAdapter) {
     adapterRef.current.remove(id)
   }, [])
 
+  const updateAnnotation = useCallback(
+    (id: string, patch: Partial<Pick<Annotation, "body" | "status">>) => {
+      const current = annotations.find(a => a.id === id)
+      if (!current) return
+      const updated = { body: patch.body ?? current.body, status: patch.status ?? current.status }
+      setAnnotations(prev => prev.map(a => (a.id === id ? { ...a, ...updated } : a)))
+      void adapterRef.current.update?.(id, updated)
+    },
+    [annotations]
+  )
+
   const getSlideAnnotations = useCallback(
     (slideIndex: number) => annotations.filter(a => a.slideIndex === slideIndex),
     [annotations]
   )
 
-  const openCount = useMemo(() => annotations.filter(a => a.status === "open").length, [annotations])
+  const openCount = useMemo(
+    () => annotations.filter(a => a.status === "open").length,
+    [annotations]
+  )
 
   // Allow external state updates (e.g. from postMessage adapter)
   const updateAnnotations = useCallback((updated: Annotation[]) => {
     setAnnotations(updated)
   }, [])
 
-  return { annotations, addAnnotation, deleteAnnotation, getSlideAnnotations, openCount, updateAnnotations }
+  return {
+    annotations,
+    addAnnotation,
+    deleteAnnotation,
+    updateAnnotation,
+    getSlideAnnotations,
+    openCount,
+    updateAnnotations
+  }
 }