Advanced / Composition · guide
Composition hub — scenes, templates, assets, components & plugins
Current Apexify.js 6.0.0 documentation for Composition hub — scenes, templates, assets, components & plugins.
This folder documents Apexify.js's higher-level composition architecture: named assets ($…), immutable templates ({{…}}), reusable scene components, asynchronous plugins, and opt-in asset resolution for imperative/batch workflows.
Start by goal
| You want to… | Start here |
|---|---|
| Register reusable images, font paths, palettes, or arbitrary composition values | Named assets |
| Define one design and fill placeholders per request/row | Templates |
| Compose badges, progress bars, avatars, cards, and watermarks | Preset components |
| Install optional named extensions safely | Plugins |
Use $ references inside imperative APIs, batch, or chain | Imperative & batch resolution |
| Work directly with ordered/nested scene graphs | Scene overview |
Phase 6 composition contract
Apexify.js 6 hardens the original composition features into one explicit contract:
- Assets — one root-name registry across images/fonts/palettes/values; duplicate loads fail; replacement is explicit;
$$escapes literal dollars; dotted paths and whole-field Buffer/structured values are defined; unsafe/cyclic inputs fail clearly. - Scenes — stable bottom→top order, copy-on-ingress builder semantics, isolated snapshots, direct child-canvas surface compositing, mandatory validation, and aggregate scene limits.
- Templates — immutable definition/data snapshots; nullish-only defaults; native
0/false/""preservation; visibility before missing-field resolution; unique ids; deep overrides; deterministic insertions; flex and grid layout; final scene validation. - Components — validated scene-layer factories with bounded geometry. Accessibility semantics belong to the UI that presents the generated raster.
- Plugins —
await painter.use(plugin)is the supported lifecycle; installs may be async, same-name duplicates are rejected, installs serialize, and PluginHost mutations roll back transactionally on failure.
Mental model
painter.assets owns named reusable composition data. Scenes and templates can reference that data with $name / dotted paths. renderScene resolves scene asset refs by default; imperative methods and SceneBuilder.render() keep resolution off unless you opt in or call prepareForRender() first.
Templates first transform authored template data into a validated SceneRenderInput: insertions and overrides are applied deterministically, hidden branches are removed, placeholders/assets resolve, layout expands, then normal scene validation runs. Components simply return ordinary SceneLayer[], so they compose with scenes/builders/templates without a separate rendering model.
Plugins are an extension lifecycle around the same painter: register plain APIs with painter.plugins.use(name, api), or perform one-time setup with await painter.use(plugin).