@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/features/.select-button.md

@@ -1,54 +1,43 @@
-<!-- source-hash: e190543dcb8ddd78af0a45f332d3eefe -->
-A selectable button component that supports icons, images, tags, and selected/disabled states, designed for use in option-selection UIs such as lists or grids.
+<!-- source-hash: 74eb7379842105cc594b84564c93e6f2 -->
+A selectable button component built with `React.forwardRef` that supports rich content including icons, images, tags, and descriptions, with distinct selected/unselected visual states.
 
 ## Key Components
 
 ### `SelectButtonProps`
 | Prop | Type | Description |
 |------|------|-------------|
-| `title` | `string` | Primary label text (required) |
-| `description` | `string` | Optional subtitle, visible on `md+` screens |
-| `selected` | `boolean` | Highlights the button with accent styling and shows a check icon |
-| `disabled` | `boolean` | Disables interaction and reduces opacity |
+| `title` | `string` | Required button label |
+| `description` | `string` | Optional subtitle (visible on `md+` breakpoints) |
+| `selected` | `boolean` | Toggles active/highlighted state |
+| `disabled` | `boolean` | Disables interaction and dims the button |
 | `icon` | `React.ReactNode` | Optional leading icon |
 | `image` | `{ src, alt }` | Optional thumbnail image |
-| `tag` | `string` | Optional badge label rendered via `Tag` |
-| `tagVariant` | `TagProps['variant']` | Controls tag style, defaults to `"outline"` |
+| `tag` | `string` | Optional `Tag` badge label |
+| `tagVariant` | `TagProps['variant']` | Badge variant, defaults to `"outline"` |
 | `onClick` | `() => void` | Click handler |
-| `className` | `string` | Additional CSS classes |
+| `className` | `string` | Additional CSS overrides |
 
 ### `SelectButton`
-A `forwardRef` button with `role="option"` and `aria-selected`, suitable for accessible listbox patterns. Applies ODS design tokens for color, spacing, and focus states.
+A forwarded-ref `<button>` with `role="option"` and `aria-selected`, suitable for use inside listbox-style selection UIs. Renders a `CheckCircleIcon` when selected.
 
 ## Usage Example
 
 ```typescript
 import { SelectButton } from './select-button'
-import { ServerIcon } from '../icons-v2-generated/...'
+import { ServerIcon } from '../icons'
 
-// Basic selectable option
 <SelectButton
-  title="Standard Plan"
-  description="Up to 10 devices"
-  selected={selectedPlan === 'standard'}
-  onClick={() => setSelectedPlan('standard')}
-/>
-
-// With icon and tag
-<SelectButton
-  title="Enterprise Plan"
-  description="Unlimited devices"
+  title="Production Server"
+  description="us-east-1 · 4 vCPU"
   icon={<ServerIcon />}
-  tag="Popular"
+  image={{ src: "/logos/aws.png", alt: "AWS" }}
+  tag="Recommended"
   tagVariant="solid"
-  selected={selectedPlan === 'enterprise'}
-  onClick={() => setSelectedPlan('enterprise')}
+  selected={selectedId === 'prod'}
+  onClick={() => setSelectedId('prod')}
 />
+```
 
-// With thumbnail image
-<SelectButton
-  title="Acme Corp"
-  image={{ src: '/logos/acme.png', alt: 'Acme Corp logo' }}
-  selected={true}
-/>
-```
+> **Accessibility note:** Wrap multiple `SelectButton` instances in a container with `role="listbox"` to form a complete ARIA listbox pattern.
+
+**Source:** [`select-button.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/select-button.tsx)

package/src/components/features/.seo-editor-preview.md

@@ -1,51 +1,64 @@
-<!-- source-hash: e691658139dcf0e352222348aeae0a32 -->
-Self-contained React component that combines SEO metadata editing fields with a live social media (Open Graph) card preview, used across blog posts, case studies, and product releases in the Flamingo/OpenFrame platform.
+<!-- source-hash: d142e47d8c6e07ffbb045420607beaf0 -->
+Renders a combined SEO metadata editor and live social media preview card, providing inline character-count validation and AI confidence indicators for SEO title, description, and keywords fields, plus OG image upload/display.
 
 ## Key Components
 
 ### `SEOEditorPreview` (default export)
-The main component rendering a two-panel layout:
-- **Editor fields** — SEO title, description, keywords, and OG image upload
-- **Live OG card preview** — real-time social media card simulation
 
-### `SEOEditorPreviewProps` interface
+A client-side React component that combines three responsibilities:
+
+- **SEO field editing** — `Input`/`Textarea` fields for `seoTitle`, `seoDescription`, and `seoKeywords`, each with character-count tracking and length-limit warnings sourced from `SEO_TITLE_MAX_LENGTH` and `SEO_DESCRIPTION_MAX_LENGTH` constants.
+- **OG image management** — upload via `onOgImageUpload`, display with hover-to-replace/remove controls, and automatic fallback to `featuredImage` when no OG image is set.
+- **Live social preview** — a "Social Media Preview" card reflecting display fallbacks (`seoTitle → title`, `seoDescription → summary`, `ogImageUrl → featuredImage`).
+
+### `SEOEditorPreviewProps`
+
 | Prop | Type | Description |
-|------|------|-------------|
+|---|---|---|
 | `seoTitle` / `seoDescription` / `seoKeywords` / `ogImageUrl` | `string` | Controlled SEO field values |
 | `title` / `summary` / `featuredImage` | `string` | Auto-populate fallback sources |
-| `onSeo*Change` / `onOgImageUrlChange` | `(value: string) => void` | Change handlers per field |
-| `onOgImageUpload` | `(file: File) => Promise<string>` | Optional parent-provided upload handler |
-| `aiConfidenceSeo*` | `number` (optional) | AI confidence scores shown via `ConfidenceBadge` |
-| `domain` | `string` | Preview domain label (default: `'openmsp.ai'`) |
-| `disabled` | `boolean` | Disables all inputs |
-
-### Internal State
-- `imageError` — falls back to placeholder when OG image fails to load
-- `isUploading` — shows `Loader2` spinner during file upload
-- `fileInputRef` — ref to hidden `<input type="file">` for programmatic click
+| `onSeo*Change` / `onOgImageUrlChange` | `(value: string) => void` | Controlled change handlers |
+| `onOgImageUpload` | `(file: File) => Promise<string>` | Parent-supplied upload handler |
+| `aiConfidenceSeo*` | `number` (optional) | Triggers `AIGeneratedBadge` + `ConfidenceBadge` |
+| `domain` | `string` | Preview domain (default: `'openmsp.ai'`) |
+| `disabled` | `boolean` | Disables all interactive controls |
 
 ## Usage Example
 
 ```typescript
-<SEOEditorPreview
-  seoTitle={post.seoTitle}
-  seoDescription={post.seoDescription}
-  seoKeywords={post.seoKeywords}
-  ogImageUrl={post.ogImageUrl}
-  title={post.title}
-  summary={post.summary}
-  featuredImage={post.featuredImage}
-  onSeoTitleChange={(v) => updatePost({ seoTitle: v })}
-  onSeoDescriptionChange={(v) => updatePost({ seoDescription: v })}
-  onSeoKeywordsChange={(v) => updatePost({ seoKeywords: v })}
-  onOgImageUrlChange={(v) => updatePost({ ogImageUrl: v })}
-  onOgImageUpload={async (file) => {
-    const { url } = await uploadAsset(file);
+import { SEOEditorPreview } from './seo-editor-preview';
+
+function ArticleForm() {
+  const [seoTitle, setSeoTitle] = useState('');
+  const [seoDescription, setSeoDescription] = useState('');
+
+  const handleUpload = async (file: File): Promise<string> => {
+    const formData = new FormData();
+    formData.append('file', file);
+    const res = await fetch('/api/upload', { method: 'POST', body: formData });
+    const { url } = await res.json();
     return url;
-  }}
-  aiConfidenceSeoTitle={0.92}
-  domain="flamingo.run"
-/>
+  };
+
+  return (
+    <SEOEditorPreview
+      seoTitle={seoTitle}
+      seoDescription={seoDescription}
+      seoKeywords=""
+      ogImageUrl=""
+      title="Getting Started with OpenFrame"
+      summary="A guide to the unified MSP platform."
+      featuredImage="/images/hero.png"
+      onSeoTitleChange={setSeoTitle}
+      onSeoDescriptionChange={setSeoDescription}
+      onSeoKeywordsChange={() => {}}
+      onOgImageUrlChange={() => {}}
+      onOgImageUpload={handleUpload}
+      aiConfidenceSeoTitle={0.87}
+      domain="flamingo.run"
+    />
+  );
+}
 ```
 
-> All SEO fields accept empty strings (never `undefined`). When a field is empty, the component automatically falls back to `title`, `summary`, or `featuredImage` props, showing an "Auto-populated" hint label beneath the input.
+> **Source:** [`seo-editor-preview.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/seo-editor-preview.tsx)

package/src/components/features/.social-links-manager.md

@@ -1,25 +1,31 @@
-<!-- source-hash: d38fe303fe5fb74d67b5d888ec7ca267 -->
-A client-side React component for managing a dynamic list of social media profile links, supporting add, update, and remove operations with platform-aware icons.
+<!-- source-hash: 590a86864f3606344569842b53130fe9 -->
+A client-side React component for managing a dynamic list of social media profile links, supporting platform selection, URL input, and visibility controls.
 
 ## Key Components
 
-### Interfaces
+### Exported Interfaces
 
-| Interface | Description |
-|---|---|
-| `SocialLink` | Represents a single link entry with `platform`, `url`, and optional `username` |
-| `SocialPlatform` | Describes a platform definition sourced from dynamic data (e.g., database), including `icon_name`, `url_pattern`, and `placeholder` |
-| `SocialLinksManagerProps` | Component props: `links`, `onChange` callback, optional `platforms` array, and optional `className` |
+- **`SocialLink`** — Represents a single social link entry with `platform`, `url`, optional `username`, and `visibility` (`'external' | 'internal'`).
+- **`SocialPlatform`** — Describes a platform definition (typically fetched from a database) with fields like `id`, `name`, `display_name`, `icon_name`, `url_pattern`, `placeholder`, and `enabled`.
 
-### `SocialLinksManager`
+### Component
 
-The primary exported component. Renders a list of social link rows, each with:
-- A platform icon (resolved via `iconMap` using `icon_name` from `SocialPlatform` or falls back to `platform` string)
-- A `Select` dropdown for choosing the platform
-- An `Input` for the profile URL
-- A delete button (`Trash2`) to remove the entry
+- **`SocialLinksManager`** — Main component accepting:
+  - `links` — Current array of `SocialLink` entries
+  - `onChange` — Callback invoked with the updated links array on any mutation
+  - `platforms` — Optional array of `SocialPlatform` definitions (defaults to empty; pass dynamic data from your API)
+  - `className` — Optional CSS class override
 
-Supported icon keys in `iconMap`: `linkedin`, `github`, `twitter`, `reddit`, `slack`, `whatsapp`, `website`, `youtube`, `instagram`, `facebook`, `discord`, `telegram`, `tiktok`.
+### Internal Helpers
+
+- **`addLink`** — Appends a new empty link defaulting to the first available platform.
+- **`removeLink(index)`** — Removes the link at the given index.
+- **`updateLink(index, field, value)`** — Mutates a specific field on a link entry immutably.
+- **`getIcon(link, platform?)`** — Resolves the correct icon component from `iconMap` using `platform.icon_name` or `link.platform` as a fallback.
+
+### `iconMap`
+
+A static mapping from platform key strings to icon components, covering: `linkedin`, `github`, `twitter`, `reddit`, `slack`, `whatsapp`, `website`, `youtube`, `instagram`, `facebook`, `discord`, `telegram`, `tiktok`, `email`/`mail`.
 
 ## Usage Example
 
@@ -27,8 +33,22 @@ Supported icon keys in `iconMap`: `linkedin`, `github`, `twitter`, `reddit`, `sl
 import { SocialLinksManager, SocialLink, SocialPlatform } from './social-links-manager';
 
 const platforms: SocialPlatform[] = [
-  { id: '1', name: 'linkedin', display_name: 'LinkedIn', icon_name: 'linkedin', enabled: true, placeholder: 'https://linkedin.com/in/...' },
-  { id: '2', name: 'github', display_name: 'GitHub', icon_name: 'github', enabled: true, placeholder: 'https://github.com/...' },
+  {
+    id: '1',
+    name: 'linkedin',
+    display_name: 'LinkedIn',
+    icon_name: 'linkedin',
+    placeholder: 'https://linkedin.com/in/username',
+    enabled: true,
+  },
+  {
+    id: '2',
+    name: 'github',
+    display_name: 'GitHub',
+    icon_name: 'github',
+    placeholder: 'https://github.com/username',
+    enabled: true,
+  },
 ];
 
 function ProfileEditor() {
@@ -44,4 +64,6 @@ function ProfileEditor() {
 }
 ```
 
-> **Note:** `platforms` defaults to an empty array, so platform data should always be passed explicitly — typically fetched from your database to keep icon and URL patterns in sync.
+**Visibility note:** Links with `visibility: 'internal'` are intended for company-hub rendering only and should be filtered server-side before exposing to external consumers.
+
+**Source:** [`social-links-manager.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/social-links-manager.tsx)

package/src/components/features/.start-with-openframe-button.md

@@ -1,53 +1,51 @@
-<!-- source-hash: 12ec98968857443cbefad0230bd2d335 -->
-A client-side React button component that renders a branded "Start with OpenFrame" CTA button, supporting five visual modes with the OpenFrame logo icon and a "Beta" status badge.
+<!-- source-hash: e7990b46fb9187b4eebc186c31d83f16 -->
+A branded CTA button component for the OpenFrame platform, rendering the OpenFrame logo icon alongside customizable label text and a "Beta" status badge.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `StartWithOpenFrameButton` | `React.ForwardRefExoticComponent` | Main button component with OpenFrame branding |
-| `StartWithOpenFrameButtonProps` | `interface` | Extends `ButtonProps`, omitting `variant`, `size`, and `leftIcon` |
-
-### Props
+### `StartWithOpenFrameButtonProps`
+Extends `ButtonProps` (omitting `variant`, `size`, and `leftIcon`) with:
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `mode` | `'outline' \| 'yellow' \| 'pink' \| 'purple' \| 'cyan'` | `'outline'` | Visual color mode |
-| `buttonSize` | `'sm' \| 'md' \| 'lg'` | — | Maps to internal Button size tokens |
-| `loading` | `boolean` | `false` | Shows loading state, hides the OpenFrame icon |
-| `buttonBackgroundColor` | `string` | — | Custom background override (cyan mode only) |
-| `buttonTextColor` | `string` | — | Custom text color override (cyan mode only) |
-| `children` | `React.ReactNode` | `'Start Free Trial'` | Button label |
-
-### Mode Behavior
-
-| Mode | Variant | Background Token |
-|------|---------|-----------------|
-| `outline` | `outline` | Default outline style |
-| `yellow` | `accent` | `--ods-open-yellow-base` |
-| `pink` / `purple` | `accent` | `--ods-flamingo-pink-base` |
-| `cyan` | `accent` | `--ods-flamingo-cyan-base` |
+|---|---|---|---|
+| `children` | `React.ReactNode` | `'Start Free Trial'` | Button label text |
+| `mode` | `'outline' \| 'yellow' \| 'pink' \| 'purple' \| 'cyan'` | `'outline'` | Visual style theme |
+| `buttonSize` | `'sm' \| 'md' \| 'lg'` | — | Maps to internal Button size values |
+| `loading` | `boolean` | `false` | Shows loading state; hides logo icon |
+| `buttonBackgroundColor` | `string` | — | Custom background (cyan mode only) |
+| `buttonTextColor` | `string` | — | Custom text color (cyan mode only) |
+
+### `StartWithOpenFrameButton`
+A `React.forwardRef` component that:
+- Maps `mode` to `Button` variant (`outline` or `accent`) and ODS Tailwind classes
+- Adjusts `OpenFrameLogo` icon colors for contrast per mode
+- Injects a fixed `StatusBadge` ("Beta") as `rightIcon`
+- Supports inline style overrides for the `cyan` mode
 
 ## Usage Example
 
 ```typescript
 import { StartWithOpenFrameButton } from './start-with-openframe-button';
 
-// Default outline mode
-<StartWithOpenFrameButton onClick={() => router.push('/signup')} />
+// Default outline style
+<StartWithOpenFrameButton />
 
-// Yellow accent, large size
+// Yellow accent variant with large size
 <StartWithOpenFrameButton mode="yellow" buttonSize="lg">
   Get Started
 </StartWithOpenFrameButton>
 
-// Cyan with custom brand colors
+// Cyan mode with custom brand colors
 <StartWithOpenFrameButton
   mode="cyan"
-  buttonBackgroundColor="#00BCD4"
+  buttonBackgroundColor="#00BFA5"
   buttonTextColor="#000000"
-/>
+>
+  Launch OpenFrame
+</StartWithOpenFrameButton>
 
 // Loading state
-<StartWithOpenFrameButton loading={isSubmitting} />
-```
+<StartWithOpenFrameButton loading={true} />
+```
+
+> **Source:** [`start-with-openframe-button.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/start-with-openframe-button.tsx)

package/src/components/features/.status-filter-component.md

@@ -1,56 +1,47 @@
-<!-- source-hash: f987a6879214f07a120da4bd03335b15 -->
-Reusable client-side status filter component that renders a row of toggle buttons for filtering content by status, following the admin dashboard pattern used across the Flamingo/OpenFrame platform.
+<!-- source-hash: edc07c45893f37b235057e00e9d58942 -->
+A reusable React client component that renders a row of status filter buttons for admin dashboards, supporting role-based selective disabling of individual status options.
 
 ## Key Components
 
 ### Interfaces
 
-| Interface | Description |
-|-----------|-------------|
-| `StatusOption` | Defines a filter option with `value` and `label` strings |
-| `StatusFilterComponentProps` | Full props contract for the component |
+- **`StatusOption`** — Shape for each filter option: `{ value: string; label: string }`
+- **`StatusFilterComponentProps`** — Full prop contract for the component:
 
-### Props
+| Prop | Type | Description |
+|---|---|---|
+| `selectedStatus` | `string` | Currently active filter value |
+| `onStatusChange` | `(status: string) => void` | Callback fired on button click |
+| `statusOptions` | `StatusOption[]` | List of available filter options |
+| `showCount` | `boolean?` | Toggles item count display (default: `false`) |
+| `count` | `number?` | Number to display when `showCount` is true |
+| `className` | `string?` | Additional CSS classes for the wrapper |
+| `disabledValues` | `string[]?` | Status values to render but disable (e.g. for role-gating) |
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `selectedStatus` | `string` | — | Currently active filter value |
-| `onStatusChange` | `(status: string) => void` | — | Callback fired on filter selection |
-| `statusOptions` | `StatusOption[]` | — | Array of filter options to render |
-| `showCount` | `boolean` | `false` | Toggles item count display |
-| `count` | `number` | `0` | Number shown when `showCount` is enabled |
-| `className` | `string` | `''` | Additional CSS classes for the wrapper |
+### Component
 
-### Exported
-
-- `StatusFilterComponent` — named export, main component
-- `StatusOption` — exported interface
-- `StatusFilterComponentProps` — exported interface
+- **`StatusFilterComponent`** — Renders an "All" button followed by individual status buttons. Active status uses the `accent` variant; inactive uses `outline`. Disabled buttons remain visible but non-interactive — useful for exposing a full status set while restricting which values a viewer may select.
 
 ## Usage Example
 
 ```typescript
 import { StatusFilterComponent, StatusOption } from './status-filter-component';
 
-const ticketStatusOptions: StatusOption[] = [
-  { value: 'open', label: 'Open' },
-  { value: 'in_progress', label: 'In Progress' },
-  { value: 'closed', label: 'Closed' },
+const statusOptions: StatusOption[] = [
+  { value: 'published', label: 'Published' },
+  { value: 'draft', label: 'Draft' },
+  { value: 'archived', label: 'Archived' },
 ];
 
-export function TicketDashboard() {
-  const [status, setStatus] = React.useState('all');
-
-  return (
-    <StatusFilterComponent
-      selectedStatus={status}
-      onStatusChange={setStatus}
-      statusOptions={ticketStatusOptions}
-      showCount
-      count={42}
-    />
-  );
-}
+// Non-management users can only switch to 'published'
+<StatusFilterComponent
+  selectedStatus={currentStatus}
+  onStatusChange={setCurrentStatus}
+  statusOptions={statusOptions}
+  showCount={true}
+  count={42}
+  disabledValues={['draft', 'archived']}
+/>
 ```
 
-> **Note:** The `'all'` option is always rendered as a dedicated button — any `StatusOption` with `value: 'all'` in the input array is automatically excluded from the mapped list to prevent duplication.
+> **Source:** [`status-filter-component.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/status-filter-component.tsx)

package/src/components/features/.tags-selector.md

@@ -1,61 +1,57 @@
-<!-- source-hash: 0d6f9a8deca3671804c89abef2d0469f -->
-A reusable React component for selecting and creating tags with search autocomplete, chip display, and tag limit enforcement.
+<!-- source-hash: 8568bb28ffc1ce07d2d726b7322e39a7 -->
+Reusable React component for selecting and managing tags with search autocomplete, chip display, and optional tag creation.
 
 ## Key Components
 
-### `TagsSelector`
-Main exported component that renders a search input with inline tag chips, an autocomplete dropdown, and a tag counter.
+### Interfaces
 
-**Props (`TagsSelectorProps`):**
+- **`Tag`** — Shape of a tag object: `id`, `name`, `slug`
+- **`TagsSelectorProps`** — Component props:
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `availableTags` | `Tag[]` | — | Pool of tags to search from |
-| `selectedTagIds` | `number[]` | — | Currently selected tag IDs |
-| `onTagsChange` | `(tagIds: number[]) => void` | — | Callback when selection changes |
-| `onCreateTag` | `(name: string) => Promise<Tag \| null>` | — | Optional async tag creation handler |
+|---|---|---|---|
+| `availableTags` | `Tag[]` | — | Pool of selectable tags |
+| `selectedTagIds` | `number[]` | — | Controlled list of selected tag IDs |
+| `onTagsChange` | `(ids: number[]) => void` | — | Fires when selection changes |
+| `onCreateTag` | `(name: string) => Promise<Tag \| null>` | — | Async handler to create a new tag |
 | `maxTags` | `number` | `10` | Maximum selectable tags |
-| `allowCreate` | `boolean` | `true` | Enables the "Create tag" option |
-| `disabled` | `boolean` | `false` | Disables all interactions |
+| `allowCreate` | `boolean` | `true` | Show "Create tag" option in dropdown |
+| `disabled` | `boolean` | `false` | Disables all interaction |
 
-### Internal Helpers
+### Exported Component
 
-- `handleTagAdd` — Adds a tag if not already selected and under the limit
-- `handleTagRemove` — Removes a tag chip from selection
-- `handleCreateTag` — Calls `onCreateTag`, auto-selects the result, manages loading state
-- `getFilteredTagsForAutocomplete` — Filters available tags by search query, excluding already selected
-- `tagExistsWithName` — Case-insensitive duplicate check before showing "Create" option
+- **`TagsSelector`** — Main component rendering the search input, tag chips, autocomplete dropdown, and tag counter
 
 ## Usage Example
 
 ```typescript
 import { TagsSelector } from './tags-selector';
 
-function BlogPostForm() {
-  const [selectedTagIds, setSelectedTagIds] = useState<number[]>([]);
+function MyForm() {
+  const [selectedIds, setSelectedIds] = useState<number[]>([]);
 
-  const handleCreateTag = async (name: string) => {
+  const handleCreate = async (name: string) => {
     const res = await fetch('/api/tags', {
       method: 'POST',
       body: JSON.stringify({ name }),
     });
-    return res.json(); // { id, name, slug }
+    return res.json(); // returns Tag | null
   };
 
   return (
     <TagsSelector
       availableTags={[
-        { id: 1, name: 'MSP', slug: 'msp' },
-        { id: 2, name: 'AI', slug: 'ai' },
+        { id: 1, name: 'TypeScript', slug: 'typescript' },
+        { id: 2, name: 'React', slug: 'react' },
       ]}
-      selectedTagIds={selectedTagIds}
-      onTagsChange={setSelectedTagIds}
-      onCreateTag={handleCreateTag}
+      selectedTagIds={selectedIds}
+      onTagsChange={setSelectedIds}
+      onCreateTag={handleCreate}
       maxTags={5}
-      placeholder="Search tags..."
+      placeholder="Search or create tags..."
     />
   );
 }
 ```
 
-> **Note:** The dropdown auto-opens on focus and supports keyboard creation — pressing `Enter` while typing a new tag name triggers `handleCreateTag` when `allowCreate` is enabled.
+**Source:** [`tags-selector.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tags-selector.tsx)

package/src/components/features/.transcript-summary-editor.md

@@ -1,26 +1,32 @@
-<!-- source-hash: 82679c7416bd1640d332a170504ba800 -->
-A reusable React component that renders editable textarea fields for video summary, transcript, and optional SRT subtitles — with AI generation badges and confidence score indicators.
+<!-- source-hash: 861a257f5441c2c79974b0bc1518d8c1 -->
+Reusable React component that renders editable textarea fields for video summary, transcript, and optional SRT subtitles, with AI generation badges and confidence score indicators.
 
 ## Key Components
 
 ### `TranscriptSummaryEditor`
-The default export. Renders up to three labeled textarea sections:
 
-| Section | Shown When |
-|---|---|
-| **Video Summary** | Always |
-| **Transcript** | Always |
-| **Subtitles (SRT)** | `subtitles` content exists OR `onSubtitlesChange` is provided |
+Main exported component rendering up to three editor sections:
 
-Each section supports:
-- Customizable label, helper text, and placeholder
-- Configurable minimum height
-- `isAIGenerated` badge (Sparkles icon / CC icon for subtitles)
-- `ConfidenceBadge` for AI confidence scores (video summary and transcript only)
-- `disabled` state propagated to all textareas
+- **Video Summary** — always visible; supports Markdown input
+- **Transcript** — always visible; supports speaker diarization format
+- **Subtitles (SRT)** — conditionally rendered when `subtitles` content or `onSubtitlesChange` handler is provided
 
 ### `TranscriptSummaryEditorProps`
-Full TypeScript interface with all configurable props — all optional except `onVideoSummaryChange` and `onTranscriptChange`.
+
+Full interface with sensible defaults for all optional props:
+
+| Prop | Type | Default |
+|---|---|---|
+| `videoSummary` | `string` | `''` |
+| `transcript` | `string` | `''` |
+| `isAIGenerated` | `boolean` | `false` |
+| `videoSummaryConfidence` | `number \| null` | — |
+| `transcriptConfidence` | `number \| null` | — |
+| `disabled` | `boolean` | `false` |
+| `subtitles` | `string` | — |
+| `onSubtitlesChange` | `(value: string) => void` | — |
+
+All label, helper text, placeholder, and `minHeight` props are customizable per field.
 
 ## Usage Example
 
@@ -38,11 +44,11 @@ function InterviewEditor() {
       onVideoSummaryChange={setSummary}
       transcript={transcript}
       onTranscriptChange={setTranscript}
+      subtitles={subtitles}
+      onSubtitlesChange={setSubtitles}
       isAIGenerated={true}
       videoSummaryConfidence={87}
       transcriptConfidence={92}
-      subtitles={subtitles}
-      onSubtitlesChange={setSubtitles}
       videoSummaryMinHeight={250}
       transcriptMinHeight={400}
     />
@@ -50,4 +56,4 @@ function InterviewEditor() {
 }
 ```
 
-> Designed for use with `CustomerInterview` and `ProductRelease` entities in the Flamingo/OpenFrame platform, providing a consistent editing UI across entity types.
+**Source:** [`transcript-summary-editor.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/transcript-summary-editor.tsx)

package/src/components/features/.use-video-warmup.md

@@ -0,0 +1,47 @@
+<!-- source-hash: f3f269920014c6536db44dfc2792eefe -->
+Provides React hooks for warming the network path to video origins, reducing click-to-first-frame latency via preconnects and IntersectionObserver-gated preloads.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `saveDataEnabled` | `function` | Detects metered connections via `navigator.connection?.saveData`; SSR-safe |
+| `useVideoOriginPreconnect` | `hook` | Fires TCP/TLS preconnects to Mux and Supabase Storage origins without IO subscription |
+| `useVideoWarmup` | `hook` | Full warmup — preconnects on every render + IO-gated `<link rel="preload" as="video">` for Supabase-hosted MP4s |
+| `MUX_STREAM_ORIGIN` | `const` | Re-exported from `mux-origins.ts` (server-safe module) |
+| `MUX_IMAGE_ORIGIN` | `const` | Re-exported from `mux-origins.ts` (server-safe module) |
+
+**Origin resolution priority:** explicit `supabaseStorageOrigin` arg → `ChatRuntime.endpoints.supabaseStorageOrigin` → preload skipped (Mux preconnects still fire).
+
+**Preload gates (all must pass):**
+1. Container is within `nearMargin` of viewport (default `1000px`)
+2. `saveDataEnabled()` returns `false`
+3. `videoUrl` origin matches `supabaseStorageOrigin` (Mux HLS and YouTube are intentional no-ops)
+
+## Usage Example
+
+```typescript
+// Full warmup — owns the video container ref
+function VideoCard({ videoUrl }: { videoUrl: string }) {
+  const { ref, isNear } = useVideoWarmup<HTMLDivElement>({
+    videoUrl,
+    nearMargin: '800px',
+  })
+
+  return (
+    <div ref={ref}>
+      {isNear && <MuxPlayer src={videoUrl} />}
+    </div>
+  )
+}
+
+// Preconnect-only — no container ref available
+function ReleasePage() {
+  useVideoOriginPreconnect()
+  return <SiblingVideoPlayer />
+}
+```
+
+> **`useVideoOriginPreconnect` vs `useVideoWarmup`:** Use `useVideoOriginPreconnect` when you cannot attach a `ref` to the video container (e.g. a page that delegates rendering to a sibling). Use `useVideoWarmup` when you own the container.
+
+**Source:** [`hooks/use-video-warmup.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/hooks/use-video-warmup.ts)