---
title: "types · types"
url: https://developers.dagio.ai/reference/types-types/
---

# types · types

   
                      
                                                                
                             
                  
           
          
   

The following types define named objects and their relationships. Tables include inherited properties. Schema-derived types refer to their validated structures; a TypeScript declaration does not replace the compiler’s semantic checks.

## CanvasLeafNodeKind

Closed native object kinds; rendering libraries do not extend this contract.

```typescript
export type CanvasLeafNodeKind = 'text' | 'rect' | 'ellipse' | 'triangle' | 'line' | 'image';
```

```typescript
type CanvasLeafNodeKind = "text" | "rect" | "ellipse" | "triangle" | "line" | "image";
```

## CanvasNodeKind

Closed native leaves, containers and attached connections.

```typescript
export type CanvasNodeKind = CanvasLeafNodeKind | 'group' | 'frame' | 'connector';
```

```typescript
type CanvasNodeKind = CanvasLeafNodeKind | "group" | "frame" | "connector";
```

## CanvasStrokeType

Frame stroke styles shared by shapes and text blocks.

```typescript
export type CanvasStrokeType = 'none' | 'solid' | 'dashed' | 'dotted';
```

```typescript
type CanvasStrokeType = "none" | "solid" | "dashed" | "dotted";
```

## CanvasNodeBase

Geometry is expressed in document units, independently of the viewport zoom.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `id` | `string` | **Required.** Stable object identity; do not use its title as an identifier. |
| `x` | `number` | **Required.** Horizontal coordinate in the enclosing content coordinate system. |
| `y` | `number` | **Required.** Vertical coordinate in the enclosing content coordinate system. |
| `width` | `number` | **Required.** Element width in the enclosing contract’s unit. |
| `height` | `number` | **Required.** Element height in the enclosing contract’s unit. |
| `rotation` | `number` | **Required.** Element rotation using the native format’s unit and bounds. |
| `opacity` | `number` | **Required.** Presentation opacity within the admitted range. |
| `locked` | `boolean` | **Required.** Prevents ordinary editing operations on the affected element. |
| `strokeType` | `CanvasStrokeType` | **Required.** Defines stroke Type for this object. Observe the type, variants and bounds in the Options column. |
| `strokeColor` | `string` | **Required.** Stroke color in the native content’s admitted format. |
| `strokeWidth` | `number` | **Required.** Stroke thickness within graphics policy bounds. |
| `parentId` | `string \| null` | **Required.** Defines parent Id for this object. Observe the type, variants and bounds in the Options column. |
| `pinned` | `boolean` | **Required.** Defines pinned for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasNodeBase extends CanvasHierarchy {
  id: string;
  x: number;
  y: number;
  width: number;
  height: number;
  rotation: number;
  opacity: number;
  locked: boolean;
  strokeType: CanvasStrokeType;
  strokeColor: string;
  strokeWidth: number;
}
```

## CanvasTextNode

Text paint, frame stroke and background alpha remain independent values.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `kind` | `"text"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `text` | `string` | **Required.** Defines text for this object. Observe the type, variants and bounds in the Options column. |
| `richText` | `ProseMirrorSurfaceDocument \| undefined` | Optional. Native document grammar owns the retained paragraphs, lists and marks. |
| `fontFamily` | `string` | **Required.** Font family selected from policy-admitted values. |
| `fontSize` | `number` | **Required.** Defines font Size for this object. Observe the type, variants and bounds in the Options column. |
| `fontWeight` | `400 \| 700` | **Required.** Defines font Weight for this object. Observe the type, variants and bounds in the Options column. |
| `fontStyle` | `"normal" \| "italic"` | **Required.** Defines font Style for this object. Observe the type, variants and bounds in the Options column. |
| `underline` | `boolean` | **Required.** Defines underline for this object. Observe the type, variants and bounds in the Options column. |
| `textAlign` | `"left" \| "right" \| "center"` | **Required.** Text alignment within its container. |
| `lineHeight` | `number` | **Required.** Defines line Height for this object. Observe the type, variants and bounds in the Options column. |
| `letterSpacing` | `number` | **Required.** Defines letter Spacing for this object. Observe the type, variants and bounds in the Options column. |
| `textColor` | `string` | **Required.** Defines text Color for this object. Observe the type, variants and bounds in the Options column. |
| `backgroundColor` | `string` | **Required.** Defines background Color for this object. Observe the type, variants and bounds in the Options column. |
| `backgroundOpacity` | `number` | **Required.** Defines background Opacity for this object. Observe the type, variants and bounds in the Options column. |
| `id` | `string` | **Required.** Stable object identity; do not use its title as an identifier. |
| `x` | `number` | **Required.** Horizontal coordinate in the enclosing content coordinate system. |
| `y` | `number` | **Required.** Vertical coordinate in the enclosing content coordinate system. |
| `width` | `number` | **Required.** Element width in the enclosing contract’s unit. |
| `height` | `number` | **Required.** Element height in the enclosing contract’s unit. |
| `rotation` | `number` | **Required.** Element rotation using the native format’s unit and bounds. |
| `opacity` | `number` | **Required.** Presentation opacity within the admitted range. |
| `locked` | `boolean` | **Required.** Prevents ordinary editing operations on the affected element. |
| `strokeType` | `CanvasStrokeType` | **Required.** Defines stroke Type for this object. Observe the type, variants and bounds in the Options column. |
| `strokeColor` | `string` | **Required.** Stroke color in the native content’s admitted format. |
| `strokeWidth` | `number` | **Required.** Stroke thickness within graphics policy bounds. |
| `parentId` | `string \| null` | **Required.** Defines parent Id for this object. Observe the type, variants and bounds in the Options column. |
| `pinned` | `boolean` | **Required.** Defines pinned for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasTextNode extends CanvasNodeBase {
  kind: 'text';
  text: string;
  /** Native document grammar owns the retained paragraphs, lists and marks. */
  richText?: ProseMirrorSurfaceDocument;
  fontFamily: string;
  fontSize: number;
  fontWeight: 400 | 700;
  fontStyle: 'normal' | 'italic';
  underline: boolean;
  textAlign: 'left' | 'center' | 'right';
  lineHeight: number;
  letterSpacing: number;
  textColor: string;
  backgroundColor: string;
  backgroundOpacity: number;
}
```

## CanvasShapeNode

Closed filled primitives; a line uses the same world geometry and frame stroke.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `kind` | `"rect" \| "ellipse" \| "triangle" \| "line"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `fill` | `string` | **Required.** Graphical fill defined by the admitted paint variant. |
| `id` | `string` | **Required.** Stable object identity; do not use its title as an identifier. |
| `x` | `number` | **Required.** Horizontal coordinate in the enclosing content coordinate system. |
| `y` | `number` | **Required.** Vertical coordinate in the enclosing content coordinate system. |
| `width` | `number` | **Required.** Element width in the enclosing contract’s unit. |
| `height` | `number` | **Required.** Element height in the enclosing contract’s unit. |
| `rotation` | `number` | **Required.** Element rotation using the native format’s unit and bounds. |
| `opacity` | `number` | **Required.** Presentation opacity within the admitted range. |
| `locked` | `boolean` | **Required.** Prevents ordinary editing operations on the affected element. |
| `strokeType` | `CanvasStrokeType` | **Required.** Defines stroke Type for this object. Observe the type, variants and bounds in the Options column. |
| `strokeColor` | `string` | **Required.** Stroke color in the native content’s admitted format. |
| `strokeWidth` | `number` | **Required.** Stroke thickness within graphics policy bounds. |
| `parentId` | `string \| null` | **Required.** Defines parent Id for this object. Observe the type, variants and bounds in the Options column. |
| `pinned` | `boolean` | **Required.** Defines pinned for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasShapeNode extends CanvasNodeBase {
  kind: 'rect' | 'ellipse' | 'triangle' | 'line';
  fill: string;
}
```

## CanvasImageNode

Images reference canonical media, never arbitrary URLs or temporary object URLs.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `kind` | `"image"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `mediaId` | `string` | **Required.** Defines media Id for this object. Observe the type, variants and bounds in the Options column. |
| `id` | `string` | **Required.** Stable object identity; do not use its title as an identifier. |
| `x` | `number` | **Required.** Horizontal coordinate in the enclosing content coordinate system. |
| `y` | `number` | **Required.** Vertical coordinate in the enclosing content coordinate system. |
| `width` | `number` | **Required.** Element width in the enclosing contract’s unit. |
| `height` | `number` | **Required.** Element height in the enclosing contract’s unit. |
| `rotation` | `number` | **Required.** Element rotation using the native format’s unit and bounds. |
| `opacity` | `number` | **Required.** Presentation opacity within the admitted range. |
| `locked` | `boolean` | **Required.** Prevents ordinary editing operations on the affected element. |
| `strokeType` | `CanvasStrokeType` | **Required.** Defines stroke Type for this object. Observe the type, variants and bounds in the Options column. |
| `strokeColor` | `string` | **Required.** Stroke color in the native content’s admitted format. |
| `strokeWidth` | `number` | **Required.** Stroke thickness within graphics policy bounds. |
| `parentId` | `string \| null` | **Required.** Defines parent Id for this object. Observe the type, variants and bounds in the Options column. |
| `pinned` | `boolean` | **Required.** Defines pinned for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasImageNode extends CanvasNodeBase {
  kind: 'image';
  mediaId: string;
}
```

## CanvasLeafNode

Native Canvas object union, independent of Surface Canvas serialization.

```typescript
export type CanvasLeafNode = CanvasTextNode | CanvasShapeNode | CanvasImageNode;
```

## CanvasHierarchy

Hierarchy uses local coordinates; no implicit Surface Canvas transform is durable.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `parentId` | `string \| null` | **Required.** Defines parent Id for this object. Observe the type, variants and bounds in the Options column. |
| `pinned` | `boolean` | **Required.** Defines pinned for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasHierarchy {
  parentId: string | null;
  pinned: boolean;
}
```

## CanvasLayout

Closed deterministic layout over canonical measured object dimensions.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `kind` | `"free" \| "row" \| "column" \| "grid"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `gap` | `number` | **Required.** Defines gap for this object. Observe the type, variants and bounds in the Options column. |
| `padding` | `number` | **Required.** Defines padding for this object. Observe the type, variants and bounds in the Options column. |
| `columns` | `number` | **Required.** Ordered columns and their authorized value sources. |
| `align` | `"center" \| "start" \| "end"` | **Required.** Defines align for this object. Observe the type, variants and bounds in the Options column. |
| `sizing` | `"fixed" \| "hug"` | **Required.** Defines sizing for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasLayout {
  kind: 'free' | 'row' | 'column' | 'grid';
  gap: number;
  padding: number;
  columns: number;
  align: 'start' | 'center' | 'end';
  sizing: 'fixed' | 'hug';
}
```

## CanvasContainerNode

A persistent container is an ordinary native object, not a serialized renderer group.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `kind` | `"group" \| "frame"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `name` | `string` | **Required.** Readable name of the element in its presentation context. |
| `fill` | `string` | **Required.** Graphical fill defined by the admitted paint variant. |
| `layout` | `CanvasLayout` | **Required.** Arrangement algorithm or structure configured by variant properties. |
| `id` | `string` | **Required.** Stable object identity; do not use its title as an identifier. |
| `x` | `number` | **Required.** Horizontal coordinate in the enclosing content coordinate system. |
| `y` | `number` | **Required.** Vertical coordinate in the enclosing content coordinate system. |
| `width` | `number` | **Required.** Element width in the enclosing contract’s unit. |
| `height` | `number` | **Required.** Element height in the enclosing contract’s unit. |
| `rotation` | `number` | **Required.** Element rotation using the native format’s unit and bounds. |
| `opacity` | `number` | **Required.** Presentation opacity within the admitted range. |
| `locked` | `boolean` | **Required.** Prevents ordinary editing operations on the affected element. |
| `strokeType` | `CanvasStrokeType` | **Required.** Defines stroke Type for this object. Observe the type, variants and bounds in the Options column. |
| `strokeColor` | `string` | **Required.** Stroke color in the native content’s admitted format. |
| `strokeWidth` | `number` | **Required.** Stroke thickness within graphics policy bounds. |
| `parentId` | `string \| null` | **Required.** Defines parent Id for this object. Observe the type, variants and bounds in the Options column. |
| `pinned` | `boolean` | **Required.** Defines pinned for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasContainerNode extends CanvasNodeBase, CanvasHierarchy {
  kind: 'group' | 'frame';
  name: string;
  fill: string;
  layout: CanvasLayout;
}
```

## CanvasConnectorEndpoint

Exact bounding-box port of a native same-page object, never a fuzzy title/reference.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `nodeId` | `string` | **Required.** Defines node Id for this object. Observe the type, variants and bounds in the Options column. |
| `port` | `"center" \| "north" \| "east" \| "south" \| "west"` | **Required.** Defines port for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasConnectorEndpoint {
  nodeId: string;
  port: 'north' | 'east' | 'south' | 'west' | 'center';
}
```

## CanvasConnectorNode

Attached native connection; its geometry is derived by the shared operation engine.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `kind` | `"connector"` | **Required.** Selects the variant and the properties admitted in this branch. |
| `source` | `CanvasConnectorEndpoint` | **Required.** Defines source for this object. Observe the type, variants and bounds in the Options column. |
| `target` | `CanvasConnectorEndpoint` | **Required.** Defines target for this object. Observe the type, variants and bounds in the Options column. |
| `routing` | `"straight" \| "orthogonal"` | **Required.** Defines routing for this object. Observe the type, variants and bounds in the Options column. |
| `label` | `string` | **Required.** Human-readable label displayed in the interface. |
| `fontFamily` | `string` | **Required.** Font family selected from policy-admitted values. |
| `fontSize` | `number` | **Required.** Defines font Size for this object. Observe the type, variants and bounds in the Options column. |
| `fontWeight` | `400 \| 700` | **Required.** Defines font Weight for this object. Observe the type, variants and bounds in the Options column. |
| `fontStyle` | `"normal" \| "italic"` | **Required.** Defines font Style for this object. Observe the type, variants and bounds in the Options column. |
| `textColor` | `string` | **Required.** Defines text Color for this object. Observe the type, variants and bounds in the Options column. |
| `startArrow` | `"none" \| "arrow"` | **Required.** Defines start Arrow for this object. Observe the type, variants and bounds in the Options column. |
| `endArrow` | `"none" \| "arrow"` | **Required.** Defines end Arrow for this object. Observe the type, variants and bounds in the Options column. |
| `id` | `string` | **Required.** Stable object identity; do not use its title as an identifier. |
| `x` | `number` | **Required.** Horizontal coordinate in the enclosing content coordinate system. |
| `y` | `number` | **Required.** Vertical coordinate in the enclosing content coordinate system. |
| `width` | `number` | **Required.** Element width in the enclosing contract’s unit. |
| `height` | `number` | **Required.** Element height in the enclosing contract’s unit. |
| `rotation` | `number` | **Required.** Element rotation using the native format’s unit and bounds. |
| `opacity` | `number` | **Required.** Presentation opacity within the admitted range. |
| `locked` | `boolean` | **Required.** Prevents ordinary editing operations on the affected element. |
| `strokeType` | `CanvasStrokeType` | **Required.** Defines stroke Type for this object. Observe the type, variants and bounds in the Options column. |
| `strokeColor` | `string` | **Required.** Stroke color in the native content’s admitted format. |
| `strokeWidth` | `number` | **Required.** Stroke thickness within graphics policy bounds. |
| `parentId` | `string \| null` | **Required.** Defines parent Id for this object. Observe the type, variants and bounds in the Options column. |
| `pinned` | `boolean` | **Required.** Defines pinned for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasConnectorNode extends CanvasNodeBase, CanvasHierarchy {
  kind: 'connector';
  source: CanvasConnectorEndpoint;
  target: CanvasConnectorEndpoint;
  routing: 'straight' | 'orthogonal';
  label: string;
  fontFamily: string;
  fontSize: number;
  fontWeight: 400 | 700;
  fontStyle: 'normal' | 'italic';
  textColor: string;
  startArrow: 'none' | 'arrow';
  endArrow: 'none' | 'arrow';
}
```

## CanvasNode

Portable native node union, independent of renderer serialization.

```typescript
export type CanvasNode = CanvasLeafNode | CanvasContainerNode | CanvasConnectorNode;
```

## CanvasPage

Page array order and node array order are canonical back-to-front order.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `id` | `string` | **Required.** Stable object identity; do not use its title as an identifier. |
| `width` | `number` | **Required.** Element width in the enclosing contract’s unit. |
| `height` | `number` | **Required.** Element height in the enclosing contract’s unit. |
| `background` | `string` | **Required.** Defines background for this object. Observe the type, variants and bounds in the Options column. |
| `nodes` | `CanvasNode[]` | **Required.** Defines nodes for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasPage {
  id: string;
  width: number;
  height: number;
  background: string;
  nodes: CanvasNode[];
}
```

## CanvasDocument

Complete canonical content accepted by every Surface host and server.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `type` | `"surface_canvas"` | **Required.** Defines type for this object. Observe the type, variants and bounds in the Options column. |
| `schema_version` | `6` | **Required.** Defines schema_version for this object. Observe the type, variants and bounds in the Options column. |
| `mode` | `"pages" \| "whiteboard"` | **Required.** Defines mode for this object. Observe the type, variants and bounds in the Options column. |
| `pages` | `CanvasPage[]` | **Required.** Canvas or relevant document pages with stable identities. |
| `resourceKind` | `"scene" \| "component" \| "library"` | **Required.** Defines resource Kind for this object. Observe the type, variants and bounds in the Options column. |
| `componentDefinition` | `CanvasComponentDefinition \| null` | **Required.** Defines component Definition for this object. Observe the type, variants and bounds in the Options column. |
| `libraryDefinition` | `CanvasLibraryDefinition \| null` | **Required.** Defines library Definition for this object. Observe the type, variants and bounds in the Options column. |
| `instances` | `CanvasComponentInstance[]` | **Required.** Defines instances for this object. Observe the type, variants and bounds in the Options column. |
| `assets` | `CanvasAssetBinding[]` | **Required.** Each image address binds one immutable authorized Asset Revision. |
| `sourceRegions` | `CanvasSourceRegion[]` | **Required.** Defines source Regions for this object. Observe the type, variants and bounds in the Options column. |
| `dataObjects` | `CanvasDataObject[]` | **Required.** Defines data Objects for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasDocument {
  type: 'surface_canvas';
  schema_version: 6;
  mode: 'pages' | 'whiteboard';
  pages: CanvasPage[];
  resourceKind: 'scene' | 'component' | 'library';
  componentDefinition: CanvasComponentDefinition | null;
  libraryDefinition: CanvasLibraryDefinition | null;
  instances: CanvasComponentInstance[];
  /** Each image address binds one immutable authorized Asset Revision. */
  assets: CanvasAssetBinding[];
  sourceRegions: CanvasSourceRegion[];
  dataObjects: CanvasDataObject[];
}
```

## CanvasSourceRegionPreview

Read-only preparation completes a draft without mutating the saved destination subtree.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `contract` | `"SurfaceCanvasDerivedRegionPreview@1"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `surfaceId` | `string` | **Required.** Defines surface Id for this object. Observe the type, variants and bounds in the Options column. |
| `revisionId` | `string` | **Required.** Defines revision Id for this object. Observe the type, variants and bounds in the Options column. |
| `version` | `number` | **Required.** Declared content or publication version identifying the applicable interpretation. |
| `graphWatermark` | `number` | **Required.** Defines graph Watermark for this object. Observe the type, variants and bounds in the Options column. |
| `region` | `CanvasSourceRegion` | **Required.** Defines region for this object. Observe the type, variants and bounds in the Options column. |
| `querySelection` | `{ readonly complete: true; readonly sources: readonly SurfaceRevisionReference[]; } \| null` | **Required.** Defines query Selection for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasSourceRegionPreview {
  readonly contract: 'SurfaceCanvasDerivedRegionPreview@1';
  readonly surfaceId: string;
  readonly revisionId: string;
  readonly version: number;
  readonly graphWatermark: number;
  readonly region: CanvasSourceRegion;
  readonly querySelection: {
    readonly complete: true;
    readonly sources: readonly SurfaceRevisionReference[];
  } | null;
}
```

## CanvasSourceObservation

Freshness observes native heads and snapshots, never an inferred deletion or automatic pin replacement.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `contract` | `"SurfaceCanvasDerivedSourcesObservation@1"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `surfaceId` | `string` | **Required.** Defines surface Id for this object. Observe the type, variants and bounds in the Options column. |
| `revisionId` | `string` | **Required.** Defines revision Id for this object. Observe the type, variants and bounds in the Options column. |
| `version` | `number` | **Required.** Declared content or publication version identifying the applicable interpretation. |
| `graphWatermark` | `number` | **Required.** Defines graph Watermark for this object. Observe the type, variants and bounds in the Options column. |
| `regions` | `readonly { readonly key: string; readonly citations: readonly { readonly reference: SurfaceRevisionReference; readonly anchorId: string \| null; readonly currentRevisionId: string; readonly state: "same-head" \| "head-advanced"; }[]; readonly querySnapshot: "none" \| "same-graph" \| "graph-advanced"; }[]` | **Required.** Defines regions for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasSourceObservation {
  readonly contract: 'SurfaceCanvasDerivedSourcesObservation@1';
  readonly surfaceId: string;
  readonly revisionId: string;
  readonly version: number;
  readonly graphWatermark: number;
  readonly regions: readonly {
    readonly key: string;
    readonly citations: readonly {
      readonly reference: SurfaceRevisionReference;
      readonly anchorId: string | null;
      readonly currentRevisionId: string;
      readonly state: 'same-head' | 'head-advanced';
    }[];
    readonly querySnapshot: 'none' | 'same-graph' | 'graph-advanced';
  }[];
}
```

## CanvasPolicy

Model-owned editing policy; font names are references to qualified client assets.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `contract` | `"CanvasPolicy@7"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `objects` | `CanvasNodeKind[]` | **Required.** Native page objects with types, identities and geometry. |
| `fontFamilies` | `string[]` | **Required.** Defines font Families for this object. Observe the type, variants and bounds in the Options column. |
| `minimumPages` | `number` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `maximumPages` | `number` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `pageOperations` | `("delete" \| "add" \| "move" \| "duplicate" \| "insert")[]` | **Required.** Defines page Operations for this object. Observe the type, variants and bounds in the Options column. |
| `objectOrderOperations` | `("bring-forward" \| "send-backward" \| "bring-to-front" \| "send-to-back")[]` | **Required.** Defines object Order Operations for this object. Observe the type, variants and bounds in the Options column. |
| `textPaintProperties` | `("text-color" \| "text-background-color" \| "text-background-opacity")[]` | **Required.** Defines text Paint Properties for this object. Observe the type, variants and bounds in the Options column. |
| `borderStyles` | `CanvasStrokeType[]` | **Required.** Defines border Styles for this object. Observe the type, variants and bounds in the Options column. |
| `borderWeightRange` | `{ minimum: number; maximum: number; }` | **Required.** Defines border Weight Range for this object. Observe the type, variants and bounds in the Options column. |
| `protectedNodeIds` | `string[]` | **Required.** Defines protected Node Ids for this object. Observe the type, variants and bounds in the Options column. |
| `protectedPageIds` | `string[]` | **Required.** Defines protected Page Ids for this object. Observe the type, variants and bounds in the Options column. |
| `hierarchyOperations` | `("group" \| "ungroup" \| "reparent")[]` | **Required.** Defines hierarchy Operations for this object. Observe the type, variants and bounds in the Options column. |
| `layouts` | `("free" \| "row" \| "column" \| "grid")[]` | **Required.** Defines layouts for this object. Observe the type, variants and bounds in the Options column. |
| `maximumDepth` | `number` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `modes` | `("pages" \| "whiteboard")[]` | **Required.** Defines modes for this object. Observe the type, variants and bounds in the Options column. |
| `connectorRoutings` | `("straight" \| "orthogonal")[]` | **Required.** Defines connector Routings for this object. Observe the type, variants and bounds in the Options column. |
| `resourceKind` | `"scene" \| "component" \| "library"` | **Required.** Defines resource Kind for this object. Observe the type, variants and bounds in the Options column. |
| `componentOperations` | `("define" \| "library-edit" \| "instance-create" \| "instance-update" \| "instance-edit" \| "instance-detach")[]` | **Required.** Defines component Operations for this object. Observe the type, variants and bounds in the Options column. |
| `componentSources` | `CanvasComponentSourcePolicy[]` | **Required.** Defines component Sources for this object. Observe the type, variants and bounds in the Options column. |
| `maximumInstances` | `number` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `assetSources` | `{ modelId: string; assetDefinitionPaths: string[]; }[]` | **Required.** Defines asset Sources for this object. Observe the type, variants and bounds in the Options column. |
| `maximumAssets` | `number` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `fontCatalogue` | `CanvasFontCatalogueReference` | **Required.** Defines font Catalogue for this object. Observe the type, variants and bounds in the Options column. |
| `maximumComponentDepth` | `number` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `maximumComponentDependencies` | `number` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `visualData` | `{ kinds: ("table" \| "chart")[]; modes: ("snapshot" \| "live")[]; operations: ("create" \| "configure" \| "refresh" \| "remove")[]; maximumObjects: number; maximumRows: number; maximumColumns: number; } \| undefined` | Optional. Absence denies semantic visual data; this declaration grants neither source access nor Field writes. |
| `derivedSources` | `{ operations: ("bind" \| "refresh" \| "remove")[]; maximumRegions: number; } \| undefined` | Optional. Absence grants no source-region operation; ordinary Source8 and DataProtection checks still apply. |
| `export` | `{ formats: ("png" \| "jpeg" \| "svg" \| "pdf")[]; maxPages: number; maxPixels: number; maxArtifactBytes: number; } \| undefined` | Optional. Export policy for affected content. |

```typescript
export interface CanvasPolicy {
  contract: 'CanvasPolicy@7';
  objects: CanvasNodeKind[];
  fontFamilies: string[];
  minimumPages: number;
  maximumPages: number;
  pageOperations: ('add' | 'duplicate' | 'insert' | 'move' | 'delete')[];
  objectOrderOperations: ('bring-forward' | 'send-backward' | 'bring-to-front' | 'send-to-back')[];
  textPaintProperties: ('text-color' | 'text-background-color' | 'text-background-opacity')[];
  borderStyles: CanvasStrokeType[];
  borderWeightRange: { minimum: number; maximum: number };
  protectedNodeIds: string[];
  protectedPageIds: string[];
  hierarchyOperations: ('group' | 'ungroup' | 'reparent')[];
  layouts: CanvasLayout['kind'][];
  maximumDepth: number;
  modes: ('pages' | 'whiteboard')[];
  connectorRoutings: CanvasConnectorNode['routing'][];
  resourceKind: 'scene' | 'component' | 'library';
  componentOperations: (
    | 'define'
    | 'library-edit'
    | 'instance-create'
    | 'instance-update'
    | 'instance-edit'
    | 'instance-detach'
  )[];
  componentSources: CanvasComponentSourcePolicy[];
  maximumInstances: number;
  assetSources: { modelId: string; assetDefinitionPaths: string[] }[];
  maximumAssets: number;
  fontCatalogue: CanvasFontCatalogueReference;
  maximumComponentDepth: number;
  maximumComponentDependencies: number;
  /** Absence denies semantic visual data; this declaration grants neither source access nor Field writes. */
  visualData?: {
    kinds: ('table' | 'chart')[];
    modes: ('snapshot' | 'live')[];
    operations: ('create' | 'configure' | 'refresh' | 'remove')[];
    maximumObjects: number;
    maximumRows: number;
    maximumColumns: number;
  };
  /** Absence grants no source-region operation; ordinary Source8 and DataProtection checks still apply. */
  derivedSources?: {
    operations: ('bind' | 'refresh' | 'remove')[];
    maximumRegions: number;
  };
  export?: {
    formats: ('png' | 'jpeg' | 'svg' | 'pdf')[];
    maxPages: number;
    maxPixels: number;
    maxArtifactBytes: number;
  };
}
```

## CanvasAssetBinding

A deterministic media address cannot be reassigned to different bytes behind a protected object.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `mediaId` | `string` | **Required.** Defines media Id for this object. Observe the type, variants and bounds in the Options column. |
| `reference` | `SurfaceAssetReference` | **Required.** Defines reference for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasAssetBinding {
  mediaId: string;
  reference: SurfaceAssetReference;
}
```

## CanvasNodePatch

A kind-specific partial update cannot mutate an object's stable identity or kind.

```typescript
export type CanvasNodePatch =
  | Partial<Omit<CanvasTextNode, 'id' | 'kind'>>
  | Partial<Omit<CanvasShapeNode, 'id' | 'kind'>>
  | Partial<Omit<CanvasImageNode, 'id' | 'kind'>>
  | Partial<Omit<CanvasContainerNode, 'id' | 'kind'>>
  | Partial<Omit<CanvasConnectorNode, 'id' | 'kind'>>
  | Partial<CanvasHierarchy>;
```

```typescript
type CanvasNodePatch = Partial<Omit<CanvasTextNode, "kind" | "id">> | Partial<Omit<CanvasShapeNode, "kind" | "id">> | Partial<Omit<CanvasImageNode, "kind" | "id">> | Partial<Omit<CanvasContainerNode, "kind" | "id">> | Partial<Omit<CanvasConnectorNode, "kind" | "id">> | Partial<CanvasHierarchy>;
```

## CanvasOperation

Granular portable operations compiled into the canonical Change Set revision owner.

```typescript
export type CanvasOperation =
  | { kind: 'content.copy'; copy: CanvasContentCopy }
  | { kind: 'document.semantic-order'; sourceRegionKeys: string[]; dataObjectIds: string[] }
  | { kind: 'data.object.set'; expectedObject: CanvasDataObject | null; object: CanvasDataObject }
  | { kind: 'data.object.remove'; expectedObject: CanvasDataObject }
  | {
      kind: 'source.region.replace';
      expectedRegion: CanvasSourceRegion | null;
      region: CanvasSourceRegion;
      expectedNodeIds: string[];
      nodes: CanvasNode[];
    }
  | { kind: 'source.region.remove'; expectedRegion: CanvasSourceRegion; expectedNodeIds: string[] }
  | {
      kind: 'source.region.copy';
      expectedRegion: CanvasSourceRegion;
      nodeMap: Record<string, string>;
      newRegionKey: string;
      targetPageId: string;
      parentId: string | null;
      x: number;
      y: number;
      index: number;
    }
  | { kind: 'asset.reference.add'; binding: CanvasAssetBinding }
  | { kind: 'asset.reference.remove'; mediaId: string }
  | { kind: 'component.define'; definition: CanvasComponentDefinition }
  | { kind: 'library.update'; definition: CanvasLibraryDefinition }
  | {
      kind: 'component.instance.create';
      pageId: string;
      instanceId: string;
      reference: CanvasComponentReference;
      nodeMap: Record<string, string>;
      parameters: Record<string, CanvasComponentValue>;
      variantKey: string | null;
      overrides: Record<string, CanvasNodePatch>;
      x: number;
      y: number;
      index: number;
    }
  | {
      kind: 'component.instance.update';
      instanceId: string;
      expectedReference: CanvasComponentReference;
      reference: CanvasComponentReference;
      nodeMap: Record<string, string>;
      parameters: Record<string, CanvasComponentValue>;
      variantKey: string | null;
      overrides: Record<string, CanvasNodePatch>;
    }
  | { kind: 'component.instance.detach'; instanceId: string }
  | { kind: 'component.instance.remove'; instanceId: string }
  | {
      kind: 'component.zone.replace';
      instanceId: string;
      zoneKey: string;
      expectedReference: CanvasComponentReference;
      expectedNodeIds: string[];
      nodes: CanvasNode[];
    }
  | { kind: 'document.mode'; mode: 'pages' | 'whiteboard' }
  | {
      kind: 'node.reparent';
      pageId: string;
      nodeId: string;
      parentId: string | null;
      index: number;
    }
  | { kind: 'layout.apply'; pageId: string; nodeId: string; layout: CanvasLayout }
  | { kind: 'page.add'; page: CanvasPage; index: number }
  | { kind: 'page.remove'; pageId: string }
  | {
      kind: 'page.update';
      pageId: string;
      patch: Partial<Pick<CanvasPage, 'width' | 'height' | 'background'>>;
    }
  | { kind: 'page.reorder'; pageIds: string[] }
  | { kind: 'node.add'; pageId: string; node: CanvasNode; index: number }
  | { kind: 'node.remove'; pageId: string; nodeId: string }
  | { kind: 'node.update'; pageId: string; nodeId: string; patch: CanvasNodePatch }
  | { kind: 'node.reorder'; pageId: string; nodeIds: string[] };
```

```typescript
type CanvasOperation = { kind: "content.copy"; copy: CanvasContentCopy; } | { kind: "document.semantic-order"; sourceRegionKeys: string[]; dataObjectIds: string[]; } | { kind: "data.object.set"; expectedObject: CanvasDataObject | null; object: CanvasDataObject; } | { kind: "data.object.remove"; expectedObject: CanvasDataObject; } | { kind: "source.region.replace"; expectedRegion: CanvasSourceRegion | null; region: CanvasSourceRegion; expectedNodeIds: string[]; nodes: CanvasNode[]; } | { kind: "source.region.remove"; expectedRegion: CanvasSourceRegion; expectedNodeIds: string[]; } | { kind: "source.region.copy"; expectedRegion: CanvasSourceRegion; nodeMap: Record<string, string>; newRegionKey: string; targetPageId: string; parentId: string | null; x: number; y: number; index: number; } | { kind: "asset.reference.add"; binding: CanvasAssetBinding; } | { kind: "asset.reference.remove"; mediaId: string; } | { kind: "component.define"; definition: CanvasComponentDefinition; } | { kind: "library.update"; definition: CanvasLibraryDefinition; } | { kind: "component.instance.create"; pageId: string; instanceId: string; reference: CanvasComponentReference; nodeMap: Record<string, string>; parameters: Record<string, CanvasComponentValue>; variantKey: string | null; overrides: Record<string, CanvasNodePatch>; x: number; y: number; index: number; } | { kind: "component.instance.update"; instanceId: string; expectedReference: CanvasComponentReference; reference: CanvasComponentReference; nodeMap: Record<string, string>; parameters: Record<string, CanvasComponentValue>; variantKey: string | null; overrides: Record<string, CanvasNodePatch>; } | { kind: "component.instance.detach"; instanceId: string; } | { kind: "component.instance.remove"; instanceId: string; } | { kind: "component.zone.replace"; instanceId: string; zoneKey: string; expectedReference: CanvasComponentReference; expectedNodeIds: string[]; nodes: CanvasNode[]; } | { kind: "document.mode"; mode: "pages" | "whiteboard"; } | { kind: "node.reparent"; pageId: string; nodeId: string; parentId: string | null; index: number; } | { kind: "layout.apply"; pageId: string; nodeId: string; layout: CanvasLayout; } | { kind: "page.add"; page: CanvasPage; index: number; } | { kind: "page.remove"; pageId: string; } | { kind: "page.update"; pageId: string; patch: Partial<Pick<CanvasPage, "width" | "height" | "background">>; } | { kind: "page.reorder"; pageIds: string[]; } | { kind: "node.add"; pageId: string; node: CanvasNode; index: number; } | { kind: "node.remove"; pageId: string; nodeId: string; } | { kind: "node.update"; pageId: string; nodeId: string; patch: CanvasNodePatch; } | { kind: "node.reorder"; pageId: string; nodeIds: string[]; };
```

## CanvasComponentProperty

Only native scalar properties may be exposed; structural identity and protections are never parameters.

```typescript
export type CanvasComponentProperty =
  | 'text'
  | 'label'
  | 'name'
  | 'fill'
  | 'textColor'
  | 'backgroundColor'
  | 'backgroundOpacity'
  | 'strokeColor'
  | 'strokeWidth'
  | 'fontSize'
  | 'fontWeight'
  | 'fontStyle'
  | 'underline'
  | 'textAlign'
  | 'lineHeight'
  | 'letterSpacing'
  | 'opacity'
  | 'x'
  | 'y'
  | 'width'
  | 'height';
```

```typescript
type CanvasComponentProperty = "text" | "label" | "name" | "width" | "fontSize" | "fontWeight" | "fontStyle" | "underline" | "textAlign" | "lineHeight" | "letterSpacing" | "textColor" | "backgroundColor" | "backgroundOpacity" | "x" | "y" | "height" | "opacity" | "strokeColor" | "strokeWidth" | "fill";
```

## CanvasComponentValue

Parameter values are closed native scalars, not expressions, executable bindings or renderer state.

```typescript
export type CanvasComponentValue = string | number | boolean;
```

## CanvasComponentParameter

One typed exposed property may bind several exact native objects in the reusable subtree.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `key` | `string` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `label` | `string` | **Required.** Human-readable label displayed in the interface. |
| `type` | `"number" \| "boolean" \| "text" \| "color"` | **Required.** Defines type for this object. Observe the type, variants and bounds in the Options column. |
| `default` | `CanvasComponentValue` | **Required.** Initial value matching the declared type; does not replace an existing saved value. |
| `minimum` | `number \| null` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `maximum` | `number \| null` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `options` | `CanvasComponentValue[]` | **Required.** Suggested and admitted values for a declared choice. |
| `bindings` | `{ nodeId: string; property: CanvasComponentProperty; }[]` | **Required.** Defines bindings for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasComponentParameter {
  key: string;
  label: string;
  type: 'text' | 'number' | 'boolean' | 'color';
  default: CanvasComponentValue;
  minimum: number | null;
  maximum: number | null;
  options: CanvasComponentValue[];
  bindings: { nodeId: string; property: CanvasComponentProperty }[];
}
```

## CanvasComponentDefinition

Declarative reusable subtree owned by an ordinary versioned Canvas Surface.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `contract` | `"CanvasComponentDefinition@2"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `name` | `string` | **Required.** Readable name of the element in its presentation context. |
| `description` | `string` | **Required.** Explanation of this element’s purpose, content or effect. |
| `pageId` | `string` | **Required.** Defines page Id for this object. Observe the type, variants and bounds in the Options column. |
| `rootNodeId` | `string` | **Required.** Defines root Node Id for this object. Observe the type, variants and bounds in the Options column. |
| `parameters` | `CanvasComponentParameter[]` | **Required.** Named operation or Query parameters and their associated values. |
| `variants` | `{ key: string; label: string; values: Record<string, CanvasComponentValue>; }[]` | **Required.** Defines variants for this object. Observe the type, variants and bounds in the Options column. |
| `zones` | `CanvasComponentZone[]` | **Required.** Defines zones for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasComponentDefinition {
  contract: 'CanvasComponentDefinition@2';
  name: string;
  description: string;
  pageId: string;
  rootNodeId: string;
  parameters: CanvasComponentParameter[];
  variants: { key: string; label: string; values: Record<string, CanvasComponentValue> }[];
  zones: CanvasComponentZone[];
}
```

## CanvasComponentZone

A zone names one disjoint native container, not HTML, renderer objects or a second document.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `key` | `string` | **Required.** Stable semantic identifier used by references; changing it changes identity. |
| `label` | `string` | **Required.** Human-readable label displayed in the interface. |
| `rootNodeId` | `string` | **Required.** Defines root Node Id for this object. Observe the type, variants and bounds in the Options column. |
| `minimumChildren` | `number` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `maximumChildren` | `number` | **Required.** Cardinality or budget bound for the named resource. Exceeding the bound is refused; null denotes no bound only where admitted by the schema. |
| `allowedKinds` | `CanvasNodeKind[]` | **Required.** Defines allowed Kinds for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasComponentZone {
  key: string;
  label: string;
  rootNodeId: string;
  minimumChildren: number;
  maximumChildren: number;
  allowedKinds: CanvasNodeKind[];
}
```

## CanvasLibraryDefinition

A private/shared library is ordinary governed content; its references never confer source access.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `contract` | `"CanvasLibraryDefinition@1"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `name` | `string` | **Required.** Readable name of the element in its presentation context. |
| `description` | `string` | **Required.** Explanation of this element’s purpose, content or effect. |
| `components` | `{ key: string; label: string; description: string; reference: CanvasComponentReference; }[]` | **Required.** Defines components for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasLibraryDefinition {
  contract: 'CanvasLibraryDefinition@1';
  name: string;
  description: string;
  components: {
    key: string;
    label: string;
    description: string;
    reference: CanvasComponentReference;
  }[];
}
```

## CanvasComponentInstance

Version-bound native instance; object mappings preserve existing Anchors during explicit upgrades.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `contract` | `"CanvasComponentInstance@2"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `id` | `string` | **Required.** Stable object identity; do not use its title as an identifier. |
| `pageId` | `string` | **Required.** Defines page Id for this object. Observe the type, variants and bounds in the Options column. |
| `reference` | `CanvasComponentReference` | **Required.** Defines reference for this object. Observe the type, variants and bounds in the Options column. |
| `nodeMap` | `Record<string, string>` | **Required.** Defines node Map for this object. Observe the type, variants and bounds in the Options column. |
| `parameters` | `Record<string, CanvasComponentValue>` | **Required.** Named operation or Query parameters and their associated values. |
| `variantKey` | `string \| null` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `overrides` | `Record<string, CanvasNodePatch>` | **Required.** Defines overrides for this object. Observe the type, variants and bounds in the Options column. |
| `nodeOrigins` | `Record<string, CanvasComponentNodeOrigin>` | **Required.** Defines node Origins for this object. Observe the type, variants and bounds in the Options column. |
| `zoneContainers` | `Record<string, string>` | **Required.** Defines zone Containers for this object. Observe the type, variants and bounds in the Options column. |
| `zones` | `Record<string, string[]>` | **Required.** Defines zones for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasComponentInstance {
  contract: 'CanvasComponentInstance@2';
  id: string;
  pageId: string;
  reference: CanvasComponentReference;
  nodeMap: Record<string, string>;
  parameters: Record<string, CanvasComponentValue>;
  variantKey: string | null;
  overrides: Record<string, CanvasNodePatch>;
  nodeOrigins: Record<string, CanvasComponentNodeOrigin>;
  zoneContainers: Record<string, string>;
  zones: Record<string, string[]>;
}
```

## CanvasComponentNodeOrigin

Every nested node retains its exact defining Revision and complete outer-to-inner ownership chain.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `reference` | `CanvasComponentReference` | **Required.** Defines reference for this object. Observe the type, variants and bounds in the Options column. |
| `sourceNodeId` | `string` | **Required.** Defines source Node Id for this object. Observe the type, variants and bounds in the Options column. |
| `chain` | `CanvasComponentReference[]` | **Required.** Defines chain for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasComponentNodeOrigin {
  reference: CanvasComponentReference;
  sourceNodeId: string;
  chain: CanvasComponentReference[];
}
```

## CanvasContentCopy

An explicit copy intent carries local identities and placement only, never source bodies, values or permission.

```typescript
export type CanvasContentCopy =
  | {
      kind: 'selection';
      sourcePageId: string;
      rootNodeIds: string[];
      expectedNodeIds: string[];
      nodeMap: Record<string, string>;
      regionKeys: Record<string, string>;
      targetPageId: string;
      placements: { sourceNodeId: string; parentId: string | null; x: number; y: number }[];
      index: number;
    }
  | {
      kind: 'page';
      sourcePageId: string;
      expectedNodeIds: string[];
      nodeMap: Record<string, string>;
      regionKeys: Record<string, string>;
      newPageId: string;
      index: number;
    };
```

```typescript
type CanvasContentCopy = { kind: "selection"; sourcePageId: string; rootNodeIds: string[]; expectedNodeIds: string[]; nodeMap: Record<string, string>; regionKeys: Record<string, string>; targetPageId: string; placements: { sourceNodeId: string; parentId: string | null; x: number; y: number; }[]; index: number; } | { kind: "page"; sourcePageId: string; expectedNodeIds: string[]; nodeMap: Record<string, string>; regionKeys: Record<string, string>; newPageId: string; index: number; };
```

## CanvasContentCopyIntent

Local gesture metadata is an untrusted flat intent; only the native original-body owner can attest retained snapshots.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `copy` | `CanvasContentCopy` | **Required.** Defines copy for this object. Observe the type, variants and bounds in the Options column. |
| `operationsBeforeCopy` | `readonly CanvasOperation[]` | **Required.** Defines operations Before Copy for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasContentCopyIntent {
  readonly copy: CanvasContentCopy;
  readonly operationsBeforeCopy: readonly CanvasOperation[];
}
```

## CanvasDiffOptions

Optional copy gestures retain their true position among authored edits without changing historical body contracts.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `copies` | `readonly CanvasContentCopyIntent[]` | **Required.** Defines copies for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasDiffOptions {
  readonly copies: readonly CanvasContentCopyIntent[];
}
```

## CanvasComponentResolver

Only a server-authorized or explicitly read definition may satisfy a portable operation.

```typescript
export type CanvasComponentResolver = (reference: CanvasComponentReference) => CanvasDocument;
```

## CanvasComponentSourcePolicy

A declared source capability is not a grant; CP/Core still authorize each actual target.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `modelId` | `string` | **Required.** Defines model Id for this object. Observe the type, variants and bounds in the Options column. |
| `componentDefinitionPaths` | `string[]` | **Required.** Exact path of the relevant definition type; each reference must exist in the Model and respect declared scope. |
| `libraryDefinitionPaths` | `string[]` | **Required.** Exact path of the relevant definition type; each reference must exist in the Model and respect declared scope. |

```typescript
export interface CanvasComponentSourcePolicy {
  modelId: string;
  componentDefinitionPaths: string[];
  libraryDefinitionPaths: string[];
}
```

## CanvasComponentUpdatePreview

Explicit update impact, never an automatic retargeting of removed objects or invalid parameters.

| Field | Options / expected values | Description |
| --- | --- | --- |
| `compatible` | `boolean` | **Required.** Defines compatible for this object. Observe the type, variants and bounds in the Options column. |
| `preservedNodeIds` | `string[]` | **Required.** Defines preserved Node Ids for this object. Observe the type, variants and bounds in the Options column. |
| `addedSourceNodeIds` | `string[]` | **Required.** Defines added Source Node Ids for this object. Observe the type, variants and bounds in the Options column. |
| `removedNodeIds` | `string[]` | **Required.** Defines removed Node Ids for this object. Observe the type, variants and bounds in the Options column. |
| `conflicts` | `string[]` | **Required.** Defines conflicts for this object. Observe the type, variants and bounds in the Options column. |

```typescript
export interface CanvasComponentUpdatePreview {
  compatible: boolean;
  preservedNodeIds: string[];
  addedSourceNodeIds: string[];
  removedNodeIds: string[];
  conflicts: string[];
}
```

[All references](https://developers.dagio.ai/reference/)

<!-- surface-examples:start -->

## Applied examples : Visual content in the record

Insert the Canvas editor, then an Asset when a separate visual resource is needed.

### Configuration

Component properties `NativeContent.props`. [Properties and accepted values](https://developers.dagio.ai/surface-components/#nativecontent).

```json
{
  "recordProfileKey": "client",
  "contentKind": "canvas"
}
```

### Variation and connection

Component properties `NativeContent.props`. [Properties and accepted values](https://developers.dagio.ai/surface-components/#nativecontent).

```json
{
  "recordProfileKey": "client",
  "contentKind": "asset"
}
```

### UI layout example

The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.

1. Client need
2. Options
3. Selected proposal
4. Sources

<!-- surface-examples:end -->