feat(media): warn before permanently deleting a file the site still uses

[mostafasadeghidev]

Stacked on #505, which records what depends on a media asset and builds the sentence. This is the part that puts it in front of the operator.

Important

Depends on #505 and #497. GitHub cannot base a cross-fork PR on another fork branch, so this targets main and the diff carries both of those PRs until they land. The new work is the commits after #505's — the warning wiring, the computed page usage, and reading every site branch — everything before them belongs to #505 (the recording and the wording) and #497 (the confirmation this decorates). Merge those two first and this diff collapses to that work.

What it does

media_usage_refs and buildUsageWarning shipped in #505 without anything that shows them, so a permanent delete still said nothing about an avatar in the selection:

Delete "avatar.png" permanently?

This removes the file and every generated size from disk. Any page
still referencing it will render a broken image.

⚠ This file is still in use:
   profile picture — Ada Lovelace

[Cancel]  [Delete permanently]

Both surfaces that offer a permanent delete are wired — the viewer window and the grid's context menu — and each owns its own dialog, so each was wired separately. There is a test per surface. The bulk window is a third such surface; its permanent delete arrives with #500, so its wiring belongs in whichever of the two lands second.

Page content is computed, not recorded

Avatars could be recorded (#505) because a profile picture has one writer and an explicit set/unset. Page content has neither: it is written continuously by the collab relay, and taking an image off a page emits no event at all. A table fed by that fills with references to nodes that no longer exist, and the warning starts naming pages that are fine — and a warning that is sometimes wrong is worse than none, because it gets ignored.

So collectContentUsageRefs computes the answer from the draft site document when it is asked. It cannot drift, because there is nothing to keep in sync. The test that matters pins exactly that: remove the image, ask again, the reference is gone.

The walk already existed. mediaPrefetch has resolved image/media props on every publish for a long time — including background images and the definition tree of every Visual Component a page references. It splits into a page-scoped half this reuses; publish behaviour is unchanged. The module schema is already the registry of which props hold a media reference, so there is no second list to keep honest.

The cost lands on permanent delete and nowhere else — never a page load, never a trash. Walking every page tree is O(site) on an action that is about to be irreversible. If a site ever outgrows that, the fix is to cache it with the walk still the source of truth, so the cache can be checked against it.

It reads the draft, not the published artefacts. An image on an unpublished page is still in use — a check that only knew about live pages would let a delete quietly break the next publish.

And it reads every site branch. Media is shared across branches while pages are not, so a purge removes a file from all of them at once. An image used only on a branch breaks that branch's preview immediately and the live site when the branch merges — but reading main alone would have called it unused. Main is reported plainly; a branch is named only where its use is not already on main:

⚠ This file is still in use:
   on the page — Home
   on the page — About us (branch "Redesign")

Every fork starts as a copy of main, so naming a shared page once per branch would repeat the same line for every branch that exists. Page ids are logical on every branch, which is what lets the same page match across them. Main is read first by name rather than by relying on listBranches to order it first. The cost becomes O(branches × site), still only on a permanent delete.

One detail worth flagging in review: contentUsage.ts imports @modules/base itself. Without the registry populated the walk matches nothing and reports no usage — a warning that is silently always empty, which is the one failure mode worse than not having it.

Three decisions worth stating

The lookup is awaited before the dialog opens. A warning that arrives while the operator is already reading the dialog is a warning they will not see. It costs one round trip on a click that is about to be irreversible.

resolveUsageWarning is a plain async function, not a hook holding state. The state version cannot work here: every caller opens its dialog in the same closure that requested the lookup, where a setState is not yet visible — the warning would always have been one delete behind. Callers that keep a dialog open across renders store the returned value themselves.

It is also where "never rejects" lives, rather than in each lookupUsage. Every dialog opens from a floating void (async () => …)(), which drops a rejection silently — a failed lookup would have produced a delete button that does nothing at all, which is worse than one that deletes without the extra warning. One door, one guarantee, and the two hooks lose their duplicated try/catch.

The shared dialog stays generic

ConfirmDeleteRequest gains details?: ReactNode — caller-owned content below the description. Media passes the warning; nothing else passes anything. The alternative was teaching a dialog that also confirms page and layer deletes what a media asset is.

The warning now counts per asset but names per place: one file on three pages is one file lost — "3 of 11" would overstate the damage — but it is three pages to go and fix, and naming one sends the operator to repair a third of the breakage.

bun test src/__tests__/media/                    52 pass
bun test src/__tests__/server/mediaContentUsage  11 pass   (3 of them branches)
tsc -b, bun run build, eslint                    clean

docs/features/media.md gains the section this area was missing: what the lookup reads, why settings are recorded and content computed, and the branch rule.

Co-Authored-By: Claude Opus 5 noreply@anthropic.com