Amberstone Lodge

Problem: Initial Python import failed with ModuleNotFoundError: mcio even though source existed in the repository.

Detection: Failed import + inspection of sibling MCIO directory — distinguished import-path problem from missing source.

Solution: Locate sibling source relative to the generator; use uv with the script's small declared dependency set.

Result: Generation and tests run with existing local source.

Problem: An inspected demo path stripped state suffixes, losing stair orientation, trapdoor halves, and other essential properties. A library data-version comment also disagreed with the actual target release.

Detection: Source inspection before choosing the export path (prevented risk, not an actual corrupted file).

Solution: Use the block-state-aware canvas, validate properties against the 1.21.1 registry, read data version from the cached release archive.

Result: File reports data version 3955. Tests verify normalized exact block-state reload.

Problem: Importing the compiled headless renderer failed — it did not export renderLitematicWithMetadata.

Detection: Import error + comparison with TypeScript source entry point.

Solution: Run wrapper against TypeScript source via installed vite-node with xvfb-run for headless display.

Result: Previews rendered successfully. Asset warnings remain and were not eliminated.

Problem: Two screenshots cannot determine every dimension, hidden wall, floor connection, or roof intersection.

Solution: Use the approved scale, preserve the identifying composition and palette, design compatible unseen rooms and elevations.

Result: Reference-inspired lodge. Exact equivalence to the original builder's model remains unverified.

Problem: Design coordinates use XYZ; canvas uses YZX. Increasing X is not the viewer's right when facing north. Mirroring positions alone leaves directional states inconsistent.

Detection: Inspection of canvas API and north-facing view convention, then exported coordinate/state checks.

Solution: Convert axes explicitly; reflect X at export; also exchange east/west states, door hinges, left/right stair shapes; transform banner positions and crop origins consistently.

Result: Tower appears on viewer's right from north. Tests cover exported orientation.

Problem: The reference combines concave slopes, flared eaves, a lower roof, and dormers. Thin rows leave discontinuities where height changes sharply.

Solution: Configurable height profiles, fill vertical transitions between steep rows, combine overlapping surfaces by maximum height. Add layered edges, ridge detailing, restrained material variation.

Result: Main roof silhouette recognizable. Did not automatically seal all adjacent wall and dormer gaps (see #6).

Problem: Build could look roofed from front while interior air still connected to the schematic boundary.

Detection: Six-neighbor air flood-fill from indoor probes with doors treated as shut. Escape coordinates localized gaps more precisely than visual inspection.

Solution: Six targeted joins — floor cap beneath tower dormer, raised rear-wing infill, extended low-dormer infill, missing rear gable, closed front dormer peak, glazed entrance transom.

Result: v002+ pass all 7 indoor enclosure probes. Negative test confirms the check rejects a deliberately opened ridge.

Problem: Bedroom and attic failed access checks despite placed stairs. Two separate causes.

Detection: Room-reachability results + inspection of stair columns and headroom.

Solution: Stop access-clearing from erasing the first stair. Replace solid stair supports (which blocked lower flights) with shallow supports. Clear headroom, adjust landings and rail openings.

Result: All 8 destinations reachable in the discrete walking model.

Problem: Candles and plants floated over thin surfaces. Lantern chains ended below supporting beams. Early forge chain interfered with roof support.

Detection: Interior previews, coordinate inspection, and targeted support diagnostics.

Solution: Top slabs or inverted stairs for tabletops, align decorations with support surfaces, add missing supports, extend hanging chains to beams, use persistent leaves for custom pines.

Result: Final support tests pass for checked candles, pots, campfires, lanterns, banners, and leaves.

Problem: Green bed sat below the full-height paneled frame, weakening the most recognizable interior detail.

Detection: Bedroom views showed that legal bed blocks and correct two-part pairing were insufficient for a convincing visible bed.

Solution: Raise bed one block onto a dark oak base while retaining the lower paneled frame.

Result: Green mattress visible; two paired beds remain valid. Trade-off: taller platform bed.

Problem: A green banner block alone does not encode white stripes. The canvas route did not carry banner block entities automatically.

Detection: Inspection of export representation and banner data requirements.

Solution: Inject two banner block entities with modern patterns data, three white stripe patterns each, and correctly reflected integer positions before compression.

Result: Focused test verifies identifiers, positions, colors, and patterns in NBT. Previews still display plain green banners — rendering cause not conclusively established. Unresolved visually.

Problem: v002's rear roof exposed bookshelf and beam patches. Enclosure checks passed because a bookshelf is still solid.

Detection: Rear-view inspection + comparing roof-stage snapshot with final block map. Eight replacements identified.

Solution: Move attic shelf inward, shorten beam away from roof sides, place vines only into empty cells. Add check preserving every deepslate cell from the roof/forge snapshot.

Result: v003+ preserve all 1,548 protected roof cells.

Problem (#15): At its inner edge, the canopy rose into the upper wing's glazing at Y=11.

Problem (#16): After fixing the canopy, a separate cobblestone slab trim band still replaced part of the same window's lower edge.

Detection: Exterior inspection, coordinate checks, then a new focused window test that expected glass but found minecraft:cobblestone_slab.

Solution: Reduce canopy rise (#15); skip offending chimney-collar cells at wing wall and window height (#16).

Result: v004 passes the focused test including 6 checked glazing positions. v003 retained with documented defect.

Problem: Early previews had very dark walls and disproportionately bright upper faces.

Detection: Reading the renderer shader — light-direction inputs were face-brightness coefficients involving absolute X/Z normals, not conventional normalized directional light.

Solution: Replace negative components with small positive coefficients; suitable ambient brightness; separate settings for interiors.

Result: Materials legible in subsequent previews. This was a rendering configuration correction, not a palette issue.

Problem: A bedroom cutaway looked toward the headboard, hiding the mattress. Cropping left detached-looking leaves and lights whose supports were outside the crop.

Detection: Comparing cutaways with the full schematic, changing viewing directions.

Solution: Adjust bedroom crop and camera; add rear and straight-front views; render interior perspectives inside the complete schematic.

Result: Final v004 has 9 views. Apparent floating fragments in crops must be verified against the full model.

Problem: Initial reruns reused root schematic and preview paths. Earlier drafts were already gone when version retention was requested.

Solution: Freeze existing artifacts as v001. Write later changes into unused versions/vNNN directories with stage exports, cutaways, source snapshots, validation, and reports. Use exclusive writes for schematics.

Result: v001–v004 remain available. Early overwritten drafts not recovered; v001 lacks same archival coverage as later checkpoints.

Problem: Generation continued after a focused test command failed — exit status not checked.

Solution: Preserve flawed checkpoint with explicit review note; correct the defect in v004; verify passing suite separately.

Result: Final suite passes, but the workflow error was real. A successful export report must not be presented as equivalent to every focused test passing.

Problem: A few edits failed because the requested patch context no longer matched the document exactly.

Detection: apply_patch rejected the affected edits rather than silently applying them incorrectly.

Solution: Re-read relevant text and use smaller, exact-context hunks.

Result: Documentation updated without destructive recovery. Smaller edits would have avoided the friction.

Problem: Fixed geometry does not imply byte-identical files or a fully portable historical environment. A new output directory can be partly written before a later validation failure.

Remaining work: Timestamps can change binary hashes on regeneration. Sibling libraries and resource caches are not fully pinned per snapshot. Renderer wrapper is shared rather than snapshotted per version. Writer exports before completing all validation.

Recommendation: Validate in an isolated staging directory; publish only after every required check succeeds.

Problem: Many placements use fixed architectural coordinates despite a central configuration object. Sequential writes use replacement semantics, so subsystem overlap silently changes existing blocks.

Remaining work: Region ownership, local coordinate frames, and explicit allowed-overlap rules would make future variants safer. Walking check uses discrete cells; enclosure check ignores detailed stair/pane geometry.