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

package/src/components/shared/onboarding/.onboarding-step-card.md

@@ -1,43 +1,44 @@
-<!-- source-hash: 8d3c4c86cfef654b8a89093151c49814 -->
-A React component that renders an interactive card for individual onboarding steps, displaying step information and providing action buttons based on completion status.
+<!-- source-hash: a586fc7eef91717f42e06b54e7cb5290 -->
+A React client component that renders a single onboarding step as an interactive card, supporting completed, skipped, pending, and loading states with appropriate actions.
 
 ## Key Components
 
-- **OnboardingStepCardProps**: Interface defining the step object, completion states, action handlers, and styling props
-- **OnboardingStepCard**: Main component that renders step cards with responsive layout and state-dependent UI
-- **handleAction**: Async function that manages processing state during step actions
-- **handleSkip**: Function for handling step skip actions with event propagation prevention
+### `OnboardingStepCard`
+The primary exported component. Renders a responsive card with a title/description column and a dynamic action column based on step state.
 
-## Usage Example
+**Props (`OnboardingStepCardProps`):**
 
-```typescript
-import { OnboardingStepCard } from './onboarding-step-card'
-import { CheckIcon } from 'lucide-react'
+| Prop | Type | Description |
+|------|------|-------------|
+| `step` | `object` | Step metadata including title, description, icons, action text, and callbacks |
+| `isCompleted` | `boolean` | Shows a success badge and re-run action button |
+| `isSkipped` | `boolean` | Shows a neutral "SKIPPED" badge |
+| `isCheckingCompletion` | `boolean` | Renders animated skeleton placeholders |
+| `onAction` | `() => void \| Promise<void>` | Primary action handler (async-safe) |
+| `onSkip` | `() => void` | Skip step handler |
+| `className` | `string?` | Optional additional CSS classes |
+
+**Internal state:**
+- `isProcessing` — Tracks in-flight async action calls to disable the button and prevent double-submission.
 
-const step = {
-  id: 'connect-device',
-  title: 'Connect Your Device',
-  description: 'Link your OpenFrame device to get started',
-  actionIcon: (color?: string) => <CheckIcon color={color} />,
-  actionText: 'Connect Now',
-  completedText: 'Reconnect',
-  onAction: async () => {
-    // Device connection logic
-  },
-  onSkip: () => {
-    // Skip step logic
-  }
-}
+## Usage Example
 
+```typescript
 <OnboardingStepCard
-  step={step}
+  step={{
+    id: 'connect-psa',
+    title: 'Connect your PSA',
+    description: 'Link your ticketing system to get started',
+    actionIcon: (color) => <PlugIcon color={color} />,
+    actionText: 'Connect Now',
+    completedText: 'Reconnect',
+    onAction: () => router.push('/integrations/psa'),
+    onSkip: () => console.log('skipped'),
+  }}
   isCompleted={false}
   isSkipped={false}
   isCheckingCompletion={false}
-  onAction={handleStepAction}
-  onSkip={handleStepSkip}
-  className="max-w-md"
+  onAction={() => router.push('/integrations/psa')}
+  onSkip={() => markStepSkipped('connect-psa')}
 />
-```
-
-The component automatically handles different states: incomplete (showing Skip/Action buttons), completed (showing badge and reconnect option), skipped (showing skipped badge), and loading (showing skeleton UI).
+```

package/src/components/shared/onboarding/.onboarding-walkthrough.md

@@ -1,51 +1,47 @@
-<!-- source-hash: d87b964ccbfaf2cb1dd8da2dfb0db703 -->
-A React component that renders a complete onboarding walkthrough with steps that can be completed, skipped, or automatically marked as complete based on external validation.
+<!-- source-hash: 89208f0119005a51561aa80d8594f307 -->
+Renders a multi-step onboarding walkthrough UI that syncs external completion status with local storage state, prevents race conditions via refs, and displays dismissible step cards.
 
 ## Key Components
 
-- **OnboardingWalkthrough**: Main component that orchestrates the onboarding flow
-- **OnboardingWalkthroughProps**: Interface defining configuration options including steps, completion status, and loading states
-- **useOnboardingState**: Custom hook for managing onboarding state and persistence
-- **OnboardingStepCard**: Child component for rendering individual steps (imported)
-
-## Key Features
-
-- **Auto-completion Sync**: Automatically marks steps as complete based on external `completionStatus` prop
-- **Race Condition Prevention**: Uses refs to prevent duplicate actions and state conflicts
-- **Responsive Design**: Mobile-first layout with stacked elements on small screens
-- **Persistent State**: Stores progress in localStorage via configurable `storageKey`
-- **Action Handling**: Executes step actions and validates completion asynchronously
+- **`OnboardingWalkthrough`** — Main exported component that orchestrates step rendering, completion tracking, and dismissal
+- **`OnboardingWalkthroughProps`** — Interface defining the component's props
+- **`useOnboardingState`** — Hook managing persistent onboarding state (completed/skipped/dismissed) via `localStorage`
+- **`OnboardingStepCard`** — Child component rendering individual step cards
+- **Race condition guards** — Three refs (`hasAutoMarkedRef`, `autoMarkingInProgressRef`, `actionInProgressRef`) prevent duplicate or concurrent state mutations
 
 ## Usage Example
 
 ```typescript
 import { OnboardingWalkthrough } from './onboarding-walkthrough'
-import { useOnboardingCompletion } from './hooks/use-onboarding-completion'
-
-function App() {
-  const { completionStatus, isLoading } = useOnboardingCompletion()
-  
-  const steps = [
-    {
-      id: 'setup-device',
-      title: 'Setup Device',
-      onAction: async () => {
-        // Navigate to device setup
-      },
-      checkComplete: async () => {
-        // Verify device is configured
-        return await checkDeviceStatus()
-      }
-    }
-  ]
-
-  return (
-    <OnboardingWalkthrough
-      steps={steps}
-      completionStatus={completionStatus}
-      isLoadingCompletion={isLoading}
-      onDismiss={() => console.log('Onboarding dismissed')}
-    />
-  )
-}
-```
+import type { OnboardingStepConfig } from '../../../hooks/ui/use-onboarding-state'
+
+const steps: OnboardingStepConfig[] = [
+  {
+    id: 'knowledge-base',
+    title: 'Set up Knowledge Base',
+    description: 'Upload your documentation.',
+    onAction: async () => { /* open modal or navigate */ },
+  },
+  {
+    id: 'connect-psa',
+    title: 'Connect your PSA',
+    description: 'Integrate your ticketing system.',
+    onAction: async () => { /* trigger integration flow */ },
+    checkComplete: async () => await checkPsaConnected(),
+  },
+]
+
+<OnboardingWalkthrough
+  steps={steps}
+  storageKey="my-app-onboarding"
+  completionStatus={{ 'connect-psa': true }}
+  isLoadingCompletion={false}
+  onDismiss={() => console.log('dismissed')}
+/>
+```
+
+## Behavior Notes
+
+- **Auto-sync**: When `completionStatus` prop changes, steps flagged `true` are automatically marked complete via `markMultipleComplete`, guarded by a JSON-stringified status key to avoid re-processing identical data.
+- **Action deduplication**: `actionInProgressRef` tracks in-flight step actions per `step.id`, silently skipping duplicate triggers.
+- **All hooks called unconditionally** — the `state.dismissed` early return happens *after* all hooks and refs are initialized, satisfying React's Rules of Hooks.

package/src/components/shared/product-release/.index.md

@@ -1,40 +1,38 @@
-<!-- source-hash: fe3c3eaf77690b6e1108b738006bd2c9 -->
-A client-side module that exports components and types for displaying product releases and roadmap information in the Flamingo platform.
+<!-- source-hash: b0b73e639c7dda545193a2a31fafd1ca -->
+Barrel export file for the **product release** UI component family, re-exporting all public components, skeletons, and related TypeScript types from the `product-release` feature directory.
 
 ## Key Components
 
-- **ProductReleaseCard** - Component for displaying individual product release cards with associated props type
-- **ProductReleaseCardSkeleton** - Loading skeleton component for product release cards  
-- **ReleaseDetailPage** - Main component for rendering detailed release pages with markdown content and roadmap sections
-- **ReleaseDetailSkeleton** - Loading skeleton for the release detail page
-- **Type Exports** - Comprehensive TypeScript interfaces including `MarkdownRendererProps`, `RoadmapItem`, `DeliveryResponse`, and section-specific prop types
+| Export | Type | Description |
+|--------|------|-------------|
+| `ProductReleaseCard` | Component | Card UI for displaying a product release |
+| `ProductReleaseCardSkeleton` | Component | Loading skeleton for `ProductReleaseCard` |
+| `ReleaseDetailPage` | Component | Full release detail page layout |
+| `ReleaseDetailSkeleton` | Component | Loading skeleton for `ReleaseDetailPage` |
+| `DeliveryResponse` | Type | Canonical delivery response type (sourced from `types/delivery`) |
+| `ProductReleaseCardProps` | Type | Props for `ProductReleaseCard` |
+| `ReleaseDetailPageProps` | Type | Props for `ReleaseDetailPage` |
+| `VideoDisplaySectionProps` | Type | Props for the video display section slot |
+| `MarkdownRendererProps` | Type | Props for the markdown renderer slot |
+| `RoadmapItem` | Type | Individual roadmap item type |
+
+> **Note:** `RoadmapSectionProps` and `DeliverySectionProps` are intentionally **not** re-exported here to avoid TS2308 ambiguous re-export conflicts with the concrete `<RoadmapGrid>` / `<DeliverySection>` components. Import them directly from the `release-detail-page` module if needed.
 
 ## Usage Example
 
 ```typescript
-import { 
-  ProductReleaseCard, 
-  ReleaseDetailPage,
+import {
+  ProductReleaseCard,
   ProductReleaseCardSkeleton,
-  type RoadmapItem 
-} from './index'
-
-// Display a product release card
-<ProductReleaseCard 
-  title="OpenFrame v2.1"
-  description="Enhanced AI automation features"
-  releaseDate="2024-03-15"
-/>
-
-// Show loading state
-<ProductReleaseCardSkeleton />
+  ReleaseDetailPage,
+  ReleaseDetailSkeleton,
+  type ReleaseDetailPageProps,
+  type DeliveryResponse,
+} from '@flamingo-stack/openframe-frontend-core/components/shared/product-release'
 
-// Render detailed release page with roadmap
-<ReleaseDetailPage 
-  releaseId="v2.1"
-  markdownContent={content}
-  roadmapItems={roadmapData}
-/>
-```
+// Render a release card
+<ProductReleaseCard title="v2.1.0" date="2025-06-01" />
 
-The module follows the "use client" directive, indicating these components are designed for client-side rendering in Next.js applications and likely include interactive features for browsing Flamingo's product releases and development roadmap.
+// Deep import for internal slot types
+import type { RoadmapSectionProps } from '@flamingo-stack/openframe-frontend-core/components/shared/product-release/release-detail-page'
+```

package/src/components/shared/product-release/.product-release-card-skeleton.md

@@ -1,44 +1,44 @@
-<!-- source-hash: c0adf54207555e0c4b1be60f8796bbfe -->
-A React skeleton loader component that displays animated placeholder content while product release card data is loading.
+<!-- source-hash: 35eb2dca49e5c1311632535a7cffdf8b -->
+Pixel-perfect loading skeleton for `ProductReleaseCard` that prevents layout shift by mirroring the loaded card's exact dimensions in both `lg` and `sm` variants.
 
 ## Key Components
 
-- **ProductReleaseCardSkeleton** - Main skeleton component with pulse animation
-- **ProductReleaseCardSkeletonProps** - TypeScript interface defining component props
-- **cn utility** - CSS class name merging function for conditional styling
+### `ProductReleaseCardSkeleton`
+
+A client-side animated pulse skeleton component with two size branches:
+
+| Branch | Matches | Structure |
+|--------|---------|-----------|
+| `lg` | `ProductReleaseCard size="lg"` | Hero image + version pill + title + summary + changelog strip + 4-cell metadata grid |
+| `sm` | `ProductReleaseCard size="sm"` | Thumbnail + title row + date row + summary row |
+
+### `ProductReleaseCardSkeletonProps`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Additional CSS classes |
+| `size` | `'lg' \| 'sm'` | `'lg'` | Must match the target card's `size` prop to prevent layout shift on resolve |
 
 ## Usage Example
 
 ```typescript
 import { ProductReleaseCardSkeleton } from './product-release-card-skeleton'
 
-// Basic usage
-function LoadingState() {
-  return <ProductReleaseCardSkeleton />
-}
-
-// With custom styling
-function CustomLoadingState() {
+// Full release card placeholder (e.g. in ReleasesList grid)
+function ReleasesListLoading() {
   return (
-    <ProductReleaseCardSkeleton 
-      className="shadow-lg border-2" 
-    />
+    <div className="grid grid-cols-1 gap-4">
+      {Array.from({ length: 5 }).map((_, i) => (
+        <ProductReleaseCardSkeleton key={i} size="lg" />
+      ))}
+    </div>
   )
 }
 
-// Multiple skeletons for list loading
-function ProductReleasesList({ isLoading }) {
-  if (isLoading) {
-    return (
-      <div className="space-y-4">
-        {Array.from({ length: 3 }).map((_, index) => (
-          <ProductReleaseCardSkeleton key={index} />
-        ))}
-      </div>
-    )
-  }
-  // ... render actual content
+// Compact inline placeholder (e.g. inside a chat message)
+function ChatReleaseLoading() {
+  return <ProductReleaseCardSkeleton size="sm" />
 }
 ```
 
-The component provides a responsive layout that adapts from column to row orientation on mobile/desktop, with skeleton placeholders for title (2 lines), description (3 lines), version info, date, and an icon. The pulse animation provides visual feedback during loading states.
+> **Important:** Always pass the same `size` value as the `ProductReleaseCard` it replaces. Mismatched sizes cause measurable layout shift when the loaded card resolves, since placeholder heights are calibrated to match each variant's exact rendered metrics.

package/src/components/shared/product-release/.product-release-card.md

@@ -1,38 +1,56 @@
-<!-- source-hash: d95c7f17971bf8e3a5aa9bf22f8c17a9 -->
-A React component that displays product release information in an interactive card format with responsive layout for desktop and mobile viewports.
+<!-- source-hash: 46c409eeb72da32ccf9384919a0c8ba0 -->
+React card component for displaying product release information in two density variants (`lg` and `sm`), used across OpenFrame's releases catalog, Flamingo's DevCenter, and related-content rails.
 
 ## Key Components
 
-- **ProductReleaseCard** - Main component that renders release information
-- **ProductReleaseCardProps** - TypeScript interface defining component props
-- **InteractiveCard** - Imported wrapper component providing click interactions
-- **ChevronRight** - Lucide React icon for visual navigation cue
+### Types & Interfaces
+
+| Export | Description |
+|--------|-------------|
+| `ProductReleaseCardSize` | Union type `'lg' \| 'sm'` controlling card density |
+| `ProductReleaseCardAnchorProps` | Structural `<a>` prop bundle for consumer-controlled routing (href, target, rel, onClick) |
+| `ProductReleaseCardProps` | Full prop surface for the card component |
+
+### `ProductReleaseCard`
+
+The primary export. Renders in two layout modes:
+
+- **`lg` (default):** Three-zone rich card — hero (16:9 cover + version pill + title + summary), changelog stats strip (features/fixes/improvements/breaking counts), and a 4-cell metadata grid (Type · Status · Released · Author). Author cell falls back to an `EMPTY_AUTHOR_PLACEHOLDER` shape to prevent skeleton reflow.
+- **`sm`:** Compact horizontal layout (~80px tall) for chat messages and tight inline surfaces. Replaces `<h3>` with `<span>`, uses a `<span>`-anchored link wrapper, and renders: 56px icon + 1-line title + version/date meta.
 
 ## Usage Example
 
 ```typescript
 import { ProductReleaseCard } from './product-release-card'
 
-function ReleaseList() {
-  return (
-    <div className="space-y-4">
-      <ProductReleaseCard
-        title="Major UI Overhaul"
-        summary="Complete redesign of the dashboard interface with improved user experience"
-        version="2.1.0"
-        formattedDate="March 15, 2024"
-        onClick={() => router.push('/releases/2.1.0')}
-        className="hover:shadow-lg"
-      />
-      <ProductReleaseCard
-        title="Security Updates"
-        version="2.0.1"
-        formattedDate="February 28, 2024"
-        onClick={() => router.push('/releases/2.0.1')}
-      />
-    </div>
-  )
-}
+// Large catalog card with full metadata
+<ProductReleaseCard
+  size="lg"
+  title="OpenFrame 2.1.0"
+  summary="Unified AI-driven interface improvements and new automation hooks."
+  version="2.1.0"
+  formattedDate="May 2026"
+  coverImage="https://cdn.flamingo.run/releases/2.1.0.jpg"
+  releaseType="minor"
+  releaseStatus="stable"
+  releaseTypeBadgeColor="success"
+  changelogCounts={{ features: 8, fixes: 5, improvements: 3, breaking: 0 }}
+  author={{ full_name: "Jane Doe", avatar_url: null, job_title: "Engineer" }}
+  anchorProps={{ href: "/releases/2.1.0", onClick: handleNav }}
+/>
+
+// Compact inline card (e.g., inside a chat message)
+<ProductReleaseCard
+  size="sm"
+  title="OpenFrame 2.1.0"
+  version="2.1.0"
+  formattedDate="May 2026"
+  anchorProps={{ href: "/releases/2.1.0" }}
+/>
 ```
 
-The component features a responsive design that stacks content vertically on mobile and arranges it horizontally on desktop. It uses DM Sans typography, ODS design tokens for styling, and includes proper click event handling with propagation control for nested interactive elements.
+## Notes
+
+- **Routing:** Prefer `anchorProps` (from the hub's `useNavLink`) over the legacy `onClick` prop. When both are provided, `anchorProps` wins.
+- **Author cell:** Always rendered using `effectiveAuthor` (falls back to `{ full_name: '—', avatar_url: null, job_title: 'Unknown' }`) to maintain a fixed 4-column grid and prevent skeleton reflow.
+- **Inline duplication policy:** The `lg` metadata grid intentionally duplicates the hub's `<EntityAuthorCard>` visuals — the OSS lib carries zero hub imports by design. Keep both in lockstep when cell padding, divider styles, or avatar sizes change.

package/src/components/shared/product-release/.release-detail-page.md

@@ -1,42 +1,41 @@
-<!-- source-hash: cdd882b49d403f07e79375cf36040ac9 -->
-A React component that renders a detailed release page with metadata display, media gallery, linked tasks, and flexible component injection for different app contexts.
+<!-- source-hash: bce89d098aaae5a0045e31b754508d2a -->
+A client-side React page component that renders a detailed view of a product release, including metadata, changelog sections, linked roadmap/delivery tasks, media, and video content. It supports injectable components for app-specific rendering and pre-fetched data for admin preview.
 
 ## Key Components
 
-- **ReleaseDetailPage**: Main component that displays comprehensive release information including title, version, metadata grid, and changelog sections
-- **DefaultMarkdownRenderer**: Simple fallback component for rendering markdown content as plain text
-- **Type interfaces**: `ReleaseDetailPageProps`, `UseReleaseResult`, `MarkdownRendererProps` for component customization and data structure
-- **Media gallery integration**: Handles image gallery modal with navigation functionality
-- **Linked tasks fetching**: Automatically fetches roadmap and delivery tasks associated with the release
+### Exported Types
+- **`ReleaseDetailPageProps`** — Main props interface; accepts `slug`, optional `initialData`, a `useRelease` hook, and injectable section components
+- **`UseReleaseResult`** — Shape returned by the injected `useRelease` hook
+- **`MarkdownRendererProps`**, **`RoadmapSectionProps`**, **`DeliverySectionProps`**, **`VideoSectionProps`**, **`VideoDisplaySectionProps`** — Props interfaces for each injectable section component
+- **`RoadmapItem`**, **`DeliveryResponse`** — Re-exported canonical types for source compatibility
+
+### Main Export
+- **`ReleaseDetailPage`** — Primary page component; orchestrates data fetching, linked task loading, gallery state, and layout rendering
+
+### Internal Helpers
+- **`DefaultMarkdownRenderer`** — Fallback renderer using `whitespace-pre-wrap` when no `MarkdownRenderer` is injected
 
 ## Usage Example
 
 ```typescript
 import { ReleaseDetailPage } from './release-detail-page';
-import { useRelease } from '../hooks/useRelease';
-import { CustomMarkdownRenderer } from '../components/markdown';
+import { useRelease } from '@/hooks/use-release';
+import { MarkdownRenderer } from '@/components/markdown-renderer';
+import { RoadmapSection } from '@/components/roadmap-section';
 
-function ReleasePage({ params }: { params: { slug: string } }) {
+export default function ReleasePage({ params }: { params: { slug: string } }) {
   return (
     <ReleaseDetailPage
       slug={params.slug}
       useRelease={useRelease}
-      MarkdownRenderer={CustomMarkdownRenderer}
-      RoadmapSection={RoadmapTasksComponent}
-      DeliverySection={DeliveryTasksComponent}
-      roadmapApiEndpoint="/api/roadmap-tasks"
-      deliveryApiEndpoint="/api/delivery-tasks"
+      MarkdownRenderer={MarkdownRenderer}
+      RoadmapSection={RoadmapSection}
+      roadmapApiEndpoint="/api/roadmap"
+      deliveryApiEndpoint="/api/delivery"
+      backButton={{ label: 'Back to releases', href: '/releases' }}
     />
   );
 }
-
-// For admin preview with pre-fetched data
-<ReleaseDetailPage
-  slug="v2.1.0"
-  initialData={preloadedReleaseData}
-  useRelease={useRelease}
-  MarkdownRenderer={RichMarkdownRenderer}
-/>
 ```
 
-The component supports both public release viewing and admin preview modes, with optional component injection for custom markdown rendering and task management sections.
+> **Note:** The `useRelease` hook must be provided at the app level to ensure it uses the correct `QueryClient`. When `initialData` is supplied, the hook is bypassed entirely — enabling admin preview without a network fetch.

package/src/components/shared/roadmap/.index.md

@@ -0,0 +1,37 @@
+<!-- source-hash: 499214f4840bb2650161d384a662b71b -->
+Barrel export file for the shared roadmap surface, exposing grid components and voting hook while intentionally omitting `RoadmapItem` and `VoteType` to prevent TypeScript TS2308 ambiguous re-export errors.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `RoadmapGrid` | Component | Main grid layout for displaying roadmap items |
+| `RoadmapGridProps` | Type | Props interface for `RoadmapGrid` |
+| `RoadmapGridSkeleton` | Component | Loading skeleton for the roadmap grid |
+| `RoadmapGridSkeletonProps` | Type | Props interface for `RoadmapGridSkeleton` |
+| `useRoadmapVoting` | Hook | Hook encapsulating roadmap voting logic |
+| `VoteState` | Type | State shape for a vote interaction |
+| `UseRoadmapVotingOptions` | Type | Options interface for `useRoadmapVoting` |
+
+## Intentionally Omitted Exports
+
+| Omitted | Reason | Canonical Import Path |
+|---------|--------|-----------------------|
+| `RoadmapItem` | Already exported via two paths; a third triggers TS2308 | `@flamingo-stack/openframe-frontend-core/components/chat` |
+| `VoteType` | Duplicate of the same type re-exported from `./chat` | `@flamingo-stack/openframe-frontend-core/components/chat` |
+
+## Usage Example
+
+```typescript
+// ✅ Import roadmap surface components from this barrel
+import {
+  RoadmapGrid,
+  RoadmapGridSkeleton,
+  useRoadmapVoting,
+  type VoteState,
+  type UseRoadmapVotingOptions,
+} from '@flamingo-stack/openframe-frontend-core/components/shared/roadmap';
+
+// ✅ Import omitted types from their canonical paths
+import type { RoadmapItem, VoteType } from '@flamingo-stack/openframe-frontend-core/components/chat';
+```

package/src/components/shared/roadmap/.roadmap-grid-skeleton.md

@@ -0,0 +1,39 @@
+<!-- source-hash: 906f9090b003db906415d2c34987f68e -->
+Loading skeleton for the `/roadmap` grid view, rendering animated placeholder cards while roadmap data is being fetched.
+
+## Key Components
+
+### `RoadmapCardSkeleton` *(internal)*
+A 340px animated placeholder card mimicking the full grid card layout. Renders pulsing skeletons for:
+- Status badge (top-right)
+- Icon + title + subtitle
+- 3-line description block
+- Bottom action area (button + badge)
+
+> **Note:** Intentionally kept file-internal to avoid naming collision with `RoadmapCardSkeleton` from `lib/chat/entity-cards/roadmap-card.tsx`, which is a compact 56px chat-card variant.
+
+### `RoadmapGridSkeleton` *(exported)*
+Renders a responsive 1→2 column grid of `RoadmapCardSkeleton` instances.
+
+### `RoadmapGridSkeletonProps`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `count` | `number` | `4` | Number of skeleton cards to render |
+| `showLeftMargin` | `boolean` | `true` | Applies `md:ml-[120px]` to align with the page hero title block. Pass `false` for narrower surfaces (e.g. release detail page) |
+
+## Usage Example
+
+```typescript
+// Default: 4 cards with left margin (full roadmap page)
+<RoadmapGridSkeleton />
+
+// Custom count, no left margin (embedded in a narrower rail)
+<RoadmapGridSkeleton count={6} showLeftMargin={false} />
+
+// Typical Suspense / conditional pattern
+{isLoading
+  ? <RoadmapGridSkeleton count={4} />
+  : <RoadmapGrid items={roadmapItems} />
+}
+```

package/src/components/shared/roadmap/.roadmap-grid.md

@@ -0,0 +1,66 @@
+<!-- source-hash: afe909dc035ab417a954948a391b890a -->
+Full-page roadmap surface that renders a responsive 2-column grid of `RoadmapCard` components with integrated voting state and live count refresh.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `RoadmapGrid` | Component | Main grid component rendering all roadmap items |
+| `RoadmapGridProps` | Interface | Component prop contract |
+| `DEFAULT_BUILD_REFRESH_URL` | Constant | Default URL builder: `(taskId) => /api/roadmap/${taskId}` |
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `RoadmapItem[]` | — | Roadmap entries to display |
+| `onItemUpdate` | `(item: RoadmapItem) => void` | — | Callback fired after a successful vote refresh |
+| `showLeftMargin` | `boolean` | `true` | Applies `md:ml-[120px]` for hero alignment; pass `false` for rails |
+| `buildRefreshUrl` | `(taskId: string) => string` | `DEFAULT_BUILD_REFRESH_URL` | Path-based URL builder for per-task refresh after vote |
+| `votingOptions` | `UseRoadmapVotingOptions` | — | Vote endpoint + storage key forwarded to `useRoadmapVoting` |
+
+## Voting Flow
+
+```mermaid
+graph TD
+    A["User Clicks Vote"] --> B{"Task Already Voting?"}
+    B -->|Yes| C["Ignore / No-op"]
+    B -->|No| D["Lock Task ID in votingTasks"]
+    D --> E["toggleVote()"]
+    E --> F{"result.success?"}
+    F -->|No| G["Unlock Task ID"]
+    F -->|Yes| H["GET buildRefreshUrl(taskId)"]
+    H --> I{"response.ok?"}
+    I -->|Yes| J["onItemUpdate(data.item)"]
+    I -->|No| G
+    J --> G
+```
+
+## Usage Example
+
+```typescript
+import { RoadmapGrid } from './roadmap-grid';
+import type { RoadmapItem } from '../../chat/types/entities/roadmap-item';
+
+function RoadmapPage({ items }: { items: RoadmapItem[] }) {
+  const [roadmapItems, setRoadmapItems] = useState(items);
+
+  const handleItemUpdate = (updated: RoadmapItem) => {
+    setRoadmapItems(prev =>
+      prev.map(i => (i.id === updated.id ? updated : i))
+    );
+  };
+
+  return (
+    <RoadmapGrid
+      items={roadmapItems}
+      onItemUpdate={handleItemUpdate}
+      showLeftMargin={true}
+      buildRefreshUrl={(taskId) => `/api/roadmap/${taskId}`}
+      votingOptions={{ endpoint: '/api/votes', storageKey: 'roadmap-votes' }}
+    />
+  );
+}
+```
+
+> **Note on `buildRefreshUrl`:** This prop is intentionally a function rather than a string template to safely support embedders whose by-id route shape differs (e.g. `/api/roadmap?id=…`). String concatenation would silently break non-standard routes.