Consider providing a compact, agent-friendly authoring layer for Bento Slides

[benedictjohannes]

Context

Bento Slides is explicitly designed to be authored and edited by AI coding agents. The AGENTS.md guide is intended to be provided to agents such as Claude Code, and the documented file-harness workflow has the agent edit the JSON inside the #bento-doc block directly.

This works, but the JSON representation is quite verbose for an LLM to author. A large amount of the generated output consists of repetitive structural/default properties rather than information that is meaningful to the author.

For example, even a simple text element normally carries fields such as:

Original JSON text element

{
  "id": "title",
  "type": "text",
  "x": 96,
  "y": 100,
  "w": 1088,
  "h": 100,
  "rotation": 0,
  "opacity": 1,
  "html": "Hello",
  "fontSize": 48,
  "fontFamily": "system-ui, sans-serif",
  "fontWeight": 800,
  "color": "#111",
  "align": "left",
  "valign": "top",
  "lineHeight": 1.1
}

Much of this is boilerplate. It becomes particularly costly when an agent is generating a deck with dozens or hundreds of elements.

A small proof-of-concept

I built a small TypeScript authoring harness for my own use.

bentoUtils.ts

export interface BentoElement {
	id: string;
	type: "text" | "shape" | "image" | "table" | "chart" | "media" | "path";
	x: number;
	y: number;
	w: number;
	h: number;
	[key: string]: any;
}

export interface BentoSlide {
	id: string;
	background?: string;
	transition?: string;
	notes?: string;
	elements?: (BentoElement | BentoElement[])[];
	[key: string]: any;
}

export interface BentoDoc {
	format: string;
	version: number;
	title?: string;
	size?: { width: number; height: number };
	theme?: {
		background?: string;
		color?: string;
		accent?: string;
		fontFamily?: string;
		[key: string]: any;
	};
	slides: BentoSlide[];
	[key: string]: any;
}

/**
 * Applies default properties to elements (rotation, opacity, text alignment, default font)
 * and flattens any nested element arrays produced by element factory helpers.
 */
export function applyElementDefaults(doc: BentoDoc, options?: { validate?: boolean }): BentoDoc {
	const defaultFontFamily =
		doc.theme?.fontFamily ||
		"Inter, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif";

	for (const slide of doc.slides || []) {
		if (!slide.elements) continue;

		// Flatten element arrays (in case helpers return arrays of elements)
		const flattened: BentoElement[] = [];
		for (const item of slide.elements) {
			if (Array.isArray(item)) {
				flattened.push(...(item as BentoElement[]));
			} else if (item) {
				flattened.push(item as BentoElement);
			}
		}
		slide.elements = flattened;

		for (const el of flattened) {
			if (el.rotation === undefined) el.rotation = 0;
			if (el.opacity === undefined) el.opacity = 1;

			if (el.type === "text") {
				if (el.align === undefined) el.align = "left";
				if (el.valign === undefined) el.valign = "top";
				if (el.fontFamily === undefined) el.fontFamily = defaultFontFamily;
			}
		}
	}

	if (options?.validate) {
		const errors = validateBentoDoc(doc);
		if (errors.length > 0) {
			console.warn(`[Bento Lint Warnings]:\n` + errors.map((e) => `  - ${e}`).join("\n"));
		}
	}

	return doc;
}

/**
 * Layout helper for calculating side-by-side row items.
 * Computes bounding boxes (x, y, w, h) for `count` items spread evenly across `totalWidth`.
 */
export function layoutRow(options: {
	startX: number;
	y: number;
	totalWidth: number;
	height: number;
	count: number;
	gap?: number;
}): Array<{ x: number; y: number; w: number; h: number }> {
	const { startX, y, totalWidth, height, count, gap = 20 } = options;
	if (count <= 0) return [];
	const availableWidth = totalWidth - gap * (count - 1);
	const itemW = availableWidth / count;

	const boxes = [];
	for (let i = 0; i < count; i++) {
		boxes.push({
			x: startX + i * (itemW + gap),
			y,
			w: itemW,
			h: height,
		});
	}
	return boxes;
}

/**
 * Layout helper for matrix grid positioning.
 */
export function layoutGrid(options: {
	startX: number;
	startY: number;
	width: number;
	height: number;
	rows: number;
	cols: number;
	gapX?: number;
	gapY?: number;
}): Array<{ row: number; col: number; x: number; y: number; w: number; h: number }> {
	const { startX, startY, width, height, rows, cols, gapX = 20, gapY = 20 } = options;
	const cellW = (width - gapX * (cols - 1)) / cols;
	const cellH = (height - gapY * (rows - 1)) / rows;

	const grid = [];
	for (let r = 0; r < rows; r++) {
		for (let c = 0; c < cols; c++) {
			grid.push({
				row: r,
				col: c,
				x: startX + c * (cellW + gapX),
				y: startY + r * (cellH + gapY),
				w: cellW,
				h: cellH,
			});
		}
	}
	return grid;
}

/**
 * Factory for building a standard Bento Card (Shape + Title + Body Text elements).
 */
export function createCard(options: {
	id: string;
	x?: number;
	y?: number;
	w?: number;
	h?: number;
	fill?: string;
	stroke?: string;
	strokeWidth?: number;
	radius?: number;
	shadow?: any;
	kicker?: { html: string; color?: string; fontSize?: number; align?: "left" | "center" | "right" };
	title?: { html: string; color?: string; fontSize?: number; fontFamily?: string; align?: "left" | "center" | "right"; fontWeight?: number };
	body?: { html: string; color?: string; fontSize?: number; align?: "left" | "center" | "right"; fontWeight?: number };
	padding?: number;
}): BentoElement[] {
	const {
		id,
		x = 0,
		y = 0,
		w = 0,
		h = 0,
		fill = "#FFFFFF",
		stroke = "transparent",
		strokeWidth = 0,
		radius = 24,
		shadow,
		kicker,
		title,
		body,
		padding = 28,
	} = options;

	const elements: BentoElement[] = [];

	// Background Shape
	elements.push({
		id: `${id}_bg`,
		type: "shape",
		shape: "rect",
		x,
		y,
		w,
		h,
		fill,
		stroke,
		strokeWidth,
		radius,
		...(shadow ? { shadow } : {}),
	});

	let currentY = y + padding;
	const contentW = w - padding * 2;
	const contentX = x + padding;

	if (kicker) {
		const kickerH = kicker.fontSize ? kicker.fontSize * 1.4 : 20;
		elements.push({
			id: `${id}_kicker`,
			type: "text",
			x: contentX,
			y: currentY,
			w: contentW,
			h: kickerH,
			html: kicker.html,
			fontSize: kicker.fontSize || 12,
			fontWeight: 700,
			color: kicker.color || "#FF9E8A",
			align: kicker.align || "left",
			lineHeight: 1.2,
			letterSpacing: 2,
		});
		currentY += kickerH + 8;
	}

	if (title) {
		const titleH = title.fontSize ? title.fontSize * 1.3 : 32;
		elements.push({
			id: `${id}_title`,
			type: "text",
			x: contentX,
			y: currentY,
			w: contentW,
			h: titleH,
			html: title.html,
			fontSize: title.fontSize || 24,
			fontWeight: title.fontWeight || 800,
			fontFamily: title.fontFamily,
			color: title.color || "#0D1B2E",
			align: title.align || "left",
			lineHeight: 1.2,
		});
		currentY += titleH + 12;
	}

	if (body) {
		const remainingH = y + h - currentY - padding;
		elements.push({
			id: `${id}_body`,
			type: "text",
			x: contentX,
			y: currentY,
			w: contentW,
			h: Math.max(remainingH, 24),
			html: body.html,
			fontSize: body.fontSize || 16,
			fontWeight: body.fontWeight || 400,
			color: body.color || "#41597A",
			align: body.align || "left",
			lineHeight: 1.45,
		});
	}

	return elements;
}

/**
 * Factory for slide top header/kicker/divider chrome.
 */
export function createHeader(options: {
	kicker: string;
	pageNumber?: string | number;
	title?: string;
	subtitle?: string;
	isDark?: boolean;
	y?: number;
}): BentoElement[] {
	const { kicker, pageNumber, title, subtitle, isDark = false, y = 54 } = options;
	const elements: BentoElement[] = [];

	const primaryColor = isDark ? "#FF9E8A" : "#C25A43";
	const ruleColor = isDark ? "rgba(255,255,255,0.14)" : "rgba(15,23,36,0.12)";
	const pageColor = isDark ? "rgba(255,255,255,0.42)" : "rgba(30,42,58,0.4)";

	// Kicker
	elements.push({
		id: "hdr_kicker",
		type: "text",
		x: 96,
		y,
		w: 700,
		h: 26,
		html: kicker.toUpperCase(),
		fontSize: 13,
		fontWeight: 700,
		color: primaryColor,
		lineHeight: 1.2,
		letterSpacing: 4,
	});

	// Page Counter
	if (pageNumber !== undefined) {
		const pageStr = typeof pageNumber === "number" ? String(pageNumber).padStart(2, "0") : pageNumber;
		elements.push({
			id: "hdr_page",
			type: "text",
			x: 1024,
			y,
			w: 160,
			h: 26,
			html: pageStr,
			fontSize: 13,
			fontWeight: 700,
			color: pageColor,
			align: "right",
			lineHeight: 1.2,
			letterSpacing: 2,
		});
	}

	// Divider Line
	elements.push({
		id: "hdr_rule",
		type: "shape",
		shape: "line",
		x: 96,
		y: y + 32,
		w: 1088,
		h: 1.5,
		fill: ruleColor,
		stroke: "transparent",
		strokeWidth: 1.5,
		radius: 0,
		strokeStyle: "solid",
	});

	if (title) {
		elements.push({
			id: "hdr_title",
			type: "text",
			x: 96,
			y: y + 54,
			w: 1088,
			h: 60,
			html: title,
			fontSize: 44,
			fontFamily: "'Georgia', 'Times New Roman', serif",
			fontWeight: 900,
			color: isDark ? "#FFFFFF" : "#0D1B2E",
			lineHeight: 1.1,
		});
	}

	if (subtitle) {
		const subY = title ? y + 120 : y + 54;
		elements.push({
			id: "hdr_subtitle",
			type: "text",
			x: 96,
			y: subY,
			w: 1088,
			h: 40,
			html: subtitle,
			fontSize: 20,
			fontWeight: 500,
			color: isDark ? "#B6C1D2" : "#5E7699",
			lineHeight: 1.4,
		});
	}

	return elements;
}

/**
 * Validates a Bento document for structural, schema, and rendering issues.
 */
export function validateBentoDoc(doc: any): string[] {
	const warnings: string[] = [];

	if (!doc || typeof doc !== "object") {
		return ["Document is not an object"];
	}

	if (doc.format !== "bento/slides") {
		warnings.push(`Expected format "bento/slides", got "${doc.format}"`);
	}

	const forbiddenBlockTags = ["<div", "<p", "<ul", "<ol", "<li", "<h1", "<h2", "<h3", "<h4", "<table"];

	(doc.slides || []).forEach((slide: any, sIdx: number) => {
		const sId = slide.id || `slide[${sIdx}]`;
		const seenIds = new Set<string>();

		(slide.elements || []).forEach((el: any, eIdx: number) => {
			if (!el.id) {
				warnings.push(`${sId}: element at index ${eIdx} missing "id"`);
			} else {
				if (seenIds.has(el.id)) {
					warnings.push(`${sId}: duplicate element id "${el.id}"`);
				}
				seenIds.add(el.id);
			}

			if (el.x === undefined || el.y === undefined || el.w === undefined || el.h === undefined) {
				warnings.push(`${sId} (${el.id}): missing coordinates (x, y, w, h)`);
			}

			if (el.type === "text" && typeof el.html === "string") {
				const lowerHtml = el.html.toLowerCase();
				for (const tag of forbiddenBlockTags) {
					if (lowerHtml.includes(tag)) {
						warnings.push(
							`${sId} (${el.id}): text.html contains block container tag "${tag}>". Bento engine ignores/breaks styling on block elements. Use flat tags <b>, <i>, <br>, <span style="..."> instead.`
						);
					}
				}
			}
		});
	});

	return warnings;
}

The basic idea is to let the agent write a more compact authoring representation and compile/normalize it into the existing Bento document format. It currently provides:

• default-property expansion;
• nested-element flattening;
• row/grid layout helpers;
• a reusable card factory;
• reusable header/chrome generation;
• lightweight authoring-time validation.

For example, applyElementDefaults() allows an author to omit properties that have known defaults:

export const doc = applyElementDefaults({
  format: "bento/slides",
  version: 1,
  title: "Example",
  theme: {
    background: "#101418",
    color: "#F2F0EA",
    accent: "#FF9E8A",
    fontFamily: "system-ui, sans-serif"
  },
  slides: [
    {
      id: "s1",
      elements: [
        {
          id: "title",
          type: "text",
          x: 96,
          y: 100,
          w: 1088,
          h: 100,
          html: "Hello",
          fontSize: 48,
          fontWeight: 800
        }
      ]
    }
  ]
});

The helper fills in the repetitive defaults and produces the normal Bento JSON representation. I also have helpers for common structures:

layoutRow(...)
layoutGrid(...)
createCard(...)
createHeader(...)

This isn't intended to hide Bento's document model. The generated result remains normal Bento JSON; the TypeScript layer is simply a more compact authoring representation. For example, createCard() can produce the background, kicker, title, and body elements as one authoring operation, while still producing ordinary editable Bento elements with deterministic IDs.

This utility was built purely from observing the provided AGENTS.md; I haven't looked into Bento's internal implementation. The motivation came from using ChatGPT to author a Bento slide and observing that it wrote a Python script to generate repetitive elements. I realized that a small reusable authoring layer could solve the same problem more directly.

Why this matters particularly for AI agents

For a human, repetitive JSON is mostly an inconvenience.

For an LLM, it has additional costs:

• More context consumed by repetitive properties.
• More output tokens spent reproducing boilerplate.
• Less context available for the actual content and design decisions.
• More difficulty making large structural edits consistently.

This is particularly relevant during iterative editing, where the agent may repeatedly need to read and modify a large document.

The current AGENTS.md workflow effectively asks an agent to author directly in the canonical document representation. A compact authoring layer would let the agent work at a slightly higher level while preserving the same underlying Bento model.

This could be better coming from upstream

I haven't looked at the TypeScript code that comprises Bento's internals, so I don't know whether this is best implemented inside the runtime, as a companion package, or as part of the agent skill.

However, the documented Bento element schema already provides a sufficiently structured foundation for building a compact authoring layer on top of it.

Such authoring aids could take several forms:

1. Official helper library, similar to my proof of concept.
2. A compact JSON representation where default properties may be omitted and are normalized by Bento.
3. An official TypeScript authoring API / DSL that compiles to the existing document format.

The important distinction is that the storage/runtime representation does not necessarily need to change. The compact representation could simply compile into the existing bento/slides schema.

In one particular Bento slide I worked with:

wc *
  3263   7175  87382 Meeting260810.json
  1532   4220  42678 Meeting260810.ts

So the TypeScript authoring source was roughly half the size of the generated JSON, while also expressing some structures at a higher level rather than merely omitting defaults.

The Meeting260810.ts is a 11 slide Bento slide that consists of structural code such as:

import { applyElementDefaults, createCard, createHeader, layoutRow } from "../bentoUtils";

const slide3Boxes = layoutRow({ startX: 116, y: 250, totalWidth: 1048, height: 240, count: 2, gap: 48 });
const slide6Boxes = layoutRow({ startX: 96, y: 260, totalWidth: 1088, height: 240, count: 3, gap: 34 });
const slide7Boxes = layoutRow({ startX: 116, y: 320, totalWidth: 1048, height: 200, count: 2, gap: 48 });
const slide11Boxes = layoutRow({ startX: 96, y: 240, totalWidth: 1088, height: 280, count: 3, gap: 34 });

export const doc = applyElementDefaults({
  // actual content is here
}, { validate: true });

if (import.meta.main) {
  const { writeFile } = await import("node:fs/promises");
  const { join } = await import("node:path");
  const jsonOutPath = join(import.meta.dir, "Meeting260810.json");
  await writeFile(jsonOutPath, JSON.stringify(doc, null, 2), "utf-8");
}

I'd be interested in whether this is something you'd consider supporting officially, or whether there is already a preferred approach for compact, agent-oriented Bento authoring that I have missed.

[nyblnet]

Some way to compress the document JSON is something I was exploring so this is really timely. I particularly appreciate the poc implementation. Will test this over the weekend and see how we can incorporate this in the next release. From what I can see, we should be able to add this ability to the runtime quite easily and without much adding much size. Thanks for taking the time to put this together and the feedback!

[nyblnet]

This is in 1.2.0, out now, and your proof of concept is the shape it took. A document can carry "compact": true and leave out every field that equals what the editor would have inserted; on load they come back from the editor's own defaults, including the ones derived from the deck. Two things came straight from your harness: elements may nest arrays, and an element without an id gets one minted from its slide and position, the same every run. Round two added text that sizes itself, Markdown content, layouts and roles instead of coordinates, and a load report of what was dropped. Getting it back: Save, then Copy compact JSON, or window.bento.compact(). There is also node scripts/bento-check.mjs for a headless check with a picture per slide, and a published schema at bento.page/schema/slides.json. The saved file is unchanged and always the full document. On an agent-written deck the JSON is about a third of the size. Thank you for the write-up and the code. Closing this and #422.