From 6ca2dbe8030f87f16efa4e814163d31d6ee90b49 Mon Sep 17 00:00:00 2001
From: Maggie Appleton <5599295+MaggieAppleton@users.noreply.github.com>
Date: Sun, 11 Oct 2026 08:21:42 +0100
Subject: [PATCH 01/10] Open documents for reading on phones, with an edit
 toggle

Phones now open a document in a local reading mode: the editor is not
editable, so tapping prose places no caret and raises no keyboard, links
follow on tap, and editing-only chrome (Show source, code language menus,
image editing, tab add/remove, table rails, slash menu) stays hidden.
Selection and commenting keep working, because reading is separate from the
permission-based readOnly lock, which still wins.

A pencil in the phone tab bar switches to editing inside the tap, placing the
caret where the reader last tapped or at the first block in view. While the
keyboard is up, a docked formatting toolbar (bold, italic, heading, list,
link, insert, hide keyboard) replaces the tabs and the selection bubble.
Empty and newly created documents open ready to write, and a new document's
title hands focus to the body as its rename starts, so keys typed meanwhile
are kept. The mode lasts across tab changes and reconnects and resets per
document. Desktop and viewers are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/web/src/keyboard-open.ts                 |  19 ++
 apps/web/src/phone-header.tsx                 |   8 +-
 apps/web/src/phone-workspace.css              |  62 +++++-
 apps/web/src/phone-workspace.tsx              |  11 +-
 apps/web/src/room-workspace.tsx               |  59 ++++-
 apps/web/src/workspace.tsx                    |   4 +
 e2e/phone-read-mode.e2e.ts                    | 206 ++++++++++++++++++
 e2e/responsive-workspace.e2e.ts               |   6 +-
 e2e/room.ts                                   |  16 +-
 e2e/sidecar.e2e.ts                            |   7 +-
 e2e/tab-authoring.e2e.ts                      |   3 +-
 e2e/table.e2e.ts                              |   3 +-
 e2e/toolbar.e2e.ts                            |  18 +-
 packages/editor/src/edit-mode.test.ts         |  46 ++++
 packages/editor/src/edit-mode.ts              |  42 ++++
 packages/editor/src/index.ts                  |   2 +
 packages/editor/src/plan-editor.tsx           | 141 +++++++++++-
 packages/editor/src/styles.css                |  47 ++++
 packages/editor/src/toolbar/bubble.tsx        |  97 +++++----
 packages/editor/src/toolbar/dock.tsx          | 150 +++++++++++++
 packages/editor/src/toolbar/index.tsx         |  30 ++-
 packages/editor/src/toolbar/link.tsx          |  13 +-
 packages/editor/src/toolbar/slash.tsx         |  30 ++-
 packages/editor/src/widget-options.ts         |   7 +
 packages/editor/src/widgets/render-blocks.tsx |  11 +-
 25 files changed, 968 insertions(+), 70 deletions(-)
 create mode 100644 apps/web/src/keyboard-open.ts
 create mode 100644 e2e/phone-read-mode.e2e.ts
 create mode 100644 packages/editor/src/edit-mode.test.ts
 create mode 100644 packages/editor/src/edit-mode.ts
 create mode 100644 packages/editor/src/toolbar/dock.tsx

diff --git a/apps/web/src/keyboard-open.ts b/apps/web/src/keyboard-open.ts
new file mode 100644
index 000000000..1d6d4b1d7
--- /dev/null
+++ b/apps/web/src/keyboard-open.ts
@@ -0,0 +1,19 @@
+import { useSyncExternalStore } from "react";
+
+/** Follows `:root[data-keyboard-open]`, which the visual-viewport adapter keeps current. */
+export function useKeyboardOpen(): boolean {
+	return useSyncExternalStore(subscribe, current, () => false);
+}
+
+function subscribe(notify: () => void): () => void {
+	let observer = new MutationObserver(notify);
+	observer.observe(document.documentElement, {
+		attributes: true,
+		attributeFilter: ["data-keyboard-open"],
+	});
+	return () => observer.disconnect();
+}
+
+function current(): boolean {
+	return document.documentElement.hasAttribute("data-keyboard-open");
+}
diff --git a/apps/web/src/phone-header.tsx b/apps/web/src/phone-header.tsx
index b0fd3baa3..b887c16ce 100644
--- a/apps/web/src/phone-header.tsx
+++ b/apps/web/src/phone-header.tsx
@@ -56,13 +56,18 @@ export function PhoneHeader(
 		return () => cancel(handle);
 	}, [hostsTrigger]);
 
-	let finishEdit = () => {
+	// Also runs as a save starts, not after it: keys typed while the rename travels would
+	// otherwise land in a field that is about to close.
+	let handOff = () => {
 		// Naming a new document leads into writing it, unless the user already tapped elsewhere.
 		if (editing === "new" && header.current?.contains(document.activeElement)) {
 			header.current.closest(".workspace-root")
 				?.querySelector<HTMLElement>(".plan-content[contenteditable='true']")
 				?.focus();
 		}
+	};
+	let finishEdit = () => {
+		handOff();
 		onEditingChange();
 	};
 
@@ -90,6 +95,7 @@ export function PhoneHeader(
 							channel={{ id: room, title: label }}
 							inline
 							onCancel={finishEdit}
+							onSavingChange={saving => saving && handOff()}
 							replay={editing === "new"}
 							onRenamed={detail => {
 								onRenamed(detail.channel);
diff --git a/apps/web/src/phone-workspace.css b/apps/web/src/phone-workspace.css
index a12520b94..dfb73031c 100644
--- a/apps/web/src/phone-workspace.css
+++ b/apps/web/src/phone-workspace.css
@@ -227,6 +227,7 @@
 }
 
 .phone-tab-bar,
+.phone-tab-toolbar,
 .phone-tab-action {
 	background: var(--color-glass);
 	-webkit-backdrop-filter: var(--glass-filter);
@@ -246,6 +247,32 @@
 	border-radius: var(--radius-full);
 }
 
+.phone-tab-bar[hidden] {
+	display: none;
+}
+
+/* Editing on a phone: formatting takes the tabs' place and rides above the keyboard. */
+:root[data-keyboard-open] .phone-tab-row[data-phone-tab-toolbar] {
+	visibility: visible;
+	transform: none;
+}
+
+.phone-tab-toolbar {
+	flex: 1;
+	min-width: 0;
+	height: var(--phone-tab-bar-height);
+	border-radius: var(--radius-full);
+	overflow: hidden;
+	animation: phone-tab-toolbar-in var(--tab-slide-dur) var(--tab-slide-ease);
+}
+
+@keyframes phone-tab-toolbar-in {
+	from {
+		opacity: 0;
+		transform: translateY(calc(var(--spacing) * 3)) scale(0.98);
+	}
+}
+
 .phone-tab-indicator {
 	position: absolute;
 	inset-block: var(--spacing);
@@ -297,7 +324,8 @@
 	}
 }
 
-.phone-tab [data-nucleo-icon] {
+.phone-tab [data-nucleo-icon],
+.phone-tab-action [data-nucleo-icon] {
 	color: inherit;
 }
 
@@ -386,6 +414,31 @@
 	}
 }
 
+/* The edit toggle turns into a filled Done button while editing. */
+.phone-tab-action[data-editing] {
+	background: var(--color-brand);
+	color: var(--color-page);
+	outline-color: var(--color-brand);
+}
+
+.phone-tab-action > svg {
+	grid-area: 1 / 1;
+	transition:
+		opacity var(--duration-fast) var(--ease-out),
+		transform var(--tab-slide-dur) var(--tab-slide-ease);
+}
+
+.phone-tab-action > [data-edit-icon="done"],
+.phone-tab-action[data-editing] > [data-edit-icon="edit"] {
+	opacity: 0;
+	transform: scale(0.4) rotate(45deg);
+}
+
+.phone-tab-action[data-editing] > [data-edit-icon="done"] {
+	opacity: 1;
+	transform: none;
+}
+
 /* Destinations ---------------------------------------------------------- */
 
 /* Sibling tabs glide in from the side their tab lies on and push the old one out. */
@@ -431,7 +484,12 @@
 	.workspace-root[data-workspace-phone] > .phone-top-bar,
 	.workspace-root[data-workspace-phone] .workspace-stack-bar,
 	.phone-tab-indicator,
-	.phone-tab-row {
+	.phone-tab-row,
+	.phone-tab-action > svg {
 		transition: none;
 	}
+
+	.phone-tab-toolbar {
+		animation: none;
+	}
 }
diff --git a/apps/web/src/phone-workspace.tsx b/apps/web/src/phone-workspace.tsx
index 187e7f583..82d6ab231 100644
--- a/apps/web/src/phone-workspace.tsx
+++ b/apps/web/src/phone-workspace.tsx
@@ -32,6 +32,7 @@ export function PhoneTabBar(
 		documentActivity,
 		labels,
 		onSelect,
+		toolbar,
 		unanswered,
 	}: {
 		/** The circular control at the bar's trailing end, such as an edit toggle. */
@@ -44,13 +45,21 @@ export function PhoneTabBar(
 		documentActivity?: DocumentActivity;
 		labels: Record<WorkspaceDestination, string>;
 		onSelect: (destination: WorkspaceDestination, current: boolean, source: HTMLElement) => void;
+		/** Takes the tabs' place while set, such as formatting while editing; stays above the keyboard. */
+		toolbar?: ReactNode;
 		unanswered: number;
 	},
 ) {
 	let index = destinations.indexOf(active);
 	return (
-		<div className="phone-tab-row" data-phone-tab-row="">
+		<div
+			className="phone-tab-row"
+			data-phone-tab-row=""
+			data-phone-tab-toolbar={toolbar ? "" : undefined}
+		>
+			{toolbar && <div className="phone-tab-toolbar">{toolbar}</div>}
 			<nav
+				hidden={!!toolbar}
 				aria-label="Workspace view"
 				className="phone-tab-bar"
 				style={{ "--phone-tab-count": destinations.length } as CSSProperties}
diff --git a/apps/web/src/room-workspace.tsx b/apps/web/src/room-workspace.tsx
index b9c0c4159..483bf6c1f 100644
--- a/apps/web/src/room-workspace.tsx
+++ b/apps/web/src/room-workspace.tsx
@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { flushSync } from "react-dom";
 import { documentPath } from "@chopin/protocol/document-url";
-import { ArchiveIcon, ChevronIcon, DocumentIcon } from "@chopin/icons";
+import { ArchiveIcon, CheckIcon, ChevronIcon, DocumentIcon, PencilIcon } from "@chopin/icons";
 import { Badge } from "@chopin/visuals";
 import {
 	advanceDecisionView,
@@ -8,10 +9,12 @@ import {
 	countUnanswered,
 	cursor,
 	Decisions,
+	documentEditMode,
 	documentHasPlanningContent,
 	Face,
 	firstOpenDecision,
 	GitHubReferencesProvider,
+	opensEditing,
 	PlanEditor,
 	PlanStatus,
 	QuestionnaireStore,
@@ -51,6 +54,7 @@ import { DocumentActionsMenu } from "./document-actions-menu";
 import { DocumentRename } from "./document-rename";
 import { browserStorage, rememberOpened } from "./documents-sheet-model";
 import { PhoneHeader } from "./phone-header";
+import { useKeyboardOpen } from "./keyboard-open";
 import { motionContract } from "./motion-contract";
 import { motionImmediately } from "./motion-input";
 import { useNavigationDocument } from "./navigation-shell";
@@ -170,13 +174,18 @@ export function Header(
 		// Hand the caret back only when the field took it with it, not after a blur commit.
 		if (!editing && previous && document.activeElement === document.body) title.current?.focus();
 	}, [editing]);
-	let finishEdit = () => {
+	// Also runs as a save starts, not after it: keys typed while the rename travels would
+	// otherwise land in a field that is about to close.
+	let handOff = () => {
 		// Naming a new document leads into writing it, unless the user already clicked elsewhere.
 		if (editing === "new" && header.current?.contains(document.activeElement)) {
 			header.current.closest(".workspace-root")
 				?.querySelector<HTMLElement>(".plan-content[contenteditable='true']")
 				?.focus();
 		}
+	};
+	let finishEdit = () => {
+		handOff();
 		onEditingChange();
 	};
 	return (
@@ -204,6 +213,7 @@ export function Header(
 								channel={{ id: room, title: label }}
 								inline
 								onCancel={finishEdit}
+								onSavingChange={saving => saving && handOff()}
 								replay={editing === "new"}
 								onRenamed={detail => {
 									onRenamed(detail.channel);
@@ -326,6 +336,11 @@ export function RoomWorkspace(
 	let [planState, setPlanState] = useState<PlanState>({ synced: false });
 	// Claimed while rendering, so a new document's title takes focus as soon as it mounts.
 	let [titleEdit, setTitleEdit] = useState(() => claimTitleEdit(room));
+	// A phone reads until its writer asks to edit. Local to this client and this document: it
+	// survives tab changes and reconnects, and the next document opens reading again.
+	let [editing, setEditing] = useState(() => opensEditing({ renaming: titleEdit === "new" }));
+	let [formatDock, setFormatDock] = useState<HTMLElement | null>(null);
+	let keyboardOpen = useKeyboardOpen();
 	useEffect(() => {
 		let listen = (event: Event) => {
 			if ((event as CustomEvent<string>).detail !== room) return;
@@ -895,6 +910,25 @@ export function RoomWorkspace(
 
 	let workspaceArchivedAt = archivedAt ?? metadata.archivedAt;
 	let workspaceCanEdit = effectiveCanEdit && !workspaceArchivedAt;
+	let editMode = documentEditMode({
+		canEdit: !!workspaceCanEdit && !implementation.locked,
+		editing,
+		phone,
+	});
+	// An empty document has nothing to read, so it opens ready to write. Decided once, on arrival.
+	let arrived = useRef(false);
+	useEffect(() => {
+		if (!planState.synced || arrived.current) return;
+		arrived.current = true;
+		if (opensEditing({ empty: planState.empty })) setEditing(true);
+	}, [planState.synced, planState.empty]);
+	let toggleEditing = () => {
+		// Synchronous, so the editor takes focus inside the tap and iOS raises the keyboard.
+		flushSync(() => {
+			setEditing(!editing);
+			if (!editing && view !== "plan") selectDestination("plan");
+		});
+	};
 	let actOnResearchOffer = (
 		offerId: string,
 		choice: "research" | "dismiss" | "resume",
@@ -1022,6 +1056,8 @@ export function RoomWorkspace(
 			/>
 		</>
 	);
+	// A child room renders its document alone, with no tab bar for the edit toggle.
+	let childRoom = presentation.type === "child";
 	let plan = (
 		<GitHubReferencesProvider value={githubReferences}>
 			<PlanEditor
@@ -1045,6 +1081,8 @@ export function RoomWorkspace(
 				connection={status === "deleted" ? "closed" : status}
 				key={workspaceArchivedAt ? "archived" : "active"}
 				disclosureMotion={motionContract("collapse")}
+				editMode={childRoom ? undefined : editMode}
+				formatDock={!childRoom && editMode === "editing" && keyboardOpen ? formatDock : undefined}
 				motionImmediately={settleMotionImmediately}
 				onScrollTop={setPlanScrollTop}
 				onState={setPlanState}
@@ -1198,6 +1236,23 @@ export function RoomWorkspace(
 				}
 				status={statusNotices}
 				ids={workspaceIds}
+				phoneAction={editMode && (
+					<button
+						aria-label={editing ? "Done editing" : "Edit document"}
+						className="phone-tab-action"
+						data-editing={editing || undefined}
+						onClick={toggleEditing}
+						type="button"
+					>
+						<PencilIcon aria-hidden="true" data-edit-icon="edit" size={24} />
+						<CheckIcon aria-hidden="true" data-edit-icon="done" size={24} />
+					</button>
+				)}
+				// Formatting rides above the keyboard while typing. With the keyboard down the tabs
+				// return, and a selection gets the ordinary bubble instead.
+				phoneToolbar={editMode === "editing" && keyboardOpen && (
+					<div className="h-full" ref={setFormatDock} />
+				)}
 				identity={room}
 				mode={mode}
 				presence={<RoomMembers members={members} ring="page" />}
diff --git a/apps/web/src/workspace.tsx b/apps/web/src/workspace.tsx
index a8929d33a..6770dca0a 100644
--- a/apps/web/src/workspace.tsx
+++ b/apps/web/src/workspace.tsx
@@ -148,6 +148,8 @@ export type WorkspaceProps = {
 	phone?: boolean;
 	/** Extension point for a circular control at the end of the phone tab bar. */
 	phoneAction?: ReactNode;
+	/** Replaces the phone tabs while set, such as formatting while editing. */
+	phoneToolbar?: ReactNode;
 	unanswered: number;
 	chatActivity: { unread: number; busy: boolean };
 	documentActivity?: DocumentActivity;
@@ -251,6 +253,7 @@ export function Workspace(
 		onDestination,
 		phone = false,
 		phoneAction,
+		phoneToolbar,
 		plan,
 		presence,
 		presentation: workspacePresentation,
@@ -770,6 +773,7 @@ export function Workspace(
 						),
 					}}
 					onSelect={selectPhoneTab}
+					toolbar={phoneToolbar}
 					unanswered={unanswered}
 				/>
 			)}
diff --git a/e2e/phone-read-mode.e2e.ts b/e2e/phone-read-mode.e2e.ts
new file mode 100644
index 000000000..7c75f4257
--- /dev/null
+++ b/e2e/phone-read-mode.e2e.ts
@@ -0,0 +1,206 @@
+/**
+ * Reading on a phone: documents open as a reader holds them, the pencil switches to editing, and
+ * editing-only chrome stays out of a reader's way. Desktop and viewers are unchanged.
+ */
+
+import { createChannel } from "./database";
+import { authenticate, content, edit, expect, openIsolatedRoom, roomPath, test } from "./room";
+import { RESPONSIVE_SOURCE } from "./responsive";
+import { installVisualViewport, setVisualViewport } from "./visual-viewport";
+
+import type { BrowserContext, Page } from "@playwright/test";
+
+const PHONE = { hasTouch: true, isMobile: true, viewport: { width: 390, height: 844 } };
+const PROSE = "Members lose edits when the train goes into a tunnel.";
+const SOURCE = `${PROSE} See the [Yjs docs](https://example.com/yjs).
+
+Second paragraph for the caret.
+`;
+
+function pencil(page: Page) {
+	return page.getByRole("button", { name: "Edit document" });
+}
+
+function done(page: Page) {
+	return page.getByRole("button", { name: "Done editing" });
+}
+
+async function fakeKeyboard(context: BrowserContext) {
+	await installVisualViewport(context, {
+		height: 844,
+		offsetLeft: 0,
+		offsetTop: 0,
+		pageLeft: 0,
+		pageTop: 0,
+		scale: 1,
+		width: 390,
+	});
+}
+
+test("a phone opens a document for reading", async ({ join, seed }) => {
+	await seed(SOURCE);
+	let page = await join("ana", PHONE);
+	await expect(content(page)).toHaveAttribute("contenteditable", "false");
+	await expect(pencil(page)).toBeVisible();
+	let box = await pencil(page).boundingBox();
+	expect(box!.width).toBeGreaterThanOrEqual(44);
+
+	// Tapping prose places no caret, so no keyboard comes up.
+	await page.getByText("Second paragraph").tap();
+	expect(
+		await page.evaluate(() => (document.activeElement as HTMLElement | null)?.isContentEditable),
+	)
+		.toBe(false);
+
+	// A reader's selection can still be commented on, and offers no formatting.
+	await page.getByText("Second paragraph").evaluate(element => {
+		let text = document.createTreeWalker(element, NodeFilter.SHOW_TEXT).nextNode()!;
+		let range = document.createRange();
+		range.setStart(text, 0);
+		range.setEnd(text, 6);
+		getSelection()!.removeAllRanges();
+		getSelection()!.addRange(range);
+	});
+	await expect(page.getByRole("button", { name: "Comment on this passage" })).toBeVisible();
+	await expect(page.getByRole("button", { name: "Bold" })).toHaveCount(0);
+});
+
+test("a reader's tap follows a link instead of previewing it", async ({ join, seed }) => {
+	await seed(SOURCE);
+	let page = await join("ana", PHONE);
+	await page.context().route(
+		"https://example.com/**",
+		route => route.fulfill({ body: "<title>Yjs</title>", contentType: "text/html" }),
+	);
+	let opened = page.context().waitForEvent("page");
+	await page.getByRole("link", { name: "Yjs docs" }).tap();
+	expect((await opened).url()).toBe("https://example.com/yjs");
+	await expect(page.getByRole("button", { name: /^Open/ })).toHaveCount(0);
+});
+
+test("an in-app link navigates within Chopin", async ({ baseURL, join, room, seed }) => {
+	let other = crypto.randomUUID();
+	await createChannel(Number(new URL(baseURL!).port), other);
+	await seed(`Read [the other document](${roomPath(other)}) next.\n`);
+	let page = await join("ana", PHONE);
+	await page.getByRole("link", { name: "the other document" }).tap();
+	await expect(page).toHaveURL(new RegExp(`${roomPath(other)}$`));
+	await expect(page).not.toHaveURL(new RegExp(`${roomPath(room)}$`));
+});
+
+test("the pencil edits where the reader tapped and Done returns to reading", async ({ join, seed }) => {
+	await seed(SOURCE);
+	let page = await join("ana", PHONE);
+	let writer = await join("bo", { viewport: { width: 1440, height: 900 } });
+
+	await page.getByText("Second paragraph").tap();
+	await pencil(page).tap();
+	await expect(content(page)).toHaveAttribute("contenteditable", "true");
+	await expect(content(page)).toBeFocused();
+	await expect(done(page)).toBeVisible();
+	await page.keyboard.type("Typed ");
+	await expect(content(page)).toContainText("Typed ");
+	await expect(writer.getByText(/Typed /)).toBeVisible();
+
+	// Editing survives a trip to another tab.
+	let tabs = page.getByRole("navigation", { name: "Workspace view" });
+	await tabs.getByRole("button", { name: /^Chat/ }).tap();
+	await expect(page.getByRole("complementary", { name: "Chat" })).toBeVisible();
+	await tabs.getByRole("button", { name: "Document", exact: true }).tap();
+	await expect(done(page)).toBeVisible();
+
+	await done(page).tap();
+	await expect(content(page)).toHaveAttribute("contenteditable", "false");
+	await expect(pencil(page)).toBeVisible();
+	expect(
+		await page.evaluate(() => (document.activeElement as HTMLElement | null)?.isContentEditable),
+	)
+		.toBeFalsy();
+
+	// Someone else's edits keep arriving while reading.
+	await content(writer).click();
+	await writer.keyboard.press("ControlOrMeta+End");
+	await writer.keyboard.type(" Remote words.");
+	await expect(content(page)).toContainText("Remote words.");
+});
+
+test("formatting docks above the keyboard while editing", async ({ baseURL, browser, room, seed }) => {
+	await seed(SOURCE);
+	let { close, page } = await openIsolatedRoom(browser, baseURL!, room, "ana", PHONE, fakeKeyboard);
+	try {
+		await page.getByText("Second paragraph").tap();
+		await pencil(page).tap();
+		await setVisualViewport(page, { event: "resize", height: 500 });
+		let dock = page.getByRole("toolbar", { name: "Formatting" });
+		await expect(dock).toBeVisible();
+		await expect(page.getByRole("navigation", { name: "Workspace view" })).toBeHidden();
+		await expect(done(page)).toBeVisible();
+		for (let control of await dock.getByRole("button").all()) {
+			let box = await control.boundingBox();
+			if (box) expect(box.height).toBeGreaterThanOrEqual(44);
+		}
+		let bottom = await dock.evaluate(element => element.getBoundingClientRect().bottom);
+		expect(bottom).toBeLessThanOrEqual(500);
+
+		await dock.getByRole("button", { name: "Bold" }).tap();
+		await page.keyboard.type("loud");
+		await expect(content(page).locator("strong, b").filter({ hasText: "loud" })).toHaveCount(1);
+		await expect(content(page)).toBeFocused();
+		// One formatting surface at a time.
+		await expect(page.getByRole("toolbar", { name: "Text formatting" })).toHaveCount(0);
+
+		await dock.getByRole("button", { name: "Hide keyboard" }).tap();
+		await expect(content(page)).not.toBeFocused();
+		await setVisualViewport(page, { event: "resize", height: 844 });
+		await expect(dock).toHaveCount(0);
+		await expect(page.getByRole("navigation", { name: "Workspace view" })).toBeVisible();
+	} finally {
+		await close();
+	}
+});
+
+test("reading hides editing-only chrome that editing brings back", async ({ join, seed }) => {
+	await seed(RESPONSIVE_SOURCE);
+	let page = await join("ana", PHONE);
+	let editing = [
+		page.getByRole("button", { name: "Show source" }),
+		page.getByRole("button", { name: /^Code language:/ }),
+		page.getByRole("button", { name: "Edit image" }),
+		page.getByRole("button", { name: "Add tab" }),
+		page.getByRole("button", { name: /^Remove / }),
+	];
+	for (let control of editing) await expect(control).toHaveCount(0);
+	// The language still reads as a label.
+	await expect(content(page).getByText("TypeScript", { exact: true }).first()).toBeAttached();
+
+	await edit(page);
+	await expect(page.getByRole("button", { name: "Show source" }).first()).toBeAttached();
+	await expect(page.getByRole("button", { name: "Add tab" }).first()).toBeAttached();
+});
+
+test("viewers get no pencil and desktop stays editable", async ({ baseURL, browser, join, room, seed }) => {
+	await seed(SOURCE);
+	let desktop = await join("ana", { viewport: { width: 1440, height: 900 } });
+	await expect(content(desktop)).toHaveAttribute("contenteditable", "true");
+	await expect(pencil(desktop)).toHaveCount(0);
+
+	let context = await browser.newContext({ ...PHONE, baseURL });
+	try {
+		let viewer = await context.newPage();
+		await authenticate(viewer, "readonly", baseURL!);
+		await viewer.goto(roomPath(room));
+		await expect(viewer.locator("[data-plan-synced]")).toBeAttached({ timeout: 20_000 });
+		await expect(content(viewer)).toHaveAttribute("contenteditable", "false");
+		await expect(viewer.getByRole("navigation", { name: "Workspace view" })).toBeVisible();
+		await expect(pencil(viewer)).toHaveCount(0);
+		await expect(done(viewer)).toHaveCount(0);
+	} finally {
+		await context.close();
+	}
+});
+
+test("an empty document opens ready to write", async ({ join }) => {
+	let page = await join("ana", PHONE);
+	await expect(done(page)).toBeVisible();
+	await expect(content(page)).toHaveAttribute("contenteditable", "true");
+});
diff --git a/e2e/responsive-workspace.e2e.ts b/e2e/responsive-workspace.e2e.ts
index 77cbbd160..a4cec8c50 100644
--- a/e2e/responsive-workspace.e2e.ts
+++ b/e2e/responsive-workspace.e2e.ts
@@ -1,4 +1,4 @@
-import { authenticate, content, expect, openIsolatedRoom, ready, test } from "./room";
+import { authenticate, content, edit, expect, openIsolatedRoom, ready, test } from "./room";
 import { chatInput, expectChatValue } from "./chat-input";
 import { expectInsideViewport, expectNoHorizontalOverflow, RESPONSIVE_SOURCE } from "./responsive";
 import { installVisualViewport, setVisualViewport } from "./visual-viewport";
@@ -117,7 +117,8 @@ test("a representative compact phone exposes one mounted destination at a time",
 	await expect(chatPane(page)).toBeHidden();
 	await expect(page.getByRole("dialog", { name: "Implementation", exact: true })).toHaveCount(0);
 	await nav.getByRole("button", { name: "Document", exact: true }).click();
-	await expect(content(page)).toBeEditable();
+	await expect(content(page)).toBeVisible();
+	await edit(page);
 	await expectNoHorizontalOverflow(page);
 });
 
@@ -620,6 +621,7 @@ test("Chromium visual viewport emulation keeps document editing above the keyboa
 	let emulation = await emulatedVisualViewportPage(browser, baseURL!, room);
 	try {
 		let editor = content(emulation.page);
+		await edit(emulation.page);
 		await editor.focus();
 		await setVisualViewport(emulation.page, {
 			event: "resize",
diff --git a/e2e/room.ts b/e2e/room.ts
index f56579c83..b24ade616 100644
--- a/e2e/room.ts
+++ b/e2e/room.ts
@@ -128,9 +128,21 @@ export function content(page: Page) {
 	return page.getByRole("textbox", { name: "editable markdown" });
 }
 
-/** Wait until the channel has synchronized and can be typed into. */
+/**
+ * Wait until the channel has synchronized and can be typed into, or, on a phone, has opened for
+ * reading. Call `edit` before typing into a document opened on a phone.
+ */
 export async function ready(page: Page): Promise<void> {
-	await expect(content(page)).toHaveAttribute("contenteditable", "true", { timeout: 20_000 });
+	let editable = page.locator(".plan-content[contenteditable='true']");
+	let reading = page.locator(".plan[data-plan-reading] [data-plan-synced]");
+	await expect(editable.or(reading).first()).toBeAttached({ timeout: 20_000 });
+}
+
+/** A phone opens documents for reading; switch to editing the way a writer would. */
+export async function edit(page: Page): Promise<void> {
+	let pencil = page.getByRole("button", { name: "Edit document" });
+	if (await pencil.isVisible()) await pencil.click();
+	await expect(content(page)).toHaveAttribute("contenteditable", "true");
 }
 
 /** The status pane, which keeps its label in the DOM even when it draws nothing. */
diff --git a/e2e/sidecar.e2e.ts b/e2e/sidecar.e2e.ts
index 2df9fecbe..62c814172 100644
--- a/e2e/sidecar.e2e.ts
+++ b/e2e/sidecar.e2e.ts
@@ -12,7 +12,7 @@ import { chatInput, expectChatValue } from "./chat-input";
  * test here writes the plan before anybody opens it.
  */
 
-import { authenticate, content, expect, ready, roomPath, test } from "./room";
+import { authenticate, content, edit, expect, ready, roomPath, test } from "./room";
 import { storedQuestion } from "../apps/server/src/testing/plan";
 
 import type { Locator, Page } from "@playwright/test";
@@ -998,6 +998,7 @@ test("a compact new-comment sheet blocks navigation and restores editor focus",
 		isMobile: true,
 		viewport: { width: 390, height: 844 },
 	});
+	await edit(page);
 	let editor = content(page);
 	let plan = page.getByRole("button", {
 		name: "Document",
@@ -1053,6 +1054,7 @@ test("submitting a compact new comment restores editor focus", async ({ join, se
 		isMobile: true,
 		viewport: { width: 390, height: 844 },
 	});
+	await edit(page);
 	let editor = content(page);
 	await editor.locator("p").nth(1).selectText();
 	await page.getByRole("button", { name: "Comment on this passage", exact: true }).click();
@@ -1071,6 +1073,7 @@ test("resolving a compact comment restores editor focus", async ({ join, seed })
 		isMobile: true,
 		viewport: { width: 390, height: 844 },
 	});
+	await edit(page);
 	let editor = content(page);
 	let sheet = await thread(page);
 	await sheet.getByRole("button", { name: "Resolve", exact: true }).click();
@@ -1305,6 +1308,7 @@ test("a compact orphan sheet owns focus and restores its opener", async ({ join,
 		isMobile: true,
 		viewport: { width: 390, height: 844 },
 	});
+	await edit(page);
 	let first = content(page).locator("p").first();
 	await first.selectText();
 	await page.keyboard.press("Backspace");
@@ -1331,6 +1335,7 @@ test("a remotely orphaned compact comment closes its sheet and restores editor f
 		isMobile: true,
 		viewport: { width: 390, height: 844 },
 	});
+	await edit(page);
 	let editor = content(page);
 	let sheet = await thread(page);
 	await expect(sheet.getByRole("button", { name: "Close comment" })).toBeFocused();
diff --git a/e2e/tab-authoring.e2e.ts b/e2e/tab-authoring.e2e.ts
index 3a77a3ed7..f55a7c7f3 100644
--- a/e2e/tab-authoring.e2e.ts
+++ b/e2e/tab-authoring.e2e.ts
@@ -1,4 +1,4 @@
-import { content, expect, test, written } from "./room";
+import { content, edit, expect, test, written } from "./room";
 
 import type { WebSocketRoute } from "@playwright/test";
 
@@ -116,6 +116,7 @@ test("touch removes the selected tab with one tap", async ({ join, seed }) => {
 		hasTouch: true,
 		isMobile: true,
 	});
+	await edit(page);
 	let strip = content(page).getByRole("tablist");
 	let remove = content(page).getByRole("button", { name: "Remove Mobile", exact: true });
 	await expect(remove).toHaveCSS("opacity", "1");
diff --git a/e2e/table.e2e.ts b/e2e/table.e2e.ts
index b7b3200d1..de18d898d 100644
--- a/e2e/table.e2e.ts
+++ b/e2e/table.e2e.ts
@@ -14,7 +14,7 @@
  * which elements get rendered.
  */
 
-import { content, expect, openIsolatedRoom, test } from "./room";
+import { content, edit, expect, openIsolatedRoom, test } from "./room";
 import { expectFocusIndicator } from "./focus";
 import { installPointerMedia } from "./pointer-media";
 import { expectInsideViewport, expectNoHorizontalOverflow } from "./responsive";
@@ -77,6 +77,7 @@ function items(page: Page): Locator {
 }
 
 async function touchToolbar(page: Page, cell: Locator = content(page).locator("td").first()) {
+	await edit(page);
 	await cell.tap();
 	let toolbar = page.getByRole("toolbar", { name: "Table actions" });
 	await expect(toolbar).toBeVisible();
diff --git a/e2e/toolbar.e2e.ts b/e2e/toolbar.e2e.ts
index 098a778dc..6a156fcb0 100644
--- a/e2e/toolbar.e2e.ts
+++ b/e2e/toolbar.e2e.ts
@@ -7,9 +7,18 @@
  * required. Everything here is on the other side of that line.
  */
 
-import { authenticate, content, expect, openIsolatedRoom, roomPath, test, written } from "./room";
+import {
+	authenticate,
+	content,
+	edit,
+	expect,
+	openIsolatedRoom,
+	roomPath,
+	test,
+	written,
+} from "./room";
 import { expectInsideViewport } from "./responsive";
-import { installVisualViewport } from "./visual-viewport";
+import { installVisualViewport, setVisualViewport } from "./visual-viewport";
 
 import type { Browser, Locator, Page } from "@playwright/test";
 
@@ -579,6 +588,7 @@ test("touch editor menus use reachable targets and stay inside the viewport", as
 		viewport: { width: 390, height: 844 },
 	});
 
+	await edit(page);
 	await content(page).click();
 	await page.keyboard.type("/");
 	let menu = page.getByRole("listbox", MENU);
@@ -634,6 +644,10 @@ test("an open slash menu follows its caret while the editor scrolls", async ({ b
 	await seed(LONG_EDITOR);
 	let emulation = await emulatedVisualViewportPage(browser, baseURL!, room);
 	try {
+		// The keyboard hides the edit toggle; a reader opens editing before typing raises it.
+		await setVisualViewport(emulation.page, { event: "resize", height: 844, offsetTop: 0 });
+		await edit(emulation.page);
+		await setVisualViewport(emulation.page, { event: "resize", height: 640, offsetTop: 72 });
 		let block = content(emulation.page).getByText("Paragraph 9.", { exact: true });
 		await block.scrollIntoViewIfNeeded();
 		// Start in the upper third, so the menu opens below the caret and has room to stay there:
diff --git a/packages/editor/src/edit-mode.test.ts b/packages/editor/src/edit-mode.test.ts
new file mode 100644
index 000000000..7b4a7bfc1
--- /dev/null
+++ b/packages/editor/src/edit-mode.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+
+import { documentEditMode, opensEditing, selectionOffer } from "./edit-mode";
+
+describe("documentEditMode", () => {
+	test("phones read until a writer asks to edit", () => {
+		expect(documentEditMode({ canEdit: true, editing: false, phone: true })).toBe("reading");
+		expect(documentEditMode({ canEdit: true, editing: true, phone: true })).toBe("editing");
+	});
+
+	test("desktop and viewers have no mode", () => {
+		expect(documentEditMode({ canEdit: true, editing: false, phone: false })).toBeUndefined();
+		expect(documentEditMode({ canEdit: true, editing: true, phone: false })).toBeUndefined();
+		// Permission wins: a viewer is read-only, not reading.
+		expect(documentEditMode({ canEdit: false, editing: true, phone: true })).toBeUndefined();
+	});
+});
+
+describe("opensEditing", () => {
+	test("new and empty documents open editing", () => {
+		expect(opensEditing({ renaming: true })).toBe(true);
+		expect(opensEditing({ empty: true })).toBe(true);
+		expect(opensEditing({ empty: false })).toBe(false);
+		expect(opensEditing({})).toBe(false);
+	});
+});
+
+describe("selectionOffer", () => {
+	test("reading keeps commenting", () => {
+		expect(selectionOffer({ docked: false, locked: false, mode: "reading" })).toBe("comment");
+	});
+
+	test("any other lock offers nothing, even while reading", () => {
+		expect(selectionOffer({ docked: false, locked: true, mode: "reading" })).toBe("none");
+		expect(selectionOffer({ docked: false, locked: true })).toBe("none");
+	});
+
+	test("the docked toolbar replaces the bubble while editing", () => {
+		expect(selectionOffer({ docked: true, locked: false, mode: "editing" })).toBe("none");
+		expect(selectionOffer({ docked: false, locked: false, mode: "editing" })).toBe("format");
+	});
+
+	test("desktop formats as before", () => {
+		expect(selectionOffer({ docked: false, locked: false })).toBe("format");
+	});
+});
diff --git a/packages/editor/src/edit-mode.ts b/packages/editor/src/edit-mode.ts
new file mode 100644
index 000000000..099d179b5
--- /dev/null
+++ b/packages/editor/src/edit-mode.ts
@@ -0,0 +1,42 @@
+/**
+ * Reading and editing on a phone.
+ *
+ * A phone holds a document the way a reader does until its writer asks to edit: tapping prose
+ * selects or follows links instead of raising the keyboard. This is a local choice, never synced,
+ * and separate from permission: a viewer is read-only whatever this says, and a reader who may
+ * write can still select and comment, which a permission lock does not allow.
+ */
+
+/** How this client holds a document. `undefined` means the surface has no reading mode. */
+export type EditMode = "reading" | "editing";
+
+/** Phones read until asked to edit. Elsewhere, and for anyone who cannot write, there is no mode. */
+export function documentEditMode(
+	{ canEdit, editing, phone }: { canEdit: boolean; editing: boolean; phone: boolean },
+): EditMode | undefined {
+	if (!phone || !canEdit) return undefined;
+	return editing ? "editing" : "reading";
+}
+
+/** Whether a document should open straight into editing: there is nothing yet to read. */
+export function opensEditing(
+	{ empty, renaming }: { empty?: boolean; renaming?: boolean },
+): boolean {
+	return !!renaming || !!empty;
+}
+
+/**
+ * What a non-collapsed selection offers.
+ *
+ * `locked` is every reason the editor cannot be edited except reading mode itself: a permission,
+ * an agent turn, a lost connection, or a document that has not arrived. Reading keeps commenting;
+ * a docked formatting toolbar takes over formatting while editing on a phone.
+ */
+export function selectionOffer(
+	{ docked, locked, mode }: { docked: boolean; locked: boolean; mode?: EditMode },
+): "none" | "comment" | "format" {
+	if (locked) return "none";
+	if (mode === "reading") return "comment";
+	if (mode === "editing" && docked) return "none";
+	return "format";
+}
diff --git a/packages/editor/src/index.ts b/packages/editor/src/index.ts
index 9c7d58900..90a459739 100644
--- a/packages/editor/src/index.ts
+++ b/packages/editor/src/index.ts
@@ -31,6 +31,8 @@ export {
 } from "./disclosure-motion";
 export type { MotionDisclosureContract } from "./disclosure-motion";
 export { displayName } from "./display-name";
+export { documentEditMode, opensEditing, selectionOffer } from "./edit-mode";
+export type { EditMode } from "./edit-mode";
 export { AgentFace, Face } from "./face";
 export type { FaceProps } from "./face";
 export { GitHubReferencesProvider } from "./github-references";
diff --git a/packages/editor/src/plan-editor.tsx b/packages/editor/src/plan-editor.tsx
index db515c79c..d7abacbfa 100644
--- a/packages/editor/src/plan-editor.tsx
+++ b/packages/editor/src/plan-editor.tsx
@@ -8,6 +8,14 @@
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { markdownShortcutPlugin, MDXEditor } from "@mdxeditor/editor";
+import {
+	$getNearestNodeFromDOMNode,
+	$getRoot,
+	$isElementNode,
+	$isParagraphNode,
+	$isTextNode,
+	BLUR_COMMAND,
+} from "lexical";
 
 // Structural editor CSS, then our retheme over the top.
 import "@mdxeditor/editor/style.css";
@@ -35,6 +43,8 @@ import type { PlanProvider } from "./provider";
 import type { QuestionnaireStore } from "./questionnaires";
 import type { ThreadStore } from "./threads";
 import type { Connection, Transport } from "./transport";
+import type { EditMode } from "./edit-mode";
+import type { LexicalEditor } from "lexical";
 import type { CommentPresentation, QuestionStepMotion, ResearchStore } from "./widget-options";
 import type { Refusal } from "./history";
 import type { ResearchLauncher } from "./research-launcher";
@@ -77,6 +87,13 @@ export type PlanEditorProps = {
 	busy?: boolean;
 	/** Read-only because this participant may view but not edit. */
 	readOnly?: boolean;
+	/**
+	 * This client's own reading or editing mode on a phone. Reading locks the text like
+	 * `readOnly` but keeps selection and commenting; a permission lock still wins.
+	 */
+	editMode?: EditMode;
+	/** Host element for the docked formatting toolbar while editing on a phone. */
+	formatDock?: HTMLElement | null;
 	/**
 	 * Where the plan's questionnaires are published.
 	 *
@@ -125,6 +142,8 @@ export type PlanState = {
 	lost?: number;
 	/** Why it could not be opened at all, if it could not. */
 	failed?: string;
+	/** Whether the document held no content when it last finished opening. */
+	empty?: boolean;
 	/**
 	 * An undo or redo this person just asked for that could not be applied
 	 * safely, for the host to mention briefly. A new object for each refusal.
@@ -144,6 +163,8 @@ export function PlanEditor(
 		commentPresentation = "popover",
 		connection,
 		disclosureMotion,
+		editMode,
+		formatDock,
 		motionImmediately,
 		onScrollTop,
 		onState,
@@ -199,7 +220,9 @@ export function PlanEditor(
 
 	// The store resolves anchors itself, because a Lexical key is per-editor:
 	// the server's key for a block means nothing in this browser.
+	let bindingRef = useRef<Binding>(undefined);
 	let onBinding = useCallback((value: Binding | undefined) => {
+		bindingRef.current = value;
 		setBinding(value);
 		questions?.bind(value);
 		threads?.bind(value);
@@ -293,7 +316,9 @@ export function PlanEditor(
 			resume(value);
 		});
 		value.on("sync", synced => {
-			setState(prev => ({ ...prev, synced }));
+			let editor = bindingRef.current?.editor;
+			let empty = synced && editor ? isEmpty(editor) : undefined;
+			setState(prev => ({ ...prev, synced, empty: empty ?? prev.empty }));
 			questions?.setDocumentSynced(synced);
 		});
 		value.on("status", ({ message, status }) => {
@@ -328,7 +353,56 @@ export function PlanEditor(
 	// Locking waits out a blip, and edits made meanwhile wait in the outbox.
 	let offline = useConnectionNotice(connection !== undefined && connection !== "connected")
 		!== "none";
-	let locked = offline || !!busy || !!readOnly || !state.synced;
+	let blocked = offline || !!busy || !!readOnly || !state.synced;
+	let locked = blocked || editMode === "reading";
+
+	// Where a reader last tapped, so that choosing Edit can put the caret there.
+	let tapped = useRef<{ node: Node; offset: number }>(undefined);
+	useEffect(() => {
+		let element = scroller.current;
+		if (!element || editMode !== "reading") return;
+		let tap = (event: PointerEvent) => {
+			let point = caretAt(event.clientX, event.clientY);
+			if (point && element.querySelector(".plan-content")?.contains(point.node)) {
+				tapped.current = point;
+			}
+		};
+		element.addEventListener("pointerup", tap);
+		return () => element.removeEventListener("pointerup", tap);
+	}, [editMode, generation, wire]);
+
+	/*
+	 * Moving between reading and editing.
+	 *
+	 * Runs after MDXEditor has applied the lock, because its effects run before this parent's.
+	 * A host that changes mode inside the tap (with `flushSync`) keeps the focus inside the user
+	 * gesture, which is what lets iOS raise the keyboard.
+	 */
+	let previousMode = useRef(editMode);
+	useEffect(() => {
+		let previous = previousMode.current;
+		previousMode.current = editMode;
+		let editor = binding?.editor;
+		if (!editor || previous === editMode) return;
+		if (editMode === "reading") {
+			// A contenteditable that stops being editable while focused fires no blur, which would
+			// leave this client's caret showing to everyone else.
+			let root = editor.getRootElement();
+			let active = document.activeElement;
+			if (root && active instanceof HTMLElement && root.contains(active)) active.blur();
+			editor.dispatchCommand(BLUR_COMMAND, new FocusEvent("blur"));
+			let selection = window.getSelection();
+			if (root && selection?.anchorNode && root.contains(selection.anchorNode)) {
+				selection.removeAllRanges();
+			}
+			return;
+		}
+		if (previous !== "reading" || editMode !== "editing" || !editor.isEditable()) return;
+		let point = tapped.current;
+		tapped.current = undefined;
+		editor.getRootElement()?.focus({ preventScroll: true });
+		editor.update(() => placeCaret(point, editor, scroller.current), { discrete: true });
+	}, [binding, editMode]);
 
 	// Empty without a connection, and never used: the editor is not rendered
 	// at all until there is one, so there is nothing to configure.
@@ -393,6 +467,9 @@ export function PlanEditor(
 						wire,
 						connected: !offline,
 						canEdit: !readOnly,
+						editMode,
+						blocked,
+						formatDock,
 						self: user.name,
 						synced: state.synced,
 					}),
@@ -428,6 +505,9 @@ export function PlanEditor(
 			changes,
 			offline,
 			readOnly,
+			editMode,
+			blocked,
+			formatDock,
 			state.synced,
 		],
 	);
@@ -456,6 +536,7 @@ export function PlanEditor(
 			className={`plan flex h-full w-full flex-col ${className ?? ""}`}
 			data-plan-afterword={!!afterword || undefined}
 			data-plan-offline={offline || undefined}
+			data-plan-reading={editMode === "reading" || undefined}
 		>
 			<div className="plan-workspace">
 				<div className="plan-document">
@@ -496,3 +577,59 @@ export function PlanEditor(
 		</div>
 	);
 }
+
+/** Whether the document has nothing in it yet: no blocks, or one empty paragraph. */
+function isEmpty(editor: LexicalEditor): boolean {
+	return editor.read(() => {
+		let root = $getRoot();
+		let first = root.getFirstChild();
+		return root.getChildrenSize() === 0
+			|| (root.getChildrenSize() === 1 && $isParagraphNode(first)
+				&& first.getTextContentSize() === 0);
+	});
+}
+
+function caretAt(x: number, y: number): { node: Node; offset: number } | undefined {
+	if (document.caretPositionFromPoint) {
+		let position = document.caretPositionFromPoint(x, y);
+		return position ? { node: position.offsetNode, offset: position.offset } : undefined;
+	}
+	let range = document.caretRangeFromPoint?.(x, y);
+	return range ? { node: range.startContainer, offset: range.startOffset } : undefined;
+}
+
+/**
+ * Put the caret where the reader last tapped, or else at the start of the first block in view, so
+ * starting to edit never scrolls the reader away from what they were looking at. Call in an update.
+ */
+function placeCaret(
+	point: { node: Node; offset: number } | undefined,
+	editor: LexicalEditor,
+	scroller: HTMLElement | null,
+): void {
+	let node = point?.node.isConnected ? $getNearestNodeFromDOMNode(point.node) : null;
+	if ($isTextNode(node)) {
+		let offset = Math.min(point?.offset ?? 0, node.getTextContentSize());
+		node.select(offset, offset);
+		return;
+	}
+	if ($isElementNode(node) && !node.isInline()) {
+		node.selectStart();
+		return;
+	}
+	let root = editor.getRootElement();
+	// Content scrolls under the host's top bar, which the scroll padding accounts for.
+	let top = scroller
+		? scroller.getBoundingClientRect().top
+			+ (parseFloat(getComputedStyle(scroller).scrollPaddingTop) || 0)
+		: 0;
+	for (let child of root?.children ?? []) {
+		if (child.getBoundingClientRect().bottom <= top) continue;
+		let block = $getNearestNodeFromDOMNode(child);
+		if ($isElementNode(block)) {
+			block.selectStart();
+			return;
+		}
+	}
+	$getRoot().selectEnd();
+}
diff --git a/packages/editor/src/styles.css b/packages/editor/src/styles.css
index fe8c01cc2..6043ea3d7 100644
--- a/packages/editor/src/styles.css
+++ b/packages/editor/src/styles.css
@@ -5512,3 +5512,50 @@ body:has(.plan-comment-sheet-popup[data-swiping])
 	.plan-content {
 	padding-bottom: calc(var(--spacing) * 6);
 }
+
+/* Formatting docked above a phone's keyboard while editing; the host supplies the surface. */
+.plan-format-dock {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: calc(var(--spacing) / 2);
+	min-width: 0;
+	height: 100%;
+	padding-inline: var(--spacing);
+	overflow-x: auto;
+	overscroll-behavior-x: contain;
+	scrollbar-width: none;
+	-webkit-user-select: none;
+	user-select: none;
+}
+
+.plan-format-dock::-webkit-scrollbar {
+	display: none;
+}
+
+.plan-format-dock-button {
+	display: grid;
+	flex: none;
+	place-items: center;
+	width: var(--control-target-coarse);
+	height: var(--control-target-coarse);
+	border-radius: var(--radius-full);
+	color: var(--color-text-secondary);
+	font-size: var(--text-lg);
+	line-height: 1;
+	touch-action: manipulation;
+	-webkit-touch-callout: none;
+	transition:
+		background-color var(--duration-fast) var(--ease-out),
+		color var(--duration-fast) var(--ease-out);
+}
+
+.plan-format-dock-button:active:not(:disabled),
+.plan-format-dock-button[aria-pressed="true"] {
+	background: var(--color-selected);
+	color: var(--color-text-primary);
+}
+
+.plan-format-dock-button:disabled {
+	opacity: var(--opacity-quiet);
+}
diff --git a/packages/editor/src/toolbar/bubble.tsx b/packages/editor/src/toolbar/bubble.tsx
index f2f62b82b..6e52168e1 100644
--- a/packages/editor/src/toolbar/bubble.tsx
+++ b/packages/editor/src/toolbar/bubble.tsx
@@ -55,7 +55,7 @@ import {
 } from "lexical";
 
 import type { HeadingTagType } from "@lexical/rich-text";
-import type { ElementNode, LexicalNode, TextFormatType } from "lexical";
+import type { ElementNode, LexicalEditor, LexicalNode, TextFormatType } from "lexical";
 import type { DOMRectLike, SurfacePlacement } from "./placement";
 
 /** Block shapes the bubble can switch between. */
@@ -145,6 +145,51 @@ export function $block(node: LexicalNode | null): Block {
 	return "paragraph";
 }
 
+/** Change the selected blocks from one shape to another, the same way the block menu does. */
+export function convertBlock(editor: LexicalEditor, block: Block, next: Block): void {
+	// Already a quote: converting again would nest one inside the other.
+	if (next === block || next === "task") return;
+
+	if (next === "bullet") {
+		editor.dispatchCommand(INSERT_UNORDERED_LIST_COMMAND, undefined);
+		return;
+	}
+	if (next === "number") {
+		editor.dispatchCommand(INSERT_ORDERED_LIST_COMMAND, undefined);
+		return;
+	}
+	// Containers are unwrapped, not swapped: `$setBlocksType` converts the
+	// block it finds and leaves the list or quote standing around it.
+	if (block === "bullet" || block === "number" || block === "task") {
+		editor.dispatchCommand(REMOVE_LIST_COMMAND, undefined);
+	}
+	if (block === "quote") {
+		editor.update(() => {
+			let selection = $getSelection();
+			if (!$isRangeSelection(selection)) return;
+			let inner = owner(selection.anchor.getNode());
+			// Only the wrapping shape needs lifting. Where the quote is
+			// itself the block, `$setBlocksType` below replaces it.
+			if ($isQuoteNode(inner)) return;
+			let quote = quoted(inner);
+			if (!quote) return;
+			for (let child of quote.getChildren()) quote.insertBefore(child);
+			quote.remove();
+		});
+	}
+
+	let build: () => ElementNode = next === "quote"
+		? $createQuoteNode
+		: next === "paragraph"
+		? $createParagraphNode
+		: () => $createHeadingNode(next);
+
+	editor.update(() => {
+		let selection = $getSelection();
+		if ($isRangeSelection(selection)) $setBlocksType(selection, build);
+	});
+}
+
 type Mark = { format: TextFormatType; label: string; glyph: ReactNode; shortcut: string };
 
 /** Each letter is drawn in the style it applies, so the row reads as a format bar. */
@@ -194,7 +239,9 @@ function usePrimaryCoarse(): boolean {
 }
 
 export function SelectionBubble(
-	{ disabled, hidden, onComment }: {
+	{ commentOnly, disabled, hidden, onComment }: {
+		/** A reader's selection: the text cannot change, so only commenting is offered. */
+		commentOnly?: boolean;
 		disabled?: boolean;
 		/** Another surface has taken the bubble's place for now. */
 		hidden?: boolean;
@@ -261,45 +308,7 @@ export function SelectionBubble(
 
 	let convert = useCallback((next: Block) => {
 		setChoosing(false);
-		// Already a quote: converting again would nest one inside the other.
-		if (next === block || next === "task") return;
-
-		if (next === "bullet") {
-			return editor.dispatchCommand(INSERT_UNORDERED_LIST_COMMAND, undefined);
-		}
-		if (next === "number") {
-			return editor.dispatchCommand(INSERT_ORDERED_LIST_COMMAND, undefined);
-		}
-		// Containers are unwrapped, not swapped: `$setBlocksType` converts the
-		// block it finds and leaves the list or quote standing around it.
-		if (block === "bullet" || block === "number" || block === "task") {
-			editor.dispatchCommand(REMOVE_LIST_COMMAND, undefined);
-		}
-		if (block === "quote") {
-			editor.update(() => {
-				let selection = $getSelection();
-				if (!$isRangeSelection(selection)) return;
-				let inner = owner(selection.anchor.getNode());
-				// Only the wrapping shape needs lifting. Where the quote is
-				// itself the block, `$setBlocksType` below replaces it.
-				if ($isQuoteNode(inner)) return;
-				let quote = quoted(inner);
-				if (!quote) return;
-				for (let child of quote.getChildren()) quote.insertBefore(child);
-				quote.remove();
-			});
-		}
-
-		let build: () => ElementNode = next === "quote"
-			? $createQuoteNode
-			: next === "paragraph"
-			? $createParagraphNode
-			: () => $createHeadingNode(next);
-
-		editor.update(() => {
-			let selection = $getSelection();
-			if ($isRangeSelection(selection)) $setBlocksType(selection, build);
-		});
+		convertBlock(editor, block, next);
 	}, [editor, block]);
 
 	/*
@@ -396,7 +405,7 @@ export function SelectionBubble(
 		return listenToEditorGeometry(editor, place);
 	}, [anchor, editor, place]);
 
-	if (!anchor || disabled || hidden) return null;
+	if (!anchor || disabled || hidden || (commentOnly && !onComment)) return null;
 
 	let comment = onComment && (
 		<button
@@ -445,7 +454,9 @@ export function SelectionBubble(
 			 */
 			onMouseDown={event => event.preventDefault()}
 		>
-			{choosing
+			{commentOnly
+				? comment
+				: choosing
 				? BLOCKS.map(item => (
 					<button
 						key={item.id}
diff --git a/packages/editor/src/toolbar/dock.tsx b/packages/editor/src/toolbar/dock.tsx
new file mode 100644
index 000000000..009acf04d
--- /dev/null
+++ b/packages/editor/src/toolbar/dock.tsx
@@ -0,0 +1,150 @@
+/**
+ * Formatting docked above a phone's keyboard while editing.
+ *
+ * The same commands as the selection bubble, in a fixed row the thumb can reach, so a phone
+ * never shows two formatting surfaces at once. Nothing here may take focus: the caret it acts on
+ * would go with it, and on a phone so would the keyboard.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
+import { KeyboardIcon, LinkIcon, PlusIcon } from "@chopin/icons";
+import { $getSelection, $isRangeSelection, FORMAT_TEXT_COMMAND } from "lexical";
+
+import { $block, convertBlock } from "./bubble";
+import { $linkAt, OPEN_LINK_EDITOR_COMMAND } from "./link";
+import { OPEN_SLASH_MENU_COMMAND } from "./slash";
+
+import type { ReactNode } from "react";
+import type { Block } from "./bubble";
+
+type DockState = {
+	bold: boolean;
+	italic: boolean;
+	block: Block;
+	/** A link can be added over a selection, or edited with the caret inside one. */
+	linkable: boolean;
+};
+
+const IDLE: DockState = { bold: false, italic: false, block: "paragraph", linkable: false };
+
+/** Blocks the Heading button treats as already being a heading, so it turns them back. */
+const HEADINGS = new Set<Block>(["h1", "h2", "h3", "h4", "h5", "h6"]);
+
+export function FormatDock({ disabled }: { disabled?: boolean }) {
+	let [editor] = useLexicalComposerContext();
+	let [state, setState] = useState<DockState>(IDLE);
+
+	let sync = useCallback(() => {
+		editor.getEditorState().read(() => {
+			let selection = $getSelection();
+			if (!$isRangeSelection(selection)) return setState(IDLE);
+			setState({
+				bold: selection.hasFormat("bold"),
+				italic: selection.hasFormat("italic"),
+				block: $block(selection.anchor.getNode()),
+				linkable: !selection.isCollapsed() || !!$linkAt(selection),
+			});
+		});
+	}, [editor]);
+
+	useEffect(() => {
+		sync();
+		return editor.registerUpdateListener(sync);
+	}, [editor, sync]);
+
+	let heading = HEADINGS.has(state.block);
+	let listed = state.block === "bullet";
+
+	return (
+		<div
+			aria-label="Formatting"
+			className="plan-format-dock"
+			contentEditable={false}
+			data-focus-boundary=""
+			// A press must not move focus out of the document, or the keyboard drops.
+			onMouseDown={event => event.preventDefault()}
+			onPointerDown={event => event.preventDefault()}
+			role="toolbar"
+		>
+			<DockButton
+				disabled={disabled}
+				label="Bold"
+				onPress={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold")}
+				pressed={state.bold}
+			>
+				<span className="font-bold">B</span>
+			</DockButton>
+			<DockButton
+				disabled={disabled}
+				label="Italic"
+				onPress={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "italic")}
+				pressed={state.italic}
+			>
+				<span className="italic">I</span>
+			</DockButton>
+			<DockButton
+				disabled={disabled}
+				label="Heading"
+				onPress={() => convertBlock(editor, state.block, heading ? "paragraph" : "h2")}
+				pressed={heading}
+			>
+				<span className="font-semibold">H</span>
+			</DockButton>
+			<DockButton
+				disabled={disabled}
+				label="Bulleted list"
+				onPress={() => convertBlock(editor, state.block, listed ? "paragraph" : "bullet")}
+				pressed={listed}
+			>
+				<span className="text-base font-semibold">UL</span>
+			</DockButton>
+			<DockButton
+				disabled={disabled || !state.linkable}
+				label="Link"
+				onPress={() => editor.dispatchCommand(OPEN_LINK_EDITOR_COMMAND, undefined)}
+			>
+				<LinkIcon size={18} />
+			</DockButton>
+			<DockButton
+				disabled={disabled}
+				label="Insert block"
+				onPress={() => editor.dispatchCommand(OPEN_SLASH_MENU_COMMAND, undefined)}
+			>
+				<PlusIcon size={18} />
+			</DockButton>
+			<DockButton
+				label="Hide keyboard"
+				onPress={() => {
+					let active = document.activeElement;
+					if (active instanceof HTMLElement) active.blur();
+				}}
+			>
+				<KeyboardIcon size={18} />
+			</DockButton>
+		</div>
+	);
+}
+
+function DockButton(
+	{ children, disabled, label, onPress, pressed }: {
+		children: ReactNode;
+		disabled?: boolean;
+		label: string;
+		onPress: () => void;
+		pressed?: boolean;
+	},
+) {
+	return (
+		<button
+			aria-label={label}
+			aria-pressed={pressed}
+			className="plan-format-dock-button"
+			disabled={disabled}
+			onClick={onPress}
+			type="button"
+		>
+			{children}
+		</button>
+	);
+}
diff --git a/packages/editor/src/toolbar/index.tsx b/packages/editor/src/toolbar/index.tsx
index eb913de7c..84461eccc 100644
--- a/packages/editor/src/toolbar/index.tsx
+++ b/packages/editor/src/toolbar/index.tsx
@@ -10,11 +10,14 @@ import { useCellValue } from "@mdxeditor/gurx";
 import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
 import { $getSelection, $isRangeSelection } from "lexical";
 import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
 
+import { selectionOffer } from "../edit-mode";
 import { $describe } from "../passage";
 import { widgets$ } from "../widgets-plugin";
 import { usePhone } from "../phone";
 import { SelectionBubble } from "./bubble";
+import { FormatDock } from "./dock";
 import { LinkSurface } from "./link";
 import { ResearchComposerSurface } from "./research";
 import { ResearchLaunchRegistration } from "./research-launch";
@@ -39,6 +42,14 @@ export function Toolbar() {
 
 	useEffect(() => (disabled ? undefined : registerTaskRule(editor)), [editor, disabled]);
 
+	// A phone reader's lock is not a permission lock: the selection can still comment.
+	let offer = selectionOffer({
+		docked: !!options.formatDock,
+		locked: options.editMode ? !!options.blocked : disabled,
+		mode: options.editMode,
+	});
+	let dock = options.editMode === "editing" ? options.formatDock : undefined;
+
 	let threads = options.threads;
 
 	// Commenting is offered only when there is somewhere for the comment to
@@ -92,9 +103,22 @@ export function Toolbar() {
 	return (
 		<>
 			{phone
-				? <SelectionBar disabled={disabled} hidden={linking} onComment={comment} />
-				: <SelectionBubble disabled={disabled} hidden={linking} onComment={comment} />}
-			<LinkSurface binding={options.binding} disabled={disabled} onEditing={setLinking} />
+				? <SelectionBar disabled={offer === "none"} hidden={linking} onComment={comment} />
+				: (
+					<SelectionBubble
+						commentOnly={offer === "comment"}
+						disabled={offer === "none"}
+						hidden={linking}
+						onComment={comment}
+					/>
+				)}
+			<LinkSurface
+				binding={options.binding}
+				disabled={disabled}
+				follow={options.editMode === "reading"}
+				onEditing={setLinking}
+			/>
+			{dock && createPortal(<FormatDock disabled={disabled} />, dock)}
 			<SlashMenu
 				actions={options.research && options.researchDrafts ? RESEARCH_ACTIONS : undefined}
 				disabled={disabled}
diff --git a/packages/editor/src/toolbar/link.tsx b/packages/editor/src/toolbar/link.tsx
index a140ed55b..c62ea099a 100644
--- a/packages/editor/src/toolbar/link.tsx
+++ b/packages/editor/src/toolbar/link.tsx
@@ -119,9 +119,11 @@ function follow(editor: LexicalEditor, key: NodeKey, url: string): void {
 }
 
 export function LinkSurface(
-	{ binding, disabled, onEditing }: {
+	{ binding, disabled, follow: following, onEditing }: {
 		binding?: Binding;
 		disabled?: boolean;
+		/** A reader's tap follows a link at once, as in any page, rather than previewing it. */
+		follow?: boolean;
 		onEditing?: (editing: boolean) => void;
 	},
 ) {
@@ -251,7 +253,7 @@ export function LinkSurface(
 				let found = node && ($isLinkNode(node) ? node : $findMatchingParent(node, $isLinkNode));
 				return found ? { key: found.getKey(), url: found.getURL() } : undefined;
 			});
-			if (event.button === 1 || event.metaKey || event.ctrlKey || !link) {
+			if (event.button === 1 || event.metaKey || event.ctrlKey || !link || following) {
 				event.stopPropagation();
 				window.open(anchor.href, "_blank", "noopener,noreferrer");
 				return;
@@ -269,7 +271,12 @@ export function LinkSurface(
 			current?.addEventListener("click", click);
 			current?.addEventListener("mouseup", middle);
 		});
-	}, [editor, sync]);
+	}, [editor, following, sync]);
+
+	// A reader never sees the preview, including one left open from editing.
+	useEffect(() => {
+		if (following) setOpen(undefined);
+	}, [following]);
 
 	let close = useCallback(() => {
 		setOpen(current => {
diff --git a/packages/editor/src/toolbar/slash.tsx b/packages/editor/src/toolbar/slash.tsx
index 67531d44b..c78448be1 100644
--- a/packages/editor/src/toolbar/slash.tsx
+++ b/packages/editor/src/toolbar/slash.tsx
@@ -25,6 +25,7 @@ import {
 	$isTextNode,
 	COLLABORATION_TAG,
 	COMMAND_PRIORITY_LOW,
+	createCommand,
 	HISTORIC_TAG,
 	KEY_DOWN_COMMAND,
 } from "lexical";
@@ -75,7 +76,7 @@ import {
 
 import type { ReactElement } from "react";
 import type { IconProps } from "@chopin/icons";
-import type { ElementNode, LexicalEditor, LexicalNode } from "lexical";
+import type { ElementNode, LexicalCommand, LexicalEditor, LexicalNode } from "lexical";
 import type { DOMRectLike, SurfacePlacement } from "./placement";
 import type { OpenResearch } from "./research";
 
@@ -411,6 +412,12 @@ export type SlashMenuProps = {
 
 const NO_ACTIONS = new Set<string>();
 
+/**
+ * Type a `/` at the caret and open the menu for it, for a control that stands in for the key:
+ * a phone's docked toolbar, where a software keyboard may not report the key at all.
+ */
+export const OPEN_SLASH_MENU_COMMAND: LexicalCommand<void> = createCommand("OPEN_SLASH_MENU");
+
 export function SlashMenu({ actions = NO_ACTIONS, disabled }: SlashMenuProps) {
 	let [editor] = useLexicalComposerContext();
 	let [query, setQuery] = useState<string>();
@@ -496,6 +503,27 @@ export function SlashMenu({ actions = NO_ACTIONS, disabled }: SlashMenuProps) {
 		);
 	}, [editor]);
 
+	useEffect(() => {
+		if (disabled) return;
+		return editor.registerCommand(
+			OPEN_SLASH_MENU_COMMAND,
+			() => {
+				armed.current = true;
+				editor.update(() => {
+					let selection = $getSelection();
+					if (!$isRangeSelection(selection)) return;
+					let offset = selection.anchor.offset;
+					let text = selection.anchor.getNode().getTextContent();
+					// The slash has to start a word to count as a trigger.
+					let before = selection.isCollapsed() && offset > 0 ? text[offset - 1] : undefined;
+					selection.insertText(before === undefined || /\s/.test(before) ? "/" : " /");
+				});
+				return true;
+			},
+			COMMAND_PRIORITY_LOW,
+		);
+	}, [editor, disabled]);
+
 	// Track what follows the `/` so the list can filter as the user types.
 	useEffect(() => {
 		// Clears any query left behind by the lock, which would otherwise spring
diff --git a/packages/editor/src/widget-options.ts b/packages/editor/src/widget-options.ts
index 30b5bf6d6..0eecd8385 100644
--- a/packages/editor/src/widget-options.ts
+++ b/packages/editor/src/widget-options.ts
@@ -8,6 +8,7 @@ import type { CardMetaStore } from "./card-meta";
 import type { Binding } from "@lexical/yjs";
 import type { ChangeStore } from "./changes";
 import type { ContentSwapMotion } from "./content-swap";
+import type { EditMode } from "./edit-mode";
 import type { MotionDisclosureContract } from "./disclosure-motion";
 import type { Research } from "@chopin/protocol";
 import type { GitHubReference, GitHubReferenceResult } from "@chopin/protocol/github-reference";
@@ -82,6 +83,12 @@ export type WidgetOptions = {
 	connected?: boolean;
 	synced?: boolean;
 	canEdit?: boolean;
+	/** This client's reading or editing mode on a phone; see `edit-mode.ts`. */
+	editMode?: EditMode;
+	/** Locked for any reason other than reading mode, so a reader's selection can still comment. */
+	blocked?: boolean;
+	/** Where the host docks formatting while editing on a phone, replacing the selection bubble. */
+	formatDock?: HTMLElement | null;
 	/** The viewer's own handle. */
 	self?: string;
 };
diff --git a/packages/editor/src/widgets/render-blocks.tsx b/packages/editor/src/widgets/render-blocks.tsx
index b9ed5a704..e04079e96 100644
--- a/packages/editor/src/widgets/render-blocks.tsx
+++ b/packages/editor/src/widgets/render-blocks.tsx
@@ -53,6 +53,7 @@ import { $isTableCellNode, $isTableRowNode } from "@lexical/table";
 import { $isCodeBlockNode, $isMathNode } from "@chopin/dialect";
 
 import { enclosing, remember } from "../collapse";
+import { widgets$ } from "../widget-options";
 import { describeDiagramError, kindOf, languageOptions, plainText, titleOf } from "./code";
 import { CodeView } from "./code-view";
 import { fitsLegibly } from "./diagram-fit";
@@ -265,11 +266,13 @@ function Toggle({ collapsed, onToggle }: { collapsed: boolean; onToggle: () => v
 
 /** Attaches a preview element beside a block's source, keyed to its content. */
 function Preview(
-	{ block, editor, collapsed, disabled, editing, onToggle, onHidable }: {
+	{ block, editor, collapsed, disabled, editing, onToggle, onHidable, reading }: {
 		block: Block;
 		editor: LexicalEditor;
 		collapsed: boolean;
 		disabled?: boolean;
+		/** A phone reader sees the rendered block; its source is authoring material. */
+		reading?: boolean;
 		/** The caret is in this block's source and the editor has focus. */
 		editing: boolean;
 		onToggle: () => void;
@@ -477,7 +480,7 @@ function Preview(
 							</span>
 						)
 					}
-					{hidable && <Toggle collapsed={collapsed} onToggle={onToggle} />}
+					{hidable && !reading && <Toggle collapsed={collapsed} onToggle={onToggle} />}
 					{title && <span className="plan-code-title">{title}</span>}
 					{named && <Language block={block} editor={editor} disabled={disabled} />}
 				</div>,
@@ -885,6 +888,7 @@ const FOCUSABLE_PREVIEW = `.plan-code-view, .plan-diagram, .plan-seecode, ${WIRE
 export function PreviewPlugin() {
 	let [editor] = useLexicalComposerContext();
 	let disabled = useCellValue(readOnly$);
+	let reading = useCellValue(widgets$).editMode === "reading";
 	let [blocks, setBlocks] = useState<Block[]>([]);
 	/** Blocks whose source this viewer is looking at, and why. */
 	let [shown, setShown] = useState<Record<string, Shown>>({});
@@ -1311,8 +1315,9 @@ export function PreviewPlugin() {
 					key={block.key}
 					block={block}
 					editor={editor}
-					collapsed={!shown[block.key]}
+					collapsed={!shown[block.key] || reading}
 					disabled={disabled}
+					reading={reading}
 					editing={editing === block.key}
 					onToggle={() => toggle(block.key)}
 					onHidable={reportHidable}

From 7aed23146a882d26b1cc11cdbcd053f78baf7d6b Mon Sep 17 00:00:00 2001
From: Maggie Appleton <5599295+MaggieAppleton@users.noreply.github.com>
Date: Sun, 11 Oct 2026 08:41:01 +0100
Subject: [PATCH 02/10] Let phone readers reopen resolved comments and measure
 dock targets by layout

Reopen and discard on a resolved comment are sidecar actions, so reading mode
keeps them; only other locks hide them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 e2e/phone-read-mode.e2e.ts             |  8 ++++++--
 packages/editor/src/resolved-layer.tsx | 10 ++++++----
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/e2e/phone-read-mode.e2e.ts b/e2e/phone-read-mode.e2e.ts
index 7c75f4257..9bebde9d4 100644
--- a/e2e/phone-read-mode.e2e.ts
+++ b/e2e/phone-read-mode.e2e.ts
@@ -135,9 +135,13 @@ test("formatting docks above the keyboard while editing", async ({ baseURL, brow
 		await expect(dock).toBeVisible();
 		await expect(page.getByRole("navigation", { name: "Workspace view" })).toBeHidden();
 		await expect(done(page)).toBeVisible();
+		// Layout size, not the box: the dock rises in with a brief scale.
 		for (let control of await dock.getByRole("button").all()) {
-			let box = await control.boundingBox();
-			if (box) expect(box.height).toBeGreaterThanOrEqual(44);
+			let size = await control.evaluate(element => {
+				let html = element as HTMLElement;
+				return Math.min(html.offsetWidth, html.offsetHeight);
+			});
+			expect(size).toBeGreaterThanOrEqual(44);
 		}
 		let bottom = await dock.evaluate(element => element.getBoundingClientRect().bottom);
 		expect(bottom).toBeLessThanOrEqual(500);
diff --git a/packages/editor/src/resolved-layer.tsx b/packages/editor/src/resolved-layer.tsx
index 49870e56b..01b2974aa 100644
--- a/packages/editor/src/resolved-layer.tsx
+++ b/packages/editor/src/resolved-layer.tsx
@@ -495,6 +495,8 @@ export function ResolvedLayer(
 	itemsRef.current = items;
 
 	useEffect(() => editor.registerEditableListener(setEditable), [editor]);
+	// Reopening and discarding are sidecar actions, not prose edits, so a phone reader keeps them.
+	let actionable = editable || (options.editMode === "reading" && !options.blocked);
 	useEffect(() => {
 		let off = subscribeDecision(() => {
 			let current = currentDecision();
@@ -516,7 +518,7 @@ export function ResolvedLayer(
 	}, []);
 	let actions = useResolvedActions({
 		canEdit: options.canEdit !== false && options.connected === true
-			&& editable,
+			&& actionable,
 		dismiss: closeAfterReply,
 		editor,
 		entries,
@@ -875,7 +877,7 @@ export function ResolvedLayer(
 					if (current.item.kind === "comment") {
 						let { item } = current;
 						let canReopen = !!threads && options.canEdit !== false && options.connected === true
-							&& editable;
+							&& actionable;
 						return (
 							<CommentPopover
 								close={dismiss}
@@ -914,7 +916,7 @@ export function ResolvedLayer(
 									<ResolvedActions
 										className="mt-3 flex flex-wrap items-center justify-end gap-2"
 										disabled={options.canEdit === false || options.connected !== true
-											|| !editable || !options.wire}
+											|| !actionable || !options.wire}
 										key={`${decision.key}:${intent.current}`}
 										onDiscard={() => actions.request("discard", decision)}
 										onReopen={() => actions.request("reopen", decision)}
@@ -944,7 +946,7 @@ export function ResolvedLayer(
 							close={dismiss}
 							error={reopening?.key === sheet.key ? reopening.error : undefined}
 							onReopen={!!threads && options.canEdit !== false && options.connected === true
-									&& editable
+									&& actionable
 								? () => reopen(sheet.key, sheet.comment.thread.id)
 								: undefined}
 							pending={reopening?.key === sheet.key && !reopening.error}

From f392dd26cf1c8808abd2c4b8e5f26606a29133ef Mon Sep 17 00:00:00 2001
From: Maggie Appleton <5599295+MaggieAppleton@users.noreply.github.com>
Date: Sun, 11 Oct 2026 09:13:49 +0100
Subject: [PATCH 03/10] Dock formatting only for the document's own keyboard
 and settle review details

- The dock needs focus in the visible document's editor, so Chat, a comment
  reply or the title rename never get it.
- The pencil opens the document from Chat, which overlays it without changing
  the view.
- Entering edit mode blurs a root that a reader's tap already focused before
  focusing it, so a real focus event fires (iOS keyboard, presence).
- Hide keyboard is pinned outside a scrolling, edge-faded command row; a
  Comment button joins it while text is selected.
- Insert block starts a new paragraph instead of splitting a word, and the
  slash menu keeps above the dock.
- ListIcon in @chopin/icons for the dock and the block menu.
- Title focus returns to the field when a rename fails; an "Editing" cue in
  the phone top bar; inert task boxes look inert while reading; the
  comment-only bubble is labelled "Selection".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/web/src/keyboard-open.ts                 |  27 +++-
 apps/web/src/phone-header.tsx                 |  12 +-
 apps/web/src/room-workspace.tsx               |  20 ++-
 e2e/phone-read-mode.e2e.ts                    | 104 ++++++++++++-
 e2e/toolbar.e2e.ts                            |   3 +-
 packages/editor/src/plan-editor.tsx           |  11 +-
 packages/editor/src/styles.css                |  36 ++++-
 packages/editor/src/toolbar/bubble.tsx        |  13 +-
 packages/editor/src/toolbar/dock-clearance.ts |   8 +
 packages/editor/src/toolbar/dock.tsx          | 137 +++++++++++-------
 packages/editor/src/toolbar/index.tsx         |   2 +-
 packages/editor/src/toolbar/slash.tsx         |  18 ++-
 packages/icons/src/index.ts                   |   1 +
 packages/icons/src/list.tsx                   |  14 ++
 14 files changed, 329 insertions(+), 77 deletions(-)
 create mode 100644 packages/editor/src/toolbar/dock-clearance.ts
 create mode 100644 packages/icons/src/list.tsx

diff --git a/apps/web/src/keyboard-open.ts b/apps/web/src/keyboard-open.ts
index 1d6d4b1d7..c456c2a77 100644
--- a/apps/web/src/keyboard-open.ts
+++ b/apps/web/src/keyboard-open.ts
@@ -1,4 +1,6 @@
-import { useSyncExternalStore } from "react";
+import { useEffect, useState, useSyncExternalStore } from "react";
+
+import type { RefObject } from "react";
 
 /** Follows `:root[data-keyboard-open]`, which the visual-viewport adapter keeps current. */
 export function useKeyboardOpen(): boolean {
@@ -17,3 +19,26 @@ function subscribe(notify: () => void): () => void {
 function current(): boolean {
 	return document.documentElement.hasAttribute("data-keyboard-open");
 }
+
+/** Whether focus is in a document editor inside `scope`: where the docked formatting acts. */
+export function useEditorFocus(scope: RefObject<HTMLElement | null>): boolean {
+	let [focused, setFocused] = useState(false);
+	useEffect(() => {
+		let update = () => {
+			let active = document.activeElement;
+			setFocused(
+				!!active?.closest(".plan-content") && !!scope.current?.contains(active),
+			);
+		};
+		update();
+		// `focusout` fires before the next element takes focus, so settle after both events.
+		let settle = () => queueMicrotask(update);
+		document.addEventListener("focusin", settle);
+		document.addEventListener("focusout", settle);
+		return () => {
+			document.removeEventListener("focusin", settle);
+			document.removeEventListener("focusout", settle);
+		};
+	}, [scope]);
+	return focused;
+}
diff --git a/apps/web/src/phone-header.tsx b/apps/web/src/phone-header.tsx
index b887c16ce..a2a7dc872 100644
--- a/apps/web/src/phone-header.tsx
+++ b/apps/web/src/phone-header.tsx
@@ -24,6 +24,7 @@ export function PhoneHeader(
 		archivedAt,
 		canManage,
 		editing,
+		editingDocument,
 		label,
 		onAction,
 		onEditingChange,
@@ -34,6 +35,8 @@ export function PhoneHeader(
 		archivedAt?: string;
 		canManage: boolean;
 		editing?: TitleEdit;
+		/** The document itself is in edit mode, which the bar says under the title. */
+		editingDocument?: boolean;
 		label: string;
 		onAction: (action: DocumentAction) => void;
 		onEditingChange: (editing?: TitleEdit) => void;
@@ -95,6 +98,11 @@ export function PhoneHeader(
 							channel={{ id: room, title: label }}
 							inline
 							onCancel={finishEdit}
+							// The body took focus as the save started; a refusal needs the field back.
+							onErrorChange={error =>
+								error !== undefined
+								&& header.current?.querySelector<HTMLInputElement>(".document-title-input")
+									?.focus()}
 							onSavingChange={saving => saving && handOff()}
 							replay={editing === "new"}
 							onRenamed={detail => {
@@ -104,7 +112,9 @@ export function PhoneHeader(
 						/>
 					)
 					: <span className="truncate">{label}</span>}
-				{archivedAt && <span className="phone-top-bar-subtitle">Archived</span>}
+				{archivedAt
+					? <span className="phone-top-bar-subtitle">Archived</span>
+					: editingDocument && <span className="phone-top-bar-subtitle">Editing</span>}
 			</div>
 			<div className="phone-top-bar-slot">
 				{canManage && (
diff --git a/apps/web/src/room-workspace.tsx b/apps/web/src/room-workspace.tsx
index 483bf6c1f..443621ac7 100644
--- a/apps/web/src/room-workspace.tsx
+++ b/apps/web/src/room-workspace.tsx
@@ -54,7 +54,7 @@ import { DocumentActionsMenu } from "./document-actions-menu";
 import { DocumentRename } from "./document-rename";
 import { browserStorage, rememberOpened } from "./documents-sheet-model";
 import { PhoneHeader } from "./phone-header";
-import { useKeyboardOpen } from "./keyboard-open";
+import { useEditorFocus, useKeyboardOpen } from "./keyboard-open";
 import { motionContract } from "./motion-contract";
 import { motionImmediately } from "./motion-input";
 import { useNavigationDocument } from "./navigation-shell";
@@ -213,6 +213,11 @@ export function Header(
 								channel={{ id: room, title: label }}
 								inline
 								onCancel={finishEdit}
+								// The body took focus as the save started; a refusal needs the field back.
+								onErrorChange={error =>
+									error !== undefined
+									&& header.current?.querySelector<HTMLInputElement>(".document-title-input")
+										?.focus()}
 								onSavingChange={saving => saving && handOff()}
 								replay={editing === "new"}
 								onRenamed={detail => {
@@ -499,6 +504,7 @@ export function RoomWorkspace(
 		[chatActive],
 	);
 	let planVisible = workspacePresentation.documentVisible && view === "plan";
+	let editorFocused = useEditorFocus(frame);
 	let latestPlanVisible = useRef(planVisible);
 	latestPlanVisible.current = planVisible;
 	let latestBusy = useRef(chatActivity.busy);
@@ -922,11 +928,14 @@ export function RoomWorkspace(
 		arrived.current = true;
 		if (opensEditing({ empty: planState.empty })) setEditing(true);
 	}, [planState.synced, planState.empty]);
+	// Only the document's own keyboard gets formatting: never Chat, a comment reply, or the title.
+	let docked = editMode === "editing" && keyboardOpen && planVisible && editorFocused;
 	let toggleEditing = () => {
 		// Synchronous, so the editor takes focus inside the tap and iOS raises the keyboard.
 		flushSync(() => {
 			setEditing(!editing);
-			if (!editing && view !== "plan") selectDestination("plan");
+			// Chat opens over the document without changing `view`, so ask what is on screen.
+			if (!editing && !planVisible) selectDestination("plan");
 		});
 	};
 	let actOnResearchOffer = (
@@ -1082,7 +1091,7 @@ export function RoomWorkspace(
 				key={workspaceArchivedAt ? "archived" : "active"}
 				disclosureMotion={motionContract("collapse")}
 				editMode={childRoom ? undefined : editMode}
-				formatDock={!childRoom && editMode === "editing" && keyboardOpen ? formatDock : undefined}
+				formatDock={!childRoom && docked ? formatDock : undefined}
 				motionImmediately={settleMotionImmediately}
 				onScrollTop={setPlanScrollTop}
 				onState={setPlanState}
@@ -1200,6 +1209,7 @@ export function RoomWorkspace(
 							archivedAt={workspaceArchivedAt}
 							canManage={effectiveCanManage}
 							editing={titleEdit}
+							editingDocument={editMode === "editing"}
 							label={metadata.title}
 							onAction={action => onDocumentAction(room, action)}
 							onEditingChange={setTitleEdit}
@@ -1250,9 +1260,7 @@ export function RoomWorkspace(
 				)}
 				// Formatting rides above the keyboard while typing. With the keyboard down the tabs
 				// return, and a selection gets the ordinary bubble instead.
-				phoneToolbar={editMode === "editing" && keyboardOpen && (
-					<div className="h-full" ref={setFormatDock} />
-				)}
+				phoneToolbar={docked && <div className="h-full" ref={setFormatDock} />}
 				identity={room}
 				mode={mode}
 				presence={<RoomMembers members={members} ring="page" />}
diff --git a/e2e/phone-read-mode.e2e.ts b/e2e/phone-read-mode.e2e.ts
index 9bebde9d4..22d9986f3 100644
--- a/e2e/phone-read-mode.e2e.ts
+++ b/e2e/phone-read-mode.e2e.ts
@@ -3,6 +3,7 @@
  * editing-only chrome stays out of a reader's way. Desktop and viewers are unchanged.
  */
 
+import { chatInput } from "./chat-input";
 import { createChannel } from "./database";
 import { authenticate, content, edit, expect, openIsolatedRoom, roomPath, test } from "./room";
 import { RESPONSIVE_SOURCE } from "./responsive";
@@ -98,6 +99,7 @@ test("the pencil edits where the reader tapped and Done returns to reading", asy
 	await expect(content(page)).toHaveAttribute("contenteditable", "true");
 	await expect(content(page)).toBeFocused();
 	await expect(done(page)).toBeVisible();
+	await expect(page.locator(".phone-top-bar")).toContainText("Editing");
 	await page.keyboard.type("Typed ");
 	await expect(content(page)).toContainText("Typed ");
 	await expect(writer.getByText(/Typed /)).toBeVisible();
@@ -153,7 +155,28 @@ test("formatting docks above the keyboard while editing", async ({ baseURL, brow
 		// One formatting surface at a time.
 		await expect(page.getByRole("toolbar", { name: "Text formatting" })).toHaveCount(0);
 
-		await dock.getByRole("button", { name: "Hide keyboard" }).tap();
+		// The way out is pinned, never scrolled off the row.
+		let hide = dock.getByRole("button", { name: "Hide keyboard" });
+		let pinned = await hide.evaluate(element => {
+			let box = element.getBoundingClientRect();
+			let row = element.closest("[role=toolbar]")!.getBoundingClientRect();
+			return box.left >= row.left && box.right <= row.right && box.right <= innerWidth;
+		});
+		expect(pinned).toBe(true);
+
+		// A writer can comment while the keyboard is up.
+		await content(page).getByText("Members lose").evaluate(element => {
+			let text = document.createTreeWalker(element, NodeFilter.SHOW_TEXT).nextNode()!;
+			let range = document.createRange();
+			range.setStart(text, 0);
+			range.setEnd(text, 7);
+			getSelection()!.removeAllRanges();
+			getSelection()!.addRange(range);
+		});
+		await expect(dock.getByRole("button", { name: "Comment on this passage" })).toBeVisible();
+		await content(page).getByText("Second paragraph").click();
+
+		await hide.tap();
 		await expect(content(page)).not.toBeFocused();
 		await setVisualViewport(page, { event: "resize", height: 844 });
 		await expect(dock).toHaveCount(0);
@@ -208,3 +231,82 @@ test("an empty document opens ready to write", async ({ join }) => {
 	await expect(done(page)).toBeVisible();
 	await expect(content(page)).toHaveAttribute("contenteditable", "true");
 });
+
+test("the pencil focuses the editor afresh even when a reader's tap already focused it", async ({ join, seed }) => {
+	await seed(SOURCE);
+	let page = await join("ana", PHONE);
+	await page.getByText("Second paragraph").tap();
+	// iOS never moves focus to a tapped button: click without letting focus leave the root.
+	await expect(content(page)).toBeFocused();
+	await content(page).evaluate(root => {
+		(window as typeof window & { focused?: number }).focused = 0;
+		root.addEventListener("focus", () => (window as typeof window & { focused: number }).focused++);
+	});
+	await pencil(page).evaluate(button => (button as HTMLButtonElement).click());
+	await expect(content(page)).toHaveAttribute("contenteditable", "true");
+	expect(await page.evaluate(() => (window as typeof window & { focused?: number }).focused))
+		.toBeGreaterThan(0);
+	await expect(content(page)).toBeFocused();
+});
+
+test("the pencil opens the document from Chat and Decisions", async ({ join, seed }) => {
+	await seed(SOURCE);
+	let page = await join("ana", PHONE);
+	let tabs = page.getByRole("navigation", { name: "Workspace view" });
+	for (let tab of [/^Chat/, /^Decisions/]) {
+		await tabs.getByRole("button", { name: tab }).tap();
+		await pencil(page).tap();
+		await expect(page.locator('[data-document-view="plan"]')).toBeVisible();
+		await expect(content(page)).toBeFocused();
+		await done(page).tap();
+	}
+});
+
+test("only the document's own keyboard gets the formatting dock", async ({ baseURL, browser, room, seed }) => {
+	await seed(SOURCE);
+	let { close, page } = await openIsolatedRoom(browser, baseURL!, room, "ana", PHONE, fakeKeyboard);
+	try {
+		let dock = page.getByRole("toolbar", { name: "Formatting" });
+		await pencil(page).tap();
+		await page.getByRole("navigation", { name: "Workspace view" })
+			.getByRole("button", { name: /^Chat/ }).tap();
+		let composer = chatInput(page.getByRole("complementary", { name: "Chat", exact: true }));
+		await composer.focus();
+		await setVisualViewport(page, { event: "resize", height: 500 });
+		await expect(page.locator("html")).toHaveAttribute("data-keyboard-open", "");
+		await expect(dock).toHaveCount(0);
+
+		await setVisualViewport(page, { event: "resize", height: 844 });
+		await page.getByRole("navigation", { name: "Workspace view" })
+			.getByRole("button", { name: "Document", exact: true }).tap();
+		await page.locator(".phone-top-bar").getByRole("button", { name: /^Actions for / }).tap();
+		await page.getByRole("menuitem", { name: "Rename", exact: true }).tap();
+		await expect(page.getByRole("textbox", { name: "Document title" })).toBeFocused();
+		await setVisualViewport(page, { event: "resize", height: 500 });
+		await expect(dock).toHaveCount(0);
+	} finally {
+		await close();
+	}
+});
+
+test("Insert block starts a new paragraph and keeps its menu above the dock", async ({ baseURL, browser, room, seed }) => {
+	await seed(SOURCE);
+	let { close, page } = await openIsolatedRoom(browser, baseURL!, room, "ana", PHONE, fakeKeyboard);
+	try {
+		await page.getByText("Second paragraph").tap();
+		await pencil(page).tap();
+		await setVisualViewport(page, { event: "resize", height: 500 });
+		let dock = page.getByRole("toolbar", { name: "Formatting" });
+		await dock.getByRole("button", { name: "Insert block" }).tap();
+		await expect(content(page)).toContainText("Second paragraph for the caret.");
+		let menu = page.getByRole("listbox", { name: "Insert block" });
+		await expect(menu).toBeVisible();
+		let [menuBottom, dockTop] = await Promise.all([
+			menu.evaluate(element => element.getBoundingClientRect().bottom),
+			dock.evaluate(element => element.getBoundingClientRect().top),
+		]);
+		expect(menuBottom).toBeLessThanOrEqual(dockTop);
+	} finally {
+		await close();
+	}
+});
diff --git a/e2e/toolbar.e2e.ts b/e2e/toolbar.e2e.ts
index 6a156fcb0..dfcfa4bbc 100644
--- a/e2e/toolbar.e2e.ts
+++ b/e2e/toolbar.e2e.ts
@@ -676,7 +676,8 @@ test("an open selection toolbar follows its range while the editor scrolls", asy
 		let block = content(emulation.page).getByText("Paragraph 9.", { exact: true });
 		await block.scrollIntoViewIfNeeded();
 		await block.selectText();
-		let bubble = emulation.page.getByRole("toolbar", BUBBLE);
+		// A phone reader's selection: the bubble offers commenting only.
+		let bubble = emulation.page.getByRole("toolbar", { name: "Selection" });
 		await expect(bubble).toBeVisible();
 
 		await expectSurfaceToFollowEditorScroll(emulation.page, bubble);
diff --git a/packages/editor/src/plan-editor.tsx b/packages/editor/src/plan-editor.tsx
index d7abacbfa..97af2dbfa 100644
--- a/packages/editor/src/plan-editor.tsx
+++ b/packages/editor/src/plan-editor.tsx
@@ -400,7 +400,16 @@ export function PlanEditor(
 		if (previous !== "reading" || editMode !== "editing" || !editor.isEditable()) return;
 		let point = tapped.current;
 		tapped.current = undefined;
-		editor.getRootElement()?.focus({ preventScroll: true });
+		/*
+		 * A reader's tap focuses the root (Lexical gives a locked root `tabIndex=-1`), and iOS
+		 * Safari never moves focus to a tapped button, so the root can still hold focus here.
+		 * Focusing it again would be a no-op: no `focus` event, so Lexical never announces this
+		 * writer's caret, and iOS raises the keyboard only for focus gained inside the gesture.
+		 * Let go first, then take it back, both while the tap is still being handled.
+		 */
+		let root = editor.getRootElement();
+		if (root && document.activeElement === root) root.blur();
+		root?.focus({ preventScroll: true });
 		editor.update(() => placeCaret(point, editor, scroller.current), { discrete: true });
 	}, [binding, editMode]);
 
diff --git a/packages/editor/src/styles.css b/packages/editor/src/styles.css
index 6043ea3d7..f65cf0bbf 100644
--- a/packages/editor/src/styles.css
+++ b/packages/editor/src/styles.css
@@ -5369,6 +5369,19 @@ body:has(.plan-comment-sheet-popup[data-swiping])
 	animation: plan-check-in var(--duration-fast) var(--ease-out);
 }
 
+/* A phone reader cannot tick a task, so the box drops its pressable look until editing. */
+.plan[data-plan-reading]
+	.plan-content
+	:is([class*="_listItemUnchecked"], [class*="_listItemChecked"]):before {
+	border-style: dashed;
+	box-shadow: none;
+	cursor: default;
+}
+
+.plan[data-plan-reading] .plan-content [class*="_listItemUnchecked"]:hover:before {
+	background-color: var(--color-page);
+}
+
 @keyframes plan-check-in {
 	from {
 		opacity: 0;
@@ -5517,22 +5530,37 @@ body:has(.plan-comment-sheet-popup[data-swiping])
 .plan-format-dock {
 	display: flex;
 	align-items: center;
-	justify-content: space-between;
 	gap: calc(var(--spacing) / 2);
 	min-width: 0;
 	height: 100%;
 	padding-inline: var(--spacing);
+	-webkit-user-select: none;
+	user-select: none;
+}
+
+/* The commands scroll when a narrow phone cannot show them all; Hide keyboard stays pinned. */
+.plan-format-dock-scroll {
+	display: flex;
+	flex: 1;
+	align-items: center;
+	justify-content: space-between;
+	gap: calc(var(--spacing) / 2);
+	min-width: 0;
 	overflow-x: auto;
 	overscroll-behavior-x: contain;
 	scrollbar-width: none;
-	-webkit-user-select: none;
-	user-select: none;
 }
 
-.plan-format-dock::-webkit-scrollbar {
+.plan-format-dock-scroll::-webkit-scrollbar {
 	display: none;
 }
 
+/* More waits past the trailing edge: fade it so the row reads as scrollable. */
+.plan-format-dock-scroll[data-more] {
+	-webkit-mask-image: linear-gradient(to right, #000 calc(100% - var(--spacing) * 8), transparent);
+	mask-image: linear-gradient(to right, #000 calc(100% - var(--spacing) * 8), transparent);
+}
+
 .plan-format-dock-button {
 	display: grid;
 	flex: none;
diff --git a/packages/editor/src/toolbar/bubble.tsx b/packages/editor/src/toolbar/bubble.tsx
index 6e52168e1..9aee672ba 100644
--- a/packages/editor/src/toolbar/bubble.tsx
+++ b/packages/editor/src/toolbar/bubble.tsx
@@ -9,7 +9,7 @@
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import type { ReactNode } from "react";
 import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
-import { ChevronIcon, CodeIcon, LinkPlusIcon, MessagePlusIcon } from "@chopin/icons";
+import { ChevronIcon, CodeIcon, LinkPlusIcon, ListIcon, MessagePlusIcon } from "@chopin/icons";
 
 import { $linkAt, OPEN_LINK_EDITOR_COMMAND } from "./link";
 import { placeSurface, visibleAnchor } from "./placement";
@@ -63,13 +63,13 @@ import type { DOMRectLike, SurfacePlacement } from "./placement";
 export type Block = "paragraph" | "quote" | "bullet" | "number" | "task" | HeadingTagType;
 
 /** `glyph` is what shows; `label` is what it means, for hover and assistive tech. */
-const BLOCKS: Array<{ id: Block; glyph: string; label: string }> = [
+const BLOCKS: Array<{ id: Block; glyph: ReactNode; label: string }> = [
 	{ id: "paragraph", glyph: "T", label: "Text" },
 	{ id: "h1", glyph: "H1", label: "Heading 1" },
 	{ id: "h2", glyph: "H2", label: "Heading 2" },
 	{ id: "h3", glyph: "H3", label: "Heading 3" },
 	{ id: "quote", glyph: ">", label: "Quote" },
-	{ id: "bullet", glyph: "UL", label: "Bulleted list" },
+	{ id: "bullet", glyph: <ListIcon size={14} />, label: "Bulleted list" },
 	{ id: "number", glyph: "OL", label: "Numbered list" },
 ];
 
@@ -90,7 +90,10 @@ const SHORT: Partial<Record<Block, string>> = {
 function describe(block: Block): { short: string; label: string } {
 	if (block === "task") return { short: "Task list", label: "Task list" };
 	let known = BLOCKS.find(item => item.id === block);
-	if (known) return { short: SHORT[block] ?? known.glyph, label: known.label };
+	if (known) {
+		let glyph = typeof known.glyph === "string" ? known.glyph : known.label;
+		return { short: SHORT[block] ?? glyph, label: known.label };
+	}
 	return { short: block.toUpperCase(), label: `Heading ${block.slice(1)}` };
 }
 
@@ -435,7 +438,7 @@ export function SelectionBubble(
 		<div
 			ref={ref}
 			role="toolbar"
-			aria-label="Text formatting"
+			aria-label={commentOnly ? "Selection" : "Text formatting"}
 			data-focus-boundary=""
 			contentEditable={false}
 			// No translate utilities here: placement belongs to the layout effect,
diff --git a/packages/editor/src/toolbar/dock-clearance.ts b/packages/editor/src/toolbar/dock-clearance.ts
new file mode 100644
index 000000000..d0054ef0a
--- /dev/null
+++ b/packages/editor/src/toolbar/dock-clearance.ts
@@ -0,0 +1,8 @@
+import type { ViewportBox } from "./placement";
+
+/** A phone's docked formatting covers the bottom of the document; keep a surface above it. */
+export function aboveDock(viewport: ViewportBox): ViewportBox {
+	let dock = document.querySelector(".plan-format-dock")?.getBoundingClientRect();
+	if (!dock || dock.height === 0 || dock.top >= viewport.top + viewport.height) return viewport;
+	return { ...viewport, height: Math.max(0, dock.top - viewport.top) };
+}
diff --git a/packages/editor/src/toolbar/dock.tsx b/packages/editor/src/toolbar/dock.tsx
index 009acf04d..98dfc3490 100644
--- a/packages/editor/src/toolbar/dock.tsx
+++ b/packages/editor/src/toolbar/dock.tsx
@@ -6,9 +6,9 @@
  * would go with it, and on a phone so would the keyboard.
  */
 
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import { useLexicalComposerContext } from "@lexical/react/LexicalComposerContext";
-import { KeyboardIcon, LinkIcon, PlusIcon } from "@chopin/icons";
+import { KeyboardIcon, LinkIcon, ListIcon, MessagePlusIcon, PlusIcon } from "@chopin/icons";
 import { $getSelection, $isRangeSelection, FORMAT_TEXT_COMMAND } from "lexical";
 
 import { $block, convertBlock } from "./bubble";
@@ -22,18 +22,31 @@ type DockState = {
 	bold: boolean;
 	italic: boolean;
 	block: Block;
+	/** Some text is selected, so it can be linked or commented on. */
+	selected: boolean;
 	/** A link can be added over a selection, or edited with the caret inside one. */
 	linkable: boolean;
 };
 
-const IDLE: DockState = { bold: false, italic: false, block: "paragraph", linkable: false };
+const IDLE: DockState = {
+	bold: false,
+	italic: false,
+	block: "paragraph",
+	selected: false,
+	linkable: false,
+};
 
 /** Blocks the Heading button treats as already being a heading, so it turns them back. */
 const HEADINGS = new Set<Block>(["h1", "h2", "h3", "h4", "h5", "h6"]);
 
-export function FormatDock({ disabled }: { disabled?: boolean }) {
+export function FormatDock(
+	{ disabled, onComment }: { disabled?: boolean; onComment?: () => void },
+) {
 	let [editor] = useLexicalComposerContext();
 	let [state, setState] = useState<DockState>(IDLE);
+	let scroller = useRef<HTMLDivElement>(null);
+	/** Whether more buttons wait past the row's trailing edge, which then fades. */
+	let [more, setMore] = useState(false);
 
 	let sync = useCallback(() => {
 		editor.getEditorState().read(() => {
@@ -43,6 +56,7 @@ export function FormatDock({ disabled }: { disabled?: boolean }) {
 				bold: selection.hasFormat("bold"),
 				italic: selection.hasFormat("italic"),
 				block: $block(selection.anchor.getNode()),
+				selected: !selection.isCollapsed(),
 				linkable: !selection.isCollapsed() || !!$linkAt(selection),
 			});
 		});
@@ -53,6 +67,21 @@ export function FormatDock({ disabled }: { disabled?: boolean }) {
 		return editor.registerUpdateListener(sync);
 	}, [editor, sync]);
 
+	let commentable = !!onComment && state.selected;
+	useLayoutEffect(() => {
+		let element = scroller.current;
+		if (!element) return;
+		let measure = () => setMore(element.scrollLeft + element.clientWidth < element.scrollWidth - 1);
+		measure();
+		let observer = new ResizeObserver(measure);
+		observer.observe(element);
+		element.addEventListener("scroll", measure, { passive: true });
+		return () => {
+			observer.disconnect();
+			element.removeEventListener("scroll", measure);
+		};
+	}, [commentable]);
+
 	let heading = HEADINGS.has(state.block);
 	let listed = state.block === "bullet";
 
@@ -67,52 +96,60 @@ export function FormatDock({ disabled }: { disabled?: boolean }) {
 			onPointerDown={event => event.preventDefault()}
 			role="toolbar"
 		>
-			<DockButton
-				disabled={disabled}
-				label="Bold"
-				onPress={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold")}
-				pressed={state.bold}
-			>
-				<span className="font-bold">B</span>
-			</DockButton>
-			<DockButton
-				disabled={disabled}
-				label="Italic"
-				onPress={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "italic")}
-				pressed={state.italic}
-			>
-				<span className="italic">I</span>
-			</DockButton>
-			<DockButton
-				disabled={disabled}
-				label="Heading"
-				onPress={() => convertBlock(editor, state.block, heading ? "paragraph" : "h2")}
-				pressed={heading}
-			>
-				<span className="font-semibold">H</span>
-			</DockButton>
-			<DockButton
-				disabled={disabled}
-				label="Bulleted list"
-				onPress={() => convertBlock(editor, state.block, listed ? "paragraph" : "bullet")}
-				pressed={listed}
-			>
-				<span className="text-base font-semibold">UL</span>
-			</DockButton>
-			<DockButton
-				disabled={disabled || !state.linkable}
-				label="Link"
-				onPress={() => editor.dispatchCommand(OPEN_LINK_EDITOR_COMMAND, undefined)}
-			>
-				<LinkIcon size={18} />
-			</DockButton>
-			<DockButton
-				disabled={disabled}
-				label="Insert block"
-				onPress={() => editor.dispatchCommand(OPEN_SLASH_MENU_COMMAND, undefined)}
-			>
-				<PlusIcon size={18} />
-			</DockButton>
+			<div className="plan-format-dock-scroll" data-more={more || undefined} ref={scroller}>
+				<DockButton
+					disabled={disabled}
+					label="Bold"
+					onPress={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "bold")}
+					pressed={state.bold}
+				>
+					<span className="font-bold">B</span>
+				</DockButton>
+				<DockButton
+					disabled={disabled}
+					label="Italic"
+					onPress={() => editor.dispatchCommand(FORMAT_TEXT_COMMAND, "italic")}
+					pressed={state.italic}
+				>
+					<span className="italic">I</span>
+				</DockButton>
+				<DockButton
+					disabled={disabled}
+					label="Heading"
+					onPress={() => convertBlock(editor, state.block, heading ? "paragraph" : "h2")}
+					pressed={heading}
+				>
+					<span className="font-semibold">H</span>
+				</DockButton>
+				<DockButton
+					disabled={disabled}
+					label="Bulleted list"
+					onPress={() => convertBlock(editor, state.block, listed ? "paragraph" : "bullet")}
+					pressed={listed}
+				>
+					<ListIcon size={18} />
+				</DockButton>
+				<DockButton
+					disabled={disabled || !state.linkable}
+					label="Link"
+					onPress={() => editor.dispatchCommand(OPEN_LINK_EDITOR_COMMAND, undefined)}
+				>
+					<LinkIcon size={18} />
+				</DockButton>
+				{commentable && (
+					<DockButton label="Comment on this passage" onPress={() => onComment?.()}>
+						<MessagePlusIcon size={18} />
+					</DockButton>
+				)}
+				<DockButton
+					disabled={disabled}
+					label="Insert block"
+					onPress={() => editor.dispatchCommand(OPEN_SLASH_MENU_COMMAND, undefined)}
+				>
+					<PlusIcon size={18} />
+				</DockButton>
+			</div>
+			{/* Pinned outside the scrolling row, so the way out is never cut off. */}
 			<DockButton
 				label="Hide keyboard"
 				onPress={() => {
diff --git a/packages/editor/src/toolbar/index.tsx b/packages/editor/src/toolbar/index.tsx
index 84461eccc..3dbd34604 100644
--- a/packages/editor/src/toolbar/index.tsx
+++ b/packages/editor/src/toolbar/index.tsx
@@ -118,7 +118,7 @@ export function Toolbar() {
 				follow={options.editMode === "reading"}
 				onEditing={setLinking}
 			/>
-			{dock && createPortal(<FormatDock disabled={disabled} />, dock)}
+			{dock && createPortal(<FormatDock disabled={disabled} onComment={comment} />, dock)}
 			<SlashMenu
 				actions={options.research && options.researchDrafts ? RESEARCH_ACTIONS : undefined}
 				disabled={disabled}
diff --git a/packages/editor/src/toolbar/slash.tsx b/packages/editor/src/toolbar/slash.tsx
index c78448be1..3880dbbbe 100644
--- a/packages/editor/src/toolbar/slash.tsx
+++ b/packages/editor/src/toolbar/slash.tsx
@@ -74,6 +74,7 @@ import {
 	SHELL,
 } from "./surface";
 
+import { aboveDock } from "./dock-clearance";
 import type { ReactElement } from "react";
 import type { IconProps } from "@chopin/icons";
 import type { ElementNode, LexicalCommand, LexicalEditor, LexicalNode } from "lexical";
@@ -512,11 +513,16 @@ export function SlashMenu({ actions = NO_ACTIONS, disabled }: SlashMenuProps) {
 				editor.update(() => {
 					let selection = $getSelection();
 					if (!$isRangeSelection(selection)) return;
-					let offset = selection.anchor.offset;
-					let text = selection.anchor.getNode().getTextContent();
-					// The slash has to start a word to count as a trigger.
-					let before = selection.isCollapsed() && offset > 0 ? text[offset - 1] : undefined;
-					selection.insertText(before === undefined || /\s/.test(before) ? "/" : " /");
+					// A block with words in it gets a new paragraph after it, rather than a slash
+					// splitting a word or trailing a sentence.
+					let block = selection.anchor.getNode().getTopLevelElement();
+					if (block && block.getTextContentSize() > 0) {
+						let paragraph = $createParagraphNode();
+						block.insertAfter(paragraph);
+						paragraph.select();
+					}
+					let next = $getSelection();
+					if ($isRangeSelection(next)) next.insertText("/");
 				});
 				return true;
 			},
@@ -571,7 +577,7 @@ export function SlashMenu({ actions = NO_ACTIONS, disabled }: SlashMenuProps) {
 			setPosition(undefined);
 			return;
 		}
-		let viewport = editorSurfaceViewport(editor);
+		let viewport = aboveDock(editorSurfaceViewport(editor));
 		element.style.maxWidth = `${Math.max(0, viewport.width - 16)}px`;
 		let next = placeSurface(
 			liveAnchor,
diff --git a/packages/icons/src/index.ts b/packages/icons/src/index.ts
index f4019aebc..f7c61becc 100644
--- a/packages/icons/src/index.ts
+++ b/packages/icons/src/index.ts
@@ -59,5 +59,6 @@ export {
 	TabsIcon,
 	WrenchIcon,
 } from "./line";
+export { ListIcon } from "./list";
 export { ArchiveIcon, DocumentIcon, LoaderIcon, SearchIcon } from "./system";
 export { WarningIcon } from "./warning";
diff --git a/packages/icons/src/list.tsx b/packages/icons/src/list.tsx
new file mode 100644
index 000000000..00ba83ad6
--- /dev/null
+++ b/packages/icons/src/list.tsx
@@ -0,0 +1,14 @@
+import { LineIcon } from "./icon";
+
+import type { IconProps } from "./icon";
+
+export function ListIcon(props: IconProps) {
+	return (
+		<LineIcon {...props}>
+			<path d="M6.75 4.75h8.5M6.75 9h8.5M6.75 13.25h8.5" />
+			<circle cx="3.25" cy="4.75" r=".75" fill="currentColor" stroke="none" />
+			<circle cx="3.25" cy="9" r=".75" fill="currentColor" stroke="none" />
+			<circle cx="3.25" cy="13.25" r=".75" fill="currentColor" stroke="none" />
+		</LineIcon>
+	);
+}

From 2d449d97d2d23a9165129470293fdcf2e566caf2 Mon Sep 17 00:00:00 2001
From: Maggie Appleton <5599295+MaggieAppleton@users.noreply.github.com>
Date: Sun, 11 Oct 2026 09:29:22 +0100
Subject: [PATCH 04/10] Collapse the dock test's selection by key, not by text
 that typing has split

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 e2e/phone-read-mode.e2e.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/e2e/phone-read-mode.e2e.ts b/e2e/phone-read-mode.e2e.ts
index 22d9986f3..6315a12ea 100644
--- a/e2e/phone-read-mode.e2e.ts
+++ b/e2e/phone-read-mode.e2e.ts
@@ -174,7 +174,9 @@ test("formatting docks above the keyboard while editing", async ({ baseURL, brow
 			getSelection()!.addRange(range);
 		});
 		await expect(dock.getByRole("button", { name: "Comment on this passage" })).toBeVisible();
-		await content(page).getByText("Second paragraph").click();
+		// Collapse the selection; the typing above may have split the second paragraph's words.
+		await page.keyboard.press("ArrowRight");
+		await expect(dock.getByRole("button", { name: "Comment on this passage" })).toHaveCount(0);
 
 		await hide.tap();
 		await expect(content(page)).not.toBeFocused();

From f4c34e5ec1826ee25f48abe411800480e74dc6fb Mon Sep 17 00:00:00 2001
From: Maggie Appleton <5599295+MaggieAppleton@users.noreply.github.com>
Date: Sun, 11 Oct 2026 09:53:05 +0100
Subject: [PATCH 05/10] Keep the Editing cue visible at the top and fade both
 dock edges

The top bar's small title waits for the heading to scroll away, which hid the
Editing subtitle with it; a standalone Editing pill now stands in while the
title is hidden. The dock's command row fades whichever edge has buttons
scrolled past it. Insert block keeps placing its paragraph after the whole
list or table, and says why.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/web/src/phone-header.tsx         | 54 +++++++++++++++------------
 apps/web/src/phone-workspace.css      | 29 +++++++++++++-
 e2e/phone-read-mode.e2e.ts            |  4 +-
 packages/editor/src/styles.css        | 31 +++++++++++++--
 packages/editor/src/toolbar/dock.tsx  | 19 ++++++++--
 packages/editor/src/toolbar/slash.tsx |  4 +-
 6 files changed, 106 insertions(+), 35 deletions(-)

diff --git a/apps/web/src/phone-header.tsx b/apps/web/src/phone-header.tsx
index a2a7dc872..71c8281c9 100644
--- a/apps/web/src/phone-header.tsx
+++ b/apps/web/src/phone-header.tsx
@@ -91,30 +91,36 @@ export function PhoneHeader(
 					</button>
 				)}
 			</div>
-			<div className="phone-top-bar-title">
-				{editing && canManage && !archivedAt
-					? (
-						<DocumentRename
-							channel={{ id: room, title: label }}
-							inline
-							onCancel={finishEdit}
-							// The body took focus as the save started; a refusal needs the field back.
-							onErrorChange={error =>
-								error !== undefined
-								&& header.current?.querySelector<HTMLInputElement>(".document-title-input")
-									?.focus()}
-							onSavingChange={saving => saving && handOff()}
-							replay={editing === "new"}
-							onRenamed={detail => {
-								onRenamed(detail.channel);
-								finishEdit();
-							}}
-						/>
-					)
-					: <span className="truncate">{label}</span>}
-				{archivedAt
-					? <span className="phone-top-bar-subtitle">Archived</span>
-					: editingDocument && <span className="phone-top-bar-subtitle">Editing</span>}
+			<div className="phone-top-bar-center">
+				<div className="phone-top-bar-title">
+					{editing && canManage && !archivedAt
+						? (
+							<DocumentRename
+								channel={{ id: room, title: label }}
+								inline
+								onCancel={finishEdit}
+								// The body took focus as the save started; a refusal needs the field back.
+								onErrorChange={error =>
+									error !== undefined
+									&& header.current?.querySelector<HTMLInputElement>(".document-title-input")
+										?.focus()}
+								onSavingChange={saving => saving && handOff()}
+								replay={editing === "new"}
+								onRenamed={detail => {
+									onRenamed(detail.channel);
+									finishEdit();
+								}}
+							/>
+						)
+						: <span className="truncate">{label}</span>}
+					{archivedAt
+						? <span className="phone-top-bar-subtitle">Archived</span>
+						: editingDocument && <span className="phone-top-bar-subtitle">Editing</span>}
+				</div>
+				{/* The title waits for the heading to scroll away; the mode must show regardless. */}
+				{editingDocument && !archivedAt && (
+					<span aria-hidden="true" className="phone-top-bar-mode">Editing</span>
+				)}
 			</div>
 			<div className="phone-top-bar-slot">
 				{canManage && (
diff --git a/apps/web/src/phone-workspace.css b/apps/web/src/phone-workspace.css
index dfb73031c..606e24ce8 100644
--- a/apps/web/src/phone-workspace.css
+++ b/apps/web/src/phone-workspace.css
@@ -147,7 +147,18 @@
 }
 
 /* The small title waits until the document's own title has scrolled away. */
-.phone-top-bar-title {
+.phone-top-bar-center {
+	display: grid;
+	min-width: 0;
+	place-items: center;
+}
+
+.phone-top-bar-center > * {
+	grid-area: 1 / 1;
+}
+
+.phone-top-bar-title,
+.phone-top-bar-mode {
 	transition: opacity var(--duration-base) var(--ease-out);
 }
 
@@ -155,6 +166,22 @@
 	opacity: 0;
 }
 
+/* Stands in for the hidden title while editing, so the mode is always on screen. */
+.phone-top-bar-mode {
+	padding: calc(var(--spacing) / 2) calc(var(--spacing) * 2);
+	border-radius: var(--radius-full);
+	background: var(--color-brand-wash);
+	color: var(--color-brand-ink);
+	font-size: var(--text-2xs);
+	font-weight: var(--font-weight-medium);
+	opacity: 0;
+	pointer-events: none;
+}
+
+.workspace-root[data-workspace-title="hidden"] .phone-top-bar-mode {
+	opacity: 1;
+}
+
 .phone-top-bar-slot {
 	display: flex;
 	align-items: center;
diff --git a/e2e/phone-read-mode.e2e.ts b/e2e/phone-read-mode.e2e.ts
index 6315a12ea..f39965a19 100644
--- a/e2e/phone-read-mode.e2e.ts
+++ b/e2e/phone-read-mode.e2e.ts
@@ -99,7 +99,9 @@ test("the pencil edits where the reader tapped and Done returns to reading", asy
 	await expect(content(page)).toHaveAttribute("contenteditable", "true");
 	await expect(content(page)).toBeFocused();
 	await expect(done(page)).toBeVisible();
-	await expect(page.locator(".phone-top-bar")).toContainText("Editing");
+	// At the top of the document the small title waits, but the mode still shows.
+	await expect(page.locator(".phone-top-bar-mode")).toHaveText("Editing");
+	await expect(page.locator(".phone-top-bar-mode")).toHaveCSS("opacity", "1");
 	await page.keyboard.type("Typed ");
 	await expect(content(page)).toContainText("Typed ");
 	await expect(writer.getByText(/Typed /)).toBeVisible();
diff --git a/packages/editor/src/styles.css b/packages/editor/src/styles.css
index f65cf0bbf..b3b8c700b 100644
--- a/packages/editor/src/styles.css
+++ b/packages/editor/src/styles.css
@@ -5555,10 +5555,33 @@ body:has(.plan-comment-sheet-popup[data-swiping])
 	display: none;
 }
 
-/* More waits past the trailing edge: fade it so the row reads as scrollable. */
-.plan-format-dock-scroll[data-more] {
-	-webkit-mask-image: linear-gradient(to right, #000 calc(100% - var(--spacing) * 8), transparent);
-	mask-image: linear-gradient(to right, #000 calc(100% - var(--spacing) * 8), transparent);
+/* Buttons scrolled past an edge: fade that edge so the row reads as scrollable. */
+.plan-format-dock-scroll {
+	--dock-fade: calc(var(--spacing) * 8);
+	--dock-fade-start: #000;
+	--dock-fade-end: #000;
+	-webkit-mask-image: linear-gradient(
+		to right,
+		var(--dock-fade-start),
+		#000 var(--dock-fade),
+		#000 calc(100% - var(--dock-fade)),
+		var(--dock-fade-end)
+	);
+	mask-image: linear-gradient(
+		to right,
+		var(--dock-fade-start),
+		#000 var(--dock-fade),
+		#000 calc(100% - var(--dock-fade)),
+		var(--dock-fade-end)
+	);
+}
+
+.plan-format-dock-scroll[data-more-start] {
+	--dock-fade-start: transparent;
+}
+
+.plan-format-dock-scroll[data-more-end] {
+	--dock-fade-end: transparent;
 }
 
 .plan-format-dock-button {
diff --git a/packages/editor/src/toolbar/dock.tsx b/packages/editor/src/toolbar/dock.tsx
index 98dfc3490..ff3077f0a 100644
--- a/packages/editor/src/toolbar/dock.tsx
+++ b/packages/editor/src/toolbar/dock.tsx
@@ -45,8 +45,8 @@ export function FormatDock(
 	let [editor] = useLexicalComposerContext();
 	let [state, setState] = useState<DockState>(IDLE);
 	let scroller = useRef<HTMLDivElement>(null);
-	/** Whether more buttons wait past the row's trailing edge, which then fades. */
-	let [more, setMore] = useState(false);
+	/** Which edges of the row have buttons scrolled past them; those edges fade. */
+	let [edges, setEdges] = useState({ start: false, end: false });
 
 	let sync = useCallback(() => {
 		editor.getEditorState().read(() => {
@@ -71,7 +71,13 @@ export function FormatDock(
 	useLayoutEffect(() => {
 		let element = scroller.current;
 		if (!element) return;
-		let measure = () => setMore(element.scrollLeft + element.clientWidth < element.scrollWidth - 1);
+		let measure = () => {
+			let start = element.scrollLeft > 1;
+			let end = element.scrollLeft + element.clientWidth < element.scrollWidth - 1;
+			setEdges(current =>
+				current.start === start && current.end === end ? current : { start, end }
+			);
+		};
 		measure();
 		let observer = new ResizeObserver(measure);
 		observer.observe(element);
@@ -96,7 +102,12 @@ export function FormatDock(
 			onPointerDown={event => event.preventDefault()}
 			role="toolbar"
 		>
-			<div className="plan-format-dock-scroll" data-more={more || undefined} ref={scroller}>
+			<div
+				className="plan-format-dock-scroll"
+				data-more-end={edges.end || undefined}
+				data-more-start={edges.start || undefined}
+				ref={scroller}
+			>
 				<DockButton
 					disabled={disabled}
 					label="Bold"
diff --git a/packages/editor/src/toolbar/slash.tsx b/packages/editor/src/toolbar/slash.tsx
index 3880dbbbe..f07330dcd 100644
--- a/packages/editor/src/toolbar/slash.tsx
+++ b/packages/editor/src/toolbar/slash.tsx
@@ -514,7 +514,9 @@ export function SlashMenu({ actions = NO_ACTIONS, disabled }: SlashMenuProps) {
 					let selection = $getSelection();
 					if (!$isRangeSelection(selection)) return;
 					// A block with words in it gets a new paragraph after it, rather than a slash
-					// splitting a word or trailing a sentence.
+					// splitting a word or trailing a sentence. Deliberately the top-level block: a
+					// table cell holds only inline text in the dialect, and the inserted components
+					// cannot live inside a list item, so those go after the whole table or list.
 					let block = selection.anchor.getNode().getTopLevelElement();
 					if (block && block.getTextContentSize() > 0) {
 						let paragraph = $createParagraphNode();

From c2e344ecd3009fb9836b781681929e5a9c76ff9e Mon Sep 17 00:00:00 2001
From: Maggie Appleton <5599295+MaggieAppleton@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:15:42 +0100
Subject: [PATCH 06/10] Check that a phone reader's selection gets the docked
 Comment bar

The selection bar from #474 now takes its gate from selectionOffer(), so a
reader's lock no longer hides it; the reading spec asserts the bar itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 e2e/phone-read-mode.e2e.ts           |  5 ++++-
 packages/editor/src/phone.ts         | 26 --------------------------
 packages/editor/src/widgets/phone.ts | 21 ---------------------
 3 files changed, 4 insertions(+), 48 deletions(-)
 delete mode 100644 packages/editor/src/phone.ts
 delete mode 100644 packages/editor/src/widgets/phone.ts

diff --git a/e2e/phone-read-mode.e2e.ts b/e2e/phone-read-mode.e2e.ts
index f39965a19..d258baa77 100644
--- a/e2e/phone-read-mode.e2e.ts
+++ b/e2e/phone-read-mode.e2e.ts
@@ -62,7 +62,10 @@ test("a phone opens a document for reading", async ({ join, seed }) => {
 		getSelection()!.removeAllRanges();
 		getSelection()!.addRange(range);
 	});
-	await expect(page.getByRole("button", { name: "Comment on this passage" })).toBeVisible();
+	// The phone's docked selection bar, not the editing bubble.
+	let bar = page.getByRole("toolbar", { name: "Selection actions" });
+	await expect(bar.getByRole("button", { name: "Comment on this passage" })).toBeVisible();
+	await expect(page.getByRole("toolbar", { name: "Text formatting" })).toHaveCount(0);
 	await expect(page.getByRole("button", { name: "Bold" })).toHaveCount(0);
 });
 
diff --git a/packages/editor/src/phone.ts b/packages/editor/src/phone.ts
deleted file mode 100644
index da14bcedb..000000000
--- a/packages/editor/src/phone.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { useEffect, useState } from "react";
-
-/*
- * What counts as a phone for the editor's touch surfaces: a primary coarse
- * pointer on a narrow screen. The comment sheet, the selection action bar and
- * the margin markers all ask this one question, so a shared phone class can
- * replace it here.
- */
-export const PHONE_MAX_WIDTH = 430;
-export const PHONE_QUERY = `(pointer: coarse) and (max-width: ${PHONE_MAX_WIDTH}px)`;
-
-export function isPhone({ coarse, width }: { coarse: boolean; width: number }): boolean {
-	return coarse && width <= PHONE_MAX_WIDTH;
-}
-
-export function usePhone(): boolean {
-	let [phone, setPhone] = useState(() => matchMedia(PHONE_QUERY).matches);
-	useEffect(() => {
-		let query = matchMedia(PHONE_QUERY);
-		let update = () => setPhone(query.matches);
-		update();
-		query.addEventListener("change", update);
-		return () => query.removeEventListener("change", update);
-	}, []);
-	return phone;
-}
diff --git a/packages/editor/src/widgets/phone.ts b/packages/editor/src/widgets/phone.ts
deleted file mode 100644
index 389a94d46..000000000
--- a/packages/editor/src/widgets/phone.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-import { useSyncExternalStore } from "react";
-
-/**
- * The phone class: a coarse pointer on a small screen, in either orientation.
- *
- * Kept identical to the media query that gates wide-content styles in
- * styles.css. When the shell publishes `usePhone()` and `:root[data-phone]`
- * from `../pointer`, both switch to those and this file goes.
- */
-export const PHONE_QUERY =
-	"(pointer: coarse) and (max-width: 600px), (pointer: coarse) and (max-height: 500px)";
-
-function subscribe(change: () => void): () => void {
-	let query = matchMedia(PHONE_QUERY);
-	query.addEventListener("change", change);
-	return () => query.removeEventListener("change", change);
-}
-
-export function usePhone(): boolean {
-	return useSyncExternalStore(subscribe, () => matchMedia(PHONE_QUERY).matches, () => false);
-}

From 80ea524b923a5bcab036219946d8a6c743dc367f Mon Sep 17 00:00:00 2001
From: Maggie Appleton <5599295+MaggieAppleton@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:15:43 +0100
Subject: [PATCH 07/10] Use the shared phone class for comments, selection,
 decisions and wide content

The interim phone checks from the mobile slices (coarse and at most 430px
for the comment sheet and selection bar, and a copy of the phone media
query for wide content and decisions) now all use usePhone() from
@chopin/editor/pointer, the class the shell mirrors as :root[data-phone].
The comment sheet and docked selection bar therefore apply to every phone,
landscape and phones up to 600px wide included. The toolbar spec that
needed a non-phone touch screen moves from 600px to 601px.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 e2e/toolbar.e2e.ts                            |  5 ++---
 packages/editor/src/comment-layer.tsx         |  9 +++++----
 packages/editor/src/comment-sheet.test.ts     |  9 ---------
 packages/editor/src/comment-sheet.tsx         |  7 -------
 packages/editor/src/decisions.tsx             |  2 +-
 packages/editor/src/resolved-layer.tsx        | 16 ++++------------
 packages/editor/src/styles.css                |  5 ++---
 packages/editor/src/toolbar/index.tsx         |  2 +-
 packages/editor/src/widgets/questionnaire.tsx |  2 +-
 packages/editor/src/widgets/render-blocks.tsx |  2 +-
 10 files changed, 17 insertions(+), 42 deletions(-)

diff --git a/e2e/toolbar.e2e.ts b/e2e/toolbar.e2e.ts
index dfcfa4bbc..db571f1a2 100644
--- a/e2e/toolbar.e2e.ts
+++ b/e2e/toolbar.e2e.ts
@@ -671,13 +671,12 @@ test("an open slash menu follows its caret while the editor scrolls", async ({ b
 test("an open selection toolbar follows its range while the editor scrolls", async ({ baseURL, browser, room, seed }) => {
 	await seed(LONG_EDITOR);
 	// Wider than a phone, where a touch selection still gets the floating bubble.
-	let emulation = await emulatedVisualViewportPage(browser, baseURL!, room, 600);
+	let emulation = await emulatedVisualViewportPage(browser, baseURL!, room, 601);
 	try {
 		let block = content(emulation.page).getByText("Paragraph 9.", { exact: true });
 		await block.scrollIntoViewIfNeeded();
 		await block.selectText();
-		// A phone reader's selection: the bubble offers commenting only.
-		let bubble = emulation.page.getByRole("toolbar", { name: "Selection" });
+		let bubble = emulation.page.getByRole("toolbar", BUBBLE);
 		await expect(bubble).toBeVisible();
 
 		await expectSurfaceToFollowEditorScroll(emulation.page, bubble);
diff --git a/packages/editor/src/comment-layer.tsx b/packages/editor/src/comment-layer.tsx
index 7e315f16d..9a9c7f386 100644
--- a/packages/editor/src/comment-layer.tsx
+++ b/packages/editor/src/comment-layer.tsx
@@ -17,11 +17,11 @@ import {
 	popoverPoint,
 } from "./comment-geometry";
 import { containsHit, passageHits } from "./comment-hits";
-import { CommentSheet, commentSheetHeading, usesCommentSheet } from "./comment-sheet";
+import { CommentSheet, commentSheetHeading } from "./comment-sheet";
 import { useCommentSheetReveal } from "./comment-sheet-reveal";
 import { $rangeOf } from "./marks";
 import { blockElement } from "./scroll";
-import { COARSE_POINTER_QUERY, PRIMARY_COARSE_POINTER_QUERY } from "./pointer";
+import { COARSE_POINTER_QUERY, PRIMARY_COARSE_POINTER_QUERY, usePhone } from "./pointer";
 import { OPEN_COMMENT, useThreads } from "./threads";
 import { useTransitionPresence } from "./transition-presence";
 import { widgets$ } from "./widget-options";
@@ -400,8 +400,9 @@ export function CommentLayer({ store }: { store: ThreadStore }) {
 	let focusOnOpen = useRef<string | undefined>(undefined);
 	let options = useCellValue(widgets$);
 	let canEdit = options.canEdit !== false;
-	let compact = options.commentPresentation === "sheet"
-		&& usesCommentSheet({ coarse: primaryCoarse, width: host?.clientWidth ?? Infinity });
+	let phone = usePhone();
+	// The comment sheet belongs to the phone class, portrait or landscape.
+	let compact = options.commentPresentation === "sheet" && phone;
 	let previousCompact = useRef(compact);
 	let immediately = options.motionImmediately?.() ?? false;
 	let draft = canEdit ? state.draft : undefined;
diff --git a/packages/editor/src/comment-sheet.test.ts b/packages/editor/src/comment-sheet.test.ts
index 00609b69b..8e6c95ef7 100644
--- a/packages/editor/src/comment-sheet.test.ts
+++ b/packages/editor/src/comment-sheet.test.ts
@@ -7,7 +7,6 @@ import {
 	commentSheetHeight,
 	commentSheetMedium,
 	commentSheetTop,
-	usesCommentSheet,
 } from "./comment-sheet";
 
 describe("comment sheet size", () => {
@@ -48,14 +47,6 @@ describe("comment sheet size", () => {
 		expect(commentSheetMedium(844, 250)).toBe(422);
 		expect(commentSheetMedium(361, 900)).toBeCloseTo(332);
 	});
-
-	it("reserves the drawer for phone-sized coarse pointers", () => {
-		expect(usesCommentSheet({ coarse: true, width: 390 })).toBe(true);
-		expect(usesCommentSheet({ coarse: true, width: 430 })).toBe(true);
-		expect(usesCommentSheet({ coarse: true, width: 431 })).toBe(false);
-		expect(usesCommentSheet({ coarse: true, width: 768 })).toBe(false);
-		expect(usesCommentSheet({ coarse: false, width: 390 })).toBe(false);
-	});
 });
 
 describe("comment sheet heading", () => {
diff --git a/packages/editor/src/comment-sheet.tsx b/packages/editor/src/comment-sheet.tsx
index 4bc3e25d6..e0a9826c5 100644
--- a/packages/editor/src/comment-sheet.tsx
+++ b/packages/editor/src/comment-sheet.tsx
@@ -3,19 +3,12 @@ import { Drawer } from "@base-ui/react/drawer";
 import { ChevronIcon, CloseIcon } from "@chopin/icons";
 import { currentViewport, listenToViewportChanges } from "@chopin/viewport";
 
-import { isPhone, PHONE_MAX_WIDTH } from "./phone";
-
 import type { ReactNode } from "react";
 
 /** The tallest the sheet grows, as a fraction of the space above the keyboard. */
 export const COMMENT_SHEET_LARGE = 0.92;
 /** Where the sheet opens, as a fraction of the space above the keyboard, so its passage shows above it. */
 export const COMMENT_SHEET_MEDIUM = 0.5;
-export const COMMENT_SHEET_MAX_WIDTH = PHONE_MAX_WIDTH;
-
-export function usesCommentSheet(device: { coarse: boolean; width: number }): boolean {
-	return isPhone(device);
-}
 
 /** How much of a sheet's scrolling notes the medium detent keeps in view beneath its header. */
 export const COMMENT_SHEET_PEEK = 64;
diff --git a/packages/editor/src/decisions.tsx b/packages/editor/src/decisions.tsx
index 55d80fdaf..cf2db2ab5 100644
--- a/packages/editor/src/decisions.tsx
+++ b/packages/editor/src/decisions.tsx
@@ -12,7 +12,7 @@ import { CheckIcon, ChevronIcon, DecisionIcon } from "@chopin/icons";
 import { EmptyState } from "@chopin/visuals";
 
 import { MotionDisclosure, MotionDisclosureIcon } from "./disclosure-motion";
-import { usePhone } from "./widgets/phone";
+import { usePhone } from "./pointer";
 import { useQuestionnaires } from "./questionnaires";
 import { PendingAnswersContext, PendingAnswersStore, SaveBar } from "./save-bar";
 import { forget } from "./touched";
diff --git a/packages/editor/src/resolved-layer.tsx b/packages/editor/src/resolved-layer.tsx
index 01b2974aa..259f0b6f3 100644
--- a/packages/editor/src/resolved-layer.tsx
+++ b/packages/editor/src/resolved-layer.tsx
@@ -42,7 +42,7 @@ import { useResolvedActions } from "./resolved-actions";
 import { decisionHostVisible } from "./decision-placement";
 import { when } from "./card";
 import { Note, stamp } from "./comments";
-import { CommentSheet, commentSheetHeading, usesCommentSheet } from "./comment-sheet";
+import { CommentSheet, commentSheetHeading } from "./comment-sheet";
 import { displayName } from "./display-name";
 import { Face } from "./face";
 import { $rangeOf, paintShared } from "./marks";
@@ -63,7 +63,7 @@ import {
 	verticalReach,
 } from "./resolved";
 import { useQuestionnaires, useRelations } from "./questionnaires";
-import { PRIMARY_COARSE_POINTER_QUERY } from "./pointer";
+import { usePhone } from "./pointer";
 import { blockElement } from "./scroll";
 import { openCommentThread } from "./threads";
 import { useTransitionPresence } from "./transition-presence";
@@ -430,17 +430,9 @@ export function ResolvedLayer(
 	let pressing = useRef(false);
 	let enterPopover = useRef(false);
 	let origin = useRef<HTMLElement | undefined>(undefined);
-	let [primaryCoarse, setPrimaryCoarse] = useState(false);
-	useEffect(() => {
-		let query = matchMedia(PRIMARY_COARSE_POINTER_QUERY);
-		let update = () => setPrimaryCoarse(query.matches);
-		update();
-		query.addEventListener("change", update);
-		return () => query.removeEventListener("change", update);
-	}, []);
 	// On a phone a pinned resolved comment opens in the comment sheet, not a popover over the prose.
-	let compact = options.commentPresentation === "sheet"
-		&& usesCommentSheet({ coarse: primaryCoarse, width: host?.clientWidth ?? Infinity });
+	let phone = usePhone();
+	let compact = options.commentPresentation === "sheet" && phone;
 	let compactRef = useRef(compact);
 	compactRef.current = compact;
 	// A modal sheet hides the document from assistive tech; that is not the document going away.
diff --git a/packages/editor/src/styles.css b/packages/editor/src/styles.css
index b3b8c700b..78e65fe86 100644
--- a/packages/editor/src/styles.css
+++ b/packages/editor/src/styles.css
@@ -577,9 +577,8 @@
 /*
  * Wide authored blocks on a phone: a coarse pointer on a small screen, and a
  * narrow document. The media query is the phone class, kept identical to
- * `PHONE_QUERY` in widgets/phone.ts; when the shell publishes it as
- * `:root[data-phone]`, this one condition is what changes. Narrow desktop
- * windows keep their scroll lanes untouched.
+ * `isPhone` in pointer.ts, so it also holds where no shell sets
+ * `:root[data-phone]`. Narrow desktop windows keep their scroll lanes untouched.
  */
 @media (pointer: coarse) and (max-width: 600px), (pointer: coarse) and (max-height: 500px) {
 	@container (max-width: 40rem) {
diff --git a/packages/editor/src/toolbar/index.tsx b/packages/editor/src/toolbar/index.tsx
index 3dbd34604..b09cad715 100644
--- a/packages/editor/src/toolbar/index.tsx
+++ b/packages/editor/src/toolbar/index.tsx
@@ -15,7 +15,7 @@ import { createPortal } from "react-dom";
 import { selectionOffer } from "../edit-mode";
 import { $describe } from "../passage";
 import { widgets$ } from "../widgets-plugin";
-import { usePhone } from "../phone";
+import { usePhone } from "../pointer";
 import { SelectionBubble } from "./bubble";
 import { FormatDock } from "./dock";
 import { LinkSurface } from "./link";
diff --git a/packages/editor/src/widgets/questionnaire.tsx b/packages/editor/src/widgets/questionnaire.tsx
index cbab1f23f..4d1b89e68 100644
--- a/packages/editor/src/widgets/questionnaire.tsx
+++ b/packages/editor/src/widgets/questionnaire.tsx
@@ -26,7 +26,7 @@ import { Deck } from "../deck";
 import { deckLayout } from "../deck-runs";
 import { EvidenceHover, EvidenceTrigger } from "./evidence-hover";
 import { PresenceFaces, withoutSelf } from "../presence-faces";
-import { usePhone } from "./phone";
+import { usePhone } from "../pointer";
 import { PendingAnswersContext } from "../save-bar";
 import { forget, remember, selectionOf, stillMine, useSelections, withChange } from "../touched";
 import { useRelations } from "../questionnaires";
diff --git a/packages/editor/src/widgets/render-blocks.tsx b/packages/editor/src/widgets/render-blocks.tsx
index e04079e96..0a2b25dd0 100644
--- a/packages/editor/src/widgets/render-blocks.tsx
+++ b/packages/editor/src/widgets/render-blocks.tsx
@@ -58,7 +58,7 @@ import { describeDiagramError, kindOf, languageOptions, plainText, titleOf } fro
 import { CodeView } from "./code-view";
 import { fitsLegibly } from "./diagram-fit";
 import { DiagramSheet, ExpandDiagram } from "./diagram-sheet";
-import { usePhone } from "./phone";
+import { usePhone } from "../pointer";
 import { LanguageMenu } from "./language-menu";
 import { registerPreviewSelection } from "./preview-selection";
 import { diffSourceLine, lastLineStart, offsetOfLine } from "./source-offset";

From c5a337b6197d17c46d568fa275b8da544659138a Mon Sep 17 00:00:00 2001
From: Maggie Appleton <5599295+MaggieAppleton@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:16:04 +0100
Subject: [PATCH 08/10] Renew design-contract review hashes for the
 reading-mode owners and add ListIcon

- apps/web/src/workspace.tsx: passes a phoneToolbar node through to the tab
  bar; no class or style change.
- packages/editor/src/toolbar/bubble.tsx (20 pinned cases, one file):
  extracts convertBlock and adds a comment-only variant with a literal
  aria-label; the reviewed placement and class sites are unchanged.
- packages/editor/src/toolbar/slash.tsx: an open-slash command and a
  viewport clipped above the dock, numeric geometry only.
- packages/editor/src/plan-editor.tsx: reading mode, caret placement and a
  data-plan-reading flag; no new style expressions.
- packages/editor/src/resolved-layer.tsx and comment-layer.tsx: reading
  keeps sidecar actions, and the sheet follows the shared phone class.
- packages/editor/src/widgets/questionnaire.tsx: imports the shared phone
  hook; nothing else changed.
- packages/icons/src/list.tsx: new icon forwarding IconProps to LineIcon,
  like the reviewed sibling icons.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../exceptions/dynamic-editor.json             | 18 +++++++++---------
 .../exceptions/dynamic-packages.json           | 14 ++++++++++++++
 .../exceptions/dynamic-web.json                |  2 +-
 3 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/scripts/design-contract/exceptions/dynamic-editor.json b/scripts/design-contract/exceptions/dynamic-editor.json
index f0341a444..45c073d07 100644
--- a/scripts/design-contract/exceptions/dynamic-editor.json
+++ b/scripts/design-contract/exceptions/dynamic-editor.json
@@ -102,7 +102,7 @@
 				1
 			]
 		],
-		"sourceHash": "558cd35df361433eb32e0bdb9adf3bebfadae003d0dc48e014aec8498927b0cb"
+		"sourceHash": "447d5b138a9c02ea7804acc5ad37b9f19f983475c43c73350bc2c322bf7af708"
 	},
 	{
 		"file": "packages/editor/src/toolbar/bubble.tsx",
@@ -172,7 +172,7 @@
 				4
 			]
 		],
-		"sourceHash": "67072bbe65e50ef77d73b6d3913d3b493678bd4cf61e3c1c90c28eeaf3f08bba"
+		"sourceHash": "e661834fae291b0f83fcfd6ddfa49012435a546b0d298fbed09d1d6ab3e6738d"
 	},
 	{
 		"file": "packages/editor/src/widgets/research-motion.tsx",
@@ -214,7 +214,7 @@
 				1
 			]
 		],
-		"sourceHash": "14ed5508ba3bf275de10434fd151130b02c3beee0e0164c012084402dd2d6eb7"
+		"sourceHash": "2ec3f9ca5014f4c45015c19edb0b1479e69597bf871816c2450e949b67de9d17"
 	},
 	{
 		"file": "packages/editor/src/comment-layer.tsx",
@@ -242,7 +242,7 @@
 				1
 			]
 		],
-		"sourceHash": "14ed5508ba3bf275de10434fd151130b02c3beee0e0164c012084402dd2d6eb7"
+		"sourceHash": "2ec3f9ca5014f4c45015c19edb0b1479e69597bf871816c2450e949b67de9d17"
 	},
 	{
 		"file": "packages/editor/src/table/rails.tsx",
@@ -361,7 +361,7 @@
 				2
 			]
 		],
-		"sourceHash": "a0feb156f5b197fb4cc5a06f849503d2b6f7436848439e86b2dcfeb140ab4382"
+		"sourceHash": "8e4ca42841041f65cac8c8d3e3380c793019a7c7cf9992871d5fcd88afe6d511"
 	},
 	{
 		"file": "packages/editor/src/collaboration.tsx",
@@ -403,7 +403,7 @@
 				1
 			]
 		],
-		"sourceHash": "3bda8f742fdc353a9d6f16f1df71631bc6a2936bb1b3da514f5081d84261559f"
+		"sourceHash": "b4d7af43fdc69c771a65f63b5fc0beda6ef389db041b3bcc947e2449aa19a7d3"
 	},
 	{
 		"file": "packages/editor/src/widgets/code-view.tsx",
@@ -466,7 +466,7 @@
 				1
 			]
 		],
-		"sourceHash": "3bda8f742fdc353a9d6f16f1df71631bc6a2936bb1b3da514f5081d84261559f"
+		"sourceHash": "b4d7af43fdc69c771a65f63b5fc0beda6ef389db041b3bcc947e2449aa19a7d3"
 	},
 	{
 		"file": "packages/editor/src/resolved-layer.tsx",
@@ -480,7 +480,7 @@
 				1
 			]
 		],
-		"sourceHash": "30e54009e5163e39f86298586a466d01236e68aca762b1ca027b3881aba6c943"
+		"sourceHash": "cbf31bf18ac5eec0ac5d73b98948b7377628977e717a5bfc969396e1279fd3c6"
 	},
 	{
 		"file": "packages/editor/src/resolved-layer.tsx",
@@ -494,6 +494,6 @@
 				1
 			]
 		],
-		"sourceHash": "30e54009e5163e39f86298586a466d01236e68aca762b1ca027b3881aba6c943"
+		"sourceHash": "cbf31bf18ac5eec0ac5d73b98948b7377628977e717a5bfc969396e1279fd3c6"
 	}
 ]
diff --git a/scripts/design-contract/exceptions/dynamic-packages.json b/scripts/design-contract/exceptions/dynamic-packages.json
index 7c5b7a2a7..0699ec7dc 100644
--- a/scripts/design-contract/exceptions/dynamic-packages.json
+++ b/scripts/design-contract/exceptions/dynamic-packages.json
@@ -412,6 +412,20 @@
 		],
 		"sourceHash": "849f492e94d49ef2135dd7f00b7d9792c8d499b37bbdfbd2c4fc37b0f0207ad9"
 	},
+	{
+		"file": "packages/icons/src/list.tsx",
+		"reason": "Icon wrapper forwards SVG accessibility, sizing, and caller styling props. Literal style/class call sites are scanned; no ambient rendering code is executed.",
+		"cases": [
+			[
+				"dynamic",
+				"*",
+				"props",
+				"unresolved JSX props > ListIcon > <LineIcon>",
+				1
+			]
+		],
+		"sourceHash": "4f7d0232af2d03d5d8df9a226b48388c6a8011473ee53c2138568d77b8945bc3"
+	},
 	{
 		"file": "packages/visuals/src/ui/mini-bars.tsx",
 		"reason": "Public visual primitive forwards typed DOM/Base UI props. Literal style/class call sites remain scanned; runtime caller values need browser review.",
diff --git a/scripts/design-contract/exceptions/dynamic-web.json b/scripts/design-contract/exceptions/dynamic-web.json
index 695248b9c..74947d1fc 100644
--- a/scripts/design-contract/exceptions/dynamic-web.json
+++ b/scripts/design-contract/exceptions/dynamic-web.json
@@ -276,7 +276,7 @@
 				1
 			]
 		],
-		"sourceHash": "4ec004501afae96a55f8f9c90b925bd00077b25c56a4cd3e0cedf45e70b9df4a"
+		"sourceHash": "831e66816a4d138cd1aa768c8544cafdb451c35c3cae026f7003481b73fba155"
 	},
 	{
 		"file": "apps/web/src/navigation-dialog.tsx",

From 20a0dd8f7e70f76c552d92258e337e97ad909d8c Mon Sep 17 00:00:00 2001
From: Maggie Appleton <5599295+MaggieAppleton@users.noreply.github.com>
Date: Sun, 11 Oct 2026 12:45:54 +0100
Subject: [PATCH 09/10] Edit from the pencil in the merged phone specs and give
 the cue test a heading

- wide-content and pwa: phones open documents for reading, so the specs that
  type into a table cell, show source, or measure the callout title field
  tap Edit document first.
- phone-read-mode: the Editing pill stands in for the bar's title only while
  the document's heading is in view; seed one so the test exercises it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 e2e/phone-read-mode.e2e.ts | 3 ++-
 e2e/pwa.e2e.ts             | 2 ++
 e2e/wide-content.e2e.ts    | 7 +++++--
 3 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/e2e/phone-read-mode.e2e.ts b/e2e/phone-read-mode.e2e.ts
index d258baa77..911ea249a 100644
--- a/e2e/phone-read-mode.e2e.ts
+++ b/e2e/phone-read-mode.e2e.ts
@@ -93,7 +93,8 @@ test("an in-app link navigates within Chopin", async ({ baseURL, join, room, see
 });
 
 test("the pencil edits where the reader tapped and Done returns to reading", async ({ join, seed }) => {
-	await seed(SOURCE);
+	// A heading, so the top bar's small title waits at the top of the document.
+	await seed(`# Field notes\n\n${SOURCE}`);
 	let page = await join("ana", PHONE);
 	let writer = await join("bo", { viewport: { width: 1440, height: 900 } });
 
diff --git a/e2e/pwa.e2e.ts b/e2e/pwa.e2e.ts
index 556e5fca4..253506f13 100644
--- a/e2e/pwa.e2e.ts
+++ b/e2e/pwa.e2e.ts
@@ -52,6 +52,8 @@ test("touch text fields stay at least 16px while desktop keeps its sizes", async
 	expect(await fontSize(desktop, "Callout title")).toBeLessThan(16);
 
 	let phone = await join("ana", PHONE);
+	// Phones open documents for reading; fields appear once the writer edits.
+	await phone.getByRole("button", { name: "Edit document" }).tap();
 	expect(await fontSize(phone, "Callout title")).toBeGreaterThanOrEqual(16);
 	await content(phone).locator("p").filter({ hasText: "The rollout" }).selectText();
 	await phone.getByRole("button", { name: "Comment on this passage", exact: true }).click();
diff --git a/e2e/wide-content.e2e.ts b/e2e/wide-content.e2e.ts
index 778b1558a..d82936dcd 100644
--- a/e2e/wide-content.e2e.ts
+++ b/e2e/wide-content.e2e.ts
@@ -60,7 +60,9 @@ test("a wide table fades only the sides that still hide columns", async ({ join,
 	await expect(table).toHaveAttribute("data-more", "end");
 	await expectNoHorizontalOverflow(page);
 
-	// Editing a cell can give the table a new element; the fade must follow it.
+	// Editing a cell can give the table a new element; the fade must follow it. Phones open
+	// documents for reading, so the writer switches to editing first.
+	await page.getByRole("button", { name: "Edit document" }).tap();
 	await content(page).getByRole("cell", { name: "Same" }).click();
 	await page.keyboard.type(" as before, with a longer explanation");
 	await expect(content(page).getByRole("cell", { name: /longer explanation/ })).toBeVisible();
@@ -77,7 +79,8 @@ test("code wraps on a phone and keeps one preview when it stops", async ({ join,
 	await expect(view.locator("pre[data-overflow='wrap']")).toBeAttached();
 	expect(await view.evaluate(node => node.scrollWidth <= node.clientWidth)).toBe(true);
 
-	// The source wraps too while someone is editing it.
+	// The source wraps too while someone is editing it; phones edit from the pencil.
+	await page.getByRole("button", { name: "Edit document" }).tap();
 	await content(page).getByRole("button", { name: "Show source" }).click();
 	let source = content(page).locator("[data-plan-source]");
 	await expect(source).toBeVisible();

From bbffb87fcf0ade4db83e0d8dd7944fdb26b2db31 Mon Sep 17 00:00:00 2001
From: Maggie Appleton <5599295+MaggieAppleton@users.noreply.github.com>
Date: Sun, 11 Oct 2026 13:19:48 +0100
Subject: [PATCH 10/10] Follow the phone action sheet and pencil caret in the
 reading specs

- phone-read-mode: phones open document actions as a sheet (#478), so
  Rename is a button in that dialog, not a menu item.
- wide-content: entering editing puts the caret in the first block in view,
  which can already open the code's source; accept either state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 e2e/phone-read-mode.e2e.ts | 4 +++-
 e2e/wide-content.e2e.ts    | 5 ++++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/e2e/phone-read-mode.e2e.ts b/e2e/phone-read-mode.e2e.ts
index 911ea249a..e4f05d9de 100644
--- a/e2e/phone-read-mode.e2e.ts
+++ b/e2e/phone-read-mode.e2e.ts
@@ -288,7 +288,9 @@ test("only the document's own keyboard gets the formatting dock", async ({ baseU
 		await page.getByRole("navigation", { name: "Workspace view" })
 			.getByRole("button", { name: "Document", exact: true }).tap();
 		await page.locator(".phone-top-bar").getByRole("button", { name: /^Actions for / }).tap();
-		await page.getByRole("menuitem", { name: "Rename", exact: true }).tap();
+		// Phones open document actions as a sheet.
+		await page.getByRole("dialog", { name: /^Actions for / })
+			.getByRole("button", { name: "Rename", exact: true }).tap();
 		await expect(page.getByRole("textbox", { name: "Document title" })).toBeFocused();
 		await setVisualViewport(page, { event: "resize", height: 500 });
 		await expect(dock).toHaveCount(0);
diff --git a/e2e/wide-content.e2e.ts b/e2e/wide-content.e2e.ts
index d82936dcd..33b0dc073 100644
--- a/e2e/wide-content.e2e.ts
+++ b/e2e/wide-content.e2e.ts
@@ -81,8 +81,11 @@ test("code wraps on a phone and keeps one preview when it stops", async ({ join,
 
 	// The source wraps too while someone is editing it; phones edit from the pencil.
 	await page.getByRole("button", { name: "Edit document" }).tap();
-	await content(page).getByRole("button", { name: "Show source" }).click();
+	// Editing puts the caret in the first block in view, which may already open this source.
+	let show = content(page).getByRole("button", { name: "Show source" });
 	let source = content(page).locator("[data-plan-source]");
+	await expect(show.or(source).first()).toBeVisible();
+	if (await show.isVisible()) await show.click();
 	await expect(source).toBeVisible();
 	expect(await source.evaluate(node => node.scrollWidth <= node.clientWidth)).toBe(true);
 	await expectNoHorizontalOverflow(page);