Struct Document 

pub struct Document {

    pub version: u32,
    pub colorspace: Option<String>,
    pub doc_id: Option<String>,
    pub mirror_margins: Option<bool>,
    pub page_progression: Option<String>,
    pub page_parity_start: Option<String>,
    pub facing_pages: Option<bool>,
    pub spread_gutter: Option<Dimension>,
    pub margin_inner: Option<Dimension>,
    pub margin_outer: Option<Dimension>,
    pub margin_top: Option<Dimension>,
    pub margin_bottom: Option<Dimension>,
    pub project: Option<Project>,
    pub assets: AssetBlock,
    pub libraries: Vec<LibraryDef>,
    pub actions: Vec<ActionDef>,
    pub tokens: TokenBlock,
    pub styles: StyleBlock,
    pub components: Vec<ComponentDef>,
    pub masters: Vec<MasterDef>,
    pub sections: Vec<SectionDef>,
    pub provenance: Vec<ProvenanceDef>,
    pub variants: Vec<VariantDef>,
    pub recipes: Vec<RecipeDef>,
    pub diagnostic_policy: DiagnosticPolicy,
    pub brand_contract: BrandContract,
    pub body: DocumentBody,
}

The root zenith node — the complete parsed .zen document.

Fields

version: u32

Must be 1 in v0.

colorspace: Option<String>

Declared export color space: Some("srgb") (default) or Some("cmyk"). None when the author omitted the colorspace attribute. In v0 this is informational export metadata only — it does NOT change PNG output (the PNG is always sRGB); a future PDF backend consults it. An invalid value is preserved here verbatim and surfaced as a validation warning.

doc_id: Option<String>

Stable document identity: an optional ULID minted at document creation, stored verbatim as a Crockford base-32 string (no special characters, no escaping). None when the author omitted doc-id. This is pure metadata — render and compile code must not read it.

mirror_margins: Option<bool>

Mirrored book margins toggle. Some(true) → page margins mirror by page parity (recto = odd 1-based page → inner margin on LEFT; verso = even → inner margin on RIGHT). Some(false) or None (default) → margins are uniform (inner = left, outer = right on every page). This only affects how Page::margin_inner/Page::margin_outer are interpreted by the margin.violation validation advisory; it is metadata, not layout.

page_progression: Option<String>

Declared page progression for export: Some("ltr") (default) or Some("rtl") (right-to-left book page order). None when the author omitted the attribute. v0: metadata for export (e.g. a PDF /ViewerPreferences /Direction /R2L); it does NOT change page render order or PNG output. An invalid value is preserved verbatim and surfaced as a validation warning.

page_parity_start: Option<String>

Declared STARTING parity for page 1: Some("recto") (default behavior) or Some("verso") (page 1 is a verso, shifting the whole recto/verso sequence by one). None when the author omitted the attribute — page 1 is then a recto, exactly as before. An invalid value is preserved verbatim and surfaced as a validation warning (document.invalid_page_parity_start); it then falls through to the default (page 1 = recto). This drives the mirrored-margin binding side and the master/field running-head recto/verso selection via Document::page_is_recto.

facing_pages: Option<bool>

When true, the document is designed as facing-page spreads (recto/verso pairs viewed together). Informational metadata; pages still render independently. Parsed from facing-pages=#true on the document node.

spread_gutter: Option<Dimension>

The gutter (gap) between the two pages of a spread composite, e.g. spread-gutter=(px)40. Used by the --spread render path. None = no gap.

margin_inner: Option<Dimension>

Document-level DEFAULT book live-area inner (gutter/binding) margin. When a Page omits its own Page::margin_inner, it inherits this value. None (default) → no document default; the page’s own value (possibly None) is used verbatim, so a document with no margins is byte-identical to before this attribute existed. Same KDL syntax as on a page (margin-inner=(px)225). See Document::effective_margins.

margin_outer: Option<Dimension>

Document-level DEFAULT book live-area outer (fore-edge) margin. Cascades to a page that omits Page::margin_outer. See Document::margin_inner.

margin_top: Option<Dimension>

Document-level DEFAULT book live-area top margin. Cascades to a page that omits Page::margin_top. See Document::margin_inner.

margin_bottom: Option<Dimension>

Document-level DEFAULT book live-area bottom margin. Cascades to a page that omits Page::margin_bottom. See Document::margin_inner.

project: Option<Project>

assets: AssetBlock

Asset declarations; empty when the assets block is absent.

libraries: Vec<LibraryDef>

Imported-package manifest; empty when the libraries block is absent. Each entry declares an external library dependency (id/version/hash). The engine preserves and validates these but does not fetch package content.

actions: Vec<ActionDef>

Action declarations; empty when the actions block is absent. Each entry declares a named transaction script (id/label/version/tx_json). The engine round-trips the tx payload verbatim without parsing it.

tokens: TokenBlock

styles: StyleBlock

components: Vec<ComponentDef>

Reusable component definitions; empty when the components block is absent. Instanced via Node::Instance.

masters: Vec<MasterDef>

Reusable master-page definitions; empty when the masters block is absent. Projected onto pages via Page::master.

sections: Vec<SectionDef>

Section label ranges; empty when the sections block is absent. Each entry labels a contiguous run of pages starting at SectionDef::start_page and running to the next section’s start page (or document end). Sections do NOT contain pages; they are metadata ranges over the flat page list, analogous to PDF PageLabels. Declaration order is preserved; range computation (sorting by page index) is deferred to the field-resolution unit.

provenance: Vec<ProvenanceDef>

Per-node origin records; empty when the provenance block is absent. Each entry records where a document node came from: the node id it describes, the declared library/package it originated from, the optional item name, and an optional link state. Both the node id and the library id are cross-validated against the document (the node must exist; the library must be declared in the libraries block). Declaration order is preserved. This is metadata about nodes — the engine round-trips and validates it but does not act on the link state.

variants: Vec<VariantDef>

Variant declarations; empty when the variants block is absent. Each entry declares a named size/override variant derived from a source page (id, source, w, h, optional override children). Core round-trips and validates these records; variant generation is performed by the CLI engine (zenith variant).

recipes: Vec<RecipeDef>

Recipe declarations; empty when the recipes block is absent. Each entry declares a named generative recipe (id, kind, optional seed/generator/bounds/detached, optional param/palette/ expanded children). The engine round-trips and validates these records but does NOT act on them; expansion is a later unit.

diagnostic_policy: DiagnosticPolicy

Document-level diagnostic policy parsed from the root diagnostics { … } block; empty (the default) when the block is absent. The policy adjusts how specific diagnostic codes are reported during validation (allow / deny / warn, with Error severity immutable). It is consulted ONLY in crate::validate() — the scene compiler and render path never read it, so it can never change rendered output. An empty policy is an identity pass, so a document with no diagnostics block validates and round-trips byte-identically to before this field existed.

brand_contract: BrandContract

Brand contract parsed from the root brand { … } block; empty (the default) when the block is absent. Declares approved colors, font families, and font weights. The validator emits brand.* Warning diagnostics when a resolved token’s value is off-contract. An empty (default) contract is an identity pass — a document with no brand block validates and round-trips byte-identically to before this field existed.

body: DocumentBody

Implementations

impl Document

pub fn page_is_recto(&self, page: &Page, page_index_1based: usize) -> bool

True when the given page (at its 1-based position in document order) is a recto (right-hand) page; false for a verso (left-hand) page. This is the SINGLE source of truth for page parity across the workspace (mirrored margins + master/field running-head selection).

Precedence (highest first):

1. An explicit per-page Page::parity override ("recto"/"verso"). Any value other than "verso" (case-insensitive) — including an invalid one — is treated as recto, matching the validator’s forward-compatible warning behavior.
2. The document Document::page_parity_start offset: "verso" (case-insensitive) makes page 1 a verso and shifts the whole sequence by one; any other / absent value keeps the default.
3. Default: page 1 is a recto — page_index_1based % 2 == 1, exactly the pre-feature behavior. With no parity attributes this returns index % 2 == 1 byte-identically.

Pure and deterministic.

pub fn effective_margins( &self, page: &Page, ) -> (Option<Dimension>, Option<Dimension>, Option<Dimension>, Option<Dimension>)

The page’s EFFECTIVE book live-area margins, as (inner, outer, top, bottom): each side is the page’s own value when set, else the document-level default (Document::margin_inner etc.). This is the SINGLE source of truth for the document→page margin cascade; every live-area / margin computation reads margins through here so per-page overrides and document defaults resolve identically everywhere.

With no document margins set, this returns exactly the page’s own values (including None), so the default-off path is byte-identical to reading page.margin_* directly. Pure and deterministic.

Trait Implementations

impl Clone for Document

fn clone(&self) -> Document

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Document

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Document

fn eq(&self, other: &Document) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Document