@zvk/game-bridge 0.1.0

package/dist/geometry/matrix.js

@@ -0,0 +1,77 @@
+import { convexQuad2, point2, rect2 } from "./types.js";
+export const DEFAULT_AFFINE_EPSILON = 1e-12;
+function validateEpsilon(epsilon) {
+    if (!Number.isFinite(epsilon) || epsilon < 0)
+        throw new RangeError("epsilon must be finite and non-negative");
+}
+function transform(from, to, a, b, c, d, e, f) {
+    return { from, to, a, b, c, d, e, f };
+}
+export function affineTransform(from, to, values) {
+    if (![values.a, values.b, values.c, values.d, values.e, values.f].every(Number.isFinite)) {
+        throw new RangeError("Affine transform components must be finite");
+    }
+    return transform(from, to, values.a, values.b, values.c, values.d, values.e, values.f);
+}
+export function identityTransform(space) {
+    return transform(space, space, 1, 0, 0, 1, 0, 0);
+}
+export function translationTransform(from, to, x, y) {
+    return affineTransform(from, to, { a: 1, b: 0, c: 0, d: 1, e: x, f: y });
+}
+export function scaleTransform(from, to, scaleX, scaleY) {
+    return affineTransform(from, to, { a: scaleX, b: 0, c: 0, d: scaleY, e: 0, f: 0 });
+}
+export function rotationTransform(from, to, radians, origin = { x: 0, y: 0 }) {
+    if (![radians, origin.x, origin.y].every(Number.isFinite))
+        throw new RangeError("Rotation values must be finite");
+    const cosine = Math.cos(radians);
+    const sine = Math.sin(radians);
+    return transform(from, to, cosine, sine, -sine, cosine, origin.x - cosine * origin.x + sine * origin.y, origin.y - sine * origin.x - cosine * origin.y);
+}
+export function composeTransforms(first, second) {
+    return transform(first.from, second.to, second.a * first.a + second.c * first.b, second.b * first.a + second.d * first.b, second.a * first.c + second.c * first.d, second.b * first.c + second.d * first.d, second.a * first.e + second.c * first.f + second.e, second.b * first.e + second.d * first.f + second.f);
+}
+export const determinant = (value) => value.a * value.d - value.b * value.c;
+export function isFiniteTransform(value) {
+    return [value.a, value.b, value.c, value.d, value.e, value.f].every(Number.isFinite);
+}
+export function isInvertibleTransform(value, epsilon = DEFAULT_AFFINE_EPSILON) {
+    validateEpsilon(epsilon);
+    if (!isFiniteTransform(value))
+        return false;
+    const scale = Math.max(1, value.a ** 2 + value.b ** 2 + value.c ** 2 + value.d ** 2);
+    return Math.abs(determinant(value)) > epsilon * scale;
+}
+export function invertTransform(value, epsilon = DEFAULT_AFFINE_EPSILON) {
+    validateEpsilon(epsilon);
+    if (!isFiniteTransform(value))
+        return { ok: false, error: { code: "non-finite-transform" } };
+    if (!isInvertibleTransform(value, epsilon))
+        return { ok: false, error: { code: "non-invertible-transform" } };
+    const det = determinant(value);
+    return { ok: true, value: transform(value.to, value.from, value.d / det, -value.b / det, -value.c / det, value.a / det, (value.c * value.f - value.d * value.e) / det, (value.b * value.e - value.a * value.f) / det) };
+}
+export function transformPoint(value, input) {
+    return point2(value.to, value.a * input.x + value.c * input.y + value.e, value.b * input.x + value.d * input.y + value.f);
+}
+export function transformRectQuad(value, input) {
+    return convexQuad2(value.to, transformPoint(value, point2(value.from, input.x, input.y)), transformPoint(value, point2(value.from, input.x + input.width, input.y)), transformPoint(value, point2(value.from, input.x + input.width, input.y + input.height)), transformPoint(value, point2(value.from, input.x, input.y + input.height)));
+}
+export function transformRectBounds(value, input) {
+    const quad = transformRectQuad(value, input);
+    const xs = [quad.topLeft.x, quad.topRight.x, quad.bottomRight.x, quad.bottomLeft.x];
+    const ys = [quad.topLeft.y, quad.topRight.y, quad.bottomRight.y, quad.bottomLeft.y];
+    const left = Math.min(...xs);
+    const top = Math.min(...ys);
+    return rect2(value.to, left, top, Math.max(...xs) - left, Math.max(...ys) - top);
+}
+export function approximatelyEqualTransform(left, right, epsilon = DEFAULT_AFFINE_EPSILON) {
+    validateEpsilon(epsilon);
+    if (left.from !== right.from || left.to !== right.to)
+        return false;
+    return ["a", "b", "c", "d", "e", "f"].every((key) => {
+        const magnitude = Math.max(1, Math.abs(left[key]), Math.abs(right[key]));
+        return Math.abs(left[key] - right[key]) <= epsilon * magnitude;
+    });
+}

package/dist/geometry/placement.d.ts

@@ -0,0 +1,24 @@
+import { type Point2, type Rect2, type Size2 } from "./types.js";
+import { type Insets2 } from "./visibility.js";
+export type AnchorPlacement = "top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end" | "right" | "right-start" | "right-end";
+export interface AnchoredRectRequest {
+    readonly anchor: Point2<"overlay"> | Rect2<"overlay">;
+    readonly floatingSize: Size2<"overlay">;
+    readonly bounds: Rect2<"overlay">;
+    readonly preferred: AnchorPlacement;
+    readonly fallbacks?: readonly AnchorPlacement[];
+    readonly gap?: number;
+    readonly safeInsets?: Insets2;
+    readonly avoid?: readonly Rect2<"overlay">[];
+    readonly clamp?: boolean;
+}
+export interface AnchoredRectPlacement {
+    readonly rect: Rect2<"overlay">;
+    readonly placement: AnchorPlacement;
+    readonly fits: boolean;
+    readonly clampedX: boolean;
+    readonly clampedY: boolean;
+    readonly overflow: Insets2;
+    readonly avoidedArea: number;
+}
+export declare function placeAnchoredRect(request: AnchoredRectRequest): AnchoredRectPlacement;

package/dist/geometry/placement.js

@@ -0,0 +1,49 @@
+import { rect2 } from "./types.js";
+import { insetRect, overflowInsets, overlapArea } from "./visibility.js";
+const noInsets = { top: 0, right: 0, bottom: 0, left: 0 };
+function anchorRect(anchor) {
+    return "width" in anchor ? anchor : rect2("overlay", anchor.x, anchor.y, 0, 0);
+}
+function candidate(request, placement, safe) {
+    const anchor = anchorRect(request.anchor);
+    const gap = request.gap ?? 0;
+    if (!Number.isFinite(gap) || gap < 0)
+        throw new RangeError("gap must be finite and non-negative");
+    const side = placement.split("-")[0];
+    const alignment = placement.split("-")[1] ?? "center";
+    let x;
+    let y;
+    if (side === "top" || side === "bottom") {
+        y = side === "top" ? anchor.y - gap - request.floatingSize.height : anchor.y + anchor.height + gap;
+        x = alignment === "start" ? anchor.x : alignment === "end" ? anchor.x + anchor.width - request.floatingSize.width : anchor.x + (anchor.width - request.floatingSize.width) / 2;
+    }
+    else {
+        x = side === "left" ? anchor.x - gap - request.floatingSize.width : anchor.x + anchor.width + gap;
+        y = alignment === "start" ? anchor.y : alignment === "end" ? anchor.y + anchor.height - request.floatingSize.height : anchor.y + (anchor.height - request.floatingSize.height) / 2;
+    }
+    let rect = rect2("overlay", x, y, request.floatingSize.width, request.floatingSize.height);
+    let overflow = overflowInsets(rect, safe);
+    const score = overflow.top + overflow.right + overflow.bottom + overflow.left;
+    const avoidedArea = (request.avoid ?? []).reduce((sum, avoided) => sum + overlapArea(rect, avoided), 0);
+    let clampedX = false;
+    let clampedY = false;
+    if (request.clamp) {
+        const nextX = rect.width > safe.width ? safe.x : Math.min(Math.max(rect.x, safe.x), safe.x + safe.width - rect.width);
+        const nextY = rect.height > safe.height ? safe.y : Math.min(Math.max(rect.y, safe.y), safe.y + safe.height - rect.height);
+        clampedX = nextX !== rect.x;
+        clampedY = nextY !== rect.y;
+        rect = rect2("overlay", nextX, nextY, rect.width, rect.height);
+        overflow = overflowInsets(rect, safe);
+    }
+    return { rect, placement, fits: score === 0 && avoidedArea === 0, clampedX, clampedY, overflow, avoidedArea, score };
+}
+export function placeAnchoredRect(request) {
+    if (request.floatingSize.width < 0 || request.floatingSize.height < 0)
+        throw new RangeError("Floating size must be non-negative");
+    const safe = insetRect(request.bounds, request.safeInsets ?? noInsets);
+    const placements = [request.preferred, ...(request.fallbacks ?? [])];
+    const ranked = placements.map((placement, index) => ({ value: candidate(request, placement, safe), index }));
+    ranked.sort((left, right) => left.value.score - right.value.score || left.value.avoidedArea - right.value.avoidedArea || left.index - right.index || left.value.placement.localeCompare(right.value.placement));
+    const { score: _, ...result } = ranked[0].value;
+    return result;
+}

package/dist/geometry/projection.d.ts

@@ -0,0 +1,118 @@
+import { approximatelyEqualTransform, type AffineTransform2D } from "./matrix.js";
+import { type ConvexQuad2, type Point2, type Rect2, type Size2 } from "./types.js";
+import { type VisibilityMargins2 } from "./visibility.js";
+export interface GameBridgeTransformSnapshotV1 {
+    readonly protocolVersion: 1;
+    readonly cameraId: string;
+    readonly capturedAtMs: number;
+    readonly clockId: string;
+    readonly worldToCamera: AffineTransform2D<"world", "camera">;
+    readonly cameraToGame: AffineTransform2D<"camera", "game">;
+    readonly gameToBacking: AffineTransform2D<"game", "backing">;
+    readonly backingToCanvasCss: AffineTransform2D<"backing", "canvas-css">;
+    readonly canvasCssToClient: AffineTransform2D<"canvas-css", "client">;
+    readonly clientToOverlay: AffineTransform2D<"client", "overlay">;
+    readonly cameraViewport: Rect2<"game">;
+    readonly gameLogicalSize: Size2<"game">;
+    readonly gameViewportInBacking: Rect2<"backing">;
+    readonly canvasBackingSize: Size2<"backing">;
+    readonly canvasCssSize: Size2<"canvas-css">;
+    readonly canvasContentClientRect: Rect2<"client">;
+    readonly overlayClientRect: Rect2<"client">;
+    readonly cameraVisible: boolean;
+    readonly roundPixels: boolean;
+}
+export interface ProjectionContext2D {
+    readonly source: GameBridgeTransformSnapshotV1;
+    readonly worldToGame: AffineTransform2D<"world", "game">;
+    readonly gameToWorld: AffineTransform2D<"game", "world">;
+    readonly worldToClient: AffineTransform2D<"world", "client">;
+    readonly clientToWorld: AffineTransform2D<"client", "world">;
+    readonly worldToOverlay: AffineTransform2D<"world", "overlay">;
+    readonly overlayToWorld: AffineTransform2D<"overlay", "world">;
+    readonly gameToOverlay: AffineTransform2D<"game", "overlay">;
+    readonly overlayToGame: AffineTransform2D<"overlay", "game">;
+    readonly cameraClipInGame: Rect2<"game">;
+    readonly canvasClipInClient: ConvexQuad2<"client">;
+    readonly overlayClip: Rect2<"overlay">;
+}
+export interface ProjectionCompileError {
+    readonly code: "unsupported-protocol-version" | "invalid-camera-id" | "invalid-clock-id" | "non-finite-transform" | "non-invertible-transform" | "negative-dimension" | "zero-sized-surface" | "transform-space-mismatch" | "inconsistent-transform-snapshot";
+    readonly message: string;
+}
+export type CompileProjectionContextResult = {
+    readonly ok: true;
+    readonly context: ProjectionContext2D;
+} | {
+    readonly ok: false;
+    readonly error: ProjectionCompileError;
+};
+export type ProjectionVisibilityKind = "visible" | "outside-camera" | "outside-canvas" | "outside-overlay" | "camera-hidden" | "source-hidden";
+export interface ProjectionVisibility {
+    readonly kind: ProjectionVisibilityKind;
+    readonly inCamera: boolean;
+    readonly inCanvas: boolean;
+    readonly inOverlay: boolean;
+}
+export interface ProjectedWorldPoint {
+    readonly worldPoint: Point2<"world">;
+    readonly gamePoint: Point2<"game">;
+    readonly canvasCssPoint: Point2<"canvas-css">;
+    readonly clientPoint: Point2<"client">;
+    readonly overlayPoint: Point2<"overlay">;
+    readonly normalizedPoint: Point2<"normalized">;
+    readonly visibility: ProjectionVisibility;
+}
+export interface ProjectionPointError {
+    readonly code: "invalid-point";
+    readonly message: string;
+}
+export type ProjectWorldPointResult = {
+    readonly ok: true;
+    readonly value: ProjectedWorldPoint;
+} | {
+    readonly ok: false;
+    readonly error: ProjectionPointError;
+};
+export interface ProjectWorldPointsResult {
+    readonly points: readonly ProjectedWorldPoint[];
+    readonly invalid: readonly {
+        readonly index: number;
+        readonly error: ProjectionPointError;
+    }[];
+}
+export type ProjectionRounding = "none" | "integer" | "device-pixel";
+export interface ProjectPointOptions {
+    readonly rounding?: ProjectionRounding;
+    readonly cameraMargins?: VisibilityMargins2;
+    readonly sourceVisible?: boolean;
+}
+export type OutsideProjectionPolicy = "reject" | "allow" | "clamp-to-camera";
+export interface InverseProjectionOptions {
+    readonly outside?: OutsideProjectionPolicy;
+    readonly maxSnapshotAgeMs?: number;
+    readonly nowMs?: number;
+    readonly clockId?: string;
+}
+export type InverseProjectionResult = {
+    readonly ok: true;
+    readonly worldPoint: Point2<"world">;
+    readonly gamePoint: Point2<"game">;
+    readonly wasClamped: boolean;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: "outside-camera" | "outside-canvas" | "stale-snapshot" | "clock-mismatch" | "non-invertible-transform" | "invalid-point";
+    };
+};
+export declare function compileProjectionContext(snapshot: GameBridgeTransformSnapshotV1): CompileProjectionContextResult;
+export declare function toNormalizedPoint(point: Point2<"overlay">, overlaySize: Size2<"overlay">): Point2<"normalized">;
+export declare function fromNormalizedPoint(point: Point2<"normalized">, overlaySize: Size2<"overlay">): Point2<"overlay">;
+export declare function projectWorldPoint(context: ProjectionContext2D, point: Point2<"world">, options?: ProjectPointOptions): ProjectWorldPointResult;
+export declare function projectGamePoint(context: ProjectionContext2D, point: Point2<"game">, options?: ProjectPointOptions): ProjectWorldPointResult;
+export declare function projectWorldPoints(context: ProjectionContext2D, points: readonly Point2<"world">[], options?: ProjectPointOptions, output?: ProjectedWorldPoint[]): ProjectWorldPointsResult;
+export declare function clientPointToWorld(context: ProjectionContext2D, point: Point2<"client">, options?: InverseProjectionOptions): InverseProjectionResult;
+export declare function overlayPointToGame(context: ProjectionContext2D, point: Point2<"overlay">, options?: InverseProjectionOptions): InverseProjectionResult;
+export declare const overlayPointToWorld: typeof overlayPointToGame;
+export declare function areTransformSnapshotsEqual(left: GameBridgeTransformSnapshotV1, right: GameBridgeTransformSnapshotV1): boolean;
+export { approximatelyEqualTransform };

package/dist/geometry/projection.js

@@ -0,0 +1,194 @@
+import { DEFAULT_AFFINE_EPSILON, approximatelyEqualTransform, composeTransforms, invertTransform, isFiniteTransform, transformPoint, transformRectBounds, transformRectQuad, } from "./matrix.js";
+import { isFinitePoint, point2, rect2, } from "./types.js";
+import { clampPointToHalfOpenRect, containsPoint, containsPointInConvexQuad, expandRect, } from "./visibility.js";
+const compileError = (code, message) => ({ ok: false, error: { code, message } });
+const approximately = (left, right) => Math.abs(left - right) <= DEFAULT_AFFINE_EPSILON * Math.max(1, Math.abs(left), Math.abs(right));
+const equalRect = (left, right) => approximately(left.x, right.x) && approximately(left.y, right.y) && approximately(left.width, right.width) && approximately(left.height, right.height);
+const expectedLabels = [
+    ["worldToCamera", "world", "camera"], ["cameraToGame", "camera", "game"],
+    ["gameToBacking", "game", "backing"], ["backingToCanvasCss", "backing", "canvas-css"],
+    ["canvasCssToClient", "canvas-css", "client"], ["clientToOverlay", "client", "overlay"],
+];
+function rawRectIsValid(value) {
+    if (![value.x, value.y, value.width, value.height].every(Number.isFinite))
+        return "finite";
+    return value.width < 0 || value.height < 0 ? "negative" : "ok";
+}
+function rawSizeIsValid(value) {
+    if (![value.width, value.height].every(Number.isFinite))
+        return "finite";
+    return value.width < 0 || value.height < 0 ? "negative" : "ok";
+}
+export function compileProjectionContext(snapshot) {
+    if (snapshot.protocolVersion !== 1)
+        return compileError("unsupported-protocol-version", "Only protocol version 1 is supported");
+    if (typeof snapshot.cameraId !== "string" || snapshot.cameraId.trim() === "")
+        return compileError("invalid-camera-id", "cameraId must be non-empty");
+    if (typeof snapshot.clockId !== "string" || snapshot.clockId.trim() === "" || !Number.isFinite(snapshot.capturedAtMs))
+        return compileError("invalid-clock-id", "clockId must be non-empty and capturedAtMs finite");
+    for (const [key, from, to] of expectedLabels) {
+        const value = snapshot[key];
+        if (value.from !== from || value.to !== to)
+            return compileError("transform-space-mismatch", `${String(key)} must map ${from} to ${to}`);
+        if (!isFiniteTransform(value))
+            return compileError("non-finite-transform", `${String(key)} contains a non-finite component`);
+    }
+    const dimensionValues = [snapshot.cameraViewport, snapshot.gameLogicalSize, snapshot.gameViewportInBacking, snapshot.canvasBackingSize, snapshot.canvasCssSize, snapshot.canvasContentClientRect, snapshot.overlayClientRect];
+    for (const value of dimensionValues) {
+        const validity = "x" in value ? rawRectIsValid(value) : rawSizeIsValid(value);
+        if (validity === "finite")
+            return compileError("non-finite-transform", "Snapshot dimensions and coordinates must be finite");
+        if (validity === "negative")
+            return compileError("negative-dimension", "Snapshot dimensions must be non-negative");
+        if (value.width === 0 || value.height === 0)
+            return compileError("zero-sized-surface", "Projection surfaces must be non-zero");
+    }
+    const { cameraToGame } = snapshot;
+    if (![cameraToGame.a, cameraToGame.d].every((value) => approximately(value, 1)) || ![cameraToGame.b, cameraToGame.c].every((value) => approximately(value, 0)) ||
+        !approximately(cameraToGame.e, snapshot.cameraViewport.x) || !approximately(cameraToGame.f, snapshot.cameraViewport.y)) {
+        return compileError("inconsistent-transform-snapshot", "cameraToGame must be an identity-linear viewport translation");
+    }
+    const gameBounds = rect2("game", 0, 0, snapshot.gameLogicalSize.width, snapshot.gameLogicalSize.height);
+    const backingBounds = rect2("backing", 0, 0, snapshot.canvasBackingSize.width, snapshot.canvasBackingSize.height);
+    const cssBounds = rect2("canvas-css", 0, 0, snapshot.canvasCssSize.width, snapshot.canvasCssSize.height);
+    if (!equalRect(transformRectBounds(snapshot.gameToBacking, gameBounds), snapshot.gameViewportInBacking))
+        return compileError("inconsistent-transform-snapshot", "gameToBacking disagrees with gameViewportInBacking");
+    if (!equalRect(transformRectBounds(snapshot.backingToCanvasCss, backingBounds), cssBounds))
+        return compileError("inconsistent-transform-snapshot", "backingToCanvasCss disagrees with canvasCssSize");
+    if (!equalRect(transformRectBounds(snapshot.canvasCssToClient, cssBounds), snapshot.canvasContentClientRect))
+        return compileError("inconsistent-transform-snapshot", "canvasCssToClient disagrees with canvasContentClientRect");
+    const overlayMapped = transformRectBounds(snapshot.clientToOverlay, snapshot.overlayClientRect);
+    if (!equalRect(overlayMapped, { x: 0, y: 0, width: snapshot.overlayClientRect.width, height: snapshot.overlayClientRect.height }) ||
+        !approximately(snapshot.clientToOverlay.a, 1) || !approximately(snapshot.clientToOverlay.b, 0) || !approximately(snapshot.clientToOverlay.c, 0) || !approximately(snapshot.clientToOverlay.d, 1))
+        return compileError("inconsistent-transform-snapshot", "clientToOverlay must preserve the axis-aligned overlay reference box");
+    const worldToGame = composeTransforms(snapshot.worldToCamera, snapshot.cameraToGame);
+    const gameToCanvasCss = composeTransforms(snapshot.gameToBacking, snapshot.backingToCanvasCss);
+    const gameToClient = composeTransforms(gameToCanvasCss, snapshot.canvasCssToClient);
+    const worldToClient = composeTransforms(worldToGame, gameToClient);
+    const gameToOverlay = composeTransforms(gameToClient, snapshot.clientToOverlay);
+    const worldToOverlay = composeTransforms(worldToClient, snapshot.clientToOverlay);
+    const gameToWorld = invertTransform(worldToGame);
+    const clientToWorld = invertTransform(worldToClient);
+    const overlayToWorld = invertTransform(worldToOverlay);
+    const overlayToGame = invertTransform(gameToOverlay);
+    if (!gameToWorld.ok || !clientToWorld.ok || !overlayToWorld.ok || !overlayToGame.ok)
+        return compileError("non-invertible-transform", "The required projection path is singular");
+    return { ok: true, context: {
+            source: snapshot, worldToGame, gameToWorld: gameToWorld.value, worldToClient, clientToWorld: clientToWorld.value,
+            worldToOverlay, overlayToWorld: overlayToWorld.value, gameToOverlay, overlayToGame: overlayToGame.value,
+            cameraClipInGame: snapshot.cameraViewport,
+            canvasClipInClient: transformRectQuad(snapshot.canvasCssToClient, cssBounds),
+            overlayClip: rect2("overlay", 0, 0, snapshot.overlayClientRect.width, snapshot.overlayClientRect.height),
+        } };
+}
+function calculateVisibility(context, game, client, overlay, options) {
+    const cameraRect = options.cameraMargins === undefined ? context.cameraClipInGame : expandRect(context.cameraClipInGame, options.cameraMargins);
+    const inCamera = containsPoint(cameraRect, game);
+    const inCanvas = containsPointInConvexQuad(context.canvasClipInClient, client);
+    const inOverlay = containsPoint(context.overlayClip, overlay);
+    const kind = options.sourceVisible === false ? "source-hidden" : !context.source.cameraVisible ? "camera-hidden" : !inCamera ? "outside-camera" : !inCanvas ? "outside-canvas" : !inOverlay ? "outside-overlay" : "visible";
+    return { kind, inCamera, inCanvas, inOverlay };
+}
+function roundOverlay(context, point, rounding) {
+    if (rounding === "none")
+        return point;
+    if (rounding === "integer")
+        return point2("overlay", Math.round(point.x), Math.round(point.y));
+    const stepX = Math.hypot(context.source.backingToCanvasCss.a, context.source.backingToCanvasCss.b) || 1;
+    const stepY = Math.hypot(context.source.backingToCanvasCss.c, context.source.backingToCanvasCss.d) || 1;
+    return point2("overlay", Math.round(point.x / stepX) * stepX, Math.round(point.y / stepY) * stepY);
+}
+export function toNormalizedPoint(point, overlaySize) {
+    if (!isFinitePoint(point) || overlaySize.width <= 0 || overlaySize.height <= 0)
+        throw new RangeError("Point must be finite and overlay size must be positive");
+    return point2("normalized", point.x / overlaySize.width, point.y / overlaySize.height);
+}
+export function fromNormalizedPoint(point, overlaySize) {
+    if (!isFinitePoint(point) || overlaySize.width <= 0 || overlaySize.height <= 0)
+        throw new RangeError("Point must be finite and overlay size must be positive");
+    return point2("overlay", point.x * overlaySize.width, point.y * overlaySize.height);
+}
+function projectedFromGame(context, game, world, options) {
+    if (!isFinitePoint(game) || !isFinitePoint(world))
+        return { ok: false, error: { code: "invalid-point", message: "Point coordinates must be finite" } };
+    const backing = transformPoint(context.source.gameToBacking, game);
+    const canvasCss = transformPoint(context.source.backingToCanvasCss, backing);
+    const client = transformPoint(context.source.canvasCssToClient, canvasCss);
+    const unroundedOverlay = transformPoint(context.source.clientToOverlay, client);
+    const overlay = roundOverlay(context, unroundedOverlay, options.rounding ?? "none");
+    const normalized = toNormalizedPoint(overlay, { width: context.overlayClip.width, height: context.overlayClip.height });
+    return { ok: true, value: { worldPoint: world, gamePoint: game, canvasCssPoint: canvasCss, clientPoint: client, overlayPoint: overlay, normalizedPoint: normalized, visibility: calculateVisibility(context, game, client, overlay, options) } };
+}
+export function projectWorldPoint(context, point, options = {}) {
+    if (!isFinitePoint(point))
+        return { ok: false, error: { code: "invalid-point", message: "Point coordinates must be finite" } };
+    return projectedFromGame(context, transformPoint(context.worldToGame, point), point, options);
+}
+export function projectGamePoint(context, point, options = {}) {
+    if (!isFinitePoint(point))
+        return { ok: false, error: { code: "invalid-point", message: "Point coordinates must be finite" } };
+    return projectedFromGame(context, point, transformPoint(context.gameToWorld, point), options);
+}
+export function projectWorldPoints(context, points, options = {}, output = []) {
+    output.length = 0;
+    const invalid = [];
+    points.forEach((point, index) => { const result = projectWorldPoint(context, point, options); if (result.ok)
+        output.push(result.value);
+    else
+        invalid.push({ index, error: result.error }); });
+    return { points: output, invalid };
+}
+function checkAge(context, options) {
+    if (options.maxSnapshotAgeMs === undefined)
+        return null;
+    if (!Number.isFinite(options.maxSnapshotAgeMs) || options.maxSnapshotAgeMs < 0 || !Number.isFinite(options.nowMs) || options.clockId !== context.source.clockId)
+        return { ok: false, error: { code: "clock-mismatch" } };
+    return options.nowMs - context.source.capturedAtMs > options.maxSnapshotAgeMs ? { ok: false, error: { code: "stale-snapshot" } } : null;
+}
+function inverseFromGame(context, gameInput, inCanvas, options) {
+    const age = checkAge(context, options);
+    if (age !== null)
+        return age;
+    if (!isFinitePoint(gameInput))
+        return { ok: false, error: { code: "invalid-point" } };
+    const outside = options.outside ?? "reject";
+    if (outside !== "allow" && !inCanvas)
+        return { ok: false, error: { code: "outside-canvas" } };
+    const inCamera = containsPoint(context.cameraClipInGame, gameInput);
+    if (outside === "reject" && !inCamera)
+        return { ok: false, error: { code: "outside-camera" } };
+    const wasClamped = outside === "clamp-to-camera" && !inCamera;
+    const game = wasClamped ? clampPointToHalfOpenRect(gameInput, context.cameraClipInGame) : gameInput;
+    return { ok: true, gamePoint: game, worldPoint: transformPoint(context.gameToWorld, game), wasClamped };
+}
+export function clientPointToWorld(context, point, options = {}) {
+    if (!isFinitePoint(point))
+        return { ok: false, error: { code: "invalid-point" } };
+    return inverseFromGame(context, transformPoint(composeTransforms(context.clientToWorld, context.worldToGame), point), containsPointInConvexQuad(context.canvasClipInClient, point), options);
+}
+export function overlayPointToGame(context, point, options = {}) {
+    if (!isFinitePoint(point))
+        return { ok: false, error: { code: "invalid-point" } };
+    const overlayToClient = invertTransform(context.source.clientToOverlay);
+    if (!overlayToClient.ok)
+        return { ok: false, error: { code: "non-invertible-transform" } };
+    const client = transformPoint(overlayToClient.value, point);
+    return inverseFromGame(context, transformPoint(context.overlayToGame, point), containsPointInConvexQuad(context.canvasClipInClient, client), options);
+}
+export const overlayPointToWorld = overlayPointToGame;
+function exactTransform(left, right) {
+    return left.from === right.from && left.to === right.to && left.a === right.a && left.b === right.b && left.c === right.c && left.d === right.d && left.e === right.e && left.f === right.f;
+}
+export function areTransformSnapshotsEqual(left, right) {
+    if (left === right)
+        return true;
+    return left.protocolVersion === right.protocolVersion && left.cameraId === right.cameraId && left.capturedAtMs === right.capturedAtMs && left.clockId === right.clockId &&
+        left.cameraVisible === right.cameraVisible && left.roundPixels === right.roundPixels &&
+        expectedLabels.every(([key]) => exactTransform(left[key], right[key])) &&
+        equalRectExact(left.cameraViewport, right.cameraViewport) && equalSizeExact(left.gameLogicalSize, right.gameLogicalSize) &&
+        equalRectExact(left.gameViewportInBacking, right.gameViewportInBacking) && equalSizeExact(left.canvasBackingSize, right.canvasBackingSize) &&
+        equalSizeExact(left.canvasCssSize, right.canvasCssSize) && equalRectExact(left.canvasContentClientRect, right.canvasContentClientRect) && equalRectExact(left.overlayClientRect, right.overlayClientRect);
+}
+const equalRectExact = (left, right) => left.x === right.x && left.y === right.y && left.width === right.width && left.height === right.height;
+const equalSizeExact = (left, right) => left.width === right.width && left.height === right.height;
+export { approximatelyEqualTransform };

package/dist/geometry/types.d.ts

@@ -0,0 +1,62 @@
+export type GameCoordinateSpace = "world" | "camera" | "game" | "backing" | "canvas-css" | "client" | "overlay" | "normalized";
+declare const coordinateSpaceBrand: unique symbol;
+export type CoordinateSpaceBrand<TSpace extends GameCoordinateSpace> = {
+    readonly [coordinateSpaceBrand]: TSpace;
+};
+export type Point2<TSpace extends GameCoordinateSpace> = Readonly<{
+    x: number;
+    y: number;
+}> & CoordinateSpaceBrand<TSpace>;
+export type Vector2<TSpace extends GameCoordinateSpace> = Point2<TSpace>;
+export type Size2<TSpace extends GameCoordinateSpace> = Readonly<{
+    width: number;
+    height: number;
+}> & CoordinateSpaceBrand<TSpace>;
+export type Rect2<TSpace extends GameCoordinateSpace> = Readonly<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}> & CoordinateSpaceBrand<TSpace>;
+export type ConvexQuad2<TSpace extends GameCoordinateSpace> = Readonly<{
+    topLeft: Point2<TSpace>;
+    topRight: Point2<TSpace>;
+    bottomRight: Point2<TSpace>;
+    bottomLeft: Point2<TSpace>;
+}> & CoordinateSpaceBrand<TSpace>;
+export interface GeometryParseError {
+    readonly code: "invalid-value" | "unexpected-field";
+    readonly message: string;
+}
+export type GeometryParseResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: GeometryParseError;
+};
+export interface GeometryParseOptions {
+    readonly strict?: boolean;
+}
+export declare function point2<TSpace extends GameCoordinateSpace>(_space: TSpace, x: number, y: number): Point2<TSpace>;
+export declare const worldPoint: (x: number, y: number) => Point2<"world">;
+export declare const worldVector: (x: number, y: number) => Vector2<"world">;
+export declare const cameraPoint: (x: number, y: number) => Point2<"camera">;
+export declare const gamePoint: (x: number, y: number) => Point2<"game">;
+export declare const backingPoint: (x: number, y: number) => Point2<"backing">;
+export declare const canvasCssPoint: (x: number, y: number) => Point2<"canvas-css">;
+export declare const clientPoint: (x: number, y: number) => Point2<"client">;
+export declare const overlayPoint: (x: number, y: number) => Point2<"overlay">;
+export declare const overlayVector: (x: number, y: number) => Vector2<"overlay">;
+export declare const normalizedPoint: (x: number, y: number) => Point2<"normalized">;
+export declare function size2<TSpace extends GameCoordinateSpace>(_space: TSpace, width: number, height: number): Size2<TSpace>;
+export declare function rect2<TSpace extends GameCoordinateSpace>(_space: TSpace, x: number, y: number, width: number, height: number): Rect2<TSpace>;
+export declare function convexQuad2<TSpace extends GameCoordinateSpace>(_space: TSpace, topLeft: Point2<TSpace>, topRight: Point2<TSpace>, bottomRight: Point2<TSpace>, bottomLeft: Point2<TSpace>): ConvexQuad2<TSpace>;
+export declare function parsePoint2<TSpace extends GameCoordinateSpace>(space: TSpace, value: unknown, options?: GeometryParseOptions): GeometryParseResult<Point2<TSpace>>;
+export declare function parseSize2<TSpace extends GameCoordinateSpace>(space: TSpace, value: unknown, options?: GeometryParseOptions): GeometryParseResult<Size2<TSpace>>;
+export declare function parseRect2<TSpace extends GameCoordinateSpace>(space: TSpace, value: unknown, options?: GeometryParseOptions): GeometryParseResult<Rect2<TSpace>>;
+export declare function isFinitePoint(point: Readonly<{
+    x: number;
+    y: number;
+}>): boolean;
+export {};

package/dist/geometry/types.js

@@ -0,0 +1,79 @@
+function assertFinite(value, name) {
+    if (!Number.isFinite(value)) {
+        throw new RangeError(`${name} must be finite`);
+    }
+}
+function assertDimension(value, name) {
+    assertFinite(value, name);
+    if (value < 0) {
+        throw new RangeError(`${name} must be non-negative`);
+    }
+}
+export function point2(_space, x, y) {
+    assertFinite(x, "x");
+    assertFinite(y, "y");
+    return { x, y };
+}
+export const worldPoint = (x, y) => point2("world", x, y);
+export const worldVector = (x, y) => point2("world", x, y);
+export const cameraPoint = (x, y) => point2("camera", x, y);
+export const gamePoint = (x, y) => point2("game", x, y);
+export const backingPoint = (x, y) => point2("backing", x, y);
+export const canvasCssPoint = (x, y) => point2("canvas-css", x, y);
+export const clientPoint = (x, y) => point2("client", x, y);
+export const overlayPoint = (x, y) => point2("overlay", x, y);
+export const overlayVector = (x, y) => point2("overlay", x, y);
+export const normalizedPoint = (x, y) => point2("normalized", x, y);
+export function size2(_space, width, height) {
+    assertDimension(width, "width");
+    assertDimension(height, "height");
+    return { width, height };
+}
+export function rect2(_space, x, y, width, height) {
+    assertFinite(x, "x");
+    assertFinite(y, "y");
+    assertDimension(width, "width");
+    assertDimension(height, "height");
+    return { x, y, width, height };
+}
+export function convexQuad2(_space, topLeft, topRight, bottomRight, bottomLeft) {
+    return { topLeft, topRight, bottomRight, bottomLeft };
+}
+function parseRecord(value, fields, dimensions, options) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return { ok: false, error: { code: "invalid-value", message: "Expected a plain object" } };
+    }
+    const record = value;
+    for (const field of fields) {
+        if (!Object.prototype.propertyIsEnumerable.call(record, field) || typeof record[field] !== "number" || !Number.isFinite(record[field])) {
+            return { ok: false, error: { code: "invalid-value", message: `${field} must be an own enumerable finite number` } };
+        }
+        if (dimensions.includes(field) && record[field] < 0) {
+            return { ok: false, error: { code: "invalid-value", message: `${field} must be non-negative` } };
+        }
+    }
+    if (options.strict) {
+        const unexpected = Object.keys(record).find((field) => !fields.includes(field));
+        if (unexpected !== undefined) {
+            return { ok: false, error: { code: "unexpected-field", message: `Unexpected field: ${unexpected}` } };
+        }
+    }
+    return { ok: true, value: record };
+}
+export function parsePoint2(space, value, options = {}) {
+    const parsed = parseRecord(value, ["x", "y"], [], options);
+    return parsed.ok ? { ok: true, value: point2(space, parsed.value.x, parsed.value.y) } : parsed;
+}
+export function parseSize2(space, value, options = {}) {
+    const parsed = parseRecord(value, ["width", "height"], ["width", "height"], options);
+    return parsed.ok ? { ok: true, value: size2(space, parsed.value.width, parsed.value.height) } : parsed;
+}
+export function parseRect2(space, value, options = {}) {
+    const parsed = parseRecord(value, ["x", "y", "width", "height"], ["width", "height"], options);
+    return parsed.ok
+        ? { ok: true, value: rect2(space, parsed.value.x, parsed.value.y, parsed.value.width, parsed.value.height) }
+        : parsed;
+}
+export function isFinitePoint(point) {
+    return Number.isFinite(point.x) && Number.isFinite(point.y);
+}

package/dist/geometry/visibility.d.ts

@@ -0,0 +1,30 @@
+import { type ConvexQuad2, type GameCoordinateSpace, type Point2, type Rect2 } from "./types.js";
+export interface Insets2 {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+}
+export interface VisibilityMargins2 {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+}
+export interface RayRectIntersection<TSpace extends GameCoordinateSpace> {
+    readonly point: Point2<TSpace>;
+    readonly edge: "top" | "right" | "bottom" | "left";
+    readonly distance: number;
+}
+export declare function insetRect<TSpace extends GameCoordinateSpace>(rect: Rect2<TSpace>, insets: Insets2): Rect2<TSpace>;
+export declare function expandRect<TSpace extends GameCoordinateSpace>(rect: Rect2<TSpace>, margins: VisibilityMargins2): Rect2<TSpace>;
+export declare function containsPoint<TSpace extends GameCoordinateSpace>(rect: Rect2<TSpace>, point: Point2<TSpace>): boolean;
+export declare function containsPointInConvexQuad<TSpace extends GameCoordinateSpace>(quad: ConvexQuad2<TSpace>, point: Point2<TSpace>): boolean;
+export declare function intersectRects<TSpace extends GameCoordinateSpace>(left: Rect2<TSpace>, right: Rect2<TSpace>): Rect2<TSpace> | null;
+export declare function unionRects<TSpace extends GameCoordinateSpace>(left: Rect2<TSpace>, right: Rect2<TSpace>): Rect2<TSpace>;
+export declare function clampPointToRect<TSpace extends GameCoordinateSpace>(point: Point2<TSpace>, rect: Rect2<TSpace>): Point2<TSpace>;
+export declare function clampPointToHalfOpenRect<TSpace extends GameCoordinateSpace>(point: Point2<TSpace>, rect: Rect2<TSpace>): Point2<TSpace>;
+export declare function closestPointOnRectEdge<TSpace extends GameCoordinateSpace>(point: Point2<TSpace>, rect: Rect2<TSpace>): Point2<TSpace>;
+export declare function intersectRayWithRect<TSpace extends GameCoordinateSpace>(origin: Point2<TSpace>, direction: Point2<TSpace>, rect: Rect2<TSpace>): RayRectIntersection<TSpace> | null;
+export declare function overflowInsets<TSpace extends GameCoordinateSpace>(inner: Rect2<TSpace>, outer: Rect2<TSpace>): Insets2;
+export declare function overlapArea<TSpace extends GameCoordinateSpace>(left: Rect2<TSpace>, right: Rect2<TSpace>): number;