Fail fast on missing terrain assets and recover empty renders

docs/server-plugin.md

@@ -68,6 +68,29 @@ If the worker stops renewing its lease, the page warns that it has stopped repor
 - `minegeo status` reports the active stage and the last completed export folder.
 - `minegeo help` lists commands.
 
-If processing fails on the website, read the draft's error. Fix the worker/setup or reduce the export area, then create and upload a new export. Keep the old folders until you no longer need them.
+If processing fails on the website, read the draft's error. A renderer/setup failure can be retried using the already uploaded export; you do not need to export or upload it again.
+
+### Recover an empty render
+
+A report with `meshes: 0`, `emittedFaces: 0`, and ordinary blocks such as stone and dirt in `unsupported` means Minecraft assets did not reach the renderer. Those renders previously completed incorrectly with sky-only images. Assets are local to each host: the ignored `.cache` folder does not transfer when pulling Git changes.
+
+The worker now prepares missing/incomplete vanilla assets before rendering. Setup prepares them before installing Chromium, so a browser installation failure cannot skip the asset download. A completion marker is written after extraction; core models/textures are checked on subsequent runs. Missing models, zero geometry, lost graphics contexts and sky-only downward/map images fail processing instead of producing a playable draft.
+
+To regenerate an existing unpublished draft after pulling this fix:
+
+1. Stop MineGeo with Ctrl+C so its worker is stopped.
+2. Run this from the repository root, replacing the UUID with the draft's ID:
+
+   ```sh
+   npm run reprocess -- 00ff0076-cae1-4a0d-ab81-9014833309f4
+   ```
+
+3. Restart with your usual `npm run dev` or `npm start` command. On the Mac test server:
+
+   ```sh
+   PORT=3008 MINEGEO_HOST=0.0.0.0 MINEGEO_ALLOW_ANY_ORIGIN=true npm run dev
+   ```
+
+The maintenance command prepares plugin rendering assets, keeps the original raw export, clears the previous preview metadata and queues a fresh render. It refuses published revisions and active jobs. Inspect the regenerated private draft and submit it for review again. If the export itself is invalid, create and upload a corrected export instead.
 
 Expected limits: Minecraft 1.21.11 / Java 21, Overworld only, five or more safe viewpoints, at most 2048 blocks per selected side and the worker's terrain/file-size limits. A large selection may need to be split into smaller maps.

docs/verification.md

@@ -26,3 +26,17 @@ This pass did not launch a Minecraft client, use Playwright, or use the Computer
 The subsequent renderer changes replace per-block model transformation and texture loading with cached state templates, numeric section bitsets, bounded typed geometry buffers and spatial meshes. WebP output avoids an intermediate PNG encode, and processed-image uploads run in a four-request pool. GPU selection is automatic with software fallback on initialization failure.
 
 No tests, browsers or benchmarks were run for this change at the user's request. Its speedup and image fidelity on the 2,651,888-block Mac export are unverified. The new per-stage timings, blocks-per-second logs and geometry counts provide measurements for the next real run.
+
+## Empty-render recovery
+
+The subsequent Mac report showed 2,651,888 input blocks but zero meshes, emitted faces and geometry bytes. Ordinary vanilla block models and fluid textures were all unavailable. The worker previously skipped those failures and completed sky-only previews. The fix prepares missing/incomplete assets before rendering, checks extraction completion, and rejects zero geometry or sky-only downward/map output.
+
+After the user authorized tests again, the following checks passed on Windows using the pinned Playwright 1.56.1 / Chromium 1194 product renderer:
+
+- All 27 unit tests, including missing/interrupted asset caches, missing textures, corrupted client checksums, negative-coordinate occupancy, geometry-buffer growth, sky-only WebP rejection, and reprocessing safety/rollback.
+- TypeScript checking with incremental caching disabled.
+- A 4,913-block grass/water/tree/building fixture: 29 meshes, 6,521 emitted faces, no unsupported states, valid WebP faces and visible downward terrain at all five viewpoints.
+- The cached real Paper export: 17,738 blocks, 31 states, 71 meshes, 62,727 emitted faces, no unsupported states, valid map/cubemap images and visible downward terrain at all 12 viewpoints.
+- A nonexistent block model failed with an explicit missing-assets error instead of completing an empty draft.
+
+Both worker renders closed their Chromium processes automatically. No Minecraft server/client or website UI automation was started. Outputs and reports are under `.cache/renderer-regression`; `npm run test:renderer` reproduces the fixture, and a cached export folder can be supplied as an argument. The full 2,651,888-block dataset and Intel Metal/macOS behavior still require regeneration on the Mac. No speedup claim is inferred from the small Windows fixtures.