diff --git a/HANDOFF.md b/HANDOFF.md
new file mode 100644
index 00000000..b608f998
--- /dev/null
+++ b/HANDOFF.md
@@ -0,0 +1,162 @@
+# Handoff — cropping, gradients and text docs
+
+Working notes so this can be picked up on another machine. **Delete this file
+before merging** — it is scratch, not site content.
+
+## Where things stand
+
+Two branches, both pushed to origin.
+
+### `cropping-demos` — pushed, ready for a PR
+
+Open at https://github.com/fabricjs/fabricjs.github.io/pull/new/cropping-demos
+
+| Commit | |
+| --- | --- |
+| `ae50fb4` | feat(demos): add cropping controls demo |
+| `c2df674` | docs(cropping): trim the cropping images guide |
+| `86b7068` | progress *(yours)* |
+| `f73866b` | docs(cropping): explain how enterCropMode is built |
+| `b44affd` | chore: bump fabric.js submodule to v7.4.0 |
+| `ac74579` | chore(api): regenerate reference for v7.4.0 |
+| `4fc3ecd` | feat(gradients): add gradient controls demo and using gradients guide |
+
+Contains: the cropping controls demo, the gradient controls demo, the rewritten
+`cropping-images` guide, the new `using-gradients` guide, the fabric bump to
+7.4.0 (package + submodule), and the 454-file API reference regeneration.
+
+### `using-text` — pushed, in progress
+
+| Commit | |
+| --- | --- |
+| `b3f33be` | docs(text): add the Text guide group |
+| `0047eba` / `82f6b63` | *(yours — added then removed `.claude/launch.json`)* |
+
+Nine pages under `src/content/docs/docs/Text/`, orders 310–390, rendering as a
+collapsible sidebar group between `Getting started` and `Upgrading`.
+
+## Resuming on another machine
+
+```bash
+git fetch origin
+git checkout using-text
+git submodule update --init --recursive   # must land on tag v740
+npm install
+npm run dev
+```
+
+Two environment facts that will otherwise waste your time:
+
+- **`westures` is a devDependency now, and it is required.** `fabric/extensions`
+  re-exports its westures gesture integration unconditionally, but fabric
+  declares `westures` nowhere. Without it, importing `fabric/extensions` dies
+  with `ERR_MODULE_NOT_FOUND` and takes the whole dev server down.
+- **The submodule must be at `v740`.** Tags are named `v740`, not `v7.4.0`. The
+  API reference is generated from it, so a mismatch produces a large spurious
+  diff under `src/content/docs/api/`.
+
+## Text docs — the nine pages
+
+`src/content/docs/docs/Text/`
+
+| Order | File | Notes |
+| --- | --- | --- |
+| 310 | `choosing-a-class.mdx` | The three classes as a chain; only `set()` re-lays-out; the three index spaces |
+| 320 | `layout-and-appearance.mdx` | interactive canvas |
+| 330 | `fonts.mdx` | The measurement cache and the late-webfont failure. The most load-bearing page |
+| 340 | `character-styles.mdx` | interactive canvas |
+| 350 | `editing.mdx` | interactive canvas |
+| 360 | `textbox-wrapping.mdx` | interactive canvas |
+| 370 | `editing-ui.mdx` | The integration cookbook — toolbar focus, undo/redo, mobile, a11y |
+| 380 | `text-on-a-path.mdx` | Beta limits |
+| 390 | `serializing-text.mdx` | Style compression lossiness, SVG asymmetry |
+
+Interactive examples live in a sibling directory per page, e.g.
+`Text/editing/code.js`, imported as `./editing/code.js?raw`. From a page inside
+the group, `CodeEditor` is four levels up: `../../../../components/CodeEditor`.
+
+## Library findings worth taking upstream
+
+These came out of verifying doc claims against a running build. All reproduced.
+
+1. **`fabric/extensions` has an undeclared dependency on `westures`.** Not in
+   `dependencies`, `peerDependencies` or `optionalDependencies`. A downstream
+   user importing only the cropping helpers still hits it.
+
+2. **`toObject()` throws on a style declaration holding only unknown keys.**
+
+   ```js
+   new fabric.FabricText('abcd', { styles: { 0: { 0: { mine: 'x' } } } }).toObject();
+   // TypeError: Cannot read properties of undefined (reading 'end')
+   ```
+
+   `stylesToArray` tries to extend a range that was never opened, because
+   `hasStyleChanged` only compares the 14 known properties. Relevant to anyone
+   adding a custom per-character style property.
+
+3. **CRLF shifts styles by one character per line on a JSON round trip.**
+   `stylesToArray` splits on `'\n'`, `stylesFromArray` on `/\r?\n/`.
+
+   ```js
+   const t = new fabric.FabricText('ab\r\ncd', { styles: { 1: { 0: { fill: 'red' } } } });
+   (await fabric.FabricText.fromObject(t.toObject())).styles;
+   // { 1: { 1: { fill: 'red' } } }   ← moved to character 1
+   ```
+
+4. **`ctrlKeysMapUp[88]` points at a `cut` method that does not exist.** Works in
+   practice only because `_copyDone` short-circuits `onKeyUp` first.
+
+5. **`renderGhostImage` and `cropPanMoveHandler` are not exported** from
+   `fabric/extensions`, so the crop ghost cannot be used with a control set you
+   assigned yourself — only via `enterCropMode`. Exporting them would make the
+   "recompose the pieces yourself" story in the docs actually true.
+
+6. **A gradient colour stop at offset 0 or 1 sits exactly under an axis endpoint
+   handle** and shadows it in hit-testing, so that endpoint becomes hard to grab.
+
+7. **`Textbox`'s class JSDoc claims Y scaling is locked.** It is not — `mt`, `mb`
+   and the corner handles all scale. The doc comment is stale.
+
+## Corrections already applied to the docs
+
+Three claims that source-reading got wrong and testing caught. Mentioning them
+because the same reasoning traps are easy to fall back into:
+
+- An assigned `Textbox` **height is not rejected** — it survives until the next
+  layout pass, then is overwritten.
+- `setSelectionStyles({ prop: undefined })` **deletes the override** and reverts
+  to the object value. It is not a no-op, and it differs from passing `false`.
+- Custom style properties are dropped when merged into a run, but **crash** when
+  they are the only key (see finding 2).
+
+## Open follow-ups
+
+- **Open the `cropping-demos` PR.** Nothing blocking it.
+- **Supersede the Old docs text pages** now that the Text group exists:
+  `Old docs/fabric-text.md`, the `### Text` section of `fabric-intro-part-2.md`,
+  and the Node fonts section of `fabric-intro-part-4.md`. The precedent is the
+  `'/docs/old-docs/fabric-object-caching'` redirect already in
+  `astro.config.mjs`.
+- **Fold the `loading-custom-fonts` demo prose into `Text/fonts.mdx`** and leave
+  the demo as the showcase, per the docs-vs-demos split in `AGENTS.md`.
+- **A rich-text toolbar demo** would be the natural showcase for `editing-ui.mdx`.
+- **Standardise demo tags** — currently `text`, `text styles`, `fonts`,
+  `typography` are used inconsistently.
+- **Collapsible / expandable `CodeEditor`** — your idea from the cropping work:
+  some canvases want the code minimised by default, with the interaction
+  foregrounded.
+- Dependabot reports 64 vulnerabilities on the default branch (28 high). Pre-existing.
+
+## Verifying interactive pages
+
+The canvases register themselves on `window.canvasesId[canvasId]`, which makes
+them scriptable from the browser console — much more reliable than eyeballing:
+
+```js
+const c = window.canvasesId['text-editing'];
+c.getObjects()[0].enterEditing();
+```
+
+One trap when simulating drags: dispatch `mouseup` on **`document`**, not
+`window`. Fabric does not see a window-level mouseup, so `_currentTransform`
+stays active and every later drag silently continues the first handle.
diff --git a/src/content/docs/docs/Text/character-styles.mdx b/src/content/docs/docs/Text/character-styles.mdx
new file mode 100644
index 00000000..70552184
--- /dev/null
+++ b/src/content/docs/docs/Text/character-styles.mdx
@@ -0,0 +1,237 @@
+---
+date: '2026-07-30'
+title: 'Styling individual characters'
+description: 'The styles object, styling a range, and how styles survive editing'
+sidebar:
+  order: 340
+---
+
+import { CodeEditor } from '../../../../components/CodeEditor';
+import code from './character-styles/code.js?raw';
+
+What makes Fabric.js text *rich* text is that any of a small set of properties can
+be overridden per character. This page is the data model behind that.
+
+<CodeEditor code={code} canvasId="text-styles" client:idle canvasDown>
+  <canvas width="600" height="220" id="text-styles"></canvas>
+</CodeEditor>
+
+## The styles object
+
+`styles` is a sparse, two-level map: **logical line index**, then **grapheme index
+within that line**.
+
+```js
+text.styles = {
+  0: {
+    0: { fontWeight: 'bold' },
+    1: { fontWeight: 'bold' },
+  },
+  2: {
+    5: { fill: 'red' },
+  },
+};
+```
+
+A missing line means no styles on that line. A missing character means it inherits
+from the object. So `styles` records only the differences, never a complete
+picture — which is why reading a character's *effective* value needs a helper
+rather than a lookup.
+
+Two things about the indices:
+
+- Character indices count **graphemes**, not UTF-16 units. An emoji or a flag
+  occupies one style slot even though `text.length` counts several.
+- Line indices are **logical** lines — the ones separated by `\n` in your text.
+  For a `Textbox`, the lines you *see* are wrapped lines, and those are a
+  different index space. See [wrapping text with Textbox](/docs/text/textbox-wrapping).
+
+## What can be styled
+
+Exactly fourteen properties:
+
+`fontSize`, `fontWeight`, `fontFamily`, `fontStyle`, `underline`, `overline`,
+`linethrough`, `stroke`, `strokeWidth`, `fill`, `deltaY`, `textBackgroundColor`,
+`textDecorationThickness`, `textDecorationColor`.
+
+Anything not in that list is object-wide only. In particular **`textAlign`,
+`lineHeight`, `charSpacing`, `direction`, `shadow` and `opacity` cannot vary per
+character** — so there is no per-paragraph alignment within a single text object.
+If your editor needs mixed alignment, use one object per paragraph.
+
+`deltaY` shifts a character's baseline in pixels, and is how superscript works.
+
+## Reading and writing a range
+
+```js
+// read
+const styles = text.getSelectionStyles(startIndex, endIndex);
+const complete = text.getSelectionStyles(startIndex, endIndex, true);
+
+// write (merges into whatever is already there)
+text.setSelectionStyles({ fontWeight: 'bold' }, startIndex, endIndex);
+```
+
+Indices are graphemes, `start` is inclusive and `end` is **exclusive**. On an
+`IText` both arguments default to the current selection, which is what makes a
+toolbar button a one-liner:
+
+```js
+itext.setSelectionStyles({ underline: true });
+```
+
+The `complete` flag fills in the object-level value for every property that isn't
+overridden, so you get all fourteen keys back. Use it when you need to know what a
+character actually looks like; omit it when you want to know what was explicitly
+set.
+
+### Three traps in this API
+
+**Omitting `endIndex` silently does nothing.** The documentation suggests it
+defaults to `startIndex + 1`; it does not — the internal loop runs from `start` to
+`end` and with `end` missing it never executes. `getSelectionStyles(3)` returns an
+empty array and `setSelectionStyles({...}, 3)` sets nothing. Always pass an
+explicit end. For the same reason `endIndex: 0` is falsy and behaves like omitting
+it.
+
+**`undefined` and `false` do different things, and neither is a no-op.** Passing
+`undefined` *removes the override*, so the character falls back to the object-level
+value. Passing `false` writes an override of `false`. When the object's own value is
+`true`, the two give opposite results:
+
+```js
+const text = new fabric.FabricText('abc', {
+  underline: true,                            // object-level
+  styles: { 0: { 0: { underline: false } } }, // character 0 overrides it
+});
+
+text.setSelectionStyles({ underline: undefined }, 0, 1);
+// override deleted → character 0 is now underlined, like the rest
+
+text.setSelectionStyles({ underline: false }, 0, 1);
+// override kept → character 0 stays not underlined
+```
+
+So `undefined` means "inherit from the object" and `false` means "force off". Other
+properties in the same declaration are untouched either way. To strip a property
+from every character at once, use `text.removeStyle('underline')`.
+
+**`setSelectionStyles` does not re-measure immediately.** It marks the object for
+re-measurement at the next render instead. Between your call and that render,
+`width`, `height` and `getBoundingRect()` are stale — which bites when you
+reposition a toolbar or an overlay right after applying a style. If you need
+correct dimensions now:
+
+```js
+text.setSelectionStyles({ fontSize: 60 }, 0, 4);
+text.initDimensions();
+text.setCoords();
+```
+
+## Reading an effective value
+
+To find out what a character actually renders as — style override if present,
+object value otherwise — use `getValueOfPropertyAt`:
+
+```js
+const size = text.getValueOfPropertyAt(lineIndex, charIndex, 'fontSize');
+```
+
+Reading `text.fontSize` ignores styles, and reading `text.styles[l][c].fontSize`
+ignores the fallback. This helper is the only correct route, and it takes *line
+and character* coordinates rather than a flat index — convert with
+`text.get2DCursorLocation(index, true)`.
+
+Do not mutate what the lower-level style getters hand back. They return a live
+reference when a style exists and a throwaway empty object when it does not, and
+you cannot tell which from the outside — so treat results as read-only.
+
+## Housekeeping
+
+Styles accumulate redundancy fast, especially through copy and paste, which
+records the *complete* style of every copied character. Two helpers clean up:
+
+- **`text.cleanStyle(property)`** removes per-character values equal to the
+  object's value, prunes the empties, and — if every character agrees — hoists the
+  value onto the object and drops the per-character entries. Note that it can
+  therefore change the object-level property.
+- **`text.removeStyle(property)`** deletes that property everywhere.
+
+`text.styleHas(property)` tells you whether a property appears anywhere, and
+`isEmptyStyles(lineIndex)` whether a line has any styling at all. Both are used
+internally to pick faster rendering paths.
+
+## Superscript and subscript
+
+```js
+text.setSuperscript(startIndex, endIndex);
+text.setSubscript(startIndex, endIndex);
+```
+
+Both are conveniences over `fontSize` and `deltaY`, controlled by the
+`superscript` and `subscript` objects (`{ size: 0.6, baseline: -0.35 }` and
+`{ size: 0.6, baseline: 0.11 }`).
+
+Two consequences of being computed rather than semantic: applying it twice
+compounds — the size multiplies by 0.6 each time — and because `deltaY` is stored
+in pixels, changing `fontSize` afterwards does not rescale the shift. There is no
+`unsetSuperscript`; you reset `fontSize` and `deltaY` yourself.
+
+Also note that the default `superscript`, `subscript` and `offsets` objects are
+shared between instances, so mutating one in place affects every text object
+created afterwards. Replace the whole object instead:
+
+```js
+text.superscript = { size: 0.7, baseline: -0.4 }; // not text.superscript.size = 0.7
+```
+
+## How styles survive edits
+
+When text is inserted or deleted, style keys have to shift with it. Fabric.js
+handles this for you as long as you go through the right API:
+
+- **`text.insertChars(chars, styleArray, start, end)`** — inserts, optionally with
+  one style object per inserted grapheme.
+- **`text.removeChars(start, end)`** — deletes and reflows the remaining styles.
+
+Both re-measure and re-position afterwards. Prefer them over `set('text', …)`,
+which replaces the string without reflowing `styles` at all.
+
+Two behaviours worth knowing because they are visible to users: typing inherits
+the style of the character to the **left** of the caret, and pressing Enter at the
+end of a line deliberately does not drag the previous character's style onto the
+new line. Clearing the text entirely discards all styles.
+
+Neither `insertChars` nor `removeChars` syncs the hidden textarea or fires
+`changed`, so calling them mid-edit needs care — see
+[building a text editing UI](/docs/text/editing-ui).
+
+## Adding your own style property
+
+You can extend the styleable set on a subclass:
+
+```js
+class MyText extends fabric.IText {
+  static _styleProperties = [...fabric.IText._styleProperties, 'myProp'];
+}
+```
+
+That is enough for `getSelectionStyles(…, true)` and `getValueOfPropertyAt` to see
+it. You then override `_renderChar` to draw it, add it to `cacheProperties` if an
+object-level change should repaint, and to `textLayoutProperties` if it affects
+measurement.
+
+**There is a real limit here, so plan for it.** The internal comparison that
+decides "did the style change between these two characters" has a hard-coded list
+of the fourteen properties and no override hook. Two consequences:
+
+1. Adjacent characters differing *only* in your custom property are drawn as one
+   run, using the first character's value.
+2. Serialisation compresses runs the same way, so your property's variation is
+   **dropped by `toObject()`** — and a declaration containing *only* unknown
+   properties makes `toObject()` throw. Never let your property be the sole
+   occupant of a declaration.
+
+The workaround is to serialise `styles` yourself — the loader already accepts the
+uncompressed object form — or to ensure your property never varies independently
+of a known one. See [serializing and exporting text](/docs/text/serializing-text).
diff --git a/src/content/docs/docs/Text/character-styles/code.js b/src/content/docs/docs/Text/character-styles/code.js
new file mode 100644
index 00000000..e37658f9
--- /dev/null
+++ b/src/content/docs/docs/Text/character-styles/code.js
@@ -0,0 +1,39 @@
+const canvas = new fabric.Canvas(canvasEl);
+
+const text = new fabric.IText('Rich text on canvas', {
+  fontSize: 34,
+  fill: '#334155',
+});
+
+// styles is keyed by logical line, then by grapheme index within that line.
+text.styles = {
+  0: {
+    0: { fontWeight: 'bold' },
+    1: { fontWeight: 'bold' },
+    2: { fontWeight: 'bold' },
+    3: { fontWeight: 'bold' },
+    5: { fill: '#7c3aed', fontStyle: 'italic' },
+    6: { fill: '#7c3aed', fontStyle: 'italic' },
+    7: { fill: '#7c3aed', fontStyle: 'italic' },
+    8: { fill: '#7c3aed', fontStyle: 'italic' },
+    13: { underline: true, textBackgroundColor: '#fef08a' },
+    14: { underline: true, textBackgroundColor: '#fef08a' },
+    15: { underline: true, textBackgroundColor: '#fef08a' },
+    16: { underline: true, textBackgroundColor: '#fef08a' },
+    17: { underline: true, textBackgroundColor: '#fef08a' },
+    18: { underline: true, textBackgroundColor: '#fef08a' },
+  },
+};
+
+// Assigning styles in place does not re-measure, so do it explicitly.
+text.initDimensions();
+text.setCoords();
+
+canvas.add(text);
+canvas.centerObject(text);
+
+// The supported way to style a range: indices are graphemes, end is exclusive.
+text.setSelectionStyles({ fontSize: 44 }, 0, 4);
+text.initDimensions();
+text.setCoords();
+canvas.requestRenderAll();
diff --git a/src/content/docs/docs/Text/choosing-a-class.mdx b/src/content/docs/docs/Text/choosing-a-class.mdx
new file mode 100644
index 00000000..7ba09527
--- /dev/null
+++ b/src/content/docs/docs/Text/choosing-a-class.mdx
@@ -0,0 +1,150 @@
+---
+date: '2026-07-30'
+title: 'Text objects: choosing a class'
+description: 'FabricText, IText and Textbox — what each one adds and which to use'
+sidebar:
+  order: 310
+---
+
+Fabric.js has three text classes, and they form a chain rather than a menu:
+
+```
+FabricText  →  IText  →  Textbox
+```
+
+Each one inherits everything from the previous, so the question is never "which
+features do I get" but "how far along the chain do I need to go".
+
+## FabricText
+
+The base class. It renders text and nothing else: no cursor, no keyboard, no
+mouse handling. Everything about how text *looks* lives here — fonts, spacing,
+alignment, decorations, per-character styles — and the other two classes inherit
+all of it.
+
+```js
+const label = new fabric.FabricText('Read only', {
+  fontFamily: 'Helvetica',
+  fontSize: 24,
+});
+```
+
+Reach for it when the text is content rather than input: labels, watermarks,
+captions, generated output. It is the cheapest of the three and cannot be typed
+into even if the canvas is interactive.
+
+## IText
+
+`IText` — the *I* is for interactive — adds the entire editing experience:
+
+- a caret with a blink animation, and a rendered selection
+- keyboard input through a hidden `<textarea>`, including IME composition
+- click to place the caret, double-click to select a word, triple-click for the line
+- copy, cut, paste and drag-and-drop of text
+- the `editing:entered` / `changed` / `editing:exited` event family
+
+```js
+const editable = new fabric.IText('Double-click me', { left: 50, top: 50 });
+canvas.add(editable);
+```
+
+Lines break only where you put a `\n`. The object grows as wide as its longest
+line, and there is no wrapping.
+
+The interactive behaviour is split across four internal layers —
+`ITextBehavior`, `ITextKeyBehavior`, `ITextClickBehavior` and then `IText`
+itself — which matters only when you go looking for a method to override.
+
+## Textbox
+
+`Textbox` extends `IText`, so **it is editable too**. What it adds is a fixed
+`width` that text wraps inside, and a `height` recomputed from the wrapped result:
+
+```js
+const box = new fabric.Textbox('This text wraps inside a fixed width', {
+  width: 200,
+});
+```
+
+This trips people up regularly: you do not choose between "editable" and
+"wrapping". `Textbox` is the editable *and* wrapping option, and there is no
+wrapping-but-not-editable class. If you need that, use a `Textbox` with
+`editable: false`.
+
+## Which one
+
+| You need | Use |
+| --- | --- |
+| Static text, no input | `FabricText` |
+| Typing, lines break only at `\n` | `IText` |
+| Typing inside a fixed width, with wrapping | `Textbox` |
+| Wrapping but not editable | `Textbox` with `editable: false` |
+
+When in doubt, `Textbox` is the closest thing to what a user expects a text box
+to be, and it is what most editor applications end up using.
+
+## The one rule that catches everyone
+
+Text measures itself. Changing a property that affects layout has to re-measure
+the glyphs, re-split the lines and recompute width and height — and that only
+happens when you go through `set()`:
+
+```js
+// re-measures, updates width/height
+text.set('fontSize', 60);
+text.set({ text: 'new content' });
+
+// changes the field and nothing else — width and height are now wrong
+text.fontSize = 60;
+text.text = 'new content';
+```
+
+There are no property setters doing this behind your back. Direct assignment is
+silent: no error, no warning, just a stale bounding box, stale controls, and
+character positions that no longer match what is drawn.
+
+The properties that trigger re-measurement are collected in
+`FabricText.textLayoutProperties`:
+
+`fontSize`, `fontWeight`, `fontFamily`, `fontStyle`, `lineHeight`, `text`,
+`charSpacing`, `textAlign`, `styles`, `path`, `pathStartOffset`, `pathSide`,
+`pathAlign` — plus `width` on `Textbox`.
+
+Everything else (`underline`, `textBackgroundColor`, `direction`, `fill`, …) only
+needs a repaint, which `set()` also handles.
+
+Two consequences worth remembering now, both covered in detail later:
+
+- Mutating the `styles` object in place is direct assignment by another name, and
+  needs a manual `initDimensions()`. See [styling individual characters](/docs/text/character-styles).
+- While an `IText` is being edited, the hidden textarea is the source of truth
+  for the text, so even `set('text', …)` gets reverted by the next keystroke. See
+  [building a text editing UI](/docs/text/editing-ui).
+
+## Three index spaces
+
+Text code deals with positions constantly, and Fabric.js uses three different
+kinds of index. Mixing them up is the single most common source of subtle bugs,
+so it is worth naming them before you meet them:
+
+1. **String offsets** — plain UTF-16 indices into `text`. `text.length` lives here.
+2. **Grapheme indices** — one step per *user-perceived character*. `selectionStart`,
+   `selectionEnd` and the character keys in `styles` all live here. An emoji is
+   one grapheme and several UTF-16 units, so these two spaces are not
+   interchangeable.
+3. **Line indices** — and there are two flavours: *logical* lines (split on `\n`,
+   what `styles` is keyed by) and *visual* lines (what actually gets drawn, which
+   for a wrapping `Textbox` is different).
+
+Fabric.js provides converters for the first two, `fromStringToGraphemeSelection`
+and `fromGraphemeToStringSelection`, and `get2DCursorLocation(index, skipWrapping)`
+for the third — where `skipWrapping: true` gives you logical coordinates and the
+default gives visual ones.
+
+## Where to go next
+
+- [Text layout and appearance](/docs/text/layout-and-appearance) — the properties that control how text looks.
+- [Fonts: loading, measuring and caching](/docs/text/fonts) — read this before shipping a custom font. It prevents a whole class of bug.
+- [Styling individual characters](/docs/text/character-styles) — the rich-text data model.
+- [Editing text](/docs/text/editing) — the interactive layer in depth.
+- [Wrapping text with Textbox](/docs/text/textbox-wrapping) — how wrapping actually decides where to break.
diff --git a/src/content/docs/docs/Text/editing-ui.mdx b/src/content/docs/docs/Text/editing-ui.mdx
new file mode 100644
index 00000000..77fbe014
--- /dev/null
+++ b/src/content/docs/docs/Text/editing-ui.mdx
@@ -0,0 +1,271 @@
+---
+date: '2026-07-30'
+title: 'Building a text editing UI'
+description: 'Toolbars, focus, undo/redo and the practical problems of wiring text editing into an app'
+sidebar:
+  order: 370
+---
+
+The previous pages describe what Fabric.js gives you. This one is about the gap
+between that and a working editor — the problems you only meet once you put a
+toolbar next to the canvas.
+
+## The focus problem
+
+This is the first thing that will break, so start here.
+
+All keyboard input goes through a hidden `<textarea>`. When the user clicks your
+bold button, the browser moves focus to that button, the textarea fires `blur`, and
+Fabric.js responds by **stopping the caret blink and nothing else**. The object
+stays `isEditing === true`, but typing no longer reaches it. To the user the caret
+has simply died.
+
+Fabric.js recovers focus only for clicks on the canvas itself. For your own UI you
+have to prevent the focus loss, which is best done by not letting the toolbar take
+focus in the first place:
+
+```js
+toolbar.addEventListener('mousedown', (e) => e.preventDefault());
+```
+
+`preventDefault` on `mousedown` stops the focus shift while still letting `click`
+fire, so your buttons work and the textarea keeps focus. Do this on the container
+and it covers every button inside.
+
+If something must take focus — a text input for the font size, a colour picker —
+hand focus back afterwards:
+
+```js
+input.addEventListener('change', () => {
+  applyFontSize(input.value);
+  itext.hiddenTextarea?.focus();
+});
+```
+
+Note the `?.` — the textarea is created when editing begins and destroyed when it
+ends, so never cache the reference.
+
+If your toolbar lives inside a modal or a component that traps focus, mount the
+textarea inside it instead of on `document.body`:
+
+```js
+itext.hiddenTextareaContainer = myModalElement;
+```
+
+## Reading the current formatting
+
+A toolbar needs to show the state of the selection. Ask for the *complete* styles
+of the selected range and check whether they agree:
+
+```js
+function selectionState(itext, property) {
+  const styles = itext.getSelectionStyles(
+    itext.selectionStart,
+    itext.selectionEnd,
+    true, // fill in object-level values
+  );
+  if (styles.length === 0) {
+    // caret with no selection: report the object value
+    return itext[property];
+  }
+  const first = styles[0][property];
+  return styles.every((s) => s[property] === first) ? first : 'mixed';
+}
+```
+
+Two details matter here. The `true` flag is what makes unstyled characters report
+the object's value instead of `undefined`, so a run of plain text does not read as
+"mixed". And an empty result means there is no selection — a caret — in which case
+there is nothing to inspect and you should fall back to the object, or to the
+character before the caret if you want the "what will I type in" answer.
+
+Refresh on `selection:changed` and `changed`:
+
+```js
+itext.on('selection:changed', updateToolbar);
+itext.on('changed', updateToolbar);
+```
+
+## Applying formatting
+
+With a selection, this is a one-liner, because the range arguments default to the
+current selection:
+
+```js
+itext.setSelectionStyles({ fontWeight: 'bold' });
+canvas.requestRenderAll();
+```
+
+Two things to add around it. First, remember that `setSelectionStyles` defers
+re-measurement to the next render, so if your UI reads the bounding box — to place
+a floating toolbar above the text, say — force it first:
+
+```js
+itext.setSelectionStyles({ fontSize: 60 });
+itext.initDimensions();
+itext.setCoords();
+canvas.requestRenderAll();
+```
+
+Second, a toggle needs to read before it writes, and should use `false` rather than
+`undefined` to switch a property off:
+
+```js
+function toggleUnderline(itext) {
+  const current = selectionState(itext, 'underline');
+  itext.setSelectionStyles({ underline: current !== true });
+  canvas.requestRenderAll();
+}
+```
+
+With no selection there is nothing to style. Either disable those controls when
+`selectionStart === selectionEnd`, or apply the change to the whole object with
+`itext.set(...)` — decide which and be consistent, because users notice.
+
+## Changing text programmatically
+
+While editing, the hidden textarea holds the authoritative copy of the text, and
+the next keystroke overwrites the object from it. So a plain `set` is silently
+undone:
+
+```js
+itext.set('text', 'replaced'); // reverted as soon as the user types
+```
+
+The right approach depends on whether you want to stay in edit mode.
+
+**Not staying** — simplest, and correct for things like "replace all":
+
+```js
+itext.exitEditing();
+itext.set('text', newValue);
+canvas.requestRenderAll();
+```
+
+**Staying** — use the character APIs, which reflow `styles` properly, then sync the
+textarea by hand:
+
+```js
+function insertAtCaret(itext, str) {
+  const at = itext.selectionStart;
+  itext.insertChars(str, undefined, at, itext.selectionEnd);
+
+  // keep the textarea in step, or the next keystroke reverts this
+  if (itext.hiddenTextarea) {
+    itext.hiddenTextarea.value = itext.text;
+  }
+  itext.selectionStart = itext.selectionEnd = at + str.length;
+  itext._updateTextarea();
+
+  itext.fire('changed');
+  itext.canvas?.fire('text:changed', { target: itext });
+  itext.canvas?.requestRenderAll();
+}
+```
+
+`insertChars` and `removeChars` do not fire `changed` themselves, which is why the
+example does it — otherwise your autosave and undo stack never hear about the edit.
+`_updateTextarea` is internal but it is the only route to re-syncing the selection,
+and Fabric.js itself uses it for exactly this purpose in its drag-and-drop code.
+
+## Undo and redo
+
+Fabric.js has none. There is no history, and Ctrl+Z is not bound — which also means
+the browser's own textarea undo can fire and produce a partial, style-less undo you
+did not ask for. Intercept it:
+
+```js
+itext.keysMap = { ...itext.keysMap }; // clone: maps are shared process-wide
+// then handle Ctrl+Z yourself in a keydown listener on the textarea,
+// or override onKeyDown in a subclass
+```
+
+Build the history on `changed`, snapshotting `toObject()`. Snapshot on a debounce
+rather than per keystroke, or your history will have one entry per character:
+
+```js
+let timer;
+itext.on('changed', () => {
+  clearTimeout(timer);
+  timer = setTimeout(() => history.push(itext.toObject()), 400);
+});
+```
+
+Restore by exiting editing, applying the snapshot, and re-entering if you want to
+keep the session — restoring mid-edit runs into the textarea problem above.
+
+Remember that `toObject()` compresses `styles` into ranges, so a custom style
+property will not survive the round trip. See
+[serializing and exporting text](/docs/text/serializing-text).
+
+## Floating toolbars
+
+To position a toolbar over the text, use the object's bounding rect in viewport
+coordinates and add the canvas offset:
+
+```js
+function toolbarPosition(itext) {
+  const r = itext.getBoundingRect();      // already viewport space
+  const rect = canvas.getElement().getBoundingClientRect();
+  return { left: rect.left + r.left, top: rect.top + r.top - 44 };
+}
+```
+
+Recompute on `selection:changed`, `changed`, `object:modified` and on canvas
+zoom or pan. And make sure the bounding rect is fresh — after a style change that
+means `initDimensions()` then `setCoords()` first, as above.
+
+## One editor at a time
+
+Entering editing on one text object silently exits any other on the same canvas,
+firing its exit events — including `object:modified` if the text changed. If you
+persist on `object:modified`, expect it to arrive as a side effect of the user
+clicking into a *different* text object, not only when they click away entirely.
+
+Objects on separate canvases can both be editing, and will fight over focus and
+over the shared clipboard channel. If your app has multiple canvases, exit editing
+explicitly when one loses attention.
+
+## Mobile
+
+Focusing the hidden textarea is what raises the soft keyboard, so basic typing
+works. Two rough edges:
+
+- The textarea is styled at a 1px font size, well under the threshold at which iOS
+  Safari suppresses zoom-on-focus, so expect the viewport to zoom when editing
+  begins. Mitigate with a viewport meta tag; there is no library-side fix.
+- The textarea's position is computed from a cached canvas offset that is refreshed
+  on window resize but **not on scroll**. Scroll the page mid-edit and the invisible
+  textarea drifts, which on mobile means the OS scrolls the wrong area into view and
+  IME candidate windows appear in the wrong place. Fix it yourself:
+
+```js
+window.addEventListener('scroll', () => canvas.calcOffset(), { passive: true });
+```
+
+## Accessibility
+
+Be clear-eyed about this: canvas text editing in Fabric.js is not accessible as
+shipped. The hidden textarea carries no label, no ARIA attributes and no role, and
+there is no keyboard route into editing at all — `enterEditing` is reachable only
+from pointer events or your own code.
+
+If accessibility is a requirement, plan for it at the application level: provide a
+keyboard-accessible way to enter editing, expose the text content in an
+accompanying DOM structure, and consider whether a canvas editor is the right
+choice for the content in question. A `<textarea>` overlay synced to the canvas is
+sometimes the more honest answer.
+
+## Editing while other things happen
+
+A few interactions worth testing early, since each has a real cause:
+
+- **Setting object properties mid-edit.** Writes to `selectable`, `hasControls`,
+  `borderColor`, `lockMovementX`, `lockMovementY` and `hoverCursor` are stashed and
+  applied on exit, so they look like no-ops while editing.
+- **The caret disappearing.** It is drawn on the canvas's top context; anything
+  else that clears that context wipes it until the next blink.
+- **Exporting.** `toCanvasElement` hides the caret for you, but a custom export
+  path that bypasses it will bake the caret into the image.
+- **Disposal.** `canvas.dispose()` tears editing down without firing exit events, so
+  do not rely on `editing:exited` for cleanup.
diff --git a/src/content/docs/docs/Text/editing.mdx b/src/content/docs/docs/Text/editing.mdx
new file mode 100644
index 00000000..62edda02
--- /dev/null
+++ b/src/content/docs/docs/Text/editing.mdx
@@ -0,0 +1,251 @@
+---
+date: '2026-07-30'
+title: 'Editing text'
+description: 'The IText editing lifecycle, selection, keyboard input and events'
+sidebar:
+  order: 350
+---
+
+import { CodeEditor } from '../../../../components/CodeEditor';
+import code from './editing/code.js?raw';
+
+`IText` and `Textbox` bring a full editing experience: a blinking caret, mouse
+selection, keyboard input, IME composition, clipboard and drag-and-drop. This page
+covers how that machinery works and how to drive it yourself.
+
+Open the console and interact with the text below to watch the events fire.
+
+<CodeEditor code={code} canvasId="text-editing" client:idle canvasDown>
+  <canvas width="600" height="260" id="text-editing"></canvas>
+</CodeEditor>
+
+## Entering and exiting
+
+Editing is a mode the object is in, tracked by `isEditing`, and gated by
+`editable` (default `true`).
+
+```js
+text.enterEditing();
+text.isEditing; // true
+text.exitEditing();
+```
+
+By default it takes **two clicks** to start editing: the first selects the object,
+the second enters editing. That is deliberate — it lets a user move a text object
+without falling into edit mode — and it is not controlled by a flag. For
+single-click editing, call `enterEditing()` yourself:
+
+```js
+canvas.on('mouse:down', ({ target }) => {
+  if (target instanceof fabric.IText) {
+    canvas.setActiveObject(target);
+    target.enterEditing();
+  }
+});
+```
+
+Two asymmetries to know about. `enterEditing()` does nothing if the object is
+already editing or is not `editable`, but **`exitEditing()` has no such guard** —
+calling it when not editing re-fires the exit events, and can fire `modified` a
+second time. Guard your own calls:
+
+```js
+if (text.isEditing) {
+  text.exitEditing();
+}
+```
+
+**Only one object per canvas can be editing.** Entering editing on one text
+silently exits any other, including firing its `editing:exited` and possibly
+`object:modified`. Objects on *different* canvases can edit simultaneously, and
+will then compete for keyboard focus.
+
+Editing an object inside a `Group` requires `group.interactive = true`.
+
+## Events
+
+Object-level events, in the order they fire:
+
+| Event | Payload | When |
+| --- | --- | --- |
+| `editing:entered` | `{ e }` if from a pointer event, otherwise nothing | Editing began |
+| `selection:changed` | none | Caret or selection moved |
+| `changed` | none while typing; `{ index, action }` on drop or drag-out | Text content changed |
+| `editing:exited` | none | Editing ended |
+| `modified` | none | On exit, only if the text actually changed |
+
+Canvas-level equivalents, all carrying `{ target }`:
+
+`text:editing:entered`, `text:selection:changed`, `text:changed`,
+`text:editing:exited`, and `object:modified` (again, only when the text changed).
+
+```js
+canvas.on('text:changed', ({ target }) => {
+  save(target.toObject());
+});
+```
+
+Note that the canvas-level `text:editing:entered` arrives *after* the object's
+`selection:changed`, so do not rely on the entered event being the first thing you
+see.
+
+One documentation bug worth flagging: `IText` claims to fire `copy`, `cut` and
+`paste`. **It does not** — those names are DOM listeners internally, and there is
+nothing to subscribe to.
+
+## Selection and the caret
+
+`selectionStart` and `selectionEnd` are **grapheme indices** into the text — not
+UTF-16 offsets. When they are equal you have a caret; when they differ, a
+selection.
+
+```js
+text.selectionStart = 0;
+text.selectionEnd = 5;
+```
+
+Assigning them directly, as above, changes nothing observable: no event, no
+textarea sync, no repaint. The setters do more:
+
+```js
+text.setSelectionStart(0);
+text.setSelectionEnd(5);
+```
+
+though be aware they fire `selection:changed` *before* storing the new value, so
+handlers observe the previous index. For a reliable selection change from your own
+code, set the fields and then ask for a repaint — the pattern in
+[building a text editing UI](/docs/text/editing-ui).
+
+Helpers worth knowing:
+
+- `getSelectedText()`
+- `selectAll()`, `selectWord(index)`, `selectLine(index)` — the latter two only act
+  while editing, which is why double-click and triple-click do nothing on a
+  non-editing object
+- `get2DCursorLocation(index, skipWrapping)` → `{ lineIndex, charIndex }`
+- `fromStringToGraphemeSelection` / `fromGraphemeToStringSelection` for converting
+  to and from string offsets
+
+**Mind the index space.** Two internal clamps compare grapheme indices against
+`text.length`, which is a UTF-16 length — for text containing emoji these differ,
+so out-of-range indices can slip through. Convert and clamp against the grapheme
+count yourself when handling untrusted positions.
+
+### Appearance
+
+| Property | Default |
+| --- | --- |
+| `cursorColor` | `''` — inherits the fill of the character before the caret |
+| `cursorWidth` | `2` |
+| `cursorDelay` | `1000` ms |
+| `cursorDuration` | `600` ms |
+| `selectionColor` | `'rgba(17,119,255,0.3)'` |
+| `editingBorderColor` | `'rgba(102,153,255,0.25)'` |
+
+The caret width is divided by the object scale and canvas zoom so it stays
+visually constant. Only the horizontal scale is compensated for, so a
+non-uniformly scaled text gets a slightly off caret.
+
+The caret and selection are drawn on the canvas's **top context**, not the main
+one. Anything else that clears that context — a group selection box, drawing mode,
+your own overlay — can wipe the caret until the next blink.
+
+## Keyboard input
+
+All keyboard handling flows through a hidden `<textarea>`; there are no document
+or canvas key listeners. That has one dominant consequence: **if the textarea
+loses focus, typing stops working**, and Fabric.js will not tell you.
+
+Fabric.js handles a deliberately small set of keys itself, through four maps:
+
+- `keysMap` — Tab and Escape exit editing; Home, End, Page Up, Page Down and the
+  four arrows move the caret
+- `keysMapRtl` — the same with left/right mirrored, used when `direction === 'rtl'`
+- `ctrlKeysMapDown` — Ctrl/Cmd+A selects all
+- `ctrlKeysMapUp` — Ctrl/Cmd+C and Ctrl/Cmd+X
+
+Everything else — printable characters, Enter, Backspace, Delete, Ctrl+V — is left
+to the textarea, and Fabric.js reconciles the result by diffing the textarea's
+value against its own text on every `input` event. That diff is also what keeps
+`styles` aligned with the new content.
+
+Modifiers extend caret movement: Alt moves by word, Cmd (or Home/End) by line, and
+Shift extends the selection.
+
+To rebind a key, **clone the map first** — the maps are shared between every text
+object in the process:
+
+```js
+text.keysMap = { ...text.keysMap };
+text.keysMap[13] = 'exitEditing'; // Enter now commits instead of inserting
+```
+
+Map values are method names looked up on the object, so you can add your own
+methods to the prototype and reference them by name. The maps are keyed by the
+legacy `keyCode`, which is layout-dependent; for anything beyond the basics,
+override `onKeyDown` in a subclass instead.
+
+Note that `keysMap` is consulted *before* the Ctrl maps and ignores modifiers, so
+an entry there shadows any Ctrl combination on the same key.
+
+There is one known bug in the default maps: Ctrl/Cmd+X is mapped to a method named
+`cut` that **does not exist**. Cut still works in practice, because the browser's
+native cut plus the input diff does the job before that entry is ever reached.
+
+## IME and composition
+
+Composition is supported: `inCompositionMode` is true while composing, during
+which Fabric.js leaves the selection alone, reads the textarea's own selection for
+rendering, and draws a thin underline instead of the selection band. Predictive
+text and autocorrect are switched off on the textarea, so mobile suggestion bars
+do not appear.
+
+`compositionColor` styles the composition underline, but note it has no default
+value and falls back to black regardless of your theme.
+
+## Clipboard
+
+Copy, cut and paste ride the native DOM events on the textarea. Per-character
+styles survive **within the same page** — Fabric.js keeps the copied styles in a
+module-level side channel and restores them if the pasted string is byte-identical
+to what was copied.
+
+Styles do **not** survive pasting from another tab, another window, after a reload,
+or from outside Fabric.js. In those cases the inserted text takes the style of the
+neighbouring character. Two bundles of Fabric.js on one page also do not share the
+channel.
+
+Copying records the *complete* style of every character, which inflates `styles`
+quickly. Consider `cleanStyle()` afterwards, or disable the behaviour globally:
+
+```js
+fabric.config.disableStyleCopyPaste = true;
+```
+
+## Drag and drop
+
+Dragging a selection out of a text object is supported and carries two payloads: a
+`text/plain` string, and an `application/fabric` payload containing the selected
+text plus its styles — so dragging between Fabric.js objects preserves formatting
+properly, unlike the clipboard.
+
+Dropping onto a text object inserts at the caret position under the pointer, with a
+live caret preview during the drag. Dragging text *out* to another object ends the
+source's editing session. Use the canvas `drop:before` event to rewrite the payload
+if you need to.
+
+## Programmatic changes while editing
+
+This deserves its own warning. While editing, the hidden textarea is the source of
+truth for the text content, and the next keystroke overwrites the object from it.
+So this does not stick:
+
+```js
+text.set('text', 'replaced'); // reverted on the next keypress
+```
+
+Use `insertChars` and `removeChars` and sync the textarea, or exit editing first.
+The full pattern, along with toolbar focus handling, undo/redo and the rest of the
+integration work, is in
+[building a text editing UI](/docs/text/editing-ui).
diff --git a/src/content/docs/docs/Text/editing/code.js b/src/content/docs/docs/Text/editing/code.js
new file mode 100644
index 00000000..28109a5a
--- /dev/null
+++ b/src/content/docs/docs/Text/editing/code.js
@@ -0,0 +1,25 @@
+const canvas = new fabric.Canvas(canvasEl);
+
+const text = new fabric.IText('Click once to select,\nagain to edit', {
+  fontSize: 28,
+  fill: '#334155',
+  // appearance of the editing session
+  cursorColor: '#7c3aed',
+  cursorWidth: 2,
+  selectionColor: 'rgba(124, 58, 237, 0.25)',
+  editingBorderColor: '#7c3aed',
+});
+
+canvas.add(text);
+canvas.centerObject(text);
+
+// Object level events
+text.on('editing:entered', () => console.log('editing:entered'));
+text.on('changed', () => console.log('changed →', text.text));
+text.on('selection:changed', () =>
+  console.log('selection', text.selectionStart, text.selectionEnd),
+);
+text.on('editing:exited', () => console.log('editing:exited'));
+
+// Canvas level events carry the target
+canvas.on('text:changed', ({ target }) => console.log('canvas saw', target.type));
diff --git a/src/content/docs/docs/Text/fonts.mdx b/src/content/docs/docs/Text/fonts.mdx
new file mode 100644
index 00000000..005d655a
--- /dev/null
+++ b/src/content/docs/docs/Text/fonts.mdx
@@ -0,0 +1,230 @@
+---
+date: '2026-07-30'
+title: 'Fonts: loading, measuring and caching'
+description: 'How Fabric.js measures text, why late-loading webfonts corrupt layout, and how to do it correctly'
+sidebar:
+  order: 330
+---
+
+If you ship a custom font, read this page before anything else. Getting the order
+of operations wrong does not produce a temporary flash of the wrong typeface — it
+permanently corrupts the measurements of every text object using that family, and
+nothing reports an error.
+
+## How Fabric.js measures text
+
+Fabric.js needs the width of every character to lay out a line, position a caret,
+draw a selection, and decide where a `Textbox` wraps. It gets those widths from
+`ctx.measureText()` on an offscreen canvas, and it caches them aggressively.
+
+Three facts about that cache drive everything else on this page:
+
+1. **It is global and lives as long as the page.** It is not per object, not per
+   canvas — a single module-level cache shared by everything.
+2. **Its key is the family name plus style and weight**, lowercased. Nothing else.
+3. **`fontSize` is not part of the key.** Every character is measured once at a
+   fixed 400px and scaled arithmetically to whatever size you asked for.
+
+That last point means metrics are assumed to scale linearly. Fonts with optical
+sizing or size-specific hinting will be very slightly off at small sizes.
+
+Widths are also measured in pairs to capture kerning, but only when both
+characters share an identical font declaration. Styling one character of a pair
+changes the measured width of its neighbour.
+
+## The failure mode
+
+A text object measures itself **synchronously, in its constructor**. So:
+
+```js
+// The font has been requested by CSS but has not arrived yet.
+const text = new fabric.IText('Hello', { fontFamily: 'Inter' });
+```
+
+At this moment the browser has no `Inter`, so it substitutes a fallback and
+`measureText` returns the fallback's widths. Fabric.js has no way to detect the
+substitution, and stores those widths **under the key `inter`**.
+
+When the font finishes loading, the glyphs repaint correctly — but the cached
+widths do not change, and neither does `text.width`. What you get is:
+
+- a bounding box and selection border that no longer fit the text
+- controls in the wrong place
+- a caret and selection rectangles that drift from the glyphs
+- underlines and text backgrounds of the wrong length
+- a `Textbox` that wraps in the wrong places
+
+And because the cache is global, **every text object created later with that
+family inherits the wrong widths**, including ones created long after the font
+loaded. The corruption outlives the page's loading phase.
+
+## Doing it correctly
+
+Load the font first, then create text. Fabric.js ships no font loader at all —
+there is no `loadFont` utility, no readiness promise, no font event. Use the
+browser's CSS Font Loading API:
+
+```js
+const font = new FontFace('Inter', "url(/fonts/inter.woff2) format('woff2')", {
+  weight: '400',
+  style: 'normal',
+});
+await font.load();
+document.fonts.add(font);
+
+// only now
+const text = new fabric.IText('Hello', { fontFamily: 'Inter' });
+```
+
+If the `@font-face` came from a stylesheet rather than JavaScript, ask for the
+exact face you need:
+
+```js
+await document.fonts.load('400 40px "Inter"');
+```
+
+Be careful with `document.fonts.ready`. It resolves when *pending* loads finish,
+and a face that nothing has requested yet is not pending — so awaiting it can
+resolve before your font has loaded at all. Request the face explicitly, as
+above.
+
+Load one face per weight and style you actually use. `bold` and `italic` are
+cached separately, and synthesised bold usually measures poorly.
+
+Fonts must also be loaded **before `loadFromJSON`**, because deserialising a text
+object runs the same measuring constructor.
+
+## Recovering from a late load
+
+If a font can arrive late — a user-supplied font, a font picker, a slow
+connection — you can repair the damage, but it takes four steps in this order:
+
+```js
+// 1. clear the poisoned widths for that family
+fabric.cache.clearFontCache('Inter');
+
+// 2. re-measure every object using it
+obj.initDimensions();
+
+// 3. force a repaint of the cached bitmap (required for Textbox)
+obj.dirty = true;
+
+// 4. refresh the interaction box
+obj.setCoords();
+
+canvas.requestRenderAll();
+```
+
+Both halves are necessary. Clearing the cache alone does nothing, because the
+object keeps its own copy of the measurements. Calling `initDimensions()` alone
+does nothing either, because it re-reads the same poisoned cache. And the order
+matters — clear first.
+
+Step 3 is easy to miss: `FabricText.initDimensions()` marks the object dirty for
+you, but **`Textbox` overrides the method and does not**. Since a width-only
+change does not alter a Textbox's height, the cached bitmap can otherwise be
+reused and you keep seeing stale glyphs. Set `dirty` yourself.
+
+`clearFontCache()` with no argument empties the whole cache, which is the safe
+option if you are not sure which families are affected. With an argument it
+matches case-insensitively but needs the **exact family string** you put on the
+object.
+
+Objects inside a `Group` need the group's layout re-run afterwards, and remember
+that a family can also appear in per-character `styles`, not just in
+`obj.fontFamily`.
+
+## Family name discipline
+
+The cache key is the whole string, so `'Inter'` and `'Inter, sans-serif'` are two
+unrelated entries — clearing one leaves the other stale. Pick one form and use it
+everywhere.
+
+Prefer a **bare family name with no comma and no quotes**. It keeps the cache
+predictable, lets Fabric.js quote the name correctly for the canvas, and avoids
+two separate SVG export problems:
+
+- A per-character `fontFamily` containing a comma is exported wrapped in a single
+  pair of quotes, turning `Arial, sans-serif` into one bogus family name. Per
+  character font *stacks* do not survive SVG export.
+- Family names containing any of `;` `<` `>` `\`, or sequences like `url(` or
+  `data:`, are stripped from SVG span styles by a sanitiser and vanish silently.
+
+If you need fallbacks, keep them out of the property and handle them at the font
+loading level.
+
+## SVG export
+
+An exported SVG references fonts by name; it does not embed them. Fabric.js can
+emit `@font-face` rules pointing at URLs you supply, but **only for families you
+register yourself**:
+
+```js
+fabric.config.addFonts({ Inter: '/fonts/inter.woff2' });
+```
+
+`config.fontPaths` — and `addFonts`, `removeFonts`, `clearFonts` — affect **SVG
+export only**. They are not a loader and have no effect on canvas rendering or
+measurement, which is a common misreading of the API.
+
+Two sharp edges when you use it:
+
+- The lookup is exact and case-sensitive, so a `fontFamily` of `'Inter, sans-serif'`
+  will not match a registration of `Inter`.
+- If an object's own `fontFamily` is not registered, the per-character fonts on
+  that object are skipped too — so register the base family even when you only
+  care about styled runs.
+
+Because Fabric.js bakes absolute positions into every exported text run, an SVG
+opened without the right font shows substituted glyphs at Fabric's original
+positions. Single-run text degrades tolerably; heavily styled text does not.
+
+## SVG import
+
+Do not rely on it for fonts. `@font-face` rules inside an imported SVG are
+ignored, SVG font elements are ignored, and `font-variant` is dropped. Import
+gives you a family *name* and nothing that makes it available — so load the font
+yourself and re-measure afterwards.
+
+One concrete hazard: a `font-family` whose name starts with a digit is parsed as a
+number and throws during import, taking the whole document with it. Sanitise
+untrusted SVG before loading it.
+
+## Node and server-side rendering
+
+In Node there is no CSS Font Loading API. Fonts come from `node-canvas`:
+
+```js
+const { registerFont } = require('canvas');
+registerFont('./fonts/inter.woff2', { family: 'Inter', weight: '400' });
+```
+
+Register **every** family, weight and style **at process start, before creating
+any canvas or text object**. `fabric.config.addFonts` does not help here — it only
+writes SVG markup.
+
+Also worth knowing: Fabric's default `fontFamily` is `Times New Roman`, which
+frequently does not exist on a Linux container. You will silently get whatever
+fontconfig substitutes, and your server render will not match the browser. Set a
+default you actually ship:
+
+```js
+fabric.FabricText.ownDefaults.fontFamily = 'Inter';
+```
+
+Complex-script shaping and colour emoji depend on the `node-canvas` build and
+will not match a browser exactly, so do not expect pixel parity for those.
+
+## Checklist
+
+1. Await the specific faces (family + weight + style) before creating any text.
+2. Use one canonical family string everywhere; prefer a bare name.
+3. Use only valid CSS `fontWeight` and `fontStyle` values.
+4. Load fonts before `loadFromJSON`.
+5. If a font can load late: `clearFontCache(family)` → `initDimensions()` →
+   `dirty = true` → `setCoords()` → render.
+6. For SVG export, `config.addFonts` every family, including base families of
+   objects with styled runs.
+7. In Node, `registerFont` everything up front and override the default family.
+8. In a long-lived editor that lets users try many fonts, clear unused families
+   occasionally — the cache grows without bound and never expires.
diff --git a/src/content/docs/docs/Text/layout-and-appearance.mdx b/src/content/docs/docs/Text/layout-and-appearance.mdx
new file mode 100644
index 00000000..8ef5157f
--- /dev/null
+++ b/src/content/docs/docs/Text/layout-and-appearance.mdx
@@ -0,0 +1,164 @@
+---
+date: '2026-07-30'
+title: 'Text layout and appearance'
+description: 'Fonts, spacing, alignment and decorations on a text object'
+sidebar:
+  order: 320
+---
+
+import { CodeEditor } from '../../../../components/CodeEditor';
+import code from './layout-and-appearance/code.js?raw';
+
+Every property on this page belongs to `FabricText`, so it works the same on
+`IText` and `Textbox`. All of them can be set in the constructor or later with
+`set()` — and only with `set()`, as
+[choosing a class](/docs/text/choosing-a-class) explains.
+
+<CodeEditor code={code} canvasId="text-appearance" client:idle canvasDown>
+  <canvas width="480" height="260" id="text-appearance"></canvas>
+</CodeEditor>
+
+## Font
+
+| Property | Default | Notes |
+| --- | --- | --- |
+| `fontFamily` | `'Times New Roman'` | A CSS family name. Quoted automatically unless it already contains a quote or a comma |
+| `fontSize` | `40` | In pixels |
+| `fontWeight` | `'normal'` | `'normal'`, `'bold'`, or a number like `700` |
+| `fontStyle` | `'normal'` | `'normal'`, `'italic'`, `'oblique'` |
+
+These four are assembled into a canvas `font` string. That has a consequence
+worth knowing: **a value the browser cannot parse invalidates the whole
+declaration**, and canvas silently ignores an invalid `font`. A `fontWeight` of
+`'demibold'` does not fall back to normal — it leaves the previous font in
+effect, so your text is measured *and* drawn with the wrong typeface and nothing
+reports an error. Stick to real CSS values.
+
+There is no `fontVariant` or `fontStretch`, and no small-caps.
+
+Custom families need care beyond naming them: see [fonts](/docs/text/fonts).
+
+## Spacing
+
+**`lineHeight`** (default `1.16`) is a multiplier, not a pixel value.
+
+**`charSpacing`** (default `0`) is in **thousandths of an em**, which surprises
+everyone the first time. To add one em of space between characters you write
+`charSpacing: 1000`; a subtle tracking adjustment is more like `20`.
+
+```js
+text.set('charSpacing', 40); // ≈ 0.04em
+```
+
+Two caveats. `charSpacing` is computed from the object's `fontSize` even for
+characters that carry their own `fontSize` in `styles`, so a 12px character
+inside a 40px text gets 40px-scale letter spacing. And any non-zero value forces
+Fabric.js to draw the line character by character instead of in one call, which
+costs performance and loses ligatures and contextual shaping.
+
+### How height is actually computed
+
+This catches people building vertical layouts. A line's box is
+`fontSize × 1.13`, and only the gaps *between* lines are multiplied by
+`lineHeight` — the last line contributes no gap. So a single-line text at
+`fontSize: 40` is **45.2** tall, not `40 × 1.16`:
+
+```js
+new fabric.FabricText('one line', { fontSize: 40 }).height; // 45.2
+```
+
+The `1.13` factor is `_fontSizeMult`, and the baseline sits at
+`_fontSizeFraction` (`0.222`) inside the box. Both are overridable, but they are
+internal names — treat them as such.
+
+Note also that Fabric.js only ever measures glyph *widths*. Line height comes
+from the arithmetic above, never from the font's own ascent and descent metrics.
+If your design needs metric-accurate line boxes, you have to compute them
+yourself.
+
+## Alignment
+
+`textAlign` (default `'left'`) accepts `'left'`, `'center'`, `'right'`,
+`'justify'`, and three hybrids: `'justify-left'`, `'justify-center'`,
+`'justify-right'`.
+
+The hybrids justify every line *except* the last one, which is aligned normally
+instead — the usual typographic convention, since justifying a short final line
+looks broken. Plain `'justify'` treats the last line as left-aligned.
+
+Justification works by widening the spaces in a line after measurement. A side
+effect: the per-character boxes reflect the justified positions while the cached
+line width does not, so do not mix the two when computing your own overlays.
+
+There is **no vertical alignment** in Fabric.js — no `verticalAlign`, on any of
+the three classes. Text is always vertically centred in its own bounding box, and
+you position the object yourself.
+
+## Direction
+
+`direction` accepts `'ltr'` (default) and `'rtl'`, but the source marks it
+**experimental and explicitly not supported yet**, and it is worth taking that at
+face value: measurement is always performed left-to-right regardless of the
+setting, and setting `direction` does not re-measure. RTL and bidirectional text
+are not in a shippable state — plan around it rather than on it.
+
+## Decorations
+
+`underline`, `overline` and `linethrough` are booleans (default `false`). In
+older versions of Fabric.js this was a single `textDecoration` string; that API
+is gone.
+
+```js
+text.set({ underline: true, linethrough: false });
+```
+
+They are not real font decorations — Fabric.js draws them as filled rectangles at
+fixed fractions of the font size. Two properties tune them:
+
+- **`textDecorationThickness`** (default `66.667`) is in thousandths of an em,
+  like `charSpacing`. It is not a pixel value, which is worth remembering if you
+  expose it in a UI.
+- **`textDecorationColor`** is unset by default and falls back to the character's
+  `fill`. **Set it explicitly if your text has a gradient or pattern fill** —
+  the fallback assigns the fill object straight to the drawing context, which
+  silently leaves the previous colour in place and paints the wrong one.
+
+A thick decoration can also extend past the object's bounding box and get clipped
+by the render cache.
+
+## Backgrounds
+
+There are two, and they are different:
+
+- **`backgroundColor`** — inherited from `FabricObject`, fills the whole bounding box.
+- **`textBackgroundColor`** — fills only behind the glyphs, line by line, and can
+  be set per character through `styles`.
+
+```js
+text.set('textBackgroundColor', '#fef08a');
+```
+
+One real gotcha: **`textBackgroundColor` removes the object's shadow.** Drawing
+the text background clears the shadow from the context and does not restore it,
+so a text with both loses the shadow entirely. If you need both, put the shadow
+on a separate object underneath.
+
+## Text on a path
+
+`path`, `pathStartOffset`, `pathSide` and `pathAlign` bend text along a `Path`.
+It is a beta feature with real limitations — single line only, no justification —
+and has its own page: [text on a path](/docs/text/text-on-a-path).
+
+## Setting defaults for every text object
+
+To change these globally, assign to `ownDefaults` rather than repeating options
+at every call site. Note that the three classes have separate defaults, so a
+value set on `FabricText` does not reach `IText` or `Textbox` if those already
+declare their own:
+
+```js
+fabric.FabricText.ownDefaults.fontFamily = 'Helvetica';
+```
+
+See [configuring defaults](/docs/configuring-defaults) for how `ownDefaults`
+resolves across the class hierarchy.
diff --git a/src/content/docs/docs/Text/layout-and-appearance/code.js b/src/content/docs/docs/Text/layout-and-appearance/code.js
new file mode 100644
index 00000000..2bdab15d
--- /dev/null
+++ b/src/content/docs/docs/Text/layout-and-appearance/code.js
@@ -0,0 +1,18 @@
+const canvas = new fabric.Canvas(canvasEl);
+
+const text = new fabric.FabricText('Layout\nand appearance', {
+  fontFamily: 'Helvetica',
+  fontSize: 34,
+  lineHeight: 1.16,
+  charSpacing: 0,
+  textAlign: 'left',
+  underline: false,
+  fill: '#334155',
+});
+
+canvas.add(text);
+canvas.centerObject(text);
+
+// Try editing the values above and watch the bounding box change. Note that
+// `height` is not fontSize * lineHeight * lineCount — see the page below.
+console.log('width', text.width, 'height', text.height);
diff --git a/src/content/docs/docs/Text/serializing-text.mdx b/src/content/docs/docs/Text/serializing-text.mdx
new file mode 100644
index 00000000..9c5abf73
--- /dev/null
+++ b/src/content/docs/docs/Text/serializing-text.mdx
@@ -0,0 +1,212 @@
+---
+date: '2026-07-30'
+title: 'Serializing and exporting text'
+description: 'JSON round-trips, style compression and what SVG export and import can and cannot carry'
+sidebar:
+  order: 390
+---
+
+Text serialises like any other object, with one twist: the `styles` structure is
+stored in a different shape from the one you work with at runtime.
+
+## JSON round-trip
+
+```js
+const json = canvas.toJSON();
+await canvas.loadFromJSON(json);
+```
+
+Per-object:
+
+```js
+const data = text.toObject();
+const restored = await fabric.IText.fromObject(data);
+```
+
+**Load fonts before deserialising.** `fromObject` constructs a text object, and
+construction measures the glyphs — so a font that has not arrived yet poisons the
+measurement cache exactly as described in [fonts](/docs/text/fonts). This is the
+most common way the font bug reaches production: the fonts are loaded correctly on
+the authoring path and forgotten on the restore path.
+
+## The two shapes of styles
+
+At runtime `styles` is a nested map of line → character → declaration. Serialised,
+it becomes a flat array of ranges over the whole text:
+
+```js
+// runtime
+text.styles = { 0: { 0: { fontWeight: 'bold' }, 1: { fontWeight: 'bold' } } };
+
+// serialized
+[{ start: 0, end: 2, style: { fontWeight: 'bold' } }]
+```
+
+`start` is inclusive, `end` exclusive, and indices are graphemes counted across the
+whole text with newlines included. Conversion happens automatically in both
+directions, and the loader accepts either shape — so handing it a runtime-style
+nested object also works, which is a useful escape hatch.
+
+The compression is why the round trip is not perfectly lossless.
+
+### What compression drops
+
+Adjacent characters are merged into one range when their **fourteen known
+styleable properties** match. Only the first character's declaration is kept.
+
+So if you added a custom style property — see
+[styling individual characters](/docs/text/character-styles) — and it varies between
+two characters that agree on all fourteen known properties, that variation is
+**silently discarded by `toObject()`**:
+
+```js
+new fabric.FabricText('abcd', {
+  styles: { 0: { 0: { fontWeight: 'bold', mine: 'x' },
+                 1: { fontWeight: 'bold', mine: 'y' } } },
+}).toObject().styles;
+// [{ start: 0, end: 2, style: { fontWeight: 'bold', mine: 'x' } }]  ← 'y' is gone
+```
+
+Worse, a declaration containing **only** unknown properties can make `toObject()`
+throw outright, because no range has been opened for it to extend:
+
+```js
+new fabric.FabricText('abcd', {
+  styles: { 0: { 0: { mine: 'x' } } },
+}).toObject();
+// TypeError: Cannot read properties of undefined (reading 'end')
+```
+
+So a custom property must never be the only thing in a declaration, and must not be
+relied on to vary independently.
+
+If you rely on custom style properties, serialise `styles` yourself:
+
+```js
+class MyText extends fabric.IText {
+  toObject(propertiesToInclude = []) {
+    return {
+      ...super.toObject(propertiesToInclude),
+      styles: fabric.util.cloneDeep(this.styles), // uncompressed
+    };
+  }
+}
+```
+
+The loader accepts the nested form, so no matching `fromObject` work is needed.
+
+### Normalise line endings
+
+There is an asymmetry to be aware of: the two directions of style conversion split
+lines slightly differently — one on `\n` only, the other on `\r\n` as well. Text
+containing Windows line endings therefore comes back with its styles **shifted by
+one character per line**:
+
+```js
+const text = new fabric.FabricText('ab\r\ncd', {
+  styles: { 1: { 0: { fill: 'red' } } }, // second line, first character
+});
+const restored = await fabric.FabricText.fromObject(text.toObject());
+restored.styles; // { 1: { 1: { fill: 'red' } } }  ← moved to the second character
+```
+
+With `\n` the same round trip is exact.
+
+Normalise on the way in and the problem disappears:
+
+```js
+text.set('text', input.replace(/\r\n/g, '\n'));
+```
+
+This is worth doing regardless: a lone `\r` is not treated as a line break but is
+still measured and treated as whitespace for justification.
+
+### Other notes
+
+- `fill` values that are `Gradient` or `Pattern` instances are shared rather than
+  deep-copied during style cloning.
+- `Textbox` serialises `minWidth` and `splitByGrapheme` in addition to the usual
+  properties. `width` round-trips, so wrapping is reproduced — but font metrics
+  differ between environments, so the resulting line breaks are not guaranteed to be
+  identical on another machine.
+- `deltaY`, `superscript`, `subscript` and `offsets` are **not** serialised at the
+  object level. Superscript survives only because it is expressed as per-character
+  `fontSize` and `deltaY` inside `styles`.
+
+## SVG export
+
+```js
+const svg = canvas.toSVG();
+```
+
+Text becomes a `<text>` element containing one `<tspan>` per style run, with
+`xml:space="preserve"` and `white-space: pre`.
+
+The important structural fact: **every `tspan` carries absolute `x` and `y`
+coordinates**, computed from Fabric's own measurements. There is no `text-anchor`
+and no reliance on the consumer's layout — alignment is baked into the numbers.
+
+That makes export predictable, and also fragile in one specific way. If the viewer
+does not have your font, glyphs are substituted but the run positions stay exactly
+where Fabric put them. A single unstyled run degrades acceptably; heavily styled
+text shows gaps and overlaps at every run boundary. Embedding the font via
+`config.addFonts` is the fix — see [fonts](/docs/text/fonts).
+
+More things that are worth knowing before you rely on exported SVG:
+
+- **One `tspan` per character** when `charSpacing` is non-zero or a path is set.
+  Output size grows accordingly.
+- **Decorations are handed to the consumer**, as CSS `text-decoration`, rather than
+  drawn as the rectangles Fabric.js uses on canvas. Position and thickness will not
+  match your canvas rendering exactly. `text-decoration-thickness` is emitted as a
+  percentage, which is patchily supported, and `text-decoration-color` is not
+  supported by all major browsers.
+- **Per-character font stacks break.** A comma-containing `fontFamily` in a style is
+  quoted as a single family name. Use bare family names.
+- **Style values are sanitised.** A family name containing characters like `;`, `<`
+  or `>` is dropped from the span style silently, and the character falls back to the
+  parent font.
+- **Text on a path** exports as individually rotated characters, not `<textPath>`.
+
+## SVG import
+
+Import is considerably weaker than export, and it is important not to assume symmetry:
+
+```js
+const { objects } = await fabric.loadSVGFromString(svg);
+```
+
+What is lost:
+
+- **All per-character styles.** Child `<tspan>` elements are not read — only the
+  combined text content — so an SVG that Fabric.js exported with rich styling
+  re-imports as uniformly styled text.
+- **Line structure.** Whitespace is collapsed, so multi-line SVG text arrives as a
+  single line.
+- **`@font-face` and SVG fonts** are ignored entirely; you get a family name and
+  nothing that makes it available.
+- `font-variant`, `textLength`, `writing-mode`, `dx`/`dy` lists and `textPath` are
+  all unsupported.
+
+What is read: `font-family`, `font-style`, `font-weight`, `font-size`,
+`letter-spacing` (converted into `charSpacing`), `text-decoration` and
+`text-anchor`, plus the `font` shorthand. Missing `font-size` defaults to 16.
+
+One hazard with untrusted input: a `font-family` whose name begins with a digit is
+parsed as a number and throws, failing the whole import. Sanitise before loading.
+
+If you need faithful round-trips, use Fabric's own JSON rather than SVG. SVG is a
+good export target and a lossy import format.
+
+## Exporting to an image
+
+```js
+const dataUrl = canvas.toDataURL({ format: 'png', multiplier: 2 });
+const el = text.toCanvasElement({ multiplier: 2 });
+```
+
+`toCanvasElement` hides the editing caret for you, so exporting mid-edit is safe. A
+custom export path that bypasses it will bake the caret into the output.
+
+Rasterised text is exactly as good as the measurements behind it, so — one last
+time — make sure the fonts were loaded before the text objects were created.
diff --git a/src/content/docs/docs/Text/text-on-a-path.mdx b/src/content/docs/docs/Text/text-on-a-path.mdx
new file mode 100644
index 00000000..606ca5de
--- /dev/null
+++ b/src/content/docs/docs/Text/text-on-a-path.mdx
@@ -0,0 +1,112 @@
+---
+date: '2026-07-30'
+title: 'Text on a path'
+description: 'Bending text along a Path, and the limits of the beta feature'
+sidebar:
+  order: 380
+---
+
+A text object can follow a `Path` instead of a straight baseline. The feature is
+marked **beta** in the source, and the limits below are real — read them before
+designing around it.
+
+## Using it
+
+Give the text a `path`:
+
+```js
+const path = new fabric.Path('M 0 0 Q 150 -100 300 0', {
+  fill: '',
+  stroke: '',
+  visible: false,
+});
+
+const text = new fabric.FabricText('Text along a curve', {
+  path,
+  fontSize: 28,
+  top: 100,
+  left: 100,
+});
+```
+
+Each character is placed and rotated along the curve. The path is *part of* the
+text object — it is drawn with its own `fill` and `stroke`, so set `visible: false`
+(or clear both paint properties) if you only want the text.
+
+Four properties control the arrangement:
+
+| Property | Default | Behaviour |
+| --- | --- | --- |
+| `path` | `undefined` | The `Path` to follow |
+| `pathStartOffset` | `0` | Distance along the path where the text begins, in pixels |
+| `pathSide` | `'left'` | `'right'` flips the text to the other side of the curve |
+| `pathAlign` | `'baseline'` | How glyphs sit relative to the path: `'baseline'`, `'center'`, `'ascender'`, `'descender'` |
+
+`textAlign` also works — `'left'`, `'center'` and `'right'` position the text along
+the path.
+
+## Attach the path through the constructor or set()
+
+This is the trap that catches everyone:
+
+```js
+text.path = myPath;        // breaks rendering
+text.set('path', myPath);  // correct
+```
+
+Attaching a path requires precomputing information about its segments, and that
+only happens in the constructor or through `set()`. With a directly assigned path,
+the character positions are never computed while the renderer still takes the
+path-drawing branch — you get flat, unrotated, mispositioned text, and the object's
+size is wrong too.
+
+The same applies to changing the path's shape later: re-run `set('path', path)` (or
+call `setPathInfo()`) after modifying the path data.
+
+## What is not supported
+
+**Single line only.** Every line is positioned from the start of the path
+independently, so a text containing `\n` draws all of its lines **on top of each
+other**. There is no per-line offset. Use one text object per line, each with its
+own path.
+
+**No justification.** `textAlign: 'justify'` and its variants silently do nothing on
+a path.
+
+**No wrapping.** `Textbox` overrides the layout that handles paths, so combining
+wrapping with a path is not a supported combination.
+
+**No SVG `<textPath>`.** Export emits individually positioned and rotated
+characters rather than a `textPath` element — visually close, but not editable as
+text-on-a-path by other tools, and the path itself is exported separately. SVG
+*import* of `textPath` is not implemented at all.
+
+**RTL is not handled** in the path rendering branch.
+
+## Other things to know
+
+- **The bounding box becomes the path's bounding box.** Glyphs that ride outside it
+  fall outside the selection box, and can be clipped by the object's render cache.
+- **Text longer than the path wraps around it**, overlapping its own beginning,
+  rather than being truncated.
+- **The path's own transform is ignored** for layout. Scaling, rotating or moving the
+  `Path` object does not move the text; scale the text object or rebuild the path
+  data instead.
+- **Underlines need a fill.** Decorations on a path are skipped for characters with
+  no `fill`, so outline-only text loses them.
+- **Character positions are computed lazily** on the first render with a path, not at
+  construction — so reading per-character geometry immediately after creating the
+  object gives you nothing.
+- `textBackgroundColor` rectangles are placed without accounting for `pathAlign`, so
+  they drift vertically for non-baseline alignments.
+
+## When to reach for it
+
+It works well for what it was built for: a single line of display text along a
+gentle curve, sized to fit. For anything more — multi-line text on a path,
+justified text on a path, or round-tripping through SVG — you will be fighting the
+implementation, and building the layout yourself with one object per glyph is
+usually less work.
+
+There is a [text on path demo](/demos/text-on-path) showing it fitted to a
+user-drawn path.
diff --git a/src/content/docs/docs/Text/textbox-wrapping.mdx b/src/content/docs/docs/Text/textbox-wrapping.mdx
new file mode 100644
index 00000000..d3f81f26
--- /dev/null
+++ b/src/content/docs/docs/Text/textbox-wrapping.mdx
@@ -0,0 +1,178 @@
+---
+date: '2026-07-30'
+title: 'Wrapping text with Textbox'
+description: 'How Textbox decides where to break lines, and how width, scaling and styles interact'
+sidebar:
+  order: 360
+---
+
+import { CodeEditor } from '../../../../components/CodeEditor';
+import code from './textbox-wrapping/code.js?raw';
+
+`Textbox` extends `IText`, so everything in [editing text](/docs/text/editing)
+applies. What it adds is a fixed `width` that text wraps inside, and a `height`
+derived from the result.
+
+<CodeEditor code={code} canvasId="textbox-wrapping" client:idle canvasDown>
+  <canvas width="600" height="280" id="textbox-wrapping"></canvas>
+</CodeEditor>
+
+## How wrapping works
+
+The algorithm is **greedy first-fit**, one pass, no look-ahead:
+
+1. Split the text into logical lines on `\n`.
+2. Split each logical line into words (or into graphemes, with `splitByGrapheme`).
+3. Measure every word.
+4. Fill a line word by word; when the next word would exceed the width, start a new
+   line.
+5. Set `height` from the resulting line count.
+
+There is no Knuth–Plass style optimisation, no hyphenation, no soft-hyphen support
+and no awareness of the Unicode line-breaking rules. Word boundaries are spaces,
+tabs and carriage returns — nothing else.
+
+Two consequences fall directly out of this:
+
+- **A word wider than the box is never broken.** Instead the box widens to fit it.
+- **Chinese, Japanese and Korean text does not wrap at all** with the default
+  settings, because it contains no spaces — the whole paragraph is one "word".
+  That is what `splitByGrapheme` is for.
+
+## Properties
+
+| Property | Default | Behaviour |
+| --- | --- | --- |
+| `width` | `0` | The wrapping width. Setting it re-wraps |
+| `splitByGrapheme` | `false` | Break anywhere rather than at word boundaries |
+| `dynamicMinWidth` | computed | Output, not input: the width of the widest unbreakable word |
+| `minWidth` | `20` | **Currently inert** — nothing in the library reads it |
+
+### width
+
+`width` is the wrap target and must be changed through `set()`:
+
+```js
+box.set('width', 320); // re-wraps and recomputes height
+box.width = 320;       // does not re-wrap
+```
+
+If you create a `Textbox` without a width it gets `0` and then sizes itself to its
+widest word.
+
+### dynamicMinWidth
+
+This is the floor that surprises people. If you set a `width` narrower than the
+widest single word, the box silently snaps back up to fit that word — so a width
+slider appears to "stick" at a minimum you did not choose. Read
+`box.dynamicMinWidth` if you want your UI to reflect the real lower bound, or
+enable `splitByGrapheme` so long words can be broken.
+
+### splitByGrapheme
+
+```js
+box.splitByGrapheme = true;
+box.initDimensions(); // required — see below
+```
+
+Note that unlike `width`, **`splitByGrapheme` is not one of the properties that
+triggers re-wrapping**, so `set()` will not re-flow the text on its own. Call
+`initDimensions()` after changing it.
+
+## Height is not yours
+
+`height` is recomputed from the wrapped line count on every layout pass. An
+assigned height is not rejected outright — it survives until the next re-wrap and
+is then overwritten, which makes it look like it worked right up until the user
+edits the text:
+
+```js
+box.set('height', 400);
+box.height;          // 400, for now
+
+box.set('width', 300); // any layout pass...
+box.height;            // ...and it is back to whatever the text needs
+```
+
+Treat `height` as read-only output.
+
+There is **no fixed-height mode** — no overflow, no clipping, no ellipsis, no
+max-lines, and no shrink-to-fit. A `Textbox` is always exactly as tall as its
+content. If you need a fixed frame, clip the object or the canvas region yourself,
+and if you need text to shrink to fit you have to iterate `fontSize` and re-measure
+in a loop.
+
+There is no vertical alignment either.
+
+## Resizing and scaling
+
+`Textbox` replaces only its **left and right middle handles** with width handles.
+The consequences are worth stating explicitly, because the mix is unusual:
+
+- **`ml` / `mr`** change `width` — text re-wraps live as you drag.
+- **corner handles** change `scaleX` and `scaleY` — text is stretched, no re-wrap.
+- **`mt` / `mb`** change `scaleY` — vertically stretched, no re-wrap.
+
+So the on-screen width is `width * scaleX`, while the wrapping width is `width`
+alone. If your UI reports a width to the user, decide which of the two you mean.
+
+The class documentation states that Y scaling is locked; in current versions that is
+**out of date** — the top, bottom and corner handles do scale. If you want the
+locked behaviour, remove or replace those controls yourself. See
+[configuring controls](/docs/configuring-controls).
+
+## Wrapped lines vs logical lines
+
+This is the part to internalise before writing any code that touches positions in a
+`Textbox`.
+
+`styles` is keyed by **logical** line — the lines you separated with `\n`. But
+everything that renders, measures or positions a caret works in **visual** lines —
+the wrapped ones. A three-line paragraph that wraps into seven visual lines still
+has exactly three entries in `styles`.
+
+Fabric.js keeps an internal map between the two, and translates for you inside the
+style accessors. What you need to remember:
+
+- Never index `styles` with a visual line number.
+- Get logical coordinates with `box.get2DCursorLocation(index, true)`, and visual
+  ones with `box.get2DCursorLocation(index)`.
+- The map is rebuilt on every layout, so never cache indices derived from it across
+  an edit.
+
+Because styles live on logical lines, they survive re-wrapping unharmed — resizing
+the box does not disturb your formatting.
+
+One accessor to be careful with: `styleHas(property, lineIndex)` over-reports for a
+wrapped paragraph, answering for the whole logical line rather than the visual
+segment you asked about. `isEmptyStyles(lineIndex)` is segment-accurate.
+
+There is also a subtle difference in caret arithmetic between the two wrap modes:
+with word wrapping the space at a soft break is consumed, while with
+`splitByGrapheme` nothing is dropped. If you implement your own selection maths,
+account for it.
+
+## Styles change where lines break
+
+Because wrapping measures the real text, per-character styles feed back into it. A
+bold or larger run makes words wider and can re-flow the whole box:
+
+```js
+box.setSelectionStyles({ fontSize: 40 }, 0, 10);
+box.initDimensions(); // re-wrap now rather than at the next render
+```
+
+`charSpacing` does the same. This is expected, but it means "apply bold" is not a
+purely visual operation in a `Textbox` — it can change the layout, and your
+surrounding UI may need to react.
+
+## Performance
+
+Wrapping runs synchronously on every keystroke while editing, re-measuring every
+word of every logical line. The global character-width cache is what keeps this
+viable — which is another reason a poisoned font cache hurts here. For very large
+documents, prefer several smaller text objects over one enormous `Textbox`.
+
+If you call `initDimensions()` by hand on a `Textbox`, set `dirty = true` as well:
+unlike the base class, the override does not do it for you, and a width-only change
+can otherwise reuse the stale cached bitmap.
diff --git a/src/content/docs/docs/Text/textbox-wrapping/code.js b/src/content/docs/docs/Text/textbox-wrapping/code.js
new file mode 100644
index 00000000..f4d5c37d
--- /dev/null
+++ b/src/content/docs/docs/Text/textbox-wrapping/code.js
@@ -0,0 +1,24 @@
+const canvas = new fabric.Canvas(canvasEl);
+
+const box = new fabric.Textbox(
+  'Drag the side handles to change the wrapping width. The corner handles scale instead.',
+  {
+    width: 260,
+    fontSize: 20,
+    fill: '#334155',
+    textAlign: 'left',
+    // set to true to break anywhere instead of at spaces (useful for CJK)
+    splitByGrapheme: false,
+    cornerColor: '#ffffff',
+    cornerStrokeColor: '#334155',
+    borderColor: '#334155',
+    transparentCorners: false,
+  },
+);
+
+canvas.add(box);
+canvas.centerObject(box);
+canvas.setActiveObject(box);
+
+// height is derived from the wrapped result on every layout pass
+console.log('lines:', box.textLines.length, 'height:', box.height);
diff --git a/src/content/docs/docs/core-concepts.md b/src/content/docs/docs/core-concepts.md
index 84023454..c2a8d9dc 100644
--- a/src/content/docs/docs/core-concepts.md
+++ b/src/content/docs/docs/core-concepts.md
@@ -32,7 +32,7 @@ Each of these objects represent a visually different shape that can be added on
 - `Rect`
 - `Circle`, `Ellipse`
 - `FabricImage`
-- `FabricText`, `IText`, `Textbox`
+- `FabricText`, `IText`, `Textbox` — see [choosing a text class](/docs/text/choosing-a-class)
 
 ### Patterns, Gradients and Shadows