Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.ts
index 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.ts
index 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): Pag
const 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): HostedProvid
return 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.ts
index 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.ts
index 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.ts
index 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.py
index 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 AsyncSession
from repowise.core.persistence import crud
from repowise.core.persistence.models import _now_utc
from 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 are
difficult 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__.py
index 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.py
index 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 datetime
from 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: str
repository_id: str
page_type: str
title: str
- content: str
target_path: str
source_hash: str
model_name: str
@@ -25,7 +68,7 @@ class PageResponse(BaseModel):
version: int
confidence: float
freshness_status: str
- metadata: dict
+ content_chars: int
human_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: datetime
updated_at: datetime
+ @classmethod
+ def from_orm(cls, obj: object) -> PageSummaryResponse:
+ return cls(**_summary_fields(obj))
+
+
+class PageResponse(PageSummaryResponse):
+ content: str
+ metadata: dict
+
@classmethod
def 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.ts
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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. Older
diff --git a/packages/ui/src/present/index.ts b/packages/ui/src/present/index.ts
index 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.ts
new file mode 100644
index 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.ts
index 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
// Docs
pagesList: () => 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 risk
diff --git a/packages/web/src/app/repos/[id]/wiki/[...slug]/page.tsx b/packages/web/src/app/repos/[id]/wiki/[...slug]/page.tsx
index 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.tsx
index 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 navigation
const 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) {
) : (
<DocsTree
pages={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.tsx
index 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: string
interface 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 (
<DocsReader
page={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.tsx
index 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 (
<GraphDocPanelShell
diff --git a/packages/web/src/lib/hooks/use-c4-context.ts b/packages/web/src/lib/hooks/use-c4-context.ts
index 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.ts
index 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.ts
index 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.py
index 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.asyncio
async def test_get_page_by_path(client: AsyncClient, app) -> None:
_, page_id = await _create_page(client, app.state.session_factory)