@flamingo-stack/openframe-frontend-core 0.0.568 → 0.0.569

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.568",
+  "version": "0.0.569",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/chat/hooks/use-chat-attachments.ts

@@ -9,7 +9,7 @@
  * `AbortController` for clean remove-mid-upload.
  *
  * Auth propagation:
- *   - `chatAuthedFetch` carries bearer-act-as headers + Supabase
+ *   - `embedAuthedFetch` carries bearer-act-as headers + Supabase
  *     session cookies — used both for minting the upload URL and as
  *     the auth path before falling through to the signed PUT.
  *   - The byte-PUT to the signed URL uses an inline `uploadWithProgress`
@@ -26,7 +26,7 @@
 import { useCallback, useMemo, useRef, useState } from 'react'
 import { fileTypeFromBlob } from 'file-type'
 import { useRequiredChatRuntime } from '../../../contexts/chat-runtime-context'
-import { chatAuthedFetch } from '../utils/chat-authed-fetch'
+import { embedAuthedFetch } from '../../../utils/embed-authed-fetch'
 import {
   CHAT_ATTACHMENT_MIME_TYPES,
   CHAT_ATTACHMENT_CONCURRENT_UPLOADS_PER_USER,
@@ -243,7 +243,7 @@ export function useChatAttachments(): UseChatAttachmentsApi {
         //    bearer-act-as headers (if present).
         updateOne(att.id, { status: 'uploading', progress: 5 })
 
-        const urlResp = await chatAuthedFetch(uploadUrlEndpoint, {
+        const urlResp = await embedAuthedFetch(uploadUrlEndpoint, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           signal: ctrl?.signal,

package/src/components/chat/hooks/use-chat-history-hydration.ts

@@ -19,7 +19,7 @@
 
 import { useEffect, useRef, useState, type MutableRefObject } from 'react'
 import type { Message } from './use-chat'
-import { chatAuthedFetch } from '../utils/chat-authed-fetch'
+import { embedAuthedFetch } from '../../../utils/embed-authed-fetch'
 import { AUTO_CONTINUATION_DIRECTIVE_PREFIX } from '../utils/auto-continuation-directive'
 
 export interface UseChatHistoryHydrationArgs {
@@ -79,7 +79,7 @@ export function useChatHistoryHydration({
     setIsHydratingHistory(true)
     ;(async () => {
       try {
-        const res = await chatAuthedFetch(
+        const res = await embedAuthedFetch(
           `${historyUrl}?conversationId=${encodeURIComponent(conversationId)}`,
           { method: 'GET' },
         )

package/src/components/chat/hooks/use-chat-identity.ts

@@ -43,8 +43,8 @@
 
 import { createContext, createElement, useContext, useEffect, useState, type ReactNode } from 'react'
 import { useRequiredChatRuntime } from '../../../contexts/chat-runtime-context'
-import { chatAuthedFetch } from '../utils/chat-authed-fetch'
-import { getChatProxyAuth } from '../utils/chat-proxy-auth-storage'
+import { embedAuthedFetch } from '../../../utils/embed-authed-fetch'
+import { getEmbedProxyAuth } from '../../../utils/embed-proxy-auth-storage'
 
 /**
  * Wire-shape for the identity route response. Mirrors the hub's
@@ -109,10 +109,10 @@ const ANON_DEFAULTS: ChatIdentityResponse = {
 function useResolveChatIdentity(enabled: boolean): ChatIdentitySurface {
   const runtime = useRequiredChatRuntime()
   const url = runtime.endpoints.identityUrl
-  // `getChatProxyAuth()` reads localStorage every render. If the user
+  // `getEmbedProxyAuth()` reads localStorage every render. If the user
   // pastes bearer creds mid-session (via the `/debug` creds bar),
   // their email arrives here and the effect's dep changes → refetch.
-  const proxyEmail = getChatProxyAuth()?.email ?? null
+  const proxyEmail = getEmbedProxyAuth()?.email ?? null
 
   const [data, setData] = useState<ChatIdentityResponse>(ANON_DEFAULTS)
   // Only "loading" if THIS instance will actually fetch. A disabled
@@ -126,7 +126,7 @@ function useResolveChatIdentity(enabled: boolean): ChatIdentitySurface {
     const ctrl = new AbortController()
 
     setIsLoading(true)
-    chatAuthedFetch(url, { signal: ctrl.signal })
+    embedAuthedFetch(url, { signal: ctrl.signal })
       .then(async (resp) => {
         if (!resp.ok) return ANON_DEFAULTS
         return (await resp.json()) as ChatIdentityResponse

package/src/components/chat/hooks/use-sse-chat-adapter.ts

@@ -57,7 +57,7 @@ import type { ChatRef } from '../chat-ref.types'
 import type { Message } from '../types/message.types'
 import type { MessageSegment } from '../types/message.types'
 import { useSlashCommandRegistry, type SlashCommandSummary } from './use-slash-commands'
-import { chatAuthedFetch } from '../utils/chat-authed-fetch'
+import { embedAuthedFetch } from '../../../utils/embed-authed-fetch'
 import type { ScrollAnchor } from '../utils/scroll-anchor'
 import { buildConfirmToolBody, readServerErrorMessage } from '../../../chat-protocol/confirm-tool'
 import { createSseFrameDecoder } from '../../../chat-protocol/decode'
@@ -458,10 +458,10 @@ export function useSseChatAdapter(
       abortControllerRef.current = ctrl
 
       try {
-        // `chatAuthedFetch` carries the bearer-act-as headers (+ Supabase
+        // `embedAuthedFetch` carries the bearer-act-as headers (+ Supabase
         // session cookies) — same wrapper `use-chat-attachments` and
         // `use-chat-identity` use.
-        const response = await chatAuthedFetch(targetPath, {
+        const response = await embedAuthedFetch(targetPath, {
           method: 'POST',
           body: JSON.stringify(requestBody),
           signal: ctrl.signal,

package/src/components/chat/utils/.index.md

@@ -8,7 +8,7 @@ Barrel export module that consolidates and re-exports all message processing, ch
 | **Message Accumulation** | `MessageSegmentAccumulator`, `createMessageSegmentAccumulator`, `AccumulatorCallbacks` |
 | **Historical Messages** | `processHistoricalMessages`, `extractErrorMessages`, `processHistoricalMessagesWithErrors` |
 | **Chat Navigation** | `handleChatNavClick`, `resolveExternalNavigation`, `decideNewTab`, `computeIsNewTab`, `buildAnchorProps` |
-| **Proxy Auth** | `getChatProxyAuth`, `setChatProxyAuth`, `clearChatProxyAuth`, `applyProxyAuth`, `chatAuthedFetch` |
+| **Proxy Auth** | moved to `utils/` — `getEmbedProxyAuth`, `setEmbedProxyAuth`, `clearEmbedProxyAuth`, `applyProxyAuth`, `embedAuthedFetch` |
 | **Attachments** | `formatChatAttachmentMarkdownForBubble`, `stripChatAttachmentMarkdown`, `buildChatAttachmentViewUrl` |
 | **UI / Styling** | `chatChipClass`, compact card class constants (`COMPACT_CARD_*`), `getStatusColorScheme` |
 | **Icon Registry** | `ICON_REGISTRY`, `getIconComponent`, `normalizeIconKey`, `getDynamicIcon` |
@@ -21,7 +21,6 @@ Barrel export module that consolidates and re-exports all message processing, ch
 import {
   createMessageSegmentAccumulator,
   handleChatNavClick,
-  getChatProxyAuth,
   getIconComponent,
   formatChatAttachmentMarkdownForBubble,
   decideNewTab,

package/src/components/chat/utils/chat-conversation-storage.ts

@@ -19,7 +19,7 @@ import {
   createLocalStorageAdapter,
   type LocalStorageAdapter,
 } from '../../../utils/local-storage-adapter'
-import { getChatProxyAuth } from './chat-proxy-auth-storage'
+import { getEmbedProxyAuth } from '../../../utils/embed-proxy-auth-storage'
 
 export interface PersistedChatConversation {
   conversationId: string
@@ -29,7 +29,7 @@ const STORAGE_KEY = 'conversation'
 
 const namespaceFor = (source: string): string => {
   const base = `mingo-chat-${source}`
-  const auth = getChatProxyAuth()
+  const auth = getEmbedProxyAuth()
   return auth?.email ? `${base}-u-${encodeURIComponent(auth.email.toLowerCase())}` : base
 }
 

package/src/components/chat/utils/index.ts

@@ -89,16 +89,9 @@ export {
   type RuntimeMode,
 } from './decide-new-tab'
 
-// Chat-proxy auth (localStorage adapter + fetch wrapper)
-export {
-  getChatProxyAuth,
-  getPersistedProxyEmail,
-  setChatProxyAuth,
-  clearChatProxyAuth,
-  applyProxyAuth,
-  type ChatProxyAuth,
-} from './chat-proxy-auth-storage'
-export { chatAuthedFetch } from './chat-authed-fetch'
+// Embed-surface auth moved to `utils/` (embed-proxy-auth-storage /
+// embed-authed-fetch) — import the Embed* names from
+// `@flamingo-stack/openframe-frontend-core/utils`.
 
 // Pure content helpers
 export { flattenAssistantContent } from './flatten-assistant-content'

package/src/components/embeds/claude-embed.tsx

@@ -4,6 +4,7 @@ import { ExternalLink } from 'lucide-react'
 import { Button } from '../ui/button/button'
 import { ClaudeIcon } from '../icons/claude-icon'
 import { EmbedViewerFrame } from './embed-viewer-frame'
+import { useClaudeMirrorSrc } from '../../hooks/use-claude-mirror-src'
 import { toClaudeEmbedUrl } from '../../utils/embed-url-converters'
 
 export type ClaudeEmbedKind = 'artifact' | 'design'
@@ -33,18 +34,29 @@ const KIND_HEADING: Record<ClaudeEmbedKind, string> = {
  * `{{claude-artifact:URL}}` / `{{claude-design:URL}}` shortcodes, so it looks
  * identical wherever markdown renders — a spec body, a comment, a links rail.
  *
- * A PUBLISHED artifact frames through its `/embed` route (`toClaudeEmbedUrl`).
- * Everything else has no embeddable route at all, and then `src` is null and
- * the shared frame shows its own empty state — the action stays either way, so
- * the artifact is always one click away.
+ * FRAME SOURCE — fully under the hood, in priority order:
+ *   1. The host's SELF-HOSTED MIRROR: the url's artifact id derives the
+ *      storage-view proxy path (`toClaudeMirrorPath`), probed with a
+ *      1-byte ranged fetch. When the host has ingested a copy, the frame
+ *      shows it — claude.ai frame-locks CODE artifacts entirely, so this
+ *      is the only way those ever render inline.
+ *   2. claude.ai's own `/embed` route for a PUBLISHED artifact
+ *      (`toClaudeEmbedUrl`).
+ *   3. Neither → the shared frame's empty state.
+ * The consumer passes only the claude URL; "Open in Claude" always
+ * targets it, so commenting stays on claude.ai.
  *
- * What defeats the frame: a Claude CODE url (no Embed settings exist for it,
- * and its `/embed` path answers `frame-ancestors 'self'`), a Claude Design url
- * (no embed route), an artifact whose author has not allow-listed this host,
- * or an http host (mixed content — it will not paint on `http://localhost`).
+ * What defeats the claude.ai leg: a Claude CODE url (no Embed settings
+ * exist for it, and its `/embed` path answers `frame-ancestors 'self'`),
+ * a Claude Design url (no embed route), an artifact whose author has not
+ * allow-listed this host, or an http host (mixed content).
  */
 export function ClaudeEmbed({ url, kind = 'artifact', title, height, loading = 'lazy' }: ClaudeEmbedProps) {
-  const embedUrl = toClaudeEmbedUrl(url)
+  // Mirror detection lives in `useClaudeMirrorSrc` (derive from
+  // EndpointsRuntime + 1-byte ranged probe) — this component stays
+  // presentational: mirror when the hook found one, claude.ai otherwise.
+  const mirrorSrc = useClaudeMirrorSrc(url)
+  const embedUrl = mirrorSrc ?? toClaudeEmbedUrl(url)
   return (
     <EmbedViewerFrame
       className="my-6 space-y-3"
@@ -65,6 +77,10 @@ export function ClaudeEmbed({ url, kind = 'artifact', title, height, loading = '
         </Button>
       }
       src={embedUrl}
+      // The framed artifact has no internal fullscreen button of its own
+      // (unlike Figma's player) — the shell provides the toggle for both
+      // the claude.ai `/embed` route and a mirror.
+      fullscreenControl
       loading={loading}
       height={height}
       // Same frame contract Figma gets — an artifact is a real app: it copies
@@ -72,11 +88,22 @@ export function ClaudeEmbed({ url, kind = 'artifact', title, height, loading = '
       allow="clipboard-write; clipboard-read; fullscreen"
       // …but UNLIKE Figma, an artifact is USER-AUTHORED HTML and JS, so it is
       // sandboxed. Omitting `allow-top-navigation` is the point: an artifact
-      // cannot navigate the page it is embedded in. `allow-same-origin` beside
-      // `allow-scripts` is what Anthropic's own embed snippet uses and is safe
-      // on a CROSS-ORIGIN frame — it grants the frame claude.ai's origin, never
-      // ours.
-      sandbox="allow-scripts allow-same-origin allow-popups allow-forms"
+      // cannot navigate the page it is embedded in. The `allow-same-origin`
+      // token is CONDITIONAL on where the frame points:
+      //   - claude.ai `/embed` (no mirror): Anthropic's own embed snippet
+      //     uses it, and on a CROSS-ORIGIN frame it grants the frame
+      //     claude.ai's origin — never ours. The artifact runtime needs
+      //     it (storage, postMessage handshake).
+      //   - the derived MIRROR is served from the HOST's OWN origin —
+      //     `allow-same-origin` + `allow-scripts` there would be a no-op
+      //     sandbox handing the artifact first-party cookies and
+      //     `window.parent`. A static mirror renders fine from an opaque
+      //     origin, so the token is dropped.
+      sandbox={
+        mirrorSrc
+          ? 'allow-scripts allow-popups allow-forms'
+          : 'allow-scripts allow-same-origin allow-popups allow-forms'
+      }
       allowFullScreen
       emptyIcon={<ClaudeIcon className="w-16 h-16 mb-4" />}
       emptyMessage="Open this one in Claude · it has no embeddable view"

package/src/components/embeds/embed-viewer-frame.tsx

@@ -1,7 +1,10 @@
 'use client'
 
-import React from 'react'
+import React, { useEffect, useRef, useState } from 'react'
+import { Maximize2, Minimize2 } from 'lucide-react'
 import { cn } from '../../utils/cn'
+import { FullscreenSwitchController } from '../../utils/fullscreen-switch'
+import { Button } from '../ui/button/button'
 import { EmbedIframe } from './embed-iframe'
 
 /**
@@ -47,6 +50,13 @@ export interface EmbedViewerFrameProps {
   sandbox?: string
   /** Wrapper classes; defaults to the sheets/pdf `space-y-4`. */
   className?: string
+  /** Opt-in fullscreen toggle in the header row (rendered after `actions`,
+   *  only when there is a `src`). Fullscreens the WHOLE frame — header
+   *  included — so the exit control stays reachable (Esc works too).
+   *  Exists because some embedded contents ship their own fullscreen
+   *  button (the Figma player) and some cannot (a self-hosted Claude
+   *  artifact mirror) — the shell provides the affordance uniformly. */
+  fullscreenControl?: boolean
 }
 
 export function EmbedViewerFrame({
@@ -63,9 +73,45 @@ export function EmbedViewerFrame({
   loading,
   sandbox,
   className,
+  fullscreenControl,
 }: EmbedViewerFrameProps) {
+  const frameRef = useRef<HTMLDivElement>(null)
+  const [isFullscreen, setIsFullscreen] = useState(false)
+
+  // ONE fullscreen implementation across the library and its hosts:
+  // `FullscreenSwitchController` (shared with the hub's deck) owns the
+  // Fullscreen API calls, webkit fallbacks, rejection safety, and the
+  // change-event-driven state — Esc, F11, buttons and browser chrome all
+  // converge on its listener, so the icon can never desync. Here it runs
+  // element-level (`target` = this frame; no mask classes — the frame
+  // styles off its own state).
+  const controllerRef = useRef<FullscreenSwitchController | null>(null)
+  useEffect(() => {
+    if (!fullscreenControl) return
+    const controller = new FullscreenSwitchController({
+      target: () => frameRef.current,
+      onFullscreenChange: setIsFullscreen,
+    })
+    controllerRef.current = controller
+    controller.attach()
+    return () => {
+      controllerRef.current = null
+      controller.detach()
+    }
+  }, [fullscreenControl])
+  const toggleFullscreen = () => controllerRef.current?.toggle()
+
   return (
-    <div className={cn('space-y-4', className)}>
+    <div
+      ref={frameRef}
+      className={cn(
+        'space-y-[var(--spacing-system-mf)]',
+        className,
+        // Fullscreen paints its own ground (the fullscreened element
+        // otherwise sits on the UA's black backdrop) and scrolls itself.
+        isFullscreen && 'overflow-auto bg-ods-bg p-[var(--spacing-system-mf)]',
+      )}
+    >
       <div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
         <div className="flex items-center gap-2 min-w-0">
           {icon}
@@ -75,13 +121,40 @@ export function EmbedViewerFrame({
             <span className="text-h6 font-semibold text-ods-text-primary truncate">{title}</span>
           )}
         </div>
-        {actions}
+        {/* Same responsive action-row idiom as the PDF viewer's button pair
+            and every viewer's own action: full-width stacked on mobile,
+            inline row from `sm:` up, SAME Button idiom (outline /
+            small-legacy / w-4 icon / w-full sm:w-auto). Without the
+            fullscreen toggle, `actions` renders EXACTLY as before — the
+            wrapper exists only when the toggle joins it, so pre-existing
+            viewers (figma/pdf/sheets) are byte-identical. */}
+        {fullscreenControl && src ? (
+          <div className="flex flex-col gap-[var(--spacing-system-xsf)] sm:flex-row sm:items-center">
+            {actions}
+            <Button
+              variant="outline"
+              size="small-legacy"
+              onClick={toggleFullscreen}
+              aria-label={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
+              leftIcon={isFullscreen ? <Minimize2 className="w-4 h-4" /> : <Maximize2 className="w-4 h-4" />}
+              className="w-full sm:w-auto"
+            >
+              {isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
+            </Button>
+          </div>
+        ) : (
+          actions
+        )}
       </div>
       {src ? (
         <EmbedIframe
           src={src}
           title={title}
-          height={height}
+          // 96px = the fullscreen wrapper's own chrome above the iframe:
+          // header row (~40px incl. its gap) + the wrapper's mf padding
+          // (16px × 2) + the mf space-y gap (16px), rounded up so the
+          // frame never forces a scrollbar. Recheck if that chrome changes.
+          height={isFullscreen ? 'calc(100vh - 96px)' : height}
           allow={allow}
           allowFullScreen={allowFullScreen}
           loading={loading}

package/src/components/ui/markdown/__tests__/sanitize-invariant.test.ts

@@ -16,6 +16,7 @@ import {
   buildEffectiveTagSet,
   buildSanitizeSchema,
   escapeUnknownHtmlTags,
+  rehypeStripUnsafe,
   SAFE_HTML_TAGS,
   SVG_TAGS,
 } from '../sanitize'
@@ -352,3 +353,32 @@ describe('link-definition shelters blank in every shape (round 21)', () => {
     expect(masked).toContain('## after heading')
   })
 })
+
+describe('URL_ATTRS covers hast PROPERTY keys, not attribute names', () => {
+  it('strips a javascript: data-url via its camelized hast key', () => {
+    // property-information camelizes `data-url` to `dataUrl` BEFORE the
+    // strip pass runs - the URL_ATTRS entry must match the lowercased
+    // PROPERTY key or the scheme check silently never fires.
+    const tree = {
+      type: 'root',
+      children: [
+        {
+          type: 'element',
+          tagName: 'div',
+          properties: {
+            className: ['claude-embed'],
+            dataUrl: 'javascript:alert(1)',
+            dataKind: 'artifact',
+          },
+          children: [],
+        },
+      ],
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ;(rehypeStripUnsafe() as (t: unknown) => void)(tree as any)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const props = (tree.children[0] as any).properties
+    expect(props.dataUrl).toBeUndefined()
+    expect(props.dataKind).toBe('artifact')
+  })
+})

package/src/components/ui/markdown/rich/__tests__/shortcodes.test.ts

@@ -91,6 +91,14 @@ describe('processShortcodes design-doc embeds', () => {
     expect(design).toContain('data-kind="design"');
   });
 
+  it('threads the optional pipe title into data-title', () => {
+    const titled = processShortcodes('{{claude-artifact:https://claude.ai/a|Brief doc}}');
+    expect(titled).toContain('data-title="Brief doc"');
+
+    const untitled = processShortcodes('{{claude-artifact:https://claude.ai/a}}');
+    expect(untitled).not.toContain('data-title');
+  });
+
   it('escapes the url attribute so a crafted link cannot break out of the block', () => {
     const output = processShortcodes('{{claude-artifact:https://claude.ai/a"><script>alert(1)</script>}}');
     expect(output).not.toContain('<script>');

package/src/components/ui/markdown/sanitize.ts

@@ -395,6 +395,10 @@ const URL_ATTRS = new Set([
   'data',
   'action',
   'background',
+  // The embed shortcodes' primary url (`data-url` → `dataUrl`) — it
+  // becomes an anchor href ("Open in Claude") and a link-preview fetch
+  // target, so a `javascript:`/`data:` scheme there is a live sink too.
+  'dataurl',
 ])
 
 /**

package/src/components/ui/table/table.tsx

@@ -21,6 +21,7 @@ function injectSyntheticColumns<T>(
   rowActions?: RowAction<T>[],
   renderRowActions?: (item: T) => ReactNode,
   rowHref?: (item: T) => string | null | undefined,
+  actionsColumnWidth?: string,
 ): TableColumn<T>[] {
   const hasActions = Boolean(rowActions?.length) || Boolean(renderRowActions)
   const result = [...columns]
@@ -29,7 +30,10 @@ function injectSyntheticColumns<T>(
     const actionsColumn: TableColumn<T> = {
       key: '__actions__',
       label: '',
-      width: 'min-w-[100px] w-auto shrink-0 flex-none',
+      // A caller-fixed width keeps the header and every row on ONE grid
+      // (see `actionsColumnWidth` in types.ts); the default stays
+      // content-sized for back-compat.
+      width: actionsColumnWidth ?? 'min-w-[100px] w-auto shrink-0 flex-none',
       align: 'right',
       renderCell: (item: T) => (
         <div className="flex gap-2 items-center justify-end pointer-events-auto" data-no-row-click>
@@ -120,11 +124,12 @@ export function Table<T = any>({
   stickyHeader,
   stickyHeaderOffset,
   animateRowReorder,
+  actionsColumnWidth,
 }: TableProps<T>) {
   // Opt-in row-reorder animation: framer-motion is loaded lazily (its own chunk)
   // ONLY when `animateRowReorder` is set, so the default table stays motion-free.
   const tableMotion = useTableMotion(Boolean(animateRowReorder))
-  const columnsWithActions = injectSyntheticColumns(columns, rowActions, renderRowActions, rowHref)
+  const columnsWithActions = injectSyntheticColumns(columns, rowActions, renderRowActions, rowHref, actionsColumnWidth)
   const getRowHref = (item: T): string | undefined => {
     if (onRowClick || !rowHref) return undefined
     return rowHref(item) ?? undefined

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

@@ -110,6 +110,15 @@ export interface TableProps<T = any> {
   rowActions?: RowAction<T>[]
   // Custom renderer for the actions area (e.g., kebab/dots menu)
   renderRowActions?: (item: T) => ReactNode
+  /**
+   * Width class(es) for the synthetic actions column. The default is
+   * content-sized (`w-auto`), which mis-aligns every OTHER column between
+   * the header and the rows whenever the row actions are wider than the
+   * header's "Showing N results" counter (each side sizes to its own
+   * content). Pass a FIXED width (e.g. `w-60`) when the actions are wide
+   * text buttons so the header and rows share one grid.
+   */
+  actionsColumnWidth?: string
 
   /**
    * When provided, renders a right-pointing chevron link at the end of every row

package/src/contexts/endpoints-runtime-context.tsx

@@ -34,6 +34,12 @@ export interface EndpointsRuntime {
   }
   /** POST contact-form submission. */
   contactUrl: string
+  /** GET base of the host's private-storage view proxy
+   *  (`<base>/<bucket>/<object>`). `ClaudeEmbed` derives artifact mirror
+   *  urls under it (`<base>/design-briefs/<uuid>.html`). OPTIONAL: a host
+   *  without the proxy simply omits it and claude embeds fall back to
+   *  claude.ai — no probing happens. */
+  storageViewBaseUrl?: string
 }
 
 export const EndpointsRuntimeContext = createContext<EndpointsRuntime | null>(null)

package/src/hooks/index.ts

@@ -29,6 +29,10 @@ export * from './use-access-code-integration'
 // THE og-placeholder URL hook (endpoints-driven; no injected builder)
 export * from './use-og-placeholder-url'
 
+// Claude artifact mirror detection (endpoints-driven; ClaudeEmbed's
+// transparent mirror leg)
+export * from './use-claude-mirror-src'
+
 // Deep-link "scroll to URL hash" after data loads. Pairs with URL
 // composers that emit `?<filter>=<id>#<prefix>-<id>` — the filter
 // narrows the list, the hash scrolls the matching DOM id.

package/src/hooks/use-claude-mirror-src.ts

@@ -0,0 +1,43 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useEndpointsRuntime } from '../contexts/endpoints-runtime-context'
+import { toClaudeMirrorPath } from '../utils/embed-url-converters'
+
+/**
+ * The host's SELF-HOSTED MIRROR src for a claude artifact url, or `null`
+ * while none is known — THE hook behind `ClaudeEmbed`'s transparent
+ * mirror leg, extracted so the component stays presentational.
+ *
+ * Fully under the hood: derives the candidate mirror path from the url's
+ * artifact id under the host's configured storage-view proxy base
+ * (`EndpointsRuntime.storageViewBaseUrl` — the SAME proxy-path mechanism
+ * as every other lib→API call) and probes it with a 1-byte ranged GET
+ * (the proxy forwards Range, so the probe costs nothing). Exists → the
+ * mirror path; missing / no proxy / network blip → `null`, and the
+ * caller's claude.ai fallback is exactly the pre-mirror behavior. A host
+ * that mounts no EndpointsRuntime provider (or omits the entry) skips
+ * the mirror leg entirely.
+ */
+export function useClaudeMirrorSrc(url: string): string | null {
+  const endpoints = useEndpointsRuntime()
+  const mirrorPath = toClaudeMirrorPath(url, endpoints?.storageViewBaseUrl)
+  const [mirrorSrc, setMirrorSrc] = useState<string | null>(null)
+  useEffect(() => {
+    setMirrorSrc(null)
+    if (!mirrorPath) return
+    let cancelled = false
+    fetch(mirrorPath, { headers: { Range: 'bytes=0-0' } })
+      .then(res => {
+        if (!cancelled && (res.ok || res.status === 206)) setMirrorSrc(mirrorPath)
+      })
+      .catch(() => {
+        // No proxy on this host / network blip — the caller's claude.ai
+        // fallback stands, same as before mirrors existed.
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [mirrorPath])
+  return mirrorSrc
+}

package/src/utils/.embed-proxy-auth-storage.md

@@ -1,5 +1,5 @@
 <!-- source-hash: 4f6996d4ad0ba284b64e13807891eb62 -->
-Manages client-side persistence of embed-surface proxy credentials (`CHAT_PROXY_SECRET` + impersonation email) in `localStorage`, enabling embedded surfaces (chat widget, ticket center, etc.) to authenticate as a proxied customer across sessions.
+Manages client-side persistence of embed-surface proxy credentials (a platform API key + impersonation email) in `localStorage`, enabling embedded surfaces (chat widget, ticket center, etc.) to authenticate as a proxied customer across sessions.
 
 ## Key Components
 
@@ -35,4 +35,4 @@ const response = await fetch(url, { method: 'POST', headers })
 clearEmbedProxyAuth()
 ```
 
-> **Security note:** Credentials persist in `localStorage` (survives tab close and browser restart). This is intentional — re-pasting on every tab was rejected as a dev-experience tradeoff. The `/debug` entry point is admin-gated, and all headers are server-validated against `CHAT_PROXY_SECRET`.
+> **Security note:** Credentials persist in `localStorage` (survives tab close and browser restart). This is intentional — re-pasting on every tab was rejected as a dev-experience tradeoff. The `/debug` entry point is admin-gated, and all headers are server-validated against the hash-at-rest platform API key store (revocable in `/admin/api-keys`).

package/src/utils/embed-proxy-auth-storage.ts

@@ -1,24 +1,28 @@
 'use client'
 
 /**
- * Client-side persistence for embed-surface proxy credentials
- * (`CHAT_PROXY_SECRET` + impersonation email). Used by every embedded
+ * Client-side persistence for embed-surface proxy credentials (a
+ * PLATFORM API KEY + impersonation email). Used by every embedded
  * surface — the chat widget AND the ticket center AND any future
  * embedded React component that needs to identify itself as the
  * impersonated customer.
  *
  * When set, the surface attaches the creds as
- *   `Authorization: Bearer <secret>` + `X-Chat-Act-As: <email>`
+ *   `Authorization: Bearer <platform API key>` + `X-Chat-Act-As: <email>`
  * on every call to `/api/docs/chat`, `/api/chat/*`, and any other route
  * gated by `requireChatAuth` — proving to the server that this session
- * is acting on behalf of <email>.
+ * is acting on behalf of <email>. The key is minted in the hub's
+ * `/admin/api-keys` and is platform-bound (`fpk_<platform>_…`): a
+ * SERVICE key may act as any email; a PERSONAL key only as its owner.
  *
- * **Naming history:** the wire-side header names are still `X-Chat-*`
- * and the env var is `CHAT_PROXY_SECRET`. Those are server contracts;
- * renaming them would require a coordinated deploy + customer-side
- * env-var migration. The CLIENT-side helpers were renamed `Embed*` so
- * non-chat surfaces (e.g. ticket center) don't have to import a
- * chat-prefixed symbol just to send the same headers.
+ * **Naming history:** the stored field is still named `secret` and the
+ * wire-side header names are `X-Chat-*`. Those are client/server
+ * contracts predating the per-platform key migration (the old shared
+ * `CHAT_PROXY_SECRET` env is removed hub-side); renaming them would
+ * break persisted state + the wire shape for zero behavior change. The
+ * CLIENT-side helpers were renamed `Embed*` so non-chat surfaces (e.g.
+ * ticket center) don't have to import a chat-prefixed symbol just to
+ * send the same headers.
  *
  * Persists to **`localStorage`** so the bearer token + act-as identity
  * survive tab close, new-tab opens, and browser restarts — the
@@ -26,10 +30,11 @@
  * cycle was rejected as a dev-experience tradeoff that wasn't worth
  * the security gain. An XSS sink on this origin can read the value
  * indefinitely (vs only-this-tab with sessionStorage), but `/debug`
- * is admin-gated behind the platform's `askAI.enabled` flag and the
- * impersonation header it sets is server-validated against
- * `CHAT_PROXY_SECRET` anyway. Explicit "Clear" button on the creds
- * bar is the supported logout path; closing the tab is no longer.
+ * is admin-gated behind the platform's `askAI.enabled` flag, the key
+ * is server-verified (hash-at-rest, platform-bound, revocable in
+ * `/admin/api-keys`), and the act-as reach is bounded by the key's
+ * tier. Explicit "Clear" button on the creds bar is the supported
+ * logout path; closing the tab is no longer.
  *
  * Namespaced under `<platform>.chat.proxy-auth.v1` (the storage key is
  * unchanged from the old chat-prefixed helper — that's a storage