Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
The web demo can tell a returning visitor where their deck went (#342)
nyblnet4557df96993a
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 06b511f0..c1b453ab 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -228,6 +228,15 @@ jobs:# file carrying a script tag.run: node scripts/test-preview.ts+ - name: Return-gate rig+ # The web demo always starts fresh, so someone who saved from+ # bento.page and came back saw a blank starter and read it as lost+ # work. The gate that fixes it can be worse than the silence it+ # replaces: firing over a real document, or offering a host that has no+ # release (telling an Android user to install a Chrome extension). This+ # pins both, and that the mobile rows degrade until those hosts ship.+ run: node scripts/test-return-gate.ts+- name: Offline-mode rig# Offline mode promises "nothing leaves this computer" and was broken# five ways at once (GHSA-5c3x-xqp6-g94r): a manual update check, adiff --git a/docs/DECISIONS.md b/docs/DECISIONS.mdindex 51be409e..b3aeaf08 100644--- a/docs/DECISIONS.md+++ b/docs/DECISIONS.md@@ -14,6 +14,52 @@ Decision. Why. Pointers.---+## 2026-08-23 — The web demo gates on RETURN, not on save++Someone works at `https://bento.page/slides/`, saves, comes back later and gets+a fresh starter, because a never-saved deck stays dormant by design. It reads+as lost work. It is not — the file is on disk — but nothing on screen says so,+and two things genuinely do not survive: version history and recovery live in+IndexedDB keyed to the `bento.page` ORIGIN and do not follow the file to+`file://`, and neither does the session.++**Blocking straight after the save was considered and rejected.** Once an FSA+handle exists the editor silently rewrites the real file every 2.5s+(`writeUpdatedFile`), so that tab is a working session writing to disk on every+edit; interrupting it would sever something that is functioning and lose+whatever was typed since the last write. The confusion happens on the NEXT+visit, so that is where the gate goes. **"Start a new deck anyway" is always+present** — some visitors do want a fresh one, and some cannot install+anything.++**Availability gating is required from day one, not added later.** The offer is+`hasFsAccess()` × `hostCan('write')` × *which host actually has a release*.+Hardcoding "install the extension" would tell an Android user to install a+Chrome extension. `HOST_AVAILABLE` in `kernel/src/returngate.ts` carries that,+and `scripts/test-return-gate.ts` pins both states — that the mobile rows say+"keep the file" today, and that they become real offers the day the flag flips,+so the flag is wired rather than decorative.++**Capability decides what to SAY; the platform guess decides only which LINK.**+`hasFsAccess()` is a real feature test, UA sniffing is a guess. A browser that+gains the API is handled correctly on the day it ships with no change here. For+Safari/Firefox desktop the honest answer is a different browser, not a pitch+for an extension that cannot help them.++State is viewer-scoped `localStorage`, never in the document — the same rule+locale, theme and reduced motion follow. A deck carrying it would tell everyone+you sent it to that you had once saved something.++In `kernel/`, not `slides/`: Spaces, Dash and Type have the identical problem+and would each grow their own copy. The kernel owns the remembering and the+policy; the words and the markup are the app's. Spec (gitignored):+`working/handover-web-demo-return-gate.md`, from the `tray-views` session.++NOT done here, and worth weighing first: making **Download** the primary action+on the landing page (it is currently `btn primary` on "Try it in your browser")+would avoid the situation for most people and costs nothing. That is a site+change, not an app one.+## 2026-08-19 — The shells are packed with zopfli, and the format does not moveEvery Bento file carries its whole runtime, so the packer's efficiency is adiff --git a/kernel/src/returngate.ts b/kernel/src/returngate.tsnew file mode 100644index 00000000..ee12543e--- /dev/null+++ b/kernel/src/returngate.ts@@ -0,0 +1,148 @@+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 The Bento authors+//+// "You saved a deck from here before" — the state and the policy behind it.+//+// WHY THIS EXISTS. Someone opens https://bento.page/slides/, works, saves. The+// file lands on disk correctly. They come back to the same URL later and get a+// FRESH STARTER, because a never-saved deck stays dormant by design. It reads+// as lost work. It is not — but nothing on screen says so, and two things+// genuinely do not survive the round trip: version history and recovery live in+// IndexedDB keyed to the bento.page ORIGIN and do not follow the file to+// file://, and the session does not either.+//+// THE GATE IS ON RETURN, NOT ON SAVE. Blocking straight after the save was the+// first instinct and is wrong: once an FSA handle exists the editor silently+// rewrites the real file every 2.5s (save.ts writeUpdatedFile), so that tab is+// a working session writing to disk on every edit. Interrupting it would sever+// something that is functioning and lose whatever was typed since the last+// write. The confusion happens on the NEXT VISIT, so that is where the gate+// goes.+//+// WHAT LIVES HERE: the remembering, and the decision about what to offer.+// NOT the words and not the markup — those are the app's, because each app+// says it differently. Spaces, Dash and Type have the identical problem, and+// built app-side each would grow its own copy of this.+//+// The policy function is PURE and takes its inputs as arguments rather than+// reaching for save.ts, so it can be tested without a DOM and cannot drift+// from what the caller actually observed.++import { lsDel, lsGet, lsSet } from './storage.ts'++/** localStorage, viewer-scoped — the same rule locale, theme and reduced+ * motion already follow. This NEVER goes in the document: it is a fact about+ * this browser, not about the deck, and a deck that carried it would tell+ * everyone you sent it to that YOU once saved something. */+const KEY = 'bento-saved-here'++/**+ * Remember that a save happened from this origin, and under what name, so the+ * next visit can say which file to open. Deliberately stores ONLY the name:+ * no doc id, no path (a page cannot know a path), nothing that identifies the+ * document's contents.+ */+export const noteSavedHere = (fileName: string): void => {+ if (fileName) lsSet(KEY, fileName)+}++/** The last file name saved from this origin, or null. */+export const savedHere = (): string | null => lsGet(KEY)++/** Forget it — for "start a new deck anyway", so the gate does not re-nag. */+export const clearSavedHere = (): void => lsDel(KEY)++/**+ * Is this a page served over the web, rather than the user's own file?+ *+ * The gate is meaningless on file:// — there the reader IS looking at their+ * saved deck, which is the thing the gate would be telling them to open.+ */+export const isWebOrigin = (): boolean => {+ try {+ return /^https?:$/.test(location.protocol)+ } catch {+ return false+ }+}++/**+ * Which hosts a reader could actually install TODAY.+ *+ * Availability gating is required from day one rather than added later:+ * hardcoding "install the extension" would tell an Android user to install a+ * Chrome extension. Flip these as each host gets a release — that is the whole+ * maintenance burden of the mobile rows.+ */+export const HOST_AVAILABLE = {+ desktopExtension: true,+ ios: false, // tray/ios — PR open, no release+ android: false, // tray/android — on main via #87, no release+} as const++export type Platform = 'desktop' | 'ios' | 'android' | 'unknown'++export type Offer =+ /** Everything already works. Say nothing at all. */+ | { kind: 'silent' }+ /** Chrome/Edge desktop with no host: the extension is a real upgrade. */+ | { kind: 'extension' }+ /** An installable app exists for this platform. */+ | { kind: 'app'; platform: 'ios' | 'android' }+ /** No FSA and no host to fix it: keep the file wherever the OS puts files. */+ | { kind: 'keep-file'; platform: Platform }+ /** Desktop browser with no File System Access at all. No host helps. */+ | { kind: 'use-chromium' }++/**+ * What to offer, given what was OBSERVED rather than guessed.+ *+ * `fsAccess` is a real feature test (save.ts hasFsAccess / canWriteInPlace);+ * `platform` is a guess from the user agent. Where they disagree the+ * capability decides WHAT TO SAY and the platform decides only WHICH LINK —+ * so a browser that gains File System Access tomorrow is handled correctly by+ * this function on the day it ships, with no change here.+ */+export function offerFor(env: {+ fsAccess: boolean+ canWrite: boolean+ platform: Platform+}): Offer {+ // A host is already writing the file in place. Nothing to sell, nothing to+ // warn about: this is the case the whole feature is trying to reach.+ if (env.canWrite) return { kind: 'silent' }++ // The browser can write in place but nothing is holding a handle across+ // sessions — the extension is exactly the missing piece.+ if (env.fsAccess) {+ return HOST_AVAILABLE.desktopExtension ? { kind: 'extension' } : { kind: 'keep-file', platform: env.platform }+ }++ // From here down the browser has no File System Access at all.+ if (env.platform === 'ios') {+ return HOST_AVAILABLE.ios ? { kind: 'app', platform: 'ios' } : { kind: 'keep-file', platform: 'ios' }+ }+ if (env.platform === 'android') {+ return HOST_AVAILABLE.android ? { kind: 'app', platform: 'android' } : { kind: 'keep-file', platform: 'android' }+ }+ // Safari or Firefox on a desktop. No extension will help — saying "install+ // our extension" here would be a lie, and the honest answer is a browser+ // that implements the API.+ if (env.platform === 'desktop') return { kind: 'use-chromium' }+ return { kind: 'keep-file', platform: env.platform }+}++/**+ * Should the returning-visitor gate be shown?+ *+ * `docIsFresh` is the app's to decide — only the app knows whether what it just+ * loaded is its own starter or a real document — and it is the input that stops+ * the gate appearing over someone's actual work.+ */+export function shouldGateOnReturn(state: {+ webOrigin: boolean+ savedName: string | null+ docIsFresh: boolean+}): boolean {+ return state.webOrigin && !!state.savedName && state.docIsFresh+}diff --git a/scripts/test-return-gate.ts b/scripts/test-return-gate.tsnew file mode 100644index 00000000..1ed4fc03--- /dev/null+++ b/scripts/test-return-gate.ts@@ -0,0 +1,111 @@+#!/usr/bin/env node+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 The Bento authors+// Return-gate rig.+//+// node scripts/test-return-gate.ts+//+// WHAT THIS PROVES. The gate exists to stop a returning visitor thinking they+// lost work. Every way it can go wrong is a way of being WORSE than the silent+// blank starter it replaces:+//+// 1. Firing over a real document. The gate says "this page always starts+// fresh" — over someone's actual deck that is false, and alarming.+// 2. Offering a host that does not exist. Hardcoding "install the extension"+// tells an Android user to install a Chrome extension. The mobile rows+// must degrade to "keep the file" until those hosts ship, and this rig is+// what keeps that true as HOST_AVAILABLE flips.+// 3. Nagging where nothing is wrong. A reader whose host already writes the+// file in place must hear nothing at all.+// 4. Selling an extension to a browser no extension can help. Safari and+// Firefox on the desktop have no File System Access; the honest answer is+// a different browser, not a pitch.+// 5. Recording it in the DOCUMENT. It is a fact about this browser. A deck+// carrying it would tell everyone you send it to that you once saved.++let failures = 0+let checks = 0+const ok = (cond: boolean, msg: string) => {+ checks+++ if (!cond) { failures++; console.log(` FAIL ${msg}`) } else console.log(` ok ${msg}`)+}++const store = new Map<string, string>()+let storageWorks = true+;(globalThis as any).localStorage = {+ getItem: (k: string) => { if (!storageWorks) throw new Error('blocked'); return store.get(k) ?? null },+ setItem: (k: string, v: string) => { if (!storageWorks) throw new Error('blocked'); store.set(k, v) },+ removeItem: (k: string) => { if (!storageWorks) throw new Error('blocked'); store.delete(k) },+}+;(globalThis as any).location = { protocol: 'https:' }++const g = await import('../kernel/src/returngate.ts')++// ---- 1. remembering -------------------------------------------------------+ok(g.savedHere() === null, 'a browser that has never saved from here remembers nothing')+g.noteSavedHere('Q3 review.bento.html')+ok(g.savedHere() === 'Q3 review.bento.html', 'a save is remembered, with the name to open')+g.clearSavedHere()+ok(g.savedHere() === null, '"start a new deck anyway" clears it, so the gate does not re-nag')+ok(typeof (g as any).stampIntoDoc === 'undefined',+ 'there is no way to write this into a document — viewer-scoped by construction')++storageWorks = false+let threw = false+try { g.noteSavedHere('x.bento.html'); void g.savedHere(); g.clearSavedHere() } catch { threw = true }+ok(!threw, 'blocked site data degrades to no gate rather than throwing')+storageWorks = true+store.clear()++// ---- 2. where it applies --------------------------------------------------+ok(g.isWebOrigin() === true, 'https is a web origin')+;(globalThis as any).location = { protocol: 'file:' }+ok(g.isWebOrigin() === false, 'file:// is not — there the reader IS looking at their saved deck')+;(globalThis as any).location = { protocol: 'https:' }++// ---- 3. the gate fires only where it is true ------------------------------+const gate = (webOrigin: boolean, savedName: string | null, docIsFresh: boolean) =>+ g.shouldGateOnReturn({ webOrigin, savedName, docIsFresh })+ok(gate(true, 'deck.bento.html', true), 'returning visitor on the web with a fresh starter: gate')+ok(!gate(true, 'deck.bento.html', false),+ 'NOT over a real document — "this page always starts fresh" would be false and alarming')+ok(!gate(true, null, true), 'not for a first-time visitor who has saved nothing')+ok(!gate(false, 'deck.bento.html', true), 'not on file://, where the file is already open')++// ---- 4. the offer matrix --------------------------------------------------+const offer = (fsAccess: boolean, canWrite: boolean, platform: any) =>+ g.offerFor({ fsAccess, canWrite, platform })+ok(offer(true, true, 'desktop').kind === 'silent',+ 'a host already writing in place is told NOTHING — that is the destination, not a problem')+ok(offer(true, false, 'desktop').kind === 'extension',+ 'Chrome/Edge desktop with no host: the extension is the missing piece')+ok(offer(false, false, 'desktop').kind === 'use-chromium',+ 'Safari/Firefox desktop: no extension can help, so it does not pretend one can')++ok(g.HOST_AVAILABLE.ios === false && g.HOST_AVAILABLE.android === false,+ 'the mobile hosts are still marked unreleased (flip these when they ship)')+const ios = offer(false, false, 'ios')+const android = offer(false, false, 'android')+ok(ios.kind === 'keep-file' && (ios as any).platform === 'ios',+ 'iOS is told to keep the file, NOT to install an app that has no release')+ok(android.kind === 'keep-file' && (android as any).platform === 'android',+ 'Android likewise — and never "install the extension", which is a Chrome extension')++{+ const AVAIL = g.HOST_AVAILABLE as any+ const restore = AVAIL.ios+ AVAIL.ios = true+ const shipped = offer(false, false, 'ios')+ ok(shipped.kind === 'app' && (shipped as any).platform === 'ios',+ 'and it becomes a real offer the day that host ships — the flag is wired, not decorative')+ AVAIL.ios = restore+ ok(offer(false, false, 'ios').kind === 'keep-file', 'and reverts when the flag goes back')+}++ok(offer(true, false, 'unknown').kind === 'extension',+ 'an unrecognised platform that CAN write in place is still offered the extension')+ok(offer(false, false, 'unknown').kind === 'keep-file',+ 'an unrecognised platform that cannot is given the answer that is true everywhere')++console.log(`\n${checks - failures}/${checks} checks passed`)+if (failures) process.exit(1)