Skip to content

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

Closed
maniator wants to merge 2 commits into
mainfrom
claude/project-thread-vpvjev
Closed

maniator wants to merge 2 commits into
mainfrom
claude/project-thread-vpvjev

Conversation

@maniator

@maniator maniator commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Requested by Naftali · project thread

What & why

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.

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

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, and a rollback moves both. Previews and staging keep the manual at /help on their own host, as today; staging gets no separate help host.

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 claude/project-thread-vpvjev to try it on this preview, 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 claude/project-thread-vpvjev, 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.

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 (CI. The help site, help address, help menu, About and Help, 404, update prompt, compare and telemetry suites pass locally.)
  • 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.

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.
  • The game's "could not open" messages now name help.verticopolis.com.

Generated by Claude Code

https://claude.ai/code/session_01Ms7trYsinXUbmcSQZ3d6N7


Generated by Claude Code

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

Request Review

@github-actions

Copy link
Copy Markdown
Contributor

📸 Screenshot drift check

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

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

Moved to #2339 (branch help-subdomain) at the owner's request; same commits.


Generated by Claude Code

@maniator maniator closed this Nov 15, 2026
@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.

This branch was successfully deployed

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