You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The repository's guides now live at apps/docs/content/docs and the site
reads those exact files. Package README symlinks under content/reference
do the same for the eleven package docs, so nothing is copied.
- Add apps/* to the pnpm workspace, and exclude apps/* from the root
build, dev, and build:types filters. Without that, pnpm build would
boot a GraphQL server and run next build inside the library build,
which every CI job and pnpm test depend on.
- Add frontmatter (id, title, section, order, summary, related) to the
seven guides so Flatbread can validate ids and order the navigation.
- Repair every link that pointed at the old docs/ path.
- Add five markdown plugins the site runs through Flatbread's transformer:
strip the leading H1, carry code fence titles, rewrite repo links to
site routes, add heading anchors, and colour code with Shiki.
Change-Id: I472065d89b0b2b3ecd7752eebe81877d4151c992
The site at apps/docs renders every guide and package README through
Flatbread's GraphQL server while it builds, then exports 22 static files.
Nothing calls a server once the build is done.
Interface: a terminal document. One monospaced family, widths counted in
character cells, every vertical step one line high, two tones and a
single accent taken from the Flatbread mark. Panels use one-pixel borders
with box-drawing characters at the corners so they hold their shape at
any width; the navigation is a real directory tree, where the connectors
never have to stretch.
Motion: the hero resolves out of punctuation one cell at a time, page
titles assemble character by character, the caret marking the current
page slides between rows, and the content column repaints on navigation.
Every one of those checks useReducedMotion first and renders its final
state instead.
Motion's splitText belongs to Motion+, which installs from a private
registry with a secret token, so the site splits text itself. The whole
string stays in aria-label and each piece is inline-block.
Also adds search (scored in the browser, since Flatbread ranks nothing),
a table of contents read from the rendered HTML, copy buttons added to
code blocks after mount, a link checker that fails the build on a broken
cross-reference, and an Ubuntu-only CI job.
Change-Id: Ic1a52e34ab701be06bceeff57c5b3ea5cc6df1d9
On a phone the tree pushed the page eighteen links down. It now sits
behind a 'pages' toggle below 900px and stays open above it. The open
state follows a media query, because the reliable way to force a
<details> open across browsers is still the open attribute.
Also records what this exercise found in the Proof: one retrospective
Finding listing six limits in the content model, two Issues for the real
defects (a content path cannot climb above the project directory, and
initial load disagrees with watch mode about capture patterns), and one
Constraint explaining why the site cannot depend on Motion+.
Change-Id: I8804bdab70b945675e0fe70cac889f8478883863
cursorBot
changed the title
Toeknee/docs site ascii c1d8
Docs site built on Flatbread, reading the repo's own Markdown
Aug 12, 2026
svimg 3.1 and 3.2 pull sharp 0.30 and 0.31. Those versions download a
prebuilt binary, and on a socket hang-up they fall back to node-gyp.
windows-latest ships Visual Studio 18, which node-gyp 11 does not
recognise, so the fallback always fails.
sharp 0.34 ships platform packages as optional npm dependencies and has
no compile path. One workspace override replaces every copy. svimg only
calls metadata, resize, jpeg/png/webp/avif quality, toFile, and
toBuffer, which still work.
Change-Id: I14e5b03cea0c3a49b5c40789128f0c0e0ff1ec78
sqlite3, pulled in by @cursor/sdk, still uses prebuild-install. A
socket hang-up on Windows Node 20 falls through to node-gyp, which
cannot use Visual Studio 18. Three attempts with a short pause cover
that remaining flake without changing the package.
Change-Id: Iff3853a4e6a4153ff39f8bac186e711d0de6826e
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
REQUEST_CHANGES — Consensus HIGH on two docs-app contracts: module-level once() freezes nav/search under the documented pnpm docs / watch path, and remark-repo-links rewrites relative links without the source file (first filesystem hit wins). GraphQL↔page wiring from #246 is fixed; merge still needs the watch memo fix, source-aware link rewrite (+ matrix test), and a thin unit net for the pure logic this app ships.
Chunk-bound feedback (priority)
HIGHapps/docs/lib/content.ts — once() keeps the first GraphQL list forever; empty allDocs / allSections / allPackages still “succeed.” Skip/invalidate once outside production; fail (or assert vs disk) when collections are empty but content exists on disk.
HIGHapps/docs/plugins/remark-repo-links.mjs — Source-blind first-hit resolution can map README.md to the wrong /reference/*. Pass the Markdown base (or require a unique match) and add a rewrite matrix test.
MEDapps/docs/scripts/check-links.mjs — Scalar related iterates characters; nav YAML dual-id / required fields unchecked.
MEDapps/docs/lib/toc.ts / lib/search.ts — Attribute-order TOC regex and ranking logic are pure and untested.
MED Root pnpm docs / verify — No predocs build; verify omits docs:build while CI docs-site catches it.
MED DX/docs paths — CONTRIBUTING omits the docs site; @flatbread/core README relative link breaks on npm; README should warn play vs docs port clash + symlink need.
The docs app shipped pure logic with no tests and no place to put
them. Vitest now runs in `apps/docs`, and the root `test` script
includes it beside the codegen and utils suites.
Two gaps in the root scripts close with it. `pnpm docs` on a fresh
clone failed with an opaque `ERR_MODULE_NOT_FOUND` because nothing
built the packages first; `predocs` now runs `pnpm build`. And
`pnpm verify` never looked at the docs pages, so a broken link or a
missing frontmatter key only showed up in the `docs-site` CI job;
`verify` now ends with `pnpm docs:check`.
Change-Id: Ie1d41e9fae2dba2f80d600359c6393938432b1b1
`once()` held the first answer to every list query for the life of
the process. Under `flatbread start --watch -- next dev` that process
outlives every file save, so the sidebar, the home page, and search
kept showing the corpus as it stood when the server started, while a
guide page read through `getDoc` refreshed. The memo now applies only
to a production build, which is the case it was written for.
An empty collection also used to build green. `allDocs` coming back
empty flattened to `[]`, and the site shipped a blank home page and an
empty sidebar; `check-links` could not catch it, because it reads the
filesystem rather than the graph. Each list reader now fails with the
collection name and the directory to look at.
Change-Id: I3f30efd46aa6f684d63e8666e49bf9a555960931
Flatbread hands the markdown processor a string, not a file, so the
rewriter cannot see which page a link came from. It used to resolve
the link against the guides folder and every package folder in turn
and take the first hit. That is a guess. A link to `./README.md`
inside `packages/core/README.md` landed on `/reference/codegen/`,
the first package with a README, and any `./`-relative path that
exists under two packages had the same fault.
The rewriter now collects every distinct file the bases point at and
rewrites only when they agree on one. Bases often do agree: every
package sits at the same depth, so `../../CONTRIBUTING.md` names the
same file from any of them. An ambiguous link is left alone, and
`check-links` reports it with the candidates and a way out, so it
fails the build instead of shipping a link that only works on GitHub.
Two smaller faults go with it. A scalar `related:` in frontmatter used
to iterate characters and report a missing page per letter; it now
reports once that `related` must be a list. And the checker's work
moved into an exported `collectProblems()` so tests can call it,
leaving the command-line behaviour unchanged.
Change-Id: I48ecb9c80a7c904b909a7da07a8f04826fc6d8a8
The contents list read the rendered HTML with a pattern that demanded
`id` be the first attribute. A heading serialized as
`<h2 class="..." id="...">` produced no entry, so the page lost its
contents list while the anchors beside each heading still worked.
The pattern now matches the tag and looks for `id` among whatever
attributes it carries.
Two comments in `rehype-heading-anchors.mjs` claimed the plugin kept
its slug rule in step with one in `lib/toc.ts`. There is no such rule
there: the plugin is the only place a heading id is made, and
`lib/toc.ts` reads those ids back out of the HTML. The comments now
say that.
Tests cover both files and the search ranking, which had none.
Change-Id: I740c764eb050959eb2b29d791c011544ac198ddc
`CONTRIBUTING.md` sent every newcomer to `pnpm play` and
`examples/nextjs`, so a contributor editing a guide had no way to
learn that `pnpm docs`, `pnpm docs:build`, and `pnpm docs:check`
exist. It now names them and says plainly that `pnpm verify` checks
the docs pages but leaves the full docs build to CI.
`packages/core/README.md` linked to the export guide with a path that
climbs out of the package. That works in the monorepo and on the site,
but the npm page for `@flatbread/core` ships only the package
directory, so the reader most likely to follow it got a 404. It is now
an absolute GitHub URL, as in `packages/flatbread/README.md`.
`apps/docs/README.md` gains the two things that catch people out:
`pnpm play` and `pnpm docs` both want ports 5057 and 3000, so only one
may run at a time, and the `content/reference` symlinks come out as
plain text on a Windows clone without symlink support.
Change-Id: Idb68b48b703f33e235abdca57d05cb468d27f622
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
REQUEST_CHANGES — Prior eaf20ad blockers are fixed at c3383dc (once no longer freezes watch chrome; empty collections throw; remark is unanimous not first-hit; related scalar guarded; TOC id order-independent; predocs / CONTRIBUTING / core README links landed). Two independent HIGHs remain, plus a non-empty coverage plan over non-test sources.
Blocking / high
apps/docs/lib/content.test.ts — GraphQL mocks never assert collection counts against disk (CONTENT_DIRS). Under-count still passes unit tests.
package.jsonpnpm.overrides.sharp — Workspace-wide native pin in a docs PR without release callout; affects examples/nextjs and other consumers.
Medium (selected)
Post-flatMap silent empty when all GraphQL rows are invalid (content.ts).
Hero “flat files” framing vs positioning (app/page.tsx).
apps/docs/README.md root vs package-local run instructions.
The site exports to plain files, so every GraphQL read must be
cacheable: a `no-store` fetch makes the route dynamic, and a dynamic
route cannot be exported. Next keeps those cached answers in
`.next/cache/fetch-cache`, and that directory outlives the build.
Since each build sent the same URL, method, body, and headers, the
second build read the first build's answers.
Edit a guide, run `pnpm docs:build`, and the page kept its old title.
CI never saw it, because a fresh checkout has no `.next`, so the fault
only showed up after the stale page reached a reader.
The request URL now carries a stamp taken once when the module loads.
A new build gets a new key; repeated queries inside one build still
hit the cache, which is what `force-cache` is there for.
Change-Id: Ia963689e5930d1a764174c7c63f0f564a3e5d970
A package README that must read well on npm cannot use a relative
path, so it writes the absolute GitHub URL instead. The rewriter only
looked at relative links, so `/reference/flatbread/` — the repository
README, and the busiest reference page here — threw the reader out to
GitHub for the glossary, the export guide, and a dozen other guides
sitting one route away.
An absolute link into this repository names its file outright, so
there is nothing to guess: when the site serves that file, the link
now becomes the site route. A link to a file with no page here, to a
file that is gone, or to another branch is left as it stands. That
halves the GitHub links in the exported site, from 31 to 14.
Change-Id: I72bc0d562b09f68385202650eb6c7e8f7abf2afd
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
BLOCK — workspace-wide pnpm.overrides.sharp (package.json:95-97) still has no PR body / CHANGELOG Unreleased callout (release-discipline blocker). Independently: consensus HIGH graph↔disk parity and GraphQL failure-path coverage remain open after c3383dc…013c43c (stamp + blob only).
`pnpm docs` never started the site. pnpm has a built-in `docs`
command — the same one npm has — which opens the package homepage in
a web browser, and it wins over a script of that name. Following the
instructions in `CONTRIBUTING.md` opened a browser tab, left ports
3000 and 5057 empty, and printed no error to explain it.
The script is now `docs:dev`, with `predocs:dev` building the packages
before it. A colon cannot collide with a pnpm command, so the three
docs commands — `docs:dev`, `docs:build`, `docs:check` — are safe as a
set. Nothing is left behind under the old name, since a shadowed
script is a trap rather than a convenience.
Change-Id: I196ad5591ae111a56d2aa2978683f19e8202c7da
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
BLOCK — Workspace-wide pnpm.overrides.sharp: "0.34.3" still has no CHANGELOG/CONTRIBUTING/migration note. Consensus HIGH holes also remain: post-flatMap silent [], missing graph↔disk parity tests, and untested GraphQL !ok / errors / missing-data throws.
Not dependency-only (99 non-dep paths of 103). Delta since 013c43c: rename docs → docs:dev only. That closes the README redundant manual build and the pnpm script-name collision. It does not close the open BLOCKER/HIGH items.
Blocking / consensus (priority)
BLOCKER — Document or scope the workspace sharp override (package.json).
HIGH — Re-guard after flatMap in content.ts; add all-invalid + graph↔disk tests.
HIGH — Three GraphQL throw-path unit tests.
Coverage plan
content.test.ts — all-invalid rows after flatMap must fail closed.
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
COMMENT — Prior blockers look remediated at f10ec27 (sharp 0.35.3 scoped + CHANGELOG/CONTRIBUTING, empty collections fail loud, check-content-parity, GraphQL throw tests, remark .. guard, hero “files in Git → typed relational graph”, play/docs:dev port warning). No BLOCKER. Remaining work is test/contract polish on non-test sources, so this stays COMMENT rather than APPROVE.
Not dependency-only (124 paths / 199 chunks vs origin/main4e3ff43). Oven CLI unavailable → Task-tool fallback. Models: HIGH cursor-grok-4.5-high, MED/LOW composer-2.5.
Prior open threads (19): 16 fully_addressed, 3 partially_addressed (related soft-drop after expectRecords — collections now throw; nested related still quiet).
Chunk-bound feedback (judge)
MEDapps/docs/lib/content.ts related flatMap — drops bad related rows → empty chips, no throw. Assert keep/drop (or fail loud) in content.test.ts.
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
COMMENT — Prior f10ec27 residuals (related soft-drop, thin getters, parity/export/links/sanitize/remark ..) are closed in the 9097b87 delta. No BLOCKER and no HIGH remain. Residual MED/LOW items are coverage and release/DX gaps around dual basePath (/ vs /flatbread), untested build-docs-base-path exit/env, empty-basePath export checks, undocumented non-sharp overrides, and Unreleased docs-site silence. Non-test sources changed with a non-empty coverage plan → COMMENT (not REQUEST_CHANGES: gaps are missing tests/docs, not a broken shipped contract).
Chunk-bound feedback
scripts/build-docs-base-path.mjs:1-17 — MED (test-coverage-robustness, docs-site-contracts) — verify runs the /flatbread rebuild, but nothing asserts env/exit; docs:build still ships only the root export.
package.json:32-38 — MED (docs-site-contracts) — docs:build stops at unprefixed HTML; Pages proof is CI/verify only unless documented or chained.
apps/docs/scripts/check-export.test.mjs:1-213 — MED (docs-site-contracts) — every withExport hardcodes basePath: '/flatbread'; empty-basePath branch untested.
package.json:98-105 — MED (release-discipline) — sharp BLOCKER closed; four other overrides still undocumented.
CHANGELOG.md:6-14 — MED (release-discipline) — Unreleased omits apps/docs, Pages deploy, and content move.
LOW: CI /flatbread-only vs verify dual build; related whitespace/null tests; parity success-path non-JSON; next.config.ts basePath normalize.
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
COMMENT — Prior 9097b87 MED residuals are closed on 900a3b8. No blockers or HIGHs. Consensus MED remains on the public rehype-sanitize widen in @flatbread/transformer-markdown (no Unreleased Runtime note, no package-local allow/deny tests). Several single-perspective MEDs and a non-empty coverage plan on non-test source keep this above APPROVE without REQUEST_CHANGES.
Closed vs last sync:build-docs-base-path tests + docs:build/verify/CI dual-path; empty-basePath export; non-sharp overrides documented; Unreleased apps/docs/Pages; related whitespace/null readers; parity non-JSON success; next-config normalize.
MEDpackages/transformer-markdown/.../markdown.ts:22-34 — silent public HTML allowlist widen (language-*, dataTitle) without Unreleased Runtime note or package-local tests.
MEDapps/docs/app/page.tsx — home PACKAGE_GROUPS can drop ungrouped packages (Sidebar has Other; home does not).
MEDapps/docs/scripts/check-links.mjs — related ?? [] makes related: null skip “must be a list”.
MED (coverage) remark blob rewrite with basePath=/flatbread; GraphQL force-cache/no-store; export blank search fields.
R100 renames left stale relatives in apps/docs/content/notes/experiments/issue-167|168-*.md (0-addition renames — not inline-able). Extend check-links to notes so moves cannot leave broken ../pmf-decision-rubric.md.
Reviewer scoreboard
docs-site-contracts: high signal
correctness-and-contracts: high signal
test-coverage-robustness: high signal
docs-and-positioning: medium (R100 note links)
release-discipline: medium (APPROVE on release lens)
Canvas
Open Canvas — /home/ubuntu/.cursor/projects/workspace/canvases/dag-review-900a3b8.canvas.tsx
Judge: /tmp/review-judge-final.md
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
COMMENT — No blockers on sync c22cdf08 (base 76d1edb). Prior COMMENT MEDs from 900a3b8 look closed (package-groups “Other”, related nulls, force-cache/export/remark/basePath coverage, markdown package tests, Unreleased apps/docs/Pages). Remaining items are coverage increments on already-locked contracts, so lone coverage HIGHs were downgraded to MED under anti-pedantry (not REQUEST_CHANGES). Non-empty coverage plan + non-test source edits keep the floor at COMMENT.
Not dependency-only (129 non-lock paths / 225 chunks excl. lockfile).
Coverage plan (priority)
MED — markdown.test.ts: fenced ts/tsx (and hyphenated lang) keep language-* (today only raw HTML keep is locked).
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
APPROVE — five perspectives approve at 9fbcee8. Prior COMMENT residual (MED coverage after c22cdf08) is closed by behavior asserts. No BLOCKER, no consensus HIGH, no two independent HIGHs.
Not dependency-only (125 non-dep paths / 229 chunks excl. lockfile). Delta since last sync is test/README/CHANGELOG closes for the remaining coverage plan.
Chunk-bound feedback
apps/docs/lib/graphql.test.ts:66 (MED)
setTimeout(2) before stamp reload can flake when Date.now does not advance. Stub Date.now (or inject a clock) so the reload stamp advances without sleep.
Optional: related: null → [] in content.test.ts; one getSections under the once() suite.
Notes hygiene: stale docs/experiments/… path literals in issue-167 fenced config and issue-169 R100 prose (check-links does not catch non-link strings).
Optional: CHANGELOG sharp bullet vs lockfile next>sharp / svimg>sharp wording.
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
COMMENT — Prior APPROVE at 9fbcee8 still holds on shipped contracts. The fa71c71 delta closed related: null → [], getSections production once() coverage, note path literals, and the GraphQL stamp flake (Date.now stub). No BLOCKER or HIGH remains.
Non-empty coverage gaps on non-test sources keep this at COMMENT (edge/negative hardening), not REQUEST_CHANGES.
MED (consensus):transformer-markdown sanitize keep-attrs tested; dangerous URL/handler/script/data-*strip negatives still thin.
MED: docs content missing-section / blank _content.raw / related ?? [] asymmetry vs check-links; Shiki unknown-lang / empty-fence untested.
MED (single): load-bearing content/reference symlinks until core watch vs initial-load capture is fixed — do not swap to packages/[id]/README.md.
MED (publish follow-up only): Unreleased documents markdown sanitize without a package version bump — Pages merge is fine; bump if publishing @flatbread/* from this train. Proof/filesystem Unreleased bullets have no matching packages/*/src in this diff — not merge blockers.
Sanitize allowlist without package bump — @flatbread/transformer-markdown HTML contract changed at 1.0.1; bump before any npm publish (publish:ci would otherwise skip).
Coverage plan is non-empty and non-test source changed. Consensus MED remains a publish follow-up, not a merge blocker: @flatbread/transformer-markdown sanitize allowlist (language-[A-Za-z0-9_-]+, data-title) is in-tree at 1.0.1 without a package bump — npm latest will lag until the next release train.
Chunk-bound feedback (merged)
MEDpackages/transformer-markdown/src/processors/markdown.ts:22-34 (+ wiring :7-10, apply :84) — publish @flatbread/transformer-markdown on the next train so npm matches CHANGELOG/README. No bump required to merge.
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
COMMENT — No BLOCKERs or consensus HIGHs. Open work is MED publish stickiness (sanitize / yaml without bumps), MED contract softness (related ?? [], SearchDialog basePath fetch unproven), and prior LOW coverage gaps. Coverage plan is non-empty on non-test source → COMMENT (prior LOWs alone do not escalate to REQUEST_CHANGES).
Range: 76d1edb...d2af1ec (not dependency-only: 127 non-dep / 235 chunks). Delta since 45e7c9b: Sidebar Motion comment cleanup + jsdom@16.7.0 for SearchDialog tests — no new blockers.
Bump @flatbread/transformer-markdown and @flatbread/transformer-yaml before registry publish; maintainer note to enable Pages (GitHub Actions) before first deploy-docs; optional jsdom upgrade.
Disputed: coverage asked REQUEST_CHANGES on prior LOWs — judge keeps COMMENT. yaml CHANGELOG lag thread marked partially addressed (notes aligned; bump still open).
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
COMMENT — No blockers. Disputed docs-site claims that Next nests export files under out/flatbread/ do not drive REQUEST_CHANGES (judge overrules; Next keeps artifacts at out/ root; Pages serves that tree at URL /flatbread; check-export strip/FS design matches). Consensus MED remains a publish follow-up: @flatbread/transformer-markdown sanitize/language-* allowlist change without a package.json version bump. Non-empty coverage plan + non-test source → COMMENT (edge gaps, not merge-blocking contracts).
Range: 76d1edb...82d7d98. Delta since prior sync (45e7c9b) closed CodeCopy clipboard, SearchDialog basePath/reopen, and markdown dotted-language LOWs.
Chunk-bound feedback (actionable)
MEDpackages/transformer-markdown/src/processors/markdown.ts:22-34 — bump @flatbread/transformer-markdown on the Unreleased publish train (correctness + release consensus).
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
COMMENT — No BLOCKER. One solo HIGH (Sidebar component tests) does not meet the consensus-HIGH / two-HIGH bar. Coverage gaps remain on non-test sources, so this stays COMMENT rather than APPROVE. Publish-time @flatbread/transformer-markdown semver (HTML allowlist still at 1.0.1) is a follow-up, not a merge block for this docs-site PR.
Five perspectives → COMMENT; Pages path contract holds
transformer-markdown public HTML change without version bump = publish hazard, not merge block
46a6c5b closures stand
Suggested follow-ups
Bump @flatbread/transformer-markdown before npm publish (do not reuse 1.0.1). Align home hero with positioning (or document the split). Demote standalone codegen --watch behind unified-loop. Unify basePath normalize. Fill Sidebar/search/SearchDialog/parity/CodeCopy gaps.
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
COMMENT — No blockers or consensus HIGH at 561a3e0. Shared normalizeBasePath closes the Pages/out/ desync hold. Remaining consensus issues are MED publish follow-up for @flatbread/transformer-markdown sanitize without a version bump, and SearchDialog still reading raw NEXT_PUBLIC_BASE_PATH. Coverage gaps on non-test source keep this at COMMENT, not APPROVE.
Delta 46a6c5b…561a3e0 (fix(docs): close final production gaps) closed prior residuals: Sidebar component tests, SearchDialog non-JSON guard, CodeCopy/parity/export/basePath share, Proof-first hero rewrite. HOLD honored: do not elevate out/ nesting vs /flatbread URL.
Chunk-bound feedback
See inline comments (severity order). Full judge text also covers Toc observer, related null residual, core README Pages link, and Pages ops follow-up.
Coverage plan
SearchDialog: NEXT_PUBLIC_BASE_PATH'/' and '/flatbread/' without relying on next.config rewrite
SearchDialog: reject/loadError on incomplete search entry fields; / while focus is in another INPUT/TEXTAREA
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
COMMENT at b92c10a (merge-base 76d1edb). Not dependency-only. No BLOCKER and no consensus HIGH.
Sync fix(docs): harden search and navigation closes the prior SearchDialog raw-NEXT_PUBLIC_BASE_PATH residual (normalizeBasePath), adds isSearchEntries, lands Toc/CodeCopy tests, aligns the hero lede with “typed relational graph”, and points packages/core at the published Pages URL.
Residual MEDs are publish-train / ops follow-ups, not merge blockers:
@flatbread/transformer-markdown sanitize allowlist still at published 1.0.1
@flatbread/transformer-yamljs-yaml floor without a package bump
One-time GitHub Pages admin enable (already documented in CONTRIBUTING)
Hold stands: static export with basePath keeps files at out/ root — do not elevate nesting claims.
Coverage plan
Toc — empty list, missing headings, observer disconnect on unmount
SearchDialog — mixed invalid array members / empty-string fields after the shape guard
CodeCopy — overlapping timer / rapid re-click across blocks
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
COMMENT — No BLOCKER or consensus HIGH. Coverage plan is non-empty while non-test source changed under apps/docs and packages/transformer-markdown; ThemeToggle/NavDisclosure gaps are not documented contracts (rule: coverage plan + non-test source → COMMENT).
Closed at 6c44eab
SearchDialog blank-string validation now matches check-export required fields. Prior normalizeBasePath gap stays closed. out/ root vs /flatbread URL layout still holds — do not re-raise nesting.
The reason will be displayed to describe this comment to others. Learn more.
MED (consensus — publish follow-up) — rehype-sanitize now keeps filtered language-* / data-title on <code> while @flatbread/transformer-markdown stays at 1.0.1. CHANGELOG Unreleased already documents the behavior.
Minimal fix: At publish cut, bump the package with pnpm bump and ship the Unreleased note. Do not pre-bump in this PR. Not a merge blocker.
The reason will be displayed to describe this comment to others. Learn more.
MED (consensus — publish follow-up) — js-yaml floor moves ^4.1.0 → ^4.3.1 with no package version bump and no src change. Root CHANGELOG already records the dependency move.
Minimal fix: Bump @flatbread/transformer-yaml at publish cut. Leave Unreleased as-is for merge.
The reason will be displayed to describe this comment to others. Learn more.
Stale comment
Review verdict
COMMENT — No BLOCKER and no consensus HIGH. Delta 6c44eab → f3911c2 closes the prior ThemeToggle / NavDisclosure coverage plan with behavior tests. Residual merge bar is coverage: REFERENCE_ACTIONS[].nextAction.href is still shape-checked only while the reference page renders those hashes as live in-page links. Anchors resolve at HEAD today; the miss is regression detection, not a broken contract. Prior sanitize allowlist + js-yaml floor are closed at package level; coordinated lockstep publish remains a MED follow-up only. Hold: do not re-elevate intentional GitHub Pages out/-root / basePath layout.
MED — apps/docs/lib/reference-actions.test.ts: For each published package id, slugify h2/h3 from content/reference/<id>.md with rehype-heading-anchors rules; assert nextAction.href.slice(1) is in that set; add negative #missing-section. (Alternate: one check in check-export.mjs against exported HTML — pick one home.)
LOW — NavDisclosure.test.tsx: Wide media + pathname change stays open / no #main-content focus; missing #main-content does not throw.
The reason will be displayed to describe this comment to others. Learn more.
severity: MED — flagged-by: test-coverage-robustness, docs-site-contracts
risk: This asserts href shape (^#[a-z0-9-]+$) only. A README heading rename keeps CI green while the reference “next action” CTA 404s in-page (reference/[slug]/page.tsx renders action.nextAction.href live).
minimal fix: For each PUBLISHED_PACKAGE_IDS entry, derive h2/h3 ids from content/reference/<id>.md with the same slug rules as plugins/rehype-heading-anchors.mjs, and assert nextAction.href.slice(1) is in that set. Add one negative (#missing-section). Alternate home: the same check once in check-export.mjs against exported HTML — do not duplicate thrice.
The reason will be displayed to describe this comment to others. Learn more.
severity: MED — flagged-by: test-coverage-robustness, docs-site-contracts
risk: Live hash link depends on REFERENCE_ACTIONS staying aligned with README headings. Current HEAD anchors match for all eleven packages; coverage still cannot catch a heading rename.
minimal fix: Prefer the href↔heading assert on reference-actions.test.ts (or one check-export pass). No page change required while anchors resolve.
The reason will be displayed to describe this comment to others. Learn more.
Review verdict
COMMENT — No blockers or consensus HIGHs. Prior REFERENCE_ACTIONSnextAction.href ↔ heading-id MED is closed at fcb53f0 (check-export same-page fragment test + postbuild). Standing sanitize / js-yaml items stay publish residuals, not REQUEST_CHANGES on this non-release PR. Coverage plan still lists an optional unit-speed href↔heading pairing gap while the PR touches non-test source, so the floor is COMMENT (not APPROVE).
Delta this sync (f3911c2..fcb53f0): NavDisclosure wide-screen pathname + missing-#main-content tests; check-export missing same-page next-action fragment test.
Closed / hold
CLOSED:REFERENCE_ACTIONS fragment ↔ export check (detector + unit fixture).
HOLD: intentional out/ root artifacts + URL /flatbreadbasePath — do not elevate nesting without a counterexample.
Coverage plan
MED (optional):apps/docs/lib/reference-actions.test.ts — it.each over REFERENCE_ACTIONS asserting each nextAction.href.slice(1) ∈ slugified H2–H4 ids from the matching package README / heading pipeline. Postbuild already enforces; this only shortens the loop.
LOW:apps/docs/app/reference/[slug]/page.tsx render smoke that next-action href appears in HTML.
LOW: Optionally wire check-export.test.mjs to live REFERENCE_ACTIONS beyond synthetic HTML.
The reason will be displayed to describe this comment to others. Learn more.
severity: MED (publish residual, not REQUEST_CHANGES)
Sanitize allowlist narrowing (/^language-[A-Za-z0-9_-]+$/ + dataTitle) ships in workspace/apps/docs, but @flatbread/transformer-markdown stays at 1.0.1.
Minimal fix: On the release PR, bump this package with the sanitize change; keep docs workspace:* dogfood as-is until then.
The reason will be displayed to describe this comment to others. Learn more.
Coverage plan (optional MED) — consensus across correctness / test-coverage / docs-site.
nextAction.href is shape-checked (/^#[a-z0-9-]+$/) and wrong fragments fail postbuildcheck-export, but vitest does not yet assert each href ∈ slugified H2–H4 ids from the matching package README.
Minimal fix if wanted:it.each over REFERENCE_ACTIONS running the heading slug pipeline and asserting href.slice(1) ∈ ids. Not REQUEST_CHANGES while postbuild stays mandatory.
The reason will be displayed to describe this comment to others. Learn more.
CLOSED (prior MED) — this same-page #fragment case closes the prior REFERENCE_ACTIONSnextAction.href ↔ heading-id / export-check concern at fcb53f0.
It matches the production collectExportProblems loop that validates exported reference HTML. Do not reopen as REQUEST_CHANGES.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
cursor
Bot
changed the title
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
docs time