promptslide 0.3.6 → 0.3.8

package/src/commands/publish.mjs

@@ -2,10 +2,10 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
 import { dirname, join, basename, relative, extname } from "node:path"
 import { fileURLToPath } from "node:url"
 
-import { bold, green, cyan, red, dim } from "../utils/ansi.mjs"
+import { bold, green, cyan, red, yellow, dim } from "../utils/ansi.mjs"
 import { requireAuth } from "../utils/auth.mjs"
 import { captureSlideAsDataUri, isPlaywrightAvailable, createCaptureSession } from "../utils/export.mjs"
-import { publishToRegistry, registryItemExists, searchRegistry, updateLockfileItem, updateLockfilePublishConfig, readLockfile, writeLockfile, hashContent, detectPackageManager, requestUploadTokens, uploadBinaryToBlob, assetFileToSlug, detectAssetDepsInContent, readDeckMeta, updateDeckMeta, readItemMeta, updateItemMeta } from "../utils/registry.mjs"
+import { publishToRegistry, registryItemExists, fetchRegistryItem, searchRegistry, updateLockfileItem, updateLockfilePublishConfig, readLockfile, writeLockfile, hashContent, detectPackageManager, requestUploadTokens, uploadBinaryToBlob, assetFileToSlug, detectAssetDepsInContent, readDeckMeta, updateDeckMeta, readItemMeta, updateItemMeta } from "../utils/registry.mjs"
 import { prompt, confirm, select, closePrompts } from "../utils/prompts.mjs"
 import { parseDeckConfig } from "../utils/deck-config.mjs"
 
@@ -15,12 +15,17 @@ const CLI_VERSION = JSON.parse(readFileSync(join(__dirname, "..", "..", "package
 function readDeckSlug(cwd) {
   const lock = readLockfile(cwd)
   // Prefer stored deck slug — migrate old two-part format (e.g. "my-deck/name" → "my-deck")
-  if (lock.deckSlug) return lock.deckSlug.split("/")[0]
+  // Sanitize to match validation rules (lowercase alphanumeric + hyphens only)
+  if (lock.deckSlug) return sanitizeSlug(lock.deckSlug.split("/")[0])
   // Migrate legacy deckPrefix (old lockfiles stored prefix separately)
-  if (lock.deckPrefix) return lock.deckPrefix
+  if (lock.deckPrefix) return sanitizeSlug(lock.deckPrefix)
   return ""
 }
 
+function sanitizeSlug(raw) {
+  return raw.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")
+}
+
 function defaultDeckSlug(cwd) {
   const dirName = basename(cwd)
   return dirName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")
@@ -91,6 +96,24 @@ function detectRegistryDeps(content) {
   return deps
 }
 
+/** Detect sibling layout imports — both relative ("./foo") and absolute ("@/layouts/foo"). */
+function detectLayoutSiblingDeps(content) {
+  const deps = []
+  // Relative imports: import ... from "./shared-footer"
+  const relativeRegex = /import\s+.*?\s+from\s+["']\.\/([^"']+)["']/g
+  for (const match of content.matchAll(relativeRegex)) {
+    const name = match[1].replace(/\.tsx?$/, "")
+    deps.push(name)
+  }
+  // Absolute imports: import ... from "@/layouts/shared-footer"
+  const absoluteRegex = /import\s+.*?\s+from\s+["']@\/layouts\/([^"']+)["']/g
+  for (const match of content.matchAll(absoluteRegex)) {
+    const name = match[1].replace(/\.tsx?$/, "")
+    if (!deps.includes(name)) deps.push(name)
+  }
+  return deps
+}
+
 /**
  * Discover shared source files under src/ that aren't slides, layouts, or theme.
  * These are files in directories like src/components/, src/lib/, src/hooks/, etc.
@@ -451,6 +474,27 @@ export async function publish(args) {
     // Persist slug early so it's available even if publish fails partway
     updateLockfilePublishConfig(cwd, { deckSlug })
 
+    // Warn if this deck already exists in the registry
+    try {
+      const existing = await fetchRegistryItem(deckSlug, auth)
+      if (existing) {
+        const existingTitle = existing.title || existing.name || deckSlug
+        const existingVer = existing.version ? ` ${dim(`(v${existing.version})`)}` : ""
+        console.log(`  ${yellow("Warning:")} ${cyan(deckSlug)} already exists in the registry.`)
+        console.log(`  ${dim("Existing deck:")} ${existingTitle}${existingVer}`)
+        console.log()
+        const shouldContinue = await confirm("Do you want to overwrite it?")
+        if (!shouldContinue) {
+          console.log(`  ${dim("Publish cancelled.")}`)
+          closePrompts()
+          return
+        }
+        console.log()
+      }
+    } catch {
+      // Existence check failure is non-blocking (item doesn't exist or network error)
+    }
+
     // Walk public/ to collect assets and build reference set
     const publicDir = join(cwd, "public")
     const publicAssets = []
@@ -687,8 +731,9 @@ export async function publish(args) {
 
         const assetDeps = detectAssetDepsInContent(content, deckSlug, publicFileSet)
         const npmDeps = detectNpmDeps(content)
+        const siblingDeps = detectLayoutSiblingDeps(content).map(d => `${deckSlug}/${d}`)
         const regDeps = hasTheme ? [`${deckSlug}/theme`] : []
-        regDeps.push(...assetDeps)
+        regDeps.push(...siblingDeps, ...assetDeps)
 
         try {
           const result = await publishToRegistry({
@@ -772,9 +817,11 @@ export async function publish(args) {
 
     // ── Phase 5: Deck manifest (includes shared source modules) ──
     itemIndex++
+    const themeSlugs = hasTheme ? [`${deckSlug}/theme`] : []
+    const layoutSlugs = layoutEntries.map(f => `${deckSlug}/${f.replace(/\.tsx?$/, "")}`)
     const slideSlugs = slideEntries.map(f => `${deckSlug}/${f.replace(/\.tsx?$/, "")}`)
     const assetSlugs = publicAssets.map(a => assetFileToSlug(deckSlug, a.relativePath))
-    const allDeckDeps = [...slideSlugs, ...assetSlugs]
+    const allDeckDeps = [...themeSlugs, ...layoutSlugs, ...slideSlugs, ...assetSlugs]
 
     // Bundle shared source files with the deck item so preview/install can resolve @/ imports
     const sharedFiles = sharedSources.map(s => ({
@@ -883,6 +930,27 @@ export async function publish(args) {
   console.log(`  Slug: ${cyan(slug)}`)
   console.log()
 
+  // Warn if this item already exists in the registry
+  try {
+    const existing = await fetchRegistryItem(slug, auth)
+    if (existing) {
+      const existingTitle = existing.title || existing.name || slug
+      const existingVer = existing.version ? ` ${dim(`(v${existing.version})`)}` : ""
+      console.log(`  ${yellow("Warning:")} ${cyan(slug)} already exists in the registry.`)
+      console.log(`  ${dim("Existing item:")} ${existingTitle}${existingVer}`)
+      console.log()
+      const shouldContinue = await confirm("Do you want to overwrite it?")
+      if (!shouldContinue) {
+        console.log(`  ${dim("Publish cancelled.")}`)
+        closePrompts()
+        return
+      }
+      console.log()
+    }
+  } catch {
+    // Existence check failure is non-blocking (item doesn't exist or network error)
+  }
+
   // Warn if same base slug exists under a different prefix
   try {
     const { items: results } = await searchRegistry({ search: baseSlug, type }, auth)

package/src/commands/pull.mjs

@@ -216,6 +216,35 @@ export async function pull(args) {
     }
   }
 
+  // Fetch annotations from registry
+  if (deckItem.id) {
+    try {
+      const annotationsRes = await fetch(`${auth.registry}/api/items/${deckItem.id}/annotations`, {
+        headers: { Authorization: `Bearer ${auth.token}`, ...(auth.organizationId ? { "X-Organization-Id": auth.organizationId } : {}) }
+      })
+      if (annotationsRes.ok) {
+        const data = await annotationsRes.json()
+        const annotations = data.annotations ?? []
+        if (annotations.length > 0) {
+          const annotationsFile = { version: 1, annotations: annotations.map(a => ({
+            id: a.id,
+            slideIndex: a.slideIndex,
+            slideTitle: a.slideTitle,
+            target: a.target,
+            body: a.body,
+            createdAt: a.createdAt,
+            status: a.status,
+            ...(a.resolution ? { resolution: a.resolution } : {})
+          })) }
+          writeFileSync(join(cwd, "annotations.json"), JSON.stringify(annotationsFile, null, 2) + "\n", "utf-8")
+          console.log(`  ${green("+")} ${cyan("annotations.json")} ${dim(`(${annotations.length} annotation${annotations.length === 1 ? "" : 's'})`)}`)
+        }
+      }
+    } catch {
+      // Annotations are non-critical; don't fail the pull
+    }
+  }
+
   // Summary
   console.log()
   if (written.length === 0) {

package/src/core/annotations/adapters/http.ts

@@ -0,0 +1,43 @@
+import type { Annotation, AnnotationsFile, AnnotationStorageAdapter } from "../types"
+
+const ENDPOINT = "/__promptslide_annotations"
+
+async function loadAll(): Promise<Annotation[]> {
+  try {
+    const res = await fetch(ENDPOINT)
+    if (!res.ok) return []
+    const data: AnnotationsFile = await res.json()
+    return data.annotations || []
+  } catch {
+    return []
+  }
+}
+
+async function saveAll(annotations: Annotation[]): Promise<void> {
+  const data: AnnotationsFile = { version: 1, annotations }
+  await fetch(ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(data)
+  })
+}
+
+/** Storage adapter for local Vite dev server (reads/writes annotations.json via middleware) */
+export function createHttpAdapter(): AnnotationStorageAdapter {
+  let cache: Annotation[] = []
+
+  return {
+    async load() {
+      cache = await loadAll()
+      return cache
+    },
+    async add(annotation) {
+      cache = [...cache, annotation]
+      await saveAll(cache)
+    },
+    async remove(id) {
+      cache = cache.filter(a => a.id !== id)
+      await saveAll(cache)
+    }
+  }
+}

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

@@ -0,0 +1,82 @@
+import { useEffect, useRef, useState } from "react"
+import { ArrowUp, X } from "lucide-react"
+
+interface AnnotationFormProps {
+  xPercent: number
+  yPercent: number
+  onSubmit: (text: string) => void
+  onCancel: () => void
+}
+
+export function AnnotationForm({ xPercent, yPercent, onSubmit, onCancel }: AnnotationFormProps) {
+  const [text, setText] = useState("")
+  const textareaRef = useRef<HTMLTextAreaElement>(null)
+
+  useEffect(() => {
+    textareaRef.current?.focus()
+  }, [])
+
+  const handleSubmit = () => {
+    const trimmed = text.trim()
+    if (!trimmed) return
+    onSubmit(trimmed)
+  }
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault()
+      handleSubmit()
+    }
+    if (e.key === "Escape") {
+      onCancel()
+    }
+    e.stopPropagation()
+  }
+
+  // Position the form, flipping if near edges
+  const left = xPercent > 70 ? undefined : `${xPercent}%`
+  const right = xPercent > 70 ? `${100 - xPercent}%` : undefined
+  const top = yPercent > 70 ? undefined : `${yPercent}%`
+  const bottom = yPercent > 70 ? `${100 - yPercent}%` : undefined
+
+  return (
+    <div
+      role="dialog"
+      className="absolute z-40 w-72 overflow-hidden rounded-xl border border-white/[0.08] bg-neutral-900/95 shadow-2xl backdrop-blur-2xl"
+      style={{ left, right, top, bottom }}
+      onClick={e => e.stopPropagation()}
+      onKeyDown={e => e.stopPropagation()}
+    >
+      <div className="flex items-center justify-between border-b border-white/[0.06] px-3.5 py-2.5">
+        <span className="text-xs font-medium tracking-wide text-neutral-400">Add annotation</span>
+        <button
+          onClick={onCancel}
+          className="rounded-lg p-1 text-neutral-500 transition-colors hover:bg-white/[0.06] hover:text-neutral-300"
+        >
+          <X className="h-3.5 w-3.5" />
+        </button>
+      </div>
+      <div className="p-3">
+        <textarea
+          ref={textareaRef}
+          value={text}
+          onChange={e => setText(e.target.value)}
+          onKeyDown={handleKeyDown}
+          placeholder="Describe the change you want..."
+          className="w-full resize-none rounded-lg border border-white/[0.08] bg-white/[0.04] px-3 py-2 text-sm text-white placeholder-neutral-500 outline-none transition-colors focus:border-[#FF6B35]/50 focus:bg-white/[0.06]"
+          rows={3}
+        />
+        <div className="mt-2.5 flex items-center justify-between">
+          <span className="text-[11px] text-neutral-600">Enter to send</span>
+          <button
+            onClick={handleSubmit}
+            disabled={!text.trim()}
+            className="flex h-7 w-7 items-center justify-center rounded-lg bg-[#FF6B35] text-white shadow-lg shadow-[#FF6B35]/20 transition-all hover:bg-[#FF7A4A] hover:shadow-[#FF6B35]/30 disabled:opacity-30 disabled:shadow-none disabled:hover:bg-[#FF6B35]"
+          >
+            <ArrowUp className="h-3.5 w-3.5" strokeWidth={2.5} />
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,198 @@
+import { useCallback, useEffect, useRef, useState } from "react"
+import type { SlideConfig } 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[]
+  currentSlide: number
+  /** Ref to the slide container element (the div wrapping SlideRenderer) */
+  slideContainerRef: React.RefObject<HTMLDivElement | null>
+  selectedId: string | null
+  onSelectId: (id: string | null) => void
+  onShowPanel: () => void
+  slideAnnotations: Annotation[]
+  addAnnotation: (slideIndex: number, slideTitle: string, target: AnnotationTarget, body: string) => void
+}
+
+interface PendingAnnotation {
+  target: AnnotationTarget
+  xPercent: number
+  yPercent: number
+}
+
+export function AnnotationOverlay({ slides, currentSlide, slideContainerRef, selectedId, onSelectId, onShowPanel, slideAnnotations, addAnnotation }: AnnotationOverlayProps) {
+  const [pending, setPending] = useState<PendingAnnotation | null>(null)
+  const [hoveredElement, setHoveredElement] = useState<DOMRect | null>(null)
+  const overlayRef = useRef<HTMLDivElement>(null)
+
+  const slideTitle = slides[currentSlide]?.title || `Slide ${currentSlide + 1}`
+
+  // Resolve annotation positions — use the element if found, otherwise fallback coordinates
+  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 }
+    }
+
+    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
+      return { annotation: a, xPercent, yPercent, number: i + 1 }
+    }
+
+    return { annotation: a, xPercent: a.target.position.xPercent, yPercent: a.target.position.yPercent, number: i + 1 }
+  })
+
+  const handleOverlayClick = useCallback(
+    (e: React.MouseEvent) => {
+      const container = slideContainerRef.current
+      if (!container) return
+
+      // Get the element under the click by temporarily hiding the overlay
+      const overlay = overlayRef.current
+      if (overlay) overlay.style.pointerEvents = "none"
+      const elementUnder = document.elementFromPoint(e.clientX, e.clientY) as HTMLElement | null
+      if (overlay) overlay.style.pointerEvents = ""
+
+      if (!elementUnder || !container.contains(elementUnder)) {
+        setPending(null)
+        onSelectId(null)
+        return
+      }
+
+      // 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)) {
+        // For inline spans, prefer their parent for a more meaningful target
+        const parent = target.parentElement
+        if (parent.tagName !== "DIV" || parent.children.length <= 3) {
+          target = parent
+        }
+      }
+
+      const annotationTarget = buildElementTarget(target, container)
+      const containerRect = container.getBoundingClientRect()
+      const xPercent = ((e.clientX - containerRect.left) / containerRect.width) * 100
+      const yPercent = ((e.clientY - containerRect.top) / containerRect.height) * 100
+
+      setPending({ target: annotationTarget, xPercent, yPercent })
+      onSelectId(null)
+    },
+    [slideContainerRef, onSelectId]
+  )
+
+  const handleSubmit = useCallback(
+    (text: string) => {
+      if (!pending) return
+      addAnnotation(currentSlide, slideTitle, pending.target, text)
+      setPending(null)
+      onShowPanel()
+    },
+    [pending, currentSlide, slideTitle, addAnnotation, onShowPanel]
+  )
+
+  // Track hover for element highlighting
+  const handleMouseMove = useCallback(
+    (e: React.MouseEvent) => {
+      if (pending) {
+        setHoveredElement(null)
+        return
+      }
+
+      const container = slideContainerRef.current
+      if (!container) return
+
+      const overlay = overlayRef.current
+      if (overlay) overlay.style.pointerEvents = "none"
+      const elementUnder = document.elementFromPoint(e.clientX, e.clientY) as HTMLElement | null
+      if (overlay) overlay.style.pointerEvents = ""
+
+      if (elementUnder && container.contains(elementUnder) && elementUnder !== container) {
+        const containerRect = container.getBoundingClientRect()
+        const elRect = elementUnder.getBoundingClientRect()
+        setHoveredElement(
+          new DOMRect(
+            elRect.left - containerRect.left,
+            elRect.top - containerRect.top,
+            elRect.width,
+            elRect.height
+          )
+        )
+      } else {
+        setHoveredElement(null)
+      }
+    },
+    [slideContainerRef, pending]
+  )
+
+  // Clear pending when slide changes
+  useEffect(() => {
+    setPending(null)
+    onSelectId(null)
+    setHoveredElement(null)
+  }, [currentSlide, onSelectId])
+
+  return (
+    <>
+      {/* Hover highlight */}
+      {hoveredElement && (
+        <div
+          className="pointer-events-none absolute z-20 rounded-lg border-2 border-dashed border-[#FF6B35]/50 bg-[#FF6B35]/5"
+          style={{
+            left: hoveredElement.x,
+            top: hoveredElement.y,
+            width: hoveredElement.width,
+            height: hoveredElement.height
+          }}
+        />
+      )}
+
+      {/* Click capture overlay */}
+      <div
+        ref={overlayRef}
+        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` }}
+        onClick={handleOverlayClick}
+        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)
+          }}
+        />
+      ))}
+
+      {/* New annotation form */}
+      {pending && (
+        <AnnotationForm
+          xPercent={pending.xPercent}
+          yPercent={pending.yPercent}
+          onSubmit={handleSubmit}
+          onCancel={() => setPending(null)}
+        />
+      )}
+
+    </>
+  )
+}

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

@@ -0,0 +1,150 @@
+import { MessageCircle, Trash2, X } from "lucide-react"
+import type { Annotation } from "./types"
+
+interface AnnotationPanelProps {
+  annotations: Annotation[]
+  selectedId: string | null
+  onSelect: (id: string) => void
+  onDelete: (id: string) => void
+  onClose: () => void
+}
+
+export function AnnotationPanel({ annotations, selectedId, onSelect, onDelete, onClose }: AnnotationPanelProps) {
+  const open = annotations.filter(a => a.status === "open")
+  const resolved = annotations.filter(a => a.status === "resolved")
+
+  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>
+        <button
+          onClick={onClose}
+          className="rounded-lg p-1.5 text-neutral-500 transition-colors hover:bg-white/[0.06] hover:text-neutral-300"
+        >
+          <X className="h-4 w-4" />
+        </button>
+      </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="flex flex-col items-center gap-2 px-4 py-8 text-center">
+            <div className="flex h-10 w-10 items-center justify-center rounded-xl bg-white/[0.04]">
+              <MessageCircle className="h-5 w-5 text-neutral-600" />
+            </div>
+            <p className="text-sm text-neutral-500">Click on slide elements to add annotations</p>
+          </div>
+        )}
+
+        {open.length > 0 && (
+          <div>
+            <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) => (
+              <AnnotationItem
+                key={a.id}
+                annotation={a}
+                number={i + 1}
+                isSelected={a.id === selectedId}
+                onSelect={() => onSelect(a.id)}
+                onDelete={() => onDelete(a.id)}
+              />
+            ))}
+          </div>
+        )}
+
+        {resolved.length > 0 && (
+          <div className={open.length > 0 ? "mt-3" : ""}>
+            <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) => (
+              <AnnotationItem
+                key={a.id}
+                annotation={a}
+                number={open.length + i + 1}
+                isSelected={a.id === selectedId}
+                onSelect={() => onSelect(a.id)}
+                onDelete={() => onDelete(a.id)}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+function AnnotationItem({
+  annotation,
+  number,
+  isSelected,
+  onSelect,
+  onDelete
+}: {
+  annotation: Annotation
+  number: number
+  isSelected: boolean
+  onSelect: () => void
+  onDelete: () => void
+}) {
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      onClick={onSelect}
+      onKeyDown={e => { if (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]"
+      }`}
+    >
+      <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="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 ${
+            annotation.status === "open"
+              ? "bg-[#FF6B35] text-white"
+              : "bg-neutral-700 text-neutral-400"
+          }`}
+        >
+          {number}
+        </div>
+        <div className="min-w-0 pr-4">
+          <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>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,42 @@
+interface AnnotationPinProps {
+  number: number
+  status: "open" | "resolved"
+  xPercent: number
+  yPercent: number
+  isSelected: boolean
+  onClick: () => void
+}
+
+export function AnnotationPin({ number, status, xPercent, yPercent, isSelected, onClick }: AnnotationPinProps) {
+  const isResolved = status === "resolved"
+
+  return (
+    <button
+      onClick={e => {
+        e.stopPropagation()
+        onClick()
+      }}
+      className="absolute z-30 -translate-x-1/2 -translate-y-1/2 transition-all duration-200 hover:scale-110"
+      style={{ left: `${xPercent}%`, top: `${yPercent}%` }}
+      title={`Annotation #${number}`}
+    >
+      {/* Glow ring */}
+      {isSelected && !isResolved && (
+        <div className="absolute inset-[-4px] animate-pulse rounded-full bg-[#FF6B35]/25 blur-sm" />
+      )}
+      <div
+        className={`relative flex h-7 w-7 items-center justify-center rounded-full text-[11px] font-semibold shadow-lg backdrop-blur-sm transition-all duration-200 ${
+          isSelected
+            ? isResolved
+              ? "bg-neutral-500/90 text-white ring-2 ring-neutral-400/50"
+              : "bg-[#FF6B35] text-white ring-2 ring-[#FF6B35]/40 ring-offset-1 ring-offset-black/50"
+            : isResolved
+              ? "bg-neutral-700/80 text-neutral-400"
+              : "bg-[#FF6B35]/90 text-white hover:bg-[#FF6B35]"
+        }`}
+      >
+        {number}
+      </div>
+    </button>
+  )
+}