Types - Document#

type AreaUnit
// = "mm2" | "cm2" | "m2" | "in2" | "ft2"

type Argument
// = {
    key: string;
    /** ALWAYS an expression string — an object-shaped VALUE (e.g.
     *  placeComponent's `args` override) is authored as expression-string
     *  SYNTAX like `"{ width: 500 }"`, never a raw JS object. Empty is allowed
     *  (file parameter with no file selected); validity is enforced by
     *  validateExpressions(). */
    input: string;
    label?: string;
    /** Constraint fields — parameter args (numeric methods) only; ignored elsewhere. */
    min?: string;
    max?: string;
    step?: string;
    options?: Option[];
}

type Chain
// = {
    key: string;
    label?: string;
    parameters?: (Operation | Container)[];
    operations: (Operation | Container)[];
}

type Component
// = {
    key: string;
    /** Editor-chrome display name (not printed on the artifact — see
     *  model's title-vs-label law). */
    label?: string;
    /** Chain-level flat declaration — with `ModelJSON.flat` and the "flat"
     *  LANE, one of the only three ways 2D context is established. When true,
     *  the whole `operations` body runs under the flat contract (vocabulary
     *  gate + z=0 point args + force-flatten). Empty `operations` is valid.
     *  `opening` under flat is meaningless (validate warning). */
    flat?: boolean;
    /** This component's own input arguments — a function signature. Evaluated
     *  in an ISOLATED scope (never sees the host model's `parameters[]`); a
     *  placement's `args` overrides these by key, so the SAME component
     *  placed twice can render differently. Value methods only
     *  (length/number/…). */
    parameters?: (Operation | Container)[];
    /** The component's own body — an entity-streaming chain. Lane "component"
     *  when undeclared; when `flat: true`, the whole body is flat-enforced.
     *  Undeclared content falls back to INFERRED isFlat (bbox z-extent). */
    operations: (Entities | Container)[];
    /**
     * Baked static geometry (import/AI) — plain Entity[], never an
     * expression. Spliced by placeComponent alongside evaluated `operations`.
     * A component may have baked content, authored content, or both; only
     * `entities` (empty operations) is a valid imported asset.
     */
    entities?: unknown[];
    /** Optional cut volumes — evaluated in the SAME isolated scope + `args`,
     *  with the SAME placement transform (`at`/`rotate`/`scale`) as the body.
     *  THE OPENING LAW (cut-at-placement): in an ordinary 3D chain, each
     *  `placeComponent` step SUBTRACTS these (closed solid) volumes from the
     *  stream entities PRESENT BEFORE that step in that SAME chain (a wall
     *  placed earlier gets a doorway cut through it; a wall placed AFTER is
     *  unaffected — "what is behind does not know"). The opening volumes themselves
     *  never render and never flow downstream — they exist only to cut.
     *  Ignored entirely in a FLAT placement context (no volume to cut there).
     *  Meaningless when `flat: true` (validate warning). */
    opening?: (Entities | Container)[];
    /** Rig chains scoped to this component (joint trees) — materialize per
     *  placement. One skeleton chain: nested `joint` nodes fold to
     *  flat Skeleton (DFS pre-order); key = sole identity
     *  (skin.skeleton / track.skeleton). See ModelJSON.skeletons. */
    skeletons?: Chain[];
    /** Animation chains scoped to this component — track nodes fold to
     *  AnimationClip + Track exactly like ModelJSON.animations, and
     *  materialize per placement like `skeletons` just above.
     *
     *  This lane USED to be a second animation vocabulary: a baked
     *  interchange record whose track declared its own `target`+`property`,
     *  whose clip stored `duration`/`loop`, whose `values` were flat, and
     *  which admitted CUBICSPLINE — every one of those removed from the
     *  graph model on purpose (a Track carries no target: the CONSUMER holds
     *  the reference; a clip's length is `groupDuration` over its members and
     *  looping belongs to a USE). `skeletons` was unified with the model lane
     *  already; animations now match, so one clip shape exists, not two.
     *  An importer authors track NODES here (the same way it authors joint
     *  nodes for `skeletons`), not a baked record. */
    animations?: Chain[];
}

type Container
// = {
    key?: string;
    label?: string;
    enabled?: string;
    operations: (Entities | Container)[];
}

type Entities
// = {
    key?: string;
    label?: string;
    /** Optional enable expression — falsy = this step is bypassed / emits nothing. */
    enabled?: string;
    /** Method VALIDITY is registry-dependent (which node registries are
     *  loaded) — the schema only checks the string shape; model's
     *  validateModelJSON(json, registry) rejects unknown methods. */
    method: string;
    args?: Argument[];
}

type LaneNode
// = {
    key: string;
    label?: string;
    enabled?: string;
    method: M;
    args?: Argument[];
}

type LengthUnit
// = "mm" | "cm" | "m" | "in" | "ft"

type MassUnit
// = "mg" | "g" | "kg" | "lb" | "oz"

type ModelJSON
// = {
    id?: string;
    /** Schema shape this document was written against — model's
     *  SCHEMA_VERSION at save time. Optional and inert on load (absent =
     *  pre-stamp vintage, sniffed by shape). */
    version?: number;
    /** Content title printed on the artifact (title-vs-label law). */
    title: string;
    /** Chain-level flat declaration — with `Component.flat` and the "flat"
     *  LANE, one of the only three ways 2D context is established (a single
     *  step cannot declare itself flat). The whole `operations` body runs
     *  under the flat contract: FLAT_LANE_METHODS vocabulary gate, point-arg
     *  z=0, created entities force-flattened. Same field as `Component.flat`
     *  — model's `installModel` copies it onto the installed component.
     *  Empty body + flat is trivially valid. */
    flat?: boolean;
    /** Model-level settings — see ModelSettings's doc. Display units live
     *  at `settings.units` (not a top-level field). Same family as `title`:
     *  data the body reads, not a graph node. */
    settings?: ModelSettings;
    /** Material nodes (method `"material"`, expression args for every
     *  Material field). **`name` = the record's identity**, referenced by
     *  name from applyMaterial; **`key` = optional node graph id** (editor
     *  use only, never a lookup key). Resolved: evaluateMaterials() →
     *  Material. */
    materials?: (Operation | Container)[];
    /** Layer nodes (method `"layer"`, expression args name/color/lineWidth/
     *  lineStyle). **`name` = by-name identity** (applyLayer); **`key` =
     *  optional graph id only**. Resolved: evaluateLayers() → Layer. */
    layers?: (Operation | Container)[];
    /** Style nodes (method `"style"`, expression args name/background/
     *  shading/exposure). **`name` = by-name identity**
     *  (viewStyle); **`key` = optional graph id only**. Resolved:
     *  evaluateStyles() → Style. */
    styles?: (Operation | Container)[];
    /** Text style nodes (method `"textStyle"`, expression args name/font/
     *  height/widthFactor/oblique). **`name` = by-name identity** (a `text`
     *  node's `style` arg, and every annotation style's `textStyle`).
     *  Resolved: collectTextStyles() → TextStyle. */
    textStyles?: (Operation | Container)[];
    /** Annotation style nodes (method `"annotationStyle"`, expression args
     *  for arrow/extension geometry and measurement formatting). **`name` =
     *  by-name identity** (a dimension or leader node's `style` arg).
     *  Resolved: collectAnnotationStyles() → AnnotationStyle. A SEPARATE lane
     *  from `textStyles` on purpose — DXF's STYLE vs DIMSTYLE split, so one
     *  text style serves dimensions, notes and leaders alike. */
    annotationStyles?: (Operation | Container)[];
    /** Named camera poses (camera method nodes). A view3d head may reference by key.
     *  NOT product: never in the entity stream. A LUMINAIRE is not a lane node
     *  either — it is an ordinary object in `objects[]` carrying
     *  `EntityBase.emission` (the `lights[]` lane was deleted 2026-08-16, and
     *  the `helpers[]` datum lane the same day — see RETIRED_ROOT_MESSAGES). */
    cameras?: LaneNode<CameraM>[];
    /** Skeleton chains — nested joint nodes fold to flat Skeleton
     *  (DFS pre-order). Key = sole identity (skin.skeleton references it). */
    skeletons?: Chain[];
    /** Animation chains — track nodes fold to AnimationClip
     *  (expression args). Baked import clips stay on Component.animations. */
    animations?: Chain[];
    parameters?: (Operation | Container)[];
    /** Root body — the SET of scene objects (ModelLane role "scene"). Each
     *  entry folds its OWN `operations` from an empty stream; the root is not
     *  itself a chain (SCHEMA 46, see Container / migrateRootObjects). */
    objects?: Container[];
    /** Texture lane: math->image chains in the operations grammar, but a
     *  fully separate stream (image buffers, never entities) with its own
     *  method vocabulary. A material whose `texture` names a texture key
     *  receives the rasterized pixels at evaluate time. Sampling (wrap/
     *  filter/uvSet) rides the chain's builtin params. */
    textures?: Chain[];
    /** Reporting lane: named table chains (Revit-Schedule-like pipelines,
     *  see TableChain's doc). Referenced from any expression via
     *  `Table.get('key')` — never part of the entity graph. */
    tables?: TableChain[];
    /** Named views: CHAIN lane — key + operations of typed heads
     *  (viewPlan/viewSection/viewElevation/view3d) + viewFilter/viewStyle
     *  steps. Family is the head method (VIEW_FAMILY_OF map). Consumed by
     *  resolveSheet/drawingSetToSvg / evaluateView. */
    views?: View[];
    /** Named reusable definitions — 2D or 3D, whichever they evaluate to; see
     *  Component's doc for the full contract (isolated scope, emergent
     *  flatness, placement via `placeComponent`, the `opening` cut-at-
     *  placement law). Placed into root `operations` / another component's
     *  own `operations` (ordinary 3D chain — instanced group placement).
     *  Reaches PAPER only through a views[] entry (a viewDetail head frames
     *  it), never a sheet-level `placeComponent`. */
    components?: Component[];
    /** Sheet set: an ordered construction-drawing set (A-101 GROUND FLOOR
     *  PLAN, A-201 SECTION A-A …). Each sheet's `operations` places its own
     *  views/tables/images by key (see Sheet's own doc) plus
     *  any sheet-local ad hoc flat content; model's
     *  drawingSetToSvg renders one SVG per sheet plus a drawing index. */
    sheets?: Sheet[];
}

type ModelLane
// = "parameters" | "scene" | "component" | "flat"

type ModelSettings
// = {
    units?: UnitConfig;
    activeView?: string;
    cameraTour?: {
        legs: {
            view: string;
            duration: number;
        }[];
    };
    environment?: Environment;
}

type Operation
// = {
    key?: string;
    label?: string;
    /** Optional enable expression — falsy = this node is bypassed / emits nothing. */
    enabled?: string;
    /** Method VALIDITY is registry-dependent (which node registries are
     *  loaded) — the schema only checks the string shape; model's
     *  validateModelJSON(json, registry) rejects unknown methods. */
    method: string;
    args?: Argument[];
    /** Child nodes for CONTAINER methods. Recursive — the same Operation | Container
     *  shape as every other chain. The entity-fold engine never reads this
     *  (a scene[] operation with children silently drops them). */
    children?: (Operation | Container)[];
    /** Numeric parameters only — this parameter's USE of a track: which
     *  `formulaTrack`/`numberTrack` in animations[] drives it (a numeric
     *  parameter is one number over time, so only the two 1-number track
     *  methods may), and on
     *  what terms. Keys are plain, not expressions: the same "just the id, no
     *  evaluation" convention `BlockEntity.definition` / skin's `skeleton`
     *  already use. The terms live here rather than on the track because two
     *  parameters may share one curve and disagree about them — see
     *  {@link AnimationBinding}. */
    animation?: AnimationBinding;
}

type Option
// = {
    label: string;
    /** An expression string (model's exprSchema). */
    input: string;
}

type RawModel
// = Partial<ModelJSON<CameraM>> & { title: string; /** Pre-migration top-level unit — offline tooling only; live docs use settings.units. */ unit?: UnitConfig; }

type Sheet
// = {
    /** Sheet identifier / drawing number, e.g. "A-101". Free-form (NOT
     *  generatorKeySchema) — drawing numbers contain hyphens and must stay
     *  author-facing strings. Unique within the set; also the index row key. */
    key: string;
    /** Sheet title block name, e.g. "GROUND FLOOR PLAN" — CONTENT printed on
     *  the artifact (title-vs-label law). An EXPRESSION (titleValue law):
     *  `"'PLAN LEVEL ' + level"` renders evaluated, a plain name stays
     *  literal. */
    title?: string;
    /** Builtin paper/scale params (paperWidth/paperHeight/scale) + free params. */
    parameters?: (Operation | Container)[];
    /** This sheet's content — lane "flat" (see model's FLAT_LANE_METHODS). A
     *  top-level `viewport` node with no `at` arg auto-tiles into a scaled
     *  row (resolveSheet extracts these before running the rest); every
     *  other node (a positioned `viewport`, `tableEntity`, `imageEntity`,
     *  or ordinary curve/point/annotation content) is
     *  authored in the SAME y-up bottom-left paper-space convention every
     *  other flat context uses, flipped once into sheet space at resolve
     *  time.
     *
     *  Required, like every other chain's body. A sheet with no operations is
     *  a blank page — frame, zone grid and title block and nothing else —
     *  which is a legal (if empty) drawing, and it is spelled `[]`;
     *  `undefined` was a second spelling of the same nothing (the zod schema
     *  defaults it, so a document that omits the field still loads). */
    operations: (Operation | Container)[];
}

type TableChain
// = {
    key: string;
    label?: string;
    /** HEADER — one `column` node per column (key on the node). */
    columns?: (Operation | Container)[];
    /** BODY — `row` producers + verb transforms (tableFilter/Group/Sort/…). */
    operations: (Operation | Container)[];
}

type UnitConfig
// = {
    length: LengthUnit;
    area?: AreaUnit;
    volume?: VolumeUnit;
    mass?: MassUnit;
}

type View
// = {
    key: string;
    label?: string;
    operations: (Operation | Container)[];
}

type VolumeUnit
// = "mm3" | "cm3" | "m3" | "in3" | "ft3" | "L"