promptslide 0.3.6 → 0.3.8

package/src/core/annotations/api.ts

@@ -0,0 +1,23 @@
+import type { Annotation, AnnotationsFile } from "./types"
+
+const ENDPOINT = "/__promptslide_annotations"
+
+export async function fetchAnnotations(): Promise<Annotation[]> {
+  try {
+    const res = await fetch(ENDPOINT)
+    if (!res.ok) return []
+    const data: AnnotationsFile = await res.json()
+    return data.annotations || []
+  } catch {
+    return []
+  }
+}
+
+export async function saveAnnotations(annotations: Annotation[]): Promise<void> {
+  const data: AnnotationsFile = { version: 1, annotations }
+  await fetch(ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(data)
+  })
+}

package/src/core/annotations/index.ts

@@ -0,0 +1,5 @@
+export { AnnotationOverlay } from "./annotation-overlay"
+export { AnnotationPanel } from "./annotation-panel"
+export { useAnnotations } from "./use-annotations"
+export { createHttpAdapter } from "./adapters/http"
+export type { Annotation, AnnotationsFile, AnnotationStorageAdapter, AnnotationTarget } from "./types"

package/src/core/annotations/selectors.ts

@@ -0,0 +1,76 @@
+import type { AnnotationTarget } from "./types"
+
+/**
+ * Build a composite target descriptor from a clicked DOM element.
+ */
+export function buildElementTarget(
+  element: HTMLElement,
+  slideRoot: HTMLElement
+): AnnotationTarget {
+  const rect = element.getBoundingClientRect()
+  const rootRect = slideRoot.getBoundingClientRect()
+
+  const xPercent = ((rect.left + rect.width / 2 - rootRect.left) / rootRect.width) * 100
+  const yPercent = ((rect.top + rect.height / 2 - rootRect.top) / rootRect.height) * 100
+
+  return {
+    dataAnnotate: element.getAttribute("data-annotate") || undefined,
+    contentNearPin: getTextFingerprint(element),
+    position: { xPercent, yPercent }
+  }
+}
+
+/**
+ * Resolve a stored target back to a DOM element, trying strategies in priority order.
+ */
+export function resolveTarget(
+  target: AnnotationTarget,
+  slideRoot: HTMLElement
+): { element: HTMLElement | null; method: "dataAnnotate" | "contentNearPin" | "position" } {
+  // 1. Try data-annotate attribute
+  if (target.dataAnnotate) {
+    const el = slideRoot.querySelector<HTMLElement>(`[data-annotate="${target.dataAnnotate}"]`)
+    if (el) return { element: el, method: "dataAnnotate" }
+  }
+
+  // 2. Try text content match
+  if (target.contentNearPin) {
+    const match = findByTextContent(slideRoot, target.contentNearPin)
+    if (match) return { element: match, method: "contentNearPin" }
+  }
+
+  // 3. Fallback to coordinates (no element found)
+  return { element: null, method: "position" }
+}
+
+/**
+ * Extract a text fingerprint from an element (first 100 chars, trimmed).
+ */
+function getTextFingerprint(element: HTMLElement): string | undefined {
+  const text = element.textContent?.trim()
+  if (!text) return undefined
+  return text.slice(0, 100)
+}
+
+/**
+ * Find an element by matching its text content.
+ */
+function findByTextContent(root: HTMLElement, text: string): HTMLElement | null {
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT)
+  let best: HTMLElement | null = null
+  let bestLength = Infinity
+
+  while (walker.nextNode()) {
+    const el = walker.currentNode as HTMLElement
+    const elText = el.textContent?.trim()
+    if (!elText) continue
+
+    const elFingerprint = elText.slice(0, 100)
+    if (elFingerprint === text && elText.length < bestLength) {
+      best = el
+      bestLength = elText.length
+    }
+  }
+
+  return best
+}

package/src/core/annotations/types.ts

@@ -0,0 +1,47 @@
+/**
+ * Types for the slide annotation system.
+ * Annotations are stored as a JSON file in the project root
+ * and read by coding agents to act on user feedback.
+ */
+
+export interface AnnotationTarget {
+  /** User-assigned data-annotate value, if present on the element */
+  dataAnnotate?: string
+  /** Nearby visible text to help locate the annotated area (first 100 chars, not meant to be edited) */
+  contentNearPin?: string
+  /** Coordinates as percentage of slide dimensions */
+  position: { xPercent: number; yPercent: number }
+}
+
+export interface Annotation {
+  /** Unique identifier */
+  id: string
+  /** Slide index (0-based, matching deck-config order) */
+  slideIndex: number
+  /** Slide title from SlideConfig (informational, for agent readability) */
+  slideTitle: string
+  /** Target element identification */
+  target: AnnotationTarget
+  /** The user's feedback text */
+  body: string
+  /** ISO 8601 timestamp */
+  createdAt: string
+  /** open = needs attention, resolved = agent addressed it */
+  status: "open" | "resolved"
+  /** Agent's note when resolving */
+  resolution?: string
+}
+
+export interface AnnotationsFile {
+  version: 1
+  annotations: Annotation[]
+}
+
+/** Storage adapter for annotation persistence */
+export interface AnnotationStorageAdapter {
+  load(): Promise<Annotation[]>
+  add(annotation: Annotation): Promise<void>
+  remove(id: string): 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

@@ -0,0 +1,50 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import { createHttpAdapter } from "./adapters/http"
+import type { Annotation, AnnotationStorageAdapter, AnnotationTarget } from "./types"
+
+export function useAnnotations(adapter?: AnnotationStorageAdapter) {
+  const adapterRef = useRef(adapter ?? createHttpAdapter())
+  const [annotations, setAnnotations] = useState<Annotation[]>([])
+
+  // Load on mount and subscribe to external updates
+  useEffect(() => {
+    adapterRef.current.load().then(setAnnotations)
+    return adapterRef.current.subscribe?.(setAnnotations)
+  }, [])
+
+  const addAnnotation = useCallback(
+    (slideIndex: number, slideTitle: string, target: AnnotationTarget, body: string) => {
+      const annotation: Annotation = {
+        id: crypto.randomUUID(),
+        slideIndex,
+        slideTitle,
+        target,
+        body,
+        createdAt: new Date().toISOString(),
+        status: "open"
+      }
+      setAnnotations(prev => [...prev, annotation])
+      adapterRef.current.add(annotation)
+    },
+    []
+  )
+
+  const deleteAnnotation = useCallback((id: string) => {
+    setAnnotations(prev => prev.filter(a => a.id !== id))
+    adapterRef.current.remove(id)
+  }, [])
+
+  const getSlideAnnotations = useCallback(
+    (slideIndex: number) => annotations.filter(a => a.slideIndex === slideIndex),
+    [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 }
+}

package/src/core/index.ts

@@ -73,5 +73,9 @@ export { SlideDeck } from "./slide-deck"
 // Error Boundary
 export { SlideErrorBoundary } from "./slide-error-boundary"
 
+// Annotations
+export { AnnotationOverlay, useAnnotations, createHttpAdapter } from "./annotations"
+export type { Annotation, AnnotationsFile, AnnotationStorageAdapter, AnnotationTarget } from "./annotations"
+
 // Utils
 export { cn } from "./utils"

package/src/core/slide-deck.tsx

@@ -1,12 +1,14 @@
 import { LayoutGroup } from "framer-motion"
-import { ChevronLeft, ChevronRight, Download, Grid3X3, List, Maximize, Monitor } from "lucide-react"
-import { useCallback, useEffect, useRef, useState } from "react"
+import { ChevronLeft, ChevronRight, Download, Grid3X3, List, Maximize, MessageCircle, Monitor } from "lucide-react"
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
 
 import type { SlideTransitionType } from "./transitions"
 import type { SlideConfig } from "./types"
 
 import { SLIDE_DIMENSIONS } from "./animation-config"
 import { AnimationProvider } from "./animation-context"
+import { AnnotationOverlay, AnnotationPanel, useAnnotations } from "./annotations"
+import type { Annotation, AnnotationTarget } from "./annotations"
 import { SlideErrorBoundary } from "./slide-error-boundary"
 import { SlideRenderer } from "./slide-renderer"
 import { useSlideNavigation } from "./use-slide-navigation"
@@ -22,6 +24,12 @@ interface SlideDeckProps {
   slides: SlideConfig[]
   transition?: SlideTransitionType
   directionalTransition?: boolean
+  /** Annotation data to display. When provided (even empty array), annotation UI is enabled. When undefined, annotation UI is hidden. */
+  annotations?: Annotation[]
+  /** Called when the user creates an annotation */
+  onAnnotationAdd?: (slideIndex: number, slideTitle: string, target: AnnotationTarget, body: string) => void
+  /** Called when the user deletes an annotation */
+  onAnnotationDelete?: (id: string) => void
 }
 
 // =============================================================================
@@ -66,7 +74,7 @@ function SlideExportView({ slides, slideIndex }: { slides: SlideConfig[]; slideI
 // COMPONENT
 // =============================================================================
 
-export function SlideDeck({ slides, transition, directionalTransition }: SlideDeckProps) {
+export function SlideDeck({ slides, transition, directionalTransition, annotations, onAnnotationAdd, onAnnotationDelete }: SlideDeckProps) {
   // Check for export mode via URL params
   const [exportParams] = useState(() => {
     if (typeof window === "undefined") return null
@@ -79,10 +87,27 @@ export function SlideDeck({ slides, transition, directionalTransition }: SlideDe
     return <SlideExportView slides={slides} slideIndex={exportParams.slideIndex} />
   }
 
+  // Use internal useAnnotations as fallback when no external annotations prop is provided
+  const internal = useAnnotations()
+  const isExternallyManaged = annotations !== undefined
+  const effectiveAnnotations = isExternallyManaged ? annotations : internal.annotations
+  const effectiveAdd = isExternallyManaged ? onAnnotationAdd : internal.addAnnotation
+  const effectiveDelete = isExternallyManaged ? onAnnotationDelete : internal.deleteAnnotation
+
+  const openCount = useMemo(() => effectiveAnnotations.filter(a => a.status === "open").length, [effectiveAnnotations])
+  const getSlideAnnotations = useCallback(
+    (slideIndex: number) => effectiveAnnotations.filter(a => a.slideIndex === slideIndex),
+    [effectiveAnnotations]
+  )
+
   const [viewMode, setViewMode] = useState<ViewMode>("slide")
   const [isPresentationMode, setIsPresentationMode] = useState(false)
+  const [isAnnotationMode, setIsAnnotationMode] = useState(false)
+  const [showAnnotationPanel, setShowAnnotationPanel] = useState(false)
+  const [selectedAnnotationId, setSelectedAnnotationId] = useState<string | null>(null)
   const [scale, setScale] = useState(1)
   const containerRef = useRef<HTMLDivElement>(null)
+  const slideContainerRef = useRef<HTMLDivElement>(null)
 
   const {
     currentSlide,
@@ -162,7 +187,7 @@ export function SlideDeck({ slides, transition, directionalTransition }: SlideDe
         return
       }
 
-      if (viewMode !== "slide") return
+      if (viewMode !== "slide" || isAnnotationMode) return
 
       if (e.key === "ArrowRight" || e.key === " ") {
         e.preventDefault()
@@ -175,7 +200,7 @@ export function SlideDeck({ slides, transition, directionalTransition }: SlideDe
 
     window.addEventListener("keydown", handleKeyDown)
     return () => window.removeEventListener("keydown", handleKeyDown)
-  }, [advance, goBack, viewMode, togglePresentationMode])
+  }, [advance, goBack, viewMode, togglePresentationMode, isAnnotationMode])
 
   return (
     <div className="min-h-screen w-full bg-neutral-950 text-foreground">
@@ -204,8 +229,9 @@ export function SlideDeck({ slides, transition, directionalTransition }: SlideDe
       {/* Toolbar */}
       <div
         className={cn(
-          "fixed top-4 right-4 z-50 flex gap-1 rounded-lg border border-neutral-800 bg-neutral-950/90 p-1 backdrop-blur-sm print:hidden",
-          isPresentationMode && "hidden"
+          "fixed top-4 z-50 flex gap-1 rounded-lg border border-neutral-800 bg-neutral-950/90 p-1 backdrop-blur-sm transition-[right] print:hidden",
+          isPresentationMode && "hidden",
+          isAnnotationMode && showAnnotationPanel ? "right-[19.5rem]" : "right-4"
         )}
       >
         <button
@@ -241,6 +267,31 @@ export function SlideDeck({ slides, transition, directionalTransition }: SlideDe
 
         <div className="mx-1 w-px bg-neutral-800" />
 
+        <button
+          onClick={() => {
+            setIsAnnotationMode(prev => {
+              const next = !prev
+              setShowAnnotationPanel(next)
+              if (!next) setSelectedAnnotationId(null)
+              return next
+            })
+          }}
+          className={cn(
+            "relative rounded-md p-2 text-neutral-400 transition-colors hover:bg-neutral-800 hover:text-white",
+            isAnnotationMode && "bg-[#FF6B35] text-white hover:bg-[#FF7A4A]"
+          )}
+          title="Annotate slides"
+        >
+          <MessageCircle className="h-4 w-4" />
+          {openCount > 0 && (
+            <span className="absolute -top-1 -right-1 flex h-4 w-4 items-center justify-center rounded-full bg-[#FF6B35] text-[10px] font-bold text-white">
+              {openCount}
+            </span>
+          )}
+        </button>
+
+        <div className="mx-1 w-px bg-neutral-800" />
+
         <button
           onClick={handleExportPdf}
           className="rounded-md p-2 text-neutral-400 transition-colors hover:bg-neutral-800 hover:text-white"
@@ -260,88 +311,122 @@ export function SlideDeck({ slides, transition, directionalTransition }: SlideDe
       {/* Slide View */}
       {viewMode === "slide" && (
         <div
-          ref={containerRef}
-          role="presentation"
-          tabIndex={isPresentationMode ? 0 : undefined}
           className={cn(
-            "flex h-screen w-full flex-col items-center justify-center overflow-hidden print:hidden",
-            isPresentationMode ? "bg-black p-0" : "p-4 md:p-8"
+            "flex h-screen w-full print:hidden",
+            isPresentationMode ? "bg-black" : ""
           )}
-          onClick={isPresentationMode ? advance : undefined}
-          onKeyDown={
-            isPresentationMode
-              ? e => {
-                  if (e.key === "Enter" || e.key === " ") advance()
-                }
-              : undefined
-          }
         >
-          <LayoutGroup id="slide-deck">
-            {isPresentationMode ? (
-              <div
-                className="pointer-events-none relative overflow-hidden bg-black"
-                style={{
-                  width: SLIDE_DIMENSIONS.width,
-                  height: SLIDE_DIMENSIONS.height,
-                  transform: `scale(${scale})`,
-                  transformOrigin: "center center"
-                }}
-              >
-                <SlideRenderer
-                  slides={slides}
-                  currentSlide={currentSlide}
-                  animationStep={animationStep}
-                  totalSteps={totalSteps}
-                  direction={direction}
-                  showAllAnimations={showAllAnimations}
-                  transition={transition}
-                  directionalTransition={directionalTransition}
-                  onTransitionComplete={onTransitionComplete}
-                />
-              </div>
-            ) : (
-              <div className="relative aspect-video w-full max-w-7xl overflow-hidden rounded-xl border border-neutral-800 bg-black shadow-2xl">
-                <SlideRenderer
-                  slides={slides}
-                  currentSlide={currentSlide}
-                  animationStep={animationStep}
-                  totalSteps={totalSteps}
-                  direction={direction}
-                  showAllAnimations={showAllAnimations}
-                  transition={transition}
-                  directionalTransition={directionalTransition}
-                  onTransitionComplete={onTransitionComplete}
-                />
-              </div>
+          <div
+            ref={containerRef}
+            role="presentation"
+            tabIndex={isPresentationMode ? 0 : undefined}
+            className={cn(
+              "flex flex-1 flex-col items-center justify-center overflow-hidden",
+              isPresentationMode ? "bg-black p-0" : "p-4 md:p-8"
             )}
-          </LayoutGroup>
-
-          {/* Navigation Controls */}
-          {!isPresentationMode && (
-            <div className="mt-6 flex items-center gap-4">
-              <button
-                onClick={goBack}
-                className="rounded-full border border-neutral-800 bg-black/50 p-2 text-neutral-400 backdrop-blur-sm transition-colors hover:bg-neutral-900 hover:text-white"
-              >
-                <ChevronLeft className="h-5 w-5" />
-              </button>
-              <div className="flex min-w-[4rem] flex-col items-center">
-                <span className="font-mono text-sm text-neutral-500">
-                  {currentSlide + 1} / {slides.length}
-                </span>
-                {slides[currentSlide]?.title && (
-                  <span className="mt-0.5 text-xs text-neutral-600">
-                    {slides[currentSlide].title}
+            onClick={isPresentationMode ? advance : undefined}
+            onKeyDown={
+              isPresentationMode
+                ? e => {
+                    if (e.key === "Enter" || e.key === " ") advance()
+                  }
+                : undefined
+            }
+          >
+            <LayoutGroup id="slide-deck">
+              {isPresentationMode ? (
+                <div
+                  className="pointer-events-none relative overflow-hidden bg-black"
+                  style={{
+                    width: SLIDE_DIMENSIONS.width,
+                    height: SLIDE_DIMENSIONS.height,
+                    transform: `scale(${scale})`,
+                    transformOrigin: "center center"
+                  }}
+                >
+                  <SlideRenderer
+                    slides={slides}
+                    currentSlide={currentSlide}
+                    animationStep={animationStep}
+                    totalSteps={totalSteps}
+                    direction={direction}
+                    showAllAnimations={showAllAnimations}
+                    transition={transition}
+                    directionalTransition={directionalTransition}
+                    onTransitionComplete={onTransitionComplete}
+                  />
+                </div>
+              ) : (
+                <div ref={slideContainerRef} className="relative aspect-video w-full max-w-7xl overflow-hidden rounded-xl border border-neutral-800 bg-black shadow-2xl">
+                  <SlideRenderer
+                    slides={slides}
+                    currentSlide={currentSlide}
+                    animationStep={animationStep}
+                    totalSteps={totalSteps}
+                    direction={direction}
+                    showAllAnimations={showAllAnimations}
+                    transition={transition}
+                    directionalTransition={directionalTransition}
+                    onTransitionComplete={onTransitionComplete}
+                  />
+                  {isAnnotationMode && (
+                    <AnnotationOverlay
+                      slides={slides}
+                      currentSlide={currentSlide}
+                      slideContainerRef={slideContainerRef}
+                      selectedId={selectedAnnotationId}
+                      onSelectId={setSelectedAnnotationId}
+                      onShowPanel={() => setShowAnnotationPanel(true)}
+                      slideAnnotations={getSlideAnnotations(currentSlide)}
+                      addAnnotation={effectiveAdd ?? (() => {})}
+
+                    />
+                  )}
+                </div>
+              )}
+            </LayoutGroup>
+
+            {/* Navigation Controls */}
+            {!isPresentationMode && (
+              <div className="mt-6 flex items-center gap-4">
+                <button
+                  onClick={goBack}
+                  className="rounded-full border border-neutral-800 bg-black/50 p-2 text-neutral-400 backdrop-blur-sm transition-colors hover:bg-neutral-900 hover:text-white"
+                >
+                  <ChevronLeft className="h-5 w-5" />
+                </button>
+                <div className="flex min-w-[4rem] flex-col items-center">
+                  <span className="font-mono text-sm text-neutral-500">
+                    {currentSlide + 1} / {slides.length}
                   </span>
-                )}
+                  {slides[currentSlide]?.title && (
+                    <span className="mt-0.5 text-xs text-neutral-600">
+                      {slides[currentSlide].title}
+                    </span>
+                  )}
+                </div>
+                <button
+                  onClick={advance}
+                  className="rounded-full border border-neutral-800 bg-black/50 p-2 text-neutral-400 backdrop-blur-sm transition-colors hover:bg-neutral-900 hover:text-white"
+                >
+                  <ChevronRight className="h-5 w-5" />
+                </button>
               </div>
-              <button
-                onClick={advance}
-                className="rounded-full border border-neutral-800 bg-black/50 p-2 text-neutral-400 backdrop-blur-sm transition-colors hover:bg-neutral-900 hover:text-white"
-              >
-                <ChevronRight className="h-5 w-5" />
-              </button>
-            </div>
+            )}
+          </div>
+
+          {/* Annotation Panel — beside the slide */}
+          {isAnnotationMode && showAnnotationPanel && !isPresentationMode && (
+            <AnnotationPanel
+              annotations={getSlideAnnotations(currentSlide)}
+              selectedId={selectedAnnotationId}
+              onSelect={setSelectedAnnotationId}
+              onDelete={effectiveDelete ?? (() => {})}
+              onClose={() => {
+                setShowAnnotationPanel(false)
+                setSelectedAnnotationId(null)
+              }}
+            />
           )}
         </div>
       )}

package/src/vite/plugin.mjs

@@ -1,3 +1,5 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs"
+import { join } from "node:path"
 import { bold, dim } from "../utils/ansi.mjs"
 
 const VIRTUAL_ENTRY_ID = "virtual:promptslide-entry"
@@ -156,6 +158,16 @@ export function promptslidePlugin({ root: initialRoot } = {}) {
     name: "promptslide",
     enforce: "pre",
 
+    config() {
+      return {
+        server: {
+          watch: {
+            ignored: ["**/annotations.json"]
+          }
+        }
+      }
+    },
+
     configResolved(config) {
       if (!root) root = config.root
     },
@@ -190,6 +202,48 @@ export function promptslidePlugin({ root: initialRoot } = {}) {
         })
       })
 
+      // Pre-middleware: read annotations
+      server.middlewares.use((req, res, next) => {
+        if (req.method !== "GET" || req.url !== "/__promptslide_annotations") return next()
+
+        const filePath = join(root, "annotations.json")
+        try {
+          if (existsSync(filePath)) {
+            const content = readFileSync(filePath, "utf-8")
+            res.setHeader("Content-Type", "application/json")
+            res.statusCode = 200
+            res.end(content)
+          } else {
+            res.setHeader("Content-Type", "application/json")
+            res.statusCode = 200
+            res.end(JSON.stringify({ version: 1, annotations: [] }))
+          }
+        } catch {
+          res.statusCode = 500
+          res.end()
+        }
+      })
+
+      // Pre-middleware: write annotations
+      server.middlewares.use((req, res, next) => {
+        if (req.method !== "POST" || req.url !== "/__promptslide_annotations") return next()
+
+        let body = ""
+        req.on("data", chunk => { body += chunk })
+        req.on("end", () => {
+          try {
+            const data = JSON.parse(body)
+            const filePath = join(root, "annotations.json")
+            writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8")
+            res.statusCode = 204
+            res.end()
+          } catch {
+            res.statusCode = 400
+            res.end()
+          }
+        })
+      })
+
       // Pre-middleware: serve /embed route
       server.middlewares.use(async (req, res, next) => {
         const url = new URL(req.url, "http://localhost")