v0.8.0 — the board replays what everyone else did, instead of arriving rearranged

TODO #13, #15 and #18 — Gitea#20 steps 2-4 pointed at a seated player's own screen.
Every accepted intent, and every automatic phase that does anything, becomes an
ordered presentation step. A bot's whole switching turn used to land in one push;
now it arrives as a run of steps, the district panel follows whoever is acting,
and a [N behind] … [Skip] row says how far the board is from the game.

Solitaire runs the same path — one collector inside submit(), which both session
kinds already funnel through — which is where its automatic phases finally get a
visible beat.

Dwell is assigned by kind: switching holds the screen, turn bookkeeping costs
nothing, and the clock turning over earns the beat. Tunable per viewer without a
rebuild, and off entirely at pace 0.

Also: switching was the one class of action logging unattributed, and now names
its train. Reasoning, measurements and the three things that turned out wrong are
in CHANGELOG.md.

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

src/sim/public-delta.ts

@@ -0,0 +1,132 @@
+/**
+ * Delta for the SEATLESS public frame — v0.8.0, `docs/plans/jitsi-common-board.md` § v0.8.0 § 3.
+ *
+ * `frame-delta.ts` solves the same-shaped problem for a seated player's `Frame` and does NOT carry
+ * over, which is worth saying plainly because reusing it looks obvious and is wrong. It nulls three
+ * TOP-LEVEL keys — `cells`, `facilities`, `division` — and a `PublicFrame` has only the last of
+ * those. Its `cells` and `facilities` live one level down, inside `districts[]`, one entry per seat,
+ * and that is where nearly all of the bytes are.
+ *
+ * **So the districts are deltaed PER SEAT rather than as one array.** One accepted intent changes
+ * one district; comparing the whole array as a unit would resend every other player's board on
+ * every step, which is exactly the cost this exists to avoid. On a four-player table that is three
+ * boards of waste per step, and a step is emitted for every bot move as well as every human one.
+ *
+ * It is also a TRUE PARTIAL rather than a full frame with holes in it, which is the other place
+ * `frame-delta.ts` does not carry over. See `PublicFrameDelta` below for the measurement that forced
+ * that; in short, most steps change one field and shipping the other thirty-four cost 16.7 MB a game.
+ *
+ * The convention that does carry over, kept identical so a reader of one file can read the other:
+ * an absent or `null` field means "unchanged since the last thing sent to this receiver", and the
+ * receiving side merges against the last full frame it actually holds. A first connect or a
+ * reconnect after a gap sends a full frame instead — the display stream resets rather than replaying
+ * (§ v0.8.0).
+ *
+ * Node-free by design, like `frame-delta.ts`: the server and the browser both import this directly.
+ */
+
+import type { CellView, DivisionView, FacilityView, PublicDistrict, PublicFrame } from './view.ts';
+
+/**
+ * One district with its two heavy fields nulled when unchanged.
+ *
+ * `seat` is the identity and is always present — it is what the receiver matches on. `player` and
+ * `name` are always sent too, and deliberately: Employee Rotation moves players between districts,
+ * so the pairing of seat to player is itself news, and it costs two small fields to never have to
+ * reason about whether a relabelling was missed.
+ */
+export type PublicDistrictDelta = Omit<PublicDistrict, 'cells' | 'facilities'> & {
+  cells: CellView[] | null;
+  facilities: FacilityView[] | null;
+};
+
+/** The shared-table half of a `PublicFrame` — everything that is not the Division or a district. */
+type PublicTable = Omit<PublicFrame, 'division' | 'districts'>;
+
+/**
+ * A `PublicFrame` reduced to WHAT CHANGED.
+ *
+ * **Partial, not a full frame with holes**, and that distinction was measured rather than assumed.
+ * The first version of this spread `...next` and nulled only the board fields, so every step shipped
+ * all 35 top-level properties even when the sole change was whose turn it was. Once TODO #18 gave
+ * automatic phases their own steps, most steps became exactly that — a turn handed on, nothing to
+ * look at — and a full 6-day game cost **19.4 MB**, of which **16.7 MB was those silent steps at
+ * ~11 KB each**. As a partial they are a few dozen bytes.
+ */
+export type PublicFrameDelta = {
+  /** Only the shared-table fields whose value differs from the previous frame. */
+  table: Partial<PublicTable>;
+  /** The Division, only when it changed. */
+  division: DivisionView[] | null;
+  /** Only the districts that changed, each carrying only the board fields that changed. */
+  districts: PublicDistrictDelta[];
+};
+
+const same = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
+
+const TABLE_KEYS = (frame: PublicFrame): (keyof PublicTable)[] =>
+  (Object.keys(frame) as (keyof PublicFrame)[]).filter(
+    (k): k is keyof PublicTable => k !== 'division' && k !== 'districts',
+  );
+
+/**
+ * `previous` is the last public frame actually sent to THIS receiver, or `null` for a first connect
+ * or a reset — in which case everything is sent in full.
+ */
+export function deltaPublicFrame(previous: PublicFrame | null, next: PublicFrame): PublicFrameDelta {
+  const before = new Map(previous?.districts.map((d) => [d.seat, d]) ?? []);
+  const table: Partial<PublicTable> = {};
+  for (const key of TABLE_KEYS(next)) {
+    if (previous === null || !same(previous[key], next[key])) {
+      (table as Record<string, unknown>)[key] = next[key];
+    }
+  }
+  const districts: PublicDistrictDelta[] = [];
+  for (const d of next.districts) {
+    const was = before.get(d.seat);
+    const cells = was && same(was.cells, d.cells) ? null : d.cells;
+    const facilities = was && same(was.facilities, d.facilities) ? null : d.facilities;
+    // A district with nothing new is left out entirely rather than sent as a row of nulls: on a
+    // four-player table three of them are unchanged on every single step.
+    if (was && cells === null && facilities === null && same(was, d)) continue;
+    districts.push({ ...d, cells, facilities });
+  }
+  return {
+    table,
+    division: previous !== null && same(previous.division, next.division) ? null : next.division,
+    districts,
+  };
+}
+
+/** The receiving side: merges a delta back onto the last full public frame this receiver holds. */
+export function applyPublicDelta(previous: PublicFrame | null, delta: PublicFrameDelta): PublicFrame {
+  const base = previous ?? (delta.table as PublicTable);
+  const merged = { ...base, ...delta.table } as PublicTable;
+  const bySeat = new Map((previous?.districts ?? []).map((d) => [d.seat, d]));
+  for (const d of delta.districts) {
+    const was = bySeat.get(d.seat);
+    bySeat.set(d.seat, {
+      ...d,
+      cells: d.cells ?? need(was?.cells, `districts[seat ${d.seat}].cells`),
+      facilities: d.facilities ?? need(was?.facilities, `districts[seat ${d.seat}].facilities`),
+    });
+  }
+  return {
+    ...merged,
+    division: delta.division ?? need(previous?.division, 'division'),
+    districts: [...bySeat.values()].sort((a, b) => a.seat - b.seat),
+  };
+}
+
+/**
+ * A delta that says "unchanged" against a receiver that has nothing to merge onto is a bug in the
+ * SENDER's bookkeeping, not a recoverable state — it means the two sides disagree about what has
+ * been delivered, and quietly producing a frame with a missing board would put a blank district in
+ * front of a player. `frame-delta.ts` throws in the same situation and for the same reason.
+ */
+function need<T>(value: T | undefined, what: string): T {
+  if (value === undefined) {
+    throw new Error(`deltaPublicFrame said "${what}" is unchanged, but there is no previous frame to merge onto`);
+  }
+  return value;
+}