@unmade/text-renderer 1.2.0 → 1.3.0

package/README.md

@@ -147,6 +147,53 @@ rendered output. Rotating the frame rather than reasoning about rotation inside
 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:

package/dist/fitting/index.d.ts

@@ -67,9 +67,9 @@ export interface FitAndTruncateTextToBoxResult extends FitTextToBoxResult {
 /**
  * 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: for flat and custom baselines
- * it's a direct O(1) calculation; for curved baselines it's a bounded
- * numeric solve (see solveCurvedFit).
+ * 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

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { type GenerateCurvedBaselineOptions, type GenerateFlatBaselineOptions, g
 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';