@axiapps/bridge-metrics 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(src_exports, {
   DEFAULT_DISRUPTION_METHOD: () => DEFAULT_DISRUPTION_METHOD,
   METRICS_SPEC: () => METRICS_SPEC,
   NON_DAMAGING_CONDITIONS: () => NON_DAMAGING_CONDITIONS,
+  OUT_OF_POSITION: () => OUT_OF_POSITION,
   PROFESSION_COLORS: () => PROFESSION_COLORS,
   ROLLUP_SOURCES_VERSION: () => ROLLUP_SOURCES_VERSION,
   ReportSchemaError: () => ReportSchemaError,
@@ -30,12 +31,14 @@ __export(src_exports, {
   applySquadStabilityGeneration: () => applySquadStabilityGeneration,
   buildConditionIconMap: () => buildConditionIconMap,
   buildRollupData: () => buildRollupData,
+  classifyDegree: () => classifyDegree,
   compareRunSets: () => compareRunSets,
   computeDownContribution: () => computeDownContribution,
   computeIncomingDisruptions: () => computeIncomingDisruptions,
   computeOutgoingConditions: () => computeOutgoingConditions,
   computeOutgoingCrowdControl: () => computeOutgoingCrowdControl,
   computePlayerAggregation: () => computePlayerAggregation,
+  computePositioning: () => computePositioning,
   computeSquadBarrier: () => computeSquadBarrier,
   computeSquadHealing: () => computeSquadHealing,
   createPlayerAggregationAccumulators: () => createPlayerAggregationAccumulators,
@@ -2835,11 +2838,277 @@ var compareRunSets = (a, b) => {
     })
   };
 };
+
+// src/positioning.ts
+var OUT_OF_POSITION = 1200;
+var clamp = (val, min, max) => Math.max(min, Math.min(max, val));
+var squadOf = (r) => (r.details?.players ?? []).filter((p) => !p?.notInSquad);
+function linkedDeathHits(player, tagPositions, pollingRate) {
+  const replay = player?.combatReplayData;
+  if (!replay || !Array.isArray(replay.dead) || !Array.isArray(replay.down)) return [];
+  const playerPositions = replay.positions;
+  if (!Array.isArray(playerPositions) || playerPositions.length === 0) return [];
+  const playerStart = Number(replay.start ?? 0);
+  const playerOffset = Math.floor(playerStart / pollingRate);
+  const deadSet = /* @__PURE__ */ new Set();
+  for (const entry of replay.dead) {
+    if (Array.isArray(entry) && Number.isFinite(Number(entry[0])) && Number(entry[0]) > 0) {
+      deadSet.add(Number(entry[0]));
+    }
+  }
+  const hits = [];
+  for (const entry of replay.down) {
+    if (!Array.isArray(entry)) continue;
+    const downStartMs = Number(entry[0]);
+    const linkedDeathMs = Number(entry[1]);
+    if (!Number.isFinite(downStartMs) || downStartMs < 0) continue;
+    if (!deadSet.has(linkedDeathMs)) continue;
+    const pollIndex = Math.floor(downStartMs / pollingRate);
+    const playerIdx = clamp(pollIndex - playerOffset, 0, playerPositions.length - 1);
+    const tagIdx = clamp(pollIndex, 0, tagPositions.length - 1);
+    const [px, py] = playerPositions[playerIdx];
+    const [tx, ty] = tagPositions[tagIdx];
+    hits.push({ px, py, tx, ty, downStartMs });
+  }
+  return hits;
+}
+function classifyDegree(report) {
+  const squad = squadOf(report);
+  const meta = report.details?.combatReplayMetaData ?? {};
+  const commander = squad.find((p) => p?.hasCommanderTag);
+  const tagPositions = commander?.combatReplayData?.positions ?? [];
+  if (commander && tagPositions.length > 0 && (meta.pollingRate ?? 0) > 0 && (meta.inchToPixel ?? 0) > 0) return "full";
+  if (squad.some((p) => typeof p?.statsAll?.[0]?.distToCom === "number")) return "coarse";
+  return "none";
+}
+function computePositioning(report) {
+  const degree = classifyDegree(report);
+  const squad = squadOf(report);
+  const meta = report.details?.combatReplayMetaData ?? {};
+  const pollingRate = (meta.pollingRate ?? 0) > 0 ? meta.pollingRate : 0;
+  const inchToPixel = (meta.inchToPixel ?? 0) > 0 ? meta.inchToPixel : 0;
+  const commander = squad.find((p) => p?.hasCommanderTag);
+  const tagPositions = commander?.combatReplayData?.positions ?? [];
+  const replayUsable = !!commander && tagPositions.length > 0 && pollingRate > 0 && inchToPixel > 0;
+  const perPlayerMap = /* @__PURE__ */ new Map();
+  const outOfPositionDeaths = [];
+  if (replayUsable) {
+    for (const player of squad) {
+      const account = player?.account ?? "Unknown";
+      const isCommanderPlayer = !!player?.hasCommanderTag;
+      const playerPositions = player?.combatReplayData?.positions;
+      if (!Array.isArray(playerPositions) || playerPositions.length === 0) continue;
+      const playerStart = Number(player?.combatReplayData?.start ?? 0);
+      const playerOffset = Math.floor(playerStart / pollingRate);
+      const samples = [];
+      for (let i = 0; i < playerPositions.length; i++) {
+        const tagIdx = clamp(i + playerOffset, 0, tagPositions.length - 1);
+        const [px, py] = playerPositions[i];
+        const [tx, ty] = tagPositions[tagIdx];
+        const dist = isCommanderPlayer ? 0 : Math.hypot(px - tx, py - ty) / inchToPixel;
+        samples.push(dist);
+      }
+      if (!isCommanderPlayer) {
+        const existing = perPlayerMap.get(account);
+        if (existing) {
+          for (const s of samples) existing.push(s);
+        } else {
+          perPlayerMap.set(account, samples);
+        }
+      }
+      if (isCommanderPlayer) continue;
+      for (const { px, py, tx, ty, downStartMs } of linkedDeathHits(player, tagPositions, pollingRate)) {
+        const distAtDown = Math.round(Math.hypot(px - tx, py - ty) / inchToPixel);
+        if (distAtDown > OUT_OF_POSITION) {
+          outOfPositionDeaths.push({ account, distAtDown, atSec: Math.round(downStartMs / 1e3) });
+        }
+      }
+    }
+  }
+  const perPlayer = [];
+  if (replayUsable) {
+    for (const [account, samples] of perPlayerMap) {
+      if (samples.length === 0) continue;
+      const avg = samples.reduce((s, v) => s + v, 0) / samples.length;
+      const peak = Math.max(...samples);
+      perPlayer.push({ account, avgDistToTag: Math.round(avg), peakDistToTag: Math.round(peak) });
+    }
+    perPlayer.sort((a, b) => b.peakDistToTag - a.peakDistToTag);
+  } else if (degree === "coarse") {
+    for (const p of squad) {
+      const account = p?.account;
+      if (!account) continue;
+      const distToCom = p?.statsAll?.[0]?.distToCom;
+      if (typeof distToCom !== "number") continue;
+      perPlayer.push({ account, avgDistToTag: distToCom, peakDistToTag: distToCom });
+    }
+    perPlayer.sort((a, b) => b.peakDistToTag - a.peakDistToTag);
+  }
+  if (degree !== "full" || !replayUsable) {
+    return { degree, perPlayer, outOfPositionDeaths, squad: null, commander: null, deathClusters: [], figure: void 0 };
+  }
+  const squadNonCmdr = squad.filter((p) => !p?.hasCommanderTag && Array.isArray(p?.combatReplayData?.positions) && (p.combatReplayData.positions.length ?? 0) > 0);
+  const numTicks = tagPositions.length;
+  let spreadSum = 0;
+  let peakSpreadValue = 0;
+  let peakSpreadAtSec = 0;
+  let tagToCentroidSum = 0;
+  let peakLeadValue = 0;
+  let peakLeadAtSec = 0;
+  const deathCoords = [];
+  for (const player of squad) {
+    for (const { px, py } of linkedDeathHits(player, tagPositions, pollingRate)) {
+      deathCoords.push([px, py]);
+    }
+  }
+  for (let i = 0; i < numTicks; i++) {
+    const atSec = i * pollingRate / 1e3;
+    const [tx, ty] = tagPositions[i];
+    if (squadNonCmdr.length > 0) {
+      let spreadAtTick = 0;
+      let centroidX = 0;
+      let centroidY = 0;
+      for (const player of squadNonCmdr) {
+        const positions = player.combatReplayData.positions;
+        const playerStart = Number(player.combatReplayData?.start ?? 0);
+        const playerOffset = Math.floor(playerStart / pollingRate);
+        const pIdx = clamp(i - playerOffset, 0, positions.length - 1);
+        const [px, py] = positions[pIdx];
+        spreadAtTick += Math.hypot(px - tx, py - ty) / inchToPixel;
+        centroidX += px;
+        centroidY += py;
+      }
+      const avgSpreadAtTick = spreadAtTick / squadNonCmdr.length;
+      spreadSum += avgSpreadAtTick;
+      if (avgSpreadAtTick > peakSpreadValue) {
+        peakSpreadValue = avgSpreadAtTick;
+        peakSpreadAtSec = atSec;
+      }
+      centroidX /= squadNonCmdr.length;
+      centroidY /= squadNonCmdr.length;
+      const tagToCentroidDist = Math.hypot(tx - centroidX, ty - centroidY) / inchToPixel;
+      tagToCentroidSum += tagToCentroidDist;
+      if (tagToCentroidDist > peakLeadValue) {
+        peakLeadValue = tagToCentroidDist;
+        peakLeadAtSec = atSec;
+      }
+    }
+  }
+  const avgSpread = numTicks > 0 ? spreadSum / numTicks : 0;
+  const peakAvgRatio = avgSpread > 0 ? peakSpreadValue / avgSpread : 1;
+  const cohesionNote = peakAvgRatio > 2.5 ? "tight then scattered" : "held together";
+  const squadFollowLag = numTicks > 0 ? tagToCentroidSum / numTicks : 0;
+  const CLUSTER_CELL = 150;
+  const cellMap = /* @__PURE__ */ new Map();
+  for (const [x, y] of deathCoords) {
+    const cellX = Math.floor(x / CLUSTER_CELL);
+    const cellY = Math.floor(y / CLUSTER_CELL);
+    const key = `${cellX},${cellY}`;
+    const existing = cellMap.get(key);
+    if (existing) {
+      existing.sumX += x;
+      existing.sumY += y;
+      existing.count++;
+    } else {
+      cellMap.set(key, { sumX: x, sumY: y, count: 1 });
+    }
+  }
+  const deathClusters = Array.from(cellMap.values()).map(({ sumX, sumY, count }) => ({ x: sumX / count, y: sumY / count, count })).sort((a, b) => b.count - a.count).slice(0, 6);
+  const stride = Math.ceil(1e3 / pollingRate);
+  const tagPath = [];
+  for (let i = 0; i < tagPositions.length; i += stride) {
+    tagPath.push(tagPositions[i]);
+  }
+  const downCoords = [];
+  for (const player of squad) {
+    const replay = player?.combatReplayData;
+    if (!replay || !Array.isArray(replay.down) || !Array.isArray(replay.positions)) continue;
+    const playerStart = Number(replay.start ?? 0);
+    const playerOffset = Math.floor(playerStart / pollingRate);
+    for (const entry of replay.down) {
+      if (!Array.isArray(entry)) continue;
+      const downStartMs = Number(entry[0]);
+      if (!Number.isFinite(downStartMs) || downStartMs < 0) continue;
+      const pollIndex = Math.floor(downStartMs / pollingRate);
+      const playerIdx = clamp(pollIndex - playerOffset, 0, replay.positions.length - 1);
+      const [px, py] = replay.positions[playerIdx];
+      downCoords.push([px, py]);
+    }
+  }
+  const spreadTimeline = [];
+  let sumMassX = 0;
+  let sumMassY = 0;
+  let massCount = 0;
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (let i = 0; i < numTicks; i += stride) {
+    const atSec = i * pollingRate / 1e3;
+    const [tx, ty] = tagPositions[i];
+    let spreadAtTick = 0;
+    let centroidX = 0;
+    let centroidY = 0;
+    for (const player of squadNonCmdr) {
+      const positions = player.combatReplayData.positions;
+      const playerStart = Number(player.combatReplayData?.start ?? 0);
+      const playerOffset = Math.floor(playerStart / pollingRate);
+      const pIdx = clamp(i - playerOffset, 0, positions.length - 1);
+      const [px, py] = positions[pIdx];
+      spreadAtTick += Math.hypot(px - tx, py - ty) / inchToPixel;
+      centroidX += px;
+      centroidY += py;
+    }
+    if (squadNonCmdr.length > 0) {
+      centroidX /= squadNonCmdr.length;
+      centroidY /= squadNonCmdr.length;
+      spreadTimeline.push([atSec, Math.round(spreadAtTick / squadNonCmdr.length)]);
+      sumMassX += centroidX;
+      sumMassY += centroidY;
+      minX = Math.min(minX, centroidX);
+      maxX = Math.max(maxX, centroidX);
+      minY = Math.min(minY, centroidY);
+      maxY = Math.max(maxY, centroidY);
+      massCount++;
+    }
+  }
+  const massX = massCount > 0 ? sumMassX / massCount : 0;
+  const massY = massCount > 0 ? sumMassY / massCount : 0;
+  const massR = massCount > 0 ? Math.hypot(maxX - minX, maxY - minY) / 2 : 0;
+  const sizes = meta.sizes ?? [0, 0];
+  const figure = {
+    map: { sizes, inchToPixel },
+    tagPath,
+    squadMass: { x: Math.round(massX), y: Math.round(massY), r: Math.round(massR) },
+    deaths: deathCoords,
+    downs: downCoords,
+    spread: spreadTimeline,
+    peakSpread: Math.round(peakSpreadValue)
+  };
+  return {
+    degree,
+    perPlayer,
+    outOfPositionDeaths,
+    squad: {
+      avgSpread: Math.round(avgSpread),
+      peakSpread: { value: Math.round(peakSpreadValue), atSec: peakSpreadAtSec },
+      cohesionNote
+    },
+    commander: {
+      account: commander?.account ?? "Unknown",
+      peakLeadFromSquad: { value: Math.round(peakLeadValue), atSec: peakLeadAtSec },
+      squadFollowLag: Math.round(squadFollowLag)
+    },
+    deathClusters,
+    figure
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_DISRUPTION_METHOD,
   METRICS_SPEC,
   NON_DAMAGING_CONDITIONS,
+  OUT_OF_POSITION,
   PROFESSION_COLORS,
   ROLLUP_SOURCES_VERSION,
   ReportSchemaError,
@@ -2847,12 +3116,14 @@ var compareRunSets = (a, b) => {
   applySquadStabilityGeneration,
   buildConditionIconMap,
   buildRollupData,
+  classifyDegree,
   compareRunSets,
   computeDownContribution,
   computeIncomingDisruptions,
   computeOutgoingConditions,
   computeOutgoingCrowdControl,
   computePlayerAggregation,
+  computePositioning,
   computeSquadBarrier,
   computeSquadHealing,
   createPlayerAggregationAccumulators,

package/dist/index.d.cts

@@ -11,3 +11,99 @@ export { PlayerRoleClassification, RoleClassificationFactor } from './roles.cjs'
 export { isResUtilitySkill } from './resUtility.cjs';
 export { parseTimestamp as parseFightTimestamp, resolveFightTimestamp } from './timestampUtils.cjs';
 export { PlayerAggregate, ReportSchemaError, RunPlayerSummary, RunSetComparison, RunSummary, aggregatePlayers, compareRunSets, extractRunSummary } from './reportMetrics.cjs';
+
+type ReplayDegree = 'full' | 'coarse' | 'none';
+type AnyPlayer = {
+    notInSquad?: boolean;
+    hasCommanderTag?: boolean;
+    account?: string;
+    profession?: string;
+    statsAll?: Array<{
+        distToCom?: number;
+        stackDist?: number;
+    }>;
+    combatReplayData?: {
+        positions?: Array<[number, number]>;
+        dead?: Array<[number, number]>;
+        down?: Array<[number, number]>;
+        start?: number;
+    };
+};
+type ParsedReport = {
+    details?: {
+        players?: AnyPlayer[];
+        combatReplayMetaData?: {
+            pollingRate?: number;
+            inchToPixel?: number;
+            sizes?: [number, number];
+        };
+        durationMS?: number;
+    };
+};
+type PerPlayerDistance = {
+    account: string;
+    avgDistToTag: number;
+    peakDistToTag: number;
+};
+type OutOfPositionDeath = {
+    account: string;
+    distAtDown: number;
+    atSec: number;
+};
+type SquadCohesion = {
+    avgSpread: number;
+    peakSpread: {
+        value: number;
+        atSec: number;
+    };
+    cohesionNote: string;
+};
+type CommanderOverextension = {
+    account: string;
+    peakLeadFromSquad: {
+        value: number;
+        atSec: number;
+    };
+    /** v1 definition: mean per-tick distance from commander to squad centroid */
+    squadFollowLag: number;
+};
+type DeathCluster = {
+    x: number;
+    y: number;
+    count: number;
+};
+type PositioningFigure = {
+    map: {
+        sizes: [number, number];
+        inchToPixel: number;
+    };
+    /** Down-sampled tag path: ~1 point/sec (stride = Math.ceil(1000/pollingRate)) */
+    tagPath: Array<[number, number]>;
+    /** Approximate bounding circle of the squad centroid over time */
+    squadMass: {
+        x: number;
+        y: number;
+        r: number;
+    };
+    /** Death locations (reused from deathClusters source) */
+    deaths: Array<[number, number]>;
+    /** Down positions */
+    downs: Array<[number, number]>;
+    /** [[sec, spreadValue]] down-sampled to ~1 point/sec */
+    spread: Array<[number, number]>;
+    peakSpread: number;
+};
+type PositioningSummary = {
+    degree: ReplayDegree;
+    perPlayer: PerPlayerDistance[];
+    outOfPositionDeaths: OutOfPositionDeath[];
+    squad: SquadCohesion | null;
+    commander: CommanderOverextension | null;
+    deathClusters: DeathCluster[];
+    figure: PositioningFigure | undefined;
+};
+declare const OUT_OF_POSITION = 1200;
+declare function classifyDegree(report: ParsedReport): ReplayDegree;
+declare function computePositioning(report: ParsedReport): PositioningSummary;
+
+export { type CommanderOverextension, type DeathCluster, OUT_OF_POSITION, type OutOfPositionDeath, type ParsedReport, type PerPlayerDistance, type PositioningFigure, type PositioningSummary, type ReplayDegree, type SquadCohesion, classifyDegree, computePositioning };

package/dist/index.d.ts

@@ -11,3 +11,99 @@ export { PlayerRoleClassification, RoleClassificationFactor } from './roles.js';
 export { isResUtilitySkill } from './resUtility.js';
 export { parseTimestamp as parseFightTimestamp, resolveFightTimestamp } from './timestampUtils.js';
 export { PlayerAggregate, ReportSchemaError, RunPlayerSummary, RunSetComparison, RunSummary, aggregatePlayers, compareRunSets, extractRunSummary } from './reportMetrics.js';
+
+type ReplayDegree = 'full' | 'coarse' | 'none';
+type AnyPlayer = {
+    notInSquad?: boolean;
+    hasCommanderTag?: boolean;
+    account?: string;
+    profession?: string;
+    statsAll?: Array<{
+        distToCom?: number;
+        stackDist?: number;
+    }>;
+    combatReplayData?: {
+        positions?: Array<[number, number]>;
+        dead?: Array<[number, number]>;
+        down?: Array<[number, number]>;
+        start?: number;
+    };
+};
+type ParsedReport = {
+    details?: {
+        players?: AnyPlayer[];
+        combatReplayMetaData?: {
+            pollingRate?: number;
+            inchToPixel?: number;
+            sizes?: [number, number];
+        };
+        durationMS?: number;
+    };
+};
+type PerPlayerDistance = {
+    account: string;
+    avgDistToTag: number;
+    peakDistToTag: number;
+};
+type OutOfPositionDeath = {
+    account: string;
+    distAtDown: number;
+    atSec: number;
+};
+type SquadCohesion = {
+    avgSpread: number;
+    peakSpread: {
+        value: number;
+        atSec: number;
+    };
+    cohesionNote: string;
+};
+type CommanderOverextension = {
+    account: string;
+    peakLeadFromSquad: {
+        value: number;
+        atSec: number;
+    };
+    /** v1 definition: mean per-tick distance from commander to squad centroid */
+    squadFollowLag: number;
+};
+type DeathCluster = {
+    x: number;
+    y: number;
+    count: number;
+};
+type PositioningFigure = {
+    map: {
+        sizes: [number, number];
+        inchToPixel: number;
+    };
+    /** Down-sampled tag path: ~1 point/sec (stride = Math.ceil(1000/pollingRate)) */
+    tagPath: Array<[number, number]>;
+    /** Approximate bounding circle of the squad centroid over time */
+    squadMass: {
+        x: number;
+        y: number;
+        r: number;
+    };
+    /** Death locations (reused from deathClusters source) */
+    deaths: Array<[number, number]>;
+    /** Down positions */
+    downs: Array<[number, number]>;
+    /** [[sec, spreadValue]] down-sampled to ~1 point/sec */
+    spread: Array<[number, number]>;
+    peakSpread: number;
+};
+type PositioningSummary = {
+    degree: ReplayDegree;
+    perPlayer: PerPlayerDistance[];
+    outOfPositionDeaths: OutOfPositionDeath[];
+    squad: SquadCohesion | null;
+    commander: CommanderOverextension | null;
+    deathClusters: DeathCluster[];
+    figure: PositioningFigure | undefined;
+};
+declare const OUT_OF_POSITION = 1200;
+declare function classifyDegree(report: ParsedReport): ReplayDegree;
+declare function computePositioning(report: ParsedReport): PositioningSummary;
+
+export { type CommanderOverextension, type DeathCluster, OUT_OF_POSITION, type OutOfPositionDeath, type ParsedReport, type PerPlayerDistance, type PositioningFigure, type PositioningSummary, type ReplayDegree, type SquadCohesion, classifyDegree, computePositioning };

package/dist/index.js

@@ -86,10 +86,276 @@ import {
   hexToRgba,
   toSuperscript
 } from "./chunk-WW5XFXGC.js";
+
+// src/positioning.ts
+var OUT_OF_POSITION = 1200;
+var clamp = (val, min, max) => Math.max(min, Math.min(max, val));
+var squadOf = (r) => (r.details?.players ?? []).filter((p) => !p?.notInSquad);
+function linkedDeathHits(player, tagPositions, pollingRate) {
+  const replay = player?.combatReplayData;
+  if (!replay || !Array.isArray(replay.dead) || !Array.isArray(replay.down)) return [];
+  const playerPositions = replay.positions;
+  if (!Array.isArray(playerPositions) || playerPositions.length === 0) return [];
+  const playerStart = Number(replay.start ?? 0);
+  const playerOffset = Math.floor(playerStart / pollingRate);
+  const deadSet = /* @__PURE__ */ new Set();
+  for (const entry of replay.dead) {
+    if (Array.isArray(entry) && Number.isFinite(Number(entry[0])) && Number(entry[0]) > 0) {
+      deadSet.add(Number(entry[0]));
+    }
+  }
+  const hits = [];
+  for (const entry of replay.down) {
+    if (!Array.isArray(entry)) continue;
+    const downStartMs = Number(entry[0]);
+    const linkedDeathMs = Number(entry[1]);
+    if (!Number.isFinite(downStartMs) || downStartMs < 0) continue;
+    if (!deadSet.has(linkedDeathMs)) continue;
+    const pollIndex = Math.floor(downStartMs / pollingRate);
+    const playerIdx = clamp(pollIndex - playerOffset, 0, playerPositions.length - 1);
+    const tagIdx = clamp(pollIndex, 0, tagPositions.length - 1);
+    const [px, py] = playerPositions[playerIdx];
+    const [tx, ty] = tagPositions[tagIdx];
+    hits.push({ px, py, tx, ty, downStartMs });
+  }
+  return hits;
+}
+function classifyDegree(report) {
+  const squad = squadOf(report);
+  const meta = report.details?.combatReplayMetaData ?? {};
+  const commander = squad.find((p) => p?.hasCommanderTag);
+  const tagPositions = commander?.combatReplayData?.positions ?? [];
+  if (commander && tagPositions.length > 0 && (meta.pollingRate ?? 0) > 0 && (meta.inchToPixel ?? 0) > 0) return "full";
+  if (squad.some((p) => typeof p?.statsAll?.[0]?.distToCom === "number")) return "coarse";
+  return "none";
+}
+function computePositioning(report) {
+  const degree = classifyDegree(report);
+  const squad = squadOf(report);
+  const meta = report.details?.combatReplayMetaData ?? {};
+  const pollingRate = (meta.pollingRate ?? 0) > 0 ? meta.pollingRate : 0;
+  const inchToPixel = (meta.inchToPixel ?? 0) > 0 ? meta.inchToPixel : 0;
+  const commander = squad.find((p) => p?.hasCommanderTag);
+  const tagPositions = commander?.combatReplayData?.positions ?? [];
+  const replayUsable = !!commander && tagPositions.length > 0 && pollingRate > 0 && inchToPixel > 0;
+  const perPlayerMap = /* @__PURE__ */ new Map();
+  const outOfPositionDeaths = [];
+  if (replayUsable) {
+    for (const player of squad) {
+      const account = player?.account ?? "Unknown";
+      const isCommanderPlayer = !!player?.hasCommanderTag;
+      const playerPositions = player?.combatReplayData?.positions;
+      if (!Array.isArray(playerPositions) || playerPositions.length === 0) continue;
+      const playerStart = Number(player?.combatReplayData?.start ?? 0);
+      const playerOffset = Math.floor(playerStart / pollingRate);
+      const samples = [];
+      for (let i = 0; i < playerPositions.length; i++) {
+        const tagIdx = clamp(i + playerOffset, 0, tagPositions.length - 1);
+        const [px, py] = playerPositions[i];
+        const [tx, ty] = tagPositions[tagIdx];
+        const dist = isCommanderPlayer ? 0 : Math.hypot(px - tx, py - ty) / inchToPixel;
+        samples.push(dist);
+      }
+      if (!isCommanderPlayer) {
+        const existing = perPlayerMap.get(account);
+        if (existing) {
+          for (const s of samples) existing.push(s);
+        } else {
+          perPlayerMap.set(account, samples);
+        }
+      }
+      if (isCommanderPlayer) continue;
+      for (const { px, py, tx, ty, downStartMs } of linkedDeathHits(player, tagPositions, pollingRate)) {
+        const distAtDown = Math.round(Math.hypot(px - tx, py - ty) / inchToPixel);
+        if (distAtDown > OUT_OF_POSITION) {
+          outOfPositionDeaths.push({ account, distAtDown, atSec: Math.round(downStartMs / 1e3) });
+        }
+      }
+    }
+  }
+  const perPlayer = [];
+  if (replayUsable) {
+    for (const [account, samples] of perPlayerMap) {
+      if (samples.length === 0) continue;
+      const avg = samples.reduce((s, v) => s + v, 0) / samples.length;
+      const peak = Math.max(...samples);
+      perPlayer.push({ account, avgDistToTag: Math.round(avg), peakDistToTag: Math.round(peak) });
+    }
+    perPlayer.sort((a, b) => b.peakDistToTag - a.peakDistToTag);
+  } else if (degree === "coarse") {
+    for (const p of squad) {
+      const account = p?.account;
+      if (!account) continue;
+      const distToCom = p?.statsAll?.[0]?.distToCom;
+      if (typeof distToCom !== "number") continue;
+      perPlayer.push({ account, avgDistToTag: distToCom, peakDistToTag: distToCom });
+    }
+    perPlayer.sort((a, b) => b.peakDistToTag - a.peakDistToTag);
+  }
+  if (degree !== "full" || !replayUsable) {
+    return { degree, perPlayer, outOfPositionDeaths, squad: null, commander: null, deathClusters: [], figure: void 0 };
+  }
+  const squadNonCmdr = squad.filter((p) => !p?.hasCommanderTag && Array.isArray(p?.combatReplayData?.positions) && (p.combatReplayData.positions.length ?? 0) > 0);
+  const numTicks = tagPositions.length;
+  let spreadSum = 0;
+  let peakSpreadValue = 0;
+  let peakSpreadAtSec = 0;
+  let tagToCentroidSum = 0;
+  let peakLeadValue = 0;
+  let peakLeadAtSec = 0;
+  const deathCoords = [];
+  for (const player of squad) {
+    for (const { px, py } of linkedDeathHits(player, tagPositions, pollingRate)) {
+      deathCoords.push([px, py]);
+    }
+  }
+  for (let i = 0; i < numTicks; i++) {
+    const atSec = i * pollingRate / 1e3;
+    const [tx, ty] = tagPositions[i];
+    if (squadNonCmdr.length > 0) {
+      let spreadAtTick = 0;
+      let centroidX = 0;
+      let centroidY = 0;
+      for (const player of squadNonCmdr) {
+        const positions = player.combatReplayData.positions;
+        const playerStart = Number(player.combatReplayData?.start ?? 0);
+        const playerOffset = Math.floor(playerStart / pollingRate);
+        const pIdx = clamp(i - playerOffset, 0, positions.length - 1);
+        const [px, py] = positions[pIdx];
+        spreadAtTick += Math.hypot(px - tx, py - ty) / inchToPixel;
+        centroidX += px;
+        centroidY += py;
+      }
+      const avgSpreadAtTick = spreadAtTick / squadNonCmdr.length;
+      spreadSum += avgSpreadAtTick;
+      if (avgSpreadAtTick > peakSpreadValue) {
+        peakSpreadValue = avgSpreadAtTick;
+        peakSpreadAtSec = atSec;
+      }
+      centroidX /= squadNonCmdr.length;
+      centroidY /= squadNonCmdr.length;
+      const tagToCentroidDist = Math.hypot(tx - centroidX, ty - centroidY) / inchToPixel;
+      tagToCentroidSum += tagToCentroidDist;
+      if (tagToCentroidDist > peakLeadValue) {
+        peakLeadValue = tagToCentroidDist;
+        peakLeadAtSec = atSec;
+      }
+    }
+  }
+  const avgSpread = numTicks > 0 ? spreadSum / numTicks : 0;
+  const peakAvgRatio = avgSpread > 0 ? peakSpreadValue / avgSpread : 1;
+  const cohesionNote = peakAvgRatio > 2.5 ? "tight then scattered" : "held together";
+  const squadFollowLag = numTicks > 0 ? tagToCentroidSum / numTicks : 0;
+  const CLUSTER_CELL = 150;
+  const cellMap = /* @__PURE__ */ new Map();
+  for (const [x, y] of deathCoords) {
+    const cellX = Math.floor(x / CLUSTER_CELL);
+    const cellY = Math.floor(y / CLUSTER_CELL);
+    const key = `${cellX},${cellY}`;
+    const existing = cellMap.get(key);
+    if (existing) {
+      existing.sumX += x;
+      existing.sumY += y;
+      existing.count++;
+    } else {
+      cellMap.set(key, { sumX: x, sumY: y, count: 1 });
+    }
+  }
+  const deathClusters = Array.from(cellMap.values()).map(({ sumX, sumY, count }) => ({ x: sumX / count, y: sumY / count, count })).sort((a, b) => b.count - a.count).slice(0, 6);
+  const stride = Math.ceil(1e3 / pollingRate);
+  const tagPath = [];
+  for (let i = 0; i < tagPositions.length; i += stride) {
+    tagPath.push(tagPositions[i]);
+  }
+  const downCoords = [];
+  for (const player of squad) {
+    const replay = player?.combatReplayData;
+    if (!replay || !Array.isArray(replay.down) || !Array.isArray(replay.positions)) continue;
+    const playerStart = Number(replay.start ?? 0);
+    const playerOffset = Math.floor(playerStart / pollingRate);
+    for (const entry of replay.down) {
+      if (!Array.isArray(entry)) continue;
+      const downStartMs = Number(entry[0]);
+      if (!Number.isFinite(downStartMs) || downStartMs < 0) continue;
+      const pollIndex = Math.floor(downStartMs / pollingRate);
+      const playerIdx = clamp(pollIndex - playerOffset, 0, replay.positions.length - 1);
+      const [px, py] = replay.positions[playerIdx];
+      downCoords.push([px, py]);
+    }
+  }
+  const spreadTimeline = [];
+  let sumMassX = 0;
+  let sumMassY = 0;
+  let massCount = 0;
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (let i = 0; i < numTicks; i += stride) {
+    const atSec = i * pollingRate / 1e3;
+    const [tx, ty] = tagPositions[i];
+    let spreadAtTick = 0;
+    let centroidX = 0;
+    let centroidY = 0;
+    for (const player of squadNonCmdr) {
+      const positions = player.combatReplayData.positions;
+      const playerStart = Number(player.combatReplayData?.start ?? 0);
+      const playerOffset = Math.floor(playerStart / pollingRate);
+      const pIdx = clamp(i - playerOffset, 0, positions.length - 1);
+      const [px, py] = positions[pIdx];
+      spreadAtTick += Math.hypot(px - tx, py - ty) / inchToPixel;
+      centroidX += px;
+      centroidY += py;
+    }
+    if (squadNonCmdr.length > 0) {
+      centroidX /= squadNonCmdr.length;
+      centroidY /= squadNonCmdr.length;
+      spreadTimeline.push([atSec, Math.round(spreadAtTick / squadNonCmdr.length)]);
+      sumMassX += centroidX;
+      sumMassY += centroidY;
+      minX = Math.min(minX, centroidX);
+      maxX = Math.max(maxX, centroidX);
+      minY = Math.min(minY, centroidY);
+      maxY = Math.max(maxY, centroidY);
+      massCount++;
+    }
+  }
+  const massX = massCount > 0 ? sumMassX / massCount : 0;
+  const massY = massCount > 0 ? sumMassY / massCount : 0;
+  const massR = massCount > 0 ? Math.hypot(maxX - minX, maxY - minY) / 2 : 0;
+  const sizes = meta.sizes ?? [0, 0];
+  const figure = {
+    map: { sizes, inchToPixel },
+    tagPath,
+    squadMass: { x: Math.round(massX), y: Math.round(massY), r: Math.round(massR) },
+    deaths: deathCoords,
+    downs: downCoords,
+    spread: spreadTimeline,
+    peakSpread: Math.round(peakSpreadValue)
+  };
+  return {
+    degree,
+    perPlayer,
+    outOfPositionDeaths,
+    squad: {
+      avgSpread: Math.round(avgSpread),
+      peakSpread: { value: Math.round(peakSpreadValue), atSec: peakSpreadAtSec },
+      cohesionNote
+    },
+    commander: {
+      account: commander?.account ?? "Unknown",
+      peakLeadFromSquad: { value: Math.round(peakLeadValue), atSec: peakLeadAtSec },
+      squadFollowLag: Math.round(squadFollowLag)
+    },
+    deathClusters,
+    figure
+  };
+}
 export {
   DEFAULT_DISRUPTION_METHOD,
   METRICS_SPEC,
   NON_DAMAGING_CONDITIONS,
+  OUT_OF_POSITION,
   PROFESSION_COLORS,
   ROLLUP_SOURCES_VERSION,
   ReportSchemaError,
@@ -97,12 +363,14 @@ export {
   applySquadStabilityGeneration,
   buildConditionIconMap,
   buildRollupData,
+  classifyDegree,
   compareRunSets,
   computeDownContribution,
   computeIncomingDisruptions,
   computeOutgoingConditions,
   computeOutgoingCrowdControl,
   computePlayerAggregation,
+  computePositioning,
   computeSquadBarrier,
   computeSquadHealing,
   createPlayerAggregationAccumulators,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@axiapps/bridge-metrics",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "type": "module",
     "description": "AxiBridge report aggregation core: player aggregation, rollup builder, metric extractors",
     "license": "GPL-3.0-only",
@@ -33,6 +33,7 @@
     "publishConfig": { "access": "public" },
     "scripts": {
         "build": "tsup",
+        "prepare": "tsup",
         "prepublishOnly": "tsup",
         "test": "vitest run --maxWorkers=2"
     },