perf(engine): fuse the particle sweep, bound the spatial grid, and fill the pub-API test gaps

[eastspire]

Summary

Engine per-frame fixes, a pub-interface completion, the test coverage that was missing around both, and a cleanup of 561 constants that only existed to satisfy the hardcoded-strings rule inside the DSL macros. Bumps 0.28.9 -> 0.28.10.

Scope note: the per-frame work is deliberately at the algorithm/architecture level. The per-accessor clone costs in the WebGL uniform cache and the WebGPU descriptor paths were reviewed and left alone — they are Lombok accessor semantics, and changing them belongs in a separate pass.

1. ParticleEmitter::update walked the particle array twice per step

The integration pass applied gravity, velocity and age to every live particle, then a second Vec::retain pass walked the whole array again to drop the expired ones. The two passes are now one: a read cursor integrates each particle and a write cursor compacts the survivors downward.

• One sweep per step instead of two.
• retain moved the whole tail whenever anything died; the swap-based compaction moves only survivors, and nothing at all when nothing expired — the common case for a short-lived emitter.
• The per-particle gravity.scaled(delta_time) is hoisted out of the loop.
• The emission cap reads the live count through the mutable borrow it is about to take, instead of materialising an owned copy of the whole vector to call .len().

Survivor order is preserved, and surviving_particles_keep_their_relative_order_after_compaction pins it as a subsequence check.

2. SpatialHashGrid2D/3D::clear() never released a cell

clear() emptied each cell's Vec but kept every key it had ever seen, so a roaming scene accumulated one permanent map entry per cell ever visited and both the map and the per-tick clear grew for the life of the process. Cells that end the pass empty are now dropped; occupied cells keep their key and buffer, so a stationary body still pays no allocation.

3. A degenerate cell size turned one insert into a billions-long loop

Found by a test, not by inspection. create clamped a non-positive cell size to EPSILON (1e-6), leaving an inverse cell size of 1e6 — a body of ordinary size mapped to a column range in the millions, and a single insert iterated billions of empty cells. The suite hung on it. A cell size that is not finite and strictly positive now falls back to the documented default, shared by the 2D and 3D constructors.

4. ParticleConfig was not configurable from outside the crate

Every tunable carried #[set(pub(crate))], so from outside the crate the emitter could only be built from ParticleConfig::default(); gravity, colours, sizes, angle and spread had no setter at all. The narrowing attributes are removed so the derive emits the public setters — additive, no existing signature changes.

5. 561 constants that only existed to satisfy §1.3c

The hardcoded-strings rule pushes literals into const.rs. Inside the four DSL macros — html!, class!, var!, vars! — that produced indirection with no payoff: a literal in a template is the payload, and the macro already emits the bytes verbatim. The shape of the result is the evidence: 561 constants had exactly one kind of use, a reference from inside a macro body, and 38 const.rs files existed only to hold them.

All 714 references are inlined back to literals, the constants are deleted, and 16 const.rs files that end up with no items are removed along with their mod r#const; declaration and re-export in the sibling mod.rs.

Constants that are genuinely reused are untouched. Four sit on both sides of a macro boundary and keep their name, because the non-macro caller is the real reason they exist:

• FILE_UPLOAD_ID — id: in the template and get_element_by_id in the hook
• ROUTE_HASH_PREFIX — used by the sidebar and navbar link builders
• THEME_DARK — read by the theme hook's match_media comparison
• HOOKS_ASYNC_RESOLVED_VALUE — passed to the resolver in the hook

The rule itself is unchanged for everything else: check 38 went from 552 to 273 hits, and the remainder are literals in ordinary code (item.link.starts_with("http") and similar), not template payloads.

No rendered output changes — every inlined value is the exact string the constant held.

6. Standards violations in the touched files

check 35 (§5.1) reported 5 real hits, all pre-existing. Fixed here: four handlers in example/src/page/event/view/fn.rs that were bare let x = move |_: Event| { bindings while every neighbouring handler in the same file was already Box<dyn FnMut(Event)>, plus pin_pos in docs/build.rs sitting beside an already-boxed order_of. A sixth surfaced in ui/src/component/nav/view/fn.rs once the surrounding const block was deleted; it predates this branch too.

Tests

Nine modules had no coverage at all. The engine suite goes from 136 to 261 cases.

module	covers
cell	EngineCell / MaybeEngineCell, incl. try_set returning Err(value) rather than overwriting
collider	2D/3D AABB, circle, sphere, cross-shape, and AABB3D::broad_phase
easing	all 31 variants: endpoints, symmetry, overshoot legality, closed forms
entity	component lifecycle, tags, object-pool recycling, EventBus routing
particle	lifetime retirement, emission rate, RNG reproducibility, render output, compaction order
scene	register/unregister, switch, deferred transition, update isolation
spatial	hash grid 2D/3D, dedup, query_into buffer reset, cell reclamation
timer	one-shot vs repeating, pause, reset, clamping
tween	delay, pause/resume, loop, ping-pong, completion callback

Two are correctness anchors rather than shape checks: grid_query_never_misses_a_body_a_linear_scan_would_overlap cross-checks the grid against a linear scan, and the compaction test checks survivor order as a subsequence.

Verification

• cargo test -p euv-engine — 261 passed, 0 failed
• cargo clippy -p euv -p euv-ui -p euv-example --all-targets — 0 warnings
• cargo fmt --check — clean, idempotent
• cargo check -p euv -p euv-core -p euv-ui -p euv-example -p euv-docs --target wasm32-unknown-unknown — clean
• staged_file_gate.py (the pre-commit hook) — 0 new violations on all three commits

Standards audit: two false positives fixed in the skill, not papered over

run_check in audit_rust_standards.py decided PASS/FAIL purely on "did the wrapper print anything", never consulting the subprocess exit code. Every wrapper propagates its verifier's verdict through exit "$exit_code", so a passing verifier that printed its own success trailer scored as a violation. Both offenders were filter drift — the wrapper's grep -v guard had fallen out of sync with the verifier's summary string:

• check 27 filtered ^OK: 0 lib, but the script prints OK: 8 lib.rs file(s) checked, no group-order violation
• check 28 filtered ^=== no-comments-in-tests:, but the script prints === no-comments-in-test-files: 0 violation(s) in 0 file(s)

Running either verifier by hand exits 0. Patching the two hardcoded filters would have left the same landmine in the other 25 wrappers, so run_check now trusts the exit code, and the "exited non-zero with no stdout" path reports a real diagnostic instead of silently passing a check that never ran.

Confirmed the fix does not hide real findings: the five genuine §5.1 violations were still reported as 5 hits after the change and were fixed on their own merits.

That last guard immediately exposed a third problem, in the other direction. Check 15 (pure &Foo helper in fn.rs, §1.3.1) had never executed. Its inline awk template carried three compounding defects: {{/}} brace escapes meant for str.format() while substitute() resolves placeholders with a manual .replace(); a split(types, arr, "\n") inside a Python triple-quoted string, so Python ate the escape and awk received a real newline inside a string literal; and a 3-argument match(), a GNU awk extension BSD awk lacks. awk died on every run, and because the verdict came from stdout, the check reported PASS the entire time. It is now a companion script, verify_pure_ref_helper.py, which is portable and self-testable; it scans 10 fn.rs files in this tree and finds 0 violations.

Still open, and deliberately not in this PR

• 389 real pre-existing violations outside the engine and untouched here: check 37 (§2.2 doc comments) has 116 in example/ and ui/; check 38 retains 273 literals that are in ordinary code rather than template payloads. Genuine cleanup work, not patch-sized.
• Checks 16, 17, 18 and 20 cannot run in the sandbox this was developed in. They are inline bash snippets using <<'PY' heredocs, and the sandbox refuses to create the temp file a heredoc needs. They now fail loudly with the shell's own error rather than silently reporting PASS, which is the correct behaviour but means the full-tree audit cannot be demonstrated green here. On an ordinary shell they run normally, and nothing in this branch depends on them.
• TaskRegistry::unregister has a real stale-handle bug. Register A, B, C, unregister A, then unregister B's handle — Vec::remove(1) deletes C. The doc comment claims it "re-resolves the index against the current list rather than trusting a stale one", which the code does not do. The fix needs a generation tag on TaskHandle, changing its shape and new() arity, so it is a breaking change for a minor bump rather than this patch.