@codexo/exojs-tilemap 0.13.0

package/dist/esm/chunkGeometry.d.ts

@@ -0,0 +1,71 @@
+import type { Texture } from '@codexo/exojs';
+import type { ReadonlyTileChunk } from './TileChunk';
+import type { TileSet } from './TileSet';
+import type { TileTransform } from './types';
+/**
+ * One textured tile quad in chunk-local pixel space.
+ *
+ * `u0/v0/u1/v1` are the raw (min/max) source UV bounds of the tile within its
+ * tileset texture — flip/orientation is **not** baked here; it travels in
+ * {@link TileQuad.orient} and is applied by the per-backend renderer (flipX/Y
+ * via UV-corner swap, diagonal via an axis swap in the shader). Keeping the
+ * geometry orientation-neutral lets both backends share one CPU builder.
+ * @internal
+ */
+export interface TileQuad {
+    /** Local destination rect, left/top (chunk-local pixels). */
+    readonly x0: number;
+    readonly y0: number;
+    /** Local destination rect, right/bottom (chunk-local pixels). */
+    readonly x1: number;
+    readonly y1: number;
+    /** Normalised source UV bounds (always min ≤ max). */
+    readonly u0: number;
+    readonly v0: number;
+    readonly u1: number;
+    readonly v1: number;
+    /** Orientation code: bit0 = flipX, bit1 = flipY, bit2 = diagonal. */
+    readonly orient: number;
+}
+/**
+ * Geometry for one tileset "page" within a chunk: every tile in the chunk that
+ * draws from a single tileset texture, grouped so the renderer can batch by
+ * `(shader, texture)`.
+ * @internal
+ */
+export interface ChunkPage {
+    /** The tileset all quads in this page draw from. */
+    readonly tileset: TileSet;
+    /** The underlying GPU texture (the tileset's atlas), bound once per page. */
+    readonly texture: Texture;
+    /** The tile quads for this page, in deterministic row-major order. */
+    readonly quads: readonly TileQuad[];
+}
+/** Pack a {@link TileTransform} into a 3-bit orientation code. @internal */
+export declare function orientCode(transform: TileTransform): number;
+/** Read the cumulative chunk-geometry rebuild count. @internal */
+export declare function getTileGeometryRebuildCount(): number;
+/** Reset the chunk-geometry rebuild counter (call before a measured frame). @internal */
+export declare function resetTileGeometryRebuildCount(): void;
+/**
+ * Build per-tileset page geometry for a single chunk.
+ *
+ * Iterates the chunk's packed cells in deterministic row-major order, skipping
+ * empties, out-of-range tilesets, and out-of-range local tile ids (all treated
+ * as empty — this is the renderer's half of the G-GID contract). Each surviving
+ * cell is resolved to its source UV rect (from `tileset.getTileRect` + the
+ * tileset `TextureRegion`) and a chunk-local destination rect (bottom-left
+ * aligned per Tiled orthogonal semantics, so tilesets whose tiles are taller
+ * than the map grid extend upward).
+ *
+ * Allocation happens here only — the result is cached on the owning
+ * {@link import('./TileChunkNode').TileChunkNode} keyed by `chunk.revision`, so
+ * unchanged chunks never rebuild and the per-frame path stays allocation-free.
+ *
+ * @param chunk      The readonly chunk view to build from.
+ * @param tilesets   The layer's tileset array (packed `tilesetIndex` selects one).
+ * @param tileWidth  Map/layer tile cell width in pixels.
+ * @param tileHeight Map/layer tile cell height in pixels.
+ * @internal
+ */
+export declare function buildChunkPages(chunk: ReadonlyTileChunk, tilesets: readonly TileSet[], tileWidth: number, tileHeight: number): ChunkPage[];

package/dist/esm/chunkGeometry.js

@@ -0,0 +1,98 @@
+import { unpackTile } from './types.js';
+
+/** Pack a {@link TileTransform} into a 3-bit orientation code. @internal */
+function orientCode(transform) {
+    return (transform.flipX ? 1 : 0) | (transform.flipY ? 2 : 0) | (transform.diagonal ? 4 : 0);
+}
+/**
+ * Build per-tileset page geometry for a single chunk.
+ *
+ * Iterates the chunk's packed cells in deterministic row-major order, skipping
+ * empties, out-of-range tilesets, and out-of-range local tile ids (all treated
+ * as empty — this is the renderer's half of the G-GID contract). Each surviving
+ * cell is resolved to its source UV rect (from `tileset.getTileRect` + the
+ * tileset `TextureRegion`) and a chunk-local destination rect (bottom-left
+ * aligned per Tiled orthogonal semantics, so tilesets whose tiles are taller
+ * than the map grid extend upward).
+ *
+ * Allocation happens here only — the result is cached on the owning
+ * {@link import('./TileChunkNode').TileChunkNode} keyed by `chunk.revision`, so
+ * unchanged chunks never rebuild and the per-frame path stays allocation-free.
+ *
+ * @param chunk      The readonly chunk view to build from.
+ * @param tilesets   The layer's tileset array (packed `tilesetIndex` selects one).
+ * @param tileWidth  Map/layer tile cell width in pixels.
+ * @param tileHeight Map/layer tile cell height in pixels.
+ * @internal
+ */
+function buildChunkPages(chunk, tilesets, tileWidth, tileHeight) {
+    if (chunk.empty) {
+        return [];
+    }
+    const buckets = new Map();
+    const width = chunk.width;
+    const height = chunk.height;
+    for (let ly = 0; ly < height; ly++) {
+        for (let lx = 0; lx < width; lx++) {
+            const packed = chunk.getRawAt(lx, ly);
+            if (packed === 0) {
+                continue;
+            }
+            const decoded = unpackTile(packed);
+            if (decoded === null) {
+                continue;
+            }
+            const tileset = tilesets[decoded.tilesetIndex];
+            // Out-of-range tileset or local id → treat as empty (G-GID). getTileRect
+            // throws on an out-of-range id, so the bounds check must precede it.
+            if (tileset === undefined || decoded.localTileId >= tileset.tileCount) {
+                continue;
+            }
+            const region = tileset.texture;
+            const texture = region.texture;
+            const textureWidth = texture.width;
+            const textureHeight = texture.height;
+            if (textureWidth <= 0 || textureHeight <= 0) {
+                continue;
+            }
+            const rect = tileset.getTileRect(decoded.localTileId);
+            // Absolute source pixel rect = tileset-region offset + in-atlas tile rect.
+            const sx = region.x + rect.x;
+            const sy = region.y + rect.y;
+            // Exact tile UVs, no half-texel inset. This assumes NEAREST filtering on
+            // the tileset atlas (the typical pixel-art case). Under LINEAR/mipmap
+            // filtering an atlas WITHOUT extrusion padding can bleed neighbouring
+            // tiles at the edges; author tilesets with extruded margins for linear
+            // sampling. (Extrusion-aware tilemap UV insetting — already done on the
+            // NineSlice/RepeatingSprite geometry paths — is a v0.14 follow-up.)
+            const u0 = sx / textureWidth;
+            const v0 = sy / textureHeight;
+            const u1 = (sx + rect.width) / textureWidth;
+            const v1 = (sy + rect.height) / textureHeight;
+            // Bottom-left aligned destination (Tiled orthogonal). Uniform tiles
+            // (rect.height === tileHeight) collapse to a plain cell rect.
+            const x0 = lx * tileWidth;
+            const y0 = ly * tileHeight + tileHeight - rect.height;
+            const x1 = x0 + rect.width;
+            const y1 = y0 + rect.height;
+            let bucket = buckets.get(tileset);
+            if (bucket === undefined) {
+                bucket = [];
+                buckets.set(tileset, bucket);
+            }
+            bucket.push({ x0, y0, x1, y1, u0, v0, u1, v1, orient: orientCode(decoded.transform) });
+        }
+    }
+    // Emit pages in tileset-array order for deterministic, reproducible builds.
+    const pages = [];
+    for (const tileset of tilesets) {
+        const quads = buckets.get(tileset);
+        if (quads !== undefined && quads.length > 0) {
+            pages.push({ tileset, texture: tileset.texture.texture, quads });
+        }
+    }
+    return pages;
+}
+
+export { buildChunkPages, orientCode };
+//# sourceMappingURL=chunkGeometry.js.map

package/dist/esm/chunkGeometry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunkGeometry.js","sources":["../../../src/chunkGeometry.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/index.d.ts

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

package/dist/esm/index.js

@@ -0,0 +1,10 @@
+export { tilemapExtension } from './tilemapExtension.js';
+export { TileLayer } from './TileLayer.js';
+export { TileMap } from './TileMap.js';
+export { TileSet } from './TileSet.js';
+export { TileLayerNode } from './TileLayerNode.js';
+export { TileMapNode } from './TileMapNode.js';
+export { TileMapBand } from './TileMapBand.js';
+export { TileMapView } from './TileMapView.js';
+export { TILE_TRANSFORM_IDENTITY, tileToChunkCoord, tileToLocalInChunk } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}

package/dist/esm/pixelSnap.d.ts

@@ -0,0 +1,12 @@
+import type { PixelSnapMode } from '@codexo/exojs/rendering';
+/**
+ * Throw a deterministic error when `mode` is not a valid {@link PixelSnapMode}.
+ *
+ * Mirrors the core `Drawable` setter's guard so the tilemap node passthroughs
+ * (`TileMapView` / `TileMapNode` / `TileLayerNode`) reject JavaScript-invalid
+ * values atomically — even for an empty layer that has no chunk drawable to
+ * delegate the validation to. Kept local because the core guard is not part of
+ * the public API surface.
+ * @internal
+ */
+export declare function assertPixelSnapMode(mode: PixelSnapMode): void;

package/dist/esm/pixelSnap.js

@@ -0,0 +1,19 @@
+const validPixelSnapModes = new Set(['none', 'position', 'geometry']);
+/**
+ * Throw a deterministic error when `mode` is not a valid {@link PixelSnapMode}.
+ *
+ * Mirrors the core `Drawable` setter's guard so the tilemap node passthroughs
+ * (`TileMapView` / `TileMapNode` / `TileLayerNode`) reject JavaScript-invalid
+ * values atomically — even for an empty layer that has no chunk drawable to
+ * delegate the validation to. Kept local because the core guard is not part of
+ * the public API surface.
+ * @internal
+ */
+function assertPixelSnapMode(mode) {
+    if (typeof mode !== 'string' || !validPixelSnapModes.has(mode)) {
+        throw new Error(`pixelSnapMode must be 'none', 'position', or 'geometry' (got ${String(mode)}).`);
+    }
+}
+
+export { assertPixelSnapMode };
+//# sourceMappingURL=pixelSnap.js.map

package/dist/esm/pixelSnap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixelSnap.js","sources":["../../../src/pixelSnap.ts"],"sourcesContent":[null],"names":[],"mappings":"AAEA,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAS,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AAElG;;;;;;;;;AASG;AACG,SAAU,mBAAmB,CAAC,IAAmB,EAAA;AACrD,IAAA,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;QAC9D,MAAM,IAAI,KAAK,CAAC,CAAA,6DAAA,EAAgE,MAAM,CAAC,IAAI,CAAC,CAAA,EAAA,CAAI,CAAC;IACnG;AACF;;;;"}

package/dist/esm/public.d.ts

@@ -0,0 +1,18 @@
+export { tilemapExtension } from './tilemapExtension';
+export type { Extension } from '@codexo/exojs/extensions';
+export type { ReadonlyTileChunk } from './TileChunk';
+export type { TileLayerOptions } from './TileLayer';
+export { TileLayer } from './TileLayer';
+export type { TileMapOptions } from './TileMap';
+export { TileMap } from './TileMap';
+export type { TileSetOptions } from './TileSet';
+export { TileSet } from './TileSet';
+export type { TileLayerNodeOptions } from './TileLayerNode';
+export { TileLayerNode } from './TileLayerNode';
+export type { TileMapNodeOptions } from './TileMapNode';
+export { TileMapNode } from './TileMapNode';
+export { TileMapBand } from './TileMapBand';
+export type { TileLayerSelector, TileMapBandDefinition, TileMapViewOptions, } from './TileMapView';
+export { TileMapView } from './TileMapView';
+export type { ChunkCoord, PackedTile, ResolvedTile, TileDefinition, TileProperties, TilePropertyValue, TileTransform, } from './types';
+export { TILE_TRANSFORM_IDENTITY, tileToChunkCoord, tileToLocalInChunk, } from './types';

package/dist/esm/register.d.ts

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

package/dist/esm/register.js

@@ -0,0 +1,20 @@
+import { ExtensionRegistry } from '@codexo/exojs/extensions';
+import { tilemapExtension } from './tilemapExtension.js';
+export { TileLayer } from './TileLayer.js';
+export { TileMap } from './TileMap.js';
+export { TileSet } from './TileSet.js';
+export { TileLayerNode } from './TileLayerNode.js';
+export { TileMapNode } from './TileMapNode.js';
+export { TileMapBand } from './TileMapBand.js';
+export { TileMapView } from './TileMapView.js';
+export { TILE_TRANSFORM_IDENTITY, tileToChunkCoord, tileToLocalInChunk } from './types.js';
+
+// @codexo/exojs-tilemap/register — explicit registration entry.
+// Importing this entry registers the default tilemapExtension descriptor
+// in the global ExtensionRegistry. Subsequently constructed Applications
+// that use global defaults will receive the tilemap extension.
+// This is the only side-effectful entry in this package.
+ExtensionRegistry.register(tilemapExtension);
+
+export { tilemapExtension };
+//# sourceMappingURL=register.js.map

package/dist/esm/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sources":["../../../src/register.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;;;;;AAAA;AACA;AACA;AACA;AACA;AAMA,iBAAiB,CAAC,QAAQ,CAAC,gBAAgB,CAAC;;;;"}

package/dist/esm/tilemapExtension.d.ts

@@ -0,0 +1,18 @@
+import type { Extension } from '@codexo/exojs/extensions';
+/**
+ * Default immutable tilemap extension descriptor.
+ *
+ * Registers the WebGL2/WebGPU tile chunk renderers (`renderers`); it carries no
+ * asset bindings — there is no generic on-disk tilemap format in this slice, so
+ * format adapters (e.g. `@codexo/exojs-tiled`) own loading and depend on this
+ * descriptor to pull in rendering.
+ *
+ * Install + register directly for procedural / hand-built maps
+ * (`extensions: [tilemapExtension]` plus a `TileMap` built via the runtime), or
+ * receive it transitively through a format adapter's `dependencies`.
+ *
+ * Use with `ApplicationOptions.extensions` or call
+ * `import '@codexo/exojs-tilemap/register'` for global auto-registration.
+ * @advanced
+ */
+export declare const tilemapExtension: Extension;

package/dist/esm/tilemapExtension.js

@@ -0,0 +1,52 @@
+import { RenderBackendType } from '@codexo/exojs/rendering';
+import { TileChunkNode } from './TileChunkNode.js';
+import { WebGl2TileChunkRenderer } from './webgl2/WebGl2TileChunkRenderer.js';
+import { WebGpuTileChunkRenderer } from './webgpu/WebGpuTileChunkRenderer.js';
+
+/** Per-tile instance batch size for the WebGL2 tile chunk renderer. */
+const tileRendererBatchSize = 4096;
+/**
+ * Build the renderer binding that wires the per-backend
+ * {@link import('./TileChunkNode').TileChunkNode} renderers. The binding targets
+ * the internal chunk drawable; applications never construct it directly — they
+ * build {@link import('./TileMapNode').TileMapNode} /
+ * {@link import('./TileLayerNode').TileLayerNode}, whose chunk children resolve
+ * to this renderer through the registry prototype walk.
+ */
+function buildTileChunkRendererBinding(batchSize) {
+    return {
+        targets: [TileChunkNode],
+        create(backend) {
+            if (backend.backendType === RenderBackendType.WebGl2) {
+                return new WebGl2TileChunkRenderer(batchSize);
+            }
+            if (backend.backendType === RenderBackendType.WebGpu) {
+                return new WebGpuTileChunkRenderer();
+            }
+            throw new Error(`Unsupported render backend: ${String(backend.backendType)}`);
+        },
+    };
+}
+/**
+ * Default immutable tilemap extension descriptor.
+ *
+ * Registers the WebGL2/WebGPU tile chunk renderers (`renderers`); it carries no
+ * asset bindings — there is no generic on-disk tilemap format in this slice, so
+ * format adapters (e.g. `@codexo/exojs-tiled`) own loading and depend on this
+ * descriptor to pull in rendering.
+ *
+ * Install + register directly for procedural / hand-built maps
+ * (`extensions: [tilemapExtension]` plus a `TileMap` built via the runtime), or
+ * receive it transitively through a format adapter's `dependencies`.
+ *
+ * Use with `ApplicationOptions.extensions` or call
+ * `import '@codexo/exojs-tilemap/register'` for global auto-registration.
+ * @advanced
+ */
+const tilemapExtension = Object.freeze({
+    id: '@codexo/exojs-tilemap',
+    renderers: [buildTileChunkRendererBinding(tileRendererBatchSize)],
+});
+
+export { tilemapExtension };
+//# sourceMappingURL=tilemapExtension.js.map

package/dist/esm/tilemapExtension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tilemapExtension.js","sources":["../../../src/tilemapExtension.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAQA;AACA,MAAM,qBAAqB,GAAG,IAAI;AAElC;;;;;;;AAOG;AACH,SAAS,6BAA6B,CAAC,SAAiB,EAAA;IACtD,OAAO;QACL,OAAO,EAAE,CAAC,aAAa,CAAC;AACxB,QAAA,MAAM,CAAC,OAAsB,EAAA;YAC3B,IAAI,OAAO,CAAC,WAAW,KAAK,iBAAiB,CAAC,MAAM,EAAE;AACpD,gBAAA,OAAO,IAAI,uBAAuB,CAAC,SAAS,CAAC;YAC/C;YAEA,IAAI,OAAO,CAAC,WAAW,KAAK,iBAAiB,CAAC,MAAM,EAAE;gBACpD,OAAO,IAAI,uBAAuB,EAAE;YACtC;AAEA,YAAA,MAAM,IAAI,KAAK,CAAC,CAAA,4BAAA,EAA+B,MAAM,CAAC,OAAO,CAAC,WAA2B,CAAC,CAAA,CAAE,CAAC;QAC/F,CAAC;KACF;AACH;AAEA;;;;;;;;;;;;;;;AAeG;AACI,MAAM,gBAAgB,GAAc,MAAM,CAAC,MAAM,CAAC;AACvD,IAAA,EAAE,EAAE,uBAAuB;AAC3B,IAAA,SAAS,EAAE,CAAC,6BAA6B,CAAC,qBAAqB,CAAC,CAAC;AAClE,CAAA;;;;"}

package/dist/esm/types.d.ts

@@ -0,0 +1,139 @@
+import type { TileSet } from './TileSet';
+/**
+ * Union of legal tile-property value types in the generic runtime.
+ * Format-neutral; adapters map their native property systems into this set.
+ * @advanced
+ */
+export type TilePropertyValue = null | boolean | number | string;
+/**
+ * An immutable, flat key-value bag of generic tile properties.
+ * Adapters copy and freeze source properties; the runtime never retains
+ * a caller-owned mutable object.
+ * @advanced
+ */
+export type TileProperties = Readonly<Record<string, TilePropertyValue>>;
+/**
+ * Describes the orientation of a placed tile independent of source-format
+ * flip-bit encodings. The eight legal combinations map to the eight distinct
+ * 90°-rotation-and-flip states of a rectangular texture quad.
+ *
+ * Applying the transform at geometry-build time (reordering UV corners)
+ * avoids per-tile runtime cost and per-frame matrix allocation.
+ * @stable
+ */
+export interface TileTransform {
+    /** Horizontal flip (mirror left-right). */
+    readonly flipX: boolean;
+    /** Vertical flip (mirror top-bottom). */
+    readonly flipY: boolean;
+    /** Anti-diagonal flip (transpose of the UV axes). Combined with flips produces 90° rotations. */
+    readonly diagonal: boolean;
+}
+/** The identity transform: no flip, no diagonal. */
+export declare const TILE_TRANSFORM_IDENTITY: Readonly<TileTransform>;
+/**
+ * Short string label for a {@link TileTransform} (debug / serialisation).
+ * Returns one of the eight deterministic names, e.g. `"flipX"` or `"diag+flipX+flipY"`.
+ * @internal
+ */
+export declare function tileTransformLabel(t: TileTransform): string;
+/**
+ * Opaque packed tile data stored in a {@link TileChunk}'s compact array.
+ * 0 means "empty cell". Any non-zero value encodes localTileId, tilesetIndex,
+ * and flip bits according to the bit-layout constants below.
+ *
+ * A `PackedTile` is **not** a source-format GID — it is a fully resolved
+ * internal compact representation. Use {@link packTile} / {@link unpackTile}
+ * (package-internal) to convert between packed form and a {@link ResolvedTile}
+ * if writing adapters.
+ *
+ * In public APIs, prefer {@link ResolvedTile} or null for queries.
+ * `PackedTile` is exposed as `@advanced` so `ReadonlyTileChunk.getRawAt()`
+ * has a self-documenting return type.
+ * @advanced
+ */
+export type PackedTile = number;
+/** Bit width allocated to the local tile ID within a packed tile word. */
+export declare const PACKED_LOCAL_BITS = 20;
+/** Bit width allocated to the tileset index within a packed tile word. */
+export declare const PACKED_TILESET_BITS = 9;
+/** Bit width allocated to the transform/flip bits. */
+export declare const PACKED_TRANSFORM_BITS = 3;
+export declare const PACKED_LOCAL_MASK: number;
+export declare const PACKED_TILESET_MASK: number;
+export declare const PACKED_TRANSFORM_MASK: number;
+export declare const PACKED_TILESET_SHIFT = 20;
+export declare const PACKED_TRANSFORM_SHIFT: number;
+/** Maximum tileset index representable in a packed tile. */
+export declare const MAX_TILESET_INDEX: number;
+/** Maximum local tile ID representable in a packed tile (1-based storage). */
+export declare const MAX_LOCAL_TILE_ID: number;
+/**
+ * Encode a tileset-local tile reference and transform into a packed word.
+ * The localTileId is stored as (localTileId + 1) so that a packed value of 0
+ * cleanly represents an empty cell, while tile 0 from tileset 0 with identity
+ * transform is stored as 1 (non-zero).
+ * Returns 0 for an empty cell.
+ * @internal
+ */
+export declare function packTile(tilesetIndex: number, localTileId: number, transform: TileTransform): PackedTile;
+/**
+ * Decode a packed word into its components.
+ * Returns null for an empty cell (packed === 0).
+ * @internal
+ */
+export declare function unpackTile(packed: PackedTile): {
+    tilesetIndex: number;
+    localTileId: number;
+    transform: TileTransform;
+} | null;
+/**
+ * A fully resolved, format-independent tile reference returned by queries.
+ * Materialised on-demand from the packed storage; never stored as a per-cell
+ * heap object.
+ * @advanced
+ */
+export interface ResolvedTile {
+    /** The owning tileset (already resolved from source-format GID). */
+    readonly tileset: TileSet;
+    /** 0-based tile index within the tileset. */
+    readonly localTileId: number;
+    /** Orientation transform for this placed tile. */
+    readonly transform: TileTransform;
+}
+/**
+ * Optional per-tile metadata in a {@link TileSet}. Sparse — only defined
+ * tiles carry a definition. May carry animation data in future slices.
+ * @advanced
+ */
+export interface TileDefinition {
+    /** The local tile ID this definition belongs to. */
+    readonly localTileId: number;
+    /** Tile properties (copied and frozen by the tileset). */
+    readonly properties?: TileProperties;
+}
+/** A signed chunk coordinate pair. */
+export interface ChunkCoord {
+    readonly cx: number;
+    readonly cy: number;
+}
+/** Convert tile coordinates to chunk coordinates given a chunk size. */
+export declare function tileToChunkCoord(tx: number, ty: number, chunkW: number, chunkH: number): ChunkCoord;
+/** Convert tile coordinates to local-in-chunk coordinates. */
+export declare function tileToLocalInChunk(tx: number, ty: number, chunkW: number, chunkH: number): {
+    lx: number;
+    ly: number;
+};
+/**
+ * Validate that a value is a finite, safe, positive integer.
+ * Used for dimensions, tile counts, chunk sizes.
+ */
+export declare function validatePositiveInteger(value: number, label: string): void;
+/**
+ * Validate a non-negative finite integer.
+ */
+export declare function validateNonNegativeInteger(value: number, label: string): void;
+/**
+ * Validate that a value is a finite integer (may be negative).
+ */
+export declare function validateInteger(value: number, label: string): void;

package/dist/esm/types.js

@@ -0,0 +1,121 @@
+/** The identity transform: no flip, no diagonal. */
+const TILE_TRANSFORM_IDENTITY = Object.freeze({
+    flipX: false,
+    flipY: false,
+    diagonal: false,
+});
+/** Bit width allocated to the local tile ID within a packed tile word. */
+const PACKED_LOCAL_BITS = 20;
+/** Bit width allocated to the tileset index within a packed tile word. */
+const PACKED_TILESET_BITS = 9;
+/** Bit width allocated to the transform/flip bits. */
+const PACKED_TRANSFORM_BITS = 3;
+const PACKED_LOCAL_MASK = (1 << PACKED_LOCAL_BITS) - 1;
+const PACKED_TILESET_MASK = ((1 << PACKED_TILESET_BITS) - 1) << PACKED_LOCAL_BITS;
+const PACKED_TRANSFORM_MASK = ((1 << PACKED_TRANSFORM_BITS) - 1) << (PACKED_LOCAL_BITS + PACKED_TILESET_BITS);
+const PACKED_TILESET_SHIFT = PACKED_LOCAL_BITS;
+const PACKED_TRANSFORM_SHIFT = PACKED_LOCAL_BITS + PACKED_TILESET_BITS;
+/** Maximum tileset index representable in a packed tile. */
+const MAX_TILESET_INDEX = (1 << PACKED_TILESET_BITS) - 1;
+/** Maximum local tile ID representable in a packed tile (1-based storage). */
+const MAX_LOCAL_TILE_ID = (1 << PACKED_LOCAL_BITS) - 2;
+// Transform bit-field values (bit 0 = flipX, bit 1 = flipY, bit 2 = diagonal).
+const TRANSFORM_FLIP_X = 1 << 0;
+const TRANSFORM_FLIP_Y = 1 << 1;
+const TRANSFORM_DIAGONAL = 1 << 2;
+/**
+ * Encode a tileset-local tile reference and transform into a packed word.
+ * The localTileId is stored as (localTileId + 1) so that a packed value of 0
+ * cleanly represents an empty cell, while tile 0 from tileset 0 with identity
+ * transform is stored as 1 (non-zero).
+ * Returns 0 for an empty cell.
+ * @internal
+ */
+function packTile(tilesetIndex, localTileId, transform) {
+    if (tilesetIndex < 0 || tilesetIndex > MAX_TILESET_INDEX) {
+        throw new Error(`Tileset index ${tilesetIndex} exceeds maximum ${MAX_TILESET_INDEX}.`);
+    }
+    if (localTileId < 0 || localTileId > MAX_LOCAL_TILE_ID) {
+        throw new Error(`Local tile ID ${localTileId} exceeds maximum ${MAX_LOCAL_TILE_ID}.`);
+    }
+    let bits = 0;
+    if (transform.flipX)
+        bits |= TRANSFORM_FLIP_X;
+    if (transform.flipY)
+        bits |= TRANSFORM_FLIP_Y;
+    if (transform.diagonal)
+        bits |= TRANSFORM_DIAGONAL;
+    // +1 so 0 means "empty" not "tile 0 without transform"
+    const storedId = localTileId + 1;
+    return (storedId & PACKED_LOCAL_MASK)
+        | ((tilesetIndex << PACKED_TILESET_SHIFT) & PACKED_TILESET_MASK)
+        | ((bits << PACKED_TRANSFORM_SHIFT) & PACKED_TRANSFORM_MASK);
+}
+/**
+ * Decode a packed word into its components.
+ * Returns null for an empty cell (packed === 0).
+ * @internal
+ */
+function unpackTile(packed) {
+    if (packed === 0)
+        return null;
+    const storedId = packed & PACKED_LOCAL_MASK;
+    // Undo the +1 offset applied during packTile.
+    const localTileId = storedId - 1;
+    const tilesetIndex = (packed & PACKED_TILESET_MASK) >>> PACKED_TILESET_SHIFT;
+    const rawTransform = (packed & PACKED_TRANSFORM_MASK) >>> PACKED_TRANSFORM_SHIFT;
+    return {
+        tilesetIndex,
+        localTileId,
+        transform: {
+            flipX: !!(rawTransform & TRANSFORM_FLIP_X),
+            flipY: !!(rawTransform & TRANSFORM_FLIP_Y),
+            diagonal: !!(rawTransform & TRANSFORM_DIAGONAL),
+        },
+    };
+}
+/** Convert tile coordinates to chunk coordinates given a chunk size. */
+function tileToChunkCoord(tx, ty, chunkW, chunkH) {
+    return {
+        cx: Math.floor(tx / chunkW),
+        cy: Math.floor(ty / chunkH),
+    };
+}
+/** Convert tile coordinates to local-in-chunk coordinates. */
+function tileToLocalInChunk(tx, ty, chunkW, chunkH) {
+    return {
+        lx: ((tx % chunkW) + chunkW) % chunkW,
+        ly: ((ty % chunkH) + chunkH) % chunkH,
+    };
+}
+/**
+ * Validate that a value is a finite, safe, positive integer.
+ * Used for dimensions, tile counts, chunk sizes.
+ */
+function validatePositiveInteger(value, label) {
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive integer (got ${value}).`);
+    }
+    if (value > Number.MAX_SAFE_INTEGER) {
+        throw new Error(`${label} exceeds safe integer range (got ${value}).`);
+    }
+}
+/**
+ * Validate a non-negative finite integer.
+ */
+function validateNonNegativeInteger(value, label) {
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${label} must be a non-negative integer (got ${value}).`);
+    }
+}
+/**
+ * Validate that a value is a finite integer (may be negative).
+ */
+function validateInteger(value, label) {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+        throw new Error(`${label} must be a finite integer (got ${value}).`);
+    }
+}
+
+export { MAX_LOCAL_TILE_ID, MAX_TILESET_INDEX, PACKED_LOCAL_BITS, PACKED_LOCAL_MASK, PACKED_TILESET_BITS, PACKED_TILESET_MASK, PACKED_TILESET_SHIFT, PACKED_TRANSFORM_BITS, PACKED_TRANSFORM_MASK, PACKED_TRANSFORM_SHIFT, TILE_TRANSFORM_IDENTITY, packTile, tileToChunkCoord, tileToLocalInChunk, unpackTile, validateInteger, validateNonNegativeInteger, validatePositiveInteger };
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sources":["../../../src/types.ts"],"sourcesContent":[null],"names":[],"mappings":"AA2CA;AACO,MAAM,uBAAuB,GAA4B,MAAM,CAAC,MAAM,CAAC;AAC5E,IAAA,KAAK,EAAE,KAAK;AACZ,IAAA,KAAK,EAAE,KAAK;AACZ,IAAA,QAAQ,EAAE,KAAK;AAChB,CAAA;AAkCD;AACO,MAAM,iBAAiB,GAAG;AACjC;AACO,MAAM,mBAAmB,GAAG;AACnC;AACO,MAAM,qBAAqB,GAAG;AAE9B,MAAM,iBAAiB,GAAG,CAAC,CAAC,IAAI,iBAAiB,IAAI;AACrD,MAAM,mBAAmB,GAAG,CAAC,CAAC,CAAC,IAAI,mBAAmB,IAAI,CAAC,KAAK;AAChE,MAAM,qBAAqB,GAAG,CAAC,CAAC,CAAC,IAAI,qBAAqB,IAAI,CAAC,MAAM,iBAAiB,GAAG,mBAAmB;AAE5G,MAAM,oBAAoB,GAAG;AAC7B,MAAM,sBAAsB,GAAG,iBAAiB,GAAG;AAE1D;AACO,MAAM,iBAAiB,GAAG,CAAC,CAAC,IAAI,mBAAmB,IAAI;AAC9D;AACO,MAAM,iBAAiB,GAAG,CAAC,CAAC,IAAI,iBAAiB,IAAI;AAE5D;AACA,MAAM,gBAAgB,GAAG,CAAC,IAAI,CAAC;AAC/B,MAAM,gBAAgB,GAAG,CAAC,IAAI,CAAC;AAC/B,MAAM,kBAAkB,GAAG,CAAC,IAAI,CAAC;AAEjC;;;;;;;AAOG;SACa,QAAQ,CAAC,YAAoB,EAAE,WAAmB,EAAE,SAAwB,EAAA;IAC1F,IAAI,YAAY,GAAG,CAAC,IAAI,YAAY,GAAG,iBAAiB,EAAE;QACxD,MAAM,IAAI,KAAK,CAAC,CAAA,cAAA,EAAiB,YAAY,CAAA,iBAAA,EAAoB,iBAAiB,CAAA,CAAA,CAAG,CAAC;IACxF;IACA,IAAI,WAAW,GAAG,CAAC,IAAI,WAAW,GAAG,iBAAiB,EAAE;QACtD,MAAM,IAAI,KAAK,CAAC,CAAA,cAAA,EAAiB,WAAW,CAAA,iBAAA,EAAoB,iBAAiB,CAAA,CAAA,CAAG,CAAC;IACvF;IACA,IAAI,IAAI,GAAG,CAAC;IACZ,IAAI,SAAS,CAAC,KAAK;QAAE,IAAI,IAAI,gBAAgB;IAC7C,IAAI,SAAS,CAAC,KAAK;QAAE,IAAI,IAAI,gBAAgB;IAC7C,IAAI,SAAS,CAAC,QAAQ;QAAE,IAAI,IAAI,kBAAkB;;AAElD,IAAA,MAAM,QAAQ,GAAG,WAAW,GAAG,CAAC;AAChC,IAAA,OAAO,CAAC,QAAQ,GAAG,iBAAiB;AAChC,WAAC,CAAC,YAAY,IAAI,oBAAoB,IAAI,mBAAmB;WAC5D,CAAC,IAAI,IAAI,sBAAsB,IAAI,qBAAqB,CAAC;AAChE;AAEA;;;;AAIG;AACG,SAAU,UAAU,CAAC,MAAkB,EAAA;IAK3C,IAAI,MAAM,KAAK,CAAC;AAAE,QAAA,OAAO,IAAI;AAC7B,IAAA,MAAM,QAAQ,GAAG,MAAM,GAAG,iBAAiB;;AAE3C,IAAA,MAAM,WAAW,GAAG,QAAQ,GAAG,CAAC;IAChC,MAAM,YAAY,GAAG,CAAC,MAAM,GAAG,mBAAmB,MAAM,oBAAoB;IAC5E,MAAM,YAAY,GAAG,CAAC,MAAM,GAAG,qBAAqB,MAAM,sBAAsB;IAChF,OAAO;QACL,YAAY;QACZ,WAAW;AACX,QAAA,SAAS,EAAE;AACT,YAAA,KAAK,EAAE,CAAC,EAAE,YAAY,GAAG,gBAAgB,CAAC;AAC1C,YAAA,KAAK,EAAE,CAAC,EAAE,YAAY,GAAG,gBAAgB,CAAC;AAC1C,YAAA,QAAQ,EAAE,CAAC,EAAE,YAAY,GAAG,kBAAkB,CAAC;AAChD,SAAA;KACF;AACH;AAyCA;AACM,SAAU,gBAAgB,CAAC,EAAU,EAAE,EAAU,EAAE,MAAc,EAAE,MAAc,EAAA;IACrF,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,MAAM,CAAC;QAC3B,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,MAAM,CAAC;KAC5B;AACH;AAEA;AACM,SAAU,kBAAkB,CAAC,EAAU,EAAE,EAAU,EAAE,MAAc,EAAE,MAAc,EAAA;IACvF,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM;QACrC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM;KACtC;AACH;AAEA;;;AAGG;AACG,SAAU,uBAAuB,CAAC,KAAa,EAAE,KAAa,EAAA;IAClE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE;QACrE,MAAM,IAAI,KAAK,CAAC,CAAA,EAAG,KAAK,CAAA,iCAAA,EAAoC,KAAK,CAAA,EAAA,CAAI,CAAC;IACxE;AACA,IAAA,IAAI,KAAK,GAAG,MAAM,CAAC,gBAAgB,EAAE;QACnC,MAAM,IAAI,KAAK,CAAC,CAAA,EAAG,KAAK,CAAA,iCAAA,EAAoC,KAAK,CAAA,EAAA,CAAI,CAAC;IACxE;AACF;AAEA;;AAEG;AACG,SAAU,0BAA0B,CAAC,KAAa,EAAE,KAAa,EAAA;IACrE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE;QACpE,MAAM,IAAI,KAAK,CAAC,CAAA,EAAG,KAAK,CAAA,qCAAA,EAAwC,KAAK,CAAA,EAAA,CAAI,CAAC;IAC5E;AACF;AAEA;;AAEG;AACG,SAAU,eAAe,CAAC,KAAa,EAAE,KAAa,EAAA;AAC1D,IAAA,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE;QACvD,MAAM,IAAI,KAAK,CAAC,CAAA,EAAG,KAAK,CAAA,+BAAA,EAAkC,KAAK,CAAA,EAAA,CAAI,CAAC;IACtE;AACF;;;;"}