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

package/src/components/chat/utils/.process-historical-messages.md

@@ -1,37 +1,20 @@
-<!-- source-hash: abb044a6e8d133979dfd31cca4044960 -->
-Transforms raw `HistoricalMessage` arrays from GraphQL/API responses into display-ready `ProcessedMessage` objects, handling message grouping, approval state resolution, and tool call rendering.
+<!-- source-hash: a4a5bd19ceba365107b95a454fcee29b -->
+Converts raw `HistoricalMessage` records from GraphQL/API responses into display-ready `ProcessedMessage` arrays, grouping consecutive assistant turns, resolving approval states, and extracting escalated approvals.
 
 ## Key Components
 
-### `processHistoricalMessages(messages, options)`
-Main export. Iterates over historical messages, groups consecutive assistant turns into single display messages, and returns a `ProcessHistoricalMessagesResult` containing:
-- `messages` — fully rendered `ProcessedMessage[]` ready for UI consumption
-- `escalatedApprovals` — approvals filtered out by `displayApprovalTypes` that the consumer handles separately (e.g., admin-side approvals in a client-facing view)
+### Exports
 
-### `processMessageData(data, accumulator, approvalStatuses, options, escalatedApprovals)`
-Internal dispatcher. Routes each `MessageData` item by `MESSAGE_TYPE` to the correct accumulator method:
+- **`processHistoricalMessages(messages, options)`** — Main entry point. Iterates over historical messages, groups assistant turns using an accumulator, flushes user/system messages inline, and returns a `ProcessHistoricalMessagesResult`.
+- **`ProcessHistoricalMessagesResult`** — Return type containing `messages: ProcessedMessage[]` and `escalatedApprovals: Map<string, ...>`.
 
-| Type | Action |
-|---|---|
-| `TEXT` | `appendText` |
-| `THINKING` | `appendThinking` |
-| `EXECUTING_TOOL` / `EXECUTED_TOOL` | `addToolExecution` |
-| `APPROVAL_REQUEST` | Batch or legacy approval card, or escalate |
-| `APPROVAL_RESULT` | Resolves pending/escalated approvals |
+### Internal Functions
 
-### `flushAssistantMessage()` *(internal closure)*
-Drains the segment accumulator into a single assistant `ProcessedMessage`. Uses the **last** message ID in the group as the React key for stable pagination behavior.
-
-### `ProcessHistoricalMessagesResult`
-```typescript
-export interface ProcessHistoricalMessagesResult {
-  messages: ProcessedMessage[]
-  escalatedApprovals: Map<
-    string,
-    { command: string; explanation?: string; approvalType: string; toolCalls?: PendingToolCallData[] }
-  >
-}
-```
+- **`processMessageData(data, accumulator, approvalStatuses, options, escalatedApprovals)`** — Dispatches a single `MessageData` item to the appropriate accumulator method based on `MESSAGE_TYPE` (`TEXT`, `THINKING`, `EXECUTING_TOOL`, `EXECUTED_TOOL`, `APPROVAL_REQUEST`).
+- **`flushAssistantMessage()`** — Drains the `MessageSegmentAccumulator` into a single assistant `ProcessedMessage`, using the last message ID in the group for stable React keys. Resets all grouping state unconditionally.
+- **`getOwnerDisplayName(owner)`** — Resolves a human-readable sender name from a `MessageOwner` (admin full name, or `'You'` for clients).
+- **`getOwnerAvatar(owner)`** — Extracts the admin's profile image URL from the owner, if present.
+- **`pushStandaloneMessages(processedMessages, msg, messageDataArray)`** — Emits `SYSTEM`-type messages directly as `role: 'user'` entries with `authorType: 'system'`.
 
 ## Usage Example
 
@@ -39,19 +22,32 @@ export interface ProcessHistoricalMessagesResult {
 import { processHistoricalMessages } from './process-historical-messages'
 
 const { messages, escalatedApprovals } = processHistoricalMessages(
-  rawMessages,
+  rawHistoricalMessages,
   {
     assistantName: 'Fae',
     assistantType: 'fae',
+    assistantAvatar: '/avatars/fae.png',
     approvalStatuses: { 'req-123': 'approved' },
     displayApprovalTypes: ['CLIENT'],
     batchApprovalsEnabled: true,
-    onApprove: (id) => handleApprove(id),
-    onReject: (id) => handleReject(id),
+    onApprove: (id) => console.log('Approved', id),
+    onReject: (id) => console.log('Rejected', id),
   }
 )
 
-// escalatedApprovals contains ADMIN-type approvals for separate rendering
+// Render messages
+messages.forEach((msg) => console.log(msg.role, msg.content))
+
+// Handle approvals that require elevated review
+escalatedApprovals.forEach((approval, id) => {
+  console.log(`Escalated: ${id}`, approval.command)
+})
 ```
 
-> **Note on `batchApprovalsEnabled`:** Defaults to `true`. Pass `false` to unfold batch approval requests into individual legacy approval cards — useful when the consuming UI has not yet adopted the batch approval component.
+## Notes
+
+- `displayApprovalTypes` intentionally has **no default** on the history path — omitting it displays all approval types, preserving pre-existing history semantics and avoiding silent data loss on reload.
+- `batchApprovalsEnabled` defaults to `true` so consumers without the flag still receive the batch approval UI.
+- `streamSeq` is propagated via `Math.max` across rows in an assistant group, ensuring accurate history-merge coverage downstream.
+
+**Source:** [`process-historical-messages.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/process-historical-messages.ts)

package/src/components/chat/utils/.scripted-stream.md

@@ -0,0 +1,52 @@
+<!-- source-hash: cc8f96e18729e1c4644f8e6b851866bd -->
+Converts a stored `HistoricalMessage[]` into ordered `StreamFrame` playback frames that animate a chat surface identically to the live NATS/SSE stream — without requiring a network connection.
+
+## Key Components
+
+### Types
+
+- **`StreamFrame`** — A single rendered playback step containing the partial message list, `StreamingPhase`, `typing` indicator state, and `delayMs` hold time before advancing.
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `normalizeHistoricalMessageData` | Normalizes `messageData` (single item or array) to `MessageData[]`. |
+| `isHistoricalUserTurn` | Returns `true` when a message has an `owner` (user-authored); assistant turns have none. |
+| `buildStreamFrames` | Core export — expands a full message list into a deterministic sequence of `StreamFrame`s. |
+
+### Playback Cadence Constants
+
+| Constant | Value | Role |
+|---|---|---|
+| `THINK_MS` | 550 ms | Pause before assistant reply begins streaming |
+| `TOKEN_MS` | 55 ms | Delay per word revealed during text streaming |
+| `USER_MS` | 480 ms | Dwell after a user turn lands |
+| `SEGMENT_MS` | 340 ms | Pop-in delay for tool/approval card segments |
+| `POST_MS` | 240 ms | Dwell after a completed assistant turn |
+
+## Usage Example
+
+```typescript
+import { buildStreamFrames } from './scripted-stream'
+import type { HistoricalMessage } from '../types'
+
+const conversation: HistoricalMessage[] = [
+  { owner: 'user', content: 'How do I reset a password?', messageData: null },
+  {
+    content: 'Here is how you reset a password…',
+    messageData: [{ type: 'TEXT', text: 'Here is how you reset a password…' }],
+  },
+]
+
+const frames = buildStreamFrames(conversation)
+
+// Drive an EmbeddableChat in previewMode, e.g. inside useScriptedStream:
+frames.forEach((frame, i) => {
+  setTimeout(() => {
+    renderChat(frame.messages, frame.phase, frame.typing)
+  }, frames.slice(0, i).reduce((sum, f) => sum + f.delayMs, 0))
+})
+```
+
+> **Note:** Frame count for any shared message prefix is deterministic — a host that appends a continuation after an approval resumes seamlessly without rebuilding earlier frames. Pair with `useScriptedStream` for the scheduling clock.

package/src/components/chat/utils/.source-row-cta.md

@@ -1,54 +1,55 @@
-<!-- source-hash: e259d6e958fa331a13973e9d2749ffbc -->
-Resolves the "what does clicking this row do?" CTA contract for source rows across chat-adjacent surfaces (chips, inline cards, search results). Pure function — no DOM, no fetch, no side effects.
+<!-- source-hash: 6609067763f343156daece1351c3881a -->
+Resolves the call-to-action contract for a single source row — determining its icon, destination URL, target platform, and Ask drill-in eligibility — for use across chat-adjacent surfaces (source chips, inline cards, search results).
 
 ## Key Components
 
 ### Interfaces
 
-| Interface | Purpose |
-|---|---|
-| `SourceRowInput` | Row data — `sourceRepo`, `documentType`, `id`, `title`, `externalUrl`, `path` |
-| `SourceRowContext` | Host-injected context — `baseRoute`, `chipBasePlatform`, `currentPlatform`, `tableIdForDocumentType` |
-| `SourceRowCTA` | Resolved contract — `icon`, `iconLabel`, `href`, `targetPlatform`, `askable`, `chatRef` |
+- **`SourceRowInput`** — Describes the raw row data: `sourceRepo`, `documentType`, `id`, `title`, `externalUrl`, `targetPlatform`, and `path`.
+- **`SourceRowContext`** — Host-injected runtime context: `baseRoute`, `chipBasePlatform`, `currentPlatform`, `tableIdForDocumentType`, `composeContentUrl`, and `docPlatformTargets`.
+- **`SourceRowCTA`** — The resolved output contract: `icon`, `iconLabel`, `href`, `targetPlatform`, `askable`, and `chatRef`.
 
-### Exports
+### Functions
 
-- **`resolveSourceRowCTA(row, ctx)`** — Primary resolver. Returns the full CTA contract for a row. Handles icon resolution, URL safety (`safeHref`), path sanitization, and Ask drill-in viability.
-- **`resolveSourceIcon(input, ctx)`** — Lightweight helper for surfaces that only need the icon + label (inline cards, search dropdown). Accepts `{ sourceRepo, documentType }` or a bare `string` (treated as `documentType`) for backward compatibility.
+- **`resolveSourceRowCTA(row, ctx)`** — Core pure function. Derives the icon, resolves the destination URL through a priority chain, and determines Ask drill-in viability.
+- **`sourceRowCtxFromRuntime(runtime, surface)`** — Convenience builder that wires a `ChatRuntime` into a `SourceRowContext`, centralizing wiring shared by all call sites.
+- **`sanitizePath(path)`** — Strips unsafe characters from path strings to prevent traversal or query-string injection.
 
-### Internal Helpers
+### Constants
 
-- **`sanitizePath(path)`** — Strips non-alphanumeric characters except `/`, `-`, `.`, `_` to prevent path traversal or query injection.
-- **`shouldFallbackToPathNav(row)`** — Limits in-app path fallback to `markdown` and `data_room_doc` document types only.
-- **`pickSourceIcon(sourceRepo, documentType)`** — Maps `sourceRepo` → icon name → React component via `SOURCE_ICON_NAMES` + `ICON_REGISTRY`; falls back to `FileText`.
+- **`DOC_TABLE_TYPES`** — `['markdown', 'data_room_doc']` — the document types that resolve via path-based navigation rather than requiring an `externalUrl`.
 
 ## Usage Example
 
 ```typescript
-import { resolveSourceRowCTA, resolveSourceIcon } from './source-row-cta'
+import { resolveSourceRowCTA, sourceRowCtxFromRuntime } from './source-row-cta'
+
+const ctx = sourceRowCtxFromRuntime(
+  {
+    source: 'flamingo',
+    composeContentUrl: runtime.composeContentUrl,
+    docPlatformTargets: runtime.docPlatformTargets,
+  },
+  { baseRoute: '/knowledge-base', chipBasePlatform: 'flamingo' },
+)
 
-// Full CTA resolution for a chip or search result
 const cta = resolveSourceRowCTA(
   {
     sourceRepo: 'blog-posts',
     documentType: 'blog_post',
-    id: 'post-42',
-    title: 'Series A Playbook',
-    externalUrl: 'https://example.com/posts/42',
-    targetPlatform: 'hub',
-  },
-  {
-    baseRoute: '/knowledge-base',
-    currentPlatform: 'hub',
-    tableIdForDocumentType: (type) => type === 'blog_post' ? 'blog-posts' : null,
+    id: 'abc-123',
+    title: 'How we built OpenFrame',
+    externalUrl: 'https://flamingo.run/blog/abc-123',
   },
+  ctx,
 )
-// cta.href       → 'https://example.com/posts/42'  (safeHref-validated)
-// cta.askable   → true
-// cta.chatRef   → { type: 'blog_post', sourceRepo: 'blog-posts', id: 'post-42', ... }
 
-// Icon-only resolution for an inline card tracking strip
-const { Icon, label } = resolveSourceIcon({ documentType: 'cap_table' }, { tableIdForDocumentType })
+// cta.href        → sanitized destination URL
+// cta.icon        → React icon component
+// cta.askable     → true (has id + documentType)
+// cta.chatRef     → pre-built ChatRef for the Ask handler
 ```
 
-> `href` is always `safeHref()`-sanitized — a hostile RAG row cannot inject `javascript:` or `data:` URIs into the DOM. Ask drill-in (`askable`) requires both a non-empty `id` and a `documentType`.
+**URL resolution priority (doc rows):** `docPlatformTargets[documentType]` → `chipBasePlatform` → `baseRoute` → `null`. All final hrefs pass through `safeHref()` to block `javascript:` / `data:` injection.
+
+**Source:** [`source-row-cta.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/source-row-cta.ts)

package/src/components/chat/utils/.tool-call-helpers.md

@@ -1,22 +1,23 @@
-<!-- source-hash: 6aecca2e05a8c612241168939fffcf70 -->
-Utility helpers for resolving, formatting, and rendering tool call data — titles, argument values, and execution results — used across approval and execution UI cards.
+<!-- source-hash: 39498ad7a2e0f9d7ad0f6c8c114b7a36 -->
+Utility module for extracting, formatting, and rendering tool call metadata — titles, command bodies, argument values, and execution results — in a human-readable form for approval and execution cards.
 
 ## Key Components
 
 ### Constants
-- **`COMMAND_BODY_ARG_KEYS`** — Ordered list of argument keys (`command`, `query`, `script`, `scriptContent`, `code`) checked when resolving a tool call's display title.
+
+- **`COMMAND_BODY_ARG_KEYS`** — Ordered list of argument keys (`command`, `query`, `script`, `scriptContent`, `code`) used to locate the primary command body in a tool call's argument map.
 
 ### Functions
 
-| Function | Description |
-|---|---|
-| `getToolCallTitle(opts)` | Resolves a human-readable title from args, title, or name — shape-agnostic for both approval and execution cards. |
-| `getCommandText(call)` | Thin adapter over `getToolCallTitle` for `PendingToolCallData`. |
-| `expandedJsonStringify(value)` | Pretty-prints JSON with real newlines for multi-line strings instead of escaped `\n` sequences. |
-| `formatToolArgValue(value)` | Determines inline vs. block rendering for a single tool argument value. |
-| `formatToolResult(value)` | Determines inline vs. block rendering for a tool execution result, stripping markdown code fences if present. |
+- **`getToolCallTitle(opts)`** — Resolves a human-readable title for a tool call. Falls through `COMMAND_BODY_ARG_KEYS` → `title` → `name` → `'Tool call'`. Shape-agnostic; works for both `PendingToolCallData` and `ToolExecutionData`.
+- **`getCommandText(call)`** — Thin adapter over `getToolCallTitle` for `PendingToolCallData` objects.
+- **`getCommandBody(args)`** — Returns only the raw command body (first `COMMAND_BODY_ARG_KEYS` match), with no fallback. Used by the Fae client card's expanded view.
+- **`expandedJsonStringify(value)`** — Pretty-prints JSON with real newlines instead of escaped `\n` sequences in multi-line strings. Optimised for human readability, not re-parsing.
+- **`formatToolArgValue(value)`** — Determines render mode for a single argument value: JSON block, text block, or inline string.
+- **`formatToolResult(value)`** — Determines render mode for a tool execution result. Strips markdown code fences, then applies the same JSON/block/inline logic as `formatToolArgValue`.
 
 ### Types
+
 - **`FormattedArgValue`** — Discriminated union: `{ kind: 'inline'; text: string }` or `{ kind: 'block'; text: string; language: 'json' | 'text' }`.
 
 ## Usage Example
@@ -24,19 +25,26 @@ Utility helpers for resolving, formatting, and rendering tool call data — titl
 ```typescript
 import {
   getCommandText,
+  getCommandBody,
   formatToolArgValue,
   formatToolResult,
 } from './tool-call-helpers'
 
-// Resolve display title from a pending tool call
-const title = getCommandText(pendingCall)
-// → e.g. "Get-Process | Where-Object CPU -gt 50"
+// Resolve display title for an approval card
+const title = getCommandText({
+  toolName: 'bash',
+  toolTitle: null,
+  toolCallArguments: { command: 'ls -la /var/log' },
+})
+// → 'ls -la /var/log'
 
 // Render an argument value
-const rendered = formatToolArgValue({ host: 'server-01', port: 22 })
-// → { kind: 'block', text: '{\n  "host": "server-01",\n  "port": 22\n}', language: 'json' }
+const formatted = formatToolArgValue('{"key": "value\nwith newline"}')
+// → { kind: 'block', text: '...', language: 'json' }
 
 // Render a tool execution result (strips fences, detects JSON)
-const result = formatToolResult('```json\n{"status":"ok"}\n```')
+const result = formatToolResult('```bash\n{"status": "ok"}\n```')
 // → { kind: 'block', text: '{\n  "status": "ok"\n}', language: 'json' }
-```
+```
+
+**Source:** [`tool-call-helpers.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tool-call-helpers.ts)

package/src/components/contact/.contact-form.md

@@ -1,25 +1,23 @@
-<!-- source-hash: e6e63274e2215026ef420402aa7a9e8f -->
-A self-contained, reusable contact form component that supports both standard contact submission and custom ticket-creation flows via configurable props. It handles field visibility toggling, attachment staging, Zod validation, and dual submit paths (built-in API vs. caller-provided handler).
+<!-- source-hash: b966a03234b6e0b13e69b8aed2a51f90 -->
+Canonical contact form component supporting both public contact flows and internal ticket creation. Accepts configurable field visibility, custom submit handlers, file attachments, and bot-protection signals, making a single form reusable across multiple surfaces without forking.
 
 ## Key Components
 
-**Exported Types**
-- `ContactFormHideableField` — Union type of the six fields that can be suppressed from the UI (`name`, `email`, `companySize`, `referralSource`, `helpCategory`, `message`)
-- `ContactFormProps` — Full prop interface covering attribution, pre-fill, layout, submission, and slot customization
+| Export | Type | Description |
+|---|---|---|
+| `ContactForm` | Component | Main form component with all contact/ticket functionality |
+| `ContactFormProps` | Interface | Full prop surface for customization and embedding |
+| `ContactFormHideableField` | Type | Union of field keys that can be suppressed from rendering |
 
-**Main Export**
-- `ContactForm` — The primary form component
-
-**Internal Hooks Used**
-- `useForm` (react-hook-form) + `zodResolver` against `ContactSchema`
-- `useContactSubmission` — built-in `/api/contact` submit path with toast + redirect
-- `useChatAttachments` — file staging shared with the chat composer
-- `useState` — tracks in-flight state for the custom submit path
+**Internal hooks used:**
+- `useContactSubmission` — built-in `/api/contact` submit flow (toast + redirect)
+- `useHumanitySignals` — honeypot + timing bot-protection signals
+- `useChatAttachments` — file staging using the same primitives as the chat composer
 
 ## Usage Example
 
 ```typescript
-// Standard contact page — built-in submit flow
+// Basic contact page usage
 <ContactForm
   userId={user?.id}
   helpCategoryOptions={appConfig.contact.contactReasons}
@@ -27,12 +25,13 @@ A self-contained, reusable contact form component that supports both standard co
   onSubmitSuccess={clearStoredRedditClickId}
 />
 
-// Ticket creation — custom submit, hidden fields, extra Subject input
+// Ticket creation surface — hides name/email, adds Subject field,
+// uses a custom submit handler
 <ContactForm
-  hideFields={['name', 'email', 'companySize', 'referralSource', 'helpCategory']}
-  defaultValues={{ name: user.name, email: user.email, helpCategory: 'Support' }}
-  attachmentsEnabled
+  hideFields={['name', 'email', 'companySize', 'referralSource']}
+  defaultValues={{ name: user.name, email: user.email }}
   extraTopField={<SubjectInput value={subject} onChange={setSubject} />}
+  attachmentsEnabled
   submitLabel="Open ticket"
   onCustomSubmit={async (data, attachments) => {
     await actions.submitTicket({ ...data, subject, attachments })
@@ -40,4 +39,10 @@ A self-contained, reusable contact form component that supports both standard co
 />
 ```
 
-> **Note:** When hiding `name`, `email`, or `helpCategory`, you **must** supply their values via `defaultValues` — Zod still validates them even when the fields are not rendered. Hidden `<input type="hidden">` elements ensure react-hook-form includes them in the submit payload.
+## Notes
+
+- `defaultValues` is **required** when hiding `name`, `email`, or `helpCategory` — Zod still validates hidden fields; missing values cause a silent submit block (a `console.warn` logs the offending fields in DevTools).
+- `onCustomSubmit` bypasses the built-in toast/redirect chain entirely; the caller owns all success/error UX.
+- `attachmentsEnabled` must be `true` to render the file picker; otherwise `attachments` passed to `onCustomSubmit` is always `[]`.
+
+**Source:** [`contact-form.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/contact-form.tsx)

package/src/components/docs/.doc-navigation-context.md

@@ -0,0 +1,49 @@
+<!-- source-hash: 64fe296f0d441160ca77beb4bd1eaaca -->
+React context that bridges `useDocumentTree` viewer instances to `GlobalAskAI` components, enabling programmatic document navigation without global events or URL parsing.
+
+## Key Components
+
+### `DocNavigator` (interface)
+Represents a mounted document viewer with three members:
+- `baseRoute` — the URL prefix this navigator owns (e.g., `'/knowledge-base'`)
+- `findNodeByPath(path)` — looks up a `DocNode` by storage path
+- `selectNode(node)` — triggers navigation as if the user clicked a sidebar item
+
+### `DocNavigationProvider`
+Context provider that maintains a `Map<baseRoute, DocNavigator>`. Supports multiple concurrent navigators (dual-pane, nested viewers) with longest-prefix matching to route navigation calls to the correct owner.
+
+### `useDocNavigation()` (hook)
+Returns the context value with three methods:
+- `register(nav)` — registers a navigator; returns a StrictMode-safe cleanup function
+- `navigate(path)` — resolves the owning navigator and selects the node; returns `true` if handled
+- `isAvailable()` — returns `true` if at least one navigator is mounted
+
+## Usage Example
+
+```typescript
+// In a document viewer component
+import { useDocNavigation } from './doc-navigation-context'
+
+function DocViewer({ baseRoute }: { baseRoute: string }) {
+  const { register } = useDocNavigation()
+
+  useEffect(() => {
+    const cleanup = register({
+      baseRoute,
+      findNodeByPath: (path) => tree.find(path) ?? null,
+      selectNode: (node) => setActiveNode(node),
+    })
+    return cleanup
+  }, [baseRoute, register])
+}
+
+// In GlobalAskAI — navigate to a cited document
+function AskAI() {
+  const { navigate, isAvailable } = useDocNavigation()
+
+  const handleCitationClick = (storagePath: string) => {
+    const handled = navigate(storagePath)
+    if (!handled) window.open(storagePath, '_blank')
+  }
+}
+```

package/src/components/docs/.doc-viewer.md

@@ -0,0 +1,64 @@
+<!-- source-hash: cf4c252821dd0aa2c926e8dce8077256 -->
+Renders a full-featured documentation viewer with a collapsible sidebar navigation, AI-powered search, sticky section navigation, and pluggable content/skeleton renderers for markdown and embed document types.
+
+## Key Components
+
+### Exports
+
+- **`DocViewer`** — Main component wrapping `DocViewerContent`; accepts `DocViewerProps` and wires document tree state, scroll spy, link resolution, and search into a `PageLayout` shell
+- **`DEFAULT_DOC_VIEWER_PALETTE`** — Shared ODS color token map for the viewer chrome (background, text, border, card); intentionally uniform across knowledge-base and data-room surfaces
+
+### Props (`DocViewerProps`)
+
+| Prop | Type | Description |
+|---|---|---|
+| `sourceId` | `DocSourceId` | Registry source identifier, threaded into API calls and link resolution |
+| `renderContent` | `fn` | Caller-supplied renderer for doc body (markdown, PDF, Figma, Sheets, etc.) |
+| `renderSkeleton` | `fn` | Returns a typed loading skeleton based on `documentType` |
+| `chatSource` | `string` | Server-side platform identifier for RAG search; never pass user input |
+| `baseRoute` | `string` | Root path for URL navigation |
+| `shell` | `boolean` | When `false`, omits the `<main>` wrapper if the host layout already provides it |
+| `structureEndpoint` | `string?` | Override for doc tree API (defaults to `/api/docs/sources/${sourceId}/structure`) |
+| `contentEndpoint` | `string?` | Override for doc content API |
+| `searchEndpoint` | `string?` | Override for RAG search endpoint |
+| `resolveLinkEndpoint` | `string?` | Override for internal link resolver (prop → runtime → `/api/docs/resolve-link`) |
+| `backButton` | `object \| false` | Back-button config; pass `false` to hide |
+
+### Internal Hooks
+
+- **`useDocumentTree`** — Fetches structure + content, manages `selectedPath`, `expandedNodes`, navigation
+- **`useScrollSpy`** — Tracks active section for sticky nav highlighting
+- **`useDocNavigation`** — Context-based in-page navigation
+- **`useDocsResolveLink`** — Async internal link resolver pipeline
+- **`useDocSearch`** — RAG search bar state and navigation callbacks
+
+## Usage Example
+
+```typescript
+import { DocViewer } from "@openframe/lib"
+import { renderDocContent } from "./my-renderer"
+import { renderDocSkeleton } from "./my-skeleton"
+
+export default function DocsPage({ params }: { params: { path: string[] } }) {
+  return (
+    <DocViewer
+      sourceId="openframe-docs"
+      chatSource="hub"
+      baseRoute="/docs"
+      docPath={params.path?.join("/")}
+      title="Documentation"
+      sidebarLabel="DOCUMENTATION"
+      showAIChat
+      renderContent={(content, handlers) =>
+        renderDocContent(content, handlers)
+      }
+      renderSkeleton={(documentType) =>
+        renderDocSkeleton(documentType)
+      }
+      backButton={{ label: "Back to home", href: "/" }}
+    />
+  )
+}
+```
+
+**Source:** [`doc-viewer.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/doc-viewer.tsx)

package/src/components/docs/.docs-hub-page.md

@@ -0,0 +1,49 @@
+<!-- source-hash: d5476a1b465d54af10c5d777aa9edbff -->
+Embeddable docs-hub page component that wires `<DocViewer>` with sensible per-document-type rendering defaults, reducing consumer setup to a single required prop (`documentTypeRenderers.markdown`).
+
+## Key Components
+
+### `DocsHubPage` (default export)
+The primary component. Accepts a renderer map and delegates to `<DocViewer>` after merging consumer-supplied renderers with built-in defaults for `pdf`, `google_sheet`, `figma`, and `file` types.
+
+### `DocumentTypeRenderers`
+A type-safe renderer map. `markdown` is **required**; all other document types are optional overrides. The library intentionally omits a default markdown renderer to let consumers choose their own sanitization strategy and avoid XSS exposure.
+
+### Default renderers
+| Type | Default behavior |
+|---|---|
+| `pdf` | `<PdfViewer>` if `fileUrl` exists, else unsupported message |
+| `google_sheet` | `<GoogleSheetsViewer>` if `externalUrl` exists, else unsupported message |
+| `figma` | `<FigmaEmbed>` if `externalUrl` exists, else unsupported message |
+| `file` | `<FileDownloadCard>` (handles missing URL internally) |
+| unknown | Centered "Unsupported document type" text panel |
+
+### `defaultRenderSkeleton`
+Picks `<MarkdownSkeleton>` for markdown/undefined types and `<EmbedSkeleton>` (shape-aware) for all embed types.
+
+## Usage Example
+
+```typescript
+import { DocsHubPage } from './docs-hub-page'
+import ReactMarkdown from 'react-markdown'
+
+export function KnowledgeBasePage() {
+  return (
+    <DocsHubPage
+      title="Knowledge Base"
+      sidebarLabel="DOCUMENTATION"
+      // markdown renderer is required — consumer owns sanitization
+      documentTypeRenderers={{
+        markdown: (content) => (
+          <ReactMarkdown>{content.markdownBody ?? ''}</ReactMarkdown>
+        ),
+        // override only when you need custom props, e.g.:
+        // pdf: (content) => <PdfViewer src={content.fileUrl} showToolbar />,
+      }}
+      showAIChat={true}
+    />
+  )
+}
+```
+
+> **Note:** This component is client-side only (`'use client'`). For SEO, the host application is responsible for server-side rendering. See `docs/EMBEDDING_DOCS_HUB.md` for full embedder setup.

package/src/components/docs/.index.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 9d7bd787c09286e0b64acbaa1eea4ea0 -->
+Public API barrel file for the documentation viewer feature, re-exporting all components, hooks, context providers, and TypeScript types needed to build and integrate a documentation hub UI.
+
+## Key Components
+
+| Export | Source | Description |
+|---|---|---|
+| `DocViewer` | `./doc-viewer` | Core document rendering component |
+| `DocsHubPage` | `./docs-hub-page` | Full documentation hub page layout |
+| `MarkdownSkeleton`, `EmbedSkeleton` | `./skeletons` | Loading skeleton components |
+| `useDocumentTree` | `./use-document-tree` | Hook for fetching/managing document tree structure |
+| `useScrollSpy` | `./use-scroll-spy` | Hook for tracking scroll position within docs |
+| `DocNavigationProvider`, `useDocNavigation` | `./doc-navigation-context` | Context provider and hook for doc navigation state |
+
+### Re-exported Types
+
+Types from `../../types/doc-source` define the API contract for the `/api/docs/sources/[sourceId]/{structure,content}` and `/api/docs/resolve-link` endpoints:
+
+- `DocNode`, `DocContent`, `DocSourceId`, `DocumentType` — doc source data shapes
+- `DocRenderHandlers`, `ResolveLinkResult` — renderer and link resolution interfaces
+
+## Usage Example
+
+```typescript
+import {
+  DocsHubPage,
+  useDocumentTree,
+  DocNavigationProvider,
+  type DocumentTypeRenderers,
+  type DocNode,
+} from '@/features/docs'
+
+const renderers: DocumentTypeRenderers = {
+  markdown: (content) => <MarkdownRenderer content={content} />,
+}
+
+export default function DocsLayout() {
+  return (
+    <DocNavigationProvider>
+      <DocsHubPage sourceId="my-source" renderers={renderers} />
+    </DocNavigationProvider>
+  )
+}
+```
+
+## Notes
+
+- Marked `"use client"` — all exports are React Client Components or client-side hooks.
+- Consumers implementing a custom doc source must satisfy the API contract types (`DocNode`, `DocContent`, etc.) exported from this file.
+
+**Source:** [`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

package/src/components/docs/.skeletons.md

@@ -0,0 +1,47 @@
+<!-- source-hash: 8ab264cb863c4be18bbbf4b0df822e4c -->
+Animated loading skeleton components for the DocsHub document viewer, providing layout-matched placeholders while document content loads.
+
+## Key Components
+
+### `MarkdownSkeleton`
+
+A text-style skeleton that mimics a rendered markdown article layout — paragraphs of pulsing bars, a heading bar, and two card-style callout blocks. Used by `<DocsHubPage>` as the default skeleton for `markdown` and unknown document types.
+
+### `EmbedSkeleton`
+
+A document-type-aware skeleton for iframe-based viewers (`pdf`, `google_sheet`, `figma`, `file`). Matches the header button count and body layout of the actual viewer to minimize layout shift on load.
+
+**`EmbedSkeletonProps`**
+
+| Prop | Type | Description |
+|---|---|---|
+| `documentType` | `'pdf' \| 'google_sheet' \| 'figma' \| 'file' \| string` | Controls header button count and card layout |
+
+**Layout by `documentType`:**
+
+| Value | Layout |
+|---|---|
+| `pdf` | Header + icon/title + **two** buttons (Preview, Download) + iframe body |
+| `google_sheet` / `figma` | Header + icon/title + **one** button + iframe body |
+| `file` | Centered `FileDownloadCard`-style bordered card (icon, name, download button) |
+| `undefined` / other | Generic one-button header + iframe body |
+
+> **Note:** Bars use `bg-ods-border` intentionally — `--ods-skeleton` resolves to transparent in this build, which would leave large surfaces visually empty.
+
+## Usage Example
+
+```typescript
+import { MarkdownSkeleton, EmbedSkeleton } from './skeletons'
+
+// Default markdown loading state
+<MarkdownSkeleton />
+
+// PDF viewer loading state (two-button header)
+<EmbedSkeleton documentType="pdf" />
+
+// File download card loading state
+<EmbedSkeleton documentType="file" />
+
+// Embedders can override entirely via renderSkeleton prop on DocsHubPage
+<DocsHubPage renderSkeleton={() => <MyCustomSkeleton />} />
+```