@flamingo-stack/openframe-frontend-core 0.0.295 → 0.0.296-snapshot.20260621021605

package/dist/utils/page-header-constants.d.ts

@@ -0,0 +1,15 @@
+/**
+ * String constants shared by page-header consumers (`<PageHeader>`,
+ * `<DevSectionPage>`, `<DocsHubPage>` callers). Lives in `utils/` —
+ * NOT `'use client'` — so server modules (e.g. the hub's
+ * `lib/docs/hub-docs-presets.tsx` that builds preset JSX with
+ * `<Icon className={SECTION_HERO_ICON_CLASS} />`) can import the raw
+ * string. Importing the constant from a `'use client'` module turns it
+ * into a Next.js client-reference proxy in server contexts, which
+ * lucide's internal `mergeClasses` then calls `.trim()` on and crashes.
+ */
+/** Tailwind class applied uniformly to every section-hero / page-header
+ *  icon across the lib (Roadmap Map, Releases Rocket, Knowledge Hub
+ *  BookOpen, Data Room Building2, …). Yellow accent color, 40x40. */
+export declare const SECTION_HERO_ICON_CLASS = "h-10 w-10 text-ods-accent";
+//# sourceMappingURL=page-header-constants.d.ts.map

package/dist/utils/page-header-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-header-constants.d.ts","sourceRoot":"","sources":["../../src/utils/page-header-constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;qEAEqE;AACrE,eAAO,MAAM,uBAAuB,8BAA8B,CAAA"}

package/dist/utils/social-embed-cache.d.ts

@@ -0,0 +1,29 @@
+interface CacheOptions {
+    platform: 'reddit' | 'twitter';
+    url: string;
+    apiEndpoint: string;
+}
+export declare class SocialEmbedCache {
+    private static instance;
+    static getInstance(): SocialEmbedCache;
+    getFromMemory(url: string): any | null;
+    setInMemory(url: string, data: any): void;
+    getFromServer(options: CacheOptions): Promise<any | null>;
+    private updateServerCache;
+    setInServer(options: CacheOptions, data: any): Promise<void>;
+    fetchDirect(options: CacheOptions & {
+        directFetcher: () => Promise<any>;
+    }): Promise<any | null>;
+    fetchWithHierarchy(options: CacheOptions & {
+        dataValidator: (data: any) => boolean;
+        onDataUpdate: (data: any) => void;
+        onError: (error: string) => void;
+        onLoading: (loading: boolean) => void;
+    }): Promise<void>;
+    private scheduleAsyncRefresh;
+    private backgroundRefresh;
+    private silentBackgroundRefresh;
+}
+export declare const socialCache: SocialEmbedCache;
+export {};
+//# sourceMappingURL=social-embed-cache.d.ts.map

package/dist/utils/social-embed-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"social-embed-cache.d.ts","sourceRoot":"","sources":["../../src/utils/social-embed-cache.ts"],"names":[],"mappings":"AAmBA,UAAU,YAAY;IACpB,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmB;IAE1C,MAAM,CAAC,WAAW,IAAI,gBAAgB;IAQtC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI;IAKtC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI;IAKnC,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;YAoBjD,iBAAiB;IAezB,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B5D,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG;QACxC,aAAa,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAA;KAClC,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAajB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG;QAC/C,aAAa,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC;QACtC,YAAY,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC;QAClC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;QACjC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;KACvC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmIjB,OAAO,CAAC,oBAAoB;YAgCd,iBAAiB;IAiD/B,OAAO,CAAC,uBAAuB;CAgDhC;AAED,eAAO,MAAM,WAAW,kBAAiC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.295",
+  "version": "0.0.296-snapshot.20260621021605",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -78,6 +78,12 @@
       "require": "./dist/components/contact/index.cjs",
       "default": "./dist/components/contact/index.js"
     },
+    "./components/case-studies": {
+      "types": "./dist/components/case-studies/index.d.ts",
+      "import": "./dist/components/case-studies/index.js",
+      "require": "./dist/components/case-studies/index.cjs",
+      "default": "./dist/components/case-studies/index.js"
+    },
     "./schemas/contact-schema": {
       "types": "./dist/schemas/contact-schema.d.ts",
       "import": "./dist/schemas/contact-schema.js",

package/src/components/case-studies/index.ts

@@ -0,0 +1,4 @@
+export {
+  ShareExperienceSection,
+  type ShareExperienceSectionProps,
+} from './share-experience-section'

package/src/components/case-studies/share-experience-section.tsx

@@ -0,0 +1,185 @@
+'use client'
+
+import React from 'react'
+import { BenefitCard, BenefitCardGrid } from '../ui'
+import {
+  G2Icon,
+  CapterraIcon,
+  TrustpilotIcon,
+  GetAppIcon,
+} from '../icons'
+import {
+  ContactForm,
+  type ContactFormProps,
+} from '../contact'
+
+/**
+ * `<ShareExperienceSection>` — the case-studies "Share Your Experience"
+ * CTA block.
+ *
+ * Hub usage: rendered inside the unified case-studies chrome (between
+ * the search bar and the case-study card grid) so it stays at the same
+ * y-offset + gutters as the rest of the page content.
+ *
+ * Embedders mount this anywhere they like. The inner `<ContactForm>`
+ * submits through the AMBIENT `EndpointsRuntime.contactUrl` (same proxy
+ * seam every other embed-aware form uses), so embedders behind a
+ * `/content` reverse proxy get a working submission with no per-call-
+ * site wiring.
+ *
+ * **Copy is overridable.** Every string is a prop with a sensible
+ * "Flamingo case-studies" default so the hub keeps its existing copy
+ * verbatim; embedders override what they need.
+ *
+ * **Contact-form integration is configurable.** Hub auto-resolves
+ * `userId` / `helpCategoryOptions` / `rdtCid` / `onSubmitSuccess` from
+ * its app context and passes them down via `contactFormProps`;
+ * embedders without that context just omit them. All other
+ * `ContactFormProps` are forwarded too, so the host can adjust prefill,
+ * success redirect, hidden fields, etc. without forking this component.
+ */
+export interface ShareExperienceSectionProps {
+  /** Override the section heading. JSX so the host can break lines /
+   *  colorize the accent the same way the hub does. Default: the
+   *  hub's two-line "Share Your Experience / with Fellow MSPs:" copy. */
+  title?: React.ReactNode
+  /** Override the lead paragraph. Default: the hub's review-incentive
+   *  copy referencing Flamingo. Pass a brand-neutral string in embeds. */
+  subtitle?: React.ReactNode
+  /** Override the "How it works?" sub-heading. */
+  howItWorksTitle?: React.ReactNode
+  /** Override the "How it works?" body copy. */
+  howItWorksBody?: React.ReactNode
+  /** Forwarded to the inner `<ContactForm>`. The hub passes its
+   *  auto-resolved `userId` / `helpCategoryOptions` / `rdtCid` /
+   *  `onSubmitSuccess` here. Embedders pass overrides like
+   *  `successRedirectUrl` or extra prefill copy. */
+  contactFormProps?: Partial<ContactFormProps>
+  className?: string
+}
+
+const DEFAULT_TITLE: React.ReactNode = (
+  <>
+    Share Your Experience
+    <br />
+    with Fellow MSPs<span className="text-ods-accent">:</span>
+  </>
+)
+
+const DEFAULT_SUBTITLE: React.ReactNode = (
+  <>
+    We know your time is valuable. When you leave an honest review about
+    your Flamingo experience, we&apos;d like to thank you with a gift
+    certificate – not as payment for a review, but as appreciation for
+    the time you invest in helping other MSPs make informed decisions.
+  </>
+)
+
+const DEFAULT_HOW_IT_WORKS_TITLE: React.ReactNode = (
+  <>
+    How it works<span className="text-ods-accent">?</span>
+  </>
+)
+
+const DEFAULT_HOW_IT_WORKS_BODY: React.ReactNode = (
+  <>
+    Share your name and email with us, and we&apos;ll reach out to guide
+    you through the review process and arrange your thank-you gift
+    certificate.
+  </>
+)
+
+/** Defaults that match the hub's existing /case-studies behavior. Host
+ *  overrides via `contactFormProps` win over these. */
+const DEFAULT_CONTACT_FORM_PROPS = {
+  prefilledReason: 'I want to do a case study',
+  prefilledMessage: 'I want to do a case study',
+  hideFields: ['companySize', 'referralSource', 'helpCategory', 'message'] as ContactFormProps['hideFields'],
+  title: '',
+  subtitle: '',
+  footerText: '',
+  noBorder: true,
+  noPadding: true,
+  buttonVariant: 'outline' as ContactFormProps['buttonVariant'],
+  buttonClassName: 'w-full',
+  successToastMessage: "Thank you! We'll reach out to schedule your case study.",
+} satisfies Partial<ContactFormProps>
+
+export function ShareExperienceSection({
+  title = DEFAULT_TITLE,
+  subtitle = DEFAULT_SUBTITLE,
+  howItWorksTitle = DEFAULT_HOW_IT_WORKS_TITLE,
+  howItWorksBody = DEFAULT_HOW_IT_WORKS_BODY,
+  contactFormProps,
+  className,
+}: ShareExperienceSectionProps = {}) {
+  return (
+    <section className={`flex flex-col gap-10${className ? ` ${className}` : ''}`}>
+      <div className="text-ods-text-primary">
+        <h2 className="text-h1 text-ods-text-primary">{title}</h2>
+        <p className="text-h4 mt-6 max-w-[765px]">{subtitle}</p>
+      </div>
+
+      <div className="bg-ods-background border border-ods-border rounded-md p-10">
+        <div className="flex flex-col gap-10">
+          <div className="flex flex-col gap-6 text-ods-text-primary">
+            <h3 className="text-h2">{howItWorksTitle}</h3>
+            <p className="text-h4">{howItWorksBody}</p>
+          </div>
+
+          <BenefitCardGrid columns={4}>
+            <BenefitCard
+              icon={
+                <div className="bg-ods-background border border-ods-border rounded-md p-2 w-12 h-12 flex items-center justify-center">
+                  <G2Icon width={24} height={24} />
+                </div>
+              }
+              title="G2"
+              description="g2.com"
+              variant="auth-figma"
+            />
+            <BenefitCard
+              icon={
+                <div className="bg-ods-background border border-ods-border rounded-md p-2 w-12 h-12 flex items-center justify-center">
+                  <CapterraIcon width={24} height={24} />
+                </div>
+              }
+              title="Capterra"
+              description="capterra.com"
+              variant="auth-figma"
+            />
+            <BenefitCard
+              icon={
+                <div className="bg-ods-background border border-ods-border rounded-md p-2 w-12 h-12 flex items-center justify-center">
+                  <TrustpilotIcon width={24} height={24} />
+                </div>
+              }
+              title="TrustPilot"
+              description="trustpilot.com"
+              variant="auth-figma"
+            />
+            <BenefitCard
+              icon={
+                <div className="bg-ods-background border border-ods-border rounded-md p-2 w-12 h-12 flex items-center justify-center">
+                  <GetAppIcon width={24} height={24} />
+                </div>
+              }
+              title="GetApp"
+              description="getapp.com"
+              variant="auth-figma"
+            />
+          </BenefitCardGrid>
+
+          {/* Submission proxies through ambient EndpointsRuntime.contactUrl —
+           *  no per-call-site wiring needed for embeds behind a reverse
+           *  proxy. Hub's auto-resolving wrapper passes userId / rdtCid /
+           *  onSubmitSuccess via `contactFormProps`. */}
+          <ContactForm
+            {...DEFAULT_CONTACT_FORM_PROPS}
+            {...contactFormProps}
+          />
+        </div>
+      </div>
+    </section>
+  )
+}

package/src/components/chat/chat-container.tsx

@@ -12,16 +12,14 @@ import type { ConnectionIndicatorProps, ChatContainerProps, ChatHeaderProps } fr
 const ConnectionIndicator: React.FC<ConnectionIndicatorProps> = ({ status }) => {
   const getStatusStyles = () => {
     switch (status) {
-      // ODS attention tokens — same scheme used by the rest of the chat
-      // shell (StatusBadge, error toast, etc.). Hex Tailwind palette
-      // (`bg-green-500` / `bg-red-500`) would diverge from the theme and
-      // is forbidden by the host's design-token policy.
+      // ODS semantic status tokens — preset-defined utilities aliasing the same
+      // green/yellow/red as the raw ods-attention palette (which is CSS-vars only).
       case 'connected':
-        return 'bg-ods-attention-green-success'
+        return 'bg-ods-success'
       case 'connecting':
-        return 'bg-ods-attention-yellow-warning animate-pulse'
+        return 'bg-ods-warning animate-pulse'
       case 'disconnected':
-        return 'bg-ods-attention-red-error'
+        return 'bg-ods-error'
       default:
         return 'bg-ods-text-tertiary'
     }

package/src/components/chat/embeddable-chat.tsx

@@ -1127,7 +1127,7 @@ function EmbeddableChatInner({
   // falls back to the platform default here) — instead it sets a truthy baseRoute +
   // `chipBasePlatform` so doc chips with no externalUrl resolve cross-platform to that
   // platform's public knowledge hub (`getBaseUrl(chipBasePlatform)/knowledge-base/…`),
-  // exactly like the hub's openframe config (baseRoute:'/', chipBasePlatform:'flamingo').
+  // exactly like the hub's openframe config (baseRoute:'/', chipBasePlatform:'openframe').
   const resolvedBaseRoute =
     baseRoute || (source === 'flamingo' ? '/knowledge-base' : '/data-room')
 

package/src/components/chat/error-message-display.tsx

@@ -2,51 +2,69 @@
 
 import { forwardRef, useState } from "react"
 import { cn } from "../../utils/cn"
-import { AlertCircle, ChevronDown } from "lucide-react"
+import { AlertCircleIcon } from "../icons-v2-generated"
+import { ExpandChevron } from "./expand-chevron"
+import { useCollapsible } from "./hooks/use-collapsible"
 import type { ErrorMessageDisplayProps } from "./types"
 
+const iconTint = {
+  error: "text-ods-error",
+  warning: "text-ods-warning",
+  info: "text-ods-text-secondary",
+} as const
+
 const ErrorMessageDisplay = forwardRef<HTMLDivElement, ErrorMessageDisplayProps>(
-  ({ className, title, details, ...props }, ref) => {
-    const [isExpanded, setIsExpanded] = useState(false)
+  ({ className, title, details, type = "error", ...props }, ref) => {
+    const [expanded, setExpanded] = useState(false)
+    const { innerRef, containerStyle } = useCollapsible({ expanded })
+    const hasDetails = Boolean(details)
 
     return (
       <div
         ref={ref}
         className={cn(
-          "bg-[var(--ods-attention-red-error-secondary)] border border-ods-error rounded-[6px] p-3 mb-2 flex items-start gap-3",
+          "bg-ods-card rounded-md p-[var(--spacing-system-xsf)] mb-[var(--spacing-system-xsf)]",
           className
         )}
         {...props}
       >
-        <AlertCircle className="w-6 h-6 text-white flex-shrink-0 mt-0.5" />
-        <div className="flex flex-col gap-0.5 min-w-0 flex-1">
-          <div className="flex items-center justify-between gap-2">
-            <span className="text-lg leading-6 text-white font-['DM_Sans'] font-medium">
-              {title}
-            </span>
-            {details && (
-              <button
-                type="button"
-                onClick={() => setIsExpanded(prev => !prev)}
-                className="flex-shrink-0 p-0.5 rounded hover:bg-white/10 transition-colors"
-                aria-expanded={isExpanded}
-                aria-label={isExpanded ? "Collapse error details" : "Expand error details"}
-              >
-                <ChevronDown
-                  className={cn(
-                    "w-5 h-5 text-white transition-transform duration-200",
-                    isExpanded && "rotate-180"
-                  )}
-                />
-              </button>
+        <button
+          type="button"
+          onClick={hasDetails ? () => setExpanded(prev => !prev) : undefined}
+          aria-expanded={hasDetails ? expanded : undefined}
+          aria-label={
+            hasDetails ? (expanded ? "Collapse details" : "Expand details") : undefined
+          }
+          disabled={!hasDetails}
+          className={cn(
+            "flex w-full items-center gap-[var(--spacing-system-xsf)] text-left",
+            hasDetails ? "cursor-pointer" : "cursor-default"
+          )}
+        >
+          <AlertCircleIcon size={16} className={cn("shrink-0", iconTint[type])} />
+          <span
+            className={cn(
+              "min-w-0 flex-1 font-mono text-sm font-medium uppercase leading-5 tracking-[-0.28px]",
+              expanded ? "text-ods-text-primary" : "truncate text-ods-text-secondary"
             )}
+          >
+            {title}
+          </span>
+          {hasDetails && <ExpandChevron expanded={expanded} />}
+        </button>
+
+        {hasDetails && (
+          <div style={containerStyle}>
+            <div
+              ref={innerRef}
+              className="px-[var(--spacing-system-lf)] pt-[var(--spacing-system-xsf)]"
+            >
+              <p className="text-sm font-medium leading-5 text-ods-text-primary">
+                {details}
+              </p>
+            </div>
           </div>
-          {details && isExpanded && (
-            <span className="text-sm leading-5 text-white font-['DM_Sans'] font-medium mt-1">
-              {details}
-            </span>
-          )}
-        </div>
+        )}
       </div>
     )
   }

package/src/components/chat/types/component.types.ts

@@ -448,6 +448,8 @@ export interface ApprovalRequestMessageProps extends HTMLAttributes<HTMLDivEleme
 export interface ErrorMessageDisplayProps extends HTMLAttributes<HTMLDivElement> {
   title: string
   details?: string
+  /** Severity — drives the icon tint. Defaults to `error`. */
+  type?: 'error' | 'warning' | 'info'
 }
 
 // ========== Context Compaction Display Props ==========

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

@@ -2,7 +2,10 @@
 
 import React, { useMemo } from "react"
 import { MultiLevelNavigation, MobileNavigationDropdown } from "../navigation/multi-level-navigation"
-import { PageHeading } from "../layout/page-heading"
+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"
 import { PersistentSidebar, PersistentMobileDropdown } from "../persistent-filter-controls"
 import { CategorySidebarSkeleton } from "../loading/page-layout-skeleton"
 import { DocSearchBar, useDocSearch } from "../shared/doc-search"
@@ -12,6 +15,7 @@ import { useScrollSpy } from "./use-scroll-spy"
 import { useDocNavigation } from "./doc-navigation-context"
 import { findDocNodeByPath } from "../../utils/doc-tree-nav"
 import type { DocContent, DocNode, DocRenderHandlers, DocSourceId } from "../../types/doc-source"
+import { useDocsResolveLink } from "./use-docs-resolve-link"
 
 /** Color tokens for the doc-viewer chrome. Hub-side `DocViewer` callers share
  *  this constant; no need to override per source — the palette is intentionally
@@ -30,7 +34,7 @@ export const DEFAULT_DOC_VIEWER_PALETTE = {
 export interface DocViewerProps {
   /**
    * Registry source id (`'openframe-docs'`, `'data-room-docs'`, …). Flowed through
-   * `renderContent`'s handlers for `/api/resolve-link` POSTs.
+   * `renderContent`'s handlers for `/api/docs/resolve-link` POSTs.
    */
   sourceId: DocSourceId
 
@@ -55,7 +59,24 @@ export interface DocViewerProps {
    */
   chatSource: string
 
-  title: string | React.ReactNode
+  /** 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
+   *  `<DevSectionView>`'s hero uses (Map for Roadmap, Rocket for Releases,
+   *  etc.). Pass a pre-rendered React element styled with
+   *  `SECTION_HERO_ICON_CLASS` (`h-10 w-10 text-ods-accent`) for visual
+   *  parity with other lib pages. */
+  titleIcon?: React.ReactNode
+  /** Subtitle (h6, secondary text) rendered beneath the title. */
+  subtitle?: string
+  /** Render a yellow accent dot (`.`) after the title — same flag as
+   *  the hub's legacy `<AdminPageHeader accentDot>` so the docs-hub
+   *  surface keeps its existing accent styling after the migration. */
+  accentDot?: boolean
   /** Override the default ODS palette. Optional — most callers should omit. */
   colorPalette?: typeof DEFAULT_DOC_VIEWER_PALETTE
   className?: string
@@ -74,6 +95,17 @@ export interface DocViewerProps {
   structureEndpoint?: string
   /** Same shape as `structureEndpoint`. Defaults to `/api/docs/sources/${sourceId}/content`. */
   contentEndpoint?: string
+  /** RAG-search endpoint that backs the in-source search bar (when `showAIChat`
+   *  is on). Defaults to `/api/docs/search`. Override for proxy-prefix embeds —
+   *  same injectability pattern as `structureEndpoint` / `contentEndpoint`. */
+  searchEndpoint?: string
+  /** POST internal-link resolver. The viewer threads an async `onResolveLink`
+   *  into `renderContent`'s `handlers` that posts `{ link, currentPath, source }`
+   *  here. Defaults to `/api/docs/resolve-link`. Override for proxy-prefix embeds —
+   *  same injectability pattern as `structureEndpoint` / `contentEndpoint` /
+   *  `searchEndpoint`, with `ChatRuntime.endpoints.docsResolveLinkUrl` as a
+   *  runtime fallback (prop → runtime → default). */
+  resolveLinkEndpoint?: string
   /** Base route path for URL navigation. */
   baseRoute: string
 
@@ -85,6 +117,13 @@ export interface DocViewerProps {
 
   /** Folder-index filename (default `'README.md'`). */
   folderIndexFile?: string
+
+  /** Back-button shown above the title. Mirrors `<DevSectionPage>` /
+   *  `<HelpCenterList>` / `<LegalDocumentPage>` so every embeddable surface
+   *  shares the same chrome. Defaults to `{ label: 'Back to home', href: '/' }`.
+   *  Pass `false` to hide; pass `{ href: '/docs' }` etc. when the embed's
+   *  home isn't `/`. */
+  backButton?: { label?: string; href?: string } | false
 }
 
 export function DocViewer(props: DocViewerProps) {
@@ -97,16 +136,22 @@ function DocViewerContent({
   renderSkeleton,
   chatSource,
   title,
+  titleIcon,
+  subtitle,
+  accentDot,
   colorPalette = DEFAULT_DOC_VIEWER_PALETTE,
   className = "",
   docPath,
   sidebarLabel = "DOCUMENTATION",
   structureEndpoint,
   contentEndpoint,
+  searchEndpoint,
+  resolveLinkEndpoint,
   baseRoute,
   emptyStateText,
   showAIChat = false,
   folderIndexFile,
+  backButton,
 }: DocViewerProps) {
   // Default endpoints derived from sourceId. Hub callers omit the props in 99%
   // of cases; the override is for embed contexts where the doc-viewer sits
@@ -115,6 +160,13 @@ function DocViewerContent({
     structureEndpoint ?? `/api/docs/sources/${sourceId}/structure`
   const resolvedContentEndpoint =
     contentEndpoint ?? `/api/docs/sources/${sourceId}/content`
+  // Resolve-link endpoint chain (prop → ChatRuntime.endpoints → hub default)
+  // + the full fetch + JSON-parse pipeline live in `useDocsResolveLink`.
+  // Keeping it factored out as a proper hook makes the contract reusable
+  // by any embedder rendering doc content outside `<DocViewer>` (custom
+  // markdown renderers, link-resolver previews, etc.) and keeps this
+  // component focused on layout + state.
+  const resolveLink = useDocsResolveLink(sourceId, resolveLinkEndpoint)
   const {
     structure,
     selectedPath,
@@ -139,9 +191,23 @@ function DocViewerContent({
   const { activeSection, handleSectionClick } = useScrollSpy(content?.sections)
 
   const docNav = useDocNavigation()
+
+  // Back-button config — mirrors `<DevSectionPage>` so the docs surface
+  // matches every other embeddable page's chrome. Default target is `/`
+  // (the embed's home); pass `backButton: false` to hide entirely, or
+  // override the href when the embed's home isn't `/`.
+  const router = useRouter()
+  const backCfg =
+    backButton === false
+      ? null
+      : {
+          label: backButton?.label ?? 'Back to home',
+          onClick: () => router.push(backButton?.href ?? '/'),
+        }
   const docSearch = useDocSearch({
     source: chatSource,
     baseRoute,
+    searchEndpoint,
     onNavigate: (path) => navigateToDoc(path, { fromInternalLink: true }),
     onInPageSwap: (path) => docNav.navigate(path),
   })
@@ -152,8 +218,9 @@ function DocViewerContent({
       onInternalLinkClick: navigateToDoc,
       currentPath: selectedPath,
       sourceId,
+      onResolveLink: resolveLink,
     })
-  }, [content, selectedPath, renderContent, navigateToDoc, sourceId])
+  }, [content, selectedPath, renderContent, navigateToDoc, sourceId, resolveLink])
 
   // Selected node's documentType drives:
   //   - which skeleton the caller renders during fetch (markdown vs embed)
@@ -192,15 +259,32 @@ function DocViewerContent({
   const resolvedEmptyText = emptyStateText || defaultEmptyText
 
   return (
-    <section className={`${bgClass} ${className}`} style={bgStyle}>
-      <div
-        className="max-w-[1920px] px-6 md:px-20 py-6 md:py-10 mx-auto"
-        style={containerBgStyle}
-      >
-        <div className="flex flex-col gap-6">
-          <div className="flex flex-col gap-4">
-            {typeof title === 'string' ? <PageHeading>{title}</PageHeading> : title}
-          </div>
+    // 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
+    // palette overrides still apply (none in the codebase today; the API
+    // surface is preserved).
+    <PageShell contentClassName={`${bgClass} ${className}`}>
+      <div style={{ ...bgStyle, ...containerBgStyle }}>
+        <PageLayout backButton={backCfg ?? undefined}>
+          <div className="w-full flex flex-col gap-10">
+            <PageHeader
+              title={title}
+              titleIcon={titleIcon}
+              subtitle={subtitle}
+              accentDot={accentDot}
+              noTopPadding
+              noBottomMargin
+            />
 
           {showAIChat && (
             <DocSearchBar
@@ -271,9 +355,16 @@ function DocViewerContent({
               <div className="flex-1 min-w-0 w-full">
                 <div
                   className={`grid grid-cols-1 ${
-                    (showStickyNav && stickyNavSections.length > 0) ||
-                    isLoadingContent ||
-                    isLoadingStructure
+                    // "On this page" right column only makes sense for
+                    // MARKDOWN content (PDFs / Sheets / Figma / file have no
+                    // sections to navigate to). Gating the grid template on
+                    // `isMarkdownContent` also suppresses the section-skeleton
+                    // bars during embed loads — the user-reported "skeleton
+                    // shouldn't be on file pages" bug.
+                    isMarkdownContent &&
+                    ((showStickyNav && stickyNavSections.length > 0) ||
+                      isLoadingContent ||
+                      isLoadingStructure)
                       ? 'lg:grid-cols-[1fr_280px]'
                       : ''
                   } gap-8`}
@@ -292,7 +383,7 @@ function DocViewerContent({
                     </article>
                   </div>
 
-                  {(isLoadingContent || isLoadingStructure) && (
+                  {isMarkdownContent && (isLoadingContent || isLoadingStructure) && (
                     <div className="hidden lg:block">
                       <div className="sticky top-24">
                         <div className="h-[14px] w-28 bg-ods-border rounded animate-pulse mb-5" />
@@ -338,8 +429,9 @@ function DocViewerContent({
               </div>
             </div>
           )}
-        </div>
+          </div>
+        </PageLayout>
       </div>
-    </section>
+    </PageShell>
   )
 }