murow 0.0.73 → 0.1.3

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

@@ -0,0 +1,34 @@
+export interface TimelineEntry<S> {
+    tick: number;
+    receivedAt: number;
+    sample: S;
+}
+/**
+ * A bounded, tick-ordered ring of timestamped samples. Inserts in tick order
+ * (dedup by tick), prunes to capacity, and drops history when a wall-clock gap
+ * exceeds the stale window. Knows nothing about what a sample contains.
+ */
+export declare class Timeline<S> {
+    private entries;
+    private _latestReceivedAt;
+    capacity: number;
+    staleWindow: number;
+    constructor(capacity: number, staleWindowMs: number);
+    get length(): number;
+    get latestReceivedAt(): number;
+    at(index: number): TimelineEntry<S>;
+    newest(): TimelineEntry<S> | undefined;
+    oldest(): TimelineEntry<S> | undefined;
+    setStaleWindow(staleWindowMs: number): void;
+    clear(): void;
+    /**
+     * Insert a sample in tick order. Returns true if a wall-clock gap beyond
+     * the stale window dropped the existing history first.
+     */
+    record(tick: number, receivedAt: number, sample: S): boolean;
+    /**
+     * Indices `[a, b]` of the consecutive entries straddling `tick`
+     * (`entries[a].tick <= tick <= entries[b].tick`), or null if none.
+     */
+    straddle(tick: number): [number, number] | null;
+}

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 {};

package/dist/types/ecs/entity-handle.d.ts

@@ -96,7 +96,7 @@ export declare class EntityHandle {
      * const velocityVx = entity.field(Velocity, 'vx');
      *
      * // Direct array access - same as RAW API!
-     * transformX[entity.id] += velocityVx[entity.id] * dt;
+     * transformX[entity.id] += velocityVx[entity.id] * deltaTime;
      * ```
      */
     field<T extends object, K extends keyof T>(component: Component<T>, field: K): Float32Array | Int32Array | Uint32Array | Uint16Array | Uint8Array;
@@ -149,8 +149,8 @@ export declare class EntityHandle {
      * const velocity = entity.get(Velocity);    // Uses cached data
      *
      * entity
-     *   .setField(Transform, 'x', transform.x + velocity.vx * dt)
-     *   .setField(Transform, 'y', transform.y + velocity.vy * dt)
+     *   .setField(Transform, 'x', transform.x + velocity.vx * deltaTime)
+     *   .setField(Transform, 'y', transform.y + velocity.vy * deltaTime)
      *   .flush();
      * ```
      */
@@ -189,8 +189,8 @@ export declare class EntityHandle {
      * ```typescript
      * // Mutate fields directly
      * entity.setFields(Transform, function (t) {
-     *   t.x += velocity.vx * dt;
-     *   t.y += velocity.vy * dt;
+     *   t.x += velocity.vx * deltaTime;
+     *   t.y += velocity.vy * deltaTime;
      * });
      *
      * // Conditional mutation

package/dist/types/ecs/system-builder.d.ts

@@ -120,10 +120,23 @@ export declare class ExecutableSystem {
     private queryMask;
     private conditionPredicate?;
     private proxyEntity;
+    /**
+     * Indices of queried components that have `__sync` metadata. Cached at
+     * construction so `execute()` can flip dirty bits without re-checking
+     * each tick. Empty for systems whose query touches no synced components,
+     * which keeps the hot path zero-overhead.
+     */
+    private syncedComponentIndices;
     constructor(world: World, components: Component<any>[], userCallback: (entity: any, deltaTime: number, world: World) => void, fieldDescs: FieldDesc[], queryMaskKey: string, queryMask: number[], conditionPredicate?: (entity: any) => boolean);
     /**
      * Execute the system for all matching entities.
      *
+     * If the system's query includes any synced components, every entity
+     * touched by the system is marked dirty for those components after the
+     * callback runs (coarse strategy. the network layer assumes any
+     * entity that flowed through a system whose query included its synced
+     * component may have changed).
+     *
      * @param deltaTime - Time delta to pass to system callback
      */
     execute(deltaTime: number): void;

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

@@ -1,3 +1,4 @@
+import type { ArrayFromField, Schema } from "../core/binary-codec";
 import { Component } from "./component";
 import { ComponentStore } from "./component-store";
 import { EntityHandle } from "./entity-handle";
@@ -70,6 +71,21 @@ export declare class World extends WorldSystems {
     private queryMaskCache;
     private despawnedBuffer;
     private despawnedCount;
+    /**
+     * Per-component dirty bitmask, indexed by [componentIndex][entity>>>5].
+     * `null` for components without `__sync` metadata: no overhead when
+     * networking isn't in play. Higher-level packages might read these
+     * to build per-peer snapshot deltas.
+     */
+    private dirtyBitsByComponent;
+    /**
+     * Per-component field bundle: a frozen object whose keys are the
+     * component's field names and whose values are the same typed-array
+     * references returned by `getFieldArray`. Built once at registration,
+     * shared forever — `world.fields(C)` returns the same object on every
+     * call (zero garbage). Indexed by `component.__worldIndex`.
+     */
+    private fieldsByComponent;
     private worldId;
     constructor(config: WorldConfig);
     /**
@@ -150,6 +166,34 @@ export declare class World extends WorldSystems {
      * Invalidate all query caches (called on archetype changes).
      */
     private invalidateQueryCache;
+    /**
+     * Mark an entity dirty for a given component index. No-op for
+     * components without `__sync` metadata. Called internally by every
+     * write path (`add`, `set`, `update`, `system-builder` field setters).
+     */
+    markDirty(entity: Entity, componentIndex: number): void;
+    /**
+     * Test whether an entity is currently marked dirty for a component.
+     * Used by snapshot builders.
+     */
+    isDirty(entity: Entity, component: Component<any>): boolean;
+    /**
+     * Clear the dirty bit for an entity/component pair. Called by the
+     * snapshot builder after a delta for the entity has been acknowledged
+     * by all peers.
+     */
+    clearDirty(entity: Entity, component: Component<any>): void;
+    /**
+     * Iterate dirty entities for a synced component. Calls `cb` for each
+     * entity whose dirty bit is set. Returns immediately for unsynced
+     * components.
+     */
+    forEachDirty(component: Component<any>, cb: (entity: Entity) => void): void;
+    /**
+     * Clear all dirty bits across all components. Usually the snapshot
+     * pipeline clears bits per-entity as it processes them.
+     */
+    clearAllDirty(): void;
     /**
      * Add a component to an entity with initial data.
      */
@@ -223,8 +267,8 @@ export declare class World extends WorldSystems {
      *   const t = world.get(entity, Transform);
      *   const v = world.get(entity, Velocity);
      *   world.update(entity, Transform, {
-     *     x: t.x + v.vx * dt,
-     *     y: t.y + v.vy * dt
+     *     x: t.x + v.vx * deltaTime,
+     *     y: t.y + v.vy * deltaTime
      *   });
      * }
      * ```
@@ -289,12 +333,36 @@ export declare class World extends WorldSystems {
      * const velocityVy = world.getFieldArray(Velocity, 'vy');
      *
      * for (const entity of world.query(Transform, Velocity)) {
-     *   transformX[entity] += velocityVx[entity] * dt;
-     *   transformY[entity] += velocityVy[entity] * dt;
+     *   transformX[entity] += velocityVx[entity] * deltaTime;
+     *   transformY[entity] += velocityVy[entity] * deltaTime;
      * }
      * ```
      */
     getFieldArray<T extends object>(component: Component<T>, fieldName: keyof T): Float32Array | Int32Array | Uint32Array | Uint16Array | Uint8Array;
+    /**
+     * Get a typed-array bundle for every field of a component.
+     *
+     * Returns the same frozen object on every call - built once at component
+     * registration and shared forever. Each field name maps to its underlying
+     * typed array, with the EXACT element type inferred from the schema:
+     * `f32 -> Float32Array`, `u8 -> Uint8Array`, `u16 -> Uint16Array`, etc.
+     * No casts needed in caller code.
+     *
+     * Use this when you want RAW-speed per-entity reads/writes without the
+     * `world.update({...})` allocation + `for...in` overhead. Bypasses dirty
+     * tracking: for networked components, see `ctx.fields()` in `murow/netcode`
+     * which auto-marks dirty, or call `world.markDirty(entity, index)` yourself.
+     *
+     * @example
+     * ```ts
+     * const pos = world.fields(Position);   // pos.x, pos.z typed as Float32Array
+     * pos.x[entity] += velocity.x * dt;
+     * pos.z[entity] += velocity.z * dt;
+     * ```
+     */
+    fields<T extends object, S extends Schema<T>>(component: Component<T, S>): Readonly<{
+        [K in keyof S]: ArrayFromField<S[K]>;
+    }>;
     /**
      * Create an EntityHandle wrapper for fluent API usage.
      *

package/dist/types/game/loop/loop.d.ts

@@ -29,6 +29,7 @@ export declare class GameLoop<T extends GameLoopType = DriverType> {
     private _tickData;
     private _skipData;
     private _renderData;
+    private _scheduler;
     constructor(options: GameLoopOptions<T>);
     step(deltaTime: number): void;
     /**
@@ -47,12 +48,41 @@ export declare class GameLoop<T extends GameLoopType = DriverType> {
      * Stops the game ticker and emits a 'stop' event.
      */
     stop(): void;
+    /**
+     * Registers a callback to run on a fixed tick interval.
+     *
+     * The unit methods resolve to a tick count from the loop's `tickRate`, so
+     * every schedule fires in lockstep with the simulation regardless of unit.
+     *
+     * @example
+     * const id = loop.every(2).seconds(spawnWave);
+     * loop.clearSchedule(id);
+     */
+    every(count: number): ScheduleBuilder;
+    /**
+     * Cancels a single schedule by the id returned from `every`.
+     */
+    clearSchedule(id: number): boolean;
+    /**
+     * Cancels every registered schedule.
+     */
+    clearSchedules(): void;
+}
+interface ScheduleBuilder {
+    ticks(cb: () => void): number;
+    seconds(cb: () => void): number;
+    milliseconds(cb: () => void): number;
 }
 interface GameLoopOptions<T extends GameLoopType> {
     tickRate: number;
     type: T;
-    onTick?: (dt: number, tick: number, input: ReturnType<InputManager["snapshot"]>) => void;
-    onRender?: (dt: number, alpha: number, input: ReturnType<InputManager["peek"]>) => void;
+    /**
+     * Maximum number of simultaneously live schedules registered via `every`.
+     * Defaults to 32.
+     */
+    maxSchedules?: number;
+    onTick?: (deltaTime: number, tick: number, input: ReturnType<InputManager["snapshot"]>) => void;
+    onRender?: (deltaTime: number, alpha: number, input: ReturnType<InputManager["peek"]>) => void;
 }
 type BaseEvents = [
     [
@@ -64,6 +94,25 @@ type BaseEvents = [
             startedAt: number;
         }
     ],
+    [
+        "sync",
+        {
+            /**
+             * Current tick number.
+             */
+            tick: number;
+            /**
+             * Delta time since the last tick.
+             */
+            deltaTime: number;
+            /**
+             * Input snapshot at the start of the tick.
+             *
+             * **Only available in client loops.**
+             */
+            input: ReturnType<InputManager["snapshot"]>;
+        }
+    ],
     [
         "pre-tick",
         {

package/dist/types/game/loop/ticker-schedule.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Fixed-capacity, zero-GC scheduler of tick-interval callbacks for the game loop.
+ *
+ * Schedules are stored in a pre-allocated object pool indexed by a {@link SlotMap}
+ * slot, so registering and cancelling reuse objects instead of producing garbage.
+ * Ids returned by {@link every} pack the slot with a generation counter, so an id
+ * left over from a cancelled schedule can never cancel the schedule that later
+ * reuses its slot.
+ */
+export declare class TickerSchedule {
+    private readonly _capacity;
+    private readonly _slots;
+    private readonly _generations;
+    private readonly _pool;
+    private _dirty;
+    private _running;
+    constructor(capacity: number);
+    /**
+     * Number of live schedules.
+     */
+    get size(): number;
+    /**
+     * Maximum number of simultaneously live schedules.
+     */
+    get capacity(): number;
+    /**
+     * Registers a callback to fire every `intervalTicks`, starting `intervalTicks`
+     * after `currentTick`. Returns a stable id for {@link clear}, or `-1` if the
+     * scheduler is at capacity.
+     */
+    every(intervalTicks: number, cb: () => void, currentTick: number): number;
+    /**
+     * Cancels the schedule for `id`. No-op (returns `false`) if the id is stale,
+     * unknown, or already cancelled.
+     */
+    clear(id: number): boolean;
+    /**
+     * Cancels every live schedule.
+     */
+    clearAll(): void;
+    /**
+     * Fires every schedule whose interval has elapsed at `currentTick`, then
+     * realigns it relative to `currentTick` (a long frame fires once, not a burst).
+     */
+    run(currentTick: number): void;
+    /**
+     * Re-anchors every live schedule's next fire relative to `baseTick`. Called
+     * when the loop restarts and the tick count resets.
+     */
+    rebase(baseTick: number): void;
+    private _compact;
+}

package/dist/types/net/adapters/bun-websocket.d.ts

@@ -63,7 +63,10 @@ export declare class BunWebSocketServerTransport implements ServerTransportAdapt
     getPeerIds(): string[];
     close(): void;
     /**
-     * Internal: Register a new peer (called from Bun server fetch handler)
+     * Internal: Register a new peer. Records the peer in the internal map
+     * but does NOT fire connection handlers: that's `_handlePeerConnection`'s
+     * job, called separately by the `open` callback. Splitting registration
+     * from notification keeps the handler count to exactly one per connect.
      */
     _registerPeer(socket: ServerWebSocket<unknown>): string;
     /**
@@ -76,7 +79,20 @@ export declare class BunWebSocketServerTransport implements ServerTransportAdapt
     _handlePeerDisconnection(peerId: string): void;
     _handlePeerConnection(peerId: string): void;
     /**
-     * Static factory method to create a Bun WebSocket server
+     * Static factory method to create a Bun WebSocket server.
+     *
+     * @param port - Port to listen on.
+     * @param opts - Optional configuration:
+     *   - `path`: If set, only requests to this URL pathname are upgraded
+     *     (e.g., `/ws`). Other paths fall through to `fetch`. Defaults to
+     *     accepting any path.
+     *   - `fetch`: Handler for non-upgrade HTTP requests on the same port.
+     *     Useful for serving a static bundle alongside the WS endpoint so
+     *     the whole app runs on one port. If omitted, non-upgrade requests
+     *     get a 400 response (matches the previous WS-only behavior).
      */
-    static create(port: number): BunWebSocketServerTransport;
+    static create(port: number, opts?: {
+        path?: string;
+        fetch?: (req: Request, server: Server<unknown>) => Response | Promise<Response>;
+    }): BunWebSocketServerTransport;
 }

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

@@ -13,3 +13,4 @@ export * from "./prefab-bucket";
 export * from "./prefab-bucket/specs";
 export { PrefabBucket } from "./prefab-bucket/concrete";
 export type { PrefabBucket2D, PrefabBucket3D } from "./prefab-bucket/concrete";
+export * from "./raycast";

package/dist/types/renderer/prefab-bucket/concrete.d.ts

@@ -16,7 +16,8 @@
  * bucket.get('typo');    // ❌ TS error: '"typo"' not in '"minion" | "floor"'
  * ```
  */
-import { BasePrefabBucket, type StringOr } from './index';
+import { BasePrefabBucket, type SpecWithHitbox, type StringOr } from './index';
+import type { HitboxLibrary } from '../../core/hitbox/hitbox-library';
 import type { CompositePrefab, PartOffset, Prefab2D, Prefab2DSpec, Prefab3D, Prefab3DSpec, PrefabFor } from './specs';
 type SpecForMode<M> = M extends '3d' ? Prefab3DSpec : Prefab2DSpec;
 type PrefabUnionForMode<M> = M extends '3d' ? Prefab3D : Prefab2D;
@@ -27,20 +28,29 @@ type PrefabUnionForMode<M> = M extends '3d' ? Prefab3D : Prefab2D;
  * to register new specs and their prefab types. Call `load` to parse all registered
  * specs and populate the bucket's internal prefab registry.
  */
-export declare class PrefabBucket<M extends '2d' | '3d' = '3d', Specs extends Record<string, SpecForMode<M>> = {}> extends BasePrefabBucket<M, SpecForMode<M>, PrefabUnionForMode<M>, Specs> {
+export declare class PrefabBucket<M extends '2d' | '3d' = '3d', Specs extends Record<string, SpecForMode<M>> = {}, HB extends string = never> extends BasePrefabBucket<M, SpecForMode<M>, PrefabUnionForMode<M>, Specs, HB> {
+    private _hitboxLibrary;
     constructor(mode: M);
+    /**
+     * Register the hitbox library backing this bucket. Specs may then set
+     * `hitbox` to any of the library's names, autocompleted and type-checked.
+     */
+    hitboxes<N extends string>(library: HitboxLibrary<M, N>): PrefabBucket<M, Specs, N>;
+    /** The registered hitbox library, or `null` if none was set. */
+    get hitboxLibrary(): HitboxLibrary<M> | null;
     /**
      * Add a spec. Chains return the subclass type so the bucket variable's
      * static type accumulates id→spec mappings, enabling `get` to narrow.
+     * When a hitbox library is registered, `hitbox` must be one of its names.
      */
-    add<const S extends SpecForMode<M>>(spec: S): PrefabBucket<M, Specs & {
+    add<const S extends SpecWithHitbox<SpecForMode<M>, HB>>(spec: S): PrefabBucket<M, Specs & {
         [K in S['id']]: S;
-    }>;
-    addAll<const Ss extends readonly SpecForMode<M>[]>(specs: Ss): PrefabBucket<M, Specs & {
+    }, HB>;
+    addAll<const Ss extends readonly SpecWithHitbox<SpecForMode<M>, HB>[]>(specs: Ss): PrefabBucket<M, Specs & {
         [K in Ss[number]['id']]: Extract<Ss[number], {
             id: K;
         }>;
-    }>;
+    }, HB>;
     /**
      * Return the parsed prefab variant for this id. Narrow type — `get('minion')`
      * returns `GltfPrefab` (with `.animations`, `.jointCount`), not the union.

package/dist/types/renderer/prefab-bucket/index.d.ts

@@ -22,6 +22,10 @@ export type PrefabMode = '2d' | '3d';
  * suggestions for the known set.
  */
 export type StringOr<T extends string> = T | (string & {});
+/** A spec union with its `hitbox` field constrained to the hitbox names `HB`. */
+export type SpecWithHitbox<S, HB extends string> = S extends unknown ? Omit<S, 'hitbox'> & {
+    readonly hitbox?: StringOr<HB>;
+} : never;
 export interface PrefabSpecBase {
     readonly type: string;
     readonly id: string;
@@ -56,7 +60,7 @@ export interface PrefabParserContext {
  */
 export type PrefabParser<Spec extends PrefabSpecBase = PrefabSpecBase, Prefab extends PrefabBase = PrefabBase> = (spec: Spec, ctx: PrefabParserContext) => Promise<Prefab> | Prefab;
 export type PrefabParserMap<Spec extends PrefabSpecBase, Prefab extends PrefabBase> = Record<string, PrefabParser<Spec, Prefab>>;
-export declare class BasePrefabBucket<M extends PrefabMode = PrefabMode, Spec extends PrefabSpecBase = PrefabSpecBase, Prefab extends PrefabBase = PrefabBase, Specs extends Record<string, Spec> = {}> {
+export declare class BasePrefabBucket<M extends PrefabMode = PrefabMode, Spec extends PrefabSpecBase = PrefabSpecBase, Prefab extends PrefabBase = PrefabBase, Specs extends Record<string, Spec> = {}, HB extends string = string> {
     readonly mode: M;
     /** Shared notification channel - see `PrefabBucketEvents`. */
     readonly events: EventSystem<PrefabBucketEvents>;
@@ -68,26 +72,26 @@ export declare class BasePrefabBucket<M extends PrefabMode = PrefabMode, Spec ex
     protected groups: Map<string, string[]>;
     constructor(mode: M, parsers?: PrefabParserMap<Spec, Prefab>);
     /** Add a single spec. Throws if id is a duplicate, contains '.', or if the bucket is already loaded. */
-    add<const S extends Spec>(spec: S): BasePrefabBucket<M, Spec, Prefab, Specs & {
+    add<const S extends SpecWithHitbox<Spec, HB>>(spec: S): BasePrefabBucket<M, Spec, Prefab, Specs & {
         [K in S['id']]: S;
-    }>;
+    }, HB>;
     /**
      * Internal add that skips the '.' validation. Used by `addGroup` on
      * subclasses to register parts under group-path ids (e.g. `'campfire.logs'`)
      * after the group itself has validated user input.
      */
-    protected addUnchecked<const S extends Spec>(spec: S): BasePrefabBucket<M, Spec, Prefab, Specs & {
+    protected addUnchecked<const S extends SpecWithHitbox<Spec, HB>>(spec: S): BasePrefabBucket<M, Spec, Prefab, Specs & {
         [K in S['id']]: S;
-    }>;
+    }, HB>;
     /**
      * Add multiple specs. Validates the whole batch (ids unique, not loaded) before
      * committing, so the bucket never lands in a half-applied state.
      */
-    addAll<const Ss extends readonly Spec[]>(specs: Ss): BasePrefabBucket<M, Spec, Prefab, Specs & {
+    addAll<const Ss extends readonly SpecWithHitbox<Spec, HB>[]>(specs: Ss): BasePrefabBucket<M, Spec, Prefab, Specs & {
         [K in Ss[number]['id']]: Extract<Ss[number], {
             id: K;
         }>;
-    }>;
+    }, HB>;
     /** Load all pending specs in parallel. Idempotent if already loaded. */
     load(): Promise<void>;
     /**

package/dist/types/renderer/prefab-bucket/specs.d.ts

@@ -42,6 +42,7 @@ export interface GltfSpec {
     readonly freezeAnimations?: boolean;
     /** Optional user-defined sidecar data (scale, speed, gameplay hints, etc). */
     readonly metadata?: Record<string, unknown>;
+    readonly hitbox?: string;
 }
 export interface GridSpec {
     readonly type: 'grid';
@@ -52,6 +53,7 @@ export interface GridSpec {
     readonly lineWidth: number;
     /** Optional user-defined sidecar data (scale, speed, gameplay hints, etc). */
     readonly metadata?: Record<string, unknown>;
+    readonly hitbox?: string;
 }
 /** Unit cube prefab centered at origin. Use the instance's `scale` to size it. */
 export interface CubeSpec {
@@ -60,6 +62,7 @@ export interface CubeSpec {
     /** Edge length. Defaults to 1. */
     readonly size?: number;
     readonly metadata?: Record<string, unknown>;
+    readonly hitbox?: string;
 }
 /** Local transform offset applied to a part inside a composite/group at spawn time. */
 export interface PartOffset {
@@ -80,6 +83,7 @@ export interface CompositeSpec {
         readonly offset?: PartOffset;
     }[];
     readonly metadata?: Record<string, unknown>;
+    readonly hitbox?: string;
 }
 export type Prefab3DSpec = GltfSpec | GridSpec | CubeSpec | CompositeSpec;
 /**
@@ -126,6 +130,7 @@ type GltfPrefabBase<S extends GltfSpec> = {
     readonly totalVertexCount: number;
     /** Passed through from the spec. */
     readonly metadata: MetadataOf<S>;
+    readonly hitbox?: string;
 };
 /**
  * Animation record/list fields, narrowed by what the spec declared:
@@ -161,12 +166,14 @@ export interface GridPrefab<S extends GridSpec = GridSpec> {
     readonly step: number;
     readonly lineWidth: number;
     readonly metadata: MetadataOf<S>;
+    readonly hitbox?: string;
 }
 export interface CubePrefab<S extends CubeSpec = CubeSpec> {
     readonly type: 'cube';
     readonly id: S['id'];
     readonly size: number;
     readonly metadata: MetadataOf<S>;
+    readonly hitbox?: string;
 }
 export interface CompositePrefab<S extends CompositeSpec = CompositeSpec> {
     readonly type: 'composite';
@@ -176,6 +183,7 @@ export interface CompositePrefab<S extends CompositeSpec = CompositeSpec> {
         readonly offset?: PartOffset;
     }[];
     readonly metadata: MetadataOf<S>;
+    readonly hitbox?: string;
 }
 export type Prefab3D = GltfPrefab | GridPrefab | CubePrefab | CompositePrefab;
 export interface SpritesheetSpec {
@@ -188,6 +196,7 @@ export interface SpritesheetSpec {
     /** URL to a texture-packer JSON file. Mutually exclusive with frameWidth/frameHeight. */
     readonly data?: string;
     readonly metadata?: Record<string, unknown>;
+    readonly hitbox?: string;
 }
 export type Prefab2DSpec = SpritesheetSpec;
 export interface SpritesheetPrefab<S extends SpritesheetSpec = SpritesheetSpec> {
@@ -198,6 +207,7 @@ export interface SpritesheetPrefab<S extends SpritesheetSpec = SpritesheetSpec>
     readonly width: number;
     readonly height: number;
     readonly metadata: MetadataOf<S>;
+    readonly hitbox?: string;
 }
 export type Prefab2D = SpritesheetPrefab;
 /**

package/dist/types/renderer/raycast/index.d.ts

@@ -0,0 +1 @@
+export * from './raycast';