@umicat/phaser-sdk 1.0.8 → 1.0.10

package/SDK-GUIDE.md

@@ -589,16 +589,48 @@ The `assets[]` table is the single source of truth for asset loading in scene-as
 }
 ```
 
-`kind` is the entity discriminator with seven variants: `sprite` / `rect` / `circle` / `code-rendered` / `group` / `tilemap` / `trigger`. Per-kind render fields live at the entity root (no nested `visual` sub-object):
+`kind` is the entity discriminator: `sprite` / `rect` / `circle` / `code-rendered` / `group` / `tilemap-ref` / `trigger` / `prefab-ref` (plus the deprecated embedded `tilemap`). Per-kind render fields live at the entity root (no nested `visual` sub-object):
 
 - `sprite` → `assetId`, optional `frame` / `tint` / `alpha` / `flipX` / `flipY`
 - `rect` → `width`, `height`, optional `fillColor` / `strokeColor` / `strokeWidth` / `alpha`
 - `circle` → `radius`, optional `fillColor` / `strokeColor` / `strokeWidth` / `alpha`
 - `code-rendered` → `script` (path to render script), optional `params` / `width` / `height`
-- `tilemap` → `tileSize`, `size`, `layers[]`
+- `tilemap-ref` → `tilemapId` — reference to a standalone tilemap file at `public/tilemaps/<tilemapId>.json` (see "Tilemaps as standalone resources" below). The scene carries only the reference + placement; the map data lives in the file.
+- `tilemap` → `tileSize`, `size`, `layers[]` — **deprecated** embedded form (tilemap-as-resource, ADR-008). Still renders so existing scenes keep working; don't author new ones — write a tilemap file + `tilemap-ref` instead.
 - `trigger` → `shape`, optional `description` / `targets` / `behaviorScript`
 - `group` → `children[]`
 
+### Tilemaps as standalone resources (ADR-008)
+
+A tilemap's cell data is a project resource, not scene content. Each map is one JSON file at `public/tilemaps/<id>.json`:
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "id": "forest-floor",            // must match the filename stem
+  "name": "Forest Floor",
+  "tileSize": { "width": 32, "height": 32 },   // pixels per cell
+  "size": { "width": 40, "height": 30 },       // map size in CELLS
+  "humanCurated": true,            // set by Tilemap Studio; agents must ask before overwriting cells
+  "metadata": { "createdAt": "...", "editedAt": "...", "author": "user" },
+  "layers": [                      // same layer shape as the embedded form (minus editor-only `locked`)
+    { "id": "ground", "tilesetIds": ["forest-tileset"], "z": 0,
+      "data": [[0, 1, null, 2]] }  // row-major, size.height rows × size.width cols, null = empty
+  ]
+}
+```
+
+The scene references it with a `tilemap-ref` entity — placement only:
+
+```json
+{ "id": "e-ground", "kind": "tilemap-ref", "tilemapId": "forest-floor",
+  "role": "terrain", "transform": { "x": 640, "y": 360, "depth": 1 } }
+```
+
+`loadWorldScene` fetches every referenced tilemap file before spawning (clear error naming the expected `public/tilemaps/<id>.json` path when one is missing) and renders it through the SAME runtime path the embedded form uses — autotile, per-tile metadata/collision, and animated tiles all work identically, and `getTilemapAt` / `addTilemapCollider` are unchanged. To change a map, edit the FILE; to move it, edit the entity's transform. The in-Editor paint RPC (`setTilemapTool` / `editTilemap` / `tilemapEdited`) is deprecated — humans paint in Tilemap Studio, agents write the file.
+
+For a standalone canvas (e.g. Tilemap Studio's preview), `renderTilemapPreview(scene, tilemapFile, resolveAsset, position?)` renders a `TilemapFile` in any Phaser scene without a scene file or entity registry — the caller loads the tileset textures first. Related exports: `TILEMAPS_BASE`, `tilemapFilePath(id)`, `tilemapFileCacheKey(id)`, `loadReferencedTilemapFiles(scene, sceneFile)`, types `TilemapRefEntity` / `TilemapFile` / `TilemapFileLayer`.
+
 **Optional physics body (since 0.2.54).** Any renderable entity (`sprite` / `rect` / `circle` / `code-rendered`) may carry a `physics` block — the same shape prefabs use (see the Prefabs section's `physics` field reference). When present, `loadWorldScene` gives the entity an Arcade body, sized and offset per the block, so behavior code doesn't call `physics.add.existing` / `body.setSize` for it. A code-rendered platform, for example, can declare `"physics": { "bodyW": 200, "bodyH": 32, "immovable": true }` and be collidable the moment the scene loads.
 
 **World gravity from scene data (since 0.2.55).** A world scene's `world.physics.gravity` (`{ x?, y? }`) — or, as a manifest-wide default, `manifest.globals.physics.gravity` — is applied to the scene's Arcade physics world by `loadWorldScene`. Scene-level wins over the manifest global. Example: a platformer's `world/main.json` carries `"world": { "width": 5120, "height": 720, "physics": { "gravity": { "x": 0, "y": 700 } } }` and the player just falls — no `this.physics.world.gravity` line in `GameScene.ts`. (Before 0.2.55 these two fields were typed but inert; only `game.json`'s `GameConfig.physics.gravity`, wired through `createUmicatGame` in `main.ts`, took effect.)

package/dist/editor/EditorBridge.d.ts

@@ -94,6 +94,11 @@ export declare function getEditorCamera(game: Phaser.Game): Phaser.Cameras.Scene
  * Without the await, addLayer's `textures.exists()` check fails on
  * the in-flight load → skips layer creation → painter can't find
  * layer → click falls through to drag-the-entity.
+ *
+ * @deprecated Tilemap-as-resource (ADR-008, Phase 4) — edit the standalone
+ * `public/tilemaps/{id}.json` file instead (Tilemap Studio / agent file
+ * write). Kept fully functional for legacy embedded tilemaps + undo replay
+ * on unmigrated hosts; host side removed in Phase 5.
  */
 export declare function handleEditTilemap(game: Phaser.Game, entityId: string, ops: TilemapEditOp[], manifestAsset?: AssetRecord): Promise<void>;
 /**
@@ -111,5 +116,9 @@ export declare function findTilemapLayerById(container: Phaser.GameObjects.Conta
  *
  * The optional `asset` arg is required for `autotilePaint` (the only op
  * that needs to resolve a terrain's ruleMap); other ops ignore it.
+ *
+ * @deprecated Tilemap-as-resource (ADR-008, Phase 4) — cell data now lives
+ * in `public/tilemaps/{id}.json`; edit the file. Behavior unchanged for
+ * legacy embedded tilemaps + the deprecated paint path.
  */
 export declare function applyTilemapOp(layer: Phaser.Tilemaps.TilemapLayer, op: TilemapEditOp, asset?: AssetRecord | null): void;

package/dist/editor/EditorBridge.js

@@ -8,7 +8,8 @@ import { getEntityRegistry } from '../scene/EntityRegistry.js';
 import { applyAssetHitbox, applyTilesetAnimations, applyTilesetTileMetadata, applyTrackedHitArea, parseColor, resetTilesetAnimationsToRoot, spawnEntity } from '../scene/spawnEntity.js';
 import { applyAutotile, findTerrain, getAutotileKind, invalidateAutotileCells } from '../scene/autotile.js';
 import { resolveRenderScript } from '../scene/renderScripts.js';
-import { getManifest } from '../scene/SceneLoader.js';
+import { getManifest, tilemapFilePath } from '../scene/SceneLoader.js';
+import { tilemapFileCacheKey } from '../scene/types.js';
 import { getRules, patchRule } from '../scene/Rules.js';
 import { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './EditorOverlayScene.js';
 import { getEditorState, setEditorActive, setSelection, getSelection, getEditorMode, setEditorMode, getActiveSceneId, setActiveSceneId, setDebugOverlayState, setTilemapToolState, } from './EditorState.js';
@@ -1276,6 +1277,31 @@ async function createEntity(game, entity, manifestAsset) {
             }
         }
     }
+    else if (entity.kind === 'tilemap-ref') {
+        // Tilemap-as-resource (ADR-008): the ref's cell data lives in the
+        // standalone file `public/tilemaps/{tilemapId}.json`. At scene LOAD,
+        // SceneLoader's `loadReferencedTilemapFiles` fetches it into the JSON
+        // cache before spawn; but editor-time drag-to-place bypasses that path,
+        // so the file is absent and `spawnTilemapRef` soft-fails (placeholder /
+        // nothing). Fetch the file here, THEN queue each tileset its layers
+        // reference — mirrors the sprite/tilemap lazy-load above so a freshly
+        // dropped tilemap renders LIVE without a save+reload round-trip.
+        const tilemapId = entity.tilemapId;
+        if (tilemapId) {
+            try {
+                await loadTilemapFileIntoScene(sceneRef, tilemapId);
+            }
+            catch (e) {
+                console.warn('[umicat/editor] createEntity: tilemap-ref file load failed:', e);
+            }
+            const file = sceneRef.cache.json.get(tilemapFileCacheKey(tilemapId));
+            for (const layer of file?.layers ?? []) {
+                for (const tid of layer.tilesetIds ?? []) {
+                    queueIfMissing(resolveById(tid));
+                }
+            }
+        }
+    }
     for (const a of assetsToLoad) {
         await loadAssetIntoScene(scene, a);
     }
@@ -1312,7 +1338,7 @@ async function createEntity(game, entity, manifestAsset) {
     // with hidden grid renders nothing, so the user sees nothing on the
     // canvas + thinks the drop failed. Re-run the visibility walk after
     // every editor-driven spawn so newly-dropped tilemaps show their bounds.
-    if (entity.kind === 'tilemap') {
+    if (entity.kind === 'tilemap' || entity.kind === 'tilemap-ref') {
         setTilemapGridsVisible(game, true);
     }
 }
@@ -1449,6 +1475,57 @@ function loadAssetIntoScene(scene, asset) {
             scene.load.start();
     });
 }
+/**
+ * Editor-time loader for a standalone tilemap file (`public/tilemaps/{id}.json`),
+ * fetched into the Phaser JSON cache under `tilemapFileCacheKey(id)` — the same
+ * key `spawnTilemapRef` reads from. Mirrors `loadAssetIntoScene`'s await-loader
+ * pattern. Idempotent: resolves immediately if the file is already cached. Used
+ * by `createEntity` when a `tilemap-ref` is dragged in, since the scene-load
+ * path (`loadReferencedTilemapFiles`) that normally primes this cache never runs
+ * for editor-time spawns.
+ */
+function loadTilemapFileIntoScene(scene, tilemapId) {
+    return new Promise((resolve, reject) => {
+        const cacheKey = tilemapFileCacheKey(tilemapId);
+        if (scene.cache.json.exists(cacheKey)) {
+            resolve();
+            return;
+        }
+        const cleanup = () => {
+            scene.load.off(Phaser.Loader.Events.FILE_COMPLETE, perFileComplete);
+            scene.load.off(Phaser.Loader.Events.FILE_LOAD_ERROR, onError);
+            scene.load.off(Phaser.Loader.Events.COMPLETE, onComplete);
+        };
+        const perFileComplete = (key) => {
+            if (key === cacheKey) {
+                cleanup();
+                resolve();
+            }
+        };
+        const onComplete = () => {
+            cleanup();
+            // COMPLETE without the file landing means it 404'd / failed — surface
+            // as a rejection so the caller logs, but spawnTilemapRef still soft-fails
+            // gracefully (placeholder) if we proceed regardless.
+            if (scene.cache.json.exists(cacheKey))
+                resolve();
+            else
+                reject(new Error(`tilemap file not loaded: ${tilemapFilePath(tilemapId)}`));
+        };
+        const onError = (file) => {
+            if (file.key !== cacheKey)
+                return;
+            cleanup();
+            reject(new Error(`failed to load tilemap file ${tilemapId}: ${file.url}`));
+        };
+        scene.load.on(Phaser.Loader.Events.FILE_COMPLETE, perFileComplete);
+        scene.load.on(Phaser.Loader.Events.FILE_LOAD_ERROR, onError);
+        scene.load.on(Phaser.Loader.Events.COMPLETE, onComplete);
+        scene.load.json(cacheKey, tilemapFilePath(tilemapId));
+        if (!scene.load.isLoading())
+            scene.load.start();
+    });
+}
 function deleteEntity(game, entityId) {
     // HUD mode — dispatch to the HUD-scene helper, which destroys + unregisters
     // + drops the entity from the cached scene file.
@@ -2246,6 +2323,15 @@ function handlePatchRule(game, path, value) {
     patchRule(scene, path, value);
 }
 // --- Slice 6 Phase B — tilemap painter -----------------------------------
+//
+// @deprecated (whole section) — tilemap-as-resource (ADR-008, platform
+// restructure Phase 4). Tilemap editing moves to Tilemap Studio, which
+// writes the standalone `public/tilemaps/{id}.json` file; the agent edits
+// that file directly instead of pushing paint ops. Everything below KEEPS
+// WORKING unchanged for one minor version so legacy embedded
+// `kind:'tilemap'` entities + unmigrated hosts can still paint; the host
+// side is removed in Phase 5.
+/** @deprecated Phase 4 — in-Editor paint path retired (see section note). Behavior unchanged. */
 function handleSetTilemapTool(game, msg) {
     setTilemapToolState(game, {
         tilemapEditingId: msg.tilemapEditingId,
@@ -2286,6 +2372,11 @@ function handleSetTilemapTool(game, msg) {
  * Without the await, addLayer's `textures.exists()` check fails on
  * the in-flight load → skips layer creation → painter can't find
  * layer → click falls through to drag-the-entity.
+ *
+ * @deprecated Tilemap-as-resource (ADR-008, Phase 4) — edit the standalone
+ * `public/tilemaps/{id}.json` file instead (Tilemap Studio / agent file
+ * write). Kept fully functional for legacy embedded tilemaps + undo replay
+ * on unmigrated hosts; host side removed in Phase 5.
  */
 export async function handleEditTilemap(game, entityId, ops, manifestAsset) {
     const scene = findWorldScene(game);
@@ -2359,6 +2450,10 @@ export async function handleEditTilemap(game, entityId, ops, manifestAsset) {
  * individual cells. Mirrors how `createTilemap` builds layers initially
  * (in spawnEntity.ts) — same Container parent, same per-layer tagging,
  * same centered (-w/2, -h/2) positioning.
+ *
+ * @deprecated Tilemap-as-resource (ADR-008, Phase 4) — layer structure now
+ * lives in `public/tilemaps/{id}.json`; edit the file. Behavior unchanged
+ * for legacy embedded tilemaps.
  */
 function applyTilemapStructureOp(scene, container, op) {
     switch (op.kind) {
@@ -2682,6 +2777,10 @@ export function findTilemapLayerById(container, layerId) {
  *
  * The optional `asset` arg is required for `autotilePaint` (the only op
  * that needs to resolve a terrain's ruleMap); other ops ignore it.
+ *
+ * @deprecated Tilemap-as-resource (ADR-008, Phase 4) — cell data now lives
+ * in `public/tilemaps/{id}.json`; edit the file. Behavior unchanged for
+ * legacy embedded tilemaps + the deprecated paint path.
  */
 export function applyTilemapOp(layer, op, asset) {
     switch (op.kind) {

package/dist/editor/EditorOverlayScene.js

@@ -465,6 +465,13 @@ export class EditorOverlayScene extends Phaser.Scene {
         this.postDragEnd(drag.entityId, before, after);
     }
     // --- Slice 6 Phase B — tilemap painter -----------------------------------
+    //
+    // @deprecated (whole section) — tilemap-as-resource (ADR-008, Phase 4).
+    // Human tilemap authoring moves to Tilemap Studio (writes the standalone
+    // `public/tilemaps/{id}.json` file); these in-canvas paint handlers KEEP
+    // WORKING unchanged for one minor version so legacy embedded
+    // `kind:'tilemap'` entities + unmigrated hosts can still paint. Host side
+    // removed in Phase 5.
     /**
      * Pointer-down inside paint mode. Returns true when the pointer hit the
      * active layer (stroke began); false when the pointer fell outside the

package/dist/editor/EditorState.d.ts

@@ -35,8 +35,16 @@ export interface EditorDebugOverlayState {
  *
  * `tilemapEditingId` doubles as the "are we in paint mode?" flag — when
  * non-null AND the selected entity is a tilemap, paint mode is active.
+ *
+ * @deprecated Tilemap-as-resource (ADR-008, platform restructure Phase 4).
+ * The in-Editor paint path (this state + the stroke/rect accumulators
+ * below) is retired in favor of Tilemap Studio writing
+ * `public/tilemaps/{id}.json` directly. Everything KEEPS WORKING unchanged
+ * for one minor version so legacy embedded `kind:'tilemap'` entities +
+ * unmigrated hosts can still paint; the host side is removed in Phase 5.
  */
 export type TilemapTool = 'brush' | 'eraser' | 'rect' | 'fill' | 'picker';
+/** @deprecated Phase 4 — see {@link TilemapTool}'s deprecation note. Behavior unchanged. */
 export interface TilemapToolState {
     /** Tilemap entity currently being painted. Null = not in paint mode. */
     tilemapEditingId: string | null;

package/dist/index.d.ts

@@ -16,9 +16,9 @@ export type { ChatMessage, ChatMessageKind } from './realtime/UmicatRoom.js';
 export { RpcError } from './core/Transport.js';
 export type { Transport, TransportKind } from './core/Transport.js';
 export type { UmicatUser } from './protocol.js';
-export { loadWorldScene, preloadManifest, preloadSceneAssets, applyPixelArtFilters, getManifest, SCENES_BASE, MANIFEST_PATH, suspendSceneUpdates, } from './scene/SceneLoader.js';
+export { loadWorldScene, preloadManifest, preloadSceneAssets, applyPixelArtFilters, getManifest, SCENES_BASE, MANIFEST_PATH, TILEMAPS_BASE, tilemapFilePath, loadReferencedTilemapFiles, suspendSceneUpdates, } from './scene/SceneLoader.js';
 export type { LoadWorldSceneOptions } from './scene/SceneLoader.js';
-export { spawnEntity, parseColor, applyAssetHitbox, applyTilesetTileMetadata, getTilemapAt, addTilemapCollider, } from './scene/spawnEntity.js';
+export { spawnEntity, parseColor, applyAssetHitbox, applyTilesetTileMetadata, getTilemapAt, addTilemapCollider, renderTilemapPreview, } from './scene/spawnEntity.js';
 export type { SpawnContext, AssetResolver, RenderScriptResolver, TilemapHit, } from './scene/spawnEntity.js';
 export { applyAutotile, findTerrain, getAutotileKind, invalidateAutotileCells, invalidateAutotileVertices, } from './scene/autotile.js';
 export type { AutotileAffectedCell } from './scene/autotile.js';
@@ -38,6 +38,6 @@ export type { RenderScriptModule } from './scene/renderScripts.js';
 export { setupEditorBridge } from './editor/EditorBridge.js';
 export { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './editor/EditorOverlayScene.js';
 export type { EditorEntityPatch, EditorEnterMessage, EditorExitMessage, EditorGetSceneMessage, EditorApplyEditMessage, EditorSetSelectionMessage, EditorPanZoomMessage, EditorHostToSdkMessage, EditorSceneLoadedMessage, EditorSelectionPickedMessage, EditorDragEndMessage, EditorShortcutMessage, EditorCreateEntityMessage, EditorDeleteEntityMessage, EditorSetEditModeMessage, EditorSelectionRectMessage, EditorSdkToHostMessage, } from './protocol.js';
-export { SCHEMA_VERSION, isPerFrameNinePatch, isPerFrameHitbox, } from './scene/types.js';
-export type { Manifest, ManifestGroup, SceneRef, HudRef, AssetRecord, AssetKind, SceneType, SceneFile, WorldScene, HudScene, WorldSceneConfig, CameraConfig, WorldEntity, WorldEntityKind, NonGroupWorldEntity, RenderableEntity, SpriteEntity, RectEntity, CircleEntity, CodeRenderedEntity, GroupEntity, TilemapEntity, TilemapLayer, TilesetMetadata, TileMetadata, TilesetAutotile, TilesetAnimation, WangTerrain, TriggerEntity, PrefabRefEntity, TriggerShape, HudEntity, HudEntityKind, HudEntityBase, HudTextEntity, HudImageEntity, HudIconButtonEntity, HudProgressBarEntity, HudPanelEntity, HudTextSource, HudNumberSource, HudLayer, Transform, Anchor, AnchorSide, NinePatchConfig, NinePatchPerFrame, HitboxRect, HitboxPerFrame, DepthAnchor, } from './scene/types.js';
+export { SCHEMA_VERSION, isPerFrameNinePatch, isPerFrameHitbox, tilemapFileCacheKey, } from './scene/types.js';
+export type { Manifest, ManifestGroup, SceneRef, HudRef, AssetRecord, AssetKind, SceneType, SceneFile, WorldScene, HudScene, WorldSceneConfig, CameraConfig, WorldEntity, WorldEntityKind, NonGroupWorldEntity, RenderableEntity, SpriteEntity, RectEntity, CircleEntity, CodeRenderedEntity, GroupEntity, TilemapEntity, TilemapRefEntity, TilemapFile, TilemapFileLayer, TilemapLayer, TilesetMetadata, TileMetadata, TilesetAutotile, TilesetAnimation, WangTerrain, TriggerEntity, PrefabRefEntity, TriggerShape, HudEntity, HudEntityKind, HudEntityBase, HudTextEntity, HudImageEntity, HudIconButtonEntity, HudProgressBarEntity, HudPanelEntity, HudTextSource, HudNumberSource, HudLayer, Transform, Anchor, AnchorSide, NinePatchConfig, NinePatchPerFrame, HitboxRect, HitboxPerFrame, DepthAnchor, } from './scene/types.js';
 export { PROTOCOL_VERSION, type HelloMessage, type InitMessage, type RpcRequestMessage, type RpcResultOk, type RpcResultError, type HostToSdkMessage, type SdkToHostMessage, type RpcErrorPayload, type RpcMethod, type SavesGetParams, type SavesGetResult, type SavesSetParams, type SavesSetResult, type SavesDeleteParams, type SavesDeleteResult, type SavesListResult, type GameDataGetParams, type GameDataGetResult, type GameDataSetParams, type GameDataSetResult, type GameDataDeleteParams, type GameDataDeleteResult, type GameDataListResult, type RealtimeGetTokenParams, type RealtimeGetTokenResult, } from './protocol.js';

package/dist/index.js

@@ -14,8 +14,14 @@ export { RealtimeModule } from './realtime/RealtimeModule.js';
 export { UmicatRoom, PlayerDataFacade, RoomDataFacade, ChatFacade, MAX_CHAT_TEXT_LEN, } from './realtime/UmicatRoom.js';
 export { RpcError } from './core/Transport.js';
 // Scene-as-data (visual editor foundation, slice 1)
-export { loadWorldScene, preloadManifest, preloadSceneAssets, applyPixelArtFilters, getManifest, SCENES_BASE, MANIFEST_PATH, suspendSceneUpdates, } from './scene/SceneLoader.js';
-export { spawnEntity, parseColor, applyAssetHitbox, applyTilesetTileMetadata, getTilemapAt, addTilemapCollider, } from './scene/spawnEntity.js';
+export { loadWorldScene, preloadManifest, preloadSceneAssets, applyPixelArtFilters, getManifest, SCENES_BASE, MANIFEST_PATH, TILEMAPS_BASE, tilemapFilePath, loadReferencedTilemapFiles, suspendSceneUpdates, } from './scene/SceneLoader.js';
+export { spawnEntity, parseColor, applyAssetHitbox, applyTilesetTileMetadata, getTilemapAt, addTilemapCollider, 
+// Tilemap-as-resource (ADR-008, Phase 4) — minimal rendering surface for
+// Tilemap Studio's standalone canvas: renders a TilemapFile through the
+// exact in-game path (layers, autotile-resolved cells, tile metadata,
+// animations) without a scene file or entity registry. Pair with
+// `tilemapFileCacheKey` / `TILEMAPS_BASE` to fetch the file.
+renderTilemapPreview, } from './scene/spawnEntity.js';
 // Slice 6 Phase D — Wang autotile runtime.
 export { applyAutotile, findTerrain, getAutotileKind, invalidateAutotileCells, invalidateAutotileVertices, // deprecated alias kept for 0.2.122–0.2.124 callers
  } from './scene/autotile.js';
@@ -39,5 +45,5 @@ export { setupEditorModeListener, isEditMode } from './scene/EditorMode.js';
 export { setRenderScriptRegistry, getRenderScriptRegistry, resolveRenderScript, } from './scene/renderScripts.js';
 export { setupEditorBridge } from './editor/EditorBridge.js';
 export { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './editor/EditorOverlayScene.js';
-export { SCHEMA_VERSION, isPerFrameNinePatch, isPerFrameHitbox, } from './scene/types.js';
+export { SCHEMA_VERSION, isPerFrameNinePatch, isPerFrameHitbox, tilemapFileCacheKey, } from './scene/types.js';
 export { PROTOCOL_VERSION, } from './protocol.js';

package/dist/protocol.d.ts

@@ -366,6 +366,13 @@ export interface EditorSetDebugOverlayMessage {
  * many times per second; round-tripping each one through postMessage would
  * add visible latency. SDK paints locally + posts ONE `tilemapEdited` per
  * completed stroke for undo recording — same pattern as drag-to-move.
+ *
+ * @deprecated Tilemap-as-resource (ADR-008, platform restructure Phase 4).
+ * Tilemap editing moves to Tilemap Studio, which writes the standalone
+ * `public/tilemaps/{id}.json` file directly — the in-Editor paint path is
+ * deprecated in Phase 4 and the host side is removed in Phase 5. The SDK
+ * keeps this message working (behavior unchanged) for one minor version so
+ * unmigrated hosts / legacy embedded tilemaps keep painting.
  */
 export interface EditorSetTilemapToolMessage {
     type: 'umicat:editor:setTilemapTool';
@@ -405,6 +412,12 @@ export interface EditorSetTilemapToolMessage {
  * replay (host pushes the inverse op), and any future host-driven flow.
  * Live painting via pointer events does NOT use this message — that path
  * goes SDK→host (`tilemapEdited`) for undo recording.
+ *
+ * @deprecated Tilemap-as-resource (ADR-008, Phase 4). The agent now writes
+ * `public/tilemaps/{id}.json` directly instead of pushing paint ops through
+ * the editor; humans paint in Tilemap Studio. Kept working (behavior
+ * unchanged) for one minor version for legacy embedded `kind:'tilemap'`
+ * entities and undo replay on unmigrated hosts.
  */
 export interface EditorEditTilemapMessage {
     type: 'umicat:editor:editTilemap';
@@ -433,6 +446,10 @@ export interface EditorEditTilemapMessage {
  * paint/erase/fillRect/bucketFill mutate cell data within a layer (Phase B.3
  * + B.4); addLayer/removeLayer/setLayerVisibility mutate the layer list
  * itself (Phase B.5).
+ *
+ * @deprecated Tilemap-as-resource (ADR-008, Phase 4) — see
+ * {@link EditorEditTilemapMessage}. Edit the standalone tilemap file
+ * instead; ops remain functional for legacy embedded tilemaps.
  */
 export type TilemapEditOp = {
     kind: 'paint';
@@ -772,6 +789,11 @@ export interface EditorCameraStateMessage {
  * The SDK already applied the op locally before posting — so the iframe is
  * already showing the painted cells. This message exists for undo +
  * persistence, NOT live preview (mirrors how `dragEnd` works).
+ *
+ * @deprecated Tilemap-as-resource (ADR-008, Phase 4). The in-Editor paint
+ * path is retired in favor of Tilemap Studio writing
+ * `public/tilemaps/{id}.json`. Still emitted (behavior unchanged) while
+ * legacy embedded tilemaps + unmigrated hosts exist.
  */
 export interface EditorTilemapEditedMessage {
     type: 'umicat:editor:tilemapEdited';
@@ -799,6 +821,10 @@ export interface EditorTilemapEditedMessage {
  * Photoshop / Aseprite eyedropper convention — pick once, paint next).
  *
  * `tileIndex: null` means the picked cell is empty.
+ *
+ * @deprecated Tilemap-as-resource (ADR-008, Phase 4) — paint path retired,
+ * see {@link EditorTilemapEditedMessage}. Still emitted while legacy
+ * embedded tilemaps + unmigrated hosts exist.
  */
 export interface EditorTilemapTilePickedMessage {
     type: 'umicat:editor:tilemapTilePicked';

package/dist/scene/SceneLoader.d.ts

@@ -10,6 +10,16 @@ import { EntityRegistry } from './EntityRegistry.js';
  */
 export declare const SCENES_BASE = "scenes/";
 export declare const MANIFEST_PATH = "scenes/manifest.json";
+/**
+ * Where standalone tilemap resource files live (tilemap-as-resource,
+ * ADR-008 / platform restructure Phase 4). A scene's `tilemap-ref` entity
+ * carries `tilemapId`; the file is `public/tilemaps/{tilemapId}.json`
+ * (served origin-relative as `tilemaps/{tilemapId}.json`, same convention
+ * as {@link SCENES_BASE}).
+ */
+export declare const TILEMAPS_BASE = "tilemaps/";
+/** Origin-relative URL of a standalone tilemap file. */
+export declare function tilemapFilePath(tilemapId: string): string;
 /**
  * Fetches the manifest via Phaser's loader. Must be called from a Phaser
  * scene's `preload()` since it queues a load request. Subsequent calls
@@ -116,3 +126,18 @@ export declare function loadWorldScene(scene: Phaser.Scene, sceneId: string, opt
     sceneFile: WorldScene;
     registry: EntityRegistry;
 }>;
+/**
+ * Fetch every standalone tilemap file referenced by the scene's
+ * `tilemap-ref` entities into the Phaser JSON cache (tilemap-as-resource,
+ * ADR-008 / Phase 4). Idempotent — files already in the cache aren't
+ * re-fetched, so scene transitions back to a tilemap-using scene are free.
+ *
+ * Fails LOUDLY with an actionable message when a referenced file is
+ * missing or malformed: a tilemap-ref without its file would render
+ * nothing, and the silent variant of that bug ("my ground disappeared")
+ * is much harder to diagnose than a thrown scene-load error naming the
+ * exact expected path. The spawn path additionally soft-fails (magenta
+ * placeholder) for refs spawned outside this loader, e.g. editor
+ * createEntity.
+ */
+export declare function loadReferencedTilemapFiles(scene: Phaser.Scene, sceneFile: WorldScene): Promise<void>;

package/dist/scene/SceneLoader.js

@@ -1,5 +1,5 @@
 import Phaser from 'phaser';
-import { SCHEMA_VERSION, } from './types.js';
+import { SCHEMA_VERSION, tilemapFileCacheKey, } from './types.js';
 import { spawnEntity } from './spawnEntity.js';
 import { attachEntityRegistry } from './EntityRegistry.js';
 import { resolveRenderScript } from './renderScripts.js';
@@ -11,6 +11,18 @@ import { resolveRenderScript } from './renderScripts.js';
  */
 export const SCENES_BASE = 'scenes/';
 export const MANIFEST_PATH = `${SCENES_BASE}manifest.json`;
+/**
+ * Where standalone tilemap resource files live (tilemap-as-resource,
+ * ADR-008 / platform restructure Phase 4). A scene's `tilemap-ref` entity
+ * carries `tilemapId`; the file is `public/tilemaps/{tilemapId}.json`
+ * (served origin-relative as `tilemaps/{tilemapId}.json`, same convention
+ * as {@link SCENES_BASE}).
+ */
+export const TILEMAPS_BASE = 'tilemaps/';
+/** Origin-relative URL of a standalone tilemap file. */
+export function tilemapFilePath(tilemapId) {
+    return `${TILEMAPS_BASE}${tilemapId}.json`;
+}
 const MANIFEST_CACHE_KEY = '__unboxyManifestState';
 /**
  * Fetches the manifest via Phaser's loader. Must be called from a Phaser
@@ -78,7 +90,7 @@ export function preloadSceneAssets(scene, sceneFile, manifest) {
     if (sceneFile.type !== 'world')
         return; // HUD slice will add its own walker
     const state = getOrInitState(scene, manifest);
-    const ids = collectAssetIds(sceneFile.entities, manifest);
+    const ids = collectAssetIds(sceneFile.entities, manifest, (tilemapId) => scene.cache.json.get(tilemapFileCacheKey(tilemapId)));
     for (const id of ids) {
         if (state.requestedAssetIds.has(id))
             continue;
@@ -98,7 +110,7 @@ export function preloadSceneAssets(scene, sceneFile, manifest) {
         state.requestedAssetIds.add(id);
     }
 }
-function collectAssetIds(entities, manifest) {
+function collectAssetIds(entities, manifest, resolveTilemapFile) {
     const ids = new Set();
     function walk(e) {
         if (e.kind === 'sprite') {
@@ -119,6 +131,18 @@ function collectAssetIds(entities, manifest) {
                     ids.add(id);
             }
         }
+        else if (e.kind === 'tilemap-ref') {
+            // Tilemap-as-resource (Phase 4): the ref's layer data lives in
+            // `public/tilemaps/{tilemapId}.json` — loaded into the JSON cache by
+            // `loadReferencedTilemapFiles` BEFORE this walker runs, so the
+            // resolver can read the file's layers and queue their tilesets the
+            // same way the embedded-tilemap branch above does.
+            const file = resolveTilemapFile?.(e.tilemapId);
+            for (const layer of file?.layers ?? []) {
+                for (const id of layer.tilesetIds ?? [])
+                    ids.add(id);
+            }
+        }
         else if (e.kind === 'prefab-ref') {
             // Authored prefab instance — preload whatever the prefab's visual
             // references (sprite prefabs carry an assetId at the record root).
@@ -286,6 +310,21 @@ function queueAssetLoad(scene, asset) {
                     }
                     : null);
             if (!cfg) {
+                // A TILESET asset can be modality 'spritesheet' yet carry no
+                // spriteSheetConfig — it's sliced by `tileset.cellSize` in
+                // `createTilemap`'s `addTilesetImage`, never consumed as Phaser
+                // animation frames. Load it as a plain image so tilemap layers
+                // referencing it actually render. Mirrors the editor's
+                // `loadAssetIntoScene` fallback (EditorBridge) — without this the
+                // two load paths diverge: a tilemap-ref renders live in the editor
+                // but its layer vanishes after save+reload because scene-load
+                // skipped the texture. (Host now writes tilesets as kind:'image',
+                // but this keeps agent-authored / legacy spritesheet-kind tilesets
+                // robust too.)
+                if (asset.tileset) {
+                    scene.load.image(asset.textureKey, asset.path);
+                    return;
+                }
                 // eslint-disable-next-line no-console
                 console.warn(`[umicat/scene] asset '${asset.id}' kind=spritesheet missing spriteSheetConfig (and no top-level frameWidth/frameHeight); skipping load`);
                 return;
@@ -386,6 +425,12 @@ async function loadWorldSceneImpl(scene, sceneId, options) {
     // entities spawn. Scene-level `world.physics.gravity` wins over the
     // manifest-wide `globals.physics.gravity`.
     applyWorldGravity(scene, sceneFile, manifest);
+    // Tilemap-as-resource (ADR-008, Phase 4): resolve `tilemap-ref` entities
+    // by fetching their standalone `public/tilemaps/{id}.json` files FIRST —
+    // the asset preload below reads each file's layers to know which tileset
+    // textures to queue. Files land in the Phaser JSON cache (keyed by
+    // `tilemapFileCacheKey`) so repeat loads of the same scene are free.
+    await loadReferencedTilemapFiles(scene, sceneFile);
     // Lazy preload of any new assets this scene needs, then await loader.
     preloadSceneAssets(scene, sceneFile, manifest);
     await runLoader(scene);
@@ -449,6 +494,72 @@ async function loadSceneJson(scene, ref) {
     await runLoader(scene);
     return scene.cache.json.get(cacheKey);
 }
+/** Recursively collect every `tilemap-ref` entity (groups walked too). */
+function collectTilemapRefs(entities) {
+    const refs = [];
+    function walk(e) {
+        if (e.kind === 'tilemap-ref') {
+            refs.push(e);
+        }
+        else if (e.kind === 'group') {
+            for (const child of e.children)
+                walk(child);
+        }
+    }
+    for (const e of entities)
+        walk(e);
+    return refs;
+}
+/**
+ * Fetch every standalone tilemap file referenced by the scene's
+ * `tilemap-ref` entities into the Phaser JSON cache (tilemap-as-resource,
+ * ADR-008 / Phase 4). Idempotent — files already in the cache aren't
+ * re-fetched, so scene transitions back to a tilemap-using scene are free.
+ *
+ * Fails LOUDLY with an actionable message when a referenced file is
+ * missing or malformed: a tilemap-ref without its file would render
+ * nothing, and the silent variant of that bug ("my ground disappeared")
+ * is much harder to diagnose than a thrown scene-load error naming the
+ * exact expected path. The spawn path additionally soft-fails (magenta
+ * placeholder) for refs spawned outside this loader, e.g. editor
+ * createEntity.
+ */
+export async function loadReferencedTilemapFiles(scene, sceneFile) {
+    const refs = collectTilemapRefs(sceneFile.entities);
+    if (refs.length === 0)
+        return;
+    const queuedIds = new Set();
+    for (const ref of refs) {
+        if (queuedIds.has(ref.tilemapId))
+            continue;
+        queuedIds.add(ref.tilemapId);
+        const cacheKey = tilemapFileCacheKey(ref.tilemapId);
+        if (scene.cache.json.exists(cacheKey))
+            continue;
+        scene.load.json(cacheKey, tilemapFilePath(ref.tilemapId));
+    }
+    try {
+        await runLoader(scene);
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        throw new Error(`[umicat/scene] scene '${sceneFile.id}' references standalone tilemap file(s) that failed to load (${detail}). ` +
+            `tilemap-ref entities expect a file at public/tilemaps/<tilemapId>.json — ` +
+            `referenced ids: ${Array.from(queuedIds).join(', ')}`);
+    }
+    // Validate every ref resolved to a structurally-plausible TilemapFile.
+    for (const ref of refs) {
+        const file = scene.cache.json.get(tilemapFileCacheKey(ref.tilemapId));
+        if (!file) {
+            throw new Error(`[umicat/scene] entity '${ref.id}' (kind=tilemap-ref) points at tilemap '${ref.tilemapId}' ` +
+                `but public/tilemaps/${ref.tilemapId}.json did not load — create the file or remove the ref`);
+        }
+        if (!file.tileSize || !file.size || !Array.isArray(file.layers)) {
+            throw new Error(`[umicat/scene] tilemap file public/tilemaps/${ref.tilemapId}.json is malformed — ` +
+                `expected { schemaVersion, id, tileSize: {width,height}, size: {width,height}, layers: [...] } (TilemapFile schema)`);
+        }
+    }
+}
 /**
  * Phaser's `load` queue is fire-and-forget; this wraps it in a promise.
  * If the loader is already idle and has nothing queued, resolves

package/dist/scene/spawnEntity.d.ts

@@ -1,5 +1,5 @@
 import Phaser from 'phaser';
-import { AssetRecord, TileMetadata, WorldEntity } from './types.js';
+import { AssetRecord, TileMetadata, TilemapFile, WorldEntity } from './types.js';
 import { EntityRegistry } from './EntityRegistry.js';
 /**
  * Resolves an asset id to its AssetRecord, throwing a clear error if the
@@ -23,6 +23,33 @@ export interface SpawnContext {
  * group's children) can attach it to a parent container.
  */
 export declare function spawnEntity(ctx: SpawnContext, entity: WorldEntity): Phaser.GameObjects.GameObject;
+/**
+ * Minimal rendering surface for Tilemap Studio's standalone canvas
+ * (tilemap-as-resource, ADR-008 / Phase 4).
+ *
+ * Renders a `TilemapFile` into a bare Phaser scene through the SAME path
+ * scene-spawned tilemaps use (grid sketch + one TilemapLayer per layer,
+ * including autotile-resolved cells, NEAREST filtering, per-tile metadata
+ * and tile animations) — so the Studio preview is pixel-identical to the
+ * in-game render. Returns the container GameObject; destroy it (plus the
+ * layers stashed under its `tilemapLayers` data key — they are scene-root
+ * siblings, not children, due to the Phaser Container/TilemapLayer
+ * rendering quirk) before re-rendering after an edit.
+ *
+ * Prerequisites the caller owns:
+ *  - every tileset texture referenced by `file.layers[].tilesetIds` is
+ *    loaded into `scene.textures` and resolvable via `resolveAsset`
+ *  - the preview is static: the per-frame layer-position sync hook that
+ *    scene loads install is NOT active here, so move the container only by
+ *    re-rendering (or position it once at `position` and leave it)
+ *
+ * Deliberately NOT registered in any EntityRegistry — this is a rendering
+ * helper, not an entity spawn.
+ */
+export declare function renderTilemapPreview(scene: Phaser.Scene, file: TilemapFile, resolveAsset: AssetResolver, position?: {
+    x: number;
+    y: number;
+}): Phaser.GameObjects.GameObject;
 /**
  * Read the auto-tracker's recorded draw extent and set editor hit-area
  * data on the GameObject. Falls back to declared `visual.width/height`

package/dist/scene/spawnEntity.js

@@ -1,12 +1,26 @@
 import Phaser from 'phaser';
-import { isPerFrameHitbox, } from './types.js';
-import { getEntityRegistry } from './EntityRegistry.js';
+import { isPerFrameHitbox, tilemapFileCacheKey, } from './types.js';
+import { EntityRegistry, getEntityRegistry } from './EntityRegistry.js';
 /**
  * Spawn one entity into the scene and register it. Returns the created
  * GameObject so callers (notably `spawnEntity` itself, recursing on a
  * group's children) can attach it to a parent container.
  */
 export function spawnEntity(ctx, entity) {
+    if (entity.kind === 'tilemap-ref') {
+        // Tilemap-as-resource (ADR-008, Phase 4). The ref carries only
+        // reference + placement; cell data comes from the standalone file at
+        // `public/tilemaps/{tilemapId}.json` (fetched into the JSON cache by
+        // SceneLoader's `loadReferencedTilemapFiles` before spawn). We
+        // synthesize a legacy-shaped `kind:'tilemap'` entity in memory and
+        // recurse — the inner call runs the UNCHANGED createTilemap rendering
+        // path (grid sketch, layers, autotile, tile metadata, animations) and
+        // tags the GameObject `entityKind:'tilemap'`, so every existing
+        // runtime consumer (layer-position sync, Y-sort, getTilemapAt,
+        // addTilemapCollider, debug overlay) works on refs with zero changes.
+        // Early return: the recursion already applied transform/tag/register.
+        return spawnTilemapRef(ctx, entity);
+    }
     let go;
     switch (entity.kind) {
         case 'sprite':
@@ -111,6 +125,92 @@ function createMissingPlaceholder(scene, label) {
     void label;
     return g;
 }
+// --- Tilemap as a project resource (ADR-008, Phase 4) ----------------------
+/**
+ * Build the legacy-shaped embedded entity a `tilemap-ref` + its resolved
+ * `TilemapFile` are equivalent to. Placement (transform / role /
+ * properties) comes from the ref; tile/map dimensions + layer data come
+ * from the file. Shared by the scene spawn path and
+ * {@link renderTilemapPreview}.
+ */
+function tilemapEntityFromFile(ref, file) {
+    return {
+        id: ref.id,
+        kind: 'tilemap',
+        ...(ref.role !== undefined ? { role: ref.role } : {}),
+        ...(ref.properties !== undefined ? { properties: ref.properties } : {}),
+        transform: ref.transform,
+        tileSize: file.tileSize,
+        size: file.size,
+        // TilemapFileLayer is TilemapLayer minus the editor-only `locked` flag,
+        // so the file's layers slot straight into the legacy shape.
+        layers: file.layers,
+    };
+}
+/**
+ * Spawn a `tilemap-ref` entity by resolving its standalone file from the
+ * Phaser JSON cache and recursing through `spawnEntity` with a synthesized
+ * legacy `kind:'tilemap'` entity — the same rendering path embedded
+ * tilemaps use; only the data source differs.
+ *
+ * Soft-fails to the magenta placeholder when the file isn't in the cache
+ * (SceneLoader's `loadReferencedTilemapFiles` throws a clearer error for
+ * the normal scene-load path; this branch covers direct spawns, e.g.
+ * editor createEntity, where killing the scene would be worse).
+ */
+function spawnTilemapRef(ctx, entity) {
+    const file = ctx.scene.cache.json.get(tilemapFileCacheKey(entity.tilemapId));
+    if (!file || !file.tileSize || !file.size || !Array.isArray(file.layers)) {
+        console.warn(`[umicat/scene] tilemap-ref '${entity.id}' references tilemap '${entity.tilemapId}' but ` +
+            `public/tilemaps/${entity.tilemapId}.json is not loaded (or malformed); rendering placeholder. ` +
+            `Scene loads fetch it automatically — direct spawns must load it into the JSON cache first ` +
+            `(key: '${tilemapFileCacheKey(entity.tilemapId)}').`);
+        const go = createMissingPlaceholder(ctx.scene, `tilemap: ${entity.tilemapId}?`);
+        applyTransform(go, entity.transform);
+        tagGameObject(go, entity);
+        ctx.registry.register(entity.id, entity.role, go);
+        return go;
+    }
+    const go = spawnEntity(ctx, tilemapEntityFromFile(entity, file));
+    // Ref marker for the editor / Tilemap Studio: the GO renders + behaves as
+    // entityKind 'tilemap' (runtime consumers unchanged), but hosts can read
+    // this data key to know the cell data lives in a standalone file.
+    go.setData('tilemapId', entity.tilemapId);
+    return go;
+}
+/**
+ * Minimal rendering surface for Tilemap Studio's standalone canvas
+ * (tilemap-as-resource, ADR-008 / Phase 4).
+ *
+ * Renders a `TilemapFile` into a bare Phaser scene through the SAME path
+ * scene-spawned tilemaps use (grid sketch + one TilemapLayer per layer,
+ * including autotile-resolved cells, NEAREST filtering, per-tile metadata
+ * and tile animations) — so the Studio preview is pixel-identical to the
+ * in-game render. Returns the container GameObject; destroy it (plus the
+ * layers stashed under its `tilemapLayers` data key — they are scene-root
+ * siblings, not children, due to the Phaser Container/TilemapLayer
+ * rendering quirk) before re-rendering after an edit.
+ *
+ * Prerequisites the caller owns:
+ *  - every tileset texture referenced by `file.layers[].tilesetIds` is
+ *    loaded into `scene.textures` and resolvable via `resolveAsset`
+ *  - the preview is static: the per-frame layer-position sync hook that
+ *    scene loads install is NOT active here, so move the container only by
+ *    re-rendering (or position it once at `position` and leave it)
+ *
+ * Deliberately NOT registered in any EntityRegistry — this is a rendering
+ * helper, not an entity spawn.
+ */
+export function renderTilemapPreview(scene, file, resolveAsset, position = { x: 0, y: 0 }) {
+    const entity = tilemapEntityFromFile({ id: `__tilemap-preview:${file.id}`, transform: { x: position.x, y: position.y } }, file);
+    // createTilemap never touches ctx.registry (registration happens in
+    // spawnEntity, which we bypass) — a throwaway registry satisfies the
+    // SpawnContext shape without clobbering a live scene registry.
+    const ctx = { scene, registry: new EntityRegistry(), resolveAsset };
+    const go = createTilemap(ctx, entity);
+    applyTransform(go, entity.transform);
+    return go;
+}
 /**
  * Apply a scene entity's optional `physics` block. Only renderable entity
  * kinds (sprite / rect / circle / code-rendered) carry a body — they mirror

package/dist/scene/types.d.ts

@@ -753,7 +753,7 @@ export interface Anchor {
     offsetX?: number;
     offsetY?: number;
 }
-export type WorldEntityKind = 'sprite' | 'rect' | 'circle' | 'code-rendered' | 'group' | 'tilemap' | 'trigger' | 'prefab-ref';
+export type WorldEntityKind = 'sprite' | 'rect' | 'circle' | 'code-rendered' | 'group' | 'tilemap' | 'tilemap-ref' | 'trigger' | 'prefab-ref';
 export interface WorldEntityBase {
     id: string;
     /** Optional semantic tag. Behavior code keys off this. */
@@ -836,6 +836,15 @@ export interface GroupEntity extends WorldEntityBase {
  *
  * Multi-tileset per layer (`tilesetIds: string[]`) is reserved in the
  * shape for later phases but Phase A only consumes the first id.
+ *
+ * @deprecated Tilemap-as-resource (ADR-008, platform restructure Phase 4).
+ * Cell data now lives in standalone files at `public/tilemaps/{id}.json`
+ * (see {@link TilemapFile}); scenes carry only a {@link TilemapRefEntity}
+ * (`kind: 'tilemap-ref'`) holding the reference + placement. Embedded
+ * tilemap entities KEEP RENDERING so unmigrated scenes still work — do not
+ * author new ones. The migration script in umicat-agent-session-service
+ * (`scripts/migrate-tilemaps.ts`) converts embedded → file+ref per
+ * workspace.
  */
 export interface TilemapEntity extends WorldEntityBase {
     kind: 'tilemap';
@@ -888,6 +897,72 @@ export interface TilemapLayer {
     };
     ySort?: boolean;
 }
+/**
+ * Scene-side reference to a standalone tilemap file. Placement comes from
+ * the inherited `transform` (position / depth / scale); everything else —
+ * tile size, map size, layers, cell data — comes from the referenced
+ * `public/tilemaps/{tilemapId}.json` file at load time.
+ *
+ * ```json
+ * { "id": "e-ground", "kind": "tilemap-ref", "tilemapId": "forest-floor",
+ *   "role": "terrain", "transform": { "x": 640, "y": 360, "depth": 1 } }
+ * ```
+ */
+export interface TilemapRefEntity extends WorldEntityBase {
+    kind: 'tilemap-ref';
+    /** Id of the tilemap file — `public/tilemaps/{tilemapId}.json`. */
+    tilemapId: string;
+}
+/**
+ * One layer inside a `TilemapFile`. Identical to the scene-embedded
+ * {@link TilemapLayer} shape minus the editor-only `locked` flag (which
+ * never had a runtime effect and doesn't belong in a shared resource).
+ */
+export type TilemapFileLayer = Omit<TilemapLayer, 'locked'>;
+/**
+ * Standalone tilemap resource file — `public/tilemaps/{id}.json`.
+ *
+ * Written by Tilemap Studio (the single human-authoring surface) and by the
+ * agent directly (workspace file edit — the editor paint RPC is retired).
+ * Read by the SDK's SceneLoader when a scene's `tilemap-ref` entity points
+ * at it, and rendered through the same path as the legacy embedded entity.
+ */
+export interface TilemapFile {
+    schemaVersion: number;
+    /** Stable id; the filename is `{id}.json` and refs carry it as `tilemapId`. */
+    id: string;
+    /** Display name for pickers / Studio. Falls back to `id`. */
+    name?: string;
+    /** Render-time cell size in pixels. Layer data indexes cells at this size. */
+    tileSize: {
+        width: number;
+        height: number;
+    };
+    /** Map size in cells (not pixels). */
+    size: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Set when a human painted this map in Tilemap Studio. The agent must
+     * NOT overwrite cell data in a human-curated file without asking the
+     * user first.
+     */
+    humanCurated?: boolean;
+    metadata?: {
+        createdAt?: string;
+        editedAt?: string;
+        /** `'user'` | `'agent'` | `'migration-v1'` (free-form). */
+        author?: string;
+    };
+    layers: TilemapFileLayer[];
+}
+/**
+ * Phaser JSON-cache key under which a fetched tilemap file is stored.
+ * Shared by the SceneLoader preload pass (write) and the `tilemap-ref`
+ * spawn path + any external canvas harness (read).
+ */
+export declare function tilemapFileCacheKey(tilemapId: string): string;
 export type TriggerShape = {
     kind: 'rect';
     width: number;
@@ -929,7 +1004,7 @@ export interface PrefabRefEntity extends WorldEntityBase {
     kind: 'prefab-ref';
     prefabId: string;
 }
-export type NonGroupWorldEntity = SpriteEntity | RectEntity | CircleEntity | CodeRenderedEntity | TilemapEntity | TriggerEntity | PrefabRefEntity;
+export type NonGroupWorldEntity = SpriteEntity | RectEntity | CircleEntity | CodeRenderedEntity | TilemapEntity | TilemapRefEntity | TriggerEntity | PrefabRefEntity;
 export type WorldEntity = NonGroupWorldEntity | GroupEntity;
 /**
  * Renderable entity kinds — those that produce a single GameObject with

package/dist/scene/types.js

@@ -32,3 +32,11 @@ export function isPerFrameNinePatch(np) {
 export function isPerFrameHitbox(h) {
     return !!h && h.default != null;
 }
+/**
+ * Phaser JSON-cache key under which a fetched tilemap file is stored.
+ * Shared by the SceneLoader preload pass (write) and the `tilemap-ref`
+ * spawn path + any external canvas harness (read).
+ */
+export function tilemapFileCacheKey(tilemapId) {
+    return `umicat:tilemap:${tilemapId}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/phaser-sdk",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Umicat Phaser 3 SDK — game infrastructure for the Umicat platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",