@3sln/trove 0.0.2

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

@@ -0,0 +1,155 @@
+// The "speak to search" surface, and the part of it that works with no API at all.
+//
+// Two jobs, and they are independent on purpose:
+//
+//   1. PUT THE SEARCH FIELD UNDER THE MICROPHONE. A TV remote's mic dictates into
+//      whatever text field the platform keyboard is attached to, and does nothing at
+//      all when there isn't one. So the command opens the search surface and focuses
+//      its input. On webOS and Tizen that is the entire feature — the platform does
+//      the listening, the text arrives as ordinary input events, and Trove never asks
+//      for a microphone.
+//
+//   2. TRANSCRIBE OURSELVES, where the browser can do it on-device (see voice.js).
+//      Additive: if it isn't available the field is still focused and the remote's own
+//      mic still works.
+
+import { cell } from '../runtime.js';
+import { canTranscribeLocally, localAvailability, installLocal, listen } from './voice.js';
+
+export class VoiceSearchService {
+  /**
+   * @param {object} deps
+   * @param {import('./workbench.js').WorkbenchService} deps.workbench
+   * @param {object} deps.notifications
+   */
+  constructor({ workbench, notifications, settings } = {}) {
+    this.workbench = workbench;
+    this.notifications = notifications;
+    this.settings = settings;
+    this.session = null;
+    this.state = { supported: canTranscribeLocally(), status: 'unknown', listening: false };
+    this.cell = cell(this.state);
+  }
+
+  observe() {
+    return this.cell;
+  }
+  #set(patch) {
+    this.state = { ...this.state, ...patch };
+    this.cell.setValue(this.state);
+  }
+
+  /** Ask once whether an on-device language pack is ready, and remember the answer. */
+  async refresh() {
+    if (!this.state.supported) return 'unavailable';
+    const status = await localAvailability(this.#lang());
+    this.#set({ status });
+    return status;
+  }
+
+  #lang() {
+    return this.settings?.get?.('search.voiceLanguage') || navigator.language || 'en-US';
+  }
+
+  /** Can we offer a microphone button right now? */
+  canListen() {
+    return this.state.supported && (this.state.status === 'available' || this.state.status === 'downloadable');
+  }
+
+  /**
+   * The command behind `search.voice`.
+   *
+   * `focus` is what makes this worth binding on a TV even when we cannot transcribe:
+   * it is the difference between the remote's mic having a target and being swallowed
+   * by the platform assistant.
+   */
+  async run({ onText } = {}) {
+    this.openSearchSurface();
+    // Focus AFTER the surface has rendered — the input does not exist yet on the frame
+    // that opened it.
+    await this.focusInput();
+    if (!this.state.supported) return { listening: false, reason: 'unsupported' };
+
+    const status = this.state.status === 'unknown' ? await this.refresh() : this.state.status;
+    if (status === 'downloadable') {
+      // Pressing the button IS the consent to fetch it; nothing downloads before that.
+      this.notifications?.info('Downloading the on-device voice model — this happens once.');
+      const ok = await installLocal(this.#lang());
+      this.#set({ status: ok ? 'available' : 'unavailable' });
+      if (!ok) return { listening: false, reason: 'install-failed' };
+    } else if (status !== 'available') {
+      return { listening: false, reason: status };
+    }
+    return this.toggle({ onText });
+  }
+
+  /** Start listening, or stop if already. */
+  toggle({ onText } = {}) {
+    if (this.session) {
+      this.stop();
+      return { listening: false };
+    }
+    try {
+      this.session = listen({
+        lang: this.#lang(),
+        onText,
+        onEnd: () => { this.session = null; this.#set({ listening: false }); },
+        onError: (err) => {
+          this.session = null;
+          this.#set({ listening: false });
+          // A refused microphone is a decision, not a fault worth shouting about.
+          if (!/not-allowed|service-not-allowed|denied/i.test(err.message)) {
+            this.notifications?.warn(`Couldn't listen: ${err.message}`);
+          }
+        },
+      });
+      this.#set({ listening: true });
+      return { listening: true };
+    } catch (err) {
+      this.notifications?.warn(`Couldn't listen: ${err.message}`);
+      return { listening: false, reason: 'error' };
+    }
+  }
+
+  stop() {
+    this.session?.stop();
+    this.session = null;
+    this.#set({ listening: false });
+  }
+
+  /**
+   * Make sure a search field is on screen.
+   *
+   * Already on the launcher with nothing open → it is the search surface, use it. Any
+   * other view, or a file open over it → the modal, which is the one search box that
+   * can appear over anything.
+   */
+  openSearchSurface() {
+    const wb = this.workbench;
+    if (!wb) return;
+    const onLauncher = wb.state.activity === 'home' && !wb.nav?.state?.activeTabId;
+    if (onLauncher) wb.closeSearchModal?.();
+    else wb.openSearchModal();
+  }
+
+  /** @returns {Promise<boolean>} whether an input actually took focus */
+  focusInput({ tries = 12 } = {}) {
+    return new Promise((resolve) => {
+      let left = tries;
+      const attempt = () => {
+        const el = document.querySelector('.search-modal .launch-input') || document.querySelector('.launch-input');
+        if (el) {
+          el.focus();
+          // Put the caret at the end so dictation appends rather than overwriting a
+          // query someone already typed.
+          try { el.setSelectionRange(el.value.length, el.value.length); } catch { /* not a text input */ }
+          resolve(document.activeElement === el);
+          return;
+        }
+        if (--left <= 0) { resolve(false); return; }
+        requestAnimationFrame(attempt);
+      };
+      attempt();
+    });
+  }
+}

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

@@ -0,0 +1,162 @@
+// A parser/evaluator for "when" clauses — the same conditional mini-language VS
+// Code uses to gate commands, keybindings, and menu items on UI state. It reads
+// a context (a flat key→value map from the ContextKeyService) and returns a
+// boolean.
+//
+// Supported: bare keys (truthy), !key, ==, !=, >, <, >=, <=, =~ /re/, && , ||,
+// parentheses, string/number/boolean literals. Expressions are parsed once into
+// a predicate function and cached, so evaluation on every keydown is cheap.
+//
+// A key is either a core context key (`view.active`, `explorer.hasSelection`) or a
+// contribution URI naming a plugin's `register` — `trove+contrib:acme.com/docs/busy`.
+// Registers are addressed by their full URI precisely because they're contributions
+// like any other: a plugin can only ever gate on a value someone declared and owns.
+
+const cache = new Map();
+
+export function compileWhen(expr) {
+  if (!expr) return () => true;
+  if (cache.has(expr)) return cache.get(expr);
+  let fn;
+  try {
+    fn = new Parser(expr).parseExpression();
+  } catch (err) {
+    console.warn(`Invalid when clause: "${expr}" — ${err.message}`);
+    fn = () => false;
+  }
+  cache.set(expr, fn);
+  return fn;
+}
+
+export function evaluateWhen(expr, ctx) {
+  return compileWhen(expr)(ctx || {});
+}
+
+// Note the `trove+contrib:` alternative comes before the regex-literal one: a URI's
+// slashes would otherwise start a /…/ literal and swallow the rest of the expression.
+const TOKEN = /\s*(=~|==|!=|>=|<=|&&|\|\||[()!<>]|trove\+contrib:[A-Za-z0-9_./-]+|\/(?:\\.|[^/])*\/|'(?:\\.|[^'])*'|"(?:\\.|[^"])*"|[A-Za-z0-9_.:-]+)/y;
+
+class Parser {
+  constructor(src) {
+    this.src = src;
+    this.tokens = this.#lex(src);
+    this.pos = 0;
+  }
+  #lex(src) {
+    const out = [];
+    let i = 0;
+    TOKEN.lastIndex = 0;
+    while (i < src.length) {
+      TOKEN.lastIndex = i;
+      const m = TOKEN.exec(src);
+      if (!m || m.index == null) {
+        if (!src.slice(i).trim()) break;
+        throw new Error(`Unexpected "${src.slice(i)}"`);
+      }
+      out.push(m[1]);
+      i = TOKEN.lastIndex;
+    }
+    return out;
+  }
+  #peek() {
+    return this.tokens[this.pos];
+  }
+  #next() {
+    return this.tokens[this.pos++];
+  }
+  #eat(t) {
+    if (this.#peek() !== t) throw new Error(`Expected "${t}"`);
+    this.pos++;
+  }
+
+  parseExpression() {
+    const fn = this.#or();
+    if (this.pos !== this.tokens.length) throw new Error(`Trailing "${this.#peek()}"`);
+    return fn;
+  }
+  #or() {
+    let left = this.#and();
+    while (this.#peek() === '||') {
+      this.#next();
+      const right = this.#and();
+      const l = left;
+      left = (c) => l(c) || right(c);
+    }
+    return left;
+  }
+  #and() {
+    let left = this.#unary();
+    while (this.#peek() === '&&') {
+      this.#next();
+      const right = this.#unary();
+      const l = left;
+      left = (c) => l(c) && right(c);
+    }
+    return left;
+  }
+  #unary() {
+    if (this.#peek() === '!') {
+      this.#next();
+      const operand = this.#unary();
+      return (c) => !operand(c);
+    }
+    return this.#comparison();
+  }
+  #comparison() {
+    const left = this.#primary();
+    const op = this.#peek();
+    if (['==', '!=', '>=', '<=', '>', '<', '=~'].includes(op)) {
+      this.#next();
+      if (op === '=~') {
+        const reTok = this.#next();
+        const re = parseRegex(reTok);
+        return (c) => re.test(String(left(c) ?? ''));
+      }
+      const right = this.#primary();
+      return (c) => compare(op, left(c), right(c));
+    }
+    // Bare value → truthiness.
+    return (c) => truthy(left(c));
+  }
+  #primary() {
+    const t = this.#next();
+    if (t === undefined) throw new Error('Unexpected end');
+    if (t === '(') {
+      const inner = this.#or();
+      this.#eat(')');
+      return inner;
+    }
+    if (t === 'true') return () => true;
+    if (t === 'false') return () => false;
+    if (/^-?\d+(\.\d+)?$/.test(t)) {
+      const n = Number(t);
+      return () => n;
+    }
+    if (t[0] === "'" || t[0] === '"') {
+      const s = t.slice(1, -1).replace(/\\(.)/g, '$1');
+      return () => s;
+    }
+    // A context key.
+    return (c) => c[t];
+  }
+}
+
+function parseRegex(tok) {
+  const m = /^\/((?:\\.|[^/])*)\/([a-z]*)$/.exec(tok);
+  if (!m) throw new Error(`Bad regex ${tok}`);
+  return new RegExp(m[1], m[2]);
+}
+function truthy(v) {
+  return !(v === undefined || v === null || v === false || v === '' || v === 0);
+}
+function compare(op, a, b) {
+  switch (op) {
+    case '==': return a == b; // eslint-disable-line eqeqeq
+    case '!=': return a != b; // eslint-disable-line eqeqeq
+    case '>': return a > b;
+    case '<': return a < b;
+    case '>=': return a >= b;
+    case '<=': return a <= b;
+  }
+  return false;
+}

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

@@ -0,0 +1,156 @@
+// WorkbenchService — the shell's ephemeral UI state (not the file data, which
+// ngin owns). The main panel is a STACK of panels: the base is the root search
+// (launcher); opening a file pushes a viewer panel; back pops. The stack is mirrored
+// into the browser history (pushState/popState) so back/forward navigate it. A
+// double-shift opens a modal search overlay; picking from it resets the stack.
+// It also mirrors key bits into the ContextKeyService for when-clauses.
+
+import { cell } from '../runtime.js';
+import { OverlayService, wrapIndex } from './overlay.js';
+import { NavigationService } from './navigation.js';
+
+export class WorkbenchService {
+  constructor(context) {
+    this.context = context;
+    // Two focused sub-services own their own state + subject; the workbench delegates
+    // and coordinates the couplings across them (Esc close-order, opening a file).
+    this.overlay = new OverlayService(context);
+    this.nav = new NavigationService(context);
+    this.state = {
+      activity: 'home', // home (stack) | plugins | settings
+      sidebarVisible: true,
+      launch: { query: '', index: 0 }, // the launcher's query
+      searchModal: false, // the double-shift modal search overlay
+      infoPanel: false,
+      // Phone chrome: which bottom sheet is up, if any ('status' | 'more'). A phone has
+      // no room for a permanent status bar or a left rail, so both fold into a sheet
+      // that is pulled up on demand.
+      sheet: null,
+    };
+    this.cell = cell(this.state);
+  }
+
+  observe() {
+    return this.cell;
+  }
+  observeOverlay() {
+    return this.overlay.observe();
+  }
+  observeNav() {
+    return this.nav.observe();
+  }
+  #set(patch) {
+    this.state = { ...this.state, ...patch };
+    this.cell.setValue(this.state);
+  }
+
+  /**
+   * Say that something the shell renders from changed without going through here.
+   *
+   * There is exactly one such thing — `platform.capabilities`, which arrives from the
+   * server after boot and is read straight off the platform by the status bar. A cell
+   * drops a write of the value it already holds, so re-pushing `state` is not a nudge;
+   * a fresh object is.
+   */
+  touch() {
+    this.#set({});
+  }
+
+  // --- overlay delegations (state lives in OverlayService) -------------------
+  openPalette(mode, query) { this.overlay.openPalette(mode, query); }
+  setPaletteQuery(query) { this.overlay.setPaletteQuery(query); }
+  movePalette(delta, count) { this.overlay.movePalette(delta, count); }
+  closePalette() { this.overlay.closePalette(); }
+  showDialog(dialog) { this.overlay.showDialog(dialog); }
+  updateDialog(patch) { this.overlay.updateDialog(patch); }
+  closeDialog() { this.overlay.closeDialog(); }
+  showContextMenu(x, y, items) { this.overlay.showContextMenu(x, y, items); }
+  closeContextMenu() { this.overlay.closeContextMenu(); }
+  openPluginPanel(pluginId) { this.overlay.openPluginPanel(pluginId); }
+  closePluginPanel() { this.overlay.closePluginPanel(); }
+
+  // --- navigation delegations (state lives in NavigationService) -------------
+  activeTab() { return this.nav.activeTab(); }
+  back() { this.nav.back(); }
+  pop() { this.nav.pop(); }
+  closeTab(id) { this.nav.closeTab(id); }
+  updateTabNode(node) { this.nav.updateTabNode(node); }
+  onPopState(e) { this.nav.onPopState(e); }
+
+  setActivity(activity) {
+    this.#set({ activity, sidebarVisible: true });
+    this.context.set('view.active', activity);
+  }
+  /** Return to the launcher home (reset the panel stack to the base search). */
+  showHome() {
+    this.#set({ activity: 'home', searchModal: false });
+    this.nav.reset();
+    this.context.set('view.active', 'home');
+  }
+
+  // --- launcher --------------------------------------------------------------
+  setLaunchQuery(query) {
+    this.#set({ launch: { query, index: 0 } });
+  }
+  moveLaunch(delta, count) {
+    if (!count) return;
+    this.#set({ launch: { ...this.state.launch, index: wrapIndex(this.state.launch.index, delta, count) } });
+  }
+  /** The command palette's highlighted row. Missing entirely, so every `mouseenter`
+   *  threw and the highlight never followed the pointer — hover row 5, press Enter,
+   *  run row 0. */
+  setPaletteIndex(index) {
+    this.overlay.setPaletteIndex?.(index);
+  }
+  setLaunchIndex(index) {
+    this.#set({ launch: { ...this.state.launch, index } });
+  }
+
+  // --- modal search (double-shift) ------------------------------------------
+  openSearchModal() {
+    this.#set({ searchModal: true, launch: { query: '', index: 0 } });
+    this.context.set('searchModal.open', true);
+  }
+  closeSearchModal() {
+    this.#set({ searchModal: false });
+    this.context.set('searchModal.open', false);
+  }
+
+  /**
+   * Open a file into the viewer stack (delegates to NavigationService). Coordinates the
+   * shell state the nav service can't own: switch to the home activity and close the
+   * modal search overlay.
+   */
+  openFile(node, openerId, opts = {}) {
+    this.#set({ activity: 'home', searchModal: false });
+    this.nav.openFile(node, openerId, opts);
+  }
+  /** Raise (or swap, or drop) the phone bottom sheet. Tapping the open one closes it. */
+  openSheet(name) {
+    this.#set({ sheet: this.state.sheet === name ? null : name });
+    this.context.set('sheet.open', this.state.sheet || '');
+  }
+  closeSheet() {
+    if (!this.state.sheet) return;
+    this.#set({ sheet: null });
+    this.context.set('sheet.open', '');
+  }
+  toggleInfoPanel(force) {
+    this.#set({ infoPanel: force ?? !this.state.infoPanel });
+    this.context.set('infoPanel.open', this.state.infoPanel);
+  }
+
+  /** Close any transient overlay (Esc), in priority order across overlay + stack.
+   *  Returns true if something closed. */
+  closeOverlays() {
+    const o = this.overlay.state;
+    if (o.contextMenu) return this.overlay.closeContextMenu(), true;
+    if (o.dialog) return this.overlay.closeDialog(), true;
+    if (this.state.sheet) return this.closeSheet(), true;
+    if (this.state.searchModal) return this.closeSearchModal(), true;
+    if (o.palette) return this.overlay.closePalette(), true;
+    if (o.pluginPanel) return this.overlay.closePluginPanel(), true;
+    if (this.nav.state.stack.length > 1) return this.nav.back(), true; // pop the top viewer panel
+    return false;
+  }
+}

package/packages/web/src/runtime.js

@@ -0,0 +1,73 @@
+// Wire the 3sln stack for Trove's web client.
+//
+//   - dodo: the VDOM (h, reconcile, element helpers, alias/special)
+//   - dodo/reactive: cells, and the `watch` component that renders one
+//
+// bones is gone; what Trove used of it — `watch`, a writable subject, and a way
+// to combine several of them — moved into dodo as the **Cell** protocol:
+//
+//   { onDirty(fn) -> unsubscribe, getValue() -> any }
+//
+// That is a smaller contract than the observable it replaces, and the difference
+// shows up in two places we care about. It is push-to-invalidate / pull-to-read,
+// so any number of invalidations in one frame coalesce into a single render;
+// and a cell always HAS a value, so a `watch` renders its store's current state
+// on the first pass instead of waiting for an emission that already happened.
+//
+// `PENDING` is how a cell says "no value yet" — `watch` renders its placeholder
+// instead of calling the builder. An error is reported by THROWING from
+// `getValue()`, which `watch` renders as its error view. Both matter for
+// `fromAsync` below, which is the only shape of ours the module does not ship.
+
+import * as dodo from '@3sln/dodo';
+import {
+  watch, cell, derive, constant, mapCell, connectable,
+  fromObservable, toObservable, effect, isCell, readCell, PENDING,
+} from '@3sln/dodo/reactive';
+
+export const dd = dodo;
+
+export {
+  watch, cell, derive, constant, mapCell, connectable,
+  fromObservable, toObservable, effect, isCell, readCell, PENDING,
+};
+
+/**
+ * A cell backed by one async call: `PENDING` until it settles, the value after,
+ * and a throw from `getValue()` if it rejects — which is exactly the vocabulary
+ * `watch`'s `placeholder` and `error` options are written against.
+ *
+ * The work starts on the first listener, not at construction, so building one
+ * for a view that is never rendered costs nothing. It runs ONCE: a cell that
+ * refetched every time its last watcher went away and came back would reload a
+ * document on every remount.
+ */
+export function fromAsync(work) {
+  let state = { status: 'idle' };
+  return connectable(
+    (notify) => {
+      if (state.status === 'idle') {
+        state = { status: 'running' };
+        Promise.resolve()
+          .then(work)
+          .then(
+            (value) => { state = { status: 'done', value }; notify(); },
+            (error) => { state = { status: 'failed', error }; notify(); },
+          );
+      }
+      // Nothing to disconnect: a promise cannot be un-awaited, and the result is
+      // kept so a later listener reads it rather than starting again.
+      return () => {};
+    },
+    () => {
+      if (state.status === 'failed') throw state.error;
+      return state.status === 'done' ? state.value : PENDING;
+    },
+  );
+}
+
+/** The reactive API as one object, for `platform.reactive` (and plugin-facing code). */
+export const reactive = {
+  watch, cell, derive, constant, mapCell, connectable,
+  fromObservable, fromAsync, toObservable, effect, isCell, readCell, PENDING,
+};