@pixxl-tools/cantext

Canvas-first rich text editor engine for Pixxl Text.

@pixxl-tools/cantext owns the structural document model, editor kernel, command bus, layout engine, import/export transforms, worker coordination, React bindings, and text-specific CanvasDocument persona helpers. It does not own shared canvas app chrome; use @pixxl-tools/canvas/react for that.

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

Quick Start

import { createEditor } from "@pixxl-tools/cantext";

const editor = createEditor({ initialValue: "Draft text" });

editor.dispatch({ type: "insertText", text: " ready" });
console.log(editor.getDocumentStructure());
editor.destroy();

React entrypoints:

import { CantextSurface } from "@pixxl-tools/cantext/react/surface";
import "@pixxl-tools/canvas/styles.css";

Import/export helpers:

import { documentStructureToHtml, htmlToDocumentStructure } from "@pixxl-tools/cantext/html";
import { documentStructureToMarkdown, markdownToDocumentStructure } from "@pixxl-tools/cantext/markdown";

Install/CSS

Install the package with its canvas and React peers:

pnpm add @pixxl-tools/cantext @pixxl-tools/canvas react react-dom

Use core/import/export helpers without CSS. React surfaces need host app CSS:

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

@pixxl-tools/cantext/react is client-only. Worker entrypoints are loaded through @pixxl-tools/cantext/workers or the host app runtime.

Public API

• @pixxl-tools/cantext: createEditor, EditorKernel, OffsetMapper, layout/render helpers, document transforms, style defaults, command types, CanvasDocument persona helpers.
• @pixxl-tools/cantext/core: stable editor core re-export for consumers that do not need React.
• @pixxl-tools/cantext/document: cantextDocumentToCanvasDocument and canvasDocumentToCantextDocument.
• @pixxl-tools/cantext/html: HTML import/export helpers and serialization policy constants.
• @pixxl-tools/cantext/markdown: Markdown import/export helpers.
• @pixxl-tools/cantext/pdf: PDF export helpers.
• @pixxl-tools/cantext/react: full React editor bindings.
• @pixxl-tools/cantext/react/surface: render-only surface primitives.
• @pixxl-tools/cantext/rendering: render scene and page-layout helpers.
• @pixxl-tools/cantext/interaction: shared canvas selection adapter helpers.
• @pixxl-tools/cantext/workers: browser worker runtime entrypoint.

Root exports intentionally include some legacy/internal modules while editor apps migrate. New code should prefer the named subpaths above and avoid depending on worker coordinator internals directly.

Model/Persistence

Canonical rich text is structural JSON: sections, blocks, inline text runs, marks, annotations, tables, anchored objects, comments, suggestions, and document settings. HTML and Markdown strings are import/export concerns, not storage.

Cross-product storage uses CanvasDocument from @pixxl-tools/canvas:

• Active edit kinds: richText, text, and inline image references.
• cantext persona helpers are exported from the root package.
• Other canvas element kinds must round-trip unchanged.

Adapter usage:

import {
  canvasDocumentToCantextDocument,
  cantextDocumentToCanvasDocument,
} from "@pixxl-tools/cantext/document";

const document = cantextDocumentToCanvasDocument(documentStructure);
const roundTripped = canvasDocumentToCantextDocument(document);

Runtime Notes

• createEditor owns an EditorKernel; call destroy() when the editor leaves scope.
• workerMode controls derived runtime behavior for layout/export work.
• Use structural commands or dispatch; avoid mutating document nodes directly.
• Use documentStructureToHtml and documentStructureToMarkdown for export output.

Examples

Runnable examples:

• examples/cantext/hello.ts: in-memory editor lifecycle.
• examples/cantext/import-export.ts: Markdown and HTML conversion.

Use createEditor({ initialValue }) for in-memory editing. Use @pixxl-tools/cantext/html and @pixxl-tools/cantext/markdown for import/export.

• cantext/docs/document-model.md for storage and conversion rules.
• website/src/components/tools/cantext for product chrome integration.

Testing

Relevant checks:

pnpm test
pnpm bench

Run visual tests when layout, pagination, render scene, or app chrome changes.

Limits

• Canvas rendering is authoritative for app display; HTML/Markdown/PDF are import/export surfaces.
• Worker runtime may fall back to main-thread derivation when worker setup fails.
• Root export still carries legacy/internal compatibility symbols; new code should use subpaths.

Troubleshooting

• If layout differs between worker and main thread, run visual tests and inspect page geometry before changing baselines.
• If commands do nothing, verify editor is not destroyed and command payload matches EditorCommand.
• If exported HTML/Markdown drops styling, confirm style exists in structural JSON and is supported by the target serializer.

Migration/Versioning

Prefer additive document fields and normalize at load boundaries. Legacy root exports stay until consumers migrate to documented subpaths.