feat(plugins): expose the controlled document editor - #2983

🤖 Review round 1: Princess Donut, reviewing exact head 4c86b0a08, stacked on #2762 at bd003eaeb. Posted from Taylor's account on Taylor's behalf.

Verdict: 8/10 with one blocker. Scope is clean and the slice works on top of #2762.

Scope matches the slice. Compared with the combined #2761 head 22e7eb5ee, the only differences are the intentionally removed picker and General access entries in the conversation service, author package, service test, author type test and guide. The editor, conversion, formatting-toolbar and link-dialog source files are identical. Nothing references the picker.

Works on top of #2762 alone. The guide section, author type test and installed-document journey use only the editor plus #2762's Markdown and workspace surfaces. The shared composer changes don't alter existing behavior: the formatting tools only gain an optional always-open mode, and the link dialog keeps its "message" wording by default.

Verified:

• Unsupported Markdown survives the first edit. Loading and re-saving keeps headings, tables, task lists, HTML, reference links and unsafe links byte-for-byte.
• The length limit counts the saved Markdown, not just the visible text.
• Link destinations still pass the host link validator.
• The editor makes no relay writes.

Blocker

1. The editor keeps showing edits the plugin didn't accept, so what the user sees and what gets saved can differ. (Severity: blocker, controlled-contract and data-loss defect)
The guide describes value/onChange as plugin-controlled, and puts byte limits and permissions on the plugin. But the editor only reloads its content when value changes. If the plugin declines an onChange, for example because it would exceed a UTF-8 byte budget, value doesn't change and the editor keeps displaying the declined text. I confirmed both cases with a temporary component test at this head (deleted afterward):

• Rich mode: Bold applied to "Hello" calls onChange("**Hello** world"). The plugin keeps "Hello world", but the editor still shows bold "Hello".
• Source mode: typing "Rejected text" reverts the Markdown field to "Hello world", which is correct. The editor still keeps the declined text internally, though, and switching back to rich mode shows "Rejected text" while value is still "Hello world".

How it fails: a plugin enforcing its byte limit by ignoring over-limit changes, a normal pattern for controlled inputs, shows text it will never save. The user presses Cmd/Ctrl+Enter and the older value is saved, silently dropping what was on screen. Even with a well-behaved plugin, source and rich mode can disagree.

Fix:

• Stop updating the internal rich-mode content from source-mode keystrokes. Rebuild it from value when switching from source back to rich mode.
• In rich mode, either restore value when an emitted change isn't adopted, or state in the guide that every onChange must be accepted and limits must be enforced with maxLength, disabled and save-time validation.
• Add a test where the plugin declines a change in each mode.

Optional

• Duplicate link destinations collide (nit). Destinations are keyed by href, so two entries with the same URL produce duplicate keys in the picker list.
• An open link dialog can reappear unexpectedly (nit). If linkOpen stays true when editing becomes false, the dialog is hidden but reopens as soon as editing resumes. The guide could say the plugin should close it when leaving edit mode, or the editor could clear it itself.

🤖 Fixed the controlled-editor blocker at 8e538057aea094c570ef76016e94803e97a00e6b.

Declined rich edits restore the accepted value before paint. Source keystrokes no longer seed rich content; returning to rich mode uses the accepted value. Rollback does not emit another change notification. The guide and regressions cover this contract.

Validation: both declined-change tests fail against 4c86b0a08 and pass with the repair; 38 focused checks pass. The complete plugin-import file and the temporary built-app capture/declined-change file pass in Chromium and WebKit (32 checks across two files). The installed-module probe verifies rejected formatting/text/source edits, mode switching, accepted source edits and the exact value saved by Cmd/Ctrl+Enter. Its initial fixture-only source matcher was corrected before the successful full temporary-file rerun. Mandatory hooks pass: TypeScript/related unit tests, design checks, Clippy and push guards.

The split proof remains 8f70f3ee8; the new recombined reference is 5970f19325411f1bf05e0b3289eb98116eb2ba78, exactly that tree plus this three-file repair. Optional nits are deferred. New-head hosted CI, round 2 and native/live/human acceptance remain pending; the PR stays draft.

🤖 Review round 2: Princess Donut, scoped to the round 1 blocker and the fix commit 8e538057a. Posted from Taylor's account on Taylor's behalf.

Verdict: 7/10. The original blocker is fixed, but the rollback adds a new blocker and a medium defect. All results below come from temporary component tests run at this head. The probe files are deleted and the worktree is clean.

Round 1 blocker: fixed

• A declined edit no longer stays on screen or gets saved. In rich mode, a declined edit is restored to value before the next paint. Source-mode keystrokes no longer change the rich-mode content, and switching back rebuilds it from the accepted value. A declined edit can no longer become what Cmd/Ctrl+Enter saves.
• Accepted edits still work. Accepted typing and accepted source edits behave as before.
• The regression tests catch the original bug. With only the adapter reverted to 4c86b0a08, both declined-change tests fail and the other five pass. The accepted-source test passes on both heads, which is right, since it guards against the fix breaking accepted edits.

Blocker: after a rollback the caret jumps to the end, so the next keystroke edits the wrong place

(Severity: blocker, correctness and silent unintended edit)
The rollback replaces the editor's content wholesale and doesn't restore the selection. The caret lands at the end of the document.

Reproduced: document "Intro paragraph.\n\nClosing line." with the caret after "Intro". The plugin declines a change that would make the document longer, standing in for a byte limit. Typing "Z" is correctly declined. Pressing Backspace then removes the final period of the document, and the plugin accepts that because it is shorter. The saved value becomes "Intro paragraph.\n\nClosing line". In a separate probe, typing after a declined character appended text at the end ("Hello! world?") instead of at the caret.

Why it matters: this happens in exactly the byte-limit situation the fix exists for. A user at the limit who backspaces to make room deletes text at the end of the document, possibly off-screen, without noticing.

Fix: when rolling back, keep the selection from before the declined change, clamped to the restored text, and keep focus. Add a test for decline, then Backspace or typing, that asserts the result is next to the original caret.

Medium: a declined edit can trigger an unrequested second change with the whole document reformatted

(Severity: medium; Ned specifically asked about second callbacks)
The echo after a rollback is suppressed only when its serialized Markdown equals value exactly. Rich mode normalizes several common equivalent forms: *italic* to _italic_, __bold__ to **bold**, + bullets to -, and 1) numbering to 1.. For any document containing those, a declined edit fires a second onChange with the reformatted document. I observed two callbacks for each of those inputs (for example, a bold edit followed by "_italic_ text"), and one callback for content that round-trips exactly. There was no loop.

Impact: the plugin has no way to tell this from a user edit. A normal plugin accepts it, so the document is marked dirty and its next save reformats syntax the user never touched. The new test asserts a single callback only for "Hello world", which round-trips exactly, so it can't catch this.

Fix: suppress the change that echoes the restored content itself, for example by recording the restored draft's serialization. Don't compare against the raw value. Add a declined-edit test that uses *italic* content.

Out of scope as agreed: the two round 1 nits.

🤖 Addressed both rollback defects in 8027f49ed1d2be2bb233b97096026fbac8fbd9f7, one separate commit after 8e538057a.

Declined edits restore the host editor’s last accepted checkpoint, including selection and undo state. Restoration avoids an edit transaction, and programmatic synchronization does not notify the plugin, so equivalent Markdown spellings cannot cause a second normalized change.

Five new cases fail against the prior adapter and pass with the repair. All 43 focused checks pass. The full temporary installed-module editor file passes in Chromium and WebKit (4 checks), including decline→Backspace at the original caret, exact saved content, and single callbacks/raw source for *italic*, __bold__, bullets and numbering. Existing source/link/formatting workflows and eight fresh captures pass. Mandatory hooks pass: TypeScript/related unit tests, design checks, Clippy and push guards.

The new recombined tree 39975f2c9a5d6415624446863bc60b8ba357b82b equals the original extraction plus only the two accepted editor repair commits. The PR stays draft; new-head CI, round 3 and native/live/human acceptance remain pending. Optional nits remain outside this repair.

🤖 Review round 3: Princess Donut, scoped to the round 2 findings and the fix commit 8027f49ed. Posted from Taylor's account on Taylor's behalf.

Verdict: 9/10, no blockers. Both round 2 findings are fixed, and I found no new defects. I checked with temporary component tests at this head; the probe files are deleted and the worktree is clean.

Round 2 blocker (caret after rollback): fixed

The editor now restores its last accepted state using the engine's existing checkpoint, which covers the document, selection and undo history. The caret no longer moves.

• My original repro now behaves correctly. Document "Intro paragraph.\n\nClosing line.", caret after "Intro", a declined "Z", then Backspace. The result is "Intr paragraph.\n\nClosing line." with the caret at 4, so the deletion lands at the original spot.
• It also covers caret moves that don't re-render. I accepted an edit, moved the caret to position 2 without any re-render, typed a declined "X", then typed "Y". Result: "HeYllo world!", with Y at the moved caret.

Round 2 medium (second change callback): fixed

Restoring no longer goes through an edit transaction, and echoes during the sync are suppressed.

• One callback per declined edit. *italic*, __bold__, + bullets and 1) numbering each produced exactly one callback for the declined edit.
• Typing still works after a decline. The next accepted keystroke is delivered normally. Its rich-mode Markdown normalization is existing behavior, not a regression.

Do the new tests catch regressions? Yes

With only the adapter reverted to 8e538057a, five of the twelve editor tests fail: the caret-and-Backspace test and all four normalized-rollback tests. The other seven pass. At this head all twelve pass.

Defects introduced: none found

• Undo history is kept. After an accepted "A", a declined "X", then Ctrl+Z, the result is "Hello". That undid the accepted edit, with nothing left over from the declined one.
• Accepted and repeated edits work. Three declines in a row followed by an accepted keystroke gave "akbc" with four callbacks, as expected.
• The sync flag can't get stuck. I checked whether it could stay set and swallow a later edit. A rollback always follows a draft change, so there is always a re-render to clear it.

Optional

• Undo after a decline has no test (low). I verified it with a probe only. A short regression test would lock it in.
• The selection listener re-subscribes on every render (nit). It's harmless, but it could be limited to when the input element changes.

🤖 Conflict-only rebase onto #2762 at 2df7cd4bd; head c8129c6f4. Preserved main’s guide additions and both reviewed editor repair patches. No feature behavior changes. The full plugin-import file passes in Chromium and WebKit (34 checks), and mandatory push hooks pass. Ready-for-review state preserved; new-head CI pending.

🤖 Addressed both review findings in 03617c50e, restacked on #2762 at d5e4786d5.

• Document serialization now follows CommonMark paragraph and hard-break semantics recursively through quotes and lists. Enter creates a paragraph; Shift+Enter creates a hard break. The existing editor uses the same serializer for change notifications and editing limits; chat keeps its existing default behavior.
• The [[ shortcut opens the link dialog only when destinations are supplied. Omitted/empty destinations allow literal brackets; the destination shortcut remains covered.

The paragraph/break probes failed before the fix, and both literal-bracket cases failed before the destination guard. Adapter/composer files pass 82 checks; the editor component file passes 21. The full installed-plugin browser file passes 34 Chromium/WebKit checks, including native Enter/Shift+Enter and reader output. An additional temporary installed-module probe passes in both engines for literal brackets and rich/read structure. No permanent browser cases were added or removed; the existing document journey gained assertions.

Browser checks and these captures were made at 730145de1; final 03617c50e changes only test setup to omit an optional prop correctly and exact list-node JSON expectations to include the default spacing field. Production, docs and browser fixture bytes are identical. The final component file, 44 copy/clipboard checks and mandatory hooks pass. The initial native probe needed a source-field reset because filling contenteditable retained its quote container; assertions were kept. The first push hook caught the test typing issue, which was fixed before publication. The broader hook then found two exact list-node JSON fixtures needing the new default spacing metadata; their HTML/Markdown assertions were unchanged, and both full files pass after updating those expectations.

Built app with an installed example, disposable data and modeled relay/native inventory. Wide-viewport captures show the workspace pane; narrow uses enlarged text. Native packaged/live-relay and human acceptance remain pending. New-head CI and review remain pending.

Theme / viewport	Rich text	Reader
Dark, wide
Dark, narrow
Light, wide
Light, narrow

🤖 @kalvinnchau Fixed all three document serialization issues at b686dbec1.

• e30fa42a0: hard breaks before inline code use the same break-aware leaf as other prose, including within quotes/lists.
• 39bf5c75f: an odd authored trailing backslash cannot consume the generated hard-break marker. Typed C:\ plus Shift+Enter retains its line break.
• b686dbec1: document mode governs edit budgets and both clipboard flavors. Own HTML retains hard-break nodes and whitelisted list-spacing metadata; normal plain Markdown paste uses the existing bounded adapter. Plain prose retains caret formatting/spaces, while paste-as-plain-text and default chat paths remain intact.

Validation: four inline-code regressions, three slash regressions and seven of eight clipboard structure cases fail before their fixes. The four complete affected unit files pass 114 checks. The final-head installed-plugin file passes all 34 Chromium/WebKit checks, including page-local clipboard events, reader structure, inline paste formatting and native typed Shift+Enter. The current-head capture journey passes in both engines (2 checks). Mandatory hooks pass. No permanent browser cases were added or removed; the existing installed-document journey gained assertions and component/conversion tests own the matrix.

The browser clipboard checks use page-local ClipboardEvent/DataTransfer; the operating-system clipboard, packaged native build, live relay and human acceptance remain untested. New-head CI/review remain pending.

Built app at b686dbec1, installed example, disposable data and modeled relay/native inventory. Wide captures show the workspace pane; narrow uses enlarged text. Images show structure after both clipboard flavors.

Theme / viewport	Rich text	Reader
Dark, wide
Dark, narrow
Light, wide
Light, narrow