@cs2dak/maps 0.2.0 → 1.0.0

package/src/lineups.ts

@@ -0,0 +1,336 @@
+import type { Vec3 } from "./nav.js";
+
+/** CS2 竞技模式标准回合时长（秒，freeze 结束后）。 */
+const ROUND_DURATION_SECONDS = 115;
+
+export type LineupClusterMode = "loose" | "strict";
+
+type GrenadeClusterKind = "smoke" | "molotov" | "incendiary" | "flashbang" | "he";
+
+export const GRENADE_CLUSTER_PRESETS = {
+  loose: {
+    landingRadius: {
+      smoke: 150,
+      molotov: 180,
+      incendiary: 170,
+      flashbang: 220,
+      he: 220,
+    },
+    originRadius: null,
+  },
+  strict: {
+    landingRadius: {
+      smoke: 96,
+      molotov: 120,
+      incendiary: 112,
+      flashbang: 160,
+      he: 160,
+    },
+    originRadius: {
+      smoke: 64,
+      molotov: 64,
+      incendiary: 64,
+      flashbang: 80,
+      he: 80,
+    },
+  },
+} as const;
+
+export interface LineupPracticePose {
+  position: Vec3;
+  yaw: number;
+  pitch: number;
+}
+
+export interface LineupThrowEvidence {
+  entryId: string;
+  roundNumber: number;
+  tick: number;
+  practicePose?: LineupPracticePose | null;
+}
+
+export interface LineupGrenadeLike {
+  roundNumber: number;
+  grenade: string;
+  throwerIndex: number;
+  throwTick: number;
+  throwPosition: Vec3;
+  effectPosition: Vec3;
+  /** 投掷 tick 的玩家站位/视角，用于生成跑图练习命令。 */
+  practicePose?: LineupPracticePose | null;
+  /** 跨场聚类所需：区分各 demo 的 grenade 来源。 */
+  entryId: string;
+  /** 回合 freezeEndTick，用于计算投掷时间（throwTick - freezeEndTick → 秒）。 */
+  freezeEndTick: number;
+  /** 投掷时 thrower 所在的 callout 名（从 replay placeDict 解析）。 */
+  throwerPlaceName?: string | null;
+  /** 落点/生效点对应的 callout 名（从 3D callout grid 解析）。 */
+  effectCallout?: string | null;
+  /** effectCallout 的多数表决置信度。 */
+  effectCalloutConfidence?: number | null;
+  /** effectCallout 所在格采样数。 */
+  effectCalloutSamples?: number | null;
+  /** thrower 所在方。 */
+  side?: "t" | "ct" | null;
+  /**
+   * thrower 的队伍 key（"teamA" / "teamB"），跨场聚类时替代 throwerTeam 回调。
+   * 单场场景下 throwerTeam 回调也能用，但跨场后 playerIndex 不复跨场有效。
+   */
+  teamKey?: string | null;
+}
+
+export interface LineupCluster {
+  id: string;
+  mapName: string;
+  mode: LineupClusterMode;
+  grenade: string;
+  throwPosition: Vec3;
+  effectPosition: Vec3;
+  count: number;
+  roundNumbers: number[];
+  throwerIndices: number[];
+  /** 聚类成员的投掷证据（demo + 回合 + throwTick），按时间排序；[0] 即最早一次投掷。 */
+  throws: LineupThrowEvidence[];
+  winRatePercent: number | null;
+  /** 跨场记录：哪些 demo 含该 lineup。 */
+  entryIds: string[];
+  /** 跨场涉及的 demo 数（按 entryId 去重）。 */
+  demoCount: number;
+  /** 最高频投掷时间段（10 秒桶，如 "10-20s"），基于 freezeEndTick 偏移。 */
+  throwTimeBucket: string | null;
+  /** 最高频投掷位 callout（从 replay placeDict 取 thrower 位置）。 */
+  throwerPlaceName: string | null;
+  /** 最高频落点 callout（从 3D callout grid 取 effectPosition 位置）。 */
+  effectCallout: string | null;
+  /** 同簇内落点 callout 置信度均值。 */
+  effectCalloutConfidence: number | null;
+  /** 同簇内落点 callout 采样总数。 */
+  effectCalloutSamples: number | null;
+  /** 最高频 side。 */
+  side: "t" | "ct" | null;
+}
+
+export interface BuildLineupClustersOptions {
+  mapName: string;
+  grenades: LineupGrenadeLike[];
+  /** key: `${entryId}:${roundNumber}`，跨场场景下每场 roundNumber 会重复，需加 entryId 前缀。 */
+  roundWinners?: Map<string, string>;
+  throwerTeam?: (throwerIndex: number) => string | null;
+  throwToleranceUnits?: number;
+  effectToleranceUnits?: number;
+  /** strict=固定道具学习；loose=只看大致落点/区域频率。默认 strict。 */
+  mode?: LineupClusterMode;
+  /** tickrate，用于将 freeEndTick 偏移量转换为秒。默认 64。 */
+  tickrate?: number;
+}
+
+/**
+ * 按投掷位置 + 落点位置的空间容差聚类。跨场聚类应由调用方合并
+ * 所有 entry 的 grenades 后单次调用，不可每场各调一次再 flat 拼合。
+ *
+ * throwerPlaceName 通过 replay player track 的 place 字段解析；
+ * effectCallout 来自 Studio 3D callout grid，多数表决后进入簇摘要。
+ */
+export function buildLineupClusters({
+  mapName,
+  grenades,
+  roundWinners,
+  throwerTeam,
+  throwToleranceUnits,
+  effectToleranceUnits,
+  mode = "strict",
+  tickrate = 64
+}: BuildLineupClustersOptions): LineupCluster[] {
+  const clusters: Array<
+    LineupCluster & { wins: number; teamRounds: number }
+  > = [];
+  // 辅助 map：记录 throwTimeBucket 的频次分布，用于取 mode
+  const bucketCounts: Array<Map<string, number>> = [];
+  const placeCounts: Array<Map<string, number>> = [];
+  const effectCalloutCounts: Array<Map<string, number>> = [];
+  const effectCalloutStats: Array<Map<string, { confidenceSum: number; confidenceCount: number; samples: number }>> = [];
+  const sideCounts: Array<Map<string, number>> = [];
+
+  for (const grenade of grenades) {
+    const effectTolerance = effectToleranceUnits ?? landingRadiusFor(mode, grenade.grenade);
+    const throwTolerance = throwToleranceUnits ?? originRadiusFor(mode, grenade.grenade);
+    const existing = clusters.find((cluster) =>
+      cluster.grenade === grenade.grenade &&
+      (throwTolerance == null || distance(cluster.throwPosition, grenade.throwPosition) <= throwTolerance) &&
+      distance(cluster.effectPosition, grenade.effectPosition) <= effectTolerance
+    );
+    const team = throwerTeam?.(grenade.throwerIndex) ?? grenade.teamKey ?? null;
+    const winner = roundWinners?.get(`${grenade.entryId}:${grenade.roundNumber}`) ?? null;
+    const won = team != null && winner === team;
+    const counted = team != null && winner != null;
+    const target = existing ?? {
+      id: `${mapName}:${mode}:${grenade.grenade}:${clusters.length + 1}`,
+      mapName,
+      mode,
+      grenade: grenade.grenade,
+      throwPosition: grenade.throwPosition,
+      effectPosition: grenade.effectPosition,
+      count: 0,
+      roundNumbers: [],
+      throwerIndices: [],
+      throws: [],
+      winRatePercent: null,
+      wins: 0,
+      teamRounds: 0,
+      entryIds: [],
+      demoCount: 0,
+      throwTimeBucket: null,
+      throwerPlaceName: null,
+      effectCallout: null,
+      effectCalloutConfidence: null,
+      effectCalloutSamples: null,
+      side: null,
+    };
+
+    const idx = existing ? clusters.indexOf(existing) : clusters.length;
+    if (!existing) {
+      bucketCounts.push(new Map());
+      placeCounts.push(new Map());
+      effectCalloutCounts.push(new Map());
+      effectCalloutStats.push(new Map());
+      sideCounts.push(new Map());
+    }
+
+    // 基础计数
+    target.count += 1;
+    target.roundNumbers.push(grenade.roundNumber);
+    target.throwerIndices.push(grenade.throwerIndex);
+    target.throws.push({
+      entryId: grenade.entryId,
+      roundNumber: grenade.roundNumber,
+      tick: grenade.throwTick,
+      practicePose: grenade.practicePose ?? null,
+    });
+    target.throwPosition = averagePoint(target.throwPosition, grenade.throwPosition, target.count);
+    target.effectPosition = averagePoint(target.effectPosition, grenade.effectPosition, target.count);
+    if (counted) target.teamRounds += 1;
+    if (won) target.wins += 1;
+
+    // 跨场条目追踪
+    if (!target.entryIds.includes(grenade.entryId)) {
+      target.entryIds.push(grenade.entryId);
+    }
+    target.demoCount = target.entryIds.length;
+
+    // 投掷时间：10 秒桶 → 倒计时（距 freezeEnd 的剩余秒数，CS2 标准 1:55 回合）
+    if (grenade.freezeEndTick > 0) {
+      const secondsSinceFreeze = (grenade.throwTick - grenade.freezeEndTick) / tickrate;
+      if (secondsSinceFreeze >= 0) {
+        const bucketStart = Math.floor(secondsSinceFreeze / 10) * 10;
+        const midpoint = bucketStart + 5; // 桶中值，如 10-20s 桶取 15s
+        const remaining = Math.max(0, ROUND_DURATION_SECONDS - midpoint);
+        const label = `${Math.floor(remaining / 60)}:${String(Math.round(remaining % 60)).padStart(2, "0")}`;
+        const bc = bucketCounts[idx];
+        bc.set(label, (bc.get(label) ?? 0) + 1);
+      }
+    }
+
+    // 投掷位 callout
+    if (grenade.throwerPlaceName) {
+      const pc = placeCounts[idx];
+      pc.set(grenade.throwerPlaceName, (pc.get(grenade.throwerPlaceName) ?? 0) + 1);
+    }
+
+    // 落点 callout
+    if (grenade.effectCallout) {
+      const ec = effectCalloutCounts[idx];
+      ec.set(grenade.effectCallout, (ec.get(grenade.effectCallout) ?? 0) + 1);
+      const statsByCallout = effectCalloutStats[idx];
+      const stats = statsByCallout.get(grenade.effectCallout) ?? { confidenceSum: 0, confidenceCount: 0, samples: 0 };
+      if (typeof grenade.effectCalloutConfidence === "number") {
+        stats.confidenceSum += grenade.effectCalloutConfidence;
+        stats.confidenceCount += 1;
+      }
+      if (typeof grenade.effectCalloutSamples === "number") {
+        stats.samples += grenade.effectCalloutSamples;
+      }
+      statsByCallout.set(grenade.effectCallout, stats);
+    }
+
+    // side
+    if (grenade.side) {
+      const sc = sideCounts[idx];
+      sc.set(grenade.side, (sc.get(grenade.side) ?? 0) + 1);
+    }
+
+    if (!existing) clusters.push(target);
+  }
+
+  return clusters
+    .map((cluster, i) => {
+      const effectCallout = modeOfMap(effectCalloutCounts[i]);
+      const effectStats = effectCallout ? effectCalloutStats[i].get(effectCallout) : undefined;
+      return {
+        ...cluster,
+        roundNumbers: [...new Set(cluster.roundNumbers)].sort((a, b) => a - b),
+        throwerIndices: [...new Set(cluster.throwerIndices)].sort((a, b) => a - b),
+        throws: [...cluster.throws].sort((a, b) =>
+          a.entryId.localeCompare(b.entryId) || a.roundNumber - b.roundNumber || a.tick - b.tick
+        ),
+        winRatePercent: cluster.teamRounds > 0
+          ? Math.round((cluster.wins / cluster.teamRounds) * 1000) / 10
+          : null,
+        entryIds: [...new Set(cluster.entryIds)].sort(),
+        demoCount: new Set(cluster.entryIds).size,
+        throwTimeBucket: modeOfMap(bucketCounts[i]),
+        throwerPlaceName: modeOfMap(placeCounts[i]),
+        effectCallout,
+        effectCalloutConfidence: effectStats && effectStats.confidenceCount > 0
+          ? Math.round((effectStats.confidenceSum / effectStats.confidenceCount) * 1000) / 1000
+          : null,
+        effectCalloutSamples: effectStats && effectStats.samples > 0 ? effectStats.samples : null,
+        side: modeOfMap(sideCounts[i]) as "t" | "ct" | null,
+      };
+    })
+    .sort((a, b) => b.count - a.count || a.grenade.localeCompare(b.grenade));
+}
+
+function distance(a: Vec3, b: Vec3): number {
+  return Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
+}
+
+function grenadeKind(grenade: string): GrenadeClusterKind {
+  const value = grenade.toLowerCase();
+  if (value.includes("smoke")) return "smoke";
+  if (value.includes("molotov")) return "molotov";
+  if (value.includes("incendiary") || value.includes("incgrenade")) return "incendiary";
+  if (value.includes("flash")) return "flashbang";
+  return "he";
+}
+
+function landingRadiusFor(mode: LineupClusterMode, grenade: string): number {
+  return GRENADE_CLUSTER_PRESETS[mode].landingRadius[grenadeKind(grenade)];
+}
+
+function originRadiusFor(mode: LineupClusterMode, grenade: string): number | null {
+  const radius = GRENADE_CLUSTER_PRESETS[mode].originRadius;
+  return radius ? radius[grenadeKind(grenade)] : null;
+}
+
+function averagePoint(current: Vec3, next: Vec3, count: number): Vec3 {
+  if (count <= 1) return next;
+  return {
+    x: current.x + (next.x - current.x) / count,
+    y: current.y + (next.y - current.y) / count,
+    z: current.z + (next.z - current.z) / count,
+  };
+}
+
+/** 取 Map<string, number> 中 value 最大的 key；空 map 返回 null。 */
+function modeOfMap(map: Map<string, number>): string | null {
+  if (map.size === 0) return null;
+  let bestKey: string | null = null;
+  let bestCount = 0;
+  for (const [key, count] of map) {
+    if (count > bestCount) {
+      bestCount = count;
+      bestKey = key;
+    }
+  }
+  return bestKey;
+}

package/src/nav.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { deriveCompactNav, findNavPath, nearestNavArea, type AwpyNav } from "./nav.js";
+
+const source: AwpyNav = {
+  version: 35,
+  sub_version: 1,
+  is_analyzed: true,
+  areas: {
+    1: {
+      area_id: 1,
+      hull_index: 0,
+      dynamic_attribute_flags: 0,
+      corners: [
+        { x: 0, y: 0, z: 0 },
+        { x: 10, y: 0, z: 0 },
+        { x: 10, y: 10, z: 0 },
+        { x: 0, y: 10, z: 0 },
+      ],
+      connections: [2],
+      ladders_above: [],
+      ladders_below: [],
+    },
+    2: {
+      area_id: 2,
+      hull_index: 0,
+      dynamic_attribute_flags: 0,
+      corners: [
+        { x: 10, y: 0, z: 0 },
+        { x: 20, y: 0, z: 0 },
+        { x: 20, y: 10, z: 0 },
+        { x: 10, y: 10, z: 0 },
+      ],
+      connections: [3],
+      ladders_above: [],
+      ladders_below: [],
+    },
+    3: {
+      area_id: 3,
+      hull_index: 0,
+      dynamic_attribute_flags: 0,
+      corners: [
+        { x: 20, y: 0, z: 0 },
+        { x: 30, y: 0, z: 0 },
+        { x: 30, y: 10, z: 0 },
+        { x: 20, y: 10, z: 0 },
+      ],
+      connections: [],
+      ladders_above: [],
+      ladders_below: [],
+    },
+  },
+};
+
+describe("nav graph", () => {
+  it("derives compact areas and follows directed adjacency", () => {
+    const nav = deriveCompactNav("de_test", 123, source);
+    expect(nav.areas).toHaveLength(3);
+    expect(findNavPath(nav, 1, 3)).toEqual([1, 2, 3]);
+    expect(findNavPath(nav, 3, 1)).toEqual([]);
+  });
+
+  it("maps a world point to its containing or nearest nav area", () => {
+    const nav = deriveCompactNav("de_test", 123, source);
+    expect(nearestNavArea(nav, { x: 4, y: 4, z: 2 })?.id).toBe(1);
+    expect(nearestNavArea(nav, { x: 18, y: 5, z: 2 })?.id).toBe(2);
+    expect(nearestNavArea(nav, { x: 34, y: 5, z: 2 })?.id).toBe(3);
+  });
+});

package/src/nav.ts

@@ -0,0 +1,228 @@
+export interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface AwpyNavArea {
+  area_id: number;
+  hull_index: number;
+  dynamic_attribute_flags: number;
+  corners: Vec3[];
+  connections: number[];
+  ladders_above: number[];
+  ladders_below: number[];
+}
+
+export interface AwpyNav {
+  version: number;
+  sub_version: number;
+  is_analyzed: boolean;
+  areas: Record<string | number, AwpyNavArea>;
+}
+
+export interface CompactNavArea {
+  id: number;
+  corners: Vec3[];
+  centroid: Vec3;
+  neighbors: number[];
+}
+
+export interface CompactNav {
+  mapName: string;
+  buildId: number;
+  sourceFormat: {
+    version: number;
+    subVersion: number;
+  };
+  areas: CompactNavArea[];
+}
+
+export function deriveCompactNav(mapName: string, buildId: number, source: AwpyNav): CompactNav {
+  const sourceAreas = Object.values(source.areas);
+  const knownIds = new Set(sourceAreas.map((area) => area.area_id));
+
+  return {
+    mapName,
+    buildId,
+    sourceFormat: {
+      version: source.version,
+      subVersion: source.sub_version,
+    },
+    areas: sourceAreas.map((area) => ({
+      id: area.area_id,
+      corners: area.corners,
+      centroid: centroid(area.corners),
+      neighbors: [...new Set(area.connections)].filter((id) => knownIds.has(id)),
+    })),
+  };
+}
+
+export function findNavPath(nav: CompactNav, startId: number, endId: number): number[] {
+  if (startId === endId) return nav.areas.some((area) => area.id === startId) ? [startId] : [];
+
+  const byId = new Map(nav.areas.map((area) => [area.id, area]));
+  if (!byId.has(startId) || !byId.has(endId)) return [];
+
+  const queue = [startId];
+  const previous = new Map<number, number | null>([[startId, null]]);
+
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    const current = queue[cursor]!;
+    for (const neighbor of byId.get(current)!.neighbors) {
+      if (previous.has(neighbor)) continue;
+      previous.set(neighbor, current);
+      if (neighbor === endId) return reconstructPath(previous, endId);
+      queue.push(neighbor);
+    }
+  }
+
+  return [];
+}
+
+export function nearestNavArea(nav: CompactNav, point: Vec3): CompactNavArea | undefined {
+  let bestContaining: CompactNavArea | undefined;
+  let bestContainingZ = Number.POSITIVE_INFINITY;
+
+  for (const area of nav.areas) {
+    if (!pointInPolygon(point, area.corners)) continue;
+    const zDistance = Math.abs(point.z - area.centroid.z);
+    if (zDistance < bestContainingZ) {
+      bestContaining = area;
+      bestContainingZ = zDistance;
+    }
+  }
+  if (bestContaining) return bestContaining;
+
+  let nearest: CompactNavArea | undefined;
+  let nearestDistance = Number.POSITIVE_INFINITY;
+  for (const area of nav.areas) {
+    const distance = squaredDistance(point, area.centroid);
+    if (distance < nearestDistance) {
+      nearest = area;
+      nearestDistance = distance;
+    }
+  }
+  return nearest;
+}
+
+export interface NavZCluster {
+  min: number;
+  max: number;
+  median: number;
+  count: number;
+}
+
+export interface NavZSample {
+  /** 落在 polygon 内的 nav area Z 质心列表（已排序）。 */
+  zValues: number[];
+  min: number;
+  max: number;
+  median: number;
+  /**
+   * 按 Z 间距自动分组的簇（默认间距阈值 50 units）。
+   * 相邻簇之间的间隙就是 zMin/zMax 边界的自然分割点。
+   * 单层区域通常只有 1 个簇；Hut/HutRoof 这类重叠区域会出现 2 个簇。
+   */
+  clusters: NavZCluster[];
+}
+
+/**
+ * 采样 XY polygon 内所有 nav area 的 Z 质心，返回分布统计。
+ *
+ * polygon 使用世界坐标 XY（与 MapZone.polygon 同系）。
+ * 返回 null 表示 polygon 内无 nav area 覆盖（坐标系不匹配或地图未标定）。
+ *
+ * 用途：标定重叠 callout 的 zMin/zMax 时，查看 clusters 找到簇间间隙，
+ * 把间隙中点作为边界值填入 MapZone。不要用 median 直接作为 zMin/zMax。
+ */
+export function sampleNavZ(
+  nav: CompactNav,
+  polygon: Array<[number, number]>,
+  clusterGapThreshold = 50,
+  zFilter?: { zMin?: number; zMax?: number },
+): NavZSample | null {
+  const zValues: number[] = [];
+  for (const area of nav.areas) {
+    const { x, y, z } = area.centroid;
+    if (zFilter?.zMin !== undefined && z < zFilter.zMin) continue;
+    if (zFilter?.zMax !== undefined && z > zFilter.zMax) continue;
+    if (pointInPolygon2d(x, y, polygon)) zValues.push(z);
+  }
+  if (zValues.length === 0) return null;
+  zValues.sort((a, b) => a - b);
+
+  const min = zValues[0]!;
+  const max = zValues[zValues.length - 1]!;
+  const median = zValues[Math.floor(zValues.length / 2)]!;
+  return { zValues, min, max, median, clusters: detectClusters(zValues, clusterGapThreshold) };
+}
+
+function pointInPolygon2d(x: number, y: number, polygon: Array<[number, number]>): boolean {
+  let inside = false;
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i, i += 1) {
+    const [xi, yi] = polygon[i]!;
+    const [xj, yj] = polygon[j]!;
+    if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) inside = !inside;
+  }
+  return inside;
+}
+
+function detectClusters(sortedZ: number[], gapThreshold: number): NavZCluster[] {
+  if (sortedZ.length === 0) return [];
+  const clusters: NavZCluster[] = [];
+  let start = 0;
+  for (let i = 1; i <= sortedZ.length; i += 1) {
+    if (i < sortedZ.length && sortedZ[i]! - sortedZ[i - 1]! <= gapThreshold) continue;
+    const slice = sortedZ.slice(start, i);
+    clusters.push({
+      min: slice[0]!,
+      max: slice[slice.length - 1]!,
+      median: slice[Math.floor(slice.length / 2)]!,
+      count: slice.length,
+    });
+    start = i;
+  }
+  return clusters;
+}
+
+function centroid(points: Vec3[]): Vec3 {
+  if (points.length === 0) return { x: 0, y: 0, z: 0 };
+  const total = points.reduce(
+    (sum, point) => ({ x: sum.x + point.x, y: sum.y + point.y, z: sum.z + point.z }),
+    { x: 0, y: 0, z: 0 },
+  );
+  return {
+    x: total.x / points.length,
+    y: total.y / points.length,
+    z: total.z / points.length,
+  };
+}
+
+function pointInPolygon(point: Vec3, polygon: Vec3[]): boolean {
+  let inside = false;
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i, i += 1) {
+    const current = polygon[i]!;
+    const previous = polygon[j]!;
+    const crosses =
+      current.y > point.y !== previous.y > point.y &&
+      point.x <
+        ((previous.x - current.x) * (point.y - current.y)) / (previous.y - current.y) + current.x;
+    if (crosses) inside = !inside;
+  }
+  return inside;
+}
+
+function squaredDistance(a: Vec3, b: Vec3): number {
+  return (a.x - b.x) ** 2 + (a.y - b.y) ** 2 + (a.z - b.z) ** 2;
+}
+
+function reconstructPath(previous: Map<number, number | null>, endId: number): number[] {
+  const path: number[] = [];
+  let current: number | null = endId;
+  while (current !== null) {
+    path.push(current);
+    current = previous.get(current) ?? null;
+  }
+  return path.reverse();
+}

package/src/position-candidates.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { generateMapPositionCandidates, materializeReviewedPositionAsset } from "./position-candidates.js";
+
+const rows = [1, 2].map((roundNumber) => ({ matchId: "m1", mapName: "de_inferno", roundNumber, teamKey: "teamA", side: "t" as const, playerIndex: 0, steamId64: "p1", openingEligibleSeconds: 20, openingPositionGroupDwell: [{ positionGroupId: "banana", seconds: 16, share: 0.8 }], openingPath: [{ tick: 100, callout: "Banana", positionGroupId: "banana", x: 1, y: 2, z: 3 }] }));
+
+describe("map position candidates", () => {
+  it("generates deterministic candidates and materializes reviewed assets with provenance", () => {
+    const first = generateMapPositionCandidates(rows); const second = generateMapPositionCandidates([...rows].reverse());
+    expect(first).toEqual(second);
+    expect(first[0]).toMatchObject({ proposedId: "banana", proposedDisplayName: "香蕉道", sampleCount: 2 });
+    const asset = materializeReviewedPositionAsset(first, [{ candidateId: first[0]!.id, action: "rename", displayName: "香蕉道默认" }], { mapName: "de_inferno", side: "t", reviewedAt: "2026-07-14T00:00:00.000Z", reviewer: "test" });
+    expect(asset.groups[0]).toMatchObject({ id: "banana", name: "香蕉道默认", callouts: ["Banana"] });
+    expect(asset.provenance.decisions).toHaveLength(1);
+  });
+
+  it("keeps unresolved candidates unresolved without guessing a name", () => {
+    const candidates = generateMapPositionCandidates([{ ...rows[0]!, openingPositionGroupDwell: [], openingPath: [] }]);
+    expect(candidates[0]).toMatchObject({ type: "unresolved", proposedDisplayName: "未命名候选" });
+    expect(materializeReviewedPositionAsset(candidates, [], { mapName: "de_inferno", side: "t", reviewedAt: "2026-07-14T00:00:00.000Z", reviewer: "test" }).unresolvedCandidateIds).toEqual([candidates[0]!.id]);
+  });
+
+  it("separates deterministic unknown spatial clusters and classifies transit paths without naming them", () => {
+    const unknown = [
+      { ...rows[0]!, roundNumber: 1, openingPositionGroupDwell: [], openingPath: [{ tick: 100, callout: null, positionGroupId: null, x: 0, y: 0, z: 0 }, { tick: 200, callout: null, positionGroupId: null, x: 50, y: 40, z: 0 }] },
+      { ...rows[0]!, roundNumber: 2, openingPositionGroupDwell: [], openingPath: [{ tick: 100, callout: null, positionGroupId: null, x: 10, y: 10, z: 0 }, { tick: 200, callout: null, positionGroupId: null, x: 60, y: 50, z: 0 }] },
+      { ...rows[0]!, roundNumber: 3, openingPositionGroupDwell: [], openingPath: [{ tick: 100, callout: null, positionGroupId: null, x: 1600, y: 0, z: 0 }, { tick: 200, callout: null, positionGroupId: null, x: 1660, y: 20, z: 0 }] },
+      { ...rows[0]!, roundNumber: 4, openingPositionGroupDwell: [], openingPath: [{ tick: 100, callout: "A", positionGroupId: null, x: 0, y: 0, z: 0 }, { tick: 200, callout: "B", positionGroupId: null, x: 1200, y: 0, z: 0 }] },
+    ];
+    const candidates = generateMapPositionCandidates(unknown);
+    expect(candidates.filter((candidate) => candidate.type === "stable_spatial_position")).toHaveLength(1);
+    expect(candidates.some((candidate) => candidate.type === "transit")).toBe(true);
+    expect(new Set(candidates.map((candidate) => candidate.proposedId)).size).toBe(candidates.length);
+    expect(candidates.every((candidate) => candidate.proposedDisplayName === "未命名候选")).toBe(true);
+  });
+
+  it("keeps semantic candidate ids stable when unrelated candidates are added", () => {
+    const base = generateMapPositionCandidates(rows);
+    const extended = generateMapPositionCandidates([...rows, { ...rows[0]!, playerIndex: 9, steamId64: "p9", openingPositionGroupDwell: [{ positionGroupId: "alt", seconds: 16, share: 0.8 }], openingPath: [{ tick: 100, callout: "Alt", positionGroupId: "alt", x: 900, y: 2, z: 3 }] }]);
+    expect(extended.find((candidate) => candidate.proposedId === "banana")?.id).toBe(base.find((candidate) => candidate.proposedId === "banana")?.id);
+  });
+
+  it("materializes a reviewer-specified split as independently reviewable children", () => {
+    const input = [
+      { ...rows[0]!, roundNumber: 1 },
+      { ...rows[0]!, roundNumber: 2 },
+      { ...rows[0]!, roundNumber: 3 },
+    ];
+    const candidate = generateMapPositionCandidates(input)[0]!;
+    const groups = candidate.representativeEvidence.map((evidence, index) => ({ id: index === 0 ? "left" : "right", evidence: [evidence] }));
+    const asset = materializeReviewedPositionAsset([candidate], [{ candidateId: candidate.id, action: "split", splitGroups: [groups[0]!, { id: "right", evidence: groups.slice(1).flatMap((group) => group.evidence) }] }], { mapName: "de_inferno", side: "t", reviewedAt: "2026-07-14T00:00:00.000Z", reviewer: "test" });
+    expect(asset.splitCandidates).toHaveLength(2);
+    expect(asset.splitCandidates.every((child) => child.parentCandidateId === candidate.id)).toBe(true);
+    expect(asset.unresolvedCandidateIds).toEqual(asset.splitCandidates.map((child) => child.id).sort());
+    expect(() => materializeReviewedPositionAsset([candidate], [{ candidateId: candidate.id, action: "split" }], { mapName: "de_inferno", side: "t", reviewedAt: "2026-07-14T00:00:00.000Z", reviewer: "test" })).toThrow("至少需要两个");
+  });
+
+  it("surfaces legacy review ids that no longer match stable candidates", () => {
+    const candidate = generateMapPositionCandidates(rows)[0]!;
+    const asset = materializeReviewedPositionAsset([candidate], [{ candidateId: "de_inferno:t:001", action: "rename", displayName: "旧编号" }], { mapName: "de_inferno", side: "t", reviewedAt: "2026-07-14T00:00:00.000Z", reviewer: "test" });
+    expect(asset.unmatchedDecisionIds).toEqual(["de_inferno:t:001"]);
+  });
+});