@codexo/exojs-tilemap 0.15.2 → 0.16.0

package/dist/esm/TileMap.js

@@ -1,361 +1,405 @@
-import { validatePositiveInteger } from './types.js';
-import { TileMapView } from './TileMapView.js';
+import { validatePairedDimensions, validatePositiveInteger } from "./types.js";
+import { TileMapView } from "./TileMapView.js";
 
+//#region src/TileMap.ts
 /**
- * A generic, format-independent tile map.
- *
- * Owns a finite grid of {@link TileLayer}s and a shared set of {@link TileSet}s.
- * Tile data is stored in compact chunked arrays — no per-tile heap objects.
- *
- * The map does NOT own tileset textures (those are Loader-owned) and does
- * NOT own SceneNode children — see {@link import('./TileMapNode').TileMapNode},
- * which owns those.
- *
- * Multiple tilesets are supported: each cell stores a packed tileset index
- * and local tile ID, so different tilesets may have different tile dimensions.
- *
- * @advanced
- */
-class TileMap {
-    /** Map name (debug). */
-    name;
-    /** Map width in tiles. */
-    width;
-    /** Map height in tiles. */
-    height;
-    /** Tile width in pixels. */
-    tileWidth;
-    /** Tile height in pixels. */
-    tileHeight;
-    /** Pixel width. */
-    get pixelWidth() { return this.width * this.tileWidth; }
-    /** Pixel height. */
-    get pixelHeight() { return this.height * this.tileHeight; }
-    /** Default chunk width for layers. */
-    chunkWidth;
-    /** Default chunk height for layers. */
-    chunkHeight;
-    /** Map class/type string (Tiled `class`; may be empty). */
-    class;
-    /** Map background colour as `0xRRGGBB`, or `null`. Informational. */
-    backgroundColor;
-    /** Tile draw order (Tiled `renderorder`). Informational. */
-    renderOrder;
-    /** Map-level properties (immutable). */
-    properties;
-    _tilesets;
-    _layers = [];
-    _layerById = new Map();
-    _objectLayers = [];
-    _imageLayers = [];
-    _revision = 0;
-    _destroyed = false;
-    /**
-     * @throws When dimensions or other options are invalid.
-     */
-    constructor(options) {
-        validatePositiveInteger(options.width, 'map.width');
-        validatePositiveInteger(options.height, 'map.height');
-        validatePositiveInteger(options.tileWidth, 'map.tileWidth');
-        validatePositiveInteger(options.tileHeight, 'map.tileHeight');
-        const chunkWidth = options.chunkWidth ?? 32;
-        const chunkHeight = options.chunkHeight ?? 32;
-        validatePositiveInteger(chunkWidth, 'chunkWidth');
-        validatePositiveInteger(chunkHeight, 'chunkHeight');
-        this.name = options.name ?? 'TileMap';
-        this.width = options.width;
-        this.height = options.height;
-        this.tileWidth = options.tileWidth;
-        this.tileHeight = options.tileHeight;
-        this.chunkWidth = chunkWidth;
-        this.chunkHeight = chunkHeight;
-        this.class = options.class ?? '';
-        this.backgroundColor = options.backgroundColor ?? null;
-        this.renderOrder = options.renderOrder ?? 'right-down';
-        this._tilesets = options.tilesets ? [...options.tilesets] : [];
-        this.properties = options.properties
-            ? Object.freeze({ ...options.properties })
-            : Object.freeze({});
-        if (options.layers) {
-            for (const layer of options.layers) {
-                this._addLayer(layer);
-            }
-        }
-        if (options.objectLayers) {
-            this._objectLayers.push(...options.objectLayers);
-        }
-        if (options.imageLayers) {
-            this._imageLayers.push(...options.imageLayers);
-        }
-    }
-    // ── Tilesets ──────────────────────────────────────────────────────────
-    /** Immutable list of tilesets available to this map. */
-    get tilesets() {
-        return this._tilesets;
-    }
-    /**
-     * Add a tileset. Tilesets must have unique names.
-     * @throws If a tileset with the same name already exists, or the map is destroyed.
-     */
-    addTileset(tileset) {
-        this._checkDestroyed();
-        if (this._tilesets.some(ts => ts.name === tileset.name)) {
-            throw new Error(`Tileset "${tileset.name}" already exists in map "${this.name}".`);
-        }
-        this._tilesets.push(tileset);
-        this._revision++;
-    }
-    /**
-     * Get a tileset by name, or undefined.
-     */
-    getTileset(name) {
-        return this._tilesets.find(ts => ts.name === name);
-    }
-    // ── Layers ────────────────────────────────────────────────────────────
-    /** Immutable snapshot of layers (ordered). */
-    get layers() {
-        return this._layers;
-    }
-    _addLayer(layer) {
-        if (this._layerById.has(layer.id)) {
-            throw new Error(`Layer ID ${layer.id} already exists in map "${this.name}".`);
-        }
-        this._layerById.set(layer.id, layer);
-        this._layers.push(layer);
-    }
-    /**
-     * Add a layer after construction.
-     * @throws If a layer with the same ID already exists.
-     */
-    addLayer(layer) {
-        this._checkDestroyed();
-        this._addLayer(layer);
-        this._revision++;
-    }
-    /**
-     * Get a layer by ID.
-     */
-    getLayerById(id) {
-        return this._layerById.get(id);
-    }
-    /**
-     * Get a layer by name. Returns the first match in insertion order.
-     */
-    getLayerByName(name) {
-        return this._layers.find(l => l.name === name);
-    }
-    /**
-     * Get a tile layer by name. Convenience alias for {@link getLayerByName}.
-     */
-    getTileLayer(name) {
-        return this.getLayerByName(name);
-    }
-    /**
-     * Remove a layer by ID. The layer is destroyed.
-     * @returns true if the layer was found and removed.
-     */
-    removeLayer(id) {
-        this._checkDestroyed();
-        const layer = this._layerById.get(id);
-        if (!layer)
-            return false;
-        this._layers.splice(this._layers.indexOf(layer), 1);
-        this._layerById.delete(id);
-        layer.destroy();
-        this._revision++;
-        return true;
-    }
-    // ── Object layers (data-only) ─────────────────────────────────────────
-    /** Immutable snapshot of object layers (insertion order). */
-    get objectLayers() {
-        return this._objectLayers;
-    }
-    /**
-     * Add an object layer after construction.
-     * @throws If the map is destroyed.
-     */
-    addObjectLayer(layer) {
-        this._checkDestroyed();
-        this._objectLayers.push(layer);
-        this._revision++;
-    }
-    /**
-     * Get an object layer by name (first match in insertion order), or undefined.
-     *
-     * Supply an {@link ObjectSchema} type argument `S` to obtain a typed view of
-     * the layer — `getObjectLayer<LevelObjects>('Entities')` returns an
-     * `ObjectLayer<LevelObjects>` whose {@link ObjectLayer.byType} / {@link
-     * ObjectLayer.where} accessors narrow `properties`. The schema is a static
-     * developer promise only; no runtime validation is performed and the call
-     * remains fully back-compatible when omitted.
-     */
-    getObjectLayer(name) {
-        return this._objectLayers.find(layer => layer.name === name);
-    }
-    /**
-     * Get an object layer by ID.
-     *
-     * Supply an {@link ObjectSchema} type argument `S` to obtain a typed view of
-     * the layer, as with {@link getObjectLayer}.
-     */
-    getObjectLayerById(id) {
-        return this._objectLayers.find(layer => layer.id === id);
-    }
-    /**
-     * Remove an object layer by ID.
-     * @returns true if the layer was found and removed.
-     */
-    removeObjectLayer(id) {
-        this._checkDestroyed();
-        const index = this._objectLayers.findIndex(layer => layer.id === id);
-        if (index === -1)
-            return false;
-        this._objectLayers.splice(index, 1);
-        this._revision++;
-        return true;
-    }
-    // ── Image layers (data-only) ──────────────────────────────────────────
-    /** Immutable snapshot of image layers (insertion order). */
-    get imageLayers() {
-        return this._imageLayers;
-    }
-    /**
-     * Get an image layer by name (first match in insertion order), or undefined.
-     */
-    getImageLayer(name) {
-        return this._imageLayers.find(layer => layer.name === name);
-    }
-    /**
-     * Get an image layer by ID.
-     */
-    getImageLayerById(id) {
-        return this._imageLayers.find(layer => layer.id === id);
-    }
-    /**
-     * Remove an image layer by ID.
-     * @returns true if the layer was found and removed.
-     */
-    removeImageLayer(id) {
-        this._checkDestroyed();
-        const index = this._imageLayers.findIndex(layer => layer.id === id);
-        if (index === -1)
-            return false;
-        this._imageLayers.splice(index, 1);
-        this._revision++;
-        return true;
-    }
-    // ── Scene composition ─────────────────────────────────────────────────
-    /**
-     * Create a new {@link TileMapView} that groups this map's layers into
-     * independently placeable band / layer scene nodes for interleaving
-     * application actors between tile layers.
-     *
-     * Each call returns a fresh, independent view — the map does **not** cache a
-     * single global view, so multiple coexisting views of the same map are
-     * allowed. The view references this map but never owns it: destroying the
-     * view frees only its generated layer/band nodes — never the map, its layers,
-     * tileset textures, or any application actors.
-     *
-     * @advanced
-     */
-    createView(options) {
-        return new TileMapView(this, options);
-    }
-    // ── Queries ───────────────────────────────────────────────────────────
-    /**
-     * Get a resolved tile from a given layer at tile coordinates.
-     * Convenience for `map.getLayerById(id)?.getTileAt(tx, ty)`.
-     * Returns null for an empty cell, out-of-bounds, or missing layer.
-     */
-    getTileAt(layerId, tx, ty) {
-        const layer = this._layerById.get(layerId);
-        if (!layer)
-            return null;
-        return layer.getTileAt(tx, ty);
-    }
-    /**
-     * Set a tile on a given layer at tile coordinates.
-     * Convenience for `map.getLayerById(id)?.setTileAt(tx, ty, tile)`.
-     * @throws If the layer does not exist, coordinates are out of bounds,
-     *         or the tile reference is invalid.
-     */
-    setTileAt(layerId, tx, ty, tile) {
-        const layer = this._layerById.get(layerId);
-        if (!layer)
-            throw new Error(`Layer ${layerId} not found in map "${this.name}".`);
-        layer.setTileAt(tx, ty, tile);
-    }
-    /**
-     * Clear a tile on a given layer at tile coordinates.
-     * Convenience for `map.getLayerById(id)?.clearTileAt(tx, ty)`.
-     * @throws If the layer does not exist or coordinates are out of bounds.
-     */
-    clearTileAt(layerId, tx, ty) {
-        const layer = this._layerById.get(layerId);
-        if (!layer)
-            throw new Error(`Layer ${layerId} not found in map "${this.name}".`);
-        layer.clearTileAt(tx, ty);
-    }
-    // ── Coordinate conversion (base layer) ────────────────────────────────
-    /**
-     * Convert a tile coordinate to the pixel position of its top-left corner
-     * in map-local space (ignoring layer offsets).
-     */
-    tileToPixel(tx, ty) {
-        return {
-            x: tx * this.tileWidth,
-            y: ty * this.tileHeight,
-        };
-    }
-    /**
-     * Convert a pixel position in map-local space to the tile coordinate
-     * that contains it. Uses `floor`. May return coordinates outside map bounds.
-     */
-    pixelToTile(px, py) {
-        return {
-            tx: Math.floor(px / this.tileWidth),
-            ty: Math.floor(py / this.tileHeight),
-        };
-    }
-    // ── Revision / lifecycle ──────────────────────────────────────────────
-    /**
-     * Monotonic map revision counter. Increments on structural changes only
-     * (add/remove layer, add tileset). Cell mutations are tracked per-chunk
-     * and per-layer; the renderer reads chunk-level revisions directly.
-     * @advanced
-     */
-    get revision() {
-        return this._revision;
-    }
-    /** Whether the map has been destroyed. */
-    get destroyed() {
-        return this._destroyed;
-    }
-    _checkDestroyed() {
-        if (this._destroyed) {
-            throw new Error(`TileMap "${this.name}" has been destroyed.`);
-        }
-    }
-    /**
-     * Destroy the map and all owned layers and chunk storage.
-     *
-     * Is idempotent. Does NOT destroy tileset textures (Loader-owned) or
-     * any SceneNodes (those do not exist yet in this slice).
-     */
-    destroy() {
-        if (this._destroyed)
-            return;
-        this._destroyed = true;
-        for (const layer of this._layers) {
-            layer.destroy();
-        }
-        this._layers.length = 0;
-        this._layerById.clear();
-        this._objectLayers.length = 0;
-        this._imageLayers.length = 0;
-        this._tilesets.length = 0;
-    }
-}
+* A generic, format-independent tile map.
+*
+* Owns a finite grid of {@link TileLayer}s and a shared set of {@link TileSet}s.
+* Tile data is stored in compact chunked arrays - no per-tile heap objects.
+*
+* The map does NOT own tileset textures (those are Loader-owned) and does
+* NOT own SceneNode children - see {@link import('./TileMapNode').TileMapNode},
+* which owns those.
+*
+* Multiple tilesets are supported: each cell stores a packed tileset index
+* and local tile ID, so different tilesets may have different tile dimensions.
+*
+* @advanced
+*/
+var TileMap = class {
+	/** Map name (debug). */
+	name;
+	/** Map width in tiles, or `undefined` if unbounded. */
+	width;
+	/** Map height in tiles, or `undefined` if unbounded. */
+	height;
+	/** Tile width in pixels. */
+	tileWidth;
+	/** Tile height in pixels. */
+	tileHeight;
+	/** Pixel width, or `undefined` if unbounded. */
+	get pixelWidth() {
+		return this.width === void 0 ? void 0 : this.width * this.tileWidth;
+	}
+	/** Pixel height, or `undefined` if unbounded. */
+	get pixelHeight() {
+		return this.height === void 0 ? void 0 : this.height * this.tileHeight;
+	}
+	/** `true` if this map has a fixed width/height; `false` if unbounded. */
+	get bounded() {
+		return this.width !== void 0 && this.height !== void 0;
+	}
+	/** Default chunk width for layers. */
+	chunkWidth;
+	/** Default chunk height for layers. */
+	chunkHeight;
+	/** Map class/type string (Tiled `class`; may be empty). */
+	class;
+	/** Map background colour as `0xRRGGBB`, or `null`. Informational. */
+	backgroundColor;
+	/** Tile draw order (Tiled `renderorder`). Informational. */
+	renderOrder;
+	/** Map-level properties (immutable). */
+	properties;
+	_tilesets;
+	_layers = [];
+	_layerById = /* @__PURE__ */ new Map();
+	_objectLayers = [];
+	_imageLayers = [];
+	_documentOrder = [];
+	_revision = 0;
+	_destroyed = false;
+	/**
+	* @throws When dimensions or other options are invalid.
+	*/
+	constructor(options) {
+		validatePairedDimensions(options.width, options.height, "TileMap", "map");
+		validatePositiveInteger(options.tileWidth, "map.tileWidth");
+		validatePositiveInteger(options.tileHeight, "map.tileHeight");
+		const chunkWidth = options.chunkWidth ?? 32;
+		const chunkHeight = options.chunkHeight ?? 32;
+		validatePositiveInteger(chunkWidth, "chunkWidth");
+		validatePositiveInteger(chunkHeight, "chunkHeight");
+		this.name = options.name ?? "TileMap";
+		this.width = options.width;
+		this.height = options.height;
+		this.tileWidth = options.tileWidth;
+		this.tileHeight = options.tileHeight;
+		this.chunkWidth = chunkWidth;
+		this.chunkHeight = chunkHeight;
+		this.class = options.class ?? "";
+		this.backgroundColor = options.backgroundColor ?? null;
+		this.renderOrder = options.renderOrder ?? "right-down";
+		this._tilesets = options.tilesets ? [...options.tilesets] : [];
+		this.properties = options.properties ? Object.freeze({ ...options.properties }) : Object.freeze({});
+		if (options.layers) for (const layer of options.layers) this._addLayer(layer);
+		if (options.objectLayers) this._objectLayers.push(...options.objectLayers);
+		if (options.imageLayers) for (const layer of options.imageLayers) this._addImageLayer(layer);
+		this._documentOrder.push(...this._buildDocumentOrder(options.documentOrder));
+	}
+	/**
+	* Validate an explicit `documentOrder` option against current tile/image
+	* layer membership and resolve it to layer instances, or compute the
+	* fallback order (tile layers in insertion order, then image layers) when
+	* omitted. The order stores instance references - not ids - so a
+	* cross-kind id collision in a fallback map can never resolve to the
+	* wrong layer.
+	* @throws Per the validation rules documented on {@link
+	*         TileMapOptions.documentOrder}.
+	*/
+	_buildDocumentOrder(documentOrder) {
+		if (!documentOrder) return [...this._layers, ...this._imageLayers];
+		const tileIds = new Set(this._layers.map((l) => l.id));
+		const imageIds = new Set(this._imageLayers.map((l) => l.id));
+		for (const id of tileIds) if (imageIds.has(id)) throw new Error(`Layer ID ${id} exists as both a tile layer and an image layer in map "${this.name}"; documentOrder cannot disambiguate them.`);
+		const seen = /* @__PURE__ */ new Set();
+		for (const id of documentOrder) {
+			if (!tileIds.has(id) && !imageIds.has(id)) throw new Error(`documentOrder references unknown layer ID ${id} in map "${this.name}".`);
+			if (seen.has(id)) throw new Error(`documentOrder lists layer ID ${id} more than once in map "${this.name}".`);
+			seen.add(id);
+		}
+		const totalLayers = tileIds.size + imageIds.size;
+		if (seen.size !== totalLayers) {
+			for (const id of [...tileIds, ...imageIds]) if (!seen.has(id)) throw new Error(`documentOrder is missing layer ID ${id} in map "${this.name}".`);
+		}
+		const instanceCount = this._layers.length + this._imageLayers.length;
+		if (documentOrder.length !== instanceCount) throw new Error(`documentOrder has ${documentOrder.length} entries but map "${this.name}" has ${instanceCount} tile/image layer instances; check for a duplicate image-layer ID.`);
+		return documentOrder.map((id) => {
+			const layer = this._layerById.get(id) ?? this._imageLayers.find((imageLayer) => imageLayer.id === id);
+			if (!layer) throw new Error(`documentOrder references layer id ${id}, but map "${this.name}" has no tile or image layer with that id.`);
+			return layer;
+		});
+	}
+	/** Immutable list of tilesets available to this map. */
+	get tilesets() {
+		return this._tilesets;
+	}
+	/**
+	* Add a tileset. Tilesets must have unique names.
+	* @throws If a tileset with the same name already exists, or the map is destroyed.
+	*/
+	addTileset(tileset) {
+		this._checkDestroyed();
+		if (this._tilesets.some((ts) => ts.name === tileset.name)) throw new Error(`Tileset "${tileset.name}" already exists in map "${this.name}".`);
+		this._tilesets.push(tileset);
+		this._revision++;
+	}
+	/**
+	* Get a tileset by name, or undefined.
+	*/
+	getTileset(name) {
+		return this._tilesets.find((ts) => ts.name === name);
+	}
+	/** Immutable snapshot of layers (ordered). */
+	get layers() {
+		return this._layers;
+	}
+	_addLayer(layer) {
+		if (this._layerById.has(layer.id)) throw new Error(`Layer ID ${layer.id} already exists in map "${this.name}".`);
+		this._layerById.set(layer.id, layer);
+		this._layers.push(layer);
+	}
+	/**
+	* Add a layer after construction. Appended to the end of {@link
+	* renderableLayers}'s document order.
+	* @throws If a layer with the same ID already exists.
+	*/
+	addLayer(layer) {
+		this._checkDestroyed();
+		this._addLayer(layer);
+		this._documentOrder.push(layer);
+		this._revision++;
+	}
+	/**
+	* Get a tile layer by ID.
+	*/
+	getTileLayerById(id) {
+		return this._layerById.get(id);
+	}
+	/**
+	* Get a tile layer by name. Returns the first match in insertion order.
+	*/
+	getTileLayer(name) {
+		return this._layers.find((l) => l.name === name);
+	}
+	/**
+	* Remove a layer by ID. The layer is destroyed and spliced out of {@link
+	* renderableLayers}'s document order.
+	* @returns true if the layer was found and removed.
+	*/
+	removeLayer(id) {
+		this._checkDestroyed();
+		const layer = this._layerById.get(id);
+		if (!layer) return false;
+		this._layers.splice(this._layers.indexOf(layer), 1);
+		this._layerById.delete(id);
+		const orderIndex = this._documentOrder.indexOf(layer);
+		if (orderIndex !== -1) this._documentOrder.splice(orderIndex, 1);
+		layer.destroy();
+		this._revision++;
+		return true;
+	}
+	/** Immutable snapshot of object layers (insertion order). */
+	get objectLayers() {
+		return this._objectLayers;
+	}
+	/**
+	* Add an object layer after construction.
+	* @throws If the map is destroyed.
+	*/
+	addObjectLayer(layer) {
+		this._checkDestroyed();
+		this._objectLayers.push(layer);
+		this._revision++;
+	}
+	/**
+	* Get an object layer by name (first match in insertion order), or undefined.
+	*
+	* Supply an {@link ObjectSchema} type argument `S` to obtain a typed view of
+	* the layer - `getObjectLayer<LevelObjects>('Entities')` returns an
+	* `ObjectLayer<LevelObjects>` whose {@link ObjectLayer.byType} / {@link
+	* ObjectLayer.where} accessors narrow `properties`. The schema is a static
+	* developer promise only; no runtime validation is performed and the call
+	* remains fully back-compatible when omitted.
+	*/
+	getObjectLayer(name) {
+		return this._objectLayers.find((layer) => layer.name === name);
+	}
+	/**
+	* Get an object layer by ID.
+	*
+	* Supply an {@link ObjectSchema} type argument `S` to obtain a typed view of
+	* the layer, as with {@link getObjectLayer}.
+	*/
+	getObjectLayerById(id) {
+		return this._objectLayers.find((layer) => layer.id === id);
+	}
+	/**
+	* Remove an object layer by ID.
+	* @returns true if the layer was found and removed.
+	*/
+	removeObjectLayer(id) {
+		this._checkDestroyed();
+		const index = this._objectLayers.findIndex((layer) => layer.id === id);
+		if (index === -1) return false;
+		this._objectLayers.splice(index, 1);
+		this._revision++;
+		return true;
+	}
+	/** Immutable snapshot of image layers (insertion order). */
+	get imageLayers() {
+		return this._imageLayers;
+	}
+	/**
+	* Add an image layer after construction. Appended to both {@link
+	* imageLayers} and the end of {@link renderableLayers}'s document order.
+	* @throws If an image layer with the same ID already exists. An ID shared
+	*   with a *tile* layer is permitted - the two kinds keep separate ID
+	*   spaces, and all internal bookkeeping is instance-based.
+	*/
+	addImageLayer(layer) {
+		this._checkDestroyed();
+		this._addImageLayer(layer);
+		this._documentOrder.push(layer);
+		this._revision++;
+	}
+	/** Shared by the constructor and {@link addImageLayer}: enforce ID uniqueness within the image-layer kind. */
+	_addImageLayer(layer) {
+		if (this._imageLayers.some((existing) => existing.id === layer.id)) throw new Error(`Image layer ID ${layer.id} already exists in map "${this.name}".`);
+		this._imageLayers.push(layer);
+	}
+	/**
+	* Get an image layer by name (first match in insertion order), or undefined.
+	*/
+	getImageLayer(name) {
+		return this._imageLayers.find((layer) => layer.name === name);
+	}
+	/**
+	* Get an image layer by ID.
+	*/
+	getImageLayerById(id) {
+		return this._imageLayers.find((layer) => layer.id === id);
+	}
+	/**
+	* Remove an image layer by ID. Spliced out of {@link renderableLayers}'s
+	* document order.
+	* @returns true if the layer was found and removed.
+	*/
+	removeImageLayer(id) {
+		this._checkDestroyed();
+		const layer = this._imageLayers.find((l) => l.id === id);
+		if (!layer) return false;
+		this._imageLayers.splice(this._imageLayers.indexOf(layer), 1);
+		const orderIndex = this._documentOrder.indexOf(layer);
+		if (orderIndex !== -1) this._documentOrder.splice(orderIndex, 1);
+		this._revision++;
+		return true;
+	}
+	/**
+	* Tile and image layers combined into a single document order (see {@link
+	* TileMapOptions.documentOrder}), maintained live as membership changes.
+	* Reflects `addLayer` / `addImageLayer` / `removeLayer` /
+	* `removeImageLayer` calls made after construction. Holds instance
+	* references, so entries stay correct even when a tile layer and an image
+	* layer share an id in a fallback-ordered map. Object layers are
+	* data-only and never appear here.
+	*/
+	get renderableLayers() {
+		return this._documentOrder;
+	}
+	/**
+	* Create a new {@link TileMapView} that groups this map's layers into
+	* independently placeable band / layer scene nodes for interleaving
+	* application actors between tile layers.
+	*
+	* Each call returns a fresh, independent view - the map does **not** cache a
+	* single global view, so multiple coexisting views of the same map are
+	* allowed. The view references this map but never owns it: destroying the
+	* view frees only its generated layer/band nodes - never the map, its layers,
+	* tileset textures, or any application actors.
+	*
+	* @advanced
+	*/
+	createView(options) {
+		return new TileMapView(this, options);
+	}
+	/**
+	* Get a resolved tile from a given layer at tile coordinates.
+	* Convenience for `map.getTileLayerById(id)?.getTileAt(tx, ty)`.
+	* Returns null for an empty cell, out-of-bounds, or missing layer.
+	*/
+	getTileAt(layerId, tx, ty) {
+		const layer = this._layerById.get(layerId);
+		if (!layer) return null;
+		return layer.getTileAt(tx, ty);
+	}
+	/**
+	* Set a tile on a given layer at tile coordinates.
+	* Convenience for `map.getTileLayerById(id)?.setTileAt(tx, ty, tile)`.
+	* @throws If the layer does not exist, coordinates are out of bounds,
+	*         or the tile reference is invalid.
+	*/
+	setTileAt(layerId, tx, ty, tile) {
+		const layer = this._layerById.get(layerId);
+		if (!layer) throw new Error(`Layer ${layerId} not found in map "${this.name}".`);
+		layer.setTileAt(tx, ty, tile);
+	}
+	/**
+	* Clear a tile on a given layer at tile coordinates.
+	* Convenience for `map.getTileLayerById(id)?.clearTileAt(tx, ty)`.
+	* @throws If the layer does not exist or coordinates are out of bounds.
+	*/
+	clearTileAt(layerId, tx, ty) {
+		const layer = this._layerById.get(layerId);
+		if (!layer) throw new Error(`Layer ${layerId} not found in map "${this.name}".`);
+		layer.clearTileAt(tx, ty);
+	}
+	/**
+	* Convert a tile coordinate to the pixel position of its top-left corner
+	* in map-local space (ignoring layer offsets).
+	*/
+	tileToPixel(tx, ty) {
+		return {
+			x: tx * this.tileWidth,
+			y: ty * this.tileHeight
+		};
+	}
+	/**
+	* Convert a pixel position in map-local space to the tile coordinate
+	* that contains it. Uses `floor`. May return coordinates outside map bounds.
+	*/
+	pixelToTile(px, py) {
+		return {
+			tx: Math.floor(px / this.tileWidth),
+			ty: Math.floor(py / this.tileHeight)
+		};
+	}
+	/**
+	* Monotonic map revision counter. Increments on structural changes only
+	* (add/remove layer, add tileset). Cell mutations are tracked per-chunk
+	* and per-layer; the renderer reads chunk-level revisions directly.
+	* @advanced
+	*/
+	get revision() {
+		return this._revision;
+	}
+	/** Whether the map has been destroyed. */
+	get destroyed() {
+		return this._destroyed;
+	}
+	_checkDestroyed() {
+		if (this._destroyed) throw new Error(`TileMap "${this.name}" has been destroyed.`);
+	}
+	/**
+	* Destroy the map and all owned layers and chunk storage.
+	*
+	* Is idempotent. Does NOT destroy tileset textures (Loader-owned) or
+	* any SceneNodes (those do not exist yet in this slice).
+	*/
+	destroy() {
+		if (this._destroyed) return;
+		this._destroyed = true;
+		for (const layer of this._layers) layer.destroy();
+		this._layers.length = 0;
+		this._layerById.clear();
+		this._objectLayers.length = 0;
+		this._imageLayers.length = 0;
+		this._documentOrder.length = 0;
+		this._tilesets.length = 0;
+	}
+};
 
+//#endregion
 export { TileMap };
-//# sourceMappingURL=TileMap.js.map
+//# sourceMappingURL=TileMap.js.map