@flamingo-stack/openframe-frontend-core 0.0.206 → 0.0.207-snapshot.20260526023528

package/package.json

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

package/src/components/chat/hooks/use-realtime-chunk-processor.ts

@@ -55,11 +55,22 @@ export function useRealtimeChunkProcessor(
         })
       }
 
+      // Resumed dialog: a MESSAGE_START already fired server-side. Treat
+      // subsequent continuation chunks (after the next MESSAGE_END) as
+      // post-stream so they append into the existing bubble instead of
+      // replacing its content via the cold-start cumulative path.
+      hasEverStreamedRef.current = true
       hasInitializedWithData.current = true
     }
   }, [initialState, callbacks])
 
   const isInStreamRef = useRef(false)
+  // Distinguishes post-MESSAGE_END continuation (append into prior bubble)
+  // from cold-start before any MESSAGE_START (cumulative; otherwise
+  // appendSegmentsToLastAssistant silently drops the chunk when no
+  // assistant bubble exists yet). Flipped true on MESSAGE_START and on
+  // resumed-dialog initializeWithState.
+  const hasEverStreamedRef = useRef(false)
 
   // Track pending escalated approvals (single or batch)
   const pendingEscalatedRef = useRef<
@@ -85,6 +96,7 @@ export function useRealtimeChunkProcessor(
       switch (action.action) {
         case 'message_start':
           isInStreamRef.current = true
+          hasEverStreamedRef.current = true
           callbacks.onStreamStart?.()
           accumulator.resetSegments()
           break
@@ -101,17 +113,43 @@ export function useRealtimeChunkProcessor(
 
         case 'text': {
           const segments = accumulator.appendText(action.text)
-          callbacks.onSegmentsUpdate?.(segments)
+          // Append-mode only for *true* post-stream continuation (after a
+          // MESSAGE_END we actually saw). Cold-start chunks (no prior
+          // MESSAGE_START) emit cumulative segments so the consumer can
+          // spawn the first assistant bubble — otherwise appendSegmentsToLastAssistant
+          // silently drops the chunk when no last assistant exists.
+          if (isInStreamRef.current || !hasEverStreamedRef.current) {
+            callbacks.onSegmentsUpdate?.(segments)
+          } else {
+            callbacks.onSegmentsUpdate?.([{ type: 'text', text: action.text }], { append: true })
+          }
           break
         }
 
         case 'thinking': {
           const segments = accumulator.appendThinking(action.text)
-          callbacks.onSegmentsUpdate?.(segments)
+          if (isInStreamRef.current || !hasEverStreamedRef.current) {
+            callbacks.onSegmentsUpdate?.(segments)
+          } else {
+            callbacks.onSegmentsUpdate?.([{ type: 'thinking', text: action.text }], { append: true })
+          }
           break
         }
 
         case 'tool_execution': {
+          // Post-MESSAGE_END tool chunks (cancellations / async batch
+          // results for a batch in a prior bubble) flow only through the
+          // cross-message updater. Skipping the accumulator avoids
+          // pushing a standalone segment that the next text chunk would
+          // replay into a new bubble.
+          if (!isInStreamRef.current && callbacks.onToolExecuted) {
+            callbacks.onToolExecuted(action.segment)
+            break
+          }
+          // In-stream: accumulator-driven update of the streaming bubble
+          // is the source of truth. Don't fire onToolExecuted here — its
+          // cross-message scan is first-match-wins and could touch a
+          // same-execId segment in a prior bubble (agent retry case).
           const segments = accumulator.addToolExecution(action.segment)
           callbacks.onSegmentsUpdate?.(segments)
           break
@@ -234,11 +272,20 @@ export function useRealtimeChunkProcessor(
               callbacks.onSegmentsUpdate?.(segments)
             }
           } else {
-            const segments = accumulator.updateApprovalStatus(requestId, status)
-            callbacks.onSegmentsUpdate?.(segments)
+            // Always keep the in-memory accumulator in sync so a following
+            // text/tool chunk replays the resolved status into the message.
+            accumulator.updateApprovalStatus(requestId, status)
+            // When the consumer wires cross-message resolution via
+            // `onApprovalResolved`, skip `onSegmentsUpdate` here: this path
+            // routes through `ensureAssistantMessage` + `updateStreamingMessageSegments`,
+            // which adopts/creates an assistant bubble and replays the
+            // accumulator's segments into it — turning a status flip into a
+            // bubble overwrite that wipes the original card.
+            if (!callbacks.onApprovalResolved) {
+              callbacks.onSegmentsUpdate?.(accumulator.getSegments())
+            }
           }
-          // approvalType from the result is informational; not consumed downstream yet.
-          void approvalType
+          callbacks.onApprovalResolved?.(requestId, status, approvalType)
           break
         }
 

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

@@ -5,7 +5,13 @@
 
 import type { ChunkData, NatsMessageType, FetchChunksFunction } from './network.types'
 import type { ChatType, ChatApprovalStatus } from './chat.types'
-import type { MessageSegment, PendingToolCallData, TokenUsageData, ExecutingToolState } from './message.types'
+import type {
+  MessageSegment,
+  PendingToolCallData,
+  TokenUsageData,
+  ExecutingToolState,
+  ToolExecutionSegment,
+} from './message.types'
 
 // ========== Hook Options ==========
 
@@ -169,6 +175,22 @@ export interface RealtimeChunkCallbacks {
   onEscalatedApproval?: (requestId: string, data: { command: string; explanation?: string; approvalType: string }) => void
   /** Called when an escalated approval result is received */
   onEscalatedApprovalResult?: (requestId: string, approved: boolean, data: { command: string; explanation?: string; approvalType: string }) => void
+  /**
+   * Called whenever an `APPROVAL_RESULT` chunk is processed. Fires in addition
+   * to the accumulator's in-message status flip so consumers can find the
+   * matching `approval_request` / `approval_batch` segment in an *earlier*
+   * message bubble (e.g. when a user-interrupted approval is resolved while
+   * a new assistant message is streaming). Idempotent — safe to no-op if no
+   * matching segment is found dialog-wide.
+   */
+  onApprovalResolved?: (requestId: string, status: ChatApprovalStatus, approvalType: string) => void
+  /**
+   * Called whenever an `EXECUTED_TOOL` chunk is processed. Lets consumers
+   * merge the result into the originating `EXECUTING_TOOL` (or batch
+   * `executions[execId]`) segment in an earlier message bubble when the tool
+   * outlived its message scope. Idempotent.
+   */
+  onToolExecuted?: (segment: ToolExecutionSegment) => void
   /** Called when a DIALOG_CLOSED chunk is received */
   onDialogClosed?: () => void
 }

package/src/components/index.ts

@@ -65,6 +65,14 @@ export * from './shared/onboarding'
 // Product Release components
 export * from './shared/product-release'
 
+// Dev-center shared components (Roadmap / Delivery / DevSectionView chrome)
+export * from './shared/dev-section'
+export * from './shared/roadmap'
+export * from './shared/delivery'
+
+// Legal-document shared component (privacy policy, terms of service)
+export * from './shared/legal-document'
+
 // Detail Page Skeleton
 export { DetailPageSkeleton, type DetailPageSkeletonProps } from './shared/detail-page-skeleton'
 

package/src/components/shared/delivery/delivery-lists.tsx

@@ -0,0 +1,199 @@
+'use client';
+
+/**
+ * DeliveryLists — the delivery section body (two tables: recently
+ * completed + active). Reads `search` and `task_type` URL params
+ * written by the shared `<DevSectionView>` chrome and refetches on
+ * change.
+ *
+ * Endpoint configuration:
+ *   - `completedApiEndpoint` / `inProgressApiEndpoint` are the two
+ *     per-bucket GET endpoints. Defaults match the hub's pre-migration
+ *     routes (`/api/delivery/completed`, `/api/delivery/in-progress`).
+ *
+ * Coupling constraint — `searchParamKey` / `taskTypeParamKey`:
+ *   These props serve TWO purposes:
+ *     1. URL READS — keys this component reads via `useSearchParams()`.
+ *        MUST match the consuming chrome's `section.search.paramKey` /
+ *        `section.filter.paramKey` (the chrome WRITES the URL params).
+ *     2. API WRITES — keys this component sends as query params on the
+ *        outbound fetch to `{completedApiEndpoint,inProgressApiEndpoint}`.
+ *        The hub API contract uses `'search'` / `'task_type'`; embedders
+ *        reverse-proxying those routes must preserve the same names OR
+ *        rewrite the inbound query string on the proxy side.
+ *
+ *   Defaults align with `OPENFRAME_DEV_SECTIONS.delivery.{search.paramKey,filter.paramKey}`
+ *   AND the hub API contract, so the OpenFrame zero-config case "just
+ *   works". Custom chrome overriding the param keys must override BOTH
+ *   ends consistently AND ensure the backend reads the same names.
+ */
+
+import { useEffect, useState } from 'react';
+import { useSearchParams, useRouter, usePathname } from '../../../embed-shims';
+import type { DeliveryResponse } from '../../../types/delivery';
+import { DeliveryTable } from './delivery-table';
+import { EmptyState } from '../../empty-state';
+import { LoadError } from '../../ui/error-state';
+
+const DEFAULT_COMPLETED_ENDPOINT = '/api/delivery/completed';
+const DEFAULT_IN_PROGRESS_ENDPOINT = '/api/delivery/in-progress';
+const DEFAULT_SEARCH_PARAM_KEY = 'search';
+const DEFAULT_TASK_TYPE_PARAM_KEY = 'task_type';
+
+export interface DeliveryListsProps {
+  /** GET endpoint for the "Recently Completed" bucket. Default
+   *  `/api/delivery/completed`. */
+  completedApiEndpoint?: string;
+  /** GET endpoint for the "Active Tasks" bucket. Default
+   *  `/api/delivery/in-progress`. */
+  inProgressApiEndpoint?: string;
+  /** URL param key for the search input. MUST match the consuming
+   *  chrome's `section.search.paramKey`. Default `'search'`. */
+  searchParamKey?: string;
+  /** URL param key for the task-type filter. MUST match the consuming
+   *  chrome's `section.filter.paramKey`. Default `'task_type'`. */
+  taskTypeParamKey?: string;
+}
+
+export function DeliveryLists({
+  completedApiEndpoint = DEFAULT_COMPLETED_ENDPOINT,
+  inProgressApiEndpoint = DEFAULT_IN_PROGRESS_ENDPOINT,
+  searchParamKey = DEFAULT_SEARCH_PARAM_KEY,
+  taskTypeParamKey = DEFAULT_TASK_TYPE_PARAM_KEY,
+}: DeliveryListsProps = {}) {
+  const searchParams = useSearchParams();
+  const router = useRouter();
+  const pathname = usePathname();
+
+  const [data, setData] = useState<DeliveryResponse | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // Get filter state from URL
+  const searchQuery = searchParams.get(searchParamKey) || '';
+  const taskTypeFilter = searchParams.get(taskTypeParamKey) || 'all';
+
+  useEffect(() => {
+    async function fetchDeliveryData() {
+      try {
+        setIsLoading(true);
+        setError(null);
+
+        // Build query parameters for filtering. The outbound key names
+        // mirror the inbound URL-param keys — see "Coupling constraint"
+        // in the file docblock for why.
+        const params = new URLSearchParams();
+        if (searchQuery) {
+          params.set(searchParamKey, searchQuery);
+        }
+        if (taskTypeFilter && taskTypeFilter !== 'all') {
+          params.set(taskTypeParamKey, taskTypeFilter);
+        }
+        const queryString = params.toString();
+        const queryParam = queryString ? `?${queryString}` : '';
+
+        // Fetch completed and in-progress tasks separately with filters
+        const [completedResponse, inProgressResponse] = await Promise.all([
+          fetch(`${completedApiEndpoint}${queryParam}`),
+          fetch(`${inProgressApiEndpoint}${queryParam}`),
+        ]);
+
+        if (!completedResponse.ok || !inProgressResponse.ok) {
+          throw new Error('Failed to fetch delivery items');
+        }
+
+        const [completedResult, inProgressResult] = await Promise.all([
+          completedResponse.json(),
+          inProgressResponse.json(),
+        ]);
+
+        setData({
+          completed: completedResult.items || [],
+          inProgress: inProgressResult.items || [],
+        });
+      } catch (err) {
+        console.error('Error fetching delivery items:', err);
+        setError('Failed to load delivery items. Please try again later.');
+      } finally {
+        setIsLoading(false);
+      }
+    }
+
+    fetchDeliveryData();
+  }, [searchQuery, taskTypeFilter, completedApiEndpoint, inProgressApiEndpoint, searchParamKey, taskTypeParamKey]);
+
+  const filteredCompleted = data?.completed || [];
+  const filteredInProgress = data?.inProgress || [];
+
+  const showCompleted = true;
+  const showInProgress = true;
+
+  const hasActiveFilters = searchQuery !== '' || taskTypeFilter !== 'all';
+  const hasResults = (showCompleted && filteredCompleted.length > 0) || (showInProgress && filteredInProgress.length > 0);
+
+  // Error state — consume lib's canonical LoadError so ODS tokens +
+  // retry affordance stay in lockstep with every other surface.
+  if (error) {
+    return (
+      <div className="w-full">
+        <LoadError message={error} onRetry={() => window.location.reload()} />
+      </div>
+    );
+  }
+
+  return (
+    <div className="w-full flex flex-col gap-[40px]">
+      {/* Empty state if no results after filtering */}
+      {!isLoading && !hasResults && (
+        hasActiveFilters ? (
+          <EmptyState
+            type="search"
+            title="No tasks found"
+            description="No tasks match your current filters. Try adjusting your search or status filter."
+            showCTA={true}
+            ctaText="Reset Filters"
+            onCtaClick={() => {
+              const params = new URLSearchParams(searchParams.toString());
+              params.delete(searchParamKey);
+              params.delete(taskTypeParamKey);
+              router.replace(`${pathname}?${params.toString()}`, { scroll: false });
+            }}
+          />
+        ) : (
+          <EmptyState
+            type="generic"
+            title="No tasks available"
+            description="Check back soon for upcoming tasks!"
+            showCTA={false}
+          />
+        )
+      )}
+
+      {/* Completed Tasks Table */}
+      {showCompleted && (hasResults || isLoading) && (
+        <div className="w-full">
+          <h3 className="text-h2 text-ods-text-primary tracking-[-0.48px] md:tracking-[-0.56px] lg:tracking-[-0.64px] mb-4">
+            Recently Completed<span className="text-ods-accent">:</span>
+          </h3>
+          <DeliveryTable
+            items={filteredCompleted}
+            isLoading={isLoading}
+          />
+        </div>
+      )}
+
+      {/* In Progress Tasks Table */}
+      {showInProgress && (hasResults || isLoading) && (
+        <div className="w-full">
+          <h3 className="text-h2 text-ods-text-primary tracking-[-0.48px] md:tracking-[-0.56px] lg:tracking-[-0.64px] mb-4">
+            Active Tasks<span className="text-ods-accent">:</span>
+          </h3>
+          <DeliveryTable
+            items={filteredInProgress}
+            isLoading={isLoading}
+          />
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/shared/delivery/delivery-table.tsx

@@ -0,0 +1,174 @@
+'use client';
+
+import { StatusBadge } from '../../ui';
+import { getStatusColorScheme } from '../../../utils';
+import {
+  type DeliveryItem,
+  TASK_TYPE_LABELS,
+  TASK_TYPE_TEXT_COLORS,
+} from '../../../types/delivery';
+
+interface DeliveryTableProps {
+  items: DeliveryItem[];
+  isLoading?: boolean;
+}
+
+/**
+ * Format relative time for display
+ */
+function getRelativeTime(timestamp: number): string {
+  const now = Date.now();
+  const diff = now - timestamp;
+  const days = Math.floor(diff / (1000 * 60 * 60 * 24));
+  const weeks = Math.floor(days / 7);
+  const months = Math.floor(days / 30);
+
+  if (months > 0) {
+    return months === 1 ? 'last month' : `${months} months ago`;
+  }
+  if (weeks > 0) {
+    return weeks === 1 ? 'last week' : `${weeks} weeks ago`;
+  }
+  if (days > 0) {
+    return days === 1 ? 'yesterday' : `${days} days ago`;
+  }
+  return 'today';
+}
+
+/**
+ * Skeleton loader for rows - matching responsive structure
+ */
+function SkeletonRow() {
+  return (
+    <div className="border-b border-ods-border last:border-b-0 p-[12px] md:p-[16px]">
+      <div className="flex flex-col md:flex-row items-start justify-between gap-[12px] md:gap-[16px] w-full">
+        {/* Left: Title, subtitle, and description skeleton */}
+        <div className="flex-1 min-w-0 w-full md:w-auto flex flex-col gap-[12px] md:gap-[16px]">
+          {/* Title skeleton - responsive */}
+          <div className="min-h-[24px] flex items-center">
+            <div className="h-[20px] bg-ods-border rounded animate-pulse w-full"></div>
+          </div>
+          {/* Subtitle skeleton - 1 line */}
+          <div className="min-h-[20px] flex items-center">
+            <div className="h-[20px] bg-ods-border rounded animate-pulse w-1/2"></div>
+          </div>
+          {/* Description skeleton - 3 lines */}
+          <div className="min-h-[72px] flex items-center">
+            <div className="flex-1 space-y-1">
+              <div className="h-[20px] bg-ods-border rounded animate-pulse w-full"></div>
+              <div className="h-[20px] bg-ods-border rounded animate-pulse w-full"></div>
+              <div className="h-[20px] bg-ods-border rounded animate-pulse w-2/3"></div>
+            </div>
+          </div>
+        </div>
+
+        {/* Right: Badge skeleton - two stacked badges */}
+        <div className="flex-shrink-0 self-start flex flex-col gap-2">
+          <div className="h-[32px] w-[100px] bg-ods-border rounded animate-pulse"></div>
+          <div className="h-[32px] w-[120px] bg-ods-border rounded animate-pulse"></div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * DeliveryTable Component
+ * Displays bug fixes and enhancements with fixed-height rows
+ */
+export function DeliveryTable({ items, isLoading = false }: DeliveryTableProps) {
+  // Show skeletons while loading
+  if (isLoading) {
+    return (
+      <div className="bg-ods-card border border-ods-border rounded-[6px] overflow-hidden w-full">
+        <div className="w-full">
+          {[1, 2, 3, 4, 5].map((i) => (
+            <SkeletonRow key={i} />
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  // Empty state
+  if (items.length === 0) {
+    return (
+      <div className="bg-ods-card border border-ods-border rounded-[6px] p-[40px] text-center w-full">
+        <p className="text-ods-text-secondary text-[14px] font-['DM_Sans'] font-medium">
+          No tasks available
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="bg-ods-card border border-ods-border rounded-[6px] overflow-hidden w-full">
+      <div className="w-full">
+        {items.map((item, index) => {
+          // Get task type badge label and text color
+          const taskType = item.taskType as keyof typeof TASK_TYPE_LABELS;
+          const typeBadgeLabel = TASK_TYPE_LABELS[taskType] || 'TASK';
+          const typeBadgeTextColor = TASK_TYPE_TEXT_COLORS[taskType] || '';
+
+          // Get status badge color scheme using centralized utility
+          const statusBadgeScheme = getStatusColorScheme(item.status);
+
+          // Calculate relative time from last activity (dateUpdated)
+          const relativeTime = getRelativeTime(item.dateUpdated);
+
+          return (
+            <div
+              key={item.id}
+              className={`border-b border-ods-border last:border-b-0 p-[12px] md:p-[16px] ${index === 0 ? '' : ''}`}
+            >
+              <div className="flex flex-col md:flex-row items-start justify-between gap-[12px] md:gap-[16px] w-full">
+                {/* Left: Title, subtitle, and description - matching roadmap-card.tsx structure */}
+                <div className="flex-1 min-w-0 w-full md:w-auto flex flex-col gap-[12px] md:gap-[16px]">
+                  {/* Title: 2 lines on mobile, 1 line on desktop */}
+                  <div className="min-h-[24px] md:min-h-[24px] flex items-center">
+                    <h3 className="text-h3 text-ods-text-primary tracking-[-0.36px] flex-1 line-clamp-2 md:truncate break-words">
+                      {item.title}
+                    </h3>
+                  </div>
+
+                  {/* Subtitle: 1 line with last activity date, list name(s), task ID - Azeret Mono.
+                      A task can live in multiple ClickUp lists ("Tasks in Multiple Lists" feature) —
+                      we render every list joined by ", ". */}
+                  <div className="min-h-[20px] flex items-center">
+                    <p className="text-h5 text-ods-text-secondary uppercase tracking-[-0.28px] truncate">
+                      ACTIVE {relativeTime}{item.listNames.length > 0 ? `, ${item.listNames.join(', ')}` : ''}, {item.id}
+                    </p>
+                  </div>
+
+                  {/* Description: 3 lines max, 72px height with vertical centering - matching roadmap */}
+                  <div className="min-h-[72px] flex items-center">
+                    <p className="text-h4 text-ods-text-secondary line-clamp-3 break-words">
+                      {item.description || 'No description provided'}
+                    </p>
+                  </div>
+                </div>
+
+                {/* Right: Status and Type badges stacked vertically */}
+                <div className="flex-shrink-0 self-start flex flex-col gap-2">
+                  {/* Status Badge - matching roadmap cards */}
+                  <StatusBadge
+                    text={item.status.toUpperCase()}
+                    colorScheme={statusBadgeScheme}
+                    variant="card"
+                    className="border border-ods-border"
+                  />
+                  {/* Task Type Badge - same style as Version badge in roadmap */}
+                  <StatusBadge
+                    text={typeBadgeLabel}
+                    variant="card"
+                    className={`border border-ods-border ${typeBadgeTextColor}`}
+                  />
+                </div>
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/src/components/shared/delivery/index.ts

@@ -0,0 +1,9 @@
+// NOTE: `DeliverySection` (standalone unfiltered fetch) was deleted —
+// it had zero consumers (hub's release-detail wraps `<DeliveryTable>`
+// directly, the public bug-fixes-and-enhancements page uses
+// `<DeliveryLists>` with URL-driven filters) and duplicated the
+// fetch/loading state machine. If an embedder ever needs a no-filter
+// variant, build it as `<DeliveryLists ignoreUrlFilters />` rather
+// than reviving a separate component.
+export { DeliveryLists, type DeliveryListsProps } from './delivery-lists';
+export { DeliveryTable } from './delivery-table';

package/src/components/shared/dev-section/dev-section-page.tsx

@@ -0,0 +1,72 @@
+'use client';
+
+/**
+ * DevSectionPage — full-page wrapper for a dev-center section
+ * (`/roadmap`, `/bug-fixes-and-enhancements`, `/releases`).
+ *
+ * Mounts the lib's canonical `PageLayout` directly (no in-app wrapper)
+ * so the back-button affordance stays in lockstep with whatever the
+ * design system ships — any future lib change to BackButton / TitleBlock
+ * propagates automatically.
+ *
+ * Composition: `PageShell` → `PageLayout` (back-to-home wired) →
+ * `DevSectionView` (icon hero + search + filter pills) → list body.
+ *
+ * Adding a new section is one entry in `OPENFRAME_DEV_SECTIONS` plus a
+ * single-line page file mounting this factory with the new key.
+ */
+
+import type { ReactNode } from 'react';
+import { useRouter } from '../../../embed-shims/next-navigation';
+import { PageShell, PageLayout } from '../../ui';
+import { DevSectionView } from './dev-section-view';
+import {
+  OPENFRAME_DEV_SECTIONS,
+  type OpenframeDevSectionKey,
+} from '../../../utils/dev-sections/openframe-dev-sections';
+
+const SECTION_HERO_ICON_CLASS = 'h-10 w-10 text-ods-accent';
+
+export interface DevSectionPageProps {
+  sectionKey: OpenframeDevSectionKey;
+  /** The page-specific list body (e.g. `<RoadmapList />`). */
+  children: ReactNode;
+  /** Back-button config — same shape as `LegalDocumentPage` /
+   *  `ReleaseDetailPage`. Pass `false` to hide. Default
+   *  `{ label: 'Back to home', href: '/' }`. */
+  backButton?: { label?: string; href?: string } | false;
+}
+
+export function DevSectionPage({ sectionKey, children, backButton }: DevSectionPageProps) {
+  const router = useRouter();
+  const section = OPENFRAME_DEV_SECTIONS[sectionKey];
+  const Icon = section.icon;
+
+  // Back-button config — mirrors LegalDocumentPage / ReleaseDetailPage.
+  // Default: { label: 'Back to home', href: '/' }. Pass `false` to hide.
+  // After `backButton &&` narrowing, inner type is `{ label?, href? } |
+  // undefined`; don't re-compare to `false` (TS2367).
+  const backCfg =
+    backButton === false
+      ? undefined
+      : {
+          label: (backButton ? backButton.label : undefined) ?? 'Back to home',
+          onClick: () => router.push((backButton ? backButton.href : undefined) ?? '/'),
+        };
+
+  return (
+    <PageShell>
+      <PageLayout backButton={backCfg}>
+        <DevSectionView
+          sectionKey={sectionKey}
+          hero={{
+            icon: <Icon className={SECTION_HERO_ICON_CLASS} />,
+            description: section.hero.description,
+          }}
+        >
+          {children}
+        </DevSectionView>
+      </PageLayout>
+    </PageShell>
+  );
+}