feat(assets): cook standalone mobile textures to raw ASTC (PRD568)

[jonit-dev]

This draft implements the standalone-texture slice of PRD568: Android/iOS cooks convert the selected Basis result into raw ASTC 4x4 KTX2 with full mips, sRGB/UNORM headers and no supercompression. Web/desktop retain their Basis path. The starter contract requires a real ASTC output and validates every emitted KTX2. A separate receipt-guard regression now rejects new undeclared paths even when copied timestamps are old; child-exit diagnostics preserve existing test budgets.

Validation: full assets suite on original Debian/Node20.19.6 passed at source 90383cb3d (566 passed, 6 skipped, exit 0, 255.29 s). Fresh assets + scaffolder builds passed at ac870d5db; the compiled starter mobile caller passed (1 passed, 65 skipped, exit 0, 3.07 s) within one 240 s supervisor. The earlier worker-exit cause remains unproven.

Normal pre-push pnpm ci:fast passed agents, lint, docs and drift for ac870d5db; it proves drift only, with no native or full CI qualification.

OPEN: final ASTC byte caps (maxBytes currently measures Basis), shipped ASTC quality (floor currently measures the Basis decode), mobile decoder overrides/codec-none contracts, embedded/shared model textures, lightmaps, admission, native and visual proof. This draft is partial and remains at 0%; it makes no release or native-runtime claim.

TL;DR — The cook writes Basis KTX2, UASTC or ETC1S, chosen per texture by the quality ladder (packages/assets/src/passes/model-textures.ts:426-430). At load time three transcodes each file to whatever the GPU takes (TRANSCODE_TARGETS, texture.ts:68-71: UASTC to astc4x4 or bc7, ETC1S to bc1 or etc2). That transcoder is WASM.

0% by the PRD's own boxes: 0/2 phases (0/4 boxes), 0/2 acceptance criteria. PRD: docs/PRDs/unreal-source-borrowing/PRD-568-mobile-builds-ship-gpu-ready-astc.md.

Phases

Phase 1: Cook and admit raw ASTC — 0/2

• A mobile-target cook writes ASTC 4×4 KTX2 with the right vkFormat, full mips and no supercompression; web and desktop output is byte-identical to before. proof: red-green pnpm exec vitest run packages/assets/__tests__
• The packaging gate admits raw-block KTX2 on QuickJS and still refuses Basis KTX2 there. proof: red-green pnpm exec vitest run packages/create-threenative/__tests__/native-ktx2.spec.ts

Phase 2: Load and check on the host — 0/2

• A package with ASTC on an adapter without texture-compression-astc fails at startup with a named error. proof: red-green pnpm exec vitest run packages/core/__tests__/assets.spec.ts
• The texture bytes and APK size of the ASTC build against the PNG build are recorded here. proof: the AC-1 runner's artifact listing

Acceptance criteria

• AC-1 [local]: An Android QuickJS build of the VQ-01 fixture ships ASTC KTX2 instead of PNG, packages without TN_NATIVE_KTX2_UNSUPPORTED, and renders both authored checker colours on the emulator. proof: sh scripts/vq01-android-proof.sh <artifact-dir> emulator-5554 with THREENATIVE_GRADLE_ARGS=-PthreenativeJsEngine=quickjs — Evidence: pending.
• AC-2 [local]: The same fixture on Android V8 loads every texture without a transcoder call, and its first-frame load time is no worse than the Basis build in 3 interleaved launches. proof: the same runner with V8, comparing TN_STALL_SEGMENTS — Evidence: pending.

Still open

• Phase 1: Cook and admit raw ASTC: A mobile-target cook writes ASTC 4×4 KTX2 with the right vkFormat, full mips and no supercompression; web and desktop output is byte-identical to before. proof: red-green pnpm exec vitest run packages/assets/__tests__
• Phase 1: Cook and admit raw ASTC: The packaging gate admits raw-block KTX2 on QuickJS and still refuses Basis KTX2 there. proof: red-green pnpm exec vitest run packages/create-threenative/__tests__/native-ktx2.spec.ts
• Phase 2: Load and check on the host: A package with ASTC on an adapter without texture-compression-astc fails at startup with a named error. proof: red-green pnpm exec vitest run packages/core/__tests__/assets.spec.ts
• Phase 2: Load and check on the host: The texture bytes and APK size of the ASTC build against the PNG build are recorded here. proof: the AC-1 runner's artifact listing
• Acceptance Criteria: AC-1 [local]: An Android QuickJS build of the VQ-01 fixture ships ASTC KTX2 instead of PNG, packages without TN_NATIVE_KTX2_UNSUPPORTED, and renders both authored checker colours on the emulator. proof: sh scripts/vq01-android-proof.sh <artifact-dir> emulator-5554 with THREENATIVE_GRADLE_ARGS=-PthreenativeJsEngine=quickjs — Evidence: pending.
• Acceptance Criteria: AC-2 [local]: The same fixture on Android V8 loads every texture without a transcoder call, and its first-frame load time is no worse than the Basis build in 3 interleaved launches. proof: the same runner with V8, comparing TN_STALL_SEGMENTS — Evidence: pending.

_{Generated from the PRD's checkboxes. Regenerate on each push so the PR and the PRD never disagree.}