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.

Rebuild the docs page on the Overview's design language (#1118)

Raghav Chamadiya2282d0688db0
diff --git a/packages/ui/__tests__/wiki/path-index.test.ts b/packages/ui/__tests__/wiki/path-index.test.ts
new file mode 100644
index 000000000..e2e71874a
--- /dev/null
+++ b/packages/ui/__tests__/wiki/path-index.test.ts
@@ -0,0 +1,130 @@
+import { describe, it, expect } from "vitest";
+import {
+ buildPathIndex,
+ elidePath,
+ looksLikePath,
+ normalizePath,
+ resolvePath,
+} from "../../src/wiki/path-index";
+
+const page = (id: string, target_path: string) => ({ id, target_path });
+
+describe("looksLikePath", () => {
+ it("accepts paths and filenames with extensions", () => {
+ expect(looksLikePath("packages/core/fs_walk.py")).toBe(true);
+ expect(looksLikePath("languages/spec.py")).toBe(true);
+ expect(looksLikePath("spec.py")).toBe(true);
+ expect(looksLikePath("index.ts")).toBe(true);
+ });
+
+ it("rejects prose shorthand that inline code is also used for", () => {
+ // Bare words are identifiers, not paths.
+ expect(looksLikePath("chat")).toBe(false);
+ expect(looksLikePath("ParsedFile")).toBe(false);
+ // A leading dot with no basename in front of it is a technology name.
+ expect(looksLikePath(".NET")).toBe(false);
+ // Anything with whitespace is a phrase.
+ expect(looksLikePath("npm run build")).toBe(false);
+ expect(looksLikePath("")).toBe(false);
+ });
+});
+
+describe("normalizePath", () => {
+ it("strips the decorations prose adds to a path", () => {
+ expect(normalizePath("./packages/ui")).toBe("packages/ui");
+ expect(normalizePath("packages/ui/")).toBe("packages/ui");
+ expect(normalizePath("packages/ui/src/*")).toBe("packages/ui/src");
+ expect(normalizePath(" packages/ui ")).toBe("packages/ui");
+ expect(normalizePath("packages//ui")).toBe("packages/ui");
+ });
+});
+
+describe("buildPathIndex / resolvePath", () => {
+ const pages = [
+ page("p1", "packages/core/src/repowise/core/fs_walk.py"),
+ page("p2", "packages/core/src/repowise/core/ingestion/models.py"),
+ page("p3", "packages/core/src/repowise/core/persistence/models.py"),
+ page("p4", "packages/ui"),
+ ];
+ const index = buildPathIndex(pages);
+
+ it("resolves a full path", () => {
+ expect(resolvePath(index, "packages/core/src/repowise/core/fs_walk.py")).toEqual({
+ pageId: "p1",
+ path: "packages/core/src/repowise/core/fs_walk.py",
+ });
+ });
+
+ it("resolves an unambiguous trailing fragment", () => {
+ expect(resolvePath(index, "core/fs_walk.py")?.pageId).toBe("p1");
+ expect(resolvePath(index, "fs_walk.py")?.pageId).toBe("p1");
+ expect(resolvePath(index, "ingestion/models.py")?.pageId).toBe("p2");
+ });
+
+ it("refuses to guess when a fragment is ambiguous", () => {
+ // Two pages end in models.py. A wrong link is indistinguishable from a
+ // right one until you follow it, so neither wins.
+ expect(resolvePath(index, "models.py")).toBeNull();
+ });
+
+ it("keeps an exact path even when it is also an ambiguous suffix", () => {
+ const withCollision = buildPathIndex([
+ page("a", "models.py"),
+ page("b", "deep/nested/models.py"),
+ ]);
+ expect(resolvePath(withCollision, "models.py")?.pageId).toBe("a");
+ });
+
+ it("normalizes the anchor before lookup", () => {
+ expect(resolvePath(index, "./packages/ui/")?.pageId).toBe("p4");
+ expect(resolvePath(index, "packages/ui/*")?.pageId).toBe("p4");
+ });
+
+ it("returns null for unknown paths and for non-paths", () => {
+ expect(resolvePath(index, "packages/nope/missing.py")).toBeNull();
+ expect(resolvePath(index, "chat")).toBeNull();
+ });
+
+ it("ignores symbol targets, which the interlinker owns", () => {
+ const symbols = buildPathIndex([page("s", "packages/core/engine.py::Engine")]);
+ expect(resolvePath(symbols, "packages/core/engine.py")).toBeNull();
+ });
+
+ it("tolerates pages with no target path", () => {
+ const messy = buildPathIndex([
+ { id: "x" },
+ { id: "y", target_path: null },
+ { id: "z", target_path: "" },
+ page("ok", "a/b.py"),
+ ]);
+ expect(resolvePath(messy, "a/b.py")?.pageId).toBe("ok");
+ });
+
+ it("indexes only the last few segments, so a deep prefix does not resolve", () => {
+ const deep = buildPathIndex([page("d", "a/b/c/d/e/f.py")]);
+ expect(resolvePath(deep, "d/e/f.py")?.pageId).toBe("d");
+ // Six segments from the end is beyond what prose writes and beyond what
+ // we index; the full path still works.
+ expect(resolvePath(deep, "b/c/d/e/f.py")).toBeNull();
+ expect(resolvePath(deep, "a/b/c/d/e/f.py")?.pageId).toBe("d");
+ });
+});
+
+describe("elidePath", () => {
+ it("leaves a short path alone", () => {
+ expect(elidePath("packages/ui")).toEqual({ head: "", tail: "packages/ui" });
+ });
+
+ it("keeps the tail of a long path and marks the head for dimming", () => {
+ const { head, tail } = elidePath(
+ "packages/core/src/repowise/core/ingestion/models.py",
+ );
+ expect(tail).toBe("ingestion/models.py");
+ expect(head).toBe("packages/…/");
+ });
+
+ it("does not elide a long path that has nothing to drop", () => {
+ const single = "a-very-long-single-segment-filename-indeed.py";
+ expect(elidePath(single)).toEqual({ head: "", tail: single });
+ });
+});
diff --git a/packages/ui/src/brand.ts b/packages/ui/src/brand.ts
index 5f2cb4754..7b8ee8d6d 100644
--- a/packages/ui/src/brand.ts
+++ b/packages/ui/src/brand.ts
@@ -43,13 +43,13 @@ export const LIGHT = {
/** Dark-mode surface/text values. */
export const DARK = {
- bgRoot: "#1a1a1b",
- bgSurface: "#232325",
- bgElevated: "#2b2c2e",
- bgInset: "#141415",
- textPrimary: "#ececed",
- textSecondary: "#a2a2a6",
- textTertiary: "#717176",
+ bgRoot: "#0e0e0f",
+ bgSurface: "#141416",
+ bgElevated: "#1c1c1f",
+ bgInset: "#0a0a0b",
+ textPrimary: "#f2f2f3",
+ textSecondary: "#b4b4b9",
+ textTertiary: "#7c7c82",
accentPrimary: "#f59520",
accentFill: "#f59520",
accentSecondary: "#a98fc4",
diff --git a/packages/ui/src/docs/docs-header.tsx b/packages/ui/src/docs/docs-header.tsx
index d5d079ede..1f22022c5 100644
--- a/packages/ui/src/docs/docs-header.tsx
+++ b/packages/ui/src/docs/docs-header.tsx
@@ -17,10 +17,16 @@ const ICONS = {
} as const;
/**
- * Single compact chrome row for the documentation surface: title, the
- * Explorer / Doc-freshness view switch as a segmented control, and a
- * right-aligned slot for page-specific actions. Pure presentation — the host
- * resolves tab hrefs/active state and injects a router-aware ``LinkComponent``.
+ * Single compact chrome row for the documentation surface: the Explorer /
+ * Doc-freshness view switch as a segmented control, and a right-aligned slot
+ * for page-specific actions. Pure presentation — the host resolves tab
+ * hrefs/active state and injects a router-aware ``LinkComponent``.
+ *
+ * The row sits beside the pages tree rather than above it, so the tree keeps
+ * the full height of the window and this bar spans only the surface it acts
+ * on. The "Documentation" heading it used to show is kept for document
+ * structure but no longer rendered: the route is /docs, the tab strip says
+ * Explorer, and on the reader the page's own title is the h1 directly beneath.
*/
export function DocsHeader({
tabs,
@@ -33,13 +39,11 @@ export function DocsHeader({
}) {
const Link = LinkComponent;
return (
- <div className="shrink-0 flex h-12 items-center gap-3 border-b border-[var(--color-border-default)] px-4 sm:px-6">
- <h1 className="text-sm font-semibold text-[var(--color-text-primary)]">
- Documentation
- </h1>
+ <div className="shrink-0 flex h-12 items-center gap-2 border-b border-[var(--color-border-default)] px-3 sm:gap-3 sm:px-6">
+ <h1 className="sr-only">Documentation</h1>
<nav
- className="flex items-center rounded-lg bg-[var(--color-bg-elevated)] p-0.5"
+ className="flex shrink-0 items-center rounded-lg bg-[var(--color-bg-elevated)] p-0.5"
aria-label="Docs views"
>
{tabs.map((tab) => {
@@ -49,21 +53,29 @@ export function DocsHeader({
key={tab.href}
href={tab.href}
aria-current={tab.isActive ? "page" : undefined}
+ title={tab.label}
className={cn(
- "flex items-center gap-1.5 rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
+ "flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium whitespace-nowrap transition-colors sm:px-2.5",
tab.isActive
? "bg-[var(--color-bg-surface)] text-[var(--color-text-primary)] shadow-sm"
: "text-[var(--color-text-tertiary)] hover:text-[var(--color-text-secondary)]",
)}
>
- <Icon className="h-3.5 w-3.5" />
- {tab.label}
+ <Icon className="h-3.5 w-3.5 shrink-0" />
+ {/* On a phone the two icons carry the switch on their own. The
+ labels are the first thing to go: they are the widest element
+ in the row and the least load-bearing, since the active tab is
+ already marked by its filled ground. */}
+ <span className="hidden sm:inline">{tab.label}</span>
</Link>
);
})}
</nav>
- <div className="ml-auto flex items-center gap-2">{children}</div>
+ {/* Actions scroll rather than wrap or squeeze the switch. */}
+ <div className="ml-auto flex min-w-0 items-center gap-2 overflow-x-auto">
+ {children}
+ </div>
</div>
);
}
diff --git a/packages/ui/src/docs/docs-page-actions.tsx b/packages/ui/src/docs/docs-page-actions.tsx
index ef6d4958b..b8df30c79 100644
--- a/packages/ui/src/docs/docs-page-actions.tsx
+++ b/packages/ui/src/docs/docs-page-actions.tsx
@@ -35,7 +35,7 @@ export function DocsPageActions({
}) {
return (
<>
- <ConfidenceBadge score={confidence} status={freshnessStatus} />
+ <ConfidenceBadge score={confidence} status={freshnessStatus} compact />
{personaHasEffect && (
<div
className="inline-flex items-center rounded-md border border-[var(--color-border-default)] p-0.5 shrink-0"
diff --git a/packages/ui/src/docs/docs-reader.tsx b/packages/ui/src/docs/docs-reader.tsx
index 8442073ec..fdafdfb09 100644
--- a/packages/ui/src/docs/docs-reader.tsx
+++ b/packages/ui/src/docs/docs-reader.tsx
@@ -3,13 +3,11 @@
import { useCallback, useEffect, useMemo, useRef } from "react";
import {
FileText,
- Clock,
- Cpu,
ArrowRight,
ArrowLeft,
+ ChevronRight,
Loader2,
Layers,
- FileInput,
} from "lucide-react";
import type { DocPage } from "@repowise-dev/types/docs";
import { cn } from "../lib/cn";
@@ -28,6 +26,11 @@ import {
} from "../wiki/wiki-links-types";
import { Breadcrumb } from "../shared/breadcrumb";
+/** 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
+ * of everything the graph knows. */
+const RELATED_LIMIT = 5;
+
const RELATED_REASON_LABELS: Record<RelatedReason, string> = {
imports: "imports",
"imported-by": "imported by",
@@ -195,6 +198,11 @@ function DocsReaderBody({
const nav = useMemo(() => computeDocNav(page, pages), [page, pages]);
const wikiLinks = useMemo(() => getWikiLinks(page.metadata), [page.metadata]);
+ // A page with no model behind it. Structural pages are templates by design
+ // and always will be; a model-written page that is still a template has
+ // prose outstanding, which is what the upgrade affordance is for.
+ const isTemplatePage = page.provider_name === "template";
+
// The reader renders the page title as the H1 above the body, but generated
// content often opens with its own "# <title>" line (the deterministic
// templates do), so the same heading shows twice. Drop a leading H1 that
@@ -327,7 +335,14 @@ function DocsReaderBody({
<div className="flex h-full">
<div className="flex flex-col flex-1 min-w-0">
<div ref={scrollRef} className="flex-1 overflow-y-auto">
- <div className="px-4 sm:px-6 py-8 max-w-[768px] mx-auto">
+ {/* Centred in the space the rail leaves, with the rail itself flush
+ to the edge. The two alternatives both fail on a wide window:
+ anchoring the column left opens a ~620px hole between it and the
+ rail, and centring the column-plus-rail group as a unit unpins the
+ rail from the edge and strands whitespace to its right. Centring
+ here makes the gap to the rail equal the gap to the tree, so both
+ read as margins rather than as a gap. */}
+ <div className="mx-auto w-full max-w-[720px] px-4 py-8 sm:px-6">
{/* Hierarchical breadcrumb */}
<div className="mb-3 overflow-hidden">
<Breadcrumb
@@ -346,14 +361,33 @@ function DocsReaderBody({
{page.title}
</h1>
- {/* One calm metadata line: type + module + layer + freshness. The
- generation provenance (version, tokens, model) lives in the
- right rail so the page opens on its content, not its receipt. */}
- <div className="flex flex-wrap items-center gap-x-3 gap-y-1.5 text-[10px] text-[var(--color-text-tertiary)] mb-6">
- <span className="rounded-full bg-[var(--color-bg-elevated)] px-2 py-0.5 uppercase tracking-wider">
+ {/* One quiet provenance line: what kind of page this is, who wrote
+ it, and when. Previously this row carried an accent-filled
+ "Regenerate" pill immediately beside the h1, which read as a
+ statement about the page rather than an action on it and
+ out-shouted the title. The upgrade affordance now sits at the
+ end of the content, where a reader has seen the page is thin.
+
+ "Written by <model>" / "Built from the index" is the Overview
+ page's vocabulary, deliberately: a page can lack prose because
+ its provider call failed, so calling that "deterministic" would
+ be untrue. */}
+ <div className="flex flex-wrap items-center gap-x-2 gap-y-1.5 text-[11px] text-[var(--color-text-tertiary)] mb-5">
+ <span className="font-mono text-[10px] uppercase tracking-[0.12em]">
{getPageTypeLabel(page.page_type)}
</span>
- {upgradeSlot}
+ <span aria-hidden className="opacity-40">&middot;</span>
+ <span className="text-[var(--color-text-secondary)]">
+ {isTemplatePage
+ ? "Built from the index"
+ : page.model_name
+ ? `Written by ${page.model_name}`
+ : "Written by a model"}
+ </span>
+ <span aria-hidden className="opacity-40">&middot;</span>
+ <span title={page.updated_at}>
+ updated {formatRelativeTime(page.updated_at)}
+ </span>
{moduleSeg && (
<button
onClick={() => goToPageId(moduleSeg.pageId!)}
@@ -377,12 +411,54 @@ function DocsReaderBody({
{layerName}
</span>
))}
- <span className="flex items-center gap-1">
- <Clock className="h-3 w-3" />
- {formatRelativeTime(page.updated_at)}
- </span>
</div>
+ {/* What this page was written from. The rail carried this as
+ basenames only, below the fold of a narrow column; at the top of
+ the page it frames everything under it, and it is the one piece
+ of provenance a reader wants *before* reading rather than
+ after. Collapsed by default — it answers a question, it does not
+ raise one. */}
+ {sources.length > 0 && (
+ <details className="group mb-6 rounded-lg border border-[var(--color-border-default)]">
+ <summary className="flex cursor-pointer list-none items-center gap-2 px-3.5 py-2 text-xs text-[var(--color-text-secondary)]">
+ <ChevronRight className="h-3 w-3 shrink-0 text-[var(--color-text-tertiary)] transition-transform group-open:rotate-90" />
+ <span>
+ Built from {sources.length} source{sources.length === 1 ? "" : " files"}
+ </span>
+ <span className="ml-auto truncate font-mono text-[10px] text-[var(--color-text-tertiary)]">
+ {sources
+ .slice(0, 3)
+ .map((s) => s.path.split("/").pop())
+ .join(", ")}
+ {sources.length > 3 && " …"}
+ </span>
+ </summary>
+ <ul className="flex flex-col gap-1 border-t border-[var(--color-border-default)] px-3.5 py-2.5">
+ {sources.map((s) => (
+ <li key={s.path} className="text-xs">
+ {s.pageId ? (
+ <button
+ onClick={() => goToPageId(s.pageId!)}
+ className="block w-full truncate text-left font-mono text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-accent-primary)]"
+ title={`${s.path} (${s.kind})`}
+ >
+ {s.path}
+ </button>
+ ) : (
+ <span
+ className="block truncate font-mono text-[var(--color-text-tertiary)]"
+ title={`${s.path} (${s.kind})`}
+ >
+ {s.path}
+ </span>
+ )}
+ </li>
+ ))}
+ </ul>
+ </details>
+ )}
+
{/* Low-confidence flag */}
{page.confidence > 0 && page.confidence < 0.5 && (
<div className="mb-4 flex items-start gap-1.5 rounded-md border border-[var(--color-warning)]/40 bg-[var(--color-warning)]/10 px-3 py-2">
@@ -401,16 +477,36 @@ function DocsReaderBody({
</div>
)}
- {/* Markdown content */}
- <article className="prose prose-invert max-w-none leading-relaxed overflow-hidden">
+ {/* Markdown content.
+ No `prose` wrapper: every element the renderer emits is already
+ styled through our own tokens, so the plugin contributed exactly
+ two things — a hardcoded `prose-invert` that fed dark variables
+ to light mode, and `code::before/::after { content: "`" }`, which
+ printed literal backticks around every unresolved inline ref. */}
+ <article className="max-w-none leading-relaxed overflow-hidden">
<WikiMarkdown
content={visibleContent}
wikiLinks={wikiLinks}
buildHref={(pid) => buildPageHref(pid)}
LinkComponent={WikiInlineLink}
+ pages={pages}
/>
</article>
+ {/* The upgrade affordance, at the end of the content rather than
+ beside the title. Someone who has read to here knows the page is
+ thin; someone at the title does not yet, and an accent pill up
+ there competed with the h1 for a decision they could not make. */}
+ {isTemplatePage && upgradeSlot && (
+ <div className="mt-8 flex flex-wrap items-center gap-x-3 gap-y-2 border-t border-[var(--color-border-default)] pt-4">
+ <p className="text-xs text-[var(--color-text-tertiary)]">
+ This page is built from the index. A model can write the how and
+ why on top of it.
+ </p>
+ {upgradeSlot}
+ </div>
+ )}
+
{/* Sibling prev / next */}
{(nav.prev || nav.next) && (
<nav className="mt-8 flex items-stretch gap-3 border-t border-[var(--color-border-default)] pt-4">
@@ -471,127 +567,100 @@ function DocsReaderBody({
</div>
)}
- {/* Related pages, bottom strip. The right rail is hidden below
- lg (vscode webview panels rarely reach lg either), so narrow
- viewports get the related links here instead. */}
- {relatedLinks.length > 0 && (
- <div className="mt-8 lg:hidden">
- <p className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider mb-2">
- Related
- </p>
- <div className="flex flex-wrap gap-1.5">
- {relatedLinks.slice(0, 8).map((r) => (
- <button
- key={r.id}
- onClick={() => goToPageId(r.id)}
- className="rounded-full border border-[var(--color-border-default)] bg-[var(--color-bg-surface)] px-2.5 py-1 text-xs text-[var(--color-text-secondary)] hover:text-[var(--color-accent-primary)] hover:border-[var(--color-accent-primary)] transition-colors"
- title={r.reason ? RELATED_REASON_LABELS[r.reason] : r.title}
- >
- {r.title}
- </button>
- ))}
+ {/* Where the rail goes when there is no room for a rail.
+ Nothing is dropped at narrow widths, it relocates: the reader
+ already did this for Related, and the same treatment now covers
+ the intelligence sections and the contents. The breakpoint is
+ 2xl, not lg — see the rail below for why. */}
+ <div className="mt-10 grid gap-8 border-t border-[var(--color-border-default)] pt-6 sm:grid-cols-2 2xl:hidden">
+ {intelligenceSlot && (
+ <div className="flex flex-col gap-4">{intelligenceSlot}</div>
+ )}
+ {relatedLinks.length > 0 && (
+ <div>
+ <p className="mb-2 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">
+ Related
+ </p>
+ <ul className="flex flex-col gap-2">
+ {relatedLinks.slice(0, RELATED_LIMIT).map((r) => (
+ <li key={r.id}>
+ <button
+ onClick={() => goToPageId(r.id)}
+ className="block w-full text-left text-xs leading-snug text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-accent-primary)]"
+ >
+ {r.title}
+ </button>
+ {r.reason && (
+ <span className="block font-mono text-[10px] text-[var(--color-text-tertiary)]">
+ {RELATED_REASON_LABELS[r.reason]}
+ </span>
+ )}
+ </li>
+ ))}
+ </ul>
</div>
- </div>
- )}
+ )}
+ </div>
</div>
</div>
</div>
- {/* Right intelligence rail — on-page contents, provenance, related,
- backlinks, then host-supplied data-bound intelligence sections. */}
+ {/* Right rail — three zones, in the order a reader wants them: where am
+ I in this page, what do I need to know about this code, where do I go
+ next. The receipt sits under a hairline at the bottom.
+
+ It used to carry eight blocks behind five uppercase labels, which is
+ mostly label for about a dozen rows, and the intelligence sections
+ each announced themselves separately even when they were three rows
+ long. At a glance, Importance, Community, Call graph and Security are
+ now one Signals list assembled by the host.
+
+ `2xl` (1536px), not `lg` (1024px): the chrome either side of the
+ reading column is 56 + 288 + 300 = 644px, and body copy at 16px wants
+ about 640px to reach 65 characters. At lg the column landed at ~420px,
+ so the rail was switching on some 400px before the layout could pay
+ for it. Below 2xl every section here renders under the article
+ instead. */}
{sidebarOpen && (
- <div className="hidden lg:block border-l border-[var(--color-border-default)] bg-[var(--color-bg-surface)] shrink-0 w-[260px] overflow-auto">
- <div className="space-y-6 p-4">
+ <div className="hidden 2xl:block shrink-0 w-[300px] overflow-auto">
+ <div className="flex flex-col gap-7 py-8 pl-6 pr-7">
<TableOfContents content={bodyContent} />
- {sources.length > 0 && (
- <div>
- <div className="flex items-center gap-1.5 mb-2">
- <FileInput className="h-3 w-3 text-[var(--color-text-tertiary)]" />
- <span className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider">
- Built from
- </span>
- </div>
- <ul className="space-y-1">
- {sources.slice(0, 5).map((s) => (
- <li key={s.path} className="text-xs">
- {s.pageId ? (
- <button
- onClick={() => goToPageId(s.pageId!)}
- className="truncate text-left font-mono text-[var(--color-text-secondary)] hover:text-[var(--color-accent-primary)] transition-colors w-full"
- title={`${s.path} (${s.kind})`}
- >
- {s.path.split("/").pop()}
- </button>
- ) : (
- <span
- className="block truncate font-mono text-[var(--color-text-tertiary)]"
- title={`${s.path} (${s.kind})`}
- >
- {s.path.split("/").pop()}
- </span>
- )}
- </li>
- ))}
- </ul>
- {sources.length > 5 && (
- <p className="mt-1 text-[10px] text-[var(--color-text-tertiary)]">
- + {sources.length - 5} more
- </p>
- )}
- </div>
- )}
- {/* Generation provenance — moved off the title row so the page
- opens on its content. Model, cost and version answer "how was
- this made", which is a rail question, not a headline. */}
- <div>
- <p className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider mb-2">
- Generated
- </p>
- <div className="space-y-1 text-[10px] text-[var(--color-text-tertiary)]">
- {page.model_name && (
- <div className="flex items-center gap-1.5 font-mono">
- <Cpu className="h-3 w-3 shrink-0" />
- <span className="truncate" title={page.model_name}>
- {page.model_name}
- </span>
- </div>
- )}
- <div className="font-mono">
- {formatTokens(page.input_tokens)} in · {formatTokens(page.output_tokens)} out
- </div>
- <div>v{page.version}</div>
- </div>
- </div>
+
+ {intelligenceSlot}
+
{relatedLinks.length > 0 && (
<div>
- <p className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider mb-2">
+ <p className="mb-2.5 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">
Related
</p>
- <ul className="space-y-1.5">
- {relatedLinks.slice(0, 8).map((r) => (
- <li key={r.id} className="text-xs">
+ <ul className="flex flex-col gap-2.5">
+ {relatedLinks.slice(0, RELATED_LIMIT).map((r) => (
+ <li key={r.id}>
+ {/* Wraps rather than truncates. At 260px the old rail
+ rendered "File: packages/server/src/repowise/s…",
+ which names nothing. */}
<button
onClick={() => goToPageId(r.id)}
- className="truncate text-left text-[var(--color-text-secondary)] hover:text-[var(--color-accent-primary)] transition-colors w-full"
- title={r.title}
+ className="block w-full text-left text-xs leading-snug text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-accent-primary)]"
>
{r.title}
</button>
{r.reason && (
- <span className="block text-[10px] text-[var(--color-text-tertiary)]">
+ <span className="block font-mono text-[10px] text-[var(--color-text-tertiary)]">
{RELATED_REASON_LABELS[r.reason]}
</span>
)}
</li>
))}
</ul>
- {relatedLinks.length > 8 && (
- <p className="mt-1 text-[10px] text-[var(--color-text-tertiary)]">
- + {relatedLinks.length - 8} more
+ {relatedLinks.length > RELATED_LIMIT && (
+ <p className="mt-2 text-[10px] text-[var(--color-text-tertiary)]">
+ + {relatedLinks.length - RELATED_LIMIT} more
</p>
)}
</div>
)}
+
<BacklinksPanel
backlinks={getBacklinks(page.metadata)}
repoId={repoId}
@@ -602,7 +671,20 @@ function DocsReaderBody({
</LinkComponent>
)}
/>
- {intelligenceSlot}
+
+ {/* How this page was made. A receipt, so it sits at the bottom
+ under a rule rather than above the things you came for. */}
+ <div className="mt-auto flex flex-wrap gap-x-3 gap-y-1 border-t border-[var(--color-border-default)] pt-3.5 font-mono text-[10px] tabular-nums text-[var(--color-text-tertiary)]">
+ {page.model_name && (
+ <span className="truncate" title={page.model_name}>
+ {page.model_name}
+ </span>
+ )}
+ <span>
+ {formatTokens(page.input_tokens)} in · {formatTokens(page.output_tokens)} out
+ </span>
+ <span>v{page.version}</span>
+ </div>
</div>
</div>
)}
diff --git a/packages/ui/src/docs/docs-tree.tsx b/packages/ui/src/docs/docs-tree.tsx
index 88c6c7b17..f465fa2e2 100644
--- a/packages/ui/src/docs/docs-tree.tsx
+++ b/packages/ui/src/docs/docs-tree.tsx
@@ -18,6 +18,7 @@ import {
getOnboardingSlot,
getPageTypeIcon,
getPageTypeLabel,
+ isStubPage,
type OnboardingSlot,
} from "../lib/page-types";
import { RAW_GRAPH_ID, displayLabel, treeLabel } from "./page-labels";
@@ -311,13 +312,27 @@ const SPINE_TYPES = new Set([
const isSpinePage = (page: DocPage) => SPINE_TYPES.has(page.page_type);
-// Concept content rows (the modules and cycles nested under a layer) all carry
-// the same folder glyph, so a run of them reads as a column of identical icons
-// that says nothing the indentation does not already say. Dropping the icon on
-// just these rows lets the outline read by its shape. Layers keep their icon as
-// the section anchor, onboarding chapters keep theirs, and the deterministic
-// file tree keeps its file/folder glyphs — only this middle rung goes quiet.
-const CONCEPT_CONTENT_TYPES = new Set(["module_page", "scc_page"]);
+// The whole concept spine goes without icons.
+//
+// This started as a rule for the middle rung only: modules and cycles nested
+// under a layer all carry the same folder glyph, so a run of them reads as a
+// column of identical icons that says nothing the indentation does not already
+// say. The same argument holds one rung up. Every onboarding chapter draws the
+// same compass and every layer the same stack, so the top of the tree was nine
+// rows of near-identical glyphs down the left edge, which is a texture rather
+// than information.
+//
+// Without them the outline reads by its shape — indentation for depth, weight
+// for rank — which is how a table of contents has always worked. The
+// deterministic file tree keeps its file/folder glyphs, where the icon does
+// distinguish one row from the next.
+const CONCEPT_CONTENT_TYPES = new Set([
+ "module_page",
+ "scc_page",
+ "onboarding",
+ "layer_page",
+ "repo_overview",
+]);
const hidesTreeIcon = (page?: DocPage): boolean =>
page ? CONCEPT_CONTENT_TYPES.has(page.page_type) : false;
@@ -580,7 +595,11 @@ function TreeItem({
)}
<span
className={cn(
- "truncate font-medium",
+ // Wraps rather than truncates. A section title cut to
+ // "Documentation Generation Engi…" names nothing, and the tree
+ // has the vertical room — it is a list of a few dozen concept
+ // rows, not a viewport-bound table.
+ "min-w-0 text-left font-medium [overflow-wrap:anywhere]",
// A top-level section is the parent of everything indented under
// it, so it carries the strongest weight in the tree.
(node.path === ONBOARDING_DIR_KEY || depth === 0) &&
@@ -589,9 +608,7 @@ function TreeItem({
>
{node.name}
</span>
- {showFreshness && node.page && (
- <FreshnessDot status={node.page.freshness_status as FreshnessStatus} />
- )}
+ <RowMarkers page={node.page} showFreshness={showFreshness} />
</button>
{isExpanded && hasChildren && (
@@ -640,10 +657,8 @@ function TreeItem({
)}
/>
)}
- <span className="truncate">{node.name}</span>
- {showFreshness && node.page && (
- <FreshnessDot status={node.page.freshness_status as FreshnessStatus} />
- )}
+ <span className="min-w-0 text-left [overflow-wrap:anywhere]">{node.name}</span>
+ <RowMarkers page={node.page} showFreshness={showFreshness} />
</button>
);
}
@@ -665,7 +680,49 @@ function FreshnessDot({ status }: { status: FreshnessStatus }) {
if (status === "fresh") return null;
const color =
status === "stale" ? "bg-[var(--color-warning)]" : "bg-[var(--color-error)]";
- return <span className={cn("ml-auto h-1.5 w-1.5 rounded-full shrink-0", color)} />;
+ return <span className={cn("h-1.5 w-1.5 rounded-full shrink-0", color)} />;
+}
+
+/**
+ * A page a model is expected to write that has not been written yet.
+ *
+ * Whether a page carries prose was previously only discoverable by opening it
+ * and reading the rail, so "how far does the prose go" took one click per page.
+ * Marking it in the tree answers that while browsing.
+ *
+ * Hollow, and only on stubs — same reasoning as FreshnessDot above. A marker
+ * on every row says nothing; this one means there is something left to do.
+ * Structural pages (files, symbols, contracts) are templates by design and are
+ * never marked.
+ */
+function StubDot({ page }: { page: DocPage }) {
+ if (!isStubPage(page)) return null;
+ return (
+ <span
+ title="Built from the index. A model has not written this page yet."
+ className="h-1.5 w-1.5 shrink-0 rounded-full ring-1 ring-[var(--color-text-tertiary)]"
+ />
+ );
+}
+
+/** Trailing status markers, right-aligned as one group so the two dots do not
+ * fight over `ml-auto`. */
+function RowMarkers({
+ page,
+ showFreshness,
+}: {
+ page: DocPage | undefined;
+ showFreshness: boolean;
+}) {
+ if (!page) return null;
+ return (
+ <span className="ml-auto flex shrink-0 items-center gap-1 pl-1">
+ <StubDot page={page} />
+ {showFreshness && (
+ <FreshnessDot status={page.freshness_status as FreshnessStatus} />
+ )}
+ </span>
+ );
}
// ---------------------------------------------------------------------------
diff --git a/packages/ui/src/wiki/confidence-badge.tsx b/packages/ui/src/wiki/confidence-badge.tsx
index 1db52c981..bc3cf5683 100644
--- a/packages/ui/src/wiki/confidence-badge.tsx
+++ b/packages/ui/src/wiki/confidence-badge.tsx
@@ -17,6 +17,15 @@ interface ConfidenceBadgeProps {
showScore?: boolean;
staleSince?: string | null;
className?: string;
+ /**
+ * Drop to the status dot alone below `sm`.
+ *
+ * For crowded chrome rows on a phone. The dot already carries the state —
+ * colour is the whole signal, and the word beside it is the widest thing in
+ * the row. Opt-in, because in a table or a card the label is the readable
+ * part and losing it would be a downgrade.
+ */
+ compact?: boolean;
}
export function ConfidenceBadge({
@@ -25,6 +34,7 @@ export function ConfidenceBadge({
showScore = false,
staleSince,
className,
+ compact = false,
}: ConfidenceBadgeProps) {
const status = (statusProp as FreshnessStatus | undefined) ?? scoreToStatus(score);
const badgeClasses = statusBadgeClasses(status);
@@ -32,22 +42,30 @@ export function ConfidenceBadge({
const badge = (
<span
+ {...(compact ? { title: label } : {})}
className={cn(
- "inline-flex items-center gap-1.5 rounded border px-2 py-0.5 text-xs font-medium transition-colors",
+ "inline-flex shrink-0 items-center gap-1.5 rounded border py-0.5 text-xs font-medium transition-colors",
+ compact ? "px-1.5 sm:px-2" : "px-2",
badgeClasses,
className,
)}
>
<span
className={cn(
- "h-1.5 w-1.5 rounded-full",
+ "h-1.5 w-1.5 shrink-0 rounded-full",
status === "fresh" && "bg-[var(--color-success)]",
status === "stale" && "animate-pulse bg-[var(--color-warning)]",
status === "outdated" && "bg-[var(--color-error)]",
)}
/>
- {label}
- {showScore && <span className="opacity-70">· {formatConfidence(score)}</span>}
+ {/* Hidden visually, never from a screen reader: the colour is the signal
+ on a phone, but "Fresh" is still the name of the state. */}
+ <span className={cn(compact && "sr-only sm:not-sr-only")}>{label}</span>
+ {showScore && (
+ <span className={cn("opacity-70", compact && "hidden sm:inline")}>
+ · {formatConfidence(score)}
+ </span>
+ )}
</span>
);
diff --git a/packages/ui/src/wiki/path-index.ts b/packages/ui/src/wiki/path-index.ts
new file mode 100644
index 000000000..c81cac500
--- /dev/null
+++ b/packages/ui/src/wiki/path-index.ts
@@ -0,0 +1,174 @@
+/**
+ * Resolving a code path mentioned in prose to the wiki page that documents it.
+ *
+ * The backend already resolves *some* inline refs during interlinking and
+ * persists them as ``metadata.wiki_links``. That pass only fires for anchors it
+ * recognised at generation time, so on a real page most path mentions come back
+ * unresolved: the repo overview for this codebase carries 57 distinct inline
+ * code spans and 34 wiki_links, of which a handful actually match. Everything
+ * else renders as dead text even though a ``file_page`` for that exact path is
+ * sitting in the same loaded page list.
+ *
+ * So resolve the rest here, on the client, from the pages the reader already
+ * has. No backend change, no regeneration, and it stays correct as the index
+ * grows because it is derived from the live list rather than baked into prose.
+ *
+ * Two rules keep it honest:
+ *
+ * - An exact ``target_path`` always wins over a suffix match.
+ * - An ambiguous suffix resolves to nothing. Prose says ``models.py`` and this
+ * monorepo has eleven of them; linking to whichever one happened to be
+ * indexed first is worse than not linking at all, because a wrong link is
+ * indistinguishable from a right one until you follow it.
+ */
+
+/** The subset of a page this module needs. Structural typing keeps it usable
+ * from both the web app's `PageResponse` and the shared `DocPage`. */
+export interface PathIndexablePage {
+ id: string;
+ target_path?: string | null;
+}
+
+export interface PathTarget {
+ pageId: string;
+ /** The full indexed path, for the link's tooltip. */
+ path: string;
+}
+
+export interface PathIndex {
+ /** Full ``target_path`` → page. */
+ exact: Map<string, PathTarget>;
+ /** Trailing path fragment → page, or null where the fragment is ambiguous. */
+ suffix: Map<string, PathTarget | null>;
+}
+
+/**
+ * How many trailing segments of a path get their own suffix entry.
+ *
+ * Four covers what prose actually writes (`spec.py`, `languages/spec.py`,
+ * `ingestion/languages/spec.py`) without indexing every prefix of every path
+ * in a 5,000-page repo.
+ */
+const MAX_SUFFIX_SEGMENTS = 4;
+
+/** A symbol page's target is ``path::Name``; those are the interlinker's job. */
+function isPathLike(targetPath: string): boolean {
+ return targetPath.length > 0 && !targetPath.includes("::");
+}
+
+/**
+ * Normalise a path for lookup and indexing: no leading ``./``, no repeated or
+ * trailing slashes, no trailing glob. Prose writes `packages/ui/src/*` and
+ * `ingestion/resolvers/` for the same thing a target_path spells without either.
+ */
+export function normalizePath(raw: string): string {
+ return raw
+ .trim()
+ .replace(/^\.\//, "")
+ .replace(/\/+/g, "/")
+ .replace(/\/\*+$/, "")
+ .replace(/\/+$/, "");
+}
+
+/**
+ * True when an inline code span is plausibly a path at all.
+ *
+ * Inline code is also used for identifiers, flags and prose shorthand, and a
+ * bare word must never match a page. Requires either a slash with something
+ * after it, or a single filename carrying an extension — which is why `.NET`
+ * (no basename before the dot) and `chat` are rejected while `spec.py` is not.
+ */
+export function looksLikePath(anchor: string): boolean {
+ if (!anchor || anchor.length > 200) return false;
+ if (/\s/.test(anchor)) return false;
+ if (/\/[^/]/.test(anchor)) return true;
+ return /^[\w.-]*[\w-]\.[a-zA-Z0-9]{1,6}$/.test(anchor);
+}
+
+/** Register a suffix, tombstoning it as ambiguous if a different page claims
+ * it. Once ambiguous it stays ambiguous — a third claimant changes nothing. */
+function addSuffix(
+ suffix: Map<string, PathTarget | null>,
+ key: string,
+ target: PathTarget,
+): void {
+ if (!suffix.has(key)) {
+ suffix.set(key, target);
+ return;
+ }
+ const existing = suffix.get(key);
+ if (existing && existing.pageId !== target.pageId) suffix.set(key, null);
+}
+
+/**
+ * Build the lookup from the loaded page list.
+ *
+ * Linear in total path segments and memoized by the caller on the page list,
+ * so it runs once per repo rather than once per render.
+ */
+export function buildPathIndex(pages: readonly PathIndexablePage[]): PathIndex {
+ const exact = new Map<string, PathTarget>();
+ const suffix = new Map<string, PathTarget | null>();
+
+ for (const page of pages) {
+ const raw = page.target_path;
+ if (typeof raw !== "string" || !isPathLike(raw)) continue;
+ const path = normalizePath(raw);
+ if (!path) continue;
+
+ const target: PathTarget = { pageId: page.id, path };
+ // First page to claim a path keeps it. Duplicates are a generator bug,
+ // not something to surface in the reader.
+ if (!exact.has(path)) exact.set(path, target);
+
+ const segments = path.split("/");
+ const start = Math.max(1, segments.length - MAX_SUFFIX_SEGMENTS);
+ for (let i = start; i < segments.length; i++) {
+ addSuffix(suffix, segments.slice(i).join("/"), target);
+ }
+ }
+
+ return { exact, suffix };
+}
+
+/**
+ * Resolve one inline ref. Returns null for anything that is not a path, is
+ * unknown, or is ambiguous.
+ */
+export function resolvePath(
+ index: PathIndex,
+ anchor: string,
+): PathTarget | null {
+ if (!looksLikePath(anchor)) return null;
+ const path = normalizePath(anchor);
+ if (!path) return null;
+ const hit = index.exact.get(path);
+ if (hit) return hit;
+ return index.suffix.get(path) ?? null;
+}
+
+/**
+ * Shorten a long path for display, keeping the end.
+ *
+ * The informative part of `packages/core/src/repowise/core/ingestion/models.py`
+ * is the tail; the head is the same on every path in the repo and, rendered at
+ * full length inline, it breaks the line rhythm of the paragraph around it.
+ * The full path stays available as the link's title.
+ *
+ * Returns the head to be dimmed and the tail to be shown at full strength, so
+ * the caller can style them differently without re-parsing.
+ */
+export function elidePath(
+ path: string,
+ maxLength = 34,
+ keepSegments = 2,
+): { head: string; tail: string } {
+ if (path.length <= maxLength) return { head: "", tail: path };
+ const segments = path.split("/");
+ if (segments.length <= keepSegments) return { head: "", tail: path };
+
+ const tail = segments.slice(-keepSegments).join("/");
+ // A tail that is already over budget means the basename itself is long;
+ // eliding further would cost the only part worth reading.
+ return { head: `${segments[0]}/…/`, tail };
+}
diff --git a/packages/ui/src/wiki/wiki-markdown.tsx b/packages/ui/src/wiki/wiki-markdown.tsx
index 73177f15e..ffbd2c5bd 100644
--- a/packages/ui/src/wiki/wiki-markdown.tsx
+++ b/packages/ui/src/wiki/wiki-markdown.tsx
@@ -12,6 +12,13 @@ import {
type WikiLinkKind,
type WikiLinkRef,
} from "./wiki-links-types";
+import {
+ buildPathIndex,
+ elidePath,
+ resolvePath,
+ type PathIndex,
+ type PathIndexablePage,
+} from "./path-index";
/**
* Resolves an inline backtick ref to an internal wiki page href, or null
@@ -112,6 +119,8 @@ function ClientCodeBlock({ code, language }: { code: string; language: string })
function buildComponents(
resolveLink: WikiLinkLookup | null,
LinkComponent: WikiLinkComponent,
+ pathIndex: PathIndex,
+ buildPathHref: ((pageId: string) => string) | undefined,
): Components {
const Link = LinkComponent;
return {
@@ -174,26 +183,49 @@ function buildComponents(
return <ClientCodeBlock code={trimmed} language={lang} />;
}
- // Inline code: if the ref resolves to a known wiki page, render it as
- // a clickable internal link instead of a dead code span. We already
- // computed these targets in interlinking.py — just surface them.
+ // Inline code. Two states, and they have to look different:
+ //
+ // live — resolves to a page in this wiki. A faint ground, primary ink,
+ // accent only on hover.
+ // dead — nothing behind it. Plain mono in tertiary ink, no ground.
+ //
+ // Previously both rendered in full-saturation accent, which turned a list
+ // of file paths into a wall of orange and made the clickable ones no more
+ // clickable-looking than the rest. Decorating only what you can follow
+ // inverts that: the loud thing on the page is the thing that does
+ // something.
const text = typeof children === "string" ? children : extractText(children);
- const resolved = resolveLink ? resolveLink(text.trim()) : null;
- if (resolved) {
+ const anchor = text.trim();
+ // The interlinker's own resolutions win — it can resolve symbols and page
+ // titles, which the path index deliberately does not attempt.
+ const linked = resolveLink ? resolveLink(anchor) : null;
+ const viaPath = linked ? null : resolvePath(pathIndex, anchor);
+ const href = linked?.href ?? (viaPath ? buildPathHref?.(viaPath.pageId) : undefined);
+
+ if (href) {
+ const full = viaPath?.path ?? anchor;
+ const { head, tail } = elidePath(full);
return (
<Link
- href={resolved.href}
- title={`Go to ${text.trim()}`}
- className="rounded bg-[var(--color-accent-muted)] px-1.5 py-0.5 text-[0.85em] font-mono text-[var(--color-accent-primary)] underline decoration-dotted underline-offset-2 hover:bg-[var(--color-accent-primary)] hover:text-white transition-colors"
+ href={href}
+ title={full}
+ className="rounded bg-[color-mix(in_srgb,var(--color-text-primary)_6%,transparent)] px-1.5 py-0.5 text-[0.85em] font-mono whitespace-nowrap text-[var(--color-text-primary)] transition-colors hover:bg-[var(--color-accent-muted)] hover:text-[var(--color-accent-primary)] hover:underline hover:underline-offset-2"
>
- {children}
+ {head ? (
+ <>
+ <span className="opacity-55">{head}</span>
+ {tail}
+ </>
+ ) : (
+ children
+ )}
</Link>
);
}
return (
<code
- className="rounded bg-[var(--color-bg-elevated)] px-1.5 py-0.5 text-[0.85em] font-mono text-[var(--color-accent-primary)]"
+ className="text-[0.85em] font-mono text-[var(--color-text-tertiary)]"
{...props}
>
{children}
@@ -272,6 +304,12 @@ interface WikiMarkdownProps {
buildHref?: (pageId: string, kind: WikiLinkKind) => string;
/** Router-aware link (e.g. Next.js ``Link``). Defaults to a plain ``<a>``. */
LinkComponent?: WikiLinkComponent;
+ /**
+ * The loaded page list, used to resolve inline path refs the backend's
+ * interlinking pass left unresolved. Omit it and those refs simply render
+ * as plain code spans, exactly as before.
+ */
+ pages?: readonly PathIndexablePage[];
}
export function WikiMarkdown({
@@ -279,7 +317,12 @@ export function WikiMarkdown({
wikiLinks,
buildHref,
LinkComponent = "a",
+ pages,
}: WikiMarkdownProps) {
+ // Keyed on the page list identity: the reader loads it once per repo, so
+ // this runs once rather than on every content change.
+ const pathIndex = useMemo(() => buildPathIndex(pages ?? []), [pages]);
+
const components = useMemo(() => {
let resolveLink: WikiLinkLookup | null = null;
if (wikiLinks && wikiLinks.length > 0 && buildHref) {
@@ -290,8 +333,12 @@ export function WikiMarkdown({
return { href: buildHref(hit.pageId, hit.kind), kind: hit.kind };
};
}
- return buildComponents(resolveLink, LinkComponent);
- }, [wikiLinks, buildHref, LinkComponent]);
+ // Path hits are always file-kind by construction.
+ const buildPathHref = buildHref
+ ? (pageId: string) => buildHref(pageId, "file")
+ : undefined;
+ return buildComponents(resolveLink, LinkComponent, pathIndex, buildPathHref);
+ }, [wikiLinks, buildHref, LinkComponent, pathIndex]);
// Parsing + reconciling a large markdown document is the dominant cost when a
// page opens. Memoize the rendered tree on (content, components) so unrelated
diff --git a/packages/ui/styles/globals.css b/packages/ui/styles/globals.css
index df79e7ff4..e543d4a98 100644
--- a/packages/ui/styles/globals.css
+++ b/packages/ui/styles/globals.css
@@ -338,26 +338,37 @@
.dark {
/* Neutral graphite base — a true dark gray (near-zero hue) so nothing reads
blue, green, or plum. The surface ramp climbs root -> surface -> elevated
- -> overlay with wide steps so the sidebar, breadcrumb bar, cards, tables,
- and modals all read as distinct layers off the same tokens. Light mode is
- unchanged. */
- --color-bg-root: #1a1a1b;
- --color-bg-surface: #232325;
- --color-bg-elevated: #2b2c2e;
- --color-bg-overlay: #343539;
- --color-bg-inset: #141415;
-
- /* Neutral hairlines so card / sidebar / table edges read on the gray base. */
- --color-border-default: rgba(255, 255, 255, 0.1);
- --color-border-hover: rgba(255, 255, 255, 0.18);
+ -> overlay so the sidebar, breadcrumb bar, cards, tables and modals all
+ read as distinct layers off the same tokens. Light mode is unchanged.
+
+ The whole ramp sits lower than it used to (root was #1a1a1b, surface
+ #232325). Two reasons. Reading surfaces are the base plane, and on the
+ docs page the old values made the reading column the *darkest* of the
+ three panels, recessed between two lighter ones — a trench, which is the
+ opposite of how a reading UI should stack. And near-black gives the accent
+ and the semantic colours somewhere to go: the same #f59520 that looked
+ muddy on graphite carries on this ground. */
+ --color-bg-root: #0e0e0f;
+ --color-bg-surface: #141416;
+ --color-bg-elevated: #1c1c1f;
+ --color-bg-overlay: #26262a;
+ --color-bg-inset: #0a0a0b;
+
+ /* Neutral hairlines so card / sidebar / table edges read on the gray base.
+ Lighter than before: the same alpha reads considerably louder against
+ near-black, and at 0.10 every border on the page started shouting. */
+ --color-border-default: rgba(255, 255, 255, 0.07);
+ --color-border-hover: rgba(255, 255, 255, 0.15);
--color-border-active: rgba(245, 149, 32, 0.55);
- /* Neutral gray text (no plum / blue cast) to match the graphite chrome. */
- --color-text-primary: #ececed;
- --color-text-secondary: #a2a2a6;
- --color-text-tertiary: #717176;
- --color-text-inverse: #1a1a1b;
- --color-text-on-accent: #1a1a1b;
+ /* Neutral gray text (no plum / blue cast) to match the graphite chrome.
+ Secondary carries body copy and is lifted the most — on the old ground it
+ was grey-on-grey and read flat at any length. */
+ --color-text-primary: #f2f2f3;
+ --color-text-secondary: #b4b4b9;
+ --color-text-tertiary: #7c7c82;
+ --color-text-inverse: #0e0e0f;
+ --color-text-on-accent: #0e0e0f;
--color-accent-primary: #f59520;
--color-accent-fill: #f59520;
@@ -405,10 +416,13 @@
--color-diagram-cluster-border: #a98fc4;
--color-diagram-grid: rgba(222, 210, 235, 0.05);
- /* Zoom canvas — dark: elevated graphite cards on the near-black canvas. */
- --color-zoom-card-fill: #2b2c2e; /* leaf card (bg-elevated) */
- --color-zoom-card-fill-2: #232325; /* container card (bg-surface) */
- --color-zoom-card-text: #ececed;
+ /* Zoom canvas — dark: elevated graphite cards on the near-black canvas.
+ These are literals rather than var() references because the canvas
+ renderer reads them into WebGL, but they have to move with the surface
+ ramp or the cards float above a ground that has dropped beneath them. */
+ --color-zoom-card-fill: #1c1c1f; /* leaf card (bg-elevated) */
+ --color-zoom-card-fill-2: #141416; /* container card (bg-surface) */
+ --color-zoom-card-text: #f2f2f3;
--color-zoom-card-border: rgba(255, 255, 255, 0.10);
--color-zoom-card-border-hover: rgba(255, 255, 255, 0.20);
--color-zoom-card-shadow: rgba(0, 0, 0, 0.45);
@@ -453,8 +467,9 @@
--shadow-xl: 0 16px 48px rgba(0, 0, 0, 0.6), inset 0 0 0 1px rgba(255, 255, 255, 0.07);
--shadow-button: 0 1px 2px rgba(0, 0, 0, 0.4);
- /* Dark soft wash — neutral graphite with a faint lift at the end */
- --gradient-warm-wash: linear-gradient(160deg, #1c1c1e 0%, #232325 55%, #2c2c2f 100%);
+ /* Dark soft wash — neutral graphite with a faint lift at the end. Tracks the
+ surface ramp: the wash reads as a lit panel only if it starts at the base. */
+ --gradient-warm-wash: linear-gradient(160deg, #101012 0%, #16161a 55%, #1f1f23 100%);
}
/* -------------------------------------------------------------------- */
diff --git a/packages/web/src/components/docs/docs-explorer.tsx b/packages/web/src/components/docs/docs-explorer.tsx
index ad2f0943e..b30236cd4 100644
--- a/packages/web/src/components/docs/docs-explorer.tsx
+++ b/packages/web/src/components/docs/docs-explorer.tsx
@@ -47,7 +47,14 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
if (typeof window === "undefined") return true;
return window.matchMedia("(min-width: 768px)").matches;
});
- const [sidebarOpen, setSidebarOpen] = useState(true);
+ // The rail defaults to whether the layout can afford it, not to `true`.
+ // Mirrors the 2xl breakpoint the reader uses to place its sections; a manual
+ // toggle wins from then on, same contract as the app sidebar's route-based
+ // collapse.
+ const [sidebarOpen, setSidebarOpen] = useState(() => {
+ if (typeof window === "undefined") return true;
+ return window.matchMedia("(min-width: 1536px)").matches;
+ });
const [searchOpen, setSearchOpen] = useState(false);
const [isExporting, setIsExporting] = useState(false);
const searchParams = useSearchParams();
@@ -182,11 +189,26 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
}
}, [pages]);
- let body: React.ReactNode;
- if (isLoading) {
- body = (
- <div className="flex h-full">
- <div className="w-full md:w-[300px] border-r border-[var(--color-border-default)] p-3 space-y-2">
+ // 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
+ // too, so the layout does not reflow once the pages land.
+ const treePanel = (
+ // No right border. Tree, reading column and rail sit on one plane and are
+ // separated by space; a rule on each side of the reading column made it
+ // read as a trench between two panels.
+ // Below md the tree is a drawer over the reader, not a column beside it.
+ // As a column it would claim the full width and starve the header column
+ // it now sits next to, squashing the view switch into a few pixels.
+ <div
+ className={cn(
+ "bg-[var(--color-bg-surface)] transition-all duration-200 shrink-0 overflow-y-auto",
+ treePanelOpen
+ ? "absolute inset-y-0 left-0 z-30 w-full md:static md:w-[288px]"
+ : "w-0 overflow-hidden",
+ )}
+ >
+ {isLoading ? (
+ <div className="space-y-2 p-3">
<Skeleton className="h-8 w-full rounded-md" />
<Skeleton className="h-4 w-3/4 rounded" />
<Skeleton className="h-4 w-1/2 rounded" />
@@ -195,9 +217,29 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
<Skeleton className="h-4 w-3/4 rounded" />
<Skeleton className="h-4 w-1/2 rounded" />
</div>
- <div className="flex-1 flex items-center justify-center">
- <Skeleton className="h-8 w-48 rounded" />
- </div>
+ ) : (
+ <DocsTree
+ pages={pages}
+ selectedPageId={selectedPage?.id ?? null}
+ 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);
+ if (typeof window !== "undefined" && !window.matchMedia("(min-width: 768px)").matches) {
+ setTreePanelOpen(false);
+ }
+ }}
+ />
+ )}
+ </div>
+ );
+
+ 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) {
@@ -218,108 +260,91 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
);
} else {
body = (
- <div className="relative flex h-full">
- {/* Tree sidebar */}
- <div
- className={cn(
- "border-r border-[var(--color-border-default)] bg-[var(--color-bg-surface)] transition-all duration-200 shrink-0 relative",
- treePanelOpen ? "w-full md:w-[300px]" : "w-0 overflow-hidden border-r-0",
- )}
- >
- <DocsTree
- pages={pages}
- selectedPageId={selectedPage?.id ?? null}
- 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);
- if (typeof window !== "undefined" && !window.matchMedia("(min-width: 768px)").matches) {
- setTreePanelOpen(false);
- }
- }}
- />
- </div>
-
- {/* Toggle button */}
- <button
- onClick={() => setTreePanelOpen((o) => !o)}
- aria-label={treePanelOpen ? "Hide pages tree" : "Show pages tree"}
- aria-expanded={treePanelOpen}
- className={cn(
- "absolute top-3 z-20 rounded-r-md border border-l-0 border-[var(--color-border-default)] bg-[var(--color-bg-surface)] p-1 text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-bg-elevated)] transition-colors",
- treePanelOpen ? "hidden md:block left-[300px]" : "left-0",
- )}
- >
- {treePanelOpen ? (
- <PanelLeftClose className="h-3.5 w-3.5" />
- ) : (
- <PanelLeft className="h-3.5 w-3.5" />
- )}
- </button>
-
- {/* Viewer */}
- <div className={cn("flex-1 min-w-0", treePanelOpen ? "hidden md:block" : "block")}>
- <DocsViewer
- page={selectedPage}
- pages={pages}
- repoId={repoId}
- onSelectPage={handleSelectPage}
- persona={persona}
- sidebarOpen={sidebarOpen}
- onGenerated={handleGenerated}
- />
- </div>
+ <div className="h-full min-w-0">
+ <DocsViewer
+ page={selectedPage}
+ pages={pages}
+ repoId={repoId}
+ onSelectPage={handleSelectPage}
+ persona={persona}
+ sidebarOpen={sidebarOpen}
+ onGenerated={handleGenerated}
+ />
</div>
);
}
+ // Tree beside the chrome, not under it. The header used to span the full
+ // width, which pushed the tree down by its height on every screen and cost
+ // that much of the list for a bar that says "Documentation" on a page whose
+ // route is already /docs. The tree now starts at the top and the bar sits to
+ // the right of it, over the reading column it actually acts on.
return (
- <div className="flex flex-col h-full">
- <DocsHeader>
- {selectedPage && (
- <DocsPageActions
- page={selectedPage}
- persona={persona}
- setPersona={setPersona}
- personaHasEffect={personaHasEffect}
- />
+ <div className="relative flex h-full">
+ {treePanel}
+
+ <button
+ onClick={() => setTreePanelOpen((o) => !o)}
+ aria-label={treePanelOpen ? "Hide pages tree" : "Show pages tree"}
+ aria-expanded={treePanelOpen}
+ className={cn(
+ "absolute top-3.5 z-20 rounded-md p-1 text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-bg-elevated)] transition-colors",
+ treePanelOpen ? "hidden md:block left-[292px]" : "left-1",
+ )}
+ >
+ {treePanelOpen ? (
+ <PanelLeftClose className="h-3.5 w-3.5" />
+ ) : (
+ <PanelLeft className="h-3.5 w-3.5" />
)}
- {selectedPage && isModelWrittenType(selectedPage.page_type) && (
- <PageGenerateButton
+ </button>
+
+ <div className="flex flex-1 min-w-0 flex-col">
+ <DocsHeader>
+ {selectedPage && (
+ <DocsPageActions
+ page={selectedPage}
+ persona={persona}
+ setPersona={setPersona}
+ personaHasEffect={personaHasEffect}
+ />
+ )}
+ {selectedPage && isModelWrittenType(selectedPage.page_type) && (
+ <PageGenerateButton
+ page={selectedPage}
+ repoId={repoId}
+ onGenerated={handleGenerated}
+ />
+ )}
+ {hasStubs && <BulkGenerateButton repoId={repoId} onGenerated={handleGenerated} />}
+ <button
+ onClick={() => setSearchOpen(true)}
+ className="flex items-center gap-2 rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] px-2.5 py-1.5 text-xs text-[var(--color-text-tertiary)] transition-colors hover:text-[var(--color-text-secondary)]"
+ >
+ <Search className="h-3.5 w-3.5" />
+ <span className="hidden sm:inline">Search</span>
+ <kbd className="hidden rounded border border-[var(--color-border-default)] px-1 py-0.5 text-[10px] sm:inline">
+ ⌘K
+ </kbd>
+ </button>
+ <ExportMenu
+ isExporting={isExporting}
+ onExportAll={handleExportAll}
+ zipHref={`/api/repos/${repoId}/export`}
page={selectedPage}
repoId={repoId}
- onGenerated={handleGenerated}
/>
- )}
- {hasStubs && <BulkGenerateButton repoId={repoId} onGenerated={handleGenerated} />}
- <button
- onClick={() => setSearchOpen(true)}
- className="flex items-center gap-2 rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] px-2.5 py-1.5 text-xs text-[var(--color-text-tertiary)] transition-colors hover:text-[var(--color-text-secondary)]"
- >
- <Search className="h-3.5 w-3.5" />
- <span className="hidden sm:inline">Search</span>
- <kbd className="hidden rounded border border-[var(--color-border-default)] px-1 py-0.5 text-[10px] sm:inline">
- ⌘K
- </kbd>
- </button>
- <ExportMenu
- isExporting={isExporting}
- onExportAll={handleExportAll}
- zipHref={`/api/repos/${repoId}/export`}
- page={selectedPage}
- repoId={repoId}
- />
- {presentable && <PresentButton onClick={() => setPresent("deck")} />}
- {selectedPage && (
- <SidebarToggle
- open={sidebarOpen}
- onToggle={() => setSidebarOpen((o) => !o)}
- />
- )}
- </DocsHeader>
+ {presentable && <PresentButton onClick={() => setPresent("deck")} />}
+ {selectedPage && (
+ <SidebarToggle
+ open={sidebarOpen}
+ onToggle={() => setSidebarOpen((o) => !o)}
+ />
+ )}
+ </DocsHeader>
- <div className="flex-1 min-h-0">{body}</div>
+ <div className="flex-1 min-h-0">{body}</div>
+ </div>
{/* Present mode overlay — full-screen, escapes the dashboard chrome */}
{presentMode && presentModel && (
diff --git a/packages/web/src/components/docs/docs-viewer.tsx b/packages/web/src/components/docs/docs-viewer.tsx
index 55aed1507..a665d9684 100644
--- a/packages/web/src/components/docs/docs-viewer.tsx
+++ b/packages/web/src/components/docs/docs-viewer.tsx
@@ -3,14 +3,7 @@
import { useCallback } from "react";
import Link from "next/link";
import useSWR from "swr";
-import {
- Activity,
- Network,
- GitBranch,
- ArrowRight,
- Flame,
- Bug,
-} from "lucide-react";
+import { ArrowRight, Flame, Bug } from "lucide-react";
import { cn } from "@/lib/utils/cn";
import { getGitMetadata } from "@/lib/api/git";
import { summarizeFixHistory } from "@repowise-dev/ui/lib/fix-history";
@@ -74,14 +67,9 @@ function DocsSidebar({ repoId, targetPath }: { repoId: string; targetPath: strin
return (
<div className="space-y-4">
- {/* Graph Metrics */}
+ {/* Graph importance. No section header of its own — the rail groups these
+ under one "Signals" label, so the rows speak for themselves. */}
<div>
- <div className="flex items-center gap-1.5 mb-2">
- <Activity className="h-3 w-3 text-[var(--color-text-tertiary)]" />
- <span className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider">
- Importance
- </span>
- </div>
<div className="space-y-2">
<PercentileBar value={metrics.pagerank_percentile} label="PageRank" />
<PercentileBar value={metrics.betweenness_percentile} label="Centrality" />
@@ -97,21 +85,17 @@ function DocsSidebar({ repoId, targetPath }: { repoId: string; targetPath: strin
</div>
</div>
- {/* Community */}
+ {/* Community — a single value, so it renders as a labelled row like the
+ rest rather than as its own titled section. */}
{metrics.community_label && (
- <div>
- <div className="flex items-center gap-1.5 mb-2">
- <Network className="h-3 w-3 text-[var(--color-text-tertiary)]" />
- <span className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider">
- Community
- </span>
- </div>
+ <div className="flex items-center justify-between gap-2">
+ <span className="text-xs text-[var(--color-text-tertiary)]">Community</span>
<Link
href={`/repos/${repoId}/architecture?view=graph&colorMode=community`}
- className="inline-flex items-center gap-1 text-xs text-[var(--color-accent)] hover:underline"
+ className="inline-flex items-center gap-1 truncate text-xs text-[var(--color-accent)] hover:underline"
>
{metrics.community_label}
- <ArrowRight className="h-2.5 w-2.5" />
+ <ArrowRight className="h-2.5 w-2.5 shrink-0" />
</Link>
</div>
)}
@@ -119,12 +103,6 @@ function DocsSidebar({ repoId, targetPath }: { repoId: string; targetPath: strin
{/* Callers/Callees (for symbol pages) */}
{callData && (callData.caller_count > 0 || callData.callee_count > 0) && (
<div>
- <div className="flex items-center gap-1.5 mb-2">
- <GitBranch className="h-3 w-3 text-[var(--color-text-tertiary)]" />
- <span className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider">
- Call Graph
- </span>
- </div>
{callData.caller_count > 0 && (
<div className="mb-2">
<p className="text-[10px] text-[var(--color-text-tertiary)] mb-1">Called by ({callData.caller_count})</p>
@@ -179,12 +157,8 @@ function AtAGlance({ repoId, targetPath }: { repoId: string; targetPath: string
);
return (
<div>
- <div className="flex items-center gap-1.5 mb-2">
- <Flame className="h-3 w-3 text-[var(--color-text-tertiary)]" />
- <span className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider">
- At a glance
- </span>
- </div>
+ {/* Leads the Signals list: the chips are the fastest read on the page,
+ and they carry their own meaning without a header over them. */}
<div className="flex flex-wrap gap-1.5">
{data.is_hotspot && (
<Badge variant="outline" className="text-[10px] border-[var(--color-warning)]/40 text-[var(--color-warning)]">
@@ -352,18 +326,23 @@ export function DocsViewer({
}
intelligenceSlot={
hasTargetPath ? (
- <>
- <AtAGlance repoId={repoId} targetPath={targetPath} />
- <DocsSidebar repoId={repoId} targetPath={targetPath} />
- {isFilePath && (
- <div>
- <p className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider mb-2">
- Security signals
- </p>
+ // One "Signals" block, not five. At a glance, Importance, Community,
+ // Call graph and Security each announced themselves with their own
+ // uppercase label over a handful of rows, so the rail was mostly
+ // label. They answer one question between them — what should I know
+ // about this code before I touch it — so they read as one list.
+ <div>
+ <p className="mb-2.5 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">
+ Signals
+ </p>
+ <div className="flex flex-col gap-4">
+ <AtAGlance repoId={repoId} targetPath={targetPath} />
+ <DocsSidebar repoId={repoId} targetPath={targetPath} />
+ {isFilePath && (
<SecurityPanelWrapper repoId={repoId} filePath={targetPath} />
- </div>
- )}
- </>
+ )}
+ </div>
+ </div>
) : undefined
}
/>