@flamingo-stack/openframe-frontend-core 0.0.296 → 0.0.297

package/src/components/embeds/twitter-embed-client.tsx

@@ -0,0 +1,308 @@
+"use client";
+
+import { useState, useEffect, useRef } from 'react';
+import { XLogo } from '../icons/x-logo';
+import { socialCache } from '../../utils/social-embed-cache';
+import { TwitterContainer } from './embed-container';
+import { useRichMarkdownRuntime } from './rich-markdown-runtime';
+
+// Using inline SVG icons to avoid dependency issues
+const MessageCircleIcon = () => (
+  <svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+    <path d="M21 15a2 2 0 01-2 2H7l-4 4V5a2 2 0 012-2h14a2 2 0 012 2z"/>
+  </svg>
+);
+
+const ExternalLinkIcon = () => (
+  <svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+    <path d="M18 13v6a2 2 0 01-2 2H5a2 2 0 01-2-2V8a2 2 0 012-2h6"/>
+    <polyline points="15,3 21,3 21,9"/>
+    <line x1="10" y1="14" x2="21" y2="3"/>
+  </svg>
+);
+
+const HeartIcon = () => (
+  <svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+    <path d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z"/>
+  </svg>
+);
+
+const RepeatIcon = () => (
+  <svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+    <polyline points="17,1 21,5 17,9"/>
+    <path d="M3 11V9a4 4 0 0 1 4-4h14"/>
+    <polyline points="7,23 3,19 7,15"/>
+    <path d="M21 13v2a4 4 0 0 1-4 4H3"/>
+  </svg>
+);
+
+const ClockIcon = () => (
+  <svg width="12" height="12" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+    <circle cx="12" cy="12" r="10"/>
+    <polyline points="12,6 12,12 16,14"/>
+  </svg>
+);
+
+const UserIcon = () => (
+  <svg width="12" height="12" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+    <path d="M20 21v-2a4 4 0 00-4-4H8a4 4 0 00-4 4v2"/>
+    <circle cx="12" cy="7" r="4"/>
+  </svg>
+);
+
+// X glyph: the lib's standard XLogo (color follows the text context).
+const XIcon = () => <XLogo className="w-5 h-5" color="currentColor" />;
+
+
+
+interface TwitterOEmbedResponse {
+  url: string;
+  author_name: string;
+  author_url: string;
+  html: string;
+  width: number;
+  height: number;
+  type: string;
+  cache_age: string;
+  provider_name: string;
+  provider_url: string;
+  version: string;
+}
+
+interface TwitterEmbedProps {
+  url: string;
+  tweetId?: string;
+  maxWidth?: number;
+}
+
+export function TwitterEmbedClient({ url, tweetId, maxWidth = 700 }: TwitterEmbedProps) {
+  const { twitterProxyUrl } = useRichMarkdownRuntime();
+  const [tweetData, setTweetData] = useState<TwitterOEmbedResponse | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const initializationDone = useRef(false);
+
+  // Extract tweet ID from URL if not provided
+  const extractedTweetId = tweetId || url.match(/status\/(\d+)/)?.[1];
+
+  // Normalize the Twitter URL
+  const tweetUrl = url.includes('twitter.com') || url.includes('x.com')
+    ? url
+    : `https://twitter.com/twitter/status/${extractedTweetId}`;
+
+  useEffect(() => {
+    // Only run once
+    if (initializationDone.current) return;
+    initializationDone.current = true;
+
+    if (!extractedTweetId) {
+      setError('Invalid tweet URL or ID');
+      setLoading(false);
+      return;
+    }
+
+    // Use centralized cache hierarchy
+    socialCache.fetchWithHierarchy({
+      platform: 'twitter',
+      url: tweetUrl,
+      apiEndpoint: twitterProxyUrl,
+      dataValidator: (data) => data && data.html,
+      onDataUpdate: (data) => setTweetData(data),
+      onError: (errorMsg) => setError(errorMsg),
+      onLoading: (loading) => setLoading(loading)
+    });
+  }, []); // Empty dependency array - only run once
+
+  if (loading) {
+    return (
+      <TwitterContainer>
+        <div className="border border-ods-border rounded-lg p-6 bg-ods-card animate-pulse">
+          <div className="flex items-center space-x-3 mb-4">
+            <div className="w-12 h-12 bg-ods-border rounded-full"></div>
+            <div>
+              <div className="h-4 bg-ods-border rounded w-32 mb-2"></div>
+              <div className="h-3 bg-ods-border rounded w-24"></div>
+            </div>
+          </div>
+          <div className="space-y-2 mb-4">
+            <div className="h-4 bg-ods-border rounded w-full"></div>
+            <div className="h-4 bg-ods-border rounded w-3/4"></div>
+          </div>
+          <div className="flex items-center space-x-4">
+            <div className="h-4 bg-ods-border rounded w-16"></div>
+            <div className="h-4 bg-ods-border rounded w-16"></div>
+            <div className="h-4 bg-ods-border rounded w-16"></div>
+          </div>
+        </div>
+      </TwitterContainer>
+    );
+  }
+
+  if (error || !tweetData) {
+    return (
+      <TwitterContainer>
+        <div className="border border-ods-border rounded-lg p-6 bg-ods-card">
+          <div className="flex items-center space-x-3 text-ods-text-secondary mb-4">
+            <XIcon />
+            <span>Tweet unavailable</span>
+          </div>
+
+          <div className="text-center">
+            <p className="text-ods-text-secondary text-sm mb-4">
+              This tweet could not be loaded. It may have been deleted, made private, or the account may be suspended.
+            </p>
+            <a
+              href={url}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex items-center space-x-2 px-4 py-2 bg-ods-bg-secondary text-ods-text-primary rounded-md text-sm font-medium hover:bg-ods-bg-tertiary transition-colors"
+            >
+              <XIcon />
+              <span>View on X</span>
+            </a>
+          </div>
+        </div>
+      </TwitterContainer>
+    );
+  }
+
+  // Parse the HTML to extract detailed tweet information and media
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(tweetData.html, 'text/html');
+  const blockquote = doc.querySelector('blockquote');
+
+  // Extract tweet text (remove attribution line)
+  const fullText = blockquote?.textContent || '';
+  const tweetText = fullText.replace(/- .* \(@.*\).*$/, '').trim();
+
+  // Extract username from author_url (e.g., https://twitter.com/username)
+  const username = tweetData.author_url ? tweetData.author_url.split('/').pop() : '';
+
+
+
+  // Extract any links from the tweet
+  const links = Array.from(blockquote?.querySelectorAll('a') || [])
+    .map(link => ({
+      url: link.href,
+      text: link.textContent || link.href
+    }))
+    .filter(link => !link.url.includes('twitter.com') && !link.url.includes('x.com'));
+
+  // Format time (simulated - we don't have real timestamp from oEmbed)
+  const formatTime = () => {
+    return 'on X'; // Simplified since we don't have actual timestamp
+  };
+
+  const truncateText = (text: string, maxLength: number = 600) => {
+    if (text.length <= maxLength) return text;
+    return text.slice(0, maxLength) + '...';
+  };
+
+  // Profile picture URL using Unavatar service.
+  // The hub used to proxy this via `useProxiedImageUrl` (chat runtime), but
+  // docs / blog pages don't mount a chat runtime, so we fetch unavatar
+  // directly. Embedders that need a proxy can register a runtime later.
+  const getProfilePicUrl = (username: string | undefined) => {
+    if (!username) return '';
+    return `https://unavatar.io/twitter/${username}`;
+  };
+
+  return (
+    <TwitterContainer>
+      <div className="border border-ods-border rounded-lg bg-ods-card overflow-hidden">
+        {/* Header with Profile Picture */}
+        <div className="p-4 border-b border-ods-border">
+          <div className="flex items-center justify-between">
+            <div className="flex items-center space-x-3">
+              {/* User Profile Picture */}
+              <div className="w-8 h-8 rounded-full overflow-hidden flex-shrink-0">
+                <img
+                  src={getProfilePicUrl(username)}
+                  alt={`${tweetData.author_name} profile picture`}
+                  className="w-full h-full object-cover"
+                  onError={(e) => {
+                    // Simple fallback without state updates
+                    const target = e.target as HTMLImageElement;
+                    target.src = 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIGZpbGw9Im5vbmUiIHN0cm9rZT0iY3VycmVudENvbG9yIiB2aWV3Qm94PSIwIDAgMjQgMjQiPjxwYXRoIGQ9Ik0yMCAyMXYtMmE0IDQgMCAwIDAtNC00SDhhNCA0IDAgMCAwLTQgNHYyIi8+PGNpcmNsZSBjeD0iMTIiIGN5PSI3IiByPSI0Ii8+PC9zdmc+';
+                  }}
+                />
+              </div>
+              <div>
+                <p className="text-ods-text-primary font-medium">@{username}</p>
+                <div className="flex items-center space-x-2 text-ods-text-secondary text-sm">
+                  <UserIcon />
+                  <span>{tweetData.author_name}</span>
+                  <ClockIcon />
+                  <span>{formatTime()}</span>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {/* Content */}
+        <div className="p-4">
+          {tweetText && (
+            <div
+              className="text-ods-text-secondary text-sm leading-relaxed mb-4 overflow-hidden"
+              style={{ maxHeight: `${maxWidth - 200}px` }}
+            >
+              <p className="whitespace-pre-wrap">
+                {truncateText(tweetText)}
+              </p>
+            </div>
+          )}
+
+
+
+          {/* Links Section */}
+          {links.length > 0 && (
+            <div className="mb-4 space-y-2">
+              {links.map((link, index) => (
+                <a
+                  key={index}
+                  href={link.url}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex items-center space-x-2 text-[#1DA1F2] hover:text-ods-accent transition-colors text-sm"
+                >
+                  <ExternalLinkIcon />
+                  <span className="underline">{link.text}</span>
+                </a>
+              ))}
+            </div>
+          )}
+
+          {/* Stats */}
+          <div className="flex items-center space-x-6 text-ods-text-secondary text-sm">
+            <div className="flex items-center space-x-1">
+              <HeartIcon />
+              <span>Likes</span>
+            </div>
+            <div className="flex items-center space-x-1">
+              <RepeatIcon />
+              <span>Retweets</span>
+            </div>
+            <div className="flex items-center space-x-1">
+              <MessageCircleIcon />
+              <span>Replies</span>
+            </div>
+          </div>
+        </div>
+
+        {/* Footer */}
+        <div className="px-4 py-3 bg-ods-bg-secondary border-t border-ods-border">
+          <a
+            href={url}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center space-x-2 text-ods-accent hover:opacity-80 transition-colors text-sm font-medium"
+          >
+            <ExternalLinkIcon />
+            <span>View on X</span>
+          </a>
+        </div>
+      </div>
+    </TwitterContainer>
+  );
+}

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

@@ -10,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[]
@@ -33,6 +38,8 @@ export function PageLayout({
   children,
   title,
   subtitle,
+  titleIcon,
+  accentDot,
   image,
   backButton,
   actions,
@@ -46,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}
@@ -74,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, min-h-screen, 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>
+  )
+}