[foxnne]

Stacked on #601 and based on its branch, so the diff is this change alone; GitHub retargets it to main when #601 merges. It takes up the follow-ups that PR lists.

What changes

For plugin authors: a new optional Plugin.VTable.documentBytes(state, doc, path, allocator) → []u8. It returns the bytes a save to path would write, for a copy that is not a save, with none of a save's bookkeeping or side effects: no format on save, no edit remembered for documentWritten, no undo stop. fizzy takes these bytes:

• for the crash checkpoint (KeptDocuments.capture from Checkpoint, every few seconds of typing)
• for a restart or a plugin reload carrying unsaved work
• for a tape's file (Tracks.fileAt)
• for a fizzy.document.changed listener that asks for the unsaved text

An owner without the hook keeps working as before: Plugin.documentBytes falls back to documentSnapshot + encodeSnapshot, bookkeeping included.

Saves keep the snapshot: DocumentIo.save, and the web download (Editor.downloadDocument), which now calls the new Plugin.saveBytes (both halves of a save at once, followed by documentWritten).

Why: documentSnapshot is "the storage-agnostic half of saving". It runs at a save's start, so it formats on save and records which edit the bytes stand for. Every non-save copy did the same. In the text plugin that meant:

1. With format_on_save on (off by default), each checkpoint ran the formatter on a dirty document while the person was typing in it.
2. A checkpoint taken while a save's write was in flight overwrote serialized_op_id. If an edit came in between, the write landed and documentWritten marked the document clean at an edit newer than the file on disk.

Implemented in:

• text: the hook returns the text as it stands.
• archive: it had the same in-flight bug through serialized_generation, so it gets the hook too (doc.pack, with no generation recorded).

Document.savedBytes's comment now says only a save takes it. docs/PLUGINS.md names the hook, and its storage-agnostic section now names the snapshot pair, which is what a save uses.

Tests (tests/integration.zig, the tour test's "A document's steps" block, after #601's save check):

• Format on save on, with a stand-in formatter: a KeptDocuments.capture keeps the text as typed and leaves the document unformatted. A real save (saveBytes) still formats, which shows the formatter was live.
• A checkpoint while a save is in flight: take a save's snapshot at "a", type "b", take a checkpoint, then land the write (documentWritten). The document is still dirty.

Each check fails without the text plugin's hook: the first with formatted where as typed was expected, the second with the document clean.

SDK impact

• None
• Core-only or additive: reaches plugins at the next SDK release
• Fingerprint moved: recorded in sdk/src/version.zig, sdk_version untouched, PR labelled sdk
• SDK release: bumps sdk_version, lists the sdk PRs since the last sdk-v* tag

A new optional vtable field, null by default. An existing plugin builds unchanged and gets the fallback, which behaves as before.

pixi (fizzyedit/pixi) implements documentSnapshot and has both problems in its own form:

• File.saveSnapshot sets editor.saving_bookmark = history.bookmark, so a checkpoint during a save moves the bookmark that written cleans to.
• It also calls finishReveal(), so a checkpoint ends a reveal in progress.

pixi would need a documentBytes that builds the same Snapshot content without those two lines, encodes it in place (File.encode), and destroys it. The .pixi zip encode then runs on the UI thread at each checkpoint, as it already does through the fallback today.

Verified

• macOS: zig build test-integration (80/80 steps; the two new checks each fail with the text hook removed), zig build, zig build test (113/113), check-web (42/42), test-sdk-version (35/35). scripts/check-fmt.sh flags only backend/src/platform/win32_titlebar.zig, which this branch's base (text: a crash checkpoint no longer splits a run of typing #601's) predates main's fix for (ci: main's checks pass again (a formatted file, the examples' branch) #597); untouched here.
• Windows:
• Linux: CI
• Web: check-web builds; the download path was not run

Follow-ups

• pixi's documentBytes is written and builds against this branch's SDK, with pixi's zig build test passing. It's a local change for the pixi repo, pushed at the repin that brings this SDK, since SDK 0.2.30 has no such field. It splits saveSnapshot into the save's bookkeeping around a takeSnapshot that changes nothing. A drawing still being revealed is completed in the copy, as captureState does; a flat image is the one case that still finishes the reveal, because its composite is read back from the GPU.
• The checkpoint still encodes on the UI thread for every owner. If a large document shows up in a frame, the seam is to snapshot through the hook and encode on DocumentIo's worker.

🤖 Generated with Claude Code