murow 0.0.72 → 0.1.1

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

@@ -51,8 +51,8 @@ export declare class GameLoop<T extends GameLoopType = DriverType> {
 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;
+    onTick?: (deltaTime: number, tick: number, input: ReturnType<InputManager["snapshot"]>) => void;
+    onRender?: (deltaTime: number, alpha: number, input: ReturnType<InputManager["peek"]>) => void;
 }
 type BaseEvents = [
     [
@@ -64,6 +64,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/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/base/renderer-3d.d.ts

@@ -4,7 +4,7 @@
 import { BaseRenderer } from "./renderer";
 import type { Camera3DState, Renderer3DOptions } from "../types";
 export declare abstract class Base3DRenderer extends BaseRenderer<Renderer3DOptions> {
-    readonly maxModels: number;
+    readonly maxInstances: number;
     abstract readonly camera: Camera3DState;
     constructor(canvas: HTMLCanvasElement, options: Renderer3DOptions);
 }

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

@@ -17,7 +17,7 @@
  * ```
  */
 import { BasePrefabBucket, type StringOr } from './index';
-import type { Prefab2D, Prefab2DSpec, Prefab3D, Prefab3DSpec, PrefabFor } from './specs';
+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;
 /**
@@ -48,8 +48,48 @@ export declare class PrefabBucket<M extends '2d' | '3d' = '3d', Specs extends Re
      * Accepts any string at runtime but autocompletes known ids.
      */
     get<K extends keyof Specs & string, R = PrefabFor<Specs[K]>>(id: StringOr<K>): R;
+    /**
+     * Register a named group of part specs. Each part is added as a top-level
+     * prefab with id `<groupName>.<partId>` (or `<groupName>.<auto-hex>` when
+     * the part omitted `id`). A `composite` prefab is also created at id
+     * `groupName`, with the parts wired up via their `offset` for spawning.
+     *
+     * ```ts
+     * bucket.addGroup('campfire', [
+     *   { type: 'gltf', id: 'logs', src: '/logs.glb' },
+     *   { type: 'cube', id: 'flame', size: 0.3, offset: { position: [0, 0.3, 0] } },
+     *   { type: 'cube', size: 0.5, offset: { position: [0, 0.8, 0] } },  // auto id
+     * ]);
+     *
+     * await bucket.load();
+     *
+     * bucket.get('campfire');             // composite (spawnable as one)
+     * bucket.get('campfire.logs');        // the part directly
+     * bucket.getGroup('campfire').prefabs; // both parts
+     * ```
+     */
+    addGroup(name: string, parts: readonly GroupPartInput<M>[]): this;
+    /**
+     * Look up a group registered via `addGroup`. Returns the parts in order
+     * and an `asComposite()` helper that returns the composite prefab created
+     * for the group (equivalent to `bucket.get(groupName)`).
+     */
+    getGroup(name: string): {
+        prefabs: Prefab3D[];
+        asComposite(): CompositePrefab;
+    };
 }
+/**
+ * Part spec accepted by `addGroup`: a regular 3D spec with `id` optional
+ * (auto-generated when absent) and a new `offset` field.
+ */
+type GroupPartInput<M extends '2d' | '3d'> = M extends '3d' ? {
+    [K in Prefab3DSpec as K['type']]: Omit<K, 'id'> & {
+        id?: string;
+        offset?: PartOffset;
+    };
+}[Prefab3DSpec['type']] : never;
 /** Convenience aliases for explicit mode typing (e.g. function params). */
 export type PrefabBucket2D<Specs extends Record<string, Prefab2DSpec> = {}> = PrefabBucket<'2d', Specs>;
 export type PrefabBucket3D<Specs extends Record<string, Prefab3DSpec> = {}> = PrefabBucket<'3d', Specs>;
-export type { GltfPrefab, GltfSpec, GridPrefab, GridSpec, Prefab2D, Prefab2DSpec, Prefab3D, Prefab3DSpec, PrefabFor, SpritesheetPrefab, SpritesheetSpec, } from './specs';
+export type { CompositePrefab, CompositeSpec, CubePrefab, CubeSpec, GltfPrefab, GltfSpec, GridPrefab, GridSpec, PartOffset, Prefab2D, Prefab2DSpec, Prefab3D, Prefab3DSpec, PrefabFor, SpritesheetPrefab, SpritesheetSpec, } from './specs';

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

@@ -58,17 +58,27 @@ export type PrefabParser<Spec extends PrefabSpecBase = PrefabSpecBase, Prefab ex
 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> = {}> {
     readonly mode: M;
-    /** Shared notification channel — see `PrefabBucketEvents`. */
+    /** Shared notification channel - see `PrefabBucketEvents`. */
     readonly events: EventSystem<PrefabBucketEvents>;
     private parsers;
     private pending;
     private pendingIds;
     private prefabs;
+    /** `groupName -> ordered list of final part ids`. Populated by `addGroup` on subclasses. */
+    protected groups: Map<string, string[]>;
     constructor(mode: M, parsers?: PrefabParserMap<Spec, Prefab>);
-    /** Add a single spec. Throws if id is a duplicate or if the bucket is already loaded. */
+    /** 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 & {
         [K in S['id']]: S;
     }>;
+    /**
+     * 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 & {
+        [K in S['id']]: S;
+    }>;
     /**
      * Add multiple specs. Validates the whole batch (ids unique, not loaded) before
      * committing, so the bucket never lands in a half-applied state.

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

@@ -53,7 +53,35 @@ export interface GridSpec {
     /** Optional user-defined sidecar data (scale, speed, gameplay hints, etc). */
     readonly metadata?: Record<string, unknown>;
 }
-export type Prefab3DSpec = GltfSpec | GridSpec;
+/** Unit cube prefab centered at origin. Use the instance's `scale` to size it. */
+export interface CubeSpec {
+    readonly type: 'cube';
+    readonly id: string;
+    /** Edge length. Defaults to 1. */
+    readonly size?: number;
+    readonly metadata?: Record<string, unknown>;
+}
+/** Local transform offset applied to a part inside a composite/group at spawn time. */
+export interface PartOffset {
+    readonly position?: readonly [number, number, number];
+    readonly rotation?: readonly [number, number, number];
+}
+/**
+ * A prefab that spawns several other prefabs at fixed local offsets. Created
+ * by `bucket.addGroup(...)`; not typically written by hand. Spawning a
+ * composite instance spawns one child per part, with each part's offset
+ * composed onto the instance's position/rotation.
+ */
+export interface CompositeSpec {
+    readonly type: 'composite';
+    readonly id: string;
+    readonly parts: readonly {
+        readonly partId: string;
+        readonly offset?: PartOffset;
+    }[];
+    readonly metadata?: Record<string, unknown>;
+}
+export type Prefab3DSpec = GltfSpec | GridSpec | CubeSpec | CompositeSpec;
 /**
  * Map a spec's `animations` tuple to a record-keyed-by-name. Used to type
  * `GltfPrefab.animations` so `prefab.animations.Run` is a string literal
@@ -134,7 +162,22 @@ export interface GridPrefab<S extends GridSpec = GridSpec> {
     readonly lineWidth: number;
     readonly metadata: MetadataOf<S>;
 }
-export type Prefab3D = GltfPrefab | GridPrefab;
+export interface CubePrefab<S extends CubeSpec = CubeSpec> {
+    readonly type: 'cube';
+    readonly id: S['id'];
+    readonly size: number;
+    readonly metadata: MetadataOf<S>;
+}
+export interface CompositePrefab<S extends CompositeSpec = CompositeSpec> {
+    readonly type: 'composite';
+    readonly id: S['id'];
+    readonly parts: readonly {
+        readonly partId: string;
+        readonly offset?: PartOffset;
+    }[];
+    readonly metadata: MetadataOf<S>;
+}
+export type Prefab3D = GltfPrefab | GridPrefab | CubePrefab | CompositePrefab;
 export interface SpritesheetSpec {
     readonly type: 'spritesheet';
     readonly id: string;
@@ -162,5 +205,5 @@ export type Prefab2D = SpritesheetPrefab;
  * bucket's `get()` so `bucket.get('minion')` returns `GltfPrefab` directly,
  * not the discriminated union.
  */
-export type PrefabFor<S> = S extends GltfSpec ? GltfPrefab<S> : S extends GridSpec ? GridPrefab<S> : S extends SpritesheetSpec ? SpritesheetPrefab<S> : never;
+export type PrefabFor<S> = S extends GltfSpec ? GltfPrefab<S> : S extends GridSpec ? GridPrefab<S> : S extends CubeSpec ? CubePrefab<S> : S extends CompositeSpec ? CompositePrefab<S> : S extends SpritesheetSpec ? SpritesheetPrefab<S> : never;
 export {};

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

@@ -14,10 +14,12 @@ export interface Renderer2DOptions extends RendererOptions {
 }
 export interface Renderer3DOptions extends RendererOptions {
     /**
-     * Non-skinned instance budget. Optional when a prefab bucket is provided —
-     * the renderer will derive a sensible default from the bucket.
+     * How many instances you intend to spawn at once. Sizes both the
+     * non-skinned instance pool directly and seeds the default for the
+     * skinned-instance budget. Optional when a prefab bucket is provided -
+     * the renderer derives a sensible default from the bucket.
      */
-    maxModels?: number;
+    maxInstances?: number;
     enableLighting?: boolean;
 }
 export interface Camera2DState {