canvas_core

canvas_core is a pure-Dart canvas document engine. It provides a serializable scene graph, platform-neutral geometry primitives, deterministic scene computation, hit testing, snapping, viewport math, and renderer-agnostic paint operations.

Use it when you want to model or transform canvas-style documents without depending on Flutter, dart:ui, widgets, files, HTTP, or a specific rendering backend.

Features

CanvasSceneDocument and Node models for text, image, icon, path, and group content.
Stable JSON serialization for storing, syncing, and round-tripping scene documents.
computeScene for deterministic transforms, draw order, bounds, and cached geometry.
buildPaintOpsFromScene for a renderer-neutral draw plan.
Headless editor helpers for hit testing, snapping, history, and viewport calculation.
Host-service contracts for text measurement, image intrinsics, image source resolution, and icon resolution.
Generic scene font-family discovery for renderer/resource preflight.

Installation

Add the package to your app or package:

dart pub add canvas_core

For Flutter projects:

flutter pub add canvas_core

Imports

Import the runtime API for documents, geometry, services, scene computation, and paint operations:

import 'package:canvas_core/canvas_core_runtime.dart';

Import the editor utilities only when you need headless interaction helpers such as hit testing, snapping, or undo history:

import 'package:canvas_core/canvas_core_editor.dart';

Do not import files under package:canvas_core/src/; use the public barrels above.

Basic usage

Create a document, compute it with host services, and build paint operations for any renderer:

import 'package:canvas_core/canvas_core_runtime.dart';

final document = CanvasSceneDocument(
  artboardSize: const Size2D(1080, 1080), 
  backgroundFill: const CanvasFill.none(),
  backgroundOpacity: 1.0,
  children: <Node>[
    Node.text(
      id: 'headline',
      xf: const Transform2D(position: Vec2(540, 540)),
      data: const TextData(
        text: 'Hello canvas',
        fontFamily: 'Inter',
        fontWeight: 700,
        fontSize: 72,
      ),
    ),
  ],
);

final services = CoreServices(textMeasurer: myTextMeasurer);
final computed = computeScene(document, services);
final paintOps = buildPaintOpsFromScene(document, computed);

myTextMeasurer is supplied by your runtime. A Flutter app can use FlutterTextPipeline from canvas_renderer_flutter; a server or CLI can implement TextMeasurer directly.

Runtime resource discovery

Core discovers logical resource requirements without loading platform resources.

Use collectSceneFontFamilies to collect text and font-backed icon families, including hidden and nested scene content:

final fontFamilies = collectSceneFontFamilies(
  document,
  fallbackFontFamilies: fallbackFontFamilies,
  icons: myIconResolver,
);

Immutable node editing

NodeEditingX provides common immutable field edits that preserve node identity and tree structure:

final renamed = node.withName('Headline');
final moved = renamed.withXf(nextTransform);
final hidden = moved.withHidden(true);
final locked = hidden.withLocked(true);

Use SceneTreeOps for structural operations such as adding, deleting, moving, duplicating, or reordering scene nodes.

JSON round-trip

final json = encodeCanvasScene(document);
final restored = decodeCanvasScene(json);

Rendering pipeline

The canonical runtime flow is:

CanvasSceneDocument
  -> optional host-invoked ScenePreparer
  -> CanvasRenderPipeline.build()
  -> RenderSnapshot
  -> renderer-specific PaintOp replay

ScenePreparer is a synchronous, renderer-neutral transformation applied by the host before building:

final renderPipeline = CanvasRenderPipeline(
  textMeasurer: myTextMeasurer,
  images: myImageIntrinsics,
  icons: myIconResolver,
);

final preparedScene =
    scenePreparer?.call(document, renderPipeline.services) ?? document;

final snapshot = renderPipeline.build(preparedScene);

CanvasRenderPipeline does not invoke preparation automatically. Its stable services instance can be shared with preparation so preparation and final layout use the same host services.

Renderers consume PaintOp values. They do not need to interpret the scene graph, layout rules, or z-order themselves.

Architecture

See doc/architecture.md for package entrypoints, data flow, and layering guidance.

Versioning

canvas_core follows semantic versioning. While the package is below 1.0.0, breaking changes are released as 0.(x+1).0.

See VERSIONING.md for the full policy.

Package boundaries

canvas_core is Dart-only and must stay independent of Flutter and dart:ui.
Text measurement, image intrinsic sizes, and icon lookup are host services.
Paint, hit testing, snapping, selection, and export should reuse ComputedScene so they agree on transforms and bounds.
Public consumers should import only canvas_core_runtime.dart and, when needed, canvas_core_editor.dart.

License

Licensed under the Apache License, Version 2.0. See LICENSE.