@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/components/features/.video-bites-display.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 5b4e3ad25ef1abb4f28d722afea48eb0 -->
+Renders a responsive, lazily-loaded grid of short video bites grouped by aspect ratio (portrait, square, landscape), using viewport-gating to defer off-screen player mounts and prevent cumulative layout shift (CLS).
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `VideoBitesDisplay` | Component | Primary public component; filters, sorts, and groups bites by aspect ratio |
+| `VideoBiteCard` | Component | Individual bite card wrapping `<Video>` inside a styled `<Card>` |
+| `LazyBite` | Component (internal) | Defers child mount until within 500px of the viewport via `useNearViewport` |
+| `BiteGrid` | Component (internal) | Renders ratio-appropriate column grid with each bite wrapped in `LazyBite` |
+
+## Key Behaviors
+
+- **Filtering & sorting**: Optionally filters to published bites only, sorted newest-first by `created_at`
+- **Aspect ratio grouping**: When multiple ratios exist, renders `<RatioTabs>`; otherwise falls back to a flat `<BiteGrid>`
+- **CLS prevention**: `LazyBite` uses a CSS `aspect-ratio` placeholder matching the bite's ratio before the player mounts; `layout="fill"` on `<Video>` fills the card from first paint
+- **Player routing**: All bites go through the `<Video>` primitive (no raw `VideoPlayer` carve-out) since MuxPlayer loads its HLS engine lazily
+
+## Usage Example
+
+```typescript
+import { VideoBitesDisplay } from './video-bites-display';
+import type { VideoTeaser } from '../../types/video-processing';
+
+const bites: VideoTeaser[] = [
+  {
+    url: 'https://stream.example.com/clip1.mp4',
+    title: 'Product Demo',
+    thumbnail_url: 'https://cdn.example.com/thumb1.jpg',
+    published: true,
+    created_at: '2024-06-01T12:00:00Z',
+  },
+];
+
+export function HighlightsSection() {
+  return (
+    <VideoBitesDisplay
+      bites={bites}
+      title="Product Highlights"
+      filterPublished={true}
+      showTitle={true}
+    />
+  );
+}
+```

package/src/components/features/.video-clips-section.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 81400380536975a05d6ee9dc0f9ea30f -->
+Reusable wrapper component around `AIEnrichSection` that provides a standardized UI for triggering and managing video clips extraction from uploaded media.
+
+## Key Components
+
+### `VideoClipsSection`
+A pre-configured `AIEnrichSection` wrapper that handles the video clips extraction step for `CustomerInterview` and `ProductRelease` entities. Automatically toggles the button label between `"Generate Clips"` and `"Regenerate Clips"` based on whether a result already exists.
+
+### `VideoClipsSectionProps`
+Full interface for controlling extraction state, UI labels, cancel behavior, and required field validation display.
+
+## Usage Example
+
+```typescript
+import { VideoClipsSection } from './video-clips-section';
+
+<VideoClipsSection
+  onExtractClips={handleExtract}
+  isProcessing={isLoading}
+  canEnrich={!!uploadedVideo}
+  requiredFields={[{ label: 'Video', isMet: !!uploadedVideo }]}
+  status={extractionStatus}
+  statusMessage="Clips extracted successfully"
+  hasResult={clips.length > 0}
+  showCancel={true}
+  onCancel={handleCancel}
+  isCancelling={isCancelling}
+/>
+```
+
+## Props Summary
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onExtractClips` | `() => void` | — | Triggers extraction |
+| `isProcessing` | `boolean` | — | Shows loading state |
+| `canEnrich` | `boolean` | — | Enables the button |
+| `hasResult` | `boolean` | `false` | Switches label to "Regenerate" |
+| `disabledMessage` | `string` | `"Upload a video first"` | Tooltip when disabled |
+| `loadingLabel` | `string` | `"Extracting clips..."` | In-progress button label |
+| `showCancel` | `boolean` | `true` | Shows cancel option |

package/src/components/features/.video-ratio-tabs.md

@@ -0,0 +1,56 @@
+<!-- source-hash: d2815a723188c45f4c5d2910a19ffd76 -->
+Aspect-ratio tab and grouping primitives for video grids, used by `VideoBitesDisplay` and admin editors to render portrait, square, and landscape clips in cohesive tabbed groups.
+
+## Key Components
+
+### Types & Interfaces
+- **`VizardAspectRatio`** — Union type for Vizard clip ratios: `'9:16' | '16:9' | '1:1'`
+- **`VideoTeaserWithRatio`** — Extends `VideoTeaser` with `aspect_ratio`, `confidence`, `viral_reason`, and timing metadata
+- **`RatioCategory`** — Grid grouping label: `'portrait' | 'square' | 'landscape'`
+
+### Constants
+- **`RATIO_GRID_CLASS`** — Tailwind grid classes for admin editor views (narrower columns)
+- **`RATIO_DISPLAY_GRID_CLASS`** — Tailwind grid classes for public display pages (wider columns)
+
+### Components
+- **`RatioTabs`** — Tab wrapper that only renders tabs with content; auto-collapses to flat render when only one ratio group is populated; uses `forceMount` to prevent scroll-jump on tab switch
+
+### Utilities
+- **`detectAspectRatio(ratioString?, width?, height?)`** — Resolves a `VizardAspectRatio` from a string, falling back to dimension inference, defaulting to `'9:16'`
+- **`ratioToCategory(ratio)`** — Maps `VizardAspectRatio` → `RatioCategory`
+- **`groupByAspectRatio(items, getAspectRatio)`** — Buckets any item array into `{ portrait, square, landscape, hasMultiple }`
+
+## Usage Example
+
+```typescript
+import {
+  RatioTabs,
+  groupByAspectRatio,
+  detectAspectRatio,
+  ratioToCategory,
+  RATIO_DISPLAY_GRID_CLASS,
+} from './video-ratio-tabs';
+
+// Group clips by detected aspect ratio
+const { portrait, square, landscape, hasMultiple } = groupByAspectRatio(
+  clips,
+  (clip) => detectAspectRatio(clip.aspect_ratio, clip.width, clip.height),
+);
+
+// Render with tabbed UI
+<RatioTabs
+  groups={{
+    portrait: {
+      count: portrait.length,
+      render: () => (
+        <div className={RATIO_DISPLAY_GRID_CLASS.portrait}>
+          {portrait.map((c) => <ClipCard key={c.id} clip={c} />)}
+        </div>
+      ),
+    },
+    square: { count: square.length, render: () => <SquareGrid items={square} /> },
+    landscape: { count: landscape.length, render: () => <LandscapeGrid items={landscape} /> },
+  }}
+  defaultTab="portrait"
+/>
+```

package/src/components/features/.video-source-selector.md

@@ -0,0 +1,60 @@
+<!-- source-hash: 1995e98822c487bba791ce8689ae2447 -->
+Unified toggle component for selecting between a YouTube URL input and a direct video file upload, managing upload state, progress, and preview rendering internally.
+
+## Key Components
+
+### Exports
+- **`VideoSourceSelector`** — Main React component (default + named export)
+- **`VideoSourceType`** — Union type: `'youtube' | 'uploaded'`
+- **`VideoSourceSelectorProps`** — Full prop interface for the component
+
+### Internal State
+| State | Purpose |
+|---|---|
+| `isUploading` | Tracks active upload operation |
+| `uploadProgress` | Numeric progress (0–100) |
+| `uploadMessage` | Status message during upload |
+| `uploadError` | Error string if upload fails |
+
+### Key Handlers
+- **`handleUploadClick`** — Programmatically triggers a hidden `<input type="file">`, invokes `onUploadVideo`, and manages progress callbacks
+- **`handleDeleteVideo`** — Clears the uploaded video URL via `onMainVideoUrlChange('')`
+
+## Usage Example
+
+```typescript
+import { VideoSourceSelector, VideoSourceType } from './video-source-selector';
+
+function MyForm() {
+  const [sourceType, setSourceType] = useState<VideoSourceType>('youtube');
+  const [youtubeUrl, setYoutubeUrl] = useState('');
+  const [videoUrl, setVideoUrl] = useState('');
+
+  const handleUpload = async (file: File, onProgress?: (p: number) => void) => {
+    const formData = new FormData();
+    formData.append('file', file);
+    // ... upload logic with progress callbacks
+    return 'https://cdn.example.com/video.mp4';
+  };
+
+  return (
+    <VideoSourceSelector
+      videoSourceType={sourceType}
+      onVideoSourceTypeChange={setSourceType}
+      youtubeUrl={youtubeUrl}
+      onYoutubeUrlChange={setYoutubeUrl}
+      mainVideoUrl={videoUrl}
+      onMainVideoUrlChange={setVideoUrl}
+      onUploadVideo={handleUpload}
+      isAIGenerated={false}
+      title="Course Video"
+    />
+  );
+}
+```
+
+## Notes
+
+- Switching between `youtube` and `uploaded` tabs **preserves both values** — no data is cleared on toggle
+- Accepts optional `VideoPreviewComponent` and `UploadProgressComponent` for custom rendering; falls back to built-in implementations if omitted
+- All text labels and placeholders are customizable via props for reuse across different contexts

package/src/components/features/.video.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 9e88b910bdaffc13eb668740a6d415f4 -->
+Renders video content from YouTube URLs, bare video IDs, or file sources (HLS/MP4) with smart auto-detection and three layout modes. Consolidates the previous `<VideoPlayer>` and `<YouTubeEmbed>` primitives into a single component.
+
+## Key Components
+
+- **`Video`** — Primary export. Discriminates on `kind` prop (`'youtube'` | `'file'` | `'auto'`) to route to the correct player branch, then wraps in the chosen layout
+- **`extractYouTubeId`** — Exported utility that parses any YouTube URL shape or bare 11-char video ID into a raw video ID. Uses strict URL parsing + anchored regex (ReDoS-safe)
+- **`VideoProps`** — Discriminated union type (`VideoFileProps | VideoYouTubeProps | VideoAutoProps`)
+- **`VideoLayout`** — `'centered'` | `'fill'` | `'native'`
+- **`resolveKind`** (internal) — URL classifier that maps a URL to `'youtube'` or `'file'`
+- **`YouTubeFacade`** (internal) — Lite-YouTube poster + click-to-iframe embed
+- **`FilePlayer`** (internal) — `<MuxPlayer>` wrapper handling HLS, MP4, captions, and Mux Data
+
+## Usage Example
+
+```typescript
+// Auto-detect source from URL (recommended)
+<Video url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" layout="centered" />
+
+// Bare YouTube ID
+<Video url="dQw4w9WgXcQ" layout="native" priority />
+
+// HLS or MP4 file with captions
+<Video
+  kind="file"
+  url="https://cdn.example.com/video.m3u8"
+  captionsUrl="https://cdn.example.com/captions.vtt"
+  layout="fill"
+  muted
+/>
+
+// Marketing embed — minimal YouTube controls
+<Video
+  kind="youtube"
+  url="https://youtu.be/dQw4w9WgXcQ"
+  layout="centered"
+  minimalControls
+  title="Product demo"
+/>
+
+// Validate a URL without rendering
+import { extractYouTubeId } from './video';
+const id = extractYouTubeId('https://youtu.be/dQw4w9WgXcQ'); // → "dQw4w9WgXcQ"
+```

package/src/components/features/.waitlist-form.md

@@ -0,0 +1,60 @@
+<!-- source-hash: 6dd94b5db8fe43eb78a9a8032c387c0e -->
+A platform-agnostic waitlist registration form component for OpenFrame/Flamingo, handling email capture, optional phone input with country detection, SMS consent, and submission state management.
+
+## Key Components
+
+### `WaitlistFormProps`
+Configuration interface with the following notable props:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onRegister` | `(email, phone?) => Promise<void>` | Required submission handler; must throw on failure |
+| `geoApiUrl` | `string \| null` | Geo-detection endpoint for auto-selecting country code (default: `"/api/geo"`) |
+| `isSubmitting` | `boolean` | Controls loading state on the submit button |
+| `isSuccess` | `boolean` | Switches button label to `successLabel` |
+| `defaultEmail` / `defaultPhone` | `string` | Pre-filled values from auth context or user profile |
+| `termsOfServiceUrl` / `privacyPolicyUrl` | `string` | Links rendered in SMS consent copy |
+
+### `WaitlistForm`
+The exported form component. Key internal behaviors:
+
+- **Hydration-safe skeleton** — renders animated placeholder blocks until client-side mount
+- **Geo-detection** — fetches `geoApiUrl` on mount to pre-select the user's country code via `libphonenumber-js`
+- **Generic email warning** — surfaces a warning (not a block) when a personal domain is detected
+- **SMS consent gate** — requires checkbox agreement before submitting a phone number
+- **E.164 formatting** — converts raw phone input via `formatPhoneE164` before calling `onRegister`
+- **Enter key support** — `handleKeyDown` triggers submission from any field
+
+## Usage Example
+
+```typescript
+import { WaitlistForm } from './waitlist-form'
+
+function WaitlistPage() {
+  const [isSubmitting, setIsSubmitting] = useState(false)
+  const [isSuccess, setIsSuccess] = useState(false)
+
+  const handleRegister = async (email: string, phone?: string) => {
+    setIsSubmitting(true)
+    try {
+      await api.joinWaitlist({ email, phone })
+      setIsSuccess(true)
+    } finally {
+      setIsSubmitting(false)
+    }
+  }
+
+  return (
+    <WaitlistForm
+      onRegister={handleRegister}
+      isSubmitting={isSubmitting}
+      isSuccess={isSuccess}
+      geoApiUrl="/api/geo"
+      termsOfServiceUrl="/legal/terms"
+      privacyPolicyUrl="/legal/privacy"
+    />
+  )
+}
+```
+
+> **Note:** `onRegister` is responsible for its own error toasts. The form handles only email-empty and consent-missing validation client-side.

package/src/components/features/ai-enrich/.AIEnrichButton.md

@@ -1,45 +1,48 @@
-<!-- source-hash: 85d234020490e54e3251b26b200e61b1 -->
-A specialized button component that provides AI-powered content enrichment functionality with loading states, customizable variants, and a sparkles icon.
+<!-- source-hash: 553f8dbdfb9763d4ad797668077fd3a4 -->
+A reusable client-side button component that triggers AI enrichment actions, featuring a sparkles icon, loading state, and configurable size/variant options.
 
 ## Key Components
 
-- **`AIEnrichButton`** - Main React functional component that renders an AI enrichment button
-- **`AIEnrichButtonProps`** - TypeScript interface defining component props including onClick handler, loading states, and styling options
-- **`sizeMap`** - Maps component size props (`sm`, `md`, `lg`) to Button component sizes
-- **`variantMap`** - Maps component variants (`primary`, `secondary`, `outline`) to Button component variants
+### `AIEnrichButtonProps`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onClick` | `() => void` | — | Handler called on button click |
+| `disabled` | `boolean` | `false` | Disables the button |
+| `loading` | `boolean` | `false` | Shows loading state and swaps label |
+| `label` | `string` | `'AI Enrich'` | Default button text |
+| `loadingLabel` | `string` | `'Enriching...'` | Text shown during loading |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
+| `variant` | `'primary' \| 'secondary' \| 'outline'` | `'outline'` | Visual style |
+| `className` | `string` | — | Additional CSS classes |
+
+### `AIEnrichButton`
+The exported functional component. Internally maps the `size` and `variant` props to the underlying `Button` component's accepted values, and hides the `SparklesIcon` while loading.
 
 ## Usage Example
 
 ```typescript
 import { AIEnrichButton } from './components/AIEnrichButton'
 
-function ContentEditor() {
-  const [isEnriching, setIsEnriching] = useState(false)
+function TicketForm() {
+  const [enriching, setEnriching] = React.useState(false)
 
   const handleEnrich = async () => {
-    setIsEnriching(true)
-    try {
-      // Call AI enrichment API
-      await enrichContent()
-    } finally {
-      setIsEnriching(false)
-    }
+    setEnriching(true)
+    await enrichTicketWithAI()
+    setEnriching(false)
   }
 
   return (
-    <div>
-      <AIEnrichButton
-        onClick={handleEnrich}
-        loading={isEnriching}
-        label="Enhance with AI"
-        loadingLabel="Processing..."
-        variant="primary"
-        size="md"
-        className="my-4"
-      />
-    </div>
+    <AIEnrichButton
+      onClick={handleEnrich}
+      loading={enriching}
+      size="sm"
+      variant="primary"
+      label="Enrich Ticket"
+      loadingLabel="Analyzing..."
+    />
   )
 }
 ```
 
-The component automatically handles loading states, disables interaction during processing, and displays appropriate labels. The sparkles icon provides visual feedback for AI functionality and is hidden during loading.
+> The button automatically disables itself during loading (`disabled || loading`), preventing duplicate submissions while Mingo AI processes the enrichment request.

package/src/components/features/ai-enrich/.AIEnrichSection.md

@@ -1,51 +1,55 @@
-<!-- source-hash: 5552d95934cddb1d296daa3277e703de -->
-A React component that provides a comprehensive UI section for AI-powered data enrichment functionality. It handles the complete enrichment workflow including trigger button, status display, confidence metrics, warnings, and required field validation.
+<!-- source-hash: 3297a26442c5b70d119e373c4687b748 -->
+Reusable AI enrichment panel component that renders a full-featured UI section for triggering AI-powered data enrichment, displaying status feedback, confidence scores, warnings, and optional custom instructions.
 
 ## Key Components
 
-- **AIEnrichSection**: Main component that orchestrates the AI enrichment interface
-- **ConfidenceField**: Interface for displaying confidence scores of enriched fields
-- **AIRequiredField**: Interface for tracking required fields and their completion status
-- **AIEnrichSectionProps**: Comprehensive props interface supporting all enrichment states
+### Interfaces
+
+| Interface | Purpose |
+|-----------|---------|
+| `ConfidenceField` | Defines a field with an optional confidence score for display |
+| `AIRequiredField` | Describes a required form field, its fill state, and display label |
+| `AIEnrichSectionProps` | Full prop contract for the `AIEnrichSection` component |
+
+### Component: `AIEnrichSection`
+
+The main exported component. Renders a card-style panel with:
+
+- **Header** — Icon (defaults to `SparklesIcon`), title, and optional description
+- **Custom Instructions** (opt-in) — Controlled `<Textarea>` for user-provided AI focus hints, passed upstream to Claude via `buildEditorFocusBlock()`
+- **Action Buttons** — `AIEnrichButton` (primary) and optional cancel button during loading
+- **Disabled State** — Shows `disabledMessage` with badge-styled list of unfilled required fields
+- **Loading State** — Spinner with live `statusMessage`
+- **Results Section** — Success/error status indicator, confidence badge, `AIWarningsSection`, custom `children`, and a clear button
 
 ## Usage Example
 
 ```typescript
-import { AIEnrichSection } from './AIEnrichSection'
-
-function FormWithAIEnrichment() {
-  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle')
-  const [warnings, setWarnings] = useState<string[]>([])
-  
-  const requiredFields = [
-    { key: 'email', label: 'Email', isFilled: !!formData.email },
-    { key: 'company', label: 'Company', isFilled: !!formData.company }
-  ]
-
-  const confidenceFields = [
-    { label: 'Industry', key: 'industry', confidence: 85 },
-    { label: 'Company Size', key: 'size', confidence: 92 }
-  ]
-
-  return (
-    <AIEnrichSection
-      onEnrich={handleAIEnrichment}
-      loading={status === 'loading'}
-      status={status}
-      statusMessage="Analyzing company data..."
-      overallConfidence={88}
-      warnings={warnings}
-      requiredFields={requiredFields}
-      confidenceFields={confidenceFields}
-      onClear={() => setStatus('idle')}
-      canEnrich={requiredFields.every(f => f.isFilled)}
-    >
-      <div className="text-sm">
-        Created 3 new tags based on industry analysis
-      </div>
-    </AIEnrichSection>
-  )
-}
+<AIEnrichSection
+  title="Enrich Asset"
+  description="Use AI to auto-fill missing asset details."
+  onEnrich={handleEnrich}
+  loading={isLoading}
+  canEnrich={hasRequiredFields}
+  status={enrichStatus}
+  statusMessage="Analyzing asset data..."
+  overallConfidence={87}
+  warnings={enrichWarnings}
+  requiredFields={[
+    { key: 'version', label: 'Version', isFilled: !!formValues.version },
+    { key: 'vendor', label: 'Vendor', isFilled: !!formValues.vendor },
+  ]}
+  showCustomInstructions
+  customInstructions={instructions}
+  onCustomInstructionsChange={setInstructions}
+  onClear={handleClear}
+  showCancel
+  onCancel={handleCancel}
+/>
 ```
 
-The component automatically handles disabled states when required fields are missing, displays confidence badges for enriched data, and provides a clean interface for managing the entire AI enrichment process.
+## Notes
+
+- Supports `'default'` and `'compact'` layout variants via the `variant` prop
+- `customInstructions` is fully controlled — the parent owns the string value
+- `requiredFields` drives both `canEnrich` gating and the unfilled-fields badge display

package/src/components/features/board/.board-column-header.md

@@ -0,0 +1,38 @@
+<!-- source-hash: 1ad6ce49d76bfa9f7bbe6737c01b2305 -->
+Renders the header for a Kanban board column, supporting both expanded and collapsed states with ticket status display, count, and optional ticket creation.
+
+## Key Components
+
+### `BoardColumnHeaderProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `column` | `BoardColumnDef` | Column definition including id, label, color, and tickets |
+| `collapsed` | `boolean` | Controls collapsed/expanded display mode |
+| `onToggleCollapse` | `() => void` | Callback to toggle column collapse state |
+| `onAddTicket` | `() => void` (optional) | Callback to trigger ticket creation |
+
+### `BoardColumnHeader`
+Client component that renders two distinct layouts:
+- **Collapsed:** Vertical layout with expand icon, rotated status tag, and ticket count
+- **Expanded:** Horizontal layout with status tag, count, collapse button, and optional add-ticket button
+
+Uses `getTicketStatusConfig` to determine whether to use a built-in status color or a custom column color for the `TicketStatusTag`.
+
+## Usage Example
+
+```typescript
+import { BoardColumnHeader } from './board-column-header'
+
+<BoardColumnHeader
+  column={{
+    id: 'in-progress',
+    label: 'In Progress',
+    color: '#FFC008',
+    tickets: [...],
+    total: 12,
+  }}
+  collapsed={false}
+  onToggleCollapse={() => setCollapsed(prev => !prev)}
+  onAddTicket={() => openCreateTicketModal('in-progress')}
+/>
+```

package/src/components/features/board/.board-column.md

@@ -0,0 +1,43 @@
+<!-- source-hash: 1bf9b2d5d2d477b1115c900de71defaa -->
+Renders a single kanban board column with drag-and-drop support, collapsible layout, infinite scroll via IntersectionObserver, and ticket card rendering.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `BoardColumn` | Component | Main column shell handling collapsed/expanded state, border joining, and color tinting |
+| `BoardColumnProps` | Interface | Public API for the column component |
+| `ColumnBody` | Internal Component | Scrollable droppable zone with `SortableContext`, infinite scroll sentinel, and loading states |
+| `SkeletonStack` | Internal Component | Renders `n` skeleton placeholders during initial load |
+| `EmptyState` | Internal Component | Illustrated empty state shown when a column has no tickets |
+
+## Usage Example
+
+```typescript
+<BoardColumn
+  column={{
+    id: 'open',
+    label: 'Open',
+    color: '#3B82F6',
+    tickets: myTickets,
+    hasMore: true,
+    isLoading: false,
+    isLoadingMore: false,
+  }}
+  collapsed={false}
+  onToggleCollapse={() => setCollapsed(c => !c)}
+  onAddTicket={(columnId) => openNewTicketModal(columnId)}
+  getTicketHref={(ticketId) => `/tickets/${ticketId}`}
+  renderAssignSlot={(ticket) => <AssigneePicker ticket={ticket} />}
+  onLoadMore={(columnId) => fetchNextPage(columnId)}
+  joinLeft={false}
+  joinRight={true}
+/>
+```
+
+## Notes
+
+- **Drag-and-drop**: Uses `@dnd-kit/core` (`useDroppable`) and `@dnd-kit/sortable` (`SortableContext`) — drop target is disabled when `column.dropDisabled` is set.
+- **Infinite scroll**: An `IntersectionObserver` watches a 1px sentinel div at the bottom of the scroll container; `onLoadMore` fires when it enters the viewport. Scroll is paused while `isLoadingMore` is true.
+- **Collapsed state**: When `collapsed=true`, the column shrinks to `w-14` and hides the body; the header remains visible.
+- **Joined borders**: `joinLeft`/`joinRight` props remove border radii and borders on adjacent edges for seamless multi-column layouts.

package/src/components/features/board/.board.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 266e1c3c423b749f9d7def8ff717188e -->
+A drag-and-drop Kanban board component that manages ticket movement across columns using `@dnd-kit/core`, with support for column collapsing, horizontal scrolling, and constrained drop rules.
+
+## Key Components
+
+| Export / Symbol | Description |
+|---|---|
+| `Board` | Main board component rendering all columns with full DnD orchestration |
+| `BoardProps` | Props interface defining columns, event handlers, and customization options |
+| `collisionDetection` | Custom collision strategy: prefers ticket hits, falls back to column, then closest corners |
+| `handleDragStart` | Records drag origin (ticket + source column) and sets overlay state |
+| `handleDragOver` | Optimistically moves tickets across columns respecting `dropDisabled` and `allowedFromColumns` |
+| `handleDragEnd` | Commits the move by calling `onChange` with positional context (`afterTicketId`, `beforeTicketId`), or rolls back |
+| `handleDragCancel` | Reverts local state to the last server-provided `columns` prop |
+| `locate` | Helper to find a ticket's column, index, and reference by ID |
+| `findIndexInColumn` | Helper returning a ticket's index within a specific column |
+
+## Usage Example
+
+```typescript
+<Board
+  columns={[
+    {
+      id: 'open',
+      label: 'Open',
+      tickets: [{ id: 'T-1', title: 'Fix login bug' }],
+    },
+    {
+      id: 'in-progress',
+      label: 'In Progress',
+      tickets: [],
+      allowedFromColumns: ['open'],
+    },
+    {
+      id: 'done',
+      label: 'Done',
+      tickets: [],
+      dropDisabled: true,
+    },
+  ]}
+  onChange={({ ticketId, fromColumnId, toColumnId, afterTicketId }) => {
+    api.moveTicket({ ticketId, toColumnId, afterTicketId })
+  }}
+  onLoadMore={(columnId) => fetchMore(columnId)}
+  getTicketHref={(ticketId) => `/tickets/${ticketId}`}
+  renderAssignSlot={(ticket) => <AssigneeAvatar ticket={ticket} />}
+  collapseStorageKey="board-collapse-state"
+/>
+```
+
+> **Drop rules:** Set `dropDisabled: true` on a column to block all inbound drops. Use `allowedFromColumns: ['open']` to restrict which source columns can feed into a target — dragging back to the origin column is always permitted regardless of these rules.

package/src/components/features/board/.color-utils.md

@@ -0,0 +1,26 @@
+<!-- source-hash: 908a5d80c6498d71475f70d268086189 -->
+Computes a pre-blended background tint by mixing a given hex color at 10% opacity over a fixed dark background (`#161616`), returning the resulting opaque hex color.
+
+## Key Components
+
+- **`tintOnDark(hex: string): string`** — Takes a hex color string (e.g. `#FFC008`), blends it at 10% over `#161616`, and returns the resulting opaque hex color.
+
+## Usage Example
+
+```typescript
+import { tintOnDark } from './color-utils'
+
+const tinted = tintOnDark('#FFC008')
+// Returns the pre-blended hex, e.g. "#211e13"
+// Useful for subtle colored backgrounds on dark UIs
+
+const redTint = tintOnDark('#FF0000')
+// Blends red at 10% over #161616 → "#281616"
+```
+
+## Notes
+
+- The background is hardcoded to `#161616` (decimal `22`), matching Flamingo's dark theme base.
+- Blend formula per channel: `round(0.1 * foreground + 0.9 * 22)`
+- Input hex may include or omit the leading `#`.
+- Returns a fully opaque hex string — no alpha channel — making it safe for any CSS `background-color` context.