postext-pdf 1.4.2 → 1.5.1

package/dist/__tests__/tocTagging.test.js

@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import fs from 'node:fs';
+import { PDFArray, PDFDict, PDFDocument, PDFHexString, PDFName, PDFRef, PDFString } from 'pdf-lib';
+import fontkit from '@pdf-lib/fontkit';
+import { buildDocument } from 'postext';
+import { renderToPdf } from '../pdf-backend';
+import { parseFontString } from '../fontString';
+// EF-145: the rows of a `:::toc` were tagged like body text. An unnumbered
+// row was `P › Link`, and a numbered one, whose number is painted as a
+// list marker, a one-item list of its own (`L › LI › Lbl + LBody › Link`).
+// They are now one `TOC` with a `TOCI` per row, in row order: `Lbl` for the
+// number, `Reference › Link` for the title and page (PDF 1.7 §14.8.4.3.2).
+const fontBytes = fs.readFileSync(new URL('../../../../apps/web/public/fonts/Lora-Regular.ttf', import.meta.url));
+const fontProvider = async () => new Uint8Array(fontBytes);
+const face = fontkit.create(fontBytes);
+class StubCtx {
+    font = '';
+    measureText(s) {
+        const sizePx = parseFontString(this.font)?.sizePx ?? 16;
+        const run = face.layout(s);
+        return { width: (run.advanceWidth / face.unitsPerEm) * sizePx };
+    }
+}
+globalThis.OffscreenCanvas = class {
+    getContext() {
+        return new StubCtx();
+    }
+};
+const pt = (value) => ({ value, unit: 'pt' });
+const filler = (n) => Array.from({ length: n }, (_, i) => `Paragraph ${i} with enough words to consume vertical space and force the page to overflow.`).join('\n\n');
+const config = {
+    page: {
+        width: pt(360), height: pt(300),
+        margins: { top: pt(18), bottom: pt(18), left: pt(18), right: pt(18) },
+    },
+    layout: { layoutType: 'single' },
+    locale: 'en-us',
+    headings: { levels: [{ level: 1, breakBefore: { enabled: true, parity: 'odd' } }] },
+    headingStyles: [{ id: 'front', numbered: false }],
+    toc: { levels: [{ level: 1 }, { level: 2 }], parts: { enabled: true } },
+};
+const book = `# Contents {style="front" toc="false"}
+
+:::toc
+
+# Preface {style="front"}
+
+${filler(2)}
+
+:::part{number="I" title="Foundations"}
+:::
+
+# The lantern
+
+${filler(2)}
+
+## Wicks
+
+${filler(1)}
+
+# Trimming
+
+${filler(1)}`;
+const textOf = (v) => (v instanceof PDFHexString || v instanceof PDFString ? v.decodeText() : undefined);
+function readElem(pdf, ref) {
+    const dict = pdf.context.lookup(ref, PDFDict);
+    const elem = { type: dict.get(PDFName.of('S')).decodeText(), kids: [] };
+    const k = dict.get(PDFName.of('K'));
+    for (const kid of k instanceof PDFArray ? k.asArray() : k ? [k] : []) {
+        if (kid instanceof PDFRef)
+            elem.kids.push(readElem(pdf, kid));
+        else if (kid instanceof PDFDict && kid.get(PDFName.of('Type'))?.decodeText() === 'OBJR') {
+            elem.contents = textOf(kid.lookup(PDFName.of('Obj'), PDFDict).get(PDFName.of('Contents')));
+        }
+    }
+    return elem;
+}
+let root;
+beforeAll(async () => {
+    const doc = buildDocument({ markdown: book, metadata: { title: 'Contents book' } }, config);
+    const bytes = await renderToPdf(doc, { fontProvider });
+    const out = process.env.POSTEXT_TOC_TAGS_PDF_OUT;
+    if (out)
+        fs.writeFileSync(out, bytes);
+    const pdf = await PDFDocument.load(bytes);
+    const treeRoot = pdf.catalog.lookup(PDFName.of('StructTreeRoot'), PDFDict);
+    root = readElem(pdf, treeRoot.get(PDFName.of('K')).get(0));
+}, 60_000);
+describe('contents rows in the tagged PDF (EF-145)', () => {
+    it('tags the contents as one TOC, right after its heading', () => {
+        const tocs = root.kids.filter((k) => k.type === 'TOC');
+        expect(tocs).toHaveLength(1);
+        expect(root.kids[0].type).toBe('H1');
+        expect(root.kids[1].type).toBe('TOC');
+        // No row left as a paragraph or a one-item list.
+        expect(root.kids.slice(2, 4).map((k) => k.type)).not.toContain('L');
+    });
+    it('gives every row a TOCI, in row order, the part row included', () => {
+        const toc = root.kids.find((k) => k.type === 'TOC');
+        expect(toc.kids.every((k) => k.type === 'TOCI')).toBe(true);
+        const linkText = (item) => {
+            const ref = item.kids.find((k) => k.type === 'Reference');
+            return ref.kids.find((k) => k.type === 'Link').contents ?? '';
+        };
+        // The link's description: the row's text and page, a part's number and title.
+        const rows = toc.kids.map(linkText);
+        const expected = ['Preface', 'I Foundations', 'The lantern', 'Wicks', 'Trimming'];
+        expect(rows).toHaveLength(expected.length);
+        rows.forEach((row, i) => expect(row.startsWith(expected[i]), `${row} / ${expected[i]}`).toBe(true));
+    });
+    it('labels a numbered row\'s number and links its title', () => {
+        const toc = root.kids.find((k) => k.type === 'TOC');
+        const lantern = toc.kids[2];
+        expect(lantern.kids.map((k) => k.type)).toEqual(['Lbl', 'Reference']);
+        expect(lantern.kids[1].kids.map((k) => k.type)).toEqual(['Link']);
+        const preface = toc.kids[0];
+        expect(preface.kids.map((k) => k.type)).toEqual(['Reference']);
+    });
+});
+//# sourceMappingURL=tocTagging.test.js.map

package/dist/__tests__/tocTagging.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tocTagging.test.js","sourceRoot":"","sources":["../../src/__tests__/tocTagging.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/trackedLineAlign.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=trackedLineAlign.test.d.ts.map

package/dist/__tests__/trackedLineAlign.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackedLineAlign.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/trackedLineAlign.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/trackedLineAlign.test.js

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import { PDFArray, PDFDocument, PDFRawStream, decodePDFRawStream } from 'pdf-lib';
+import fontkit from '@pdf-lib/fontkit';
+import { buildDocument } from 'postext';
+import { renderToPdf } from '../pdf-backend';
+import { parseFontString } from '../fontString';
+// EF-153 for text in the flow: a centred or right-aligned tracked line is
+// placed by its letters, the tracking after the last one left out, as on
+// canvas, in HTML and in design text.
+const fontBytes = fs.readFileSync(new URL('../../../../apps/web/public/fonts/Lora-Regular.ttf', import.meta.url));
+const fontProvider = async () => new Uint8Array(fontBytes);
+const face = fontkit.create(fontBytes);
+class StubCtx {
+    font = '';
+    measureText(s) {
+        const sizePx = parseFontString(this.font)?.sizePx ?? 16;
+        const run = face.layout(s);
+        return { width: (run.advanceWidth / face.unitsPerEm) * sizePx };
+    }
+}
+globalThis.OffscreenCanvas = class {
+    getContext() {
+        return new StubCtx();
+    }
+};
+const pt = (value) => ({ value, unit: 'pt' });
+/** 72 dpi: 1 pt = 1 px. An H1 tracked 3 pt. */
+const config = (textAlign) => ({
+    page: { width: pt(300), height: pt(200), dpi: 72, margins: { top: pt(20), bottom: pt(20), left: pt(20), right: pt(20) } },
+    layout: { layoutType: 'single' },
+    headings: { textAlign, levels: [{ level: 1, letterSpacing: pt(3), breakBefore: { enabled: false } }] },
+});
+async function contentOf(doc) {
+    const pdf = await PDFDocument.load(await renderToPdf(doc, { fontProvider, accessible: false }));
+    const contents = pdf.getPage(0).node.Contents();
+    const refs = contents instanceof PDFArray ? contents.asArray() : [contents];
+    return refs
+        .map((ref) => {
+        const s = pdf.context.lookup(ref);
+        return s instanceof PDFRawStream ? new TextDecoder('latin1').decode(decodePDFRawStream(s).decode()) : '';
+    })
+        .join('\n');
+}
+/** The x (pt) of the first text object on the heading's baseline. */
+async function headingX(doc) {
+    const heading = doc.blocks.find((b) => b.type === 'heading');
+    const y = doc.pages[0].height - heading.lines[0].baseline;
+    const content = await contentOf(doc);
+    for (const m of content.matchAll(/1 0 0 1 ([\d.-]+) ([\d.-]+) Tm/g)) {
+        if (Math.abs(Number(m[2]) - y) < 0.01)
+            return Number(m[1]);
+    }
+    throw new Error('heading text not found');
+}
+describe('tracked flow lines in the PDF (EF-153)', () => {
+    it('centres and right-aligns a tracked heading by its letters', async () => {
+        for (const [align, share] of [['left', 0], ['center', 0.5], ['right', 1]]) {
+            const doc = buildDocument({ markdown: '# Title\n\nText.' }, config(align));
+            const heading = doc.blocks.find((b) => b.type === 'heading');
+            expect(heading.letterSpacing).toBeCloseTo(3, 6);
+            // The line's width counts 3 pt after the final 'e'; its letters end
+            // 3 pt sooner.
+            const slack = heading.bbox.width - (heading.lines[0].bbox.width - 3);
+            expect(await headingX(doc)).toBeCloseTo(heading.bbox.x + slack * share, 1);
+            // A line without segments takes the same position.
+            for (const line of heading.lines)
+                delete line.segments;
+            expect(await headingX(doc)).toBeCloseTo(heading.bbox.x + slack * share, 1);
+        }
+    }, 60_000);
+});
+//# sourceMappingURL=trackedLineAlign.test.js.map

package/dist/__tests__/trackedLineAlign.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackedLineAlign.test.js","sourceRoot":"","sources":["../../src/__tests__/trackedLineAlign.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/uriLinks.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=uriLinks.test.d.ts.map

package/dist/__tests__/uriLinks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uriLinks.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/uriLinks.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/uriLinks.test.js

@@ -0,0 +1,103 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import { PDFArray, PDFDict, PDFDocument, PDFHexString, PDFName, PDFNumber, PDFString } from 'pdf-lib';
+import fontkit from '@pdf-lib/fontkit';
+import { buildDocument } from 'postext';
+import { renderToPdf } from '../pdf-backend';
+import { parseFontString } from '../fontString';
+// EF-36: the words of a Markdown link carry its URL (`VDTLineSegment.href`)
+// and the PDF makes them a live link — one URI link annotation per run of
+// linked words on a line, and a `Link` element in a tagged PDF.
+const fontBytes = fs.readFileSync(new URL('../../../../apps/web/public/fonts/Lora-Regular.ttf', import.meta.url));
+const face = fontkit.create(fontBytes);
+class StubCtx {
+    font = '';
+    measureText(s) {
+        const sizePx = parseFontString(this.font)?.sizePx ?? 16;
+        return { width: (face.layout(s).advanceWidth / face.unitsPerEm) * sizePx };
+    }
+}
+globalThis.OffscreenCanvas = class {
+    getContext() {
+        return new StubCtx();
+    }
+};
+const pt = (value) => ({ value, unit: 'pt' });
+const config = {
+    page: { width: pt(360), height: pt(360), margins: { top: pt(20), bottom: pt(20), left: pt(20), right: pt(20) } },
+    bodyText: { fontFamily: 'Lora' },
+    headings: { fontFamily: 'Lora', levels: [{ level: 1, breakBefore: { enabled: false } }] },
+};
+function uriAnnots(pdf, pageIndex = 0) {
+    const annots = pdf.getPage(pageIndex).node.lookup(PDFName.of('Annots'));
+    if (!(annots instanceof PDFArray))
+        return [];
+    const out = [];
+    for (let i = 0; i < annots.size(); i++) {
+        const a = annots.lookup(i);
+        if (!(a instanceof PDFDict))
+            continue;
+        const action = a.lookup(PDFName.of('A'));
+        if (!(action instanceof PDFDict))
+            continue;
+        const uri = action.lookup(PDFName.of('URI'));
+        const rect = a.lookup(PDFName.of('Rect'));
+        const contents = a.lookup(PDFName.of('Contents'));
+        const sp = a.lookup(PDFName.of('StructParent'));
+        out.push({
+            uri: uri instanceof PDFString || uri instanceof PDFHexString ? uri.decodeText() : String(uri),
+            rect: rect instanceof PDFArray ? rect.asArray().map((n) => n.asNumber()) : [],
+            ...(contents instanceof PDFHexString || contents instanceof PDFString ? { contents: contents.decodeText() } : {}),
+            ...(sp instanceof PDFNumber ? { structParent: sp.asNumber() } : {}),
+        });
+    }
+    return out;
+}
+async function render(markdown, accessible = true, resources = []) {
+    const doc = buildDocument({ markdown, resources }, config);
+    const bytes = await renderToPdf(doc, { fontProvider: async () => new Uint8Array(fontBytes), accessible });
+    return PDFDocument.load(bytes);
+}
+describe('renderToPdf — Markdown links (EF-36)', () => {
+    it('annotates each linked run with a URI action, absolute URLs only', async () => {
+        const pdf = await render('Visit [the site](https://postext.dev/docs) today, or [write](mailto:team@postext.example). A [relative guide](../guide) stays text.');
+        const annots = uriAnnots(pdf);
+        expect(annots.map((a) => a.uri)).toEqual(['https://postext.dev/docs', 'mailto:team@postext.example']);
+        // "the site": one annotation spanning both words.
+        const [site] = annots;
+        expect(site.rect[2] - site.rect[0]).toBeGreaterThan(20);
+        expect(site.contents).toBe('the site');
+        expect(site.structParent).toBeTypeOf('number');
+    });
+    it('splits a link broken across lines into one annotation per line', async () => {
+        const words = 'a long run of linked words that has to wrap over more than one line of this narrow page';
+        const pdf = await render(`Before [${words}](https://postext.dev/wrap) after.`);
+        const annots = uriAnnots(pdf).filter((a) => a.uri === 'https://postext.dev/wrap');
+        expect(annots.length).toBeGreaterThan(1);
+        // Lines go down the page.
+        for (let i = 1; i < annots.length; i++)
+            expect(annots[i].rect[1]).toBeLessThan(annots[i - 1].rect[1]);
+    });
+    it('annotates links in captions and table cells, and in an untagged PDF too', async () => {
+        const resources = [{
+                id: 't',
+                typeId: 'table',
+                kind: 'table',
+                caption: 'From [the census](https://a.example/census).',
+                createdAt: 0,
+                updatedAt: 0,
+                table: { model: { rows: [[{ content: 'See [row](https://a.example/row)' }]] } },
+                placement: { position: 'here' },
+            }];
+        const pdf = await render('Text.\n\n::resource{id="t"}', false, resources);
+        const uris = uriAnnots(pdf).map((a) => a.uri).sort();
+        expect(uris).toEqual(['https://a.example/census', 'https://a.example/row']);
+        expect(uriAnnots(pdf).every((a) => a.structParent === undefined)).toBe(true);
+    });
+    it('percent-encodes characters a PDF URI cannot hold', async () => {
+        const pdf = await render('See [niño](https://a.example/año?q=(1)) here.');
+        // Balanced parentheses belong to the destination, as CommonMark reads it.
+        expect(uriAnnots(pdf)[0].uri).toBe('https://a.example/a%C3%B1o?q=(1)');
+    });
+});
+//# sourceMappingURL=uriLinks.test.js.map

package/dist/__tests__/uriLinks.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uriLinks.test.js","sourceRoot":"","sources":["../../src/__tests__/uriLinks.test.ts"],"names":[],"mappings":"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"}

package/dist/colors.d.ts

@@ -9,12 +9,27 @@ export interface CmykTuple {
     y: number;
     k: number;
 }
+export interface RgbaTuple extends RgbTuple {
+    /** Opacity, 0 (clear) … 1 (opaque). */
+    a: number;
+}
+/**
+ * Parse the colour strings a postext document carries — `#rgb`, `#rgba`,
+ * `#rrggbb`, `#rrggbbaa`, `rgb()` / `rgba()` (comma or space syntax, with a
+ * `/ alpha`) and `transparent` — into 0..1 RGB components plus an opacity.
+ * Null for anything else (a keyword such as `red` or `none`, a typo).
+ */
+export declare function parseCssColor(value: string): RgbaTuple | null;
 /**
- * Parse a CSS hex color (3, 4, 6 or 8 hex digits with a leading `#`) into
- * normalized 0..1 RGB components suitable for pdf-lib's `rgb()` factory.
- * Alpha channels and malformed inputs are ignored and fall back to black.
+ * Parse a document colour (see {@link parseCssColor}) into normalized 0..1
+ * RGB components suitable for pdf-lib's `rgb()` factory. The alpha channel
+ * is dropped (read it with {@link colorAlpha}); malformed inputs fall back
+ * to black.
  */
 export declare function hexToRgb(hex: string): RgbTuple;
+/** Opacity of a document colour, 0 … 1; 1 when it carries none or does not
+ *  parse. */
+export declare function colorAlpha(value: string): number;
 /** Naive RGB → CMYK conversion (no ICC profile). Adequate for forcing a
  *  4-channel output when the source is authored in sRGB hex. */
 export declare function rgbToCmyk({ r, g, b }: RgbTuple): CmykTuple;

package/dist/colors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAuB9C;AAED;gEACgE;AAChE,wBAAgB,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,GAAG,SAAS,CAU1D;AAED,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAE5D"}
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,SAAU,SAAQ,QAAQ;IACzC,uCAAuC;IACvC,CAAC,EAAE,MAAM,CAAC;CACX;AAqBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAmC7D;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAG9C;AAED;aACa;AACb,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;gEACgE;AAChE,wBAAgB,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,GAAG,SAAS,CAU1D;AAED,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAE5D"}

package/dist/colors.js

@@ -1,33 +1,85 @@
+const HEX_DIGITS_RE = /^[0-9a-f]+$/i;
+/** A CSS `rgb()` channel (`0…255` or a percentage) as 0..1; null when
+ *  malformed. */
+function rgbChannel(token) {
+    const pct = token.endsWith('%');
+    const n = Number(pct ? token.slice(0, -1) : token);
+    if (token === '' || !Number.isFinite(n))
+        return null;
+    return Math.max(0, Math.min(1, pct ? n / 100 : n / 255));
+}
+/** A CSS alpha value (`0…1` or a percentage); null when malformed. */
+function alphaChannel(token) {
+    const pct = token.endsWith('%');
+    const n = Number(pct ? token.slice(0, -1) : token);
+    if (token === '' || !Number.isFinite(n))
+        return null;
+    return Math.max(0, Math.min(1, pct ? n / 100 : n));
+}
 /**
- * Parse a CSS hex color (3, 4, 6 or 8 hex digits with a leading `#`) into
- * normalized 0..1 RGB components suitable for pdf-lib's `rgb()` factory.
- * Alpha channels and malformed inputs are ignored and fall back to black.
+ * Parse the colour strings a postext document carries — `#rgb`, `#rgba`,
+ * `#rrggbb`, `#rrggbbaa`, `rgb()` / `rgba()` (comma or space syntax, with a
+ * `/ alpha`) and `transparent` — into 0..1 RGB components plus an opacity.
+ * Null for anything else (a keyword such as `red` or `none`, a typo).
  */
-export function hexToRgb(hex) {
-    if (!hex || typeof hex !== 'string')
-        return { r: 0, g: 0, b: 0 };
-    let s = hex.trim();
-    if (s.startsWith('#'))
-        s = s.slice(1);
-    if (s.length === 3 || s.length === 4) {
-        const r = parseInt(s[0] + s[0], 16);
-        const g = parseInt(s[1] + s[1], 16);
-        const b = parseInt(s[2] + s[2], 16);
-        if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b)) {
-            return { r: 0, g: 0, b: 0 }; // `none`, `red`… are not hex digits
+export function parseCssColor(value) {
+    if (!value || typeof value !== 'string')
+        return null;
+    const s = value.trim();
+    if (s.toLowerCase() === 'transparent')
+        return { r: 0, g: 0, b: 0, a: 0 };
+    if (s.startsWith('#')) {
+        const h = s.slice(1);
+        if (!HEX_DIGITS_RE.test(h))
+            return null;
+        const byte = (i, short) => parseInt(short ? h[i] + h[i] : h.slice(i * 2, i * 2 + 2), 16) / 255;
+        if (h.length === 3 || h.length === 4) {
+            return { r: byte(0, true), g: byte(1, true), b: byte(2, true), a: h.length === 4 ? byte(3, true) : 1 };
         }
-        return { r: r / 255, g: g / 255, b: b / 255 };
-    }
-    if (s.length === 6 || s.length === 8) {
-        const r = parseInt(s.slice(0, 2), 16);
-        const g = parseInt(s.slice(2, 4), 16);
-        const b = parseInt(s.slice(4, 6), 16);
-        if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b)) {
-            return { r: 0, g: 0, b: 0 };
+        if (h.length === 6 || h.length === 8) {
+            return { r: byte(0, false), g: byte(1, false), b: byte(2, false), a: h.length === 8 ? byte(3, false) : 1 };
         }
-        return { r: r / 255, g: g / 255, b: b / 255 };
+        return null;
+    }
+    const fn = /^rgba?\(\s*([^)]*?)\s*\)$/i.exec(s);
+    if (!fn)
+        return null;
+    // `r, g, b[, a]` or `r g b[ / a]`.
+    const body = fn[1];
+    let parts;
+    let alpha;
+    if (body.includes(',')) {
+        parts = body.split(',').map((p) => p.trim());
+        if (parts.length === 4)
+            alpha = parts.pop();
+    }
+    else {
+        const [channels, slashAlpha] = body.split('/').map((p) => p.trim());
+        parts = (channels ?? '').split(/\s+/).filter(Boolean);
+        alpha = slashAlpha;
     }
-    return { r: 0, g: 0, b: 0 };
+    if (parts.length !== 3)
+        return null;
+    const [r, g, b] = parts.map(rgbChannel);
+    const a = alpha === undefined ? 1 : alphaChannel(alpha);
+    if (r == null || g == null || b == null || a == null)
+        return null;
+    return { r, g, b, a };
+}
+/**
+ * Parse a document colour (see {@link parseCssColor}) into normalized 0..1
+ * RGB components suitable for pdf-lib's `rgb()` factory. The alpha channel
+ * is dropped (read it with {@link colorAlpha}); malformed inputs fall back
+ * to black.
+ */
+export function hexToRgb(hex) {
+    const c = parseCssColor(hex);
+    return c ? { r: c.r, g: c.g, b: c.b } : { r: 0, g: 0, b: 0 };
+}
+/** Opacity of a document colour, 0 … 1; 1 when it carries none or does not
+ *  parse. */
+export function colorAlpha(value) {
+    return parseCssColor(value)?.a ?? 1;
 }
 /** Naive RGB → CMYK conversion (no ICC profile). Adequate for forcing a
  *  4-channel output when the source is authored in sRGB hex. */

package/dist/colors.js.map

@@ -1 +1 @@
-{"version":3,"file":"colors.js","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"colors.js","sourceRoot":"","sources":["../src/colors.ts"],"names":[],"mappings":"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"}

package/dist/fontCache.d.ts

@@ -1,4 +1,4 @@
-import type { PDFDocument, PDFFont } from 'pdf-lib';
+import { type PDFDocument, type PDFFont } from 'pdf-lib';
 /** pdf-lib builds a CID font's `W` (advance widths) array from the glyphs
  *  reachable through the cmap, so a face embedded whole leaves every
  *  GSUB-only glyph — the fi/fl ligatures, contextual alternates — at the
@@ -22,20 +22,83 @@ export declare function toUnicodeCmap(glyphs: Array<{
  */
 export declare function coverAllGlyphUnicode(font: PDFFont): void;
 export type PdfFontProvider = (family: string, weight: number, style: 'normal' | 'italic') => Promise<Uint8Array>;
+/** A face the document asked for, and the face of the same family set in
+ *  its place because the provider rejected it (see
+ *  {@link FontCache.preloadFontStrings}). */
+export interface FontFallback {
+    family: string;
+    weight: number;
+    style: 'normal' | 'italic';
+    fallback: {
+        weight: number;
+        style: 'normal' | 'italic';
+    };
+    /** The provider's error message for the requested face. */
+    reason: string;
+}
+interface FaceSpec {
+    family: string;
+    weight: number;
+    style: 'normal' | 'italic';
+}
+/** `weights` in the order CSS font matching tries them for `desired`
+ *  (CSS Fonts 4 §5.2): from 400 to 500, the weights up to 500 ascending,
+ *  then the lighter ones descending, then the heavier ones ascending; below
+ *  400, lighter (or equal) descending, then heavier ascending; above 500,
+ *  heavier (or equal) ascending, then lighter descending. The browser picks
+ *  the same face, so the PDF matches the preview. */
+export declare function cssWeightOrder(desired: number, weights: readonly number[]): number[];
+/** Faces of the same family to try, in order, when the provider rejects
+ *  `spec`: every standard weight in the requested style, in CSS matching
+ *  order ({@link cssWeightOrder}), then every weight in the other style
+ *  the same way — italic falls back to upright, and upright to italic. A
+ *  family with no italics (a display face) sets its italic runs upright; a
+ *  family shipping only 400 and 700 takes a 600 as 700; one shipping a
+ *  single cut sets everything in it. */
+export declare function fallbackFaces(spec: FaceSpec): FaceSpec[];
 /**
  * Per-document mapping from `family|weight|style` to an embedded pdf-lib
  * font. Entries are populated up-front by `preload()` so that block-level
- * rendering (`get()`) is a sync lookup. A fontString that fails to parse or
- * to load is mapped to `null` and reported back via `missing()`.
+ * rendering (`get()`) is a sync lookup. A face the provider rejects falls
+ * back to another face of its family ({@link fallbackFaces}), reported
+ * through `onFallback`; a fontString that fails to parse, or whose family
+ * the provider cannot supply at all (no standard weight in either style),
+ * is mapped to `null` and reported back via `missing()`. Faces the
+ * provider answers with the same file share one embedded font, and
+ * `dropUnusedFonts()` keeps the fonts no page draws with out of the file.
  */
 export declare class FontCache {
     private pdfDoc;
     private provider;
+    private onFallback?;
     private map;
     private failed;
-    constructor(pdfDoc: PDFDocument, provider: PdfFontProvider);
+    /** One load per actual face, shared by every key that falls back to it. */
+    private loads;
+    private errors;
+    /** Loaded faces by lower-cased family, for lookups nothing preloaded. */
+    private byFamily;
+    /** Embeds by the byte length of their file: a provider that answers
+     *  several faces with one file (a stand-in for a cut the family lacks)
+     *  gets it embedded once, whatever the faces. */
+    private byLength;
+    /** Every font this cache embedded. */
+    private embedded;
+    constructor(pdfDoc: PDFDocument, provider: PdfFontProvider, onFallback?: ((fallback: FontFallback) => void) | undefined);
+    /** Embed a font file, once per distinct content. */
+    private embedBytes;
+    /** Fetch and embed one face, once. Null when the provider rejects it or
+     *  its bytes do not embed. */
+    private loadFace;
     preloadFontStrings(fontStrings: Iterable<string | undefined>): Promise<void>;
     get(fontString: string): PDFFont | null;
     missing(): string[];
+    /** Leave out of the file every font this cache embedded that no page
+     *  draws with: a face asked for but never set (the text of a figure
+     *  later drawn as a picture, say) would otherwise be written anyway,
+     *  since pdf-lib writes every font it embedded. Call it once all pages
+     *  are drawn, right before `save()`. */
+    dropUnusedFonts(): void;
 }
+export {};
 //# sourceMappingURL=fontCache.d.ts.map

package/dist/fontCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fontCache.d.ts","sourceRoot":"","sources":["../src/fontCache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAwBpD;;;;;gEAKgE;AAChE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAavD;AAgBD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,GAAG,MAAM,CAkBzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAyBxD;AAED,MAAM,MAAM,eAAe,GAAG,CAC5B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,QAAQ,GAAG,QAAQ,KACvB,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB;;;;;GAKG;AACH,qBAAa,SAAS;IAKlB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,QAAQ;IALlB,OAAO,CAAC,GAAG,CAAqC;IAChD,OAAO,CAAC,MAAM,CAAqB;gBAGzB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,eAAe;IAG7B,kBAAkB,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAsClF,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;IAOvC,OAAO,IAAI,MAAM,EAAE;CAGpB"}
+{"version":3,"file":"fontCache.d.ts","sourceRoot":"","sources":["../src/fontCache.ts"],"names":[],"mappings":"AACA,OAAO,EAAuC,KAAK,WAAW,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAwB9F;;;;;gEAKgE;AAChE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAavD;AAgBD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,GAAG,MAAM,CAkBzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAyBxD;AAED,MAAM,MAAM,eAAe,GAAG,CAC5B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,QAAQ,GAAG,QAAQ,KACvB,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB;;6CAE6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC3B,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAA;KAAE,CAAC;IACzD,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,QAAQ;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAC5B;AAKD;;;;;qDAKqD;AACrD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAWpF;AAED;;;;;;wCAMwC;AACxC,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAWxD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,SAAS;IAgBlB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,UAAU,CAAC;IAjBrB,OAAO,CAAC,GAAG,CAAqC;IAChD,OAAO,CAAC,MAAM,CAAqB;IACnC,2EAA2E;IAC3E,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,MAAM,CAA6B;IAC3C,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAA0D;IAC1E;;qDAEiD;IACjD,OAAO,CAAC,QAAQ,CAA2E;IAC3F,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAsB;gBAG5B,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,eAAe,EACzB,UAAU,CAAC,GAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,aAAA;IAGvD,oDAAoD;IACpD,OAAO,CAAC,UAAU;IA2BlB;kCAC8B;IAC9B,OAAO,CAAC,QAAQ;IAsBV,kBAAkB,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAqClF,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;IAgBvC,OAAO,IAAI,MAAM,EAAE;IAInB;;;;4CAIwC;IACxC,eAAe,IAAI,IAAI;CAWxB"}