@prmichaelsen/acp-visualizer 0.1.0

package/agent/patterns/tanstack-cloudflare.lightbox.md

@@ -0,0 +1,169 @@
+# LightboxContainer & ImageLightbox
+
+**Category**: Design
+**Applicable To**: Full-screen image galleries, memory detail viewers, crop editors, and any swipeable full-screen overlay
+**Status**: Stable
+
+---
+
+## Overview
+
+LightboxContainer is a reusable full-screen shell (portal, z-55) with slide animation, keyboard/swipe navigation, and a counter badge. ImageLightbox extends it for image galleries with crop data, lazy preloading, and scaled previews. Other lightboxes (MemoryLightbox, ImageCropLightbox) also build on LightboxContainer.
+
+---
+
+## Implementation
+
+### LightboxContainer (Shell)
+
+**File**: `src/components/LightboxContainer.tsx`
+
+```typescript
+interface LightboxContainerProps {
+  totalCount: number
+  index: number
+  onPrev: () => void
+  onNext: () => void
+  onClose: () => void
+  navDisabled?: boolean              // Disable keyboard/swipe nav (e.g., during crop edit)
+  onEscapeWhileNavDisabled?: () => void   // Escape exits sub-mode, not lightbox
+  onBackdropClickWhileNavDisabled?: () => void
+  children: ReactNode                // The slide content
+  overlay?: ReactNode                // Non-animated toolbar/controls
+  animatedClassName?: string         // Extra classes on the animated content div
+}
+```
+
+**Features**:
+- Portal to `document.body`, z-55, `bg-black/90 backdrop-blur-sm`
+- Body scroll lock + safe-area-inset-top
+- **Slide animation**: 200ms ease-out, scale(0.92) + translateX(±60px) on exit/enter
+- **Keyboard**: ArrowLeft/Right for prev/next, Escape to close
+- **Touch/swipe**: Horizontal >100px = nav, vertical up >80px from backdrop = dismiss
+- **Navigation UI**: Chevron buttons (hidden on mobile), counter badge at bottom ("3 / 10")
+- Close button (X) top-right with safe-area offset
+
+**Gesture Detection**:
+
+```typescript
+// Horizontal swipe: navigate
+if (deltaX > 100 && absX > absY) onPrev()
+if (deltaX < -100 && absX > absY) onNext()
+// Vertical swipe up from backdrop: dismiss
+if (onBackdrop && deltaY < -80 && absY > absX) onClose()
+```
+
+**Usage** (building a custom lightbox):
+
+```typescript
+function MyLightbox({ items, startIndex, onClose }) {
+  const [index, setIndex] = useState(startIndex)
+  return (
+    <LightboxContainer
+      totalCount={items.length}
+      index={index}
+      onPrev={() => setIndex(i => Math.max(0, i - 1))}
+      onNext={() => setIndex(i => Math.min(items.length - 1, i + 1))}
+      onClose={onClose}
+    >
+      <MySlideContent item={items[index]} />
+    </LightboxContainer>
+  )
+}
+```
+
+---
+
+### ImageLightbox (Gallery Viewer)
+
+**File**: `src/components/ImageLightbox.tsx`
+
+```typescript
+interface ImageLightboxProps {
+  images: Array<{ src: string; alt?: string; crop?: CropData | null }>
+  startIndex: number
+  onClose: () => void
+}
+```
+
+**Features**:
+- Built on LightboxContainer
+- Lazy-loads crop data via HEAD request to image proxy (module-level cache)
+- Preloads adjacent images (current ± 1) to eliminate flash
+- ScaledCropPreview: uses CSS `background-position` + `background-size` for efficient cropped display
+- Max constraints: 95vw width, 85vh height
+- Click-stop propagation on images (prevents backdrop close)
+
+---
+
+### ImageCropLightbox (Crop Editor)
+
+**File**: `src/components/ImageCropLightbox.tsx`
+
+```typescript
+interface ImageCropLightboxProps {
+  images: CropImage[]
+  startIndex: number
+  onClose: () => void
+  onCropChange?: (index: number, crop: CropData) => void
+}
+```
+
+**Features**:
+- Built on LightboxContainer with `navDisabled` during active crop
+- Toggle between view mode and crop mode (Escape exits crop mode, not lightbox)
+- Overlay buttons: crop toggle, reset crop
+- Lazy-loads natural image dimensions for proper crop calculations
+
+---
+
+## Anti-Patterns
+
+### Building Full-Screen Overlays Without LightboxContainer
+
+```typescript
+// Bad: Reimplementing swipe, keyboard, animation, scroll lock
+<div className="fixed inset-0 z-50" onKeyDown={handleKey}>
+  {/* Custom implementation */}
+</div>
+
+// Good: Use LightboxContainer for the shell
+<LightboxContainer totalCount={n} index={i} onPrev={prev} onNext={next} onClose={close}>
+  {/* Just the slide content */}
+</LightboxContainer>
+```
+
+### Forgetting navDisabled for Sub-Modes
+
+```typescript
+// Bad: User swipes during crop edit, navigates away and loses changes
+<LightboxContainer onPrev={prev} onNext={next}>
+  <CropEditor />
+</LightboxContainer>
+
+// Good: Disable nav during sub-mode
+<LightboxContainer
+  navDisabled={cropActive}
+  onEscapeWhileNavDisabled={() => setCropActive(false)}
+  onBackdropClickWhileNavDisabled={() => setCropActive(false)}
+>
+  <CropEditor />
+</LightboxContainer>
+```
+
+---
+
+## Checklist
+
+- [ ] Use LightboxContainer for any full-screen gallery or detail viewer
+- [ ] Set `navDisabled` when entering a sub-mode (crop, edit, etc.)
+- [ ] Provide `onEscapeWhileNavDisabled` to exit sub-mode on Escape
+- [ ] Preload adjacent slides to eliminate flash on navigation
+- [ ] Apply `e.stopPropagation()` on interactive content to prevent backdrop close
+- [ ] Safe-area-inset-top applied via inline style
+
+---
+
+**Status**: Stable
+**Last Updated**: 2026-03-14
+**Contributors**: Community

package/agent/patterns/tanstack-cloudflare.markdown-content.md

@@ -0,0 +1,115 @@
+# Markdown Content Rendering
+
+**Category**: Design
+**Applicable To**: Rendering AI-generated or user-submitted markdown with XSS protection, @mention badges, code blocks, and font size preferences
+**Status**: Stable
+
+---
+
+## Overview
+
+`MarkdownContent` wraps ReactMarkdown with rehype-sanitize for XSS protection, custom mention preprocessing (`@agent`, `@uid:userId`), link validation (internal/external routing), syntax-highlighted code blocks, and user font size preferences. Safe for rendering AI-generated content that may contain arbitrary markdown.
+
+---
+
+## Implementation
+
+**File**: `src/components/chat/MarkdownContent.tsx`
+
+```typescript
+interface MarkdownContentProps {
+  content: string
+  className?: string
+  currentUserId?: string  // For mention badge interactivity
+}
+```
+
+### Processing Pipeline
+
+```
+Raw content
+  → stripTimestampPrefix()     // Remove <msg ts="..."/> prefixes
+  → linkifyText()              // Convert bare URLs to [url](url) markdown
+  → preprocessMentions()       // @agent → **@agent**, @uid:X → **@uid:X**
+  → ReactMarkdown
+      + rehype-sanitize        // Strip XSS vectors
+      + custom components      // Links, code, strong (mentions)
+```
+
+### XSS Sanitization
+
+```typescript
+const sanitizeSchema = {
+  ...defaultSchema,
+  attributes: {
+    code: [...(defaultSchema.attributes?.code || []), 'className'],
+    a: ['href', 'title'],
+  },
+  protocols: { href: ['http', 'https', 'mailto'] },
+  tagNames: (defaultSchema.tagNames || []).filter(tag =>
+    !['script', 'iframe', 'object', 'embed', 'style'].includes(tag)
+  ),
+}
+```
+
+### Link Routing
+
+```typescript
+// Internal links (/memory/abc): navigate within app
+// External links (https://...): target="_blank" rel="noopener noreferrer"
+// Invalid URLs: render as red [Invalid Link] span
+
+function isInternalUrl(url: string): boolean { return url.startsWith('/') }
+function isValidUrl(url: string): boolean {
+  if (url.startsWith('/')) return true
+  try { return ['http:', 'https:', 'mailto:'].includes(new URL(url).protocol) }
+  catch { return false }
+}
+```
+
+### Code Blocks
+
+```typescript
+// Multiline → CodeBlock component with syntax highlighting + copy button
+// Inline → gray background with font size preference
+const isCodeBlock = code.includes('\n') || startLine !== endLine
+if (isCodeBlock) return <CodeBlock code={code} language={language} />
+return <code className="bg-gray-700 px-1.5 py-0.5 rounded">{children}</code>
+```
+
+### Mention Badges
+
+`@agent` and `@uid:userId` are preprocessed to bold markdown, then the `strong` renderer detects them:
+
+```typescript
+strong({ children }) {
+  const text = extractText(children)
+  if (text === '@agent') return <span className="bg-blue-500/20 text-blue-400 ...">@agent</span>
+  if (text.startsWith('@uid:')) return <MentionBadge userId={text.slice(5)} />
+  return <strong>{children}</strong>
+}
+```
+
+### Font Size Integration
+
+Uses `useUIPreferencesLocal()` context — heading sizes and prose classes scale with preference.
+
+---
+
+## Anti-Patterns
+
+### Rendering Unsanitized HTML
+
+```typescript
+// Bad: XSS vulnerability
+<div dangerouslySetInnerHTML={{ __html: aiResponse }} />
+
+// Good: ReactMarkdown + rehype-sanitize
+<MarkdownContent content={aiResponse} />
+```
+
+---
+
+**Status**: Stable
+**Last Updated**: 2026-03-14
+**Contributors**: Community

package/agent/patterns/tanstack-cloudflare.mention-suggestions.md

@@ -0,0 +1,98 @@
+# Mention Suggestion System
+
+**Category**: Design
+**Applicable To**: @mention autocomplete in chat inputs with instant context + async search tiers
+**Status**: Stable
+
+---
+
+## Overview
+
+A two-tier mention autocomplete: Tier 1 (instant) uses in-memory conversation participant profiles for sub-millisecond results. Tier 2 (async) searches the global people index via API when the context tier has no matches. Stale call detection prevents race conditions. Suggestions sorted by: agent first → prefix matches → substring matches.
+
+---
+
+## Implementation
+
+### useMentionSuggestions Hook
+
+**File**: `src/hooks/useMentionSuggestions.ts`
+
+```typescript
+interface MentionSuggestion {
+  id: string                    // userId or 'agent'
+  username: string
+  type: 'agent' | 'user'
+  avatarUrl?: string
+  displayName?: string
+  section?: 'context' | 'search'
+}
+
+function useMentionSuggestions(participantIds?: string[]) {
+  const contextProfilesRef = useRef<Map<string, UserProfile>>(new Map())
+  const callIdRef = useRef(0)  // Stale call detection
+
+  // Tier 1: Load participant profiles on mount
+  useEffect(() => {
+    if (!participantIds?.length) return
+    ProfileService.getProfiles(participantIds).then(profiles => {
+      contextProfilesRef.current = new Map(Object.entries(profiles))
+    })
+  }, [participantIds?.join(',')])
+
+  const getSuggestions = useCallback(async (query: string) => {
+    const thisCallId = ++callIdRef.current
+
+    // Tier 1: Instant context matches
+    const contextResults = matchFromContext(query, contextProfilesRef.current)
+
+    // Tier 2: Async global search (if context insufficient)
+    if (contextResults.length < 3 && query.length >= 1) {
+      const searchResults = await PeopleService.search(query, 5)
+      if (callIdRef.current !== thisCallId) return []  // Stale
+      return [...contextResults, ...searchResults]
+    }
+
+    return contextResults
+  }, [])
+
+  return { getSuggestions }
+}
+```
+
+### MentionAutocomplete Component
+
+**File**: `src/components/chat/MentionAutocomplete.tsx`
+
+```typescript
+interface MentionAutocompleteProps {
+  inputValue: string
+  textareaRef: RefObject<HTMLTextAreaElement | null>
+  onSelect: (suggestion, startIndex, endIndex) => void
+  getSuggestions?: (query: string) => MentionSuggestion[] | Promise<MentionSuggestion[]>
+  maxResults?: number
+  reverse?: boolean  // Bottom-to-top rendering (closest to input = most relevant)
+}
+```
+
+**Mention Detection**: Scans backwards from cursor for `@` preceded by whitespace or start-of-input.
+
+**Keyboard Navigation**: ArrowUp/Down (flipped in reverse mode), Enter/Tab to select, Escape to close.
+
+**Text Insertion**: `onSelect(suggestion, @position, endPosition)` — caller replaces the `@query` range with `@username `.
+
+---
+
+## Checklist
+
+- [ ] Tier 1 profiles loaded from conversation participants on mount
+- [ ] Tier 2 search triggered when context has < 3 matches
+- [ ] Stale call detection via incrementing callIdRef
+- [ ] Agent suggestion always appears first if query matches
+- [ ] `reverse` mode used when autocomplete renders above input
+
+---
+
+**Status**: Stable
+**Last Updated**: 2026-03-14
+**Contributors**: Community

package/agent/patterns/tanstack-cloudflare.modal.md

@@ -0,0 +1,156 @@
+# Modal & Confirmation Modal
+
+**Category**: Design
+**Applicable To**: All dialog overlays, confirmations, form modals, and persistent consent dialogs
+**Status**: Stable
+
+---
+
+## Overview
+
+The Modal system provides a portal-rendered overlay (z-55) with backdrop blur, escape/click-outside dismissal, body scroll lock, and safe-area-inset-top support. ConfirmationModal extends it with variant-colored icons and a two-button confirm/cancel footer. Use `persistent: true` to disable all dismissal paths for consent flows.
+
+---
+
+## Implementation
+
+### Modal (Base)
+
+**File**: `src/components/modals/Modal.tsx`
+
+```typescript
+interface ModalProps {
+  isOpen: boolean
+  onClose: () => void
+  children: React.ReactNode
+  title?: string
+  style?: React.CSSProperties
+  maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+  persistent?: boolean  // Disables Escape, backdrop click, and close button
+}
+```
+
+**Behavior**:
+- `createPortal` to `document.body` at z-index 55
+- Backdrop: `bg-black/50 backdrop-blur-sm`, click-outside closes (unless persistent)
+- Escape key closes (unless persistent)
+- Body scroll lock: `document.body.style.overflow = 'hidden'` on mount, restored on unmount
+- Close button (X) top-right, hidden when persistent
+- Title rendered above children if provided
+- `paddingTop: env(safe-area-inset-top)` on the fixed container
+- Backdrop click uses `e.target === e.currentTarget` to avoid closing on content clicks
+
+**Usage**:
+
+```typescript
+<Modal isOpen={showModal} onClose={() => setShowModal(false)} title="Edit Item" maxWidth="md">
+  <form>{/* form content */}</form>
+</Modal>
+```
+
+---
+
+### ConfirmationModal
+
+**File**: `src/components/modals/ConfirmationModal.tsx`
+
+```typescript
+interface ConfirmationModalProps {
+  isOpen: boolean
+  onClose: () => void
+  onConfirm: () => void
+  title: string
+  message: string | React.ReactNode
+  confirmText?: string   // default: "Confirm"
+  cancelText?: string    // default: "Cancel"
+  variant?: 'danger' | 'warning' | 'info'
+  isLoading?: boolean
+}
+```
+
+**Behavior**:
+- Built on Modal (sm width)
+- Variant-colored gradient icon circle at top:
+  - `danger`: purple-pink gradient
+  - `warning`: yellow-orange gradient
+  - `info`: blue-cyan gradient
+- Two-button footer: Cancel (gray) | Confirm (variant gradient)
+- Both buttons disabled during `isLoading`
+- Prevents modal dismiss during loading: passes `() => {}` as `onClose` to Modal
+
+**Usage**:
+
+```typescript
+<ConfirmationModal
+  isOpen={showDelete}
+  onClose={() => setShowDelete(false)}
+  onConfirm={handleDelete}
+  title="Delete Memory"
+  message="This action cannot be undone."
+  confirmText="Delete"
+  variant="danger"
+  isLoading={deleting}
+/>
+```
+
+---
+
+### SuccessModal
+
+**File**: `src/components/modals/SuccessModal.tsx`
+
+```typescript
+interface SuccessModalProps {
+  isOpen: boolean
+  onClose: () => void
+  title: string
+  message: React.ReactNode
+}
+```
+
+Single "Close" button with blue-cyan gradient. Check icon in gradient circle.
+
+---
+
+## Anti-Patterns
+
+### Rendering Modal Content Without Portal
+
+```typescript
+// Bad: Modal renders in component tree, z-index conflicts with parents
+<div className="relative z-10">
+  <div className="fixed inset-0 bg-black/50">{content}</div>
+</div>
+
+// Good: Use Modal component (portals to document.body)
+<Modal isOpen={open} onClose={close}>{content}</Modal>
+```
+
+### Forgetting isLoading Guard on Dismiss
+
+```typescript
+// Bad: User can close modal while async confirm is running
+<Modal isOpen={open} onClose={() => setOpen(false)}>
+  <button onClick={asyncConfirm}>Confirm</button>
+</Modal>
+
+// Good: Disable dismiss during loading
+<ConfirmationModal isLoading={loading} onClose={() => setOpen(false)} ... />
+// ConfirmationModal internally passes () => {} as onClose when loading
+```
+
+---
+
+## Checklist
+
+- [ ] Use `Modal` base for custom dialogs, `ConfirmationModal` for confirm/cancel flows
+- [ ] Set `persistent: true` for consent/TOS dialogs that must not be dismissed
+- [ ] Set `maxWidth` appropriately (sm for confirms, md-lg for forms, xl-2xl for complex content)
+- [ ] Guard dismiss during async operations with `isLoading`
+- [ ] Content uses max-h-[90vh] with overflow-auto for long content
+
+---
+
+**Status**: Stable
+**Last Updated**: 2026-03-14
+**Contributors**: Community