Skip to Content
Takumi

See what a document paints

Read where each box, text, and image lands with takumi paint, to find why a render looks wrong without opening the image.

takumi paint lays a document out as takumi image does and writes what it would draw as text. Read it when part of a render is missing, in the wrong place, or the wrong color, or hand it to a script or a coding agent that cannot look at the image.

card.html
<style>
  body {
    margin: 0;
  }
  #card {
    width: 1200px;
    height: 630px;
    padding: 64px;
    box-sizing: border-box;
    background: #0f172a;
    color: white;
    overflow: hidden;
  }
  .title {
    margin: 0;
    font-size: 64px;
  }
  .badge {
    position: absolute;
    left: 1300px;
    top: 40px;
    width: 96px;
    height: 96px;
    background: red;
  }
</style>
<div id="card">
  <h1 class="title">Quarterly report</h1>
  <div class="badge"></div>
</div>
takumi paint card.html -o - --width 1200 --height 630
One line for each node
canvas 1200x630
box html 0,0 1200x630
  box body 0,0 1200x630
    box div#card 0,0 1200x630 background #0f172a clips-overflow
      box h1.title 64,64 1072x83
        text h1.title 64,64 1072x83 "Quarterly report" Geist 700 64px #ffffff
      box div.badge 1300,40 96x96 background #ff0000 offscreen past the right edge

The last line shows why the red badge is missing from the image: left: 1300px puts it past the 1200px canvas.

A line holds the kind of node, a selector for its element, and its rectangle on the canvas as x,y widthxheight. A child is indented under its parent. The rest of the line says what the node shows:

  • a box's background color or gradient, and border or box-shadow when it draws one
  • a text's content, with \n where it wraps to a new line, the font it was shaped in, and its color
  • an image's src and natural size
  • clips-overflow, opacity, filters, and transform when they apply

Four markers point at a node that cannot show in full:

MarkerMeaning
offscreen past the <side> edgeIts rectangle lies outside the canvas, past that edge.
cut off at the <side> edgeIts rectangle crosses that edge, so the canvas shows only part of it.
emptyIt has no width or no height.
draws nothingText or an image that paints no pixel, as visibility: hidden leaves it.

An element that opacity: 0 hides has no node, and neither does anything inside it. Those elements come after the outline, under not painted:

not painted
  div.footer opacity: 0

An element with display: none makes no box, so it appears nowhere in the output. The root element is the exception: <html style="display: none"> is listed under not painted as html display: none.

Each declaration or at-rule the style parser dropped follows, under ignored, with why it was dropped and where it was written. JSON lists the same entries as ignoredDeclarations.

ignored
  @container (width > 400px) unknown-at-rule style-sheet
  writing-mode: vertical-rl unknown-property style-attribute
  filter: blurry(4px) invalid-value style-attribute

An element with display: none is not read, so a declaration only it uses is not listed.

Ask for more

--detail sets how much the output holds:

ValueAdds
nodesOne line for each node. The default.
drawablesA line for each thing a node draws: its fills, borders, and text.
fullThe paint order, which says what covers what and what each clip holds.
takumi paint card.html -o - --detail full
The end of the full output
paint order
  0 draw box div#card
  1 begin clip box div#card
  2 end clip box div#card
  3 begin clip box div#card
  4 draw text h1.title
  5 end clip box div#card
  6 draw box div.badge
  7 begin clip box div#card
  8 end clip box div#card

A later step draws over an earlier one, and a step between begin clip and end clip shows only inside that box. Here the title is clipped to the card, and the badge is drawn outside every clip.

Write JSON

--format json, or an output that ends in .json, writes the same paint tree takumi-paint returns. --detail trims it: nodes leaves out the drawables and the paint order, drawables keeps the drawables but still leaves out each glyph and the paint order, and full holds everything.

takumi paint card.html -o card.json --detail full

The paint reference lists every field.

Check the tree in a script

A script can read the JSON with jq and fail when a render is wrong. Each node's bounds is its rectangle on the canvas, and element names its id, tagName, and className.

This check fails unless the element with the id cta lies fully inside the canvas:

takumi paint card.html -o card.json --width 1200 --height 630

jq -e --arg id cta '
  .width as $w | .height as $h
  | [.nodes[] | select(.element.id == $id) | .bounds
     | .x >= 0 and .y >= 0 and .x + .width <= $w and .y + .height <= $h]
  | length > 0 and all
' card.json

This one fails when the style parser dropped any declaration. The JSON leaves out ignoredDeclarations when nothing was dropped, so default it to an empty list:

jq -e '(.ignoredDeclarations // []) | length == 0' card.json

An element can make several nodes, such as its box and its text, so all requires every one to fit. A hidden element makes no node, and length > 0 fails the check for it too. jq -e exits with 1 when the last value is false, which fails the script.

Last updated on