@songsid/agend 2.3.1 → 2.3.2-beta.2

package/dist/ui/fleet-office-model.js

@@ -6,14 +6,16 @@
 //   office the page makes itself (AUTO_ID, "the whole fleet", built from the teams as the canvas is), whose member
 //   filter is the team / people picker; any other office is the host's (GET /ui/offices, fleet-office-store.js),
 //   checked again here.
-//   TODO(office editor): adding and renaming offices, assigning people, dragging seats and drawing paths is a later
-//   step; it writes the same model through the store's saveOffices().
+//   The office editor (fleet-office-editor.js) adds, renames and deletes offices and picks who is in them; the layout
+//   editor (fleet-office-layout.js, #2513) moves things on a zones skin and keeps them as the office's `overrides`
+//   (fleet-office-pack.js) — both write the same model through the store's saveOffices().
 // - The auto layout: a lobby (General and the instances in no team), then a room per team in fleet.yaml's order, in a
 //   grid that wraps at the stage's width (a phone gets narrower rooms); a desk per member; a corridor graph of waypoints
 //   (each desk's aisle, a spine down each room's left padding, its door, a corridor under each row of rooms and one down
 //   the left margin) that traffic walks along (bfsPath).
 // - Poses come from the org chart's states (fleet-org.js ORG_STATES / orgState); nothing here invents a status.
 import { hue } from "./fleet-traffic.js";
+import { checkLayoutOverrides } from "./fleet-office-pack.js";
 
 // ── Poses: the org chart's states, as a character at a desk ──
 
@@ -115,7 +117,8 @@ export function officeOk(x) {
   if (!x || typeof x !== "object" || typeof x.id !== "string" || !ID.test(x.id) || x.id === AUTO_ID) return null;
   const name = typeof x.name === "string" && x.name.trim() ? x.name.trim().slice(0, 60) : x.id;
   const skin = typeof x.skin === "string" && ID.test(x.skin) ? x.skin : "pixel";
-  return { id: x.id, name, skin, members: nameList(x.members), layout: layoutOk(x.layout) };
+  const ov = x.overrides === undefined ? null : checkLayoutOverrides(x.overrides);
+  return { id: x.id, name, skin, members: nameList(x.members), layout: layoutOk(x.layout), ...(ov && ov.ok ? { overrides: ov.overrides } : {}) };
 }
 /** A stored list of offices: the valid ones, ids unique, at most MAX_OFFICES. */
 export function officesOk(list) {

package/dist/ui/fleet-office-overview.js

@@ -0,0 +1,167 @@
+// #2554: the Office view's "All offices" — every stored office as a tile on one canvas, side by side, each drawn exactly
+// as its own view would be (its style, its members, seats, poses, bubbles, walking), scaled into its tile. This module
+// is the pure part (fleet-office.js draws it): who is in no office (the lobby tile), where the tiles go, what a point
+// on the overview hits, which tiles are on screen, and the traffic that crosses between tiles.
+//
+// - Shown when at least two offices are stored (overviewOk); an id no stored office can have (ALL_ID: '*' is not an
+//   office id's character), kept per device as any office pick is.
+// - The tiles: each as large as its office's drawn content — a zones scene its 1280×720, a desks office its rooms'
+//   bounds (cropToRooms: an office of three is small) — scaled down to at most CELL_W × CELL_H, never up; a LABEL band
+//   above each (the page's label sits there), GAP apart, M from the edge. Shelf packing in the stored order (the lobby
+//   last): a row takes tiles while they fit a row width, each row as tall as its tallest tile and centred across. The
+//   row width: whichever (of the widths a run of tiles makes) lets the whole overview show largest in the panel (Fit's
+//   contain); a tie keeps the narrower. The same input always gives the same picture.
+// - Traffic between people in different tiles is a straight flight between their seats in overview coordinates
+//   (createCrossFlights); between two people in the same tile it is that tile's own (createFlights, along its corridors).
+import { FLIGHT, along, desksOf, membersOf, pathLength } from "./fleet-office-model.js";
+import { hue } from "./fleet-traffic.js";
+
+/** The switcher's "All offices" value: '*' is never in a stored office's id (fleet-office-model.js officeOk). */
+export const ALL_ID = "*all";
+/** The lobby tile's key: never an office's id. */
+export const LOBBY_TILE = "\u0000lobby";
+/** The overview's geometry, in logical units. */
+export const OV = { CELL_W: 1280, CELL_H: 720, LABEL: 56, GAP: 24, M: 24 };
+
+/** Whether "All offices" is offered: at least two stored offices. */
+export const overviewOk = (stored) => Array.isArray(stored) && stored.length >= 2;
+
+/**
+ * The people in no stored office, in the org chart's order (General, the teams, the rest): the lobby tile's. An office
+ * with no members holds everyone (fleet-office-model.js membersOf), so then nobody is left for the lobby.
+ */
+export function lobbyNodes(stored, view) {
+  const placed = new Set((stored || []).flatMap((o) => membersOf(o, view).map((n) => n.name)));
+  const out = new Map();
+  for (const n of [...view.top, ...view.teams.flatMap((tm) => tm.nodes), ...view.rest.nodes]) if (!placed.has(n.name) && !out.has(n.name)) out.set(n.name, n);
+  return [...out.values()];
+}
+
+/** A scene's scale in its tile: its own size, scaled down to fit a CELL_W × CELL_H cell (never up). */
+export const tileScale = (w, h) => Math.min(1, OV.CELL_W / Math.max(1, w), OV.CELL_H / Math.max(1, h));
+
+/**
+ * A desks layout cropped to its rooms: everything moved so the rooms' bounds start at (0, 0), its size theirs (the
+ * corridors outside the rooms and the margins are not part of a tile). Unchanged when it has no rooms.
+ */
+export function cropToRooms(L) {
+  if (!L.rooms.length) return L;
+  const x0 = Math.min(...L.rooms.map((r) => r.x)), y0 = Math.min(...L.rooms.map((r) => r.y));
+  const x1 = Math.max(...L.rooms.map((r) => r.x + r.w)), y1 = Math.max(...L.rooms.map((r) => r.y + r.h));
+  const mv = (p) => ({ ...p, x: p.x - x0, y: p.y - y0 });
+  return { ...L, rooms: L.rooms.map((r) => ({ ...mv(r), desks: r.desks.map((d) => ({ ...mv(d), seat: mv(d.seat) })) })), waypoints: (L.waypoints || []).map(mv),
+    width: x1 - x0, height: y1 - y0 };
+}
+
+/**
+ * The tiles of `scenes` ([{ key, w, h }], in order) on shelves at most `rowW` wide (a tile wider than that has a row of
+ * its own): each { key, x, y, w, h, s (its scale), label: { x, y, w, h } (the band above it) }; and the overview's size.
+ * Each row is centred across the widest; its tiles stand at its top, under their labels.
+ */
+export function arrangeTiles(scenes, rowW) {
+  const { LABEL, GAP, M } = OV;
+  const rows = [];
+  let row = null;
+  for (const sc of scenes) {
+    const s = tileScale(sc.w, sc.h), it = { key: sc.key, s, w: Math.max(1, sc.w) * s, h: Math.max(1, sc.h) * s };
+    if (!row || row.w + GAP + it.w > rowW + 1e-6) { row = { items: [], w: -GAP, h: 0 }; rows.push(row); }
+    row.items.push(it); row.w += GAP + it.w; row.h = Math.max(row.h, it.h);
+  }
+  const inner = rows.length ? Math.max(...rows.map((r) => r.w)) : 0, tiles = [];
+  let y = M;
+  for (const r of rows) {
+    let x = M + (inner - r.w) / 2;
+    for (const it of r.items) {
+      tiles.push({ key: it.key, x, y: y + LABEL, w: it.w, h: it.h, s: it.s, label: { x, y, w: it.w, h: LABEL } });
+      x += it.w + GAP;
+    }
+    y += LABEL + r.h + GAP;
+  }
+  return { rows: rows.length, rowW, tiles, width: 2 * M + inner, height: rows.length ? y - GAP + M : 2 * M };
+}
+
+/**
+ * The tiles packed for a `size` panel: of the row widths a run of consecutive tiles makes, the one whose overview shows
+ * largest there (min of the two fits); a tie keeps the narrower.
+ */
+export function tileLayout(scenes, size) {
+  const ws = scenes.map((sc) => Math.max(1, sc.w) * tileScale(sc.w, sc.h)), cands = new Set();
+  for (let i = 0; i < ws.length; i++) { let run = -OV.GAP; for (let j = i; j < ws.length; j++) { run += OV.GAP + ws[j]; cands.add(run); } }
+  let best = arrangeTiles(scenes, 0), bestK = -1;
+  for (const rowW of [...cands].sort((a, b) => a - b)) {
+    const a = arrangeTiles(scenes, rowW), k = Math.min(size.w / a.width, size.h / a.height);
+    if (k > bestK + 1e-9) { best = a; bestK = k; }
+  }
+  return best;
+}
+
+/** The tile whose scene holds the overview point (x, y), or null. */
+export const tileAt = (lay, x, y) => lay.tiles.find((t) => x >= t.x && x < t.x + t.w && y >= t.y && y < t.y + t.h) || null;
+/** The tile whose label band holds the overview point, or null. */
+export const labelAt = (lay, x, y) => lay.tiles.find((t) => x >= t.label.x && x < t.label.x + t.label.w && y >= t.label.y && y < t.label.y + t.label.h) || null;
+/** Overview → the tile's own scene units, and back; a box in the scene → the overview. */
+export const inTile = (t, x, y) => ({ x: (x - t.x) / t.s, y: (y - t.y) / t.s });
+export const fromTile = (t, p) => ({ x: t.x + p.x * t.s, y: t.y + p.y * t.s });
+export const tileBox = (t, b) => ({ x: t.x + b.x * t.s, y: t.y + b.y * t.s, w: b.w * t.s, h: b.h * t.s });
+/** The tiles a view ({ k, x, y }) shows any of in a `size` viewport: the rest are not drawn. */
+export function visibleTiles(lay, v, size) {
+  return lay.tiles.filter((t) => {
+    const x = v.x + t.x * v.k, y = v.y + t.y * v.k;
+    return x < size.w && x + t.w * v.k > 0 && y < size.h && y + t.h * v.k > 0;
+  });
+}
+
+/**
+ * A straight flight between two people in different tiles: [the sender's seat, the receiver's] in overview units (the
+ * first tile each is in), or null — when either is drawn nowhere, or some tile holds both (that tile carries it along
+ * its corridors). `parts`: [{ tile, L }] in the tiles' order.
+ */
+export function crossPath(parts, from, to) {
+  let a = null, z = null;
+  for (const p of parts) {
+    const ds = desksOf(p.L), da = ds.find((d) => d.node.name === from), dz = ds.find((d) => d.node.name === to);
+    if (da && dz) return null;
+    if (da && !a) a = fromTile(p.tile, da.seat);
+    if (dz && !z) z = fromTile(p.tile, dz.seat);
+  }
+  return a && z ? [a, z] : null;
+}
+
+const MAX_SEEN = 2000;
+/**
+ * The items in the air between tiles — fleet-office-model.js createFlights's lifecycle (each new item once; none for a
+ * stale delegation or with reduced motion), on crossPath's straight line: `frame(now, parts)` → { id, hue, kind, x, y,
+ * t } in overview units; a trip with no crossing (both in one tile, or either gone) is dropped.
+ */
+export function createCrossFlights({ max = FLIGHT.MAX } = {}) {
+  const seen = new Set();
+  let trips = [];
+  return {
+    sync(items, now, still = false) {
+      let k = 0, started = 0;
+      for (const it of items || []) {
+        if (seen.has(it.id)) continue;
+        seen.add(it.id);
+        if (seen.size > MAX_SEEN) seen.delete(seen.values().next().value);
+        if (still || it.phase === "stale") continue;
+        trips.push({ id: it.id, from: it.from, to: it.to, kind: it.kind, hue: hue(it.kind), start: now + k++ * FLIGHT.STAGGER_MS, parts: null, pts: null, ms: 0 });
+        started++;
+      }
+      if (trips.length > max) trips = trips.slice(trips.length - max);
+      return started;
+    },
+    frame(now, parts) {
+      const out = [];
+      trips = trips.filter((f) => {
+        if (f.parts !== parts) { f.parts = parts; f.pts = crossPath(parts, f.from, f.to); f.ms = f.pts ? Math.min(FLIGHT.MAX_MS, Math.max(FLIGHT.MIN_MS, pathLength(f.pts) / FLIGHT.SPEED)) : 0; }
+        if (!f.pts) return false;
+        const t = (now - f.start) / f.ms;
+        if (t >= 1) return false;
+        if (t >= 0) { const p = along(f.pts, t); out.push({ id: f.id, hue: f.hue, kind: f.kind, x: p.x, y: p.y, t }); }
+        return true;
+      });
+      return out;
+    },
+    size: () => trips.length,
+  };
+}

package/dist/ui/fleet-office-pack.d.ts

@@ -0,0 +1,39 @@
+// Types for fleet-office-pack.js: the page's module, which the host imports too (web-office-skins.ts,
+// web-office-store.ts), so both check a skin pack and an office's layout overrides by the same rules.
+/** `dw` × `dh`: its displayed size in logical units (w·scale × h·scale unless the manifest says otherwise). */
+export interface PackStrip { src: string; frames: number; w: number; h: number; fps: number; ax: number; ay: number; dw: number; dh: number }
+export interface PackPoint { x: number; y: number }
+export interface PackArea { name: string; rect: { x: number; y: number; w: number; h: number }; seats: PackPoint[] }
+export interface PackFurniture { id: string; sprite: PackStrip; x: number; y: number; depth: number | "y"; activeWhen: string[] | null; activeSprite: PackStrip | null }
+export interface CheckedPack {
+  format: 1; id: string; scale: number; background?: string; foreground?: string; matte?: string;
+  areas: Record<string, PackArea>; stateZones: Record<string, string> | null; door: PackPoint;
+  waypoints: Array<{ id: string; x: number; y: number }>; edges: Array<[string, string]>;
+  furniture: PackFurniture[]; characters: Record<string, Record<string, PackStrip>>; byInstance: Record<string, string>;
+  props: Record<string, PackStrip>; bubbles: Record<string, Record<string, string[]>>;
+  room: { floor?: string; wall?: string }; desk: { back?: string; front?: string; lit?: string };
+}
+export interface LayoutOverrides {
+  pack: string;
+  seats?: Record<string, Array<[number, number]>>;
+  furniture?: Record<string, [number, number]>;
+  door?: [number, number];
+  waypoints?: Array<{ id: string; x: number; y: number }>;
+  edges?: Array<[string, string]>;
+}
+export const LOGICAL: { w: number; h: number };
+export const CHAR_DEPTH: number;
+export const PACK_STATES: string[];
+export function own<T = unknown>(o: unknown, k: unknown): T | undefined;
+export function inherited(k: unknown): boolean;
+export function matteOk(v: unknown): v is string;
+export function checkStrip(v: unknown, at?: string, scale?: number): PackStrip;
+export function checkSkinPack(x: unknown): { ok: true; pack: CheckedPack } | { ok: false; error: string };
+export function skinPackOk(x: unknown): CheckedPack | null;
+export function packImages(pack: CheckedPack): string[];
+export function packStrips(pack: CheckedPack): Array<{ at: string; strip: PackStrip }>;
+export function checkLayoutOverrides(x: unknown): { ok: true; overrides: LayoutOverrides } | { ok: false; error: string };
+export function applyOverrides(pack: CheckedPack, ov: LayoutOverrides | null | undefined): { ok: true; pack: CheckedPack } | { ok: false; error: string };
+export function overridesBetween(pack: CheckedPack, edited: CheckedPack): LayoutOverrides | null;
+export function poseStrip(set: Record<string, PackStrip> | null | undefined, pose: string, heading?: { dx: number; dy: number } | null): { strip: PackStrip; mirror: boolean } | null;
+export function stripBox(st: PackStrip, x: number, y: number, mirror?: boolean): { x: number; y: number; w: number; h: number };

package/dist/ui/fleet-office-pack.js

@@ -1,16 +1,26 @@
-// The Office view's skin-pack format, v1 (fleet-office-skin.js draws a checked pack; nothing loads one from outside yet).
+// The Office view's skin-pack format, v1 (fleet-office-skin.js draws a checked pack; an admin uploads one — Fleet → Org
+// chart → Office → Edit offices → Upload a skin pack — and the host keeps it, src/web-office-skins.ts, checking it with
+// this same module: the page and the host agree on every rule).
 // Its shape follows Star-Office-UI's scene (MIT; github.com/ringhyacinth/Star-Office-UI): one background on a 16:9
 // logical canvas, named areas with ordered seat slots, furniture with a depth, and a state → area map. No code or art of
 // it is used here — the idea of the format only.
 //
 // A pack is a JSON manifest plus images. Every coordinate is in logical units on a 1280×720 canvas (LOGICAL), which
-// the page scales to fit its width. Images are pixel art, drawn unsmoothed at `scale` logical units per image pixel.
+// the page shows whole, then pans and zooms (fleet-office-view.js). Images are pixel art, drawn unsmoothed at `scale` logical units per image pixel.
 //
 //   {
 //     "format": 1,                                    required
 //     "id": "cozy",                                   letters, digits, - and _ (≤ 40); not a built-in skin's id
 //     "scale": 2,                                     1–8 (default 2)
 //     "background": "office.png",                     drawn over the whole 1280×720 canvas (16:9)
+//     "foreground": "front.png",                      optional, with stateZones: drawn over the whole canvas (16:9, as
+//                                                     the background) above the people, the furniture and the items in
+//                                                     the air, below the name tags, bubbles and "+n" counts (and Edit
+//                                                     layout's overlay): door frames, pillars, table fronts that hide
+//                                                     whoever walks behind them — transparent everywhere else
+//     "matte": "#1b1d24",                             optional (#2540): the colour around the scene where the Office
+//                                                     view's panel is not 16:9 (or is zoomed out), "#rrggbb"; without it
+//                                                     the page samples the background's edge pixels
 //     "areas": {                                      named zones: a rect [x, y, w, h] and its seats, in the order
 //       "desks":  { "rect": [40, 120, 620, 440], "seats": [[120, 220], [260, 220], …] },    they fill up
 //       "lounge": { "rect": [700, 120, 540, 260], "seats": [[760, 260], …] } },
@@ -23,11 +33,20 @@
 //     "furniture": [ { "id": "rack", "sprite": STRIP, "x": 1020, "y": 140, "depth": 2,
 //                      "activeWhen": "crashed", "activeSprite": STRIP } ],
 //                                                     drawn by depth: below 1000 under the people, 1000 and up over
-//                                                     them; (x, y) is where the strip's anchor goes. `activeWhen` (a
+//                                                     them; "depth": "y" (the string) sorts it among the people by base
+//                                                     y — its anchor's y against each person's feet: someone whose feet
+//                                                     are lower down (a greater y; a tie too) is drawn after it, in
+//                                                     front. (x, y) is where the strip's anchor goes. `activeWhen` (a
 //                                                     state, or a list): while anyone shown is in it, the item plays its
 //                                                     strip (or `activeSprite`); otherwise it holds the first frame
-//     "characters": { "default": { "working": STRIP, "idle": STRIP, "paused": STRIP, "needs": STRIP, "walk": STRIP },
-//                     "fox": { … } },                 "default" with at least "idle" is required; a missing pose is idle
+//     "characters": { "default": { "working": STRIP, "idle": STRIP, "paused": STRIP, "needs": STRIP, "walk": STRIP,
+//                                  "walkDown": STRIP, "walkUp": STRIP, "walkSide": STRIP },
+//                     "fox": { … } },                 "default" with at least "idle" is required; a missing pose is idle.
+//                                                     Walking (poseStrip): the current step's main axis picks the strip —
+//                                                     |dy| > |dx|: walkDown (dy > 0, toward the viewer) or walkUp; else
+//                                                     walkSide, drawn as it is when moving right and mirrored when moving
+//                                                     left (so draw it facing right). A missing one is "walk", then idle
+//                                                     ("walk" itself is never mirrored)
 //     "byInstance": { "atlas": "fox" },               optional: an instance name → its character set
 //     "props": { "task": STRIP, "send": STRIP, "report": STRIP, "broadcast": STRIP },   optional traffic items
 //     "bubbles": { "en": { "working": ["On it."] }, "zh-TW": { … } }   optional: short lines per state (≤ 12 a state,
@@ -44,20 +63,52 @@
 // "..". The check is strict: an unknown key, a value out of range or a name that refers to nothing refuses the pack,
 // with where it broke.
 //
-// TODO(office editor): the planned editor follows the reference's approach — a "show coordinates" overlay on the
-// canvas and dragging furniture and seats, the positions saved into the office (PUT /ui/offices) — out of v1.
+// Its displayed size: w·scale × h·scale logical units, unless the strip says `dw` and/or `dh` (logical units, 1–1280 and
+// 1–720): its frame is then drawn dw × dh (still unsmoothed: nearest neighbour), and with only one of them the other keeps
+// the frame's aspect. The anchor (ax, ay) stays in image pixels and moves with it. So art drawn at 120×120 px shows at
+// 96×96 with "dw": 96, "dh": 96 — whatever the pack's scale. What a person hovers or clicks is the box drawn (stripBox).
+//
+// A name the pack declares and refers to (an area, a character set, a furniture item, an instance in byInstance, and the
+// same in an office's overrides) is never one an object already has (Object.prototype's: "constructor", "toString",
+// "__proto__", …): such a name is refused, and every lookup is of the pack's own names only (own()).
+//
+// The host keeps an uploaded pack whole and never changes it: every PNG starts with its signature, a STRIP's image is
+// exactly frames·w × h, the background and the foreground are 16:9, and each file and the pack have a size cap (web-office-skins.ts).
+//
+// ── Layout overrides (the Office view's "Edit layout": a stored office's own positions on a zones pack) ──
+//
+// An office may keep `overrides` beside its skin — the pack stays as it was uploaded; the office moves things on it:
+//
+//   { "pack": "cozy",                                 the pack they were made on (on another pack they are ignored)
+//     "seats": { "desks": [[120, 220], …] },          an area's seats: as many as the pack's, each inside the area's rect
+//     "furniture": { "rack": [1000, 150] },           an item's (x, y)
+//     "door": [640, 700],
+//     "waypoints": [{ "id": "hall", "x": 640, "y": 600 }, …], "edges": [["hall", "east"], …] }
+//                                                     the walkable graph, replaced whole (edges need waypoints)
+//
+// Every coordinate is on the same 1280×720 logical canvas, in the same ranges as the pack's. checkLayoutOverrides is
+// the shape (the host checks it on every PUT /ui/offices); applyOverrides puts them on a checked pack, refusing a
+// seat outside its area, an area or furniture the pack does not have, or a seat count that differs (the host checks
+// that too, for a pack it keeps).
 
 export const LOGICAL = { w: 1280, h: 720 };
 /** The people's depth: furniture below it is drawn under them, the rest over them. */
 export const CHAR_DEPTH = 1000;
 export const PACK_STATES = ["needs", "crashed", "stuck", "working", "idle", "paused", "stopped", "missing"];
-const POSES = ["working", "idle", "paused", "needs", "walk"], PROPS = ["task", "send", "report", "broadcast"];
+const POSES = ["working", "idle", "paused", "needs", "walk", "walkDown", "walkUp", "walkSide"], PROPS = ["task", "send", "report", "broadcast"];
 const BUILT_IN = new Set(["pixel", "studio"]);
 const ID = /^[A-Za-z0-9_-]{1,40}$/;
 const SRC = /^[A-Za-z0-9._/-]{1,200}$/;
+const HEX = /^#[0-9a-f]{6}$/i;
 const LIMIT = { areas: 32, seats: 64, furniture: 128, waypoints: 512, edges: 2048, sets: 64, byInstance: 500, lines: 12, line: 40 };
 
 class Refused extends Error { constructor(at, why) { super(`${at}: ${why}`); } }
+/** `o[k]` when it is o's own property, else undefined: a name from a pack or a page never reaches Object.prototype. */
+export const own = (o, k) => (o !== null && typeof o === "object" && typeof k === "string" && Object.prototype.hasOwnProperty.call(o, k) ? o[k] : undefined);
+/** Whether `k` is a name every object already has ("constructor", "toString", "__proto__", …): never a pack's name. */
+export const inherited = (k) => typeof k === "string" && k in Object.prototype;
+/** A name a pack declares or refers to: ID's letters, never an inherited one. */
+const nameOk = (k) => typeof k === "string" && ID.test(k) && !inherited(k);
 const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
 function keys(v, allowed, at) { for (const k of Object.keys(v)) if (!allowed.includes(k)) throw new Refused(at, `unknown key "${k}"`); }
 function obj(v, at) { if (!isObj(v)) throw new Refused(at, "an object"); return v; }
@@ -68,20 +119,29 @@ function point(v, at) {
   if (!Array.isArray(v) || v.length !== 2) throw new Refused(at, "[x, y]");
   return { x: num(v[0], 0, LOGICAL.w, `${at}[0]`), y: num(v[1], 0, LOGICAL.h, `${at}[1]`) };
 }
+/** Where an item sorts: by depth, a "y" one among the people (after every number under them, before the rest). */
+const order = (f) => (f.depth === "y" ? CHAR_DEPTH - 0.5 : f.depth);
+/** A furniture item's numeric depth (its "y" is taken before this). */
+function depth(v, at) { if (!Number.isInteger(v) || v < -10000 || v > 10000) throw new Refused(at, 'a whole number from -10000 to 10000, or "y"'); return v; }
 function list(v, max, at) { if (!Array.isArray(v)) throw new Refused(at, "a list"); if (v.length > max) throw new Refused(at, `at most ${max}`); return v; }
 
-/** A frame strip, strictly. */
-export function checkStrip(v, at = "strip") {
+/** Whether `v` is a pack's `matte`: a colour as #rrggbb (six hex digits, either case). */
+export const matteOk = (v) => typeof v === "string" && HEX.test(v);
+
+/** A frame strip, strictly; `scale` the pack's (its displayed size, dw × dh, is resolved here). */
+export function checkStrip(v, at = "strip", scale = 2) {
   obj(v, at);
-  keys(v, ["src", "frames", "w", "h", "fps", "ax", "ay"], at);
+  keys(v, ["src", "frames", "w", "h", "fps", "ax", "ay", "dw", "dh"], at);
   const w = int(v.w, 1, 512, `${at}.w`), h = int(v.h, 1, 512, `${at}.h`);
+  const dw0 = v.dw === undefined ? null : num(v.dw, 1, LOGICAL.w, `${at}.dw`), dh0 = v.dh === undefined ? null : num(v.dh, 1, LOGICAL.h, `${at}.dh`);
+  const dw = dw0 ?? (dh0 !== null ? (dh0 * w) / h : w * scale), dh = dh0 ?? (dw0 !== null ? (dw0 * h) / w : h * scale);
   return { src: src(v.src, `${at}.src`), frames: int(v.frames, 1, 32, `${at}.frames`), w, h, fps: v.fps === undefined ? 4 : num(v.fps, 0, 30, `${at}.fps`),
-    ax: v.ax === undefined ? w / 2 : num(v.ax, 0, w, `${at}.ax`), ay: v.ay === undefined ? h : num(v.ay, 0, h, `${at}.ay`) };
+    ax: v.ax === undefined ? w / 2 : num(v.ax, 0, w, `${at}.ax`), ay: v.ay === undefined ? h : num(v.ay, 0, h, `${at}.ay`), dw, dh };
 }
-function strips(v, names, at) {
+function strips(v, names, at, scale) {
   obj(v, at);
   keys(v, names, at);
-  return Object.fromEntries(Object.entries(v).map(([k, s]) => [k, checkStrip(s, `${at}.${k}`)]));
+  return Object.fromEntries(Object.entries(v).map(([k, s]) => [k, checkStrip(s, `${at}.${k}`, scale)]));
 }
 function states(v, at) {
   const one = (s, here) => { if (!PACK_STATES.includes(s)) throw new Refused(here, `one of ${PACK_STATES.join(", ")}`); return s; };
@@ -92,17 +152,18 @@ function states(v, at) {
 export function checkSkinPack(x) {
   try {
     obj(x, "pack");
-    keys(x, ["format", "id", "scale", "background", "areas", "stateZones", "door", "waypoints", "edges", "furniture", "characters", "byInstance", "props", "bubbles", "room", "desk"], "pack");
+    keys(x, ["format", "id", "scale", "background", "foreground", "matte", "areas", "stateZones", "door", "waypoints", "edges", "furniture", "characters", "byInstance", "props", "bubbles", "room", "desk"], "pack");
     if (x.format !== 1) throw new Refused("format", "1");
     if (typeof x.id !== "string" || !ID.test(x.id)) throw new Refused("id", "1–40 letters, digits, _ or -");
     if (BUILT_IN.has(x.id)) throw new Refused("id", "a built-in skin's id");
     const scale = x.scale === undefined ? 2 : int(x.scale, 1, 8, "scale");
+    if (x.matte !== undefined && !matteOk(x.matte)) throw new Refused("matte", "a colour as #rrggbb");
     const areas = {};
     const rawAreas = x.areas === undefined ? {} : obj(x.areas, "areas");
     if (Object.keys(rawAreas).length > LIMIT.areas) throw new Refused("areas", `at most ${LIMIT.areas}`);
     for (const [name, a] of Object.entries(rawAreas)) {
       const at = `areas.${name}`;
-      if (!ID.test(name)) throw new Refused(at, "a name of letters, digits, _ or -");
+      if (!nameOk(name)) throw new Refused(at, "a name of letters, digits, _ or - (not an inherited one)");
       obj(a, at); keys(a, ["rect", "seats"], at);
       if (!Array.isArray(a.rect) || a.rect.length !== 4) throw new Refused(`${at}.rect`, "[x, y, w, h]");
       const [rx, ry] = [num(a.rect[0], 0, LOGICAL.w, `${at}.rect[0]`), num(a.rect[1], 0, LOGICAL.h, `${at}.rect[1]`)];
@@ -122,11 +183,12 @@ export function checkSkinPack(x) {
       stateZones = {};
       for (const [s, area] of Object.entries(x.stateZones)) {
         if (s !== "default" && !PACK_STATES.includes(s)) throw new Refused(`stateZones.${s}`, `a state (${PACK_STATES.join(", ")}) or "default"`);
-        if (typeof area !== "string" || !areas[area]) throw new Refused(`stateZones.${s}`, "an area the pack defines");
+        if (typeof area !== "string" || !own(areas, area)) throw new Refused(`stateZones.${s}`, "an area the pack defines");
         stateZones[s] = area;
       }
       if (x.background === undefined) throw new Refused("background", "required with stateZones");
     }
+    if (x.foreground !== undefined && !stateZones) throw new Refused("foreground", "only with stateZones");
     const waypoints = [], ids = new Set();
     for (const [i, w] of list(x.waypoints ?? [], LIMIT.waypoints, "waypoints").entries()) {
       const at = `waypoints[${i}]`;
@@ -143,26 +205,30 @@ export function checkSkinPack(x) {
     const furniture = list(x.furniture ?? [], LIMIT.furniture, "furniture").map((f, i) => {
       const at = `furniture[${i}]`;
       obj(f, at); keys(f, ["id", "sprite", "x", "y", "depth", "activeWhen", "activeSprite"], at);
-      if (typeof f.id !== "string" || !ID.test(f.id) || fids.has(f.id)) throw new Refused(`${at}.id`, "a new name of letters, digits, _ or -");
+      if (!nameOk(f.id) || fids.has(f.id)) throw new Refused(`${at}.id`, "a new name of letters, digits, _ or - (not an inherited one)");
       fids.add(f.id);
       if (f.activeSprite !== undefined && f.activeWhen === undefined) throw new Refused(`${at}.activeSprite`, "only with activeWhen");
-      return { id: f.id, sprite: checkStrip(f.sprite, `${at}.sprite`), x: num(f.x, 0, LOGICAL.w, `${at}.x`), y: num(f.y, 0, LOGICAL.h, `${at}.y`),
-        depth: int(f.depth ?? 0, -10000, 10000, `${at}.depth`), activeWhen: f.activeWhen === undefined ? null : states(f.activeWhen, `${at}.activeWhen`),
-        activeSprite: f.activeSprite === undefined ? null : checkStrip(f.activeSprite, `${at}.activeSprite`) };
-    }).sort((a, b) => a.depth - b.depth);
+      return { id: f.id, sprite: checkStrip(f.sprite, `${at}.sprite`, scale), x: num(f.x, 0, LOGICAL.w, `${at}.x`), y: num(f.y, 0, LOGICAL.h, `${at}.y`),
+        depth: f.depth === "y" ? "y" : depth(f.depth ?? 0, `${at}.depth`), activeWhen: f.activeWhen === undefined ? null : states(f.activeWhen, `${at}.activeWhen`),
+        activeSprite: f.activeSprite === undefined ? null : checkStrip(f.activeSprite, `${at}.activeSprite`, scale) };
+    }).sort((a, b) => order(a) - order(b));
     const sets = obj(x.characters, "characters");
     if (Object.keys(sets).length > LIMIT.sets) throw new Refused("characters", `at most ${LIMIT.sets} sets`);
     const characters = {};
     for (const [k, v] of Object.entries(sets)) {
-      if (!ID.test(k)) throw new Refused(`characters.${k}`, "a name of letters, digits, _ or -");
-      characters[k] = strips(v, POSES, `characters.${k}`);
+      if (!nameOk(k)) throw new Refused(`characters.${k}`, "a name of letters, digits, _ or - (not an inherited one)");
+      characters[k] = strips(v, POSES, `characters.${k}`, scale);
       if (!characters[k].idle) throw new Refused(`characters.${k}.idle`, "required");
     }
-    if (!characters.default) throw new Refused("characters.default", "required");
+    if (!own(characters, "default")) throw new Refused("characters.default", "required");
     const byInstance = {};
     const rawBy = x.byInstance === undefined ? {} : obj(x.byInstance, "byInstance");
     if (Object.keys(rawBy).length > LIMIT.byInstance) throw new Refused("byInstance", `at most ${LIMIT.byInstance}`);
-    for (const [k, v] of Object.entries(rawBy)) { if (typeof v !== "string" || !characters[v]) throw new Refused(`byInstance.${k}`, "a character set the pack defines"); byInstance[k] = v; }
+    for (const [k, v] of Object.entries(rawBy)) {
+      if (inherited(k)) throw new Refused(`byInstance.${k}`, "an instance's name (not an inherited one)");
+      if (typeof v !== "string" || !own(characters, v)) throw new Refused(`byInstance.${k}`, "a character set the pack defines");
+      byInstance[k] = v;
+    }
     const bubbles = {};
     for (const [lang, table] of Object.entries(x.bubbles === undefined ? {} : obj(x.bubbles, "bubbles"))) {
       if (lang !== "en" && lang !== "zh-TW") throw new Refused(`bubbles.${lang}`, '"en" or "zh-TW"');
@@ -181,9 +247,9 @@ export function checkSkinPack(x) {
     keys(room, ["floor", "wall"], "room"); keys(desk, ["back", "front", "lit"], "desk");
     const opt = (v, at) => (v === undefined ? undefined : src(v, at));
     return { ok: true, pack: {
-      format: 1, id: x.id, scale, background: opt(x.background, "background"), areas, stateZones,
+      format: 1, id: x.id, scale, background: opt(x.background, "background"), foreground: opt(x.foreground, "foreground"), matte: x.matte === undefined ? undefined : x.matte.toLowerCase(), areas, stateZones,
       door: x.door === undefined ? { x: LOGICAL.w / 2, y: LOGICAL.h - 10 } : point(x.door, "door"), waypoints, edges, furniture, characters, byInstance,
-      props: x.props === undefined ? {} : strips(x.props, PROPS, "props"), bubbles,
+      props: x.props === undefined ? {} : strips(x.props, PROPS, "props", scale), bubbles,
       room: { floor: opt(room.floor, "room.floor"), wall: opt(room.wall, "room.wall") }, desk: { back: opt(desk.back, "desk.back"), front: opt(desk.front, "desk.front"), lit: opt(desk.lit, "desk.lit") },
     } };
   } catch (err) {
@@ -194,6 +260,151 @@ export function checkSkinPack(x) {
 /** The checked pack, or null. */
 export const skinPackOk = (x) => { const r = checkSkinPack(x); return r.ok ? r.pack : null; };
 /** Every image a pack names (what a loader fetches before spriteSkin draws). */
-export const packImages = (pack) => [...new Set([pack.background, pack.room.floor, pack.room.wall, pack.desk.back, pack.desk.front, pack.desk.lit,
+export const packImages = (pack) => [...new Set([pack.background, pack.foreground, pack.room.floor, pack.room.wall, pack.desk.back, pack.desk.front, pack.desk.lit,
   ...pack.furniture.flatMap((f) => [f.sprite.src, f.activeSprite && f.activeSprite.src]),
   ...Object.values(pack.characters).flatMap((s) => Object.values(s).map((st) => st.src)), ...Object.values(pack.props).map((st) => st.src)].filter(Boolean))];
+
+/** Every frame strip a checked pack names, with where (the host checks each image is frames·w × h). */
+export function packStrips(pack) {
+  const out = [];
+  for (const f of pack.furniture) { out.push({ at: `furniture.${f.id}.sprite`, strip: f.sprite }); if (f.activeSprite) out.push({ at: `furniture.${f.id}.activeSprite`, strip: f.activeSprite }); }
+  for (const [k, set] of Object.entries(pack.characters)) for (const [pose, st] of Object.entries(set)) out.push({ at: `characters.${k}.${pose}`, strip: st });
+  for (const [k, st] of Object.entries(pack.props)) out.push({ at: `props.${k}`, strip: st });
+  return out;
+}
+
+// ── Layout overrides ──
+
+const OV_LIMIT = { areas: LIMIT.areas, seats: LIMIT.seats, furniture: LIMIT.furniture, waypoints: LIMIT.waypoints, edges: LIMIT.edges };
+/** An office's layout overrides, strictly (their shape and ranges): { ok: true, overrides } or { ok: false, error }. */
+export function checkLayoutOverrides(x) {
+  try {
+    obj(x, "overrides");
+    keys(x, ["pack", "seats", "furniture", "door", "waypoints", "edges"], "overrides");
+    if (typeof x.pack !== "string" || !ID.test(x.pack)) throw new Refused("overrides.pack", "1–40 letters, digits, _ or -");
+    const out = { pack: x.pack };
+    if (x.seats !== undefined) {
+      obj(x.seats, "overrides.seats");
+      if (Object.keys(x.seats).length > OV_LIMIT.areas) throw new Refused("overrides.seats", `at most ${OV_LIMIT.areas} areas`);
+      out.seats = {};
+      for (const [area, list0] of Object.entries(x.seats)) {
+        const at = `overrides.seats.${area}`;
+        if (!nameOk(area)) throw new Refused(at, "an area's name");
+        const pts = list(list0, OV_LIMIT.seats, at).map((p, i) => { const q = point(p, `${at}[${i}]`); return [q.x, q.y]; });
+        if (!pts.length) throw new Refused(at, "at least one seat");
+        out.seats[area] = pts;
+      }
+    }
+    if (x.furniture !== undefined) {
+      obj(x.furniture, "overrides.furniture");
+      if (Object.keys(x.furniture).length > OV_LIMIT.furniture) throw new Refused("overrides.furniture", `at most ${OV_LIMIT.furniture}`);
+      out.furniture = {};
+      for (const [id, p] of Object.entries(x.furniture)) {
+        if (!nameOk(id)) throw new Refused(`overrides.furniture.${id}`, "an item's id");
+        const q = point(p, `overrides.furniture.${id}`);
+        out.furniture[id] = [q.x, q.y];
+      }
+    }
+    if (x.door !== undefined) { const q = point(x.door, "overrides.door"); out.door = [q.x, q.y]; }
+    if (x.edges !== undefined && x.waypoints === undefined) throw new Refused("overrides.edges", "only with waypoints");
+    if (x.waypoints !== undefined) {
+      const ids = new Set();
+      out.waypoints = list(x.waypoints, OV_LIMIT.waypoints, "overrides.waypoints").map((w, i) => {
+        const at = `overrides.waypoints[${i}]`;
+        obj(w, at); keys(w, ["id", "x", "y"], at);
+        if (typeof w.id !== "string" || !ID.test(w.id) || ids.has(w.id)) throw new Refused(`${at}.id`, "a new name of letters, digits, _ or -");
+        ids.add(w.id);
+        return { id: w.id, x: num(w.x, 0, LOGICAL.w, `${at}.x`), y: num(w.y, 0, LOGICAL.h, `${at}.y`) };
+      });
+      const seen = new Set();
+      out.edges = list(x.edges ?? [], OV_LIMIT.edges, "overrides.edges").map((e, i) => {
+        if (!Array.isArray(e) || e.length !== 2 || !ids.has(e[0]) || !ids.has(e[1]) || e[0] === e[1]) throw new Refused(`overrides.edges[${i}]`, "two different waypoint ids");
+        const k = e[0] < e[1] ? `${e[0]}\u0000${e[1]}` : `${e[1]}\u0000${e[0]}`;
+        if (seen.has(k)) throw new Refused(`overrides.edges[${i}]`, "joined twice");
+        seen.add(k);
+        return [e[0], e[1]];
+      });
+    }
+    return { ok: true, overrides: out };
+  } catch (err) {
+    if (err instanceof Refused) return { ok: false, error: err.message };
+    throw err;
+  }
+}
+
+/**
+ * A checked pack with an office's checked overrides on it: { ok: true, pack } (a new object; the pack is untouched) or
+ * { ok: false, error }. Overrides made on another pack change nothing (ok, the pack as it is).
+ */
+export function applyOverrides(pack, ov) {
+  try {
+    if (!ov || ov.pack !== pack.id) return { ok: true, pack };
+    const areas = { ...pack.areas };
+    for (const [name, pts] of Object.entries(ov.seats || {})) {
+      const a = own(pack.areas, name), at = `overrides.seats.${name}`;
+      if (!a) throw new Refused(at, "an area the pack defines");
+      if (pts.length !== a.seats.length) throw new Refused(at, `${a.seats.length} seats, as the pack has`);
+      const r = a.rect;
+      areas[name] = { ...a, seats: pts.map(([x, y], i) => {
+        if (x < r.x || x > r.x + r.w || y < r.y || y > r.y + r.h) throw new Refused(`${at}[${i}]`, "outside its area's rect");
+        return { x, y };
+      }) };
+    }
+    const fids = new Set(pack.furniture.map((f) => f.id));
+    for (const id of Object.keys(ov.furniture || {})) if (!fids.has(id)) throw new Refused(`overrides.furniture.${id}`, "an item the pack has");
+    const furniture = pack.furniture.map((f) => { const q = own(ov.furniture, f.id); return q ? { ...f, x: q[0], y: q[1] } : f; });
+    const door = ov.door ? { x: ov.door[0], y: ov.door[1] } : pack.door;
+    const graph = ov.waypoints ? { waypoints: ov.waypoints.map((w) => ({ ...w })), edges: (ov.edges || []).map((e) => [e[0], e[1]]) } : { waypoints: pack.waypoints, edges: pack.edges };
+    return { ok: true, pack: { ...pack, areas, furniture, door, ...graph } };
+  } catch (err) {
+    if (err instanceof Refused) return { ok: false, error: err.message };
+    throw err;
+  }
+}
+
+/**
+ * What an edited layout keeps as overrides: only the parts that differ from the pack's own (`edited` is a pack with
+ * the same areas and furniture, positions moved); null when nothing does (the office goes back to the pack's).
+ */
+export function overridesBetween(pack, edited) {
+  const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+  const ov = { pack: pack.id };
+  for (const [name, a] of Object.entries(pack.areas)) {
+    const e = own(edited.areas, name);
+    if (e && !same(a.seats, e.seats)) (ov.seats ||= {})[name] = e.seats.map((s) => [s.x, s.y]);
+  }
+  const at = new Map(pack.furniture.map((f) => [f.id, f]));
+  for (const f of edited.furniture) { const o = at.get(f.id); if (o && (o.x !== f.x || o.y !== f.y)) (ov.furniture ||= {})[f.id] = [f.x, f.y]; }
+  if (pack.door.x !== edited.door.x || pack.door.y !== edited.door.y) ov.door = [edited.door.x, edited.door.y];
+  if (!same(pack.waypoints, edited.waypoints) || !same(pack.edges, edited.edges)) {
+    ov.waypoints = edited.waypoints.map((w) => ({ id: w.id, x: w.x, y: w.y }));
+    ov.edges = edited.edges.map((e) => [e[0], e[1]]);
+  }
+  return Object.keys(ov).length > 1 ? ov : null;
+}
+
+// ── Drawing a strip: which one a pose shows, and the box it covers ──
+
+/**
+ * The strip a character set shows for `pose` (heading: the current step { dx, dy }, while walking): { strip, mirror }, or
+ * null (no set). Walking: |dy| > |dx| → walkDown (dy > 0) or walkUp, else walkSide (mirror: moving left); a missing one
+ * → "walk" (never mirrored) → idle. Any other pose: its own strip, else idle.
+ */
+export function poseStrip(set, pose, heading = null) {
+  if (!set || typeof set !== "object") return null;
+  if (pose === "walk" && heading) {
+    const dx = Number(heading.dx) || 0, dy = Number(heading.dy) || 0;
+    if (dx || dy) {
+      const dir = Math.abs(dy) > Math.abs(dx) ? (dy > 0 ? "walkDown" : "walkUp") : "walkSide";
+      const st = own(set, dir);
+      if (st) return { strip: st, mirror: dir === "walkSide" && dx < 0 };
+    }
+  }
+  const st = own(set, pose) || own(set, "idle");
+  return st ? { strip: st, mirror: false } : null;
+}
+/** The box (logical units) a strip covers with its anchor at (x, y): its displayed size; mirrored about the anchor. */
+export function stripBox(st, x, y, mirror = false) {
+  const kx = st.dw / st.w, ky = st.dh / st.h;
+  return { x: Math.round(x - (mirror ? st.w - st.ax : st.ax) * kx), y: Math.round(y - st.ay * ky), w: st.dw, h: st.dh };
+}