Overview

What is an Element?

Every visual entity on the 2D canvas whether it is a simple geometric line, a rich text note, a spatial spreadsheet table, a 3D CAD model, an embedded PDF document, an artboard frame, or a reusable block instance is represented as an Element.

---

The Universal Element Foundation

All elements inherit a core set of base spatial, structural, and identity properties (_DucElementBase):

1. Spatial Identity & Placement

• id: Unique string identifier for the element.
• x, y: Spatial origin coordinates (PrecisionValue), stored normalized to the meter (NEUTRAL_SCOPE = "m").
• width, height: Physical bounding dimensions (PrecisionValue).
• angle: Rotation angle in radians.
• scope: The measurement unit scope (mm, cm, m, in, ft, mi) in which the element was created.

2. Visibility & Layering

• isVisible: Boolean flag determining viewport visibility.
• isDeleted: Soft-deletion flag preserving historical undo/redo and DAG version control.
• zIndex: Explicit stacking order determining which elements render on top.
• layerId: Reference to the drawing layer the element belongs to.
• frameId: Reference to the parent artboard frame container, if enclosed within one.

3. Structural Relationships & Grouping

• groupIds: Ordered array of parent group IDs, supporting nested selection and manipulation.
• regionIds: List of boolean operation region boundaries the element participates in.
• blockIds: Populated if this element helps define a master Block definition.
• instanceId: Populated if this element belongs to a live Block Instance on the canvas.

4. Concurrency & Reconciliation

• version: Integer incremented on each state change, used for real-time collaboration reconciliation.
• versionNonce: Deterministic random seed regenerated per edit to resolve identical version collisions in multi-user sessions.

---

Catalog of Element Types

.duc categorizes elements into distinct functional groups:

1. Geometric Primitives

• rectangle: Rectangular shapes with configurable corner roundness.
• ellipse: Circles, ellipses, and arc segments.
• polygon: Multi-sided regular or arbitrary closed polygons.
• line: Straight lines and multi-segment polylines.
• freedraw: Freehand vector stroke paths generated by stylus, pen, or mouse input.

2. Typography & Annotation

• text: Rich typography supporting custom font families, font sizes, line spacing, text alignments (left, center, right), and vertical alignments.

3. Structured Data & Documents

• table: Interactive spatial spreadsheets holding tabular data cells, rows, and columns directly on the canvas.
• doc: Embedded typst code document containers for rich project notes and technical specifications that is compiled to a PDF.
• pdf: Vector PDF overlays rendering multi-page document attachments in vector resolution.

4. 3D Models & Procedural Code

• model: Parametric CAD model elements supporting embedded 3D viewer states, camera inspection angles, and procedural code scripts. Can be python code or a reference to an external file containing any of STEP, STL, IFC, DXF and DWG.

5. Media & External Embeds

• image: Raster image asset attachments and SVG vector graphics.
• embeddable: Interactive external web application iframe embeds.

6. Spatial Layout & Output Boundaries

• frame: Artboard containers that visually group, clip, and organize canvas regions.
• plot: Export and print plotting boundaries defining printable page areas.

7. Reusable Block Instances

• instance: A specialized element acting as a live reference instance on the canvas, linked directly to a master Block definition. Explore how elements can be combined into reusable templates in the Blocks page.