@pixxl-tools/canvas

Shared document, editor, workspace, and React chrome for Pixxl canvas products.

@pixxl-tools/canvas is the shared home for canvas-product infrastructure. Product packages such as @pixxl-tools/cantext, @pixxl-tools/candraw, @pixxl-tools/cangraph, and @pixxl-tools/canchart own their domain engines; this package owns the common CanvasDocument, controller, history/runtime primitives, selection/workspace utilities, renderer registry, persona adapters, and reusable app chrome.

Package status: pre-1.0 public package. APIs may change before 1.0.

Quick Start

import { createCanvasDocument, createCanvasEditor } from "@pixxl-tools/canvas";

const document = createCanvasDocument({ width: 1024, height: 768 });
const editor = createCanvasEditor({ input: document });

editor.addText("Hello canvas", {
  x: 64,
  y: 64,
  width: 240,
  height: 48,
});

React chrome lives in the ./react subpath:

import {
  CanvasAppLayout,
  CanvasInspectorSidebar,
  CanvasWorkspace,
} from "@pixxl-tools/canvas/react";
import "@pixxl-tools/canvas/styles.css";

Install/CSS

Install the package and React when using React chrome:

pnpm add @pixxl-tools/canvas react

Import shared chrome CSS once in the host app:

import "@pixxl-tools/canvas/styles.css";

Use @pixxl-tools/canvas/react only in browser/client React surfaces. Non-React document, editor, runtime, and workspace helpers are available from the root package.

Public API

Use these entrypoints in product code:

• @pixxl-tools/canvas: CanvasDocument, canvasDocumentCodec, document helpers, CanvasEditor, createCanvasEditor, createCanvasController, command/history/runtime helpers, persona helpers.
• @pixxl-tools/canvas/react: CanvasWorkspace, CanvasAppLayout, rails, right sidebar, pages panel, inspector sidebar, CanvasJsonInspectorPanel, useCanvasJsonDraft, JSON draft parse/format helpers, preset preview panels, workspace refs.
• @pixxl-tools/canvas/metadata: package metadata for docs and app registries.
• @pixxl-tools/canvas/generator: generation helpers for app examples and fixtures.
• @pixxl-tools/canvas/tokens: strict utility tokens used by canvas rendering code.
• @pixxl-tools/canvas/styles.css: shared chrome styles.
• @pixxl-tools/canvas/canvas-document.v1.schema.json: legacy schema fixture kept for compatibility tests.

Broad root exports are still available for compatibility. New code should prefer the entrypoint that matches the concern instead of importing renderer or React helpers from the root.

Model/Persistence

CanvasDocument is the canonical saved shape for canvas products.

• Current schema: pixxl.canvas.document.
• Current version: 2.
• Known element kinds: shape, path, text, richText, image, chart, connector, group, frame.
• Unknown element kinds must validate as generic canvas elements and round-trip unchanged.
• Product-specific payloads belong in element.data, element.meta, or shared resources, not in alternate root formats.

Create and normalize documents through helpers:

import {
  canvasDocumentCodec,
  cloneCanvasDocument,
  createCanvasDocument,
  normalizeCanvasDocument,
} from "@pixxl-tools/canvas";

Use canvasDocumentCodec.parse, validate, migrate, serialize, clone, createEmpty, and toPrettyJson at file/import boundaries. Product apps should save CanvasDocument JSON and derive product runtime state through product adapters. JSON inspector textareas should parse strings with parseCanvasDocumentJsonDraft or formatCanvasDocumentJsonDraft from @pixxl-tools/canvas/react before calling product adapters.

Product Boundaries

• Keep shared workspace and chrome in @pixxl-tools/canvas/react.
• Keep host-specific controls, icons, and tokens outside @pixxl-tools/canvas.
• Keep app-only file actions in website/src/components/tools/shared.
• Do not move renderer engines, app state machines, chart data editors, rich-text formatting, vector commands, or graph layout internals into @pixxl-tools/canvas.

Examples

Runnable examples:

• examples/canvas/hello.ts: low-level document/editor flow.
• examples/canvas/react-chrome.tsx: shared React chrome composition.

Use createCanvasDocument and createCanvasEditor for low-level document/editor flows. Use CanvasAppLayout, CanvasWorkspace, CanvasInspectorSidebar, CanvasJsonInspectorPanel, useCanvasJsonDraft, CanvasShellPresetPanel, and CanvasPresetPreviewPanel for product chrome.

• See canvas/docs/react-chrome.md for the shared app shell contract.

Testing

Relevant checks:

pnpm lint
pnpm test
pnpm check

Run pnpm test when app chrome or canvas layout CSS changes.

Limits

• @pixxl-tools/canvas owns shared document/chrome primitives, not product render engines.
• Unknown element kinds must round-trip unchanged.
• CSS class names and tokens are public chrome contracts once used by products.

Troubleshooting

• Missing layout or rail styling usually means @pixxl-tools/canvas/styles.css was not imported.
• If product state does not persist, check CanvasDocument schema, version, pages, elements, and product payload placement.
• If a chrome change fails visual tests, first check sidebar width, rail state, and page geometry before approving baselines.

Migration/Versioning

Keep additive changes in v2 CanvasDocument. New product payloads belong in data, meta, or resources. Breaking schema changes require a migration doc and compatibility tests.