@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214

package/src/components/ui/table/.table-header.md

@@ -1,58 +1,43 @@
-<!-- source-hash: 133fe6659099063e781ba4018f01dd3f -->
-A responsive table header component that provides sorting, filtering, and selection functionality for data tables in the Flamingo platform.
+<!-- source-hash: 3fe84f90a3dc18cad93f45db6906a477 -->
+Renders the header row for a legacy table component, handling column labels, sorting indicators, filtering dropdowns, selection checkboxes, and responsive visibility.
 
 ## Key Components
 
-- **TableHeader**: Generic table header component with support for:
-  - Column sorting with visual indicators (arrow icons)
-  - Column filtering with dropdown interface
-  - Row selection with checkbox controls
-  - Responsive visibility controls for mobile/desktop
-  - Customizable column alignment and widths
+- **`TableHeader<T>`** *(deprecated)* — Main exported component. Use `DataTableHeader` from `data-table` instead.
+- **`getAlignment`** — Maps column `align` prop to Tailwind flex-justification classes.
+- **`handleSort`** — Toggles sort direction and calls `onSort` for sortable columns.
+- **`getSortIcon`** — Returns the appropriate sort icon (`Arrow01UpIcon`, `Arrow01DownIcon`, or `SwitchVrIcon`) based on active sort state.
 
 ## Usage Example
 
 ```typescript
 import { TableHeader } from './table-header'
-import type { TableColumn } from './types'
-
-interface User {
-  id: string
-  name: string
-  email: string
-  status: 'active' | 'inactive'
-}
-
-const columns: TableColumn<User>[] = [
-  {
-    key: 'name',
-    label: 'Name',
-    sortable: true,
-    align: 'left'
-  },
-  {
-    key: 'status',
-    label: 'Status', 
-    filterable: true,
-    filterOptions: [
-      { label: 'Active', value: 'active' },
-      { label: 'Inactive', value: 'inactive' }
-    ]
-  }
+
+const columns = [
+  { key: 'name', label: 'Name', sortable: true },
+  { key: 'status', label: 'Status', filterable: true, filterOptions: ['Active', 'Inactive'] },
+  { key: '__actions__', label: '' },
 ]
 
 <TableHeader
   columns={columns}
   sortBy="name"
   sortDirection="asc"
-  onSort={(key, direction) => handleSort(key, direction)}
-  filters={{ status: ['active'] }}
-  onFilterChange={handleFilterChange}
-  selectable={true}
+  onSort={(key, direction) => console.log(key, direction)}
+  filters={{}}
+  onFilterChange={(key, value) => console.log(key, value)}
+  selectable
   allSelected={false}
-  onSelectAll={handleSelectAll}
-  totalItemsCount={50}
+  someSelected={true}
+  onSelectAll={(checked) => console.log(checked)}
+  totalItemsCount={42}
+  stickyHeader
+  stickyHeaderOffset="top-16"
 />
 ```
 
-The component automatically handles responsive breakpoints, hiding non-essential columns on mobile while preserving actions and filterable columns. Sort icons change color and direction based on active state, and filter icons highlight when filters are applied.
+## Notes
+
+- Hidden on mobile (`hidden md:flex`); on non-`lg` screens, only filterable and `__actions__` columns are rendered.
+- The `__actions__` column slot displays a `"Showing N results"` count instead of a header label.
+- Sticky header behavior is controlled via `stickyHeader` and `stickyHeaderOffset` props.

package/src/components/ui/table/.table-row.md

@@ -1,52 +1,34 @@
-<!-- source-hash: a73b42b79cbaa5f35b28a433f5d412d4 -->
-A React component that renders a single row in a data table with support for selection, click handling, and dynamic column rendering.
+<!-- source-hash: fc61b63b86b6a05d8f7ae1ddcc0dba93 -->
+A deprecated table row component that renders a single row in a tabular layout, supporting click handlers, link navigation, row selection, and dynamic cell rendering with nested property access.
 
 ## Key Components
 
-- **TableRow**: Generic React component that renders table row data
-- **handleRowClick**: Click handler that respects `data-no-row-click` elements
-- **handleSelect**: Selection handler for checkbox interactions
-- **getCellValue**: Utility function that extracts and formats cell values with dot notation support
+- **`TableRow<T>`** — Generic row component accepting typed `item` data, column definitions, and interaction callbacks. Marked `@deprecated` — use `DataTableRow` from `data-table` instead.
+- **`handleRowClick`** — Click handler that respects `[data-no-row-click]` elements (e.g., checkboxes), preventing event propagation to row-level handlers.
+- **`getCellValue`** — Resolves cell content via `column.renderCell` or dot-notation key traversal (e.g., `"user.address.city"`), with fallbacks for `null`, `boolean`, and `object` values.
+- **Link mode** — When `href` is provided without `onClick`, renders an absolutely-positioned `<Link>` overlay for full-row navigation while keeping inner elements pointer-event-safe.
 
 ## Usage Example
 
 ```typescript
-import { TableRow } from './table-row'
-
-// Define your data structure
-interface User {
-  id: string
-  name: string
-  email: string
-  profile: {
-    role: string
-  }
-}
-
-// Configure columns
-const columns = [
-  { key: 'name', label: 'Name' },
-  { key: 'email', label: 'Email' },
-  { key: 'profile.role', label: 'Role' }, // Nested property access
-  {
-    key: 'actions',
-    label: 'Actions',
-    renderCell: (user: User) => (
-      <button data-no-row-click>Edit</button>
-    )
-  }
-]
-
-// Render table row
 <TableRow
-  item={userData}
-  columns={columns}
-  selectable={true}
-  selected={isSelected}
-  onSelect={handleUserSelect}
-  onClick={handleRowClick}
+  item={user}
   index={0}
+  columns={[
+    { key: 'name', label: 'Name' },
+    { key: 'address.city', label: 'City' },
+    {
+      key: 'status',
+      label: 'Status',
+      renderCell: (item) => <StatusBadge status={item.status} />
+    }
+  ]}
+  href={`/users/${user.id}`}
+  selectable
+  selected={selectedIds.has(user.id)}
+  onSelect={(item) => toggleSelection(item.id)}
+  compact={false}
 />
 ```
 
-The component supports nested property access via dot notation, custom cell rendering, row selection with checkboxes, and prevents row click events on elements marked with `data-no-row-click`.
+> **Deprecation notice:** This component is superseded by `DataTableRow` from the `data-table` package, which provides improved composability and feature support.

package/src/components/ui/table/.table-skeleton.md

@@ -1,38 +1,45 @@
-<!-- source-hash: c46a2ed35fe7c12aad3938a7ad67c369 -->
-A skeleton loading component for table cards that provides responsive placeholder animations while data is being fetched, maintaining consistent row heights across desktop and mobile layouts.
+<!-- source-hash: 1ccd2771fe5f338fc464bca5ddb0e198 -->
+Renders animated loading skeleton rows for table/card layouts with responsive desktop and mobile variants.
 
 ## Key Components
 
-- **TableCardSkeleton** - Main skeleton component that renders animated placeholder rows
-- **ROW_HEIGHT_DESKTOP/MOBILE** - Exported height constants using CSS clamp for responsive sizing
-- **TableCardSkeletonProps** - TypeScript interface defining component props (imported from types)
+- **`TableCardSkeleton`** *(deprecated)* — Main exported component. Renders `n` pulsing skeleton rows with configurable columns, optional action buttons, and optional chevron indicators. Use `DataTableSkeleton` from `data-table` instead.
+- **`ROW_HEIGHT_DESKTOP`** *(deprecated)* — Tailwind height class `h-[68px] md:h-[80px]` for desktop rows.
+- **`ROW_HEIGHT_MOBILE`** *(deprecated)* — Tailwind height class `h-[68px]` for mobile rows.
 
-The component uses CSS `clamp()` functions to ensure consistent responsive row heights:
-- Desktop: 72px minimum, 5vw preferred, 88px maximum
-- Mobile: 72px minimum, 18vw preferred, 96px maximum
+## Props (`TableCardSkeletonProps`)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `Column[]` | required | Column definitions with `key` and optional `width` |
+| `rows` | `number` | `10` | Number of skeleton rows to render |
+| `hasActions` | `boolean` | `false` | Show action button placeholders |
+| `hasChevron` | `boolean` | `false` | Show chevron placeholder |
+| `className` | `string` | — | Extra classes on each row wrapper |
+| `rowClassName` | `string` | — | Extra classes on the inner row layout |
 
 ## Usage Example
 
 ```typescript
 import { TableCardSkeleton } from './table-skeleton'
 
-// Basic usage with column definitions
-<TableCardSkeleton
-  columns={[
-    { key: 'name', width: 'w-48' },
-    { key: 'status', width: 'w-32' },
-    { key: 'date' } // flex-1 width
-  ]}
-  rows={5}
-  hasActions={true}
-  className="mb-4"
-/>
-
-// Minimal usage
-<TableCardSkeleton
-  columns={[{ key: 'content' }]}
-  rows={8}
-/>
+const columns = [
+  { key: 'name', width: 'w-1/3' },
+  { key: 'status' },
+  { key: 'date' },
+]
+
+// While data is loading:
+if (isLoading) {
+  return (
+    <TableCardSkeleton
+      columns={columns}
+      rows={5}
+      hasActions
+      hasChevron
+    />
+  )
+}
 ```
 
-The skeleton automatically handles responsive layouts, showing a multi-column desktop view and a simplified mobile card layout with actions positioned appropriately for each breakpoint.
+> **Deprecation notice:** `TableCardSkeleton` is deprecated. Migrate to `DataTableSkeleton` from the `data-table` package for new implementations.

package/src/components/ui/table/.table-timestamp-cell.md

@@ -1,37 +1,47 @@
-<!-- source-hash: 0a94dc83797133e1babefc95d649aa3b -->
-A React component for displaying timestamp and ID data in table cells with automatic timestamp formatting and consistent ODS design token styling.
+<!-- source-hash: 7500f4530337c7688e67a30e99d9fabd -->
+Renders a two-line table cell displaying a formatted timestamp with an optional labeled ID beneath it.
 
 ## Key Components
 
-- **`TableTimestampCell`** - Main component that renders timestamp as primary text and ID as secondary text
-- **`TableTimestampCellProps`** - TypeScript interface defining component props including timestamp, id, optional label, and formatting options
-- **`formatTimestampValue`** - Utility function that intelligently formats timestamps from Date objects, ISO strings, or pre-formatted strings
+### `TableTimestampCell` *(deprecated — use `data-table` instead)*
+A React client component that stacks a primary timestamp line and a secondary ID line within a flex column layout.
+
+### `TableTimestampCellProps` *(deprecated)*
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `timestamp` | `string \| Date` | — | Timestamp to display; auto-formatted if ISO string or Date |
+| `id` | `string` | — | ID value shown below the timestamp |
+| `idLabel` | `string` | `undefined` | Optional label prefix (e.g. `"Log ID"`) |
+| `className` | `string` | `undefined` | Additional CSS classes for the container |
+| `formatTimestamp` | `boolean` | `true` | Disable to render the timestamp as-is |
+
+### `formatTimestampValue` *(internal)*
+Converts a `Date` or ISO string to a locale-formatted string. Already-formatted strings (containing `,` or `/` + `:`) are returned unchanged. Falls back to `String(timestamp)` if parsing fails.
 
 ## Usage Example
 
 ```typescript
 import { TableTimestampCell } from './table-timestamp-cell'
 
-// Basic usage with ISO timestamp
+// With an ISO string and a labeled ID
 <TableTimestampCell
-  timestamp="2024-01-15T10:30:00Z"
-  id="abc123"
+  timestamp="2024-06-15T14:30:00Z"
+  id="abc-123"
+  idLabel="Log ID"
 />
 
-// With custom ID label
+// With a Date object, no label
 <TableTimestampCell
   timestamp={new Date()}
-  id="log-123"
-  idLabel="Log ID"
+  id="xyz-789"
 />
 
-// Pre-formatted timestamp (no auto-formatting)
+// Skip auto-formatting (display raw value)
 <TableTimestampCell
-  timestamp="1/15/2024, 10:30:00 AM"
-  id="chat-456"
+  timestamp="Jun 15, 2024 2:30 PM"
+  id="xyz-789"
   formatTimestamp={false}
-  className="min-w-[200px]"
 />
 ```
 
-The component automatically detects and formats ISO strings and Date objects using `toLocaleString()`, but preserves already-formatted timestamps. It uses ODS design tokens for consistent typography and spacing, with the timestamp displayed prominently above the ID in a flex column layout.
+> **Deprecated:** This component is marked for removal. Migrate to the `data-table` component for new implementations.

package/src/components/ui/table/.table.md

@@ -1,67 +1,47 @@
-<!-- source-hash: 4385b055e6984a325b3911e21d858d1a -->
-A comprehensive table component for displaying tabular data with support for sorting, filtering, pagination, row selection, and bulk actions.
+<!-- source-hash: ec4b9765ec4a72e85067393812e2e172 -->
+A deprecated generic `Table` component that renders a card-style data table with sorting, filtering, selection, pagination, and infinite scroll support.
 
 ## Key Components
 
-- **`Table<T>`** - Main generic table component that renders data in both desktop and mobile responsive layouts
-- **`injectActionsColumn()`** - Utility function that automatically adds an actions column when row actions are provided
-- **Selection Logic** - Built-in row selection with bulk operations support
-- **Responsive Design** - Automatically adapts between desktop table view and mobile card layout
-- **Pagination Support** - Supports both cursor-based and page-based pagination
+### `injectSyntheticColumns<T>`
+Internal helper that appends synthetic columns to the column definitions:
+- **`__actions__`** — renders row-level action buttons or a custom `renderRowActions` slot
+- **`__chevron__`** — renders a navigation chevron button when `rowHref` is provided
+
+### `Table<T>`
+The main exported component. **Marked `@deprecated`** — use `DataTable` from `data-table` instead.
+
+Key features:
+- **Loading state** — shows `TableCardSkeleton` while fetching with no data
+- **Empty state** — renders `TableEmptyState` with a configurable message
+- **Row selection** — checkbox-based with `selectable`, `selectedRows`, and `onSelectionChange`
+- **Bulk actions toolbar** — appears when rows are selected and `showToolbar` + `bulkActions` are set
+- **Sorting & filtering** — delegated to `TableHeader` via `sortBy`, `sortDirection`, `onSort`, `filters`
+- **Pagination** — supports cursor-based (`CursorPagination`) or page-based (`Pagination`)
+- **Infinite scroll** — uses `IntersectionObserver` on a sentinel `<div>` to trigger `onLoadMore`
+- **Sticky header** — controlled via `stickyHeader` and `stickyHeaderOffset`
+- **Placeholder rows** — invisible rows maintain consistent table height when data count is below `skeletonRows`
 
 ## Usage Example
 
 ```typescript
-import { Table } from './components/ui/table'
-
-interface User {
-  id: string
-  name: string
-  email: string
-  role: string
-}
-
-const users: User[] = [
-  { id: '1', name: 'John Doe', email: 'john@example.com', role: 'Admin' },
-  { id: '2', name: 'Jane Smith', email: 'jane@example.com', role: 'User' }
-]
-
-const columns = [
-  { key: 'name', label: 'Name', sortable: true },
-  { key: 'email', label: 'Email' },
-  { key: 'role', label: 'Role', filterable: true }
-]
-
-const rowActions = [
-  {
-    label: 'Edit',
-    onClick: (user: User) => console.log('Edit', user),
-    variant: 'outline' as const
-  },
-  {
-    label: 'Delete',
-    onClick: (user: User) => console.log('Delete', user),
-    variant: 'destructive' as const
-  }
-]
-
-export default function UsersTable() {
-  return (
-    <Table
-      data={users}
-      columns={columns}
-      rowKey="id"
-      rowActions={rowActions}
-      selectable={true}
-      onRowClick={(user) => console.log('Clicked', user)}
-      bulkActions={[
-        {
-          label: 'Delete Selected',
-          onClick: (selected) => console.log('Bulk delete', selected),
-          requiresSelection: true
-        }
-      ]}
-    />
-  )
-}
+<Table
+  data={users}
+  rowKey="id"
+  columns={[
+    { key: 'name', label: 'Name', renderCell: (u) => u.name },
+    { key: 'email', label: 'Email', renderCell: (u) => u.email },
+  ]}
+  rowActions={[{ label: 'Edit', icon: <EditIcon />, onClick: (u) => openEdit(u) }]}
+  rowHref={(u) => `/users/${u.id}`}
+  onRowClick={(u) => console.log(u)}
+  cursorPagination={{
+    hasNextPage: true,
+    hasPreviousPage: false,
+    onNext: fetchNext,
+    onPrevious: fetchPrev,
+  }}
+  loading={isFetching}
+  skeletonRows={5}
+/>
 ```

package/src/components/ui/table/.types.md

@@ -1,66 +1,74 @@
-<!-- source-hash: b29bb6f1cda418086485a5bcba6236d5 -->
-A comprehensive TypeScript type definition file for a flexible table component system, providing interfaces for data display, pagination, filtering, and user interactions.
+<!-- source-hash: 808a537086105a4fbc3af48a2f6c9794 -->
+Legacy table component type definitions, all marked `@deprecated` in favor of the `data-table` module's types.
 
 ## Key Components
 
-**Core Types:**
-- `TableColumn<T>` - Column configuration with sorting, filtering, custom rendering, and responsive visibility
-- `TableProps<T>` - Main table component props with data, styling, and interaction handlers
-- `CursorPagination` & `PagePagination` - Two pagination strategies for different data loading patterns
-- `TableFilters` - Filter state management with column-based filter values
-
-**Action Types:**
-- `BulkAction<T>` - Actions that operate on multiple selected rows
-- `RowAction<T>` - Actions for individual table rows
-- `FilterOption` & `FilterSection` - Filter UI configuration
-
-**Component Props:**
-- `TableHeaderProps`, `TableRowProps`, `TableCellProps` - Individual table element configurations
-- `TableCardSkeletonProps` - Loading state skeleton display
-- `TableEmptyStateProps` - Empty state with optional call-to-action
+| Type | Kind | Description |
+|------|------|-------------|
+| `TableColumn<T>` | Interface | Column definition with sorting, filtering, rendering, and responsive visibility options |
+| `TableProps<T>` | Interface | Full table configuration including data, pagination, selection, sorting, filtering, and styling |
+| `CursorPagination` | Interface | Cursor-based pagination controls with next/previous navigation callbacks |
+| `PagePagination` | Interface | Page-number-based pagination with page change callback |
+| `InfiniteScrollConfig` | Interface | Infinite scroll configuration with load-more callback |
+| `FilterOption` | Interface | Single filter option with id, label, and value |
+| `FilterSection` | Interface | Grouped filter UI section supporting checkbox, radio, or select types |
+| `TableFilters` | Interface | Map of column keys to active filter values |
+| `BulkAction<T>` | Interface | Bulk action definition applied to selected rows |
+| `RowAction<T>` | Interface | Per-row action with label, icon, and click handler |
+| `TableHeaderProps<T>` | Interface | Props for the table header sub-component |
+| `TableRowProps<T>` | Interface | Props for an individual table row sub-component |
+| `TableCellProps` | Interface | Props for a single table cell |
+| `TableCardSkeletonProps` | Interface | Skeleton loader configuration for loading states |
+| `TableEmptyStateProps` | Interface | Empty state display with optional action button |
+| `TailwindBreakpoint` | Type | Responsive breakpoint union: `'md' \| 'lg' \| 'xl' \| '2xl'` |
 
 ## Usage Example
 
+> ⚠️ **Deprecated** — migrate to types from the `data-table` module instead.
+
 ```typescript
+import type { TableColumn, TableProps, CursorPagination } from './types'
+
 interface User {
   id: string
   name: string
   email: string
-  status: 'active' | 'inactive'
 }
 
-const userColumns: TableColumn<User>[] = [
+const columns: TableColumn<User>[] = [
   {
     key: 'name',
     label: 'Name',
     sortable: true,
-    width: 'w-48'
+    hideAt: 'md',
+    renderCell: (user) => <span className="font-medium">{user.name}</span>,
   },
   {
     key: 'email',
     label: 'Email',
-    hideAt: 'sm',
-    renderCell: (user) => <a href={`mailto:${user.email}`}>{user.email}</a>
-  },
-  {
-    key: 'status',
-    label: 'Status',
     filterable: true,
-    filterOptions: [
-      { id: 'active', label: 'Active', value: 'active' },
-      { id: 'inactive', label: 'Inactive', value: 'inactive' }
-    ]
-  }
+    filterKey: 'email',
+  },
 ]
 
+const pagination: CursorPagination = {
+  hasNextPage: true,
+  endCursor: 'cursor_abc123',
+  onNext: (cursor) => fetchUsers({ after: cursor }),
+  onReset: () => fetchUsers({}),
+  totalCount: 200,
+  showInfo: true,
+}
+
 const tableProps: TableProps<User> = {
   data: users,
-  columns: userColumns,
+  columns,
   rowKey: 'id',
+  loading: false,
   selectable: true,
-  cursorPagination: {
-    hasNextPage: true,
-    onNext: (cursor) => loadMore(cursor)
-  }
+  cursorPagination: pagination,
+  stickyHeader: true,
+  stickyHeaderOffset: 'top-[72px]',
+  onRowClick: (user) => router.push(`/users/${user.id}`),
 }
 ```

package/src/components/ui/table/.utils.md

@@ -1,34 +1,32 @@
-<!-- source-hash: 1f2ecc100d32625e53cc8f05066ba404 -->
-Utility functions for managing responsive table column visibility using Tailwind CSS breakpoints.
+<!-- source-hash: 465bf764d0dff56cb3acee5c13872c73 -->
+Brief utility module providing responsive visibility helpers for table columns based on Tailwind CSS breakpoints. Both exports are deprecated in favor of `data-table`.
 
 ## Key Components
 
-- **`getHideClasses()`** - Generates Tailwind CSS classes to hide columns at specific breakpoints
-- **`isHiddenOnMobile()`** - Determines if a column should be hidden on mobile devices
+- **`getHideClasses(hideAt?)`** — Generates Tailwind CSS utility classes to hide/show an element at specified breakpoints. Supports single or multiple breakpoints and computes the appropriate `hidden`/`flex` class combinations.
+- **`isHiddenOnMobile(column)`** — Returns `true` if a `TableColumn` is configured to hide at the `md` breakpoint (i.e., hidden on mobile).
 
 ## Usage Example
 
 ```typescript
 import { getHideClasses, isHiddenOnMobile } from './utils'
-import type { TableColumn } from './types'
 
-// Generate hide classes for responsive design
-const hideClasses = getHideClasses('md') // Returns: 'hidden md:flex'
-const multiBreakpointClasses = getHideClasses(['sm', 'md']) // Returns: 'sm:hidden md:hidden lg:flex'
+// Single breakpoint: hide below md, show at md and above
+getHideClasses('md')
+// → 'hidden md:flex'
 
-// Check if column should be hidden on mobile
-const column: TableColumn<User> = {
-  key: 'email',
-  title: 'Email',
-  hideAt: ['sm', 'md']
-}
+// Multiple breakpoints: hide at md and lg, show at xl
+getHideClasses(['md', 'lg'])
+// → 'md:hidden lg:hidden xl:flex'
 
-const shouldHideOnMobile = isHiddenOnMobile(column) // Returns: true
+// Hide at 2xl with no larger breakpoint — just hide
+getHideClasses('2xl')
+// → '2xl:hidden'
 
-// Apply classes to table cells
-<td className={getHideClasses(column.hideAt)}>
-  {row.email}
-</td>
+// Check if a column is hidden on mobile
+const column = { key: 'email', hideAt: 'md' }
+isHiddenOnMobile(column)
+// → true
 ```
 
-The `getHideClasses()` function handles both single breakpoints and arrays, automatically calculating the appropriate show/hide pattern. For single breakpoints, it hides below and shows at/above the specified breakpoint. For multiple breakpoints, it hides at each specified breakpoint and shows after the largest one. The `isHiddenOnMobile()` function specifically checks for `sm` and `md` breakpoints to filter mobile-hidden columns.
+> **Deprecated:** Both `getHideClasses` and `isHiddenOnMobile` are deprecated. Use the `data-table` component instead.

package/src/contexts/.chat-runtime-context.md

@@ -0,0 +1,54 @@
+<!-- source-hash: 246e5605bed712d2ecbfd71d23933d41 -->
+Provides the React context and typed interface that supply runtime configuration to the Flamingo/OpenFrame chat panel, decoupling API endpoints, navigation behavior, and identity source from the host environment.
+
+## Key Components
+
+### `ChatRuntime` Interface
+The central config shape with three top-level concerns:
+
+| Field | Description |
+|---|---|
+| `endpoints` | All API URLs: streaming chat, agent approval, slash-commands, attachment upload/view, identity, and optional image proxy |
+| `navigation` | Mode (`'host'` or `'embed'`), external URL handler, in-app router callback, and new-tab decision logic |
+| `source` | Required string used for `localStorage` namespacing (`mingo-chat-<source>-v1`) |
+
+### `ChatRuntimeContext`
+Raw React context (`createContext<ChatRuntime | null>(null)`). Mount via `<ChatRuntimeContext.Provider value={...}>` at your tree root.
+
+### `useChatRuntime()`
+Nullable consumer hook. Returns `null` when no provider is mounted — signals unconfigured runtime. Use for optional/graceful-degradation consumers.
+
+### `useRequiredChatRuntime()`
+Strict consumer hook used inside chat internals. Throws a descriptive error if called outside a provider. Use this inside the chat panel itself.
+
+## Usage Example
+
+```typescript
+// Host (hub) — already handled by <HubRuntimeProvider>
+// Embedded app — wire your own provider:
+
+const runtime = useMemo<ChatRuntime>(() => ({
+  source: 'my-embedded-app',
+  endpoints: {
+    chatStreamUrl: 'https://hub.openframe.ai/api/docs/chat',
+    approvalToolUrl: 'https://hub.openframe.ai/api/chat/agent/confirm-tool',
+    commandsUrl: 'https://hub.openframe.ai/api/docs/commands',
+    buildListUrl: (type, ids) => null,
+    attachmentUploadUrl: 'https://hub.openframe.ai/api/storage/upload',
+    attachmentViewUrlPrefix: 'https://hub.openframe.ai/api/storage/view/chat-attachments/',
+    identityUrl: 'https://hub.openframe.ai/api/chat/identity',
+  },
+  navigation: {
+    mode: 'embed',
+    defaultContentOrigin: 'https://hub.openframe.ai',
+  },
+}), [])
+
+return (
+  <ChatRuntimeContext.Provider value={runtime}>
+    <ChatPanel />
+  </ChatRuntimeContext.Provider>
+)
+```
+
+> **Memoization is required.** Passing a new object reference on every render invalidates downstream `useMemo` consumers across the entire chat tree (slash-commands, nav links, stream factory). Always stabilize with `useMemo` and stable deps.