Add public API-surface snapshot regression test; lock #314 freeze decisions

Phase 1 of the #314/#313 plan (docs/plan-313-314.md): commit a deterministic
full-public-API-surface snapshot as the regression net BEFORE the #313
UIEntity::grid -> GridData refactor, so that refactor reduces to a reviewable diff.

tests/unit/api_surface_snapshot_test.py enumerates the complete public mcrfpy
surface (exported types' methods/properties with docstring-derived type + ro/rw,
12 enums with int values, module functions, singletons, the automation submodule)
and diffs it against tests/snapshots/api_surface.golden.txt. Re-baseline with
MCRF_UPDATE_API_SNAPSHOT=1.

Key design points (verified against source + live introspection):
- mcrfpy.Grid IS mcrfpy.GridView and delegates its real API to an internal
  _GridData via tp_getattro -- invisible to dir(). The test walks grid.grid_data
  AND probes delegation integrity on a live instance (69/69 members resolve).
- Behavioral writability probes compensate for docstring-derived ro/rw inference.
- Every exported class is classified FROZEN vs EXPERIMENTAL; the snapshot captures
  the classification so future additions force a deliberate freeze decision.

Freeze decisions recorded in docs/api-audit-2026-04.md:
- F3: grid_pos is the canonical cell-position name (matches the constructor kwarg);
  cell_pos/cell_x/cell_y documented as aliases. Docstrings aligned in UIEntity.cpp.
- F12: deprecated set_scale KEPT in the 1.0 surface (removal would be a new break).
- automation camelCase EXEMPT from the snake_case rule.
- EXPERIMENTAL (exempt): 3D/Voxel, Tiled/LDtk import, Shader, binding helpers.
- FROZEN: core UI/Grid/Entity/value types, enums, procgen (BSP/HeightMap/
  NoiseSource/DijkstraMap/AStarPath), Drawable (root).

Doc/stub regeneration and the entity.texture addition are deferred to Phase 2
(the #313 refactor). Addresses #314.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/api-audit-2026-04.md

@@ -942,3 +942,49 @@ Some types use raw string docstrings for methods instead of MCRF_METHOD macros.
 | Deprecations to resolve | 3 |
 | Documentation gaps | 2 |
 | **Total findings** | **15** |
+
+---
+
+## #314 Freeze Decisions (2026-06, recorded before generating the API-surface snapshot)
+
+The April audit body above is partly stale. Live introspection of the built module gives the
+authoritative counts, and the snapshot test (`tests/unit/api_surface_snapshot_test.py`) is built
+from live introspection, not from this document.
+
+**Corrected live counts (2026-06):** 12 enums (audit said 10 — adds `Perspective` #294 and
+`Heuristic` #315), 46 exported classes, 12 module functions, 7 singletons/constants (incl. the
+`automation` submodule), 1 submodule. `GridPointState` was removed in #294 (its F14 row is moot).
+
+**Per-finding final status:** F1, F4, F6, F10, F11, F13, F14 = RESOLVED (verified in source via
+#304–#308). F2 = correct-by-design (docs-only). F5, F9 = cosmetic, unchanged. F7 (`Music.pitch`),
+F8 (`Font` methods) = Future, explicitly NOT 1.0 blockers.
+
+**Decisions locked for the freeze (the snapshot golden enshrines these):**
+
+- **F3 (cell-position canonical name):** `grid_pos` is canonical (matches the `grid_pos=`
+  constructor argument); `cell_pos`/`cell_x`/`cell_y` are documented aliases. Both share the same
+  getter/setter and remain interchangeable. Docstrings aligned at `src/UIEntity.cpp` getsetters.
+- **F12 (`set_scale`):** KEPT in the 1.0 surface as a documented-deprecated function. Removing it
+  now would itself be a new breaking change; the snapshot locks it in.
+- **`mcrfpy.automation`:** PyAutoGUI-compatibility camelCase (`moveRel`/`dragTo`/etc.) is EXEMPT
+  from the snake_case rule. The snapshot records it in a clearly-labeled section.
+- **`entity.texture` (new in #313):** additive read/write property; getter returns the entity's
+  real texture, `None` only in the degenerate (default_texture-null) case — never re-derefs a null
+  default_texture. Added to the frozen contract + stubs + docs when #313 lands (golden gains exactly
+  one line).
+
+**1.0 freeze scope — class classification** (the snapshot segregates FROZEN vs EXPERIMENTAL):
+
+- **FROZEN (stable 1.0):** core value types (Color, Vector, Font, Texture), UI drawables
+  (Drawable [root], Frame, Caption, Sprite, Line, Circle, Arc), Grid/GridView/Entity, Scene,
+  Window, Timer, Keyboard, Mouse, audio (Sound, SoundBuffer, Music), procgen (BSP, HeightMap,
+  NoiseSource, DijkstraMap, AStarPath), all 12 enums, the snake_case module functions, and the
+  singletons. (Provisionally frozen, flagged for confirmation at golden review: `ColorLayer`,
+  `TileLayer` [core grid layers, distinct from Tiled import], `DiscreteMap` [#293/#294 grid data].)
+- **EXPERIMENTAL (exempt, may change post-1.0):** 3D/Voxel (Billboard, Entity3D,
+  EntityCollection3D[Iter], Model3D, Viewport3D, VoxelGrid, VoxelRegion), Tiled import (TileSetFile,
+  TileMapFile, WangSet), LDtk import (LdtkProject, AutoRuleSet), Shader, and binding helpers
+  (CallableBinding, PropertyBinding).
+
+The snapshot test FAILS on any exported class not classified (forces a deliberate decision for
+future additions).