desktop: Import and Export work offline; the menu toggle is reachable; errors say why

Export and Import were a link to the server and a reject("needs a server") on the
desktop. Both now run in the core with no server:

- core/src/local/portable.rs builds the same zip the server writes (notes.json,
  a Markdown file per note, each attachment this device holds) and reads either
  export marker or a Google Keep Takeout zip, with the server's decompression
  budget and an all-or-nothing transaction. Export saves to Downloads (no new
  plugin) and the sidebar says where; Import takes the archive as raw IPC bytes.
- core/testdata/portable.json pins the format for both copies: the server runs
  its Keep and native readers against it (test_portable_fixture.py) and checks
  its real export's keys (test_integration.py); the core runs the same cases.
- Found on the way: both importers skipped a Keep note that is only a photo as
  "empty". It now imports, on the server and in the core.
- New dependency, approved: `zip` (deflate only) plus `flate2` on its pure-Rust
  backend, both already in the lockfile.

The AppImage applications-menu toggle moves from Account, which the desktop
never shows, to the Sync page; the first-run prompt now says so.

errorMessage (#5236) replaces the hand-rolled `.error ?? …` / `.message ?? e`
reads at the remaining catch sites, so a desktop failure shows its real reason.

Task #5170.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

frontend/src/adapters/local.ts

@@ -4,9 +4,9 @@
 //
 // Argument keys are camelCase; Tauri converts them to the Rust commands' snake_case
 // parameters (e.g. labelIds -> label_ids). A few operations have no offline meaning
-// yet (account auth, device linking, URL unfurl, file import) — those reject with a
-// clear message rather than silently failing; the board, editor, attachments,
-// capture, filters, labels, checklists and reminders all work fully offline.
+// yet (account auth, device linking, URL unfurl) — those reject with a clear message
+// rather than silently failing; the board, editor, attachments, capture, filters,
+// labels, checklists, reminders, import and export all work fully offline.
 
 import { invoke } from "../desktop/bridge";
 import type { Note, NoteRevision } from "../stores/notes";
@@ -72,7 +72,9 @@ export const local: Repo = {
     deleteAttachment: (id, attId) => invoke<Note>("notes_delete_attachment", { id, attId }),
     unfurl: () => Promise.reject<Note>(new Error(NEEDS_SERVER)),
     deletePreview: (id, previewId) => invoke<Note>("notes_delete_preview", { id, previewId }),
-    import: () => Promise.reject<ImportResult>(new Error(NEEDS_SERVER)),
+    // The archive crosses as raw bytes, as an attachment does.
+    import: async (file) => invoke<ImportResult>("notes_import", new Uint8Array(await file.arrayBuffer())),
+    exportAll: () => invoke<string>("notes_export"),
     reorder: (orderedIds) => invoke<void>("notes_reorder", { orderedIds }),
     trash: (id) => invoke<Note>("notes_trash", { id }),
     restore: (id) => invoke<Note>("notes_restore", { id }),

frontend/src/adapters/repo.ts

@@ -101,6 +101,9 @@ export interface NotesRepo {
   unfurl(id: string, url: string): Promise<Note>;
   deletePreview(id: string, previewId: string): Promise<Note>;
   import(file: File): Promise<ImportResult>;
+  /** Save every note as a zip. Resolves to the path it was saved at, or null when
+   *  the browser took the download and the file is wherever downloads go. */
+  exportAll(): Promise<string | null>;
   reorder(orderedIds: string[]): Promise<void>;
   trash(id: string): Promise<Note>;
   restore(id: string): Promise<Note>;

frontend/src/adapters/rest.ts

@@ -90,6 +90,15 @@ export const rest: Repo = {
     unfurl: (id, url) => api.post<Note>(`/api/notes/${id}/unfurl`, { url }),
     deletePreview: (id, previewId) => api.del<Note>(`/api/notes/${id}/previews/${previewId}`),
     import: (file) => api.postForm<ImportResult>("/api/notes/import", fileForm(file)),
+    // A same-origin GET with the session cookie; the browser saves the attachment
+    // response itself, so there is no path to report.
+    exportAll: () => {
+      const link = document.createElement("a");
+      link.href = "/api/notes/export";
+      link.download = "";
+      link.click();
+      return Promise.resolve(null);
+    },
     reorder: (orderedIds) => api.post<void>("/api/notes/reorder", { ids: orderedIds }),
     trash: (id) => api.post<Note>(`/api/notes/${id}/trash`),
     restore: (id) => api.post<Note>(`/api/notes/${id}/restore`),

frontend/src/components/AppShell.vue

@@ -10,6 +10,7 @@ import { useUiStore } from "../stores/ui";
 import BaseModal from "./BaseModal.vue";
 import CommandPalette from "./CommandPalette.vue";
 import Icon from "./Icon.vue";
+import ExportNotes from "./ExportNotes.vue";
 import ImportNotes from "./ImportNotes.vue";
 import LabelsModal from "./LabelsModal.vue";
 import { isDesktop } from "../desktop/bridge";
@@ -484,10 +485,7 @@ async function signOut() {
           >
             <Icon name="calendar" /> Timeline
           </RouterLink>
-          <!-- Direct download (same-origin GET, session cookie sent); not a route. -->
-          <a href="/api/notes/export" download class="nav-link" title="Download all your notes as a zip">
-            <Icon name="download" /> Export
-          </a>
+          <ExportNotes />
           <ImportNotes />
 
           <!-- Account, settings and sign-out, for the screens where they are NOT in

frontend/src/components/DesktopIntegrationPrompt.vue

@@ -4,11 +4,13 @@ import BaseModal from "./BaseModal.vue";
 import BaseButton from "./BaseButton.vue";
 import { isDesktop, desktop } from "../desktop/bridge";
 import { useUiStore } from "../stores/ui";
+import { errorMessage } from "../api/errors";
 
 // First-run prompt (Linux AppImage only) offering to add Inkwell to the
 // applications menu so it behaves like an installed app instead of a loose file.
 // Shown once; the choice is remembered. Users who decline can integrate later from
-// Account. No-op on the web build and on already-integrated / non-AppImage runs.
+// the Sync page (DesktopMenuEntry). No-op on the web build and on already-integrated /
+// non-AppImage runs.
 const DISMISS_KEY = "desktop.integration.prompted";
 
 const ui = useUiStore();
@@ -38,7 +40,7 @@ async function integrate() {
     show.value = false;
     ui.showToast("Inkwell added to your applications menu.");
   } catch (e) {
-    ui.showToast((e as { message?: string }).message ?? "Couldn't add to applications.");
+    ui.showToast(errorMessage(e, "Couldn't add to applications."));
   } finally {
     working.value = false;
   }
@@ -60,7 +62,7 @@ async function integrate() {
       <p class="mt-2 text-sm text-neutral-600 dark:text-neutral-400">
         We'll add a menu entry so you can launch Inkwell from your app launcher, and keep a stable
         copy in <code class="font-mono text-xs">~/Applications</code> so it isn't lost from Downloads.
-        You can undo this any time from your account.
+        You can undo this any time from the Sync page.
       </p>
       <div class="mt-6 flex justify-end gap-3">
         <BaseButton variant="ghost" :disabled="working" @click="dismiss">Not now</BaseButton>

frontend/src/components/DesktopMenuEntry.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import { onMounted, ref } from "vue";
+import BaseButton from "./BaseButton.vue";
+import { desktop, isDesktop, type IntegrationStatus } from "../desktop/bridge";
+import { errorMessage } from "../api/errors";
+import { useUiStore } from "../stores/ui";
+
+// The applications-menu entry for a Linux AppImage: add it, or take it away again.
+// Renders nothing anywhere else — the web, Windows, or an AppImage-less Linux build.
+//
+// It lived on the Account page, which the desktop app never shows: a toggle the
+// first-run prompt promised ("undo any time") with no way to reach it.
+const ui = useUiStore();
+const status = ref<IntegrationStatus | null>(null);
+const busy = ref(false);
+
+onMounted(async () => {
+  if (!isDesktop()) return;
+  try {
+    status.value = await desktop.integrationStatus();
+  } catch {
+    status.value = null;
+  }
+});
+
+async function toggle() {
+  busy.value = true;
+  try {
+    status.value = status.value?.is_integrated ? await desktop.unintegrate() : await desktop.integrate();
+    ui.showToast(
+      status.value?.is_integrated ? "Added to your applications menu." : "Removed from your applications menu.",
+    );
+  } catch (e) {
+    ui.showToast(errorMessage(e, "Couldn't update the menu entry."));
+  } finally {
+    busy.value = false;
+  }
+}
+</script>
+
+<template>
+  <section v-if="status?.is_appimage" class="mt-10 border-t border-neutral-200 pt-8 dark:border-neutral-800">
+    <h2 class="text-sm font-semibold">Applications menu</h2>
+    <div class="mt-3 flex items-center justify-between gap-4">
+      <p class="text-sm text-neutral-500 dark:text-neutral-400">
+        {{ status.is_integrated ? "Inkwell is in your applications menu." : "Not in your applications menu." }}
+      </p>
+      <BaseButton
+        :variant="status.is_integrated ? 'ghost' : 'primary'"
+        :loading="busy"
+        class="shrink-0"
+        @click="toggle"
+      >
+        {{ status.is_integrated ? "Remove" : "Add to applications" }}
+      </BaseButton>
+    </div>
+  </section>
+</template>

frontend/src/components/ExportNotes.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import { ref } from "vue";
+import Icon from "./Icon.vue";
+import { repo } from "../adapters";
+import { errorMessage } from "../api/errors";
+import { useUiStore } from "../stores/ui";
+
+// Sidebar Export. In a browser the server streams the zip and the browser saves it;
+// on the desktop the core builds it from the local store with no server, saves it in
+// Downloads, and says exactly where.
+const ui = useUiStore();
+const busy = ref(false);
+
+async function run() {
+  if (busy.value) return;
+  busy.value = true;
+  try {
+    const savedTo = await repo.notes.exportAll();
+    if (savedTo) ui.showToast(`Exported to ${savedTo}`);
+  } catch (err) {
+    ui.showToast(errorMessage(err, "Export failed."));
+  } finally {
+    busy.value = false;
+  }
+}
+</script>
+
+<template>
+  <button
+    type="button"
+    class="nav-link w-full disabled:opacity-60"
+    :disabled="busy"
+    title="Save all your notes as a zip"
+    @click="run"
+  >
+    <Icon name="download" /> {{ busy ? "Exporting…" : "Export" }}
+  </button>
+</template>

frontend/src/components/FilterBar.vue

@@ -8,6 +8,7 @@ import type { NoteFacets } from "../stores/notes";
 import { facetCount, facetsFromQuery, facetsToQuery } from "../notes/facets";
 import { addLocalDays, formatLocalDay, parseLocalDate } from "../notes/datetime";
 import Icon from "./Icon.vue";
+import { errorMessage } from "../api/errors";
 
 // A dead-simple facet bar over the board: color + labels + has-reminder
 // + has-attachment + created-date range. The URL query IS the state, so a
@@ -71,7 +72,7 @@ async function saveView() {
     await savedFilters.create(name.trim(), facets.value);
     ui.showToast(`Saved view "${name.trim()}".`);
   } catch (e) {
-    ui.showToast((e as { error?: string }).error ?? "Couldn't save the view.");
+    ui.showToast(errorMessage(e, "Couldn't save the view."));
   }
 }
 

frontend/src/components/ImportNotes.vue

@@ -4,6 +4,7 @@ import Icon from "./Icon.vue";
 import { useNotesStore } from "../stores/notes";
 import { useLabelsStore } from "../stores/labels";
 import { useUiStore } from "../stores/ui";
+import { errorMessage } from "../api/errors";
 
 // Sidebar counterpart to Export: pick a .zip (an Inkwell export for round-trip,
 // or a Google Keep Takeout archive) and import its notes. Additive — never
@@ -31,7 +32,7 @@ async function onFile(e: Event) {
     const tail = res.skipped ? ` (${res.skipped} skipped)` : "";
     ui.showToast(`Imported ${res.imported} ${noun}${tail}.`);
   } catch (err) {
-    ui.showToast((err as { error?: string }).error ?? "Import failed.");
+    ui.showToast(errorMessage(err, "Import failed."));
   } finally {
     busy.value = false;
   }

frontend/src/composables/useNoteList.ts

@@ -1,5 +1,6 @@
 import { ref, type Ref } from "vue";
 import type { Note } from "../stores/notes";
+import { errorMessage } from "../api/errors";
 
 // The load-a-list-of-notes scaffold every recall view (Search, Timeline, Reminders)
 // hand-rolled: an items ref + loading/error flags + a load() that fills them and never
@@ -27,7 +28,7 @@ export function useNoteList(
     try {
       items.value = await fetcher();
     } catch (e) {
-      error.value = (e as { error?: string }).error ?? fallbackError;
+      error.value = errorMessage(e, fallbackError);
       items.value = [];
     } finally {
       loading.value = false;

frontend/src/views/AccountView.vue

@@ -7,7 +7,7 @@ import BaseButton from "../components/BaseButton.vue";
 import BaseInput from "../components/BaseInput.vue";
 import ClientDownloads from "../components/ClientDownloads.vue";
 import Icon from "../components/Icon.vue";
-import { isDesktop, desktop as desktopBridge, type IntegrationStatus } from "../desktop/bridge";
+import { errorMessage } from "../api/errors";
 
 // Per-user (not admin) management of linked native clients — the Tauri desktop and
 // Android apps authenticate sync with a device bearer token issued here.
@@ -23,9 +23,6 @@ const creating = ref(false);
 // The freshly-issued plaintext token — shown ONCE (never retrievable again).
 const freshToken = ref("");
 
-// Desktop-app self-integration (Linux AppImage only; the card is hidden otherwise).
-const desktopStatus = ref<IntegrationStatus | null>(null);
-const desktopBusy = ref(false);
 
 async function load() {
   error.value = "";
@@ -45,7 +42,7 @@ async function link() {
     freshToken.value = await devices.create(newName.value.trim() || "Device");
     newName.value = "";
   } catch (e) {
-    error.value = (e as { error?: string }).error ?? "Couldn't create a device token.";
+    error.value = errorMessage(e, "Couldn't create a device token.");
   } finally {
     creating.value = false;
   }
@@ -74,36 +71,8 @@ function fmt(iso: string | null): string {
   return new Date(iso).toLocaleString();
 }
 
-async function loadDesktop() {
-  if (!isDesktop()) return;
-  try {
-    desktopStatus.value = await desktopBridge.integrationStatus();
-  } catch {
-    desktopStatus.value = null;
-  }
-}
-
-async function toggleIntegration() {
-  desktopBusy.value = true;
-  try {
-    desktopStatus.value = desktopStatus.value?.is_integrated
-      ? await desktopBridge.unintegrate()
-      : await desktopBridge.integrate();
-    ui.showToast(
-      desktopStatus.value?.is_integrated
-        ? "Added to your applications menu."
-        : "Removed from your applications menu.",
-    );
-  } catch (e) {
-    ui.showToast((e as { message?: string }).message ?? "Couldn't update the menu entry.");
-  } finally {
-    desktopBusy.value = false;
-  }
-}
-
 onMounted(() => {
   void load();
-  void loadDesktop();
 });
 </script>
 
@@ -132,31 +101,6 @@ onMounted(() => {
       paste it into the app when it asks to connect. You can revoke a device at any time.
     </p>
 
-    <!-- Desktop app self-integration (Linux AppImage only) -->
-    <section
-      v-if="desktopStatus?.is_appimage"
-      class="mb-6 flex items-center justify-between gap-4 rounded-xl border border-neutral-200 p-4 dark:border-neutral-800"
-    >
-      <div class="min-w-0">
-        <p class="text-sm font-medium text-neutral-800 dark:text-neutral-100">Desktop app</p>
-        <p class="mt-0.5 text-xs text-neutral-400">
-          {{
-            desktopStatus.is_integrated
-              ? "Inkwell is in your applications menu."
-              : "Add Inkwell to your applications menu to launch it like an installed app."
-          }}
-        </p>
-      </div>
-      <BaseButton
-        :variant="desktopStatus.is_integrated ? 'ghost' : 'primary'"
-        :loading="desktopBusy"
-        class="shrink-0"
-        @click="toggleIntegration"
-      >
-        {{ desktopStatus.is_integrated ? "Remove" : "Add to applications" }}
-      </BaseButton>
-    </section>
-
     <!-- Every client this server holds, the one that fits this machine on top.
          Hides itself when the server holds none. -->
     <ClientDownloads />

frontend/src/views/BoardView.vue

@@ -12,6 +12,7 @@ import FilterBar from "../components/FilterBar.vue";
 import NoteGrid from "../components/NoteGrid.vue";
 import NoteEditor from "../components/NoteEditor.vue";
 import { isDesktop, onCaptured, onSynced, sync as syncBridge } from "../desktop/bridge";
+import { errorMessage } from "../api/errors";
 
 const notes = useNotesStore();
 const config = useConfigStore();
@@ -208,7 +209,7 @@ async function reload() {
   try {
     await notes.load(currentView.value, currentLabel.value, facets.value);
   } catch (e) {
-    loadError.value = (e as { error?: string }).error ?? "Couldn't load your notes.";
+    loadError.value = errorMessage(e, "Couldn't load your notes.");
   }
 }
 

frontend/src/views/LoginView.vue

@@ -5,7 +5,7 @@ import { useSessionStore } from "../stores/session";
 import { useConfigStore } from "../stores/config";
 import BaseInput from "../components/BaseInput.vue";
 import BaseButton from "../components/BaseButton.vue";
-import type { ApiError } from "../api/client";
+import { errorMessage } from "../api/errors";
 
 const session = useSessionStore();
 const config = useConfigStore();
@@ -33,7 +33,7 @@ async function submit() {
     await session.login(email.value, password.value);
     await router.replace(safeRedirect(route.query.redirect));
   } catch (e) {
-    error.value = (e as ApiError).error ?? "Could not sign in.";
+    error.value = errorMessage(e, "Could not sign in.");
   } finally {
     loading.value = false;
   }

frontend/src/views/RegisterView.vue

@@ -5,7 +5,7 @@ import { useSessionStore } from "../stores/session";
 import { useConfigStore } from "../stores/config";
 import BaseInput from "../components/BaseInput.vue";
 import BaseButton from "../components/BaseButton.vue";
-import type { ApiError } from "../api/client";
+import { errorMessage } from "../api/errors";
 
 const session = useSessionStore();
 const config = useConfigStore();
@@ -28,7 +28,7 @@ async function submit() {
     await session.register(email.value, password.value, displayName.value);
     await router.replace("/");
   } catch (e) {
-    error.value = (e as ApiError).error ?? "Could not create your account.";
+    error.value = errorMessage(e, "Could not create your account.");
   } finally {
     loading.value = false;
   }

frontend/src/views/SettingsView.vue

@@ -3,6 +3,7 @@ import { computed, onMounted, ref, watch } from "vue";
 import { api } from "../api/client";
 import { useConfigStore } from "../stores/config";
 import BaseButton from "../components/BaseButton.vue";
+import { errorMessage } from "../api/errors";
 
 interface SettingItem {
   key: string;
@@ -74,7 +75,7 @@ async function save() {
     saved.value = true;
     await config.reload(); // header/site name reflects changes immediately
   } catch (e) {
-    error.value = (e as { error?: string }).error ?? "Could not save settings.";
+    error.value = errorMessage(e, "Could not save settings.");
   } finally {
     saving.value = false;
   }

frontend/src/views/SyncView.vue

@@ -4,6 +4,7 @@ import { useUiStore } from "../stores/ui";
 import BaseButton from "../components/BaseButton.vue";
 import BaseInput from "../components/BaseInput.vue";
 import Icon from "../components/Icon.vue";
+import DesktopMenuEntry from "../components/DesktopMenuEntry.vue";
 import {
   SUGGESTED_CAPTURE_SHORTCUT,
   capture as captureBridge,
@@ -20,6 +21,7 @@ import {
   type UpdateChannel,
   type UpdateStatus,
 } from "../desktop/bridge";
+import { errorMessage } from "../api/errors";
 
 // Opt-in server sync for the desktop app. Being UNLINKED is the normal resting
 // state, not an incomplete setup — the app is local-first and fully usable having
@@ -111,7 +113,7 @@ async function saveShortcut(value: string) {
     // The message comes from the core and names the actual reason — "something
     // else is already using it" reads very differently from "that is not a
     // shortcut this system understands", and both are things you can act on.
-    shortcutError.value = String((e as { message?: string }).message ?? e);
+    shortcutError.value = errorMessage(e, "Couldn't save the shortcut.");
   } finally {
     savingShortcut.value = false;
   }
@@ -124,7 +126,7 @@ async function checkUpdates() {
     update.value = await updateBridge.check();
     channel.value = update.value.channel;
   } catch (e) {
-    updateError.value = String((e as Error)?.message ?? e);
+    updateError.value = errorMessage(e, "The update check failed.");
   } finally {
     checking.value = false;
     checkedOnce.value = true;
@@ -141,7 +143,7 @@ async function switchChannel(next: UpdateChannel) {
     checkedOnce.value = false;
     await checkUpdates();
   } catch (e) {
-    updateError.value = String((e as Error)?.message ?? e);
+    updateError.value = errorMessage(e, "The update check failed.");
   }
 }
 
@@ -153,7 +155,7 @@ async function installUpdate() {
     // means it failed.
     await updateBridge.install();
   } catch (e) {
-    updateError.value = String((e as Error)?.message ?? e);
+    updateError.value = errorMessage(e, "The update check failed.");
   } finally {
     installing.value = false;
   }
@@ -191,7 +193,7 @@ async function runProbe() {
   try {
     probe.value = await syncBridge.probe(url.value);
   } catch (e) {
-    probeError.value = String((e as Error)?.message ?? e);
+    probeError.value = errorMessage(e, "Couldn't reach that server.");
   } finally {
     probing.value = false;
   }
@@ -219,7 +221,7 @@ async function connect() {
     ui.showToast(`Connected to ${result.status.server_url}.`);
     await syncNow();
   } catch (e) {
-    linkError.value = String((e as Error)?.message ?? e);
+    linkError.value = errorMessage(e, "Couldn't link to that server.");
   } finally {
     linking.value = false;
   }
@@ -261,7 +263,7 @@ async function syncNow() {
     showOutcome(await syncBridge.now());
     pending.value = await syncBridge.hasPending();
   } catch (e) {
-    syncError.value = String((e as Error)?.message ?? e);
+    syncError.value = errorMessage(e, "Sync failed.");
   } finally {
     syncing.value = false;
   }
@@ -303,7 +305,7 @@ async function disconnect() {
         : "Disconnected. This device now works offline only.",
     );
   } catch (e) {
-    ui.showToast(String((e as Error)?.message ?? e));
+    ui.showToast(errorMessage(e, "Couldn't disconnect."));
   }
 }
 
@@ -676,5 +678,9 @@ onBeforeUnmount(() => stopSyncListener?.());
         </BaseButton>
       </div>
     </section>
+
+    <!-- The AppImage's menu entry, which the first-run prompt says can be undone
+         from here. Hides itself on every other build. -->
+    <DesktopMenuEntry />
   </div>
 </template>