@prmichaelsen/acp-visualizer 0.1.0 → 0.1.2

package/agent/patterns/tanstack-cloudflare.firebase-storage.md

@@ -1,369 +0,0 @@
-# Firebase Storage
-
-**Category**: Code
-**Applicable To**: All file upload/download, signed URL generation, image proxy, content moderation, and storage cleanup
-**Status**: Stable
-
----
-
-## Overview
-
-This pattern covers how Firebase Storage is used via `@prmichaelsen/firebase-admin-sdk-v8` for file operations: chunked WebSocket uploads through a Durable Object, signed URL generation, server-side image proxy with ACL, content moderation via Google Cloud Vision, and storage cleanup on account deletion. The upload pipeline streams files from client → UploadManager DO → Firebase Storage with two-phase progress reporting.
-
----
-
-## When to Use This Pattern
-
-**Use this pattern when:**
-- Adding a new file upload flow (new media type or storage path)
-- Generating signed URLs for stored files
-- Building an endpoint that serves or proxies stored files
-- Adding content moderation to a new upload type
-- Implementing storage cleanup for a new entity type
-
-**Don't use this pattern when:**
-- Storing structured data (use Firestore — see `tanstack-cloudflare.firebase-firestore`)
-- Working with client-only file handling (canvas, blob URLs)
-- Building external storage integrations (S3, R2, etc.)
-
----
-
-## Core Principles
-
-1. **WebSocket Streaming**: Uploads use chunked WebSocket messages through a Durable Object, bypassing request size limits
-2. **Deny-All-Read Storage Rules**: Firebase Storage rules deny all direct reads — the image proxy (`/api/storage/image`) is the only access path
-3. **Fail-Open Moderation**: If Google Vision API is down, uploads proceed — best-effort safety, never block on transient failures
-4. **Metadata-Driven ACL**: File metadata (userId, conversationId) stored in Firebase is the source of truth for access control, not URL parameters
-5. **Two-Phase Progress**: 0–50% = client-to-DO transfer, 50–100% = DO-to-Firebase upload
-
----
-
-## Implementation
-
-### Storage Path Structure
-
-**File**: `src/constant/collections.ts`
-
-```typescript
-export const STORAGE_BASE = BASE.replace(/\./g, '_')
-// Paths: {STORAGE_BASE}/users/{userId}/{path}/{mediaId}
-```
-
-| Media Type | Path | Example |
-|---|---|---|
-| Chat images | `['chat']` | `agentbase/users/abc/chat/media123` |
-| Profile avatars | `['profile', 'avatar']` | `agentbase/users/abc/profile/avatar/media123` |
-| Profile banners | `['profile', 'banner']` | `agentbase/users/abc/profile/banner/media123` |
-| Widget images | `['profile', 'widgets']` | `agentbase/users/abc/profile/widgets/media123` |
-
-### Upload Flow
-
-```
-Client (upload-client.ts)          UploadManager DO              Firebase Storage
-  │                                    │                              │
-  ├─ WebSocket connect ──────────►     │                              │
-  ├─ init { userId, path, size } ──►   │                              │
-  │  ◄─── ready ──────────────────     │                              │
-  ├─ chunk (256KB base64) ────────►    │ (buffers in memory)          │
-  ├─ chunk ────────────────────────►   │                              │
-  ├─ chunk (final) ────────────────►   │                              │
-  │   (0-50% progress)                 │                              │
-  │                                    ├─ Content moderation ────►    │
-  │  ◄─── moderating ─────────────    │  (Vision SafeSearch)         │
-  │  ◄─── moderation_result ──────    │                              │
-  │                                    ├─ uploadFileResumable() ────► │
-  │  ◄─── firebase_progress ──────    │  (1MB chunks, 50-100%)      │
-  │                                    │  ◄───── upload complete ──── │
-  │                                    ├─ generateSignedUrl() ──────► │
-  │  ◄─── success { signedUrl } ───   │  ◄───── signed URL ──────── │
-```
-
-### Key SDK Functions
-
-```typescript
-import {
-  uploadFileResumable,  // Upload with progress tracking
-  generateSignedUrl,    // Time-limited read URLs
-  downloadFile,         // Download file buffer
-  getFileMetadata,      // File metadata (content-type, custom metadata)
-  listFiles,            // Paginated file listing
-  deleteFile,           // Delete single file
-} from '@prmichaelsen/firebase-admin-sdk-v8'
-```
-
-### UploadManager Durable Object
-
-**File**: `src/durable-objects/UploadManager.ts`
-
-Upload to Firebase with progress:
-
-```typescript
-await uploadFileResumable(storagePath, completeBuffer, contentType, {
-  chunkSize: 1024 * 1024, // 1MB chunks to Firebase
-  onProgress: (uploaded, total) => {
-    const pct = 50 + Math.round((uploaded / total) * 50) // 50-100% phase
-    ws.send(JSON.stringify({ type: 'firebase_progress', progress: pct }))
-  },
-  metadata: {
-    userId,
-    path: path.join('/'),
-    uploadedAt: new Date().toISOString(),
-    ...customMetadata,
-  },
-})
-```
-
-Generate signed URL after upload:
-
-```typescript
-const expiresAt = new Date(Date.now() + expiresIn * 1000)
-const signedUrl = await generateSignedUrl(storagePath, {
-  action: 'read',
-  expires: expiresAt,
-})
-```
-
-### Content Moderation
-
-**File**: `src/constant/moderation.ts`
-
-```typescript
-export const MODERATION_CONFIG = {
-  adult: {
-    reject: ['VERY_LIKELY'] as const,
-    warn: ['LIKELY', 'POSSIBLE'] as const,
-  },
-  violence: {
-    reject: ['VERY_LIKELY'] as const,
-    warn: ['LIKELY', 'POSSIBLE'] as const,
-  },
-  racy: {
-    reject: [] as const, // Never reject on racy alone
-    warn: [] as const,
-  },
-  failOpen: true,  // Allow upload if Vision API fails
-  skipContentTypes: ['image/svg+xml'],
-}
-```
-
-Moderation is skipped for: video files, SVG images, and `skipModeration: true` uploads (e.g., profile avatars use a separate moderation flow).
-
-### Image Proxy (ACL Enforcement)
-
-**File**: `src/routes/api/storage/image.tsx`
-
-Access tiers (checked in order):
-1. **Owner**: Requesting user === file owner → allow
-2. **Profile images**: Path contains `/profile/` → allow (public)
-3. **Space content**: Path contains `/spaces/` → allow (public)
-4. **Chat DM**: Query conversation, validate participant membership
-5. **Chat Group**: Query conversation, validate `can_read` permission
-6. **Deny**: All others → 403
-
-```typescript
-// Download and serve the file
-const buffer = await downloadFile(storagePath)
-const metadata = await getFileMetadata(storagePath)
-
-return new Response(buffer, {
-  headers: {
-    'Content-Type': metadata.contentType || 'application/octet-stream',
-    'Cache-Control': isPublic ? 'public, max-age=3300' : 'private, max-age=3300',
-    'X-Crop-X': cropData?.x?.toString() ?? '',
-    // ... other crop metadata headers
-  },
-})
-```
-
-### MediaStorageService (Domain Wrapper)
-
-**File**: `src/services/media-storage.service.ts`
-
-High-level methods that set path and metadata for each use case:
-
-```typescript
-static async saveChatImage(file, userId, conversationId, messageId, callbacks) {
-  return uploadToStorage(file, userId, {
-    path: ['chat'],
-    metadata: { conversationId, messageId, mediaType: 'image' },
-    ...callbacks,
-  })
-}
-
-static async saveProfileAvatar(file, userId, callbacks) {
-  return uploadToStorage(file, userId, {
-    path: ['profile', 'avatar'],
-    metadata: { mediaType: 'avatar' },
-    skipModeration: true,  // Uses separate moderation flow
-    ...callbacks,
-  })
-}
-```
-
----
-
-## Examples
-
-### Example 1: Downloading a File for AI Processing
-
-**File**: `src/lib/chat/message-formatter.ts`
-
-```typescript
-import { downloadFile } from '@prmichaelsen/firebase-admin-sdk-v8'
-
-const buffer = await downloadFile(storagePath)
-let text = new TextDecoder('utf-8').decode(buffer)
-const MAX_FILE_BYTES = 50 * 1024
-if (text.length > MAX_FILE_BYTES) {
-  text = text.slice(0, MAX_FILE_BYTES) + '...[truncated]'
-}
-content.push({ type: 'text', text: `[File: ${fileName}]\n${text}\n[End File]` })
-```
-
-### Example 2: Bulk Storage Cleanup on Account Deletion
-
-**File**: `src/services/account-deletion.service.ts`
-
-```typescript
-import { listFiles, deleteFile } from '@prmichaelsen/firebase-admin-sdk-v8'
-
-const prefix = `${STORAGE_BASE}/users/${userId}/`
-let pageToken: string | undefined
-
-do {
-  const listResult = await listFiles({
-    prefix,
-    maxResults: 500,
-    ...(pageToken ? { pageToken } : {}),
-  })
-
-  for (const file of listResult.files) {
-    await deleteFile(file.name)
-  }
-
-  pageToken = listResult.nextPageToken
-} while (pageToken)
-```
-
-### Example 3: Crop Metadata Storage
-
-**File**: `src/services/media-crop-database.service.ts`
-
-Crop coordinates stored in Firestore at `{BASE}.users/{userId}/media-crops/{mediaId}`:
-
-```typescript
-static async setCrop(userId: string, mediaId: string, storagePath: string, crop: CropData) {
-  const collection = getUserMediaCropsCollection(userId)
-  await setDocument(collection, mediaId, {
-    media_id: mediaId,
-    storage_path: storagePath,
-    crop,
-    created_at: new Date().toISOString(),
-    updated_at: new Date().toISOString(),
-  })
-}
-```
-
-Crop metadata returned as response headers from the image proxy:
-`X-Crop-X`, `X-Crop-Y`, `X-Crop-Width`, `X-Crop-Height`, `X-Image-Width`, `X-Image-Height`
-
----
-
-## Anti-Patterns
-
-### Serving Files Directly from Signed URLs
-
-```typescript
-// Bad: Bypasses ACL — anyone with the URL can access
-const url = await generateSignedUrl(path, { action: 'read', expires })
-return new Response(JSON.stringify({ url }))  // Client fetches directly
-
-// Good: Proxy through server with ACL checks
-const buffer = await downloadFile(path)
-// ... validate ACL ...
-return new Response(buffer, { headers: { 'Content-Type': contentType } })
-```
-
-### Trusting URL Parameters for ACL
-
-```typescript
-// Bad: Client-supplied conversationId used for access check
-const convId = url.searchParams.get('conversationId')
-
-// Good: Read conversationId from file metadata (server source of truth)
-const metadata = await getFileMetadata(storagePath)
-const convId = metadata.metadata?.conversationId
-```
-
-### Blocking Uploads on Moderation Failure
-
-```typescript
-// Bad: API error blocks the upload entirely
-const result = await VisionService.analyzeImage(buffer)
-if (!result) throw new Error('Moderation failed')  // Blocks upload
-
-// Good: Fail open — allow upload if Vision API is unavailable
-try {
-  const result = await VisionService.analyzeImage(buffer)
-  if (shouldReject(result)) { reject(); return }
-} catch {
-  // Vision API down — allow upload (fail-open)
-}
-```
-
----
-
-## Key Design Decisions
-
-### Upload Architecture
-
-| Decision | Choice | Rationale |
-|---|---|---|
-| Upload transport | WebSocket via Durable Object | Bypasses HTTP body size limits; enables progress tracking |
-| Chunk size (client→DO) | 256KB | Stays under 1MiB Cloudflare WebSocket message limit after base64 |
-| Chunk size (DO→Firebase) | 1MB | Optimal for Firebase resumable uploads |
-| DO instance key | `idFromName(userId)` | One DO per user; consistent instance across uploads |
-
-### Security
-
-| Decision | Choice | Rationale |
-|---|---|---|
-| Storage rules | Deny-all-read | Forces all access through server-side ACL proxy |
-| ACL source of truth | File metadata (not URL params) | Prevents parameter tampering |
-| Moderation strategy | Fail-open, reject only VERY_LIKELY | Minimizes false positives while catching obvious violations |
-| Video uploads | Blocked entirely | No moderation pipeline for video yet |
-
-### Performance
-
-| Decision | Choice | Rationale |
-|---|---|---|
-| Image proxy caching | `max-age=3300` (~55 min) | Balances freshness with CDN efficiency |
-| Usage tracking | Fire-and-forget after upload | Don't block upload success on quota tracking |
-| Image compression | Client-side to ≤1568px, 0.85 JPEG | Claude-optimal size; reduces upload time |
-
----
-
-## Checklist for Implementation
-
-- [ ] Storage path uses `STORAGE_BASE` constant, not hardcoded prefix
-- [ ] New upload type added to `MediaStorageService` with correct path and metadata
-- [ ] Content moderation configured for new image upload types (skip for non-images)
-- [ ] Image proxy updated with ACL rules for new access patterns
-- [ ] `UsageDatabaseService.incrementStorage()` called after successful upload
-- [ ] Account deletion cleanup handles new storage paths
-- [ ] Client-side image compression applied before upload (if applicable)
-
----
-
-## Related Patterns
-
-- **[Firebase Auth](./tanstack-cloudflare.firebase-auth.md)**: Auth verification required before upload and download operations
-- **[Firebase Firestore](./tanstack-cloudflare.firebase-firestore.md)**: Crop metadata and usage tracking stored in Firestore
-- **[Database Service Conventions](./database-service-conventions.md)**: MediaCropDatabaseService follows standard conventions
-
----
-
-**Status**: Stable
-**Recommendation**: Follow this pattern for all new file upload/download features. Always proxy through the image API — never expose signed URLs directly to clients.
-**Last Updated**: 2026-03-14
-**Contributors**: Community

package/agent/patterns/tanstack-cloudflare.form-controls.md

@@ -1,145 +0,0 @@
-# Form Controls: Slider & ToggleSwitch
-
-**Category**: Design
-**Applicable To**: Range inputs and boolean toggles
-**Status**: Stable
-
----
-
-## Overview
-
-Two reusable form control components: Slider (continuous/discrete range input with gradient fill) and ToggleSwitch (iOS-style boolean toggle with ARIA support). Both follow consistent dark theme styling and are fully keyboard accessible. For pagination controls (Paginator, PaginationToggle, InfiniteScrollSentinel, Virtuoso), see [Pagination Suite](./tanstack-cloudflare.pagination.md).
-
----
-
-## Implementation
-
-### Slider
-
-**File**: `src/components/Slider.tsx`
-
-```typescript
-// Continuous mode
-interface SliderContinuousProps {
-  min: number
-  max: number
-  step: number
-  value: number
-  onChange: (value: number) => void
-}
-
-// Discrete mode
-interface SliderDiscreteProps {
-  options: Array<{ value: number; label?: string }>
-  value: number
-  onChange: (value: number) => void
-}
-```
-
-**Features**:
-- **Continuous**: Standard min/max/step range input
-- **Discrete**: Snaps to predefined option values, optional labels below
-- **Gradient fill**: `linear-gradient(90deg, #3b82f6 0%, #8b5cf6 ${pct}%, rgb(55 65 81) ${pct}%)`
-- Custom CSS class `slider-styled` in `styles.css`:
-  - Thumb: 20px circle, box-shadow, -7px margin-top
-  - Track: 6px height, 3px border-radius
-- Keyboard: Left/Right arrows adjust value
-
-**Usage**:
-```typescript
-<Slider min={0} max={100} step={5} value={volume} onChange={setVolume} />
-
-<Slider
-  options={[
-    { value: 0, label: 'Off' },
-    { value: 50, label: 'Medium' },
-    { value: 100, label: 'Max' },
-  ]}
-  value={level}
-  onChange={setLevel}
-/>
-```
-
----
-
-### ToggleSwitch
-
-**File**: `src/components/ToggleSwitch.tsx`
-
-```typescript
-interface ToggleSwitchProps {
-  checked: boolean
-  onChange: (checked: boolean) => void
-  size?: 'sm' | 'md' | 'lg'  // default: 'md'
-  label?: string
-  description?: string
-  disabled?: boolean
-  id?: string
-}
-```
-
-**Features**:
-- iOS-style toggle with animated knob
-- **Checked**: gradient background `from-purple-600 to-blue-600`, checkmark inside knob
-- **Unchecked**: `bg-gray-700`, plain knob
-- Size presets (md: track w-11 h-6, knob w-5 h-5)
-- Keyboard: Space/Enter toggles
-- `role="switch"`, `aria-checked` for accessibility
-- `focus-visible:ring-2 ring-purple-500` focus ring
-- Optional label + description text
-- Disabled: `opacity-50 cursor-not-allowed`
-
-**Usage**:
-```typescript
-<ToggleSwitch
-  checked={darkMode}
-  onChange={setDarkMode}
-  label="Dark Mode"
-  description="Use dark color scheme throughout the app"
-/>
-```
-
----
-
-## Anti-Patterns
-
-### Using Native Checkbox Instead of ToggleSwitch
-
-```typescript
-// Bad: Inconsistent with app design
-<input type="checkbox" checked={value} onChange={...} />
-
-// Good: Use ToggleSwitch for visual consistency
-<ToggleSwitch checked={value} onChange={setValue} label="Enable feature" />
-```
-
-### Inline Range Input Instead of Slider
-
-```typescript
-// Bad: No gradient fill, no discrete mode support
-<input type="range" min={0} max={100} />
-
-// Good: Use Slider with gradient and optional discrete options
-<Slider min={0} max={100} step={1} value={val} onChange={setVal} />
-```
-
----
-
-## Checklist
-
-- [ ] Use `Slider` for any range/value selection (not raw `<input type="range">`)
-- [ ] Use `ToggleSwitch` for boolean settings (not checkboxes)
-- [ ] ToggleSwitch has `role="switch"` and `aria-checked`
-- [ ] All controls are keyboard accessible
-
----
-
-## Related Patterns
-
-- **[Pagination Suite](./tanstack-cloudflare.pagination.md)**: Paginator, PaginationToggle, InfiniteScrollSentinel, Virtuoso patterns
-
----
-
-**Status**: Stable
-**Last Updated**: 2026-03-14
-**Contributors**: Community

package/agent/patterns/tanstack-cloudflare.global-search-context.md

@@ -1,93 +0,0 @@
-# Global Search Context
-
-**Category**: Architecture
-**Applicable To**: Cross-component state sharing without Redux — search queries, filters, or any key-scoped shared state
-**Status**: Stable
-
----
-
-## Overview
-
-A lightweight pub/sub mechanism using React Context + `useRef` that enables multiple components to share state by key without Redux. Components call `useGlobalSearch(key)` and get a `[value, setValue]` tuple. Setting a value notifies only subscribers of that key, avoiding unnecessary renders for unrelated keys.
-
----
-
-## Implementation
-
-**File**: `src/contexts/GlobalSearchContext.tsx`
-
-```typescript
-interface Store {
-  values: Map<string, string>
-  subscribers: Map<string, Set<() => void>>
-}
-
-const GlobalSearchContext = createContext<Store>(/* ... */)
-
-function GlobalSearchProvider({ children }: { children: ReactNode }) {
-  const storeRef = useRef<Store>({
-    values: new Map(),
-    subscribers: new Map(),
-  })
-  return (
-    <GlobalSearchContext.Provider value={storeRef.current}>
-      {children}
-    </GlobalSearchContext.Provider>
-  )
-}
-
-function useGlobalSearch(key: string): [string, (value: string) => void] {
-  const store = useContext(GlobalSearchContext)
-  const [, setTick] = useState(0)  // Force re-render
-
-  useEffect(() => {
-    const bump = () => setTick(t => t + 1)
-    if (!store.subscribers.has(key)) store.subscribers.set(key, new Set())
-    store.subscribers.get(key)!.add(bump)
-    return () => { store.subscribers.get(key)?.delete(bump) }
-  }, [store, key])
-
-  const value = store.values.get(key) ?? ''
-
-  const setValue = useCallback((v: string) => {
-    const current = store.values.get(key) ?? ''
-    if (current === v) return  // Skip if unchanged
-    if (v) store.values.set(key, v)
-    else store.values.delete(key)
-    store.subscribers.get(key)?.forEach(fn => fn())
-  }, [store, key])
-
-  return [value, setValue]
-}
-```
-
-**Usage**:
-
-```typescript
-// Component A (search input)
-const [query, setQuery] = useGlobalSearch('memories:query')
-<input value={query} onChange={e => setQuery(e.target.value)} />
-
-// Component B (feed list) — subscribes to same key
-const [query] = useGlobalSearch('memories:query')
-// Re-renders only when memories:query changes
-
-// Component C (different key) — NOT re-rendered
-const [filter] = useGlobalSearch('conversations:filter')
-```
-
-**Key conventions**: `{page}:{field}` (e.g., `memories:query`, `conversations:filter`, `messages:query`)
-
----
-
-## Checklist
-
-- [ ] Wrap app in `<GlobalSearchProvider>` (in root layout)
-- [ ] Use key convention `{page}:{field}` for scope isolation
-- [ ] Don't use for non-search state — this is optimized for string values
-
----
-
-**Status**: Stable
-**Last Updated**: 2026-03-14
-**Contributors**: Community