Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

57.2 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// Self-saving: a Bento file writes itself back to disk with updated data.
//
// At boot (before the app mutates the DOM) we deep-clone the document. On save
// we swap the clone's data block content for the current model JSON and
// serialize the clone back to an HTML string — byte-for-byte the same app
// shell, new document inside. TiddlyWiki pioneered this trick.

import type { KernelDoc } from './doc.ts'
import { appConfig } from './app.ts'
import { sharedStorageOrigin } from './net.ts'

const DATA_BLOCK_ID = 'bento-doc'
// Split so the literal never appears in the bundle (it would terminate the
// inline <script> that carries this very code inside a built Bento file).
const SCRIPT_CLOSE = '</scr' + 'ipt>'

/**
 * DOM the runtime injects at boot and that must NEVER reach a saved file.
 *
 * capturePristine() clones the live document, and the compressed shell's
 * loader has already inflated the app stylesheet into a <style> by then (see
 * scripts/postbuild-compress.mjs). Serializing the clone as-is wrote that
 * ~100KB of CSS back as PLAINTEXT — and the next boot inflated the payload and
 * appended another copy, so every save grew the file by another 100KB, forever.
 * The CSS ships deflated in the #bento-rt-css payload for a reason; the saved
 * file must carry it exactly once, compressed.
 *
 * So: anything injected before the pristine capture carries this attribute and
 * is stripped from every serialized shell. The kernel does not care what the
 * node is — only that the app declared it runtime-owned.
 */
const TRANSIENT_SELECTOR = '[data-bento-transient]'

let pristine: Document | null = null

/** Call first thing at boot, before any DOM mutation. */
export function capturePristine() {
  pristine = document.cloneNode(true) as Document
  if (typeof __BENTO_TEST_SEAL__ !== 'undefined' && __BENTO_TEST_SEAL__) consumeTestSeal()
  announceSeal() // boot: the host learns the starting state before anything else happens
}

/**
 * TEST BUILDS ONLY (security §31): the sealed TEST document's key handoff.
 * Phase 1 has no real path that seals a document at boot (the per-recipient
 * wraps are phase 2), yet all four apps' plaintext-to-disk guards must be
 * exercised end to end against an identity-sealed document. A rig installs a
 * one-shot global with the raw document key before the page loads (Playwright
 * addInitScript, scripts/lib/sealed-boot.mjs). Every app calls capturePristine()
 * at boot before its editor exists, so the seal is in place before any autosave
 * can start: the §E.2 ordering invariant, by construction.
 *
 * NEVER in a release shell. In phase 1 nobody holds a wrap for such a body, so a
 * stray global (an extension, a host user script, a future bug) would seal a
 * person's file to a key no one can recover. Each app's vite config defines
 * __BENTO_TEST_SEAL__ false unless BENTO_TEST_SEAL=1, the minifier drops this
 * branch, and the release conformance gate (shell-gate.mjs) refuses any shell
 * containing the global's name.
 */
declare const __BENTO_TEST_SEAL__: boolean | undefined
function consumeTestSeal() {
  const g = globalThis as { __bentoTestSeal?: unknown; __bentoTestSealProbe?: unknown }
  const key = g.__bentoTestSeal
  delete g.__bentoTestSeal
  if (!(key instanceof Uint8Array)) return
  setIdentitySeal(key)
  // What the rigs read back: did the seal take, and what would a save write?
  // (Its name carries the same mark, so the gate refuses it in a release too.)
  g.__bentoTestSealProbe = Object.freeze({
    sealed: () => isBodySealed(),
    body: (doc: KernelDoc) => encodeDocBody(doc),
    file: (doc: KernelDoc) => serializeAuto(doc),
    fileName: (doc: KernelDoc) => suggestedFileName(doc),
    storeRefusals: () => storeRefusalCount(),
  })
}

export function readEmbeddedDoc(): string | null {
  const block = document.getElementById(DATA_BLOCK_ID)
  const text = block?.textContent?.trim()
  return text || null
}

/**
 * The `#bento-doc` body from an HTML string — the file as bytes, not the live
 * DOM — so a handle's current file can be checked against the open document
 * without a parser (it runs in the launch consumer AND in a node rig). This proves
 * SAME DOCUMENT (an identical #bento-doc body), NOT same file: a copy re-saved with
 * a different surrounding shell still matches, which is exactly what the launch
 * check wants. Anchored by indexOf on the exact id attribute — double-quoted as the
 * DOM serializes it, with a LEADING SPACE so it can never match a `data-id`
 * lookalike — which is linear, where a regex over an unterminated `<script` is
 * quadratic. CRLF is normalised so a file saved with CRLF line endings still
 * compares equal. The body is <-escaped at write time so it can never itself
 * contain the close tag. Returns '' for a present-but-EMPTY block (a pristine
 * New shell), and null only when there is NO readable block at all — the two are
 * different documents, and the launch adopter (consumeLaunchQueue) must tell a
 * pristine shell from a non-Bento file. (readEmbeddedDoc deliberately still
 * collapses both to null — dash's boot dispatcher depends on that; this is the
 * string-level extractor, where '' vs null is meaningful.) */
const DOC_BLOCK_ID_ATTR = ` id="${DATA_BLOCK_ID}"`
export function embeddedDocBlock(html: string): string | null {
  const at = html.indexOf(DOC_BLOCK_ID_ATTR)
  if (at < 0) return null
  const start = html.indexOf('>', at + DOC_BLOCK_ID_ATTR.length)
  if (start < 0) return null
  const end = html.indexOf(SCRIPT_CLOSE, start + 1)
  if (end < 0) return null
  return html.slice(start + 1, end).replace(/\r\n/g, '\n').trim()
}

/**
 * Extra plaintext blocks the app wants written into every saved shell —
 * language packs today (docs/i18n-packs.md), whatever else later. The kernel
 * stays ignorant of what they mean: it is told an id, a type and a JSON body,
 * and guarantees only that they survive a save the same way #bento-doc does.
 *
 * The full set is re-declared on every serialize, so dropping one from the
 * list removes it from the next saved file — that is how "remove from this
 * file" works without a second API.
 */
export interface ShellBlock {
  id: string
  type: string
  /** JSON text; `<` is escaped on write exactly as the doc block's is */
  body: string
  attrs?: Record<string, string>
}
let shellBlocks: () => ShellBlock[] = () => []
let managedTypes: string[] = []

/**
 * Register the provider consulted on every serialize, and the block types it
 * OWNS. Call once, at boot.
 *
 * The types are declared rather than inferred from what the provider returns,
 * because the empty list is meaningful: "this file should carry no language
 * pack" has to clear the blocks the file arrived with, and a set derived from
 * the blocks about to be written would be empty exactly then — leaving the
 * last removed pack in the file (it would come back on the next open).
 */
export function registerShellBlocks(fn: () => ShellBlock[], types: string[]): void {
  shellBlocks = fn
  managedTypes = types
}

/** Every extra block currently in THIS document (as loaded from disk). */
export function readShellBlocks(type: string): Array<{ id: string; body: string; el: Element }> {
  return Array.from(document.querySelectorAll(`script[type="${type}"]`)).map((el) => ({
    id: el.id,
    body: (el.textContent ?? '').trim(),
    el,
  }))
}

/** Serialize a raw data-block body into an app shell. */
function serializeBody(shell: Document, body: string, doc: KernelDoc): string {
  const clone = shell.cloneNode(true) as Document

  // Runtime-injected DOM is not part of the shell (see TRANSIENT_SELECTOR).
  for (const el of Array.from(clone.querySelectorAll(TRANSIENT_SELECTOR))) el.remove()

  // Re-declare the app's extra blocks: drop every one of a managed type, then
  // write the current set back. Removing a language from the file is therefore
  // just "stop listing it" — no deletion path to get wrong. The clear-set is
  // the DECLARED types, never the types about to be written: an empty write
  // set still has to clear (that is what removing the file's last pack looks
  // like).
  const wanted = shellBlocks()
  for (const type of new Set([...managedTypes, ...wanted.map((b) => b.type)])) {
    for (const stale of Array.from(clone.querySelectorAll(`script[type="${type}"]`))) stale.remove()
  }
  for (const b of wanted) {
    const el = clone.createElement('script')
    el.setAttribute('type', b.type)
    el.id = b.id
    for (const [k, v] of Object.entries(b.attrs ?? {})) el.setAttribute(k, v)
    // same <-escape as the doc block: these can never contain "</script>"
    el.textContent = '\n' + (b.body.includes('<') ? b.body.replace(/</g, '\\u003c') : b.body) + '\n'
    clone.head.appendChild(el)
  }

  let block = clone.getElementById(DATA_BLOCK_ID)
  if (!block) {
    block = clone.createElement('script')
    block.setAttribute('type', 'application/bento+json')
    block.id = DATA_BLOCK_ID
    clone.head.appendChild(block)
  }
  // <-escape so the JSON can never contain "</script>" and break the file.
  block.textContent = '\n' + (body.includes('<') ? body.replace(/</g, '\\u003c') : body) + '\n'

  writePreview(clone, body, doc)

  // An encrypted file must not carry the document title in plaintext: the
  // <title> would sit in the file beside the ciphertext that exists to hide the
  // content, readable by anything that lists the file. Same veto as the preview
  // (previewAllowed covers both the live password flag and an already-encrypted
  // body), so write a generic title — the app name — instead. This touches only
  // the CLONE written to disk; the live tab's title is set elsewhere and keeps
  // the real title after unlock.
  const titleEl = clone.querySelector('title')
  if (titleEl) {
    titleEl.textContent = previewAllowed(body)
      ? doc.title + ' — ' + appConfig().appName
      : appConfig().appName
  }

  const html = '<!DOCTYPE html>\n' + clone.documentElement.outerHTML
  // Belt-and-braces: an unescaped close tag anywhere in generated output would
  // corrupt the file; this should never trigger given the escaping above.
  // Count occurrences with indexOf instead of splitting the multi-megabyte string into an array.
  let scripts = 0
  let position = 0
  // Use `indexOf` here to avoid allocations galore.
  while ((position = html.indexOf(SCRIPT_CLOSE, position)) !== -1) {
    scripts += 1
    position += SCRIPT_CLOSE.length
  }
  if (scripts !== clone.querySelectorAll('script').length) {
    console.warn('bento: unexpected script-close count in serialized file')
  }
  return html
}

// --- static first-page preview (file-manager thumbnails) ---------------------
//
// THE PROBLEM. A Bento file is one HTML document, and thumbnailers — iOS
// Files, macOS QuickLook/Finder, the bento/home app — render HTML with
// JavaScript DISABLED (verified: `qlmanage -t` renders <noscript> content).
// Until our runtime boots, every deck genuinely IS the same bytes plus the
// boot splash, so every deck thumbnailed as the same dark box.
//
// THE FIX. At save time we write a STATIC rendering of page one into the file
// and park it inside a `<noscript>`. That element's contents are rendered only
// when scripting is off, which is exactly the population we are addressing:
// a real reader never sees it — not for a frame — so there is no flash to
// suppress, no interaction with the splash's `.done`/`bsAuto` dismissal, and
// nothing for print or present to exclude. When a thumbnailer runs scripts
// after all, the preview is simply never rendered and we are back to today's
// behaviour: a regression is not possible, only an improvement.
//
// It is shell FURNITURE, not document data: nothing here enters `#bento-doc`,
// no format field is added, and a file saved by an older build (which has no
// preview) opens identically.
//
// The kernel knows nothing about how any app draws a page. It owns the
// placement, the replace-don't-append rule, the encryption veto and the
// output-safety check; the app hands back a ready-made element.

const PREVIEW_ATTR = 'data-bento-preview'

/** Builds the app's static first-page rendering. Return null for "no preview". */
export type PreviewProvider = (doc: KernelDoc) => HTMLElement | null

let previewProvider: PreviewProvider | null = null

/** Register the app's first-page renderer. Call once, at boot. Optional — an
 *  app that registers nothing simply saves files without a preview. */
export function registerPreview(fn: PreviewProvider): void {
  previewProvider = fn
}

/**
 * May this saved file carry a plaintext preview of its first page?
 *
 * NO for an encrypted deck, and this is the single most important rule here.
 * The whole point of the `bento/enc` envelope is that the content is
 * unreadable on disk without the password; rendering page one in plaintext
 * beside the ciphertext would hand an attacker the title slide — usually the
 * most disclosive page in the deck — and would do it silently, because the
 * owner would never see the markup they were shipping. A missing thumbnail is
 * the correct, expected cost of encrypting a file.
 *
 * Two independent tests, because they fail independently: the in-memory
 * password flag covers the live session, and re-parsing the body covers any
 * path that hands us an already-encrypted block without the flag set.
 *
 * Pure and exported so `scripts/test-preview.ts` can exercise it directly —
 * the surrounding DOM work is not unit-testable in node, this decision is.
 */
export function previewAllowed(body: string, encrypted = isBodySealed()): boolean {
  return !encrypted && parseEnvelope(body) === null
}

// Built by concatenation for the usual reason (AGENTS.md #1): these literals
// must never appear in a Bento bundle, which is itself inline script.
// Note the close forms carry no ">": an HTML parser ends a script element at
// `</script` followed by whitespace, `/` or `>`, so `</script foo>` closes it
// just as surely as the tidy form does.
const SCRIPT_OPEN = '<scr' + 'ipt'
const SCRIPT_CLOSE_START = '</scr' + 'ipt'
const NOSCRIPT_CLOSE = '</nosc' + 'ript'
const STYLE_OPEN = '<sty' + 'le'
const STYLE_CLOSE_START = '</sty' + 'le'

/**
 * The preview's one stylesheet, and nothing hiding inside it.
 *
 * `<style>` is a RAW TEXT element: its content is not escaped on the way out, so
 * whatever a provider puts in it is written to the file verbatim. Every app's
 * preview has one (slides and dash hoist repeated declarations into it, spaces
 * writes a sheet), and every one of them builds declarations out of AUTHOR
 * data — colours, fonts, sizes. A single `</style>` in one of those values ends
 * the element early and everything after it is live markup in the reader's DOM,
 * outside `#bento-doc`, at parse time, before the remover runs.
 *
 * A flat "refuse any `<style`" would be simpler and would refuse EVERY preview,
 * so the rule is shaped like the tokenizer instead: at most one style element,
 * no `<` anywhere in its text (the breakout attempt is itself a `<`), and no
 * second opener or stray closer anywhere around it. That last clause is what
 * catches the tidy version of the attack, which re-opens a style after the
 * markup it smuggled in and leaves the tag counts balanced.
 */
function styleIsInert(lower: string): boolean {
  const open = lower.indexOf(STYLE_OPEN)
  if (open < 0) return !lower.includes(STYLE_CLOSE_START)
  if (lower.slice(0, open).includes(STYLE_CLOSE_START)) return false
  const gt = lower.indexOf('>', open)
  if (gt < 0) return false
  const end = lower.indexOf(STYLE_CLOSE_START, gt)
  if (end < 0) return false
  const rest = lower.slice(end + STYLE_CLOSE_START.length)
  return !lower.slice(gt + 1, end).includes('<') &&
    !rest.includes(STYLE_OPEN) && !rest.includes(STYLE_CLOSE_START)
}

/**
 * Refuse any preview markup that could unbalance the file.
 *
 * The preview is generated from user content, so it is not shaped by us. A
 * `<script>`/`</script>` in it would break the open/close balance the frozen
 * splice contract (and `scripts/shell-gate.mjs`) depends on. `</noscript>` is
 * still refused although the preview no longer lives in a `<noscript>`: it
 * costs nothing, and a document written by an older Bento may still carry one.
 *
 * This check got MORE load-bearing when the preview left `<noscript>`. It is no
 * longer inert markup that only a scripting-less renderer ever parses — it now
 * lands in the live DOM of every reader's page until the remover runs.
 *
 * The app sanitizes its own output; this is the kernel refusing to take its
 * word for it. Dropping the preview costs a thumbnail. Emitting it anyway could
 * brick the file — or, through the preview's own stylesheet, put live markup in
 * the reader's DOM; see styleIsInert for the half escaping cannot reach.
 *
 * Exported for `scripts/test-preview.ts`, like previewAllowed.
 */
export function previewIsSafe(html: string): boolean {
  const lower = html.toLowerCase()
  if (lower.includes(SCRIPT_OPEN) || lower.includes(SCRIPT_CLOSE_START) || lower.includes(NOSCRIPT_CLOSE)) return false
  return styleIsInert(lower)
}

/**
 * Deletes the preview, and itself, the instant the parser reaches it.
 *
 * Parser-BLOCKING on purpose: a classic inline script placed immediately after
 * the preview runs before the parser continues, so the browser never paints a
 * frame containing it. That is what makes this free for readers.
 *
 * It is written as a string rather than built from a template because it must
 * stay one line and contain no `</script>`.
 */
const PREVIEW_REMOVER =
  `(function(){var a=document.querySelectorAll('[${PREVIEW_ATTR}]');` +
  `for(var i=a.length;i--;){var n=a[i];if(n.parentNode)n.parentNode.removeChild(n)}})()`

function writePreview(clone: Document, body: string, doc: KernelDoc): void {
  // REPLACE, NEVER APPEND. `capturePristine()` snapshots the document as it
  // was loaded, so the shell we are cloning already carries the preview the
  // PREVIOUS save wrote; appending would stack a new one on every ⌘S until the
  // file was mostly stale previews. Removing unconditionally — before deciding
  // whether to write a new one — is also how a preview correctly DISAPPEARS
  // when a plaintext deck gains a password, or when an app stops providing
  // one. Both of those are silent leaks if the removal is conditional.
  // The selector is deliberately attribute-only: it must sweep the host AND the
  // remover script beside it, and it must still find previews written by an
  // older Bento, which parked them in a <noscript>.
  for (const stale of Array.from(clone.querySelectorAll(`[${PREVIEW_ATTR}]`))) stale.remove()

  if (!previewProvider || !previewAllowed(body)) return

  let el: HTMLElement | null = null
  try {
    el = previewProvider(doc)
  } catch (err) {
    // A preview is a nicety; a failed save is not. Never let rendering page
    // one take the file down with it.
    console.warn('bento: first-page preview failed, saving without one', err)
    return
  }
  if (!el) return

  // ORDINARY MARKUP, NOT <noscript>, AND A PARSER-BLOCKING REMOVER.
  //
  // `<noscript>` was the obvious home and it is wrong here. It renders only
  // where scripting is DISABLED, and iOS — the platform this feature exists for
  // — satisfies neither half of that: probed with a page whose inline script
  // repaints it, the iOS thumbnailer renders neither the script's result nor
  // the <noscript>, so a deck thumbnailed as its boot splash no matter what we
  // put in the noscript.
  //
  // Since that thumbnailer runs no script, plain markup survives for it. And
  // since every real reader DOES run script, a parser-blocking inline remover
  // placed immediately after deletes the preview before the browser paints a
  // frame containing it. Both audiences get the right answer with no flash and
  // no compromise — which the <noscript> version could not manage.
  //
  // A reader with scripting genuinely off keeps the preview on screen, exactly
  // as before: without scripts the deck cannot render at all, so a still of
  // page one is the best available answer rather than a regression.
  const host = clone.createElement('div')
  host.setAttribute(PREVIEW_ATTR, '1')
  host.appendChild(clone.importNode(el, true))
  if (!previewIsSafe(host.innerHTML)) {
    console.warn('bento: first-page preview rejected as unsafe, saving without one')
    return
  }
  const remover = clone.createElement('script')
  remover.setAttribute(PREVIEW_ATTR, '1')
  remover.textContent = PREVIEW_REMOVER

  // Straight after the splash it replaces, so a thumbnailer reaches it before
  // the ~550KB of compressed payload at the end of the body. The remover goes
  // immediately after the host: any markup between them is markup the parser
  // could paint first.
  const splash = clone.getElementById('bento-splash')
  const parent = splash?.parentNode ?? clone.body ?? clone.documentElement
  const after = splash?.parentNode ? splash.nextSibling : null
  parent.insertBefore(host, after)
  parent.insertBefore(remover, host.nextSibling)
}

/**
 * Serialize `doc` into an arbitrary app shell (a parsed Bento HTML document).
 * Used with the boot-time pristine copy on every save, and by the self-update
 * flow with a freshly fetched NEWER shell — same document, new app around it.
 * PLAIN output — encryption-aware callers use serializeDocInto/serializeAuto.
 */
export function serializeWith(shell: Document, doc: KernelDoc): string {
  return serializeBody(shell, JSON.stringify(doc), doc)
}

/** The full .bento.html file content with `doc` embedded (plain). */
export function serializeFile(doc: KernelDoc): string {
  if (!pristine) throw new Error('capturePristine() was not called at boot')
  return serializeWith(pristine, doc)
}

// --- password encryption ----------------------------------------------------
//
// An encrypted file keeps the SAME plaintext #bento-doc block (the splice
// contract old updaters rely on) — but the block holds a bento/enc envelope
// instead of the document: AES-GCM-256 over the doc JSON, key derived from
// the password with PBKDF2-SHA-256. The password is held in memory for the
// session so ⌘S and self-update keep writing encrypted output.

export interface EncEnvelope {
  format: 'bento/enc'
  v: 1
  /** PBKDF2 rounds (password envelopes) */
  it?: number
  /** 'hkdf-kdoc' = identity-sealed (§E.1): opened by the document key, never a password */
  kdf?: 'hkdf-kdoc'
  salt: string
  iv: string
  data: string
}

/**
 * PBKDF2 rounds for NEW envelopes only.
 *
 * A .bento.html is offline at-rest storage: the ciphertext sits in a file that
 * gets mailed, synced and backed up, so an attacker guesses passwords at their
 * own pace with no rate limit anywhere. 300k was half of current guidance
 * (OWASP: 600k for PBKDF2-HMAC-SHA256), and it is the cheapest possible thing
 * to fix — one number, and the cost lands on a keypress the user already waits
 * through.
 *
 * READING IS UNAFFECTED, deliberately: the count travels in the envelope (`it`)
 * and `decryptEnvelope` derives with THAT number, never this one. Every deck
 * encrypted by an older build keeps opening with its own 300k, and re-saving it
 * re-encrypts at the new count. A file that stops opening would be far worse
 * than a weak KDF, so `scripts/test-preview.ts` pins a real 300k envelope.
 */
const ENC_ITERATIONS = 600_000

const eb64 = {
  enc(bytes: Uint8Array): string {
    let s = ''
    for (const b of bytes) s += String.fromCharCode(b)
    return btoa(s)
  },
  dec(s: string): Uint8Array {
    const b = atob(s)
    const out = new Uint8Array(b.length)
    for (let i = 0; i < b.length; i++) out[i] = b.charCodeAt(i)
    return out
  },
}

let encPassword: string | null = null

/** Set (or clear with null) the password used for every subsequent save. */
export function setEncryptionPassword(p: string | null) {
  encPassword = p
  announceSeal()
}

export const isEncryptionActive = () => encPassword !== null

/**
 * The identity seal (identity-kernel §E.2): K_doc as an HKDF base key, set when
 * a person's agent unwraps the document key, cleared on lock. With no password
 * set, every save seals the body under it (encodeDocBody).
 */
let sealBodyKey: Promise<CryptoKey> | null = null

/**
 * Set (or clear with null) the identity seal. `kdoc` is the raw 32-byte
 * document key, imported NON-EXTRACTABLE as an HKDF base. Synchronous on
 * purpose: isBodySealed() is true from this call on, before the import settles,
 * so no guard can slip a plaintext write into that gap. A failed import fails
 * every later save closed rather than letting it write plaintext.
 */
export function setIdentitySeal(kdoc: Uint8Array | null): void {
  if (kdoc === null) { sealBodyKey = null; announceSeal(); return }
  if (!(kdoc instanceof Uint8Array) || kdoc.length !== 32) throw new Error('the document key is 32 bytes')
  sealBodyKey = crypto.subtle.importKey('raw', kdoc.slice() as BufferSource, 'HKDF', false, ['deriveKey'])
  announceSeal()
}

/**
 * Is the body sealed on disk, by a password OR the identity seal? THE question
 * for every plaintext-to-disk guard (recovery snapshots, version history,
 * previews, the filename). `isEncryptionActive()` answers only "is there a
 * password", which is what the password UI wants and what a guard must not ask:
 * an identity-sealed document has no password, so a guard reading that flag
 * writes it to disk in plaintext.
 */
export const isBodySealed = () => encPassword !== null || sealBodyKey !== null

/**
 * How many times the plaintext store (autosave.ts) refused a write or a read
 * because the body is sealed. The store's refusal is a BACKSTOP under each app's
 * own guards: an app that leans on it has a missing guard. Readable only through
 * the test probe, so the sealed-test rigs can fail on any refusal (security).
 */
/**
 * Tell the HOST whether this document is sealed (security §30.6): a host that
 * declares 'seal' (home/bridge.js, Android today) blanks its app-switcher
 * snapshot while it is. Sent at boot and on EVERY change (password set or
 * removed, identity seal on or off), the moment it happens and before any save,
 * because a password set but not yet saved is already a secret. A bare boolean,
 * fire-and-forget: the host never replies, and it can only ADD blanking, so a
 * missed `true` is the only failure and a redundant post is free. Not
 * deduplicated, for that reason.
 */
let sealPostId = 0
function announceSeal(): void {
  const host = (globalThis as { __bentoHost?: { ops?: readonly string[] } }).__bentoHost
  if (typeof window === 'undefined' || typeof window.postMessage !== 'function') return
  if (!Array.isArray(host?.ops) || !host.ops.includes('seal')) return
  window.postMessage({ __bento_tray__: true, dir: 'req', id: `seal-${++sealPostId}`, op: 'seal.state', payload: { sealed: isBodySealed() } }, '*')
}

let storeRefusals = 0
export function noteStoreRefusal(): void { storeRefusals++ }
/** For rigs only (node, or a page through the test probe). Unreachable from page
 *  script in a release: a module export inside the bundle, and unused there. */
export function storeRefusalCount(): number { return storeRefusals }

/** Parse a data-block body as an encryption envelope; null if it is not one. */
export function parseEnvelope(text: string): EncEnvelope | null {
  try {
    const env = JSON.parse(text)
    if (env && env.format === 'bento/enc' && env.v === 1 && env.data && env.salt && env.iv) {
      return env as EncEnvelope
    }
  } catch {
    /* not an envelope */
  }
  return null
}

async function deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<CryptoKey> {
  const material = await crypto.subtle.importKey(
    'raw', new TextEncoder().encode(password), 'PBKDF2', false, ['deriveKey'])
  return crypto.subtle.deriveKey(
    { name: 'PBKDF2', hash: 'SHA-256', salt: salt as BufferSource, iterations },
    material, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt'])
}

async function encryptBody(json: string, password: string): Promise<string> {
  const salt = new Uint8Array(16)
  const iv = new Uint8Array(12)
  crypto.getRandomValues(salt)
  crypto.getRandomValues(iv)
  const key = await deriveKey(password, salt, ENC_ITERATIONS)
  const ct = await crypto.subtle.encrypt(
    { name: 'AES-GCM', iv: iv as BufferSource }, key, new TextEncoder().encode(json))
  const env: EncEnvelope = {
    format: 'bento/enc', v: 1, it: ENC_ITERATIONS,
    salt: eb64.enc(salt), iv: eb64.enc(iv), data: eb64.enc(new Uint8Array(ct)),
  }
  return JSON.stringify(env)
}

const BODY_INFO = new TextEncoder().encode('bento/body.v1')

/** bodyKey = HKDF-SHA-256(K_doc, salt, "bento/body.v1") as an AES-256-GCM key. */
const bodyKeyFor = (kdoc: CryptoKey, salt: Uint8Array) => crypto.subtle.deriveKey(
  { name: 'HKDF', hash: 'SHA-256', salt: salt as BufferSource, info: BODY_INFO as BufferSource },
  kdoc, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt'])

/**
 * The identity-sealed body: a GENUINE bento/enc v1 envelope (§E.1), so frozen
 * shells, previewAllowed and convert all read it as sealed. Never v:2, never
 * without salt: an old parseEnvelope would reject it, boot the starter deck, and a
 * later save would overwrite the sealed block. `salt` is the real HKDF salt,
 * fresh on every save as the password path's is, and `kdf` (ignored by old
 * shells) says which key opens it.
 */
async function sealBody(json: string, kdoc: CryptoKey): Promise<string> {
  const salt = new Uint8Array(16)
  const iv = new Uint8Array(12)
  crypto.getRandomValues(salt)
  crypto.getRandomValues(iv)
  const ct = await crypto.subtle.encrypt(
    { name: 'AES-GCM', iv: iv as BufferSource }, await bodyKeyFor(kdoc, salt), new TextEncoder().encode(json))
  const env: EncEnvelope = {
    format: 'bento/enc', v: 1, kdf: 'hkdf-kdoc',
    salt: eb64.enc(salt), iv: eb64.enc(iv), data: eb64.enc(new Uint8Array(ct)),
  }
  return JSON.stringify(env)
}

/** Open an identity-sealed envelope with the raw document key; null if it isn't one or the key is wrong. */
export async function openIdentitySealed(env: EncEnvelope, kdoc: Uint8Array): Promise<string | null> {
  if (env.kdf !== 'hkdf-kdoc') return null
  try {
    const base = await crypto.subtle.importKey('raw', kdoc as BufferSource, 'HKDF', false, ['deriveKey'])
    const pt = await crypto.subtle.decrypt(
      { name: 'AES-GCM', iv: eb64.dec(env.iv) as BufferSource }, await bodyKeyFor(base, eb64.dec(env.salt)), eb64.dec(env.data) as BufferSource)
    return new TextDecoder().decode(pt)
  } catch {
    return null
  }
}

/** Decrypt an envelope with a candidate password; null on wrong password. */
export async function decryptEnvelope(env: EncEnvelope, password: string): Promise<string | null> {
  try {
    const key = await deriveKey(password, eb64.dec(env.salt), env.it || ENC_ITERATIONS)
    const pt = await crypto.subtle.decrypt(
      { name: 'AES-GCM', iv: eb64.dec(env.iv) as BufferSource }, key, eb64.dec(env.data) as BufferSource)
    return new TextDecoder().decode(pt)
  } catch {
    return null
  }
}

/**
 * Encryption-aware serialization into an arbitrary shell — THE path for
 * saves and self-updates. Plain when no password is active.
 */
/**
 * The exact bytes that go INTO `#bento-doc`: the document JSON when no password
 * is active, or the `bento/enc` envelope over that JSON when one is. This is the
 * payload a save writes — the shell (serializeBody) is furniture around it — and
 * it is DOM-free, so it is the seam a rig can drive the real write path with.
 */
export async function encodeDocBody(doc: KernelDoc): Promise<string> {
  if (encPassword) return encryptBody(JSON.stringify(doc), encPassword)
  if (sealBodyKey) return sealBody(JSON.stringify(doc), await sealBodyKey)
  return JSON.stringify(doc)
}

export async function serializeDocInto(shell: Document, doc: KernelDoc): Promise<string> {
  return serializeBody(shell, await encodeDocBody(doc), doc)
}

/** Encryption-aware serializeFile. */
export async function serializeAuto(doc: KernelDoc): Promise<string> {
  if (!pristine) throw new Error('capturePristine() was not called at boot')
  return serializeDocInto(pristine, doc)
}

export function suggestedFileName(doc: KernelDoc, suffix = ''): string {
  // An encrypted deck should not carry its title in the download filename
  // either — use a neutral default (the app name). The real title is kept in the
  // live tab and returns to the filename once the password is cleared.
  const source = isBodySealed() ? appConfig().appName : doc.title
  const base = source.replace(/[^\w\d-]+/g, '_').replace(/^_+|_+$/g, '') || 'Untitled'
  return `${base}${suffix ? `-${suffix}` : ''}.bento.html`
}

// --- writing to disk --------------------------------------------------------

type SaveResult = 'saved' | 'saved-as' | 'copied' | 'downloaded' | 'cancelled'

interface FsFileHandle {
  createWritable(): Promise<{ write(data: Blob): Promise<void>; close(): Promise<void> }>
  getFile?(): Promise<{ text(): Promise<string> }>
  name: string
}

let fileHandle: FsFileHandle | null = null

const hasFsAccess = () => typeof (window as any).showSaveFilePicker === 'function'

/**
 * Can this browser rewrite the open file, or only hand back copies?
 *
 * The File System Access API is Chrome/Edge only: Safari and Firefox lack it,
 * and so does EVERY browser on iOS, because they are all WebKit underneath.
 * Without it there is no writable handle, which costs three things — in-place
 * save, silent autosave write-back, and in-place self-update.
 *
 * Exported because the UI must not promise what the browser cannot do. "⌘S
 * rewrites this file in place" is the product's central claim and it is simply
 * false here; saying it anyway and retracting it in a toast after the first
 * save is worse than saying the true thing up front.
 */
export const canWriteInPlace = () => hasFsAccess()

/**
 * What a save is FOR. The three cases want different files in different places,
 * and until now the picker could not tell them apart.
 *
 * · `in-place` — ⌘S. Overwrite the document being edited.
 * · `copy`     — "Save a copy…". A second file, chosen by the author.
 * · `share`    — a suffixed export: view-only, presentation package, invite,
 *                template. Deliberately a new file, and never the ⌘S target.
 * · `backup`   — the rollback copy a self-update leaves behind. Belongs BESIDE
 *                the document it backs up, and is the one save the author never
 *                asked for, so it is also the one that must never interrupt.
 */
export type SavePurpose = 'in-place' | 'copy' | 'share' | 'backup'

/**
 * The picker `id` for a purpose — and, incidentally, the only signal a HOST has
 * about what it is being asked to do.
 *
 * Browsers remember the last directory used per `id`, so distinct ids are worth
 * having on their own: exports and working files usually live in different
 * places, and one shared id made the picker open wherever you last put a
 * view-only copy.
 *
 * The other reason is not incidental. A host that polyfills
 * `showSaveFilePicker` (home/ios over UIDocument, home/webext over a directory
 * grant) sees ONLY the options bag. `saveFile(doc, forcePicker)` used to reach
 * this function with byte-identical arguments for ⌘S and for "Save a copy…",
 * so a host could not distinguish them — and one that guessed wrong overwrote
 * the open document instead of copying it. Measured, in a browser extension,
 * 2026-08-02. Intent has to be explicit in the call, because it cannot be
 * recovered from anything else in it.
 */
export const pickerIdFor = (purpose: SavePurpose): string =>
  purpose === 'in-place' ? 'bento-doc'
    : purpose === 'copy' ? 'bento-copy'
      : purpose === 'backup' ? 'bento-backup'
        : 'bento-share'

/**
 * Is a HOST polyfilling the picker — home/ios, home/webext — rather than the
 * browser's own?
 *
 * The kernel cannot infer this. `showSaveFilePicker` exists either way, and a
 * host that declines a request is indistinguishable from one that is not there:
 * both end in the native dialog. So a host that can do more than the bare
 * contract announces itself, and this is the only thing the kernel reads.
 *
 * It gates exactly one decision — see `writeBackupBeside`. Nothing else may
 * branch on it: every in-place path must keep working when it is false, because
 * that is the plain-browser case and it is the majority one.
 *
 * PRESENCE IS NOT ENOUGH, so this asks about a named capability. A host that
 * announced itself but did not recognise `bento-backup` would pass the request
 * through to the native picker — producing exactly the dialog this exists to
 * remove, and only for people who installed the host. Decks outlive host
 * versions in both directions; neither side may assume the other is current.
 */
export const hostCan = (op: string): boolean => {
  const host = (window as any).__bentoHost
  return !!host && Array.isArray(host.ops) && host.ops.includes(op)
    && typeof (window as any).showSaveFilePicker === 'function'
}

async function pickHandle(
  doc: KernelDoc, suffix = '', suggestedName?: string, purpose: SavePurpose = 'in-place',
): Promise<FsFileHandle | null> {
  try {
    // The name to offer is the file the user is ALREADY looking at, when we know
    // it. suggestedFileName() derives from doc.title, and the two drift apart
    // constantly — a deck called "Bento Slides Showcase" living in
    // Q3-board.bento.html offered to save as Bento_Slides_Showcase.bento.html,
    // so an ordinary ⌘S silently proposed a SECOND file beside the real one.
    // A suffixed export (share copies) still names itself, hence the suffix
    // check: those are deliberately new files.
    const openedName = suffix ? null : openedFileName()
    return await (window as any).showSaveFilePicker({
      suggestedName: suggestedName ?? openedName ?? suggestedFileName(doc, suffix),
      // startIn takes a HANDLE, never a path — the API gives no way to point a
      // picker at an arbitrary directory, by design. With a handle we land in
      // the open file's own folder; without one, `id` is the fallback: the
      // browser remembers the last directory used under this id, so the second
      // update onwards opens where the first one saved.
      ...(fileHandle ? { startIn: fileHandle } : {}),
      id: pickerIdFor(purpose),
      // `.bento.html`, NOT `.html`, and the compound extension is the point.
      //
      // `suggestedFileName` has always produced `.bento.html`, but the picker
      // accepted `.html` — so an author who edited the name to "Q3" got
      // `Q3.html`, and a document named that is a second-class citizen
      // everywhere the convention is what identifies us: home/webext injects
      // its save bridge on `file:///*.bento.html`, so such a file opens fine
      // and then asks where to save, and home/ios matches the same way.
      //
      // Bento was manufacturing the exception and then being asked to cope with
      // it. Accepting only the compound extension means the browser appends it
      // to a bare name, which is what everybody meant. Compound suffixes are
      // explicitly legal here (`.tar.gz` is the spec's own example) and the
      // limit is 16 characters against this one's 11.
      types: [{ description: appConfig().appName, accept: { 'text/html': ['.bento.html'] } }],
    })
  } catch (err: any) {
    if (err?.name === 'AbortError') return null
    throw err
  }
}

async function writeHandle(handle: FsFileHandle, html: string) {
  // Yield to the event loop before disk I/O.
  // On Linux + Wayland it is important to give the compositor a chance to
  // commit pending frames, before Disk I/O.
  await new Promise((r) => setTimeout(r, 0))
  const writable = await handle.createWritable()
  await writable.write(new Blob([html], { type: 'text/html' }))
  await writable.close()
}

export function downloadFile(html: string, name: string) {
  const url = URL.createObjectURL(new Blob([html], { type: 'text/html' }))
  const a = document.createElement('a')
  a.href = url
  a.download = name
  a.click()
  setTimeout(() => URL.revokeObjectURL(url), 5000)
}

// --- remembering the file handle across reopens -----------------------------
//
// Chrome's File System Access blocklist refuses ~/Documents, ~/Downloads, the
// Desktop and the home folder as DIRECTORY grants, so a deck sitting directly in
// one of them can never be covered by a bento/home folder grant and re-ran the
// full save picker on every reopen. FILE handles are not blocked and are
// structured-cloneable, so we remember the one a save produced (IndexedDB, keyed
// by docId) and, on the first ⌘S after a reopen, re-request readwrite permission
// INSIDE the save gesture — Chrome 122+ shows a small "Allow on every visit"
// prompt instead of a picker. Only a real FileSystemFileHandle is stored: a host
// polyfill (home/ios, home/webext) hands back its own handle, which is not one
// and stays on the bridge path untouched.

const HANDLE_DB = 'bento-handles'
const HANDLE_STORE = 'handles'

function handleDb(): Promise<IDBDatabase> {
  return new Promise((resolve, reject) => {
    const req = indexedDB.open(HANDLE_DB, 1)
    req.onupgradeneeded = () => { req.result.createObjectStore(HANDLE_STORE) }
    req.onsuccess = () => resolve(req.result)
    req.onerror = () => reject(req.error)
  })
}
async function idbHandle(op: 'get' | 'put' | 'delete', key: string, val?: unknown): Promise<unknown> {
  const db = await handleDb()
  try {
    return await new Promise((resolve, reject) => {
      const tx = db.transaction(HANDLE_STORE, op === 'get' ? 'readonly' : 'readwrite')
      const store = tx.objectStore(HANDLE_STORE)
      const r = op === 'get' ? store.get(key) : op === 'put' ? store.put(val, key) : store.delete(key)
      r.onsuccess = () => resolve(op === 'get' ? r.result : undefined)
      r.onerror = () => reject(r.error)
    })
  } finally { db.close() }
}

/** The store key for one FILE's handle. A copy shares its origin's docId
 *  ("Save a copy…" is the same deck, same live session), so keying by docId
 *  ALONE let the last-saved file evict the other's handle: saving a copy
 *  overwrote the original's entry, and reopening the original then fell back to
 *  the picker (#556). Keying by docId AND file name gives each file its own
 *  entry — correct whichever deck "Save a copy…" leaves open, because it keys
 *  by the file that was actually written. U+001F can't occur in a file name. */
const handleKey = (docId: string, name: string) => `${docId}\u001f${name}`

/** A FileSystemFileHandle with the permission methods (not in every lib.dom). */
type PermHandle = FsFileHandle & {
  queryPermission(d: { mode: 'readwrite' }): Promise<PermissionState>
  requestPermission(d: { mode: 'readwrite' }): Promise<PermissionState>
}
const isRealHandle = (h: unknown): h is PermHandle =>
  typeof FileSystemFileHandle !== 'undefined' && h instanceof FileSystemFileHandle

/** Remember the handle a save produced so the next reopen can reconnect it.
 *  Only ever reached from saveFile — a readonly player never saves, so its
 *  handle is never stored — and only a real handle, never a host polyfill.
 *
 *  NOT on a shared-storage origin. Chrome gives every file:// document one
 *  IndexedDB, so a stored handle is a live write capability any other local
 *  deck could read and re-permission (docs/DECISIONS.md, security-review-pr519).
 *  There a persistent grant has no identity to bind to, so it is not offered;
 *  the per-session handle still works. Real web origins and real-origin host
 *  apps (isolated storage) persist as normal. */
export async function persistHandle(doc: KernelDoc, handle: FsFileHandle): Promise<void> {
  if (sharedStorageOrigin() || !doc.docId || !isRealHandle(handle)) return
  // Per FILE (docId + name), not per docId — see handleKey (#556).
  try { await idbHandle('put', handleKey(doc.docId, handle.name), handle) } catch { /* best effort — a lost handle just means tomorrow's picker */ }
}

/**
 * First ⌘S after a reopen: if we remember a handle for this docId, re-acquire
 * permission inside the save gesture instead of showing the picker. Returns the
 * handle when permission is granted, else null (the caller falls back to the
 * picker). Exported for the rig.
 *
 * MUST run before the expensive serializeAuto so the user activation the save
 * gesture carries is still fresh when requestPermission() prompts (Chrome keeps
 * transient activation ~5 s across awaits; a ~1 s serialize would risk it).
 */
export async function reconnectHandle(doc: KernelDoc): Promise<FsFileHandle | null> {
  // Never reconnect from shared storage. On a file:// origin the store is shared
  // with every local deck, so an entry found here could have been planted by a
  // malicious file — keyed to this docId and named to match the file on screen,
  // which would make the name check below pass and re-permission a handle to a
  // DIFFERENT file on the user's own ⌘S (security-review-pr519, finding 1). We
  // also never write there (persistHandle), but refusing to READ is what closes
  // the planted-entry path. Real, isolated origins reconnect as normal.
  if (sharedStorageOrigin()) return null
  if (!doc.docId) return null
  // The remembered handle must be the file ON SCREEN, and the only check we have
  // on a bare reopen is its NAME (isSameEntry needs a second handle we do not
  // have). With no name on screen — the hosted app, nothing open — there is
  // nothing to verify against, so we do NOT reconnect: reading a docId-only entry
  // unchecked could re-permission a handle to a different file. A real reopen
  // always has a name.
  const onScreen = openedFileName()
  if (!onScreen) return null
  // Primary key is per FILE (docId + name). Fall back to the legacy docId-only
  // key for entries written before #556 — the name guard below validates it too,
  // so the fallback is no weaker than the primary.
  let key = handleKey(doc.docId, onScreen)
  let stored: unknown
  try {
    stored = await idbHandle('get', key)
    if (!isRealHandle(stored)) { key = doc.docId; stored = await idbHandle('get', key) }
  } catch { return null }
  if (!isRealHandle(stored)) return null // absent, or a host polyfill handle
  if (stored.name !== onScreen) return null // mismatch → picker, entry kept
  try {
    let perm = await stored.queryPermission({ mode: 'readwrite' })
    if (perm !== 'granted') perm = await stored.requestPermission({ mode: 'readwrite' })
    if (perm === 'granted') return stored
    void idbHandle('delete', key) // denied → forget it, use the picker
    return null
  } catch { // NotFoundError (file moved/deleted) or any handle failure
    void idbHandle('delete', key)
    return null
  }
}

/**
 * Save the document. Chrome/Edge: File System Access API (picker on first
 * save, silent rewrite after — and, since a remembered handle can reconnect,
 * one permission prompt rather than a picker on the first save after a reopen).
 * Firefox/Safari: download a copy.
 */
export async function saveFile(doc: KernelDoc, forcePicker = false): Promise<SaveResult> {
  // Reconnect a remembered handle BEFORE serializing: requestPermission() has to
  // fire inside the fresh save gesture, and serializeAuto can take ~a second.
  if (hasFsAccess() && !forcePicker && !fileHandle) {
    const re = await reconnectHandle(doc)
    if (re) fileHandle = re
  }
  const html = await serializeAuto(doc)
  if (hasFsAccess()) {
    if (forcePicker || !fileHandle) {
      // forcePicker is only ever "Save a copy…"; a first save of an unsaved
      // document is in-place by intent even though it must also pick.
      const isCopy = forcePicker
      const handle = await pickHandle(doc, '', undefined, isCopy ? 'copy' : 'in-place')
      if (!handle) return 'cancelled'
      await writeHandle(handle, html)
      // "Save a copy…" keeps the open deck on the ORIGINAL (maintainer ruling,
      // 2026-10-15): the copy is written, but the editor's handle stays with the
      // original and the copy is NOT remembered as this doc's handle — so the
      // next ⌘S still targets the original and reopening it still reconnects.
      // Only a first in-place save retargets onto the file it just created.
      if (isCopy) return 'copied'
      fileHandle = handle
      void persistHandle(doc, handle)
      return 'saved-as'
    }
    await writeHandle(fileHandle, html)
    // idempotent, and the one place the ADOPTED-handle path (a dropped file) is
    // remembered too — it only matters once you have actually saved to it.
    void persistHandle(doc, fileHandle)
    return 'saved'
  }
  downloadFile(html, suggestedFileName(doc))
  return 'downloaded'
}

export const currentFileName = () => fileHandle?.name ?? null

/**
 * Adopt a handle obtained outside the save picker — today, a file dropped onto
 * the editor via `DataTransferItem.getAsFileSystemHandle()`.
 *
 * Why this exists: a deck double-clicked from disk opens on `file://` with NO
 * handle, so every ⌘S re-runs the picker and the user re-navigates to a file
 * they are already looking at. A drop yields a real handle, so adopting it
 * turns that document into one Bento can rewrite in place.
 *
 * The caller MUST have obtained readwrite permission first — this only records
 * the handle. It is deliberately not exported through `window.bento`: adopting
 * a handle silently redirects where ⌘S writes, which is a user gesture, never
 * something a script should do behind their back.
 */
export function adoptFileHandle(handle: FsFileHandle): void {
  fileHandle = handle
}

/**
 * Consume the File Handling API's `window.launchQueue` at boot and adopt the
 * handle it delivers for the open document — so a document opened in an installed
 * PWA (`file_handlers`) or in a native host (home/bridge.js, which defines a
 * `launchQueue` carrying the open file's handle) holds a writable handle from the
 * FIRST edit, not only after the first ⌘S. Without this a reviewer who edits,
 * leaves the app and reopens the file sees nothing saved — "saved in place" is the
 * app's whole claim.
 *
 * The queue is the host's single trigger: `setConsumer` is what begins the one
 * launch request (`launch: true`), and the host answers it with the open document
 * and no picker — a host that cannot (a read-only document) refuses it and vends
 * nothing, so we adopt only when a handle actually arrives. Persistence is not
 * done here: a native host re-delivers every launch, and a real PWA handle is
 * persisted by the ordinary save path (`persistHandle`, which skips host
 * polyfills). Calling `setConsumer` more than once is the API's own error, so this
 * is guarded to run once.
 */
export function consumeLaunchQueue(): void {
  const w = globalThis as unknown as {
    launchQueue?: { setConsumer?: (fn: (params: { files?: FsFileHandle[] }) => void) => void }
  }
  const lq = w.launchQueue
  if (!lq || typeof lq.setConsumer !== 'function') return
  // The open document's #bento-doc, captured now (boot, before any edit), read
  // from the element directly and normalised EXACTLY as embeddedDocBlock does, so
  // the two compare equal. This distinguishes a present-but-EMPTY block (a pristine
  // New document → '') from a MISSING one (not a Bento document → null), which
  // readEmbeddedDoc collapses: a New document must still adopt the host's handle
  // (B6), or its first ⌘S becomes a Save-As picker that writes a second file. The
  // handle we adopt must still hold THIS document: a host bug that vends the wrong
  // file would otherwise have the first autosave silently overwrite it.
  const blockEl = document.getElementById(DATA_BLOCK_ID)
  const booted = blockEl ? (blockEl.textContent ?? '').replace(/\r\n/g, '\n').trim() : null
  try {
    lq.setConsumer(async (params) => {
      const handle = params?.files?.[0]
      // booted === null means no block at all (not a Bento document) — nothing to
      // verify against; '' (a pristine shell) is a real, adoptable document.
      if (!handle || booted === null || typeof handle.getFile !== 'function') return
      try {
        const text = await (await handle.getFile()).text()
        // Adopt only if the file is still this document AND nothing claimed a handle
        // while we awaited getFile: a Save As / "Duplicate as new deck" during that
        // await sets its own handle, and snapping back to the launched file here
        // would have autosave overwrite the file the user just moved to.
        if (!hasFileHandle() && embeddedDocBlock(text) === booted) adoptFileHandle(handle)
        // else: a different/unverifiable file, or a handle already held — leave it;
        // ⌘S falls back to the picker.
      } catch { /* unreadable handle → do not adopt */ }
    })
  } catch { /* setConsumer rejects a second registration — the first already won */ }
}

// At boot, in a browser context, claim the open document's handle. A module-level
// call is deliberate: it keeps the seam in the kernel, so every app gets it with
// no per-app change, and it is the consumer's job to begin the launch request.
// node (rigs, tooling) has no `launchQueue`; a plain, non-installed tab has none
// either — both no-op. The rig drives consumeLaunchQueue() directly.
if (typeof window !== 'undefined') consumeLaunchQueue()

/**
 * The name of the file this document is actually open AS, when knowable.
 *
 * Two sources, best first: a held FS Access handle, else this document's own
 * URL. The URL case is the one that matters — a `.bento.html` double-clicked
 * from disk grants no handle, which is exactly when a save picker appears with
 * nothing useful in it.
 *
 * Only a name ending in `.bento.html` counts. That deliberately excludes the
 * hosted demo (`/slides/`, `index.html`), so the anonymous try-it deck still
 * falls back to naming itself after its title instead of "index".
 */
export function openedFileName(): string | null {
  if (fileHandle?.name) return fileHandle.name
  try {
    const base = decodeURIComponent(new URL(location.href).pathname.split('/').pop() ?? '')
    return /\.bento\.html$/i.test(base) ? base : null
  } catch {
    return null
  }
}

/** Strip the document extension: "Q3-board.bento.html" -> "Q3-board". */
export const fileBase = (name: string) => name.replace(/\.bento\.html$/i, '').replace(/\.html$/i, '')

// --- self-update writing ----------------------------------------------------

/** Whether we hold a writable handle to the file (in-place update possible). */
export const hasFileHandle = () => fileHandle !== null

/** Overwrite the held file with arbitrary html (the freshly updated shell). */
export async function writeUpdatedFile(html: string): Promise<void> {
  if (!fileHandle) throw new Error('no file handle')
  await writeHandle(fileHandle, html)
}

/**
 * Save updated html via a picker (user points it at the file they have open,
 * or anywhere else). Returns false if cancelled. Keeps the picked handle so
 * subsequent ⌘S saves go to the same place.
 */
export async function writeUpdatedFileAs(
  html: string,
  doc: KernelDoc,
  opts: { suffix?: string; keepHandle?: boolean; suggestedName?: string; purpose?: SavePurpose } = {},
): Promise<boolean> {
  if (!hasFsAccess()) {
    downloadFile(html, opts.suggestedName ?? suggestedFileName(doc, opts.suffix))
    return true
  }
  // `share` is the right default — every caller but one is an export. The
  // exception is the self-update, which is overwriting the open document and
  // must say so: a host reads only the picker id, and `bento-share` tells it
  // "a new file the author will choose", so it correctly declines and the
  // author gets a dialog for the one save that should never need one.
  const handle = await pickHandle(doc, opts.suffix, opts.suggestedName, opts.purpose ?? 'share')
  if (!handle) return false
  // Share/export artifacts must NOT become the ⌘S target — otherwise the next
  // save would overwrite e.g. a view-only copy with the FULL document (owner
  // keys included). Only an explicit keepHandle retargets in-place saving.
  if (opts.keepHandle) fileHandle = handle
  await writeHandle(handle, html)
  return true
}

/**
 * Leave the rollback copy an in-place update depends on.
 *
 * WHY THIS IS NOT JUST `downloadFile`. It was, and the backup landed in
 * ~/Downloads: detached from the document it backs up, one per update, and — for
 * anyone with Chrome's "ask where to save each file" enabled — behind a save
 * dialog. Reported 2026-08-14 against 1.0.16. That is the wrong outcome twice
 * over: an update that rewrites the file in place, silently, ended with the one
 * prompt in the flow being for a file the author never asked for, and the
 * rollback it produced was somewhere they would have to go hunting for.
 *
 * With a host, the backup goes where it belongs — beside the original, inside
 * the folder already granted. The host derives the directory itself, from the
 * sender's own resolved path; `name` is only ever validated against that, never
 * trusted as a path. See home/webext/src/background.js `backup`.
 *
 * Without a host this stays a download, because the alternative is a picker and
 * a picker is strictly worse than the status quo for the majority case.
 *
 * Never throws: a backup that fails must not take the update down with it. The
 * caller decides what to tell the author, which is why the outcome comes back
 * as a value.
 */
export async function writeBackupBeside(html: string, name: string): Promise<'beside' | 'downloaded'> {
  if (hostCan('backup')) {
    try {
      const handle = await (window as any).showSaveFilePicker({
        suggestedName: name,
        id: pickerIdFor('backup'),
        types: [{ description: appConfig().appName, accept: { 'text/html': ['.bento.html'] } }],
      })
      if (handle) {
        await writeHandle(handle, html)
        return 'beside'
      }
    } catch {
      // Declined, cancelled, or the grant lapsed. Fall through — a backup in
      // Downloads is a worse place, not a lost one.
    }
  }
  downloadFile(html, name)
  return 'downloaded'
}