linkchat-extension-spire 0.1.9 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
-# Spire for LinkChat — 0.1.9
+# Spire for LinkChat — 0.3.0
 
-按需安装的频道合作卡牌爬塔 TUI。需要支持扩展 API 1 的 LinkChatCLI **0.7.0-beta.2 及以上**（旧宿主只支持键盘）；路线图与目标的颜色要 **0.7.3 及以上**，更旧的宿主会把颜色剥离，以及管理员安装并启用 `linkchat-spire` 后端包；后端规则版本 `spire-tui-2`、内容版本 `0.1.0-alpha.2.dev17`，存档版本不一致时明确拒绝加载，不会静默升级进行中的局。
+按需安装的频道合作卡牌爬塔 TUI。需要支持扩展 API 1 的 LinkChatCLI **0.7.0-beta.2 及以上**（旧宿主只支持键盘）；推荐使用 **0.7.4 及以上**以包含备用屏幕行定位修复；路线图与目标的颜色要 **0.7.3 及以上**，更旧的宿主会把颜色剥离，以及管理员安装并启用 `linkchat-spire` 后端包；后端规则版本 `spire-tui-4`、内容版本 `0.1.0-alpha.2.dev17`，存档版本不一致时明确拒绝加载，不会静默升级进行中的局。
 
-离线包安装：`linkchat extension install spire --from /绝对路径/linkchat-extension-spire-0.1.9.tgz`；省略 `--from` 时从官方 registry 安装 `linkchat-extension-spire@latest`。安装后重新打开 LinkChat，输入 `/spire`。2–4 人同频道创建或加入房间，各自准备后开始。断线或退出会暂停整局；所有人重新准备后继续。
+离线包安装：`linkchat extension install spire --from /绝对路径/linkchat-extension-spire-0.3.0.tgz`；省略 `--from` 时从官方 registry 安装 `linkchat-extension-spire@latest`。安装后重新打开 LinkChat，输入 `/spire`。2–4 人同频道创建或加入房间，各自准备后开始。断线或退出会暂停整局；所有人重新准备后继续。
 
 ## 操作
 
@@ -31,3 +31,11 @@
 ## 其他
 
 扩展只提供游戏界面，存档在服务器，卸载扩展不会删除存档。正式客户端 0.6.3 不包含扩展功能。此版本为正式版。
+
+## 协议 5 配套更新
+
+本版必须与协议 5 的 Spire 后端一起更新。协议 1–4 会明确提示版本不匹配并阻止游戏操作。聊天 CLI 主程序无需重新发布。
+
+升级预览按当前牌堆读取卡牌，保留战斗中的临时费用；队友面板关闭后恢复原选择。水晶球支持方向键、Enter、空格和鼠标操作。
+
+进阶 A0–A10 全部开放，默认 A0。在创建房间前选择“新局难度”，创建后固定；继续已有单人存档保留原等级。扩展 0.3.0 使用游戏协议 5，需要配套后端。

package/index.js

@@ -1,4 +1,6 @@
 import { randomUUID } from 'node:crypto';
+const PROTOCOL = 5;
+const VERSION_ERROR = 'Spire 客户端与服务器版本不匹配，请配套升级。';
 const BASE = '/api/games/spire/rooms';
 const hpText = creature => creature.awaitingRevive ? '0（待复活）' : creature.hpDisplay === 'infinite' && creature.hp > 0 ? '∞' : `${creature.hp}/${creature.maxHp}`;
 export const phases = { lobby: '等待队友', map: '路线投票', combat: '战斗', reward: '战利品', rest: '休息', shop: '商店', event: '事件', treasure: '宝箱', actComplete: '本幕完成', ending: '结局事件', victory: '通关', defeat: '攀登结束', abandoned: '已放弃' };
@@ -46,7 +48,7 @@ Object.assign(powerNames,{ravenous:'食尸增力',plating:'覆甲',tangled:'缠
 // moved on, and the screen has to say so rather than refuse to open. Only the
 // phase check is relaxed, and the caller has to ask for that explicitly.
 function wellFormed(s, knownPhase) {
-  return !!s && [1,2].includes(s.protocol) && typeof s.roomId === 'string' && Number.isSafeInteger(s.revision) && Number.isSafeInteger(s.phaseId) && (knownPhase ? Object.hasOwn(phases, s.phase) : typeof s.phase === 'string')
+  return !!s && s.protocol === PROTOCOL && typeof s.roomId === 'string' && Number.isSafeInteger(s.revision) && Number.isSafeInteger(s.phaseId) && (knownPhase ? Object.hasOwn(phases, s.phase) : typeof s.phase === 'string')
     && Array.isArray(s.players) && s.players.length <= 4 && s.players.every(p => Number.isSafeInteger(p.id) && typeof p.name === 'string')
     && Array.isArray(s.enemies) && s.enemies.length <= 12 && s.enemies.every(e => typeof e.id === 'string' && typeof e.name === 'string' && e.intent)
     && (!s.act || Number.isInteger(s.act.index) && s.act.index>=0 && s.act.index<3 && typeof s.act.name==='string')
@@ -58,6 +60,14 @@ function wellFormed(s, knownPhase) {
     && s.players.every(p=>p.companions===undefined || Array.isArray(p.companions) && p.companions.length<=3 && p.companions.every(pet=>pet && typeof pet.name==='string' && (pet.cooldown===undefined || Number.isSafeInteger(pet.cooldown) && pet.cooldown>=0)))
     && s.players.every(p=>p.monologueInstances===undefined || Array.isArray(p.monologueInstances) && p.monologueInstances.every(record=>record && Number.isSafeInteger(record.strength) && record.strength>0 && Number.isSafeInteger(record.applied) && record.applied>=0))
     && (!s.mapView || typeof s.mapView === 'object' && s.mapView.nodes && s.mapView.nodes.length <= 200 && Array.isArray(s.mapView.nodes) && s.mapView.nodes.every(n => n && typeof n.id === 'string' && Number.isSafeInteger(n.row) && Number.isSafeInteger(n.col) && typeof n.type === 'string' && (n.children === undefined || Array.isArray(n.children))))
+    && (!!s.endTurn && typeof s.endTurn === 'object' && typeof s.endTurn.canEndTurn === 'boolean' && typeof s.endTurn.canUndoEndTurn === 'boolean' && typeof s.endTurn.reason === 'string')
+    && (!s.eventProgress?.sphere || (Number.isSafeInteger(s.eventProgress.sphere.divinations) && s.eventProgress.sphere.divinations >= 0
+        && Number.isSafeInteger(s.eventProgress.sphere.width) && s.eventProgress.sphere.width > 0 && s.eventProgress.sphere.width <= 32
+        && Number.isSafeInteger(s.eventProgress.sphere.height) && s.eventProgress.sphere.height > 0 && s.eventProgress.sphere.height <= 32
+        && typeof s.eventProgress.sphere.tool === 'string' && typeof s.eventProgress.sphere.finished === 'boolean'
+        && Array.isArray(s.eventProgress.sphere.cells) && s.eventProgress.sphere.cells.length <= 1024
+        && s.eventProgress.sphere.cells.every(cell => cell && Number.isSafeInteger(cell.x) && Number.isSafeInteger(cell.y)
+            && (cell.item === null || cell.item === undefined || typeof cell.item === 'string'))))
     && Array.isArray(s.options) && Array.isArray(s.log) && s.log.every(entry => typeof entry === 'string' || entry && Number.isSafeInteger(entry.id) && typeof entry.text === 'string');
 }
 export function validState(s) { return wellFormed(s, true); }
@@ -276,7 +286,10 @@ function cut(text, width) {
 }
 export function createScreen(ctx) {
   let state, roomId, leaseId, connection, online = false, synced = false, rooms = [], loading = true, busy = false, closed = false;
-  let tab = 0, selected = 'create', index = 0, modal, note = '', pending, columns = 80, height = 24, serverProtocol = 1, unsupported;
+  let ascension = 0;
+  const ascensionNames = ['基础', '精英增多', '疲惫旅人', '贫困', '紧束腰带', '进阶之灾', '通货膨胀', '稀缺', '坚韧敌人', '致命敌人', '双重首领'];
+  const ascensionDescriptions = ['无进阶修正', '地图精英配额增加', '古神恢复损失生命的 80%', '战斗与宝箱金币减少', '初始药水栏位减 1', '初始牌组加入进阶之灾', '删牌 100 起，每次增加 50', '稀有卡与升级卡概率降低', '怪物生命与防御等强化', '怪物攻击等强化', '第三幕连续两个不同首领'];
+  let tab = 0, selected = 'create', index = 0, modal, note = '', pending, columns = 80, height = 24, serverProtocol = undefined, unsupported;
   // Frame row -> what that row means, rebuilt by every render.
   let hits = [];
   let targeting;
@@ -309,7 +322,7 @@ export function createScreen(ctx) {
   const cardItem = c => ({ id: c.id, label: `${c.name}  [${c.cost}]  ${c.description}`, card: c });
   function items() {
     if (modal) return modal.items;
-    if (!roomId) return [{ id: 'create', label: '创建合作房间（2–4 人）' }, {id:'solo',label:'单人攀登 · 开始／继续'}, ...rooms.filter(r=>r.mode!=='solo').map(r => ({ id: r.id, room: r, label: `${r.players.some(p => p.id === ctx.user.id) ? '继续' : '加入'} · ${r.players.map(p => p.name).join(' / ')} · ${r.players.length}/4 · ${phases[r.phase] ?? r.phase}${r.paused ? ' · 已暂停' : ''}${r.compatible === false ? ' · 版本不兼容' : ''}` }))];
+    if (!roomId) return [{ id: 'create', label: '创建合作房间（2–4 人）' }, {id:'solo',label:rooms.some(r=>r.mode==='solo') ? `继续单人攀登 · A${rooms.find(r=>r.mode==='solo').ascension ?? 0}` : '单人攀登 · 开始'}, {id:'ascension',label:`新局难度 · A${ascension} ${ascensionNames[ascension]}（全部开放）`}, ...rooms.filter(r=>r.mode!=='solo').map(r => ({ id: r.id, room: r, label: `${r.players.some(p => p.id === ctx.user.id) ? '继续' : '加入'} · ${r.players.map(p => p.name).join(' / ')} · A${r.ascension ?? 0} · ${r.players.length}/4 · ${phases[r.phase] ?? r.phase}${r.paused ? ' · 已暂停' : ''}${r.compatible === false ? ' · 版本不兼容' : ''}` }))];
     if (!state) return [];
     if(needsCharacterChoice())return [{id:'keepCharacter',label:`使用当前角色：${me()?.characterName??me()?.character??'铁甲战士'}`},...state.options.filter(row=>row.action?.type==='character')];
     if (['deck','draw','discard','exhaust'].includes(activeTab())) return (state.self[activeTab()] ?? []).map(cardItem);
@@ -365,13 +378,14 @@ export function createScreen(ctx) {
   }
   function anchor() {
     const rows = items(), at = rows.findIndex(row => row.id === selected);
-    index = at >= 0 ? at : Math.max(0, Math.min(index, rows.length - 1)); selected = rows[index]?.id;
+    index = at >= 0 ? at : Math.max(0, Math.min(Number.isFinite(index) ? index : 0, rows.length - 1)); selected = rows[index]?.id;
   }
   function accept(s) {
     // A phase this build does not know means the server moved ahead of the
     // extension: open it read only instead of refusing the whole state.
     const unknownPhase = typeof s?.phase === 'string' && !Object.hasOwn(phases, s.phase);
-    if (!wellFormed(s, !unknownPhase) || s.self.id !== ctx.user.id || s.channelId !== ctx.channel.id || s.roomId !== roomId) throw new Error('游戏状态与客户端不兼容。');
+    if (s?.protocol !== PROTOCOL) { synced=false; note=VERSION_ERROR; changed(); throw new Error(VERSION_ERROR); }
+    if (!wellFormed(s, !unknownPhase) || s.self.id !== ctx.user.id || s.channelId !== ctx.channel.id || s.roomId !== roomId) { synced=false; throw new Error('游戏状态与客户端不兼容。'); }
     // An older snapshot must not clear the read-only guard before it is discarded:
     // check the revision first, then update anything derived from the state.
     if (state && s.revision < state.revision) return;
@@ -419,7 +433,8 @@ export function createScreen(ctx) {
     try { result = await ctx.request(`${BASE}?channelId=${ctx.channel.id}`); }
     catch (e) { if (e?.status === 404) throw new Error('服务器尚未安装或启用 Spire 后端模块。'); throw e; }
     if (closed) return;
-    if (![1,2].includes(result?.protocol) || !Array.isArray(result.rooms)) throw new Error('服务器未启用兼容的游戏模块。');
+    if (result?.protocol !== PROTOCOL) { synced=false; serverProtocol=undefined; throw new Error(VERSION_ERROR); }
+    if (!Array.isArray(result.rooms)) throw new Error('游戏房间列表无效。');
     serverProtocol = result.protocol; rooms = result.rooms; anchor(); loading = false;
   }
   function connect(id) {
@@ -432,7 +447,7 @@ export function createScreen(ctx) {
     });
   }
   async function submit(action, retry = false) {
-    if ((!retry && !canAct()) || !leaseId || !roomId) return;
+    if ((!retry && !canAct()) || !online || !synced || !leaseId || !roomId) return;
     await guard(async () => {
       if (!retry) pending = { actionId: randomUUID(), leaseId, action: { ...action, phaseId: action.phaseId ?? state.phaseId } };
       const envelope = { ...pending, leaseId };
@@ -450,12 +465,34 @@ export function createScreen(ctx) {
     });
   }
   function choose(title, candidates, acceptChoice) {
-    modal = { title, items: candidates, accept: acceptChoice, previousSelected: selected, previousIndex: index }; index = 0; selected = candidates[0]?.id; changed();
+    modal = { title, items: candidates, accept: acceptChoice, previousSelected: selected, previousIndex: index, previousPage: listPage }; listPage = 0; index = 0; selected = candidates[0]?.id; changed();
   }
   function deckChoice(mode, callback) {
     const cards = state.self.deck.filter(c => mode === 'deckUpgrade' ? (!c.upgraded && !['status', 'curse', 'quest'].includes(c.kind)) : mode === 'deckEnchant' ? (c.canSown !== false && !c.sown && !c.inky && !c.enchantment && !['status', 'curse', 'quest'].includes(c.kind)) : c.removable !== false);
     if (!cards.length) { note = '没有符合条件的牌。'; changed(); return; }
-    choose('选择牌组中的牌', cards.map(cardItem), row => callback(row.id));
+    choose('选择牌组中的牌', cards.map(cardItem), row => {
+      if (mode === 'deckUpgrade') { void previewUpgrade(row.id, 'deck', callback); return; }
+      callback(row.id);
+    });
+  }
+  async function previewUpgrade(cardId, source, confirmUpgrade) {
+    if (!roomId || !canAct() || !cardId) return;
+    const originRoom=roomId, originPhase=state.phaseId, originRevision=state.revision;
+    await guard(async () => {
+      const body = await ctx.request(`${BASE}/${originRoom}/previews/upgrade`, 'POST', { cardId, source });
+      if(roomId!==originRoom || state?.phaseId!==originPhase || state?.revision!==originRevision)return;
+      const line = card => `${card.name}  [${card.cost}]  ${card.description}`;
+      const rows = [
+        { id:'before', label:`升级前：${line(body.before)}` },
+        { id:'after', label:`升级后：${line(body.after)}` },
+        { id:'back', label:'返回' },
+      ];
+      if (confirmUpgrade) rows.push({ id:'confirm', label:'确认升级' });
+      choose('升级预览', rows, answer => {
+        if (answer.id === 'confirm') confirmUpgrade(cardId);
+        else { modal=undefined; anchor(); changed(); }
+      });
+    });
   }
   function cardAction(c) {
     if (!canAct() || state.paused || me()?.done || me()?.hp <= 0) return;
@@ -467,13 +504,16 @@ export function createScreen(ctx) {
       else void submit(action);
     };
     const eligible = state.self.hand.filter(x => x.id !== c.id && (c.choice !== 'upgrade' || (!x.upgraded && !['status', 'curse', 'quest'].includes(x.kind))));
-    if (c.choice && eligible.length) choose(c.choice === 'upgrade' ? '选择升级的手牌' : '选择消耗的手牌', eligible.map(cardItem), row => { action.choice = row.id; send(); });
+    if (c.choice && eligible.length) choose(c.choice === 'upgrade' ? '选择升级的手牌' : '选择消耗的手牌', eligible.map(cardItem), row => {
+      const commit=()=>{ action.choice = row.id; send(); };
+      if (c.choice === 'upgrade') void previewUpgrade(row.id, 'hand', commit); else commit();
+    });
     else send();
   }
   // The keyboard branches and clicks move the same state through these, so the
   // two input paths cannot drift apart.
   function switchTab(next) { pileView=undefined; tab = ((next % tabs.length) + tabs.length) % tabs.length; index = 0; selected = undefined; changed(); }
-  function moveTo(next) { const list = items(); index = Math.max(0, Math.min(next, list.length - 1)); selected = list[index]?.id; changed(); }
+  function moveTo(next) { const list = items(); index = Math.max(0, Math.min(Number.isFinite(next) ? next : 0, list.length - 1)); selected = list[index]?.id; changed(); }
   function pageDetail(delta) { modal.detailOffset = Math.max(0, (modal.detailOffset ?? 0) + delta); changed(); }
   function clickRow(id) {
     const list = items(), at = list.findIndex(row => row.id === id);
@@ -784,11 +824,92 @@ function mapHeader(width, view) {
     return hits.filter(hit => hit.row <= y && y < hit.row + hit.height && hit.col <= x && x < hit.col + hit.width)
       .sort((left, right) => left.width * left.height - right.width * right.height)[0];
   }
+  // The divination board. The server sends only the cells a player has looked
+  // at, so the client cannot draw what it has not earned and has no layout of
+  // its own to keep in step.
+  let sphereCursor = { x: 5, y: 5 };
+  function sphereView() { return state?.eventProgress?.sphere; }
+  function sphereGlyph(cell) {
+    if (!cell) return '·';
+    if (cell.item === 'Relic') return 'R';
+    if (cell.item === 'Potion') return 'P';
+    if (cell.item === 'CardReward') return 'C';
+    if (cell.item === 'Gold') return '$';
+    if (cell.item === 'Curse') return '!';
+    return 'o';
+  }
+  function sphereAt(view, x, y) {
+    return (view.cells ?? []).find(cell => cell.x === x && cell.y === y);
+  }
+  function sphereLines(view) {
+    const header = '    ' + Array.from({ length: view.width }, (_, x) => String(x % 10)).join(' ');
+    const lines = [header];
+    for (let y = 0; y < view.height; y += 1) {
+      const cells = [];
+      for (let x = 0; x < view.width; x += 1) {
+        const here = x === sphereCursor.x && y === sphereCursor.y;
+        const glyph = sphereGlyph(sphereAt(view, x, y));
+        cells.push(here ? `[${glyph}` : ` ${glyph}`);
+      }
+      lines.push(`${String(y).padStart(2, ' ')}  ${cells.join('').slice(1)}`);
+    }
+    return lines;
+  }
+  function sphereMove(dx, dy) {
+    const view = sphereView(); if (!view) return;
+    sphereCursor = { x: Math.max(0, Math.min(view.width - 1, sphereCursor.x + dx)),
+                     y: Math.max(0, Math.min(view.height - 1, sphereCursor.y + dy)) };
+    changed();
+  }
+  function sphereUse() {
+    const view = sphereView(); if (!view || view.finished) return;
+    void submit({ type: 'sphere', op: 'use', x: sphereCursor.x, y: sphereCursor.y });
+  }
+  function sphereTool() {
+    const view = sphereView(); if (!view || view.finished) return;
+    void submit({ type: 'sphere', op: 'tool', tool: view.tool === 'Big' ? 'Small' : 'Big' });
+  }
+  // Teammate detail. Read only, and paged on the server: the client asks for a
+  // page and shows what comes back, so it never holds a second copy of anyone's
+  // deck and never has to keep one in step.
+  async function inspectPlayer(id, page = 0) {
+    if (!roomId || !canAct()) return;
+    await guard(async () => {
+      const body = await ctx.request(`${BASE}/${roomId}/players/${id}/inspection?page=${page}`);
+      const rows = body.rows ?? [];
+      const first = body.total === 0 ? 0 : page * (body.pageSize ?? 40) + 1;
+      const last = page * (body.pageSize ?? 40) + rows.length;
+      const pages = Math.max(1, Math.ceil(body.total / (body.pageSize ?? 40)));
+      const previous = modal?.inspection ? {previousSelected:modal.previousSelected, previousIndex:modal.previousIndex, previousPage:modal.previousPage} : undefined;
+      choose(`${body.name} · ${first}-${last}/${body.total} · 第 ${page + 1}/${pages} 页`,
+        rows.map((row, i) => ({ id: `i${i}`, label: `${row.pile === 'status' ? powerNames[row.key] ?? row.key : row.name ?? row.key}${row.amount !== undefined ? ` ${row.amount}` : ''}${row.description ? `：${row.description}` : ''}${row.upgraded ? ' +' : ''}` })),
+        () => { anchor(); changed(); });
+      if(previous)Object.assign(modal,previous);
+      modal.inspection={id,page,pages,total:body.total};
+      changed();
+    });
+  }
+  function endTurnState() {
+    return state.endTurn;
+  }
+  // One key, three states. The server decides which applies and why, so the
+  // client never has to infer "the turn is resolving" from the phase.
   function endTurn() {
-    if (modal || !canAct() || state?.phase !== 'combat' || state.paused || state.pendingChoice || state.pendingDecision) return;
-    if (me()?.done || (me()?.hp ?? 0) <= 0) return;
+    if (modal || !canAct() || state?.phase !== 'combat' || state.paused) return;
+    const control = endTurnState();
+    if (control.canUndoEndTurn) { void submit({ type: 'undoEnd', turn: state.turn }); return; }
+    if (!control.canEndTurn) return;
     void submit({ type: 'end' });
   }
+  function endTurnLabel() {
+    const own = me();
+    if ((own?.hp ?? 0) <= 0) return '[已倒下]';
+    if (state?.phase !== 'combat') return '';
+    const control = endTurnState();
+    if (control.canUndoEndTurn) return '[E 撤销结束回合]';
+    if (control.canEndTurn) return state.paused ? '[等待继续]' : '[E 结束回合]';
+    return state.paused ? '[等待继续]' : `[${control.reason || '等待结算'}]`;
+  }
   function inspectEntity(id) {
     const enemy = (state.enemies ?? []).find(entry => entry.id === id);
     const player = (state.players ?? []).find(entry => String(entry.id) === id);
@@ -860,12 +981,15 @@ function mapHeader(width, view) {
   function confirm() {
     if (busy || pending) return;
     anchor(); const row = items()[index]; if (!row) return;
-    if (modal) { const current = modal; modal = undefined; selected = current.previousSelected; index = current.previousIndex; current.accept(row); return; }
+    if (modal) { const current = modal; modal = undefined; selected = current.previousSelected; index = current.previousIndex; listPage = current.previousPage ?? 0; current.accept(row); return; }
     if (!roomId) {
+      if (row.id === 'ascension') { choose('进阶难度 · 效果逐级叠加 · 创建后固定', ascensionNames.map((name, level)=>({id:String(level), label:`A${level} · ${name}：${ascensionDescriptions[level]}${level===ascension ? ' ✓' : ''}`})), choice=>{ascension=Number(choice.id);changed();});return; }
       void guard(async () => {
+        if(serverProtocol!==PROTOCOL)throw new Error(VERSION_ERROR);
         if (row.id === 'create' || row.id === 'solo') {
-          if (row.id === 'solo' && serverProtocol < 2) throw new Error('单人模式需要更新 Spire 后端模块。');
-          const result = await ctx.request(BASE, 'POST', { channelId: ctx.channel.id, requestId: randomUUID(),...(serverProtocol >= 2 ? {mode:row.id==='solo'?'solo':'coop'} : {}) }); connect(result.id);
+          const existing = row.id === 'solo' && rooms.find(r=>r.mode==='solo');
+          if (existing) { if(existing.compatible===false)throw new Error('该存档需要对应版本的后端游戏模块。'); await ctx.request(`${BASE}/${existing.id}/join`, 'POST');connect(existing.id);return; }
+          const result = await ctx.request(BASE, 'POST', { ascension, channelId: ctx.channel.id, requestId: randomUUID(),mode:row.id==='solo'?'solo':'coop' }); connect(result.id);
         } else {
           if (row.room.compatible === false) throw new Error('该存档需要对应版本的后端游戏模块。');
           await ctx.request(`${BASE}/${row.id}/join`, 'POST'); connect(row.id);
@@ -1018,7 +1142,7 @@ function mapHeader(width, view) {
       const mark = hit => hits.push({ row: frame.length, col: 0, width: Infinity, height: 1, ...hit });
       if (width < 40 || rows < (mapNavigation()?12:20)) { add(`请扩大终端至至少 40 列、${mapNavigation()?12:20} 行。`, 'title'); add('Esc 返回聊天', 'muted'); return frame; }
       const own = me();
-      const heading = needsCharacterChoice() ? '选择初始角色' : state ? `${state.act ? `第 ${state.act.index + 1} 幕 ${state.act.name} · ` : ''}第 ${state.floor} 层 · ${phases[state.phase]}${state.paused ? ' · 暂停' : ''}` : `Spire · ${ctx.channel.name} · 合作房间`;
+      const heading = needsCharacterChoice() ? '选择初始角色' : state ? `A${state.ascension ?? 0} · ${state.act ? `第 ${state.act.index + 1} 幕 ${state.act.name} · ` : ''}第 ${state.floor} 层 · ${phases[state.phase]}${state.paused ? ' · 暂停' : ''}` : `Spire · ${ctx.channel.name} · 合作房间`;
       const status = state ? `金币 ${own?.gold ?? 0} · 药水 ${(own?.potions ?? []).length}/${own?.potionCapacity ?? 3} · ${state.online?.includes(ctx.user.id) ? '已连接' : '离线'}` : '';
       add(status ? pad(cut(heading, Math.max(8, width - displayWidth(status) - 2)), width - displayWidth(status)) + status : cut(heading, width), 'title');
       if(mapNavigation()) {
@@ -1145,7 +1269,7 @@ function mapHeader(width, view) {
           const usable = own?.energy ?? 0;
           const capacity = own?.energyCapacity ?? usable;
           const orbs = '●'.repeat(Math.max(0, usable)) + '○'.repeat(Math.max(0, capacity - usable));
-          const button = (own?.hp ?? 0) <= 0 ? '[已倒下]' : own?.done ? '[已结束回合]' : (!canAct() || state.paused) ? '[等待队友]' : '[E 结束回合]';
+          const button = endTurnLabel();
           // §2: the Regent's stars are a resource of the same row as the energy.
           const stars = own?.character === 'regent' || (own?.stars ?? 0) > 0 ? `星星 ${own?.stars ?? 0}` : '';
           const energy = `能量 ${orbs ? `${orbs} ` : ''}${usable}/${capacity}${stars ? `   ${stars}` : ''}`;
@@ -1166,9 +1290,22 @@ function mapHeader(width, view) {
           for (const player of state.players ?? []) {
             const here = state.online?.includes(player.id);
             const flag = !here ? '离线' : state.paused || state.phase === 'lobby' ? (player.ready ? '已准备' : '') : player.done ? '已完成' : '';
-            add(cut(`${player.id === ctx.user.id ? '› ' : '  '}${player.name}${player.characterName ? ` · ${player.characterName}` : ''} ${hpText(player)} HP · 金币 ${player.gold ?? 0}${flag ? ` · ${flag}` : ''}${player.vote ? ` · 已投票 ${player.vote}` : ''}`, width), player.id === ctx.user.id ? 'selected' : 'text');
+            const rowText = cut(`${player.id === ctx.user.id ? '› ' : '  '}${player.name}${player.characterName ? ` · ${player.characterName}` : ''} ${hpText(player)} HP · 金币 ${player.gold ?? 0}${flag ? ` · ${flag}` : ''}${player.vote ? ` · 已投票 ${player.vote}` : ''}`, width);
+            // Clicking a teammate is the same act as pressing P on them. The
+            // mark is taken before the line is pushed, while the row still is
+            // the one it will land on.
+            if (player.id !== ctx.user.id && !modal) mark({ kind: 'inspect', id: String(player.id), width: displayWidth(rowText) });
+            add(rowText, player.id === ctx.user.id ? 'selected' : 'text');
           }
           if (['event', 'ending', 'victory'].includes(state.phase) && state.eventProgress?.description) add(state.eventProgress.description, 'muted');
+          const sphere = sphereView();
+          if (sphere && !modal) {
+            const left = sphere.divinations;
+            add(`占卜剩余 ${left} 次 · 工具：${sphere.tool === 'Big' ? '大（3×3）' : '小（1 格）'} · 方向键移动，空格揭开，T 换工具`,
+                left ? 'title' : 'muted');
+            for (const line of sphereLines(sphere)) add(line, 'text');
+            add('R 遗物 · P 药水 · C 卡牌奖励 · $ 金币 · ! 诅咒 · o 空 · · 未揭开', 'muted');
+          }
 
         }
         const labels = tabs.map((key, i) => {
@@ -1311,6 +1448,20 @@ function mapHeader(width, view) {
       if(!modal && !targeting && !pileView && tab===0 && state?.phase==='combat' && ['left','right'].includes(name)){enemyPage=Math.max(0,enemyPage+(name==='right'?1:-1));changed();return;}
       if(!modal && !targeting && state?.phase==='combat' && ['a','s','d'].includes(value) && !(value==='d' && activeTab()==='potions')){openPile({a:'draw',s:'exhaust',d:'discard'}[value]);return;}
       if(name==='escape' && pileView && !modal){pileView=undefined;index=0;selected=undefined;changed();return;}
+      // The board takes the arrows before the option list does, or moving on
+      // the grid would scroll the rows underneath it.
+      if (columns>=40 && height>=20 && sphereView() && !sphereView().finished && tab===0 && !pileView && !modal && !targeting) {
+        if (name === 'up') { sphereMove(0, -1); return; }
+        if (name === 'down') { sphereMove(0, 1); return; }
+        if (name === 'left') { sphereMove(-1, 0); return; }
+        if (name === 'right') { sphereMove(1, 0); return; }
+        if (value === 'h') { sphereMove(-1, 0); return; }
+        if (value === 'l') { sphereMove(1, 0); return; }
+        if (value === 'k') { sphereMove(0, -1); return; }
+        if (value === 'j') { sphereMove(0, 1); return; }
+        if (value === ' ' || name === 'space' || name === 'return' || name === 'enter') { sphereUse(); return; }
+        if (value === 't') { sphereTool(); return; }
+      }
       if (value === ' ' && !modal && !targeting) {
         const row = items()[index];
         if (row?.pick) {
@@ -1330,7 +1481,7 @@ function mapHeader(width, view) {
         return;
       }
       if (name === 'escape' || key.ctrl && ['c', 'd'].includes(name)) {
-        if (modal) { selected = modal.previousSelected; index = modal.previousIndex; modal = undefined; anchor(); changed(); }
+        if (modal) { selected = modal.previousSelected; index = modal.previousIndex; listPage = modal.previousPage ?? 0; modal = undefined; anchor(); changed(); }
         else ctx.closeScreen(); return;
       }
       if (columns < 40 || height < (mapNavigation()?12:20)) return;
@@ -1350,11 +1501,35 @@ function mapHeader(width, view) {
       if (name === 'tab' && !modal && state) { switchTab(tab + (key.shift ? -1 : 1)); return; }
       // The key and the button share one entry point.
       if (value === 'e' && !modal && !targeting) { endTurn(); return; }
+      if (value === 'p' && !modal && !targeting && state) {
+        const others = (state.players ?? []).filter(player => player.id !== ctx.user.id);
+        if (!others.length) { note = '没有队友可查看。'; changed(); return; }
+        if (others.length === 1) { void inspectPlayer(others[0].id); return; }
+        choose('查看队友', others.map(player => ({ id: String(player.id), player: player.id, label: `${player.name} · ${player.characterName ?? ''}` })),
+               row => { void inspectPlayer(row.player ?? Number(row.id)); });
+        return;
+      }
+      if (value === 'u' && !modal && !targeting && state) {
+        const row=items()[index];
+        const cardId=row?.card?.id ?? row?.shop?.cardId ??
+          (['reward','customReward'].includes(row?.action?.type) && !['skip','reroll','sacrifice'].includes(row.action.card) ? row.action.card : undefined);
+        if (cardId) {
+          const source=row?.shop ? 'shop' : ['reward','customReward'].includes(row?.action?.type) ? 'reward' : ['deck','draw','discard','exhaust'].includes(activeTab()) ? activeTab() : 'hand';
+          void previewUpgrade(cardId,source);
+        }
+        else { note='当前项目没有可预览的升级。';changed(); }
+        return;
+      }
       if (name === 'space' && !modal && tab===0 && state?.pendingChoice?.maximum>1) { confirm();return; }
       if (value === 'd' && !modal && activeTab() === 'potions' && canAct()) {
         if (state.self.potionsLocked) { note = '请先完成事件交易，当前不能使用或丢弃药水。'; changed(); return; }
         const row = items()[index]; if (row?.potion) choose('丢弃这瓶药水？', [{ id: 'no', label: '保留' }, { id: 'yes', label: '丢弃' }], answer => { if (answer.id === 'yes') void submit({ type: 'dropPotion', potion: row.id }); else changed(); }); return;
       }
+      if (modal?.inspection && ['pageup','pagedown'].includes(name)) {
+        const wanted = modal.inspection.page + (name === 'pageup' ? -1 : 1);
+        if (wanted < 0 || wanted >= modal.inspection.pages) return;
+        void inspectPlayer(modal.inspection.id, wanted); return;
+      }
       if (modal?.detail && ['pageup','pagedown'].includes(name)) { pageDetail(name === 'pageup' ? -3 : 3); return; }
       if (name === 'pageup' || name === 'pagedown') {
         const pages = Math.max(1, Math.ceil(items().length / pageSize));
@@ -1400,6 +1575,7 @@ function mapHeader(width, view) {
           return;
         }
         if(hit?.kind==='enemyPage' && !targeting && !modal){enemyPage=(enemyPage+1)%hit.pages;changed();return;}
+        if (hit?.kind === 'inspect') {void inspectPlayer(Number(hit.id));return;}
         if (hit?.kind === 'pile') {openPile(hit.id);return;}
         if (hit?.kind === 'shopBuy') {
           const row = items()[index];
@@ -1452,4 +1628,4 @@ export async function run(context) {
 
 
 // Exported so a test can read a drawn act back the way a player does.
-export { drawMap };
+export { drawMap };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linkchat-extension-spire",
-  "version": "0.1.9",
+  "version": "0.3.0",
   "type": "module",
   "description": "Optional cooperative card-climbing TUI for LinkChat",
   "license": "UNLICENSED",