The scene contract: what vellumplot and vellumwidget depend on

The seam, in one picture

  vellumplot  ──compiles a plot to grobs carrying──▶  key / meta / id / role
                                                        │
  vellum  ──renders──▶  scene_svg()   (data-key, data-vellum-*, role attrs)
                        scene_model()  (per-element table: identity + bbox)
                                                        │
  vellumwidget  ──reads scene_svg() + scene_model()──▶  hover / select / brush / link

Everything below the grammar is pure metadata: a static PNG/SVG render never calls scene_model(), and a grob without a key/meta still draws exactly as before. Nothing here changes what is painted.

Carrying identity on a grob

The batched mark constructors (points_grob(), circle_grob(), rect_grob(), segments_grob(), hexagon_grob(), sector_grob()) take two optional per-element arguments:

• key: a character vector of data keys, one per element (recycled). This is the join key a host uses to tie an on-screen element back to a datum.
• meta: a list of free-form per-element records (recycled), e.g. a tooltip string or field values.

Every grob also takes id and role (a single value per grob) for semantic identity and accessibility.

s <- vl_scene(5, 3, bg = "white") |>
  draw(points_grob(
    x    = c(0.25, 0.5, 0.75),
    y    = c(0.4, 0.7, 0.4),
    size = vl_unit(6, "mm"),
    gp   = vl_gpar(fill = "#3498db", col = NA),
    key  = c("a", "b", "c"),
    meta = list(
      list(tooltip = "first"),
      list(tooltip = "second"),
      list(tooltip = "third")
    )
  ))
s

(Each batched grob carries one graphical style; the grammar layer above vellum emits one grob per style bucket, so a scatter with three colours is three points_grob()s. The key/meta machinery is per element regardless.)

scene_model(): the per-element table

scene_model() walks the rendered scene and returns a list of two data frames.

m <- scene_model(s)
names(m)
#> [1] "elements" "panels"

str(m$elements)
#> 'data.frame':    3 obs. of  14 variables:
#>  $ key  : chr  "a" "b" "c"
#>  $ mark : chr  "point" "point" "point"
#>  $ id   : chr  NA NA NA
#>  $ name : chr  NA NA NA
#>  $ panel: chr  NA NA NA
#>  $ x0   : num  97.3 217.3 337.3
#>  $ y0   : num  150.1 63.7 150.1
#>  $ x1   : num  143 263 383
#>  $ y1   : num  195 109 195
#>  $ x    : num  120 240 360
#>  $ y    : num  172.8 86.4 172.8
#>  $ w    : num  45.4 45.4 45.4
#>  $ h    : num  45.4 45.4 45.4
#>  $ meta :List of 3
#>   ..$ :List of 1
#>   .. ..$ tooltip: chr "first"
#>   ..$ :List of 1
#>   .. ..$ tooltip: chr "second"
#>   ..$ :List of 1
#>   .. ..$ tooltip: chr "third"

str(m$panels)
#> 'data.frame':    0 obs. of  5 variables:
#>  $ name: chr 
#>  $ x0  : num 
#>  $ y0  : num 
#>  $ x1  : num 
#>  $ y1  : num

scene_svg(): the emitted attributes

scene_svg() returns the same scene as an SVG string. Interactivity rides on SVG attributes; the raster and PDF backends ignore all of them.

svg <- scene_svg(s)
# the data-key attributes on the three points:
regmatches(svg, gregexpr('data-key="[^"]*"', svg))[[1]]
#> [1] "data-key=\"a\"" "data-key=\"b\"" "data-key=\"c\""

Four attribute mechanisms, each emitted only when its source is set:

An empty/NULL source emits no attribute, so a scene that declares no interactivity is byte-for-byte identical to one built before any of this existed.

Accessibility

A scene carries an optional accessible name and description, set with vl_scene(title=, desc=) or describe(scene, title=, desc=). When present:

• the SVG root becomes <svg role="img" aria-labelledby="…"> with <title> and <desc> children (the reliable screen-reader pattern; WCAG 1.1.1);
• the PDF is a tagged PDF: the chart is a Figure in the structure tree whose Alt is the description.

This is additive: with no title/desc the output is unchanged. The grammar layer (vellumplot) sets these automatically from the plot’s title and an auto-generated (or labs(alt=)) alt text. See vellumplot’s Accessibility article. Per-element role (above) is a genuine ARIA role; the interactive widget layer (vellumwidget) adds keyboard navigation and live-region announcements on top.

Invariants the contract guarantees

These are the properties vellumplot and vellumwidget are entitled to rely on, and that vellum’s own tests (tests/testthat/test-contract.R) pin down:

1. Paint order. scene_model()$elements is in draw order, and the SVG emits elements in the same order. A host can zip the SVG DOM and the table positionally.
2. Semantic/geometry agreement. scene_model() builds the identity columns from the R grob tree and the geometry columns from the compiled backend, then asserts they enumerate the same elements: the element counts must match and the key column must be identical at every position. A mismatch is a hard error (a compiler bug), never a silent mis-join.
3. Additivity. key/meta/id/role never change what is drawn. A render with no keys is identical to the same scene without the machinery, on every backend.
4. Stable id join key. A grob’s id surfaces as data-vellum-id in the SVG and is the join key vellumplot records in its provenance table, so a widget can map an SVG node to the grammar record that produced it.

For contributors

If you change any of the following, update this article and the contract tests in the same commit, and expect to co-release vellumplot and vellumwidget:

• the elements/panels column set or types,
• the mark vocabulary,
• which marks are keyable, or the batched-vs-single-shape rule,
• the SVG attribute names, or when they are emitted,
• the reserved meta key vocabulary. ```