> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/developers-headless/studio/template-builder/how-rendering-works.md).

# How rendering works

An embedded editor always needs an authenticated Scaleflex tenant, even in [stateless](https://docs.scaleflex.com/developers-headless/studio/template-builder/storage-modes.md) mode where your own application owns the template document. This page is why. It is worth reading before you design an integration around the widget, because it explains a constraint you cannot configure away.

### A template is not an image

A template is a document. The image only exists when someone requests the template's CDN URL, and Scaleflex renders it there, server-side, with ImageMagick:

```
https://<tenant>.filerobot.com/<path>/<template>.fdt?<templateQuery>&force_format=png
```

The editor's contract is that what an author sees while editing is what that URL will return.

That rules out drawing text in the browser. Line breaking, kerning, letter spacing, baseline placement, shrink-to-fit and antialiasing are FreeType and ImageMagick behaviors. Canvas `fillText` and DOM text go through the browser's own shaping and hinting instead, so the same layer lands differently in Chrome, Safari and Firefox, and differently from the export in all three. A few pixels of drift is enough to move a headline off a product shot.

So the editor does not approximate the export. It runs the same engine.

### The round trip

Text and shape layers are rasterized by an ImageMagick 7 build hosted in the deployment you point `base-url` at. Each layer comes back as a transparent PNG that the canvas positions with CSS.

```
  browser - the widget                        the deployment (base-url)
  --------------------                        -------------------------
  edit a text layer
      |  batched across layers, debounced
      |------  POST /api/render-layers  ----->  ImageMagick (WASM)
      |        layers + fonts + variables       |- resolve fonts: bundled,
      |                                         |  then the tenant's
      |                                         |  /.studio/fonts
      |                                         |- draw at 3x, downscale
      <------  transparent PNG per layer  -----'
      |
      '- position, rotate and fade with CSS - no round trip
```

The export pipeline drives ImageMagick 7 from PHP; the editor drives a WebAssembly build of the same engine.

### What you can observe from outside

* **Content edits cost a round trip; placement edits do not.** Text, font, weight, color, alignment, letter spacing and box size re-render. Dragging, rotating and opacity are CSS transforms on a PNG already in the page, so they stay at pointer speed.
* **Bursts collapse.** Requests are debounced at around 300 ms and batched across layers, and an in-flight batch is aborted when the author keeps typing. A sentence typed at speed costs one render, not one per keystroke.
* **Layers are drawn at 3x and downscaled**, so preview antialiasing matches the export rather than the browser's rasterizer.
* **Fonts are resolved on the server** against the tenant's `/.studio/fonts` folder and cached there, so the page never downloads a rendering engine or a font binary per weight.
* **Image layers are the exception.** They are plain `<img>` elements, drawn by the browser. A layer requiring the background-removed version of its asset still previews the cut-out, because delivery resolves that from the source URL rather than the canvas compositing it - see [The render URL](https://docs.scaleflex.com/developers-headless/studio/template-builder/render-url.md#background-removed-image-sources).

### Why the endpoint is authenticated

`POST /api/render-layers` fetches fonts and images by URL on the server's behalf, so it is not open to anonymous callers. It requires the credential the widget handed over. Without a valid one it answers `401`, and text and shape layers simply never appear - the canvas shows image layers and backgrounds and nothing else. That symptom is in [Troubleshooting](https://docs.scaleflex.com/developers-headless/studio/template-builder/troubleshooting.md).

The same credential authorizes the font list and upload calls and the asset picker.

A Hub session covers this. A stateless embed has no Hub session to hand over, and that is the gap a [security template](https://docs.scaleflex.com/developers-headless/studio/template-builder/authentication.md) fills: a permission-scoped, project-level guest credential that authorizes rendering, fonts and asset browsing without authenticating any particular user, and without your users existing in Scaleflex at all.

### What statelessness does and does not buy you

Statelessness applies to the **document**, not to the infrastructure. The editor still needs an authenticated tenant for:

* text and shape rendering, as above,
* fonts, served from the tenant's `/.studio/fonts`,
* asset browsing and upload, since image layers are picked from the DAM,
* metadata variables and regional settings.

What it does let you avoid is mapping *your users* onto Scaleflex identities. Point every embed at one service tenant with a single machine credential minted on your server, and do all per-user permission work yourself.

{% hint style="info" %}
**Images on your own CDN.** A template may reference images you host, but the render service only fetches from allowlisted hosts. Add yours to the deployment's `RENDER_ALLOWED_HOSTS_EXTRA`.
{% endhint %}

### Where to go next

* [Authentication](https://docs.scaleflex.com/developers-headless/studio/template-builder/authentication.md) - scoping the credential this page needs
* [Storage modes](https://docs.scaleflex.com/developers-headless/studio/template-builder/storage-modes.md) - the document side of the same question
