.fig Reader Architecture

The reader interprets Figma source records into independently editable scene occurrences. One reader serves the application, CLI, MCP, and worker paths; the earlier importer and its repair pipeline are gone.

Implementation status

The reader is the only import path: synchronous parsing, the document worker, page population, recovery, export, and clipboard paste all use it, and the previous importer is removed. Corpus-wide fidelity (export still reassigns node identities and drops some raw text metadata) and performance acceptance remain unfinished. The diagram describes responsibilities, not a claim of complete Figma parity.

flowchart TD
  Archive[FIG archive and resources] --> Sources[Indexed source records]
  Sources --> Closure[Selected pages and component dependencies]
  Closure --> Evaluation[Occurrence evaluation and provenance]
  Evaluation --> Graph[Editable SceneGraph]
  Graph --> Sessions[Page sessions and recovery]
  Graph --> Editor[Editor actions and undo]
  Editor --> Export[FIG export]
  Export --> Oracle[Figma reopen and visual validation]

Key distinctions

• A source record identifies an archive node; an occurrence identifies one use of it.
• An owner establishes the component scope for an override claim.
• An effective value is not enough to determine whether it is inherited or overridden.
• Saved appearance, editable layout, and exported-file fidelity are separate contracts.

                         Inherited default       Explicit equal value
Initial text             "Badge"                 "Badge"
Component changes        "Updated"               "Updated"
Instance result          "Updated"               "Badge"

Package documentation

The canonical implementation documentation lives alongside the package in packages/fig/docs. This page is the development-site entry point, not a second copy of those contracts.

Read in order:

1. Architecture and ownership
2. Source model and identities
3. Instance evaluation and precedence
4. SceneGraph materialization
5. Document sessions, rollback, and recovery
6. Export contracts
7. Validation and oracle methodology

See also system architecture, testing, and the development roadmap. Fixture provenance belongs next to fixtures; individual benchmark runs and temporary oracle results do not belong in architecture documentation.