volleyballsimtypes 0.0.513 → 0.0.514

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/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[][];

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

@@ -0,0 +1,62 @@
+// 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.
+// 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).
+export 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.
+export 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/esm/src/data/transformers/keyframe-codec.test.d.ts

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

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

@@ -0,0 +1,44 @@
+import { describe, it, expect } from '@jest/globals';
+import { encodeKeyframes, decodeKeyframes } from './keyframe-codec';
+const idx = new Map([['A', 0], ['B', 1]]);
+const roster = ['A', 'B'];
+describe('keyframe-codec round trip', () => {
+    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] = decodeKeyframes(encodeKeyframes(frames, idx), roster);
+        expect(out.find(p => p.playerId === 'A')).toEqual({ playerId: 'A', x: 1.2, y: -2.3 });
+        expect(out.find(p => p.playerId === 'B')).toEqual({ playerId: 'B', x: 3, y: 4.5 });
+    });
+    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 = encodeKeyframes(frames, idx);
+        expect(k[0]).toEqual([0, 10, 10, 1, 30, 30]); // both players
+        expect(k[1]).toEqual([1, -10, 20]); // only B
+        const dec = decodeKeyframes(k, roster);
+        expect(dec[0]).toEqual([{ playerId: 'A', x: 1, y: 1 }, { playerId: 'B', x: 3, y: 3 }]);
+        expect(dec[1]).toEqual([{ playerId: 'A', x: 1, y: 1 }, { playerId: 'B', x: -1, y: 2 }]); // A carried forward
+    });
+    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 = encodeKeyframes(frames, idx);
+        expect(k).toEqual([[0, 10, 10], [], [0, 20, 20]]);
+        const dec = decodeKeyframes(k, roster);
+        expect(dec[1]).toEqual([{ playerId: 'A', x: 1, y: 1 }]); // unchanged at the carry-forward frame
+        expect(dec[2]).toEqual([{ playerId: 'A', x: 2, y: 2 }]);
+    });
+    it('trims trailing empty frames', () => {
+        const frames = [[{ playerId: 'A', x: 1, y: 1 }], undefined, undefined];
+        expect(encodeKeyframes(frames, idx)).toEqual([[0, 10, 10]]);
+    });
+    it('skips players absent from the roster index', () => {
+        const frames = [[{ playerId: 'A', x: 1, y: 1 }, { playerId: 'GHOST', x: 5, y: 5 }]];
+        expect(encodeKeyframes(frames, idx)).toEqual([[0, 10, 10]]);
+    });
+});

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

@@ -2,13 +2,14 @@ import { pack, unpack } from 'msgpackr';
 import { deflateRawSync, inflateRawSync } from 'zlib';
 import { decompressFromBase64 } from 'lz-string';
 import { Block, FreeBall, LiberoReplacement, Rally, Reception, Serve, Set as VolleySet, Spike, Substitution } from '../../service';
+import { encodeKeyframes, decodeKeyframes } from './keyframe-codec';
 import { transformToBlock, transformToCompact, transformToFreeBall, transformToLiberoReplacement, transformToReception, transformToServe, transformToSet, transformToSpike, transformToSubstitution } from './rally-event';
 const VERSION_BYTE = 0x01;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function deflate(data) { return deflateRawSync(data); }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function inflate(data) { return inflateRawSync(data); }
-function buildRoster(events) {
+function buildRoster(events, keyframes) {
     const seen = [];
     const index = new Map();
     function add(id) {
@@ -29,14 +30,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 => transformToCompact(evt, playerIndex))
+        e: rally.events.map(evt => transformToCompact(evt, playerIndex)),
+        ...(rally.keyframes != null ? { k: encodeKeyframes(rally.keyframes, playerIndex) } : {})
     };
     const compressed = deflate(pack(payload));
     const events = Buffer.from([VERSION_BYTE, ...compressed]);
@@ -77,9 +86,12 @@ function decodeLegacyEvent(event) {
 function transformToObject(model) {
     const raw = model.events;
     let events;
+    let keyframes;
     if (raw[0] === VERSION_BYTE) {
         const payload = unpack(inflate(raw.subarray(1)));
         events = payload.e.map(evt => decodeCompactEvent(evt, payload.r));
+        if (payload.k != null)
+            keyframes = decodeKeyframes(payload.k, payload.r);
     }
     else {
         // Legacy: lz-string base64 text stored as UTF-8 bytes in the bytea column
@@ -93,7 +105,8 @@ function transformToObject(model) {
         id: model.rally_id,
         order: model.order,
         servingTeamId: model.serving_team,
-        events
+        events,
+        keyframes
     });
 }
 export { transformToObject as transformToRally, transformToAttributes as transformFromRally };

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

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

package/dist/esm/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/esm/src/service/match/index.js

@@ -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/esm/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/esm/src/service/match/rally.js

@@ -12,11 +12,12 @@ export 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/esm/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/esm/src/service/match/replay-geometry.js

@@ -0,0 +1,38 @@
+// A back line sits at |y| = 9; the wall stands just off the net on the defending side; the court is 9 m wide.
+export const COURT_BASELINE = 9;
+export const 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 = 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)
+export 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.
+export function blockCenter(attackSpot, side) {
+    const toNet = COURT_BASELINE / (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.
+export 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).
+export 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/esm/src/service/match/replay-geometry.test.d.ts

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

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

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

package/dist/esm/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/esm/src/service/match/schemas/rally.z.js

@@ -7,5 +7,8 @@ export const RallyInputSchema = z.object({
     servingTeamId: z.uuid(),
     events: z.array(z.custom((v) => v instanceof 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: z.array(z.array(z.object({ playerId: z.string(), x: z.number(), y: z.number() }))).optional()
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "volleyballsimtypes",
-  "version": "0.0.513",
+  "version": "0.0.514",
   "description": "vbsim types",
   "main": "./dist/cjs/src/index.js",
   "module": "./dist/esm/src/index.js",