@penster/canvas-types

Canonical types, validation, version interpreters, and Fabric conversion helpers for the Penster Canvas system.

Philosophy

• Single schema family with pensterVersion on every entity (document/page/layer).
• Runtime interpreters upgrade older docs on load — no V1/V2 class explosion.
• Fabric-friendly: Penster stores structured layers; editor renders a flattened Fabric JSON.
• Backend validated: Zod schemas validate all incoming data before persistence.

Install

npm i @penster/canvas-types

Usage

Create a minimal document

import { createMinimalPensterDocument } from "@penster/canvas-types";

const doc = createMinimalPensterDocument({
  width: 1080,
  height: 1080,
  backgroundColor: "#ffffff",
  // or backgroundImage: "https://cdn.../bg.png"
});

Validate on backend

import { PensterDocumentSchema, interpretPenster } from "@penster/canvas-types";

const parsed = PensterDocumentSchema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "Invalid schema" });

const doc = interpretPenster(parsed.data);
// save doc...

Convert page to Fabric JSON (render)

import { pensterToFabricJSON } from "@penster/canvas-types";

const fabricJSON = pensterToFabricJSON(doc.pages[0]);

Convert Fabric JSON back to Penster (persist layer objects)

import { fabricToPensterPage } from "@penster/canvas-types";

doc.pages[0] = fabricToPensterPage(doc.pages[0], fabricJSON);

Versioning

• CURRENT_PENSTER_VERSION exported for sanity checks.
• Interpreters live in src/interpreter.ts and centralize evolution logic.

License

See LICENSE.md.