@typeonce/ritmo-math 0.12.0 → 0.14.0

package/src/Collide2.ts

@@ -1,10 +1,12 @@
 /**
- * Continuous collision for moving circles against static boxes and circles.
+ * Continuous collision for moving circles against static walls (axis-aligned
+ * boxes and line segments) and circles.
  *
- * Movement is swept, not sampled: `sweepCircleBox` finds the first time of
+ * Movement is swept, not sampled: `sweepCircle` finds the first time of
  * contact along the whole displacement, so fast movers (dashes, projectiles)
  * cannot skip over a wall between two steps. `moveCircle` stops at walls and
- * slides along them.
+ * slides along them. Walls are passed as {@link Walls}: `Box2` boxes for a
+ * grid of rooms, `Segment2` segments for walls at any angle, or both.
  *
  * Every query returns `undefined` for "no contact", never throws, and
  * allocates only its result. Inputs are expected to be finite.
@@ -12,7 +14,7 @@
  * @example
  * ```ts
  * // Move a body by its velocity this step, sliding along the walls.
- * const moved = Collide2.moveCircle(position, Vec2.scale(velocity, dt), radius, walls)
+ * const moved = Collide2.moveCircle(position, Vec2.scale(velocity, dt), radius, { boxes: walls })
  * if (moved.blocked) bumpedWall()
  * ```
  *
@@ -30,6 +32,7 @@
  */
 import type { Box2 } from "./Box2.ts"
 import * as Ops from "./Ops.ts"
+import type { Segment2 } from "./Segment2.ts"
 import type { Vec2 } from "./Vec2.ts"
 
 /**
@@ -40,11 +43,27 @@ import type { Vec2 } from "./Vec2.ts"
 export interface Hit {
   /** Fraction of the displacement travelled before contact, in [0, 1]. */
   readonly time: number
-  /** Unit contact normal, pointing away from the box. */
+  /** Unit contact normal, pointing away from the wall. */
   readonly nx: number
   readonly ny: number
 }
 
+/**
+ * The static walls a circle collides with: axis-aligned `boxes`, line
+ * `segments`, or both. A missing list is no walls of that kind.
+ *
+ * @category Collision Types
+ */
+export interface Walls {
+  readonly boxes?: ReadonlyArray<Box2>
+  readonly segments?: ReadonlyArray<Segment2>
+  /** Not a setting: an array of walls is passed by kind. */
+  readonly length?: "pass walls by kind: { boxes: walls } or { segments: walls }"
+}
+
+const noBoxes: ReadonlyArray<Box2> = []
+const noSegments: ReadonlyArray<Segment2> = []
+
 /**
  * Where a moved circle ended up.
  *
@@ -170,7 +189,61 @@ export const sweepCircleBox = (origin: Vec2, delta: Vec2, radius: number, box: B
 }
 
 /**
- * First contact of a moving circle with any of `boxes`, or `undefined`.
+ * First contact of a circle of `radius` at `origin` moving by `delta` with
+ * `segment`, or `undefined`. Contact is computed against the segment
+ * thickened by the radius with round ends (the exact Minkowski sum), so the
+ * circle slides along it and around its ends. A circle that starts exactly
+ * touching it and moves into it hits at time 0. A circle that starts
+ * overlapping the segment is not reported; resolve it with `pushOut` first.
+ *
+ * @category Queries
+ */
+export const sweepCircleSegment = (origin: Vec2, delta: Vec2, radius: number, segment: Segment2): Hit | undefined => {
+  const ex = segment.bx - segment.ax
+  const ey = segment.by - segment.ay
+  const lengthSquared = ex * ex + ey * ey
+  if (lengthSquared > 1e-12) {
+    // The flat side facing the circle, `radius` away from the segment's line.
+    const length = Math.sqrt(lengthSquared)
+    let nx = -ey / length
+    let ny = ex / length
+    let side = (origin.x - segment.ax) * nx + (origin.y - segment.ay) * ny
+    if (side < 0) {
+      nx = -nx
+      ny = -ny
+      side = -side
+    }
+    if (side < radius) {
+      // Beside the line: overlapping when level with the segment, otherwise
+      // only its ends are in the way.
+      const along = ((origin.x - segment.ax) * ex + (origin.y - segment.ay) * ey) / lengthSquared
+      if (along >= 0 && along <= 1) return undefined
+    } else {
+      const into = delta.x * nx + delta.y * ny
+      if (into < 0) {
+        // `0 +` turns a -0 (touching at the start) into 0.
+        const time = 0 + (radius - side) / into
+        if (time <= 1) {
+          const along = ((origin.x + delta.x * time - segment.ax) * ex + (origin.y + delta.y * time - segment.ay) * ey) / lengthSquared
+          // The thickened segment is convex, so entering through its flat side is the first contact.
+          if (along >= 0 && along <= 1) return { time, nx, ny }
+        }
+      }
+    }
+  }
+  const atA = rayCircle(origin.x, origin.y, delta.x, delta.y, segment.ax, segment.ay, radius)
+  const atB = lengthSquared > 1e-12 ? rayCircle(origin.x, origin.y, delta.x, delta.y, segment.bx, segment.by, radius) : undefined
+  if (atA === undefined && atB === undefined) return undefined
+  const fromA = atB === undefined || (atA !== undefined && atA <= atB)
+  const time = fromA ? atA! : atB
+  const cx = origin.x + delta.x * time - (fromA ? segment.ax : segment.bx)
+  const cy = origin.y + delta.y * time - (fromA ? segment.ay : segment.by)
+  const length = Ops.hypot(cx, cy) || 1
+  return { time, nx: cx / length, ny: cy / length }
+}
+
+/**
+ * First contact of a moving circle with any of `walls`, or `undefined`.
  *
  * With a `radius` of 0 the circle is a point and the sweep is a segment, so
  * this is also line of sight: `undefined` means nothing blocks the line from
@@ -179,17 +252,21 @@ export const sweepCircleBox = (origin: Vec2, delta: Vec2, radius: number, box: B
  *
  * @example
  * ```ts
- * const sees = Collide2.sweepCircleBoxes(eye, Vec2.subtract(target, eye), 0, walls) === undefined
+ * const sees = Collide2.sweepCircle(eye, Vec2.subtract(target, eye), 0, { boxes: walls }) === undefined
  * ```
  *
  * @category Queries
  */
-export const sweepCircleBoxes = (origin: Vec2, delta: Vec2, radius: number, boxes: ReadonlyArray<Box2>): Hit | undefined => {
+export const sweepCircle = (origin: Vec2, delta: Vec2, radius: number, walls: Walls): Hit | undefined => {
   let first: Hit | undefined
-  for (const box of boxes) {
+  for (const box of walls.boxes ?? noBoxes) {
     const hit = sweepCircleBox(origin, delta, radius, box)
     if (hit !== undefined && (first === undefined || hit.time < first.time)) first = hit
   }
+  for (const segment of walls.segments ?? noSegments) {
+    const hit = sweepCircleSegment(origin, delta, radius, segment)
+    if (hit !== undefined && (first === undefined || hit.time < first.time)) first = hit
+  }
   return first
 }
 
@@ -215,15 +292,17 @@ export const sweepCircleCircle = (
 }
 
 /**
- * Pushes a circle out of every box it overlaps, in order, leaving `skin`
- * between it and each wall. Returns the corrected center.
+ * Pushes a circle out of every wall it overlaps, boxes first and then
+ * segments, each in order, leaving `skin` between it and each wall. Returns
+ * the corrected center. A center inside a box leaves through the nearest
+ * side; a center exactly on a segment leaves along the segment's left normal.
  *
  * @category Movement
  */
-export const pushOut = (center: Vec2, radius: number, boxes: ReadonlyArray<Box2>, skin: number = defaultSkin): Vec2 => {
+export const pushOut = (center: Vec2, radius: number, walls: Walls, skin: number = defaultSkin): Vec2 => {
   let x = center.x
   let y = center.y
-  for (const box of boxes) {
+  for (const box of walls.boxes ?? noBoxes) {
     const closestX = Math.max(box.minX, Math.min(x, box.maxX))
     const closestY = Math.max(box.minY, Math.min(y, box.maxY))
     const dx = x - closestX
@@ -247,6 +326,31 @@ export const pushOut = (center: Vec2, radius: number, boxes: ReadonlyArray<Box2>
       else y = box.maxY + radius + skin
     }
   }
+  for (const segment of walls.segments ?? noSegments) {
+    const ex = segment.bx - segment.ax
+    const ey = segment.by - segment.ay
+    const lengthSquared = ex * ex + ey * ey
+    const along = lengthSquared > 1e-12 ? Math.max(0, Math.min(1, ((x - segment.ax) * ex + (y - segment.ay) * ey) / lengthSquared)) : 0
+    const closestX = segment.ax + ex * along
+    const closestY = segment.ay + ey * along
+    const dx = x - closestX
+    const dy = y - closestY
+    const distanceSquared = dx * dx + dy * dy
+    if (distanceSquared >= radius * radius) continue
+    if (distanceSquared > 1e-12) {
+      const distance = Math.sqrt(distanceSquared)
+      x = closestX + (dx / distance) * (radius + skin)
+      y = closestY + (dy / distance) * (radius + skin)
+    } else if (lengthSquared > 1e-12) {
+      // Center on the segment: leave along its left normal.
+      const length = Math.sqrt(lengthSquared)
+      x = closestX - (ey / length) * (radius + skin)
+      y = closestY + (ex / length) * (radius + skin)
+    } else {
+      // Center on a round post: leave along +x.
+      x = closestX + radius + skin
+    }
+  }
   return { x, y }
 }
 
@@ -254,19 +358,46 @@ export const pushOut = (center: Vec2, radius: number, boxes: ReadonlyArray<Box2>
  * Moves a circle by `delta`, stopping at walls and sliding along them (up to
  * four contacts per call). The whole path is swept, so no displacement can
  * tunnel through a wall. A circle that starts inside a wall is pushed out
- * first. A circle meeting a box's corner dead-on goes around it rather than
- * stopping against it.
+ * first. A circle meeting a box's corner or a segment's end dead-on goes
+ * around it rather than stopping against it.
+ *
+ * @example
+ * ```ts
+ * // A map traced from survey data: every wall is a segment.
+ * const moved = Collide2.moveCircle(position, delta, radius, { segments: nearbyWalls })
+ * ```
  *
  * @category Movement
  */
-export const moveCircle = (start: Vec2, delta: Vec2, radius: number, boxes: ReadonlyArray<Box2>, skin: number = defaultSkin): MoveResult => {
-  let position = pushOut(start, radius, boxes, skin)
+export const moveCircle = (start: Vec2, delta: Vec2, radius: number, walls: Walls, skin: number = defaultSkin): MoveResult => {
+  let position = pushOut(start, radius, walls, skin)
   let rx = delta.x
   let ry = delta.y
   let blocked = false
   for (let iteration = 0; iteration < 4; iteration++) {
     if (rx * rx + ry * ry < 1e-12) break
-    const hit = sweepCircleBoxes(position, { x: rx, y: ry }, radius, boxes)
+    const step = { x: rx, y: ry }
+    // The first contact, and whether it is round (a box's corner or a
+    // segment's end) rather than a flat side.
+    let hit: Hit | undefined
+    let round = false
+    for (const box of walls.boxes ?? noBoxes) {
+      const found = sweepCircleBox(position, step, radius, box)
+      if (found === undefined || (hit !== undefined && found.time >= hit.time)) continue
+      hit = found
+      round = found.nx !== 0 && found.ny !== 0
+    }
+    for (const segment of walls.segments ?? noSegments) {
+      const found = sweepCircleSegment(position, step, radius, segment)
+      if (found === undefined || (hit !== undefined && found.time >= hit.time)) continue
+      hit = found
+      const ex = segment.bx - segment.ax
+      const ey = segment.by - segment.ay
+      const lengthSquared = ex * ex + ey * ey
+      const along = found.nx * ex + found.ny * ey
+      // A flat side's normal is perpendicular to the segment.
+      round = lengthSquared < 1e-12 || along * along > 1e-18 * lengthSquared
+    }
     if (hit === undefined) {
       position = { x: position.x + rx, y: position.y + ry }
       break
@@ -284,10 +415,10 @@ export const moveCircle = (start: Vec2, delta: Vec2, radius: number, boxes: Read
     if (into < 0) {
       rx -= into * hit.nx
       ry -= into * hit.ny
-      // Dead-on into a rounded corner (as an exact diagonal meets an
-      // axis-aligned box) nothing is left to slide along: go around the
-      // corner instead of stopping against it.
-      if (hit.nx !== 0 && hit.ny !== 0 && rx * rx + ry * ry < 1e-12 * into * into) {
+      // Dead-on into a rounded corner or end (as an exact diagonal meets an
+      // axis-aligned box) nothing is left to slide along: go around it
+      // instead of stopping against it.
+      if (round && rx * rx + ry * ry < 1e-12 * into * into) {
         const side = rx * -hit.ny + ry * hit.nx < 0 ? -1 : 1
         rx = -hit.ny * -into * side
         ry = hit.nx * -into * side

package/src/Random.ts

@@ -3,7 +3,7 @@
  * integer.
  *
  * Keep the state in a resource, so a run replays exactly and saves with the
- * world: declare it with this module as its validator, start it with
+ * world: declare it with `Random.codec` as its schema, start it with
  * `seed`, and draw in systems through `draw` over its write cell, which writes
  * every draw back (rolled back with a failed system). Two generators made
  * from the same state draw the same sequence on every platform. `make` is for
@@ -11,7 +11,7 @@
  *
  * @example
  * ```ts
- * const Rng = Descriptor.ConstructedResource(Random)("Game/Rng")
+ * const Rng = Descriptor.ConstructedResource(Random.codec)("Game/Rng")
  * const runtime = Game.Runtime.make({ services, resources: { Rng: Random.seed(0x5eed) } })
  *
  * Game.System("Game/Spawn", { resources: { rng: Game.System.writeResource(Rng) } }, ({ resources }) => {
@@ -35,7 +35,9 @@
  */
 import type * as Brand from "@typeonce/ritmo/Brand"
 import type { WriteCell } from "@typeonce/ritmo/Query"
+import type { StandardSchema } from "@typeonce/ritmo/Descriptor"
 import * as Result from "@typeonce/ritmo/Result"
+import { codecOf } from "./internal/codec.ts"
 
 /**
  * A generator. Every draw advances `state`.
@@ -143,7 +145,7 @@ export const make = (state: number): Random => new Mulberry32(state)
 
 /**
  * A generator's state as a resource holds it: an unsigned 32-bit integer.
- * Only `seed`, `result`, and `decode` make one, so `draw` takes the cell of a
+ * Only `seed`, `result`, and `codec` make one, so `draw` takes the cell of a
  * random resource and nothing else.
  *
  * @category Resource
@@ -160,7 +162,7 @@ const isState = (value: unknown): value is State =>
   typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 0xffffffff
 
 /**
- * Validates a state, for `Descriptor.ConstructedResource(Random)` and saves.
+ * Validates a state, for game code that builds one from a number.
  *
  * @category Resource
  */
@@ -168,12 +170,24 @@ export const result = (raw: number): Result.Result<State, InvalidState> =>
   isState(raw) ? Result.success(raw) : Result.failure({ _tag: "InvalidRandomState", value: raw })
 
 /**
- * Validates a state read from untrusted data (a save).
+ * Whether any value is a generator state: a guard, also for building a
+ * state field in your own schema (`Schema.declare(Random.is)`).
  *
  * @category Resource
  */
-export const decode = (raw: unknown): Result.Result<State, InvalidState> =>
-  isState(raw) ? Result.success(raw) : Result.failure({ _tag: "InvalidRandomState", value: raw })
+export const is = (raw: unknown): raw is State => isState(raw)
+
+/**
+ * The codec of a random resource's state (a Standard Schema, see
+ * `Descriptor.Codec`): `Descriptor.ConstructedResource(Random.codec)`. Its
+ * saved form is the number itself, so it needs no `encode`.
+ *
+ * @category Resource
+ */
+export const codec: StandardSchema<number, State> = codecOf<number, State>(
+  (raw) => isState(raw) ? Result.success(raw) : Result.failure({ _tag: "InvalidRandomState", value: raw }),
+  "a generator state: an unsigned 32-bit integer"
+)
 
 /**
  * The starting state for a seed, reduced to an unsigned 32-bit integer like

package/src/Scalar.ts

@@ -36,13 +36,14 @@
  */
 import type * as Brand from "@typeonce/ritmo/Brand"
 import * as internal from "./internal/scalar.ts"
+import type { StandardSchema } from "@typeonce/ritmo/Descriptor"
 import type * as Result from "@typeonce/ritmo/Result"
 
 /**
  * Finite number brand.
  *
  * Values of this type are guaranteed not to be `NaN`, `Infinity`, or
- * `-Infinity` when they come from a validator (`result`, `decode`). The
+ * `-Infinity` when they come from a constructor (`result`, `option`) or a `codec`. The
  * arithmetic helpers here and in `Vector2` keep the brand without
  * re-validating, so their results are finite only while they stay within
  * `±Number.MAX_VALUE`: game-sized values never come close, but validate
@@ -85,27 +86,46 @@ export type InterpolationError = {
   readonly end: number
 }
 
+/**
+ * The constructors, guard, and schema of one scalar brand.
+ *
+ * @category Constructors
+ */
+export interface Constructor<Value> {
+  /** Validates one number and returns an explicit success/failure result. */
+  readonly result: (raw: number) => Result.Result<Value, Error>
+  /** Validates one number and returns `null` on failure. */
+  readonly option: (raw: number) => Value | null
+  /** Whether any value is a number of this brand. */
+  readonly is: (raw: unknown) => raw is Value
+  /** The Standard Schema for `Descriptor.ConstructedComponent(...)`: the saved form is the number itself. */
+  readonly codec: StandardSchema<number, Value>
+}
+
 /**
  * Constructor for {@link Finite}: `result` (explicit failure), `option`
- * (`null` on failure), and `is` (a type guard).
+ * (`null` on failure), `is` (a type guard), and `codec`, for
+ * `Descriptor.ConstructedComponent(Scalar.Finite.codec)`.
  *
  * @category Constructors
  */
-export const Finite = internal.Finite
+export const Finite: Constructor<Finite> = internal.Finite
 /**
  * Constructor for {@link NonNegative}: `result` (explicit failure), `option`
- * (`null` on failure), and `is` (a type guard).
+ * (`null` on failure), `is` (a type guard), and `codec`, for
+ * `Descriptor.ConstructedComponent(Scalar.NonNegative.codec)`.
  *
  * @category Constructors
  */
-export const NonNegative = internal.NonNegative
+export const NonNegative: Constructor<NonNegative> = internal.NonNegative
 /**
  * Constructor for {@link Positive}: `result` (explicit failure), `option`
- * (`null` on failure), and `is` (a type guard).
+ * (`null` on failure), `is` (a type guard), and `codec`, for
+ * `Descriptor.ConstructedComponent(Scalar.Positive.codec)`.
  *
  * @category Constructors
  */
-export const Positive = internal.Positive
+export const Positive: Constructor<Positive> = internal.Positive
 
 /**
  * Clamps one finite value between two finite bounds.

package/src/Segment2.ts

@@ -0,0 +1,71 @@
+/**
+ * Plain line segments stored by their ends, for hot-path collision against
+ * walls that are not axis-aligned (a map traced from survey data, a slanted
+ * fence, a polygon's edges).
+ *
+ * Like `Box2`, it is the plain form the collision helpers (`Collide2`) read
+ * every frame, built once from whatever the game stores. A wall is
+ * two-sided: a circle is kept off it on both sides and around both ends.
+ *
+ * @example
+ * ```ts
+ * const fence = Segment2.between({ x: 0, y: 0 }, { x: 40, y: 30 })
+ * const moved = Collide2.moveCircle(position, delta, radius, { segments: [fence] })
+ * ```
+ *
+ * @module Segment2
+ * @docGroup helpers
+ *
+ * @categoryDescription Segment Types
+ * The structural segment shape.
+ *
+ * @categoryDescription Operations
+ * Building segments and measuring them against points and circles.
+ */
+import type { Vec2 } from "./Vec2.ts"
+
+/**
+ * The segment from (`ax`, `ay`) to (`bx`, `by`). Both ends may be the same
+ * point, which is then a round post.
+ *
+ * @category Segment Types
+ */
+export interface Segment2 {
+  readonly ax: number
+  readonly ay: number
+  readonly bx: number
+  readonly by: number
+}
+
+/**
+ * The segment from `a` to `b`.
+ *
+ * @category Operations
+ */
+export const between = (a: Vec2, b: Vec2): Segment2 => ({ ax: a.x, ay: a.y, bx: b.x, by: b.y })
+
+/**
+ * The point of the segment nearest to `point`.
+ *
+ * @category Operations
+ */
+export const closestPoint = (segment: Segment2, point: Vec2): Vec2 => {
+  const ex = segment.bx - segment.ax
+  const ey = segment.by - segment.ay
+  const lengthSquared = ex * ex + ey * ey
+  if (lengthSquared < 1e-12) return { x: segment.ax, y: segment.ay }
+  const along = Math.max(0, Math.min(1, ((point.x - segment.ax) * ex + (point.y - segment.ay) * ey) / lengthSquared))
+  return { x: segment.ax + ex * along, y: segment.ay + ey * along }
+}
+
+/**
+ * Whether a circle overlaps (or touches) the segment.
+ *
+ * @category Operations
+ */
+export const overlapsCircle = (segment: Segment2, center: Vec2, radius: number): boolean => {
+  const nearest = closestPoint(segment, center)
+  const dx = center.x - nearest.x
+  const dy = center.y - nearest.y
+  return dx * dx + dy * dy <= radius * radius
+}

package/src/Size2.ts

@@ -31,6 +31,7 @@
  * Pure readers and raw views over already-validated size values.
  */
 import type * as Brand from "@typeonce/ritmo/Brand"
+import type { StandardSchema } from "@typeonce/ritmo/Descriptor"
 import * as internal from "./internal/size2.ts"
 import type * as Result from "@typeonce/ritmo/Result"
 import type * as Scalar from "./Scalar.ts"
@@ -67,16 +68,6 @@ export type Error = {
   readonly input: Raw
 }
 
-/**
- * Failure produced by `decode` when the input does not have the raw shape.
- *
- * @category Size Types
- */
-export type DecodeError = {
-  readonly tag: "Size2/Malformed"
-  readonly input: unknown
-}
-
 /**
  * Validates one raw size and returns an explicit result.
  *
@@ -84,13 +75,20 @@ export type DecodeError = {
  */
 export const result: (raw: Raw) => Result.Result<Size2, Error> = internal.result
 /**
- * Validates untrusted input of any shape, for example a value read from a
- * save file. Descriptors built from this module use it when restoring
- * snapshots.
+ * The codec of `Size2` (a Standard Schema, see `Descriptor.Codec`): give it to
+ * `Descriptor.ConstructedComponent(...)` so raw input and saves are validated.
+ * Its saved form is the raw shape, so it needs no `encode`. To put a `Size2`
+ * inside your own object schema, use {@link is} with your library's guard
+ * schema (`Schema.declare`, `z.custom`).
+ *
+ * @example
+ * ```ts
+ * const Position = Descriptor.ConstructedComponent(Size2.codec)("Game/Position")
+ * ```
  *
  * @category Construction
  */
-export const decode: (raw: unknown) => Result.Result<Size2, Error | DecodeError> = internal.decode
+export const codec: StandardSchema<Raw, Size2> = internal.codec
 /**
  * Validates one raw size and returns `null` on failure.
  *
@@ -98,11 +96,12 @@ export const decode: (raw: unknown) => Result.Result<Size2, Error | DecodeError>
  */
 export const option: (raw: Raw) => Size2 | null = internal.option
 /**
- * Checks whether one raw size already satisfies the size invariants.
+ * Whether any value is a valid `Size2`: a guard, also for building a
+ * `Size2` field in your own schema (`Schema.declare(Size2.is)`).
  *
  * @category Construction
  */
-export const is: (raw: Raw) => raw is Raw & Size2 = internal.is
+export const is: (raw: unknown) => raw is Size2 = internal.is
 /**
  * Converts one branded size back to a fresh raw object.
  *

package/src/Vector2.ts

@@ -36,6 +36,7 @@
  * Immutable vector math and normalization helpers on already-validated values.
  */
 import type * as Brand from "@typeonce/ritmo/Brand"
+import type { StandardSchema } from "@typeonce/ritmo/Descriptor"
 import * as internal from "./internal/vector2.ts"
 import type * as Result from "@typeonce/ritmo/Result"
 import type * as Scalar from "./Scalar.ts"
@@ -72,16 +73,6 @@ export type Error = {
   readonly input: Raw
 }
 
-/**
- * Failure produced by `decode` when the input does not have the raw shape.
- *
- * @category Vector Types
- */
-export type DecodeError = {
-  readonly tag: "Vector2/Malformed"
-  readonly input: unknown
-}
-
 /**
  * Explicit failure produced when a zero-length vector cannot be normalized.
  *
@@ -103,13 +94,20 @@ export type NormalizeError = {
  */
 export const result: (raw: Raw) => Result.Result<Vector2, Error> = internal.result
 /**
- * Validates untrusted input of any shape, for example a value read from a
- * save file. Descriptors built from this module use it when restoring
- * snapshots.
+ * The codec of `Vector2` (a Standard Schema, see `Descriptor.Codec`): give it to
+ * `Descriptor.ConstructedComponent(...)` so raw input and saves are validated.
+ * Its saved form is the raw shape, so it needs no `encode`. To put a `Vector2`
+ * inside your own object schema, use {@link is} with your library's guard
+ * schema (`Schema.declare`, `z.custom`).
+ *
+ * @example
+ * ```ts
+ * const Position = Descriptor.ConstructedComponent(Vector2.codec)("Game/Position")
+ * ```
  *
  * @category Construction
  */
-export const decode: (raw: unknown) => Result.Result<Vector2, Error | DecodeError> = internal.decode
+export const codec: StandardSchema<Raw, Vector2> = internal.codec
 /**
  * Validates one raw vector and returns `null` on failure.
  *
@@ -117,11 +115,12 @@ export const decode: (raw: unknown) => Result.Result<Vector2, Error | DecodeErro
  */
 export const option: (raw: Raw) => Vector2 | null = internal.option
 /**
- * Checks whether one raw vector already satisfies the vector invariants.
+ * Whether any value is a valid `Vector2`: a guard, also for building a
+ * `Vector2` field in your own schema (`Schema.declare(Vector2.is)`).
  *
  * @category Construction
  */
-export const is: (raw: Raw) => raw is Raw & Vector2 = internal.is
+export const is: (raw: unknown) => raw is Vector2 = internal.is
 /**
  * Converts one branded vector back to a fresh raw object.
  *

package/src/index.ts

@@ -2,12 +2,13 @@
  * Math for game code.
  *
  * Validated values (`Scalar`, `Vector2`, `Size2`, `Aabb`) expose
- * Result-returning constructors, so they plug into
- * `Descriptor.ConstructedComponent(...)` / `ConstructedResource(...)` and are
- * validated once at the boundary. `InputAxis` normalizes directional input.
+ * Result-returning constructors, a guard (`is`), and one `codec` each, so
+ * they plug into `Descriptor.ConstructedComponent(Vector2.codec)` /
+ * `ConstructedResource(Random.codec)` and are validated once at the boundary. `InputAxis` normalizes directional input.
  *
  * Hot-path helpers work on plain numbers every frame: `Vec2` arithmetic,
- * `Box2` edges, `Collide2` swept circle collision, a `SpatialGrid` broad
+ * `Box2` edges, `Segment2` walls at any angle, `Collide2` swept circle
+ * collision against both, a `SpatialGrid` broad
  * phase, a `FlowField` for finding the way around walls, and a deterministic
  * `Random` whose state is one integer.
  *
@@ -23,6 +24,7 @@ export * as InputAxis from "./InputAxis.ts"
 export * as Ops from "./Ops.ts"
 export * as Random from "./Random.ts"
 export * as Scalar from "./Scalar.ts"
+export * as Segment2 from "./Segment2.ts"
 export * as Size2 from "./Size2.ts"
 export * as SpatialGrid from "./SpatialGrid.ts"
 export * as Vec2 from "./Vec2.ts"

package/src/internal/aabb.ts

@@ -1,3 +1,4 @@
+import { codecOf } from "./codec.ts"
 import * as Result from "@typeonce/ritmo/Result"
 import * as Size2 from "../Size2.ts"
 import * as Vector2 from "../Vector2.ts"
@@ -36,7 +37,7 @@ export const option = (raw: Aabb.Raw): Aabb.Aabb | null => {
   return next.ok ? next.value : null
 }
 
-export const is = (raw: Aabb.Raw): raw is Aabb.Raw & Aabb.Aabb => result(raw).ok
+export const is = (raw: unknown): raw is Aabb.Aabb => decode(raw).ok
 
 export const position = (aabb: Aabb.Aabb): Vector2.Vector2 => aabb.position
 export const size = (aabb: Aabb.Aabb): Size2.Size2 => aabb.size
@@ -66,10 +67,15 @@ export const overlapsVertically = (first: Aabb.Aabb, second: Aabb.Aabb): boolean
 export const translate = (aabb: Aabb.Aabb, delta: Vector2.Vector2): Aabb.Aabb =>
   make(Vector2.add(aabb.position, delta), aabb.size)
 
-export const decode = (raw: unknown): Result.Result<Aabb.Aabb, Aabb.Error | Aabb.DecodeError> => {
+/** Untrusted input without the raw shape. */
+type Malformed = { readonly tag: "Aabb/Malformed"; readonly input: unknown }
+
+export const decode = (raw: unknown): Result.Result<Aabb.Aabb, Aabb.Error | Malformed> => {
   if (typeof raw !== "object" || raw === null) return Result.failure({ tag: "Aabb/Malformed", input: raw })
   const { position, size } = raw as Record<string, unknown>
   return isVector2Shape(position) && isSize2Shape(size)
     ? result({ position, size })
     : Result.failure({ tag: "Aabb/Malformed", input: raw })
 }
+
+export const codec = codecOf<Aabb.Raw, Aabb.Aabb>(decode, "a box { x, y, width, height } of finite numbers with a non-negative size")