Add media usage index write-side foundation

[khoinguyenpham04]

What does this PR do?

Adds the write-side foundation for the Media Usage index. This includes the database tables/status metadata, content media reference extraction, content source snapshots for columns and draft_overlay, repository APIs, runtime refresh wiring for normal content lifecycle writes, stale marking for known bypass paths, and generation-guarded source replacement/deletion so refresh races preserve current usage and mark coverage stale instead of failing content writes.

This PR intentionally stops before repair/rebuild, the usage read API, admin Used In UI, safe delete, replace-in-place behavior, or media delete behavior changes.

Related discussion: #1503

Type of change

• Bug fix
• Feature (requires maintainer-approved Discussion)
• Refactor (no behavior change)
• Translation
• Documentation
• Performance improvement
• Tests
• Chore (dependencies, CI, tooling)

Checklist

• I have read CONTRIBUTING.md
• pnpm typecheck passes
• pnpm lint passes
• pnpm test passes (or targeted tests for my change)
• pnpm format has been run
• I have added/updated tests for my changes (if applicable)
• User-visible strings in the admin UI are wrapped for translation (if applicable). Do not include messages.po changes except in translation PRs — a workflow extracts catalogs on merge to main. N/A: no admin UI strings in this PR.
• I have added a changeset (if this PR changes a published package)
• New features link to an approved Discussion: Media usage index — power image sitemaps, "Used in", and safe deletes #1503

AI-generated code disclosure

• This PR includes AI-generated code — model/tool: OpenCode with GPT-5.5 (openai/gpt-5.5)

Screenshots / test output

Non-visual backend/indexing change.

Verified:

• pnpm lint
• pnpm typecheck
• pnpm format
• pnpm --filter emdash exec vitest run tests/integration/database/media-usage-status-migration.test.ts tests/integration/database/media-usage-content-fields.test.ts tests/integration/database/media-usage-repository.test.ts tests/integration/database/media-usage-migration.test.ts tests/integration/database/media-usage-content-snapshots.test.ts tests/integration/database/media-usage-content-refresh.test.ts tests/integration/database/media-usage-runtime-refresh.test.ts tests/integration/database/media-usage-stale-bypass.test.ts tests/unit/media/usage-extractor.test.ts tests/unit/media/usage-source-key.test.ts (10 files, 98 tests)
• git diff --check

---

Try this PR

Open a fresh playground →

A full working EmDash site, deployed from this branch. Each visit gets its own session-scoped sandbox: no login needed and no shared state. Try the admin, edit content, hit the public site.

_{Tracks feature/media-usage-index-core. Updated automatically when the playground redeploys.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 042c0e5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 16 packages

Name	Type
emdash	Patch
@emdash-cms/cloudflare	Patch
@emdash-cms/sandbox-workerd	Patch
@emdash-cms/fixture-perf-site	Patch
@emdash-cms/perf-demo-site	Patch
@emdash-cms/cache-demo-site	Patch
@emdash-cms/do-demo-site	Patch
@emdash-cms/do-solo-demo-site	Patch
@emdash-cms/admin	Patch
@emdash-cms/auth	Patch
@emdash-cms/blocks	Patch
@emdash-cms/gutenberg-to-portable-text	Patch
@emdash-cms/x402	Patch
create-emdash	Patch
@emdash-cms/auth-atproto	Patch
@emdash-cms/plugin-embeds	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	emdash-demo-cache	042c0e5	Jul 03 2026, 05:38 PM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	emdash-playground	042c0e5	Jul 03 2026, 05:38 PM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	docs	02c220d	Jul 03 2026, 03:11 PM

[pkg-pr-new]

Open in StackBlitz

@emdash-cms/admin

npm i https://pkg.pr.new/@emdash-cms/admin@1746

@emdash-cms/auth

npm i https://pkg.pr.new/@emdash-cms/auth@1746

@emdash-cms/auth-atproto

npm i https://pkg.pr.new/@emdash-cms/auth-atproto@1746

@emdash-cms/blocks

npm i https://pkg.pr.new/@emdash-cms/blocks@1746

@emdash-cms/cloudflare

npm i https://pkg.pr.new/@emdash-cms/cloudflare@1746

@emdash-cms/contentful-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/contentful-to-portable-text@1746

emdash

npm i https://pkg.pr.new/emdash@1746

create-emdash

npm i https://pkg.pr.new/create-emdash@1746

@emdash-cms/gutenberg-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/gutenberg-to-portable-text@1746

@emdash-cms/plugin-cli

npm i https://pkg.pr.new/@emdash-cms/plugin-cli@1746

@emdash-cms/plugin-types

npm i https://pkg.pr.new/@emdash-cms/plugin-types@1746

@emdash-cms/registry-client

npm i https://pkg.pr.new/@emdash-cms/registry-client@1746

@emdash-cms/registry-lexicons

npm i https://pkg.pr.new/@emdash-cms/registry-lexicons@1746

@emdash-cms/sandbox-workerd

npm i https://pkg.pr.new/@emdash-cms/sandbox-workerd@1746

@emdash-cms/x402

npm i https://pkg.pr.new/@emdash-cms/x402@1746

@emdash-cms/plugin-ai-moderation

npm i https://pkg.pr.new/@emdash-cms/plugin-ai-moderation@1746

@emdash-cms/plugin-atproto

npm i https://pkg.pr.new/@emdash-cms/plugin-atproto@1746

@emdash-cms/plugin-audit-log

npm i https://pkg.pr.new/@emdash-cms/plugin-audit-log@1746

@emdash-cms/plugin-color

npm i https://pkg.pr.new/@emdash-cms/plugin-color@1746

@emdash-cms/plugin-embeds

npm i https://pkg.pr.new/@emdash-cms/plugin-embeds@1746

@emdash-cms/plugin-field-kit

npm i https://pkg.pr.new/@emdash-cms/plugin-field-kit@1746

@emdash-cms/plugin-forms

npm i https://pkg.pr.new/@emdash-cms/plugin-forms@1746

@emdash-cms/plugin-webhook-notifier

npm i https://pkg.pr.new/@emdash-cms/plugin-webhook-notifier@1746

commit: 042c0e5

[ascorbic]

Great stuff. Just a couple of notes. However this is a very large PR. For future ones, can you keep them smaller in scope so they're easier to review.

[github-actions]

Overlapping PRs

This PR modifies files that are also changed by other open PRs:

• feat(admin): add Taxonomy Types management page #213 (5 shared files)
• feat(core): add group and sortOrder to collections for admin UI organization #292 (4 shared files)

This may cause merge conflicts or duplicated work. A maintainer will coordinate.

[masonjames]

Tested this on a real production site (masonjames.com — Ghost→EmDash migration, Node + SQLite, downstream fork with local media patches). Results:

• Merge + tests: merged cleanly, 4364/4364 core tests passing including the new media-usage suites.
• Migration on live data: 050_media_usage_index_status applied cleanly at boot on the production SQLite DB — all three tables present, ledger correct, no boot noise.
• Write-side, end-to-end: inserting a media-library image into a post and publishing produced exactly the expected _emdash_media_usage row; lifecycle writes create content:{collection}:{id}:columns source rows as designed. Alt/caption edits and unreferenced uploads correctly created no rows. All collections initialized as stale / CONTENT_USAGE_STALE — the intended "incomplete until rebuild" state. No route errors, no interference with our local media patches.
• Field observation for later phases: pre-existing content yields zero usage rows here — migrated bodies embed media as absolute URLs on a custom media domain, so there are no managed references to extract. Expected given this PR's scope, but imported sites will depend on repair/rebuild to populate the index — and it may be worth attributing absolute URLs that match a configured media/public URL, since WordPress and Ghost migrations commonly end up in this shape.

Happy to re-test when the read API / rebuild phases land.

[khoinguyenpham04]

@masonjames Thank you so much for testing this out! This is actually a really helpful validation :)

Also, I agree URL attribution for configured media/public domains is worth considering in the rebuild/import follow-up.

[masonjames]

@khoinguyenpham04 awesome! I'm really excited about the media components in emdash. Feel free to tag me on PRs whenever you'd like additional testing. Always happy to do so. 🙌

[ascorbic]

Thanks! And thanks @masonjames for the review