Templates (createTemplate)

ApexPainter#createTemplate(definition, options?) captures an immutable copy of a scene-shaped definition and returns a TemplateHandle.

TemplateHandle snapshots both the definition and each render's data before asynchronous layout work. Mutating caller-owned objects after createTemplate() or after starting a render does not change that render.

#Resolution order

The supported pipeline is deterministic:

1. Apply render-time insertions.
2. Validate unique literal layer id values.
3. Apply overrides by id.
4. Evaluate visible and remove hidden subtrees.
5. Resolve {{placeholders}}.
6. Resolve $assets.
7. Normalize numeric layout fields and shorthand layers.
8. Expand flex/grid layouts.
9. Validate the resulting SceneRenderInput with the normal scene limits.

Hidden layers are removed before their other placeholders/assets are resolved, so a missing value inside an intentionally hidden layer does not fail the render.

#Placeholders

• {{key}} — required. Missing or null/undefined values throw TemplateResolveError.
• {{key | default}} — the explicit default is used only for missing/nullish values.
• Dotted own-property paths such as {{user.name}} are supported.
• A placeholder that occupies the entire string field preserves the native value. 0, false, and "" are not treated as missing.
• An embedded placeholder inside a longer string is stringified.

Preserving an explicit empty string does not bypass the final scene contract. If "" resolves into a field that requires a non-empty string, such as a text layer's text, toRenderInput() / render() rejects the final scene during validation. Apexify.js does not silently substitute the placeholder default or drop the layer; use visible when an empty value should intentionally suppress content.

1const data = {2  position: { x: 0 },3  enabled: false,4  label: "",5  user: { name: "Ada" },6};

Unsafe prototype-path segments are not traversed.

#Shorthand layers

Template definitions may use document-style shorthand:

• { type: "text", text: "…", … } → scene texts form.
• { type: "image", source: "…", … } → scene images form.

The final SceneRenderInput contains normal scene layers.

#Minimal example

1import { ApexPainter } from "apexify.js";2import fs from "node:fs";3 4const painter = new ApexPainter({ type: "buffer" });5painter.assets.loadPalette("ui", { bg: "#0f172a", fg: "#f8fafc" });6 7const card = painter.createTemplate({8  width: 560,9  height: 220,10  background: { colorBg: "$ui.bg" },11  layers: [12    {13      id: "title",14      type: "text",15      text: "{{title}}",16      x: 32,17      y: 48,18      fontSize: 28,19      color: "$ui.fg",20    },21    {22      id: "body",23      type: "text",24      visible: "{{showBody}}",25      text: "{{body | Nothing to show}}",26      x: 32,27      y: 110,28      fontSize: 16,29      color: "$ui.fg",30    },31  ],32});33 34const png = await card.render({35  title: "Ada",36  showBody: true,37  body: "Your graph is ready.",38});39 40fs.writeFileSync("template.png", png);

#Visibility

visible accepts booleans, numbers, literal strings, or placeholder strings. Common string values are interpreted explicitly: true, 1, yes are true; false, 0, no, and the empty string are false.

For a whole placeholder such as visible: "{{feature.enabled}}", the native boolean/number/string value drives visibility.

#Overrides and insertions

Every targetable layer id must be a unique, non-empty literal string. Placeholder ids are rejected.

##Deep overrides

1await card.render(2  { title: "Build", showBody: false },3  {4    overrides: {5      title: { color: "#4ade80", fontSize: 32 },6    },7  }8);

Overrides use the authored template-layer shape and deep-merge plain nested objects. Unknown ids are rejected instead of being silently ignored.

##Deterministic insertions

1await card.render(2  { title: "Build", showBody: false },3  {4    insertions: [5      {6        targetId: "title",7        position: "after",8        layers: {9          id: "status",10          type: "text",11          text: "Passed",12          x: 32,13          y: 82,14          fontSize: 14,15          color: "#4ade80",16        },17      },18    ],19  }20);

Each insertion target must exist exactly once, and insertions may not introduce duplicate ids.

#Flex layout

A type: "layout" node with layout.type: "flex" expands to absolutely positioned children.

Text children are measured with measureText; image children require positive explicit width/height. Layout containers also require positive width/height.

1const hero = painter.createTemplate({2  width: 640,3  height: 200,4  background: { colorBg: "#020617" },5  layers: [6    {7      type: "layout",8      x: 40,9      y: 32,10      width: 560,11      height: 136,12      layout: {13        type: "flex",14        direction: "column",15        gap: 10,16        padding: 12,17        align: "start",18        justify: "center",19      },20      children: [21        { type: "text", text: "{{headline}}", x: 0, y: 0, fontSize: 26, color: "#f8fafc" },22        { type: "text", text: "{{tagline}}", x: 0, y: 0, fontSize: 15, color: "#94a3b8" },23      ],24    },25  ],26});

#Grid layout

layout.type: "grid" supports positive integer columns, non-negative gap / padding, and start / center / end alignment and justification. Cell width is derived from the container; row height is the tallest child in that row. Invalid geometry that leaves no positive cell area throws TemplateResolveError.

1{2  type: "layout",3  x: 20,4  y: 20,5  width: 400,6  height: 220,7  layout: { type: "grid", columns: 2, gap: 12, padding: 8, align: "center", justify: "center" },8  children: [9    { type: "image", source: "rectangle", width: 120, height: 60, shape: { fill: true, color: "#334155" } },10    { type: "image", source: "rectangle", width: 120, height: 60, shape: { fill: true, color: "#475569" } },11  ],12}

#Asset resolution

After placeholders, the shared asset-reference engine resolves $name, dotted paths, $$ escaping, whole-field structured/Buffer references, and scalar embedded references. Unknown assets become TemplateResolveError with the asset token and original cause.

Pass createTemplate(definition, { resolveAssetRef }) when a template needs a custom resolver instead of painter.assets.

render() deliberately calls the final scene render with resolveAssetRefs: false because the template stage already resolved its assets.

#toRenderInput

1const input = await hero.toRenderInput({ headline: "Ship faster", tagline: "One scene, many rows." });2 3await painter.renderSceneToGIF(input, {4  options: { width: 640, height: 200, outputFormat: "buffer" },5});

The returned object is an isolated, validated SceneRenderInput snapshot. Mutating it does not mutate the template definition or later renders.