Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

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.yml
index 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, a
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 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 move
Every Bento file carries its whole runtime, so the packer's efficiency is a
diff --git a/kernel/src/returngate.ts b/kernel/src/returngate.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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)