Skip to content

AI-native design editor. Open-source Figma alternative.

5.5 KB
Raw Blame

Document sessions

stateDiagram-v2
  [*] --> Unloaded
  Unloaded --> Preparing: loadPage
  Preparing --> Unloaded: preflight rejects
  Preparing --> Mutating: dependencies valid
  Mutating --> Unloaded: rollback and discard events
  Mutating --> Loaded: commit and mark loaded
  Loaded --> Loaded: publish events or repeat load

Observer failure occurs after Loaded; it does not transition back to Unloaded.

APIs and ownership

materializeDocument(records) copies caller data. materializeFigArchive(bytes) owns its parsed records. Both support source-page selection through pageIds.

createFigDocumentSession(bytes) starts with page shells. loadPage(sourcePageId) adds content to the same graph and is idempotent for loaded pages. graphPageId(sourcePageId) bridges source IDs to runtime IDs used by worker requests. Existing graph/node identities and the editor's undo manager must survive later loads and recovery.

Page loading is not a user edit: it must neither add undo commands nor clear redo history. Failed-load rollback is separate from user undo.

DocumentAssemblyOptions extends the interpreter options: the handlers a session is created with decide whether records addressing deleted nodes or components fail the load or are skipped and reported. Broken hierarchy in the dependency closure is always fatal. Core creates its open, recovery, and export sessions with one shared diagnostics sink per document.

Transaction semantics

Implemented: a scoped synchronous journal restores selected existing nodes, child lists, instance indexes, and reader lookup maps, and removes newly created nodes if the load action throws. It is not a general SceneGraph transaction. Unrelated document payloads are not cloned.

Graph events are buffered until the mutation succeeds. Nested buffers merge into their outer buffer. Observers run after the page is marked loaded. CommittedGraphEventError means graph state committed but notification failed; callers must not retry as if the graph rolled back. Queued events continue to be attempted. The underlying nanoevents dispatch may stop remaining listeners for a single event when one listener throws.

Worker results and recovery

sequenceDiagram
  participant C as Client
  participant W as Reader worker
  participant G as Edited graph
  C->>W: Populate page at base revision
  W-->>C: Delta and checkpoint
  alt Revision matches
    C->>G: Apply delta
    C->>C: Accept checkpoint
  else Result is stale
    C->>C: Reject delta and checkpoint
    C->>G: Resume reader against existing graph
  end

Only an accepted delta advances the receiver's checkpoint. Original archive bytes remain available for recovery and are released with session ownership. Recovery never replaces the edited graph.

An edited export writes every page. With a live session, it first reads internal-only pages into the edited graph: their layers never draw and loading is not an edit. Once every page is loaded, the session and the archive are released, and saves write from the document graph without a copy. Visible pages that are still unloaded are read only into a copy of the graph made for that save; a save never loads one into the document. While a population worker still fills the graph there is no live session, and internal pages are read into the copy too.

Checkpoints contain source-to-node mappings, loaded pages, saved-size tracking, and component topology addressed by complete source-identity paths. Occurrence property payloads are reconstructed from source records when recovery is needed. Restore validates paths, component identity, coverage, and roots before attaching to graph nodes.

Checkpoint stores                 Recovery reconstructs
-------------------------------   -------------------------------
source path -> graph node ID      occurrence properties
main-component identity           binding evaluation
loaded source page IDs            source-derived geometry
saved-size tracking               links to EXISTING graph objects

Rollback example

                      Before load   During load    After failure
Existing node ID       n17           n17            n17
Existing edit         "Custom"      "Custom"       "Custom"
New nodes             --            n21, n22        --
Loaded pages          {A}           {A}             {A}
Load notifications    --            buffered        discarded

This is load rollback, not an undo command. Existing user history remains intact.

Known limitations

  • Component child additions, deletions, and reordering are rejected before another page load; structural reconciliation is not implemented.
  • All frontend lifecycle and cancellation scenarios are not yet accepted. Synchronous work cannot be interrupted merely by queuing a cancel message; transport termination is tested.
  • Large-page construction and checkpoint costs still require performance work.

Implementation and tests