Add tests for scenery surface caching and preview behavior

- Introduced `test_scenery_brick_preview.gd` to validate focused placement and CPU draw-cost for large brick walls.
- Added `test_scenery_surface_cache.gd` to assess texture budget, visual equivalence, and cache invalidation.
- Created `test_scenery_surface_preview.gd` to evaluate adaptive preview selection and placement behavior.
- Implemented various helper functions to measure drawing performance and validate expected behaviors during tests.
- Added unique identifiers for new test files to ensure proper tracking and management.

docs/architecture/scenery_surface_caching.md

@@ -0,0 +1,42 @@
+# Scenery surface caching
+
+`StageRectSurface` renders committed patterned scenery through reusable texture tiles.
+Drawing previews use the adaptive lightweight renderer. Paint remains a single rectangle.
+
+## Camera movement
+
+Tiles use a fixed grid in the surface's local coordinates. Texture resolution changes in
+powers of two, so adjacent wheel steps reuse existing tiles. Panning requests only newly
+exposed tiles. Existing textures stay visible while missing tiles are prepared, with a
+lightweight surface motif beneath them to prevent blank areas.
+
+`StageSurfaceCache` keeps queued tiles as metadata. A shared queue creates and renders at
+most one tile per process frame across all surfaces. It also retires at most two obsolete
+render targets per frame. This avoids large allocations, vector rebuilds, and batches of
+GPU resource releases during camera input.
+
+Each tile has a 256 × 128 pixel core and a four pixel gutter. The gutter is cropped during
+compositing to prevent seams. Each surface requests at most 192 visible tiles and retains
+at most 224 tiles, evicting older unused entries. Half-resolution tiles retain full brick
+texture and wood grain. Only quarter-resolution tiles and below omit fine texture, for
+distant views. Brick and plank positions remain fixed. Detail can fill in progressively
+after movement, including when returning from a distant view to a normal zoom level.
+
+## Invalidation and coverage
+
+Geometry, finish, tint, and motif-origin changes invalidate that surface's tiles. Camera
+movement selects tiles without invalidating their artwork. Render targets belong to the
+surface node; queued references are weak so deleted surfaces cannot keep jobs alive.
+
+Fully opaque rectangular sibling surfaces can suppress artwork entirely hidden behind
+them. Coverage checks account for transforms, draw order, and visibility. Transparent
+surfaces, custom materials, differing relative-Z conventions, and Y-sorted parents disable
+this optimization conservatively. Revealing a surface resumes its pending tiles.
+
+## Verification
+
+`tests/test_scenery_surface_cache.gd` checks rendered appearance against the direct vector
+renderer, tile reuse and invalidation, the shared build limit, allocation and retention
+bounds, and covered-surface behavior. Run it with a graphical Godot renderer for pixel
+comparisons. The adaptive preview regressions remain in
+`tests/test_scenery_surface_preview.gd` and `tests/test_scenery_brick_preview.gd`.