@3sln/trove 0.0.2

package/packages/web/src/platform/settings.js

@@ -0,0 +1,101 @@
+// SettingsService — schema-driven, persisted, reactive settings (VS Code's
+// settings model). Core and plugins register typed setting schemas; values are
+// stored in localStorage, namespaced, and merged over defaults. The Settings UI
+// is generated from the schema, so adding a setting never means touching UI code.
+// Plugin keys are namespaced under the plugin id.
+
+import { cell } from '../runtime.js';
+
+const STORAGE_KEY = 'trove.settings';
+
+export class SettingsService {
+  constructor() {
+    this.schema = new Map(); // key -> { type, default, title, description, enum?, minimum?, maximum?, category, order }
+    this.values = read();
+    this.cell = cell(this.effective());
+  }
+
+  /**
+   * Register one or more settings. Each: { key, type, default, title,
+   * description?, enum?, enumLabels?, minimum?, maximum?, category?, order? }
+   */
+  register(schemas) {
+    for (const s of [].concat(schemas)) this.schema.set(s.key, s);
+    this.cell.setValue(this.effective());
+    return () => {
+      for (const s of [].concat(schemas)) this.schema.delete(s.key);
+      this.cell.setValue(this.effective());
+    };
+  }
+
+  get(key) {
+    if (key in this.values) return this.values[key];
+    return this.schema.get(key)?.default;
+  }
+
+  set(key, value) {
+    const schema = this.schema.get(key);
+    if (schema && value === schema.default) delete this.values[key];
+    else this.values[key] = value;
+    write(this.values);
+    this.cell.setValue(this.effective());
+  }
+
+  reset(key) {
+    delete this.values[key];
+    write(this.values);
+    this.cell.setValue(this.effective());
+  }
+
+  /** Full resolved values (defaults ⊕ overrides). */
+  effective() {
+    const out = {};
+    for (const [key, s] of this.schema) out[key] = key in this.values ? this.values[key] : s.default;
+    // Include stored keys with no (current) schema, so unknown/plugin values survive.
+    for (const [key, v] of Object.entries(this.values)) if (!(key in out)) out[key] = v;
+    return out;
+  }
+
+  observe() {
+    return this.cell;
+  }
+
+  /** Schema entries grouped by category, for the Settings UI. */
+  grouped() {
+    const groups = new Map();
+    for (const s of [...this.schema.values()].sort((a, b) => (a.order ?? 0) - (b.order ?? 0))) {
+      // `hidden` settings are state the app keeps under the settings key, not choices a
+      // person makes — the opener associations, for one, which are edited through the
+      // opener chooser and have their own section below. Rendering them anyway put a row
+      // reading "[object Object]" at the top of Settings.
+      if (s.hidden) continue;
+      const cat = s.category || 'General';
+      if (!groups.has(cat)) groups.set(cat, []);
+      groups.get(cat).push({ ...s, value: this.get(s.key) });
+    }
+    return [...groups.entries()].map(([category, items]) => ({ category, items }));
+  }
+
+  scopedFor(pluginId) {
+    const prefix = `${pluginId}.`;
+    return {
+      register: (schemas) =>
+        this.register([].concat(schemas).map((s) => ({ ...s, key: prefix + s.key, category: s.category || pluginId }))),
+      get: (key) => this.get(prefix + key),
+      set: (key, value) => this.set(prefix + key, value),
+    };
+  }
+}
+
+function read() {
+  try {
+    return JSON.parse(localStorage.getItem(STORAGE_KEY)) || {};
+  } catch {
+    return {};
+  }
+}
+function write(values) {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(values));
+  } catch { /* quota / private mode */ }
+}

package/packages/web/src/platform/spatialNav.js

@@ -0,0 +1,286 @@
+// Driving the drive with a remote control.
+//
+// A TV has four arrows, an OK button, and a Back button. It has no pointer and no Tab
+// key, so a layout that is perfectly usable with a mouse can be completely unreachable
+// from a sofa: focus lands somewhere, the arrows do nothing, and there is no way out.
+//
+// This maps the arrows onto GEOMETRY rather than DOM order. Pressing right should move
+// to the thing that is visually to the right, which is what someone holding a remote
+// expects and what tab order — written for reading order — does not give. Two rules keep
+// it from fighting the rest of the app:
+//
+//   1. If something already handled the key (the launcher's own list navigation, a text
+//      field's caret), it is left alone. `defaultPrevented` is the contract.
+//   2. Anything the app made clickable is reachable, whether or not the browser thinks
+//      it is focusable. A div with a click handler is a destination on a TV; the
+//      alternative is a list of files that cannot be opened.
+//
+// Only installed when the layout is 'tv'. On a desktop the pointer and Tab already work,
+// and remapping the arrow keys there would break scrolling.
+
+// Natively focusable, plus the app's own clickable rows. Keeping this list explicit
+// (rather than "anything with a click handler", which the DOM cannot tell us) means a
+// new clickable component is opted in deliberately.
+import { effect } from '../runtime.js';
+
+const NATIVE = 'a[href], button:not([disabled]), input:not([disabled]), select, textarea, [tabindex]:not([tabindex="-1"])';
+// `.setting-row` used to be listed here and has never existed — the rendered class is
+// `.setting`, and it isn't clickable anyway (its control is). Every entry below is
+// checked by probe15-tv-reach, so a renamed class fails a test instead of silently
+// dropping a destination.
+const APP_CLICKABLE = '.launch-item, .grid-tile, .sheet-row, .inbox-item, .plugin-card, .act-task, .act-issue, .chapter';
+const SELECTOR = `${NATIVE}, ${APP_CLICKABLE}`;
+
+// Keys a television sends for "back". The named ones are the web standard; the numbers
+// are Tizen (Samsung) and webOS (LG), which predate it and still ship.
+const BACK_KEYS = new Set(['BrowserBack', 'GoBack', 'Backspace']);
+const BACK_CODES = new Set([10009, 461]);
+
+const DIRS = { ArrowLeft: 'left', ArrowRight: 'right', ArrowUp: 'up', ArrowDown: 'down' };
+// Elements the browser already fires a click on when Enter is pressed.
+const ACTIVATES_ITSELF = new Set(['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA']);
+
+export class SpatialNavigationService {
+  /**
+   * @param {object} deps
+   * @param {import('./workbench.js').WorkbenchService} deps.workbench
+   * @param {import('./viewport.js').ViewportService} deps.viewport
+   * @param {Window} [deps.window]
+   */
+  constructor({ workbench, viewport, window: win = globalThis }) {
+    this.workbench = workbench;
+    this.viewport = viewport;
+    this.window = win;
+    this.active = false;
+    this._onKey = (e) => this.handleKey(e);
+    this._observer = null;
+    this._pending = 0;
+    this._bootstrapped = false;
+  }
+
+  /** Follow the viewport: arrows are remapped only while the TV layout is showing. */
+  install() {
+    if (this.viewport) effect(this.viewport.observe(), (vp) => this.setActive(vp.mode === 'tv'));
+    this.setActive(this.viewport?.state?.mode === 'tv');
+    return this;
+  }
+
+  setActive(on) {
+    if (on === this.active) return;
+    this.active = on;
+    // Bubble phase, so a component that wants the key gets it first and this only sees
+    // what nothing else claimed.
+    if (on) {
+      this.window.addEventListener?.('keydown', this._onKey);
+      this.#watchDom();
+      // The first frame may not have rendered yet; a TV with nothing focused is a TV
+      // where the first arrow press has no origin and appears to do nothing at all.
+      this.prime();
+      this.window.setTimeout?.(() => this.prime(), 60);
+    } else {
+      this.window.removeEventListener?.('keydown', this._onKey);
+      this._observer?.disconnect();
+      this._observer = null;
+      this._bootstrapped = false;
+    }
+  }
+
+  /**
+   * Make everything clickable focusable, and make sure something IS focused.
+   *
+   * Both halves matter. A div with a click handler is a destination on a TV but the
+   * browser will not focus it without a tabindex, and the app re-renders constantly, so
+   * this has to run again after every render rather than once at startup.
+   */
+  prime() {
+    this.candidates(); // stamps tabindex as a side effect
+    this.focusFirst();
+  }
+
+  #watchDom() {
+    const Obs = this.window.MutationObserver;
+    if (!Obs || this._observer) return;
+    // Coalesced to one pass per frame: the workbench replaces whole subtrees on a
+    // re-render, and stamping per mutation would be thousands of calls per second.
+    this._observer = new Obs(() => {
+      if (this._pending) return;
+      this._pending = this.window.requestAnimationFrame?.(() => {
+        this._pending = 0;
+        if (this.active) this.prime();
+      }) || 0;
+    });
+    this._observer.observe(this.window.document.body, { childList: true, subtree: true });
+  }
+
+  handleKey(e) {
+    if (!this.active || e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey) return;
+    const doc = this.window.document;
+    const from = doc.activeElement;
+
+    if (BACK_KEYS.has(e.key) || BACK_CODES.has(e.keyCode)) {
+      // Backspace with something to delete is a backspace. Getting this wrong throws
+      // away what someone typed on an on-screen keyboard. But an EMPTY field has nothing
+      // to delete, and a remote whose only Back button silently does nothing while a
+      // search box happens to hold focus is a remote that can't leave the screen.
+      if (e.key === 'Backspace' && isTextEntry(from) && (from.value ?? '').length > 0) return;
+      e.preventDefault();
+      this.goBack();
+      return;
+    }
+
+    const dir = DIRS[e.key];
+    if (!dir) {
+      // Enter on a real button already activates it. Enter on one of the app's clickable
+      // divs does nothing at all unless we say so — and note the test is the TAG, not
+      // "is it focusable": we stamped a tabindex on those divs ourselves, so asking
+      // whether they look focusable would answer yes for every one of them and OK would
+      // silently do nothing on every file in the list.
+      if (e.key === 'Enter' && from && !ACTIVATES_ITSELF.has(from.tagName) && from.matches(APP_CLICKABLE)) {
+        e.preventDefault();
+        from.click();
+      }
+      return;
+    }
+    // Inside a text field, left and right move the caret — until the caret runs out of
+    // text. Then the next press leaves the field. Without the second half the search box
+    // is a trap: focus goes in and the only way out is a key a remote doesn't have.
+    if ((dir === 'left' || dir === 'right') && isTextEntry(from) && !atTextEdge(from, dir)) return;
+
+    // A re-render can drop the focused node, leaving focus on <body> with no origin to
+    // navigate from. Any arrow press should recover rather than appear to do nothing.
+    const origin = from && from !== doc.body ? from : null;
+    const next = this.find(dir, origin);
+    if (!next) return;
+    e.preventDefault();
+    focusIt(next);
+  }
+
+  goBack() {
+    // An open overlay is what "back" means while one is open. Only past that does back
+    // mean the viewer stack, and only past THAT does it mean the browser.
+    if (this.workbench?.closeOverlays()) return;
+    this.window.history?.back?.();
+  }
+
+  /** Every candidate currently on screen, in whatever order the DOM gives them. */
+  candidates() {
+    const doc = this.window.document;
+    const out = [];
+    for (const el of doc.querySelectorAll(SELECTOR)) {
+      if (el.getAttribute?.('aria-hidden') === 'true' || el.hasAttribute?.('disabled')) continue;
+      const r = el.getBoundingClientRect();
+      if (r.width < 2 || r.height < 2) continue;
+      // Off-screen is not a destination — a remote can't scroll to something it can't
+      // move to, so anything outside the viewport is skipped until it scrolls in.
+      if (r.bottom < 0 || r.top > this.window.innerHeight || r.right < 0 || r.left > this.window.innerWidth) continue;
+      // The app's clickable rows aren't focusable until we make them so. Doing it here,
+      // lazily, keeps tabindex out of every component for a mode most users never see.
+      if (!el.matches(NATIVE) && !el.hasAttribute('tabindex')) el.setAttribute('tabindex', '0');
+      out.push({ el, rect: r });
+    }
+    return out;
+  }
+
+  /** The best thing to move to from `from` in `dir`, or null if there isn't one. */
+  find(dir, from) {
+    const all = this.candidates();
+    if (!all.length) return null;
+    const origin = from && from.getBoundingClientRect && from.getBoundingClientRect().width
+      ? from.getBoundingClientRect()
+      : null;
+    if (!origin) return all[0].el;
+
+    let best = null;
+    let bestScore = Infinity;
+    for (const { el, rect } of all) {
+      if (el === from) continue;
+      const score = scoreCandidate(origin, rect, dir);
+      if (score == null || score >= bestScore) continue;
+      bestScore = score;
+      best = el;
+    }
+    return best;
+  }
+
+  /**
+   * Put focus somewhere sensible, once.
+   *
+   * Deliberately only ONCE. Every re-render replaces DOM nodes and drops focus to
+   * <body>, and re-running this each time would repeatedly yank the selection back to
+   * the top of the screen while someone is halfway down a list. Recovering from lost
+   * focus is the arrow handler's job instead — it navigates from the first candidate
+   * when there is no origin, so a press always does something.
+   */
+  focusFirst() {
+    if (this._bootstrapped) return;
+    const doc = this.window.document;
+    if (doc?.activeElement && doc.activeElement !== doc.body) return;
+    const all = this.candidates();
+    if (!all.length) return;
+    // Search is what the drive is for, so that is where a remote should start.
+    const target = all.find((c) => c.el.classList?.contains('launch-input')) || all[0];
+    focusIt(target.el);
+    this._bootstrapped = true;
+  }
+}
+
+/** Is the caret already at the end it would be moving toward? */
+function atTextEdge(el, dir) {
+  const start = el.selectionStart;
+  const end = el.selectionEnd;
+  // contenteditable and some input types report nothing; treat "can't tell" as at the
+  // edge, since being unable to leave is the worse failure.
+  if (start == null || end == null) return true;
+  if (start !== end) return false; // a selection: the arrow collapses it
+  return dir === 'left' ? start === 0 : end >= (el.value ?? '').length;
+}
+
+function isTextEntry(el) {
+  if (!el) return false;
+  const tag = el.tagName;
+  if (tag === 'TEXTAREA') return true;
+  if (el.isContentEditable) return true;
+  if (tag !== 'INPUT') return false;
+  return !['checkbox', 'radio', 'button', 'submit', 'range', 'file'].includes(el.type);
+}
+
+function focusIt(el) {
+  el.focus?.({ preventScroll: true });
+  // A TV screen is mostly not where your eye is; scrolling the target to the middle is
+  // what makes a long list navigable without the selection hugging an edge.
+  el.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
+}
+
+/**
+ * How good a move is, lower being better — or null if the candidate isn't in that
+ * direction at all.
+ *
+ * Two distances matter and they are not equal. How far it is ALONG the direction of
+ * travel is the honest cost. How far it is OFF to the side is worse than it looks: a
+ * candidate that is 10px further right but 400px down is not "to the right" in any sense
+ * that matters to someone pressing right, so the sideways distance is weighted heavily.
+ */
+function scoreCandidate(from, to, dir) {
+  const vertical = dir === 'up' || dir === 'down';
+  // Near edges along the axis of travel.
+  const [fromNear, toNear] = vertical
+    ? (dir === 'down' ? [from.bottom, to.top] : [from.top, to.bottom])
+    : (dir === 'right' ? [from.right, to.left] : [from.left, to.right]);
+  const forward = dir === 'down' || dir === 'right';
+  const along = forward ? toNear - fromNear : fromNear - toNear;
+  // A tolerance, so items in the same row that overlap by a pixel or two still count.
+  if (along < -2) return null;
+
+  // Overlap on the cross axis is what makes something feel "in line". Where they overlap
+  // the sideways cost is zero; where they don't, it is the gap between them.
+  const [fs, fe, ts, te] = vertical
+    ? [from.left, from.right, to.left, to.right]
+    : [from.top, from.bottom, to.top, to.bottom];
+  const aside = Math.max(0, Math.max(fs, ts) - Math.min(fe, te));
+  // Also break ties by centre alignment, so a wide row doesn't beat the one directly
+  // under the cursor just because they both overlap.
+  const centerGap = Math.abs((fs + fe) / 2 - (ts + te) / 2);
+  return Math.max(0, along) + aside * 3 + centerGap * 0.2;
+}
+
+export { scoreCandidate };

package/packages/web/src/platform/viewport.js

@@ -0,0 +1,123 @@
+// What kind of screen is this, and how is it being driven?
+//
+// The drive runs on three shapes of device that want genuinely different chrome: a
+// desktop with a mouse and a left rail, a phone held in one hand, and a TV across the
+// room driven by a d-pad. This is the one place that decides which, so components ask
+// `state.vp.mode` instead of each inventing its own breakpoint — and so a single
+// override flips the whole shell at once.
+//
+// Detection is a guess, and guesses about TVs are especially bad (a browser on a set-top
+// box reports a large screen and, often, a mouse it does not have). So the guess is only
+// the default: `?ui=phone` in the URL, or the `workbench.layout` setting, wins outright.
+// Someone whose TV we mis-detect can fix it in Settings rather than living with it.
+
+import { cell, effect } from '../runtime.js';
+
+export const LAYOUTS = ['auto', 'desktop', 'phone', 'tv'];
+
+// Below this, the left rail plus a panel leaves nothing for the panel.
+const PHONE_MAX = 720;
+// A TV is a big screen you sit far away from. Only consulted alongside a UA hint —
+// width alone would call every large monitor a television.
+const TV_MIN = 1100;
+const TV_UA = /\b(smart-?tv|smarttv|appletv|googletv|android\s*tv|hbbtv|netcast|web0s|webos|tizen|viera|bravia|aquos|crkey|nettv|dtv|philipstv|roku|aft[a-z]{1,3})\b/i;
+
+/** Does the user agent say, unprompted, that it is a television? */
+export function looksLikeTv(ua = '', width = 0) {
+  if (!ua) return false;
+  return TV_UA.test(ua) && width >= TV_MIN;
+}
+
+export class ViewportService {
+  /**
+   * @param {object} [deps]
+   * @param {Window} [deps.window] the window to measure and listen to
+   * @param {import('./settings.js').SettingsService} [deps.settings]
+   * @param {import('./context.js').ContextKeyService} [deps.context]
+   */
+  constructor({ window: win = globalThis, settings = null, context = null } = {}) {
+    this.window = win;
+    this.settings = settings;
+    this.context = context;
+    // A URL override outranks the setting: it is how someone checks the phone layout on
+    // a laptop, and how the e2e suite drives each shell without a device farm.
+    this.urlOverride = readUrlOverride(win);
+    this.state = this.#measure();
+    this.cell = cell(this.state);
+    this._onResize = () => this.refresh();
+  }
+
+  observe() {
+    return this.cell;
+  }
+
+  /** Start listening. Separate from the constructor so tests can measure without hooks. */
+  install() {
+    this.window.addEventListener?.('resize', this._onResize);
+    this.window.addEventListener?.('orientationchange', this._onResize);
+    // `effect` runs now and on every change. The old form was
+     // `settings.observe().subscribe?.(…)` — optional-chained, so when `observe()`
+     // stopped returning something with `.subscribe` it would have become a silent
+     // no-op and the viewport would have stopped following its own setting.
+    if (this.settings) effect(this.settings.observe(), () => this.refresh());
+    this.#publish(this.state);
+    return this;
+  }
+
+  dispose() {
+    this.window.removeEventListener?.('resize', this._onResize);
+    this.window.removeEventListener?.('orientationchange', this._onResize);
+  }
+
+  refresh() {
+    const next = this.#measure();
+    const same = next.mode === this.state.mode && next.width === this.state.width
+      && next.height === this.state.height && next.coarse === this.state.coarse;
+    if (same) return;
+    this.state = next;
+    this.#publish(next);
+    this.cell.setValue(next);
+  }
+
+  #publish(vp) {
+    // Context keys so plugin `when` clauses and keybindings can target a form factor
+    // the same way they target a view.
+    this.context?.set('viewport.mode', vp.mode);
+    this.context?.set('viewport.phone', vp.mode === 'phone');
+    this.context?.set('viewport.tv', vp.mode === 'tv');
+    // The root element carries it too, so CSS can respond without every rule needing a
+    // media query that would disagree with the JS branch above it.
+    const el = this.window.document?.documentElement;
+    if (el) el.dataset.layout = vp.mode;
+  }
+
+  #measure() {
+    const win = this.window;
+    const width = win.innerWidth || 1280;
+    const height = win.innerHeight || 800;
+    const coarse = matches(win, '(pointer: coarse)');
+    const ua = win.navigator?.userAgent || '';
+    const forced = this.urlOverride || this.settings?.get?.('workbench.layout') || 'auto';
+    const mode = forced !== 'auto' && LAYOUTS.includes(forced) ? forced : detect({ width, coarse, ua });
+    return { mode, width, height, coarse, forced: forced !== 'auto' };
+  }
+}
+
+function detect({ width, coarse, ua }) {
+  if (looksLikeTv(ua, width)) return 'tv';
+  // Narrow is a phone whether or not the pointer is coarse — a desktop window dragged
+  // small has the same problem a phone does, and the layout that fits one fits the other.
+  if (width <= PHONE_MAX) return 'phone';
+  return 'desktop';
+}
+
+function matches(win, query) {
+  try { return !!win.matchMedia?.(query)?.matches; } catch { return false; }
+}
+
+function readUrlOverride(win) {
+  try {
+    const value = new URL(win.location.href).searchParams.get('ui');
+    return value && LAYOUTS.includes(value) ? value : null;
+  } catch { return null; }
+}

package/packages/web/src/platform/voice.js

@@ -0,0 +1,133 @@
+// Dictating into the search box.
+//
+// THE REMOTE'S MIC BUTTON IS NOT OURS. On every TV platform it belongs to the system:
+// webOS's SDK exposes no way for an app to listen to the Magic Remote, Tizen's voice
+// control is a packaged-app API that does not exist for a page in the TV browser, and
+// on Android TV the button raises Assistant. No key event reaches the document, so
+// there is nothing to intercept and no shortcut to bind.
+//
+// What the button DOES do is dictate into a focused text field, through the platform's
+// own keyboard. That is the whole opportunity: the mic is useful exactly when there is
+// somewhere for its text to land. `search.voice` therefore does not try to capture a
+// button — it makes sure the search field is open and focused, so the mic on the remote
+// has a target. That half works on every TV, with no API at all.
+//
+// This module is the OTHER half, for browsers that can transcribe themselves (Chrome,
+// so Android TV and the desktop). It is deliberately narrow:
+//
+//   ON-DEVICE ONLY. By default `SpeechRecognition` streams audio to the browser
+//   vendor's servers. Trove is a drive you host so that your files stay yours, and
+//   shipping a microphone that quietly forwards your voice to a third party would
+//   contradict the entire point of it. `processLocally` asks for recognition that never
+//   leaves the machine; a browser that cannot promise that is simply reported as
+//   unsupported, and the button is never offered.
+
+/**
+ * Resolved per call, not captured at import.
+ *
+ * A module-level constant would freeze the answer at load time, which is wrong twice
+ * over: the page may gain the API later (a polyfill, a flag flipped behind a restart),
+ * and a test could never stand in for it. Reading it when asked costs a property lookup.
+ */
+function impl() {
+  if (typeof window === 'undefined') return null;
+  return window.SpeechRecognition || window.webkitSpeechRecognition || null;
+}
+
+/**
+ * Whether this browser can transcribe WITHOUT sending audio anywhere.
+ *
+ * `available()` is the on-device half of the API; a browser that lacks it has no notion
+ * of local recognition, which for us is the same as having no recognition. Detecting
+ * the constructor alone would be the bug: every Chrome has that, and most of them would
+ * happily record you into a datacentre.
+ */
+export function canTranscribeLocally() {
+  const Impl = impl();
+  return !!Impl && typeof Impl.available === 'function';
+}
+
+const optionsFor = (lang) => ({ langs: [lang], processLocally: true });
+
+/**
+ * `'available' | 'downloadable' | 'downloading' | 'unavailable'`
+ *
+ * A language pack that is merely `downloadable` is not usable yet, and downloading one
+ * unasked would spend someone's bandwidth on a button they have not pressed.
+ */
+export async function localAvailability(lang = navigator.language || 'en-US') {
+  if (!canTranscribeLocally()) return 'unavailable';
+  try {
+    return await impl().available(optionsFor(lang));
+  } catch {
+    return 'unavailable';
+  }
+}
+
+/** Fetch the on-device language pack. Only ever called from an explicit user action. */
+export async function installLocal(lang = navigator.language || 'en-US') {
+  if (typeof impl()?.install !== 'function') return false;
+  try {
+    return await impl().install(optionsFor(lang));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Listen, and report what was heard.
+ *
+ * `onText(text, { final })` fires for interim results too, so the query updates as
+ * someone speaks rather than landing in one lump at the end — on a TV that feedback is
+ * the difference between "it is listening" and "did it hear me".
+ *
+ * @returns {{stop: () => void}}
+ */
+export function listen({ lang = navigator.language || 'en-US', onText, onEnd, onError } = {}) {
+  if (!canTranscribeLocally()) throw new Error('On-device speech recognition is not available here');
+  const rec = new (impl())();
+  rec.lang = lang;
+  rec.interimResults = true;
+  rec.continuous = false;
+  // Both spellings: `options` is the shape the explainer settled on, and shipping
+  // builds also read the flag straight off the instance. Setting one the browser
+  // ignores is harmless; setting neither would mean asking for local processing and
+  // silently getting the remote kind.
+  rec.options = optionsFor(lang);
+  rec.processLocally = true;
+
+  let stopped = false;
+  rec.onresult = (event) => {
+    let text = '';
+    let final = false;
+    for (let i = event.resultIndex; i < event.results.length; i++) {
+      text += event.results[i][0].transcript;
+      if (event.results[i].isFinal) final = true;
+    }
+    onText?.(text.trim(), { final });
+  };
+  // `no-speech` and `aborted` are what happens when someone changes their mind. They
+  // are not failures worth a toast.
+  rec.onerror = (event) => {
+    if (event.error === 'no-speech' || event.error === 'aborted') return;
+    onError?.(new Error(event.error || 'Speech recognition failed'));
+  };
+  rec.onend = () => { if (!stopped) { stopped = true; onEnd?.(); } };
+
+  try {
+    rec.start();
+  } catch (err) {
+    stopped = true;
+    onError?.(err);
+    onEnd?.();
+  }
+
+  return {
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      try { rec.stop(); } catch { /* already finished */ }
+      onEnd?.();
+    },
+  };
+}