@codexo/exojs-tilemap 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codexo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# @codexo/exojs-tilemap
+
+Generic, format-independent tilemap runtime **and** WebGL2/WebGPU chunk renderer for
+[ExoJS](https://exojs.dev). No Tiled (or any other on-disk format) vocabulary leaks into this
+package — adapters such as [`@codexo/exojs-tiled`](https://www.npmjs.com/package/@codexo/exojs-tiled)
+parse their format and hand this runtime fully-resolved tiles.
+
+## Installation
+
+```sh
+npm install @codexo/exojs @codexo/exojs-tilemap
+```
+
+`@codexo/exojs` is a peer dependency. Most users load Tiled maps and get this package
+transitively through `@codexo/exojs-tiled` — install it directly only for procedural or
+custom-format maps.
+
+## What this package provides
+
+**Runtime (data model)** — pure data, no scene graph:
+
+- `TileMap` — a finite, chunk-first map: dimensions, tile size, `tilesets`, ordered `layers`.
+- `TileLayer` — one tile layer; packed `Uint32Array` chunk storage, `visible` / `opacity` /
+  `offsetX/Y`, queries, and revision tracking.
+- `TileSet` — a resolved tileset grid over a Core `TextureRegion` (Loader-owned texture).
+- `ResolvedTile` / `TileTransform` — value-typed tile references with `flipX` / `flipY` /
+  `diagonal` orientation.
+
+**Scene / rendering (`@advanced`)**:
+
+- `TileMapNode` — convenience root that renders a whole `TileMap`.
+- `TileLayerNode` — renders one `TileLayer`; generated per layer by `TileMapView` (or construct
+  directly).
+- `TileMapView` — groups a map's layers into independently placeable layer nodes and named
+  `TileMapBand`s for actor interleaving (a helper, not a scene node).
+- `TileMapBand` — a `Container` of tile-layer nodes produced by `TileMapView`.
+- `tilemapExtension` — extension descriptor carrying the WebGL2/WebGPU renderer bindings.
+
+## Usage — procedural map
+
+```ts
+import { Application, Texture, TextureRegion } from '@codexo/exojs';
+import {
+  TileLayer,
+  TileMap,
+  TileMapNode,
+  TileSet,
+  tilemapExtension,
+  TILE_TRANSFORM_IDENTITY,
+} from '@codexo/exojs-tilemap';
+
+const app = new Application({ extensions: [tilemapExtension] /* canvas, … */ });
+
+// Tileset over a Loader-owned atlas texture (the runtime never destroys it).
+const atlas = await app.loader.load(Texture, 'tiles.png');
+const terrain = new TileSet({
+  name: 'terrain',
+  texture: new TextureRegion(atlas, { x: 0, y: 0, width: atlas.width, height: atlas.height }),
+  tileWidth: 16,
+  tileHeight: 16,
+  tileCount: 256,
+});
+
+const ground = new TileLayer({
+  id: 1,
+  name: 'ground',
+  width: 64,
+  height: 64,
+  tileWidth: 16,
+  tileHeight: 16,
+  tilesets: [terrain],
+});
+ground.setTileAt(0, 0, { tileset: terrain, localTileId: 5, transform: TILE_TRANSFORM_IDENTITY });
+
+const map = new TileMap({
+  name: 'world',
+  width: 64,
+  height: 64,
+  tileWidth: 16,
+  tileHeight: 16,
+  tilesets: [terrain],
+  layers: [ground],
+});
+
+// Render the whole map.
+app.scene.root.addChild(new TileMapNode(map));
+```
+
+### Interleaving actors between layers — `TileMapView`
+
+`TileMapNode` owns **only** the map's layer nodes and renders them back-to-front — use it when
+nothing renders between layers. To draw application actors *between* tile layers, create a
+`TileMapView`: it generates one `TileLayerNode` per map layer (stable identity, map document
+order) and groups them into named `TileMapBand`s that you parent yourself, as siblings of your
+own actor containers:
+
+```ts
+const view = map.createView({
+  bands: {
+    ground: ['background', 'ground'],
+    roof: ['roofs', 'foreground'],
+  },
+});
+
+worldRoot.addChild(
+  view.band('ground'),
+  actors,            // app-owned actor container — drawn between ground and roof
+  view.band('roof'),
+);
+```
+
+Or, without bands, place the generated per-layer nodes directly:
+
+```ts
+const view = map.createView();
+
+worldRoot.addChild(view.getLayerNodeById(groundId)!, actors, view.getLayerNodeById(roofId)!);
+```
+
+Actors are application-owned siblings. `TileMapView` never adopts or destroys actors.
+
+- A band definition **selects** layers (by id, or by unique layer name); rendering order within
+  a band always follows map document order — definitions never reorder layers.
+- Layers not listed in any band stay reachable via `view.getLayerNodeById(id)` /
+  `view.getLayerNodesByName(name)`; they are not auto-added to any band.
+- Destroying a view or a band destroys only the tile nodes it generated — never actors, the
+  `TileMap`, its `TileLayer`s, or tileset textures.
+- There is no map-replacement API: to swap maps, destroy the old view and create a new view from
+  the new map — the actor tree is untouched.
+- After layers are structurally added to or removed from the map, call `view.refreshLayers()`:
+  unchanged layer nodes keep their identity and bands keep their placement in your scene graph.
+
+## `/register` convenience entry
+
+```ts
+// Side effect: registers tilemapExtension in the global ExtensionRegistry.
+import '@codexo/exojs-tilemap/register';
+```
+
+## Renderer model
+
+- **Chunk-first.** A `TileLayerNode` is a container of per-chunk `TileChunkNode` drawables (one
+  per non-empty loaded chunk). The renderer batches tiles by `(shader, tileset texture)` and
+  issues one instanced draw per batch — draw calls scale with *visible chunks × layers*, not
+  total tile count.
+- **Revision-cached geometry.** Each chunk's quad geometry is built once and cached against the
+  source chunk's `revision`. Unchanged chunks never rebuild; a camera pan rebuilds nothing —
+  off-screen chunks are culled by their local bounds before any geometry is touched.
+- **Orientation.** `flipX` / `flipY` / `diagonal` are baked into the chunk geometry / resolved in
+  the shader (all 8 combinations), with no per-tile matrix or per-frame cost.
+- **Multiple tilesets** with differing tile sizes are first-class; tiles taller than the map grid
+  are bottom-left aligned (Tiled orthogonal convention).
+- **WebGL2 and WebGPU** share one CPU geometry builder and produce identical output (golden
+  parity tested on both backends).
+- **Sampling.** Tile UVs are exact (no half-texel inset), which assumes **nearest** atlas
+  filtering — the typical pixel-art case. Under linear or mipmap filtering, author tilesets with
+  extruded tile margins to avoid neighbour bleed at tile edges (extrusion-aware tilemap UV
+  insetting is a planned follow-up; the `NineSlice` / `RepeatingSprite` geometry paths already
+  inset).
+
+## Ownership & lifecycle
+
+- Tileset **textures are Loader-owned**. The runtime and renderer never destroy them.
+- `TileMapNode` / `TileMapView` / `TileMapBand` / `TileLayerNode` reference — but never own —
+  the `TileMap`. Destroying a map node, view, or band frees only the tile nodes it generated
+  (detaching them from their application parents) and their cached geometry; application actors,
+  the `TileMap` data, its `TileLayer`s, and textures all survive. Free those via
+  `TileMap.destroy()` and `Loader.destroy()` respectively.
+- A `TileMapNode` or `TileMapView` reflects the layer set at construction time. After layers are
+  structurally added to or removed from the map call `node.refreshLayers()` /
+  `view.refreshLayers()`; after tiles are written into previously-empty chunks call
+  `layerNode.refresh()`. In-place edits to existing chunks are picked up automatically.
+
+## Core compatibility
+
+| `@codexo/exojs-tilemap` | `@codexo/exojs` |
+|---|---|
+| 0.x | matching `0.x` |
+
+## Links
+
+- [API reference](https://exojs.dev/api/exojs-tilemap)
+- [`@codexo/exojs-tiled`](https://www.npmjs.com/package/@codexo/exojs-tiled) — load Tiled `.tmj` maps into this runtime
+
+## License
+
+MIT

package/dist/esm/TileChunk.d.ts

@@ -0,0 +1,136 @@
+import type { PackedTile } from './types';
+/**
+ * Public readonly view of a tile chunk.
+ *
+ * Provides read-only inspection access for iteration, queries, and the
+ * future renderer. The underlying storage is never exposed directly.
+ *
+ * @advanced
+ */
+export interface ReadonlyTileChunk {
+    /** Signed chunk X coordinate. */
+    readonly cx: number;
+    /** Signed chunk Y coordinate. */
+    readonly cy: number;
+    /** Width of this chunk in tiles. */
+    readonly width: number;
+    /** Height of this chunk in tiles. */
+    readonly height: number;
+    /** Whether every cell is empty (all-zero). */
+    readonly empty: boolean;
+    /**
+     * Monotonic revision counter. Increments on every cell mutation
+     * within this chunk. No-ops (writing same value) do NOT increment.
+     */
+    readonly revision: number;
+    /**
+     * Read the raw packed tile word at local-in-chunk coordinates.
+     * Returns 0 for empty.
+     * @throws If coordinates are invalid.
+     */
+    getRawAt(lx: number, ly: number): PackedTile;
+    /**
+     * Create a defensive copy of the tile data. The caller owns the copy;
+     * mutation of the returned array cannot affect the chunk.
+     */
+    cloneTiles(): Uint32Array;
+}
+/**
+ * A compact, fixed-size chunk of tile data within a layer.
+ *
+ * Storage is a single {@link Uint32Array} of length `width * height`,
+ * laid out row-major. Each cell is a packed tile word (0 = empty).
+ * Chunk coordinates are signed to support future infinite maps.
+ *
+ * The backing array is **private** — external code cannot mutate storage
+ * directly. All mutation must flow through {@link TileLayer} public APIs,
+ * which call the package-internal `_setRawAt` method.
+ *
+ * The chunk tracks a revision counter that increments on every mutation
+ * so the future renderer can detect which chunks need GPU rebuilds.
+ *
+ * @advanced
+ */
+export declare class TileChunk implements ReadonlyTileChunk {
+    /** Signed chunk X coordinate. */
+    readonly cx: number;
+    /** Signed chunk Y coordinate. */
+    readonly cy: number;
+    /** Width of this chunk in tiles. */
+    readonly width: number;
+    /** Height of this chunk in tiles. */
+    readonly height: number;
+    /** Packed tile storage (row-major). Private — never exposed directly. */
+    private readonly _tiles;
+    /** Whether every cell in this chunk is empty (0). Lazy-computed. */
+    private _empty;
+    /** Monotonic revision counter — incremented on every mutation. */
+    private _revision;
+    /**
+     * @param cx Signed chunk X coordinate (must be finite safe integer).
+     * @param cy Signed chunk Y coordinate (must be finite safe integer).
+     * @param width Chunk width in tiles (positive safe integer).
+     * @param height Chunk height in tiles (positive safe integer).
+     * @param source Optional source data to copy (must match length).
+     */
+    constructor(cx: number, cy: number, width: number, height: number, source?: Uint32Array);
+    /** Row-major index for cell (lx, ly) within this chunk. */
+    private _index;
+    /**
+     * Validate local-in-chunk coordinates before access.
+     * @throws If lx or ly is not a finite integer or out of [0, dimension).
+     */
+    private _validateLocalCoord;
+    /** @inheritdoc */
+    getRawAt(lx: number, ly: number): PackedTile;
+    /** @inheritdoc */
+    get empty(): boolean;
+    /** @inheritdoc */
+    get revision(): number;
+    /** @inheritdoc */
+    cloneTiles(): Uint32Array;
+    /**
+     * Package-internal access to the underlying tile storage.
+     * Returns the actual mutable `Uint32Array` — DO NOT USE publicly.
+     *
+     * Provided for the future tilemap renderer (same package) so it can
+     * read chunk data efficiently without a full `cloneTiles()` copy per frame.
+     *
+     * External consumers and other packages MUST NOT call this.
+     * @internal
+     */
+    _getRawStorage(): Uint32Array;
+    /**
+     * Validate a packed tile value before storing.
+     * Accepts any finite integer — `Uint32Array` stores via unsigned 32-bit
+     * truncation (`ToUint32`). Negative values produced by JavaScript's
+     * signed bitwise ops (e.g. when the transform bits set bit 31) are valid.
+     * @throws If the value is NaN, Infinity, or non-integer.
+     * @internal
+     */
+    private _validatePacked;
+    /**
+     * Write a packed tile word at local-in-chunk coordinates.
+     * Returns true if the stored value actually changed.
+     *
+     * Package-internal: only {@link TileLayer} may call this.
+     * @internal
+     */
+    _setRawAt(lx: number, ly: number, packed: PackedTile): boolean;
+    /**
+     * Mark the chunk as needing a GPU rebuild.
+     * Invalidates the empty cache and increments revision.
+     *
+     * Package-internal: for future renderer use only.
+     * @internal
+     */
+    _markDirty(): void;
+    /**
+     * Clear every cell in this chunk. Does not re-allocate storage.
+     * Increments revision if any cell was non-zero.
+     *
+     * Package-internal: only {@link TileLayer} may call this.
+     * @internal
+     */
+    _clear(): void;
+}

package/dist/esm/TileChunk.js

@@ -0,0 +1,192 @@
+import { validateInteger } from './types.js';
+
+/**
+ * A compact, fixed-size chunk of tile data within a layer.
+ *
+ * Storage is a single {@link Uint32Array} of length `width * height`,
+ * laid out row-major. Each cell is a packed tile word (0 = empty).
+ * Chunk coordinates are signed to support future infinite maps.
+ *
+ * The backing array is **private** — external code cannot mutate storage
+ * directly. All mutation must flow through {@link TileLayer} public APIs,
+ * which call the package-internal `_setRawAt` method.
+ *
+ * The chunk tracks a revision counter that increments on every mutation
+ * so the future renderer can detect which chunks need GPU rebuilds.
+ *
+ * @advanced
+ */
+class TileChunk {
+    /** Signed chunk X coordinate. */
+    cx;
+    /** Signed chunk Y coordinate. */
+    cy;
+    /** Width of this chunk in tiles. */
+    width;
+    /** Height of this chunk in tiles. */
+    height;
+    /** Packed tile storage (row-major). Private — never exposed directly. */
+    _tiles;
+    /** Whether every cell in this chunk is empty (0). Lazy-computed. */
+    _empty = null;
+    /** Monotonic revision counter — incremented on every mutation. */
+    _revision = 0;
+    /**
+     * @param cx Signed chunk X coordinate (must be finite safe integer).
+     * @param cy Signed chunk Y coordinate (must be finite safe integer).
+     * @param width Chunk width in tiles (positive safe integer).
+     * @param height Chunk height in tiles (positive safe integer).
+     * @param source Optional source data to copy (must match length).
+     */
+    constructor(cx, cy, width, height, source) {
+        // Validate chunk coordinates as finite safe integers (negative OK).
+        if (!Number.isFinite(cx) || !Number.isInteger(cx) || !Number.isSafeInteger(cx)) {
+            throw new Error(`TileChunk cx must be a finite safe integer (got ${cx}).`);
+        }
+        if (!Number.isFinite(cy) || !Number.isInteger(cy) || !Number.isSafeInteger(cy)) {
+            throw new Error(`TileChunk cy must be a finite safe integer (got ${cy}).`);
+        }
+        if (width <= 0 || height <= 0) {
+            throw new Error(`TileChunk dimensions must be positive (got ${width}x${height}).`);
+        }
+        if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height)) {
+            throw new Error(`TileChunk dimensions must be safe integers (got ${width}x${height}).`);
+        }
+        const size = width * height;
+        if (!Number.isSafeInteger(size)) {
+            throw new Error(`TileChunk size overflow: ${width} * ${height} is not safe.`);
+        }
+        // Guard against TypedArray length limits.
+        if (size > 0xFFFFFFFF) {
+            throw new Error(`TileChunk size ${size} exceeds TypedArray maximum length.`);
+        }
+        this.cx = cx;
+        this.cy = cy;
+        this.width = width;
+        this.height = height;
+        if (source) {
+            if (source.length !== size) {
+                throw new Error(`TileChunk source length ${source.length} != ${size}.`);
+            }
+            // Defensive copy — caller mutation of source array will not affect storage.
+            this._tiles = new Uint32Array(source);
+        }
+        else {
+            this._tiles = new Uint32Array(size);
+        }
+    }
+    /** Row-major index for cell (lx, ly) within this chunk. */
+    _index(lx, ly) {
+        return ly * this.width + lx;
+    }
+    /**
+     * Validate local-in-chunk coordinates before access.
+     * @throws If lx or ly is not a finite integer or out of [0, dimension).
+     */
+    _validateLocalCoord(lx, ly) {
+        validateInteger(lx, 'lx');
+        validateInteger(ly, 'ly');
+        if (lx < 0 || lx >= this.width) {
+            throw new Error(`lx ${lx} out of chunk bounds [0, ${this.width - 1}].`);
+        }
+        if (ly < 0 || ly >= this.height) {
+            throw new Error(`ly ${ly} out of chunk bounds [0, ${this.height - 1}].`);
+        }
+    }
+    // ── Readonly public API (ReadonlyTileChunk) ──────────────────────────
+    /** @inheritdoc */
+    getRawAt(lx, ly) {
+        this._validateLocalCoord(lx, ly);
+        return this._tiles[this._index(lx, ly)];
+    }
+    /** @inheritdoc */
+    get empty() {
+        if (this._empty === null) {
+            this._empty = this._tiles.every(v => v === 0);
+        }
+        return this._empty;
+    }
+    /** @inheritdoc */
+    get revision() {
+        return this._revision;
+    }
+    /** @inheritdoc */
+    cloneTiles() {
+        return new Uint32Array(this._tiles);
+    }
+    // ── Internal mutation (package-private, NOT public API) ──────────────
+    /**
+     * Package-internal access to the underlying tile storage.
+     * Returns the actual mutable `Uint32Array` — DO NOT USE publicly.
+     *
+     * Provided for the future tilemap renderer (same package) so it can
+     * read chunk data efficiently without a full `cloneTiles()` copy per frame.
+     *
+     * External consumers and other packages MUST NOT call this.
+     * @internal
+     */
+    _getRawStorage() {
+        return this._tiles;
+    }
+    /**
+     * Validate a packed tile value before storing.
+     * Accepts any finite integer — `Uint32Array` stores via unsigned 32-bit
+     * truncation (`ToUint32`). Negative values produced by JavaScript's
+     * signed bitwise ops (e.g. when the transform bits set bit 31) are valid.
+     * @throws If the value is NaN, Infinity, or non-integer.
+     * @internal
+     */
+    _validatePacked(packed) {
+        if (typeof packed !== 'number' || !Number.isFinite(packed) || !Number.isInteger(packed)) {
+            throw new Error(`Packed tile must be a finite integer (got ${packed}).`);
+        }
+    }
+    /**
+     * Write a packed tile word at local-in-chunk coordinates.
+     * Returns true if the stored value actually changed.
+     *
+     * Package-internal: only {@link TileLayer} may call this.
+     * @internal
+     */
+    _setRawAt(lx, ly, packed) {
+        this._validateLocalCoord(lx, ly);
+        this._validatePacked(packed);
+        const i = this._index(lx, ly);
+        const prev = this._tiles[i];
+        if (prev === packed)
+            return false;
+        this._tiles[i] = packed;
+        this._revision++;
+        this._empty = null; // invalidate cache
+        return true;
+    }
+    /**
+     * Mark the chunk as needing a GPU rebuild.
+     * Invalidates the empty cache and increments revision.
+     *
+     * Package-internal: for future renderer use only.
+     * @internal
+     */
+    _markDirty() {
+        this._empty = null;
+        this._revision++;
+    }
+    /**
+     * Clear every cell in this chunk. Does not re-allocate storage.
+     * Increments revision if any cell was non-zero.
+     *
+     * Package-internal: only {@link TileLayer} may call this.
+     * @internal
+     */
+    _clear() {
+        const hadContent = this._tiles.some(v => v !== 0);
+        if (!hadContent)
+            return;
+        this._tiles.fill(0);
+        this._revision++;
+        this._empty = true;
+    }
+}
+
+export { TileChunk };
+//# sourceMappingURL=TileChunk.js.map

package/dist/esm/TileChunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TileChunk.js","sources":["../../../src/TileChunk.ts"],"sourcesContent":[null],"names":[],"mappings":";;AA0CA;;;;;;;;;;;;;;;AAeG;MACU,SAAS,CAAA;;AAEJ,IAAA,EAAE;;AAEF,IAAA,EAAE;;AAGF,IAAA,KAAK;;AAEL,IAAA,MAAM;;AAGL,IAAA,MAAM;;IAGf,MAAM,GAAmB,IAAI;;IAG7B,SAAS,GAAG,CAAC;AAErB;;;;;;AAMG;IACH,WAAA,CAAmB,EAAU,EAAE,EAAU,EAAE,KAAa,EAAE,MAAc,EAAE,MAAoB,EAAA;;QAE5F,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,EAAE;AAC9E,YAAA,MAAM,IAAI,KAAK,CAAC,mDAAmD,EAAE,CAAA,EAAA,CAAI,CAAC;QAC5E;QACA,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,EAAE;AAC9E,YAAA,MAAM,IAAI,KAAK,CAAC,mDAAmD,EAAE,CAAA,EAAA,CAAI,CAAC;QAC5E;QAEA,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE;YAC7B,MAAM,IAAI,KAAK,CAAC,CAAA,2CAAA,EAA8C,KAAK,CAAA,CAAA,EAAI,MAAM,CAAA,EAAA,CAAI,CAAC;QACpF;AACA,QAAA,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE;YACjE,MAAM,IAAI,KAAK,CAAC,CAAA,gDAAA,EAAmD,KAAK,CAAA,CAAA,EAAI,MAAM,CAAA,EAAA,CAAI,CAAC;QACzF;AAEA,QAAA,MAAM,IAAI,GAAG,KAAK,GAAG,MAAM;QAC3B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE;YAC/B,MAAM,IAAI,KAAK,CAAC,CAAA,yBAAA,EAA4B,KAAK,CAAA,GAAA,EAAM,MAAM,CAAA,aAAA,CAAe,CAAC;QAC/E;;AAGA,QAAA,IAAI,IAAI,GAAG,UAAU,EAAE;AACrB,YAAA,MAAM,IAAI,KAAK,CAAC,kBAAkB,IAAI,CAAA,mCAAA,CAAqC,CAAC;QAC9E;AAEA,QAAA,IAAI,CAAC,EAAE,GAAG,EAAE;AACZ,QAAA,IAAI,CAAC,EAAE,GAAG,EAAE;AACZ,QAAA,IAAI,CAAC,KAAK,GAAG,KAAK;AAClB,QAAA,IAAI,CAAC,MAAM,GAAG,MAAM;QAEpB,IAAI,MAAM,EAAE;AACV,YAAA,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,EAAE;gBAC1B,MAAM,IAAI,KAAK,CACb,CAAA,wBAAA,EAA2B,MAAM,CAAC,MAAM,CAAA,IAAA,EAAO,IAAI,CAAA,CAAA,CAAG,CACvD;YACH;;YAEA,IAAI,CAAC,MAAM,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC;QACvC;aAAO;YACL,IAAI,CAAC,MAAM,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC;QACrC;IACF;;IAGQ,MAAM,CAAC,EAAU,EAAE,EAAU,EAAA;AACnC,QAAA,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,GAAG,EAAE;IAC7B;AAEA;;;AAGG;IACK,mBAAmB,CAAC,EAAU,EAAE,EAAU,EAAA;AAChD,QAAA,eAAe,CAAC,EAAE,EAAE,IAAI,CAAC;AACzB,QAAA,eAAe,CAAC,EAAE,EAAE,IAAI,CAAC;QACzB,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC,KAAK,EAAE;AAC9B,YAAA,MAAM,IAAI,KAAK,CAAC,CAAA,GAAA,EAAM,EAAE,CAAA,yBAAA,EAA4B,IAAI,CAAC,KAAK,GAAG,CAAC,CAAA,EAAA,CAAI,CAAC;QACzE;QACA,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE;AAC/B,YAAA,MAAM,IAAI,KAAK,CAAC,CAAA,GAAA,EAAM,EAAE,CAAA,yBAAA,EAA4B,IAAI,CAAC,MAAM,GAAG,CAAC,CAAA,EAAA,CAAI,CAAC;QAC1E;IACF;;;IAKO,QAAQ,CAAC,EAAU,EAAE,EAAU,EAAA;AACpC,QAAA,IAAI,CAAC,mBAAmB,CAAC,EAAE,EAAE,EAAE,CAAC;AAChC,QAAA,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACzC;;AAGA,IAAA,IAAW,KAAK,GAAA;AACd,QAAA,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE;AACxB,YAAA,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/C;QACA,OAAO,IAAI,CAAC,MAAM;IACpB;;AAGA,IAAA,IAAW,QAAQ,GAAA;QACjB,OAAO,IAAI,CAAC,SAAS;IACvB;;IAGO,UAAU,GAAA;AACf,QAAA,OAAO,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC;IACrC;;AAIA;;;;;;;;;AASG;IACI,cAAc,GAAA;QACnB,OAAO,IAAI,CAAC,MAAM;IACpB;AAEA;;;;;;;AAOG;AACK,IAAA,eAAe,CAAC,MAAkB,EAAA;QACxC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE;AACvF,YAAA,MAAM,IAAI,KAAK,CAAC,6CAA6C,MAAM,CAAA,EAAA,CAAI,CAAC;QAC1E;IACF;AAEA;;;;;;AAMG;AACI,IAAA,SAAS,CAAC,EAAU,EAAE,EAAU,EAAE,MAAkB,EAAA;AACzD,QAAA,IAAI,CAAC,mBAAmB,CAAC,EAAE,EAAE,EAAE,CAAC;AAChC,QAAA,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC;QAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3B,IAAI,IAAI,KAAK,MAAM;AAAE,YAAA,OAAO,KAAK;AACjC,QAAA,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM;QACvB,IAAI,CAAC,SAAS,EAAE;AAChB,QAAA,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;AACnB,QAAA,OAAO,IAAI;IACb;AAEA;;;;;;AAMG;IACI,UAAU,GAAA;AACf,QAAA,IAAI,CAAC,MAAM,GAAG,IAAI;QAClB,IAAI,CAAC,SAAS,EAAE;IAClB;AAEA;;;;;;AAMG;IACI,MAAM,GAAA;AACX,QAAA,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACjD,QAAA,IAAI,CAAC,UAAU;YAAE;AACjB,QAAA,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACnB,IAAI,CAAC,SAAS,EAAE;AAChB,QAAA,IAAI,CAAC,MAAM,GAAG,IAAI;IACpB;AACD;;;;"}

package/dist/esm/TileChunkNode.d.ts

@@ -0,0 +1,59 @@
+import type { Rectangle } from '@codexo/exojs';
+import { Drawable } from '@codexo/exojs/rendering';
+import type { ChunkPage } from './chunkGeometry';
+import type { ReadonlyTileChunk } from './TileChunk';
+import type { TileSet } from './TileSet';
+/**
+ * A single renderable tile chunk. One `TileChunkNode` is a {@link Drawable}
+ * that owns the batched quad geometry for exactly one {@link ReadonlyTileChunk}
+ * of one {@link import('./TileLayer').TileLayer}, positioned at the chunk's
+ * pixel origin within the owning {@link TileLayerNode}.
+ *
+ * Geometry is built lazily and cached against the source chunk's `revision`:
+ * the renderer reads {@link TileChunkNode.pages} on each visible frame, but a
+ * rebuild only happens when the underlying chunk actually changed. Off-screen
+ * chunks are culled by their accurate {@link getLocalBounds} before `render`
+ * is ever called, so a camera pan rebuilds nothing.
+ *
+ * The node references — but never owns — the runtime chunk, tilesets, and
+ * tileset textures. Destroying it releases only its cached CPU geometry; the
+ * `TileMap`/`TileLayer` data and Loader-owned textures are untouched.
+ *
+ * @internal Package-internal render node; the renderer is registered for this
+ * class. Applications use {@link TileMapNode} / {@link TileLayerNode}.
+ */
+export declare class TileChunkNode extends Drawable {
+    private readonly _chunk;
+    private readonly _tilesets;
+    private readonly _tileWidth;
+    private readonly _tileHeight;
+    private readonly _pixelWidth;
+    private readonly _pixelHeight;
+    private _pages;
+    private _builtRevision;
+    /**
+     * @param chunk          The readonly chunk this node renders.
+     * @param tilesets       The owning layer's tileset array.
+     * @param tileWidth      Map/layer tile cell width in pixels.
+     * @param tileHeight     Map/layer tile cell height in pixels.
+     * @param chunkWidthTiles  The layer's (unclamped) chunk width in tiles, used
+     *                         to compute the chunk's pixel origin. Edge chunks
+     *                         report a smaller `chunk.width`, but always start at
+     *                         `cx * chunkWidthTiles`.
+     * @param chunkHeightTiles The layer's (unclamped) chunk height in tiles.
+     */
+    constructor(chunk: ReadonlyTileChunk, tilesets: readonly TileSet[], tileWidth: number, tileHeight: number, chunkWidthTiles: number, chunkHeightTiles: number);
+    /** The signed chunk coordinates this node renders. */
+    get chunkX(): number;
+    get chunkY(): number;
+    /**
+     * The revision-cached per-tileset page geometry. Rebuilt only when the source
+     * chunk's `revision` advances; otherwise the same arrays are returned.
+     * @internal Read by the per-backend tile chunk renderer.
+     */
+    get pages(): readonly ChunkPage[];
+    /** `true` when the chunk has no drawable tiles (no geometry, no draw calls). */
+    get isEmpty(): boolean;
+    getLocalBounds(): Rectangle;
+    destroy(): void;
+}