feedback7: merge fb7-ui-backlog — #229 device tooltips, #238 settings button in lobby / room, #138 准备 folds the shop, #120 in-match spectator roster (cap stays 2), PR #308 capsule counts (+ the shared-field progress fix), PR #333 empty new shop slot on 调度中心 upgrade

- Conflicts: the stats entry (merged fb7-stats) and the settings button both sit in the lobby / room top bars — both kept; public/js/ui/settings.js (#321 diagnostics, voiceLang, SettingsButton); docs/PLAYING.md table rows resolved line by line against the merge base (#368, #354, #333 edits kept); docs/SIM.md / design/network.md snapshot field lists (resolved + ammo / wolves / neg / stand / standCut); design/client.md Screens line (#368's AI switch kept). - Grok review: MERGE AFTER FIXES — the shared-field capsule finding fixed on the branch (1a880699). - Golden: roster 23, bonds 2, fields 11, matches 18, diy 11 — #308 totals / snapshots and #333's shop RNG (union OK); broad node --test 5473 (5472 pass, 0 fail, 1 skipped); lint 0 errors; typecheck; i18n strict clean.
2026-10-08 20:56:20 +08:00
commit dc609ea13f
@@ -25,7 +25,7 @@ function ProgressList({ list }) {
      <b>${p.name}</b>
      ${p.done
        ? html`<span class="chud__prog__ok" aria-label=${t('作战结束')}>✓</span>`
-        : html`<span class="num">${p.killed != null && p.total != null ? `${p.killed}/${p.total}` : '•••'}</span>`}
+        : html`<span class="num">${(p.resolved ?? p.killed) != null && p.total != null ? `${p.resolved ?? p.killed}/${p.total}` : '•••'}</span>`}
    </span>`)}
  </div>`;
 }
@@ -711,9 +711,36 @@ function TerrainDetail({ terrain }) {
    ${Array.isArray(terrain.facts) && terrain.facts.length ? html`<${Section} title=${t('这一格')}><p class="dtext">${terrain.facts.join(' · ')}</p><//>` : null}`;
 }

+/**
+ * A stage device's tip (GitHub #228, PR #229: 阻隔工事 / “双眼皮” / 射击台 / 源石流发生装置 — the terrain tip's sibling). Opened
+ * by a tap on the device itself: the game screen resolves it with `gameLogic.deviceInfo` (prep) or `deviceTipAt` (a battle)
+ * from the stage the board on screen is built from, so the lines carry that stage's own numbers. In a battle the
+ * crate / turret is a device unit: its live HP (`live` from the battle's own sim, else `snapHp` — the screen reads the latest
+ * snapshot tuple through `unitId`) draws a HP bar like a unit card's.
+ * @param {{ name:string, tag:string, lines:string[], facts?:string[], stats?:{k:string,v:any}[] }} device
+ * @param {{ hp:number, max:number }|null} snapHp
+ */
+function DeviceDetail({ device, snapHp = null, live = null }) {
+  const hp = hpOf(live, snapHp);
+  return html`
+    <div class="dhead">
+      <div class="dhead__icon"><${Icon} name="info" /></div>
+      <div class="dhead__info">
+        <div class="dhead__chips"><span class="dtag-kind">${device.tag}</span></div>
+        <h3 class="dhead__name">${device.name}</h3>
+        ${hp ? html`<div class="dhp"><i style=${`width:${Math.max(0, Math.min(100, (hp.hp / Math.max(1, hp.max)) * 100))}%`}></i><span class="num">${fmtNum(hp.hp)} / ${fmtNum(hp.max)}</span></div>` : null}
+      </div>
+    </div>
+    <${Section} title=${t('装置机制')} micro="DEVICE">
+      ${device.lines.map((line, i) => html`<p class="dtext" key=${i}>${line}</p>`)}
+    <//>
+    ${Array.isArray(device.stats) && device.stats.length ? html`<div class="dstats">${device.stats.map((x) => html`<${Stat} key=${x.k} k=${x.k} v=${x.v} />`)}</div>` : null}
+    ${Array.isArray(device.facts) && device.facts.length ? html`<${Section} title=${t('这一格')}><p class="dtext">${device.facts.join(' · ')}</p><//>` : null}`;
+}
+
 /**
 * Resolve what a detail target shows.
- * @param {{ kind:'piece'|'chess'|'item'|'enemy'|'unit'|'token'|'terrain', id?:string, uid?:number, unit?:any, count?:number }} target
+ * @param {{ kind:'piece'|'chess'|'item'|'enemy'|'unit'|'token'|'terrain'|'device', id?:string, uid?:number, unit?:any, count?:number }} target
 * @param {Map<number, any>} pieces indexPieces(priv)
 * @param {{ priv?: any, backups?: any }} [opts] 0.2.0 补位: the player's own pieces and cards of a chess in
 *   m.private.standIns — a unit carrying `standInFor`, and a teammate's bond popup row that says it (`target.standInFor`)
@@ -726,6 +753,12 @@ export function resolveDetail(target, pieces, { priv = null, backups = data.get(
  if (!target) return null;
  // a special terrain tile (issue #184): the screen resolved the stage's own numbers already (gameLogic.terrainInfo)
  if (target.kind === 'terrain') return target.terrain && typeof target.terrain === 'object' ? { type: 'terrain', terrain: target.terrain } : null;
+  // a stage device (#228): the screen resolved the device's stage entry (gameLogic.deviceInfo / deviceTipAt); in a battle
+  // `unitId` is the crate / turret unit whose snapshot tuple gives the live HP
+  if (target.kind === 'device') {
+    const device = target.device && typeof target.device === 'object' ? target.device : null;
+    return device ? { type: 'device', device, ...(Number.isInteger(device.unitId) ? { unitId: device.unitId } : {}) } : null;
+  }
  const ownSi = (c) => ownStandIn(c, priv, backups);
  const dd = { chess: data.get('chess'), backups };
  /** the own card of chess `c`: its 自选 record and pick when the player filled that DIY slot */
@@ -855,6 +888,7 @@ export function DetailPanel({ detail, editable, snapHp, onClose, onSell, onDestr
      ${detail.type === 'enemy' ? html`<${EnemyDetail} enemy=${detail.enemy} snapHp=${snapHp} count=${detail.count} live=${liveNow} />` : null}
      ${detail.type === 'token' ? html`<${TokenDetail} token=${detail.token} piece=${detail.piece} ownerId=${detail.ownerId ?? null} snapHp=${snapHp} live=${liveNow} />` : null}
      ${detail.type === 'terrain' ? html`<${TerrainDetail} terrain=${detail.terrain} />` : null}
+      ${detail.type === 'device' ? html`<${DeviceDetail} device=${detail.device} snapHp=${snapHp} live=${liveNow} />` : null}
    </div>
  </aside>`;
 }
@@ -72,4 +72,7 @@ export const actions = {
  autoplay: (on) => act('g.autoplay', { on }),
  // solo battles only (ui/matchStatus.js pauseAvailable): m.public.paused follows
  pause: (on) => act('g.pause', { on: !!on }, { sfx: on ? 'click' : 'confirm' }),
+  // room-level intent (NOT g.*): the host frees a spectator seat while the match runs — the server takes room.removeSpectator at
+  // any time (server/lobby.js removeSpectator), the game screen had no entry for it (ui/hud.js SpectatorPill; GitHub #120)
+  removeSpectator: (playerId) => act('room.removeSpectator', { playerId }, { sfx: 'back' }),
 };
@@ -33,9 +33,9 @@ export { STATUS_META } from './gameLogic/format.js';
 export { sortedPlayers } from './gameLogic/shared.js';
 export { ownFieldId, homeFieldId, cycleField, watchTarget, switcherLabel, fieldLabel, activeBubbles } from './gameLogic/watch.js';
 export { sortBonds, bondTier, nextThreshold, grantedBonds, pieceBondIds, morphPairings, HARMONY_BOND, harmonyMembers, bondMembers, memberHeadCount, bannedPerBond, disabledBondSets, briefingBondTip, modeOffBonds, bandOffBonds, bandOffLine } from './gameLogic/bonds.js';
-export { priceTone, mergeProgress, mergeTarget, handFull, completesMerge, offerHeader, shopBlockReason, readyFundsPrompt } from './gameLogic/shop.js';
+export { priceTone, mergeProgress, mergeTarget, handFull, completesMerge, offerHeader, shopBlockReason, readyFundsPrompt, readyShopFold } from './gameLogic/shop.js';
 export { deploySets, stageOverrides, deployMap, effectiveStage, indexPieces, placementContext, piecePosition, tileAllows, summonRange, summonExcluded, canPlace, equipReplaces, equipMerges, boardTargets, dropIntent, dropFailureReason } from './gameLogic/placement.js';
-export { terrainInfo } from './gameLogic/terrain.js';
+export { terrainInfo, deviceInfo, deviceTipAt, noteDeviceUnits } from './gameLogic/terrain.js';
 export { normalizeDraft, normalizeSp } from './gameLogic/draft.js';
 export { groupEnemies, PEN, penZoneTiles, penPlacement, previewEnemyKey, factionTypes } from './gameLogic/enemies.js';
 export { snapHud, bossFrac, bossPctText, hasFlag, UF, attackInterval, fmtNum, rangeGridBox } from './gameLogic/format.js';
@@ -22,7 +22,9 @@ export const STATUS_META = Object.freeze({
 // ---- snapshots / battle HUD ---------------------------------------------------------------------------------

 /**
- * HUD numbers from a b.snap: { killed, total, dp, boss } (boss: { hp, max } when present).
+ * HUD numbers from a b.snap: { killed, resolved, total, dp, boss } (boss: { hp, max } when present).
+ * `resolved` is the capsule's numerator — knocked out + leaked among the round's own enemies (Battle.leakedInTotal);
+ * an older snapshot without it falls back to the kill count.
 * @param {any} snap
 */
 export function snapHud(snap) {
@@ -30,7 +32,8 @@ export function snapHud(snap) {
  const n = (v) => (Number.isFinite(v) ? v : null);
  let boss = null;
  if (isObj(snap.boss) && Number.isFinite(snap.boss.hp)) boss = { hp: snap.boss.hp, max: n(snap.boss.max) ?? n(snap.boss.maxHp) };
-  return { killed: n(snap.killed), total: n(snap.total), dp: n(snap.dp), boss };
+  const killed = n(snap.killed);
+  return { killed, resolved: n(snap.resolved) ?? killed, total: n(snap.total), dp: n(snap.dp), boss };
 }

 /** Boss HP fraction 0..1 (null when unknown). */
@@ -1,4 +1,5 @@
-// ui/gameLogic/shop.js — shop prices, merges, offers, the ready-funds prompt. Re-exported from ../gameLogic.js.
+// ui/gameLogic/shop.js — shop prices, merges, offers, the ready-funds prompt, the shop bar's fold on 准备. Re-exported from
+// ../gameLogic.js.

 import { GEO } from '../../../../shared/constants.js';
 import { isObj } from './shared.js';
@@ -183,3 +184,18 @@ export function readyFundsPrompt(priv, { ready = true, keptBands = null, autopla
    text: t('还有 {funds} 资金未使用。休整期结束时，本回合的剩余资金将清零。确定准备就绪吗？', { funds }),
  };
 }
+
+/**
+ * The shop bar follows the player's ready state (GitHub #138, the owner's decision of 2026-10-07): pressing 准备就绪 folds
+ * the bar — the board is set, the fight is what to look at —, cancelling it unfolds the bar again. Read from the own CONFIRMED
+ * state (m.private.ready — a refused 准备 folds nothing) and only a change inside one prep counts: the first state seen (a
+ * reconnect in the middle of a prep, the prep's start), the new round's reset to not ready and anything outside a prep are
+ * not a press. The player can still fold / unfold by hand in between.
+ * @param {{ round: any, ready: boolean }|null|undefined} prev the own prep state seen last (null: none — outside a prep)
+ * @param {{ round: any, ready: boolean }|null|undefined} cur the own prep state now (null outside a prep)
+ * @returns {'fold'|'unfold'|null}
+ */
+export function readyShopFold(prev, cur) {
+  if (!isObj(prev) || !isObj(cur) || prev.round !== cur.round || !!prev.ready === !!cur.ready) return null;
+  return cur.ready ? 'fold' : 'unfold';
+}
@@ -169,9 +169,10 @@ export const facingSwallows = (e, keys = DEFAULT_HOTKEYS) => e?.key === ' ' || a
 * right-click or long press — or a battle / teammate unit). Shop, reward, bond-member and intel (enemy) cards stay.
 * @param {{ kind?: string }|null|undefined} detail
 */
-// a card opened BY a field press (a piece, a unit, a special terrain tile: issue #184) closes on the next press of
-// the field; the ones opened from the shop / hand / HUD stay until their own close button (or the flow that opened them)
-export const closesOnFieldPress = (detail) => detail?.kind === 'piece' || detail?.kind === 'unit' || detail?.kind === 'terrain';
+// a card opened BY a field press (a piece, a unit, a special terrain tile: issue #184, a stage device: #228) closes on the
+// next press of the field; the ones opened from the shop / hand / HUD stay until their own close button (or the flow that
+// opened them)
+export const closesOnFieldPress = (detail) => detail?.kind === 'piece' || detail?.kind === 'unit' || detail?.kind === 'terrain' || detail?.kind === 'device';

 /**
 * Whether an open overlay swallows a game shortcut: a modal / the guide own the keyboard (Esc included — they close
@@ -1,9 +1,11 @@
-// ui/gameLogic/terrain.js — special terrain tips (GitHub issue #184: 特殊地形的单击信息提示). Re-exported from
-// ../gameLogic.js.
+// ui/gameLogic/terrain.js — the tips of a tap on the ground: special terrain tiles (GitHub issue #184: 特殊地形的单击信息
+// 提示) and, in the same place, stage devices (阻隔工事 / “双眼皮” / 射击台 / 气流: GitHub #228, PR #229 by @rickylxw —
+// deviceInfo / deviceTipAt below). Re-exported from ../gameLogic.js.
 //
 // The words go through t() (docs/I18N.md: the Chinese text is the msgid, public/i18n/en.json the English): the name /
 // tag / fact tables are marked N_() and translated where terrainInfo hands them out, the mechanism lines are built
-// with their numbers as params.
+// with their numbers as params. A device's NAME is a data text (data/stages.json `devices[].name`, localized by the
+// data overlay: "Barricade", "'Double Lids'" …), not a msgid.

 import { isObj } from './shared.js';
 import { t, N_ } from '../../../../shared/i18n.js';
@@ -123,3 +125,174 @@ export function terrainInfo(stage, row, col) {
  else if (tile.groundPassable === true) facts.push(t('地面单位可通过'));
  return { key, name: t(tip.name), tag: t(tip.tag), row, col, lines: tip.lines(stage.special).filter((s) => typeof s === 'string' && s), facts };
 }
+
+// ---- stage device tips (GitHub #228, PR #229 by @rickylxw: the stage DEVICES, not only the tiles) ---------------------
+
+/** The device roles a tap explains; the rest is invisible (盟约寒风, the 沼泽 / 涨潮 controllers) or not fielded this season. */
+const DEVICE_TIP_ROLES = Object.freeze(['crate', 'turret', 'platform', 'blower']);
+/** Roles the battle spawns as device UNITS (Battle._spawnStageDevices, devices.js spawnTurret): in a battle a tap finds them by unit. */
+const DEVICE_UNIT_ROLES = Object.freeze(['crate', 'turret']);
+const TIP_TAG = N_('场地装置');
+const DIR_NAME = Object.freeze({ UP: N_('上'), DOWN: N_('下'), LEFT: N_('左'), RIGHT: N_('右') });
+
+const round1 = (v) => Math.round(v * 10) / 10;
+
+/**
+ * What tapping a stage device says — the same contract as TERRAIN_TIPS, but `lines` read the device's own stage entry
+ * (data/stages.json `stage.devices[]`: stats / skill blackboard / dir / rangeTiles), the very numbers the sim runs
+ * (`sim/content/devices.js`, `Battle._spawnStageDevices`), so a tip can never disagree with the battle. The prose is ours
+ * (docs/PLAYING.md wording; PRTS 阻隔工事 / “双眼皮” / 射击台 / 源石流发生装置 and the sim's behaviour). `stats` is the
+ * stat grid under the lines (the turret's), `facts` what the tile allows.
+ */
+const DEVICE_TIPS = Object.freeze({
+  crate: {
+    lines: (st, d) => [
+      t('挡在地面上的工事：地面敌人会绕开它走；只有无路可走时才会撞上来，把它摧毁后继续前进'),
+      t('生命 {hp} 点，被摧毁后从场上消失', { hp: param(d.stats?.maxHp, 100) }),
+    ],
+    facts: () => [t(BUILDABILITY.NONE)],            // board.js buildDeployMap: an active crate takes its tile off the deploy map
+  },
+  turret: {
+    lines: (st, d) => {
+      const bb = isObj(d.skill?.bb) ? d.skill.bb : {};
+      // devices.js spawnTurret: the same blackboard keys and the same `持续N秒` read from the skill text
+      const dur = /持续(\d+(?:\.\d+)?)秒/.exec(String(d.skill?.desc ?? ''));
+      const aspdMax = param(bb.max_attack_speed, Infinity);
+      const fragMax = param(bb.max_damage_scale, Infinity);
+      return [
+        t('自动攻击射程内的一名敌人，造成法术伤害，命中的敌人附加脆弱'),
+        t('按当前层数最高的盟约计算：每 1 层，攻击速度 +{aspd}（至多 +{aspdMax}），附加的脆弱 +{frag}%（至多 +{fragMax}%）', {
+          aspd: param(bb.attack_speed_per_stack, 1),
+          aspdMax: Number.isFinite(aspdMax) ? aspdMax : '∞',
+          frag: round1(param(bb.damage_scale_per_stack, 0.001) * 100),
+          fragMax: Number.isFinite(fragMax) ? round1((fragMax - 1) * 100) : '∞',
+        }),
+        dur ? t('脆弱持续 {sec} 秒', { sec: Number(dur[1]) }) : null,
+      ];
+    },
+    stats: (st, d) => {
+      const s = isObj(d.stats) ? d.stats : {};
+      const out = [{ k: t('生命上限'), v: param(s.maxHp, 100) }];
+      if (param(s.atk, 0)) out.push({ k: t('攻击'), v: param(s.atk, 0) });
+      if (param(s.def, 0)) out.push({ k: t('防御'), v: param(s.def, 0) });
+      const sec = param(s.bat, 0) > 0 ? param(s.bat, 0) * 100 / (param(s.aspd, 100) > 0 ? param(s.aspd, 100) : 100) : 0;
+      if (sec) out.push({ k: t('攻击间隔'), v: `${round1(sec)}s` });
+      return out;
+    },
+    facts: () => [t(BUILDABILITY.NONE)],
+  },
+  platform: {
+    lines: () => [
+      t('高台位装置：地面敌人不能走上这一格'),
+      t('远程位干员可以部署在其上；站上去的干员在高位，不阻挡敌人'),
+    ],
+    facts: () => [t(BUILDABILITY.RANGED)],          // board.js: an active platform makes its tile a 'ranged' deploy tile
+  },
+  blower: {
+    lines: (st, d) => {
+      // devices.js buildTerrain: the device's own skill blackboard, else stage.special.blower.bb; rangeTiles = its own tile + the lane
+      const bb = isObj(d.skill?.bb) ? d.skill.bb : (isObj(st?.blower?.bb) ? st.blower.bb : {});
+      const dir = DIR_NAME[String(d.dir || 'UP').toUpperCase()] || DIR_NAME.UP;
+      const lane = Array.isArray(d.rangeTiles) && d.rangeTiles.length > 1 ? d.rangeTiles.length - 1 : 3;
+      const out = [t('向前方 {n} 格吹出气流（这一台朝{dir}）', { n: lane, dir: t(dir) })];
+      const eq = param(bb['blower_s_character[equal].atk'], 0);
+      const op = param(bb['blower_s_character[opposite].atk'], 0);
+      const mods = [];
+      if (eq) mods.push(t('朝向与风向相同的攻击力 {v}', { v: pctText(eq) }));
+      if (op) mods.push(t('相反的 {v}', { v: pctText(op) }));
+      if (mods.length) out.push(t('部署在气流里的干员：{mods}', { mods }));
+      const eqM = param(bb['blower_s_enemy[equal].move_speed'], 0);
+      const opM = param(bb['blower_s_enemy[opposite].move_speed'], 0);
+      const em = [];
+      if (eqM) em.push(t('顺风移动速度 ×{v}', { v: round2(1 + eqM) }));
+      if (opM) em.push(t('逆风 ×{v}', { v: round2(1 + opM) }));
+      if (em.length) out.push(t('在气流里移动的敌人：{mods}', { mods: em }));
+      return out;
+    },
+    facts: () => [t(BUILDABILITY.NONE)],
+  },
+});
+const round2 = (v) => Math.round(v * 100) / 100;
+
+/** A stage device entry is drawn: `active` when it carries it, else not `hidden` (render/tiles.js _stageDevices, board3d/layout.js stageDevices). */
+const deviceDrawn = (d) => (typeof d.active === 'boolean' ? d.active : !d.hidden);
+
+/** The card of stage device `d` standing at (row, col) — `tip` is DEVICE_TIPS[d.role]. */
+function deviceCard(stage, d, row, col) {
+  const tip = DEVICE_TIPS[d.role];
+  const lines = tip.lines(stage.special, d).filter((s) => typeof s === 'string' && s);
+  const stats = typeof tip.stats === 'function' ? tip.stats(stage.special, d) : null;
+  const name = typeof d.name === 'string' && d.name ? d.name : String(d.role);
+  return {
+    key: d.role, name, tag: t(TIP_TAG), row, col, lines, facts: tip.facts(stage.special, d).filter(Boolean),
+    ...(stats && stats.length ? { stats } : {}),
+  };
+}
+
+/**
+ * The tip a tap on the tile (row, col) opens when a stage DEVICE stands on it (GitHub #228, PR #229), or null: an ordinary
+ * tile — or a device this client does not draw (`active` false: a turret that stays dormant until 机械援助 / a 机变 card
+ * switches it on, a crate such a card removed) — falls through to `terrainInfo`. Visibility mirrors what the renderers draw
+ * (`render/tiles.js _stageDevices`, `board3d/layout.js stageDevices`): `active` when set, else not `hidden`. The stage is
+ * the shown field's (already the player's own `effectiveStage`, so a card-removed crate is not in the way). The device's
+ * name is its data text (localized by the data overlay); the lines are in the current language (t()).
+ * @param {{ devices?: any[], special?: any, rows?: string[], tiles?: Record<string, any> } | null | undefined} stage
+ * @param {number} row board row (row 0 = the bottom row, DESIGN §1)
+ * @param {number} col
+ * @param {{ roles?: readonly string[] }} [opts] `roles`: only these roles answer (default: the four of DEVICE_TIP_ROLES)
+ * @returns {{ key:string, name:string, tag:string, row:number, col:number, lines:string[], facts:string[], stats?:{k:string,v:string|number}[] } | null}
+ */
+export function deviceInfo(stage, row, col, { roles = DEVICE_TIP_ROLES } = {}) {
+  const list = Array.isArray(stage?.devices) ? stage.devices : null;
+  if (!list || !Number.isInteger(row) || !Number.isInteger(col)) return null;
+  for (const d of list) {
+    if (!isObj(d) || !Array.isArray(d.pos) || d.pos[0] !== row || d.pos[1] !== col) continue;
+    if (!roles.includes(d.role) || !DEVICE_TIPS[d.role] || !deviceDrawn(d)) continue;
+    return deviceCard(stage, d, row, col);
+  }
+  return null;
+}
+
+/**
+ * The tip of a tap on (row, col) while a BATTLE shows the field — the live counterpart of `deviceInfo`: crates and “双眼皮”
+ * turrets are device UNITS there (kind 'device', one per drawn stage device, `defId` = the device key), so they are
+ * found by the unit standing on the tile — a turret outside the battle's rect stands on another tile than its stage `pos`
+ * (devices.js deviceTile) — and what the card says comes from the stage entry of that key. The platforms and blowers are no
+ * units: they answer by their stage `pos`, as in the prep.
+ * A destroyed device (HP gone, or no longer in the snapshots once its DIE animation is over) is not there any more: the
+ * tap belongs to the tile under the wreck (null here, so it falls through to `terrainInfo`). Before the first snapshot of the
+ * battle has arrived (`snap` empty) a unit counts as standing.
+ * The result is the same card as `deviceInfo`'s, with `unitId` (the unit, for its live HP: the screen reads `b.snap`
+ * through it, like a unit card's `snapHp`).
+ * @param {object|null|undefined} stage the shown field's stage
+ * @param {number} row @param {number} col
+ * @param {{ units?: any[]|null, snap?: Map<number, any[]>|null }} battle the field's unit infos (m.field.units) and the
+ *   latest snapshot tuples by unit id ([id, x, y, hp, maxHp, …])
+ */
+export function deviceTipAt(stage, row, col, { units = null, snap = null } = {}) {
+  if (!Number.isInteger(row) || !Number.isInteger(col)) return null;
+  const u = (Array.isArray(units) ? units : []).find((x) => isObj(x) && x.kind === 'device' && Math.round(Number(x.x)) === col && Math.round(Number(x.y)) === row);
+  if (!u) return deviceInfo(stage, row, col, { roles: DEVICE_TIP_ROLES.filter((r) => !DEVICE_UNIT_ROLES.includes(r)) });
+  if (snap && snap.size > 0) {
+    const tuple = snap.get(u.id);
+    if (!Array.isArray(tuple) || !(tuple[3] > 0)) return null;
+  }
+  const list = Array.isArray(stage?.devices) ? stage.devices : [];
+  const same = list.filter((d) => isObj(d) && d.key === u.defId && DEVICE_UNIT_ROLES.includes(d.role));
+  const d = same.find((x) => Array.isArray(x.pos) && x.pos[0] === row && x.pos[1] === col) || same[0];
+  return d ? { ...deviceCard(stage, d, row, col), unitId: u.id } : null;
+}
+
+/**
+ * Fold the device units a battle shows into `map` (UnitInfo by unit id): the field meta's `units` (what stands when the field
+ * is entered) and the 'spawn' event tuples `['spawn', UnitInfo]` after it — the stage crates and the “双眼皮” turrets come
+ * into being with the battle's first step (`battleStart`), after the meta of a battle shown from its beginning was taken.
+ * Only kind 'device' is kept; `deviceTipAt` reads the map's values.
+ * @param {Map<number, any>} map
+ * @param {{ units?: any[]|null, events?: any[]|null }} [from]
+ */
+export function noteDeviceUnits(map, { units = null, events = null } = {}) {
+  for (const u of Array.isArray(units) ? units : []) if (isObj(u) && u.kind === 'device' && u.id != null) map.set(u.id, u);
+  for (const e of Array.isArray(events) ? events : []) if (Array.isArray(e) && e[0] === 'spawn' && isObj(e[1]) && e[1].kind === 'device' && e[1].id != null) map.set(e[1].id, e[1]);
+  return map;
+}
@@ -23,9 +23,9 @@
 // 准备就绪 is refused while the temp overflow row (临时整备区) holds pieces: the reason shows under the button
 // (user playtest #3 item 3; the row's own label is ui/underframe.js TempRowNotice).

-import { useRef } from '../../vendor/hooks.module.js';
+import { useEffect, useRef, useState } from '../../vendor/hooks.module.js';
 import { PHASE } from '../../../shared/constants.js';
-import { html, Button, Icon, PingPill, Countdown, Tooltip, MicroLabel, DifficultyTag, useTicker } from './components.js';
+import { html, Button, Icon, PingPill, Countdown, Tooltip, MicroLabel, DifficultyTag, Modal, useTicker } from './components.js';
 import { Sprite, LpTower, GIcon, LocalSprite } from './gameComponents.js';
 import { localAsset } from '../data.js';
 import { serverNow } from '../store.js';
@@ -36,6 +36,45 @@ import { t, tParts, N_ } from '../../../shared/i18n.js';

 const cx = (...p) => p.flat().filter(Boolean).join(' ');

+/**
+ * 观战席 capsule of the in-match top bar (GitHub #120, PR #120 by @salt-fishes; the spectator seats of community report #26):
+ * the room's spectators, which the room screen lists in a strip but the game screen — the route after 开始 — used to hide
+ * completely, so a spectator could only be removed before the match or after it. A small eye + the count beside the latency;
+ * a tap opens the roster, with the host's ✕ on every row (room.removeSpectator: the server takes it at any time; the removed
+ * seat gets room.closed {kicked} and no more frames). Renders nothing while no spectator seat is taken.
+ * @param {{ spectators: any[]|null, myId: any, isHost: boolean, onRemove: ((playerId: any) => any)|null }} props
+ */
+export function SpectatorPill({ spectators, myId, isHost, onRemove }) {
+  const [open, setOpen] = useState(false);
+  const [busy, setBusy] = useState(null);
+  const list = Array.isArray(spectators) ? spectators.filter((s) => s && typeof s === 'object') : [];
+  // the roster closes with its last seat (the pill is gone: it must not pop up again for the next spectator)
+  useEffect(() => { if (!list.length) setOpen(false); }, [list.length]);
+  if (!list.length) return null;
+  const remove = async (playerId) => {
+    if (!onRemove) return;
+    setBusy(playerId);
+    try { await onRemove(playerId); } finally { setBusy(null); }
+  };
+  return html`<${Button} variant="ghost" size="sm" icon="eye" class=${cx('specpill', list.some((s) => s.playerId === myId) && 'is-me')}
+      onClick=${() => setOpen(true)} data-testid="spectators" title=${t('观战席')} aria-label=${t('观战席')}>
+      <span class="specpill__num num">${list.length}</span>
+    <//>
+    ${open ? html`<${Modal} open=${true} title=${t('观战席')} micro="SPECTATORS" width="6.4rem" onClose=${() => setOpen(false)}
+        actions=${html`<${Button} variant="secondary" onClick=${() => setOpen(false)}>${t('关闭')}<//>`}>
+      <ul class="spec__roster" data-testid="spectator-roster">
+        ${list.map((s) => html`<li key=${s.playerId} class=${cx('spec__row', s.playerId === myId && 'is-me', s.connected === false && 'is-offline')}>
+          <${Icon} name=${s.connected === false ? 'wifiOff' : 'eye'} class="spec__ico" />
+          <span class="spec__name">${s.name || t('博士')}</span>
+          ${s.playerId === myId ? html`<span class="seat__you">${t('你')}</span>` : null}
+          ${isHost && onRemove ? html`<${Button} variant="ghost" size="sm" square=${true} icon="close" loading=${busy === s.playerId} data-testid="spectator-remove"
+            onClick=${() => remove(s.playerId)} aria-label=${t('移出观战者 {name}', { name: s.name || '' })} title=${t('移出该观战者')} />` : null}
+        </li>`)}
+      </ul>
+      <p class="spec__hint t-lo">${t('观战者不占博士席位，只能观看；创建者可以把观战者移出，被移出的人不再收到战场画面。')}</p>
+    <//>` : null}`;
+}
+
 /**
 * Phase capsule: prep label, kills n/m (combat/unite), kills + boss HP bar (boss rounds).
 * @param {{ pub:any, hud:any }} props
@@ -49,7 +88,7 @@ export function PhaseCapsule({ pub, hud, miss = null }) {
    const frac = bossFrac(boss);
    return html`<div class="capsule capsule--boss" role="status">
      <${Sprite} k="hudPanel/icon_boss" class="capsule__icon" fallback=${html`<${GIcon} name="skull" class="capsule__icon" />`} />
-      ${hud?.total != null ? html`<span class="capsule__kills num"><b>${hud.killed ?? 0}</b>/${hud.total}</span>` : null}
+      ${hud?.total != null ? html`<span class="capsule__kills num"><b>${hud.resolved ?? hud.killed ?? 0}</b>/${hud.total}</span>` : null}
      <div class="bossbar" title=${boss ? `${fmtNum(boss.hp)} / ${fmtNum(boss.max)}` : t('敌方领袖')}>
        <div class="bossbar__fill" style=${`width:${frac == null ? 100 : frac * 100}%`}></div>
        <span class="bossbar__txt num">${frac == null ? t('敌方领袖') : bossPctText(frac)}</span>
@@ -60,7 +99,7 @@ export function PhaseCapsule({ pub, hud, miss = null }) {
    return html`<div class=${cx('capsule', 'capsule--combat', phase === PHASE.UNITE && 'capsule--unite')} role="status">
      <${Sprite} k=${phase === PHASE.UNITE ? 'hudPanel/icon_coop' : 'hudPanel/icon_battle'} class="capsule__icon"
        fallback=${html`<${Icon} name="sword" class="capsule__icon" />`} />
-      <span class="capsule__kills num"><b>${hud?.killed ?? 0}</b>/${hud?.total ?? '--'}</span>
+      <span class="capsule__kills num"><b>${hud?.resolved ?? hud?.killed ?? 0}</b>/${hud?.total ?? '--'}</span>
      ${phase === PHASE.UNITE ? html`<span class="capsule__tag">${t('联防')}</span>` : null}
      ${phase === PHASE.UNITE && Number.isFinite(miss) ? html`<${MissTag} n=${miss} />` : null}
    </div>`;
@@ -306,13 +345,16 @@ export function PauseButton({ paused, busy = false, onToggle }) {
 *   onReady:(r:boolean)=>void, readyBusy?:boolean, readyCount?:number, playerCount?:number,
 *   pen?:boolean, penAvail?:boolean, onPen?:(on:boolean)=>void, config?: any, frozenAt?: number|null,
 *   pause?: { show: boolean, paused: boolean, busy?: boolean, onToggle: () => void } | null,
- *   live?: { pending: number, unite: boolean, left?: number|null } | null }} props
+ *   live?: { pending: number, unite: boolean, left?: number|null } | null,
+ *   spectators?: any[]|null, myId?: any, isHost?: boolean, onRemoveSpectator?: ((playerId: any) => any)|null }} props
+ *   spectators: the room's spectator seats (room.state) — the 观战席 capsule beside the latency (SpectatorPill; the host removes)
 *   frozenAt: the server time every clock shows while the solo match is paused (null = live)
 *   live: the own battle's pending LP loss (liveLp): the tower shows lp − pending in red with a −N tick, 联防中 during 联防;
 *     `left` (a leaker in 联防): its enemies still standing — the capsule's ×N tag
 */
 export function TopBar({ pub, priv, conn, hud, total, drawer, onExit, onDrawer, onReady, readyBusy, readyCount, playerCount, pen = false, penAvail = false, onPen = () => {},
-  config = null, frozenAt = null, pause = null, live = null, spectator = false }) {
+  config = null, frozenAt = null, pause = null, live = null, spectator = false,
+  spectators = null, myId = null, isHost = false, onRemoveSpectator = null }) {
  const phase = pub?.phase;
  const boss = isBossPhase(phase);
  const lp = boss && Number.isFinite(pub?.teamLp) ? pub.teamLp : Number.isFinite(priv?.lp) ? priv.lp : null;
@@ -338,7 +380,10 @@ export function TopBar({ pub, priv, conn, hud, total, drawer, onExit, onDrawer,
    <div class="gtop__left">
      <${Button} variant="danger" size="lg" square=${true} icon="exit" onClick=${onExit} aria-label=${t('离开')} title=${t('离开 / 暂离')} class="gtop__exit tapx" />
      <div class="gtop__meta">
-        <${PingPill} ms=${conn?.ping} online=${conn?.status === 'online'} />
+        <div class="gtop__net">
+          <${PingPill} ms=${conn?.ping} online=${conn?.status === 'online'} />
+          <${SpectatorPill} spectators=${spectators} myId=${myId} isHost=${isHost} onRemove=${onRemoveSpectator} />
+        </div>
        ${pub?.difficulty ? html`<${DifficultyTag} difficulty=${pub.difficulty} size="sm" />` : null}
      </div>
    </div>
@@ -4,10 +4,13 @@
 // while the current language's pack is a machine translation, `_meta.machineTranslated`) and the 快捷键
 // section that rebinds the in-match shortcuts (the key map: ui/gameLogic/shortcuts.js; the community request
 // 「快捷键可不可以自己设置」, the owner's decision of 2026-10-07) and 问题反馈, which copies the diagnostics of this page
-// for a bug report (diag.js: the error log, this browser, optionally the battle on screen; nothing is uploaded).
+// for a bug report (diag.js: the error log, this browser, optionally the battle on screen; nothing is uploaded). The
+// lobby and the room open it from a 设置 button next to 玩法说明 (SettingsButton, GitHub #238); the title screen and the
+// match have their own gear.

 import { useLayoutEffect, useRef, useState } from '../../vendor/hooks.module.js';
 import { html, Modal, Button, Icon, MicroLabel } from './components.js';
+import { GIcon } from './gameComponents.js';
 import { createStore, useStore, loadPref, savePref, store } from '../store.js';
 import { sanitizeSettings, HOTKEY_ACTIONS, DEFAULT_HOTKEYS, hotkeyLabel, rebindHotkey, isDefaultHotkeys, captureHotkey, VOICE_LANGS } from './gameLogic.js';
 import { audio } from '../audio.js';
@@ -247,3 +250,16 @@ export function SettingsModal({ open, onClose }) {
    </div>
  <//>`;
 }
+
+/**
+ * The 设置 button of the lobby and the room (GitHub #238 — before it the settings were reachable only from the title
+ * screen and a running match): the twin of the 玩法说明 button (ui/guide.js GuideButton), with the settings modal behind it
+ * (mounted only while open). The same modal as the title screen's and the match's: nothing in it is match-only.
+ * @param {{ class?: string, size?: 'sm'|'md'|'lg'|'xl', variant?: string, label?: string }} props
+ */
+export function SettingsButton({ class: cls, size = 'sm', variant = 'ghost', label = t('设置') }) {
+  const [open, setOpen] = useState(false);
+  return html`<${Button} variant=${variant} size=${size} class=${cx('settings-btn', cls)} onClick=${() => setOpen(true)}
+      title=${t('设置')} aria-label=${t('设置')} data-testid="settings-btn"><${GIcon} name="gear" class="btn__icon" />${label}<//>
+    ${open ? html`<${SettingsModal} open=${true} onClose=${() => setOpen(false)} />` : null}`;
+}
@@ -183,6 +183,17 @@ function SoldCard({ item = false }) {
  </div>`;
 }

+/**
+ * A slot with no card in it: the one a 调度中心 upgrade has just opened (a `null` slot — server/match/player/economy.js
+ * _openLevelSlots; GitHub #332 / PR #333: the official shop shows the new slot, empty, until the next refresh or round
+ * start fills it). Never 已招募 / SOLD OUT: nothing was bought there.
+ */
+function EmptyCard({ item = false }) {
+  // `scard--sold` too: the same inert frame (no hover lift, not a buyable card for every `:not(.scard--sold)` rule); `scard--empty` only restyles it
+  return html`<div class=${cx('scard', 'scard--sold', 'scard--empty', item && 'scard--item')} role="img" aria-label=${t('空栏位：刷新或下回合开始时补满')}
+    title=${t('空栏位：刷新或下回合开始时补满')}></div>`;
+}
+
 function LevelCard({ shop, reason, armed = false, onTap }) {
  const lv = shop?.level ?? 1;
  const max = lv >= (shop?.maxLevel ?? 6);
@@ -356,7 +367,8 @@ export function ShopBar({ priv, editable, collapsed, onCollapse, onBuy, onLevel,
          armed=${armed} onTap=${tapCard} offBonds=${offBonds} />`
        : html`<div class="shopbar__cards">
        ${chessSlots.map(({ s, i }) => {
-          if (!s || s.sold) return html`<${SoldCard} key=${`s${i}`} />`;
+          if (!s) return html`<${EmptyCard} key=${`e${i}`} />`;
+          if (s.sold) return html`<${SoldCard} key=${`s${i}`} />`;
          const reason = shopBlockReason('buy', { priv, editable, slot: s, ...LOOKUPS });
          return html`<${ChessCard} key=${`c${i}:${s.id}`} slot=${s} idx=${i} priv=${priv} frozen=${slotFrozen(s, frozen)} onBuy=${onBuy} onDetail=${onDetail} offBonds=${offBonds}
              reason=${reason} armed=${armed === armKey('c', i, s)} onTap=${editable ? (idx) => tapCard('c', idx, s, 'chess', reason, onBuy) : null} />`;