@flamingo-stack/openframe-frontend-core 0.0.303-snapshot.20260622160827 → 0.0.303

package/src/components/chat/hooks/use-slash-commands.ts

@@ -62,25 +62,14 @@ export async function fetchSlashCommands(
   signal: AbortSignal | undefined,
   commandsUrl: string,
 ): Promise<SlashCommandSummary[]> {
-  try {
-    const url = new URL(commandsUrl, window.location.origin);
-    if (prefix) url.searchParams.set("q", prefix);
-    // `headers: {}` opts out of the default `Content-Type: application/json`
-    // — this is a bare GET with no body, so no content-type is needed.
-    const res = await embedAuthedFetch(url.toString(), { signal, headers: {} });
-    if (!res.ok) return [];
-    const data = (await res.json()) as { commands?: SlashCommandSummary[] };
-    return data.commands ?? [];
-  } catch (err) {
-    // Cancellation (unmount / dep change) MUST propagate so react-query treats
-    // it as cancelled, not as a successful empty result. Every OTHER failure
-    // (network down, proxy reject, non-JSON body) degrades to "no commands" so
-    // a flaky commands endpoint can NEVER break the chat — the autocomplete /
-    // onboarding list just renders empty.
-    if ((err as Error)?.name === "AbortError") throw err;
-    console.warn("[chat] slash-commands fetch failed, showing none:", err);
-    return [];
-  }
+  const url = new URL(commandsUrl, window.location.origin);
+  if (prefix) url.searchParams.set("q", prefix);
+  // `headers: {}` opts out of the default `Content-Type: application/json`
+  // — this is a bare GET with no body, so no content-type is needed.
+  const res = await embedAuthedFetch(url.toString(), { signal, headers: {} });
+  if (!res.ok) return [];
+  const data = (await res.json()) as { commands?: SlashCommandSummary[] };
+  return data.commands ?? [];
 }
 
 /**
@@ -155,11 +144,6 @@ export function useSlashCommandRegistry(
     enabled: options?.enabled ?? true,
     staleTime: Infinity,
     gcTime: Infinity,
-    // The commands registry is non-critical chrome — a failure degrades to an
-    // empty registry (handled in `fetchSlashCommands`). Don't retry: settle to
-    // the neutral empty state immediately so a flaky endpoint never holds the
-    // welcome UI in a loading spinner.
-    retry: false,
   });
   return {
     commands: query.data ?? [],

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

@@ -2,6 +2,7 @@
 
 import React, { useMemo } from "react"
 import { MultiLevelNavigation, MobileNavigationDropdown } from "../navigation/multi-level-navigation"
+import { PageHeader } from "../layout/page-header"
 import { PageLayout } from "../layout/page-layout"
 import { PageShell } from "../layout/article-detail-layout"
 import { useRouter } from "../../embed-shims/next-navigation"
@@ -58,9 +59,10 @@ export interface DocViewerProps {
    */
   chatSource: string
 
-  /** Page title — rendered as the inline hero `<h1>` (same DOM
-   *  `<DevSectionView>`'s hero uses) so the doc-viewer chrome matches the
-   *  dev-section pages. ReactNode is intentionally not supported here —
+  /** Page title — rendered via the shared `<PageHeader>` primitive
+   *  so the doc-viewer chrome matches every other lib page
+   *  (DevSectionPage / LegalDocumentPage / OnboardingGuideDetailView)
+   *  pixel-for-pixel. ReactNode is intentionally not supported here —
    *  every consumer renders the same typography. */
   title?: string
   /** Optional icon rendered inline before the title text — same slot
@@ -257,10 +259,15 @@ function DocViewerContent({
   const resolvedEmptyText = emptyStateText || defaultEmptyText
 
   return (
-    // Render through the shared wrapper chain (PageShell → PageLayout →
-    // `gap-10 flex-col`). PageLayout owns the back-button row; the inner
-    // `gap-10` div holds an inline title hero (same DOM `<DevSectionView>`'s
-    // hero renders) followed by the search bar + content grid.
+    // STRUCTURAL UNIFICATION: render through the IDENTICAL wrapper chain
+    // `<DevSectionPage>` uses (PageShell → PageLayout → `gap-10 flex-col`),
+    // not a hand-rolled custom container with similar-looking spacing.
+    // PageLayout owns the back-button row; the inner `gap-10` div +
+    // `<PageHeader noTopPadding noBottomMargin>` renders the title section
+    // the same way `<DevSectionView>`'s hero does. This is the only way to
+    // guarantee /knowledge-base sits at pixel-identical vertical rhythm to
+    // /roadmap / /releases / /onboarding-guides — same components, same DOM,
+    // not "same CSS classes that look similar on paper."
     //
     // `colorPalette` / `className` / `bgStyle` flow through PageShell's
     // contentClassName + an inner style-passthrough wrapper so legacy
@@ -270,24 +277,14 @@ function DocViewerContent({
       <div style={{ ...bgStyle, ...containerBgStyle }}>
         <PageLayout backButton={backCfg ?? undefined}>
           <div className="w-full flex flex-col gap-10">
-            {(title || titleIcon || subtitle) && (
-              <div className="space-y-4">
-                {(title || titleIcon) && (
-                  <h1 className="text-h1 tracking-[-1.12px] text-ods-text-primary flex items-center gap-3">
-                    {titleIcon}
-                    {title && (
-                      <span>
-                        {title}
-                        {accentDot && <span className="text-ods-accent">.</span>}
-                      </span>
-                    )}
-                  </h1>
-                )}
-                <p className="font-['DM_Sans'] font-medium text-[18px] leading-[28px] text-ods-text-secondary max-w-3xl line-clamp-2 min-h-[56px]">
-                  {subtitle || ' '}
-                </p>
-              </div>
-            )}
+            <PageHeader
+              title={title}
+              titleIcon={titleIcon}
+              subtitle={subtitle}
+              accentDot={accentDot}
+              noTopPadding
+              noBottomMargin
+            />
 
           {showAIChat && (
             <DocSearchBar

package/src/components/docs/use-docs-resolve-link.ts

@@ -1,7 +1,6 @@
 import { useCallback } from 'react'
 import { useChatRuntime } from '../../contexts/chat-runtime-context'
 import type { ResolveLinkResult } from '../../types/doc-source'
-import { contentFetch } from '../../utils/embed-content-fetch'
 
 /**
  * `useDocsResolveLink(sourceId, override?)` — POST `/api/docs/resolve-link`
@@ -31,7 +30,7 @@ export function useDocsResolveLink(
   return useCallback(
     async (href: string, currentPath: string): Promise<ResolveLinkResult> => {
       try {
-        const response = await contentFetch(resolvedResolveLinkEndpoint, {
+        const response = await fetch(resolvedResolveLinkEndpoint, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({ link: href, currentPath, source: sourceId }),

package/src/components/docs/use-document-tree.ts

@@ -9,7 +9,6 @@ import {
   DEFAULT_FOLDER_INDEX_FILE,
 } from '../../utils/doc-tree-nav'
 import { useDocNavigation } from './doc-navigation-context'
-import { contentFetch } from '../../utils/embed-content-fetch'
 import { scrollElementIntoView } from '../../utils/scroll-into-view'
 import { navigateSamePageHash, HUB_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav'
 
@@ -180,7 +179,7 @@ export function useDocumentTree(
       setIsLoadingStructure(true)
       setError(null)
 
-      const response = await contentFetch(structureEndpoint)
+      const response = await fetch(structureEndpoint)
 
       if (!response.ok) {
         throw new Error('Failed to load documentation structure')
@@ -233,7 +232,7 @@ export function useDocumentTree(
       // returns early without writing to state. Clearing error here would
       // briefly flicker the user-visible error message.
 
-      const response = await contentFetch(`${contentEndpoint}?path=${encodeURIComponent(path)}`)
+      const response = await fetch(`${contentEndpoint}?path=${encodeURIComponent(path)}`)
 
       // Request-id guard: between awaits, `lastFetchedPath.current` may have
       // been bumped by a newer fetch (the structure-arrives auto-select issues

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

@@ -0,0 +1,182 @@
+'use client'
+
+import React from 'react'
+import { cn } from '../../utils/cn'
+import { EntityImage } from '../ui/entity-image'
+import { BackButton } from './back-button'
+
+/**
+ * Page-header primitive — the canonical "back-button + title + subtitle
+ * + (optional) image / actions" chrome every lib page uses.
+ *
+ * Owns the SSOT for the page-header DOM/CSS that the rest of the lib
+ * was duplicating: pre-`mb` top padding, h1 typography (`text-h2`), h6
+ * subtitle (`text-h6`), the gap between the back button and the title
+ * block, and the right-side actions slot. Consumers either render this
+ * directly (e.g. `<DocViewer>` / `<DocsHubPage>`) or compose it through
+ * the `<TitleBlock>` adapter which adds the `PageActions` /
+ * `ActionsMenu` / selector wiring on top.
+ *
+ * Why this exists: knowledge-hub vs releases sat at different vertical
+ * rhythms (px-perfect mismatch on title baseline + subtitle offset)
+ * because the docs surface hand-rolled its own chrome instead of going
+ * through `TitleBlock`. Centralizing the layout here means every
+ * embeddable lib page (DocViewer, DevSectionPage, LegalDocumentPage,
+ * OnboardingGuideDetailView) renders pixel-identical title/subtitle/
+ * back-button typography + spacing — and a future spacing/typography
+ * tweak is one file.
+ */
+export interface PageHeaderProps {
+  /** Page title (h1). Plain string — ReactNode is intentionally not
+   *  supported here so every consumer renders the same typography. */
+  title?: string
+  /** Optional icon rendered inline before the title text (e.g. the
+   *  rocket emoji on /releases, the docs icon on /knowledge-base).
+   *  Same `flex items-center gap-3` row as `<DevSectionView>`'s hero. */
+  titleIcon?: React.ReactNode
+  /** Page subtitle (description paragraph). */
+  subtitle?: string
+  /**
+   * Render a yellow accent dot (`.`) after the title. Mirrors the
+   * hub's legacy `<AdminPageHeader accentDot>` flag — now lib-wide so
+   * surfaces like `/knowledge-base` keep their existing accent styling
+   * after the migration.
+   */
+  accentDot?: boolean
+  /** Optional thumbnail / hero image rendered to the left of the
+   *  title block. Used by entity-image-style headers (onboarding
+   *  guides, knowledge-base entries). */
+  image?: { src: string; alt?: string }
+  /** Back-button shown above the title block. Hidden on mobile (matches
+   *  the existing TitleBlock + DocViewer behavior). */
+  backButton?: { label?: string; onClick: () => void }
+  /** Right-side actions slot (action buttons / menu / tab selector).
+   *  Composed externally (e.g. `<TitleBlock>` builds `PageActions` + menu
+   *  + selector and passes the result here). */
+  actions?: React.ReactNode
+  /**
+   * Visual variant.
+   * - `plain` (default): transparent background, no border.
+   * - `card`: card background, border, and padding on mobile only —
+   *   collapses to plain on md+ (legacy `TitleBlock` variant — kept so
+   *   surfaces that depend on the card affordance don't regress).
+   */
+  variant?: 'plain' | 'card'
+  /** When the consumer wraps `<PageHeader>` in its OWN spacing container
+   *  (e.g. `<DevSectionView>`'s `gap-10 flex-col`), the default `mb-l`
+   *  bottom margin doubles up. Pass `noBottomMargin` to opt out. */
+  noBottomMargin?: boolean
+  /** Same as `noBottomMargin` for the default `pt-l` top padding. Set
+   *  this when PageHeader is nested INSIDE another layout that already
+   *  provides top spacing (e.g. `<DevSectionView>`'s hero, which sits
+   *  inside `<PageLayout>`'s children flow). */
+  noTopPadding?: boolean
+  className?: string
+}
+
+// Title typography — copied verbatim from <DevSectionView>'s hero h1
+// (`src/components/shared/dev-section/dev-section-view.tsx`). The user-
+// reported "header text not aligned" between /knowledge-base and
+// /releases bottomed out here: DevSectionView rendered text-h1 with
+// tracking-[-1.12px] while this component used text-h2 — visually huge
+// gap. Now both render through the exact same class string. DevSectionView
+// is being refactored in this commit to delegate to <PageHeader> so the
+// shared-component claim is enforced at the code level too.
+const TITLE_CLASS = 'text-h1 tracking-[-1.12px] text-ods-text-primary flex items-center gap-3'
+// Subtitle ALWAYS occupies exactly 2 lines of vertical space.
+//   `min-h-[56px]` (= 2 × 28px leading) reserves the row height so a
+//   single-line subtitle doesn't shrink the header — page-to-page height
+//   stays consistent.
+//   `line-clamp-2` caps long copy at 2 lines + ellipsis so wrapping doesn't
+//   push the search bar down.
+const SUBTITLE_CLASS = "font-['DM_Sans'] font-medium text-[18px] leading-[28px] text-ods-text-secondary max-w-3xl line-clamp-2 min-h-[56px]"
+
+export function PageHeader({
+  title,
+  titleIcon,
+  subtitle,
+  accentDot,
+  image,
+  backButton,
+  actions,
+  variant = 'plain',
+  noBottomMargin = false,
+  noTopPadding = false,
+  className,
+}: PageHeaderProps) {
+  return (
+    <div
+      className={cn(
+        'flex items-end justify-between gap-[var(--spacing-system-m)]',
+        'md:flex-col md:items-start md:justify-start lg:flex-row lg:items-end lg:justify-between',
+        !noTopPadding && 'pt-[var(--spacing-system-l)]',
+        variant === 'card'
+          ? cn(
+              'bg-ods-card border-b border-ods-border',
+              'px-[var(--spacing-system-l)] pb-[var(--spacing-system-l)]',
+              'md:bg-transparent md:border-b-0',
+              'md:px-0 md:pb-0',
+              !noBottomMargin && 'md:mb-[var(--spacing-system-l)]',
+            )
+          : !noBottomMargin && 'mb-[var(--spacing-system-l)]',
+        className,
+      )}
+    >
+      <div className="flex flex-col gap-[var(--spacing-system-xs)] flex-1 min-w-0">
+        {backButton && (
+          <BackButton
+            onClick={backButton.onClick}
+            label={backButton.label}
+            className="hidden md:inline-flex"
+          />
+        )}
+        {/* Title + subtitle stack. Matches `<DevSectionView>`'s hero
+         *  exactly: `space-y-4` between h1 and p, `flex items-center
+         *  gap-3` for icon-inline title row, identical class strings.
+         *  Image (entity-image-style) prefixes the title row, NOT a
+         *  separate column with its own vertical rhythm — that's the
+         *  legacy TitleBlock 2-col layout which broke the title-to-
+         *  subtitle gap. */}
+        {(title || subtitle || image || titleIcon) && (
+          <div className="space-y-4">
+            {(title || image || titleIcon) && (
+              <h1 className={TITLE_CLASS}>
+                {image && (
+                  <EntityImage
+                    src={image.src}
+                    alt={image.alt}
+                    fallbackText={image.alt || title}
+                  />
+                )}
+                {titleIcon}
+                {title && (
+                  <span>
+                    {title}
+                    {accentDot && <span className="text-ods-accent">.</span>}
+                  </span>
+                )}
+              </h1>
+            )}
+            {(title || titleIcon || image) && (
+              // Always render the subtitle <p> when the title block exists,
+              // even when `subtitle` is empty — `SUBTITLE_CLASS` reserves
+              // `min-h-[56px]` so headers WITH and WITHOUT subtitles share a
+              // baseline (the JSDoc on SUBTITLE_CLASS claims "ALWAYS occupies
+              // exactly 2 lines"; gating the <p> on truthy `subtitle` broke
+              // that contract — pages without subtitle were ~56px shorter).
+              // Falsy subtitles render an NBSP placeholder so the empty <p>
+              // still takes its reserved height.
+              <p className={SUBTITLE_CLASS}>{subtitle || ' '}</p>
+            )}
+          </div>
+        )}
+      </div>
+
+      {actions && (
+        <div className="flex gap-2 items-center shrink-0">{actions}</div>
+      )}
+    </div>
+  )
+}
+
+export default PageHeader

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

@@ -1,32 +1,5 @@
 'use client'
 
-/* ============================================================================
- * ⛔️ FROZEN — DO NOT MODIFY (AI agents & contributors, read this first)
- * ----------------------------------------------------------------------------
- * `PageLayout` and its `TitleBlock` are a FINALIZED, locked component. They are
- * the canonical, stable page chrome for OpenFrame surfaces and their visual +
- * behavioral contract is intentionally complete. Treat this file as read-only.
- *
- * Do NOT: change the markup/CSS, swap the title typography (`text-h2`) or
- * subtitle (`text-h6`), re-architect this to delegate to another primitive,
- * add/rename props, or "unify"/"refactor"/"simplify" it. Do NOT restyle to
- * match some other surface.
- *
- * Why this rule exists (the incident it prevents): a refactor once re-styled
- * this layout (bumped the title to `text-h1`, rerouted it through a new
- * `PageHeader`/`PageWithHeader` chain) to "unify" page chrome. That silently
- * changed the look of every page rendered through `PageLayout` and had to be
- * fully reverted. The current code IS the reverted, correct baseline.
- *
- * MANY consumers depend on the EXACT current output — not only OpenFrame pages
- * but also `DevSectionPage`, `DocViewer`, and the multi-platform hub (through
- * its own local `PageWithHeader`). A change here ripples across all of them.
- *
- * If a new design genuinely needs different chrome: build a SEPARATE new
- * component for it. Never mutate this one. If you believe an edit here is
- * unavoidable, STOP and get explicit human sign-off first.
- * ========================================================================== */
-
 import React from 'react'
 import { cn } from '../../utils/cn'
 import type { ActionsMenuGroup } from '../ui/actions-menu'
@@ -37,6 +10,11 @@ export interface PageLayoutProps {
   children: React.ReactNode
   title?: string
   subtitle?: string
+  /** Inline icon rendered before the title text — forwarded to
+   *  TitleBlock/PageHeader. Same shape as DevSectionPage's hero icon. */
+  titleIcon?: React.ReactNode
+  /** Yellow accent dot after the title — forwarded to TitleBlock/PageHeader. */
+  accentDot?: boolean
   image?: { src: string; alt?: string }
   backButton?: { label?: string; onClick: () => void }
   actions?: PageActionButton[]
@@ -60,6 +38,8 @@ export function PageLayout({
   children,
   title,
   subtitle,
+  titleIcon,
+  accentDot,
   image,
   backButton,
   actions,
@@ -73,14 +53,16 @@ export function PageLayout({
 }: PageLayoutProps) {
   const hasActions = actions && actions.length > 0
   const needsBottomPadding = hasActions && actionsVariant === 'primary-buttons'
-  const hasHeader = showHeader && (title || subtitle || image || backButton || hasActions || selector)
+  const hasHeader = showHeader && (title || subtitle || titleIcon || image || backButton || hasActions || selector)
 
   return (
     <div className={cn('flex flex-col w-full', className)}>
       {hasHeader && (
         <TitleBlock
           title={title}
+          titleIcon={titleIcon}
           subtitle={subtitle}
+          accentDot={accentDot}
           image={image}
           backButton={backButton}
           actions={actions}
@@ -101,4 +83,8 @@ export function PageLayout({
 export type { PageActionButton } from '../ui/page-actions'
 export { TitleBlock } from './title-block'
 export type { TitleBlockProps } from './title-block'
+export { PageHeader } from './page-header'
+export type { PageHeaderProps } from './page-header'
+export { PageWithHeader } from './page-with-header'
+export type { PageWithHeaderProps } from './page-with-header'
 export default PageLayout

package/src/components/layout/page-with-header.tsx

@@ -0,0 +1,110 @@
+'use client'
+
+import React from 'react'
+import { useRouter } from '../../embed-shims/next-navigation'
+import { PageShell } from './article-detail-layout'
+import { PageLayout } from './page-layout'
+import { PageHeader, type PageHeaderProps } from './page-header'
+
+/**
+ * `<PageWithHeader>` — the canonical 4-layer unified-chrome wrapper that
+ * every public lib/hub page now uses (Knowledge Hub, Roadmap, FAQs,
+ * Authors, Blog, Vendors, Case Studies, Interviews, Investor Updates,
+ * /webinars-/podcasts-/events, hub admin-but-public pages, …).
+ *
+ * Renders the same JSX tree every consumer was hand-rolling individually
+ * before this helper landed:
+ *
+ *   PageShell                         ← bg-ods-bg, max-w-[1920px],
+ *                                       page-shell-px/pt/pb gutters
+ *     PageLayout backButton           ← TitleBlock → PageHeader #1 (back-btn row
+ *                                       only, pt-l + mb-l)
+ *       div.w-full.flex-col.gap-10    ← matches DevSectionView's hero container
+ *         PageHeader title/subtitle   ← PageHeader #2 (noTopPadding +
+ *           titleIcon accentDot         noBottomMargin so PageLayout's gap-l owns
+ *           noTopPadding                the spacing between #1 and #2)
+ *           noBottomMargin
+ *         children                    ← page-specific body (search, lists, forms)
+ *
+ * Why this exists: 15+ pages copy-pasted the EXACT same nesting + the
+ * EXACT same `noTopPadding + noBottomMargin + accentDot` triplet on the
+ * inner `<PageHeader>`. Forgetting one of those flags collapsed the gap
+ * to ~8px (the FAQs-vs-Onboarding-Guides bug). Centralizing the chain
+ * here makes the spacing invariant compiler-enforced — consumers can't
+ * pick the wrong combination.
+ *
+ * **Back button is config-driven by default.** Consumers don't have to
+ * thread `useRouter()` + `() => router.push('/')` themselves anymore —
+ * the helper supplies a sane default (`{ label: 'Back to home', href: '/' }`).
+ * Hosts whose `/` lives elsewhere should pass their own `href`. Pass
+ * `backButton={false}` to suppress entirely (the lib's own
+ * `<DocsHubPage>` does this on the platform-home docs landing).
+ */
+export interface PageWithHeaderProps {
+  /** Title — passed straight to inner `<PageHeader>`. */
+  title?: string
+  /** Inline icon rendered before the title (lucide / SVG node). Wrap with
+   *  `SECTION_HERO_ICON_CLASS` at the call site, or use the lib's
+   *  `<PageHeader>`'s `titleIcon` ReactNode signature directly. */
+  titleIcon?: PageHeaderProps['titleIcon']
+  /** Subtitle (1-2 lines, auto-clamped to 2 + min-h-[56px]). */
+  subtitle?: string
+  /** Render yellow accent dot after the title (default true — matches every
+   *  unified surface). Pass `false` to opt out. */
+  accentDot?: boolean
+  /** Back-button config. Defaults to `{ label: 'Back to home', href: '/' }`.
+   *  Pass `false` to hide entirely (platform-home docs landings). */
+  backButton?: { label?: string; href?: string } | false
+  /** Optional image (entity-image-style — onboarding guides etc.). */
+  image?: PageHeaderProps['image']
+  /** Optional actions slot (right side of header). */
+  actions?: React.ReactNode
+  /** Page body — search bars, lists, forms, sections. Rendered INSIDE the
+   *  gap-10 flex column so it shares gutters + vertical rhythm with the
+   *  header. */
+  children: React.ReactNode
+  /** Extra class applied to the gap-10 content wrapper. */
+  contentClassName?: string
+}
+
+export function PageWithHeader({
+  title,
+  titleIcon,
+  subtitle,
+  accentDot = true,
+  backButton,
+  image,
+  actions,
+  children,
+  contentClassName,
+}: PageWithHeaderProps) {
+  const router = useRouter()
+
+  const backCfg =
+    backButton === false
+      ? undefined
+      : {
+          label: backButton?.label ?? 'Back to home',
+          onClick: () => router.push(backButton?.href ?? '/'),
+        }
+
+  return (
+    <PageShell>
+      <PageLayout backButton={backCfg}>
+        <div className={`w-full flex flex-col gap-10${contentClassName ? ` ${contentClassName}` : ''}`}>
+          <PageHeader
+            title={title}
+            titleIcon={titleIcon}
+            subtitle={subtitle}
+            accentDot={accentDot}
+            image={image}
+            actions={actions}
+            noTopPadding
+            noBottomMargin
+          />
+          {children}
+        </div>
+      </PageLayout>
+    </PageShell>
+  )
+}