volleyballsimtypes 0.0.513 → 0.0.515

package/dist/cjs/src/data/transformers/keyframe-codec.d.ts

@@ -0,0 +1,7 @@
+export interface KeyframeCoord {
+    readonly playerId: string;
+    readonly x: number;
+    readonly y: number;
+}
+export declare function encodeKeyframes(keyframes: Array<KeyframeCoord[] | undefined>, playerIndex: Map<string, number>): number[][];
+export declare function decodeKeyframes(k: number[][], roster: string[]): KeyframeCoord[][];

package/dist/cjs/src/data/transformers/keyframe-codec.js

@@ -0,0 +1,66 @@
+"use strict";
+// Compact codec for the replay position keyframes (owner 2026-08-11): quantize each coordinate to decimetres and
+// delta-encode against the running frame, so a rally stores only the players who MOVED each event (players teleport
+// only at phase changes, so most events add almost nothing). The result rides the existing msgpack + deflate rally
+// blob. VISUALIZATION ONLY, additive + optional. See VolleyballSim/plans/positional-replay-keyframes.md.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeKeyframes = encodeKeyframes;
+exports.decodeKeyframes = decodeKeyframes;
+// Decimetre quantization (~0.1 m, ample for a replay): x in [-4.5,4.5] -> qx in [-45,45], y in [-9,9] -> qy in [-90,90].
+const SCALE = 10;
+function quant(n) { return Math.round(n * SCALE); }
+function unquant(n) { return n / SCALE; }
+// Encode keyframes (aligned by index to a rally's events) into delta arrays: `k[i]` = flat `[idx, qx, qy, ...]` for the
+// players whose quantized position CHANGED at event i vs the running map. An empty entry = carry the prior frame (a
+// carry-forward event, or no movement). Trailing empty frames are trimmed. Players are referenced by `playerIndex`
+// (the caller extends the rally roster to cover every keyframe player).
+function encodeKeyframes(keyframes, playerIndex) {
+    const px = new Map();
+    const py = new Map();
+    const out = [];
+    for (const kf of keyframes) {
+        if (kf == null) {
+            out.push([]);
+            continue;
+        }
+        const delta = [];
+        for (const p of kf) {
+            const idx = playerIndex.get(p.playerId);
+            if (idx == null)
+                continue;
+            const qx = quant(p.x);
+            const qy = quant(p.y);
+            if (px.get(idx) === qx && py.get(idx) === qy)
+                continue;
+            px.set(idx, qx);
+            py.set(idx, qy);
+            delta.push(idx, qx, qy);
+        }
+        out.push(delta);
+    }
+    while (out.length > 0 && out[out.length - 1].length === 0)
+        out.pop();
+    return out;
+}
+// Decode the delta arrays back to a per-event keyframe. Frame i = the full running map after applying deltas 0..i
+// (so a carry-forward frame repeats the prior positions). Returns one frame per encoded entry; events past the
+// encoded length reuse the last frame.
+function decodeKeyframes(k, roster) {
+    const px = new Map();
+    const py = new Map();
+    const out = [];
+    for (const delta of k) {
+        for (let j = 0; j + 2 < delta.length; j += 3) {
+            px.set(delta[j], delta[j + 1]);
+            py.set(delta[j], delta[j + 2]);
+        }
+        const frame = [];
+        for (const [idx, qx] of px) {
+            const id = roster[idx];
+            if (id != null)
+                frame.push({ playerId: id, x: unquant(qx), y: unquant(py.get(idx)) });
+        }
+        out.push(frame);
+    }
+    return out;
+}

package/dist/cjs/src/data/transformers/keyframe-codec.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/src/data/transformers/keyframe-codec.test.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const keyframe_codec_1 = require("./keyframe-codec");
+const idx = new Map([['A', 0], ['B', 1]]);
+const roster = ['A', 'B'];
+(0, globals_1.describe)('keyframe-codec round trip', () => {
+    (0, globals_1.it)('quantizes to decimetres and restores within 0.1 m', () => {
+        const frames = [[{ playerId: 'A', x: 1.23, y: -2.34 }, { playerId: 'B', x: 3, y: 4.5 }]];
+        const [out] = (0, keyframe_codec_1.decodeKeyframes)((0, keyframe_codec_1.encodeKeyframes)(frames, idx), roster);
+        (0, globals_1.expect)(out.find(p => p.playerId === 'A')).toEqual({ playerId: 'A', x: 1.2, y: -2.3 });
+        (0, globals_1.expect)(out.find(p => p.playerId === 'B')).toEqual({ playerId: 'B', x: 3, y: 4.5 });
+    });
+    (0, globals_1.it)('stores only the players who moved (delta), and carries the rest forward', () => {
+        const frames = [
+            [{ playerId: 'A', x: 1, y: 1 }, { playerId: 'B', x: 3, y: 3 }],
+            [{ playerId: 'A', x: 1, y: 1 }, { playerId: 'B', x: -1, y: 2 }] // A unchanged, B moved
+        ];
+        const k = (0, keyframe_codec_1.encodeKeyframes)(frames, idx);
+        (0, globals_1.expect)(k[0]).toEqual([0, 10, 10, 1, 30, 30]); // both players
+        (0, globals_1.expect)(k[1]).toEqual([1, -10, 20]); // only B
+        const dec = (0, keyframe_codec_1.decodeKeyframes)(k, roster);
+        (0, globals_1.expect)(dec[0]).toEqual([{ playerId: 'A', x: 1, y: 1 }, { playerId: 'B', x: 3, y: 3 }]);
+        (0, globals_1.expect)(dec[1]).toEqual([{ playerId: 'A', x: 1, y: 1 }, { playerId: 'B', x: -1, y: 2 }]); // A carried forward
+    });
+    (0, globals_1.it)('an empty (carry-forward) frame repeats the prior positions', () => {
+        const frames = [
+            [{ playerId: 'A', x: 1, y: 1 }],
+            undefined, // carry forward
+            [{ playerId: 'A', x: 2, y: 2 }]
+        ];
+        const k = (0, keyframe_codec_1.encodeKeyframes)(frames, idx);
+        (0, globals_1.expect)(k).toEqual([[0, 10, 10], [], [0, 20, 20]]);
+        const dec = (0, keyframe_codec_1.decodeKeyframes)(k, roster);
+        (0, globals_1.expect)(dec[1]).toEqual([{ playerId: 'A', x: 1, y: 1 }]); // unchanged at the carry-forward frame
+        (0, globals_1.expect)(dec[2]).toEqual([{ playerId: 'A', x: 2, y: 2 }]);
+    });
+    (0, globals_1.it)('trims trailing empty frames', () => {
+        const frames = [[{ playerId: 'A', x: 1, y: 1 }], undefined, undefined];
+        (0, globals_1.expect)((0, keyframe_codec_1.encodeKeyframes)(frames, idx)).toEqual([[0, 10, 10]]);
+    });
+    (0, globals_1.it)('skips players absent from the roster index', () => {
+        const frames = [[{ playerId: 'A', x: 1, y: 1 }, { playerId: 'GHOST', x: 5, y: 5 }]];
+        (0, globals_1.expect)((0, keyframe_codec_1.encodeKeyframes)(frames, idx)).toEqual([[0, 10, 10]]);
+    });
+});

package/dist/cjs/src/data/transformers/rally.js

@@ -6,13 +6,14 @@ const msgpackr_1 = require("msgpackr");
 const zlib_1 = require("zlib");
 const lz_string_1 = require("lz-string");
 const service_1 = require("../../service");
+const keyframe_codec_1 = require("./keyframe-codec");
 const rally_event_1 = require("./rally-event");
 const VERSION_BYTE = 0x01;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function deflate(data) { return (0, zlib_1.deflateRawSync)(data); }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function inflate(data) { return (0, zlib_1.inflateRawSync)(data); }
-function buildRoster(events) {
+function buildRoster(events, keyframes) {
     const seen = [];
     const index = new Map();
     function add(id) {
@@ -33,14 +34,22 @@ function buildRoster(events) {
             add(evt.playerOut);
         }
     }
+    // Keyframes include non-touching on-court players, so extend the roster to cover them (appended after the event
+    // players, which keep their indices, so the compact events are unaffected).
+    if (keyframes != null)
+        for (const kf of keyframes)
+            if (kf != null)
+                for (const p of kf)
+                    add(p.playerId);
     return index;
 }
 function transformToAttributes(rally, setId) {
-    const playerIndex = buildRoster(rally.events);
+    const playerIndex = buildRoster(rally.events, rally.keyframes);
     const roster = Array.from(playerIndex.keys());
     const payload = {
         r: roster,
-        e: rally.events.map(evt => (0, rally_event_1.transformToCompact)(evt, playerIndex))
+        e: rally.events.map(evt => (0, rally_event_1.transformToCompact)(evt, playerIndex)),
+        ...(rally.keyframes != null ? { k: (0, keyframe_codec_1.encodeKeyframes)(rally.keyframes, playerIndex) } : {})
     };
     const compressed = deflate((0, msgpackr_1.pack)(payload));
     const events = Buffer.from([VERSION_BYTE, ...compressed]);
@@ -81,9 +90,12 @@ function decodeLegacyEvent(event) {
 function transformToObject(model) {
     const raw = model.events;
     let events;
+    let keyframes;
     if (raw[0] === VERSION_BYTE) {
         const payload = (0, msgpackr_1.unpack)(inflate(raw.subarray(1)));
         events = payload.e.map(evt => decodeCompactEvent(evt, payload.r));
+        if (payload.k != null)
+            keyframes = (0, keyframe_codec_1.decodeKeyframes)(payload.k, payload.r);
     }
     else {
         // Legacy: lz-string base64 text stored as UTF-8 bytes in the bytea column
@@ -97,6 +109,7 @@ function transformToObject(model) {
         id: model.rally_id,
         order: model.order,
         servingTeamId: model.serving_team,
-        events
+        events,
+        keyframes
     });
 }

package/dist/cjs/src/data/transformers/rally.test.js

@@ -60,3 +60,36 @@ const rally_1 = require("./rally");
         (0, globals_1.expect)(free.failure).toBe(service_1.FreeBallFailureEnum.NO_FAILURE);
     });
 });
+(0, globals_1.describe)('rally compact round trip — position keyframes', () => {
+    const pA = (0, uuid_1.v4)(); // touches (serve)
+    const pB = (0, uuid_1.v4)(); // touches (reception)
+    const pC = (0, uuid_1.v4)(); // NON-touching: only appears in keyframes, so the roster must be extended to cover it
+    const setId = (0, uuid_1.v4)();
+    const events = [
+        service_1.Serve.create({ playerId: pA, target: 6, score: 55, failure: service_1.ServeFailureEnum.NO_FAILURE, type: service_1.ServeTypeEnum.JUMP_TOPSPIN }),
+        service_1.Reception.create({ playerId: pB, target: 5, score: 50, failure: service_1.ReceptionFailureEnum.NO_FAILURE, type: service_1.ReceptionTypeEnum.DIG })
+    ];
+    const keyframes = [
+        [{ playerId: pA, x: 1.23, y: -2.34 }, { playerId: pB, x: 3, y: 4.5 }, { playerId: pC, x: -4, y: 8 }],
+        [{ playerId: pA, x: 1.23, y: -2.34 }, { playerId: pB, x: -1, y: 2 }, { playerId: pC, x: -4, y: 8 }] // only pB moved
+    ];
+    const rally = service_1.Rally.create({ id: (0, uuid_1.v4)(), order: 0, servingTeamId: (0, uuid_1.v4)(), events, keyframes });
+    (0, globals_1.it)('encodes then decodes the keyframes through the bytea (quantized to 0.1 m, non-toucher included)', () => {
+        const decoded = (0, rally_1.transformToRally)((0, rally_1.transformFromRally)(rally, setId));
+        const kfs = decoded.keyframes ?? [];
+        (0, globals_1.expect)(kfs).toHaveLength(2);
+        const f0 = new Map(kfs[0].map(p => [p.playerId, p]));
+        (0, globals_1.expect)(f0.get(pA)).toEqual({ playerId: pA, x: 1.2, y: -2.3 });
+        (0, globals_1.expect)(f0.get(pB)).toEqual({ playerId: pB, x: 3, y: 4.5 });
+        (0, globals_1.expect)(f0.get(pC)).toEqual({ playerId: pC, x: -4, y: 8 }); // the non-touching player survived the roster extension
+        const f1 = new Map(kfs[1].map(p => [p.playerId, p]));
+        (0, globals_1.expect)(f1.get(pA)).toEqual({ playerId: pA, x: 1.2, y: -2.3 }); // carried forward (unchanged)
+        (0, globals_1.expect)(f1.get(pB)).toEqual({ playerId: pB, x: -1, y: 2 });
+        (0, globals_1.expect)(f1.get(pC)).toEqual({ playerId: pC, x: -4, y: 8 }); // carried forward
+    });
+    (0, globals_1.it)('omits the keyframe block entirely for a rally without keyframes', () => {
+        const plain = service_1.Rally.create({ id: (0, uuid_1.v4)(), order: 0, servingTeamId: (0, uuid_1.v4)(), events });
+        const decoded = (0, rally_1.transformToRally)((0, rally_1.transformFromRally)(plain, setId));
+        (0, globals_1.expect)(decoded.keyframes).toBeUndefined();
+    });
+});

package/dist/cjs/src/service/match/index.d.ts

@@ -10,3 +10,4 @@ export * from './rally-metrics';
 export * from './court-position';
 export * from './match-team';
 export * from './vper';
+export * from './replay-geometry';

package/dist/cjs/src/service/match/index.js

@@ -26,3 +26,4 @@ __exportStar(require("./rally-metrics"), exports);
 __exportStar(require("./court-position"), exports);
 __exportStar(require("./match-team"), exports);
 __exportStar(require("./vper"), exports);
+__exportStar(require("./replay-geometry"), exports);

package/dist/cjs/src/service/match/rally.d.ts

@@ -4,11 +4,17 @@ export interface PlayerPosition {
     position: CourtPosition;
     playerId: string;
 }
+export interface KeyframePosition {
+    readonly playerId: string;
+    readonly x: number;
+    readonly y: number;
+}
 export declare class Rally {
     readonly id: string;
     readonly servingTeamId: string;
     readonly events: RallyEvent[];
     readonly order: number;
+    readonly keyframes?: KeyframePosition[][];
     static create(input: unknown): Rally;
     private constructor();
     addEvent(event: RallyEvent): void;

package/dist/cjs/src/service/match/rally.js

@@ -15,11 +15,12 @@ class Rally {
         }
         return new Rally(result.data);
     }
-    constructor({ id, order, servingTeamId, events }) {
+    constructor({ id, order, servingTeamId, events, keyframes }) {
         this.id = id;
         this.order = order;
         this.servingTeamId = servingTeamId;
         this.events = events;
+        this.keyframes = keyframes;
     }
     addEvent(event) {
         this.events.push(event);

package/dist/cjs/src/service/match/replay-geometry.d.ts

@@ -0,0 +1,8 @@
+import { EventCoord } from '../event/in-play-event';
+export declare const COURT_BASELINE = 9;
+export declare const COURT_HALF_WIDTH = 4.5;
+export type DefendSign = -1 | 1;
+export declare function defendSign(defenderIsHome: boolean): DefendSign;
+export declare function blockCenter(attackSpot: EventCoord, side: DefendSign): EventCoord;
+export declare function joinedBlockerSpots(center: EventCoord, count: number): EventCoord[];
+export declare function failedBlockerSpot(homeNetX: number, center: EventCoord, reach: number): EventCoord;

package/dist/cjs/src/service/match/replay-geometry.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COURT_HALF_WIDTH = exports.COURT_BASELINE = void 0;
+exports.defendSign = defendSign;
+exports.blockCenter = blockCenter;
+exports.joinedBlockerSpots = joinedBlockerSpots;
+exports.failedBlockerSpot = failedBlockerSpot;
+// A back line sits at |y| = 9; the wall stands just off the net on the defending side; the court is 9 m wide.
+exports.COURT_BASELINE = 9;
+exports.COURT_HALF_WIDTH = 4.5;
+const NET_STANDOFF = 0.3; // the block sits this far onto the defending side of the net
+const WALL_ANTENNA = exports.COURT_HALF_WIDTH - 0.1; // keep a drawn token inside the antennas
+const WALL_GAP = 0.75; // side-by-side spacing of blockers in the wall (~shoulder width; also keeps drawn tokens from overlapping)
+function defendSign(defenderIsHome) {
+    return defenderIsHome ? -1 : 1;
+}
+function clampX(x) {
+    return Math.max(-WALL_ANTENNA, Math.min(WALL_ANTENNA, x));
+}
+// The block group CENTER for an attack (owner 2026-08-11): draw the sight line from the DEFENDING back-line center
+// (0, side*9) to the attack spot, and take where it crosses the net. Because the line pivots on the back-line center,
+// a wider or deeper attack pulls the block off the straight-in-front line toward the middle (it takes the line and
+// leaves the cross open), while a straight-on attack sits the block dead in front.
+function blockCenter(attackSpot, side) {
+    const toNet = exports.COURT_BASELINE / (exports.COURT_BASELINE + Math.abs(attackSpot.y)); // fraction of the line from back line to net
+    return { x: clampX(attackSpot.x * toNet), y: side * NET_STANDOFF };
+}
+// The joined blockers stand side by side around the block center along the net. Order the caller's blockers by their
+// base lateral position and hand each the matching slot.
+function joinedBlockerSpots(center, count) {
+    const spots = [];
+    for (let i = 0; i < count; i++) {
+        spots.push({ x: clampX(center.x + (i - (count - 1) / 2) * WALL_GAP), y: center.y });
+    }
+    return spots;
+}
+// A candidate blocker that FAILED its join roll (owner 2026-08-11): if the block spot is within its reach it is drawn
+// where it meant to block; otherwise it is caught out and drawn at the EDGE of its reach on the line toward the block
+// spot. `homeNetX` = the blocker's own net-lane position (its base lateral coord). `reach` = how far along the net it
+// can travel (the sim block model's reflex reach, passed in so this module carries no sim dependency).
+function failedBlockerSpot(homeNetX, center, reach) {
+    const dx = center.x - homeNetX;
+    const step = Math.max(-reach, Math.min(reach, dx));
+    return { x: clampX(homeNetX + step), y: center.y };
+}

package/dist/cjs/src/service/match/replay-geometry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/src/service/match/replay-geometry.test.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const replay_geometry_1 = require("./replay-geometry");
+(0, globals_1.describe)('defendSign', () => {
+    (0, globals_1.it)('maps HOME to -1 (own court y<0) and AWAY to +1', () => {
+        (0, globals_1.expect)((0, replay_geometry_1.defendSign)(true)).toBe(-1);
+        (0, globals_1.expect)((0, replay_geometry_1.defendSign)(false)).toBe(1);
+    });
+});
+(0, globals_1.describe)('blockCenter', () => {
+    (0, globals_1.it)('a straight-on attack (x=0) sits the block dead in front', () => {
+        const c = (0, replay_geometry_1.blockCenter)({ x: 0, y: 3 }, -1);
+        (0, globals_1.expect)(c.x).toBeCloseTo(0, 6);
+        (0, globals_1.expect)(c.y).toBeCloseTo(-0.3, 6); // on the defending (HOME) side of the net
+    });
+    (0, globals_1.it)('a front-row attack (y=3) draws the block from the back-line center', () => {
+        // toNet = 9 / (9 + 3) = 0.75 -> x = 4 * 0.75 = 3.0
+        const c = (0, replay_geometry_1.blockCenter)({ x: 4, y: 3 }, -1);
+        (0, globals_1.expect)(c.x).toBeCloseTo(3, 6);
+        (0, globals_1.expect)(c.y).toBeCloseTo(-0.3, 6);
+    });
+    (0, globals_1.it)('a deeper attack pulls the block further toward the middle (covers the cross)', () => {
+        const shallow = (0, replay_geometry_1.blockCenter)({ x: 4, y: 3 }, -1).x; // 3.0
+        const deep = (0, replay_geometry_1.blockCenter)({ x: 4, y: 9 }, -1).x; // 9/18 = 0.5 -> 2.0
+        (0, globals_1.expect)(deep).toBeCloseTo(2, 6);
+        (0, globals_1.expect)(deep).toBeLessThan(shallow); // deeper attack -> block closer to center
+    });
+    (0, globals_1.it)('mirrors for an AWAY defender (attacker on the y<0 side)', () => {
+        const c = (0, replay_geometry_1.blockCenter)({ x: -4, y: -3 }, 1);
+        (0, globals_1.expect)(c.x).toBeCloseTo(-3, 6);
+        (0, globals_1.expect)(c.y).toBeCloseTo(0.3, 6); // on the defending (AWAY) side of the net
+    });
+    (0, globals_1.it)('clamps the center inside the antennas', () => {
+        const c = (0, replay_geometry_1.blockCenter)({ x: 4.5, y: 0 }, -1); // toNet = 1 -> x would be 4.5
+        (0, globals_1.expect)(c.x).toBeCloseTo(4.4, 6);
+    });
+});
+(0, globals_1.describe)('joinedBlockerSpots', () => {
+    const center = { x: 3, y: -0.3 };
+    (0, globals_1.it)('a single blocker sits on the center', () => {
+        const [a] = (0, replay_geometry_1.joinedBlockerSpots)(center, 1);
+        (0, globals_1.expect)(a.x).toBeCloseTo(3, 6);
+        (0, globals_1.expect)(a.y).toBeCloseTo(-0.3, 6);
+    });
+    (0, globals_1.it)('a double straddles the center by half a gap each', () => {
+        const [a, b] = (0, replay_geometry_1.joinedBlockerSpots)(center, 2);
+        (0, globals_1.expect)(a.x).toBeCloseTo(2.625, 6);
+        (0, globals_1.expect)(b.x).toBeCloseTo(3.375, 6);
+    });
+    (0, globals_1.it)('a triple spreads one gap apart around the center', () => {
+        const [a, b, c] = (0, replay_geometry_1.joinedBlockerSpots)(center, 3);
+        (0, globals_1.expect)(a.x).toBeCloseTo(2.25, 6);
+        (0, globals_1.expect)(b.x).toBeCloseTo(3, 6);
+        (0, globals_1.expect)(c.x).toBeCloseTo(3.75, 6);
+    });
+});
+(0, globals_1.describe)('failedBlockerSpot', () => {
+    const center = { x: 3, y: -0.3 };
+    (0, globals_1.it)('within reach: drawn at the block spot it meant to reach', () => {
+        const s = (0, replay_geometry_1.failedBlockerSpot)(0, center, 5); // dx = 3, reach 5 -> reaches the center
+        (0, globals_1.expect)(s.x).toBeCloseTo(3, 6);
+        (0, globals_1.expect)(s.y).toBeCloseTo(-0.3, 6);
+    });
+    (0, globals_1.it)('out of reach: drawn at the edge of its reach toward the block spot', () => {
+        const s = (0, replay_geometry_1.failedBlockerSpot)(0, center, 1); // dx = 3, reach 1 -> stops 1 m along
+        (0, globals_1.expect)(s.x).toBeCloseTo(1, 6);
+    });
+    (0, globals_1.it)('moves left toward a block spot on its left', () => {
+        const s = (0, replay_geometry_1.failedBlockerSpot)(4, center, 0.5); // dx = -1, reach 0.5 -> 4 - 0.5 = 3.5
+        (0, globals_1.expect)(s.x).toBeCloseTo(3.5, 6);
+    });
+    (0, globals_1.it)('clamps inside the antennas', () => {
+        const s = (0, replay_geometry_1.failedBlockerSpot)(4.3, { x: 4.5, y: -0.3 }, 1); // 4.3 + 0.2 = 4.5 -> clamped
+        (0, globals_1.expect)(s.x).toBeCloseTo(4.4, 6);
+    });
+});

package/dist/cjs/src/service/match/schemas/rally.z.d.ts

@@ -5,5 +5,10 @@ export declare const RallyInputSchema: z.ZodObject<{
     order: z.ZodNumber;
     servingTeamId: z.ZodUUID;
     events: z.ZodArray<z.ZodCustom<RallyEvent, RallyEvent>>;
+    keyframes: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodObject<{
+        playerId: z.ZodString;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>>>;
 }, z.core.$strip>;
 export type RallyInput = z.infer<typeof RallyInputSchema>;

package/dist/cjs/src/service/match/schemas/rally.z.js

@@ -10,5 +10,8 @@ exports.RallyInputSchema = zod_1.z.object({
     servingTeamId: zod_1.z.uuid(),
     events: zod_1.z.array(zod_1.z.custom((v) => v instanceof event_1.RallyEvent, {
         message: 'INVALID_RALLY_EVENT_INSTANCE'
-    }))
+    })),
+    // Optional replay position keyframes (owner 2026-08-11), aligned by index to `events`: keyframes[i] = every
+    // on-court player's coord at events[i]. Present only for captured (user, non-event) matches; visualization only.
+    keyframes: zod_1.z.array(zod_1.z.array(zod_1.z.object({ playerId: zod_1.z.string(), x: zod_1.z.number(), y: zod_1.z.number() }))).optional()
 });

package/dist/cjs/src/service/team/base-config.d.ts

@@ -8,4 +8,5 @@ export interface BaseConfig {
     readonly coords: Record<string, Record<string, Record<string, BaseCoord>>>;
     readonly receive: Record<string, Record<string, boolean>>;
     readonly blocking?: Record<string, Record<string, Record<string, boolean>>>;
+    readonly attackContact?: Record<string, Record<string, BaseCoord>>;
 }

package/dist/cjs/src/service/team/default-base-config.js

@@ -88,11 +88,40 @@ const COORDS = {
         6: { 1: { d: 5.35, r: 2.35 }, 2: { d: 2.05, r: 2.1 }, 3: { d: 0.8, r: 4 }, 4: { d: 2.1, r: -1.95 }, 5: { d: 4.9, r: -1.4 }, 6: { d: 0.4, r: 1.3 } }
     }
 };
+// Per-attacker attack subbases (owner 2026-08-12): the point-of-attack ATK_L/M/R coverage shapes are replaced by ONE
+// subbase per attacker, keyed by the attacker's ZONE (ATK_Z1..ATK_Z6). Each is the whole-team formation used when the
+// attacker at that zone gets the ball. A FRONT-row zone (2/3/4) reuses its lane's old ATK_L/M/R shape, where the lane
+// is ranked by that zone's ATTACK-base lateral this rotation (leftmost r -> ATK_L, middle -> ATK_M, rightmost -> ATK_R);
+// a BACK-row zone (1/5/6) replicates the ATTACK base. Derived from COORDS so the code default and the migration agree.
+// The old ATK_L/M/R stay in COORDS as the derivation SOURCE but are NOT exposed in the default (below).
+const FRONT_ZONES = [2, 3, 4];
+const BACK_ZONES = [1, 5, 6];
+function defaultAttackSubbases() {
+    const cloneFormation = (zones) => {
+        const out = {};
+        for (const [zone, c] of Object.entries(zones))
+            out[zone] = { d: c.d, r: c.r };
+        return out;
+    };
+    const out = { ATK_Z1: {}, ATK_Z2: {}, ATK_Z3: {}, ATK_Z4: {}, ATK_Z5: {}, ATK_Z6: {} };
+    for (let rot = 1; rot <= 6; rot++) {
+        const ranked = [...FRONT_ZONES].sort((a, b) => COORDS.ATTACK[rot][a].r - COORDS.ATTACK[rot][b].r);
+        const laneFor = { [ranked[0]]: 'ATK_L', [ranked[1]]: 'ATK_M', [ranked[2]]: 'ATK_R' };
+        for (const z of FRONT_ZONES)
+            out['ATK_Z' + String(z)][String(rot)] = cloneFormation(COORDS[laneFor[z]][rot]);
+        for (const z of BACK_ZONES)
+            out['ATK_Z' + String(z)][String(rot)] = cloneFormation(COORDS.ATTACK[rot]);
+    }
+    return out;
+}
 // The default coordinate table as a BaseConfig.coords (jsonb string keys). Shared, readonly; materialized (and so
-// serialized) per team on save, so sharing the reference in memory is safe.
+// serialized) per team on save, so sharing the reference in memory is safe. ATK_L/M/R are dropped from the exposed
+// default (replaced by ATK_Z<n>); everything else is copied verbatim from COORDS.
 const DEFAULT_COORDS = (() => {
     const out = {};
     for (const [formation, rotations] of Object.entries(COORDS)) {
+        if (formation === 'ATK_L' || formation === 'ATK_M' || formation === 'ATK_R')
+            continue; // replaced by ATK_Z<n>
         out[formation] = {};
         for (const [rotation, zones] of Object.entries(rotations)) {
             out[formation][rotation] = {};
@@ -100,8 +129,35 @@ const DEFAULT_COORDS = (() => {
                 out[formation][rotation][zone] = { d: coord.d, r: coord.r };
         }
     }
-    return out;
+    return { ...out, ...defaultAttackSubbases() };
 })();
+// The default desired-contact per attacker (trajectory-set, owner 2026-08-12 decision D9): a near-net hitting point
+// in each attacker's lane, NOT the old "set to the standing dot" location. `contact.d` = a near-net depth for the
+// front row or the pipe depth for the back row; `contact.r` = the attacker's ATTACK-dot lateral clamped to the
+// antenna. Keyed [rotation][zone] -> {d,r}. The near-net depth + antenna are first-cut calibration knobs. The sim
+// does not read this yet (added with the engine phase); storing it here is inert. See plans/trajectory-set-and-approach.md.
+const NEAR_NET_CONTACT_DEPTH = 0.5; // front-row contact, m off the net
+const PIPE_CONTACT_DEPTH = 1.8; // back-row (pipe) contact, m off the net (matches the sim's BACKROW_SET_DEPTH)
+const CONTACT_ANTENNA = 4.3; // keep the contact just inside the sideline / antenna
+// LAZY + memoized (not an eager IIFE): `isBackRow` lives in the match module, which sits in a load cycle with the
+// team barrel, so calling it at module-load time hits an uninitialised import. Computed once on first use, then the
+// shared readonly reference is reused (like DEFAULT_COORDS; serialized per team on save, so sharing is safe).
+let cachedAttackContact;
+function defaultAttackContact() {
+    if (cachedAttackContact != null)
+        return cachedAttackContact;
+    const out = {};
+    for (const [rotation, zones] of Object.entries(COORDS.ATTACK)) {
+        out[rotation] = {};
+        for (const [zone, coord] of Object.entries(zones)) {
+            const backRow = (0, match_1.isBackRow)(Number(zone));
+            const r = Math.max(-CONTACT_ANTENNA, Math.min(CONTACT_ANTENNA, coord.r));
+            out[rotation][zone] = { d: backRow ? PIPE_CONTACT_DEPTH : NEAR_NET_CONTACT_DEPTH, r };
+        }
+    }
+    cachedAttackContact = out;
+    return out;
+}
 // The owner's corrected per-point-of-attack block map for the 5-1 (exported 2026-08-09), keyed
 // [DEF_L|DEF_M|DEF_R][rotation][zone] -> canBlock. `false` = that front-row zone sits OUT of the block for an attack
 // from that side; `true` = reads/joins the wall. Only the front-row zones in play for the rotation are tagged. Same
@@ -167,5 +223,5 @@ function defaultReceiveMap(system) {
 // 5-1 uses the owner's exported receive map, the other systems derive their receive map per system.
 function defaultBaseConfig(system) {
     const receive = system === rotation_system_1.RotationSystemEnum.FIVE_ONE ? DEFAULT_5_1_RECEIVE : defaultReceiveMap(system);
-    return { coords: DEFAULT_COORDS, receive, blocking: DEFAULT_BLOCKING };
+    return { coords: DEFAULT_COORDS, receive, blocking: DEFAULT_BLOCKING, attackContact: defaultAttackContact() };
 }

package/dist/cjs/src/service/team/default-base-config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/src/service/team/default-base-config.test.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const rotation_system_1 = require("./rotation-system");
+const default_base_config_1 = require("./default-base-config");
+// Back-row rotational zones (right/left/middle back). Front row is {2,3,4}.
+const BACK_ROW = new Set([1, 5, 6]);
+// The trajectory-set default desired-contact (owner D9, 2026-08-12): a near-net hitting point in each attacker's
+// lane, NOT the old set-to-the-standing-dot location. Front row contacts sit ~0.5 m off the net; back row on the
+// ~1.8 m pipe line; the lateral is the ATTACK-dot's r clamped inside the antenna (|r| <= 4.3).
+describe('defaultBaseConfig attackContact (trajectory-set default)', () => {
+    const cfg = (0, default_base_config_1.defaultBaseConfig)(rotation_system_1.RotationSystemEnum.FIVE_ONE);
+    it('provides a finite desired contact for every rotation and zone', () => {
+        expect(cfg.attackContact).toBeDefined();
+        for (let rot = 1; rot <= 6; rot++) {
+            for (let zone = 1; zone <= 6; zone++) {
+                const c = cfg.attackContact?.[String(rot)]?.[String(zone)];
+                expect(c).toBeDefined();
+                expect(Number.isFinite(c?.d)).toBe(true);
+                expect(Number.isFinite(c?.r)).toBe(true);
+            }
+        }
+    });
+    it('places front-row contacts near the net (0.5 m) and back-row on the pipe line (1.8 m)', () => {
+        for (let rot = 1; rot <= 6; rot++) {
+            for (let zone = 1; zone <= 6; zone++) {
+                const c = cfg.attackContact?.[String(rot)]?.[String(zone)];
+                expect(c.d).toBeCloseTo(BACK_ROW.has(zone) ? 1.8 : 0.5);
+            }
+        }
+    });
+    it('clamps every contact inside the antenna (|r| <= 4.3), even for a wide-pin attack dot', () => {
+        for (let rot = 1; rot <= 6; rot++) {
+            for (let zone = 1; zone <= 6; zone++) {
+                const c = cfg.attackContact?.[String(rot)]?.[String(zone)];
+                expect(Math.abs(c.r)).toBeLessThanOrEqual(4.3 + 1e-9);
+            }
+        }
+    });
+    it('keeps the contact on the attacker approach-lane side (rotation 1 OH wide dot r=5 -> +4.3)', () => {
+        const c = cfg.attackContact?.['1']?.['4'];
+        expect(c.d).toBeCloseTo(0.5); // front row, near the net
+        expect(c.r).toBeCloseTo(4.3); // clamped from the OH's wide ATTACK dot (r=5), same (positive) side
+    });
+});

package/dist/cjs/src/service/team/schemas/tactics.z.d.ts

@@ -305,6 +305,10 @@ export declare const TacticsInputSchema: z.ZodObject<{
         }, z.core.$strip>>>>;
         receive: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodBoolean>>;
         blocking: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodBoolean>>>>;
+        attackContact: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+            d: z.ZodNumber;
+            r: z.ZodNumber;
+        }, z.core.$strip>>>>;
     }, z.core.$strip>>;
     replaceKnockedImmediately: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
     injuryReplacements: z.ZodDefault<z.ZodArray<z.ZodObject<{

package/dist/cjs/src/service/team/schemas/tactics.z.js

@@ -92,7 +92,10 @@ const baseConfigSchema = zod_1.z.object({
     receive: zod_1.z.record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.boolean())),
     // Optional per-point-of-attack blocking (owner 2026-08-07): [DEF_L|DEF_M|DEF_R][rotation][zone] -> canBlock.
     // Optional so presets/tactics saved before this field validate unchanged.
-    blocking: zod_1.z.record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.boolean()))).optional()
+    blocking: zod_1.z.record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.boolean()))).optional(),
+    // Desired attack contact per attacker (trajectory-set, owner 2026-08-12): [rotation][zone] -> {d,r}. Optional so
+    // configs saved before this field validate unchanged.
+    attackContact: zod_1.z.record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), baseCoordSchema)).optional()
 });
 exports.TacticsInputSchema = zod_1.z.object({
     lineup: lineupSchema,

package/dist/cjs/src/service/team/schemas/team.z.d.ts

@@ -313,6 +313,10 @@ export declare const TeamInputSchema: z.ZodObject<{
             }, z.core.$strip>>>>;
             receive: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodBoolean>>;
             blocking: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodBoolean>>>>;
+            attackContact: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+                d: z.ZodNumber;
+                r: z.ZodNumber;
+            }, z.core.$strip>>>>;
         }, z.core.$strip>>;
         replaceKnockedImmediately: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
         injuryReplacements: z.ZodDefault<z.ZodArray<z.ZodObject<{

package/dist/esm/src/data/transformers/keyframe-codec.d.ts

@@ -0,0 +1,7 @@
+export interface KeyframeCoord {
+    readonly playerId: string;
+    readonly x: number;
+    readonly y: number;
+}
+export declare function encodeKeyframes(keyframes: Array<KeyframeCoord[] | undefined>, playerIndex: Map<string, number>): number[][];
+export declare function decodeKeyframes(k: number[][], roster: string[]): KeyframeCoord[][];