Readiness and asynchronous operations

The native document surface starts after the editor attaches to a visible application window. Initialize from the window-opened workflow and await readiness.

await editor.Ready;
await editor.SetBodyHtmlAsync("<p>Document</p>");
string html = await editor.GetBodyHtmlAsync();

Do not wait on Ready before showing the window. Do not block the UI thread with Task.Wait() or Task.Result. Awaited operations serialize native browser communication.

Handle operation failures

Read-only state, mode and changed document/selection identity can reject a captured operation. Refresh state and let the user choose the next action. A timeout after submission can leave the mutation outcome uncertain; do not resubmit a mutation automatically.

Optional image display work

Resource validation follows accepted content operations. It has a bounded read budget and does not enter content history. Caller cancellation during this optional phase retains the acknowledged content result; a lifetime-owned refresh can complete display later. Policy changes cancel old hydration. Source-selection offsets are retained only when the current document and range still match.

Source, lifecycle and files

New typing during source apply remains dirty. Explicitly apply the remaining draft or discard after pending work settles. Detachment/recreation retains accepted content and uncommitted source separately; captured operations from an old browser session are rejected. An application's controlled reparenting can use BeginReparentingAsync().

Built-in Open/Save commands use native pickers and bounded decoding/atomic file replacement. Choosing or cancelling Save does not apply the source draft. Document/source changes while a picker is open reject the stale operation.

Handle acknowledged work

Do not automatically replay a submitted mutation after timeout or cancellation. Optional image hydration follows the accepted content operation and preserves its primary acknowledgment. Picker cancellation and stale document identity must be handled without discarding an unrelated source draft.