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

package/src/components/shared/legal-document/.legal-document-page.md

@@ -1,50 +1,56 @@
-<!-- source-hash: 3706922a9df0493d5342fee857818e2a -->
-Unified page component for rendering markdown-backed legal documents (privacy policy, terms of service, etc.), replacing duplicate per-document hub components with a single configurable abstraction.
+<!-- source-hash: 4d38aabccf09a05e49d7f4a234d30fbd -->
+Unified React page component for rendering markdown-backed legal documents (privacy policy, terms of service, etc.), replacing duplicate per-document page components with a single configurable implementation.
 
 ## Key Components
 
 ### `LegalDocumentPage`
-Main exported component that handles the full page lifecycle — loading skeleton, error state, empty state, and rendered markdown content — driven entirely by props.
+Main exported component. Fetches and renders a legal document via `useLegalDocs`, handling loading skeletons, error states, and empty states. Conditionally wraps output in `PageShell` based on the `shell` prop.
 
 ### `LegalDocumentPageProps`
-Configuration interface covering:
-- **`docType`** — drives the default `/api/legal/<docType>` endpoint and error-log prefix
-- **`title` / `fallbackDescription`** — heading and subtitle text
-- **`contactEmail` / `errorContactPrompt` / `errorTitle` / `emptyStateMessage`** — per-document copy strings
-- **`initialData` / `initialLastUpdatedLabel`** — SSR hydration-safe pre-fetched data
-- **`apiEndpoint`** — optional override for reverse-proxy or alternate API paths
-- **`MarkdownRenderer`** — injectable renderer (defaults to `SimpleMarkdownRenderer`); pass a richer renderer for embeds/video/OG previews
-- **`backButton`** — configurable back-nav; pass `false` to hide in embed mode
+Full configuration interface including:
+- `docType` — drives the default `/api/legal/<docType>` endpoint
+- `title`, `fallbackDescription`, `contactEmail` — display copy
+- `errorTitle`, `errorContactPrompt`, `emptyStateMessage` — state-specific messaging
+- `initialData` / `initialLastUpdatedLabel` — SSR hydration support
+- `MarkdownRenderer` — injectable renderer component (defaults to `RichMarkdownRenderer`)
+- `backButton` — configurable back navigation or `false` to hide
+- `shell` — toggle `PageShell` wrapper for embed contexts
 
 ### `LegalDocumentMarkdownRendererProps`
-Renderer contract interface with `content`, `sectionIds`, and `demoteMarkdownH1ToH2`.
+Interface for the pluggable `MarkdownRenderer` component contract: `content`, optional `sectionIds`, and `demoteMarkdownH1ToH2`.
 
 ## Usage Example
 
 ```typescript
-// Privacy Policy page
+import { LegalDocumentPage } from './legal-document-page';
+
+// Basic usage (Privacy Policy)
 <LegalDocumentPage
   docType="privacy"
   title="Privacy Policy"
-  fallbackDescription="Our privacy policy and data protection practices."
+  fallbackDescription="Our privacy policy and data protection practices"
   contactEmail="privacy@openframe.io"
   errorContactPrompt="For privacy-related questions, please contact:"
   errorTitle="Unable to load privacy policy"
   emptyStateMessage="Privacy policy content is not available at this time."
   initialData={ssrDocument}
-  initialLastUpdatedLabel="January 15, 2025"
+  initialLastUpdatedLabel={ssrLabel}
 />
 
-// Embed mode with custom renderer and no back button
+// Embedded mode — host provides layout, custom renderer
 <LegalDocumentPage
   docType="terms"
   title="Terms of Service"
-  fallbackDescription="Terms governing use of our platform."
+  fallbackDescription="Our terms and conditions"
   contactEmail="legal@openframe.io"
   errorContactPrompt="For legal questions, please contact:"
   errorTitle="Unable to load terms of service"
-  emptyStateMessage="Terms of service content is not available at this time."
-  MarkdownRenderer={RichMarkdownRenderer}
+  emptyStateMessage="Terms of service content is not available."
+  shell={false}
   backButton={false}
+  apiEndpoint="/proxy/api/legal/terms"
+  MarkdownRenderer={MyRichRenderer}
 />
-```
+```
+
+**Source:** [`legal-document-page.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/legal-document-page.tsx)

package/src/components/shared/legal-document/.use-legal-docs.md

@@ -1,42 +1,48 @@
-<!-- source-hash: 8cc6f0cadfbca233ed799a57d6b4388c -->
-A React hook that fetches markdown-backed legal documents (privacy policy, terms of service, etc.) from a hub API endpoint, with support for SSR/RSC pre-fetched data and manual refetching.
+<!-- source-hash: ee50746d44329588b4ebfaeeb2bd0d9c -->
+Fetches a legal document (privacy policy, terms of service, or any markdown-backed legal page) from a hub API endpoint, with SSR/RSC hydration support via optional `initialData`.
 
 ## Key Components
 
 ### Interfaces
 
-| Interface | Description |
-|-----------|-------------|
-| `LegalDocument` | Shape of the fetched document — includes title, markdown content, GitHub sync metadata, and parsed section headings |
-| `UseLegalDocsOptions` | Hook configuration — optional `initialData` for SSR hydration and `apiEndpoint` override for reverse-proxy embedders |
-| `UseLegalDocsReturn` | Hook return value — `data`, `isLoading`, `error`, and `refetch` |
+- **`LegalDocument`** — Shape of the fetched legal document, mirroring the hub's server-side `LegalDocument` type to avoid server-side import dependencies.
+- **`UseLegalDocsOptions`** — Hook configuration: optional `initialData` for SSR hydration and `apiEndpoint` override for reverse-proxy embedders.
+- **`UseLegalDocsReturn`** — Hook return shape: `data`, `isLoading`, `error`, and `refetch`.
 
-### `useLegalDocs(docType, options?)`
+### Hook
 
-Core hook that manages fetch lifecycle for a legal document. Key behaviors:
-
-- **Default endpoint:** `/api/legal/<docType>` — overridable via `apiEndpoint`
-- **SSR-safe:** When `initialData` is provided, the initial client fetch is skipped entirely
-- **`docType` reset guard:** When `docType` changes, stale data is cleared immediately before the new fetch resolves — prevents flash of wrong content in embedders cycling through document types
-- **Error handling:** Propagates HTTP errors and empty-content responses as human-readable strings via the `error` state
+- **`useLegalDocs(docType, options)`** — Core hook. Resolves the effective endpoint (`/api/legal/<docType>` by default), manages fetch lifecycle state, resets state on `docType` change, and skips the initial client fetch when `initialData` is provided.
 
 ## Usage Example
 
 ```typescript
+import { useLegalDocs } from './use-legal-docs';
+
 // Basic client-side fetch
-const { data, isLoading, error, refetch } = useLegalDocs('privacy');
-
-// SSR hydration — skip initial client fetch
-const { data } = useLegalDocs('terms', {
-  initialData: serverFetchedDoc,
-});
-
-// Reverse-proxy embedder overriding the endpoint
-const { data, isLoading } = useLegalDocs('privacy', {
-  apiEndpoint: '/proxy/legal/privacy',
-});
-
-if (isLoading) return <Spinner />;
-if (error) return <ErrorBanner message={error} onRetry={refetch} />;
-return <MarkdownRenderer content={data?.content} />;
-```
+function PrivacyPage() {
+  const { data, isLoading, error, refetch } = useLegalDocs('privacy');
+
+  if (isLoading) return <p>Loading…</p>;
+  if (error) return <p>Error: {error}</p>;
+  return <article>{data?.content}</article>;
+}
+
+// With SSR-prefetched data (skips initial client fetch)
+function TermsPage({ serverData }: { serverData: LegalDocument }) {
+  const { data } = useLegalDocs('terms', { initialData: serverData });
+  return <article>{data?.content}</article>;
+}
+
+// With a proxied endpoint (embedder override)
+function EmbedPrivacy() {
+  const { data } = useLegalDocs('privacy', {
+    apiEndpoint: '/proxy/legal/privacy',
+  });
+  return <article>{data?.content}</article>;
+}
+```
+
+## Notes
+
+- `docType` is treated as an opaque string and intentionally kept out of `console.error`'s format-string argument to prevent CodeQL `js/tainted-format-string` findings.
+- State resets on `docType` change prevent stale content from briefly rendering during sequential document loads.

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

@@ -1,25 +1,31 @@
-<!-- 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.
+<!-- source-hash: 90ed7a4de133a1c00403aa5d89978252 -->
+A React client component that renders a single onboarding step as an interactive card, displaying step metadata and contextual action buttons based on completion/skip state.
 
 ## Key Components
 
 ### `OnboardingStepCard`
-The primary exported component. Renders a responsive card with a title/description column and a dynamic action column based on step state.
-
-**Props (`OnboardingStepCardProps`):**
+The primary exported component. Renders a responsive card (stacked on mobile, horizontal on `md+`) with two columns:
+- **Left column** — step title and description (truncated with tooltip)
+- **Right column** — state-driven action area
 
+### `OnboardingStepCardProps`
 | 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 |
+|---|---|---|
+| `step` | `object` | Step metadata: id, title, description, action handlers, and icon factory |
+| `isCompleted` | `boolean` | Shows COMPLETED badge + secondary action button |
+| `isSkipped` | `boolean` | Shows SKIPPED badge, no actions |
 | `isCheckingCompletion` | `boolean` | Renders animated skeleton placeholders |
-| `onAction` | `() => void \| Promise<void>` | Primary action handler (async-safe) |
+| `onAction` | `() => void \| Promise<void>` | Primary action handler |
 | `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.
+### State Machine (Right Column)
+| Condition | Rendered UI |
+|---|---|
+| `isCheckingCompletion` | Pulsing skeleton loaders |
+| `isCompleted` | COMPLETED badge + repeat-action button |
+| `isSkipped` | SKIPPED badge only |
+| default | Skip + primary action buttons |
 
 ## Usage Example
 
@@ -30,15 +36,17 @@ The primary exported component. Renders a responsive card with a title/descripti
     title: 'Connect your PSA',
     description: 'Link your ticketing system to get started',
     actionIcon: (color) => <PlugIcon color={color} />,
-    actionText: 'Connect Now',
+    actionText: 'Connect',
     completedText: 'Reconnect',
     onAction: () => router.push('/integrations/psa'),
-    onSkip: () => console.log('skipped'),
+    onSkip: () => markSkipped('connect-psa'),
   }}
   isCompleted={false}
   isSkipped={false}
   isCheckingCompletion={false}
   onAction={() => router.push('/integrations/psa')}
-  onSkip={() => markStepSkipped('connect-psa')}
+  onSkip={() => markSkipped('connect-psa')}
 />
-```
+```
+
+> **Note:** `handleAction` uses internal `isProcessing` state to disable the button during async operations, preventing duplicate submissions. Both handlers call `e.stopPropagation()` to prevent card-level click bubbling.

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

@@ -1,47 +1,61 @@
-<!-- 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.
+<!-- source-hash: 7a7aa5f6a5049b0fd0108b153da19ff8 -->
+Orchestrates a multi-step onboarding walkthrough UI, managing step completion state, skip/dismiss interactions, and syncing external completion checks to persistent localStorage state.
 
 ## Key Components
 
-- **`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
+### `OnboardingWalkthrough` (default export)
+Main component that renders a header with dismiss/close controls and a list of `OnboardingStepCard` items.
+
+### `OnboardingWalkthroughProps`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `OnboardingStepConfig[]` | — | Step definitions to render |
+| `onDismiss` | `() => void` | — | Callback fired after dismissal |
+| `storageKey` | `string` | `'openframe-onboarding-state'` | localStorage key for persisted state |
+| `completionStatus` | `Record<string, boolean>` | — | External hook-driven completion map |
+| `isLoadingCompletion` | `boolean` | `false` | Suppresses auto-marking while checks are in flight |
+| `className` / `spacing` | `string` | — | Layout overrides |
+
+### Internal Behaviors
+- **Auto-sync** (`useEffect`): Detects changes in `completionStatus` and bulk-marks newly completed steps via `markMultipleComplete`, guarded by refs to prevent race conditions.
+- **`handleStepAction`** (`useCallback`): Runs `step.onAction()`, then optionally calls `step.checkComplete()` to verify and mark completion; `knowledge-base` steps are auto-completed without verification.
+- **`handleStepSkip`** / **`handleDismiss`**: Delegate to `useOnboardingState` and fire optional callbacks.
 
 ## Usage Example
 
 ```typescript
 import { OnboardingWalkthrough } from './onboarding-walkthrough'
-import type { OnboardingStepConfig } from '../../../hooks/ui/use-onboarding-state'
+import { useOnboardingCompletion } from '../../../hooks/ui/use-onboarding-completion'
 
-const steps: OnboardingStepConfig[] = [
+const steps = [
   {
     id: 'knowledge-base',
-    title: 'Set up Knowledge Base',
-    description: 'Upload your documentation.',
-    onAction: async () => { /* open modal or navigate */ },
+    title: 'Add Knowledge Base',
+    description: 'Upload your docs.',
+    onAction: async () => router.push('/knowledge'),
   },
   {
     id: 'connect-psa',
-    title: 'Connect your PSA',
-    description: 'Integrate your ticketing system.',
-    onAction: async () => { /* trigger integration flow */ },
-    checkComplete: async () => await checkPsaConnected(),
+    title: 'Connect PSA',
+    description: 'Link your ticketing system.',
+    onAction: async () => router.push('/integrations'),
+    checkComplete: async () => !!(await fetchPsaStatus()),
+    onSkip: () => console.log('PSA skipped'),
   },
 ]
 
-<OnboardingWalkthrough
-  steps={steps}
-  storageKey="my-app-onboarding"
-  completionStatus={{ 'connect-psa': true }}
-  isLoadingCompletion={false}
-  onDismiss={() => console.log('dismissed')}
-/>
+function Dashboard() {
+  const { completionStatus, isLoading } = useOnboardingCompletion()
+
+  return (
+    <OnboardingWalkthrough
+      steps={steps}
+      completionStatus={completionStatus}
+      isLoadingCompletion={isLoading}
+      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.
+> **Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/onboarding-walkthrough.tsx)

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

@@ -1,38 +1,47 @@
-<!-- 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.
+<!-- source-hash: 60b9ca8b719e2a8ed7836247d6f859d9 -->
+Public barrel module for the product release UI component suite, marked as a client component boundary (`"use client"`).
 
 ## Key Components
 
-| 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.
+| Export | Description |
+|---|---|
+| `ProductReleaseCard` | Card component for displaying a single product release |
+| `ProductReleaseCardSkeleton` | Loading skeleton for `ProductReleaseCard` |
+| `ProductReleasesView` | List/grid view rendering multiple release cards |
+| `ReleaseDetailPage` | Full detail page for a single release, with injectable component slots |
+| `ReleaseDetailSkeleton` | Loading skeleton for `ReleaseDetailPage` |
+| `DeliveryResponse` | Re-exported type from the canonical types module for downstream consumers |
+
+### Notable Type Exports
+
+- `ProductReleaseCardProps`, `ProductReleaseCardSkeletonProps`, `ProductReleasesViewProps`
+- `ProductReleaseCardExtras` — extra data shape passed into release cards
+- `ReleaseDetailPageProps`, `VideoDisplaySectionProps`, `MarkdownRendererProps`, `RoadmapItem`
+
+> **⚠️ Intentional Omissions:** `RoadmapSectionProps` and `DeliverySectionProps` are **not** re-exported here. They conflict with identically-named prop types on `<RoadmapGrid>` and `<DeliverySection>` causing `TS2308` ambiguous re-export errors at the top-level barrel. Import them directly:
+
+```typescript
+import type { RoadmapSectionProps } from '@flamingo-stack/openframe-frontend-core/components/shared/product-release/release-detail-page'
+```
 
 ## Usage Example
 
 ```typescript
 import {
-  ProductReleaseCard,
-  ProductReleaseCardSkeleton,
+  ProductReleasesView,
   ReleaseDetailPage,
   ReleaseDetailSkeleton,
-  type ReleaseDetailPageProps,
+  type ProductReleaseCardExtras,
   type DeliveryResponse,
 } from '@flamingo-stack/openframe-frontend-core/components/shared/product-release'
 
-// Render a release card
-<ProductReleaseCard title="v2.1.0" date="2025-06-01" />
+// Render a list of releases
+<ProductReleasesView releases={releases} />
 
-// Deep import for internal slot types
-import type { RoadmapSectionProps } from '@flamingo-stack/openframe-frontend-core/components/shared/product-release/release-detail-page'
-```
+// Render a full release detail page with a suspense fallback
+<Suspense fallback={<ReleaseDetailSkeleton />}>
+  <ReleaseDetailPage release={release} />
+</Suspense>
+```
+
+**Source:** [`components/shared/product-release/index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/components/shared/product-release/index.ts)

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

@@ -1,44 +1,38 @@
-<!-- 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.
+<!-- source-hash: c2128eeaf09cf16a3c77d41f2e6d9b86 -->
+Animated loading skeleton for `ProductReleaseCard` that prevents layout shift by precisely matching the loaded card's dimensions in both `lg` and `sm` size variants.
 
 ## Key Components
 
-### `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 |
+| `size` | `'lg' \| 'sm'` | `'lg'` | Must match the target `ProductReleaseCard` size prop |
+
+### `ProductReleaseCardSkeleton`
+
+The exported component renders two structurally distinct skeletons:
+
+- **`size='lg'`** — Full card with hero section (16:9 image + version pill + title + summary), a changelog strip placeholder, and a 4-cell metadata grid (3 stat cells + 1 author avatar cell). All inner element heights are pinned to match the resolved card's `min-h` reservations.
+- **`size='sm'`** — Compact inline card (used in chat contexts) with a square thumbnail, title row with version pill, date row, and summary row. Uses `<span>` elements to remain valid inside inline containers.
+
+Both branches apply `animate-pulse` and throw defensively if an unsupported `size` value is passed at runtime.
 
 ## Usage Example
 
 ```typescript
 import { ProductReleaseCardSkeleton } from './product-release-card-skeleton'
 
-// Full release card placeholder (e.g. in ReleasesList grid)
-function ReleasesListLoading() {
-  return (
-    <div className="grid grid-cols-1 gap-4">
-      {Array.from({ length: 5 }).map((_, i) => (
-        <ProductReleaseCardSkeleton key={i} size="lg" />
-      ))}
-    </div>
-  )
-}
-
-// Compact inline placeholder (e.g. inside a chat message)
-function ChatReleaseLoading() {
-  return <ProductReleaseCardSkeleton size="sm" />
-}
+// Full card — use while fetching release data for the main releases list
+<ProductReleaseCardSkeleton size="lg" />
+
+// Compact card — use while fetching release data in a chat message slot
+<ProductReleaseCardSkeleton size="sm" className="mt-2" />
 ```
 
-> **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.
+> **Layout shift note:** The `size` prop on this skeleton **must** match the `size` prop passed to the resolved `ProductReleaseCard`. Mismatching causes a measurable reflow when the skeleton is replaced because `lg` and `sm` produce different pixel heights.
+
+## Source
+
+[`product-release-card-skeleton.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/product-release-card-skeleton.tsx)

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

@@ -1,56 +1,55 @@
-<!-- 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.
+<!-- source-hash: 2ffaa5e5c7023bbeed7803f954f2f327 -->
+React component that renders product release cards in two density variants (`lg` and `sm`) for displaying software release information across OpenFrame and Flamingo MSP platform surfaces.
 
 ## Key Components
 
 ### 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 |
+- **`ProductReleaseCardSize`** — Union type `'lg' | 'sm'` controlling card density
+- **`ProductReleaseCardAnchorProps`** — Structural `<a>` prop bundle (`href`, `target`, `rel`, `onClick`) for consumer-composed navigation; shape-compatible with the hub's `useNavLink` hook
+- **`ProductReleaseCardProps`** — Full prop surface including title, summary, version, changelog counts, author, cover image, and release metadata
 
 ### `ProductReleaseCard`
 
-The primary export. Renders in two layout modes:
+Main export. Renders one of two layouts based on the `size` prop (defaults to `'lg'`):
 
-- **`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.
+- **`lg`** — Three-zone layout: hero (16:9 cover image + version pill + title + summary), changelog stats strip (feature/fix/improvement/breaking counts), and a fixed 4-cell metadata grid (Type · Status · Released · Author). Renders as an `<InteractiveCard>` with hover/focus states.
+- **`sm`** — Compact horizontal layout (~80px tall) for inline chat and tight surfaces. Uses `<span>` elements instead of block-level tags (safe inside markdown `<p>`), 56px icon, 1-line title, and condensed meta (version · date).
+
+Navigation is handled via `anchorProps` (preferred) or legacy `onClick` for back-compat.
 
 ## Usage Example
 
 ```typescript
-import { ProductReleaseCard } from './product-release-card'
+import { ProductReleaseCard } from '@openframe/ui'
 
 // 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"
+  title="OpenFrame 2.4.0"
+  summary="Adds AI-powered ticket triage and bulk automation rules."
+  version="2.4.0"
+  formattedDate="Jun 12, 2025"
+  coverImage="https://cdn.example.com/releases/2.4.0-cover.png"
   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 }}
+  changelogCounts={{ features: 8, fixes: 14, improvements: 5, breaking: 0 }}
+  author={{ full_name: "Ada Lovelace", avatar_url: "/avatars/ada.png", job_title: "Staff Engineer" }}
+  anchorProps={{
+    href: "/releases/2.4.0",
+    onClick: (e) => router.push("/releases/2.4.0"),
+  }}
 />
 
-// Compact inline card (e.g., inside a chat message)
+// Compact inline card for chat surfaces
 <ProductReleaseCard
   size="sm"
-  title="OpenFrame 2.1.0"
-  version="2.1.0"
-  formattedDate="May 2026"
-  anchorProps={{ href: "/releases/2.1.0" }}
+  title="OpenFrame 2.4.0"
+  version="2.4.0"
+  formattedDate="Jun 12, 2025"
+  anchorProps={{ href: "/releases/2.4.0" }}
 />
 ```
 
-## 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.
+**Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/product-release-card.tsx)

package/src/components/shared/product-release/.product-releases-view.md

@@ -0,0 +1,49 @@
+<!-- source-hash: 12df6264efd81d55770e0ad3e4556641 -->
+Self-contained list view for product releases that handles fetching, filtering, pagination, and card rendering. Designed to be embedded with minimal configuration — the host provides an API endpoint and base path; all URL param reading, data fetching, and state management are handled internally.
+
+## Key Components
+
+### `ProductReleasesView` (default export)
+Main list surface. Reads search/status/page URL params written by the section chrome, fetches from the configured endpoint via `useSelfFetch`, and renders a stable slot-count layout to prevent height shifts during loading.
+
+### `ReleaseRow`
+Internal per-release component that isolates per-item hook calls (`useChatRuntime`, `useEntityCardLink`, `useRouter`) outside the parent `.map()` loop to comply with Rules of Hooks. Resolves the card's navigation href via `resolveContentHref` and delegates navigation to `executeNavigationImperative`.
+
+### `ProductReleaseCardExtras`
+Exported type describing the per-release prop bundle the `buildCardProps` callback must return — all `ProductReleaseCardProps` fields except those the view supplies directly (`title`, `summary`, `version`, `size`, `anchorProps`, `onClick`, `className`).
+
+## Usage Example
+
+```typescript
+// Minimal — uses all defaults (endpoint, basePath, rich card builder)
+<ProductReleasesView />
+
+// Custom endpoint + SSR hydration
+<ProductReleasesView
+  endpoint="/api/platform/releases"
+  initialData={serverFetchedData}
+  itemsPerPage={10}
+  basePath="/updates"
+/>
+
+// Custom card props builder
+<ProductReleasesView
+  buildCardProps={(release) => ({
+    formattedDate: formatDate(release.released_at),
+    releaseType: release.type,
+  })}
+/>
+```
+
+## Configuration
+
+| Prop | Default | Description |
+|---|---|---|
+| `endpoint` | `/api/releases` | GET endpoint; view appends `limit`, `offset`, `search`, `release_status` |
+| `initialData` | — | SSR hydration payload; skips initial client fetch |
+| `itemsPerPage` | `5` | Fixed slot count for stable layout |
+| `basePath` | `/releases` | Fallback href prefix when `composeContentUrl` is not wired |
+| `buildCardProps` | `buildProductReleaseCardProps` | Derive per-card metadata from a release object |
+| `searchParamKey` | `'search'` | Must match the URL param written by the section chrome |
+| `statusParamKey` | `'release_status'` | Status filter URL param key |
+| `pageParamKey` | `'page'` | Pagination URL param key |