# Text fitting

Text fitting keeps longer copy inside a template's design. It shrinks, grows or wraps the text layers you name until they fit their space.

## Add the rules

The rules live in `text_fitting.json`, at the root of the version next to `data.json`. This file shrinks the layer named `Price`, so its new copy is never wider than the original copy was:

```json
{ "layers": [{ "nm": "Price", "textFit": { "shrink": "toFit", "region": { "source": "originalBounds" } } }] }
```

Add it with an [edit](/docs/blitframe/projects#editing-a-project), like any other file:

```http
POST /v1/projects/{projectId}/versions
{
  "files": [
    { "path": "text_fitting.json", "content": "{ \"layers\": [ { \"nm\": \"Price\", \"textFit\": { \"shrink\": \"toFit\", \"region\": { \"source\": \"originalBounds\" } } } ] }" }
  ],
  "textFittingBaselineVersionId": "4f0a…"
}
```

Then change the copy as usual, with [replacements](/docs/blitframe/editing) or a new `data.json`. Blitframe fits the text whenever it renders or exports a version. It never changes the files in your version.

`textFittingBaselineVersionId` is optional. It names the version whose text `originalBounds` measures ([baseline version](#baseline-version)).

Read the rules back with `GET /v1/versions/{versionId}/files/text_fitting.json`. It redirects (`302`) to the file, so follow the redirect (`curl -L`). To remove the rules, edit the project with `"delete": ["text_fitting.json"]`. Earlier versions keep their file, so [restoring](/docs/blitframe/projects#undoing-a-change) one brings it back.

All requests go to `https://blitframe.codeartworks.com` with an `Authorization: Bearer <api key>` header.

## Examples

### A headline in its paragraph box

A paragraph text layer named `Headline` says "Play the game". When the copy becomes "Play the game now", the box has no room for the last word, so it is not drawn:

![A blue card with the text "Play the game" on two lines. The last word of the new copy, "now", is missing.](/docs/blitframe/images/text-fitting-box-before.png)

This rule shrinks the text until every line fits inside the box, and never below 6 pixels:

```json
{ "layers": [{ "nm": "Headline", "textFit": { "shrink": "toFit", "region": { "source": "box" }, "minSize": 6 } }] }
```

![The same card with the whole text, "Play the game now", on three lines inside the box.](/docs/blitframe/images/text-fitting-box-after.png)

A `box` region always wraps, so `"wrap": true` is not needed. Shorter copy keeps its size: `grow` does not enlarge wrapped text in a `box` region.

### A price on its badge

A text layer named `Price` sits on a shape layer named `priceTag_bg`:

![A yellow starburst badge with the price "$99" in red at its center. Selection handles mark the text and the badge behind it.](/docs/blitframe/images/text-fitting-price-badge.png)

This rule sizes the price to the badge's width, less a 10-pixel margin on each side. A longer price shrinks and a shorter one grows, between 8 and 200 pixels:

```json
{
  "layers": [
    {
      "nm": "Price",
      "textFit": {
        "shrink": "toFit",
        "grow": "toFill",
        "region": { "source": "layer", "ref": "priceTag_bg", "margin": 10 },
        "minSize": 8,
        "maxSize": 200
      }
    }
  ]
}
```

Without `wrap`, only the size adapts to the badge's width. Use point text, and give the badge a name no other layer has ([layer regions](#layer-regions)).

## The text fitting file

A file with two rules:

```json
{
  "layers": [
    {
      "nm": "Price",
      "textFit": {
        "shrink": "toFit",
        "grow": "toFill",
        "region": { "source": "originalBounds", "margin": 10 },
        "minSize": 8,
        "maxSize": 200
      }
    },
    {
      "nm": "Headline",
      "textFit": { "wrap": true, "shrink": "toFit", "region": { "source": "box" }, "maxLines": 2 }
    }
  ]
}
```

| Field | Meaning |
|---|---|
| `layers` | Up to 1,000 rules, one per text layer. |
| `layers[].nm` | The exact, case-sensitive name of one text layer in `data.json`, 1 to 200 characters. It can be in the main composition or in a precomposition it uses, at any depth. No other text layer may have the same name, and each name appears once in the file. |
| `layers[].textFit` | How to fit that layer ([textFit fields](#textfit-fields)). |

Only the layers you name are fitted. Fitting changes:

- the font size, and the line height with it, in proportion,
- the line breaks, when the text wraps,
- the position, only for a `layer` region with `wrap: true`, which centers point text in that layer,
- keyframes, only to keep sliding text hidden off frame ([moving text](#moving-text)).

Blitframe measures text the way the engine draws it ([how text is measured](#how-text-is-measured)).

## textFit fields

| Field | Values | Meaning |
|---|---|---|
| `region` | Object | Required. The space to fit into ([region sources](#region-sources)). |
| `wrap` | `true`, `false` (default) | Break the text into lines at the region's width. Line breaks already in the text are kept. A `box` region always wraps, because the engine wraps paragraph text at its box width. |
| `shrink` | `none` (default), `toFit`, `lastResort` | `toFit` reduces the font size until the text fits. `lastResort` reduces it only when the text needs more than `maxLines` lines or is taller than `maxHeight`. |
| `grow` | `none` (default), `toFill` | Enlarge text that does not wrap until it nearly fills the region's width, and fits its height, up to `maxSize`. |
| `maxLines` | Positive integer | The most lines the text may take. |
| `maxHeight` | Pixels | The tallest the text block may be. |
| `minSize` | Pixels, default `1`, at most `10000` | The text never shrinks below this size, and text set smaller is raised to it. |
| `maxSize` | Pixels, at least `minSize`, at most `10000` | The text never grows beyond this size. |
| `clampToComp` | `true`, `false` (default) | Also keep the text within the width of the composition it is in. For text in a precomposition, that is the narrowest precomposition layer that shows it. |

The fitted size is a whole number of pixels, rounded down. If no whole size between `minSize` and `maxSize` fits, it keeps its fraction. A `layer` region treats some fields differently ([layer regions](#layer-regions)).

Text that can't fit renders at the smallest size the rule allows: `minSize` when the rule shrinks it, otherwise its own size. It overflows its region rather than getting smaller. The version still renders, and its `warnings` name the layer and the limits it hit. Shorten the text or change the limits.

## Region sources

| `source` | Other fields | Fits into |
|---|---|---|
| `box` | `margin` | The layer's own paragraph box (`sz` in its text document): its width and height. Point text and text on a path have no box, so use another source for them. |
| `originalBounds` | `margin` | The width the layer's text had in the [baseline version](#baseline-version): its widest line as drawn, wrapped at its box width when it has a box. Use it to keep new copy within the space the original copy took. |
| `layer` | `ref` (required), `margin` | The bounds of another layer, such as the shape behind a price ([layer regions](#layer-regions)). |
| `rect` | `rect` (required), `margin` | An explicit `[x, y, width, height]` in composition pixels. Its width and height set the space. The text stays where it is. |

- `margin` is space in pixels kept from each edge of the region.
- With `originalBounds`, `minSize` and `maxSize` scale with the layer's font size. When its `s` is twice the baseline's, both limits double.
- On a layer that has a paragraph box, the `originalBounds` and `rect` sources also keep the text within the box. The engine wraps it at the box width and draws a line when at least half of it fits the box height. It always draws the first line.

### Layer regions

The engine fits a `layer` region itself, so it has its own rules:

- `ref` is the name of a shape, solid, image, video, 3D model, precomposition or adjustment layer in the same composition as the text. An adjustment layer counts only with its effects and its size `sw` and `sh`.
- The engine uses the first layer in the composition's `layers` list with the `ref` name. If that layer is the text itself, or another kind such as a null or a camera, the text keeps its own size. Give the region layer a unique name.
- The fit is worked out once, before the first frame, from the two layers' position, anchor point and scale. It does not follow their animation, rotation or parenting.
- With `wrap: true`, the text block is centered vertically in the referenced layer and keeps its paragraph alignment (`j`).
- With `wrap: false`, only the size adapts to the layer's width, measured from the widest line before any wrapping.
- Use point text. On paragraph text the box still applies ([layer region details](#layer-region-details)).

Some fields work differently on a `layer` region:

| Field | On a `layer` region |
|---|---|
| `shrink` | `lastResort` acts as `toFit`. |
| `grow` | Text that does not wrap grows until its widest line spans the layer's width exactly, whatever its height. Wrapped text grows too, until it fills the layer's height. |
| `minSize` | Applies only with `shrink`, and then text set smaller is raised to it. Without `shrink`, the text keeps its size. |
| Size rounding | Without `wrap`, the size always keeps its fraction. With `wrap`, it always rounds down, even below a fractional `minSize`. |
| `maxLines`, `maxHeight`, `clampToComp` | Not applied. |

## Baseline version

`originalBounds` measures the text a layer had in another version, its **baseline**. The baseline is not in the file: Blitframe keeps it with each version as `textFittingBaselineVersionId`.

- When text fitting is added or replaced, the baseline is the version the change was made on. An edit can pick another version with `textFittingBaselineVersionId`, from the history of the variation it edits (`main` by default), with a `data.json`. When there is no earlier version with a `data.json` (a new project), the version is its own baseline.
- An edit that sends `textFittingBaselineVersionId` must leave `text_fitting.json` in the new version, or it is refused with `400`. An edit that only picks a different baseline creates a new version with the same files.
- A ZIP import that contains `text_fitting.json` is always its own baseline, even into a project with earlier versions. To measure against an earlier version, edit the project afterwards with `textFittingBaselineVersionId`.
- Later edits that leave the file as it is keep the baseline, so changing the copy afterwards still measures against the original. So do [renders with replacements](/docs/blitframe/editing#in-a-render): each render's copy is measured against the pinned version's baseline.
- [Duplicating a project](/docs/blitframe/projects#duplicating-a-project) copies the baseline along with the version, so the copy fits text the same way.
- Removing the file clears the baseline.

The text being fitted always comes from the version being rendered.

## Rules in data.json

A text layer can also carry one rule in its own text data, `t.textFit` in `data.json`, with the `layer` source only. It follows the [layer region](#layer-regions) rules, and the [format reference](/docs/blitframe/data-json-format#fit-text-to-a-layer) lists how the engine reads its fields. The engine ignores an inline rule with any other source, and the version's `warnings` say so.

When the text fitting file has a rule for the same layer and that rule is applied, the inline one is ignored. A file rule that is not applied ([checking and rendering](#checking-and-rendering)) leaves the inline rule in force.

## Moving text

Text that slides in from outside the frame, or leaves it, is moved out a little further when its copy gets longer. So it still starts and ends fully hidden. This applies to every text layer whose rule is applied, in the file or inline.

When the layer's first or last position keyframe is outside the frame, Blitframe pushes that keyframe further out. It goes just far enough to keep everything the text draws outside. That includes:

- the fitted text with its stroke and baseline shift (paragraph text with its box and one more line),
- what its Drop Shadow, Glow, Gaussian Blur and Fast Box Blur effects draw around it,
- what its stroke, drop shadow and outer glow layer styles draw around it.

Positions on screen, timing and easing don't change. These layers are left as they are:

- layers with a parent, 3D layers (with an X rotation `rx`) and layers with animated rotation or an animated anchor point,
- layers whose position is driven by an expression,
- layers with Corner Pin, CC Power Pin, Mirror, CC Cylinder or Transform, which can move the text anywhere,
- text fitted to a `layer` region with `wrap: true` or `grow: toFill`, which the engine resizes and moves after Blitframe measures it.

Like the rest of fitting, this happens when Blitframe renders or exports. Your `data.json` keeps its own keyframes.

## Checking and rendering

Blitframe checks `text_fitting.json` against the version's `data.json` and fonts whenever a version that contains it is created and has no `problems`. On a version with `problems`, only the file itself is checked. Fitting never stops a version from rendering. Each fault is listed in the version's `warnings` with the field or layer at fault. Most faults leave their rule unapplied, so that text renders as written ([every fault](#faults)).

Fix the rules in another edit. The warnings of the new version show what is left. [Inspect the layers](/docs/blitframe/editing#editable-layers) of a version to see `textFit: true` on every layer a rule applies to. A version with `problems` shows none. If fitting itself fails while a version renders, the render draws all text as written, without its inline rules either.

Fitting measures text with the font files the composition uses, in the version or the [font library](/docs/blitframe/fonts). It reads only TTF and OTF files. A WOFF or WOFF2 font still renders, but its text is not fitted. To fit it, add a TTF or OTF copy of the font. Render a few frames to check the result, especially for text with animators, effects or 3D.

A [version export](/docs/blitframe/projects#exporting-a-version) of a renderable version contains `data.json` with the fitting already applied. It leaves the text fitting file out, so the ZIP renders exactly like the version.

## MCP

Agents add `text_fitting.json` with the `edit_project` tool, including `textFittingBaselineVersionId`, and read it with `read_file`. See [MCP for agents](/docs/blitframe/mcp).

## Details

### How text is measured

- With the font's own advances and kerning, and the layer's tracking. Accents and other marks take no space.
- Lines break after a space, `-` or `/`, and at every `\r`, `\n` or ETX (`\u0003`). Each one is a break, so `\r\n` makes two.
- At most 64 lines and 16,383 characters are measured.
- Fitting never picks a size that splits a word. A word too wide for the line makes the text smaller, or makes it unable to fit.
- Text that still cannot fit renders as the engine lays it out. The engine breaks a word wider than the line where it overflows. A letter wider than the line ends the text there, and nothing after it is drawn.
- Joining scripts (Arabic) and the font's own glyph compositions are measured from the unjoined characters. Render a few frames of such copy to check it.

### Size checks

A fitted layer's font size (`s`) must be positive, and it and the line height (`lh`) must be at most 10,000 pixels, or its rule is not applied. Without `lh`, or with an `lh` of 0 or less, the line height is 1.2 times the size, as the engine draws it. This check covers the `box`, `originalBounds` and `rect` sources. A `layer` region is fitted while rendering and is not checked in advance, so check those layers with a [frame render](/docs/blitframe/renders#frame-renders).

### Layer region details

- The engine fits at most 15 text layers to a `layer` region in each composition, in layer order, counting inline `t.textFit` rules.
- The text keeps its own size, and the version's `warnings` say so, when:
  - its rule is past the fifteenth,
  - no layer has the `ref` name (an audio layer does not count),
  - the first layer with that name can't be fitted to,
  - the `margin` leaves no room inside the layer, or the text layer's scale is 0 on either axis.
- The text also keeps its own size, without a warning, when the region is a shape layer that draws nothing or the text's size is 0. The version still renders in every case.
- Blitframe checks the margin in advance only for solid, adjustment, precomposition, image and video regions with a fixed scale. For a shape or 3D model region, or an animated scale, check it with a frame render.
- With `wrap: true`, the engine writes its line breaks into the text. A text animator based on lines, and line grouping, follow the fitted lines. Text past the 64th line, or from a letter wider than the layer on, is left out.
- With `wrap: true` but without `shrink` or `grow`, the text only wraps at the layer's width and the size is rounded down. Text that does not fit overflows, and a word wider than the line breaks where it overflows.
- With `wrap: true`, lines break after a space, `-` or `/` and at each line break, which stays a single break. A size at which a word has to break does not count as fitting.
- On paragraph text, the box still applies. The lines wrap at the box width and align within it. The box shows a line when at least half of it fits its height, and always shows the first line. The block is not centered, and the version's `warnings` point this out.
- With `wrap: true` on paragraph text, the box's top-left corner moves to the point where the engine would anchor centered point text. That is the layer's left edge, center or right edge, by alignment, at the first line's baseline. So the text sits lower than centered, and further right with center or right alignment.
- For paragraph text, the rule is not applied, with a warning, when the fitted size would leave nothing to draw in the lines the box shows. That happens, for example, when the first letter is wider than the box. Such text would stop the render.
- For paragraph text, the rule is also not applied, with a warning, when Blitframe cannot tell the fitted size in advance. That happens with a shape or 3D model region, or an animated scale, while `grow` has no `maxSize`. It also happens with a font it cannot measure, whenever the rule can make the text larger than it is. Point text is fitted regardless.

### Faults

Each fault is listed in the version's `warnings`, and the version still renders ([checking and rendering](#checking-and-rendering)).

| Fault | Result |
|---|---|
| The file is not valid JSON, has an unknown field or a value out of range, or names a layer twice. | No rule is applied. |
| A rule's name matches no text layer, or more than one. | That rule is not applied. The other rules still are. |
| The text is in a precomposition the main composition never uses, so the engine never draws it. | That rule is not applied. |
| A `box` region is on point text. | That rule is not applied. |
| The baseline can't be read, or a font can't be measured. | That rule is not applied. |
| The font size or line height is out of range ([size checks](#size-checks)). | That rule is not applied. |
| The fitted size would leave nothing to draw in the lines the text's box shows, for example because the first letter is wider than the box. Such text would stop the render. | That rule is not applied. |
| A `layer` region can't be applied ([layer region details](#layer-region-details)). | The text keeps its own size. |
| The text can't fit. | It renders at the smallest size the rule allows (`minSize` when the rule shrinks it, otherwise its own size) and overflows. |
