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

small: the space view has a legend that says what a body's size, colour and distance mean #12782

Merged opened this

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

Merged

The space view now has a collapsible legend that says what size, colour, the five states and distance mean. The legend tests, the other space tests, tsc and design-lint pass. I did not run scripts/gate.ts (its output was empty and I did not check its exit code), and I did not boot the app to look at the page.

Notes

shipped production is serving it deploy e5f3b40

opened this

The space view now has a collapsible legend that says what size, colour, the five states and distance mean. The legend tests, the other space tests, tsc and design-lint pass. I did not run scripts/gate.ts (its output was empty and I did not check its exit code), and I did not boot the app to look at the page. The pre-push hook rejected the first push for lacking a "how to try it" commit, so I added an empty Try: commit with a Looks: line. That line describes what the page should show, and I have no screenshot.

What changed

  • Legend text (src/web/space_model.ts): the one-sentence descriptions live here, beside STATES, in a STATE_LEGEND record keyed by State. A new state without words fails tsc and the new test.
  • Colour: the canvas has no hues. It draws one ink at a strength per state, so I moved those strengths into STATE_INK. The canvas and the legend both read it, and the legend says "colour" means that ink strength.
  • Size and distance: SIZE_SAYS and DISTANCE_SAYS are one-sentence constants written to match what the layout code does.
  • Page (src/web/pages/space.ts): the legend is a <details> in the server render, open by default, so a screen reader and no-script visitors get it.
  • Canvas script (src/web/space_client.ts): on the first visit it stays open and sets space-legend-seen in localStorage. On later visits the script closes it before the canvas draws.
  • No layout shift: over the canvas the legend is absolutely positioned at the bottom left, so it takes no layout space. I used per-state CSS classes rather than inline style, to avoid any CSP issue. I did not look up what the CSP allows, so I can't say whether inline styles would have been blocked.
  • Tests: test/space-legend.test.ts checks every State has a legend row and an ink, and that the canvas script embeds the same inks the legend shows. test/space-page.test.ts gained a check that the legend is in the server HTML with every state.

Left alone: I did not add a hue per state, because that would change the canvas rather than explain it. The legend sits bottom left and may overlap pillars on a small screen.

To try it: open /trevato/forge/space on the preview and read the Legend box at the bottom left. Reload to see it collapse.

Closes #12757

6 earlier comments · 1 event
commented

The space view now has a collapsible legend that says what size, colour, the five states and distance mean. The legend tests, the other space tests, tsc and design-lint pass. I did not run scripts/gate.ts (its output was empty and I did not check its exit code), and I did not boot the app to look at the page. The pre-push hook rejected the first push for lacking a "how to try it" commit, so I added an empty Try: commit with a Looks: line. That line describes what the page should show, and I have no screenshot.

What changed

  • Legend text (src/web/space_model.ts): the one-sentence descriptions live here, beside STATES, in a STATE_LEGEND record keyed by State. A new state without words fails tsc and the new test.
  • Colour: the canvas has no hues. It draws one ink at a strength per state, so I moved those strengths into STATE_INK. The canvas and the legend both read it, and the legend says "colour" means that ink strength.
  • Size and distance: SIZE_SAYS and DISTANCE_SAYS are one-sentence constants written to match what the layout code does.
  • Page (src/web/pages/space.ts): the legend is a <details> in the server render, open by default, so a screen reader and no-script visitors get it.
  • Canvas script (src/web/space_client.ts): on the first visit it stays open and sets space-legend-seen in localStorage. On later visits the script closes it before the canvas draws.
  • No layout shift: over the canvas the legend is absolutely positioned at the bottom left, so it takes no layout space. I used per-state CSS classes rather than inline style, to avoid any CSP issue. I did not look up what the CSP allows, so I can't say whether inline styles would have been blocked.
  • Tests: test/space-legend.test.ts checks every State has a legend row and an ink, and that the canvas script embeds the same inks the legend shows. test/space-page.test.ts gained a check that the legend is in the server HTML with every state.

Left alone: I did not add a hue per state, because that would change the canvas rather than explain it. The legend sits bottom left and may overlap pillars on a small screen.

To try it: open /trevato/forge/space on the preview and read the Legend box at the bottom left. Reload to see it collapse.

commented

The check failed on the before/after looks rule, because none of my commits had a Looks: line. A new commit now has Looks: /preview-admin/sample/space, and bun scripts/gate.ts printed nothing locally. I pushed it, and I haven't seen the forge's re-run yet.

  • forge.json: /preview-admin/sample/space was not in the looks list in forge.json, so I added it; otherwise the forge could not take pictures of the space page. I assumed that path resolves to the sample repository's space page and did not open it to confirm. If it 404s, the looks step will fail, and that path is the thing to check.
  • Commit messages: the commit message rule reads the commit messages, so the Looks: line is in the new commit, not in the earlier Try: commit.
  • Code and tests: the legend code and tests are as before. The earlier run of the space tests, tsc and design-lint passed, and I did not re-run them since.
commented

The failure notice came with no log, and I couldn't reproduce a failure locally, so I made no code change and pushed nothing.

  • Latest check: the check on head 4af2e09 is still queued and hasn't started. That head is the one carrying the Looks: line that fixed the earlier gate failure, so the failure you were sent may be from the older head.
  • Local run: bun scripts/gate.ts and bun x tsc --noEmit both exit 0. The space tests, the look tests that read forge.json, and the legend tests all pass (26 tests).
  • Not run: scripts/fast.ts returned exit 2 because forge.json changed, which puts the diff in the full tier. I didn't run the full suite here, since the forge's check does that. That tier is the one place a failure could still show up.
  • Unverified: I haven't confirmed that /preview-admin/sample/space resolves. I added it to looks in forge.json so the forge can take pictures of the space page.

If the re-run fails, send me its log and I'll fix whatever it names.

commented

The space view now has a legend for size, colour, state and distance, built from space_model. The last push fixes the failing check.

Cause of the red: an earlier commit added /preview-admin/sample/space to app.looks in forge.json. That made 25 paths, and the manifest allows at most 24. It broke test/hardening.test.ts, test/forge-looks.test.ts and test/looks-owner.test.ts. I reverted forge.json to main.

Checks run: the three failing test files plus the space legend and page tests pass (49 tests), and tsc --noEmit is clean. I did not re-run the full suite here. The other tests in the log are red on main at 9d19e87 too, and the check does not count them against this pull.

Left out: the space page is no longer in the preview's looks. Adding it back means dropping another path or raising the cap, which is a call for a person to make.

Try it: open /trevato/forge/space and read the legend at the bottom left.

🤖 Generated with Claude Code

commented

The space view has a legend for size, colour, state and distance, built from space_model. The push fixes the gate failure from the last check. The gate passes locally; I haven't seen the forge's re-run of the check on this push.

Gate fix: the "before/after looks" rule wants a look of /preview-admin/sample/space in app.looks. forge.json is already at the 24-path cap, so adding it breaks test/hardening.test.ts, test/forge-looks.test.ts and test/looks-owner.test.ts. I added a No look: line to a commit message giving that reason, which the gate accepts instead.

Left out: no before/after pictures are taken for the space page. A person would have to decide which existing look to drop, or whether to raise the cap.

Try it: open /trevato/forge/space and read the legend at the bottom left.

🤖 Generated with Claude Code

Changes requested — before the latest push

The legend is real HTML in the server render, comes from space_model, and the closed-after-first-visit logic works. Three things stop it from landing.

First, fix on phones. Open by default, absolutely positioned over the canvas at up to 50vh, on a 360px screen it covers half the plane on the first visit. Make it a collapsed, in-flow control on narrow screens, or put it in the bottom bar.

Second, a returning visitor gets a flash. The server always renders open and the script closes it after first paint, so the legend jumps from open to closed (a layout shift). Render the closed state without script, or set the state before first paint.

Third, design: principles 6 and 1, listed on the lines below. Also add the legend to docs/features/space.md; the how-to is missing.

The test for box 1's localStorage behaviour only asserts CSS strings. Add a test that proves the script closes the legend on a second visit.

commented

I've addressed all of juniper's points and pushed. space-legend, space-page and hardening pass (24 tests), tsc --noEmit and design-lint are clean, and gate.ts printed nothing. I haven't seen the forge's check on this push.

Phones. The legend is now a 44px "Legend" summary in a new bottom block, .space-foot, above the scrubber. It starts closed, and on a phone the script never opens it. It still overlays the plane if someone opens it on a 360px screen. I capped it at 40vh and made opening it the visitor's choice rather than the default. I did not make it a pure in-flow control, because the canvas fills the whole screen behind the controls.

Flash. The server always renders the legend closed, so a returning visitor sees no jump. On a first visit, only at 40rem or wider, a small script (legendJs) opens it once and sets space-legend-seen in localStorage. It sits in the bottom block outside the page's flow, so opening it shifts no layout.

Design.

  • The border is gone, and the summary has a visible focus ring.
  • The sentences are short, with one line per state.
  • The .space-foot, .space-legend and .space-legend i swatch classes are listed in docs/design/areas/space.md.

Derived text. SIZE_SAYS and COLOUR_SAYS are still hand-written, shortened prose. DISTANCE_SAYS now builds its order from STATES and STATE_LEGEND, so a new or reordered state shows up there, and a test checks it. The ink strengths come from STATE_INK, shared with the canvas.

Tests. The new tests run legendJs against a stub page. They show it opens on a first wide visit, is closed on the second visit, and stays closed on a phone. I also added the how-to to docs/features/space.md.

Still open. The forge.json looks list is at its 24-path cap, so there are no before/after pictures of the space page. An earlier commit carries a No look: line for that.

Try it: open /trevato/forge/space.

🤖 Generated with Claude Code

commented

The gate failure is fixed and pushed. The Space legend change itself is as in the earlier commit (#12782).

The check failed on one comment line in src/web/space_model.ts. It was 114 columns, over the 100-column rule. I split it into two lines and changed nothing else.

bun scripts/gate.ts and bun x tsc --noEmit now pass. The three space test files that cover the legend (space-legend, space-model, space-page) pass, 22 tests in all. I did not run space-screen.test.ts or space-view.test.ts. scripts/fast.ts could not name a smaller set: its diff was too broad, so I chose the test files myself. The forge runs the full check on this push.

Approved

Earlier asks are met: the legend is closed in the server render, 44px summary with a focus ring, no border, a phone never auto-opens it, the classes are in docs/design/areas/space.md, the how-to is in docs/features/space.md and not README, and DISTANCE_SAYS and the inks derive from STATES/STATE_INK. Tests cover every State, the script on first/second/phone visits, and the server HTML. I could not fetch the 0b053e5 diff locally, so I read the head diff. Two things I would do next (non-blocking): 1) derive SIZE_SAYS and COLOUR_SAYS from the layout constants too, or add a test that ties them to the code, since they are still hand-written; 2) give the terminal space screen the same legend lines from STATE_LEGEND so both doors say the same words, and restore a space look once the looks cap is decided.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs