@clidey/dory 1.0.7 → 1.9.0

package/src/ui/layout.tsx

@@ -1,7 +1,7 @@
 import type { ComponentChildren } from 'preact';
-import { useCallback, useEffect, useMemo, useRef, useState } from 'preact/hooks';
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks';
 import { Navigation } from '../components/navigation';
-import { ALL_NAVIGATION, ALL_OPENAPI, completeFrontMatter, loadMDXFrontMatterForPath, loadAllMDXFrontMatter, preloadFrontmatter, ALL_ASYNCAPI, isFrontmatterReady } from '../components/store';
+import { ALL_NAVIGATION, ALL_PAGES, ALL_OPENAPI, completeFrontMatter, loadMDXFrontMatterForPath, loadAllMDXFrontMatter, preloadFrontmatter, ALL_ASYNCAPI, isFrontmatterReady, getNavigationForPath } from '../components/store';
 import docsConfig from '../../docs/dory.json' with { type: 'json' };
 import type { DoryConfig } from '../types/config';
 import { usePathname } from '../components/hooks';
@@ -9,33 +9,42 @@ import { OpenAPI } from '../mdx/open-api';
 import { AsyncAPI } from '../mdx/async-api';
 import { Header } from './header';
 import { PrevNextLinks } from './prev-next-link';
-import { TableOfContents } from './table-of-content';
 import { PageMeta } from './page-meta';
+import { Breadcrumb } from './breadcrumb';
+import { PageActions } from './page-actions';
+import { PageFeedback } from './page-feedback';
+import { PageFooter } from './page-footer';
+import { TableOfContents } from './table-of-content';
+import { DocsPageFrame } from './docs-page-frame';
 import { Loading } from '../components/loading';
-import Dropdown from '../components/dropdown';
-import { useNotification } from '../components/notification';
-import { SparkleIcon } from 'lucide-react';
 import { useIsEmbedded } from '../components/hooks';
 import { ErrorBoundary } from '../components/error-boundary';
-import { cn } from '@clidey/ux';
-import { withBase } from '../utils/base-path';
+import { contentScope } from '../utils/content-scope';
 
 const config = docsConfig as DoryConfig;
 
+function embedParentOrigin(): string | null {
+  try {
+    const value = new URLSearchParams(window.location.search).get('parentOrigin');
+    if (!value) return null;
+    const origin = new URL(value);
+    if (origin.origin !== value || !['http:', 'https:'].includes(origin.protocol)) return null;
+    return origin.origin === window.location.origin || config.embed?.security?.allowedOrigins?.includes(origin.origin)
+      ? origin.origin : null;
+  } catch { return null; }
+}
+
 interface LayoutProps {
   children: ComponentChildren;
 }
 
-const prompt = (pathname: string) => `Please read and analyze the content from this documentation page: ${window.location.origin}${withBase(pathname)}.mdx\n\n` +
-  `Then, help me understand and answer any questions I have about it. ` +
-  `Please provide clear, detailed explanations and examples where relevant.`;
-
 /**
- * Main documentation layout: header, sidebar navigation, article content,
- * table of contents, and prev/next links.
+ * Main documentation layout: header, sidebar navigation, breadcrumb and page
+ * actions, article content, feedback, prev/next cards, footer, and the
+ * "On this page" rail.
  *
  * SYNC NOTE: src/entry-server.tsx renders a static SSR copy of this layout's
- * shell (the #container / sidebar nav / main / article wrappers in render()).
+ * shell (the .dory-shell / aside / main / article wrappers in render()).
  * If you change that markup structure here, update entry-server.tsx to match
  * or hydration will mismatch.
  */
@@ -43,8 +52,22 @@ export default function Layout({ children }: LayoutProps) {
   const [loading, setLoading] = useState(!isFrontmatterReady());
   const rawPathname = usePathname();
   const pathname = rawPathname === '/' ? ALL_NAVIGATION[0]?.groups[0]?.pages[0]?.href ?? '/' : rawPathname;
-  const { showNotification } = useNotification();
   const isEmbedded = useIsEmbedded();
+  const parentOrigin = useRef<string | null>(typeof window === 'undefined' ? null : embedParentOrigin());
+  const embeddedReady = useRef(false);
+  const lastEmbeddedPath = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!isEmbedded || loading || !parentOrigin.current || window.parent === window) return;
+    if (!embeddedReady.current) {
+      window.parent.postMessage({ source: 'dory', type: 'dory:ready' }, parentOrigin.current);
+      embeddedReady.current = true;
+    }
+    if (lastEmbeddedPath.current !== pathname) {
+      window.parent.postMessage({ source: 'dory', type: 'dory:navigate', path: pathname }, parentOrigin.current);
+      lastEmbeddedPath.current = pathname;
+    }
+  }, [isEmbedded, loading, pathname]);
 
   // Client-side navigation keeps the previous scroll position, so start each new
   // page at the top. The initial load keeps the browser's own position, and a
@@ -60,49 +83,6 @@ export default function Layout({ children }: LayoutProps) {
     }
   }, [pathname]);
 
-  const handleOpenMDX = useCallback(() => {
-    window.open(`${window.location.origin}${withBase(pathname)}.mdx`, '_blank');
-  }, [pathname]);
-
-  const handleCopyMDX = useCallback(async () => {
-    try {
-      const response = await fetch(`${withBase(pathname)}.mdx`);
-      if (!response.ok) throw new Error(`HTTP ${response.status}`);
-      await navigator.clipboard.writeText(await response.text());
-      showNotification('Copied to clipboard');
-    } catch (error) {
-      console.warn(`Failed to fetch ${pathname}.mdx:`, error);
-      showNotification('Could not copy MDX', 'The raw MDX file is not available.');
-    }
-  }, [pathname, showNotification]);
-  const handleOpenChatGPT = useCallback(() => {
-    const url = `https://chat.openai.com/?q=${encodeURIComponent(prompt(pathname))}`;
-    window.open(url, '_blank');
-  }, [pathname]);
-  const handleOpenAnthropic = useCallback(() => {
-    const url = `https://claude.ai/new?q=${encodeURIComponent(prompt(pathname))}`;
-    window.open(url, '_blank');
-  }, [pathname]);
-
-  const dropdownItems = useMemo(() => [
-    {
-      label: 'Open MDX',
-      onClick: handleOpenMDX,
-    },
-    {
-      label: 'Copy MDX',
-      onClick: handleCopyMDX
-    },
-    {
-      label: 'Open in ChatGPT',
-      onClick: handleOpenChatGPT
-    },
-    {
-      label: 'Open in Anthropic',
-      onClick: handleOpenAnthropic
-    }
-  ], [handleOpenMDX, handleCopyMDX, handleOpenChatGPT, handleOpenAnthropic]);
-
   useEffect(() => {
     // Try to preload frontmatter first (optimized approach).
     // If inline data was available from SSR, preloadFrontmatter() resolves immediately.
@@ -124,14 +104,12 @@ export default function Layout({ children }: LayoutProps) {
 
 
   const { title: group, group: title, page } = useMemo(() => {
-    const group = ALL_NAVIGATION.flatMap((tab) =>
-      tab.groups.find((group) =>
-        group.pages.some((page) => page.href === pathname)
-      )
-    );
+    const group = getNavigationForPath(pathname)
+      .flatMap((tab) => tab.groups)
+      .find((group) => group.pages.some((page) => page.href === pathname));
     const page = completeFrontMatter.find((page) => page.path === pathname);
 
-    return { group: group[0]?.title, title: page?.title, page };
+    return { group: group?.title, title: page?.title, page };
   }, [pathname, loading]);
 
   // Update document title and meta tags when page changes
@@ -194,7 +172,7 @@ export default function Layout({ children }: LayoutProps) {
   }, [page]);
 
   const isLandingPage = useMemo(() => {
-    const firstTab = ALL_NAVIGATION[0];
+    const firstTab = getNavigationForPath(pathname)[0];
     if (!firstTab) return false;
     return (
       firstTab.groups.length === 1 &&
@@ -211,8 +189,9 @@ export default function Layout({ children }: LayoutProps) {
     if (tab == null || tab.openapi == null) {
       return null;
     }
-    const firstDirectory = `/${tab.path.split('/')[1]}`;
-    return ALL_OPENAPI[`${firstDirectory}/openapi.json`].default;
+    const scope = contentScope(config, tab.path);
+    const firstDirectory = `/${scope.page.split('/')[1]}`;
+    return (ALL_OPENAPI[`${scope.prefix}${firstDirectory}/openapi.json`] ?? ALL_OPENAPI[`${firstDirectory}/openapi.json`])?.default ?? null;
   }, [tab, loading]);
 
   const { method, path } = useMemo(() => {
@@ -226,8 +205,9 @@ export default function Layout({ children }: LayoutProps) {
     if (tab == null || tab.asyncapi == null) {
       return null;
     }
-    const firstDirectory = `/${tab.path.split('/')[1]}`;
-    return ALL_ASYNCAPI[`${firstDirectory}/asyncapi.json`].default;
+    const scope = contentScope(config, tab.path);
+    const firstDirectory = `/${scope.page.split('/')[1]}`;
+    return (ALL_ASYNCAPI[`${scope.prefix}${firstDirectory}/asyncapi.json`] ?? ALL_ASYNCAPI[`${firstDirectory}/asyncapi.json`])?.default ?? null;
   }, [tab, loading]);
   
   const { operation, channel } = useMemo(() => {
@@ -239,95 +219,61 @@ export default function Layout({ children }: LayoutProps) {
 
   if (loading) return <div className="h-[25vh] flex grow"><Loading /></div>;
 
-  if (isLandingPage) {
+  const errorFallback = (error: Error) => (
+    <div className="flex flex-col items-center justify-center py-16 px-6 text-center">
+      <p className="text-lg font-semibold text-red-700 dark:text-red-300 mb-2">
+        This page failed to render
+      </p>
+      <pre className="text-sm text-red-600 dark:text-red-400 bg-red-50 dark:bg-red-900/30 border border-red-200 dark:border-red-800 rounded-md p-3 max-w-md overflow-auto">
+        {error.message}
+      </pre>
+    </div>
+  );
+
+  const content = openAPIJSON && tab && "openapi" in tab && method && path
+    ? <OpenAPI openAPIJson={JSON.parse(openAPIJSON)} method={method} path={path} />
+    : asyncAPIJSON && tab && "asyncapi" in tab && operation && channel
+      ? <AsyncAPI asyncAPIJson={JSON.parse(asyncAPIJSON)} operation={operation} channel={channel} />
+      : children;
+
+  const scope = contentScope(config, pathname);
+  const isScopeRoot = Boolean(scope.prefix) && pathname === scope.prefix;
+  const isNotFound = !ALL_PAGES[pathname] && !isScopeRoot;
+  const showSidebar = !isEmbedded && !isLandingPage;
+  // OpenAPI pages lay out their own two columns, so they skip the TOC and take its width.
+  const isOpenAPIPage = openAPIJSON != null;
+
+  if (isNotFound) {
     return (
-      <div className="flex w-full flex-col">
-        <Header />
-        <main className="w-full">
-          <ErrorBoundary fallback={(error) => (
-            <div className="flex flex-col items-center justify-center py-16 px-6 text-center">
-              <p className="text-lg font-semibold text-red-700 dark:text-red-300 mb-2">
-                This page failed to render
-              </p>
-              <pre className="text-sm text-red-600 dark:text-red-400 bg-red-50 dark:bg-red-900/30 border border-red-200 dark:border-red-800 rounded-md p-3 max-w-md overflow-auto">
-                {error.message}
-              </pre>
-            </div>
-          )}>
-            {children}
-          </ErrorBoundary>
-        </main>
-      </div>
+      <main className="dory-main flex min-h-dvh w-full items-center justify-center bg-background px-6 py-12 text-foreground">
+        <div className="w-full">
+          <ErrorBoundary fallback={errorFallback}>{children}</ErrorBoundary>
+        </div>
+      </main>
     );
   }
 
   return (
-    <div className="flex w-full flex-col">
+    isLandingPage ? <div className="dory-shell flex min-h-screen w-full flex-col bg-[var(--sidebar)]">
       <Header />
-      <div id="container" className={cn("relative flex w-full", {
-        "max-w-8xl sm:px-2 lg:px-8": !isEmbedded,
-        "px-0": isEmbedded,
-      })}>
-        <div className={cn("hidden lg:relative lg:block lg:flex-none", {
-          "lg:hidden": isEmbedded,
-        })}>
-          <div className="sticky top-[4.75rem] -ml-0.5 h-[calc(100vh-4.75rem)] w-64 overflow-x-hidden overflow-y-auto py-16 pr-8 pl-0.5 xl:w-72 xl:pr-16">
-            <Navigation />
-          </div>
-        </div>
-        <main className={cn("flex grow max-w-full", {
-          "px-4 py-16 sm:px-6 lg:px-8": !isEmbedded,
-          "p-8": isEmbedded,
-        })}>
-          <div className="min-w-0 w-full">
-            <article className="h-full flex flex-1 flex-col">
-              <div className="flex justify-between items-start">
-                <header className="mb-8">
-                  {title && (
-                    <p className="dory-subtitle text-sm font-medium tracking-widest uppercase mb-2">
-                      {title}
-                    </p>
-                  )}
-                  {group && (
-                    <h1 className="dory-page-title text-4xl tracking-tight">
-                      {group}
-                    </h1>
-                  )}
-                  {page?.lead && <p className="dory-lead">{page.lead}</p>}
-                </header>
-                {
-                  openAPIJSON == null && asyncAPIJSON == null &&
-                  <Dropdown className="gap-0" buttonLabel={<SparkleIcon className="w-4 h-4" />} items={dropdownItems} />
-                }
-              </div>
-              <PageMeta meta={page?.meta} />
-              <div className="flex-1 min-h-[calc(100vh-2rem)]">
-                <ErrorBoundary fallback={(error) => (
-                  <div className="flex flex-col items-center justify-center py-16 px-6 text-center">
-                    <p className="text-lg font-semibold text-red-700 dark:text-red-300 mb-2">
-                      This page failed to render
-                    </p>
-                    <pre className="text-sm text-red-600 dark:text-red-400 bg-red-50 dark:bg-red-900/30 border border-red-200 dark:border-red-800 rounded-md p-3 max-w-md overflow-auto">
-                      {error.message}
-                    </pre>
-                  </div>
-                )}>
-                  {openAPIJSON && tab && "openapi" in tab && method && path ?
-                    <OpenAPI openAPIJson={JSON.parse(openAPIJSON)} method={method} path={path} />
-                   : asyncAPIJSON && tab && "asyncapi" in tab && operation && channel ?
-                    <AsyncAPI asyncAPIJson={JSON.parse(asyncAPIJSON)} operation={operation} channel={channel} />
-                   : children}
-                </ErrorBoundary>
-              </div>
-              <PrevNextLinks />
-            </article>
-          </div>
-          {
-            openAPIJSON == null && asyncAPIJSON == null && !isEmbedded &&
-            <TableOfContents />
-          }
+      <div className="flex flex-1">
+        <main className="dory-main min-w-0 flex-1 bg-background px-6 py-10 text-foreground sm:px-10">
+          <ErrorBoundary fallback={errorFallback}>{children}</ErrorBoundary>
         </main>
       </div>
-    </div>
+    </div> : <DocsPageFrame
+      header={<Header />}
+      sidebar={showSidebar ? <Navigation /> : undefined}
+      breadcrumb={<Breadcrumb group={title} title={group} />}
+      actions={<PageActions pathname={pathname} />}
+      title={group}
+      lead={page?.lead}
+      meta={<PageMeta meta={page?.meta} />}
+      content={<ErrorBoundary fallback={errorFallback}>{content}</ErrorBoundary>}
+      afterContent={<><PageFeedback pathname={pathname} /><PrevNextLinks /><PageFooter /></>}
+      toc={!isOpenAPIPage && <TableOfContents />}
+      embedded={isEmbedded}
+      wide={isOpenAPIPage}
+    />
   );
-}
+}

package/src/ui/mobile-navigation.tsx

@@ -1,11 +1,10 @@
 'use client'
 
-import { Sheet, SheetContent, Button, ModeToggle } from '@clidey/ux'
-import { createContext, Suspense, useCallback, useContext, useRef, useState } from 'react'
+import { CatalogIcon, Sheet, SheetContent, Button, ModeToggle } from '@clidey/ux'
+import { createContext, Suspense, useCallback, useContext, useEffect, useRef, useState } from 'react'
 
-import { Bars3Icon, XMarkIcon } from '@heroicons/react/24/outline'
 import { Navigation } from '../components/navigation'
-import { useIsEmbedded } from '../components/hooks'
+import { useIsEmbedded, usePathname } from '../components/hooks'
 
 const IsInsideMobileNavigationContext = createContext(false)
 
@@ -34,8 +33,11 @@ export function useMobileNavigation() {
 export function MobileNavigation() {
   const isInsideMobileNavigation = useIsInsideMobileNavigation();
   const { isOpen, open, close } = useMobileNavigation();
-  const ToggleIcon = isOpen ? XMarkIcon : Bars3Icon;
   const isEmbedded = useIsEmbedded();
+  const pathname = usePathname();
+
+  // Picking a page navigates client-side, so close the menu once the route changes.
+  useEffect(() => close(), [pathname, close]);
 
   return (
     <IsInsideMobileNavigationContext.Provider value={true}>
@@ -47,15 +49,15 @@ export function MobileNavigation() {
         <Button
           variant="outline"
           size="icon"
-          className="relative flex size-6 lg:hidden p-4"
+          className="relative flex size-6 border-white/15 bg-white/5 text-white hover:bg-white/10 lg:hidden p-4"
           aria-label="Toggle navigation"
           onClick={open}
         >
-          <ToggleIcon className="w-8 stroke-zinc-900 dark:stroke-white" />
+          <CatalogIcon name={isOpen ? 'close' : 'menu'} className="w-8 stroke-white" />
         </Button>
         {!isInsideMobileNavigation && (
           <Suspense fallback={null}>
-            <SheetContent side="left" className="w-full sm:max-w-sm p-8 overflow-y-auto flex flex-col justify-between">
+            <SheetContent side="left" className="w-full sm:max-w-sm overflow-y-auto border-white/10 bg-[var(--sidebar)] p-4 pt-12 text-white">
               <Navigation />
               {
                 isEmbedded &&

package/src/ui/page-actions.tsx

@@ -0,0 +1,67 @@
+import { useCallback } from 'preact/hooks'
+
+import { CatalogIcon, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@clidey/ux'
+import { useNotification } from '../components/notification'
+import { withBase } from '../utils/base-path'
+
+const prompt = (pathname: string) => `Please read and analyze the content from this documentation page: ${window.location.origin}${withBase(pathname)}.mdx\n\n` +
+  `Then, help me understand and answer any questions I have about it. ` +
+  `Please provide clear, detailed explanations and examples where relevant.`
+
+/** The page action controls shared by built sites and sandboxed docs. */
+export function PageActionsView({ onCopy, onOpenMDX, onOpenChatGPT, onOpenClaude }: {
+  onCopy: () => void;
+  onOpenMDX?: () => void;
+  onOpenChatGPT: () => void;
+  onOpenClaude: () => void;
+}) {
+  const items = [
+    ...(onOpenMDX ? [{ label: 'Open MDX', action: onOpenMDX }] : []),
+    { label: 'Open in ChatGPT', action: onOpenChatGPT },
+    { label: 'Open in Claude', action: onOpenClaude },
+  ]
+  return (
+    <div className="dory-page-actions">
+      <button type="button" onClick={onCopy}>
+        <CatalogIcon name="copy" aria-hidden="true" className="h-3.5 w-3.5" />
+        Copy page
+      </button>
+      <DropdownMenu>
+        <DropdownMenuTrigger className="dory-page-actions-ai">
+          <CatalogIcon name="ai" aria-hidden="true" className="h-3.5 w-3.5 text-[var(--primary)]" />
+          AI actions
+          <CatalogIcon name="chevron-down" aria-hidden="true" className="h-3.5 w-3.5" />
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          {items.map((item) => (
+            <DropdownMenuItem key={item.label} className="cursor-pointer" onClick={item.action}>
+              {item.label}
+            </DropdownMenuItem>
+          ))}
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  )
+}
+
+/** "Copy page" and "AI actions" connected to a built Dory site's raw MDX URLs. */
+export function PageActions({ pathname }: { pathname: string }) {
+  const { showNotification } = useNotification()
+  const handleCopyMDX = useCallback(async () => {
+    try {
+      const response = await fetch(`${withBase(pathname)}.mdx`)
+      if (!response.ok) throw new Error(`HTTP ${response.status}`)
+      await navigator.clipboard.writeText(await response.text())
+      showNotification('Copied to clipboard')
+    } catch (error) {
+      console.warn(`Failed to fetch ${pathname}.mdx:`, error)
+      showNotification('Could not copy MDX', 'The raw MDX file is not available.')
+    }
+  }, [pathname, showNotification])
+  return <PageActionsView
+    onCopy={handleCopyMDX}
+    onOpenMDX={() => window.open(`${window.location.origin}${withBase(pathname)}.mdx`, '_blank')}
+    onOpenChatGPT={() => window.open(`https://chat.openai.com/?q=${encodeURIComponent(prompt(pathname))}`, '_blank')}
+    onOpenClaude={() => window.open(`https://claude.ai/new?q=${encodeURIComponent(prompt(pathname))}`, '_blank')}
+  />
+}

package/src/ui/page-feedback.tsx

@@ -0,0 +1,50 @@
+import { useEffect, useState } from 'preact/hooks'
+import { captureDocsEvent } from '../utils/analytics'
+
+/**
+ * "Was this page helpful?" prompt and a small page engagement signal.
+ */
+export function PageFeedbackView({ pathname, onAnswer }: { pathname: string; onAnswer: (helpful: boolean) => void }) {
+  const [answered, setAnswered] = useState(false)
+
+  useEffect(() => setAnswered(false), [pathname])
+
+  const answer = (helpful: boolean) => {
+    onAnswer(helpful)
+    setAnswered(true)
+  }
+
+  return (
+    <div className="dory-feedback mt-16 flex items-center justify-between border-y border-[var(--border)] py-4">
+      {answered ? (
+        <p className="text-sm text-muted-foreground" role="status">Thanks for the feedback.</p>
+      ) : (
+        <>
+          <p className="text-sm font-medium text-foreground">Was this page helpful?</p>
+          <div className="flex gap-2">
+            <button type="button" onClick={() => answer(true)}>Yes</button>
+            <button type="button" onClick={() => answer(false)}>No</button>
+          </div>
+        </>
+      )}
+    </div>
+  )
+}
+
+export function PageFeedback({ pathname }: { pathname: string }) {
+
+  useEffect(() => {
+    let visibleSeconds = 0
+    const timer = window.setInterval(() => {
+      if (document.visibilityState !== 'visible') return
+      visibleSeconds += 1
+      if (visibleSeconds === 15) {
+        captureDocsEvent('docs_page_engaged', { path: pathname, active_seconds: 15 })
+        window.clearInterval(timer)
+      }
+    }, 1000)
+    return () => window.clearInterval(timer)
+  }, [pathname])
+
+  return <PageFeedbackView pathname={pathname} onAnswer={helpful => captureDocsEvent('docs_page_feedback', { path: pathname, helpful })} />
+}

package/src/ui/page-footer.tsx

@@ -0,0 +1,23 @@
+import docsConfig from '../../docs/dory.json' with { type: 'json' }
+import type { DoryConfig } from '../types/config'
+import { DORY_REPO_URL, DoryMark } from './dory-mark'
+
+const config = docsConfig as DoryConfig
+
+/** Article footer: "Powered by Dory" and the copyright line. */
+export function PageFooterView({ copyright, name }: { copyright?: string; name: string }) {
+  return (
+    <footer className="dory-page-footer mt-12 flex items-center justify-between pb-4">
+      <a href={DORY_REPO_URL} target="_blank" rel="noopener noreferrer" className="flex items-center gap-2">
+        <DoryMark className="h-3.5 w-3.5" />
+        Powered by Dory
+      </a>
+      <span>© {new Date().getFullYear()} {copyright ?? name}</span>
+    </footer>
+  )
+}
+
+/** Article footer configured for the current built Dory site. */
+export function PageFooter() {
+  return <PageFooterView copyright={config.copyright} name={config.name} />
+}

package/src/ui/prev-next-link.tsx

@@ -1,75 +1,21 @@
-import { ArrowRightIcon } from "@heroicons/react/24/outline";
-import { withBase } from '../utils/base-path';
-import classNames from "classnames";
-import { ALL_NAVIGATION } from "../components/store";
+import { completeFrontMatter, getNavigationForPath, type Navigation } from "../components/store";
 import { usePathname } from "../components/hooks";
+import { PrevNextLinksView, type PageEntry } from './prev-next-view';
 
-function PageLink({
-  title,
-  href,
-  dir = 'next',
-  ...props
-}: Omit<React.ComponentPropsWithoutRef<'div'>, 'dir' | 'title'> & {
-  title: string
-  href: string
-  dir?: 'previous' | 'next'
-}) {
-  return (
-    <div {...props}>
-      <p className="font-display text-xs font-medium text-muted-foreground">
-        {dir === 'next' ? 'Next' : 'Previous'}
-      </p>
-      <div className="mt-1">
-        <a href={withBase(href)} className={classNames('flex items-center gap-x-1 text-sm font-semibold hover:opacity-80', {
-            'flex-row-reverse': dir === 'previous',
-          },
-        )}>
-          <p className={classNames("flex items-center gap-x-1 text-sm font-semibold hover:opacity-80", {
-            "flex-row-reverse": dir === "previous"
-          })}>
-            {title}
-            <ArrowRightIcon
-              className={classNames(
-                'h-4 w-4 flex-none fill-current',
-                {
-                  'rotate-180': dir === 'previous',
-                },
-              )}
-            />
-          </p>
-        </a>
-      </div>
-    </div>
-  )
-}
-export function PrevNextLinks() {
+/**
+ * Previous/next page cards in navigation order. Pass `navigation` when
+ * rendering on the server, where store titles are not yet loaded.
+ */
+export function PrevNextLinks({ navigation }: { navigation?: Navigation[] }) {
   const pathname = usePathname();
-  const allLinks = ALL_NAVIGATION.flatMap(tab => 
-    tab.groups.flatMap(group => 
-      group.pages.map(page => page.href)
+  const pages: PageEntry[] = (navigation ?? getNavigationForPath(pathname)).flatMap(tab =>
+    tab.groups.flatMap(group =>
+      group.pages.map(page => ({
+        title: completeFrontMatter.find(entry => entry.path === page.href)?.title ?? page.title,
+        href: page.href,
+        group: group.title,
+      }))
     )
   );
-  const linkIndex = allLinks.findIndex(link => link === pathname);
-  const previousPage = linkIndex > -1 ? allLinks[linkIndex - 1] : null;
-  const nextPage = linkIndex > -1 ? allLinks[linkIndex + 1] : null;
-
-  const previousPageTitle = previousPage ? ALL_NAVIGATION
-    .flatMap(tab => tab.groups)
-    .flatMap(group => group.pages)
-    .find(page => page.href === previousPage)?.title : null;
-  const nextPageTitle = nextPage ? ALL_NAVIGATION
-    .flatMap(tab => tab.groups)
-    .flatMap(group => group.pages)
-    .find(page => page.href === nextPage)?.title : null;
-
-  if (!nextPage && !previousPage) {
-    return null;
-  }
-
-  return (
-    <div className="mt-12 pt-6 flex border-t border-black/20 dark:border-white/20">
-      {previousPage && <PageLink dir="previous" title={previousPageTitle ?? ''} href={previousPage} />}
-      {nextPage && <PageLink className="ml-auto text-right" title={nextPageTitle ?? ''} href={nextPage} />}
-    </div>
-  )
+  return <PrevNextLinksView pages={pages} pathname={pathname} />;
 }

package/src/ui/prev-next-view.tsx

@@ -0,0 +1,27 @@
+import classNames from 'classnames';
+import { Link } from 'wouter-preact';
+
+export type PageEntry = { title: string; href: string; group: string };
+
+function PageCard({ page, dir, className, onNavigate }: { page: PageEntry; dir: 'previous' | 'next'; className?: string; onNavigate?: (href: string) => void }) {
+  const contents = <>
+    <span className="dory-pager-label">{dir === 'previous' ? `← ${page.group}` : `${page.group} →`}</span>
+    <span className="dory-pager-title">{page.title}</span>
+  </>;
+  const classes = classNames('dory-pager-card', className, { 'text-right': dir === 'next' });
+  return onNavigate
+    ? <a href="#" className={classes} onClick={event => { event.preventDefault(); onNavigate(page.href); }}>{contents}</a>
+    : <Link href={page.href} className={classes}>{contents}</Link>;
+}
+
+/** Navigation cards shared by the built site and the app-owned runtime. */
+export function PrevNextLinksView({ pages, pathname, onNavigate }: { pages: PageEntry[]; pathname: string; onNavigate?: (href: string) => void }) {
+  const index = pages.findIndex(page => page.href === pathname);
+  const previousPage = index > 0 ? pages[index - 1] : null;
+  const nextPage = index > -1 ? pages[index + 1] : null;
+  if (!nextPage && !previousPage) return null;
+  return <div className="mt-6 grid gap-4 sm:grid-cols-2">
+    {previousPage && <PageCard dir="previous" page={previousPage} onNavigate={onNavigate} />}
+    {nextPage && <PageCard dir="next" page={nextPage} onNavigate={onNavigate} className={classNames({ 'sm:col-span-2': !previousPage })} />}
+  </div>;
+}