V2 compilation contract¶

The compiler retains the existing geometry, shaping, layout and routing code. Its new responsibility is evaluating live definitions consistently.

1. Dependency resolution. Specs hold snapshotted literal arguments and explicit live references. Dataset revisions and file content hashes invalidate dependent recipes. Cycles fail before recursive rendering.
2. Measurement. Factories execute under a context-local theme. Text is shaped at its final physical size. Plots are measured with axes, keys, annotations, insets and titles.
3. Track allocation. Contiguous span constraints use prefix-sum longest paths for an exact minimum-size feasibility bound. Dykstra projections find a feasible allocation close to the requested track weights. This allows overlapping spans in different rows to share a constrained middle track.
4. Plot fitting. Measured furniture margins are shared across compatible rows and columns. Plots rebuild at the remaining data-region size. Margins grow monotonically to prevent tick-selection oscillations; convergence is checked within 0.005 mm, with a bounded number of passes.
5. Placement and routing. Each cell receives an independent copy of its drawing. Named connections route after placements settle. Final node IDs follow semantic cell names and tree positions rather than allocation order.
6. Paint and validation. Inherited paint becomes explicit in one resolved tree consumed by SVG and PDF. Transforms, clipping and opacity groups remain structural. Diagnostics run on this same tree. A compiled snapshot owns its resolved page, cell map, diagnostics, provenance and build statistics.

Caches are document-local and bounded to 512 recipe/dimension/theme entries. Author functions must be deterministic and must declare changing inputs as arguments. Direct mutation inside arbitrary closure state is outside the cache contract. File references are explicit so compiling a document does not scan unrelated directories.

Legacy drawings remain fixed geometry. A live legacy Panel invalidates a document when its built drawing changes, but its old drawing instructions are not recovered or resized. Use PlotSpec to make scales and furniture responsive.

Implementation ownership¶

plot/panel.py owns plot authoring and invalidation. Matrix validation, sample geometry and vector/raster selection live in plot/matrix.py; these functions build drawings without holding a panel. plot/furniture.py owns the plot-origin and legend-placement helpers shared by panels, polar plots and facets. Drawing, layout and plotting use the same core union_bounds() helper for unions of non-empty diagram bounds.

plot/series.py owns named-series colour selection and appearance records. Palette slots follow first appearance, including records without a colour; selection scans the shared records so twin axes and later colour declarations remain visible. plot/metadata.py leaves diagnostic notes on plot nodes; plot/scale.py owns scale mapping and ticks. Metadata uses the scale's declared domain without depending on concrete scale classes.

plot/statistics.py owns quantiles, box summaries, histogram binning and kernel densities; plot/marks.py consumes those results to draw marks. Box quartiles and bandwidth estimation each share one sorted sample. Histogram lookup uses binary search on increasing edges, retaining the legacy scan for NaN edges. Violin extents and densities share the same computed bandwidth.

Paint resolution shares immutable inherited styles between siblings. Group opacity stays on its own node and is removed from child inheritance once per group, so sharing styles preserves compositing behavior.

document/compiler.py owns live definitions, dependency caching and compilation orchestration. document/tracks.py allocates tracks; document/layout.py takes an explicit layout request through natural measurement, bounded margin fitting, placement and routing. Its result contains the content, cell boxes, handles, page height and fitting-pass count. The allocation algorithms and numerical tolerances above also apply to nested documents.

document/compiled.py owns the completed drawing, read-only placement mapping, render scene and paper colour. It exports without constructing or changing an authoring Figure. render/page.py shares page export settings and format dispatch between authored figures and compiled documents, retaining their different default text modes.

Scene compilation captures font fingerprints once for the snapshot. RenderScene.font_manifest() returns a fresh metadata inventory from those fingerprints without reading the files again. Export still checks fonts before and after rendering. Document metadata uses this captured inventory too.

The CLI uses fresh processes for watched builds, including imported helper code. Only successful exports replace existing bundle files. The local server reports build errors separately from the last successful figure.