@flamingo-stack/openframe-frontend-core 0.0.218 → 0.0.219

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

@@ -28,6 +28,7 @@ import { getIconComponent } from './icon-registry'
 import { getBaseUrl } from '../../../utils/cn'
 import { safeHref } from './compact-card-classes'
 import type { ChatRef } from '../chat-ref.types'
+import type { ComposeContentUrl } from '../../../utils/content-href'
 
 /** Path sanitization — keep alphanumerics, slash, dash, dot, underscore;
  *  strip everything else. Defends against a hostile mapper returning a
@@ -77,6 +78,26 @@ export interface SourceRowContext {
    * keeps the FileText icon.
    */
   tableIdForDocumentType?: (documentType: string) => string | null
+  /**
+   * Host-supplied unified content-href resolver (`runtime.composeContentUrl`).
+   * When provided, entity rows WITH a public `externalUrl` resolve their href
+   * through it — so the host's `hostedTypes` / `overrides` route a chat card to
+   * the SAME destination as the equivalent page-view card (in-app for hosted
+   * types, the hub URL otherwise). When omitted, the row's `externalUrl` is used
+   * verbatim (legacy).
+   */
+  composeContentUrl?: ComposeContentUrl
+  /**
+   * Host-supplied per-`documentType` doc-viewer targets — the UNIFIED, DYNAMIC
+   * replacement for the single `chipBasePlatform`. Maps a doc-table documentType
+   * (`'markdown'`, `'data_room_doc'`, …) → the platform whose PUBLIC doc viewer
+   * hosts it + that viewer's base path. A doc chip with no `externalUrl` resolves
+   * to `getBaseUrl(platform)/<basePath>/<path>` PER ROW — so a chat mixing several
+   * doc sources sends EACH to its own home (markdown→flamingo/knowledge-base,
+   * data_room_doc→company-hub/data-room) instead of one static fallback for all.
+   * Wins over `chipBasePlatform` when a row's documentType has an entry.
+   */
+  docPlatformTargets?: Record<string, { platform: string; basePath: string }>
 }
 
 export interface SourceRowCTA {
@@ -96,6 +117,30 @@ export interface SourceRowCTA {
   chatRef: ChatRef | null
 }
 
+/**
+ * Build a `SourceRowContext` from a `ChatRuntime` + the surface's `baseRoute` /
+ * `chipBasePlatform`. The runtime-derived fields (`currentPlatform`, `composeContentUrl`,
+ * `docPlatformTargets`) are wired identically at every `resolveSourceRowCTA` call site
+ * (source chips + inline cards), so they live here once — adding a ctx field is then a
+ * one-line change instead of editing all three call sites.
+ */
+export function sourceRowCtxFromRuntime(
+  runtime: {
+    source?: string
+    composeContentUrl?: ComposeContentUrl
+    docPlatformTargets?: SourceRowContext['docPlatformTargets']
+  },
+  surface: { baseRoute?: string; chipBasePlatform?: string } = {},
+): SourceRowContext {
+  return {
+    currentPlatform: runtime.source ?? null,
+    composeContentUrl: runtime.composeContentUrl,
+    docPlatformTargets: runtime.docPlatformTargets,
+    baseRoute: surface.baseRoute,
+    chipBasePlatform: surface.chipBasePlatform,
+  }
+}
+
 /**
  * Pure icon-resolution helper — `sourceRepo` (RagTableConfig.id) →
  * icon_name via `SOURCE_ICON_NAMES`, then icon_name → React component
@@ -109,14 +154,20 @@ function pickSourceIcon(sourceRepo: string | null, documentType: string | null |
 }
 
 /**
- * Only certain row kinds should fall back to in-app `path` navigation
- * when no `externalUrl` is set. Specifically: doc-tables (markdown,
- * data-room PDFs) that the in-app doc viewer can render. Entity-table
+ * Doc-table documentTypes — rows that carry an in-app `path` (not an entity
+ * `externalUrl`) and resolve to a doc viewer. The SAME set an embedder keys its
+ * `docPlatformTargets` map by (markdown = product docs, data_room_doc = data room),
+ * declared once so the two can't silently diverge.
+ */
+export const DOC_TABLE_TYPES = ['markdown', 'data_room_doc'] as const
+
+/**
+ * Only doc-table rows (DOC_TABLE_TYPES) fall back to doc-viewer navigation when no
+ * `externalUrl` is set; the in-app/per-platform viewer can render them. Entity-table
  * rows MUST come with an explicit `externalUrl` from the mapper.
  */
 function shouldFallbackToPathNav(row: SourceRowInput): boolean {
-  const t = row.documentType
-  return t === 'markdown' || t === 'data_room_doc'
+  return !!row.documentType && (DOC_TABLE_TYPES as readonly string[]).includes(row.documentType)
 }
 
 /**
@@ -138,32 +189,64 @@ export function resolveSourceRowCTA(
 
   const { icon, iconLabel } = pickSourceIcon(sourceRepo, row.documentType)
 
-  // URL resolution.
+  // URL resolution. `idValue` (row primary key) is shared with the Ask
+  // drill-in check below.
   let href: string | null = null
   let targetPlatform: string | null = null
-  if (row.externalUrl) {
-    href = safeHref(row.externalUrl) ?? null
-    targetPlatform = row.targetPlatform ?? null
-  } else if (ctx.baseRoute && row.path && shouldFallbackToPathNav(row)) {
+  const idValue = (row.id ?? '').trim()
+  if (row.path && shouldFallbackToPathNav(row) && !row.externalUrl) {
+    // Doc-table (markdown / data-room PDF) with no public URL. Resolve where its
+    // viewer lives, in priority order (NOT a content type the composeContentUrl
+    // seam knows — docs carry a tree `path`, not a slug/id):
+    //   1. docPlatformTargets[documentType] — per-doc-type cross-platform target.
+    //      The UNIFIED, DYNAMIC path: a chat mixing multiple doc sources routes
+    //      EACH row to its own home (markdown→flamingo, data_room_doc→company-hub).
+    //   2. chipBasePlatform — legacy SINGLE cross-platform fallback (one platform
+    //      for every doc; only safe when a surface sees just one doc source).
+    //   3. baseRoute — the host serves the doc viewer in-app → relative path nav.
+    //   else → null (no viewer configured → Ask-only).
     const safePath = sanitizePath(row.path)
     if (safePath) {
-      if (ctx.chipBasePlatform) {
+      const docTarget = row.documentType ? ctx.docPlatformTargets?.[row.documentType] : undefined
+      if (docTarget) {
+        // Trim leading/trailing (and collapse empty) segments WITHOUT a regex — the
+        // slash-stripping regex `/^\/+|\/+$/g` tripped CodeQL's js/polynomial-redos (high)
+        // since `\/+$` backtracks on inputs with many '/'. split/filter/join is linear.
+        const seg = docTarget.basePath.split('/').filter(Boolean).join('/')
+        const base = `${getBaseUrl(docTarget.platform)}${seg ? `/${seg}` : ''}/`
+        href = safeHref(new URL(safePath, base).toString()) ?? null
+        targetPlatform = docTarget.platform
+      } else if (ctx.chipBasePlatform) {
         const base = `${getBaseUrl(ctx.chipBasePlatform)}/knowledge-base/`
-        href = new URL(safePath, base).toString()
+        href = safeHref(new URL(safePath, base).toString()) ?? null
         targetPlatform = ctx.chipBasePlatform
-      } else {
+      } else if (ctx.baseRoute) {
         const synthetic = `https://_internal_.local${ctx.baseRoute.startsWith('/') ? ctx.baseRoute : '/' + ctx.baseRoute}/`
         const absolute = new URL(safePath, synthetic).toString()
-        href = absolute.replace('https://_internal_.local', '')
+        href = safeHref(absolute.replace('https://_internal_.local', '')) ?? null
         targetPlatform = ctx.currentPlatform ?? null
       }
-      // Final safeHref pass on the composed URL — defense-in-depth.
-      href = safeHref(href) ?? null
     }
+  } else if (ctx.composeContentUrl && row.documentType && row.externalUrl) {
+    // Entity content WITH a public viewer → the unified content-href seam. The
+    // host's hostedTypes/overrides route hosted types in-app (slug relativized
+    // from the externalUrl) and everything else to the externalUrl verbatim —
+    // the SAME resolver the page-view cards use, so chat + page links match.
+    const composed = ctx.composeContentUrl({
+      type: row.documentType,
+      identifier: idValue,
+      externalUrl: row.externalUrl,
+      targetPlatform: row.targetPlatform ?? null,
+    })
+    href = composed.href ? (safeHref(composed.href) ?? null) : null
+    targetPlatform = composed.targetPlatform
+  } else if (row.externalUrl) {
+    // No composer wired → legacy: the RAG externalUrl verbatim.
+    href = safeHref(row.externalUrl) ?? null
+    targetPlatform = row.targetPlatform ?? null
   }
 
-  // Ask drill-in viability.
-  const idValue = (row.id ?? '').trim()
+  // Ask drill-in viability. (`idValue` computed above.)
   const askable = !!(idValue && row.documentType)
   const chatRef: ChatRef | null = askable
     ? ({

package/src/components/features/board/board-column-header.tsx

@@ -1,7 +1,7 @@
 'use client'
 
 import { Button } from '../../ui/button/button'
-import { TicketStatusTag, getTicketStatusConfig } from '../../ui/ticket-status-tag'
+import { TicketStatusTag, resolveTicketStatus } from '../../ui/ticket-status-tag'
 import { Arrow02LeftIcon, Arrow02RightIcon, PlusIcon } from '../../icons-v2-generated'
 import type { BoardColumnDef } from './types'
 
@@ -19,7 +19,10 @@ export function BoardColumnHeader({
   onAddTicket,
 }: BoardColumnHeaderProps) {
   const count = column.total ?? column.tickets.length
-  const useStatusVariant = !!getTicketStatusConfig(column.id).icon
+  const tagStatus = column.statusKey ?? column.id
+  // Known statuses (ACTIVE, RESOLVED, …) render with their canonical Tag
+  // variant/icon; only unrecognized ids (custom-status UUIDs) fall back to `color`.
+  const useStatusVariant = resolveTicketStatus(tagStatus) !== null
 
   if (collapsed) {
     return (
@@ -34,7 +37,7 @@ export function BoardColumnHeader({
           <Arrow02RightIcon className="h-6 w-6 text-ods-text-secondary" />
         </Button>
         <TicketStatusTag
-          status={column.id}
+          status={tagStatus}
           label={column.label}
           color={useStatusVariant ? undefined : column.color}
           className="h-auto [writing-mode:vertical-rl]"
@@ -50,7 +53,7 @@ export function BoardColumnHeader({
     <div className="flex items-center gap-[var(--spacing-system-xsf)]">
       <div className="flex min-w-0 flex-1 items-center gap-[var(--spacing-system-xsf)]">
         <TicketStatusTag
-          status={column.id}
+          status={tagStatus}
           label={column.label}
           color={useStatusVariant ? undefined : column.color}
         />

package/src/components/features/board/types.ts

@@ -24,6 +24,13 @@ export interface BoardTicket {
 
 export interface BoardColumnDef {
   id: string
+  /**
+   * Canonical status key for header styling (e.g. 'ACTIVE', 'RESOLVED'), when the
+   * column `id` is not itself a known status (e.g. a custom-status UUID). The
+   * header resolves its TicketStatusTag variant/icon from this, falling back to
+   * `id`. Leave undefined for custom statuses so they render from `color`.
+   */
+  statusKey?: string
   label: string
   color: string
   tickets: BoardTicket[]
@@ -49,6 +56,7 @@ export interface BoardChange {
 
 const STATUS_DEFAULTS: Record<TicketStatus, { label: string; color: string }> = {
   ACTIVE: { label: 'Active', color: '#5ea62e' },
+  AI_ASSISTANCE: { label: 'AI Assistance', color: '#888888' },
   TECH_REQUIRED: { label: 'Tech Required', color: '#e1b32f' },
   ON_HOLD: { label: 'On Hold', color: '#f36666' },
   RESOLVED: { label: 'Resolved', color: '#888888' },
@@ -83,6 +91,7 @@ export function groupTicketsByStatus(
 ): BoardColumnDef[] {
   const buckets: Record<TicketStatus, BoardTicket[]> = {
     ACTIVE: [],
+    AI_ASSISTANCE: [],
     TECH_REQUIRED: [],
     ON_HOLD: [],
     RESOLVED: [],
@@ -100,6 +109,7 @@ function canonicalize(status: string): TicketStatus | null {
   if (upper === 'ACTION_REQUIRED') return 'TECH_REQUIRED'
   if (
     upper === 'ACTIVE' ||
+    upper === 'AI_ASSISTANCE' ||
     upper === 'TECH_REQUIRED' ||
     upper === 'ON_HOLD' ||
     upper === 'RESOLVED' ||

package/src/components/features/index.ts

@@ -76,3 +76,4 @@ export * from './policy-configuration-panel'
 export * from './waitlist-form'
 export * from './notifications'
 export * from './board'
+export * from './ticket-status-config-list'

package/src/components/features/ticket-status-config-list/index.ts

@@ -0,0 +1 @@
+export * from './ticket-status-config-list'

package/src/components/features/ticket-status-config-list/ticket-status-config-list.tsx

@@ -0,0 +1,97 @@
+'use client'
+
+import {
+  DndContext,
+  type DragEndEvent,
+  type DraggableAttributes,
+  type DraggableSyntheticListeners,
+  KeyboardSensor,
+  PointerSensor,
+  closestCenter,
+  useSensor,
+  useSensors,
+} from '@dnd-kit/core'
+import {
+  SortableContext,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable'
+import { CSS } from '@dnd-kit/utilities'
+import * as React from 'react'
+import { cn } from '../../../utils/cn'
+
+export interface SortableRowRenderArgs {
+  dragHandleProps: DraggableSyntheticListeners
+  dragHandleAttributes: DraggableAttributes
+  isDragging: boolean
+}
+
+export interface TicketStatusConfigListProps<T extends { id: string }> {
+  items: T[]
+  onReorder: (oldIndex: number, newIndex: number) => void
+  renderRow: (item: T, args: SortableRowRenderArgs) => React.ReactNode
+  className?: string
+}
+
+export function TicketStatusConfigList<T extends { id: string }>({
+  items,
+  onReorder,
+  renderRow,
+  className,
+}: TicketStatusConfigListProps<T>) {
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 4 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  )
+
+  const handleDragEnd = (event: DragEndEvent) => {
+    const { active, over } = event
+    if (!over || active.id === over.id) return
+    const oldIndex = items.findIndex(i => i.id === active.id)
+    const newIndex = items.findIndex(i => i.id === over.id)
+    if (oldIndex === -1 || newIndex === -1) return
+    onReorder(oldIndex, newIndex)
+  }
+
+  const sortableIds = React.useMemo(() => items.map(i => i.id), [items])
+
+  return (
+    <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
+      <SortableContext items={sortableIds} strategy={verticalListSortingStrategy}>
+        <div className={cn('flex w-full flex-col gap-[var(--spacing-system-xs)]', className)}>
+          {items.map(item => (
+            <SortableRow key={item.id} id={item.id}>
+              {args => renderRow(item, args)}
+            </SortableRow>
+          ))}
+        </div>
+      </SortableContext>
+    </DndContext>
+  )
+}
+
+function SortableRow({
+  id,
+  children,
+}: {
+  id: string
+  children: (args: SortableRowRenderArgs) => React.ReactNode
+}) {
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({ id })
+
+  const style: React.CSSProperties = {
+    transform: CSS.Transform.toString(transform),
+    transition,
+  }
+
+  return (
+    <div ref={setNodeRef} style={style}>
+      {children({
+        dragHandleProps: listeners,
+        dragHandleAttributes: attributes,
+        isDragging,
+      })}
+    </div>
+  )
+}

package/src/components/footer-waitlist-button.tsx

@@ -2,6 +2,7 @@
 
 import { useRouter } from '../embed-shims/next-navigation';
 import { useChatRuntime } from '../contexts/chat-runtime-context';
+import { executeNavigationImperative } from './chat/utils/execute-navigation';
 import { useCallback } from 'react';
 import { OpenFrameLogo } from './icons';
 import { Button } from './ui/button';
@@ -39,15 +40,9 @@ export function FooterWaitlistButton({ className }: FooterWaitlistButtonProps) {
   const runtime = useChatRuntime();
 
   const handleClick = useCallback(() => {
-    const href = '/waitlist#top';
-    // Prefer the host's unified-nav callback (hub-wired
-    // `useUnifiedNav`). Falls back to the embed-shim's router when
-    // the host hasn't provided one.
-    if (runtime?.navigation?.navigate) {
-      const handled = runtime.navigation.navigate({ href });
-      if (handled) return;
-    }
-    router.push(href);
+    // The unified nav primitive: host `navigation.navigate` if wired, else the
+    // embed-shim router; new-tab/embed decision handled internally.
+    executeNavigationImperative({ runtime, href: '/waitlist#top', fallbackNavigate: router.push });
   }, [router, runtime]);
 
   return (

package/src/components/layout/page-heading.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from 'react'
+
+/**
+ * THE page-title style — the ODS `text-h1` token (`--font-size-h1-title` =
+ * 40 / 48 / 56px, Azeret Mono semibold) plus the standard heading tracking.
+ * Mirrors the global `h1 { @apply text-h1 }` base, so every page heading is
+ * the SAME size across the lib and every consuming app.
+ *
+ * Single source of truth — do NOT hardcode a px size for a page title; render
+ * `<PageHeading>` (or, for the rare non-h1 caller, apply `PAGE_HEADING_CLASS`).
+ */
+export const PAGE_HEADING_CLASS = 'text-h1 text-ods-text-primary tracking-[-1.12px]'
+
+const DESCRIPTION_CLASS =
+  "mt-6 max-w-[640px] font-['DM_Sans'] text-[16px] md:text-[18px] leading-[24px] md:leading-[28px] text-ods-text-secondary"
+
+export interface PageHeadingProps {
+  /** Heading content — plain text or nodes (e.g. an accent <span>). */
+  children: ReactNode
+  /**
+   * Heading level. Defaults to 'h1' (exactly one per page). Pass 'h2' where the
+   * page already renders an <h1> above (e.g. a hero/featured item).
+   */
+  as?: 'h1' | 'h2'
+  /** Optional supporting copy rendered as a <p> beneath the heading. */
+  description?: ReactNode
+  /** Extra classes merged onto the heading (margins, width, truncate, etc.). */
+  className?: string
+  /** Extra classes merged onto the description <p>. */
+  descriptionClassName?: string
+}
+
+/**
+ * Unified page heading. Renders the canonical page-title <h1> (or <h2>) plus an
+ * optional description, so every page shares one consistent style instead of
+ * duplicating the class string. Layout (PageContainer, margins, surrounding
+ * sections) stays with the caller — this owns only the heading + description.
+ */
+export function PageHeading({
+  children,
+  as: Tag = 'h1',
+  description,
+  className,
+  descriptionClassName,
+}: PageHeadingProps) {
+  const headingClass = className ? `${PAGE_HEADING_CLASS} ${className}` : PAGE_HEADING_CLASS
+  const descClass = descriptionClassName ? `${DESCRIPTION_CLASS} ${descriptionClassName}` : DESCRIPTION_CLASS
+  return (
+    <>
+      <Tag className={headingClass}>{children}</Tag>
+      {description != null && description !== '' && <p className={descClass}>{description}</p>}
+    </>
+  )
+}

package/src/components/layout/title-block.tsx

@@ -39,6 +39,7 @@ export function TitleBlock({
   className,
 }: TitleBlockProps) {
   const hasActions = actions && actions.length > 0
+  const hasMenuActions = !!menuActions && menuActions.some(g => g.items.length > 0)
 
   return (
     <div
@@ -89,7 +90,7 @@ export function TitleBlock({
         )}
       </div>
 
-      {(hasActions || selector) && (
+      {(hasActions || hasMenuActions || selector) && (
         <div className="flex gap-2 items-center shrink-0">
           <PageActions
             variant={actionsVariant}

package/src/components/onboarding-guides/onboarding-guide-detail-view.tsx

@@ -1,27 +1,18 @@
 'use client'
 
 /**
- * Public-facing detail view for `/onboarding-guides/<slug>` on
- * openframe.
+ * Public-facing detail view for `/onboarding-guides/<slug>`.
  *
- * Self-contained: every concern that used to require a hub-side
- * wrapper now flows through lib primitives + the ChatRuntime context.
+ * Two modes:
+ *   - **controlled** (hub SSR): pass `initialData` (a server-fetched guide).
+ *   - **self-fetching** (config-only embed): pass `slug` + `guideEndpoint`
+ *     (the api route) and the view fetches the guide itself — no host data
+ *     layer. (Plain fetch + useEffect, the DeliveryLists pattern.)
  *
- *   - Markdown: lib `<SimpleMarkdownRenderer>` (already lib-resident).
- *   - Video warmup: lib `useVideoWarmup` (reads Supabase storage
- *     origin from `runtime.endpoints.supabaseStorageOrigin`; Mux
- *     origins are hardcoded public CDN hosts).
- *   - Captions URL: lib `getCaptionsUrl` (pure URL builder).
- *   - Video poster: inline priority chain
- *     (`main_video_thumbnail || featured_image || og_image_url`) —
- *     same fallbacks the card uses.
- *   - Related card hrefs: `runtime.composeContentUrl?.(
- *     'onboarding_guide', slug, platforms)` — falls back to same-
- *     origin relative path when no composer is wired.
- *
- * No hub-side wrapper file required. Optional `MarkdownRenderer`
- * prop lets hosts swap in a renderer with extra plugins (Reddit /
- * Twitter / X embeds) when needed.
+ * Everything else flows through lib primitives + the ChatRuntime context
+ * (markdown, video warmup, captions, related-card hrefs via
+ * `runtime.composeContentUrl`). Optional `MarkdownRenderer` lets hosts swap a
+ * renderer with extra plugins.
  */
 
 import { type ComponentType, type ReactNode } from 'react'
@@ -29,44 +20,49 @@ import { ArrowLeft } from 'lucide-react'
 
 import { Link } from '../../embed-shims'
 import { ArticleDetailLayout } from '../layout/article-detail-layout'
+import { DetailPageSkeleton } from '../shared/detail-page-skeleton'
 import { EntityVideoSection } from '../features/entity-video-section'
 import { VideoBitesDisplay } from '../features/video-bites-display'
 import { useVideoWarmup } from '../features/use-video-warmup'
 import { getCaptionsUrl } from '../features/captions-url'
 import { SimpleMarkdownRenderer } from '../ui/simple-markdown-renderer'
+import { LoadError } from '../ui/error-state'
 import { EntityAuthorCard } from '../chat/entity-cards/entity-author-card'
 import { OnboardingGuideCard } from '../chat/entity-cards/onboarding-guide-card'
 import { useChatRuntime } from '../../contexts/chat-runtime-context'
 import type { OnboardingGuide } from '../chat/types/entities/onboarding-guide'
 import type { VideoTeaser } from '../../types/video-processing'
-import { buildDefaultHref } from './build-default-href'
+import { resolveContentHref } from '../../utils/content-href'
+import { useSelfFetch } from '../../hooks/use-self-fetch'
 
 export interface OnboardingGuideDetailViewProps {
-  initialData: OnboardingGuide
+  /** Server-fetched guide (controlled / SSR mode). Omit it and pass
+   *  `slug` + `guideEndpoint` for the self-fetching config-only mode. */
+  initialData?: OnboardingGuide
+  /** Self-fetch: the guide's slug (the host reads it from its route). */
+  slug?: string
+  /** Self-fetch: builds the GET url for a single guide (the api route).
+   *  e.g. `(s) => \`/content/api/onboarding-guides/${s}\``. */
+  guideEndpoint?: (slug: string) => string
   related?: OnboardingGuide[]
   /** Optional markdown renderer override. Defaults to lib
-   *  `<SimpleMarkdownRenderer>`. Hosts override when they need extra
-   *  plugins (Reddit / Twitter / X / code-block enhancements). */
+   *  `<SimpleMarkdownRenderer>`. */
   MarkdownRenderer?: ComponentType<{ content: string }>
-  /** Optional per-row related-card renderer override. When omitted,
-   *  lib renders `<OnboardingGuideCard>` with runtime-composed href. */
+  /** Optional per-row related-card renderer override. */
   renderRelatedCard?: (guide: OnboardingGuide) => ReactNode
-  /** Back-link target. Defaults to `basePath` so the link returns to
-   *  the catalog the embedder is hosting (no drift when `basePath`
-   *  is overridden). The admin preview explicitly overrides to
-   *  `/admin/onboarding-guides`. */
+  /** Back-link target. Defaults to `basePath`. */
   backHref?: string
   /** Back-link label. Defaults to "Back to Getting Started". */
   backLabel?: string
   /** Base path the related-card hrefs default to when
-   *  `runtime.composeContentUrl` is not wired. Embedders mounting at
-   *  `/docs/onboarding/` instead of `/onboarding-guides/` should
-   *  override. Default `/onboarding-guides`. */
+   *  `runtime.composeContentUrl` is not wired. Default `/onboarding-guides`. */
   basePath?: string
 }
 
 export function OnboardingGuideDetailView({
-  initialData: guide,
+  initialData,
+  slug,
+  guideEndpoint,
   related = [],
   MarkdownRenderer = SimpleMarkdownRenderer,
   renderRelatedCard,
@@ -74,36 +70,32 @@ export function OnboardingGuideDetailView({
   backLabel = 'Back to Getting Started',
   basePath = '/onboarding-guides',
 }: OnboardingGuideDetailViewProps) {
-  // Resolve `backHref` from `basePath` when not explicitly set — so
-  // an embedder overriding `basePath="/docs/onboarding"` automatically
-  // gets the right back link without remembering to thread `backHref`
-  // too. Admin preview still wins via its explicit `backHref` override.
   const resolvedBackHref = backHref ?? basePath
   const runtime = useChatRuntime()
 
-  // Video warmup — preconnect always fires; preload only when the
-  // container scrolls within ~1 viewport AND the URL is on the
-  // configured Supabase storage origin. No origin in runtime ⇒
-  // preconnect-only path (Mux/YouTube unaffected).
+  // Controlled (hub SSR `initialData`) OR self-fetch by slug (config-only embed).
+  const url = initialData ? null : slug && guideEndpoint ? guideEndpoint(slug) : null
+  const { data: guide, isLoading, error, reload } = useSelfFetch<OnboardingGuide>(url, { initialData })
+
+  // Hooks must run unconditionally — feed them optional-chained values so they
+  // no-op while the guide is still loading.
   const { ref: videoWarmupRef } = useVideoWarmup<HTMLDivElement>({
-    videoUrl: guide.main_video_url,
+    videoUrl: guide?.main_video_url,
     supabaseStorageOrigin: runtime?.endpoints.supabaseStorageOrigin,
   })
 
-  const captionsUrl = getCaptionsUrl(
-    'onboarding_guide',
-    guide.id,
-    guide.srt_content,
-  )
+  if (error || (!guide && !isLoading)) {
+    return <LoadError message="Guide not found." onRetry={reload} />
+  }
+  if (!guide) {
+    // Skeleton (not a bare "Loading…") for parity with every other shared view —
+    // catalog, roadmap, releases all render a skeleton on first load, so the detail
+    // page shouldn't flash text then content.
+    return <DetailPageSkeleton showImageGallery={false} />
+  }
+
+  const captionsUrl = getCaptionsUrl('onboarding_guide', guide.id, guide.srt_content)
 
-  // Video poster — fallback chain:
-  //   1. Entity-owned thumbnails (main_video_thumbnail / featured_image / og_image_url)
-  //   2. Branded OG placeholder from `runtime.resolvePlaceholderUrl(title)`
-  //      — restores the hub's prior behavior where a video without a
-  //      thumbnail still showed a branded poster instead of a black
-  //      frame.
-  //   3. `undefined` (player picks its own default poster — usually
-  //      first-frame extraction).
   const videoPoster =
     guide.main_video_thumbnail ||
     guide.featured_image ||
@@ -111,22 +103,14 @@ export function OnboardingGuideDetailView({
     runtime?.resolvePlaceholderUrl?.(guide.title, { aspect: 'wide' }) ||
     undefined
 
-  // Default related-card renderer — runtime-composed cross-platform href.
   const defaultRenderRelatedCard = (g: OnboardingGuide) => {
-    const cta = runtime?.composeContentUrl
-      ? runtime.composeContentUrl(
-          'onboarding_guide',
-          g.slug,
-          g.onboarding_guide_platforms,
-        )
-      : buildDefaultHref(basePath, g.slug)
-    return (
-      <OnboardingGuideCard
-        guide={g}
-        href={cta.href}
-        targetPlatform={cta.targetPlatform}
-      />
-    )
+    const cta = resolveContentHref(runtime?.composeContentUrl, {
+      type: 'onboarding_guide',
+      slug: g.slug,
+      basePath,
+      platforms: g.onboarding_guide_platforms,
+    })
+    return <OnboardingGuideCard guide={g} href={cta.href} targetPlatform={cta.targetPlatform} />
   }
   const renderRelatedCardFn = renderRelatedCard ?? defaultRenderRelatedCard
 
@@ -142,9 +126,7 @@ export function OnboardingGuideDetailView({
           <span className="text-h5">{backLabel}</span>
         </Link>
 
-        <h1 className="text-h1 tracking-[-1.12px] text-ods-text-primary">
-          {guide.title}
-        </h1>
+        <h1 className="text-h1 tracking-[-1.12px] text-ods-text-primary">{guide.title}</h1>
 
         {/* Metadata grid — Section · Step | Published | Author. */}
         <EntityAuthorCard
@@ -159,9 +141,8 @@ export function OnboardingGuideDetailView({
           ]}
         />
 
-        {/* Video. `main_video_url` (Mux/MP4) and `youtube_url` are
-            independent columns — either one populated should render
-            the player. `EntityVideoSection` routes accordingly. */}
+        {/* Video. `main_video_url` (Mux/MP4) and `youtube_url` are independent
+            columns — either populated renders the player. */}
         {(guide.main_video_url || guide.youtube_url) && (
           <div ref={videoWarmupRef}>
             <EntityVideoSection