---
title: "Editors & Canvases"
description: "Choose reusable editor and canvas surfaces without confusing Core compatibility APIs, template patterns, and Toolkit primitives."
---
# Editors & canvases
Editors and canvases are related product surfaces, not one flagship feature.
Choose the smallest reusable layer that matches the interaction your app owns.
IBH1H2
Q3 rollout plan
/ image, table, code block...
"
}
/>
A canvas app can compose Toolkit interaction helpers and annotation UI around its own model. This mock is illustrative; Toolkit does not provide the canvas document, rendering model, or persistence.
SelectDrawCommentCanvas controls
Campaign page
Draw note
12
"
}
/>
## Ownership today
| Surface | Current owner and maturity | Use it when |
| ------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Rich editor | Toolkit-owned | You need portable rich editing, markdown, slash commands, images, drag handles, or collaboration reconciliation. |
| Blocks | Core runtime plus Toolkit UI | Core owns the schema and runtime contract; Toolkit exports the reusable client UI. |
| Design | Template pattern plus reusable `design-tweaks` | You are building a Design-like workflow and can own its domain behavior. |
| Canvas presentation | Toolkit or app composition | You need reusable UI around an app-specific canvas model. |
## Pieces {#pieces}
| Piece | Purpose |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `` | The configurable rich editor: markdown in/out, optional Yjs collaboration, extension toggles. Renders its own bubble toolbar, slash menu, and drag handle. |
| `` | Backwards-compatible alias for ``. |
| `createSharedEditorExtensions()` | The framework Tiptap schema and markdown dialects, for a fully custom editor shell. |
| `` / `createImageSlashCommand()` | The shared slash-command UI and its image-insert command. |
| `` / `buildDefaultBubbleItems()` | The shared selection toolbar for marks, links, and custom inline actions. |
| `` / `createImageExtension()` / `pickAndInsertImage()` | Image node, extension factory, and upload-and-insert helper. |
| `createCodeBlockNode()` | Code block node with a language picker (`DEFAULT_CODE_LANGUAGES`). |
| `` | Per-block drag handle and reorder behavior. |
| `createRegistryBlockNode()` / `` | Registry-backed block nodes rendered inside the rich editor. |
| `useCollabReconcile()` | Binds a Yjs doc to markdown as the saved state. |
## Choose deliberately
Import the portable editor surface from `@agent-native/toolkit/editor`:
```tsx
import {
RichMarkdownEditor,
createSharedEditorExtensions,
useCollabReconcile,
} from "@agent-native/toolkit/editor";
```
`` already wires the bubble toolbar, slash menu, and drag
handle for you, so most apps only need it directly:
```tsx
import { SharedRichEditor } from "@agent-native/toolkit/editor";
;
```
Building a fully custom Tiptap surface instead of ``? Start
from the shared schema and add only the pieces you need:
```tsx
import { useEditor, EditorContent } from "@tiptap/react";
import { createSharedEditorExtensions } from "@agent-native/toolkit/editor";
const editor = useEditor({
extensions: createSharedEditorExtensions({ features: { tables: true } }),
});
;
```
The old `@agent-native/core/client` and `@agent-native/core/client/editor`
import paths are deprecated tombstones, not compatibility re-exports:
importing from them throws an actionable error naming
`@agent-native/toolkit/editor` as the replacement (`RegistryBlockDataProvider`
moved to `@agent-native/core/blocks`, `uploadEditorImage` to
`@agent-native/core/client/uploads`). Run
`npx @agent-native/core@latest upgrade --codemods` to rewrite old imports — see
[Package Lifecycle](/docs/package-lifecycle#migration-manifests-and-tombstones).
Keep app-specific schemas, commands, persistence, upload actions, and registry
adapters in your app or Core as appropriate.
Design is not a drop-in replacement for an editor or general canvas. The
[Design template](/docs/template-design) demonstrates a complete product
pattern; `design-tweaks` are reusable presentation adjustments within that
pattern. Reuse them when they fit, but do not assume they supply a complete
canvas data model, collaboration model, or workflow.
Core owns the Blocks schema, registration, and server/runtime contract. The reusable client UI is exported by `@agent-native/toolkit/app/blocks`, including `BlockView`, `SchemaBlockEditor`, and `BlockRegistryProvider`. Keep app-specific block types and persistence on the app side while the agent and UI share Core's structured contract.
## Canvas interactions and annotations {#canvas-interactions}
Toolkit provides reusable interaction logic and annotation UI for apps that own a canvas:
| Export | What it provides |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@agent-native/toolkit/canvas-interactions` | Headless gesture and shortcut registries, pointer-to-canvas coordinates, drag thresholds, movement constraints, nudge policies, and resize helpers. |
| `@agent-native/toolkit/canvas-annotations` | `DrawOverlay` for drawing/text instructions and `CanvasCommentPins` for anchored feedback that can be sent to the agent. |
These exports do not define a canvas document model, renderer, selection model, or persistence layer. The app adapts gestures to its own canvas, stores annotations through its own actions, and decides which context the agent receives. For a complete product pattern, see the [Design template](/docs/template-design).
## What's next
- [**Toolkit overview**](/docs/agent-native-toolkit) — the full catalog and ownership boundary.
- [**Component API**](/docs/components) — the generated reference for every
public React export, including editor components.
- [**Real-Time Collaboration**](/docs/real-time-collaboration) — presence and
collaborative editing foundations `useCollabReconcile()` builds on.
- [**Design Template**](/docs/template-design) — the Design product pattern.
- [**Package Lifecycle**](/docs/package-lifecycle) — deprecated import paths,
migration manifests, and the `upgrade --codemods` rewrite.