@cs2dak/presentation 1.0.0 → 2.0.0

package/src/player.test.ts

@@ -1,116 +1,145 @@
-import { readFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
-import { loadDemoPackageFromZip } from "@cs2dak/core";
-import { buildSeasonCohort } from "@cs2dak/cohort";
 import { playerSeasonProfileSchema } from "@cs2dak/contract";
-import { buildAllPlayerSeasonProfiles, buildPlayerSeasonProfile } from "./index";
-
-const fixtureDir = fileURLToPath(new URL("../../../fixtures/input/cohort", import.meta.url));
-const integrationTimeoutMs = 20_000;
-let cohortFixtures: ReturnType<typeof buildCohort> | null = null;
-
-async function buildCohort() {
-  const names = (await readdir(fixtureDir)).filter((name) => name.endsWith(".zip")).sort();
-  const demos = await Promise.all(
-    names.map(async (name) => ({
-      matchId: name.replace(/\.zip$/, ""),
-      pkg: await loadDemoPackageFromZip(await readFile(join(fixtureDir, name)))
-    }))
-  );
-  return buildSeasonCohort(demos);
-}
-
-function getCohort() {
-  cohortFixtures ??= buildCohort();
-  return cohortFixtures;
-}
-
-describe("buildPlayerSeasonProfile", () => {
-  it(
-    "derives a per-player profile covering rating, metrics, style and trend",
-    async () => {
-      const bundle = await getCohort();
-      const profiles = buildAllPlayerSeasonProfiles(bundle);
-
-      expect(profiles).toHaveLength(bundle.players.length);
-      for (const profile of profiles) {
-        expect(() => playerSeasonProfileSchema.parse(profile)).not.toThrow();
-      }
+import { buildAllPlayerSeasonProfiles } from "./index";
+import { buildTestSeasonCohortBundle } from "./test-fixtures";
+
+describe("buildAllPlayerSeasonProfiles", () => {
+  it("derives a per-player profile covering rating, metrics, style and trend", () => {
+    const bundle = buildTestSeasonCohortBundle();
+    const profiles = buildAllPlayerSeasonProfiles(bundle);
+
+    expect(profiles).toHaveLength(bundle.players.length);
+    for (const profile of profiles) {
+      expect(() => playerSeasonProfileSchema.parse(profile)).not.toThrow();
+    }
+
+    const source = bundle.players[0];
+    const profile = profiles.find((row) => row.playerKey === source.playerKey)!;
+
+    // 元信息与评分透传（不重算）
+    expect(profile.version).toBe("cs2-demo-analysis-kit/player-profile-0.2");
+    expect(profile.rating.rivalhubRR).toBe(source.accountRR);
+    expect(profile.rating.hltvRating).toBe(source.rrV1);
+    expect(profile.rating.hltvPercentile).toBe(source.rrV1Percentile);
+    expect(profile.rating.breakdown.map((b) => b.key)).toEqual([
+      "combat",
+      "trade",
+      "mapControl",
+      "clutch",
+      "objective",
+      "utility"
+    ]);
+    expect(profile.weapons.reduce((sum, weapon) => sum + weapon.kills, 0)).toBe(source.weaponHighlights.totalKills);
+    expect(profile.weapons.map((weapon) => weapon.kills)).toEqual(
+      [...profile.weapons.map((weapon) => weapon.kills)].sort((a, b) => b - a)
+    );
+    expect(profile.weapons.every((weapon) =>
+      weapon.headshotPercent == null || (weapon.headshotPercent >= 0 && weapon.headshotPercent <= 100)
+    )).toBe(true);
+    expect(profile.highlights.noScopeKills).toBe(source.weaponHighlights.highlights.noScopeKills);
+    expect(profile.highlights.wallbangKills).toBe(source.weaponHighlights.highlights.wallbangKills);
 
-      const source = bundle.players[0];
-      const profile = buildPlayerSeasonProfile(bundle, source.playerKey);
-
-      // 元信息与评分透传（不重算）
-      expect(profile.version).toBe("cs2-demo-analysis-kit/player-profile-0.1");
-      expect(profile.rating.rivalhubRR).toBe(source.accountRR);
-      expect(profile.rating.hltvRating).toBe(source.rrV1);
-      expect(profile.rating.hltvPercentile).toBe(source.rrV1Percentile);
-      expect(profile.rating.breakdown.map((b) => b.key)).toEqual([
-        "combat",
-        "trade",
-        "clutch",
-        "objective",
-        "utility"
-      ]);
-      expect(profile.weapons.reduce((sum, weapon) => sum + weapon.kills, 0)).toBe(source.weaponHighlights.totalKills);
-      expect(profile.weapons.map((weapon) => weapon.kills)).toEqual(
-        [...profile.weapons.map((weapon) => weapon.kills)].sort((a, b) => b - a)
-      );
-      expect(profile.weapons.every((weapon) =>
-        weapon.headshotPercent == null || (weapon.headshotPercent >= 0 && weapon.headshotPercent <= 100)
-      )).toBe(true);
-      expect(profile.highlights.noScopeKills).toBe(source.weaponHighlights.highlights.noScopeKills);
-      expect(profile.highlights.wallbangKills).toBe(source.weaponHighlights.highlights.wallbangKills);
-
-      // 每场趋势条数 == 该选手参与场次，且按 matchId 升序
-      expect(profile.perMatch).toHaveLength(source.perMatch.length);
-      const ids = profile.perMatch.map((m) => m.matchId);
-      expect(ids).toEqual([...ids].sort((a, b) => a.localeCompare(b)));
-
-      // 中立性：不暴露数据库/路由字段
-      expect(profile).not.toHaveProperty("userId");
-    },
-    integrationTimeoutMs
-  );
-
-  it(
-    "exposes PRISM style as 8 ordered axes, or null when PRISM is missing",
-    async () => {
-      const bundle = await getCohort();
-      const profiles = buildAllPlayerSeasonProfiles(bundle);
-
-      for (const profile of profiles) {
-        const source = bundle.players.find((p) => p.playerKey === profile.playerKey)!;
-        if (source.prism == null) {
-          expect(profile.style).toBeNull();
-        } else {
-          expect(profile.style).not.toBeNull();
-          expect(profile.style!.axes).toHaveLength(8);
-          // 风格轴顺序固定（PRISM_AXIS_ORDER）
-          expect(profile.style!.axes.map((a) => a.key)).toEqual([
-            "firepower",
-            "opening",
-            "clutch",
-            "sniping",
-            "survival",
-            "utility",
-            "trading",
-            "entry"
-          ]);
-          for (const axis of profile.style!.axes) {
-            expect(axis.percentile).toBeGreaterThanOrEqual(0);
-            expect(axis.percentile).toBeLessThanOrEqual(100);
-          }
+    // 每场趋势条数 == 该选手参与场次，且按 matchId 升序
+    expect(profile.perMatch).toHaveLength(source.perMatch.length);
+    const ids = profile.perMatch.map((m) => m.matchId);
+    expect(ids).toEqual([...ids].sort((a, b) => a.localeCompare(b)));
+
+    // 中立性：不暴露数据库/路由字段
+    expect(profile).not.toHaveProperty("userId");
+  });
+
+  it("exposes PRISM style as 8 ordered axes, or null when PRISM is missing", () => {
+    const bundle = buildTestSeasonCohortBundle();
+    const profiles = buildAllPlayerSeasonProfiles(bundle);
+
+    for (const profile of profiles) {
+      const source = bundle.players.find((p) => p.playerKey === profile.playerKey)!;
+      if (source.prism == null) {
+        expect(profile.style).toBeNull();
+      } else {
+        expect(profile.style).not.toBeNull();
+        expect(profile.style!.axes).toHaveLength(8);
+        // 风格轴顺序固定（PRISM_AXIS_ORDER）
+        expect(profile.style!.axes.map((a) => a.key)).toEqual([
+          "firepower",
+          "opening",
+          "clutch",
+          "sniping",
+          "survival",
+          "utility",
+          "trading",
+          "entry"
+        ]);
+        for (const axis of profile.style!.axes) {
+          expect(axis.status).toBe("ready");
+          expect(axis.involvementPercentile).toBeGreaterThanOrEqual(0);
+          expect(axis.involvementPercentile).toBeLessThanOrEqual(100);
+          expect(axis.efficiencyPercentile).toBeGreaterThanOrEqual(0);
+          expect(axis.efficiencyPercentile).toBeLessThanOrEqual(100);
+          expect(axis.signalCoverage).toBe(1);
+          expect(axis.comparisonCount).toBe(5);
         }
       }
-    },
-    integrationTimeoutMs
-  );
-
-  it("throws for an unknown playerKey", async () => {
-    const bundle = await getCohort();
-    expect(() => buildPlayerSeasonProfile(bundle, "steam:does-not-exist")).toThrow(/not found/);
-  }, integrationTimeoutMs);
+    }
+  });
+
+  it("does not expose precise axis percentiles when PRISM signal coverage is partial", () => {
+    const bundle = buildTestSeasonCohortBundle();
+    const source = bundle.players.find((player) => player.prism != null)!;
+    source.prism!.axes.entry.availableSignalWeight = 0.5;
+
+    const profile = buildAllPlayerSeasonProfiles(bundle).find((item) => item.playerKey === source.playerKey)!;
+    const entry = profile.style!.axes.find((axis) => axis.key === "entry")!;
+
+    expect(entry.status).toBe("partial");
+    expect(entry.involvementPercentile).toBeNull();
+    expect(entry.efficiencyPercentile).toBeNull();
+    expect(entry.combinedPercentile).toBeNull();
+  });
+
+  it("does not expose precise PRISM percentiles for a one-player cohort", () => {
+    const bundle = buildTestSeasonCohortBundle();
+    bundle.players = bundle.players.slice(0, 1);
+
+    const profile = buildAllPlayerSeasonProfiles(bundle)[0];
+    const axis = profile.style!.axes.find((item) => item.key === "firepower")!;
+
+    expect(axis.status).toBe("insufficient");
+    expect(axis.comparisonCount).toBe(1);
+    expect(axis.involvementPercentile).toBeNull();
+    expect(axis.efficiencyPercentile).toBeNull();
+    expect(axis.combinedPercentile).toBeNull();
+  });
+
+  it("does not expose precise PRISM percentiles for a small cohort", () => {
+    const bundle = buildTestSeasonCohortBundle();
+    bundle.players = bundle.players.slice(0, 2);
+
+    const profile = buildAllPlayerSeasonProfiles(bundle)[0];
+    const axis = profile.style!.axes.find((item) => item.key === "firepower")!;
+
+    expect(axis.status).toBe("insufficient");
+    expect(axis.comparisonCount).toBe(2);
+    expect(axis.involvementPercentile).toBeNull();
+    expect(axis.efficiencyPercentile).toBeNull();
+  });
+
+  it("uses midpoint ranks when all valid PRISM values tie", () => {
+    const bundle = buildTestSeasonCohortBundle();
+    for (const player of bundle.players) {
+      if (!player.prism) continue;
+      player.prism.axes.sniping.involvementRaw = 4;
+      player.prism.axes.sniping.efficiencyRaw = 2;
+    }
+
+    const axes = buildAllPlayerSeasonProfiles(bundle)
+      .flatMap((profile) => profile.style?.axes.filter((axis) => axis.key === "sniping") ?? []);
+
+    expect(axes).toHaveLength(5);
+    for (const axis of axes) {
+      expect(axis.status).toBe("ready");
+      expect(axis.involvementPercentile).toBe(50);
+      expect(axis.efficiencyPercentile).toBe(50);
+    }
+  });
 });

package/src/player.ts

@@ -14,23 +14,28 @@ import { displayWeaponName } from "./weapons.js";
 const RR_BREAKDOWN_LABEL: Record<RRBreakdownEntry["key"], string> = {
   combat: "Combat",
   trade: "Trade",
+  mapControl: "MapControl",
   clutch: "Clutch",
   objective: "Objective",
   utility: "Utility"
 };
 
-/** PRISM 八维中文标签。 */
+/** PRISM 八维打法画像标签；不把单根轴命名成绝对能力或固定角色。 */
 const PRISM_AXIS_LABEL: Record<PrismAxisKey, string> = {
-  firepower: "火力",
-  opening: "首杀",
-  clutch: "残局",
-  sniping: "狙击",
-  survival: "生存",
-  utility: "道具",
-  trading: "补枪",
-  entry: "突破"
+  firepower: "火力输出",
+  opening: "开局对枪",
+  clutch: "残局参与",
+  sniping: "AWP 使用",
+  survival: "生存选择",
+  utility: "道具投入",
+  trading: "补枪协同",
+  entry: "突破参与"
 };
 
+const MIN_STYLE_SIGNAL_COVERAGE = 0.75;
+/** 小于此人数的 cohort 只能用于浏览原始数据，不能给出精确的相对排名。 */
+const MIN_COHORT_FOR_STYLE_PERCENTILE = 5;
+
 /** 用于强项/弱项判定的技能类指标（高 = 好）。不含纯风格标签（如 AWP）。 */
 const SKILL_METRICS: { key: LeaderboardMetricKey; label: string }[] = [
   { key: "adr", label: "输出 (ADR)" },
@@ -53,17 +58,47 @@ function percentileOf(value: number, distribution: number[]): number {
   return round((atOrBelow / distribution.length) * 100, 1);
 }
 
-function buildStyle(player: SeasonPlayerRow): PlayerSeasonProfile["style"] {
+type PrismDistributions = Record<PrismAxisKey, { involvement: number[]; efficiency: number[] }>;
+
+/** 并列值取中位秩；全员相同时返回 P50，避免小 cohort 中把并列都显示成 P100。 */
+function relativePercentileOf(value: number, distribution: number[]): number | null {
+  if (distribution.length === 0) return null;
+  const lower = distribution.filter((item) => item < value).length;
+  const equal = distribution.filter((item) => item === value).length;
+  return round(((lower + equal / 2) / distribution.length) * 100, 1);
+}
+
+function buildStyle(player: SeasonPlayerRow, distributions: PrismDistributions): PlayerSeasonProfile["style"] {
   const prism = player.prism;
   if (!prism) return null;
   return {
     weightsVersion: prism.weightsVersion,
     rrPercentile: prism.rrPercentile,
-    axes: PRISM_AXIS_ORDER.map((key) => ({
-      key,
-      label: PRISM_AXIS_LABEL[key],
-      percentile: prism.axes[key].percentile
-    }))
+    axes: PRISM_AXIS_ORDER.map((key) => {
+      const axis = prism.axes[key];
+      const comparisonCount = distributions[key].involvement.length;
+      const status = !axis.hasSignal
+        ? "unavailable" as const
+        : axis.availableSignalWeight < MIN_STYLE_SIGNAL_COVERAGE
+          ? "partial" as const
+          : comparisonCount < MIN_COHORT_FOR_STYLE_PERCENTILE
+            ? "insufficient" as const
+            : "ready" as const;
+      return {
+        key,
+        label: PRISM_AXIS_LABEL[key],
+        involvementPercentile: status === "ready"
+          ? relativePercentileOf(axis.involvementRaw, distributions[key].involvement)
+          : null,
+        efficiencyPercentile: status === "ready"
+          ? relativePercentileOf(axis.efficiencyRaw, distributions[key].efficiency)
+          : null,
+        combinedPercentile: status === "ready" ? axis.percentile : null,
+        signalCoverage: axis.availableSignalWeight,
+        comparisonCount,
+        status
+      };
+    })
   };
 }
 
@@ -72,13 +107,14 @@ function profileFromRow(
   metrics: Record<LeaderboardMetricKey, number | null>,
   weightsVersion: string,
   strengths: string[],
-  weaknesses: string[]
+  weaknesses: string[],
+  prismDistributions: PrismDistributions
 ): PlayerSeasonProfile {
   const percent = (count: number, total: number): number | null =>
     total > 0 ? round((count / total) * 100, 1) : null;
 
   return playerSeasonProfileSchema.parse({
-    version: "cs2-demo-analysis-kit/player-profile-0.1",
+    version: "cs2-demo-analysis-kit/player-profile-0.2",
     weightsVersion,
     playerKey: player.playerKey,
     name: player.name,
@@ -117,7 +153,7 @@ function profileFromRow(
         : null
     })),
     highlights: player.weaponHighlights.highlights,
-    style: buildStyle(player),
+    style: buildStyle(player, prismDistributions),
     perMatch: [...player.perMatch]
       .sort((a, b) => a.matchId.localeCompare(b.matchId))
       .map((m) => ({ matchId: m.matchId, rivalhubRR: m.accountRR, hltvRating: m.rrV1 })),
@@ -144,6 +180,17 @@ export function buildAllPlayerSeasonProfiles(bundle: SeasonCohortBundle): Player
   );
 
   const cohortLargeEnough = bundle.players.length >= MIN_COHORT_FOR_NARRATIVE;
+  const prismDistributions = Object.fromEntries(PRISM_AXIS_ORDER.map((key) => {
+    const usable = bundle.players
+      .map((player) => player.prism?.axes[key] ?? null)
+      .filter((axis): axis is NonNullable<typeof axis> =>
+        axis != null && axis.hasSignal && axis.availableSignalWeight >= MIN_STYLE_SIGNAL_COVERAGE
+      );
+    return [key, {
+      involvement: usable.map((axis) => axis.involvementRaw),
+      efficiency: usable.map((axis) => axis.efficiencyRaw)
+    }];
+  })) as PrismDistributions;
 
   return bundle.players.map((player) => {
     const metrics = metricsByKey.get(player.playerKey)!;
@@ -167,15 +214,6 @@ export function buildAllPlayerSeasonProfiles(bundle: SeasonCohortBundle): Player
       .slice(0, MAX_NARRATIVE_ITEMS)
       .map((r) => r.label);
 
-    return profileFromRow(player, metrics, bundle.weightsVersion, strengths, weaknesses);
+    return profileFromRow(player, metrics, bundle.weightsVersion, strengths, weaknesses, prismDistributions);
   });
 }
-
-/** 取单个选手档案；playerKey 不存在时抛错。 */
-export function buildPlayerSeasonProfile(bundle: SeasonCohortBundle, playerKey: string): PlayerSeasonProfile {
-  const profile = buildAllPlayerSeasonProfiles(bundle).find((p) => p.playerKey === playerKey);
-  if (!profile) {
-    throw new Error(`playerKey not found in cohort: ${playerKey}`);
-  }
-  return profile;
-}

package/src/radar-field.ts

@@ -0,0 +1,121 @@
+/**
+ * 雷达场渲染期合成 —— 把 RadarField 的原始计数归一化、按模式合成、可选差分。
+ *
+ * 纯函数，供 react 画布逐秒调用（scrubber）。底层基础场不动，所有视图都是这里的派生：
+ *   ctVis/tVis = 4:3 屏幕可见；ctAim/tAim = 30°准星覆盖；
+ *   ctPres/tPres = 位置占据；ctSound/tSound = 发声风险。
+ *   info-diff = tVis − ctVis（T 信息优势暖 / CT 预警冷）
+ *   contested = min(tVis, ctVis)（双方都看到 = 对拼线 / 真实交火点）
+ * 给定 baseline（联赛场）则输出「队伍 − 联赛」偏移（队伍倾向 / 防守漏洞）。
+ */
+import type { RadarField, RadarFieldBase } from "@cs2dak/contract";
+
+export type RadarFieldMode = RadarFieldBase | "info-diff" | "contested";
+
+export interface RadarModeOption {
+  value: RadarFieldMode;
+  label: string;
+}
+
+/**
+ * 模式选项与中文标签（沿用现有 UI 文案：视野 / 位置 / 信息差分 / 对拼线）。
+ * 盲区不单列模式——画视野覆盖、空白即盲区（配合 canvas「照亮模式」读负空间更直观）。
+ */
+export const RADAR_FIELD_MODES: RadarModeOption[] = [
+  { value: "ctVis", label: "CT 屏幕可见" },
+  { value: "tVis", label: "T 屏幕可见" },
+  { value: "ctAim", label: "CT 准星覆盖" },
+  { value: "tAim", label: "T 准星覆盖" },
+  { value: "ctPres", label: "CT 位置" },
+  { value: "tPres", label: "T 位置" },
+  { value: "ctSound", label: "CT 发声风险" },
+  { value: "tSound", label: "T 发声风险" },
+  { value: "info-diff", label: "信息差分" },
+  { value: "contested", label: "对拼线" },
+];
+
+/** 各模式的颜色强度归一化上限（与原型一致）。 */
+const MODE_CAP: Record<RadarFieldMode, number> = {
+  ctVis: 0.5,
+  tVis: 0.5,
+  ctAim: 0.35,
+  tAim: 0.35,
+  ctPres: 0.3,
+  tPres: 0.3,
+  ctSound: 1,
+  tSound: 1,
+  "info-diff": 0.4,
+  contested: 0.3,
+};
+const DELTA_CAP = 0.15;
+
+export interface RadarModeFrame {
+  /** 逐格渲染值。signed=false 时 ∈[0,cap]，signed=true 时为带符号偏移。 */
+  values: Float64Array;
+  /** true → 发散色（差分 / info-diff：暖=正 / 冷=负）；false → 顺序热力。 */
+  signed: boolean;
+  /** 颜色强度归一化上限。 */
+  cap: number;
+}
+
+/** 某基础场在 [sec−window, sec+window] 的归一化频率（计数 / 对应 side denom）。 */
+function freqAt(field: RadarField, base: RadarFieldBase, sec: number, window: number): Float64Array {
+  const nCells = field.grid.cells.length;
+  const out = new Float64Array(nCells);
+  const denomArr = base.startsWith("ct") ? field.denomCt : field.denomT;
+  let denom = 0;
+  const lo = Math.max(0, sec - window);
+  const hi = Math.min(field.maxSec - 1, sec + window);
+  for (let s = lo; s <= hi; s++) {
+    denom += denomArr[s]!;
+    const row = field.fields[base][s]!;
+    for (let g = 0; g < nCells; g++) out[g]! += row[g]!;
+  }
+  if (denom > 0) for (let g = 0; g < nCells; g++) out[g]! /= denom;
+  return out;
+}
+
+/** 单场在某模式下的逐格频率（未差分）。info-diff/contested 在此合成。 */
+function modeFreq(field: RadarField, mode: RadarFieldMode, sec: number, window: number): Float64Array {
+  if (mode === "info-diff") {
+    const t = freqAt(field, "tVis", sec, window);
+    const c = freqAt(field, "ctVis", sec, window);
+    const out = new Float64Array(t.length);
+    for (let g = 0; g < t.length; g++) out[g]! = t[g]! - c[g]!;
+    return out;
+  }
+  if (mode === "contested") {
+    const t = freqAt(field, "tVis", sec, window);
+    const c = freqAt(field, "ctVis", sec, window);
+    const out = new Float64Array(t.length);
+    for (let g = 0; g < t.length; g++) out[g]! = Math.min(t[g]!, c[g]!);
+    return out;
+  }
+  return freqAt(field, mode, sec, window);
+}
+
+/**
+ * 合成某秒的渲染帧。baseline 非空 → 输出「队伍 − 联赛」偏移（signed）。
+ * @param smoothWindow 时间平滑半窗（±N 秒），默认 ±2s。
+ */
+export function radarModeFrame(
+  field: RadarField,
+  baseline: RadarField | null,
+  mode: RadarFieldMode,
+  sec: number,
+  smoothWindow = 2
+): RadarModeFrame {
+  const team = modeFreq(field, mode, sec, smoothWindow);
+  if (!baseline) {
+    return { values: team, signed: mode === "info-diff", cap: MODE_CAP[mode] };
+  }
+  const base = modeFreq(baseline, mode, sec, smoothWindow);
+  const out = new Float64Array(team.length);
+  for (let g = 0; g < team.length; g++) out[g]! = team[g]! - base[g]!;
+  return { values: out, signed: true, cap: DELTA_CAP };
+}
+
+/** scope 内长枪局回合数（展示用）；league=赛事总局，team=该队参与的局。 */
+export function radarFieldRoundCount(field: RadarField): number {
+  return field.scope.roundCount;
+}

package/src/replay-clock.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { deriveReplayClock, formatClockSeconds } from "./replay-clock.js";
+
+const round = {
+  freezeEndTick: 1_000,
+  officialEndTick: 10_000,
+  targetEndTick: 10_320,
+  bomb: null,
+};
+
+describe("replay clock", () => {
+  it("以 freeze end 为 1:55，并可定位到 1:35", () => {
+    expect(deriveReplayClock(round, 1_000, 64)).toMatchObject({ phase: "round", secondsRemaining: 115, display: "1:55" });
+    expect(deriveReplayClock(round, 1_000 + 20 * 64, 64)).toMatchObject({ phase: "round", secondsRemaining: 95, display: "1:35" });
+  });
+
+  it("下包后使用实际爆炸时长，缺失爆炸事件时回退 40 秒", () => {
+    const planted = { ...round, bomb: { plantTick: 5_000, explodeTick: 5_000 + 35 * 64, defuseTick: null } };
+    expect(deriveReplayClock(planted, 5_000, 64)).toMatchObject({ phase: "bomb", secondsRemaining: 35, display: "0:35" });
+    expect(deriveReplayClock({ ...planted, bomb: { ...planted.bomb, explodeTick: null } }, 5_000 + 10 * 64, 64))
+      .toMatchObject({ phase: "bomb", secondsRemaining: 30, display: "0:30" });
+  });
+
+  it("官方回合结束后按下一回合 start tick 显示真实赛后间隔", () => {
+    expect(deriveReplayClock(round, 10_000, 64)).toMatchObject({ phase: "round-end", secondsRemaining: 5, display: "0:05" });
+    expect(deriveReplayClock(round, 10_192, 64)).toMatchObject({ phase: "round-end", secondsRemaining: 2, display: "0:02" });
+  });
+
+  it("freeze 阶段显示准备，通用格式不输出裸秒", () => {
+    expect(deriveReplayClock(round, 999, 64)).toMatchObject({ phase: "freeze", secondsRemaining: null, display: "准备" });
+    expect(formatClockSeconds(88)).toBe("1:28");
+  });
+});

package/src/replay-clock.ts

@@ -0,0 +1,61 @@
+export type ReplayClockPhase = "freeze" | "round" | "bomb" | "round-end";
+
+export interface ReplayClockRound {
+  freezeEndTick: number;
+  officialEndTick?: number;
+  targetEndTick?: number;
+  bomb: {
+    plantTick: number;
+    defuseTick: number | null;
+    explodeTick: number | null;
+  } | null;
+}
+
+export interface ReplayClockState {
+  phase: ReplayClockPhase;
+  label: string;
+  secondsRemaining: number | null;
+  display: string;
+}
+
+const STANDARD_ROUND_SECONDS = 115;
+const STANDARD_BOMB_SECONDS = 40;
+
+export function formatClockSeconds(seconds: number): string {
+  const safe = Math.max(0, Math.ceil(seconds));
+  return `${Math.floor(safe / 60)}:${String(safe % 60).padStart(2, "0")}`;
+}
+
+export function deriveReplayClock(
+  round: ReplayClockRound,
+  currentTick: number,
+  tickrate: number,
+): ReplayClockState {
+  const safeTickrate = tickrate > 0 ? tickrate : 64;
+  if (currentTick < round.freezeEndTick) {
+    return { phase: "freeze", label: "准备", secondsRemaining: null, display: "准备" };
+  }
+
+  if (round.officialEndTick != null && currentTick >= round.officialEndTick) {
+    const endTick = round.targetEndTick ?? round.officialEndTick;
+    const secondsRemaining = Math.max(0, (endTick - currentTick) / safeTickrate);
+    return {
+      phase: "round-end",
+      label: "下一回合",
+      secondsRemaining,
+      display: formatClockSeconds(secondsRemaining),
+    };
+  }
+
+  if (round.bomb && currentTick >= round.bomb.plantTick) {
+    const bombDuration = round.bomb.explodeTick != null
+      ? Math.max(0, (round.bomb.explodeTick - round.bomb.plantTick) / safeTickrate)
+      : STANDARD_BOMB_SECONDS;
+    const secondsRemaining = Math.max(0, bombDuration - (currentTick - round.bomb.plantTick) / safeTickrate);
+    return { phase: "bomb", label: "C4", secondsRemaining, display: formatClockSeconds(secondsRemaining) };
+  }
+
+  const secondsRemaining = Math.max(0, STANDARD_ROUND_SECONDS - (currentTick - round.freezeEndTick) / safeTickrate);
+  return { phase: "round", label: "回合", secondsRemaining, display: formatClockSeconds(secondsRemaining) };
+}
+

package/src/season-metrics.ts

@@ -15,6 +15,11 @@ export function round(value: number, digits = 2): number {
   return Math.round(value * factor) / factor;
 }
 
+/** 百分比格式化：null → "—"，否则 `${value.toFixed(digits)}%`。消除 `value == null ? "—" : `${value.toFixed(1)}%`` 的重复模式。 */
+export function formatPercent(value: number | null, digits = 1): string {
+  return value == null ? "—" : `${value.toFixed(digits)}%`;
+}
+
 /** 视图列定义（信息架构来自 RivalHub StatsLeaderboard，去掉 OCR 副指标与独立 Demo tab）。 */
 export const SEASON_STAT_VIEWS: LeaderboardView[] = [
   {