murow 0.0.73 → 0.1.3

package/dist/types/core/binary-codec/binary-codec.d.ts

@@ -2,8 +2,19 @@
  * A binary field descriptor.
  * Defines how a single value is serialized/deserialized
  * at a fixed byte size.
+ *
+ * The second type parameter `A` is a compile-time-only marker for the
+ * typed array kind used when this field is stored in an ECS World's
+ * Structure-of-Arrays column. Tagging `f32 → Float32Array`, `u8 →
+ * Uint8Array`, etc. lets `world.fields(Component)` return precisely
+ * typed Float32Array / Int32Array / ... per field without casts. The
+ * parameter is purely structural — it never appears at runtime.
+ *
+ * Defaults to `unknown` so existing call sites continue to compile.
+ * Composite fields (vec2/vec3/color/string) leave `A` defaulted; only
+ * the scalar primitives narrow it.
  */
-export type Field<T> = {
+export type Field<T, A = unknown> = {
     /** Size of the field in bytes */
     size: number;
     /**
@@ -23,6 +34,13 @@ export type Field<T> = {
      * Returns the nil value
      */
     toNil(): T;
+    /**
+     * Compile-time-only phantom marker for the SoA typed array kind. Never
+     * read at runtime; never written by any of the primitives. Exists so
+     * `Field<number, Float32Array>` and `Field<number, Uint8Array>` are
+     * structurally distinguishable to TypeScript.
+     */
+    readonly __array?: A;
 };
 /**
  * A schema mapping object keys to binary fields.
@@ -33,8 +51,19 @@ export type Field<T> = {
  * Do not rely on computed or dynamic keys.
  */
 export type Schema<T> = {
-    [K in keyof T]: Field<T[K]>;
+    [K in keyof T]: Field<T[K], any>;
 };
+/**
+ * Helper for extracting the per-field typed-array kind from a schema.
+ *
+ * Given a precise schema literal like `{ x: BinaryCodec.f32, y: BinaryCodec.u8 }`
+ * (inferred narrowly, not widened to `Schema<T>`), this maps each field to
+ * its tagged array kind: `{ x: Float32Array, y: Uint8Array }`.
+ *
+ * Fields whose `A` is `unknown` (composites: vec/color/string) fall back
+ * to the broad TypedArray union.
+ */
+export type ArrayFromField<F> = F extends Field<any, infer A> ? unknown extends A ? Float32Array | Int32Array | Uint32Array | Uint16Array | Uint8Array | Int8Array | Int16Array | Float64Array : A : never;
 /**
  * Base codec implementation.
  * Handles schema-driven encoding/decoding.
@@ -69,25 +98,25 @@ export declare class BaseBinaryCodec {
  */
 export declare class BinaryPrimitives {
     /** Unsigned 8-bit integer */
-    static readonly u8: Field<number>;
+    static readonly u8: Field<number, Uint8Array>;
     /** Unsigned 16-bit integer (big-endian) */
-    static readonly u16: Field<number>;
+    static readonly u16: Field<number, Uint16Array>;
     /** Unsigned 32-bit integer (big-endian) */
-    static readonly u32: Field<number>;
+    static readonly u32: Field<number, Uint32Array>;
     /** Signed 8-bit integer */
-    static readonly i8: Field<number>;
+    static readonly i8: Field<number, Int8Array>;
     /** Signed 16-bit integer (big-endian) */
-    static readonly i16: Field<number>;
+    static readonly i16: Field<number, Int16Array>;
     /** Signed 32-bit integer (big-endian) */
-    static readonly i32: Field<number>;
-    /** 16-bit floating point number (IEEE 754, big-endian) */
-    static readonly f16: Field<number>;
+    static readonly i32: Field<number, Int32Array>;
+    /** 16-bit floating point number (IEEE 754, big-endian) — stored as raw u16 bits */
+    static readonly f16: Field<number, Uint16Array>;
     /** 32-bit floating point number (IEEE 754, big-endian) */
-    static readonly f32: Field<number>;
+    static readonly f32: Field<number, Float32Array>;
     /** 64-bit floating point number (double, big-endian) */
-    static readonly f64: Field<number>;
+    static readonly f64: Field<number, Float64Array>;
     /** Boolean stored as 1 byte (0 = false, 1 = true) */
-    static readonly bool: Field<boolean>;
+    static readonly bool: Field<boolean, Uint8Array>;
     /**
      * String field with UTF-8 encoding and 2-byte length prefix.
      * @param maxLength Maximum number of bytes allowed
@@ -112,17 +141,17 @@ export declare class BinaryPrimitives {
         a: number;
     }>;
     /** 32-bit floating point number (IEEE 754, little-endian) */
-    static readonly f32_le: Field<number>;
+    static readonly f32_le: Field<number, Float32Array>;
     /** 64-bit floating point number (double, little-endian) */
-    static readonly f64_le: Field<number>;
+    static readonly f64_le: Field<number, Float64Array>;
     /** Unsigned 16-bit integer (little-endian) */
-    static readonly u16_le: Field<number>;
+    static readonly u16_le: Field<number, Uint16Array>;
     /** Unsigned 32-bit integer (little-endian) */
-    static readonly u32_le: Field<number>;
+    static readonly u32_le: Field<number, Uint32Array>;
     /** Signed 16-bit integer (little-endian) */
-    static readonly i16_le: Field<number>;
+    static readonly i16_le: Field<number, Int16Array>;
     /** Signed 32-bit integer (little-endian) */
-    static readonly i32_le: Field<number>;
+    static readonly i32_le: Field<number, Int32Array>;
     /**
      * 2D vector of f32 stored as a tuple [x, y] (little-endian).
      * Useful for compact math data or shader-friendly layouts.
@@ -145,43 +174,43 @@ export declare class BinaryPrimitives {
  */
 export declare class BinaryCodec extends BaseBinaryCodec {
     /** Unsigned 8-bit integer field */
-    static readonly u8: Field<number>;
+    static readonly u8: Field<number, Uint8Array<ArrayBufferLike>>;
     /** Unsigned 16-bit integer field */
-    static readonly u16: Field<number>;
+    static readonly u16: Field<number, Uint16Array<ArrayBufferLike>>;
     /** Unsigned 32-bit integer field */
-    static readonly u32: Field<number>;
+    static readonly u32: Field<number, Uint32Array<ArrayBufferLike>>;
     /** Signed 8-bit integer field */
-    static readonly i8: Field<number>;
+    static readonly i8: Field<number, Int8Array<ArrayBufferLike>>;
     /** Signed 16-bit integer field */
-    static readonly i16: Field<number>;
+    static readonly i16: Field<number, Int16Array<ArrayBufferLike>>;
     /** Signed 32-bit integer field */
-    static readonly i32: Field<number>;
+    static readonly i32: Field<number, Int32Array<ArrayBufferLike>>;
     /** 16-bit floating point field */
-    static readonly f16: Field<number>;
+    static readonly f16: Field<number, Uint16Array<ArrayBufferLike>>;
     /** 32-bit floating point field */
-    static readonly f32: Field<number>;
+    static readonly f32: Field<number, Float32Array<ArrayBufferLike>>;
     /** Boolean field */
-    static readonly bool: Field<boolean>;
+    static readonly bool: Field<boolean, Uint8Array<ArrayBufferLike>>;
     /** String field with length prefix */
     static string: typeof BinaryPrimitives.string;
     /** 2D vector field */
     static readonly vec2: Field<{
         x: number;
         y: number;
-    }>;
+    }, unknown>;
     /** 3D vector field */
     static readonly vec3: Field<{
         x: number;
         y: number;
         z: number;
-    }>;
+    }, unknown>;
     /** RGBA color field */
     static readonly color: Field<{
         r: number;
         g: number;
         b: number;
         a: number;
-    }>;
+    }, unknown>;
     /**
      * Encodes an object into a binary buffer.
      */
@@ -191,3 +220,32 @@ export declare class BinaryCodec extends BaseBinaryCodec {
      */
     static decode<T extends object>(schema: Schema<T>, buf: Uint8Array, target: T): T;
 }
+export declare const u8: Field<number, Uint8Array<ArrayBufferLike>>;
+export declare const u16: Field<number, Uint16Array<ArrayBufferLike>>;
+export declare const u32: Field<number, Uint32Array<ArrayBufferLike>>;
+export declare const i8: Field<number, Int8Array<ArrayBufferLike>>;
+export declare const i16: Field<number, Int16Array<ArrayBufferLike>>;
+export declare const i32: Field<number, Int32Array<ArrayBufferLike>>;
+export declare const f16: Field<number, Uint16Array<ArrayBufferLike>>;
+export declare const f32: Field<number, Float32Array<ArrayBufferLike>>;
+export declare const f64: Field<number, Float64Array<ArrayBufferLike>>;
+export declare const bool: Field<boolean, Uint8Array<ArrayBufferLike>>;
+export declare const string: typeof BinaryPrimitives.string;
+export declare const vec2: Field<{
+    x: number;
+    y: number;
+}, unknown>;
+export declare const vec3: Field<{
+    x: number;
+    y: number;
+    z: number;
+}, unknown>;
+export declare const vec2_le: Field<[number, number], unknown>;
+export declare const vec3_le: Field<[number, number, number], unknown>;
+export declare const vec4_le: Field<[number, number, number, number], unknown>;
+export declare const color: Field<{
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}, unknown>;

package/dist/types/core/clock/clock.d.ts

@@ -0,0 +1,37 @@
+export interface SlewClockOptions {
+    /** Drift under this advances at nominal rate instead of warping. Default 0.25. */
+    deadZone?: number;
+    /** Step bounds while warping to close a gap. */
+    warp?: {
+        /** Minimum step when warping to close a gap. Default 0.6. */
+        min?: number;
+        /** Maximum step when warping to close a gap. Default 1.4. */
+        max?: number;
+    };
+    /** Per-unit-of-drift warp gain. Default 0.1. */
+    gain?: number;
+}
+/**
+ * A scalar that advances one nominal step per `advance` toward a moving
+ * target, slewing within a band to close drift, holding steady inside a
+ * dead-zone, and snapping when the forward gap is too large to chase.
+ *
+ * Domain-agnostic: the caller supplies the target and the snap threshold.
+ */
+export declare class SlewClock {
+    private _value;
+    private readonly deadZone;
+    private readonly warpMin;
+    private readonly warpMax;
+    private readonly gain;
+    constructor(opts?: SlewClockOptions);
+    get value(): number;
+    get initialized(): boolean;
+    reset(): void;
+    /**
+     * Advance toward `target`. Seeds to `target` on first call. Forward drift
+     * beyond `snap` jumps to `target`; drift inside the dead-zone advances one
+     * nominal step; otherwise the step warps within the band to close the gap.
+     */
+    advance(target: number, snap: number): number;
+}

package/dist/types/core/clock/index.d.ts

@@ -0,0 +1 @@
+export { SlewClock, type SlewClockOptions } from './clock';

package/dist/types/core/driver/driver.d.ts

@@ -13,7 +13,7 @@ export interface LoopDriver {
     /** Internal loop iteration method */
     loop(): void;
     /** Update callback invoked each frame with delta time in seconds */
-    update(dt: number): void;
+    update(deltaTime: number): void;
 }
 /**
  * Type of driver to use for the game loop.
@@ -35,24 +35,24 @@ export type DriverType = 'server-immediate' | 'client' | 'server-timeout';
  * @example
  * ```typescript
  * // Client
- * const clientDriver = createDriver('client', (dt) => {
- *   game.update(dt);
+ * const clientDriver = createDriver('client', (deltaTime) => {
+ *   game.update(deltaTime);
  *   renderer.render();
  * });
  * clientDriver.start();
  *
  * // Server (maximum performance)
- * const serverDriver = createDriver('server', (dt) => {
- *   simulation.tick(dt);
+ * const serverDriver = createDriver('server', (deltaTime) => {
+ *   simulation.tick(deltaTime);
  * });
  * serverDriver.start();
  *
  * // Server (balanced with I/O)
- * const balancedDriver = createDriver('server-timeout', (dt) => {
- *   simulation.tick(dt);
+ * const balancedDriver = createDriver('server-timeout', (deltaTime) => {
+ *   simulation.tick(deltaTime);
  *   handleNetworkIO();
  * });
  * balancedDriver.start();
  * ```
  */
-export declare function createDriver(type: DriverType, update: (dt: number) => void): ImmediateDriver | RafDriver | TimeoutDriver;
+export declare function createDriver(type: DriverType, update: (deltaTime: number) => void): ImmediateDriver | RafDriver | TimeoutDriver;

package/dist/types/core/driver/drivers/immediate.d.ts

@@ -11,19 +11,19 @@ import { LoopDriver } from "../driver";
  *
  * @example
  * ```typescript
- * const driver = new ImmediateDriver((dt) => {
- *   world.tick(dt);
+ * const driver = new ImmediateDriver((deltaTime) => {
+ *   world.tick(deltaTime);
  *   broadcastState();
  * });
  * driver.start();
  * ```
  */
 export declare class ImmediateDriver implements LoopDriver {
-    update: (dt: number) => void;
+    update: (deltaTime: number) => void;
     /**
      * @param update - Callback invoked each tick with delta time in seconds
      */
-    constructor(update: (dt: number) => void);
+    constructor(update: (deltaTime: number) => void);
     private last;
     private running;
     /**

package/dist/types/core/driver/drivers/raf.d.ts

@@ -9,26 +9,26 @@ import { LoopDriver } from "../driver";
  *
  * @example
  * ```typescript
- * const driver = new RafDriver((dt) => {
- *   player.update(dt);
+ * const driver = new RafDriver((deltaTime) => {
+ *   player.update(deltaTime);
  *   renderer.render();
  * });
  * driver.start();
  * ```
  */
 export declare class RafDriver implements LoopDriver {
-    update: (dt: number) => void;
+    update: (deltaTime: number) => void;
     /**
      * Hard upper bound on a single frame's delta, in ms. Long pauses (tab
      * backgrounded, breakpoint hit, browser throttling) deliver one huge
      * frame on resume. Clamping keeps the engine from trying to "catch up"
      * by replaying that lost time at high speed.
      */
-    private static readonly MAX_DT_MS;
+    private static readonly MAX_DELTA_MS;
     /**
      * @param update - Callback invoked each frame with delta time in seconds
      */
-    constructor(update: (dt: number) => void);
+    constructor(update: (deltaTime: number) => void);
     private last;
     private running;
     private rafId;
@@ -48,7 +48,7 @@ export declare class RafDriver implements LoopDriver {
     /**
      * Internal loop method that calculates delta time and schedules the next frame.
      *
-     * Delta time is provided in seconds, clamped to `MAX_DT_MS` so a paused
+     * Delta time is provided in seconds, clamped to `MAX_DELTA_MS` so a paused
      * tab doesn't deliver a multi-second frame.
      */
     loop: () => void;

package/dist/types/core/driver/drivers/timeout.d.ts

@@ -16,19 +16,19 @@ import { LoopDriver } from "../driver";
  *
  * @example
  * ```typescript
- * const driver = new TimeoutDriver((dt) => {
- *   world.tick(dt);
+ * const driver = new TimeoutDriver((deltaTime) => {
+ *   world.tick(deltaTime);
  *   broadcastState();
  * });
  * driver.start();
  * ```
  */
 export declare class TimeoutDriver implements LoopDriver {
-    update: (dt: number) => void;
+    update: (deltaTime: number) => void;
     /**
      * @param update - Callback invoked each tick with delta time in seconds
      */
-    constructor(update: (dt: number) => void);
+    constructor(update: (deltaTime: number) => void);
     private last;
     private running;
     /**

package/dist/types/core/hitbox/hitbox-library.d.ts

@@ -0,0 +1,29 @@
+import { Hitbox } from './hitbox';
+/**
+ * HitboxLibrary — a named, mode-typed registry of `Hitbox` definitions.
+ *
+ * The canonical set of collision archetypes a game uses, declared once in
+ * shared code and read by the renderer (client picking), game logic, and a
+ * headless server alike. Resolves by name (`get`, serializable/authoring)
+ * or by index (`at`, for ECS components that store a numeric archetype).
+ *
+ * `add` accumulates the name union, so `bucket.hitboxes(lib)` can offer the
+ * registered names as an autocompleting, typo-checked literal type.
+ */
+export declare class HitboxLibrary<M extends '2d' | '3d' = '3d', Names extends string = never> {
+    readonly mode: M;
+    private readonly names;
+    private readonly boxes;
+    private readonly index;
+    constructor(mode: M);
+    /** Register a hitbox under `name`. Returns a library whose type carries the new name. */
+    add<const N extends string>(name: N, hitbox: Hitbox<M>): HitboxLibrary<M, Names | N>;
+    /** Resolve by name. Throws on an unknown name. */
+    get(name: Names): Hitbox<M>;
+    /** Resolve by index — the fast path for ECS components storing a numeric archetype. */
+    at(index: number): Hitbox<M>;
+    /** Numeric index for a name, for storing on an entity. Throws on an unknown name. */
+    indexOf(name: Names): number;
+    /** Registered names, in insertion order. */
+    keys(): readonly string[];
+}

package/dist/types/core/hitbox/hitbox.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Hitbox — a named set of collision shapes in model-local space.
+ *
+ * Declared once and shared across every prefab/instance that uses it. Pure
+ * data: no GPU, no per-instance state. The renderer picks against it; game
+ * logic and a headless server run authoritative hit tests against the same
+ * object. Shapes are scaled by instance scale at test time.
+ *
+ * The mode parameter (`'2d'` | `'3d'`) gates which shapes `add` accepts and
+ * accumulates the part-name union so consumers can narrow `hit.part`.
+ */
+export type Shape3D = {
+    readonly shape: 'sphere';
+    readonly radius: number;
+    readonly offset?: readonly [number, number, number];
+} | {
+    readonly shape: 'box';
+    readonly size: readonly [number, number, number];
+    readonly offset?: readonly [number, number, number];
+} | {
+    readonly shape: 'cylinder';
+    readonly radius: number;
+    readonly height: number;
+    readonly offset?: readonly [number, number, number];
+};
+export type Shape2D = {
+    readonly shape: 'circle';
+    readonly radius: number;
+    readonly offset?: readonly [number, number];
+} | {
+    readonly shape: 'rect';
+    readonly size: readonly [number, number];
+    readonly offset?: readonly [number, number];
+} | {
+    readonly shape: 'capsule';
+    readonly radius: number;
+    readonly length: number;
+    readonly offset?: readonly [number, number];
+};
+export type ShapeForMode<M extends '2d' | '3d'> = M extends '3d' ? Shape3D : Shape2D;
+export type HitboxPart<M extends '2d' | '3d'> = {
+    readonly name: string;
+} & ShapeForMode<M>;
+export declare class Hitbox<M extends '2d' | '3d' = '3d', Names extends string = never> {
+    readonly mode: M;
+    readonly parts: readonly HitboxPart<M>[];
+    constructor(mode: M, parts?: readonly HitboxPart<M>[]);
+    /** Add a named shape. Returns a new Hitbox whose type carries the added name. */
+    add<const N extends string>(name: N, shape: ShapeForMode<M>): Hitbox<M, Names | N>;
+}

package/dist/types/core/hitbox/index.d.ts

@@ -0,0 +1,3 @@
+export * from './hitbox';
+export * from './hitbox-library';
+export * from './test';

package/dist/types/core/hitbox/test.d.ts

@@ -0,0 +1,44 @@
+import type { Ray3D } from '../ray/ray-3d';
+import type { Hitbox, HitboxPart } from './hitbox';
+/** Nearest part struck plus where. The `point` is filled in 3D only. */
+export interface PartHit {
+    part: string;
+    distance: number;
+    point: [number, number, number];
+}
+/**
+ * A 3D part resolved to world space: its center after offset, and the
+ * half-extents after per-axis scale. Single-radius shapes (sphere,
+ * cylinder) inflate by the largest relevant axis so they enclose a
+ * non-uniformly scaled visual rather than clipping inside it. The single
+ * source of placement truth shared by picking and debug rendering.
+ */
+export interface PlacedPart {
+    cx: number;
+    cy: number;
+    cz: number;
+    hx: number;
+    hy: number;
+    hz: number;
+}
+/** Place a 3D part at world center `(cx,cy,cz)` grown by scale `(sx,sy,sz)`. Reused output. */
+export declare function placePart3D(part: HitboxPart<'3d'>, cx: number, cy: number, cz: number, sx: number, sy: number, sz: number): PlacedPart;
+/**
+ * Entry-test a ray against a 3D hitbox placed at world center `(cx,cy,cz)`
+ * and grown by per-axis scale `(sx,sy,sz)`. Returns the nearest part the
+ * ray enters (a reused object, valid until the next call) or `null`.
+ */
+export declare function testHitbox3D(ray: Ray3D, hitbox: Hitbox<'3d'>, cx: number, cy: number, cz: number, sx: number, sy: number, sz: number): PartHit | null;
+/**
+ * Point-test against a 2D hitbox at center `(cx,cy)`, scaled `(sx,sy)`,
+ * rotated by `rot` radians. The world point is rotated into the hitbox's
+ * local frame, then tested against each part. Returns the first part
+ * containing the point (a reused object) or `null`.
+ */
+export declare function testHitbox2D(hitbox: Hitbox<'2d'>, cx: number, cy: number, sx: number, sy: number, rot: number, wx: number, wy: number): PartHit | null;
+/**
+ * Point inside a sprite's rendered quad: an `sx` by `sy` rect centered at
+ * `(cx,cy)`, rotated by `rot`. The default pick bound for a sprite with no
+ * declared hitbox.
+ */
+export declare function pointInQuad2D(cx: number, cy: number, sx: number, sy: number, rot: number, wx: number, wy: number): boolean;

package/dist/types/core/index.d.ts

@@ -7,9 +7,15 @@ export * from './driver';
 export * from './navmesh';
 export * from './pooled-codec';
 export * from './prediction';
+export * from './clock';
+export * from './timeline';
 export * from './input';
 export * from './free-list';
 export * from './sparse-batcher';
+export * from './slot-map';
+export * from './state-machine';
 export * from './simple-rng';
 export * from './ray';
+export * from './raycast';
+export * from './hitbox';
 export * from '../renderer';

package/dist/types/core/input/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./manager";
 export * from "./sources";
+export * from "./mouse-look";
+export * from "./scroll-zoom";
 export type { InputSnapshot } from "./types";

package/dist/types/core/input/mouse-look/index.d.ts

@@ -0,0 +1 @@
+export * from "./mouse-look";