Skip to content

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

TypeScript

refactor(mcp-host): make a slide's layout and content one type

marcoteb149e8b252c1f
diff --git a/mcp-host/src/workflow/__tests__/pptxSlideTypes.test.ts b/mcp-host/src/workflow/__tests__/pptxSlideTypes.test.ts
new file mode 100644
index 000000000..d7d27b609
--- /dev/null
+++ b/mcp-host/src/workflow/__tests__/pptxSlideTypes.test.ts
@@ -0,0 +1,47 @@
+// A slide's layout and its content travel together in the types: a slide or a
+// plan that lacks what its layout draws does not compile. The checks here run
+// in `tsc --noEmit`, which CI runs over the tests; each @ts-expect-error fails
+// the typecheck if the state it marks becomes expressible again.
+import { describe, expect, it } from 'vitest'
+import type { PptxSlide, PptxTable } from '../pptxInput'
+import { type PlannedSlide, isPlanOf } from '../pptxLayout'
+
+const table: PptxTable = { headers: ['a'], rows: [['1']] }
+const body = { x: 0, y: 0, w: 1, h: 1 }
+
+describe('slide types', () => {
+ it('admit only slides that carry what their layout draws', () => {
+ const slides: PptxSlide[] = [
+ { layout: 'title-table', where: 'slides[0]', table },
+ {
+ layout: 'kpis',
+ where: 'slides[1]',
+ kpis: [{ where: 'k', value: '1' }],
+ kpiStyle: 'people',
+ },
+ { layout: 'cover', where: 'slides[2]', title: 'T' },
+ // An image that could not be embedded leaves the slide with its title.
+ { layout: 'image', where: 'slides[3]', title: 'T' },
+ ]
+ // @ts-expect-error a table slide with no table
+ const noTable: PptxSlide = { layout: 'title-table', where: 'slides[0]' }
+ // @ts-expect-error a bullets slide with a table instead of bullets
+ const wrongContent: PptxSlide = { layout: 'title-bullets', where: 'slides[0]', table }
+ // @ts-expect-error people cards on a slide that has no cards
+ const strayStyle: PptxSlide = { layout: 'title-table', where: 's', table, kpiStyle: 'people' }
+ expect([noTable, wrongContent, strayStyle]).toHaveLength(3)
+ expect(slides.map(s => s.layout)).toEqual(['title-table', 'kpis', 'cover', 'image'])
+ })
+
+ it('admit only plans that carry the part of their slide they draw', () => {
+ const spec = { layout: 'title-table' as const, where: 'slides[0]', table }
+ const layout = { pages: [], columnWidths: [], fontSize: 12 } as never
+ const plan: PlannedSlide = { spec, body, table: { layout, page: 0 } }
+ // @ts-expect-error a table plan with no page of the table
+ const noPage: PlannedSlide = { spec, body }
+ const cover: PlannedSlide = { spec: { layout: 'cover', where: 's', title: 'T' }, body }
+ expect(isPlanOf(plan, 'title-table') && plan.table.page).toBe(0)
+ expect(isPlanOf(cover, 'cover')).toBe(true)
+ expect(isPlanOf(noPage, 'kpis')).toBe(false)
+ })
+})
diff --git a/mcp-host/src/workflow/pptxInput.ts b/mcp-host/src/workflow/pptxInput.ts
index 11d35a20e..398ba38ec 100644
--- a/mcp-host/src/workflow/pptxInput.ts
+++ b/mcp-host/src/workflow/pptxInput.ts
@@ -80,28 +80,45 @@ export interface PptxColumn {
picture?: PptxPicture
}
-export interface PptxSlide {
- layout: SlideLayout
+/** What a slide of any layout may carry besides its content. */
+interface SlideCommon {
/** Where the slide came from, as the model wrote it: "slides[2]", or "data" for a template. */
where: string
title?: string
eyebrow?: string
subtitle?: string
status?: Status
- bullets?: string[]
- table?: PptxTable
- kpis?: PptxKpi[]
- /** People cards: the name large, the role under it. */
- kpiStyle?: 'people'
- chart?: PptxChart
- picture?: PptxPicture
- quote?: { text: string; attribution?: string }
- columns?: { left: PptxColumn; right: PptxColumn }
notes?: string
/** Argument paths of fields that did not come from `${where}.<field>`, for messages. */
paths?: Record<string, string>
}
+/** A slide: its layout and the content that layout draws, which it always has. */
+export type PptxSlide = SlideCommon &
+ (
+ | { layout: 'cover' }
+ | { layout: 'section' }
+ | { layout: 'title-bullets'; bullets: string[] }
+ | { layout: 'title-chart'; chart: PptxChart }
+ | { layout: 'title-table'; table: PptxTable }
+ | {
+ layout: 'kpis'
+ kpis: PptxKpi[]
+ /** People cards: the name large, the role under it. */
+ kpiStyle?: 'people'
+ }
+ | { layout: 'two-column'; columns: { left: PptxColumn; right: PptxColumn } }
+ | {
+ layout: 'image'
+ /** Absent when the image could not be embedded: the slide shows its title, and a warning says why. */
+ picture?: PptxPicture
+ }
+ | { layout: 'quote'; quote: { text: string; attribution?: string } }
+ )
+
+/** The slide of `layout`. */
+export type SlideOf<L extends SlideLayout> = Extract<PptxSlide, { layout: L }>
+
/** Argument path of one of a slide's fields, as messages name it. */
export function fieldPath(slide: PptxSlide, field: string): string {
return slide.paths?.[field] ?? `${slide.where}.${field}`
@@ -490,60 +507,68 @@ function readSlide(raw: unknown, index: number, ctx: ReadContext): PptxSlide {
)
}
const layout = raw.layout as SlideLayout
- const slide: PptxSlide = {
- layout,
+ const common: SlideCommon = {
where,
title: readText(raw.title, `${where}.title`, TEXT_LIMITS.title, ctx),
notes: readText(raw.notes, `${where}.notes`, TEXT_LIMITS.notes, ctx),
}
const used = LAYOUT_FIELDS[layout]
if (used.includes('eyebrow')) {
- slide.eyebrow = readText(raw.eyebrow, `${where}.eyebrow`, TEXT_LIMITS.eyebrow, ctx)
+ common.eyebrow = readText(raw.eyebrow, `${where}.eyebrow`, TEXT_LIMITS.eyebrow, ctx)
}
if (used.includes('subtitle')) {
- slide.subtitle = readText(raw.subtitle, `${where}.subtitle`, TEXT_LIMITS.subtitle, ctx)
+ common.subtitle = readText(raw.subtitle, `${where}.subtitle`, TEXT_LIMITS.subtitle, ctx)
}
- if (used.includes('status')) slide.status = readEnum(raw.status, `${where}.status`, STATUSES)
+ if (used.includes('status')) common.status = readEnum(raw.status, `${where}.status`, STATUSES)
+ let slide: PptxSlide
switch (layout) {
case 'cover':
case 'section':
- if (!slide.title) missing(where, layout, 'title', '"..."')
+ if (!common.title) missing(where, layout, 'title', '"..."')
+ slide = { ...common, layout }
break
- case 'title-bullets':
- slide.bullets = readStringList(raw.bullets, `${where}.bullets`, TEXT_LIMITS.bullet, ctx)
- if (!slide.bullets?.length) missing(where, layout, 'bullets', '["...", "..."]')
+ case 'title-bullets': {
+ const bullets = readStringList(raw.bullets, `${where}.bullets`, TEXT_LIMITS.bullet, ctx)
+ if (!bullets?.length) missing(where, layout, 'bullets', '["...", "..."]')
+ slide = { ...common, layout, bullets }
break
+ }
case 'title-chart':
if (raw.chart === undefined) missing(where, layout, 'chart', '{"path": "sales.png"}')
- slide.chart = readChart(raw.chart, `${where}.chart`, ctx)
+ slide = { ...common, layout, chart: readChart(raw.chart, `${where}.chart`, ctx) }
break
case 'title-table':
if (raw.table === undefined)
missing(where, layout, 'table', '{"headers": [...], "rows": [[...]]}')
- slide.table = readTable(raw.table, `${where}.table`, ctx)
+ slide = { ...common, layout, table: readTable(raw.table, `${where}.table`, ctx) }
break
- case 'kpis':
+ case 'kpis': {
if (raw.kpis === undefined)
missing(where, layout, 'kpis', '[{"label": "...", "value": "..."}]')
- slide.kpis = readKpis(raw.kpis, `${where}.kpis`, ctx)
- if (slide.kpis.length === 0)
- missing(where, layout, 'kpis', '[{"label": "...", "value": "..."}]')
+ const kpis = readKpis(raw.kpis, `${where}.kpis`, ctx)
+ if (kpis.length === 0) missing(where, layout, 'kpis', '[{"label": "...", "value": "..."}]')
+ slide = { ...common, layout, kpis }
break
+ }
case 'two-column': {
const cols = raw.columns
if (!isRecord(cols) || cols.left === undefined || cols.right === undefined) {
missing(where, layout, 'columns', '{"left": {...}, "right": {...}}')
}
- slide.columns = {
- left: readColumn(cols.left, `${where}.columns.left`, ctx),
- right: readColumn(cols.right, `${where}.columns.right`, ctx),
+ slide = {
+ ...common,
+ layout,
+ columns: {
+ left: readColumn(cols.left, `${where}.columns.left`, ctx),
+ right: readColumn(cols.right, `${where}.columns.right`, ctx),
+ },
}
break
}
case 'image':
if (raw.image === undefined) missing(where, layout, 'image', '{"path": "photo.png"}')
- slide.picture = readPicture(raw.image, `${where}.image`, ctx)
+ slide = { ...common, layout, picture: readPicture(raw.image, `${where}.image`, ctx) }
break
case 'quote': {
const q = typeof raw.quote === 'string' ? { text: raw.quote } : raw.quote
@@ -551,14 +576,18 @@ function readSlide(raw: unknown, index: number, ctx: ReadContext): PptxSlide {
? readText(q.text, `${where}.quote.text`, TEXT_LIMITS.quote, ctx)
: undefined
if (!isRecord(q) || !text) missing(where, layout, 'quote', '{"text": "..."}')
- slide.quote = {
- text,
- attribution: readText(
- q.attribution,
- `${where}.quote.attribution`,
- TEXT_LIMITS.attribution,
- ctx
- ),
+ slide = {
+ ...common,
+ layout,
+ quote: {
+ text,
+ attribution: readText(
+ q.attribution,
+ `${where}.quote.attribution`,
+ TEXT_LIMITS.attribution,
+ ctx
+ ),
+ },
}
break
}
diff --git a/mcp-host/src/workflow/pptxKpiCards.ts b/mcp-host/src/workflow/pptxKpiCards.ts
index 8fa787ebf..8c1a588c5 100644
--- a/mcp-host/src/workflow/pptxKpiCards.ts
+++ b/mcp-host/src/workflow/pptxKpiCards.ts
@@ -1,7 +1,7 @@
/** KPI and people cards. */
import { type DrawContext, fitOrShorten, hex } from './pptxDraw'
import { type PptxKpi } from './pptxInput'
-import { type Box, type PlannedSlide } from './pptxLayout'
+import { type Box, type PlanOf } from './pptxLayout'
import { type Slide, addText } from './pptxRuns'
import { TEXT_INSET_X, TEXT_INSET_Y, fitText, lineHeightIn, textWidth } from './pptxText'
@@ -189,8 +189,8 @@ function drawCard(
}
}
-export function drawKpis(slide: Slide, planned: PlannedSlide, ctx: DrawContext): void {
- const cards = planned.kpis!
+export function drawKpis(slide: Slide, planned: PlanOf<'kpis'>, ctx: DrawContext): void {
+ const cards = planned.kpis
const body = planned.body
// One row up to four cards, then two rows with the longer one first:
// five cards are three and two, not four and one.
diff --git a/mcp-host/src/workflow/pptxLayout.ts b/mcp-host/src/workflow/pptxLayout.ts
index f30f4b9d3..2e1e485f1 100644
--- a/mcp-host/src/workflow/pptxLayout.ts
+++ b/mcp-host/src/workflow/pptxLayout.ts
@@ -1,5 +1,11 @@
/** Slide planning: frames, title blocks and how lists and tables split across slides. */
-import { type PptxKpi, type PptxSlide, fieldPath } from './pptxInput'
+import {
+ type PptxKpi,
+ type PptxSlide,
+ type SlideLayout,
+ type SlideOf,
+ fieldPath,
+} from './pptxInput'
import { type TableLayout, layoutTable } from './pptxTables'
import {
TEXT_INSET_X,
@@ -80,13 +86,37 @@ function bodyBox(frame: Frame, title: TitleBlock | undefined): Box {
}
/** One slide as it will be drawn, after lists and tables are split into pages. */
-export interface PlannedSlide {
- spec: PptxSlide
+interface PlanCommon {
title?: TitleBlock
body: Box
- bullets?: { items: string[]; size: number }
- table?: { layout: TableLayout; page: number }
- kpis?: PptxKpi[]
+}
+
+/** Layouts drawn on one slide whatever their content. */
+type SingleLayout = Exclude<SlideLayout, 'title-bullets' | 'title-table' | 'kpis'>
+
+/**
+ * One slide to draw: its spec, and for a layout that runs over several slides
+ * the part on this one, which it always has.
+ */
+export type PlannedSlide = PlanCommon &
+ (
+ | { spec: SlideOf<'title-bullets'>; bullets: { items: string[]; size: number } }
+ | { spec: SlideOf<'title-table'>; table: { layout: TableLayout; page: number } }
+ | { spec: SlideOf<'kpis'>; kpis: PptxKpi[] }
+ | { spec: SlideOf<SingleLayout> }
+ )
+
+/** The plan of a slide of `layout`. */
+export type PlanOf<L extends SlideLayout> = L extends SingleLayout
+ ? PlanCommon & { spec: SlideOf<L> }
+ : Extract<PlannedSlide, { spec: { layout: L } }>
+
+/** Whether `planned` is a slide of `layout`, as a type guard. */
+export function isPlanOf<L extends SlideLayout>(
+ planned: PlannedSlide,
+ layout: L
+): planned is PlanOf<L> {
+ return planned.spec.layout === layout
}
interface ListPlan {
@@ -173,7 +203,7 @@ export function planSlide(spec: PptxSlide, frame: Frame, warnings: string[]): Pl
const titleFor = (text: string | undefined) =>
titled && text ? layoutTitle(text, frame, fieldPath(spec, 'title'), warnings) : undefined
- if (spec.layout === 'title-bullets' && spec.bullets) {
+ if (spec.layout === 'title-bullets') {
let title = titleFor(spec.title)
let body = bodyBox(frame, title)
let list = planBullets(spec.bullets, body, frame, fieldPath(spec, 'bullets'), [])
@@ -198,7 +228,7 @@ export function planSlide(spec: PptxSlide, frame: Frame, warnings: string[]): Pl
}))
}
- if (spec.layout === 'title-table' && spec.table) {
+ if (spec.layout === 'title-table') {
let title = titleFor(spec.title)
let body = bodyBox(frame, title)
let layout = layoutTable(spec.table, body, frame.wide, fieldPath(spec, 'table'), [])
@@ -216,7 +246,7 @@ export function planSlide(spec: PptxSlide, frame: Frame, warnings: string[]): Pl
}))
}
- if (spec.layout === 'kpis' && spec.kpis) {
+ if (spec.layout === 'kpis') {
const n = Math.ceil(spec.kpis.length / KPIS_PER_SLIDE)
if (n > 1) {
warnings.push(
@@ -232,7 +262,7 @@ export function planSlide(spec: PptxSlide, frame: Frame, warnings: string[]): Pl
spec,
title,
body: bodyBox(frame, title),
- kpis: spec.kpis!.slice(i * perSlide, (i + 1) * perSlide),
+ kpis: spec.kpis.slice(i * perSlide, (i + 1) * perSlide),
}
})
}
diff --git a/mcp-host/src/workflow/pptxRender.ts b/mcp-host/src/workflow/pptxRender.ts
index 60c6d6afe..da068cf19 100644
--- a/mcp-host/src/workflow/pptxRender.ts
+++ b/mcp-host/src/workflow/pptxRender.ts
@@ -2,14 +2,16 @@
import { hasRtlLetter } from './docxScript'
import { nativeChartArgs } from './pptxCharts'
import { type DrawContext, fitOrShorten, hex } from './pptxDraw'
-import { type PptxColumn, type PptxSlide, fieldPath } from './pptxInput'
+import { type PptxColumn, type PptxSlide, type SlideOf, fieldPath } from './pptxInput'
import { drawKpis } from './pptxKpiCards'
import {
BULLET_INDENT,
BULLET_SPACE_AFTER,
type Box,
+ type PlanOf,
type PlannedSlide,
type TitleBlock,
+ isPlanOf,
} from './pptxLayout'
import { addPicture, placePicture } from './pptxPictures'
import {
@@ -217,8 +219,8 @@ function drawSection(slide: Slide, spec: PptxSlide, ctx: DrawContext): void {
}
}
-function drawBullets(slide: Slide, planned: PlannedSlide, ctx: DrawContext): void {
- const list = planned.bullets!
+function drawBullets(slide: Slide, planned: PlanOf<'title-bullets'>, ctx: DrawContext): void {
+ const list = planned.bullets
slide.addText(bulletRuns(slide, list.items), {
...planned.body,
fontSize: list.size,
@@ -275,9 +277,9 @@ function sameText(a: string | undefined, b: string | undefined): boolean {
return (a ?? '').trim().toLowerCase() === (b ?? '').trim().toLowerCase()
}
-function drawChart(slide: Slide, planned: PlannedSlide, ctx: DrawContext): void {
+function drawChart(slide: Slide, planned: PlanOf<'title-chart'>, ctx: DrawContext): void {
const { spec, body } = planned
- const chart = spec.chart!
+ const chart = spec.chart
const caption = captionFor(chart.caption, body.w, `${fieldPath(spec, 'chart')}.caption`, ctx)
const area = { ...body, h: body.h - (caption ? caption.h + 0.05 : 0) }
let bottom = area.y + area.h
@@ -315,8 +317,8 @@ function drawChart(slide: Slide, planned: PlannedSlide, ctx: DrawContext): void
if (caption) drawCaption(slide, caption, body.x, bottom + 0.05, body.w, ctx)
}
-function drawTable(slide: Slide, planned: PlannedSlide, ctx: DrawContext): void {
- const { layout, page } = planned.table!
+function drawTable(slide: Slide, planned: PlanOf<'title-table'>, ctx: DrawContext): void {
+ const { layout, page } = planned.table
const { rows, rowHeights } = layout.pages[page]
const p = ctx.palette
const data = rows.map((row, r) =>
@@ -424,21 +426,21 @@ function drawColumn(
}
}
-function drawTwoColumn(slide: Slide, planned: PlannedSlide, ctx: DrawContext): void {
+function drawTwoColumn(slide: Slide, planned: PlanOf<'two-column'>, ctx: DrawContext): void {
const { body, spec } = planned
const gap = 0.4
const colW = (body.w - gap) / 2
- drawColumn(slide, spec.columns!.left, { ...body, w: colW }, `${spec.where}.columns.left`, ctx)
+ drawColumn(slide, spec.columns.left, { ...body, w: colW }, `${spec.where}.columns.left`, ctx)
drawColumn(
slide,
- spec.columns!.right,
+ spec.columns.right,
{ ...body, x: body.x + colW + gap, w: colW },
`${spec.where}.columns.right`,
ctx
)
}
-function drawImage(slide: Slide, planned: PlannedSlide, ctx: DrawContext): void {
+function drawImage(slide: Slide, planned: PlanOf<'image'>, ctx: DrawContext): void {
const { body, spec } = planned
const picture = spec.picture
if (!picture) return
@@ -453,9 +455,9 @@ function drawImage(slide: Slide, planned: PlannedSlide, ctx: DrawContext): void
if (caption) drawCaption(slide, caption, body.x, box.y + box.h + 0.05, body.w, ctx)
}
-function drawQuote(slide: Slide, spec: PptxSlide, ctx: DrawContext): void {
+function drawQuote(slide: Slide, spec: SlideOf<'quote'>, ctx: DrawContext): void {
const { frame, palette } = ctx
- const quote = spec.quote!
+ const quote = spec.quote
addText(
slide,
'“',
@@ -528,26 +530,14 @@ export function drawFooter(
}
export function drawSlide(slide: Slide, planned: PlannedSlide, ctx: DrawContext): void {
- const { spec } = planned
if (planned.title) drawTitle(slide, planned.title, ctx)
- switch (spec.layout) {
- case 'cover':
- return drawCover(slide, spec, ctx)
- case 'section':
- return drawSection(slide, spec, ctx)
- case 'title-bullets':
- return drawBullets(slide, planned, ctx)
- case 'title-chart':
- return drawChart(slide, planned, ctx)
- case 'title-table':
- return drawTable(slide, planned, ctx)
- case 'kpis':
- return drawKpis(slide, planned, ctx)
- case 'two-column':
- return drawTwoColumn(slide, planned, ctx)
- case 'image':
- return drawImage(slide, planned, ctx)
- case 'quote':
- return drawQuote(slide, spec, ctx)
- }
+ if (isPlanOf(planned, 'cover')) return drawCover(slide, planned.spec, ctx)
+ if (isPlanOf(planned, 'section')) return drawSection(slide, planned.spec, ctx)
+ if (isPlanOf(planned, 'title-bullets')) return drawBullets(slide, planned, ctx)
+ if (isPlanOf(planned, 'title-chart')) return drawChart(slide, planned, ctx)
+ if (isPlanOf(planned, 'title-table')) return drawTable(slide, planned, ctx)
+ if (isPlanOf(planned, 'kpis')) return drawKpis(slide, planned, ctx)
+ if (isPlanOf(planned, 'two-column')) return drawTwoColumn(slide, planned, ctx)
+ if (isPlanOf(planned, 'image')) return drawImage(slide, planned, ctx)
+ if (isPlanOf(planned, 'quote')) return drawQuote(slide, planned.spec, ctx)
}