Skip to content

Give the help site the game's menu bar, and move it to help.verticopolis.com - #2339

Merged
maniator merged 2 commits into
mainfrom
help-subdomain
Nov 15, 2026
Merged

maniator merged 2 commits into
mainfrom
help-subdomain

Conversation

@maniator

@maniator maniator commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Requested by Naftali · project thread

What & why

Replaces #2338, moved from its old branch to help-subdomain at the owner's request.

Two changes Naftali asked for after #2316:

  1. The game's menu bar on the help site. The Win95 menu bar is now the top row of every help page, above the navy title bar, where the game draws it.

    • File: Back to Game (or Play Verticopolis outside a game tab), Print….
    • Edit: Find… (Starlight's search), Copy Link to This Page.
    • Options: Light, Dark, Match My Device (drives Starlight's theme switch).
    • Help: What's New, Report a Problem…, Sponsor Verticopolis.

    The bar's behavior is the game's own MenuBar (src/ui/menuBar.ts). Its styles move unchanged into a shared src/styles/menu-bar.css, which both the game and the help site import. Each pick sends app_action help_menu_pick with the item's code, and the PostHog dashboard gets a "Help menu picks" tile for it.

  2. The manual moves to help.verticopolis.com, with clean addresses (help.verticopolis.com/rooms/, Naftali's pick). On Android the installed app keeps in-scope links in its own window, so the manual replaced the game. On its own host, Help opens in the browser over the running game.

    • scripts/vercel-build.sh sets VC_HELP_ORIGIN=https://help.verticopolis.com in a production build. The help build (help-site/site.mjs) then sits at the root of that host, with its canonical links, sitemap, robots.txt and share cards there. A Satteri hast plugin (astro.config.mjs) and siteHref point the pages' /help/... and game links at the right address. The Markdown keeps writing /help/..., because the game's own Help window reads the same files.
    • The game's links into the manual go through helpUrl (src/helpAddress.ts, __HELP_ORIGIN__): the Help button, the mode badge, the welcome, the update prompt, About's privacy link, the Classic and Modern summary, the gallery and the 404 page.
    • vercel.json moves to ordered routes. Vercel checks its files before any rewrites run, so the game's index.html would otherwise win at help.verticopolis.com/. Requests on the help host are now served from dist/help/, except /api/ (the analytics relay), /_vercel/, and /assets/ and /styles/ (the shared 404 page). verticopolis.com/help/... answers with a 308 to the same page on the help host, and the gallery redirect goes there in one hop. The cache headers are the same rules as before, now also matching the help host's /_astro/ and /pagefind/ paths.
    • Analytics need no change: the relay already accepts *.verticopolis.com. The help page view and the landing read the base from Astro, so they report the same page names on the new host. The dashboard's landing and help page view descriptions now name the new host.
    • The 31 share cards print help.verticopolis.com/<slug>/, redrawn in the pinned Playwright image.
    • The production deploy check fetches the help/* files from help.verticopolis.com.
    • help-site.yml adds a second build with VC_HELP_ORIGIN set. It fails on any /help/ link left in the output and runs the link check on that build too.

How the manual ships per release

It stays in the same Vercel project and the same build, so every production deployment carries its matching manual. help.verticopolis.com is a second domain on that deployment, so the game and the manual can never drift apart. Previews and staging keep the manual at /help on their own host, as today; staging gets no separate help host.

Rollback caveat: a rollback moves both together, except across this PR. Promoting a deployment from before this PR leaves help.verticopolis.com serving the game, because that deployment has no help-host routes. If that rollback is ever needed, move the domain off Production (or point it back to the branch) at the same time.

Before this merges (owner setup)

The MCP token can't add domains or env vars (403), so the owner adds:

  1. Domain: help.verticopolis.com on the project. Vercel already hosts the DNS, so it configures the record and certificate itself. First assign it to the Git branch help-subdomain to try it on this preview (done), then switch it to Production right before the release that carries this PR deploys.
  2. To try it on the preview only: a Preview env var VC_HELP_ORIGIN=https://help.verticopolis.com scoped to branch help-subdomain, then a redeploy. Delete it at merge. While it is set, this branch's *.vercel.app preview builds the manual for the help host, so its own /help links break. That is expected.

The production deploy must not go out before the domain is on Production, or verticopolis.com/help would redirect to a host that doesn't answer.

After the production deploy, check that verticopolis.com/help/rooms/?from=game lands on help.verticopolis.com/rooms/?from=game with the query kept, and that help_page_view events arrive from the new host.

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 help site's chrome, its address and the game's links to it. No simulation change.

Quality gates

  • npm run typecheck
  • npm run lint
  • npm test (the full unit project passed locally, 6262 tests; CI runs the rest)
  • npm run build (CI. The help site builds locally in both modes: /help, with the link check at 0 broken, and the help host root.)

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

Complexity

n/a: no hot path. The help menu runs only on a click, and helpUrl runs only when the player opens a manual link. The game's menu bar CSS moves to its own file and keeps the same rules in the same cascade position (src/styles.css imports it right before game/menubar.css). The routes add no function or middleware: game requests match only the same header rules as before.

Hot-path record (section 6): no hot-path surface

Screenshots / recordings

The local builds (desktop and phone) are in the project thread. The preview link is in the Vercel comment. The owner confirmed help.verticopolis.com serving the manual with the menu bar on top from this branch.

Notes for reviewers

  • The help header grows by the bar's 24 px (--sl-nav-height). The bar sits on top, and the title bar's logo and the phone's menu button keep their old size, moved down under it (help-site/src/styles/help.css).
  • In a root build, every built link was checked: no /help/ link is left, game links are absolute to verticopolis.com, and the search results, room pictures (catalog.json) and menu links resolve, with no 4xx in the browser.
  • src/tests/helpSite.test.ts loses its vercel.json header test. It parsed configuration rather than behavior, which project policy rules out, and the routes format replaced what it read.
  • src/analyticsCore.ts comments were trimmed to stay at the 500-line ceiling.
  • The game's "could not open" messages now name help.verticopolis.com.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ms7trYsinXUbmcSQZ3d6N7

@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 10:48pm UTC

Request Review

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

The docs preview for this pull request was removed when it closed.

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

Review of acaefefd9 (bmad-code-review layers + stand-in review)

Copilot, Codex and PR-Agent are out of credits, so this is the stand-in review alongside /bmad-code-review (Blind Hunter on the diff, Edge Case Hunter with the repo and the deployment open, Acceptance Auditor against the PR body), run as one lean pass.

What I checked beyond the diff

  • Production build in help-host mode (VC_HELP_ORIGIN=https://help.verticopolis.com, game + manual): resolved all 134 distinct links and asset URLs in the 31 built pages against the new routes (help host rewrite to dist/help/, with /api/, /_vercel/, /assets/, /styles/ passed through). 0 unresolved, no /help/ link left, canonical/og:image/sitemap on the help host, game links absolute to verticopolis.com, the bundles call /api/ingest, /_vercel/insights and /pagefind/ on the help host as intended.
  • This branch's deployment (dpl_5svsHT…, on help.verticopolis.com via the branch domain): /help/rooms/?from=game on the help host redirects and serves the Rooms page, /robots.txt is the manual's, /api/ingest reaches the function (405 on GET, as expected), /version.json keeps no-store, and an unknown path still gets the game's 404 page with status 404, so the move to routes did not lose the custom 404.
  • Domains: www.verticopolis.com is a domain-level 308 to the apex, so the apex-only has host rule is enough. staging.verticopolis.com builds with VERCEL_ENV=preview, so staging and previews keep /help and the host rules never match them.
  • Service worker: unchanged. /help/ stays in the navigation denylist and help/** out of precache, and the game's links now leave the worker's origin entirely.
  • Analytics: originAllowed and telemetryHostAllowed already accept *.verticopolis.com; help_page_view details keep the same names under the root base.
  • CSS move: menu-bar.css is byte-for-byte the old block, imported at the same cascade spot.
  • History: two logical commits, no fixups. Change note app: minor fits a new feature.

Findings (inline)

  1. High, patch: CI red. parityHelpPage.guard.test.ts still matches the old URL in its regex (test, test-engine (unit) fail).
  2. High, patch: deploy-production.yml's post-deploy byte check curls every dist/help/** file on verticopolis.com without -L, so the first release with this PR fails after going live and skips the release archive.
  3. Medium, patch: help_menu_pick has no tile in scripts/posthog-dashboard.mjs (help + analytics rule), and two tile descriptions still say /help.
  4. Low, patch: the committed share cards print verticopolis.com/help/....
  5. Low, optional: /gallery takes two redirects in production.

Not inline (low, mention only)

  • The PR body says "a rollback moves both". A vercel promote to a deployment from before this PR has no help host routes, so help.verticopolis.com would serve the game at / and 404 the manual pages. Worth a line in docs/ or the body.
  • Query strings on the new 308s: I could not confirm through deployment protection whether ?from=game survives verticopolis.com/help?from=game → help host. Current game builds link the help host directly, so only an old cached tab is affected; worth one check on production after the domain flip.
  • help-site.yml link-checks only the /help build; the root build that actually ships has no link check in CI (I ran it by hand). Adding VC_HELP_ORIGIN=… check-links would keep it honest.

Hot-path record

The PR body says "no hot-path surface", but the diff touches vite.config.ts, src/ui/ and root modules src/ui/ imports (src/helpAddress.ts, src/analyticsCore.ts). The section 6 table is in the next comment: no findings, every changed path is click-time or module-load.

Verdict

NO-GO at acaefefd91e6d016a2da24c42be8c773e954aaa3. Fix findings 1 to 4; then it is a GO from me once CI is green, with the standing condition from the PR body that help.verticopolis.com is moved to Production before the release deploys.

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


Generated by Claude Code

Comment thread src/tests/parityHelpPage.guard.test.ts Resolved
Comment thread vercel.json Resolved
Comment thread src/analyticsCore.ts Resolved
Comment thread help-site/site.mjs Resolved
Comment thread vercel.json Resolved

Copy link
Copy Markdown
Owner Author

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

Item Result What was checked Findings and resolution
HP-1 clear Traced every changed production function to its caller: helpUrl (src/helpAddress.ts) runs in openPageInTab / showHelp (Help click), openLinksInNewTab (compare link click), releaseNotesHref (update prompt render, once per new build), welcome helpLink (one-time modal), and at module load for PRIVACY_HREF, NOT_FOUND_LINKS and the gallery links. wireHelpMenu runs only on help pages. None is reached from a tick, frame, HUD refresh or command. none
HP-2 clear helpUrl is one anchored regex over a short path; wireHelpMenu's onOpen loops over three theme items when a menu opens. No collection work. none
HP-3 clear One string per click or render in helpUrl/fromGameHref; nothing per frame. none
HP-4 n/a No sorting added or changed. none
HP-5 n/a No containers or hashing added; THEME_ITEMS is a three-entry constant. none
HP-6 n/a No id lookups or removals. none
HP-7 clear Moved code: the menu bar CSS block moved to src/styles/menu-bar.css unchanged (diffed against main) and imported at the same cascade position, so selector matching and layout are the same. none
HP-8 n/a No cache added, dropped or bypassed. none
HP-9 n/a No HP-2 to HP-6 findings to remedy. none
HP-10 clear helpUrl is a pure function of its path and a build-time constant (__HELP_ORIGIN__); unit tests cover both modes. No result changes for the /help build. none
HP-11 clear vite.config.ts adds one define (__HELP_ORIGIN__), a string constant; no engine, WASM, worker or chunking change. The production build splits helpAddress into a tiny shared chunk, loaded with the 404 page and the game. none
HP-12 clear No renderer, HUD or per-frame UI path changed; the menu bar CSS is the same rules in the same order. none

Generated by Claude Code

The manual draws the game's Win95 menu bar under its title bar, with File
(back to the game, print), Edit (find, copy this page's link), Options
(light, dark, match the device) and Help (what's new, report a problem,
sponsor). The bar's behavior is the game's MenuBar, its styles move to a
shared src/styles/menu-bar.css that both import, and each pick reports
app_action help_menu_pick with the item's code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ms7trYsinXUbmcSQZ3d6N7
A production build now puts the manual at the root of its own host, so its
pages read help.verticopolis.com/rooms/ and the installed Android app opens
Help in the browser over the running game instead of in place of it. Every
other build (previews, staging, CI, local) keeps it under /help on its own
host.

- scripts/vercel-build.sh sets VC_HELP_ORIGIN for production. The help
  build reads it for its base, its canonical links and sitemap, and a
  Satteri hast plugin points the pages' /help/... and game links at this
  build's address. The game reads it (src/helpAddress.ts) for every link
  it opens into the manual.
- vercel.json moves to ordered routes so the help host can be matched
  before the filesystem: help.verticopolis.com serves dist/help/, and
  verticopolis.com/help/... redirects (308) to the same page there.
- Drop the test that parsed vercel.json's headers; it read configuration,
  not behavior, and the routes format replaced what it parsed.

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

Copy link
Copy Markdown
Owner Author

Re-review of b88844029 (bmad-code-review + stand-in review, round 2)

The branch is rebased onto main at b3eab2e76 (#2335). git range-diff shows the menu bar commit unchanged and the move commit changed only by the fixes below. History is still two logical commits.

All five findings from round 1 are fixed in the code. I checked each one against the diff:

  1. Parity test: HELP_LINK is now built from HELP_URL by escaping, and test-engine (unit) passes on this head (it failed on acaefef).
  2. Deploy check: deploy-production.yml maps help/<rest> to $HELP_URL/<rest> and everything else to $PRODUCTION_URL, with the error line naming the URL it fetched.
  3. Dashboard: posthog-dashboard.mjs has a "Help menu picks" tile (help_menu_pick by detail), and both tile descriptions name the new host.
  4. Share cards: gen-help-cards.mjs prints help.verticopolis.com/<slug>/. I opened rooms.png and it reads help.verticopolis.com/rooms/.
  5. Gallery: a host-scoped /gallery rule goes to https://help.verticopolis.com/rooms/ in one hop, ahead of the /help/rooms/ fallback for previews and staging.

Two fixes go past what I asked for. help-site.yml now also builds the manual for the help host, fails on any href/src still under /help, and runs the link check with root paths. check-links.mjs takes a base, with a unit test for the root case. The step comes last, after the /help-mode checks, so overwriting dist/help does not affect them. help-site (build) passed on this head.

No new findings. The new code is CI, scripts and tests, none of them a hot-path surface, so the round-1 hot-path record (no findings) stands for the code it covered, which is unchanged here.

Verdict

GO at b88844029330a47ed8a33e36867f2e920aa3d362, on two conditions:

  • CI must finish green on this head. test, the e2e shards, the screenshot capture and rust were still running when I checked. test-engine (unit), the test-engine (host) shards and help-site (build) have passed.
  • As the PR body says, help.verticopolis.com must move from the branch to Production before the release that carries this PR deploys. The deploy check now fetches every manual file from that host.

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


Generated by Claude Code

@maniator
maniator marked this pull request as ready for review November 15, 2026 22:55
@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-15T22:55:44.555401Z
We couldn’t complete this review. Comment @codex review to try again.
b888440 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.

@maniator
maniator merged commit d0df552 into main Nov 15, 2026
51 checks passed
@maniator
maniator deleted the help-subdomain branch November 15, 2026 23:05
@maniator
maniator restored the help-subdomain branch November 15, 2026 23:07

This branch was successfully deployed

1 active and 1 inactive deployments
github-pages — b8884402 Deployed Nov 15, 2026 by maniator via docs-preview (remove) / docs-pages (deploy) #809
Preview — b8884402 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