From aa02f6c541b17a1f155afbf42c279bf75a209ba8 Mon Sep 17 00:00:00 2001
From: Rahul Anand <41159815+rahulnsanand@users.noreply.github.com>
Date: Wed, 30 Sep 2026 16:51:13 +0530
Subject: [PATCH 1/2] feat: sized media grammar, unified MediaFrame,
 byte-stable embeds

---
 packages/headless/src/core/markdown.test.ts   |   6 +-
 .../headless/src/core/source-capability.ts    |   3 +
 .../embeds/EmbedResolverContext.tsx           |  66 ++-
 .../src/extensions/embeds/FileEmbedNode.tsx   | 446 +++++++++++++-----
 .../headless/src/extensions/embeds/index.ts   |   6 +
 packages/headless/src/extensions/index.ts     |  22 +
 .../extensions/media/IframeEmbedExtension.tsx |  35 +-
 .../src/extensions/media/ImageExtension.tsx   |  33 +-
 .../src/extensions/media/MediaFrame.test.tsx  | 159 +++++++
 .../src/extensions/media/MediaFrame.tsx       | 285 +++++++++++
 .../media/YouTubeEmbedExtension.tsx           |  35 +-
 .../headless/src/extensions/media/index.ts    |   2 +
 .../src/extensions/media/mediaGrammar.test.ts | 194 ++++++++
 .../src/extensions/media/mediaGrammar.ts      | 299 ++++++++++++
 packages/luthor/src/core/styles.css           | 159 ++++++-
 .../papyra-collab/papyraCollab.test.ts        |  28 ++
 packages/luthor/src/presets/papyra/adapter.ts |  23 +-
 packages/luthor/src/presets/papyra/embeds.ts  |  17 +-
 .../src/presets/papyra/mediaGolden.test.tsx   | 302 ++++++++++++
 packages/luthor/src/presets/papyra/papyra.css |  16 +-
 20 files changed, 1974 insertions(+), 162 deletions(-)
 create mode 100644 packages/headless/src/extensions/media/MediaFrame.test.tsx
 create mode 100644 packages/headless/src/extensions/media/MediaFrame.tsx
 create mode 100644 packages/headless/src/extensions/media/mediaGrammar.test.ts
 create mode 100644 packages/headless/src/extensions/media/mediaGrammar.ts
 create mode 100644 packages/luthor/src/presets/papyra/mediaGolden.test.tsx

diff --git a/packages/headless/src/core/markdown.test.ts b/packages/headless/src/core/markdown.test.ts
index 5afb24ad..2114098f 100644
--- a/packages/headless/src/core/markdown.test.ts
+++ b/packages/headless/src/core/markdown.test.ts
@@ -1562,10 +1562,12 @@ describe("markdown bridge", () => {
     };
 
     const markdown = jsonToMarkdown(input);
-    expect(markdown).toContain("![Example](https://example.com/photo.jpg");
+    // Size is native markdown (Obsidian's alt-size); the rest rides in metadata.
+    expect(markdown).toContain("![Example|720x405](https://example.com/photo.jpg");
     expect(markdown).toContain("luthor:meta v1");
+    expect(markdown).not.toContain('"width":720');
 
-    const editedMarkdown = markdown.replace("![Example]", "![Updated]");
+    const editedMarkdown = markdown.replace("![Example|720x405]", "![Updated|720x405]");
     const roundTrip = markdownToJSON(editedMarkdown) as JsonDocument;
     const imageNode = findTopLevelNode(roundTrip, "image") as {
       src?: string;
diff --git a/packages/headless/src/core/source-capability.ts b/packages/headless/src/core/source-capability.ts
index a81fec35..2c7d73de 100644
--- a/packages/headless/src/core/source-capability.ts
+++ b/packages/headless/src/core/source-capability.ts
@@ -79,6 +79,9 @@ export const MARKDOWN_NATIVE_KEY_MAP: Readonly<Record<string, ReadonlySet<string
     "linkHref",
     "linkTitle",
     "alignment",
+    // Obsidian's `![alt|W](src)` / `|WxH` carries the size in markdown itself.
+    "width",
+    "height",
   ]),
   "iframe-embed": new Set(["type", "version", "src", "caption"]),
   "youtube-embed": new Set(["type", "version", "src", "caption"]),
diff --git a/packages/headless/src/extensions/embeds/EmbedResolverContext.tsx b/packages/headless/src/extensions/embeds/EmbedResolverContext.tsx
index 9cab125e..4f6cf6cd 100644
--- a/packages/headless/src/extensions/embeds/EmbedResolverContext.tsx
+++ b/packages/headless/src/extensions/embeds/EmbedResolverContext.tsx
@@ -42,6 +42,56 @@ export interface SavedCardMetadata {
   siteName?: string;
 }
 
+/**
+ * What a host knows about an attachment before it loads — enough to reserve its
+ * box (no layout shift), pick a thumbnail, and label a file card. Every field is
+ * optional; a host that knows nothing returns `undefined` and the embed measures
+ * itself on load instead.
+ */
+export interface MediaMeta {
+  /** `image`, `gif`, `video`, `audio`, `document` or `file`. */
+  kind?: string;
+  /** The type the file is served as (`image/png`, `application/pdf`). */
+  mime?: string;
+  /** Size in bytes. */
+  size?: number;
+  /** A content version; changes whenever the bytes do. */
+  version?: string;
+  /** Intrinsic width in CSS pixels, as displayed (EXIF rotation applied). */
+  width?: number | null;
+  /** Intrinsic height in CSS pixels, as displayed. */
+  height?: number | null;
+  /** Running time of audio/video, in milliseconds. */
+  durationMs?: number | null;
+  /** An animated image (GIF/WebP): never swap it for a still thumbnail. */
+  animated?: boolean;
+  /** A poster frame exists for this video (`variant: "poster"`). */
+  poster?: boolean;
+  /** Smaller renditions exist (`variant: "thumb"`). */
+  thumb?: boolean;
+}
+
+/** Which rendition of an attachment a URL should point at. */
+export interface MediaUrlOptions {
+  /**
+   * `original` (default) — the file itself. `thumb` — a smaller still, at least
+   * `width` wide when possible. `poster` — a video's poster frame.
+   */
+  variant?: "original" | "thumb" | "poster";
+  /** Desired width in CSS pixels for `thumb` / `poster`. */
+  width?: number;
+}
+
+/** What a host's file-card expansion renders from (see `renderFileExpansion`). */
+export interface FileExpansionContext {
+  target: string;
+  /** Text after `#` in the embed (`page=3`), or empty. */
+  fragment: string;
+  url: string;
+  kind: string;
+  meta: MediaMeta | null | undefined;
+}
+
 /**
  * Callbacks an embed node uses to reach host services. Every member is optional
  * so the nodes degrade gracefully when a host wires only part of the surface (or
@@ -54,7 +104,21 @@ export interface EmbedResolvers {
    * without a loading flash. When omitted, the file embed renders a reference
    * chip instead of loading media.
    */
-  resolveMediaUrl?: (target: string) => string;
+  resolveMediaUrl?: (target: string, options?: MediaUrlOptions) => string;
+  /**
+   * Synchronous, cached metadata for a media target — `undefined` while unknown.
+   * Must return the *same object* for the same target until it changes (it is
+   * read through `useSyncExternalStore`). Pair with {@link subscribeMediaMeta}
+   * to have embeds re-render when a lookup lands.
+   */
+  getMediaMeta?: (target: string) => MediaMeta | null | undefined;
+  /** Subscribe to metadata arriving/changing. Returns an unsubscribe function. */
+  subscribeMediaMeta?: (listener: () => void) => () => void;
+  /**
+   * Extra content under a non-image file card — e.g. an inline PDF viewer the
+   * host renders on demand. Return `null` for files it has nothing to add to.
+   */
+  renderFileExpansion?: (context: FileExpansionContext) => ReactNode;
   /**
    * Navigate to a link target (the `Target` inside `[[Target]]`). Invoked when a
    * reader activates a wikilink. When omitted, the wikilink renders as inert
diff --git a/packages/headless/src/extensions/embeds/FileEmbedNode.tsx b/packages/headless/src/extensions/embeds/FileEmbedNode.tsx
index 0f921fd3..974c384f 100644
--- a/packages/headless/src/extensions/embeds/FileEmbedNode.tsx
+++ b/packages/headless/src/extensions/embeds/FileEmbedNode.tsx
@@ -15,132 +15,183 @@ import {
   type SerializedLexicalNode,
   type Spread,
 } from "lexical";
-import type { ElementTransformer } from "@lexical/markdown";
+import type { ElementTransformer, TextMatchTransformer } from "@lexical/markdown";
 import type { ReactNode } from "react";
 import { ExtensionCategory } from "@lyfie/luthor-headless/extensions/types";
 import { BaseExtension } from "@lyfie/luthor-headless/extensions/base";
-import { useEmbedResolvers } from "./EmbedResolverContext";
+import { MediaFrame } from "../media/MediaFrame";
+import {
+  formatEmbedTarget,
+  formatMediaDirectives,
+  isFileTarget,
+  parseEmbedTarget,
+  parseMediaDirectives,
+  type MediaAlignment,
+} from "../media/mediaGrammar";
 
 /**
- * Serialized shape of a {@link FileEmbedNode}. Only the verbatim `target` (the
- * `file.ext` reference) is persisted; the resolved URL and the chosen media
- * element are derived at render time, so the stored data mirrors the markdown.
+ * Serialized shape of a {@link FileEmbedNode} (version 2).
+ *
+ * Version 1 stored only `target` — the whole text inside `![[…]]`, pipes and
+ * all. {@link FileEmbedNode.importJSON} still reads it (live collaboration rooms
+ * and saved editor states carry v1 nodes), parsing that text with the media
+ * grammar.
  */
 export type SerializedFileEmbedNode = Spread<
   {
+    /** The file reference, without fragment or pipe segments. */
     target: string;
+    fragment?: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    align?: MediaAlignment;
+    caption?: string;
+    /** Pipe segments the grammar doesn't own, verbatim. */
+    extra?: string[];
+    /** Trailing `<!-- … -->` directives the grammar doesn't own, verbatim. */
+    directives?: string[];
+    escapedPipes?: boolean;
+    inline?: boolean;
+    /** The exact markdown this embed was parsed from (byte-stable export). */
+    source?: string;
   },
   SerializedLexicalNode
 >;
 
-const IMAGE_EXTENSION = /\.(?:png|jpe?g|gif|webp|svg|avif|bmp|ico)$/i;
-const AUDIO_EXTENSION = /\.(?:mp3|wav|ogg|oga|m4a|flac|aac)$/i;
-const VIDEO_EXTENSION = /\.(?:mp4|webm|mov|m4v|ogv)$/i;
-
-type EmbedKind = "image" | "audio" | "video" | "file";
+/** The editable fields of an embed, as the markdown grammar sees them. */
+export interface FileEmbedFields {
+  target: string;
+  fragment?: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+  align?: MediaAlignment;
+  caption?: string;
+  extra?: string[];
+  directives?: string[];
+  escapedPipes?: boolean;
+  inline?: boolean;
+}
 
-function classifyEmbed(target: string): EmbedKind {
-  if (IMAGE_EXTENSION.test(target)) {
-    return "image";
-  }
-  if (AUDIO_EXTENSION.test(target)) {
-    return "audio";
-  }
-  if (VIDEO_EXTENSION.test(target)) {
-    return "video";
-  }
-  return "file";
+function formatFields(fields: FileEmbedFields): string {
+  const inner = formatEmbedTarget({
+    target: fields.target,
+    fragment: fields.fragment ?? "",
+    alt: fields.alt,
+    width: fields.width,
+    height: fields.height,
+    extra: fields.extra ?? [],
+    escapedPipes: fields.escapedPipes ?? false,
+  });
+  // Directives are a line-level syntax: an inline embed has none of its own.
+  const directives = fields.inline
+    ? ""
+    : formatMediaDirectives({
+        align: fields.align,
+        caption: fields.caption,
+        unknown: fields.directives ?? [],
+      });
+  return `![[${inner}]]${directives}`;
 }
 
 /**
- * React view for a file embed. Resolves the target to a URL through the host
- * {@link EmbedResolvers} and renders the matching media element; when no URL can
- * be resolved (no host wired, or a non-media file) it renders a reference chip
- * showing the raw target, so the embed is always visible and the markdown still
- * round-trips.
+ * Parse one embed's markdown (`![[inner]]` plus, for a block, any trailing
+ * directives). Null when it isn't one.
  */
-function FileEmbedComponent({ target }: { target: string }): ReactNode {
-  const { resolveMediaUrl } = useEmbedResolvers();
-  const url =
-    typeof resolveMediaUrl === "function" ? resolveMediaUrl(target) : "";
-  const kind = classifyEmbed(target);
-
-  if (url && kind === "image") {
-    return (
-      <img className="luthor-file-embed luthor-file-embed--image" src={url} alt={target} />
-    );
-  }
-
-  if (url && kind === "audio") {
-    return (
-      <audio
-        className="luthor-file-embed luthor-file-embed--audio"
-        controls
-        src={url}
-        aria-label={target}
-      />
-    );
+export function parseFileEmbedMarkdown(
+  markdown: string,
+  inline = false,
+): FileEmbedFields | null {
+  const match = /^!\[\[([^\]\r\n]+)\]\]((?:\s*<!--[\s\S]*?-->)*)\s*$/.exec(markdown.trim());
+  if (!match) {
+    return null;
   }
-
-  if (url && kind === "video") {
-    return (
-      <video
-        className="luthor-file-embed luthor-file-embed--video"
-        controls
-        src={url}
-        aria-label={target}
-      />
-    );
+  const inner = parseEmbedTarget(match[1] ?? "");
+  if (!inner.target) {
+    return null;
   }
-
-  const chip = (
-    <span
-      className="luthor-file-embed luthor-file-embed--chip"
-      data-luthor-file-embed-target={target}
-      role="note"
-      aria-label={`Embedded file: ${target}`}
-    >
-      {target}
-    </span>
-  );
-
-  if (url) {
-    return (
-      <a
-        className="luthor-file-embed luthor-file-embed--link"
-        href={url}
-        target="_blank"
-        rel="noopener noreferrer"
-        data-luthor-file-embed-target={target}
-      >
-        {target}
-      </a>
-    );
+  const directives = parseMediaDirectives(match[2] ?? "");
+  if (!directives) {
+    return null;
   }
-
-  return chip;
+  return {
+    target: inner.target,
+    fragment: inner.fragment,
+    alt: inner.alt,
+    width: inner.width,
+    height: inner.height,
+    extra: inner.extra,
+    escapedPipes: inner.escapedPipes,
+    align: directives.align,
+    caption: directives.caption,
+    directives: directives.unknown,
+    inline,
+  };
 }
 
 /**
- * A block-level `![[file.ext]]` media embed. The node stores the file reference
- * verbatim and resolves media through the {@link EmbedResolvers} context, so it
- * is host-agnostic. The companion {@link FILE_EMBED_MARKDOWN_TRANSFORMER} gives
- * it a lossless round-trip.
+ * An embedded attachment: `![[file.ext]]`, optionally sized (`|480`,
+ * `|640x360`), aliased (`|Alt text`), fragment-addressed (`#page=3`), aligned and
+ * captioned (trailing `<!-- align:… -->` / `<!-- caption:… -->`). Block by
+ * default; inline when written mid-paragraph.
+ *
+ * **Byte-stable.** A node parsed from markdown remembers that exact text and
+ * exports it for as long as its fields still describe it. Once anything changes
+ * (a resize, a new caption, a peer's edit arriving over collaboration), it
+ * exports the canonical form instead. Opening and saving a note never rewrites
+ * an embed nobody touched.
+ *
+ * Rendering goes through {@link MediaFrame}; the host's {@link EmbedResolvers}
+ * supply URLs and metadata, so the node itself is host-agnostic.
  */
 export class FileEmbedNode extends DecoratorNode<ReactNode> {
-  /** The file reference as written inside `![[target]]`. */
+  /** The file reference, without fragment or pipe segments (`photo.png`). */
   __target: string;
+  __fragment: string;
+  __alt: string | undefined;
+  __width: number | undefined;
+  __height: number | undefined;
+  __align: MediaAlignment | undefined;
+  __caption: string | undefined;
+  __extra: string[];
+  __directives: string[];
+  __escapedPipes: boolean;
+  __inline: boolean;
+  /** The markdown this node was parsed from, if any. */
+  __source: string | undefined;
 
   static getType(): string {
     return "fileEmbed";
   }
 
   static clone(node: FileEmbedNode): FileEmbedNode {
-    return new FileEmbedNode(node.__target, node.__key);
+    return new FileEmbedNode(node.getFields(), node.__source, node.__key);
   }
 
   static importJSON(serialized: SerializedFileEmbedNode): FileEmbedNode {
-    return $createFileEmbedNode(serialized.target);
+    // v1: `target` was the whole `![[…]]` inner text.
+    if (!serialized.version || serialized.version < 2) {
+      const source = `![[${serialized.target}]]`;
+      const fields = parseFileEmbedMarkdown(source) ?? { target: serialized.target };
+      return new FileEmbedNode(fields, source);
+    }
+    return new FileEmbedNode(
+      {
+        target: serialized.target,
+        fragment: serialized.fragment,
+        alt: serialized.alt,
+        width: serialized.width,
+        height: serialized.height,
+        align: serialized.align,
+        caption: serialized.caption,
+        extra: serialized.extra,
+        directives: serialized.directives,
+        escapedPipes: serialized.escapedPipes,
+        inline: serialized.inline,
+      },
+      serialized.source,
+    );
   }
 
   // File embeds are authored through markdown, not pasted HTML; the explicit
@@ -149,39 +200,68 @@ export class FileEmbedNode extends DecoratorNode<ReactNode> {
     return null;
   }
 
-  constructor(target: string, key?: NodeKey) {
+  // Collaboration (@lexical/yjs) constructs nodes with no arguments and then
+  // copies every `__` property across, so every argument is optional.
+  constructor(fields?: FileEmbedFields | string, source?: string, key?: NodeKey) {
     super(key);
-    this.__target = target;
+    const f: FileEmbedFields =
+      typeof fields === "string" ? { target: fields } : (fields ?? { target: "" });
+    this.__target = f.target;
+    this.__fragment = f.fragment ?? "";
+    this.__alt = f.alt || undefined;
+    this.__width = f.width && f.width > 0 ? f.width : undefined;
+    this.__height = f.height && f.height > 0 ? f.height : undefined;
+    this.__align = f.align;
+    this.__caption = f.caption || undefined;
+    this.__extra = f.extra ? [...f.extra] : [];
+    this.__directives = f.directives ? [...f.directives] : [];
+    this.__escapedPipes = f.escapedPipes ?? false;
+    this.__inline = f.inline ?? false;
+    this.__source = source && source.length > 0 ? source : undefined;
   }
 
   exportJSON(): SerializedFileEmbedNode {
     return {
       type: "fileEmbed",
-      version: 1,
+      version: 2,
       target: this.__target,
+      ...(this.__fragment ? { fragment: this.__fragment } : {}),
+      ...(this.__alt ? { alt: this.__alt } : {}),
+      ...(this.__width ? { width: this.__width } : {}),
+      ...(this.__height ? { height: this.__height } : {}),
+      ...(this.__align ? { align: this.__align } : {}),
+      ...(this.__caption ? { caption: this.__caption } : {}),
+      ...(this.__extra.length > 0 ? { extra: [...this.__extra] } : {}),
+      ...(this.__directives.length > 0 ? { directives: [...this.__directives] } : {}),
+      ...(this.__escapedPipes ? { escapedPipes: true } : {}),
+      ...(this.__inline ? { inline: true } : {}),
+      ...(this.__source ? { source: this.__source } : {}),
     };
   }
 
   createDOM(): HTMLElement {
-    const div = document.createElement("div");
-    div.className = "luthor-file-embed-shell";
-    return div;
+    const element = document.createElement(this.__inline ? "span" : "div");
+    element.className = this.__inline
+      ? "luthor-file-embed-shell luthor-file-embed-shell--inline"
+      : "luthor-file-embed-shell";
+    return element;
   }
 
-  updateDOM(): boolean {
-    return false;
+  updateDOM(prevNode: FileEmbedNode): boolean {
+    // Block ↔ inline needs a different container element.
+    return prevNode.__inline !== this.__inline;
   }
 
   exportDOM(): DOMExportOutput {
-    const div = document.createElement("div");
-    div.className = "luthor-file-embed luthor-file-embed--chip";
-    div.setAttribute("data-luthor-file-embed-target", this.__target);
-    div.textContent = this.__target;
-    return { element: div };
+    const element = document.createElement(this.__inline ? "span" : "div");
+    element.className = "luthor-file-embed luthor-file-embed--chip";
+    element.setAttribute("data-luthor-file-embed-target", this.__target);
+    element.textContent = this.__alt ?? this.__target;
+    return { element };
   }
 
   isInline(): boolean {
-    return false;
+    return this.__inline;
   }
 
   canBeEmpty(): boolean {
@@ -193,17 +273,101 @@ export class FileEmbedNode extends DecoratorNode<ReactNode> {
   }
 
   getTarget(): string {
-    return this.__target;
+    return this.getLatest().__target;
+  }
+
+  /** A snapshot of the editable fields. */
+  getFields(): FileEmbedFields {
+    const self = this.getLatest();
+    return {
+      target: self.__target,
+      fragment: self.__fragment,
+      alt: self.__alt,
+      width: self.__width,
+      height: self.__height,
+      align: self.__align,
+      caption: self.__caption,
+      extra: [...self.__extra],
+      directives: [...self.__directives],
+      escapedPipes: self.__escapedPipes,
+      inline: self.__inline,
+    };
+  }
+
+  /**
+   * This embed's markdown: the exact source text while the fields still say
+   * what it said, otherwise the canonical form of the current fields.
+   */
+  getMarkdown(): string {
+    const self = this.getLatest();
+    const canonical = formatFields(self.getFields());
+    if (self.__source) {
+      const parsed = parseFileEmbedMarkdown(self.__source, self.__inline);
+      if (parsed && formatFields(parsed) === canonical) {
+        return self.__source;
+      }
+    }
+    return canonical;
+  }
+
+  /** Replace the file this embed points at (size, caption and alignment stay). */
+  setTarget(target: string): this {
+    const writable = this.getWritable();
+    writable.__target = target;
+    return writable;
+  }
+
+  /** Set (or clear, with `undefined`) the display size in CSS pixels. */
+  setSize(width: number | undefined, height?: number): this {
+    const writable = this.getWritable();
+    writable.__width = width && width > 0 ? Math.round(width) : undefined;
+    writable.__height = writable.__width && height && height > 0 ? Math.round(height) : undefined;
+    return writable;
+  }
+
+  setAlign(align: MediaAlignment | undefined): this {
+    const writable = this.getWritable();
+    writable.__align = align;
+    return writable;
+  }
+
+  setCaption(caption: string | undefined): this {
+    const writable = this.getWritable();
+    writable.__caption = caption && caption.trim() !== "" ? caption.trim() : undefined;
+    return writable;
+  }
+
+  setAlt(alt: string | undefined): this {
+    const writable = this.getWritable();
+    writable.__alt = alt && alt.trim() !== "" ? alt.trim() : undefined;
+    return writable;
   }
 
   decorate(): ReactNode {
-    return <FileEmbedComponent target={this.__target} />;
+    return (
+      <MediaFrame
+        target={this.__target}
+        fragment={this.__fragment}
+        alt={this.__alt}
+        width={this.__width}
+        height={this.__height}
+        align={this.__align}
+        caption={this.__caption}
+        inline={this.__inline}
+      />
+    );
   }
 }
 
-/** Create a {@link FileEmbedNode}. */
-export function $createFileEmbedNode(target: string): FileEmbedNode {
-  return new FileEmbedNode(target);
+/**
+ * Create a {@link FileEmbedNode} — from a bare file name (an upload), or from
+ * fields plus the markdown they were parsed from.
+ */
+export function $createFileEmbedNode(
+  fields: FileEmbedFields | string,
+  source?: string,
+): FileEmbedNode {
+  return new FileEmbedNode(fields, source);
 }
 
 /** Type guard for {@link FileEmbedNode}. */
@@ -216,8 +380,9 @@ export function $isFileEmbedNode(
 /**
  * Headless extension that registers {@link FileEmbedNode} with the editor. The
  * node is rendered by its decorator and parsed/serialized by
- * {@link FILE_EMBED_MARKDOWN_TRANSFORMER}; registration contributes only the node
- * class.
+ * {@link FILE_EMBED_MARKDOWN_TRANSFORMER} (a line of its own) and
+ * {@link FILE_EMBED_INLINE_MARKDOWN_TRANSFORMER} (inside text); registration
+ * contributes only the node class.
  */
 export class FileEmbedExtension extends BaseExtension<"fileEmbed"> {
   constructor() {
@@ -236,29 +401,60 @@ export class FileEmbedExtension extends BaseExtension<"fileEmbed"> {
 export const fileEmbedExtension = new FileEmbedExtension();
 
 /**
- * Lossless bidirectional markdown transformer for {@link FileEmbedNode}.
- *
- * Import: a line that is exactly `![[file.ext]]` becomes a file embed.
- * Export: a file embed serializes back to `![[file.ext]]`, so a body that
- * round-trips through the editor is byte-stable for these embeds.
+ * Lossless markdown transformer for a block {@link FileEmbedNode}: a line that is
+ * exactly `![[…]]`, optionally followed by `<!-- key:value -->` directives.
+ * Must run after the prefixed `![[card:…]]` / `![[youtube:…]]` /
+ * `![[iframe:…]]` and `![[Note#^id]]` transformers.
  */
 export const FILE_EMBED_MARKDOWN_TRANSFORMER: ElementTransformer = {
   dependencies: [FileEmbedNode],
   export: (node) => {
-    if (!$isFileEmbedNode(node)) {
+    if (!$isFileEmbedNode(node) || node.isInline()) {
       return null;
     }
-
-    return `![[${node.getTarget()}]]`;
+    return node.getMarkdown();
   },
-  regExp: /^!\[\[([^\]]+)\]\]\s*$/,
+  regExp: /^!\[\[([^\]\r\n]+)\]\]((?:\s*<!--[\s\S]*?-->)*)\s*$/,
   replace: (parentNode: ElementNode, _children, match) => {
-    const target = (match[1] ?? "").trim();
-    if (!target) {
-      return;
+    const source = (match[0] ?? "").trim();
+    const fields = parseFileEmbedMarkdown(source);
+    if (!fields) {
+      return false;
     }
-
-    parentNode.replace($createFileEmbedNode(target));
+    parentNode.replace($createFileEmbedNode(fields, source));
   },
   type: "element",
 };
+
+// A file target (`name.ext`, no `:` scheme), an optional `#fragment`, optional
+// pipe segments (`|` or a table cell's `\|`).
+const INLINE_EMBED =
+  "!\\[\\[([^\\]\\r\\n|#:\\\\]+?\\.[A-Za-z0-9]{1,8}(?:#[^\\]\\r\\n|\\\\]*)?(?:\\\\?\\|[^\\]\\r\\n]*)?)\\]\\]";
+
+/**
+ * Lossless markdown transformer for an inline {@link FileEmbedNode}: a
+ * `![[file.ext]]` in the middle of text. Only *file* targets (with an
+ * extension) are claimed — a mid-paragraph `![[Note]]` stays text. Must come
+ * before the wikilink transformer.
+ */
+export const FILE_EMBED_INLINE_MARKDOWN_TRANSFORMER: TextMatchTransformer = {
+  dependencies: [FileEmbedNode],
+  export: (node) => {
+    if (!$isFileEmbedNode(node) || !node.isInline()) {
+      return null;
+    }
+    return node.getMarkdown();
+  },
+  importRegExp: new RegExp(INLINE_EMBED),
+  regExp: new RegExp(`${INLINE_EMBED}$`),
+  replace: (textNode, match) => {
+    const source = match[0] ?? "";
+    const fields = parseFileEmbedMarkdown(source, true);
+    if (!fields || !isFileTarget(fields.target)) {
+      return;
+    }
+    textNode.replace($createFileEmbedNode(fields, source));
+  },
+  trigger: "]",
+  type: "text-match",
+};
diff --git a/packages/headless/src/extensions/embeds/index.ts b/packages/headless/src/extensions/embeds/index.ts
index 4c91e781..f1da3443 100644
--- a/packages/headless/src/extensions/embeds/index.ts
+++ b/packages/headless/src/extensions/embeds/index.ts
@@ -11,6 +11,9 @@ export {
   useEmbedResolvers,
   type EmbedResolvers,
   type SavedCardMetadata,
+  type MediaMeta,
+  type MediaUrlOptions,
+  type FileExpansionContext,
 } from "./EmbedResolverContext";
 export {
   ANCHORABLE_BLOCK_TYPES,
@@ -33,6 +36,9 @@ export {
   $createFileEmbedNode,
   $isFileEmbedNode,
   FILE_EMBED_MARKDOWN_TRANSFORMER,
+  FILE_EMBED_INLINE_MARKDOWN_TRANSFORMER,
+  parseFileEmbedMarkdown,
+  type FileEmbedFields,
   type SerializedFileEmbedNode,
 } from "./FileEmbedNode";
 export {
diff --git a/packages/headless/src/extensions/index.ts b/packages/headless/src/extensions/index.ts
index 6d99adb8..4ca7a2f3 100644
--- a/packages/headless/src/extensions/index.ts
+++ b/packages/headless/src/extensions/index.ts
@@ -138,6 +138,22 @@ export {
   YOUTUBE_EMBED_MARKDOWN_TRANSFORMER,
   type YouTubeEmbedPayload,
 } from "./media/YouTubeEmbedExtension";
+// The shared media grammar (`![[x|480]]`, trailing directives) and view.
+export {
+  parseEmbedTarget,
+  formatEmbedTarget,
+  formatSize,
+  parseMediaDirectives,
+  formatMediaDirectives,
+  classifyMedia,
+  isFileTarget,
+  MEDIA_MAX_DIMENSION,
+  type EmbedTarget,
+  type MediaDirectives,
+  type MediaAlignment,
+  type MediaKind,
+} from "./media/mediaGrammar";
+export { MediaFrame, formatBytes, type MediaFrameProps } from "./media/MediaFrame";
 
 // Custom extensions
 export { createCustomNodeExtension } from "./custom/CustomNodeExtension";
@@ -150,6 +166,9 @@ export {
   useEmbedResolvers,
   type EmbedResolvers,
   type SavedCardMetadata,
+  type MediaMeta,
+  type MediaUrlOptions,
+  type FileExpansionContext,
   ANCHORABLE_BLOCK_TYPES,
   isAnchorableBlockType,
   $collectAnchorableBlocks,
@@ -166,6 +185,9 @@ export {
   $createFileEmbedNode,
   $isFileEmbedNode,
   FILE_EMBED_MARKDOWN_TRANSFORMER,
+  FILE_EMBED_INLINE_MARKDOWN_TRANSFORMER,
+  parseFileEmbedMarkdown,
+  type FileEmbedFields,
   type SerializedFileEmbedNode,
   TransclusionNode,
   TransclusionExtension,
diff --git a/packages/headless/src/extensions/media/IframeEmbedExtension.tsx b/packages/headless/src/extensions/media/IframeEmbedExtension.tsx
index 451a1670..90811717 100644
--- a/packages/headless/src/extensions/media/IframeEmbedExtension.tsx
+++ b/packages/headless/src/extensions/media/IframeEmbedExtension.tsx
@@ -5,6 +5,7 @@
  * Build freely. Credit kindly.
  */
 
+import { formatSize, splitCaptionAndSize } from "./mediaGrammar";
 import React, { ReactNode, useEffect, useMemo, useRef, useState } from "react";
 import {
   $createNodeSelection,
@@ -42,6 +43,11 @@ export type IframeEmbedPayload = {
   alignment: EmbedAlignment;
   title?: string;
   caption?: string;
+  /**
+   * The size was chosen (a resize, or `|WxH` in the markdown) rather than
+   * defaulted — only a chosen size is written back to markdown.
+   */
+  sized?: boolean;
 };
 
 export interface IframeEmbedConfig extends BaseExtensionConfig {
@@ -97,6 +103,7 @@ type SerializedIframeEmbedNode = Spread<
     alignment: EmbedAlignment;
     title?: string;
     caption?: string;
+    sized?: boolean;
   },
   SerializedLexicalNode
 >;
@@ -190,6 +197,7 @@ export class IframeEmbedNode extends DecoratorNode<ReactNode> {
       alignment: serialized.alignment,
       title: serialized.title,
       caption: serialized.caption ?? "",
+      sized: serialized.sized === true,
     });
   }
 
@@ -278,6 +286,7 @@ export class IframeEmbedNode extends DecoratorNode<ReactNode> {
       alignment: this.__payload.alignment,
       title: this.__payload.title,
       caption: this.__payload.caption,
+      ...(this.__payload.sized ? { sized: true } : {}),
     };
   }
 
@@ -319,6 +328,10 @@ export class IframeEmbedNode extends DecoratorNode<ReactNode> {
     writable.__payload = {
       ...writable.__payload,
       ...payload,
+      // Any new size is a chosen one, unless the caller says otherwise.
+      ...((payload.width !== undefined || payload.height !== undefined) && payload.sized === undefined
+        ? { sized: true }
+        : {}),
     };
   }
 
@@ -787,10 +800,12 @@ export const IFRAME_EMBED_MARKDOWN_TRANSFORMER: ElementTransformer = {
     if (!$isIframeEmbedNode(node)) {
       return null;
     }
-    const { src, caption } = node.getPayload();
-    return caption && caption.trim() !== ""
-      ? `![[iframe:${src}|${caption}]]`
-      : `![[iframe:${src}]]`;
+    const { src, caption, width, height, sized } = node.getPayload();
+    const segments = [
+      ...(caption && caption.trim() !== "" ? [caption] : []),
+      ...(sized ? [formatSize(width, height)] : []),
+    ];
+    return `![[iframe:${src}${segments.map((s) => `|${s}`).join("")}]]`;
   },
   regExp: /^!\[\[iframe:([^\]|]+)(?:\|([^\]]+))?\]\]\s*$/,
   replace: (parentNode: ElementNode, _children, match) => {
@@ -802,18 +817,16 @@ export const IFRAME_EMBED_MARKDOWN_TRANSFORMER: ElementTransformer = {
     if (!parsed) {
       return;
     }
-    const rawCaption = match[2];
-    const caption =
-      rawCaption !== undefined && rawCaption.trim() !== ""
-        ? rawCaption.trim()
-        : "";
+    // `|caption`, `|800x600` or both: a trailing size is the chosen frame size.
+    const { caption, width, height } = splitCaptionAndSize(match[2]);
     parentNode.replace(
       $createIframeEmbedNode({
         src: parsed.toString(),
-        width: 640,
-        height: 360,
+        width: width ?? 640,
+        height: height ?? (width ? Math.round((width * 9) / 16) : 360),
         alignment: "center",
         caption,
+        sized: width !== undefined,
       }),
     );
   },
diff --git a/packages/headless/src/extensions/media/ImageExtension.tsx b/packages/headless/src/extensions/media/ImageExtension.tsx
index 6974e625..5039d991 100644
--- a/packages/headless/src/extensions/media/ImageExtension.tsx
+++ b/packages/headless/src/extensions/media/ImageExtension.tsx
@@ -55,6 +55,7 @@ import {
   ImageTranslator,
 } from "./ImageTranslator";
 import { sanitizeUrlForAttribute } from "../../utils/urlSafety";
+import { formatSize, MEDIA_MAX_DIMENSION } from "./mediaGrammar";
 import { reportError, warnOnce } from "../../utils/logger";
 
 /**
@@ -1293,6 +1294,28 @@ function unescapeMarkdownImageText(value: string): string {
   return value.replace(/\\(["\\\]])/g, "$1");
 }
 
+/**
+ * Obsidian's sized-image syntax: `![alt|300](url)` / `![alt|300x200](url)`.
+ * The size rides at the end of the alt text, so every other renderer still
+ * shows the picture (with a slightly odd alt) and Obsidian shows it sized.
+ */
+function splitAltSize(alt: string): { alt: string; width?: number; height?: number } {
+  const match = /^([\s\S]*?)\|(\d{1,5})(?:x(\d{1,5}))?$/.exec(alt);
+  if (!match) {
+    return { alt };
+  }
+  const width = Number(match[2]);
+  const height = match[3] === undefined ? undefined : Number(match[3]);
+  if (
+    width < 1 ||
+    width > MEDIA_MAX_DIMENSION ||
+    (height !== undefined && (height < 1 || height > MEDIA_MAX_DIMENSION))
+  ) {
+    return { alt };
+  }
+  return { alt: match[1] ?? "", width, ...(height === undefined ? {} : { height }) };
+}
+
 type MarkdownImageDirectives = {
   alignment: "left" | "center" | "right" | "none";
   linkHref?: string;
@@ -1404,7 +1427,8 @@ export const IMAGE_MARKDOWN_TRANSFORMER = {
       return null;
     }
 
-    let imageMarkdown = `![${escapeMarkdownImageText(alt)}](${src}`;
+    const size = formatSize(imageNode.__width, imageNode.__height);
+    let imageMarkdown = `![${escapeMarkdownImageText(alt)}${size ? `|${size}` : ""}](${src}`;
     
     // Add caption as title if present
     if (caption) {
@@ -1447,9 +1471,10 @@ export const IMAGE_MARKDOWN_TRANSFORMER = {
       return;
     }
 
+    const sized = splitAltSize(typeof alt === "string" ? unescapeMarkdownImageText(alt) : "");
     const imageNode = $createImageNode(
       src,
-      typeof alt === "string" ? unescapeMarkdownImageText(alt) : "",
+      sized.alt,
       typeof caption === "string" && caption.length > 0
         ? unescapeMarkdownImageText(caption)
         : undefined,
@@ -1458,8 +1483,8 @@ export const IMAGE_MARKDOWN_TRANSFORMER = {
       parsedDirectives.alignment,
       undefined,
       undefined,
-      undefined,
-      undefined,
+      sized.width,
+      sized.height,
       false,
     );
 
diff --git a/packages/headless/src/extensions/media/MediaFrame.test.tsx b/packages/headless/src/extensions/media/MediaFrame.test.tsx
new file mode 100644
index 00000000..3c5d16ea
--- /dev/null
+++ b/packages/headless/src/extensions/media/MediaFrame.test.tsx
@@ -0,0 +1,159 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+/* @vitest-environment jsdom */
+
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import {
+  EmbedResolverProvider,
+  type EmbedResolvers,
+  type MediaMeta,
+} from "../embeds/EmbedResolverContext";
+import { MediaFrame, type MediaFrameProps } from "./MediaFrame";
+
+/** A host that serves `/m/<name>`, thumbnails at `/m/<name>/thumb?w=`, and meta from a map. */
+function host(meta: Record<string, MediaMeta> = {}, variants = true) {
+  const listeners = new Set<() => void>();
+  const store = { ...meta };
+  const resolvers: EmbedResolvers = {
+    resolveMediaUrl: (target, options) => {
+      const base = `/m/${encodeURIComponent(target)}`;
+      if (!variants || !options?.variant || options.variant === "original") return base;
+      return `${base}/${options.variant}?w=${options.width ?? 0}`;
+    },
+    getMediaMeta: (target) => store[target],
+    subscribeMediaMeta: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    renderFileExpansion: ({ target, fragment }) =>
+      target.endsWith(".pdf") ? <div data-testid="expansion">viewer {fragment}</div> : null,
+  };
+  const publish = (target: string, value: MediaMeta) => {
+    store[target] = value;
+    listeners.forEach((l) => l());
+  };
+  return { resolvers, publish };
+}
+
+function draw(props: MediaFrameProps, resolvers: EmbedResolvers) {
+  return render(
+    <EmbedResolverProvider resolvers={resolvers}>
+      <MediaFrame {...props} />
+    </EmbedResolverProvider>,
+  );
+}
+
+describe("MediaFrame", () => {
+  it("without a host, shows a chip naming the file", () => {
+    draw({ target: "a.png" }, {});
+    expect(screen.getByRole("note").textContent).toBe("a.png");
+  });
+
+  it("reserves an image's box from its metadata before it loads", () => {
+    const { resolvers } = host({ "a.png": { width: 1600, height: 900, thumb: true } });
+    const { container } = draw({ target: "a.png", alt: "Beach" }, resolvers);
+    const img = container.querySelector("img")!;
+    expect(img.getAttribute("loading")).toBe("lazy");
+    expect(img.getAttribute("decoding")).toBe("async");
+    expect(img.getAttribute("alt")).toBe("Beach");
+    expect(img.style.aspectRatio).toBe("1600 / 900");
+    expect((container.querySelector(".luthor-media__frame") as HTMLElement).style.width).toBe("min(1600px, 100%)");
+  });
+
+  it("an explicit size wins, and keeps the file's shape unless a box is given", () => {
+    const { resolvers } = host({ "a.png": { width: 1600, height: 900 } });
+    const { container, rerender } = draw({ target: "a.png", width: 480 }, resolvers);
+    expect((container.querySelector(".luthor-media__frame") as HTMLElement).style.width).toBe("min(480px, 100%)");
+    expect(container.querySelector("img")!.style.aspectRatio).toBe("1600 / 900");
+    rerender(
+      <EmbedResolverProvider resolvers={resolvers}>
+        <MediaFrame target="a.png" width={400} height={400} />
+      </EmbedResolverProvider>,
+    );
+    expect(container.querySelector("img")!.style.aspectRatio).toBe("400 / 400");
+  });
+
+  it("offers right-sized thumbnails via srcset — but never for an animation", () => {
+    const { resolvers } = host({
+      "a.png": { width: 2000, height: 1000, thumb: true },
+      "b.gif": { width: 2000, height: 1000, thumb: true, animated: true },
+    });
+    const { container } = draw({ target: "a.png" }, resolvers);
+    const srcset = container.querySelector("img")!.getAttribute("srcset")!;
+    expect(srcset).toContain("/m/a.png/thumb?w=320 320w");
+    expect(srcset).toContain("/m/a.png/thumb?w=1280 1280w");
+    expect(srcset).toContain("/m/a.png 2000w");
+
+    const gif = draw({ target: "b.gif" }, resolvers);
+    expect(gif.container.querySelector("img")!.getAttribute("srcset")).toBeNull();
+  });
+
+  it("skips srcset for a host without renditions", () => {
+    const { resolvers } = host({ "a.png": { width: 2000, height: 1000, thumb: true } }, false);
+    const { container } = draw({ target: "a.png" }, resolvers);
+    expect(container.querySelector("img")!.getAttribute("srcset")).toBeNull();
+  });
+
+  it("re-renders when metadata arrives", () => {
+    const { resolvers, publish } = host();
+    const { container } = draw({ target: "late.png" }, resolvers);
+    expect(container.querySelector("img")!.style.aspectRatio).toBe("");
+    act(() => publish("late.png", { width: 300, height: 200 }));
+    expect(container.querySelector("img")!.style.aspectRatio).toBe("300 / 200");
+  });
+
+  it("turns a failed load into a card with Retry, and Retry re-requests the file", () => {
+    const { resolvers } = host();
+    const { container } = draw({ target: "gone.png" }, resolvers);
+    fireEvent.error(container.querySelector("img")!);
+    expect(screen.getByRole("group", { name: "Couldn't load gone.png" })).toBeTruthy();
+    expect(screen.getByText("Open file").getAttribute("href")).toBe("/m/gone.png");
+
+    fireEvent.click(screen.getByText("Retry"));
+    expect(container.querySelector("img")!.getAttribute("src")).toBe("/m/gone.png?retry=1");
+  });
+
+  it("gives video a poster, metadata-only preload and a 16:9 box by default", () => {
+    const { resolvers } = host({ "c.mp4": { poster: true } });
+    const { container } = draw({ target: "c.mp4" }, resolvers);
+    const video = container.querySelector("video")!;
+    expect(video.getAttribute("preload")).toBe("metadata");
+    expect(video.getAttribute("poster")).toBe("/m/c.mp4/poster?w=1280");
+    expect(video.style.aspectRatio).toBe("16 / 9");
+  });
+
+  it("shows audio in a card with its running time", () => {
+    const { resolvers } = host({ "s.mp3": { durationMs: 185_000 } });
+    const { container } = draw({ target: "s.mp3" }, resolvers);
+    expect(container.querySelector("audio")).toBeTruthy();
+    expect(container.textContent).toContain("3:05");
+  });
+
+  it("shows documents as a card with type and size, plus the host's expansion", () => {
+    const { resolvers } = host({ "q3.pdf": { size: 2_400_000 } });
+    const { container } = draw({ target: "q3.pdf", fragment: "page=3" }, resolvers);
+    expect(container.querySelector(".luthor-media__card-icon")!.textContent).toBe("PDF");
+    expect(container.textContent).toContain("PDF · 2.3 MB");
+    expect(screen.getByTestId("expansion").textContent).toBe("viewer page=3");
+  });
+
+  it("renders inline embeds as an inline frame with no caption", () => {
+    const { resolvers } = host();
+    const { container } = draw({ target: "i.png", inline: true, caption: "x" }, resolvers);
+    expect(container.querySelector("span.luthor-media--inline")).toBeTruthy();
+    expect(container.querySelector("figcaption")).toBeNull();
+  });
+
+  it("aligns and captions a block", () => {
+    const { resolvers } = host();
+    const { container } = draw({ target: "a.png", align: "center", caption: "Dusk" }, resolvers);
+    expect(container.querySelector("figure")!.getAttribute("data-align")).toBe("center");
+    expect(container.querySelector("figcaption")!.textContent).toBe("Dusk");
+  });
+});
diff --git a/packages/headless/src/extensions/media/MediaFrame.tsx b/packages/headless/src/extensions/media/MediaFrame.tsx
new file mode 100644
index 00000000..9a71aaea
--- /dev/null
+++ b/packages/headless/src/extensions/media/MediaFrame.tsx
@@ -0,0 +1,285 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+import {
+  useCallback,
+  useState,
+  useSyncExternalStore,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+import {
+  useEmbedResolvers,
+  type EmbedResolvers,
+  type MediaMeta,
+} from "../embeds/EmbedResolverContext";
+import { classifyMedia, type MediaAlignment } from "./mediaGrammar";
+
+/** Everything a media frame needs to draw an attachment. */
+export interface MediaFrameProps {
+  /** The file reference (`photo.png`), without fragment or pipes. */
+  target: string;
+  /** Text after `#` in the embed (`page=3`), or empty. */
+  fragment?: string;
+  /** Alt text; falls back to the file name. */
+  alt?: string;
+  /** Display width in CSS pixels (from `|W`); capped to the container. */
+  width?: number;
+  /** Display height in CSS pixels (from `|WxH`); only its ratio to width is used. */
+  height?: number;
+  align?: MediaAlignment;
+  caption?: string;
+  /** Rendered inside a line of text rather than as its own block. */
+  inline?: boolean;
+}
+
+const THUMB_WIDTHS = [320, 640, 1280];
+const NO_SUBSCRIPTION = () => () => {};
+
+function useMediaMeta(resolvers: EmbedResolvers, target: string): MediaMeta | null | undefined {
+  const subscribe = resolvers.subscribeMediaMeta ?? NO_SUBSCRIPTION;
+  const read = useCallback(
+    () => resolvers.getMediaMeta?.(target) ?? undefined,
+    [resolvers, target],
+  );
+  return useSyncExternalStore(subscribe, read, read);
+}
+
+function positive(value: number | null | undefined): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+/** `12 KB`, `3.4 MB`. */
+export function formatBytes(bytes: number | undefined): string {
+  if (!bytes || bytes < 0) return "";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1).replace(/\.0$/, "")} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1).replace(/\.0$/, "")} GB`;
+}
+
+function formatDuration(ms: number | undefined): string {
+  if (!ms) return "";
+  const total = Math.round(ms / 1000);
+  const h = Math.floor(total / 3600);
+  const m = Math.floor((total % 3600) / 60);
+  const s = total % 60;
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return h > 0 ? `${h}:${pad(m)}:${pad(s)}` : `${m}:${pad(s)}`;
+}
+
+function extensionLabel(target: string): string {
+  const match = /\.([a-z0-9]{1,8})$/i.exec(target);
+  return match ? match[1]!.toUpperCase() : "FILE";
+}
+
+function withRetry(url: string, attempt: number): string {
+  if (attempt === 0) return url;
+  return `${url}${url.includes("?") ? "&" : "?"}retry=${attempt}`;
+}
+
+/**
+ * The shared view for an embedded attachment: pictures, video, audio, PDFs and
+ * other files. It is built to never shift the page and never break:
+ *
+ * - **Its box is reserved before anything loads.** Width comes from the embed
+ *   (`|480`) or the host's metadata, the shape from `|WxH` or the metadata; the
+ *   element gets `aspect-ratio`, so text below doesn't jump when the file arrives.
+ * - **It loads what it needs.** Pictures are lazy, decode off the main thread, and
+ *   — when the host offers thumbnails — pick a right-sized rendition via `srcset`.
+ *   Video loads only its metadata until played, behind its poster.
+ * - **A failure is a card, not a broken-image glyph**, with Retry and a way to
+ *   open the file. The markdown is never touched.
+ */
+export function MediaFrame(props: MediaFrameProps): ReactNode {
+  const { target, fragment = "", alt, width, height, align, caption, inline = false } = props;
+  const resolvers = useEmbedResolvers();
+  const meta = useMediaMeta(resolvers, target);
+  const [attempt, setAttempt] = useState(0);
+  // Keyed by URL: replacing the file (a new target) starts clean.
+  const [failedUrl, setFailedUrl] = useState<string | null>(null);
+
+  const resolve = resolvers.resolveMediaUrl;
+  const url = typeof resolve === "function" ? resolve(target) : "";
+  const kind = classifyMedia(target);
+  const label = alt?.trim() || target;
+  const failed = failedUrl !== null && failedUrl === url;
+  const setFailed = (value: boolean) => setFailedUrl(value ? url : null);
+
+  // No host to resolve the file: a reference chip, so the embed stays visible.
+  if (!url) {
+    return (
+      <span
+        className="luthor-file-embed luthor-file-embed--chip"
+        data-luthor-file-embed-target={target}
+        role="note"
+        aria-label={`Embedded file: ${target}`}
+      >
+        {target}
+      </span>
+    );
+  }
+
+  const naturalWidth = positive(meta?.width);
+  const naturalHeight = positive(meta?.height);
+  const displayWidth = positive(width) ?? naturalWidth;
+  // Shape: an explicit box wins, then the file's own; video defaults to 16:9.
+  const ratio =
+    positive(width) && positive(height)
+      ? `${width} / ${height}`
+      : naturalWidth && naturalHeight
+        ? `${naturalWidth} / ${naturalHeight}`
+        : kind === "video"
+          ? "16 / 9"
+          : undefined;
+
+  const frameStyle: CSSProperties = {
+    ...(displayWidth ? { width: `min(${Math.round(displayWidth)}px, 100%)` } : {}),
+  };
+  const mediaStyle: CSSProperties = {
+    width: "100%",
+    height: "auto",
+    ...(ratio ? { aspectRatio: ratio } : {}),
+    objectFit: "contain",
+  };
+
+  const retry = () => {
+    setFailed(false);
+    setAttempt((n) => n + 1);
+  };
+
+  const failure = (
+    <span className="luthor-media__error" role="group" aria-label={`Couldn't load ${label}`}>
+      <span className="luthor-media__error-text">Couldn&rsquo;t load {label}</span>
+      <span className="luthor-media__error-actions">
+        <button type="button" className="luthor-media__button" onClick={retry}>
+          Retry
+        </button>
+        <a className="luthor-media__button" href={url} target="_blank" rel="noopener noreferrer">
+          Open file
+        </a>
+      </span>
+    </span>
+  );
+
+  let body: ReactNode;
+  if (failed) {
+    body = failure;
+  } else if (kind === "image") {
+    // Right-sized renditions when the host has them — never for an animation
+    // (a thumbnail is a still) and only when the intrinsic width is known.
+    const thumbUrl =
+      meta?.thumb && !meta.animated && naturalWidth && resolve
+        ? (w: number) => resolve(target, { variant: "thumb", width: w })
+        : null;
+    const candidates =
+      thumbUrl && thumbUrl(THUMB_WIDTHS[0]!) !== url
+        ? THUMB_WIDTHS.filter((w) => w < naturalWidth!).map((w) => `${thumbUrl(w)} ${w}w`)
+        : [];
+    const srcSet = candidates.length > 0 ? [...candidates, `${url} ${naturalWidth}w`].join(", ") : undefined;
+    body = (
+      <img
+        className="luthor-file-embed luthor-file-embed--image luthor-media__element"
+        src={withRetry(url, attempt)}
+        srcSet={srcSet}
+        sizes={srcSet ? (displayWidth ? `min(${Math.round(displayWidth)}px, 100vw)` : "100vw") : undefined}
+        alt={alt?.trim() || target}
+        loading="lazy"
+        decoding="async"
+        width={naturalWidth}
+        height={naturalHeight}
+        style={mediaStyle}
+        draggable={false}
+        onError={() => setFailed(true)}
+      />
+    );
+  } else if (kind === "video") {
+    const poster =
+      meta?.poster && resolve ? resolve(target, { variant: "poster", width: 1280 }) : undefined;
+    body = (
+      <video
+        className="luthor-file-embed luthor-file-embed--video luthor-media__element"
+        src={withRetry(url, attempt)}
+        poster={poster && poster !== url ? poster : undefined}
+        controls
+        preload="metadata"
+        playsInline
+        aria-label={label}
+        style={mediaStyle}
+        onError={() => setFailed(true)}
+      />
+    );
+  } else if (kind === "audio") {
+    const duration = formatDuration(positive(meta?.durationMs));
+    body = (
+      <span className="luthor-media__card luthor-media__card--audio">
+        <span className="luthor-media__card-title">
+          <span className="luthor-media__card-name">{label}</span>
+          {duration ? <span className="luthor-media__card-detail">{duration}</span> : null}
+        </span>
+        <audio
+          className="luthor-file-embed luthor-file-embed--audio"
+          src={withRetry(url, attempt)}
+          controls
+          preload="metadata"
+          aria-label={label}
+          onError={() => setFailed(true)}
+        />
+      </span>
+    );
+  } else {
+    const details = [extensionLabel(target), formatBytes(meta?.size)].filter(Boolean).join(" · ");
+    const expansion = resolvers.renderFileExpansion?.({ target, fragment, url, kind, meta }) ?? null;
+    body = (
+      <span className="luthor-media__card luthor-media__card--file">
+        <a
+          className="luthor-file-embed luthor-media__card-link"
+          href={url}
+          target="_blank"
+          rel="noopener noreferrer"
+          data-luthor-file-embed-target={target}
+        >
+          <span className="luthor-media__card-icon" aria-hidden="true">
+            {extensionLabel(target)}
+          </span>
+          <span className="luthor-media__card-title">
+            <span className="luthor-media__card-name">{label}</span>
+            {details ? <span className="luthor-media__card-detail">{details}</span> : null}
+          </span>
+        </a>
+        {expansion}
+      </span>
+    );
+  }
+
+  const className = [
+    "luthor-media",
+    `luthor-media--${kind}`,
+    inline ? "luthor-media--inline" : "luthor-media--block",
+    align ? `luthor-media--align-${align}` : "",
+    failed ? "luthor-media--failed" : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  if (inline) {
+    return (
+      <span className={className} data-luthor-media-kind={kind} style={frameStyle}>
+        {body}
+      </span>
+    );
+  }
+
+  return (
+    <figure className={className} data-luthor-media-kind={kind} data-align={align ?? "none"}>
+      <div className="luthor-media__frame" style={frameStyle}>
+        {body}
+      </div>
+      {caption ? <figcaption className="luthor-media__caption">{caption}</figcaption> : null}
+    </figure>
+  );
+}
diff --git a/packages/headless/src/extensions/media/YouTubeEmbedExtension.tsx b/packages/headless/src/extensions/media/YouTubeEmbedExtension.tsx
index 4327d446..3281b83a 100644
--- a/packages/headless/src/extensions/media/YouTubeEmbedExtension.tsx
+++ b/packages/headless/src/extensions/media/YouTubeEmbedExtension.tsx
@@ -5,6 +5,7 @@
  * Build freely. Credit kindly.
  */
 
+import { formatSize, splitCaptionAndSize } from "./mediaGrammar";
 import React, { ReactNode, useEffect, useMemo, useRef, useState } from "react";
 import {
   $createNodeSelection,
@@ -42,6 +43,11 @@ export type YouTubeEmbedPayload = {
   alignment: EmbedAlignment;
   caption?: string;
   start?: number;
+  /**
+   * The size was chosen (a resize, or `|WxH` in the markdown) rather than
+   * defaulted — only a chosen size is written back to markdown.
+   */
+  sized?: boolean;
 };
 
 export interface YouTubeEmbedConfig extends BaseExtensionConfig {
@@ -82,6 +88,7 @@ type SerializedYouTubeEmbedNode = Spread<
     alignment: EmbedAlignment;
     caption?: string;
     start?: number;
+    sized?: boolean;
   },
   SerializedLexicalNode
 >;
@@ -327,6 +334,7 @@ export class YouTubeEmbedNode extends DecoratorNode<ReactNode> {
       alignment: serialized.alignment,
       caption: serialized.caption ?? "",
       start: serialized.start,
+      sized: serialized.sized === true,
     });
   }
 
@@ -440,6 +448,7 @@ export class YouTubeEmbedNode extends DecoratorNode<ReactNode> {
       alignment: this.__payload.alignment,
       caption: this.__payload.caption,
       start: this.__payload.start,
+      ...(this.__payload.sized ? { sized: true } : {}),
     };
   }
 
@@ -487,6 +496,10 @@ export class YouTubeEmbedNode extends DecoratorNode<ReactNode> {
     writable.__payload = {
       ...writable.__payload,
       ...payload,
+      // Any new size is a chosen one, unless the caller says otherwise.
+      ...((payload.width !== undefined || payload.height !== undefined) && payload.sized === undefined
+        ? { sized: true }
+        : {}),
     };
   }
 
@@ -1039,10 +1052,12 @@ export const YOUTUBE_EMBED_MARKDOWN_TRANSFORMER: ElementTransformer = {
     if (!$isYouTubeEmbedNode(node)) {
       return null;
     }
-    const { src, caption } = node.getPayload();
-    return caption && caption.trim() !== ""
-      ? `![[youtube:${src}|${caption}]]`
-      : `![[youtube:${src}]]`;
+    const { src, caption, width, height, sized } = node.getPayload();
+    const segments = [
+      ...(caption && caption.trim() !== "" ? [caption] : []),
+      ...(sized ? [formatSize(width, height)] : []),
+    ];
+    return `![[youtube:${src}${segments.map((s) => `|${s}`).join("")}]]`;
   },
   regExp: /^!\[\[youtube:([^\]|]+)(?:\|([^\]]+))?\]\]\s*$/,
   replace: (parentNode: ElementNode, _children, match) => {
@@ -1051,18 +1066,16 @@ export const YOUTUBE_EMBED_MARKDOWN_TRANSFORMER: ElementTransformer = {
       return;
     }
     const embedUrl = toEmbedUrl(raw, YOUTUBE_MARKDOWN_EMBED_OPTIONS) ?? raw;
-    const rawCaption = match[2];
-    const caption =
-      rawCaption !== undefined && rawCaption.trim() !== ""
-        ? rawCaption.trim()
-        : "";
+    // `|caption`, `|640x360` or both: a trailing size is the chosen player size.
+    const { caption, width, height } = splitCaptionAndSize(match[2]);
     parentNode.replace(
       $createYouTubeEmbedNode({
         src: embedUrl,
-        width: 640,
-        height: 480,
+        width: width ?? 640,
+        height: height ?? (width ? Math.round((width * 9) / 16) : 480),
         alignment: "center",
         caption,
+        sized: width !== undefined,
       }),
     );
   },
diff --git a/packages/headless/src/extensions/media/index.ts b/packages/headless/src/extensions/media/index.ts
index 40096159..ce720769 100644
--- a/packages/headless/src/extensions/media/index.ts
+++ b/packages/headless/src/extensions/media/index.ts
@@ -9,3 +9,5 @@ export * from "./ImageExtension";
 export * from "./ImageTranslator";
 export * from "./IframeEmbedExtension";
 export * from "./YouTubeEmbedExtension";
+export * from "./mediaGrammar";
+export { MediaFrame, formatBytes, type MediaFrameProps } from "./MediaFrame";
diff --git a/packages/headless/src/extensions/media/mediaGrammar.test.ts b/packages/headless/src/extensions/media/mediaGrammar.test.ts
new file mode 100644
index 00000000..0cb87f77
--- /dev/null
+++ b/packages/headless/src/extensions/media/mediaGrammar.test.ts
@@ -0,0 +1,194 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  classifyMedia,
+  formatEmbedTarget,
+  formatMediaDirectives,
+  formatSize,
+  isFileTarget,
+  parseEmbedTarget,
+  parseMediaDirectives,
+  splitCaptionAndSize,
+  type EmbedTarget,
+} from "./mediaGrammar";
+
+describe("parseEmbedTarget", () => {
+  it.each([
+    ["a.png", { target: "a.png", fragment: "", extra: [] }],
+    ["a.png|300", { target: "a.png", width: 300 }],
+    ["a.png|300x200", { target: "a.png", width: 300, height: 200 }],
+    ["a.png|Sunset", { target: "a.png", alt: "Sunset" }],
+    ["a.png|Sunset|300", { target: "a.png", alt: "Sunset", width: 300 }],
+    ["a.png|300|Sunset", { target: "a.png", alt: "Sunset", width: 300 }],
+    ["doc.pdf#page=3", { target: "doc.pdf", fragment: "page=3" }],
+    ["doc.pdf#page=3|Report", { target: "doc.pdf", fragment: "page=3", alt: "Report" }],
+    ["a.png|0", { target: "a.png", alt: "0" }],
+    ["a.png|99999", { target: "a.png", alt: "99999" }],
+    ["a.png|16384", { target: "a.png", width: 16384 }],
+    ["a.png|300x0", { target: "a.png", alt: "300x0" }],
+    ["a.png|12|34", { target: "a.png", alt: "12", width: 34 }],
+    ["a.png\\|40", { target: "a.png", width: 40, escapedPipes: true }],
+  ])("%s", (inner, expected) => {
+    expect(parseEmbedTarget(inner)).toMatchObject(expected);
+  });
+
+  it("keeps unknown segments in order", () => {
+    expect(parseEmbedTarget("a.png|Alt|one|two|300")).toMatchObject({
+      alt: "Alt",
+      extra: ["one", "two"],
+      width: 300,
+    });
+  });
+});
+
+describe("formatEmbedTarget", () => {
+  it("puts the size last and keeps an escaped table pipe", () => {
+    expect(formatEmbedTarget({ target: "a.png", fragment: "", alt: "Alt", width: 300, extra: [], escapedPipes: false })).toBe("a.png|Alt|300");
+    expect(formatEmbedTarget({ target: "a.png", fragment: "", width: 40, extra: [], escapedPipes: true })).toBe("a.png\\|40");
+  });
+
+  it("never lets an alt break the embed", () => {
+    expect(formatEmbedTarget({ target: "a.png", fragment: "", alt: "x|y]]z\nq", extra: [], escapedPipes: false })).toBe("a.png|x y z q");
+  });
+});
+
+describe("formatSize", () => {
+  it.each([
+    [undefined, undefined, ""],
+    [0, undefined, ""],
+    [300.4, undefined, "300"],
+    [300, 199.6, "300x200"],
+    [99999, 99999, "16384x16384"],
+  ])("%s × %s → %s", (w, h, out) => expect(formatSize(w, h)).toBe(out));
+});
+
+describe("directives", () => {
+  it("parses align and caption, keeps unknown ones verbatim", () => {
+    expect(parseMediaDirectives(" <!-- align:center --> <!-- caption:Hi &amp; bye --> <!-- foo:bar -->")).toEqual({
+      align: "center",
+      caption: "Hi & bye",
+      unknown: ["<!-- foo:bar -->"],
+    });
+  });
+
+  it("refuses a line with anything other than comments after the embed", () => {
+    expect(parseMediaDirectives("<!-- align:center --> text")).toBeNull();
+    expect(parseMediaDirectives("text")).toBeNull();
+  });
+
+  it("keeps an alignment it doesn't know verbatim rather than inventing one", () => {
+    expect(parseMediaDirectives("<!-- align:justify -->")).toEqual({ unknown: ["<!-- align:justify -->"] });
+  });
+
+  it("encodes a caption so it can never close the comment early", () => {
+    const text = formatMediaDirectives({ caption: "a --> b <c> & d\nnext", unknown: [] });
+    expect(text).toBe(" <!-- caption:a --&gt; b &lt;c&gt; &amp; d next -->");
+    expect(parseMediaDirectives(text)?.caption).toBe("a --> b <c> & d next");
+  });
+});
+
+describe("splitCaptionAndSize", () => {
+  it.each([
+    [undefined, { caption: "" }],
+    ["My talk", { caption: "My talk" }],
+    ["800x450", { caption: "", width: 800, height: 450 }],
+    ["My talk|800x450", { caption: "My talk", width: 800, height: 450 }],
+    ["a|b", { caption: "a|b" }],
+  ])("%s", (rest, expected) => expect(splitCaptionAndSize(rest)).toEqual(expected));
+});
+
+describe("classification", () => {
+  it.each([
+    ["a.PNG", "image"],
+    ["b.heic", "image"],
+    ["c.mov", "video"],
+    ["d.opus", "audio"],
+    ["e.pdf", "pdf"],
+    ["f.docx", "file"],
+    ["My Note", "file"],
+  ])("%s → %s", (target, kind) => expect(classifyMedia(target)).toBe(kind));
+
+  it("tells file targets from note targets", () => {
+    expect(isFileTarget("a.png")).toBe(true);
+    expect(isFileTarget("archive.tar.gz")).toBe(true);
+    expect(isFileTarget("My Note")).toBe(false);
+    expect(isFileTarget("youtube:https://x.y/z.mp4")).toBe(false);
+  });
+});
+
+// ── Fuzz: format → parse is the identity on anything the grammar can produce ──
+
+function rng(seed: number) {
+  let state = seed >>> 0;
+  return () => {
+    state = (state * 1664525 + 1013904223) >>> 0;
+    return state / 2 ** 32;
+  };
+}
+
+const ALPHABET = "abcXYZ019 -_.()#&<>é漢|]\\\n";
+
+function word(next: () => number, max = 12): string {
+  const length = Math.floor(next() * max);
+  let out = "";
+  for (let i = 0; i < length; i++) out += ALPHABET[Math.floor(next() * ALPHABET.length)];
+  return out;
+}
+
+describe("fuzz", () => {
+  it("parse(format(x)) keeps every field (2000 random embeds)", () => {
+    const next = rng(20260930);
+    for (let i = 0; i < 2000; i++) {
+      const value: EmbedTarget = {
+        target: (word(next).replace(/[|#\]\\\n]/g, "") || "f") + ".png",
+        fragment: next() < 0.3 ? word(next).replace(/[|\]\\\n]/g, "").trim() : "",
+        alt: next() < 0.5 ? word(next) : undefined,
+        width: next() < 0.6 ? 1 + Math.floor(next() * 5000) : undefined,
+        height: undefined,
+        extra: [],
+        escapedPipes: next() < 0.2,
+      };
+      if (value.width && next() < 0.5) value.height = 1 + Math.floor(next() * 5000);
+      const formatted = formatEmbedTarget(value);
+      const parsed = parseEmbedTarget(formatted);
+      const sanitizedAlt =
+        value.alt?.replace(/[|\]\r\n]+/g, " ").replace(/[\s\\]+$/, "").trim() || undefined;
+      expect(parsed.target, formatted).toBe(value.target.trim());
+      expect(parsed.fragment, formatted).toBe(value.fragment);
+      // An alt that itself reads as a size (`|9`) is indistinguishable from one —
+      // Obsidian's own ambiguity, with no escape. Everything else must survive.
+      if (sanitizedAlt && /^\d{1,5}(x\d{1,5})?$/.test(sanitizedAlt)) continue;
+      expect(parsed.width, formatted).toBe(value.width);
+      expect(parsed.height, formatted).toBe(value.width ? value.height : undefined);
+      expect(parsed.alt, formatted).toBe(sanitizedAlt);
+      // …and formatting what was parsed is stable.
+      expect(formatEmbedTarget(parsed)).toBe(formatEmbedTarget(parseEmbedTarget(formatEmbedTarget(parsed))));
+    }
+  });
+
+  it("parse never throws on arbitrary input (5000 random strings)", () => {
+    const next = rng(7);
+    for (let i = 0; i < 5000; i++) {
+      const input = word(next, 40);
+      expect(() => parseEmbedTarget(input)).not.toThrow();
+      expect(() => parseMediaDirectives(input)).not.toThrow();
+      expect(() => splitCaptionAndSize(input)).not.toThrow();
+    }
+  });
+
+  it("captions survive any text (1000 random captions)", () => {
+    const next = rng(99);
+    for (let i = 0; i < 1000; i++) {
+      const caption = word(next, 30);
+      const parsed = parseMediaDirectives(formatMediaDirectives({ caption, unknown: [] }));
+      const expected = caption.replace(/[\r\n]+/g, " ").trim();
+      expect(parsed?.caption ?? "", JSON.stringify(caption)).toBe(expected);
+    }
+  });
+});
diff --git a/packages/headless/src/extensions/media/mediaGrammar.ts b/packages/headless/src/extensions/media/mediaGrammar.ts
new file mode 100644
index 00000000..d67db815
--- /dev/null
+++ b/packages/headless/src/extensions/media/mediaGrammar.ts
@@ -0,0 +1,299 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+/*
+ * The markdown grammar for sized, aligned, captioned media — pure functions, no
+ * Lexical, so every node and host shares one definition of it.
+ *
+ *   ![[photo.png]]                          natural size
+ *   ![[photo.png|480]]                      480px wide (Obsidian's syntax)
+ *   ![[clip.mp4|640x360]]                   explicit box
+ *   ![[photo.png|A sunset|480]]             alt text + width
+ *   ![[report.pdf#page=3]]                  a fragment (PDF page, heading…)
+ *   ![[photo.png|480]] <!-- align:center --> <!-- caption:Dusk -->
+ *
+ * Size is Obsidian's own `|W` / `|WxH`, so a vault stays portable. Alignment and
+ * captions have no Obsidian syntax, so they ride in trailing HTML comments that
+ * every other renderer ignores. Unknown pipe segments and unknown directives are
+ * kept verbatim, in order: the grammar never drops what it doesn't understand.
+ *
+ * Byte-stability is the caller's other half: a node remembers the exact source
+ * it was parsed from and exports that until something is actually edited — see
+ * FileEmbedNode. `format*` here produce the canonical form used after an edit.
+ */
+
+export type MediaAlignment = "left" | "center" | "right";
+
+/** A parsed `![[…]]` inner target. */
+export interface EmbedTarget {
+  /** The file reference, without fragment or pipe segments (`photo.png`). */
+  target: string;
+  /** Text after `#` (`page=3`, `Heading`), without the `#`; empty when absent. */
+  fragment: string;
+  /** The first non-size pipe segment, Obsidian's alias (used as alt text). */
+  alt?: string;
+  /** Width in CSS pixels from a `|W` or `|WxH` segment. */
+  width?: number;
+  /** Height in CSS pixels from a `|WxH` segment. */
+  height?: number;
+  /** Any further pipe segments, verbatim and in order. */
+  extra: string[];
+  /** The source used `\|` (inside a table cell); formatting keeps doing so. */
+  escapedPipes: boolean;
+}
+
+/** Parsed trailing `<!-- key:value -->` directives. */
+export interface MediaDirectives {
+  align?: MediaAlignment;
+  caption?: string;
+  /** Directives this grammar doesn't own, verbatim (`<!-- foo:bar -->`), in order. */
+  unknown: string[];
+}
+
+/** Bounds for a size segment — larger values are treated as plain text. */
+export const MEDIA_MAX_DIMENSION = 16384;
+
+const SIZE_SEGMENT = /^(\d{1,5})(?:x(\d{1,5}))?$/;
+const DIRECTIVE = /<!--\s*([a-z][a-z0-9-]*)\s*:\s*([\s\S]*?)\s*-->/gi;
+
+function parseSize(segment: string): { width: number; height?: number } | null {
+  const match = SIZE_SEGMENT.exec(segment.trim());
+  if (!match) {
+    return null;
+  }
+  const width = Number(match[1]);
+  const height = match[2] === undefined ? undefined : Number(match[2]);
+  if (width < 1 || width > MEDIA_MAX_DIMENSION) {
+    return null;
+  }
+  if (height !== undefined && (height < 1 || height > MEDIA_MAX_DIMENSION)) {
+    return null;
+  }
+  return height === undefined ? { width } : { width, height };
+}
+
+/**
+ * Split an embed's inner text on its pipes. `\|` (how a pipe is written inside a
+ * markdown table cell) is a separator too; whether it was used is reported so a
+ * reformat can keep the table intact.
+ */
+function splitPipes(inner: string): { parts: string[]; escaped: boolean } {
+  const parts: string[] = [];
+  let current = "";
+  let escaped = false;
+  for (let i = 0; i < inner.length; i++) {
+    const char = inner[i];
+    if (char === "\\" && inner[i + 1] === "|") {
+      parts.push(current);
+      current = "";
+      escaped = true;
+      i++;
+      continue;
+    }
+    if (char === "|") {
+      parts.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  parts.push(current);
+  return { parts, escaped };
+}
+
+/** Parse the text between `![[` and `]]`. */
+export function parseEmbedTarget(inner: string): EmbedTarget {
+  const { parts, escaped } = splitPipes(inner);
+  const head = (parts[0] ?? "").trim();
+  const hash = head.indexOf("#");
+  const target = hash >= 0 ? head.slice(0, hash).trim() : head;
+  const fragment = hash >= 0 ? head.slice(hash + 1).trim() : "";
+
+  const segments = parts.slice(1);
+  // The LAST segment that reads as a size is the size (Obsidian's rule when an
+  // alias and a size are both present); the first other one is the alias.
+  let sizeIndex = -1;
+  for (let i = segments.length - 1; i >= 0; i--) {
+    if (parseSize(segments[i] ?? "")) {
+      sizeIndex = i;
+      break;
+    }
+  }
+  const size = sizeIndex >= 0 ? parseSize(segments[sizeIndex] ?? "") : null;
+  const others = segments.filter((_, i) => i !== sizeIndex);
+  const [alt, ...extra] = others;
+
+  return {
+    target,
+    fragment,
+    ...(alt !== undefined && alt.trim() !== "" ? { alt: alt.trim() } : {}),
+    ...(size ? { width: size.width } : {}),
+    ...(size?.height !== undefined ? { height: size.height } : {}),
+    extra: alt !== undefined && alt.trim() === "" ? ["", ...extra] : extra,
+    escapedPipes: escaped,
+  };
+}
+
+/** Canonical inner text for an embed (the part between `![[` and `]]`). */
+export function formatEmbedTarget(value: EmbedTarget): string {
+  const pipe = value.escapedPipes ? "\\|" : "|";
+  let inner = value.target;
+  if (value.fragment) {
+    inner += `#${value.fragment}`;
+  }
+  const segments: string[] = [];
+  if (value.alt) {
+    segments.push(sanitizeSegment(value.alt));
+  }
+  segments.push(...value.extra);
+  const size = formatSize(value.width, value.height);
+  if (size) {
+    segments.push(size);
+  }
+  for (const segment of segments) {
+    inner += pipe + segment;
+  }
+  return inner;
+}
+
+/** `480`, `640x360`, or empty when there is no width. */
+export function formatSize(width?: number, height?: number): string {
+  if (!width || width < 1) {
+    return "";
+  }
+  const w = Math.min(MEDIA_MAX_DIMENSION, Math.round(width));
+  if (!height || height < 1) {
+    return String(w);
+  }
+  return `${w}x${Math.min(MEDIA_MAX_DIMENSION, Math.round(height))}`;
+}
+
+/**
+ * For `![[youtube:url|…]]` / `![[iframe:url|…]]`: everything after the URL is a
+ * caption, except a trailing size segment (`|640x360`). Older notes carry only a
+ * caption, so it keeps any pipes it had.
+ */
+export function splitCaptionAndSize(rest: string | undefined): {
+  caption: string;
+  width?: number;
+  height?: number;
+} {
+  if (!rest) {
+    return { caption: "" };
+  }
+  const segments = rest.split("|");
+  const size = segments.length > 0 ? parseSize(segments[segments.length - 1] ?? "") : null;
+  if (size) {
+    segments.pop();
+  }
+  return {
+    caption: segments.join("|").trim(),
+    ...(size ? { width: size.width } : {}),
+    ...(size?.height !== undefined ? { height: size.height } : {}),
+  };
+}
+
+// A segment may not contain the characters that end it or the embed — nor end
+// in a backslash, which would turn the next separator into an escaped `\|`.
+function sanitizeSegment(value: string): string {
+  return value.replace(/[|\]\r\n]+/g, " ").replace(/[\s\\]+$/, "").trim();
+}
+
+/**
+ * Parse the whitespace-separated run of `<!-- key:value -->` comments after an
+ * embed. Returns null when anything other than comments is there (then the line
+ * isn't a media embed with directives at all).
+ */
+export function parseMediaDirectives(trailing: string): MediaDirectives | null {
+  const result: MediaDirectives = { unknown: [] };
+  const text = trailing.trim();
+  if (!text) {
+    return result;
+  }
+  DIRECTIVE.lastIndex = 0;
+  let last = 0;
+  let match: RegExpExecArray | null;
+  while ((match = DIRECTIVE.exec(text))) {
+    if (text.slice(last, match.index).trim() !== "") {
+      return null;
+    }
+    const key = (match[1] ?? "").toLowerCase();
+    const value = match[2] ?? "";
+    if (key === "align" && isAlignment(value.trim().toLowerCase())) {
+      result.align = value.trim().toLowerCase() as MediaAlignment;
+    } else if (key === "caption") {
+      result.caption = decodeDirectiveValue(value);
+    } else {
+      result.unknown.push(match[0]);
+    }
+    last = DIRECTIVE.lastIndex;
+  }
+  return text.slice(last).trim() === "" ? result : null;
+}
+
+/** Canonical directive text (leading space included), or empty. */
+export function formatMediaDirectives(value: MediaDirectives): string {
+  const parts: string[] = [];
+  if (value.align) {
+    parts.push(`<!-- align:${value.align} -->`);
+  }
+  if (value.caption !== undefined && value.caption.trim() !== "") {
+    parts.push(`<!-- caption:${encodeDirectiveValue(value.caption)} -->`);
+  }
+  parts.push(...value.unknown);
+  return parts.length > 0 ? ` ${parts.join(" ")}` : "";
+}
+
+function isAlignment(value: string): value is MediaAlignment {
+  return value === "left" || value === "center" || value === "right";
+}
+
+// A comment can't contain `-->` (or begin a new one): encode the few characters
+// that would break it, and fold newlines — a caption is one line.
+function encodeDirectiveValue(value: string): string {
+  return value
+    .replace(/[\r\n]+/g, " ")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .trim();
+}
+
+function decodeDirectiveValue(value: string): string {
+  return value
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .trim();
+}
+
+/** Coarse media family of a target, by extension. */
+export type MediaKind = "image" | "video" | "audio" | "pdf" | "file";
+
+const IMAGE = /\.(?:png|jpe?g|gif|webp|svg|avif|bmp|ico|heic|heif|tiff?)$/i;
+const VIDEO = /\.(?:mp4|webm|mov|m4v|ogv|mkv|avi)$/i;
+const AUDIO = /\.(?:mp3|wav|ogg|oga|opus|m4a|flac|aac|weba)$/i;
+const PDF = /\.pdf$/i;
+const HAS_EXTENSION = /\.[a-z0-9]{1,8}$/i;
+
+/** Classify a target by its extension. */
+export function classifyMedia(target: string): MediaKind {
+  if (IMAGE.test(target)) return "image";
+  if (VIDEO.test(target)) return "video";
+  if (AUDIO.test(target)) return "audio";
+  if (PDF.test(target)) return "pdf";
+  return "file";
+}
+
+/**
+ * Whether a target names a file (`x.ext`) rather than a note (`My Note`). Only
+ * file targets become inline embeds mid-paragraph; a bare `![[Note]]` there is
+ * left as text for the transclusion/wikilink syntaxes to own.
+ */
+export function isFileTarget(target: string): boolean {
+  return HAS_EXTENSION.test(target.trim()) && !target.includes(":");
+}
diff --git a/packages/luthor/src/core/styles.css b/packages/luthor/src/core/styles.css
index 69405734..bb7d9043 100644
--- a/packages/luthor/src/core/styles.css
+++ b/packages/luthor/src/core/styles.css
@@ -2743,11 +2743,168 @@
 	position: relative;
 	border: 2px solid var(--luthor-border);
 	border-radius: 12px;
-	overflow: hidden;
+	/* Not overflow:hidden — the resize handles sit on the edge and must stay
+	   whole and hittable. The rounding is applied to the media itself. */
 	background: var(--luthor-bg);
 	transition: border-color var(--luthor-theme-transition), box-shadow var(--luthor-theme-transition), background-color var(--luthor-theme-transition);
 }
 
+.luthor-media-embed-shell > :is(img, iframe, video),
+.luthor-media-embed-shell > a > img {
+	border-radius: 10px;
+}
+
+/*
+ * Attachments — MediaFrame (`![[file.ext|480]]`).
+ *
+ * The frame's width comes inline (`min(Npx, 100%)`) and the element's shape from
+ * `aspect-ratio`, so the box is reserved before the file loads. Everything is a
+ * token; hosts restyle through the same variables.
+ */
+.luthor-media {
+	margin: 0.75rem 0;
+	max-width: 100%;
+}
+
+.luthor-media--block {
+	display: block;
+}
+
+.luthor-media__frame {
+	max-width: 100%;
+	position: relative;
+}
+
+.luthor-media--align-center .luthor-media__frame,
+.luthor-media--align-center .luthor-media__caption {
+	margin-left: auto;
+	margin-right: auto;
+}
+
+.luthor-media--align-right .luthor-media__frame {
+	margin-left: auto;
+}
+
+.luthor-media--align-center .luthor-media__caption {
+	text-align: center;
+}
+
+.luthor-media--align-right .luthor-media__caption {
+	text-align: right;
+}
+
+.luthor-media__element {
+	display: block;
+	max-width: 100%;
+	border-radius: 10px;
+	background: var(--luthor-muted);
+}
+
+.luthor-media--inline {
+	display: inline-block;
+	vertical-align: bottom;
+	max-width: 100%;
+	margin: 0 0.15em;
+}
+
+.luthor-media__caption {
+	margin-top: 0.4rem;
+	font-size: 0.9em;
+	color: var(--luthor-muted-fg);
+}
+
+.luthor-media__card {
+	display: flex;
+	flex-direction: column;
+	gap: 0.5rem;
+	padding: 0.65rem 0.75rem;
+	border: 1px solid var(--luthor-border);
+	border-radius: 10px;
+	background: var(--luthor-bg);
+	max-width: 100%;
+	box-sizing: border-box;
+}
+
+.luthor-media__card--audio audio {
+	width: 100%;
+}
+
+.luthor-media__card-link {
+	display: flex;
+	align-items: center;
+	gap: 0.75rem;
+	color: inherit;
+	text-decoration: none;
+	min-width: 0;
+}
+
+.luthor-media__card-icon {
+	flex: none;
+	display: inline-grid;
+	place-items: center;
+	min-width: 2.75rem;
+	height: 2.75rem;
+	padding: 0 0.35rem;
+	border-radius: 8px;
+	background: var(--luthor-muted);
+	color: var(--luthor-muted-fg);
+	font: 600 0.72rem / 1 ui-monospace, SFMono-Regular, monospace;
+	letter-spacing: 0.04em;
+}
+
+.luthor-media__card-title {
+	display: flex;
+	flex-direction: column;
+	min-width: 0;
+}
+
+.luthor-media__card-name {
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+	color: var(--luthor-fg);
+}
+
+.luthor-media__card-detail {
+	font-size: 0.85em;
+	color: var(--luthor-muted-fg);
+}
+
+.luthor-media__error {
+	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
+	justify-content: space-between;
+	gap: 0.5rem;
+	min-height: 3rem;
+	padding: 0.65rem 0.75rem;
+	border: 1px dashed var(--luthor-border-hover);
+	border-radius: 10px;
+	background: var(--luthor-muted);
+	color: var(--luthor-muted-fg);
+}
+
+.luthor-media__error-actions {
+	display: inline-flex;
+	gap: 0.4rem;
+}
+
+.luthor-media__button {
+	border: 1px solid var(--luthor-border);
+	border-radius: 6px;
+	background: var(--luthor-bg);
+	color: var(--luthor-fg);
+	padding: 0.2rem 0.6rem;
+	font: inherit;
+	font-size: 0.85em;
+	text-decoration: none;
+	cursor: pointer;
+}
+
+.luthor-media__button:hover {
+	border-color: var(--luthor-border-hover);
+}
+
 .luthor-media-embed-shell:hover {
 	border-color: var(--luthor-border-active);
 }
diff --git a/packages/luthor/src/presets/papyra-collab/papyraCollab.test.ts b/packages/luthor/src/presets/papyra-collab/papyraCollab.test.ts
index ff4949f0..b886f0f1 100644
--- a/packages/luthor/src/presets/papyra-collab/papyraCollab.test.ts
+++ b/packages/luthor/src/presets/papyra-collab/papyraCollab.test.ts
@@ -30,6 +30,8 @@ const FIXTURES = [
   "| a | b |\n| --- | --- |\n| 1 | 2 |",
   "See [[Project Plan]] and ![[Meeting#^abc123]].\n\nAnchored block ^keep0001",
   "![[diagram.png]]\n\nText after embed.",
+  // Sized, aliased, aligned, captioned and inline media (the media grammar).
+  "![[beach.jpg|Beach|640]] <!-- align:center --> <!-- caption:Dusk -->\n\nSee ![[ticket.pdf#page=2]] inline.\n\n![[youtube:https://www.youtube-nocookie.com/embed/xyz|Recap|800x450]]",
 ];
 
 /** Normalize once through the bridge — the stable form every replica must hit. */
@@ -102,6 +104,32 @@ describe("papyra headless collaboration", () => {
     expect(client.getMarkdown()).not.toContain("[Unsupported");
   });
 
+  it("a peer's resize and caption reach every replica and the saved markdown", () => {
+    const server = replica();
+    server.setMarkdown("Intro\n\n![[beach.jpg]]\n\nOutro");
+    const alice = replica(server.doc);
+    const bob = replica(server.doc);
+
+    alice.editor.update(
+      () => {
+        const embed = $getRoot().getChildren().find((n) => n.getType() === "fileEmbed") as unknown as {
+          setSize(w: number): void;
+          setCaption(c: string): void;
+        };
+        embed.setSize(480);
+        embed.setCaption("Dusk");
+      },
+      { discrete: true },
+    );
+    connect(alice.doc, server.doc);
+    connect(server.doc, bob.doc);
+
+    const expected = "Intro\n\n![[beach.jpg|480]] <!-- caption:Dusk -->\n\nOutro";
+    expect(alice.getMarkdown()).toBe(expected);
+    expect(server.getMarkdown()).toBe(expected);
+    expect(bob.getMarkdown()).toBe(expected);
+  });
+
   it("reloads a persisted room state without changing the body", () => {
     const server = replica();
     server.setMarkdown(FIXTURES[1]!);
diff --git a/packages/luthor/src/presets/papyra/adapter.ts b/packages/luthor/src/presets/papyra/adapter.ts
index 45454df0..67f20c99 100644
--- a/packages/luthor/src/presets/papyra/adapter.ts
+++ b/packages/luthor/src/presets/papyra/adapter.ts
@@ -24,7 +24,12 @@
  * it should not show.
  */
 
-import { createContext, useContext } from "react";
+import { createContext, useContext, type ReactNode } from "react";
+import type {
+  FileExpansionContext,
+  MediaMeta,
+  MediaUrlOptions,
+} from "@lyfie/luthor-headless";
 
 /** A reference to a note, by human title and/or stable id. */
 export interface PapyraNoteRef {
@@ -94,7 +99,21 @@ export interface PapyraEditorAdapter {
    * browser can load. Synchronous so embeds can render their first frame without
    * a loading flash; the host typically returns a stable CDN/API URL.
    */
-  resolveMediaUrl(filename: string): string;
+  resolveMediaUrl(filename: string, options?: MediaUrlOptions): string;
+  /**
+   * Cached metadata for a media file (size, intrinsic dimensions, whether a
+   * thumbnail/poster exists) so embeds reserve their box before loading. Return
+   * the same object for the same file until it changes; `undefined` while
+   * unknown (and start a lookup). Optional.
+   */
+  getMediaMeta?(filename: string): MediaMeta | null | undefined;
+  /** Notify embeds that metadata arrived. Returns an unsubscribe function. Optional. */
+  subscribeMediaMeta?(listener: () => void): () => void;
+  /**
+   * Extra content beneath a file card (e.g. an inline PDF viewer). Optional;
+   * return `null` for files the host has nothing to add to.
+   */
+  renderFileExpansion?(context: FileExpansionContext): ReactNode;
   /**
    * Persist a dropped or pasted file and resolve to the stored filename the
    * editor should reference as `![[filename]]`. The host owns the upload endpoint
diff --git a/packages/luthor/src/presets/papyra/embeds.ts b/packages/luthor/src/presets/papyra/embeds.ts
index d7ecbef2..524d18eb 100644
--- a/packages/luthor/src/presets/papyra/embeds.ts
+++ b/packages/luthor/src/presets/papyra/embeds.ts
@@ -42,6 +42,7 @@ import {
   BLOCK_ANCHOR_MARKDOWN_TRANSFORMER,
   CALLOUT_MARKDOWN_TRANSFORMER,
   FILE_EMBED_MARKDOWN_TRANSFORMER,
+  FILE_EMBED_INLINE_MARKDOWN_TRANSFORMER,
   IFRAME_EMBED_MARKDOWN_TRANSFORMER,
   SAVED_CARD_MARKDOWN_TRANSFORMER,
   TRANSCLUSION_MARKDOWN_TRANSFORMER,
@@ -206,9 +207,11 @@ export const PAPYRA_EMBED_NODES: NonNullable<
  * 2. **YouTube** (`![[youtube:url]]`) — the `youtube:` prefix, before file embed.
  * 3. **Iframe** (`![[iframe:url]]`) — the `iframe:` prefix, before file embed.
  * 4. **Transclusion** (`![[Note#^id]]`) — the `#^` pattern, also before file embed.
- * 5. **File embed** (`![[file.ext]]`) — block-level media.
+ * 5. **File embed** (`![[file.ext|480]] <!-- align:center -->`) — block-level media.
  * 6. **Block anchor** (`^uuid`) — trailing inline marker.
- * 7. **Wikilink** (`[[Note]]`) — inline link.
+ * 7. **Inline file embed** (`text ![[file.ext]] text`) — before the wikilink, whose
+ *    `[[…]]` would otherwise see the embed's brackets.
+ * 8. **Wikilink** (`[[Note]]`) — inline link.
  *
  * The **callout** (`> [!transcript]`) is a multiline-element transformer with a
  * distinct opening pattern, so it is independent of the ordering above; it is
@@ -227,6 +230,7 @@ export const PAPYRA_EMBED_TRANSFORMERS: NonNullable<
   TRANSCLUSION_MARKDOWN_TRANSFORMER,
   FILE_EMBED_MARKDOWN_TRANSFORMER,
   BLOCK_ANCHOR_MARKDOWN_TRANSFORMER,
+  FILE_EMBED_INLINE_MARKDOWN_TRANSFORMER,
   WIKILINK_MARKDOWN_TRANSFORMER,
 ];
 
@@ -240,7 +244,14 @@ export function createPapyraEmbedResolvers(
   adapter: PapyraEditorAdapter,
 ): EmbedResolvers {
   return {
-    resolveMediaUrl: (target) => adapter.resolveMediaUrl(target),
+    resolveMediaUrl: (target, options) => adapter.resolveMediaUrl(target, options),
+    getMediaMeta: adapter.getMediaMeta ? (target) => adapter.getMediaMeta!(target) : undefined,
+    subscribeMediaMeta: adapter.subscribeMediaMeta
+      ? (listener) => adapter.subscribeMediaMeta!(listener)
+      : undefined,
+    renderFileExpansion: adapter.renderFileExpansion
+      ? (context) => adapter.renderFileExpansion!(context)
+      : undefined,
     openLink: (target) => adapter.openNote({ title: target }),
     resolveBlock: adapter.resolveBlock
       ? (note, blockId) => adapter.resolveBlock!({ note, blockId })
diff --git a/packages/luthor/src/presets/papyra/mediaGolden.test.tsx b/packages/luthor/src/presets/papyra/mediaGolden.test.tsx
new file mode 100644
index 00000000..4c5ddc31
--- /dev/null
+++ b/packages/luthor/src/presets/papyra/mediaGolden.test.tsx
@@ -0,0 +1,302 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+/*
+ * The media golden corpus: every way a note can embed media, through the exact
+ * pipelines Papyra uses — the collaboration server's (papyraMarkdownToJSON →
+ * papyraJSONToMarkdown) and the browser editor's (setMarkdown → getMarkdown).
+ *
+ * The rule under test is the one that keeps notes safe: opening and saving a
+ * note never rewrites an embed nobody touched. Only an actual edit (a resize, a
+ * caption, an alignment) changes its text, and then to the canonical form.
+ */
+
+import { render, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import {
+  $isFileEmbedNode,
+  $isYouTubeEmbedNode,
+  FileEmbedNode,
+} from "@lyfie/luthor-headless";
+import { $getRoot, $isElementNode, createEditor, type LexicalNode } from "lexical";
+
+const $isImageNode = (node: LexicalNode) => node.getType() === "image";
+
+vi.hoisted(() => {
+  const win = globalThis as {
+    InputEvent?: { prototype: { getTargetRanges?: () => StaticRange[] } };
+  };
+  if (win.InputEvent && !win.InputEvent.prototype.getTargetRanges) {
+    win.InputEvent.prototype.getTargetRanges = () => [];
+  }
+});
+
+import { PapyraEditor, type PapyraEditorRef } from "./PapyraEditor";
+import {
+  getPapyraCollabNodes,
+  papyraJSONToMarkdown,
+  papyraMarkdownToJSON,
+} from "../papyra-collab";
+
+const UNCHANGED: [string, string][] = [
+  // ── Block file embeds ──
+  ["plain", "![[a.png]]"],
+  ["width", "![[a.png|300]]"],
+  ["box", "![[a.png|300x200]]"],
+  ["alt", "![[a.png|Alt]]"],
+  ["alt + width", "![[a.png|Alt|300]]"],
+  ["width + alt (non-canonical order)", "![[a.png|300|Alt]]"],
+  ["padded alt", "![[a.png| spaced alt |300]]"],
+  ["empty alt segment", "![[a.png||300]]"],
+  ["aligned", "![[a.png|300]] <!-- align:center -->"],
+  ["aligned + captioned", "![[a.png|300]] <!-- align:center --> <!-- caption:Dusk over the bay -->"],
+  ["directives out of order", "![[a.png]] <!-- caption:Hi --> <!-- align:right -->"],
+  ["unknown directive", "![[a.png]] <!-- foo:bar -->"],
+  ["odd directive spacing", "![[a.png]]   <!--align:left-->"],
+  ["pdf page", "![[a.pdf#page=3]]"],
+  ["pdf page + alias", "![[a.pdf#page=3|Report]]"],
+  ["docx", "![[doc.docx]]"],
+  ["zip", "![[x.zip]]"],
+  ["video box", "![[clip.mp4|640x360]]"],
+  ["audio", "![[song.mp3]]"],
+  ["spaces and parens", "![[my photo (1).png]]"],
+  ["unicode name", "![[фото-снимок.png]]"],
+  ["upper-case name", "![[A.PNG]]"],
+  ["folder path", "![[attachments/sub/deep.png]]"],
+  ["note embed", "![[My Note]]"],
+  ["heading embed", "![[Note#Heading]]"],
+  ["transclusion", "![[Note#^abcd1234]]"],
+  ["oversize number is an alias", "![[a.png|999999]]"],
+  // ── Inline ──
+  ["mid-paragraph", "before ![[inline.gif]] after"],
+  ["two inline", "two ![[a.png]] ![[b.png|40]] inline"],
+  ["in a list item", "- item ![[a.png]]"],
+  ["in a quote", "> quote ![[a.png]]"],
+  ["in an ordered list", "1. step ![[a.png|120]]"],
+  ["note embed mid-text stays text", "text ![[My Note]] text"],
+  ["next to formatting", "**bold** ![[a.png]] *it*"],
+  ["next to a wikilink", "see [[Other note]] and ![[a.png]]"],
+  ["embed then text", "![[a.png]] trailing text"],
+  ["in a heading", "# Title ![[a.png]]"],
+  // Table cells import as plain text (as wikilinks there do); an Obsidian-style
+  // escaped pipe must come back untouched.
+  ["in a table cell", "| pic | note |\n| --- | --- |\n| ![[a.png\\|40]] | x |"],
+  // ── Other embeds ──
+  ["youtube", "![[youtube:https://www.youtube-nocookie.com/embed/abc123]]"],
+  ["youtube caption", "![[youtube:https://www.youtube-nocookie.com/embed/abc123|My talk]]"],
+  ["youtube caption + size", "![[youtube:https://www.youtube-nocookie.com/embed/abc123|My talk|800x450]]"],
+  ["youtube size", "![[youtube:https://www.youtube-nocookie.com/embed/abc123|800x450]]"],
+  ["iframe", "![[iframe:https://example.com/page]]"],
+  ["iframe caption + size", "![[iframe:https://example.com/page|Docs|800x600]]"],
+  ["saved card", "![[card:https://example.com/]]"],
+  // ── Markdown images ──
+  ["api image", "![alt](/api/media/x.png)"],
+  ["api image no alt", "![](/api/media/x.png)"],
+  ["obsidian sized external", "![alt|300](https://example.com/a.png)"],
+  ["obsidian boxed external", "![alt|300x200](https://example.com/a.png)"],
+  ["captioned image", "![alt](https://example.com/a.png \"caption\")"],
+  // ── Surroundings ──
+  ["between paragraphs", "Intro\n\n![[a.png|480]] <!-- align:center -->\n\nOutro"],
+  ["in a code fence", "```\n![[a.png]]\n```"],
+  ["in inline code", "use `![[a.png]]` to embed"],
+  ["empty embed stays text", "![[]]"],
+  [
+    "a whole note",
+    [
+      "# Trip",
+      "",
+      "Day one ![[ticket.pdf#page=2|ticket]] was long.",
+      "",
+      "![[beach.jpg|640]] <!-- align:center --> <!-- caption:The beach -->",
+      "",
+      "- packed ![[list.txt]]",
+      "- watched ![[youtube:https://www.youtube-nocookie.com/embed/xyz|Recap]]",
+      "",
+      "![[clip.mov|640x360]]",
+    ].join("\n"),
+  ],
+];
+
+function serverRoundTrip(markdown: string): string {
+  return papyraJSONToMarkdown(papyraMarkdownToJSON(markdown));
+}
+
+describe("media golden corpus — collaboration server pipeline", () => {
+  it.each(UNCHANGED)("%s round-trips byte for byte", (_name, source) => {
+    expect(serverRoundTrip(source)).toBe(source);
+    // …and stays put on a second pass (save → reopen → save).
+    expect(serverRoundTrip(serverRoundTrip(source))).toBe(source);
+  });
+
+  it("parses sizes, alt, fragments and directives into the node", () => {
+    const doc = JSON.stringify(
+      papyraMarkdownToJSON("![[a.pdf#page=3|Report|640x480]] <!-- align:right --> <!-- caption:Q3 -->"),
+    );
+    expect(doc).toContain('"type":"fileEmbed"');
+    expect(doc).toContain('"target":"a.pdf"');
+    expect(doc).toContain('"fragment":"page=3"');
+    expect(doc).toContain('"alt":"Report"');
+    expect(doc).toContain('"width":640');
+    expect(doc).toContain('"height":480');
+    expect(doc).toContain('"align":"right"');
+    expect(doc).toContain('"caption":"Q3"');
+  });
+
+  it("claims mid-paragraph file embeds as inline nodes, keeping the text", () => {
+    const doc = JSON.stringify(papyraMarkdownToJSON("before ![[inline.gif]] after"));
+    expect(doc).toContain('"inline":true');
+    expect(doc).toContain("before ");
+    expect(doc).toContain(" after");
+  });
+});
+
+// ── Edits ─────────────────────────────────────────────────────────────────────
+
+/** Parse into a headless editor, apply `edit` to the first matching node, export. */
+function editFirst(markdown: string, match: (node: LexicalNode) => boolean, edit: (node: LexicalNode) => void): string {
+  const editor = createEditor({ nodes: getPapyraCollabNodes(), onError: (e) => { throw e; } });
+  editor.setEditorState(editor.parseEditorState(JSON.stringify(papyraMarkdownToJSON(markdown))));
+  const walk = (node: LexicalNode): LexicalNode | undefined => {
+    if (match(node)) return node;
+    if ($isElementNode(node)) {
+      for (const child of node.getChildren()) {
+        const hit = walk(child);
+        if (hit) return hit;
+      }
+    }
+    return undefined;
+  };
+  editor.update(
+    () => {
+      const found = walk($getRoot());
+      if (!found) throw new Error("no matching node");
+      edit(found);
+    },
+    { discrete: true },
+  );
+  return papyraJSONToMarkdown(editor.getEditorState().toJSON());
+}
+
+describe("media golden corpus — edits produce the canonical form", () => {
+  const file = (fn: (node: FileEmbedNode) => void) => (node: LexicalNode) => fn(node as FileEmbedNode);
+
+  it("a resize writes Obsidian's width", () => {
+    expect(editFirst("![[a.png]]", $isFileEmbedNode, file((n) => n.setSize(480)))).toBe("![[a.png|480]]");
+  });
+
+  it("a box resize writes WxH and keeps the alias", () => {
+    expect(editFirst("![[a.png|Sunset]]", $isFileEmbedNode, file((n) => n.setSize(640, 360)))).toBe(
+      "![[a.png|Sunset|640x360]]",
+    );
+  });
+
+  it("alignment and caption land as trailing directives, canonically ordered", () => {
+    const out = editFirst(
+      "![[a.png]] <!-- caption:Old --> <!-- keep:me -->",
+      $isFileEmbedNode,
+      file((n) => {
+        n.setAlign("center");
+        n.setCaption("A --> tricky <caption> & more");
+      }),
+    );
+    expect(out).toBe(
+      "![[a.png]] <!-- align:center --> <!-- caption:A --&gt; tricky &lt;caption&gt; &amp; more --> <!-- keep:me -->",
+    );
+    // …and read back exactly.
+    expect(JSON.stringify(papyraMarkdownToJSON(out))).toContain('"caption":"A --> tricky <caption> & more"');
+  });
+
+  it("clearing a size removes it", () => {
+    expect(editFirst("![[a.png|300]]", $isFileEmbedNode, file((n) => n.setSize(undefined)))).toBe("![[a.png]]");
+  });
+
+  it("replacing the file keeps size and directives", () => {
+    expect(
+      editFirst("![[old.png|300]] <!-- align:right -->", $isFileEmbedNode, file((n) => n.setTarget("new.png"))),
+    ).toBe("![[new.png|300]] <!-- align:right -->");
+  });
+
+  it("an inline embed resizes in place, without directives", () => {
+    expect(
+      editFirst("see ![[a.png]] here", $isFileEmbedNode, file((n) => {
+        n.setSize(40);
+        n.setAlign("center");
+      })),
+    ).toBe("see ![[a.png|40]] here");
+  });
+
+  it("a YouTube resize writes its size segment", () => {
+    expect(
+      editFirst(
+        "![[youtube:https://www.youtube-nocookie.com/embed/abc123|Talk]]",
+        $isYouTubeEmbedNode,
+        (n) => (n as unknown as { setPayload(p: object): void }).setPayload({ width: 800, height: 450 }),
+      ),
+    ).toBe("![[youtube:https://www.youtube-nocookie.com/embed/abc123|Talk|800x450]]");
+  });
+
+  it("an image resize writes Obsidian's alt-size", () => {
+    expect(
+      editFirst("![alt](https://example.com/a.png)", $isImageNode, (n) =>
+        (n as unknown as { setWidthAndHeight(w: number, h?: number): void }).setWidthAndHeight(300, undefined),
+      ),
+    ).toBe("![alt|300](https://example.com/a.png)");
+  });
+
+  it("reads version-1 JSON (a live room from before sizes existed)", () => {
+    const editor = createEditor({ nodes: getPapyraCollabNodes(), onError: (e) => { throw e; } });
+    editor.update(
+      () => {
+        const node = FileEmbedNode.importJSON({ type: "fileEmbed", version: 1, target: "a.png|300" } as never);
+        expect(node.__target).toBe("a.png");
+        expect(node.__width).toBe(300);
+        expect(node.getMarkdown()).toBe("![[a.png|300]]");
+      },
+      { discrete: true },
+    );
+  });
+});
+
+// ── The browser editor ────────────────────────────────────────────────────────
+
+async function mount() {
+  let handle: PapyraEditorRef | null = null;
+  const onChange = vi.fn();
+  render(
+    <PapyraEditor
+      defaultEditorView="visual"
+      blockAnchors="on-demand"
+      onChange={onChange}
+      onReady={(m) => {
+        handle = m;
+      }}
+    />,
+  );
+  await waitFor(() => expect(handle).not.toBeNull());
+  return { handle: handle as unknown as PapyraEditorRef, onChange };
+}
+
+// The browser's code-highlight plugin labels a bare fence with a language on
+// first render (a pre-existing, non-media behaviour tracked separately), so the
+// fence case is covered by the server pipeline above only.
+const BROWSER_CASES = UNCHANGED.filter(([name]) => name !== "in a code fence");
+
+describe("media golden corpus — browser editor", () => {
+  it.each(BROWSER_CASES)("%s survives setMarkdown → getMarkdown", async (_name, source) => {
+    const { handle, onChange } = await mount();
+    handle.setMarkdown(source);
+    const baseline = handle.getMarkdown();
+    expect(baseline).toBe(source);
+    // Rendering the embeds (decorators mounting, media metadata arriving) is
+    // never an edit: nothing reports a user change.
+    await new Promise((r) => setTimeout(r, 20));
+    const edits = onChange.mock.calls
+      .map(([e]) => e as { source: string; markdown: string })
+      .filter((e) => e.source === "user" && e.markdown !== baseline);
+    expect(edits).toEqual([]);
+  });
+});
diff --git a/packages/luthor/src/presets/papyra/papyra.css b/packages/luthor/src/presets/papyra/papyra.css
index cf06ba89..73c7bac4 100644
--- a/packages/luthor/src/presets/papyra/papyra.css
+++ b/packages/luthor/src/presets/papyra/papyra.css
@@ -89,13 +89,26 @@
 .luthor-preset-papyra .luthor-file-embed--video {
   display: block;
   max-width: 100%;
+}
+
+.luthor-preset-papyra .luthor-media--block {
   margin: 1rem 0;
 }
 
 .luthor-preset-papyra .luthor-file-embed--audio {
   display: block;
   width: 100%;
-  margin: 1rem 0;
+}
+
+.luthor-preset-papyra .luthor-media__card,
+.luthor-preset-papyra .luthor-media__error {
+  border-color: var(--papyra-accent-border, var(--papyra-accent-surface, currentColor));
+  font-family: var(--papyra-font-body, "Sora", ui-sans-serif, system-ui, sans-serif);
+}
+
+.luthor-preset-papyra .luthor-media__caption {
+  font-family: var(--papyra-font-body, "Sora", ui-sans-serif, system-ui, sans-serif);
+  color: var(--papyra-text-muted, var(--papyra-text, inherit));
 }
 
 .luthor-preset-papyra .luthor-file-embed--chip,
@@ -233,7 +246,6 @@
  */
 .luthor-preset-papyra .luthor-media-embed-shell {
   border-radius: 0.5em;
-  overflow: hidden;
   border: 1px solid
     var(--papyra-accent-border, var(--papyra-accent-surface, transparent));
 }

From e8dd1d61d94463690016eb71efb260f0523525ba Mon Sep 17 00:00:00 2001
From: Rahul Anand <41159815+rahulnsanand@users.noreply.github.com>
Date: Wed, 30 Sep 2026 20:57:42 +0530
Subject: [PATCH 2/2] feat: selection, resize, in-frame toolbar and a hardened
 upload pipeline

---
 .../core/FloatingToolbarExtension.tsx         |  47 +-
 .../embeds/EmbedResolverContext.tsx           |  50 ++
 .../extensions/embeds/FileDropUpload.test.ts  | 405 ++++++++++++++--
 .../embeds/FileDropUploadExtension.tsx        | 446 +++++++++++++-----
 .../src/extensions/embeds/FileEmbedNode.tsx   | 163 ++++++-
 .../embeds/UploadPlaceholder.test.tsx         | 116 +++++
 .../embeds/UploadPlaceholderNode.tsx          | 299 ++++++++++++
 .../headless/src/extensions/embeds/index.ts   |  18 +
 .../headless/src/extensions/embeds/uploads.ts | 106 +++++
 packages/headless/src/extensions/index.ts     |  27 ++
 .../extensions/media/EditorPromptContext.tsx  |  67 +++
 .../extensions/media/IframeEmbedExtension.tsx |   4 +-
 .../src/extensions/media/ImageExtension.tsx   | 194 ++------
 .../src/extensions/media/MediaFrame.tsx       | 295 +++++++++++-
 .../media/MediaInteraction.test.tsx           | 247 ++++++++++
 .../media/YouTubeEmbedExtension.tsx           |   8 +-
 .../headless/src/extensions/media/index.ts    |   3 +
 .../src/extensions/media/mediaSelection.ts    | 146 ++++++
 .../media/usePointerResize.test.tsx           | 141 ++++++
 .../src/extensions/media/usePointerResize.ts  | 140 ++++++
 packages/luthor/src/core/extensions.test.tsx  |  53 +++
 packages/luthor/src/core/extensions.tsx       |  88 +++-
 .../luthor/src/core/floating-toolbar.test.tsx |  53 +++
 packages/luthor/src/core/floating-toolbar.tsx |  55 ++-
 packages/luthor/src/core/styles.css           | 230 +++++++++
 packages/luthor/src/core/types.ts             |   2 +
 packages/luthor/src/core/ui.tsx               |   8 +-
 .../extensive/ExtensiveEditor.test.tsx        |   1 +
 .../src/presets/extensive/ExtensiveEditor.tsx |  47 +-
 .../src/presets/extensive/extensions.tsx      |   5 +-
 .../papyra-collab/papyraCollab.test.ts        |  29 ++
 .../src/presets/papyra/PapyraEditor.tsx       |   4 +
 packages/luthor/src/presets/papyra/adapter.ts |  17 +-
 .../luthor/src/presets/papyra/commands.ts     |  14 +-
 packages/luthor/src/presets/papyra/embeds.ts  |  18 +-
 35 files changed, 3188 insertions(+), 358 deletions(-)
 create mode 100644 packages/headless/src/extensions/embeds/UploadPlaceholder.test.tsx
 create mode 100644 packages/headless/src/extensions/embeds/UploadPlaceholderNode.tsx
 create mode 100644 packages/headless/src/extensions/embeds/uploads.ts
 create mode 100644 packages/headless/src/extensions/media/EditorPromptContext.tsx
 create mode 100644 packages/headless/src/extensions/media/MediaInteraction.test.tsx
 create mode 100644 packages/headless/src/extensions/media/mediaSelection.ts
 create mode 100644 packages/headless/src/extensions/media/usePointerResize.test.tsx
 create mode 100644 packages/headless/src/extensions/media/usePointerResize.ts
 create mode 100644 packages/luthor/src/core/extensions.test.tsx

diff --git a/packages/headless/src/extensions/core/FloatingToolbarExtension.tsx b/packages/headless/src/extensions/core/FloatingToolbarExtension.tsx
index dfede963..97e7a085 100644
--- a/packages/headless/src/extensions/core/FloatingToolbarExtension.tsx
+++ b/packages/headless/src/extensions/core/FloatingToolbarExtension.tsx
@@ -241,6 +241,13 @@ function FloatingToolbarPlugin<TCommands = any, TStates = any>({
   );
   const [selection, setSelection] = useState<RangeSelection | null>(null);
   const viewportRafIdRef = useRef<number | null>(null);
+  // The selection the person dismissed the bar for (an outside click). It stays
+  // dismissed for that selection — a collaborator's edit, a re-render, a scroll
+  // must not bring it back — until the selection itself changes.
+  const currentSignatureRef = useRef<string | null>(null);
+  const dismissedSignatureRef = useRef<string | null>(null);
+  // Which side of the selection the bar last sat on, for flip hysteresis.
+  const sideRef = useRef<"below" | "above">("below");
 
   const getSelectionAnchorRect = (element: HTMLElement): DOMRect => {
     const anchorElement = element.querySelector<HTMLElement>(
@@ -399,11 +406,21 @@ function FloatingToolbarPlugin<TCommands = any, TStates = any>({
       positionFromRight = false;
     }
 
-    /* Vertical bounds check */
-    if (y - toolbarHeight < scrollY) {
-      y = domRect.bottom + scrollY + offset.y;
-    } else if (y + toolbarHeight > scrollY + viewportHeight) {
-      y = domRect.top + scrollY - offset.y - toolbarHeight;
+    /* Vertical bounds check, with hysteresis */
+    const hysteresis = 8;
+    const belowY = domRect.bottom + scrollY + offset.y;
+    const aboveY = domRect.top + scrollY - offset.y - toolbarHeight;
+    const overflowBelow = belowY + toolbarHeight - (scrollY + viewportHeight);
+    const overflowAbove = scrollY - aboveY;
+    if (strategy !== "above") {
+      if (sideRef.current === "below" && overflowBelow > hysteresis && overflowAbove < 0) {
+        sideRef.current = "above";
+      } else if (sideRef.current === "above" && (overflowBelow < -hysteresis || overflowAbove > 0)) {
+        sideRef.current = "below";
+      }
+      y = sideRef.current === "above" ? aboveY : belowY;
+    } else if (y - toolbarHeight < scrollY) {
+      y = belowY;
     }
 
     return {
@@ -432,6 +449,19 @@ function FloatingToolbarPlugin<TCommands = any, TStates = any>({
         let newRect: DOMRect | null = null;
         let rangeSelection: RangeSelection | null = null;
 
+        const signature = $isRangeSelection(sel)
+          ? `r:${sel.anchor.key}:${sel.anchor.offset}:${sel.focus.key}:${sel.focus.offset}`
+          : $isNodeSelection(sel)
+            ? `n:${sel.getNodes().map((n) => n.getKey()).sort().join(",")}`
+            : null;
+        currentSignatureRef.current = signature;
+        if (signature !== dismissedSignatureRef.current) {
+          dismissedSignatureRef.current = null;
+        } else if (signature !== null) {
+          setIsVisible(false);
+          return;
+        }
+
         if ($isRangeSelection(sel) && !sel.isCollapsed()) {
           const domSelection = window.getSelection();
           if (domSelection && domSelection.rangeCount > 0) {
@@ -505,12 +535,13 @@ function FloatingToolbarPlugin<TCommands = any, TStates = any>({
     };
   }, [editor, config.debounceMs, createSelectionRect, extension]);
 
-  /* Hide callback */
-  const hide = () => {
+  /* Hide callback — sticks until the selection changes */
+  const hide = useCallback(() => {
+    dismissedSignatureRef.current = currentSignatureRef.current;
     setIsVisible(false);
     setSelectionRect(null);
     setSelection(null);
-  };
+  }, []);
 
   /* Require render function to be provided */
   if (!config.render) {
diff --git a/packages/headless/src/extensions/embeds/EmbedResolverContext.tsx b/packages/headless/src/extensions/embeds/EmbedResolverContext.tsx
index 4f6cf6cd..56e835dc 100644
--- a/packages/headless/src/extensions/embeds/EmbedResolverContext.tsx
+++ b/packages/headless/src/extensions/embeds/EmbedResolverContext.tsx
@@ -92,6 +92,47 @@ export interface FileExpansionContext {
   meta: MediaMeta | null | undefined;
 }
 
+/** An edit to an embedded attachment; `null` clears a field. */
+export interface MediaEdit {
+  target?: string;
+  width?: number | null;
+  height?: number | null;
+  align?: "left" | "center" | "right" | null;
+  caption?: string | null;
+  alt?: string | null;
+}
+
+/** What a media toolbar item acts on (see `mediaToolbar`). */
+export interface MediaToolbarContext {
+  target: string;
+  fragment: string;
+  /** `image`, `video`, `audio`, `pdf` or `file`. */
+  kind: string;
+  url: string;
+  meta: MediaMeta | null | undefined;
+  width?: number;
+  height?: number;
+  align?: "left" | "center" | "right";
+  caption?: string;
+  alt?: string;
+  /** Apply an edit to this embed (one undo step, one collaboration update). */
+  update: (edit: MediaEdit) => void;
+  /** Remove this embed from the document. */
+  remove: () => void;
+}
+
+/** One button in the media toolbar. */
+export interface MediaToolbarItem {
+  id: string;
+  /** Accessible name, also the tooltip. */
+  label: string;
+  /** Icon; the label is shown as text when there is none. */
+  icon?: ReactNode;
+  active?: boolean;
+  disabled?: boolean;
+  onSelect: () => void;
+}
+
 /**
  * Callbacks an embed node uses to reach host services. Every member is optional
  * so the nodes degrade gracefully when a host wires only part of the surface (or
@@ -119,6 +160,15 @@ export interface EmbedResolvers {
    * host renders on demand. Return `null` for files it has nothing to add to.
    */
   renderFileExpansion?: (context: FileExpansionContext) => ReactNode;
+  /**
+   * The toolbar shown on a selected attachment. `items` adds the host's own
+   * buttons (replace, download, …) after the built-in ones; `builtIn: false`
+   * drops the built-ins (align, size, caption, alt, open, remove).
+   */
+  mediaToolbar?: {
+    builtIn?: boolean;
+    items?: (context: MediaToolbarContext) => MediaToolbarItem[];
+  };
   /**
    * Navigate to a link target (the `Target` inside `[[Target]]`). Invoked when a
    * reader activates a wikilink. When omitted, the wikilink renders as inert
diff --git a/packages/headless/src/extensions/embeds/FileDropUpload.test.ts b/packages/headless/src/extensions/embeds/FileDropUpload.test.ts
index 72dfae3a..1a0d3f22 100644
--- a/packages/headless/src/extensions/embeds/FileDropUpload.test.ts
+++ b/packages/headless/src/extensions/embeds/FileDropUpload.test.ts
@@ -12,34 +12,47 @@ import {
   $createParagraphNode,
   $createTextNode,
   $getRoot,
+  PASTE_COMMAND,
   createEditor,
   type LexicalEditor,
 } from "lexical";
-import { FileDropUploadExtension } from "./FileDropUploadExtension";
+import {
+  FileDropUploadExtension,
+  isRichTextPaste,
+  MEDIA_DROP_EVENT,
+  type FileDropUploadConfig,
+  type UploadFileOptions,
+} from "./FileDropUploadExtension";
 import { $isFileEmbedNode, FileEmbedNode } from "./FileEmbedNode";
+import {
+  $isUploadPlaceholderNode,
+  UPLOAD_PLACEHOLDER_MARKDOWN_TRANSFORMER,
+  UploadPlaceholderNode,
+} from "./UploadPlaceholderNode";
+import { uploadRegistry } from "./uploads";
+import { jsonToMarkdown } from "../../core/markdown";
 
 const disposers: Array<() => void> = [];
-
 afterEach(() => {
-  while (disposers.length > 0) {
-    disposers.pop()?.();
-  }
+  while (disposers.length > 0) disposers.pop()?.();
 });
 
-function createHarness(uploadFile?: (file: File) => Promise<{ filename: string }>) {
+type Upload = NonNullable<FileDropUploadConfig["uploadFile"]>;
+
+function createHarness(config: FileDropUploadConfig = {}) {
   const editor = createEditor({
     namespace: "file-drop-upload-test",
-    nodes: [FileEmbedNode],
+    nodes: [FileEmbedNode, UploadPlaceholderNode],
     onError: (error) => {
       throw error;
     },
   });
-  const root = window.document.createElement("div");
+  const root = document.createElement("div");
   root.contentEditable = "true";
-  window.document.body.appendChild(root);
+  document.body.appendChild(root);
   editor.setRootElement(root);
 
-  const extension = new FileDropUploadExtension({ uploadFile });
+  const extension = new FileDropUploadExtension(config);
   const unregister = extension.register(editor);
   disposers.push(() => {
     unregister();
@@ -50,60 +63,378 @@ function createHarness(uploadFile?: (file: File) => Promise<{ filename: string }
     () => {
       const paragraph = $createParagraphNode();
       const text = $createTextNode("hello");
-      paragraph.append(text);
-      $getRoot().clear().append(paragraph);
+      paragraph.append(text, );
+      $getRoot().clear().append(paragraph, $createParagraphNode().append($createTextNode("after")));
       text.select(5, 5);
     },
     { discrete: true },
   );
 
-  return { editor, commands: extension.getCommands(editor) };
+  return { editor, extension, root, commands: extension.getCommands(editor) };
 }
 
-function embedTargets(editor: LexicalEditor): string[] {
+async function settle(editor: LexicalEditor) {
+  for (let i = 0; i < 5; i++) await Promise.resolve();
   editor.update(() => {}, { discrete: true });
+}
+
+/** Top-level blocks as short labels: text, `embed:x`, `uploading:x`. */
+function blocks(editor: LexicalEditor): string[] {
   return editor.getEditorState().read(() =>
     $getRoot()
       .getChildren()
-      .filter($isFileEmbedNode)
-      .map((node) => node.getTarget()),
+      .map((node) =>
+        $isFileEmbedNode(node)
+          ? `embed:${node.getTarget()}`
+          : $isUploadPlaceholderNode(node)
+            ? `uploading:${node.__name}`
+            : node.getTextContent(),
+      ),
   );
 }
 
-describe("uploadAndEmbedFile", () => {
-  it("uploads through the host callback and embeds the returned filename", async () => {
-    const uploadFile = vi.fn(async () => ({ filename: "photo.png" }));
-    const { editor, commands } = createHarness(uploadFile);
-    const file = new File(["x"], "photo.png", { type: "image/png" });
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+const file = (name: string, type = "image/png") => new File(["x"], name, { type });
+
+function clipboard(files: File[], data: Record<string, string> = {}) {
+  return {
+    files,
+    types: [...(files.length ? ["Files"] : []), ...Object.keys(data)],
+    getData: (type: string) => data[type] ?? "",
+  } as unknown as DataTransfer;
+}
+
+function paste(editor: LexicalEditor, data: DataTransfer): { handled: boolean; prevented: boolean } {
+  let prevented = false;
+  const event = { clipboardData: data, preventDefault: () => (prevented = true) } as unknown as ClipboardEvent;
+  let handled = false;
+  editor.update(() => {
+    handled = editor.dispatchCommand(PASTE_COMMAND, event);
+  }, { discrete: true });
+  return { handled, prevented };
+}
 
-    await commands.uploadAndEmbedFile(file);
+describe("upload pipeline", () => {
+  it("uploads through the host callback (with signal + progress) and embeds after the caret's block", async () => {
+    const uploadFile = vi.fn<Upload>(async () => ({ filename: "photo.png" }));
+    const { editor, commands } = createHarness({ uploadFile });
+    const picked = file("photo.png");
 
-    expect(uploadFile).toHaveBeenCalledWith(file);
-    expect(embedTargets(editor)).toEqual(["photo.png"]);
+    await commands.uploadAndEmbedFile(picked);
+    await settle(editor);
+
+    expect(uploadFile).toHaveBeenCalledWith(picked, expect.objectContaining({ signal: expect.any(AbortSignal), onProgress: expect.any(Function) }));
+    expect(blocks(editor)).toEqual(["hello", "embed:photo.png", "after"]);
   });
 
   it("sanitizes the filename before it reaches the body", async () => {
-    const { editor, commands } = createHarness(async () => ({ filename: "a[b]#c.png" }));
+    const { editor, commands } = createHarness({ uploadFile: async () => ({ filename: "a[b]#c.png" }) });
+    await commands.uploadAndEmbedFile(file("x.png"));
+    await settle(editor);
+    expect(blocks(editor)).toContain("embed:a-b--c.png");
+  });
 
-    await commands.uploadAndEmbedFile(new File(["x"], "x.png"));
+  it("places a batch in the order given, whatever order the uploads finish in", async () => {
+    const pending = new Map<string, ReturnType<typeof deferred<{ filename: string }>>>();
+    const uploadFile: Upload = (f) => {
+      const d = deferred<{ filename: string }>();
+      pending.set(f.name, d);
+      return d.promise;
+    };
+    const { editor, commands } = createHarness({ uploadFile });
+    const done = commands.uploadAndEmbedFiles([file("1.png"), file("2.png"), file("3.png")]);
+    await settle(editor);
+    expect(blocks(editor)).toEqual(["hello", "uploading:1.png", "uploading:2.png", "uploading:3.png", "after"]);
+
+    for (const name of ["3.png", "1.png", "2.png"]) {
+      pending.get(name)!.resolve({ filename: `stored-${name}` });
+      await settle(editor);
+    }
+    await done;
+    expect(blocks(editor)).toEqual(["hello", "embed:stored-1.png", "embed:stored-2.png", "embed:stored-3.png", "after"]);
+  });
 
-    expect(embedTargets(editor)).toEqual(["a-b--c.png"]);
+  it("runs at most three uploads at once", async () => {
+    let inFlight = 0;
+    let peak = 0;
+    const releases: Array<() => void> = [];
+    const uploadFile: Upload = (f) =>
+      new Promise((resolve) => {
+        inFlight++;
+        peak = Math.max(peak, inFlight);
+        releases.push(() => {
+          inFlight--;
+          resolve({ filename: f.name });
+        });
+      });
+    const { editor, commands } = createHarness({ uploadFile });
+    const done = commands.uploadAndEmbedFiles(["a", "b", "c", "d", "e", "f"].map((n) => file(`${n}.png`)));
+    await settle(editor);
+    expect(inFlight).toBe(3);
+    while (releases.length) {
+      releases.shift()!();
+      await settle(editor);
+    }
+    await done;
+    expect(peak).toBe(3);
+    expect(blocks(editor).filter((b) => b.startsWith("embed:"))).toHaveLength(6);
+  });
+
+  it("reports progress into the local registry, and never puts a blob: URL in the document", async () => {
+    let options: UploadFileOptions | null = null;
+    const d = deferred<{ filename: string }>();
+    const { editor, commands } = createHarness({
+      uploadFile: (_f, o) => {
+        options = o;
+        return d.promise;
+      },
+    });
+    const done = commands.uploadAndEmbedFile(file("big.png"));
+    await settle(editor);
+    options!.onProgress(0.42);
+    const id = editor.getEditorState().read(() => $getRoot().getChildren().find($isUploadPlaceholderNode)!.getUploadId());
+    expect(uploadRegistry.get(id)!.progress).toBeCloseTo(0.42);
+    expect(JSON.stringify(editor.getEditorState().toJSON())).not.toContain("blob:");
+    d.resolve({ filename: "big.png" });
+    await done;
+    expect(uploadRegistry.get(id)).toBeUndefined();
   });
 
-  it("rejects when the upload fails, so the caller can report it", async () => {
-    const { editor, commands } = createHarness(async () => {
-      throw new Error("offline");
+  it("a failure keeps the placeholder with Retry, reports once, and Retry completes it", async () => {
+    const onUploadError = vi.fn();
+    let attempt = 0;
+    const { editor, commands } = createHarness({
+      onUploadError,
+      uploadFile: async () => {
+        attempt++;
+        if (attempt === 1) throw new Error("offline");
+        return { filename: "photo.png" };
+      },
     });
+    await expect(commands.uploadAndEmbedFile(file("photo.png"))).rejects.toThrow("offline");
+    await settle(editor);
+    expect(onUploadError).toHaveBeenCalledTimes(1);
+    expect(blocks(editor)).toEqual(["hello", "uploading:photo.png", "after"]);
+    const id = editor.getEditorState().read(() => $getRoot().getChildren().find($isUploadPlaceholderNode)!.getUploadId());
+    expect(uploadRegistry.get(id)!.status).toBe("error");
+    expect(uploadRegistry.get(id)!.error).toBe("offline");
 
-    await expect(commands.uploadAndEmbedFile(new File(["x"], "x.png"))).rejects.toThrow("offline");
-    expect(embedTargets(editor)).toEqual([]);
+    uploadRegistry.get(id)!.retry();
+    await settle(editor);
+    await settle(editor);
+    expect(blocks(editor)).toEqual(["hello", "embed:photo.png", "after"]);
   });
 
-  it("rejects when no upload callback is configured", async () => {
-    const { commands } = createHarness();
+  it("cancel aborts the request", async () => {
+    let signal: AbortSignal | null = null;
+    const { editor, commands } = createHarness({
+      uploadFile: (_f, o) =>
+        new Promise((_resolve, reject) => {
+          signal = o.signal;
+          o.signal.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")));
+        }),
+    });
+    const done = commands.uploadAndEmbedFile(file("x.png"));
+    await settle(editor);
+    const id = editor.getEditorState().read(() => $getRoot().getChildren().find($isUploadPlaceholderNode)!.getUploadId());
+    uploadRegistry.get(id)!.cancel();
+    await expect(done).rejects.toMatchObject({ name: "AbortError" });
+    expect(signal!.aborted).toBe(true);
+  });
+
+  it("refuses files the host rejects before uploading them", async () => {
+    const uploadFile = vi.fn<Upload>();
+    const onUploadError = vi.fn();
+    const { editor, commands } = createHarness({
+      uploadFile,
+      onUploadError,
+      validateFile: (f) => (f.size > 0 && f.name.endsWith(".exe") ? "That kind of file can't be attached." : null),
+    });
+    await expect(commands.uploadAndEmbedFile(file("setup.exe", "application/octet-stream"))).rejects.toThrow(/can't be attached/);
+    expect(uploadFile).not.toHaveBeenCalled();
+    expect(onUploadError).toHaveBeenCalledTimes(1);
+    await settle(editor);
+    expect(blocks(editor)).toEqual(["hello", "after"]);
+  });
 
-    await expect(commands.uploadAndEmbedFile(new File(["x"], "x.png"))).rejects.toThrow(
-      /no uploadFile/,
-    );
+  it("never uploads into a read-only editor", async () => {
+    const uploadFile = vi.fn<Upload>(async () => ({ filename: "x.png" }));
+    const { editor, commands } = createHarness({ uploadFile });
+    editor.setEditable(false);
+    await expect(commands.uploadAndEmbedFile(file("x.png"))).rejects.toThrow(/read-only/);
+    expect(paste(editor, clipboard([file("x.png")])).handled).toBe(false);
+    expect(uploadFile).not.toHaveBeenCalled();
+  });
+
+  it("uses the host's current callback, not the one it was set up with", async () => {
+    const first = vi.fn<Upload>(async () => ({ filename: "old.png" }));
+    const second = vi.fn<Upload>(async () => ({ filename: "new.png" }));
+    const { editor, extension, commands } = createHarness({ uploadFile: first });
+    (extension as unknown as { config: FileDropUploadConfig }).config.uploadFile = second;
+    await commands.uploadAndEmbedFile(file("x.png"));
+    await settle(editor);
+    expect(first).not.toHaveBeenCalled();
+    expect(blocks(editor)).toContain("embed:new.png");
+  });
+
+  it("adds a paragraph after an upload at the very end, so typing can continue", async () => {
+    const { editor, commands } = createHarness({ uploadFile: async () => ({ filename: "x.png" }) });
+    editor.update(() => $getRoot().getLastChild()!.selectEnd(), { discrete: true });
+    await commands.uploadAndEmbedFile(file("x.png"));
+    await settle(editor);
+    expect(blocks(editor)).toEqual(["hello", "after", "embed:x.png", ""]);
+  });
+
+  it("no callback: the command refuses and pastes fall through", async () => {
+    const { editor, commands } = createHarness();
+    await expect(commands.uploadAndEmbedFile(file("x.png"))).rejects.toThrow(/no uploadFile/);
+    expect(paste(editor, clipboard([file("x.png")])).handled).toBe(false);
+  });
+});
+
+describe("paste policy", () => {
+  it.each([
+    ["a screenshot (files only)", [file("s.png")], {}, true],
+    ["a copied image (html is just <img>)", [file("i.png")], { "text/html": '<meta charset="utf-8"><img src="https://x/y.png">' }, true],
+    ["Word (formatted text + a picture of it)", [file("w.png")], { "text/html": "<html><body><p class=MsoNormal>Quarterly <b>report</b></p></body></html>", "text/plain": "Quarterly report" }, false],
+    ["Excel (a table + a picture of it)", [file("e.png")], { "text/html": "<table><tr><td>1</td><td>2</td></tr></table>" }, false],
+    ["Google Docs (text with an image inside)", [file("g.png")], { "text/html": '<b id="docs-internal"><p>Hello</p><img src="x"></b>' }, false],
+    ["a web page with several images", [file("p.png")], { "text/html": '<img src="a"><img src="b">' }, false],
+    ["RTF text from a desktop app", [file("r.png")], { "text/rtf": "{\\rtf1 hi}", "text/plain": "hi" }, false],
+    ["plain text only", [], { "text/plain": "hello" }, false],
+  ])("%s → upload: %s", async (_name, files, data, uploads) => {
+    const uploadFile = vi.fn<Upload>(async (f) => ({ filename: f.name }));
+    const { editor } = createHarness({ uploadFile });
+    const result = paste(editor, clipboard(files as File[], data as Record<string, string>));
+    await settle(editor);
+    expect(result.handled).toBe(uploads);
+    expect(result.prevented).toBe(uploads);
+    expect(uploadFile).toHaveBeenCalledTimes(uploads ? 1 : 0);
+  });
+
+  it("isRichTextPaste ignores comments, styles and non-breaking spaces", () => {
+    expect(isRichTextPaste(clipboard([], { "text/html": "<!--StartFragment--><style>p{}</style>&nbsp;<img src=a><!--EndFragment-->" }))).toBe(false);
+  });
+});
+
+describe("drop", () => {
+  function drop(target: HTMLElement, files: File[]) {
+    const event = new Event("drop", { bubbles: true, cancelable: true }) as DragEvent;
+    Object.defineProperty(event, "dataTransfer", { value: clipboard(files) });
+    Object.defineProperty(event, "clientX", { value: 10 });
+    Object.defineProperty(event, "clientY", { value: 10 });
+    target.dispatchEvent(event);
+    return event;
+  }
+
+  it("uploads dropped files, lets the event reach the host, and announces it", async () => {
+    const uploadFile = vi.fn<Upload>(async (f) => ({ filename: f.name }));
+    const { editor, root } = createHarness({ uploadFile });
+    const hostSawDrop = vi.fn();
+    const announced = vi.fn();
+    document.body.addEventListener("drop", hostSawDrop);
+    document.body.addEventListener(MEDIA_DROP_EVENT, announced);
+    const event = drop(root, [file("a.png"), file("b.png")]);
+    await settle(editor);
+    await settle(editor);
+    document.body.removeEventListener("drop", hostSawDrop);
+    document.body.removeEventListener(MEDIA_DROP_EVENT, announced);
+
+    expect(event.defaultPrevented).toBe(true);
+    expect(hostSawDrop).toHaveBeenCalledTimes(1);
+    expect(announced).toHaveBeenCalledTimes(1);
+    expect(uploadFile).toHaveBeenCalledTimes(2);
+    expect(blocks(editor).filter((b) => b.startsWith("embed:"))).toEqual(["embed:a.png", "embed:b.png"]);
+  });
+
+  it("lands where it was dropped: above or below the block under the pointer", async () => {
+    const uploadFile = vi.fn<Upload>(async (f) => ({ filename: f.name }));
+    const { editor, root } = createHarness({ uploadFile });
+    const blocksEl = Array.from(root.children) as HTMLElement[];
+    const after = blocksEl[1]!; // the "after" paragraph
+    after.getBoundingClientRect = () => ({ top: 100, height: 40, bottom: 140, left: 0, right: 500, width: 500, x: 0, y: 100, toJSON: () => ({}) }) as DOMRect;
+    const original = document.elementFromPoint;
+    document.elementFromPoint = () => after.firstChild as Element ?? after;
+    try {
+      // Lower half of "after": below it.
+      const low = new Event("drop", { bubbles: true, cancelable: true }) as DragEvent;
+      Object.defineProperty(low, "dataTransfer", { value: clipboard([file("below.png")]) });
+      Object.defineProperty(low, "clientX", { value: 10 });
+      Object.defineProperty(low, "clientY", { value: 130 });
+      root.dispatchEvent(low);
+      await settle(editor);
+      await settle(editor);
+      // Upper half: above it.
+      const high = new Event("drop", { bubbles: true, cancelable: true }) as DragEvent;
+      Object.defineProperty(high, "dataTransfer", { value: clipboard([file("above.png")]) });
+      Object.defineProperty(high, "clientX", { value: 10 });
+      Object.defineProperty(high, "clientY", { value: 105 });
+      root.dispatchEvent(high);
+      await settle(editor);
+      await settle(editor);
+    } finally {
+      document.elementFromPoint = original;
+    }
+    expect(blocks(editor)).toEqual(["hello", "embed:above.png", "after", "embed:below.png", ""]);
+  });
+
+  it("follows the editor to a new root element", async () => {
+    const uploadFile = vi.fn<Upload>(async (f) => ({ filename: f.name }));
+    const { editor, root } = createHarness({ uploadFile });
+    const next = document.createElement("div");
+    next.contentEditable = "true";
+    document.body.appendChild(next);
+    editor.setRootElement(next);
+    drop(root, [file("old-root.png")]);
+    drop(next, [file("new-root.png")]);
+    await settle(editor);
+    await settle(editor);
+    expect(uploadFile.mock.calls.map(([f]) => f.name)).toEqual(["new-root.png"]);
+    next.remove();
+  });
+
+  it("ignores drops into a read-only editor", async () => {
+    const uploadFile = vi.fn<Upload>();
+    const { editor, root } = createHarness({ uploadFile });
+    editor.setEditable(false);
+    const event = drop(root, [file("a.png")]);
+    await settle(editor);
+    expect(event.defaultPrevented).toBe(false);
+    expect(uploadFile).not.toHaveBeenCalled();
+  });
+});
+
+describe("placeholder in markdown", () => {
+  it("writes nothing, so a save mid-upload persists nothing for it", () => {
+    const doc = {
+      root: {
+        type: "root",
+        version: 1,
+        format: "",
+        indent: 0,
+        direction: null,
+        children: [
+          { type: "paragraph", version: 1, format: "", indent: 0, direction: null, textFormat: 0, textStyle: "", children: [{ type: "text", version: 1, text: "Intro", format: 0, detail: 0, mode: "normal", style: "" }] },
+          { type: "uploadPlaceholder", version: 1, uploadId: "up-1", name: "a.png", size: 1, kind: "image", startedAt: 1 },
+        ],
+      },
+    };
+    const md = jsonToMarkdown(doc, {
+      metadataMode: "none",
+      extraNodes: [UploadPlaceholderNode],
+      extraTransformers: [UPLOAD_PLACEHOLDER_MARKDOWN_TRANSFORMER],
+    });
+    expect(md.trim()).toBe("Intro");
+    expect(md).not.toContain("a.png");
+    expect(md).not.toContain("Unsupported");
   });
 });
diff --git a/packages/headless/src/extensions/embeds/FileDropUploadExtension.tsx b/packages/headless/src/extensions/embeds/FileDropUploadExtension.tsx
index 18ce9695..13b1e5a7 100644
--- a/packages/headless/src/extensions/embeds/FileDropUploadExtension.tsx
+++ b/packages/headless/src/extensions/embeds/FileDropUploadExtension.tsx
@@ -6,28 +6,43 @@
  */
 
 /*
- * Drop/paste → upload → `![[filename]]` pipeline.
+ * Drop / paste / pick → upload → `![[filename]]`.
  *
- * Intercepts file drops and clipboard pastes on the editor surface and
- * delegates them to a host-provided upload callback. On success the extension
- * inserts a {@link FileEmbedNode} referencing the stored filename, so the
- * body reads `![[filename]]` in markdown.
+ * The pipeline, and the promises it keeps:
  *
- * The paste handler is registered at HIGH priority so it runs before the
- * built-in ImageExtension paste handler — Papyra stores all media as named
- * files (`![[photo.png]]`), not inline base64 images.
+ * - **Where and in what order.** A drop lands where it was dropped; a paste or
+ *   a picked file at the caret. Every file gets a placeholder straight away, in
+ *   the order given, and each is replaced in place when its upload finishes —
+ *   so a batch always reads in the order it was dropped, whatever finishes
+ *   first.
+ * - **Honest progress.** At most three uploads run at once; each placeholder
+ *   shows progress, can be cancelled, and on failure offers Retry or Remove.
+ * - **Pastes do what the person meant.** Copying from Word, Excel or a web page
+ *   puts formatted text *and* a picture of it on the clipboard; the text wins.
+ *   Only a clipboard that is just files (a screenshot, a copied image) uploads.
+ * - **Never into a read-only note**, and never a `blob:` URL into the shared
+ *   document (the placeholder carries only a name and size).
+ * - **The host stays in charge.** The upload callback is read when a file is
+ *   uploaded, never captured at setup, so a host that swaps its callback is
+ *   honoured; errors go to `onUploadError`, once; nothing stops the drop event
+ *   from reaching the host's own handlers — a `luthor:media-drop` event says an
+ *   upload started.
  *
- * When no `uploadFile` callback is provided, the extension is inert and all
- * drop/paste events fall through to the next handler.
+ * Without an `uploadFile` callback the extension is inert.
  */
 
 import {
+  $createParagraphNode,
+  $getNearestNodeFromDOMNode,
   $getRoot,
   $getSelection,
+  $isElementNode,
   $isRangeSelection,
+  $isNodeSelection,
   COMMAND_PRIORITY_HIGH,
   PASTE_COMMAND,
   type LexicalEditor,
+  type LexicalNode,
 } from "lexical";
 import {
   type BaseExtensionConfig,
@@ -35,6 +50,38 @@ import {
 } from "@lyfie/luthor-headless/extensions/types";
 import { BaseExtension } from "@lyfie/luthor-headless/extensions/base";
 import { $createFileEmbedNode } from "./FileEmbedNode";
+import { $createUploadPlaceholderNode, $findUploadPlaceholder, $isUploadPlaceholderNode } from "./UploadPlaceholderNode";
+import { createUploadId, UploadQueue, uploadRegistry } from "./uploads";
+import { reportError } from "../../utils/logger";
+
+// Failures of the upload itself are reported through onUploadError as they
+// happen; anything else escaping the pipeline is a bug — say so, never swallow.
+const REPORTED = Symbol("luthor.uploadReported");
+
+function logUnexpected(error: unknown): void {
+  const reported = typeof error === "object" && error !== null && (error as Record<symbol, unknown>)[REPORTED];
+  const aborted = error instanceof DOMException && error.name === "AbortError";
+  if (!reported && !aborted) reportError("fileDropUpload: upload pipeline failed", error);
+}
+
+function markReported<T>(error: T): T {
+  if (typeof error === "object" && error !== null) {
+    try {
+      (error as Record<symbol, unknown>)[REPORTED] = true;
+    } catch {
+      // Frozen error objects: logged twice at worst.
+    }
+  }
+  return error;
+}
+
+/** What an upload callback is given besides the file. */
+export interface UploadFileOptions {
+  /** Aborted when the person cancels; pass it to `fetch` / XHR. */
+  signal: AbortSignal;
+  /** Report progress, 0–1. */
+  onProgress: (fraction: number) => void;
+}
 
 export interface FileDropUploadConfig extends BaseExtensionConfig {
   /**
@@ -46,7 +93,16 @@ export interface FileDropUploadConfig extends BaseExtensionConfig {
    * file under the unsanitized name will serve a broken reference, so
    * sanitize on the server too.
    */
-  uploadFile?: (file: File) => Promise<{ filename: string }>;
+  uploadFile?: (file: File, options: UploadFileOptions) => Promise<{ filename: string }>;
+  /**
+   * Refuse a file before uploading it (too big, a type the host won't take):
+   * return a message to show, or `null` to accept.
+   */
+  validateFile?: (file: File) => string | null;
+  /** Report a failed or refused upload (a toast). Called once per failure. */
+  onUploadError?: (error: unknown, file: File) => void;
+  /** Uploads that may run at once (default 3). */
+  concurrency?: number;
 }
 
 /**
@@ -61,156 +117,336 @@ export function sanitizeEmbedTarget(filename: string): string {
 }
 
 /**
- * Headless extension that wires drop/paste → upload → file embed insertion.
- * Pass `uploadFile` in the config to activate the pipeline; without it, the
- * extension is a no-op.
+ * Whether a paste is really rich content (keep it as text) rather than files.
+ * Word, Excel, Sheets and web pages put a rendered picture of the selection on
+ * the clipboard next to the HTML; that picture must not replace the text.
+ * A clipboard whose HTML is only an `<img>` (a copied image) or empty is files.
  */
+export function isRichTextPaste(data: DataTransfer | null): boolean {
+  if (!data) return false;
+  const html = data.getData("text/html");
+  if (html) {
+    const images = (html.match(/<img\b/gi) ?? []).length;
+    const text = html
+      .replace(/<(style|script)[\s\S]*?<\/\1>/gi, "")
+      .replace(/<!--[\s\S]*?-->/g, "")
+      .replace(/<[^>]*>/g, "")
+      .replace(/&nbsp;|&#160;/gi, " ")
+      .trim();
+    if (text.length > 0 || images > 1) return true;
+    return false;
+  }
+  // RTF with text alongside (a desktop app that offers no HTML).
+  return !!data.getData("text/rtf") && data.getData("text/plain").trim().length > 0;
+}
+
 /** Commands contributed by {@link FileDropUploadExtension}. */
 export type FileDropUploadCommands = {
   /**
-   * Upload `file` through the configured `uploadFile` callback and embed the
-   * result after the caret's block as `![[filename]]` — the same path a paste
-   * or drop takes, for a host's own "attach file" control. Resolves once the
-   * embed is inserted; rejects when no `uploadFile` is configured or the
-   * upload fails, so the caller can report it.
+   * Upload `file` and embed it after the caret's block — the same pipeline a
+   * paste takes, for a host's own "attach file" control. Resolves once the
+   * embed is in the document; rejects when the upload fails, is cancelled or
+   * is refused (the placeholder then shows Retry/Remove, and `onUploadError`
+   * has already been told).
    */
   uploadAndEmbedFile: (file: File) => Promise<void>;
+  /** Several files at once, placed in order. */
+  uploadAndEmbedFiles: (files: File[]) => Promise<void>;
 };
 
+/** The event a drop with files dispatches on the editor root (bubbles). */
+export const MEDIA_DROP_EVENT = "luthor:media-drop";
+
 export class FileDropUploadExtension extends BaseExtension<
   "fileDropUpload",
   FileDropUploadConfig,
   FileDropUploadCommands
 > {
+  private queue: UploadQueue;
+
   constructor(config: FileDropUploadConfig = {}) {
     super("fileDropUpload", [ExtensionCategory.Floating]);
     this.config = config;
+    this.queue = new UploadQueue(config.concurrency ?? 3);
   }
 
-  register(editor: LexicalEditor): () => void {
-    const uploadFile = this.config.uploadFile;
-    if (typeof uploadFile !== "function") {
-      return () => {};
-    }
+  private get enabled(): boolean {
+    return typeof this.config.uploadFile === "function";
+  }
 
+  register(editor: LexicalEditor): () => void {
     const removePaste = editor.registerCommand<ClipboardEvent>(
       PASTE_COMMAND,
       (event) => {
-        const items = event.clipboardData?.items;
-        if (!items) {
-          return false;
-        }
-
-        const files: File[] = [];
-        for (const item of Array.from(items)) {
-          if (item.kind === "file") {
-            const file = item.getAsFile();
-            if (file) {
-              files.push(file);
-            }
-          }
-        }
-
-        if (files.length === 0) {
-          return false;
-        }
-
+        if (!this.enabled || !editor.isEditable()) return false;
+        const data = event.clipboardData;
+        const files = data ? Array.from(data.files ?? []) : [];
+        if (files.length === 0 || isRichTextPaste(data)) return false;
         event.preventDefault();
-        for (const file of files) {
-          this.handleFileUpload(editor, file, uploadFile);
-        }
+        void this.uploadFiles(editor, files, "selection").catch(logUnexpected);
         return true;
       },
       COMMAND_PRIORITY_HIGH,
     );
 
-    const rootElement = editor.getRootElement();
-    let removeDrop: (() => void) | null = null;
-
-    if (rootElement) {
-      const handleDragOver = (event: DragEvent) => {
+    // Bound through the root listener so a remounted content-editable (a view
+    // switch) keeps its drop target.
+    let detach: (() => void) | null = null;
+    const removeRoot = editor.registerRootListener((root, previous) => {
+      detach?.();
+      detach = null;
+      void previous;
+      if (!root) return;
+      const onDragOver = (event: DragEvent) => {
+        if (!this.enabled || !editor.isEditable()) return;
         if (event.dataTransfer?.types.includes("Files")) {
           event.preventDefault();
           event.dataTransfer.dropEffect = "copy";
         }
       };
-
-      const handleDrop = (event: DragEvent) => {
-        const files = event.dataTransfer?.files;
-        if (!files || files.length === 0) {
-          return;
-        }
-
+      const onDrop = (event: DragEvent) => {
+        if (!this.enabled || !editor.isEditable()) return;
+        const files = Array.from(event.dataTransfer?.files ?? []);
+        if (files.length === 0) return;
+        // No stopPropagation: the host's own drop handling (an overlay that
+        // must reset) still sees the event.
         event.preventDefault();
-        event.stopPropagation();
-
-        for (const file of Array.from(files)) {
-          this.handleFileUpload(editor, file, uploadFile);
-        }
+        root.dispatchEvent(new CustomEvent(MEDIA_DROP_EVENT, { bubbles: true, detail: { count: files.length } }));
+        const at = { x: event.clientX, y: event.clientY };
+        void this.uploadFiles(editor, files, at).catch(logUnexpected);
       };
-
-      rootElement.addEventListener("dragover", handleDragOver);
-      rootElement.addEventListener("drop", handleDrop);
-
-      removeDrop = () => {
-        rootElement.removeEventListener("dragover", handleDragOver);
-        rootElement.removeEventListener("drop", handleDrop);
+      root.addEventListener("dragover", onDragOver);
+      root.addEventListener("drop", onDrop);
+      detach = () => {
+        root.removeEventListener("dragover", onDragOver);
+        root.removeEventListener("drop", onDrop);
       };
-    }
+    });
 
     return () => {
       removePaste();
-      removeDrop?.();
+      removeRoot();
+      detach?.();
     };
   }
 
   getCommands(editor: LexicalEditor): FileDropUploadCommands {
     return {
       uploadAndEmbedFile: async (file: File) => {
-        const uploadFile = this.config.uploadFile;
-        if (typeof uploadFile !== "function") {
-          throw new Error("fileDropUpload: no uploadFile callback is configured");
-        }
-        const { filename } = await uploadFile(file);
-        this.insertEmbed(editor, filename);
+        if (!this.enabled) throw new Error("fileDropUpload: no uploadFile callback is configured");
+        await this.uploadFiles(editor, [file], "selection");
+      },
+      uploadAndEmbedFiles: async (files: File[]) => {
+        if (!this.enabled) throw new Error("fileDropUpload: no uploadFile callback is configured");
+        await this.uploadFiles(editor, files, "selection");
       },
     };
   }
 
-  private handleFileUpload(
+  /**
+   * Validate, place a placeholder per file (in order), then upload each and
+   * swap its placeholder for the embed. Resolves when all are embedded;
+   * rejects with the first failure (every failure is still reported).
+   */
+  private async uploadFiles(
     editor: LexicalEditor,
-    file: File,
-    uploadFile: (file: File) => Promise<{ filename: string }>,
-  ): void {
-    uploadFile(file).then(
-      ({ filename }) => this.insertEmbed(editor, filename),
-      () => {
-        // Upload failed — swallow silently. The host adapter owns error
-        // reporting through its own UI (toasts, banners, etc.).
-      },
-    );
-  }
+    files: File[],
+    where: "selection" | { x: number; y: number },
+  ): Promise<void> {
+    if (!editor.isEditable()) throw new Error("fileDropUpload: the editor is read-only");
 
-  private insertEmbed(editor: LexicalEditor, filename: string): void {
-    const target = sanitizeEmbedTarget(filename);
-    if (!target) {
-      return;
+    const accepted: File[] = [];
+    let refusal: Error | null = null;
+    for (const file of files) {
+      const message = this.config.validateFile?.(file) ?? null;
+      if (message) {
+        const error = markReported(new Error(message));
+        refusal ??= error;
+        this.config.onUploadError?.(error, file);
+      } else {
+        accepted.push(file);
+      }
     }
+    if (accepted.length === 0) {
+      throw refusal ?? new Error("fileDropUpload: nothing to upload");
+    }
+
+    const ids = accepted.map(() => createUploadId());
+    const anchorBlock = where === "selection" ? null : blockAtPoint(editor, where.x, where.y);
     editor.update(() => {
-      const embedNode = $createFileEmbedNode(target);
-      const selection = $getSelection();
-      if ($isRangeSelection(selection)) {
-        const anchor = selection.anchor.getNode();
-        const topElement = anchor.getTopLevelElement();
-        if (topElement) {
-          topElement.insertAfter(embedNode);
-          return;
-        }
-      }
+      const placeholders = accepted.map((file, i) => $createUploadPlaceholderNode(file, ids[i]!));
+      $insertBlocks(placeholders, anchorBlock);
+    });
+
+    const results = await Promise.allSettled(accepted.map((file, i) => this.runUpload(editor, file, ids[i]!)));
+    const failure = results.find((r): r is PromiseRejectedResult => r.status === "rejected");
+    if (failure) throw failure.reason;
+    if (refusal) throw refusal;
+  }
 
-      $getRoot().append(embedNode);
+  /** Upload one file for an existing placeholder; retries reuse the placeholder. */
+  private runUpload(editor: LexicalEditor, file: File, id: string): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      let controller = new AbortController();
+      let settled = false;
+      const previewUrl =
+        typeof URL !== "undefined" && typeof URL.createObjectURL === "function" && file.type.startsWith("image/")
+          ? URL.createObjectURL(file)
+          : null;
+
+      const finish = (error?: unknown) => {
+        if (settled) return;
+        settled = true;
+        if (error === undefined) resolve();
+        else reject(error);
+      };
+
+      const cancel = () => {
+        controller.abort();
+        uploadRegistry.delete(id);
+        finish(new DOMException("Upload cancelled", "AbortError"));
+      };
+
+      const attempt = () => {
+        controller = new AbortController();
+        uploadRegistry.update(id, { status: "queued", error: null, progress: null });
+        void this.queue
+          .run(async () => {
+            if (controller.signal.aborted) throw new DOMException("Upload cancelled", "AbortError");
+            uploadRegistry.update(id, { status: "uploading" });
+            const uploadFile = this.config.uploadFile;
+            if (typeof uploadFile !== "function") throw new Error("fileDropUpload: no uploadFile callback is configured");
+            return uploadFile(file, {
+              signal: controller.signal,
+              onProgress: (fraction) => {
+                if (Number.isFinite(fraction)) uploadRegistry.update(id, { progress: Math.max(0, Math.min(1, fraction)) });
+              },
+            });
+          })
+          .then(
+            ({ filename }) => {
+              const target = sanitizeEmbedTarget(filename);
+              let placed = false;
+              editor.update(
+                () => {
+                  const placeholder = $findUploadPlaceholder(id);
+                  if (!placeholder) return; // removed while uploading
+                  if (!target) {
+                    placeholder.remove();
+                    return;
+                  }
+                  placeholder.replace($createFileEmbedNode(target));
+                  placed = true;
+                },
+                // Part of the same undoable step as the drop, not a new one.
+                { tag: "history-merge" },
+              );
+              uploadRegistry.delete(id);
+              if (placed || !target) finish();
+              else finish(new DOMException("Upload removed", "AbortError"));
+            },
+            (error: unknown) => {
+              if (controller.signal.aborted || (error instanceof DOMException && error.name === "AbortError")) {
+                return; // cancel() already settled it
+              }
+              uploadRegistry.update(id, {
+                status: "error",
+                error: error instanceof Error && error.message ? error.message : "Upload failed",
+              });
+              this.config.onUploadError?.(error, file);
+              finish(markReported(error));
+            },
+          );
+      };
+
+      uploadRegistry.set({
+        id,
+        file,
+        status: "queued",
+        progress: null,
+        previewUrl,
+        error: null,
+        cancel,
+        // A retry is a fresh attempt for the same placeholder; the caller who
+        // awaited the first attempt has already been told it failed.
+        retry: () => {
+          settled = true;
+          attempt();
+        },
+      });
+      attempt();
     });
   }
 }
 
+/** The top-level block under a point in the editor, or null. */
+function blockAtPoint(editor: LexicalEditor, x: number, y: number): { key: string; before: boolean } | null {
+  const root = editor.getRootElement();
+  if (!root || typeof document === "undefined" || typeof document.elementFromPoint !== "function") return null;
+  let element = document.elementFromPoint(x, y);
+  if (!element || !root.contains(element)) return null;
+  // Walk up to a direct child of the root: a top-level block.
+  while (element && element.parentElement !== root) element = element.parentElement;
+  if (!element) return null;
+  const rect = element.getBoundingClientRect();
+  const before = y < rect.top + rect.height / 2;
+  let key: string | null = null;
+  editor.read(() => {
+    const node = $getNearestNodeFromDOMNode(element!);
+    key = node ? (node.getTopLevelElement()?.getKey() ?? node.getKey()) : null;
+  });
+  return key ? { key, before } : null;
+}
+
+/**
+ * Insert blocks, in order: before/after the block under a drop point, else
+ * after the caret's block, else at the end. An empty paragraph the caret sat
+ * in is replaced by the uploads. A paragraph follows the last one when nothing
+ * else does, so typing can continue after an upload at the end of a note.
+ */
+function $insertBlocks(blocks: LexicalNode[], at: { key: string; before: boolean } | null): void {
+  if (blocks.length === 0) return;
+  const root = $getRoot();
+  let anchor: LexicalNode | null = null;
+  let before = false;
+
+  if (at) {
+    anchor = root.getChildren().find((child) => child.getKey() === at.key) ?? null;
+    before = at.before;
+  }
+  if (!anchor) {
+    const selection = $getSelection();
+    if ($isRangeSelection(selection)) {
+      anchor = selection.anchor.getNode().getTopLevelElement();
+    } else if ($isNodeSelection(selection)) {
+      const node = selection.getNodes()[0];
+      anchor = node ? (node.getTopLevelElement() ?? node) : null;
+    }
+  }
+
+  const replaceEmpty =
+    !!anchor && !before && $isElementNode(anchor) && anchor.getType() === "paragraph" && anchor.isEmpty();
+  const [first, ...rest] = blocks;
+  if (!anchor) root.append(first!);
+  else if (before) anchor.insertBefore(first!);
+  else anchor.insertAfter(first!);
+  let last = first!;
+  for (const block of rest) {
+    last.insertAfter(block);
+    last = block;
+  }
+  if (replaceEmpty) anchor!.remove();
+
+  const next = last.getNextSibling();
+  if (!next) {
+    const paragraph = $createParagraphNode();
+    last.insertAfter(paragraph);
+    paragraph.select();
+  } else if ($isElementNode(next)) {
+    next.selectStart();
+  }
+}
+
+export { $isUploadPlaceholderNode };
+
 export const fileDropUploadExtension = new FileDropUploadExtension();
diff --git a/packages/headless/src/extensions/embeds/FileEmbedNode.tsx b/packages/headless/src/extensions/embeds/FileEmbedNode.tsx
index 974c384f..2f0a6d48 100644
--- a/packages/headless/src/extensions/embeds/FileEmbedNode.tsx
+++ b/packages/headless/src/extensions/embeds/FileEmbedNode.tsx
@@ -6,15 +6,28 @@
  */
 
 import {
+  $createNodeSelection,
+  $createParagraphNode,
+  $getNearestNodeFromDOMNode,
+  $getNodeByKey,
+  $getSelection,
+  $isNodeSelection,
+  $setSelection,
+  CLICK_COMMAND,
+  COMMAND_PRIORITY_LOW,
   DecoratorNode,
+  KEY_DOWN_COMMAND,
   type DOMConversionMap,
   type DOMExportOutput,
   type ElementNode,
+  type LexicalEditor,
   type LexicalNode,
   type NodeKey,
   type SerializedLexicalNode,
   type Spread,
 } from "lexical";
+import type { MediaEdit } from "./EmbedResolverContext";
+import { UploadPlaceholderNode } from "./UploadPlaceholderNode";
 import type { ElementTransformer, TextMatchTransformer } from "@lexical/markdown";
 import type { ReactNode } from "react";
 import { ExtensionCategory } from "@lyfie/luthor-headless/extensions/types";
@@ -343,7 +356,23 @@ export class FileEmbedNode extends DecoratorNode<ReactNode> {
     return writable;
   }
 
+  /** Apply a toolbar/resize edit (see {@link MediaEdit}). */
+  applyEdit(edit: MediaEdit): this {
+    let node: this = this.getWritable();
+    if (edit.target !== undefined && edit.target.trim() !== "") node = node.setTarget(edit.target.trim());
+    if (edit.width !== undefined) {
+      node = node.setSize(edit.width ?? undefined, edit.height ?? (edit.width ? node.__height : undefined));
+    } else if (edit.height !== undefined && node.__width) {
+      node = node.setSize(node.__width, edit.height ?? undefined);
+    }
+    if (edit.align !== undefined) node = node.setAlign(edit.align ?? undefined);
+    if (edit.caption !== undefined) node = node.setCaption(edit.caption ?? undefined);
+    if (edit.alt !== undefined) node = node.setAlt(edit.alt ?? undefined);
+    return node;
+  }
+
   decorate(): ReactNode {
+    const key = this.__key;
     return (
       <MediaFrame
         target={this.__target}
@@ -354,11 +383,129 @@ export class FileEmbedNode extends DecoratorNode<ReactNode> {
         align={this.__align}
         caption={this.__caption}
         inline={this.__inline}
+        nodeKey={key}
+        onEdit={(editor, edit) => $editFileEmbed(editor, key, edit)}
+        onRemove={(editor) => $removeFileEmbed(editor, key)}
       />
     );
   }
 }
 
+/** Edit the file embed with `key` in one update (one undo step, one sync). */
+export function $editFileEmbed(editor: LexicalEditor, key: NodeKey, edit: MediaEdit): void {
+  editor.update(() => {
+    const node = $getNodeByKey(key);
+    if ($isFileEmbedNode(node)) {
+      node.applyEdit(edit);
+    }
+  });
+}
+
+/**
+ * Remove the file embed with `key`. A block leaves the caret where it was (in a
+ * fresh paragraph when it was the only thing there), so typing just continues.
+ */
+export function $removeFileEmbed(editor: LexicalEditor, key: NodeKey): void {
+  editor.update(() => {
+    const node = $getNodeByKey(key);
+    if (!$isFileEmbedNode(node)) return;
+    if (node.isInline()) {
+      const previous = node.getPreviousSibling();
+      node.remove();
+      previous?.selectEnd();
+      return;
+    }
+    const next = node.getNextSibling();
+    const previous = node.getPreviousSibling();
+    if (next) {
+      node.remove();
+      next.selectStart();
+    } else if (previous) {
+      node.remove();
+      previous.selectEnd();
+    } else {
+      const paragraph = $createParagraphNode();
+      node.replace(paragraph);
+      paragraph.select();
+    }
+  });
+}
+
+// A click on an embed selects it. This has to be the click command itself, at a
+// higher priority than rich text's: that handler clears any node selection on
+// every click, so selecting from a React onClick raced it and the selection
+// (and its toolbar) flickered away.
+function registerFileEmbedClicks(editor: LexicalEditor): () => void {
+  return editor.registerCommand(
+    CLICK_COMMAND,
+    (event: MouseEvent) => {
+      if (!editor.isEditable()) return false;
+      const target = event.target;
+      const element = target instanceof Element ? target : target instanceof Node ? target.parentElement : null;
+      const frame = element?.closest(".luthor-media__frame, .luthor-media--inline");
+      if (!frame) return false;
+      const node = $getNearestNodeFromDOMNode(frame);
+      if (!$isFileEmbedNode(node)) return false;
+      const selection = $createNodeSelection();
+      selection.add(node.getKey());
+      $setSelection(selection);
+      return true;
+    },
+    COMMAND_PRIORITY_LOW,
+  );
+}
+
+// Keyboard for a selected embed: Shift+←/→ resizes by 10px (Alt: by 1px),
+// Enter opens a new line after it, Escape lets go of it.
+function registerFileEmbedKeys(editor: LexicalEditor): () => void {
+  return editor.registerCommand(
+    KEY_DOWN_COMMAND,
+    (event: KeyboardEvent) => {
+      if (!editor.isEditable()) return false;
+      const selection = $getSelection();
+      if (!$isNodeSelection(selection)) return false;
+      const nodes = selection.getNodes();
+      if (nodes.length !== 1) return false;
+      const node = nodes[0];
+      if (!$isFileEmbedNode(node)) return false;
+
+      if (event.key === "Escape") {
+        event.preventDefault();
+        $setSelection(null);
+        return true;
+      }
+
+      if (event.key === "Enter" && !node.isInline() && !event.shiftKey) {
+        event.preventDefault();
+        const paragraph = $createParagraphNode();
+        node.insertAfter(paragraph);
+        paragraph.select();
+        return true;
+      }
+
+      if (event.shiftKey && (event.key === "ArrowLeft" || event.key === "ArrowRight")) {
+        const element = editor.getElementByKey(node.getKey());
+        const frame = element?.querySelector<HTMLElement>(".luthor-media__frame, .luthor-media--inline");
+        const current = node.__width ?? Math.round(frame?.getBoundingClientRect().width ?? 0);
+        if (!current) return false;
+        const step = event.altKey ? 1 : 10;
+        const max = Math.round(element?.parentElement?.getBoundingClientRect().width || Number.POSITIVE_INFINITY);
+        const next = Math.min(max, Math.max(48, current + (event.key === "ArrowRight" ? step : -step)));
+        event.preventDefault();
+        if (next !== current) {
+          node.applyEdit({
+            width: next,
+            height: node.__width && node.__height ? Math.round((next * node.__height) / node.__width) : null,
+          });
+        }
+        return true;
+      }
+      return false;
+    },
+    COMMAND_PRIORITY_LOW,
+  );
+}
+
 /**
  * Create a {@link FileEmbedNode} — from a bare file name (an upload), or from
  * fields plus the markdown they were parsed from.
@@ -389,12 +536,20 @@ export class FileEmbedExtension extends BaseExtension<"fileEmbed"> {
     super("fileEmbed", [ExtensionCategory.Floating]);
   }
 
-  register(): () => void {
-    return () => {};
+  register(editor: LexicalEditor): () => void {
+    const unregisterKeys = registerFileEmbedKeys(editor);
+    const unregisterClicks = registerFileEmbedClicks(editor);
+    return () => {
+      unregisterKeys();
+      unregisterClicks();
+    };
   }
 
-  getNodes(): Array<typeof FileEmbedNode> {
-    return [FileEmbedNode];
+  // The upload placeholder travels with file embeds: every editor that can show
+  // an embed (and the collaboration server) must know the node a collaborator's
+  // upload inserts, even when it has no upload pipeline of its own.
+  getNodes(): Array<typeof FileEmbedNode | typeof UploadPlaceholderNode> {
+    return [FileEmbedNode, UploadPlaceholderNode];
   }
 }
 
diff --git a/packages/headless/src/extensions/embeds/UploadPlaceholder.test.tsx b/packages/headless/src/extensions/embeds/UploadPlaceholder.test.tsx
new file mode 100644
index 00000000..ffcfdedf
--- /dev/null
+++ b/packages/headless/src/extensions/embeds/UploadPlaceholder.test.tsx
@@ -0,0 +1,116 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+/* @vitest-environment jsdom */
+
+import { act, render } from "@testing-library/react";
+import { LexicalComposer } from "@lexical/react/LexicalComposer";
+import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
+import { ContentEditable } from "@lexical/react/LexicalContentEditable";
+import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary";
+import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";
+import { $createParagraphNode, $getRoot, type LexicalEditor } from "lexical";
+import { useEffect } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  $isUploadPlaceholderNode,
+  UPLOAD_STALE_AFTER_MS,
+  UploadPlaceholderNode,
+} from "./UploadPlaceholderNode";
+import { uploadRegistry, type UploadTask } from "./uploads";
+
+afterEach(() => {
+  for (const id of ["up-a", "up-b"]) uploadRegistry.delete(id);
+});
+
+function Capture({ onEditor }: { onEditor: (editor: LexicalEditor) => void }) {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => {
+    onEditor(editor);
+  }, [editor, onEditor]);
+  return null;
+}
+
+async function mount(startedAt = Date.now()) {
+  let editor: LexicalEditor | null = null;
+  const view = render(
+    <LexicalComposer
+      initialConfig={{
+        namespace: "upload-placeholder",
+        nodes: [UploadPlaceholderNode],
+        onError: (error) => {
+          throw error;
+        },
+        editorState: () => {
+          $getRoot().append(
+            $createParagraphNode(),
+            new UploadPlaceholderNode({ uploadId: "up-a", name: "beach.png", size: 2048, kind: "image", startedAt }),
+          );
+        },
+      }}
+    >
+      <RichTextPlugin contentEditable={<ContentEditable />} ErrorBoundary={LexicalErrorBoundary} />
+      <Capture onEditor={(e) => (editor = e)} />
+    </LexicalComposer>,
+  );
+  await act(async () => {});
+  return { ...view, editor: editor as unknown as LexicalEditor };
+}
+
+function task(patch: Partial<UploadTask> = {}): UploadTask {
+  return {
+    id: "up-a",
+    file: new File(["x"], "beach.png"),
+    status: "uploading",
+    progress: 0.5,
+    previewUrl: null,
+    error: null,
+    cancel: vi.fn(),
+    retry: vi.fn(),
+    ...patch,
+  };
+}
+
+const click = (el: Element) =>
+  act(async () => {
+    el.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+  });
+
+describe("upload placeholder card", () => {
+  it("shows progress for this tab's upload, and Cancel stops and removes it", async () => {
+    const t = task();
+    uploadRegistry.set(t);
+    const { container, editor } = await mount();
+    expect(container.querySelector('[role="progressbar"]')!.getAttribute("aria-valuenow")).toBe("50");
+    expect(container.textContent).toContain("2 KB · 50%");
+    await click(container.querySelector('[data-upload-action="remove"]')!);
+    expect(t.cancel).toHaveBeenCalledTimes(1);
+    editor.getEditorState().read(() => expect($getRoot().getChildren().some($isUploadPlaceholderNode)).toBe(false));
+  });
+
+  it("a failed upload offers Retry", async () => {
+    const t = task({ status: "error", error: "offline", progress: null });
+    uploadRegistry.set(t);
+    const { container } = await mount();
+    expect(container.textContent).toContain("offline");
+    await click(container.querySelector('[data-upload-action="retry"]')!);
+    expect(t.retry).toHaveBeenCalledTimes(1);
+  });
+
+  it("a collaborator sees 'being uploaded' with no controls", async () => {
+    const { container } = await mount();
+    expect(container.querySelector(".luthor-upload")!.getAttribute("aria-label")).toBe("beach.png is being uploaded…");
+    expect(container.querySelector("[data-upload-action]")).toBeNull();
+  });
+
+  it("an abandoned upload goes stale and can be removed", async () => {
+    const { container, editor } = await mount(Date.now() - UPLOAD_STALE_AFTER_MS - 1000);
+    expect(container.textContent).toContain("didn't finish");
+    await click(container.querySelector('[data-upload-action="remove"]')!);
+    editor.getEditorState().read(() => expect($getRoot().getChildren().some($isUploadPlaceholderNode)).toBe(false));
+  });
+});
diff --git a/packages/headless/src/extensions/embeds/UploadPlaceholderNode.tsx b/packages/headless/src/extensions/embeds/UploadPlaceholderNode.tsx
new file mode 100644
index 00000000..50921c67
--- /dev/null
+++ b/packages/headless/src/extensions/embeds/UploadPlaceholderNode.tsx
@@ -0,0 +1,299 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+import {
+  $getNodeByKey,
+  $getRoot,
+  $isElementNode,
+  DecoratorNode,
+  type DOMConversionMap,
+  type DOMExportOutput,
+  type LexicalNode,
+  type NodeKey,
+  type SerializedLexicalNode,
+  type Spread,
+} from "lexical";
+import type { ElementTransformer } from "@lexical/markdown";
+import { useContext, useEffect, useRef, useSyncExternalStore, type ReactNode } from "react";
+import { LexicalComposerContext } from "@lexical/react/LexicalComposerContext";
+import { classifyMedia } from "../media/mediaGrammar";
+import { formatBytes } from "../media/MediaFrame";
+import { useIsEditable } from "../media/mediaSelection";
+import { uploadRegistry } from "./uploads";
+
+/** Serialized {@link UploadPlaceholderNode}: what collaborators may know. */
+export type SerializedUploadPlaceholderNode = Spread<
+  {
+    uploadId: string;
+    name: string;
+    size: number;
+    /** `image`, `video`, `audio`, `pdf` or `file`. */
+    kind: string;
+    /** When the upload started (ms since epoch) — an abandoned one goes stale. */
+    startedAt: number;
+  },
+  SerializedLexicalNode
+>;
+
+/** An upload that has been silent this long was abandoned (tab closed, crash). */
+export const UPLOAD_STALE_AFTER_MS = 15 * 60 * 1000;
+
+/**
+ * Where a file being uploaded will appear. Inserted the moment it is dropped or
+ * pasted, in order, at the drop point — so a batch lands in the order it was
+ * given no matter which upload finishes first — and replaced in place by the
+ * real `![[file]]` embed when its upload completes.
+ *
+ * It carries nothing private: no `blob:` URL, no file contents. The tab doing
+ * the upload shows progress and a preview from its local registry; everyone
+ * else (collaborators, the server) sees "Uploading …". It writes nothing to
+ * markdown, so a save mid-upload never persists it.
+ */
+export class UploadPlaceholderNode extends DecoratorNode<ReactNode> {
+  __uploadId: string;
+  __name: string;
+  __size: number;
+  __kind: string;
+  __startedAt: number;
+
+  static getType(): string {
+    return "uploadPlaceholder";
+  }
+
+  static clone(node: UploadPlaceholderNode): UploadPlaceholderNode {
+    return new UploadPlaceholderNode(
+      { uploadId: node.__uploadId, name: node.__name, size: node.__size, kind: node.__kind, startedAt: node.__startedAt },
+      node.__key,
+    );
+  }
+
+  static importJSON(serialized: SerializedUploadPlaceholderNode): UploadPlaceholderNode {
+    return new UploadPlaceholderNode(serialized);
+  }
+
+  static importDOM(): DOMConversionMap | null {
+    return null;
+  }
+
+  // Collaboration constructs nodes without arguments, then copies properties.
+  constructor(
+    fields?: Pick<SerializedUploadPlaceholderNode, "uploadId" | "name" | "size" | "kind" | "startedAt">,
+    key?: NodeKey,
+  ) {
+    super(key);
+    this.__uploadId = fields?.uploadId ?? "";
+    this.__name = fields?.name ?? "";
+    this.__size = fields?.size ?? 0;
+    this.__kind = fields?.kind ?? "file";
+    this.__startedAt = fields?.startedAt ?? Date.now();
+  }
+
+  exportJSON(): SerializedUploadPlaceholderNode {
+    return {
+      type: "uploadPlaceholder",
+      version: 1,
+      uploadId: this.__uploadId,
+      name: this.__name,
+      size: this.__size,
+      kind: this.__kind,
+      startedAt: this.__startedAt,
+    };
+  }
+
+  createDOM(): HTMLElement {
+    const div = document.createElement("div");
+    div.className = "luthor-upload-shell";
+    return div;
+  }
+
+  updateDOM(): boolean {
+    return false;
+  }
+
+  exportDOM(): DOMExportOutput {
+    return { element: null };
+  }
+
+  isInline(): boolean {
+    return false;
+  }
+
+  getTextContent(): string {
+    return "";
+  }
+
+  getUploadId(): string {
+    return this.getLatest().__uploadId;
+  }
+
+  decorate(): ReactNode {
+    return (
+      <UploadPlaceholderCard
+        nodeKey={this.__key}
+        uploadId={this.__uploadId}
+        name={this.__name}
+        size={this.__size}
+        kind={this.__kind}
+        startedAt={this.__startedAt}
+      />
+    );
+  }
+}
+
+export function $createUploadPlaceholderNode(file: File, uploadId: string): UploadPlaceholderNode {
+  return new UploadPlaceholderNode({
+    uploadId,
+    name: file.name || "file",
+    size: file.size,
+    kind: classifyMedia(file.name || ""),
+    startedAt: Date.now(),
+  });
+}
+
+export function $isUploadPlaceholderNode(node: LexicalNode | null | undefined): node is UploadPlaceholderNode {
+  return node instanceof UploadPlaceholderNode;
+}
+
+/** Find the placeholder for an upload (null when it was deleted meanwhile). */
+export function $findUploadPlaceholder(uploadId: string): UploadPlaceholderNode | null {
+  const visit = (node: LexicalNode): UploadPlaceholderNode | null => {
+    if ($isUploadPlaceholderNode(node)) return node.getUploadId() === uploadId ? node : null;
+    if ($isElementNode(node)) {
+      for (const child of node.getChildren()) {
+        const hit = visit(child);
+        if (hit) return hit;
+      }
+    }
+    return null;
+  };
+  return visit($getRoot());
+}
+
+/**
+ * Markdown for a placeholder: nothing. An in-flight upload is not content yet —
+ * a save while it runs must not write anything for it.
+ */
+export const UPLOAD_PLACEHOLDER_MARKDOWN_TRANSFORMER: ElementTransformer = {
+  dependencies: [UploadPlaceholderNode],
+  export: (node) => ($isUploadPlaceholderNode(node) ? "" : null),
+  // Never produced from markdown.
+  regExp: /(?!)/,
+  replace: () => false,
+  type: "element",
+};
+
+function UploadPlaceholderCard(props: {
+  nodeKey: string;
+  uploadId: string;
+  name: string;
+  size: number;
+  kind: string;
+  startedAt: number;
+}): ReactNode {
+  const { nodeKey, uploadId, name, size, kind, startedAt } = props;
+  const composer = useContext(LexicalComposerContext);
+  const editor = composer ? composer[0] : null;
+  const editable = useIsEditable(editor);
+  // Re-render on registry changes; read this upload's task (local only).
+  useSyncExternalStore(uploadRegistry.subscribe, uploadRegistry.version, uploadRegistry.version);
+  const task = uploadRegistry.get(uploadId);
+  const actionsRef = useRef<HTMLSpanElement | null>(null);
+
+  const stale = !task && Date.now() - startedAt > UPLOAD_STALE_AFTER_MS;
+  const failed = task?.status === "error";
+  const percent = task?.progress != null ? Math.round(task.progress * 100) : null;
+
+  const remove = () => {
+    task?.cancel();
+    editor?.update(
+      () => {
+        const node = $getNodeByKey(nodeKey);
+        if ($isUploadPlaceholderNode(node)) node.remove();
+      },
+      { tag: "history-merge" },
+    );
+  };
+
+  // Buttons inside a decorator: handled natively so the editor's own root
+  // listeners never treat the click as a selection change.
+  useEffect(() => {
+    const element = actionsRef.current;
+    if (!element) return;
+    const swallow = (event: Event) => {
+      event.preventDefault();
+      event.stopPropagation();
+    };
+    const onClick = (event: MouseEvent) => {
+      swallow(event);
+      const action = (event.target as Element | null)?.closest?.("[data-upload-action]")?.getAttribute("data-upload-action");
+      if (action === "retry") task?.retry();
+      if (action === "remove") remove();
+    };
+    element.addEventListener("mousedown", swallow);
+    element.addEventListener("pointerdown", swallow);
+    element.addEventListener("click", onClick);
+    return () => {
+      element.removeEventListener("mousedown", swallow);
+      element.removeEventListener("pointerdown", swallow);
+      element.removeEventListener("click", onClick);
+    };
+  });
+
+  const label = failed
+    ? `Couldn't upload ${name}`
+    : stale
+      ? `${name} didn't finish uploading`
+      : task
+        ? `Uploading ${name}`
+        : `${name} is being uploaded…`;
+
+  return (
+    <div
+      className={`luthor-upload luthor-upload--${kind}${failed ? " is-error" : ""}${stale ? " is-stale" : ""}`}
+      role="status"
+      aria-live="polite"
+      aria-label={label}
+      contentEditable={false}
+    >
+      {task?.previewUrl ? <img className="luthor-upload__preview" src={task.previewUrl} alt="" /> : null}
+      <div className="luthor-upload__body">
+        <span className="luthor-upload__name">{name}</span>
+        <span className="luthor-upload__detail">
+          {failed ? task?.error || "Upload failed" : stale ? "Upload didn't finish" : [formatBytes(size), percent !== null ? `${percent}%` : null].filter(Boolean).join(" · ")}
+        </span>
+        {!failed && !stale ? (
+          <span
+            className={`luthor-upload__bar${percent === null ? " is-indeterminate" : ""}`}
+            role="progressbar"
+            aria-valuemin={0}
+            aria-valuemax={100}
+            aria-valuenow={percent ?? undefined}
+          >
+            <span style={{ width: percent === null ? undefined : `${percent}%` }} />
+          </span>
+        ) : null}
+      </div>
+      {editable && (task || stale) ? (
+        <span ref={actionsRef} className="luthor-upload__actions">
+          {failed ? (
+            <button type="button" className="luthor-media__button" data-upload-action="retry">
+              Retry
+            </button>
+          ) : null}
+          <button
+            type="button"
+            className="luthor-media__button"
+            data-upload-action="remove"
+            aria-label={failed || stale ? `Remove ${name}` : `Cancel uploading ${name}`}
+          >
+            {failed || stale ? "Remove" : "Cancel"}
+          </button>
+        </span>
+      ) : null}
+    </div>
+  );
+}
diff --git a/packages/headless/src/extensions/embeds/index.ts b/packages/headless/src/extensions/embeds/index.ts
index f1da3443..2cb653d1 100644
--- a/packages/headless/src/extensions/embeds/index.ts
+++ b/packages/headless/src/extensions/embeds/index.ts
@@ -14,6 +14,9 @@ export {
   type MediaMeta,
   type MediaUrlOptions,
   type FileExpansionContext,
+  type MediaEdit,
+  type MediaToolbarContext,
+  type MediaToolbarItem,
 } from "./EmbedResolverContext";
 export {
   ANCHORABLE_BLOCK_TYPES,
@@ -38,6 +41,8 @@ export {
   FILE_EMBED_MARKDOWN_TRANSFORMER,
   FILE_EMBED_INLINE_MARKDOWN_TRANSFORMER,
   parseFileEmbedMarkdown,
+  $editFileEmbed,
+  $removeFileEmbed,
   type FileEmbedFields,
   type SerializedFileEmbedNode,
 } from "./FileEmbedNode";
@@ -105,6 +110,19 @@ export {
   FileDropUploadExtension,
   fileDropUploadExtension,
   sanitizeEmbedTarget,
+  isRichTextPaste,
+  MEDIA_DROP_EVENT,
   type FileDropUploadConfig,
   type FileDropUploadCommands,
+  type UploadFileOptions,
 } from "./FileDropUploadExtension";
+export {
+  UploadPlaceholderNode,
+  $createUploadPlaceholderNode,
+  $isUploadPlaceholderNode,
+  $findUploadPlaceholder,
+  UPLOAD_PLACEHOLDER_MARKDOWN_TRANSFORMER,
+  UPLOAD_STALE_AFTER_MS,
+  type SerializedUploadPlaceholderNode,
+} from "./UploadPlaceholderNode";
+export { uploadRegistry, type UploadTask, type UploadStatus } from "./uploads";
diff --git a/packages/headless/src/extensions/embeds/uploads.ts b/packages/headless/src/extensions/embeds/uploads.ts
new file mode 100644
index 00000000..b785af35
--- /dev/null
+++ b/packages/headless/src/extensions/embeds/uploads.ts
@@ -0,0 +1,106 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+/*
+ * Uploads in flight, as local (never synced) state.
+ *
+ * The document holds only an UploadPlaceholderNode — id, name, size, kind —
+ * because the document is shared: collaborators must see "Uploading …" and
+ * nothing else, and a `blob:` URL means nothing outside this tab. Everything
+ * that exists only here lives in this registry, keyed by upload id: progress,
+ * the preview URL, the abort handle, the error, and how to retry.
+ */
+
+export type UploadStatus = "queued" | "uploading" | "error";
+
+export interface UploadTask {
+  id: string;
+  file: File;
+  status: UploadStatus;
+  /** 0–1, when the host reports progress. */
+  progress: number | null;
+  /** A local preview of a picture (object URL), revoked when the task ends. */
+  previewUrl: string | null;
+  error: string | null;
+  /** Abort the request (or drop it from the queue). */
+  cancel: () => void;
+  /** Try again after an error. */
+  retry: () => void;
+}
+
+const tasks = new Map<string, UploadTask>();
+const listeners = new Set<() => void>();
+let version = 0;
+
+function notify(): void {
+  version++;
+  listeners.forEach((listener) => listener());
+}
+
+export const uploadRegistry = {
+  get(id: string): UploadTask | undefined {
+    return tasks.get(id);
+  },
+  /** Changes whenever any task does (for useSyncExternalStore snapshots). */
+  version(): number {
+    return version;
+  },
+  subscribe(listener: () => void): () => void {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  },
+  set(task: UploadTask): void {
+    tasks.set(task.id, task);
+    notify();
+  },
+  update(id: string, patch: Partial<UploadTask>): void {
+    const current = tasks.get(id);
+    if (!current) return;
+    tasks.set(id, { ...current, ...patch });
+    notify();
+  },
+  delete(id: string): void {
+    const current = tasks.get(id);
+    if (!current) return;
+    if (current.previewUrl) URL.revokeObjectURL(current.previewUrl);
+    tasks.delete(id);
+    notify();
+  },
+};
+
+export function createUploadId(): string {
+  const random =
+    typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+      ? crypto.randomUUID().replace(/-/g, "")
+      : Math.random().toString(36).slice(2) + Date.now().toString(36);
+  return `up-${random.slice(0, 20)}`;
+}
+
+/**
+ * Runs at most `limit` jobs at a time, in the order they were queued. A phone's
+ * worth of photos dropped at once must not open fifty requests together.
+ */
+export class UploadQueue {
+  private running = 0;
+  private readonly waiting: Array<() => void> = [];
+
+  constructor(private readonly limit = 3) {}
+
+  run<T>(job: () => Promise<T>): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const start = () => {
+        this.running++;
+        job().then(resolve, reject).finally(() => {
+          this.running--;
+          this.waiting.shift()?.();
+        });
+      };
+      if (this.running < this.limit) start();
+      else this.waiting.push(start);
+    });
+  }
+}
diff --git a/packages/headless/src/extensions/index.ts b/packages/headless/src/extensions/index.ts
index 4ca7a2f3..629bce16 100644
--- a/packages/headless/src/extensions/index.ts
+++ b/packages/headless/src/extensions/index.ts
@@ -154,6 +154,15 @@ export {
   type MediaKind,
 } from "./media/mediaGrammar";
 export { MediaFrame, formatBytes, type MediaFrameProps } from "./media/MediaFrame";
+export {
+  EditorPromptProvider,
+  useEditorPrompt,
+  type PromptField,
+  type PromptRequest,
+  type RequestPrompt,
+} from "./media/EditorPromptContext";
+export { useIsNodeSelected, useIsEditable, registerClickToSelect } from "./media/mediaSelection";
+export { usePointerResize, type PointerResizeOptions, type ResizeEdge } from "./media/usePointerResize";
 
 // Custom extensions
 export { createCustomNodeExtension } from "./custom/CustomNodeExtension";
@@ -169,6 +178,9 @@ export {
   type MediaMeta,
   type MediaUrlOptions,
   type FileExpansionContext,
+  type MediaEdit,
+  type MediaToolbarContext,
+  type MediaToolbarItem,
   ANCHORABLE_BLOCK_TYPES,
   isAnchorableBlockType,
   $collectAnchorableBlocks,
@@ -187,6 +199,8 @@ export {
   FILE_EMBED_MARKDOWN_TRANSFORMER,
   FILE_EMBED_INLINE_MARKDOWN_TRANSFORMER,
   parseFileEmbedMarkdown,
+  $editFileEmbed,
+  $removeFileEmbed,
   type FileEmbedFields,
   type SerializedFileEmbedNode,
   TransclusionNode,
@@ -240,8 +254,21 @@ export {
   FileDropUploadExtension,
   fileDropUploadExtension,
   sanitizeEmbedTarget,
+  isRichTextPaste,
+  MEDIA_DROP_EVENT,
   type FileDropUploadConfig,
   type FileDropUploadCommands,
+  type UploadFileOptions,
+  UploadPlaceholderNode,
+  $createUploadPlaceholderNode,
+  $isUploadPlaceholderNode,
+  $findUploadPlaceholder,
+  UPLOAD_PLACEHOLDER_MARKDOWN_TRANSFORMER,
+  UPLOAD_STALE_AFTER_MS,
+  type SerializedUploadPlaceholderNode,
+  uploadRegistry,
+  type UploadTask,
+  type UploadStatus,
 } from "./embeds";
 
 // Core extensions
diff --git a/packages/headless/src/extensions/media/EditorPromptContext.tsx b/packages/headless/src/extensions/media/EditorPromptContext.tsx
new file mode 100644
index 00000000..957a43dc
--- /dev/null
+++ b/packages/headless/src/extensions/media/EditorPromptContext.tsx
@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+import { createContext, useContext, type ReactNode } from "react";
+
+/** One field of a {@link PromptRequest}. */
+export interface PromptField {
+  name: string;
+  label: string;
+  placeholder?: string;
+  type?: "text" | "url";
+  required?: boolean;
+  /** Starting value (editing an existing caption, alt text, …). */
+  value?: string;
+}
+
+/** Values a decorator asks the person for. */
+export interface PromptRequest {
+  title: string;
+  submitLabel?: string;
+  fields: readonly PromptField[];
+}
+
+/** Ask for values; resolves the trimmed values by field name, or `null` on cancel. */
+export type RequestPrompt = (request: PromptRequest) => Promise<Record<string, string> | null>;
+
+/*
+ * Decorators (a media frame's caption and alt-text buttons) can't host their
+ * own text inputs: keystrokes inside a decorator reach the editor's root
+ * listeners first, so Backspace would delete the node being captioned. They ask
+ * the editor shell's themed dialog instead, through this context. A shell
+ * without one gets `window.prompt`.
+ */
+const EditorPromptContext = createContext<RequestPrompt | null>(null);
+
+export function EditorPromptProvider({
+  requestPrompt,
+  children,
+}: {
+  requestPrompt: RequestPrompt;
+  children: ReactNode;
+}): ReactNode {
+  return <EditorPromptContext.Provider value={requestPrompt}>{children}</EditorPromptContext.Provider>;
+}
+
+/** The shell's prompt, or a `window.prompt` fallback (one field at a time). */
+export function useEditorPrompt(): RequestPrompt {
+  const provided = useContext(EditorPromptContext);
+  return provided ?? promptFallback;
+}
+
+async function promptFallback(request: PromptRequest): Promise<Record<string, string> | null> {
+  if (typeof window === "undefined" || typeof window.prompt !== "function") return null;
+  const values: Record<string, string> = {};
+  for (const field of request.fields) {
+    const answer = window.prompt(field.label, field.value ?? "");
+    if (answer === null) return null;
+    const trimmed = answer.trim();
+    if (field.required && !trimmed) return null;
+    values[field.name] = trimmed;
+  }
+  return values;
+}
diff --git a/packages/headless/src/extensions/media/IframeEmbedExtension.tsx b/packages/headless/src/extensions/media/IframeEmbedExtension.tsx
index 90811717..6cff1e05 100644
--- a/packages/headless/src/extensions/media/IframeEmbedExtension.tsx
+++ b/packages/headless/src/extensions/media/IframeEmbedExtension.tsx
@@ -6,6 +6,7 @@
  */
 
 import { formatSize, splitCaptionAndSize } from "./mediaGrammar";
+import { registerClickToSelect } from "./mediaSelection";
 import React, { ReactNode, useEffect, useMemo, useRef, useState } from "react";
 import {
   $createNodeSelection,
@@ -570,8 +571,7 @@ export class IframeEmbedExtension extends BaseExtension<
   }
 
   register(editor: LexicalEditor): () => void {
-    void editor;
-    return () => {};
+    return registerClickToSelect(editor, (node) => node instanceof IframeEmbedNode);
   }
 
   getNodes(): any[] {
diff --git a/packages/headless/src/extensions/media/ImageExtension.tsx b/packages/headless/src/extensions/media/ImageExtension.tsx
index 5039d991..af7b0a55 100644
--- a/packages/headless/src/extensions/media/ImageExtension.tsx
+++ b/packages/headless/src/extensions/media/ImageExtension.tsx
@@ -56,6 +56,8 @@ import {
 } from "./ImageTranslator";
 import { sanitizeUrlForAttribute } from "../../utils/urlSafety";
 import { formatSize, MEDIA_MAX_DIMENSION } from "./mediaGrammar";
+import { registerClickToSelect, useIsNodeSelected } from "./mediaSelection";
+import { usePointerResize } from "./usePointerResize";
 import { reportError, warnOnce } from "../../utils/logger";
 
 /**
@@ -71,13 +73,7 @@ let defaultImageResizable = true;
 let defaultScaleByRatio = false;
 
 const MIN_IMAGE_WIDTH = 50;
-const MIN_IMAGE_HEIGHT = 50;
 const MAX_IMAGE_WIDTH = 2400;
-const MAX_IMAGE_HEIGHT = 2400;
-
-function clampSize(value: number, min: number, max: number): number {
-  return Math.min(max, Math.max(min, Math.round(value)));
-}
 
 export function shouldShowImageResizeHandles(
   isEditorEditable: boolean,
@@ -121,17 +117,17 @@ function ImageComponent({
   width,
   height,
   resizable = true,
-  scaleByRatio = false,
+  // (`scaleByRatio` is accepted but no longer needed: resizing is always
+  // aspect-locked — width only, height follows.)
   uploading = false,
 }: ImageComponentProps): ReactNode {
   const [editor] = useLexicalComposerContext();
   const imageRef = useRef<HTMLImageElement>(null);
   const shellRef = useRef<HTMLDivElement>(null);
-  const resizeFrameRef = useRef<number | null>(null);
   const widthRef = useRef<number>(0);
   const heightRef = useRef<number>(0);
-  const [isSelected, setIsSelected] = useState(false);
-  const [isResizing, setIsResizing] = useState(false);
+  // One shared selection store per editor (not a listener per image).
+  const isSelected = useIsNodeSelected(editor, nodeKey);
   const [isEditorEditable, setIsEditorEditable] = useState(() => editor.isEditable());
   const [currentWidth, setCurrentWidth] = useState<number | "auto">(
     width || "auto",
@@ -181,40 +177,12 @@ function ImageComponent({
     heightRef.current = typeof height === "number" ? height : 0;
   }, [width, height]);
 
-  useEffect(() => {
-    return () => {
-      if (resizeFrameRef.current != null) {
-        window.cancelAnimationFrame(resizeFrameRef.current);
-      }
-      document.body.style.userSelect = "";
-      document.body.style.cursor = "";
-    };
-  }, []);
-
   useEffect(() => {
     return editor.registerEditableListener((editable) => {
       setIsEditorEditable(editable);
     });
   }, [editor]);
 
-  // Listen for selection changes
-  useEffect(() => {
-    if (!nodeKey) return;
-    return editor.registerUpdateListener(({ editorState }) => {
-      editorState.read(() => {
-        const selection = $getSelection();
-        if ($isNodeSelection(selection)) {
-          const selectedNodes = selection.getNodes();
-          setIsSelected(
-            selectedNodes.some((node) => node.getKey() === nodeKey),
-          );
-        } else {
-          setIsSelected(false);
-        }
-      });
-    });
-  }, [editor, nodeKey]);
-
   // Handle click to select
   const onClick = (event: React.MouseEvent) => {
     if (!isEditorEditable) {
@@ -231,116 +199,31 @@ function ImageComponent({
     });
   };
 
-  const startResize =
-    (axis: "width" | "height") =>
-    (event: React.MouseEvent<HTMLButtonElement>) => {
-    if (!isEditorEditable || !imageRef.current || !nodeKey) {
-      return;
-    }
-
-    event.preventDefault();
-    event.stopPropagation();
-    setIsResizing(true);
-    document.body.style.userSelect = "none";
-    document.body.style.cursor = axis === "width" ? "ew-resize" : "ns-resize";
-
-    const startX = event.clientX;
-    const startY = event.clientY;
-    const startWidth =
-      imageRef.current.clientWidth ||
-      (typeof currentWidth === "number" ? currentWidth : 100);
-    const startHeight =
-      imageRef.current.clientHeight ||
-      (typeof currentHeight === "number" ? currentHeight : 100);
-    const hasRatioBaseline =
-      Number.isFinite(startWidth) &&
-      Number.isFinite(startHeight) &&
-      startWidth > 0 &&
-      startHeight > 0;
-    const aspectRatio = hasRatioBaseline ? startWidth / startHeight : null;
-
-    widthRef.current = startWidth;
-    heightRef.current = startHeight;
-
-    const applyPreviewSize = () => {
-      resizeFrameRef.current = null;
-      if (shellRef.current) {
-        shellRef.current.style.width = `${widthRef.current}px`;
-      }
-      if (imageRef.current) {
-        imageRef.current.style.height = `${heightRef.current}px`;
-      }
-    };
-
-    const onMove = (moveEvent: MouseEvent) => {
-      const useRatio =
-        !!aspectRatio &&
-        (scaleByRatio ? !moveEvent.shiftKey : moveEvent.shiftKey);
-      let nextWidth =
-        axis === "width"
-          ? clampSize(
-              startWidth + (moveEvent.clientX - startX),
-              MIN_IMAGE_WIDTH,
-              MAX_IMAGE_WIDTH,
-            )
-          : widthRef.current;
-      let nextHeight =
-        axis === "height"
-          ? clampSize(
-              startHeight + (moveEvent.clientY - startY),
-              MIN_IMAGE_HEIGHT,
-              MAX_IMAGE_HEIGHT,
-            )
-          : heightRef.current;
-
-      if (useRatio && aspectRatio) {
-        if (axis === "width") {
-          nextHeight = clampSize(
-            nextWidth / aspectRatio,
-            MIN_IMAGE_HEIGHT,
-            MAX_IMAGE_HEIGHT,
-          );
-        } else {
-          nextWidth = clampSize(
-            nextHeight * aspectRatio,
-            MIN_IMAGE_WIDTH,
-            MAX_IMAGE_WIDTH,
-          );
-        }
-      }
-
+  // Width-only, aspect-locked resize through pointer capture: the picture keeps
+  // its shape (height follows), the drag survives leaving the handle or the
+  // window, and the document changes once, on release.
+  const { onPointerDown: onResizePointerDown, resizing: isResizing } = usePointerResize({
+    frameRef: shellRef,
+    minWidth: MIN_IMAGE_WIDTH,
+    maxWidth: () =>
+      Math.min(
+        MAX_IMAGE_WIDTH,
+        shellRef.current?.parentElement?.getBoundingClientRect().width || MAX_IMAGE_WIDTH,
+      ),
+    centered: alignment === "center",
+    onCommit: (nextWidth) => {
+      if (!nodeKey) return;
       widthRef.current = nextWidth;
-      heightRef.current = nextHeight;
-
-      if (resizeFrameRef.current == null) {
-        resizeFrameRef.current = window.requestAnimationFrame(applyPreviewSize);
-      }
-    };
-
-    const onUp = () => {
-      if (resizeFrameRef.current != null) {
-        window.cancelAnimationFrame(resizeFrameRef.current);
-        resizeFrameRef.current = null;
-      }
-
-      setIsResizing(false);
-      setCurrentWidth(widthRef.current);
-      setCurrentHeight(heightRef.current);
+      setCurrentWidth(nextWidth);
+      setCurrentHeight("auto");
       editor.update(() => {
         const node = $getNodeByKey(nodeKey);
         if (node instanceof ImageNode) {
-          node.setWidthAndHeight(widthRef.current, heightRef.current);
+          node.setWidthAndHeight(nextWidth, undefined);
         }
       });
-      document.body.style.userSelect = "";
-      document.body.style.cursor = "";
-      document.removeEventListener("mousemove", onMove);
-      document.removeEventListener("mouseup", onUp);
-    };
-
-    document.addEventListener("mousemove", onMove);
-    document.addEventListener("mouseup", onUp);
-  };
+    },
+  });
 
   const figureStyle: React.CSSProperties = {
     margin: 0,
@@ -366,10 +249,11 @@ function ImageComponent({
     textAlign: "center",
   };
 
+  // Handles stay up for the whole drag (hiding them mid-drag was disorienting).
   const showResizeHandles = shouldShowImageResizeHandles(
     isEditorEditable,
     isSelected,
-    isResizing,
+    false,
     resizable,
   );
 
@@ -415,20 +299,15 @@ function ImageComponent({
             <button
               type="button"
               className="luthor-media-embed-resize-handle-width"
-              aria-label="Resize image width"
+              aria-label="Resize image"
               aria-hidden={!showResizeHandles}
               tabIndex={showResizeHandles ? 0 : -1}
-              style={{ opacity: showResizeHandles ? 1 : 0, pointerEvents: showResizeHandles ? "auto" : "none" }}
-              onMouseDown={startResize("width")}
-            />
-            <button
-              type="button"
-              className="luthor-media-embed-resize-handle-height"
-              aria-label="Resize image height"
-              aria-hidden={!showResizeHandles}
-              tabIndex={showResizeHandles ? 0 : -1}
-              style={{ opacity: showResizeHandles ? 1 : 0, pointerEvents: showResizeHandles ? "auto" : "none" }}
-              onMouseDown={startResize("height")}
+              style={{
+                opacity: showResizeHandles ? 1 : 0,
+                pointerEvents: showResizeHandles ? "auto" : "none",
+                touchAction: "none",
+              }}
+              onPointerDown={onResizePointerDown("right")}
             />
           </>
         ) : null}
@@ -647,7 +526,7 @@ export class ImageNode extends DecoratorNode<ReactNode> {
     return this.__height;
   }
 
-  setWidthAndHeight(width: number, height: number): void {
+  setWidthAndHeight(width: number | undefined, height: number | undefined): void {
     const writable = this.getWritable();
     writable.__width = width;
     writable.__height = height;
@@ -1089,7 +968,10 @@ export class ImageExtension extends BaseExtension<
       );
     }
 
+    const removeClickSelect = registerClickToSelect(editor, (node) => node instanceof ImageNode);
+
     return () => {
+      removeClickSelect();
       removeSelectionTracker();
       removeCommand();
       removeDelete();
diff --git a/packages/headless/src/extensions/media/MediaFrame.tsx b/packages/headless/src/extensions/media/MediaFrame.tsx
index 9a71aaea..9be6e63c 100644
--- a/packages/headless/src/extensions/media/MediaFrame.tsx
+++ b/packages/headless/src/extensions/media/MediaFrame.tsx
@@ -7,17 +7,28 @@
 
 import {
   useCallback,
+  useContext,
+  useEffect,
+  useRef,
   useState,
   useSyncExternalStore,
   type CSSProperties,
   type ReactNode,
 } from "react";
+import { LexicalComposerContext } from "@lexical/react/LexicalComposerContext";
+import type { LexicalEditor } from "lexical";
 import {
   useEmbedResolvers,
   type EmbedResolvers,
+  type MediaEdit,
   type MediaMeta,
+  type MediaToolbarContext,
+  type MediaToolbarItem,
 } from "../embeds/EmbedResolverContext";
+import { useEditorPrompt } from "./EditorPromptContext";
 import { classifyMedia, type MediaAlignment } from "./mediaGrammar";
+import { useIsEditable, useIsNodeSelected } from "./mediaSelection";
+import { usePointerResize } from "./usePointerResize";
 
 /** Everything a media frame needs to draw an attachment. */
 export interface MediaFrameProps {
@@ -35,10 +46,20 @@ export interface MediaFrameProps {
   caption?: string;
   /** Rendered inside a line of text rather than as its own block. */
   inline?: boolean;
+  /**
+   * The Lexical node this frame draws. With it (inside an editable editor) the
+   * frame becomes interactive: click to select, drag to resize, a toolbar.
+   */
+  nodeKey?: string;
+  /** Apply an edit to the node (one `editor.update`). */
+  onEdit?: (editor: LexicalEditor, edit: MediaEdit) => void;
+  /** Remove the node. */
+  onRemove?: (editor: LexicalEditor) => void;
 }
 
 const THUMB_WIDTHS = [320, 640, 1280];
 const NO_SUBSCRIPTION = () => () => {};
+const MIN_WIDTH = 48;
 
 function useMediaMeta(resolvers: EmbedResolvers, target: string): MediaMeta | null | undefined {
   const subscribe = resolvers.subscribeMediaMeta ?? NO_SUBSCRIPTION;
@@ -82,6 +103,29 @@ function withRetry(url: string, attempt: number): string {
   return `${url}${url.includes("?") ? "&" : "?"}retry=${attempt}`;
 }
 
+// ── Icons (inline, currentColor, 16px grid) ──────────────────────────────────
+
+function Icon({ d }: { d: string }): ReactNode {
+  return (
+    <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5"
+      strokeLinecap="round" strokeLinejoin="round" aria-hidden="true" focusable="false">
+      <path d={d} />
+    </svg>
+  );
+}
+const ICONS = {
+  alignLeft: "M2.5 3.5h11M2.5 6.5h7M2.5 9.5h11M2.5 12.5h7",
+  alignCenter: "M2.5 3.5h11M4.5 6.5h7M2.5 9.5h11M4.5 12.5h7",
+  alignRight: "M2.5 3.5h11M6.5 6.5h7M2.5 9.5h11M6.5 12.5h7",
+  caption: "M2.5 3.5h11v6h-11zM4.5 12.5h7",
+  alt: "M3 12.5l2.5-9 2.5 9M3.8 9.5h3.4M10.5 3.5v9h3",
+  open: "M9 2.5h4.5V7M13.5 2.5L7.5 8.5M12 9.5v4H2.5V4h4",
+  remove: "M3 4.5h10M6.5 4.5V3h3v1.5M4.5 4.5l.7 9h5.6l.7-9",
+  reset: "M3 8a5 5 0 1 0 1.5-3.5M3 2.5v3h3",
+};
+
+// ── The frame ────────────────────────────────────────────────────────────────
+
 /**
  * The shared view for an embedded attachment: pictures, video, audio, PDFs and
  * other files. It is built to never shift the page and never break:
@@ -94,14 +138,32 @@ function withRetry(url: string, attempt: number): string {
  *   Video loads only its metadata until played, behind its poster.
  * - **A failure is a card, not a broken-image glyph**, with Retry and a way to
  *   open the file. The markdown is never touched.
+ *
+ * Given a `nodeKey` inside an editable editor it is also interactive: a click
+ * selects it; a selected picture or video shows resize handles and a toolbar
+ * (alignment, size, caption, alt text, open, remove, plus the host's items).
+ * The toolbar lives inside the frame — anchored to the picture itself, mounted
+ * only while it is selected — so it can't drift on scroll or blink on a click.
  */
 export function MediaFrame(props: MediaFrameProps): ReactNode {
-  const { target, fragment = "", alt, width, height, align, caption, inline = false } = props;
+  const { target, fragment = "", alt, width, height, align, caption, inline = false, nodeKey, onEdit, onRemove } = props;
   const resolvers = useEmbedResolvers();
   const meta = useMediaMeta(resolvers, target);
+  const composer = useContext(LexicalComposerContext);
+  const editor: LexicalEditor | null = composer ? composer[0] : null;
+  const isEditable = useIsEditable(editor);
+  const isSelected = useIsNodeSelected(editor, nodeKey);
+  const requestPrompt = useEditorPrompt();
   const [attempt, setAttempt] = useState(0);
   // Keyed by URL: replacing the file (a new target) starts clean.
   const [failedUrl, setFailedUrl] = useState<string | null>(null);
+  const figureRef = useRef<HTMLElement | null>(null);
+  const frameRef = useRef<HTMLElement | null>(null);
+  const badgeRef = useRef<HTMLSpanElement | null>(null);
+  const toolbarRef = useRef<HTMLDivElement | null>(null);
+  const actionsRef = useRef<Map<string, () => void>>(new Map());
+  // A small picture gets its toolbar underneath rather than covering it.
+  const [compact, setCompact] = useState(false);
 
   const resolve = resolvers.resolveMediaUrl;
   const url = typeof resolve === "function" ? resolve(target) : "";
@@ -109,6 +171,70 @@ export function MediaFrame(props: MediaFrameProps): ReactNode {
   const label = alt?.trim() || target;
   const failed = failedUrl !== null && failedUrl === url;
   const setFailed = (value: boolean) => setFailedUrl(value ? url : null);
+  const interactive = !!(editor && nodeKey && onEdit && isEditable);
+  const resizable = interactive && !inline && !failed && (kind === "image" || kind === "video");
+
+  const edit = useCallback(
+    (change: MediaEdit) => {
+      if (editor && onEdit) onEdit(editor, change);
+    },
+    [editor, onEdit],
+  );
+
+  const containerWidth = () =>
+    figureRef.current?.parentElement?.getBoundingClientRect().width ||
+    figureRef.current?.getBoundingClientRect().width ||
+    Number.POSITIVE_INFINITY;
+
+  const { onPointerDown, resizing } = usePointerResize({
+    frameRef,
+    minWidth: MIN_WIDTH,
+    maxWidth: containerWidth,
+    centered: align === "center",
+    onPreview: (w) => {
+      if (badgeRef.current) badgeRef.current.textContent = w === null ? "" : `${w} px`;
+    },
+    // Keep the box's shape when it has one of its own (`|WxH`); otherwise the
+    // file's own ratio follows the new width.
+    onCommit: (w) =>
+      edit({ width: w, height: positive(width) && positive(height) ? Math.round((w * height!) / width!) : null }),
+  });
+
+  useEffect(() => {
+    const frame = frameRef.current;
+    if (!frame || !isSelected || inline || typeof ResizeObserver === "undefined") return;
+    const measure = () => setCompact(frame.getBoundingClientRect().width < 360);
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(frame);
+    return () => observer.disconnect();
+  }, [isSelected, inline]);
+
+  // Toolbar buttons are handled natively: a click inside a decorator reaches
+  // the editor's own root listeners before React sees it, and must neither
+  // move the selection nor steal focus from the editor.
+  useEffect(() => {
+    const toolbar = toolbarRef.current;
+    if (!toolbar) return;
+    const swallow = (event: Event) => {
+      event.preventDefault();
+      event.stopPropagation();
+    };
+    const onClick = (event: MouseEvent) => {
+      swallow(event);
+      const button = (event.target as Element | null)?.closest?.("[data-media-action]");
+      const id = button?.getAttribute("data-media-action");
+      if (id && !button?.hasAttribute("disabled")) actionsRef.current.get(id)?.();
+    };
+    toolbar.addEventListener("mousedown", swallow);
+    toolbar.addEventListener("pointerdown", swallow);
+    toolbar.addEventListener("click", onClick);
+    return () => {
+      toolbar.removeEventListener("mousedown", swallow);
+      toolbar.removeEventListener("pointerdown", swallow);
+      toolbar.removeEventListener("click", onClick);
+    };
+  });
 
   // No host to resolve the file: a reference chip, so the embed stays visible.
   if (!url) {
@@ -137,11 +263,16 @@ export function MediaFrame(props: MediaFrameProps): ReactNode {
           ? "16 / 9"
           : undefined;
 
-  const frameStyle: CSSProperties = {
-    ...(displayWidth ? { width: `min(${Math.round(displayWidth)}px, 100%)` } : {}),
-  };
+  // A known width fills its (capped) box; an unknown one shows the file at its
+  // own size, never stretched past it.
+  const frameStyle: CSSProperties = displayWidth
+    ? { width: `min(${Math.round(displayWidth)}px, 100%)` }
+    : kind === "image"
+      ? { width: "fit-content", maxWidth: "100%" }
+      : {};
   const mediaStyle: CSSProperties = {
-    width: "100%",
+    width: displayWidth || kind !== "image" ? "100%" : "auto",
+    maxWidth: "100%",
     height: "auto",
     ...(ratio ? { aspectRatio: ratio } : {}),
     objectFit: "contain",
@@ -242,6 +373,11 @@ export function MediaFrame(props: MediaFrameProps): ReactNode {
           target="_blank"
           rel="noopener noreferrer"
           data-luthor-file-embed-target={target}
+          onClick={(event) => {
+            // In an editable note the first click selects the card; opening it
+            // is the toolbar's "Open" (or a modifier click).
+            if (interactive && !event.metaKey && !event.ctrlKey) event.preventDefault();
+          }}
         >
           <span className="luthor-media__card-icon" aria-hidden="true">
             {extensionLabel(target)}
@@ -256,28 +392,171 @@ export function MediaFrame(props: MediaFrameProps): ReactNode {
     );
   }
 
+  // ── Toolbar ──
+  let toolbar: ReactNode = null;
+  if (interactive && isSelected && !inline && !resizing) {
+    const context: MediaToolbarContext = {
+      target, fragment, kind, url, meta, width, height, align, caption, alt,
+      update: edit,
+      remove: () => editor && onRemove?.(editor),
+    };
+    const items: MediaToolbarItem[] = [];
+    if (resolvers.mediaToolbar?.builtIn !== false) {
+      const setAlign = (next: MediaAlignment) => edit({ align: align === next ? null : next });
+      items.push(
+        { id: "align-left", label: "Align left", icon: <Icon d={ICONS.alignLeft} />, active: align === "left", onSelect: () => setAlign("left") },
+        { id: "align-center", label: "Centre", icon: <Icon d={ICONS.alignCenter} />, active: align === "center", onSelect: () => setAlign("center") },
+        { id: "align-right", label: "Align right", icon: <Icon d={ICONS.alignRight} />, active: align === "right", onSelect: () => setAlign("right") },
+      );
+      if (kind === "image" || kind === "video") {
+        for (const [fraction, text] of [[0.25, "¼"], [0.5, "½"], [0.75, "¾"], [1, "Full"]] as const) {
+          items.push({
+            id: `size-${fraction}`,
+            label: fraction === 1 ? "Full width" : `${text} width`,
+            onSelect: () => {
+              const full = containerWidth();
+              if (Number.isFinite(full)) edit({ width: Math.max(MIN_WIDTH, Math.round(full * fraction)), height: null });
+            },
+          });
+        }
+        if (positive(width)) {
+          items.push({ id: "size-reset", label: "Original size", icon: <Icon d={ICONS.reset} />, onSelect: () => edit({ width: null, height: null }) });
+        }
+      }
+      items.push({
+        id: "caption",
+        label: caption ? "Edit caption" : "Add caption",
+        icon: <Icon d={ICONS.caption} />,
+        active: !!caption,
+        onSelect: () => {
+          void requestPrompt({
+            title: caption ? "Edit caption" : "Add caption",
+            submitLabel: "Save",
+            fields: [{ name: "caption", label: "Caption", value: caption ?? "", placeholder: "Shown under the file" }],
+          }).then((values) => {
+            if (values) edit({ caption: values.caption || null });
+          });
+        },
+      });
+      if (kind === "image") {
+        items.push({
+          id: "alt",
+          label: "Alt text",
+          icon: <Icon d={ICONS.alt} />,
+          active: !!alt,
+          onSelect: () => {
+            void requestPrompt({
+              title: "Alt text",
+              submitLabel: "Save",
+              fields: [{ name: "alt", label: "Describe the picture for screen readers", value: alt ?? "" }],
+            }).then((values) => {
+              if (values) edit({ alt: values.alt || null });
+            });
+          },
+        });
+      }
+      items.push({
+        id: "open",
+        label: "Open in new tab",
+        icon: <Icon d={ICONS.open} />,
+        onSelect: () => window.open(url, "_blank", "noopener,noreferrer"),
+      });
+    }
+    const hostItems = resolvers.mediaToolbar?.items?.(context) ?? [];
+    items.push(...hostItems);
+    if (resolvers.mediaToolbar?.builtIn !== false) {
+      items.push({ id: "remove", label: "Remove", icon: <Icon d={ICONS.remove} />, onSelect: () => context.remove() });
+    }
+
+    actionsRef.current = new Map(items.map((item) => [item.id, item.onSelect]));
+    toolbar = (
+      <div ref={toolbarRef} className={`luthor-media__toolbar${compact ? " is-compact" : ""}`} role="toolbar" aria-label="Attachment" contentEditable={false}>
+        {items.map((item) => (
+          <button
+            key={item.id}
+            type="button"
+            className={`luthor-media__tool${item.active ? " is-active" : ""}${item.icon ? "" : " luthor-media__tool--text"}`}
+            data-media-action={item.id}
+            aria-label={item.label}
+            aria-pressed={item.active === undefined ? undefined : item.active}
+            title={item.label}
+            disabled={item.disabled}
+          >
+            {item.icon ?? item.label.replace(/ width$/, "")}
+          </button>
+        ))}
+      </div>
+    );
+  }
+
+  const handles = resizable && isSelected ? (
+    <>
+      <span
+        className="luthor-media__handle luthor-media__handle--left"
+        role="separator"
+        aria-orientation="vertical"
+        aria-label="Resize"
+        onPointerDown={onPointerDown("left")}
+      />
+      <span
+        className="luthor-media__handle luthor-media__handle--right"
+        role="separator"
+        aria-orientation="vertical"
+        aria-label="Resize"
+        onPointerDown={onPointerDown("right")}
+      />
+      <span ref={badgeRef} className="luthor-media__size-badge" aria-live="polite" />
+    </>
+  ) : null;
+
   const className = [
     "luthor-media",
     `luthor-media--${kind}`,
     inline ? "luthor-media--inline" : "luthor-media--block",
     align ? `luthor-media--align-${align}` : "",
     failed ? "luthor-media--failed" : "",
+    interactive ? "is-interactive" : "",
+    isSelected ? "is-selected" : "",
+    resizing ? "is-resizing" : "",
   ]
     .filter(Boolean)
     .join(" ");
 
   if (inline) {
     return (
-      <span className={className} data-luthor-media-kind={kind} style={frameStyle}>
+      <span
+        ref={(el) => {
+          figureRef.current = el;
+          frameRef.current = el;
+        }}
+        className={className}
+        data-luthor-media-kind={kind}
+        style={frameStyle}
+      >
         {body}
       </span>
     );
   }
 
   return (
-    <figure className={className} data-luthor-media-kind={kind} data-align={align ?? "none"}>
-      <div className="luthor-media__frame" style={frameStyle}>
+    <figure
+      ref={(el) => {
+        figureRef.current = el;
+      }}
+      className={className}
+      data-luthor-media-kind={kind}
+      data-align={align ?? "none"}
+    >
+      <div
+        ref={(el) => {
+          frameRef.current = el;
+        }}
+        className="luthor-media__frame"
+        style={frameStyle}
+      >
         {body}
+        {handles}
+        {toolbar}
       </div>
       {caption ? <figcaption className="luthor-media__caption">{caption}</figcaption> : null}
     </figure>
diff --git a/packages/headless/src/extensions/media/MediaInteraction.test.tsx b/packages/headless/src/extensions/media/MediaInteraction.test.tsx
new file mode 100644
index 00000000..f0618333
--- /dev/null
+++ b/packages/headless/src/extensions/media/MediaInteraction.test.tsx
@@ -0,0 +1,247 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+/* @vitest-environment jsdom */
+
+import { act, fireEvent, render } from "@testing-library/react";
+import { LexicalComposer } from "@lexical/react/LexicalComposer";
+import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
+import { ContentEditable } from "@lexical/react/LexicalContentEditable";
+import { LexicalErrorBoundary } from "@lexical/react/LexicalErrorBoundary";
+import { RichTextPlugin } from "@lexical/react/LexicalRichTextPlugin";
+import {
+  $createParagraphNode,
+  $getRoot,
+  $getSelection,
+  $isNodeSelection,
+  KEY_DOWN_COMMAND,
+  type LexicalEditor,
+} from "lexical";
+import { useEffect } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { EmbedResolverProvider, type EmbedResolvers } from "../embeds/EmbedResolverContext";
+import {
+  $createFileEmbedNode,
+  $isFileEmbedNode,
+  FileEmbedNode,
+  fileEmbedExtension,
+  type FileEmbedFields,
+} from "../embeds/FileEmbedNode";
+import { EditorPromptProvider, type RequestPrompt } from "./EditorPromptContext";
+
+if (typeof window.PointerEvent === "undefined") {
+  class PointerEventPolyfill extends MouseEvent {
+    pointerId: number;
+    constructor(type: string, init: PointerEventInit = {}) {
+      super(type, init);
+      this.pointerId = init.pointerId ?? 0;
+    }
+  }
+  (window as unknown as { PointerEvent: typeof PointerEventPolyfill }).PointerEvent = PointerEventPolyfill;
+}
+
+beforeEach(() => {
+  vi.spyOn(window, "requestAnimationFrame").mockImplementation((cb) => {
+    cb(0);
+    return 1;
+  });
+  // The media frame is 300px wide inside an 800px-wide note.
+  vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function (this: HTMLElement) {
+    const width = this.classList.contains("luthor-media__frame") || this.classList.contains("luthor-media--inline") ? 300 : 800;
+    return { width, height: 200, top: 0, left: 0, right: width, bottom: 200, x: 0, y: 0, toJSON: () => ({}) } as DOMRect;
+  });
+});
+afterEach(() => vi.restoreAllMocks());
+
+function Capture({ onEditor }: { onEditor: (editor: LexicalEditor) => void }) {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => {
+    onEditor(editor);
+    return fileEmbedExtension.register(editor);
+  }, [editor, onEditor]);
+  return null;
+}
+
+async function mountEditor(
+  fields: FileEmbedFields = { target: "photo.png" },
+  resolvers: EmbedResolvers = {},
+  requestPrompt?: RequestPrompt,
+) {
+  let editor: LexicalEditor | null = null;
+  const tree = (
+    <LexicalComposer
+      initialConfig={{
+        namespace: "media-interaction",
+        nodes: [FileEmbedNode],
+        onError: (error) => {
+          throw error;
+        },
+        editorState: () => {
+          const root = $getRoot();
+          root.append($createParagraphNode(), $createFileEmbedNode(fields), $createParagraphNode());
+        },
+      }}
+    >
+      <EmbedResolverProvider resolvers={{ resolveMediaUrl: (t) => `/m/${t}`, ...resolvers }}>
+        <RichTextPlugin contentEditable={<ContentEditable />} ErrorBoundary={LexicalErrorBoundary} />
+      </EmbedResolverProvider>
+      <Capture onEditor={(e) => (editor = e)} />
+    </LexicalComposer>
+  );
+  const view = render(requestPrompt ? <EditorPromptProvider requestPrompt={requestPrompt}>{tree}</EditorPromptProvider> : tree);
+  await act(async () => {});
+  return { ...view, editor: editor as unknown as LexicalEditor };
+}
+
+function embed(editor: LexicalEditor): FileEmbedNode {
+  return editor.getEditorState().read(() => $getRoot().getChildren().find($isFileEmbedNode)!) as FileEmbedNode;
+}
+
+function markdown(editor: LexicalEditor): string {
+  return editor.getEditorState().read(() => embed(editor).getMarkdown());
+}
+
+async function select(container: HTMLElement) {
+  await act(async () => {
+    fireEvent.click(container.querySelector(".luthor-media__frame")!);
+  });
+}
+
+async function tool(container: HTMLElement, id: string) {
+  const button = container.querySelector(`[data-media-action="${id}"]`);
+  expect(button, id).not.toBeNull();
+  await act(async () => {
+    button!.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+  });
+}
+
+describe("media frame in the editor", () => {
+  it("a click selects it and shows its toolbar and handles", async () => {
+    const { container, editor } = await mountEditor();
+    expect(container.querySelector(".luthor-media__toolbar")).toBeNull();
+    await select(container);
+    expect(container.querySelector(".luthor-media.is-selected")).not.toBeNull();
+    expect(container.querySelector(".luthor-media__toolbar")).not.toBeNull();
+    expect(container.querySelectorAll(".luthor-media__handle")).toHaveLength(2);
+    editor.getEditorState().read(() => expect($isNodeSelection($getSelection())).toBe(true));
+  });
+
+  it("clicking a selected picture again never remounts its toolbar (no blink)", async () => {
+    const { container } = await mountEditor();
+    await select(container);
+    const toolbar = container.querySelector(".luthor-media__toolbar")!;
+    const removed: Node[] = [];
+    const observer = new MutationObserver((records) => records.forEach((r) => removed.push(...r.removedNodes)));
+    observer.observe(container, { childList: true, subtree: true });
+    for (let i = 0; i < 20; i++) await select(container);
+    await act(async () => {});
+    observer.disconnect();
+    expect(container.querySelector(".luthor-media__toolbar")).toBe(toolbar);
+    expect(removed.filter((n) => n === toolbar || (n as Element).contains?.(toolbar))).toHaveLength(0);
+  });
+
+  it("toolbar alignment toggles, and lands in the markdown", async () => {
+    const { container, editor } = await mountEditor();
+    await select(container);
+    await tool(container, "align-center");
+    expect(markdown(editor)).toBe("![[photo.png]] <!-- align:center -->");
+    await tool(container, "align-center");
+    expect(markdown(editor)).toBe("![[photo.png]]");
+  });
+
+  it("size presets use the container; Original size clears it", async () => {
+    const { container, editor } = await mountEditor();
+    await select(container);
+    await tool(container, "size-0.5");
+    expect(markdown(editor)).toBe("![[photo.png|400]]");
+    await tool(container, "size-reset");
+    expect(markdown(editor)).toBe("![[photo.png]]");
+  });
+
+  it("caption and alt text go through the editor's prompt", async () => {
+    const prompt = vi.fn<RequestPrompt>(async (request): Promise<Record<string, string>> =>
+      request.fields[0]!.name === "caption" ? { caption: "Dusk" } : { alt: "A beach" },
+    );
+    const { container, editor } = await mountEditor({ target: "photo.png" }, {}, prompt);
+    await select(container);
+    await tool(container, "caption");
+    await tool(container, "alt");
+    expect(markdown(editor)).toBe("![[photo.png|A beach]] <!-- caption:Dusk -->");
+    expect(prompt.mock.calls[0]![0].fields[0]!.value).toBe("");
+  });
+
+  it("Remove deletes it and keeps the caret in the document", async () => {
+    const { container, editor } = await mountEditor();
+    await select(container);
+    await tool(container, "remove");
+    editor.getEditorState().read(() => {
+      expect($getRoot().getChildren().some($isFileEmbedNode)).toBe(false);
+      expect($getSelection()).not.toBeNull();
+    });
+  });
+
+  it("host items appear, get the embed's context, and can replace the built-ins", async () => {
+    const onSelect = vi.fn();
+    const { container } = await mountEditor(
+      { target: "photo.png", width: 200 },
+      { mediaToolbar: { builtIn: false, items: (ctx) => [{ id: "replace", label: `Replace ${ctx.target} @${ctx.width}`, onSelect }] } },
+    );
+    await select(container);
+    expect(container.querySelector('[data-media-action="align-left"]')).toBeNull();
+    expect(container.querySelector('[data-media-action="replace"]')!.getAttribute("aria-label")).toBe("Replace photo.png @200");
+    await tool(container, "replace");
+    expect(onSelect).toHaveBeenCalledTimes(1);
+  });
+
+  it("dragging a handle commits exactly one change", async () => {
+    const { container, editor } = await mountEditor();
+    const updates = vi.fn();
+    editor.registerMutationListener(FileEmbedNode, (mutations) => updates(mutations), { skipInitialization: true });
+    await select(container);
+    const handle = container.querySelector(".luthor-media__handle--right")!;
+    await act(async () => {
+      fireEvent.pointerDown(handle, { pointerId: 1, button: 0, clientX: 300 });
+      for (let x = 305; x <= 400; x += 5) fireEvent.pointerMove(handle, { pointerId: 1, clientX: x });
+      fireEvent.pointerUp(handle, { pointerId: 1, clientX: 400 });
+    });
+    expect(markdown(editor)).toBe("![[photo.png|400]]");
+    expect(updates).toHaveBeenCalledTimes(1);
+  });
+
+  it("keyboard: Shift+→ grows 10px, Alt+Shift+← shrinks 1px, Enter opens a line, Escape lets go", async () => {
+    const { container, editor } = await mountEditor();
+    await select(container);
+    const key = (init: KeyboardEventInit) =>
+      act(async () => {
+        editor.dispatchCommand(KEY_DOWN_COMMAND, new KeyboardEvent("keydown", init));
+      });
+    await key({ key: "ArrowRight", shiftKey: true });
+    expect(markdown(editor)).toBe("![[photo.png|310]]");
+    await key({ key: "ArrowLeft", shiftKey: true, altKey: true });
+    expect(markdown(editor)).toBe("![[photo.png|309]]");
+    await key({ key: "Escape" });
+    editor.getEditorState().read(() => expect($getSelection()).toBeNull());
+
+    await select(container);
+    await key({ key: "Enter" });
+    editor.getEditorState().read(() => {
+      const children = $getRoot().getChildren();
+      const index = children.findIndex($isFileEmbedNode);
+      expect(children[index + 1]!.getType()).toBe("paragraph");
+      expect($isNodeSelection($getSelection())).toBe(false);
+    });
+  });
+
+  it("read-only: no selection, toolbar or handles", async () => {
+    const { container, editor } = await mountEditor();
+    await act(async () => editor.setEditable(false));
+    await select(container);
+    expect(container.querySelector(".luthor-media.is-selected")).toBeNull();
+    expect(container.querySelector(".luthor-media__toolbar")).toBeNull();
+    expect(container.querySelector(".luthor-media__handle")).toBeNull();
+  });
+});
diff --git a/packages/headless/src/extensions/media/YouTubeEmbedExtension.tsx b/packages/headless/src/extensions/media/YouTubeEmbedExtension.tsx
index 3281b83a..391e615f 100644
--- a/packages/headless/src/extensions/media/YouTubeEmbedExtension.tsx
+++ b/packages/headless/src/extensions/media/YouTubeEmbedExtension.tsx
@@ -6,6 +6,7 @@
  */
 
 import { formatSize, splitCaptionAndSize } from "./mediaGrammar";
+import { registerClickToSelect } from "./mediaSelection";
 import React, { ReactNode, useEffect, useMemo, useRef, useState } from "react";
 import {
   $createNodeSelection,
@@ -746,7 +747,7 @@ export class YouTubeEmbedExtension extends BaseExtension<
   }
 
   register(editor: LexicalEditor): () => void {
-    return editor.registerUpdateListener(({ editorState }) => {
+    const removeTracker = editor.registerUpdateListener(({ editorState }) => {
       editorState.read(() => {
         const selection = $getSelection();
         if (!$isNodeSelection(selection)) {
@@ -759,6 +760,11 @@ export class YouTubeEmbedExtension extends BaseExtension<
         }
       });
     });
+    const removeClickSelect = registerClickToSelect(editor, (node) => node instanceof YouTubeEmbedNode);
+    return () => {
+      removeTracker();
+      removeClickSelect();
+    };
   }
 
   getNodes(): any[] {
diff --git a/packages/headless/src/extensions/media/index.ts b/packages/headless/src/extensions/media/index.ts
index ce720769..f220e6bb 100644
--- a/packages/headless/src/extensions/media/index.ts
+++ b/packages/headless/src/extensions/media/index.ts
@@ -11,3 +11,6 @@ export * from "./IframeEmbedExtension";
 export * from "./YouTubeEmbedExtension";
 export * from "./mediaGrammar";
 export { MediaFrame, formatBytes, type MediaFrameProps } from "./MediaFrame";
+export * from "./EditorPromptContext";
+export * from "./mediaSelection";
+export * from "./usePointerResize";
diff --git a/packages/headless/src/extensions/media/mediaSelection.ts b/packages/headless/src/extensions/media/mediaSelection.ts
new file mode 100644
index 00000000..79ae9ba9
--- /dev/null
+++ b/packages/headless/src/extensions/media/mediaSelection.ts
@@ -0,0 +1,146 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+import { useCallback, useSyncExternalStore } from "react";
+import {
+  $createNodeSelection,
+  $getNearestNodeFromDOMNode,
+  $getSelection,
+  $isNodeSelection,
+  $setSelection,
+  CLICK_COMMAND,
+  COMMAND_PRIORITY_LOW,
+  type LexicalEditor,
+  type LexicalNode,
+} from "lexical";
+
+/*
+ * Which nodes are selected, as one shared store per editor.
+ *
+ * Every media embed needs to know whether it is the selected one. Giving each
+ * its own update listener costs N listeners and N state updates per keystroke
+ * (and each fired even when nothing about selection changed). Here one listener
+ * per editor keeps the selected keys, and a component re-renders only when *its*
+ * answer flips — via useSyncExternalStore, so there is no effect-then-setState
+ * frame in which the old answer is shown.
+ */
+
+interface SelectionStore {
+  keys: ReadonlySet<string>;
+  editable: boolean;
+  listeners: Set<() => void>;
+}
+
+const stores = new WeakMap<LexicalEditor, SelectionStore>();
+
+function sameKeys(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
+  if (a.size !== b.size) return false;
+  for (const key of a) if (!b.has(key)) return false;
+  return true;
+}
+
+function storeFor(editor: LexicalEditor): SelectionStore {
+  const existing = stores.get(editor);
+  if (existing) return existing;
+  const created: SelectionStore = {
+    keys: new Set(),
+    editable: editor.isEditable(),
+    listeners: new Set(),
+  };
+  stores.set(editor, created);
+  const notify = () => created.listeners.forEach((listener) => listener());
+  const read = () => {
+    const next = new Set<string>();
+    editor.getEditorState().read(() => {
+      const selection = $getSelection();
+      if ($isNodeSelection(selection)) {
+        for (const node of selection.getNodes()) next.add(node.getKey());
+      }
+    });
+    if (!sameKeys(created.keys, next)) {
+      created.keys = next;
+      notify();
+    }
+  };
+  // The listeners live as long as the editor does (the store is keyed weakly
+  // on it), so there is nothing to unregister.
+  editor.registerUpdateListener(read);
+  editor.registerEditableListener((editable) => {
+    if (created.editable !== editable) {
+      created.editable = editable;
+      notify();
+    }
+  });
+  read();
+  return created;
+}
+
+const NO_EDITOR_SUBSCRIBE = () => () => {};
+
+/** Whether the node with `key` is (part of) the editor's node selection. */
+export function useIsNodeSelected(editor: LexicalEditor | null, key: string | undefined): boolean {
+  const subscribe = useCallback(
+    (listener: () => void) => {
+      if (!editor) return () => {};
+      const store = storeFor(editor);
+      store.listeners.add(listener);
+      return () => store.listeners.delete(listener);
+    },
+    [editor],
+  );
+  const read = useCallback(
+    () => (editor && key ? storeFor(editor).keys.has(key) : false),
+    [editor, key],
+  );
+  return useSyncExternalStore(editor ? subscribe : NO_EDITOR_SUBSCRIBE, read, read);
+}
+
+/** Whether the editor is editable, reactively (false without an editor). */
+export function useIsEditable(editor: LexicalEditor | null): boolean {
+  const subscribe = useCallback(
+    (listener: () => void) => {
+      if (!editor) return () => {};
+      const store = storeFor(editor);
+      store.listeners.add(listener);
+      return () => store.listeners.delete(listener);
+    },
+    [editor],
+  );
+  const read = useCallback(() => (editor ? storeFor(editor).editable : false), [editor]);
+  return useSyncExternalStore(editor ? subscribe : NO_EDITOR_SUBSCRIBE, read, read);
+}
+
+/**
+ * Select a decorator node when it is clicked. Must be the click *command*, at a
+ * priority above rich text's own handler — which clears any node selection on
+ * every click, so selecting from a React onClick raced it and the selection
+ * (and the node's toolbar) flickered. `anchorSelector` finds the clickable part
+ * of the node's DOM.
+ */
+export function registerClickToSelect(
+  editor: LexicalEditor,
+  isNode: (node: LexicalNode | null) => boolean,
+  anchorSelector = '[data-luthor-selection-anchor="true"]',
+): () => void {
+  return editor.registerCommand(
+    CLICK_COMMAND,
+    (event: MouseEvent) => {
+      if (!editor.isEditable()) return false;
+      const target = event.target;
+      const element = target instanceof Element ? target : target instanceof Node ? target.parentElement : null;
+      const anchor = element?.closest(anchorSelector);
+      if (!anchor) return false;
+      const node = $getNearestNodeFromDOMNode(anchor);
+      if (!node || !isNode(node)) return false;
+      const selection = $createNodeSelection();
+      selection.add(node.getKey());
+      $setSelection(selection);
+      return true;
+    },
+    COMMAND_PRIORITY_LOW,
+  );
+}
diff --git a/packages/headless/src/extensions/media/usePointerResize.test.tsx b/packages/headless/src/extensions/media/usePointerResize.test.tsx
new file mode 100644
index 00000000..dbfa2b41
--- /dev/null
+++ b/packages/headless/src/extensions/media/usePointerResize.test.tsx
@@ -0,0 +1,141 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+/* @vitest-environment jsdom */
+
+import { fireEvent, render } from "@testing-library/react";
+import { useRef } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { usePointerResize, type ResizeEdge } from "./usePointerResize";
+
+// jsdom has no PointerEvent: without one, pointerId/clientX never arrive.
+if (typeof window.PointerEvent === "undefined") {
+  class PointerEventPolyfill extends MouseEvent {
+    pointerId: number;
+    constructor(type: string, init: PointerEventInit = {}) {
+      super(type, init);
+      this.pointerId = init.pointerId ?? 0;
+    }
+  }
+  (window as unknown as { PointerEvent: typeof PointerEventPolyfill }).PointerEvent = PointerEventPolyfill;
+}
+
+// jsdom has no layout: give the frame a width and run animation frames at once.
+beforeEach(() => {
+  vi.spyOn(window, "requestAnimationFrame").mockImplementation((cb) => {
+    cb(0);
+    return 1;
+  });
+  vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(
+    () => ({ width: 300, height: 200, top: 0, left: 0, right: 300, bottom: 200, x: 0, y: 0, toJSON: () => ({}) }) as DOMRect,
+  );
+});
+afterEach(() => vi.restoreAllMocks());
+
+function Harness(props: { onCommit: (w: number) => void; edge?: ResizeEdge; centered?: boolean; max?: number }) {
+  const frameRef = useRef<HTMLDivElement | null>(null);
+  const { onPointerDown, resizing } = usePointerResize({
+    frameRef,
+    minWidth: 48,
+    maxWidth: () => props.max ?? 800,
+    centered: props.centered,
+    onCommit: props.onCommit,
+  });
+  return (
+    <div ref={frameRef} data-testid="frame" style={{ width: "min(300px, 100%)" }} data-resizing={resizing}>
+      <span data-testid="handle" onPointerDown={onPointerDown(props.edge ?? "right")} />
+    </div>
+  );
+}
+
+function drag(handle: HTMLElement, fromX: number, toX: number) {
+  fireEvent.pointerDown(handle, { pointerId: 1, button: 0, clientX: fromX });
+  fireEvent.pointerMove(handle, { pointerId: 1, clientX: toX });
+}
+
+describe("usePointerResize", () => {
+  it("previews on the frame and commits once, on release", () => {
+    const onCommit = vi.fn();
+    const { getByTestId } = render(<Harness onCommit={onCommit} />);
+    const handle = getByTestId("handle");
+    drag(handle, 300, 400);
+    expect(getByTestId("frame").style.width).toBe("400px");
+    expect(getByTestId("frame").dataset.resizing).toBe("true");
+    expect(onCommit).not.toHaveBeenCalled();
+    fireEvent.pointerUp(handle, { pointerId: 1, clientX: 400 });
+    expect(onCommit).toHaveBeenCalledTimes(1);
+    expect(onCommit).toHaveBeenCalledWith(400);
+    // The inline width goes back to React's value; the commit re-renders it.
+    expect(getByTestId("frame").style.width).toBe("min(300px, 100%)");
+    expect(getByTestId("frame").dataset.resizing).toBe("false");
+  });
+
+  it("an aborted drag (cancel, Escape, window blur) restores and commits nothing", () => {
+    for (const abort of [
+      (h: HTMLElement) => fireEvent.pointerCancel(h, { pointerId: 1 }),
+      () => fireEvent.keyDown(window, { key: "Escape" }),
+      () => fireEvent.blur(window),
+    ]) {
+      const onCommit = vi.fn();
+      const { getByTestId, unmount } = render(<Harness onCommit={onCommit} />);
+      const handle = getByTestId("handle");
+      drag(handle, 300, 500);
+      abort(handle);
+      expect(onCommit).not.toHaveBeenCalled();
+      expect(getByTestId("frame").style.width).toBe("min(300px, 100%)");
+      expect(document.body.style.userSelect).toBe("");
+      unmount();
+    }
+  });
+
+  it("clamps to the minimum and the container", () => {
+    const onCommit = vi.fn();
+    const { getByTestId } = render(<Harness onCommit={onCommit} max={500} />);
+    const handle = getByTestId("handle");
+    drag(handle, 300, 5000);
+    fireEvent.pointerUp(handle, { pointerId: 1 });
+    drag(handle, 300, -5000);
+    fireEvent.pointerUp(handle, { pointerId: 1 });
+    expect(onCommit.mock.calls).toEqual([[500], [48]]);
+  });
+
+  it("left handles grow leftward; centred media moves twice as fast", () => {
+    const left = vi.fn();
+    const a = render(<Harness onCommit={left} edge="left" />);
+    drag(a.getByTestId("handle"), 300, 250);
+    fireEvent.pointerUp(a.getByTestId("handle"), { pointerId: 1 });
+    expect(left).toHaveBeenCalledWith(350);
+    a.unmount();
+
+    const centred = vi.fn();
+    const b = render(<Harness onCommit={centred} centered />);
+    drag(b.getByTestId("handle"), 300, 350);
+    fireEvent.pointerUp(b.getByTestId("handle"), { pointerId: 1 });
+    expect(centred).toHaveBeenCalledWith(400);
+  });
+
+  it("ignores other pointers and non-primary buttons, and a click with no movement commits nothing", () => {
+    const onCommit = vi.fn();
+    const { getByTestId } = render(<Harness onCommit={onCommit} />);
+    const handle = getByTestId("handle");
+    fireEvent.pointerDown(handle, { pointerId: 1, button: 2, clientX: 300 });
+    fireEvent.pointerUp(handle, { pointerId: 1 });
+    fireEvent.pointerDown(handle, { pointerId: 1, button: 0, clientX: 300 });
+    fireEvent.pointerMove(handle, { pointerId: 2, clientX: 600 });
+    fireEvent.pointerUp(handle, { pointerId: 1, clientX: 300 });
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+
+  it("unmounting mid-drag leaves nothing behind", () => {
+    const onCommit = vi.fn();
+    const { getByTestId, unmount } = render(<Harness onCommit={onCommit} />);
+    drag(getByTestId("handle"), 300, 420);
+    unmount();
+    expect(document.body.style.userSelect).toBe("");
+    expect(onCommit).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/headless/src/extensions/media/usePointerResize.ts b/packages/headless/src/extensions/media/usePointerResize.ts
new file mode 100644
index 00000000..5a9fdb61
--- /dev/null
+++ b/packages/headless/src/extensions/media/usePointerResize.ts
@@ -0,0 +1,140 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+import { useCallback, useEffect, useRef, useState, type PointerEvent as ReactPointerEvent, type RefObject } from "react";
+
+/** Which edge a handle drags: the right edge grows rightward, the left leftward. */
+export type ResizeEdge = "left" | "right";
+
+export interface PointerResizeOptions {
+  /** The element whose width is previewed while dragging. */
+  frameRef: RefObject<HTMLElement | null>;
+  /** Smallest width a drag may produce (CSS px). Default 48. */
+  minWidth?: number;
+  /** Largest width — usually the container's; read at drag start. */
+  maxWidth?: () => number;
+  /**
+   * A centred element grows on both sides, so the pointer moves half as far as
+   * the width changes; pass `true` to double the pointer delta.
+   */
+  centered?: boolean;
+  /** Called once, on release, with the final width. Never during the drag. */
+  onCommit: (width: number) => void;
+  /** Optional: a live readout while dragging (e.g. a "480 px" badge). */
+  onPreview?: (width: number | null) => void;
+}
+
+/**
+ * Resize by dragging, done the robust way:
+ *
+ * - **Pointer Events + pointer capture**: mouse, touch and pen alike; the drag
+ *   keeps tracking when the pointer leaves the handle, the element or the
+ *   window, and a release anywhere ends it.
+ * - **No editor writes while dragging**: the preview mutates only the frame's
+ *   inline width (batched per animation frame). The document changes once, on
+ *   release — one history step, one collaboration update, one save.
+ * - **Every way a drag can end is handled**: release, `pointercancel`, lost
+ *   capture, window blur and Escape. Anything but a release restores the
+ *   original width and commits nothing.
+ */
+export function usePointerResize(options: PointerResizeOptions) {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const [resizing, setResizing] = useState(false);
+  const cleanupRef = useRef<(() => void) | null>(null);
+
+  // A drag in progress when the element unmounts must not leak listeners.
+  useEffect(() => () => cleanupRef.current?.(), []);
+
+  const onPointerDown = useCallback((edge: ResizeEdge) => (event: ReactPointerEvent<HTMLElement>) => {
+    const frame = optionsRef.current.frameRef.current;
+    if (!frame || event.button !== 0 || cleanupRef.current) return;
+    event.preventDefault();
+    event.stopPropagation();
+
+    const handle = event.currentTarget;
+    const pointerId = event.pointerId;
+    const startX = event.clientX;
+    const startWidth = frame.getBoundingClientRect().width;
+    const originalInline = frame.style.width;
+    const min = Math.max(1, optionsRef.current.minWidth ?? 48);
+    const max = Math.max(min, optionsRef.current.maxWidth?.() ?? Number.POSITIVE_INFINITY);
+    const factor = (optionsRef.current.centered ? 2 : 1) * (edge === "left" ? -1 : 1);
+    let width = startWidth;
+    let frameRequest: number | null = null;
+    let finished = false;
+
+    try {
+      handle.setPointerCapture(pointerId);
+    } catch {
+      // Synthetic events in tests have no live pointer to capture.
+    }
+    const previousUserSelect = document.body.style.userSelect;
+    document.body.style.userSelect = "none";
+    setResizing(true);
+
+    const paint = () => {
+      frameRequest = null;
+      frame.style.width = `${Math.round(width)}px`;
+      optionsRef.current.onPreview?.(Math.round(width));
+    };
+
+    const onMove = (move: PointerEvent) => {
+      if (move.pointerId !== pointerId) return;
+      width = Math.min(max, Math.max(min, startWidth + (move.clientX - startX) * factor));
+      if (frameRequest === null) frameRequest = requestAnimationFrame(paint);
+    };
+
+    const finish = (commit: boolean) => {
+      if (finished) return;
+      finished = true;
+      if (frameRequest !== null) cancelAnimationFrame(frameRequest);
+      handle.removeEventListener("pointermove", onMove);
+      handle.removeEventListener("pointerup", onUp);
+      handle.removeEventListener("pointercancel", onCancel);
+      handle.removeEventListener("lostpointercapture", onLost);
+      window.removeEventListener("blur", onCancel);
+      window.removeEventListener("keydown", onKey, true);
+      try {
+        if (handle.hasPointerCapture?.(pointerId)) handle.releasePointerCapture(pointerId);
+      } catch {
+        // Already released.
+      }
+      document.body.style.userSelect = previousUserSelect;
+      // Hand the width back to React: the committed value re-renders it, and an
+      // aborted drag must look exactly as it did before.
+      frame.style.width = originalInline;
+      cleanupRef.current = null;
+      setResizing(false);
+      optionsRef.current.onPreview?.(null);
+      const final = Math.round(width);
+      if (commit && Math.abs(final - Math.round(startWidth)) >= 1) optionsRef.current.onCommit(final);
+    };
+    const onUp = (up: PointerEvent) => {
+      if (up.pointerId === pointerId) finish(true);
+    };
+    const onCancel = () => finish(false);
+    const onLost = () => finish(true);
+    const onKey = (key: KeyboardEvent) => {
+      if (key.key === "Escape") {
+        key.preventDefault();
+        key.stopPropagation();
+        finish(false);
+      }
+    };
+
+    handle.addEventListener("pointermove", onMove);
+    handle.addEventListener("pointerup", onUp);
+    handle.addEventListener("pointercancel", onCancel);
+    handle.addEventListener("lostpointercapture", onLost);
+    window.addEventListener("blur", onCancel);
+    window.addEventListener("keydown", onKey, true);
+    cleanupRef.current = () => finish(false);
+  }, []);
+
+  return { onPointerDown, resizing };
+}
diff --git a/packages/luthor/src/core/extensions.test.tsx b/packages/luthor/src/core/extensions.test.tsx
new file mode 100644
index 00000000..88ec03f4
--- /dev/null
+++ b/packages/luthor/src/core/extensions.test.tsx
@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) Luthor Team and contributors.
+ * Open source under the MIT License (LICENSE).
+ * Fork it. Remix it. Ship it.
+ * Build freely. Credit kindly.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import {
+  createFloatingToolbarExtension,
+  getFloatingToolbarContextStore,
+  setFloatingToolbarContext,
+} from "./extensions";
+import type { CoreEditorCommands } from "./types";
+
+const commands = (name: string) => ({ name } as unknown as CoreEditorCommands);
+
+describe("floating toolbar context", () => {
+  it("each editor's toolbar has its own context — two editors never cross-wire", () => {
+    const a = createFloatingToolbarExtension();
+    const b = createFloatingToolbarExtension();
+    const storeA = getFloatingToolbarContextStore(a)!;
+    const storeB = getFloatingToolbarContextStore(b)!;
+    storeA.set({ commands: commands("a"), activeStates: { bold: true }, editorTheme: "light", isFeatureEnabled: () => true });
+    storeB.set({ commands: commands("b"), activeStates: {}, editorTheme: "dark", isFeatureEnabled: () => true });
+
+    const config = (ext: unknown) =>
+      (ext as { config: { getCommands: () => unknown; getActiveStates: () => unknown } }).config;
+    expect(config(a).getCommands()).toEqual({ name: "a" });
+    expect(config(b).getCommands()).toEqual({ name: "b" });
+    expect(config(a).getActiveStates()).toEqual({ bold: true });
+    expect(config(b).getActiveStates()).toEqual({});
+  });
+
+  it("notifies subscribers when its context changes (the bar re-renders at once)", () => {
+    const store = getFloatingToolbarContextStore(createFloatingToolbarExtension())!;
+    const listener = vi.fn();
+    const unsubscribe = store.subscribe(listener);
+    store.set({ commands: commands("x"), activeStates: {}, editorTheme: "light", isFeatureEnabled: () => true });
+    expect(listener).toHaveBeenCalledTimes(1);
+    unsubscribe();
+    store.set({ commands: commands("y"), activeStates: {}, editorTheme: "light", isFeatureEnabled: () => true });
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to the legacy global context until its own is set", () => {
+    const store = getFloatingToolbarContextStore(createFloatingToolbarExtension())!;
+    setFloatingToolbarContext(commands("global"), {}, "light");
+    expect(store.get().commands).toEqual({ name: "global" });
+    store.set({ commands: commands("own"), activeStates: {}, editorTheme: "light", isFeatureEnabled: () => true });
+    expect(store.get().commands).toEqual({ name: "own" });
+  });
+});
diff --git a/packages/luthor/src/core/extensions.tsx b/packages/luthor/src/core/extensions.tsx
index f760f822..ae3a79a6 100644
--- a/packages/luthor/src/core/extensions.tsx
+++ b/packages/luthor/src/core/extensions.tsx
@@ -5,7 +5,7 @@
  * Build freely. Credit kindly.
  */
 
-import { createElement, type ComponentType } from "react";
+import { createElement, useSyncExternalStore, type ComponentType } from "react";
 import { FloatingToolbarExtension } from "@lyfie/luthor-headless";
 import { FloatingToolbar } from "./floating-toolbar";
 import type { CoreEditorActiveStates, CoreEditorCommands, CoreTheme } from "./types";
@@ -17,39 +17,95 @@ type FloatingToolbarContext = {
   isFeatureEnabled: (feature: string) => boolean;
 };
 
-const floatingToolbarContext: FloatingToolbarContext = {
+/**
+ * What the floating toolbar renders from — one per editor, and reactive: a new
+ * value re-renders the bar immediately. (It used to be a single module-level
+ * object shared by every editor on the page, read when the toolbar happened to
+ * re-render — so the bar could show one editor's commands in another, or a
+ * previous selection's active states until the next selection event.)
+ */
+export interface FloatingToolbarContextStore {
+  get(): FloatingToolbarContext;
+  set(next: FloatingToolbarContext): void;
+  subscribe(listener: () => void): () => void;
+}
+
+function createStore(initial: FloatingToolbarContext | null, fallback?: FloatingToolbarContextStore): FloatingToolbarContextStore {
+  let value = initial;
+  const listeners = new Set<() => void>();
+  return {
+    get: () => value ?? fallback?.get() ?? DEFAULT_CONTEXT,
+    set: (next) => {
+      value = next;
+      listeners.forEach((listener) => listener());
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      const unsubscribeFallback = fallback?.subscribe(listener);
+      return () => {
+        listeners.delete(listener);
+        unsubscribeFallback?.();
+      };
+    },
+  };
+}
+
+const DEFAULT_CONTEXT: FloatingToolbarContext = {
   commands: {} as CoreEditorCommands,
   activeStates: {},
   editorTheme: "light",
   isFeatureEnabled: () => true,
 };
 
+// Kept for hosts that drive the toolbar through the legacy global setter.
+const globalStore = createStore(null);
+
+/**
+ * Legacy global context. Editors built by the presets now carry their own store
+ * (see {@link getFloatingToolbarContextStore}); this remains the fallback for a
+ * toolbar extension whose own store was never filled.
+ */
 export function setFloatingToolbarContext(
   commands: CoreEditorCommands,
   activeStates: CoreEditorActiveStates,
   editorTheme: CoreTheme,
   isFeatureEnabled: (feature: string) => boolean = () => true,
 ) {
-  floatingToolbarContext.commands = commands;
-  floatingToolbarContext.activeStates = activeStates;
-  floatingToolbarContext.editorTheme = editorTheme;
-  floatingToolbarContext.isFeatureEnabled = isFeatureEnabled;
+  globalStore.set({ commands, activeStates, editorTheme, isFeatureEnabled });
+}
+
+const STORE = Symbol.for("luthor.floatingToolbarContextStore");
+
+/** The context store of a toolbar extension made by {@link createFloatingToolbarExtension}. */
+export function getFloatingToolbarContextStore(extension: unknown): FloatingToolbarContextStore | null {
+  return (extension as { [STORE]?: FloatingToolbarContextStore } | null)?.[STORE] ?? null;
+}
+
+type ViewProps = { toolbarProps: Record<string, unknown>; store: FloatingToolbarContextStore };
+
+function FloatingToolbarContextView({ toolbarProps, store }: ViewProps) {
+  const context = useSyncExternalStore(store.subscribe, store.get, store.get);
+  const View = FloatingToolbar as unknown as ComponentType<Record<string, unknown>>;
+  return createElement(View, {
+    ...toolbarProps,
+    commands: context.commands,
+    activeStates: context.activeStates,
+    editorTheme: context.editorTheme,
+    isFeatureEnabled: context.isFeatureEnabled,
+  });
 }
 
+/** A floating-toolbar extension with its own reactive context store. */
 export function createFloatingToolbarExtension() {
-  const FloatingToolbarView = FloatingToolbar as unknown as ComponentType<Record<string, unknown>>;
+  const store = createStore(null, globalStore);
   const floatingToolbarExtension = new FloatingToolbarExtension();
   (floatingToolbarExtension as any).config = {
     ...(floatingToolbarExtension as any).config,
-    render: (props: unknown) => createElement(FloatingToolbarView, {
-      ...(props as Record<string, unknown>),
-      commands: floatingToolbarContext.commands,
-      activeStates: floatingToolbarContext.activeStates,
-      editorTheme: floatingToolbarContext.editorTheme,
-      isFeatureEnabled: floatingToolbarContext.isFeatureEnabled,
-    }),
-    getCommands: () => floatingToolbarContext.commands,
-    getActiveStates: () => floatingToolbarContext.activeStates,
+    render: (props: unknown) =>
+      createElement(FloatingToolbarContextView, { toolbarProps: props as Record<string, unknown>, store }),
+    getCommands: () => store.get().commands,
+    getActiveStates: () => store.get().activeStates,
   };
+  (floatingToolbarExtension as unknown as { [STORE]: FloatingToolbarContextStore })[STORE] = store;
   return floatingToolbarExtension;
 }
diff --git a/packages/luthor/src/core/floating-toolbar.test.tsx b/packages/luthor/src/core/floating-toolbar.test.tsx
index ce87574c..5ae41d05 100644
--- a/packages/luthor/src/core/floating-toolbar.test.tsx
+++ b/packages/luthor/src/core/floating-toolbar.test.tsx
@@ -244,4 +244,57 @@ describe("FloatingToolbar media editing", () => {
     expect(screen.queryByRole("button", { name: "Numbered List" })).not.toBeInTheDocument();
     expect(screen.queryByRole("button", { name: "Checklist" })).not.toBeInTheDocument();
   });
+
+  it("shows no formatting bar for a node selection it doesn't own (an attachment)", () => {
+    const { container } = render(
+      <FloatingToolbar
+        isVisible
+        selectionRect={DEFAULT_RECT}
+        commands={createCommands()}
+        activeStates={{} as CoreEditorActiveStates}
+        selection={null}
+      />,
+    );
+    expect(container.querySelector(".luthor-floating-toolbar")).toBeNull();
+  });
+
+  it("shows no bar over a YouTube or iframe embed whose feature is off", () => {
+    for (const state of [{ isYouTubeEmbedSelected: true }, { isIframeEmbedSelected: true }]) {
+      const { container, unmount } = render(
+        <FloatingToolbar
+          isVisible
+          selectionRect={DEFAULT_RECT}
+          commands={createCommands()}
+          activeStates={state as CoreEditorActiveStates}
+          isFeatureEnabled={(feature) => feature !== "youTubeEmbed" && feature !== "iframeEmbed"}
+        />,
+      );
+      expect(container.querySelector(".luthor-floating-toolbar")).toBeNull();
+      unmount();
+    }
+  });
+
+  it("a mousedown inside the editor never dismisses the bar; one outside does", () => {
+    const root = document.createElement("div");
+    const outside = document.createElement("div");
+    document.body.append(root, outside);
+    const editor = { getRootElement: () => root };
+    const hide = vi.fn();
+    render(
+      <FloatingToolbar
+        isVisible
+        selectionRect={DEFAULT_RECT}
+        commands={createCommands()}
+        activeStates={{ imageSelected: true } as CoreEditorActiveStates}
+        editor={editor}
+        hide={hide}
+      />,
+    );
+    fireEvent.mouseDown(root);
+    expect(hide).not.toHaveBeenCalled();
+    fireEvent.mouseDown(outside);
+    expect(hide).toHaveBeenCalledTimes(1);
+    root.remove();
+    outside.remove();
+  });
 });
diff --git a/packages/luthor/src/core/floating-toolbar.tsx b/packages/luthor/src/core/floating-toolbar.tsx
index 2f736054..6dad638a 100644
--- a/packages/luthor/src/core/floating-toolbar.tsx
+++ b/packages/luthor/src/core/floating-toolbar.tsx
@@ -5,7 +5,7 @@
  * Build freely. Credit kindly.
  */
 
-import { useEffect, useRef, useState, type CSSProperties } from "react";
+import { useEffect, useLayoutEffect, useRef, useState, type CSSProperties } from "react";
 import {
   AlignCenterIcon,
   AlignLeftIcon,
@@ -23,7 +23,7 @@ import {
   UnlinkIcon,
 } from "./icons";
 import { IconButton } from "./ui";
-import { getOverlayThemeStyleFromSelection } from "./overlay-theme";
+import { getOverlayThemeStyleFromElement } from "./overlay-theme";
 import type { CoreEditorActiveStates, CoreEditorCommands, CoreTheme } from "./types";
 
 type FloatingSelectionRect = {
@@ -40,6 +40,10 @@ export interface FloatingToolbarProps {
   editorTheme?: CoreTheme;
   hide?: () => void;
   isFeatureEnabled?: (feature: string) => boolean;
+  /** The editor the toolbar belongs to (clicks inside it never dismiss the bar). */
+  editor?: { getRootElement(): HTMLElement | null };
+  /** The text selection, when there is one; `null` for a node selection. */
+  selection?: object | null;
 }
 
 export function FloatingToolbar({
@@ -50,10 +54,16 @@ export function FloatingToolbar({
   editorTheme = "light",
   hide,
   isFeatureEnabled = () => true,
+  editor,
+  selection,
 }: FloatingToolbarProps) {
   const edgeInsetPx = 20;
 
   const toolbarRef = useRef<HTMLDivElement>(null);
+  // Horizontal correction measured from the rendered bar, so a wide bar near a
+  // viewport edge is pulled back in (no guessed widths).
+  const [shiftX, setShiftX] = useState(0);
+  const shiftRef = useRef(0);
   const [iframeUrlDraft, setIframeUrlDraft] = useState("");
   const [iframeCaptionDraft, setIframeCaptionDraft] = useState("");
   const [imageCaptionDraft, setImageCaptionDraft] = useState("");
@@ -79,6 +89,9 @@ export function FloatingToolbar({
       const target = event.target as Node | null;
       if (!target) return;
       if (toolbarRef.current?.contains(target)) return;
+      // Inside the editor, the selection it produces decides what shows —
+      // dismissing here and re-showing a moment later made the bar blink.
+      if (editor?.getRootElement()?.contains(target)) return;
       hide?.();
     };
 
@@ -89,7 +102,7 @@ export function FloatingToolbar({
       document.removeEventListener("mousedown", handlePointerDown, true);
       document.removeEventListener("touchstart", handlePointerDown, true);
     };
-  }, [isVisible, hide]);
+  }, [isVisible, hide, editor]);
 
   useEffect(() => {
     if (!isVisible || !iframeEmbedSelected) {
@@ -184,20 +197,48 @@ export function FloatingToolbar({
     };
   }, [activeStates.isLink, commands, isVisible]);
 
+  useLayoutEffect(() => {
+    const element = toolbarRef.current;
+    if (!element || typeof window === "undefined") return;
+    // Measure where the bar sits without our own correction applied, so the
+    // correction can never feed back into itself.
+    const applied = element.style.transform;
+    element.style.transform = "";
+    const rect = element.getBoundingClientRect();
+    element.style.transform = applied;
+    const naturalLeft = rect.left;
+    const naturalRight = rect.right;
+    const margin = 12;
+    let next = 0;
+    if (naturalRight > window.innerWidth - margin) next = window.innerWidth - margin - naturalRight;
+    if (naturalLeft + next < margin) next = margin - naturalLeft;
+    if (Math.abs(next - shiftRef.current) >= 1) {
+      shiftRef.current = next;
+      setShiftX(next);
+    }
+  }, [isVisible, selectionRect, activeStates]);
+
   if (!isVisible || !selectionRect) return null;
 
   const style: CSSProperties = {
-    ...getOverlayThemeStyleFromSelection(),
+    // Theme from the editor itself, not from wherever the DOM selection is
+    // (a node selection has none, which used to restyle the bar mid-use).
+    ...getOverlayThemeStyleFromElement(editor?.getRootElement() ?? null),
     position: "absolute",
     top: selectionRect.y,
     left: selectionRect.positionFromRight ? "auto" : selectionRect.x,
     right: selectionRect.positionFromRight ? edgeInsetPx : "auto",
+    transform: shiftX ? `translateX(${shiftX}px)` : undefined,
     maxWidth: `calc(100% - ${edgeInsetPx * 2}px)`,
     boxSizing: "border-box",
     zIndex: "var(--luthor-z-menu, 460)",
     pointerEvents: "auto",
   };
 
+  if ((iframeEmbedSelected && !iframeEmbedEnabled) || (youTubeEmbedSelected && !youTubeEmbedEnabled)) {
+    return null;
+  }
+
   if (embedSelected) {
     const setAlignment = (alignment: "left" | "center" | "right") => {
       if (iframeEmbedSelected) {
@@ -409,6 +450,12 @@ export function FloatingToolbar({
     );
   }
 
+  // The formatting bar is for text. A selected node that none of the branches
+  // above owns (an attachment, a card) keeps its own controls.
+  if (selection === null) {
+    return null;
+  }
+
   const canShowBold = isFeatureEnabled("bold");
   const canShowItalic = isFeatureEnabled("italic");
   const canShowUnderline = isFeatureEnabled("underline");
diff --git a/packages/luthor/src/core/styles.css b/packages/luthor/src/core/styles.css
index bb7d9043..7dab37a3 100644
--- a/packages/luthor/src/core/styles.css
+++ b/packages/luthor/src/core/styles.css
@@ -2905,6 +2905,236 @@
 	border-color: var(--luthor-border-hover);
 }
 
+/* Interactive media: select, resize, toolbar. */
+.luthor-media.is-interactive .luthor-media__frame {
+	cursor: default;
+}
+
+.luthor-media.is-selected .luthor-media__frame,
+.luthor-media--inline.is-selected {
+	outline: 2px solid var(--luthor-accent);
+	outline-offset: 2px;
+	border-radius: 10px;
+}
+
+.luthor-media__handle {
+	position: absolute;
+	top: 50%;
+	width: 8px;
+	height: 44px;
+	max-height: 60%;
+	transform: translateY(-50%);
+	border: 1px solid var(--luthor-bg);
+	border-radius: 999px;
+	background: var(--luthor-accent);
+	box-shadow: 0 1px 3px var(--luthor-shadow);
+	cursor: ew-resize;
+	touch-action: none;
+	z-index: 2;
+}
+
+/* A generous invisible hit area around the thin visible pill. */
+.luthor-media__handle::before {
+	content: "";
+	position: absolute;
+	inset: -10px -12px;
+}
+
+.luthor-media__handle--left {
+	left: -4px;
+}
+
+.luthor-media__handle--right {
+	right: -4px;
+}
+
+.luthor-media__size-badge {
+	position: absolute;
+	right: 8px;
+	bottom: 8px;
+	padding: 2px 6px;
+	border-radius: 6px;
+	background: color-mix(in srgb, var(--luthor-fg) 78%, transparent);
+	color: var(--luthor-bg);
+	font: 500 11px/1.4 ui-monospace, SFMono-Regular, monospace;
+	pointer-events: none;
+	z-index: 3;
+}
+
+.luthor-media__size-badge:empty {
+	display: none;
+}
+
+.luthor-media.is-resizing .luthor-media__element {
+	pointer-events: none;
+}
+
+.luthor-media__toolbar {
+	position: absolute;
+	top: 8px;
+	left: 50%;
+	transform: translateX(-50%);
+	display: inline-flex;
+	align-items: center;
+	gap: 2px;
+	padding: 3px;
+	max-width: calc(100% - 16px);
+	overflow-x: auto;
+	scrollbar-width: none;
+	border: 1px solid var(--luthor-border);
+	border-radius: 9px;
+	background: var(--luthor-bg);
+	box-shadow: 0 4px 16px var(--luthor-shadow);
+	z-index: 4;
+	white-space: nowrap;
+}
+
+/* On a small picture the bar sits under it instead of covering it. */
+.luthor-media__toolbar.is-compact {
+	top: calc(100% + 8px);
+	max-width: none;
+}
+
+.luthor-media__tool {
+	display: inline-grid;
+	place-items: center;
+	min-width: 28px;
+	height: 28px;
+	padding: 0 6px;
+	border: 1px solid transparent;
+	border-radius: 6px;
+	background: transparent;
+	color: var(--luthor-fg);
+	font: inherit;
+	font-size: 12px;
+	cursor: pointer;
+}
+
+.luthor-media__tool:hover {
+	background: var(--luthor-muted);
+}
+
+.luthor-media__tool.is-active {
+	border-color: var(--luthor-accent);
+	color: var(--luthor-accent);
+}
+
+.luthor-media__tool:focus-visible {
+	outline: 2px solid var(--luthor-accent);
+	outline-offset: 1px;
+}
+
+.luthor-media__tool:disabled {
+	opacity: 0.45;
+	cursor: default;
+}
+
+/* Upload in progress (UploadPlaceholderNode). */
+.luthor-upload {
+	display: flex;
+	align-items: center;
+	gap: 0.75rem;
+	margin: 0.75rem 0;
+	padding: 0.6rem 0.75rem;
+	border: 1px dashed var(--luthor-border-hover);
+	border-radius: 10px;
+	background: var(--luthor-muted);
+	color: var(--luthor-fg);
+	user-select: none;
+}
+
+.luthor-upload.is-error {
+	border-style: solid;
+	border-color: var(--luthor-border-active);
+}
+
+.luthor-upload__preview {
+	flex: none;
+	width: 3rem;
+	height: 3rem;
+	object-fit: cover;
+	border-radius: 6px;
+	opacity: 0.7;
+}
+
+.luthor-upload__body {
+	display: flex;
+	flex-direction: column;
+	gap: 0.25rem;
+	min-width: 0;
+	flex: 1;
+}
+
+.luthor-upload__name {
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.luthor-upload__detail {
+	font-size: 0.85em;
+	color: var(--luthor-muted-fg);
+}
+
+.luthor-upload__bar {
+	position: relative;
+	height: 4px;
+	border-radius: 999px;
+	background: var(--luthor-border);
+	overflow: hidden;
+}
+
+.luthor-upload__bar > span {
+	position: absolute;
+	inset: 0 auto 0 0;
+	background: var(--luthor-accent);
+	border-radius: inherit;
+	transition: width 0.2s ease;
+}
+
+.luthor-upload__bar.is-indeterminate > span {
+	width: 30%;
+	animation: luthor-upload-indeterminate 1.1s ease-in-out infinite;
+}
+
+@keyframes luthor-upload-indeterminate {
+	from {
+		left: -30%;
+	}
+	to {
+		left: 100%;
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.luthor-upload__bar.is-indeterminate > span {
+		animation: none;
+		width: 100%;
+		opacity: 0.4;
+	}
+}
+
+.luthor-upload__actions {
+	display: inline-flex;
+	gap: 0.4rem;
+	flex: none;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+	.luthor-media__toolbar {
+		animation: luthor-media-toolbar-in 0.12s ease-out;
+	}
+}
+
+@keyframes luthor-media-toolbar-in {
+	from {
+		opacity: 0;
+	}
+	to {
+		opacity: 1;
+	}
+}
+
 .luthor-media-embed-shell:hover {
 	border-color: var(--luthor-border-active);
 }
diff --git a/packages/luthor/src/core/types.ts b/packages/luthor/src/core/types.ts
index 2442ef93..bace219c 100644
--- a/packages/luthor/src/core/types.ts
+++ b/packages/luthor/src/core/types.ts
@@ -49,6 +49,8 @@ export interface InputField {
   type?: "text" | "url";
   /** Required fields must be filled before the dialog submits. */
   required?: boolean;
+  /** Starting value (editing an existing caption, alt text, …). */
+  value?: string;
 }
 
 /** Values a command asks the person for, in the editor's themed dialog. */
diff --git a/packages/luthor/src/core/ui.tsx b/packages/luthor/src/core/ui.tsx
index 9ca00a7f..66434865 100644
--- a/packages/luthor/src/core/ui.tsx
+++ b/packages/luthor/src/core/ui.tsx
@@ -490,9 +490,11 @@ export function InputDialog({
   onSubmit: (values: Record<string, string>) => void;
   onCancel: () => void;
 }) {
-  const [values, setValues] = useState<Record<string, string>>({});
-  // A new request starts empty.
-  useEffect(() => setValues({}), [request]);
+  const initial = (next: InputRequest | null) =>
+    Object.fromEntries((next?.fields ?? []).filter((f) => f.value !== undefined).map((f) => [f.name, f.value ?? ""]));
+  const [values, setValues] = useState<Record<string, string>>(() => initial(request));
+  // A new request starts from its own starting values (empty unless given).
+  useEffect(() => setValues(initial(request)), [request]);
   const idPrefix = useId();
 
   const trimmed = (name: string) => (values[name] ?? "").trim();
diff --git a/packages/luthor/src/presets/extensive/ExtensiveEditor.test.tsx b/packages/luthor/src/presets/extensive/ExtensiveEditor.test.tsx
index 8ede32c6..55f0ec11 100644
--- a/packages/luthor/src/presets/extensive/ExtensiveEditor.test.tsx
+++ b/packages/luthor/src/presets/extensive/ExtensiveEditor.test.tsx
@@ -256,6 +256,7 @@ const mockEditorApi = {
 
 vi.mock("@lyfie/luthor-headless", () => ({
   COLLABORATION_UPDATE_TAG: "collaboration",
+  EditorPromptProvider: ({ children }: { children: ReactNode }) => <>{children}</>,
   createEditorSystem: () => ({
     Provider: ({ children, config }: { children: ReactNode; config?: unknown }) => {
       providerMock(config as Record<string, unknown>);
diff --git a/packages/luthor/src/presets/extensive/ExtensiveEditor.tsx b/packages/luthor/src/presets/extensive/ExtensiveEditor.tsx
index cd7c96ac..8749afa7 100644
--- a/packages/luthor/src/presets/extensive/ExtensiveEditor.tsx
+++ b/packages/luthor/src/presets/extensive/ExtensiveEditor.tsx
@@ -27,7 +27,9 @@ import {
   type AnyExtension,
   type LuthorTheme,
   type SourceMetadataMode,
+  EditorPromptProvider,
 } from "@lyfie/luthor-headless";
+import { getFloatingToolbarContextStore } from "../../core/extensions";
 import {
   createExtensiveExtensions,
   extensiveExtensions,
@@ -1384,14 +1386,25 @@ function ExtensiveEditorContent({
 
   useEffect(() => cancelPendingChange, [cancelPendingChange]);
 
+  // This editor's own floating-toolbar context (never another editor's). A
+  // host without the per-editor store still gets the legacy global one.
+  const floatingToolbarStore = useMemo(
+    () => (extensions as readonly unknown[]).map(getFloatingToolbarContextStore).find(Boolean) ?? null,
+    [extensions],
+  );
   useEffect(() => {
-    setFloatingToolbarContext(
-      safeCommands,
+    const next = {
+      commands: safeCommands,
       activeStates,
-      isDark ? "dark" : "light",
-      isMenuFeatureEnabled,
-    );
-  }, [safeCommands, activeStates, isDark, isMenuFeatureEnabled]);
+      editorTheme: (isDark ? "dark" : "light") as "dark" | "light",
+      isFeatureEnabled: isMenuFeatureEnabled,
+    };
+    if (floatingToolbarStore) {
+      floatingToolbarStore.set(next);
+    } else {
+      setFloatingToolbarContext(next.commands, next.activeStates, next.editorTheme, next.isFeatureEnabled);
+    }
+  }, [safeCommands, activeStates, isDark, isMenuFeatureEnabled, floatingToolbarStore]);
 
   const methods = useMemo<ExtensiveEditorRef>(
     () => {
@@ -1564,8 +1577,16 @@ function ExtensiveEditorContent({
     // Host-contributed slash commands, bound to a minimal insert API. Mapped
     // once so the same item objects flow into both the palette and the slash
     // menu, and back out on cleanup.
+    const slashCommandMap = commandApi as unknown as Record<string, unknown>;
     const slashCommandContext: ExtensiveSlashCommandContext = {
       insertText: (text) => commandApi.insertText?.(text),
+      hasCommand: (name) => typeof slashCommandMap[name] === "function",
+      runCommand: (name, ...args) => {
+        const command = slashCommandMap[name];
+        return typeof command === "function"
+          ? (command as (...commandArgs: unknown[]) => unknown)(...args)
+          : undefined;
+      },
     };
     const extraSlashItems = (extraSlashCommands ?? []).map((command) => ({
       id: command.id,
@@ -2365,7 +2386,9 @@ function ExtensiveEditorContent({
   const shouldHideDraggableAffordances = !isDraggableBoxEnabled || !isVisualEditorMode(mode);
 
   return (
-    <>
+    // Decorators (a media frame's caption and alt-text buttons) ask for values
+    // through this same themed dialog rather than window.prompt.
+    <EditorPromptProvider requestPrompt={requestInput}>
       <div
         className={`luthor-editor${shouldHideDraggableAffordances ? " luthor-editor--draggable-disabled" : ""}`}
         data-mode={mode}
@@ -2531,7 +2554,7 @@ function ExtensiveEditorContent({
           }}
         />
       )}
-    </>
+    </EditorPromptProvider>
   );
 }
 
@@ -2548,6 +2571,14 @@ export interface ExtensiveSlashCommandContext {
    * so the text lands exactly where the user typed the slash.
    */
   insertText: (text: string) => void;
+  /** Whether a registered extension provides the command `name`. */
+  hasCommand?: (name: string) => boolean;
+  /**
+   * Run the extension command `name` with `args` (e.g. `uploadAndEmbedFile`),
+   * returning its result — `undefined` when no extension provides it. Lets a
+   * command insert a real node rather than markdown text.
+   */
+  runCommand?: (name: string, ...args: unknown[]) => unknown;
 }
 
 /**
diff --git a/packages/luthor/src/presets/extensive/extensions.tsx b/packages/luthor/src/presets/extensive/extensions.tsx
index af6a0202..f63ec6eb 100644
--- a/packages/luthor/src/presets/extensive/extensions.tsx
+++ b/packages/luthor/src/presets/extensive/extensions.tsx
@@ -654,8 +654,6 @@ const youTubeEmbedExt = new YouTubeEmbedExtension();
   rel: 1,
 };
 
-const floatingToolbarExt = createFloatingToolbarExtension();
-
 const contextMenuExt = new ContextMenuExtension();
 (contextMenuExt as any).config = {
   ...(contextMenuExt as any).config,
@@ -801,7 +799,8 @@ function buildExtensiveExtensions({
   if (enabled("enterKeyBehavior")) extensions.push(enterKeyBehaviorExtension);
   if (enabled("iframeEmbed")) extensions.push(iframeEmbedExt);
   if (enabled("youTubeEmbed")) extensions.push(youTubeEmbedExt);
-  if (enabled("floatingToolbar")) extensions.push(floatingToolbarExt);
+  // One per editor: each carries its own context (commands, active states).
+  if (enabled("floatingToolbar")) extensions.push(createFloatingToolbarExtension());
   if (enabled("contextMenu")) extensions.push(contextMenuExt);
   if (enabled("commandPalette")) extensions.push(commandPaletteExt);
   if (enabled("slashCommand")) extensions.push(slashCommandExt);
diff --git a/packages/luthor/src/presets/papyra-collab/papyraCollab.test.ts b/packages/luthor/src/presets/papyra-collab/papyraCollab.test.ts
index b886f0f1..82205235 100644
--- a/packages/luthor/src/presets/papyra-collab/papyraCollab.test.ts
+++ b/packages/luthor/src/presets/papyra-collab/papyraCollab.test.ts
@@ -21,6 +21,7 @@ import {
   papyraMarkdownToJSON,
   type PapyraHeadlessCollab,
 } from "./index";
+import { UploadPlaceholderNode } from "@lyfie/luthor-headless";
 
 const FIXTURES = [
   "Plain paragraph.",
@@ -130,6 +131,34 @@ describe("papyra headless collaboration", () => {
     expect(bob.getMarkdown()).toBe(expected);
   });
 
+  it("an upload in progress reaches peers as a placeholder but never the saved markdown", () => {
+    const server = replica();
+    server.setMarkdown("Intro\n\nOutro");
+    const alice = replica(server.doc);
+    const bob = replica(server.doc);
+
+    alice.editor.update(
+      () => {
+        const first = $getRoot().getFirstChild()!;
+        first.insertAfter(
+          new UploadPlaceholderNode({ uploadId: "up-x", name: "beach.png", size: 10, kind: "image", startedAt: 1 }),
+        );
+      },
+      { discrete: true },
+    );
+    connect(alice.doc, server.doc);
+    connect(server.doc, bob.doc);
+
+    expect(bob.editor.getEditorState().read(() => $getRoot().getChildren().map((n) => n.getType()))).toContain(
+      "uploadPlaceholder",
+    );
+    expect(JSON.stringify(bob.editor.getEditorState().toJSON())).not.toContain("blob:");
+    // The server persists markdown: nothing for the in-flight upload.
+    expect(server.getMarkdown()).not.toContain("beach.png");
+    expect(server.getMarkdown()).toContain("Intro");
+    expect(server.getMarkdown()).toContain("Outro");
+  });
+
   it("reloads a persisted room state without changing the body", () => {
     const server = replica();
     server.setMarkdown(FIXTURES[1]!);
diff --git a/packages/luthor/src/presets/papyra/PapyraEditor.tsx b/packages/luthor/src/presets/papyra/PapyraEditor.tsx
index 02e04fea..108d0dfa 100644
--- a/packages/luthor/src/presets/papyra/PapyraEditor.tsx
+++ b/packages/luthor/src/presets/papyra/PapyraEditor.tsx
@@ -616,10 +616,14 @@ export const PapyraEditor = forwardRef<PapyraEditorRef, PapyraEditorProps>(
     // auto-stamping anchor extension.
     const autoStampBlockAnchors = blockAnchors === "auto" && !isCollaborative;
     const collaborationExtension = collaboration;
+    // Uploads read the adapter live (see buildPapyraEmbedExtensions).
+    const adapterRef = useRef(adapter);
+    adapterRef.current = adapter;
     const embedExtensions = useMemo(() => {
       const extensions = buildPapyraEmbedExtensions(adapter, {
         autoStampBlockAnchors,
         typeahead,
+        liveAdapter: () => adapterRef.current,
       });
       return collaborationExtension
         ? [...extensions, collaborationExtension]
diff --git a/packages/luthor/src/presets/papyra/adapter.ts b/packages/luthor/src/presets/papyra/adapter.ts
index 67f20c99..06112745 100644
--- a/packages/luthor/src/presets/papyra/adapter.ts
+++ b/packages/luthor/src/presets/papyra/adapter.ts
@@ -28,7 +28,10 @@ import { createContext, useContext, type ReactNode } from "react";
 import type {
   FileExpansionContext,
   MediaMeta,
+  MediaToolbarContext,
+  MediaToolbarItem,
   MediaUrlOptions,
+  UploadFileOptions,
 } from "@lyfie/luthor-headless";
 
 /** A reference to a note, by human title and/or stable id. */
@@ -119,7 +122,19 @@ export interface PapyraEditorAdapter {
    * editor should reference as `![[filename]]`. The host owns the upload endpoint
    * and its authorization.
    */
-  uploadMedia(file: File): Promise<{ filename: string }>;
+  uploadMedia(file: File, options?: UploadFileOptions): Promise<{ filename: string }>;
+  /**
+   * Refuse a file before it is uploaded (too large, a kind the host won't
+   * take): return the message to show, or `null` to accept. Optional.
+   */
+  validateMedia?(file: File): string | null;
+  /** Report a failed or refused upload (a toast). Called once per failure. Optional. */
+  onUploadError?(error: unknown, file: File): void;
+  /**
+   * The host's own buttons on a selected attachment (replace, download, …),
+   * shown after the built-in ones. Optional.
+   */
+  mediaToolbarItems?(context: MediaToolbarContext): MediaToolbarItem[];
   /**
    * Navigate to a note. Invoked when the reader activates a `[[Note]]` wikilink.
    * The host owns routing; the editor only reports the intent.
diff --git a/packages/luthor/src/presets/papyra/commands.ts b/packages/luthor/src/presets/papyra/commands.ts
index 1514d1cb..35e1e571 100644
--- a/packages/luthor/src/presets/papyra/commands.ts
+++ b/packages/luthor/src/presets/papyra/commands.ts
@@ -170,11 +170,23 @@ export function createPapyraSlashCommands(
       description: "Upload and embed an image, audio, or video file",
       category: "Insert",
       keywords: ["embed", "media", "image", "audio", "video", "upload", "attach"],
-      action: async ({ insertText }) => {
+      action: async ({ insertText, hasCommand, runCommand }) => {
         const file = await pickMediaFile(PAPYRA_MEDIA_PICKER_ACCEPT);
         if (!file) {
           return;
         }
+        // The upload pipeline: a placeholder with progress at the caret, then
+        // a real embed node. (Typing the `![[name]]` text instead left it as
+        // literal text until the note was reopened.)
+        if (runCommand && hasCommand?.("uploadAndEmbedFile")) {
+          try {
+            await runCommand("uploadAndEmbedFile", file);
+          } catch {
+            // Reported through the adapter's onUploadError; the placeholder
+            // offers Retry/Remove.
+          }
+          return;
+        }
         const { filename } = await adapter.uploadMedia(file);
         insertText(`![[${filename}]]`);
       },
diff --git a/packages/luthor/src/presets/papyra/embeds.ts b/packages/luthor/src/presets/papyra/embeds.ts
index 524d18eb..c42fab9a 100644
--- a/packages/luthor/src/presets/papyra/embeds.ts
+++ b/packages/luthor/src/presets/papyra/embeds.ts
@@ -46,6 +46,8 @@ import {
   IFRAME_EMBED_MARKDOWN_TRANSFORMER,
   SAVED_CARD_MARKDOWN_TRANSFORMER,
   TRANSCLUSION_MARKDOWN_TRANSFORMER,
+  UPLOAD_PLACEHOLDER_MARKDOWN_TRANSFORMER,
+  UploadPlaceholderNode,
   WIKILINK_MARKDOWN_TRANSFORMER,
   YOUTUBE_EMBED_MARKDOWN_TRANSFORMER,
   FileDropUploadExtension,
@@ -96,6 +98,12 @@ export interface PapyraEmbedExtensionOptions {
    * registered at all. See {@link PapyraTypeaheadConfig}.
    */
   typeahead?: PapyraTypeaheadConfig;
+  /**
+   * The adapter to use *at the moment of an upload*. The editor builds its
+   * extensions once; reading the adapter through this getter keeps uploads on
+   * the host's current adapter rather than the one the editor mounted with.
+   */
+  liveAdapter?: () => PapyraEditorAdapter | undefined;
 }
 
 /** Element type of the extensive editor's `extraExtensions` array. */
@@ -166,7 +174,10 @@ export function buildPapyraEmbedExtensions(
 
   extensions.push(
     new FileDropUploadExtension({
-      uploadFile: (file) => adapter.uploadMedia(file),
+      uploadFile: (file, uploadOptions) =>
+        (options?.liveAdapter?.() ?? adapter).uploadMedia(file, uploadOptions),
+      validateFile: (file) => (options?.liveAdapter?.() ?? adapter).validateMedia?.(file) ?? null,
+      onUploadError: (error, file) => (options?.liveAdapter?.() ?? adapter).onUploadError?.(error, file),
     }),
   );
 
@@ -188,6 +199,7 @@ export const PAPYRA_EMBED_NODES: NonNullable<
   ExtensiveEditorProps["markdownExtraNodes"]
 > = [
   FileEmbedNode,
+  UploadPlaceholderNode,
   SavedCardNode,
   CalloutNode,
   IframeEmbedNode,
@@ -229,6 +241,7 @@ export const PAPYRA_EMBED_TRANSFORMERS: NonNullable<
   CALLOUT_MARKDOWN_TRANSFORMER,
   TRANSCLUSION_MARKDOWN_TRANSFORMER,
   FILE_EMBED_MARKDOWN_TRANSFORMER,
+  UPLOAD_PLACEHOLDER_MARKDOWN_TRANSFORMER,
   BLOCK_ANCHOR_MARKDOWN_TRANSFORMER,
   FILE_EMBED_INLINE_MARKDOWN_TRANSFORMER,
   WIKILINK_MARKDOWN_TRANSFORMER,
@@ -252,6 +265,9 @@ export function createPapyraEmbedResolvers(
     renderFileExpansion: adapter.renderFileExpansion
       ? (context) => adapter.renderFileExpansion!(context)
       : undefined,
+    mediaToolbar: adapter.mediaToolbarItems
+      ? { items: (context) => adapter.mediaToolbarItems!(context) }
+      : undefined,
     openLink: (target) => adapter.openNote({ title: target }),
     resolveBlock: adapter.resolveBlock
       ? (note, blockId) => adapter.resolveBlock!({ note, blockId })