@codexo/exojs-tilemap 0.13.0

package/dist/esm/TileMapBand.d.ts

@@ -0,0 +1,97 @@
+import { Container } from '@codexo/exojs';
+import type { TileLayerNode } from './TileLayerNode';
+/**
+ * A named, ordered group of {@link TileLayerNode}s produced by a
+ * {@link TileMapView} for ergonomic actor interleaving.
+ *
+ * A band is a plain {@link Container} scene node that the application parents
+ * wherever it wants (typically directly under its own world root). Bands are
+ * composition units only: a band owns **its generated tile-layer nodes** and
+ * never application actors. Placing actors *between* bands is done by parenting
+ * the bands and the actor containers as siblings in the desired document order:
+ *
+ * ```ts
+ * worldRoot.addChild(view.band('ground'), actors, view.band('roof'));
+ * ```
+ *
+ * **Rendering order within a band always follows map document order**, not the
+ * order layers were listed in the band definition — band membership *selects*
+ * layers; it never reorders them.
+ *
+ * **Ownership:** the band owns the {@link TileLayerNode}s it was created with.
+ * Destroying the band destroys those layer nodes (and their cached chunk
+ * geometry) and detaches the band from its application parent — it never
+ * touches application actors, sibling bands, the {@link TileMap}, the
+ * {@link TileLayer}s, or Loader-owned tileset textures.
+ *
+ * Bounds are the union of the band's tile-layer-node bounds (an empty band
+ * collapses to a degenerate rect at the band's transformed origin).
+ *
+ * Bands are created by {@link TileMapView}; construct them through
+ * {@link TileMapView} rather than directly.
+ *
+ * @advanced
+ */
+export declare class TileMapBand extends Container {
+    private readonly _name;
+    private readonly _layerNodes;
+    private _destroyed;
+    /**
+     * @param name       The band name (unique within its owning view).
+     * @param layerNodes The layer nodes composing this band, already ordered by
+     *                   map document order. Adopted as children.
+     * @internal Constructed by {@link TileMapView}.
+     */
+    constructor(name: string, layerNodes: readonly TileLayerNode[]);
+    /** The band name (unique within its owning {@link TileMapView}). */
+    get name(): string;
+    /**
+     * The tile-layer nodes that compose this band, in map document order. This
+     * is the band's **membership** list (the nodes it owns and destroys); it may
+     * differ from {@link Container.children} if the caller reparents an
+     * individual layer node elsewhere.
+     */
+    get layerNodes(): readonly TileLayerNode[];
+    /** Find this band's layer node rendering the layer with the given id. */
+    getLayerNodeById(id: number): TileLayerNode | undefined;
+    /** Whether this band currently owns no layer nodes. */
+    get isEmpty(): boolean;
+    /**
+     * Bounds are the union of the band's visible tile-layer-node bounds. With no
+     * visible children the band collapses to a degenerate rect at its transformed
+     * origin (rather than the whole-subtree-plus-origin union a bare Container
+     * would report).
+     */
+    updateBounds(): this;
+    /**
+     * Adopt a freshly created layer node into this band (used by
+     * {@link TileMapView.refreshLayers} when a newly added map layer joins this
+     * band). Appended; call {@link TileMapBand._reorder} afterwards to restore
+     * map document order.
+     * @internal
+     */
+    _adopt(node: TileLayerNode): void;
+    /**
+     * Drop a layer node from this band's membership without destroying it (used
+     * when its map layer was removed; the view destroys the node separately).
+     * @internal
+     */
+    _release(node: TileLayerNode): void;
+    /**
+     * Reorder this band's membership and its still-parented children to map
+     * document order. `documentIndexById` maps a layer id to its index in the
+     * map's layer list. Layer nodes the caller has reparented away from this band
+     * keep their membership (for ownership) but are not re-adopted.
+     * @internal
+     */
+    _reorder(documentIndexById: ReadonlyMap<number, number>): void;
+    /**
+     * Destroy the band: detach it from its application parent, then destroy the
+     * tile-layer nodes it owns (freeing their chunk geometry). Application actors,
+     * sibling bands, the map, layers, and tileset textures are untouched.
+     *
+     * Idempotent: a second call (e.g. when {@link TileMapView.destroy} runs after
+     * the application already destroyed this band directly) is a safe no-op.
+     */
+    destroy(): void;
+}

package/dist/esm/TileMapBand.js

@@ -0,0 +1,161 @@
+import { Container } from '@codexo/exojs';
+
+/**
+ * A named, ordered group of {@link TileLayerNode}s produced by a
+ * {@link TileMapView} for ergonomic actor interleaving.
+ *
+ * A band is a plain {@link Container} scene node that the application parents
+ * wherever it wants (typically directly under its own world root). Bands are
+ * composition units only: a band owns **its generated tile-layer nodes** and
+ * never application actors. Placing actors *between* bands is done by parenting
+ * the bands and the actor containers as siblings in the desired document order:
+ *
+ * ```ts
+ * worldRoot.addChild(view.band('ground'), actors, view.band('roof'));
+ * ```
+ *
+ * **Rendering order within a band always follows map document order**, not the
+ * order layers were listed in the band definition — band membership *selects*
+ * layers; it never reorders them.
+ *
+ * **Ownership:** the band owns the {@link TileLayerNode}s it was created with.
+ * Destroying the band destroys those layer nodes (and their cached chunk
+ * geometry) and detaches the band from its application parent — it never
+ * touches application actors, sibling bands, the {@link TileMap}, the
+ * {@link TileLayer}s, or Loader-owned tileset textures.
+ *
+ * Bounds are the union of the band's tile-layer-node bounds (an empty band
+ * collapses to a degenerate rect at the band's transformed origin).
+ *
+ * Bands are created by {@link TileMapView}; construct them through
+ * {@link TileMapView} rather than directly.
+ *
+ * @advanced
+ */
+class TileMapBand extends Container {
+    _name;
+    _layerNodes;
+    _destroyed = false;
+    /**
+     * @param name       The band name (unique within its owning view).
+     * @param layerNodes The layer nodes composing this band, already ordered by
+     *                   map document order. Adopted as children.
+     * @internal Constructed by {@link TileMapView}.
+     */
+    constructor(name, layerNodes) {
+        super();
+        this._name = name;
+        this._layerNodes = [...layerNodes];
+        for (const node of this._layerNodes) {
+            this.addChild(node);
+        }
+    }
+    /** The band name (unique within its owning {@link TileMapView}). */
+    get name() {
+        return this._name;
+    }
+    /**
+     * The tile-layer nodes that compose this band, in map document order. This
+     * is the band's **membership** list (the nodes it owns and destroys); it may
+     * differ from {@link Container.children} if the caller reparents an
+     * individual layer node elsewhere.
+     */
+    get layerNodes() {
+        return this._layerNodes;
+    }
+    /** Find this band's layer node rendering the layer with the given id. */
+    getLayerNodeById(id) {
+        return this._layerNodes.find(node => node.layer.id === id);
+    }
+    /** Whether this band currently owns no layer nodes. */
+    get isEmpty() {
+        return this._layerNodes.length === 0;
+    }
+    /**
+     * Bounds are the union of the band's visible tile-layer-node bounds. With no
+     * visible children the band collapses to a degenerate rect at its transformed
+     * origin (rather than the whole-subtree-plus-origin union a bare Container
+     * would report).
+     */
+    updateBounds() {
+        this._bounds.reset();
+        let hasVisibleChild = false;
+        for (const child of this.children) {
+            if (child.visible) {
+                this._bounds.addRect(child.getBounds());
+                hasVisibleChild = true;
+            }
+        }
+        if (!hasVisibleChild) {
+            this._bounds.addRect(this.getLocalBounds(), this.getGlobalTransform());
+        }
+        return this;
+    }
+    /**
+     * Adopt a freshly created layer node into this band (used by
+     * {@link TileMapView.refreshLayers} when a newly added map layer joins this
+     * band). Appended; call {@link TileMapBand._reorder} afterwards to restore
+     * map document order.
+     * @internal
+     */
+    _adopt(node) {
+        if (!this._layerNodes.includes(node)) {
+            this._layerNodes.push(node);
+        }
+        this.addChild(node);
+    }
+    /**
+     * Drop a layer node from this band's membership without destroying it (used
+     * when its map layer was removed; the view destroys the node separately).
+     * @internal
+     */
+    _release(node) {
+        const index = this._layerNodes.indexOf(node);
+        if (index !== -1) {
+            this._layerNodes.splice(index, 1);
+        }
+        if (node.parent === this) {
+            this.removeChild(node);
+        }
+    }
+    /**
+     * Reorder this band's membership and its still-parented children to map
+     * document order. `documentIndexById` maps a layer id to its index in the
+     * map's layer list. Layer nodes the caller has reparented away from this band
+     * keep their membership (for ownership) but are not re-adopted.
+     * @internal
+     */
+    _reorder(documentIndexById) {
+        this._layerNodes.sort((a, b) => (documentIndexById.get(a.layer.id) ?? 0) - (documentIndexById.get(b.layer.id) ?? 0));
+        for (const node of this._layerNodes) {
+            if (node.parent === this) {
+                this.addChild(node);
+            }
+        }
+    }
+    /**
+     * Destroy the band: detach it from its application parent, then destroy the
+     * tile-layer nodes it owns (freeing their chunk geometry). Application actors,
+     * sibling bands, the map, layers, and tileset textures are untouched.
+     *
+     * Idempotent: a second call (e.g. when {@link TileMapView.destroy} runs after
+     * the application already destroyed this band directly) is a safe no-op.
+     */
+    destroy() {
+        if (this._destroyed) {
+            return;
+        }
+        this._destroyed = true;
+        this.parent?.removeChild(this);
+        const owned = [...this._layerNodes];
+        this._layerNodes.length = 0;
+        super.destroy();
+        for (const node of owned) {
+            node.parent?.removeChild(node);
+            node.destroy();
+        }
+    }
+}
+
+export { TileMapBand };
+//# sourceMappingURL=TileMapBand.js.map

package/dist/esm/TileMapBand.js.map

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

package/dist/esm/TileMapNode.d.ts

@@ -0,0 +1,71 @@
+import type { Rectangle } from '@codexo/exojs';
+import { Container } from '@codexo/exojs';
+import type { PixelSnapMode } from '@codexo/exojs/rendering';
+import { TileLayerNode } from './TileLayerNode';
+import type { TileMap } from './TileMap';
+/**
+ * Options for a {@link TileMapNode}.
+ * @advanced
+ */
+export interface TileMapNodeOptions {
+    /**
+     * Whether the map's chunk nodes participate in per-chunk view culling.
+     * Forwarded to every {@link TileLayerNode}. Defaults to `true`.
+     */
+    readonly cullable?: boolean;
+}
+/**
+ * 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
+ */
+export declare class TileMapNode extends Container {
+    private readonly _map;
+    private readonly _cullChunks;
+    private readonly _layerNodes;
+    private _pixelSnapMode;
+    constructor(map: TileMap, options?: TileMapNodeOptions);
+    /** The runtime map this node renders. */
+    get map(): TileMap;
+    /**
+     * 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(): 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.
+     */
+    refreshLayers(): this;
+    getLocalBounds(): Rectangle;
+    destroy(): void;
+    private _buildLayerNodes;
+}

package/dist/esm/TileMapNode.js

@@ -0,0 +1,113 @@
+import { Container } from '@codexo/exojs';
+import { assertPixelSnapMode } from './pixelSnap.js';
+import { TileLayerNode } from './TileLayerNode.js';
+
+/**
+ * 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);
+        }
+    }
+}
+
+export { TileMapNode };
+//# sourceMappingURL=TileMapNode.js.map

package/dist/esm/TileMapNode.js.map

@@ -0,0 +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;;;;"}

package/dist/esm/TileMapView.d.ts

@@ -0,0 +1,182 @@
+import type { PixelSnapMode } from '@codexo/exojs/rendering';
+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.
+ * @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}.
+ * @advanced
+ */
+export type TileMapBandDefinition = readonly TileLayerSelector[];
+/**
+ * Options for a {@link TileMapView}.
+ * @advanced
+ */
+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.
+     *
+     * @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.
+     */
+    readonly bands?: Readonly<Record<string, TileMapBandDefinition>>;
+    /**
+     * Whether the generated {@link TileLayerNode}s' chunks participate in
+     * per-chunk view culling. Forwarded to every layer node. Default `true`.
+     */
+    readonly cullable?: boolean;
+}
+/**
+ * Groups a {@link TileMap}'s layers into independently placeable scene nodes so
+ * application actors can be interleaved **between** tile layers.
+ *
+ * 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:
+ *
+ * ```ts
+ * const view = map.createView({ bands: { ground: ['background', 'ground'], roof: ['roofs'] } });
+ * worldRoot.addChild(view.band('ground'), actors, view.band('roof'));
+ * // or without bands:
+ * worldRoot.addChild(view.getLayerNodeById(groundId)!, actors, view.getLayerNodeById(roofId)!);
+ * ```
+ *
+ * **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
+ * world container, the {@link TileMap}, the {@link TileLayer}s, or tileset
+ * textures.
+ *
+ * **Ownership:** the view owns its generated layer nodes and bands. A layer
+ * assigned to a band is owned by that band; an unbanded layer is owned by the
+ * view directly. {@link TileMapView.destroy} destroys every band and layer node
+ * (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.
+ *
+ * @advanced
+ */
+export declare class TileMapView {
+    private readonly _map;
+    private readonly _cullable;
+    /** All canonical layer nodes, in map document order. */
+    private readonly _layerNodes;
+    /** Layer id → its canonical layer node. */
+    private readonly _layerNodeById;
+    /** Bands in definition (insertion) order. */
+    private readonly _bands;
+    /** Band name → band. */
+    private readonly _bandByName;
+    /** Original band definitions (frozen) for re-resolution on refresh. */
+    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. */
+    private readonly _directLayerNodes;
+    private _destroyed;
+    private _pixelSnapMode;
+    /**
+     * @param map     The runtime map to compose. Referenced, never owned.
+     * @param options Band definitions and culling.
+     * @throws When a band definition references an unknown/ambiguous layer or
+     *         assigns a layer twice / to multiple bands.
+     */
+    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. */
+    get layers(): readonly TileLayerNode[];
+    /** The bands, in definition (insertion) order. */
+    get bands(): readonly TileMapBand[];
+    /** Whether this view has been destroyed. */
+    get destroyed(): boolean;
+    /**
+     * Render-only pixel-snap mode applied to every layer node this view owns (and
+     * 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
+     * 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(): 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.
+     */
+    getLayerNodeById(id: number): TileLayerNode | undefined;
+    /**
+     * Every canonical 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[];
+    /**
+     * The band registered under `name`.
+     * @throws If no band with that name was defined.
+     */
+    band(name: string): TileMapBand;
+    /** 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.
+     *
+     * - 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.
+     *
+     * Application actors are never touched, and bands keep their placement in the
+     * application scene graph.
+     *
+     * @throws If the view has been destroyed.
+     */
+    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(): 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. */
+    private _resolveSelector;
+    /** 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). */
+    private _definitionSelects;
+    /** Detach + destroy a node, dropping it from band membership and registries. */
+    private _removeNode;
+}