The paint tree

takumi-paint lays out a document and returns what painting it would draw, instead of an image. Use it when the output is not pixels: an editable PPTX, a Canvas replay, a native drawing API.

Every CSS value arrives resolved. You draw shapes, paints, text, and images; you never parse CSS.

import { renderPaintTree } from "takumi-paint";

const document = await renderPaintTree(
  `<style>.big { font: 700 40px Geist; color: #B3261E }</style>
   <div id="card" style="width: 640px; padding: 32px; background: #F7F3EC; border-radius: 12px">
     <div class="big">4,2 %</div>
     <p>hello <b>world</b></p>
   </div>`,
  { width: 640 },
);

const card = document.find("card");
card?.drawables[0]; // { type: "fill", role: "background", shape: { type: "rounded-rect", … }, paint: { type: "color", color: [247, 243, 236, 255] } }

for (const node of document) {
  if (node.type !== "text") continue;
  for (const run of node.runs) {
    console.log(run.text, run.element?.tagName, run.font.family, run.font.weight, run.fontSize);
  }
}

The package runs the same layout as takumi-js and walks the same stacking-context scene the image, SVG, and PDF backends paint.

Two views of one document

Iterating the document, or a box, yields nodes in document order. find(id) returns the box of the element with that id. Use this view to rebuild editable objects: node.parent and box.children follow the input tree, and a TextRun names the element it came from.

paintSteps() yields the steps a renderer takes, in paint order. Use this view to draw:

import type { Drawable, PaintDocument } from "takumi-paint";

declare function draw(ctx: CanvasRenderingContext2D, drawable: Drawable): void;
declare function newLayer(): CanvasRenderingContext2D;

function replay(ctx: CanvasRenderingContext2D, document: PaintDocument) {
  const layers: CanvasRenderingContext2D[] = [];
  let target = ctx;

  for (const step of document.paintSteps()) {
    switch (step.type) {
      case "draw":
        target.setTransform(...step.node.transform);
        for (const drawable of step.drawables) draw(target, drawable);
        break;
      case "begin-clip":
        target.save();
        target.setTransform(...step.node.transform);
        // Clip to step.clip.
        break;
      case "end-clip":
        target.restore();
        break;
      case "begin-group":
        layers.push(target);
        target = newLayer();
        break;
      case "end-group": {
        const parent = layers.pop() ?? ctx;
        // Filter, clip, and mask the layer per step.node.effects, then blend it into parent.
        parent.resetTransform();
        parent.globalAlpha = step.node.effects?.opacity ?? 1;
        parent.drawImage(target.canvas, 0, 0);
        parent.globalAlpha = 1;
        target = parent;
        break;
      }
    }
  }
}

z-index, negative stacking, and outlines that paint after later siblings are already in the step order.

Coordinates

Every length is a device pixel, and so are the width and height options. A 20px font measures 40 under a devicePixelRatio of 2.

A node's transform maps its local space onto the canvas. Its drawables sit in that local space:

• A box's local space is its border box.
• A text node shares its box's space. A run's x and y are the start of its baseline.
• An image node's local space is its content box.

The vocabulary

Gradient stops interpolate in sRGB. Takumi adds stops where the CSS interpolation space, such as the default Oklab, would differ, and unrolls repeating gradients over the area they cover. Background and mask layers arrive as pattern paints: one tile drawn at every x and y.

A shadow drawable is a blurred copy of its shape, moved by offset, and visible only outside or inside its box. blur is the Gaussian's standard deviation, half of a CSS blur radius.

Every drawable carries a role, such as background, border, box-shadow, outline, text, or text-decoration, so an exporter can put a box's background, border, and shadow back into one shape.

Text

A TextRun holds the final text, its font, and its glyph ids and positions. run.outline() returns the glyphs as SVG path data from the baseline start, so a consumer can draw the text without a font engine. run.font.data() returns the font file for a native text API.

A glyphs drawable fills a run's outline with a paint in the node's space: the text color, a text shadow's color with a blur, or the box's background for background-clip: text. With stroke, it strokes the outline instead, as -webkit-text-stroke does.

What stays unresolved

• filter: url(#id) arrives as { type: "unsupported", css }.
• backdrop-filter needs what is already drawn behind the node, which targets such as PPTX cannot read.
• A translucent layer inside a box, such as a span's opacity, is multiplied into each draw, so overlapping draws in it paint darker than the renderer's layer.
• Bitmap glyphs, such as some emoji fonts, are left out.