@codexo/exojs-tilemap 0.15.3 → 0.16.0

package/dist/esm/TileMapNode.d.ts

@@ -1,6 +1,7 @@
-import type { Rectangle } from '@codexo/exojs';
+import type { ReadonlyRectangle } from '@codexo/exojs';
 import { Container } from '@codexo/exojs';
-import type { PixelSnapMode } from '@codexo/exojs/renderer-sdk';
+import { PixelSnapMode } from '@codexo/exojs/renderer-sdk';
+import { ImageLayerNode } from './ImageLayerNode';
 import { TileLayerNode } from './TileLayerNode';
 import type { TileMap } from './TileMap';
 /**
@@ -16,17 +17,19 @@ export interface TileMapNodeOptions {
 }
 /**
  * A convenience scene node that renders a whole {@link TileMap} as a
- * {@link Container} of one {@link TileLayerNode} per tile layer, in map layer
- * order (back-to-front by document order).
+ * {@link Container} of one node per renderable layer - a {@link TileLayerNode}
+ * per tile layer and an {@link ImageLayerNode} per image layer, interleaved
+ * back-to-front by the map's combined document order
+ * ({@link import('./TileMap').TileMap.renderableLayers}).
  *
- * `TileMapNode` owns **only** its layer nodes — never application actors. Use
+ * `TileMapNode` owns **only** its layer nodes - never application actors. Use
  * it for the simple, non-interleaved case (no actors between layers); for
- * actor interleaving, place individual `TileLayerNode`s into your own scene
- * graph instead.
+ * actor interleaving, place individual `TileLayerNode`s / `ImageLayerNode`s
+ * into your own scene graph instead (see `TileMapView`).
  *
- * The node references — but never owns — the {@link TileMap}: destroying the
+ * The node references - but never owns - the {@link TileMap}: destroying the
  * node frees its layer/chunk nodes and their cached GPU geometry, while the
- * `TileMap` data and Loader-owned tileset textures survive (free them via
+ * `TileMap` data and Loader-owned textures survive (free them via
  * `TileMap.destroy()` / `Loader.destroy()` respectively).
  *
  * Layers added to or removed from the map after construction are reflected only
@@ -47,25 +50,38 @@ export declare class TileMapNode extends Container {
      * chunk node, current and rebuilt). Snaps tile chunk origins to the active
      * render target's device-pixel grid for crisp tiles; with integer tile pitch
      * the grid stays exact and adjacent chunks/layers cannot drift apart. Purely
-     * visual — tile data, layer offsets, chunk revisions, and culling are
+     * visual - tile data, layer offsets, chunk revisions, and culling are
      * unchanged. Setting the current value is a no-op; an invalid value throws and
      * leaves the prior mode unchanged.
      *
-     * @default 'none'
+     * @default PixelSnapMode.None
      * @stable
      */
     get pixelSnapMode(): PixelSnapMode;
     set pixelSnapMode(mode: PixelSnapMode);
-    /** The layer render nodes, in map layer order. */
-    get layerNodes(): readonly TileLayerNode[];
-    /** Find the layer node rendering the named layer, or `undefined`. */
-    getLayerNode(name: string): TileLayerNode | undefined;
     /**
-     * Rebuild the layer-node children from the map's current layers. Call after
-     * layers are structurally added to or removed from the map.
+     * The layer render nodes - tile and image alike - in the map's combined
+     * document order.
+     */
+    get layerNodes(): ReadonlyArray<TileLayerNode | ImageLayerNode>;
+    /**
+     * Find the layer node rendering the named layer (tile or image; first match
+     * in document order), or `undefined`.
+     */
+    getLayerNode(name: string): TileLayerNode | ImageLayerNode | undefined;
+    /**
+     * Rebuild the layer-node children from the map's current renderable layers.
+     * Call after tile or image layers are structurally added to or removed from
+     * the map.
      */
     refreshLayers(): this;
-    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;
     private _buildLayerNodes;
 }
+//# sourceMappingURL=TileMapNode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TileMapNode.d.ts","sourceRoot":"","sources":["../../src/TileMapNode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAG3D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,WAAY,SAAQ,SAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6C;IACzE,OAAO,CAAC,cAAc,CAAqC;gBAExC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB;IAa7D,yCAAyC;IACzC,IAAW,GAAG,IAAI,OAAO,CAExB;IAED;;;;;;;;;;;OAWG;IACH,IAAW,aAAa,IAAI,aAAa,CAExC;IAED,IAAW,aAAa,CAAC,IAAI,EAAE,aAAa,EAW3C;IAED;;;OAGG;IACH,IAAW,UAAU,IAAI,aAAa,CAAC,aAAa,GAAG,cAAc,CAAC,CAErE;IAED;;;OAGG;IACI,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,SAAS;IAI7E;;;;OAIG;IACI,aAAa,IAAI,IAAI;IAe5B;;;;OAIG;IACa,cAAc,IAAI,iBAAiB;IAgBnC,OAAO,IAAI,IAAI;IAY/B,OAAO,CAAC,gBAAgB;CAYzB"}

package/dist/esm/TileMapNode.js

@@ -1,113 +1,126 @@
-import { Container } from '@codexo/exojs';
-import { assertPixelSnapMode } from './pixelSnap.js';
-import { TileLayerNode } from './TileLayerNode.js';
+import { ImageLayer } from "./ImageLayer.js";
+import { assertPixelSnapMode } from "./pixelSnap.js";
+import { ImageLayerNode } from "./ImageLayerNode.js";
+import { aggregateChildLocalBounds } from "./nodeBounds.js";
+import { TileLayerNode } from "./TileLayerNode.js";
+import { PixelSnapMode } from "@codexo/exojs/renderer-sdk";
+import { Container } from "@codexo/exojs";
 
+//#region src/TileMapNode.ts
 /**
- * A convenience scene node that renders a whole {@link TileMap} as a
- * {@link Container} of one {@link TileLayerNode} per tile layer, in map layer
- * order (back-to-front by document order).
- *
- * `TileMapNode` owns **only** its layer nodes — never application actors. Use
- * it for the simple, non-interleaved case (no actors between layers); for
- * actor interleaving, place individual `TileLayerNode`s into your own scene
- * graph instead.
- *
- * The node references — but never owns — the {@link TileMap}: destroying the
- * node frees its layer/chunk nodes and their cached GPU geometry, while the
- * `TileMap` data and Loader-owned tileset textures survive (free them via
- * `TileMap.destroy()` / `Loader.destroy()` respectively).
- *
- * Layers added to or removed from the map after construction are reflected only
- * after {@link TileMapNode.refreshLayers}.
- *
- * @advanced
- */
-class TileMapNode extends Container {
-    _map;
-    _cullChunks;
-    _layerNodes = [];
-    _pixelSnapMode = 'none';
-    constructor(map, options) {
-        super();
-        this._map = map;
-        this._cullChunks = options?.cullable ?? true;
-        this._buildLayerNodes();
-    }
-    /** The runtime map this node renders. */
-    get map() {
-        return this._map;
-    }
-    /**
-     * Render-only pixel-snap mode applied to every layer (and forwarded to every
-     * chunk node, current and rebuilt). Snaps tile chunk origins to the active
-     * render target's device-pixel grid for crisp tiles; with integer tile pitch
-     * the grid stays exact and adjacent chunks/layers cannot drift apart. Purely
-     * visual — tile data, layer offsets, chunk revisions, and culling are
-     * unchanged. Setting the current value is a no-op; an invalid value throws and
-     * leaves the prior mode unchanged.
-     *
-     * @default 'none'
-     * @stable
-     */
-    get pixelSnapMode() {
-        return this._pixelSnapMode;
-    }
-    set pixelSnapMode(mode) {
-        if (mode === this._pixelSnapMode) {
-            return;
-        }
-        assertPixelSnapMode(mode);
-        this._pixelSnapMode = mode;
-        for (const node of this._layerNodes) {
-            node.pixelSnapMode = mode;
-        }
-    }
-    /** The layer render nodes, in map layer order. */
-    get layerNodes() {
-        return this._layerNodes;
-    }
-    /** Find the layer node rendering the named layer, or `undefined`. */
-    getLayerNode(name) {
-        return this._layerNodes.find(node => node.layer.name === name);
-    }
-    /**
-     * Rebuild the layer-node children from the map's current layers. Call after
-     * layers are structurally added to or removed from the map.
-     */
-    refreshLayers() {
-        const previous = [...this._layerNodes];
-        this.removeChildren();
-        this._layerNodes.length = 0;
-        for (const node of previous) {
-            node.destroy();
-        }
-        this._buildLayerNodes();
-        return this;
-    }
-    getLocalBounds() {
-        const bounds = super.getLocalBounds();
-        bounds.set(0, 0, this._map.pixelWidth, this._map.pixelHeight);
-        return bounds;
-    }
-    destroy() {
-        const layerNodes = [...this._layerNodes];
-        this._layerNodes.length = 0;
-        super.destroy();
-        for (const node of layerNodes) {
-            node.destroy();
-        }
-    }
-    _buildLayerNodes() {
-        for (const layer of this._map.layers) {
-            const node = new TileLayerNode(layer, { cullable: this._cullChunks });
-            if (this._pixelSnapMode !== 'none') {
-                node.pixelSnapMode = this._pixelSnapMode;
-            }
-            this._layerNodes.push(node);
-            this.addChild(node);
-        }
-    }
-}
+* A convenience scene node that renders a whole {@link TileMap} as a
+* {@link Container} of one node per renderable layer - a {@link TileLayerNode}
+* per tile layer and an {@link ImageLayerNode} per image layer, interleaved
+* back-to-front by the map's combined document order
+* ({@link import('./TileMap').TileMap.renderableLayers}).
+*
+* `TileMapNode` owns **only** its layer nodes - never application actors. Use
+* it for the simple, non-interleaved case (no actors between layers); for
+* actor interleaving, place individual `TileLayerNode`s / `ImageLayerNode`s
+* into your own scene graph instead (see `TileMapView`).
+*
+* The node references - but never owns - the {@link TileMap}: destroying the
+* node frees its layer/chunk nodes and their cached GPU geometry, while the
+* `TileMap` data and Loader-owned textures survive (free them via
+* `TileMap.destroy()` / `Loader.destroy()` respectively).
+*
+* Layers added to or removed from the map after construction are reflected only
+* after {@link TileMapNode.refreshLayers}.
+*
+* @advanced
+*/
+var TileMapNode = class extends Container {
+	_map;
+	_cullChunks;
+	_layerNodes = [];
+	_pixelSnapMode = PixelSnapMode.None;
+	constructor(map, options) {
+		super();
+		this._map = map;
+		this._cullChunks = options?.cullable ?? true;
+		this._buildLayerNodes();
+		if (!this._map.bounded) this.cullable = false;
+	}
+	/** The runtime map this node renders. */
+	get map() {
+		return this._map;
+	}
+	/**
+	* Render-only pixel-snap mode applied to every layer (and forwarded to every
+	* chunk node, current and rebuilt). Snaps tile chunk origins to the active
+	* render target's device-pixel grid for crisp tiles; with integer tile pitch
+	* the grid stays exact and adjacent chunks/layers cannot drift apart. Purely
+	* visual - tile data, layer offsets, chunk revisions, and culling are
+	* unchanged. Setting the current value is a no-op; an invalid value throws and
+	* leaves the prior mode unchanged.
+	*
+	* @default PixelSnapMode.None
+	* @stable
+	*/
+	get pixelSnapMode() {
+		return this._pixelSnapMode;
+	}
+	set pixelSnapMode(mode) {
+		if (mode === this._pixelSnapMode) return;
+		assertPixelSnapMode(mode);
+		this._pixelSnapMode = mode;
+		for (const node of this._layerNodes) node.pixelSnapMode = mode;
+	}
+	/**
+	* The layer render nodes - tile and image alike - in the map's combined
+	* document order.
+	*/
+	get layerNodes() {
+		return this._layerNodes;
+	}
+	/**
+	* Find the layer node rendering the named layer (tile or image; first match
+	* in document order), or `undefined`.
+	*/
+	getLayerNode(name) {
+		return this._layerNodes.find((node) => node.layer.name === name);
+	}
+	/**
+	* Rebuild the layer-node children from the map's current renderable layers.
+	* Call after tile or image layers are structurally added to or removed from
+	* the map.
+	*/
+	refreshLayers() {
+		const previous = [...this._layerNodes];
+		this.removeChildren();
+		this._layerNodes.length = 0;
+		for (const node of previous) node.destroy();
+		this._buildLayerNodes();
+		return this;
+	}
+	/**
+	* 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() {
+		const bounds = this._localBounds;
+		const { pixelHeight, pixelWidth } = this._map;
+		if (pixelWidth !== void 0 && pixelHeight !== void 0) bounds.set(0, 0, pixelWidth, pixelHeight);
+		else if (this._layerNodes.length > 0) aggregateChildLocalBounds(this._layerNodes, bounds);
+		return bounds;
+	}
+	destroy() {
+		const layerNodes = [...this._layerNodes];
+		this._layerNodes.length = 0;
+		super.destroy();
+		for (const node of layerNodes) node.destroy();
+	}
+	_buildLayerNodes() {
+		for (const layer of this._map.renderableLayers) {
+			const node = layer instanceof ImageLayer ? new ImageLayerNode(layer) : new TileLayerNode(layer, { cullable: this._cullChunks });
+			if (this._pixelSnapMode !== PixelSnapMode.None) node.pixelSnapMode = this._pixelSnapMode;
+			this._layerNodes.push(node);
+			this.addChild(node);
+		}
+	}
+};
 
+//#endregion
 export { TileMapNode };
-//# sourceMappingURL=TileMapNode.js.map
+//# sourceMappingURL=TileMapNode.js.map

package/dist/esm/TileMapNode.js.map

@@ -1 +1 @@
-{"version":3,"file":"TileMapNode.js","sources":["../../../src/TileMapNode.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAoBA;;;;;;;;;;;;;;;;;;;AAmBG;AACG,MAAO,WAAY,SAAQ,SAAS,CAAA;AACvB,IAAA,IAAI;AACJ,IAAA,WAAW;IACX,WAAW,GAAoB,EAAE;IAC1C,cAAc,GAAkB,MAAM;IAE9C,WAAA,CAAmB,GAAY,EAAE,OAA4B,EAAA;AAC3D,QAAA,KAAK,EAAE;AAEP,QAAA,IAAI,CAAC,IAAI,GAAG,GAAG;QACf,IAAI,CAAC,WAAW,GAAG,OAAO,EAAE,QAAQ,IAAI,IAAI;QAE5C,IAAI,CAAC,gBAAgB,EAAE;IACzB;;AAGA,IAAA,IAAW,GAAG,GAAA;QACZ,OAAO,IAAI,CAAC,IAAI;IAClB;AAEA;;;;;;;;;;;AAWG;AACH,IAAA,IAAW,aAAa,GAAA;QACtB,OAAO,IAAI,CAAC,cAAc;IAC5B;IAEA,IAAW,aAAa,CAAC,IAAmB,EAAA;AAC1C,QAAA,IAAI,IAAI,KAAK,IAAI,CAAC,cAAc,EAAE;YAChC;QACF;QAEA,mBAAmB,CAAC,IAAI,CAAC;AACzB,QAAA,IAAI,CAAC,cAAc,GAAG,IAAI;AAE1B,QAAA,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,WAAW,EAAE;AACnC,YAAA,IAAI,CAAC,aAAa,GAAG,IAAI;QAC3B;IACF;;AAGA,IAAA,IAAW,UAAU,GAAA;QACnB,OAAO,IAAI,CAAC,WAAW;IACzB;;AAGO,IAAA,YAAY,CAAC,IAAY,EAAA;AAC9B,QAAA,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;IAChE;AAEA;;;AAGG;IACI,aAAa,GAAA;QAClB,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC;QAEtC,IAAI,CAAC,cAAc,EAAE;AACrB,QAAA,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;AAE3B,QAAA,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE;YAC3B,IAAI,CAAC,OAAO,EAAE;QAChB;QAEA,IAAI,CAAC,gBAAgB,EAAE;AAEvB,QAAA,OAAO,IAAI;IACb;IAEgB,cAAc,GAAA;AAC5B,QAAA,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,EAAE;AAErC,QAAA,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC;AAE7D,QAAA,OAAO,MAAM;IACf;IAEgB,OAAO,GAAA;QACrB,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC;AAExC,QAAA,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;QAE3B,KAAK,CAAC,OAAO,EAAE;AAEf,QAAA,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE;YAC7B,IAAI,CAAC,OAAO,EAAE;QAChB;IACF;IAEQ,gBAAgB,GAAA;QACtB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;AACpC,YAAA,MAAM,IAAI,GAAG,IAAI,aAAa,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;AAErE,YAAA,IAAI,IAAI,CAAC,cAAc,KAAK,MAAM,EAAE;AAClC,gBAAA,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,cAAc;YAC1C;AAEA,YAAA,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;AAC3B,YAAA,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QACrB;IACF;AACD;;;;"}
+{"version":3,"file":"TileMapNode.js","names":[],"sources":["../../src/TileMapNode.ts"],"sourcesContent":["import type { ReadonlyRectangle } from '@codexo/exojs';\nimport { Container } from '@codexo/exojs';\nimport { PixelSnapMode } from '@codexo/exojs/renderer-sdk';\n\nimport { ImageLayer } from './ImageLayer';\nimport { ImageLayerNode } from './ImageLayerNode';\nimport { aggregateChildLocalBounds } from './nodeBounds';\nimport { assertPixelSnapMode } from './pixelSnap';\nimport { TileLayerNode } from './TileLayerNode';\nimport type { TileMap } from './TileMap';\n\n/**\n * Options for a {@link TileMapNode}.\n * @advanced\n */\nexport interface TileMapNodeOptions {\n  /**\n   * Whether the map's chunk nodes participate in per-chunk view culling.\n   * Forwarded to every {@link TileLayerNode}. Defaults to `true`.\n   */\n  readonly cullable?: boolean;\n}\n\n/**\n * A convenience scene node that renders a whole {@link TileMap} as a\n * {@link Container} of one node per renderable layer - a {@link TileLayerNode}\n * per tile layer and an {@link ImageLayerNode} per image layer, interleaved\n * back-to-front by the map's combined document order\n * ({@link import('./TileMap').TileMap.renderableLayers}).\n *\n * `TileMapNode` owns **only** its layer nodes - never application actors. Use\n * it for the simple, non-interleaved case (no actors between layers); for\n * actor interleaving, place individual `TileLayerNode`s / `ImageLayerNode`s\n * into your own scene graph instead (see `TileMapView`).\n *\n * The node references - but never owns - the {@link TileMap}: destroying the\n * node frees its layer/chunk nodes and their cached GPU geometry, while the\n * `TileMap` data and Loader-owned textures survive (free them via\n * `TileMap.destroy()` / `Loader.destroy()` respectively).\n *\n * Layers added to or removed from the map after construction are reflected only\n * after {@link TileMapNode.refreshLayers}.\n *\n * @advanced\n */\nexport class TileMapNode extends Container {\n  private readonly _map: TileMap;\n  private readonly _cullChunks: boolean;\n  private readonly _layerNodes: Array<TileLayerNode | ImageLayerNode> = [];\n  private _pixelSnapMode: PixelSnapMode = PixelSnapMode.None;\n\n  public constructor(map: TileMap, options?: TileMapNodeOptions) {\n    super();\n\n    this._map = map;\n    this._cullChunks = options?.cullable ?? true;\n\n    this._buildLayerNodes();\n\n    if (!this._map.bounded) {\n      this.cullable = false;\n    }\n  }\n\n  /** The runtime map this node renders. */\n  public get map(): TileMap {\n    return this._map;\n  }\n\n  /**\n   * Render-only pixel-snap mode applied to every layer (and forwarded to every\n   * chunk node, current and rebuilt). Snaps tile chunk origins to the active\n   * render target's device-pixel grid for crisp tiles; with integer tile pitch\n   * the grid stays exact and adjacent chunks/layers cannot drift apart. Purely\n   * visual - tile data, layer offsets, chunk revisions, and culling are\n   * unchanged. Setting the current value is a no-op; an invalid value throws and\n   * leaves the prior mode unchanged.\n   *\n   * @default PixelSnapMode.None\n   * @stable\n   */\n  public get pixelSnapMode(): PixelSnapMode {\n    return this._pixelSnapMode;\n  }\n\n  public set pixelSnapMode(mode: PixelSnapMode) {\n    if (mode === this._pixelSnapMode) {\n      return;\n    }\n\n    assertPixelSnapMode(mode);\n    this._pixelSnapMode = mode;\n\n    for (const node of this._layerNodes) {\n      node.pixelSnapMode = mode;\n    }\n  }\n\n  /**\n   * The layer render nodes - tile and image alike - in the map's combined\n   * document order.\n   */\n  public get layerNodes(): ReadonlyArray<TileLayerNode | ImageLayerNode> {\n    return this._layerNodes;\n  }\n\n  /**\n   * Find the layer node rendering the named layer (tile or image; first match\n   * in document order), or `undefined`.\n   */\n  public getLayerNode(name: string): TileLayerNode | ImageLayerNode | undefined {\n    return this._layerNodes.find(node => node.layer.name === name);\n  }\n\n  /**\n   * Rebuild the layer-node children from the map's current renderable layers.\n   * Call after tile or image layers are structurally added to or removed from\n   * the map.\n   */\n  public refreshLayers(): this {\n    const previous = [...this._layerNodes];\n\n    this.removeChildren();\n    this._layerNodes.length = 0;\n\n    for (const node of previous) {\n      node.destroy();\n    }\n\n    this._buildLayerNodes();\n\n    return this;\n  }\n\n  /**\n   * Recomputed lazily on read, so it writes `_localBounds` directly rather than\n   * going through `_setLocalBounds`: an invalidating write inside a getter\n   * would re-dirty the node on every read.\n   */\n  public override getLocalBounds(): ReadonlyRectangle {\n    const bounds = this._localBounds;\n\n    // Reading the pixel extents directly (rather than gating on `bounded`)\n    // is what narrows them to numbers - `bounded` is a plain boolean getter.\n    const { pixelHeight, pixelWidth } = this._map;\n\n    if (pixelWidth !== undefined && pixelHeight !== undefined) {\n      bounds.set(0, 0, pixelWidth, pixelHeight);\n    } else if (this._layerNodes.length > 0) {\n      aggregateChildLocalBounds(this._layerNodes, bounds);\n    }\n\n    return bounds;\n  }\n\n  public override destroy(): void {\n    const layerNodes = [...this._layerNodes];\n\n    this._layerNodes.length = 0;\n\n    super.destroy();\n\n    for (const node of layerNodes) {\n      node.destroy();\n    }\n  }\n\n  private _buildLayerNodes(): void {\n    for (const layer of this._map.renderableLayers) {\n      const node = layer instanceof ImageLayer ? new ImageLayerNode(layer) : new TileLayerNode(layer, { cullable: this._cullChunks });\n\n      if (this._pixelSnapMode !== PixelSnapMode.None) {\n        node.pixelSnapMode = this._pixelSnapMode;\n      }\n\n      this._layerNodes.push(node);\n      this.addChild(node);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,IAAa,cAAb,cAAiC,UAAU;CACzC,AAAiB;CACjB,AAAiB;CACjB,AAAiB,cAAqD,CAAC;CACvE,AAAQ,iBAAgC,cAAc;CAEtD,AAAO,YAAY,KAAc,SAA8B;EAC7D,MAAM;EAEN,KAAK,OAAO;EACZ,KAAK,cAAc,SAAS,YAAY;EAExC,KAAK,iBAAiB;EAEtB,IAAI,CAAC,KAAK,KAAK,SACb,KAAK,WAAW;CAEpB;;CAGA,IAAW,MAAe;EACxB,OAAO,KAAK;CACd;;;;;;;;;;;;;CAcA,IAAW,gBAA+B;EACxC,OAAO,KAAK;CACd;CAEA,IAAW,cAAc,MAAqB;EAC5C,IAAI,SAAS,KAAK,gBAChB;EAGF,oBAAoB,IAAI;EACxB,KAAK,iBAAiB;EAEtB,KAAK,MAAM,QAAQ,KAAK,aACtB,KAAK,gBAAgB;CAEzB;;;;;CAMA,IAAW,aAA4D;EACrE,OAAO,KAAK;CACd;;;;;CAMA,AAAO,aAAa,MAA0D;EAC5E,OAAO,KAAK,YAAY,MAAK,SAAQ,KAAK,MAAM,SAAS,IAAI;CAC/D;;;;;;CAOA,AAAO,gBAAsB;EAC3B,MAAM,WAAW,CAAC,GAAG,KAAK,WAAW;EAErC,KAAK,eAAe;EACpB,KAAK,YAAY,SAAS;EAE1B,KAAK,MAAM,QAAQ,UACjB,KAAK,QAAQ;EAGf,KAAK,iBAAiB;EAEtB,OAAO;CACT;;;;;;CAOA,AAAgB,iBAAoC;EAClD,MAAM,SAAS,KAAK;EAIpB,MAAM,EAAE,aAAa,eAAe,KAAK;EAEzC,IAAI,eAAe,UAAa,gBAAgB,QAC9C,OAAO,IAAI,GAAG,GAAG,YAAY,WAAW;OACnC,IAAI,KAAK,YAAY,SAAS,GACnC,0BAA0B,KAAK,aAAa,MAAM;EAGpD,OAAO;CACT;CAEA,AAAgB,UAAgB;EAC9B,MAAM,aAAa,CAAC,GAAG,KAAK,WAAW;EAEvC,KAAK,YAAY,SAAS;EAE1B,MAAM,QAAQ;EAEd,KAAK,MAAM,QAAQ,YACjB,KAAK,QAAQ;CAEjB;CAEA,AAAQ,mBAAyB;EAC/B,KAAK,MAAM,SAAS,KAAK,KAAK,kBAAkB;GAC9C,MAAM,OAAO,iBAAiB,aAAa,IAAI,eAAe,KAAK,IAAI,IAAI,cAAc,OAAO,EAAE,UAAU,KAAK,YAAY,CAAC;GAE9H,IAAI,KAAK,mBAAmB,cAAc,MACxC,KAAK,gBAAgB,KAAK;GAG5B,KAAK,YAAY,KAAK,IAAI;GAC1B,KAAK,SAAS,IAAI;EACpB;CACF;AACF"}

package/dist/esm/TileMapView.d.ts

@@ -1,20 +1,26 @@
-import type { PixelSnapMode } from '@codexo/exojs/renderer-sdk';
+import { PixelSnapMode } from '@codexo/exojs/renderer-sdk';
+import { ImageLayerNode } from './ImageLayerNode';
 import { TileLayerNode } from './TileLayerNode';
 import type { TileMap } from './TileMap';
 import { TileMapBand } from './TileMapBand';
 /**
  * A layer selector inside a {@link TileMapBandDefinition}: either a stable
- * layer **id** (`number`) or a **unique** layer **name** (`string`). Names that
- * are shared by more than one layer are rejected as ambiguous — reference such
- * layers by id.
+ * layer **id** (`number`) or a **unique** layer **name** (`string`). Selectors
+ * resolve across the map's tile **and** image layers. Names that are shared by
+ * more than one layer (of either kind) are rejected as ambiguous - reference
+ * such layers by id. An id shared by a tile layer and an image layer (possible
+ * only in fallback-ordered maps, which never validated cross-kind uniqueness)
+ * is equally ambiguous - reference such layers by a unique name.
  * @advanced
  */
 export type TileLayerSelector = number | string;
 /**
- * The layers composing one band, by id or unique name, in any order. Rendering
- * order always follows map document order regardless of the order listed here —
- * a definition *selects* layers, it never reorders them. The band's name is the
- * key it is registered under in {@link TileMapViewOptions.bands}.
+ * The layers composing one band, by id or unique name, in any order. Tile and
+ * image layers may be freely mixed. Rendering order always follows the map's
+ * combined document order ({@link import('./TileMap').TileMap.renderableLayers})
+ * regardless of the order listed here - a definition *selects* layers, it never
+ * reorders them. The band's name is the key it is registered under in
+ * {@link TileMapViewOptions.bands}.
  * @advanced
  */
 export type TileMapBandDefinition = readonly TileLayerSelector[];
@@ -25,15 +31,16 @@ export type TileMapBandDefinition = readonly TileLayerSelector[];
 export interface TileMapViewOptions {
     /**
      * Named bands, keyed by band name (keys are unique, so duplicate band names
-     * cannot occur). Each value lists the layers that compose the band. Layers
-     * not listed in any band remain reachable through
-     * {@link TileMapView.getLayerNodeById} and friends and are owned directly by
-     * the view (no implicit fallback band). The definition is copied and frozen;
-     * mutating the caller's object afterwards does not change band assignments.
+     * cannot occur). Each value lists the layers that compose the band - tile
+     * and image layers alike. Layers not listed in any band remain reachable
+     * through {@link TileMapView.getLayerNodeById} and friends and are owned
+     * directly by the view (no implicit fallback band). The definition is copied
+     * and frozen; mutating the caller's object afterwards does not change band
+     * assignments.
      *
      * @throws (at construction) on an unknown layer id, an unknown or ambiguous
-     *   layer name, a layer listed twice within one band, or a layer assigned to
-     *   more than one band.
+     *   layer name, a cross-kind ambiguous layer id, a layer listed twice within
+     *   one band, or a layer assigned to more than one band.
      */
     readonly bands?: Readonly<Record<string, TileMapBandDefinition>>;
     /**
@@ -49,7 +56,7 @@ export interface TileMapViewOptions {
  * A view produces exactly one canonical {@link TileLayerNode} per map layer
  * (stable identity, map document order) and, optionally, named {@link TileMapBand}s
  * grouping subsets of those nodes. The application parents the bands / layer
- * nodes wherever it wants — typically as siblings of its own actor containers:
+ * nodes wherever it wants - typically as siblings of its own actor containers:
  *
  * ```ts
  * const view = map.createView({ bands: { ground: ['background', 'ground'], roof: ['roofs'] } });
@@ -59,7 +66,7 @@ export interface TileMapViewOptions {
  * ```
  *
  * **Actors are application-owned siblings.** A `TileMapView` never adopts or
- * destroys actors. The view is a helper, not a scene node — it does not own the
+ * destroys actors. The view is a helper, not a scene node - it does not own the
  * world container, the {@link TileMap}, the {@link TileLayer}s, or tileset
  * textures.
  *
@@ -69,16 +76,28 @@ export interface TileMapViewOptions {
  * (detaching them from their application parents) but leaves actors, the map,
  * its layers, and Loader-owned textures untouched. There is no map-replacement
  * mutation API: to swap maps, destroy the old view, construct a new one, and
- * re-parent its bands — the actor tree is never involved.
+ * re-parent its bands - the actor tree is never involved.
+ *
+ * **Image layers.** A view also produces exactly one canonical
+ * {@link ImageLayerNode} per {@link TileMap.imageLayers} entry (stable identity,
+ * map document order), reachable through {@link imageLayerNodes},
+ * {@link getImageLayerNodeById}, and {@link getImageLayerNodeByName}. Image
+ * layers are selectable in {@link TileMapViewOptions.bands} exactly like tile
+ * layers: a band member list may mix both kinds, and the band stacks its
+ * members by the map's combined document order
+ * ({@link import('./TileMap').TileMap.renderableLayers}). A banded image node
+ * is owned by its band; an unbanded one is owned by the view directly, and the
+ * application parents it wherever the image belongs in draw order - the same
+ * way actors are interleaved.
  *
  * @advanced
  */
 export declare class TileMapView {
     private readonly _map;
     private readonly _cullable;
-    /** All canonical layer nodes, in map document order. */
+    /** All canonical tile-layer nodes, in map document order. */
     private readonly _layerNodes;
-    /** Layer id → its canonical layer node. */
+    /** Tile layer id → its canonical layer node. */
     private readonly _layerNodeById;
     /** Bands in definition (insertion) order. */
     private readonly _bands;
@@ -88,8 +107,12 @@ export declare class TileMapView {
     private readonly _bandDefs;
     /** Layer node → its owning band (absent = view-owned / unbanded). */
     private readonly _nodeBand;
-    /** Unbanded layer nodes owned directly by the view, in map document order. */
+    /** Unbanded tile-layer nodes owned directly by the view, in map document order. */
     private readonly _directLayerNodes;
+    /** All canonical image layer nodes, in map document order. */
+    private readonly _imageLayerNodes;
+    /** Image layer id → its canonical image layer node. */
+    private readonly _imageLayerNodeById;
     private _destroyed;
     private _pixelSnapMode;
     /**
@@ -101,7 +124,7 @@ export declare class TileMapView {
     constructor(map: TileMap, options?: TileMapViewOptions);
     /** The runtime map this view composes. Referenced, never owned. */
     get map(): TileMap;
-    /** All canonical layer nodes, one per map layer, in map document order. */
+    /** All canonical tile-layer nodes, one per map tile layer, in map document order. */
     get layers(): readonly TileLayerNode[];
     /** The bands, in definition (insertion) order. */
     get bands(): readonly TileMapBand[];
@@ -112,30 +135,47 @@ export declare class TileMapView {
      * forwarded to every chunk drawable, current and rebuilt by
      * {@link refreshLayers}). Snaps tile chunk origins to the active render
      * target's device-pixel grid for crisp tiles; with integer tile pitch the grid
-     * stays exact and adjacent chunks cannot drift apart. Purely visual — tile
+     * stays exact and adjacent chunks cannot drift apart. Purely visual - tile
      * data, layer offsets, chunk revisions, and culling are unchanged. Setting the
      * current value is a no-op; an invalid value throws and leaves the prior mode
      * unchanged.
      *
-     * @default 'none'
+     * @default PixelSnapMode.None
      * @stable
      */
     get pixelSnapMode(): PixelSnapMode;
     set pixelSnapMode(mode: PixelSnapMode);
     /**
-     * The canonical layer node for the layer with the given **id**, or
-     * `undefined`. Ids are authoritative and unique — this is the unambiguous
-     * lookup. The returned node may be reparented into the caller's own
-     * containers; the view still tracks it for refresh and destruction.
+     * The canonical layer node for the **tile** layer with the given **id**, or
+     * `undefined`. Tile ids are authoritative and unique - this is the
+     * unambiguous lookup. The returned node may be reparented into the caller's
+     * own containers; the view still tracks it for refresh and destruction.
      */
     getLayerNodeById(id: number): TileLayerNode | undefined;
     /**
-     * Every canonical layer node whose layer has the given **name**, in map
+     * Every canonical tile-layer node whose layer has the given **name**, in map
      * document order. Layer names are not guaranteed unique, so this returns an
      * array (empty when no layer matches). Prefer {@link getLayerNodeById} when
      * you have the id.
      */
     getLayerNodesByName(name: string): readonly TileLayerNode[];
+    /** All canonical image layer nodes, one per map image layer, in map document order. */
+    get imageLayerNodes(): readonly ImageLayerNode[];
+    /**
+     * The canonical image layer node for the image layer with the given **id**,
+     * or `undefined`. Ids are authoritative and unique - this is the unambiguous
+     * lookup. The returned node may be reparented into the caller's own
+     * containers; the view still tracks it for refresh and destruction.
+     */
+    getImageLayerNodeById(id: number): ImageLayerNode | undefined;
+    /**
+     * The canonical image layer node for the image layer with the given
+     * **name**, or `undefined` if no image layer has that name. Prefer
+     * {@link getImageLayerNodeById} when you have the id.
+     * @throws If more than one image layer shares that name (reference such
+     *         layers by id instead).
+     */
+    getImageLayerNodeByName(name: string): ImageLayerNode | undefined;
     /**
      * The band registered under `name`.
      * @throws If no band with that name was defined.
@@ -144,17 +184,19 @@ export declare class TileMapView {
     /** Whether a band with the given name was defined. */
     hasBand(name: string): boolean;
     /**
-     * Rebuild the view after **structural** map changes (layers added to or
-     * removed from the map). Ordinary tile edits and chunk creation/removal do
-     * NOT need this — those are handled by chunk revisions and
-     * {@link TileLayerNode.refresh} respectively.
+     * Rebuild the view after **structural** map changes (tile or image layers
+     * added to or removed from the map). Ordinary tile edits and chunk
+     * creation/removal do NOT need this - those are handled by chunk revisions
+     * and {@link TileLayerNode.refresh} respectively.
      *
-     * - Removed layers: their generated layer node is detached and destroyed.
-     * - Unchanged layers: keep their existing layer node (stable identity).
-     * - Added layers: a new layer node is created and assigned to the first band
-     *   whose definition selects it (by id, or by a currently-unambiguous name),
-     *   otherwise owned directly by the view.
-     * - Every band's children are re-ordered to map document order.
+     * - Removed layers (tile or image): their generated node is detached and
+     *   destroyed.
+     * - Unchanged layers: keep their existing node (stable identity).
+     * - Added layers (tile or image): a new node is created and assigned to the
+     *   first band whose definition selects it (by a currently-unambiguous id or
+     *   name), otherwise owned directly by the view.
+     * - Every band's children are re-ordered to the map's combined document
+     *   order ({@link import('./TileMap').TileMap.renderableLayers}).
      *
      * Application actors are never touched, and bands keep their placement in the
      * application scene graph.
@@ -163,20 +205,39 @@ export declare class TileMapView {
      */
     refreshLayers(): this;
     /**
-     * Destroy the view: every band and generated layer node is destroyed (and
-     * detached from its application parent), freeing cached chunk geometry.
-     * Idempotent. Application actors, sibling content, the {@link TileMap}, its
-     * {@link TileLayer}s, and Loader-owned tileset textures all survive.
+     * Destroy the view: every band, generated tile-layer node, and generated
+     * {@link ImageLayerNode} is destroyed (and detached from its application
+     * parent), freeing cached chunk geometry. Banded nodes are destroyed by
+     * their band; unbanded ones by the view directly. Idempotent. Application
+     * actors, sibling content, the {@link TileMap}, its {@link TileLayer}s and
+     * image layers, and Loader-owned textures all survive.
      */
     destroy(): void;
     /** Resolve one band definition into a {@link TileMapBand} and record it. */
     private _defineBand;
-    /** Resolve a single selector to a layer id, throwing on unknown/ambiguous. */
+    /**
+     * Resolve a single selector to a tile or image layer instance, throwing on
+     * unknown/ambiguous. Instances (not ids) disambiguate fallback-ordered maps
+     * in which a tile layer and an image layer share an id.
+     */
     private _resolveSelector;
+    /** The canonical node for a tile or image layer instance, if one exists. */
+    private _nodeFor;
     /** Assign a freshly created node to the first band that selects its layer. */
     private _assignNewNode;
-    /** Whether a band definition selects the given layer (unambiguously by name). */
+    /**
+     * Whether a band definition selects the given layer - only by a selector
+     * that is currently unambiguous (a unique name, or an id not shared across
+     * kinds), mirroring {@link _resolveSelector}'s construction-time rules.
+     */
     private _definitionSelects;
-    /** Detach + destroy a node, dropping it from band membership and registries. */
-    private _removeNode;
+    /** Whether an id currently belongs to both a tile layer and an image layer. */
+    private _isCrossKindId;
+    /** Detach + destroy a tile node, dropping it from bands and registries. */
+    private _removeTileNode;
+    /** Detach + destroy an image node, dropping it from bands and registries. */
+    private _removeImageNode;
+    /** Release a node from its band, or from the view's direct-ownership list. */
+    private _releaseFromOwner;
 }
+//# sourceMappingURL=TileMapView.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TileMapView.d.ts","sourceRoot":"","sources":["../../src/TileMapView.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAG3D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG,SAAS,iBAAiB,EAAE,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC;IACjE;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IAEpC,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuB;IACnD,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoC;IAEnE,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,wBAAwB;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAC9D,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0D;IACpF,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAuB;IAEzD,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAwB;IACzD,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqC;IAEzE,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAqC;IAE3D;;;;;OAKG;gBACgB,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB;IA+B7D,mEAAmE;IACnE,IAAW,GAAG,IAAI,OAAO,CAExB;IAED,qFAAqF;IACrF,IAAW,MAAM,IAAI,SAAS,aAAa,EAAE,CAE5C;IAED,kDAAkD;IAClD,IAAW,KAAK,IAAI,SAAS,WAAW,EAAE,CAEzC;IAED,4CAA4C;IAC5C,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED;;;;;;;;;;;;OAYG;IACH,IAAW,aAAa,IAAI,aAAa,CAExC;IAED,IAAW,aAAa,CAAC,IAAI,EAAE,aAAa,EAe3C;IAED;;;;;OAKG;IACI,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI9D;;;;;OAKG;IACI,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE;IAIlE,uFAAuF;IACvF,IAAW,eAAe,IAAI,SAAS,cAAc,EAAE,CAEtD;IAED;;;;;OAKG;IACI,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIpE;;;;;;OAMG;IACI,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAcxE;;;OAGG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW;IAYtC,sDAAsD;IAC/C,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIrC;;;;;;;;;;;;;;;;;;;OAmBG;IACI,aAAa,IAAI,IAAI;IAgG5B;;;;;;;OAOG;IACI,OAAO,IAAI,IAAI;IAsCtB,4EAA4E;IAC5E,OAAO,CAAC,WAAW;IAwCnB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAuCxB,4EAA4E;IAC5E,OAAO,CAAC,QAAQ;IAUhB,8EAA8E;IAC9E,OAAO,CAAC,cAAc;IAatB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAmB1B,+EAA+E;IAC/E,OAAO,CAAC,cAAc;IAItB,2EAA2E;IAC3E,OAAO,CAAC,eAAe;IAevB,6EAA6E;IAC7E,OAAO,CAAC,gBAAgB;IAkBxB,8EAA8E;IAC9E,OAAO,CAAC,iBAAiB;CAc1B"}