@codexo/exojs-tilemap 0.15.2 → 0.16.0

package/dist/esm/TileChunk.js

@@ -1,192 +1,194 @@
-import { validateInteger } from './types.js';
+import { validateInteger } from "./types.js";
 
+//#region src/TileChunk.ts
 /**
- * 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;
-    }
-}
+* 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
+*/
+var TileChunk = class {
+	/** 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;
+	/**
+	* Render-node-owned callbacks notified whenever `_revision` advances.
+	* `TileChunkNode.pages` caches geometry against `revision`, but that cache
+	* is only consulted from `render()` - a call the engine skips entirely for
+	* a content-clean subtree under a `RetainedContainer`. Without
+	* this push, an in-place tile edit after capture would replay stale cached
+	* geometry forever. Package-internal; not part of {@link ReadonlyTileChunk}.
+	*/
+	_dirtyListeners = null;
+	/**
+	* @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) {
+		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.`);
+		if (size > 4294967295) 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}.`);
+			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}].`);
+	}
+	/** @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);
+	}
+	/**
+	* 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);
+		if (this._tiles[i] === packed) return false;
+		this._tiles[i] = packed;
+		this._revision++;
+		this._empty = null;
+		this._notifyDirty();
+		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++;
+		this._notifyDirty();
+	}
+	/**
+	* 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() {
+		if (!this._tiles.some((v) => v !== 0)) return;
+		this._tiles.fill(0);
+		this._revision++;
+		this._empty = true;
+		this._notifyDirty();
+	}
+	/**
+	* Register a callback invoked synchronously whenever this chunk's revision
+	* advances. Multiple listeners are supported (a chunk may back more than one
+	* `TileChunkNode` - e.g. two `TileLayerNode`s over the same `TileLayer`).
+	* Package-internal: called by `TileChunkNode` to push mutations onto the
+	* scene-node content-revision chain (see the `_dirtyListeners` field).
+	* @internal
+	*/
+	_addDirtyListener(listener) {
+		(this._dirtyListeners ??= /* @__PURE__ */ new Set()).add(listener);
+	}
+	/**
+	* Unregister a listener added via {@link _addDirtyListener} (node destroy).
+	* @internal
+	*/
+	_removeDirtyListener(listener) {
+		this._dirtyListeners?.delete(listener);
+	}
+	_notifyDirty() {
+		if (this._dirtyListeners === null) return;
+		for (const listener of this._dirtyListeners) listener();
+	}
+};
 
+//#endregion
 export { TileChunk };
-//# sourceMappingURL=TileChunk.js.map
+//# sourceMappingURL=TileChunk.js.map

package/dist/esm/TileChunk.js.map

@@ -1 +1 @@
-{"version":3,"file":"TileChunk.js","sources":["../../../src/TileChunk.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"TileChunk.js","names":[],"sources":["../../src/TileChunk.ts"],"sourcesContent":["import type { PackedTile } from './types';\nimport { validateInteger } from './types';\n\n/**\n * Public readonly view of a tile chunk.\n *\n * Provides read-only inspection access for iteration, queries, and the\n * future renderer. The underlying storage is never exposed directly.\n *\n * @advanced\n */\nexport interface ReadonlyTileChunk {\n  /** Signed chunk X coordinate. */\n  readonly cx: number;\n  /** Signed chunk Y coordinate. */\n  readonly cy: number;\n  /** Width of this chunk in tiles. */\n  readonly width: number;\n  /** Height of this chunk in tiles. */\n  readonly height: number;\n  /** Whether every cell is empty (all-zero). */\n  readonly empty: boolean;\n  /**\n   * Monotonic revision counter. Increments on every cell mutation\n   * within this chunk. No-ops (writing same value) do NOT increment.\n   */\n  readonly revision: number;\n\n  /**\n   * Read the raw packed tile word at local-in-chunk coordinates.\n   * Returns 0 for empty.\n   * @throws If coordinates are invalid.\n   */\n  getRawAt(lx: number, ly: number): PackedTile;\n\n  /**\n   * Create a defensive copy of the tile data. The caller owns the copy;\n   * mutation of the returned array cannot affect the chunk.\n   */\n  cloneTiles(): Uint32Array;\n}\n\n/**\n * A compact, fixed-size chunk of tile data within a layer.\n *\n * Storage is a single {@link Uint32Array} of length `width * height`,\n * laid out row-major. Each cell is a packed tile word (0 = empty).\n * Chunk coordinates are signed to support future infinite maps.\n *\n * The backing array is **private** - external code cannot mutate storage\n * directly. All mutation must flow through {@link TileLayer} public APIs,\n * which call the package-internal `_setRawAt` method.\n *\n * The chunk tracks a revision counter that increments on every mutation\n * so the future renderer can detect which chunks need GPU rebuilds.\n *\n * @advanced\n */\nexport class TileChunk implements ReadonlyTileChunk {\n  /** Signed chunk X coordinate. */\n  public readonly cx: number;\n  /** Signed chunk Y coordinate. */\n  public readonly cy: number;\n\n  /** Width of this chunk in tiles. */\n  public readonly width: number;\n  /** Height of this chunk in tiles. */\n  public readonly height: number;\n\n  /** Packed tile storage (row-major). Private - never exposed directly. */\n  private readonly _tiles: Uint32Array;\n\n  /** Whether every cell in this chunk is empty (0). Lazy-computed. */\n  private _empty: boolean | null = null;\n\n  /** Monotonic revision counter - incremented on every mutation. */\n  private _revision = 0;\n\n  /**\n   * Render-node-owned callbacks notified whenever `_revision` advances.\n   * `TileChunkNode.pages` caches geometry against `revision`, but that cache\n   * is only consulted from `render()` - a call the engine skips entirely for\n   * a content-clean subtree under a `RetainedContainer`. Without\n   * this push, an in-place tile edit after capture would replay stale cached\n   * geometry forever. Package-internal; not part of {@link ReadonlyTileChunk}.\n   */\n  private _dirtyListeners: Set<() => void> | null = null;\n\n  /**\n   * @param cx Signed chunk X coordinate (must be finite safe integer).\n   * @param cy Signed chunk Y coordinate (must be finite safe integer).\n   * @param width Chunk width in tiles (positive safe integer).\n   * @param height Chunk height in tiles (positive safe integer).\n   * @param source Optional source data to copy (must match length).\n   */\n  public constructor(cx: number, cy: number, width: number, height: number, source?: Uint32Array) {\n    // Validate chunk coordinates as finite safe integers (negative OK).\n    if (!Number.isFinite(cx) || !Number.isInteger(cx) || !Number.isSafeInteger(cx)) {\n      throw new Error(`TileChunk cx must be a finite safe integer (got ${cx}).`);\n    }\n    if (!Number.isFinite(cy) || !Number.isInteger(cy) || !Number.isSafeInteger(cy)) {\n      throw new Error(`TileChunk cy must be a finite safe integer (got ${cy}).`);\n    }\n\n    if (width <= 0 || height <= 0) {\n      throw new Error(`TileChunk dimensions must be positive (got ${width}x${height}).`);\n    }\n    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height)) {\n      throw new Error(`TileChunk dimensions must be safe integers (got ${width}x${height}).`);\n    }\n\n    const size = width * height;\n    if (!Number.isSafeInteger(size)) {\n      throw new Error(`TileChunk size overflow: ${width} * ${height} is not safe.`);\n    }\n\n    // Guard against TypedArray length limits.\n    if (size > 0xffffffff) {\n      throw new Error(`TileChunk size ${size} exceeds TypedArray maximum length.`);\n    }\n\n    this.cx = cx;\n    this.cy = cy;\n    this.width = width;\n    this.height = height;\n\n    if (source) {\n      if (source.length !== size) {\n        throw new Error(`TileChunk source length ${source.length} != ${size}.`);\n      }\n      // Defensive copy - caller mutation of source array will not affect storage.\n      this._tiles = new Uint32Array(source);\n    } else {\n      this._tiles = new Uint32Array(size);\n    }\n  }\n\n  /** Row-major index for cell (lx, ly) within this chunk. */\n  private _index(lx: number, ly: number): number {\n    return ly * this.width + lx;\n  }\n\n  /**\n   * Validate local-in-chunk coordinates before access.\n   * @throws If lx or ly is not a finite integer or out of [0, dimension).\n   */\n  private _validateLocalCoord(lx: number, ly: number): void {\n    validateInteger(lx, 'lx');\n    validateInteger(ly, 'ly');\n    if (lx < 0 || lx >= this.width) {\n      throw new Error(`lx ${lx} out of chunk bounds [0, ${this.width - 1}].`);\n    }\n    if (ly < 0 || ly >= this.height) {\n      throw new Error(`ly ${ly} out of chunk bounds [0, ${this.height - 1}].`);\n    }\n  }\n\n  // ── Readonly public API (ReadonlyTileChunk) ──────────────────────────\n\n  /** @inheritdoc */\n  public getRawAt(lx: number, ly: number): PackedTile {\n    this._validateLocalCoord(lx, ly);\n    return this._tiles[this._index(lx, ly)]!;\n  }\n\n  /** @inheritdoc */\n  public get empty(): boolean {\n    if (this._empty === null) {\n      this._empty = this._tiles.every(v => v === 0);\n    }\n    return this._empty;\n  }\n\n  /** @inheritdoc */\n  public get revision(): number {\n    return this._revision;\n  }\n\n  /** @inheritdoc */\n  public cloneTiles(): Uint32Array {\n    return new Uint32Array(this._tiles);\n  }\n\n  // ── Internal mutation (package-private, NOT public API) ──────────────\n\n  /**\n   * Package-internal access to the underlying tile storage.\n   * Returns the actual mutable `Uint32Array` - DO NOT USE publicly.\n   *\n   * Provided for the future tilemap renderer (same package) so it can\n   * read chunk data efficiently without a full `cloneTiles()` copy per frame.\n   *\n   * External consumers and other packages MUST NOT call this.\n   * @internal\n   */\n  public _getRawStorage(): Uint32Array {\n    return this._tiles;\n  }\n\n  /**\n   * Validate a packed tile value before storing.\n   * Accepts any finite integer - `Uint32Array` stores via unsigned 32-bit\n   * truncation (`ToUint32`). Negative values produced by JavaScript's\n   * signed bitwise ops (e.g. when the transform bits set bit 31) are valid.\n   * @throws If the value is NaN, Infinity, or non-integer.\n   * @internal\n   */\n  private _validatePacked(packed: PackedTile): void {\n    if (typeof packed !== 'number' || !Number.isFinite(packed) || !Number.isInteger(packed)) {\n      throw new Error(`Packed tile must be a finite integer (got ${packed}).`);\n    }\n  }\n\n  /**\n   * Write a packed tile word at local-in-chunk coordinates.\n   * Returns true if the stored value actually changed.\n   *\n   * Package-internal: only {@link TileLayer} may call this.\n   * @internal\n   */\n  public _setRawAt(lx: number, ly: number, packed: PackedTile): boolean {\n    this._validateLocalCoord(lx, ly);\n    this._validatePacked(packed);\n    const i = this._index(lx, ly);\n    const prev = this._tiles[i];\n    if (prev === packed) return false;\n    this._tiles[i] = packed;\n    this._revision++;\n    this._empty = null; // invalidate cache\n    this._notifyDirty();\n    return true;\n  }\n\n  /**\n   * Mark the chunk as needing a GPU rebuild.\n   * Invalidates the empty cache and increments revision.\n   *\n   * Package-internal: for future renderer use only.\n   * @internal\n   */\n  public _markDirty(): void {\n    this._empty = null;\n    this._revision++;\n    this._notifyDirty();\n  }\n\n  /**\n   * Clear every cell in this chunk. Does not re-allocate storage.\n   * Increments revision if any cell was non-zero.\n   *\n   * Package-internal: only {@link TileLayer} may call this.\n   * @internal\n   */\n  public _clear(): void {\n    const hadContent = this._tiles.some(v => v !== 0);\n    if (!hadContent) return;\n    this._tiles.fill(0);\n    this._revision++;\n    this._empty = true;\n    this._notifyDirty();\n  }\n\n  /**\n   * Register a callback invoked synchronously whenever this chunk's revision\n   * advances. Multiple listeners are supported (a chunk may back more than one\n   * `TileChunkNode` - e.g. two `TileLayerNode`s over the same `TileLayer`).\n   * Package-internal: called by `TileChunkNode` to push mutations onto the\n   * scene-node content-revision chain (see the `_dirtyListeners` field).\n   * @internal\n   */\n  public _addDirtyListener(listener: () => void): void {\n    (this._dirtyListeners ??= new Set()).add(listener);\n  }\n\n  /**\n   * Unregister a listener added via {@link _addDirtyListener} (node destroy).\n   * @internal\n   */\n  public _removeDirtyListener(listener: () => void): void {\n    this._dirtyListeners?.delete(listener);\n  }\n\n  private _notifyDirty(): void {\n    if (this._dirtyListeners === null) return;\n    for (const listener of this._dirtyListeners) {\n      listener();\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/esm/TileChunkNode.d.ts

@@ -1,4 +1,4 @@
-import type { Rectangle } from '@codexo/exojs';
+import type { ReadonlyRectangle } from '@codexo/exojs';
 import { Drawable } from '@codexo/exojs/renderer-sdk';
 import type { ChunkPage } from './chunkGeometry';
 import type { ReadonlyTileChunk } from './TileChunk';
@@ -15,7 +15,7 @@ import type { TileSet } from './TileSet';
  * 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
+ * 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.
  *
@@ -31,6 +31,15 @@ export declare class TileChunkNode extends Drawable {
     private readonly _pixelHeight;
     private _pages;
     private _builtRevision;
+    /**
+     * Bound once so `TileChunk._addDirtyListener`/`_removeDirtyListener` add and
+     * remove the SAME function reference. Pushes the chunk's revision bump onto
+     * this node's own content revision (see `TileChunk._dirtyListeners`) so a
+     * `RetainedContainer` ancestor - which skips walking a content-clean
+     * subtree entirely - observes the mutation and re-collects instead of
+     * replaying stale cached geometry.
+     */
+    private readonly _onChunkDirty;
     /**
      * @param chunk          The readonly chunk this node renders.
      * @param tilesets       The owning layer's tileset array.
@@ -54,6 +63,12 @@ export declare class TileChunkNode extends Drawable {
     get pages(): readonly ChunkPage[];
     /** `true` when the chunk has no drawable tiles (no geometry, no draw calls). */
     get isEmpty(): boolean;
-    getLocalBounds(): Rectangle;
+    /**
+     * Recomputed lazily on read, so it writes `_localBounds` directly rather than
+     * going through `_setLocalBounds`: an invalidating write inside a getter
+     * would re-dirty the node on every read.
+     */
+    getLocalBounds(): ReadonlyRectangle;
     destroy(): void;
 }
+//# sourceMappingURL=TileChunkNode.d.ts.map

package/dist/esm/TileChunkNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TileChunkNode.d.ts","sourceRoot":"","sources":["../../src/TileChunkNode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,aAAc,SAAQ,QAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,cAAc,CAAM;IAE5B;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAE5B;IAEF;;;;;;;;;;OAUG;gBAED,KAAK,EAAE,iBAAiB,EACxB,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,gBAAgB,EAAE,MAAM;IAoB1B,sDAAsD;IACtD,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED;;;;OAIG;IACH,IAAW,KAAK,IAAI,SAAS,SAAS,EAAE,CAOvC;IAED,gFAAgF;IAChF,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;;;OAIG;IACa,cAAc,IAAI,iBAAiB;IAInC,OAAO,IAAI,IAAI;CAUhC"}