Repaired the GitHub Pages build environment by installing t... (+4 more)

- Repaired the GitHub Pages build environment by installing the declared
  Python dependencies under Python 3.12 and using deterministic `npm ci` installs.
- Enabled the setup actions' npm and pip download caches, keyed from
  `package-lock.json` and `pip_requirements-dev.txt`.
- Separated browser-derived scene-stat validation from the production Pages
  build. Pages now builds and uploads `dist/` without installing or launching Playwright; the fast ...
- The failed Pages run stopped in `pipeline/gen_object_library.py` because
  `lxml` was declared but not installed. The workflow now consumes the repository dependency manife...
- The local Pages build reached the browser-only scene-stat stage after
  generation, type-checking, and bundling, confirming that Python dependency installation was the r...

Author: vosslab

build_github_pages.sh

@@ -15,7 +15,6 @@
 #   dist/<protocol_name>.html    -- one per entry in generated PROTOCOLS_INDEX,
 #                                   templated from src/protocol_host_template.html
 #   dist/.nojekyll               -- GitHub Pages flag
-#   generated/scene_render_stats/<scene>.stats.json -- renderer-derived scene geometry consumed by SCENE-LINT/SCENE-DESIGN
 #
 # Contract:
 #   - Wipes dist/ from scratch.
@@ -158,14 +157,4 @@ test -f dist/style.css
 test -f dist/bench_basic.html
 test -f dist/scene_viewer.html
 
-# 10. Generate scene render-stats (renderer-derived build evidence).
-#     SCENE-LINT and SCENE-DESIGN consume generated/scene_render_stats/*.stats.json.
-#     Generate them now that dist/ exists -- the renderer loads the built dist.
-#     Stats only (no --png); PNG screenshots are optional human evidence.
-node tools/scene_to_png.mjs --all
-compgen -G "generated/scene_render_stats/*.stats.json" > /dev/null || {
-	echo "ERROR: scene render stats were not generated" >&2
-	exit 1
-}
-
-echo "Built dist/ + scene render stats (GitHub Pages-ready)."
+echo "Built dist/ (GitHub Pages-ready)."

docs/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 2026-07-30
+
+### Fixes and Maintenance
+
+- Repaired the GitHub Pages build environment by installing the declared
+  Python dependencies under Python 3.12 and using deterministic `npm ci`
+  installs.
+- Enabled the setup actions' npm and pip download caches, keyed from
+  `package-lock.json` and `pip_requirements-dev.txt`.
+- Separated browser-derived scene-stat validation from the production Pages
+  build. Pages now builds and uploads `dist/` without installing or launching
+  Playwright; the fast and exhaustive validation front doors still render the
+  required scene statistics explicitly before content validation.
+
+### Developer Tests and Notes
+
+- The failed Pages run stopped in `pipeline/gen_object_library.py` because
+  `lxml` was declared but not installed. The workflow now consumes the
+  repository dependency manifests instead of relying on runner-global tools.
+- The local Pages build reached the browser-only scene-stat stage after
+  generation, type-checking, and bundling, confirming that Python dependency
+  installation was the reported CI blocker. The browser launch then hit the
+  known macOS sandbox Mach-port restriction, which no longer affects Pages.
+
 ## 2026-07-29
 
 ### Behavior or Interface Changes

docs/FILE_STRUCTURE.md

@@ -370,7 +370,7 @@ All gitignored (see [.gitignore](../.gitignore)):
 | `generated/protocol_materials.ts` | [gen_protocols.py](../pipeline/gen_protocols.py) (per-protocol material registry; keyed by protocol_name) |
 | `generated/flow_views/<protocol_name>.txt` | [gen_flow_view.py](../pipeline/gen_flow_view.py) (per-protocol audit view; not the design source) |
 | `generated/precomputed_layout.ts` | [precompute_layout.mjs](../pipeline/precompute_layout.mjs) (`PRECOMPUTED_LAYOUT`: per-scene `{ final: ComputedItem[] }` at canonical 16:9) |
-| `generated/scene_render_stats/<scene>.stats.json` | renderer-produced scene geometry stats (build evidence consumed by SCENE-LINT/SCENE-DESIGN), written by [build_github_pages.sh](../build_github_pages.sh) via [scene_to_png.mjs](../tools/scene_to_png.mjs) |
+| `generated/scene_render_stats/<scene>.stats.json` | renderer-produced scene geometry stats consumed by SCENE-LINT/SCENE-DESIGN, written by [scene_to_png.mjs](../tools/scene_to_png.mjs) after the Pages bundle is built |
 | `dist/` | [build_github_pages.sh](../build_github_pages.sh) (GitHub Pages bundle) |
 | `dist/assets/svg/<category>/<name>.svg` | SVG assets copied by [build_github_pages.sh](../build_github_pages.sh) |
 | `dist/scene_viewer.html` | Copied from `src/scene_viewer_template.html` during build |

run_fast_checks.sh

@@ -9,17 +9,17 @@
 # Runs (in order):
 #   1. Full build (./build_github_pages.sh). Regenerates generated/
 #      (object_library, svg_manifest, scenes, protocols), precomputes the
-#      static scene layout, type-checks, bundles into dist/, and renders
-#      generated/scene_render_stats/<scene>.stats.json. That render step
-#      (node tools/scene_to_png.mjs --all, run internally by
-#      build_github_pages.sh) is REQUIRED before validate: SCENE-LINT's
-#      geometry checks read the stats files, and without them validate
-#      reports missing_render_evidence instead of a real geometry result.
-#   2. TypeScript gate (./check_codebase.sh: tsc, tsc --lint config,
+#      static scene layout, type-checks, and bundles into dist/.
+#   2. Render scene statistics with Playwright
+#      (node tools/scene_to_png.mjs --all). This is REQUIRED before
+#      validation: SCENE-LINT's geometry checks read the stats files, and
+#      without them validation reports missing_render_evidence instead of a
+#      real geometry result.
+#   3. TypeScript gate (./check_codebase.sh: tsc, tsc --lint config,
 #      eslint, prettier --check, node --test).
-#   3. Python tests (pytest tests/).
-#   4. Content validation (bash run_validate.sh), which reads the renderer
-#      evidence produced in step 1.
+#   4. Python tests (pytest tests/).
+#   5. Content validation (bash run_validate.sh), which reads the renderer
+#      evidence produced in step 2.
 #
 # Exit code is 0 only when every step passes. A step failure prints a
 # summary and exits non-zero immediately; it does not mask or skip later
@@ -132,17 +132,19 @@ trap print_summary EXIT
 SUMMARY_ENABLED=1
 
 # 1. Full build: regenerates generated/, precomputes layout, type-checks,
-#    bundles dist/, and renders generated/scene_render_stats/ (required
-#    render evidence for run_validate.sh's SCENE-LINT stage below).
+#    and bundles dist/.
 step_run build bash build_github_pages.sh
 
-# 2. TypeScript gate (typecheck, typecheck:lint, lint, format:check, test:node).
+# 2. Render evidence for run_validate.sh's SCENE-LINT stage below.
+step_run render_stats node tools/scene_to_png.mjs --all
+
+# 3. TypeScript gate (typecheck, typecheck:lint, lint, format:check, test:node).
 step_run typescript ./check_codebase.sh
 
-# 3. Python tests.
+# 4. Python tests.
 step_run pytest pytest tests/
 
-# 4. Content validation against generated evidence.
+# 5. Content validation against generated evidence.
 step_run validate bash run_validate.sh
 
 # All steps complete; summary prints via EXIT trap. Exit 0 (failure paths

run_validate.sh

@@ -2,9 +2,11 @@
 #
 # run_validate.sh validates the repository against EXISTING generated evidence.
 # Scene layout validation reads renderer-produced stats from
-# generated/scene_render_stats/<scene>.stats.json, produced by build_github_pages.sh.
+# generated/scene_render_stats/<scene>.stats.json, produced by
+# `node tools/scene_to_png.mjs --all` after building dist/.
 # This script validates only: it never renders scenes or parses PNG pixels.
-# If the stats are missing, validation fails clearly -- run ./build_github_pages.sh first.
+# If the stats are missing, validation fails clearly -- build, then render the
+# scene statistics before running this script.
 # Additional validator flags are forwarded, so release callers can run
 # `./run_validate.sh --strict` to promote warnings to a failing exit status.
 set -e

super_all_tests.sh

@@ -163,9 +163,10 @@ main() {
 	echo "Running the full suite. Details in $LOG"
 	echo ""
 
-	# --- 1. Build first. validate, scene metrics, and the browser tests all
-	#        read what this produces (generated/, dist/, render stats). ---
+	# --- 1. Build dist/, then render the scene statistics consumed by
+	#        validation and scene metrics. ---
 	run "build" bash build_github_pages.sh
+	run "render_stats" node tools/scene_to_png.mjs --all
 
 	# --- 2. Code and content gates. ---
 	run "check_codebase" ./check_codebase.sh