Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
Close the gaps an agent hits authoring a deck from agents.md alone (#193)
nyblnetd4b49fdcf345
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 92b5beb1..74416c7a 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -122,6 +122,13 @@ jobs:# file carrying a script tag.run: node scripts/test-preview.ts+ - name: Built-in layout geometry rig+ # The built-ins are drawn against 1600x900 while the model default is+ # 1280x720, so they used to hang 200px off the right edge of a default+ # deck. Nothing structural could see it — the fix is arithmetic, and so+ # is the regression.+ run: node scripts/test-layouts.ts+- name: Clipboard embedded-font rigrun: |slides/node_modules/.bin/esbuild scripts/test-clipboard.ts --bundle --platform=node --format=esm --outfile="$RUNNER_TEMP/test-clipboard.mjs"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f6fad163..34c5753c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,28 @@ pre-1.0.## [Unreleased]+- **Fix: count-up numbers work on morph slides.** `fx.countUp` was started only+ by the entrance runner, and morph and entrances are mutually exclusive — so a+ statistic on a slide reached by `transition:"morph"` silently rendered a+ static number. Count-ups now also run on a morph arrival, for elements with+ no morph partner on the previous slide; one that flew in already showing its+ number does not restart from zero. This combination is one the authoring+ guide actively recommends, so it failed quietly and often.++- **Fix: the built-in layouts fit the slide.** They were drawn for a 1600×900+ stage while the default deck is 1280×720, so applying *Title* put the title+ box 160 px off the right edge and *Title + content* overflowed the bottom by+ 88 px. They are now scaled to the deck's own page size, which also makes them+ correct for the custom sizes the slide panel offers.++- **The agent authoring guide describes what the runtime actually does.**+ `agents.md` gained the download URL, the real `fx.loop` parameters (and the+ `strokeStyle` a dash-march needs to be visible), the chart option keys+ charts-lite honours, `morphId`, layouts and `role`, column arithmetic for the+ 1280×720 canvas, and an accurate account of embedded fonts. Every gap here+ was found by an agent authoring a deck from the guide alone, and every one of+ them failed silently. Reported in detail by thinkbig1979.+## [1.0.13] — 2026-08-02- **Fix: fade, slide and zoom transitions animate again.** They had beendiff --git a/docs/agents.md b/docs/agents.mdindex 9211ddfe..f37e26ff 100644--- a/docs/agents.md+++ b/docs/agents.md@@ -34,6 +34,18 @@ mkdir -p ~/.claude/skills/bento-slides && curl -fsSL https://bento.page/skills/b[bento.page/skills/bento-slides.zip](https://bento.page/skills/bento-slides.zip)under Settings → Skills.)*+**Working without the skill, from an empty folder?** Download the app itself —+this is the file you write your document into:++```bash+curl -fsSL https://bento.page/releases/slides/Bento_Slides.bento.html -o "<Topic>.bento.html"+```++The downloaded file's `#bento-doc` block is **empty**. That is expected: opened+in a browser it mints a fresh showcase deck to get a new user started, but on+disk there is nothing to discard and nothing to copy from. Write your document+into the empty block.+A Bento deck (`*.bento.html`) is a self-contained HTML file. The documentlives in ONE plaintext block near the top:@@ -149,6 +161,12 @@ each kind of content to the feature built for it:- [ ] A drill-down that would work better as a **state slide**?- [ ] One accent colour, at most two typefaces, **96px** side margins (right-most x ≤ 1184)?- [ ] **Speaker notes** written on each slide (they travel in the file and double as the talk track)?+- [ ] **Have you actually looked at it?** Open the deck and page through every+ slide. Text overflowing its box, two elements crowding each other, a+ heading that wrapped to three lines, a chart key that was silently+ dropped — none of these are visible in the JSON, and all of them are+ obvious on screen. This is the only check that catches what the others+ cannot; a deck nobody rendered is not finished.## Minimal valid document@@ -204,6 +222,24 @@ without them — and elements should carry the full field set shown.scales (e.g. volume + a %), make `yAxis` an ARRAY of two `{type:"value"}`axes (give the 2nd `axisLabel:{formatter:"{value}%"}`) and point the oddseries at it with `"yAxisIndex":1` — render it as a `line` over the bars.+ **The engine is charts-lite, not ECharts** — it reads the option SHAPE and+ ignores every key it does not implement, silently. What it honours:+ - top level — `color`, `series`, `xAxis`, `yAxis`, `legend`, `grid`,+ `tooltip`, `textStyle`, `dataZoom`+ - any series — `type`, `name`, `data`, `yAxisIndex`, `itemStyle.color`+ - bar — `itemStyle.borderRadius`+ - line — `smooth`, `symbol`, `symbolSize`, `lineStyle.color`,+ `lineStyle.width`, `areaStyle.color`+ - pie — `radius`, `label.formatter` (or `label:false`),+ `itemStyle.borderColor`, `itemStyle.borderWidth`+ - axes — `type`, `data`, `min`, `max`, `axisLabel` (`fontSize`,+ `fontWeight`, `color`, `formatter`), `axisLine`, `splitLine`+ - legend — `show`, `top`, `bottom`, `textStyle.fontSize`,+ `textStyle.fontWeight`++ **`label` on a bar or line series does nothing** — value labels above bars+ are pie-only. If you need the numbers visible on a cartesian chart, put them+ in a table beside it, or use text elements.- **table**: `columns` (array of `{w}` fractional weights), `rows` (array of`{cells:[{html, align?, color?, bg?, bold?}]}`), `header` (bool — row 0 isthe header), and a `style` object (`headerBg`, `headerColor`, `zebra?`,@@ -227,13 +263,36 @@ without them — and elements should carry the full field set shown.elements whose `id` matches the previous slide — position, size, color,gradients. This is THE signature move: carry 2–4 ids through the deck andrearrange them per slide. Generators must emit deterministic ids.+- **`morphId` decouples morph identity from `id`.** The real pairing key is+ `morphId || id`, so an element can keep whatever `id` it likes and set+ `"morphId": "running-head"` to morph against a differently-named element on+ the next slide. For a generator this beats threading one id by hand through+ every slide, and it lets two independently-created elements pair up. The key+ must be unique **within** a slide. Plain shared `id` still works and is still+ the simplest thing when you control both slides.- **Entrances**: `fx: { enter: "fade-up", order: 0 }` — equal `order` =- simultaneous. Entrance staggers only run on non-morph arrivals.+ simultaneous. **Entrance staggers do not run on a morph arrival** — a+ morphing element is already in motion and an entrance tween would fight it.+ Count-ups are different: on a morph arrival they run for elements that have+ **no** morph partner on the previous slide (a new statistic counts; one that+ flew in already showing its number does not restart from zero). So a headline+ number on a morph slide is fine as long as it is new to that slide.- **Ken-burns**: `fx: { ambient: "kenburns", ken: { dir: "drift|out|in",scale: 1.08, duration: 20 } }` — `drift` loops, `out`/`in` settle once onslide entry. For full-bleed photos: image at 0,0,1280,720 + a scrim rect+ text on top. Never combine entrance tweens with motion-path loops.-- **Loops**: `fx: { loop: { type: "dash-march" | "motion-path", ... } }`.+- **Loops**: two shapes, both under `fx.loop`.+ - `{ type: "dash-march", distance: 18, duration: 1.4 }` — marches the stroke+ dashes along a shape. It animates `strokeDashoffset`, so it needs a+ `stroke` **and** a dash pattern: set `strokeStyle: "dashed"` or `"dotted"`.+ On a solid stroke the tween still runs and there is nothing to see.+ - `{ type: "motion-path", path: "M0,0 C60,-40 140,40 200,0", duration: 6,+ delay: 0, ease: "none", speeds: [1, 1] }` — drifts the element along a+ path given RELATIVE to its resting position (the first anchor is where it+ sits). `speeds` is optional, one multiplier per on-curve point, and lets+ the element dwell in places and rush others; omit it for constant pace.+ Never put an entrance tween on a motion-path element — they fight over the+ same transform.- **Interactivity**: element `link: "<slide-id>"` jumps on click; a slidewith `stateOf: "<parent-id>"` is a hidden variant reached only by links(arrow keys skip it, ← returns to parent). Give clickable things a padded@@ -246,9 +305,50 @@ without them — and elements should carry the full field set shown.- Canonical canvas 1280×720 (`doc.size` can differ — read it first).- Keep 96 px side margins (right-most content x ≤ 1184).+- **Column arithmetic, already done.** On 1280×720 inside 96 px margins the+ content band is 1088 px wide. Use these rather than computing your own:++ | Split | Width | `x` positions | Gutter |+ |---|---|---|---|+ | 2 columns | 528 | 96, 656 | 32 |+ | 3 columns | 340 | 96, 470, 844 | 34 |+ | 4 columns | 254 | 96, 374, 652, 930 | 24 |+ | 60 / 40 (text + image) | 624 / 432 | 96, 752 | 32 |++ Every row ends flush at x = 1184. Vertically, a title band of `y:72 h:84`+ over content starting at `y:208` leaves 416 px of content height above a+ 96 px bottom margin.- One accent color; 2 typefaces max. `theme` sets deck defaults.- Fonts: `doc.fonts` (`{family, asset, weight}`) + woff2 data URIs in`doc.assets` if you need embedded faces; otherwise stick to system stacks.+ **A `fontFamily` naming a face the document does not carry falls back+ silently** to the next entry in the stack — there is no warning, and the deck+ just looks like the fallback. Fonts belong to the DOCUMENT, not the app:+ Instrument Sans and Fraunces appear in the starter deck and in several+ templates because those files embed them in their own `doc.assets`, not+ because the app provides them. So either embed the woff2 yourself, start from+ a template that already carries the face, or name a system stack and mean it.+ Always write a full stack (`"'Fraunces', Georgia, serif"`), never a bare+ family name.++## Layouts and `role`++`doc.layouts` is a supported top-level key: an array of Slide-shaped templates+the editor offers under *Apply layout*. Every deck also gets five built-ins+(`layout-title`, `layout-title-content`, `layout-two-col`, `layout-section`,+`layout-blank`), which are scaled to the deck's `doc.size` when applied.++The part that matters when you are generating a deck is **`role`**. Any text+element can carry `"role": "title" | "subtitle" | "body" | "kicker"`. Applying a+layout matches donor to target by `id` first and then by `role` + `type`, so+roles are what let someone restyle your deck later without re-typing it —+content rides across, the layout supplies frame and typography. Setting them+costs one key per element and makes a generated deck feel native to the editor.++Two smaller things: a layout's text elements use `placeholder` (a dimmed prompt+shown in the editor, hidden in present and print) rather than `html`, and+slides instantiated from the same layout keep their element ids — which is+exactly why their furniture morphs across a transition.## Dynamic fields (tokens in text `html`)@@ -270,8 +370,9 @@ keywords}` object — great for title slides and footers that fill from one placpresentation with no editor. Set it only on hand-out copies.- If `template: true` is set, every open mints a fresh document (that's fordistributable templates; remove it for a personal deck).-- Charts degrade gracefully but exotic ECharts config is ignored — keep- options minimal.+- Charts degrade gracefully but anything outside the list in the **chart**+ element type above is ignored, with no warning — keep options minimal and+ check the rendered slide rather than trusting the JSON.- **Media size**: embedding a large video as a data URI can push the file intothe tens of MB and make it slow to open and save. Embed only short clips;otherwise host the file and put its URL in `media.src`.diff --git a/plugins/bento-slides/skills/bento-slides/SKILL.md b/plugins/bento-slides/skills/bento-slides/SKILL.mdindex 4e5106e2..e61577b5 100644--- a/plugins/bento-slides/skills/bento-slides/SKILL.md+++ b/plugins/bento-slides/skills/bento-slides/SKILL.md@@ -40,8 +40,10 @@ curl -fsSL https://bento.page/releases/slides/Bento_Slides.bento.html -o "<Topic(Windows without curl: `iwr https://bento.page/releases/slides/Bento_Slides.bento.html -OutFile <Topic>.bento.html`.)-Then verify the download contains `id="bento-doc"`, and **replace** that-block's JSON (it ships with a showcase deck — discard it) with your document.+Then verify the download contains `id="bento-doc"`, and write your document+into that block. **The block is empty in the downloaded file** — a browser+mints a showcase deck on first open, but on disk there is nothing to discard+and nothing to copy from, so do not go looking for it.Rules for a fresh document:- **Fetch https://bento.page/agents.md BEFORE authoring** and start from its@@ -53,9 +55,12 @@ Rules for a fresh document:- **Omit `docId` and `collab` entirely**: the app mints a fresh identity anddormant collaboration credentials on first open.-When done, offer to open it (`open` / `xdg-open` / `start`) — the file boots-straight into the editor with the finished deck. Aim for one pass from-request to opened deck.+When done, open it (`open` / `xdg-open` / `start`) — the file boots straight+into the editor with the finished deck — and **look at every slide before you+report done**. Text overflow, elements crowding each other, a heading that+wrapped to three lines and a chart key the renderer dropped are all invisible+in the JSON and obvious on screen. Author, render, check, fix; a deck nobody+looked at is not finished.## Workflowdiff --git a/scripts/test-layouts.ts b/scripts/test-layouts.tsnew file mode 100644index 00000000..fd094932--- /dev/null+++ b/scripts/test-layouts.ts@@ -0,0 +1,84 @@+#!/usr/bin/env node+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 The Bento authors+// Built-in layout geometry rig.+//+// node scripts/test-layouts.ts (Node ≥ 23.6 strips types natively)+//+// WHAT THIS PROVES. `builtinLayouts()` is drawn against a 1600x900 stage+// (LAYOUT_BASE) while the model default is 1280x720. For as long as the+// function ignored the deck's page size, applying "Title" to a default deck+// put the title box at x:160 w:1280 — a right edge of 1440 on a 1280-wide+// slide — and "Title + content" overflowed the bottom by 88px.+//+// That is the kind of defect no structural gate sees: tsc is happy, the shell+// builds, the file saves, and the only symptom is a heading running off the+// side of a slide somebody is presenting. It was found by an agent authoring+// a deck from agents.md (issue #160, finding 9b), not by us.+//+// So: every built-in layout must fit inside the canvas it is asked for, at+// the model default, at the authoring base, and at the non-16:9 sizes the+// slide panel offers. A layout that overflows here would ship a broken slide+// to whoever picked it.++import { builtinLayouts } from '../slides/src/model.ts'++let failures = 0+let checks = 0+function ok(cond: boolean, msg: string) {+ checks+++ if (!cond) { failures++; console.log(` FAIL ${msg}`) }+ else console.log(` ok ${msg}`)+}++// The model default, the geometry's own base, and the two page-size presets+// that are not 16:9 — a squarer canvas is where a naive width-only scale breaks.+const SIZES = [+ { width: 1280, height: 720, name: 'model default 16:9' },+ { width: 1600, height: 900, name: 'authoring base 16:9' },+ { width: 1024, height: 768, name: '4:3' },+ { width: 1920, height: 1080, name: 'large 16:9' },+]++for (const size of SIZES) {+ const bad: string[] = []+ for (const ly of builtinLayouts(size)) {+ for (const e of ly.elements) {+ if (e.x < 0 || e.y < 0 || e.x + e.w > size.width || e.y + e.h > size.height) {+ bad.push(`${ly.id}/${e.id} → right ${e.x + e.w}, bottom ${e.y + e.h}`)+ }+ }+ }+ ok(bad.length === 0,+ `every built-in layout fits ${size.width}x${size.height} (${size.name})` ++ (bad.length ? `\n ${bad.join('\n ')}` : ''))+}++// Type has to scale too. A heading kept at 76px on a 1024-wide canvas would+// fit its BOX by the check above and still overflow it visually.+const titleAt = (w: number, h: number) => {+ const ly = builtinLayouts({ width: w, height: h }).find((l) => l.id === 'layout-title')!+ return ly.elements.find((e) => e.id === 'lt-title') as { fontSize?: number }+}+ok((titleAt(1280, 720).fontSize ?? 0) < (titleAt(1600, 900).fontSize ?? 0),+ 'title type shrinks with the canvas')+ok((titleAt(1920, 1080).fontSize ?? 0) > (titleAt(1600, 900).fontSize ?? 0),+ 'title type grows with the canvas')++// Omitting the size must return the base geometry untouched — `layoutElementIds`+// calls it that way purely to collect ids, and scaling there would be waste.+const bare = builtinLayouts()+const base = builtinLayouts({ width: 1600, height: 900 })+ok(JSON.stringify(bare) === JSON.stringify(base),+ 'no size argument returns the unscaled base geometry')++// Ids are the join key for `applyLayout` (match by id, then by role), so a+// rescale must never rename anything.+ok(builtinLayouts({ width: 1024, height: 768 }).map((l) => l.id).join() === bare.map((l) => l.id).join(),+ 'scaling preserves layout ids')+ok(JSON.stringify(builtinLayouts({ width: 1024, height: 768 }).map((l) => l.elements.map((e) => e.id)))+ === JSON.stringify(bare.map((l) => l.elements.map((e) => e.id))),+ 'scaling preserves element ids')++console.log(`\n${checks - failures}/${checks} checks passed`)+if (failures) process.exit(1)diff --git a/slides/src/editor/editor.ts b/slides/src/editor/editor.tsindex 636cce65..f9933be1 100644--- a/slides/src/editor/editor.ts+++ b/slides/src/editor/editor.ts@@ -1490,7 +1490,7 @@ export class Editor {t.textContent = i18nT('Apply layout to this slide')pick.appendChild(t)}- const sections: Array<[string, Slide[], boolean]> = [[t('Built-in'), builtinLayouts(), false]]+ const sections: Array<[string, Slide[], boolean]> = [[t('Built-in'), builtinLayouts(doc.size), false]]if (doc.layouts?.length) sections.push([t('This document'), doc.layouts, true])for (const [label, layouts, custom] of sections) {const h = div('ed-layoutpick-h')diff --git a/slides/src/model.ts b/slides/src/model.tsindex 81e47fcc..421faafa 100644--- a/slides/src/model.ts+++ b/slides/src/model.ts@@ -843,9 +843,48 @@ const bar = (id: string, frame: { x: number; y: number; w: number; h: number }):rotation: 0, opacity: 1, fill: '#F7A600', stroke: 'transparent', strokeWidth: 0, radius: 2,})-/** The layouts every document offers out of the box (not persisted until edited). */-export function builtinLayouts(): Slide[] {- return [+/**+ * The canvas the built-in layout geometry below is authored against.+ *+ * It is NOT the model default (1280x720) — these layouts were drawn for a+ * 1600x900 stage, so on a default deck every one of them used to hang off the+ * right edge (`lt-title` ran to x=1440 on a 1280-wide slide) and the+ * title+content body overflowed the bottom by 88px. `builtinLayouts(size)`+ * scales them to the deck instead, which also makes them correct for the+ * custom page sizes the slide panel offers.+ */+const LAYOUT_BASE = { width: 1600, height: 900 }++/** Rescale a built-in layout from LAYOUT_BASE onto an arbitrary canvas. */+function scaleLayout(ly: Slide, sx: number, sy: number): Slide {+ // Type scales with the SMALLER axis: on a squarer canvas the limiting+ // dimension is what decides whether a heading still fits its box.+ const st = Math.min(sx, sy)+ return {+ ...ly,+ elements: ly.elements.map((el) => {+ const next = {+ ...el,+ x: Math.round(el.x * sx), y: Math.round(el.y * sy),+ w: Math.round(el.w * sx), h: Math.round(el.h * sy),+ } as SlideElement+ if (next.type === 'text') {+ const txt = next as TextElement+ if (txt.fontSize) txt.fontSize = Math.max(8, Math.round(txt.fontSize * st))+ if (txt.letterSpacing) txt.letterSpacing = Math.round(txt.letterSpacing * st * 10) / 10+ }+ return next+ }),+ }+}++/**+ * The layouts every document offers out of the box (not persisted until edited).+ * Pass the deck's page size to get geometry that fits it; omit it only when the+ * caller just wants the element ids.+ */+export function builtinLayouts(size?: { width: number; height: number }): Slide[] {+ const base: Slide[] = [{id: 'layout-title', name: 'Title', background: '#FFFFFF', transition: 'fade', notes: '', elements: [bar('lt-bar', { x: 160, y: 380, w: 72, h: 8 }),@@ -886,6 +925,10 @@ export function builtinLayouts(): Slide[] {},{ id: 'layout-blank', name: 'Blank', background: '#FFFFFF', transition: 'fade', notes: '', elements: [] },]+ if (!size || (size.width === LAYOUT_BASE.width && size.height === LAYOUT_BASE.height)) return base+ const sx = size.width / LAYOUT_BASE.width+ const sy = size.height / LAYOUT_BASE.height+ return base.map((ly) => scaleLayout(ly, sx, sy))}/** A fresh slide from a layout — new slide id, element ids KEPT (lineage). */diff --git a/slides/src/present.ts b/slides/src/present.tsindex 273782f8..f8f56370 100644--- a/slides/src/present.ts+++ b/slides/src/present.ts@@ -948,7 +948,12 @@ export function startPresentation(from &&((forward && doc.slides[toIdx]?.transition === 'morph') ||(!forward && doc.slides[fromIdx]?.transition === 'morph'))- if (morphing) { if (!reduceMotion) runMorph(doc, from!, to, fromIdx, toIdx) }+ if (morphing) {+ if (!reduceMotion) {+ runMorph(doc, from!, to, fromIdx, toIdx)+ runMorphArrivalCountUps(doc.slides[fromIdx], doc.slides[toIdx], to)+ }+ }else if (!reduceMotion) runEnterFx(doc.slides[toIdx], to)if (!reduceMotion) {runAmbientFx(doc.slides[toIdx], to)@@ -1116,6 +1121,29 @@ function runEnterFx(slide: Slide, section: HTMLElement) {settleGuarantee(entering.map(([el, node]) => [node, el]))}+/**+ * Count-ups on a MORPH arrival, for elements the morph did not carry over.+ *+ * Morph and entrance are mutually exclusive branches — an entrance tween on a+ * morphing element would fight the morph — and `runCountUp` lived only on the+ * entrance side, so `fx.countUp` on a slide reached by `transition:'morph'`+ * silently rendered a static number. That is a combination the authoring guide+ * actively recommends (a headline statistic on a slide that morphs its+ * furniture in), so it failed quietly and often.+ *+ * A count-up element WITH a morph partner is already on screen showing its+ * number as it flies in; restarting it from zero would be wrong. One with no+ * partner is new on this slide, has no transform to fight, and is exactly what+ * the author asked to count.+ */+function runMorphArrivalCountUps(from: Slide | undefined, to: Slide, section: HTMLElement) {+ const carried = new Set((from?.elements ?? []).map((el) => el.morphId || el.id))+ for (const [el, node] of fxNodes(to, section)) {+ if (!el.fx!.countUp || el.showOnHover) continue+ if (!carried.has(el.morphId || el.id)) runCountUp(node)+ }+}+/*** Wall-clock safety net: on starved render loops (throttled tabs, weak* machines) tween progress crawls — guarantee every animated element lands