justskill-design 0.0.1 → 3.2.0

package/lib/readers/pen.mjs

@@ -0,0 +1,1684 @@
+/**
+ * lib/readers/pen.mjs — a `.pen` file to a design file.
+ *
+ * One direction only, and honestly so. Reading is a mapping exercise: pen's
+ * model is close enough to HTML with inline CSS that most of it has a direct
+ * spelling. Writing back is a different product, so there is no writer, and no
+ * pretence of one.
+ *
+ * Every loss is counted. `importPen` returns a ledger with three columns:
+ *
+ *   - `lost`       something in the file has no spelling here and is gone
+ *   - `converted`  a value was rewritten to the one spelling this format allows
+ *   - `unmapped`   a property this reader does not know at all, by name
+ *
+ * The ledger is the point. A silent import is how a user loses a gradient and
+ * finds out on the review screen.
+ *
+ * ## What maps to what
+ *
+ * Pen has no CSS, so the mapping is by intent, not by name:
+ *
+ *   - a top-level frame becomes a page (`<section data-type="page">`)
+ *   - `layout: "vertical"` becomes `display:flex;flex-direction:column`
+ *   - an absent `layout` becomes `display:flex;flex-direction:row`
+ *   - an absent `alignItems` becomes `align-items:flex-start`, on a row and on a
+ *     column alike. Pen's own exporter writes `flex-start` for both, and
+ *     centring a row moved every nanny card's text 2px down against its photo
+ *   - `justifyContent`/`alignItems` become the CSS properties, with
+ *     `space_between` becoming `space-between`
+ *   - `fill` is `background-color`, except on text and icons, where it is `color`
+ *   - an image fill's `mode` is `background-size`: `cover` and `contain` carry
+ *     over as themselves, `fill` stretches and is `100% 100%`. Pen's own export
+ *     writes both spellings. A mode with no CSS word for it is counted as
+ *     unmapped instead of quietly becoming `cover`, which crops what the design
+ *     stretched
+ *   - `cornerRadius: 9999` stays a pixel radius, because `50%` on a 375x48 bar
+ *     draws an ellipse and pen means a pill
+ *   - `ellipse` becomes `data-kind="ellipse"` plus `border-radius:50%`
+ *   - `clip` becomes `overflow:hidden`
+ *   - `textGrowth: "fixed-width"` becomes `white-space:normal` on a fixed width
+ *   - a `ref` is inlined: the node it names is copied in, the copy's root keeps
+ *     the reference's own id and its descendants are renumbered under it, because
+ *     this format stores no reference and an id is unique across the file. The
+ *     copy is counted in `refs.inlined`
+ *   - `descendants` patches are applied to that copy, field by field. An `icon`
+ *     field swaps the glyph the copy draws, because a glyph is geometry here and
+ *     a name is only its label
+ *   - `variables` become the token block, and `$name` references become `var()`
+ *   - `x`/`y` become `data-canvas`
+ *
+ * ## What has no spelling, and is counted as lost
+ *
+ * Non-linear gradients, mesh gradients, more than one fill, inner shadows,
+ * slots, themes, prototype links, and any property not in the list above. Each
+ * one is named in the ledger rather than dropped in the dark.
+ *
+ * Pure. No node: imports, so the canvas could read a `.pen` file too.
+ */
+
+import { parse, prepareBuiltDocument } from "../parse.mjs";
+import { ICONS, ICON_LIBRARY, ICON_VIEW_BOX, hasIcon, iconBody } from "../icons.mjs";
+import { pathBounds, rotatePath } from "../svg-path.mjs";
+import { serializeCanonical } from "../serialize.mjs";
+import { ensureGenericFamily, normalizeColor, normalizeValue, normalizeStyleText, round3, TOKEN_GROUP_UNIT, TOKEN_GROUPS } from "../table.mjs";
+import { baseCss } from "../base-css.mjs";
+
+export const PEN_VERSION_SUPPORTED = ["2.6", "2.19"];
+
+const ICONS_COUNT = Object.keys(ICONS).length;
+
+// -- json with comments -------------------------------------------------------
+
+/**
+ * Pen allows `//` and `/* *\/` comments in its JSON.
+ * A naive strip would eat a `//` inside a string, such as a URL.
+ */
+export function stripJsonComments(source) {
+  const text = String(source);
+  let out = "";
+  let inString = false;
+  let quote = null;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (inString) {
+      out += ch;
+      if (ch === "\\") { out += text[i + 1] ?? ""; i += 1; continue; }
+      if (ch === quote) inString = false;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { inString = true; quote = ch; out += ch; continue; }
+    if (ch === "/" && text[i + 1] === "/") {
+      while (i < text.length && text[i] !== "\n") i += 1;
+      out += "\n";
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2);
+      i = end === -1 ? text.length : end + 1;
+      continue;
+    }
+    out += ch;
+  }
+  return out;
+}
+
+/** A refusal a caller can branch on, in the shape the CLI reports by name. */
+export function penError(code, message) {
+  const failure = new Error(message);
+  failure.code = code;
+  return failure;
+}
+
+export function parsePen(text) {
+  let json;
+  try {
+    json = JSON.parse(stripJsonComments(text));
+  } catch (error) {
+    throw penError("pen/invalid-json", `The .pen file is not JSON: ${error.message}`);
+  }
+  if (!json || typeof json !== "object" || !Array.isArray(json.children)) {
+    throw penError("pen/no-pages", "The .pen file has no children array, so it holds no artboards.");
+  }
+  return json;
+}
+
+// -- the ledger ---------------------------------------------------------------
+
+export function createLedger() {
+  return {
+    version: null,
+    pages: 0,
+    sourceNodes: 0,
+    nodes: 0,
+    lost: {},
+    converted: {},
+    unmapped: {},
+    refs: { found: 0, inlined: 0, overridesApplied: 0, overrideFieldsDropped: 0 },
+    notes: [],
+  };
+}
+
+function count(target, key, by = 1) {
+  target[key] = (target[key] ?? 0) + by;
+}
+
+// -- escaping and ids ---------------------------------------------------------
+
+const TEXT_ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;" };
+const ATTR_ESCAPES = { "&": "&amp;", '"': "&quot;", "<": "&lt;", ">": "&gt;" };
+
+const escapeText = (value) => String(value ?? "").replace(/[&<>]/g, (ch) => TEXT_ESCAPES[ch]);
+const escapeAttr = (value) => String(value ?? "").replace(/[&"<>]/g, (ch) => ATTR_ESCAPES[ch]);
+
+/** Pen does not constrain ids. This format does, so a bad one is rewritten. */
+export const ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
+
+/**
+ * Pen ids to ids this format accepts.
+ *
+ * The result maps a NODE to its new id, not an id string to a new id string: a
+ * pen file may carry the same id twice, and a string-keyed map would silently
+ * keep only the last one, leaving the first node unimportable.
+ *
+ * @returns {Map<object, string>}
+ */
+export function idMapFor(json) {
+  const used = new Set();
+  const mapping = new Map();
+  const visit = (node) => {
+    const original = typeof node.id === "string" ? node.id : null;
+    let candidate = original
+      ? (ID_PATTERN.test(original) ? original : sanitiseId(original))
+      : `n-${mapping.size + 1}`;
+    if (used.has(candidate)) {
+      let n = 2;
+      while (used.has(`${candidate}-${n}`)) n += 1;
+      candidate = `${candidate}-${n}`;
+      count(temporaryLedger.converted, "duplicateIds");
+    }
+    used.add(candidate);
+    mapping.set(node, candidate);
+    for (const child of node.children ?? []) visit(child);
+  };
+  for (const artboard of json.children) visit(artboard);
+  return mapping;
+}
+
+/**
+ * The node each source id names, for a file with unique ids.
+ *
+ * This is what inlining a `ref` reads: the reference stores the NAME of the node
+ * it points at, and the copy has to be made from that node's own subtree.
+ */
+export function idLookup(json) {
+  const byNode = idMapFor(json);
+  const byIdNode = new Map();
+  const visit = (node) => {
+    if (typeof node.id === "string" && !byIdNode.has(node.id)) byIdNode.set(node.id, node);
+    for (const child of node.children ?? []) visit(child);
+  };
+  for (const artboard of json.children) visit(artboard);
+  return { byNode, byIdNode };
+}
+
+function sanitiseId(raw) {
+  const cleaned = String(raw).replace(/[^A-Za-z0-9_-]/g, "-").replace(/^[^A-Za-z_]+/, "");
+  return cleaned.slice(0, 64) || `n-${Math.abs(hash(String(raw))).toString(36)}`;
+}
+
+function hash(text) {
+  let h = 0;
+  for (let i = 0; i < text.length; i += 1) h = ((h << 5) - h + text.charCodeAt(i)) | 0;
+  return h;
+}
+
+// -- variables ----------------------------------------------------------------
+
+/**
+ * Pen variables become the token block. The group comes from the name's own
+ * prefix when it is one of the seven, so `$space-md` lands in `--space-md` and
+ * `$surface-container` lands in `--color-surface-container`.
+ *
+ * A variable that is themeable carries a LIST of values rather than one, and the
+ * list is not a value. Reading it as one used to write the string
+ * "[object Object],[object Object]" into the token block — a file that validated
+ * and whose tokens meant nothing. The entry with no `theme` of its own is the one
+ * every theme starts from and the one pen's own export inlines, so that entry is
+ * the value; a variable with nothing readable in it is left out and named, which
+ * leaves its references visible to the validator instead of silently wrong.
+ */
+export function tokensFromVariables(variables, ledger) {
+  const tokens = new Map();
+  const refs = new Map();
+  for (const [name, definition] of Object.entries(variables ?? {})) {
+    const raw = definition && typeof definition === "object" ? definition.value : definition;
+    const value = Array.isArray(raw) ? defaultThemeValue(raw, ledger) : raw;
+    const type = definition && typeof definition === "object" ? definition.type : null;
+    if (value !== null && typeof value === "object") {
+      count(ledger.lost, "unresolvedVariable");
+      ledger.notes.push(`variable ${name} carries ${Array.isArray(value) ? "a list of values" : "an object"} where this format wants one value; it was left out of the token block, and its references will not resolve`);
+      continue;
+    }
+    const cssName = tokenNameFor(name, type);
+    let cssValue;
+    if (type === "number") {
+      const unit = TOKEN_GROUP_UNIT[cssName.slice(2).split("-")[0]] ?? "px";
+      cssValue = `${value}${unit}`;
+      count(ledger.converted, "numericTokens");
+    } else if (type === "string") {
+      // A `--font-*` token holds a family list, and pen's own export writes
+      // `system-ui, sans-serif` after every list it emits. A list that ends in a
+      // webfont ends in something the machine may not have, so the fallback
+      // becomes the DOCUMENT default — a serif face on most engines, and a
+      // different layout with it. The fallback goes on the token, because the
+      // elements reference the token and never spell a family themselves.
+      const quoted = `"${String(value)}"`;
+      cssValue = cssName.startsWith("--font-") ? ensureGenericFamily(quoted) : quoted;
+      count(ledger.converted, "stringTokens");
+    } else {
+      try {
+        cssValue = normalizeColor(String(value));
+      } catch {
+        cssValue = String(value);
+        count(ledger.converted, "unparsedColors");
+      }
+    }
+    tokens.set(cssName, { name: cssName, value: cssValue, type: type ?? "color" });
+    refs.set(name, cssName);
+    if (cssName !== `--${name}`) count(ledger.converted, "renamedTokens");
+  }
+  return { tokens, refs };
+}
+
+/** The entry a themed variable carries for the document's default theme. */
+function defaultThemeValue(entries, ledger) {
+  count(ledger.converted, "themedVariables");
+  const plain = entries.find((entry) => entry && typeof entry === "object" && entry.theme === undefined);
+  return plain ? plain.value : entries[0]?.value;
+}
+
+function tokenNameFor(name, type) {
+  const raw = String(name);
+  const lower = raw.toLowerCase().replace(/[^a-z0-9-]/g, "-");
+  const group = lower.split("-")[0];
+  if (TOKEN_GROUPS.includes(group)) return `--${lower}`;
+  const fallback = type === "number" ? "space" : type === "string" ? "font" : "color";
+  count(temporaryLedger, "tokensWithoutGroup");
+  return `--${fallback}-${lower}`;
+}
+
+// The token group fallback needs the ledger, and a module-level handle keeps
+// `tokenNameFor` a pure function of its own name. It is set during an import.
+let temporaryLedger = createLedger();
+
+/** `$name` becomes `var(--name)`, or the value itself when it is not a token. */
+export function resolveReference(value, refs, ledger) {
+  if (typeof value !== "string" || !value.startsWith("$")) return value;
+  const name = value.slice(1);
+  const cssName = refs.get(name) ?? `--${name}`;
+  if (!refs.has(name)) count(ledger.unmapped, "unresolvedVariableReferences");
+  return `var(${cssName})`;
+}
+
+// -- style mapping ------------------------------------------------------------
+
+const JUSTIFY = { space_between: "space-between", space_around: "space-around", space_evenly: "space-around", start: "flex-start", end: "flex-end", center: "center" };
+const ALIGN = { start: "flex-start", end: "flex-end", center: "center", stretch: "stretch", baseline: "baseline" };
+
+/**
+ * An image fill's `mode`, as CSS `background-size`.
+ *
+ * Pen states how the image meets its box. `cover` and `contain` carry over as
+ * the same keywords; `fill` stretches the image to the box, which CSS writes as
+ * `100% 100%`. A mode that is not here is not guessed at — the ledger reports it
+ * as unmapped, because a crop where the design stretches is exactly the kind of
+ * difference nobody looks for.
+ */
+const IMAGE_FILL_SIZE = { cover: "cover", contain: "contain", fill: "100% 100%" };
+
+/**
+ * Pen node to an inline `style` value.
+ *
+ * The order of the checks is the order of precedence: a text node's `fill` is
+ * a colour for the glyphs, not a background.
+ */
+export function styleFromNode(node, refs, ledger, context = {}) {
+  const style = new Map();
+  const set = (property, value) => {
+    if (value === undefined || value === null || value === "") return;
+    style.set(property, value);
+  };
+
+  // A child of a `layout:none` frame is placed by its own x and y, and by nothing else.
+  //
+  // This is the other half of the `relative` set below: with neither, the child is a
+  // block box in the parent's flow, so two children that overlap in pen (a battery body
+  // and the fill inside it) stack in the file. `left`/`top` are the properties the table
+  // accepts for this, and `position` before `width` is the emit order.
+  if (context.parentLayoutNone === true && Number.isFinite(node.x) && Number.isFinite(node.y)) {
+    set("position", "absolute");
+    set("left", `${round3(node.x)}px`);
+    set("top", `${round3(node.y)}px`);
+    count(ledger.converted, "absoluteChild");
+  }
+
+  // Three cases, and the difference between the last two matters:
+  //
+  //   "vertical"   a column
+  //   "horizontal" a row, which is also pen's DEFAULT when `layout` is absent
+  //   "none"       no flow at all; the children are positioned absolutely
+  //
+  // Reading an absent `layout` as a column is a tempting mistake and a costly
+  // one: 208 frames in the reference file have more than one child and no
+  // `layout` field, and every one of them is a row.
+  //
+  // `none` used to be counted as a conversion and then not converted: the frame got no
+  // declarations at all, so its children — which pen places by their own x and y — became
+  // ordinary block boxes and stacked. The status bar's battery fill rendered *below* the
+  // battery body instead of inside it. Now the frame becomes the containing block (see
+  // the absolute placement below) and `relative` is what makes that true.
+  if (node.layout === "none") {
+    set("position", "relative");
+    count(ledger.converted, "layoutNone");
+  } else if (node.layout === "vertical") {
+    set("display", "flex");
+    set("flex-direction", "column");
+    // Pen's own default for a column. It matters more than it looks: with
+    // `stretch`, a frame with no width fills the column, and the reference
+    // artboard renders its buttons as full-width bars instead of the pills it
+    // drew. `flex-start` is what pen means when it does not say.
+    set("align-items", "flex-start");
+    if (node.gap !== undefined) set("gap", `${node.gap}px`);
+  } else if (hasElementChildren(node)) {
+    set("display", "flex");
+    set("flex-direction", "row");
+    set("align-items", "flex-start");
+    if (node.gap !== undefined) set("gap", `${node.gap}px`);
+  }
+
+  // An explicit value is written AFTER the default, or the default erases it.
+  if (node.justifyContent) set("justify-content", JUSTIFY[node.justifyContent] ?? node.justifyContent);
+  if (node.alignItems) set("align-items", ALIGN[node.alignItems] ?? node.alignItems);
+
+  if (node.padding !== undefined) {
+    const padding = Array.isArray(node.padding) ? node.padding : [node.padding];
+    set("padding", boxValue(padding));
+  }
+
+  const parentIsRow = context.parentIsRow === true;
+  const parentIsColumn = context.parentIsColumn === true;
+
+  // Pen's `width` on an auto-layout REUSABLE frame is the CONTENT width, and the
+  // padding sits outside it. Pen's own exporter says so: in the reference
+  // artboard it writes `content-box` on exactly two nodes, `TabBar` and
+  // `BottomActionBar`, and `border-box` on the other 115.
+  //
+  // Both conditions are load-bearing, and each one is a measured counterexample:
+  //
+  //   `reusable`    `Month/2026年9月` is a column with `gap` and 12px of padding
+  //                 on both sides, and its 236px is the BORDER box. Only the
+  //                 reusable masters state a content width.
+  //   `layout|gap`  `StatusBar` is a master with 48px of padding, and its 375px
+  //                 is the border box too, because it is a fixed-position frame
+  //                 and not an auto-layout one.
+  //
+  // Across the whole reference file the rule matches ten nodes, and eight of
+  // them have no padding on the axis they declare, so they do not move. The two
+  // that do move are `TabBar` 375 → 423 and `BottomActionBar` 375 → 407, which
+  // is what pen's own export of the same artboard measures.
+  const autoLayout = node.layout === "vertical" || node.layout === "horizontal" || node.gap !== undefined;
+  const pad = node.reusable === true && autoLayout && node.padding !== undefined ? paddingSides(node.padding) : null;
+
+  // Filling is about the axis, and only a container can fill one.
+  //
+  //   in a ROW, `fill_container` on the width shares the main axis: flex:1.
+  //   in a COLUMN, the width is the cross axis and stretches.
+  //   `fill_container` on a HEIGHT is the cross axis in a row and the main axis
+  //   in a column.
+  //
+  // Two mistakes live here, and both are quiet. Writing `100%` collapses,
+  // because a percentage inside an auto-width parent resolves to zero. And
+  // stretching a text node along a row stretches it VERTICALLY, which is not
+  // what the author asked for: the sheet in the reference modal grew to four
+  // times its height that way. A text node hugs its content instead.
+  if (node.width !== undefined) {
+    const value = widthValue(node.width, node.textGrowth, parentIsRow ? true : parentIsColumn ? false : undefined);
+    if (value === FILL_ALONG) {
+      if (context.text && !hasElementChildren(node)) set("width", "fit-content");
+      else { set("flex", "1 1 0%"); set("min-width", "0"); }
+    } else if (value === FILL_ACROSS) {
+      if (context.text && !hasElementChildren(node)) set("width", "fit-content");
+      // `align-self: stretch` is the obvious spelling and it is the wrong one:
+      // it is overridden by the parent's own `align-items`, and a column whose
+      // author wrote `align-items: flex-start` — which pen does by default —
+      // then leaves the child hugging its content. A tab bar collapsed from
+      // 327px to 38px that way. `100%` fills a parent that has a definite
+      // width, which is the case where pen says `fill_container` on the cross
+      // axis.
+      else set("width", "100%");
+    } else {
+      set("width", paddedSize(value, pad, "x"));
+    }
+  }
+  if (node.height !== undefined) {
+    const value = heightValue(node.height, parentIsColumn ? true : parentIsRow ? false : undefined);
+    if (value === FILL_ALONG) { set("flex", "1 1 0%"); set("min-height", "0"); }
+    else if (value === FILL_ACROSS) set("align-self", "stretch");
+    else set("height", paddedSize(value, pad, "y"));
+  }
+
+  // A frame with no width stretches to its parent, which is the flex default
+  // and what pen means by an unset width on a container. Only a leaf hugs its
+  // content, because a leaf has nothing to stretch around.
+  if (node.width === undefined && !hasElementChildren(node) && context.text) set("width", "fit-content");
+
+  // Pen's auto layout is a fixed-position model: a control keeps the size it was
+  // drawn at, and nothing shrinks to fit. CSS flexbox is the opposite — every
+  // item starts at `flex-shrink: 1` — so a 375px status bar inside a 404px column
+  // gets squeezed, and the whole artboard reads as squashed.
+  //
+  // Pen's own exporter states this on every flex child, and the pen FILE has no
+  // field for it: it is what the format means, not something the author chose.
+  // So it is written here, where pen's semantics are translated, and not in the
+  // format table, where it would rewrite every hand-written design.
+  const penType = node.type;
+  const isContainer = penType === "frame" || node.reusable === true;
+  if (isContainer && !style.has("flex")) set("flex-shrink", "0");
+
+  if (node.textGrowth === "fixed-width" && node.width === undefined) {
+    set("white-space", "normal");
+    count(ledger.converted, "textGrowth");
+  }
+
+  // A fill is a background on a box and a colour on a glyph — except on a glyph
+  // that strokes its own outline, where the stroke IS the drawing. There the
+  // stroke's paint is the colour, and a fill beside it is named as lost by
+  // `glyphPlan`: this format gives a glyph one paint, and the element's `color`
+  // is it.
+  const glyphStrokePaint = context.glyph ? glyphStroke(node) : null;
+  const fill = node.fill;
+  if (glyphStrokePaint) {
+    set("color", colourValue(resolveReference(glyphStrokePaint.paint, refs, ledger), ledger));
+  } else if (typeof fill === "string") {
+    const value = colourValue(resolveReference(fill, refs, ledger), ledger);
+    if (context.glyph) set("color", value);
+    else if (context.text) set("color", value);
+    else set("background-color", value);
+  } else if (fill && typeof fill === "object") {
+    applyObjectFill(fill, style, set, ledger, context);
+  }
+
+  if (node.cornerRadius !== undefined) {
+    if (Array.isArray(node.cornerRadius)) {
+      // Pen writes one radius, or four in top-right-bottom-left order. This
+      // format has a single `border-radius`, so four equal corners become one
+      // value and anything else becomes the four longhand properties.
+      const corners = node.cornerRadius.map((v) => (Number(v) >= 9999 ? "9999px" : `${Number(v)}px`));
+      if (corners.length === 1 || corners.every((v) => v === corners[0])) {
+        set("border-radius", corners[0]);
+      } else {
+        // This format has one radius for all four corners (docs/format-v3.md,
+        // canonical form). Per-corner radii would be four more properties in
+        // the table and four more controls in the inspector, for one node in a
+        // 1541-node reference file. So the corners collapse to the largest and
+        // the loss is named, rather than the format growing a rare feature.
+        const largest = corners.slice().sort((a, b) => (parseFloat(b) || 0) - (parseFloat(a) || 0))[0];
+        set("border-radius", largest);
+        count(ledger.lost, "perCornerRadius");
+      }
+      count(ledger.converted, "cornerRadiusArray");
+    } else if (node.cornerRadius >= 9999) {
+      // A pill, and `50%` is NOT one: a percentage radius is measured against
+      // the box's own width and height, so on a 421x48 button it draws an
+      // ellipse. Pen says 9999 and means "as round as the box allows", which is
+      // what a very large pixel radius does.
+      set("border-radius", "9999px");
+      count(ledger.converted, "pillRadius");
+    } else {
+      set("border-radius", `${node.cornerRadius}px`);
+    }
+  }
+
+  if (node.type === "ellipse") {
+    // Pen's ellipse is a true ellipse: `rx` and `ry` differ when the box is not
+    // square, and `50%` is the only radius that does the same — it is measured
+    // against the box's own width and height. The declaration goes on the node
+    // and not into a `[data-kind="ellipse"]` rule, because `export` strips the
+    // design attributes and the rule would stop matching in the deliverable.
+    set("border-radius", "50%");
+    count(ledger.converted, "ellipseRadius");
+  }
+
+  // A glyph draws its outline, so a stroke on it is the drawing and not a ring
+  // around the box. `applyStroke` below writes the ring, which is right for a
+  // frame and wrong for a `<svg>`; the glyph's own stroke is written on its
+  // `<path>` instead. See `glyphStroke`.
+  if ((node.stroke !== undefined || node.strokeWidth !== undefined) && !context.glyph) {
+    applyStroke(node, style, set, refs, ledger);
+  }
+
+  if (node.effect !== undefined) applyEffect(node.effect, style, set, ledger);
+
+  if (node.opacity !== undefined && node.opacity < 1) set("opacity", String(node.opacity));
+  if (node.clip === true) set("overflow", "hidden");
+  // A stroked outline is centred on its path, so half of it lies outside the
+  // drawing; a turned one lies outside its own box. Both are still drawn, which
+  // is what pen means by `overflow: visible` on the same element. It goes after
+  // `clip`, because for a glyph the spilling is the design.
+  if (context.glyphOverflow === true) set("overflow", "visible");
+
+  if (context.text) applyTextStyle(node, style, set, refs, ledger);
+
+  return styleOrder(style, ledger);
+}
+
+/**
+ * A colour as this format spells it: six or eight digit lower case hex.
+ * A `var()` reference is left alone, and a value that cannot be read is passed
+ * through and counted, because the validator will report it with a better
+ * message than this reader can.
+ */
+function colourValue(value, ledger) {
+  const text = String(value ?? "");
+  if (text === "" || text.startsWith("var(")) return text;
+  try {
+    return normalizeColor(text);
+  } catch {
+    count(ledger.converted, "unparsedColors");
+    return text;
+  }
+}
+
+/**
+ * The declarations a `ref` states for itself: only size, and only when the
+ * source gave one. Everything else belongs to the node it points at.
+ *
+ * The main axis is `flex`, and `flex-basis` beats the copy's own `width`, so
+ * filling along the axis works from the reference alone. The cross axis is
+ * different: `align-self: stretch` stretches a flex item only while its own
+ * cross size is `auto`, and a master that states a size — every master does —
+ * wins over it. A `fill_container` divider inside the review list therefore
+ * stayed at the master's 320px instead of the list's 311px. A percentage says
+ * what the reference means, and resolves to `auto` when the parent has no
+ * definite size, which is the case where stretching would have done nothing
+ * either.
+ */
+function styleFromRefSize(node, context = {}, ledger) {
+  const style = new Map();
+  const width = node.width === undefined ? undefined : widthValue(node.width, node.textGrowth, context.parentIsRow === true);
+  if (width === FILL_ALONG) { style.set("flex", "1 1 0%"); style.set("min-width", "0"); }
+  else if (width === FILL_ACROSS) style.set("width", "100%");
+  else if (typeof width === "string") style.set("width", width);
+  if (node.height !== undefined) {
+    const height = heightValue(node.height, context.parentIsColumn === true);
+    if (height === FILL_ALONG) { style.set("flex", "1 1 0%"); style.set("min-height", "0"); }
+    else if (height === FILL_ACROSS) style.set("height", "100%");
+    else style.set("height", height);
+  }
+  if (style.size === 0) return "";
+  return orderedStyleText([...style.entries()], ledger);
+}
+
+/**
+ * One declaration list over another, in the table's order.
+ *
+ * The same merge the format's own renderer does for a field-level patch: a
+ * property the later list states replaces the earlier one and every other
+ * declaration survives. Both halves go through the format's normalizer, so the
+ * result is canonical by construction.
+ */
+function mergeStyleText(base, extra, ledger) {
+  if (!extra) return base;
+  const map = new Map();
+  for (const declaration of parseBareDeclarations(base)) map.set(declaration.property, declaration.value);
+  for (const declaration of parseBareDeclarations(extra)) map.set(declaration.property, declaration.value);
+  return orderedStyleText([...map.entries()], ledger);
+}
+
+/** Split a declaration list. Only used to hand text back to the format table. */
+function parseBareDeclarations(value) {
+  const declarations = [];
+  for (const part of String(value ?? "").split(";")) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const colon = trimmed.indexOf(":");
+    if (colon === -1) continue;
+    declarations.push({ property: trimmed.slice(0, colon).trim().toLowerCase(), value: trimmed.slice(colon + 1).trim() });
+  }
+  return declarations;
+}
+
+function hasElementChildren(node) {
+  return Array.isArray(node.children) && node.children.some((child) => child && typeof child === "object" && child.type);
+}
+
+function boxValue(values) {
+  return values.map((v) => (v === 0 ? "0" : `${v}px`)).join(" ");
+}
+
+/**
+ * The four padding sides, in CSS order.
+ *
+ * Pen writes padding as one number, or as a list in top/right/bottom/left order,
+ * which is also CSS order — so a list of three is top, horizontal, bottom, the
+ * same as `padding: a b c` in CSS.
+ */
+function paddingSides(padding) {
+  const values = (Array.isArray(padding) ? padding : [padding])
+    .map((v) => (typeof v === "number" ? v : parseFloat(v)))
+    .filter((v) => Number.isFinite(v));
+  if (values.length === 0) return { top: 0, right: 0, bottom: 0, left: 0 };
+  if (values.length === 1) return { top: values[0], right: values[0], bottom: values[0], left: values[0] };
+  if (values.length === 2) return { top: values[0], right: values[1], bottom: values[0], left: values[1] };
+  if (values.length === 3) return { top: values[0], right: values[1], bottom: values[2], left: values[1] };
+  return { top: values[0], right: values[1], bottom: values[2], left: values[3] };
+}
+
+/** A declared size plus the padding on that axis. A keyword passes through. */
+function paddedSize(value, pad, axis) {
+  if (!pad) return value;
+  const match = /^(-?\d+(?:\.\d+)?)px$/.exec(String(value));
+  if (!match) return value;
+  const extra = axis === "x" ? pad.left + pad.right : pad.top + pad.bottom;
+  if (!extra) return value;
+  return `${Math.round((Number(match[1]) + extra) * 100) / 100}px`;
+}
+
+/**
+ * Sizes that are not a number.
+ *
+ * `fill_container` needs the parent's axis to be spelled, so these return a
+ * marker: filling the main axis and filling the cross axis are two different
+ * declarations. Returning `100%` for both is what a first pass does, and it
+ * collapses — a percentage width inside a parent whose own width is auto
+ * resolves to zero, so a panel beside a fixed portrait shrinks instead of
+ * filling the rest, and its text wraps three times.
+ */
+const FILL_ALONG = Symbol("fill-along");
+const FILL_ACROSS = Symbol("fill-across");
+
+/**
+ * Pen writes sizes as a number, or as one of a few keywords.
+ *
+ * `fill_container` and `fill` both mean "take the parent's width"; `hug` means
+ * "shrink to the content". Pen 2.19 renamed the first pair, and the newer name is
+ * by far the more common one in a real file: 714 uses against a handful.
+ */
+function widthValue(width, textGrowth, parentIsRow) {
+  if (width === "fill_container" || width === "fill") {
+    if (parentIsRow === undefined) return "100%";
+    return parentIsRow ? FILL_ALONG : FILL_ACROSS;
+  }
+  if (width === "hug" || width === "hug_contents" || width === "fit_content") return "fit-content";
+  if (width === "max_content") return "fit-content";
+  if (width === null) return "fit-content";
+  if (typeof width === "string") return width;
+  return `${width}px`;
+}
+
+/** The same keywords apply to a height. */
+function heightValue(height, parentIsColumn) {
+  if (height === "fill_container" || height === "fill") {
+    if (parentIsColumn === undefined) return "100%";
+    return parentIsColumn ? FILL_ALONG : FILL_ACROSS;
+  }
+  if (height === "hug" || height === "hug_contents" || height === "fit_content") return "fit-content";
+  if (height === "max_content") return "fit-content";
+  if (height === null) return "fit-content";
+  if (typeof height === "string") return height;
+  return `${height}px`;
+}
+
+function applyObjectFill(fill, style, set, ledger, context) {
+  const type = fill.type ?? "solid";
+  if (type === "image") {
+    if (context.text || context.glyph) {
+      count(ledger.lost, "imageFillOnText");
+      return;
+    }
+    if (fill.url) {
+      set("background-image", `url("${fill.url}")`);
+      // How the image meets its box. `cover` and `contain` are the CSS keywords
+      // of the same name; pen's `fill` stretches the image, which CSS writes as
+      // `100% 100%`. A mode this format cannot draw stays in the ledger as
+      // unmapped rather than quietly becoming `cover`: an image that is cropped
+      // where the design stretches it is a difference no one would look for.
+      const size = IMAGE_FILL_SIZE[fill.mode ?? "cover"];
+      if (size) set("background-size", size);
+      set("background-position", "center");
+      count(ledger.converted, "imageFills");
+      if (!size) count(ledger.unmapped, `fillMode:${fill.mode}`);
+    } else {
+      count(ledger.lost, "imageFillWithoutUrl");
+    }
+    return;
+  }
+  if (type === "gradient") {
+    if (fill.gradientType && fill.gradientType !== "linear") {
+      count(ledger.lost, `gradient:${fill.gradientType}`);
+      return;
+    }
+    const stops = Array.isArray(fill.colors) ? fill.colors : [];
+    if (stops.length < 2) {
+      count(ledger.lost, "gradientWithFewerThanTwoStops");
+      return;
+    }
+    // Pen's `rotation` runs counter-clockwise and CSS measures clockwise from
+    // "to top", so one is the other subtracted from 360. Two measurements pin
+    // it, and both come from pen's own rendering of the reference file:
+    //
+    //   180  the caption scrim. Pen is dark at the bottom, and 360-180 = 180.
+    //   135  the meetup banner. Pen's darkest corner is the bottom LEFT, which
+    //        is 225deg, and 360-135 = 225.
+    //
+    // An earlier version wrote `rotation + 180` instead. That is right for 180
+    // and 90 degrees wrong for everything else, which is the kind of error a
+    // gradient hides: the band is still a band, it is just on the wrong side.
+    const rotation = Number.isFinite(fill.rotation) ? ((360 - fill.rotation) % 360 + 360) % 360 : 180;
+    const rendered = stops
+      .map((stop) => {
+        let color = String(stop.color ?? "#000000");
+        try {
+          color = normalizeColor(color);
+        } catch {
+          count(ledger.converted, "unparsedGradientStops");
+        }
+        const position = Number.isFinite(stop.position) ? `${Math.round(stop.position * 100)}%` : null;
+        return position === null ? color : `${color} ${position}`;
+      })
+      .join(",");
+    set("background-image", `linear-gradient(${rotation}deg,${rendered})`);
+    count(ledger.converted, "linearGradients");
+    return;
+  }
+  if (Array.isArray(fill.enabled) || fill.enabled === false) {
+    count(ledger.lost, "disabledFill");
+    return;
+  }
+  count(ledger.unmapped, `fillType:${type}`);
+}
+
+function applyStroke(node, style, set, refs, ledger) {
+  // 2.19 writes `stroke: {fill, thickness, align}`; 2.6 writes `stroke` plus
+  // `strokeWidth`. Both are read, so one reader covers both files.
+  let color = node.stroke;
+  let width = node.strokeWidth ?? 1;
+  if (node.stroke && typeof node.stroke === "object" && !Array.isArray(node.stroke)) {
+    // A stroke with no paint is not drawn. `border` needs a colour and there is none, so
+    // writing one means inventing it — and the value this used to invent was black.
+    //
+    // Two measurements in the reference artboards say the paint-less stroke is structure,
+    // not design. Every painted one follows its page: the same battery border is #000000 on
+    // the light pages and #ffffff on the dark ones, and the nine notification buttons carry
+    // nine different colours and thicknesses, four of them carrying none at all. Every
+    // paint-less one is the identical `{align:"inside",thickness:1}` on all nine styles,
+    // which no designer writes and no theme can colour. And the invented line hides where
+    // nobody looked: black on #141417 is invisible, black on white is a box.
+    const paint = node.stroke.fill ?? node.stroke.color;
+    if (paint === undefined || paint === null) {
+      count(ledger.lost, "strokeWithoutPaint");
+      return;
+    }
+    color = paint;
+    width = node.stroke.thickness ?? width;
+    if (node.stroke.align && node.stroke.align !== "inside") {
+      count(ledger.lost, `strokeAlign:${node.stroke.align}`);
+    }
+  }
+  const cssColor = colourValue(resolveReference(color, refs, ledger), ledger);
+  if (width && typeof width === "object") {
+    const sides = [width.top ?? 0, width.right ?? 0, width.bottom ?? 0, width.left ?? 0];
+    set("border-width", sides.map((v) => (v === 0 ? "0" : `${v}px`)).join(" "));
+    set("border-style", "solid");
+    set("border-color", cssColor);
+    count(ledger.converted, "perSideStroke");
+    return;
+  }
+  const cssWidth = typeof width === "number" ? width : 1;
+  if (cssWidth === 0) return;
+  set("border", `${cssWidth}px solid ${cssColor}`);
+}
+
+function applyEffect(effect, style, set, ledger) {
+  const effects = Array.isArray(effect) ? effect : [effect];
+  const shadows = [];
+  for (const entry of effects) {
+    if (!entry || typeof entry !== "object") continue;
+    if (entry.type === "innerShadow" || entry.shadowType === "inner") {
+      count(ledger.lost, "innerShadow");
+      continue;
+    }
+    if (entry.type !== "shadow") {
+      count(ledger.unmapped, `effect:${entry.type}`);
+      continue;
+    }
+    const x = entry.offset?.x ?? 0;
+    const y = entry.offset?.y ?? 0;
+    const blur = entry.blur ?? 0;
+    let color = String(entry.color ?? "#00000040");
+    try {
+      color = normalizeColor(color);
+    } catch {
+      count(ledger.converted, "unparsedShadowColors");
+    }
+    shadows.push(`${x}px ${y}px ${blur}px ${color}`);
+  }
+  if (shadows.length) set("box-shadow", shadows.join(", "));
+}
+
+function applyTextStyle(node, style, set, refs, ledger) {
+  if (node.fontFamily) {
+    const value = resolveReference(node.fontFamily, refs, ledger);
+    if (value.startsWith("var(")) {
+      set("font-family", value);
+    } else {
+      // Pen's own export appends `system-ui, sans-serif` to every family it
+      // writes, and it is not decoration. A list that ends in a webfont ends in
+      // something the machine may not have, so the fallback becomes the DOCUMENT
+      // default — a serif face on most engines, and a different layout with it.
+      // Offline, behind a proxy, or on a build machine, the design would stop
+      // looking like the design.
+      set("font-family", ensureGenericFamily(String(node.fontFamily)));
+    }
+  }
+  if (node.fontSize !== undefined) set("font-size", `${node.fontSize}px`);
+  if (node.fontWeight !== undefined) set("font-weight", String(node.fontWeight));
+  if (node.lineHeight !== undefined) set("line-height", String(node.lineHeight));
+  if (node.letterSpacing !== undefined) {
+    set("letter-spacing", `${node.letterSpacing}px`);
+  }
+  if (node.textAlign) set("text-align", node.textAlign);
+  if (node.textTransform) set("text-transform", node.textTransform);
+  // A newline in pen's text is a line break the author placed, and pen's own
+  // export writes it as `<br>` inside ordinary whitespace. Written as a literal
+  // newline it is a space: HTML folds it away, the line wraps wherever it happens
+  // to fit, and the design reads differently on every machine with a different
+  // font. `pre-line` is the spelling of what pen renders — the breaks are kept
+  // and runs of spaces still fold. `pre-wrap` keeps the spaces as well, and a
+  // space at the end of a line then counts towards the line's centre: 11px of
+  // shift on the welcome document, measured against pen's export of the same file.
+  if (hasHardBreak(node.content)) {
+    set("white-space", "pre-line");
+    count(ledger.converted, "hardBreaks");
+  } else if (node.fixedWidth === true) set("white-space", "normal");
+}
+
+/** Whether a text node's content carries a line break of its own. */
+function hasHardBreak(content) {
+  return typeof content === "string" && /[\n\r]/.test(content);
+}
+
+/** Emit order, without importing the table: this reader must stay dependency-light. */
+const STYLE_ORDER = [
+  "display", "flex-direction", "flex-wrap", "align-items", "justify-content", "gap", "padding",
+  "position", "left", "top", "width", "height", "flex", "background-color", "border",
+  "border-width", "border-style", "border-color", "border-radius", "box-shadow", "opacity",
+  "overflow", "font-family", "font-size", "font-weight", "line-height", "letter-spacing",
+  "color", "text-align", "text-transform", "white-space", "background-image", "background-size",
+  "background-position",
+];
+
+/**
+ * Order the declarations and hand each value to the format's own normalizer.
+ *
+ * The second half matters more than it looks. Pen writes `font-weight: "normal"`
+ * and shadow offsets as `0px`; the canonical form wants `400` and `0`. Re-deriving
+ * those rules here would give two normalizers that drift apart, so the reader
+ * borrows the one the validator and the canvas already use.
+ */
+function styleOrder(map, ledger) {
+  return orderedStyleText([...map.entries()], ledger);
+}
+
+/**
+ * Order declarations the way the format table does, and put each value through
+ * the format's own normalizer.
+ *
+ * Both halves matter. Pen writes `font-weight: "normal"` and shadow offsets as
+ * `0px`; the canonical form wants `400` and `0`. And the emit ORDER is fixed by
+ * the table — `min-width` before `flex`, `position` before `width` — so a reader
+ * with its own idea of the order writes a file whose very first `format --check`
+ * reports a diff the author never made.
+ *
+ * Re-deriving either here would give two implementations, and two
+ * implementations drift.
+ */
+function orderedStyleText(pairs, ledger) {
+  const kept = [];
+  for (const [property, value] of pairs) {
+    if (value === undefined || value === null || value === "") continue;
+    kept.push([property, normaliseValueFor(property, value, ledger)]);
+  }
+  const text = kept.map(([property, value]) => `${property}:${value}`).join(";");
+  return normalizeStyleText(text, parseBareDeclarations).text;
+}
+
+/**
+ * One value, through the format's own normalizer.
+ *
+ * The validator has the better message for a value it cannot read, so an
+ * unreadable value is passed through and recorded rather than re-diagnosed.
+ */
+function normaliseValueFor(property, value, ledger) {
+  if (!ledger || property.startsWith("--")) return value;
+  try {
+    const normalized = normalizeValue(property, value);
+    if (normalized.changed) count(ledger.converted, "normalizedValues");
+    return normalized.value;
+  } catch (error) {
+    ledger.notes.push(`${property}:${value} — ${error.message}`);
+    return value;
+  }
+}
+
+// -- nodes --------------------------------------------------------------------
+
+/**
+ * Pen node types, as this format's types.
+ *
+ * `icon_font` and `path` are both an icon by another spelling. Pen 2.6 writes a glyph as
+ * `iconFontName` + `iconFontFamily` where 2.19 writes `icon` + `library`, and a `path`
+ * node carries the outline itself instead of a name. All three draw the same thing, so
+ * they all become `icon`; what differs is where the geometry comes from, and that is
+ * `glyphBody`'s business.
+ */
+const TYPE_MAP = {
+  frame: "frame", text: "text", icon: "icon", icon_font: "icon", path: "icon",
+  rectangle: "shape", ellipse: "shape",
+};
+
+/**
+ * The type this node becomes, or null when the node has no spelling here.
+ *
+ * `reusable` changes nothing: pen's master is a frame that other nodes reference,
+ * and the reference is what carries the meaning. Nothing in this format is named
+ * by another element, so a master and a plain frame are the same element.
+ */
+function dataTypeFor(node) {
+  return TYPE_MAP[node.type] ?? null;
+}
+
+/**
+ * A glyph's name, in whichever of the three spellings the node uses.
+ *
+ * A `path` node has no name of its own — its outline is the glyph — so the layer name
+ * becomes one. The table wants letters, digits and hyphens, and `data-icon` is a label
+ * here: the drawing is the geometry, and the validator does not look the name up.
+ */
+function iconNameFor(node) {
+  const named = node.icon ?? node.iconFontName;
+  if (named !== undefined && named !== null && String(named) !== "") return String(named);
+  const slug = String(node.name ?? "").trim().toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug === "" ? "circle" : slug;
+}
+
+/**
+ * The stroke a glyph draws itself with, or null when it is filled instead.
+ *
+ * Two spellings, and both are read: 2.6 writes `stroke` as a colour beside
+ * `strokeWidth`, 2.19 writes `stroke: {fill, thickness, align}`. A width with no
+ * paint is not a stroke — `applyStroke` says why at length, and the reason does
+ * not change because the node is a glyph.
+ *
+ * Pure: it resolves nothing and counts nothing, because the style and the markup
+ * both ask it the same question and a helper that counted would count twice. The
+ * paint goes through the same `colourValue`/`resolveReference` path as a fill.
+ */
+function glyphStroke(node) {
+  const stroke = node.stroke;
+  let paint = null;
+  let width = null;
+  if (typeof stroke === "string") {
+    paint = stroke;
+    width = node.strokeWidth ?? null;
+  } else if (stroke && typeof stroke === "object" && !Array.isArray(stroke)) {
+    paint = stroke.fill ?? stroke.color ?? null;
+    width = stroke.thickness ?? node.strokeWidth ?? null;
+  }
+  if (stroke === undefined && node.strokeWidth !== undefined) return null;
+  if (paint === null || paint === undefined || paint === "") return null;
+
+  const linecap = CAPS.has(node.strokeLinecap) ? node.strokeLinecap : null;
+  const linejoin = JOINS.has(node.strokeLinejoin) ? node.strokeLinejoin : null;
+  if (width !== null && typeof width === "object") {
+    // A per-side width on an outline has no meaning — which side of a curve? —
+    // and pen writes the four-value spelling for boxes. It collapses to the
+    // largest, the way `cornerRadius` collapses to its largest corner, and the
+    // ledger names it instead of the outline disappearing.
+    const sides = [width.top, width.right, width.bottom, width.left].map(Number).filter(Number.isFinite);
+    const largest = sides.length ? Math.max(...sides) : null;
+    return { paint, width: largest, perSide: true, linecap, linejoin };
+  }
+  const number = Number(width);
+  return { paint, width: Number.isFinite(number) && number > 0 ? number : null, perSide: false, linecap, linejoin };
+}
+
+const CAPS = new Set(["butt", "round", "square"]);
+const JOINS = new Set(["miter", "round", "bevel"]);
+
+/** A node's own rotation, in pen's degrees, or null when it has none worth writing. */
+function rotationOf(node) {
+  const rotation = Number(node.rotation);
+  if (!Number.isFinite(rotation) || rotation % 360 === 0) return null;
+  return rotation;
+}
+
+/**
+ * Everything a glyph's element needs, decided once.
+ *
+ * The grid first. A named glyph comes from the built-in set and is drawn on that
+ * set's grid. A `path` node carries its own outline, and the box that outline is
+ * drawn in is the OUTLINE'S OWN box — not the node's. The two are the same for
+ * every glyph a design tool draws at the size it was drawn, which is why the
+ * node's box looked right for so long; they stop being the same the moment a
+ * path is scaled, and a 14×14 arrow in a 366×366 node then drew 14 pixels wide
+ * in the corner of its own box. pen's own export of that node says
+ * `viewBox="0 0 14 14"` on a 366×366 element: the outline's box is the grid, and
+ * the element scales it. So the outline is measured, and its box is the viewBox.
+ *
+ * A node whose outline cannot be measured keeps the node's box, which is what
+ * this reader did for every path before, and which is right for an outline that
+ * does not parse or has no area to speak of.
+ *
+ * Then the turn. This format has a `transform`, but it is one `rotate()` about
+ * the element's centre, and there is no `transform-origin`; pen turns an element
+ * about its top-left corner. The two pivots differ, so a rotated outline is
+ * rewritten instead of wrapped: the coordinates are turned about the box's own
+ * origin, which is where pen turns it, and pen measures rotation
+ * counter-clockwise where CSS measures it clockwise. The geometry is no longer
+ * the bytes pen wrote, so the ledger says so.
+ *
+ * @param {object} node
+ * @param {object} ledger
+ * @returns {{viewBox: string, geometry: string|null, stroke: object|null, overflow: boolean, turned: boolean}}
+ */
+function glyphPlan(node, ledger) {
+  const plan = { viewBox: ICON_VIEW_BOX, geometry: null, stroke: glyphStroke(node), overflow: false, turned: false };
+  const isPath = node.type === "path" && typeof node.geometry === "string" && node.geometry !== "";
+
+  if (!isPath) {
+    // A named glyph with a stroke of its own: the width is not reproduced,
+    // because the built-in set's drawing is stroked by the file's own base rule
+    // and this reader will not invent a second stroke weight for it.
+    if (plan.stroke) {
+      count(ledger.lost, "iconStroke");
+      if (ledger.lost.iconStroke === 1) {
+        ledger.notes.push(`a named glyph carries stroke width ${plan.stroke.width ?? "?"}; this format draws the built-in set at its own weight, so the width was not reproduced`);
+      }
+      plan.stroke = null;
+    }
+    return plan;
+  }
+
+  count(ledger.converted, "pathAsGeometry");
+  const bounds = pathBounds(node.geometry);
+  plan.geometry = node.geometry;
+  plan.viewBox = bounds ? boxText(bounds) : nodeBoxText(node);
+
+  if (plan.stroke) {
+    if (plan.stroke.perSide) {
+      count(ledger.lost, "pathStrokeWidthPerSide");
+      ledger.notes.push(`node ${node.id ?? "?"} strokes its outline with one width per side; an outline has no sides, so the largest was used and the ledger names the loss`);
+    }
+    if (node.fill !== undefined && node.fill !== null) {
+      // pen would draw the fill and the stroke; this format gives the element one
+      // `color`, and the stroke is the one that is drawn. Named, not silent.
+      count(ledger.lost, "glyphFill");
+      ledger.notes.push(`node ${node.id ?? "?"} carries both a fill and a stroke; this format draws one paint per glyph, and the stroke is the one written`);
+    }
+  }
+
+  const rotation = rotationOf(node);
+  if (rotation !== null && bounds) {
+    try {
+      plan.geometry = rotatePath(node.geometry, -rotation, bounds.minX, bounds.minY);
+      plan.turned = true;
+      count(ledger.converted, "bakedRotation");
+      if (ledger.converted.bakedRotation === 1) {
+        ledger.notes.push(`node ${node.id ?? "?"} is rotated ${rotation} degrees; pen turns it about its top-left corner and this format can only turn about the centre, so the outline itself was turned by ${-rotation} and the ledger counts it as bakedRotation`);
+      }
+    } catch {
+      plan.turned = false;
+    }
+  }
+
+  // Half of a centred stroke lies outside the outline, and a turned outline lies
+  // outside the box it was measured in. Both are drawn anyway, as pen draws them.
+  plan.overflow = Boolean(plan.stroke) || plan.turned;
+
+  // pen stretches an outline into the node's box (`preserveAspectRatio="none"`);
+  // this format's `<svg>` keeps the aspect ratio and centres what is left over.
+  // The difference is a fraction of a pixel on the glyphs that have one, and it
+  // is counted rather than hidden.
+  if (bounds) {
+    const inkAspect = (bounds.maxX - bounds.minX) / (bounds.maxY - bounds.minY);
+    const boxAspect = Number(node.width) / Number(node.height);
+    if (Number.isFinite(boxAspect) && boxAspect > 0 && Math.abs(inkAspect / boxAspect - 1) > 0.01) {
+      count(ledger.converted, "letterboxedGlyph");
+    }
+  }
+  return plan;
+}
+
+/** The viewBox text for a measured outline. */
+function boxText(bounds) {
+  return `${round3(bounds.minX)} ${round3(bounds.minY)} ${round3(bounds.maxX - bounds.minX)} ${round3(bounds.maxY - bounds.minY)}`;
+}
+
+/** The viewBox text for a node whose outline could not be measured. */
+function nodeBoxText(node) {
+  const width = Number(node.width);
+  const height = Number(node.height);
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return ICON_VIEW_BOX;
+  return `0 0 ${round3(width)} ${round3(height)}`;
+}
+
+function tagFor(node, dataType) {
+  if (dataType === "text") return "p";
+  if (dataType === "icon") return "svg";
+  if (dataType === "image") return "img";
+  return "div";
+}
+
+/**
+ * What a child has to know about its parent.
+ *
+ * Two axes and one absence. `fill_container` means "share the main axis" in a row and
+ * "stretch across" in a column — two different declarations — and a child of a
+ * `layout:none` frame is placed by its own x and y rather than by the flow.
+ *
+ * This exists because the artboard loop built the same object by hand and left the flags
+ * out, so every direct child of a page was read as if its parent's axis were unknown and
+ * `fill_container` fell back to `width:100%`. On a row page that is wrong by exactly the
+ * width of the sibling before it: the Swiss Clean dashboard's content took the full
+ * 1440px beside its 240px sidebar, and the page's own `overflow:hidden` cut those 240px
+ * off the right edge — the Export button and half the last metric card. It hid for as long
+ * as it did because the reference file's 25 pages all have `layout: vertical`, where
+ * `100%` and `stretch` happen to agree.
+ */
+function childContext(node, context) {
+  const { forcedStyle, forcedAttrs, ...rest } = context;
+  return {
+    ...rest,
+    parentIsRow: node.layout !== "vertical",
+    parentIsColumn: node.layout === "vertical",
+    parentLayoutNone: node.layout === "none",
+  };
+}
+
+/**
+ * Render one pen node as HTML.
+ *
+ * The reader writes HTML text and then parses it with the real parser, so an
+ * imported file goes through exactly the same model, serializer and validator
+ * as a hand-written one. Building a tree directly would create a second
+ * representation that could drift from the parser's.
+ */
+function renderNode(node, refs, ledger, context = {}) {
+  if (node.type === "ref") return renderRef(node, refs, ledger, context);
+  if (context.countSource !== false) ledger.sourceNodes += 1;
+  const dataType = dataTypeFor(node);
+  if (!dataType) {
+    count(ledger.lost, `nodeType:${node.type}`);
+    return "";
+  }
+  ledger.nodes += 1;
+
+  const id = context.ids.get(node) ?? node.id ?? `n-${ledger.nodes}`;
+  const attrs = [`data-id="${escapeAttr(id)}"`, `data-type="${dataType}"`];
+  if (node.name) attrs.push(`data-name="${escapeAttr(node.name)}"`);
+
+  if (dataType === "shape") {
+    // A reusable ellipse is an ellipse like any other: `data-kind` is the name of
+    // the shape and the node's own `border-radius:50%` is the shape itself, so a
+    // copy of it scales with its box exactly as pen's ellipse does.
+    attrs.push(`data-kind="${node.type === "ellipse" ? "ellipse" : "rect"}"`);
+  }
+  // The glyph's own answers — its grid, its outline, its stroke — are decided
+  // before the style, because the style has to know whether the drawing spills
+  // outside its box. See `glyphPlan`.
+  const glyph = dataType === "icon" ? glyphPlan(node, ledger) : null;
+
+  // A rotation this format cannot express: everything except a glyph whose
+  // outline could be turned. Named once, counted once, and the count is what the
+  // printed ledger line shows.
+  const rotation = rotationOf(node);
+  if (rotation !== null && !glyph?.turned) {
+    if (!ledger.lost.rotation) {
+      ledger.notes.push(`node ${id} is rotated ${rotation} degrees; pen turns it about its top-left corner, which this format cannot express, so it is drawn upright and the ledger names the loss`);
+    }
+    count(ledger.lost, "rotation");
+  }
+
+  if (dataType === "icon") {
+    attrs.push(`data-icon="${escapeAttr(iconNameFor(node))}"`);
+    attrs.push(`data-icon-library="${escapeAttr(node.library ?? node.iconFontFamily ?? "lucide")}"`);
+    // Without this the glyph is not scaled, it is clipped. See `glyphPlan`.
+    attrs.push(`viewBox="${glyph.viewBox}"`);
+  }
+  // A patch that only says "not hidden" writes nothing: the attribute is how a
+  // node is hidden, and its absence is the same statement in fewer bytes.
+  if (node.__dataHidden === "true") attrs.push('data-hidden="true"');
+  for (const [name, value] of context.forcedAttrs ?? []) {
+    attrs.push(`${name}="${escapeAttr(value)}"`);
+  }
+  // What this node's own style has to know about itself — not what its children need,
+  // which is `childContext()` below. The two were one name once, and the local one
+  // shadowed the function.
+  const styleContext = {
+    ...context,
+    glyph: dataType === "icon",
+    text: dataType === "text",
+    glyphOverflow: glyph?.overflow === true,
+  };
+  let style = styleFromNode(node, refs, ledger, styleContext);
+  // Field-level patches a reference carried (`fontSize`, `width`, …) merge over the
+  // copy's own declarations here, in the same order and through the same normalizer
+  // as every other declaration the reader writes.
+  if (Array.isArray(node.__extraStyle) && node.__extraStyle.length > 0) {
+    style = mergeStyleText(style, node.__extraStyle.map(([property, value]) => `${property}:${value}`).join(";"), ledger);
+  }
+  if (context.forcedStyle) style = mergeStyleText(style, context.forcedStyle, ledger);
+  if (style) attrs.push(`style="${escapeAttr(style)}"`);
+
+  const tag = tagFor(node, dataType);
+  if (dataType === "image" || dataType === "icon") {
+    const inner = dataType === "icon" ? glyphBody(node, ledger, glyph) : "";
+    return `<${tag} ${attrs.join(" ")}>${inner}</${tag}>`;
+  }
+  if (!Array.isArray(node.children) || node.children.length === 0) {
+    if (dataType === "text") {
+      return `<${tag} ${attrs.join(" ")}>${escapeText(node.content ?? node.name ?? "")}</${tag}>`;
+    }
+    return `<${tag} ${attrs.join(" ")}></${tag}>`;
+  }
+
+  // A child has to know its parent's axis: `fill_container` means "share the
+  // main axis" in a row and "stretch across" in a column, and those are two
+  // different declarations.
+  const children = node.children
+    .map((child) => renderNode(child, refs, ledger, childContext(node, context)))
+    .join("\n");
+  if (dataType === "text") {
+    return `<${tag} ${attrs.join(" ")}>${escapeText(node.content ?? "")}</${tag}>`;
+  }
+  return `<${tag} ${attrs.join(" ")}>\n${children}\n</${tag}>`;
+}
+
+/**
+ * A glyph, as inline geometry.
+ *
+ * Pen stores a glyph by name. This format stores geometry, so the name is
+ * resolved against the built-in set and the glyph's own paths are written in.
+ * Nothing is fetched: the set is in the repository, so an import works offline
+ * and produces the same bytes on every machine.
+ *
+ * A name the set does not carry becomes a visible placeholder AND is counted in
+ * the ledger. A wrong glyph would be worse than an obviously wrong one, and a
+ * silent one would be worse than both.
+ *
+ * @param {object} node
+ * @param {object} ledger
+ * @param {object} plan what `glyphPlan` decided for this node
+ */
+function glyphBody(node, ledger, plan) {
+  // Pen 2.6 writes a glyph as `iconFontName` where 2.19 writes `icon`. Same drawing, older
+  // spelling, and worth a ledger line: the reference file carries 233 of them, and before
+  // this they were all counted as an unknown node type.
+  if (node.type === "icon_font") count(ledger.converted, "iconFont");
+  // A `path` node IS geometry: there is no name to look up, and the outline is the glyph.
+  if (plan && plan.geometry !== null) {
+    const turns = node.fillRule === "evenodd" ? ' fill-rule="evenodd"' : "";
+    if (plan.stroke) {
+      // The stroke is the drawing, so nothing is filled and the width is the one
+      // pen wrote. `vector-effect` keeps that width when the outline is scaled
+      // into the node's box, which is what makes a 50 in a 14-unit outline
+      // fifty pixels wide — pen's own export writes the same three attributes on
+      // the same element, for the same reason.
+      const parts = [
+        `d="${escapeAttr(plan.geometry)}"`,
+        'fill="none"',
+        'stroke="currentColor"',
+        `stroke-width="${plan.stroke.width ?? 1}"`,
+        plan.stroke.linecap ? `stroke-linecap="${plan.stroke.linecap}"` : "",
+        plan.stroke.linejoin ? `stroke-linejoin="${plan.stroke.linejoin}"` : "",
+        'vector-effect="non-scaling-stroke"',
+      ].filter(Boolean);
+      return `<path ${parts.join(" ")}${turns}></path>`;
+    }
+    // `fill="currentColor"` opts this path out of the base rule that strokes every child
+    // of an `<svg>` carrying neither `data-fill` nor its own `fill`. Pen's `path` with a
+    // fill is a filled outline, and a filled outline drawn as a stroke is a different
+    // shape.
+    return `<path d="${escapeAttr(plan.geometry)}" fill="currentColor"${turns}></path>`;
+  }
+  return glyphFor(node.icon ?? node.iconFontName, ledger);
+}
+
+/**
+ * The same lookup, by name. A reference can swap the glyph one copy draws, and
+ * that patch is geometry too, so it goes through here.
+ */
+function glyphFor(value, ledger) {
+  const name = String(value ?? "");
+  if (name && hasIcon(name)) return iconBody(name);
+  count(ledger.lost, name ? "glyphNotInSet" : "iconWithoutName");
+  if (name) ledger.notes.push(`glyph ${JSON.stringify(name)} is not in the built-in set (${ICONS_COUNT} glyphs): a placeholder was written`);
+  return `<rect x="3" y="3" width="18" height="18" rx="3" fill="none" stroke="currentColor"></rect>`;
+}
+
+/**
+ * How deep a chain of references may nest before the reader calls it a loop.
+ *
+ * Pen allows a reference inside a master, which is how one reusable frame is
+ * built out of another. A chain that comes back to a reference it already
+ * inlined would never terminate, and a chain 16 deep is not a design any more.
+ */
+const REF_DEPTH_LIMIT = 16;
+
+/**
+ * A `ref` node, inlined.
+ *
+ * Pen stores a reference and, separately, the node it names. This format stores
+ * no reference: the subtree is copied in, so the file is what it draws. The copy's
+ * root keeps the reference node's own id — that is the element the reference
+ * stood for — and the copy's descendants are renumbered under it, because an id
+ * is unique across the whole file and one master may be referenced many times.
+ *
+ * A `ref` that names nothing is refused rather than written as an empty box: the
+ * import would produce a file whose content is missing, and a checker would have
+ * to guess that an empty frame was meant to be a card.
+ */
+function renderRef(node, refs, ledger, context) {
+  const chain = context.chain ?? [];
+  const target = context.byIdNode?.get(node.ref);
+  if (!target) {
+    throw penError("pen/unresolved-ref",
+      `The reference ${JSON.stringify(node.ref)} points at no node in this file, so there is no subtree to inline.`);
+  }
+  if (chain.includes(node.ref)) {
+    throw penError("pen/ref-cycle",
+      `These references form a loop: ${[...chain, node.ref].join(" -> ")}.`);
+  }
+  if (chain.length >= REF_DEPTH_LIMIT) {
+    throw penError("pen/ref-depth",
+      `References nest more than ${REF_DEPTH_LIMIT} deep at ${JSON.stringify(node.ref)}.`);
+  }
+
+  const rootId = context.ids.get(node) ?? node.id ?? `n-${ledger.nodes + 1}`;
+  // A reference that carries children of its own is a shape pen's model does not
+  // merge into the master. Dropping them quietly would be content the file never
+  // shows, so the ledger names it.
+  if ((node.children ?? []).some((child) => child && typeof child === "object")) {
+    count(ledger.lost, "refChildren");
+    ledger.notes.push(`the reference ${JSON.stringify(rootId)} carries children of its own; pen's reference is the master's subtree, so they were not written`);
+  }
+  const copy = structuredClone(target);
+  applyRefOverrides(copy, node.descendants, refs, ledger);
+  renameCopy(target, copy, rootId, context.usedIds);
+  count(ledger.refs, "inlined");
+
+  return renderNode(copy, refs, ledger, {
+    ...context,
+    // The bytes under a copy are the master's, counted once where the master is.
+    countSource: false,
+    chain: [...chain, node.ref],
+    // A reference may state its own size. It was merged over the master's own
+    // declarations at mount time once; here it is one more declaration list.
+    forcedStyle: styleFromRefSize(node, context, ledger),
+  });
+}
+
+/**
+ * Renumber a copy so its ids stay unique, in place.
+ *
+ * The root keeps the reference's own id and every descendant becomes
+ * `<root>__<its own id>`, which is the same shape a hand-written id takes
+ * (`home__title`) and the only shape that keeps a nested copy readable. Past 64
+ * characters — the format's limit — the id falls back to the root plus a hash of
+ * the original, and a collision takes a `-2` suffix. All of it is deterministic:
+ * the same `.pen` produces the same bytes.
+ */
+function renameCopy(original, copy, rootId, usedIds) {
+  const seen = usedIds ?? new Set();
+  seen.add(rootId);
+  const visit = (source, dupe, isRoot) => {
+    if (isRoot) dupe.id = rootId;
+    else {
+      const base = source.id;
+      if (typeof base === "string" && base !== "") dupe.id = uniqueCopyId(rootId, base, seen);
+      else delete dupe.id;
+    }
+    const sourceChildren = (source.children ?? []).filter((child) => child && typeof child === "object");
+    const copyChildren = (dupe.children ?? []).filter((child) => child && typeof child === "object");
+    for (let i = 0; i < sourceChildren.length && i < copyChildren.length; i += 1) {
+      visit(sourceChildren[i], copyChildren[i], false);
+    }
+  };
+  visit(original, copy, true);
+}
+
+function uniqueCopyId(rootId, base, used) {
+  let candidate = `${rootId}__${base}`;
+  if (candidate.length > 64) candidate = `${rootId.slice(0, 40)}__${Math.abs(hash(base)).toString(36)}`;
+  let id = candidate;
+  for (let n = 2; used.has(id); n += 1) id = `${candidate}-${n}`;
+  used.add(id);
+  return id;
+}
+
+/**
+ * The field-level patches a `ref` carries, applied to the copy's own nodes.
+ *
+ * Pen's `descendants` names nodes of the master. The copy is a pen tree too, so a
+ * patch is a pen property — that is the whole reason this happens before rendering
+ * rather than to the bytes afterwards: `icon` becomes the master's glyph resolved
+ * from the built-in set, `fill` goes through the same colour path as any fill, and
+ * a CSS field is a declaration the renderer already knows how to order.
+ *
+ * A field with no spelling here is counted in `unmapped`, never dropped quietly.
+ */
+function applyRefOverrides(copy, descendants, refs, ledger) {
+  if (!descendants || typeof descendants !== "object") return;
+  const index = new Map();
+  walkPen(copy, (node) => {
+    if (typeof node.id === "string" && !index.has(node.id)) index.set(node.id, node);
+  });
+
+  let applied = 0;
+  for (const [targetId, fields] of Object.entries(descendants)) {
+    const target = index.get(targetId);
+    if (!target) {
+      count(ledger.unmapped, `overrideTarget:${targetId}`);
+      ledger.notes.push(`the reference patches ${JSON.stringify(targetId)}, which is not an id inside the node it points at`);
+      continue;
+    }
+    let touched = false;
+    const declarations = [];
+    for (const [key, value] of Object.entries(fields ?? {})) {
+      if (key === "content") { target.content = String(value); touched = true; continue; }
+      if (key === "fill") { target.fill = resolveReference(value, refs, ledger); touched = true; continue; }
+      // `icon` swaps one copy's glyph. The name is the node's own spelling, and
+      // the geometry follows from it: a glyph here is bytes, so writing the name
+      // without redrawing is a label that disagrees with its own drawing.
+      if (key === "icon") {
+        target.icon = String(value);
+        count(ledger.converted, "iconOverrides");
+        touched = true;
+        continue;
+      }
+      if (key === "enabled" || key === "visible") {
+        if (value) delete target.__dataHidden;
+        else target.__dataHidden = "true";
+        touched = true;
+        continue;
+      }
+      const css = OVERRIDE_CSS[key];
+      if (css) {
+        const rendered = cssValueFor(css, value, { refs }, ledger);
+        if (rendered) { declarations.push([css, rendered]); touched = true; }
+        continue;
+      }
+      ledger.refs.overrideFieldsDropped += 1;
+      count(ledger.unmapped, `override:${key}`);
+    }
+    if (declarations.length) target.__extraStyle = declarations;
+    if (touched) applied += 1;
+  }
+  if (applied > 0) ledger.refs.overridesApplied += 1;
+}
+
+const OVERRIDE_CSS = {
+  fontSize: "font-size",
+  fontWeight: "font-weight",
+  lineHeight: "line-height",
+  letterSpacing: "letter-spacing",
+  textAlign: "text-align",
+  width: "width",
+  height: "height",
+  cornerRadius: "border-radius",
+  clip: "overflow",
+  opacity: "opacity",
+};
+
+function cssValueFor(property, value, context, ledger) {
+  if (property === "overflow") return value ? "hidden" : "visible";
+  if (property === "border-radius") return value >= 9999 ? "9999px" : `${value}px`;
+  if (["width", "height", "font-size", "letter-spacing", "cornerRadius"].includes(property)) return `${value}px`;
+  if (property === "opacity") return String(value);
+  return resolveReference(String(value), context.refs, ledger);
+}
+
+// -- the import ---------------------------------------------------------------
+
+/**
+ * @param {string} text the `.pen` file
+ * @param {object} options `{ title, fallbackTitle }`
+ *   `title` wins, then the document's own `name`, then `fallbackTitle`. The last one exists
+ *   because this function is handed text and cannot know what the file is called; the verb
+ *   that read it supplies the name. Before it, a `.pen` with no `name` was titled
+ *   "imported", which is a title that says only that something happened.
+ * @returns {{ html: string, ledger: object, diagnostics: Array }}
+ */
+export function importPen(text, options = {}) {
+  const ledger = createLedger();
+  temporaryLedger = ledger;
+  const json = parsePen(text);
+  ledger.version = json.version ?? null;
+  if (ledger.version && !PEN_VERSION_SUPPORTED.includes(ledger.version)) {
+    ledger.notes.push(`version ${ledger.version} is newer than this reader was written against (${PEN_VERSION_SUPPORTED.join(", ")})`);
+  }
+
+  const { tokens, refs } = tokensFromVariables(json.variables, ledger);
+  const { byNode: ids, byIdNode } = idLookup(json);
+  const renamed = [...ids.entries()].filter(([node, to]) => node.id !== to).length;
+  if (renamed > 0) count(ledger.converted, "renumberedIds", renamed);
+
+  // Every id the file has already spent. An inlined copy renumbers under its
+  // reference's id, and it has to stay out of this set: an id is unique across the
+  // whole document.
+  const usedIds = new Set(ids.values());
+  const context = { ids, byIdNode, refs, tokens, usedIds, chain: [] };
+  const pages = [];
+  for (const artboard of json.children) {
+    if (artboard.type !== "frame") {
+      count(ledger.lost, `topLevelType:${artboard.type}`);
+      continue;
+    }
+    // A reusable artboard is a frame other nodes reference. It is still an
+    // artboard, so it is still a page: nothing here is scaffolding.
+    const id = ids.get(artboard) ?? artboard.id ?? `page-${pages.length}`;
+    const attrs = [`data-id="${escapeAttr(id)}"`, `data-type="page"`];
+    if (artboard.name) attrs.push(`data-name="${escapeAttr(artboard.name)}"`);
+    if (Number.isFinite(artboard.x) || Number.isFinite(artboard.y)) {
+      attrs.push(`data-canvas="${Math.round(artboard.x ?? 0)},${Math.round(artboard.y ?? 0)}"`);
+    }
+    attrs.push(`style="${escapeAttr(pageStyle(artboard, refs, ledger))}"`);
+
+    const children = (artboard.children ?? [])
+      .map((child) => renderNode(child, refs, ledger, childContext(artboard, context)))
+      .join("\n");
+    pages.push(`  <section ${attrs.join(" ")}>\n${children}\n  </section>`);
+  }
+
+  ledger.pages = pages.length;
+
+  if (pages.length === 0) {
+    const failure = new Error("The .pen file has no top-level frame, so it has no artboard to import.");
+    failure.code = "pen/no-pages";
+    throw failure;
+  }
+
+  ledger.refs.found = countRefs(json);
+
+  const tokenBlock = [...tokens.values()].map((t) => `${t.name}:${t.value}`).join(";");
+  const head = [
+    "  <meta charset=\"utf-8\">",
+    `  <title>${escapeText(options.title ?? json.name ?? options.fallbackTitle ?? "imported")}</title>`,
+    '  <meta name="design-schema" content="3.0">',
+    // The base rules come first, in the same block as the tokens. Without them
+    // the imported file means something else in a plain browser than it does in
+    // the canvas: `width` becomes the content width, and every label grows the
+    // height of its default margin. See `lib/base-css.mjs`.
+    `  <style>${baseCss()}\n    :root{${tokenBlock}}</style>`,
+    '  <style>section[data-type="page"]{ margin:0 0 24px }</style>',
+  ].join("\n");
+
+  const html = [
+    "<!doctype html>",
+    "<html lang=\"zh\">",
+    "<head>",
+    head,
+    "</head>",
+    "<body>",
+    pages.join("\n"),
+    "</body>",
+    "</html>",
+    "",
+  ].join("\n");
+
+  // Round trip through the real parser and serializer, so the output is
+  // canonical by construction rather than by hope.
+  const doc = prepareBuiltDocument(parse(html));
+  return { html: serializeCanonical(doc), ledger, diagnostics: doc.diagnostics ?? [] };
+}
+
+/**
+ * An artboard's own style becomes the page box's style.
+ *
+ * The artboard IS a frame, so it goes through the same mapping a frame does.
+ * Mapping only its fill and size is the mistake that hides a whole screen class:
+ * a modal artboard carries `justifyContent: "end"` so its sheet sits at the
+ * bottom, and dropping that leaves the sheet at the top of an otherwise empty
+ * page — with the same total height, which is what makes it hard to notice.
+ *
+ * The values go through the same normalizers the per-node path uses, so an
+ * imported file is canonical by construction and its first `format --check`
+ * passes. A reader that writes its own spelling is a reader that produces files
+ * whose first edit shows up as a formatting diff.
+ */
+function pageStyle(artboard, refs, ledger) {
+  const style = new Map();
+  for (const part of styleFromNode(artboard, refs, ledger, { parentIsColumn: true }).split(";")) {
+    const trimmed = part.trim();
+    const colon = trimmed.indexOf(":");
+    if (colon === -1) continue;
+    style.set(trimmed.slice(0, colon).trim(), trimmed.slice(colon + 1).trim());
+  }
+  // The page box is positioned by the canvas, so it keeps its own size, and it
+  // clips what overflows.
+  if (artboard.width !== undefined) style.set("width", `${Number(artboard.width)}px`);
+  if (artboard.height !== undefined) style.set("height", `${Number(artboard.height)}px`);
+  style.set("overflow", "hidden");
+  return orderedStyleText([...style.entries()], ledger);
+}
+
+function walkPen(node, visit) {
+  visit(node);
+  for (const child of node.children ?? []) walkPen(child, visit);
+}
+
+/** Every `ref` in the file, whether or not it resolves. */
+function countRefs(json) {
+  let n = 0;
+  for (const artboard of json.children) walkPen(artboard, (node) => { if (node.type === "ref") n += 1; });
+  return n;
+}
+
+/** A one-line summary, for a CLI to print. */
+export function ledgerLine(ledger) {
+  const lost = Object.entries(ledger.lost);
+  const unmapped = Object.entries(ledger.unmapped);
+  const parts = [
+    `${ledger.pages} pages`,
+    `${ledger.nodes} elements`,
+    `${ledger.refs.inlined} references inlined`,
+    `${ledger.refs.overridesApplied} with overrides`,
+  ];
+  if (lost.length) parts.push(`lost: ${lost.map(([k, v]) => `${k}×${v}`).join(", ")}`);
+  if (unmapped.length) parts.push(`unmapped: ${unmapped.map(([k, v]) => `${k}×${v}`).join(", ")}`);
+  return parts.join(" · ");
+}