@pixxl-tools/candraw

Canvas-first vector document engine for Pixxl Draw.

@pixxl-tools/candraw owns vector item models, path geometry, document commands, reducers, hit testing, canvas rendering, SVG/PNG export, and draw-specific CanvasDocument persona helpers. Shared product chrome belongs in @pixxl-tools/canvas/react.

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

Quick Start

import { createCanvasController } from "@pixxl-tools/candraw";

const canvas = createCanvasController();

canvas.editor.addRectangle(
  { x: 32, y: 32, width: 240, height: 144 },
  { name: "card" },
);
canvas.editor.addText("candraw", { x: 56, y: 96, width: 180, height: 40 });

const document = canvas.editor.getInput();

Lower-level geometry:

import { DEFAULT_STYLE, createRectanglePath } from "@pixxl-tools/candraw/core";

const path = createRectanglePath(
  "rect-1",
  { x: 0, y: 0, width: 100, height: 80 },
  DEFAULT_STYLE,
);

Install/CSS

Install the package with shared canvas helpers:

pnpm add @pixxl-tools/candraw @pixxl-tools/canvas

Core/vector APIs do not require CSS. Product editor chrome uses @pixxl-tools/canvas/react and host styles:

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

Public API

• @pixxl-tools/candraw: public vector APIs plus CanvasDocument persona helpers.
• @pixxl-tools/candraw/core: bounds, matrix, path, point, shape, style, and text layout helpers.
• @pixxl-tools/candraw/document: reducer, commands, project repository, schema, path operations, selection adapter, vectorProjectToCanvasDocument, and canvasDocumentToVectorProject. Use for editor integrations; do not treat reducer internals as stable storage.
• @pixxl-tools/candraw/geometry: cubic curves, intersections, boolean operations, winding, and path conversion.
• @pixxl-tools/candraw/rendering: canvas renderer, overlay renderer, hit testing, SVG export, PNG export, and view state.

Model/Persistence

Draw saves through CanvasDocument from @pixxl-tools/canvas and exposes candraw persona helpers from the root export.

Actively edited element kinds:

• shape
• path
• image
• text

Other element kinds must round-trip unchanged. Vector project snapshots remain the editor/runtime model; persist shared files as CanvasDocument.

Adapter usage:

import {
  canvasDocumentToVectorProject,
  vectorProjectToCanvasDocument,
} from "@pixxl-tools/candraw/document";

const document = vectorProjectToCanvasDocument(vectorProject);
const runtimeProject = canvasDocumentToVectorProject(document);

Command API

import { createCanvasEditor } from "@pixxl-tools/candraw";

const editor = createCanvasEditor();
const rect = editor.addRectangle({ x: 0, y: 0, width: 100, height: 80 });

rect.setStyle({ fill: "var(--pixxl-color-surface)" });
editor.transaction((tx) => {
  tx.addEllipse({ x: 160, y: 0, width: 80, height: 80 });
});

Commands are serializable. History is owned by the shared canvas controller in app integrations.

Examples

Runnable examples:

• examples/candraw/hello.ts: editor-style commands and CanvasDocument output.
• examples/candraw/export-svg.ts: vector snapshot to SVG output.

Use createCanvasController for editor-style commands. Use @pixxl-tools/candraw/core for pure path/shape helpers. Use @pixxl-tools/candraw/rendering for canvas/SVG/PNG output.

• See candraw/docs/vector-model.md for model and geometry boundaries.

Limits

• Canvas rendering is the canonical renderer; SVG export is output-only.
• Path boolean operations are geometric helpers, not a live collaborative command protocol.
• App file menus, resize menus, and project persistence remain in website.

Testing

Relevant checks:

pnpm test

Troubleshooting

• If hit testing misses a shape, check transformed bounds before renderer output.
• If path operations fail, verify input paths are closed when boolean geometry requires closed contours.
• If app menu actions differ from other canvas products, check website/src/components/tools/shared/AppFileMenu.tsx first.

Migration/Versioning

Persist shared files as CanvasDocument. Vector project snapshots are runtime/editor state and should not become a second public storage contract.