OpenPencil

https://openpencil.dev/
Admin
OpenPencil is an open-source, AI-native design editor that opens Figma files, offers full...
Tokens:60,934
Snippets:851
Trust Score:5.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Development Setup Commands

Source: https://openpencil.dev/development/contributing

Commands to install dependencies and start the development servers for the editor and documentation.

```sh
bun install
bun run dev          # Editor at localhost:1420
bun run docs:dev     # Docs at localhost:5173
```

--------------------------------

### Basic useCanvasInput Setup

Source: https://openpencil.dev/programmable/sdk/api/composables/use-canvas-input

A basic example demonstrating how to set up useCanvasInput with useCanvas, passing canvas hit-test properties.

```typescript
const canvas = useCanvas(canvasRef, editor)

useCanvasInput(
  canvasRef,
  editor,
  canvas.hitTestSectionTitle,
  canvas.hitTestComponentLabel,
  canvas.hitTestFrameTitle,
)
```

--------------------------------

### Clone and Install Dependencies

Source: https://openpencil.dev/getting-started

Clones the repository and installs necessary packages using Bun.

```sh
git clone https://github.com/open-pencil/open-pencil.git
cd open-pencil
bun install
```

--------------------------------

### Install Open Pencil SDK Packages

Source: https://openpencil.dev/programmable/sdk/getting-started

Install the core, Vue, and CanvasKit WASM packages using bun.

```bash
bun add @open-pencil/core @open-pencil/vue canvaskit-wasm
```

--------------------------------

### Start Development Server

Source: https://openpencil.dev/getting-started

Launches the editor at http://localhost:1420.

```sh
bun run dev
```

--------------------------------

### Install MCP Server

Source: https://openpencil.dev/overview/features

Global installation command for the OpenPencil MCP server.

```sh
npm install -g @open-pencil/mcp
```

--------------------------------

### Install OpenPencil CLI

Source: https://openpencil.dev/programmable/cli/inspecting

Installation commands for the OpenPencil CLI using npm or Homebrew.

```sh
npm install -g @open-pencil/cli
# or
brew install open-pencil/tap/open-pencil
```

--------------------------------

### Initialize useTypography

Source: https://openpencil.dev/programmable/sdk/api/composables/use-typography

Basic setup for importing and initializing the useTypography composable.

```ts
import { useTypography } from '@open-pencil/vue'

const typography = useTypography()
```

--------------------------------

### Run Windows Desktop Development

Source: https://openpencil.dev/getting-started

Starts the Tauri development environment on Windows.

```sh
bun run tauri dev
```

--------------------------------

### Example AI prompt

Source: https://openpencil.dev/programmable/mcp-server

A sample prompt for interacting with the OpenPencil MCP server.

```text
Use the open-pencil MCP server to inspect the current page and create a small hero section on the canvas.
```

--------------------------------

### Install OpenPencil on macOS via Homebrew

Source: https://openpencil.dev/getting-started

Installs the latest signed release for macOS using the OpenPencil tap.

```sh
brew install open-pencil/tap/open-pencil
```

--------------------------------

### Run OpenPencil MCP Server

Source: https://openpencil.dev/programmable/mcp-server

Commands to start the MCP server via package execution or source.

```sh
openpencil-mcp-http
```

```sh
bun packages/mcp/src/index.ts
```

```sh
npx tsx packages/mcp/src/index.ts
```

--------------------------------

### Install Linux System Dependencies

Source: https://openpencil.dev/getting-started

Installs required system libraries for Tauri on Debian/Ubuntu systems.

```sh
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \
  libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
```

--------------------------------

### Initialize macOS Desktop Development

Source: https://openpencil.dev/getting-started

Installs Xcode command line tools and the Tauri CLI for macOS development.

```sh
xcode-select --install
cargo install tauri-cli --version "^2"
bun run tauri dev
```

--------------------------------

### Initialize useMenuModel

Source: https://openpencil.dev/programmable/sdk/api/composables/use-menu-model

Initialize the useMenuModel composable to access its menu models. This example shows how to get the appMenu, canvasMenu, and selectionLabelMenu.

```typescript
const { appMenu, canvasMenu, selectionLabelMenu } = useMenuModel()

```

--------------------------------

### Register OpenPencil with Claude Code

Source: https://openpencil.dev/programmable/mcp-server

Install the package and add it to Claude Code's MCP configuration.

```sh
npm install -g @open-pencil/mcp
claude mcp add --scope user open-pencil -- openpencil-mcp
```

--------------------------------

### Basic Locale Switching Example

Source: https://openpencil.dev/programmable/sdk/api/composables/use-i18n

Demonstrates how to use useI18n to display localized menu items and allow users to switch locales via a select dropdown.

```vue
<script setup lang="ts">
import { useI18n } from '@open-pencil/vue'

const { menu, locale, availableLocales, localeLabels, setLocale } = useI18n()
</script>

<template>
  <label class="flex items-center gap-2">
    <span>{{ menu.view }}</span>
    <select :value="locale" @change="setLocale(($event.target as HTMLSelectElement).value as typeof locale)">
      <option v-for="code in availableLocales" :key="code" :value="code">
        {{ localeLabels[code] }}
      </option>
    </select>
  </label>
</template>
```

--------------------------------

### Basic useMenuModel Initialization

Source: https://openpencil.dev/programmable/sdk/api/composables/use-menu-model

A minimal example of initializing useMenuModel to obtain the canvasMenu. Render the 'canvasMenu.value' into your context menu component.

```typescript
const { canvasMenu } = useMenuModel()

```

--------------------------------

### Import web content

Source: https://openpencil.dev/reference/cli

Import HTML and CSS into an OpenPencil document. Use the examples below to see how to apply CSS or Tailwind classes during import.

```sh
openpencil import page.html [options]
```

```sh
openpencil import card.html --css card.css -o card.fig
openpencil import card.html --tailwind "flex flex-col gap-3 w-80 p-6 rounded-xl bg-white" -o card.fig
```

--------------------------------

### Add OpenPencil Skill to AI Agent

Source: https://openpencil.dev/programmable/mcp-server

Use this command to install the OpenPencil skill for supported AI coding agents.

```sh
npx skills add open-pencil/skills@open-pencil
```

--------------------------------

### Exporting JSX Components

Source: https://openpencil.dev/programmable/cli/exporting

Commands and output examples for exporting designs as JSX with Tailwind or native OpenPencil styles.

```sh
openpencil export design.fig -f jsx --style tailwind
```

```html
<div className="flex flex-col gap-4 p-6 bg-white rounded-xl">
  <p className="text-2xl font-bold text-[#1D1B20]">Card Title</p>
  <p className="text-sm text-[#49454F]">Description text</p>
</div>
```

--------------------------------

### Import usePageList Composable

Source: https://openpencil.dev/programmable/sdk/api/composables/use-page-list

Import the usePageList composable from the OpenPencil Vue library. This is the initial setup required to use its functionalities.

```typescript
import { usePageList } from '@open-pencil/vue'

const pageList = usePageList()
```

--------------------------------

### Write SceneGraph Unit Test

Source: https://openpencil.dev/development/testing

Example of a unit test using bun:test to verify SceneGraph node creation and retrieval.

```typescript
import { describe, expect, it } from 'bun:test'
import { SceneGraph } from '@open-pencil/scene-graph'

describe('SceneGraph', () => {
  it('creates and retrieves a node', () => {
    const sg = new SceneGraph()
    const node = sg.createNode('RECTANGLE', sg.root, { name: 'Test' })
    expect(sg.getNode(node.guid)).toBeDefined()
  })
})
```

--------------------------------

### Get Document Information

Source: https://openpencil.dev/programmable/cli/inspecting

Retrieve an overview of a design file including page count, node count, and file size.

```sh
openpencil info design.fig
```

--------------------------------

### Basic Vue Component with Canvas and Selection Display

Source: https://openpencil.dev/programmable/sdk/getting-started

A complete example demonstrating how to set up a canvas, use editor composables, and display the selected item count. The useCanvas composable includes an optional onReady callback.

```vue
<script setup lang="ts">
import { ref } from 'vue'

import { useCanvas, useEditor, useSelectionState } from '@open-pencil/vue'

const canvasRef = ref<HTMLCanvasElement | null>(null)
const editor = useEditor()
const { selectedCount } = useSelectionState()

useCanvas(canvasRef, editor, {
  onReady: () => {
    console.log('Canvas ready')
  },
})
</script>

<template>
  <div class="grid h-full grid-rows-[1fr_auto]">
    <canvas ref="canvasRef" class="size-full" />
    <div class="border-t px-3 py-2 text-xs text-muted">
      Selected: {{ selectedCount }}
    </div>
  </div>
</template>
```

--------------------------------

### CSS Grid Track Sizing Example

Source: https://openpencil.dev/user-guide/auto-layout

Defines three columns for a grid layout: two flexible columns using fractional units and one fixed-size column in the center. This is useful for dashboard or gallery layouts.

```css
1fr 200px 1fr
```

--------------------------------

### vLLM tool call streaming error example

Source: https://openpencil.dev/programmable/byok-provider-compatibility

An example of a malformed stream chunk where the closing brace is incorrectly indexed and missing an ID.

```text
 1  [{"index":0,"id":"chatcmpl-tool-…","function":{"arguments":"","name":"create_node"},"type":"function"}]
 …  deltas 2–11 stream the arguments, all index 0
12  [{"index":1,"function":{"arguments":"}"}}]      ← wrong index, no id
```

--------------------------------

### Initialize and use ColorBindingProvider

Source: https://openpencil.dev/programmable/sdk/api/advanced/use-color-binding-provider

Demonstrates initializing the provider and interacting with binding targets and color values. Requires an editor instance provided via provideEditor().

```ts
import type { Color } from '@open-pencil/scene-graph'
import type { BindingTarget } from '@open-pencil/vue'
import { useColorBindingProvider } from '@open-pencil/vue'

const provider = useColorBindingProvider()
const targets: BindingTarget[] = [
  { nodeId: 'rectangle-id', path: 'fills/0/color' }
]
const value: Color = { r: 0.2, g: 0.5, b: 0.9, a: 1 }

provider.getState(targets)
provider.resolve('variable-id')
```

--------------------------------

### GET /health

Source: https://openpencil.dev/programmable/mcp-server

Checks the server and application connection status.

```APIDOC
## GET /health

### Description
Returns the current health status of the server and its connection to the application. This endpoint does not return the authentication token.

### Method
GET

### Endpoint
/health
```

--------------------------------

### Run MCP server from source

Source: https://openpencil.dev/programmable/mcp-server

Configure MCP clients to run the server directly using Bun or Node.js.

```json
{
  "mcpServers": {
    "open-pencil": {
      "command": "bun",
      "args": ["/path/to/open-pencil/packages/mcp/src/stdio.ts"]
    }
  }
}
```

```json
{
  "mcpServers": {
    "open-pencil": {
      "command": "npx",
      "args": ["tsx", "/path/to/open-pencil/packages/mcp/src/stdio.ts"]
    }
  }
}
```

--------------------------------

### Project Directory Structure

Source: https://openpencil.dev/development/contributing

Overview of the repository layout including core packages, UI components, and testing directories.

```text
packages/
  core/              @open-pencil/core — engine (zero DOM deps)
    src/             Scene graph, renderer, layout, codec, kiwi, types
  cli/               @open-pencil/cli — headless CLI for .fig operations
    src/commands/    info, tree, find, export, eval, analyze
  mcp/               @open-pencil/mcp — MCP server for AI tools
    src/             stdio + HTTP (Hono) transports, 87 tools
src/
  components/        Vue SFCs (canvas, panels, toolbar, color picker)
    properties/      Property panel sections (Appearance, Fill, Stroke, etc.)
  composables/       Canvas input, keyboard shortcuts, rendering hooks
  stores/            Editor state (Vue reactivity)
  engine/            Re-export shims from @open-pencil/core
  kiwi/              Re-export shims from @open-pencil/core
  types.ts           Shared types (re-exported from core)
  constants.ts       UI colors, defaults, thresholds
desktop/             Tauri v2 (Rust + config)
tests/
  e2e/               Playwright visual regression
  engine/            Unit tests (bun:test)
docs/                VitePress documentation site
```

--------------------------------

### Create an Editor Instance

Source: https://openpencil.dev/programmable/sdk/getting-started

Instantiate the editor with specified width and height using createEditor from the core package.

```typescript
import { createEditor } from '@open-pencil/core/editor'

const editor = createEditor({
  width: 1200,
  height: 800,
})
```

--------------------------------

### Live App Mode

Source: https://openpencil.dev/programmable/cli/scripting

Runs a script against the currently open document in the desktop application.

```sh
openpencil eval -c "return figma.currentPage.name"
```

--------------------------------

### Build Desktop Application for Distribution

Source: https://openpencil.dev/getting-started

Builds the desktop application for the current platform or specific targets.

```sh
bun run tauri build                                    # Current platform
bun run tauri build --target universal-apple-darwin    # macOS universal
```

--------------------------------

### Initialize useAppearance

Source: https://openpencil.dev/programmable/sdk/api/composables/use-appearance

Import and initialize the composable to access appearance controls.

```ts
import { useAppearance } from '@open-pencil/vue'

const appearance = useAppearance()
```

--------------------------------

### Initialize useLayout

Source: https://openpencil.dev/programmable/sdk/api/composables/use-layout

Import and initialize the useLayout composable.

```ts
import { useLayout } from '@open-pencil/vue'

const layout = useLayout()
```

--------------------------------

### Import and Use useVariablesTable

Source: https://openpencil.dev/programmable/sdk/api/advanced/use-variables-table

Import the useVariablesTable composable from the OpenPencil Vue SDK and call it with options to get table columns.

```typescript
import { useVariablesTable } from '@open-pencil/vue'

const { columns } = useVariablesTable(options)
```

--------------------------------

### useColorModel(options)

Source: https://openpencil.dev/programmable/sdk/api/composables/use-color-model

Initializes the color model with a reactive color reference and optional callbacks for state persistence and format management.

```APIDOC
## useColorModel(options)

### Description
Initializes a reactive color model for managing color state and conversions. It accepts a color reference and various callbacks to handle updates to the scene graph or external state.

### Parameters
- **color** (Ref<Color>) - Required - A reactive reference to the current color object.
- **onUpdate** (Function) - Optional - Callback triggered when the color changes.
- **defaultFormat** (String) - Optional - The initial color format (e.g., 'hex', 'rgb', 'hsl', 'hsb', 'okhcl').
- **onFormatChange** (Function) - Optional - Callback triggered when the active format changes.
- **okhcl** (Function) - Optional - A getter function for the current OkHCL state.
- **onUpdateOkHCL** (Function) - Optional - Callback triggered when OkHCL values are updated.

### Methods
- **updateHSLChannel(channel, value)**: Updates a specific HSL channel.
- **updateAlpha(value)**: Updates the alpha channel.
- **updateHex(hex)**: Updates the color using a hex string.
- **setFormat(format)**: Changes the active color format.
- **updateOkHCLChannel(channel, value)**: Updates a specific OkHCL channel.

### Computed Properties
- **hex**: The current color as a hex string.
- **rekaColor**: The color in Reka-compatible format.
- **rgb**: The color in RGB format.
- **hsl**: The color in HSL format.
- **hsb**: The color in HSB format.
- **sliderPreview / sliderGradient**: Presentation data for UI sliders.
```

--------------------------------

### POST /rpc

Source: https://openpencil.dev/programmable/mcp-server

Executes authenticated live-app automation commands.

```APIDOC
## POST /rpc

### Description
Used for authenticated live-app automation. This endpoint accepts commands to interact with the OpenPencil application.

### Method
POST

### Endpoint
/rpc
```

--------------------------------

### Run all project checks

Source: https://openpencil.dev/development/contributing

Executes the full suite of linting, formatting, and type-checking tools.

```sh
bun run check
```

--------------------------------

### Track Cursor Movement with useCanvasInput

Source: https://openpencil.dev/programmable/sdk/api/composables/use-canvas-input

Example of using useCanvasInput to track cursor movement within the canvas space by providing a callback function.

```typescript
useCanvasInput(
  canvasRef,
  editor,
  hitTestSectionTitle,
  hitTestComponentLabel,
  hitTestFrameTitle,
  (cx, cy) => {
    console.log(cx, cy)
  },
)
```

--------------------------------

### Control Live Editor via CLI

Source: https://openpencil.dev/overview/features

Commands to interact with the active desktop application instance.

```sh
openpencil tree                     # Live document
openpencil export -f png            # Screenshot canvas
```

--------------------------------

### Access Editor Commands and Selection State

Source: https://openpencil.dev/programmable/sdk/getting-started

Import and use useEditorCommands and useSelectionState composables from @open-pencil/vue to interact with the editor and get selection information.

```typescript
import { useEditorCommands, useSelectionState } from '@open-pencil/vue'

const selection = useSelectionState()
const commands = useEditorCommands()
```

--------------------------------

### useViewportKind

Source: https://openpencil.dev/programmable/sdk/api/advanced/use-viewport-kind

Returns simple responsive flags used by the OpenPencil editor UI. This composable is useful when your shell requires a light abstraction over breakpoints, rather than directly integrating useBreakpoints.

```APIDOC
## useViewportKind()

### Description
Provides simple responsive flags for the OpenPencil editor UI, abstracting breakpoint logic for shell implementations.

### Returns
- **isMobile** (boolean) - Flag indicating if the viewport is considered mobile.
- **isDesktop** (boolean) - Flag indicating if the viewport is considered desktop.

### Usage Example
```ts
import { useViewportKind } from '@open-pencil/vue'

const { isMobile, isDesktop } = useViewportKind()
```
```

--------------------------------

### Using GradientEditorBar in Vue

Source: https://openpencil.dev/programmable/sdk/api/components/gradient-editor-bar

Example of how to integrate the GradientEditorBar component in a Vue.js application. It demonstrates binding props and listening to custom events for managing gradient stops.

```vue
<GradientEditorBar
  :stops="stops"
  :active-stop-index="activeStopIndex"
  :bar-background="barBackground"
  @select-stop="selectStop"
  @drag-stop="dragStop"
  v-slot="ctx"
>
  <MyGradientBar v-bind="ctx" />
</GradientEditorBar>
```

--------------------------------

### Basic Page List Rendering with PageListRoot

Source: https://openpencil.dev/programmable/sdk/api/components/page-list-root

Demonstrates how to use PageListRoot to render a list of pages and handle page switching. It provides access to pages, the current page ID, and a switchPage function via slots.

```vue
<PageListRoot v-slot="{ pages, currentPageId, switchPage }">
  <ul>
    <li v-for="page in pages" :key="page.id">
      <button
        :data-active="page.id === currentPageId"
        @click="switchPage(page.id)"
      >
        {{ page.name }}
      </button>
    </li>
  </ul>
</PageListRoot>
```

--------------------------------

### Using GradientEditorRoot in Vue

Source: https://openpencil.dev/programmable/sdk/api/components/gradient-editor-root

Example of how to integrate GradientEditorRoot into a Vue application. It binds a fill object and listens for updates, passing the slot props to a custom UI component.

```vue
<GradientEditorRoot :fill="fill" @update="fill = $event" v-slot="ctx">
  <MyGradientUI v-bind="ctx" />
</GradientEditorRoot>
```

--------------------------------

### Basic useCanvas with Options

Source: https://openpencil.dev/programmable/sdk/api/composables/use-canvas

Configure the useCanvas composable with options to show rulers and log a message when the renderer is ready.

```vue
<script setup lang="ts">
import { ref } from 'vue'

import { useCanvas, useEditor } from '@open-pencil/vue'

const canvasRef = ref<HTMLCanvasElement | null>(null)
const editor = useEditor()

useCanvas(canvasRef, editor, {
  showRulers: true,
  onReady: () => {
    console.log('Renderer ready')
  },
})
</script>

<template>
  <canvas ref="canvasRef" class="size-full" />
</template>
```

--------------------------------

### Basic useEditor Usage in Vue

Source: https://openpencil.dev/programmable/sdk/api/composables/use-editor

Demonstrates how to use the useEditor composable within a Vue component's script setup to access editor state, such as the current page ID.

```vue
<script setup lang="ts">
import { computed } from 'vue'

import { useEditor } from '@open-pencil/vue'

const editor = useEditor()
const pageId = computed(() => editor.state.currentPageId)
</script>

<template>
  <div>Current page: {{ pageId }}</div>
</template>
```

--------------------------------

### Live App Mode Commands

Source: https://openpencil.dev/programmable/cli/inspecting

Interact with the active document in the running desktop application by omitting the file argument.

```sh
openpencil documents         # list open document/page IDs
openpencil tree              # inspect the active live document
openpencil tree --document-id tab-123 --page-id 0:1
openpencil eval --document-id tab-123 --page-id 0:1 -c "..."
```

--------------------------------

### Update Export Scale and Format

Source: https://openpencil.dev/programmable/sdk/api/composables/use-export

Update the scale and format for a specific export preset using its index. This example changes the first preset (index 0) to 2x scale and WEBP format.

```typescript
exportState.updateScale(0, 2)
exportState.updateFormat(0, 'WEBP')
```

--------------------------------

### Configure MCP Server

Source: https://openpencil.dev/overview/features

JSON configuration for integrating the OpenPencil MCP server into client environments.

```json
{
  "mcpServers": {
    "open-pencil": {
      "command": "openpencil-mcp"
    }
  }
}
```

--------------------------------

### List Pages and Variables

Source: https://openpencil.dev/programmable/cli/inspecting

Commands to list all pages or design variables in a document.

```sh
openpencil pages design.fig
openpencil variables design.fig
```

--------------------------------

### Build a "move to page" submenu

Source: https://openpencil.dev/programmable/sdk/api/composables/use-editor-commands

This snippet shows how to construct a submenu for moving the editor selection to different pages. It utilizes `otherPages` to get a list of available pages and `moveSelectionToPage` to perform the action.

```APIDOC
## moveSelectionToPage

### Description
Moves the current editor selection to a specified page.

### Method
`moveSelectionToPage(pageId: string)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **pageId** (string) - Required - The ID of the target page to move the selection to.

### Request Example
```ts
import { useEditorCommands } from '@open-pencil/vue'

const { otherPages, moveSelectionToPage } = useEditorCommands()

const items = otherPages.value.map(page => ({
  label: page.name,
  action: () => moveSelectionToPage(page.id),
}))
```

### Response
This method does not return a value directly, but performs an action within the editor.
```

--------------------------------

### Penpot Rendering Pipeline Flow

Source: https://openpencil.dev/overview/comparison

Visualizes the data flow from ClojureScript through Rust WASM to the Skia rendering engine.

```text
ClojureScript (compiled to JS)
  → decompose to primitives + binary-pack into WASM linear memory
  → Rust WASM (via Emscripten C FFI)
  → skia-safe (Rust Skia bindings)
  → Skia (WebGL)
```

--------------------------------

### useColorBindingProvider()

Source: https://openpencil.dev/programmable/sdk/api/advanced/use-color-binding-provider

A composable that adapts OpenPencil COLOR variables to the BindingProvider<Color> contract. It requires an editor provided by provideEditor().

```APIDOC
## useColorBindingProvider()

### Description
Adapts OpenPencil COLOR variables to the generic `BindingProvider<Color>` contract. It resolves current-mode colors, binds indexed paint paths, creates variables in a Colors collection, updates all collection modes, and exposes editor undo transactions.

### Usage
```ts
import { useColorBindingProvider } from '@open-pencil/vue';

const provider = useColorBindingProvider();

// Example: Get state for specific targets
const targets = [{ nodeId: 'rectangle-id', path: 'fills/0/color' }];
provider.getState(targets);

// Example: Resolve a variable
provider.resolve('variable-id');
```

### Requirements
- Requires an editor provided by `provideEditor()`.
```

--------------------------------

### Configure Claude Code permissions

Source: https://openpencil.dev/programmable/mcp-server

Add auto-approval settings for OpenPencil tools in the Claude settings file.

```json
{
  "permissions": {
    "allow": ["mcp__open-pencil__*"]
  }
}
```

--------------------------------

### Initialize useDocumentWorkspace

Source: https://openpencil.dev/programmable/sdk/api/composables/use-document-workspace

Configure the workspace with source methods and an optional refresh interval.

```ts
import { useDocumentWorkspace } from '@open-pencil/vue'

const workspace = useDocumentWorkspace({
  source: {
    refresh: () => documentService.list(),
    loadPreview: (id) => documentService.loadPreview(id),
    subscribe: (listener) => documentService.subscribe(listener),
  },
  refreshInterval: 60_000,
})
```

--------------------------------

### Import and Initialize useCanvas

Source: https://openpencil.dev/programmable/sdk/api/composables/use-canvas

Import necessary functions and initialize the useCanvas composable with a canvas reference and the editor instance.

```typescript
import { ref } from 'vue'

import { useCanvas, useEditor } from '@open-pencil/vue'

const canvasRef = ref<HTMLCanvasElement | null>(null)
const editor = useEditor()

useCanvas(canvasRef, editor)
```

--------------------------------

### useConstraints()

Source: https://openpencil.dev/programmable/sdk/api/composables/use-constraints

Initializes the constraints controller to read and update resize constraints for selected nodes.

```APIDOC
## useConstraints()

### Description
Provides selection-derived horizontal and vertical constraint state plus undo-aware actions for frame children.

### Signature
`const constraints = useConstraints()`

### Returns
- **active** (boolean) - True if every selected node is an eligible child of a frame-like container.
- **horizontal** (string) - Current horizontal constraint: 'MIN', 'CENTER', 'MAX', 'STRETCH', 'SCALE', or 'MIXED'.
- **vertical** (string) - Current vertical constraint: 'MIN', 'CENTER', 'MAX', 'STRETCH', 'SCALE', or 'MIXED'.
- **setAxis(axis, mode)** (function) - Sets the constraint mode for the specified axis ('horizontal' | 'vertical').
- **togglePin(axis, side, value)** (function) - Toggles the pin state for a specific axis and side.

### Example
```ts
import { useConstraints } from '@open-pencil/vue'

const constraints = useConstraints()
constraints.setAxis('horizontal', 'STRETCH')
constraints.togglePin('vertical', 'trailing', false)
```
```

--------------------------------

### useAppearance()

Source: https://openpencil.dev/programmable/sdk/api/composables/use-appearance

Initializes the appearance-focused control composable for property panels, returning an object containing state and methods for managing selection appearance.

```APIDOC
## useAppearance()

### Description
Initializes the appearance composable to manage properties such as visibility, opacity, corner radius, and corner smoothing for the current selection.

### Returns
- **visibilityState** (Ref) - Current visibility state.
- **opacityPercent** (Ref) - Current opacity as a percentage.
- **cornerRadiusValue** (Ref) - Current corner radius value.
- **cornerSmoothingPercent** (Ref) - Current corner smoothing as a normalized percentage.
- **showIndependentCorners** (Ref) - Boolean indicating if independent corners are enabled.
- **toggleVisibility()** (Function) - Toggles the visibility of the selection.
- **toggleIndependentCorners()** (Function) - Toggles the independent corner state.
- **updateCornerProp(prop, value)** (Function) - Updates a specific corner property locally.
- **commitCornerProp(prop, value, originalValue)** (Function) - Commits a change to a corner property to the undo stack.
```

--------------------------------

### Query models.dev API for model metadata

Source: https://openpencil.dev/programmable/byok-provider-compatibility

Use this command to fetch specific model capabilities and cost information from the models.dev catalog.

```bash
curl -s https://models.dev/api.json \
  | jq '.scaleway.models["gemma-4-26b-a4b-it"] | {tool_call, attachment, reasoning, cost, limit}'
```

--------------------------------

### useLayout()

Source: https://openpencil.dev/programmable/sdk/api/composables/use-layout

Initializes the layout controller to access state and actions for node layout properties.

```APIDOC
## useLayout()

### Description
Initializes the layout controller for the current node, exposing methods to manipulate sizing, padding, alignment, and grid configurations.

### Signature
`const layout = useLayout()`

### Returns
- **layout** (Object) - An object containing state and methods for layout manipulation.
```

--------------------------------

### useDocumentWorkspace()

Source: https://openpencil.dev/programmable/sdk/api/composables/use-document-workspace

Initializes the document workspace state with a provided source configuration and optional refresh interval.

```APIDOC
## useDocumentWorkspace(options)

### Description
Initializes the document workspace state. The source object must provide methods for refreshing the document list, loading previews, and subscribing to updates.

### Parameters
- **source** (Object) - Required - Configuration object containing `refresh`, `loadPreview`, and `subscribe` methods.
- **refreshInterval** (Number) - Optional - Interval in milliseconds for automatic refreshes.
- **onPreviewError** (Function) - Optional - Callback function triggered when a preview fails to load.

### Returns
- **documents** (Array) - The current list of documents.
- **previewDirective** (Object) - Vue directive for triggering lazy preview loading.
- **previewURL** (Function) - Returns the object URL for a given document ID.
- **loadPreview** (Function) - Manually triggers a retry for a failed preview.
- **clearPreviews** (Function) - Clears all generated object URLs.
- **error** (Object) - The latest document-list refresh failure.
- **previewErrors** (Object) - Map of preview failures by document ID.
```

--------------------------------

### Run Unit Tests

Source: https://openpencil.dev/development/testing

Command to execute the engine unit test suite.

```sh
bun run test:unit
```

--------------------------------

### Implement Open Pencil Layout with Yoga

Source: https://openpencil.dev/overview/comparison

Demonstrates the integration of the Yoga WASM library to calculate layout properties.

```typescript
import Yoga from 'yoga-layout'
// Direct mapping: Figma stack* fields → Yoga flex properties
const root = Yoga.Node.create()
root.setFlexDirection(FlexDirection.Row)
root.calculateLayout()
applyYogaLayout(graph, frame, yogaRoot)
```

--------------------------------

### Implement PropertyGridRoot with columns and actions

Source: https://openpencil.dev/programmable/sdk/api/components/property-grid

Defines a two-column property grid with input fields and an action slot for additional controls.

```vue
<script setup lang="ts">
import { PropertyGridRoot } from '@open-pencil/vue'
</script>

<template>
  <PropertyGridRoot :columns="2">
    <label>
      Width
      <input type="number" />
    </label>
    <label>
      Height
      <input type="number" />
    </label>
    <template #actions>
      <button type="button" aria-label="Constrain proportions">Link</button>
    </template>
  </PropertyGridRoot>
</template>
```

--------------------------------

### Analyze spacing and layout

Source: https://openpencil.dev/reference/cli

Check gap and padding values in auto-layout frames against a base grid size.

```sh
openpencil analyze spacing [file] [options]
```

--------------------------------

### useOkHCL()

Source: https://openpencil.dev/programmable/sdk/api/advanced/use-okhcl

The useOkHCL composable provides an interface for interacting with OkHCL color metadata on nodes within the OpenPencil editor.

```APIDOC
## useOkHCL()

### Description
Initializes the OkHCL adapter for managing fill and stroke color intent on editor nodes.

### Methods
- **getFillOkHCLColor(node, index)**: Retrieves the OkHCL color for a specific fill index.
- **getStrokeOkHCLColor(node, index)**: Retrieves the OkHCL color for a specific stroke index.
- **updateFillOkHCL(node, index, color)**: Updates the OkHCL color for a fill, supporting undo history.
- **updateStrokeOkHCL(node, index, color)**: Updates the OkHCL color for a stroke, supporting undo history.
- **getFillPreviewInfo(node, index)**: Returns preview information including color space and gamut clipping status for a fill.
- **getStrokePreviewInfo(node, index)**: Returns preview information including color space and gamut clipping status for a stroke.
- **getFieldFormat(node, index, type)**: Gets the current field format for a fill or stroke.
- **setFillFieldFormat(node, index, format)**: Sets the field format for a fill.
- **setStrokeFieldFormat(node, index, format)**: Sets the field format for a stroke.

### Properties
- **fieldOptions**: Available options for building format selectors.
```

--------------------------------

### Implementing FillRoot in Vue

Source: https://openpencil.dev/programmable/sdk/api/components/fill-root

Demonstrates using FillRoot to manage fill state and trigger category conversions via the default slot.

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { Fill } from '@open-pencil/scene-graph'
import { FillRoot } from '@open-pencil/vue'

const fill = ref<Fill>({
  type: 'SOLID',
  color: { r: 0.2, g: 0.5, b: 0.9, a: 1 },
  opacity: 1,
  visible: true
})
</script>

<template>
  <FillRoot :fill="fill" @update="fill = $event" v-slot="model">
    <button @click="model.actions.toGradient">Gradient</button>
  </FillRoot>
</template>
```

--------------------------------

### Implement a basic PropertySection

Source: https://openpencil.dev/programmable/sdk/api/components/property-section

Use PropertySectionRoot to manage the collapsible state and wrap header and content components.

```vue
<script setup lang="ts">
import {
  PropertySectionContent,
  PropertySectionHeader,
  PropertySectionRoot,
  PropertySectionTitle
} from '@open-pencil/vue'
</script>

<template>
  <PropertySectionRoot default-open>
    <PropertySectionHeader>
      <PropertySectionTitle>Layout</PropertySectionTitle>
    </PropertySectionHeader>
    <PropertySectionContent>Panel fields</PropertySectionContent>
  </PropertySectionRoot>
</template>
```

--------------------------------

### Define Penpot Type System Structure

Source: https://openpencil.dev/overview/comparison

Outlines the distributed type definition files and modular organization in Penpot.

```clojure
;; 20+ type definition files in common/src/app/common/types/
;; shapes_builder.cljc, shapes_helpers.cljc
;; Separate type systems for: color, component, container, fills,
;; grid, modifiers, objects_map, page, path, etc.
```

--------------------------------

### Import useFillControls

Source: https://openpencil.dev/programmable/sdk/api/composables/use-fill-controls

Import the useFillControls composable from the OpenPencil Vue SDK. This is the initial step to using its features.

```typescript
import { useFillControls } from '@open-pencil/vue'

const fills = useFillControls()
```

--------------------------------

### Basic usage of useColorModel

Source: https://openpencil.dev/programmable/sdk/api/composables/use-color-model

Initializes the color model with a reactive color reference and an update callback to sync changes.

```ts
import { ref } from 'vue'
import { useColorModel } from '@open-pencil/vue'
import type { Color } from '@open-pencil/scene-graph'

const color = ref<Color>({ r: 0.25, g: 0.5, b: 0.9, a: 1 })

const model = useColorModel({
  color,
  onUpdate: (nextColor) => {
    color.value = nextColor
  },
})

model.updateHSLChannel('s', 72)
model.updateAlpha(0.8)
```

--------------------------------

### List design variables

Source: https://openpencil.dev/reference/cli

Use this command to list design variables and collections from a file.

```sh
openpencil variables [file] [options]
```

--------------------------------

### Export Designs to JSX via CLI

Source: https://openpencil.dev/programmable/jsx-renderer

Convert existing design files into JSX format using the OpenPencil CLI.

```sh
openpencil export design.fig -f jsx                   # OpenPencil format
openpencil export design.fig -f jsx --style tailwind  # Tailwind classes
```
Tokens:
Raw