Named assets (painter.assets)

AssetManager is the named composition registry on painter.assets. It stores images, font paths, palettes, and arbitrary JSON-like values, then resolves $name / dotted $value.path references for scenes, templates, and opt-in imperative APIs.

• renderScene, renderSceneToGIF, renderSceneToVideoFrames — asset resolution is on by default; pass resolveAssetRefs: false to skip it.
• Templates — placeholders resolve first, then asset references resolve during TemplateHandle.render / toRenderInput.
• SceneBuilder.render — asset resolution is off by default; opt in with { resolveAssetRefs: true }.
• Imperative create APIs / batch / chain — resolution is opt-in; see Imperative & batch resolution.

#Registering assets

1import { ApexPainter } from "apexify.js";2 3const painter = new ApexPainter({ type: "buffer" });4 5painter.assets.loadImage("logo", "./brand/logo.png");6painter.assets.loadFont("heading", "./fonts/Inter-Bold.ttf");7painter.assets.loadPalette("theme", {8  bg: "#020617",9  text: "#f8fafc",10  muted: "#64748b",11});12painter.assets.loadValue("copy", {13  hero: { title: "Apexify", enabled: true },14  spacing: [8, 16, 24],15});

##Duplicate and replacement contract

Root names are unique across the whole registry. loadImage, loadFont, loadPalette, and loadValue throw ApexifyAssetError when that name is already registered. Replacement is explicit:

• replaceImage(name, source)
• replaceFont(name, path)
• replacePalette(name, colors)
• replaceValue(name, value)

A replace call also throws when the target name does not exist. This prevents accidental overwrite during application startup.

Cleanup/introspection:

• has(name) — root-name existence check.
• delete(name) — remove any asset kind by root name.
• unregisterImage, unregisterFont, unregisterPalette — kind-specific removal helpers.
• list() — returns { name, kind } registrations.
• clear() — empties the registry.

Registered JSON-like data and Buffers are copied on ingress, and resolve() returns an isolated copy. Mutating the original registration value or a resolved Buffer does not mutate registry storage.

#Reference syntax

Call assets.resolve() without the leading dollar sign:

1painter.assets.resolve("logo");2painter.assets.resolve("theme.text");3painter.assets.resolve("copy.hero.title");4painter.assets.resolve("copy.spacing.1");

In composition data, use the leading $:

Unknown roots, missing nested properties, unsafe path segments, and attempts to embed a non-scalar asset inside a longer string throw ApexifyAssetError. Use a non-scalar reference as the entire field value instead.

The deep resolver rejects cyclic arrays/plain objects rather than recursing indefinitely. Opaque runtime objects are preserved; JSON-like arrays/records are traversed.

#Example — scene + palette + image

1import { ApexPainter } from "apexify.js";2import fs from "node:fs";3 4const painter = new ApexPainter({ type: "buffer" });5 6painter.assets7  .loadImage("avatar", "./fixtures/user.png")8  .loadPalette("brand", { panel: "#1e293b", ink: "#e2e8f0" });9 10const png = await painter.renderScene({11  width: 480,12  height: 240,13  background: { colorBg: "$brand.panel" },14  layers: [15    {16      type: "text",17      texts: {18        text: "Signed in",19        x: 24,20        y: 36,21        fontSize: 22,22        color: "$brand.ink",23      },24    },25    {26      type: "image",27      images: { source: "$avatar", x: 320, y: 40, width: 112, height: 112 },28    },29  ],30});31 32fs.writeFileSync("card.png", png);

Use loadFont plus a full-field font path reference when a text API accepts a font path string.

#prepareForRender

painter.prepareForRender<T>(value): T deep-resolves asset references in JSON-like arrays/records without rendering anything. It is useful when an imperative API does not expose an asset-resolution option or when you want one resolved snapshot reused across calls.

1const base = painter.prepareForRender({2  width: 720,3  height: 400,4  colorBg: "$theme.bg",5});6 7await painter.createCanvas(base);

Because resolution returns a new composition structure, the input object is not mutated.

#Relationship to templates

Templates use one deterministic pipeline: visibility filtering → placeholder resolution → asset resolution → numeric/layout normalization → scene validation. A whole placeholder or asset reference can preserve native values such as false, 0, arrays, objects, or Buffers where the target field accepts them.

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