murow 0.0.72 → 0.1.1

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/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,36 @@ 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_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;
+    private visibilityHandler;
     /**
      * Starts the game loop using requestAnimationFrame.
      *
-     * Resets timing to prevent large initial delta.
+     * Resets timing to prevent large initial delta and installs a
+     * visibilitychange handler so the first frame after a hidden tab
+     * doesn't deliver a multi-second delta.
      */
     start(): void;
     /**
@@ -38,7 +48,8 @@ export declare class RafDriver implements LoopDriver {
     /**
      * Internal loop method that calculates delta time and schedules the next frame.
      *
-     * Delta time is provided in seconds.
+     * 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/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";

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

@@ -0,0 +1,139 @@
+import type { InputSnapshot } from "../types";
+export interface AxisOptions {
+    /** Initial value, radians. Default 0. */
+    initial?: number;
+    /** Lower clamp, radians. Default -Infinity (unbounded). */
+    min?: number;
+    /** Upper clamp, radians. Default +Infinity (unbounded). */
+    max?: number;
+}
+export interface MouseLookOptions {
+    /** Radians per pixel of mouse motion. Default 0.002. */
+    sensitivity?: number;
+    /**
+     * Yaw axis config. Default: unbounded (yaw wraps freely around the
+     * vertical axis). Clamp it for cameras that don't rotate fully.
+     */
+    yaw?: AxisOptions;
+    /**
+     * Pitch axis config. Default min/max: ±PI/2 - 0.01 (just shy of
+     * straight up/down so the basis vectors stay well-defined).
+     */
+    pitch?: AxisOptions;
+    /**
+     * Flip horizontal look direction. With the default (false), moving
+     * the mouse right rotates the view right; set true to invert.
+     */
+    invertX?: boolean;
+    /**
+     * Flip vertical look direction. With the default (false), moving the
+     * mouse up tilts the view up; set true for flight-sim style.
+     */
+    invertY?: boolean;
+    /**
+     * Accept drag-to-look as a fallback for platforms without Pointer Lock
+     * (iOS Safari). When true, `update(input)` accumulates while
+     * `dragButton` is held even without an active lock. Default true.
+     */
+    drag?: boolean;
+    /** Mouse button that drives drag-to-look. Default 'left'. */
+    dragButton?: "left" | "middle" | "right";
+}
+/**
+ * Yaw/pitch state driven by mouse motion, with optional pointer lock and
+ * drag-to-look fallback.
+ *
+ * The class owns the input handling. Output helpers (`forward`, `right`,
+ * `up`, `orbit`) are read-only views computed from yaw/pitch each call.
+ *
+ * Zero-alloc: each output has its own backing `Float32Array(3)` reused
+ * across calls. Don't hold a reference past the next call to the same
+ * accessor; the values will overwrite. Copy if you need to persist.
+ *
+ * Usage:
+ * ```ts
+ * const look = new MouseLook({ sensitivity: 0.002 });
+ *
+ * canvas.addEventListener('click', () => {
+ *     look.lock(canvas).catch(() => {}); // iOS: drag-to-look takes over
+ * });
+ *
+ * loop.events.on('tick', ({ input }) => {
+ *     look.update(input);
+ *
+ *     // FPS:
+ *     const pos = renderer.camera.position;
+ *     const f = look.forward;
+ *     renderer.camera.setTarget(pos[0] + f[0], pos[1] + f[1], pos[2] + f[2]);
+ *
+ *     // Or TPS / orbit:
+ *     const c = look.orbit(playerPos, 8);
+ *     renderer.camera.setPosition(c[0], c[1], c[2]);
+ *     renderer.camera.setTarget(playerPos[0], playerPos[1], playerPos[2]);
+ * });
+ * ```
+ */
+export declare class MouseLook {
+    yaw: number;
+    pitch: number;
+    sensitivity: number;
+    yawMin: number;
+    yawMax: number;
+    pitchMin: number;
+    pitchMax: number;
+    invertX: boolean;
+    invertY: boolean;
+    drag: boolean;
+    dragButton: "left" | "middle" | "right";
+    private lockedElement;
+    /** Active `pointerlockchange`/`error` listeners from an in-flight `lock()`. */
+    private pendingLockCleanup;
+    private _forward;
+    private _right;
+    private _up;
+    private _orbit;
+    constructor(opts?: MouseLookOptions);
+    /**
+     * Apply input deltas. Gated internally: writes happen when pointer
+     * lock is active, or (if `drag` is true) while `dragButton` is held.
+     */
+    update(input: InputSnapshot): void;
+    /**
+     * Request pointer lock on `element`. Resolves once locked. Rejects if
+     * Pointer Lock API is unavailable (iOS Safari) or the browser denies
+     * the request, in which case drag-to-look takes over (if enabled).
+     */
+    lock(element: HTMLElement): Promise<void>;
+    /** Release pointer lock if currently held. */
+    unlock(): void;
+    /** True while pointer lock is active on the element we locked to. */
+    get locked(): boolean;
+    /**
+     * Unit vector pointing the way the camera is facing. Shared buffer:
+     * don't hold the returned reference past the next `forward` read.
+     */
+    get forward(): Float32Array;
+    /**
+     * Right direction. Lies in the XZ plane, independent of pitch.
+     * Shared buffer: don't hold the returned reference past the next
+     * `right` read.
+     */
+    get right(): Float32Array;
+    /**
+     * Camera-local up. Tilts with pitch. Shared buffer: don't hold the
+     * returned reference past the next `up` read.
+     */
+    get up(): Float32Array;
+    /**
+     * Camera position in orbit around `target` at `distance`, given the
+     * current yaw/pitch. Pairs naturally with `setTarget(target)` to
+     * point the camera back at the orbited object. Shared buffer: don't
+     * hold the returned reference past the next `orbit` call.
+     */
+    orbit(target: ArrayLike<number>, distance: number): Float32Array;
+    /**
+     * Release pointer lock, drop the locked element, and detach any
+     * in-flight `lock()` listeners. Safe to call multiple times.
+     */
+    destroy(): void;
+}

package/dist/types/core/input/scroll-zoom/index.d.ts

@@ -0,0 +1 @@
+export * from "./scroll-zoom";

package/dist/types/core/input/scroll-zoom/scroll-zoom.d.ts

@@ -0,0 +1,38 @@
+import type { InputSnapshot } from "../types";
+export interface ScrollZoomOptions {
+    /** Starting value. */
+    initial: number;
+    /** Lower clamp. */
+    min: number;
+    /** Upper clamp. */
+    max: number;
+    /**
+     * Multiplied with the per-tick scroll delta. Positive scroll (wheel
+     * forward / two-finger up) increases `value` by `sensitivity *
+     * deltaScrollY`. Use a negative sensitivity to invert. Default 0.01.
+     */
+    sensitivity?: number;
+}
+/**
+ * Scroll-wheel driven scalar with clamps. Use for orbit distance, FOV,
+ * RTS camera height, anything that's "scroll to change a number."
+ *
+ * Usage:
+ * ```ts
+ * const zoom = new ScrollZoom({ initial: 8, min: 3, max: 20 });
+ *
+ * loop.events.on('tick', ({ input }) => {
+ *     zoom.update(input);
+ *     const [cx, cy, cz] = mouseLook.orbit(playerPos, zoom.value);
+ *     // ...
+ * });
+ * ```
+ */
+export declare class ScrollZoom {
+    value: number;
+    min: number;
+    max: number;
+    sensitivity: number;
+    constructor(opts: ScrollZoomOptions);
+    update(input: InputSnapshot): void;
+}

package/dist/types/ecs/component.d.ts

@@ -1,11 +1,17 @@
 import { Schema } from "../core/binary-codec";
 import { ArrayField } from "../core/pooled-codec";
 /**
- * Metadata for a component definition
+ * Metadata for a component definition.
+ *
+ * The second type parameter `S` carries the precise schema literal type
+ * (e.g. `{ x: Field<number, Float32Array>, y: Field<number, Uint8Array> }`)
+ * so that `world.fields(component)` can return a per-field typed-array
+ * map without casts. Defaults to the loose `Schema<T>` for compatibility
+ * with callers that don't preserve the narrow schema.
  */
-export interface ComponentMeta<T extends object> {
+export interface ComponentMeta<T extends object, S extends Schema<T> = Schema<T>> {
     /** Schema defining the component's binary layout */
-    schema: Schema<T>;
+    schema: S;
     /** Unique name for this component type */
     name: string;
     /** Size of the component in bytes */
@@ -18,33 +24,83 @@ export interface ComponentMeta<T extends object> {
     arrayCodec: ArrayField<T>;
 }
 /**
- * Component type returned by defineComponent
+ * Component type returned by defineComponent.
+ *
+ * `T` is the value-shape inferred from the schema. `S` is the precise
+ * schema literal type, used by `world.fields()` to return per-field
+ * typed-array maps with exact element types (Float32Array vs Uint8Array
+ * vs ...). When omitted, `S` defaults to the loose `Schema<T>` and
+ * `world.fields()` falls back to a broad TypedArray union per field.
  */
-export type Component<T extends object = any> = ComponentMeta<T> & {
+export type Component<T extends object = any, S extends Schema<T> = Schema<T>> = ComponentMeta<T, S> & {
     /** Type marker for TypeScript inference */
     __type?: T;
     /** Internal: Index assigned by World when registered */
     __worldIndex?: number;
+    /**
+     * Opaque metadata attached by higher-level packages (e.g. `murow/netcode`
+     * stores `SyncSpec` here to mark a component as networked). Core never
+     * interprets this; readers narrow it to the shape they own.
+     */
+    __sync?: unknown;
 };
 /**
  * Infer the data type from a Component
  */
-export type InferComponentType<C> = C extends Component<infer T> ? T : never;
+export type InferComponentType<C> = C extends Component<infer T, any> ? T : never;
+/**
+ * Descriptor form of `defineComponent`. Pass `{ schema, sync }` to attach
+ * opaque sync metadata (consumed by `murow/netcode` to mark the component
+ * as networked).
+ */
+export interface ComponentDescriptor<T extends object, S extends Schema<T> = Schema<T>> {
+    schema: S;
+    sync: unknown;
+}
+/**
+ * Helper: derive the value-shape `T` from a narrowly-typed schema literal.
+ * Each entry must be a `Field<T[K], any>`, and we extract the `T[K]` per key.
+ */
+type InferSchemaShape<S> = {
+    [K in keyof S]: S[K] extends import("../core/binary-codec").Field<infer V, any> ? V : never;
+};
 /**
  * Define a component type with its binary schema.
  *
- * @example
+ * Two call shapes are supported:
+ * - Bare schema (the common case): `defineComponent(name, schema)`
+ * - Descriptor with sync metadata: `defineComponent(name, { schema, sync })`
+ *
+ * The descriptor form attaches `__sync` to the returned component. Core
+ * doesn't interpret `__sync`; it's read by higher-level packages such as
+ * `murow/netcode`. The check for descriptor form is `'schema' in arg &&
+ * 'sync' in arg`, which is unambiguous because real component field names
+ * never collide with both keys at once.
+ *
+ * The schema literal type is preserved through inference so that
+ * `world.fields(component)` returns precisely-typed typed arrays per
+ * field (Float32Array vs Uint8Array vs Uint16Array etc.) without casts.
+ *
+ * @example Bare schema
  * ```typescript
  * const Transform = defineComponent('Transform', {
  *   x: BinaryCodec.f32,
  *   y: BinaryCodec.f32,
  *   rotation: BinaryCodec.f32,
  * });
+ * ```
  *
- * const Health = defineComponent('Health', {
- *   current: BinaryCodec.u16,
- *   max: BinaryCodec.u16,
+ * @example Descriptor with sync
+ * ```typescript
+ * const Position = defineComponent('Position', {
+ *   schema: { x: f32, y: f32 },
+ *   sync: { rate: 'every-tick', interest: 'aoi' },
  * });
  * ```
  */
-export declare function defineComponent<T extends object>(name: string, schema: Schema<T>): Component<T>;
+export declare function defineComponent<S extends Record<string, import("../core/binary-codec").Field<any, any>>>(name: string, schema: S): Component<InferSchemaShape<S> & object, S extends Schema<InferSchemaShape<S> & object> ? S : never>;
+export declare function defineComponent<S extends Record<string, import("../core/binary-codec").Field<any, any>>>(name: string, def: {
+    schema: S;
+    sync: unknown;
+}): Component<InferSchemaShape<S> & object, S extends Schema<InferSchemaShape<S> & object> ? S : never>;
+export {};