@crowdedkingdoms/crowdyjs 8.3.0 → 8.4.0

package/dist/stores/chunks.js

@@ -0,0 +1,378 @@
+/**
+ * ChunkStore — the SDK-managed chunk/voxel cache: bulk loading, typed
+ * per-voxel and per-chunk state, realtime merge of voxel notifications,
+ * optimistic local edits, and the deterministic-worldgen write-back pattern.
+ * Replaces the WorldStreamer + WorldState + codec plumbing every voxel game
+ * hand-writes (~860 LOC in Blocks with Friends).
+ */
+import { generateCrowdyUuid, decodeBase64, encodeBase64 } from '../utils.js';
+import { rawCodec } from './codec.js';
+import { CHUNK_VOLUME, chunkDistance, chunkKey, chunksAround, fromChunkInput, toChunkInput, voxelIndex, } from './keys.js';
+/**
+ * The SDK-managed **chunk/voxel cache** — the client-side source of truth
+ * for terrain:
+ *
+ * - `ensureAround(center, radius)` bulk-loads via `chunks.byDistance`
+ *   (in-flight deduped), hydrates sparse voxel states, marks chunks the
+ *   server never stored as `missing`, and hands them to your `onMissing`
+ *   worldgen hook.
+ * - Realtime `voxelUpdate` notifications merge into the cache automatically
+ *   (dense grid write + typed state decode + revision bump + change event).
+ * - `setVoxel` applies locally (optimistic) and replicates via the UDP path.
+ * - `seed`/`flush` implement deterministic-worldgen write-back through
+ *   `chunks.update`, one throttled chunk at a time.
+ *
+ * All reads are synchronous; writes land on WebSocket events, so render
+ * loops and background tabs behave (see the module docs).
+ */
+export class ChunkStore {
+    constructor(ctx, config = {}) {
+        this.ctx = ctx;
+        this.config = config;
+        this.chunks = new Map();
+        this.inFlight = new Set();
+        this.writeBackQueue = [];
+        this.changeListeners = new Set();
+        this.fallbackUuid = generateCrowdyUuid();
+        this.revisionValue = 0;
+        this.sequence = 0;
+        this.voxelStateCodec =
+            config.voxelStateCodec ?? rawCodec;
+        this.chunkStateCodec =
+            config.chunkStateCodec ?? rawCodec;
+        this.hydrateStates = config.hydrateVoxelStates ?? config.voxelStateCodec !== undefined;
+        this.now = config.now ?? Date.now;
+        // Realtime merge: live edits land in the cache as they replicate.
+        ctx.onDispose(ctx.on('voxelUpdate', (notification) => {
+            const coord = {
+                x: Number(notification.chunkX),
+                y: Number(notification.chunkY),
+                z: Number(notification.chunkZ),
+            };
+            const chunk = this.chunks.get(chunkKey(coord));
+            if (!chunk)
+                return; // only merge into chunks we track
+            this.applyVoxel(chunk, notification.voxelX, notification.voxelY, notification.voxelZ, notification.voxelType, notification.voxelState || undefined);
+        }));
+        const writeBackInterval = config.writeBackIntervalMs ?? 700;
+        if (writeBackInterval !== false && writeBackInterval > 0) {
+            ctx.onDispose(ctx.ticker.every(writeBackInterval, () => {
+                void this.persistNext();
+            }));
+        }
+    }
+    /** Bumped on every cache change — poll it cheaply from a render loop. */
+    get revision() {
+        return this.revisionValue;
+    }
+    /** The cached chunk at a coordinate (any load state), if tracked. */
+    get(coord) {
+        return this.chunks.get(chunkKey(coord));
+    }
+    /** Every tracked chunk (any load state). */
+    list() {
+        return [...this.chunks.values()];
+    }
+    /** The dense voxel type at a within-chunk coordinate (0 when unknown). */
+    voxelTypeAt(coord, x, y, z) {
+        const chunk = this.chunks.get(chunkKey(coord));
+        return chunk?.voxels?.[voxelIndex(x, y, z)] ?? 0;
+    }
+    /** The typed per-voxel state at a within-chunk coordinate, if any. */
+    voxelStateAt(coord, x, y, z) {
+        return this.chunks.get(chunkKey(coord))?.voxelStates.get(voxelIndex(x, y, z));
+    }
+    /** Subscribe to per-chunk changes (loads, merges, edits). @returns off. */
+    onChunkChanged(listener) {
+        this.changeListeners.add(listener);
+        return () => this.changeListeners.delete(listener);
+    }
+    /**
+     * Ensure every chunk within `radius` (Chebyshev, 1-8) of `center` is
+     * tracked: bulk-loads untracked ones, hydrates sparse voxel states when
+     * configured, marks server-unknown chunks `missing`, and seeds them via
+     * `onMissing`. In-flight requests are deduped; safe to call every time the
+     * player crosses a chunk boundary.
+     */
+    async ensureAround(center, radius) {
+        const wanted = chunksAround(center, radius).filter((coord) => {
+            const key = chunkKey(coord);
+            return !this.chunks.has(key) && !this.inFlight.has(key);
+        });
+        if (wanted.length === 0)
+            return;
+        for (const coord of wanted)
+            this.inFlight.add(chunkKey(coord));
+        try {
+            const response = await this.ctx.client.chunks.byDistance({
+                appId: this.ctx.appId,
+                centerCoordinate: toChunkInput(center),
+                maxDistance: Math.max(1, Math.min(8, radius)),
+                limit: (2 * radius + 1) ** 3,
+            });
+            const returned = new Set();
+            for (const chunk of response.chunks) {
+                const coord = fromChunkInput(chunk.coordinates);
+                returned.add(chunkKey(coord));
+                this.applyServerChunk(coord, chunk.voxels ?? null, chunk.chunkState ?? null);
+            }
+            // Requested-but-absent chunks have never been stored server-side.
+            for (const coord of wanted) {
+                if (returned.has(chunkKey(coord)))
+                    continue;
+                this.markMissing(coord);
+            }
+            if (this.hydrateStates) {
+                await Promise.all(wanted
+                    .filter((coord) => returned.has(chunkKey(coord)))
+                    .map((coord) => this.hydrate(coord)));
+            }
+        }
+        catch (error) {
+            for (const coord of wanted) {
+                const key = chunkKey(coord);
+                if (!this.chunks.has(key)) {
+                    const chunk = this.ensureEntry(coord);
+                    chunk.loadState = 'failed';
+                    this.touch(chunk);
+                }
+            }
+            throw error;
+        }
+        finally {
+            for (const coord of wanted)
+                this.inFlight.delete(chunkKey(coord));
+        }
+    }
+    /**
+     * Hydrate one chunk's sparse voxel states (and chunk state) via a
+     * single-chunk fetch — bulk loads omit them.
+     */
+    async hydrate(coord) {
+        const full = await this.ctx.client.chunks.get({
+            appId: this.ctx.appId,
+            coordinates: toChunkInput(coord),
+        });
+        if (!full) {
+            this.markMissing(coord);
+            return;
+        }
+        const chunk = this.ensureEntry(coord);
+        if (full.voxels != null)
+            chunk.voxels = decodeBase64(full.voxels);
+        chunk.chunkState = this.decodeChunkState(full.chunkState ?? null);
+        for (const entry of full.voxelStates ?? []) {
+            const index = voxelIndex(entry.voxelCoord.x, entry.voxelCoord.y, entry.voxelCoord.z);
+            if (chunk.voxels)
+                chunk.voxels[index] = entry.voxelType;
+            if (entry.state) {
+                try {
+                    chunk.voxelStates.set(index, this.voxelStateCodec.decode(entry.state));
+                }
+                catch {
+                    // Foreign/legacy blobs skip silently; the dense type still applied.
+                }
+            }
+        }
+        chunk.loadState = 'loaded';
+        chunk.hydrated = true;
+        this.touch(chunk);
+    }
+    /**
+     * Edit one voxel: applies to the cache immediately (optimistic) and
+     * replicates via the realtime voxel path. Resolves with the send
+     * acceptance.
+     */
+    async setVoxel(input) {
+        const chunk = this.ensureEntry(input.chunk);
+        if (input.optimistic ?? true) {
+            this.applyVoxel(chunk, input.x, input.y, input.z, input.voxelType, undefined, input.state);
+        }
+        const sequenceNumber = this.nextSequence();
+        this.ctx.trackSend({
+            kind: 'voxelUpdate',
+            sequenceNumber,
+            sentAt: this.now(),
+            uuid: this.senderUuid(),
+            detail: { chunk: input.chunk, x: input.x, y: input.y, z: input.z },
+        });
+        return this.ctx.client.udp.sendVoxelUpdate({
+            appId: this.ctx.appId,
+            chunk: toChunkInput(input.chunk),
+            uuid: this.senderUuid(),
+            voxel: { x: input.x, y: input.y, z: input.z },
+            voxelType: input.voxelType,
+            voxelState: input.state !== undefined ? this.voxelStateCodec.encode(input.state) : '',
+            sequenceNumber,
+            ...(this.config.distance !== undefined ? { distance: this.config.distance } : {}),
+            ...(this.config.decayRate !== undefined
+                ? { decayRate: this.config.decayRate }
+                : {}),
+        });
+    }
+    /**
+     * Seed a locally generated chunk (deterministic worldgen) and queue it for
+     * write-back so the server copy exists for everyone.
+     */
+    seed(coord, voxels, options = {}) {
+        if (voxels.length !== CHUNK_VOLUME) {
+            throw new Error(`seed() needs a ${CHUNK_VOLUME}-byte dense grid, got ${voxels.length}`);
+        }
+        const chunk = this.ensureEntry(coord);
+        chunk.voxels = voxels;
+        chunk.loadState = 'seeded';
+        if (options.writeBack ?? true)
+            this.markDirty(coord);
+        this.touch(chunk);
+    }
+    /** Queue a tracked chunk's dense grid for (throttled) write-back. */
+    markDirty(coord) {
+        const key = chunkKey(coord);
+        const chunk = this.chunks.get(key);
+        if (!chunk)
+            return;
+        chunk.dirty = true;
+        if (!this.writeBackQueue.includes(key))
+            this.writeBackQueue.push(key);
+    }
+    /** Chunks currently queued for write-back. */
+    get pendingWriteBacks() {
+        return this.writeBackQueue.length;
+    }
+    /** Persist every queued chunk now (awaits all writes). */
+    async flush() {
+        while (this.writeBackQueue.length > 0) {
+            await this.persistNext();
+        }
+    }
+    /** Drop tracked chunks farther than `radius` from `center` (dirty ones kept). */
+    pruneBeyond(center, radius) {
+        for (const [key, chunk] of this.chunks) {
+            if (chunk.dirty)
+                continue;
+            if (chunkDistance(chunk.coord, center) > radius) {
+                this.chunks.delete(key);
+                this.revisionValue += 1;
+            }
+        }
+    }
+    // -- internals --------------------------------------------------------------
+    async persistNext() {
+        const key = this.writeBackQueue.shift();
+        if (!key)
+            return;
+        const chunk = this.chunks.get(key);
+        if (!chunk || !chunk.voxels)
+            return;
+        try {
+            await this.ctx.client.chunks.update({
+                appId: this.ctx.appId,
+                coordinates: toChunkInput(chunk.coord),
+                voxels: encodeBase64(chunk.voxels),
+            });
+            chunk.dirty = false;
+            if (chunk.loadState === 'seeded')
+                chunk.loadState = 'loaded';
+            this.touch(chunk);
+        }
+        catch {
+            // Requeue at the back; the next tick retries.
+            chunk.dirty = true;
+            this.writeBackQueue.push(key);
+        }
+    }
+    applyServerChunk(coord, voxels, chunkState) {
+        const chunk = this.ensureEntry(coord);
+        if (voxels != null)
+            chunk.voxels = decodeBase64(voxels);
+        chunk.chunkState = this.decodeChunkState(chunkState);
+        chunk.loadState = 'loaded';
+        this.touch(chunk);
+    }
+    markMissing(coord) {
+        const chunk = this.ensureEntry(coord);
+        if (chunk.loadState === 'loaded' || chunk.loadState === 'seeded')
+            return;
+        chunk.loadState = 'missing';
+        this.touch(chunk);
+        const generated = this.config.onMissing?.(coord);
+        if (generated)
+            this.seed(coord, generated);
+    }
+    applyVoxel(chunk, x, y, z, voxelType, encodedState, decodedState) {
+        if (!chunk.voxels)
+            chunk.voxels = new Uint8Array(CHUNK_VOLUME);
+        const index = voxelIndex(x, y, z);
+        chunk.voxels[index] = voxelType;
+        let state = decodedState;
+        if (state === undefined && encodedState) {
+            try {
+                state = this.voxelStateCodec.decode(encodedState);
+            }
+            catch {
+                state = undefined;
+            }
+        }
+        if (state !== undefined) {
+            chunk.voxelStates.set(index, state);
+        }
+        else {
+            chunk.voxelStates.delete(index);
+        }
+        this.touch(chunk);
+    }
+    ensureEntry(coord) {
+        const key = chunkKey(coord);
+        let chunk = this.chunks.get(key);
+        if (!chunk) {
+            chunk = {
+                key,
+                coord,
+                voxels: null,
+                voxelStates: new Map(),
+                chunkState: null,
+                loadState: 'loading',
+                revision: 0,
+                updatedAt: this.now(),
+                hydrated: false,
+                dirty: false,
+            };
+            this.chunks.set(key, chunk);
+        }
+        return chunk;
+    }
+    decodeChunkState(encoded) {
+        if (encoded == null || encoded === '')
+            return null;
+        try {
+            return this.chunkStateCodec.decode(encoded);
+        }
+        catch {
+            return null;
+        }
+    }
+    touch(chunk) {
+        chunk.revision += 1;
+        chunk.updatedAt = this.now();
+        this.revisionValue += 1;
+        for (const listener of [...this.changeListeners])
+            listener(chunk);
+    }
+    senderUuid() {
+        const configured = typeof this.config.actorUuid === 'function'
+            ? this.config.actorUuid()
+            : this.config.actorUuid;
+        return configured ?? this.fallbackUuid;
+    }
+    nextSequence() {
+        this.sequence = (this.sequence + 1) % 256;
+        return this.sequence;
+    }
+}
+/**
+ * Attach a {@link ChunkStore} to a world session context. Prefer the
+ * `chunks` key of `createWorldSession`'s config.
+ */
+export function attachChunkStore(ctx, config = {}) {
+    return new ChunkStore(ctx, config);
+}

package/dist/stores/codec.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Typed state codecs — the foundation of the World Stores layer.
+ *
+ * Every opaque base64 blob on the platform (actor replication `state`, voxel
+ * `voxelState`, chunk `chunkState`, client event `state`, channel/actor
+ * message `payload`, `UserAppState.state`, avatar public/private/app state)
+ * is app-defined. A {@link StateCodec} names that definition ONCE: the dev
+ * registers their custom type + encoder/decoder with a store, and the store
+ * speaks typed values everywhere else.
+ */
+/**
+ * A two-way codec between a typed value and the platform's base64 wire form.
+ * Implement your own, or build one with {@link jsonCodec} (compact JSON),
+ * {@link rawCodec} (pass-through base64), or {@link structCodec} (fixed-layout
+ * binary — the right choice for high-rate replication state).
+ */
+export interface StateCodec<T> {
+    /** Encode a typed value into the base64 wire form. */
+    encode(value: T): string;
+    /** Decode the base64 wire form back into the typed value. */
+    decode(data: string): T;
+}
+/**
+ * JSON codec: `JSON.stringify` → UTF-8 → base64. Convenient for low-rate,
+ * structured state (save blobs, avatar profiles, channel payloads). Do NOT
+ * use it for per-tick actor replication — spatial packets have a ~1.1 KB
+ * budget and JSON wastes most of it; use {@link structCodec} there.
+ */
+export declare function jsonCodec<T>(): StateCodec<T>;
+/**
+ * Identity codec: the typed value IS the base64 string. Use it when the app
+ * already has its own encoding pipeline and just wants the stores' lifecycle
+ * management.
+ */
+export declare const rawCodec: StateCodec<string>;
+/**
+ * UTF-8 text codec: plain strings ↔ base64 (chat payloads, simple messages).
+ */
+export declare const textCodec: StateCodec<string>;
+/**
+ * One field of a {@link structCodec} layout. Build fields with the factory
+ * helpers ({@link f32}, {@link u8}, …) rather than by hand.
+ */
+export interface StructField<V> {
+    /** Bytes this field occupies. */
+    size: number;
+    read(view: DataView, offset: number, littleEndian: boolean): V;
+    write(view: DataView, offset: number, value: V, littleEndian: boolean): void;
+    /** True for {@link reserved} padding — excluded from the value type. */
+    skip?: boolean;
+}
+/** A struct layout: ordered named fields (insertion order = byte order). */
+export type StructSpec = Record<string, StructField<unknown>>;
+/** The typed value a {@link StructSpec} encodes (reserved fields omitted). */
+export type StructValue<S extends StructSpec> = {
+    [K in keyof S as S[K]['skip'] extends true ? never : K]: S[K] extends StructField<infer V> ? V : never;
+};
+/** 32-bit float field. */
+export declare function f32(): StructField<number>;
+/** 64-bit float field (e.g. epoch-milliseconds timestamps). */
+export declare function f64(): StructField<number>;
+/** Unsigned 8-bit int field (flags, small ids). */
+export declare function u8(): StructField<number>;
+/** Unsigned 16-bit int field. */
+export declare function u16(): StructField<number>;
+/** Unsigned 32-bit int field. */
+export declare function u32(): StructField<number>;
+/** Signed 8-bit int field. */
+export declare function i8(): StructField<number>;
+/** Signed 16-bit int field. */
+export declare function i16(): StructField<number>;
+/** Signed 32-bit int field. */
+export declare function i32(): StructField<number>;
+/** Boolean stored as one byte (0/1). */
+export declare function bool8(): StructField<boolean>;
+/** Fixed-length raw bytes field. */
+export declare function bytes(length: number): StructField<Uint8Array>;
+/** Reserved padding bytes — occupies layout space, absent from the value type. */
+export declare function reserved(length: number): StructField<undefined> & {
+    skip: true;
+};
+/** A {@link StateCodec} produced by {@link structCodec}, exposing its byte size. */
+export interface StructCodec<T> extends StateCodec<T> {
+    /** The fixed encoded size in bytes (before base64). */
+    readonly byteLength: number;
+}
+/**
+ * Build a fixed-layout binary codec from a declarative field spec — the
+ * replication-state workhorse. Fields are laid out in declaration order,
+ * little-endian by default (matching the platform's wire conventions).
+ *
+ * The Blocks-with-Friends 48-byte pose, declaratively:
+ *
+ * ```ts
+ * const poseCodec = structCodec({
+ *   x: f32(), y: f32(), z: f32(),
+ *   yaw: f32(), pitch: f32(),
+ *   vx: f32(), vy: f32(), vz: f32(),
+ *   flags: u8(), heldBlockId: u8(), _r0: reserved(2),
+ *   updatedAt: f64(), _r1: reserved(4),
+ * }); // poseCodec.byteLength === 48
+ * ```
+ *
+ * @throws {Error} at decode time when the payload is shorter than the layout.
+ */
+export declare function structCodec<S extends StructSpec>(spec: S, options?: {
+    littleEndian?: boolean;
+}): StructCodec<StructValue<S>>;
+//# sourceMappingURL=codec.d.ts.map

package/dist/stores/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/stores/codec.ts"],"names":[],"mappings":"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"}

package/dist/stores/codec.js

@@ -0,0 +1,186 @@
+/**
+ * Typed state codecs — the foundation of the World Stores layer.
+ *
+ * Every opaque base64 blob on the platform (actor replication `state`, voxel
+ * `voxelState`, chunk `chunkState`, client event `state`, channel/actor
+ * message `payload`, `UserAppState.state`, avatar public/private/app state)
+ * is app-defined. A {@link StateCodec} names that definition ONCE: the dev
+ * registers their custom type + encoder/decoder with a store, and the store
+ * speaks typed values everywhere else.
+ */
+import { decodeBase64, encodeBase64 } from '../utils.js';
+/**
+ * JSON codec: `JSON.stringify` → UTF-8 → base64. Convenient for low-rate,
+ * structured state (save blobs, avatar profiles, channel payloads). Do NOT
+ * use it for per-tick actor replication — spatial packets have a ~1.1 KB
+ * budget and JSON wastes most of it; use {@link structCodec} there.
+ */
+export function jsonCodec() {
+    return {
+        encode: (value) => encodeBase64(new TextEncoder().encode(JSON.stringify(value))),
+        decode: (data) => JSON.parse(new TextDecoder().decode(decodeBase64(data))),
+    };
+}
+/**
+ * Identity codec: the typed value IS the base64 string. Use it when the app
+ * already has its own encoding pipeline and just wants the stores' lifecycle
+ * management.
+ */
+export const rawCodec = {
+    encode: (value) => value,
+    decode: (data) => data,
+};
+/**
+ * UTF-8 text codec: plain strings ↔ base64 (chat payloads, simple messages).
+ */
+export const textCodec = {
+    encode: (value) => encodeBase64(new TextEncoder().encode(value)),
+    decode: (data) => new TextDecoder().decode(decodeBase64(data)),
+};
+/** 32-bit float field. */
+export function f32() {
+    return {
+        size: 4,
+        read: (v, o, le) => v.getFloat32(o, le),
+        write: (v, o, value, le) => v.setFloat32(o, value, le),
+    };
+}
+/** 64-bit float field (e.g. epoch-milliseconds timestamps). */
+export function f64() {
+    return {
+        size: 8,
+        read: (v, o, le) => v.getFloat64(o, le),
+        write: (v, o, value, le) => v.setFloat64(o, value, le),
+    };
+}
+/** Unsigned 8-bit int field (flags, small ids). */
+export function u8() {
+    return {
+        size: 1,
+        read: (v, o) => v.getUint8(o),
+        write: (v, o, value) => v.setUint8(o, value),
+    };
+}
+/** Unsigned 16-bit int field. */
+export function u16() {
+    return {
+        size: 2,
+        read: (v, o, le) => v.getUint16(o, le),
+        write: (v, o, value, le) => v.setUint16(o, value, le),
+    };
+}
+/** Unsigned 32-bit int field. */
+export function u32() {
+    return {
+        size: 4,
+        read: (v, o, le) => v.getUint32(o, le),
+        write: (v, o, value, le) => v.setUint32(o, value, le),
+    };
+}
+/** Signed 8-bit int field. */
+export function i8() {
+    return {
+        size: 1,
+        read: (v, o) => v.getInt8(o),
+        write: (v, o, value) => v.setInt8(o, value),
+    };
+}
+/** Signed 16-bit int field. */
+export function i16() {
+    return {
+        size: 2,
+        read: (v, o, le) => v.getInt16(o, le),
+        write: (v, o, value, le) => v.setInt16(o, value, le),
+    };
+}
+/** Signed 32-bit int field. */
+export function i32() {
+    return {
+        size: 4,
+        read: (v, o, le) => v.getInt32(o, le),
+        write: (v, o, value, le) => v.setInt32(o, value, le),
+    };
+}
+/** Boolean stored as one byte (0/1). */
+export function bool8() {
+    return {
+        size: 1,
+        read: (v, o) => v.getUint8(o) !== 0,
+        write: (v, o, value) => v.setUint8(o, value ? 1 : 0),
+    };
+}
+/** Fixed-length raw bytes field. */
+export function bytes(length) {
+    return {
+        size: length,
+        read: (v, o) => new Uint8Array(v.buffer, v.byteOffset + o, length).slice(),
+        write: (v, o, value) => {
+            const target = new Uint8Array(v.buffer, v.byteOffset + o, length);
+            target.set(value.subarray(0, length));
+        },
+    };
+}
+/** Reserved padding bytes — occupies layout space, absent from the value type. */
+export function reserved(length) {
+    return {
+        size: length,
+        skip: true,
+        read: () => undefined,
+        write: () => { },
+    };
+}
+/**
+ * Build a fixed-layout binary codec from a declarative field spec — the
+ * replication-state workhorse. Fields are laid out in declaration order,
+ * little-endian by default (matching the platform's wire conventions).
+ *
+ * The Blocks-with-Friends 48-byte pose, declaratively:
+ *
+ * ```ts
+ * const poseCodec = structCodec({
+ *   x: f32(), y: f32(), z: f32(),
+ *   yaw: f32(), pitch: f32(),
+ *   vx: f32(), vy: f32(), vz: f32(),
+ *   flags: u8(), heldBlockId: u8(), _r0: reserved(2),
+ *   updatedAt: f64(), _r1: reserved(4),
+ * }); // poseCodec.byteLength === 48
+ * ```
+ *
+ * @throws {Error} at decode time when the payload is shorter than the layout.
+ */
+export function structCodec(spec, options = {}) {
+    const littleEndian = options.littleEndian ?? true;
+    const fields = Object.entries(spec);
+    const byteLength = fields.reduce((sum, [, f]) => sum + f.size, 0);
+    return {
+        byteLength,
+        encode(value) {
+            const buffer = new Uint8Array(byteLength);
+            const view = new DataView(buffer.buffer);
+            let offset = 0;
+            for (const [name, field] of fields) {
+                if (!field.skip) {
+                    field.write(view, offset, value[name], littleEndian);
+                }
+                offset += field.size;
+            }
+            return encodeBase64(buffer);
+        },
+        decode(data) {
+            const buffer = decodeBase64(data);
+            if (buffer.byteLength < byteLength) {
+                throw new Error(`structCodec: payload is ${buffer.byteLength} bytes, layout needs ${byteLength}`);
+            }
+            const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+            const out = {};
+            let offset = 0;
+            for (const [name, field] of fields) {
+                if (!field.skip) {
+                    out[name] = field.read(view, offset, littleEndian);
+                }
+                offset += field.size;
+            }
+            return out;
+        },
+    };
+}