feat: offer installed apps a reload when a new build is live

iOS keeps the Home Screen app alive in the background and players rarely
force close it, so they kept playing an old build long after a deploy.
There was no way for a running copy to learn that a newer one was live.

Each production build now carries an id: BUILD_ID, else GITHUB_SHA (CI
and the Alchemy deploy), else the local commit with a timestamp when the
tree is dirty, else a timestamp. A small Vite plugin defines it as
__BUILD_ID__ and writes dist/version.json. The dev server uses "dev" and
never checks; the tests use "test".

The game fetches version.json with no-store and a time query when the
page becomes visible again, on a back forward cache restore, on window
focus, and every five minutes on the title, pause, end screens, and the
break between waves. update only records the newer build as an Option,
and failures are ignored. A "New version ready" chip shows on those quiet
screens, never mid-wave, and tapping it reloads. public/_headers serves
version.json no-store and the HTML no-cache.

Story and Scene tests cover the checks, the chip on each quiet screen,
the reload, failures, and the subscription filters. tools/audit/shots26.ts
shoots the chip layout and runs the end to end rebuild and reload check.

Author: Tanner-Scadden

AGENTS.md

@@ -72,7 +72,7 @@ Before you finish a change, run `typecheck`, `lint`, `test`, and `build`. All fo
 | `src/effectsView.ts`   | Bullets, decals, particles, blasts, popups, and rattling doors         |
 | `src/hud.ts`           | Hearts, money, the streak, gun and trap slots, and the round text      |
 | `src/wavePreview.ts`   | The door markers that preview a wave, and their spoken text            |
-| `src/touchControls.ts` | Sticks, ghost sticks, icon buttons, gun slots, and the thumb corner   |
+| `src/touchControls.ts` | Sticks, ghost sticks, icon buttons, gun slots, and the thumb corner    |
 | `src/menus.ts`         | Mode buttons, the new zombie card, corner icons, tips, rotate notice   |
 | `src/pauseHelp.ts`     | The pause screen's panel of controls and tips for each device          |
 | `src/powerupView.ts`   | Pickups, callouts, the boost aura, and HUD timers on canvas            |
@@ -84,6 +84,8 @@ Before you finish a change, run `typecheck`, `lint`, `test`, and `build`. All fo
 | `src/sprite.ts`        | Pixel maps turned into canvas shapes                                   |
 | `src/icons.ts`         | Pixel maps turned into SVG icons for the HTML buttons                  |
 | `src/prng.ts`          | The seeded random number generator                                     |
+| `src/version.ts`       | The running build id, the `version.json` check, and reloading          |
+| `src/updateChip.ts`    | The "New version ready" chip shown on quiet screens                    |
 | `src/constants.ts`     | The view size, speeds, and other tuning numbers                        |
 
 ### Deploying
@@ -107,6 +109,16 @@ Credentials: locally, the Cloudflare API token is in the macOS keychain under `c
 
 GitHub Pages is gone: its workflow is deleted and the site is disabled. Cloudflare Workers Builds is not connected either; the Deploy workflow is the only deploy path, so do not connect the repo in the Cloudflare dashboard.
 
+#### How updates reach installed apps
+
+iOS keeps a Home Screen app alive in the background, so players can keep an old build for days after a deploy. There is no service worker, on purpose. Instead:
+
+- **Build id.** A small plugin in `vite.config.ts` stamps every production build with an id: `BUILD_ID` if set, else `GITHUB_SHA` (CI and the Alchemy deploy in CI), else the local commit (with `-dirty-<timestamp>` when the tree has uncommitted changes, since a local deploy ships them), else a timestamp. The id is the compile-time constant `__BUILD_ID__` and is also written to `dist/version.json` as `{ "build": "<id>" }`. `bun dev` uses `dev` and never checks; the tests use `test`.
+- **Never cached.** `public/_headers` serves `/version.json` with `no-store` and `/` and `/index.html` with `no-cache`, and the game fetches `version.json` with `cache: 'no-store'` and a time query.
+- **When it checks.** When the page becomes visible again, on a back forward cache restore, on window focus, and every five minutes on the title, pause, Game Over, Victory, and the break between waves. Never on a timer mid-wave. A failed or offline check is ignored.
+- **The prompt.** If the live build differs from the running one, a "New version ready" chip shows on those same quiet screens, never during a wave. Tapping it reloads the page. Its place lives in `.update-chip` in `src/styles.css`, as arena pixels (`--chip-arena-x`, `--chip-arena-y`), so it is easy to move.
+- **Check it.** `PART=e2e bun shots26.ts` in `tools/audit` builds, serves, rebuilds under an open page, and checks that the chip appears and the reload lands on the new build.
+
 ### Rules
 
 - **Keep the game deterministic.** `update` is pure. It never calls `Math.random` and never reads the clock. Randomness comes from the seeded generator whose state lives in the Model, so the same seed and the same Messages give the same game.

PLATFORM.md

@@ -8,6 +8,7 @@ All on 2026-10-28.
 
 - **Everything moves to Cloudflare.** GitHub Pages was only for testing on other devices. It was removed (the site and `.github/workflows/pages.yml`) on 2026-10-28, once the Cloudflare deploy was live.
 - **The game is hosted at https://munch-manor.tanner-scadden.workers.dev**, the free `workers.dev` address, with no custom domain yet. The account's `workers.dev` subdomain is `tanner-scadden`.
+- **Installed apps find new builds with `version.json`, not a service worker.** Each build stamps its commit into the bundle and into `version.json`, which is never cached. The game fetches it when it comes back into view, on focus, and every five minutes on quiet screens, and offers a tap to reload when the build differs. See "Deploying" in `AGENTS.md`.
 - **GitHub Actions is the only deploy path.** Cloudflare Workers Builds (the dashboard's git integration) stays disconnected, so one push never fires two deploys.
 - **Free plan first.** Upgrade to Workers Paid only if the game takes off.
 - **Our own mini sync engine over scopes**, for personal and shared state. See "Sync engine".
@@ -59,7 +60,7 @@ Package names and APIs need checking against the Effect version the game uses (E
 - **Token permissions.** CI deploys with an account-owned token, `munch-manor-ci`, minted by `infra/github.ts`: Workers Scripts Write, Secrets Store Write, Account Settings Read, Workers Tail Read. Secrets Store Write is needed even to read, because Alchemy reads the state store's token by binding the secret to a short-lived preview Worker. The keychain token used by hand is much broader (it can mint tokens) and never goes to CI. Cloudflare's Workers Builds API rejected that account-owned token, so whether Workers Builds is connected can only be seen in the dashboard or in a Worker's deployment history (a `wrangler` source).
 - **The account had no `workers.dev` subdomain.** Alchemy's state store needs one, so `tanner-scadden` was claimed through the API before the first deploy.
 - **Two deploy paths collide quietly.** While Workers Builds was still connected, one push ran `wrangler deploy` and overwrote the Worker with a single page fallback. Alchemy's next deploy saw no changed inputs, and `alchemy drift` saw no drift, so both reported success. `alchemy deploy --force` put the declared version back.
-- **Routing and caching.** The game has no routes, so unknown paths answer 404 (`notFoundHandling: 'none'`). The default single page fallback served `index.html` at nested paths, where its relative asset paths missed. `public/_headers` makes the hashed files in `/assets` immutable for a year, and `index.html` revalidates on every load.
+- **Routing and caching.** The game has no routes, so unknown paths answer 404 (`notFoundHandling: 'none'`). The default single page fallback served `index.html` at nested paths, where its relative asset paths missed. `public/_headers` makes the hashed files in `/assets` immutable for a year, `index.html` and `/` are `no-cache` so every load revalidates, and `version.json` is `no-store`.
 
 ## Sync engine
 

infra/README.md

@@ -46,6 +46,10 @@ bun alchemy deploy github.ts --stage prod
 
 If the repository is renamed, change `REPOSITORY` and deploy twice, the second time with `--force`. The rename makes Alchemy replace each secret: it writes the new one, then deletes the old one, and GitHub redirects the old name to the same repository, so the delete removes the secret just written. The forced deploy writes it again. Check with `gh secret list`.
 
+## Updates on installed apps
+
+The Vite build stamps the bundle and `version.json` with `GITHUB_SHA`, which the Alchemy build child inherits in CI. A local deploy stamps the local commit, plus a timestamp when the tree is dirty. Alchemy skips the build when no input changed, so `version.json` only changes when the game does. See "How updates reach installed apps" in `AGENTS.md`.
+
 ## Check a deploy
 
 ```sh

public/_headers

@@ -3,3 +3,12 @@
 
 /manifest.webmanifest
   Content-Type: application/manifest+json
+
+/
+  Cache-Control: no-cache
+
+/index.html
+  Cache-Control: no-cache
+
+/version.json
+  Cache-Control: no-store

src/main.ts

@@ -118,6 +118,15 @@ import {
   refusePlacement,
   trapCenter,
 } from './traps'
+import {
+  RUNNING_BUILD,
+  UPDATE_CHECK_INTERVAL,
+  fetchRemoteBuild,
+  isCheckingForUpdates,
+  isUpdateWindow,
+  maybeNewerBuild,
+  reloadPage,
+} from './version'
 import {
   FINAL_WAVE,
   isRoundActive,
@@ -210,6 +219,14 @@ export const Message = defineMessageUnion({
   FailedPlaySound: { sound: SoundEffect, reason: Schema.String },
   CompletedCueMusic: { mood: MusicMood },
   FailedCueMusic: { mood: MusicMood, reason: Schema.String },
+  FocusedWindow: {},
+  RestoredPageFromCache: {},
+  TickedUpdateCheck: {},
+  CompletedFetchBuild: { build: Schema.String },
+  FailedFetchBuild: { reason: Schema.String },
+  ClickedUpdateButton: {},
+  CompletedReloadPage: {},
+  FailedReloadPage: { reason: Schema.String },
 })
 export type Message = typeof Message.Type
 
@@ -416,6 +433,28 @@ export const FocusShopItem = Command.define('FocusShopItem', {
     ),
 })
 
+export const FetchBuild = Command.define('FetchBuild', {
+  messages: [Message.CompletedFetchBuild, Message.FailedFetchBuild],
+  execute: pipe(
+    fetchRemoteBuild,
+    Effect.map(build => Message.CompletedFetchBuild({ build })),
+    Effect.catch(error =>
+      Effect.succeed(Message.FailedFetchBuild({ reason: error.reason })),
+    ),
+  ),
+})
+
+export const ReloadPage = Command.define('ReloadPage', {
+  messages: [Message.CompletedReloadPage, Message.FailedReloadPage],
+  execute: pipe(
+    reloadPage,
+    Effect.as(Message.CompletedReloadPage()),
+    Effect.catch(error =>
+      Effect.succeed(Message.FailedReloadPage({ reason: error.reason })),
+    ),
+  ),
+})
+
 // INIT
 
 export const init: Runtime.ApplicationInit<Model, Message> = () => ({
@@ -1060,6 +1099,13 @@ const isFreshRun = (model: Model): boolean =>
   Phase.isAnyOf(['Preparation'])(model.phase) &&
   model.elapsedMs < START_SOUND_GRACE_MS
 
+// VERSION
+
+const checkForUpdate = (model: Model): UpdateReturn =>
+  isCheckingForUpdates(RUNNING_BUILD)
+    ? { model, commands: [FetchBuild()] }
+    : { model }
+
 const updateGame = (model: Model, message: Message) =>
   Message.match<UpdateReturn>(message, {
     TickedFrame: ({ deltaTime }) => {
@@ -1146,7 +1192,7 @@ const updateGame = (model: Model, message: Message) =>
       if (visibility === 'Hidden') {
         return pauseWhenAway(noted)
       } else {
-        return { model: noted }
+        return checkForUpdate(noted)
       }
     },
 
@@ -1396,6 +1442,26 @@ const updateGame = (model: Model, message: Message) =>
     CompletedCueMusic: () => ({ model }),
 
     FailedCueMusic: () => ({ model }),
+
+    FocusedWindow: () => checkForUpdate(model),
+
+    RestoredPageFromCache: () => checkForUpdate(model),
+
+    TickedUpdateCheck: () => checkForUpdate(model),
+
+    CompletedFetchBuild: ({ build }) => ({
+      model: modifyFields(model, {
+        maybeNewerBuild: () => maybeNewerBuild(RUNNING_BUILD, build),
+      }),
+    }),
+
+    FailedFetchBuild: () => ({ model }),
+
+    ClickedUpdateButton: () => ({ model, commands: [ReloadPage()] }),
+
+    CompletedReloadPage: () => ({ model }),
+
+    FailedReloadPage: () => ({ model }),
   })
 
 const dismissHomeScreenTip = (model: Model): Model =>
@@ -1501,6 +1567,32 @@ export const maybeWindowBlurMessage = ({
     ? Option.some(Message.BlurredWindow())
     : Option.none()
 
+export const maybeWindowFocusMessage = ({
+  target,
+}: Readonly<{ target: EventTarget | null }>): Option.Option<Message> =>
+  target === window ? Option.some(Message.FocusedWindow()) : Option.none()
+
+export const maybePageShowMessage = ({
+  persisted,
+}: Readonly<{ persisted: boolean }>): Option.Option<Message> =>
+  persisted ? Option.some(Message.RestoredPageFromCache()) : Option.none()
+
+export const pageVisibilityMessage = (
+  visibilityState: DocumentVisibilityState,
+): Message =>
+  Message.ChangedPageVisibility({
+    visibility: visibilityState === 'hidden' ? 'Hidden' : 'Visible',
+  })
+
+export const updateCheckActivity = (model: Model): Activity =>
+  isCheckingForUpdates(RUNNING_BUILD) && isUpdateWindow(model.phase)
+    ? 'Active'
+    : 'Idle'
+
+const updateCheckMessages = Stream.map(Stream.tick(UPDATE_CHECK_INTERVAL), () =>
+  Message.TickedUpdateCheck(),
+)
+
 const keyboardMessages = Stream.merge(
   Dom.streamFromEventFilterMap({
     target: document,
@@ -1602,14 +1694,40 @@ export const subscriptions = Subscription.make<Model, Message>()(entry => ({
     Dom.streamFromEvent({
       target: document,
       type: 'visibilitychange',
-      mapEvent: () =>
-        Message.ChangedPageVisibility({
-          visibility:
-            document.visibilityState === 'hidden' ? 'Hidden' : 'Visible',
-        }),
+      mapEvent: () => pageVisibilityMessage(document.visibilityState),
+    }),
+  ),
+
+  windowFocus: Subscription.persistentEntry(
+    Dom.streamFromEventFilterMap({
+      target: window,
+      type: 'focus',
+      filterMapEvent: maybeWindowFocusMessage,
     }),
   ),
 
+  pageRestores: Subscription.persistentEntry(
+    Dom.streamFromEventFilterMap({
+      target: window,
+      type: 'pageshow',
+      filterMapEvent: maybePageShowMessage,
+    }),
+  ),
+
+  updateCheck: entry(
+    { activity: Activity },
+    {
+      modelToDependencies: model => ({
+        activity: updateCheckActivity(model),
+      }),
+      dependenciesToStream: ({ activity }) =>
+        Stream.when(
+          updateCheckMessages,
+          Effect.sync(() => activity === 'Active'),
+        ),
+    },
+  ),
+
   mouseAim: entry(
     { activity: Activity },
     {

src/model.ts

@@ -898,6 +898,7 @@ export const Model = Schema.Struct({
   homeScreenTip: HomeScreenTip,
   homeScreenSteps: Dialog.Model,
   pageVisibility: PageVisibility,
+  maybeNewerBuild: Schema.Option(Schema.String),
   appearance: Appearance,
   character: CharacterPicker,
 })
@@ -1080,6 +1081,7 @@ export const initialModel: Model = {
   homeScreenTip: 'Unseen',
   homeScreenSteps: Dialog.init({ id: HOME_SCREEN_STEPS_ID }),
   pageVisibility: 'Visible',
+  maybeNewerBuild: Option.none(),
   appearance: defaultAppearance,
   character: closedCharacterPicker,
 }

src/music.story.test.ts

@@ -6,7 +6,14 @@ import { describe, expect, test } from 'vitest'
 import { ARENA_LEVEL } from './arena'
 import type { SoundEffect } from './audio'
 import { ZOMBIE_MAX_HP } from './constants'
-import { CueMusic, Message, PlaySound, ResumeAudio, update } from './main'
+import {
+  CueMusic,
+  FetchBuild,
+  Message,
+  PlaySound,
+  ResumeAudio,
+  update,
+} from './main'
 import {
   AudioState,
   type Model,
@@ -342,8 +349,13 @@ describe('music only plays when it can be heard', () => {
       message(Message.ChangedPageVisibility({ visibility: 'Visible' })),
       Command.expectExact(
         CueMusic({ mood: 'Creep', level: 'Full', stinger: 'None' }),
+        FetchBuild,
       ),
       resolveCue('Creep'),
+      Command.resolve(
+        FetchBuild,
+        Message.FailedFetchBuild({ reason: 'offline' }),
+      ),
     )
   })
 

src/styles.css

@@ -1796,3 +1796,57 @@ body {
     animation: none;
   }
 }
+
+.update-chip-frame {
+  position: fixed;
+  top: env(safe-area-inset-top, 0px);
+  right: env(safe-area-inset-right, 0px);
+  bottom: env(safe-area-inset-bottom, 0px);
+  left: env(safe-area-inset-left, 0px);
+  container-type: size;
+  pointer-events: none;
+  z-index: 20;
+}
+
+.update-chip {
+  --arena-px: min(100cqw / 320, 100cqh / 180);
+  --chip-arena-x: 4;
+  --chip-arena-y: 28;
+  position: absolute;
+  left: calc(
+    (100cqw - 320 * var(--arena-px)) / 2 + var(--chip-arena-x) * var(--arena-px)
+  );
+  top: calc(
+    (100cqh - 180 * var(--arena-px)) / 2 + var(--chip-arena-y) * var(--arena-px)
+  );
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  min-height: 40px;
+  padding: 4px 12px;
+  border: 2px solid rgba(155, 227, 106, 0.7);
+  border-radius: 12px;
+  background: rgba(8, 10, 12, 0.85);
+  color: #f4f1de;
+  font: bold 11px/1.25 monospace;
+  text-align: left;
+  white-space: nowrap;
+  cursor: pointer;
+  pointer-events: auto;
+  touch-action: manipulation;
+}
+
+.update-chip-action {
+  color: #9be36a;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.update-chip:hover {
+  border-color: #9be36a;
+}
+
+.update-chip:focus-visible {
+  outline: 2px solid #ffe066;
+  outline-offset: 2px;
+}