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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.481",
+  "version": "0.0.482",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -120,6 +120,12 @@
       "require": "./dist/components/features/mux-origins.cjs",
       "default": "./dist/components/features/mux-origins.js"
     },
+    "./components/features/captions-url": {
+      "types": "./dist/components/features/captions-url.d.ts",
+      "import": "./dist/components/features/captions-url.js",
+      "require": "./dist/components/features/captions-url.cjs",
+      "default": "./dist/components/features/captions-url.js"
+    },
     "./components/features/video-bites-shared": {
       "types": "./dist/components/features/video-bites-shared.d.ts",
       "import": "./dist/components/features/video-bites-shared.js",
@@ -367,7 +373,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.4",
-    "@hookform/resolvers": "^5.4.0",
+    "@hookform/resolvers": "~5.2.2",
     "@storybook/nextjs-vite": "^10.1.11",
     "@svgr/cli": "^8.1.0",
     "@testing-library/jest-dom": "^6.9.1",

package/src/.index.md

@@ -1,43 +1,50 @@
-<!-- source-hash: d4303f00cc142a2cc9865685967f362b -->
-Main export barrel file for the `@flamingo/ui-kit` package, aggregating and re-exporting all components, hooks, utilities, types, and assets from the library.
+<!-- source-hash: 862fd90b3a9c67e41d15d6c3cc9b05fe -->
+The main barrel export file for the `@flamingo/ui-kit` package, re-exporting all public components, hooks, utilities, and types from their respective submodules into a single entry point.
 
 ## Key Components
 
-| Export | Source | Description |
-|--------|--------|-------------|
-| `ui` | `./components/ui` | Base UI primitives (buttons, inputs, modals, etc.) |
-| `features` | `./components/features` | Feature-specific composite components |
-| `icons` | `./components/icons` | Icon set components |
-| `navigation` | `./components/navigation` | Navigation components (sidebars, menus, breadcrumbs) |
-| `platform` | `./components/platform` | Platform-level layout components |
-| `chat` | `./components/chat` | Chat/messaging UI components (Mingo AI, Fae) |
-| `onboarding` | `./components/shared/onboarding` | Onboarding flow components |
-| `LogsList` | `./components/logs-list` | Renders a list of log entries |
-| `LogSeverityDot` | `./components/log-severity-dot` | Visual severity indicator dot for logs |
-| `ToolIcon` | `./components/tool-icon` | Icon component for tool representations |
-| `logs.types` | `./types/logs.types` | TypeScript types for log data structures |
-| `hooks` | `./hooks` | Shared React hooks |
-| `utils` | `./utils` | Utility/helper functions |
-| `types` | `./types` | Global TypeScript type definitions |
-| `assets` | `./assets` | Static assets (images, SVGs, fonts) |
+**Component Exports**
+- `./components/ui` — Base UI primitives
+- `./components/features` — Feature-specific components
+- `./components/icons` — Icon set
+- `./components/navigation` — Navigation components
+- `./components/platform` — Platform-level components
+- `./components/chat` — Chat components and payload types
+- `./components/shared/onboarding` — Onboarding flow components
 
-## Usage Example
+**Named Component Exports**
+- `LogsList` — Renders a list of log entries
+- `LogSeverityDot` — Visual indicator for log severity levels
+- `ToolIcon` — Icon component for tool representations
 
-```typescript
-// Import UI primitives
-import { Button, Input, Modal } from '@flamingo/ui-kit'
+**Non-Component Exports**
+- `./hooks` — Shared React hooks
+- `./utils` — Utility functions
+- `./types` — CMS domain types (canonical source)
+- `./types/logs.types` — Log-specific type definitions
+- `./assets` — Static assets
 
-// Import chat components for Mingo AI / Fae
-import { ChatWindow, ChatMessage } from '@flamingo/ui-kit'
+**Disambiguation Block**
 
-// Import log components
-import { LogsList, LogSeverityDot } from '@flamingo/ui-kit'
+Explicit `export type` re-exports for CMS domain types that would otherwise be silently dropped by TypeScript (`TS2308`) due to naming conflicts with identically-named types in `./components/chat`. The following are explicitly resolved to their `./types` (CMS) origin:
 
-// Import types
-import type { LogEntry } from '@flamingo/ui-kit'
+`BlogAuthor`, `BlogCategory`, `BlogPost`, `BlogPostSummary`, `CaseStudy`, `CustomerInterview`, and related filter/response/config shapes.
 
-// Import hooks and utilities
-import { useTheme, formatDate } from '@flamingo/ui-kit'
+## Usage Example
+
+```typescript
+// Consuming the full kit from the barrel
+import {
+  LogsList,
+  LogSeverityDot,
+  ToolIcon,
+  type BlogPost,
+  type CaseStudy,
+  type CustomerInterview,
+} from '@flamingo/ui-kit'
+
+// Chat subpath still exposes its own payload variants
+import type { BlogPost as ChatBlogPost } from '@flamingo/ui-kit/components/chat'
 ```
 
-> This is a barrel file — import directly from `@flamingo/ui-kit` rather than from deep subpaths to ensure consistent access and tree-shaking compatibility.
+> **Note:** If you need the chat-specific payload variants of `BlogPost`, `CaseStudy`, etc., import them directly from the `@flamingo/ui-kit/components/chat` subpath rather than the root barrel to avoid ambiguity.

package/src/.platform-domains.md

@@ -0,0 +1,65 @@
+<!-- source-hash: 788b2f31d1bae5bb48d44855c468c228 -->
+Defines the single source of truth for all platform domain registrations and derives host resolution, cookie base-domain sets, URL normalization, and preview detection from one central registry table.
+
+## Key Components
+
+### Types & Registry
+
+- **`PlatformDomainKey`** — Union of `PlatformName` plus the forward-only `'openframe-dashboard'`
+- **`PlatformDomainEntry`** — Shape of each registry row: `key`, `defaultUrl`, `envVar`, optional `aliasHostnames`, optional `pseudo` flag
+- **`PLATFORM_DOMAINS`** — Readonly registry array; ordering is load-bearing (`flamingo` must precede `flamingo-teaser` and `universal`)
+
+### URL Resolution
+
+- **`getPlatformProductionUrl(platform)`** — Returns the effective URL: env override → `defaultUrl` → flamingo fallback; always scheme-safe
+- **`ensureScheme(url)`** — Normalizes bare-host or protocol-relative env overrides to `https://`; exported as the single owner of this rule
+- **`byKey(key)`** — Looks up a registry entry by platform key
+
+### Host Utilities
+
+- **`hostOf(value)`** — Parses a URL to its lowercase, port-stripped hostname; returns `null` on failure
+- **`expandWwwApex(host)`** — Expands a host to its `www.`/apex pair for reverse matching
+- **`toRegistrableBaseDomain(host)`** — Extracts the registrable base domain (e.g. `flamingo.run`)
+- **`getPlatformByHostname(hostname)`** — Reverse resolves a hostname to a platform key (first-wins, non-pseudo only)
+
+### Preview Detection
+
+- **`isPreviewEnv()`** — Checks `VERCEL_ENV === 'preview'`
+- **`isPreviewHost(hostname)`** — Checks for `*.vercel.app` suffix
+
+### Cookie SSO
+
+- **`getAllPlatformBaseDomains()`** — ⚠️ Non-pure. Returns the cross-subdomain SSO cookie domain set; branches on localhost, Vercel preview, and production
+
+## Usage Example
+
+```typescript
+import {
+  getPlatformProductionUrl,
+  getPlatformByHostname,
+  getAllPlatformBaseDomains,
+  ensureScheme,
+} from './platform-domains'
+
+// Resolve the effective URL for a platform (env override or default)
+const url = getPlatformProductionUrl('openframe')
+// → 'https://openframe.ai' (or NEXT_PUBLIC_OPENFRAME_URL if set)
+
+// Normalize a bare-host env override
+ensureScheme('hub.openframe.ai')
+// → 'https://hub.openframe.ai'
+
+// Reverse-resolve an incoming request hostname to a platform key
+getPlatformByHostname('www.openframe.ai')
+// → 'openframe'
+
+// Get all cookie base domains for cross-hub SSO (client-side only)
+getAllPlatformBaseDomains()
+// → ['.flamingo.run', 'flamingo.run', '.openframe.ai', 'openframe.ai', ...]
+```
+
+## Notes
+
+- **Edge-safe and pure** — no React, no Node builtins, no `server-only`; safe in middleware (`proxy.ts`), `'use client'` providers, and `server-only` modules simultaneously
+- **Compile-time guards** — `satisfies` checks enforce bidirectional consistency between `PLATFORM_DOMAINS` and `ENV_OVERRIDES`; a missing or stale env var fails the build
+- **Ordering invariant** — `flamingo` must appear before `flamingo-teaser` and `universal` in the registry; a module-load self-check enforces this at runtime

package/src/assets/.fae-avatar.md

@@ -0,0 +1,33 @@
+<!-- source-hash: 9af84fb2f937986a14b04c717b822451 -->
+Base64-encoded PNG data URI for Fae's avatar — the AI helpdesk agent's brand mark, self-contained for zero-asset-serving dependency.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `FAE_AVATAR_DATA_URI` | `string` | Base64 PNG data URI (160×160px, ~37 KB) representing Fae's avatar mark |
+
+## Usage Example
+
+```typescript
+import { FAE_AVATAR_DATA_URI } from './fae-avatar';
+
+// Use directly in an <img> tag — no CDN or host assets needed
+const avatar = document.createElement('img');
+avatar.src = FAE_AVATAR_DATA_URI;
+avatar.alt = 'Fae avatar';
+document.body.appendChild(avatar);
+
+// Or in React/Vue component props
+<AgentMark src={FAE_AVATAR_DATA_URI} alt="Fae" />
+```
+
+## Notes
+
+- **Self-contained**: The full PNG is inlined as a `data:image/png;base64,...` URI, so no external hosting or asset pipeline is required.
+- **Fae-specific**: Fae has no separate vector icon — this avatar IS the brand mark (see `AgentMark` component).
+- **Source spec**: 160×160 PNG, approximately 37 KB before base64 encoding.
+
+## Source
+
+[`fae-avatar.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/fae-avatar.ts)

package/src/assets/.index.md

@@ -1,20 +1,26 @@
-<!-- source-hash: 60869445354e1580c9ff2b1a134284dd -->
-A minimal assets module that provides a centralized export point for static assets like fonts and other resources, with platform utilities planned for future implementation.
+<!-- source-hash: 0b3ff07887f7e19514fd9f0b3902113d -->
+Barrel export file that aggregates and re-exports all assets from the `assets` module, including static resources and the Fae avatar component.
 
 ## Key Components
 
-- **`assets`** - A frozen empty object that serves as a placeholder for future asset exports
+- **`assets`** — An empty, frozen constant object (`as const`) serving as a namespace placeholder for future static assets (fonts, icons, etc.)
+- **`fae-avatar`** — Re-exports everything from the `./fae-avatar` module
 
 ## Usage Example
 
 ```typescript
-import { assets } from './index';
+import { assets, FaeAvatar } from '@openframe-oss-lib/assets';
 
-// Currently returns an empty object
-console.log(assets); // {}
+// Use re-exported Fae avatar
+<FaeAvatar size="md" />;
 
-// Future usage might look like:
-// const { fonts, images, icons } = assets;
+// Access the assets namespace (reserved for future use)
+console.log(assets); // {}
 ```
 
-This module follows a placeholder pattern, establishing the infrastructure for asset management while keeping the current implementation minimal. The `as const` assertion ensures type safety and immutability of the exported object structure.
+## Notes
+
+- The `assets` object is intentionally empty and typed `as const` — it acts as a stable, extensible namespace for future platform utilities and static assets (e.g., fonts, images).
+- All public exports from `./fae-avatar` are surfaced directly from this index, making it the single entry point for asset-related imports.
+
+**Source:** [`assets/index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/assets/index.ts)

package/src/components/.agent-mark.md

@@ -0,0 +1,31 @@
+<!-- source-hash: a03e06ae468a977ee1c26dabab767bac -->
+Renders the visual mark (glyph) for either the Mingo or Fae AI agent — the single source of truth for how each agent is visually represented. Mingo renders as a vector icon; Fae renders as an avatar image bundled as a base64 data URI so no host asset is required.
+
+## Key Components
+
+- **`AgentName`** — Union type `'fae' | 'mingo'` identifying supported agents.
+- **`AgentMarkProps`** — Props interface controlling which agent to render, sizing classes, and an optional Fae avatar source override.
+- **`AgentMark`** — Main component. Delegates to `MingoIcon` for Mingo and an `<img>` tag for Fae. Both branches are decorative (no accessible text).
+
+## Usage Example
+
+```typescript
+import { AgentMark } from '@flamingo-stack/openframe-oss-lib';
+
+// Render Mingo's vector mark at 20×20
+<AgentMark agent="mingo" className="w-5 h-5" />
+
+// Render Fae's bundled avatar at 20×20
+<AgentMark agent="fae" className="w-5 h-5" />
+
+// Override Fae's avatar with a hosted asset
+<AgentMark
+  agent="fae"
+  className="w-5 h-5"
+  faeAvatarSrc="https://cdn.example.com/fae-avatar.png"
+/>
+```
+
+> **Note:** `className` controls all sizing and positioning. The component renders only the glyph — wrapping, backgrounds, and layout are the caller's responsibility.
+
+**Source:** [`agent-mark.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/agent-mark.tsx)

package/src/components/.announcement-bar.md

@@ -1,42 +1,54 @@
-<!-- source-hash: pending-regeneration -->
-A dismissible platform announcement bar with DUAL MODE support: SSR-seeded (Next hosts) and client-only (bare React apps without SSR). Single-line 44px strip, contrast handled by scoping content with the ODS theme classes, event-driven freshness (no polling).
+<!-- source-hash: bce846e08704bc1bed6ac9dfbae8c900 -->
+Renders the platform-wide announcement bar in both SSR (Next.js) and client-only (Vite/CRA embed) modes, handling fetch, dismissal state, animations, and XSS-safe CTA navigation.
 
 ## Key Components
 
-| Export/Function | Description |
-|----------------|-------------|
-| `AnnouncementBar` | Main component — renders the bar or `null` when there is nothing to show |
-| `initialAnnouncement` prop | SSR mode seed (nullable): server resolved announcement + dismissal cookie; skips the mount fetch |
-| `previewMode` prop | Render-only (admin live preview): no fetch, inert dismiss, no storage side effects |
-
-## Modes
-
-- **SSR mode** (hub / any Next host): the server passes `initialAnnouncement` (already dismissal-filtered via the cookie helpers in `announcement-storage.ts`). The bar is in the first HTML byte — zero layout shift, no flash for dismissed users, zero mount fetch.
-- **Client-only mode** (Vite/CRA embeds, no SSR — the react-embedding-example structure): mount the bar PROP-LESS inside an EndpointsRuntime provider; `announcementsUrl` is a fixed suffix under the embedder's one content base (`${CONTENT}/announcements/active`). No provider → renders nothing, never fetches. Appearance animates in (grid `0fr -> 1fr`). Deliberately NO per-component URL or platform knobs: the platform is never sent as a parameter — each server returns its own announcement via `currentPlatform()`.
-
-## Behavior Notes
-
-- **No polling**: freshness is visibility-driven — `useSelfFetch`'s `revalidateOnVisibleAfterMs` refetches on tab refocus when held data is older than 60s. Idle tabs make zero requests.
-- **Dismissal**: cookie is the SSOT (`<platform>-announcement-dismissed=<id>`, id-match); localStorage is read-only legacy. Storage reads happen only in effects (hydration safety).
-- **Contrast**: the admin background's tone selects `.theme-light`/`.theme-dark` around the content; all colors resolve from the active ODS theme's Tier-1 primitives.
-- **Responsive**: single truncating line (description hidden < sm); CTA is desktop-only, the whole bar is the tap target on mobile.
-
-## Usage Examples
+### `AnnouncementBar` (default export)
+The primary component accepting these props (`AnnouncementBarProps`):
+
+| Prop | Type | Description |
+|---|---|---|
+| `initialAnnouncement` | `Announcement \| null \| undefined` | SSR-seeded announcement; omit for client-only self-fetch |
+| `previewMode` | `boolean` | Admin draft preview — disables fetch, storage, and dismiss |
+| `dismissible` | `boolean` | Whether the user can dismiss the bar |
+| `className` | `string` | Optional wrapper class |
+
+### Internal Utilities Used
+- **`useSelfFetch`** — visibility-driven revalidation (refocuses after 60s stale); no polling
+- **`useEndpointsRuntime`** — resolves `announcementsUrl`; absent provider = silent no-op
+- **`isAnnouncementDismissed` / `dismissAnnouncement`** — cookie-based dismissal SSOT
+- **`pickReadableTextColor`** — selects `theme-light` / `theme-dark` ODS scope from background color
+- **`EntityIcon`** — renders uploaded image URL or library glyph by name
+- **`AnnouncementBarView`** — pure presentational shell (44px strip, `text-h6`, compact CTA)
+
+## Usage Example
+
+```typescript
+// SSR mode (Next.js layout — zero flash, no CLS)
+import { AnnouncementBar } from '@openframe/ui';
+
+export default async function RootLayout({ children }) {
+  const announcement = await resolveAnnouncement(); // server-side
+  return (
+    <html>
+      <body>
+        <AnnouncementBar initialAnnouncement={announcement} />
+        {children}
+      </body>
+    </html>
+  );
+}
 
-```tsx
-// SSR mode (Next server component resolves the seed):
-<AnnouncementBar initialAnnouncement={announcementOrNull} />
+// Client-only mode (Vite / CRA embed — self-fetches from provider URL)
+import { AnnouncementBar, EndpointsRuntimeProvider } from '@openframe/ui';
 
-// Client-only mode (react-embedding-example structure): one content base,
-// endpoints built once, bar mounted prop-less inside the provider.
-const endpointsRuntime: EndpointsRuntime = {
-  announcementsUrl: `${CONTENT}/announcements/active`,
-  accessCode: { validateUrl: `${CONTENT}/validate-access-code`, consumeUrl: `${CONTENT}/consume-access-code` },
-  contactUrl: `${CONTENT}/contact`,
+function App() {
+  return (
+    <EndpointsRuntimeProvider announcementsUrl="/api/announcements">
+      <AnnouncementBar />
+    </EndpointsRuntimeProvider>
+  );
 }
-
-<EndpointsRuntimeContext.Provider value={endpointsRuntime}>
-  <AnnouncementBar />
-  <main>{/* app content */}</main>
-</EndpointsRuntimeContext.Provider>
 ```
+
+> **Design freeze notice:** The bar's visual spec (44px height, `text-h6`, 20/24px icon, compact CTA, ghost-icon dismiss) is owner-approved and must not be altered without explicit written sign-off. See [`ui/announcement-bar-view.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/ui/announcement-bar-view.tsx) for the full warning.

package/src/components/.calendar.md

@@ -1,11 +1,11 @@
-<!-- source-hash: f8ae158ddc696cfb68419e4860069278 -->
-A styled calendar component wrapping `react-day-picker`'s `DayPicker` with Flamingo/Tailwind design tokens and accessible navigation icons.
+<!-- source-hash: 7de87dc45992b08ca9f6ea49ee42b409 -->
+A styled calendar component wrapping `react-day-picker`'s `DayPicker` with Flamingo's design system tokens, Tailwind utility classes, and Lucide navigation icons.
 
 ## Key Components
 
-- **`Calendar`** — Main export; a thin wrapper around `DayPicker` that applies consistent Tailwind class names for layout, navigation, day cells, selected/range/today states, and outside-day visibility.
-- **`CalendarProps`** — Re-exported type alias for `React.ComponentProps<typeof DayPicker>`, allowing full passthrough of any `DayPicker` prop.
-- **`Chevron` override** — Replaces the default DayPicker navigation icon with `lucide-react`'s `ChevronLeft` at a fixed `h-4 w-4` size.
+- **`Calendar`** — Primary export; a configured `DayPicker` wrapper with pre-applied `classNames` for layout, selection states, range highlighting, and navigation
+- **`CalendarProps`** — Re-exported type alias for `React.ComponentProps<typeof DayPicker>`, allowing full passthrough of `react-day-picker` props
+- **Chevron navigation** — Uses `ChevronLeft` from `lucide-react` via the `components.Chevron` slot override
 
 ## Usage Example
 
@@ -14,31 +14,32 @@ import { Calendar } from "@/components/calendar"
 import { useState } from "react"
 
 export function DatePicker() {
-  const [selected, setSelected] = useState<Date>()
+  const [date, setDate] = useState<Date | undefined>(undefined)
 
   return (
     <Calendar
       mode="single"
-      selected={selected}
-      onSelect={setSelected}
-      showOutsideDays={false}
+      selected={date}
+      onSelect={setDate}
+      showOutsideDays={true}
     />
   )
 }
 ```
 
 ```typescript
-// Date range selection
+// Range selection example
 import { DateRange } from "react-day-picker"
 
-export function RangePicker() {
-  const [range, setRange] = useState<DateRange>()
+export function DateRangePicker() {
+  const [range, setRange] = useState<DateRange | undefined>(undefined)
 
   return (
     <Calendar
       mode="range"
       selected={range}
       onSelect={setRange}
+      numberOfMonths={2}
     />
   )
 }
@@ -46,6 +47,9 @@ export function RangePicker() {
 
 ## Notes
 
-- `showOutsideDays` defaults to `true`; pass `false` to hide days from adjacent months.
-- Custom `classNames` are merged via spread (`...classNames`), so individual slot styles can be overridden per instance.
-- The `Chevron` component override is cast with `as any` to satisfy DayPicker's internal component map typing.
+- `showOutsideDays` defaults to `true` — days from adjacent months are visible but styled with `text-muted-foreground`
+- All `classNames` props are merged via spread (`...classNames`), so individual class overrides are supported
+- Uses `buttonVariants` from the internal button primitive for consistent focus/hover states on nav and day cells
+- The `Chevron` component override uses `ChevronLeft` for both directions; swap to conditional `ChevronRight` if directional icons are needed
+
+**Source:** [`calendar.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/calendar.tsx)

package/src/components/.categories-cart.md

@@ -1,42 +1,46 @@
-<!-- source-hash: 7161864532df5559c1bd18aba5ddcb23 -->
-A clickable card component that displays a product/vendor category with its associated vendor icons, subcategory count, and product count, linking to a filtered vendor listing page.
+<!-- source-hash: 6da745f71200af5947581734733c0a33 -->
+A card component that renders a single vendor category with its associated vendor icons, subcategory count, and product count, linking to a filtered vendor listing page.
 
 ## Key Components
 
-- **`CategoriesCart`** — Main exported component accepting `RealCategoryCardProps`
-  - `category` — Category object with `slug`, `name`, and `description`
-  - `vendors` — Array of vendor objects to display as icons (default: `[]`)
-  - `vendorCount` — Total number of products in the category (default: `0`)
-  - `subcategoryCount` — Number of subcategories (default: `0`)
-  - `isLoading` — Toggles skeleton loading state (default: `false`)
-  - `className` — Optional additional CSS classes
-
-## Key Behaviors
-
-| State | Behavior |
-|-------|----------|
-| `isLoading: true` | Renders 20 animated pulse skeleton placeholders |
-| Vendors present | Renders `VendorIcon` components in grayscale/muted style |
-| No vendors | Renders 6 grey placeholder icon blocks |
-
-- Navigates to `/vendors?category={slug}` on click
-- Highlights border and arrow button in `#FFC008` (Flamingo yellow) on hover
-- Applies left/right gradient overlays to fade the vendor icon row
+**`CategoriesCart`** (`RealCategoryCardProps`) — Main exported component with props:
+- `category` — Category object with `slug`, `name`, and `description`
+- `vendors` — Array of vendor objects to display as icon thumbnails
+- `vendorCount` — Total product count displayed in the subtitle
+- `subcategoryCount` — Total subcategory count displayed in the subtitle
+- `isLoading` — Toggles animated skeleton placeholders for vendor icons
+- `className` — Optional additional CSS classes
 
 ## Usage Example
 
 ```typescript
 import { CategoriesCart } from './categories-cart';
 
+const category = {
+  slug: 'security',
+  name: 'Security',
+  description: 'Endpoint protection, SIEM, and threat detection tools.',
+};
+
 <CategoriesCart
-  category={{
-    slug: 'rmm-tools',
-    name: 'RMM Tools',
-    description: 'Remote monitoring and management platforms for MSPs.',
-  }}
-  vendors={[{ id: '1', name: 'NinjaRMM', logo: '/logos/ninja.png' }]}
-  vendorCount={12}
-  subcategoryCount={3}
+  category={category}
+  vendors={vendorList}
+  vendorCount={42}
+  subcategoryCount={8}
   isLoading={false}
 />
-```
+```
+
+## Rendering States
+
+| State | Behavior |
+|---|---|
+| `isLoading: true` | 20 pulsing skeleton rectangles replace vendor icons |
+| `vendors.length > 0` | Renders grayscale `VendorIcon` thumbnails in a scrollable row |
+| `vendors.length === 0` | 6 muted placeholder squares with inner icon stubs |
+
+Vendor icons are displayed inside a horizontally clipped row with left/right gradient fade overlays for a soft scroll-edge effect. The entire card is wrapped in a `Link` that navigates to `/vendors?category={slug}`.
+
+---
+
+**Source:** [`categories-cart.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/categories-cart.tsx)

package/src/components/.category-card.md

@@ -1,46 +1,46 @@
-<!-- source-hash: b7066469baad9b1425fac7c4d9d108dd -->
-A React card component that displays category information with icons, counts, and navigation functionality in a dark-themed layout. The component is designed for displaying product category overviews with visual hierarchy and interactive elements.
+<!-- source-hash: 0c73c0168a5cf11103870e0bcf2eb7ff -->
+A client-side React card component for displaying a product category with its metadata, icon grid, and a navigation button.
 
 ## Key Components
 
-- **CategoryCard**: Main component that renders a category information card
-- **CategoryCardProps**: TypeScript interface defining the component's props structure
-- **Icon display area**: Flexible grid that shows category-related icons with fallback placeholders
-- **Interactive button**: Navigation element with hover effects and accessibility features
+### `CategoryCard`
+
+A presentational card component that renders category information in a structured layout.
+
+**Props (`CategoryCardProps`):**
+
+| Prop | Type | Description |
+|---|---|---|
+| `name` | `string` | Category display name |
+| `description` | `string` | Short description text |
+| `categoryCount` | `number` | Number of subcategories |
+| `productCount` | `number` | Number of products in the category |
+| `icons` | `React.ReactNode[]` | Optional array of icon nodes; renders 10 skeleton placeholders if empty |
 
 ## Usage Example
 
 ```typescript
-import { CategoryCard } from './category-card';
-import { DatabaseIcon, ServerIcon, CloudIcon } from './icons';
-
-function CategoryGrid() {
-  const icons = [
-    <DatabaseIcon key="db" />,
-    <ServerIcon key="server" />,
-    <CloudIcon key="cloud" />
-  ];
+import { CategoryCard } from "./category-card";
+import { ServerIcon, DatabaseIcon } from "lucide-react";
 
+export default function Page() {
   return (
-    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
-      <CategoryCard
-        name="Data Management"
-        description="Comprehensive tools for database administration and data analytics"
-        categoryCount={5}
-        productCount={23}
-        icons={icons}
-      />
-      
-      {/* Card without custom icons - will show 10 placeholder icons */}
-      <CategoryCard
-        name="Security Tools"
-        description="Essential security and monitoring solutions"
-        categoryCount={3}
-        productCount={15}
-      />
-    </div>
+    <CategoryCard
+      name="Infrastructure"
+      description="Tools for managing servers, networking, and cloud resources."
+      categoryCount={5}
+      productCount={42}
+      icons={[<ServerIcon />, <DatabaseIcon />]}
+    />
   );
 }
 ```
 
-The component features a responsive design with dark theme styling, automatic icon fallbacks, and smooth hover transitions for enhanced user experience.
+## Notes
+
+- **Client Component** — marked with `"use client"` for React interactivity.
+- **Icon grid** — renders up to the provided icons; falls back to 10 skeleton placeholder slots when `icons` is empty or omitted.
+- **Navigation button** — includes an accessible `aria-label` using the category `name`; intended to trigger navigation to a category detail view (wire up an `onClick` or wrap in a link as needed).
+- Styled with OpenDS design tokens (`ods-*`) for consistent theming across the OpenFrame UI.
+
+**Source:** [`category-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/category-card.tsx)