# FBoard

- Human documentation: [https://docs.univer.ai/reference/facade/board](https://docs.univer.ai/reference/facade/board)

- Agent Markdown: [https://docs.univer.ai/reference/facade/board.md](https://docs.univer.ai/reference/facade/board.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/board.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/board.mdx)

---

The facade class for a board unit.

This facade is the recommended entry point for agents and integrations that create or edit board content. Prefer
element ids for later references and batch APIs when creating or updating
multiple elements. Facade mutations go through the board command layer, so collaboration, undo/redo, validation, and
container invariants follow the same path as UI operations.

Persist returned element ids in the caller's own state when later edits need to address the same elements. The facade
does not provide semantic-key indexes or implicit idempotent creation.
Avoid chaining many single-element mutations when generating diagrams. Prefer `insertShapes()`,
`insertConnectors()`, and other batch helpers so related edits travel as compact batch mutations with compact
undo/redo history.

## Access

Access through:

* [`FUniver.createBoard()`](https://docs.univer.ai/reference/facade/univer.md#createboard)
* [`FUniver.getActiveBoard()`](https://docs.univer.ai/reference/facade/univer.md#getactiveboard)
* [`FUniver.getBoard()`](https://docs.univer.ai/reference/facade/univer.md#getboard)
* [`FCollaboration.loadBoardAsync()`](https://docs.univer.ai/reference/facade/collaboration.md#loadboardasync)

## Setup

Register [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) or a preset that includes it. In plugin mode, import `@univerjs-pro/boards/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/guides/boards/getting-started/facade.md).

## `@univerjs-pro/boards`

### `FBoard.addElement`

Adds one fully constructed board element through the command layer.

This is a low-level escape hatch for code that already has an `IBoardPageElement`. Agent scripts should prefer
`insertShapes()`, `insertConnector()`, `createContainer()`, or `createSwimlane()` because those APIs are more
higher-level and harder to misuse.

```typescript
addElement(element: IBoardPageElement, options?: IBoardFacadeAddElementOptions): boolean
```

**Parameters**

* `element` — Required. Fully constructed board element.
* `options` — Optional. Default: `{}`. Insert options such as `insertIndex`.

**Returns**

`true` when the element passes local invariants and the command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const seed = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 120, top: 120 },
  name: 'Seed',
})

if (!seed) throw new Error('Cannot create seed shape')

const source = board.getElement(seed.getId())
if (!source) throw new Error('Cannot read seed shape')
const rawId = `${source.id}-copy`
const added = board.addElement({
  ...source,
  id: rawId,
  transform: { ...source.transform, left: 320 },
})
if (!added) throw new Error('Cannot add raw shape')

console.log(rawId)
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeAddElementOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.addElements`

Adds multiple fully constructed board elements in one command.

This keeps collaboration traffic and undo history compact when callers already own valid element models. Agent
scripts that are creating new shapes or connectors should prefer `insertShapes()` and `insertConnectors()`.

```typescript
addElements(elements: IBoardPageElement[], options?: IBoardFacadeAddElementsOptions): boolean
```

**Parameters**

* `elements` — Required. Fully constructed board elements.
* `options` — Optional. Default: `{}`. Batch insert options such as `insertIndex`, `fitContainerId`.

**Returns**

`true` when all elements pass local invariants and the command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 80 } },
])
const elements = shapes
  ?.map((shape) => board.getElement(shape.getId()))
  .filter((element) => element !== null)
if (
  !shapes ||
  !elements ||
  elements.length !== shapes.length ||
  !board.removeElements(shapes.map((shape) => shape.getId()))
) {
  throw new Error('Cannot prepare elements')
}
if (!board.addElements(elements)) throw new Error('Cannot add elements')
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeAddElementsOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.addSwimlaneLane`

Adds a lane to a swimlane container.

The lane is inserted at `options.insertIndex` or appended when omitted. Lane order is normalized after insertion.

```typescript
addSwimlaneLane(containerId: string, lane: IBoardFacadeSwimlaneLane, options?: IBoardFacadeAddSwimlaneLaneOptions): boolean
```

**Parameters**

* `containerId` — Required. Swimlane container id.
* `lane` — Required. Lane model to add.
* `options` — Optional. Default: `{}`. Optional insert index.

**Returns**

`true` when the lane is added.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const swimlaneId = `swimlane-${Date.now()}`
if (
  !board.createSwimlane({
    id: swimlaneId,
    left: 80,
    top: 80,
    lanes: [{ id: 'todo', title: 'Todo' }],
  }) ||
  !board.addSwimlaneLane(swimlaneId, { id: 'done', title: 'Done', size: 200, order: 1 })
) {
  throw new Error('Cannot add lane')
}
```

**Types:** [`IBoardFacadeSwimlaneLane`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`IBoardFacadeAddSwimlaneLaneOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.alignElements`

Aligns at least two elements against their combined resolved bounds.

```typescript
alignElements(elementIds: string[], alignment: BoardFacadeElementAlignment): boolean
```

**Parameters**

* `elementIds` — Required. Existing element ids.
* `alignment` — Required. Edge or center alignment mode.

**Returns**

`true` when at least one element moves and the batch succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const nodes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 160 } },
])
if (
  !nodes ||
  !board.alignElements(
    nodes.map((node) => node.getId()),
    'left',
  )
) {
  throw new Error('Cannot align nodes')
}
```

**Types:** [`BoardFacadeElementAlignment`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.analyzeModelLayout`

Detects model-visible Board layout conflicts on the active page.

Model analysis can inspect persisted manual connector paths. Auto-routed connectors without persisted route
points are reported as unresolved; a UI host can use rendered analysis for their final paths.

```typescript
analyzeModelLayout(focusPadding?: number): AnalyzeBoardModelLayoutResult
```

**Parameters**

* `focusPadding` — Optional. Padding added to each issue's suggested screenshot bounds.

**Returns**

Structured layout issues, or `false` when the command cannot run.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const analysis = board.analyzeModelLayout(48)
if (!analysis) throw new Error('Cannot analyze the active board')

const blockingIssues = analysis.issues.filter((issue) => issue.severity === 'error')
console.log({ blockingIssues, unresolved: analysis.summary.unresolvedConnectorCount })
```

**Types:** [`AnalyzeBoardModelLayoutResult`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.arrangeElements`

Arranges elements in their supplied order, preserving their current sizes.

```typescript
arrangeElements(elementIds: string[], options: IBoardFacadeArrangeElementsOptions): boolean
```

**Parameters**

* `elementIds` — Required. Existing element ids in visual order.
* `options` — Required. Direction, gap, and optional starting point.

**Returns**

`true` when at least one element moves and the batch succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 180 } },
])
if (
  !shapes ||
  !board.arrangeElements(
    shapes.map((shape) => shape.getId()),
    { direction: 'horizontal', gap: 60 },
  )
) {
  throw new Error('Cannot arrange shapes')
}
```

**Types:** [`IBoardFacadeArrangeElementsOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.arrangeElementsInCircle`

Arranges elements around a circle in their supplied order.

```typescript
arrangeElementsInCircle(elementIds: string[], options: IBoardFacadeArrangeElementsInCircleOptions): boolean
```

**Parameters**

* `elementIds` — Required. Existing element ids in circular order.
* `options` — Required. Circle center, radius, start angle, and direction.

**Returns**

`true` when the geometry is valid and the batch succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Ellipse, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Ellipse, transform: { left: 280, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Ellipse, transform: { left: 480, top: 80 } },
])
if (
  !shapes ||
  !board.arrangeElementsInCircle(
    shapes.map((shape) => shape.getId()),
    {
      center: { x: 400, y: 300 },
      radius: 180,
    },
  )
)
  throw new Error('Cannot arrange circle')
```

**Types:** [`IBoardFacadeArrangeElementsInCircleOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.arrangeElementsInGrid`

Arranges elements in their supplied order into a row-major grid.

```typescript
arrangeElementsInGrid(elementIds: string[], options: IBoardFacadeArrangeElementsInGridOptions): boolean
```

**Parameters**

* `elementIds` — Required. Existing element ids in row-major order.
* `options` — Required. Column count, gaps, and optional starting point.

**Returns**

`true` when at least one element moves and the batch succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 180 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 480, top: 280 } },
])
if (
  !shapes ||
  !board.arrangeElementsInGrid(
    shapes.map((shape) => shape.getId()),
    { columns: 2 },
  )
) {
  throw new Error('Cannot arrange grid')
}
```

**Types:** [`IBoardFacadeArrangeElementsInGridOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.arrangeElementsInLayers`

Arranges explicitly supplied element layers for flowcharts and dependency diagrams.

Each inner array is rendered in its supplied visual order. Layers flow top-to-bottom by default, or left-to-right
when `direction` is `horizontal`.

```typescript
arrangeElementsInLayers(layers: string[][], options?: IBoardFacadeArrangeElementsInLayersOptions): boolean
```

**Parameters**

* `layers` — Required. Element ids grouped into ordered visual layers.
* `options` — Optional. Default: `{}`. Flow direction, layer/item gaps, alignments, and optional starting point.

**Returns**

`true` when all ids are unique and valid and the batch succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const nodes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Diamond, transform: { left: 280, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 480, top: 40 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 480, top: 180 } },
])
if (!nodes) throw new Error('Cannot insert flowchart nodes')
const [start, decision, approved, rejected] = nodes
const arranged = board.arrangeElementsInLayers(
  [[start.id], [decision.id], [approved.id, rejected.id]],
  { direction: 'horizontal', layerGap: 140, itemGap: 100 },
)
if (!arranged) throw new Error('Cannot arrange flowchart')
```

**Types:** [`IBoardFacadeArrangeElementsInLayersOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.beginExport`

Starts the host-configured Board export flow for this board.

Export rendering and file delivery are owned by the registered export adapter. This facade method only supplies
stable board context and an optional target hint, so UI, service, and SDK callers share the same operation.

```typescript
beginExport(targetType?: 'image' | 'pdf' | string): boolean
```

**Parameters**

* `targetType` — Optional. Optional adapter target such as `image`, `pdf`, or a host-supported format.

**Returns**

`true` when a registered adapter accepts the request.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const opened = board.beginExport('image')
console.log(opened)
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.beginImport`

Starts the host-configured Board import flow for this board.

This method delegates to the registered import adapter; it does not parse files in the model package. Hosts may
open a picker, display an import dialog, or route to an exchange service. Agents that already own structured Board
content should use the element insertion APIs instead of this interactive adapter entry point.

```typescript
beginImport(sourceType?: string): boolean
```

**Parameters**

* `sourceType` — Optional. Optional adapter hint such as `mermaid`, `pptx`, or another host-supported source type.

**Returns**

`true` when a registered adapter accepts the request.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const opened = board.beginImport('mermaid')
console.log(opened)
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.bringElementsForward`

Moves elements one z-order step forward.

```typescript
bringElementsForward(elementIds: string[]): boolean
```

**Parameters**

* `elementIds` — Required. Existing element ids.

**Returns**

`true` when the order changes successfully.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 120, top: 120 } },
])
if (!shapes || !board.bringElementsForward([shapes[0].getId()]))
  throw new Error('Cannot move shape forward')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.bringElementsToFront`

Brings elements to the front.

```typescript
bringElementsToFront(elementIds: string[]): boolean
```

**Parameters**

* `elementIds` — Required. Existing element ids.

**Returns**

`true` when the order changes successfully.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 120, top: 120 } },
])
if (!shapes || !board.bringElementsToFront([shapes[0].getId()]))
  throw new Error('Cannot bring shape to front')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.checkElementIds`

Checks a list of generated board element ids and returns a structured preflight result.

Use this when an integration starts from UI selection ids or event payload ids and wants to verify all referenced
elements still exist before mapping them back to generated ids or running low-level commands.

```typescript
checkElementIds(elementIds: string[]): IBoardFacadeElementIdCheckResult
```

**Parameters**

* `elementIds` — Required. Generated board element ids.

**Returns**

Requested ids, existing ids, missing ids, and an `allExist` boolean.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.checkElementIds([shape.getId(), 'missing-element']))
```

**Types:** [`IBoardFacadeElementIdCheckResult`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.checkElementIdTypes`

Checks generated board element ids against expected board element types.

Use this before type-specific low-level integrations that start from UI selection ids. It separates missing ids
from ids that still exist but point to the wrong element type.

```typescript
checkElementIdTypes(elementIds: string[], expectedTypes: BoardElementType | BoardElementType[]): IBoardFacadeElementIdTypeCheckResult
```

**Parameters**

* `elementIds` — Required. Generated board element ids.
* `expectedTypes` — Required. Allowed board element type or types.

**Returns**

Requested ids, matching ids, missing ids, mismatched ids, and an `allMatch` boolean.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.checkElementIdTypes([shape.getId()], univerAPI.Enum.BoardElementType.Shape))
```

**Types:** [`IBoardFacadeElementIdTypeCheckResult`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`BoardElementType`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.clearBackground`

Clears the active Board page background and restores the theme-aware canvas fill.

```typescript
clearBackground(): this
```

**Returns**

This board, for chaining.

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.createContainer`

Creates a generic, UML package, or system-boundary container.

Containers can group elements and optionally auto-capture/membership-lock children depending on the provided
container options. Give agent-created containers generated ids so later scripts can move children into them.

```typescript
createContainer(options: IBoardFacadeCreateContainerOptions): boolean
```

**Parameters**

* `options` — Required. Container creation options.

**Returns**

`true` when the container is created through the command layer.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (
  !board.createContainer({
    id: containerId,
    kind: univerAPI.Enum.BoardContainerKind.SystemBoundary,
    left: 80,
    top: 80,
    title: 'Planning',
  })
) {
  throw new Error('Cannot create container')
}
```

**Types:** [`IBoardFacadeCreateContainerOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.createSwimlane`

Creates a swimlane container.

Use this for process maps, responsibility diagrams, or timelines. Provide lane ids that are meaningful to the
agent, such as `todo`, `doing`, and `done`, so later lane operations are readable.

```typescript
createSwimlane(options: IBoardFacadeCreateSwimlaneOptions): boolean
```

**Parameters**

* `options` — Required. Swimlane creation options.

**Returns**

`true` when the swimlane is created through the command layer.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const swimlaneId = `swimlane-${Date.now()}`
if (
  !board.createSwimlane({
    id: swimlaneId,
    left: 80,
    top: 80,
    title: 'Workflow',
    lanes: [
      { id: 'todo', title: 'Todo' },
      { id: 'done', title: 'Done' },
    ],
  })
)
  throw new Error('Cannot create swimlane')
```

**Types:** [`IBoardFacadeCreateSwimlaneOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.describeElement`

Describes one board element as a compact agent-friendly summary.

Use this when an agent needs to inspect an element without depending on the full internal model. The descriptor
includes generated element id, resolved metadata, parent id, local transform, and world bounds,
but it does not include heavy payloads such as `shapeData` or `connectorData`.

Agent scripts should prefer `describeElement()` when element ids are known; use this id-based
method only for UI selection ids, event payload ids, or low-level integrations.

```typescript
describeElement(elementId: string): IBoardFacadeElementDescriptor | null
```

**Parameters**

* `elementId` — Required. Generated board element id.

**Returns**

Compact element descriptor, or `null` when the element is missing.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.describeElement(shape.getId()))
```

**Types:** [`IBoardFacadeElementDescriptor`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.describeElements`

Describes matching board elements as compact agent-friendly summaries.

This is the recommended discovery API for agents before they modify a board. It returns descriptors in board
z-order, supports the same filters as `findElements()`, and avoids exposing large internal element payloads in
prompts or tool results.

```typescript
describeElements(query?: IBoardFacadeElementQuery): IBoardFacadeElementDescriptor[]
```

**Parameters**

* `query` — Optional. Default: `{}`. Optional type and visibility filters.

**Returns**

Compact descriptors in board z-order.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
console.log(board.describeElements({ elementType: univerAPI.Enum.BoardElementType.Shape }))
```

**Types:** [`IBoardFacadeElementDescriptor`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`IBoardFacadeElementQuery`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.describeElementsByIds`

Describes multiple board elements addressed by generated ids.

Use this when an integration starts from UI selection ids or event payload ids and the agent needs compact
descriptors before deciding which id-based mutation APIs to call. The returned object preserves every normalized
requested id and uses `null` when an element is missing.

```typescript
describeElementsByIds(elementIds: string[]): Record<string, IBoardFacadeElementDescriptor | null>
```

**Parameters**

* `elementIds` — Required. Generated board element ids.

**Returns**

An id-to-descriptor map that preserves requested ids and uses `null` for missing elements.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.describeElementsByIds([shape.getId()]))
```

**Types:** [`IBoardFacadeElementDescriptor`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.disbandContainer`

Disbands a container while preserving its children.

This is useful when an agent decides a grouping container is no longer semantically meaningful. The method refuses
blocked containers and containers whose parent membership rules prevent disbanding.

```typescript
disbandContainer(containerId: string): boolean
```

**Parameters**

* `containerId` — Required. Container id to disband.

**Returns**

`true` when the disband command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (
  !board.createContainer({ id: containerId, left: 80, top: 80 }) ||
  !board.disbandContainer(containerId)
) {
  throw new Error('Cannot disband container')
}
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.distributeElements`

Distributes at least three elements with equal horizontal or vertical gaps.

```typescript
distributeElements(elementIds: string[], distribution: BoardFacadeElementDistribution): boolean
```

**Parameters**

* `elementIds` — Required. Existing element ids.
* `distribution` — Required. Distribution axis.

**Returns**

`true` when at least one element moves and the batch succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 260, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 560, top: 80 } },
])
if (
  !shapes ||
  !board.distributeElements(
    shapes.map((shape) => shape.getId()),
    'horizontal',
  )
) {
  throw new Error('Cannot distribute shapes')
}
```

**Types:** [`BoardFacadeElementDistribution`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.findElements`

Finds board elements by type and visibility.

Agent examples should use `univerAPI.Enum.BoardElementType` constants for type filters so scripts remain discoverable
and typo-resistant.

```typescript
findElements(query?: IBoardFacadeElementQuery): IBoardPageElement[]
```

**Parameters**

* `query` — Optional. Default: `{}`. Query options. Omit it to list all visible elements on the active page.

**Returns**

Matching elements in board z-order.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.findElements({ elementType: univerAPI.Enum.BoardElementType.Shape })
console.log(shapes.map((shape) => shape.id))
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeElementQuery`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.fitContainerToContent`

Fits a container bounds to its current content.

Use this after an agent moves elements into a container or changes child geometry. The operation goes through the
same command path as the UI action.

```typescript
fitContainerToContent(containerId: string): boolean
```

**Parameters**

* `containerId` — Required. Container id.

**Returns**

`true` when the fit command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (!board.createContainer({ id: containerId, left: 80, top: 80 }))
  throw new Error('Cannot create container')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 120, top: 120 },
})
if (!shape || !board.reparentElements([shape.getId()], containerId))
  throw new Error('Cannot insert shape')
if (!board.fitContainerToContent(containerId)) throw new Error('Cannot fit container')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.fitElementsIntoBounds`

Fits an element group into a rectangle while optionally preserving its aspect ratio.

```typescript
fitElementsIntoBounds(elementIds: string[], bounds: IBoardRect, options?: IBoardFacadeFitElementsIntoBoundsOptions): boolean
```

**Parameters**

* `elementIds` — Required. Existing element ids.
* `bounds` — Required. Target board-coordinate rectangle.
* `options` — Optional. Default: `{}`. Aspect-ratio behavior.

**Returns**

`true` when source and target bounds are valid and the batch succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 180 } },
])
if (
  !shapes ||
  !board.fitElementsIntoBounds(
    shapes.map((shape) => shape.getId()),
    {
      left: 100,
      top: 100,
      width: 640,
      height: 360,
    },
  )
)
  throw new Error('Cannot fit shapes')
```

**Types:** [`IBoardRect`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/utils/board-container-transform.util.d.ts) · [`IBoardFacadeFitElementsIntoBoundsOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getBackground`

Gets the active Board page background as detached data.

```typescript
getBackground(): IBoardBackgroundData | undefined
```

**Returns**

The explicit background, or `undefined` when the page uses the default canvas background.

**Types:** [`IBoardBackgroundData`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getConnectorConnection`

Returns detached endpoint and routing data for one connector.

```typescript
getConnectorConnection(elementId: string): IBoardFacadeConnectorConnection | null
```

**Parameters**

* `elementId` — Required. Existing connector id.

**Returns**

Detached connection data, or `null` when the id is missing or not a connector.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 320, top: 80 } },
])
if (!shapes) throw new Error('Cannot insert shapes')
const connector = board.insertConnector({
  fromElementId: shapes[0].getId(),
  toElementId: shapes[1].getId(),
})
if (!connector) throw new Error('Cannot insert connector')
console.log(board.getConnectorConnection(connector.id))
```

**Types:** [`IBoardFacadeConnectorConnection`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getConnectorLabels`

Returns a detached copy of connector labels in rendering order, including rich document content.
Mutating the result does not change the Board; use `setConnectorLabels` or `updateConnectorLabel` to write.

```typescript
getConnectorLabels(elementId: string): IBoardConnectorLabel[]
```

**Parameters**

* `elementId` — Required. Connector id on the active page.

**Returns**

Labels synchronously, or an empty array if there are none or the id is not a connector.

**Examples**

```ts
const labels = board.getConnectorLabels(connectorId)
const labelIds = labels.map((label) => label.id)
```

**Types:** [`IBoardConnectorLabel`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getConnectorLabelStyle`

Gets the detached visual style of one connector label.

Label appearance is separate from rich-text formatting. `fill` and `stroke` style the label box, while
`interruptLine` controls whether the connector route is visually interrupted behind the label. Missing `fill` means
transparent, missing `stroke` means no border, and missing `interruptLine` means the route is interrupted.

```typescript
getConnectorLabelStyle(elementId: string): IBoardConnectorLabelStyle | null
```

**Parameters**

* `elementId` — Required. Existing connector id.

**Returns**

Detached label style, or `null` when the connector or label is missing.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const style = board.getConnectorLabelStyle('connector-id')
if (style) console.log(style.fill?.color, style.stroke?.color, style.interruptLine ?? true)
```

**Types:** [`IBoardConnectorLabelStyle`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getConnectorLabelText`

Gets one connector label as a detached rich-text value.

The returned value never mutates the Board directly. Call `copy()` to obtain the shared Univer
`RichTextBuilder`, update the builder, and pass it to `setConnectorLabelText()` to commit the change through the
Board command layer. This is the same value/builder flow used by other Univer rich-text facade APIs.

```typescript
getConnectorLabelText(elementId: string): RichTextValue | null
```

**Parameters**

* `elementId` — Required. Existing connector id.

**Returns**

Detached label text, or `null` when the connector or label is missing.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 320, top: 80 } },
])
if (!shapes) throw new Error('Cannot insert shapes')
const connector = board.insertConnector({
  fromElementId: shapes[0].getId(),
  toElementId: shapes[1].getId(),
  labelText: 'Next',
})
if (!connector) throw new Error('Cannot insert connector')

const value = board.getConnectorLabelText(connector.id)
const builder = value?.copy()
if (!builder) throw new Error('Connector label is missing')
builder.setStyle(0, builder.toPlainText().length, {
  fs: 16,
  bl: univerAPI.Enum.BooleanNumber.TRUE,
  cl: { rgb: '#2563eb' },
})
if (!board.setConnectorLabelText(connector.id, builder)) throw new Error('Cannot style label')
```

**Types:** [`RichTextValue`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/data-model/rich-text-builder.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getConnectorStyle`

Returns a detached connector style snapshot.

```typescript
getConnectorStyle(elementId: string): IBoardFacadeConnectorStylePatch | null
```

**Parameters**

* `elementId` — Required. Existing connector id.

**Returns**

Editable connector style, or `null` when the id is missing or not a connector.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 320, top: 80 } },
])
if (!shapes) throw new Error('Cannot insert shapes')
const connector = board.insertConnector({
  fromElementId: shapes[0].getId(),
  toElementId: shapes[1].getId(),
})
if (!connector) throw new Error('Cannot insert connector')
console.log(board.getConnectorStyle(connector.id))
```

**Types:** [`IBoardFacadeConnectorStylePatch`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getContainerChildren`

Gets direct children of a container in board z-order.

This only returns direct members whose `parentId` equals `containerId`. Use `getContainerDescendants()` when an
agent needs nested container content.

Agent scripts should prefer `getContainerChildren()` when element ids are known; use this id-based
method only for UI selection ids, event payload ids, or low-level integrations.

```typescript
getContainerChildren(containerId: string): IBoardPageElement[]
```

**Parameters**

* `containerId` — Required. Container element id.

**Returns**

Direct child elements. Returns an empty array for missing or non-container elements.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (!board.createContainer({ id: containerId, left: 80, top: 80 }))
  throw new Error('Cannot create container')
const child = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 120, top: 120 },
})
if (!child || !board.reparentElements([child.getId()], containerId))
  throw new Error('Cannot insert child')
console.log(board.getContainerChildren(containerId))
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getContainerDescendants`

Gets all nested descendants of a container in traversal order.

The traversal follows direct children in board z-order and then walks nested containers. It guards against cycles so
agent scripts can inspect imperfect imported content without hanging.

Agent scripts should prefer `getContainerDescendants()` when element ids are known; use this id-based
method only for UI selection ids, event payload ids, or low-level integrations.

```typescript
getContainerDescendants(containerId: string): IBoardPageElement[]
```

**Parameters**

* `containerId` — Required. Container element id.

**Returns**

Nested child elements. Returns an empty array for missing or empty containers.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (!board.createContainer({ id: containerId, left: 80, top: 80 }))
  throw new Error('Cannot create container')
const child = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 120, top: 120 },
})
if (!child || !board.reparentElements([child.getId()], containerId))
  throw new Error('Cannot insert child')
console.log(board.getContainerDescendants(containerId))
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getContainerStyle`

Returns a detached container-style snapshot.

```typescript
getContainerStyle(elementId: string): IBoardFacadeContainerStyle | null
```

**Parameters**

* `elementId` — Required. Existing container id.

**Returns**

Editable frame/title style, or `null` when the id is missing or not a container.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (!board.createContainer({ id: containerId, left: 80, top: 80 }))
  throw new Error('Cannot create container')
console.log(board.getContainerStyle(containerId))
```

**Types:** [`IBoardFacadeContainerStyle`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getData`

Gets the current in-memory board snapshot.

This does not force resource serialization. Use `save()` when you need a persisted snapshot with resource data.
The returned serialization snapshot is detached: changing it cannot mutate the live board. For ordinary board
inspection, prefer `describeElements()` or other id-based reads.

```typescript
getData(): IBoardData
```

**Returns**

The current board data.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const data = board.getData()
console.log(data.name, Object.keys(data.pages ?? {}).length)
```

**Types:** [`IBoardData`](https://docs.univer.ai/reference/types/board-data.md)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElement`

Gets one element by generated id.

This low-level read returns a detached model snapshot. Changing it cannot mutate the live board; use
`updateElement()` or an intent-specific mutation method to apply changes.

```typescript
getElement(elementId: string): IBoardPageElement | null
```

**Parameters**

* `elementId` — Required. Generated board element id.

**Returns**

The element, or `null` when it is missing.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape || !board.getElement(shape.getId())) throw new Error('Cannot read inserted shape')
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementBounds`

Reads one board element's resolved bounds by generated id.

Use this when code starts from a UI selection id and only needs board-coordinate bounds for layout, collision,
or viewport calculations. This is lighter than `describeElement()` because it returns only the resolved bounds.

Agent scripts should prefer `getElementBounds()` when element ids are known; use this id-based
method only for UI selection ids, event payload ids, or low-level integrations.

```typescript
getElementBounds(elementId: string): IBoardRect | null
```

**Parameters**

* `elementId` — Required. Generated board element id.

**Returns**

Resolved board-coordinate bounds, or `null` when the element is missing.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.getElementBounds(shape.getId()))
```

**Types:** [`IBoardRect`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/utils/board-container-transform.util.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementCenter`

Reads one board element's center point by generated id.

Use this when code starts from a UI selection id and needs a stable board-coordinate point for connector
endpoints, relative placement, or distance calculations. The center is derived from resolved world bounds, so it
accounts for parent container transforms.

Agent scripts should prefer `getElementCenter()` when element ids are known; use this id-based
method only for UI selection ids, event payload ids, or low-level integrations.

```typescript
getElementCenter(elementId: string): IBoardFacadePoint | null
```

**Parameters**

* `elementId` — Required. Generated board element id.

**Returns**

Center point in board coordinates, or `null` when the element is missing.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.getElementCenter(shape.getId()))
```

**Types:** [`IBoardFacadePoint`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementGeometry`

Reads one board element's lightweight geometry by generated id.

Use this when code starts from a UI selection id and needs both resolved bounds and center point. It is lighter
than `describeElement()` and avoids making agents call separate bounds and center APIs.

Agent scripts should prefer `getElementGeometry()` when element ids are known; use this id-based
method only for UI selection ids, event payload ids, or low-level integrations.

```typescript
getElementGeometry(elementId: string): IBoardFacadeElementGeometry | null
```

**Parameters**

* `elementId` — Required. Generated board element id.

**Returns**

Geometry snapshot, or `null` when the element is missing.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.getElementGeometry(shape.getId()))
```

**Types:** [`IBoardFacadeElementGeometry`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementIdsInOrder`

Gets generated board element ids in board z-order with optional facade filters.

Use this narrow helper when an id-based integration needs ordered ids but the script still wants the same type,
visibility filters supported by `findElements()`. Prefer `getElementIdsInOrder()` for prompts
and saved agent plans.

```typescript
getElementIdsInOrder(query?: IBoardFacadeElementQuery): string[]
```

**Parameters**

* `query` — Optional. Default: `{}`. Optional type and visibility filters.

**Returns**

Generated element ids in board z-order.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const visibleShapeIds = board.getElementIdsInOrder({
  elementTypes: [univerAPI.Enum.BoardElementType.Shape],
})

console.log(visibleShapeIds)
```

**Types:** [`IBoardFacadeElementQuery`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementLayout`

Returns the active Board page's element layout in Board model coordinates.

This is a model-only query. It does not depend on a Scene, viewport,
scroll position, zoom, Canvas, DOM, or a UI plugin. Because Board is an
infinite canvas, the result intentionally has no finite container bounds.

```typescript
getElementLayout(): IBoardFacadeElementLayoutResult
```

**Returns**

Ordered element bounds and their union.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const layout = board.getElementLayout()
console.log(layout.subUnitId, layout.contentBounds)
```

**Types:** [`IBoardFacadeElementLayoutResult`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementMetadata`

Gets resolved top-level metadata for an element.

The returned booleans use board defaults: `visible` and `selectable` default to `true`, while `locked` defaults to
`false`. This is easier for agents than reading raw optional model fields.

Agent scripts should prefer `getElementMetadata()` when element ids are known; use this id-based
method only for UI selection ids, event payload ids, or low-level integrations.

```typescript
getElementMetadata(elementId: string): IBoardFacadeElementMetadata | null
```

**Parameters**

* `elementId` — Required. Generated board element id.

**Returns**

Resolved metadata, or `null` when the element is missing.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.getElementMetadata(shape.getId()))
```

**Types:** [`IBoardFacadeElementMetadata`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementOrder`

Gets generated element ids in the current board z-order.

This is a low-level order API. Use it when a UI integration or import/export pipeline must preserve the raw page
order. Agent scripts should prefer `getElementIdsInOrder()` for generated element ids or `describeElements()` for
type, metadata, and z-order in one descriptor list.

```typescript
getElementOrder(): string[]
```

**Returns**

Ordered generated element ids. Returns an empty array when the page does not exist.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
console.log(board.getElementOrder())
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementParentChain`

Gets the parent container chain for an element.

The first id is the direct parent, followed by ancestors. This is useful when an agent needs to understand whether
an element is inside a group, generic container, or swimlane before moving or deleting it.

Agent scripts should prefer `getElementParentChain()` when element ids are known; use this id-based
method only for UI selection ids, event payload ids, or low-level integrations.

```typescript
getElementParentChain(elementId: string): string[]
```

**Parameters**

* `elementId` — Required. Element id to inspect.

**Returns**

Parent container ids from nearest to farthest.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (!board.createContainer({ id: containerId, left: 80, top: 80 }))
  throw new Error('Cannot create container')
const child = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 120, top: 120 },
})
if (!child || !board.reparentElements([child.getId()], containerId))
  throw new Error('Cannot insert child')
console.log(board.getElementParentChain(child.getId()))
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementPermission`

Returns the permission facade for one stable Board element id.

The Board's single page id remains an internal address component and is resolved automatically.

```typescript
getElementPermission(elementId: string): FBoardElementPermission
```

**Parameters**

* `elementId` — Required. Stable Board element id.

**Returns**

Permission facade combining the Board and Element Edit points.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active Board.')
const element = Object.values(board.getElements())[0]
if (!element) throw new Error('Board element not found.')
await board.getElementPermission(element.id).setReadOnly()
```

**Types:** [`FBoardElementPermission`](https://docs.univer.ai/reference/facade/board-element-permission.md)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElements`

Gets all elements on the Board as an id-to-element map.

Use `getElementOrder()` when iteration order matters.
This low-level read returns detached model snapshots. For agent reasoning over board content, prefer
`describeElements()` or id-based descriptor APIs so scripts do not depend on internal element payloads.

```typescript
getElements(): Record<string, IBoardPageElement>
```

**Returns**

Element map in Board z-order, or an empty object when the Board is empty.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
console.log(Object.keys(board.getElements()))
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementsBoundingRect`

Reads the union bounds for all board elements matching a facade query.

Use this when an agent needs the overall occupied board rectangle for visible content, a group, a type
subset, or another query without first collecting ids. It uses the same filters as `describeElements()`,
including default hidden-element filtering.

```typescript
getElementsBoundingRect(query?: IBoardFacadeElementQuery): IBoardRect | null
```

**Parameters**

* `query` — Optional. Default: `{}`. Optional type and visibility filters.

**Returns**

Union bounds for matching elements, or `null` when the query matches no bounded elements.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
console.log(board.getElementsBoundingRect({ elementType: univerAPI.Enum.BoardElementType.Shape }))
```

**Types:** [`IBoardRect`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/utils/board-container-transform.util.d.ts) · [`IBoardFacadeElementQuery`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementsBoundingRectByIds`

Reads the union bounds for multiple board elements addressed by generated ids.

Use this after a UI selection when an agent needs the group's overall board-coordinate rectangle for centering,
spacing, collision checks, or viewport fitting. Missing ids are ignored; `null` means none of the requested ids
resolved to elements with bounds.

```typescript
getElementsBoundingRectByIds(elementIds: string[]): IBoardRect | null
```

**Parameters**

* `elementIds` — Required. Generated board element ids.

**Returns**

Union bounds for existing elements, or `null` when no requested id resolves.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 160 } },
])
if (!shapes) throw new Error('Cannot insert shapes')
console.log(board.getElementsBoundingRectByIds(shapes.map((shape) => shape.getId())))
```

**Types:** [`IBoardRect`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/utils/board-container-transform.util.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementsBoundsByIds`

Reads resolved bounds for multiple board elements addressed by generated ids.

The returned object preserves every normalized requested id and uses `null` for missing elements. Use this after
a UI multi-selection when an agent wants to compute spacing or alignment without pulling full descriptors.

```typescript
getElementsBoundsByIds(elementIds: string[]): Record<string, IBoardRect | null>
```

**Parameters**

* `elementIds` — Required. Generated board element ids.

**Returns**

An id-to-bounds map that preserves requested ids and uses `null` for missing elements.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.getElementsBoundsByIds([shape.getId()]))
```

**Types:** [`IBoardRect`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/utils/board-container-transform.util.d.ts) · [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementsByIds`

Gets multiple elements by generated ids.

This is a low-level escape hatch for framework integrations that already have generated ids. Agent scripts should
usually prefer `describeElementsByIds()` or id-based APIs because raw elements include internal board model
payloads.

```typescript
getElementsByIds(elementIds: string[]): Record<string, IBoardPageElement | null>
```

**Parameters**

* `elementIds` — Required. Generated board element ids.

**Returns**

An id-to-element map that preserves requested ids and uses `null` for missing elements.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.getElementsByIds([shape.getId(), 'missing-element']))
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementsCentersByIds`

Reads center points for multiple board elements addressed by generated ids.

The returned object preserves every normalized requested id and uses `null` for missing elements. Use this after
UI multi-selection when an agent wants anchor points without pulling full descriptors.

```typescript
getElementsCentersByIds(elementIds: string[]): Record<string, IBoardFacadePoint | null>
```

**Parameters**

* `elementIds` — Required. Generated board element ids.

**Returns**

An id-to-center map that preserves requested ids and uses `null` for missing elements.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.getElementsCentersByIds([shape.getId()]))
```

**Types:** [`IBoardFacadePoint`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementsGeometry`

Reads lightweight geometry descriptors for all board elements matching a facade query.

Use this when an agent needs identity, type, z-order, bounds, and center point for matching elements without the
heavier text and metadata payload in `describeElements()`. Results preserve board z-order and use the
same filters as `describeElements()`.

```typescript
getElementsGeometry(query?: IBoardFacadeElementQuery): IBoardFacadeElementGeometryDescriptor[]
```

**Parameters**

* `query` — Optional. Default: `{}`. Optional type and visibility filters.

**Returns**

Geometry descriptors in board z-order. Elements without resolved bounds are skipped.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
console.log(board.getElementsGeometry({ elementType: univerAPI.Enum.BoardElementType.Shape }))
```

**Types:** [`IBoardFacadeElementGeometryDescriptor`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`IBoardFacadeElementQuery`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementsGeometryByIds`

Reads lightweight geometry snapshots for multiple board elements addressed by generated ids.

The returned object preserves every normalized requested id and uses `null` for missing elements. Use this after
UI multi-selection when an agent needs both bounds and centers for spacing, alignment, or connector planning.

```typescript
getElementsGeometryByIds(elementIds: string[]): Record<string, IBoardFacadeElementGeometry | null>
```

**Parameters**

* `elementIds` — Required. Generated board element ids.

**Returns**

An id-to-geometry map that preserves requested ids and uses `null` for missing elements.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.getElementsGeometryByIds([shape.getId()]))
```

**Types:** [`IBoardFacadeElementGeometry`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementsMetadataByIds`

Gets resolved top-level metadata for multiple generated board element ids.

This is the batch companion to `getElementMetadata()`. It is useful after a selection or hit-test flow where the
caller already has generated ids and wants resolved `visible`, `selectable`, and `locked` booleans without reading
raw optional model fields.

```typescript
getElementsMetadataByIds(elementIds: string[]): Record<string, IBoardFacadeElementMetadata | null>
```

**Parameters**

* `elementIds` — Required. Generated board element ids.

**Returns**

An id-to-metadata map that preserves requested ids and uses `null` for missing elements.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
console.log(board.getElementsMetadataByIds([shape.getId()]))
```

**Types:** [`IBoardFacadeElementMetadata`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getId`

Gets the board unit id.

```typescript
getId(): string
```

**Returns**

The unit id of this board.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

console.log(board.getId())
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getName`

Gets the board display name from the snapshot.

```typescript
getName(): string
```

**Returns**

The board name.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

console.log(board.getName())
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getNextAvailableBounds`

Calculates a simple empty bounds rectangle next to existing board content.

Use this before inserting a newly generated diagram, table, or group of shapes so agent output does not overlap the
current board. The method is a pure read helper: it does not create elements, dispatch commands, or reserve space.
It finds the union bounds of `query`, then places the requested rectangle to the right or below that occupied area.
When the query matches nothing, it returns the requested size at `origin`.

```typescript
getNextAvailableBounds(options: IBoardFacadeGetNextAvailableBoundsOptions): IBoardRect | null
```

**Parameters**

* `options` — Required. Desired size, spacing, placement, fallback origin, and optional occupancy query.

**Returns**

Suggested bounds in board coordinates, or `null` when size or gap values are invalid.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const bounds = board.getNextAvailableBounds({
  width: 240,
  height: 120,
  placement: univerAPI.Enum.BoardFacadeNextAvailableBoundsPlacement.Right,
})
console.log(bounds)
```

**Types:** [`IBoardRect`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/utils/board-container-transform.util.d.ts) · [`IBoardFacadeGetNextAvailableBoundsOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getPermission`

Returns the Board unit permission facade.

```typescript
getPermission(): FBoardPermission
```

**Returns**

Permission facade for Edit, Copy, Print, Export, and Comment.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active Board.')
await board.getPermission().setReadOnly()
```

**Types:** [`FBoardPermission`](https://docs.univer.ai/reference/facade/board-permission.md)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getShape`

Returns a live common Shape handle by Board element id.

```typescript
getShape(shapeId: string): FShape | FConnectorShape | null
```

**Parameters**

* `shapeId` — Required.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const inserted = board.insertShape({ shapeType: univerAPI.Enum.ShapeTypeEnum.Rect })
const shape = inserted && board.getShape(inserted.getId())
if (!shape) throw new Error('Cannot resolve Shape')
console.log(shape.getSnapshot())
```

**Types:** [`FShape`](https://docs.univer.ai/reference/facade/shape.md) · [`FConnectorShape`](https://docs.univer.ai/reference/facade/connector-shape.md)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getShapes`

Returns all live common Shape and Connector handles on the active Board page.

```typescript
getShapes(): Array<FShape | FConnectorShape>
```

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
console.log(board.getShapes().map((shape) => shape.getId()))
```

**Types:** [`FShape`](https://docs.univer.ai/reference/facade/shape.md) · [`FConnectorShape`](https://docs.univer.ai/reference/facade/connector-shape.md) · [`Array`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getTextContent`

Gets standalone text as a detached rich-text value.

```typescript
getTextContent(elementId: string): RichTextValue | null
```

**Parameters**

* `elementId` — Required. Existing standalone text id.

**Returns**

Detached rich text, or `null` when the id is missing or not standalone text.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const text = board.insertText({ text: 'Draft', left: 80, top: 80 })
if (!text) throw new Error('Cannot insert text')
console.log(board.getTextContent(text.id)?.getData())
```

**Types:** [`RichTextValue`](https://unpkg.com/@univerjs/core@1.0.0-rc.0/lib/types/docs/data-model/rich-text-builder.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getThemeData`

Gets the current board theme data.

```typescript
getThemeData(): IBoardThemeData
```

**Returns**

The active board theme.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

console.log(board.getThemeData().id, board.getThemeData().name)
```

**Types:** [`IBoardThemeData`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.id`

```typescript
readonly id: string
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertClassRelation`

Inserts a UML relationship as a native editable connector, without moving its existing endpoint shapes.
Aggregation/composition put the whole (diamond) at `start`; generalization/realization put the parent/interface
(triangle) at `end`. The name, two roles and two multiplicities become independently editable labels.

```typescript
insertClassRelation(options: IBoardFacadeInsertClassRelationOptions): IBoardPageElement | null
```

**Parameters**

* `options` — Required. Relationship type, existing endpoint ids, optional labels and insertion index.

**Returns**

The inserted element synchronously, or `null` if validation or the undoable command fails.

**Examples**

```ts
const relation = board.insertClassRelation({
  type: 'composition',
  name: 'owns',
  start: { elementId: agentId, role: 'owner', multiplicity: '1' },
  end: { elementId: toolId, role: 'tools', multiplicity: '0..*' },
})
if (!relation) throw new Error('Cannot create class relation')
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeInsertClassRelationOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertClassRelations`

Inserts UML relationships in one undoable command. Every relationship and endpoint must be valid;
otherwise nothing is inserted. Uses the endpoint and label semantics of `insertClassRelation`.
This is an insertion API, not a replacement of existing connections.

```typescript
insertClassRelations(relations: IBoardFacadeInsertClassRelationItem[], options?: IBoardFacadeInsertConnectorsOptions): IBoardPageElement[] | null
```

**Parameters**

* `relations` — Required. Relationships between shapes already on the active page.
* `options` — Optional. Default: `{}`. Optional insertion index and container fitting target.

**Returns**

Inserted elements synchronously, or `null` on invalid input or command failure.

**Examples**

```ts
const relations = board.insertClassRelations([
  { type: 'generalization', start: { elementId: agentId }, end: { elementId: baseAgentId } },
  { type: 'dependency', start: { elementId: agentId }, end: { elementId: toolId }, name: 'uses' },
])
if (!relations) throw new Error('Cannot create class relations')
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeInsertClassRelationItem`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`IBoardFacadeInsertConnectorsOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertConnector`

Inserts a connector between two elements or free points.

For agent scripts, prefer `fromElementId` and `toElementId` after obtaining ids from `insertShapes()` or discovery
methods. When endpoint sides and routing are omitted, the facade chooses facing sides and a space-aware persisted
route. The method resolves those ids to shape-site endpoints, creates the connector through the board
connector factory, and dispatches `AddBoardElementsOperation` so collaboration and undo/redo use the normal command
path without chaining facade APIs or commands.

```typescript
insertConnector(options: IBoardFacadeInsertConnectorOptions): IBoardPageElement | null
```

**Parameters**

* `options` — Required. Connector insertion options.

**Returns**

The generated connector element when the insert command succeeds, otherwise `null`.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 320, top: 80 } },
])
if (!shapes) throw new Error('Cannot insert shapes')
const connector = board.insertConnector({
  fromElementId: shapes[0].getId(),
  toElementId: shapes[1].getId(),
  style: { endMarker: { type: 'filledTriangle', size: 'md' } },
})
if (!connector) throw new Error('Cannot insert connector')
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeInsertConnectorOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertConnectors`

Inserts multiple connectors in a single board command.

Use this after `insertShapes()` when an agent creates a complete diagram. It resolves `fromElementId`/`toElementId` for each
connector, creates all connector elements, and dispatches one `addElements` command, reducing collaboration traffic
and keeping undo/redo history compact.

```typescript
insertConnectors(connectors: IBoardFacadeInsertConnectorItem[], options?: IBoardFacadeInsertConnectorsOptions): IBoardPageElement[] | null
```

**Parameters**

* `connectors` — Required. Connector items to create. Use element ids to address connectors later.
* `options` — Optional. Default: `{}`. Batch insert options such as `insertIndex`, `fitContainerId`.

**Returns**

The generated connector elements when the batch succeeds, otherwise `null`.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 320, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 560, top: 80 } },
])
if (!shapes) throw new Error('Cannot insert shapes')
const connectors = board.insertConnectors([
  {
    fromElementId: shapes[0].getId(),
    toElementId: shapes[1].getId(),
  },
  {
    fromElementId: shapes[1].getId(),
    toElementId: shapes[2].getId(),
  },
])
if (!connectors) throw new Error('Cannot insert connectors')
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeInsertConnectorItem`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`IBoardFacadeInsertConnectorsOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertEntityRelation`

Inserts a native editable crow-foot relationship. Each cardinality describes the endpoint on which it is set;
`identifying` uses a solid line and `nonIdentifying` a dashed line. Existing entities are not repositioned.

```typescript
insertEntityRelation(options: IBoardFacadeInsertEntityRelationOptions): IBoardPageElement | null
```

**Parameters**

* `options` — Required. Relationship kind, existing endpoint ids, cardinalities and optional name.

**Returns**

The inserted element synchronously, or `null` if validation or the undoable command fails.

**Examples**

```ts
const relation = board.insertEntityRelation({
  type: 'nonIdentifying',
  label: 'records',
  start: { elementId: agentId, cardinality: 'one' },
  end: { elementId: runId, cardinality: 'zeroOrMany' },
})
if (!relation) throw new Error('Cannot create entity relation')
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeInsertEntityRelationOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertEntityRelations`

Inserts crow-foot relationships atomically in one undoable command. Uses `insertEntityRelation` semantics;
it does not remove existing connections. An invalid relationship or endpoint rejects the entire batch.

```typescript
insertEntityRelations(relations: IBoardFacadeInsertEntityRelationItem[], options?: IBoardFacadeInsertConnectorsOptions): IBoardPageElement[] | null
```

**Parameters**

* `relations` — Required. Relationships between entities already on the active page.
* `options` — Optional. Default: `{}`. Optional insertion index and container fitting target.

**Returns**

Inserted elements synchronously, or `null` on invalid input or command failure.

**Examples**

```ts
const relations = board.insertEntityRelations([
  {
    type: 'identifying',
    label: 'contains',
    start: { elementId: runId, cardinality: 'one' },
    end: { elementId: stepId, cardinality: 'oneOrMany' },
  },
])
if (!relations) throw new Error('Cannot create entity relations')
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeInsertEntityRelationItem`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`IBoardFacadeInsertConnectorsOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertImage`

Inserts a Board image using agent-friendly options.

Use a element id when an agent may later replace the image source or move the image. The element is created
through the Board image factory and then dispatched through the normal add-element command path, so it participates
in collaboration and undo/redo like a UI-inserted image.

```typescript
insertImage(options: IBoardFacadeInsertImageOptions): IBoardPageElement | null
```

**Parameters**

* `options` — Required. Image source, bounds, and parent.

**Returns**

The inserted image element, otherwise `null` when the source, parent, or command is invalid.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const image = board.insertImage({
  source: 'https://example.com/image.png',
  imageSourceType: univerAPI.Enum.ImageSourceType.URL,
  left: 80,
  top: 80,
  width: 320,
  height: 180,
})
if (!image) throw new Error('Cannot insert image')
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeInsertImageOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertSequenceMessage`

Inserts one ordered message using the activation and shared-timeline rules of `insertSequenceMessages`.
Create native lifeline participants and activation bars before calling this method.

```typescript
insertSequenceMessage(options: IBoardFacadeInsertSequenceMessageOptions, layout?: Omit<IBoardFacadeInsertSequenceMessagesOptions, 'insertIndex'>): IBoardPageElement | null
```

**Parameters**

* `options` — Required. Message type, positive order, participant ids and optional explicit activation ids.
* `layout` — Optional. Default: `{}`. Timeline origin, spacing and self-message dimensions in Board units.

**Returns**

The inserted connector synchronously, or `null` when the message cannot be bound or inserted.

**Examples**

```ts
const message = board.insertSequenceMessage(
  {
    fromParticipantId: agentId,
    toParticipantId: toolId,
    type: 'synchronous',
    order: 1,
    text: 'execute()',
  },
  { timeOriginY: 160 },
)
if (!message) throw new Error('Cannot bind sequence message')
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeInsertSequenceMessageOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IBoardFacadeInsertSequenceMessagesOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertSequenceMessages`

Inserts messages bound to a covering activation, or to the lifeline outside execution spans.
Create activation bars first. Ambiguous overlapping spans require explicit activation IDs.
Bindings are persisted shape sites: editing an activation moves its attached messages with it.
All messages share one world-space timeline. Create targets must have their header center at the
receive time; destroy targets must end their lifeline there. This helper never moves participants.
Message Y is `timeOriginY + firstOffsetY + (order - 1) * step`; defaults are 72 for the first offset and 48
for the step. Without an explicit origin, the earliest participant header bottom is used.
Orders must be positive, integral and unique within the batch. The entire batch is one undoable insertion.

```typescript
insertSequenceMessages(messages: IBoardFacadeInsertSequenceMessageItem[], options?: IBoardFacadeInsertSequenceMessagesOptions): IBoardPageElement[] | null
```

**Parameters**

* `messages` — Required. Ordered messages referencing native lifelines and optional native activation bars on the active page.
* `options` — Optional. Default: `{}`. Shared timeline, self-loop dimensions, insertion index and optional container fitting target.

**Returns**

Inserted connectors synchronously, or `null` without partial insertion if any message is invalid.

**Examples**

```ts
const messages = board.insertSequenceMessages(
  [
    {
      fromParticipantId: agentId,
      toParticipantId: toolId,
      type: 'synchronous',
      order: 1,
      text: 'execute()',
    },
    {
      fromParticipantId: toolId,
      toParticipantId: agentId,
      type: 'reply',
      order: 2,
      text: 'result',
    },
  ],
  { timeOriginY: 160, firstOffsetY: 48, step: 64 },
)
if (!messages) throw new Error('Check participant geometry and overlapping activation spans')
// Inspect model geometry with analyzeModelLayout(); use analyzeRenderedLayout() in a rendered Board UI
// to check measured text and route collisions before capturing a screenshot.
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeInsertSequenceMessageItem`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`IBoardFacadeInsertSequenceMessagesOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertShape`

Inserts a Shape or Connector through the common Board Shape host adapter.

Put geometry under `transform`; top-level `left`, `top`, `width`, and `height` are rejected. The Board generates
the element id, and the returned live handle exposes that id through `getId()`. Set text or additional styling on
the handle after creation. Use `insertShapeAtPoint()` instead when Board-specific drop-target attachment or
`textBox` options are required.

```typescript
insertShape(input: IBoardShapeCreateInput): FShape | FConnectorShape | null
```

**Parameters**

* `input` — Required. Common Shape creation input. Board supplies its own transform defaults when fields are omitted.

**Returns**

A live common Shape handle, or `null` when creation fails.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,
  transform: { left: 80, top: 80, width: 180, height: 100 },
  name: 'Review card',
  description: 'Tracks the current review step',
  visible: true,
  selectable: true,
  shapeData: {
    fill: { fillType: univerAPI.Enum.ShapeFillEnum.SolidFill, color: '#ede9fe' },
    stroke: {
      lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,
      color: '#7c3aed',
      width: 2,
    },
  },
})
if (!shape) throw new Error('Cannot insert Shape')
shape.setRotation(6).setStrokeLineCapType(univerAPI.Enum.ShapeLineCapEnum.Round)
shape
  .getText()
  .setText('Board card')
  .setHorizontalAlign(univerAPI.Enum.HorizontalAlign.CENTER)
  .setVerticalAlign(univerAPI.Enum.VerticalAlign.MIDDLE)

const shapeId = shape.getId()
const savedShape = board.getShape(shapeId)
if (!savedShape || savedShape.getText().getPlainText() !== 'Board card') {
  throw new Error('Cannot verify inserted Shape')
}
console.log({ shapeId, transform: savedShape.getTransform() })
```

**Types:** [`FShape`](https://docs.univer.ai/reference/facade/shape.md) · [`FConnectorShape`](https://docs.univer.ai/reference/facade/connector-shape.md) · [`IBoardShapeCreateInput`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertShapeAtPoint`

Inserts a shape at a board coordinate and optionally attaches it to the container or swimlane lane at that point.

This is the shortest path for agents that place cards, nodes, or annotations into an existing board region. The
method maps `point` to `left`/`top`, resolves the drop target with `resolveDropTargetAtPoint()`, and fills
`parentId`/`laneId` internally when the caller did not provide explicit parent options.

```typescript
insertShapeAtPoint(options: IBoardFacadeInsertShapeAtPointOptions): IBoardPageElement | null
```

**Parameters**

* `options` — Required. Shape insertion options with a required `point`.

**Returns**

The generated shape element when the insert command succeeds, otherwise `null`.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShapeAtPoint({
  point: { x: 180, y: 160 },
  shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,
  text: 'Dropped card',
})
if (!shape) throw new Error('Cannot insert shape at point')
```

**Types:** [`IBoardPageElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeInsertShapeAtPointOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertShapes`

Inserts multiple live Shapes or Connectors through one atomic Board command.

This is the batch counterpart of `insertShape()`: every item uses `IBoardShapeCreateInput`, and every returned value is
a live common Shape handle. All inputs are inserted by one Board command; validation or command failure returns
`null` without exposing a partially successful result. Geometry belongs under each item's `transform`, and the
returned handles preserve input order.

```typescript
insertShapes(inputs: IBoardShapeCreateInput[]): Array<FShape | FConnectorShape> | null
```

**Parameters**

* `inputs` — Required. Common Shape creation inputs in the requested insertion order.

**Returns**

Live Shape handles in input order, or `null` when validation or the atomic command fails.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  {
    shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,
    transform: { left: 80, top: 80, width: 180, height: 100 },
    name: 'Start',
  },
  {
    shapeType: univerAPI.Enum.ShapeTypeEnum.Ellipse,
    transform: { left: 320, top: 80, width: 180, height: 100 },
    name: 'Finish',
  },
])
if (!shapes || shapes.length !== 2) throw new Error('Cannot insert Shapes')

shapes[0].getText().setText('Start')
shapes[1].getText().setText('Finish')
const shapeIds = shapes.map((shape) => shape.getId())
const verified = shapeIds.every((shapeId) => board.getShape(shapeId) !== null)
if (!verified) throw new Error('Cannot verify inserted Shapes')
console.log({ shapeIds, transforms: shapes.map((shape) => shape.getTransform()) })
```

**Types:** [`Array`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`FShape`](https://docs.univer.ai/reference/facade/shape.md) · [`FConnectorShape`](https://docs.univer.ai/reference/facade/connector-shape.md) · [`IBoardShapeCreateInput`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertText`

Inserts standalone Board text through the normal command path.

Use this for labels, annotations, headings, and document fragments that should not have a shape background. The
returned element remains editable with the standard Board text editor. Prefer a element id when an agent may
update the same annotation in a later run.

```typescript
insertText(options: IBoardFacadeInsertTextOptions): IBoardTextElement | null
```

**Parameters**

* `options` — Required. Text content, bounds, optional style, and parent.

**Returns**

The inserted text element, otherwise `null` when validation or the command fails.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const text = board.insertText({
  text: 'Board heading',
  left: 80,
  top: 80,
  textStyle: { color: '#2563EB', fontSize: 32, bold: true },
})
if (!text) throw new Error('Cannot insert text')
```

**Types:** [`IBoardTextElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadeInsertTextOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.moveElementsOutOfContainer`

Moves elements out of their current container to the Board root.

This is a semantic alias for `reparentElements(elementIds, undefined)`.

```typescript
moveElementsOutOfContainer(elementIds: string[]): boolean
```

**Parameters**

* `elementIds` — Required. Element ids to move.

**Returns**

`true` when the move succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (!board.createContainer({ id: containerId, left: 80, top: 80 }))
  throw new Error('Cannot create container')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 120, top: 120 },
})
if (!shape || !board.reparentElements([shape.getId()], containerId))
  throw new Error('Cannot insert shape')
if (!board.moveElementsOutOfContainer([shape.getId()])) throw new Error('Cannot move shape out')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.moveElementsToContainer`

Moves elements into a container.

This is a semantic alias for `reparentElements(elementIds, containerId)`, easier for agents to choose when the
target is definitely a container.

```typescript
moveElementsToContainer(elementIds: string[], containerId: string): boolean
```

**Parameters**

* `elementIds` — Required. Element ids to move.
* `containerId` — Required. Target container id.

**Returns**

`true` when the move succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (!board.createContainer({ id: containerId, left: 80, top: 80 }))
  throw new Error('Cannot create container')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 480, top: 80 },
})
if (!shape || !board.moveElementsToContainer([shape.getId()], containerId))
  throw new Error('Cannot move shape')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.normalizeConnectorRouting`

Resets selected connectors to the Board orthogonal auto router.

The command preserves endpoints, labels, style, parent scope, and lane membership while clearing manual path
state. The change participates in Board undo and redo.

```typescript
normalizeConnectorRouting(connectorIds: string[]): NormalizeBoardConnectorRoutingResult
```

**Parameters**

* `connectorIds` — Required. Generated connector ids, normally taken from layout issue results.

**Returns**

The changed and skipped ids. When connectors change, `affectedBounds` covers the previous connector
routes and their bound endpoint elements; a no-op returns `null`. The API returns `false` when the command fails.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const analysis = board.analyzeModelLayout()
if (!analysis) throw new Error('Cannot analyze the active board')
const connectorIds = Array.from(new Set(analysis.issues.flatMap((issue) => issue.connectorIds)))

if (connectorIds.length > 0) {
  const result = board.normalizeConnectorRouting(connectorIds)
  if (!result) throw new Error('Cannot normalize connector routing')
  console.log(result.changedConnectorIds, result.skippedElementIds)
}
```

**Types:** [`NormalizeBoardConnectorRoutingResult`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.redo`

Redoes the last operation undone in this board.

This method focuses this board before executing redo, making it the preferred redo API for agent scripts that
already hold an `FBoard` instance.

```typescript
redo(): boolean
```

**Returns**

`true` when an operation was redone; otherwise `false`.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape || !board.undo() || !board.redo()) throw new Error('Cannot redo shape insertion')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.removeConnectorLabel`

Removes one connector label through the Board command layer.

The connector itself and its routing remain unchanged. The removal participates in collaboration and undo/redo,
so `board.undo()` restores the label text, rich-text document, box style, and position.

```typescript
removeConnectorLabel(elementId: string, labelId?: string): boolean
```

**Parameters**

* `elementId` — Required. Existing connector id with a label.
* `labelId` — Optional.

**Returns**

`true` when the label exists and is removed.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const connectorId = 'connector-id'
if (!board.removeConnectorLabel(connectorId)) throw new Error('Cannot remove connector label')

// Restore the removed label when needed.
board.undo()
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.removeElement`

Removes one board element through the command layer.

The method rejects locally known locked, hidden, unselectable, or membership-locked container content. Prefer
id-based lookup before removal in agent scripts so generated ids do not leak into prompts.

```typescript
removeElement(elementId: string): boolean
```

**Parameters**

* `elementId` — Required. Element id to remove.

**Returns**

`true` when the remove command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape || !board.removeElement(shape.getId())) throw new Error('Cannot remove shape')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.removeElements`

Removes multiple board elements in one command.

Use this batch API when an agent cleans up several generated elements. It rejects duplicate ids and dispatches one
command, which keeps collaboration and undo history compact.

```typescript
removeElements(elementIds: string[]): boolean
```

**Parameters**

* `elementIds` — Required. Element ids to remove.

**Returns**

`true` when all ids pass local checks and the remove command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 80 } },
])
if (!shapes || !board.removeElements(shapes.map((shape) => shape.getId())))
  throw new Error('Cannot remove shapes')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.removeSwimlaneLane`

Removes one lane from a swimlane container.

Empty unlocked lanes are removed directly. When the lane contains children, choose an explicit `contentPolicy`:
promote children to the swimlane pool, move them to another unlocked lane, or delete them.

```typescript
removeSwimlaneLane(containerId: string, laneId: string, options?: IBoardFacadeRemoveSwimlaneLaneOptions): boolean
```

**Parameters**

* `containerId` — Required. Swimlane container id.
* `laneId` — Required. Lane id to remove.
* `options` — Optional. Default: `{}`. Optional content policy.

**Returns**

`true` when the lane is removed.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const swimlaneId = `swimlane-${Date.now()}`
if (
  !board.createSwimlane({
    id: swimlaneId,
    left: 80,
    top: 80,
    lanes: [
      { id: 'todo', title: 'Todo' },
      { id: 'done', title: 'Done' },
    ],
  }) ||
  !board.removeSwimlaneLane(swimlaneId, 'done')
)
  throw new Error('Cannot remove lane')
```

**Types:** [`IBoardFacadeRemoveSwimlaneLaneOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.renameSwimlaneLane`

Renames one swimlane lane.

Empty names are rejected and whitespace is trimmed. Locked lanes cannot be renamed.

```typescript
renameSwimlaneLane(containerId: string, laneId: string, title: string): boolean
```

**Parameters**

* `containerId` — Required. Swimlane container id.
* `laneId` — Required. Lane id to rename.
* `title` — Required. New lane title.

**Returns**

`true` when the lane title changes.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const swimlaneId = `swimlane-${Date.now()}`
if (
  !board.createSwimlane({
    id: swimlaneId,
    left: 80,
    top: 80,
    lanes: [{ id: 'todo', title: 'Todo' }],
  }) ||
  !board.renameSwimlaneLane(swimlaneId, 'todo', 'Ready')
)
  throw new Error('Cannot rename lane')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.reorderElements`

Reorders existing elements in board z-order.

```typescript
reorderElements(elementIds: string[], placement: BoardElementOrderPlacement): boolean
```

**Parameters**

* `elementIds` — Required. Existing element ids.
* `placement` — Required. Absolute or one-step z-order placement.

**Returns**

`true` when every id exists and the order changes successfully.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 120, top: 120 } },
])
if (!shapes) throw new Error('Cannot insert shapes')
const background = shapes[1]
if (!board.reorderElements([background.id], 'back')) {
  throw new Error('Cannot send background to back')
}
```

**Types:** [`BoardElementOrderPlacement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/commands/operations/reorder-board-elements.operation.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.reorderSwimlaneLane`

Moves a swimlane lane to a new index.

Locked lanes cannot be reordered. `targetIndex` is clamped into the valid range, making agent-generated values
safe when they are slightly outside the current lane count.

```typescript
reorderSwimlaneLane(containerId: string, laneId: string, targetIndex: number): boolean
```

**Parameters**

* `containerId` — Required. Swimlane container id.
* `laneId` — Required. Lane id to move.
* `targetIndex` — Required. New zero-based index.

**Returns**

`true` when the lane order changes.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const swimlaneId = `swimlane-${Date.now()}`
if (
  !board.createSwimlane({
    id: swimlaneId,
    left: 80,
    top: 80,
    lanes: [
      { id: 'todo', title: 'Todo' },
      { id: 'done', title: 'Done' },
    ],
  }) ||
  !board.reorderSwimlaneLane(swimlaneId, 'done', 0)
)
  throw new Error('Cannot reorder lane')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.reparentElements`

Reparents elements into a container or back to the Board root.

Pass `parentId` to move elements into a container. Pass `undefined` to move them out to the Board root. The method
checks membership-locked parents and target container accessibility before dispatching.

```typescript
reparentElements(elementIds: string[], parentId?: string): boolean
```

**Parameters**

* `elementIds` — Required. Element ids to move.
* `parentId` — Optional. Target container id, or `undefined` for the Board root.

**Returns**

`true` when the reparent command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (!board.createContainer({ id: containerId, left: 80, top: 80 }))
  throw new Error('Cannot create container')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 480, top: 80 },
})
if (!shape || !board.reparentElements([shape.getId()], containerId))
  throw new Error('Cannot reparent shape')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.resolveCaptureBounds`

Resolves a screenshot target to active-page Board world bounds without requiring a browser renderer.

Omit options for all visible content, pass `region` for an explicit world rectangle, or pass `elementIds` for
the union of visible element bounds. Region and element selectors are mutually exclusive.

```typescript
resolveCaptureBounds(options?: IBoardFacadeCaptureBoundsOptions): ResolveBoardCaptureBoundsResult
```

**Parameters**

* `options` — Optional. Default: `{}`. Capture selector and world-unit padding.

**Returns**

Structured bounds or a selector error, or `false` when the command cannot run.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const [element] = board.describeElements()
if (!element) throw new Error('The active board is empty')
const target = board.resolveCaptureBounds({ elementIds: [element.id], padding: 48 })
if (!target) throw new Error('Cannot resolve Board capture bounds')
if (!target.ok) throw new Error(`Cannot capture Board: ${target.code}`)

console.log(target.bounds)
```

**Types:** [`ResolveBoardCaptureBoundsResult`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`IBoardFacadeCaptureBoundsOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.resolveContainerAtPoint`

Resolves the topmost unlocked container at a board coordinate.

Use this before inserting or moving agent-created elements when you want them to attach to the container under a
point. `area: 'content'` ignores container headers and uses the usable content area, including swimlane lane
content when available.

```typescript
resolveContainerAtPoint(point: IBoardFacadePoint, options?: IBoardFacadeResolveContainerAtPointOptions): IBoardContainerElement | null
```

**Parameters**

* `point` — Required. Point in board coordinates.
* `options` — Optional. Default: `{}`. Container-area options. Defaults to the outer container area.

**Returns**

The deepest topmost matching container, or `null`.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (!board.createContainer({ id: containerId, left: 80, top: 80, width: 320, height: 240 })) {
  throw new Error('Cannot create container')
}
console.log(board.resolveContainerAtPoint({ x: 160, y: 160 }))
```

**Types:** [`IBoardContainerElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardFacadePoint`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`IBoardFacadeResolveContainerAtPointOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.resolveDropTargetAtPoint`

Resolves the board drop target at a coordinate for agent insert operations.

Use `containerId` as `parentId` and `laneId` as `laneId` when inserting an element at the same point. The
descriptor gives agents enough context to reason about the target without reading raw container payloads. When the
point is outside a matching container, or outside content bounds when `area: 'content'` is used, the method returns
`null`.

```typescript
resolveDropTargetAtPoint(point: IBoardFacadePoint, options?: IBoardFacadeResolveContainerAtPointOptions): IBoardFacadeDropTarget | null
```

**Parameters**

* `point` — Required. Point in board coordinates.
* `options` — Optional. Default: `{}`. Container-area options. Defaults to the outer container area.

**Returns**

Drop target information, or `null` when no valid target exists at that point.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (!board.createContainer({ id: containerId, left: 80, top: 80, width: 320, height: 240 })) {
  throw new Error('Cannot create container')
}
console.log(board.resolveDropTargetAtPoint({ x: 160, y: 160 }, { area: 'content' }))
```

**Types:** [`IBoardFacadeDropTarget`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`IBoardFacadePoint`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`IBoardFacadeResolveContainerAtPointOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.save`

Save and return the board snapshot, including resource data.

This is a detached serialization export. It is not a live model reference; use facade mutation APIs instead of
editing it when changes must participate in undo/redo and collaboration.

```typescript
save(): IBoardData
```

**Returns**

The board snapshot.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const snapshot = board.save()
console.log(snapshot.name, Object.keys(snapshot.pages ?? {}).length)
```

**Types:** [`IBoardData`](https://docs.univer.ai/reference/types/board-data.md)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.sendElementsBackward`

Moves elements one z-order step backward.

```typescript
sendElementsBackward(elementIds: string[]): boolean
```

**Parameters**

* `elementIds` — Required. Existing element ids.

**Returns**

`true` when the order changes successfully.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 120, top: 120 } },
])
if (!shapes || !board.sendElementsBackward([shapes[1].getId()]))
  throw new Error('Cannot move shape backward')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.sendElementsToBack`

Sends elements to the back.

```typescript
sendElementsToBack(elementIds: string[]): boolean
```

**Parameters**

* `elementIds` — Required. Existing element ids.

**Returns**

`true` when the order changes successfully.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 120, top: 120 } },
])
if (!shapes || !board.sendElementsToBack([shapes[1].getId()]))
  throw new Error('Cannot send shape to back')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setConnectorConnection`

Patches connector endpoints, routing, or manual waypoints through the normal update command.

```typescript
setConnectorConnection(elementId: string, patch: IBoardFacadeConnectorConnectionPatch): boolean
```

**Parameters**

* `elementId` — Required. Existing connector id.
* `patch` — Required. Endpoint and routing fields to replace.

**Returns**

`true` when the connector and endpoints are valid and the update succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 320, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 560, top: 80 } },
])
if (!shapes) throw new Error('Cannot insert connector targets')
const connector = board.insertConnector({
  fromElementId: shapes[0].getId(),
  toElementId: shapes[1].getId(),
})
if (!connector) throw new Error('Cannot insert connector')
const replacement = shapes[2]
const changed = board.setConnectorConnection(connector.id, {
  end: { elementId: replacement.id, connectionSiteId: 3 },
  routing: 'curve',
})
if (!changed) throw new Error('Cannot reconnect edge')
```

**Types:** [`IBoardFacadeConnectorConnectionPatch`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setConnectorLabels`

Replaces every label on one connector in one undoable command, preserving its endpoints and route.
Pass `[]` to remove all labels. Label ids must be non-empty and unique within the connector.
`autoSize` does not wrap automatically; `fixedWidth` wraps to the specified width and grows vertically;
`fixedSize` also fixes height. Measured dimensions remain render-derived, not persisted by this method.

```typescript
setConnectorLabels(elementId: string, labels: readonly IBoardFacadeConnectorLabel[]): boolean
```

**Parameters**

* `elementId` — Required. Existing connector id on the active page.
* `labels` — Required. Complete replacement labels with stable ids; plain text or rich document content is supported.

**Returns**

`true` synchronously on success; `false` for invalid labels, a non-connector id or command failure.

**Examples**

```ts
const ok = board.setConnectorLabels(connectorId, [
  {
    id: 'name',
    content: 'executes',
    placement: { anchor: 'center' },
    layout: { mode: 'autoSize' },
  },
  { id: 'target', content: '0..*', placement: { anchor: 'end', side: 'left' } },
])
if (!ok) throw new Error('Cannot replace connector labels')
```

**Types:** [`IBoardFacadeConnectorLabel`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setConnectorLabelStyle`

Patches the visual style of one existing connector label through the Board command layer.

Omitted fields preserve their current values. Pass `null` for `fill` or `stroke` to restore the default
transparent/no-border appearance. Set `interruptLine` to `false` only when the connector should remain visible
behind the text. `lineGap` is the extra spacing around the label box in Board units.

```typescript
setConnectorLabelStyle(elementId: string, patch: IBoardConnectorLabelStylePatch): boolean
```

**Parameters**

* `elementId` — Required. Existing connector id with a label.
* `patch` — Required. Label appearance fields to update.

**Returns**

`true` when the label exists and the command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const connectorId = 'connector-id'

if (
  !board.setConnectorLabelStyle(connectorId, {
    fill: { color: '#ffffff', opacity: 0.92 },
    stroke: {
      color: '#94a3b8',
      width: 1,
      lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,
    },
    interruptLine: true,
    lineGap: 3,
  })
)
  throw new Error('Cannot style connector label')

// Restore the default transparent label while keeping the route interrupted behind the text.
board.setConnectorLabelStyle(connectorId, { fill: null, stroke: null, interruptLine: true })
```

**Types:** [`IBoardConnectorLabelStylePatch`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setConnectorLabelText`

Sets one connector label, creating the label when necessary.

Pass a string for plain text or the shared `RichTextBuilder` returned by `univerAPI.newRichText()` or
`getConnectorLabelText(...).copy()`. The builder is detached before the command executes, so later builder
changes do not mutate the Board. The command participates in collaboration and undo/redo.

Text changes preserve declarative layout constraints. Board UI measures content at runtime without writing
derived dimensions into the model. Use `updateConnectorLabel(..., { layout })` to change sizing constraints;
successful headless execution does not imply that visual layout has been measured.

```typescript
setConnectorLabelText(elementId: string, text: BoardFacadeTextContent): boolean
```

**Parameters**

* `elementId` — Required. Existing connector id.
* `text` — Required. Plain or rich label content.

**Returns**

`true` when the connector exists and the update succeeds or is already current.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 320, top: 80 } },
])
if (!shapes) throw new Error('Cannot insert shapes')
const connector = board.insertConnector({
  fromElementId: shapes[0].getId(),
  toElementId: shapes[1].getId(),
})
if (!connector) throw new Error('Cannot insert connector')

const label = univerAPI
  .newRichText()
  .align({ horizontal: univerAPI.Enum.HorizontalAlign.CENTER })
  .span('Approved', { bold: true, fontSize: 16, color: '#16a34a' })
if (!board.setConnectorLabelText(connector.id, label)) {
  throw new Error('Cannot set label')
}
```

**Types:** [`BoardFacadeTextContent`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/board-text-content.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setConnectorStyle`

Patches the visual style of one connector without changing its endpoints or label.

Animation is disabled by default. The available modes are `dash` (moving dash), `particle` (one moving dot),
`pulse` (whole-path highlight), `gradient` (moving fading highlight), `particles` (repeated dots), and `arrows`
(repeated directional arrowheads). Use `animation: null` to disable an existing animation. A small number of
animated connectors can make data flow easier to read; keep dense diagrams static unless motion adds meaning.
Marker names are validated at runtime; use `{ type: 'none' }` rather than `null` to hide a marker.

```typescript
setConnectorStyle(elementId: string, patch: IBoardFacadeConnectorStylePatch): boolean
```

**Parameters**

* `elementId` — Required. Existing connector id.
* `patch` — Required. Connector style fields to update.

**Returns**

`true` when the connector and patch are valid and the update succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 320, top: 80 } },
])
if (!shapes) throw new Error('Cannot insert shapes')
const connector = board.insertConnector({
  fromElementId: shapes[0].getId(),
  toElementId: shapes[1].getId(),
})
if (
  !connector ||
  !board.setConnectorStyle(connector.id, {
    stroke: '#4f46e5',
    strokeWidth: 2,
    animation: { mode: 'gradient', direction: 'forward', speed: 1 },
  })
) {
  throw new Error('Cannot style connector')
}
// Reverse and accelerate the same animation.
if (
  !board.setConnectorStyle(connector.id, {
    animation: { mode: 'gradient', direction: 'reverse', speed: 2 },
  })
)
  throw new Error('Cannot update connector animation')
// Restore a static connector. `undefined` would preserve the current animation instead.
if (!board.setConnectorStyle(connector.id, { animation: null })) {
  throw new Error('Cannot disable connector animation')
}
```

**Types:** [`IBoardFacadeConnectorStylePatch`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setContainerAutoResize`

Enables or disables auto-resize for a container.

Auto-resize is useful for agent-generated groups that should grow with their children. The facade rejects disabling
auto-resize on a membership-locked container because that would conflict with local container invariants.

```typescript
setContainerAutoResize(containerId: string, autoResize: boolean): boolean
```

**Parameters**

* `containerId` — Required. Container id.
* `autoResize` — Required. Whether the container should auto-resize.

**Returns**

`true` when the command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (
  !board.createContainer({ id: containerId, left: 80, top: 80 }) ||
  !board.setContainerAutoResize(containerId, true)
)
  throw new Error('Cannot enable auto-resize')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setContainerMembershipLocked`

Enables or disables membership locking for a container.

A membership-locked container prevents facade operations from moving children out through normal reparent/remove
paths. This helps agents protect generated groups after they are finalized.

```typescript
setContainerMembershipLocked(containerId: string, membershipLocked: boolean): boolean
```

**Parameters**

* `containerId` — Required. Container id.
* `membershipLocked` — Required. Whether membership should be locked.

**Returns**

`true` when the command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (
  !board.createContainer({ id: containerId, left: 80, top: 80 }) ||
  !board.setContainerMembershipLocked(containerId, true)
)
  throw new Error('Cannot lock membership')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setContainerStyle`

Patches the frame and title style of a generic container or swimlane.

```typescript
setContainerStyle(elementId: string, patch: IBoardFacadeContainerStylePatch): boolean
```

**Parameters**

* `elementId` — Required. Existing container id.
* `patch` — Required. Frame fields and optional partial title style.

**Returns**

`true` when the container and patch are valid and the update succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const containerId = `container-${Date.now()}`
if (
  !board.createContainer({ id: containerId, left: 80, top: 80 }) ||
  !board.setContainerStyle(containerId, {
    fillColor: '#f8fafc',
    strokeColor: '#64748b',
  })
)
  throw new Error('Cannot style container')
```

**Types:** [`IBoardFacadeContainerStylePatch`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setElementMetadata`

Updates top-level metadata for one element.

This keeps geometry and element-specific payload intact while using the normal Board command path, so the
change participates in undo/redo and collaboration.

```typescript
setElementMetadata(elementId: string, patch: IBoardFacadeSetElementMetadataPatch): boolean
```

**Parameters**

* `elementId` — Required. Existing element id returned by an insert or discovery API.
* `patch` — Required. Metadata fields to update. Explicit `undefined` clears `name` or `description`.

**Returns**

`true` when the element exists and the update succeeds or is already current.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 120, top: 120 },
  name: 'Review',
})
if (!shape || !board.setElementMetadata(shape.getId(), { name: 'Review step', locked: true })) {
  throw new Error('Cannot update shape metadata')
}
```

**Types:** [`IBoardFacadeSetElementMetadataPatch`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setElementsMetadata`

Updates top-level metadata for several elements in one command.

Every id must exist and be editable; otherwise no element is changed.

```typescript
setElementsMetadata(patches: Record<string, IBoardFacadeSetElementMetadataPatch>): boolean
```

**Parameters**

* `patches` — Required. Element-id-to-metadata map.

**Returns**

`true` when every target is valid and the atomic batch succeeds or is already current.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 80 } },
])
if (
  !shapes ||
  !board.setElementsMetadata({
    [shapes[0].getId()]: { name: 'Start' },
    [shapes[1].getId()]: { name: 'Finish' },
  })
)
  throw new Error('Cannot update metadata')
```

**Types:** [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IBoardFacadeSetElementMetadataPatch`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setElementsTransform`

Applies transform patches atomically to several elements.

```typescript
setElementsTransform(patches: Record<string, IBoardFacadeElementTransformPatch>): boolean
```

**Parameters**

* `patches` — Required. Element-id-to-transform map.

**Returns**

`true` when every target and patch is valid and the batch succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 80 } },
])
if (
  !shapes ||
  !board.setElementsTransform({
    [shapes[0].getId()]: { left: 120 },
    [shapes[1].getId()]: { left: 360, rotation: 15 },
  })
)
  throw new Error('Cannot transform shapes')
```

**Types:** [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IBoardFacadeElementTransformPatch`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setElementTransform`

Moves, resizes, rotates, or flips one element without rebuilding its full model.

```typescript
setElementTransform(elementId: string, patch: IBoardFacadeElementTransformPatch): boolean
```

**Parameters**

* `elementId` — Required. Existing element id.
* `patch` — Required. Transform fields to replace; omitted fields keep their current values.

**Returns**

`true` when the element and patch are valid and the update succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,
  transform: { left: 80, top: 80 },
  name: 'Move me',
})
if (!shape || !board.setElementTransform(shape.getId(), { left: 240, top: 160, rotation: 15 })) {
  throw new Error('Cannot transform shape')
}
```

**Types:** [`IBoardFacadeElementTransformPatch`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setImageBackground`

Uses an image as the active Board page background.

The background stays below Board elements and does not participate in selection or pointer interaction.

```typescript
setImageBackground(options: IBoardFacadeSetImageBackgroundOptions): this
```

**Parameters**

* `options` — Required. Image source and fill behavior.

**Returns**

This board, for chaining.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
board?.setImageBackground({
  source: 'https://example.com/background.jpg',
  imageSourceType: univerAPI.Enum.ImageSourceType.URL,
  fit: 'cover',
})
```

**Types:** [`IBoardFacadeSetImageBackgroundOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setName`

Sets the board display name.

```typescript
setName(name: string): this
```

**Parameters**

* `name` — Required. The new board name.

**Returns**

This board, for chaining.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
board?.setName('Planning Board')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setSwimlaneLaneCollapsed`

Collapses or expands one swimlane lane.

Collapsing is rejected for locked lanes. Use this when an agent wants to reduce visual noise without deleting the
lane or its children.

```typescript
setSwimlaneLaneCollapsed(containerId: string, laneId: string, collapsed: boolean): boolean
```

**Parameters**

* `containerId` — Required. Swimlane container id.
* `laneId` — Required. Lane id to update.
* `collapsed` — Required. Whether the lane should be collapsed.

**Returns**

`true` when the collapsed state changes.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const swimlaneId = `swimlane-${Date.now()}`
if (
  !board.createSwimlane({
    id: swimlaneId,
    left: 80,
    top: 80,
    lanes: [{ id: 'todo', title: 'Todo' }],
  }) ||
  !board.setSwimlaneLaneCollapsed(swimlaneId, 'todo', true)
)
  throw new Error('Cannot collapse lane')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setSwimlaneLanes`

Replaces the full swimlane model for a swimlane container.

This is a low-level lane operation. Prefer the focused lane APIs for agent scripts because they express intent
more clearly. Locked lanes cannot be removed, reordered, resized, renamed, or moved by this method.

```typescript
setSwimlaneLanes(containerId: string, swimlane: IBoardSwimlaneData): boolean
```

**Parameters**

* `containerId` — Required. Swimlane container id.
* `swimlane` — Required. Complete next swimlane model.

**Returns**

`true` when the update command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const swimlaneId = `swimlane-${Date.now()}`
if (
  !board.createSwimlane({
    id: swimlaneId,
    left: 80,
    top: 80,
    lanes: [{ id: 'todo', title: 'Todo' }],
  })
) {
  throw new Error('Cannot create swimlane')
}
const element = board.getElement(swimlaneId)
if (
  !element ||
  element.type !== univerAPI.Enum.BoardElementType.Container ||
  element.containerData.kind !== 'swimlane' ||
  !element.containerData.swimlane ||
  !board.setSwimlaneLanes(swimlaneId, { ...element.containerData.swimlane, laneGap: 16 })
) {
  throw new Error('Cannot update swimlane')
}
```

**Types:** [`IBoardSwimlaneData`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setSwimlaneLaneSize`

Resizes one swimlane lane.

The method rejects locked lanes and missing swimlane containers. Use meaningful lane ids so agent scripts can modify
layouts without relying on generated indexes.

```typescript
setSwimlaneLaneSize(containerId: string, laneId: string, size: number): boolean
```

**Parameters**

* `containerId` — Required. Swimlane container id.
* `laneId` — Required. Lane id to resize.
* `size` — Required. New lane size in board coordinates.

**Returns**

`true` when the resize command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const swimlaneId = `swimlane-${Date.now()}`
if (
  !board.createSwimlane({
    id: swimlaneId,
    left: 80,
    top: 80,
    lanes: [{ id: 'todo', title: 'Todo' }],
  }) ||
  !board.setSwimlaneLaneSize(swimlaneId, 'todo', 240)
)
  throw new Error('Cannot resize lane')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setTextContent`

Replaces standalone text content while preserving its bounds and style.

```typescript
setTextContent(elementId: string, content: BoardFacadeTextContent): boolean
```

**Parameters**

* `elementId` — Required. Existing standalone text id.
* `content` — Required. Plain text or a value returned by `univerAPI.newRichText()`.

**Returns**

`true` when the text element exists and the update succeeds or is already current.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const text = board.insertText({ text: 'Draft', left: 80, top: 80 })
if (!text || !board.setTextContent(text.id, 'Approved')) throw new Error('Cannot update text')
```

**Types:** [`BoardFacadeTextContent`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/board-text-content.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.setTheme`

Applies a board theme by id.

Theme ids come from board theme presets or host-provided theme registration. Passing the current theme id is safe
and keeps the example copy-paste runnable.

```typescript
setTheme(themeIdOrOptions: string | IBoardFacadeSetThemeOptions): boolean
```

**Parameters**

* `themeIdOrOptions` — Required. Theme id or `{ themeId }`.

**Returns**

`true` when the theme command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const currentThemeId = board.getThemeData().id
if (!currentThemeId) throw new Error('No board theme id')

const changed = board.setTheme(currentThemeId)
if (!changed) throw new Error('Cannot apply board theme')
```

**Types:** [`IBoardFacadeSetThemeOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.translateElement`

Translates one element by a relative board-coordinate delta.

```typescript
translateElement(elementId: string, translation: IBoardFacadeElementTranslation): boolean
```

**Parameters**

* `elementId` — Required. Existing element id.
* `translation` — Required. Relative horizontal and vertical movement.

**Returns**

`true` when the delta is finite and non-zero and the update succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape || !board.translateElement(shape.getId(), { dx: 120, dy: 40 }))
  throw new Error('Cannot move shape')
```

**Types:** [`IBoardFacadeElementTranslation`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.translateElements`

Translates several elements by the same relative board-coordinate delta in one command.

```typescript
translateElements(elementIds: string[], translation: IBoardFacadeElementTranslation): boolean
```

**Parameters**

* `elementIds` — Required. Existing element ids.
* `translation` — Required. Shared relative movement.

**Returns**

`true` when every target is valid and the atomic batch succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 80 } },
])
if (
  !shapes ||
  !board.translateElements(
    shapes.map((shape) => shape.getId()),
    { dx: 40, dy: 80 },
  )
) {
  throw new Error('Cannot move shapes')
}
```

**Types:** [`IBoardFacadeElementTranslation`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.undo`

Undoes the last operation in this board.

Unlike `univerAPI.undo()`, this method first focuses this board, so it remains deterministic when an agent also
edits embedded rich-text documents or other Univer units.

```typescript
undo(): boolean
```

**Returns**

`true` when an operation was undone; otherwise `false`.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape || !board.undo()) throw new Error('Cannot undo shape insertion')
```

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.updateConnectorLabel`

Updates one stable label id in an undoable command; other labels, endpoints and routing remain unchanged.
Content and layout replace their entire previous values; placement and style merge individual fields.
A null layout restores AutoSize; null placement/style restores defaults. An explicit anchor or path ratio
clears the old free offset unless an offset is supplied in the same patch.

```typescript
updateConnectorLabel(elementId: string, labelId: string, patch: IBoardFacadeConnectorLabelPatch): boolean
```

**Parameters**

* `elementId` — Required. Existing connector id on the active page.
* `labelId` — Required. Existing stable label id, as returned by `getConnectorLabels`.
* `patch` — Required. Content, placement, sizing or style changes. Omitted fields are retained.

**Returns**

`true` synchronously on success; `false` for a missing label, invalid patch or command failure.

**Examples**

```ts
const ok = board.updateConnectorLabel(connectorId, 'name', {
  content: 'Executes tools with approval',
  layout: { mode: 'fixedWidth', width: 160 },
  placement: { anchor: 'center', offset: null },
})
if (!ok) throw new Error('Cannot update connector label')
```

**Types:** [`IBoardFacadeConnectorLabelPatch`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.updateElement`

Updates one element model through the command layer.

This is a low-level API for callers that already have a complete next element model. For agent scripts, prefer
intent-specific APIs such as metadata setters, container APIs, and shape/connector insert APIs where possible.
Supplying the current model and transform is a successful no-op: it creates neither an undo entry nor a
collaboration mutation.

```typescript
updateElement(elementId: string, options: IBoardFacadeUpdateElementOptions): boolean
```

**Parameters**

* `elementId` — Required. Existing element id to update.
* `options` — Required. Next element model and optional transform behavior.

**Returns**

`true` when the update command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 80, top: 80 },
})
if (!shape) throw new Error('Cannot insert shape')
const element = board.getElement(shape.getId())
if (
  !element ||
  !board.updateElement(shape.getId(), { element: { ...element, name: 'Updated shape' } })
) {
  throw new Error('Cannot update shape')
}
```

**Types:** [`IBoardFacadeUpdateElementOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.wrapElementsInContainer`

Wraps existing elements in a new or existing container.

Pass `containerId` to reuse a known container. Omit it to let the command create a container using `title`.
Duplicate ids and blocked elements are rejected before dispatch.

```typescript
wrapElementsInContainer(elementIds: string[], options?: IBoardFacadeWrapElementsInContainerOptions): boolean
```

**Parameters**

* `elementIds` — Required. Element ids to wrap.
* `options` — Optional. Default: `{}`. Optional container id and title.

**Returns**

`true` when the wrap command succeeds.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const shapes = board.insertShapes([
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 80, top: 80 } },
  { shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 280, top: 80 } },
])
if (
  !shapes ||
  !board.wrapElementsInContainer(
    shapes.map((shape) => shape.getId()),
    { title: 'Group' },
  )
) {
  throw new Error('Cannot wrap shapes')
}
```

**Types:** [`IBoardFacadeWrapElementsInContainerOptions`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

## `@univerjs-pro/boards-chart`

### `FBoard.getChart`

Returns a Board Chart by its Chart resource id or Board element id.

```typescript
getChart(chartIdOrElementId: string): FBoardChart | null
```

**Parameters**

* `chartIdOrElementId` — Required. A Chart resource id or Board element id.

**Returns**

The live Board Chart facade, or `null` if it does not exist.

**Examples**

```ts
const fBoard = univerAPI.getActiveBoard()
const fChart = fBoard.getChart('chart-1234')
console.log(fChart?.getInfo())
```

**Types:** [`FBoardChart`](https://docs.univer.ai/reference/facade/board-chart.md)

**Package:** [`@univerjs-pro/boards-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-chart@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getCharts`

Returns all Charts in this Board.

```typescript
getCharts(): FBoardChart[]
```

**Returns**

Live Chart facades in Board element order.

**Examples**

```ts
const fBoard = univerAPI.getActiveBoard()
const fCharts = fBoard.getCharts()
fCharts.forEach((fChart) => {
  console.log(fChart.getId(), fChart.getElementId(), fChart.getInfo())
})
```

**Types:** [`FBoardChart`](https://docs.univer.ai/reference/facade/board-chart.md)

**Package:** [`@univerjs-pro/boards-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-chart@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.insertChart`

Inserts a Chart into this Board from detached Chart information.

```typescript
insertChart(info: IBoardChartInfo): Promise<FBoardChart>
```

**Parameters**

* `info` — Required. The configuration, data source, placement, and ownership produced by a Board Chart Builder.

**Returns**

A live facade for the inserted Board Chart.

**Throws**

If the data source or size is invalid, a reference cannot be resolved, or insertion fails.

**Examples**

```ts
const fBoard = univerAPI.getActiveBoard()
const chartInfo = fBoard
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource([
    ['Quarter', 'Sales'],
    ['Q1', 120],
    ['Q2', 180],
  ])
  .setAbsolutePosition(120, 80)
  .setSize(640, 360)
  .setTitle('Quarterly sales')
  .build()

const fChart = await fBoard.insertChart(chartInfo)
fChart.setSubtitle('FY 2026')
```

**Types:** [`FBoardChart`](https://docs.univer.ai/reference/facade/board-chart.md) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IBoardChartInfo`](https://unpkg.com/@univerjs-pro/boards-chart@1.0.0-rc.0/lib/types/chart-builder/types.d.ts)

**Package:** [`@univerjs-pro/boards-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-chart@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.newChart`

Creates a detached, type-specific Chart Builder for this Board.

```typescript
newChart<T extends ChartTypeString>(type: T): FBoardChartBuilderOf<T>
```

**Parameters**

* `type` — Required. The Chart type to create.

**Returns**

A detached Builder that produces insertable Board Chart information.

**Examples**

```ts
const fBoard = univerAPI.getActiveBoard()
const chartInfo = fBoard
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource([
    ['Quarter', 'Sales'],
    ['Q1', 120],
    ['Q2', 180],
  ])
  .setAbsolutePosition(120, 80)
  .setSize(640, 360)
  .setTitle('Quarterly sales')
  .build()

const fChart = await fBoard.insertChart(chartInfo)
console.log(fChart.getId(), fChart.getElementId())
```

**Types:** [`FBoardChartBuilderOf`](https://unpkg.com/@univerjs-pro/boards-chart@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-chart@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

## `@univerjs-pro/boards-exchange-client`

### `FBoard.insertMermaidAsync`

Convert Mermaid code and insert the resulting diagram into this Board's active page.

```typescript
insertMermaidAsync(code: string, options?: IBoardMermaidOptions): Promise<boolean>
```

**Parameters**

* `code` — Required. Mermaid source code to convert and insert
* `options` — Optional. Mermaid conversion and insertion options

**Returns**

A promise that resolves to `true` when the diagram is inserted; otherwise `false`

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (board) {
  const inserted = await board.insertMermaidAsync('flowchart TD; A[Start] --> B[Finish]', {
    diagramType: 'flowchart',
    fileName: 'workflow.mermaid',
    containerName: 'Workflow',
    selectAfterInsert: true,
    left: 320,
    top: 240,
  })
}
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IBoardMermaidOptions`](https://unpkg.com/@univerjs-pro/boards-exchange-client@1.0.0-rc.0/lib/types/services/board-mermaid-import.service.d.ts)

**Package:** [`@univerjs-pro/boards-exchange-client`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-exchange-client.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-exchange-client@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

## `@univerjs-pro/boards-mind`

### `FBoard.getMindMap`

Gets a structured mind map by its generated container id.

```typescript
getMindMap(containerId: string): FBoardMindMap | null
```

**Parameters**

* `containerId` — Required. Mind-map container id.

**Returns**

Mind-map facade, or `null` when it is missing.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const inserted = board.insertMindMap({ left: 120, top: 120, root: { text: 'Release' } })
if (!inserted) throw new Error('Cannot insert mind map')
console.log(board.getMindMap(inserted.getId()))
```

**Types:** [`FBoardMindMap`](https://docs.univer.ai/reference/facade/board-mind-map.md)

**Package:** [`@univerjs-pro/boards-mind`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-mind.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-mind@1.0.0-rc.0/lib/types/facade/f-board-mind-map.d.ts)

### `FBoard.getMindMaps`

Gets all structured mind maps in Board z-order.

Use this before a bulk audit or migration. The result only contains structured mind-map containers; ordinary
containers, shapes, and connectors are excluded.

```typescript
getMindMaps(): FBoardMindMap[]
```

**Returns**

Mind map facades, including hidden or locked maps so agents can inspect complete state.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
console.log(board.getMindMaps().map((mindMap) => mindMap.getId()))
```

**Types:** [`FBoardMindMap`](https://docs.univer.ai/reference/facade/board-mind-map.md)

**Package:** [`@univerjs-pro/boards-mind`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-mind.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-mind@1.0.0-rc.0/lib/types/facade/f-board-mind-map.d.ts)

### `FBoard.insertMindMap`

Inserts a structured mind map.

```typescript
insertMindMap(options: IBoardMindMapFacadeInsertOptions): FBoardMindMap | null
```

**Parameters**

* `options` — Required. Position, layout, and root-node tree.

**Returns**

Mind-map facade, or `null` when insertion fails.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const mindMap = board.insertMindMap({
  left: 120,
  top: 120,
  root: { text: 'Release', children: [{ text: 'QA' }, { text: 'Launch' }] },
})
if (!mindMap) throw new Error('Cannot insert mind map')
```

**Types:** [`FBoardMindMap`](https://docs.univer.ai/reference/facade/board-mind-map.md) · [`IBoardMindMapFacadeInsertOptions`](https://unpkg.com/@univerjs-pro/boards-mind@1.0.0-rc.0/lib/types/facade/f-board-mind-map.d.ts)

**Package:** [`@univerjs-pro/boards-mind`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-mind.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-mind@1.0.0-rc.0/lib/types/facade/f-board-mind-map.d.ts)

## `@univerjs-pro/boards-table`

### `FBoard.getTable`

Gets a Board table by its generated host element id.

```typescript
getTable(elementId: string): FBoardTable | null
```

**Parameters**

* `elementId` — Required. Board table host element id.

**Returns**

Table facade, or `null` when it is missing.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const inserted = board.insertTable({ left: 80, top: 80, rows: 3, columns: 3 })
if (!inserted) throw new Error('Cannot insert table')
console.log(board.getTable(inserted.getId()))
```

**Types:** [`FBoardTable`](https://docs.univer.ai/reference/facade/board-table.md)

**Package:** [`@univerjs-pro/boards-table`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-table.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-table@1.0.0-rc.0/lib/types/facade/f-board-table.d.ts)

### `FBoard.getTables`

Gets all table facades in Board z-order.

```typescript
getTables(): FBoardTable[]
```

**Returns**

Board table facades.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
console.log(board.getTables().map((table) => table.getId()))
```

**Types:** [`FBoardTable`](https://docs.univer.ai/reference/facade/board-table.md)

**Package:** [`@univerjs-pro/boards-table`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-table.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-table@1.0.0-rc.0/lib/types/facade/f-board-table.d.ts)

### `FBoard.insertTable`

Inserts a Board table.

```typescript
insertTable(options: IBoardTableFacadeInsertOptions): FBoardTable | null
```

**Parameters**

* `options` — Required. Position, size, dimensions, and optional diagram preset.

**Returns**

Table facade, or `null` when insertion fails.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const table = board.insertTable({ left: 80, top: 80, rows: 3, columns: 3 })
if (!table) throw new Error('Cannot insert table')
```

**Types:** [`FBoardTable`](https://docs.univer.ai/reference/facade/board-table.md) · [`IBoardTableFacadeInsertOptions`](https://unpkg.com/@univerjs-pro/boards-table@1.0.0-rc.0/lib/types/facade/f-board-table.d.ts)

**Package:** [`@univerjs-pro/boards-table`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-table.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-table@1.0.0-rc.0/lib/types/facade/f-board-table.d.ts)

## `@univerjs-pro/boards-thread-comment`

### `FBoard.createElementCommentAsync`

Creates a comment for any Board element ID, including shapes, text, images, charts, tables, connectors, mind maps, and ink.

```typescript
createElementCommentAsync(elementId: string, content: ThreadComment.ThreadCommentContent, options?: IBoardCommentCreateOptions): Promise<boolean>
```

**Parameters**

* `elementId` — Required. Stable ID of an element on the active Board page.
* `content` — Required. Plain text or a Univer document body for rich comment content.
* `options` — Optional. Default: `{}`. Optional stable IDs, author, attachments, and creation time.

**Returns**

`true` when the create command succeeds; otherwise, `false`.

**Throws**

If the element does not exist on the active page.

If the content is empty.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
const chart = board?.getCharts()[0]
if (chart) await board?.createElementCommentAsync(chart.getElementId(), 'Verify this chart.')
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`ThreadComment.ThreadCommentContent`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts) · [`IBoardCommentCreateOptions`](https://unpkg.com/@univerjs-pro/boards-thread-comment@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards-thread-comment`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-thread-comment@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.createPositionCommentAsync`

Creates a free-position comment in Board world coordinates.

```typescript
createPositionCommentAsync(position: IBoardCommentPosition, content: ThreadComment.ThreadCommentContent, options?: IBoardCommentCreateOptions): Promise<boolean>
```

**Parameters**

* `position` — Required. Position in the Board's unscaled world coordinate system.
* `content` — Required. Plain text or a Univer document body for rich comment content.
* `options` — Optional. Default: `{}`. Optional stable IDs, author, attachments, and creation time.

**Returns**

`true` when the create command succeeds; otherwise, `false`.

**Throws**

If either coordinate is not finite or the content is empty.

**Examples**

```ts
await univerAPI
  .getActiveBoard()
  ?.createPositionCommentAsync({ x: 320, y: 180 }, 'Review this area.')
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IBoardCommentPosition`](https://unpkg.com/@univerjs-pro/boards-thread-comment@1.0.0-rc.0/lib/types/facade/f-board.d.ts) · [`ThreadComment.ThreadCommentContent`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts) · [`IBoardCommentCreateOptions`](https://unpkg.com/@univerjs-pro/boards-thread-comment@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

**Package:** [`@univerjs-pro/boards-thread-comment`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-thread-comment@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getComments`

Returns locally loaded element and free-position comments across all pages in this Board.

```typescript
getComments(): ThreadComment.IFacadeThreadCommentInfo[]
```

**Returns**

Every locally loaded comment thread owned by this Board.

**Examples**

```ts
const comments = univerAPI.getActiveBoard()?.getComments() ?? []
comments.forEach(({ root, anchor }) => console.log(root.id, anchor))
```

**Types:** [`ThreadComment.IFacadeThreadCommentInfo`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts)

**Package:** [`@univerjs-pro/boards-thread-comment`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-thread-comment@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.getElementComments`

Returns locally loaded comments for one stable Board element ID on the active page.

```typescript
getElementComments(elementId: string): ThreadComment.IFacadeThreadCommentInfo[]
```

**Parameters**

* `elementId` — Required. Stable ID of the target Board element.

**Returns**

Matching comment threads for the active page and element.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
const elementId = board ? Object.keys(board.getElements())[0] : undefined
const comments = board && elementId ? board.getElementComments(elementId) : []
console.log(comments.length)
```

**Types:** [`ThreadComment.IFacadeThreadCommentInfo`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts)

**Package:** [`@univerjs-pro/boards-thread-comment`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-thread-comment@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.listCommentsAsync`

Synchronizes known threads and returns element and free-position comments across all pages in this Board.

```typescript
listCommentsAsync(): Promise<ThreadComment.IFacadeThreadCommentInfo[]>
```

**Returns**

A promise resolving to every synchronized comment thread owned by this Board.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
const comments = board ? await board.listCommentsAsync() : []
console.log(comments.length)
```

**Types:** [`ThreadComment.IFacadeThreadCommentInfo`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/boards-thread-comment`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-thread-comment@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

### `FBoard.listElementCommentsAsync`

Synchronizes known threads and returns comments for one stable Board element ID on the active page.

```typescript
listElementCommentsAsync(elementId: string): Promise<ThreadComment.IFacadeThreadCommentInfo[]>
```

**Parameters**

* `elementId` — Required. Stable ID of the target Board element.

**Returns**

A promise resolving to matching synchronized comment threads.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
const elementId = board ? Object.keys(board.getElements())[0] : undefined
const comments = board && elementId ? await board.listElementCommentsAsync(elementId) : []
console.log(comments.length)
```

**Types:** [`ThreadComment.IFacadeThreadCommentInfo`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/boards-thread-comment`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/boards-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs-pro/boards-thread-comment@1.0.0-rc.0/lib/types/facade/f-board.d.ts)

## `@univerjs-pro/ink`

### `FBoard.getInks`

Lists persistent Ink elements in Board z-order, including hidden or locked Ink.

```typescript
getInks(): IBoardShapeElement[]
```

**Returns**

Ink shape elements in Board z-order.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
console.log(board.getInks().length)
```

**Types:** [`IBoardShapeElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts)

**Package:** [`@univerjs-pro/ink`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/ink.md) · [Type definitions](https://unpkg.com/@univerjs-pro/ink@1.0.0-rc.0/lib/types/facade/f-board-ink.d.ts)

### `FBoard.insertInk`

Inserts one persistent Ink element through the normal Board command path.

```typescript
insertInk(options: IBoardInkFacadeInsertOptions): IBoardShapeElement | null
```

**Parameters**

* `options` — Required. Ink model, style, element id, and optional container placement.

**Returns**

The inserted Board shape element, or `null` when validation or insertion fails.

**Examples**

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')
const ink = board.insertInk({
  tool: univerAPI.Enum.BoardInkTool.Brush,
  model: {
    kind: 'brush',
    points: [
      { x: 80, y: 80, t: 0 },
      { x: 160, y: 120, t: 1 },
      { x: 240, y: 90, t: 2 },
    ],
    color: '#2563eb',
    width: 4,
    opacity: 1,
  },
})
if (!ink) throw new Error('Cannot insert ink')
```

**Types:** [`IBoardShapeElement`](https://unpkg.com/@univerjs-pro/boards@1.0.0-rc.0/lib/types/board.type.d.ts) · [`IBoardInkFacadeInsertOptions`](https://unpkg.com/@univerjs-pro/ink@1.0.0-rc.0/lib/types/facade/f-board-ink.d.ts)

**Package:** [`@univerjs-pro/ink`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/ink.md) · [Type definitions](https://unpkg.com/@univerjs-pro/ink@1.0.0-rc.0/lib/types/facade/f-board-ink.d.ts)