@cs2dak/maps 0.2.1 → 1.0.0

package/src/position-candidates.ts

@@ -0,0 +1,183 @@
+import { positionGroupDisplay } from "./default-positions.js";
+
+export const MAP_POSITION_CANDIDATE_VERSION = 3;
+export type PositionCandidateType = "stable_spatial_position" | "responsibility_group" | "opening_action" | "transit" | "unresolved" | "unclassifiable";
+export type PositionCandidateReviewAction = "keep" | "rename" | "merge" | "split" | "opening_action" | "transit" | "unclassifiable" | "unresolved";
+
+export interface OpeningPositionCandidateInput {
+  matchId: string; mapName: string; roundNumber: number; teamKey: string; side: "t" | "ct"; playerIndex: number; steamId64: string;
+  openingEligibleSeconds: number | null;
+  openingMeanComponentSize?: number | null;
+  openingIsolationSeconds?: number | null;
+  openingPositionGroupDwell: Array<{ positionGroupId: string; seconds: number; share: number }>;
+  openingPath: Array<{ tick: number; callout: string | null; positionGroupId: string | null; x: number; y: number; z: number }>;
+}
+
+export interface MapPositionCandidate {
+  version: typeof MAP_POSITION_CANDIDATE_VERSION; id: string; parentCandidateId?: string; mapName: string; side: "t" | "ct"; type: PositionCandidateType;
+  proposedId: string; proposedDisplayName: string; callouts: string[];
+  trajectorySummary: { start: { x: number; y: number; z: number } | null; end: { x: number; y: number; z: number } | null; dwellSeconds: number; pathSamples: number };
+  sampleCount: number; teamCount: number; playerCount: number; assignmentStability: number | null; overlap: number | null;
+  teamKeys: string[];
+  componentSummary: { meanOpeningComponentSize: number | null; isolatedShare: number | null };
+  representativeEvidence: Array<{ matchId: string; roundNumber: number; playerIndex: number }>;
+  confidence: number; limitations: string[];
+}
+
+function rounded(value: number): number { return Number(value.toFixed(3)); }
+
+function stableHash(value: string): string {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) { hash ^= value.charCodeAt(index); hash = Math.imul(hash, 16777619); }
+  return (hash >>> 0).toString(36);
+}
+
+function evidenceKey(value: { matchId: string; roundNumber: number; playerIndex: number }): string {
+  return `${value.matchId}:${value.roundNumber}:${value.playerIndex}`;
+}
+
+function distance(first: { x: number; y: number; z: number }, second: { x: number; y: number; z: number }): number {
+  return Math.hypot(first.x - second.x, first.y - second.y, first.z - second.z);
+}
+
+function pathClass(row: OpeningPositionCandidateInput): "stationary" | "opening_action" | "transit" | "no_path" {
+  const start = row.openingPath[0];
+  const end = row.openingPath.at(-1);
+  if (!start || !end) return "no_path";
+  const displacement = distance(start, end);
+  if (displacement >= 900) return "transit";
+  if (displacement >= 400 && new Set(row.openingPath.map((point) => point.callout).filter(Boolean)).size >= 2) return "opening_action";
+  return "stationary";
+}
+
+function unresolvedSpatialKey(row: OpeningPositionCandidateInput): string {
+  const point = row.openingPath.at(-1) ?? row.openingPath[0];
+  if (!point) return "no_path";
+  return [pathClass(row), Math.round(point.x / 384), Math.round(point.y / 384), Math.round(point.z / 192)].join(":");
+}
+
+function meanPoint(points: Array<{ x: number; y: number; z: number }>): { x: number; y: number; z: number } | null {
+  if (points.length === 0) return null;
+  return {
+    x: rounded(points.reduce((sum, point) => sum + point.x, 0) / points.length),
+    y: rounded(points.reduce((sum, point) => sum + point.y, 0) / points.length),
+    z: rounded(points.reduce((sum, point) => sum + point.z, 0) / points.length),
+  };
+}
+
+export function generateMapPositionCandidates(rows: OpeningPositionCandidateInput[]): MapPositionCandidate[] {
+  const groups = new Map<string, Array<{ row: OpeningPositionCandidateInput; dwell: OpeningPositionCandidateInput["openingPositionGroupDwell"][number] | null }>>();
+  for (const row of rows) {
+    const dwell = row.openingPositionGroupDwell.length ? [...row.openingPositionGroupDwell].sort((a, b) => b.seconds - a.seconds || a.positionGroupId.localeCompare(b.positionGroupId))[0]! : null;
+    const groupId = dwell?.positionGroupId ?? `unresolved:${unresolvedSpatialKey(row)}`;
+    const key = `${row.mapName}\t${row.side}\t${groupId}`;
+    groups.set(key, [...(groups.get(key) ?? []), { row, dwell }]);
+  }
+  return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([key, items]) => {
+    items.sort((a, b) => a.row.matchId.localeCompare(b.row.matchId) || a.row.roundNumber - b.row.roundNumber || a.row.playerIndex - b.row.playerIndex);
+    const [mapName, side, groupId] = key.split("\t") as [string, "t" | "ct", string];
+    const unresolved = groupId.startsWith("unresolved:");
+    const display = unresolved ? { resolved: false, displayName: "未命名候选", officialName: null } : positionGroupDisplay(mapName, side, groupId);
+    const paths = items.flatMap((item) => item.row.openingPath);
+    const shares = items.map((item) => item.dwell?.share ?? 0);
+    const endPoints = items.map((item) => item.row.openingPath.at(-1)).filter((point): point is NonNullable<typeof point> => point != null);
+    const center = meanPoint(endPoints);
+    const spatialStability = center && endPoints.length ? rounded(Math.max(0, 1 - endPoints.reduce((sum, point) => sum + distance(point, center), 0) / endPoints.length / 600)) : null;
+    const assignmentStability = unresolved ? spatialStability : shares.length ? rounded(shares.reduce((sum, value) => sum + value, 0) / shares.length) : null;
+    const roundAssignments = new Map<string, number>();
+    for (const item of items) {
+      const roundKey = `${item.row.matchId}:${item.row.roundNumber}:${item.row.teamKey}`;
+      roundAssignments.set(roundKey, (roundAssignments.get(roundKey) ?? 0) + 1);
+    }
+    const overlap = roundAssignments.size ? rounded([...roundAssignments.values()].filter((count) => count > 1).length / roundAssignments.size) : null;
+    const motion = pathClass(items[0]!.row);
+    const type: PositionCandidateType = unresolved
+      ? motion === "transit" ? "transit" : motion === "opening_action" ? "opening_action" : (assignmentStability ?? 0) >= 0.55 && items.length >= 2 ? "stable_spatial_position" : "unresolved"
+      : (assignmentStability ?? 0) >= 0.55 ? "stable_spatial_position" : "responsibility_group";
+    const starts = items.map((item) => item.row.openingPath[0]).filter((point): point is NonNullable<typeof point> => point != null);
+    const openingSeconds = items.reduce((sum, item) => sum + (item.row.openingEligibleSeconds ?? 0), 0);
+    const isolatedSeconds = items.reduce((sum, item) => sum + (item.row.openingIsolationSeconds ?? 0), 0);
+    const componentValues = items.map((item) => item.row.openingMeanComponentSize).filter((value): value is number => value != null);
+    const semanticKey = [MAP_POSITION_CANDIDATE_VERSION, mapName, side, type, groupId, motion, ...items.map((item) => `${evidenceKey(item.row)}:${Math.round((item.row.openingPath.at(-1)?.x ?? 0) / 64)}:${Math.round((item.row.openingPath.at(-1)?.y ?? 0) / 64)}:${Math.round((item.row.openingPath.at(-1)?.z ?? 0) / 32)}`)].join("|");
+    const stableId = `${mapName}:${side}:${type}:${stableHash(semanticKey)}`;
+    return {
+      version: MAP_POSITION_CANDIDATE_VERSION, id: stableId, mapName, side, type,
+      proposedId: unresolved ? `${side}_candidate_${stableHash(semanticKey)}` : groupId,
+      proposedDisplayName: display.resolved ? display.displayName : "未命名候选",
+      callouts: [...new Set(paths.map((point) => point.callout).filter((value): value is string => value != null))].sort(),
+      trajectorySummary: { start: meanPoint(starts), end: meanPoint(endPoints), dwellSeconds: rounded(items.reduce((sum, item) => sum + (item.dwell?.seconds ?? (motion === "stationary" ? item.row.openingEligibleSeconds ?? 0 : 0)), 0)), pathSamples: paths.length },
+      sampleCount: new Set(items.map((item) => `${item.row.matchId}:${item.row.roundNumber}`)).size,
+      teamCount: new Set(items.map((item) => `${item.row.matchId}:${item.row.teamKey}`)).size,
+      playerCount: new Set(items.map((item) => item.row.steamId64)).size,
+      teamKeys: [...new Set(items.map((item) => item.row.teamKey))].sort(),
+      componentSummary: { meanOpeningComponentSize: componentValues.length ? rounded(componentValues.reduce((sum, value) => sum + value, 0) / componentValues.length) : null, isolatedShare: openingSeconds > 0 ? rounded(isolatedSeconds / openingSeconds) : null },
+      assignmentStability, overlap,
+      representativeEvidence: items.slice(0, 5).map((item) => ({ matchId: item.row.matchId, roundNumber: item.row.roundNumber, playerIndex: item.row.playerIndex })),
+      confidence: rounded(Math.min(1, items.length / 20) * (assignmentStability ?? 0.25) * (1 - (overlap ?? 0))),
+      limitations: [...(paths.length === 0 ? ["缺少 opening path/coordinates。"] : []), ...(unresolved ? ["无法从当前地图资产解析 position group；候选名称保持未命名，需审阅后才能写入资产。"] : [])],
+    };
+  });
+}
+
+export interface PositionCandidateSplitGroup { id: string; evidence: Array<{ matchId: string; roundNumber: number; playerIndex: number }>; displayName?: string }
+export interface PositionCandidateReview { candidateId: string; action: PositionCandidateReviewAction; displayName?: string; targetId?: string; note?: string; splitGroups?: PositionCandidateSplitGroup[] }
+export interface ReviewedPositionAsset { version: 3; mapName: string; side: "t" | "ct"; groups: Array<{ id: string; name: string; callouts: string[] }>; unresolvedCandidateIds: string[]; splitCandidates: MapPositionCandidate[]; unmatchedDecisionIds: string[]; provenance: { candidateVersion: number; reviewedAt: string; reviewer: string; decisions: PositionCandidateReview[] } }
+
+function splitChildren(candidate: MapPositionCandidate, decision: PositionCandidateReview): MapPositionCandidate[] {
+  const groups = decision.splitGroups;
+  if (!groups || groups.length < 2) throw new Error(`候选 ${candidate.id} 的 split 至少需要两个具名 evidence 分组。`);
+  const parentEvidence = new Set(candidate.representativeEvidence.map(evidenceKey));
+  const seen = new Set<string>();
+  for (const group of groups) {
+    if (!group.id.trim() || group.evidence.length === 0) throw new Error(`候选 ${candidate.id} 的 split 分组必须提供名称和 evidence。`);
+    for (const evidence of group.evidence) {
+      const key = evidenceKey(evidence);
+      if (!parentEvidence.has(key) || seen.has(key)) throw new Error(`候选 ${candidate.id} 的 split evidence 必须来自父候选且不可重复。`);
+      seen.add(key);
+    }
+  }
+  if (seen.size !== parentEvidence.size) throw new Error(`候选 ${candidate.id} 的 split 必须明确分配全部代表 evidence。`);
+  return groups.map((group) => {
+    const members = [...group.evidence].sort((a, b) => evidenceKey(a).localeCompare(evidenceKey(b)));
+    const childId = `${candidate.id}:split:${stableHash([candidate.id, group.id, ...members.map(evidenceKey)].join("|"))}`;
+    return {
+      ...candidate,
+      id: childId,
+      parentCandidateId: candidate.id,
+      proposedId: `${candidate.proposedId}_${group.id}`,
+      proposedDisplayName: group.displayName?.trim() || "未命名候选",
+      representativeEvidence: members,
+      sampleCount: new Set(members.map((item) => `${item.matchId}:${item.roundNumber}`)).size,
+      playerCount: new Set(members.map((item) => item.playerIndex)).size,
+      confidence: rounded(Math.min(candidate.confidence, members.length / Math.max(candidate.representativeEvidence.length, 1))),
+      limitations: [...candidate.limitations, "由人工 split 审阅产生；名称和归类仍需独立确认。"],
+    };
+  });
+}
+
+export function materializeReviewedPositionAsset(candidates: MapPositionCandidate[], decisions: PositionCandidateReview[], input: { mapName: string; side: "t" | "ct"; reviewedAt: string; reviewer: string }): ReviewedPositionAsset {
+  const decisionById = new Map(decisions.map((decision) => [decision.candidateId, decision]));
+  const groups = new Map<string, { id: string; name: string; callouts: Set<string> }>();
+  const unresolvedCandidateIds: string[] = [];
+  const splitCandidates: MapPositionCandidate[] = [];
+  const matchedDecisionIds = new Set<string>();
+  for (const candidate of candidates.filter((row) => row.mapName === input.mapName && row.side === input.side)) {
+    const decision = decisionById.get(candidate.id) ?? { candidateId: candidate.id, action: "unresolved" as const };
+    if (decisionById.has(candidate.id)) matchedDecisionIds.add(candidate.id);
+    if (decision.action === "split") {
+      const children = splitChildren(candidate, decision);
+      splitCandidates.push(...children);
+      unresolvedCandidateIds.push(...children.map((child) => child.id));
+      continue;
+    }
+    if (["unresolved", "unclassifiable", "opening_action", "transit"].includes(decision.action)) { unresolvedCandidateIds.push(candidate.id); continue; }
+    const id = decision.action === "merge" ? decision.targetId : candidate.proposedId;
+    if (!id) { unresolvedCandidateIds.push(candidate.id); continue; }
+    const current = groups.get(id) ?? { id, name: decision.displayName ?? candidate.proposedDisplayName, callouts: new Set<string>() };
+    if (decision.action === "rename" && decision.displayName) current.name = decision.displayName;
+    for (const callout of candidate.callouts) current.callouts.add(callout);
+    groups.set(id, current);
+  }
+  const unmatchedDecisionIds = decisions.filter((decision) => !matchedDecisionIds.has(decision.candidateId)).map((decision) => decision.candidateId).sort();
+  return { version: 3, mapName: input.mapName, side: input.side, groups: [...groups.values()].map((group) => ({ ...group, callouts: [...group.callouts].sort() })).sort((a, b) => a.id.localeCompare(b.id)), unresolvedCandidateIds: unresolvedCandidateIds.sort(), splitCandidates: splitCandidates.sort((a, b) => a.id.localeCompare(b.id)), unmatchedDecisionIds, provenance: { candidateVersion: MAP_POSITION_CANDIDATE_VERSION, reviewedAt: input.reviewedAt, reviewer: input.reviewer, decisions: [...decisions].sort((a, b) => a.candidateId.localeCompare(b.candidateId)) } };
+}

package/src/radar-grid.ts

@@ -0,0 +1,66 @@
+/**
+ * 雷达场栅格 —— 由地图 nav 决定的确定性规则栅格（不由 demo 决定）。
+ *
+ * 同一地图任意 demo 算出同一套格、同序、同 index，所以两场场可逐元素相加/相减。
+ * 格 = 把 nav area 质心按 cellSize 桶进规则格，只保留含 ≥1 质心的「可行走格」（稀疏）。
+ * 每格代表点取桶内质心均值；z 不加靶高（靶高由 core 计算 LOS 时统一加，避免双份常量漂移）。
+ */
+import type { Vec3 } from "./nav.js";
+import { getMapNav } from "./geometry-assets.js";
+
+/** 默认格边长（世界单位）。callout-grid 是 10u 更细；覆盖场用 128u 控制格数 ~300。 */
+export const RADAR_FIELD_CELL_SIZE = 128;
+
+/** world→radar 标定版本；MAP_CALIBRATIONS 变动时手动 +1，使旧缓存场失效。 */
+export const MAP_CALIBRATION_VERSION = "1";
+
+export interface RadarFieldGridIndex {
+  cellSize: number;
+  /** 每格代表世界坐标 [x, y, z]，与 fields 列同序。 */
+  cells: Array<[number, number, number]>;
+  /** "gx,gy" → 列 index；compute 用玩家落点查所属格。 */
+  keyToIndex: Map<string, number>;
+}
+
+function cellKey(x: number, y: number, cellSize: number): string {
+  return `${Math.floor(x / cellSize)},${Math.floor(y / cellSize)}`;
+}
+
+/**
+ * 构建某图的雷达场栅格；无 nav 资产时返回 null（调用方降级）。
+ * 结果对同一 (mapName, cellSize) 完全确定，可安全用于跨场合并。
+ */
+export function buildRadarFieldGrid(
+  mapName: string,
+  cellSize: number = RADAR_FIELD_CELL_SIZE
+): RadarFieldGridIndex | null {
+  const nav = getMapNav(mapName);
+  if (!nav || nav.areas.length === 0) return null;
+
+  const acc = new Map<string, { x: number; y: number; z: number; n: number }>();
+  for (const area of nav.areas) {
+    const c: Vec3 = area.centroid;
+    const key = cellKey(c.x, c.y, cellSize);
+    const e = acc.get(key) ?? { x: 0, y: 0, z: 0, n: 0 };
+    e.x += c.x;
+    e.y += c.y;
+    e.z += c.z;
+    e.n += 1;
+    acc.set(key, e);
+  }
+
+  // 按 key 排序保证列序确定（跨场、跨进程一致）。
+  const sorted = [...acc.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1));
+  const cells: Array<[number, number, number]> = sorted.map(([, e]) => [
+    e.x / e.n,
+    e.y / e.n,
+    e.z / e.n,
+  ]);
+  const keyToIndex = new Map(sorted.map(([key], i) => [key, i]));
+  return { cellSize, cells, keyToIndex };
+}
+
+/** 玩家世界坐标 → 所属格列 index；不在任何可行走格内时 -1。 */
+export function radarFieldCellAt(grid: RadarFieldGridIndex, x: number, y: number): number {
+  return grid.keyToIndex.get(cellKey(x, y, grid.cellSize)) ?? -1;
+}

package/src/route-assets.test.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { CALLOUT_DICT } from "./callout-names.js";
+import { getMapRoutes, MAP_ROUTE_ASSETS } from "./route-assets.js";
+import { ACTIVE_DUTY_MAPS } from "./zones.js";
+import type { MapRoute, MapRoutes } from "./routes.js";
+
+const ROUTE_TYPES = new Set([
+  "primary_entry",
+  "secondary_entry",
+  "mid_connector",
+  "lurk_lane",
+  "rotation_cut",
+]);
+const ROUTE_CONFIDENCE = new Set(["high", "medium", "low"]);
+
+function loadRoutes(mapName: string): MapRoutes {
+  const path = fileURLToPath(new URL(`../map-routes/${mapName}.json`, import.meta.url));
+  return JSON.parse(readFileSync(path, "utf8")) as MapRoutes;
+}
+
+function expectedBombsite(route: MapRoute): string {
+  return route.bombsite === "a" ? "BombsiteA" : "BombsiteB";
+}
+
+describe("map route assets", () => {
+  it("route zones 不重复维护中文名", () => {
+    for (const [map, routes] of Object.entries(MAP_ROUTE_ASSETS)) {
+      const table = CALLOUT_DICT[map] ?? {};
+      for (const route of routes.routes) {
+        for (const zone of route.zones) {
+          expect("nameCn" in zone).toBe(false);
+          expect(table[zone.id] ?? zone.id).toBeTruthy();
+        }
+      }
+    }
+  });
+
+  it("provides at least one confirmed route for every active duty map", () => {
+    for (const mapName of ACTIVE_DUTY_MAPS) {
+      expect(loadRoutes(mapName).routes, mapName).not.toHaveLength(0);
+    }
+  });
+
+  it("exposes confirmed Dust2 routes through the public route asset helper", () => {
+    const dust2 = getMapRoutes("de_dust2");
+    expect(dust2?.mapName).toBe("de_dust2");
+    // 标注工具可继续新增动线，故只断言 4 条已确认动线存在（不做精确等于，避免脆断）。
+    expect(dust2?.routes.map((route) => route.id)).toEqual(
+      expect.arrayContaining(["a_long", "a_short", "b_tunnels", "b_mid_lower"]),
+    );
+    expect(getMapRoutes("de_cache")).toBeNull();
+  });
+
+  it("keeps route metadata and callout references internally consistent", () => {
+    for (const mapName of ACTIVE_DUTY_MAPS) {
+      const asset = loadRoutes(mapName);
+      const callouts = CALLOUT_DICT[mapName];
+      const ids = asset.routes.map((route) => route.id);
+
+      expect(asset.mapName).toBe(mapName);
+      expect(new Set(ids).size, `${mapName} route ids`).toBe(ids.length);
+
+      for (const route of asset.routes) {
+        const zoneIds = route.zones.map((zone) => zone.id);
+
+        expect(ROUTE_TYPES.has(route.type), `${mapName}/${route.id} type`).toBe(true);
+        expect(ROUTE_CONFIDENCE.has(route.confidence), `${mapName}/${route.id} confidence`).toBe(true);
+        expect(zoneIds[0], `${mapName}/${route.id} start`).toBe("TSpawn");
+        expect(zoneIds.at(-1), `${mapName}/${route.id} end`).toBe(expectedBombsite(route));
+        expect(new Set(zoneIds).size, `${mapName}/${route.id} repeated zones`).toBe(zoneIds.length);
+
+        for (const zone of route.zones) {
+          expect(zone.id in callouts, `${mapName}/${route.id}/${zone.id}`).toBe(true);
+        }
+      }
+    }
+  });
+});

package/src/route-assets.ts

@@ -0,0 +1,23 @@
+import ancientRoutes from "../map-routes/de_ancient.json" with { type: "json" };
+import anubisRoutes from "../map-routes/de_anubis.json" with { type: "json" };
+import dust2Routes from "../map-routes/de_dust2.json" with { type: "json" };
+import infernoRoutes from "../map-routes/de_inferno.json" with { type: "json" };
+import mirageRoutes from "../map-routes/de_mirage.json" with { type: "json" };
+import nukeRoutes from "../map-routes/de_nuke.json" with { type: "json" };
+import overpassRoutes from "../map-routes/de_overpass.json" with { type: "json" };
+import type { MapRoutes } from "./routes.js";
+import type { ActiveDutyMap } from "./zones.js";
+
+export const MAP_ROUTE_ASSETS: Record<ActiveDutyMap, MapRoutes> = {
+  de_ancient: ancientRoutes as MapRoutes,
+  de_anubis: anubisRoutes as MapRoutes,
+  de_dust2: dust2Routes as MapRoutes,
+  de_inferno: infernoRoutes as MapRoutes,
+  de_mirage: mirageRoutes as MapRoutes,
+  de_nuke: nukeRoutes as MapRoutes,
+  de_overpass: overpassRoutes as MapRoutes,
+};
+
+export function getMapRoutes(mapName: string): MapRoutes | null {
+  return (MAP_ROUTE_ASSETS as Record<string, MapRoutes | undefined>)[mapName] ?? null;
+}

package/src/routes.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { routeIndex, furthestRouteIndex, type MapRoute } from "./routes.js";
+
+const aPalace: MapRoute = {
+  id: "a_palace",
+  name: "A 大厅",
+  type: "primary_entry",
+  bombsite: "a",
+  confidence: "high",
+  zones: [
+    { id: "TSpawn" },
+    { id: "PalaceAlley" },
+    { id: "TRamp" },
+    { id: "PalaceInterior" },
+    { id: "BombsiteA" },
+  ],
+};
+
+describe("routeIndex", () => {
+  it("returns advance index along the route", () => {
+    expect(routeIndex(aPalace, "TSpawn")).toBe(0);
+    expect(routeIndex(aPalace, "PalaceInterior")).toBe(3);
+    expect(routeIndex(aPalace, "BombsiteA")).toBe(4);
+  });
+
+  it("returns -1 for callouts off the route or nullish", () => {
+    expect(routeIndex(aPalace, "Apartments")).toBe(-1);
+    expect(routeIndex(aPalace, null)).toBe(-1);
+    expect(routeIndex(aPalace, undefined)).toBe(-1);
+  });
+});
+
+describe("furthestRouteIndex", () => {
+  it("takes the furthest controlled callout along the route", () => {
+    expect(furthestRouteIndex(aPalace, ["TSpawn", "TRamp", "PalaceAlley"])).toBe(2);
+  });
+
+  it("ignores callouts not on the route", () => {
+    expect(furthestRouteIndex(aPalace, ["Apartments", "Underpass"])).toBe(-1);
+    expect(furthestRouteIndex(aPalace, ["Apartments", "PalaceInterior"])).toBe(3);
+  });
+
+  it("returns -1 for an empty set", () => {
+    expect(furthestRouteIndex(aPalace, [])).toBe(-1);
+  });
+});

package/src/routes.ts

@@ -0,0 +1,93 @@
+/**
+ * map-routes — 进攻动线（T 方从匪家到包点的推进路径）
+ *
+ * 【归档 2026-06】route(有序动线)+zone(多边形) 的人工标注已停止演进，被
+ * `default-positions.ts`（callout 默认位归并）取代。本文件仅为 spatial shadow 层
+ * （phase/mapcontrol，当前发 null）保留，不再新增/修订动线资产。RR 现役零依赖。
+ *
+ * 定位：一条动线 = 一串**有序的 CS2 callout 区域名**（= replay `place` 列
+ * 对应的 placeDict 取值），从 T 出生区指向某个包点。控制进度 / 道具拖延都沿这条
+ * 一维序列度量。
+ *
+ * 边界：动线**只引用 callout 名字，不含任何坐标**——区域归属由 v3 replay `place`
+ * 列提供，本层不做几何。需要把一个 callout 再切细（如 Palace 分上下）时
+ * 才回到 `zones.ts` 的多边形层。本文件只定义结构 + 沿线定位，不算指标（指标在 core）。
+ *
+ * 数据：每张图一个 `packages/maps/map-routes/<map>.json`，由 `scripts/extract-routes.ts`
+ * 从真实 demo 的 T 方开局转移半自动挖出、人工确认。
+ */
+
+/** 动线上的一个命名区域。 */
+export interface RouteZone {
+  /** `lastPlaceName` 原始取值（如 "TSpawn" / "PalaceAlley" / "BombsiteA"）。 */
+  id: string;
+}
+
+/** 动线类型——区分进攻线 vs 控制/入侵线。 */
+export type RouteType =
+  | "primary_entry"    // 主进攻线：A厅、B坡、Dust2 B洞 —— 直插包点的干道
+  | "secondary_entry"  // 副进攻线：A小、B侧门、Inferno二楼 —— 次要/split 进点路径
+  | "mid_connector"    // 中路 connector：中路→拱门/甜甜圈/连接 —— 价值在夹击与压缩防守
+  | "lurk_lane"        // 单挂牵制线：控VIP/黑屋 —— 终点是控制区而非包点
+  | "rotation_cut";    // 断回防线：入侵警家/切轮转路线 —— 切断CT回防通道
+
+/** 可信度——数据支撑程度。 */
+export type RouteConfidence = "high" | "medium" | "low";
+
+/** 一条进攻动线：从 T 出生区到某包点的有序 callout 序列。 */
+export interface MapRoute {
+  /** 稳定唯一 id（如 "a_main" / "b_ramp"）。 */
+  id: string;
+  /** 人类可读名（如 "A 厅" / "B 坡"）。 */
+  name: string;
+  /** 动线类型。 */
+  type: RouteType;
+  /** 该动线指向的包点。 */
+  bombsite: "a" | "b";
+  /** 可信度标签。 */
+  confidence: RouteConfidence;
+  /**
+   * 推进顺序的 callout 序列（T 出生区 → 包点）。
+   * 第一个元素通常为 TSpawn、最后一个为 BombsiteA / BombsiteB。
+   */
+  zones: RouteZone[];
+}
+
+export interface MapRoutes {
+  /** 如 "de_mirage"。 */
+  mapName: string;
+  /** 标定版本，便于演进。 */
+  version: string;
+  routes: MapRoute[];
+}
+
+/** 提取动线上所有 zone id（供兼容字符串 API 使用）。 */
+function zoneIds(route: MapRoute): string[] {
+  return route.zones.map((z) => z.id);
+}
+
+/**
+ * callout 在动线上的位置下标（0 = 起点/T 出生侧，越大越靠近包点），
+ * 不在该动线上返回 -1。
+ */
+export function routeIndex(route: MapRoute, placeName: string | null | undefined): number {
+  if (!placeName) return -1;
+  return zoneIds(route).indexOf(placeName);
+}
+
+/**
+ * 一组当前被某方占有的 callout，沿该动线推进到的**最远下标**（-1 = 一个都不在线上）。
+ * 这是「区域控制进度」的核心原语：进攻方连续占有到 banana 顶 = 进度 = 该 callout 的下标。
+ */
+export function furthestRouteIndex(
+  route: MapRoute,
+  controlledPlaceNames: Iterable<string>,
+): number {
+  let best = -1;
+  const ids = zoneIds(route);
+  for (const pl of controlledPlaceNames) {
+    const i = ids.indexOf(pl);
+    if (i > best) best = i;
+  }
+  return best;
+}