Public: anyone can read this; the crew can change it.

/docs index answers under 40 ms and 15 KB, measured on production #13021

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

The /docs index is now 14.5 KB in the test app, down from 24.3 KB on production. Every document is still listed and linked. I did not measure the 40 ms target and did not take the before/after pictures at 390 and 1280 px, light and dark, so those two "done when" items are open.

Notes

shipped production is serving it deploy 8e1361f

opened this

The /docs index is now 14.5 KB in the test app, down from 24.3 KB on production. Every document is still listed and linked. I did not measure the 40 ms target and did not take the before/after pictures at 390 and 1280 px, light and dark, so those two "done when" items are open. I also did not call keep_plan or estimate.

What changed

  • On the index, each document is now a bare <li><a href="/docs/NAME">Title</a></li>. The generic row markup cost about 130 bytes per document, mostly whitespace and nested spans, and it is gone from this page.
  • Search results on /docs?q= still use the full row with its snippet.
  • A small .docs-index rule in src/web/style/components.ts keeps the hover state and a 44 px hit area. It is documented in the new docs/design/areas/docs.md.

Tests

  • A new test in test/docs-link.test.ts fails if any document drops off the index or the page reaches 15 KB.
  • I changed one existing assertion in that file: the "index is rows" test expected <ul class="list">, and the class is now list docs-index.
  • bun test on docs-link, design-lint and mcp-size is green, as are tsc --noEmit and scripts/gate.ts.
  • bun scripts/design-lint.ts still prints many messages elsewhere in the tree, and I did not clear them. There is no message for .docs-index or the lines I added; test/design-lint.test.ts is green.

Left out

  • The 40 ms target, and the page chrome (about 9.7 KB, shared by every page). Trimming the chrome would have pushed this past the issue's "docs index" scope, and only the document rows were needed to reach 15 KB.
  • The 14.5 KB figure was measured in the test app. Production's chrome is slightly larger because of the longer URLs, so the real figure may land closer to the 15 KB line.
  • Nothing was added to MCP or the terminal. The terminal docs list already shows the same documents.

Try it: open /docs and check the page size. Gzipped it was already about 4.5 KB on production.

🤖 Generated with Claude Code

Closes #12997

5 earlier comments · 2 events
commented

The /docs index is now 14.5 KB in the test app, down from 24.3 KB on production. Every document is still listed and linked. I did not measure the 40 ms target and did not take the before/after pictures at 390 and 1280 px, light and dark, so those two "done when" items are open. I also did not call keep_plan or estimate.

What changed

  • On the index, each document is now a bare <li><a href="/docs/NAME">Title</a></li>. The generic row markup cost about 130 bytes per document, mostly whitespace and nested spans, and it is gone from this page.
  • Search results on /docs?q= still use the full row with its snippet.
  • A small .docs-index rule in src/web/style/components.ts keeps the hover state and a 44 px hit area. It is documented in the new docs/design/areas/docs.md.

Tests

  • A new test in test/docs-link.test.ts fails if any document drops off the index or the page reaches 15 KB.
  • I changed one existing assertion in that file: the "index is rows" test expected <ul class="list">, and the class is now list docs-index.
  • bun test on docs-link, design-lint and mcp-size is green, as are tsc --noEmit and scripts/gate.ts.
  • bun scripts/design-lint.ts still prints many messages elsewhere in the tree, and I did not clear them. There is no message for .docs-index or the lines I added; test/design-lint.test.ts is green.

Left out

  • The 40 ms target, and the page chrome (about 9.7 KB, shared by every page). Trimming the chrome would have pushed this past the issue's "docs index" scope, and only the document rows were needed to reach 15 KB.
  • The 14.5 KB figure was measured in the test app. Production's chrome is slightly larger because of the longer URLs, so the real figure may land closer to the 15 KB line.
  • Nothing was added to MCP or the terminal. The terminal docs list already shows the same documents.

Try it: open /docs and check the page size. Gzipped it was already about 4.5 KB on production.

🤖 Generated with Claude Code

commented

The /docs index is now 14.5 KB in the test app, down from 24.3 KB on production. Every document is still listed and linked. This push fixes the two gate failures, and I did not see the forge's check run on it. Locally bun scripts/gate.ts, bun x tsc --noEmit and test/docs-link.test.ts are green.

What changed

  • On the index, each document is now a bare <li><a href="/docs/NAME">Title</a></li>, styled by a small .docs-index rule that keeps the hover state and a 44 px hit area. The generic row markup cost about 130 bytes per document and is gone from this page. Search results on /docs?q= keep the full row with its snippet. The new class is documented in docs/design/areas/docs.md.
  • A new test in test/docs-link.test.ts fails if a document drops off the index or the page reaches 15 KB. I changed the existing "index is rows" assertion to expect list docs-index.
  • This push wraps two comments in src/web/pages/docs_link.ts and src/web/style/components.ts at 100 columns. It also adds /docs to the app.looks list in forge.json, with a Looks: /docs line in the commit, so the forge takes the before/after pictures (light and dark) on the preview.

Not done

  • I did not measure the 40 ms target.
  • The page chrome (about 9.7 KB, shared by every page) is untouched, so production may land closer to the 15 KB line than the test app does.
  • Nothing was added to MCP or the terminal; the terminal docs list already shows the same documents.

Try it: open /docs and check the page size. Gzipped it was already about 4.5 KB on production.

🤖 Generated with Claude Code

commented

The preview failed because adding /docs put app.looks in forge.json over its limit of 24 paths. I removed it, and the gate passes locally with that change. I did not check that the preview deploy now succeeds.

The index change is the same. Each document on /docs is one bare link per line, and none is dropped. In the test app the page is 14.5 KB, down from 24.3 KB on production. A new test in test/docs-link.test.ts fails if a document is missing or the page reaches 15 KB. The .docs-index styling is documented in docs/design/areas/docs.md.

  • No before/after pictures: the forge's look gate wants a path from app.looks, and the list is full, so the last commit carries a No look: line giving that reason. The pictures at 390 and 1280 px, light and dark, are therefore still missing from the pull. Someone would need to free a slot in app.looks for /docs to get them.
  • Latency not measured: the 40 ms target is unverified, and the shared page chrome (about 9.7 KB) is untouched.
  • MCP and terminal: nothing was added to either. The terminal docs list already shows the same documents.

To try it, open /docs and check the page size. Gzipped it was already about 4.5 KB on production.

🤖 Generated with Claude Code

Changes requested — before the latest push

The preview /docs is 14,728 bytes with 65 bare links, so the size target is met, but only barely, and the rest of the issue is not shown.

Fix first: measure the 40 ms target and put the number on the pull. I curled the preview once and got 0.47 s total; that is a cold single request over the network, so it proves nothing either way, but the pull has no measurement at all. Report server time from the page's own timing header, warm, on the preview.

Also needed:

  1. Before/after pictures at 390 and 1280 px, light and dark, are not on the pull. Free a slot in app.looks (or swap one) so the forge takes /docs; the pull cannot say it is done without them.
  2. 14.7 KB against a 15 KB budget leaves 300 bytes of headroom, and production chrome is larger (the builder says so). The test measures the test app, so production can fail the issue's own bar. Trim the shared chrome or a heading, or assert a tighter bound that reflects production URLs.
  3. Design lint: confirm bun scripts/design-lint.ts is clean for the touched files; the builder says it prints many messages elsewhere and the box needs it green.
  4. Principle 7 (rows over boxes): the bare <li><a> bypasses the row() component with a parallel hand-rolled row class. It is documented in docs/design/areas/docs.md, which is the right place, but prefer making row() cheaper for everyone than forking it.
  5. Principle 5: the hover turns the whole link accent; fine, but the focus style only sets outline-offset, so check the focus ring is visible on the muted hover background.
commented

Changes for the review: I added a latency test, tightened the size bound, and put /docs back in the looks. I did not slim row(). The pictures are not on the pull yet, because they need a forge run on this push.

Latency (40 ms). I measured the preview warm, with six requests and the Server-Timing header each time. The first request was app;dur=6.8, and the five after it were 2.5–2.8 ms (render 1.5–1.7 ms, session 0.1 ms). That is well under 40 ms. The 0.47 s total from the one cold curl was network time, not the server's. I also added a test in test/docs-link.test.ts: after one warm-up request, it asserts the median of ten /docs requests is under 40 ms.

Size (15 KB).

  • Bound: the size test's bound is now 14 KB, down from 15 KB, so production's larger chrome still has room under the issue's 15 KB.
  • Page change: the test app was at 14,596 bytes against the 14 KB bound, so I dropped the optional closing </li> on each index row. That is valid HTML and saves about 325 bytes (65 rows × 5), which brings the page under 14 KB.

Looks. /docs is back in app.looks in forge.json, swapped in for /feed, which keeps the list at its 24-path limit. The before/after pictures at 390 and 1280 px, light and dark, should come from the forge's look run on this push. I can't take them from the sandbox.

Design lint and checks. bun scripts/design-lint.ts is clean ("no colour, size or component added outside the system"). bun x tsc --noEmit and bun scripts/gate.ts pass. test/docs-link.test.ts passes (11 tests). I did not run the full suite.

Not done.

  • Principle 7: I kept .docs-index rather than slimming row() for everyone. Slimming row() touches every list on the forge, and the issue is about one page. The class stays documented in docs/design/areas/docs.md. Say so if you want that as a follow-up.
  • Focus ring: the global :focus-visible rule in base.ts already sets a 2px accent outline. .docs-index only moves the offset inward (-2px), so the ring stays inside the row and visible on the muted hover background. I checked this in the CSS, not on screen.
commented

Both check failures are fixed and pushed. test/docs-link.test.ts and test/forge-looks.test.ts pass (18 tests), and bun scripts/gate.ts and bun x tsc --noEmit are clean. I did not run the full suite.

  • Clock test: the forge refuses wall-clock bounds in tests, so I replaced the "under 40 ms" test with a work count. A warm /docs request must cost at most four SQL statements (via expectWork and requestStatements).
  • Looks test: app.looks must match the router's top-level pages. /feed is a real page, so dropping it from the looks without a reason failed that test. I added /feed to NOT_A_PAGE with the reason that its slot went to /docs. I removed the /docs entry, which described it as a redirect and is no longer true.

The 40 ms evidence for the pull is the preview's own Server-Timing header, measured warm. The first request showed app;dur=6.8 and the next five 2.5–2.8 ms, so the page is well under 40 ms. The count test guards the cause of slowness (SQL work), not a stopwatch.

I did not slim row(). .docs-index stays as a separate class, documented in docs/design/areas/docs.md. I did not check the focus ring on screen, only in the CSS: it inherits the global 2px accent outline from base.ts, with the offset moved inward.

The look pictures at 390 and 1280 px, light and dark, should come from the forge's look run on this push.

Approved

Earlier asks: the 40 ms evidence is met by the warm Server-Timing figure plus a work-count test (no wall clock); the 14 KB bound and the dropped optional </li> are in; /docs is back in looks with /feed explained in NOT_A_PAGE. The preview serves /docs at 200 and 14,403 bytes, every document linked as a bare link row. Two things I would do next, both non-blocking: (1) Non-blocking: slim row() itself so .docs-index is not a second row component (principle 7); file it as a follow-up. (2) Non-blocking: check the focus ring on screen, since only the CSS was read, and add the before/after pictures at 390 and 1280 px that the look run now takes for /docs. Left box 3 open because the pictures are not yet on the pull.

commented

Left #12997 open: 1 unticked item remain (before/after pictures at 390 and 1280 px, light and dark, are on the pull).

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs