Skip to contents

Design Notes

Source: DESIGN.md

This document records architectural priorities for grrr so they are not lost.

10 Design Points

  1. Tree-first model
  • Treat every graphic as a scene tree (AST), not a one-shot imperative draw sequence.
  1. Atomic vs compound nodes
  • Keep a strict split between leaf drawables (grab_atom) and structural/group nodes (grab_bag).
  1. Late expansion
  • Expand compound nodes to backend primitives only at rendering/lowering time.
  1. Explicit coordinate spaces
  • Every node declares its coordinate space (for example data, panel, local, device).
  1. Explicit transforms
  • Every node carries a transform payload so nested placement is deterministic and inspectable.
  1. Stable node identity
  • Nodes have stable IDs suitable for diffing, targeted updates, caching, and interaction.
  1. Style inheritance as data
  • Inherited aesthetics are merged branch-wise and treated as explicit render state.
  1. Deterministic traversal and passes
  • Rendering proceeds through explicit, deterministic passes rather than hidden side effects.
  1. Dirty tracking and caching
  • Nodes can be marked dirty, and render/style computation may be cached across passes.
  1. Versioned scene schema
  • Scene AST is serializable with explicit schema versioning for portability and migration.

Implementation Roadmap (for grrr)

Scope note: grrr should focus on scene representation and rendering infrastructure; high-level plot grammar construction belongs to bridge packages (for example ggplot-oriented tooling), not grrr core.

  1. Formalize spaces and transforms
  • Add coordinate_space and transform to all nodes.
  1. Add stable IDs and deterministic traversal
  • Add node_id to nodes and provide deterministic path-based assignment.
  1. Implement explicit rendering passes
  • Use prepare/plan/emit rendering stages.
  1. Add style cache + dirty tracking
  • Cache merged branch styles with dirty-aware invalidation.
  1. Add versioned scene schema and serializers
  • Provide list/json/yaml serialization with schema metadata.