Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// Language packs (docs/i18n-packs.md): fetching them, and carrying them in
// the file.
//
// A PACK LIVES IN THE FILE. Nowhere else.
//
// An earlier version of this also let a pack be installed into localStorage
// "on this computer". It was removed, because localStorage is scoped per
// ORIGIN and that is fatally misaligned with how Bento is actually used: the
// download comes from bento.page (an https origin), and the file is then
// opened from disk (a file:// origin). A language added on the website was
// therefore GONE the moment the user saved the deck and reopened it locally —
// the exact journey the product encourages. "I added Korean and it vanished"
// is not a bug a user can diagnose, and no amount of wording fixes it.
//
// Keeping one home also matches the rest of Bento: the file IS the software,
// so a language belongs to the deck. The trade is that adding a language
// requires saving the file — which the UI states plainly rather than hiding.
import { appConfig } from '../../kernel/src/app.ts'
import { addPack, removePack, type LanguagePack } from '../../kernel/src/i18n.ts'
import { readShellBlocks, type ShellBlock } from '../../kernel/src/save.ts'
import { fetchPinned, verifySigned } from '../../kernel/src/update.ts'
import { netFetch, sharedStorageOrigin } from '../../kernel/src/net.ts'
// Extension-explicit like the kernel imports above, so this module also loads
// under plain node — scripts/test-packs.ts exercises the real thing.
import { PACKED } from './i18n/packed.ts'
import { lsGet } from '../../kernel/src/storage.ts'
const DEFAULT_CHANNEL = 'https://bento.page/releases/slides'
/**
* Where the release channel publishes the pack index and the packs.
* Dev override: localStorage 'bento-packs-url' — the same convention the
* updater uses for 'bento-update-url', so a local channel can be pointed at
* without a rebuild. (A URL, not pack data: nothing durable lives here.)
* The override reads from the host: it is honoured only where storage is
* this document's own (kernel net.ts sharedStorageOrigin), never where every
* local document shares one.
*/
const channel = (): string =>
(sharedStorageOrigin() ? null : lsGet('bento-packs-url')) ?? DEFAULT_CHANNEL
export interface PackListing {
lang: string
label: string
/** absolute, or relative to the channel */
url: string
/** app version the pack was built against, for display */
version?: string
/** lowercase hex sha256 of the pack's bytes, PINNED by the signed index */
sha256: string
/** size of the pack, for display */
bytes?: number
}
export type PackError = 'offline' | 'bad-pack' | 'wrong-app' | 'unverified'
/**
* Locale codes that must resolve to a pack filed under a DIFFERENT code.
*
* The bundled catalogs already have this (the `alias` map in
* slides/src/i18n.ts: zh-CN → zh-Hans, pt-BR → pt); packs need it for the
* same reason. A pack's language code is what kernel `resolve()` matches
* navigator.language against — exactly, then by base language — so a pack
* filed under a code no browser reports is a pack nobody can ever be given.
*
* `tl` → `fil` is that case: ISO 639-1 has `tl` for Tagalog, but browsers,
* Android, iOS and macOS all report Filipino as `fil` / `fil-PH`. The pack is
* therefore filed as `fil`, and `tl` stays reachable here for any system that
* does report it (a Linux box with LANG=tl_PH) and for files saved carrying
* the pack under its old code.
*
* Registered WITHOUT a label, so an alias never shows as a second entry in
* the language picker.
*
* Both directions are listed on purpose: `fil: ['tl']` is the live case, and
* `tl: ['fil']` makes a file saved carrying the pack under its OLD code still
* answer the `fil-PH` that a browser actually reports.
*/
const ALIASES: Record<string, readonly string[]> = { fil: ['tl'], tl: ['fil'] }
/** Register a pack under its own code and under every alias of it. */
function register(pack: LanguagePack): boolean {
if (!addPack(pack, 'slides')) return false
for (const alias of ALIASES[pack.lang] ?? []) addPack({ ...pack, lang: alias, label: undefined }, 'slides')
return true
}
/** Undo `register` — the aliases go with the pack that created them. */
function unregister(lang: string): void {
for (const alias of ALIASES[lang] ?? []) removePack(alias)
removePack(lang)
}
/** The block type carrying a pack inside a saved shell. */
export const PACK_BLOCK_TYPE = 'application/bento+lang'
const blockId = (lang: string) => `bento-lang-${lang}`
/** Packs destined for the file: those already in it, plus any staged since. */
const inFile = new Map<string, LanguagePack>()
/** Which of those were NOT in the file as loaded — i.e. need a save. */
const pending = new Set<string>()
/**
* Read packs already embedded in this file and register them. Runs at boot
* from the i18n facade, before the first t(): a deck that arrives carrying
* Japanese must show Japanese immediately, offline, with nothing fetched.
*
* DELIBERATELY NOT RE-VERIFIED. A pack was verified when it was added
* (signed index, pinned hash — fetchIndex/fetchPack below); once spliced it
* is part of the file, carrying exactly the trust the document itself does.
* Anyone who can rewrite this block can rewrite the whole shell — including
* the code doing the checking — so a check here would buy nothing, while
* requiring the network at boot would break offline use, which is the
* product's core promise. Verification belongs at the door, not in the room.
*/
export function readPacksFromShell(): number {
let n = 0
for (const { body } of readShellBlocks(PACK_BLOCK_TYPE)) {
try {
const pack = JSON.parse(body) as LanguagePack
if (pack?.lang && pack.strings && register(pack)) {
inFile.set(pack.lang, pack)
n++
}
} catch {
// a corrupt block must not stop the app booting — skip it
}
}
return n
}
/**
* How much of the app's CURRENT interface a pack actually covers.
*
* Measured, not inferred from the version number. A pack built for an older
* release may still cover everything — if that release added no strings, the
* version differs and nothing is missing — while a same-version pack could be
* incomplete. What the reader cares about is how much English they will see,
* so count that directly. PACKED's keys are exactly the strings the running
* app asks for.
*/
export function packCoverage(pack: LanguagePack): { missing: number; total: number } {
const keys = Object.keys(PACKED)
let missing = 0
for (const k of keys) if (!pack.strings[k]) missing++
return { missing, total: keys.length }
}
/** Packs in the file, flagged if they are still waiting for a save. */
export function packsInFile(): Array<LanguagePack & { pending: boolean }> {
return [...inFile.values()].map((p) => ({ ...p, pending: pending.has(p.lang) }))
}
/**
* Download and validate a pack. Does not decide where it goes.
*
* The bytes are accepted only if they hash to the sha256 the SIGNED index
* pinned for this listing (kernel fetchPinned). So the chain is: our embedded
* release key signed the index, the index pins this pack — substituting a
* pack means breaking the hash, and fixing the hash means breaking the
* signature. A hash we cannot match is 'unverified' and the pack is refused
* outright; there is no path where unverified strings reach the UI.
*
* A network failure and a failed check are told apart on purpose: one is
* "try again later", the other is "something is wrong with that download",
* and telling a user to check their connection when they are being served a
* forged pack would be a lie.
*/
export async function fetchPack(listing: PackListing): Promise<LanguagePack | PackError> {
const url = /^https?:/.test(listing.url) ? listing.url : `${channel()}/${listing.url}`
if (!/^[0-9a-f]{64}$/i.test(listing.sha256 ?? '')) return 'unverified'
const bytes = await fetchPinned(url, listing.sha256)
if (!bytes) {
// fetchPinned refuses unreachable and unmatched alike — correct for it,
// useless for the sentence we have to show. One cheap HEAD on the FAILURE
// path only (the happy path stays a single download) separates "you are
// offline / it isn't published" from "those bytes are not the pack we
// were promised". Either way nothing unverified is returned.
try {
return (await netFetch(url, { cache: 'no-store', method: 'HEAD' })).ok ? 'unverified' : 'offline'
} catch {
return 'offline'
}
}
let pack: LanguagePack
try {
pack = JSON.parse(new TextDecoder().decode(bytes)) as LanguagePack
} catch {
return 'bad-pack'
}
if (!pack?.lang || !pack.strings || typeof pack.strings !== 'object') return 'bad-pack'
if (pack.app && pack.app !== 'slides') return 'wrong-app'
return pack
}
/**
* Put a pack in the file. Registers it immediately so the editor can use it
* right away; the FILE gains it on the next save.
*
* Staged rather than written-on-click because on every browser without File
* System Access "write" means silently downloading a second copy of the
* user's deck — a surprising thing to do to someone who asked for a language.
*/
export function stageForFile(pack: LanguagePack): boolean {
if (!pack?.lang || !pack.strings) return false
if (!register(pack)) return false
inFile.set(pack.lang, pack)
pending.add(pack.lang)
return true
}
/** Take a pack out of the file — also applied on the next save. */
export function unstageFromFile(lang: string): boolean {
if (!inFile.has(lang)) return false
inFile.delete(lang)
pending.add(lang)
unregister(lang)
return true
}
/** Everything staged has now been written — called after a successful save. */
export function markFileSaved(): void {
pending.clear()
}
/** The blocks the kernel writes into every saved shell. */
export function shellBlocksForPacks(): ShellBlock[] {
return [...inFile.values()].map((p) => ({
id: blockId(p.lang),
type: PACK_BLOCK_TYPE,
body: JSON.stringify(p),
attrs: { 'data-lang': p.lang },
}))
}
/**
* The channel's whole index, unfiltered. [] if unpublished, unreachable, or
* NOT PROPERLY SIGNED.
*
* The index is a signed envelope — `{payload, sig}`, ECDSA P-256 over the
* payload's bytes, verified against the release key already embedded in this
* shell (kernel verifySigned). It is the whole trust anchor for packs: every
* listing pins its pack's sha256, so signing the index signs the hashes, and
* a fetched pack is checked against its pinned hash. Same shape as the update
* manifest, same key, no second trust root.
*
* FAIL CLOSED, no legacy path. An unsigned or badly signed index yields NO
* listings — the Languages dialog then says there is nothing to add, which is
* exactly right: an index we cannot authenticate is an index we know nothing
* about. Nothing is published yet, so there is no unsigned index in the world
* to be compatible with, and adding a permissive fallback would mean anyone
* who can answer for the channel picks the strings in your UI.
*
* Payload shape, produced by scripts/sign-packs.mjs (spec in
* docs/i18n-packs.md §"Signing and release"):
*
* { app: 'bento-slides', version, at, packs: [ { lang, label, version,
* url, sha256, bytes } ] }
*
* `app` is checked exactly as the release manifest's is: the signing key is
* platform-wide, so the id is what stops a validly-signed bento/spaces index
* being served to bento/slides. `url` is relative to the channel unless
* absolute, so a dev channel serves its OWN packs instead of quietly reaching
* back to bento.page.
*/
async function fetchIndex(): Promise<PackListing[]> {
try {
const res = await netFetch(`${channel()}/packs.json`, { cache: 'no-store' })
if (!res.ok) return []
const payload = (await verifySigned(await res.text(), 'language pack index')) as {
app?: unknown
packs?: unknown
}
if (!payload || typeof payload !== 'object') return []
if (payload.app !== appConfig().appId) return []
if (!Array.isArray(payload.packs)) return []
// A listing with no usable pin can never be verified, so it can never be
// offered — drop it here rather than let it fail later at the Add button.
return (payload.packs as PackListing[]).filter(
(p) => p?.lang && p?.url && /^[0-9a-f]{64}$/i.test(p?.sha256 ?? ''),
)
} catch {
return []
}
}
/**
* Packs on offer from the release channel, minus those the file already has.
* "Nothing to offer" is a normal state, not an error worth shouting about.
*/
export async function availablePacks(): Promise<PackListing[]> {
return (await fetchIndex()).filter((p) => !inFile.has(p.lang))
}
/**
* Bring this file's packs up to a new app version, called from the update
* flow once the release is verified.
*
* WHY THIS EXISTS. A pack is written into the file at the version it was
* built for and then never changes, while the app around it keeps updating.
* Every release that adds UI strings makes that pack a little more
* incomplete — the new strings fall back to English, per string, silently.
* Over a few releases a fully translated deck drifts back toward English
* with nothing to fix it. Update is the one moment we know the version
* changed, and the packs are on the same signed channel, so it is also the
* cheapest moment to put them right.
*
* Refusing to fail is the whole point: any pack we cannot re-fetch is simply
* KEPT at its current version. Degraded beats absent.
*
* That includes a pack that fails VERIFICATION — an unsigned index, or bytes
* that don't match their pinned hash. Keeping is not laxity: the pack already
* in the file was verified when it was added and has been travelling with the
* document ever since, so it is strictly the more trustworthy of the two. The
* new bytes are refused; the old ones stay. What must never happen — and does
* not — is an unverified pack being written into the file by the update flow.
*/
export async function refreshPacksForVersion(version: string): Promise<{ refreshed: string[]; kept: string[] }> {
const refreshed: string[] = []
const kept: string[] = []
const langs = [...inFile.keys()]
if (!langs.length) return { refreshed, kept }
const index = await fetchIndex()
for (const lang of langs) {
const listing = index.find((p) => p.lang === lang)
if (!listing) { kept.push(lang); continue }
const got = await fetchPack(listing)
if (typeof got === 'string' || got.lang !== lang) { kept.push(lang); continue }
// Only replace with something actually built for the incoming version —
// a channel still serving the old pack should leave the file untouched.
if (got.version && version && got.version !== version) { kept.push(lang); continue }
inFile.set(lang, got)
register(got)
refreshed.push(lang)
}
return { refreshed, kept }
}