rn-gamekit 0.1.0 → 0.2.1

package/src/events/payload.ts

@@ -0,0 +1,234 @@
+import { GameEventError } from './errors';
+
+const MAX_PAYLOAD_NODES = 512;
+const MAX_PAYLOAD_DEPTH = 10;
+const MAX_PAYLOAD_STRING_LENGTH = 4096;
+const MAX_PAYLOAD_ARRAY_LENGTH = 256;
+
+/**
+ * Validate, clone, and deeply freeze a payload.
+ *
+ * Accepted: finite numbers, strings, booleans, `null`, `undefined` (as an
+ * optional property value), arrays, and plain records (`Object.prototype`
+ * or `Object.create(null)`). Rejected: functions, symbols, bigints,
+ * promises/thenables, sparse arrays, class instances, unsafe prototypes,
+ * native handles, React elements (`$$typeof`), cycles, accessors,
+ * non-enumerable properties, and non-finite numbers. Errors are reported
+ * with `Event "<name>" payload invalid at <path>`.
+ *
+ * The clone is frozen deeply so callers cannot mutate the staged envelope.
+ */
+export function cloneAndValidatePayload(
+  payload: unknown,
+  eventName: string,
+  basePath = 'payload',
+): unknown {
+  let nodeCount = 0;
+  // Ancestry set — only the current recursion stack, not the entire visited graph.
+  // Shared acyclic references are allowed; true cycles are rejected.
+  const ancestry = new WeakSet<object>();
+
+  const fail = (path: string, reason: string): never => {
+    throw new GameEventError(`Event "${eventName}" payload invalid at ${path}: ${reason}`);
+  };
+
+  const isPlainRecord = (value: object): boolean => {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+  };
+
+  const isReactElement = (value: object): boolean => {
+    // Use descriptor to avoid invoking a getter for $$typeof.
+    const desc = Object.getOwnPropertyDescriptor(value, '$$typeof' as unknown as string);
+    if (desc !== undefined) {
+      return true;
+    }
+    // Also check prototype chain via `in` without invoking getter? `in` can invoke proxy traps but not getters.
+    // For safety, also check `Object.prototype.hasOwnProperty` on the object and its prototype chain via `in`.
+    // If the object has a getter for $$typeof on its prototype, `in` will not invoke it, but `'$$typeof' in value` will still
+    // check presence without invoking. We use `in` as a fallback that does not execute the getter.
+    return '$$typeof' in (value as Record<string, unknown>);
+  };
+
+  const clone = (value: unknown, path: string, depth: number): unknown => {
+    if (depth > MAX_PAYLOAD_DEPTH) {
+      fail(path, `exceeds maximum depth of ${MAX_PAYLOAD_DEPTH}`);
+    }
+    nodeCount += 1;
+    if (nodeCount > MAX_PAYLOAD_NODES) {
+      fail(path, `exceeds maximum payload size of ${MAX_PAYLOAD_NODES} nodes`);
+    }
+
+    if (value === null || value === undefined) {
+      return value;
+    }
+    const type = typeof value;
+    if (type === 'string') {
+      const str = value as string;
+      if (str.length > MAX_PAYLOAD_STRING_LENGTH) {
+        fail(path, `string exceeds maximum length of ${MAX_PAYLOAD_STRING_LENGTH}`);
+      }
+      return str;
+    }
+    if (type === 'boolean') {
+      return value;
+    }
+    if (type === 'number') {
+      const num = value as number;
+      if (!Number.isFinite(num)) {
+        fail(path, 'number must be finite');
+      }
+      return num;
+    }
+    if (type === 'bigint') {
+      fail(path, 'bigint is not a supported payload type');
+    }
+    if (type === 'symbol') {
+      fail(path, 'symbol is not a supported payload type');
+    }
+    if (type === 'function') {
+      fail(path, 'function is not a supported payload type');
+    }
+    if (type !== 'object') {
+      fail(path, `unsupported payload type "${type}"`);
+    }
+
+    const obj = value as object;
+    if (ancestry.has(obj)) {
+      fail(path, 'cycle detected in payload');
+    }
+    ancestry.add(obj);
+
+    // Use try/finally to ensure ancestry is cleaned even when we throw.
+    try {
+      // GS-EVENT-03: thenables are rejected without invoking any user code.
+      // Only safe operations run here (instanceof, getPrototypeOf, own
+      // descriptors). A Promise fails with its useful path; every other
+      // non-plain object fails at the array/record branches below — the
+      // preliminary inherited `.then` read that could execute a getter is
+      // gone. Own `then` functions are rejected later as function values.
+      if (obj instanceof Promise) {
+        fail(path, 'promise/thenable is not a supported payload type');
+      }
+
+      if (isReactElement(obj)) {
+        fail(path, 'React element is not a supported payload type');
+      }
+
+      if (Array.isArray(obj)) {
+        const arr = obj as unknown[];
+        if (Object.getPrototypeOf(arr) !== Array.prototype) {
+          fail(path, 'array subclass is not a supported payload type');
+        }
+        if (arr.length > MAX_PAYLOAD_ARRAY_LENGTH) {
+          fail(path, `array exceeds maximum length of ${MAX_PAYLOAD_ARRAY_LENGTH}`);
+        }
+
+        // Use descriptors to avoid invoking getters and to detect sparse holes.
+        const descs = Object.getOwnPropertyDescriptors(arr);
+        // Sparse check: every index < length must have an own descriptor.
+        for (let index = 0; index < arr.length; index += 1) {
+          const key = String(index);
+          if (!(key in descs)) {
+            fail(`${path}[${index}]`, 'sparse array holes are not supported');
+          }
+          const d = descs[key]!;
+          if (d.get !== undefined || d.set !== undefined) {
+            fail(`${path}[${index}]`, 'accessor property is not supported');
+          }
+          if (d.enumerable === false) {
+            fail(`${path}[${index}]`, 'non-enumerable property is not supported');
+          }
+        }
+
+        // Clone indices via descriptors to avoid getter invocation.
+        const cloned: unknown[] = new Array(arr.length);
+        for (let index = 0; index < arr.length; index += 1) {
+          const key = String(index);
+          const d = descs[key]!;
+          cloned[index] = clone(d.value, `${path}[${index}]`, depth + 1);
+        }
+
+        // Check for non-index own properties (including symbols).
+        for (const key of Reflect.ownKeys(descs) as (string | symbol)[]) {
+          if (typeof key === 'symbol') {
+            fail(`${path}[Symbol(${String(key).slice(7, -1)})]`, 'symbol-keyed property is not supported');
+          }
+          const k = key as string;
+          if (k === 'length') {
+            continue;
+          }
+          // Indices already handled.
+          if (/^(0|[1-9]\d*)$/.test(k)) {
+            const idx = Number(k);
+            if (idx < arr.length && String(idx) === k) {
+              continue;
+            }
+          }
+          if (k === '__proto__' || k === 'constructor' || k === 'prototype') {
+            fail(`${path}.${k}`, 'unsafe prototype key is not supported');
+          }
+          const d = descs[k]!;
+          if (d.get !== undefined || d.set !== undefined) {
+            fail(`${path}.${k}`, 'accessor property is not supported');
+          }
+          if (d.enumerable === false) {
+            fail(`${path}.${k}`, 'non-enumerable property is not supported');
+          }
+          fail(`${path}.${k}`, 'array extra property is not a supported payload member');
+        }
+
+        Object.freeze(cloned);
+        return cloned;
+      }
+
+      // Plain record
+      if (!isPlainRecord(obj)) {
+        fail(path, 'only plain records and arrays are supported (class instance, Map, Set, Date, etc. are rejected)');
+      }
+      const proto = Object.getPrototypeOf(obj);
+
+      const descs = Object.getOwnPropertyDescriptors(obj);
+      // Check for symbol keys and unsafe keys, and validate descriptors.
+      for (const key of Reflect.ownKeys(descs) as (string | symbol)[]) {
+        if (typeof key === 'symbol') {
+          fail(`${path}[Symbol(${String(key).slice(7, -1)})]`, 'symbol-keyed property is not supported');
+        }
+        const k = key as string;
+        if (k === '__proto__' || k === 'constructor' || k === 'prototype') {
+          fail(`${path}.${k}`, 'unsafe prototype key is not supported');
+        }
+        const d = descs[k]!;
+        if (d.get !== undefined || d.set !== undefined) {
+          fail(`${path}.${k}`, 'accessor property is not supported');
+        }
+        if (d.enumerable === false) {
+          fail(`${path}.${k}`, 'non-enumerable property is not supported');
+        }
+      }
+
+      const cloned: Record<string, unknown> = proto === null ? Object.create(null) : {};
+      for (const key of Object.keys(descs)) {
+        // `Object.keys` already filters to enumerable string keys, but we have already validated
+        // via `getOwnPropertyDescriptors` that all own keys are enumerable data properties.
+        // Use descriptor value without invoking getter (we already checked it's a data descriptor).
+        const d = descs[key]!;
+        cloned[key] = clone(d.value, `${path}.${key}`, depth + 1);
+      }
+      Object.freeze(cloned);
+      return cloned;
+    } finally {
+      ancestry.delete(obj);
+    }
+  };
+
+  const result = clone(payload, basePath, 0);
+  return result;
+}
+
+export const PAYLOAD_LIMITS = {
+  MAX_PAYLOAD_NODES,
+  MAX_PAYLOAD_DEPTH,
+  MAX_PAYLOAD_STRING_LENGTH,
+  MAX_PAYLOAD_ARRAY_LENGTH,
+} as const;

package/src/events/seed.ts

@@ -0,0 +1,33 @@
+import type { AnyGameEventEnvelope } from './types';
+
+/**
+ * Derive a deterministic seed from a committed event envelope.
+ *
+ * The seed is stable within a session and across replays because it
+ * depends only on the envelope's identity `(tick, ordinal)` and name,
+ * never on wall time, React renders, or display frames.
+ *
+ * `seedGameEvent` is suitable for seeding seeded visual effects,
+ * particles, or audio variations that must replay identically.
+ */
+function hashString(value: string): number {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+export function seedGameEvent(event: AnyGameEventEnvelope): number {
+  const nameHash = hashString(event.name);
+  // Deterministic mixing of tick, ordinal, and name hash — the documented
+  // stable identity (tick, ordinal, name). sceneTick is intentionally
+  // excluded; it is presentation-local and would make the seed disagree
+  // with its contract.
+  let seed = 17;
+  seed = Math.imul(seed, 31) + event.tick;
+  seed = Math.imul(seed, 31) + event.ordinal;
+  seed = Math.imul(seed, 31) + nameHash;
+  return seed >>> 0;
+}

package/src/events/types.ts

@@ -0,0 +1,53 @@
+import type { DeepReadonly } from '../core/session/types';
+
+declare const EventDefsBrand: unique symbol;
+
+/** A type-witness descriptor for one game event's payload. */
+export interface GameEventDescriptor<TPayload> {
+  /** @internal Payload witness — no runtime value. */
+  readonly __payload?: TPayload;
+}
+
+/** A map from event name to its payload type. */
+export type GameEventMap = Record<string, unknown>;
+
+/** A map from event name to its descriptor (the authored declaration). */
+export type GameEventDefinitions<TMap extends GameEventMap> = {
+  readonly [K in keyof TMap]: GameEventDescriptor<TMap[K]>;
+};
+
+/** Branded event definitions — nominal identity for scene/game binding. */
+export type BrandedGameEventDefs<T extends Record<string, GameEventDescriptor<unknown>>> = T & {
+  readonly [EventDefsBrand]?: T;
+};
+
+/** Infer the payload map from a descriptor map. */
+export type InferGameEventMap<TDefs extends Record<string, GameEventDescriptor<unknown>>> = {
+  [K in keyof TDefs as K extends string ? K : never]: TDefs[K] extends GameEventDescriptor<infer P> ? P : never;
+};
+
+/** One committed event envelope. Identity is `(tick, ordinal)` within a session. */
+export interface GameEventEnvelope<TName extends string, TPayload> {
+  readonly name: TName;
+  readonly payload: DeepReadonly<TPayload>;
+  readonly tick: number;
+  readonly scene: string;
+  readonly sceneTick: number;
+  readonly ordinal: number;
+}
+
+/** Type-erased envelope for storage and delivery. */
+export type AnyGameEventEnvelope = GameEventEnvelope<string, unknown>;
+
+/** An emitter scoped to one fixed tick and one scene. */
+export interface GameEventEmitter<TMap extends GameEventMap> {
+  emit<TName extends keyof TMap & string>(name: TName, payload: TMap[TName]): void;
+}
+
+/** Listener for one event name. May be sync or async; rejections are observed without awaiting. */
+export type GameEventListener<TPayload> = (
+  event: GameEventEnvelope<string, TPayload>,
+) => void | Promise<void>;
+
+/** Infer the listener payload for a given game definition's event map. */
+export type GameEventPayloadFor<TMap extends GameEventMap, TName extends keyof TMap & string> = TMap[TName];

package/src/events.ts

@@ -0,0 +1,20 @@
+/**
+ * Subpath entry for `rn-gamekit/events`.
+ *
+ * Typed event definitions, envelopes, payload limits, seeding, and errors.
+ * Does not expose internal validation helpers or effect consumers.
+ */
+export { GameEventError } from './events/errors';
+export { defineGameEvents, gameEvent } from './events/defineGameEvents';
+export { seedGameEvent } from './events/seed';
+export { PAYLOAD_LIMITS } from './events/payload';
+export type {
+  AnyGameEventEnvelope,
+  GameEventDefinitions,
+  GameEventDescriptor,
+  GameEventEmitter,
+  GameEventEnvelope,
+  GameEventListener,
+  GameEventMap,
+  InferGameEventMap,
+} from './events/types';

package/src/geometry/helpers.ts

@@ -0,0 +1,136 @@
+/**
+ * Pure geometry helpers (T11.1): AABB centers, translation, expansion, and
+ * union, plus vector arithmetic. All functions validate their inputs,
+ * preserve them untouched, and return fresh immutable values.
+ */
+import type { Aabb2D, Point2D, Vector2D } from './types';
+import {
+  assertValidAabb2D,
+  assertValidPoint2D,
+  assertValidVector2D,
+  GeometryError,
+} from './validation';
+
+/** Center of an AABB. */
+export function aabbCenter2D(aabb: Aabb2D): Point2D {
+  assertValidAabb2D(aabb);
+  return Object.freeze({
+    x: aabb.x + aabb.width / 2,
+    y: aabb.y + aabb.height / 2,
+  });
+}
+
+/** Translate an AABB by a delta vector, returning a new AABB. */
+export function translateAabb2D(aabb: Aabb2D, delta: Vector2D): Aabb2D {
+  assertValidAabb2D(aabb);
+  assertValidVector2D(delta, 'delta');
+  return Object.freeze({
+    x: aabb.x + delta.x,
+    y: aabb.y + delta.y,
+    width: aabb.width,
+    height: aabb.height,
+  });
+}
+
+/**
+ * Expand an AABB symmetrically (or per-axis) by the given amounts.
+ *
+ * A negative inset shrinks the AABB. The expanded result keeps the same
+ * width/height semantics; `inset` is the margin added on each side.
+ */
+export function expandAabb2D(aabb: Aabb2D, inset: number | Vector2D): Aabb2D {
+  assertValidAabb2D(aabb);
+  const x = typeof inset === 'number' ? inset : inset.x;
+  const y = typeof inset === 'number' ? inset : inset.y;
+  assertFiniteInset(x, 'inset.x');
+  assertFiniteInset(y, 'inset.y');
+  const expanded = Object.freeze({
+    x: aabb.x - x,
+    y: aabb.y - y,
+    width: aabb.width + x * 2,
+    height: aabb.height + y * 2,
+  });
+  // A negative inset may legitimately shrink the shape, but never into a
+  // malformed (negative-size) result.
+  assertValidAabb2D(expanded, 'expanded');
+  return expanded;
+}
+
+function assertFiniteInset(value: number, field: string): void {
+  if (!Number.isFinite(value)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      field,
+      `expected a finite inset, got ${String(value)}`,
+    );
+  }
+}
+
+/** The smallest AABB containing both inputs (bounding union). */
+export function unionAabb2D(first: Aabb2D, second: Aabb2D): Aabb2D {
+  assertValidAabb2D(first, 'first');
+  assertValidAabb2D(second, 'second');
+  const minX = Math.min(first.x, second.x);
+  const minY = Math.min(first.y, second.y);
+  const maxX = Math.max(first.x + first.width, second.x + second.width);
+  const maxY = Math.max(first.y + first.height, second.y + second.height);
+  return Object.freeze({
+    x: minX,
+    y: minY,
+    width: maxX - minX,
+    height: maxY - minY,
+  });
+}
+
+/** Component-wise vector addition. */
+export function addVector2D(first: Vector2D, second: Vector2D): Vector2D {
+  assertValidVector2D(first, 'first');
+  assertValidVector2D(second, 'second');
+  return Object.freeze({ x: first.x + second.x, y: first.y + second.y });
+}
+
+/** Component-wise vector subtraction (`first - second`). */
+export function subtractVector2D(first: Vector2D, second: Vector2D): Vector2D {
+  assertValidVector2D(first, 'first');
+  assertValidVector2D(second, 'second');
+  return Object.freeze({ x: first.x - second.x, y: first.y - second.y });
+}
+
+/** Scale a vector by a finite scalar. */
+export function scaleVector2D(vector: Vector2D, scalar: number): Vector2D {
+  assertValidVector2D(vector);
+  if (!Number.isFinite(scalar)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      'scalar',
+      `expected a finite number, got ${String(scalar)}`,
+    );
+  }
+  return Object.freeze({ x: vector.x * scalar, y: vector.y * scalar });
+}
+
+/** Euclidean length of a vector. */
+export function lengthVector2D(vector: Vector2D): number {
+  assertValidVector2D(vector);
+  return Math.hypot(vector.x, vector.y);
+}
+
+/**
+ * Normalize a vector to unit length. The zero vector is returned unchanged
+ * (never NaN); callers that need a fallback direction choose it explicitly.
+ */
+export function normalizeVector2D(vector: Vector2D): Vector2D {
+  assertValidVector2D(vector);
+  const length = Math.hypot(vector.x, vector.y);
+  if (length === 0) {
+    return Object.freeze({ x: 0, y: 0 });
+  }
+  return Object.freeze({ x: vector.x / length, y: vector.y / length });
+}
+
+/** Euclidean distance between two points. */
+export function distancePoint2D(first: Point2D, second: Point2D): number {
+  assertValidPoint2D(first, 'first');
+  assertValidPoint2D(second, 'second');
+  return Math.hypot(second.x - first.x, second.y - first.y);
+}

package/src/geometry/index.ts

@@ -0,0 +1,14 @@
+export type { Aabb2D, Circle2D, Point2D, Segment2D, Vector2D } from './types';
+export { GeometryError, type GeometryErrorCode } from './validation';
+export {
+  aabbCenter2D,
+  addVector2D,
+  distancePoint2D,
+  expandAabb2D,
+  lengthVector2D,
+  normalizeVector2D,
+  scaleVector2D,
+  subtractVector2D,
+  translateAabb2D,
+  unionAabb2D,
+} from './helpers';

package/src/geometry/types.ts

@@ -1,3 +1,13 @@
+/**
+ * Canonical 2D geometry values (T11.1).
+ *
+ * All shapes are immutable plain data in Gamekit's logical world
+ * coordinates (positive x right, positive y down). `Aabb2D.x/y` identify the
+ * minimum/top-left corner. Width, height, and radius are finite and
+ * nonnegative; malformed values throw `GeometryError` at the public
+ * operation boundary and never masquerade as "no collision".
+ */
+
 /** A plain 2D point in logical/world or surface coordinate space. */
 export interface Point2D {
   /** Horizontal coordinate. */
@@ -5,3 +15,47 @@ export interface Point2D {
   /** Vertical coordinate. */
   readonly y: number;
 }
+
+/** A plain 2D vector (translation, displacement, or direction). */
+export interface Vector2D {
+  /** Horizontal component. */
+  readonly x: number;
+  /** Vertical component. */
+  readonly y: number;
+}
+
+/**
+ * An axis-aligned rectangle in logical world units.
+ *
+ * `x`/`y` are the top-left corner (the minimum corner in Gamekit's
+ * positive-down convention). Shape-compatible with the viewport `Rect`
+ * type: any `Rect` is also a valid `Aabb2D` by shape, and vice versa.
+ */
+export interface Aabb2D {
+  /** Left edge. */
+  readonly x: number;
+  /** Top edge. */
+  readonly y: number;
+  /** Width, finite and nonnegative. */
+  readonly width: number;
+  /** Height, finite and nonnegative. */
+  readonly height: number;
+}
+
+/** A circle in logical world units. */
+export interface Circle2D {
+  /** Center x. */
+  readonly x: number;
+  /** Center y. */
+  readonly y: number;
+  /** Radius, finite and nonnegative. */
+  readonly radius: number;
+}
+
+/** A directed segment (ray-style query input). */
+export interface Segment2D {
+  /** Segment start point. */
+  readonly start: Point2D;
+  /** Segment end point. */
+  readonly end: Point2D;
+}

package/src/geometry/validation.ts

@@ -0,0 +1,131 @@
+/**
+ * Geometry validation and structured errors (T11.1).
+ *
+ * Mirrors the package's structured-error style (`GameAssetError`): a stable
+ * machine-readable code plus the offending field. Validation happens at
+ * public operation boundaries; helpers never coerce or reorder malformed
+ * values into valid shapes.
+ *
+ * Numeric policy (GS-GEOMETRY-01): validators require the declared
+ * structural shape (a null/array/scalar argument fails with
+ * GEOMETRY_INVALID_SHAPE, never a TypeError) and finite components within
+ * ordinary game-world magnitudes. Derived-value overflow from extreme
+ * finite inputs is out of contract: helpers do not re-validate results,
+ * and zero-length normalization of an overflowing length stays a zero
+ * vector by the existing defined behavior.
+ */
+import type { Aabb2D, Circle2D, Point2D, Segment2D, Vector2D } from './types';
+
+/** Stable error codes for geometry and collision input. */
+export type GeometryErrorCode =
+  | 'GEOMETRY_INVALID_NUMBER'
+  | 'GEOMETRY_INVALID_SIZE'
+  | 'GEOMETRY_INVALID_BITS'
+  | 'GEOMETRY_INVALID_SEGMENT'
+  | 'GEOMETRY_INVALID_SHAPE'
+  | 'GEOMETRY_DUPLICATE_ID'
+  | 'GEOMETRY_SPATIAL_INDEX_RANGE';
+
+/** A structured geometry or collision input failure. */
+export class GeometryError extends Error {
+  /** Stable machine-readable code. */
+  readonly code: GeometryErrorCode;
+  /** Field path within the value that caused the failure. */
+  readonly field: string;
+
+  constructor(code: GeometryErrorCode, field: string, message: string) {
+    super(`${code} at ${field}: ${message}`);
+    this.name = 'GeometryError';
+    this.code = code;
+    this.field = field;
+  }
+}
+
+/** Assert a finite number (rejects NaN and ±Infinity). */
+export function assertFiniteNumber(value: number, field: string): void {
+  if (!Number.isFinite(value)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_NUMBER',
+      field,
+      `expected a finite number, got ${String(value)}`,
+    );
+  }
+}
+
+/** Assert a finite, nonnegative size (width, height, radius). */
+export function assertNonnegativeSize(value: number, field: string): void {
+  assertFiniteNumber(value, field);
+  if (value < 0) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_SIZE',
+      field,
+      `expected a nonnegative size, got ${value}`,
+    );
+  }
+}
+
+/** Assert an unsigned 32-bit integer (collision filters and bit masks). */
+export function assertUnsigned32Bits(value: number, field: string): void {
+  if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_BITS',
+      field,
+      `expected an unsigned 32-bit integer, got ${String(value)}`,
+    );
+  }
+}
+
+/** Assert a value is a plain record before reading fields (GS-GEOMETRY-01). */
+function assertRecordShape(value: unknown, name: string): asserts value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_SHAPE',
+      name,
+      `expected an object with numeric fields, got ${Array.isArray(value) ? 'an array' : String(value)}`,
+    );
+  }
+}
+
+/** Validate a point or vector component pair. */
+export function assertValidPoint2D(point: Point2D, name = 'point'): void {
+  assertRecordShape(point, name);
+  assertFiniteNumber(point.x, `${name}.x`);
+  assertFiniteNumber(point.y, `${name}.y`);
+}
+
+/** Validate a vector (same shape as a point, distinct naming). */
+export function assertValidVector2D(vector: Vector2D, name = 'vector'): void {
+  assertRecordShape(vector, name);
+  assertFiniteNumber(vector.x, `${name}.x`);
+  assertFiniteNumber(vector.y, `${name}.y`);
+}
+
+/** Validate an AABB: finite corner, finite nonnegative size. */
+export function assertValidAabb2D(aabb: Aabb2D, name = 'aabb'): void {
+  assertRecordShape(aabb, name);
+  assertFiniteNumber(aabb.x, `${name}.x`);
+  assertFiniteNumber(aabb.y, `${name}.y`);
+  assertNonnegativeSize(aabb.width, `${name}.width`);
+  assertNonnegativeSize(aabb.height, `${name}.height`);
+}
+
+/** Validate a circle: finite center, finite nonnegative radius. */
+export function assertValidCircle2D(circle: Circle2D, name = 'circle'): void {
+  assertRecordShape(circle, name);
+  assertFiniteNumber(circle.x, `${name}.x`);
+  assertFiniteNumber(circle.y, `${name}.y`);
+  assertNonnegativeSize(circle.radius, `${name}.radius`);
+}
+/** Validate a segment: finite endpoints that are not both degenerate checks. */
+export function assertValidSegment2D(segment: Segment2D, name = 'segment'): void {
+  assertRecordShape(segment, name);
+  assertValidPoint2D(segment.start, `${name}.start`);
+  assertValidPoint2D(segment.end, `${name}.end`);
+  if (segment.start.x === segment.end.x && segment.start.y === segment.end.y) {
+    throw new GeometryError(
+      'GEOMETRY_INVALID_SEGMENT',
+      name,
+      'expected distinct endpoints, got a zero-length segment',
+    );
+  }
+}

package/src/geometry.ts

@@ -0,0 +1,6 @@
+/**
+ * Subpath entry for `rn-gamekit/geometry`.
+ *
+ * Headless geometry primitives — no React, React Native, Skia, or native peers.
+ */
+export * from './geometry/index';