App Configuration

Pass Sketchpad an optional JSON-safe definition to shape one hosted drawing experience. The hosted runtime supplies and validates its own schema version; your application owns the definition’s revision and product choices.

Table of Contents

• Definition
• Ownership and Versioning
• Tools
• UI
• Hosted Capabilities
• Portable Values
• Defaults and Settings

Definition

const definition = {
	definitionVersion: '1',
	description: 'A focused product artwork editor.',
	name: 'Artwork editor'
}

const sketchpad = new Sketchpad({ definition, session })

definitionVersion is your revision for this recipe. It is independent from the hosted client and saved-document versions. Keep definitions as plain data that can be stored, compared, and sent through postMessage without code.

The generated API reference is the source of truth for exact fields. The sections below explain the durable configuration boundaries.

Ownership and Versioning

The client owns hosted frame lifecycle, the app definition owns a reusable product recipe, document and layer handles identify runtime state, and your server owns projects, origins, keys, scopes, and usage. Keep these records separate so a definition can be stored without document content or credentials.

When a definition is supplied, definitionVersion and name identify your recipe. Increment definitionVersion when your application changes that recipe’s meaning. It is independent from the hosted client URL and saved-file versions; migrations belong to the application or service that stores the definition.

The hosted runtime validates the complete definition before mounting. Invalid shapes, duplicate ids, unsupported catalog values, and unsafe runtime values fail as one configuration error rather than mounting a partial product.

Tools

groups defines the visible primary-tool grouping and display order. The hosted product preloads those tools plus defaultTool, selects the default, and applies supported option overrides:

const definition = {
	definitionVersion: '2',
	name: 'Artwork editor',
	tools: {
		defaultTool: 'select',
		groups: [{ id: 'create', tools: ['select', 'tileBrush', 'shape', 'fancyText'] }],
		overrides: {
			fancyText: { defaultContent: 'Type here...' }
		}
	}
}

Definitions select hosted tools; they never contain implementations, constructors, or module paths. Omitting tools uses the maintained default surface. A defaultTool may be preloaded without appearing in a visible group.

UI

UI configuration uses stable region ids and registered contributions. The hosted product currently recognizes primary-toolbar, floating-toolbar, and tool-action-strip. Omitting ui uses its standard chrome; supplying regions makes the selected surface explicit.

const definition = {
	definitionVersion: '3',
	name: 'Bottom toolbar editor',
	ui: {
		regions: {
			'primary-toolbar': [
				{
					type: 'standard',
					options: { position: 'bottom' }
				}
			],
			'tool-action-strip': [{ type: 'standard' }]
		}
	}
}

Each maintained region accepts one standard contribution. The primary toolbar supports position and mirrorInRTL; the other maintained regions do not accept options. Unsupported values fail during mounting.

See UI Composition for the portable boundary.

Hosted Capabilities

Definitions may declare required or optional product capabilities and integrations. They select capabilities already offered by the hosted product; they do not let browser code inject services or credentials into the frame.

const definition = {
	capabilities: { required: ['vector'] },
	definitionVersion: '4',
	integrations: { optional: ['files'] },
	name: 'Vector editor'
}

Treat requirement ids as compatibility metadata, not authorization. The hosted product evaluates requirements when it publishes the corresponding catalog; declaring a value never grants a capability or injects an integration.

Portable Values

Definitions may contain JSON primitives, arrays, and objects. Do not include:

• functions or callbacks
• DOM nodes or browser handles
• UI framework components
• service implementations or credentials
• loaded images, fonts, or renderer resources

The hosted runtime rejects malformed definitions and reports the rejected field. Keep sensitive or live integration state on your server or application side of the hosted boundary.

Defaults and Settings

defaults and settings carry registered JSON values for newly created app state. They do not overwrite existing documents or persisted user preferences. The hosted product decides which registered keys it supports.

Use the generated API reference for exact current types and the service API reference for session and usage endpoints.