Skip to content

Document the desktop in full and count every new button - #2354

Merged
maniator merged 2 commits into
mainfrom
claude/project-thread-a68jib
Nov 16, 2026
Merged

maniator merged 2 commits into
mainfrom
claude/project-thread-a68jib

Conversation

@maniator

@maniator maniator commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Requested by Naftali · project thread

What & why

Naftali asked for the help site to cover the 1994 desktop from 4.6.0 (#2336) in full, and for every new button, title-screen buttons included, to report proper analytics.

Help site. The Desktop page (help-site/src/content/docs/desktop.mdx) now explains:

  • each window's title bar buttons (_ □ ✕, which window has which, and that the tower's ✕ is File > Close);
  • what each window holds: the tower (menu bar, floor numbers, hint, status bar), Info (Rating, Date, Time, Fund, Pop, Traffic, the four speed buttons, Undo/Redo, the Update button), Tools, the Map, the Bulletin and Tower Info;
  • the Verticopolis menu item by item, with each item's menu-bar twin, and what it leaves out on the opening screen;
  • the opening screen's buttons (Continue, Open Tower…, New Tower, How to Play, Sponsor, Install, the speaker) and its taskbar;
  • the keys for the taskbar and window menus.
    The privacy page now says buttons are counted along with menu commands and windows.

Analytics audit. Before this PR, these new buttons sent nothing, or could not be told apart:

Button Before Now
Taskbar window buttons only the resulting desk_window min/restore, focus presses lost desk_task <window>_front, _min, _restore (title_front on the title screen)
Verticopolis button (opening without a pick) nothing desk_start_open title or tower, plus a funnel tile to desk_start
Tray monitor and speaker nothing (speaker only as a bare mute) desk_tray display or sound
Window menu (right-click on title bar or taskbar, Shift+F10) only the resulting verb desk_win_menu_open taskbar or title_bar, desk_win_menu <window>_<command>
Tower ✕ and Control Panel ✕ nothing desk_window tower_close, control_panel_close (Map, Bulletin and Tower Info keep their own events)
Title screen in its desk window nothing desk_title_shown, once per page life
Title screen buttons only Open, Sponsor and Install had a source; Continue and New Tower had none title_pick continue (button, Esc or click outside), open, new, help, mute, install, sponsor
Manual's Play / Back to game (title bar and front page, #2349) nothing help_game_link bar_play, bar_back, front_play, front_back

A menu that presses a title-screen button from a script (File > New… and Options > Sound on the title screen, the desk's Verticopolis menu) stays that menu's own menu_pick or desk_start and never adds a title_pick. isTrusted is how the listener tells them apart. The desk's codes now live in src/ui/desk/deskAnalytics.ts, so deskController.ts stays at the 500-line ceiling. docs/analytics-data-map.md documents every row, and so does docs/ui/desk-windows.md. It also gains a short section on the help site's events, which were missing from it.

Dashboard. scripts/posthog-dashboard.mjs widens "The desk: windows, taskbar and Control Panel" to the new codes and adds "The desk: Verticopolis menu opened to picked" (funnel), "Title screen: buttons pressed" and "Help site: Play and Back to game".

Closes n/a (owner request in the project thread)

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: help pages and analytics only; no gameplay or simulation change.

Quality gates

  • npm run typecheck
  • npm run lint
  • npm test (locally: the touched suites and src/tests; full run in CI)
  • npm run build (CI)

Versioning

  • Added a .changes note with the right app: and crate: levels (app: patch for the manual page, crate: none)
  • This PR changes no engine source

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: not significant under section 5. Every new call runs on a single player press, never per frame or per tick. wireTitlePicks adds one capture click listener to the document for the page life; each click does one closest() walk up the element's ancestors and one property lookup, O(depth), and sends nothing unless the click lands on a title-screen button. The desk handlers add one beacon call to presses that already ran a handler. No scan, cache or observer was added or removed.

Hot-path record (section 6): pending the review thread's skill run on this PR.

Screenshots / recordings

None: the help page reuses the existing desktop screenshots (docs/screenshots/features/desk-*.png), and no game UI changes visually. Its share card is unchanged, since the page's title and description are unchanged.

Notes for reviewers

  • title_pick continue is sent from showTitleScreen's onContinue, so it counts all three ways Continue happens. The delegated listener skips Continue on purpose so nothing is counted twice.
  • A window menu Close on the tower now calls mb-close directly instead of clicking the tower's ✕, so a menu Close is a desk_win_menu tower_close row and never also a desk_window tower_close.
  • The dashboard tiles reach PostHog only when the script runs or through the connector (see the project's dashboard sync note).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ms7trY5bPq1ye4TemCpsse

@vercel

vercel Bot commented Nov 16, 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 16, 2026 1:27am UTC

Request Review

@github-actions github-actions Bot added this to the 4.x milestone Nov 16, 2026
@maniator
maniator marked this pull request as ready for review November 16, 2026 01:17
@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-16T01:17:39.019990Z
We couldn’t complete this review. Comment @codex review to try again.
489a7ec 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.

Stand-in review (Copilot, Codex and PR-Agent down) + /bmad-code-review, head 489a7ec

Codex failed on this head (usage limit) and Copilot and PR-Agent are out of credits, so this is the stand-in-pr-review run plus the bmad-code-review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor, Hot-Path Auditor) in one lean pass. Routing: bmad (help site, analytics, UI plumbing; no engine, save or gameplay path).

What I checked

  • Help text against the code and the live 4.6.0 desk: title-bar buttons per window (deskWindow.ts adds _ to every framed window, □ only with canMax, ✕ on tower/Map/Bulletin/Tower Info/Control Panel), double-click to maximize, the tower title (<name> - Verticopolis), Info's meters and buttons (index.html #topbar, desk.css), traffic labels and the · 12F floor, WD1 time, the Verticopolis menu items and what the title screen leaves out (START_ITEMS, no controlPanel handler, mb-close hidden), Shift+F10 / ContextMenu, arrows, Enter, Esc, every linked page and anchor. All correct apart from the two inline findings.
  • Analytics: every new code is in AppActionName, the data map table, desk-windows.md and the dashboard script; names follow the existing desk_* / *_pick scheme; the relay has no action allowlist to update. Scripted title-button presses (ON_TITLE_SCREEN, desk start) stay out of title_pick via isTrusted; Continue reports once from onContinue; a window-menu Close on the tower no longer double-counts; the help site's File > Play item is not a[data-game-link], so help_game_link and help_menu_pick game never overlap; the relay uses sendBeacon/keepalive, so bar_play/front_back survive the navigation or tab close.
  • Tests: the 8 touched suites pass locally (115 tests). They mock analyticsActions and assert the calls, and each would fail if its wiring were removed.
  • Version: app: patch, crate: none, Player line present, no version edits. History: 2 logical commits.

Findings

# Severity Triage Where Finding
1 medium patch desktop.mdx:141 (+ data map 196, titleScreen.ts:63, titlePicks.ts:14) On the desk, a click outside the title window does not continue; a click on the window's own empty face does. Inline.
2 low patch desktop.mdx:70, :67 The Info strip's one-time Install chip is missing; the 0 key is Pause, not a speed. Inline.
3 low defer src/ui/Onboarding.ts safeDismiss (pre-existing, #2336) On the desk, a click anywhere on the title window's empty gray face or its poster sky drops the player into their tower (Continue), because #splash is the window itself there. Probed on production: those points hit #splash. A safe action, but surprising for a click on artwork. Suggested fix: under body.desk-title, skip the click dismiss (Esc stays), or dismiss on a click on the desk outside the window. Needs a backlog row plus its mirrored issue, or fix it here if you'd rather not file.

Optional, not blocking (one lens each): help_game_link wiring in Header.astro has no test of its own (only gameLinkDetail is tested); a middle-click on the title screen's Sponsor counts as sponsor_click but not title_pick; WindowMenu.show derives taskbar/title_bar from the above layout flag, so a future caller that opens upward from elsewhere would be misfiled (a named from argument would read better).

Hot-path record (section 6), commit 489a7ec, whole diff

Item Result What was checked Findings and resolution
HP-1 clear reportTitlePick (document capture click, every click in the page), trackDesk*/trackWindowMenu* (taskbar, tray, window menu, title-bar ✕ handlers), DeskController.changed/taskPressed, WindowMenu.show, DeskTaskbar.openMenu, DeskTitle.show, showTitleScreen.onContinue, Header.astro link listeners: all per-command (one player press) or once per page life; none reached from runFrame, the HUD tick or a step none
HP-2 clear no collection walks; titlePickOf is one closest() up the target's ancestors (DOM depth, about 20) per click none
HP-3 clear one detail string per press; no allocation per frame none
HP-4 n/a no sorting added none
HP-5 clear hasOwnProperty lookups on two constant 6–7 key objects none
HP-6 n/a no id lookups or removals added none
HP-7 clear moved NAME table into deskAnalytics.ts unchanged; changed() rewrite keeps the first-move latch (same branches) none
HP-8 n/a no cache added, dropped or bypassed none
HP-9 n/a no findings needing a remedy none
HP-10 clear analytics only; the one behavior change (tower window-menu Close calls mb-close directly instead of the ✕) runs the same File > Close path, covered by deskController.test.ts none
HP-11 n/a no WASM, host or build change none
HP-12 clear no per-frame or HUD-refresh work; the capture listener costs one ancestor walk per click and sends nothing off the title screen none

Nothing here gets slower: every added call sits on a player press.

Verdict: CONDITIONAL GO at 489a7ec. Conditions:

  1. Fix findings 1 and 2 (docs and two code comments only).
  2. Record finding 3 as a backlog row with its issue, or fix it in this PR.
  3. Rebase onto main: it is 3 merges behind (#2342, #2345, #2351), which touch docs/analytics-data-map.md, scripts/posthog-dashboard.mjs and src/analyticsAppActions.ts. git merge-tree says it applies cleanly.
  4. CI green on the new head (e2e, test and screenshot capture were still running at review time).

The fixes make a new commit, so it needs a quick re-check from me before merge; if it only touches the docs and comments named above, the hot-path record carries.

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


Generated by Claude Code

Comment thread help-site/src/content/docs/desktop.mdx Resolved
Comment thread help-site/src/content/docs/desktop.mdx Resolved
The Desktop page now covers each window's title bar buttons, what the
tower, Info, Tools, Map, Bulletin and Tower Info windows hold, the Info
strip's meters and buttons, the Verticopolis menu item by item, the
opening screen's buttons and taskbar, and the desktop's keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ms7trY5bPq1ye4TemCpsse
The 1994 desk and the title screen now report what each new button
did: taskbar presses, the Verticopolis menu opening, the tray, window
menus, the tower's and Control Panel's close buttons, the title window
showing, each title-screen button (title_pick) and the manual's Play
and Back to game links. The desk's codes move into deskAnalytics.ts,
the data map and privacy page say what is counted, and the dashboard
script gains the matching tiles.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ms7trY5bPq1ye4TemCpsse

@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.

Re-review (stand-in + /bmad-code-review), head 5c4b586

I read the diff from my last verdict's head (489a7ec) first. The branch is rebased onto main at d6a8367, and it is 2 commits with no fixup or merge-from-main commits. Comparing the PR's own diff before and after the rebase, only these changed:

  • help-site/src/content/docs/desktop.mdx: the Continue row now says only that Esc does the same. Info lists the one-time Install button ("File > Install app", which matches #btn-install-menu in src/index.html). Pause shows 0 and the speed row reads 1 to 3. Finding 1 and finding 2 fixed.
  • docs/analytics-data-map.md, the dashboard tile description, and the comments in titleScreen.ts and titlePicks.ts: they now say "a click on the title screen's empty background". The data map also explains what that means on the desk. This matches the production probe. Only comments changed, no code.
  • _bmad-output/implementation-artifacts/backlog.md: the row desk-title-click-continues (P3, issue #2355) is added. #2355 is open with bug and P3 labels, and its body follows the bug form. Finding 3 recorded.

Both review threads are fixed in the code and resolved. The touched suites pass on this head (120 tests, backlog mirror test included). No new findings.

Hot-path record: the record from 489a7ec carries over. The fix round changed only docs, a backlog row and two code comments, and nothing that runs on a section 1 surface. I confirmed the rest of the PR's diff is unchanged by the rebase.

Verdict: GO at 5c4b586. CI was still running at review time (e2e, test, capture, smoke). As usual, merge waits until every required check is green.

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


Generated by Claude Code

@maniator
maniator merged commit 0e8e6b8 into main Nov 16, 2026
48 checks passed
@maniator
maniator deleted the claude/project-thread-a68jib branch November 16, 2026 01:38

This branch was successfully deployed

1 active deployment
Preview — 5c4b5868 Deployed Nov 16, 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