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.

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

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

CanvasNodeKind

Closed native leaves, containers and attached connections.

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

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

CanvasStrokeType

Frame stroke styles shared by shapes and text blocks.

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

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.

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.

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.

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.

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

CanvasLeafNode

Native Canvas object union, independent of Surface Canvas serialization.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

CanvasNodePatch

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

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>;

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.

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[] };

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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;
    };

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.

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.

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

CanvasComponentResolver

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

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.

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.

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

All references

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.

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

Variation and connection

Component properties NativeContent.props. Properties and accepted values.

{
  "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

SurfaceClients / North StudioExample

types · typesVisual content in the record

Clients

01Client needNorth Studio

02OptionsProject element

03Selected proposalProject element

04SourcesProject element