@flamingo-stack/openframe-frontend-core 0.0.204 → 0.0.205

package/src/components/chat/utils/chat-attachment-markdown.ts

@@ -0,0 +1,190 @@
+/**
+ * Shared helper for the host-side markdown formatter ↔ server-side
+ * parser pair. Single source of truth so the host-side build (chat
+ * bubble render) and the server-side strip (LLM input cleanup) can
+ * never drift.
+ *
+ * Lib-side replacement for the hub's `lib/utils/chat-attachment-markdown.ts`.
+ * The hub file pulled its constants from `lib/config/chat-attachment-config`
+ * + its `ChatAttachment` type from `lib/types/chat-attachment`. Both are
+ * inlined here as lib-local constants/types — they're stable wire-format
+ * contracts (the hub's view-route owns the prefix + token-param name; any
+ * change is a coordinated migration).
+ *
+ * URL flavors at a glance:
+ *   - HOST-SIDE (user-bubble render): uses the runtime's
+ *     `attachmentViewUrlPrefix` (hub default = `/api/storage/view/chat-attachments/`).
+ *     Embedded apps override per their reverse-proxy topology.
+ *   - SERVER-SIDE (strip regex): uses the constant
+ *     `CHAT_ATTACHMENT_VIEW_URL_PREFIX` directly. The chat ROUTE always
+ *     runs on the hub, so it always strips on the hub default.
+ *   - ANTHROPIC image-blocks: uses the RAW Supabase signed URL — NOT the
+ *     proxy URL — because Anthropic's image fetcher doesn't reliably
+ *     follow 302 redirects.
+ *
+ * Security gates inside the formatter:
+ *   - Filename markdown chars escaped via `escapeMarkdownInline` so a
+ *     name like `screenshot](https://evil.com).png` cannot terminate
+ *     the markdown image early and embed an attacker-controlled URL.
+ *   - `<` and `>` escaped too — prevents CommonMark autolink expansion
+ *     for filenames containing URL-shaped text.
+ */
+
+// ---------------------------------------------------------------------------
+// Lib-local constants + types (mirror the hub's chat-attachment-config /
+// chat-attachment.ts). These are wire-format contracts owned by the hub's
+// view route; embedders that want to override the prefix do so via
+// `ChatRuntime.endpoints.attachmentViewUrlPrefix`, not by changing these.
+// ---------------------------------------------------------------------------
+
+/** Hub-default prefix for the view-proxy URL. Embedders override via the
+ *  runtime. The server-side strip regex always uses THIS value (server
+ *  runs on the hub). */
+export const CHAT_ATTACHMENT_VIEW_URL_PREFIX = '/api/storage/view/chat-attachments/'
+
+/** Query parameter name for the HMAC view token. */
+export const CHAT_ATTACHMENT_VIEW_TOKEN_QUERY_PARAM = 't'
+
+/** Subset Anthropic's image content-block API supports. HEIC / video
+ *  attachments fall through to the text-marker form so the LLM still sees
+ *  a reference even when it can't visually parse the file. */
+export const ANTHROPIC_SUPPORTED_IMAGE_MIME = [
+  'image/jpeg',
+  'image/png',
+  'image/webp',
+  'image/gif',
+] as const
+
+/**
+ * Wire shape for a single chat attachment.
+ *
+ * `viewToken` is server-issued (HMAC-signed) and embedded in the markdown
+ * URL's `?t=` query parameter. The client never generates it — the upload
+ * route returns it alongside the storage path.
+ */
+export interface ChatAttachment {
+  storagePath: string
+  viewToken: string
+  contentType: string
+  fileName: string
+  size: number
+}
+
+// ---------------------------------------------------------------------------
+// URL building
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the markdown view-URL for a chat attachment.
+ *
+ * `viewUrlPrefix` is parameterized (NOT pulled from the constant) so
+ * host-side callers can pass the runtime's prefix
+ * (`ChatRuntime.endpoints.attachmentViewUrlPrefix`) — embedded apps
+ * supply an absolute URL against the hub's origin so chat-history
+ * markdown works cross-origin.
+ *
+ * Server-side callers (the strip regex source) should pass
+ * `CHAT_ATTACHMENT_VIEW_URL_PREFIX` directly.
+ */
+export function buildChatAttachmentViewUrl(
+  viewUrlPrefix: string,
+  storagePath: string,
+  viewToken: string,
+): string {
+  return `${viewUrlPrefix}${storagePath}?${CHAT_ATTACHMENT_VIEW_TOKEN_QUERY_PARAM}=${encodeURIComponent(viewToken)}`
+}
+
+// ---------------------------------------------------------------------------
+// Markdown formatter
+// ---------------------------------------------------------------------------
+
+/**
+ * Escape inline-markdown special characters from a filename before
+ * interpolation. Closes the markdown-injection / phishing primitive:
+ * a filename like `screenshot](https://evil.com).png` would otherwise
+ * terminate `![filename](...)` early and emit an attacker-controlled
+ * URL in the user's bubble.
+ *
+ * Escapes: `[`, `]`, `(`, `)`, `\`, `\n`, `\r`, `<`, `>`, `"`.
+ */
+export function escapeMarkdownInline(text: string): string {
+  return text.replace(/[[\]()\\\n\r<>"]/g, (ch) => {
+    switch (ch) {
+      case '\n':
+        return ' '
+      case '\r':
+        return ''
+      default:
+        return `\\${ch}`
+    }
+  })
+}
+
+/**
+ * Format a single chat-attachment as a markdown line to append to the
+ * user's bubble text BEFORE sending.
+ *
+ * Images (MIME in `ANTHROPIC_SUPPORTED_IMAGE_MIME`) emit the `![]()`
+ * image form so the browser renders the attachment inline. Everything
+ * else (HEIC, video, audio) emits the `[Attached: ...]` link form so the
+ * bubble shows a clickable file pill instead of a broken-image icon.
+ */
+export function formatChatAttachmentMarkdownForBubble(
+  att: ChatAttachment,
+  viewUrlPrefix: string,
+): string {
+  const safeName = escapeMarkdownInline(att.fileName)
+  const url = buildChatAttachmentViewUrl(viewUrlPrefix, att.storagePath, att.viewToken)
+  const isImage = (ANTHROPIC_SUPPORTED_IMAGE_MIME as readonly string[]).includes(att.contentType)
+  return isImage ? `\n\n![${safeName}](${url})` : `\n\n[Attached: ${safeName}](${url})`
+}
+
+// ---------------------------------------------------------------------------
+// Server-side strip regex + parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Module-private: the `CHAT_ATTACHMENT_VIEW_URL_PREFIX` with regex
+ * meta-characters escaped, so it can be safely interpolated into
+ * regex sources. Computed ONCE at module load. Exported so other
+ * regex-building call sites can share the same source of truth.
+ */
+export const CHAT_ATTACHMENT_VIEW_URL_PREFIX_REGEX_ESCAPED =
+  CHAT_ATTACHMENT_VIEW_URL_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/**
+ * Single anchored regex matching both the image (`![]()`) and link
+ * (`[Attached: ...]`) forms keyed on the server-side prefix.
+ *
+ * `gm` flags — multi-line anchored so the regex matches per-line.
+ * Non-chat markdown links/images stay untouched because the regex
+ * requires the literal `/api/storage/view/chat-attachments/` prefix.
+ */
+export const CHAT_ATTACHMENT_MARKDOWN_PATTERN = new RegExp(
+  `^\\s*!?\\[[^\\]]*\\]\\(${CHAT_ATTACHMENT_VIEW_URL_PREFIX_REGEX_ESCAPED}[^)]+\\)\\s*$`,
+  'gm',
+)
+
+/**
+ * Strip pre-embedded chat-attachment markdown lines from `text`.
+ * Returns the cleaned text + the storage paths extracted from the
+ * matched URLs.
+ */
+export function stripChatAttachmentMarkdown(text: string): {
+  stripped: string
+  storagePaths: string[]
+} {
+  const storagePaths: string[] = []
+  const pathExtract = new RegExp(
+    `\\(${CHAT_ATTACHMENT_VIEW_URL_PREFIX_REGEX_ESCAPED}([^?)]+)`,
+  )
+  const stripped = text.replace(CHAT_ATTACHMENT_MARKDOWN_PATTERN, (match) => {
+    const m = match.match(pathExtract)
+    if (m && m[1]) storagePaths.push(m[1])
+    return ''
+  })
+  return {
+    stripped: stripped.replace(/\n{3,}/g, '\n\n').trim(),
+    storagePaths,
+  }
+}

package/src/components/chat/utils/chat-authed-fetch.ts

@@ -0,0 +1,73 @@
+'use client'
+
+/**
+ * Shared `fetch` wrapper for chat-side endpoints that need to carry
+ * the bearer-act-as identity (proxy `Authorization` + `X-Chat-Act-As`
+ * headers from `chat-proxy-auth-storage.ts`).
+ *
+ * Three call sites today:
+ *   - `useEmbeddedChat` — chat-stream + confirm-tool POST.
+ *   - `useChatAttachments` — chat-attachment upload-URL mint.
+ *   - `useChatIdentity` — capability route GET.
+ *
+ * Without a unified helper, a future chat endpoint that forgets to call
+ * `applyProxyAuth` silently degrades bearer-act-as users to anon.
+ *
+ * Drop-in replacement for `fetch()` — `Authorization` / `X-Chat-Act-As`
+ * are merged into `init.headers` if proxy creds are stashed in
+ * localStorage, otherwise the call falls through unchanged.
+ *
+ * Use this for any client-side fetch hitting `/api/docs/chat/*`,
+ * `/api/chat/*`, or `/api/storage/generate-upload-url` (chat-attachment
+ * surface). Routes that do NOT need bearer-act-as (e.g.
+ * `/api/profile/me`) keep using vanilla `fetch`.
+ */
+
+import { applyProxyAuth } from './chat-proxy-auth-storage'
+
+/**
+ * `fetch` wrapper that attaches chat-proxy bearer headers (when
+ * present in localStorage) and forces `credentials: 'same-origin'`
+ * so Supabase auth cookies travel too.
+ *
+ * Headers are MERGED: caller-supplied `init.headers` keys override the
+ * proxy headers (so a caller explicitly passing `Authorization` wins).
+ * In practice `applyProxyAuth` only sets the keys our chat auth chain
+ * cares about and no caller should override those — but the merge
+ * direction is documented so a future caller doesn't get a surprise.
+ */
+export function chatAuthedFetch(url: string, init: RequestInit = {}): Promise<Response> {
+  // `applyProxyAuth` accepts `Record<string, string>`; normalize the
+  // caller's headers to that shape. RequestInit accepts `HeadersInit`
+  // which is broader (Headers instance OR array of tuples).
+  //
+  // When the caller passes no headers, fall back to the same default
+  // `applyProxyAuth` uses internally — `Content-Type: application/json`
+  // — so JSON POSTs keep their content-type when only `applyProxyAuth(url)`
+  // is used at the call site. GET callers that explicitly want no body
+  // headers can pass `init.headers = {}` to opt out.
+  let baseHeaders: Record<string, string>
+  if (init.headers === undefined) {
+    baseHeaders = { 'Content-Type': 'application/json' }
+  } else {
+    baseHeaders = {}
+    if (init.headers instanceof Headers) {
+      init.headers.forEach((v, k) => {
+        baseHeaders[k] = v
+      })
+    } else if (Array.isArray(init.headers)) {
+      for (const [k, v] of init.headers) baseHeaders[k] = v
+    } else {
+      Object.assign(baseHeaders, init.headers as Record<string, string>)
+    }
+  }
+
+  const { url: authedUrl, headers } = applyProxyAuth(url, baseHeaders)
+  return fetch(authedUrl, {
+    ...init,
+    headers,
+    // Always include Supabase auth cookies. `applyProxyAuth` handles
+    // the bearer header layer; cookies are the session-tier carrier.
+    credentials: init.credentials ?? 'same-origin',
+  })
+}

package/src/components/chat/utils/chat-nav-resolution.ts

@@ -0,0 +1,151 @@
+'use client'
+
+/**
+ * Embed-mode navigation resolver + shared click-handling primitives.
+ *
+ * Used by the lib chat panel's chip + card click handlers to force
+ * new-tab + absolutize against the embedder-supplied content origin.
+ *
+ * Refactor from hub origin (D5): inferTargetPlatformFromHref +
+ * getPlatformDomain dropped. Caller threads `targetPlatform` directly.
+ * Relative URLs without a defaultContentOrigin emit a dev warning
+ * and resolve against window.location.origin (likely wrong in embed
+ * mode; embedder should set defaultContentOrigin).
+ */
+
+import type { ChatRuntime } from '../../../contexts/chat-runtime-context'
+
+/** Arguments accepted by `window.open` for a new tab — keep `noopener`
+ *  + `noreferrer` to prevent the opened page from accessing
+ *  window.opener (reverse-tabnabbing class). */
+export const NEW_TAB_FEATURES = 'noopener,noreferrer'
+
+/** Modifier-click predicate — matches the existing useNavLink branch
+ *  (cmd/ctrl/shift/alt OR non-primary mouse button). */
+export function isModifierClick(e: {
+  button?: number
+  metaKey?: boolean
+  ctrlKey?: boolean
+  shiftKey?: boolean
+  altKey?: boolean
+}): boolean {
+  return (
+    e.button !== 0 ||
+    !!e.metaKey ||
+    !!e.ctrlKey ||
+    !!e.shiftKey ||
+    !!e.altKey
+  )
+}
+
+/** Strip the origin from a same-origin absolute URL, returning a relative
+ *  path the host's router will treat as in-app navigation. Pass-through
+ *  for already-relative URLs and for cross-origin URLs. */
+export function stripSameOriginToPath(href: string): string {
+  if (!href.startsWith('http')) return href
+  try {
+    const u = new URL(href)
+    return u.pathname + u.search + u.hash
+  } catch {
+    return href
+  }
+}
+
+export interface ExternalNavResolution {
+  /** Absolutized href — relative paths are joined with
+   *  `runtime.navigation.defaultContentOrigin` (embed contract). */
+  href: string
+  /** Synchronous opener. MUST be invoked inline from a user gesture for
+   *  popup-blocker compatibility (Safari/Firefox). Honors
+   *  runtime.navigation.openExternal override, else falls back to
+   *  window.open(href, '_blank', 'noopener,noreferrer'). */
+  open: () => void
+}
+
+/**
+ * Pre-resolve an href against the embed-mode `defaultContentOrigin`.
+ *
+ * In `embed` mode every chat-rendered anchor MUST point at an absolute
+ * URL on the hub origin (not the embedder origin). Without
+ * pre-resolution, relative paths like `/knowledge-base/foo.md` render
+ * as `<a href="/knowledge-base/...">` — the click handler intercepts
+ * primary-button clicks correctly, but modifier-click (cmd/ctrl/middle/
+ * right) bypasses the handler and opens `<embedder-origin>/...` → 404.
+ * Pre-resolution at render time makes every browser-native navigation
+ * path (hover preview, status bar, copy-link, new-tab via modifier)
+ * land on the hub correctly.
+ *
+ * In `host` mode (the hub itself) the href is returned unchanged —
+ * relative paths resolve naturally against the hub's own origin.
+ *
+ * Absolute URLs and protocol-relative URLs are returned unchanged in
+ * both modes.
+ */
+export function resolveHrefForRuntime(
+  href: string,
+  runtime: ChatRuntime,
+): string {
+  if (runtime.navigation.mode !== 'embed') return href
+  if (href.startsWith('http')) return href
+  if (href.startsWith('//')) return href
+  const origin = runtime.navigation.defaultContentOrigin
+  if (!origin) return href
+  return origin.replace(/\/+$/, '') + (href.startsWith('/') ? href : '/' + href)
+}
+
+/**
+ * Resolve external navigation in embed mode.
+ *
+ * Browser-only: called from React event handlers (onClick, imperative
+ * click handlers) after mount. No SSR-reachable paths.
+ */
+export function resolveExternalNavigation(args: {
+  href: string
+  targetPlatform: string | null | undefined
+  runtime: ChatRuntime
+}): ExternalNavResolution {
+  let abs = args.href
+
+  // Defense: protocol-relative URLs (`//evil.com/x`) are NOT same-origin —
+  // browsers treat them as cross-origin absolute. Without this guard,
+  // a malicious href like `//evil.com/x` would skip the `startsWith('http')`
+  // check and reach the origin-concat branch below, producing a malformed
+  // URL that some browsers normalize back to `https://evil.com/x`
+  // (open-redirect class).
+  if (abs.startsWith('//')) abs = window.location.protocol + abs
+
+  if (!abs.startsWith('http')) {
+    if (args.runtime.navigation.defaultContentOrigin) {
+      // Strip trailing slashes via a loop, not `/\/+$/` — CodeQL flags
+      // the greedy `+` as polynomial-redos even with the `$` anchor.
+      // The loop is unambiguously O(n) in slash count.
+      let origin = args.runtime.navigation.defaultContentOrigin
+      while (origin.endsWith('/')) origin = origin.slice(0, -1)
+      abs = origin + (abs.startsWith('/') ? abs : '/' + abs)
+    } else if (
+      args.runtime.navigation.mode === 'embed' &&
+      process.env.NODE_ENV !== 'production'
+    ) {
+      console.warn(
+        '[chat-nav-resolution] relative href in embed mode with no ' +
+          'defaultContentOrigin set on runtime.navigation — link will resolve ' +
+          'against the embedder origin.',
+        { href: abs, targetPlatform: args.targetPlatform },
+      )
+    }
+  }
+
+  const open = () => {
+    // Explicit if/else (NOT `??`) — `??` only short-circuits on
+    // null/undefined LHS, but `openExternal?.(href)` returns void on a
+    // successful call, which `??` treats as undefined and re-fires
+    // window.open — double-open bug.
+    if (args.runtime.navigation.openExternal) {
+      args.runtime.navigation.openExternal(abs)
+    } else {
+      window.open(abs, '_blank', NEW_TAB_FEATURES)
+    }
+  }
+
+  return { href: abs, open }
+}

package/src/components/chat/utils/chat-proxy-auth-storage.ts

@@ -0,0 +1,148 @@
+'use client'
+
+/**
+ * Client-side persistence for the chat-proxy credentials
+ * (`CHAT_PROXY_SECRET` + impersonation email). When set, the chat widget
+ * attaches them as `Authorization: Bearer <secret>` + `X-Chat-Act-As: <email>`
+ * on every call to `/api/docs/chat` and `/api/chat/agent/*` — proving to
+ * the server that this session is acting on behalf of <email>.
+ *
+ * Persists to **`sessionStorage`** (not `localStorage`) so the bearer
+ * token and act-as identity evaporate when the tab closes. An XSS sink
+ * on this origin can still exfiltrate the value while the tab is open
+ * (impossible to avoid without server-side opaque tokens), but the
+ * exposure window shrinks from "indefinite" to "current tab session"
+ * which is an order of magnitude better. Admin-only by convention —
+ * the `/debug` admin route hosts the paste-creds UI and is gated
+ * behind the platform's `askAI.enabled` flag.
+ *
+ * Namespaced under `<platform>.chat.proxy-auth.v1` so switching
+ * `NEXT_PUBLIC_APP_TYPE` mid-session doesn't drag stale creds across
+ * surfaces.
+ */
+
+import { createLocalStorageAdapter } from '../../../utils/local-storage-adapter'
+import { getAppType } from '../../../utils/app-config'
+
+export interface ChatProxyAuth {
+  secret: string
+  email: string
+  /** Optional identity passthrough — empty/omitted = not sent. Server
+   *  parses these as `X-Chat-{First,Last}-Name` / `X-Chat-Avatar-Url` and
+   *  threads them through `resolveChatProxyIdentity`'s returned user. */
+  firstName?: string
+  lastName?: string
+  avatarUrl?: string
+}
+
+function isValidPersistedAuth(value: unknown): value is ChatProxyAuth {
+  if (!value || typeof value !== 'object') return false
+  const v = value as Record<string, unknown>
+  if (
+    typeof v.secret !== 'string' || v.secret.trim().length === 0 ||
+    typeof v.email !== 'string' || v.email.trim().length === 0
+  ) return false
+  // Optional fields: when present must be strings. Empty string is treated
+  // as absent later (in `getChatProxyAuth`).
+  if (v.firstName != null && typeof v.firstName !== 'string') return false
+  if (v.lastName != null && typeof v.lastName !== 'string') return false
+  if (v.avatarUrl != null && typeof v.avatarUrl !== 'string') return false
+  return true
+}
+
+const adapter = createLocalStorageAdapter<ChatProxyAuth>({
+  key: 'chat.proxy-auth.v1',
+  // Namespace by platform so a developer switching `NEXT_PUBLIC_APP_TYPE`
+  // mid-session doesn't drag stale creds across surfaces.
+  namespace: () => getAppType(),
+  validate: isValidPersistedAuth,
+  logTag: '[chat-proxy-auth-storage]',
+  // sessionStorage — cleared when the tab closes. Bearer token + act-as
+  // identity should NOT outlive the current session, so localStorage's
+  // indefinite persistence is the wrong choice here. See file-level
+  // doc comment for the threat-model rationale.
+  backend: 'session',
+})
+
+/** Trim + null-coerce an optional identity field so consumers can do
+ *  `auth.firstName ?? ''` without worrying about whitespace-only strings. */
+function normalizeOptional(value: string | undefined): string | undefined {
+  if (!value) return undefined
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : undefined
+}
+
+/**
+ * Returns full credentials (secret + email + optional identity passthrough)
+ * when secret + email are available in localStorage. Survives page reloads.
+ * Returns `null` when nothing is saved — callers treat that as "fall back
+ * to cookie auth".
+ */
+export function getChatProxyAuth(): ChatProxyAuth | null {
+  const persisted = adapter.load()
+  if (!persisted) return null
+  return {
+    secret: persisted.secret,
+    email: persisted.email.trim().toLowerCase(),
+    firstName: normalizeOptional(persisted.firstName),
+    lastName: normalizeOptional(persisted.lastName),
+    avatarUrl: normalizeOptional(persisted.avatarUrl),
+  }
+}
+
+/**
+ * Returns the LAST email the admin saved. The bar reads this to pre-fill
+ * the email field on mount.
+ */
+export function getPersistedProxyEmail(): string | null {
+  const persisted = adapter.load()
+  return persisted?.email.trim().toLowerCase() ?? null
+}
+
+/** Save the proxy creds to localStorage. Secret + email are required;
+ *  identity-passthrough fields are persisted only when non-empty. */
+export function setChatProxyAuth(value: ChatProxyAuth): void {
+  adapter.save({
+    secret: value.secret,
+    email: value.email.trim().toLowerCase(),
+    firstName: normalizeOptional(value.firstName),
+    lastName: normalizeOptional(value.lastName),
+    avatarUrl: normalizeOptional(value.avatarUrl),
+  })
+}
+
+/** Drop the persisted creds. */
+export function clearChatProxyAuth(): void {
+  adapter.clear()
+}
+
+/**
+ * Apply the chat-proxy auth (Bearer + X-Chat-Act-As) to a fetch call's
+ * URL + headers. Used by every chat-side route that needs to identify
+ * itself as the proxied customer (the docs chat stream AND every
+ * confirm-tool / agent-* route the chat shell calls afterwards). When
+ * proxy auth is absent (regular cookie-session users), returns the
+ * inputs unchanged so the cookie-auth path still works.
+ *
+ * `X-Chat-Act-As` header (vs a URL query param) keeps PII out of
+ * access logs, Sentry breadcrumbs, browser history, and CDN analytics.
+ */
+export function applyProxyAuth(
+  url: string,
+  baseHeaders: Record<string, string> = { 'Content-Type': 'application/json' },
+): { url: string; headers: Record<string, string> } {
+  const auth = getChatProxyAuth()
+  const headers = { ...baseHeaders }
+  if (auth?.secret) {
+    headers.Authorization = `Bearer ${auth.secret}`
+  }
+  if (auth?.email) {
+    headers['X-Chat-Act-As'] = auth.email
+  }
+  // Optional identity passthrough — only attached when present so the
+  // server's "required vs optional" header shape stays exact.
+  if (auth?.firstName) headers['X-Chat-First-Name'] = auth.firstName
+  if (auth?.lastName) headers['X-Chat-Last-Name'] = auth.lastName
+  if (auth?.avatarUrl) headers['X-Chat-Avatar-Url'] = auth.avatarUrl
+  return { url, headers }
+}

package/src/components/chat/utils/chip-action-class.ts

@@ -0,0 +1,19 @@
+/**
+ * Single CSS string for chip-density action buttons (Recent / Search /
+ * Find / Display, plus the inline Display popover's submit / cancel
+ * buttons).
+ *
+ * Shared between the empty-state chip's action row and the
+ * `<DisplayChipAction>` popover so both render with byte-equivalent
+ * styling — no per-call ad-hoc Tailwind chain that drifts over time.
+ *
+ * Sizing intent: 11px font + tight `px-2 py-1` padding lands below UI-Kit
+ * `Button size="small"` (24-32px min-height). These are chip-density
+ * action buttons, not standard buttons — they sit inside the empty-state
+ * chip card's tertiary action row.
+ */
+export const CHIP_ACTION_BUTTON_CLASS =
+  'text-[11px] font-medium text-ods-text-secondary hover:text-ods-text-primary ' +
+  'bg-transparent hover:bg-ods-card-hover border border-ods-border rounded-md ' +
+  'px-2 py-1 transition-colors focus-visible:outline-none focus-visible:ring-2 ' +
+  'focus-visible:ring-ods-focus'

package/src/components/chat/utils/chip-styles.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared className generator for the chat-adjacent UI family:
+ *  - **Source chips** (citation list below an assistant turn)
+ *  - **Inline entity-card pills** (within prose, marker-rendered)
+ *  - **Search-result rows** (dropdown beneath the search input)
+ *
+ * Centralising the token here means a single ODS change propagates to
+ * every surface — chip / card / dropdown row read as the same family.
+ *
+ * The `tone` arg controls the resting text color:
+ *  - `secondary` — citation chips and tertiary metadata. Muted resting.
+ *  - `primary`   — chips that ARE the subject of the sentence. Matches
+ *    body text color so the chip reads as content, not metadata.
+ *
+ * The `density` arg controls size / padding:
+ *  - `'chip'`     — inline pill (`px-2 py-0.5 text-[11px]`). Default;
+ *    used by the citation row and inline entity-card markers.
+ *  - `'list-row'` — wider, taller row (`px-3 py-2 text-sm`). Used by
+ *    the search-bar dropdown. Same ODS family — same border, hover
+ *    transition, accent treatment — just larger touch target.
+ *  - `'card-row'` — for the tracking strip beneath a card frame
+ *    (`px-2 py-1 text-[11px]` no border). Same family, no frame.
+ */
+export interface ChipClassOptions {
+  tone: 'primary' | 'secondary'
+  /** Visual density. Defaults to `'chip'`. */
+  density?: 'chip' | 'list-row' | 'card-row'
+  /** Extra classes appended verbatim (e.g. `cursor-pointer`). */
+  extra?: string
+}
+
+export function chatChipClass({ tone, density = 'chip', extra }: ChipClassOptions): string {
+  const toneClass = tone === 'primary' ? 'text-ods-text-primary' : 'text-ods-text-secondary'
+  // Size / padding by density. All three share the same border + hover
+  // semantics so a chip and a search-row read as the same UI family.
+  const sizeClass = density === 'list-row'
+    ? 'px-3 py-2 text-sm gap-2'
+    : density === 'card-row'
+      ? 'px-2 py-1 text-[11px] gap-1.5'
+      : 'px-2 py-0.5 text-[11px] gap-1.5'
+  // `card-row` is the "no-frame" variant — no border, no card bg, so it
+  // sits cleanly under a card without visually wrapping it.
+  const frameClass = density === 'card-row'
+    ? ''
+    : 'bg-ods-card border border-ods-border rounded'
+  const base =
+    `inline-flex items-center ${sizeClass} ${frameClass} ` +
+    `${toneClass} ` +
+    'hover:text-ods-accent hover:border-ods-accent transition-colors align-baseline'
+  return extra ? `${base} ${extra}` : base
+}