Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat: load the docs page without every page's body (#1120)
Raghav Chamadiya5221679eaec6
diff --git a/packages/api-client/src/hosted.test.ts b/packages/api-client/src/hosted.test.tsindex a43e35472..89da7e7e9 100644--- a/packages/api-client/src/hosted.test.ts+++ b/packages/api-client/src/hosted.test.ts@@ -320,6 +320,34 @@ describe("docs", () => {expect(calls.filter((c) => c.url.includes("/docs"))).toHaveLength(1);});+ it("serves summaries with the heavy fields actually removed", async () => {+ const { p } = provider([+ REPOS_ROUTE,+ [+ "/docs",+ {+ ...DOCS_BODY,+ pages: [+ {+ id: "overview",+ page_type: "overview",+ title: "Overview",+ content: "a body",+ metadata: { layer_order: ["ui"] },+ },+ ],+ },+ ],+ ]);++ const [summary] = await p.listAllPages("repo-1", { fields: "summary" });++ expect(summary).not.toHaveProperty("content");+ expect(summary).not.toHaveProperty("metadata");+ expect(summary!.title).toBe("Overview");+ expect(summary!.content_chars).toBe("a body".length);+ });+it("listPages filters by page_type and slices", async () => {const { p } = provider([REPOS_ROUTE, ["/docs", DOCS_BODY]]);const filtered = await p.listPages("repo-1", { page_type: "file_page" });diff --git a/packages/api-client/src/hosted.ts b/packages/api-client/src/hosted.tsindex 2cab92265..fd62e5366 100644--- a/packages/api-client/src/hosted.ts+++ b/packages/api-client/src/hosted.ts@@ -48,9 +48,11 @@ import type {ModuleHealthSummary,Paginated,PageResponse,+ PageSummary,RepoResponse,SearchResultResponse,} from "./types";+import type { PageFields } from "./pages";// ---------------------------------------------------------------------------// Config + hosted-only response types@@ -249,12 +251,14 @@ export function mapHostedPage(raw: Record<string, unknown>, repoId: string): Pagconst str = (k: string): string => (typeof raw[k] === "string" ? (raw[k] as string) : "");const num = (k: string, fallback = 0): number =>typeof raw[k] === "number" ? (raw[k] as number) : fallback;+ const content = str("content");return {id: str("id") || str("page_id"),repository_id: repoId,page_type: str("page_type"),title: str("title"),- content: str("content"),+ content,+ content_chars: content.length,target_path: str("target_path"),source_hash: str("source_hash"),model_name: str("model_name"),@@ -273,6 +277,12 @@ export function mapHostedPage(raw: Record<string, unknown>, repoId: string): Pag};}+/** Drop a page's two heavy fields, keeping the rest byte-identical. */+export function toPageSummary(page: PageResponse): PageSummary {+ const { content: _content, metadata: _metadata, ...summary } = page;+ return summary;+}+/** A dead_code.json finding into the local finding shape (artifact rows lack* the local-DB triage fields, which default to an open, note-less finding). */export function mapHostedDeadCodeFinding(raw: Record<string, unknown>): DeadCodeFindingResponse {@@ -383,7 +393,14 @@ export interface HostedProvider {repoId: string,opts?: { page_type?: string; limit?: number; offset?: number },): Promise<PageResponse[]>;- listAllPages(repoId: string, opts?: { page_type?: string }): Promise<PageResponse[]>;+ listAllPages(+ repoId: string,+ opts: { page_type?: string; fields: "summary" },+ ): Promise<PageSummary[]>;+ listAllPages(+ repoId: string,+ opts?: { page_type?: string; fields?: "full" },+ ): Promise<PageResponse[]>;getPageById(pageId: string, repoId?: string): Promise<PageResponse>;// Decisions / risk / dead code@@ -552,6 +569,32 @@ export function createHostedProvider(config: HostedProviderConfig): HostedProvidreturn mapped;}+ // Declared out here (rather than inline in the returned object) so it can+ // carry the same overloads the interface does — an object-literal method+ // can't.+ async function listAllPages(+ repoId: string,+ opts: { page_type?: string; fields: "summary" },+ ): Promise<PageSummary[]>;+ async function listAllPages(+ repoId: string,+ opts?: { page_type?: string; fields?: "full" },+ ): Promise<PageResponse[]>;+ async function listAllPages(+ repoId: string,+ opts?: { page_type?: string; fields?: PageFields },+ ): Promise<PageSummary[]> {+ const pages = await loadPages(repoId);+ const scoped = opts?.page_type+ ? pages.filter((p) => p.page_type === opts.page_type)+ : pages;+ // Hosted serves its whole docs artifact in one cached call, so `summary`+ // saves it no round trip. It still honours the contract: callers get rows+ // with no `content`/`metadata`, so a component typed against the summary+ // shape can't quietly read a body a leaner backend wouldn't have sent.+ return opts?.fields === "summary" ? scoped.map(toPageSummary) : scoped;+ }+return {listRepos,refresh(): void {@@ -741,10 +784,7 @@ export function createHostedProvider(config: HostedProviderConfig): HostedProvid}return pages;},- async listAllPages(repoId, opts): Promise<PageResponse[]> {- const pages = await loadPages(repoId);- return opts?.page_type ? pages.filter((p) => p.page_type === opts.page_type) : pages;- },+ listAllPages,async getPageById(pageId, repoId): Promise<PageResponse> {const pools = repoId? [await loadPages(repoId)]diff --git a/packages/api-client/src/pages.test.ts b/packages/api-client/src/pages.test.tsindex 6d410a013..efb5bcb53 100644--- a/packages/api-client/src/pages.test.ts+++ b/packages/api-client/src/pages.test.ts@@ -1,13 +1,54 @@import { describe, expect, it, vi, beforeEach } from "vitest";const apiPost = vi.fn();+const apiGet = vi.fn();vi.mock("./client", () => ({- apiGet: vi.fn(),+ apiGet: (...args: unknown[]) => apiGet(...args),apiPatch: vi.fn(),apiPost: (...args: unknown[]) => apiPost(...args),}));-import { regeneratePage } from "./pages";+import { listAllPages, regeneratePage } from "./pages";++describe("listAllPages", () => {+ beforeEach(() => {+ apiGet.mockReset();+ });++ it("asks for full rows when no fields option is given", async () => {+ apiGet.mockResolvedValue([]);+ await listAllPages("r1");+ expect(apiGet.mock.calls[0]![1]).toMatchObject({+ repo_id: "r1",+ fields: "full",+ });+ });++ it("passes fields=summary through on every page of the listing", async () => {+ // A full batch means there may be more, so it pages again; the second+ // batch is short and ends the loop.+ const batch = Array.from({ length: 2000 }, (_, i) => ({ id: `p${i}` }));+ apiGet.mockResolvedValueOnce(batch).mockResolvedValueOnce([{ id: "last" }]);++ const all = await listAllPages("r1", { fields: "summary" });++ expect(all).toHaveLength(2001);+ expect(apiGet.mock.calls).toHaveLength(2);+ for (const call of apiGet.mock.calls) {+ expect(call[1]).toMatchObject({ fields: "summary" });+ }+ // Sequential, not fanned out: offsets follow one another.+ expect(apiGet.mock.calls.map((c) => (c[1] as { offset: number }).offset)).toEqual([+ 0, 2000,+ ]);+ });++ it("keeps full listings on the smaller batch, where a row is ~15x heavier", async () => {+ apiGet.mockResolvedValue([]);+ await listAllPages("r1");+ expect(apiGet.mock.calls[0]![1]).toMatchObject({ limit: 500, fields: "full" });+ });+});describe("regeneratePage", () => {beforeEach(() => {diff --git a/packages/api-client/src/pages.ts b/packages/api-client/src/pages.tsindex 2bec236a2..0e58db91e 100644--- a/packages/api-client/src/pages.ts+++ b/packages/api-client/src/pages.ts@@ -1,29 +1,83 @@import { apiGet, apiPatch, apiPost } from "./client";import type {PageResponse,+ PageSummary,PageVersionResponse,JobLaunchResponse,GenerateCascade,} from "./types";+/**+ * How much of each page a listing should carry.+ *+ * `full` is every field and stays the default, so no existing caller changes+ * meaning. `summary` drops `content` and `metadata` — 95% of the bytes on a+ * large wiki, and read by nothing that renders a list — in exchange for a+ * `content_chars` count.+ */+export type PageFields = "full" | "summary";++interface ListPagesOpts {+ page_type?: string;+ sort_by?: string;+ order?: string;+ limit?: number;+ offset?: number;+}+export async function listPages(repoId: string,- opts?: { page_type?: string; sort_by?: string; order?: string; limit?: number; offset?: number },-): Promise<PageResponse[]> {- return apiGet<PageResponse[]>("/api/pages", { repo_id: repoId, ...opts });+ opts: ListPagesOpts & { fields: "summary" },+): Promise<PageSummary[]>;+export async function listPages(+ repoId: string,+ opts?: ListPagesOpts & { fields?: "full" },+): Promise<PageResponse[]>;+export async function listPages(+ repoId: string,+ opts?: ListPagesOpts & { fields?: PageFields },+): Promise<PageSummary[]> {+ return apiGet<PageSummary[]>("/api/pages", { repo_id: repoId, ...opts });+}++interface ListAllPagesOpts {+ page_type?: string;+ sort_by?: string;+ order?: string;}/** Fetch all pages for a repo, auto-paginating through the 500-item backend limit. */export async function listAllPages(repoId: string,- opts?: { page_type?: string; sort_by?: string; order?: string },-): Promise<PageResponse[]> {- const PAGE_SIZE = 500;- const all: PageResponse[] = [];+ opts: ListAllPagesOpts & { fields: "summary" },+): Promise<PageSummary[]>;+export async function listAllPages(+ repoId: string,+ opts?: ListAllPagesOpts & { fields?: "full" },+): Promise<PageResponse[]>;+export async function listAllPages(+ repoId: string,+ opts?: ListAllPagesOpts & { fields?: PageFields },+): Promise<PageSummary[]> {+ // Batch size follows the shape, because the two differ by ~15x per row. 500+ // full rows is ~6 MB; 500 summary rows is ~0.4 MB, so the same number of+ // trips would be spent almost entirely on latency. Both stay under a couple+ // of megabytes per response.+ const fields = opts?.fields ?? "full";+ const PAGE_SIZE = fields === "summary" ? 2000 : 500;+ const all: PageSummary[] = [];let offset = 0;while (true) {- const batch = await listPages(repoId, { ...opts, limit: PAGE_SIZE, offset });+ // Kept sequential on purpose. Several concurrent multi-megabyte listings is+ // the request shape behind a past memory incident; the fix for a slow+ // listing is a smaller payload, not more of it at once.+ const batch = await listPages(repoId, {+ ...opts,+ limit: PAGE_SIZE,+ offset,+ fields,+ } as ListPagesOpts & { fields: "summary" });all.push(...batch);if (batch.length < PAGE_SIZE) break;offset += PAGE_SIZE;@@ -32,9 +86,21 @@ export async function listAllPages(return all;}-/** Get page by its ID using the query-param endpoint (avoids path conflicts) */-export async function getPageById(pageId: string): Promise<PageResponse> {- return apiGet<PageResponse>("/api/pages/lookup", { page_id: pageId });+/**+ * Get page by its ID using the query-param endpoint (avoids path conflicts).+ *+ * Pass `repoId` whenever the caller knows it: a workspace server keeps a+ * separate store per repo and routes on that value, so without it the lookup+ * only ever reaches the default store.+ */+export async function getPageById(+ pageId: string,+ repoId?: string,+): Promise<PageResponse> {+ return apiGet<PageResponse>("/api/pages/lookup", {+ page_id: pageId,+ ...(repoId ? { repo_id: repoId } : {}),+ });}/** Get page versions by ID */diff --git a/packages/api-client/src/types/pages.ts b/packages/api-client/src/types/pages.tsindex 9bcbace60..2c7e68291 100644--- a/packages/api-client/src/types/pages.ts+++ b/packages/api-client/src/types/pages.ts@@ -2,12 +2,16 @@// Pages// ----------------------------------------------------------------------------export interface PageResponse {+/**+ * What `GET /api/pages?fields=summary` returns: every page field except the+ * two heavy ones. On a large wiki `content` and `metadata` are 95% of a full+ * listing's bytes, and nothing that draws a list of pages reads either.+ */+export interface PageSummary {id: string;repository_id: string;page_type: string;title: string;- content: string;target_path: string;source_hash: string;model_name: string;@@ -19,7 +23,15 @@ export interface PageResponse {version: number;confidence: number;freshness_status: string;- metadata: Record<string, unknown>;+ /** Length of the omitted `content`, so a list can rank pages by how much was+ * written without carrying the writing. Optional: a backend predating the+ * field just omits it, and callers fall back rather than ranking on+ * `undefined`. */+ content_chars?: number;+ /** Present only when this row was fetched in full — a caller is free to+ * hydrate a few rows of an otherwise summary listing. */+ content?: string;+ metadata?: Record<string, unknown>;human_notes: string | null;created_at: string;updated_at: string;@@ -32,6 +44,11 @@ export interface PageResponse {structural_key?: string | null;}+export interface PageResponse extends PageSummary {+ content: string;+ metadata: Record<string, unknown>;+}+export interface PageVersionResponse {id: string;page_id: string;diff --git a/packages/server/src/repowise/server/routers/pages.py b/packages/server/src/repowise/server/routers/pages.pyindex cc52e3901..a4884a587 100644--- a/packages/server/src/repowise/server/routers/pages.py+++ b/packages/server/src/repowise/server/routers/pages.py@@ -14,7 +14,11 @@ from sqlalchemy.ext.asyncio import AsyncSessionfrom repowise.core.persistence import crudfrom repowise.core.persistence.models import _now_utcfrom repowise.server.deps import get_db_session, verify_api_key-from repowise.server.schemas import PageResponse, PageVersionResponse+from repowise.server.schemas import (+ PageResponse,+ PageSummaryResponse,+ PageVersionResponse,+)router = APIRouter(prefix="/api/pages",@@ -23,7 +27,7 @@ router = APIRouter()[email protected]("", response_model=list[PageResponse])[email protected]("", response_model=None)async def list_pages(repo_id: str = Query(..., description="Repository ID"),page_type: str | None = Query(None, description="Filter by page type"),@@ -39,9 +43,21 @@ async def list_pages(order: str = Query("desc", description="Sort order: asc or desc"),limit: int = Query(100, ge=1, le=5000),offset: int = Query(0, ge=0),+ fields: str = Query(+ "full",+ description="How much of each page to return. 'full' (the default) is "+ "every field. 'summary' drops 'content' and 'metadata' — together 95% "+ "of a listing's bytes, and read by nothing that renders a list of "+ "pages — and adds 'content_chars' in their place.",+ ),session: AsyncSession = Depends(get_db_session), # noqa: B008-) -> list[PageResponse]:+) -> list[PageResponse] | list[PageSummaryResponse]:"""List wiki pages for a repository."""+ if fields not in ("full", "summary"):+ raise HTTPException(+ status_code=400,+ detail=f"Unknown fields '{fields}'. Valid: full, summary.",+ )pages = await crud.list_pages(session,repo_id,@@ -52,18 +68,33 @@ async def list_pages(sort_by=sort_by,order=order,)+ # response_model is off on this route: the two shapes are serialized by the+ # models themselves, so FastAPI can't coerce a summary back into a full row.+ if fields == "summary":+ return [PageSummaryResponse.from_orm(p) for p in pages]return [PageResponse.from_orm(p) for p in pages]@router.get("/lookup", response_model=PageResponse)async def get_page_by_query(page_id: str = Query(..., description="Page ID (e.g. file_page:src/main.py)"),+ repo_id: str | None = Query(+ None,+ description="Repository the page belongs to. Optional, but required to "+ "reach a page outside the default store in workspace mode, where the "+ "session is routed by this value.",+ ),session: AsyncSession = Depends(get_db_session), # noqa: B008) -> PageResponse:"""Get a single wiki page by ID passed as query parameter.Use this endpoint when the page_id contains characters that aredifficult to encode in a URL path.++ ``repo_id`` is what routes the session to the right database. Without it a+ workspace server looks the page up in whichever store is the default, and a+ page id that exists in another repo comes back as a 404 — so any caller+ that knows the repo should say so."""page = await crud.get_page(session, page_id)if page is None:diff --git a/packages/server/src/repowise/server/schemas/__init__.py b/packages/server/src/repowise/server/schemas/__init__.pyindex 84918b552..050b30b5a 100644--- a/packages/server/src/repowise/server/schemas/__init__.py+++ b/packages/server/src/repowise/server/schemas/__init__.py@@ -152,6 +152,7 @@ from .ownership import (from .pages import (JobResponse,PageResponse,+ PageSummaryResponse,PageVersionResponse,)from .pagination import Paginated@@ -314,6 +315,7 @@ __all__ = ["OwnerProfileResponse","OwnershipEntry","PageResponse",+ "PageSummaryResponse","PageVersionResponse","Paginated","RepoCreate",diff --git a/packages/server/src/repowise/server/schemas/pages.py b/packages/server/src/repowise/server/schemas/pages.pyindex b7c1cc0f6..65ea79260 100644--- a/packages/server/src/repowise/server/schemas/pages.py+++ b/packages/server/src/repowise/server/schemas/pages.py@@ -8,12 +8,55 @@ from datetime import datetimefrom pydantic import BaseModel-class PageResponse(BaseModel):+def _summary_fields(obj: object) -> dict:+ """The part of a page row that costs nothing to send.++ Shared by both response models so a field added to one can never go+ missing from the other.+ """+ return dict(+ id=obj.id, # type: ignore[attr-defined]+ repository_id=obj.repository_id, # type: ignore[attr-defined]+ page_type=obj.page_type, # type: ignore[attr-defined]+ title=obj.title, # type: ignore[attr-defined]+ target_path=obj.target_path, # type: ignore[attr-defined]+ source_hash=obj.source_hash, # type: ignore[attr-defined]+ model_name=obj.model_name, # type: ignore[attr-defined]+ provider_name=obj.provider_name, # type: ignore[attr-defined]+ input_tokens=obj.input_tokens, # type: ignore[attr-defined]+ output_tokens=obj.output_tokens, # type: ignore[attr-defined]+ cached_tokens=obj.cached_tokens, # type: ignore[attr-defined]+ generation_level=obj.generation_level, # type: ignore[attr-defined]+ version=obj.version, # type: ignore[attr-defined]+ confidence=obj.confidence, # type: ignore[attr-defined]+ freshness_status=obj.freshness_status, # type: ignore[attr-defined]+ content_chars=len(obj.content or ""), # type: ignore[attr-defined]+ human_notes=obj.human_notes, # type: ignore[attr-defined]+ parent_page_id=obj.parent_page_id, # type: ignore[attr-defined]+ display_order=obj.display_order, # type: ignore[attr-defined]+ section_number=obj.section_number, # type: ignore[attr-defined]+ structural_key=obj.structural_key, # type: ignore[attr-defined]+ created_at=obj.created_at, # type: ignore[attr-defined]+ updated_at=obj.updated_at, # type: ignore[attr-defined]+ )+++class PageSummaryResponse(BaseModel):+ """A page row without its two heavy fields.++ On a 5,485-page wiki a full listing measured 38.6 MB, of which ``content`` and+ ``metadata`` are 95%. Nothing that draws a list of pages — the docs tree,+ breadcrumbs, the command palette — reads either one, so ``GET /api/pages``+ can serve this instead when the caller asks for ``fields=summary``.++ ``content_chars`` stands in for the one thing a list genuinely wanted the+ body for: ranking pages by how much was written.+ """+id: strrepository_id: strpage_type: strtitle: str- content: strtarget_path: strsource_hash: strmodel_name: str@@ -25,7 +68,7 @@ class PageResponse(BaseModel):version: intconfidence: floatfreshness_status: str- metadata: dict+ content_chars: inthuman_notes: str | None = None# Position in the wiki outline. Older rows carry no placement, which reads# as a flat wiki and is what those rows actually describe.@@ -36,34 +79,21 @@ class PageResponse(BaseModel):created_at: datetimeupdated_at: datetime+ @classmethod+ def from_orm(cls, obj: object) -> PageSummaryResponse:+ return cls(**_summary_fields(obj))+++class PageResponse(PageSummaryResponse):+ content: str+ metadata: dict+@classmethoddef from_orm(cls, obj: object) -> PageResponse:- metadata = json.loads(obj.metadata_json) # type: ignore[attr-defined]return cls(- id=obj.id, # type: ignore[attr-defined]- repository_id=obj.repository_id, # type: ignore[attr-defined]- page_type=obj.page_type, # type: ignore[attr-defined]- title=obj.title, # type: ignore[attr-defined]+ **_summary_fields(obj),content=obj.content, # type: ignore[attr-defined]- target_path=obj.target_path, # type: ignore[attr-defined]- source_hash=obj.source_hash, # type: ignore[attr-defined]- model_name=obj.model_name, # type: ignore[attr-defined]- provider_name=obj.provider_name, # type: ignore[attr-defined]- input_tokens=obj.input_tokens, # type: ignore[attr-defined]- output_tokens=obj.output_tokens, # type: ignore[attr-defined]- cached_tokens=obj.cached_tokens, # type: ignore[attr-defined]- generation_level=obj.generation_level, # type: ignore[attr-defined]- version=obj.version, # type: ignore[attr-defined]- confidence=obj.confidence, # type: ignore[attr-defined]- freshness_status=obj.freshness_status, # type: ignore[attr-defined]- metadata=metadata,- human_notes=obj.human_notes, # type: ignore[attr-defined]- parent_page_id=obj.parent_page_id, # type: ignore[attr-defined]- display_order=obj.display_order, # type: ignore[attr-defined]- section_number=obj.section_number, # type: ignore[attr-defined]- structural_key=obj.structural_key, # type: ignore[attr-defined]- created_at=obj.created_at, # type: ignore[attr-defined]- updated_at=obj.updated_at, # type: ignore[attr-defined]+ metadata=json.loads(obj.metadata_json), # type: ignore[attr-defined])diff --git a/packages/types/src/docs.ts b/packages/types/src/docs.tsindex 31433c267..301150816 100644--- a/packages/types/src/docs.ts+++ b/packages/types/src/docs.ts@@ -9,12 +9,19 @@export type FreshnessStatus = "fresh" | "stale" | "outdated" | (string & {});-export interface DocPage {+/**+ * A page without its body or its metadata blob.+ *+ * This is what a *list* of pages should be. On a large wiki the two omitted+ * fields are 95% of a full listing, and nothing that renders a list — the docs+ * tree, breadcrumbs, the command palette, the path index — reads either one.+ * Anything that shows a page's body takes `DocPage` instead and fetches it.+ */+export interface DocPageSummary {id: string;repository_id: string;page_type: string;title: string;- content: string;target_path: string;source_hash: string;model_name: string;@@ -26,7 +33,21 @@ export interface DocPage {version: number;confidence: number;freshness_status: FreshnessStatus;- metadata: Record<string, unknown>;+ /**+ * Length of the omitted `content`, so a list can still rank pages by how+ * much was written without carrying the writing. Optional: a backend older+ * than this field simply doesn't send it, and callers fall back rather than+ * ranking on `undefined`.+ */+ content_chars?: number;+ /**+ * Present only when this row was fetched in full. A list is free to hydrate+ * a few of its rows — the docs page does exactly that for cycle pages, whose+ * label is parsed out of the body — so readers must handle its absence+ * rather than assume a body is there.+ */+ content?: string;+ metadata?: Record<string, unknown>;human_notes: string | null;/*** Position in the wiki outline, computed once at generation time so every@@ -41,6 +62,11 @@ export interface DocPage {updated_at: string;}+export interface DocPage extends DocPageSummary {+ content: string;+ metadata: Record<string, unknown>;+}+export interface DocPageVersion {id: string;page_id: string;diff --git a/packages/ui/__tests__/docs/command-palette.test.tsx b/packages/ui/__tests__/docs/command-palette.test.tsxnew file mode 100644index 000000000..3203e0d4a--- /dev/null+++ b/packages/ui/__tests__/docs/command-palette.test.tsx@@ -0,0 +1,94 @@+import { describe, it, expect, vi, afterEach } from "vitest";+import { render, screen, cleanup, waitFor, fireEvent } from "@testing-library/react";+import { DocsCommandPalette } from "../../src/docs/command-palette.js";+import type { DocPage, DocPageSummary } from "@repowise-dev/types/docs";++afterEach(cleanup);++function summary(overrides: Partial<DocPageSummary> = {}): DocPageSummary {+ return {+ id: "p1",+ repository_id: "r1",+ page_type: "file_page",+ title: "Page",+ target_path: "src/foo.ts",+ source_hash: "h",+ model_name: "m",+ provider_name: "p",+ input_tokens: 0,+ output_tokens: 0,+ cached_tokens: 0,+ generation_level: 0,+ version: 1,+ confidence: 1,+ freshness_status: "fresh",+ human_notes: null,+ created_at: "",+ updated_at: "",+ ...overrides,+ };+}++const PAGES: DocPageSummary[] = [+ summary({ id: "auth", title: "Authentication", target_path: "src/auth.ts" }),+ summary({ id: "db", title: "Database", target_path: "src/db.ts" }),+];++describe("DocsCommandPalette", () => {+ it("matches titles and paths without any page bodies loaded", async () => {+ render(+ <DocsCommandPalette pages={PAGES} open onSelect={() => {}} />,+ );++ fireEvent.change(screen.getByRole("combobox"), { target: { value: "auth" } });++ await waitFor(() =>+ expect(screen.getByText("Authentication")).toBeInTheDocument(),+ );+ expect(screen.queryByText("Database")).not.toBeInTheDocument();+ });++ it("gets body matches from searchFn, with the server's snippet", async () => {+ const searchFn = vi.fn(async () => [+ { page: PAGES[1]!, snippet: "…rotates the connection pool…" },+ ]);+ render(+ <DocsCommandPalette+ pages={PAGES}+ open+ onSelect={() => {}}+ searchFn={searchFn}+ />,+ );++ // "pool" appears in no title and no path — only in a body the list does+ // not carry, so this hit can only come from the server.+ fireEvent.change(screen.getByRole("combobox"), { target: { value: "pool" } });++ await waitFor(() =>+ expect(screen.getByText("…rotates the connection pool…")).toBeInTheDocument(),+ );+ expect(searchFn).toHaveBeenCalledWith("pool");+ });++ it("still matches bodies locally when a row was loaded with one", async () => {+ const hydrated: DocPage = {+ ...summary({ id: "cfg", title: "Config", target_path: "src/cfg.ts" }),+ content: "The retry budget is fixed at three attempts.",+ metadata: {},+ };+ render(+ <DocsCommandPalette+ pages={[...PAGES, hydrated]}+ open+ onSelect={() => {}}+ />,+ );++ fireEvent.change(screen.getByRole("combobox"), {+ target: { value: "retry budget" },+ });++ await waitFor(() => expect(screen.getByText("Config")).toBeInTheDocument());+ });+});diff --git a/packages/ui/__tests__/docs/page-labels.test.ts b/packages/ui/__tests__/docs/page-labels.test.tsnew file mode 100644index 000000000..937af14ae--- /dev/null+++ b/packages/ui/__tests__/docs/page-labels.test.ts@@ -0,0 +1,80 @@+import { describe, it, expect } from "vitest";+import { displayLabel, treeLabel } from "../../src/docs/page-labels.js";+import type { DocPageSummary } from "@repowise-dev/types/docs";++function summary(overrides: Partial<DocPageSummary> = {}): DocPageSummary {+ return {+ id: "p1",+ repository_id: "r1",+ page_type: "file_page",+ title: "Page",+ target_path: "src/foo.ts",+ source_hash: "h",+ model_name: "m",+ provider_name: "p",+ input_tokens: 0,+ output_tokens: 0,+ cached_tokens: 0,+ generation_level: 0,+ version: 1,+ confidence: 1,+ freshness_status: "fresh",+ human_notes: null,+ created_at: "",+ updated_at: "",+ ...overrides,+ };+}++const CYCLE_BODY = [+ "# Circular Dependency: scc-103",+ "",+ "- `packages/core/src/generation/page_generator/core.py`",+ "- `packages/core/src/generation/page_generator/prompts.py`",+].join("\n");++describe("displayLabel", () => {+ it("names a cycle after the directory its members share", () => {+ const page = summary({+ page_type: "scc_page",+ title: "Circular Dependency: scc-103",+ target_path: "scc-103",+ content: CYCLE_BODY,+ });+ expect(displayLabel(page)).toBe("Cycle: generation/page_generator");+ });++ it("keeps the title when the row arrived without its body", () => {+ // A summary listing carries no bodies, so there is nothing to derive from.+ // The title is a worse label, but it is a true one.+ const page = summary({+ page_type: "scc_page",+ title: "Circular Dependency: scc-103",+ target_path: "scc-103",+ });+ expect(displayLabel(page)).toBe("Circular Dependency: scc-103");+ });++ it("names other page types without touching the body at all", () => {+ expect(+ displayLabel(summary({ page_type: "layer_page", title: "Layer: Runtime" })),+ ).toBe("Runtime");+ expect(+ displayLabel(+ summary({+ page_type: "module_page",+ title: "Module: ingestion",+ target_path: "src/ingestion",+ }),+ ),+ ).toBe("ingestion");+ });+});++describe("treeLabel", () => {+ it("names a file relative to the module it hangs off", () => {+ const parent = summary({ page_type: "module_page", target_path: "src/api" });+ const page = summary({ target_path: "src/api/routes/users.ts" });+ expect(treeLabel(page, parent)).toBe("routes/users.ts");+ });+});diff --git a/packages/ui/__tests__/present/load-present-pages.test.ts b/packages/ui/__tests__/present/load-present-pages.test.tsnew file mode 100644index 000000000..42d55e18f--- /dev/null+++ b/packages/ui/__tests__/present/load-present-pages.test.ts@@ -0,0 +1,136 @@+import { describe, it, expect, vi } from "vitest";+import { loadPresentPages } from "../../src/present/load-present-pages.js";+import type { DocPage, DocPageSummary } from "@repowise-dev/types/docs";++function summary(overrides: Partial<DocPageSummary> = {}): DocPageSummary {+ return {+ id: "p1",+ repository_id: "r1",+ page_type: "file_page",+ title: "Page",+ target_path: "src/foo.ts",+ source_hash: "h",+ model_name: "m",+ provider_name: "p",+ input_tokens: 0,+ output_tokens: 0,+ cached_tokens: 0,+ generation_level: 0,+ version: 1,+ confidence: 1,+ freshness_status: "fresh",+ human_notes: null,+ created_at: "",+ updated_at: "",+ ...overrides,+ };+}++function full(overrides: Partial<DocPage> = {}): DocPage {+ return {+ ...summary(overrides),+ content: "body",+ metadata: {},+ ...overrides,+ };+}++/** Fetcher that serves whatever it is given and records what was asked for. */+function fetcher(pool: DocPage[]) {+ const asked: string[] = [];+ const fetchPage = vi.fn(async (id: string) => {+ asked.push(id);+ const hit = pool.find((p) => p.id === id);+ if (!hit) throw new Error(`no page ${id}`);+ return hit;+ });+ return { fetchPage, asked };+}++describe("loadPresentPages", () => {+ it("returns nothing when there is no overview to present", async () => {+ const { fetchPage } = fetcher([]);+ expect(await loadPresentPages([summary()], fetchPage)).toEqual([]);+ expect(fetchPage).not.toHaveBeenCalled();+ });++ it("leaves the bulk of the wiki alone", async () => {+ const pages: DocPageSummary[] = [+ summary({ id: "overview", page_type: "repo_overview", target_path: "repo" }),+ ...Array.from({ length: 500 }, (_, i) =>+ summary({ id: `file-${i}`, target_path: `src/f${i}.ts` }),+ ),+ ];+ const { fetchPage, asked } = fetcher([+ full({ id: "overview", page_type: "repo_overview", target_path: "repo" }),+ ]);++ const loaded = await loadPresentPages(pages, fetchPage);++ expect(asked).toEqual(["overview"]);+ expect(loaded.map((p) => p.id)).toEqual(["overview"]);+ });++ it("takes the richest modules by content_chars, not by whatever came first", async () => {+ const modules = [+ summary({ id: "m-small", page_type: "module_page", content_chars: 10 }),+ summary({ id: "m-big", page_type: "module_page", content_chars: 9000 }),+ summary({ id: "m-mid", page_type: "module_page", content_chars: 500 }),+ ];+ const pages = [+ summary({ id: "overview", page_type: "repo_overview" }),+ ...modules,+ ];+ const pool = [+ full({ id: "overview", page_type: "repo_overview" }),+ ...modules.map((m) => full({ id: m.id, page_type: "module_page" })),+ ];+ const { fetchPage, asked } = fetcher(pool);++ await loadPresentPages(pages, fetchPage);++ // All three fit under the cap, but the order they are taken in is the+ // order the deck shows them.+ expect(asked.slice(1)).toEqual(["m-big", "m-mid", "m-small"]);+ });++ it("follows the overview's guided tour to its landmark pages", async () => {+ const overview = full({+ id: "overview",+ page_type: "repo_overview",+ metadata: {+ guided_tour: [+ { order: 1, target_path: "src/entry.ts" },+ { order: 2, target_path: "src/missing.ts" },+ ],+ },+ });+ const pages = [+ summary({ id: "overview", page_type: "repo_overview" }),+ summary({ id: "entry", target_path: "src/entry.ts" }),+ ];+ const { fetchPage, asked } = fetcher([+ overview,+ full({ id: "entry", target_path: "src/entry.ts" }),+ ]);++ const loaded = await loadPresentPages(pages, fetchPage);++ // The stop with no page behind it is skipped rather than fetched blindly.+ expect(asked).toEqual(["overview", "entry"]);+ expect(loaded.map((p) => p.id)).toEqual(["overview", "entry"]);+ });++ it("does not refetch a row that already carries its body", async () => {+ const pages = [+ full({ id: "overview", page_type: "repo_overview" }),+ full({ id: "arch", page_type: "architecture_diagram" }),+ ];+ const { fetchPage } = fetcher([]);++ const loaded = await loadPresentPages(pages, fetchPage);++ expect(fetchPage).not.toHaveBeenCalled();+ expect(loaded.map((p) => p.id)).toEqual(["overview", "arch"]);+ });+});diff --git a/packages/ui/src/docs/command-palette.tsx b/packages/ui/src/docs/command-palette.tsxindex bdb393a4b..57013796a 100644--- a/packages/ui/src/docs/command-palette.tsx+++ b/packages/ui/src/docs/command-palette.tsx@@ -5,26 +5,35 @@ import { Search, CornerDownLeft } from "lucide-react";import { cn } from "../lib/cn";import { getPageTypeIcon, getPageTypeLabel } from "../lib/page-types";import { useDebounce } from "../hooks/use-debounce";-import type { DocPage } from "@repowise-dev/types/docs";+import type { DocPageSummary } from "@repowise-dev/types/docs";++/** One server-side hit: the loaded page it maps to, plus its context line. */+export interface PaletteSearchHit {+ page: DocPageSummary;+ snippet?: string;+}interface CommandPaletteProps {- pages: DocPage[];- onSelect: (page: DocPage) => void;+ pages: DocPageSummary[];+ onSelect: (page: DocPageSummary) => void;/** Controlled open state. Omit for self-managed (⌘K only). */open?: boolean;onOpenChange?: (open: boolean) => void;/*** Optional server-backed search (semantic / full-text). When provided, its* results are merged in *after* strong local title/path matches, so the- * palette stays instant while also surfacing meaning-based hits that the- * client-side substring filter can't find. Should resolve to `DocPage`s- * (the caller maps the search endpoint's hits back to loaded pages).+ * palette stays instant while also surfacing hits the client-side substring+ * filter can't find. The caller maps the search endpoint's results back to+ * loaded pages and passes the endpoint's snippet through.+ *+ * This is how body matching works when the page list carries no bodies,+ * which is the normal case on a large wiki.*/- searchFn?: (query: string) => Promise<DocPage[]>;+ searchFn?: (query: string) => Promise<PaletteSearchHit[]>;}interface Hit {- page: DocPage;+ page: DocPageSummary;/** Lower is better. */rank: number;/** Short context snippet when the match was in the body. */@@ -33,12 +42,15 @@ interface Hit {// Title hit ranks above path hit ranks above body hit. A leading match// (startsWith) beats a contained match within the same tier.-function score(page: DocPage, q: string): Hit | null {+function score(page: DocPageSummary, q: string): Hit | null {const title = page.title.toLowerCase();const path = (page.target_path || "").toLowerCase();if (title.startsWith(q)) return { page, rank: 0 };if (title.includes(q)) return { page, rank: 1 };if (path.includes(q)) return { page, rank: 2 };+ // Body matching only when this row was loaded with its body. A summary+ // listing has none, and `searchFn` covers the body for those callers.+ if (!page.content) return null;const body = page.content.toLowerCase();const at = body.includes(q) ? body.indexOf(q) : -1;if (at !== -1) {@@ -50,9 +62,12 @@ function score(page: DocPage, q: string): Hit | null {}/**- * ⌘K / Ctrl-K full-text command palette over the already-loaded page list.- * Searches title, path, and body — no extra request, since the page content- * is in the list response. (Semantic search is a separate backend feature.)+ * ⌘K / Ctrl-K command palette over the loaded page list.+ *+ * Title and path are matched here, so typing stays instant. Bodies are matched+ * by `searchFn` against the server: a large wiki's page list is loaded without+ * bodies, because carrying them costs tens of megabytes before anything+ * renders.*/export function DocsCommandPalette({pages,@@ -116,7 +131,7 @@ export function DocsCommandPalette({// Server-backed (semantic / full-text) results, fetched only when a// searchFn is supplied. Failures fall back silently to the client layer.- const [serverPages, setServerPages] = useState<DocPage[]>([]);+ const [serverPages, setServerPages] = useState<PaletteSearchHit[]>([]);useEffect(() => {const q = debounced.trim();if (!searchFn || q.length < 2) {@@ -149,10 +164,10 @@ export function DocsCommandPalette({seen.add(h.page.id);}}- for (const p of serverPages) {- if (!seen.has(p.id)) {- merged.push({ page: p, rank: 3 });- seen.add(p.id);+ for (const { page, snippet } of serverPages) {+ if (!seen.has(page.id)) {+ merged.push({ page, rank: 3, ...(snippet ? { snippet } : {}) });+ seen.add(page.id);}}for (const h of clientHits) {@@ -170,7 +185,7 @@ export function DocsCommandPalette({if (!open) return null;- function choose(page: DocPage) {+ function choose(page: DocPageSummary) {onSelect(page);setOpen(false);}diff --git a/packages/ui/src/docs/doc-nav.ts b/packages/ui/src/docs/doc-nav.tsindex 2c5ec0659..2b4bcc9d4 100644--- a/packages/ui/src/docs/doc-nav.ts+++ b/packages/ui/src/docs/doc-nav.ts@@ -14,7 +14,7 @@// The host app turns the returned ``pageId`` values into hrefs (route shape// differs between the CLI web app and hosted frontend).-import type { DocPage } from "@repowise-dev/types/docs";+import type { DocPageSummary } from "@repowise-dev/types/docs";import { treeLabel } from "./page-labels";export interface DocNavSegment {@@ -48,8 +48,8 @@ function parentDir(path: string): string {}/** Ancestors of ``page``, outermost first, excluding the root and the page. */-function ancestors(page: DocPage, byId: Map<string, DocPage>): DocPage[] {- const chain: DocPage[] = [];+function ancestors(page: DocPageSummary, byId: Map<string, DocPageSummary>): DocPageSummary[] {+ const chain: DocPageSummary[] = [];const seen = new Set<string>([page.id]);let current = byId.get(page.parent_page_id ?? "");while (current && !seen.has(current.id)) {@@ -63,7 +63,7 @@ function ancestors(page: DocPage, byId: Map<string, DocPage>): DocPage[] {}/** The label a page carries in a trail — the same one the docs tree shows. */-function crumbLabel(page: DocPage): string {+function crumbLabel(page: DocPageSummary): string {return treeLabel(page, undefined);}@@ -75,7 +75,7 @@ function crumbLabel(page: DocPage): string {* layer it sits in — rather than through directory names that may have no page* behind them.*/-export function computeDocNav(page: DocPage, pages: DocPage[]): DocNavInfo {+export function computeDocNav(page: DocPageSummary, pages: DocPageSummary[]): DocNavInfo {const byId = new Map(pages.map((p) => [p.id, p]));const chain = page.parent_page_id ? ancestors(page, byId) : [];@@ -123,7 +123,7 @@ export function computeDocNav(page: DocPage, pages: DocPage[]): DocNavInfo {// Index module pages by the directory they represent so an ancestor// directory segment can deep-link to its module overview.- const moduleByPath = new Map<string, DocPage>();+ const moduleByPath = new Map<string, DocPageSummary>();for (const p of pages) {if (p.page_type === "module_page" && p.target_path) {moduleByPath.set(p.target_path, p);@@ -162,8 +162,8 @@ export function computeDocNav(page: DocPage, pages: DocPage[]): DocNavInfo {}function siblingLinks(- siblings: DocPage[],- page: DocPage,+ siblings: DocPageSummary[],+ page: DocPageSummary,): { prev?: DocSiblingLink; next?: DocSiblingLink } {const idx = siblings.findIndex((p) => p.id === page.id);if (idx === -1) return {};diff --git a/packages/ui/src/docs/docs-reader.tsx b/packages/ui/src/docs/docs-reader.tsxindex fdafdfb09..9dc3cdbf3 100644--- a/packages/ui/src/docs/docs-reader.tsx+++ b/packages/ui/src/docs/docs-reader.tsx@@ -6,10 +6,9 @@ import {ArrowRight,ArrowLeft,ChevronRight,- Loader2,Layers,} from "lucide-react";-import type { DocPage } from "@repowise-dev/types/docs";+import type { DocPage, DocPageSummary } from "@repowise-dev/types/docs";import { cn } from "../lib/cn";import { formatRelativeTime, formatTokens } from "../lib/format";import { getPageTypeLabel } from "../lib/page-types";@@ -25,6 +24,7 @@ import {type RelatedReason,} from "../wiki/wiki-links-types";import { Breadcrumb } from "../shared/breadcrumb";+import { Skeleton } from "../ui/skeleton";/** Related entries shown before the "+ N more" line. Five, not eight: the list* is a suggestion of where to go next, and past about five it reads as a dump@@ -66,11 +66,11 @@ export type ReaderLinkComponent = React.ElementType<{interface DocsReaderProps {page: DocPage | null;/** Full page list — powers hierarchical breadcrumbs and prev/next. */- pages?: DocPage[];+ pages?: DocPageSummary[];repoId: string;isLoading?: boolean;/** Select another page in-place (breadcrumb / prev-next / wiki links). */- onSelectPage?: (page: DocPage) => void;+ onSelectPage?: (page: DocPageSummary) => void;/** Navigate by page id (resolved wiki links / backlinks fall through here). */onNavigatePageId?: (pageId: string) => void;persona: ReaderPersona;@@ -124,13 +124,7 @@ export function DocsReader({scrollRef.current?.scrollTo(0, 0);}, [page?.id]);- if (isLoading) {- return (- <div className="flex items-center justify-center h-full">- <Loader2 className="h-5 w-5 animate-spin text-[var(--color-accent-primary)]" />- </div>- );- }+ if (isLoading) return <ReaderSkeleton />;if (!page) {return (@@ -168,6 +162,44 @@ export function DocsReader({);}+/**+ * The reading column while its page is being fetched.+ *+ * Same wrapper, same 720px column, same rhythm: breadcrumb, title, provenance+ * line, prose. A centred spinner used to sit here, which collapsed the layout+ * to nothing and reflowed the whole column when the page landed.+ */+function ReaderSkeleton() {+ return (+ <div className="flex h-full" aria-busy="true">+ <div className="flex flex-col flex-1 min-w-0">+ <div className="flex-1 overflow-y-auto">+ <div className="mx-auto w-full max-w-[720px] px-4 py-8 sm:px-6">+ <Skeleton className="mb-3 h-3 w-52 rounded" />+ <Skeleton className="mb-2 h-9 w-2/3 rounded" />+ <Skeleton className="mb-5 h-3 w-44 rounded" />+ {/* Literal widths, not interpolated ones — Tailwind only ships the+ classes it can see in the source. */}+ <div className="flex flex-col gap-3">+ {[+ "w-full",+ "w-11/12",+ "w-5/6",+ "w-full",+ "w-3/4",+ "w-full",+ "w-2/3",+ ].map((w, i) => (+ <Skeleton key={i} className={`h-4 rounded ${w}`} />+ ))}+ </div>+ </div>+ </div>+ </div>+ </div>+ );+}+function DocsReaderBody({page,pages,@@ -183,7 +215,7 @@ function DocsReaderBody({upgradeSlot,}: {page: DocPage;- pages: DocPage[];+ pages: DocPageSummary[];repoId: string;sidebarOpen: boolean;scrollRef: React.RefObject<HTMLDivElement | null>;diff --git a/packages/ui/src/docs/docs-tree.tsx b/packages/ui/src/docs/docs-tree.tsxindex f465fa2e2..78e5fb05b 100644--- a/packages/ui/src/docs/docs-tree.tsx+++ b/packages/ui/src/docs/docs-tree.tsx@@ -24,7 +24,7 @@ import {import { RAW_GRAPH_ID, displayLabel, treeLabel } from "./page-labels";import { cn } from "../lib/cn";import { statusBadgeClasses, type FreshnessStatus } from "../lib/confidence";-import type { DocPage } from "@repowise-dev/types/docs";+import type { DocPageSummary } from "@repowise-dev/types/docs";// Synthetic path used as the Onboarding folder's tree key. Distinct from any// real target_path (which never starts with "@") so directory lookups don't@@ -42,16 +42,16 @@ interface TreeNode {name: string;path: string;isDir: boolean;- page?: DocPage;+ page?: DocPageSummary;children: TreeNode[];/** Dotted outline number from the stored tree ("2.4.1"), when the page has one. */section?: string;}interface DocsTreeProps {- pages: DocPage[];+ pages: DocPageSummary[];selectedPageId: string | null;- onSelectPage: (page: DocPage) => void;+ onSelectPage: (page: DocPageSummary) => void;className?: string;}@@ -68,11 +68,11 @@ function PageIcon({ pageType, className }: { pageType: string; className?: strin// Build tree from flat page list// ----------------------------------------------------------------------------function buildOnboardingFolder(pages: DocPage[]): TreeNode | null {+function buildOnboardingFolder(pages: DocPageSummary[]): TreeNode | null {// Bucket every page by its onboarding slot. Both promoted pages// (repo_overview / architecture_diagram, tagged via metadata) and dedicated// `page_type === "onboarding"` pages flow into the same bucket.- const bySlot = new Map<OnboardingSlot, DocPage>();+ const bySlot = new Map<OnboardingSlot, DocPageSummary>();for (const page of pages) {const slot = getOnboardingSlot(page);if (slot && !bySlot.has(slot)) {@@ -106,7 +106,7 @@ function buildOnboardingFolder(pages: DocPage[]): TreeNode | null {};}-function buildTree(allPages: DocPage[]): TreeNode[] {+function buildTree(allPages: DocPageSummary[]): TreeNode[] {// A tombstoned page documents a file that no longer exists. The folder view// mirrors the filesystem, so it drops them too, matching the domain view// (buildStoredTree) rather than listing pages for files that are gone.@@ -129,8 +129,8 @@ function buildTree(allPages: DocPage[]): TreeNode[] {// ---- Remaining special pages (overview/architecture only when *not*// already promoted into the Onboarding folder) and path-based pages ----- const specialPages: DocPage[] = [];- const pathPages: DocPage[] = [];+ const specialPages: DocPageSummary[] = [];+ const pathPages: DocPageSummary[] = [];for (const page of pages) {if (onboardingPageIds.has(page.id)) continue;@@ -310,7 +310,7 @@ const SPINE_TYPES = new Set(["onboarding",]);-const isSpinePage = (page: DocPage) => SPINE_TYPES.has(page.page_type);+const isSpinePage = (page: DocPageSummary) => SPINE_TYPES.has(page.page_type);// The whole concept spine goes without icons.//@@ -334,21 +334,21 @@ const CONCEPT_CONTENT_TYPES = new Set(["repo_overview",]);-const hidesTreeIcon = (page?: DocPage): boolean =>+const hidesTreeIcon = (page?: DocPageSummary): boolean =>page ? CONCEPT_CONTENT_TYPES.has(page.page_type) : false;// The single bottom folder holding every deterministic page. Namespaced like// the other synthetic keys so it can never collide with a real page id.const AUTO_ROOT_KEY = "@group:auto-documented";-function compareSiblings(a: DocPage, b: DocPage): number {+function compareSiblings(a: DocPageSummary, b: DocPageSummary): number {return ((a.display_order ?? 0) - (b.display_order ?? 0) ||(a.target_path || a.title).localeCompare(b.target_path || b.title));}-function buildStoredTree(pages: DocPage[]): TreeNode[] {+function buildStoredTree(pages: DocPageSummary[]): TreeNode[] {// A tombstoned page documents a file that no longer exists. It keeps its row// and its content, but the tree deliberately has no place for it, so it must// be excluded here rather than treated as an unplaced page.@@ -361,7 +361,7 @@ function buildStoredTree(pages: DocPage[]): TreeNode[] {const deterministicPages = visible.filter((p) => !isSpinePage(p));const byId = new Map(spinePages.map((p) => [p.id, p]));- const childrenOf = new Map<string, DocPage[]>();+ const childrenOf = new Map<string, DocPageSummary[]>();const claimed = new Set<string>();for (const page of spinePages) {const parentId = page.parent_page_id;@@ -382,7 +382,7 @@ function buildStoredTree(pages: DocPage[]): TreeNode[] {// Reached, not just claimed: a parent cycle would otherwise silently swallow// every page in it. Anything the walk misses lands in the tail instead.const reached = new Set<string>();- function toNode(page: DocPage, parent: DocPage | undefined): TreeNode {+ function toNode(page: DocPageSummary, parent: DocPageSummary | undefined): TreeNode {reached.add(page.id);const children = (childrenOf.get(page.id) ?? []).filter((c) => !reached.has(c.id))@@ -420,7 +420,7 @@ function buildStoredTree(pages: DocPage[]): TreeNode[] {// an unplaced page is still a page. On a store whose tree has not been built// yet this grouping IS the outline, a fair rendering of a wiki that genuinely// has no recorded hierarchy.- const strayByType = new Map<string, DocPage[]>();+ const strayByType = new Map<string, DocPageSummary[]>();for (const page of spinePages) {if (reached.has(page.id)) continue;const bucket = strayByType.get(page.page_type);@@ -470,7 +470,7 @@ type TypeFilter = "all" | typeof ALL_PAGE_TYPES[number];type FreshnessFilter = "all" | "fresh" | "stale" | "outdated";function matchesFilters(- page: DocPage | undefined,+ page: DocPageSummary | undefined,search: string,typeFilter: TypeFilter,freshnessFilter: FreshnessFilter,@@ -536,7 +536,7 @@ function TreeItem({selectedPageId: string | null;expandedDirs: Set<string>;toggleDir: (path: string) => void;- onSelectPage: (page: DocPage) => void;+ onSelectPage: (page: DocPageSummary) => void;/** Open every dir while a search is active so matches are never hidden. */forceExpand?: boolean;/** Per-row freshness dots are opt-in — off by default to keep rows quiet. */@@ -695,7 +695,7 @@ function FreshnessDot({ status }: { status: FreshnessStatus }) {* Structural pages (files, symbols, contracts) are templates by design and are* never marked.*/-function StubDot({ page }: { page: DocPage }) {+function StubDot({ page }: { page: DocPageSummary }) {if (!isStubPage(page)) return null;return (<span@@ -711,7 +711,7 @@ function RowMarkers({page,showFreshness,}: {- page: DocPage | undefined;+ page: DocPageSummary | undefined;showFreshness: boolean;}) {if (!page) return null;diff --git a/packages/ui/src/docs/page-labels.ts b/packages/ui/src/docs/page-labels.tsindex 284ce148c..93646e2b4 100644--- a/packages/ui/src/docs/page-labels.ts+++ b/packages/ui/src/docs/page-labels.ts@@ -11,11 +11,15 @@// (`doc-nav.ts`, framework-neutral) needs the same labels and must not pull in// React to get them.-import type { DocPage } from "@repowise-dev/types/docs";+import type { DocPageSummary } from "@repowise-dev/types/docs";export const RAW_GRAPH_ID = /^(?:community|scc)[-_\s]?\d+$/i;-export function sccDisplayLabel(page: DocPage): string {+export function sccDisplayLabel(page: DocPageSummary): string {+ // The label is parsed out of the body, so a row fetched without one has+ // nothing to derive from and keeps its title. Callers that render cycle+ // pages in a list fetch those rows in full for this reason.+ if (!page.content) return page.title;// Cycle members appear back-ticked in the generated description; prefer// the "Files Involved" section when present so prose mentions don't leak in.const involved = page.content.split(/^##\s+Files Involved\s*$/im)[1];@@ -47,7 +51,10 @@ const PATH_NAMED_TYPES = new Set(["file_page", "api_contract", "infra_page"]);* off. A file under its module is named relative to it, so three files called* index.py in different resolver directories stay distinguishable.*/-export function treeLabel(page: DocPage, parent: DocPage | undefined): string {+export function treeLabel(+ page: DocPageSummary,+ parent: DocPageSummary | undefined,+): string {const path = page.target_path;if (page.page_type === "symbol_spotlight" && path.includes("::")) {// "path/to/file.py::Symbol" — the file is the parent row, so the symbol is@@ -62,7 +69,7 @@ export function treeLabel(page: DocPage, parent: DocPage | undefined): string {return path.split("/").pop() || path;}-export function displayLabel(page: DocPage): string {+export function displayLabel(page: DocPageSummary): string {const metaLabel = page.metadata?.["derived_label"];if (typeof metaLabel === "string" && metaLabel) return metaLabel;diff --git a/packages/ui/src/lib/page-types.ts b/packages/ui/src/lib/page-types.tsindex c6917aea2..04c096728 100644--- a/packages/ui/src/lib/page-types.ts+++ b/packages/ui/src/lib/page-types.ts@@ -11,7 +11,7 @@ import {Compass,Layers,} from "lucide-react";-import type { DocPage } from "@repowise-dev/types/docs";+import type { DocPageSummary } from "@repowise-dev/types/docs";export interface PageTypeConfig {label: string;@@ -121,7 +121,7 @@ function isOnboardingSlot(value: unknown): value is OnboardingSlot {* - New onboarding pages (page_type === "onboarding") carry the slot in* `metadata.subkind` (and also `metadata.onboarding_slot` as a mirror).*/-export function getOnboardingSlot(page: DocPage): OnboardingSlot | null {+export function getOnboardingSlot(page: DocPageSummary): OnboardingSlot | null {const meta = page.metadata ?? {};const fromSlot = meta["onboarding_slot"];if (isOnboardingSlot(fromSlot)) return fromSlot;diff --git a/packages/ui/src/present/build-present-model.ts b/packages/ui/src/present/build-present-model.tsindex 83fbaa246..6c093a523 100644--- a/packages/ui/src/present/build-present-model.ts+++ b/packages/ui/src/present/build-present-model.ts@@ -3,7 +3,7 @@// guarded so missing page types (e.g. no architecture diagram, index-only repos)// degrade to a shorter deck instead of erroring.-import type { DocPage } from "@repowise-dev/types/docs";+import type { DocPage, DocPageSummary } from "@repowise-dev/types/docs";import { filterMarkdownByPersona } from "../docs/reader-persona";import {splitOnH2,@@ -15,13 +15,13 @@ import {import type { PresentModel, PresentSlide, PresentStep } from "./types";// Curation caps keep the deck tight and premium on large repos.-const MAX_LAYER_SLIDES = 5;-const MAX_MODULE_SLIDES = 5;+export const MAX_LAYER_SLIDES = 5;+export const MAX_MODULE_SLIDES = 5;const MAX_TOUR_STOPS = 8;const DECK_BODY_CHARS = 520;const STEP_BODY_CHARS = 1100;-interface TourStop {+export interface TourStop {order?: number | undefined;title?: string | undefined;target_path?: string | undefined;@@ -29,7 +29,7 @@ interface TourStop {kind?: string | undefined;}-function readTour(overview: DocPage | undefined): TourStop[] {+export function readTour(overview: DocPage | undefined): TourStop[] {const raw = overview?.metadata?.["guided_tour"];if (!Array.isArray(raw)) return [];return raw@@ -44,7 +44,7 @@ function readTour(overview: DocPage | undefined): TourStop[] {}));}-function readLayerOrder(overview: DocPage | undefined): string[] {+export function readLayerOrder(overview: DocPage | undefined): string[] {const raw = overview?.metadata?.["layer_order_ids"] ?? overview?.metadata?.["layer_order"];return Array.isArray(raw) ? raw.filter((x): x is string => typeof x === "string") : [];}@@ -92,11 +92,31 @@ function estimateMinutes(markdown: string): number {return Math.min(12, Math.max(2, 2 + Math.ceil(words / 200)));}-/** True when there is enough generated content to present. */-export function canPresent(pages: DocPage[]): boolean {+/** True when there is enough generated content to present. Reads only the page+ * type, so it answers from a summary listing without fetching any bodies. */+export function canPresent(pages: readonly DocPageSummary[]): boolean {return pages.some((p) => p.page_type === "repo_overview");}+/** Rank layer pages the way the deck orders them, longest-standing first. */+export function orderedLayers<T extends DocPageSummary>(+ pages: readonly T[],+ overview: DocPage | undefined,+): T[] {+ const layerOrder = readLayerOrder(overview);+ const rankOf = (name: string | undefined) => {+ if (!name) return Number.MAX_SAFE_INTEGER;+ const idx = layerOrder.indexOf(name);+ return idx === -1 ? Number.MAX_SAFE_INTEGER : idx;+ };+ return pages+ .filter((p) => p.page_type === "layer_page")+ // Rank on the layer page's target_path, which is the stable ``layer:<slug>``+ // id. layer_name is display text the LLM rewrites between generations, so+ // ranking on it silently drops every layer to MAX_SAFE_INTEGER.+ .sort((a, b) => rankOf(a.target_path) - rankOf(b.target_path));+}+export function buildPresentModel(pages: DocPage[],opts: { repoName?: string } = {},@@ -137,19 +157,7 @@ export function buildPresentModel(}// 3 — Layers, ordered by the overview's layer_order when resolvable- const layerOrder = readLayerOrder(overview);- const rankOf = (name: string | undefined) => {- if (!name) return Number.MAX_SAFE_INTEGER;- const idx = layerOrder.indexOf(name);- return idx === -1 ? Number.MAX_SAFE_INTEGER : idx;- };- const layerPages = pages- .filter((p) => p.page_type === "layer_page")- // Rank on the layer page's target_path, which is the stable ``layer:<slug>``- // id. layer_name is display text the LLM rewrites between generations, so- // ranking on it silently drops every layer to MAX_SAFE_INTEGER.- .sort((a, b) => rankOf(a.target_path) - rankOf(b.target_path))- .slice(0, MAX_LAYER_SLIDES);+ const layerPages = orderedLayers(pages, overview).slice(0, MAX_LAYER_SLIDES);for (const p of layerPages) {// Layer pages generated with the deterministic architecture diagram embed// it as a mermaid block; pair prose with diagram in a split slide. Olderdiff --git a/packages/ui/src/present/index.ts b/packages/ui/src/present/index.tsindex c14460b44..3eeab7ce4 100644--- a/packages/ui/src/present/index.ts+++ b/packages/ui/src/present/index.ts@@ -4,6 +4,7 @@// renders <PresentOverlay>.export { buildPresentModel, canPresent } from "./build-present-model";+export { loadPresentPages } from "./load-present-pages";export { PresentOverlay, type PresentMode } from "./present-overlay";export { PresentButton } from "./present-button";export type { PresentModel, PresentSlide, PresentStep, PresentSlideKind } from "./types";diff --git a/packages/ui/src/present/load-present-pages.ts b/packages/ui/src/present/load-present-pages.tsnew file mode 100644index 000000000..b9afeb60d--- /dev/null+++ b/packages/ui/src/present/load-present-pages.ts@@ -0,0 +1,68 @@+// Gather the pages a Present deck is built from.+//+// `buildPresentModel` needs bodies, but the host's page list no longer carries+// them: on a large wiki that would be tens of megabytes loaded before anything+// renders. A deck only ever draws on a couple of dozen pages, though — the+// overview, the architecture diagram, the first few layers and modules, and the+// guided tour's landmarks — so they can be fetched when Present is opened.+//+// The selection rules live here rather than being re-derived from the builder's+// caps: same constants, same ordering functions, one definition each.++import type { DocPage, DocPageSummary } from "@repowise-dev/types/docs";+import {+ MAX_LAYER_SLIDES,+ MAX_MODULE_SLIDES,+ orderedLayers,+ readTour,+} from "./build-present-model";++/** A row is usable as a `DocPage` once it carries both of the heavy fields. */+function isHydrated(page: DocPageSummary): page is DocPage {+ return typeof page.content === "string" && page.metadata !== undefined;+}++/**+ * Resolve the deck's source pages, fetching bodies only for rows that arrived+ * without one. Returns an empty list when there is nothing to present, which+ * is the same condition `canPresent` reports.+ */+export async function loadPresentPages(+ pages: readonly DocPageSummary[],+ fetchPage: (pageId: string) => Promise<DocPage>,+): Promise<DocPage[]> {+ const hydrate = (page: DocPageSummary): Promise<DocPage> =>+ isHydrated(page) ? Promise.resolve(page) : fetchPage(page.id);++ const overviewRow = pages.find((p) => p.page_type === "repo_overview");+ if (!overviewRow) return [];+ // The overview comes first on its own: the guided tour and the layer order+ // are read out of its metadata, and both decide what else is worth fetching.+ const overview = await hydrate(overviewRow);++ const wanted: DocPageSummary[] = [overview];++ const arch = pages.find((p) => p.page_type === "architecture_diagram");+ if (arch) wanted.push(arch);++ wanted.push(...orderedLayers(pages, overview).slice(0, MAX_LAYER_SLIDES));++ // "Richest first" — the builder proxies richness by body length, which the+ // summary reports as content_chars. A row with no count sorts last rather+ // than winning on a NaN comparison.+ wanted.push(+ ...pages+ .filter((p) => p.page_type === "module_page")+ .sort((a, b) => (b.content_chars ?? 0) - (a.content_chars ?? 0))+ .slice(0, MAX_MODULE_SLIDES),+ );++ const byPath = new Map(pages.map((p) => [p.target_path, p]));+ for (const stop of readTour(overview)) {+ const hit = stop.target_path ? byPath.get(stop.target_path) : undefined;+ if (hit) wanted.push(hit);+ }++ const unique = [...new Map(wanted.map((p) => [p.id, p])).values()];+ return Promise.all(unique.map(hydrate));+}diff --git a/packages/vscode/src/core/webviewApi.ts b/packages/vscode/src/core/webviewApi.tsindex 638274ce9..08118c2f3 100644--- a/packages/vscode/src/core/webviewApi.ts+++ b/packages/vscode/src/core/webviewApi.ts@@ -300,7 +300,8 @@ export function createHostApi(ctx: RepowiseContext, epoch: () => number): HostAp// DocspagesList: () => cached("docs:pages", (id) => listAllPages(id)),- pageById: (pageId) => cached(`docs:page:${pageId}`, () => getPageById(pageId)),+ pageById: (pageId) =>+ cached(`docs:page:${pageId}`, (id) => getPageById(pageId, id)),fileDetail: (relPath) => cached(`docs:file:${relPath}`, (id) => getFileDetail(id, relPath)),// Branch riskdiff --git a/packages/web/src/app/repos/[id]/wiki/[...slug]/page.tsx b/packages/web/src/app/repos/[id]/wiki/[...slug]/page.tsxindex b92d482d5..4ce42c836 100644--- a/packages/web/src/app/repos/[id]/wiki/[...slug]/page.tsx+++ b/packages/web/src/app/repos/[id]/wiki/[...slug]/page.tsx@@ -7,10 +7,10 @@ interface Props {}export async function generateMetadata({ params }: Props): Promise<Metadata> {- const { slug } = await params;+ const { id, slug } = await params;const pageId = slug.join("/");try {- const page = await getPageById(pageId);+ const page = await getPageById(pageId, id);return { title: page.title };} catch {return { title: "Documentation" };diff --git a/packages/web/src/components/docs/docs-explorer.tsx b/packages/web/src/components/docs/docs-explorer.tsxindex b30236cd4..ae6ac35a9 100644--- a/packages/web/src/components/docs/docs-explorer.tsx+++ b/packages/web/src/components/docs/docs-explorer.tsx@@ -1,6 +1,7 @@"use client";import { useState, useCallback, useEffect, useMemo } from "react";+import useSWR from "swr";import { useSearchParams, useRouter } from "next/navigation";import { BookOpen, PanelLeftClose, PanelLeft, Search } from "lucide-react";import { cn } from "@/lib/utils/cn";@@ -12,6 +13,7 @@ import {PresentOverlay,buildPresentModel,canPresent,+ loadPresentPages,type PresentMode,} from "@repowise-dev/ui/present";import {@@ -31,10 +33,11 @@ import { PageGenerateButton } from "./page-generate-button";import { BulkGenerateButton } from "./bulk-generate-button";import { isModelWrittenType, isStubPage } from "@repowise-dev/ui/lib/page-types";import { search as searchPages } from "@/lib/api/search";+import { getPageById, listAllPages } from "@/lib/api/pages";import { downloadTextFile } from "@/lib/utils/download";import { Skeleton } from "@repowise-dev/ui/ui/skeleton";-import type { DocPage } from "@repowise-dev/types/docs";-import type { PageResponse } from "@/lib/api/types";+import type { DocPage, DocPageSummary } from "@repowise-dev/types/docs";+import type { PageSummary } from "@/lib/api/types";interface DocsExplorerProps {repoId: string;@@ -42,7 +45,21 @@ interface DocsExplorerProps {export function DocsExplorer({ repoId }: DocsExplorerProps) {const { pages, isLoading, mutate } = usePages(repoId);- const [selectedPage, setSelectedPage] = useState<PageResponse | null>(null);+ // The list carries no bodies, so the reader's page is fetched on its own.+ // Only the id is state; the page itself is whatever that id resolves to,+ // which keeps it correct after a regeneration without a second copy to sync.+ const [selectedPageId, setSelectedPageId] = useState<string | null>(null);+ const {+ data: selectedPage = null,+ isLoading: pageLoading,+ mutate: mutateSelectedPage,+ } = useSWR(+ selectedPageId ? `page:${selectedPageId}` : null,+ () => getPageById(selectedPageId!, repoId),+ // No retry: the one expected failure is a ?page= id that no longer exists,+ // and retrying a 404 just delays the empty state.+ { revalidateOnFocus: false, shouldRetryOnError: false },+ );const [treePanelOpen, setTreePanelOpen] = useState(() => {if (typeof window === "undefined") return true;return window.matchMedia("(min-width: 768px)").matches;@@ -85,7 +102,7 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {// The docs header offers one bulk "write the subsystem pages" action, shown// only while concept pages are still stubs. A structural page is never a stub.const hasStubs = useMemo(- () => (pages as DocPage[]).some((p) => isStubPage(p)),+ () => pages.some((p) => isStubPage(p)),[pages],);@@ -94,32 +111,30 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {// link or breadcrumb navigates via <Link href="?page=...">.const pageParam = searchParams.get("page");useEffect(() => {- if (pages.length === 0) return;if (pageParam) {- if (selectedPage?.id === pageParam) return;- const match = pages.find((p) => p.id === pageParam);- if (match) setSelectedPage(match);+ // Set straight from the URL without waiting for the list: a page id is+ // enough to fetch it, so the reading column and the tree load side by+ // side rather than one behind the other. An id that turns out not to+ // exist resolves to the reader's empty state, same as before.+ setSelectedPageId(pageParam);return;}// No ?page= in the URL — open the repo overview by default (falling back// to the first page) so the viewer never lands on an empty state.- if (selectedPage) return;+ if (selectedPageId || pages.length === 0) return;const overview = pages.find((p) => p.page_type === "repo_overview");- setSelectedPage(overview ?? pages[0]);- }, [pages, pageParam, selectedPage]);+ setSelectedPageId((overview ?? pages[0])?.id ?? null);+ }, [pages, pageParam, selectedPageId]);- // After a page is (re)generated, pull the fresh page list and re-point the- // viewer at the updated object so its content and provenance flip in place.+ // After a page is (re)generated, pull the fresh list (freshness and stub+ // state live there) and refetch the page on screen so its content and+ // provenance flip in place.const handleGenerated = useCallback(async () => {- const fresh = await mutate();- setSelectedPage((prev) => {- if (!prev || !fresh) return prev;- return fresh.find((p) => p.id === prev.id) ?? prev;- });- }, [mutate]);+ await Promise.all([mutate(), mutateSelectedPage()]);+ }, [mutate, mutateSelectedPage]);- const handleSelectPage = useCallback((page: PageResponse) => {- setSelectedPage(page);+ const handleSelectPage = useCallback((page: DocPageSummary) => {+ setSelectedPageId(page.id);// Update URL without full navigationconst params = new URLSearchParams(searchParams.toString());params.set("page", page.id);@@ -129,17 +144,22 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {// Present mode — an on-the-fly slide deck + guided walkthrough over the same// loaded pages. Open state lives in ?present=deck|walkthrough so a specific// mode is shareable. The model is derived, never generated or fetched.- const presentable = useMemo(- () => canPresent(pages as unknown as DocPage[]),- [pages],- );- const presentModel = useMemo(- () => (presentable ? buildPresentModel(pages as unknown as DocPage[]) : null),- [pages, presentable],- );+ const presentable = useMemo(() => canPresent(pages), [pages]);const presentParam = searchParams.get("present");const presentMode: PresentMode | null =presentParam === "walkthrough" ? "walkthrough" : presentParam === "deck" ? "deck" : null;+ // A deck draws on a couple of dozen pages out of thousands, so their bodies+ // are fetched when Present is opened rather than carried by the page list.+ const { data: presentModel = null } = useSWR(+ presentable && presentMode ? `present:${repoId}` : null,+ async () => {+ const source = await loadPresentPages(pages, (id) =>+ getPageById(id, repoId) as Promise<DocPage>,+ );+ return source.length > 0 ? buildPresentModel(source) : null;+ },+ { revalidateOnFocus: false },+ );const setPresent = useCallback((mode: PresentMode | null, pageId?: string) => {const params = new URLSearchParams(searchParams.toString());@@ -153,31 +173,46 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {);const openInReaderFromPresent = useCallback((pageId: string) => {- const match = pages.find((p) => p.id === pageId);- if (match) setSelectedPage(match);+ setSelectedPageId(pageId);setPresent(null, pageId);},- [pages, setPresent],+ [setPresent],);- // Server-backed search for the ⌘K palette: hit the semantic/full-text- // endpoint, then map results back to the loaded page objects so selection- // behaves identically to a client-side hit. Unknown ids (rare) are dropped.+ // Server-backed search for the ⌘K palette. The palette matches titles and+ // paths itself; bodies are matched here, because the loaded list carries+ // none. Both search modes run: full-text is the literal body match the+ // palette used to do client-side, semantic finds pages that mean the same+ // thing without sharing a word. Results map back to the loaded rows so+ // selection behaves identically to a local hit; unknown ids are dropped.const searchFn = useCallback(async (q: string) => {- const results = await searchPages(q, { repo_id: repoId, limit: 30 });+ const [fulltext, semantic] = await Promise.all([+ searchPages(q, { repo_id: repoId, limit: 20, search_type: "fulltext" }),+ searchPages(q, { repo_id: repoId, limit: 20, search_type: "semantic" }),+ ]);const byId = new Map(pages.map((p) => [p.id, p]));- return results- .map((r) => byId.get(r.page_id))- .filter((p): p is PageResponse => p !== undefined) as unknown as DocPage[];+ const seen = new Set<string>();+ const hits: { page: PageSummary; snippet?: string }[] = [];+ for (const r of [...fulltext, ...semantic]) {+ const page = byId.get(r.page_id);+ if (!page || seen.has(page.id)) continue;+ seen.add(page.id);+ hits.push({ page, ...(r.snippet ? { snippet: r.snippet } : {}) });+ }+ return hits;},[repoId, pages],);- const handleExportAll = useCallback(() => {+ // Every page's markdown in one file. The bodies aren't loaded — that is the+ // point of the summary listing — so this is the one place that still asks+ // for the whole wiki, at the moment someone asks for the whole wiki.+ const handleExportAll = useCallback(async () => {setIsExporting(true);try {- const sorted = [...pages].sort((a, b) =>+ const full = await listAllPages(repoId);+ const sorted = [...full].sort((a, b) =>a.target_path.localeCompare(b.target_path),);const content = sorted@@ -187,7 +222,7 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {} finally {setIsExporting(false);}- }, [pages]);+ }, [repoId]);// The tree panel, rendered at every state so it keeps the full height of the// window rather than starting below a chrome bar. Its skeleton lives here@@ -220,12 +255,11 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {) : (<DocsTreepages={pages}- selectedPageId={selectedPage?.id ?? null}+ // The id, not the fetched page: the row should highlight on click,+ // not once its body has come back.+ selectedPageId={selectedPageId}onSelectPage={(p) => {- // DocsTree yields its DocPage type; the elements are the real- // PageResponse objects we passed in (they carry the extra- // provenance fields), so this narrowing is safe.- handleSelectPage(p as unknown as PageResponse);+ handleSelectPage(p);if (typeof window !== "undefined" && !window.matchMedia("(min-width: 768px)").matches) {setTreePanelOpen(false);}@@ -235,14 +269,11 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {</div>);+ // The reader no longer waits on the page list — it has an id from the URL+ // and fetches its own page — so the only thing that blocks on the list is+ // knowing whether there is any documentation at all.let body: React.ReactNode;- if (isLoading) {- body = (- <div className="flex-1 flex items-center justify-center">- <Skeleton className="h-8 w-48 rounded" />- </div>- );- } else if (pages.length === 0) {+ if (!isLoading && pages.length === 0) {body = (<div className="flex flex-col items-center justify-center h-full gap-4 text-center px-8"><div className="rounded-full bg-[var(--color-bg-elevated)] border border-[var(--color-border-default)] p-4">@@ -265,6 +296,9 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {page={selectedPage}pages={pages}repoId={repoId}+ // Reading-column skeleton while its own page is in flight, and while+ // the list is still deciding which page to open on.+ isLoading={pageLoading || (!selectedPageId && isLoading)}onSelectPage={handleSelectPage}persona={persona}sidebarOpen={sidebarOpen}@@ -359,10 +393,10 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {{/* ⌘K full-text command palette over loaded pages */}<DocsCommandPalette- pages={pages as unknown as DocPage[]}+ pages={pages}open={searchOpen}onOpenChange={setSearchOpen}- onSelect={(p) => handleSelectPage(p as unknown as PageResponse)}+ onSelect={handleSelectPage}searchFn={searchFn}/></div>diff --git a/packages/web/src/components/docs/docs-viewer.tsx b/packages/web/src/components/docs/docs-viewer.tsxindex a665d9684..f8fa37221 100644--- a/packages/web/src/components/docs/docs-viewer.tsx+++ b/packages/web/src/components/docs/docs-viewer.tsx@@ -16,8 +16,8 @@ import { VersionHistoryWrapper } from "@/components/wiki/version-history";import { SecurityPanelWrapper } from "@/components/wiki/security-panel";import { useGraphMetrics, useCallersCallees } from "@/lib/hooks/use-graph";import type { ReaderPersona } from "@repowise-dev/ui/docs/reader-persona";-import type { DocPage } from "@repowise-dev/types/docs";-import type { PageResponse } from "@/lib/api/types";+import type { DocPage, DocPageSummary } from "@repowise-dev/types/docs";+import type { PageResponse, PageSummary } from "@/lib/api/types";function PercentileBar({ value, label }: { value: number; label: string }) {const pct = 100 - value;@@ -241,12 +241,13 @@ function AtAGlance({ repoId, targetPath }: { repoId: string; targetPath: stringinterface DocsViewerProps {page: PageResponse | null;- /** Full page list — powers hierarchical breadcrumbs and prev/next. */- pages?: PageResponse[];+ /** Full page list — powers hierarchical breadcrumbs and prev/next. Rows+ * carry no bodies; the page being read is fetched on its own. */+ pages?: PageSummary[];repoId: string;isLoading?: boolean;/** Select another page in-place (breadcrumb / prev-next / wiki links). */- onSelectPage?: (page: PageResponse) => void;+ onSelectPage?: (page: DocPageSummary) => void;persona: ReaderPersona;sidebarOpen: boolean;/** Called once an inline page upgrade completes so the host refreshes. */@@ -296,10 +297,10 @@ export function DocsViewer({return (<DocsReaderpage={page as unknown as DocPage | null}- pages={pages as unknown as DocPage[]}+ pages={pages}repoId={repoId}isLoading={isLoading}- onSelectPage={onSelectPage as ((p: DocPage) => void) | undefined}+ onSelectPage={onSelectPage}onNavigatePageId={onNavigatePageId}persona={persona}sidebarOpen={sidebarOpen}diff --git a/packages/web/src/components/graph/graph-doc-panel.tsx b/packages/web/src/components/graph/graph-doc-panel.tsxindex d407d9cbc..e6e4d482e 100644--- a/packages/web/src/components/graph/graph-doc-panel.tsx+++ b/packages/web/src/components/graph/graph-doc-panel.tsx@@ -13,7 +13,7 @@ interface GraphDocPanelWrapperProps {export function GraphDocPanel({ repoId, nodeId, onClose }: GraphDocPanelWrapperProps) {const pageId = `file_page:${nodeId}`;- const { page, isLoading, error } = usePage(pageId);+ const { page, isLoading, error } = usePage(pageId, repoId);return (<GraphDocPanelShelldiff --git a/packages/web/src/lib/hooks/use-c4-context.ts b/packages/web/src/lib/hooks/use-c4-context.tsindex 5af956d54..45ff33649 100644--- a/packages/web/src/lib/hooks/use-c4-context.ts+++ b/packages/web/src/lib/hooks/use-c4-context.ts@@ -75,7 +75,7 @@ export function useC4SelectionContext(const { data: page, isLoading: pageLoading } = useSWR<PageResponse>(pageId ? `c4-page:${pageId}` : null,- () => getPageById(pageId!),+ () => getPageById(pageId!, repoId ?? undefined),SWR_OPTS,);diff --git a/packages/web/src/lib/hooks/use-page.ts b/packages/web/src/lib/hooks/use-page.tsindex 369b65c5e..8f0932c0e 100644--- a/packages/web/src/lib/hooks/use-page.ts+++ b/packages/web/src/lib/hooks/use-page.ts@@ -4,10 +4,12 @@ import useSWR from "swr";import { getPageById, getPageVersions } from "@/lib/api/pages";import type { PageResponse, PageVersionResponse } from "@/lib/api/types";-export function usePage(pageId: string | null) {+/** `repoId` routes the lookup to the right store; a workspace server keeps one+ * database per repo and the primary cannot see the others' pages. */+export function usePage(pageId: string | null, repoId?: string) {const { data, error, isLoading, mutate } = useSWR<PageResponse>(pageId ? `page:${pageId}` : null,- () => getPageById(pageId!),+ () => getPageById(pageId!, repoId),{ revalidateOnFocus: false },);return { page: data, error, isLoading, mutate };diff --git a/packages/web/src/lib/hooks/use-pages.ts b/packages/web/src/lib/hooks/use-pages.tsindex 8937afa4d..ce11c1f8c 100644--- a/packages/web/src/lib/hooks/use-pages.ts+++ b/packages/web/src/lib/hooks/use-pages.ts@@ -2,12 +2,57 @@import useSWR from "swr";import { listAllPages } from "@/lib/api/pages";-import type { PageResponse } from "@/lib/api/types";+import type { PageSummary } from "@/lib/api/types";+/**+ * Page types whose row in a *list* is drawn from something a summary doesn't+ * carry: an onboarding slot lives in metadata, and a cycle page's label is+ * parsed out of its body. There are a couple of dozen such pages against+ * thousands of files, so they are fetched in full and merged in.+ *+ * The overview is here for the same reason it is worth having early anyway:+ * it is the page the reader opens on, and Present reads its guided tour.+ */+const HYDRATED_TYPES = [+ "repo_overview",+ "architecture_diagram",+ "onboarding",+ "scc_page",+] as const;++async function loadPages(+ repoId: string,+ pageType?: string,+): Promise<PageSummary[]> {+ const hydrating = pageType+ ? HYDRATED_TYPES.filter((t) => t === pageType)+ : HYDRATED_TYPES;++ const [summaries, ...hydrated] = await Promise.all([+ listAllPages(repoId, {+ ...(pageType ? { page_type: pageType } : {}),+ fields: "summary",+ }),+ ...hydrating.map((page_type) => listAllPages(repoId, { page_type })),+ ]);++ if (hydrated.length === 0) return summaries;+ const full = new Map(hydrated.flat().map((p) => [p.id, p]));+ return summaries.map((p) => full.get(p.id) ?? p);+}++/**+ * Every page in a repo, without the bodies.+ *+ * A full listing of this repo's 5,485 pages measured 38.6 MB over twelve+ * sequential round trips, of which `content` and `metadata` are 95% — and the+ * tree renders neither. The reader fetches the one page it is showing;+ * Present and Export fetch what they need when they are used.+ */export function usePages(repoId: string | null, opts?: { page_type?: string }) {- const { data, error, isLoading, mutate } = useSWR<PageResponse[]>(+ const { data, error, isLoading, mutate } = useSWR<PageSummary[]>(repoId ? `pages:${repoId}:${opts?.page_type ?? "all"}` : null,- () => listAllPages(repoId!, { page_type: opts?.page_type }),+ () => loadPages(repoId!, opts?.page_type),{ revalidateOnFocus: false },);return { pages: data ?? [], error, isLoading, mutate };diff --git a/tests/unit/server/test_pages.py b/tests/unit/server/test_pages.pyindex 8d76d4677..0471e628a 100644--- a/tests/unit/server/test_pages.py+++ b/tests/unit/server/test_pages.py@@ -53,6 +53,111 @@ async def test_list_pages_with_data(client: AsyncClient, app) -> None:assert data[0]["title"] == "main.py"+async def test_list_pages_defaults_to_full_rows(client: AsyncClient, app) -> None:+ """No `fields` means what it always meant — content and metadata included."""+ repo_id, _ = await _create_page(client, app.state.session_factory)+ resp = await client.get("/api/pages", params={"repo_id": repo_id})+ assert resp.status_code == 200+ row = resp.json()[0]+ assert row["content"] == "# Main module\n\nEntry point."+ assert "metadata" in row+++async def test_list_pages_summary_drops_the_heavy_fields(+ client: AsyncClient, app+) -> None:+ repo_id, page_id = await _create_page(client, app.state.session_factory)+ resp = await client.get(+ "/api/pages", params={"repo_id": repo_id, "fields": "summary"}+ )+ assert resp.status_code == 200+ row = resp.json()[0]+ assert "content" not in row+ assert "metadata" not in row+ # Everything a list actually renders is still there.+ assert row["id"] == page_id+ assert row["title"] == "main.py"+ assert row["target_path"] == "src/main.py"+ assert row["content_chars"] == len("# Main module\n\nEntry point.")+++async def test_list_pages_rejects_unknown_fields(client: AsyncClient, app) -> None:+ repo_id, _ = await _create_page(client, app.state.session_factory)+ resp = await client.get(+ "/api/pages", params={"repo_id": repo_id, "fields": "titles"}+ )+ assert resp.status_code == 400+++async def test_lookup_accepts_repo_id(client: AsyncClient, app) -> None:+ """The session is routed by repo_id, so a lookup that knows the repo says+ so — without it a workspace server searches the wrong store."""+ repo_id, page_id = await _create_page(client, app.state.session_factory)+ resp = await client.get(+ "/api/pages/lookup", params={"page_id": page_id, "repo_id": repo_id}+ )+ assert resp.status_code == 200+ assert resp.json()["id"] == page_id+++async def test_lookup_reaches_a_second_workspace_store(client: AsyncClient, app) -> None:+ """In workspace mode each repo has its own database and the primary one+ cannot see the others' rows. A page there is reachable only when the+ request carries the repo_id the session is routed by."""+ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine+ from sqlalchemy.pool import StaticPool++ from repowise.core.persistence.database import init_db++ other_engine = create_async_engine(+ "sqlite+aiosqlite:///:memory:",+ connect_args={"check_same_thread": False},+ poolclass=StaticPool,+ )+ await init_db(other_engine)+ other_factory = async_sessionmaker(+ other_engine, expire_on_commit=False, class_=AsyncSession+ )+ other_repo_id = "b" * 32+ app.state.workspace_sessions = {other_repo_id: other_factory}++ async with get_session(other_factory) as session:+ await crud.upsert_repository(+ session, name="other", local_path="/tmp/other", repo_id=other_repo_id+ )+ await crud.upsert_page(+ session,+ page_id="file_page:src/only_over_here.py",+ repository_id=other_repo_id,+ page_type="file_page",+ title="only_over_here.py",+ content="Lives in the second store.",+ target_path="src/only_over_here.py",+ source_hash="h",+ model_name="mock",+ provider_name="mock",+ )++ try:+ params = {"page_id": "file_page:src/only_over_here.py"}+ # Without repo_id the request lands on the primary store, which has+ # never heard of this page.+ assert (await client.get("/api/pages/lookup", params=params)).status_code == 404++ scoped = await client.get(+ "/api/pages/lookup", params={**params, "repo_id": other_repo_id}+ )+ assert scoped.status_code == 200+ assert scoped.json()["content"] == "Lives in the second store."+ finally:+ await other_engine.dispose()++@pytest.mark.asyncioasync def test_get_page_by_path(client: AsyncClient, app) -> None:_, page_id = await _create_page(client, app.state.session_factory)