diff --git a/docs/ADDON_COMPAT.md b/docs/ADDON_COMPAT.md
index 98025a36..7ad937d8 100644
--- a/docs/ADDON_COMPAT.md
+++ b/docs/ADDON_COMPAT.md
@@ -1894,3 +1894,49 @@ upscale pack). A tile whose rect is not 256x256 at a 256 pitch, or whose file is
 layout assumes, names the fault outright instead of being guessed at from a screenshot.
 
 Off unless the variable is set: it runs a Lua chunk per map change.
+
+## The map, answered by its own trace: the stock art does not follow a resized detail frame
+
+`WOW_MAP_TRACE=1` named it on the first run, in one line:
+
+```
+world map art: detail 1431x954 @(10,1122) scale 0.70 shown=1
+  | 1 256x256 @(10,1122) file 512x512 | 2 256x256 @(266,1122) file 512x512 | ...
+```
+
+1.12's `WorldMapDetailFrame` is **always** 1002x668, so everything drawn into it is placed in
+absolute pixels against that: twelve 256x256 tiles anchor-chained from its TOPLEFT (1024x768 of
+art, the overhang clipped by the frame), each exploration overlay at the offset and size
+`WorldMapOverlay.dbc` gives it, and the hover highlight likewise.
+
+The canvas breaks that assumption the moment it sizes the frame to anything else, and it does:
+`OnCanvasSizeChanged` falls back to the container's own rect whenever it has no art layer to read,
+which is every moment the canvas has no `mapID` — including the blip through the world view that
+the same log shows on every map open. The result is a **1024x768 sheet of art pinned to the
+top-left of a 1431x954 frame**: 72% of the width, 80% of the height, and the rest of the map
+drawing nothing. That is the grey grom reported, with the art magnified relative to what was left
+of the frame, and no amount of offline auditing could see it because every number that was wrong
+was a *runtime* number.
+
+Fixed in `assets/ui/MapCanvas.lua`: the art is rescaled to whatever size the frame has, by the
+same factor on each axis. The tiles need only their size set — 1.12's XML chains them
+TOPRIGHT-to-TOPLEFT and BOTTOMLEFT-to-TOPLEFT, so resizing one moves the grid. The overlays carry
+absolute offsets, so they are captured from the values the stock repaint last wrote (hooked on
+`WorldMapFrame_Update`, the only moment those base values are readable) and scaled from that base,
+so a second pass cannot compound. Measured: a 1431x954 frame now holds a 1462x1097 grid, which is
+the same 1024/1002 and 768/668 proportion the reference frames.
+
+Two smaller things fell out of it and are fixed with it:
+
+- **The container resizing was not treated as a canvas size change.** The canvas was re-sized only
+  when the map changed (`SetMapID`, `SyncFromSelection`), so a window resized while the map stayed
+  put left the canvas at the old size. It now has an `OnSizeChanged` of its own.
+- **A derived resize fires no `OnSizeChanged` here.** Measured: a child `SetAllPoints` to a parent
+  that is then resized gets no event, and answers `0x0` until the layout pass. So the rescale
+  takes the size its caller just set as an argument rather than reading the frame back — reading
+  it would answer the old size.
+
+**Harness note for the next person:** `addon_harness`'s `--tick` step calls `script.tick` but not
+`script.resolve`, and `resolve` is what drains the layout pass's queued `OnSizeChanged`. So
+`OnSizeChanged` never fires under `--tick` alone and it is not evidence of an engine gap; a
+`--mouse` or `--plates` step resolves, and under those it fires normally.