Skip to content

Add full Preview state codec for Work Column transfer #981

Description

@jeonghun-jj-lee

Important

Problem -- Preview currently owns editable renderer state inside one webview. A detached host cannot provide equivalent editing without a complete, versioned logical document codec.

Approach -- Encode and restore Preview's recursive workspace, document identity, drafts, selections, scroll anchors, undo/redo, pending save and close operations, and conflict state through #979's acknowledged journal.

Scope -- in: Preview state codec, write-ahead mutations, hydration, save/close fencing, and round-trip tests. out: native panel creation, attached geometry, inspector replay, and widget state.

Assumptions -- Physical editor and renderer instances may be recreated across webviews, but every supported logical editing outcome must remain equivalent.

Acceptance Criteria

  • A Preview checkpoint round-trips pane tree, stable pane IDs, tab order, active tab, focused leaf, zoom, and canvas scroll.
  • Every open document round-trips resource identity, base revision, dirty content, mode, multi-selection, renderer scroll anchor, undo/redo history, pending save or close operation, save outcome, and conflict state.
  • A Preview mutation is write-ahead journaled through Add durable Work Column record and lease journal #979 before it is treated as committed by the host.
  • Hydrating a checkpoint recreates equivalent editable state, including undo/redo and dirty-close behavior, without duplicating an open document.
  • A stale save or close result whose operation ID or lease generation no longer matches is ignored without changing current document state.
  • A failed codec or checksum validation leaves the current host lease unchanged and reports hydration failure.
  • Ordinary in-document Preview moves keep physical renderer identity; cross-webview hydration creates a new physical instance only after logical state validates.

Testing Decisions

Create codec round-trip and operation-order tests for documents, pane trees, dirty drafts, multi-selection, undo/redo, save, close, and conflicts. Extend the existing Preview browser suite with an editable-document parity fixture that compares outcomes before and after hydrate.

Key Decisions

  • Logical document parity -- cross-webview transfer preserves document semantics and history, not the original editor object.
  • Fenced async results -- save and close completion apply only to the exact operation and lease generation that initiated them.
  • Checkpoint validation -- codec version and canonical checksum must agree before a destination may acknowledge hydration.

Constraints & Invariants

  • The eight-document limit remains a logical-document limit.
  • No dirty draft or acknowledged editor operation is lost across hydrate.
  • This slice does not create a detached host; it supplies its required state codec.

Prior Art

  • Existing Preview workspace, retained renderer, editor, and dirty-close behavior.
  • Existing Preview browser regression coverage.

Source

Part of #977. Blocked by #979. ADR 0014, Dockable Work Column.

Review Amendment (2026-09-10)

  • Resolve state ownership with the ADR amendment: the workspace owns the pane tree and split-node geometry plus outer-canvas scroll; each leaf owns tab order, active tab, focus, and zoom; each document owns mode, draft, selections, editor history, and renderer scroll.
  • Add conditional file writes: reads expose a content revision; writes require an expected revision and return either the next revision or authoritative conflict content and revision.
  • Define a versioned editor-state adapter containing document text, all selection ranges, primary range, history groups, and replay or mapping policy. Hydration constructs the editor from this adapter before accepting input.
  • Define document revisions as provisional, journal-acknowledged, and transferable. Checkpoint quiescence drains through a named acknowledged revision with retry and backpressure behavior.
  • State that a restored dirty draft is authoritative over its matching base revision. Late reads refresh clean state only or surface a conflict, never overwrite the restored draft.
  • Define scroll-anchor variants and restore timing for workspace, text editor, markdown preview, image, and PDF. Explicitly exclude non-serializable visual selections where no logical equivalent exists.
  • Define save and close transitions keyed by operation ID, lease generation, and document revision; validate hydrate referential integrity for unique resources, pane IDs, active tabs, focus IDs, split ratios, and the eight-document limit.
  • Add bidirectional two-webview tests for undo/redo, multi-selection, delayed reads and saves, close-transfer races, stale completions, invalid checkpoints, document-kind anchors, and ordinary in-document renderer identity.

Metadata

Metadata

Labels

hitlNeeds human review before merge

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions