@7365admin1/layer-common 3.2.1-staging.64 → 3.2.1-staging.66

package/utils/camera-wall.ts

@@ -21,9 +21,20 @@
  * 3. **A control that is off is drawn, dimmed, and says why** — never hidden. The
  *    sentence shown is the SERVER'S own sentence, never rewritten here, so a
  *    camera cannot explain itself two different ways on two screens.
- * 4. **"Live" means a picture is arriving**, not "we asked for one". The tile
- *    says `Connecting…` until the player page is actually up, and `No signal`
- *    when it never comes.
+ * 4. **"Live" means a picture is arriving**, not "we asked for one", and not
+ *    "the page that would show one loaded". Those are three different claims
+ *    and the tile used to make the strongest one on the evidence for the
+ *    weakest. See the long note above `tileView` — this rule was being broken
+ *    in production and a supervisor was being told a blank tile was live.
+ * 5. **A switched-off control also says what would switch it on, and who to
+ *    ask.** The server's sentence states the fact; it deliberately does not name
+ *    a next step, because a server has no idea who the reader can go and talk
+ *    to. So the next step is a SECOND line, owned here and keyed by the
+ *    server's own reason CODE — rule 3 is intact, nothing is rewritten.
+ * 6. **The recorder's health and the player page's state are two different
+ *    facts and never share one indicator.** "The page is up" and "the recorder
+ *    answered" can disagree, and a supervisor needs to know which they are
+ *    looking at. Merging them is the same defect as a still tile saying "Live".
  *
  * These match the iSecure365 mobile monitoring build one for one, deliberately:
  * the same product should not answer the same question differently on a phone
@@ -92,7 +103,14 @@ export function wallLayout(key: string | undefined) {
 
 /**
  * At three columns a tile is small enough that the chrome starts eating the
- * picture, so the tile drops its status WORD and keeps the dot.
+ * picture, so the type shrinks and the recorder line loses its timestamp.
+ *
+ * **It no longer removes the camera's name or its status.** It used to drop the
+ * status WORD at nine tiles and leave a bare 7 px dot — a mobile-first call
+ * that is wrong on a desktop wall, which is the layout a supervisor watches
+ * from furthest away and the one where a camera is most likely to be missed.
+ * Whether a camera is alive is the tile's whole job; it is not the thing that
+ * gets cut for room.
  */
 export function isDenseLayout(key: string | undefined) {
   return wallLayout(key).columns >= 3;
@@ -111,27 +129,87 @@ export function wallCameras(items: unknown): TWallCamera[] {
 }
 
 /**
- * The tiles, in order, padded with `null` to the layout's size.
+ * The cameras a wall would show, before the layout cuts them down.
  *
  * An empty selection is **not** "no cameras" — it is "nobody has chosen yet",
  * and the wall falls back to the site's own order. A supervisor who clears the
  * picker gets their site back, not a black screen.
  */
-export function wallTiles(
+function wallChosen(
+  cameras: TWallCamera[],
+  selectedIds: string[] | undefined
+): TWallCamera[] {
+  if (!selectedIds || !selectedIds.length) return cameras;
+  const byId = new Map(cameras.map((c) => [c._id, c]));
+  return selectedIds.map((id) => byId.get(id)).filter((c): c is TWallCamera => !!c);
+}
+
+/**
+ * How many pages the wall needs — never fewer than one.
+ *
+ * **This exists because it was missing, and a camera was going missing with
+ * it.** The wall took the first `tiles` cameras and dropped the rest on the
+ * floor: a site with five cameras on a 2x2 wall showed four, said "Cameras 5"
+ * in the toolbar, and gave nobody any way to reach the fifth. It did not read
+ * as a missing feature, it read as a broken count. The mobile wall has paged
+ * since it was built; this is the same rule, on the web.
+ */
+export function wallPageCount(
   cameras: TWallCamera[],
   selectedIds: string[] | undefined,
   layoutKey: string | undefined
-): Array<TWallCamera | null> {
+): number {
+  const total = wallChosen(cameras, selectedIds).length;
+  return Math.max(1, Math.ceil(total / wallLayout(layoutKey).tiles));
+}
+
+/** Keeps a page number inside the wall, whatever the layout just did to it. */
+export function clampPage(page: number, pages: number): number {
+  if (!Number.isFinite(page)) return 0;
+  return Math.min(Math.max(0, Math.floor(page)), Math.max(0, pages - 1));
+}
+
+/**
+ * The cameras on one page, in order. **Never padded.**
+ *
+ * It used to pad to the layout's tile count with `null`, and the wall drew each
+ * one as a dashed box reading "No camera in this position." Five cameras on a
+ * nine-tile wall meant four dead grey rectangles, which is not what a video
+ * wall does and not information: nobody looking at that screen was unaware
+ * they had five cameras, and there is nothing to drop into an empty cell
+ * because cameras are added in Site Settings, not here.
+ *
+ * So the grid packs instead — see `wallRows`. The layout picker still means
+ * "at most this many, at this size"; it stops meaning "always exactly this
+ * many holes".
+ */
+export function wallTiles(
+  cameras: TWallCamera[],
+  selectedIds: string[] | undefined,
+  layoutKey: string | undefined,
+  page = 0
+): TWallCamera[] {
   const { tiles } = wallLayout(layoutKey);
-  const byId = new Map(cameras.map((c) => [c._id, c]));
-  const chosen =
-    selectedIds && selectedIds.length
-      ? selectedIds.map((id) => byId.get(id)).filter((c): c is TWallCamera => !!c)
-      : cameras;
-
-  const out: Array<TWallCamera | null> = chosen.slice(0, tiles);
-  while (out.length < tiles) out.push(null);
-  return out;
+  const chosen = wallChosen(cameras, selectedIds);
+  const start = clampPage(page, wallPageCount(cameras, selectedIds, layoutKey)) * tiles;
+
+  return chosen.slice(start, start + tiles);
+}
+
+/**
+ * How many grid rows this page actually needs — the other half of packing.
+ *
+ * Without it a 3x3 wall holding five cameras still reserves three rows, so the
+ * five tiles are drawn two-thirds height with a band of empty screen under
+ * them. Sizing the grid to the content gives that screen back to the pictures,
+ * which is the entire reason a supervisor chose a bigger layout.
+ *
+ * Never more rows than the layout would have had, and never fewer than one.
+ */
+export function wallRows(count: number, layoutKey: string | undefined): number {
+  const { columns, tiles } = wallLayout(layoutKey);
+  const capped = Math.min(Math.max(0, Math.floor(count)), tiles);
+  return Math.min(Math.ceil(tiles / columns), Math.max(1, Math.ceil(capped / columns)));
 }
 
 /* -------------------------------------------------------------------------- */
@@ -146,6 +224,7 @@ export function wallTiles(
  * waiting on something somebody has to switch on.
  */
 export const CAPABILITY_TAGS = {
+  supported: "Ready",
   unsupported: "Not set up yet",
   unknown: "Not checked yet",
 } as const;
@@ -157,24 +236,121 @@ export const CAPABILITY_TAGS = {
  */
 const NOT_PROBED = "This camera has not been asked what it can do yet.";
 
-/** The four capabilities the wall draws a control for, and their plain names. */
+/**
+ * RULE 5 — the second line, and why the server cannot write it.
+ *
+ * The server's sentence is a statement of fact: *"No direct connection to this
+ * camera's recorder is configured on this server."* That is correct, it is the
+ * server's to own, and it is **not** an answer to the only question a reader
+ * actually has, which is "so how do I set it up?" — a real question, asked of
+ * this exact screen. A server cannot answer it: it knows the configuration is
+ * absent, it has no idea who the person reading has to go and ask.
+ *
+ * So the next step lives here, keyed by the server's own reason CODE rather
+ * than by matching its words. Rule 3 is untouched — the server's sentence is
+ * still shown verbatim; this is a second line under it.
+ *
+ * **Every one of these says the same true and unwelcome thing in a different
+ * way: none of it is switched on from this page.** Saying so plainly is the
+ * point. An empty settings screen that quietly does nothing would be worse.
+ */
+export const CAPABILITY_NEXT_STEPS: Record<string, string> = {
+  "device-http-not-configured":
+    "This is a server setting, not something to switch on from this page: the server needs a network route to the camera's recorder, plus the recorder's sign-in details. Ask your Seven365 administrator.",
+  "device-http-disabled":
+    "Direct camera access is switched off on this server. Ask your Seven365 administrator to switch it on.",
+  "device-http-unreachable":
+    "The recorder did not answer this server. Ask your Seven365 administrator or the camera installer to check the recorder and its network.",
+  "device-http-locked-out":
+    "Sign-ins to the recorder are being held back so its account is not locked out. Ask your Seven365 administrator to check the recorder's sign-in details.",
+  "control-not-enabled":
+    "Camera control is switched off on this server. Switching it on moves real hardware, so it has to be approved by a Seven365 backend lead first.",
+  "device-no-ptz":
+    "This camera cannot move, so there is nothing to switch on. A different camera would be needed.",
+  "no-recorder-configured":
+    "No recorder is set up for this camera's video service. Ask your Seven365 administrator to add it.",
+  "no-channel-in-address":
+    "This camera's address does not say which stream it is. Correct it in Site Settings, under CCTV.",
+  "not-a-relay-player-url":
+    "This camera's address is not a live-video page address. Correct it in Site Settings, under CCTV.",
+  "no-address":
+    "This camera has no address. Add it in Site Settings, under CCTV.",
+  "invalid-address":
+    "This camera's address is not valid. Correct it in Site Settings, under CCTV.",
+  "camera-inactive":
+    "This camera is switched off. Set it back to active in Site Settings, under CCTV.",
+  "device-not-probed":
+    "The camera is asked what it can do the first time it is opened. Nothing to do — check back in a moment.",
+  "no-transport":
+    "Nothing on this server can do this yet. It has to be built before it can be switched on.",
+};
+
+/**
+ * For a reason code this build has never heard of — a newer server, a code
+ * added after this layer was published. Deliberately vague about the cause and
+ * exact about the next step, which is the half that matters: it is still not a
+ * setting on this page, and there is still somebody to ask.
+ */
+const NEXT_STEP_FALLBACK =
+  "This is not something to switch on from this page. Ask your Seven365 administrator.";
+
+/**
+ * The capabilities the wall draws a control for, and their plain names.
+ *
+ * `ready` is what the panel says when the server reports the capability
+ * WORKING, and it describes **this screen** rather than the product. Only
+ * `digitalZoom` is actually built here; the other four are real on the camera
+ * and not yet drawn on the web, and saying so is better than a panel that
+ * points at a timeline nobody has built. Today the server reports all four
+ * unsupported, so none of those sentences is on screen — they are there so
+ * that the day one flips, the screen does not start lying.
+ */
 export const WALL_CAPABILITY_CONTROLS = [
-  { key: "playback", title: "Recorded footage" },
-  { key: "events", title: "Events and alarms" },
-  { key: "ptz", title: "Move camera" },
-  { key: "presets", title: "Stored positions" },
+  {
+    key: "digitalZoom",
+    title: "Zoom",
+    ready:
+      "Scroll or pinch on a tile to zoom in, then drag to move around. Reset returns to the whole picture. This crops and enlarges the picture on your screen — it does not move the camera.",
+  },
+  {
+    key: "playback",
+    title: "Recorded footage",
+    ready: "This camera can serve recorded footage. The playback controls are not on this screen yet.",
+  },
+  {
+    key: "events",
+    title: "Events and alarms",
+    ready: "This camera reports events. The event list is not on this screen yet.",
+  },
+  {
+    key: "ptz",
+    title: "Move camera",
+    ready: "This camera can be moved. The movement controls are not on this screen yet.",
+  },
+  {
+    key: "presets",
+    title: "Stored positions",
+    ready: "This camera has stored positions. Recalling them is not on this screen yet.",
+  },
 ] as const;
 
 export type TCapabilityView = {
   state: "supported" | "unsupported" | "unknown";
   available: boolean;
-  /** `null` when the capability works — a working control needs no tag. */
-  tag: string | null;
-  /** The server's sentence, or the not-probed one. Never empty. */
-  detail: string;
+  /** Always set: "Ready" when it works, the reason wording when it does not. */
+  tag: string;
+  /**
+   * The server's sentence, or the not-probed one — and `null` when the
+   * capability WORKS, because the server sends no sentence for a working
+   * capability and falling back to the not-probed one made a working control
+   * claim it had never been checked.
+   */
+  detail: string | null;
+  /** Rule 5: what would switch it on and who to ask. `null` when it works. */
+  nextStep: string | null;
 };
 
-/** Rule 2 and rule 3, in one place. */
+/** Rules 2, 3 and 5, in one place. */
 export function capabilityView(
   camera: TWallCamera | null | undefined,
   key: string
@@ -185,11 +361,28 @@ export function capabilityView(
       ? entry.state
       : "unknown";
 
+  if (state === "supported") {
+    return {
+      state,
+      available: true,
+      tag: CAPABILITY_TAGS.supported,
+      detail: null,
+      nextStep: null,
+    };
+  }
+
+  const reason = (entry?.reason || "").trim();
+
   return {
     state,
-    available: state === "supported",
-    tag: state === "supported" ? null : CAPABILITY_TAGS[state],
+    available: false,
+    tag: CAPABILITY_TAGS[state],
     detail: (entry?.detail || "").trim() || NOT_PROBED,
+    nextStep:
+      CAPABILITY_NEXT_STEPS[reason] ??
+      (state === "unknown"
+        ? CAPABILITY_NEXT_STEPS["device-not-probed"]
+        : NEXT_STEP_FALLBACK),
   };
 }
 
@@ -205,47 +398,193 @@ export function capabilityView(
  */
 export const LIVE_CONNECT_TIMEOUT_MS = 15_000;
 
+/**
+ * How long a tile that WAS confirmed playing may go without another frame
+ * before it stops saying "Live".
+ *
+ * Only reachable once the video service reports frames at all (see
+ * `playerSignal`). It exists because the opposite mistake — a tile that went
+ * green once and stays green over a frozen picture — is the same defect as the
+ * mobile app's "Live" badge over a nine-second-old still, and is exactly what
+ * this whole rewrite is fixing.
+ */
+export const LIVE_FRAME_TIMEOUT_MS = 12_000;
+
 export type TTileState =
   | "live"
+  | "unverified"
   | "connecting"
   | "no-signal"
   | "offline"
   | "unavailable";
 
 /**
- * The four words a tile may say about itself.
+ * The words a tile may say about itself.
  *
  * `offline` and `no-signal` are two different facts and used to share one word:
  * "Offline" on every tile at once means the BROWSER lost the network; "No
  * signal" on one tile means that camera is not answering. A supervisor needs to
  * know which of those they are looking at.
+ *
+ * `unverified` is the state this wall is in for every camera on this estate
+ * today, and saying so is the point — see the note above `tileView`.
  */
 export const TILE_LABELS = {
   live: "Live",
+  unverified: "Not verified",
   connecting: "Connecting…",
   "no-signal": "No signal",
   offline: "No connection",
   unavailable: "Not set up yet",
 } as const;
 
-/** What the browser knows about the embedded player page. */
-export type TPlayerState = "loading" | "ready" | "timeout";
+/**
+ * What the browser knows about the embedded player page.
+ *
+ * - `loading`  — nothing yet; the document request has not finished.
+ * - `page-up`  — the document loaded. **This says nothing about pictures.**
+ * - `playing`  — the video service reported a decoded frame (see `playerSignal`).
+ * - `stalled`  — it reported frames and then stopped, or said it stalled.
+ * - `failed`   — the document never loaded, or the browser reported an error.
+ */
+export type TPlayerState = "loading" | "page-up" | "playing" | "stalled" | "failed";
+
+/* ------------------------------------------------------------------------- */
+/* What the video service can tell us, and what it cannot                     */
+/* ------------------------------------------------------------------------- */
+
+/**
+ * EVERYTHING THIS BROWSER CAN HONESTLY KNOW ABOUT A CROSS-ORIGIN PLAYER.
+ *
+ * The player is another origin's page in an `<iframe>`, so the list is short
+ * and it is worth writing down, because the badge is built only from this:
+ *
+ * 1. **`load` fires** → that origin returned a document. Nothing more. The
+ *    video service answers `GET /<channel>` with the same HTML for a channel
+ *    that has no camera behind it, so `load` on a dead camera is normal.
+ * 2. **`load` never fires** → DNS, TLS or the connection failed, or the service
+ *    is down. Only observable as *absence*, hence the timeout.
+ * 3. **`error` fires** → rare in practice for cross-origin frames, but free.
+ * 4. **`postMessage` from that origin** → the only channel that could carry
+ *    "a frame decoded". The service does not send one today; `playerSignal`
+ *    below is the listener, so the day it does, the wall goes green with no
+ *    further frontend release.
+ *
+ * NOT available, and we must stop pretending otherwise: the frame rate, the
+ * canvas pixels, the WebSocket's state, whether ffmpeg upstream is producing
+ * anything. All of those live inside the other origin's document and the
+ * browser blocks every route to them — correctly.
+ *
+ * Opening our own WebSocket to the service to check would start a SECOND
+ * decode of the same camera per tile, which is a real load on the recorder for
+ * a status dot. Rejected.
+ */
+export type TPlayerSignal = "playing" | "stalled" | "failed" | null;
+
+/**
+ * Reads a `postMessage` payload from the video service.
+ *
+ * Deliberately forgiving about shape and deliberately strict about origin —
+ * the origin check belongs to the caller, which has the camera's address; this
+ * only decides what a message MEANS. Anything unrecognised is `null`, which
+ * leaves the tile exactly where it was: an unknown message must never be able
+ * to turn a badge green.
+ */
+export function playerSignal(data: unknown): TPlayerSignal {
+  const event =
+    typeof data === "string"
+      ? data
+      : data && typeof data === "object"
+        ? String((data as Record<string, unknown>).event ?? (data as Record<string, unknown>).type ?? "")
+        : "";
+
+  switch (event.trim().toLowerCase()) {
+    case "frame":
+    case "videodecode":
+    case "playing":
+      return "playing";
+    case "stalled":
+    case "paused":
+      return "stalled";
+    case "error":
+    case "sourceclosed":
+      return "failed";
+    default:
+      return null;
+  }
+}
+
+/**
+ * The origin a message must come from to be believed, or `""` for an address
+ * that is not a URL at all. Kept here so the rule is tested rather than
+ * inlined in a component.
+ */
+export function playerOrigin(host: string | null | undefined): string {
+  if (!host) return "";
+  try {
+    return new URL(host).origin;
+  } catch {
+    return "";
+  }
+}
 
 export type TTileView = {
   state: TTileState;
   label: string;
-  /** A sentence for the states that need explaining; `null` when live. */
+  /**
+   * A sentence that COVERS THE TILE. Only for states where there is nothing
+   * worth looking at underneath it — never over a picture that may be fine.
+   */
   detail: string | null;
+  /**
+   * A quieter sentence for the badge's tooltip and the focused camera's panel.
+   * `unverified` uses this rather than `detail` for exactly one reason: there
+   * may well be a good picture under that badge, and a scrim over a working
+   * camera would be a worse lie than the one being fixed.
+   */
+  note: string | null;
   /** Whether the player page may be embedded at all. */
   showPlayer: boolean;
 };
 
+/**
+ * The sentence behind "Not verified", said once on the focused camera's panel
+ * rather than nine times across the wall. Invented here: no server has a
+ * reason code for "your browser cannot see inside another origin's page".
+ */
+export const UNVERIFIED_DETAIL =
+  "The video page loaded, but this browser cannot confirm a picture is arriving. The player belongs to the video service and a browser cannot look inside it. Judge the tile by what you can see, and report a blank or frozen picture.";
+
 /**
  * Rule 4, plus every reason a tile may have nothing to show.
  *
  * Order matters: the browser being offline beats everything (it explains every
  * tile at once), then the record's own problems, then the server's verdict on
  * live video, and only then what the embedded page is actually doing.
+ *
+ * ## WHY THIS NO LONGER SAYS "Live" WHEN THE PAGE LOADS
+ *
+ * It used to, and it was wrong in production: on a live wall, one camera
+ * rendered pure white and another pure black, and both carried a green "Live".
+ * A third, on a nine-tile layout, was a black rectangle with a green dot. In
+ * every case the player page had loaded and no picture was arriving.
+ *
+ * The badge was asserting a fact nobody had checked. The video service returns
+ * its player HTML for any channel — including one with no camera behind it —
+ * so the `load` event proves the SERVICE is up and proves nothing at all about
+ * the CAMERA. Building "Live" on it is the same class of defect as the mobile
+ * app's "Live" badge over a nine-second-old still: a guard is told he is
+ * watching something he is not.
+ *
+ * So the page loading now earns `unverified`, and `live` is reserved for a
+ * frame the video service actually reported (`playerSignal`). Today no camera
+ * on this estate will reach `live`, and that is the honest answer rather than
+ * a comfortable one. The two-line change on the video service's side that
+ * would light these up is described in the PR; it is not ours to make.
+ *
+ * A tile deliberately does NOT decay from `unverified` to `no-signal` on a
+ * timer. Asserting death without evidence is the same mistake as asserting
+ * life without evidence, pointed the other way.
  */
 export function tileView(
   camera: TWallCamera | null | undefined,
@@ -256,6 +595,7 @@ export function tileView(
     state,
     label: TILE_LABELS[state],
     detail,
+    note: detail,
     showPlayer: false,
   });
 
@@ -277,23 +617,190 @@ export function tileView(
   if (live.state === "unsupported") return dead("unavailable", live.detail);
 
   const player = opts.player ?? "loading";
-  if (player === "timeout")
-    return {
-      state: "no-signal",
-      label: TILE_LABELS["no-signal"],
+  const showing = (state: TTileState, detail: string | null): TTileView => ({
+    state,
+    label: TILE_LABELS[state],
+    detail,
+    note: detail,
+    showPlayer: true,
+  });
+
+  switch (player) {
+    case "failed":
       // Invented: only the browser can know the page never loaded, so the
       // server has no reason code for it. Worded as a fact, not a diagnosis —
       // we genuinely cannot tell a dead camera from a dead video service.
-      detail: "The live view did not load. The camera or the video service may be down.",
-      showPlayer: true,
-    };
-  if (player === "loading")
-    return {
-      state: "connecting",
-      label: TILE_LABELS.connecting,
-      detail: null,
-      showPlayer: true,
-    };
+      return showing(
+        "no-signal",
+        "The live view did not load. The camera or the video service may be down."
+      );
+    case "stalled":
+      // It WAS playing and stopped. That is the one case where we can say a
+      // picture has genuinely gone away, because we saw one arrive first.
+      return showing(
+        "no-signal",
+        "The picture stopped arriving. The camera or the video service may have dropped."
+      );
+    case "playing":
+      return showing("live", null);
+    case "page-up":
+      return { ...showing("unverified", null), note: UNVERIFIED_DETAIL };
+    default:
+      return showing("connecting", null);
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Health — RULE 6                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * One camera's health, as `GET /site-cameras/site/:siteId/health` returns it.
+ *
+ * **Reachability is a per-RECORDER answer**, cached per recorder on the server:
+ * twelve cameras hanging off one device is one TCP connect shared between the
+ * tiles, not twelve. That is why a wall may ask for this at all.
+ *
+ * **`firmwareVersion` and `deviceTime` are null on this estate and say why.**
+ * They are facts you get over the recorder's HTTP interface, which is not
+ * reachable — so the server sends `detailUnavailableReason` rather than leaving
+ * two empty fields to read as "checked, and fine".
+ */
+export type TWallCameraHealth = {
+  health?: "ok" | "drifted" | "unreachable" | "unsupported" | null;
+  reachable?: boolean | null;
+  reason?: string | null;
+  /** ISO timestamp of the last picture this server actually got. */
+  lastFrameAt?: string | null;
+  driftSeconds?: number | null;
+  firmwareVersion?: string | null;
+  deviceTime?: string | null;
+  detailUnavailableReason?: string | null;
+};
+
+export type THealthTone = "ok" | "warn" | "down" | "unknown";
+
+export type THealthView = {
+  tone: THealthTone;
+  /** Always a whole short phrase — never a bare word beside a dot. */
+  label: string;
+  /** The server's own sentence when it sent one. */
+  detail: string | null;
+  /** "4 min ago", or `null` when this server has never had a picture. */
+  lastFrame: string | null;
+  /** Why firmware and clock are blank. The server's sentence, verbatim. */
+  deviceDetail: string | null;
+};
+
+const HEALTH_LABELS: Record<string, { tone: THealthTone; label: string }> = {
+  ok: { tone: "ok", label: "Recorder responding" },
+  drifted: { tone: "warn", label: "Recorder clock is out" },
+  unreachable: { tone: "down", label: "Recorder not responding" },
+  unsupported: { tone: "unknown", label: "Not checked" },
+};
+
+/**
+ * Rule 6. This is about the RECORDER, and the tile's own badge is about the
+ * player page — the two are reported separately and never merged, because they
+ * genuinely disagree: a working relay in front of a dead recorder shows a live
+ * page and an unreachable device, and a supervisor who is told only "Live"
+ * learns the wrong thing.
+ */
+export function healthView(
+  health: TWallCameraHealth | null | undefined,
+  now: number = Date.now()
+): THealthView {
+  const known = health?.health ? HEALTH_LABELS[health.health] : undefined;
+  const fallback: { tone: THealthTone; label: string } =
+    health?.reachable === true
+      ? HEALTH_LABELS.ok
+      : health?.reachable === false
+        ? HEALTH_LABELS.unreachable
+        : { tone: "unknown", label: "Health not checked yet" };
+
+  const { tone, label } = known ?? fallback;
 
-  return { state: "live", label: TILE_LABELS.live, detail: null, showPlayer: true };
+  return {
+    tone,
+    label,
+    detail: (health?.reason || "").trim() || null,
+    lastFrame: agoLabel(health?.lastFrameAt, now),
+    deviceDetail: (health?.detailUnavailableReason || "").trim() || null,
+  };
+}
+
+/**
+ * "just now" / "40s ago" / "6 min ago" / "3 h ago".
+ *
+ * Coarse on purpose above a minute: a supervisor is deciding whether a picture
+ * is CURRENT, and "6 min ago" answers that where "371s ago" makes them do
+ * arithmetic to reach the same answer.
+ */
+export function agoLabel(iso: string | null | undefined, now: number = Date.now()): string | null {
+  if (!iso) return null;
+  const at = Date.parse(iso);
+  if (!Number.isFinite(at)) return null;
+
+  const seconds = Math.max(0, Math.round((now - at) / 1000));
+  if (seconds < 5) return "just now";
+  if (seconds < 60) return `${seconds}s ago`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)} min ago`;
+  return `${Math.round(seconds / 3600)} h ago`;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Digital zoom                                                                */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * DIGITAL ZOOM IS CROPPING, NOT PTZ, AND THE DIFFERENCE IS THE WHOLE POINT.
+ *
+ * This magnifies the picture already on the screen. **No request leaves the
+ * browser and no hardware moves** — which is exactly why it works today on
+ * every camera while "Move camera" does not, and why the two must never look
+ * like the same control.
+ *
+ * The arithmetic is identical to the mobile build's (`zoomable.tsx`), including
+ * the 4x ceiling, so the same gesture gives the same result on a phone and on a
+ * laptop.
+ */
+export const MAX_DIGITAL_ZOOM = 4;
+
+/** Beyond 4x a substream frame is enlarged pixels — a magnification that shows
+ *  less than you started with is a control that lies. */
+export function clampZoom(scale: number): number {
+  if (!Number.isFinite(scale)) return 1;
+  return Math.min(MAX_DIGITAL_ZOOM, Math.max(1, scale));
+}
+
+/**
+ * Keeps the magnified picture covering the tile.
+ *
+ * At scale `s` the picture is `s` times the frame, so it may be moved by half
+ * the overflow each way and no further. Without this a drag walks the picture
+ * off the tile and leaves a supervisor looking at the background — arriving at
+ * the blank-rectangle failure this whole surface exists to prevent, by gesture.
+ */
+export function clampPan(
+  offset: { x: number; y: number },
+  scale: number,
+  frame: { width: number; height: number }
+): { x: number; y: number } {
+  const limitX = Math.max(0, (frame.width * (scale - 1)) / 2);
+  const limitY = Math.max(0, (frame.height * (scale - 1)) / 2);
+
+  return {
+    x: Math.min(limitX, Math.max(-limitX, offset.x || 0)),
+    y: Math.min(limitY, Math.max(-limitY, offset.y || 0)),
+  };
+}
+
+/**
+ * One wheel notch. `deltaY` varies wildly between a mouse, a trackpad and a
+ * browser's delta mode, so the DIRECTION is used and the magnitude is not: a
+ * fixed step is predictable everywhere, and predictability is worth more here
+ * than proportionality.
+ */
+export function zoomStep(scale: number, deltaY: number): number {
+  return clampZoom(deltaY < 0 ? scale * 1.25 : scale / 1.25);
 }