@eva/plugin-renderer-tilemap 2.1.0-beta.5 → 2.1.0-beta.7

package/dist/plugin-renderer-tilemap.esm.js

@@ -45,25 +45,32 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
 };
 
 /**
- * Phaser-style Static Tilemap 渲染组件(MVP)。
+ * Tilemap 渲染组件。
  *
- * 行为:
- * 1. 从 `tileset` 资源加载一张 spritesheet 纹理;
- * 2. 每个 layer 对应一个 PixiJS Container;
- * 3. layer 内每个非零 tile 都创建一个 Sprite,texture 由原 tileset 切片得到;
- * 4. tile 在 layer Container 内的位置:`(col * tileW + offsetX, row * tileH + offsetY)`。
+ * v1 (Phaser-style, 静态): 通过 `tileset` + `layers[].data[][]` 渲染。
+ * v2 (Godot-style, chunked): 通过 `tilemapRef` + `layersV2[].cellData.chunks` 渲染。
  *
- * 不支持(Phase 2 视情况增加):tile flipping、动态修改 API、iso/hex、physics 碰撞、camera。
+ * System 通过有无 `tilemapRef` 判断走哪条路径。两条路径不共存于同一实例。
  */
 class Tilemap extends Component {
     constructor() {
         super(...arguments);
+        // v1 fields
         this.tileset = '';
         this.tileWidth = 32;
         this.tileHeight = 32;
         this.tilesetSpacing = 0;
         this.tilesetMargin = 0;
         this.layers = [];
+        // v2 fields
+        this.tilemapRef = '';
+        // 显式 `= undefined`:被 TilemapSystem 的 @componentObserver 观察;
+        // init() 用 `Object.assign(this, obj)` 只 copy obj 里存在的 key,DSL v1 路径
+        // (tileset+layers) 不传 layersV2 时 own property 不存在,observer.ts:236 会打
+        // "prop layersV2 not in component: Tilemap, Can not observer" 并跳过响应式挂载,
+        // 后续赋值 tilemap.layersV2 也不会触发 System rebuild。加 `= undefined` 让 TS
+        // emit `this.layersV2 = void 0`,保证 own property 存在。
+        this.layersV2 = undefined;
     }
     init(obj) {
         if (obj)
@@ -90,88 +97,1176 @@ __decorate([
 __decorate([
     type('number'),
     __metadata("design:type", Number)
-], Tilemap.prototype, "tilesetMargin", void 0);
+], Tilemap.prototype, "tilesetMargin", void 0);
+__decorate([
+    type('string'),
+    __metadata("design:type", String)
+], Tilemap.prototype, "tilemapRef", void 0);
+
+/**
+ * 与 libs/dsl/src/editor/chunk-codec.ts 同形的解码 helper。
+ * 在 plugin 内复制一份是为了避免 @eva/* 反向依赖 @ali/eva-dsl 或本仓 libs/dsl。
+ *
+ * 这里只需要解码 + 拆 cell;编码留给 DSL 编辑层。
+ */
+const CHUNK_SIZE$2 = 16;
+const CHUNK_CELL_COUNT = CHUNK_SIZE$2 * CHUNK_SIZE$2;
+function unpackCell(packed) {
+    return {
+        sourceSlot: packed & 0xff,
+        col: (packed >>> 8) & 0xff,
+        row: (packed >>> 16) & 0xff,
+        altIdx: (packed >>> 24) & 0x1f,
+        flipH: ((packed >>> 29) & 1) === 1,
+        flipV: ((packed >>> 30) & 1) === 1,
+        transpose: ((packed >>> 31) & 1) === 1,
+    };
+}
+function isEmptyCellValue(packed) {
+    return (packed & 0xff) === 0;
+}
+function decodeChunk(blob) {
+    const bytes = base64Decode(blob.blob);
+    if (bytes.byteLength !== CHUNK_CELL_COUNT * 4) {
+        throw new Error(`decodeChunk: expected ${CHUNK_CELL_COUNT * 4} bytes, got ${bytes.byteLength}`);
+    }
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    return new Int32Array(copy.buffer);
+}
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+function base64Decode(s) {
+    if (typeof atob === 'function') {
+        const bin = atob(s);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    const bufCtor = globalThis.Buffer;
+    if (bufCtor) {
+        return new Uint8Array(bufCtor.from(s, 'base64'));
+    }
+    // manual fallback
+    const clean = s.replace(/[^A-Za-z0-9+/]/g, '');
+    const padding = s.endsWith('==') ? 2 : s.endsWith('=') ? 1 : 0;
+    const len = Math.floor((clean.length * 3) / 4) - padding;
+    const out = new Uint8Array(len);
+    let p = 0;
+    for (let i = 0; i < clean.length; i += 4) {
+        const v0 = BASE64_ALPHABET.indexOf(clean[i]);
+        const v1 = BASE64_ALPHABET.indexOf(clean[i + 1]);
+        const v2 = clean[i + 2] ? BASE64_ALPHABET.indexOf(clean[i + 2]) : 0;
+        const v3 = clean[i + 3] ? BASE64_ALPHABET.indexOf(clean[i + 3]) : 0;
+        const w = (v0 << 18) | (v1 << 12) | (v2 << 6) | v3;
+        if (p < len)
+            out[p++] = (w >> 16) & 0xff;
+        if (p < len)
+            out[p++] = (w >> 8) & 0xff;
+        if (p < len)
+            out[p++] = w & 0xff;
+    }
+    return out;
+}
+
+/**
+ * TileSet 外链 .tileset.json 在运行时的 minimal type shape。
+ *
+ * 为避免反向依赖 libs/dsl,这里独立声明;与 libs/dsl/src/types/tileset.ts 的 disk schema 同形。
+ */
+function makeLoadedTileset(raw) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
+    const slotByIdMap = new Map();
+    // slot 0 reserved as "empty"; sources begin at slot 1
+    const sourcesBySlot = [];
+    // Detect cache collisions: same textureAsset with different regionSize/margins/separation
+    // will share frame texture cache slots downstream (cache key = textureAsset#col,row),
+    // producing visual artifacts where source A renders source B's frame. Warn so users see
+    // the issue instead of staring at swapped sprites.
+    const seenByAsset = new Map();
+    for (let i = 0; i < raw.sources.length; i++) {
+        const src = raw.sources[i];
+        sourcesBySlot.push(src);
+        slotByIdMap.set(src.id, i + 1);
+        if (src.kind === 'atlas' && src.textureAsset) {
+            const prev = seenByAsset.get(src.textureAsset);
+            if (prev) {
+                const sameRegion = prev.regionSize.width === src.regionSize.width &&
+                    prev.regionSize.height === src.regionSize.height;
+                const sameMargins = ((_b = (_a = prev.margins) === null || _a === void 0 ? void 0 : _a.x) !== null && _b !== void 0 ? _b : 0) === ((_d = (_c = src.margins) === null || _c === void 0 ? void 0 : _c.x) !== null && _d !== void 0 ? _d : 0) &&
+                    ((_f = (_e = prev.margins) === null || _e === void 0 ? void 0 : _e.y) !== null && _f !== void 0 ? _f : 0) === ((_h = (_g = src.margins) === null || _g === void 0 ? void 0 : _g.y) !== null && _h !== void 0 ? _h : 0);
+                const sameSep = ((_k = (_j = prev.separation) === null || _j === void 0 ? void 0 : _j.x) !== null && _k !== void 0 ? _k : 0) === ((_m = (_l = src.separation) === null || _l === void 0 ? void 0 : _l.x) !== null && _m !== void 0 ? _m : 0) &&
+                    ((_p = (_o = prev.separation) === null || _o === void 0 ? void 0 : _o.y) !== null && _p !== void 0 ? _p : 0) === ((_r = (_q = src.separation) === null || _q === void 0 ? void 0 : _q.y) !== null && _r !== void 0 ? _r : 0);
+                if (!sameRegion || !sameMargins || !sameSep) {
+                    if (typeof console !== 'undefined') {
+                        console.warn(`[Tilemap] Atlas sources '${prev.sourceId}' and '${src.id}' share textureAsset='${src.textureAsset}' ` +
+                            `but differ in regionSize/margins/separation. Frame texture cache may collide and render wrong frames. ` +
+                            `Use distinct textureAssets per atlas source.`);
+                    }
+                }
+            }
+            else {
+                seenByAsset.set(src.textureAsset, {
+                    regionSize: src.regionSize,
+                    margins: src.margins,
+                    separation: src.separation,
+                    sourceId: src.id,
+                });
+            }
+        }
+    }
+    return {
+        raw,
+        sourcesBySlot,
+        slotByIdMap,
+        tileWidth: raw.tileSize.width,
+        tileHeight: raw.tileSize.height,
+    };
+}
+
+/**
+ * TileAnimation driver (Phase 3).
+ *
+ * 纯计算层:输入 TilesetDocumentRaw 的 atlas.tiles[].animation,以及当前
+ * 时间(performance.now() 风格的 ms);输出每个 tile 当前应处的 atlasCoords。
+ *
+ * Phase 3 v1 只支持 sync phase;randomStart 留接口,实现为按 sourceSlot+col+row
+ * 派生确定性 phase offset(避免 Date.now / Math.random,见 memory)。
+ *
+ * 运行时 System 在 update() 时调用 advance(now),拿到 dirtyTilesByKey,
+ * 然后只重建那些 tile 所在的 chunk;不每帧重建整个 layer。
+ */
+class TileAnimationDriver {
+    constructor() {
+        this.animations = [];
+        this.lastFrameIdxByKey = new Map();
+    }
+    loadFromTileset(raw) {
+        var _a;
+        this.animations = [];
+        this.lastFrameIdxByKey.clear();
+        for (let slotIdx = 0; slotIdx < raw.sources.length; slotIdx++) {
+            const src = raw.sources[slotIdx];
+            if (src.kind !== 'atlas')
+                continue;
+            const slot = slotIdx + 1;
+            for (const tile of src.tiles) {
+                const anim = tile.animation;
+                if (!anim || !anim.frames || anim.frames.length === 0)
+                    continue;
+                const frames = anim.frames.map((f) => {
+                    var _a;
+                    return ({
+                        col: f.atlasCoords.col,
+                        row: f.atlasCoords.row,
+                        durationMs: anim.stepMs * ((_a = f.durationFactor) !== null && _a !== void 0 ? _a : 1),
+                    });
+                });
+                const totalDurationMs = frames.reduce((s, f) => s + f.durationMs, 0);
+                if (totalDurationMs <= 0)
+                    continue;
+                const phaseOffsetMs = anim.phase === 'randomStart'
+                    ? deterministicPhaseOffset(slot, tile.atlasCoords.col, tile.atlasCoords.row, totalDurationMs)
+                    : 0;
+                this.animations.push({
+                    sourceSlot: slot,
+                    col: tile.atlasCoords.col,
+                    row: tile.atlasCoords.row,
+                    frames,
+                    totalDurationMs,
+                    phase: (_a = anim.phase) !== null && _a !== void 0 ? _a : 'sync',
+                    phaseOffsetMs,
+                });
+            }
+        }
+    }
+    get animationCount() {
+        return this.animations.length;
+    }
+    /** True when (slot,col,row) is the source tile of an animation in this driver. */
+    isAnimatedSource(slot, col, row) {
+        for (const a of this.animations) {
+            if (a.sourceSlot === slot && a.col === col && a.row === row)
+                return true;
+        }
+        return false;
+    }
+    advance(nowMs) {
+        const currentFrames = new Map();
+        const dirtyKeys = new Set();
+        for (const anim of this.animations) {
+            const key = `${anim.sourceSlot},${anim.col},${anim.row}`;
+            const t = ((nowMs + anim.phaseOffsetMs) % anim.totalDurationMs + anim.totalDurationMs) % anim.totalDurationMs;
+            let acc = 0;
+            let idx = 0;
+            for (; idx < anim.frames.length; idx++) {
+                acc += anim.frames[idx].durationMs;
+                if (t < acc)
+                    break;
+            }
+            if (idx >= anim.frames.length)
+                idx = anim.frames.length - 1;
+            const frame = anim.frames[idx];
+            currentFrames.set(key, { col: frame.col, row: frame.row });
+            const prev = this.lastFrameIdxByKey.get(key);
+            if (prev !== idx) {
+                dirtyKeys.add(key);
+                this.lastFrameIdxByKey.set(key, idx);
+            }
+        }
+        return { currentFrames, dirtyKeys };
+    }
+    reset() {
+        this.lastFrameIdxByKey.clear();
+    }
+}
+/** 派生 phase offset。避免 Math.random / Date.now;只用 tile coordinates。 */
+function deterministicPhaseOffset(slot, col, row, total) {
+    // Mulberry32-ish single iteration on a hashed seed
+    let h = slot * 73856093 ^ col * 19349663 ^ row * 83492791;
+    h = (h ^ (h >>> 13)) * 1274126177;
+    h = h ^ (h >>> 16);
+    const t = ((h >>> 0) / 0xffffffff);
+    return Math.floor(t * total);
+}
+
+/**
+ * Tilemap performance probes(Sprint C B3,关联 ADR-0013)。
+ *
+ * 提供 11 个 probe(11 计时器 / 计数器),host 可通过 installTilemapPerfProbes(game)
+ * 把它们注册到 ADR-0013 的 installPerfProbes 命令式 API 中。
+ *
+ * 当前不直接依赖 ADR-0013 的 perf 包(避免循环依赖),改为暴露 PerfProbeRegistry
+ * 接口,host 注入。这样:
+ *   - Phase B 门禁:budgetCoverage 通过这 11 个 probe 计入
+ *   - 测试场景:host 可注入 in-memory 收集器 verify metrics
+ */
+/** Probe 名称常量,与 ADR-0018 §4.6 表对齐。 */
+const TILEMAP_PROBE_NAMES = {
+    DIRTY_REBUILD_MS: 'tilemap.dirtyRebuild.ms',
+    CULL_CHECK_MS: 'tilemap.cullCheck.ms',
+    ANIM_TICK_MS: 'tilemap.animTick.ms',
+    DRAWCALLS_COUNT: 'tilemap.drawcalls.count',
+    DRAWCALLS_BY_ATLAS: 'tilemap.drawcalls.byAtlas',
+    PHYSICS_REBAKE_MS: 'tilemap.physicsRebake.ms',
+    GPU_UPLOAD_MS: 'tilemap.gpuUpload.ms',
+    GPU_UPLOAD_BYTES: 'tilemap.gpuUpload.bytes',
+    AUTOTILE_MS: 'tilemap.autotile.ms',
+    PATCH_APPLY_MS: 'tilemap.patchApply.ms',
+    DIRTY_PENDING: 'tilemap.dirty.pending',
+    DIRTY_FRAMES_BEHIND: 'tilemap.dirty.framesBehind',
+    BODIES_TOTAL: 'tilemap.bodies.total',
+    BODIES_CREATED: 'tilemap.bodies.created',
+    BODIES_DESTROYED: 'tilemap.bodies.destroyed',
+    /**
+     * ChunkRenderStrategy dispatch counters(P1-3, ADR-0018 §Phase 4).
+     * 每构建一个 chunk emit 一次,分别记录 sprite / mesh / mesh-降级-sprite 的次数。
+     */
+    STRATEGY_SPRITE_COUNT: 'tilemap.strategy.sprite.count',
+    STRATEGY_MESH_COUNT: 'tilemap.strategy.mesh.count',
+    STRATEGY_MESH_FALLBACK_COUNT: 'tilemap.strategy.meshFallback.count',
+    /**
+     * SceneCollection cell skip counter(P1-4, ADR-0018 §H2).
+     * 当 TileMap chunk 内含 sceneCollection source 的 cell 时,runtime 暂时跳过(不渲染),
+     * 每跳过一次累加 1。配合每条 record 一次性 console.warn,提示需要 prefab placeholder 实现。
+     */
+    SCENECOLLECTION_SKIPPED_COUNT: 'tilemap.sceneCollection.skipped.count',
+    /**
+     * Viewport culling hits counter(C-2, ADR-0018 §Phase 4)。
+     * 每次 buildChunksForLayer 跳过一个 off-screen chunk 时累加 1。
+     * 当前 record-level `cullingBoundsHint` 由 host 注入(可选),未注入时该 probe 永远为 0。
+     * 真正的 camera-driven viewport 接入留下 cycle(参考 RendererSystem.application.renderer.view)。
+     */
+    CULL_HITS_COUNT: 'tilemap.cull.hits',
+    /**
+     * Mode-switch failure counter(T-L2, Phase L)。
+     * 当 handleChange 内部 v1↔v2 mode 切换时,新 mode 的 asset 加载失败导致旧 mode 已 teardown
+     * 又 build 不出来的情况:record.mode='unknown',probe 累加 1。host 看到 >0 表示 tilemap 资源
+     * 异常,需要诊断 tilemapRef/tileset 引用是否有效。
+     */
+    MODE_SWITCH_FAILED_COUNT: 'tilemap.modeSwitch.failed',
+    /**
+     * Animation tick error counter(T-N1, Phase N)。
+     *
+     * update() 内每帧 advance 每个 animation driver。某个 driver advance / 后续 sprite swap
+     * throw 时,本 probe +1 并 console.error 之,但不影响其他 entity 的 tick(try/catch 局部
+     * 包裹,外层 try/finally 确保 ANIM_TICK_MS endTiming 一定被调)。host 看到该 probe >0 表示
+     * tilemap 有 entity 的 animation pipeline 异常,需要诊断。
+     */
+    ANIM_TICK_ERROR_COUNT: 'tilemap.animTick.error.count',
+    /**
+     * WebGL context lost counter(T-N2, Phase N)。
+     *
+     * Eva runtime 监听 canvas 的 `webglcontextlost`,触发时本 probe +1,并把 record-level
+     * `contextLost = true` 暂停 tilemap update tick;`webglcontextrestored` 时清掉该标志。
+     * host 看到 >0 即知 WebGL 异常,通常需要在 restored 后 force re-add tilemap component
+     * 重新建几何。
+     */
+    CONTEXT_LOST_COUNT: 'tilemap.context.lost',
+};
+/** 创建一个内存收集器(测试用)。 */
+function createInMemoryProbeRegistry() {
+    const inFlight = new Map();
+    const timings = new Map();
+    const counts = new Map();
+    const gauges = new Map();
+    return {
+        beginTiming(name) {
+            inFlight.set(name, nowMs());
+        },
+        endTiming(name) {
+            const t0 = inFlight.get(name);
+            if (t0 === undefined)
+                return;
+            inFlight.delete(name);
+            const dur = nowMs() - t0;
+            if (!timings.has(name))
+                timings.set(name, []);
+            timings.get(name).push(dur);
+        },
+        count(name, delta = 1) {
+            var _a;
+            counts.set(name, ((_a = counts.get(name)) !== null && _a !== void 0 ? _a : 0) + delta);
+        },
+        gauge(name, value) {
+            gauges.set(name, value);
+        },
+        histogram(name, value) {
+            this.count(`${name}.histN`);
+            this.count(`${name}.histSum`, value);
+        },
+        timings,
+        counts,
+        gauges,
+    };
+}
+function nowMs() {
+    if (typeof performance !== 'undefined' && performance.now)
+        return performance.now();
+    // performance.now 不可用时返回 0(测试环境必有 performance,此分支几乎不走)
+    return 0;
+}
+/**
+ * Adapter:把 host 端 installPerfProbes 的 API 适配到 PerfProbeRegistry。
+ *
+ * ADR-0013 的 installPerfProbes 暴露 `game.perfProbes?.{begin,end,count,gauge}` 等
+ * 命名空间。这里只做转发,host 决定具体接入哪个版本。
+ */
+function adaptGamePerfProbes(game) {
+    var _a, _b, _c, _d;
+    const p = game === null || game === void 0 ? void 0 : game.perfProbes;
+    if (!p)
+        return null;
+    return {
+        beginTiming: (_a = p.beginTiming) !== null && _a !== void 0 ? _a : (() => { }),
+        endTiming: (_b = p.endTiming) !== null && _b !== void 0 ? _b : (() => { }),
+        count: (_c = p.count) !== null && _c !== void 0 ? _c : (() => { }),
+        gauge: (_d = p.gauge) !== null && _d !== void 0 ? _d : (() => { }),
+        histogram: p.histogram,
+    };
+}
+/**
+ * Coverage 计算 — Phase B 门禁要求 budgetCoverage ≥ 0.95。
+ * 这里返回当前 hot-path 涉及的 probe 名字集合,host 用它对比 installPerfProbes 实际
+ * 注册的 probe set。
+ */
+function getRequiredTilemapProbes() {
+    return Object.values(TILEMAP_PROBE_NAMES);
+}
+
+/**
+ * Chunk render strategy(Phase 4).
+ *
+ * 当前 system.ts 直接走 sprite-entity 路径(每非空 cell 一个 PIXI.Sprite),
+ * 简单可靠。Phase 4 引入 strategy 接口为后续 Mesh 路径预留位置:
+ *   - sprite:Phase 1 MVP 路径,适合 < 4096 个 cell / chunk 数 < 30 的场景
+ *   - mesh: 单 chunk 一次 draw call,适合 200×200 60% 填充等高密度
+ *   - auto: 按 chunk 内非空 cell 数与 atlas 数动态选择
+ *
+ * 这里只 ship strategy interface + sprite 实现 + auto-pick 阈值;实际 PIXI.Mesh
+ * shader 在下一轮 cycle 落地(见 ADR-0018 §11 未决问题 2)。
+ */
+/**
+ * 决定单个 chunk 走哪条渲染路径。
+ *
+ * 阈值来源于 ADR-0018 §10 风险登记册(Phase 4 P2-7 改造):
+ * - 单 chunk 非空 cell 数 >= 192 (75%) 且单 atlas → mesh
+ * - 多 atlas → sprite(等 texture-array 支持后再切 mesh)
+ * - 否则 sprite 简单稳定
+ */
+function resolveChunkRenderStrategy(ctx) {
+    if (ctx.preference && ctx.preference !== 'auto')
+        return ctx.preference;
+    if (ctx.atlasesInChunk > 1)
+        return 'sprite';
+    if (ctx.nonEmptyCellsInChunk >= 192)
+        return 'mesh';
+    return 'sprite';
+}
+/**
+ * 估算单个 chunk 在 sprite 路径下的额外 PIXI 节点开销(用于 perf-probe)。
+ */
+function estimateSpriteNodes(nonEmptyCellsInChunk) {
+    // 1 Container + N Sprites
+    return 1 + nonEmptyCellsInChunk;
+}
+
+/**
+ * ChunkMesh 渲染路径(Sprint C B1 — 框架已铺,shader 在 Cycle 2 落地)。
+ *
+ * Phase 4 真实 PIXI.Mesh + 自定义 vert/frag 在 PIXI v8 上需要 ProgramSource + GeometrySystem,
+ * 改动量较大,需要单独的 bench。本 cycle 先 ship 接口形态 + sprite-entity fallback,
+ * 让 ChunkRenderer 策略层可以选择"mesh-path",当 mesh 不可用时自动回退 sprite。
+ *
+ * 单一职责:
+ *   - 描述 "一个 chunk 通过 Mesh 渲染" 的契约
+ *   - 提供降级到 sprite 路径的 builder
+ *
+ * 真实 Mesh shader 实现见 ADR-0018 §Phase 4 — 在浏览器 PIXI WebGL 稳定后接入。
+ */
+/**
+ * 创建一个 chunk 的 Mesh-path render container。
+ *
+ * 当前实现:返回 Container stub。Cycle 2 接入真实 PIXI.Mesh + 自定义 shader 时
+ * 替换内部实现即可,调用方接口不变(返回 Container,由 ChunkRenderer 加到 stage)。
+ *
+ * 接口稳定保证:
+ *   - 返回 Container 必须有 children 数组(Container 默认即有)
+ *   - 返回的 Container 在 destroy() 时正确释放纹理
+ */
+function buildChunkMesh(_config) {
+    const container = new Container();
+    container.label = `chunk-mesh-stub-${_config.chunkKey}`;
+    // Mesh path 在 Cycle 2 实际接入。当前返回 empty container —— ChunkRenderer 会通过
+    // resolveChunkRenderStrategy 看到 mesh 不可用而降级到 sprite 路径。
+    return container;
+}
+/** 返回 true 表示当前环境支持 Mesh path(需要 WebGL2 + Program shader)。 */
+function isMeshPathAvailable() {
+    // Cycle 2 落地后改为真实探测。当前一律 false,触发 sprite-entity 路径。
+    return false;
+}
+/**
+ * 估算单 chunk Mesh path 占用 GPU memory(单位 KB)。
+ * 用于 perf probes,Mesh path 上线后 budget 监控参考。
+ */
+function estimateChunkMeshMemoryKB(config) {
+    // vertex buffer:每 cell 4 vertices × (xy + uv + flags) ≈ 32B/cell
+    // index buffer:6 indices/cell × 2B = 12B/cell
+    // cells = 256
+    const cellsBytes = 256 * (32 + 12);
+    return Math.ceil(cellsBytes / 1024);
+}
 
 let TilemapSystem = class TilemapSystem extends Renderer {
     constructor() {
         super(...arguments);
         this.name = 'Tilemap';
         this.records = {};
+        /** Animation driver per Tilemap entity(只有 v2 路径有 animation,v1 不用)。 */
+        this.animationDrivers = new Map();
+        /**
+         * Perf probe sink (ADR-0013 + ADR-0018 §4.6).
+         * Resolved from `game.perfProbes` in init(); null when host did not install probes —
+         * all helper methods become no-ops, no overhead in production builds without perf.
+         */
+        this.probes = null;
+        /**
+         * T-N2 (Phase N):tab visibility / WebGL context loss state。
+         * - `isHidden`:document.visibilityState === 'hidden' 时为 true,update() early return
+         * - `contextLost`:webglcontextlost 事件触发为 true;webglcontextrestored 清回 false
+         * - listener 引用保留以便 destroy 时 detach(避免内存泄漏)
+         */
+        this.isHidden = false;
+        this.contextLost = false;
+        /** T-N2:已 install handlers 的 canvas 引用,destroy 时 detach 用。 */
+        this.canvasWithCtxListeners = null;
     }
     init() {
         this.renderSystem = this.game.getSystem(RendererSystem);
         this.renderSystem.rendererManager.register(this);
+        // Best-effort probe pickup; host may install perf hooks later (see ADR-0013).
+        this.probes = adaptGamePerfProbes(this.game);
+        // T-N2:浏览器环境下绑定 visibility / context-loss listener;
+        // node/jsdom 缺 document 时跳过(installVisibilityHandlers 自带早返)。
+        this.installVisibilityHandlers();
+    }
+    /**
+     * T-N2 (Phase N):安装 visibility / WebGL context-loss listener。
+     *
+     * 安装姿势:
+     *   - visibility:`document.visibilitychange` → 更新 `isHidden`
+     *   - context loss:`canvas.webglcontextlost` → 设 `contextLost=true` + probe;
+     *                   `canvas.webglcontextrestored` → 清回 false
+     *
+     * 失败容忍:任何环境异常(jsdom 不支持某些 listener / renderSystem 还没初始化 application)
+     * 都静默 catch,不让 init 因此崩溃。
+     */
+    installVisibilityHandlers() {
+        var _a, _b, _c;
+        if (typeof document === 'undefined')
+            return; // node / jsdom 跳过
+        try {
+            this.visibilityListener = () => {
+                this.isHidden = !!document.hidden;
+            };
+            document.addEventListener('visibilitychange', this.visibilityListener);
+        }
+        catch (_d) {
+            /* ignore — 某些 jsdom 环境的 addEventListener 可能行为异常 */
+        }
+        // WebGL context lost/restored — canvas 来自 renderSystem.application.canvas
+        try {
+            const canvas = (_c = (_b = (_a = this.renderSystem) === null || _a === void 0 ? void 0 : _a.application) === null || _b === void 0 ? void 0 : _b.canvas) !== null && _c !== void 0 ? _c : null;
+            if (canvas && typeof canvas.addEventListener === 'function') {
+                this.contextLostListener = () => {
+                    this.contextLost = true;
+                    this.probeCount(TILEMAP_PROBE_NAMES.CONTEXT_LOST_COUNT, 1);
+                    if (typeof console !== 'undefined') {
+                        console.warn('[Tilemap] WebGL context lost — pausing animation tick');
+                    }
+                };
+                this.contextRestoredListener = () => {
+                    this.contextLost = false;
+                    if (typeof console !== 'undefined') {
+                        console.info('[Tilemap] WebGL context restored — resuming animation tick');
+                    }
+                    // Host 决定是否 force component re-add 重建几何;plugin 不主动 rebuild,
+                    // 仅清掉 contextLost flag 让 update tick 恢复。
+                };
+                canvas.addEventListener('webglcontextlost', this.contextLostListener);
+                canvas.addEventListener('webglcontextrestored', this.contextRestoredListener);
+                this.canvasWithCtxListeners = canvas;
+            }
+        }
+        catch (_e) {
+            /* ignore */
+        }
+    }
+    /**
+     * T-N2:卸载 visibility / context-loss listener,destroy() 调用以避免内存泄漏。
+     */
+    uninstallVisibilityHandlers() {
+        if (typeof document !== 'undefined' && this.visibilityListener) {
+            try {
+                document.removeEventListener('visibilitychange', this.visibilityListener);
+            }
+            catch (_a) {
+                /* ignore */
+            }
+            this.visibilityListener = undefined;
+        }
+        if (this.canvasWithCtxListeners) {
+            try {
+                if (this.contextLostListener) {
+                    this.canvasWithCtxListeners.removeEventListener('webglcontextlost', this.contextLostListener);
+                }
+                if (this.contextRestoredListener) {
+                    this.canvasWithCtxListeners.removeEventListener('webglcontextrestored', this.contextRestoredListener);
+                }
+            }
+            catch (_b) {
+                /* ignore */
+            }
+            this.contextLostListener = undefined;
+            this.contextRestoredListener = undefined;
+            this.canvasWithCtxListeners = null;
+        }
+    }
+    /** Late probe attach — host can call this after `installPerfProbes` if init order isn't right. */
+    attachPerfProbes(probes) {
+        this.probes = probes;
+    }
+    /**
+     * T-L7 (Phase L) public API:host 注入 viewport culling hint。
+     *
+     * - bounds 非 null:更新 record.cullingBoundsHint,下次 build 时 buildChunksForLayer 会
+     *   跳过不相交的 chunk。
+     * - null:清除 hint(等价于不剔除任何 chunk)。
+     *
+     * 本方法只更新字段,不强制重建。host 想立刻生效有两种姿势:
+     *   1. 调用后通过 `component.layersV2 = layersV2.slice()` 触发 observer rebuild
+     *   2. 调 `invalidateChunks` 标记 dirty 让 rAF flush 时按新 hint rebuild
+     * 这样 setHint 是 O(1),呼应性能预算。
+     */
+    setCullingBoundsHint(gameObjectId, bounds) {
+        const record = this.records[gameObjectId];
+        if (!record)
+            return;
+        if (bounds === null) {
+            record.cullingBoundsHint = undefined;
+        }
+        else {
+            record.cullingBoundsHint = bounds;
+        }
+    }
+    /**
+     * T-L4 (Phase L) public API:host 标记若干 chunk dirty,触发 rAF flush 增量重建。
+     *
+     * 触发场景:layer paint stroke 完成后 host 知道哪些 chunkKey 被改了,调本方法即可。
+     * 比 prop=layersV2 整体 reassign 高效得多(整 layer rebuild O(visibleChunks) → O(stroke)).
+     *
+     * 流程:
+     *   1. 把 chunkKeys 累加到 record.dirtyChunkKeys.get(layerId)
+     *   2. emit DIRTY_PENDING gauge(总 size)
+     *   3. 如果还没 scheduled,启动一次 rAF tick 在下一帧调 flushDirtyChunks
+     *
+     * 调用方应保证 chunkKey 形态与 cellData.chunks key 一致(如 "0,0")。未知 chunkKey
+     * 在 flush 时被静默忽略(已在 cellData.chunks 内会被处理;否则跳过)。
+     */
+    invalidateChunks(gameObjectId, layerId, chunkKeys) {
+        const record = this.records[gameObjectId];
+        if (!record || chunkKeys.length === 0)
+            return;
+        let bucket = record.dirtyChunkKeys.get(layerId);
+        if (!bucket) {
+            bucket = new Set();
+            record.dirtyChunkKeys.set(layerId, bucket);
+        }
+        for (const k of chunkKeys)
+            bucket.add(k);
+        // gauge:总 dirty chunk 数(跨 layer)
+        let total = 0;
+        for (const s of record.dirtyChunkKeys.values())
+            total += s.size;
+        this.probeGauge(TILEMAP_PROBE_NAMES.DIRTY_PENDING, total);
+        // schedule rAF flush(避免一帧内重复 schedule)
+        if (!record.flushScheduled) {
+            record.flushScheduled = true;
+            const sched = typeof requestAnimationFrame !== 'undefined'
+                ? requestAnimationFrame
+                : (cb) => setTimeout(() => cb(0), 16);
+            sched(() => this.flushDirtyChunks(gameObjectId));
+        }
+    }
+    /**
+     * T-L4 (Phase L):rAF callback;只 rebuild record.dirtyChunkKeys 内 chunk,不影响其他 chunk。
+     *
+     * 本方法是 public 供测试调用,但生产路径只走 invalidateChunks scheduled trigger。
+     * 行为:
+     *   - 找到 component 的 layersV2 layer for layerId
+     *   - 对每个 dirty chunkKey:destroy 旧 chunkContainer + 重新 populate
+     *   - emit DIRTY_FRAMES_BEHIND counter+1(本帧 flush 了 N 个 chunk 即"延迟一帧")
+     *   - 清空 dirtyChunkKeys + 把 DIRTY_PENDING gauge 归零
+     */
+    flushDirtyChunks(gameObjectId) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+        const record = this.records[gameObjectId];
+        if (!record)
+            return;
+        record.flushScheduled = false;
+        if (record.dirtyChunkKeys.size === 0)
+            return;
+        if (record.mode !== 'v2' || !record.loadedTileset) {
+            // v1 / unknown 路径不支持增量 chunk rebuild;清空 dirty + skip
+            record.dirtyChunkKeys.clear();
+            this.probeGauge(TILEMAP_PROBE_NAMES.DIRTY_PENDING, 0);
+            return;
+        }
+        this.probeCount(TILEMAP_PROBE_NAMES.DIRTY_FRAMES_BEHIND, 1);
+        const loaded = record.loadedTileset;
+        const animDriver = (_a = this.animationDrivers.get(gameObjectId)) !== null && _a !== void 0 ? _a : null;
+        // lookup component 通过 game.gameObjects → 找 Tilemap component。
+        // 这里取巧:invalidateChunks 调用方应该已经写好 layersV2,我们从 layerContainersV2 反查
+        // chunkContainer,destroy + 重新调 populateChunkSprites。需要拿到 layer 配置(cellData/modulate
+        // /opacity)— 通过遍历 record.layerContainersV2 找到 chunkContainers 即可。但要 populate 还需
+        // cellData.chunks[chunkKey] — 必须找 component。
+        const game = this.game;
+        let component = null;
+        if (game === null || game === void 0 ? void 0 : game.gameObjects) {
+            for (const go of game.gameObjects) {
+                if (go.id !== gameObjectId)
+                    continue;
+                const c = (_b = go.components) === null || _b === void 0 ? void 0 : _b.find((cc) => (cc === null || cc === void 0 ? void 0 : cc.name) === 'Tilemap');
+                if (c) {
+                    component = c;
+                    break;
+                }
+            }
+        }
+        const cellW = (_d = (_c = component === null || component === void 0 ? void 0 : component.cellSize) === null || _c === void 0 ? void 0 : _c.width) !== null && _d !== void 0 ? _d : loaded.tileWidth;
+        const cellH = (_f = (_e = component === null || component === void 0 ? void 0 : component.cellSize) === null || _e === void 0 ? void 0 : _e.height) !== null && _f !== void 0 ? _f : loaded.tileHeight;
+        const originX = (_h = (_g = component === null || component === void 0 ? void 0 : component.mapOrigin) === null || _g === void 0 ? void 0 : _g.x) !== null && _h !== void 0 ? _h : 0;
+        const originY = (_k = (_j = component === null || component === void 0 ? void 0 : component.mapOrigin) === null || _j === void 0 ? void 0 : _j.y) !== null && _k !== void 0 ? _k : 0;
+        this.probeBegin(TILEMAP_PROBE_NAMES.DIRTY_REBUILD_MS);
+        try {
+            for (const [layerId, chunkKeys] of record.dirtyChunkKeys) {
+                const layerEntry = record.layerContainersV2.get(layerId);
+                if (!layerEntry)
+                    continue;
+                // 找 layer 配置(modulate/opacity/cellData)— 必须从 component.layersV2 找。
+                const layerSpec = (_m = (_l = component === null || component === void 0 ? void 0 : component.layersV2) === null || _l === void 0 ? void 0 : _l.find((l) => l.id === layerId)) !== null && _m !== void 0 ? _m : null;
+                if (!layerSpec)
+                    continue;
+                for (const chunkKey of chunkKeys) {
+                    const oldChunkContainer = layerEntry.chunkContainers.get(chunkKey);
+                    if (oldChunkContainer) {
+                        layerEntry.container.removeChild(oldChunkContainer);
+                        try {
+                            oldChunkContainer.destroy({ children: true });
+                        }
+                        catch (_q) {
+                            /* ignore */
+                        }
+                        layerEntry.chunkContainers.delete(chunkKey);
+                    }
+                    // populate 新 chunk(如果 cellData 还包含该 key)
+                    const blob = (_p = (_o = layerSpec.cellData) === null || _o === void 0 ? void 0 : _o.chunks) === null || _p === void 0 ? void 0 : _p[chunkKey];
+                    if (!blob || blob.nonEmpty <= 0)
+                        continue;
+                    const chunkContainer = new Container();
+                    chunkContainer.label = `chunk-${chunkKey}`;
+                    this.populateChunkSprites(chunkContainer, chunkKey, blob, record, loaded, cellW, cellH, originX, originY, layerSpec, animDriver);
+                    layerEntry.container.addChild(chunkContainer);
+                    layerEntry.chunkContainers.set(chunkKey, chunkContainer);
+                }
+            }
+        }
+        finally {
+            this.probeEnd(TILEMAP_PROBE_NAMES.DIRTY_REBUILD_MS);
+        }
+        record.dirtyChunkKeys.clear();
+        this.probeGauge(TILEMAP_PROBE_NAMES.DIRTY_PENDING, 0);
+        this.requestRedraw();
+    }
+    probeBegin(name) {
+        var _a;
+        (_a = this.probes) === null || _a === void 0 ? void 0 : _a.beginTiming(name);
+    }
+    probeEnd(name) {
+        var _a;
+        (_a = this.probes) === null || _a === void 0 ? void 0 : _a.endTiming(name);
+    }
+    probeCount(name, delta = 1) {
+        var _a;
+        (_a = this.probes) === null || _a === void 0 ? void 0 : _a.count(name, delta);
+    }
+    probeGauge(name, value) {
+        var _a;
+        (_a = this.probes) === null || _a === void 0 ? void 0 : _a.gauge(name, value);
     }
     rendererUpdate(_gameObject) {
         // 静态 tilemap MVP:几何不随 transform.size 变化,无需逐帧刷新。
     }
+    /**
+     * Eva.js update 调用(每帧)— 推进 v2 path animation tick。
+     * 任何 tile 切到新 frame 时,标记对应 chunk dirty,下一帧重建。
+     * v1 路径不参与(没 animation 元数据)。
+     *
+     * T-N1 (Phase N) hardening:
+     *   - 每个 driver advance 包在内层 try/catch:一个 entity 的 animation pipeline 抛错
+     *     不影响其他 entity 的 tick(continue 到下一个);失败计入 ANIM_TICK_ERROR_COUNT probe
+     *     并 console.error 留诊断。
+     *   - 外层 try/finally 包整段 hot path:保证 probeEnd(ANIM_TICK_MS) 一定 pair probeBegin,
+     *     不会因为内层逻辑泄漏 throw 导致 timing 计 inFlight 永远不释放。
+     *
+     * T-N2 (Phase N) hardening:
+     *   - tab hidden 或 WebGL context lost 时直接 early return,不浪费 CPU,且避免 context lost
+     *     期间渲染调用堆栈抛错。
+     */
+    update(_frame) {
+        // T-N2:tab 切换到后台 / WebGL context 异常 → 暂停 tick。
+        if (this.isHidden || this.contextLost)
+            return;
+        if (this.animationDrivers.size === 0)
+            return;
+        this.probeBegin(TILEMAP_PROBE_NAMES.ANIM_TICK_MS);
+        let totalSpritesSwapped = 0;
+        try {
+            const now = (typeof performance !== 'undefined' && performance.now) ? performance.now() : 0;
+            // PERF-T-O2 (see ADR-0022): consider flattening dirty (sprite, texture) pairs into a typed
+            // array once per record when animatedSpritesByAnimKey changes. Trigger: >1000 animated cells
+            // + p99(animTick.ms) > 2ms. Defer until probe data warrants.
+            for (const [gameObjectId, driver] of this.animationDrivers) {
+                const record = this.records[gameObjectId];
+                if (!record || record.mode !== 'v2')
+                    continue;
+                try {
+                    const result = driver.advance(now);
+                    if (result.dirtyKeys.size === 0)
+                        continue;
+                    // For each dirty animation source (slot,col,row), look up every live Sprite that
+                    // was painted with that source tile and swap its texture to the new frame.
+                    // currentFrames maps source key → new (col,row) within the same source atlas.
+                    const loaded = record.loadedTileset;
+                    if (!loaded)
+                        continue;
+                    let anyApplied = false;
+                    for (const animKey of result.dirtyKeys) {
+                        const sprites = record.animatedSpritesByAnimKey.get(animKey);
+                        if (!sprites || sprites.length === 0)
+                            continue;
+                        const nextFrame = result.currentFrames.get(animKey);
+                        if (!nextFrame)
+                            continue;
+                        const parts = animKey.split(',');
+                        const slot = Number.parseInt(parts[0], 10);
+                        const newTex = this.getAtlasFrameTexture(record, loaded, {
+                            sourceSlot: slot,
+                            col: nextFrame.col,
+                            row: nextFrame.row,
+                        });
+                        if (!newTex)
+                            continue;
+                        for (const sp of sprites) {
+                            sp.texture = newTex;
+                            anyApplied = true;
+                            totalSpritesSwapped++;
+                        }
+                    }
+                    if (anyApplied)
+                        this.requestRedraw();
+                }
+                catch (e) {
+                    // T-N1:本 entity 出错不破坏其他 entity 的 tick。
+                    this.probeCount(TILEMAP_PROBE_NAMES.ANIM_TICK_ERROR_COUNT, 1);
+                    if (typeof console !== 'undefined') {
+                        console.error(`[Tilemap] animation tick failed for entity ${gameObjectId}`, e);
+                    }
+                    // continue to next driver
+                }
+            }
+        }
+        finally {
+            this.probeEnd(TILEMAP_PROBE_NAMES.ANIM_TICK_MS);
+            if (totalSpritesSwapped > 0)
+                this.probeCount('tilemap.anim.spritesSwapped', totalSpritesSwapped);
+        }
+    }
     componentChanged(changed) {
-        var _a, _b, _c;
         return __awaiter(this, void 0, void 0, function* () {
             if (changed.componentName !== 'Tilemap')
                 return;
             const component = changed.component;
             const gameObjectId = changed.gameObject.id;
             if (changed.type === OBSERVER_TYPE.ADD) {
+                yield this.handleAdd(gameObjectId, changed.gameObject, component);
+            }
+            else if (changed.type === OBSERVER_TYPE.CHANGE) {
+                yield this.handleChange(gameObjectId, component, changed);
+            }
+            else if (changed.type === OBSERVER_TYPE.REMOVE) {
+                this.handleRemove(gameObjectId);
+            }
+        });
+    }
+    /* ───────────────────────────────────────────────────────────── lifecycle ── */
+    handleAdd(gameObjectId, gameObject, component) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.probeBegin(TILEMAP_PROBE_NAMES.DIRTY_REBUILD_MS);
+            try {
                 const asyncId = this.increaseAsyncId(gameObjectId);
-                let texture = null;
-                if (component.tileset) {
-                    const { instance } = yield resource.getResource(component.tileset);
-                    if (!this.validateAsyncId(gameObjectId, asyncId))
-                        return;
-                    if (!instance) {
-                        console.error(`GameObject:${changed.gameObject.name}'s Tilemap tileset load error`);
-                        return;
-                    }
-                    texture = instance;
-                }
-                if (!texture)
-                    return;
+                const mode = this.detectMode(component);
                 const root = new Container();
-                const container = this.containerManager.getContainer(gameObjectId);
-                if (container)
-                    container.addChildAt(root, 0);
+                const containerHost = this.containerManager.getContainer(gameObjectId);
+                if (containerHost)
+                    containerHost.addChildAt(root, 0);
                 const record = {
                     root,
                     layerContainers: [],
+                    layerContainersV2: new Map(),
                     frameTextures: [],
-                    baseTexture: texture,
+                    frameTexturesV2: new Map(),
+                    baseTexture: null,
+                    atlasTextures: new Map(),
+                    loadedTileset: null,
+                    mode,
+                    animatedSpritesByAnimKey: new Map(),
+                    sceneCollectionWarnedSourceIds: new Set(),
+                    // T-L4 (Phase L):dirty chunk tracking,默认空 + 未 scheduled。
+                    dirtyChunkKeys: new Map(),
+                    flushScheduled: false,
                 };
                 this.records[gameObjectId] = record;
-                this.buildLayers(record, component);
+                if (mode === 'v1') {
+                    yield this.ensureV1Built(record, gameObjectId, gameObject, component, asyncId);
+                }
+                else if (mode === 'v2') {
+                    yield this.ensureV2Built(record, gameObjectId, gameObject, component, asyncId);
+                }
+                // mode === 'unknown' → no-op (record sits empty, waiting for handleChange to upgrade).
             }
-            else if (changed.type === OBSERVER_TYPE.CHANGE) {
-                const record = this.records[gameObjectId];
-                if (!record)
+            finally {
+                this.probeEnd(TILEMAP_PROBE_NAMES.DIRTY_REBUILD_MS);
+            }
+        });
+    }
+    /**
+     * v1 path:load tileset texture + buildLayersV1。被 handleAdd 与 handleChange(mode upgrade)共用。
+     *
+     * 调用方负责:
+     *   - 在调用前设置 record.mode = 'v1'
+     *   - 在调用前 increaseAsyncId 拿到 asyncId
+     *   - record 在 records[gameObjectId] 已就位
+     *
+     * 本方法负责:
+     *   - resource.getResource(tileset)
+     *   - asyncId 校验(swap 期间 ref 被替换则中断)
+     *   - 错误日志
+     *   - 把 baseTexture 写回 record + buildLayersV1 + requestRedraw
+     */
+    ensureV1Built(record, gameObjectId, gameObject, component, asyncId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const texture = yield this.loadV1Texture(component);
+            if (!this.validateAsyncId(gameObjectId, asyncId))
+                return;
+            if (!texture) {
+                if (typeof console !== 'undefined') {
+                    console.error(`GameObject:${gameObject.name}'s Tilemap tileset load error`);
+                }
+                return;
+            }
+            record.baseTexture = texture;
+            this.buildLayersV1(record, component);
+            this.requestRedraw(); // Editor preview ticker 在 edit 模式被冻结,资源加载完手动 trigger 一帧
+        });
+    }
+    /**
+     * v2 path:load tileset doc + atlas textures + animation driver + buildLayersV2。
+     * 被 handleAdd 与 handleChange(mode upgrade / tilemapRef swap)共用。
+     *
+     * 调用方负责:
+     *   - 在调用前设置 record.mode = 'v2'
+     *   - 在调用前 increaseAsyncId 拿到 asyncId
+     *   - 在调用前已 tearDown 旧 mode 的产物(如果是 mode upgrade)
+     */
+    ensureV2Built(record, gameObjectId, gameObject, component, asyncId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const loaded = yield this.loadV2Tileset(component);
+            if (!this.validateAsyncId(gameObjectId, asyncId))
+                return;
+            if (!loaded) {
+                if (typeof console !== 'undefined') {
+                    console.error(`GameObject:${gameObject.name}'s Tilemap tilemapRef load error`);
+                }
+                return;
+            }
+            record.loadedTileset = loaded;
+            yield this.loadAtlasTextures(record, loaded);
+            if (!this.validateAsyncId(gameObjectId, asyncId))
+                return;
+            // Animation:为该 entity 创建独立 driver(per-entity 避免跨 tilemap phase 互相干扰)。
+            // Driver must exist BEFORE buildLayersV2 so populate can register animated sprites.
+            const animDriver = new TileAnimationDriver();
+            animDriver.loadFromTileset(loaded.raw);
+            const driverForBuild = animDriver.animationCount > 0 ? animDriver : null;
+            if (driverForBuild)
+                this.animationDrivers.set(gameObjectId, driverForBuild);
+            this.buildLayersV2(record, component, driverForBuild);
+            this.requestRedraw();
+        });
+    }
+    /**
+     * Editor preview 的 PIXI ticker 在 edit 模式被冻结。Tilemap mount/hot-swap 完成时
+     * 主动 trigger 一帧让 chunk 立即可见。preserveDrawingBuffer:true 后单次 render 即可
+     * 定格(见 plugin-renderer/lib/System.ts createApplication 注释)。
+     */
+    requestRedraw() {
+        var _a;
+        try {
+            const app = (_a = this.renderSystem) === null || _a === void 0 ? void 0 : _a.application;
+            if ((app === null || app === void 0 ? void 0 : app.renderer) && app.stage) {
+                app.renderer.render(app.stage);
+            }
+        }
+        catch (e) {
+            if (typeof console !== 'undefined') {
+                console.warn('[Tilemap] requestRedraw failed', e);
+            }
+        }
+    }
+    handleChange(gameObjectId, component, changed) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const record = this.records[gameObjectId];
+            if (!record)
+                return;
+            const prop = (_b = (_a = changed.prop) === null || _a === void 0 ? void 0 : _a.prop) === null || _b === void 0 ? void 0 : _b[0];
+            this.probeBegin(TILEMAP_PROBE_NAMES.PATCH_APPLY_MS);
+            try {
+                // C-1 + T-L2(Phase L):mode upgrade / switch on live entity,带 fail-safe rollback。
+                //
+                // 触发场景:
+                //   - unknown → v1 (component 起初无 tileset/tilemapRef,后续 patch 上 tileset)
+                //   - unknown → v2 (同上,patch 上 tilemapRef)
+                //   - v1 → v2  (host 切换:tileset 清空 + tilemapRef 设值)
+                //   - v2 → v1  (反向)
+                //
+                // T-L2 修复:旧代码先 `record.mode = newMode` + 清空 baseTexture/loadedTileset 再 await load。
+                // 如果 load 失败,record 卡在新 mode + 半建空白 → 之后 prop change 走错分支。
+                // 新流程:load 失败时 record.mode → 'unknown',emit MODE_SWITCH_FAILED probe,host 看得见。
+                const newMode = this.detectMode(component);
+                if (newMode !== record.mode) {
+                    const asyncId = this.increaseAsyncId(gameObjectId);
+                    try {
+                        // Teardown 旧 mode 的产物(不可逆,但 host 已发 patch,旧 mode 不再展示是用户预期)
+                        if (record.mode === 'v1') {
+                            this.tearDownChildrenV1(record);
+                        }
+                        else if (record.mode === 'v2') {
+                            this.tearDownChildrenV2(record);
+                            this.animationDrivers.delete(gameObjectId);
+                        }
+                        // 清空跨 mode 共享字段(mode 暂不切,等 ensure resolve 再 commit)
+                        record.baseTexture = null;
+                        record.loadedTileset = null;
+                        if (newMode === 'v1') {
+                            const texture = yield this.loadV1Texture(component);
+                            if (!this.validateAsyncId(gameObjectId, asyncId))
+                                return;
+                            if (!texture) {
+                                // mode-switch 失败:record 状态 → 'unknown',probe+1,host 可在 dashboard 看到。
+                                record.mode = 'unknown';
+                                this.probeCount(TILEMAP_PROBE_NAMES.MODE_SWITCH_FAILED_COUNT, 1);
+                                if (typeof console !== 'undefined') {
+                                    console.error(`GameObject:${changed.gameObject.name}'s Tilemap mode-switch v→v1 failed (tileset load returned null)`);
+                                }
+                                return;
+                            }
+                            record.mode = 'v1';
+                            record.baseTexture = texture;
+                            this.buildLayersV1(record, component);
+                            this.requestRedraw();
+                        }
+                        else if (newMode === 'v2') {
+                            const loaded = yield this.loadV2Tileset(component);
+                            if (!this.validateAsyncId(gameObjectId, asyncId))
+                                return;
+                            if (!loaded) {
+                                record.mode = 'unknown';
+                                this.probeCount(TILEMAP_PROBE_NAMES.MODE_SWITCH_FAILED_COUNT, 1);
+                                if (typeof console !== 'undefined') {
+                                    console.error(`GameObject:${changed.gameObject.name}'s Tilemap mode-switch v→v2 failed (tilemapRef load returned null)`);
+                                }
+                                return;
+                            }
+                            yield this.loadAtlasTextures(record, loaded);
+                            if (!this.validateAsyncId(gameObjectId, asyncId))
+                                return;
+                            // commit 推迟到这里
+                            record.mode = 'v2';
+                            record.loadedTileset = loaded;
+                            const animDriver = new TileAnimationDriver();
+                            animDriver.loadFromTileset(loaded.raw);
+                            const driverForBuild = animDriver.animationCount > 0 ? animDriver : null;
+                            if (driverForBuild)
+                                this.animationDrivers.set(gameObjectId, driverForBuild);
+                            this.buildLayersV2(record, component, driverForBuild);
+                            this.requestRedraw();
+                        }
+                        else {
+                            // newMode === 'unknown' → 干净 teardown 后保持 unknown
+                            record.mode = 'unknown';
+                        }
+                    }
+                    catch (e) {
+                        record.mode = 'unknown';
+                        this.probeCount(TILEMAP_PROBE_NAMES.MODE_SWITCH_FAILED_COUNT, 1);
+                        if (typeof console !== 'undefined') {
+                            console.error('[Tilemap] mode switch threw', e);
+                        }
+                    }
                     return;
-                if (((_b = (_a = changed.prop) === null || _a === void 0 ? void 0 : _a.prop) === null || _b === void 0 ? void 0 : _b[0]) === 'tileset') {
+                }
+                // 同 mode 内 prop 替换(tileset 换图 / tilemapRef 换 ref / layersV2 整体 reassign)
+                if (prop === 'tileset' && record.mode === 'v1') {
+                    const asyncId = this.increaseAsyncId(gameObjectId);
+                    const texture = yield this.loadV1Texture(component);
+                    if (!this.validateAsyncId(gameObjectId, asyncId))
+                        return;
+                    if (!texture)
+                        return;
+                    this.tearDownChildrenV1(record);
+                    record.baseTexture = texture;
+                    this.buildLayersV1(record, component);
+                    this.requestRedraw();
+                }
+                else if (prop === 'tilemapRef' && record.mode === 'v2') {
                     const asyncId = this.increaseAsyncId(gameObjectId);
-                    const { instance } = yield resource.getResource(component.tileset);
+                    const loaded = yield this.loadV2Tileset(component);
                     if (!this.validateAsyncId(gameObjectId, asyncId))
                         return;
-                    if (!instance)
+                    if (!loaded)
                         return;
-                    this.tearDownChildren(record);
-                    record.baseTexture = instance;
-                    this.buildLayers(record, component);
+                    this.tearDownChildrenV2(record);
+                    record.loadedTileset = loaded;
+                    yield this.loadAtlasTextures(record, loaded);
+                    if (!this.validateAsyncId(gameObjectId, asyncId))
+                        return;
+                    // Rebuild animation driver to match the new tileset (animations may have changed).
+                    this.animationDrivers.delete(gameObjectId);
+                    const animDriver = new TileAnimationDriver();
+                    animDriver.loadFromTileset(loaded.raw);
+                    const driverForBuild = animDriver.animationCount > 0 ? animDriver : null;
+                    if (driverForBuild)
+                        this.animationDrivers.set(gameObjectId, driverForBuild);
+                    this.buildLayersV2(record, component, driverForBuild);
+                    this.requestRedraw();
+                }
+                else if (prop === 'layersV2' && record.mode === 'v2') {
+                    // T-L1 (Phase L):layersV2 整体 ref reassign → 整 layer 重建。
+                    // 复用 loadedTileset + atlasTextures(它们没变),只 teardown sprite/chunk container
+                    // + animation driver(driver 来自 loadedTileset.raw 可重建)。
+                    // 整 layer rebuild 是浪费 — T-L4 提供 invalidateChunks 增量路径,
+                    // host 在 paint stroke 后用 invalidateChunks 而不是替换整个 layersV2。
+                    this.tearDownChildrenV2(record);
+                    this.animationDrivers.delete(gameObjectId);
+                    // 清空 dirtyChunkKeys:整 layer rebuild 后所有 chunk 都是 fresh
+                    record.dirtyChunkKeys.clear();
+                    const loaded = record.loadedTileset;
+                    let driverForBuild = null;
+                    if (loaded) {
+                        const animDriver = new TileAnimationDriver();
+                        animDriver.loadFromTileset(loaded.raw);
+                        if (animDriver.animationCount > 0) {
+                            driverForBuild = animDriver;
+                            this.animationDrivers.set(gameObjectId, animDriver);
+                        }
+                    }
+                    this.buildLayersV2(record, component, driverForBuild);
+                    this.requestRedraw();
                 }
             }
-            else if (changed.type === OBSERVER_TYPE.REMOVE) {
-                this.increaseAsyncId(gameObjectId);
-                const record = this.records[gameObjectId];
-                if (!record)
-                    return;
-                this.tearDownChildren(record);
-                const container = (_c = this.containerManager) === null || _c === void 0 ? void 0 : _c.getContainer(gameObjectId);
-                if (container)
-                    container.removeChild(record.root);
-                record.root.destroy({ children: true });
-                delete this.records[gameObjectId];
+            finally {
+                this.probeEnd(TILEMAP_PROBE_NAMES.PATCH_APPLY_MS);
             }
         });
     }
-    /** 销毁现有 layer/frame 纹理(切换 tileset 或卸载时调用)。 */
-    tearDownChildren(record) {
+    handleRemove(gameObjectId) {
+        var _a;
+        this.increaseAsyncId(gameObjectId);
+        const record = this.records[gameObjectId];
+        if (!record)
+            return;
+        this.tearDownChildrenV1(record);
+        this.tearDownChildrenV2(record);
+        const containerHost = (_a = this.containerManager) === null || _a === void 0 ? void 0 : _a.getContainer(gameObjectId);
+        if (containerHost)
+            containerHost.removeChild(record.root);
+        record.root.destroy({ children: true });
+        delete this.records[gameObjectId];
+        this.animationDrivers.delete(gameObjectId);
+        // Re-emit live record count as a gauge so dashboards can see entity churn.
+        this.probeGauge('tilemap.records.alive', Object.keys(this.records).length);
+    }
+    detectMode(component) {
+        if (component.tilemapRef)
+            return 'v2';
+        if (component.tileset)
+            return 'v1';
+        return 'unknown';
+    }
+    /* ───────────────────────────────────────────────────── v1 Phaser-style ── */
+    loadV1Texture(component) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!component.tileset)
+                return null;
+            const { instance } = yield resource.getResource(component.tileset);
+            return (_a = instance) !== null && _a !== void 0 ? _a : null;
+        });
+    }
+    tearDownChildrenV1(record) {
         for (const layer of record.layerContainers) {
             record.root.removeChild(layer);
             layer.destroy({ children: true });
@@ -181,11 +1276,13 @@ let TilemapSystem = class TilemapSystem extends Renderer {
             try {
                 tex.destroy(false);
             }
-            catch ( /* ignore */_a) { /* ignore */ }
+            catch (_a) {
+                /* ignore */
+            }
         }
         record.frameTextures = [];
     }
-    buildLayers(record, component) {
+    buildLayersV1(record, component) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
         const base = record.baseTexture;
         if (!base)
@@ -196,20 +1293,16 @@ let TilemapSystem = class TilemapSystem extends Renderer {
         const renderH = (_b = component.renderTileHeight) !== null && _b !== void 0 ? _b : tileH;
         const margin = component.tilesetMargin || 0;
         const spacing = component.tilesetSpacing || 0;
-        // 推断 columns
         const sourceWidth = (_j = (_g = (_f = (_d = (_c = base.orig) === null || _c === void 0 ? void 0 : _c.width) !== null && _d !== void 0 ? _d : (_e = base.source) === null || _e === void 0 ? void 0 : _e.width) !== null && _f !== void 0 ? _f : base.width) !== null && _g !== void 0 ? _g : (_h = base.frame) === null || _h === void 0 ? void 0 : _h.width) !== null && _j !== void 0 ? _j : 0;
         const inferredCols = sourceWidth > 0 ? Math.max(1, Math.floor((sourceWidth - margin + spacing) / (tileW + spacing))) : 1;
         const cols = component.tilesetColumns && component.tilesetColumns > 0 ? component.tilesetColumns : inferredCols;
-        // 每次重建 frameTextures(以 tile id - 1 索引)。Phaser 中 id 0 = 空,真实 tile id 从 1 开始。
-        // 我们提前不知道 layer 用了哪些 id,所以延迟切;为简单先一次性切前 cols * 推断行数 个。
-        // 但避免无限切,这里只在 setTexture 时按需切。
-        const tilesetCache = new Map();
+        const cache = new Map();
         const getFrameTexture = (tileId) => {
             var _a, _b;
             if (tileId <= 0)
                 return null;
             const idx = tileId - 1;
-            const cached = tilesetCache.get(idx);
+            const cached = cache.get(idx);
             if (cached)
                 return cached;
             const col = idx % cols;
@@ -217,19 +1310,14 @@ let TilemapSystem = class TilemapSystem extends Renderer {
             const x = margin + col * (tileW + spacing);
             const y = margin + row * (tileH + spacing);
             try {
-                // PixiJS v8: 用源纹理 + frame Rectangle 创建子纹理
                 const source = (_b = (_a = base.source) !== null && _a !== void 0 ? _a : base.baseTexture) !== null && _b !== void 0 ? _b : base;
-                const sub = new Texture({
-                    source,
-                    frame: new Rectangle(x, y, tileW, tileH),
-                });
-                tilesetCache.set(idx, sub);
+                const sub = new Texture({ source, frame: new Rectangle(x, y, tileW, tileH) });
+                cache.set(idx, sub);
                 record.frameTextures.push(sub);
                 return sub;
             }
             catch (e) {
                 if (typeof console !== 'undefined') {
-                    // eslint-disable-next-line no-console
                     console.warn('[Tilemap] Texture slice failed, falling back to base', e);
                 }
                 return base;
@@ -271,26 +1359,1213 @@ let TilemapSystem = class TilemapSystem extends Renderer {
             record.layerContainers.push(layerContainer);
         }
     }
+    /* ──────────────────────────────────────────────────── v2 chunked path ── */
+    loadV2Tileset(component) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!component.tilemapRef)
+                return null;
+            const res = yield resource.getResource(component.tilemapRef);
+            if (!res)
+                return null;
+            const json = (_a = res.instance) !== null && _a !== void 0 ? _a : (_b = res.data) === null || _b === void 0 ? void 0 : _b.json;
+            if (!json || json.kind !== 'tileset') {
+                if (typeof console !== 'undefined') {
+                    console.error(`[Tilemap] resource '${component.tilemapRef}' is not a TileSet document`);
+                }
+                return null;
+            }
+            return makeLoadedTileset(json);
+        });
+    }
+    loadAtlasTextures(record, loaded) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const assetsToLoad = new Set();
+            for (const src of loaded.sourcesBySlot) {
+                if (src.kind === 'atlas' && src.textureAsset)
+                    assetsToLoad.add(src.textureAsset);
+            }
+            yield Promise.all(Array.from(assetsToLoad).map((assetId) => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b, _c;
+                try {
+                    const res = yield resource.getResource(assetId);
+                    const texture = (_c = (_a = res === null || res === void 0 ? void 0 : res.instance) !== null && _a !== void 0 ? _a : (_b = res === null || res === void 0 ? void 0 : res.data) === null || _b === void 0 ? void 0 : _b.image) !== null && _c !== void 0 ? _c : null;
+                    if (texture)
+                        record.atlasTextures.set(assetId, texture);
+                }
+                catch (e) {
+                    if (typeof console !== 'undefined') {
+                        console.warn(`[Tilemap] failed to load atlas asset '${assetId}'`, e);
+                    }
+                }
+            })));
+        });
+    }
+    tearDownChildrenV2(record) {
+        for (const { container } of record.layerContainersV2.values()) {
+            record.root.removeChild(container);
+            container.destroy({ children: true });
+        }
+        record.layerContainersV2.clear();
+        for (const tex of record.frameTexturesV2.values()) {
+            try {
+                tex.destroy(false);
+            }
+            catch (_a) {
+                /* ignore */
+            }
+        }
+        record.frameTexturesV2.clear();
+        // Live Sprite references are now invalid (destroyed by container.destroy above).
+        record.animatedSpritesByAnimKey.clear();
+    }
+    buildLayersV2(record, component, animDriver) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        const loaded = record.loadedTileset;
+        if (!loaded)
+            return;
+        const cellW = (_b = (_a = component.cellSize) === null || _a === void 0 ? void 0 : _a.width) !== null && _b !== void 0 ? _b : loaded.tileWidth;
+        const cellH = (_d = (_c = component.cellSize) === null || _c === void 0 ? void 0 : _c.height) !== null && _d !== void 0 ? _d : loaded.tileHeight;
+        const originX = (_f = (_e = component.mapOrigin) === null || _e === void 0 ? void 0 : _e.x) !== null && _f !== void 0 ? _f : 0;
+        const originY = (_h = (_g = component.mapOrigin) === null || _g === void 0 ? void 0 : _g.y) !== null && _h !== void 0 ? _h : 0;
+        const layers = (_j = component.layersV2) !== null && _j !== void 0 ? _j : [];
+        // 按 zIndex 稳定排序
+        const sorted = layers
+            .map((l, i) => ({ layer: l, idx: i }))
+            .sort((a, b) => { var _a, _b; return ((_a = a.layer.zIndex) !== null && _a !== void 0 ? _a : 0) - ((_b = b.layer.zIndex) !== null && _b !== void 0 ? _b : 0); });
+        for (const { layer } of sorted) {
+            if (layer.enabled === false)
+                continue;
+            const container = new Container();
+            container.label = (_k = layer.name) !== null && _k !== void 0 ? _k : layer.id;
+            container.alpha = (_l = layer.opacity) !== null && _l !== void 0 ? _l : 1;
+            container.visible = layer.visible !== false;
+            const chunkContainers = new Map();
+            this.buildChunksForLayer(record, container, chunkContainers, layer, loaded, cellW, cellH, originX, originY, animDriver);
+            record.root.addChild(container);
+            record.layerContainersV2.set(layer.id, { container, chunkContainers });
+        }
+    }
+    // PERF-T-O4 (see ADR-0022): consider lazy chunk building tied to cullingBoundsHint.
+    // Chunks entering viewport: unbuilt → built. Leaving: built → evicted (destroy sprites,
+    // keep metadata). Trigger: tilemap > 50×50 OR > 100 chunks total + DIRTY_REBUILD_MS p99
+    // > 30ms. Needs a host writer for cullingBoundsHint first (T-L7 ship, no writer today).
+    buildChunksForLayer(record, layerContainer, chunkContainers, layer, loaded, cellW, cellH, originX, originY, animDriver) {
+        var _a;
+        const cellData = layer.cellData;
+        if (!cellData || !cellData.chunks)
+            return;
+        const visibleChunks = Object.entries(cellData.chunks).filter(([, b]) => b && b.nonEmpty > 0);
+        const totalChunksVisible = visibleChunks.length;
+        // C-2:viewport culling。
+        //
+        // 当 record.cullingBoundsHint 由 host 注入时,跳过任何 chunk 世界 bounds 与 hint 不相交的
+        // chunk(不 build sprite container,但保留 chunkContainers slot 为空让后续 lazy build 接入)。
+        // hint 未注入时 = 不剔除,行为兼容。
+        //
+        // 真正的 camera bounds 计算留下 cycle(参考 RendererSystem.application.renderer.view)。本 cycle
+        // 只做 probe emission + API ready,实际剔除生效仅当 host 主动注入 hint。
+        const cullingHint = (_a = record.cullingBoundsHint) !== null && _a !== void 0 ? _a : null;
+        let culledCount = 0;
+        this.probeBegin(TILEMAP_PROBE_NAMES.CULL_CHECK_MS);
+        for (const [chunkKey, blob] of visibleChunks) {
+            // Viewport culling check(per-chunk,O(1))。仅当 host 注入 hint 时启用。
+            if (cullingHint) {
+                const parts = chunkKey.split(',');
+                const ckX = Number.parseInt(parts[0], 10);
+                const ckY = Number.parseInt(parts[1], 10);
+                const chunkMinX = originX + ckX * CHUNK_SIZE$2 * cellW;
+                const chunkMinY = originY + ckY * CHUNK_SIZE$2 * cellH;
+                const chunkMaxX = chunkMinX + CHUNK_SIZE$2 * cellW;
+                const chunkMaxY = chunkMinY + CHUNK_SIZE$2 * cellH;
+                const intersects = chunkMaxX > cullingHint.minX &&
+                    chunkMinX < cullingHint.maxX &&
+                    chunkMaxY > cullingHint.minY &&
+                    chunkMinY < cullingHint.maxY;
+                if (!intersects) {
+                    culledCount++;
+                    continue;
+                }
+            }
+            const chunkContainer = new Container();
+            chunkContainer.label = `chunk-${chunkKey}`;
+            // P1-3:每个 chunk 先咨询 ChunkRenderStrategy 选择渲染路径。
+            // - sprite:populateChunkSprites(现有 MVP 路径,每非空 cell 一个 PIXI.Sprite)
+            // - mesh:  尝试 buildChunkMesh(...)。当前 isMeshPathAvailable()===false,buildChunkMesh
+            //          只返回 stub 空 Container,会被视为"mesh 不可用"自动降级 sprite。
+            // 计算 atlasesInChunk 需要 decode 一次 chunk 数据,扫一遍 unique sourceSlot 的 atlas source 个数。
+            //
+            // C-4:复用 decoded Int32Array — populateChunkSprites 内部会再 decode 一次,把这里 decode
+            //      结果透传过去避免重复工作(纯优化,行为兼容)。
+            let atlasesInChunk = 1;
+            let preDecoded = null;
+            try {
+                preDecoded = decodeChunk(blob);
+                const seenAtlasSlots = new Set();
+                for (let i = 0; i < preDecoded.length; i++) {
+                    const v = preDecoded[i];
+                    if (isEmptyCellValue(v))
+                        continue;
+                    const slot = v & 0xff;
+                    const src = loaded.sourcesBySlot[slot - 1];
+                    if (src && src.kind === 'atlas')
+                        seenAtlasSlots.add(slot);
+                }
+                atlasesInChunk = Math.max(1, seenAtlasSlots.size);
+            }
+            catch (_b) {
+                // Decode failure 在 populateChunkSprites 内会再次报警并跳过,这里保留默认 1 让 strategy 继续走。
+                atlasesInChunk = 1;
+                preDecoded = null;
+            }
+            const strategy = resolveChunkRenderStrategy({
+                nonEmptyCellsInChunk: blob.nonEmpty,
+                atlasesInChunk,
+                totalChunksVisible,
+                // preference 未来从 layer/component config 透出;当前一律走 auto。
+            });
+            let dispatched = 'sprite';
+            if (strategy === 'mesh') {
+                if (this.tryBuildMeshChunk(chunkContainer, chunkKey, blob, loaded, cellW, cellH, originX, originY, layer)) {
+                    dispatched = 'mesh';
+                }
+                else {
+                    // mesh path 当前不可用(stub),降级 sprite + 记录 fallback probe。
+                    dispatched = 'meshFallback';
+                    this.probeCount(TILEMAP_PROBE_NAMES.STRATEGY_MESH_FALLBACK_COUNT, 1);
+                    this.populateChunkSprites(chunkContainer, chunkKey, blob, record, loaded, cellW, cellH, originX, originY, layer, animDriver, preDecoded);
+                }
+            }
+            else {
+                this.populateChunkSprites(chunkContainer, chunkKey, blob, record, loaded, cellW, cellH, originX, originY, layer, animDriver, preDecoded);
+            }
+            if (dispatched === 'sprite')
+                this.probeCount(TILEMAP_PROBE_NAMES.STRATEGY_SPRITE_COUNT, 1);
+            else if (dispatched === 'mesh')
+                this.probeCount(TILEMAP_PROBE_NAMES.STRATEGY_MESH_COUNT, 1);
+            layerContainer.addChild(chunkContainer);
+            chunkContainers.set(chunkKey, chunkContainer);
+        }
+        this.probeEnd(TILEMAP_PROBE_NAMES.CULL_CHECK_MS);
+        if (culledCount > 0)
+            this.probeCount(TILEMAP_PROBE_NAMES.CULL_HITS_COUNT, culledCount);
+    }
+    /**
+     * 尝试用 mesh path 渲染 chunk(P1-3)。
+     *
+     * 当前实现策略:
+     * - 先检查 isMeshPathAvailable():当 false(本 cycle 默认),直接返回 false 让上层降级。
+     * - 当 true(后续 cycle 接入真实 shader 时):调 buildChunkMesh,把结果 add 到 chunkContainer。
+     *
+     * 出错 / 返回空容器一律视为不可用,返回 false 让 buildChunksForLayer 走 sprite 路径。
+     * 这样 "mesh path is dead code" 的局面变成 "mesh path 已 wired,降级有 probe 记录"。
+     */
+    tryBuildMeshChunk(chunkContainer, chunkKey, blob, loaded, cellW, cellH, _originX, _originY, _layer) {
+        return false;
+    }
+    // PERF-T-O3 (see ADR-0022): consider per-Tilemap Sprite pool. On tearDownChildrenV2,
+    // move sprites to pool instead of destroy({children: true}); pop from pool here before
+    // `new Sprite`. Trigger: GC pause profile shows alloc churn dominates + > 5000 sprites
+    // per rebuild cycle. Note: Mesh path (Phase 4) would sidestep this entirely.
+    populateChunkSprites(chunkContainer, chunkKey, blob, record, loaded, cellW, cellH, originX, originY, layer, animDriver, 
+    /** C-4:caller(buildChunksForLayer)decode 后透传,可省一次 decodeChunk 调用。 */
+    decoded) {
+        let arr;
+        if (decoded) {
+            arr = decoded;
+        }
+        else {
+            try {
+                arr = decodeChunk(blob);
+            }
+            catch (e) {
+                if (typeof console !== 'undefined') {
+                    console.warn(`[Tilemap] chunk decode failed for ${chunkKey}`, e);
+                }
+                return;
+            }
+        }
+        const parts = chunkKey.split(',');
+        const ckX = Number.parseInt(parts[0], 10);
+        const ckY = Number.parseInt(parts[1], 10);
+        const baseCx = ckX * CHUNK_SIZE$2;
+        const baseCy = ckY * CHUNK_SIZE$2;
+        const tintNum = parseHexTint(layer.modulate);
+        let spritesInChunk = 0;
+        for (let ly = 0; ly < CHUNK_SIZE$2; ly++) {
+            for (let lx = 0; lx < CHUNK_SIZE$2; lx++) {
+                const packed = arr[ly * CHUNK_SIZE$2 + lx];
+                if (isEmptyCellValue(packed))
+                    continue;
+                const cell = unpackCell(packed);
+                const tex = this.getAtlasFrameTexture(record, loaded, cell);
+                if (!tex)
+                    continue;
+                const sprite = new Sprite(tex);
+                spritesInChunk++;
+                sprite.x = originX + (baseCx + lx) * cellW;
+                sprite.y = originY + (baseCy + ly) * cellH;
+                sprite.width = cellW;
+                sprite.height = cellH;
+                if (cell.flipH)
+                    sprite.scale.x = -Math.abs(sprite.scale.x || 1);
+                if (cell.flipV)
+                    sprite.scale.y = -Math.abs(sprite.scale.y || 1);
+                if (cell.transpose)
+                    sprite.rotation = Math.PI / 2;
+                if (cell.flipH)
+                    sprite.x += cellW;
+                if (cell.flipV)
+                    sprite.y += cellH;
+                if (tintNum != null)
+                    sprite.tint = tintNum;
+                chunkContainer.addChild(sprite);
+                // Register sprite for live animation texture swap if this source tile is animated.
+                if (animDriver && animDriver.isAnimatedSource(cell.sourceSlot, cell.col, cell.row)) {
+                    const animKey = `${cell.sourceSlot},${cell.col},${cell.row}`;
+                    let bucket = record.animatedSpritesByAnimKey.get(animKey);
+                    if (!bucket) {
+                        bucket = [];
+                        record.animatedSpritesByAnimKey.set(animKey, bucket);
+                    }
+                    bucket.push(sprite);
+                }
+            }
+        }
+        if (spritesInChunk > 0) {
+            this.probeCount(TILEMAP_PROBE_NAMES.DRAWCALLS_COUNT, spritesInChunk);
+        }
+    }
+    getAtlasFrameTexture(record, loaded, cell) {
+        var _a, _b, _c, _d;
+        const src = loaded.sourcesBySlot[cell.sourceSlot - 1];
+        if (!src)
+            return null;
+        if (src.kind !== 'atlas') {
+            // P1-4:遇到 sceneCollection(或其他非 atlas)source。当前 runtime 暂时不实例化 prefab,
+            // 跳过该 cell 不渲染,但要让 host 看见这个 gap:
+            //   - 每个 record 内对同一 source 只 warn 一次(防 devtools 刷爆)
+            //   - 计数 probe 累加,host 可在 perf dashboard 上看到"static path 漏渲染 N 个 cell"
+            // 真正的 prefab placeholder 渲染留下一轮 cycle(参考 expandSceneCollectionSource / resolveCellPrefabName)。
+            if (src.kind === 'sceneCollection') {
+                this.probeCount(TILEMAP_PROBE_NAMES.SCENECOLLECTION_SKIPPED_COUNT, 1);
+                if (!record.sceneCollectionWarnedSourceIds.has(src.id)) {
+                    record.sceneCollectionWarnedSourceIds.add(src.id);
+                    if (typeof console !== 'undefined') {
+                        console.warn(`[Tilemap] sceneCollection source '${src.id}' cells are not yet rendered ` +
+                            `(prefab instantiation pending). Skipped cell at slot=${cell.sourceSlot} col=${cell.col} row=${cell.row}.`);
+                    }
+                }
+            }
+            return null;
+        }
+        const atlas = record.atlasTextures.get(src.textureAsset);
+        if (!atlas)
+            return null;
+        const margins = (_a = src.margins) !== null && _a !== void 0 ? _a : { x: 0, y: 0 };
+        const sep = (_b = src.separation) !== null && _b !== void 0 ? _b : { x: 0, y: 0 };
+        const fw = src.regionSize.width;
+        const fh = src.regionSize.height;
+        // T-N3 (Phase N):cache key 必须包含 regionSize / margins / separation —
+        // 同一个 textureAsset 在多个 source 配置(不同切片大小或留白)下会有不同的 frame 坐标,
+        // 旧的 `${textureAsset}#${col},${row}` 在 hot-swap tileset 后会 collision,误返回旧 frame。
+        // 现在把切片几何参数都拼进 key,确保不同配置之间隔离。
+        const cacheKey = `${src.textureAsset}#${fw}x${fh}|${margins.x},${margins.y}|${sep.x},${sep.y}#${cell.col},${cell.row}`;
+        const cached = record.frameTexturesV2.get(cacheKey);
+        if (cached)
+            return cached;
+        const fx = margins.x + cell.col * (fw + sep.x);
+        const fy = margins.y + cell.row * (fh + sep.y);
+        try {
+            const source = (_d = (_c = atlas.source) !== null && _c !== void 0 ? _c : atlas.baseTexture) !== null && _d !== void 0 ? _d : atlas;
+            const sub = new Texture({ source, frame: new Rectangle(fx, fy, fw, fh) });
+            record.frameTexturesV2.set(cacheKey, sub);
+            return sub;
+        }
+        catch (e) {
+            if (typeof console !== 'undefined') {
+                console.warn(`[Tilemap] frame slice failed for ${cacheKey}`, e);
+            }
+            return null;
+        }
+    }
     destroy() {
         var _a;
         for (const key in this.records) {
             const id = parseInt(key);
             const record = this.records[id];
-            this.tearDownChildren(record);
+            this.tearDownChildrenV1(record);
+            this.tearDownChildrenV2(record);
             const container = (_a = this.containerManager) === null || _a === void 0 ? void 0 : _a.getContainer(id);
             if (container)
                 container.removeChild(record.root);
             record.root.destroy({ children: true });
             delete this.records[id];
         }
+        // T-N2:解绑 visibility / context-loss listener,避免 system tear-down 后泄漏。
+        this.uninstallVisibilityHandlers();
     }
 };
 TilemapSystem.systemName = 'Tilemap';
 TilemapSystem = __decorate([
     decorators.componentObserver({
-        Tilemap: [{ prop: ['tileset'], deep: false }],
+        Tilemap: [
+            { prop: ['tileset'], deep: false },
+            { prop: ['tilemapRef'], deep: false },
+            // T-L1 (Phase L):watch layersV2 整体 ref 变化(浅观察)。
+            // Host 通过 `component.layersV2 = layersV2.slice()` 或重新 assign 触发 rebuild。
+            // 不用 deep:true:每个 chunk 编辑都触发 too 频繁(host 应用 batch + assign new array)。
+            // 当前实现:T-L1 走整 layer rebuild(reuse loadedTileset + atlasTextures);
+            // T-L4 增量 dirty chunk path 由 host 显式 invalidateChunks 触发,不走 observer。
+            { prop: ['layersV2'], deep: false },
+        ],
     })
 ], TilemapSystem);
-var TilemapSystem$1 = TilemapSystem;
+var TilemapSystem$1 = TilemapSystem;
+function parseHexTint(modulate) {
+    if (!modulate)
+        return undefined;
+    const m = /^#?([0-9a-fA-F]{6})(?:[0-9a-fA-F]{2})?$/.exec(modulate);
+    if (!m)
+        return undefined;
+    return parseInt(m[1], 16);
+}
+
+/**
+ * Autotile peering-bit index (Phase 2).
+ *
+ * 在 TileSet load 时构建,把每个 alt tile 的 peering bits 编进 hash key
+ * 实现 O(1) 邻居匹配。
+ *
+ * 数据模型:
+ * - 一个 terrainSet 有最多 8 个方向(Godot corners+sides),每个方向上当前
+ *   邻居的 terrain id 取值 0..255。
+ * - 把 8 个方向打包成一个 BigInt 作 exact-match key:每 byte 一个方向。
+ * - 通配 (`undefined` neighbor) 用 0xff 哨兵表示;查询时构造 actual neighborhood
+ *   也用 0xff 表示"无邻居 / 空 cell"。
+ * - exact 命中优先;否则在 wildcard 桶里按 Hamming 距离打分,取最小者(同分则
+ *   按 probability 加权随机 - 注意此处仅返回候选,不做 RNG)。
+ *
+ * 这里只暴露纯函数 + 数据结构,RNG/decision 留给 AutotileCommand 调用方。
+ */
+const NEIGHBOR_DIRECTIONS = [
+    "topLeft",
+    "top",
+    "topRight",
+    "right",
+    "bottomRight",
+    "bottom",
+    "bottomLeft",
+    "left",
+];
+/**
+ * 4-bit-per-direction × 8 directions = 32-bit number 作 hash key。
+ * terrain id 范围 0..14;15 (0xf) 作 NO_NEIGHBOR / wildcard 哨兵。
+ * v1 限制最多 15 个 terrain per terrain set,足够 Godot 47-tile Wang 集。
+ */
+const NO_NEIGHBOR = 0xf;
+const MAX_TERRAIN_ID = 14;
+/** 8 dirs × 4 bits = 32-bit number key. terrain id 限制 0..14。 */
+function packBits(values) {
+    var _a;
+    let key = 0;
+    for (let i = 0; i < 8; i++) {
+        const v = ((_a = values[i]) !== null && _a !== void 0 ? _a : NO_NEIGHBOR) & 0xf;
+        key |= v << (i * 4);
+    }
+    return key >>> 0;
+}
+function readNibble(key, slot) {
+    return (key >>> (slot * 4)) & 0xf;
+}
+/**
+ * Build the index from a TileSet's terrainSet candidates.
+ *
+ * `candidates` is the flat list of all (sourceSlot, col, row, altIdx) belonging
+ * to the given terrainSet, each with optional peeringBits + probability.
+ */
+class PeeringBitIndex {
+    constructor(terrainSetIndex) {
+        this.terrainSetIndex = terrainSetIndex;
+        this.exact = new Map();
+        this.wildcards = [];
+    }
+    add(candidate, bits) {
+        var _a;
+        const present = [];
+        const mask = [];
+        for (let i = 0; i < 8; i++) {
+            const dir = NEIGHBOR_DIRECTIONS[i];
+            const v = bits === null || bits === void 0 ? void 0 : bits[dir];
+            if (v === undefined) {
+                present.push(NO_NEIGHBOR);
+                mask.push(0); // wildcard nibble
+            }
+            else {
+                present.push(v & 0xf);
+                mask.push(0xf); // exact nibble required
+            }
+        }
+        const key = packBits(present);
+        const maskKey = packBits(mask);
+        const isFullExact = mask.every((m) => m === 0xf);
+        if (isFullExact) {
+            const list = (_a = this.exact.get(key)) !== null && _a !== void 0 ? _a : [];
+            list.push(candidate);
+            this.exact.set(key, list);
+        }
+        else {
+            this.wildcards.push({ key, mask: maskKey, candidate });
+        }
+    }
+    /**
+     * Match an `actual` neighborhood:8 byte values, NO_NEIGHBOR for "empty".
+     *
+     * Returns the set of best-matching candidates (Hamming distance 0 = exact).
+     * If no candidate matches at any distance, returns empty list.
+     */
+    match(actual) {
+        const key = packBits(actual);
+        const exact = this.exact.get(key);
+        if (exact && exact.length > 0) {
+            return { candidates: exact.slice(), exactMatch: true, bestHammingDistance: 0 };
+        }
+        let bestDist = Infinity;
+        let pool = [];
+        for (const { key: candKey, mask, candidate } of this.wildcards) {
+            let dist = 0;
+            let viable = true;
+            for (let slot = 0; slot < 8; slot++) {
+                const m = readNibble(mask, slot);
+                if (m === 0)
+                    continue; // wildcard slot
+                const a = readNibble(key, slot);
+                const b = readNibble(candKey, slot);
+                if (a !== b) {
+                    dist++;
+                    if (dist > bestDist) {
+                        viable = false;
+                        break;
+                    }
+                }
+            }
+            if (!viable)
+                continue;
+            if (dist < bestDist) {
+                bestDist = dist;
+                pool = [candidate];
+            }
+            else if (dist === bestDist) {
+                pool.push(candidate);
+            }
+        }
+        // Also consider exact buckets with masked dirs - matters when the actual
+        // has NO_NEIGHBOR slots that the exact entries can satisfy via wildcards.
+        // (Not needed in v1 — exact entries by definition have no wildcards.)
+        return { candidates: pool, exactMatch: false, bestHammingDistance: bestDist === Infinity ? -1 : bestDist };
+    }
+    get exactBucketCount() {
+        return this.exact.size;
+    }
+    get wildcardCount() {
+        return this.wildcards.length;
+    }
+}
+/**
+ * Probability-weighted picker — deterministic when seed is provided.
+ */
+function pickAutotileCandidate(candidates, rng) {
+    if (candidates.length === 0)
+        return null;
+    if (candidates.length === 1)
+        return candidates[0];
+    const totalProb = candidates.reduce((sum, c) => sum + (c.probability > 0 ? c.probability : 1), 0);
+    const t = rng() * totalProb;
+    let acc = 0;
+    for (const c of candidates) {
+        acc += c.probability > 0 ? c.probability : 1;
+        if (t < acc)
+            return c;
+    }
+    return candidates[candidates.length - 1];
+}
+
+/**
+ * Tile mesh shader 源码(G3)。
+ *
+ * PIXI v8 用 ProgramSource + Geometry,程序员手工写 GLSL 即可。这里 vert/frag
+ * 走 packed vertex attribute,flip/transpose 在 vertex 阶段通过 mat2 完成。
+ *
+ * Attribute 布局(每 vertex 32 bytes):
+ *   aPosition vec2 (8B)  cell 左上 + 局部偏移
+ *   aTexCoord vec2 (8B)  atlas UV 0..1
+ *   aFlags    vec4 (16B) [flipH, flipV, transpose, animPhase]
+ */
+const TILE_VERT_SHADER = `#version 300 es
+precision highp float;
+
+in vec2 aPosition;
+in vec2 aTexCoord;
+in vec4 aFlags;
+
+uniform mat3 uProjectionMatrix;
+uniform mat3 uWorldTransformMatrix;
+
+out vec2 vTexCoord;
+
+void main() {
+  vec3 worldPos = uWorldTransformMatrix * vec3(aPosition, 1.0);
+  gl_Position = vec4((uProjectionMatrix * worldPos).xy, 0.0, 1.0);
+
+  vec2 uv = aTexCoord;
+  if (aFlags.x > 0.5) uv.x = 1.0 - uv.x;
+  if (aFlags.y > 0.5) uv.y = 1.0 - uv.y;
+  if (aFlags.z > 0.5) { float t = uv.x; uv.x = uv.y; uv.y = t; }
+  vTexCoord = uv;
+}
+`;
+const TILE_FRAG_SHADER = `#version 300 es
+precision highp float;
+
+in vec2 vTexCoord;
+out vec4 fragColor;
+
+uniform sampler2D uTexture;
+uniform vec4 uModulate;
+
+void main() {
+  vec4 sampled = texture(uTexture, vTexCoord);
+  fragColor = sampled * uModulate;
+  if (fragColor.a < 0.01) discard;
+}
+`;
+const TILE_SHADER_SOURCES = {
+    vertex: TILE_VERT_SHADER,
+    fragment: TILE_FRAG_SHADER,
+};
+
+/**
+ * Build packed vertex/index buffers for a chunk mesh(G3)。
+ *
+ * 输入:Int32Array(256 packed cells)+ atlas region info。
+ * 输出:Float32Array (vertex data) + Uint16Array (indices)。
+ *
+ * 每非空 cell 4 vertices × 8 floats(2 pos + 2 uv + 4 flags) = 32 floats = 128B。
+ * 6 indices/quad × 2B = 12B index。
+ */
+const CHUNK_SIZE$1 = 16;
+const VERTS_PER_QUAD = 4;
+const FLOATS_PER_VERT = 8;
+/**
+ * Build geometry for a chunk。chunkX/Y 是 chunk 在世界坐标的左上(已含 mapOrigin)。
+ */
+function buildChunkGeometry(args) {
+    const { cells, chunkWorldX, chunkWorldY, cellWidth, cellHeight, atlasInfo } = args;
+    if (cells.length !== CHUNK_SIZE$1 * CHUNK_SIZE$1) {
+        throw new Error(`buildChunkGeometry: cells length ${cells.length} != ${CHUNK_SIZE$1 * CHUNK_SIZE$1}`);
+    }
+    let nonEmpty = 0;
+    for (let i = 0; i < cells.length; i++)
+        if (!isEmptyCellValue(cells[i]))
+            nonEmpty++;
+    const vertexData = new Float32Array(nonEmpty * VERTS_PER_QUAD * FLOATS_PER_VERT);
+    const indices = new Uint16Array(nonEmpty * 6);
+    let v = 0;
+    let i = 0;
+    let quadIdx = 0;
+    for (let ly = 0; ly < CHUNK_SIZE$1; ly++) {
+        for (let lx = 0; lx < CHUNK_SIZE$1; lx++) {
+            const packed = cells[ly * CHUNK_SIZE$1 + lx];
+            if (isEmptyCellValue(packed))
+                continue;
+            const cell = unpackCell(packed);
+            const x0 = chunkWorldX + lx * cellWidth;
+            const y0 = chunkWorldY + ly * cellHeight;
+            const x1 = x0 + cellWidth;
+            const y1 = y0 + cellHeight;
+            const u0 = (atlasInfo.margins.x + cell.col * (atlasInfo.regionWidth + atlasInfo.separation.x)) / atlasInfo.textureWidth;
+            const u1 = u0 + atlasInfo.regionWidth / atlasInfo.textureWidth;
+            const v0 = (atlasInfo.margins.y + cell.row * (atlasInfo.regionHeight + atlasInfo.separation.y)) / atlasInfo.textureHeight;
+            const v1 = v0 + atlasInfo.regionHeight / atlasInfo.textureHeight;
+            const fh = cell.flipH ? 1 : 0;
+            const fv = cell.flipV ? 1 : 0;
+            const tr = cell.transpose ? 1 : 0;
+            const animPhase = 0;
+            // 4 vertices (TL, TR, BR, BL)
+            const writeVert = (x, y, u, vv) => {
+                vertexData[v++] = x;
+                vertexData[v++] = y;
+                vertexData[v++] = u;
+                vertexData[v++] = vv;
+                vertexData[v++] = fh;
+                vertexData[v++] = fv;
+                vertexData[v++] = tr;
+                vertexData[v++] = animPhase;
+            };
+            writeVert(x0, y0, u0, v0);
+            writeVert(x1, y0, u1, v0);
+            writeVert(x1, y1, u1, v1);
+            writeVert(x0, y1, u0, v1);
+            const base = quadIdx * VERTS_PER_QUAD;
+            indices[i++] = base;
+            indices[i++] = base + 1;
+            indices[i++] = base + 2;
+            indices[i++] = base;
+            indices[i++] = base + 2;
+            indices[i++] = base + 3;
+            quadIdx++;
+        }
+    }
+    return { vertexData, indices, quadCount: quadIdx };
+}
+
+/**
+ * TileSet hot reload(H1)。
+ *
+ * dev mode 用文件 watcher 监听 `.tileset.json` 变化,变化时:
+ *   1. 重新 parse JSON → 新 TilesetDocumentRaw
+ *   2. diff 与旧版的 sources / tiles
+ *   3. 只 mark **受影响 cell 所在 chunk** dirty,不 rebuild 整 layer
+ *
+ * 本文件只 ship diff 与计算 affected cells 的纯函数。host(dev server 或 VSCode
+ * extension)负责文件 watch + 把新 raw 通过 resource.reload() 喂给运行时,运行时
+ * 调 `diffTilesetForChunkRebuild` + `computeAffectedChunks` 获取要 rebuild 的
+ * chunk set。
+ *
+ * ## 职责边界:source/tile-level coarse diff(plugin 内部 SSE pipeline 用)
+ *
+ * 这里的 `diffTilesetForChunkRebuild` 是 **chunk-rebuild 决策粒度** 的 diff:
+ * 只关心 "哪些 source 增删改 / 哪些 (col,row) tile key 变了",输出直接喂
+ * `computeAffectedChunks` 计算受影响 chunk set。它故意不下沉到 alternatives /
+ * animation / customData / physics / terrain 字段级别 — 任意一个变了对 chunk
+ * rebuild 的结论都一样(就是 rebuild)。
+ *
+ * 如果消费方是 **host UX 层**(显示 schema-level changes for AI revision / git-
+ * style preview / inspector diff 提示),需要的是 document-level detailed diff
+ * — 见 `@ali/eva-dsl` 的 `diffTilesetDocuments`(`libs/dsl/src/editor/tileset-
+ * diff.ts`),它会按 alternatives / animation / customData / physics / terrain
+ * 分桶报告每个 tile 的具体变化。
+ *
+ * 同名警告:历史上本文件的 `diffTilesetDocuments` 与 dsl 端同名但职责不同,
+ * 已改名为 `diffTilesetForChunkRebuild`;旧名保留 alias 供过渡。
+ */
+/**
+ * 计算两个 TilesetDocumentRaw 之间的 source/tile-level coarse diff,供
+ * `computeAffectedChunks` 决定哪些 chunk 要 rebuild。
+ *
+ * 不要与 `@ali/eva-dsl` 的 `diffTilesetDocuments` 混淆 — 后者是 document-level
+ * detailed diff(per alternative / animation / customData / physics / terrain),
+ * 用于 host UX 显示,不是 chunk-rebuild 决策。
+ */
+function diffTilesetForChunkRebuild(prev, next) {
+    const prevSources = new Map();
+    const nextSources = new Map();
+    for (const s of prev.sources)
+        prevSources.set(s.id, s);
+    for (const s of next.sources)
+        nextSources.set(s.id, s);
+    const addedSources = [];
+    const removedSourceIds = [];
+    const changedSourceIds = [];
+    for (const id of nextSources.keys()) {
+        if (!prevSources.has(id))
+            addedSources.push(nextSources.get(id));
+        else if (JSON.stringify(prevSources.get(id)) !== JSON.stringify(nextSources.get(id)))
+            changedSourceIds.push(id);
+    }
+    for (const id of prevSources.keys()) {
+        if (!nextSources.has(id))
+            removedSourceIds.push(id);
+    }
+    const addedTilesByKey = new Set();
+    const removedTilesByKey = new Set();
+    const changedTilesByKey = new Set();
+    const indexTiles = (src) => {
+        const m = new Map();
+        if (src.kind !== "atlas")
+            return m;
+        for (const t of src.tiles)
+            m.set(`${src.id}/${t.atlasCoords.col},${t.atlasCoords.row}`, t);
+        return m;
+    };
+    for (const [id, src] of nextSources) {
+        const prevSrc = prevSources.get(id);
+        if (!prevSrc) {
+            const tiles = indexTiles(src);
+            for (const k of tiles.keys())
+                addedTilesByKey.add(k);
+            continue;
+        }
+        const a = indexTiles(prevSrc);
+        const b = indexTiles(src);
+        for (const k of b.keys()) {
+            if (!a.has(k))
+                addedTilesByKey.add(k);
+            else if (JSON.stringify(a.get(k)) !== JSON.stringify(b.get(k)))
+                changedTilesByKey.add(k);
+        }
+        for (const k of a.keys()) {
+            if (!b.has(k))
+                removedTilesByKey.add(k);
+        }
+    }
+    for (const id of removedSourceIds) {
+        const a = indexTiles(prevSources.get(id));
+        for (const k of a.keys())
+            removedTilesByKey.add(k);
+    }
+    return { addedSources, removedSourceIds, changedSourceIds, addedTilesByKey, removedTilesByKey, changedTilesByKey };
+}
+/**
+ * @deprecated Use `diffTilesetForChunkRebuild`. Alias kept for transitional
+ * compatibility — the name collided with `@ali/eva-dsl`'s `diffTilesetDocuments`
+ * (document-level detailed diff for host UX), which has different semantics.
+ */
+const diffTilesetDocuments = diffTilesetForChunkRebuild;
+/**
+ * 给定 diff 结果 + 文档 chunks(`chunkKey → Int32Array`),返回需要 rebuild 的 chunk key set。
+ *
+ * 算法:遍历所有 chunks,对每个非空 cell,如果它引用的 atlas (sourceSlot, col, row) 在 changed
+ * /removed/added tile set 里,标记该 chunk dirty。
+ */
+function computeAffectedChunks(chunks, sourceIdBySlot, diff) {
+    const dirty = new Set();
+    const cellKeyMatches = (cellSlot, col, row) => {
+        const sourceId = sourceIdBySlot.get(cellSlot);
+        if (!sourceId)
+            return false;
+        const k = `${sourceId}/${col},${row}`;
+        return diff.changedTilesByKey.has(k) || diff.removedTilesByKey.has(k) || diff.addedTilesByKey.has(k);
+    };
+    for (const [chunkKey, arr] of Object.entries(chunks)) {
+        for (let i = 0; i < arr.length; i++) {
+            const packed = arr[i];
+            const slot = packed & 0xff;
+            if (slot === 0)
+                continue;
+            const col = (packed >>> 8) & 0xff;
+            const row = (packed >>> 16) & 0xff;
+            if (cellKeyMatches(slot, col, row)) {
+                dirty.add(chunkKey);
+                break;
+            }
+        }
+    }
+    return dirty;
+}
+
+/**
+ * SceneCollection source(H2)。
+ *
+ * 与 atlas source 并列;一个 sceneCollection source 的 tile 对应一个 prefab name,
+ * runtime 在 buildLayer 时不 instantiate sprite,而是 instantiate prefab(走 host 注入
+ * 的 prefab factory)。
+ *
+ * 本文件只 ship 解析 helper + 实例化接口,真实 prefab instantiation 留给 host
+ * (DSLRenderer 通常已经有 prefab → GameObject 的 builder)。
+ */
+/**
+ * 把 sceneCollection source 展开成 prefab ref 数组。
+ */
+function expandSceneCollectionSource(src) {
+    if (src.kind !== "sceneCollection")
+        return [];
+    return src.prefabRefs.map((p, i) => ({ sourceId: src.id, prefabName: p, index: i }));
+}
+/**
+ * 给定 packed cell + source 列表,查这个 cell 对应的 prefab name(如果是 scene-collection
+ * source);atlas source 返回 null。
+ */
+function resolveCellPrefabName(packed, sourcesBySlot) {
+    var _a;
+    const slot = packed & 0xff;
+    if (slot === 0)
+        return null;
+    const src = sourcesBySlot[slot - 1];
+    if (!src || src.kind !== "sceneCollection")
+        return null;
+    const col = (packed >>> 8) & 0xff;
+    // scene-collection 只用 col 作为 index(row 保留 0)
+    return (_a = src.prefabRefs[col]) !== null && _a !== void 0 ? _a : null;
+}
+
+/**
+ * DecompositionCache(C1,关联 ADR-0019)。
+ *
+ * TileSet 上每 alt tile 可能有任意 polygon collision shape。Matter.js 要求 convex,
+ * concave 需 poly-decomp。decompose 是 O(n²),不能每 paint stroke 重做。
+ *
+ * 这里在 TileSet load 时把每 alt tile 的 polygon list 一次性 decompose 成 convex parts,
+ * 后续 stroke 只走 translate;decompose 结果按 (sourceSlot, col, row, altIdx, layerId) key 缓存。
+ *
+ * 当前 cycle:cache 数据结构 + key 生成 + LRU eviction skeleton 实现完毕,真 poly-decomp
+ * 在 Phase 3 落地时接入 npm `poly-decomp` 包。
+ */
+function cacheKeyOf(k) {
+    return `${k.sourceSlot},${k.col},${k.row},${k.altIdx},${k.layerId}`;
+}
+class DecompositionCache {
+    constructor(maxEntries = 1000) {
+        this.cache = new Map();
+        this.accessOrder = new Map();
+        this.accessCounter = 0;
+        this.maxEntries = maxEntries;
+    }
+    get(key) {
+        const k = cacheKeyOf(key);
+        const cached = this.cache.get(k);
+        if (cached)
+            this.accessOrder.set(k, ++this.accessCounter);
+        return cached;
+    }
+    set(key, value) {
+        const k = cacheKeyOf(key);
+        this.cache.set(k, value);
+        this.accessOrder.set(k, ++this.accessCounter);
+        if (this.cache.size > this.maxEntries)
+            this.evictLRU();
+    }
+    has(key) {
+        return this.cache.has(cacheKeyOf(key));
+    }
+    clear() {
+        this.cache.clear();
+        this.accessOrder.clear();
+        this.accessCounter = 0;
+    }
+    get size() {
+        return this.cache.size;
+    }
+    evictLRU() {
+        let oldestKey;
+        let oldestAccess = Infinity;
+        for (const [k, c] of this.accessOrder) {
+            if (c < oldestAccess) {
+                oldestAccess = c;
+                oldestKey = k;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+            this.accessOrder.delete(oldestKey);
+        }
+    }
+}
+/**
+ * 把局部 polygon 平移到目标 cell 的世界坐标。
+ * Phase 3 在 chunk rebuild 时调用,把 cached convex parts 复用到任意 cell 位置。
+ */
+function translateConvexParts(parts, dx, dy) {
+    return parts.map((p) => ({
+        vertices: p.vertices.map((v) => ({ x: v.x + dx, y: v.y + dy })),
+    }));
+}
+/**
+ * 判定 polygon 是否为 convex(简单凸多边形)。
+ *
+ * 算法:遍历每一对相邻边,计算 cross product;如所有非零 cross 同号即 convex。
+ * collinear(cross=0)被视为退化情况,不影响判定。
+ *
+ * 此函数 export 出去让 host UI 可以在用户绘制 polygon 时做 pre-check,
+ * 在视觉层提示 concave warning,避免落入 decomposePolygon 的 throw。
+ */
+function isConvex(polygon) {
+    if (polygon.length < 3)
+        return true;
+    let sign = 0;
+    const n = polygon.length;
+    for (let i = 0; i < n; i++) {
+        const a = polygon[i];
+        const b = polygon[(i + 1) % n];
+        const c = polygon[(i + 2) % n];
+        const ex1 = b.x - a.x;
+        const ey1 = b.y - a.y;
+        const ex2 = c.x - b.x;
+        const ey2 = c.y - b.y;
+        const cross = ex1 * ey2 - ey1 * ex2;
+        if (cross !== 0) {
+            if (sign === 0)
+                sign = cross > 0 ? 1 : -1;
+            else if ((cross > 0 ? 1 : -1) !== sign)
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * 暂时占位的 polygon → convex parts 函数。
+ * Phase 3 落地 npm `poly-decomp` 时替换实现;当前假设输入已 convex,
+ * 输入 concave polygon(L/T/U/凹槽)会 throw,防止静默产出错误 Matter body。
+ *
+ * Host 应在 paint 前用 isConvex 做 pre-check,把 concave 提示给用户,避免触发 throw。
+ */
+function decomposePolygon(polygon) {
+    if (polygon.length < 3)
+        return [];
+    if (!isConvex(polygon)) {
+        const err = new Error(`decomposePolygon: input polygon (${polygon.length} vertices) is non-convex. ` +
+            `This is a placeholder implementation that assumes convex input — concave polygons silently produce ` +
+            `invalid Matter.js bodies. Real concave decomposition requires the 'poly-decomp' npm dependency ` +
+            `(see ADR-0019 Phase 1). If you need concave physics tiles right now, split into convex parts manually.`);
+        if (typeof console !== 'undefined')
+            console.error('[Tilemap]', err.message);
+        throw err;
+    }
+    return [{ vertices: polygon.slice() }];
+}
+
+/**
+ * 把 DecompositionCache(string-key)适配出 numeric-key 接口供 TileMapStaticBody 用。
+ * numeric key = (slot << 24) | (altIdx << 18) | (row << 9) | col。
+ * 这套 packed key 不需要 layerId(同 cell 跨 layer 的 physics 几何相同)。
+ */
+function cacheKeyOfNum(slot, col, row, altIdx) {
+    return (((slot & 0xff) << 24) | ((altIdx & 0x3f) << 18) | ((row & 0x1ff) << 9) | (col & 0x1ff)) >>> 0;
+}
+DecompositionCache.prototype.getNum = function (key) {
+    return this.get({ sourceSlot: (key >>> 24) & 0xff, altIdx: (key >>> 18) & 0x3f, row: (key >>> 9) & 0x1ff, col: key & 0x1ff, layerId: "__num__" });
+};
+DecompositionCache.prototype.setNum = function (key, value) {
+    this.set({ sourceSlot: (key >>> 24) & 0xff, altIdx: (key >>> 18) & 0x3f, row: (key >>> 9) & 0x1ff, col: key & 0x1ff, layerId: "__num__" }, value);
+};
+
+/**
+ * Body source registry shim(G1)。
+ *
+ * 真实 plugin-matterjs `registerBodySource` API 落地需要 ADR-0019 评审 + BREAKING
+ * change。这里先 ship 一个完全相同的抽象层,plugin-renderer-tilemap 内部用它建
+ * TileMapStaticBody body 集合。host 在初始化时把这个 registry 喂给 plugin-matterjs
+ * (或直接消费它建 Matter.Composite)。
+ *
+ * 当 ADR-0019 落地后,只需要把这里的 import 切到 @eva/plugin-matterjs/lib/body-source。
+ */
+class BodySourceRegistryImpl {
+    constructor() {
+        this.builders = new Map();
+    }
+    register(name, builder) {
+        this.builders.set(name, builder);
+    }
+    unregister(name) {
+        this.builders.delete(name);
+    }
+    has(name) {
+        return this.builders.has(name);
+    }
+    build(name, ctx) {
+        const b = this.builders.get(name);
+        if (!b)
+            return null;
+        return b(ctx);
+    }
+    listRegisteredNames() {
+        return Array.from(this.builders.keys());
+    }
+    clear() {
+        this.builders.clear();
+    }
+}
+const TILEMAP_BODY_SOURCE_REGISTRY = new BodySourceRegistryImpl();
+
+/**
+ * TileMapStaticBody(G2)。
+ *
+ * 走 chunked cellData,把每 painted cell 配的 physics polygons 通过 DecompositionCache
+ * 转 convex parts + translate 到 cell world 位置,产出 BodyDefinition[] 给
+ * BodySourceRegistry。
+ */
+const CHUNK_SIZE = 16;
+function unpackSlot(packed) {
+    return packed & 0xff;
+}
+function unpackCol(packed) {
+    return (packed >>> 8) & 0xff;
+}
+function unpackRow(packed) {
+    return (packed >>> 16) & 0xff;
+}
+function unpackAlt(packed) {
+    return (packed >>> 24) & 0x1f;
+}
+/**
+ * Build BodyDefinition[] for an entire TileMap layer。
+ *
+ * 每 cell 引用 TileSet 中对应 tile 的 physics polygons:
+ *   - 在 cache 里查 cached convex parts(load 时已 decompose)
+ *   - 没缓存就 decomposePolygon stub(当前 polygon=convex 直接返回)
+ *   - translate 到 cell world 位置
+ */
+function buildTileMapStaticBodies(input, ctx) {
+    var _a;
+    const out = [];
+    for (const [chunkKey, arr] of Object.entries(input.chunksByKey)) {
+        const [ckxStr, ckyStr] = chunkKey.split(",");
+        const ckx = Number.parseInt(ckxStr, 10);
+        const cky = Number.parseInt(ckyStr, 10);
+        if (!Number.isFinite(ckx) || !Number.isFinite(cky))
+            continue;
+        for (let ly = 0; ly < CHUNK_SIZE; ly++) {
+            for (let lx = 0; lx < CHUNK_SIZE; lx++) {
+                const packed = arr[ly * CHUNK_SIZE + lx];
+                const slot = unpackSlot(packed);
+                if (slot === 0)
+                    continue;
+                const col = unpackCol(packed);
+                const row = unpackRow(packed);
+                const altIdx = unpackAlt(packed);
+                const physicsKey = `${slot},${col},${row},${altIdx}`;
+                const physicsEntries = input.physicsByCellKey.get(physicsKey);
+                if (!physicsEntries || physicsEntries.length === 0)
+                    continue;
+                const cellWorldX = input.mapOriginX + (ckx * CHUNK_SIZE + lx) * input.cellWidth + ctx.worldX;
+                const cellWorldY = input.mapOriginY + (cky * CHUNK_SIZE + ly) * input.cellHeight + ctx.worldY;
+                for (const entry of physicsEntries) {
+                    for (const poly of entry.polygons) {
+                        const cacheKeyNum = cacheKeyOfNum(slot, col, row, altIdx);
+                        let parts = (_a = input.cache.getNum(cacheKeyNum)) === null || _a === void 0 ? void 0 : _a.parts;
+                        if (!parts) {
+                            parts = decomposePolygon(poly.points);
+                            input.cache.setNum(cacheKeyNum, { parts });
+                        }
+                        const translated = translateConvexParts(parts, cellWorldX, cellWorldY);
+                        for (let pi = 0; pi < translated.length; pi++) {
+                            out.push({
+                                id: `tile-${chunkKey}-${lx}-${ly}-${entry.layerId}-${pi}`,
+                                vertices: translated[pi].vertices,
+                                centerX: cellWorldX + input.cellWidth / 2,
+                                centerY: cellWorldY + input.cellHeight / 2,
+                                isStatic: true,
+                                oneWay: entry.oneWay,
+                                friction: entry.friction,
+                                restitution: entry.restitution,
+                                metadata: { layerId: entry.layerId, chunkKey, cellLocal: [lx, ly] },
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * Host-side stop-gap for ADR-0019 plugin-matterjs `registerBodySource` API.
+ *
+ * Until the matter-side `registerBodySource` PR lands (ADR-0019 Phase 1), the
+ * tilemap plugin cannot push BodyDefinition[] directly into Matter.World.
+ * This module gives the host a thin adapter: pull BodyDefinition[] out of the
+ * tilemap record, hand them to a host-supplied registrar that knows how to
+ * create one Matter.Body per def (typically by spawning child GameObjects with
+ * Physics components, since that path is already wired through plugin-matterjs).
+ *
+ * Once ADR-0019 ships, this adapter is replaced by a direct registry handshake
+ * inside system.ts and this file becomes deprecated; the deprecation is one
+ * import-line change for hosts.
+ */
+/**
+ * Build BodyDefinition[] for a TileMap entity and group by physics layer.
+ *
+ * The host is expected to call this after `system.handleAdd` resolves and the
+ * record has its `loadedTileset`. The host passes:
+ *   - chunksByKey from `decodeChunk(layer.cellData.chunks[key])`
+ *   - physicsByCellKey derived from `loadedTileset.raw.sources[i].tiles[j].alternatives[k].physics`
+ *
+ * This keeps the runtime plugin agnostic of how the host actually registers bodies
+ * with Matter (child GameObject + Physics component vs. direct Matter.Composite.add).
+ */
+function buildTileMapStaticBodyDefinitions(input, ctx, 
+/**
+ * T-L3 (Phase L):optional probe registry。当 host 注入时,本函数会:
+ *   - PHYSICS_REBAKE_MS:wrap 整个 buildTileMapStaticBodies 调用计时
+ *   - BODIES_TOTAL:emit gauge,反映当前生成的 body 总数
+ *   - BODIES_CREATED:counter+totalBodyCount,统计累计 created
+ * 不注入时 silent no-op,保持与现有 caller 行为兼容。
+ * BODIES_DESTROYED 暂未 emit(无清晰 destroy point),Cycle 2 再补。
+ */
+probes) {
+    var _a, _b;
+    probes === null || probes === void 0 ? void 0 : probes.beginTiming(TILEMAP_PROBE_NAMES.PHYSICS_REBAKE_MS);
+    let bodies;
+    try {
+        bodies = buildTileMapStaticBodies(input, ctx);
+    }
+    finally {
+        probes === null || probes === void 0 ? void 0 : probes.endTiming(TILEMAP_PROBE_NAMES.PHYSICS_REBAKE_MS);
+    }
+    const bodiesByLayerId = new Map();
+    for (const b of bodies) {
+        const layerId = (_b = (_a = b.metadata) === null || _a === void 0 ? void 0 : _a.layerId) !== null && _b !== void 0 ? _b : "<unlabeled>";
+        let bucket = bodiesByLayerId.get(layerId);
+        if (!bucket) {
+            bucket = [];
+            bodiesByLayerId.set(layerId, bucket);
+        }
+        bucket.push(b);
+    }
+    const totalBodyCount = bodies.length;
+    probes === null || probes === void 0 ? void 0 : probes.gauge(TILEMAP_PROBE_NAMES.BODIES_TOTAL, totalBodyCount);
+    if (totalBodyCount > 0) {
+        probes === null || probes === void 0 ? void 0 : probes.count(TILEMAP_PROBE_NAMES.BODIES_CREATED, totalBodyCount);
+    }
+    return { bodies, totalBodyCount, bodiesByLayerId };
+}
+/**
+ * Extract `physicsByCellKey` Map from a LoadedTileset's raw atlas tile data.
+ *
+ * Each tile alternative may carry `physics: Array<{ layerId, polygons, oneWay, friction, restitution }>`.
+ * The returned Map is keyed by `${slot},${col},${row},${altIdx}` matching the cell-packed
+ * id format used by `buildTileMapStaticBodies`.
+ */
+function extractPhysicsByCellKey(tilesetRaw) {
+    const out = new Map();
+    for (let slotIdx = 0; slotIdx < tilesetRaw.sources.length; slotIdx++) {
+        const src = tilesetRaw.sources[slotIdx];
+        if (!src || src.kind !== "atlas" || !src.tiles)
+            continue;
+        const slot = slotIdx + 1; // 1-based to match unpackSlot
+        for (const tile of src.tiles) {
+            const { col, row } = tile.atlasCoords;
+            for (const alt of tile.alternatives) {
+                if (!alt.physics || alt.physics.length === 0)
+                    continue;
+                const key = `${slot},${col},${row},${alt.altId & 0x1f}`;
+                out.set(key, alt.physics);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Status flag — true once ADR-0019 lands and this host stop-gap can be removed.
+ *
+ * Hosts can branch on this to switch from the child-GameObject workaround to a
+ * direct registry handshake. Until then, importing this module signals "I am
+ * using the pre-ADR-0019 path".
+ */
+const ADR_0019_NATIVE_REGISTRY_AVAILABLE = false;
+
+// 注册 TILESET 资源类型。此处 try/catch 防止多次 import 重复注册时抛错。
+try {
+    resource.registerResourceType('TILESET');
+}
+catch (_a) {
+    /* already registered */
+}
+// 注册 TILESET 资源的 instance 解析回调:把 raw json 作为 instance 暴露,
+// 同时把 src.json.data 拷贝到 res.data.json,与 lottie/audio 资源约定一致。
+try {
+    resource.registerInstance('TILESET', (res) => {
+        var _a, _b, _c, _d;
+        // pixi.js v8 Assets.load 把 JSON 内容放在 res.data.json 或 src.json.data,
+        // 不同版本路径不一致:这里两边都兜底,返回 raw JSON 作为 instance。
+        const fromData = (_a = res.data) === null || _a === void 0 ? void 0 : _a.json;
+        const fromSrc = (_c = (_b = res.src) === null || _b === void 0 ? void 0 : _b.json) === null || _c === void 0 ? void 0 : _c.data;
+        return (_d = fromData !== null && fromData !== void 0 ? fromData : fromSrc) !== null && _d !== void 0 ? _d : null;
+    });
+}
+catch (_b) {
+    /* already registered */
+}
 
-export { Tilemap, TilemapSystem$1 as TilemapSystem };
+export { ADR_0019_NATIVE_REGISTRY_AVAILABLE, CHUNK_SIZE$2 as CHUNK_SIZE, DecompositionCache, MAX_TERRAIN_ID, NEIGHBOR_DIRECTIONS, NO_NEIGHBOR, PeeringBitIndex, TILEMAP_BODY_SOURCE_REGISTRY, TILEMAP_PROBE_NAMES, TILE_FRAG_SHADER, TILE_SHADER_SOURCES, TILE_VERT_SHADER, TileAnimationDriver, Tilemap, TilemapSystem$1 as TilemapSystem, adaptGamePerfProbes, buildChunkGeometry, buildChunkMesh, buildTileMapStaticBodies, buildTileMapStaticBodyDefinitions, cacheKeyOf, cacheKeyOfNum, computeAffectedChunks, createInMemoryProbeRegistry, decodeChunk, decomposePolygon, diffTilesetDocuments, diffTilesetForChunkRebuild, estimateChunkMeshMemoryKB, estimateSpriteNodes, expandSceneCollectionSource, extractPhysicsByCellKey, getRequiredTilemapProbes, isEmptyCellValue, isMeshPathAvailable, makeLoadedTileset, pickAutotileCandidate, resolveCellPrefabName, resolveChunkRenderStrategy, translateConvexParts, unpackCell };