Blacksite/.cursor/plans/fbx_external_texture_dependencies_2026-07-13.plan.md

FBX External Texture Dependencies

Issue: Gitea #58 (BS-JD-210)

Goal

Make FBX external texture discovery deterministic from import through runtime loading. Missing or unsafe references must be reported before the Asset Browser queues Bevy loads, while an explicit Authoring Override remains a supported untextured workflow.

Scope

1. Add one path-safe FBX texture-reference resolver shared by the local bevy_ufbx loader and the editor asset pipeline. Normalize separators, deduplicate references, retain relative textures/ and .fbm/ layouts, and reject absolute or parent-traversing references.
2. Decode external images through the FBX LoadContext, reuse one handle per normalized path, and consolidate unavailable dependency logging so duplicate ufbx texture records cannot create repeated asset-server failures.
3. Generate static-mesh dependencies from parsed FBX texture references. Treat them as required for Source Materials and as declared-but-optional for Authoring Override during read-only project validation.
4. Replace the FBX-only file copy with a staged bundle transaction that preflights every referenced file, preserves relative sidecar layout, backs up overwritten destinations, and rolls back a partial commit.
5. Preflight source-material thumbnails, retain neutral direct FBX mesh/model previews, and expose a stable failure reason plus missing dependency status in the Asset Browser.
6. Deliberately normalize the committed painted-chair fixture to Authoring Override rather than add large absent 2K textures.

Verification

• Unit tests for sibling textures/, .fbm/, duplicate references, missing files, path traversal, destination symlink containment, transactional preservation, consolidated project findings, and read-only validation.
• cargo fmt, focused crate tests, workspace Clippy, workspace tests, validate-levels, and validate-samples. Packaged tests remain deferred by project-owner direction.
• Native editor QA for the painted chair and an intentionally broken Source Materials variant, including log inspection and screenshots published as ordinary Gitea attachments.

Documentation

• Record the cross-crate dependency/override contract in ADR 0044.
• Update editor architecture, Asset Browser workflow, root controls/checklist, documentation maps, and an issue-specific evaluation record.