@unmade/text-renderer 1.1.1 → 1.3.0

package/README.md

@@ -46,6 +46,154 @@ const { getRenderedText } = await import('@unmade/text-renderer/node');
 
 **CE Lambda integration**: When wiring text-renderer into the Configuration Engine Lambda, use the `/node` ESM entry (`@unmade/text-renderer/node`) from an ESM Lambda handler, or use the `await import()` pattern above from an existing CJS handler. The `ce-adapter` sub-package (`@unmade/text-renderer/ce-adapter`) retains a CJS build and can be `require()`'d normally.
 
+## Choosing a font size
+
+`getRenderedText` draws text at a size you give it. These work out what that size should be.
+
+```typescript
+import { getFontSizeToFitBox, loadFont } from '@unmade/text-renderer';
+
+const font = await loadFont('https://example.com/font.ttf');
+
+const { fontSize, fits, boundBy } = getFontSizeToFitBox({
+  font,
+  text: 'HELLO',
+  boxDimensions: {
+    width: 500,
+    height: 200,
+    physicalWidth: 100,
+    physicalHeight: 40,
+    physicalUnits: 'mm',
+  },
+  size: { mode: 'fitToBox', minFontSize: 20, maxFontSize: 200 },
+  spacing: { outlineWidth: 0, letterSpacing: 0, letterSpacingOutline: 0 },
+  baseline: 'flat',            // or 'curved', or { type: 'custom', path: '...' }
+  verticalAlignment: 'centre', // affects where a curved baseline sits
+});
+```
+
+For flat and custom baselines this is a direct calculation rather than a search: glyph
+widths, outline stroke and letter spacing are all `fontSize * constant`, so measuring
+once at a reference size and solving for a scale factor is exact. Curved baselines are
+bisected instead, against both limits at once: neither the arc's length nor the arch's
+position is proportional to font size, so both are evaluated at each candidate size.
+
+The height check asks where the text will actually land, not how tall it is. The arch is
+positioned from a standard capital, so that its shape does not change as characters are
+typed — which means a descender hangs below the arch's ends, outside a box the arch itself
+sits comfortably inside. The check reads the arch's placement from the same function that
+generates the baseline path, so a size it accepts is one the renderer can draw.
+
+### The three ways to decide a size
+
+`size` covers each of them, so none is a special case:
+
+| `size` | Meaning |
+|---|---|
+| `{ mode: 'fitToBox', minFontSize, maxFontSize }` | Solve for the largest size that fits the box |
+| `{ mode: 'fontSize', fontSize }` | Pin a size in pixels |
+| `{ mode: 'physicalSize', physicalSize: [60, 'mm'] }` | Pin a physical size — what a fixed size preset is |
+
+`minFontSize` and `maxFontSize` belong only to `fitToBox`, because they only mean
+anything while solving. A pinned size overrides them by design.
+
+Pinning inverts the problem. Instead of the text being fixed and the size free, the
+size is fixed and the **text length** becomes the free variable — hold 60mm, and fit as
+many characters as will go.
+
+### Reading the result
+
+```typescript
+interface FitTextToBoxResult {
+  fontSize: number;
+  fits: boolean;                 // false when it won't fit even at the smallest allowed size
+  boundBy: 'width' | 'height' | 'requestedSize';
+}
+```
+
+`boundBy` says which limit decided the outcome — when it fits, what capped the size;
+when it doesn't, what couldn't be satisfied. Callers generally need to respond
+differently to each: text too wide for its box and text too tall for its box call for
+different remedies, and in the configuration engine they surface as different messages.
+
+`requestedSize` means the box wasn't the limiting factor: either `maxFontSize` was
+reached while solving, or a pinned size was simply granted.
+
+### Shortening text that won't fit
+
+```typescript
+import { fitAndTruncateTextToBox } from '@unmade/text-renderer';
+
+const result = fitAndTruncateTextToBox({ font, text, boxDimensions, size, spacing });
+
+result.text;              // possibly shortened
+result.truncated;         // whether anything was removed
+result.linesDropped;      // whole lines removed
+result.charactersRemoved; // trailing characters removed
+```
+
+Whole lines are dropped before characters are trimmed. Both counts are reported rather
+than a single mode, because one call can do both — drop a line, then find the remainder
+still needs trimming — and because the caller usually wants to say something different
+about each.
+
+Works in every `size` mode. With a pinned size it is the only thing that can give: the
+size stays put and the text shortens.
+
+### Rotation
+
+Deliberately absent. Pass the box you want text laid out in and apply rotation to the
+rendered output. Rotating the frame rather than reasoning about rotation inside the
+solver keeps it working in one coordinate space, and is also what lets a rotated tall
+placement use its long side for the baseline.
+
+## Measuring text
+
+`renderText` returns artwork; `measureText` returns its dimensions, for the same
+inputs.
+
+```typescript
+import { measureText } from '@unmade/text-renderer';
+
+const m = measureText({
+  font,
+  text: 'HELLO',
+  boxDimensions,
+  physicalSize: [20, 'mm'],
+  spacing: { outlineWidth: 0, letterSpacing: 0, letterSpacingOutline: 0 },
+  baseline: 'flat',
+});
+
+m.bbox;              // { x, y, width, height } in box pixels
+m.physicalWidth;     // in the box's units
+m.physicalHeight;
+m.physicalCapHeight; // see below
+m.lines;             // per line, in rendered order
+```
+
+It measures the **same positioned glyphs that get drawn**, rather than
+re-deriving dimensions from font metrics. That matters for more than tidiness: a
+curved line's bounds follow the arch, which no flat metrics calculation can know
+about, and any second implementation eventually disagrees with the first.
+`renderText` and `measureText` share one layout pass for exactly that reason.
+
+It throws where `renderText` would throw, and for the same reasons — so if
+measuring succeeds, rendering the same options will too.
+
+### Cap height is reported, not derived
+
+`physicalCapHeight` is the physical height of a standard capital at the chosen
+font size. It is **not** `physicalHeight`, and can't be calculated from it:
+
+- `physicalHeight` measures the glyphs actually present, so it grows with
+  descenders, accents and punctuation
+- `physicalCapHeight` is a property of the font and size alone, so the same size
+  always reports the same cap height regardless of what was typed
+
+Both are needed. Cap height is what a fixed size preset targets and what gets
+persisted against a design for manufacturing; the measured height is what the
+artwork actually occupies.
+
 ## Configuration Engine adapter
 
 The `ce-adapter` sub-package bridges CE (Configuration Engine) editor state to renderer options:
@@ -88,6 +236,89 @@ comparisons/{designUrlHash}/{timestamp}/{placementId}/
   renderer-options.json # GetRenderedTextOptions (mapped TR input)
 ```
 
+## Platform bundle suites
+
+The package builds a separate bundle per platform — browser, worker and node —
+each resolving a different variant of `@unmade/platform`:
+
+| | `DOMPoint` | `DOMMatrix` | `DOMParser` |
+|---|---|---|---|
+| node | polyfill | `@thednp` polyfill | linkedom |
+| worker | **native** | `@thednp` polyfill | linkedom/worker |
+| browser | native | native | native |
+
+`__tests__/platform/` tests those built bundles, each in the host it ships into:
+the node bundle in the test process, the browser bundle on a page, and the worker
+bundle inside a real `DedicatedWorkerGlobalScope`. Nothing else runs them — the
+unit suite tests `src` under node, where neither `DOMPoint` nor `DOMMatrix`
+exists, so it can only ever exercise the polyfills.
+
+```bash
+npm run test:platform
+```
+
+It builds first, because it loads `dist` and a stale bundle would otherwise give
+a green run against code that is no longer there. It needs a browser:
+`npx playwright install chromium`.
+
+### The two suites
+
+**`render.test.ts`** draws every scenario in `scenarios.ts` on all three bundles,
+through both public render entry points — `getRenderedText`, which loads its own
+font, and `renderText`, which takes one already loaded. Each render is rasterised
+here, by one resvg call for all three, and checked twice:
+
+- **pixel-identical to the node bundle's, with no tolerance.** All three go
+  through the same rasteriser in the same process, so nothing legitimate can move
+  a pixel. This is the assertion that the differing geometry and DOM
+  implementations do not reach the artwork.
+- **within 1% of a committed reference** in `platform/references/`, so a change
+  that shifts all three together is caught as well.
+
+**`api.test.ts`** covers the rest of the public API, which nothing else would
+call on the browser or worker bundles: constants, baseline generation and
+validation, measurement, font loading and the font cache. Each is called with
+identical inputs on all three bundles and the results compared. It also asserts
+the three export the same names, that every export has a probe, and that each
+bundle ran in the host it is built for — a `typeof DOMPoint` check cannot tell a
+page from a worker, since both have the native globals.
+
+### The report
+
+Every run writes `__tests__/platform-output/report.html`: one self-contained file
+with each scenario's committed reference beside what each bundle drew, badged
+with both comparisons, plus the diff images and the browser's user agent. It is
+gitignored and collected as a CI artifact from `platform-test` whether the run
+passed or failed, so a by-eye check is always available. The SVG each bundle
+produced is written alongside it, so a difference the report shows as pixels can
+be diffed as text.
+
+### Fonts
+
+Served from the test process, so every platform fetches byte-identical bytes from
+the same URL and the font is never a variable. Three, chosen for what they
+exercise:
+
+- **Bangers** — irregular display face: curves, diagonals, varying stroke widths.
+  Caps only.
+- **Lora** — high-contrast serif with true lowercase, so descenders feed the
+  baseline and line-height calculation.
+- **giants-color** — glyphs stored as SVG documents, the only path that goes
+  through a `DOMParser` and back out through an `XMLSerializer`.
+
+The two added faces are OFL, with their licences beside them in
+`__tests__/fixtures/`.
+
+### Updating the references
+
+```bash
+UPDATE_FIXTURES=true npm run test:platform
+```
+
+Rewrites every reference from the node bundle's render, then still checks the
+other two against what it just stored. Review the diffs in the report before
+committing.
+
 ## Regression tests
 
 Regression tests live in `__tests__/regression.test.ts` and use fixture pairs in `__tests__/fixtures/regression/`:

package/dist/{__vite-browser-external-CijFC1_R.js → __vite-browser-external-oLchLuMx.js}

@@ -1,4 +1,4 @@
-import { t as e } from "./chunk-3b4jIN3o.js";
+import { t as e } from "./rolldown-runtime-DtPi1Y-2.js";
 //#region __vite-browser-external
 var t = /* @__PURE__ */ e(((e, t) => {
 	t.exports = {};

package/dist/baselines/index.d.ts

@@ -28,6 +28,25 @@ export interface GenerateCurvedBaselineOptions {
     textHeight: number;
     verticalAlignment: VerticalTextAlignmentValues;
 }
+/** Where the arch sits vertically: its peak, and the baseline at its ends. */
+export interface CurvedBaselineGeometry {
+    /** y of the peak — the highest point of the baseline. */
+    curveTop: number;
+    /** y of the two ends — the lowest points of the baseline. */
+    curveBottom: number;
+    /** Horizontal gap left at each end so the outer glyphs are not clipped. */
+    curveXInset: number;
+}
+/**
+ * The arch's placement, on its own so that the path and anything reasoning
+ * about where the text will land come from one calculation.
+ *
+ * Sizing needs this: it has to know where the renderer will actually put the
+ * baseline before it can say whether the text riding it clears the box. Working
+ * that out separately is what let the fit engine believe a size fitted while
+ * the render clipped.
+ */
+export declare const curvedBaselineGeometry: ({ boxDimensions, baseline, textHeight, verticalAlignment, }: GenerateCurvedBaselineOptions) => CurvedBaselineGeometry;
 /**
  * Generate a path command to curve text and align that text to the top of the box.
  * Uses two quadratic bezier curves — one from the bottom left to the peak, and a

package/dist/ce-adapter/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e){return e.type===`text`}function t(e){let t=e.getState().garment;return e.settings.garments.find(e=>e.slug===t)}function n(e,t,n){if(!e.embellishment_positions)return;let r=e.embellishment_positions.filter(e=>e.placement===t?!n||!e.variant?!0:e.variant===n||e.variant.toLowerCase()===`common`:!1);if(n&&r.length>1){let e=r.find(e=>e.variant===n);if(e)return e}return r[0]}function r(e,t){let n=e.fonts.find(e=>e.id===t);if(n)return{id:n.id,fontUrl:n.font_url,fontFamily:n.font_family,letterSpacing:n.letter_spacing??0,letterSpacingOutline:n.letter_spacing_outline??0,outlineWidth:n.outline_width??0,fixedColours:n.fixed_colours}}function i(t,i,a,o,s,c){let{library:l}=s,u=[];for(let[d,f]of Object.entries(o)){if(f.type!==`text`)continue;let o=f,{meta:p}=o;if(!p?.text)continue;let{libraryItemID:m}=o,h=l[m];if(!h||!e(h))continue;let g=p.font;if(g===void 0)continue;let _=r(h,g);if(!_)continue;let v=n(i,d,c);if(!v)continue;let y=null,b=null;if(p.colours&&h.palette!=null)try{let e=t.palettes.getUsedColours(h.palette,p.colours);y=e[0]??null,b=e[1]??null}catch(e){console.warn(`[extractTextPlacements] Colour resolution failed for ${d}:`,e)}let x=s.byId?.[d],S={vertical:`top`,horizontal:`left`};if(x){let e=x;e.vertical_alignment&&(S.vertical=e.vertical_alignment),e.horizontal_alignment&&(S.horizontal=e.horizontal_alignment)}u.push({placementId:d,displayName:d,source:a,text:p.text,font:_,isCurved:p.isCurved??!1,isDistributed:p.isDistributed??!1,verticalAlignment:p.verticalAlignment??S.vertical,horizontalAlignment:p.horizontalAlignment??S.horizontal,rotation:p.rotation??0,spacing:p.spacing??null,fillColour:y,outlineColour:b,position:{width:v.width,height:v.height,physicalWidth:v.physical_width_decimal,physicalHeight:v.physical_height_decimal,physicalUnits:v.physical_size_units,baselinePath:v.baseline_path,rotation:v.rotation},userSetPhysicalSize:p.retainedPhysicalSize??null,fontMetrics:(()=>{let e=p.fontMetrics??{size:0,height:0,baseline:0,width:0},t=e.physicalFontSize||(e.physicalHeight!=null&&e.physicalHeight>0&&e.physicalUnits!=null?[e.physicalHeight,e.physicalUnits]:void 0);return{...e,physicalFontSize:t}})(),manufacturingMethod:p.manufacturing_method??``})}return u}function a(e){let n=e.getState(),r=t(e);if(!r)return console.warn(`[extractTextPlacements] No matching garment found`),[];let a=typeof e.getCurrentVariant==`function`?e.getCurrentVariant():void 0,o=[],s=n.vals?.placements,c=e.settings.placements;s&&c&&o.push(...i(e,r,`placements`,s,c,a));let l=n.vals?.embellishments,u=e.settings.embellishments;return l&&u&&o.push(...i(e,r,`embellishments`,l,u,a)),o.length===0&&console.warn(`[extractTextPlacements] No text entries found in either placements or embellishments`),o}function o(e){return e===`center`?`centre`:e}function s(e){let t=o(e.horizontalAlignment);e.isDistributed&&(t=`distributed`);let n;n=e.position.baselinePath?{type:`custom`,path:e.position.baselinePath}:e.isCurved?`curved`:`flat`;let r=e.userSetPhysicalSize?[e.userSetPhysicalSize[0],e.userSetPhysicalSize[1]]:e.fontMetrics.physicalFontSize==null?[e.position.physicalHeight,e.position.physicalUnits]:e.fontMetrics.physicalFontSize,i={outlineWidth:e.outlineColour==null?0:e.font.outlineWidth,letterSpacing:e.spacing?.letter_spacing??0,letterSpacingOutline:e.spacing?.letter_spacing_outline??0},a=e.fillColour?{hex:e.fillColour.hex,reference:e.fillColour.reference??void 0}:void 0,s=e.outlineColour?{hex:e.outlineColour.hex,reference:e.outlineColour.reference??void 0}:void 0,c;if(e.font.fixedColours){let t={};for(let[n,r]of Object.entries(e.font.fixedColours))t[n]={hex:r.hex,reference:r.reference};c=t}return{text:e.text,fontUrl:e.font.fontUrl,physicalSize:r,fontSizeFallback:e.fontMetrics.size,boxDimensions:{width:e.position.width,height:e.position.height,physicalWidth:e.position.physicalWidth,physicalHeight:e.position.physicalHeight,physicalUnits:e.position.physicalUnits},spacing:i,verticalAlignment:o(e.verticalAlignment),horizontalAlignment:t,baseline:n,fillColour:a,strokeColour:s,colourMap:c}}exports.extractTextPlacements=a,exports.mapStateToRendererOptions=s;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e){return e.type===`text`}function t(e){let t=e.getState().garment;return e.settings.garments.find(e=>e.slug===t)}function n(e,t,n){if(!e.embellishment_positions)return;let r=e.embellishment_positions.filter(e=>e.placement===t?!n||!e.variant||e.variant===n||e.variant.toLowerCase()===`common`:!1);if(n&&r.length>1){let e=r.find(e=>e.variant===n);if(e)return e}return r[0]}function r(e,t){let n=e.fonts.find(e=>e.id===t);if(n)return{id:n.id,fontUrl:n.font_url,fontFamily:n.font_family,letterSpacing:n.letter_spacing??0,letterSpacingOutline:n.letter_spacing_outline??0,outlineWidth:n.outline_width??0,fixedColours:n.fixed_colours}}function i(t,i,a,o,s,c){let{library:l}=s,u=[];for(let[d,f]of Object.entries(o)){if(f.type!==`text`)continue;let o=f,{meta:p}=o;if(!p?.text)continue;let{libraryItemID:m}=o,h=l[m];if(!h||!e(h))continue;let g=p.font;if(g===void 0)continue;let _=r(h,g);if(!_)continue;let v=n(i,d,c);if(!v)continue;let y=null,b=null;if(p.colours&&h.palette!=null)try{let e=t.palettes.getUsedColours(h.palette,p.colours);y=e[0]??null,b=e[1]??null}catch(e){console.warn(`[extractTextPlacements] Colour resolution failed for ${d}:`,e)}let x=s.byId?.[d],S={vertical:`top`,horizontal:`left`};if(x){let e=x;e.vertical_alignment&&(S.vertical=e.vertical_alignment),e.horizontal_alignment&&(S.horizontal=e.horizontal_alignment)}u.push({placementId:d,displayName:d,source:a,text:p.text,font:_,isCurved:p.isCurved??!1,isDistributed:p.isDistributed??!1,verticalAlignment:p.verticalAlignment??S.vertical,horizontalAlignment:p.horizontalAlignment??S.horizontal,rotation:p.rotation??0,spacing:p.spacing??null,fillColour:y,outlineColour:b,position:{width:v.width,height:v.height,physicalWidth:v.physical_width_decimal,physicalHeight:v.physical_height_decimal,physicalUnits:v.physical_size_units,baselinePath:v.baseline_path,rotation:v.rotation},userSetPhysicalSize:p.retainedPhysicalSize??null,fontMetrics:(()=>{let e=p.fontMetrics??{size:0,height:0,baseline:0,width:0},t=e.physicalFontSize||(e.physicalHeight!=null&&e.physicalHeight>0&&e.physicalUnits!=null?[e.physicalHeight,e.physicalUnits]:void 0);return{...e,physicalFontSize:t}})(),manufacturingMethod:p.manufacturing_method??``})}return u}function a(e){let n=e.getState(),r=t(e);if(!r)return console.warn(`[extractTextPlacements] No matching garment found`),[];let a=typeof e.getCurrentVariant==`function`?e.getCurrentVariant():void 0,o=[],s=n.vals?.placements,c=e.settings.placements;s&&c&&o.push(...i(e,r,`placements`,s,c,a));let l=n.vals?.embellishments,u=e.settings.embellishments;return l&&u&&o.push(...i(e,r,`embellishments`,l,u,a)),o.length===0&&console.warn(`[extractTextPlacements] No text entries found in either placements or embellishments`),o}function o(e){return e===`center`?`centre`:e}function s(e){let t=o(e.horizontalAlignment);e.isDistributed&&(t=`distributed`);let n;n=e.position.baselinePath?{type:`custom`,path:e.position.baselinePath}:e.isCurved?`curved`:`flat`;let r=e.userSetPhysicalSize?[e.userSetPhysicalSize[0],e.userSetPhysicalSize[1]]:e.fontMetrics.physicalFontSize==null?[e.position.physicalHeight,e.position.physicalUnits]:e.fontMetrics.physicalFontSize,i={outlineWidth:e.outlineColour==null?0:e.font.outlineWidth,letterSpacing:e.spacing?.letter_spacing??0,letterSpacingOutline:e.spacing?.letter_spacing_outline??0},a=e.fillColour?{hex:e.fillColour.hex,reference:e.fillColour.reference??void 0}:void 0,s=e.outlineColour?{hex:e.outlineColour.hex,reference:e.outlineColour.reference??void 0}:void 0,c;if(e.font.fixedColours){let t={};for(let[n,r]of Object.entries(e.font.fixedColours))t[n]={hex:r.hex,reference:r.reference};c=t}return{text:e.text,fontUrl:e.font.fontUrl,physicalSize:r,fontSizeFallback:e.fontMetrics.size,boxDimensions:{width:e.position.width,height:e.position.height,physicalWidth:e.position.physicalWidth,physicalHeight:e.position.physicalHeight,physicalUnits:e.position.physicalUnits},spacing:i,verticalAlignment:o(e.verticalAlignment),horizontalAlignment:t,baseline:n,fillColour:a,strokeColour:s,colourMap:c}}exports.extractTextPlacements=a,exports.mapStateToRendererOptions=s;

package/dist/ce-adapter/index.js

@@ -8,7 +8,7 @@ function t(e) {
 }
 function n(e, t, n) {
 	if (!e.embellishment_positions) return;
-	let r = e.embellishment_positions.filter((e) => e.placement === t ? !n || !e.variant ? !0 : e.variant === n || e.variant.toLowerCase() === "common" : !1);
+	let r = e.embellishment_positions.filter((e) => e.placement === t ? !n || !e.variant || e.variant === n || e.variant.toLowerCase() === "common" : !1);
 	if (n && r.length > 1) {
 		let e = r.find((e) => e.variant === n);
 		if (e) return e;

package/dist/fitting/index.d.ts

@@ -0,0 +1,86 @@
+import { LoadedFont } from '../loading';
+import { BaselineConfig, BaselineType, BoxDimensions, PhysicalSize, TextSpacing, VerticalTextAlignmentValues } from '../types';
+/**
+ * How the font size is arrived at.
+ *
+ * `fitToBox` solves for the largest size the box allows. The other two pin the
+ * size and leave the text length as the free variable instead — which is what a
+ * fixed size preset is: hold 60mm, and fit as many characters as will go. All
+ * three then behave identically downstream, so a pinned size is an ordinary mode
+ * rather than a special path.
+ */
+export type FitSize = {
+    mode: 'fitToBox';
+    minFontSize: number;
+    maxFontSize: number;
+} | {
+    mode: 'fontSize';
+    fontSize: number;
+} | {
+    mode: 'physicalSize';
+    physicalSize: PhysicalSize;
+};
+export interface FitTextToBoxOptions {
+    font: LoadedFont;
+    text: string;
+    boxDimensions: BoxDimensions;
+    size: FitSize;
+    spacing?: TextSpacing;
+    baseline?: BaselineType | BaselineConfig;
+    verticalAlignment?: VerticalTextAlignmentValues;
+}
+/**
+ * Which limit decided the outcome.
+ *
+ * - `width` — the box width, or the arc/custom path length for a non-flat baseline
+ * - `height` — the box height
+ * - `requestedSize` — the size the caller asked for, reached before the box
+ *   mattered. Covers both hitting `maxFontSize` when solving and simply getting
+ *   the pinned size that was requested.
+ */
+export type FitConstraint = 'width' | 'height' | 'requestedSize';
+export interface FitTextToBoxResult {
+    fontSize: number;
+    /** False when the text cannot fit within the box even at minFontSize. */
+    fits: boolean;
+    /**
+     * When `fits`, the limit that capped the size. When not, the limit that could
+     * not be satisfied.
+     *
+     * Callers need this to tell one failure from another: overflowing the width
+     * and overflowing the height call for different responses, and in the
+     * configuration engine they surface as different messages to the user.
+     */
+    boundBy: FitConstraint;
+}
+export interface FitAndTruncateTextToBoxResult extends FitTextToBoxResult {
+    text: string;
+    truncated: boolean;
+    /**
+     * How the text was shortened. Reported separately because dropping a line and
+     * trimming characters are different outcomes with different messages, and a
+     * single pass can do both — drop a line, then still need to trim.
+     */
+    linesDropped: number;
+    charactersRemoved: number;
+}
+/**
+ * Calculate the font size at which `text` fills `boxDimensions` as closely
+ * as possible without overflowing, for any baseline shape. This replaces
+ * binary-searching for a fitting font size: flat and custom baselines are
+ * solved in one step, from a single measurement, while curved baselines need
+ * a bounded numeric solve (see solveCurvedFit).
+ *
+ * `fits: false` means the text doesn't fit even at minFontSize — the caller
+ * (e.g. fitAndTruncateTextToBox) should either shorten the text or accept
+ * the overflow at minFontSize.
+ */
+export declare const getFontSizeToFitBox: (options: FitTextToBoxOptions) => FitTextToBoxResult;
+/**
+ * Like getFontSizeToFitBox, but when text doesn't fit even at minFontSize,
+ * shortens it (dropping the last whole line first if there is more than
+ * one, otherwise trimming trailing characters) and retries until it fits
+ * or there's nothing left to remove. Mirrors CE's existing truncation UX —
+ * text lost this way is a caller/product concern, not a rendering one.
+ */
+export declare const fitAndTruncateTextToBox: (options: FitTextToBoxOptions) => FitAndTruncateTextToBoxResult;

package/dist/helpers/bbox.d.ts

@@ -1,3 +1,4 @@
+import { PlatformMatrix } from '../types';
 export declare class Box {
     corners: DOMPoint[];
     x1: number;
@@ -13,7 +14,7 @@ export declare class Box {
     get x4(): number;
     get y4(): number;
     constructor(x1: number, y1: number, x2: number, y2: number, x3?: number, y3?: number, x4?: number, y4?: number);
-    transform(matrix: DOMMatrix): void;
+    transform(matrix: PlatformMatrix): void;
     toPointsArray(): number[][];
     getBBox(): BBox;
 }

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import { GetRenderedTextOptions } from './types';
 export { type GenerateCurvedBaselineOptions, type GenerateFlatBaselineOptions, generateCurvedBaseline, generateFlatBaseline, normaliseBaselineOption, validateCustomBaselinePath, } from './baselines';
 export { DEFAULT_OUTLINE_FACTOR, DEFAULT_SPACING, LINE_HEIGHT, } from './constants';
+export { type FitAndTruncateTextToBoxResult, type FitConstraint, type FitSize, type FitTextToBoxOptions, type FitTextToBoxResult, fitAndTruncateTextToBox, getFontSizeToFitBox, } from './fitting';
 export { getFontColours } from './glyph/svg-glyph-converter';
+export { type LayoutTextOptions, layoutText, type MeasuredLine, measureText, type TextLayout, type TextMeasurement, } from './layout';
 export { getFontCache, type LoadedFont, loadFont } from './loading';
 export { type GetFontSizeFromPhysicalSizeOptions, type GetTextMetricsAtFontSizeOptions, getFontSizeFromPhysicalSize, getTextMetricsAtFontSize, } from './measuring';
 export type { GetTextAsPathDataOptions, SvgGlyphEntry } from './rendering';