resvg-napi 0.0.0-probe.1788204851 → 0.2.0

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 resvg-napi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# resvg-napi
+
+[![npm](https://img.shields.io/npm/v/resvg-napi)](https://www.npmjs.com/package/resvg-napi)
+[![conformance](https://img.shields.io/badge/resvg%20conformance-1715%2F1715-brightgreen)](#conformance)
+[![licence](https://img.shields.io/npm/l/resvg-napi)](#licence)
+
+Node.js bindings for [resvg](https://github.com/linebender/resvg) 0.48: render
+SVG to PNG, and read back what usvg made of the document — the resolved tree,
+text metrics, paint, geometry.
+
+Generated from the upstream Rust sources, so the TypeScript surface is usvg's
+own, names and doc comments included.
+
+```bash
+npm install resvg-napi
+```
+
+```js
+import { Resvg, FontDatabase, renderAsync } from 'resvg-napi'
+
+const doc = new Resvg(svg, { dpi: 192, fontFamily: 'DejaVu Sans' })
+doc.renderPng({ width: 1200, background: '#fff' })      // Buffer
+doc.renderRaw({ crop: doc.absLayerBoundingBox() })      // RGBA8, trimmed
+await renderAsync(svg, options, { width: 1200 })        // off the event loop
+```
+
+## What you can read back
+
+`index.d.ts` is the reference — it is generated, so it cannot drift. This is
+the map.
+
+**Render.** Parse once with `new Resvg(svg, options?, fonts?, images?)`, then
+render as often as you like.
+
+| | |
+|---|---|
+| `renderPng(params?)` | `Buffer` |
+| `renderRaw(params?)` | `RawImage`, un-premultiplied RGBA8 |
+| `toString(opts?)` | the resolved tree, back as SVG |
+| `renderPngAsync` · `renderRawAsync` · `toStringAsync` | the same, off the event loop, `AbortSignal`-aware |
+
+`params` carries `width` / `height` / `scale`, a `background` colour and a
+`crop` box. `Resvg.parseAsync` moves the parse off the loop too.
+
+**Walk the tree.** `node(id)` and `children()` hand back `SvgNode`s, and each
+one knows what it is:
+
+```js
+const n = doc.node('surname')
+n.kind           // 'group' | 'path' | 'image' | 'text'
+n.path()         // geometry, fill, stroke — null unless it is a shape
+n.text()         // chunks, layouted spans, positioned glyphs, decoration
+n.renderPng()    // that element alone, cropped to its own extent
+```
+
+A span carries what it is drawn with, down to the lines through it:
+
+```js
+const span = n.text().chunks[0].spans[0]
+span.decoration.underline?.fill?.paint  // …and .overline, .lineThrough
+```
+
+Paint is a discriminated union, so TypeScript narrows it:
+
+```ts
+const paint = n.path()?.fill?.paint
+if (paint?.type === 'color') paint.value   // { red, green, blue }
+else paint?.id                             // the gradient or pattern it names
+```
+
+**Measure.** Every node reports `boundingBox()`, `absBoundingBox()`,
+`strokeBoundingBox()`, `absLayerBoundingBox()` and `extent()` — in the
+document's own units, which is not the canvas. See *Fitting text* below for why
+that distinction bites.
+
+**Fonts.** `FontDatabase` is `fontdb` itself: `loadSystemFonts()`,
+`loadFontData(buffer)`, `loadFontFile(path)`, `faces()`, `query()`, and the
+generic-family setters. A face reports its `families`, `weight`, `style`
+(`'normal' | 'italic' | 'oblique'`) and whether it is `monospaced`. `pendingFonts()` on a parsed document names the
+families it wanted and did not get; `pendingImages()` does the same for hrefs.
+
+**Definitions.** `linearGradients()`, `radialGradients()`, `patterns()`,
+`clipPaths()`, `masks()`, `filters()` — the paint servers an element's `id`
+refers to.
+
+Something missing? The generator keeps a report of every upstream member it
+left alone, with the reason. `RESVG_NAPI_CODEGEN_LOG=1 cargo build` prints it,
+and [CONTRIBUTING.md](CONTRIBUTING.md) explains what the reasons mean.
+
+## Conformance
+
+resvg's own test corpus, rendered through these bindings: **1715 of 1715 match**
+the reference PNGs upstream asserts on, within 1/255 per channel — a tolerance
+measured rather than chosen, with the reason recorded in
+[`scripts/conformance.mjs`](scripts/conformance.mjs).
+
+```bash
+npm run conformance:fetch   # the corpus, at the tag Cargo.toml pins
+npm run conformance         # 15 seconds including the fetch
+```
+
+CI runs it on every pull request, so a resvg bump that changes a render shows up
+as a diff rather than passing unnoticed.
+
+## Platforms
+
+Thirteen targets.
+
+| | x64 | arm64 | armv7 | ia32 |
+|---|---|---|---|---|
+| Linux (glibc) | ✅ | ✅ | ✅ | — |
+| Linux (musl) | ✅ | ✅ | — | — |
+| macOS | ✅ | ✅ | — | — |
+| Windows (MSVC) | ✅ | ✅ | — | ✅ |
+| Android | — | ✅ | ✅ | — |
+| WASI (`wasm32-wasip1-threads`) | ✅ | — | — | — |
+
+The dependency tree is pure Rust — `fontconfig` support comes from
+`fontconfig-parser`, not the C library — so every target cross-compiles without
+a system SDK.
+
+The WASI build is the same generated bindings on emnapi instead of node-api, and
+it is complete: rendering, `toString`, bounding boxes, the node walk, `renderAsync`
+(threads via `wasm32-wasip1-threads`) and even filesystem image resolution all
+work. One difference: `loadSystemFonts()` finds 0 faces inside the sandbox, so
+fonts must be supplied with `loadFontData(buffer)` — the demo fetches them from
+google/fonts by name rather than making you find a file.
+
+Adding a target is an entry in `scripts/ci-targets.mjs` — which host builds it
+and which cross-compilation flag it needs — and the triple in `package.json`
+under `napi.targets`; then `npm run create-npm-dirs`. The two lists used to be
+independent, so a target could sit in one and not the other; the script now
+fails when they disagree.
+
+CI does not build all thirteen on a pull request. It builds the two that can
+tell it something — `x86_64-unknown-linux-gnu`, which the tests, the drift
+checks and the conformance suite run on, and `wasm32-wasip1-threads`, whose
+generated shims and test run are a different code path. The other eleven build
+on the merge, on a `v*` tag, on a manual dispatch, or on a pull request labelled
+`full-matrix` when the proof is wanted before merging rather than after.
+
+
+## Fitting text to a width
+
+An Illustrator template says how wide a field may be on the element itself
+(`data-maxwidth="85"`), which is not SVG — resvg drops it. `fit.mjs` reads the
+constraint from the source, measures the rendered text with
+`node(id).extent()`, and compresses the element horizontally, composing a
+`scale(k 1)` onto whatever transform it already has (the same device those
+templates use by hand):
+
+```js
+import { fitTextWidths } from 'resvg-napi/fit.mjs'
+
+const { svg, adjustments, problems } = fitTextWidths(source,
+  (s) => new Resvg(s, { fontFamily }, fonts))
+// adjustments: [{ id: 'surname', from: 200.23, to: 90, factor: 0.4495, measured: 90.0031 }]
+```
+
+The limit is read in **the document's own units**, the ones the attribute is
+written in. That matters: `width="85.6mm"` with a `viewBox` 240.94 wide makes usvg
+normalise the tree to 323.53 units, so `extent()` comes back 1.343× larger than
+anything the file says. Comparing raw canvas widths compresses text that actually
+fits — everything past `limit / 1.343`.
+
+No `id` needed: an element that has none gets one generated, numbered in document
+order, so the constraint does not depend on the template carrying ids. The scale
+is anchored at the element's own `x` — a bare `scale()` is anchored at the origin
+and slides the text left as it narrows.
+
+A geometric scale is exactly linear in width, so one pass lands on the target;
+the second measurement is a check, and it is reported. Text that already fits is
+left untouched, and a constraint that cannot be honoured says why: no `id` to
+measure by, no visible extent, or an unusable width. It compresses glyphs rather
+than reducing `font-size` — the choice the templates already made.
+
+## Diagnostics
+
+usvg and resvg report every recoverable problem through the `log` crate —
+unparsable values, skipped shapes, unmatched font families, images that could not
+be read. Nothing consumes that by default, so those messages used to vanish:
+
+```js
+import { setLogLevel, takeLogs, Resvg } from 'resvg-napi'
+
+setLogLevel('warn')            // off | error | warn | info | debug | trace
+new Resvg(svg).renderPng()
+takeLogs()
+// [ "WARN usvg::parser::style: Failed to parse fill value: 'notacolour'. Fallback to black.",
+//   "WARN usvg::parser::shapes: Rect '' has an invalid 'width' value. Skipped." ]
+```
+
+`takeLogs()` drains the buffer, which is capped at 500 entries so a pathological
+document cannot grow it without end.
+
+## Elsewhere
+
+- **[demo/](demo/README.md)** — a browser proof bench: Liquid templating, an
+  array editor, per-element export, live diagnostics. `npm run demo`.
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — how the bindings are generated, and
+  what to read before touching `build.rs`.
+
+## Licence
+
+Apache-2.0 OR MIT, matching resvg.

package/browser.js

@@ -0,0 +1 @@
+export * from 'resvg-napi-wasm32-wasi'

package/fit.d.mts

@@ -0,0 +1,62 @@
+/**
+ * Horizontal text fitting, driven by `data-maxwidth`.
+ *
+ * Declarations for `fit.mjs`, which is JavaScript with JSDoc: written by hand,
+ * unlike `index.d.ts`, so they can drift. `npm run typecheck` reads them.
+ */
+
+/** A `Resvg` instance, however the caller chose to build one. */
+type Renderer = {
+  node(id: string): { extent(): { width: number } | null } | null
+}
+
+/** One element carrying a width constraint, and what is needed to rewrite it. */
+export interface WidthConstraint {
+  /** The element's opening tag, verbatim. */
+  tag: string
+  /** The tag name: `text`, `tspan`, ... */
+  name: string
+  /** The attribute text inside that tag, verbatim. */
+  attrs: string
+  /** The element's `id`, or null when it had none and one must be generated. */
+  id: string | null
+  /** The limit, in the document's own units -- not canvas pixels. */
+  max: number
+  /** Byte offset of the tag in the source string. */
+  index: number
+}
+
+/** One element that was compressed, and by how much. */
+export interface Adjustment {
+  id: string
+  /** Measured width before, in the document's units. */
+  from: number
+  /** The limit it was fitted to. */
+  to: number
+  /** The horizontal scale applied: `to / from`. */
+  factor: number
+  /** Measured width after, as a check on the one-pass assumption. */
+  measured: number
+}
+
+export interface FitResult {
+  /** The source, with a `scale(k 1)` composed onto each fitted element. */
+  svg: string
+  adjustments: Adjustment[]
+  /** Constraints that could not be honoured, each saying why. */
+  problems: string[]
+}
+
+/** Elements carrying a width constraint, with the tag text needed to rewrite it. */
+export function findWidthConstraints(svg: string): WidthConstraint[]
+
+/**
+ * Fits every `data-maxwidth` element by compressing it horizontally.
+ *
+ * @param svg     source, after any templating
+ * @param render  `(svg) => Resvg`; supply fonts and options here
+ */
+export function fitTextWidths(
+  svg: string,
+  render: (svg: string) => Renderer,
+): FitResult

package/fit.mjs

@@ -0,0 +1,170 @@
+// Horizontal fitting for text that must not exceed a width, the way an
+// Illustrator template expresses it: `data-maxwidth` on the element itself.
+//
+// resvg drops attributes it does not know, so the constraint can only be read
+// from the source. The measurement, on the other hand, comes from the render:
+// `node(id).extent()` is the width the text actually occupies with the fonts in
+// hand -- which is the only number that matters.
+//
+// The correction is a horizontal scale appended to the element's own transform,
+// matching what these templates already do (`scale(1.11 1)`). A pure geometric
+// scale is exactly linear in width, so one pass lands on the target; the second
+// measurement is a check, not an iteration.
+
+const ATTR = 'data-maxwidth';
+
+/**
+ * Ratio between the tree's canvas units and the document's own coordinates.
+ *
+ * `width="85.6mm" viewBox="0 0 240.94 …"` makes usvg normalise the tree to the
+ * physical size (323.53 units at 96 dpi), so `extent()` comes back 1.343× larger
+ * than the numbers written in the file. A limit expressed in the document's own
+ * units has to be compared in those units, or everything wider than
+ * `limit / ratio` gets compressed while it actually fits.
+ */
+function unitScale(svg, canvasWidth) {
+  const viewBox = svg.match(/\bviewBox\s*=\s*"\s*[-\d.]+[\s,]+[-\d.]+[\s,]+([\d.]+)/);
+  const width = viewBox ? Number(viewBox[1]) : NaN;
+  if (!Number.isFinite(width) || width <= 0) return 1;
+  return canvasWidth / width;
+}
+
+/** Elements carrying a width constraint, with the tag text needed to rewrite it. */
+export function findWidthConstraints(svg) {
+  const found = [];
+  for (const match of svg.matchAll(/<([a-zA-Z][\w:.-]*)\b([^>]*?)(\/?)>/g)) {
+    const [tag, name, attrs] = match;
+    const max = attrs.match(new RegExp(`${ATTR}\\s*=\\s*"([^"]*)"`))?.[1];
+    if (max === undefined) continue;
+    const width = Number(max);
+    const id = attrs.match(/\bid\s*=\s*"([^"]*)"/)?.[1];
+    found.push({ tag, name, attrs, id, max: width, index: match.index });
+  }
+  return found;
+}
+
+/**
+ * Appends a horizontal scale to a tag's transform, creating one if absent.
+ *
+ * Anchored at the element's own `x`: a bare `scale()` is anchored at the origin,
+ * which slides the text left as it narrows -- 30.72 to 3.98 on a `x="28"` text.
+ * `translate(x) scale(k) translate(-x)` compresses it in place, and collapses to
+ * a plain scale when x is 0, which is the case for anything positioned by a
+ * transform.
+ */
+function withHorizontalScale(tag, attrs, factor) {
+  // `x` may be a list for per-glyph positioning; the first value is the anchor.
+  const anchor = Number.parseFloat(attrs.match(/\bx\s*=\s*"\s*([-\d.]+)/)?.[1] ?? '0') || 0;
+  const scale = anchor
+    ? `translate(${round(anchor)} 0) scale(${round(factor)} 1) translate(${round(-anchor)} 0)`
+    : `scale(${round(factor)} 1)`;
+  const existing = attrs.match(/\btransform\s*=\s*"([^"]*)"/);
+  if (existing) {
+    // Composed on the right: the element keeps its position, the glyphs
+    // compress toward the anchor the transform established.
+    return tag.replace(existing[0], `transform="${existing[1].trim()} ${scale}"`);
+  }
+  return tag.replace(/(\/?)>$/, ` transform="${scale}"$1>`);
+}
+
+const round = (n) => Math.round(n * 10000) / 10000;
+
+/**
+ * Measuring goes through `node(id)`, but a template has no reason to carry ids
+ * just to be measurable. Elements that lack one get a generated id, checked
+ * against the source so it cannot collide.
+ *
+ * Insertions run backwards so the offsets still ahead of them stay valid. The
+ * caller then re-reads the constraints from the rewritten source: patching the
+ * old offsets by hand is how the first version corrupted the document.
+ */
+function ensureIds(svg) {
+  const missing = findWidthConstraints(svg).filter((c) => !c.id);
+  if (!missing.length) return svg;
+
+  // Numbered in document order, so a diagnostic about `fit-1` refers to the
+  // first constrained element, then spliced back to front.
+  let n = 0;
+  const named = missing.map((c) => {
+    let id;
+    do {
+      id = `fit-${++n}`;
+    } while (svg.includes(`"${id}"`));
+    return { ...c, id };
+  });
+
+  let out = svg;
+  for (const c of named.reverse()) {
+    const tagged = c.tag.replace(/^<([a-zA-Z][\w:.-]*)/, `<$1 id="${c.id}"`);
+    out = out.slice(0, c.index) + tagged + out.slice(c.index + c.tag.length);
+  }
+  return out;
+}
+
+/**
+ * Fits every `data-maxwidth` element by compressing it horizontally.
+ *
+ * @param svg     source, after any templating
+ * @param render  (svg) => Resvg instance; supply fonts and options here
+ * @returns { svg, adjustments, problems }
+ */
+export function fitTextWidths(svg, render) {
+  const problems = [];
+  if (!findWidthConstraints(svg).length) return { svg, adjustments: [], problems };
+
+  // Every constrained element carries an id from here on, and the offsets are
+  // read from this exact string.
+  svg = ensureIds(svg);
+  const constraints = findWidthConstraints(svg);
+
+  let doc;
+  try {
+    doc = render(svg);
+  } catch (e) {
+    return { svg, adjustments: [], problems: [`could not measure: ${e.message}`] };
+  }
+
+  // Every width below is in the document's own units, like the attribute.
+  const scale = unitScale(svg, doc.width);
+  let out = svg;
+  const adjustments = [];
+  const splices = [];
+  for (const c of constraints) {
+    if (!Number.isFinite(c.max) || c.max <= 0) {
+      problems.push(`#${c.id}: ${ATTR}="${c.max}" is not a usable width`);
+      continue;
+    }
+    const extent = doc.node(c.id)?.extent();
+    if (!extent) {
+      problems.push(`#${c.id} has no visible extent: nothing to fit`);
+      continue;
+    }
+    const width = extent.width / scale;
+    if (width <= c.max) continue;
+
+    const factor = c.max / width;
+    splices.push({ index: c.index, length: c.tag.length,
+                   text: withHorizontalScale(c.tag, c.attrs, factor) });
+    adjustments.push({ id: c.id, from: round(width), to: c.max, factor: round(factor) });
+  }
+
+  // Backwards, so each offset still points where it did when it was taken.
+  for (const s of splices.sort((a, b) => b.index - a.index)) {
+    out = out.slice(0, s.index) + s.text + out.slice(s.index + s.length);
+  }
+
+  if (!adjustments.length) return { svg: out, adjustments, problems };
+
+  // Verify rather than trust: report what the widths actually became.
+  try {
+    const after = render(out);
+    const afterScale = unitScale(out, after.width);
+    for (const a of adjustments) {
+      const got = after.node(a.id)?.extent()?.width;
+      a.measured = got === undefined ? NaN : round(got / afterScale);
+    }
+  } catch (e) {
+    problems.push(`could not verify: ${e.message}`);
+  }
+  return { svg: out, adjustments, problems };
+}