Add media usage index foundation and my plan for Media usage in EmDash

[khoinguyenpham04]

Hi everyone,

I'm Noah, the new software engineering intern at Cloudflare, and I'll be working with @ascorbic over the next 12 weeks on EmDash.

I’m planning the first Media Library PR and would like feedback before starting implementation.

Why this matters

EmDash already has a strong technical foundation: Astro-native content, Cloudflare-native deployment, plugins, media providers, and MCP/agent support.

The next step is making the core CMS workflows feel production-ready for real editors and publishers.

Media is one part of that, but it touches several bigger product areas:

• editor trust and reliability;
• structured content and blocks;
• reusable assets;
• safe content operations;
• future agent workflows.

If EmDash cannot answer where a media item is used, then humans and agents both have to guess before deleting, replacing, auditing, or optimizing files.

This proposal starts with that missing foundation.

My vision

Media Library in EmDash should be more than a place to upload files.

The goal is to make media work across the authoring flow:

• Find: locate the right asset quickly;
• Use: insert media from the picker, image fields, and rich text blocks;
• Check: see where media is used before changing or deleting it;
• Improve: replace, optimize, add metadata, set focal points, and review AI/provider suggestions safely.

This keeps the project under Media Library, but treats the important surfaces as:

• Media Library Page;
• Media Detail Panel;
• Media Picker;
• image/file fields;
• Portable Text image blocks;
• future gallery or ordered media flows.

Current state

EmDash already has a useful media base:

• media upload;
• grid/list views;
• local filename search and MIME filtering;
• cursor pagination and Load More;
• Media Picker;
• Media Detail Panel;
• alt text and caption editing;
• local/R2/S3-compatible storage;
• media metadata like dimensions, blurhash, dominant color, and content hash.

So the first task should not be basic upload, pagination, or search.

The biggest missing foundation is that EmDash does not know where a media item is used.

Problem

Today, editors cannot reliably answer:

• Where is this file used?
• Is it safe to delete?
• What content would be affected if I replace it?
• Does this file have no known references?
• Which media items need review or cleanup?

Without usage data, features like safe delete, replace-in-place, usage filters, image audits, embedded-image sitemaps, and safer agent workflows all become harder.

Roadmap preview

1. Build usage data first

Add a media usage index, usage count, and read-only Used in support.

This is the foundation for the rest of the work.

2. Improve the Media Detail Panel

Use usage data to make MediaDetailPanel answer practical editor questions:

• what is this file;
• where is it used;
• is it missing important metadata;
• is it safe to delete;
• what would replacement affect.

3. Add safety and replacement actions

Build on the usage index with:

• safe-delete warning;
• No known references filter;
• replace-in-place with usage context.

4. Improve media quality and editor flow

Follow with:

• focal point support;
• render-helper support for focal points;
• picker/editor improvements;
• ordered multi-select for galleries;
• per-use metadata design;
• reviewable AI alt/caption suggestions;
• provider/plugin paths for AI search or image generation.

The long-term goal is not just a better /media page. It is a safer media authoring workflow across the CMS.

First PR focus

The first PR would add the usage index foundation.

Proposed v0 scope

• Add _emdash_media_usage table.
• Extract local media references from top-level image fields, top-level file fields, repeater image sub-fields, and Portable Text image blocks.
• Keep usage rows updated on content create/update.
• Remove stale usage rows when references are removed.
• Store at least media_id, collection, content_id, locale, content_status, and source/field_path.
• Add handler/API support to list usage for one media item.
• Expose usage count for future No known references filtering.
• Add tests for extraction, updates, removed references, and Portable Text image blocks.
• Optionally add a small read-only Used in section in MediaDetailPanel if it stays small enough.

Those should build on the usage index after the foundation lands.

As this is the initial version of the scope I'll be working on, I'd love to hear more from the community for feedback and improvements.

Related discussions: #990, #1503, #897.