Skip to content

Redesign the page-not-found page as a message box on the 1994 desk - #2346

Merged
maniator merged 1 commit into
mainfrom
claude/project-thread-41dmj4
Nov 15, 2026
Merged

maniator merged 1 commit into
mainfrom
claude/project-thread-41dmj4

Conversation

@maniator

@maniator maniator commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Requested by Naftali · project thread

What & why

Naftali asked for a new 404 page that fits the recent updates. The old one was the Windows 3.1 page frame with four big buttons. The new one looks like the game on a computer:

  • A Windows 95 message box on the teal 1994 desk, with the warning icon, the missing address, and the buttons at the bottom right (Play the game is the default).
  • The startup screen's sunrise skyline across the top of the box, in the same colors. One tower is missing a floor: the sun shows through the gap, and the game's floor tag says 404.
  • A taskbar along the bottom: the Verticopolis button (back to the game), a pressed "Page not found" task, and the tray clock, read the way the desk's clock reads it.
  • The manual moved to help.verticopolis.com (Give the help site the game's menu bar, and move it to help.verticopolis.com #2339), and that host serves this same file for its missing pages. The page tells the two apart (notFoundSite): on the manual's host, or under /help on a build that serves it there, the title says "Verticopolis Player's Manual", the heading says "Page 404 isn't in the manual.", and Player's Manual is the default button.
  • Every way back to the game (the default button, the close box, the taskbar button) still closes a tab the game opened, as the manual does.
  • Phones get the same box at full width with the buttons stacked; the taskbar keeps only the Verticopolis button and the clock. The sunrise rises once on load and stands still with reduced motion.
  • Analytics: app_action not_found_view (game or help) and not_found_pick (game, manual, changelog, rooms, close, taskbar), a new "Page not found" section in docs/analytics-data-map.md and a dashboard tile. The missing address is never sent.

This PR does not depend on the desk PR (#2336); the page carries its own desk and taskbar styles in src/styles/not-found.css.

Type of change

  • Bug fix (non-breaking change that fixes an issue)
  • Classic-canon fix (matches the 1994 original for all towers)
  • Modern-mode feature (opt-in, "what the original couldn't do")
  • New player-facing feature (mode-agnostic)
  • Refactor / internal-only (no player-facing behavior change)
  • Docs / tooling

Game mode impact

n/a: the 404 page runs no game code.

Quality gates

  • npm run typecheck
  • npm run lint
  • npm test (648 files, 7,950 tests locally)
  • npm run build (twice in the pinned container for the screenshots; CI too)

Versioning

  • Added a .changes note with the right app: and crate: levels, or this PR changes no deployed path
  • Engine change: updated packages/verticopolis-engine/README.md and/or engine-rs/CRATE_README.md, or read both and put readmes: unchanged in the note, or this PR changes no engine source

app: patch (an existing page restyled, no new game feature), crate: none. The template needs a type box, and a new look for an existing page is closest to "New player-facing feature"; it adds no game feature, so the note stays at patch.

Complexity

Hot paths and call frequency (tier), sizes, complexity before and after, remaining scans and why, caches kept or replaced (HP-8), invalidation evidence, measurements: n/a: a standalone page outside the game. It renders once on load and once a minute for the tray clock; the two analytics codes add to a type union only.

Hot-path record (section 6): #2346 (comment) (the only section 1 path is a type-only change to src/analyticsCore.ts).

Screenshots / recordings

Rendered in the pinned Playwright container (mcr.microsoft.com/playwright:v1.61.1-jammy), new not-found shard; screenshot-determinism-check.ts not-found rendered the four shots identically twice.

Computer Phone
Game not-found not-found-phone
Manual not-found-help not-found-help-phone

The old page had no committed screenshot: it was the Windows 3.1 page frame with the heading "Page not found" and four large buttons in a two by two grid.

Notes for reviewers

  • Tests: src/notFoundPage.test.ts covers which site a path belongs to, the button order on each, the tray clock and its minute timer, each pick's analytics code (a spy) for a click and a middle-click (never a right-click), and the close-the-tab path on each way back to the game.
  • Review: /bmad-code-review round 1 found three patches, fixed in 842809b. The stand-in review at 842809b found the build loading the 404 sheet before the retro sheet (two rules lost); fixed in 190e222 by importing retro-page.css from not-found.css, with the shots rendered again. Its optional notes are in too: a real missing path in the game shots, and a plain face behind the taskbar task's checker.
  • The screenshot runner now also waits for notFoundReady. The manual's variant is staged with 404.html?at=manual, which moves the address under /help before the page reads it.
  • Help site: n/a, the manual has no page about the 404 page.
  • .page-links and .page-lede code left retro-page.css with their only user.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ms7trZuFqXAhnhQ4rim5CG

@vercel

vercel Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
verticopolis Ready Ready Preview Nov 15, 2026 11:37pm UTC

Request Review

@maniator maniator self-assigned this Nov 15, 2026
@github-actions github-actions Bot added this to the 4.x milestone Nov 15, 2026

Copy link
Copy Markdown
Owner Author

/bmad-code-review round 1 (lean pass, author run) at 842809b

Mode: no-spec (Acceptance Auditor checked against the thread's ask: retro 404 for the game and help.verticopolis.com, working links, screenshots). Layers run in one pass per CLAUDE.md: Blind Hunter, Edge Case Hunter, Acceptance Auditor, Hot-Path Auditor.

Triage

# Source Finding Class Resolution
1 edge auxclick also fires on a right-click (context menu), so the manual buttons counted a pick that never navigated, against the data map patch Fixed in 842809b: counts button === 1 only (MIDDLE_BUTTON), test covers both buttons
2 blind Middle-click counted on manual buttons but not on the game, close or taskbar links patch Fixed in 842809b: every link counts a middle-click
3 edge Tray clock redrew a minute after load, so it could lag the real minute by up to 59s patch Fixed in 842809b: msToNextMinute schedules just after each minute turns over, with a test
4 blind notFoundReady flag in production code dismiss Same pattern as galleryReady / previewReady, read only by the screenshot runner

Confirming pass on 842809b: no new patch findings. No defer findings.

Hot-path record (section 6), commit 842809b, whole diff. The only section 1 path touched is src/analytics*.ts (analyticsCore.ts, two names added to the AppActionName type union). src/notFoundPage.ts is its own Vite entry (404.html) and nothing in src/game/, src/render/ or src/ui/ imports it.

Item Result What was checked Findings and resolution
HP-1 clear notFoundPage.ts callers: only 404.html's module script; main() runs once per page load, the clock redraw once a minute. analyticsCore.ts change is type-only, no emitted code none
HP-2 n/a no collection work: the page maps a fixed four-link array none
HP-3 n/a one lit render per minute on a page with no game; no per-frame allocation none
HP-4 n/a no sorting none
HP-5 n/a no maps or sets added none
HP-6 n/a no id lookups or removals none
HP-7 n/a nothing ported or moved; the old 404 template was replaced, not carried none
HP-8 n/a no cache dropped or added; no engine code none
HP-9 n/a no HP-2 to HP-6 findings none
HP-10 n/a no optimization; the analytics union only grows none
HP-11 clear no WASM, host or build-setting change; vite.config.ts untouched (404 entry and precache exclusion unchanged) none
HP-12 clear no game renderer or HUD change; the 404 page's own refresh is one render per minute none

Copilot, Codex and PR-Agent are down (out of credits), so an independent stand-in review from another thread is still needed before this signs off.


Generated by Claude Code

@maniator
maniator marked this pull request as ready for review November 15, 2026 23:20
@chatgpt-codex-connector

Copy link
Copy Markdown
Codex Review Summary: ❌ Failed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ❌ Failed 2026-11-15T23:20:30.142624Z
We couldn’t complete this review. Comment @codex review to try again.
842809b Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

@github-actions

Copy link
Copy Markdown
Contributor

📸 Screenshot drift check

No drift: the committed screenshots already match a fresh deterministic generation. ✅

@maniator maniator left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

Independent stand-in review (Copilot, Codex and PR-Agent are down): stand-in-pr-review + /bmad-code-review, head 842809b

Mode: no-spec. I ran a lean pass with all four layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor against the PR body and the ask, and the Hot-Path Auditor). I also checked the built page in a browser and the routing on both hosts.

What I verified

  • Build and links on both hosts. I built with VC_HELP_ORIGIN=https://help.verticopolis.com, served dist/ in Chromium, and routed requests the way vercel.json does (on the help host, everything except assets/, styles/ and api/ goes to /help/..., and a document nobody answers gets the root 404.html).
    • help.verticopolis.com/rooms/hotell: the title bar says "Verticopolis Player's Manual" and the heading says "Page 404 isn't in the manual.". The default button is Player's Manual → https://help.verticopolis.com/, then Play the game → https://verticopolis.com/, Release notes → https://help.verticopolis.com/changelog, Every room → https://help.verticopolis.com/rooms.
    • verticopolis.com/towers/old-link and /helpful: the page is the game's, with Play the game → https://verticopolis.com/ as the default and the same manual links.
    • Every asset loads from both hosts (/assets/* skips the help rewrite; the favicon and manifest load through /help/). The only misses were Vercel's own /_vercel/* scripts and /api/ingest, which this local setup doesn't serve.
  • Vercel routing. vercel.json is unchanged. In production today (4.4.0), both help.verticopolis.com/<missing> and verticopolis.com/<missing> already return the root 404.html with a 404 status, so the new page will appear on both hosts. The manual's own Starlight 404 is never served. The PR's preview was still building when I checked.
  • Something to check after the 4.5.0 deploy (not caused by this PR). version.json still reports 4.4.0, and help.verticopolis.com/changelog and /rooms return 404 today, while verticopolis.com/help/changelog and /help/rooms return 200. The manual buttons on this page only work once the #2339 routing is live on production, so check them on the help host after the deploy.
  • Analytics. telemetryHostAllowed accepts *.verticopolis.com, so both hosts send events. The missing address is never sent. The data map and the dashboard tile match the codes in the code.
  • Tests. src/notFoundPage.test.ts passes (17 tests). It spies on trackAppAction and checks real behavior (which site, button order, click and middle-click counting, closing the tab), and its assertions would fail if that behavior broke. No new em-dashes; American English throughout.
  • CI at 842809b: every completed check is green, including screenshot drift and the not-found shard. e2e-general shards 1, 2 and 4 were still running when I posted.

Triage

# Source Finding Class
1 edge+auditor The built CSS order is reversed: notFound-*.css loads before retro-page-*.css, so body.nf-page (padding 0, 100dvh) loses to body.retro-page. The phone box is 28px narrower than designed, so it isn't full width as the PR body says (inline). patch
2 edge .btn.xs overrides .nf-win .nf-close for the same reason (inline). patch
3 blind .changes says app: patch, but the template ticks "New player-facing feature". Pick one: untick it, or say why patch. I agree patch fits a 404 restyle. optional
4 blind The game screenshots show "There is no page at /404.html", which no player will see. Staging a realistic path, as the manual variant does, would make the gallery shot more representative. optional
5 blind .nf-task uses repeating-conic-gradient with no fallback background line. Only very old browsers are affected. optional

No defer findings, so no backlog rows.

Hot-path record (section 6), commit 842809b, whole diff

The only section 1 surface touched is src/analyticsCore.ts. I traced the callers myself: the change adds two names to the AppActionName type union and emits no code. src/notFoundPage.ts is only reached from the 404.html entry, and nothing under src/game, src/render or src/ui imports it.

Item Result What was checked Findings
HP-1 clear main() runs once per load; the tray clock redraws once a minute (msToNextMinute), one timer at a time none
HP-2 n/a no collection work beyond mapping the fixed four links none
HP-3 n/a one lit render per minute on a page with no game; nothing per frame none
HP-4 n/a no sorting none
HP-5 n/a no maps or sets none
HP-6 n/a no id lookups or removals none
HP-7 n/a the old template was replaced, not ported none
HP-8 n/a no cache added or dropped none
HP-9 n/a no HP-2 to HP-6 findings none
HP-10 n/a no optimization claim none
HP-11 clear no WASM, host or vite.config.ts change; 404 still kept out of the precache (globIgnores) none
HP-12 clear no game renderer or HUD change none

History and version

There are two commits. The second ("Count middle-clicks only, tick the tray clock on the minute, add the shots") is mostly review fixes to the first, so consider folding them when you tidy. The branch is one commit behind main (the 4.5.0 release merge), so rebase before merge. crate: none is correct.

Verdict

NO-GO on 842809b. Fix the stylesheet order (findings 1 and 2), render the four not-found shots again in the pinned container, and push. The rest of the change is sound, so a re-review should be quick.

Reviewed against Verticopolis conventions (.github/copilot-instructions.md).


Generated by Claude Code

Comment thread src/styles/not-found.css Resolved
Comment thread src/styles/not-found.css Resolved

@maniator maniator left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

Stand-in re-review (stand-in-pr-review + /bmad-code-review, confirming pass), head 190e222

I read the diff from 842809b first, then the whole diff again.

The earlier findings, checked against the code

# Finding at 842809b Status at 190e222 Evidence
1 body.nf-page lost to body.retro-page in the build fixed I rebuilt with VC_HELP_ORIGIN=https://help.verticopolis.com. dist/404.html now links only notFound-*.css, with the retro rules first. In Chromium the body padding is 0px and the message box is 520px on a computer and 362px on a 390px phone.
2 .btn.xs overrode .nf-win .nf-close fixed The built close box is padding 0, font-size 11px, line-height 11px, 18px wide
3 (optional) app: patch vs the "New player-facing feature" box addressed The PR body now says why the box is ticked and the note stays at patch. I agree.
4 (optional) Shots showed /404.html addressed The game variant now stages /towers/old-link. The committed phone shot shows that path and a full-width box.
5 (optional) No fallback for repeating-conic-gradient addressed background: var(--r-light) comes first, and the gradient is still applied in Chromium

Both threads have replies naming 190e222 and are resolved, and the fix is in the code.

Confirming pass

  • I ran the host check again: help.verticopolis.com/rooms/hotell shows the manual version (Player's Manual is the default and goes to https://help.verticopolis.com/). verticopolis.com/towers/old-link and /helpful show the game version (Play the game is the default and goes to https://verticopolis.com/). Every asset loads on both hosts.
  • src/notFoundPage.test.ts passes (17 tests).
  • The @import only affects this entry. Other pages that use retro-page.css still link it themselves.
  • New patch findings: none. New defer findings: none.

Hot-path record (section 6), commit 190e222

This round changed only src/404.html, src/styles/not-found.css, scripts/scenes/notFound.ts and the four screenshots, none of which is a section 1 surface. My record for 842809b (HP-1 to HP-12: clear or n/a, no findings) carries unchanged to 190e222, because the one section 1 file (src/analyticsCore.ts, a type-only union change) is identical.

Verdict

CONDITIONAL GO on 190e222. Conditions:

  1. CI green on 190e222. When I posted, the test, e2e and screenshot jobs (including the drift check) were still queued or running.
  2. Before merge, rebase onto main: the branch is still on d0df552, one commit behind the 4.5.0 release merge. Fold the two fix commits into the first, or give them messages that state the step, as the clean-history rule asks. If the rebased tree matches 190e222 apart from main's changes, this GO carries. If anything else changes, it needs another look.

Reviewed against Verticopolis conventions (.github/copilot-instructions.md).


Generated by Claude Code

The 404 page now matches the game on a computer: a Windows 95 message box
on the teal 1994 desk, the startup screen's sunrise skyline across its top
with one tower missing floor 404, and a taskbar with the Verticopolis button
and a tray clock that turns over on the minute. The same file serves the
manual's own host, so the page tells a missing manual page from a missing
game page and puts the Player's Manual first there. Every way back to the
game still closes a game-opened tab.

not-found.css imports retro-page.css and is the page's only stylesheet, so
its rules come after the shared ones in the build.

Analytics: app_action not_found_view (game or help) and not_found_pick
(which button; a click, Enter or middle-click, never a right-click), in the
data map and a dashboard tile. The screenshots get their own shard,
not-found, rendered in the pinned Playwright container.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ms7trZuFqXAhnhQ4rim5CG
@maniator
maniator force-pushed the claude/project-thread-41dmj4 branch from 190e222 to ad21e4b Compare November 15, 2026 23:30

Copy link
Copy Markdown
Owner Author

Condition 2 of the CONDITIONAL GO is done. I folded the three commits into one (ad21e4b). Its tree matched 190e222 exactly before the rebase (git diff 190e222 was empty). I then rebased it onto main at cb85b56 (the 4.5.0 release merge). main changed none of this PR's files, so the PR's diff is unchanged. The 404 tests and the file-size check pass on the rebased head. I'm waiting on CI for condition 1.


Generated by Claude Code

@maniator
maniator enabled auto-merge November 15, 2026 23:40
@maniator
maniator merged commit e5e1fc3 into main Nov 15, 2026
46 checks passed
@maniator
maniator deleted the claude/project-thread-41dmj4 branch November 15, 2026 23:42

This branch was successfully deployed

1 active deployment
Preview — ad21e4bb Deployed Nov 15, 2026 by vercel[bot]
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.

2 participants