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

package/src/components/chat/entity-cards/.investor-update-card.md

@@ -1,47 +1,58 @@
-<!-- source-hash: 756619c21c965403499e06eb7fef94fa -->
-Pure presentation component for rendering investor update cards in two density modes (`default` and `sm`), with no internal click logic — callers supply the resolved `href`.
+<!-- source-hash: a793a81d6d93872c90072ec1575fa676 -->
+Pure presentation component for displaying investor update entities across three density variants (`default`, `sm`, `portrait`), with no internal click logic — callers provide the resolved `href`.
 
 ## Key Components
 
-### `InvestorUpdateCard`
-Main card component. Renders differently based on the `size` prop:
-- **`default`** — delegates to `AdminContentCard` with image, title, summary, badges, and period meta
-- **`sm`** — compact horizontal layout using shared `COMPACT_CARD_*` utility classes
+| Export | Description |
+|---|---|
+| `InvestorUpdateCard` | Main card component rendering one of three layouts based on the `size` prop |
+| `InvestorUpdateCardSkeleton` | Loading placeholder matching the card's layout for `default`/`portrait` or `sm` density |
+| `InvestorUpdateCardProps` | Props interface defining the card's API |
 
-### `InvestorUpdateCardSkeleton`
-Loading placeholder matching the visual footprint of each density mode. Uses `animate-pulse` for the default size.
+**Size variants:**
 
-### `InvestorUpdateCardProps`
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `update` | `InvestorUpdate` | Entity data |
-| `href` | `string` | Resolved detail URL (caller-supplied) |
-| `target` | `'_blank'` | Optional new-tab behavior |
-| `placeholderUrl` | `string \| null` | OG fallback when `featured_image` is absent |
-| `size` | `'default' \| 'sm'` | Card density (defaults to `'default'`) |
+- **`default`** — Full card using `AdminContentCard` with cover image, title, summary, badge, and period meta
+- **`sm`** — Compact horizontal layout (`EntityPortraitCard`-style) with image slot, title, update number badge, period subtitle, and truncated summary
+- **`portrait`** — Rail/strip layout delegated to `EntityPortraitCard`, with optional content-type chip controlled by `showTypeBadge`
 
 ## Usage Example
 
 ```typescript
-// Default density — full card
+import { InvestorUpdateCard, InvestorUpdateCardSkeleton } from './investor-update-card'
+
+// Default density
 <InvestorUpdateCard
   update={investorUpdate}
-  href={`/investor-updates/${investorUpdate.slug}`}
-  placeholderUrl="/images/update-placeholder.png"
+  href="/updates/q3-2024"
+  size="default"
 />
 
-// Compact horizontal — e.g. inside a chat dispatch or sidebar list
+// Compact horizontal (e.g., list/feed rows)
 <InvestorUpdateCard
   update={investorUpdate}
-  href={`/investor-updates/${investorUpdate.slug}`}
+  href="/updates/q3-2024"
+  size="sm"
   target="_blank"
   rel="noopener noreferrer"
-  size="sm"
 />
 
-// Skeleton while data loads
+// Portrait rail (mixed-type content strips)
+<InvestorUpdateCard
+  update={investorUpdate}
+  href="/updates/q3-2024"
+  size="portrait"
+  showTypeBadge={true}
+/>
+
+// Loading state
 <InvestorUpdateCardSkeleton size="sm" />
 ```
 
-> **Design note:** The component intentionally owns zero click/navigation logic. Tab behavior (`target="_blank"`) is resolved externally (e.g. via `computeIsNewTab`) and passed in, keeping the component fully declarative.
+**Key behaviours:**
+- Falls back to a generated placeholder image via `useEntityCardPlaceholder` when `featured_image` is absent; aspect ratio is `square` for `sm`, `wide` otherwise
+- Tab target and `rel` are resolved by `useEntityCardLink`, supporting cross-platform dispatch via `targetPlatform`
+- Image `onError` hides broken images gracefully in the `sm` variant
+
+## Source
+
+[`investor-update-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/investor-update-card.tsx)

package/src/components/chat/entity-cards/.onboarding-guide-card.md

@@ -1,58 +1,49 @@
-<!-- source-hash: ecac941a52e178236e11d54fe42337ec -->
-Pure presentation component that renders an onboarding guide card in three layout variants — `catalog`, `default`, and `sm` — plus matching skeleton states for loading UI.
+<!-- source-hash: a2963272b94148f7415e5c66d6d9d7b8 -->
+Renders an onboarding guide entity card in four layout variants (`catalog`, `default`, `sm`, `portrait`), with runtime-derived link attributes and placeholder images sourced from `ChatRuntime` via hub-wired hooks.
 
 ## Key Components
 
 ### `OnboardingGuideCard`
-Main card component. Stateless and click-logic-free; the caller wraps with navigation and provides the resolved `href`.
+Main export. Renders one of four variants based on the `size` prop:
+- **`catalog`** — Rich detail card with hero image, title, summary, duration badge, and `EntityAuthorCard` author/section grid.
+- **`default`** — Horizontal step-numbered card for "More in section" rails.
+- **`sm`** — Compact horizontal card for inline chat rendering.
+- **`portrait`** — Delegates to `EntityPortraitCard` for strip/rail density layouts.
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `guide` | `OnboardingGuide` | Guide entity data |
-| `href` | `string` | Detail URL resolved by caller |
-| `target` | `'_blank'` | Optional new-tab behavior |
-| `size` | `'catalog' \| 'default' \| 'sm'` | Layout variant (default: `'default'`) |
-| `placeholderUrl` | `string \| null` | OG fallback image for catalog/sm |
-| `className` | `string` | Additional CSS classes |
+Link `target`/`rel` are resolved via `useEntityCardLink`; placeholder images via `useEntityCardPlaceholder`. Explicit props always override runtime values.
 
 ### `OnboardingGuideCardSkeleton`
-Loading placeholder that mirrors each layout variant's structure with animated pulse states.
+Loading placeholder matching the layout of each `size` variant. Supports `catalog`, `default`, and `sm`.
 
-### `HORIZONTAL_SIZE_TOKENS`
-Internal token map for spacing/typography in the `default` variant.
-
-## Variants
+### `stripMarkdownPreview(text)`
+Internal utility. Strips raw markdown syntax (fenced code blocks, headings, links, bold/italic markers) from guide summaries before rendering as prose. Hard-caps output at 240 characters to prevent CSS `line-clamp` failures from dumping full guide content into the card.
 
-| Variant | Layout | Use Case |
-|---------|--------|----------|
-| `catalog` | Hero image + author grid | Public catalog page |
-| `default` | Horizontal step-numbered | "More in section" rail |
-| `sm` | Compact horizontal | Chat-inline rendering |
+### `HORIZONTAL_SIZE_TOKENS`
+Frozen design-token map scoping padding, icon sizing, and typography to the `default` variant.
 
 ## Usage Example
 
 ```typescript
 import { OnboardingGuideCard, OnboardingGuideCardSkeleton } from './onboarding-guide-card'
 
-// Loading state
-if (isLoading) {
-  return <OnboardingGuideCardSkeleton size="catalog" />
-}
-
-// Catalog variant (public listing)
+// Catalog variant (public guide listing page)
 <OnboardingGuideCard
   guide={guide}
   href={`/guides/${guide.slug}`}
   size="catalog"
-  placeholderUrl={ogImageUrl}
+  showTypeBadge={false}
 />
 
-// Chat inline (sm variant, new tab)
+// Compact inline variant (chat message)
 <OnboardingGuideCard
   guide={guide}
   href={`/guides/${guide.slug}`}
   size="sm"
   target="_blank"
   rel="noopener noreferrer"
+  placeholderUrl="https://api.example.com/og-placeholder.png"
 />
+
+// Loading state
+<OnboardingGuideCardSkeleton size="catalog" />
 ```

package/src/components/chat/entity-cards/.product-release-card-defaults.md

@@ -1,31 +1,38 @@
-<!-- source-hash: 192500e77aad1a0a4024a9e7d8dfcfec -->
-Provides the lib-side default implementation of `buildProductReleaseCardProps` for chat dispatch, satisfying the three fields required by the compact (`size='sm'`) `<ProductReleaseCard>` variant without requiring hub-side extras.
+<!-- source-hash: 29cc203019f2ef9b57297e18679a37af -->
+Provides lib-side default prop builders for `<ProductReleaseCard>`, covering both the compact `sm` (chat dispatch) and full `lg` (catalog page) card variants without requiring embedder-supplied extras.
 
 ## Key Components
 
 ### Interfaces
-- **`ReleaseLike`** — Loosely typed shape for raw API row data, covering image URLs, video URLs, and release date fields
-- **`DerivedSmProps`** — Output shape containing only the three sm-relevant props: `coverImage`, `hasVideoCover`, and `formattedDate`
+
+- **`ReleaseLike`** — Minimal shape for `sm` builder; covers image/video thumbnail and date fields
+- **`RichReleaseLike`** — Extended shape for `lg` builder; adds `release_type`, `release_status`, `view_count`, `author`, and changelog arrays
+- **`DerivedSmProps`** — Output type for the compact builder (`coverImage`, `hasVideoCover`, `formattedDate`)
+- **`ProductReleaseCardDerivedProps`** — Full output type for the rich builder, including badge color, author, view count, and changelog counts
 
 ### Functions
-- **`pickCover(item)`** — Resolves the best cover image URL by mirroring the hub's `resolveReleaseCover` precedence: video thumbnails take priority when a video is set, falling back to `featured_image` then `og_image_url`
-- **`defaultBuildProductReleaseCardProps(item)`** — Main export; builds the `DerivedSmProps` bundle from an unknown API row, using `formatReleaseDate` for TZ-safe date formatting
+
+- **`pickCover(item)`** *(internal)* — Selects the best cover image URL using a simplified sm-specific heuristic: prefers video thumbnails when a video URL is present, otherwise falls back to `featured_image` or `og_image_url`
+- **`defaultBuildProductReleaseCardProps(item)`** — Lightweight builder for chat-dispatch `sm` cards; satisfies only the three fields the compact variant reads
+- **`buildProductReleaseCardProps(item)`** — Rich `lg`-variant builder and the **default** for `<ProductReleasesView>`; populates the full metadata grid using `resolveReleaseCover` and `releaseTypeToBadgeColor`
 
 ## Usage Example
 
 ```typescript
-import { defaultBuildProductReleaseCardProps } from './product-release-card-defaults'
-
-// Used as fallback when opts.extras.buildProductReleaseCardProps is not supplied
-const props = defaultBuildProductReleaseCardProps(apiRow)
-// → { coverImage: 'https://...', hasVideoCover: true, formattedDate: 'Jan 15, 2025' }
-
-// Hub-side embedders override with their richer builder via extras:
-const cardProps = (opts.extras?.buildProductReleaseCardProps ?? defaultBuildProductReleaseCardProps)(row)
+import {
+  defaultBuildProductReleaseCardProps,
+  buildProductReleaseCardProps,
+} from './product-release-card-defaults'
+
+// Compact sm card (chat dispatch — no extras needed)
+const smProps = defaultBuildProductReleaseCardProps(releaseRow)
+// → { coverImage, hasVideoCover, formattedDate }
+
+// Full lg card (ProductReleasesView default)
+const lgProps = buildProductReleaseCardProps(releaseRow)
+// → { coverImage, hasVideoCover, formattedDate, releaseType,
+//     releaseStatus, releaseTypeBadgeColor, viewCount,
+//     author, changelogCounts }
 ```
 
-## Notes
-
-- Uses `formatReleaseDate` (not `new Date().toLocaleDateString`) to avoid UTC off-by-one day shifts on date-only `YYYY-MM-DD` strings
-- Produces an empty string for `formattedDate` when `release_date` is absent, rather than throwing
-- lg-only fields (`changelogCounts`, badge color, view count) are intentionally omitted — hub embedders supply those via `extras`
+> Hub-side embedders can override the default by passing a richer builder via `opts.extras.buildProductReleaseCardProps`. The `sm` builder intentionally diverges from `resolveReleaseCover` to avoid pulling hub-only dependencies into the lib bundle.

package/src/components/chat/entity-cards/.program-card.md

@@ -1,59 +1,56 @@
-<!-- source-hash: 882a2c614fa33ecfd7b3ef948ea40a94 -->
-Brief overview of the `program-card.tsx` component — a pure presentational card for displaying podcasts, webinars, and events with two density modes.
+<!-- source-hash: d98ea9bb6ec08d6a08478099793fa07d -->
+Presentation-only card component for programs (podcasts, webinars, events) supporting three density modes: `default`, `sm` (compact), and `portrait` (vertical rail).
 
 ## Key Components
 
 ### Exports
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ProgramCardSkeleton` | Component | Loading placeholder supporting `default` and `sm` sizes |
-| `ProgramCard<T>` | Generic Component | Main card component, typed against `BaseProgramItem` |
-| `ProgramCardProps<T>` | Interface | Props contract for `ProgramCard` |
+- **`ProgramCard<T>`** — Generic card component accepting any `BaseProgramItem` subtype; delegates to density-specific render branches
+- **`ProgramCardSkeleton`** — Animated loading placeholder matching `default` or `sm` layout
+- **`ProgramCardProps<T>`** — Interface defining all card inputs
 
-### Internal Helpers
+### Internal Utilities
 
-- **`getHosts()`** — Normalizes host data from either a typed array or a JSON string
-- **`MediaGallery`** — Scrollable thumbnail strip with `ImageGalleryModal` lightbox integration
+- **`formatUtc(date, fmt)`** — UTC-pinned `date-fns` formatter that prevents React #418 hydration mismatches between server (UTC) and client (local) timezones
+- **`getHosts(hosts)`** — Normalizes `ProgramHost[]` or raw JSON string into `{ name, avatar }[]`
+- **`MediaGallery`** — Horizontally scrollable thumbnail strip with `ImageGalleryModal` lightbox on click
 
-### Card Sizes (`CardSize`)
+### Density Modes
 
 | Size | Layout | Use Case |
-|------|--------|----------|
-| `default` | Vertical, full detail | Standalone page/feed cards |
-| `sm` | Compact horizontal | Chat-inline embeds |
-
-### Type-Aware Metadata
-
-The card adapts displayed metadata based on `config.type`:
-
-- **`podcast`** → Duration via `formatDurationCompact`
-- **`event`** → Location name
-- **`webinar`** → Start time + duration via `formatTimeWithTimezone` / `formatDurationFromRange`
+|---|---|---|
+| `default` | Wide horizontal with full detail | Archive/listing pages |
+| `sm` | Compact horizontal row | Chat-inline cards |
+| `portrait` | Vertical via `EntityPortraitCard` | Mixed-content rails |
 
 ## Usage Example
 
 ```typescript
-import { ProgramCard } from './program-card'
+import { ProgramCard, ProgramCardSkeleton } from './program-card'
+import { podcastConfig } from '../config/podcast-config'
+
+// Loading state
+if (isLoading) return <ProgramCardSkeleton size="sm" />
 
-// Default (vertical) layout
+// Default density
 <ProgramCard
-  config={{ type: 'podcast', labels: { singular: 'Episode' } }}
+  config={podcastConfig}
   item={episode}
-  href="/podcasts/ep-42"
+  media={episode.media}
+  href={`/podcasts/${episode.slug}`}
   size="default"
 />
 
-// Compact inline variant (e.g., inside chat)
+// Portrait for mixed-content rail
 <ProgramCard
-  config={{ type: 'webinar', labels: { singular: 'Webinar' } }}
-  item={webinarItem}
-  href="https://external.com/webinar"
+  config={webinarConfig}
+  item={webinar}
+  href={`/webinars/${webinar.slug}`}
+  size="portrait"
+  showTypeBadge={true}
   target="_blank"
   rel="noopener noreferrer"
-  size="sm"
-  placeholderUrl="https://cdn.example.com/og-fallback.png"
 />
 ```
 
-> **Note:** `ProgramCard` is purely presentational — it owns no navigation logic. Callers are responsible for computing and passing `href` and `target`.
+> The card writes no click logic — callers wrap or pass `href` directly. Use `target="_blank"` with `rel="noopener noreferrer"` for cross-platform or embed contexts.

package/src/components/chat/entity-cards/.roadmap-card.md

@@ -1,46 +1,55 @@
-<!-- source-hash: 853672c07dc2c32f2542a936a393a3ad -->
-Pure presentation component for roadmap items with two density modes — a rich default card (vote buttons, Figma/screenshot controls) and a compact horizontal variant for inline chat display.
+<!-- source-hash: 7154e56664d4c339b92c30b7f464bd80 -->
+Pure presentation component for roadmap feature items, supporting two layout densities: a rich `default` card (with vote buttons, Figma links, and screenshot gallery) and a compact `sm` card for inline chat display.
 
 ## Key Components
 
-| Export | Description |
-|--------|-------------|
-| `RoadmapCard` | Main card component, renders either `default` or `sm` layout |
-| `RoadmapCardSkeleton` | Loading placeholder matching both card densities |
-| `VoteType` | Union type `'up' \| 'down' \| null` for vote state |
-| `RoadmapCardProps` | Full props interface for the card |
+### `RoadmapCard`
+Main export. Renders either the full roadmap page card or a compact horizontal card based on the `size` prop.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `item` | `RoadmapItem` | Roadmap item data (title, status, description, votes, etc.) |
+| `size` | `'default' \| 'sm'` | Layout density |
+| `href` | `string` | Navigation URL (compact branch only) |
+| `target` | `'_blank'` | Opens in new tab when set |
+| `userVote` | `VoteType` | Current user's vote (`'up'`, `'down'`, or `null`) |
+| `onVote` | `(type) => void` | Vote handler (default size only) |
+| `isVoting` | `boolean` | Disables vote buttons during pending request |
+| `id` | `string` | DOM id for `useScrollToHash` deep-linking (e.g. `roadmap-<external_id>`) |
+
+### `RoadmapCardSkeleton`
+Loading placeholder that mirrors the layout of either size variant using animated pulse placeholders.
+
+### `VoteType`
+```typescript
+export type VoteType = 'up' | 'down' | null
+```
 
 ## Usage Example
 
 ```typescript
-// Default (full roadmap page card with vote controls)
+// Default rich card (roadmap page)
 <RoadmapCard
-  item={roadmapItem}
+  id={`roadmap-${item.externalId}`}
+  item={item}
+  size="default"
   userVote={currentVote}
   onVote={(type) => handleVote(item.id, type)}
-  isVoting={isPending}
+  isVoting={votingInFlight}
 />
 
-// Compact inline variant (chat/sidebar)
-<a href={`/roadmap/${item.id}`}>
-  <RoadmapCard
-    item={roadmapItem}
-    size="sm"
-    href={`/roadmap/${item.id}`}
-    cardType="delivery_item"
-    target="_blank"
-    rel="noopener noreferrer"
-  />
-</a>
-
-// Skeleton loader
+// Compact card (chat inline, wrapped by parent anchor)
+<RoadmapCard
+  item={item}
+  size="sm"
+  href={`/roadmap/${item.externalId}`}
+  target="_blank"
+  rel="noopener noreferrer"
+  cardType="roadmap_item"
+/>
+
+// Skeleton while loading
 <RoadmapCardSkeleton size="sm" />
 ```
 
-## Key Behaviors
-
-- **Icon resolution**: prefers `item.icon` (proxied), falls back to `TaskTypeIcon` for internal tasks, then initials
-- **`sm` branch**: wraps content in `<a>` when `href` is valid; renders a static `<span>` when no href is available
-- **Vote UI** (`default` only): rendered only when `onVote` is provided; buttons disabled during `isVoting`
-- **Screenshot gallery**: controlled via local `showScreenshots` state; Figma link and screenshot count displayed as metadata badges in the compact branch
-- **Responsive status badge**: shown inline on `md+` screens, moves below the header row on mobile
+> **Icon fallback order (compact branch):** `TaskTypeIcon` (internal tasks) → proxied logo image → 2-letter title abbreviation.

package/src/components/chat/entity-cards/.roadmap-vote-button.md

@@ -1,52 +1,49 @@
-<!-- source-hash: 69f5a0ba80b7e510b67573e50f546e85 -->
-A pure-presentational thumbs-up / thumbs-down vote button used within `RoadmapCard`'s default variant. Renders an icon with an optional vote count; all interaction logic is delegated to the parent via `onClick`.
+<!-- source-hash: 289ff1c6a5daf3110837897be5b2e698 -->
+A presentational thumbs-up/thumbs-down vote button component used within `RoadmapCard`'s default variant. Delegates all interaction logic to the parent via an `onClick` prop.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `RoadmapVoteButtonProps` | `interface` | Prop contract for the button |
-| `RoadmapVoteButton` | `function` | Styled outline button with thumb icon and count |
+### `RoadmapVoteButton`
 
-### Props
+The sole export — a styled `Button` wrapper that renders either a `ThumbsUpIcon` or `ThumbsDownIcon` based on `voteType`, with optional vote count display and active/disabled states.
+
+### `RoadmapVoteButtonProps`
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `voteType` | `'up' \| 'down'` | — | Selects `ThumbsUpIcon` or `ThumbsDownIcon` |
-| `count` | `number` | — | Vote tally displayed next to the icon |
-| `isActive` | `boolean` | — | Applies active background when the user has voted |
-| `onClick` | `() => void` | — | Click handler supplied by parent (e.g. `useRoadmapVoting`) |
-| `disabled` | `boolean` | `false` | Disables interaction and applies reduced opacity |
-| `showCount` | `boolean` | `true` | Toggles count label visibility |
-| `color` | `string` | — | Forwarded to the icon as a fill/stroke color |
-| `className` | `string` | — | Additional CSS classes merged via `cn()` |
+|---|---|---|---|
+| `voteType` | `'up' \| 'down'` | — | Determines which icon to render |
+| `count` | `number` | — | Vote count displayed alongside the icon |
+| `isActive` | `boolean` | — | Applies active background styling when the user has voted |
+| `onClick` | `() => void` | — | Click handler; typically wired from a `useRoadmapVoting` hook |
+| `disabled` | `boolean` | `false` | Prevents interaction and applies reduced opacity |
+| `showCount` | `boolean` | `true` | Toggles visibility of the vote count label |
+| `color` | `string` | — | Optional color override passed to the icon |
+| `className` | `string` | — | Additional classes merged via `cn()` |
 
 ## Usage Example
 
 ```typescript
 import { RoadmapVoteButton } from './roadmap-vote-button'
 
-function RoadmapCard() {
-  const { upvotes, hasVotedUp, handleVote } = useRoadmapVoting(itemId)
+function RoadmapCard({ item }) {
+  const { upvoteCount, hasUpvoted, handleUpvote } = useRoadmapVoting(item.id)
 
   return (
-    <div className="flex gap-2">
-      <RoadmapVoteButton
-        voteType="up"
-        count={upvotes}
-        isActive={hasVotedUp}
-        onClick={() => handleVote('up')}
-        color="#FFC008"
-      />
-      <RoadmapVoteButton
-        voteType="down"
-        count={0}
-        isActive={false}
-        onClick={() => handleVote('down')}
-        showCount={false}
-        disabled
-      />
-    </div>
+    <RoadmapVoteButton
+      voteType="up"
+      count={upvoteCount}
+      isActive={hasUpvoted}
+      onClick={handleUpvote}
+      disabled={!isAuthenticated}
+    />
   )
 }
-```
+```
+
+## Notes
+
+- Pure presentational component — no internal state or data fetching.
+- Active state (`isActive`) applies `bg-ods-border` styling to visually distinguish a cast vote.
+- Uses the `cn()` utility for conditional class merging; all ODS design tokens (`ods-bg`, `ods-border`) follow the OpenFrame Design System conventions.
+
+**Source:** [`roadmap-vote-button.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/roadmap-vote-button.tsx)

package/src/components/chat/entity-cards/.slack-message-card.md

@@ -1,48 +1,47 @@
-<!-- source-hash: 82997feaf6df9370cc3057cd02b01be6 -->
-Renders a visual card component for Slack message markers, supporting both `compact` and `row` display variants with optional anchor navigation and a loading skeleton state.
+<!-- source-hash: 39388beb5287597e62780b1e9b0cd15d -->
+Renders a visual card for Slack message markers in two layout variants (`compact` and `row`), with a matching skeleton loader for loading states. Pure presentation component — navigation behavior is injected externally via `anchorProps`.
 
 ## Key Components
 
-### `SlackMessageCard`
-Main card component that displays a Slack message entry with icon, title, preview text, channel name, and date. Rendering behavior varies by nav context:
-- Wraps in a caller-provided `<a>` via `anchorProps` if supplied
-- Falls back to a direct external `<a href>` if `item.url` is valid
-- Renders a static `<span>` when no link is available
-
-### `SlackMessageCardSkeleton`
-Animated placeholder matching the card layout for loading states. Accepts `variant` and `className` props.
-
-### `parseChannelFromUrl` *(internal)*
-Extracts the Slack channel ID from a Slack archive URL (`*.slack.com/archives/<channelId>/...`) as a fallback when `item.channel` is not set.
-
-### Interfaces
-
-| Interface | Purpose |
-|---|---|
-| `SlackMessageCardProps` | `item`, `variant`, `className`, `anchorProps` |
-| `SlackMessageCardAnchorProps` | Typed `<a>` prop bundle composed by the caller |
+| Export | Type | Description |
+|---|---|---|
+| `SlackMessageCard` | Component | Main card rendering a `SlackMessageItem` in `compact` (default) or `row` layout |
+| `SlackMessageCardSkeleton` | Component | Animated placeholder matching the card's layout during data fetching |
+| `SlackMessageCardProps` | Interface | Props for `SlackMessageCard`: `item`, `variant`, `className`, `anchorProps` |
+| `SlackMessageCardAnchorProps` | Interface | Anchor prop bundle (`href`, `target`, `rel`, `onClick`) composed by the caller |
+| `parseChannelFromUrl` | Helper (private) | Extracts the Slack channel ID from a `*.slack.com/archives/<channel>` URL |
 
 ## Usage Example
 
 ```typescript
 import { SlackMessageCard, SlackMessageCardSkeleton } from './slack-message-card'
+import type { SlackMessageItem } from '../types/entities/slack-message'
+
+const item: SlackMessageItem = {
+  title: 'Deployment alert',
+  preview: 'Production deploy succeeded at 14:32 UTC.',
+  url: 'https://myteam.slack.com/archives/C01AB2CD3EF/p1234567890',
+  channel: null,
+  dateUpdated: '2024-06-01T14:32:00Z',
+}
 
-// Compact card with caller-controlled navigation
+// Compact card with external navigation
+<SlackMessageCard item={item} />
+
+// Compact card with caller-controlled navigation (e.g. SPA router)
 <SlackMessageCard
-  item={slackMessageItem}
-  variant="compact"
+  item={item}
   anchorProps={{
-    href: '/messages/123',
-    onClick: (e) => handleNavigate(e),
+    href: '/messages/42',
+    onClick: (e) => { e.preventDefault(); router.push('/messages/42') },
   }}
 />
 
-// Inline row variant (e.g. inside a list or table)
-<SlackMessageCard
-  item={slackMessageItem}
-  variant="row"
-/>
+// Inline row layout (e.g. inside a list or table)
+<SlackMessageCard item={item} variant="row" />
 
-// Skeleton while loading
+// Loading state
 <SlackMessageCardSkeleton variant="compact" />
-```
+```
+
+**Anchor resolution priority:** `anchorProps` → `item.url` (opens `_blank`) → static `<span>` when no URL is available.

package/src/components/chat/entity-cards/.use-cover-image-fallback.md

@@ -0,0 +1,47 @@
+<!-- source-hash: f3c02d66e41de5152b76a04f3d0f2e14 -->
+Manages a two-step cover image fallback chain for entity cards: real cover URL → branded placeholder URL → `null` (hide the media element).
+
+## Key Components
+
+### `useCoverImageFallback(imageUrl?, placeholderUrl?)`
+Primary hook implementing the fallback chain. Tracks failed URLs in a `Set` so derived `src` re-resolves instantly on prop changes without reset effects or retry loops.
+
+**Returns `CoverImageFallback`:**
+
+| Field | Type | Description |
+|---|---|---|
+| `src` | `string \| null` | First non-failed URL from `[imageUrl, placeholderUrl]`, or `null` |
+| `onError` | `() => void` | Wire directly to the media element's `onError` handler |
+
+### `hideOnError`
+Standalone event handler for compact image slots with no placeholder chain. Sets `display: none` on the broken image element, leaving the slot background visible.
+
+## Usage Example
+
+```typescript
+import { useCoverImageFallback, hideOnError } from './use-cover-image-fallback'
+
+// Full fallback chain (cover → placeholder → hide slot)
+function EntityCard({ coverUrl, placeholderUrl }) {
+  const { src, onError } = useCoverImageFallback(coverUrl, placeholderUrl)
+
+  if (!src) return <div className="empty-media-slot" />
+
+  return <img src={src} onError={onError} alt="Cover" />
+}
+
+// Compact card — no placeholder, just hide on break
+function CompactCard({ coverUrl }) {
+  return <img src={coverUrl} onError={hideOnError} alt="Cover" />
+}
+```
+
+## Design Notes
+
+- **No retry loops:** failed URLs are stored in a `Set`; once marked failed they are skipped permanently for the component's lifetime.
+- **Prop-change safe:** `src` is fully derived — passing a new `coverUrl` re-resolves immediately with no `useEffect` reset needed.
+- **Centralised logic:** replaces per-card `imageError` state and `displayImage` ternaries that previously drifted across `BlogCard` and `EntityPortraitCard`.
+
+## Source
+
+[`use-cover-image-fallback.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-cover-image-fallback.ts)