Say why the tray waits while shaders compile, and for how long

[drehtuer]

Shows a "Preparing the dice" plate over the tray while a dice material compiles. The plate carries a progress bar and an estimate of the time left, so the wait after an install or update has a visible reason.

Based on #383 (feature/test-cleanup), stacked as .claude/CLAUDE.md asks.

Why

Filament's materials are compiled on the phone for the driver that is there (decision 46). They are kept in codeCacheDir, which Android empties on every update. So the first launch after an install or update spent about 3.2 s on a black tray. A translucent die, the glass table or a textured table then stalled about 2 s mid-throw the first time it was needed. Nothing said why.

How

• FilamentEngine reports a compile only when the material isn't on disk. It calls started before the compile and finished in a finally, so the plate can't get stuck if a compile throws. A normal launch reads the cache and shows nothing.
• ShaderWork / ShaderProgress (plain Kotlin, JVM-tested):
  • libfilamat gives no progress, so the bar fills with elapsed time against an estimate.
  • It is capped at 95 % until the compile actually ends.
  • The text counts down "About N seconds left", then says "Almost done" once the estimate has run out.
• ShaderTimings sets where the estimate comes from:
  • Defaults are the Pixel 10a's figures: opaque 2.4 s and resin 2.0 s measured; glass and table 2.0 s assumed.
  • What this phone actually took is saved to noBackupFilesDir/shader-timings.txt, which survives updates. The next update's bar is then this phone's own figure.
  • A garbled line falls back to its own default.
• Plumbing:
  • RollThread.shaders: StateFlow<ShaderWork> → Tray.shaders, which defaults to never compiling, so fakes and the power-saving tray are unchanged.
  • TrayDriver forwards it to RollScreen.
  • Power-saving mode makes no engine, so the plate never shows there.
• UI (PreparingTheDice):
  • A Plate centred over the tray, under the controls, that ignores touches.
  • The title names what is being prepared: dice, translucent dice, glass table or table.
  • TalkBack gets one polite live announcement, and the bar has progress semantics in whole per cent.
  • All strings are resources.
• Docs:
  • Decision 95.
  • docs/architecture.md: threading, with a mermaid sequence diagram, and the storage layout.
  • docs/physics-and-rendering.md: "Preparing the dice".
  • Prototype option 1za in design/, the design/README.md map, and README's rendering bullet.

Tests and coverage

• ShaderWorkTest (14), ShaderTimingsTest (10) and PreparingTheDiceTest (11, Robolectric, including RollScreen integration).
• render/filament: function 76.6 → 77.5 %, branch 73.3 → 74.6 %.
• feature/roll: function 94.5 → 94.6 %, branch 70.7 → 71.2 %.
• test, detekt, ktlintCheck and lint are green for render/filament, feature/roll and app. render/filament's device-test sources compile.

Device check — Pixel 10a, 2026-10-05

Debug build of this branch, fresh install:

• Cold compile. After run-as … rm -rf code_cache/materials and a relaunch, "Preparing the dice" (opaque) shows, then "Preparing the table" (textured felt). Each has a moving bar and "About N seconds left". The plate goes once the felt is drawn.
• Learnt timings. no_backup/shader-timings.txt holds opaque=2437, table=2243 after the first launch and 2451 / 2180 after the second. The figures are stable, so the defaults are about right.
• Warm relaunch. No plate at all.
• Fresh install. The first-launch welcome covers the whole screen during the compile, so the plate is not seen there. The compile finishes behind the welcome text.
• render/filament device suite: 60 tests. 58 passed and 0 failed. 2 declined (RenderGalleryTest and RenderedHarnessTest are opt-in and skip themselves without -e gallery / -e harness.rolls).

For the owner to judge: the startup compile is shown as two plates in a row ("dice" then "table"), each with its own bar starting from empty. Is that fine, or should it be one bar across both? Also whether the wording reads right.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate failed

Failed conditions
B Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE