refactor(console): fetch book/doc once at a /docs layout route

Previously every docs page (index, book landing, reader) called useBookData
independently, so a single page issued the doc+book list fetch from several
components and every in-section navigation re-fetched. Hoist the fetch to a
DocsLayout route that loads once and shares the result via context; the pages
read it with useBookData (now a context consumer). Nesting the /docs child
routes under the layout (top-level + app-scoped) means navigating within the
section issues no further book/doc requests — only the reader's single-doc
content fetch.

Browser-verified: a full /docs → /docs/manual → reader walk now hits
/meta/doc and /meta/book once each (×2 is dev StrictMode only), down from
~8 and ~6 before.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

apps/console/src/App.tsx

@@ -45,6 +45,7 @@ import SharedRecordPage from './pages/SharedRecordPage';
 import DocPage from './pages/DocPage';
 import DocsIndex from './pages/DocsIndex';
 import DocsSlug from './pages/DocsSlug';
+import DocsLayout from './pages/DocsLayout';
 import { LoginPage } from './pages/auth/LoginPage';
 import { RegisterPage } from './pages/auth/RegisterPage';
 import { ForgotPasswordPage } from './pages/auth/ForgotPasswordPage';
@@ -185,25 +186,22 @@ export function App() {
               * lists every installed `doc` (grouped by package), and one
               * viewer route renders any item; cross-references between docs
               * resolve to that same viewer route. Both are app-independent. */}
+            {/* Docs portal (ADR-0046 §6). The layout fetches book + doc once
+              * and shares it with every child route via context. Children:
+              *   index        → book index
+              *   :slug        → a book landing, or a flat-doc permalink that
+              *                  redirects to its canonical /docs/<book>/<name>
+              *   :slug/:name  → in-book reader (doc identity stays single-
+              *                  coordinate; the book segment is derived nav). */}
             <Route path="/docs" element={
               <ProtectedRoute>
-                <DocsIndex />
+                <DocsLayout />
               </ProtectedRoute>
-            } />
-            {/* One portal segment: a book landing (slug) or a flat-doc permalink
-              * that redirects to its canonical /docs/<book>/<name> (ADR-0046 §6). */}
-            <Route path="/docs/:slug" element={
-              <ProtectedRoute>
-                <DocsSlug />
-              </ProtectedRoute>
-            } />
-            {/* In-book reader: <slug> = book, <name> = doc (doc identity stays
-              * single-coordinate; the book segment is derived navigation). */}
-            <Route path="/docs/:slug/:name" element={
-              <ProtectedRoute>
-                <DocPage />
-              </ProtectedRoute>
-            } />
+            }>
+              <Route index element={<DocsIndex />} />
+              <Route path=":slug" element={<DocsSlug />} />
+              <Route path=":slug/:name" element={<DocPage />} />
+            </Route>
             <Route path="/home" element={
               <ProtectedRoute>
                 <HomeRoute />

apps/console/src/AppContent.tsx

@@ -36,6 +36,7 @@ const IntegrationsPage = lazy(() => import('./pages/developer/IntegrationsPage')
 const DocPage = lazy(() => import('./pages/DocPage'));
 const AppDocsIndex = lazy(() => import('./pages/AppDocsIndex'));
 const DocsSlug = lazy(() => import('./pages/DocsSlug'));
+const DocsLayout = lazy(() => import('./pages/DocsLayout'));
 
 // Note: marketplace routes (`system/marketplace`, `system/marketplace/:packageId`)
 // are registered by DefaultAppContent in @object-ui/app-shell so they're
@@ -92,11 +93,14 @@ const systemRoutes = (
     <Route path="developer/integrations" element={<Suspense fallback={<LoadingScreen />}><IntegrationsPage /></Suspense>} />
     {/* ADR-0048 — package docs under the package container: app-scoped index
         (/apps/:packageId/docs) + single-doc viewer (/apps/:packageId/docs/:name) */}
-    <Route path="docs" element={<Suspense fallback={<LoadingScreen />}><AppDocsIndex /></Suspense>} />
-    {/* ADR-0046 §6 — one segment resolves to a book landing or redirects a flat
-        doc to its canonical /docs/<book>/<name>; then the in-book reader. */}
-    <Route path="docs/:slug" element={<Suspense fallback={<LoadingScreen />}><DocsSlug /></Suspense>} />
-    <Route path="docs/:slug/:name" element={<Suspense fallback={<LoadingScreen />}><DocPage /></Suspense>} />
+    {/* ADR-0046 §6 — the docs layout fetches book + doc once and shares it with
+        the app-scoped index, book landings, and reader (one segment resolves to
+        a book landing or redirects a flat doc to /docs/<book>/<name>). */}
+    <Route path="docs" element={<Suspense fallback={<LoadingScreen />}><DocsLayout /></Suspense>}>
+      <Route index element={<Suspense fallback={<LoadingScreen />}><AppDocsIndex /></Suspense>} />
+      <Route path=":slug" element={<Suspense fallback={<LoadingScreen />}><DocsSlug /></Suspense>} />
+      <Route path=":slug/:name" element={<Suspense fallback={<LoadingScreen />}><DocPage /></Suspense>} />
+    </Route>
     {/* Legacy URL redirects → metadata-admin engine (zero-cost compatibility). */}
     <Route path="system/objects" element={<ObjectRedirect />} />
     <Route path="system/objects/:objectName" element={<ObjectRedirect />} />

apps/console/src/pages/DocsLayout.tsx

@@ -0,0 +1,25 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { Outlet } from 'react-router-dom';
+import { BookDataContext, useBookDataFetch } from './use-book-data';
+
+/**
+ * Layout route for the docs portal (`/docs/*`). Fetches the book + doc
+ * metadata ONCE and shares it with every child route (index, book landing,
+ * reader) via context, so navigating within the section doesn't re-fetch and a
+ * single page never issues the same request from several components.
+ */
+export default function DocsLayout() {
+  const data = useBookDataFetch();
+  return (
+    <BookDataContext.Provider value={data}>
+      <Outlet />
+    </BookDataContext.Provider>
+  );
+}

apps/console/src/pages/docs-portal.test.tsx

@@ -61,17 +61,21 @@ vi.mock('@object-ui/i18n', () => ({
 }));
 
 // Imported AFTER the mocks so the pages pick up the mocked modules.
+import DocsLayout from './DocsLayout';
 import DocsIndex from './DocsIndex';
 import DocsSlug from './DocsSlug';
 import DocPage from './DocPage';
 
+// Mirrors the real route table: the layout fetches once and shares the data.
 function Harness({ entry }: { entry: string }) {
   return (
     <MemoryRouter initialEntries={[entry]}>
       <Routes>
-        <Route path="/docs" element={<DocsIndex />} />
-        <Route path="/docs/:slug" element={<DocsSlug />} />
-        <Route path="/docs/:slug/:name" element={<DocPage />} />
+        <Route path="/docs" element={<DocsLayout />}>
+          <Route index element={<DocsIndex />} />
+          <Route path=":slug" element={<DocsSlug />} />
+          <Route path=":slug/:name" element={<DocPage />} />
+        </Route>
       </Routes>
     </MemoryRouter>
   );

apps/console/src/pages/use-book-data.ts

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { useEffect, useMemo, useState } from 'react';
+import { createContext, useContext, useEffect, useMemo, useState } from 'react';
 import { useAdapter } from '@object-ui/app-shell';
 import { buildPortalBooks, type Book, type ResolverDoc } from './book-nav';
 
@@ -77,7 +77,12 @@ interface RawState {
   error?: string;
 }
 
-export function useBookData(): BookData {
+/**
+ * Fetch the book + doc metadata once. Used by {@link BookDataProvider} at the
+ * `/docs` layout route so the whole docs section shares a single fetch, rather
+ * than each page (index, book landing, reader) re-fetching independently.
+ */
+function useBookDataFetch(): BookData {
   const adapter = useAdapter();
   const [data, setData] = useState<RawState>({ authoredBooks: [], docs: [], state: 'loading' });
 
@@ -125,3 +130,20 @@ export function useBookData(): BookData {
 
   return { ...data, books };
 }
+
+const LOADING: BookData = { authoredBooks: [], books: [], docs: [], state: 'loading' };
+
+/**
+ * Shared book/doc data, provided once at the `/docs` layout route (see
+ * DocsLayout) and consumed by {@link useBookData}. Exported so the layout's
+ * provider — which lives in a `.tsx` file — can supply it.
+ */
+export const BookDataContext = createContext<BookData | null>(null);
+
+/** The one-time fetcher the layout drives. Internal to the docs section. */
+export { useBookDataFetch };
+
+/** Read the shared book/doc data. Returns a loading state outside the provider. */
+export function useBookData(): BookData {
+  return useContext(BookDataContext) ?? LOADING;
+}