Make media handling a first-class editing workflow

[masonjames]

Current state

EmDash already treats media as a core capability, and the current admin has a strong foundation:

• A dedicated Media Library with grid/list views.
• Local and external provider tabs.
• Multiple-file upload support.
• Upload progress and success/error feedback.
• A slide-out media detail panel.
• Editable alt text and caption fields for image media.
• Core media API support for listing, uploading, deduplication by content hash, width/height metadata, blurhash/dominant color generation, and relative media URLs.

That is a good start. The next step is to make media handling excellent in the places editors touch every day: content fields, rich text, image pickers, galleries, and replacement workflows.

Problem

Media is one of the highest-frequency CMS workflows. Editors do not experience it as "storage." They experience it as:

1. Drop an image into the editor.
2. See it upload.
3. Add alt text and maybe a caption.
4. Insert it into the exact content location.
5. Reorder image groups.
6. Replace an outdated image without breaking the page.
7. Control the crop/focal point.
8. Use embeds and files without guessing which button or field to use.

Right now, EmDash has the core media foundation, but the workflow is too segmented. Uploading, selecting, editing metadata, inserting, replacing, and ordering media should feel like one coherent editing surface.

This proposal focuses on the specific UX behaviors that should become first-class in EmDash.

---

Proposed scope

1. Drag-and-drop upload everywhere media is selected

Add visible drag-and-drop upload zones to the main daily-use surfaces:

• Media Library.
• Media picker modal.
• Image field widgets.
• Rich text / Portable Text media insertion.
• Gallery picker or gallery block.

Expected behavior:

• Drag one or more files into the drop zone.
• Upload begins immediately.
• Progress is shown per file or as a batch.
• Failed files show actionable errors.
• Successfully uploaded files remain selected when the user is in a picker context.
• If the user uploads into an image field, the first uploaded image is selected automatically.
• If the user uploads into a gallery, uploaded files are appended in upload order.

This should build on the existing multiple-file upload logic in MediaLibrary, but expose it through obvious drop targets instead of relying mainly on the upload button/file input.

2. Replace asset in place

Add a replacement workflow for an existing media item.

Expected behavior:

• User opens a media item.
• User clicks Replace file.
• User uploads a new file.
• EmDash preserves the existing media item identity.
• Existing content references keep working.
• Existing alt text, caption, and focal point are preserved by default.
• File metadata updates: filename, MIME type, size, dimensions, content hash, blurhash, dominant color, storage key if needed.
• The UI confirms that the asset was replaced and shows the updated preview.

Recommended technical direction:

• Preserve the media item ID.
• Generate a new storage key for the replacement file.
• Update the media record to point to the new storage key.
• Keep old alt/caption/focal metadata unless the user edits it.
• Avoid reusing the same storage key by default, because CDN/browser cache invalidation gets ugly fast. Same ID plus new storage key is the safer compromise.

Open design question:

• Should replacement allow changing media category, for example image to PDF, or should v1 restrict replacement to the same broad type such as image-to-image, video-to-video, document-to-document?

Recommendation: restrict v1 to the same broad type, with a clear error message. That avoids broken rendering assumptions in templates and rich text blocks.

3. Alt text and caption workflow in the picker/editor, not only in the detail panel

The current MediaDetailPanel already supports alt text and caption editing for image media. That is good, but the workflow should also be available at the moment of insertion.

Expected behavior:

• When inserting an image with missing alt text, the picker shows "No alt text."
• The user can add/edit alt text directly inside the picker before inserting.
• The user can add/edit a caption before inserting.
• The user can mark an image as decorative where appropriate.
• The editor should not hard-block publishing by default, but should make missing alt text visible and easy to fix.
• List/grid items should display metadata status: Alt set, No alt text, Caption set, Decorative.

Recommended split:

• Global media alt text: belongs to the media item.
• Caption: can exist globally, but should allow per-use override in rich text or gallery contexts.
• Decorative flag: probably per-use, because the same image may be meaningful in one context and decorative in another.

4. Focal point support

Add focal point metadata for image media.

Expected behavior:

• User opens an image in the detail panel or picker.
• User clicks on the important area of the image.
• EmDash stores a normalized focal point, for example { x: 0.42, y: 0.31 }.
• Components that render cropped images can use that value for object-position.
• The UI previews the crop behavior where possible.

Recommended technical direction:

• Store focal point as normalized coordinates.
• Add focal point editing to MediaDetailPanel.
• Surface focal point in MediaPickerModal for quick adjustment before insertion.
• Update image rendering helpers/components to consume focal point when available.

Open design question:

• Should focal point be global to the media item, per content usage, or both?

Recommendation: v1 should store a global focal point on the media item. Per-use overrides can come later for advanced layouts.

5. Gallery ordering

Add a reusable ordered media selection pattern.

Expected behavior:

• User selects multiple media items.
• Selected items appear in a tray or ordered list.
• User can reorder by drag-and-drop.
• User can reorder with keyboard controls.
• User can remove individual items.
• The stored value preserves order explicitly.
• Gallery order should never depend on upload time, media ID, filename, or database return order.

Recommended technical direction:

• Create an ordered media picker primitive that can be reused by:
  • Gallery field type.
  • Rich text gallery block.
  • Plugin setting fields.
  • Future image carousel/lightbox plugins.
• Store gallery values as an ordered array of media references.
• Include optional per-item caption/alt override support later, but do not let that block v1.

6. Inline media edits

Allow small metadata edits without forcing users to leave their editing context.

Expected behavior:

• In a picker, users can edit alt/caption/focal point before inserting.
• In a content editor image field, users can edit alt/caption/focal point for the selected asset.
• In rich text, selecting an image block exposes quick actions:
  • Change image.
  • Replace underlying asset.
  • Edit alt text.
  • Edit caption.
  • Set focal point.
  • Remove image from content.

This does not need to replace the full Media Detail Panel. It should reuse the same underlying update API and keep the detail panel as the full management view.

7. Clear embed/media insertion

Add an explicit media insertion flow to the rich text editor.

Expected behavior:

• Editor has a clear Insert media control.
• Slash command or toolbar menu exposes:
  • Image.
  • Gallery.
  • Video.
  • File/document.
  • Embed URL.
• Inserting local media opens the media picker.
• Inserting an embed URL uses a clear embed workflow.
• Unsupported embed URLs produce a clear fallback, such as a linked card or plain link.

Recommended split:

• Core should handle local media insertion: image, file, video/audio where supported.
• External embed provider resolution should live in a first-party plugin or plugin-capable extension point.
• The UI can still expose "Embed URL" if the embed plugin is installed.

---

Priority ranking

Rank	Enhancement	User impact	Code lift	Recommended location	Why
1	Drag-and-drop upload in picker/editor fields	Very high	Medium	Core/admin	This is the most visible daily editing improvement and builds on existing upload logic.
2	Inline alt text/caption workflow	Very high	Low-medium	Core/admin	The detail panel already supports alt/caption, so the biggest work is exposing it in the right places.
3	Media library pagination/local search access	Very high	Medium	Core/admin	If users cannot access assets beyond the first page, every other media UX improvement suffers. Discussion #897 appears directly related.
4	Replace asset in place	Very high	Medium-high	Core/API/admin	Prevents broken pages and solves a real client/editor workflow. Needs careful storage/cache design.
5	Clear media insertion in rich text	High	Medium	Core/admin, plugin hooks	Editors need one obvious path for image/file/gallery/embed insertion.
6	Gallery ordering	High	Medium-high	Core primitive, optional gallery plugin	Ordering is essential, but the reusable picker primitive matters more than one gallery layout.
7	Focal point support	High	Medium	Core media metadata/admin/rendering	Important for polished sites, especially card grids and hero images.
8	Plugin settings media picker	Medium-high	Low-medium	Admin/plugins	Already requested in issue #174; unlocks SEO logos, organization images, author images, and plugin UX.
9	MCP/programmatic media upload	Medium for editors, high for automation	Low-medium	Core/MCP	Already requested in issue #620; useful for agentic content workflows but less urgent than human editing flow.

---

Core vs plugin recommendation

Should be core

These should be core because they affect the basic editing contract of the CMS:

• Drag-and-drop upload surfaces.
• Media picker modal improvements.
• Media detail panel improvements.
• Alt/caption editing.
• Replace-in-place API and UI.
• Focal point metadata.
• Ordered media selection primitive.
• Local media insertion in rich text.
• Media pagination/load-more/local search.

Should be plugin or extension point

These should not bloat core v1:

• Advanced external embeds, provider-specific cards, oEmbed-style resolution.
• CDN image transformations.
• AI-generated alt text.
• DAM integrations.
• Stock image search.
• Advanced image editing/cropping.
• Lightbox/gallery presentation styles.
• Provider-specific bulk operations.

Core should make these possible. Plugins should own the specialized behavior.

---

Implementation sketch

Admin components likely involved

• MediaLibrary
• MediaDetailPanel
• MediaPickerModal
• content field components for image/media fields
• rich text / Portable Text editor components
• plugin settings field rendering

The current admin component tree already includes MediaLibrary, MediaDetailPanel, and MediaPickerModal, so this should be an enhancement to existing primitives rather than a new isolated media UI.

API/core areas likely involved

• Existing media list/upload endpoint.
• Media update endpoint.
• New media replace endpoint.
• Media schema/model updates for focal point.
• Media value normalization and rendering helpers.
• Storage adapter behavior for replacement.
• Tests for URL stability, replacement, metadata persistence, pagination, and ordered gallery values.

The current media API already accepts cursor, limit, and mimeType for listing and returns nextCursor, which suggests pagination may be partly available at the API layer and mainly needs to be exposed properly in the admin UI.

Proposed first PR sequence

1. Expose reliable media pagination/load-more in admin

   • Aligns with discussion Media Library doesn't expose pagination — users with >50 files can't access them #897.
   • Makes larger libraries usable before adding more media features.

2. Add drag-and-drop upload to Media Library and Media Picker

   • Reuse existing multiple upload logic.
   • Add drop zone states, progress, and error messages.

3. Inline alt/caption editing in Media Picker

   • Reuse existing updateMedia behavior.
   • Add missing-alt indicators and quick edit affordances.

4. Replace-in-place API and detail panel action

   • Preserve media item ID.
   • Generate new storage key.
   • Retain alt/caption/focal metadata.
   • Update width/height/hash/blurhash/dominant color.

5. Focal point support

   • Add metadata storage.
   • Add UI selector.
   • Use in image rendering helpers/components.

6. Ordered multi-select picker

   • Add reusable ordered selected-items tray.
   • Use it for gallery field/block support.

7. Rich text media insertion

   • Add explicit Insert Media / Insert Gallery / Embed URL actions.
   • Keep embed provider resolution plugin-capable.

---

Acceptance criteria

• Users can drag files into the Media Library and Media Picker.
• Users can drag an image into an image field and have it upload/select without leaving the editor.
• Users can upload multiple files and see progress/error feedback.
• Users can edit alt text and captions from the picker before insertion.
• Missing alt text is visible in grid/list/picker views.
• Users can replace an existing media item without breaking existing content references.
• Replacement keeps existing alt/caption/focal metadata unless explicitly changed.
• Image focal point can be set visually and is stored as normalized coordinates.
• Rendered cropped images can use focal point data.
• Galleries preserve explicit user-defined order.
• Gallery ordering works with drag-and-drop and keyboard controls.
• Rich text has an obvious insertion path for image, gallery, file/video, and embed URL.
• Plugin authors can use the same picker primitive for plugin settings.
• Larger media libraries remain accessible through pagination/load-more and search/filter behavior.
• Tests cover upload, replace, metadata editing, focal point persistence, gallery ordering, and pagination.

---

Non-goals for v1

• Full digital asset management.
• Image cropping/editing tools.
• AI alt text generation.
• Stock image search.
• Full oEmbed clone.
• Provider-specific advanced media search.
• CDN transformation rules.
• Bulk media replacement.
• Per-breakpoint focal points.

Those are valuable, but they should not block the daily editing improvements.

---

Open questions

1. Should replace-in-place allow replacing an image with a non-image?
2. Should focal point be global, per usage, or both?
3. Should captions be global media metadata, per usage, or both?
4. Should "decorative image" be stored per usage rather than globally?
5. Should gallery support be a core field/block, or should core only provide the ordered media picker primitive?
6. Should embed URL insertion live behind an installed embeds plugin, or should core provide a basic fallback card?
7. Should local media search be added at the same time as pagination, or should v1 only expose load-more?

---

Recommendation

Start with the highest-frequency editor pain:

1. Media pagination/load-more.
2. Drag-and-drop upload in picker/editor contexts.
3. Inline alt/caption editing.
4. Replace-in-place.
5. Focal point.
6. Ordered gallery selection.
7. Rich text insertion actions.
8. Plugin settings media picker.
9. MCP upload.

This keeps the first PRs practical while still moving toward a much stronger media system.

[MA2153]

Those are great ideas. Should we tackle each one in a separate discussion? It might make it easier to keep track of things.

[masonjames]

Thanks! I agree these should become separate discussions as we move toward implementation. A few already have dedicated threads, like pagination, but my intent here was to create a central hub for the broader media-management direction in EmDash.

If there are specific items you think would benefit from their own breakout discussion, let me know and I’ll open those separately.

[MA2153]

Yep I figured this would serve as a general tracking thread.

I think "Replace asset in place" in particular needs further discussion because I remember that EmDash doesn't track media references. We also have to decide what happens to published content items. Do we re-publish them? Just silently change it? etc.

I haven't looked deeply into the rest of them, but I like the focal point suggestion, that would solve a problem I currently have when displaying thumbnails.

[rob-j-oliver]

+1 focal point be global and per usage (or just per usage).