@7365admin1/layer-common 3.2.4 → 3.2.5

package/utils/camera-wall.ts

@@ -0,0 +1,926 @@
+/**
+ * THE CAMERA WALL'S RULES, WITH NO MARKUP IN THEM.
+ *
+ * `CameraWall.vue` draws the wall; this file decides what it is allowed to draw.
+ * Keeping the two apart is not tidiness — every rule below is one somebody can
+ * get wrong in a way nobody notices until a supervisor is looking at the wrong
+ * picture, so each one is stated once, here, and pinned by `camera-wall.test.ts`.
+ *
+ * ## The four rules
+ *
+ * 1. **Only `type: "ip"` cameras go on a wall.** An ANPR unit belongs to visitor
+ *    and vehicle management: it is pointed at a number plate, it is wired to a
+ *    barrier, and its record carries a real device address and a real credential.
+ *    Putting one on a monitoring wall is a defect, not a feature. The request
+ *    already asks the server for `type=ip`; `wallCameras()` filters again on the
+ *    way in, because "the caller passed the right query" is an assumption and
+ *    this is the rule.
+ * 2. **A capability we have not been told about is NOT available.** An absent or
+ *    malformed descriptor reads as `unknown`, and `unknown` counts as no — so a
+ *    browser talking to an older API cannot draw a control that would do nothing.
+ * 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", 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
+ * and on a laptop.
+ */
+
+/** One capability's answer, as the API returns it (core's `CameraCapabilityEntry`). */
+export type TWallCapability = {
+  state?: "supported" | "unsupported" | "unknown";
+  transport?: string | null;
+  reason?: string | null;
+  /** The server's own sentence. Displayed verbatim; never rewritten here. */
+  detail?: string | null;
+};
+
+/** A camera as the wall needs it. Extra fields on the record are ignored. */
+export type TWallCamera = {
+  _id: string;
+  name?: string;
+  /**
+   * The stored address. For a `type: "ip"` camera this is a complete, directly
+   * renderable live-video page — it is the picture, not a fragment to resolve.
+   */
+  host?: string;
+  type?: string;
+  status?: string;
+  capabilities?: Record<string, TWallCapability>;
+  /**
+   * The server's own sentence for why this camera cannot show a picture, or
+   * `null`/absent when it can. Answered from the record before anything is
+   * requested, so it costs no device traffic.
+   *
+   * **Preferred over anything worked out here.** The server knows things the
+   * browser cannot — that no recorder is configured for this camera's relay, for
+   * instance, which is the true answer for every camera until the API host is
+   * configured. Replacing it with our own wording hides that.
+   */
+  unavailableReason?: string | null;
+};
+
+/* -------------------------------------------------------------------------- */
+/* Layouts                                                                     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The three wall sizes.
+ *
+ * Square only, and only three of them. A VMS layout picker exists so a
+ * supervisor can change what they are watching in one click; a list of eleven
+ * arrangements is a settings screen wearing a toolbar's clothes.
+ */
+export const WALL_LAYOUTS = [
+  { key: "1x1", columns: 1, tiles: 1, label: "Single" },
+  { key: "2x2", columns: 2, tiles: 4, label: "Four" },
+  { key: "3x3", columns: 3, tiles: 9, label: "Nine" },
+] as const;
+
+export type TWallLayoutKey = (typeof WALL_LAYOUTS)[number]["key"];
+
+/** Four tiles: enough to be a wall, small enough to still be readable. */
+export const DEFAULT_WALL_LAYOUT: TWallLayoutKey = "2x2";
+
+export function wallLayout(key: string | undefined) {
+  return WALL_LAYOUTS.find((l) => l.key === key) ?? WALL_LAYOUTS[1];
+}
+
+/**
+ * At three columns a tile is small enough that the chrome starts eating the
+ * 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;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Which cameras, and in what order                                            */
+/* -------------------------------------------------------------------------- */
+
+/** Rule 1. Only `type: "ip"`. See the note at the top of this file. */
+export function wallCameras(items: unknown): TWallCamera[] {
+  if (!Array.isArray(items)) return [];
+  return items.filter(
+    (c): c is TWallCamera => !!c && typeof c === "object" && (c as TWallCamera).type === "ip"
+  );
+}
+
+/**
+ * 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.
+ */
+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
+): 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 chosen = wallChosen(cameras, selectedIds);
+  const start = clampPage(page, wallPageCount(cameras, selectedIds, layoutKey)) * tiles;
+
+  return chosen.slice(start, start + tiles);
+}
+
+/**
+ * WHICH TILE THE DETAIL PANEL IS ABOUT, and the guarantee that makes the panel
+ * able to stop naming it.
+ *
+ * The panel used to print the camera's name so the reader could tell which of
+ * up to nine tiles it was describing. The name is gone — the selected tile wears
+ * an accent ring instead — and that only works because **this can never return a
+ * camera that is not on the page being looked at.** It resolves out of the
+ * CURRENT page's tiles, so a selection left behind on page 1 does not leave the
+ * panel describing an invisible camera from page 2; it falls back to the first
+ * tile of the page you are actually on, which the ring then marks.
+ *
+ * The caller keeps the raw id, so paging back restores the original selection.
+ *
+ * Extracted from the component purely so this guarantee is a tested rule rather
+ * than a line of template nobody would think to check.
+ */
+export function focusedCamera(
+  tiles: TWallCamera[],
+  focusedId: string | undefined
+): TWallCamera | null {
+  return tiles.find((c) => c._id === focusedId) || tiles[0] || null;
+}
+
+/**
+ * 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)));
+}
+
+/* -------------------------------------------------------------------------- */
+/* Capabilities                                                                */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The two words a switched-off control wears.
+ *
+ * Lifted unchanged from the mobile build, and the "yet" is the whole point: it
+ * is the difference between a feature that is broken and a feature that is
+ * 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;
+
+/**
+ * What a client with no descriptor at all should say. This is the server's own
+ * `device-not-probed` sentence, reused rather than reinvented, so an older API
+ * that sends no descriptor still explains itself in the product's own words.
+ */
+const NOT_PROBED = "This camera has not been asked what it can do yet.";
+
+/**
+ * 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.
+ *
+ * ## "Ask your Seven365 administrator" was a dead end, and it has been replaced
+ *
+ * That was the whole of the advice, and the owner — who IS the administrator —
+ * read it on the live wall and pointed out that it tells him nothing. It tells a
+ * property manager nothing either: they raise a ticket and wait, because the
+ * screen never said what the ticket should ASK FOR.
+ *
+ * The real answer is two changes, and they are two different jobs for two
+ * different people:
+ *
+ *  1. **a network change** — the site's network has to let our server reach the
+ *     camera recorder. Today it does not: the recorder answers video only.
+ *  2. **a configuration change on our server** — that recorder then has to be
+ *     added to the server's configuration.
+ *
+ * So each line below names the change that is missing and who does it, in that
+ * order. **No environment variable is named**, deliberately: the names belong in
+ * the deployment documentation (`iservice365-core/docs/camera-integration-config.md`),
+ * not on a property manager's screen, and printing them would make the sentence
+ * unreadable to the person it is written for without helping the person who
+ * needs them, who has the document.
+ *
+ * Nor does any line point at the camera setup guide. That guide covers ADDING a
+ * camera in Site Settings; it does not cover recorder connectivity, so sending
+ * the reader there would be sending them somewhere that does not answer the
+ * question. Naming the two changes IS the actionable content.
+ */
+export const CAPABILITY_NEXT_STEPS: Record<string, string> = {
+  "device-http-not-configured":
+    "Not switchable from this page. It needs the site's network opened so our server can reach the camera recorder, and that recorder then added to the server's configuration — your Seven365 administrator arranges both with whoever installed the cameras.",
+  "device-http-disabled":
+    "Not switchable from this page. The connection to the recorder exists but is turned off in the server's configuration — your Seven365 administrator turns it on.",
+  "device-http-unreachable":
+    "Our server cannot reach this camera's recorder. Usually the site's network is blocking it or the recorder is down — your Seven365 administrator and whoever installed the cameras check it between them.",
+  "device-http-locked-out":
+    "Sign-ins to the recorder are being held back so its account is not locked out. It clears on its own; if it keeps happening the password held for the recorder is wrong and your Seven365 administrator corrects it in the server's configuration.",
+  "control-not-enabled":
+    "Not switchable from this page. This one moves real hardware, so a Seven365 backend lead has to approve it before it is turned on in the server's configuration.",
+  "device-no-ptz":
+    "This camera cannot move, so there is nothing to switch on. A different camera would be needed.",
+  "no-recorder-configured":
+    "Not switchable from this page. This camera's video service has no recorder linked to it in the server's configuration — your Seven365 administrator adds 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":
+    "Not built yet. Nothing on this server can do it.",
+};
+
+/**
+ * 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 =
+  "Not switchable from this page — it needs a change to the server's configuration, which your Seven365 administrator makes.";
+
+/**
+ * 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: "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;
+  /** 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;
+};
+
+/** Rules 2, 3 and 5, in one place. */
+export function capabilityView(
+  camera: TWallCamera | null | undefined,
+  key: string
+): TCapabilityView {
+  const entry = camera?.capabilities?.[key];
+  const state =
+    entry?.state === "supported" || entry?.state === "unsupported"
+      ? 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: 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),
+  };
+}
+
+/**
+ * RULE 7 — SAY IT ONCE FOR THE GROUP WHEN IT IS ONE FACT, NOT FOUR.
+ *
+ * On this estate all four of the switched-off controls are off for the SAME
+ * reason: there is no direct connection to the recorder. So the panel drew four
+ * cards, each carrying an identical sentence and an identical next step —
+ * eight lines of repetition saying one thing. Four copies of a sentence do not
+ * make it four facts; they make the reader skim, and skimming is how the one
+ * line that mattered got missed.
+ *
+ * So when every unavailable control shares the same reason, this returns it and
+ * the panel prints it once above the row. Each card keeps its own title and its
+ * own tag, so the individual state is never lost — only the echo is.
+ *
+ * Returns `null` the moment the reasons DIFFER, which is the case that must not
+ * be flattened: "the recorder is unreachable" and "this camera cannot move" are
+ * two different problems with two different people to ask, and merging them
+ * would be a lie of convenience. Also `null` when nothing is off (nothing to
+ * explain) or when only one control is off (a group note for a group of one is
+ * just the card, moved).
+ */
+export function sharedCapabilityNote(
+  camera: TWallCamera | null | undefined,
+  keys: readonly string[]
+): { detail: string; nextStep: string | null } | null {
+  const off = keys
+    .map((key) => capabilityView(camera, key))
+    .filter((view) => !view.available);
+
+  if (off.length < 2) return null;
+
+  const first = off[0];
+  const same = off.every(
+    (view) => view.detail === first.detail && view.nextStep === first.nextStep
+  );
+
+  return same && first.detail
+    ? { detail: first.detail, nextStep: first.nextStep }
+    : null;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Tile state                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * How long a player page may take to load before the tile stops claiming it is
+ * coming. Deliberately generous — lifted from the mobile build, where the
+ * argument is that reporting a working video service as dead is the worse of
+ * the two mistakes.
+ */
+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 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`.
+ *
+ * It used to read "Not verified", which is a word from our side of the fence:
+ * it describes a check we did not manage to make. "Not confirmed" describes the
+ * PICTURE, which is the only thing the reader cares about, and it is the same
+ * claim. The instruction that goes with it — check the tile — is in
+ * `UNVERIFIED_DETAIL`, on the badge's tooltip and once on the panel.
+ */
+export const TILE_LABELS = {
+  live: "Live",
+  unverified: "Not confirmed",
+  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.
+ *
+ * - `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 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 confirmed", said once on the focused camera's panel
+ * rather than nine times across the wall.
+ *
+ * **Written for a guard or a property manager, not for us.** The first version
+ * of this line explained cross-origin isolation — "the player belongs to the
+ * video service and a browser cannot look inside it" — which is true, is the
+ * reason, and is none of the reader's business. The owner read it on the live
+ * wall and said so. A reader of this screen has exactly three questions: is
+ * this camera working, what do I do if it is not, and what can I do here. WHY
+ * the software cannot answer the first one is our problem, not theirs.
+ *
+ * So: what we cannot do, then what they should do. Nothing else. The claim is
+ * every bit as honest as the paragraph it replaces — it just stops making the
+ * reader sit through an engineering lesson to get to the instruction.
+ */
+export const UNVERIFIED_DETAIL =
+  "This page cannot confirm the picture is arriving, so check the tile yourself. If it is blank or frozen, report the camera.";
+
+/**
+ * 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,
+  opts: { online?: boolean; player?: TPlayerState } = {}
+): TTileView {
+  const online = opts.online !== false;
+  const dead = (state: TTileState, detail: string | null): TTileView => ({
+    state,
+    label: TILE_LABELS[state],
+    detail,
+    note: detail,
+    showPlayer: false,
+  });
+
+  if (!camera) return dead("unavailable", "No camera in this position.");
+  if (!online)
+    return dead("offline", "This browser has no internet connection.");
+  // The server's refusal wins over anything reconstructed here. It covers the
+  // same two cases below AND the ones only it can know — chiefly "no recorder is
+  // configured for this camera's relay", which is the honest answer for every
+  // camera until the API host is configured, and which used to be replaced by
+  // our own guess.
+  const reason = camera.unavailableReason?.trim();
+  if (reason) return dead("unavailable", reason);
+  if (camera.status && camera.status !== "active")
+    return dead("unavailable", "This camera is not active.");
+  if (!camera.host) return dead("unavailable", "This camera has no address configured.");
+
+  const live = capabilityView(camera, "liveVideo");
+  if (live.state === "unsupported") return dead("unavailable", live.detail);
+
+  const player = opts.player ?? "loading";
+  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.
+      return showing(
+        "no-signal",
+        "No picture. The camera or the video service may be down. Report it if it stays like this."
+      );
+    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. Report it if it does not come back."
+      );
+    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;
+};
+
+/*
+  THE FIRMWARE-AND-CLOCK LINE IS GONE, AND IT IS NOT COMING BACK.
+
+  The server sends `detailUnavailableReason` — "Firmware and device clock are
+  not available: this recorder is reachable over video only." — so that two
+  blank fields do not read as "checked, and fine". That is a good reason to
+  send it and a bad reason to DRAW it: this screen never showed firmware or a
+  device clock in the first place, so the sentence was explaining the absence
+  of something the reader had not been offered and could not use. A guard
+  cannot act on a firmware version. Softening the wording would have kept the
+  noise, so the line is removed instead. The field is still on
+  `TWallCameraHealth` because the API sends it; nothing on the wall draws it.
+*/
+
+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: "Recorder 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: "Recorder not checked yet" };
+
+  const { tone, label } = known ?? fallback;
+
+  return {
+    tone,
+    label,
+    detail: (health?.reason || "").trim() || null,
+    lastFrame: agoLabel(health?.lastFrameAt, now),
+  };
+}
+
+/**
+ * "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);
+}