@prmichaelsen/acp-visualizer 0.1.0 → 0.1.2

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

@@ -1,169 +0,0 @@
-# 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

@@ -1,115 +0,0 @@
-# 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

@@ -1,98 +0,0 @@
-# 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

@@ -1,156 +0,0 @@
-# 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