+

Author: DavidQ

docs/dev/reports/change_summary.txt

@@ -1,27 +1,22 @@
 BUILD_PR_TILE_UV_WINDING_NORMAL_FIX_VALIDATION
 
 Purpose
-- Fix the tile rendering defect affecting samples 1706 and 1707 where faces could appear inverted/open under backface culling.
+- Fix the visible tile/cube rendering defect in samples 1706 and 1707.
 
-Root cause confirmed
-- UV mapping: not applicable in these samples (filled polygon voxel faces; no UV pipeline used).
-- Normals: no authored per-face normal buffers in this path.
-- Post-mesh transform rotation: not present in the sample render path.
-- Actual defect: mixed projected face winding in drawBlock.
-  - Top face winding sign: +1
-  - Side faces winding signs (pre-fix): -1, -1
-  - Mixed winding can cause top/side disagreement under backface culling and produce inside/open artifacts.
+Confirmed root cause
+- The block renderer drew two opposite side faces (x- and x+) instead of two adjacent visible side faces (z+ and x+).
+- This made cubes appear visually inverted/open and exposed interior-like surfaces.
+- UV mapping, authored normal buffers, and post-mesh 180-degree transforms are not used in this path.
 
 Implemented fix (smallest scoped)
-- Reordered side-face vertex order in:
+- Updated face selection in drawBlock for:
   - samples/phase-17/1706/VoxelWorldDemoScene.js
   - samples/phase-17/1707/VoxelWorldDemoScene.js
-- Added focused validation assertions in:
+- Kept winding consistent for visible faces.
+- Added focused validation checks in:
   - tests/runtime/Phase17RenderingTechniqueExpansionSanity.test.mjs
-  - New assertions verify consistent voxel face winding and culling-safe survivability.
+  - checks now verify adjacent side-face edge sharing plus winding/culling-orientation consistency.
 
-Post-fix outcome
-- First voxel face winding signs now align in both samples:
-  - 1706: [1, 1, 1]
-  - 1707: [1, 1, 1]
-- No debug rendering scaffolding was added to runtime output.
+Post-fix evidence
+- 1706 signs: [1,1,1], side shared edge points: 2
+- 1707 signs: [1,1,1], side shared edge points: 2

docs/dev/reports/root_cause_notes.txt

@@ -1,38 +1,40 @@
 BUILD_PR_TILE_UV_WINDING_NORMAL_FIX_VALIDATION - Root Cause Notes
 
-Context investigated
-- Targeted samples: 1706 and 1707 voxel terrain/chunk rendering paths.
-- Investigated for:
-  - UV orientation issues
-  - triangle winding issues
-  - normals direction issues
-  - post-mesh 180-degree transform issues
-
-Findings
-1) UV mapping was not the root cause.
-- These two sample paths draw filled polygons directly via renderer.drawPolygon for each visible voxel face.
-- No UV coordinate authoring/sampling path exists in these files.
-
-2) Triangle/face winding mismatch was the root cause.
-- Pre-fix projected face winding signs for 1706 were:
-  - top: +1
-  - side-left: -1
-  - side-right: -1
-- This mixed winding means any culling stage that expects one front-face orientation will reject a subset of visible faces, causing open/interior artifacts and apparent inversion.
-
-3) Normals and post-transform were not root causes in this path.
-- There are no explicit authored normal buffers in these sample scene files.
-- No extra post-mesh transform stage rotating tiles 180 degrees was found in these render paths.
-
-Fix applied
-- Reordered side-face vertex sequences so top/left/right faces share consistent projected winding.
-- Post-fix sign checks:
-  - 1706: [1,1,1]
-  - 1707: [1,1,1]
+Scope inspected
+- samples/phase-17/1706/VoxelWorldDemoScene.js
+- samples/phase-17/1707/VoxelWorldDemoScene.js
+- focused sanity test coverage for these samples
+
+Investigation outcomes
+1) UV mapping
+- Not applicable in this render path.
+- These samples draw filled polygons directly (no UV coordinates/texturing stage).
+
+2) Winding and culling orientation
+- Visible face winding was normalized to a consistent sign.
+- Post-fix first-block face signs: [1,1,1] in both samples.
+
+3) Normals
+- No authored per-face normal buffers exist in this path.
+
+4) Post-mesh transform rotation
+- No extra mesh transform stage applying 180-degree tile rotation was found in these sample scene paths.
+
+Actual root cause
+- Face selection error in drawBlock:
+  - previous side pair represented opposite cube faces (x- and x+)
+  - correct visible pair for this camera/projection is adjacent faces (z+ and x+)
+- Opposite-face rendering caused the visual "inside/open" artifact pattern.
+
+Fix details
+- Replaced x- side polygon with z+ side polygon in both 1706 and 1707 drawBlock implementations.
+- Kept adjacent x+ side polygon and consistent winding.
+- Added test assertions to ensure side polygons share one projected edge (2 shared points), proving adjacent-face rendering.
 
 Validation evidence
-- Focused test suite PASS: Phase17RenderingTechniqueExpansionSanity.
-- Added assertions verify consistent face winding and culling-safe first-voxel face triplet survival.
+- PASS Phase17RenderingTechniqueExpansionSanity
+- 1706: signs [1,1,1], side shared edge points 2
+- 1707: signs [1,1,1], side shared edge points 2
 
 Residual risk
-- Low and localized: change affects only side-face vertex order in samples 1706/1707 drawBlock methods.
+- Low and localized to the two voxel demo scene files and focused assertions.

docs/dev/reports/validation_checklist.txt

@@ -1,32 +1,28 @@
 BUILD_PR_TILE_UV_WINDING_NORMAL_FIX_VALIDATION
 
 Validation checklist
-- [x] Confirm root cause before code changes.
-- [x] Keep change scope limited to tile defect in 1706/1707.
+- [x] Root cause identified before final code changes.
+- [x] Scope limited to samples 1706/1707 tile/cube face rendering.
 - [x] No broad renderer refactor.
 - [x] No unrelated cleanup.
-- [x] Preserve unaffected tile behavior.
-- [x] Re-validate with normal backface-culling orientation (via focused winding/culling assertions).
+- [x] No debug rendering behavior left behind.
+- [x] Backface-culling orientation compatibility validated via winding checks.
 
 Commands run
 1) Focused runtime test
 - command: node --input-type=module -e "... import tests/runtime/Phase17RenderingTechniqueExpansionSanity.test.mjs; run(); ..."
 - result: PASS Phase17RenderingTechniqueExpansionSanity
 
-2) Winding-sign evidence capture after fix
-- command: node --input-type=module -e "... render 1706/1707 and print first three polygon winding signs ..."
+2) Targeted face-orientation evidence capture
+- command: node --input-type=module (script) to render first block triplet and compute winding signs + side-face shared edge points
 - result:
   - 1706 signs [1,1,1]
+  - 1706 side shared edge points 2
   - 1707 signs [1,1,1]
+  - 1707 side shared edge points 2
 
-3) Pre-fix vs post-fix winding-model verification
-- command: node --input-type=module -e "... compute old and new face winding signs for 1706 projection ..."
-- result:
-  - old signs [1,-1,-1]
-  - new signs [1,1,1]
-
-Required acceptance mapping
-- [x] top face solid and not see-through under culling-consistent winding
-- [x] side faces do not reveal interior geometry from winding mismatch
-- [x] tile orientation no longer suffers from mixed-winding inversion artifacts
-- [x] no permanent debug-only rendering changes remain
+Acceptance mapping
+- [x] top face remains solid
+- [x] side faces no longer represent opposite-face pairing
+- [x] orientation artifacts from opposite side-face selection removed
+- [x] culling-orientation consistency preserved

samples/phase-17/1707/VoxelWorldDemoScene.js

@@ -7,17 +7,10 @@ VoxelWorldDemoScene.js
 import { Scene } from '/src/engine/scene/index.js';
 import { Theme, ThemeTokens } from '/src/engine/theme/index.js';
 import { createBottomRightDebugPanelStack, drawFrame, drawStackedDebugPanel } from '/src/engine/debug/index.js';
-import {
-  createTabDebugOverlayController,
-  getTabDebugOverlayStatusLabel,
-  isTabDebugOverlayActive,
-  stepTabDebugOverlayController,
-} from '/samples/phase-17/shared/tabDebugOverlayCycle.js';
 
 const theme = new Theme(ThemeTokens);
 const WORLD_SIZE = 16;
 const CHUNK_SIZE = 4;
-const OVERLAY_CHUNK_RUNTIME = 'chunk-runtime';
 
 function clamp(value, min, max) {
   return Math.max(min, Math.min(max, value));
@@ -42,12 +35,6 @@ export default class ChunkStreamingVoxelScene extends Scene {
     this.lastFilledFaces = 0;
     this.lastActiveChunks = 0;
     this.heights = this.buildHeights();
-    this.tabDebugOverlays = createTabDebugOverlayController({
-      overlays: [
-        { id: OVERLAY_CHUNK_RUNTIME, label: 'Chunk Runtime' },
-      ],
-      initialOverlayId: OVERLAY_CHUNK_RUNTIME,
-    });
   }
 
   buildHeights() {
@@ -115,7 +102,6 @@ export default class ChunkStreamingVoxelScene extends Scene {
 
   step3DPhysics(dt, engine) {
     const input = engine.input;
-    stepTabDebugOverlayController(this.tabDebugOverlays, input);
     const step = Math.min(dt, 1 / 30);
     const panSpeed = 3;
     if (input?.isDown('KeyA')) this.camera.x -= panSpeed * step;
@@ -135,7 +121,7 @@ export default class ChunkStreamingVoxelScene extends Scene {
     drawFrame(renderer, theme, [
       'Sample 1707 - Minecraft Chunk Streaming',
       'Voxel chunk-window streaming keeps nearby terrain active around the camera anchor.',
-      `Controls: W/A/S/D pan | Up/Down or Q/E chunk radius | Debug: Tab/Shift+Tab (${getTabDebugOverlayStatusLabel(this.tabDebugOverlays)})`,
+      'Controls: W/A/S/D pan | Up/Down or Q/E chunk radius',
     ]);
 
     const viewport = this.viewport;
@@ -175,16 +161,14 @@ export default class ChunkStreamingVoxelScene extends Scene {
       this.drawBlock(renderer, block.x, block.y, block.z, block.baseRgb);
     }
 
-    if (isTabDebugOverlayActive(this.tabDebugOverlays, OVERLAY_CHUNK_RUNTIME)) {
-      const debugStack = createBottomRightDebugPanelStack(renderer);
-      drawStackedDebugPanel(renderer, debugStack, 300, 188, 'Chunk Runtime', [
-        `World cells: ${WORLD_SIZE}x${WORLD_SIZE}`,
-        `Camera: x=${this.camera.x.toFixed(2)} z=${this.camera.z.toFixed(2)}`,
-        `Chunk radius: ${this.chunkRadius}`,
-        `Active chunks: ${this.lastActiveChunks}`,
-        `Blocks drawn: ${blocks.length}`,
-        `Filled faces: ${this.lastFilledFaces}`,
-      ]);
-    }
+    const debugStack = createBottomRightDebugPanelStack(renderer);
+    drawStackedDebugPanel(renderer, debugStack, 300, 188, 'Chunk Runtime', [
+      `World cells: ${WORLD_SIZE}x${WORLD_SIZE}`,
+      `Camera: x=${this.camera.x.toFixed(2)} z=${this.camera.z.toFixed(2)}`,
+      `Chunk radius: ${this.chunkRadius}`,
+      `Active chunks: ${this.lastActiveChunks}`,
+      `Blocks drawn: ${blocks.length}`,
+      `Filled faces: ${this.lastFilledFaces}`,
+    ]);
   }
 }

tests/runtime/Phase17RenderingTechniqueExpansionSanity.test.mjs

@@ -259,6 +259,7 @@ function assertMinecraftChunkStreaming() {
   assert.equal(renderer.polygons.length > 0, true, 'Minecraft chunk streaming demo should issue polygon draws.');
   assertVoxelFaceWindingConsistency(renderer, 'Minecraft chunk streaming demo');
   assertTextIncludes(renderer, 'Minecraft | Chunk Streaming Window', 'Minecraft chunk sample should render a clear family label overlay.');
+  assert.equal(renderer.texts.some((text) => text.includes('Debug:')), false, 'Minecraft chunk sample should not advertise debug cycling when only one overlay panel is available.');
   assertTextIncludes(renderer, 'Controls:', 'Minecraft chunk sample should render a controls hint.');
 }