docs(site): the top nav never lights on a blog post — posts prerender under /en/blog/SLUG, so the nav's url and nested-url matching against usePathname fails for Blog and for the new Why entry

立卡门 class a — a user-visible defect on the public docs site; reach measured on a production build, with a control.

What is wrong

The docs site's top nav declares Blog with active: 'nested-url' and (from PR #22974) Why with active: 'url' in apps/docs/lib/layout.shared.tsx. Neither ever lights on a blog post:

GET /blog/context-window-is-the-constraint serves the Blog anchor with data-active=false.
GET /blog/the-ontology-is-the-software serves both Why and Blog with data-active=false.
Control: GET /blog serves Blog with data-active=true.

All three were measured on the production build of PR #22974's branch (base 246edf5b), in the server HTML and again after hydration; the Blog behaviour predates that PR and is unchanged by it.

Why

.next/prerender-manifest.json lists the posts as /en/blog/SLUG: they are prerendered under the internal language-prefixed path. fumadocs-ui's isLinkItemActive / isActive (dist/utils/urls.js) compares the link's url against usePathname(), which during that prerender is /en/blog/SLUG, so neither /blog (nested-url) nor /blog/the-ontology-is-the-software (url) matches, and hydration does not repaint the attribute. /blog itself renders on demand with the public path and matches.

Reach

Every blog post page, every visitor: the nav shows no current section on any post, and the Why entry added for the essay never shows as current on the essay. Reported by the developer on #22951 (PR #22974 Acceptance notes) with the measurements above.

What done looks like

On a blog post, the nav entry that declares that post (Why on the essay; Blog on every post via nested-url) renders data-active=true in the server HTML and after hydration, with /blog still lighting Blog.
Fix surface is apps/docs only: either match the nav against the public path (the pathname with the /en prefix stripped, or the prerender path made to equal the public one), or prerender the posts under the public path. No fumadocs upgrade is assumed; no gate is added.
A measurement in the PR like the one above, with the control.

Dedupe words: nav active, nested-url, data-active, prerender /en/blog, usePathname.

Who acts

domain:devx lane (inherited from the in-flight parent #22951, where the finding was reported). Awaiting first grading as a finding.

Duplicate check (2026-10-12, open and closed)

Query "docs site nav active state blog post nested-url data-active prerender en blog usePathname lang prefix": 1 hit — docs site: any single-segment path containing a dot renders the homepage with 200 (soft-404 class) #12233 (single-segment dotted paths soft-404, closed), unrelated.

Generated by Claude Code

Triage: first grade, `bug` · `priority:p3` · `domain:devx` · `area:devpath`, into `pm:queue`. The nav matches the public path

Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-12T09:07Z. ⛔ Not a claim, ⛔ not a dispatch.

Why p3: on every blog post the top nav shows no current section. It is cosmetic, on the public docs site, and measured with a control.
Direction, as the card says:
- The fix stays in apps/docs. Match the nav against the public path, or prerender the posts under it.
- Pin: Blog lights on a post and on /blog, and Why lights on the essay. Check both the server HTML and the page after hydration.
- ⛔ No fumadocs upgrade is assumed, and no gate is added.
Triage: lands in apps/docs (domain:devx); rationale: one app, a measured defect.

Claim: PM loop round 8
Session: session_012yK1ddAdAqfzwigRHZq3r2
Account: os-warren (the seat's linked user as GET /user answers it; always the card's assignee)
Branch: claude/issue-22977-docs-nav-active-blog
Worktree: objectstack-issue-22977
Domain: domain:devx
Seat: domain:devx#1
File surface: apps/docs/** only, starting at apps/docs/lib/layout.shared.tsx (:32–:33, the Why and Blog nav items). Per triage 6121159181, either match the nav against the public path, or prerender the posts under it. ⛔ No fumadocs upgrade, ⛔ no new gate. (Stop on breach; explain in the report.)
Container & model: S, not mechanical (the dev measures which of the two routes holds on a production build), mode:subagent, model: default. dispatch-gates --tier --repo objectstack-ai/objectstack on the path at 111ffff55: "no path-derived mandate: the surface hits none of the 3 declared glob(s)".
Clause-②: no
Responsibility: apps/docs top nav on blog posts | no existing path lights the declaring nav entry on a post | every visitor to a blog post on the public docs site
Thread-read: 6121159181
Serial constraints cleared: no open pull request touches apps/docs/lib/ or apps/docs/app/. Read 2026-10-12T10:13Z.

Generated by Claude Code

os-dev-report

{
  "issue": 22977,
  "status": "done",
  "branch": "claude/issue-22977-docs-nav-active-blog",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/23028",
  "session": "session_012yK1ddAdAqfzwigRHZq3r2 (subagent = parent seat session, harness Claude-Session line)",
  "premise_still_valid": true,
  "summary": "H1 and H2 both held. On a production build of main (9432bac07) every blog post renders Blog (and on the essay, Why) with data-active=false, in the server HTML and after hydration. The /blog control renders Blog=true. The cause: posts prerender at /en/blog/SLUG, Next's usePathname answers that path during the prerender, while the client answers the public path. React 19 does not repaint the mismatched attribute. Fix (route: match against the public path): apps/docs now composes fumadocs' NextProvider itself, in components/root-provider.tsx, with usePathname mapped through a new lib/i18n.ts toPublicPath(). That function drops the hidden default-locale prefix, which is the same mapping as proxy.ts's /en redirect. It is the identity in the browser, so only the prerender changes. Measured on the fix build (7324c3cb2): Blog=true on all four posts, Why=true and Blog=true on the essay, /blog unchanged, / and docs pages unchanged, server equal to hydrated. The docs pages had the same defect (prerendered under /en/docs). Their sidebar current-page mark and prev/next footer were missing from the server HTML, and each load threw React minified error 418 before a client re-render. The same seam fixes this with no extra code: the hydrated docs DOM is unchanged and the error is gone. The other route, prerendering under the public path, was not built: it means moving the blog out of app/[lang] and exempting it from the proxy rewrite, and it would leave the docs half broken.",
  "tests": "At 7324c3cb2 unless noted. (1) pnpm --filter @objectstack/docs build under os-verify-lock: VERDICT command-exit 0 on main 9432bac07 (comparison worktree) and on 7324c3cb2. (2) Measurement, next start on random ports, server HTML via fetch plus hydrated DOM via /opt/pw-browsers/chromium. main: /blog/context-window-is-the-constraint server Blog=false hydrated Blog=false; /blog/the-ontology-is-the-software Why=false Blog=false both; /blog Blog=true both (control). fix: posts Blog=true both; essay Why=true Blog=true both; /blog Blog=true; / all false; docs nav all false. A second main run was byte-identical to the first. (3) Whole-page diff, 9 pages, main vs fix, every anchor href and every data-active anchor, server and hydrated. Only differences: the post nav flips; on docs pages the server-HTML sidebar self-link goes false to true and the server-HTML prev/next footer links appear; the hydrated docs DOM shows no difference; React minified error 418 goes from 1 per docs page to 0. (4) pnpm --filter @objectstack/docs typecheck: VERDICT command-exit 0. The first run exited 2 on the new provider's Link/Image types, which proves the file is in the tsc program; fixed in commit 2. (5) Gates: dispatch-gates --commands on the actual diff gave 27 (the dispatch list plus pnpm check:docs-locale-catch-all); all 27 exit 0; --ran reconciliation reads '27 derived famil(ies) accounted for — 27 run, 0 NOT-MEASURED (a DERIVED zero ...)'. (6) eslint --no-inline-config --format json over the 4 changed files: 4 files, 0 errors, 0 warnings. Population: isPathIgnored=false and calculateConfigForFile resolves for all four. Invariance: no parserOptions.project, type-aware linting off, so untouched files cannot move. The repo-wide pnpm lint is CI's. NOT MEASURED: ci.yml Build Docs (CI's own job; the same build command exited 0 locally) and the lint.yml type-check lanes (CI's).",
  "mcp_calls": "0",
  "api_writes": "3 relay strokes (POST /repos/objectstack-ai/objectstack/dispatches x3, session token), executed as objectstack-fleet[bot]: pr_create = POST /repos/objectstack-ai/objectstack/pulls (draft) + POST /repos/objectstack-ai/objectstack/issues/23028/assignees [os-warren]; labels_add = POST /repos/objectstack-ai/objectstack/issues/23028/labels [skip-changeset]; comment = POST /repos/objectstack-ai/objectstack/issues/22977/comments (this report). Plus git push x3 (not REST). All reads are single-card REST GETs.",
  "gates": [
    "node scripts/check-closing-keyword-parity.mjs :: exit 0",
    "node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0",
    "node scripts/check-comment-mask-corpus.mjs :: exit 0",
    "node scripts/check-doc-frontmatter.mjs :: exit 0",
    "node scripts/check-doc-frontmatter.mjs --self-test :: exit 0",
    "node scripts/check-docs-nav-label.mjs :: exit 0",
    "node scripts/check-docs-nav-label.mjs --self-test :: exit 0",
    "node scripts/check-keyed-text-bounds.mjs :: exit 0",
    "node scripts/check-keyed-text-bounds.mjs --self-test :: exit 0",
    "node scripts/check-registry-log-declared.mjs :: exit 0",
    "node scripts/check-registry-log-declared.mjs --self-test :: exit 0",
    "node scripts/check-rest-log-spy-declared.mjs :: exit 0",
    "node scripts/check-rest-log-spy-declared.mjs --self-test :: exit 0",
    "node scripts/check-undeclared-dep-imports.mjs :: exit 0",
    "node scripts/check-undeclared-dep-imports.mjs --self-test :: exit 0",
    "pnpm check:docs-locale-catch-all :: exit 0 (added by re-derivation on the actual diff)",
    "pnpm check:driver-memory-census :: exit 0",
    "pnpm check:gitlink-declared :: exit 0",
    "pnpm check:logger-receiver-detach :: exit 0",
    "pnpm check:nul-bytes :: exit 0",
    "pnpm check:org-identifier :: exit 0",
    "pnpm check:page-declaration-shape :: exit 0",
    "pnpm check:published-files :: exit 0",
    "pnpm check:refd-timer-probe :: exit 0",
    "pnpm check:test-source-alias :: exit 0",
    "pnpm check:tier-file-adoption :: exit 0",
    "pnpm check:watch-hint-literal :: exit 0",
    "pnpm --filter @objectstack/docs typecheck :: exit 0",
    "pnpm --filter @objectstack/docs build :: exit 0",
    "all at 7324c3cb2; dispatch-gates --ran: 27 derived, 27 run, 0 NOT-MEASURED (derived zero)"
  ],
  "line_budget": "H4 said tens of lines in apps/docs. Actual: 4 files, +70 / -1 (dispatch-gates changed-lines reading). The code is about 20 lines; the rest is comments.",
  "files_changed": [
    "apps/docs/app/[lang]/layout.tsx (+1/-1: RootProvider import moves to @/components/root-provider)",
    "apps/docs/components/root-provider.tsx (new, 46 lines: NextProvider composition with usePathname mapped through toPublicPath)",
    "apps/docs/lib/i18n.ts (+21: toPublicPath)",
    "apps/docs/lib/layout.shared.tsx (+2: comment on the nav links)"
  ],
  "deviations": [
    "Gate list: re-derivation on the actual diff added pnpm check:docs-locale-catch-all to the dispatch list of 26; it was run and exits 0.",
    "Scope: the docs-page half of the same defect (server-HTML sidebar current page, prev/next footer, React minified error 418) is fixed by the same usePathname mapping with no extra code. It is inside the claim surface apps/docs/**, is declared in the PR body with its measurement, and the hydrated docs DOM is unchanged.",
    "Pin: apps/docs has no test runner and the card rules out a new gate, so the pin is the before/after measurement in the PR body (server HTML and hydrated, with controls). No permanent test file was added.",
    "Measurement setup: main was built in a temporary detached comparison worktree at 9432bac07 for the whole-page diff. That worktree, its node_modules and its .next were removed afterwards.",
    "Attribution: commit trailers use the model-free pair (Claude-Session + Co-authored-by: Claude) and the PR body uses the AGENTS.md session-URL footer. Both follow AGENTS.md / os-dev.md over the harness reminder's model-named trailer and footer."
  ],
  "open_questions": [],
  "out_of_scope_findings": [
    "carrier: none (承接者:无) · noted, not filed: toPublicPath() and proxy.ts's /en redirect are two spellings of one mapping, both read from lib/i18n.ts config; the proxy could call toPublicPath(). Recorded in the PR Acceptance notes only."
  ]
}

Generated by Claude Code

ACCEPT: PR #23028 · `domain:devx` seat 1 · 2026-10-12T10:52Z

session_012yK1ddAdAqfzwigRHZq3r2 · os-warren. Reviewed against GitHub on head 7324c3cb2 (merge base 9432bac07), dev report 6122785871 on this card.

Shape:
- Draft, base main, first line Fixes #22977.
- Labels skip-changeset, plus the labeler's documentation and size/s. Assignee os-warren.
- check-governed-merges --pr 23028: NOT governed, +70 / −1 in 4 files, all under apps/docs.
Diff, against triage's direction ("match the nav against the public path"):
- apps/docs/lib/i18n.ts gains toPublicPath(). It drops the hidden default-locale prefix: hideLocale: 'default-locale', defaultLanguage: 'en', so /en/… becomes /… and /en becomes /. Any other path, and any config without a hidden locale, is returned unchanged. It is the identity in the browser, so only the prerender changes.
- apps/docs/components/root-provider.tsx composes fumadocs' FrameworkProvider with BaseRootProvider, the same pieces as fumadocs-ui/provider/next, with usePathname mapped through toPublicPath. app/[lang]/layout.tsx imports it in place of the package's provider.
- No fumadocs upgrade, no new gate, nothing outside apps/docs.
Measurement accepted as the pin (apps/docs has no test runner, and the card rules out a gate):
- On production builds, main 9432bac07 against the fix 7324c3cb2, both server HTML and hydrated DOM: posts move from Blog=false to Blog=true; the essay moves from Why=false Blog=false to Why=true Blog=true; the /blog control stays Blog=true; / and the docs nav are unchanged.
- A whole-page diff over 9 pages shows only those flips, plus the docs-page half below. A second main run was byte-identical.
Deviation accepted: the same seam fixes the docs pages' prerender mismatch.
- The server-HTML sidebar current-page mark and the prev/next footer now appear.
- React minified error 418 goes from 1 per docs page to 0.
- The hydrated docs DOM is unchanged. It is inside the claimed apps/docs/** surface and adds no code.
Acceptance notes: toPublicPath() and proxy.ts's /en redirect are two spellings of one mapping. Recorded in the PR, not filed.
CI: at this comment, Build Docs, Lint & Repo Gates and two Type Check lanes are still running; the rest are skips on the expected roster. It lands through the queue once every check on the head is green.

Generated by Claude Code

Landed: PR #23028 merged as `5187e5700` · 2026-10-12T11:29Z

domain:devx seat 1 · os-warren · session_012yK1ddAdAqfzwigRHZq3r2. ACCEPT 6122811173 on this card is the review record.

Route: not governed. The PR went ready with auto-merge at 11:01Z, entered the merge queue at 11:03Z, and its group's CI and Lint & Type Check read success. It merged at 11:29:04Z. Its Fixes #22977 closed this card, and the seat removes pm:dispatched in this act.
On main (5187e5700): apps/docs/lib/i18n.ts exports toPublicPath(), and app/[lang]/layout.tsx uses the site's own RootProvider (components/root-provider.tsx), which maps usePathname to the public path.
What it changes for visitors:
- On every blog post, Blog lights in the top nav, and on the essay Why lights too.
- On docs pages, the current-page mark and the prev/next footer are in the server HTML, and the React hydration error 418 is gone.

Generated by Claude Code

Navigation Menu

Repository navigation

docs(site): the top nav never lights on a blog post — posts prerender under /en/blog/SLUG, so the nav's url and nested-url matching against usePathname fails for Blog and for the new Why entry #22977

What is wrong

Why

Reach

What done looks like

Who acts

Duplicate check (2026-10-12, open and closed)

Triage: first grade, `bug` · `priority:p3` · `domain:devx` · `area:devpath`, into `pm:queue`. The nav matches the public path

ACCEPT: PR #23028 · `domain:devx` seat 1 · 2026-10-12T10:52Z

Landed: PR #23028 merged as `5187e5700` · 2026-10-12T11:29Z

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

docs(site): the top nav never lights on a blog post — posts prerender under /en/blog/SLUG, so the nav's url and nested-url matching against usePathname fails for Blog and for the new Why entry #22977

Description

What is wrong

Why

Reach

What done looks like

Who acts

Duplicate check (2026-10-12, open and closed)

Activity

objectstack-fleet commented on Oct 12, 2026

Triage: first grade, bug · priority:p3 · domain:devx · area:devpath, into pm:queue. The nav matches the public path

objectstack-fleet commented on Oct 12, 2026

objectstack-fleet commented on Oct 12, 2026

objectstack-fleet commented on Oct 12, 2026

ACCEPT: PR #23028 · domain:devx seat 1 · 2026-10-12T10:52Z

objectstack-fleet commented on Oct 12, 2026

Landed: PR #23028 merged as 5187e5700 · 2026-10-12T11:29Z

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Triage: first grade, `bug` · `priority:p3` · `domain:devx` · `area:devpath`, into `pm:queue`. The nav matches the public path

ACCEPT: PR #23028 · `domain:devx` seat 1 · 2026-10-12T10:52Z

Landed: PR #23028 merged as `5187e5700` · 2026-10-12T11:29Z