Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs(mcp-host): correct comments that misstate what the generators do

marcoteb38d2878201c7
diff --git a/mcp-host/src/workflow/__tests__/internalTools.charts.rendering.test.ts b/mcp-host/src/workflow/__tests__/internalTools.charts.rendering.test.ts
index e320d94af..b9803ea9e 100644
--- a/mcp-host/src/workflow/__tests__/internalTools.charts.rendering.test.ts
+++ b/mcp-host/src/workflow/__tests__/internalTools.charts.rendering.test.ts
@@ -135,7 +135,7 @@ const BAR_ARGS = {
}
describe('chart text actually renders', () => {
- it('draws the title, which an image with no fonts silently omitted', async () => {
+ it('draws the title on an image with no system fonts', async () => {
const tool = findTool('clerum__generate_chart')
// Two titles of different length over an identical plot: the longer one
@@ -346,7 +346,7 @@ describe('legend of a single series', () => {
})
})
-describe('legibility regressions found in QA', () => {
+describe('legibility of small values and lone bars', () => {
it('keeps small magnitudes from collapsing to zero', async () => {
const tool = findTool('clerum__generate_chart')
const r = await tool.execute(
diff --git a/mcp-host/src/workflow/__tests__/pdfText.test.ts b/mcp-host/src/workflow/__tests__/pdfText.test.ts
index 3d9aacc00..9af809b0e 100644
--- a/mcp-host/src/workflow/__tests__/pdfText.test.ts
+++ b/mcp-host/src/workflow/__tests__/pdfText.test.ts
@@ -133,7 +133,8 @@ describe('right-to-left text', () => {
})
it('breaks a long paragraph into lines itself so each line reads in order', () => {
- // Ten 4-letter words at 5pt a letter: 20pt each plus spaces, about 4 a line in 100pt.
+ // Ten 4-letter words at 5pt a letter: 20pt each plus a 5pt space, 3 a line in
+ // the 94pt a 100pt line fills.
const words = Array.from({ length: 10 }, (_, i) => String.fromCodePoint(0x5d0 + i).repeat(4))
const { node } = typeset({ text: words.join(' ') }, { ...ctx, width: 100 })
const lines = runs(node)
diff --git a/mcp-host/src/workflow/chartData.ts b/mcp-host/src/workflow/chartData.ts
index cf194be43..c94de9b6d 100644
--- a/mcp-host/src/workflow/chartData.ts
+++ b/mcp-host/src/workflow/chartData.ts
@@ -76,7 +76,7 @@ function readNumeral(text: string): Readings | undefined {
return out.dot === undefined && out.comma === undefined ? undefined : out
}
-/** Scale words, only directly after the number. A lowercase "m" is refused. */
+/** Scale words, directly after the number or after one space. A lowercase "m" is refused. */
const SCALES: Record<string, number> = {
k: 3,
K: 3,
diff --git a/mcp-host/src/workflow/chartPlugins.ts b/mcp-host/src/workflow/chartPlugins.ts
index e8e81860a..4def8375f 100644
--- a/mcp-host/src/workflow/chartPlugins.ts
+++ b/mcp-host/src/workflow/chartPlugins.ts
@@ -174,7 +174,6 @@ function radialTickColumn(chart: Chart): Box | undefined {
}
}
-/** The legend and title boxes, which value labels must not print over. */
/** The rectangle of every drawn bar, with the element it belongs to. */
function barBoxes(chart: Chart, horizontal: boolean): Array<Box & { element: unknown }> {
const out: Array<Box & { element: unknown }> = []
@@ -214,6 +213,7 @@ function barBoxes(chart: Chart, horizontal: boolean): Array<Box & { element: unk
return out
}
+/** The legend and title boxes, which value labels must not print over. */
function reservedBoxes(chart: Chart): Box[] {
const blocks = [
(chart as { legend?: Partial<Box> }).legend,
@@ -533,10 +533,7 @@ export function gaugeCenterPlugin(o: GaugeCenterOptions): Plugin {
}
}
-/**
- * Paint the theme background behind the plot. Kept here so every chart shares
- * one implementation rather than rebuilding the plugin per render.
- */
+/** Paint the theme background behind the plot. */
export function backgroundPlugin(color: string): Plugin {
return {
id: 'clerumBackground',
diff --git a/mcp-host/src/workflow/dashboardCharts.ts b/mcp-host/src/workflow/dashboardCharts.ts
index cc51e1192..4d55ea550 100644
--- a/mcp-host/src/workflow/dashboardCharts.ts
+++ b/mcp-host/src/workflow/dashboardCharts.ts
@@ -59,7 +59,8 @@ const PALETTE_SIZE = 7
/**
* The palette token for series or slice `i`. Past the palette the colors
- * repeat fainter each round, with `dash` for lines, so no two series look alike.
+ * repeat fainter each round, with a dash for lines, so the first 21 series look
+ * different; later ones repeat.
*/
function paletteColor(i: number, alpha = 1): { color: string; dash?: number[] } {
const round = Math.floor(i / PALETTE_SIZE)
diff --git a/mcp-host/src/workflow/dashboardScript.ts b/mcp-host/src/workflow/dashboardScript.ts
index 549b2f0f2..27aa17a6a 100644
--- a/mcp-host/src/workflow/dashboardScript.ts
+++ b/mcp-host/src/workflow/dashboardScript.ts
@@ -1,8 +1,9 @@
/**
* The script that draws a dashboard's charts in the browser.
*
- * Each chart and each sparkline is drawn on its own, so one that Chart.js
- * refuses shows why in its card and never blanks the others. Colors are read
+ * Each chart and each sparkline is drawn on its own: a chart Chart.js refuses
+ * shows why in its card, a sparkline it refuses is removed, and neither blanks
+ * the others. Colors are read
* from the page's CSS variables and read again when the color scheme or the
* print media changes, so the series stay legible in light, dark and print.
* Animation is off: headless HTML-to-PDF converters print a chart the moment it
diff --git a/mcp-host/src/workflow/docxMarkdown.ts b/mcp-host/src/workflow/docxMarkdown.ts
index c976c57ed..68ef35f9e 100644
--- a/mcp-host/src/workflow/docxMarkdown.ts
+++ b/mcp-host/src/workflow/docxMarkdown.ts
@@ -87,8 +87,8 @@ interface ListFrame {
* Consume one list, nested items included, starting at `start`. Depth follows
* the stack of indents seen so far, as the PDF generator does, so a 4-space
* sub-item is one level down rather than two. Blank lines between items keep a
- * loose list together; a different marker, or a count that starts over at 1,
- * begins a new list.
+ * loose list together; a switch between bullets and numbers, or a count that
+ * starts over at 1, begins a new list.
*/
function parseList(lines: string[], start: number, ctx: DocxBodyContext, out: Paragraph[]): number {
const base = indentOf(lines[start])
diff --git a/mcp-host/src/workflow/docxTable.ts b/mcp-host/src/workflow/docxTable.ts
index 8821bf6f7..28abc8783 100644
--- a/mcp-host/src/workflow/docxTable.ts
+++ b/mcp-host/src/workflow/docxTable.ts
@@ -61,9 +61,9 @@ let context: SKRSContext2D | undefined
const advances = [new Map<string, number>(), new Map<string, number>()]
/**
- * Advance of one character at 1pt in ems. The few thousand characters Roboto
- * covers are measured once each with it; Roboto runs 8-10% wider than Calibri
- * in both weights, so a sum of advances errs toward fitting.
+ * Advance of one character at 1pt in ems. Characters in MEASURED_CHAR are
+ * measured once each in Roboto, which runs about 7-10% wider than Calibri
+ * (Medium against Bold included), so a sum of advances errs toward fitting.
*/
function advanceEm(ch: string, bold: boolean): number {
if (!MEASURED_CHAR.test(ch)) return WIDE_CHAR.test(ch) ? 1 : 0.6
diff --git a/mcp-host/src/workflow/fonts.ts b/mcp-host/src/workflow/fonts.ts
index e5f7f7918..a4088f1f8 100644
--- a/mcp-host/src/workflow/fonts.ts
+++ b/mcp-host/src/workflow/fonts.ts
@@ -125,8 +125,8 @@ export function ensureFontsReady(): void {
* 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.
+ * DejaVu and Noto carry the arrows and check marks Roboto lacks; anything
+ * the body face 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
@@ -218,8 +218,9 @@ function facesForPrefix(prefix: string): PdfFaces | undefined {
}
/**
- * Characters Roboto cannot draw. A face is only worth preferring over the
- * bundled one if it covers some of these.
+ * Probes for a broad face: an arrow, a check mark and a Han character, which
+ * Roboto lacks, and ≥, α and я, which a broad face also draws. A face scores
+ * by how many it can draw.
*/
const COVERAGE_PROBES = ['\u2192', '\u2713', '\u4E2D', '\u2265', '\u03B1', '\u044F']
@@ -615,8 +616,8 @@ function resolvePdfFaces(): PdfFaces {
}
}
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.
+ // Registering the chosen family under the PDF alias lets text be measured
+ // in the face the PDF will embed.
const file = Array.isArray(chosen.normal) ? chosen.normal[0] : chosen.normal
try {
if (typeof file === 'string') GlobalFonts.registerFromPath(file, PDF_FONT_FAMILY)
@@ -683,8 +684,8 @@ export function pdfFontDescriptors(): Record<string, PdfFaces> {
}
// 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.
+// lacks is drawn by giving its run another family. Arabic and Hebrew come from
+// here unless the body face draws them.
/**
* Faces tried, in order, for a character the run's own face lacks. The script
@@ -1007,9 +1008,9 @@ export function canRender(ch: string): boolean {
}
/**
- * 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.
+ * ASCII stand-ins for symbols models reach for constantly. Charts apply them
+ * only when the character cannot be drawn; PDFs always apply them to emoji,
+ * which no embedded face draws in color.
*/
const SUBSTITUTIONS: Record<string, string> = {
'\u2192': '->',
diff --git a/mcp-host/src/workflow/internalTools.ts b/mcp-host/src/workflow/internalTools.ts
index ec378f42f..cffa56062 100644
--- a/mcp-host/src/workflow/internalTools.ts
+++ b/mcp-host/src/workflow/internalTools.ts
@@ -395,18 +395,6 @@ interface ChartDataset {
fill?: boolean
}
-/**
- * Apply theme colors to datasets that don't specify their own. Each dataset gets
- * a different color from the palette by index. For pie/doughnut/polarArea where
- * each slice is a separate color, every slice gets its own color: a caller's
- * short list is completed from the theme, and slices past the palette get
- * shades of it.
- *
- * Palettes have 7 colors. With more than 7 datasets the palette wraps via
- * `idx % palette.length` — adjacent series can end up sharing a color. To
- * differentiate >7 series, callers should supply explicit `borderColor` /
- * `backgroundColor` per dataset instead of relying on the palette.
- */
/**
* A mark that reaches the end of the plot has nowhere to put its value label
* and reads as clipped, so a value axis runs 4% of its range past the data on
@@ -510,6 +498,17 @@ function pointRadius(full: number, crowd: number, points: number): number {
return points <= crowd ? full : Math.max(1.5, full * Math.sqrt(crowd / points))
}
+/**
+ * Apply theme colors to datasets that don't specify their own. Each dataset gets
+ * a different color from the palette by index. For pie/doughnut/polarArea where
+ * each slice is a separate color, every slice gets its own color: a caller's
+ * short list is completed from the theme, and slices past the palette get
+ * shades of it.
+ *
+ * Palettes have 7 colors; with more datasets the palette wraps via
+ * `idx % palette.length`, so series i and i+7 share a color. Callers who need
+ * more distinct series pass `borderColor` / `backgroundColor` per dataset.
+ */
function applyThemePalette(
datasets: ChartDataset[],
theme: ChartTheme,
@@ -561,8 +560,8 @@ function applyThemePalette(
if (chartType === 'scatter') {
if (point.pointRadius === undefined) point.pointRadius = pointRadius(6, 100, points)
} else if (chartType === 'line' || chartType === 'area' || chartType === 'stackedArea') {
- // A series with gaps draws no segments at all, leaving its points as
- // the only mark on the canvas.
+ // A value with a gap on both sides gets no segment, so its point is
+ // its only mark.
if (point.pointRadius === undefined) point.pointRadius = pointRadius(4, 60, points)
if (point.pointBackgroundColor === undefined) point.pointBackgroundColor = color
}
@@ -696,8 +695,8 @@ function resolveChartType(
rotation: -90,
circumference: 180,
cutout: '70%',
- // A half circle is sized against the full circle's box, so without the
- // bottom padding the dial is drawn past the lower edge of the canvas.
+ // The bottom padding leaves room under the dial's flat edge for the
+ // "/ max" line the readout prints below it.
radius: '88%',
layout: { padding: { top: 12, right: 16, bottom: 90, left: 16 } },
plugins: { legend: { display: false } },
@@ -1272,7 +1271,7 @@ const MAX_LAYOUT_SIDE = 1600
const MAX_CANVAS_PIXELS = 13_107_200
/**
- * Pixel ratio for a chart of the given layout size. A large chart is drawn at a
+ * Pixel ratio for a chart of the requested size. A large chart is drawn at a
* lower density rather than refused, down to 1; undefined when even that would
* exceed MAX_CANVAS_PIXELS.
*/
@@ -1524,7 +1523,10 @@ function crc32(buf: Buffer): number {
/** A4 width (595pt) less the 40pt side margins the documents use. */
const PDF_CONTENT_WIDTH = PORTRAIT.width
-/** Printable width of a default Word page, in pixels at 96dpi. */
+/**
+ * Widest a DOCX image is drawn, in pixels at 96 dpi; the page leaves about 601
+ * between its margins.
+ */
const DOCX_MAX_IMAGE_WIDTH = 560
const DOCX_MAX_IMAGE_HEIGHT = 380
@@ -1890,7 +1892,7 @@ function buildList(
continue
}
const isOrdered = ORDERED_RE.test(lines[i].trimStart())
- // A different marker at the same indent starts a different list.
+ // Switching between bullets and numbers at the same indent starts a different list.
if (isOrdered !== ordered) break
items.push(parseInlineMarkdown(stripListMarker(lines[i]), onImage))
i++
@@ -2263,10 +2265,6 @@ function applyPageOrientation(
return initial
}
-/**
- * The footer text as the lines it will take, cut to what the bottom margin
- * can hold, with a note when anything is cut.
- */
/** More characters than a header or footer line ever holds at the running size. */
const RUNNING_LINE_CHARS = 400
@@ -2282,6 +2280,10 @@ function longestFitting(chars: string[], fits: (text: string) => boolean): numbe
return lo
}
+/**
+ * The footer text as the lines it will take, cut to what the bottom margin
+ * can hold, with a note when anything is cut.
+ */
function footerLines(
text: string,
width: number,
diff --git a/mcp-host/src/workflow/pdfText.ts b/mcp-host/src/workflow/pdfText.ts
index 7160a1e20..20fd575be 100644
--- a/mcp-host/src/workflow/pdfText.ts
+++ b/mcp-host/src/workflow/pdfText.ts
@@ -37,7 +37,10 @@ interface Glyph {
cp: number
}
-/** Dropped because they carry nothing to draw. Joiners are kept: Arabic shaping reads them. */
+/**
+ * Dropped because they carry nothing to draw. A joiner after a right-to-left
+ * letter is kept, since Arabic shaping reads it; other joiners are dropped.
+ */
const INVISIBLE = /^[\u200B\u200E\u200F\u2060\uFE00-\uFE0F\uFEFF]$/u
const JOINER = /^[\u200C\u200D]$/u
const EMOJI = /^\p{Emoji_Presentation}$/u
diff --git a/mcp-host/src/workflow/pptxDeck.ts b/mcp-host/src/workflow/pptxDeck.ts
index 61faea308..99a192b34 100644
--- a/mcp-host/src/workflow/pptxDeck.ts
+++ b/mcp-host/src/workflow/pptxDeck.ts
@@ -109,7 +109,7 @@ export const PPTX_PALETTES: Record<string, PptxPalette> = {
},
}
-/** Series colors after the palette's own, so a chart of many slices does not repeat one. */
+/** Series colors after the palette's own, so a chart of up to ten slices does not repeat one. */
const EXTRA_SERIES_COLORS = ['#7c3aed', '#0d9488', '#ea580c', '#db2777']
export const PPTX_ASPECT_RATIOS: Record<string, { name: string; width: number; height: number }> = {
diff --git a/mcp-host/src/workflow/pptxInput.ts b/mcp-host/src/workflow/pptxInput.ts
index 8affa9f3f..b2f4c3fb4 100644
--- a/mcp-host/src/workflow/pptxInput.ts
+++ b/mcp-host/src/workflow/pptxInput.ts
@@ -4,8 +4,8 @@
* Everything the renderer draws passes through here first, so a malformed
* argument becomes a message naming the field and the fix rather than a
* JavaScript TypeError, a slide with an error printed on it, or an empty slide
- * reported as success. Repairs that keep the content (rows sent as records,
- * text over its length limit) are made here and reported as warnings.
+ * reported as success. Repairs (rows sent as records read by header, text
+ * shortened to its length limit) are made here and reported as warnings.
*/
import { type EmbeddableImage, loadEmbeddableImage } from './embeddedImages'
import { ChartSpecError, type NativeChart, readNativeChart } from './pptxCharts'