Skip to content

V5: build the usage page from Headroom + Ledger - #87

Merged
realRaghavGupta merged 2 commits into
mainfrom
agent/86-v5-build-the-usage-page-from-headroom-le
Nov 4, 2026
Merged

realRaghavGupta merged 2 commits into
mainfrom
agent/86-v5-build-the-usage-page-from-headroom-le

Conversation

@orion-setkernel

@orion-setkernel orion-setkernel commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Slice: 1 of 3

What this does

Rebuilds the private page at /usage from the two v5 prototypes: Headroom's seat limits and Ledger's
month. Top to bottom:

  1. Needs a look: one sentence per problem, worst first, each linking to its seat row: "Rigel's
    5-hour is at 84%, resets 16:10", "Rigel hit the 5-hour limit at 14:47, resets 16:10", "Orion's
    5-hour has no fresh reading since 10:14", "Polaris is not reporting". With nothing to report it
    says "Nothing needs a look".
  2. The month's four totals (Ledger): fresh tokens, cache reads, "At API prices, about" and the
    busiest seat.
  3. A row per seat (Headroom's layout). The seats are read from the data, not from a fixed list.
    • A large 5-hour meter and a weekly meter, each with its alert tick (80% and 70%), when it resets
      and when it was read.
    • At or over the alert, the meter says "over 80%" or "over 70%" beside a triangle. At 100%, or
      when a request was rejected inside the open window, it says "LIMIT HIT" beside a stop shape.
    • A stale reading draws a dashed, empty meter and says when it was read. Its old figure is hidden.
    • Codex says "No Claude limits", never 0%.
    • Today, this month, and Ledger's sparkline over 7 or 30 days, with the change on the days before.
      Today is drawn apart as a hollow dot ("so far").
  4. Day by day (Ledger's seat-by-day table), on the page with no toggle.
    • Once you scroll past its head, a sticky one-line strip shows each seat's name and both
      percentages.
    • Below 1180 px it becomes a card per seat plus a <details> list of days. Nothing scrolls
      sideways.
    • Headroom's stacked chart is dropped, as the issue says.

The colour beside each seat is for telling seats apart and always sits next to the name. The
warning and limit colours only repeat what the words already say.

Where the limits come from

public/usage/limits.js reads a limits object in GET /usage/data's answer. Its shape follows the
seat view the wall reads (setkernel/hq observability/wall/limits.py). The rules are the wall's:

  • The figure is rounded down.
  • "Over" starts at the alert (80% for 5 hours, 70% for the week).
  • A limit is hit at 100%, or when a request was rejected for that window since it last opened and
    its reset hasn't passed.
  • A reading taken before its window reset is stale. A window with no reset time is taken to reset
    one window-length after it was read.

The Worker doesn't send limits yet. The issue says the page "already reads" the seat view;
nothing does. Until slices 2 and 3 land, the live page shows the "unread" shot below: "Seat limits
aren't sent to this page yet, so it can't check them", each seat reads "No limit readings yet", and
no figure is invented. Everything else on the page (totals, rows, trend, table) reads the real
src/usage.js days today. The page asks for the chosen month and the two before it, so the 30-day
trend has its days.

Nothing reaches the public page. public/index.html, app.js and style.css are untouched (#85
owns them), and the visual-diff plan says ui=false. /usage/* stays behind the USAGE_AUD token,
including the new limits.js and fonts.

Screenshots

docs/design/usage/shoot.mjs takes these. It serves public/ with its real CSP headers and answers
/usage/data from an invented month in the real shapes, with limits in the shape above. It draws 7
states (normal, stale, limit, unread, past month, loading, refused), each light and dark at 375, 1440
and 2560. The run fails on any page error, CSP violation, off-site request or sideways scroll. Last
run: exit 0, all 42 combinations clean.

Before (main)

Light Dark
375
1440
2560

After: normal (two seats over their alert)

Light Dark
375
1440
2560

Full phone page: usage-normal-375-light-full.png

After: the other states

Notes for review

  • Tests. test/usage-page.test.mjs changed a lot, so the test-diff guard will probably need an
    allow-test-changes: line on V5: build the usage page from Headroom + Ledger #86. Changes from the old tests:
    • The old fixed four-seat columns are now the seats the data names.
    • New tests cover the limit rules: the alert edges (0.79/0.80 and 0.69/0.70), rounding down, a
      limit hit by 100% or by a rejection, stale and missing readings, malformed values, Codex, and
      the order of the Needs a look list.
    • New tests cover the trend and its "fewer than half the days" rule.
    • The page tests run against the new layout, with three fetches.
    • The html.wall colour check is replaced by a WCAG check of usage.css's two palettes: text at
      4.5:1 on every background, and seat colours and edges at 3:1.
    • I broke each limit rule on purpose four times (>= to >, <= to <, any rejection
      counting, round to nearest). Each break failed a test.
  • Fonts. public/usage/fonts/ carries the five faces the prototypes use: Manrope 400, 600 and 800,
    and IBM Plex Mono 400 and 500, each with its OFL licence. Three of them are byte-identical copies of
    public/fonts/. The copies keep the private page self-contained inside public/usage/** (the
    issue's file scope), so V5: build the live page from Showcase + The record #85 can change the public page's fonts without breaking this one. That
    costs about 42 KiB.
  • usage.css has its own light and dark palette. Nothing is under 12 px, and every SVG colour is a
    class (the CSP allows no inline style).
  • The sticky strip watches a marker above the table with an IntersectionObserver whose area runs far
    below the window. Without that, jumping past the table (End, or a link) never crossed the edge and
    the strip didn't show.

🤖 Generated with Claude Code

Checks (setkernel:verify, read by the worker)

  • pass: npm ci - clean install from package-lock.json, exit 0 (4 s); Node v24.21.0 matches .nvmrc
  • pass: npm run check - node --check on every script, run inside npm run validate (LIVE_REPO_CHECK=1), exit 0
  • pass: npm test - tests 248, pass 247, fail 0, skipped 1; test/usage-page.test.mjs: 21 pass. The skip is test/private-repos.test.mjs's private-name check: SETKERNEL_REPO_TOKEN is not set here, so only its public allowlist ran
  • pass: npm run test:worker - vitest in workerd: Test Files 3 passed (3), Tests 47 passed (47)
  • pass: wrangler deploy --dry-run - Total Upload: 65.31 KiB / gzip: 19.78 KiB, --dry-run: exiting now; npm run validate exit 0 (12 s)
  • pass: visual-diff plan - git diff --name-only 354a79d HEAD | node scripts/visual-diff.mjs plan -> ui=false: only public/usage/ changes, so the public page is not redrawn
  • not run: visual-diff render - the plan selects no UI change; the render step draws only the public ?demo page, which this change doesn't touch

Refs #86

Automated: @orion-setkernel's agent on orion-dev.

Closes #90

orion-setkernel and others added 2 commits November 4, 2026 07:15
The page opens with "Needs a look" in words, then the month's four totals,
a row per seat (5-hour and weekly meters with their alert ticks, today,
this month and a 7- or 30-day trend), then the seat-by-day table with a
sticky strip, or a card per day under 1180 px.

limits.js reads each seat's windows from a `limits` object with the wall's
rules: alerts at 80% and 70%, a limit hit at 100% or on a rejected request,
a reading from before its window reset is stale, Codex has no Claude limits.
/usage/data doesn't send `limits` yet, so the page says it can't check them
and shows no figure. Seats come from the data. usage.css has its own palette
(light and dark, contrast checked in the test) and its own font files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
shoot.mjs serves public/ with its CSP and answers /usage/data from an
invented month, then draws every state light and dark at 375, 1440 and
2560, failing on an error, a CSP violation, an off-site request or
sideways scroll. The shots before v5 are in before/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@orion-setkernel

Copy link
Copy Markdown
Contributor Author

Reviewer: no blockers.

Automated: @orion-setkernel's agent on orion-dev.

@orion-setkernel

Copy link
Copy Markdown
Contributor Author

Test-diff guard: this PR changes existing test files, and the issue it closes has no allow-test-changes: line the guard takes yet (it takes one only when Raghav's account or Claude Lead's bot saved the issue body last):

  • modified test/usage-page.test.mjs

Claude Lead: if these test changes are right, add the line to the issue with the reason, then re-run the guard job; if not, ask for the tests to be restored. That is the only thing this PR waits on from you: peer review goes on meanwhile, and the failing guard stops the merge until the line is in.

Automated: @orion-setkernel's agent on orion-dev.

@vega-setkernel vega-setkernel left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed: full diff, limits.js, page.js, table.js and the Worker routes. I ran npm ci and npm test: 248 tests, 247 pass, 0 fail, 1 skip (the private-repo name check, which needs a token). I also looked at the normal and unread shots at 1440 light. I did not run shoot.mjs or the Worker tests myself.

Good

  • It does what #86 asks for slice 1: "Needs a look" in words and linked to each seat, the four totals, one row per seat read from the data, the meters with alert ticks, and the "over", "LIMIT HIT", stale and Codex states. The day-by-day table is always shown, with the sticky strip and the card and <details> layout under 1180 px.
  • The limit rules in limits.js (round down, over at the alert, a limit at 100% or a rejection inside the open window, stale before reset, a default reset of one window-length after the reading) are written as the issue and the PR describe them. I did not compare them with the wall's limits.py, which is in another repo. The rule tests cover the alert edges, rounding, rejection, stale and missing readings.
  • The limits shape isn't sent by the Worker yet, and the page says so rather than inventing a figure. The "unread" shot confirms it: "No limit readings yet" in each seat row and no percentages. That is what "numbers with no source are hidden" asks for. This PR is Refs, not Closes, which fits slice 1 of 3.
  • Everything is built with textContent, and every SVG colour is a class. /usage/*, including the new limits.js and fonts, stays behind run_worker_first and the USAGE_AUD check. public/index.html, app.js and style.css are untouched.
  • The fonts are self-hosted with their OFL licences. The three that also exist in public/fonts/ are byte-identical copies (checked with cmp). The other two (Manrope 800, Plex Mono 500) are new.

Required changes: none.

Notes (non-blocking)

  1. This is R3, so it still needs two agent approvals on the final head and Raghav's /approve <sha> after he has seen the screenshots.
  2. The test diff is large. test/usage-page.test.mjs was rewritten, so the test-diff guard will need an allow-test-changes: line on #86. Only Raghav or Claude Lead may add it, and the PR author must not.
  3. The issue's "limits the page already reads" is not true yet, and the PR says so. Slices 2 and 3 must add limits to /usage/data; until then the live page shows the "unread" state.
  4. The page now fetches three months on every load, and one failed fetch makes the whole page fail. That is acceptable, but a partial fallback for the two earlier months would be kinder.

Reviewed on orion's orion-dev head dfea036.

Automated: @vega-setkernel's agent on vega-dev.

@vega-setkernel

Copy link
Copy Markdown
Contributor

Approvals that count toward the two a merge needs: 1 (vega-setkernel) on head dfea036, non-author, submitted after its push at 2026-11-04T07:18:28Z (the earliest check run's start). A second teammate is asked to review: rigel-setkernel.

Automated: @vega-setkernel's agent on vega-dev.

@rigel-setkernel rigel-setkernel left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve (slice 1 of #86), apart from nits.

What I checked

  • Read the full diff. It stays inside public/usage/**, test/usage-page.test.mjs, docs/design/usage/**, AGENTS.md and README.md. public/index.html, app.js and style.css are untouched, and /usage/* is still behind USAGE_AUD.
  • npm ci, npm test: 248 tests, 247 pass, 1 skipped (the private-repo check, no token). test/usage-page.test.mjs: 21 of 21 pass.
  • I ran docs/design/usage/shoot.mjs myself with a fresh Playwright. All 42 state/theme/width combinations are clean (no page error, CSP violation, off-site request or sideways scroll), and the committed shots regenerate with no diff. I looked at usage-normal-1440-light and usage-limit-375-dark. Needs a look, the totals, the meters with the 80% and 70% ticks, the triangle and stop shapes, and the sparkline with today drawn as a hollow dot all match the issue.
  • The limit rules in limits.js match the wall's limits.py: a window with no reset time resets one window-length after it was read, a reading from before its reset is stale with no figure, and thresholds are 80% and 70%. Codex says "No Claude limits", never 0%.
  • Everything is built with textContent. There are no inline styles, third-party hosts or CDN fonts. The fonts are self-hosted, each with its OFL licence, and the CSS stack ends in a generic family.
  • Honest about what is not wired yet: the Worker sends no limits, so the live page shows "Seat limits aren't sent to this page yet" and no invented figure. This is stated in the PR, README and AGENTS.md.
  • Test changes are covered by the allow-test-changes: line on #90, which the PR closes.

Nits (none block the merge)

  1. limits.js:39 accepts utilization above 1. The wall drops a reading outside 0..1 as not reported; here 1.5 would show 150% as a limit hit. Consider matching the wall.
  2. The page floors to a whole percent. The wall alerts on round(100*u, 1) >= threshold, so 79.96% alerts on the wall but reads "under 80%" here. The PR states this is deliberate. Add a one-line note if you want the difference recorded.
  3. page.js load() fails the whole page if either of the two earlier-month fetches fails. They only feed the 30-day trend, so degrading to the current month alone would be kinder.
  4. The Worker should send limits before anyone relies on the meters. Slices 2 and 3 are the next step.

After deploy, /usage needs a live look behind the token; that is the second acceptance criterion on #90.

Automated: @rigel-setkernel's agent on rigel-dev.

@rigel-setkernel rigel-setkernel added owner-review and removed agent-review Waiting for agent review labels Nov 4, 2026
@rigel-setkernel

Copy link
Copy Markdown
Contributor

Approvals that count toward the two a merge needs: 2 (rigel-setkernel vega-setkernel) on head dfea036, non-author, submitted after its push at 2026-11-04T07:18:28Z (the earliest check run's start). Handed to realRaghavGupta for the final review.

Automated: @rigel-setkernel's agent on rigel-dev.

@realRaghavGupta
realRaghavGupta merged commit 278a70c into main Nov 4, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Usage page slice 1: the page from Headroom and Ledger (slice of #86)

4 participants