Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

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.yml
index 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 rig
run: |
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.md
index 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 been
diff --git a/docs/agents.md b/docs/agents.md
index 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 document
lives 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 odd
series 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 is
the 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 and
rearrange 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 on
slide 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 slide
with `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 plac
presentation with no editor. Set it only on hand-out copies.
- If `template: true` is set, every open mints a fresh document (that's for
distributable 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 into
the 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.md
index 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 and
dormant 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.
## Workflow
diff --git a/scripts/test-layouts.ts b/scripts/test-layouts.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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