Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

Gallery templates carry the typeface they ask for (#201)

nyblneta188ef29cc2f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e3b65f0..ad9387cf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,17 @@ pre-1.0.
## [Unreleased]
+- **Fix: two gallery templates asked for a typeface they did not carry.** The
+ Orbital and Pixel Picnic templates set their text in Instrument Sans but
+ embedded no font at all, so every viewer without that typeface installed
+ silently got Helvetica Neue instead. They now carry the face — and only the
+ face they use, rather than every font the gallery has.
+
+ `validate()` gained the check that finds this class of bug (`font-not-embedded`).
+ It is worth having precisely because the failure is invisible to whoever made
+ the deck: they are the person most likely to have the typeface installed, so
+ it looks correct on the one machine that cannot detect the problem.
+
- **Pan the canvas by dragging, and past the slide's edges.** The scrollbars
were the only way to move a zoomed slide, which puts the control at the edge
of the screen while the work is in the middle of it. **Hold space and drag**
diff --git a/docs/agents.md b/docs/agents.md
index ecbe7693..d2308d68 100644
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -374,8 +374,11 @@ without them — and elements should carry the full field set shown.
- 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:
+ silently** to the next entry in the stack — there is no warning, and worse,
+ it will usually look right to *you*, because you are the one with the
+ typeface installed. Everyone else gets the fallback. `validate()` reports
+ this (`font-not-embedded`) precisely because you cannot see it locally.
+ 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
diff --git a/scripts/build-example-decks.mjs b/scripts/build-example-decks.mjs
index cc95969e..f2cc0214 100644
--- a/scripts/build-example-decks.mjs
+++ b/scripts/build-example-decks.mjs
@@ -134,11 +134,38 @@ const drift = (ax, ay, fx, fy, px = 0, py = 0) => {
return `M0,0 L${pts.slice(1).join(' L')} Z`
}
+/**
+ * The gallery faces a deck actually needs.
+ *
+ * `withFonts: true` takes every face; a LIST takes only the families named, so
+ * a deck that sets one typeface does not ship the bytes of another. Same rule
+ * the clipboard follows — carry exactly the faces in use.
+ *
+ * A face a deck NAMES but does not carry falls back silently: the text simply
+ * renders in the next entry of the stack, with no warning anywhere. Orbital and
+ * Picnic did that with Instrument Sans until 2026-08-02, which is why they now
+ * name what they need instead of relying on an all-or-nothing flag.
+ */
+const fontsFor = (want) => {
+ const families = want === true ? FONTS.fonts.map((f) => f.family) : want
+ const picked = FONTS.fonts.filter((f) => families.includes(f.family))
+ const missing = families.filter((fam) => !FONTS.fonts.some((f) => f.family === fam))
+ if (missing.length) throw new Error(`withFonts names unknown families: ${missing.join(', ')}`)
+ return {
+ fonts: picked,
+ assets: Object.fromEntries(picked.map((f) => [f.asset, FONTS.assets[f.asset]])),
+ }
+}
+
const doc = (o) => ({
format: 'bento/slides', version: 1, title: o.title,
size: { width: 1280, height: 720 },
theme: o.theme, template: true,
- ...(o.withFonts ? { assets: { ...FONTS.assets, ...(o.assets ?? {}) }, fonts: [...FONTS.fonts, ...(o.fonts ?? [])] }
+ ...(o.withFonts
+ ? (() => {
+ const f = fontsFor(o.withFonts)
+ return { assets: { ...f.assets, ...(o.assets ?? {}) }, fonts: [...f.fonts, ...(o.fonts ?? [])] }
+ })()
: (o.assets ? { assets: o.assets, ...(o.fonts ? { fonts: o.fonts } : {}) } : {})),
...(o.present ? { present: o.present } : {}),
slides: o.slides, modified: new Date().toISOString(),
@@ -580,7 +607,7 @@ function deckOrbital() {
})
return doc({
- title: 'Orbital — dark immersive template',
+ title: 'Orbital — dark immersive template', withFonts: ['Instrument Sans'],
assets: {
'ph-stars': photo('orbital-stars.jpg'),
'ph-cubesats': photo('orbital-cubesats.jpg'), 'ph-jwst': photo('orbital-jwst.jpg'),
@@ -708,7 +735,7 @@ function deckPicnic() {
})
return doc({
- title: 'Pixel Picnic — playful template',
+ title: 'Pixel Picnic — playful template', withFonts: ['Instrument Sans'],
assets: { 'ph-fair': photo('picnic-fair.jpg'), 'ph-fairwide': photo('picnic-fairwide.jpg') },
theme: { background: SUN, color: INK, accent: GUM, fontFamily: IN },
slides: [s1, s2, s3, s3b, s4, s5],
diff --git a/scripts/test-validate.ts b/scripts/test-validate.ts
index 7ebc45f6..43ee7931 100644
--- a/scripts/test-validate.ts
+++ b/scripts/test-validate.ts
@@ -42,6 +42,8 @@ ok(!starter.findings.some((f) => f.code === 'unknown-key'),
'the starter deck has no unknown keys — the generated key tables match the format it is written in')
ok(!starter.findings.some((f) => f.code === 'chart-key-ignored'),
'the starter deck has no dead chart options')
+ok(!starter.findings.some((f) => f.code === 'font-not-embedded'),
+ 'the starter deck carries every typeface it names')
ok(!starter.findings.some((f) => f.code === 'overridden-enter-fx'),
'the starter deck has no entrance animations the morph would override')
ok(starter.measured === false, 'measured is false without a DOM rather than silently skipping')
@@ -134,6 +136,32 @@ ok(!r.findings.some((f) => f.code === 'overridden-enter-fx' && f.element === 'fr
ok(r.findings.some((f) => f.code === 'overridden-enter-fx' && f.element === 'dup'),
'an entrance on an element that morphs in IS reported')
+// ------------------------------------------------- fonts named but not carried
+// The failure mode is invisible to whoever authored the deck, because they are
+// exactly the person with the typeface installed. Two gallery templates shipped
+// naming Instrument Sans and carrying nothing; on this machine they LOOKED
+// right. Only the document can be checked, never the local font list.
+const fontDoc = (fontFamily: string, fonts: unknown = null): BentoDoc => ({
+ ...clean, fonts,
+ theme: { accent: '#F7A600', fontFamily },
+} as any)
+const named = (d: BentoDoc) => validateDoc(d, { measure: false })
+ .findings.filter((f) => f.code === 'font-not-embedded')
+
+ok(named(fontDoc("'Instrument Sans', 'Helvetica Neue', sans-serif")).length === 1,
+ 'a face named but not carried is reported')
+ok(named(fontDoc("'Instrument Sans', sans-serif",
+ [{ family: 'Instrument Sans', asset: 'font-instrument', weight: '100 900' }])).length === 0,
+ 'the same face IS carried → no finding')
+for (const stack of [
+ 'system-ui, sans-serif',
+ "'Helvetica Neue', Arial, sans-serif",
+ 'Georgia, serif',
+ "ui-monospace, 'SF Mono', Menlo, monospace",
+]) {
+ ok(named(fontDoc(stack)).length === 0, `a system stack is not reported (${stack.split(',')[0]})`)
+}
+
// ------------------------------------------------- chart false-positive guard
// The shape the starter deck's own charts use. Every key here IS implemented,
// so any finding is the validator lying about working configuration.
diff --git a/slides/src/validate.ts b/slides/src/validate.ts
index f55caea1..4053a5d1 100644
--- a/slides/src/validate.ts
+++ b/slides/src/validate.ts
@@ -79,6 +79,35 @@ const CHART_KEYS = {
legend: ['show', 'top', 'bottom', 'textStyle', 'itemWidth', 'itemHeight', 'itemGap', 'data'],
}
+/**
+ * Families a viewer's machine can be expected to resolve without the document
+ * carrying the bytes — generics, the CSS system keywords, and the faces that
+ * ship with mainstream desktop operating systems.
+ *
+ * Anything else named FIRST in a stack, and not in `doc.fonts`, is a face the
+ * document is asking for and does not have. On the author's machine that
+ * usually looks fine, because the author is exactly the person who has the
+ * typeface installed; everyone else silently gets the next entry in the stack.
+ * Two gallery templates shipped that way for months.
+ */
+const SYSTEM_FAMILIES = new Set([
+ 'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy', 'system-ui',
+ 'ui-serif', 'ui-sans-serif', 'ui-monospace', 'ui-rounded',
+ '-apple-system', 'blinkmacsystemfont', 'segoe ui', 'roboto', 'helvetica',
+ 'helvetica neue', 'arial', 'arial black', 'verdana', 'tahoma', 'trebuchet ms',
+ 'georgia', 'times', 'times new roman', 'palatino', 'garamond', 'book antiqua',
+ 'courier', 'courier new', 'menlo', 'monaco', 'consolas', 'sf mono',
+ 'liberation mono', 'lucida console', 'impact', 'comic sans ms', 'cambria',
+ 'calibri', 'candara', 'optima', 'futura', 'gill sans', 'avenir', 'avenir next',
+ 'noto sans', 'noto serif', 'dejavu sans', 'pt sans', 'pt serif', 'emoji',
+])
+
+/** The first family in a CSS font stack, unquoted and lowercased. */
+function firstFamily(stack: string): string {
+ const first = stack.split(',')[0]?.trim() ?? ''
+ return first.replace(/^['"]|['"]$/g, '').trim().toLowerCase()
+}
+
const morphKey = (el: SlideElement) => el.morphId || el.id
/**
@@ -123,6 +152,19 @@ export function validateDoc(doc: BentoDoc, opts: ValidateOpts = {}): ValidateRes
message: `Font "${f.family}" points at asset "${f.asset}", which is not in doc.assets — the face will not load and text falls back silently.` })
}
}
+ const embedded = new Set((doc.fonts ?? []).map((f) => f.family.trim().toLowerCase()))
+ const seenFallback = new Set<string>()
+ const checkFamily = (stack: string | undefined, where: Omit<Finding, 'code' | 'severity' | 'message'>) => {
+ if (!stack) return
+ const fam = firstFamily(stack)
+ if (!fam || embedded.has(fam) || SYSTEM_FAMILIES.has(fam)) return
+ // one finding per family — a deck sets the same stack on 40 elements
+ if (seenFallback.has(fam)) return
+ seenFallback.add(fam)
+ add({ ...where, code: 'font-not-embedded', severity: 'info',
+ message: `"${stack.split(',')[0].trim()}" is not in doc.fonts, so it renders only for viewers who happen to have it installed — everyone else silently gets the next family in the stack. Embed the woff2 in doc.assets and declare it in doc.fonts.` })
+ }
+ checkFamily(doc.theme?.fontFamily, { path: 'theme.fontFamily' })
for (const slide of doc.slides) {
const sid = slide.id
@@ -249,6 +291,8 @@ export function validateDoc(doc: BentoDoc, opts: ValidateOpts = {}): ValidateRes
}
}
+ if (el.type === 'text') checkFamily((el as TextElement).fontFamily, at)
+
// charts ---------------------------------------------------------------
if (el.type === 'chart' && el.option) validateChart(el.option as any, at, add)
}