VMPrint AST Reference

This document is the reference for the public VMPrint document input format: the JSON/object tree you author and hand to the VMPrint pipeline.

The AST is the canonical public source format. The engine internally normalizes it into a spatial runtime form, but callers work with the AST.

If you want the guided teaching path instead of the full contract, start with the authoring guide:

• Authoring Guide

1. Pipeline Overview

Direct callers usually construct **`DocumentInput`**. The `SemanticDocument` layer is only relevant when using the [draft2final](https://github.com/cosmiciron/draft2final) standalone CLI.

---

## 2. `DocumentInput`

```typescript
interface DocumentInput {
    documentVersion: '1.0' | '1.1';
    layout: LayoutConfig;
    fonts?: FontSources;
    styles: Partial<Record<string, ElementStyle>>;
    elements: Element[];
    header?: PageRegionDefinition;
    footer?: PageRegionDefinition;
    debug?: boolean;
}

3. LayoutConfig

All numeric values are in points unless noted.

interface LayoutConfig {
    pageSize: 'A4' | 'LETTER' | { width: number; height: number };
    orientation?: 'portrait' | 'landscape';
    margins: { top: number; right: number; bottom: number; left: number };
    pageTemplates?: PageTemplate[];
    fontFamily: string;
    fontSize: number;
    lineHeight: number;

    pageBackground?: string;

    headerInsetTop?: number;
    headerInsetBottom?: number;
    footerInsetTop?: number;
    footerInsetBottom?: number;

    pageNumberStart?: number;

    lang?: string;
    direction?: 'ltr' | 'rtl' | 'auto';
    hyphenation?: 'off' | 'auto' | 'soft';
    hyphenateCaps?: boolean;
    hyphenMinWordLength?: number;
    hyphenMinPrefix?: number;
    hyphenMinSuffix?: number;
    justifyEngine?: 'legacy' | 'advanced';
    justifyStrategy?: 'auto' | 'space' | 'inter-character';

    opticalScaling?: {
        enabled?: boolean;
        cjk?: number;
        korean?: number;
        thai?: number;
        devanagari?: number;
        arabic?: number;
        cyrillic?: number;
        latin?: number;
        default?: number;
    };

    storyWrapOpticalUnderhang?: boolean;
    worldPlain?: WorldPlainOptions;
}

interface PageTemplate {
    pageIndex?: number;
    selector?: 'first' | 'odd' | 'even' | 'all';
    pageSize?: 'A4' | 'LETTER' | { width: number; height: number };
    orientation?: 'portrait' | 'landscape';
    margins?: { top: number; right: number; bottom: number; left: number };
}

layout.pageTemplates overrides page geometry for matching pages. Templates are applied in declaration order over the document defaults, so later matches can refine earlier broad selectors. pageIndex is zero-based; selector uses human page parity, so page index 0 is the first odd page. A matching template may override pageSize, orientation, margins, or any combination of those fields. Pages without a matching template keep the document-level layout.

{
  "layout": {
    "pageSize": { "width": 460, "height": 360 },
    "margins": { "top": 32, "right": 32, "bottom": 32, "left": 32 },
    "pageTemplates": [
      {
        "pageIndex": 1,
        "pageSize": { "width": 280, "height": 420 },
        "margins": { "top": 34, "right": 22, "bottom": 34, "left": 22 }
      },
      {
        "pageIndex": 2,
        "pageSize": { "width": 420, "height": 230 },
        "margins": { "top": 20, "right": 44, "bottom": 20, "left": 44 }
      }
    ]
  }
}

The engine resolves template geometry before measuring each page, so available flow width, header/footer regions, debug margins, overlays, and rendered page media boxes all use the active page’s dimensions.

layout.worldPlain

worldPlain defines the document-stage world substrate. When present, root elements inhabit that stage instead of being treated as only sequential flow.

interface WorldPlainOptions {
    style?: Partial<ElementStyle>;
}

worldPlain is authored through layout. Do not author { "type": "world-plain" } directly; the engine may synthesize an internal host wrapper at runtime, but that wrapper is not part of the public AST.

4. Font Sources

interface FontSources {
    regular?: string;
    bold?: string;
    italic?: string;
    bolditalic?: string;
    [key: string]: string | undefined;
}

Values are file paths or embedded data URLs.

5. Element

interface Element {
    type: string;
    content: string;
    children?: Element[];

    image?: EmbeddedImagePayload;
    table?: TableLayoutOptions;

    slots?: StripSlot[];
    columns?: number;
    gutter?: number;
    balance?: boolean;
    zones?: ZoneDefinition[];

    zoneLayout?: ZoneLayoutOptions;
    stripLayout?: StripLayoutOptions;
    dropCap?: DropCapSpec;
    columnSpan?: 'all' | number;
    placement?: StoryLayoutDirective;

    properties?: ElementProperties;
}

Style resolution order: styles[element.type] -> properties.style.

6. ElementProperties

interface ElementProperties {
    style?: Partial<ElementStyle>;

    colSpan?: number;
    rowSpan?: number;

    sourceId?: string;
    linkTarget?: string;
    semanticRole?: string;
    reflowKey?: string;

    keepWithNext?: boolean;
    marginTop?: number;
    marginBottom?: number;

    simulationContinuation?: SimulationContinuationSpec;
    pageOverrides?: {
        header?: PageRegionContent | null;
        footer?: PageRegionContent | null;
    };

    sourceRange?: { lineStart: number; colStart: number; lineEnd: number; colEnd: number };
    sourceSyntax?: string;
    language?: string;
    spatialField?: SpatialFieldDirective;
    zoneField?: SpatialFieldDirective;
}

AST 1.1 keeps properties for overrides, metadata, and cross-cutting controls. Structural payloads live on the element itself.

SpatialFieldDirective

type StoryFloatShape = 'rect' | 'circle';

interface StoryExclusionAssemblyMember {
    x: number;
    y: number;
    w: number;
    h: number;
    shape?: StoryFloatShape;
}

interface StoryExclusionAssembly {
    members: StoryExclusionAssemblyMember[];
}

interface SpatialFieldDirective {
    kind?: 'exclude';
    x?: number;
    y?: number;
    align?: 'left' | 'right' | 'center';
    wrap?: 'around' | 'top-bottom' | 'none';
    gap?: number;
    shape?: StoryFloatShape;
    exclusionAssembly?: StoryExclusionAssembly;
    hidden?: boolean;
}

Hosts decide what the field means:

• story consumes it as wrap/exclusion geometry
• zone-map consumes it as placed spatial presence within a region host
• worldPlain consumes it as world-space presence on the stage declared in layout

7. ElementStyle

All fields are optional. Common fields include:

• typography: fontFamily, fontSize, fontWeight, fontStyle, textAlign, letterSpacing, lineHeight, textIndent, color, opacity
• internationalisation: lang, direction, hyphenation, hyphenateCaps, hyphenMinWordLength, hyphenMinPrefix, hyphenMinSuffix, justifyEngine, justifyStrategy
• box model: marginTop, marginBottom, marginLeft, marginRight, padding*, width, height, backgroundColor, zIndex
• borders: borderWidth, borderColor, borderRadius, borderTopWidth, borderBottomWidth, borderLeftWidth, borderRightWidth, borderTopColor, borderBottomColor, borderLeftColor, borderRightColor
• inline object alignment: verticalAlign, baselineShift, inlineMarginLeft, inlineMarginRight, inlineOpticalInsetTop, inlineOpticalInsetRight, inlineOpticalInsetBottom, inlineOpticalInsetLeft
• pagination control: pageBreakBefore, keepWithNext, allowLineSplit, orphans, widows, overflowPolicy

See engine/src/engine/types.ts for the complete shape.

8. Reserved Structural type Values

All other type strings are user-defined and are used for style lookup.

9. Inline Element Types

10. Image Payload (element.image)

interface EmbeddedImagePayload {
    data: string;
    mimeType?: string;
    fit?: 'contain' | 'fill';
}

Used for both block and inline images.

11. Table Configuration (element.table)

interface TableLayoutOptions {
    headerRows?: number;
    repeatHeader?: boolean;
    columnGap?: number;
    rowGap?: number;
    columns?: TableColumnSizing[];
    cellStyle?: Partial<ElementStyle>;
    headerCellStyle?: Partial<ElementStyle>;
}

TableColumnSizing

interface TableColumnSizing {
    mode?: 'fixed' | 'auto' | 'flex';
    value?: number;
    fr?: number;
    min?: number;
    max?: number;
    basis?: number;
    minContent?: number;
    maxContent?: number;
    grow?: number;
    shrink?: number;
}

11a. Strip (type: "strip")

A strip is a compact one-row horizontal composition band for bylines, folio lines, masthead sub-rows, and similar left/center/right compositions.

{
  "type": "strip",
  "stripLayout": {
    "tracks": [
      { "mode": "flex", "fr": 1 },
      { "mode": "fixed", "value": 32 },
      { "mode": "flex", "fr": 1 }
    ],
    "gap": 8
  },
  "slots": [
    { "id": "left", "elements": [{ "type": "folio-left", "content": "Work Title" }] },
    { "id": "center", "elements": [{ "type": "folio-center", "content": "{pageNumber}" }] },
    { "id": "right", "elements": [{ "type": "folio-right", "content": "Chapter Title" }] }
  ]
}

interface StripLayoutOptions {
    tracks?: TableColumnSizing[];
    gap?: number;
}

interface StripSlot {
    id?: string;
    elements: Element[];
    style?: Record<string, any>;
}

Use strip for lightweight composition, not tabular data.

11b. Zone Map (type: "zone-map")

A zone-map defines independent layout regions inside the current field. The classic strip form is still supported, but zones may also use explicit rectangular region bounds with x, y, width, and optional height.

{
  "type": "zone-map",
  "zoneLayout": {
    "columns": [
      { "mode": "flex", "fr": 2 },
      { "mode": "flex", "fr": 1 }
    ],
    "gap": 16,
    "frameOverflow": "move-whole",
    "worldBehavior": "fixed"
  },
  "properties": {
    "style": {
      "marginTop": 12,
      "marginBottom": 12
    }
  },
  "zones": [
    {
      "id": "main",
      "elements": [
        { "type": "h2", "content": "Main Area" },
        { "type": "p", "content": "Body text in the left zone." }
      ]
    },
    {
      "id": "sidebar",
      "elements": [
        { "type": "sidebar-label", "content": "SIDEBAR" },
        { "type": "sidebar-body", "content": "Sidebar content." }
      ]
    }
  ]
}

interface ZoneLayoutOptions {
    columns?: TableColumnSizing[];
    gap?: number;
    frameOverflow?: 'move-whole' | 'continue';
    worldBehavior?: 'fixed' | 'spanning' | 'expandable';
}

interface ZoneDefinition {
    id?: string;
    elements: Element[];
    style?: Record<string, any>;
}

zones[] entries are region descriptors, not DOM children.

frameOverflow makes the zone field lifecycle explicit:

• move-whole: conservative field behavior; the whole zone-map moves if it does not fit
• continue: opt into paged-field lifecycle, but only authored world behaviors that support continuation currently activate it at runtime

worldBehavior makes the authored world rule explicit:

• fixed: conservative default; the authored region topology is non-expandable
• spanning: the author explicitly defines a multi-map region plan, including how the region crosses later local maps
• expandable: the region may automatically grow into later local maps while preserving authored topology unless later authored rules say otherwise

frameOverflow and worldBehavior are related but not the same thing.

For now:

• omitting frameOverflow keeps the old move-whole behavior
• omitting worldBehavior defaults to fixed
• frameOverflow: "continue" only gains live page-to-page regional continuation when paired with worldBehavior: "expandable"

12. Drop Cap (element.dropCap)

interface DropCapSpec {
    enabled?: boolean;
    lines?: number;
    characters?: number;
    gap?: number;
    characterStyle?: Partial<ElementStyle>;
}

13. Story Placement (element.placement)

Declared on direct children of a story element to float or absolutely position them relative to the story’s content area.

interface StoryLayoutDirective {
    mode: 'float' | 'story-absolute';
    x?: number;
    y?: number;
    align?: 'left' | 'right' | 'center';
    wrap?: 'around' | 'top-bottom' | 'none';
    gap?: number;
}

Any block element can float or use story-absolute if it carries explicit obstacle size through style width and height. Images may omit explicit size and derive it from intrinsic image dimensions.

13b. field-actor

field-actor is the public visible body actor for world/map-style spatial presence. It exists so callers do not need to model a rock, hazard, or creature as image + spatialField.

{
  "type": "field-actor",
  "content": "",
  "properties": {
    "style": {
      "width": 96,
      "height": 72,
      "backgroundColor": "#0f8b8d"
    },
    "spatialField": {
      "kind": "exclude",
      "hidden": false,
      "x": 180,
      "y": 120,
      "exclusionAssembly": {
        "members": [
          { "x": 0, "y": 10, "w": 42, "h": 42, "shape": "circle" },
          { "x": 28, "y": 18, "w": 46, "h": 18, "shape": "rect" },
          { "x": 54, "y": 0, "w": 42, "h": 42, "shape": "circle" }
        ]
      }
    }
  }
}

field-actor must declare properties.style.width and properties.style.height.

13c. Column Span (element.columnSpan)

Declared on children of a multi-column story. A spanned element breaks the column flow, is laid out at full story width, then flow resumes below.

columnSpan?: 'all' | number

14. Simulation Continuation (properties.simulationContinuation)

Controls marker elements inserted automatically around page splits.

15. Page Regions

interface PageRegionDefinition {
    default?: PageRegionContent | null;
    firstPage?: PageRegionContent | null;
    odd?: PageRegionContent | null;
    even?: PageRegionContent | null;
}

interface PageRegionContent {
    elements: Element[];
    style?: Partial<ElementStyle>;
}

"{pageNumber}", "{physicalPageNumber}", and "{totalPages}" tokens inside content are substituted during finalization.

16. Nesting Rules

17. Minimal Example

{
  "documentVersion": "1.1",
  "layout": {
    "pageSize": "LETTER",
    "margins": { "top": 72, "right": 72, "bottom": 72, "left": 72 },
    "fontFamily": "Helvetica",
    "fontSize": 12,
    "lineHeight": 1.4
  },
  "styles": {
    "h1": { "fontSize": 24, "fontWeight": "bold", "marginBottom": 12, "keepWithNext": true },
    "paragraph": { "marginBottom": 10, "allowLineSplit": true, "orphans": 2, "widows": 2 }
  },
  "elements": [
    { "type": "h1", "content": "Title" },
    {
      "type": "paragraph",
      "content": "",
      "children": [
        { "type": "text", "content": "Plain text, then " },
        { "type": "text", "content": "bold", "properties": { "style": { "fontWeight": "bold" } } },
        { "type": "text", "content": " and " },
        {
          "type": "inline",
          "content": "",
          "properties": { "style": { "fontStyle": "italic", "color": "#333" } },
          "children": [{ "type": "text", "content": "italic" }]
        },
        { "type": "text", "content": "." }
      ]
    }
  ]
}

Table Example

{
  "type": "table",
  "content": "",
  "table": {
    "headerRows": 1,
    "repeatHeader": true,
    "columns": [
      { "mode": "flex", "fr": 2 },
      { "mode": "flex", "fr": 1 },
      { "mode": "fixed", "value": 60 }
    ]
  },
  "children": [
    {
      "type": "table-row",
      "content": "",
      "properties": { "semanticRole": "header" },
      "children": [
        { "type": "table-cell", "content": "Name" },
        { "type": "table-cell", "content": "Status" },
        { "type": "table-cell", "content": "Score" }
      ]
    }
  ]
}

Story / Float Example

{
  "type": "story",
  "columns": 2,
  "gutter": 18,
  "children": [
    {
      "type": "image",
      "content": "",
      "image": { "data": "<base64>", "mimeType": "image/png", "fit": "contain" },
      "properties": {
        "layout": { "mode": "float", "align": "right", "wrap": "around", "gap": 8 },
        "style": { "width": 120, "height": 90 }
      }
    },
    { "type": "paragraph", "content": "Text flows around the floated image." }
  ]
}

18. Key Source Files