@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213-snapshot.20260528174436

package/src/components/contact/.contact-form.md

@@ -0,0 +1,43 @@
+<!-- source-hash: e6e63274e2215026ef420402aa7a9e8f -->
+A self-contained, reusable contact form component that supports both standard contact submission and custom ticket-creation flows via configurable props. It handles field visibility toggling, attachment staging, Zod validation, and dual submit paths (built-in API vs. caller-provided handler).
+
+## Key Components
+
+**Exported Types**
+- `ContactFormHideableField` — Union type of the six fields that can be suppressed from the UI (`name`, `email`, `companySize`, `referralSource`, `helpCategory`, `message`)
+- `ContactFormProps` — Full prop interface covering attribution, pre-fill, layout, submission, and slot customization
+
+**Main Export**
+- `ContactForm` — The primary form component
+
+**Internal Hooks Used**
+- `useForm` (react-hook-form) + `zodResolver` against `ContactSchema`
+- `useContactSubmission` — built-in `/api/contact` submit path with toast + redirect
+- `useChatAttachments` — file staging shared with the chat composer
+- `useState` — tracks in-flight state for the custom submit path
+
+## Usage Example
+
+```typescript
+// Standard contact page — built-in submit flow
+<ContactForm
+  userId={user?.id}
+  helpCategoryOptions={appConfig.contact.contactReasons}
+  rdtCid={getStoredRedditClickId()}
+  onSubmitSuccess={clearStoredRedditClickId}
+/>
+
+// Ticket creation — custom submit, hidden fields, extra Subject input
+<ContactForm
+  hideFields={['name', 'email', 'companySize', 'referralSource', 'helpCategory']}
+  defaultValues={{ name: user.name, email: user.email, helpCategory: 'Support' }}
+  attachmentsEnabled
+  extraTopField={<SubjectInput value={subject} onChange={setSubject} />}
+  submitLabel="Open ticket"
+  onCustomSubmit={async (data, attachments) => {
+    await actions.submitTicket({ ...data, subject, attachments })
+  }}
+/>
+```
+
+> **Note:** When hiding `name`, `email`, or `helpCategory`, you **must** supply their values via `defaultValues` — Zod still validates them even when the fields are not rendered. Hidden `<input type="hidden">` elements ensure react-hook-form includes them in the submit payload.

package/src/components/contact/.index.md

@@ -0,0 +1,27 @@
+<!-- source-hash: 29826720baf088c1409fbd30046713a4 -->
+Re-exports the `ContactForm` component along with its associated TypeScript types from the `contact-form` module.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `ContactForm` | Component | The main contact form component |
+| `ContactFormProps` | Type | Props interface for the `ContactForm` component |
+| `ContactFormHideableField` | Type | Type representing fields that can be hidden in the form |
+
+## Usage Example
+
+```typescript
+import {
+  ContactForm,
+  type ContactFormProps,
+  type ContactFormHideableField,
+} from '@/components/contact-form'
+
+const hiddenFields: ContactFormHideableField[] = ['phone', 'company']
+
+const props: ContactFormProps = {
+  onSubmit: (data) => console.log(data),
+  hideFields: hiddenFields,
+}
+```

package/src/components/features/.array-entry-manager.md

@@ -1,53 +1,44 @@
-<!-- source-hash: b9899c71d148f2b5407351f417b4f050 -->
-A React component for managing arrays of entries with add/edit/remove functionality, supporting both immediate and deferred save modes.
+<!-- source-hash: 9a66a790bb4e14efee7ac5e9ffc0cfb8 -->
+A generic, reusable React component for managing arrays of objects with inline add, edit, remove, and multi-line paste support. Supports both immediate and deferred (save-gated) change modes.
 
 ## Key Components
 
-- **ArrayEntryManager** - Generic TypeScript component for managing array entries with configurable fields
-- **Props Interface** - Comprehensive configuration options including custom renderers, save modes, and styling
-- **State Management** - Handles both immediate updates and draft mode with dirty state tracking
-- **Paste Handling** - Smart multi-line paste support for bulk entry addition
+### `ArrayEntryManager<T>`
+A generic client component that renders a labeled list of editable input entries backed by a typed array.
 
-## Usage Example
-
-```typescript
-import { ArrayEntryManager } from './array-entry-manager';
-import { Github } from 'lucide-react';
+**Props:**
 
-interface Release {
-  github_release_url: string;
-  version?: string;
-}
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `ReactNode` | Section label; supports strings or badge components |
+| `items` | `T[]` | Array of objects to manage |
+| `onChange` | `(items: T[]) => void` | Called on change (immediate) or save (deferred) |
+| `fieldKey` | `keyof T` | Object key to bind each input to |
+| `requireSave` | `boolean` | When `true`, buffers edits locally until "Save" is clicked |
+| `onDirtyChange` | `(isDirty: boolean) => void` | Notifies parent of unsaved changes |
+| `renderLabel` | `(item: T, index: number) => ReactNode` | Custom renderer above each input |
+| `isSaving` | `boolean` | Shows spinner on the save button during async operations |
 
-function ReleaseManager() {
-  const [releases, setReleases] = useState<Release[]>([]);
-  const [isSaving, setIsSaving] = useState(false);
+**Behaviors:**
+- **Draft mode** (`requireSave=true`): edits are buffered in local state; `onChange` fires only on explicit save
+- **Immediate mode** (`requireSave=false`): every edit calls `onChange` directly
+- **Multi-line paste**: pasting newline-separated values auto-creates multiple entries
+- **Add at top**: new items are prepended for better UX
 
-  const handleSave = async (items: Release[]) => {
-    setIsSaving(true);
-    // Save to API
-    await saveReleases(items);
-    setIsSaving(false);
-  };
-
-  return (
-    <ArrayEntryManager
-      title="GitHub Releases"
-      items={releases}
-      onChange={handleSave}
-      fieldKey="github_release_url"
-      placeholder="https://github.com/owner/repo/releases/tag/v1.0.0"
-      emptyMessage="No releases configured"
-      addButtonText="Add Release"
-      icon={<Github className="h-5 w-5" />}
-      requireSave={true}
-      isSaving={isSaving}
-      renderLabel={(item, index) => 
-        item.version && <span className="badge">{item.version}</span>
-      }
-    />
-  );
-}
-```
+## Usage Example
 
-The component supports immediate onChange updates or deferred saves with dirty state tracking, multi-line paste for bulk additions, and custom label rendering for enhanced UX.
+```typescript
+<ArrayEntryManager<{ github_release_url: string }>
+  title="Release URLs"
+  items={releaseUrls}
+  onChange={setReleaseUrls}
+  fieldKey="github_release_url"
+  placeholder="https://github.com/org/repo/releases/tag/v1.0.0"
+  emptyMessage="No release URLs configured."
+  addButtonText="Add URL"
+  saveButtonText="Save URLs"
+  requireSave={true}
+  onDirtyChange={(dirty) => setHasUnsavedChanges(dirty)}
+  isSaving={isSaving}
+/>
+```

package/src/components/features/.changelog-manager.md

@@ -1,12 +1,35 @@
-<!-- source-hash: 3644c900574f6a351d839d94b7f4446b -->
-A client-side React component for managing changelog entries with expandable/collapsible sections, providing an interface to add, edit, and remove changelog items with title and description fields.
+<!-- source-hash: 2cb028936365715865c9571d3df0261e -->
+A reusable React component for managing a dynamic list of changelog entries, supporting add, remove, expand/collapse, and optional per-entry visibility toggling.
 
 ## Key Components
 
-- **ChangelogManager**: Main component that renders a list of expandable changelog entries
-- **ChangelogManagerProps**: Interface defining component props including title, entries array, change handler, and optional expand control
-- **State Management**: Uses `useState` for tracking expanded items and `useEffect` for handling expand-all functionality
-- **Entry Operations**: Functions for adding, removing, and updating changelog entries with automatic expansion state management
+### `ChangelogManager` (default export)
+
+A controlled list manager rendered as a collapsible accordion of `ChangelogEntry` items.
+
+**Props (`ChangelogManagerProps`):**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `string` | Section label displayed above the entry list |
+| `entries` | `ChangelogEntry[]` | Controlled array of changelog entries |
+| `onChange` | `(entries: ChangelogEntry[]) => void` | Callback fired on any mutation |
+| `className` | `string?` | Optional wrapper class override |
+| `expandAll` | `boolean?` | When `true`, expands all items (e.g. post-AI enrichment) |
+| `showVisibilityToggle` | `boolean?` | Renders a per-entry `Eye`/`EyeOff` toggle; used by investor updates |
+
+**Internal state:**
+- `expandedIndices` — `Set<number>` tracking which accordion items are open
+
+**Key functions:**
+
+| Function | Behavior |
+|----------|----------|
+| `addEntry()` | Appends a blank entry and auto-expands it |
+| `removeEntry(index)` | Removes entry and adjusts the expanded indices set |
+| `updateEntry(index, field, value)` | Immutably updates a single field on an entry |
+| `toggleExpanded(index)` | Toggles accordion open/close state |
+| `toggleVisibility(index)` | Flips `visibility` between `'public'` and `'internal'` |
 
 ## Usage Example
 
@@ -14,20 +37,23 @@ A client-side React component for managing changelog entries with expandable/col
 import { ChangelogManager } from './changelog-manager';
 import type { ChangelogEntry } from '../../types/product-release';
 
-function ReleaseNotesForm() {
-  const [features, setFeatures] = useState<ChangelogEntry[]>([]);
-  const [expandFeatures, setExpandFeatures] = useState(false);
-
-  return (
-    <ChangelogManager
-      title="New Features"
-      entries={features}
-      onChange={setFeatures}
-      expandAll={expandFeatures}
-      className="mb-6"
-    />
-  );
-}
+const [entries, setEntries] = useState<ChangelogEntry[]>([]);
+
+// Basic product release changelog
+<ChangelogManager
+  title="What's New"
+  entries={entries}
+  onChange={setEntries}
+/>
+
+// Investor update with visibility control + auto-expand after AI fill
+<ChangelogManager
+  title="Highlights"
+  entries={entries}
+  onChange={setEntries}
+  showVisibilityToggle
+  expandAll={aiEnrichmentComplete}
+/>
 ```
 
-The component provides a clean interface for managing changelog sections with collapsible entries, automatic expansion of new items, and responsive design with dark theme styling. Each entry includes title and description fields with validation indicators.
+> **Note:** `showVisibilityToggle` is intended for investor update flows. Leave it unset for standard product release changelogs to preserve their default UX. New entries default to `visibility: 'public'` when the toggle is enabled.

package/src/components/features/.changelog-sections-manager.md

@@ -1,11 +1,11 @@
-<!-- source-hash: 24082a43cb0377e101a4f1957ec35829 -->
-A React component that organizes and manages changelog entries across four distinct categories, providing a structured interface for editing product release notes.
+<!-- source-hash: 25788d62c9b251ff8382443ab8b6fcff -->
+A client-side React component that renders all four standard changelog sections (Features Added, Bugs Fixed, Improvements, Breaking Changes) as a unified, styled panel by composing multiple `ChangelogManager` instances.
 
 ## Key Components
 
-- **ChangelogSectionsManager**: Main component that renders four `ChangelogManager` instances for different changelog categories
-- **ChangelogSectionsManagerProps**: Interface defining props including entry arrays, change handlers, and display options
-- **Category Sections**: Features Added, Bugs Fixed, Improvements, and Breaking Changes
+- **`ChangelogSectionsManager`** — Main exported component that groups and renders all changelog sections in a single card layout
+- **`ChangelogSectionsManagerProps`** — Interface defining per-section entry arrays, change handlers, optional `className`, and `expandAll` flag
+- **`expandAll`** — Boolean prop that expands all entries across all sections simultaneously, intended for use after AI enrichment populates fields
 
 ## Usage Example
 
@@ -13,27 +13,22 @@ A React component that organizes and manages changelog entries across four disti
 import { ChangelogSectionsManager } from './changelog-sections-manager';
 import type { ChangelogEntry } from '../../types/product-release';
 
-function ReleaseEditor() {
-  const [features, setFeatures] = useState<ChangelogEntry[]>([]);
-  const [bugs, setBugs] = useState<ChangelogEntry[]>([]);
-  const [improvements, setImprovements] = useState<ChangelogEntry[]>([]);
-  const [breaking, setBreaking] = useState<ChangelogEntry[]>([]);
+const [featuresAdded, setFeaturesAdded] = useState<ChangelogEntry[]>([]);
+const [bugsFixed, setBugsFixed] = useState<ChangelogEntry[]>([]);
+const [improvements, setImprovements] = useState<ChangelogEntry[]>([]);
+const [breakingChanges, setBreakingChanges] = useState<ChangelogEntry[]>([]);
 
-  return (
-    <ChangelogSectionsManager
-      featuresAdded={features}
-      bugsFixed={bugs}
-      improvements={improvements}
-      breakingChanges={breaking}
-      onFeaturesAddedChange={setFeatures}
-      onBugsFixedChange={setBugs}
-      onImprovementsChange={setImprovements}
-      onBreakingChangesChange={setBreaking}
-      expandAll={true} // Expand all sections after AI enrichment
-      className="my-4"
-    />
-  );
-}
+<ChangelogSectionsManager
+  featuresAdded={featuresAdded}
+  bugsFixed={bugsFixed}
+  improvements={improvements}
+  breakingChanges={breakingChanges}
+  onFeaturesAddedChange={setFeaturesAdded}
+  onBugsFixedChange={setBugsFixed}
+  onImprovementsChange={setImprovements}
+  onBreakingChangesChange={setBreakingChanges}
+  expandAll={aiEnrichmentComplete}
+/>
 ```
 
-The component uses a consistent card layout with ODS (OpenFrame Design System) styling and delegates individual section management to the `ChangelogManager` component. The `expandAll` prop is particularly useful for displaying AI-enhanced changelog entries.
+Each section delegates entry management (add, edit, remove) to its own `ChangelogManager` instance while sharing the `expandAll` state, keeping the parent component's state management straightforward with one array and one setter per section.

package/src/components/features/.command-box.md

@@ -1,12 +1,20 @@
-<!-- source-hash: 58a52ec93cc9a268c0cf74ea4894e9e7 -->
-A unified React component for displaying commands with optional title and configurable action buttons, featuring responsive design and consistent styling within the ODS design system.
+<!-- source-hash: b7d1c615d3d37a540958daff7feed5f3 -->
+A reusable React component for displaying command strings in a styled monospace box with optional title and configurable action buttons.
 
 ## Key Components
 
-- **`CommandBoxAction`** - Interface defining action button properties including label, click handler, variant, icon, and state
-- **`CommandBoxProps`** - Main component props interface with command text, title, actions, and styling options
-- **`CommandBox`** - Primary component that renders command text in a styled card with optional action buttons
-- **`lineClampClasses`** - Static mapping object for Tailwind line-clamp classes to enable build-time optimization
+### Interfaces
+
+| Interface | Description |
+|-----------|-------------|
+| `CommandBoxAction` | Defines a button with `label`, `onClick`, optional `variant`, `icon`, `disabled`, and `loading` states |
+| `CommandBoxProps` | Component props including `command` (required), `title`, `primaryAction`, `secondaryAction`, layout classes, and `maxLines` |
+
+### Exports
+
+- **`CommandBox`** — Main component rendering the command display box
+- **`CommandBoxAction`** — Interface for action button configuration
+- **`CommandBoxProps`** — Interface for component props
 
 ## Usage Example
 
@@ -14,34 +22,29 @@ A unified React component for displaying commands with optional title and config
 import { CommandBox } from '@flamingo/ui-kit/components/features'
 import { Copy, Play } from 'lucide-react'
 
-// Basic command display with copy action
 <CommandBox
-  title="Installation Command"
-  command="npm install @flamingo/ui-kit"
-  primaryAction={{
-    label: 'Copy',
-    onClick: () => navigator.clipboard.writeText(command),
-    icon: <Copy className="w-4 h-4" />,
-    variant: 'primary'
-  }}
-/>
-
-// Multi-line command with line limiting
-<CommandBox
-  command="curl -L https://example.com/install.sh | bash -s -- --config production"
-  maxLines={2}
+  title="Device Add Command"
+  command="curl -L https://example.com/install.sh | bash"
+  maxLines={3}
   primaryAction={{
     label: 'Copy Command',
-    onClick: handleCopy,
-    variant: 'outline'
+    onClick: () => navigator.clipboard.writeText(command),
+    icon: <Copy className="w-5 h-5" />,
+    variant: 'accent'
   }}
   secondaryAction={{
-    label: 'Execute',
-    onClick: handleExecute,
-    icon: <Play className="w-4 h-4" />,
-    loading: isExecuting
+    label: 'Run on Machine',
+    onClick: handleRun,
+    icon: <Play className="w-5 h-5" />,
+    variant: 'outline',
+    loading: isRunning
   }}
 />
 ```
 
-The component automatically handles responsive layout, switching from row to column layout on smaller screens, and supports up to 6 lines of text clamping for long commands.
+## Notes
+
+- **Line clamping** uses a static `lineClampClasses` map (`1–6`) to ensure Tailwind generates the correct `line-clamp-*` classes at build time. Set `maxLines={0}` (default) for unlimited display.
+- **Button layout** stacks vertically on mobile and aligns right horizontally on `md+` screens.
+- Secondary action renders before the primary action visually, consistent with standard UI conventions.
+- `variant` defaults to `'accent'` for primary and `'outline'` for secondary if not specified.

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

@@ -0,0 +1,46 @@
+<!-- source-hash: 87dfd7f5b94bff0f44ed579685785b88 -->
+Reusable editor component for entity summary fields with AI generation badges and confidence score display.
+
+## Key Components
+
+**`EntitySummaryEditor`** — Default export. A controlled textarea editor with optional AI metadata indicators.
+
+**`EntitySummaryEditorProps`** — TypeScript interface defining all configurable props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `summary` | `string` | `''` | Controlled text value |
+| `onSummaryChange` | `(value: string) => void` | required | Change handler |
+| `isAIGenerated` | `boolean` | `false` | Shows AI Generated badge |
+| `summaryConfidence` | `number \| null` | — | Confidence score (0–100) |
+| `label` | `string` | `'Summary (Markdown supported)'` | Field label |
+| `helperText` | `string` | `'Entity summary...'` | Subtext below label |
+| `placeholder` | `string` | `'Brief summary...'` | Textarea placeholder |
+| `minHeight` | `number` | `200` | Minimum height in px |
+| `disabled` | `boolean` | `false` | Disables the textarea |
+| `className` | `string` | `''` | Container class override |
+
+## Usage Example
+
+```typescript
+import { EntitySummaryEditor } from './entity-summary-editor';
+
+function ReleaseForm() {
+  const [summary, setSummary] = React.useState('');
+
+  return (
+    <EntitySummaryEditor
+      summary={summary}
+      onSummaryChange={setSummary}
+      isAIGenerated={true}
+      summaryConfidence={87}
+      label="Release Summary (Markdown supported)"
+      helperText="Displayed on release cards and detail page."
+      placeholder="Describe this release..."
+      minHeight={240}
+    />
+  );
+}
+```
+
+When `isAIGenerated` is `true`, a `Sparkles` icon badge renders next to the label. When `summaryConfidence` is provided, `ConfidenceBadge` renders inline showing the AI confidence percentage.

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

@@ -0,0 +1,51 @@
+<!-- source-hash: e2ba951ef60128447d27416a00b1a586 -->
+Renders the video block for entity detail pages, combining full video, highlight video, AI-generated summary, and video bites into a unified tabbed layout.
+
+## Key Components
+
+### `EntityVideoSection` (default export)
+Main component that orchestrates the video display logic:
+- **Tab UI** — renders "Full Video" / "Highlights" tabs when both a full video and highlight video are present; falls back to a single `<Video>` when only one exists
+- **YouTube precedence** — resolves `youtubeUrl` vs `mainVideoUrl` priority at this level, keeping `<Video>` as a single-source-per-render primitive
+- **Video summary** — renders an AI-generated markdown summary via injected `MarkdownRenderer`
+- **Video bites grid** — delegates to `<VideoBitesDisplay>` when `videoBites` are provided
+- **Null guard** — returns `null` when no video, summary, or bites are present
+
+### `EntityVideoSectionProps`
+Full interface for controlling content and behavior:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `youtubeUrl` | `string \| null` | YouTube URL (takes priority over `mainVideoUrl`) |
+| `mainVideoUrl` | `string \| null` | Uploaded video URL |
+| `highlightVideoUrl` | `string \| null` | AI-generated highlight clip |
+| `captionsUrl` | `string \| null` | HTTPS URL to a VTT captions file |
+| `MarkdownRenderer` | `ComponentType` | Injected renderer for summary markdown |
+| `priority` | `boolean` | LCP hint for eager poster loading |
+| `srtContent` | `string \| null` | Deprecated — use `captionsUrl` |
+
+## Usage Example
+
+```typescript
+import { EntityVideoSection } from './entity-video-section';
+import { MarkdownRenderer } from '@/components/markdown-renderer';
+
+export function TalkDetailPage({ talk }) {
+  return (
+    <EntityVideoSection
+      youtubeUrl={talk.youtubeUrl}
+      mainVideoUrl={talk.videoUrl}
+      highlightVideoUrl={talk.highlightUrl}
+      highlightVideoThumbnail={talk.highlightThumb}
+      mainVideoPoster={talk.posterUrl}
+      title={talk.title}
+      videoSummary={talk.aiSummary}
+      videoBites={talk.bites}
+      bitesTitle="Key Moments"
+      captionsUrl={talk.captionsUrl}
+      MarkdownRenderer={MarkdownRenderer}
+      priority
+    />
+  );
+}
+```

package/src/components/features/.figma-prototype-viewer.md

@@ -1,45 +1,64 @@
-<!-- source-hash: 334f79ef37d39fafa41a9fecfc6bf342 -->
-A responsive React component for embedding and viewing Figma prototypes with automatic device detection, adaptive scaling, and section-based navigation.
+<!-- source-hash: d8463fe41098681892c9956a4d6c77ce -->
+Renders an interactive Figma prototype viewer component with responsive layout, automatic device detection, section navigation, and scaled iframe embedding for both desktop and mobile viewports.
 
 ## Key Components
 
-- **FigmaPrototypeViewer**: Main component with unified state management and responsive iframe embedding
-- **UnifiedState**: Comprehensive state interface managing view modes, scaling, navigation, and UI states
-- **ViewMode Types**: `DESKTOP`, `MOBILE`, `MOBILE_TOUCH` with automatic detection based on screen size and touch capability
-- **Configuration System**: Supports environment variables and config-based setup for file keys, dimensions, and starting points
-- **Scaling Engine**: Calculates optimal iframe scaling and positioning for different screen sizes
-- **Section Navigation**: Integration with SectionSelector for prototype flow navigation
+### Interfaces & Types
+- **`FigmaPrototypeViewerConfig`** — Main configuration object; accepts file keys (per-device or legacy single), sections, dimensions, starting points, and UI class overrides
+- **`FigmaPrototypeSection`** — Defines a navigable prototype section with separate desktop/mobile node IDs
+- **`UnifiedState`** — Consolidated state shape covering view mode, iframe lifecycle, scaling, UI visibility flags, and navigation
+- **`ViewMode`** — `'DESKTOP' | 'MOBILE' | 'MOBILE_TOUCH'`
+- **`IframeState`** — `'INITIAL' | 'LOADING' | 'READY' | 'RELOADING' | 'SLEEP_RECOVERY'`
+
+### Core Functions
+- **`getViewMode(screenWidth, isTouchDevice)`** — Derives current `ViewMode` from screen width against the 768px breakpoint
+- **`calculateScaling(viewMode, containerDimensions, config?)`** — Computes `scale`, `marginX/Y`, and `scaledDimensions` to fit content without upscaling
+- **`resolveFileKey(config, viewMode)`** — Picks the correct Figma file key via env vars → per-device config → legacy `fileKey`
+- **`resolveStartingPoint(config, viewMode, section?)`** — Resolves the initial prototype node via env vars → config → first section fallback
+- **`generateEmbedUrl(...)`** — Builds the `embed.figma.com/proto` URL with all required query parameters
+- **`renderUnifiedUI(state, handlers, config, iframeRef)`** — Pure render function producing the full component JSX from state
+
+### Environment Variable Overrides
+Content dimensions and file keys can be set at the environment level:
+
+```text
+NEXT_PUBLIC_FIGMA_MOBILE_FILE_KEY
+NEXT_PUBLIC_FIGMA_DESKTOP_FILE_KEY
+NEXT_PUBLIC_FIGMA_MOBILE_STARTING_POINT
+NEXT_PUBLIC_FIGMA_DESKTOP_STARTING_POINT
+NEXT_PUBLIC_FIGMA_MOBILE_WIDTH / _HEIGHT
+NEXT_PUBLIC_FIGMA_DESKTOP_WIDTH / _HEIGHT
+```
+
+Priority order: **env vars → config props → defaults**
 
 ## Usage Example
 
 ```typescript
 import { FigmaPrototypeViewer } from './figma-prototype-viewer'
+import type { FigmaPrototypeViewerConfig } from './figma-prototype-viewer'
 
-const config = {
-  title: "Design System Prototype",
-  desktopFileKey: "abc123...",
-  mobileFileKey: "def456...",
+const config: FigmaPrototypeViewerConfig = {
+  title: 'Onboarding Flow',
+  desktopFileKey: 'abc123XYZ',
+  mobileFileKey: 'xyz789ABC',
+  desktopStartingPoint: '1:23',
+  mobileStartingPoint: '4:56',
   sections: [
     {
-      id: "onboarding",
-      number: "01",
-      title: "User Onboarding",
-      startingNodeId: "123:456",
-      mobileStartingNodeId: "789:012"
-    }
+      id: 'sign-up',
+      number: '01',
+      title: 'Sign Up',
+      description: 'New user registration flow',
+      startingNodeId: '1:23',
+      mobileStartingNodeId: '4:56',
+    },
   ],
+  mobileContentDimensions: { width: 343, height: 600 },
   desktopContentDimensions: { width: 944, height: 600 },
-  mobileContentDimensions: { width: 343, height: 600 }
 }
 
-function PrototypePage() {
-  return (
-    <FigmaPrototypeViewer 
-      config={config}
-      onSectionClick={(sectionId) => console.log('Section changed:', sectionId)}
-    />
-  )
+export default function PrototypePage() {
+  return <FigmaPrototypeViewer config={config} />
 }
-```
-
-The component automatically detects device capabilities, manages iframe states (loading, ready, reloading), and provides smooth transitions between sections. Environment variables can override config settings for deployment flexibility.
+```