docs: 2026-07-16 full audit - sync every doc to as-built engine reality#117
Merged
Conversation
Eight parallel audits of docs/ (+ CLAUDE.md/README/spec) against the code and git history; every verified discrepancy fixed: - HW-GI opt-in (66dad5b) reflected everywhere it was missing: PT docs, perf README, lumen-roadmap, renderer spec. SW GI is the documented shipping default; BLOOM_HW_GI=1 / BLOOM_PT / --pt is the opt-in. - Stale statuses: perf 003/004/007/007a/007b/013 'open' -> landed; 005 'prototype failed' -> revived and landed as EN-044; 014's SDF disk cache 'not landed' -> landed (sdf_cache.rs); 011 notes the ffi_core define_core_ffi! consolidation that replaced per-platform copies. - tickets.md: EN-054 marked shipped (d30fba9), EN-040 registered (it shipped unregistered), EN-021/022/023 'pending merge' cleared, EN-058(c) struck as measured, EN-060/EN-062 numbering note added. - RFC 0001 'Draft' -> implemented (ABI v3) with a new §10 as-built map; RFC 0002 gains as-built notes (setSunDirection does NOT drive the directional light; equirect IBL, CPU-baked LUTs, real signatures). - watchOS docs rewritten: SceneKit 3D + glb loader exist ('No 3D' was false); CLAUDE.md's 'README only' line replaced; visionos added. - Counts and signatures verified against source: ~470 FFI functions (121 physics), joint UBO 1024 not 128, Vertex3D stride 96 with tangent, updateModelAnimation 8-arg with rotY in radians, mixer API (EN-028) + instantiateAnimation (EN-055) documented, web glue is wrapFfiForI64 pass-through (no __perryToJsValue). - Two stale code comments fixed alongside: graph.rs no longer claims the render graph is unwired; pt_pass.rs a-trous comment says six iterations (1/2/4/8/16/1) - PT-3b doc corrected to match. Full audit trail in the session; crash-triage-windows.md, ios-target.md and world-format.md audited clean, no changes needed.
📝 WalkthroughWalkthroughThe PR aligns architecture, platform, FFI, renderer, physics, animation, performance, RFC, and ticket documentation with current as-built behavior, including Web/WASM and watchOS integration details and opt-in hardware GI behavior. ChangesEngine documentation alignment
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/perf/013-lumen-surface-cache.md`:
- Line 3: Update the 013-lumen-surface-cache document’s approach and cost-model
references from 256×256 cards to the landed 64×64 resolution, and recalculate
the associated bandwidth and VRAM estimates consistently. Keep the as-built
64×64 summary and other unrelated performance details unchanged.
In `@docs/perf/014-lumen-mesh-sdfs.md`:
- Around line 117-120: Rename the “Disk cache for MDFs” row in the feature table
to use SDF terminology consistently, while preserving its existing plan and
landed details.
In `@docs/skeletal-animation.md`:
- Line 186: Update the legacy API example’s updateModelAnimation call to define
the rotation value before use, either by passing 0.0 directly or declaring const
rotY = 0.0 immediately beforehand.
In `@docs/web-target.md`:
- Line 39: Update the architecture and “How It Works” references in
docs/web-target.md to use the generated artifact name bloom_web_bg.wasm
consistently, matching the wasm-pack output; alternatively, explicitly document
any rename before referring to bloom_web.wasm.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: b38a3689-8e88-4e85-b6be-e3a6c56a4f6f
📒 Files selected for processing (35)
CLAUDE.mdREADME.mdbloom-renderer-spec-v2.mddocs/design-api.mddocs/migration-0.5.mddocs/perf/003-stochastic-ssr.mddocs/perf/004-cached-shadow-maps.mddocs/perf/005-depth-prepass.mddocs/perf/006-shadow-pass-culling.mddocs/perf/007-prep-wgpu-upgrade.mddocs/perf/007a-lumen-screen-probes-sw.mddocs/perf/007b-lumen-screen-probes-hw.mddocs/perf/008-visibility-buffer.mddocs/perf/009-gpu-driven-rendering.mddocs/perf/010-async-compute.mddocs/perf/011-cross-platform-ffi.mddocs/perf/012-remaining-bind-group-caches.mddocs/perf/013-lumen-surface-cache.mddocs/perf/014-lumen-mesh-sdfs.mddocs/perf/016-lumen-importance-sampling.mddocs/perf/README.mddocs/perf/lumen-roadmap.mddocs/physics.mddocs/pt/PT-1-progressive-megakernel.mddocs/pt/PT-3b-svgf-denoiser.mddocs/pt/PT-5-integration-and-restir.mddocs/pt/pt-roadmap.mddocs/rfc/0001-material-render-graph.mddocs/rfc/0002-atmospheric-sky.mddocs/skeletal-animation.mddocs/tickets.mddocs/watchos-target.mddocs/web-target.mdnative/shared/src/renderer/graph.rsnative/shared/src/renderer/pt_pass.rs
| # 013 — Lumen Surface Cache (Mesh Cards) | ||
|
|
||
| **Effort:** 1-2 weeks · **Expected gain:** HW bounce reaches full Lumen quality · **Status:** open | ||
| **Effort:** 1-2 weeks · **Expected gain:** HW bounce reaches full Lumen quality · **Status:** landed (V3 — as-built: 64×64 cards in a 4096² atlas, per-frame drained capture queue; see the [README](README.md) 013 row for the landed summary) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Synchronize the card-resolution details.
The new as-built summary says cards are 64×64, but this document still specifies 256×256 cards in the approach and cost model. Update the stale 256×256 references and related bandwidth/VRAM estimates before treating this as the authoritative landed record.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/perf/013-lumen-surface-cache.md` at line 3, Update the
013-lumen-surface-cache document’s approach and cost-model references from
256×256 cards to the landed 64×64 resolution, and recalculate the associated
bandwidth and VRAM estimates consistently. Keep the as-built 64×64 summary and
other unrelated performance details unchanged.
Comment on lines
117
to
+120
| | Sub-feature | Plan | Landed | | ||
| |-------------------------------|-------------------|------------------------------------| | ||
| | Per-mesh MDFs | GPU jump-flood | Brute-force point-triangle (V1) | | ||
| | Disk cache for MDFs | Yes | **Not landed** (in-memory only) | | ||
| | Disk cache for MDFs | Yes | Landed post-V15 (`sdf_cache.rs`, issue #22) | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use SDF terminology consistently.
The table says “Disk cache for MDFs,” while the ticket, implementation path, and later text refer to per-mesh SDFs. Rename this row to avoid documenting a different or nonexistent artifact.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/perf/014-lumen-mesh-sdfs.md` around lines 117 - 120, Rename the “Disk
cache for MDFs” row in the feature table to use SDF terminology consistently,
while preserving its existing plan and landed details.
| // In your game loop: | ||
| const time = getTime(); // seconds since start | ||
| updateModelAnimation(animHandle, 0, time, 1.0, playerX, playerY, playerZ); | ||
| updateModelAnimation(animHandle, 0, time, 1.0, playerX, playerY, playerZ, rotY); |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the relevant section of the documentation with line numbers.
sed -n '150,210p' docs/skeletal-animation.md | cat -nRepository: Bloom-Engine/engine
Length of output: 3856
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Print the relevant section and search for any rotY definition in the file.
echo "== relevant section =="
sed -n '150,210p' docs/skeletal-animation.md | cat -n
echo
echo "== rotY occurrences =="
rg -n '\brotY\b' docs/skeletal-animation.md || trueRepository: Bloom-Engine/engine
Length of output: 4352
Define rotY in the legacy API example. The snippet passes rotY without declaring it, so the example is incomplete as written. Use 0.0 directly or add const rotY = 0.0 before the call.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/skeletal-animation.md` at line 186, Update the legacy API example’s
updateModelAnimation call to define the rotation value before use, either by
passing 0.0 directly or declaring const rotY = 0.0 immediately beforehand.
|
|
||
| This runs: | ||
| 1. `wasm-pack build` to compile `native/web/` → `bloom_web.wasm` + JS bindings | ||
| 1. `wasm-pack build` to compile `native/web/` → `pkg/bloom_web_bg.wasm` + `pkg/bloom_web.js` bindings |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== file list =="
git ls-files 'docs/web-target.md' 'build.sh' 'native/web' 2>/dev/null || true
echo
echo "== docs/web-target.md outline =="
ast-grep outline docs/web-target.md --view expanded || true
echo
echo "== docs/web-target.md relevant lines =="
nl -ba docs/web-target.md | sed -n '1,220p'
echo
echo "== search for bloom_web file names =="
rg -n 'bloom_web(_bg)?\.wasm|bloom_web\.js|wasm-pack build|rename|mv .*\.wasm' docs build.sh native -S || trueRepository: Bloom-Engine/engine
Length of output: 649
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== build-related files =="
fd -a 'build.sh|.*\.sh$' . | sed -n '1,120p'
echo
echo "== search for wasm rename/copy behavior =="
rg -n 'bloom_web_bg\.wasm|bloom_web\.wasm|mv .*wasm|cp .*wasm|rename' . -S
echo
echo "== docs/web-target.md around the cited lines =="
nl -ba docs/web-target.md | sed -n '30,170p'Repository: Bloom-Engine/engine
Length of output: 2634
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== docs/web-target.md lines 1-170 =="
sed -n '1,170p' docs/web-target.md | cat -n
echo
echo "== native/web/build.sh lines 1-180 =="
sed -n '1,180p' native/web/build.sh | cat -nRepository: Bloom-Engine/engine
Length of output: 12041
Use the generated wasm name consistently. The architecture and “How It Works” steps still reference bloom_web.wasm, but the build outputs pkg/bloom_web_bg.wasm and copies it unchanged. Update those references, or document a rename, so readers load the correct artifact.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/web-target.md` at line 39, Update the architecture and “How It Works”
references in docs/web-target.md to use the generated artifact name
bloom_web_bg.wasm consistently, matching the wasm-pack output; alternatively,
explicitly document any rename before referring to bloom_web.wasm.
This was referenced Jul 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Full audit of
docs/(plusCLAUDE.md,README.md,bloom-renderer-spec-v2.md) against the current code and git history. Eight parallel audit passes; every verified discrepancy fixed. 35 files, +462/-184.Headline corrections
BLOOM_HW_GI=1/BLOOM_PT/--pt(measured +20 ms/frame on the 760M, b34c1f3).visionos/added to the architecture tree.sdf_cache.rs); 011 now documents thedefine_core_ffi!consolidation.setSunDirectiondoes not drive the directional light.Vertex3Dstride 96 (tangent field),updateModelAnimation8-arg withrotYin radians, EN-028 mixer + EN-055instantiateAnimationdocumented, web glue iswrapFfiForI64pass-through (__perryToJsValuenever existed in the glue).graph.rs'NOT yet wired' andpt_pass.rsà-trous count — the array runs six iterations (1/2/4/8/16/1); PT-3b corrected to match.Audited clean, no changes needed:
crash-triage-windows.md,ios-target.md,world-format.md.Note:
build-webis red on main independently of this PR — EN-055 (323a6c9) introduced ungatedanim_mixer/gltf/StagedModelreferences inmodels.rsthat break--no-default-features --features web. Every main run since PR #107 fails the same job; now registered as EN-063 in tickets.md (second commit) with root cause and fix sketch.Summary by CodeRabbit