@reddb-io/ui 0.3.0 → 0.3.2

package/src/lib/StatusBar.svelte

@@ -2,7 +2,7 @@
   import { useRouter } from './router.svelte'
   import { connection } from './connections.svelte'
   import { pendingChanges } from './pending-changes.svelte'
-  import { ArrowRight, FilePenLine, Lock } from 'lucide-svelte'
+  import { ArrowRight, FilePenLine, Lock, Terminal } from 'lucide-svelte'
   import { readBuildInfo } from './build-info'
 
   const build = readBuildInfo()
@@ -48,6 +48,12 @@
     window.dispatchEvent(new CustomEvent('red:open-connect'))
   }
 
+  // Toggle the instrumented developer console (#128). Neutral chrome — the
+  // console never claims the accent, matching one-accent-per-screen.
+  function toggleConsole() {
+    window.dispatchEvent(new CustomEvent('red:toggle-dev-console'))
+  }
+
   function openCluster(e: MouseEvent) {
     const target = e.target as HTMLElement | null
     if (target?.closest('button, a, [data-no-nav]')) return
@@ -154,6 +160,18 @@
     </button>
   {/if}
 
+  <button
+    type="button"
+    onclick={toggleConsole}
+    data-no-nav
+    aria-label="Toggle developer console"
+    title="Developer console — every query and HTTP call, with timing and row counts"
+    class="inline-flex items-center gap-1 px-3 text-fg-3 hover:text-fg-1 hover:bg-bg-2/60 transition-colors cursor-pointer bg-transparent border-0 border-l border-line-1"
+  >
+    <Terminal class="size-3" />
+    <span>Console</span>
+  </button>
+
   <span
     class="inline-flex items-center px-3 shrink-0 font-mono text-fg-3 border-l border-line-1 select-none"
     title={`red-ui ${build.version} · ${build.gitSha} · built ${build.buildTime}`}

package/src/lib/Topbar.svelte

@@ -2,7 +2,7 @@
   import { Kbd } from '@reddb-io/ui-kit'
   import ConnectDropdown from './ConnectDropdown.svelte'
   import ActivityIndicator from './ActivityIndicator.svelte'
-  import { Search, Sun, Moon, Network, Database, FileCode2, Shield, Settings2 } from 'lucide-svelte'
+  import { Search, Sun, Moon, Network, Database, FileCode2, Shield, Settings2, LineChart, Sparkles } from 'lucide-svelte'
   import { theme } from './theme.svelte'
   import { useRouter } from './router.svelte'
 
@@ -14,10 +14,12 @@
     window.dispatchEvent(new KeyboardEvent('keydown', { key: 'k', metaKey: true, ctrlKey: true, bubbles: true }))
   }
 
+  const onAsk = $derived(router.view === 'ask')
   const onQuery = $derived(router.view === 'query')
   const onCollections = $derived(router.view === 'collections')
   const onCluster = $derived(router.view === 'cluster')
   const onSecurity = $derived(router.view === 'security')
+  const onAnalytics = $derived(router.view === 'analytics')
   const onSettings = $derived(router.view === 'settings')
 </script>
 
@@ -38,6 +40,19 @@
       <div class="w-px h-[18px] bg-line-2"></div>
     {/if}
     <nav class="flex items-center gap-0.5">
+      <a
+        href={router.href({ view: 'ask' })}
+        onclick={(e) => router.go({ view: 'ask' }, e)}
+        title="Ask — grounded natural-language query"
+        aria-current={onAsk ? 'page' : undefined}
+        class={[
+          'inline-flex items-center gap-1.5 h-7 px-2 rounded-md text-xs no-underline transition-colors',
+          onAsk ? 'bg-bg-2 text-accent' : 'text-fg-2 hover:text-fg-0 hover:bg-bg-2',
+        ].join(' ')}
+      >
+        <Sparkles class="size-3.5" />
+        <span>Ask</span>
+      </a>
       <a
         href={router.href({ view: 'query' })}
         onclick={(e) => router.go({ view: 'query' }, e)}
@@ -90,6 +105,19 @@
         <Shield class="size-3.5" />
         <span>Security</span>
       </a>
+      <a
+        href={router.href({ view: 'analytics' })}
+        onclick={(e) => router.go({ view: 'analytics' }, e)}
+        title="Analytics"
+        aria-current={onAnalytics ? 'page' : undefined}
+        class={[
+          'inline-flex items-center gap-1.5 h-7 px-2 rounded-md text-xs no-underline transition-colors',
+          onAnalytics ? 'bg-bg-2 text-fg-0' : 'text-fg-2 hover:text-fg-0 hover:bg-bg-2',
+        ].join(' ')}
+      >
+        <LineChart class="size-3.5" />
+        <span>Analytics</span>
+      </a>
       <a
         href={router.href({ view: 'settings' })}
         onclick={(e) => router.go({ view: 'settings' }, e)}

package/src/lib/Workspace.svelte

@@ -6,6 +6,9 @@
   // The SvelteKit Surface wraps this same component with a Kit-backed router.
   import { onMount, untrack } from 'svelte'
   import Splash from './Splash.svelte'
+  import LoadingOverlay from './LoadingOverlay.svelte'
+  import DevConsole from './DevConsole.svelte'
+  import GlobalProgressBar from './GlobalProgressBar.svelte'
   import Topbar from './Topbar.svelte'
   import StatusBar from './StatusBar.svelte'
   import CommandPalette from './CommandPalette.svelte'
@@ -14,10 +17,11 @@
   import PendingChangesPanel from './PendingChangesPanel.svelte'
   import CollectionsView from './CollectionsView.svelte'
   import ClusterView from './ClusterView.svelte'
+  import AskView from './AskView.svelte'
   import SecurityView from './SecurityView.svelte'
   import SettingsView from './SettingsView.svelte'
   import Appearance from './Appearance.svelte'
-  import { connection, setConnectionProvider } from './connections.svelte'
+  import { connection, makeCustomConnection, setConnectionProvider } from './connections.svelte'
   import { runQueryPreferStream, type ConnectionProvider } from '#reddb'
   import { theme, type Theme } from './theme.svelte'
   import { skins } from './skins/skins.svelte'
@@ -28,6 +32,7 @@
   import { detectCapability } from './capability'
   import { defaultSubpage } from './collection-pages'
   import { createStateRouter, pathToLocation, setRouter, type Router, type View } from './router.svelte'
+  import { workspaceSession, type WorkspaceSnapshot } from './workspace-session'
 
   let {
     router: injectedRouter,
@@ -79,6 +84,27 @@
     }
   }
 
+  function buildSnapshot(): WorkspaceSnapshot {
+    return {
+      view: router.view,
+      collection: router.collection,
+      subpage: router.subpage,
+      tabs: tabs.tabs,
+      activeTabId: tabs.activeId,
+    }
+  }
+
+  function applySnapshot(snap: WorkspaceSnapshot): void {
+    if (snap.tabs.length > 0) tabs.hydrate(snap.tabs, snap.activeTabId)
+    router.go(
+      snap.collection
+        ? { view: 'collection', collection: snap.collection, subpage: snap.subpage ?? 'table' }
+        : { view: snap.view },
+      undefined,
+      true,
+    )
+  }
+
   onMount(() => {
     if (connectionProvider) {
       // Host-injected provider (#33): adopt its authenticated connection.
@@ -89,7 +115,13 @@
       // Connection Bootstrap: one boot resolver handles Tauri IPC, host globals,
       // the Open Contract URL/hash, and finally persisted standalone state.
       void connection.bootstrap().then((route) => {
-        if (route) navigateToBootRoute(route)
+        if (route) {
+          navigateToBootRoute(route)
+        } else {
+          // No explicit boot route — restore the last workspace session.
+          const snap = workspaceSession.restore()
+          if (snap) applySnapshot(snap)
+        }
       })
     }
   })
@@ -103,6 +135,42 @@
     return () => window.removeEventListener('red:open-pending-changes', handler as EventListener)
   })
 
+  // Runtime deep-link routing: subscribe to Tauri "deep-link" events so that
+  // clicking a red:// URL while the app is already running focuses the window
+  // (handled Rust-side via single-instance) and routes to the target connection.
+  // Boot-time deep links go through connection.bootstrap(); this path handles
+  // everything that arrives after the app is already mounted.
+  onMount(() => {
+    if (typeof window === 'undefined') return
+    if (!('__TAURI_INTERNALS__' in window || '__TAURI__' in window)) return
+
+    let unlisten: (() => void) | undefined
+
+    void import('@tauri-apps/api/event')
+      .then(({ listen }) =>
+        listen<string[]>('deep-link', async (event) => {
+          const raw = event.payload?.[0]
+          if (!raw) return
+
+          // Extract ?to= route before normalizing the connection target.
+          let target = raw
+          let route: string | null = null
+          try {
+            const equiv = raw.replace(/^reds?(\+[a-z]+)?:\/\//, 'http://')
+            const u = new URL(equiv)
+            route = u.searchParams.get('to')
+            if (route) target = raw.split('?')[0]
+          } catch {}
+
+          await connection.tryConnect(makeCustomConnection(target))
+          if (route) navigateToBootRoute(route)
+        })
+      )
+      .then((fn) => { unlisten = fn })
+
+    return () => { unlisten?.() }
+  })
+
   // Wire the commit executor to the active client. Re-binds whenever the
   // underlying client changes (connect / disconnect / switch).
   $effect(() => {
@@ -112,7 +180,9 @@
       queryTabs.setExecutor(null)
       return
     }
-    queryTabs.setExecutor((sql) => runQueryPreferStream(client, sql))
+    queryTabs.setExecutor((sql, options) =>
+      runQueryPreferStream(client, sql, options)
+    )
     pendingChanges.setExecutor(async (changes) =>
       Promise.all(
         changes.map(async (c): Promise<CommitOutcome> => {
@@ -161,6 +231,47 @@
     if (secureStore.store) connection.hydrateUrls()
   })
 
+  // Autosave: debounce-schedule a snapshot on every router/tab state change.
+  // Guard on `booted` so we don't snapshot the blank pre-splash state.
+  $effect(() => {
+    if (!booted) return
+    const snap = buildSnapshot()
+    workspaceSession.schedule(snap)
+  })
+
+  // Flush immediately on page hide / window blur so an edit made
+  // right before closing is never lost to the debounce window.
+  onMount(() => {
+    const flush = () => { if (booted) workspaceSession.flush(buildSnapshot()) }
+    document.addEventListener('visibilitychange', flush)
+    window.addEventListener('blur', flush)
+    return () => {
+      document.removeEventListener('visibilitychange', flush)
+      window.removeEventListener('blur', flush)
+    }
+  })
+
+  // Tauri close-request: flush, then destroy the window. The Rust watchdog
+  // races this — if the webview hangs, it force-destroys after its bound.
+  onMount(() => {
+    if (typeof window === 'undefined') return
+    if (!('__TAURI_INTERNALS__' in window || '__TAURI__' in window)) return
+
+    let unlisten: (() => void) | undefined
+
+    void import('@tauri-apps/api/event')
+      .then(({ listen }) =>
+        listen<void>('close-request', async () => {
+          workspaceSession.flush(buildSnapshot())
+          const { getCurrentWindow } = await import('@tauri-apps/api/window')
+          await getCurrentWindow().destroy()
+        }),
+      )
+      .then((fn) => { unlisten = fn })
+
+    return () => { unlisten?.() }
+  })
+
   function openNewQuery() {
     const label = queryTabs.nextLabel()
     const tab = tabs.open({ kind: 'query', label, key: label }, true)
@@ -236,14 +347,25 @@
 {#if !booted}
   <Splash onDone={() => (booted = true)} />
 {:else}
-  <div class="app grid grid-rows-[44px_32px_1fr] h-screen">
+  <div class="app relative grid grid-rows-[44px_32px_1fr] h-screen">
+    <GlobalProgressBar />
     <Topbar showConnect={showConnect} />
     <StatusBar />
     <main class="relative overflow-hidden z-[1]">
-      {#if router.view === 'cluster'}
+      {#if router.view === 'ask'}
+        <AskView />
+      {:else if router.view === 'cluster'}
         <ClusterView />
       {:else if router.view === 'security'}
         <SecurityView />
+      {:else if router.view === 'analytics'}
+        <!-- Lazy: LayerChart + d3 are heavy, so the charting bundle only
+             loads when the user actually opens Analytics. -->
+        {#await import('./AnalyticsView.svelte')}
+          <div class="flex h-full items-center justify-center font-mono text-[12px] text-fg-3">loading analytics…</div>
+        {:then { default: AnalyticsView }}
+          <AnalyticsView />
+        {/await}
       {:else if router.view === 'settings'}
         <SettingsView />
       {:else if router.view === 'appearance'}
@@ -258,3 +380,12 @@
     <PendingChangesPanel open={pendingOpen} onClose={() => (pendingOpen = false)} />
   </div>
 {/if}
+
+<!-- Step-logged loading overlay (#127): sits above the shell during a slow
+     connect/boot; self-hides once the open resolves and never flashes on fast
+     opens. -->
+<LoadingOverlay />
+
+<!-- Instrumented developer console (#128): a collapsible, accent-free log of
+     every query/HTTP call the client made, toggled from the StatusBar. -->
+<DevConsole />

package/src/lib/activity.svelte.ts

@@ -16,61 +16,65 @@
 // without untrack, the effect would track those as dependencies and our
 // own writes would re-fire it — infinite loop (`effect_update_depth_exceeded`).
 
-import { untrack } from 'svelte'
+import { untrack } from "svelte";
 
 export interface ActivityEntry {
-  id: number
-  label: string
-  startedAt: number
-  durationMs: number | null
-  status: 'pending' | 'ok' | 'error'
-  error?: string
+  id: number;
+  label: string;
+  startedAt: number;
+  durationMs: number | null;
+  status: "pending" | "ok" | "error";
+  error?: string;
 }
 
-const MAX_LOG = 20
+const MAX_LOG = 20;
 
 class ActivityStore {
-  inflight = $state(0)
-  log = $state<ActivityEntry[]>([])
-  private nextId = 1
+  inflight = $state(0);
+  active = $derived(this.inflight > 0);
+  log = $state<ActivityEntry[]>([]);
+  private nextId = 1;
 
   async track<T>(label: string, op: () => Promise<T>): Promise<T> {
-    const id = this.nextId++
+    const id = this.nextId++;
     const entry: ActivityEntry = {
       id,
       label,
       startedAt: Date.now(),
       durationMs: null,
-      status: 'pending',
-    }
+      status: "pending",
+    };
     untrack(() => {
-      this.log = [entry, ...this.log].slice(0, MAX_LOG)
-      this.inflight += 1
-    })
+      this.log = [entry, ...this.log].slice(0, MAX_LOG);
+      this.inflight += 1;
+    });
     try {
-      const result = await op()
+      const result = await op();
       untrack(() =>
-        this.update(id, { durationMs: Date.now() - entry.startedAt, status: 'ok' }),
-      )
-      return result
+        this.update(id, {
+          durationMs: Date.now() - entry.startedAt,
+          status: "ok",
+        })
+      );
+      return result;
     } catch (err) {
       untrack(() =>
         this.update(id, {
           durationMs: Date.now() - entry.startedAt,
-          status: 'error',
+          status: "error",
           error: (err as Error).message,
-        }),
-      )
-      throw err
+        })
+      );
+      throw err;
     } finally {
       untrack(() => {
-        this.inflight = Math.max(0, this.inflight - 1)
-      })
+        this.inflight = Math.max(0, this.inflight - 1);
+      });
     }
   }
 
   private update(id: number, patch: Partial<ActivityEntry>) {
-    this.log = this.log.map((e) => (e.id === id ? { ...e, ...patch } : e))
+    this.log = this.log.map((e) => (e.id === id ? { ...e, ...patch } : e));
   }
 
   /** Panic button for when the indicator gets stuck out of sync with
@@ -79,13 +83,18 @@ class ActivityStore {
   reset() {
     untrack(() => {
       this.log = this.log.map((e) =>
-        e.status === 'pending'
-          ? { ...e, status: 'error', error: 'reset by user', durationMs: Date.now() - e.startedAt }
-          : e,
-      )
-      this.inflight = 0
-    })
+        e.status === "pending"
+          ? {
+              ...e,
+              status: "error",
+              error: "reset by user",
+              durationMs: Date.now() - e.startedAt,
+            }
+          : e
+      );
+      this.inflight = 0;
+    });
   }
 }
 
-export const activity = new ActivityStore()
+export const activity = new ActivityStore();

package/src/lib/collection-preview.ts

@@ -0,0 +1,14 @@
+import type { Capability } from "./renderers/types";
+
+export function safeCollectionName(collection: string): string {
+  return collection.replace(/[^A-Za-z0-9_./-]/g, "");
+}
+
+export function collectionPreviewQuery(
+  collection: string,
+  capability: Capability | undefined
+): string {
+  const safe = safeCollectionName(collection);
+  if (capability === "kv") return `LIST KV ${safe} LIMIT 200`;
+  return `SELECT * FROM ${safe} LIMIT 200`;
+}

package/src/lib/connections.svelte.ts

@@ -11,6 +11,7 @@
 import {
   BROWSER_TRANSPORTS,
   DESKTOP_TRANSPORTS,
+  DesktopError,
   EMPTY_SERVER_CAPABILITIES,
   LocalUrlProvider,
   RedClient,
@@ -18,6 +19,7 @@ import {
   isUrlReachable,
   parseBootParams,
   resolveConnectionBootstrap,
+  transportForUrl,
   type Connection,
   type ConnectionBootstrap,
   type ConnectionProvider,
@@ -34,6 +36,7 @@ import {
 } from "./connection-history";
 import { secureStore } from "./secureStore.svelte";
 import { activity } from "./activity.svelte";
+import { loading } from "./loading.svelte";
 
 export type { HistoryEntry } from "./connection-history";
 
@@ -173,13 +176,82 @@ export function makeCustomConnection(input: string): ConnectionPreset {
 // Transport reachability is a Surface property (#34, ADR-0003): a Tauri shell
 // can open native unix/embedded connections the browser can't. Detect the
 // Surface here so the default provider declares the right reachable set.
-function surfaceTransports(): Transport[] {
-  const tauri =
+function isTauriSurface(): boolean {
+  return (
     typeof window !== "undefined" &&
-    ("__TAURI_INTERNALS__" in window || "__TAURI__" in window);
-  return [...(tauri ? DESKTOP_TRANSPORTS : BROWSER_TRANSPORTS)];
+    ("__TAURI_INTERNALS__" in window || "__TAURI__" in window)
+  );
+}
+
+function surfaceTransports(): Transport[] {
+  return [...(isTauriSurface() ? DESKTOP_TRANSPORTS : BROWSER_TRANSPORTS)];
 }
 
+/**
+ * Open a `file://` connection by asking the Tauri shell to spawn a local
+ * file-backed reddb sidecar; returns the `http://127.0.0.1:<port>` URL the
+ * HTTP client then talks to.
+ *
+ * Tauri-ness is checked HERE, at call time — not when the provider is built.
+ * In `tauri dev` this module can evaluate before Tauri injects its globals, so
+ * gating the resolver at construction left it unwired and `file://` fell
+ * through to a raw fetch ("Load failed"). At connect time the IPC bridge is
+ * always present. The browser has no filesystem/process access, so we fail
+ * with a clear message there instead.
+ */
+async function tauriOpenEmbedded(fileUrl: string): Promise<string> {
+  if (!isTauriSurface()) {
+    throw new Error("file:// databases can only be opened in the desktop app");
+  }
+  const path = fileUrl.replace(/^file:\/\//i, "");
+  const { invoke } = await import("@tauri-apps/api/core");
+  try {
+    return await invoke<string>("open_embedded", { path });
+  } catch (e) {
+    // The standalone-Surface adapter seam: classify the command's structured
+    // error (or a legacy string/plugin error) in exactly one place, then throw
+    // a plain Error the provider can surface without any further coercion.
+    throw DesktopError.from(e);
+  }
+}
+
+/**
+ * Desktop HTTP for loopback targets goes through Tauri's rust-side fetch.
+ *
+ * An embedded file-backed reddb (and the bundled `red` generally) emits no CORS
+ * headers, so a cross-origin webview fetch from the app/dev origin to
+ * `127.0.0.1:<port>` is blocked ("Load failed"). Tauri's HTTP plugin issues the
+ * request from Rust, bypassing the webview's same-origin policy. Only loopback
+ * targets are rerouted; remote servers keep the plain webview fetch. In the
+ * browser this is always the plain fetch.
+ */
+const desktopFetch: typeof fetch = async (input, init) => {
+  const url =
+    typeof input === "string"
+      ? input
+      : input instanceof URL
+        ? input.href
+        : input.url;
+  const isLoopback =
+    /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?(\/|$)/i.test(url);
+  if (isTauriSurface() && isLoopback) {
+    try {
+      const { fetch: tauriFetch } = await import("@tauri-apps/plugin-http");
+      return await tauriFetch(
+        input as URL | Request | string,
+        init as RequestInit
+      );
+    } catch (e) {
+      // Surface the real reason — the http plugin can reject with a bare
+      // string/object that would otherwise read as "undefined" upstream.
+      const reason =
+        e instanceof Error ? e.message : typeof e === "string" ? e : String(e);
+      throw new Error(`rust-side fetch failed for ${url}: ${reason}`);
+    }
+  }
+  return fetch(input, init);
+};
+
 function isHandoffTokenConsumer(
   candidate: ConnectionProvider
 ): candidate is ConnectionProvider & HandoffTokenConsumer {
@@ -198,6 +270,13 @@ export const provider: ConnectionProvider & {
   presets: PRESETS,
   history: historyStore,
   transports: surfaceTransports(),
+  // Always wired: the resolver itself decides (at call time) whether it's on a
+  // Tauri Surface, so a not-yet-injected global at module load can't disable it.
+  embeddedResolver: tauriOpenEmbedded,
+  // Route loopback HTTP through Tauri's rust-side fetch (CORS bypass for the
+  // embedded/local reddb); plain webview fetch everywhere else.
+  clientFactory: (url, opts) =>
+    new RedClient(url, { ...opts, fetch: desktopFetch }),
   // Boot-params pre-configuration (#36, ADR-0005): a Surface (the MCP App)
   // seeds the endpoint + initial route in the app URL; the Core reads it
   // through the provider. Query tokens are ignored and hash tokens are not
@@ -370,7 +449,13 @@ class ConnectionStore {
     // An explicit connect attempt means a target has been chosen — unblocks
     // automatic refresh from here on (#21).
     this.#targetResolved = true;
+    // Step-logged loading (#127): the connect sequence appends real,
+    // timestamped steps so a slow open (sidecar spawn, readiness, handshake,
+    // initial stats/schema fetch) shows honest feedback instead of a frozen
+    // screen. Fast opens finish before the overlay's reveal threshold.
+    loading.begin(`Opening ${preset.label}`);
     try {
+      loading.step("Reaching server", preset.url);
       const active = await activity.track(`connect · ${preset.label}`, () =>
         getConnectionProvider().connect(preset.id)
       );
@@ -381,6 +466,7 @@ class ConnectionStore {
         description: preset.description,
       };
       persist(this.active);
+      loading.step("Fetching stats & capabilities");
       const [stats, replication, capabilities] = await Promise.all([
         activity
           .track(`connect · ${preset.label} stats`, () => active.client.stats())
@@ -405,9 +491,11 @@ class ConnectionStore {
       };
       this.#capabilities = capabilities;
       this.connected = true;
+      loading.succeed();
       return true;
     } catch (e) {
       this.probe = { reachable: false, error: (e as Error).message };
+      loading.fail((e as Error).message);
       return false;
     }
   }
@@ -491,3 +579,78 @@ class ConnectionStore {
 }
 
 export const connection = new ConnectionStore();
+
+/**
+ * Honest, actionable copy for a `file://` target that can't be opened on the
+ * current Surface (#123). The web build has no filesystem/process access, so a
+ * local database file needs the desktop app — say that plainly instead of
+ * failing with a generic transport-unsupported error (live-or-empty honesty
+ * applied to the Connect flow).
+ */
+export const LOCAL_FILE_DESKTOP_ONLY =
+  "Local database files (file://) can only be opened in the desktop app — the web version can't reach files on your machine.";
+
+/**
+ * Explanation for an unreachable connection target, or null when the target IS
+ * reachable / has no file-specific guidance. The Connect UI shows this instead
+ * of the generic "unsupported transport" line when the user types a `file://`
+ * URL on the web (#123). Kept in the store (not the component) so the
+ * connect-flow seam is unit-testable without rendering.
+ */
+export function unreachableConnectHint(url: string): string | null {
+  if (connection.canReach(url)) return null;
+  return transportForUrl(url) === "unix" ? LOCAL_FILE_DESKTOP_ONLY : null;
+}
+
+/**
+ * Native file picker — the subset of `@tauri-apps/plugin-dialog`'s `open` we
+ * use. Injected by tests; in production it's the lazily-imported dialog plugin.
+ */
+export type FilePicker = (options: {
+  multiple: false;
+  directory: false;
+  title: string;
+  filters: { name: string; extensions: string[] }[];
+}) => Promise<string | null>;
+
+export interface OpenDatabaseFileResult {
+  ok: boolean;
+  /** True when the user dismissed the picker without choosing a file. */
+  cancelled?: boolean;
+  /** Human-readable reason when the flow failed (not a cancellation). */
+  reason?: string;
+}
+
+/**
+ * Desktop "Open database file…" flow (#123): open the OS picker for a `.rdb`
+ * file and connect to it through the existing `file://` embedded path (Tauri
+ * spawns a local file-backed reddb sidecar; the UI talks HTTP to it). Only the
+ * standalone (Tauri) Surface has a native picker — on the web there is none, so
+ * this returns the honest desktop-only message the caller surfaces.
+ *
+ * `pick` is injected by tests; in production it's the Tauri dialog plugin's
+ * `open`, imported lazily so the browser bundle never pulls it in.
+ */
+export async function openDatabaseFile(
+  pick?: FilePicker
+): Promise<OpenDatabaseFileResult> {
+  if (!pick && !isTauriSurface()) {
+    return { ok: false, reason: LOCAL_FILE_DESKTOP_ONLY };
+  }
+  const open =
+    pick ??
+    ((await import("@tauri-apps/plugin-dialog")).open as unknown as FilePicker);
+  const selected = await open({
+    multiple: false,
+    directory: false,
+    title: "Open database file",
+    filters: [{ name: "reddb database", extensions: ["rdb"] }],
+  });
+  if (!selected) return { ok: false, cancelled: true };
+  const ok = await connection.tryConnect(
+    makeCustomConnection(`file://${selected}`)
+  );
+  return ok
+    ? { ok: true }
+    : { ok: false, reason: connection.probe.error ?? "unreachable" };
+}