fix(site-import): resolve assets below exporter archive roots

[tommy230]

Summary

A WordPress export can store media below an extra archive directory while its HTML references the same files from the archive root. The import uploaded those unreferenced files during its media sweep, but resolveFileMapKey could not connect the HTML references to their bytes, so the published page kept broken image URLs.

resolveFileMapKey now tries a unique path-segment suffix after exact and punctuation-insensitive lookup. The suffix index is built lazily once per import. Exact keys still win, and suffix collisions remain unresolved and emit the existing unresolved-asset warning instead of choosing a file.

Coverage keeps the reported passthrough/wp-content case and adds exact-key precedence, ambiguous suffixes, and path-segment boundary behavior. The site-import pipeline documentation now describes exporter-specific archive directories rather than treating passthrough/ as an Instatic convention.

Verification

• bun run build (clean)
• bun test (6,831 pass, 0 fail)
• bun run lint (clean)
• Docker/deployment check, if relevant (not relevant: importer-only resolver change)

The reported root-relative asset test fails on current main before the resolver change and passes on this branch.

Checklist

• Tests cover behavior changes.
• Docs were updated when behavior, config, deployment, or public surfaces changed.
• No compatibility shim was added for old pre-release behavior.
• No secrets, local databases, uploads, or generated artifacts are included.

[DavidBabinec]

Thanks for tracking this down; a WordPress export that stores files under passthrough/ while the HTML references them root-relative is a real gap, and the two tests describe it well.

Two things need changing before this can land:

1. The branch predates #349, which replaced the single exact lookup with resolveFileMapKey (punctuation-insensitive matching plus the unresolved-asset warning). The PR now conflicts with main, and the fallback belongs inside that resolver chain rather than in front of it.

2. passthrough/ is not an Instatic convention (nothing in the repo produces or documents it), so a hardcoded prefix bakes one exporter's private layout into core. A general fallback covers it without the magic string: after the exact and normalised misses, match the resolved path as a unique suffix of a FileMap key (so wp-content/uploads/x.png finds passthrough/wp-content/uploads/x.png, and any other storage prefix, while an ambiguous suffix stays unresolved and warns, matching the uniqueness rule #349 already applies). The "exact key wins" test still holds under that shape.

If you rebase onto main and move the fallback into resolveFileMapKey as a suffix match, this is an easy merge. Happy to review again quickly.

[tommy230]

Rebased onto current main and moved the fallback into resolveFileMapKey after exact and punctuation-insensitive lookup. The hardcoded passthrough/ retry is gone; the resolver now uses a cached unique path-segment suffix index, while ambiguous suffixes stay unresolved and emit the existing warning.

I kept the reported WordPress regression and exact-key precedence coverage, and added tests for suffix ambiguity and segment boundaries. Verification is clean: bun run build, bun run lint, and bun test with 6,831 pass and 0 fail.

@DavidBabinec ready for another look when you have a moment.