Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
feat(mcp-host): add the shared input, output and image modules of the artifact generators
marcoteb6171e514f2fa
diff --git a/mcp-host/src/workflow/__tests__/embeddedImages.test.ts b/mcp-host/src/workflow/__tests__/embeddedImages.test.tsnew file mode 100644index 000000000..44344d271--- /dev/null+++ b/mcp-host/src/workflow/__tests__/embeddedImages.test.ts@@ -0,0 +1,273 @@+import { afterEach, beforeEach, describe, expect, it } from 'vitest'+import { createCanvas, loadImage } from '@napi-rs/canvas'+import * as fs from 'fs'+import * as os from 'os'+import * as path from 'path'+import { fitImageSize, loadEmbeddableImage, predecodeImages } from '../embeddedImages'++let outputDir: string++beforeEach(() => {+ outputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'clerum-embed-'))+})++afterEach(() => {+ fs.rmSync(outputDir, { recursive: true, force: true })+})++async function writeImage(name: string, format: 'png' | 'jpeg' | 'webp', w = 40, h = 20) {+ const canvas = createCanvas(w, h)+ canvas.getContext('2d').fillRect(0, 0, w, h)+ const data = format === 'png' ? canvas.toBuffer('image/png') : await canvas.encode(format)+ fs.writeFileSync(path.join(outputDir, name), data)+}++/** A JPEG with an APP1 Exif segment carrying only the orientation tag. */+function withExifOrientation(jpeg: Buffer, orientation: number): Buffer {+ const tiff = Buffer.from([+ 0x4d,+ 0x4d,+ 0x00,+ 0x2a,+ 0x00,+ 0x00,+ 0x00,+ 0x08,+ 0x00,+ 0x01,+ 0x01,+ 0x12,+ 0x00,+ 0x03,+ 0x00,+ 0x00,+ 0x00,+ 0x01,+ 0x00,+ orientation,+ 0x00,+ 0x00,+ 0x00,+ 0x00,+ 0x00,+ 0x00,+ ])+ const body = Buffer.concat([Buffer.from('Exif\0\0', 'latin1'), tiff])+ const header = Buffer.from([0xff, 0xe1, (body.length + 2) >> 8, (body.length + 2) & 0xff])+ return Buffer.concat([jpeg.subarray(0, 2), header, body, jpeg.subarray(2)])+}++async function opaquePixels(png: Buffer): Promise<number> {+ const image = await loadImage(png)+ const canvas = createCanvas(image.width, image.height)+ const ctx = canvas.getContext('2d')+ ctx.drawImage(image, 0, 0)+ const data = ctx.getImageData(0, 0, image.width, image.height).data+ let count = 0+ for (let i = 3; i < data.length; i += 4) if (data[i] > 0) count+++ return count+}++describe('fitImageSize', () => {+ const box = { width: 500, height: 300 }++ it('keeps proportions and never exceeds the box, even for an explicit size', () => {+ expect(fitImageSize({ width: 1000, height: 500 }, box)).toEqual({ width: 500, height: 250 })+ expect(fitImageSize({ width: 1000, height: 500 }, box, { width: 2000 })).toEqual({+ width: 500,+ height: 250,+ })+ expect(fitImageSize({ width: 100, height: 100 }, box, { height: 900 })).toEqual({+ width: 300,+ height: 300,+ })+ })++ it('reads a width and height given together as a box to fit in', () => {+ expect(fitImageSize({ width: 100, height: 100 }, box, { width: 200, height: 100 })).toEqual({+ width: 100,+ height: 100,+ })+ expect(fitImageSize({ width: 200, height: 100 }, box, { width: 400, height: 400 })).toEqual({+ width: 400,+ height: 200,+ })+ expect(fitImageSize({ width: 100, height: 100 }, box, { width: 1000, height: 1000 })).toEqual({+ width: 300,+ height: 300,+ })+ })+})++describe('loadEmbeddableImage', () => {+ it('accepts a bare filename or an object with path', async () => {+ await writeImage('a.png', 'png')+ const warnings: string[] = []+ expect(loadEmbeddableImage('a.png', outputDir, warnings)).toMatchObject({+ format: 'png',+ width: 40,+ height: 20,+ })+ expect(loadEmbeddableImage({ path: 'a.png' }, outputDir, warnings)?.format).toBe('png')+ expect(warnings).toEqual([])+ })++ it('reads the format from the bytes and converts decoded images to opaque PNG', async () => {+ await writeImage('photo.png', 'jpeg')+ await writeImage('anim.webp', 'webp')+ fs.writeFileSync(+ path.join(outputDir, 'logo.svg'),+ '<svg xmlns="http://www.w3.org/2000/svg" width="30" height="10"><rect width="30" height="10"/></svg>'+ )+ await predecodeImages({ images: ['anim.webp', { path: 'logo.svg' }] }, outputDir)+ const warnings: string[] = []+ expect(loadEmbeddableImage('photo.png', outputDir, warnings)?.format).toBe('jpeg')+ const webp = loadEmbeddableImage('anim.webp', outputDir, warnings)+ expect(webp?.format).toBe('png')+ expect(await opaquePixels(webp!.data)).toBe(40 * 20)+ const svg = loadEmbeddableImage('logo.svg', outputDir, warnings)+ expect(svg).toMatchObject({ format: 'png', width: 30, height: 10 })+ expect(await opaquePixels(svg!.data)).toBe(30 * 10)+ expect(warnings).toEqual([])+ })++ it('finds images named inside markdown bodies', async () => {+ await writeImage('inline.webp', 'webp')+ await predecodeImages({ body: 'Intro\n\n\n' }, outputDir)+ const image = loadEmbeddableImage('inline.webp', outputDir, [])+ expect(await opaquePixels(image!.data)).toBe(40 * 20)+ })++ it('finds a body image whose name holds spaces, in each form markdown writes it', async () => {+ await writeImage('my chart.webp', 'webp')+ await writeImage('image (1).webp', 'webp')+ await predecodeImages(+ { body: '\n\n.webp "Title")' },+ outputDir+ )+ expect(loadEmbeddableImage('my chart.webp', outputDir, [])).toBeDefined()+ expect(loadEmbeddableImage('image (1).webp', outputDir, [])).toBeDefined()+ })++ it('scans a body of unclosed image openings in linear time', async () => {+ const started = performance.now()+ await predecodeImages({ body: '!['.repeat(100000) }, outputDir)+ expect(performance.now() - started).toBeLessThan(5000)+ })++ it('reports an image it was not able to decode instead of drawing it blank', async () => {+ await writeImage('late.webp', 'webp')+ const warnings: string[] = []+ expect(loadEmbeddableImage('late.webp', outputDir, warnings)).toBeUndefined()+ expect(warnings).toEqual(["'late.webp' is not an image this tool can read and was left out."])+ })++ it('rasterizes a huge SVG at a bounded size instead of its declared one', async () => {+ // The canvas library aborts the process when it cannot allocate the bitmap.+ fs.writeFileSync(+ path.join(outputDir, 'huge.svg'),+ '<svg xmlns="http://www.w3.org/2000/svg" width="32000" height="16000"><rect width="32000" height="16000"/></svg>'+ )+ fs.writeFileSync(+ path.join(outputDir, 'inches.svg'),+ '<svg xmlns="http://www.w3.org/2000/svg" width="1000in" height="1000in" viewBox="0 0 10 10"><rect width="10" height="10"/></svg>'+ )+ await predecodeImages(['huge.svg', 'inches.svg'], outputDir)+ expect(loadEmbeddableImage('huge.svg', outputDir, [])).toMatchObject({+ width: 2048,+ height: 1024,+ })+ expect(loadEmbeddableImage('inches.svg', outputDir, [])).toMatchObject({+ width: 2048,+ height: 2048,+ })+ })++ it('does not decode an image whose header declares an enormous size', async () => {+ const gif = Buffer.from(+ 'R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==',+ 'base64'+ )+ gif.writeUInt16LE(60000, 6)+ gif.writeUInt16LE(60000, 8)+ fs.writeFileSync(path.join(outputDir, 'huge.gif'), gif)+ await predecodeImages(['huge.gif'], outputDir)+ expect(loadEmbeddableImage('huge.gif', outputDir, [])).toBeUndefined()+ })++ it('leaves out, with a warning, what is missing or not an image', () => {+ fs.writeFileSync(path.join(outputDir, 'notes.png'), 'plain text')+ const warnings: string[] = []+ expect(loadEmbeddableImage('missing.png', outputDir, warnings)).toBeUndefined()+ expect(loadEmbeddableImage('notes.png', outputDir, warnings)).toBeUndefined()+ expect(loadEmbeddableImage({ width: 100 }, outputDir, warnings, 'images[2]')).toBeUndefined()+ expect(warnings).toEqual([+ "Image 'missing.png' was not found in the output folder and was left out.",+ "'notes.png' is not an image this tool can read and was left out.",+ 'images[2] needs a file name, such as the one clerum__generate_chart returns; it was left out.',+ ])+ })++ it('uses the file of the same name when given an absolute path from elsewhere', async () => {+ await writeImage('chart.png', 'png')+ const warnings: string[] = []+ const image = loadEmbeddableImage('/output/chart.png', outputDir, warnings)+ expect(image?.path).toBe(path.join(path.resolve(outputDir), 'chart.png'))+ expect(warnings[0]).toContain("'/output/chart.png' is outside the output folder")+ })++ it('refuses a link inside the output folder that points outside it', async () => {+ const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'clerum-outside-'))+ try {+ const canvas = createCanvas(4, 4)+ canvas.getContext('2d').fillRect(0, 0, 4, 4)+ fs.writeFileSync(path.join(outside, 'secret.png'), canvas.toBuffer('image/png'))+ fs.symlinkSync(path.join(outside, 'secret.png'), path.join(outputDir, 'innocent.png'))+ expect(() => loadEmbeddableImage('innocent.png', outputDir, [])).toThrow(+ /path traversal blocked/+ )+ } finally {+ fs.rmSync(outside, { recursive: true, force: true })+ }+ })++ it('says a web address is not downloaded', () => {+ const warnings: string[] = []+ expect(+ loadEmbeddableImage('https://example.com/chart.png', outputDir, warnings, 'images[0]')+ ).toBeUndefined()+ expect(warnings[0]).toContain('is a web address or inline data, and images are not downloaded')+ })++ it('turns a photo tagged with an EXIF rotation upright for every format', async () => {+ // 40x20 with the left quarter blue, tagged "rotate 90° clockwise".+ const canvas = createCanvas(40, 20)+ const ctx = canvas.getContext('2d')+ ctx.fillStyle = '#ff0000'+ ctx.fillRect(0, 0, 40, 20)+ ctx.fillStyle = '#0000ff'+ ctx.fillRect(0, 0, 10, 20)+ fs.writeFileSync(+ path.join(outputDir, 'photo.jpg'),+ withExifOrientation(canvas.toBuffer('image/jpeg'), 6)+ )+ await predecodeImages(['photo.jpg'], outputDir)+ const image = loadEmbeddableImage('photo.jpg', outputDir, [])!+ expect(image).toMatchObject({ format: 'jpeg', width: 20, height: 40 })+ const decoded = await loadImage(image.data)+ const probe = createCanvas(decoded.width, decoded.height)+ probe.getContext('2d').drawImage(decoded, 0, 0)+ const [r, , b] = probe.getContext('2d').getImageData(10, 2, 1, 1).data+ expect(b).toBeGreaterThan(200)+ expect(r).toBeLessThan(60)+ })++ it('still refuses to leave the output folder', () => {+ expect(() => loadEmbeddableImage('../../etc/passwd', outputDir, [])).toThrow(+ /path traversal blocked/+ )+ expect(() => loadEmbeddableImage('/etc/passwd', outputDir, [])).toThrow(+ /path traversal blocked/+ )+ })+})diff --git a/mcp-host/src/workflow/__tests__/inlineMarkup.test.ts b/mcp-host/src/workflow/__tests__/inlineMarkup.test.tsnew file mode 100644index 000000000..49dff7cd0--- /dev/null+++ b/mcp-host/src/workflow/__tests__/inlineMarkup.test.ts@@ -0,0 +1,209 @@+import { describe, expect, it } from 'vitest'+import {+ decodeEntities,+ htmlToMarkdownInline,+ htmlToPlainText,+ imageTarget,+ inlineSpans,+ quoteParagraphs,+ withoutClosingHashes,+} from '../inlineMarkup'++describe('inline HTML', () => {+ it('maps emphasis tags onto markdown and <br> onto a line break', () => {+ expect(+ htmlToMarkdownInline('<b>a</b> <strong>b</strong> <i>c</i> <em>d</em> <del>e</del>')+ ).toBe('**a** **b** *c* *d* ~~e~~')+ expect(htmlToMarkdownInline('one<br>two<BR/>three')).toBe('one\ntwo\nthree')+ })++ it('keeps links, turns img into an image reference and drops scripts and comments', () => {+ expect(htmlToMarkdownInline('<a href="https://x.test/a">site</a>')).toBe(+ '[site](https://x.test/a)'+ )+ expect(htmlToMarkdownInline('<img src="chart.png" alt="c">')).toBe('')+ expect(htmlToMarkdownInline('a<script>alert(1)</script>b<!-- note -->')).toBe('ab')+ })++ it('leaves text that only looks like a tag, and HTML quoted in code', () => {+ expect(htmlToMarkdownInline('Vec<String> and a < b')).toBe('Vec<String> and a < b')+ expect(htmlToMarkdownInline('use `<br>` here')).toBe('use `<br>` here')+ expect(htmlToPlainText('if a<b and c>d or x<i then y>z')).toBe('if a<b and c>d or x<i then y>z')+ })++ it('reads a tag whose attributes have values, or are HTML boolean attributes', () => {+ expect(htmlToMarkdownInline('<b class="x">a</b> <span data-n=1 title=\'t\'>b</span>')).toBe(+ '**a** b'+ )+ expect(htmlToMarkdownInline('<table><tr><td nowrap>1</td><td>2</td></tr></table>')).toBe('1 2')+ expect(htmlToMarkdownInline('<b >a</b >')).toBe('**a**')+ })++ it('breaks the line at block elements and drops their tags', () => {+ expect(htmlToMarkdownInline('<h2>Sales</h2><p>One</p><div>Two</div>')).toBe('Sales\nOne\nTwo')+ expect(+ htmlToMarkdownInline('<table><tr><th>A</th><th>B</th></tr><tr><td>1</td></tr></table>')+ ).toBe('A B\n1')+ expect(htmlToMarkdownInline('<details><summary>S</summary>D</details>')).toBe('S\nD')+ })++ it('keeps list items apart, numbered as their list is', () => {+ expect(htmlToMarkdownInline('<ul><li>a</li><li>b</li></ul><ol><li>c</li><li>d</li></ol>')).toBe(+ '\u2022 a\n\u2022 b\n1. c\n2. d'+ )+ })++ it('reduces a title to its text', () => {+ expect(htmlToPlainText('HTML <b>mixed</b> & <i>title</i>')).toBe('HTML mixed & title')+ expect(htmlToPlainText('<h1>A</h1><p>B</p> <img src="x.png">')).toBe('A B')+ })+})++describe('entities', () => {+ it('decodes named and numeric references', () => {+ expect(decodeEntities('a & b <c> AB ')).toBe('a & b <c> AB \u00A0')+ })++ it('leaves unknown and unrepresentable references as written', () => {+ expect(decodeEntities('&bogus; � �')).toBe('&bogus; � �')+ })++ it('prints an encoded marker instead of reading it as markup', () => {+ expect(inlineSpans('**not bold** <b>')).toEqual([+ { text: '**not bold** <b>' },+ ])+ })+})++describe('inline markdown', () => {+ it('reads ***text*** as bold italic, and nests emphasis', () => {+ expect(inlineSpans('A ***both*** B')).toEqual([+ { text: 'A ' },+ { text: 'both', bold: true, italics: true },+ { text: ' B' },+ ])+ expect(inlineSpans('~~old **bold**~~')).toEqual([+ { text: 'old ', strike: true },+ { text: 'bold', strike: true, bold: true },+ ])+ })++ it('prints an escaped marker as itself', () => {+ expect(+ inlineSpans('\\*not italic\\*')+ .map(s => s.text)+ .join('')+ ).toBe('*not italic*')+ expect(inlineSpans('\\*not italic\\*').some(s => s.italics)).toBe(false)+ })++ it('keeps multiplication signs that have spaces around them', () => {+ expect(inlineSpans('Math 5 * 3 * 2 = 30')).toEqual([{ text: 'Math 5 * 3 * 2 = 30' }])+ })++ it('keeps balanced parentheses in a link target', () => {+ expect(inlineSpans('[wiki](https://en.wikipedia.org/wiki/Foo_(bar)) end')).toEqual([+ { text: 'wiki', link: 'https://en.wikipedia.org/wiki/Foo_(bar)' },+ { text: ' end' },+ ])+ })++ it('names an image written in the text, with its alt text', () => {+ expect(inlineSpans('see  now')).toEqual([+ { text: 'see ' },+ { text: 'Revenue', image: 'sales.png' },+ { text: ' now' },+ ])+ expect(inlineSpans('``')).toEqual([{ text: '', code: true }])+ })+})++describe('ATX headings', () => {+ it('drops a closing run of hashes only when a space precedes it', () => {+ expect(withoutClosingHashes('Section title ##')).toBe('Section title')+ expect(withoutClosingHashes('C#')).toBe('C#')+ expect(withoutClosingHashes('Issue #42')).toBe('Issue #42')+ expect(withoutClosingHashes('##')).toBe('')+ })+})++describe('image targets', () => {+ it('reads the file an image names, in each form Markdown allows', () => {+ expect(imageTarget('chart.png')).toBe('chart.png')+ expect(imageTarget(' <my chart.png> ')).toBe('my chart.png')+ expect(imageTarget('<my chart.png> "Sales"')).toBe('my chart.png')+ expect(imageTarget('chart.png "Quarterly sales"')).toBe('chart.png')+ expect(imageTarget("chart.png 'Sales'")).toBe('chart.png')+ expect(imageTarget('chart.png (Sales)')).toBe('chart.png')+ expect(imageTarget('my\\_chart.png')).toBe('my_chart.png')+ expect(imageTarget('a&b.png')).toBe('a&b.png')+ })++ it('reads a name with spaces written without angle brackets whole', () => {+ expect(imageTarget('my chart.png')).toBe('my chart.png')+ expect(imageTarget('image (1).png')).toBe('image (1).png')+ expect(imageTarget('image (1).png "Costs"')).toBe('image (1).png')+ expect(imageTarget('my chart.png (Sales)')).toBe('my chart.png')+ })++ it('finds an image whose name holds a parenthesized part', () => {+ const [span] = inlineSpans('.png)')+ expect(span).toEqual({ text: 'Sales', image: 'image (1).png' })+ })+})++describe('block quotes', () => {+ it('ends a paragraph at an empty quoted line and runs the others on', () => {+ expect(quoteParagraphs(['One', 'runs on.', '', ' ', 'Two.', ''])).toEqual([+ 'One runs on.',+ 'Two.',+ ])+ expect(quoteParagraphs(['', ''])).toEqual([''])+ })+})++describe('hostile input', () => {+ // Each input is about 200 KB on one line: an unclosed construct repeated, so+ // a pattern that rescans the rest of the line from every opening is quadratic.+ const inputs: Record<string, string> = {+ img: "<img src='x".repeat(20000),+ tag: '<b'.repeat(100000),+ tagSpaced: '<b '.repeat(66667),+ tagAttributes: '<b a=1'.repeat(30000),+ tagAttributesOpen: `<b ${'a=1 '.repeat(50000)}`,+ tagBoolean: `<td ${'nowrap '.repeat(28000)}`,+ comment: '<!--'.repeat(50000),+ script: '<script>'.repeat(25000),+ anchor: '<a href="https://x.test">'.repeat(8000),+ list: '<ol><li>'.repeat(25000),+ image: ',+ imageGroups: `'.repeat(60000)}`,+ imageGroupsRepeated: `'.repeat(5)}`.repeat(10000),+ link: '[a](http://x'.repeat(16000),+ bracket: '['.repeat(200000),+ bold: '**a '.repeat(50000),+ boldItalic: '***a '.repeat(40000),+ italic: '*a '.repeat(66667),+ strike: '~~a '.repeat(50000),+ code: '`a '.repeat(66667),+ escape: '\\*'.repeat(100000),+ entity: ''.repeat(50000),+ }+ const parsers: Record<string, (text: string) => unknown> = {+ htmlToMarkdownInline,+ htmlToPlainText,+ inlineSpans,+ }++ for (const [name, input] of Object.entries(inputs)) {+ it(`reads ${name} in linear time`, () => {+ for (const [parser, parse] of Object.entries(parsers)) {+ const started = performance.now()+ parse(input)+ expect(performance.now() - started, `${parser} on ${name}`).toBeLessThan(2000)+ }+ })+ }+})diff --git a/mcp-host/src/workflow/__tests__/tableRows.test.ts b/mcp-host/src/workflow/__tests__/tableRows.test.tsnew file mode 100644index 000000000..422231039--- /dev/null+++ b/mcp-host/src/workflow/__tests__/tableRows.test.ts@@ -0,0 +1,58 @@+import { describe, expect, it } from 'vitest'+import { headerText, normalizeTableRows } from '../tableRows'++describe('normalizeTableRows', () => {+ it('passes array rows through untouched', () => {+ const warnings: string[] = []+ expect(normalizeTableRows([['a', 1, null]], ['A', 'B', 'C'], 'tables[0]', warnings)).toEqual([+ ['a', 1, null],+ ])+ expect(warnings).toEqual([])+ })++ it('reads record rows by header name, ignoring case and spaces', () => {+ const warnings: string[] = []+ const rows = normalizeTableRows(+ [+ { Name: 'Ana', Amount: 1200 },+ { ' name ': 'Luis', amount: 900, extra: 'x' },+ ],+ ['Name', 'Amount'],+ 'tables[0]',+ warnings+ )+ expect(rows).toEqual([+ ['Ana', 1200],+ ['Luis', 900],+ ])+ expect(warnings).toEqual([+ 'tables[0]: 2 row(s) were objects and were read by header name; send each row as an array of cells in header order.',+ "tables[0]: the key(s) 'extra' match no header, so those values were left out.",+ ])+ })++ it('takes record values in order when there are no headers', () => {+ expect(normalizeTableRows([{ a: 1, b: 2 }], undefined, 's', [])).toEqual([[1, 2]])+ })++ it('drops what is not a row and says so', () => {+ const warnings: string[] = []+ expect(normalizeTableRows([['ok'], 'text', null, 3], ['A'], 'sheets[1]', warnings)).toEqual([+ ['ok'],+ ])+ expect(warnings).toEqual([+ 'sheets[1]: 3 row(s) were neither an array nor an object and were left out.',+ ])+ const more: string[] = []+ expect(normalizeTableRows('a,b', ['A'], 'tables[2]', more)).toEqual([])+ expect(more).toEqual(['tables[2]: rows must be an array of rows; they were left out.'])+ })+})++describe('headerText', () => {+ it('shows numeric headers and blanks null', () => {+ expect(headerText(2026)).toBe('2026')+ expect(headerText(null)).toBe('')+ expect(headerText('Q1')).toBe('Q1')+ })+})diff --git a/mcp-host/src/workflow/artifactOutput.ts b/mcp-host/src/workflow/artifactOutput.tsnew file mode 100644index 000000000..77b5315e4--- /dev/null+++ b/mcp-host/src/workflow/artifactOutput.ts@@ -0,0 +1,162 @@+/**+ * Naming, placing and reporting the files the document generators write.+ */+import { createHash } from 'crypto'+import * as fs from 'fs'+import * as path from 'path'+import type { ArtifactMetadata, InternalToolResult } from './types'++const MAX_STEM_LENGTH = 120++/**+ * Extensions a requested name may already carry. Anything else after a dot is+ * part of the name, so "report.v2" keeps its "v2".+ */+const KNOWN_EXTENSIONS = new Set([+ 'md',+ 'markdown',+ 'txt',+ 'pdf',+ 'doc',+ 'docx',+ 'xls',+ 'xlsx',+ 'csv',+ 'ppt',+ 'pptx',+ 'png',+ 'jpg',+ 'jpeg',+ 'gif',+ 'webp',+ 'svg',+ 'htm',+ 'html',+ 'json',+])++/**+ * A safe filename for a generated artifact.+ *+ * Only ASCII letters, digits, '.', '_' and '-' are kept, because the download+ * paths do not all encode other characters. Dropping characters must not make+ * two requested names equal ("報告.md" and "資料.md" would both be "__.md"), so+ * when anything other than a space is replaced or dropped a short hash of the+ * requested name is appended. The stem is shortened before the extension is+ * added, so a long name keeps its extension.+ */+export function outputFilename(requested: unknown, ext: string, fallbackStem: string): string {+ const extension = ext.replace(/^\./, '').toLowerCase()+ const base = path.basename(String(requested ?? '').normalize('NFC')).trim()+ const dot = base.lastIndexOf('.')+ const stem =+ dot > 0 && KNOWN_EXTENSIONS.has(base.slice(dot + 1).toLowerCase()) ? base.slice(0, dot) : base++ if (!stem) return `${fallbackStem}.${extension}`+ const safe = stem+ .replace(/[^A-Za-z0-9._-]+/g, '_')+ .replace(/\.{2,}/g, '.')+ .replace(/^[._-]+|[._-]+$/g, '')+ if (safe === stem.replace(/\s+/g, '_') && safe && safe.length <= MAX_STEM_LENGTH) {+ return `${safe}.${extension}`+ }+ const hash = createHash('sha256').update(stem).digest('hex').slice(0, 8)+ return `${(safe || fallbackStem).slice(0, MAX_STEM_LENGTH - hash.length - 1)}-${hash}.${extension}`+}++export interface OutputTarget {+ filename: string+ filePath: string+ /** A file already at `filePath` will be overwritten. */+ replacesExisting: boolean+}++/** Where to write `filename`; a file already there is replaced. */+export function claimOutputFile(outputDir: string, filename: string): OutputTarget {+ const filePath = path.join(outputDir, filename)+ const entry = lstat(filePath)+ // A write follows a symbolic link, so a link in the name's place is removed+ // and a regular file is written there instead of wherever it points.+ if (entry?.isSymbolicLink()) fs.unlinkSync(filePath)+ return { filename, filePath, replacesExisting: !!entry && !entry.isSymbolicLink() }+}++function lstat(file: string): fs.Stats | undefined {+ try {+ return fs.lstatSync(file)+ } catch {+ return undefined+ }+}++/** Size of the file a write is about to replace, so a quota check does not count it twice. */+export function replacedBytes(target: OutputTarget): number {+ if (!target.replacesExisting) return 0+ try {+ return fs.statSync(target.filePath).size+ } catch {+ return 0+ }+}++/** Lines of notes a result carries; the rest are counted. */+const MAX_NOTES = 12++/** Notes of one kind shown before the rest of the kind is counted. */+const NOTES_PER_KIND = 3++/** A note about content the file does not hold, which comes first. */+const LOSS_NOTE =+ /\b(dropped|left out|could not|cannot|missing|not drawn|was cut|were cut|skipped)\b/i++/**+ * `warnings` in a length the agent can relay: past a few, notes that differ+ * only in their numbers (a row, a cell, a count) are counted, and notes about+ * lost content come first.+ */+export function capNotes(warnings: string[]): string[] {+ const groups = new Map<string, { notes: string[]; loss: boolean }>()+ for (const warning of new Set(warnings)) {+ const key = warning.replace(/\d+(?:\.\d+)?/g, '#')+ const group = groups.get(key)+ if (group) group.notes.push(warning)+ else groups.set(key, { notes: [warning], loss: LOSS_NOTE.test(warning) })+ }+ const lines = [...groups.values()]+ .sort((a, b) => Number(b.loss) - Number(a.loss))+ .flatMap(({ notes }) => {+ const shown = notes.slice(0, NOTES_PER_KIND)+ const more = notes.length - shown.length+ if (more > 0) shown[shown.length - 1] += ` (${more} more like it.)`+ return shown+ })+ if (lines.length <= MAX_NOTES) return lines+ return [...lines.slice(0, MAX_NOTES), `(${lines.length - MAX_NOTES} more notes of other kinds.)`]+}++/**+ * The result of a generator that wrote `target`. The message leads with the+ * name the file was actually saved under, which is what another generator must+ * be given to embed it, and carries any warnings so the agent can relay them.+ */+export function artifactResult(+ target: OutputTarget,+ format: ArtifactMetadata['format'],+ opts: { summary?: string; warnings?: string[] } = {}+): InternalToolResult {+ const stats = fs.statSync(target.filePath)+ const parts = [opts.summary ?? `File generated: ${target.filename} (${format}).`]+ const warnings = capNotes(opts.warnings ?? [])+ if (warnings.length > 0) parts.push(`Notes: ${warnings.join(' ')}`)+ return {+ success: true,+ artifact: {+ name: target.filename,+ format,+ path: target.filePath,+ sizeBytes: stats.size,+ createdAt: new Date().toISOString(),+ },+ content: parts.join('\n'),+ }+}diff --git a/mcp-host/src/workflow/embeddedImages.ts b/mcp-host/src/workflow/embeddedImages.tsnew file mode 100644index 000000000..2b4f616d0--- /dev/null+++ b/mcp-host/src/workflow/embeddedImages.ts@@ -0,0 +1,490 @@+/**+ * Reading, sizing and preparing the images the document generators embed.+ */+import { createCanvas, loadImage } from '@napi-rs/canvas'+import * as fs from 'fs'+import * as path from 'path'+import { imageTarget } from './inlineMarkup'++export interface ImageSize {+ width: number+ height: number+}++/** Pixels per metre at 96 dpi, the density a PNG carries when it is not oversampled. */+export const PNG_BASE_PPM = 3780++function isPng(buf: Buffer): boolean {+ return buf.length > 24 && buf.readUInt32BE(0) === 0x89504e47+}++function isJpeg(buf: Buffer): boolean {+ return buf.length > 4 && buf[0] === 0xff && buf[1] === 0xd8+}++/** The EXIF orientation of a JPEG (1 = upright), from its APP1 segment. */+function jpegOrientation(buf: Buffer): number {+ if (!isJpeg(buf)) return 1+ let i = 2+ while (i + 4 < buf.length && buf[i] === 0xff) {+ const marker = buf[i + 1]+ const length = buf.readUInt16BE(i + 2)+ if (marker === 0xda) break+ if (marker === 0xe1 && buf.toString('latin1', i + 4, i + 10) === 'Exif\0\0') {+ const tiff = i + 10+ const le = buf.toString('latin1', tiff, tiff + 2) === 'II'+ const u16 = (at: number) => (le ? buf.readUInt16LE(at) : buf.readUInt16BE(at))+ const u32 = (at: number) => (le ? buf.readUInt32LE(at) : buf.readUInt32BE(at))+ if (tiff + 8 > buf.length) return 1+ const ifd = tiff + u32(tiff + 4)+ if (ifd + 2 > buf.length) return 1+ for (let n = 0, count = u16(ifd); n < count; n++) {+ const entry = ifd + 2 + n * 12+ if (entry + 10 > buf.length) return 1+ if (u16(entry) === 0x0112) return u16(entry + 8)+ }+ return 1+ }+ i += 2 + length+ }+ return 1+}++/** Pixel dimensions of a PNG or JPEG, read from its header. */+function headerSize(buf: Buffer): ImageSize | undefined {+ // PNG: IHDR is the first chunk, width and height at byte 16.+ if (isPng(buf)) {+ const width = buf.readUInt32BE(16)+ const height = buf.readUInt32BE(20)+ return width > 0 && height > 0 ? { width, height } : undefined+ }+ // JPEG: walk the segment chain to the frame header, which carries the size.+ if (isJpeg(buf)) {+ let i = 2+ while (i + 9 < buf.length) {+ if (buf[i] !== 0xff) {+ i+++ continue+ }+ const marker = buf[i + 1]+ // SOF0..SOF15, skipping the non-frame markers in that range.+ if (+ marker >= 0xc0 &&+ marker <= 0xcf &&+ marker !== 0xc4 &&+ marker !== 0xc8 &&+ marker !== 0xcc+ ) {+ return { height: buf.readUInt16BE(i + 5), width: buf.readUInt16BE(i + 7) }+ }+ i += 2 + buf.readUInt16BE(i + 2)+ }+ }+ return undefined+}++/** 1200 dpi. A density past it is not one to show a picture at: it would shrink it to a speck. */+const MAX_DENSITY_RATIO = 12.5++/** Oversampling factor recorded in a PNG's pHYs chunk; 1 when absent or implausible. */+function pngDensityRatio(buf: Buffer): number {+ if (!isPng(buf)) return 1+ let at = 8+ while (at + 8 <= buf.length) {+ const length = buf.readUInt32BE(at)+ const type = buf.toString('latin1', at + 4, at + 8)+ if (type === 'pHYs' && at + 8 + 9 <= buf.length) {+ const ppm = buf.readUInt32BE(at + 8)+ const unit = buf.readUInt8(at + 16)+ if (unit === 1 && ppm > 0) {+ const ratio = ppm / PNG_BASE_PPM+ return Number.isFinite(ratio) && ratio >= 1 && ratio <= MAX_DENSITY_RATIO ? ratio : 1+ }+ return 1+ }+ if (type === 'IDAT' || type === 'IEND') return 1+ at += 12 + length+ }+ return 1+}++/**+ * Size an image should be shown at, in CSS pixels at 96 dpi. An oversampled+ * image reports fewer display pixels than it stores, which is what keeps its+ * type at the size it was laid out for.+ */+function displaySize(buf: Buffer): ImageSize | undefined {+ const intrinsic = headerSize(buf)+ if (!intrinsic) return undefined+ const ratio = pngDensityRatio(buf)+ if (ratio <= 1) return intrinsic+ return {+ width: Math.max(1, Math.round(intrinsic.width / ratio)),+ height: Math.max(1, Math.round(intrinsic.height / ratio)),+ }+}++function readFile(file: string): Buffer | undefined {+ try {+ return fs.readFileSync(file)+ } catch {+ return undefined+ }+}++/**+ * Pixel dimensions of a PNG or JPEG file. Embedding an image into a fixed box+ * distorts it — a 2:1 chart placed in a 16:9 slot is visibly stretched — so+ * every embedder sizes against the real aspect ratio.+ */+export function imageIntrinsicSize(file: string): ImageSize | undefined {+ const buf = readFile(file)+ return buf ? headerSize(buf) : undefined+}++export function imageDisplaySize(file: string): ImageSize | undefined {+ const buf = readFile(file)+ return buf ? displaySize(buf) : undefined+}++/**+ * Box for an image of `size` that fits `max`, always in the image's own+ * proportions. An explicit width or height is honoured and the other side+ * derived; both together are read as a box to fit in, because a model that+ * sends both almost never means to distort the image. Whatever was asked for+ * is then scaled down until it fits the page.+ */+export function fitImageSize(+ size: ImageSize | undefined,+ max: ImageSize,+ requested: { width?: number; height?: number } = {}+): ImageSize {+ const reqW = requested.width && requested.width > 0 ? requested.width : undefined+ const reqH = requested.height && requested.height > 0 ? requested.height : undefined+ let width: number+ let height: number+ if (!size) {+ if (!reqW && !reqH) return { width: max.width, height: max.height }+ width = reqW ?? max.width+ height = reqH ?? max.height+ } else {+ const ratio = size.width / size.height+ if (reqW && reqH) {+ const scale = Math.min(reqW / size.width, reqH / size.height)+ width = size.width * scale+ height = size.height * scale+ } else if (reqW) {+ width = reqW+ height = reqW / ratio+ } else if (reqH) {+ width = reqH * ratio+ height = reqH+ } else {+ width = size.width+ height = size.height+ }+ }+ const scale = Math.min(max.width / width, max.height / height, 1)+ return { width: Math.round(width * scale), height: Math.round(height * scale) }+}++/** fitImageSize for an image on disk. */+export function fitImageBox(+ file: string,+ max: ImageSize,+ requested: { width?: number; height?: number } = {}+): ImageSize {+ return fitImageSize(imageDisplaySize(file), max, requested)+}++/** The path an image argument names: a filename, or an object carrying `path`. */+export function imageRefPath(ref: unknown): string | undefined {+ if (typeof ref === 'string') return ref.trim() || undefined+ if (ref && typeof ref === 'object') {+ const p = (ref as { path?: unknown }).path+ if (typeof p === 'string' && p.trim()) return p.trim()+ }+ return undefined+}++/**+ * Resolve an image path inside `outputDir`.+ *+ * A path that escapes the folder is an error. The one exception is+ * an absolute path whose file name exists in the folder: models copy the path+ * a generator reported in another mode (`/output/chart.png`) or invent one, and+ * failing the whole document for it helped nobody. Returns undefined, with a+ * warning, when the file is missing.+ */+export function resolveImagePath(+ requested: string,+ outputDir: string,+ warnings: string[]+): string | undefined {+ const root = path.resolve(outputDir)+ const resolved = path.resolve(root, requested)+ const inside = resolved.startsWith(root + path.sep)+ let file = resolved+ if (!inside) {+ const sibling = path.join(root, path.basename(requested))+ if (!path.isAbsolute(requested) || !fs.existsSync(sibling)) {+ throw new Error(`path traversal blocked: ${requested}`)+ }+ warnings.push(+ `'${requested}' is outside the output folder, so '${path.basename(requested)}' from the output folder was used.`+ )+ file = sibling+ }+ if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {+ warnings.push(`Image '${requested}' was not found in the output folder and was left out.`)+ return undefined+ }+ if (!insideRealFolder(file, root)) throw new Error(`path traversal blocked: ${requested}`)+ return file+}++/** Whether `file`, links resolved, is inside `root`, links resolved. */+function insideRealFolder(file: string, root: string): boolean {+ try {+ return fs.realpathSync(file).startsWith(fs.realpathSync(root) + path.sep)+ } catch {+ return false+ }+}++export interface EmbeddableImage {+ /** Resolved file inside the output folder. */+ path: string+ /** PNG or JPEG bytes; other formats arrive converted to PNG. */+ data: Buffer+ format: 'png' | 'jpeg'+ /** Display size in CSS pixels. */+ width: number+ height: number+ /** Size of the stored bitmap, which is larger than the display size when oversampled. */+ pixels: ImageSize+}++/**+ * Largest image decoded for conversion, in pixels (64 MB of RGBA). The canvas+ * library aborts the whole process, uncatchably, when it cannot allocate a+ * bitmap, so every size is checked from the file header before decoding.+ */+const MAX_DECODE_PIXELS = 16_000_000+const MAX_SVG_SIDE = 2048++/** Width and height from a GIF, WebP or BMP header, read before the image is decoded. */+function declaredSize(buf: Buffer): ImageSize | undefined {+ if (buf.length >= 10 && buf.toString('latin1', 0, 4) === 'GIF8') {+ return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) }+ }+ if (buf.length >= 26 && buf.toString('latin1', 0, 2) === 'BM') {+ return { width: Math.abs(buf.readInt32LE(18)), height: Math.abs(buf.readInt32LE(22)) }+ }+ if (+ buf.length >= 30 &&+ buf.toString('latin1', 0, 4) === 'RIFF' &&+ buf.toString('latin1', 8, 12) === 'WEBP'+ ) {+ const chunk = buf.toString('latin1', 12, 16)+ if (chunk === 'VP8X') {+ return { width: 1 + buf.readUIntLE(24, 3), height: 1 + buf.readUIntLE(27, 3) }+ }+ if (chunk === 'VP8L') {+ const bits = buf.readUInt32LE(21)+ return { width: 1 + (bits & 0x3fff), height: 1 + ((bits >> 14) & 0x3fff) }+ }+ if (chunk === 'VP8 ') {+ return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff }+ }+ }+ return undefined+}++const SVG_UNIT_PX: Record<string, number> = {+ '': 1,+ px: 1,+ pt: 4 / 3,+ pc: 16,+ mm: 96 / 25.4,+ cm: 96 / 2.54,+ in: 96,+ em: 16,+ ex: 8,+}++function svgLength(tag: string, name: string): number | undefined {+ const m = new RegExp(`\\s${name}\\s*=\\s*["']\\s*([0-9.]+)\\s*([a-z]*)\\s*["']`, 'i').exec(tag)+ const factor = m ? SVG_UNIT_PX[m[2].toLowerCase()] : undefined+ return m && factor ? Number(m[1]) * factor : undefined+}++/**+ * An SVG whose root size fits the decode budget. The canvas library rasterizes+ * an SVG at its declared size, so a huge width, height or viewBox is rewritten+ * to a smaller one; the drawing is vector, so it scales without loss.+ */+function boundedSvg(buf: Buffer): Buffer | undefined {+ const text = buf.toString('utf8')+ const open = /<svg\b[^<>]*>/i.exec(text)+ if (!open) return undefined+ const tag = open[0]+ const box =+ /\sviewBox\s*=\s*["']\s*[-0-9.e]+[\s,]+[-0-9.e]+[\s,]+([0-9.e]+)[\s,]+([0-9.e]+)/i.exec(tag)+ const width = svgLength(tag, 'width') ?? (box ? Number(box[1]) : undefined)+ const height = svgLength(tag, 'height') ?? (box ? Number(box[2]) : undefined)+ if (!width || !height || !Number.isFinite(width) || !Number.isFinite(height)) return buf+ const scale = Math.min(+ 1,+ MAX_SVG_SIDE / Math.max(width, height),+ Math.sqrt(MAX_DECODE_PIXELS / (width * height))+ )+ if (scale >= 1) return buf+ const sized = tag+ .replace(/\s(width|height)\s*=\s*(["'])[^"']*\2/gi, '')+ .replace(+ /^<svg\b/i,+ `<svg width="${Math.max(1, Math.floor(width * scale))}" height="${Math.max(1, Math.floor(height * scale))}"` ++ (box ? '' : ` viewBox="0 0 ${width} ${height}"`)+ )+ return Buffer.from(+ text.slice(0, open.index) + sized + text.slice(open.index + tag.length),+ 'utf8'+ )+}++function isSvg(buf: Buffer): boolean {+ const head = buf.toString('utf8', 0, Math.min(buf.length, 1024)).trimStart()+ return /^(?:<\?xml[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*(?:<!DOCTYPE[^>]*>\s*)?<svg\b/i.test(head)+}++/** Bytes safe to hand to the decoder, or undefined for a format or size this tool does not convert. */+function decodable(raw: Buffer): Buffer | undefined {+ if (isSvg(raw)) return boundedSvg(raw)+ const size = isJpeg(raw) ? headerSize(raw) : declaredSize(raw)+ if (!size || !size.width || !size.height) return undefined+ return size.width * size.height <= MAX_DECODE_PIXELS ? raw : undefined+}++/**+ * PNG bytes of images decoded ahead of a render, by file and version. The+ * canvas library decodes GIF, WebP and SVG asynchronously, and an image drawn+ * before it finishes comes out fully transparent; the generators read images+ * synchronously deep inside their layout code, so the decoding happens first.+ */+const decoded = new Map<string, Buffer>()+const MAX_DECODED = 32++function decodedKey(file: string): string | undefined {+ try {+ const stat = fs.statSync(file)+ return `${file}\0${stat.size}\0${stat.mtimeMs}`+ } catch {+ return undefined+ }+}++const IMAGE_NAME = /\.(?:png|jpe?g|gif|webp|svg|bmp|avif|ico|tiff?)$/i+// As the markdown reader matches an image: the alt text stops at the next+// bracket, so a line of unclosed "![" is scanned once, not from every opening.+const MARKDOWN_IMAGE = /!\[[^[\]\n]*\]\(((?:[^()\n]|\([^()\n]*\))*)\)/g++function collectImageNames(value: unknown, into: Set<string>, depth = 0): void {+ if (depth > 64) return+ if (typeof value === 'string') {+ const text = value.trim()+ if (IMAGE_NAME.test(text) && text.length < 1024) into.add(text)+ if (text.includes('!['))+ for (const m of text.matchAll(MARKDOWN_IMAGE)) into.add(imageTarget(m[1]))+ } else if (Array.isArray(value)) {+ for (const item of value) collectImageNames(item, into, depth + 1)+ } else if (value && typeof value === 'object') {+ for (const item of Object.values(value)) collectImageNames(item, into, depth + 1)+ }+}++/**+ * Decode every image an argument names that is neither PNG nor JPEG, so+ * loadEmbeddableImage can convert it. Never throws: whatever cannot be decoded+ * here is reported by loadEmbeddableImage when a generator asks for it.+ */+export async function predecodeImages(args: unknown, outputDir: string): Promise<void> {+ const names = new Set<string>()+ collectImageNames(args, names)+ const root = path.resolve(outputDir)+ for (const name of names) {+ try {+ const resolved = path.resolve(root, name)+ const file = resolved.startsWith(root + path.sep)+ ? resolved+ : path.isAbsolute(name)+ ? path.join(root, path.basename(name))+ : undefined+ const key = file && decodedKey(file)+ if (!file || !key || decoded.has(key) || !insideRealFolder(file, root)) continue+ const raw = fs.readFileSync(file)+ if (isPng(raw) || (isJpeg(raw) && jpegOrientation(raw) <= 1)) continue+ const input = decodable(raw)+ if (!input) continue+ const image = await loadImage(input)+ if (!image.width || !image.height || image.width * image.height > MAX_DECODE_PIXELS) continue+ const canvas = createCanvas(image.width, image.height)+ canvas.getContext('2d').drawImage(image, 0, 0)+ // The decoder applies the EXIF rotation; re-encoding drops it, so every+ // format shows the photo the same way up.+ decoded.set(+ key,+ isJpeg(raw) ? canvas.toBuffer('image/jpeg', 92) : canvas.toBuffer('image/png')+ )+ while (decoded.size > MAX_DECODED) decoded.delete(decoded.keys().next().value as string)+ } catch {+ // Left for loadEmbeddableImage to report against the argument that named it.+ }+ }+}++/**+ * Load an image argument for embedding. The format is read from the bytes, not+ * the extension, so a GIF named .png still embeds; formats other than PNG and+ * JPEG need predecodeImages first. Anything missing or unreadable is left out+ * with a warning naming it, so the agent learns why it is not in the document.+ */+export function loadEmbeddableImage(+ ref: unknown,+ outputDir: string,+ warnings: string[],+ label = 'image'+): EmbeddableImage | undefined {+ const requested = imageRefPath(ref)+ if (requested && /^(?:https?|ftp|data):/i.test(requested)) {+ const shown = requested.length > 60 ? `${requested.slice(0, 57)}...` : requested+ warnings.push(+ `${label} '${shown}' is a web address or inline data, and images are not downloaded; ` ++ 'save the image to the output folder first and pass its file name. It was left out.'+ )+ return undefined+ }+ if (!requested) {+ warnings.push(+ `${label} needs a file name, such as the one clerum__generate_chart returns; it was left out.`+ )+ return undefined+ }+ const file = resolveImagePath(requested, outputDir, warnings)+ if (!file) return undefined+ const raw = readFile(file)+ const key = decodedKey(file)+ const upright = raw && (isPng(raw) || (isJpeg(raw) && jpegOrientation(raw) <= 1))+ const data = upright ? raw : key ? decoded.get(key) : undefined+ const size = data ? displaySize(data) : undefined+ const pixels = data ? headerSize(data) : undefined+ if (!data || !size || !pixels) {+ warnings.push(`'${requested}' is not an image this tool can read and was left out.`)+ return undefined+ }+ return { path: file, data, format: isPng(data) ? 'png' : 'jpeg', ...size, pixels }+}++export function imageDataUrl(image: EmbeddableImage): string {+ return `data:image/${image.format};base64,${image.data.toString('base64')}`+}diff --git a/mcp-host/src/workflow/fonts.ts b/mcp-host/src/workflow/fonts.tsnew file mode 100644index 000000000..8d942bb4d--- /dev/null+++ b/mcp-host/src/workflow/fonts.ts@@ -0,0 +1,1118 @@+/**+ * Font provisioning for the artifact renderers.+ *+ * Both renderers start from the Roboto faces pdfmake vendors as base64,+ * registered from memory, so text renders even on an image without system+ * fonts (where @napi-rs/canvas would measure every string at zero width) and a+ * PDF never falls back to the Latin-1-only standard-14 Helvetica.+ *+ * Roboto carries no arrows, check marks or CJK. Where the image ships fonts+ * that do, the canvas fallback stack reaches them and a PDF run switches to a+ * face that has the character; where it ships none, the text is rewritten or+ * reported. Chart coverage is measured by rendering, PDF coverage read from+ * each face's cmap, so neither is assumed.+ */+import { GlobalFonts, type SKRSContext2D, createCanvas } from '@napi-rs/canvas'+import * as fs from 'fs'+import * as path from 'path'++/** Family the bundled Roboto is registered under. */+export const CHART_FONT_FAMILY = 'Clerum Sans'++/** Family name registered with pdfmake. */+export const PDF_FONT_FAMILY = 'ClerumSans'++/** Family pdfmake uses for code blocks and inline code. */+export const PDF_MONO_FAMILY = 'ClerumMono'++/**+ * Family list handed to the canvas. Roboto first so output is identical across+ * images; the rest are picked up only when the image ships them, which is what+ * makes arrows, check marks and CJK render natively where they exist.+ */+export const CHART_FONT_STACK =+ `"${CHART_FONT_FAMILY}", "DejaVu Sans", "Noto Sans", "Liberation Sans", ` ++ '"Noto Sans CJK SC", "Noto Sans CJK JP", "Arial Unicode MS", sans-serif'++interface RobotoFaces {+ normal: Buffer+ bold: Buffer+ italics: Buffer+ bolditalics: Buffer+}++/**+ * Directories scanned for extra faces. Registering them is what puts the+ * fallback families above within the canvas's reach. Absent dirs are skipped.+ */+const SYSTEM_FONT_DIRS = [+ '/usr/share/fonts',+ '/usr/local/share/fonts',+ '/opt/fonts',+ '/System/Library/Fonts',+]++/** Private Use codepoint — no real font claims it, so it renders as "missing". */+const MISSING_PROBE = '\uE000'++let faces: RobotoFaces | undefined+let ready = false++function loadRobotoFaces(): RobotoFaces {+ if (faces) return faces+ // pdfmake's vfs export shape differs across builds (`pdfMake.vfs`, `vfs`, or+ // the table itself), so probe rather than pin to one of them.+ const mod = require('pdfmake/build/vfs_fonts.js')+ const table: Record<string, string> = mod?.pdfMake?.vfs ?? mod?.vfs ?? mod+ const decode = (name: string): Buffer => {+ const b64 = table[name]+ if (typeof b64 !== 'string') throw new Error(`pdfmake vfs is missing ${name}`)+ return Buffer.from(b64, 'base64')+ }+ faces = {+ normal: decode('Roboto-Regular.ttf'),+ bold: decode('Roboto-Medium.ttf'),+ italics: decode('Roboto-Italic.ttf'),+ bolditalics: decode('Roboto-MediumItalic.ttf'),+ }+ return faces+}++function walk(dir: string, depth: number): string[] {+ if (depth > 3) return []+ const out: string[] = []+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {+ const full = path.join(dir, entry.name)+ if (entry.isDirectory()) out.push(...walk(full, depth + 1))+ else if (/\.(ttf|otf|ttc)$/i.test(entry.name)) out.push(full)+ }+ return out+}++function registerSystemFonts(): void {+ for (const dir of SYSTEM_FONT_DIRS) {+ let files: string[]+ try {+ if (!fs.existsSync(dir)) continue+ files = walk(dir, 0)+ } catch {+ continue+ }+ for (const file of files) {+ try {+ GlobalFonts.registerFromPath(file)+ } catch {+ // A face the renderer cannot parse is simply not available.+ }+ }+ }+}++/**+ * Register the bundled faces (and any system faces) exactly once. Safe to call+ * from every render path; later calls are free.+ */+export function ensureFontsReady(): void {+ if (ready) return+ ready = true+ const f = loadRobotoFaces()+ GlobalFonts.register(f.normal, CHART_FONT_FAMILY)+ GlobalFonts.register(f.bold, `${CHART_FONT_FAMILY} Bold`)+ registerSystemFonts()+}++/**+ * Families a PDF can be built from, widest coverage first.+ *+ * The body family is the widest one present, since every run starts in it:+ * DejaVu and Noto carry arrows, check marks, Greek and Cyrillic that Roboto+ * lacks; anything it still lacks falls back per run.+ * Matching is by family prefix rather than exact filename because the same+ * family is packaged under different names — `DejaVuSans.ttf` on one image,+ * `NotoSans-Regular.ttf` on another — and a missed guess would silently drop+ * back to the narrower face.+ */+const PDF_FAMILY_PREFIXES = [+ 'NotoSans',+ 'DejaVuSans',+ 'LiberationSans',+ 'NotoSansSC',+ 'NotoSerifSC',+]++/** Fixed-width families, for code blocks. */+const MONO_FAMILY_PREFIXES = ['DejaVuSansMono', 'NotoSansMono', 'LiberationMono', 'DejaVuSerifMono']++/**+ * One face for pdfmake: an embedded buffer, a path to a standalone file, or a+ * `[path, postScriptName]` pair addressing a face inside a collection.+ * pdfmake spreads an array descriptor into `pdfKitDoc.font(...)`, which is the+ * only way to open one face of a `.ttc`.+ */+type PdfFace = Buffer | string | [string, string]++interface PdfFaces {+ normal: PdfFace+ bold: PdfFace+ italics: PdfFace+ bolditalics: PdfFace+}++let pdfFaces: PdfFaces | undefined+let monoFaces: PdfFaces | undefined+let faceIndex: Map<string, string> | undefined++/**+ * Every embeddable face on this image, keyed by lowercased basename.+ *+ * TrueType Collections are left out on purpose: pdfkit subsets a single face+ * and cannot open a `.ttc` without being told which face inside it to use, so+ * handing it one fails the whole document with "createSubset is not a+ * function". The canvas has no such limit and keeps using them.+ */+function embeddableFaces(): Map<string, string> {+ if (faceIndex) return faceIndex+ const index = new Map<string, string>()+ for (const dir of SYSTEM_FONT_DIRS) {+ try {+ if (!fs.existsSync(dir)) continue+ for (const file of walk(dir, 0)) {+ if (!/\.(ttf|otf)$/i.test(file)) continue+ const stem = path+ .basename(file)+ .replace(/\.(ttf|otf)$/i, '')+ .toLowerCase()+ if (!index.has(stem)) index.set(stem, file)+ }+ } catch {+ continue+ }+ }+ faceIndex = index+ return index+}++/** First face matching any of `stems`, in order. */+function pickFace(stems: string[]): string | undefined {+ const index = embeddableFaces()+ for (const stem of stems) {+ const hit = index.get(stem.toLowerCase())+ if (hit) return hit+ }+ return undefined+}++/**+ * Resolve one family's four faces from a prefix, accepting both the bare and+ * the `-Regular` spelling, and falling back to the regular face for styles the+ * image does not ship.+ */+function facesForPrefix(prefix: string): PdfFaces | undefined {+ const normal = pickFace([prefix, `${prefix}-Regular`, `${prefix}-Book`])+ if (!normal) return undefined+ const bold = pickFace([`${prefix}-Bold`, `${prefix}Bold`]) ?? normal+ const italics = pickFace([`${prefix}-Italic`, `${prefix}-Oblique`, `${prefix}Oblique`]) ?? normal+ const bolditalics =+ pickFace([`${prefix}-BoldItalic`, `${prefix}-BoldOblique`, `${prefix}BoldOblique`]) ?? bold+ return { normal, bold, italics, bolditalics }+}++/**+ * Characters Roboto cannot draw. A face is only worth preferring over the+ * bundled one if it covers some of these.+ */+const COVERAGE_PROBES = ['\u2192', '\u2713', '\u4E2D', '\u2265', '\u03B1', '\u044F']++/**+ * A usable body face has to draw ordinary letters and digits. Checked because+ * an image can ship fonts whose name suggests broad coverage but which hold+ * only symbols — macOS packages one called `CJKSymbolsFallback` — and taking+ * one of those would leave a document with no readable text at all.+ */+const LATIN_PROBES = ['A', 'g', '0']++/**+ * How many probe characters `file` can draw, measured by rendering them.+ * Returns -1 for a face that cannot set plain Latin, which disqualifies it.+ */+function coverageScore(file: string): number {+ const alias = '__ClerumProbeFace'+ try {+ GlobalFonts.registerFromPath(file, alias)+ } catch {+ return -1+ }+ const font = `"${alias}"`+ const missing = renderSignature(MISSING_PROBE, font)+ const blank = renderSignature(' ', font)+ for (const ch of LATIN_PROBES) {+ const sig = renderSignature(ch, font)+ if (sig === missing || sig === blank) return -1+ }+ let score = 0+ for (const ch of COVERAGE_PROBES) {+ if (renderSignature(ch, font) !== missing) score+++ }+ return score+}++/**+ * Any regular-weight face from a family known to be broad. Used only when none+ * of the named prefixes matched, so an image that packages those families+ * under names this list does not predict still gets the wider font rather than+ * silently falling back to the narrow bundled one.+ */+function discoverWideFace(): PdfFaces | undefined {+ const candidates: string[] = []+ for (const [stem, file] of embeddableFaces()) {+ if (!/^(dejavusans|notosans|liberationsans)(-regular|-book)?$/.test(stem)) continue+ candidates.push(file)+ }+ let best: { file: string; score: number } | undefined+ for (const file of candidates) {+ const score = coverageScore(file)+ if (score > 0 && (!best || score > best.score)) best = { file, score }+ }+ if (!best) return undefined+ const stem = path.basename(best.file).replace(/\.(ttf|otf)$/i, '')+ return facesForPrefix(stem.replace(/-(Regular|Book)$/i, ''))+}++/**+ * PostScript names of the faces inside a TrueType Collection.+ *+ * Debian packages Noto CJK only as collections, and a collection cannot be+ * embedded in a PDF without naming which face to take — so without this, a+ * Chinese, Japanese or Korean document loses its text entirely. Parsed here+ * rather than through a font library because the only consumer of one is+ * pdfkit, reached through pdfmake.+ */+function collectionFaceNames(file: string): string[] {+ return (+ withFileReader(file, read => {+ const names: string[] = []+ for (const dirOffset of (collectionOffsets(read) ?? []).slice(0, 64)) {+ const name = postScriptName(read, tableDirectory(read, dirOffset))+ if (name && !names.includes(name)) names.push(name)+ }+ return names+ }) ?? []+ )+}++// What a face can draw is read from its cmap, which is exactly what pdfkit+// consults when it embeds text, instead of being inferred from a rendering.++/** `length` bytes at `offset`, or undefined when that runs past the end. */+type ByteReader = (offset: number, length: number) => Buffer | undefined++function bufferReader(buf: Buffer): ByteReader {+ return (offset, length) =>+ offset >= 0 && length >= 0 && offset + length <= buf.length+ ? buf.subarray(offset, offset + length)+ : undefined+}++/** Run `use` over `file`, reading only the byte ranges it asks for. */+function withFileReader<T>(file: string, use: (read: ByteReader) => T): T | undefined {+ let fd: number+ try {+ fd = fs.openSync(file, 'r')+ } catch {+ return undefined+ }+ try {+ const size = fs.fstatSync(fd).size+ return use((offset, length) => {+ if (offset < 0 || length < 0 || offset + length > size) return undefined+ const out = Buffer.alloc(length)+ fs.readSync(fd, out, 0, length, offset)+ return out+ })+ } catch {+ return undefined+ } finally {+ fs.closeSync(fd)+ }+}++/** Table-directory offsets of the faces in a collection; undefined for a single face. */+function collectionOffsets(read: ByteReader): number[] | undefined {+ const head = read(0, 12)+ if (!head || head.toString('latin1', 0, 4) !== 'ttcf') return undefined+ const count = head.readUInt32BE(8)+ const table = read(12, count * 4)+ if (!table) return []+ return Array.from({ length: count }, (_, i) => table.readUInt32BE(i * 4))+}++interface TableEntry {+ offset: number+ length: number+}++function tableDirectory(read: ByteReader, dirOffset: number): Map<string, TableEntry> {+ const tables = new Map<string, TableEntry>()+ const head = read(dirOffset, 12)+ if (!head) return tables+ const count = head.readUInt16BE(4)+ const records = read(dirOffset + 12, count * 16)+ if (!records) return tables+ for (let t = 0; t < count; t++) {+ const at = t * 16+ tables.set(records.toString('latin1', at, at + 4), {+ offset: records.readUInt32BE(at + 8),+ length: records.readUInt32BE(at + 12),+ })+ }+ return tables+}++function postScriptName(read: ByteReader, tables: Map<string, TableEntry>): string | undefined {+ const entry = tables.get('name')+ const table = entry && read(entry.offset, entry.length)+ if (!table || table.length < 6) return undefined+ const count = table.readUInt16BE(2)+ const stringOffset = table.readUInt16BE(4)+ for (let r = 0; r < count; r++) {+ const rec = 6 + r * 12+ if (rec + 12 > table.length) break+ // nameID 6 is the PostScript name, which is what pdfkit looks up.+ if (table.readUInt16BE(rec + 6) !== 6) continue+ const platformId = table.readUInt16BE(rec)+ const len = table.readUInt16BE(rec + 8)+ const off = stringOffset + table.readUInt16BE(rec + 10)+ if (off + len > table.length) continue+ const raw = Buffer.from(table.subarray(off, off + len))+ // Platform 3 (Windows) stores UTF-16BE; the others are single-byte.+ const text = platformId === 3 ? raw.swap16().toString('utf16le') : raw.toString('latin1')+ const clean = text.replace(/[^\x20-\x7E]/g, '').trim()+ if (clean) return clean+ }+ return undefined+}++/** Appends `cp` to sorted `[first, last, ...]` ranges, extending the last one when adjacent. */+function addCodePoint(ranges: number[], cp: number): void {+ const n = ranges.length+ if (n > 0 && ranges[n - 1] === cp - 1) ranges[n - 1] = cp+ else if (n === 0 || ranges[n - 1] < cp) ranges.push(cp, cp)+}++function format4Ranges(t: Buffer, off: number): number[] {+ const ranges: number[] = []+ const segX2 = t.readUInt16BE(off + 6)+ const ends = off + 14+ const starts = ends + segX2 + 2+ const deltas = starts + segX2+ const rangeOffsets = deltas + segX2+ if (rangeOffsets + segX2 > t.length) return ranges+ for (let s = 0; s < segX2 / 2; s++) {+ const end = t.readUInt16BE(ends + 2 * s)+ const start = t.readUInt16BE(starts + 2 * s)+ const delta = t.readUInt16BE(deltas + 2 * s)+ const ro = t.readUInt16BE(rangeOffsets + 2 * s)+ for (let c = start; c <= Math.min(end, 0xfffe); c++) {+ let glyph: number+ if (ro === 0) {+ glyph = (c + delta) & 0xffff+ } else {+ const at = rangeOffsets + 2 * s + ro + 2 * (c - start)+ glyph = at + 2 <= t.length ? t.readUInt16BE(at) : 0+ if (glyph !== 0) glyph = (glyph + delta) & 0xffff+ }+ if (glyph !== 0) addCodePoint(ranges, c)+ }+ }+ return ranges+}++function format12Ranges(t: Buffer, off: number): number[] {+ const groups: Array<[number, number]> = []+ const count = t.readUInt32BE(off + 12)+ for (let g = 0; g < count; g++) {+ const at = off + 16 + g * 12+ if (at + 12 > t.length) break+ const first = t.readUInt32BE(at)+ const last = t.readUInt32BE(at + 4)+ // A group starting at glyph 0 maps its first code point to .notdef.+ const from = t.readUInt32BE(at + 8) === 0 ? first + 1 : first+ if (from <= last) groups.push([from, last])+ }+ groups.sort((a, b) => a[0] - b[0])+ const ranges: number[] = []+ for (const [first, last] of groups) {+ const n = ranges.length+ if (n > 0 && first <= ranges[n - 1] + 1) ranges[n - 1] = Math.max(ranges[n - 1], last)+ else ranges.push(first, last)+ }+ return ranges+}++/** Unicode ranges the face's cmap maps to a glyph, from its widest Unicode subtable. */+function cmapRanges(read: ByteReader, tables: Map<string, TableEntry>): number[] {+ const entry = tables.get('cmap')+ const t = entry && read(entry.offset, entry.length)+ if (!t || t.length < 4) return []+ let best: { off: number; format: number } | undefined+ for (let i = 0; i < t.readUInt16BE(2); i++) {+ const rec = 4 + i * 8+ if (rec + 8 > t.length) break+ const platform = t.readUInt16BE(rec)+ const encoding = t.readUInt16BE(rec + 2)+ const off = t.readUInt32BE(rec + 4)+ if (off + 16 > t.length) continue+ const format = t.readUInt16BE(off)+ const unicode = platform === 0 || (platform === 3 && (encoding === 1 || encoding === 10))+ if (!unicode || (format !== 4 && format !== 12)) continue+ if (!best || (format === 12 && best.format !== 12)) best = { off, format }+ }+ if (!best) return []+ return best.format === 12 ? format12Ranges(t, best.off) : format4Ranges(t, best.off)+}++interface FaceInfo {+ /** Sorted `[first, last, ...]` code point ranges the face has glyphs for. */+ ranges: number[]+ /** Vertical metrics as pdfkit reads them, or undefined when the face has none. */+ metrics?: FaceMetrics+ /** Carries OpenType or AAT layout tables, so fontkit shapes and orders a right-to-left run itself. */+ shapes: boolean+ /** Has outlines pdfkit can embed; colour-bitmap emoji faces have none. */+ outlines: boolean+}++/** From `hhea` and `head`, the tables fontkit reads ascent and descent from. */+function faceMetrics(read: ByteReader, tables: Map<string, TableEntry>): FaceMetrics | undefined {+ const hhea = tables.get('hhea')+ const head = tables.get('head')+ const vertical = hhea && read(hhea.offset + 4, 4)+ const units = head && read(head.offset + 18, 2)+ const em = units?.readUInt16BE(0)+ if (!vertical || !em) return undefined+ const ascent = vertical.readInt16BE(0) / em+ return { ascent, lineHeight: ascent - vertical.readInt16BE(2) / em }+}++function faceInfoAt(read: ByteReader, dirOffset: number): FaceInfo {+ const tables = tableDirectory(read, dirOffset)+ return {+ ranges: cmapRanges(read, tables),+ metrics: faceMetrics(read, tables),+ shapes: tables.has('GSUB') || tables.has('GPOS') || tables.has('morx'),+ outlines:+ (tables.has('glyf') || tables.has('CFF ')) && !tables.has('CBDT') && !tables.has('sbix'),+ }+}++function readFaceInfo(face: PdfFace): FaceInfo | undefined {+ if (Buffer.isBuffer(face)) {+ const read = bufferReader(face)+ return faceInfoAt(read, collectionOffsets(read)?.[0] ?? 0)+ }+ const [file, wanted] = Array.isArray(face) ? face : [face, undefined]+ return withFileReader(file, read => {+ const offsets = collectionOffsets(read)+ if (!offsets) return faceInfoAt(read, 0)+ const at = wanted+ ? offsets.find(o => postScriptName(read, tableDirectory(read, o)) === wanted)+ : offsets[0]+ return at === undefined ? undefined : faceInfoAt(read, at)+ })+}++function coversCodePoint(ranges: number[], cp: number): boolean {+ let lo = 0+ let hi = ranges.length / 2 - 1+ while (lo <= hi) {+ const mid = (lo + hi) >> 1+ if (cp < ranges[mid * 2]) hi = mid - 1+ else if (cp > ranges[mid * 2 + 1]) lo = mid + 1+ else return true+ }+ return false+}++/** Collections worth embedding, and the script variants to prefer within them. */+const COLLECTION_PREFERENCE = [/CJKsc-/i, /CJKjp-/i, /CJKtc-/i, /CJKkr-/i, /CJKhk-/i]++/**+ * Faces from a collection on disk, preferring a proportional script variant+ * over the monospaced ones. Returns undefined when the file names no usable+ * face, so the caller can move on to the next candidate.+ */+function facesFromCollection(file: string, boldFile?: string): PdfFaces | undefined {+ const names = collectionFaceNames(file).filter(n => !/Mono/i.test(n))+ if (names.length === 0) return undefined+ const pick =+ COLLECTION_PREFERENCE.map(re => names.find(n => re.test(n))).find(Boolean) ?? names[0]+ const boldNames = boldFile ? collectionFaceNames(boldFile).filter(n => !/Mono/i.test(n)) : []+ const boldPick =+ COLLECTION_PREFERENCE.map(re => boldNames.find(n => re.test(n))).find(Boolean) ?? boldNames[0]+ const normal: PdfFace = [file, pick]+ const bold: PdfFace = boldFile && boldPick ? [boldFile, boldPick] : normal+ return { normal, bold, italics: normal, bolditalics: bold }+}++/** Collections on this image, keyed by lowercased basename. */+function embeddableCollections(): Map<string, string> {+ if (collectionIndex) return collectionIndex+ const index = new Map<string, string>()+ for (const dir of SYSTEM_FONT_DIRS) {+ try {+ if (!fs.existsSync(dir)) continue+ for (const file of walk(dir, 0)) {+ if (!/\.ttc$/i.test(file)) continue+ const stem = path+ .basename(file)+ .replace(/\.ttc$/i, '')+ .toLowerCase()+ if (!index.has(stem)) index.set(stem, file)+ }+ } catch {+ continue+ }+ }+ collectionIndex = index+ return index+}++let collectionIndex: Map<string, string> | undefined++/**+ * The best CJK-capable collection the image ships, chosen by what it can+ * actually draw rather than by its filename.+ */+function cjkCollectionFaces(): PdfFaces | undefined {+ const collections = embeddableCollections()+ let best: { faces: PdfFaces; score: number } | undefined+ for (const [stem, file] of collections) {+ if (!/cjk/.test(stem) || /serif/.test(stem) || /bold/.test(stem)) continue+ const score = coverageScore(file)+ // Rejects a symbols-only fallback, which sets no Latin and would leave the+ // document unreadable.+ if (score <= 0) continue+ const boldFile = collections.get(stem.replace(/-regular$/, '-bold'))+ const faces = facesFromCollection(file, boldFile)+ if (faces && (!best || score > best.score)) best = { faces, score }+ }+ return best?.faces+}++function resolvePdfFaces(): PdfFaces {+ if (pdfFaces) return pdfFaces+ ensureFontsReady()+ // A family with a real italic face comes first, since *emphasis* is drawn+ // upright in one without; CJK falls back per character to the collection.+ // Only an image with no standalone family takes the collection as body.+ const named = PDF_FAMILY_PREFIXES.map(prefix => () => facesForPrefix(prefix))+ const withItalic = named.map(faces => () => {+ const found = faces()+ return found && found.italics !== found.normal ? found : undefined+ })+ const candidates: Array<() => PdfFaces | undefined> = [+ ...withItalic,+ ...named,+ cjkCollectionFaces,+ discoverWideFace,+ ]+ let chosen: PdfFaces | undefined+ for (const candidate of candidates) {+ const faces = candidate()+ if (faces && embeds(faces, 'Ag0')) {+ chosen = faces+ break+ }+ }+ if (chosen) {+ // Registering the chosen family under the PDF alias is what lets glyph+ // coverage be measured against the faces the PDF will actually embed.+ const file = Array.isArray(chosen.normal) ? chosen.normal[0] : chosen.normal+ try {+ if (typeof file === 'string') GlobalFonts.registerFromPath(file, PDF_FONT_FAMILY)+ pdfFaces = chosen+ return pdfFaces+ } catch {+ // Unparseable face: fall through to the bundled one.+ }+ }+ const roboto = loadRobotoFaces()+ GlobalFonts.register(roboto.normal, PDF_FONT_FAMILY)+ pdfFaces = roboto+ return pdfFaces+}++function resolveMonoFaces(): PdfFaces {+ if (monoFaces) return monoFaces+ ensureFontsReady()+ for (const prefix of MONO_FAMILY_PREFIXES) {+ const faces = facesForPrefix(prefix)+ if (faces && embeds(faces, 'Ag0')) {+ monoFaces = faces+ return monoFaces+ }+ }+ // No fixed-width face on this image. The body face would render the block+ // but lose its column alignment, so Western text goes to the PDF viewer's+ // built-in Courier and everything else falls back per character to embedded faces.+ monoFaces = COURIER_FACES+ return monoFaces+}++/** The standard-14 Courier. pdfkit encodes it as WinAnsi, so it can draw only that set. */+const COURIER_FACES: PdfFaces = {+ normal: 'Courier',+ bold: 'Courier-Bold',+ italics: 'Courier-Oblique',+ bolditalics: 'Courier-BoldOblique',+}++/** Courier's advance width, in ems, for every character it is given. */+const COURIER_ADVANCE = 0.6++/** What pdfkit knows of Courier: WinAnsi coverage, and the ascent (629) and descent (-157) of its AFM. */+const COURIER_INFO: FaceInfo = (() => {+ const ranges: number[] = []+ const winAnsi = [+ 0x152, 0x153, 0x160, 0x161, 0x178, 0x17d, 0x17e, 0x192, 0x2c6, 0x2dc, 0x2013, 0x2014, 0x2018,+ 0x2019, 0x201a, 0x201c, 0x201d, 0x201e, 0x2020, 0x2021, 0x2022, 0x2026, 0x2030, 0x2039, 0x203a,+ 0x20ac, 0x2122,+ ]+ for (let cp = 0x20; cp <= 0x7e; cp++) addCodePoint(ranges, cp)+ for (let cp = 0xa0; cp <= 0xff; cp++) addCodePoint(ranges, cp)+ for (const cp of winAnsi) addCodePoint(ranges, cp)+ return { ranges, metrics: { ascent: 0.629, lineHeight: 0.786 }, shapes: false, outlines: true }+})()++/** Font descriptors for `new PdfPrinter(...)`, keyed by the families pdfmake uses. */+export function pdfFontDescriptors(): Record<string, PdfFaces> {+ return {+ [PDF_FONT_FAMILY]: resolvePdfFaces(),+ [PDF_MONO_FAMILY]: resolveMonoFaces(),+ }+}++// pdfmake embeds whatever family a run names, so a character the body face+// lacks is drawn by giving its run another family. No CJK or Latin face carries+// Arabic or Hebrew, so those always come from here.++/**+ * Faces tried, in order, for a character the run's own face lacks. The script+ * faces lead so Arabic and Hebrew are set in faces drawn for them rather than+ * in a broad face that carries a few of their letters.+ */+const SCRIPT_FALLBACK_PREFIXES = [+ // Alpine's Noto Sans Arabic draws letters as a dotless base shared by several+ // letters plus dot marks, and pdfkit's ToUnicode map gives each glyph one+ // letter, so the text layer reads wrong letters; its UI build does not.+ 'NotoSansArabicUI',+ 'NotoSansArabic',+ 'NotoNaskhArabic',+ 'NotoKufiArabic',+ 'NotoSansHebrew',+ 'NotoSerifHebrew',+ 'NotoRashiHebrew',+]++/** Tried after the script faces and the CJK collection. */+const FALLBACK_PREFIXES = [+ 'DejaVuSans',+ 'NotoSans',+ 'LiberationSans',+ 'NotoSansSymbols2',+ 'NotoSansSymbols',+ 'NotoSansMath',+]++/** Other regular-weight faces from the families the images install, tried after the list above. */+const FALLBACK_STEM = /^(noto|dejavu|liberation)[a-z0-9]*(-regular)?$/++interface FallbackFamily {+ family: string+ faces: PdfFaces+}++/** Vertical metrics of a face in ems, as pdfkit uses them to lay out a line. */+export interface FaceMetrics {+ /** Height above the baseline. */+ ascent: number+ /** Ascent less descent: the height of one line before pdfmake's lineHeight factor. */+ lineHeight: number+}++/** Everything a PDF typesetter needs to know about the faces available to it. */+export interface PdfGlyphSource {+ /** Family that can draw `cp` in a run set in `base`, or undefined when no face can. */+ familyFor(cp: number, base: string): string | undefined+ /** Whether fontkit puts a right-to-left run set in `family` into display order itself. */+ reversesRtl(family: string): boolean+ /** Advance width of `text` set in `family` at `size` points. */+ measure(text: string, family: string, size: number, bold: boolean): number+ /** Vertical metrics of `family`, or undefined when unknown. */+ metrics(family: string): FaceMetrics | undefined+ /** pdfmake descriptors for `families`, always including the body and mono ones. */+ descriptors(families: Iterable<string>): Record<string, PdfFaces>+}++function faceFile(face: PdfFace): string | undefined {+ if (Buffer.isBuffer(face)) return undefined+ return Array.isArray(face) ? face[0] : face+}++/**+ * Whether pdfkit can lay out and embed `ch` in `faces`. Some faces an image+ * ships parse for their cmap yet fail inside pdfkit ("Not a fixed size"), and+ * one such face named by a single run fails the whole document.+ */+function embeds(faces: PdfFaces, ch: string): boolean {+ try {+ const PdfPrinter = require('pdfmake')+ const doc = new PdfPrinter({ Probe: faces }).createPdfKitDocument({+ content: [{ text: ch, font: 'Probe' }],+ defaultStyle: { font: 'Probe' },+ })+ doc.on('data', () => undefined)+ doc.end()+ return true+ } catch {+ return false+ }+}++function discoverFallbacks(exclude: Set<string>): FallbackFamily[] {+ const out: FallbackFamily[] = []+ const seen = new Set<string>()+ const add = (prefix: string): void => {+ const faces = facesForPrefix(prefix)+ const file = faces && faceFile(faces.normal)+ if (!faces || !file || seen.has(file) || exclude.has(file)) return+ seen.add(file)+ out.push({ family: `Fallback-${prefix}`, faces })+ }+ SCRIPT_FALLBACK_PREFIXES.forEach(add)+ const cjk = cjkCollectionFaces()+ const cjkFile = cjk && faceFile(cjk.normal)+ if (cjk && cjkFile && !exclude.has(cjkFile)) {+ seen.add(cjkFile)+ out.push({ family: 'Fallback-CJK', faces: cjk })+ }+ FALLBACK_PREFIXES.forEach(add)+ const rest = [...embeddableFaces().keys()]+ .filter(stem => FALLBACK_STEM.test(stem) && !/mono|emoji/.test(stem))+ .sort((a, b) => Number(/serif/.test(a)) - Number(/serif/.test(b)) || a.localeCompare(b))+ for (const stem of rest)+ add(path.basename(embeddableFaces().get(stem)!).replace(/(-Regular)?\.(ttf|otf)$/i, ''))+ return out+}++class GlyphSource implements PdfGlyphSource {+ private readonly info = new Map<string, FaceInfo | undefined>()+ private readonly chosen = new Map<string, string | undefined>()+ private readonly embeddable = new Map<string, boolean>()+ // resolvePdfFaces registers the body family with the canvas itself.+ private readonly registered = new Set<string>([PDF_FONT_FAMILY])+ private fallbacks?: FallbackFamily[]+ private ctx?: SKRSContext2D++ private facesOf(family: string): PdfFaces | undefined {+ if (family === PDF_FONT_FAMILY) return resolvePdfFaces()+ if (family === PDF_MONO_FAMILY) return resolveMonoFaces()+ return this.fallbackList().find(f => f.family === family)?.faces+ }++ private fallbackList(): FallbackFamily[] {+ if (!this.fallbacks) {+ const exclude = new Set<string>()+ for (const faces of [resolvePdfFaces(), resolveMonoFaces()]) {+ const file = faceFile(faces.normal)+ if (file) exclude.add(file)+ }+ this.fallbacks = discoverFallbacks(exclude)+ }+ return this.fallbacks+ }++ private infoOf(family: string): FaceInfo | undefined {+ if (!this.info.has(family)) {+ const faces = this.facesOf(family)+ let info: FaceInfo | undefined+ if (faces === COURIER_FACES) info = COURIER_INFO+ else if (faces) info = readFaceInfo(faces.normal)+ this.info.set(family, info?.outlines ? info : undefined)+ }+ return this.info.get(family)+ }++ private covers(family: string, cp: number): boolean {+ const info = this.infoOf(family)+ return info !== undefined && coversCodePoint(info.ranges, cp)+ }++ /** A fallback face is tried in pdfkit once, with the first character it is chosen for. */+ private usable(fallback: FallbackFamily, cp: number): boolean {+ let ok = this.embeddable.get(fallback.family)+ if (ok === undefined) {+ ok = embeds(fallback.faces, String.fromCodePoint(cp))+ this.embeddable.set(fallback.family, ok)+ }+ return ok+ }++ familyFor(cp: number, base: string): string | undefined {+ const key = `${base}\u0000${cp}`+ if (this.chosen.has(key)) return this.chosen.get(key)+ let hit: string | undefined+ if (this.covers(base, cp)) hit = base+ else if (base !== PDF_FONT_FAMILY && this.covers(PDF_FONT_FAMILY, cp)) hit = PDF_FONT_FAMILY+ else {+ hit = this.fallbackList().find(f => this.covers(f.family, cp) && this.usable(f, cp))?.family+ }+ this.chosen.set(key, hit)+ return hit+ }++ reversesRtl(family: string): boolean {+ return this.infoOf(family)?.shapes ?? false+ }++ metrics(family: string): FaceMetrics | undefined {+ return this.infoOf(family)?.metrics+ }++ measure(text: string, family: string, size: number, bold: boolean): number {+ const faces = this.facesOf(family)+ if (!faces || faces === COURIER_FACES) return [...text].length * size * COURIER_ADVANCE+ // The bold face is registered on its own, because the canvas would+ // otherwise embolden the regular one, which is narrower than the face+ // pdfkit embeds.+ const face = bold ? faces.bold : faces.normal+ const alias = bold ? `${family} Bold` : family+ if (!this.registered.has(alias)) {+ this.registered.add(alias)+ ensureFontsReady()+ try {+ if (Buffer.isBuffer(face)) GlobalFonts.register(face, alias)+ else GlobalFonts.registerFromPath(faceFile(face)!, alias)+ } catch {+ // Measured with the canvas default instead; only line breaking is approximate.+ }+ }+ this.ctx ??= createCanvas(8, 8).getContext('2d')+ this.ctx.font = `${size}px "${alias}"`+ return this.ctx.measureText(text).width+ }++ descriptors(families: Iterable<string>): Record<string, PdfFaces> {+ const out = pdfFontDescriptors()+ for (const family of families) {+ const faces = this.facesOf(family)+ if (faces) out[family] = faces+ }+ return out+ }+}++let glyphSource: GlyphSource | undefined++/** The faces this image offers the PDF renderer, with per-character fallback between them. */+export function pdfGlyphSource(): PdfGlyphSource {+ glyphSource ??= new GlyphSource()+ return glyphSource+}++// ─── Glyph coverage ──────────────────────────────────────────────────+//+// Chart text is checked by rendering it through the canvas fallback stack.+// PDFs do not use this: pdfGlyphSource reads each face's cmap and falls back+// per character.++let missingSignature: string | undefined+const coverage = new Map<number, boolean>()++/**+ * Signature of the pixels a character leaves when drawn in `font`.+ *+ * A plain ink count is not enough to tell a real glyph from the missing-glyph+ * box: the two collide whenever they happen to darken the same number of+ * pixels, and the character is then rewritten even though the font could draw+ * it. Hashing the bitmap makes a collision effectively impossible.+ */+function renderSignature(ch: string, font: string): string {+ const canvas = createCanvas(64, 64)+ const ctx = canvas.getContext('2d')+ ctx.fillStyle = '#ffffff'+ ctx.fillRect(0, 0, 64, 64)+ ctx.fillStyle = '#000000'+ ctx.font = `36px ${font}`+ ctx.fillText(ch, 6, 46)+ const data = ctx.getImageData(0, 0, 64, 64).data+ // FNV-1a over the thresholded (ink / no ink) bitmap, plus the ink count so an+ // all-blank render stands out when debugging.+ let hash = 0x811c9dc5+ let ink = 0+ for (let i = 0; i < data.length; i += 4) {+ const dark = data[i] < 128 ? 1 : 0+ if (dark) ink+++ hash ^= dark+ hash = Math.imul(hash, 0x01000193) >>> 0+ }+ return `${ink}:${hash.toString(36)}`+}++/**+ * Whether the chart fonts can actually draw `ch`. Determined by rendering,+ * because a font reports a width for glyphs it substitutes.+ */+export function canRender(ch: string): boolean {+ const cp = ch.codePointAt(0)+ if (cp === undefined || cp < 0x80) return true+ const cached = coverage.get(cp)+ if (cached !== undefined) return cached+ let ok: boolean+ try {+ ensureFontsReady()+ missingSignature ??= renderSignature(MISSING_PROBE, CHART_FONT_STACK)+ ok = renderSignature(ch, CHART_FONT_STACK) !== missingSignature+ } catch {+ ok = false+ }+ coverage.set(cp, ok)+ return ok+}++/**+ * ASCII stand-ins for symbols models reach for constantly. Applied only when+ * the character cannot be drawn, so a renderer whose fonts carry the glyph+ * keeps the original.+ */+const SUBSTITUTIONS: Record<string, string> = {+ '\u2192': '->',+ '\u27F6': '->',+ '\u279C': '->',+ '\u2794': '->',+ '\u2190': '<-',+ '\u2194': '<->',+ '\u21D2': '=>',+ '\u21D0': '<=',+ '\u21D4': '<=>',+ '\u2191': '^',+ '\u2193': 'v',+ '\u2713': 'OK',+ '\u2714': 'OK',+ '\u2611': '[x]',+ '\u2717': 'X',+ '\u2718': 'X',+ '\u2612': '[x]',+ '\u2248': '~',+ '\u2265': '>=',+ '\u2264': '<=',+ '\u2260': '!=',+ '\u2261': '==',+ '\u221E': 'inf',+ '\u2022': '*',+ '\u2023': '-',+ '\u25AA': '-',+ '\u25AB': '-',+ '\u25E6': '-',+ '\u25CF': '*',+ '\u25CB': 'o',+ '\u2605': '*',+ '\u2606': '*',+ '\u26A0': '!',+ '\u2122': '(TM)',+ '\u2120': '(SM)',+ '\u2014': '-',+ '\u2013': '-',+ '\u2026': '...',+ '\u201C': '"',+ '\u201D': '"',+ '\u2018': "'",+ '\u2019': "'",+ '\u2010': '-',+ '\u2011': '-',+ '\u2212': '-',+ // Space variants: locale-formatted numbers and times carry U+202F and U+00A0.+ '\u00A0': ' ',+ '\u2000': ' ',+ '\u2001': ' ',+ '\u2002': ' ',+ '\u2003': ' ',+ '\u2004': ' ',+ '\u2005': ' ',+ '\u2006': ' ',+ '\u2007': ' ',+ '\u2008': ' ',+ '\u2009': ' ',+ '\u200A': ' ',+ '\u202F': ' ',+ '\u205F': ' ',+ '\u3000': ' ',+ // Status emoji, which models often put alone in a table cell. No embedded+ // face draws them in colour, and a coloured circle means only its colour,+ // so they become words.+ '\u2705': 'OK',+ '\u2716': 'X',+ '\u274c': 'X',+ '\u274e': 'X',+ '\u2757': '!',+ '\u2755': '!',+ '\u2753': '?',+ '\u2754': '?',+ '\u2b50': '*',+ '\u2b06': '^',+ '\u2b07': 'v',+ '\u27a1': '->',+ '\u2b05': '<-',+ '\u{1F7E2}': '(green)',+ '\u{1F7E1}': '(yellow)',+ '\u{1F7E0}': '(orange)',+ '\u{1F534}': '(red)',+ '\u{1F535}': '(blue)',+ '\u{1F7E3}': '(purple)',+ '\u{1F7E4}': '(brown)',+ '\u26ab': '(black)',+ '\u26aa': '(white)',+ '\u{1F7E9}': '(green)',+ '\u{1F7E8}': '(yellow)',+ '\u{1F7E7}': '(orange)',+ '\u{1F7E5}': '(red)',+ '\u{1F7E6}': '(blue)',+ '\u{1F7EA}': '(purple)',+ '\u{1F7EB}': '(brown)',+ '\u2b1b': '(black)',+ '\u2b1c': '(white)',+ '\u{1F4C8}': '(up)',+ '\u{1F4C9}': '(down)',+}++/** The ASCII stand-in for a symbol or status emoji, when one is defined. */+export function asciiStandIn(ch: string): string | undefined {+ return SUBSTITUTIONS[ch]+}++/** Zero-width joiners, variation selectors and byte-order marks — safe to drop. */+const INVISIBLE = /[\u200B-\u200F\u2060\uFE00-\uFE0F\uFEFF]/g++const NON_ASCII = /[^\x00-\x7F]/++/**+ * Rewrite chart text so every character survives rendering. Characters the+ * chart fonts cover are untouched; the rest become their ASCII stand-in, and+ * anything with no stand-in is dropped rather than drawn as a blank box.+ */+export function sanitizeForFont(text: string): string {+ if (!text || !NON_ASCII.test(text)) return text++ let out = ''+ for (const ch of text.replace(INVISIBLE, '')) {+ if (canRender(ch)) {+ out += ch+ continue+ }+ const sub = SUBSTITUTIONS[ch]+ if (sub !== undefined) out += sub+ // No stand-in and no glyph: dropped, which keeps the surrounding text+ // legible instead of drawing a blank box or a different character.+ }+ return out+}diff --git a/mcp-host/src/workflow/inlineMarkup.ts b/mcp-host/src/workflow/inlineMarkup.tsnew file mode 100644index 000000000..ecbc01cdf--- /dev/null+++ b/mcp-host/src/workflow/inlineMarkup.ts@@ -0,0 +1,449 @@+/**+ * Inline markdown, and the bits of HTML models mix into it, read once for the+ * PDF and DOCX generators so both print the same text the same way.+ *+ * Every pattern here runs on text a model wrote, so none may backtrack across+ * the input: each stops at the next tag, bracket or marker of its own kind.+ */++// A tag's attributes. Each takes a value unless it is one of HTML's boolean+// attributes, so text such as "a<b and c>d" is not read as a <b> tag.+const ATTRIBUTES =+ '(?:\\s+(?:(?:allowfullscreen|async|checked|controls|default|defer|disabled|hidden|inert|' ++ 'loop|multiple|muted|nowrap|open|readonly|required|reversed|selected)(?![-\\w:.=])|' ++ '[A-Za-z_:][-\\w:.]*\\s*=\\s*(?:"[^"<>]*"|\'[^\'<>]*\'|[^\\s"\'=<>`]+)))*\\s*'++/** Opening and closing tags named by the `names` alternatives, with their attributes. */+const tag = (names: string) => `</?(?:${names})${ATTRIBUTES}>`++const SCRIPT_OPEN = /<(script|style)\b[^<>]*>/gi+const LINE_BREAK = /<br\s*\/?>/gi+// A block or cell boundary ends a word even when no space surrounds the tags.+const BLOCK_EDGE = new RegExp(+ `(?:${tag(+ 'article|blockquote|caption|dd|details|div|dt|figcaption|figure|footer|h[1-6]|header|li|ol|p|pre|section|summary|table|tr|ul'+ )}\\s*)+`,+ 'gi'+)+const CELL_EDGE = new RegExp(`(?:${tag('t[dh]')}\\s*)+`, 'gi')+const BOLD_TAG = new RegExp(tag('b|strong'), 'gi')+const ITALIC_TAG = new RegExp(tag('i|em'), 'gi')+const CODE_TAG = new RegExp(tag('code|kbd|tt'), 'gi')+const STRIKE_TAG = new RegExp(tag('del|s|strike'), 'gi')+const LIST_TAG = new RegExp(`<(/?)(ul|ol|li)${ATTRIBUTES}>`, 'gi')+const IMG_TAG = /<img\b[^<>]*>/gi+const IMG_SRC = /\bsrc\s*=\s*(["'])([^"'<>]+)\1/i+/** A backslash before ASCII punctuation, which CommonMark prints as that character. */+const ESCAPE = /\\[!-/:-@[-`{-~]/+// The label stops at the next anchor tag, so an unclosed <a> is not rescanned+// to the end of the text from every opening.+const ANCHOR =+ /<a\s[^<>]*?href\s*=\s*["']((?:https?:\/\/|mailto:)[^"'\s<>]+)["'][^<>]*>((?:[^<]|<(?!\/?a[\s>]))*?)<\/a\s*>/gi++// Only real element names are removed, so a placeholder such as <namespace>+// in a command survives as text.+const HTML_TAG = new RegExp(+ '</?(?:' ++ [+ 'a',+ 'abbr',+ 'article',+ 'aside',+ 'big',+ 'blockquote',+ 'caption',+ 'center',+ 'cite',+ 'dd',+ 'del',+ 'details',+ 'div',+ 'dl',+ 'dt',+ 'figcaption',+ 'figure',+ 'font',+ 'footer',+ 'h[1-6]',+ 'header',+ 'hr',+ 'img',+ 'ins',+ 'label',+ 'li',+ 'mark',+ 'nav',+ 'ol',+ 'p',+ 'pre',+ 's',+ 'script',+ 'section',+ 'small',+ 'span',+ 'strike',+ 'style',+ 'sub',+ 'summary',+ 'sup',+ 'table',+ 'tbody',+ 'td',+ 'tfoot',+ 'th',+ 'thead',+ 'time',+ 'tr',+ 'u',+ 'ul',+ ].join('|') ++ `)${ATTRIBUTES}/?>`,+ 'gi'+)++const NAMED_ENTITIES: Record<string, string> = {+ amp: '&',+ lt: '<',+ gt: '>',+ quot: '"',+ apos: "'",+ nbsp: '\u00A0',+ ndash: '\u2013',+ mdash: '\u2014',+ hellip: '\u2026',+ lsquo: '\u2018',+ rsquo: '\u2019',+ ldquo: '\u201C',+ rdquo: '\u201D',+ laquo: '\u00AB',+ raquo: '\u00BB',+ middot: '\u00B7',+ bull: '\u2022',+ times: '\u00D7',+ divide: '\u00F7',+ deg: '\u00B0',+ copy: '\u00A9',+ reg: '\u00AE',+ trade: '\u2122',+ euro: '\u20AC',+ pound: '\u00A3',+ yen: '\u00A5',+ cent: '\u00A2',+}++/** Code points XML 1.0 can carry; a numeric reference to anything else stays literal. */+function xmlAllowed(cp: number): boolean {+ return (+ cp === 0x9 ||+ cp === 0xa ||+ (cp >= 0x20 && cp <= 0xd7ff) ||+ (cp >= 0xe000 && cp <= 0xfffd) ||+ (cp >= 0x10000 && cp <= 0x10ffff)+ )+}++/** Character references decoded; an unknown or unrepresentable one stays as written. */+export function decodeEntities(text: string): string {+ if (!text.includes('&')) return text+ return text.replace(/&(#x[0-9a-f]{1,6}|#\d{1,7}|[a-z]{2,8});/gi, (entity, name: string) => {+ if (name.startsWith('#')) {+ const cp =+ name[1] === 'x' || name[1] === 'X' ? parseInt(name.slice(2), 16) : parseInt(name.slice(1))+ return xmlAllowed(cp) ? String.fromCodePoint(cp) : entity+ }+ return NAMED_ENTITIES[name.toLowerCase()] ?? entity+ })+}++/** `text` without HTML comments, found in one pass; an unclosed one is left as written. */+function withoutComments(text: string): string {+ if (!text.includes('<!--')) return text+ let out = ''+ let at = 0+ for (let open = text.indexOf('<!--'); open >= 0; open = text.indexOf('<!--', at)) {+ const close = text.indexOf('-->', open + 4)+ if (close < 0) break+ out += text.slice(at, open)+ at = close + 3+ }+ return out + text.slice(at)+}++/** `text` without <script> and <style> elements, found in one pass. */+function withoutScripts(text: string): string {+ if (!/<(?:script|style)\b/i.test(text)) return text+ const lower = text.toLowerCase()+ let out = ''+ let at = 0+ SCRIPT_OPEN.lastIndex = 0+ for (let open = SCRIPT_OPEN.exec(text); open; open = SCRIPT_OPEN.exec(text)) {+ const close = lower.indexOf(`</${open[1].toLowerCase()}`, SCRIPT_OPEN.lastIndex)+ const end = close < 0 ? -1 : lower.indexOf('>', close)+ if (end < 0) break+ out += text.slice(at, open.index)+ at = end + 1+ SCRIPT_OPEN.lastIndex = at+ }+ return out + text.slice(at)+}++/**+ * Replace `pattern` with `separator` between words, and with nothing at either+ * end of `text`. A match that already spans a line break keeps the break.+ */+function separate(text: string, pattern: RegExp, separator: string): string {+ return text.replace(pattern, (match: string, offset: number) =>+ offset === 0 || offset + match.length === text.length+ ? ''+ : match.includes('\n')+ ? '\n'+ : separator+ )+}++/**+ * Each <li> given the marker its list shows, a bullet or its number, so a list+ * written in HTML keeps its items apart once the tags are gone.+ */+function withListMarkers(text: string): string {+ if (!/<li\b/i.test(text)) return text+ const lists: Array<{ ordered: boolean; count: number }> = []+ return text.replace(LIST_TAG, (tag: string, close: string, name: string) => {+ const kind = name.toLowerCase()+ if (kind !== 'li') {+ if (close) lists.pop()+ else lists.push({ ordered: kind === 'ol', count: 0 })+ return tag+ }+ if (close) return tag+ const list = lists[lists.length - 1]+ return `${tag}${list?.ordered ? `${++list.count}. ` : '\u2022 '}`+ })+}++/** An <img> tag as the markdown image it names, or nothing when it names no source. */+function imageMarkdown(tag: string): string {+ const src = IMG_SRC.exec(tag)?.[2].trim()+ return src ? `` : ''+}++function htmlSegmentToMarkdown(text: string): string {+ const html = withListMarkers(withoutScripts(withoutComments(text))).replace(LINE_BREAK, '\n')+ return separate(separate(html, BLOCK_EDGE, '\n'), CELL_EDGE, ' ')+ .replace(IMG_TAG, imageMarkdown)+ .replace(ANCHOR, (_m, href: string, label: string) => `[${label}](${href})`)+ .replace(BOLD_TAG, '**')+ .replace(ITALIC_TAG, '*')+ .replace(CODE_TAG, '`')+ .replace(STRIKE_TAG, '~~')+ .replace(HTML_TAG, '')+}++function htmlSegmentToPlainText(text: string): string {+ return decodeEntities(+ withoutScripts(withoutComments(text))+ .replace(LINE_BREAK, ' ')+ .replace(BLOCK_EDGE, ' ')+ .replace(CELL_EDGE, ' ')+ .replace(ANCHOR, (_m, _href: string, label: string) => label)+ .replace(BOLD_TAG, '')+ .replace(ITALIC_TAG, '')+ .replace(CODE_TAG, '')+ .replace(STRIKE_TAG, '')+ .replace(HTML_TAG, '')+ )+}++function mapOutsideCode(text: string, convert: (segment: string) => string): string {+ return text+ .split(/(`[^`\n]+`)/)+ .map((part, i) => (i % 2 === 1 ? part : convert(part)))+ .join('')+}++/**+ * Inline HTML as the markdown the span reader understands: <br> and block+ * edges become line breaks, <b>/<i>/<code>/<s>/<a>/<img> their markdown forms,+ * and other tags are dropped. Entities stay encoded until the spans are read,+ * so an encoded asterisk prints instead of starting emphasis. Code spans are+ * left as written.+ */+export function htmlToMarkdownInline(text: string): string {+ if (!text.includes('<')) return text+ return mapOutsideCode(text, htmlSegmentToMarkdown)+}++/** Inline HTML reduced to its text, for titles and other places that take no formatting. */+export function htmlToPlainText(text: string): string {+ const plain =+ text.includes('<') || text.includes('&') ? mapOutsideCode(text, htmlSegmentToPlainText) : text+ return plain.replace(/[ \t\r\n]+/g, ' ').trim()+}++/** Like htmlToPlainText, line by line: line breaks, <br> included, are kept. */+export function htmlToPlainLines(text: string): string {+ return text+ .replace(LINE_BREAK, '\n')+ .split('\n')+ .map(line => htmlToPlainText(line))+ .join('\n')+}++/** A heading's text without its optional closing run of hashes (`## Title ##`). */+export function withoutClosingHashes(text: string): string {+ const t = text.trimEnd()+ let end = t.length+ while (end > 0 && t[end - 1] === '#') end--+ if (end === t.length) return t+ if (end === 0) return ''+ return /\s/.test(t[end - 1]) ? t.slice(0, end).trimEnd() : t+}++/**+ * The paragraphs of a block quote, from its lines without their `>` marker. A+ * quoted line left empty ends a paragraph; the lines of one paragraph run on,+ * joined by a space. A quote with no text is one empty paragraph.+ */+export function quoteParagraphs(lines: string[]): string[] {+ const paragraphs: string[] = []+ let current: string[] = []+ for (const line of [...lines, '']) {+ if (line.trim()) {+ current.push(line)+ } else if (current.length > 0) {+ paragraphs.push(current.join(' '))+ current = []+ }+ }+ return paragraphs.length > 0 ? paragraphs : ['']+}++// No part may run into the next opening bracket or parenthesis: otherwise an+// unclosed image or link is rescanned to the end of the line from every+// opening, which takes minutes on a long line. As in CommonMark, a marker with+// a space on its inner side is not emphasis, so `5 * 3 * 2` keeps its+// asterisks, and no emphasis may span a marker of its own kind, which keeps+// every scan short.+const INLINE_TOKEN = new RegExp(+ [+ /!\[[^[\]\n]*\]\((?:[^()\n]|\([^()\n]*\))*\)/.source,+ /\[[^[\]\n]+\]\((?:https?:\/\/|mailto:)(?:[^\s()]|\([^\s()]*\))+\)/.source,+ /`[^`]+`/.source,+ ESCAPE.source,+ /(?<!\*)\*\*\*(?![\s*])[^*]*[^\s*\\]\*\*\*(?!\*)/.source,+ /\*\*(?![\s*])(?:[^*]|\*(?!\*))*?[^\s*\\]\*\*/.source,+ /(?<!\*)\*(?![\s*])[^*]*[^\s*\\]\*(?!\*)/.source,+ /~~(?![\s~])[^~\n]*[^\s~\\]~~/.source,+ ].join('|'),+ 'g'+)++function unescapeMarkdown(text: string): string {+ return text.replace(new RegExp(ESCAPE.source, 'g'), escaped => escaped.slice(1))+}++/**+ * The file named between the parentheses of ``: `<my chart.png>`,+ * or `chart.png`, either with an optional title after it. The rest is read+ * whole, so a name with spaces written without angle brackets still names its file.+ */+export function imageTarget(inside: string): string {+ const t = inside.trim()+ const angle = /^<([^<>\n]*)>/.exec(t)+ const titled = /^(.*?)\s+(?:"[^"\n]*"|'[^'\n]*'|\([^()\n]*\))$/.exec(t)+ return decodeEntities(unescapeMarkdown(angle ? angle[1] : titled ? titled[1] : t))+}++/** One stretch of inline text and the formatting it carries. */+export interface InlineSpan {+ text: string+ bold?: boolean+ italics?: boolean+ strike?: boolean+ code?: boolean+ /** Target of a link; the span's text is its label. */+ link?: string+ /** An image written inside the text: the span's text is its alt text. */+ image?: string+}++type SpanStyle = Pick<InlineSpan, 'bold' | 'italics' | 'strike'>++/** Whether `span` can take on the text of `next`: both plain, formatted alike. */+function joins(span: InlineSpan, next: InlineSpan): boolean {+ return (+ span.link === undefined &&+ next.link === undefined &&+ span.image === undefined &&+ next.image === undefined &&+ !span.code &&+ !next.code &&+ !!span.bold === !!next.bold &&+ !!span.italics === !!next.italics &&+ !!span.strike === !!next.strike+ )+}++function appendSpans(source: string, style: SpanStyle, out: InlineSpan[]): void {+ const pattern = new RegExp(INLINE_TOKEN)+ let at = 0+ const plain = (text: string) => {+ if (text) out.push({ ...style, text: decodeEntities(text) })+ }+ for (let m = pattern.exec(source); m; m = pattern.exec(source)) {+ plain(source.slice(at, m.index))+ const token = m[0]+ if (token.startsWith('+ out.push({+ ...style,+ text: decodeEntities(unescapeMarkdown(token.slice(2, split))),+ image: imageTarget(token.slice(split + 2, -1)),+ })+ } else if (token.startsWith('[')) {+ const split = token.indexOf('](')+ out.push({+ ...style,+ text: decodeEntities(unescapeMarkdown(token.slice(1, split))),+ link: decodeEntities(token.slice(split + 2, -1)),+ })+ } else if (token.startsWith('`')) {+ out.push({ ...style, text: token.slice(1, -1), code: true })+ } else if (token.startsWith('\\')) {+ out.push({ ...style, text: token.slice(1) })+ } else if (token.startsWith('***')) {+ appendSpans(token.slice(3, -3), { ...style, bold: true, italics: true }, out)+ } else if (token.startsWith('**')) {+ appendSpans(token.slice(2, -2), { ...style, bold: true }, out)+ } else if (token.startsWith('~~')) {+ appendSpans(token.slice(2, -2), { ...style, strike: true }, out)+ } else {+ appendSpans(token.slice(1, -1), { ...style, italics: true }, out)+ }+ at = pattern.lastIndex+ }+ plain(source.slice(at))+}++/**+ * The spans of one block of markdown already through htmlToMarkdownInline:+ * **bold**, *italic*, ***both***, ~~strike~~, `code`, [links](https://...),+ *  and backslash escapes.+ */+export function markdownSpans(markdown: string): InlineSpan[] {+ const spans: InlineSpan[] = []+ appendSpans(markdown, {}, spans)+ // An escape or an empty marker pair splits text that prints as one run.+ const joined: InlineSpan[] = []+ for (const span of spans) {+ const last = joined[joined.length - 1]+ if (last && joins(last, span)) last.text += span.text+ else joined.push(span)+ }+ return joined+}++/** The spans of one block of inline markdown that may carry HTML. */+export function inlineSpans(text: string): InlineSpan[] {+ return markdownSpans(htmlToMarkdownInline(text))+}diff --git a/mcp-host/src/workflow/schemaArguments.ts b/mcp-host/src/workflow/schemaArguments.tsnew file mode 100644index 000000000..ad455cc9e--- /dev/null+++ b/mcp-host/src/workflow/schemaArguments.ts@@ -0,0 +1,129 @@+/**+ * A generator's arguments read against its own schema: a null sent for an+ * optional argument counts as unset, and arguments the schema does not declare+ * are reported back to the model instead of being dropped silently.+ */++type SchemaNode = {+ type?: unknown+ properties?: Record<string, SchemaNode>+ required?: string[]+ items?: SchemaNode+ anyOf?: SchemaNode[]+ additionalProperties?: unknown+}++function isRecord(value: unknown): value is Record<string, unknown> {+ return value !== null && typeof value === 'object' && !Array.isArray(value)+}++function typesOf(node: SchemaNode | undefined): string[] {+ const t = node?.type+ return Array.isArray(t) ? t : typeof t === 'string' ? [t] : []+}++/** The node to follow for `value`: the node itself, or its anyOf branch of the value's type. */+function nodeFor(node: SchemaNode | undefined, value: unknown): SchemaNode | undefined {+ if (!node?.anyOf) return node+ const type = Array.isArray(value) ? 'array' : isRecord(value) ? 'object' : undefined+ return type ? node.anyOf.find(branch => typesOf(branch).includes(type)) : undefined+}++function allowsNull(node: SchemaNode | undefined): boolean {+ return typesOf(node).includes('null') || !!node?.anyOf?.some(b => typesOf(b).includes('null'))+}++/**+ * `value` without the null properties its schema neither requires nor allows.+ * Many models send null for every optional argument they leave unset, and the+ * runtimes already read null as absent.+ */+export function withoutUnsetNulls(schema: unknown, value: unknown, depth = 0): unknown {+ const node = nodeFor(schema as SchemaNode, value)+ if (!node || depth > 64) return value+ if (Array.isArray(value)) {+ return node.items ? value.map(item => withoutUnsetNulls(node.items, item, depth + 1)) : value+ }+ if (!isRecord(value) || !node.properties) return value+ const required = new Set(node.required ?? [])+ const out: Record<string, unknown> = {}+ for (const [key, item] of Object.entries(value)) {+ const child = node.properties[key]+ if (item === null && child && !required.has(key) && !allowsNull(child)) continue+ Object.defineProperty(out, key, {+ value: child ? withoutUnsetNulls(child, item, depth + 1) : item,+ enumerable: true,+ writable: true,+ configurable: true,+ })+ }+ return out+}++function readablePath(parts: Array<string | number>): string {+ return parts+ .map((part, i) => (typeof part === 'number' ? `[${part}]` : i === 0 ? part : `.${part}`))+ .join('')+}++interface UnknownArgument {+ path: string+ holder: Record<string, unknown>+ key: string+}++function unknownEntries(schema: unknown, value: unknown): UnknownArgument[] {+ const found: UnknownArgument[] = []+ const visit = (raw: SchemaNode | undefined, item: unknown, at: Array<string | number>) => {+ const node = nodeFor(raw, item)+ if (!node || at.length > 64) return+ if (Array.isArray(item)) {+ if (node.items) item.forEach((entry, i) => visit(node.items, entry, [...at, i]))+ return+ }+ if (!isRecord(item) || !node.properties || node.additionalProperties !== undefined) return+ for (const [key, entry] of Object.entries(item)) {+ const child = node.properties[key]+ if (child) visit(child, entry, [...at, key])+ else found.push({ path: readablePath([...at, key]), holder: item, key })+ }+ }+ visit(schema as SchemaNode, value, [])+ return found+}++/**+ * Arguments the schema does not declare. An extra key is not a validation+ * error (additionalProperties is not a field every provider accepts), so these+ * are reported back instead. Objects that declare additionalProperties are+ * open maps and are not checked.+ */+export function unknownArguments(schema: unknown, value: unknown): string[] {+ return unknownEntries(schema, value).map(entry => entry.path)+}++/**+ * The undeclared arguments of `value`, each made a getter that records whether+ * it was read, so that after a generator ran `ignored()` names only the ones it+ * never looked at. A generator reads some arguments under names the schema+ * leaves out; those are not ignored. `value` must be the caller's own copy.+ */+export function watchUnknownArguments(schema: unknown, value: unknown): { ignored(): string[] } {+ const entries = unknownEntries(schema, value)+ const read = new Set<number>()+ entries.forEach(({ holder, key }, i) => {+ let current = holder[key]+ Object.defineProperty(holder, key, {+ get() {+ read.add(i)+ return current+ },+ set(next: unknown) {+ current = next+ },+ enumerable: true,+ configurable: true,+ })+ })+ return { ignored: () => entries.filter((_, i) => !read.has(i)).map(entry => entry.path) }+}diff --git a/mcp-host/src/workflow/tableRows.ts b/mcp-host/src/workflow/tableRows.tsnew file mode 100644index 000000000..8e110d1f3--- /dev/null+++ b/mcp-host/src/workflow/tableRows.ts@@ -0,0 +1,78 @@+/**+ * Table rows in the shapes models send them, including `{Header: value}`+ * records, as arrays of cells in header order.+ */++function isRecord(value: unknown): value is Record<string, unknown> {+ return value !== null && typeof value === 'object' && !Array.isArray(value)+}++/** Header text as it is displayed: a year sent as 2026 is still a header. */+export function headerText(header: unknown): string {+ return header === null || header === undefined ? '' : String(header)+}++/**+ * `rows` as arrays of cells. A record is read by header name, exactly or+ * ignoring case and surrounding space; without headers its values are taken in+ * key order. Anything else is dropped. Each kind of repair is reported once in+ * `warnings`, prefixed with `label`.+ */+export function normalizeTableRows(+ rows: unknown,+ headers: unknown[] | undefined,+ label: string,+ warnings: string[]+): unknown[][] {+ if (rows === undefined || rows === null) return []+ if (!Array.isArray(rows)) {+ warnings.push(`${label}: rows must be an array of rows; they were left out.`)+ return []+ }+ const names = (headers ?? []).map(h => headerText(h).trim().toLowerCase())+ let fromRecords = 0+ let dropped = 0+ const unmatched = new Set<string>()+ const out: unknown[][] = []+ for (const row of rows) {+ if (Array.isArray(row)) {+ out.push(row)+ } else if (isRecord(row)) {+ fromRecords+++ if (names.length === 0) {+ out.push(Object.values(row))+ continue+ }+ const byName = new Map(Object.entries(row).map(([k, v]) => [k.trim().toLowerCase(), v]))+ for (const key of Object.keys(row)) {+ if (!names.includes(key.trim().toLowerCase())) unmatched.add(key)+ }+ out.push(+ (headers ?? []).map((h, i) =>+ Object.prototype.hasOwnProperty.call(row, headerText(h))+ ? row[headerText(h)]+ : byName.get(names[i])+ )+ )+ } else {+ dropped+++ }+ }+ if (fromRecords > 0) {+ warnings.push(+ `${label}: ${fromRecords} row(s) were objects and were read by header name; send each row as an array of cells in header order.`+ )+ }+ if (unmatched.size > 0) {+ warnings.push(+ `${label}: the key(s) ${[...unmatched].map(k => `'${k}'`).join(', ')} match no header, so ` ++ 'those values were left out.'+ )+ }+ if (dropped > 0) {+ warnings.push(+ `${label}: ${dropped} row(s) were neither an array nor an object and were left out.`+ )+ }+ return out+}diff --git a/mcp-host/src/workflow/toolText.ts b/mcp-host/src/workflow/toolText.tsnew file mode 100644index 000000000..b1e243e21--- /dev/null+++ b/mcp-host/src/workflow/toolText.ts@@ -0,0 +1,62 @@+/**+ * Text cleanup applied to the arguments of every document generator.+ *+ * DOCX, XLSX and PPTX are XML, and XML 1.0 forbids most C0 control characters,+ * so one ANSI escape makes Word refuse a DOCX; the PDF renderer draws them as+ * boxes, and the markdown parsers split on '\n' only. Cleaning the arguments+ * once, before a generator reads them, covers every string that can reach a file.+ */++/** CSI and terminated OSC sequences, then any other escape and its next byte. */+const ANSI_ESCAPE =+ /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b[@-_]?/g++/** Characters XML 1.0 cannot carry, plus DEL. Tab and newline are kept. */+const UNREPRESENTABLE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F\uFFFE\uFFFF]/g++/** Half of a surrogate pair, left behind when a string is cut mid-emoji. */+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g++export function cleanText(text: string): string {+ return text+ .replace(/\r\n?|[\f\v\u2028\u2029]/g, '\n')+ .replace(ANSI_ESCAPE, '')+ .replace(UNREPRESENTABLE, '')+ .replace(LONE_SURROGATE, '')+}++function isPlainObject(value: unknown): value is Record<string, unknown> {+ if (value === null || typeof value !== 'object') return false+ const proto = Object.getPrototypeOf(value)+ return proto === Object.prototype || proto === null+}++const MAX_DEPTH = 64++/**+ * A copy of `value` with every string, object key included, run through+ * cleanText. A key that only matches another after cleaning is dropped: the+ * arguments were validated before cleaning, so the key already clean is the one+ * the schema checked. Values nested past MAX_DEPTH levels are kept as they are:+ * no generator reads that deep, and walking them could overflow the stack.+ */+export function cleanToolArgs<T>(value: T, depth = 0): T {+ if (depth > MAX_DEPTH) return value+ if (typeof value === 'string') return cleanText(value) as T+ if (Array.isArray(value)) return value.map(item => cleanToolArgs(item, depth + 1)) as T+ if (!isPlainObject(value)) return value+ const out: Record<string, unknown> = {}+ for (const [key, item] of Object.entries(value)) {+ const clean = cleanText(key)+ if (Object.prototype.hasOwnProperty.call(out, clean)) continue+ if (clean !== key && Object.prototype.hasOwnProperty.call(value, clean)) continue+ // defineProperty keeps a key such as "__proto__" an ordinary own property.+ Object.defineProperty(out, clean, {+ value: cleanToolArgs(item, depth + 1),+ enumerable: true,+ writable: true,+ configurable: true,+ })+ }+ return out as T+}