Add sample-local README contract and prevent silent fallback for fullscreen preview capture - PR_26126_028-sample-local-readme-and-fullscreen-capture-fix

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,24 +1,34 @@
-# Codex Commands - PR_26126_026-locate-missing-samples
+# Codex Commands - PR_26126_028-sample-local-readme-and-fullscreen-capture-fix
 
 ```bash
-codex run "Create PR_26126_026-locate-missing-samples. Do not modify code. Perform a repo search to determine where sample IDs 0125, 0126, and 0127 are defined or referenced. Search for these IDs across samples, metadata, tool hints, and any index/registry files. Report exact file paths where they exist, or explicitly confirm they do not exist as folders under samples/phase-* directories. If they are referenced but missing physically, identify the source (metadata, index, or generator logic) that is producing them. Output findings only in docs/dev/reports/missing_samples_0125_0126_0127.txt. Produce review artifacts."
+codex run "Create PR_26126_028-sample-local-readme-and-fullscreen-capture-fix. Fix Preview Generator V2 documentation and capture behavior. Add a README.md template under existing sample folders using the pattern samples/phase-xx/XXXX/README.md. The README must explain where the sample implementation actually lives, how the sample folder/index.html launches or bypasses into that code, and how Preview Generator V2 should discover/launch the sample without assuming numeric folders. Do not add a root samples README. Do not modify sample JSON. Also fix Full Screen (1600x900 HTML Page) capture so it does not silently fall back to non-fullscreen capture when html-to-image/html2canvas fails on unsupported CSS color functions such as color(...). For fullscreen mode, capture must either use the intended 1600x900 viewport/full-page path or fail clearly with an actionable error; do not mark OK when fallback was used for fullscreen. Preserve Canvas Only behavior. Produce review artifacts."
 ```
 
 ## Validation Commands
 
 ```bash
-Get-ChildItem -Path samples -Directory -Recurse -ErrorAction SilentlyContinue | Where-Object { $_.Name -in @('0125','0126','0127') } | Select-Object -ExpandProperty FullName
-rg -n --hidden --no-ignore --glob '!node_modules/**' --glob '!.git/**' --glob '!tmp/**' --glob '!**/*.svg' --glob '!**/*.png' --glob '!**/*.jpg' --glob '!**/*.jpeg' --glob '!**/*.gif' --glob '!**/*.zip' "\b(0125|0126|0127)\b" samples docs tools src scripts tests games package.json *.json *.md
-Select-String -Path tools/preview-generator-v2/index.html -Pattern 'resolveSamplePhase|phaseDir.entries|hasIndexHtml|sampleEntries.push|sampleEntries.sort|No sample index.html' -Context 2,3
-Select-String -Path @('scripts/generate-sample-manifest.mjs','scripts/generate-samples-index.mjs','scripts/generate-runtime-sample-previews.mjs') -Pattern 'readdir|phase-|index.html|samplesDir|sampleId|id' -Context 2,3
-Select-String -Path samples/metadata/metadataReference.js,samples/metadata/samples.index.metadata.json -Pattern '0125|0126|0127|0124|0101|phase-01' -Context 1,2
-rg -n "0225|0226|0227" samples/metadata/samples.index.metadata.json samples/index.html samples/index.render.js --glob '!**/*.svg'
-rg -n -i "executeSample|execute sample|sample-card|samples-phase-list|samples-pinned-list|buildSampleRows|createSampleCard" samples/index.html samples/index.render.js samples/metadata/samples.index.metadata.json
-git diff --check -- docs/dev/reports/missing_samples_0125_0126_0127.txt docs/dev/codex_commands.md docs/dev/commit_comment.txt
-git diff --cached --name-only -- samples games start_of_day tools src scripts tests
+$sampleDirs = Get-ChildItem samples -Directory -Filter 'phase-*' | Sort-Object Name | ForEach-Object { Get-ChildItem $_.FullName -Directory | Where-Object { $_.Name -match '^\d{4}$' } | Sort-Object FullName }
+$missingReadmes = $sampleDirs | Where-Object { !(Test-Path (Join-Path $_.FullName 'README.md')) }
+if ($missingReadmes) { $missingReadmes.FullName; throw "Missing sample README files." }
+if (Test-Path samples/README.md) { throw "Unexpected root samples/README.md" }
+$sampleReadmes = $sampleDirs | ForEach-Object { Join-Path $_.FullName 'README.md' }
+rg -n "SAMPLE_LOCAL_CONTRACT_README|Preview Generator V2 discovers samples|SKIP|FAIL|games/<gamename>|index.html is the only discovery" $sampleReadmes
+rg -n "Full Screen capture failed|html2canvas may not support CSS color functions|extractBestToolFallbackSvg|using fallback" tools/preview-generator-v2/index.html
+git diff --check
+git diff --cached --name-only -- '*.json' start_of_day tools/shared tools/schemas
+npm run test:workspace-v2
+npm test
 npm run codex:review-artifacts
 ```
 
-## Notes
+## Playwright
 
-No Playwright impact. This PR is search/report only and does not modify runtime code, samples, schemas, or tests.
+No Playwright test was added. This PR changes documentation and Preview Generator V2 fullscreen capture error handling only. `npm run test:workspace-v2` was attempted but is not defined in the current `package.json`.
+
+## Test Notes
+
+`npm test` was attempted as the available default test gate and failed in the existing shared extraction guard baseline before this PR's changed Preview Generator V2 code or README files were involved. The reported violations are outside this PR scope.
+
+## Manual Test
+
+Use Preview Generator V2 with Canvas Only to confirm existing canvas capture still works. Use Full Screen (1600x900 HTML Page) on a target with unsupported CSS color functions and confirm it logs a clear `FAIL` instead of silently falling back to a non-fullscreen capture.

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Locate missing sample IDs 0125-0127 - PR_26126_026-locate-missing-samples
+Document sample-local contracts and harden fullscreen preview capture - PR_26126_028-sample-local-readme-and-fullscreen-capture-fix

docs/dev/reports/codex_changed_files.txt

@@ -1,19 +1,282 @@
-# PR_26126_026-locate-missing-samples
+# git status --short
+M  docs/dev/codex_commands.md
+M  docs/dev/commit_comment.txt
+A  samples/phase-01/0101/README.md
+A  samples/phase-01/0102/README.md
+A  samples/phase-01/0103/README.md
+A  samples/phase-01/0104/README.md
+A  samples/phase-01/0105/README.md
+A  samples/phase-01/0106/README.md
+A  samples/phase-01/0107/README.md
+A  samples/phase-01/0108/README.md
+M  samples/phase-01/0109/README.md
+M  samples/phase-01/0110/README.md
+M  samples/phase-01/0111/README.md
+M  samples/phase-01/0112/README.md
+M  samples/phase-01/0113/README.md
+M  samples/phase-01/0114/README.md
+M  samples/phase-01/0115/README.md
+M  samples/phase-01/0116/README.md
+M  samples/phase-01/0117/README.md
+M  samples/phase-01/0118/README.md
+M  samples/phase-01/0119/README.md
+M  samples/phase-01/0120/README.md
+M  samples/phase-01/0121/README.md
+M  samples/phase-01/0122/README.md
+M  samples/phase-01/0123/README.md
+M  samples/phase-01/0124/README.md
+M  samples/phase-02/0201/README.md
+M  samples/phase-02/0202/README.md
+M  samples/phase-02/0203/README.md
+M  samples/phase-02/0204/README.md
+M  samples/phase-02/0205/README.md
+M  samples/phase-02/0206/README.md
+M  samples/phase-02/0207/README.md
+M  samples/phase-02/0208/README.md
+M  samples/phase-02/0209/README.md
+M  samples/phase-02/0210/README.md
+M  samples/phase-02/0211/README.md
+M  samples/phase-02/0212/README.md
+M  samples/phase-02/0213/README.md
+M  samples/phase-02/0214/README.md
+M  samples/phase-02/0215/README.md
+M  samples/phase-02/0216/README.md
+M  samples/phase-02/0217/README.md
+M  samples/phase-02/0218/README.md
+M  samples/phase-02/0219/README.md
+M  samples/phase-02/0220/README.md
+M  samples/phase-02/0221/README.md
+M  samples/phase-02/0222/README.md
+M  samples/phase-02/0223/README.md
+M  samples/phase-02/0224/README.md
+A  samples/phase-02/0225/README.md
+M  samples/phase-02/0226/README.md
+M  samples/phase-02/0227/README.md
+M  samples/phase-03/0301/README.md
+M  samples/phase-03/0302/README.md
+M  samples/phase-03/0303/README.md
+M  samples/phase-03/0304/README.md
+M  samples/phase-03/0305/README.md
+M  samples/phase-03/0306/README.md
+M  samples/phase-03/0307/README.md
+M  samples/phase-03/0308/README.md
+M  samples/phase-03/0309/README.md
+M  samples/phase-03/0310/README.md
+M  samples/phase-03/0311/README.md
+M  samples/phase-03/0312/README.md
+M  samples/phase-03/0313/README.md
+M  samples/phase-03/0314/README.md
+M  samples/phase-03/0315/README.md
+M  samples/phase-03/0316/README.md
+M  samples/phase-03/0317/README.md
+M  samples/phase-03/0318/README.md
+M  samples/phase-03/0319/README.md
+M  samples/phase-03/0320/README.md
+M  samples/phase-03/0321/README.md
+M  samples/phase-03/0322/README.md
+M  samples/phase-03/0323/README.md
+M  samples/phase-03/0324/README.md
+A  samples/phase-03/0325/README.md
+A  samples/phase-03/0326/README.md
+A  samples/phase-03/0327/README.md
+M  samples/phase-04/0401/README.md
+M  samples/phase-04/0402/README.md
+M  samples/phase-04/0403/README.md
+M  samples/phase-04/0404/README.md
+M  samples/phase-04/0405/README.md
+M  samples/phase-04/0406/README.md
+M  samples/phase-04/0407/README.md
+M  samples/phase-04/0408/README.md
+M  samples/phase-04/0409/README.md
+M  samples/phase-04/0410/README.md
+M  samples/phase-04/0411/README.md
+M  samples/phase-04/0412/README.md
+A  samples/phase-04/0413/README.md
+A  samples/phase-05/0501/README.md
+A  samples/phase-05/0502/README.md
+A  samples/phase-05/0503/README.md
+A  samples/phase-05/0504/README.md
+A  samples/phase-05/0505/README.md
+A  samples/phase-05/0506/README.md
+A  samples/phase-05/0507/README.md
+A  samples/phase-05/0508/README.md
+A  samples/phase-05/0509/README.md
+A  samples/phase-05/0510/README.md
+A  samples/phase-05/0511/README.md
+A  samples/phase-05/0512/README.md
+A  samples/phase-06/0601/README.md
+A  samples/phase-06/0602/README.md
+A  samples/phase-06/0603/README.md
+A  samples/phase-06/0604/README.md
+A  samples/phase-06/0605/README.md
+A  samples/phase-06/0606/README.md
+A  samples/phase-06/0607/README.md
+A  samples/phase-06/0608/README.md
+A  samples/phase-06/0609/README.md
+A  samples/phase-06/0610/README.md
+A  samples/phase-06/0611/README.md
+A  samples/phase-06/0612/README.md
+A  samples/phase-06/0613/README.md
+A  samples/phase-06/0614/README.md
+A  samples/phase-07/0701/README.md
+A  samples/phase-07/0702/README.md
+A  samples/phase-07/0703/README.md
+A  samples/phase-07/0704/README.md
+A  samples/phase-07/0705/README.md
+A  samples/phase-07/0706/README.md
+A  samples/phase-07/0707/README.md
+A  samples/phase-07/0708/README.md
+A  samples/phase-07/0709/README.md
+A  samples/phase-07/0710/README.md
+A  samples/phase-07/0711/README.md
+A  samples/phase-07/0712/README.md
+A  samples/phase-07/0713/README.md
+A  samples/phase-08/0801/README.md
+A  samples/phase-08/0802/README.md
+A  samples/phase-08/0803/README.md
+A  samples/phase-08/0804/README.md
+A  samples/phase-08/0805/README.md
+A  samples/phase-08/0806/README.md
+A  samples/phase-08/0807/README.md
+A  samples/phase-08/0808/README.md
+A  samples/phase-08/0809/README.md
+A  samples/phase-08/0810/README.md
+A  samples/phase-09/0901/README.md
+A  samples/phase-09/0902/README.md
+A  samples/phase-09/0903/README.md
+A  samples/phase-09/0904/README.md
+A  samples/phase-09/0905/README.md
+A  samples/phase-09/0906/README.md
+A  samples/phase-10/1001/README.md
+A  samples/phase-10/1002/README.md
+A  samples/phase-10/1003/README.md
+A  samples/phase-11/1101/README.md
+A  samples/phase-11/1102/README.md
+A  samples/phase-11/1103/README.md
+A  samples/phase-11/1104/README.md
+A  samples/phase-11/1105/README.md
+A  samples/phase-11/1106/README.md
+M  samples/phase-12/1201/README.md
+M  samples/phase-12/1202/README.md
+M  samples/phase-12/1203/README.md
+M  samples/phase-12/1204/README.md
+M  samples/phase-12/1205/README.md
+M  samples/phase-12/1206/README.md
+M  samples/phase-12/1207/README.md
+M  samples/phase-12/1208/README.md
+A  samples/phase-12/1209/README.md
+A  samples/phase-12/1210/README.md
+A  samples/phase-12/1211/README.md
+A  samples/phase-12/1212/README.md
+ M samples/phase-12/1212/assets/images/preview.svg
+A  samples/phase-12/1213/README.md
+ M samples/phase-12/1213/assets/images/preview.svg
+A  samples/phase-12/1214/README.md
+ M samples/phase-12/1214/assets/images/preview.svg
+A  samples/phase-12/1215/README.md
+ M samples/phase-12/1215/assets/images/preview.svg
+A  samples/phase-12/1216/README.md
+ M samples/phase-12/1216/assets/images/preview.svg
+A  samples/phase-12/1217/README.md
+ M samples/phase-12/1217/assets/images/preview.svg
+A  samples/phase-12/1218/README.md
+ M samples/phase-12/1218/assets/images/preview.svg
+A  samples/phase-12/1219/README.md
+ M samples/phase-12/1219/assets/images/preview.svg
+A  samples/phase-12/1220/README.md
+ M samples/phase-12/1220/assets/images/preview.svg
+A  samples/phase-13/1301/README.md
+A  samples/phase-13/1302/README.md
+A  samples/phase-13/1303/README.md
+A  samples/phase-13/1304/README.md
+A  samples/phase-13/1305/README.md
+A  samples/phase-13/1306/README.md
+A  samples/phase-13/1307/README.md
+A  samples/phase-13/1308/README.md
+A  samples/phase-13/1309/README.md
+A  samples/phase-13/1310/README.md
+A  samples/phase-13/1311/README.md
+A  samples/phase-13/1312/README.md
+A  samples/phase-13/1313/README.md
+A  samples/phase-13/1314/README.md
+A  samples/phase-13/1315/README.md
+A  samples/phase-13/1316/README.md
+A  samples/phase-13/1317/README.md
+A  samples/phase-13/1318/README.md
+A  samples/phase-13/1319/README.md
+A  samples/phase-13/1320/README.md
+A  samples/phase-14/1401/README.md
+A  samples/phase-14/1402/README.md
+A  samples/phase-14/1403/README.md
+A  samples/phase-14/1404/README.md
+A  samples/phase-14/1405/README.md
+A  samples/phase-14/1406/README.md
+A  samples/phase-14/1407/README.md
+A  samples/phase-14/1408/README.md
+A  samples/phase-14/1409/README.md
+A  samples/phase-14/1410/README.md
+A  samples/phase-14/1411/README.md
+A  samples/phase-14/1412/README.md
+A  samples/phase-14/1413/README.md
+A  samples/phase-14/1414/README.md
+A  samples/phase-14/1415/README.md
+A  samples/phase-14/1416/README.md
+A  samples/phase-14/1417/README.md
+A  samples/phase-14/1418/README.md
+A  samples/phase-15/1501/README.md
+A  samples/phase-15/1502/README.md
+A  samples/phase-15/1503/README.md
+A  samples/phase-15/1504/README.md
+A  samples/phase-15/1505/README.md
+A  samples/phase-15/1506/README.md
+A  samples/phase-16/1601/README.md
+A  samples/phase-16/1602/README.md
+A  samples/phase-16/1603/README.md
+A  samples/phase-16/1604/README.md
+A  samples/phase-16/1605/README.md
+A  samples/phase-16/1606/README.md
+A  samples/phase-16/1607/README.md
+A  samples/phase-16/1608/README.md
+A  samples/phase-16/1609/README.md
+A  samples/phase-16/1610/README.md
+A  samples/phase-16/1611/README.md
+A  samples/phase-16/1612/README.md
+A  samples/phase-16/1613/README.md
+A  samples/phase-16/1614/README.md
+A  samples/phase-16/1615/README.md
+A  samples/phase-16/1616/README.md
+A  samples/phase-16/1617/README.md
+A  samples/phase-16/1618/README.md
+A  samples/phase-16/1619/README.md
+A  samples/phase-16/1620/README.md
+A  samples/phase-16/1621/README.md
+A  samples/phase-16/1622/README.md
+A  samples/phase-17/1701/README.md
+A  samples/phase-17/1702/README.md
+A  samples/phase-17/1703/README.md
+A  samples/phase-17/1704/README.md
+A  samples/phase-17/1705/README.md
+A  samples/phase-17/1706/README.md
+A  samples/phase-17/1707/README.md
+A  samples/phase-17/1708/README.md
+A  samples/phase-17/1709/README.md
+A  samples/phase-17/1710/README.md
+A  samples/phase-17/1711/README.md
+A  samples/phase-17/1712/README.md
+A  samples/phase-17/1713/README.md
+A  samples/phase-18/1801/README.md
+A  samples/phase-19/1901/README.md
+A  samples/phase-19/1902/README.md
+M  tools/preview-generator-v2/index.html
 
-Staged PR files:
-- docs/dev/codex_commands.md
-- docs/dev/commit_comment.txt
-- docs/dev/reports/codex_changed_files.txt
-- docs/dev/reports/codex_review.diff
-- docs/dev/reports/missing_samples_0125_0126_0127.txt
-
-Unstaged files excluded from this docs-only PR:
-- samples/phase-12/1212/assets/images/preview.svg
-- samples/phase-12/1213/assets/images/preview.svg
-- samples/phase-12/1214/assets/images/preview.svg
-- samples/phase-12/1215/assets/images/preview.svg
-- samples/phase-12/1216/assets/images/preview.svg
-- samples/phase-12/1217/assets/images/preview.svg
-- samples/phase-12/1218/assets/images/preview.svg
-- samples/phase-12/1219/assets/images/preview.svg
-- samples/phase-12/1220/assets/images/preview.svg
+# git diff --stat
+samples/phase-12/1212/assets/images/preview.svg | 17 ++---------
+ samples/phase-12/1213/assets/images/preview.svg | 17 ++---------
+ samples/phase-12/1214/assets/images/preview.svg | 17 ++---------
+ samples/phase-12/1215/assets/images/preview.svg | 40 ++++++++++++++++---------
+ samples/phase-12/1216/assets/images/preview.svg | 40 ++++++++++++++++---------
+ samples/phase-12/1217/assets/images/preview.svg | 40 ++++++++++++++++---------
+ samples/phase-12/1218/assets/images/preview.svg | 17 ++---------
+ samples/phase-12/1219/assets/images/preview.svg | 17 ++---------
+ samples/phase-12/1220/assets/images/preview.svg | 17 ++---------
+ 9 files changed, 96 insertions(+), 126 deletions(-)