@zvk/game-bridge 0.1.0

package/dist/core/intents.js

@@ -0,0 +1,43 @@
+export function createIntentSink(options = {}) {
+    if (options.onIntent !== undefined && typeof options.onIntent !== "function") {
+        throw new TypeError("onIntent must be a function when provided");
+    }
+    if (options.now !== undefined && typeof options.now !== "function") {
+        throw new TypeError("now must be a function when provided");
+    }
+    let nextSequence = 0;
+    let destroyed = false;
+    let handler = options.onIntent;
+    const now = options.now ?? Date.now;
+    const sink = {
+        dispatch: (intent, dispatchOptions = {}) => {
+            if (destroyed)
+                return { status: "destroyed", sequence: nextSequence };
+            const issuedAtMs = dispatchOptions.issuedAtMs ?? now();
+            if (!Number.isFinite(issuedAtMs)) {
+                throw new RangeError("issuedAtMs must be finite");
+            }
+            const sequence = nextSequence;
+            nextSequence += 1;
+            const envelope = {
+                protocolVersion: 1,
+                sequence,
+                issuedAtMs,
+                ...(dispatchOptions.source === undefined ? {} : { source: dispatchOptions.source }),
+                intent,
+            };
+            if (handler === undefined)
+                return { status: "unhandled", sequence };
+            handler(envelope);
+            return { status: "handled", sequence };
+        },
+    };
+    return {
+        sink,
+        getNextSequence: () => nextSequence,
+        destroy: () => {
+            destroyed = true;
+            handler = undefined;
+        },
+    };
+}

package/dist/core/serializable.d.ts

@@ -0,0 +1,3 @@
+import type { JsonValue } from "./types.js";
+export declare function assertJsonValue(value: unknown, label?: string): asserts value is JsonValue;
+export declare function isJsonValue(value: unknown): value is JsonValue;

package/dist/core/serializable.js

@@ -0,0 +1,71 @@
+function childPath(path, key) {
+    return /^[A-Za-z_$][\w$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+}
+function fail(path, reason) {
+    throw new TypeError(`Expected JSON-compatible data at ${path}: ${reason}`);
+}
+export function assertJsonValue(value, label = "$") {
+    const ancestors = new Set();
+    const visit = (candidate, path) => {
+        if (candidate === null || typeof candidate === "string" || typeof candidate === "boolean")
+            return;
+        if (typeof candidate === "number") {
+            if (!Number.isFinite(candidate))
+                fail(path, "number must be finite");
+            return;
+        }
+        if (typeof candidate !== "object")
+            fail(path, `${typeof candidate} is not JSON-compatible`);
+        const object = candidate;
+        if (ancestors.has(object))
+            fail(path, "cycle detected");
+        ancestors.add(object);
+        try {
+            if (Array.isArray(candidate)) {
+                for (let index = 0; index < candidate.length; index += 1) {
+                    if (!Object.hasOwn(candidate, index))
+                        fail(`${path}[${index}]`, "sparse array slots are not allowed");
+                    const descriptor = Object.getOwnPropertyDescriptor(candidate, index);
+                    if (descriptor === undefined || !descriptor.enumerable) {
+                        fail(`${path}[${index}]`, "non-enumerable array slots are not allowed");
+                    }
+                    if (!("value" in descriptor))
+                        fail(`${path}[${index}]`, "accessor array slots are not allowed");
+                    visit(descriptor.value, `${path}[${index}]`);
+                }
+                const unexpected = Reflect.ownKeys(candidate).filter((key) => key !== "length" && (typeof key === "symbol" || !/^\d+$/.test(key)));
+                if (unexpected.length > 0)
+                    fail(path, "arrays may not contain symbol or named properties");
+                return;
+            }
+            const prototype = Object.getPrototypeOf(candidate);
+            if (prototype !== Object.prototype && prototype !== null) {
+                fail(path, "only plain objects are allowed");
+            }
+            for (const key of Reflect.ownKeys(candidate)) {
+                if (typeof key === "symbol")
+                    fail(path, "symbol keys are not allowed");
+                const descriptor = Object.getOwnPropertyDescriptor(candidate, key);
+                if (descriptor === undefined || !descriptor.enumerable) {
+                    fail(childPath(path, key), "non-enumerable properties are not allowed");
+                }
+                if (!("value" in descriptor))
+                    fail(childPath(path, key), "accessor properties are not allowed");
+                visit(descriptor.value, childPath(path, key));
+            }
+        }
+        finally {
+            ancestors.delete(object);
+        }
+    };
+    visit(value, label);
+}
+export function isJsonValue(value) {
+    try {
+        assertJsonValue(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,17 @@
+export type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+export type GameBridgeDiagnosticSeverity = "info" | "warning" | "error";
+export type GameBridgeDiagnosticCode = "dom-unavailable" | "camera-unavailable" | "camera-id-unavailable" | "canvas-disconnected" | "overlay-disconnected" | "zero-sized-surface" | "invalid-backing-size" | "non-finite-measurement" | "invalid-clock-id" | "non-finite-transform" | "non-invertible-transform" | "inconsistent-transform-snapshot" | "unsupported-css-transform" | "unsupported-camera-transform" | "scheduler-unavailable" | "resize-observer-unavailable" | "capture-callback-threw" | "invalid-anchor" | "duplicate-anchor-id" | "source-frame-regression" | "stale-snapshot" | "clock-mismatch" | "outside-camera" | "outside-canvas" | "outside-overlay" | "ambiguous-camera" | "destroyed";
+export interface GameBridgeDiagnostic {
+    readonly code: GameBridgeDiagnosticCode;
+    readonly severity: GameBridgeDiagnosticSeverity;
+    readonly message: string;
+    readonly anchorId?: string;
+    readonly cameraId?: string;
+    readonly capturedAtMs?: number;
+}

package/dist/core/types.js

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

package/dist/dom/index.d.ts

@@ -0,0 +1,68 @@
+import type { BridgeScheduler } from "../index.js";
+import type { AffineTransform2D, Rect2, Size2 } from "../geometry/index.js";
+export type DomReferenceBox = "content-box" | "padding-box" | "border-box";
+export interface CanvasDomMetrics {
+    readonly capturedAtMs: number;
+    readonly clockId: string;
+    readonly connected: boolean;
+    readonly backingSize: Size2<"backing">;
+    readonly canvasCssSize: Size2<"canvas-css">;
+    readonly canvasContentClientRect: Rect2<"client">;
+    readonly overlayClientRect: Rect2<"client">;
+    readonly backingToCanvasCss: AffineTransform2D<"backing", "canvas-css">;
+    readonly canvasCssToClient: AffineTransform2D<"canvas-css", "client">;
+    readonly clientToOverlay: AffineTransform2D<"client", "overlay">;
+}
+export interface DomMeasurementError {
+    readonly code: "dom-unavailable" | "canvas-disconnected" | "overlay-disconnected" | "zero-sized-surface" | "invalid-backing-size" | "unsupported-css-transform" | "non-finite-measurement" | "invalid-clock-id";
+    readonly message: string;
+}
+export type MeasureGameSurfaceResult = {
+    readonly ok: true;
+    readonly metrics: CanvasDomMetrics;
+} | {
+    readonly ok: false;
+    readonly error: DomMeasurementError;
+};
+export interface MeasureGameSurfaceOptions {
+    readonly canvas: HTMLCanvasElement;
+    readonly overlay: HTMLElement;
+    readonly overlayBox?: DomReferenceBox;
+    readonly capturedAtMs?: number;
+    readonly clockId?: string;
+    readonly cssTransform?: AffineTransform2D<"canvas-css", "client">;
+}
+export declare function readElementReferenceRect(element: Element, box: DomReferenceBox): Rect2<"client">;
+export declare function measureGameSurface(options: MeasureGameSurfaceOptions): MeasureGameSurfaceResult;
+export type AnimationFrameSchedulerResult = {
+    readonly ok: true;
+    readonly scheduler: BridgeScheduler<number>;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: "scheduler-unavailable";
+        readonly message: string;
+    };
+};
+export declare function createAnimationFrameScheduler(target?: Pick<Window, "requestAnimationFrame" | "cancelAnimationFrame">): AnimationFrameSchedulerResult;
+export interface GameSurfaceObserver {
+    readonly measure: () => MeasureGameSurfaceResult;
+    readonly disconnect: () => void;
+}
+export type ObserveGameSurfaceResult = {
+    readonly ok: true;
+    readonly observer: GameSurfaceObserver;
+} | {
+    readonly ok: false;
+    readonly error: DomMeasurementError | {
+        readonly code: "resize-observer-unavailable" | "scheduler-unavailable";
+        readonly message: string;
+    };
+};
+export interface ObserveGameSurfaceOptions extends MeasureGameSurfaceOptions {
+    readonly onChange: (result: MeasureGameSurfaceResult) => void;
+    readonly scheduler?: BridgeScheduler;
+    readonly observeScroll?: boolean;
+    readonly observeVisualViewport?: boolean;
+}
+export declare function observeGameSurface(options: ObserveGameSurfaceOptions): ObserveGameSurfaceResult;

package/dist/dom/index.js

@@ -0,0 +1,244 @@
+const error = (code, message) => ({
+    ok: false,
+    error: { code, message },
+});
+const number = (value) => Number.parseFloat(value) || 0;
+function computedStyle(element) {
+    const view = element.ownerDocument?.defaultView;
+    return view && typeof view.getComputedStyle === "function"
+        ? view.getComputedStyle(element)
+        : null;
+}
+function insetRect(rect, top, right, bottom, left) {
+    return {
+        x: (rect.left ?? rect.x ?? 0) + left,
+        y: (rect.top ?? rect.y ?? 0) + top,
+        width: Math.max(0, rect.width - left - right),
+        height: Math.max(0, rect.height - top - bottom),
+    };
+}
+export function readElementReferenceRect(element, box) {
+    const rect = element.getBoundingClientRect();
+    if (box === "border-box") {
+        return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
+    }
+    const style = computedStyle(element);
+    if (!style) {
+        return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
+    }
+    const borderTop = number(style.borderTopWidth);
+    const borderRight = number(style.borderRightWidth);
+    const borderBottom = number(style.borderBottomWidth);
+    const borderLeft = number(style.borderLeftWidth);
+    const declaredWidth = number(style.width);
+    const declaredHeight = number(style.height);
+    const paddingWidth = number(style.paddingLeft) + number(style.paddingRight);
+    const paddingHeight = number(style.paddingTop) + number(style.paddingBottom);
+    const borderWidth = borderLeft + borderRight;
+    const borderHeight = borderTop + borderBottom;
+    const naturalBorderWidth = style.boxSizing === "border-box" ? declaredWidth : declaredWidth + paddingWidth + borderWidth;
+    const naturalBorderHeight = style.boxSizing === "border-box" ? declaredHeight : declaredHeight + paddingHeight + borderHeight;
+    const scaleX = naturalBorderWidth > 0 ? rect.width / naturalBorderWidth : 1;
+    const scaleY = naturalBorderHeight > 0 ? rect.height / naturalBorderHeight : 1;
+    const paddingRect = insetRect(rect, borderTop * scaleY, borderRight * scaleX, borderBottom * scaleY, borderLeft * scaleX);
+    if (box === "padding-box")
+        return paddingRect;
+    return insetRect(paddingRect, number(style.paddingTop) * scaleY, number(style.paddingRight) * scaleX, number(style.paddingBottom) * scaleY, number(style.paddingLeft) * scaleX);
+}
+function hasUnsupportedTransform(element, stopAfter = null) {
+    for (let current = element; current; current = current.parentElement) {
+        const style = computedStyle(current);
+        const transform = style?.transform;
+        if (transform && transform !== "none") {
+            if (transform.startsWith("matrix3d(") || style?.perspective && style.perspective !== "none")
+                return true;
+            const match = /^matrix\(([^)]+)\)$/.exec(transform);
+            if (!match)
+                return true;
+            const values = match[1]?.split(",").map(Number);
+            if (!values || values.length !== 6 || values.some((value) => !Number.isFinite(value)))
+                return true;
+            if (Math.abs(values[1] ?? 0) > 1e-12 || Math.abs(values[2] ?? 0) > 1e-12)
+                return true;
+        }
+        if (current === stopAfter)
+            break;
+    }
+    return false;
+}
+function resolveClock(options) {
+    const hasTime = options.capturedAtMs !== undefined;
+    const hasId = options.clockId !== undefined;
+    if (hasTime !== hasId) {
+        return hasTime
+            ? { ok: false, result: error("invalid-clock-id", "capturedAtMs and clockId must be supplied together") }
+            : { ok: false, result: error("non-finite-measurement", "capturedAtMs and clockId must be supplied together") };
+    }
+    if (hasTime) {
+        if (!Number.isFinite(options.capturedAtMs))
+            return { ok: false, result: error("non-finite-measurement", "capturedAtMs must be finite") };
+        if (!options.clockId?.trim())
+            return { ok: false, result: error("invalid-clock-id", "clockId must be non-empty") };
+        return { ok: true, capturedAtMs: options.capturedAtMs, clockId: options.clockId };
+    }
+    const performance = options.canvas.ownerDocument?.defaultView?.performance;
+    if (!performance || typeof performance.now !== "function")
+        return { ok: false, result: error("dom-unavailable", "A browser performance clock is unavailable") };
+    return { ok: true, capturedAtMs: performance.now(), clockId: "performance" };
+}
+export function measureGameSurface(options) {
+    const { canvas, overlay } = options;
+    if (!canvas?.ownerDocument?.defaultView || !overlay?.ownerDocument?.defaultView)
+        return error("dom-unavailable", "DOM measurement is unavailable");
+    if (!canvas.isConnected)
+        return error("canvas-disconnected", "Canvas is disconnected");
+    if (!overlay.isConnected)
+        return error("overlay-disconnected", "Overlay is disconnected");
+    const clock = resolveClock(options);
+    if (!clock.ok)
+        return clock.result;
+    if (!Number.isFinite(canvas.width) || !Number.isFinite(canvas.height) || canvas.width <= 0 || canvas.height <= 0)
+        return error("invalid-backing-size", "Canvas backing dimensions must be finite and positive");
+    if ((!options.cssTransform && hasUnsupportedTransform(canvas)) || hasUnsupportedTransform(overlay))
+        return error("unsupported-css-transform", "Rotation, skew, or perspective requires an explicit supported transform");
+    const content = readElementReferenceRect(canvas, "content-box");
+    const overlayRect = readElementReferenceRect(overlay, options.overlayBox ?? "padding-box");
+    const values = [content.x, content.y, content.width, content.height, overlayRect.x, overlayRect.y, overlayRect.width, overlayRect.height];
+    if (values.some((value) => !Number.isFinite(value)))
+        return error("non-finite-measurement", "DOM measurement contained a non-finite value");
+    if (content.width <= 0 || content.height <= 0 || overlayRect.width <= 0 || overlayRect.height <= 0)
+        return error("zero-sized-surface", "Canvas or overlay has zero size");
+    const style = computedStyle(canvas);
+    const declaredWidth = style ? number(style.width) : 0;
+    const declaredHeight = style ? number(style.height) : 0;
+    const cssWidth = declaredWidth > 0
+        ? (style?.boxSizing === "border-box" ? Math.max(0, declaredWidth - number(style.borderLeftWidth) - number(style.borderRightWidth) - number(style.paddingLeft) - number(style.paddingRight)) : declaredWidth)
+        : content.width;
+    const cssHeight = declaredHeight > 0
+        ? (style?.boxSizing === "border-box" ? Math.max(0, declaredHeight - number(style.borderTopWidth) - number(style.borderBottomWidth) - number(style.paddingTop) - number(style.paddingBottom)) : declaredHeight)
+        : content.height;
+    if (cssWidth <= 0 || cssHeight <= 0)
+        return error("zero-sized-surface", "Canvas CSS content box has zero size");
+    const backingToCanvasCss = {
+        from: "backing", to: "canvas-css", a: cssWidth / canvas.width, b: 0, c: 0,
+        d: cssHeight / canvas.height, e: 0, f: 0,
+    };
+    const canvasCssToClient = options.cssTransform ?? {
+        from: "canvas-css", to: "client", a: content.width / cssWidth, b: 0, c: 0, d: content.height / cssHeight, e: content.x, f: content.y,
+    };
+    const clientToOverlay = {
+        from: "client", to: "overlay", a: 1, b: 0, c: 0, d: 1, e: -overlayRect.x, f: -overlayRect.y,
+    };
+    return {
+        ok: true,
+        metrics: Object.freeze({
+            capturedAtMs: clock.capturedAtMs,
+            clockId: clock.clockId,
+            connected: true,
+            backingSize: Object.freeze({ width: canvas.width, height: canvas.height }),
+            canvasCssSize: Object.freeze({ width: cssWidth, height: cssHeight }),
+            canvasContentClientRect: Object.freeze(content),
+            overlayClientRect: Object.freeze(overlayRect),
+            backingToCanvasCss: Object.freeze(backingToCanvasCss),
+            canvasCssToClient: Object.freeze(canvasCssToClient),
+            clientToOverlay: Object.freeze(clientToOverlay),
+        }),
+    };
+}
+export function createAnimationFrameScheduler(target) {
+    const candidate = target ?? (typeof window === "undefined" ? undefined : window);
+    if (!candidate)
+        return { ok: false, error: { code: "scheduler-unavailable", message: "Animation frame scheduling is unavailable" } };
+    if (typeof candidate.requestAnimationFrame !== "function" || typeof candidate.cancelAnimationFrame !== "function")
+        throw new TypeError("Animation frame scheduler members must be functions");
+    return {
+        ok: true,
+        scheduler: {
+            request: (flush) => candidate.requestAnimationFrame(flush),
+            cancel: (handle) => candidate.cancelAnimationFrame(handle),
+        },
+    };
+}
+function measurementKey(result) {
+    if (!result.ok)
+        return `error:${result.error.code}:${result.error.message}`;
+    const { capturedAtMs: _time, ...meaning } = result.metrics;
+    return JSON.stringify(meaning);
+}
+export function observeGameSurface(options) {
+    const view = options.canvas?.ownerDocument?.defaultView;
+    if (!view)
+        return { ok: false, error: { code: "dom-unavailable", message: "DOM observation is unavailable" } };
+    const ResizeObserverConstructor = view.ResizeObserver;
+    if (typeof ResizeObserverConstructor !== "function")
+        return { ok: false, error: { code: "resize-observer-unavailable", message: "ResizeObserver is unavailable" } };
+    const animationScheduler = options.scheduler ? undefined : createAnimationFrameScheduler(view);
+    if (animationScheduler && !animationScheduler.ok)
+        return animationScheduler;
+    const request = options.scheduler
+        ? options.scheduler.request
+        : (flush) => animationScheduler.scheduler.request(flush);
+    const cancel = options.scheduler
+        ? options.scheduler.cancel
+        : (handle) => animationScheduler.scheduler.cancel(handle);
+    let disconnected = false;
+    let pending;
+    let scheduled = false;
+    let lastKey = "";
+    const measure = () => measureGameSurface(options);
+    const emit = () => {
+        pending = undefined;
+        scheduled = false;
+        if (disconnected)
+            return;
+        const result = measure();
+        const key = measurementKey(result);
+        if (key !== lastKey) {
+            lastKey = key;
+            options.onChange(result);
+        }
+    };
+    const schedule = () => {
+        if (disconnected || scheduled)
+            return;
+        scheduled = true;
+        pending = request(emit);
+    };
+    const resizeObserver = new ResizeObserverConstructor(schedule);
+    resizeObserver.observe(options.canvas);
+    resizeObserver.observe(options.overlay);
+    view.addEventListener("resize", schedule);
+    view.document.addEventListener("fullscreenchange", schedule);
+    if (options.observeScroll !== false)
+        view.addEventListener("scroll", schedule, true);
+    const visualViewport = view.visualViewport;
+    const observeViewport = options.observeVisualViewport ?? Boolean(visualViewport);
+    if (observeViewport && visualViewport) {
+        visualViewport.addEventListener("resize", schedule);
+        visualViewport.addEventListener("scroll", schedule);
+    }
+    emit();
+    return {
+        ok: true,
+        observer: {
+            measure,
+            disconnect: () => {
+                if (disconnected)
+                    return;
+                disconnected = true;
+                resizeObserver.disconnect();
+                view.removeEventListener("resize", schedule);
+                view.document.removeEventListener("fullscreenchange", schedule);
+                view.removeEventListener("scroll", schedule, true);
+                if (visualViewport) {
+                    visualViewport.removeEventListener("resize", schedule);
+                    visualViewport.removeEventListener("scroll", schedule);
+                }
+                if (scheduled)
+                    cancel(pending);
+                pending = undefined;
+                scheduled = false;
+            },
+        },
+    };
+}

package/dist/geometry/anchors.d.ts

@@ -0,0 +1,48 @@
+import type { GameBridgeDiagnostic, JsonValue } from "../core/types.js";
+import { type ProjectionContext2D, type ProjectedWorldPoint, type ProjectionPointError, type ProjectionRounding } from "./projection.js";
+import { type Point2, type Vector2 } from "./types.js";
+export interface WorldAnchorSnapshot<TMetadata extends JsonValue = JsonValue> {
+    readonly id: string;
+    readonly worldPoint: Point2<"world">;
+    readonly worldOffset?: Vector2<"world">;
+    readonly overlayOffset?: Vector2<"overlay">;
+    readonly sourceVisible?: boolean;
+    readonly metadata?: TMetadata;
+}
+export interface AnchorValidationError {
+    readonly code: "empty-anchor-id" | "invalid-anchor";
+    readonly message: string;
+}
+export interface ProjectedWorldAnchor<TMetadata extends JsonValue = JsonValue> extends ProjectedWorldPoint {
+    readonly id: string;
+    readonly metadata?: TMetadata;
+}
+export interface ProjectWorldAnchorsOptions {
+    readonly rounding?: ProjectionRounding;
+    readonly cameraMargins?: import("./visibility.js").VisibilityMargins2;
+    readonly invalidAnchorPolicy?: "omit" | "fail-batch";
+    readonly duplicateIdPolicy?: "fail-batch" | "keep-first";
+}
+export interface InvalidWorldAnchorProjection {
+    readonly index: number;
+    readonly id?: string;
+    readonly error: ProjectionPointError | AnchorValidationError;
+}
+export type ProjectWorldAnchorsResult<TMetadata extends JsonValue = JsonValue> = {
+    readonly ok: true;
+    readonly anchors: readonly ProjectedWorldAnchor<TMetadata>[];
+    readonly invalid: readonly InvalidWorldAnchorProjection[];
+    readonly diagnostics: readonly GameBridgeDiagnostic[];
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: "duplicate-anchor-id" | "invalid-anchor-batch";
+        readonly anchorId?: string;
+        readonly message: string;
+    };
+    readonly invalid: readonly InvalidWorldAnchorProjection[];
+    readonly diagnostics: readonly GameBridgeDiagnostic[];
+};
+export declare function projectWorldAnchors<TMetadata extends JsonValue = JsonValue>(context: ProjectionContext2D, anchors: readonly WorldAnchorSnapshot<TMetadata>[], options?: ProjectWorldAnchorsOptions): ProjectWorldAnchorsResult<TMetadata>;
+export declare function areProjectedWorldAnchorsEqual(left: readonly ProjectedWorldAnchor[], right: readonly ProjectedWorldAnchor[]): boolean;
+export declare function reuseProjectedAnchors<TMetadata extends JsonValue>(previous: readonly ProjectedWorldAnchor<TMetadata>[], next: readonly ProjectedWorldAnchor<TMetadata>[]): readonly ProjectedWorldAnchor<TMetadata>[];

package/dist/geometry/anchors.js

@@ -0,0 +1,96 @@
+import { projectWorldPoint } from "./projection.js";
+import { containsPoint } from "./visibility.js";
+import { point2 } from "./types.js";
+const finitePoint = (value) => value === undefined || (Number.isFinite(value.x) && Number.isFinite(value.y));
+function diagnostic(message, anchorId, duplicate = false) {
+    return anchorId === undefined
+        ? { code: duplicate ? "duplicate-anchor-id" : "invalid-anchor", severity: "warning", message }
+        : { code: duplicate ? "duplicate-anchor-id" : "invalid-anchor", severity: "warning", message, anchorId };
+}
+function roundedOverlay(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 projectWorldAnchors(context, anchors, options = {}) {
+    const projected = [];
+    const invalid = [];
+    const diagnostics = [];
+    const seen = new Set();
+    for (let index = 0; index < anchors.length; index += 1) {
+        const anchor = anchors[index];
+        if (typeof anchor.id !== "string" || anchor.id.trim() === "") {
+            const error = { code: "empty-anchor-id", message: "Anchor ID must be non-empty" };
+            invalid.push({ index, ...(typeof anchor.id === "string" ? { id: anchor.id } : {}), error });
+            diagnostics.push(diagnostic(error.message));
+            continue;
+        }
+        if (seen.has(anchor.id)) {
+            const error = { code: "invalid-anchor", message: `Duplicate anchor ID: ${anchor.id}` };
+            invalid.push({ index, id: anchor.id, error });
+            diagnostics.push(diagnostic(error.message, anchor.id, true));
+            if ((options.duplicateIdPolicy ?? "fail-batch") === "fail-batch") {
+                return { ok: false, error: { code: "duplicate-anchor-id", anchorId: anchor.id, message: error.message }, invalid, diagnostics };
+            }
+            continue;
+        }
+        seen.add(anchor.id);
+        if (!finitePoint(anchor.worldPoint) || !finitePoint(anchor.worldOffset) || !finitePoint(anchor.overlayOffset)) {
+            const error = { code: "invalid-anchor", message: `Anchor ${anchor.id} contains a non-finite point or offset` };
+            invalid.push({ index, id: anchor.id, error });
+            diagnostics.push(diagnostic(error.message, anchor.id));
+            continue;
+        }
+        const world = point2("world", anchor.worldPoint.x + (anchor.worldOffset?.x ?? 0), anchor.worldPoint.y + (anchor.worldOffset?.y ?? 0));
+        const result = projectWorldPoint(context, world, {
+            rounding: "none",
+            ...(options.cameraMargins === undefined ? {} : { cameraMargins: options.cameraMargins }),
+            ...(anchor.sourceVisible === undefined ? {} : { sourceVisible: anchor.sourceVisible }),
+        });
+        if (!result.ok) {
+            invalid.push({ index, id: anchor.id, error: result.error });
+            diagnostics.push(diagnostic(result.error.message, anchor.id));
+            continue;
+        }
+        const overlay = roundedOverlay(context, point2("overlay", result.value.overlayPoint.x + (anchor.overlayOffset?.x ?? 0), result.value.overlayPoint.y + (anchor.overlayOffset?.y ?? 0)), options.rounding ?? "none");
+        const normalized = point2("normalized", overlay.x / context.overlayClip.width, overlay.y / context.overlayClip.height);
+        const inOverlay = containsPoint(context.overlayClip, overlay);
+        const visibility = { ...result.value.visibility, inOverlay,
+            kind: result.value.visibility.kind === "source-hidden" || result.value.visibility.kind === "camera-hidden" || result.value.visibility.kind === "outside-camera" || result.value.visibility.kind === "outside-canvas"
+                ? result.value.visibility.kind : inOverlay ? "visible" : "outside-overlay" };
+        projected.push({ ...result.value, id: anchor.id, overlayPoint: overlay, normalizedPoint: normalized, visibility, ...(anchor.metadata === undefined ? {} : { metadata: anchor.metadata }) });
+    }
+    if (invalid.length > 0 && options.invalidAnchorPolicy === "fail-batch") {
+        return { ok: false, error: { code: "invalid-anchor-batch", message: "One or more anchors were invalid" }, invalid, diagnostics };
+    }
+    return { ok: true, anchors: projected, invalid, diagnostics };
+}
+function equalPoint(left, right) { return left.x === right.x && left.y === right.y; }
+function equalAnchor(left, right) {
+    return left.id === right.id && left.metadata === right.metadata && equalPoint(left.worldPoint, right.worldPoint) && equalPoint(left.gamePoint, right.gamePoint) &&
+        equalPoint(left.canvasCssPoint, right.canvasCssPoint) && equalPoint(left.clientPoint, right.clientPoint) && equalPoint(left.overlayPoint, right.overlayPoint) &&
+        equalPoint(left.normalizedPoint, right.normalizedPoint) && left.visibility.kind === right.visibility.kind && left.visibility.inCamera === right.visibility.inCamera &&
+        left.visibility.inCanvas === right.visibility.inCanvas && left.visibility.inOverlay === right.visibility.inOverlay;
+}
+export function areProjectedWorldAnchorsEqual(left, right) {
+    return left === right || (left.length === right.length && left.every((anchor, index) => equalAnchor(anchor, right[index])));
+}
+export function reuseProjectedAnchors(previous, next) {
+    const byId = new Map(previous.map((anchor) => [anchor.id, anchor]));
+    let changed = previous.length !== next.length;
+    const reused = next.map((anchor, index) => {
+        const prior = byId.get(anchor.id);
+        if (prior !== undefined && equalAnchor(prior, anchor)) {
+            if (prior !== previous[index])
+                changed = true;
+            return prior;
+        }
+        changed = true;
+        return anchor;
+    });
+    return changed ? reused : previous;
+}

package/dist/geometry/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./matrix.js";
+export * from "./visibility.js";
+export * from "./projection.js";
+export * from "./anchors.js";
+export * from "./placement.js";

package/dist/geometry/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./matrix.js";
+export * from "./visibility.js";
+export * from "./projection.js";
+export * from "./anchors.js";
+export * from "./placement.js";

package/dist/geometry/matrix.d.ts

@@ -0,0 +1,45 @@
+import { type ConvexQuad2, type GameCoordinateSpace, type Point2, type Rect2 } from "./types.js";
+export declare const DEFAULT_AFFINE_EPSILON = 1e-12;
+export interface AffineTransform2D<TFrom extends GameCoordinateSpace, TTo extends GameCoordinateSpace> {
+    readonly from: TFrom;
+    readonly to: TTo;
+    readonly a: number;
+    readonly b: number;
+    readonly c: number;
+    readonly d: number;
+    readonly e: number;
+    readonly f: number;
+}
+export type InvertTransformResult<TFrom extends GameCoordinateSpace, TTo extends GameCoordinateSpace> = {
+    readonly ok: true;
+    readonly value: AffineTransform2D<TTo, TFrom>;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: "non-finite-transform" | "non-invertible-transform";
+    };
+};
+export declare function affineTransform<TFrom extends GameCoordinateSpace, TTo extends GameCoordinateSpace>(from: TFrom, to: TTo, values: Readonly<{
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+}>): AffineTransform2D<TFrom, TTo>;
+export declare function identityTransform<TSpace extends GameCoordinateSpace>(space: TSpace): AffineTransform2D<TSpace, TSpace>;
+export declare function translationTransform<TFrom extends GameCoordinateSpace, TTo extends GameCoordinateSpace>(from: TFrom, to: TTo, x: number, y: number): AffineTransform2D<TFrom, TTo>;
+export declare function scaleTransform<TFrom extends GameCoordinateSpace, TTo extends GameCoordinateSpace>(from: TFrom, to: TTo, scaleX: number, scaleY: number): AffineTransform2D<TFrom, TTo>;
+export declare function rotationTransform<TFrom extends GameCoordinateSpace, TTo extends GameCoordinateSpace>(from: TFrom, to: TTo, radians: number, origin?: Readonly<{
+    x: number;
+    y: number;
+}>): AffineTransform2D<TFrom, TTo>;
+export declare function composeTransforms<A extends GameCoordinateSpace, B extends GameCoordinateSpace, C extends GameCoordinateSpace>(first: AffineTransform2D<A, B>, second: AffineTransform2D<B, C>): AffineTransform2D<A, C>;
+export declare const determinant: (value: AffineTransform2D<GameCoordinateSpace, GameCoordinateSpace>) => number;
+export declare function isFiniteTransform(value: AffineTransform2D<GameCoordinateSpace, GameCoordinateSpace>): boolean;
+export declare function isInvertibleTransform(value: AffineTransform2D<GameCoordinateSpace, GameCoordinateSpace>, epsilon?: number): boolean;
+export declare function invertTransform<TFrom extends GameCoordinateSpace, TTo extends GameCoordinateSpace>(value: AffineTransform2D<TFrom, TTo>, epsilon?: number): InvertTransformResult<TFrom, TTo>;
+export declare function transformPoint<TFrom extends GameCoordinateSpace, TTo extends GameCoordinateSpace>(value: AffineTransform2D<TFrom, TTo>, input: Point2<TFrom>): Point2<TTo>;
+export declare function transformRectQuad<TFrom extends GameCoordinateSpace, TTo extends GameCoordinateSpace>(value: AffineTransform2D<TFrom, TTo>, input: Rect2<TFrom>): ConvexQuad2<TTo>;
+export declare function transformRectBounds<TFrom extends GameCoordinateSpace, TTo extends GameCoordinateSpace>(value: AffineTransform2D<TFrom, TTo>, input: Rect2<TFrom>): Rect2<TTo>;
+export declare function approximatelyEqualTransform(left: AffineTransform2D<GameCoordinateSpace, GameCoordinateSpace>, right: AffineTransform2D<GameCoordinateSpace, GameCoordinateSpace>, epsilon?: number): boolean;