resvg-napi 0.1.2 → 0.3.0

package/README.md

@@ -1,11 +1,17 @@
-# resvg-napi
+# Render and inspect SVG
 
-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.
+[![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)
 
-Generated from the upstream Rust sources, so the TypeScript surface is usvg's
-own, names and doc comments included.
+Render an SVG to PNG, and read back what the renderer made of the document — the
+resolved tree, text metrics, paint, geometry. Node.js bindings for
+[resvg](https://github.com/linebender/resvg) 0.48, generated from the upstream
+Rust sources, so the TypeScript surface is usvg's own, names and doc comments
+included.
+
+**[Try it in the browser](https://p8nut.github.io/resvg-napi/)** — the same
+bindings compiled to WASI, rendering in the page, nothing to install.
 
 ```bash
 npm install resvg-napi
@@ -20,35 +26,58 @@ 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. What follows
+is the map.
 
-`index.d.ts` is the reference — it is generated, so it cannot drift. This is
-the map.
+## Render SVG to PNG
 
-**Render.** Parse once with `new Resvg(svg, options?, fonts?, images?)`, then
-render as often as you like.
+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 |
+| `toString(opts?)` | the resolved tree, back as SVG — text as paths unless `preserveText` |
 | `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:
+## Text as outlines
+
+`toString()` hands back the resolved tree with **the text converted to paths** —
+an SVG that draws the same where the font is not installed, which is what a
+print or PDF pipeline needs from a template:
+
+```js
+const doc = new Resvg(svg, { fontFamily: 'DejaVu Sans' }, fonts)
+doc.toString()                        // one <path> per glyph, no <text>
+doc.toString({ preserveText: true })  // <text> kept, resolved but not outlined
+```
+
+The outlines come from the same layout `renderPng` draws, so a glyph sits where
+the raster puts it — and `extent()` measured it before either.
+
+## Inspect the usvg 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
+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
@@ -57,23 +86,90 @@ 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
+## Measure text and geometry
+
+Every node reports `boundingBox()`, `absBoundingBox()`, `strokeBoundingBox()`,
+`absLayerBoundingBox()` and `extent()` — in the document's own units, which is
+not the canvas. See [Fitting text to a width](#fitting-text-to-a-width) for why
 that distinction bites.
 
-**Fonts.** `FontDatabase` is `fontdb` itself: `loadSystemFonts()`,
-`loadFontData(buffer)`, `loadFontFile(path)`, `faces()`, `query()`, and the
-generic-family setters. `pendingFonts()` on a parsed document names the
-families it wanted and did not get; `pendingImages()` does the same for hrefs.
+## 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.
+
+`pendingFonts()` names the families nobody had. `faceOf(glyph)` names the face
+that drew the text instead — the substitution a document-wide list cannot show,
+and the one that survives to print:
+
+```js
+const text = doc.node('title').text()
+text.chunks[0].spans[0].font.families    // ['Brand Sans', 'DejaVu Sans'] — asked for
+for (const glyph of text.layouted[0].positionedGlyphs) {
+  doc.faceOf(glyph)?.postScriptName       // 'DejaVuSans' — what actually drew it
+}
+```
+
+`faceOf` returns `null` only for a glyph from another document: the id a glyph
+carries is a key into the font database its own document was parsed with.
+
+## Paint servers
+
+`linearGradients()`, `radialGradients()`, `patterns()`, `clipPaths()`, `masks()`,
+`filters()` — the paint servers an element's `id` refers to.
+
+## Examples
+
+Four templates in [`demo/examples/`](demo/examples), each rendered by
+`node demo/render.mjs <template.svg>`: Liquid fills the template from the JSON
+file next to it, this binding rasterises the result. The images below are that
+command's output.
+
+### Roster — a table from a JSON array
+
+![roster](https://raw.githubusercontent.com/p8nut/resvg-napi/main/demo/assets/roster.png)
+
+A `staff` array becomes rows, with an embedded logo and a QR code generated
+during templating. The fourth name runs straight into the column beside it —
+measuring that overflow, and compressing it away, is what [Fitting text to a
+width](#fitting-text-to-a-width) below is for.
 
-**Definitions.** `linearGradients()`, `radialGradients()`, `patterns()`,
-`clipPaths()`, `masks()`, `filters()` — the paint servers an element's `id`
-refers to.
+### Photo card — images and glyphs
 
-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.
+![photo card](https://raw.githubusercontent.com/p8nut/resvg-napi/main/demo/assets/photo-card.png)
+
+Everything a card does with raster images and type, and nothing it does with
+data.
+
+### Badge sheet — one template, stamped per record
+
+![badge sheet](https://raw.githubusercontent.com/p8nut/resvg-napi/main/demo/assets/badge-sheet.png)
+
+Pulls `badge.svg` in as a partial and repeats it. A guided tour, where every zone
+of the page is one Liquid capability.
+
+`sheet.svg` covers the data half — pagination, grouping, theming, and
+`--lang fr` driving `<switch systemLanguage>`, which usvg picks nothing from
+without a language.
+
+## 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
 
@@ -112,7 +208,6 @@ 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
@@ -147,7 +242,7 @@ 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
+## Warnings and logs
 
 usvg and resvg report every recoverable problem through the `log` crate —
 unparsable values, skipped shapes, unmatched font families, images that could not
@@ -166,12 +261,50 @@ takeLogs()
 `takeLogs()` drains the buffer, which is capped at 500 entries so a pathological
 document cannot grow it without end.
 
-## Elsewhere
+## Troubleshooting
+
+**A font family did not apply.** `pendingFonts()` on the parsed document names
+the families it asked for and did not get, and `faceOf(glyph)` names the face
+that was used in their place. Supply them with
+`loadFontFile(path)` or `loadFontData(buffer)` before rendering. Under WASI,
+`loadSystemFonts()` finds nothing inside the sandbox, so every face has to be
+loaded by hand.
+
+**An image did not appear.** `pendingImages()` names the hrefs that could not be
+resolved.
+
+**A measurement disagrees with the numbers in the file.** Bounding boxes are in
+the document's own units and usvg normalises the tree, so they are not canvas
+pixels. See [Fitting text to a width](#fitting-text-to-a-width) for the arithmetic.
+
+**Something was dropped and nothing said so.** usvg reports it through the `log`
+crate and nothing consumes that by default — see [Warnings and
+logs](#warnings-and-logs).
+
+**A member is missing from the TypeScript surface.** 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.
+
+## Demo
+
+A browser proof bench for the same bindings compiled to WASI: Liquid templating,
+an array editor, per-element export, live diagnostics. Deployed from `main` at
+**[p8nut.github.io/resvg-napi](https://p8nut.github.io/resvg-napi/)**, and it
+runs locally too:
+
+```bash
+npm run demo
+```
+
+![the proof bench](https://raw.githubusercontent.com/p8nut/resvg-napi/main/demo/assets/screenshot.png)
+
+[demo/README.md](demo/README.md) describes the page.
+
+## Contributing
 
-- **[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`.
+[CONTRIBUTING.md](CONTRIBUTING.md) — how the bindings are generated, and what to
+read before touching the generator.
 
 ## Licence
 

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