Let a project choose how its game link is zoomed (#279)

The page of a released game always drew the camera at Auto, the
largest whole step that fits. A camera of 300x180 in a window of
1280x800 stands at step 4 and leaves a border left and right. The
issue asks for Fit next to it. Answered there: a setting of its own
rather than the scale of the Game tab, and no switch for the player.

- The project has a field gameLinkZoom, 'auto' or 'fit'. A document
  without it reads as 'auto', so nothing changes for a project that
  is there already. No format bump.
- Project settings has a row "Link zoom" with a menu of Auto and
  Fit. It is an undo step of its own, SetGameLinkZoomCommand.
- GameScreen hands the field to cameraView where it passed a fixed
  'auto'.
- gameScale, the scale of the Game tab, is not touched and does not
  reach the link.
- The released copy is frozen, so the change reaches the link only
  with "Update release".

Decided here:

- The row is called "Link zoom", not "Game link zoom" as proposed.
  The longer label is wider than the label column of the dialog and
  pushed its button 12 px out of line with the others.
- The undo step keeps the name "Game link zoom", which is what the
  tooltip of the undo button shows.
- A note under the row says "The released game at the largest whole
  step that fits, or filling the window."

Tests:
- Gate on melektaus-atx: 211 files, 3227 tests (3219 + 8), exit 0
- e2e 60 on melektaus-atx: 19 checks, all pass
- e2e 35,46,59,60: 74 checks, all pass
- No full run and no smokes. The sum of 1671 (1668 + 3) is reckoned,
  1668 is what CI counted for 9e869df.
- Eight unit tests: the default, saving and loading, values that
  are not a choice, undo, gameScale left alone, the factor of Fit
  for a window larger and smaller than the camera, and the rule
  behind Apply.
- Three e2e checks in block 60i of module 60, with the real mouse:
  Auto to Fit in the dialog, update the release, open the link
  without a session and measure scale, frame and pixels. Fit reads
  4.267 where Auto reads 4.
- Nine unit counter-probes and three browser counter-probes all fail
  their tests.
- Not checked in the browser: Fit in a window smaller than the
  camera, which has a unit test, and Fit under a display scale above
  100 %. Nothing was looked at after the build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/core/commands/projectCommands.ts

@@ -1,5 +1,11 @@
 import { collisionLayersOf } from '../model/collisionLayers';
-import { DEFAULT_WHILE_PLAYING, type PlayFrom, type WhilePlaying } from '../model/playSettings';
+import {
+  DEFAULT_GAME_LINK_ZOOM,
+  DEFAULT_WHILE_PLAYING,
+  type GameLinkZoom,
+  type PlayFrom,
+  type WhilePlaying,
+} from '../model/playSettings';
 import type { Project } from '../model/Project';
 import { clampSymbolScale } from '../model/symbolScale';
 import type { Command } from './Command';
@@ -91,3 +97,20 @@ export class SetWhilePlayingCommand implements Command {
     project.whilePlaying = this.previous;
   }
 }
+
+/** How the page of the released game sizes the camera frame (#279). */
+export class SetGameLinkZoomCommand implements Command {
+  readonly label = 'Game link zoom';
+  private previous: GameLinkZoom = DEFAULT_GAME_LINK_ZOOM;
+
+  constructor(private readonly zoom: GameLinkZoom) {}
+
+  execute(project: Project): void {
+    this.previous = project.gameLinkZoom;
+    project.gameLinkZoom = this.zoom;
+  }
+
+  undo(project: Project): void {
+    project.gameLinkZoom = this.previous;
+  }
+}

src/core/model/Project.ts

@@ -8,9 +8,11 @@ import {
 } from './Asset';
 import { DEFAULT_LAYER_NAME } from './collisionLayers';
 import {
+  DEFAULT_GAME_LINK_ZOOM,
   DEFAULT_GAME_SCALE,
   DEFAULT_PLAY_FROM,
   DEFAULT_WHILE_PLAYING,
+  type GameLinkZoom,
   type GameScale,
   type PlayFrom,
   type WhilePlaying,
@@ -57,6 +59,8 @@ export interface Project {
   whilePlaying: WhilePlaying;
   /** The scale the game view draws the camera at. Saved, but not an undo step: it is how you look. */
   gameScale: GameScale;
+  /** How the page of the released game sizes the camera frame (see `playSettings.ts`). */
+  gameLinkZoom: GameLinkZoom;
   /** Which symbols, names and collider outlines the scene view shows, per type. Saved like `gameScale`. */
   sceneVisibility: SceneVisibility;
 }
@@ -75,6 +79,7 @@ export function createEmptyProject(id: string, name: string): Project {
     playFrom: DEFAULT_PLAY_FROM,
     whilePlaying: DEFAULT_WHILE_PLAYING,
     gameScale: DEFAULT_GAME_SCALE,
+    gameLinkZoom: DEFAULT_GAME_LINK_ZOOM,
     sceneVisibility: defaultSceneVisibility(),
   };
 }

src/core/model/playSettings.ts

@@ -20,6 +20,24 @@ function isGameScale(value: unknown): value is GameScale {
   return value === 'auto' || value === 'fit' || GAME_SCALE_STEPS.includes(value as number);
 }
 
+/**
+ * How the page of a released game sizes the camera frame (#279): the largest step that fits, or
+ * fitted. A setting of its own rather than `gameScale`, which is how the editor looks at the game
+ * and changes while working; fixed steps make no sense for a window nobody knows the size of.
+ */
+export type GameLinkZoom = 'auto' | 'fit';
+
+export const GAME_LINK_ZOOMS: readonly GameLinkZoom[] = ['auto', 'fit'];
+
+/** Also what a project written before there was a choice reads as: the page always drew at Auto. */
+export const DEFAULT_GAME_LINK_ZOOM: GameLinkZoom = 'auto';
+
+/** Read off untrusted JSON; anything that is not one of the choices is the default. */
+export function gameLinkZoomOf(raw: unknown): GameLinkZoom {
+  const value = (raw as { gameLinkZoom?: unknown } | null)?.gameLinkZoom;
+  return GAME_LINK_ZOOMS.includes(value as GameLinkZoom) ? (value as GameLinkZoom) : DEFAULT_GAME_LINK_ZOOM;
+}
+
 /**
  * How closely the editor's panels follow a running game (#265). The game itself runs every frame
  * in each of them; only what the hierarchy, the inspector and the graphs show of it is held back.

src/core/store/serialize.ts

@@ -45,7 +45,7 @@ import type {
 import { parseCellKey } from '../model/tilemap';
 import { pluginsOf } from './projectPlugins';
 import { collisionLayersOf } from '../model/collisionLayers';
-import { gameScaleOf, playFromOf, whilePlayingOf } from '../model/playSettings';
+import { gameLinkZoomOf, gameScaleOf, playFromOf, whilePlayingOf } from '../model/playSettings';
 import { sceneVisibilityOf } from '../model/sceneVisibility';
 import { symbolScaleOf } from '../model/symbolScale';
 import { decodeCells, encodeCells } from './tilemapCells';
@@ -282,6 +282,7 @@ export function deserializeProject(raw: unknown, fallbackId = ''): Project {
     playFrom: playFromOf(r),
     whilePlaying: whilePlayingOf(r),
     gameScale: gameScaleOf(r),
+    gameLinkZoom: gameLinkZoomOf(r),
     sceneVisibility: sceneVisibilityOf(r),
   };
   // A hand-edited file may have copies that no longer match their Struct asset.

src/editor/ProjectSession.ts

@@ -4,6 +4,7 @@
 import {
   RenameProjectCommand,
   SetCollisionLayersCommand,
+  SetGameLinkZoomCommand,
   SetPlayFromCommand,
   SetSymbolScaleCommand,
   SetWhilePlayingCommand,
@@ -321,7 +322,8 @@ export class ProjectSession {
   }
 
   /**
-   * Name, the scene Play starts, how closely the panels follow it, the symbol scale and the collision layers (#152) in one dialog
+   * Name, the scene Play starts, how closely the panels follow it, the zoom of the game link, the
+   * symbol scale and the collision layers (#152) in one dialog
    * (#183). Each is an undo step of its own – one each, and only for what actually changed.
    */
   openProjectSettings(): ProjectSettingsDialog {
@@ -330,6 +332,7 @@ export class ProjectSession {
       name: project.name,
       playFrom: this.state.playFrom,
       whilePlaying: project.whilePlaying,
+      gameLinkZoom: project.gameLinkZoom,
       collisionLayers: [...project.collisionLayers],
       symbolScale: project.symbolScale,
     };
@@ -344,6 +347,8 @@ export class ProjectSession {
         if (change.playFrom !== undefined) this.state.execute(new SetPlayFromCommand(change.playFrom));
         if (change.whilePlaying !== undefined)
           this.state.execute(new SetWhilePlayingCommand(change.whilePlaying));
+        if (change.gameLinkZoom !== undefined)
+          this.state.execute(new SetGameLinkZoomCommand(change.gameLinkZoom));
       }),
     );
   }

src/editor/ProjectSettingsDialog.ts

@@ -1,7 +1,13 @@
 import { layerFallback, MAX_COLLISION_LAYERS } from '../core/model/collisionLayers';
 import { clampSymbolScale, SYMBOL_SCALE_MAX, SYMBOL_SCALE_MIN } from '../core/model/symbolScale';
 import { Button, HStack, Label, Menu, NumberField, TextField, Theme, VStack } from '../ui';
-import { type PlayFrom, WHILE_PLAYING, type WhilePlaying } from '../core/model/playSettings';
+import {
+  GAME_LINK_ZOOMS,
+  type GameLinkZoom,
+  type PlayFrom,
+  WHILE_PLAYING,
+  type WhilePlaying,
+} from '../core/model/playSettings';
 import { FormDialog } from './FormDialog';
 
 /** What the dialog hands back when Apply is pressed. */
@@ -9,6 +15,7 @@ export interface ProjectSettings {
   name: string;
   playFrom: PlayFrom;
   whilePlaying: WhilePlaying;
+  gameLinkZoom: GameLinkZoom;
   collisionLayers: string[];
   symbolScale: number;
 }
@@ -29,6 +36,7 @@ export function settingsChanges(
   symbolScale?: number;
   playFrom?: PlayFrom;
   whilePlaying?: WhilePlaying;
+  gameLinkZoom?: GameLinkZoom;
 } {
   const name = after.name.trim() || before.name;
   const symbolScale = clampSymbolScale(after.symbolScale);
@@ -40,6 +48,7 @@ export function settingsChanges(
     ...(symbolScale === before.symbolScale ? {} : { symbolScale }),
     ...(after.playFrom === before.playFrom ? {} : { playFrom: after.playFrom }),
     ...(after.whilePlaying === before.whilePlaying ? {} : { whilePlaying: after.whilePlaying }),
+    ...(after.gameLinkZoom === before.gameLinkZoom ? {} : { gameLinkZoom: after.gameLinkZoom }),
   };
 }
 
@@ -54,9 +63,14 @@ const WHILE_PLAYING_LABEL: Record<WhilePlaying, string> = {
   minimal: 'Minimal',
 };
 
+const GAME_LINK_ZOOM_LABEL: Record<GameLinkZoom, string> = {
+  auto: 'Auto',
+  fit: 'Fit',
+};
+
 /**
  * Everything about the project that is not an asset (#183): its name, which scene Play starts and
- * how closely the panels follow it (#265), the
+ * how closely the panels follow it (#265), the zoom of the game link (#279), the
  * size of the scene view's symbol icons, and the collision layers (#152). The top bar carries icons
  * only, so this is the one place they are edited.
  *
@@ -68,11 +82,13 @@ export class ProjectSettingsDialog extends FormDialog {
   private projectName: string;
   private playFrom: PlayFrom;
   private whilePlaying: WhilePlaying;
+  private gameLinkZoom: GameLinkZoom;
   private layers: string[];
   private symbolScale: number;
   private readonly nameField: TextField;
   private readonly playFromButton: Button;
   private readonly whilePlayingButton: Button;
+  private readonly gameLinkZoomButton: Button;
   private readonly symbolScaleField: NumberField;
   private readonly rows = new VStack({ gap: Theme.gap });
   private readonly addButton: Button;
@@ -82,6 +98,7 @@ export class ProjectSettingsDialog extends FormDialog {
     this.projectName = settings.name;
     this.playFrom = settings.playFrom;
     this.whilePlaying = settings.whilePlaying;
+    this.gameLinkZoom = settings.gameLinkZoom;
     this.layers = [...settings.collisionLayers];
     this.symbolScale = clampSymbolScale(settings.symbolScale);
 
@@ -118,6 +135,18 @@ export class ProjectSettingsDialog extends FormDialog {
       }),
     );
 
+    this.gameLinkZoomButton = new Button(GAME_LINK_ZOOM_LABEL[this.gameLinkZoom], {
+      width: 150,
+      align: 'left',
+      onClick: () => this.openGameLinkZoomMenu(),
+    });
+    this.content.add(this.formRow(this.fieldLabel('Link zoom'), this.gameLinkZoomButton));
+    this.content.add(
+      new Label('The released game at the largest whole step that fits, or filling the window.', {
+        style: 'muted',
+      }),
+    );
+
     this.symbolScaleField = new NumberField(this.symbolScale, {
       width: 150,
       min: SYMBOL_SCALE_MIN,
@@ -153,6 +182,7 @@ export class ProjectSettingsDialog extends FormDialog {
         name: this.projectName,
         playFrom: this.playFrom,
         whilePlaying: this.whilePlaying,
+        gameLinkZoom: this.gameLinkZoom,
         collisionLayers: this.layers,
         symbolScale: this.symbolScale,
       }),
@@ -165,12 +195,19 @@ export class ProjectSettingsDialog extends FormDialog {
     return [...this.layers];
   }
 
-  /** Name, start-scene switch, panel preset and symbol scale as they stand (test hook). */
-  values(): { name: string; playFrom: PlayFrom; whilePlaying: WhilePlaying; symbolScale: number } {
+  /** Name, start-scene switch, panel preset, link zoom and symbol scale as they stand (test hook). */
+  values(): {
+    name: string;
+    playFrom: PlayFrom;
+    whilePlaying: WhilePlaying;
+    gameLinkZoom: GameLinkZoom;
+    symbolScale: number;
+  } {
     return {
       name: this.projectName,
       playFrom: this.playFrom,
       whilePlaying: this.whilePlaying,
+      gameLinkZoom: this.gameLinkZoom,
       symbolScale: this.symbolScale,
     };
   }
@@ -185,6 +222,11 @@ export class ProjectSettingsDialog extends FormDialog {
     return this.whilePlayingButton;
   }
 
+  /** The game link zoom switch, so a check can click it. */
+  get gameLinkZoomControl(): Button {
+    return this.gameLinkZoomButton;
+  }
+
   /** The symbol scale field, so a check can type into it. */
   get symbolScaleControl(): NumberField {
     return this.symbolScaleField;
@@ -224,6 +266,19 @@ export class ProjectSettingsDialog extends FormDialog {
     ).openBelow(this.whilePlayingButton);
   }
 
+  private openGameLinkZoomMenu(): void {
+    new Menu(
+      GAME_LINK_ZOOMS.map((zoom) => ({
+        label: GAME_LINK_ZOOM_LABEL[zoom],
+        current: this.gameLinkZoom === zoom,
+        onSelect: () => {
+          this.gameLinkZoom = zoom;
+          this.gameLinkZoomButton.setText(GAME_LINK_ZOOM_LABEL[zoom]);
+        },
+      })),
+    ).openBelow(this.gameLinkZoomButton);
+  }
+
   private addLayer(): void {
     if (this.layers.length >= MAX_COLLISION_LAYERS) return;
     this.layers.push(layerFallback(this.layers.length));

src/editor/debug/uiHooks.ts

@@ -303,6 +303,11 @@ export function uiHooks({ app, state, editor }: HookContext) {
       const dialog = editor.projectSettingsDialog();
       return dialog ? centreOf(dialog.whilePlayingControl) : null;
     },
+    /** Where to click the Game link zoom switch inside that dialog (#279). */
+    projectSettingsGameLinkZoomAt: () => {
+      const dialog = editor.projectSettingsDialog();
+      return dialog ? centreOf(dialog.gameLinkZoomControl) : null;
+    },
     /** Where to click the symbol scale field inside that dialog. */
     projectSettingsSymbolScaleAt: () => {
       const dialog = editor.projectSettingsDialog();

src/player/GameScreen.ts

@@ -9,8 +9,9 @@ import { cameraView, type View } from '../viewport/view';
 import { type Frame, type ViewSource, WorldViewport } from '../viewport/WorldViewport';
 
 /**
- * A released game on screen (#266): the running world through its active camera, at the largest
- * zoom step that fits (Auto), letterboxed in the page colour. Before the game runs, and after it
+ * A released game on screen (#266): the running world through its active camera, at the zoom the
+ * project names for its link (#279: the largest step that fits, or fitted), letterboxed in the
+ * page colour. Before the game runs, and after it
  * stopped itself, it shows a line of text instead – "Click to play", or why there is nothing to play.
  */
 
@@ -89,7 +90,8 @@ export class GameScreen extends WorldViewport {
 
   protected override currentView(): View | null {
     const camera = this.running ? cameraOfWorld(this.running) : null;
-    return camera ? cameraView(camera, this.w, this.h, 'auto', ui().app.renderer.resolution) : null;
+    const zoom = this.state.project.gameLinkZoom;
+    return camera ? cameraView(camera, this.w, this.h, zoom, ui().app.renderer.resolution) : null;
   }
 
   protected override collectFrame(): Frame {