feat(mobile): real persistence via @capacitor/preferences (Phase 4) (#34)

* docs(plan): add phase-4 storage implementation plan

* chore(mobile): add @capacitor/preferences + @shared alias

* feat(mobile): add storage layer (preferences wrapper + workspace/padHistory/settings stores)

* feat(mobile): wire CapacitorPlatform to the storage layer + add persistence smoke test

state.getInitial/workspace.*/padHistory.*/settings.* now read+write through
@capacitor/preferences via the new stores. Errors funnel through `wrap()`
into typed `{ ok: false, error }` envelopes that the shell already knows
how to unwrap into AppError.

Adds a Playwright test that pre-seeds localStorage with a Capacitor
Preferences-shaped workspace blob, loads the page, and asserts the
workspace renders in the rail (and AddWorkspaceDialog is hidden) —
end-to-end coverage of the read path through the Zod-validated store.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(mobile): cast Zod-inferred entries to PadHistoryEntry[] at store boundary

exactOptionalPropertyTypes treats title?: string and title?: string | undefined
as distinct; Zod's .optional() emits the latter. Same boundary cast as
desktop's pad-history-store. Local typecheck slipped because of stale
tsbuildinfo cache; cleaning out/ surfaces the error and CI catches it too.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: JohnMcLear

docs/superpowers/plans/2026-05-11-etherpad-mobile-phase4-storage.md

@@ -21,9 +21,11 @@
     "@capacitor/android": "^8.0.0",
     "@capacitor/app": "^8.0.0",
     "@capacitor/core": "^8.0.0",
+    "@capacitor/preferences": "^8.0.1",
     "@etherpad/shell": "workspace:*",
     "react": "^19.2.0",
-    "react-dom": "^19.2.0"
+    "react-dom": "^19.2.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@capacitor/cli": "^8.0.0",

packages/mobile/package.json

@@ -1,55 +1,72 @@
 import type { Platform } from '@etherpad/shell';
+import * as workspaceStore from './storage/workspace-store.js';
+import * as padHistoryStore from './storage/pad-history-store.js';
+import * as settingsStore from './storage/settings-store.js';
 
 /**
- * Stub `CapacitorPlatform` for Phase 3. Returns empty state for every read
- * so the shell renders its first-launch UI (the non-dismissable
- * `AddWorkspaceDialog`). Write methods reject with NOT_IMPLEMENTED — Phase 4
- * replaces these with `@capacitor/preferences` + `@capacitor/filesystem`.
+ * Concrete `Platform` impl for mobile. Workspace, pad-history, and settings
+ * persistence go through `@capacitor/preferences` (web fallback = localStorage
+ * with `CapacitorStorage.<key>` prefix). Pad rendering (`tab.*`),
+ * desktop-specific surfaces (`httpLogin`, `updater`), and pad-content search
+ * remain stubbed — they land in Phase 5+ alongside `PadIframeStack` and the
+ * deep-links / share / permissions plugin.
  *
- * Events are no-op subscribers: the unsubscribe fn does nothing because
- * nothing ever fires. Mobile is single-window so cross-process events aren't
- * meaningful; Phase 4 may add an in-process mitt bus if components want to
- * fire local events.
- *
- * All reads that flow through `ipc.ts`'s `unwrap()` helper return the
- * `{ ok: true, value: ... }` IPC envelope shape. Methods that bypass
- * unwrap (`updater.getState`, `quickSwitcher.searchPadContent`, the events)
- * return raw values per the shell's type contract.
+ * All write paths funnel through `wrap()` so a thrown error inside a store
+ * surfaces to the shell as a typed `{ ok: false, error: ... }` envelope
+ * (consumed by `ipc.ts`'s `unwrap()`).
  */
 export function createCapacitorPlatform(): Platform {
   const ok = Promise.resolve({ ok: true });
-  const okValue = <T>(value: T) => Promise.resolve({ ok: true, value });
-  const notImpl = (op: string) =>
-    Promise.reject(new Error(`[mobile/Phase 3] ${op} not implemented yet`));
-  const noopUnsubscribe = (): (() => void) => () => {};
-
-  const defaultSettings = {
-    schemaVersion: 1 as const,
-    defaultZoom: 1,
-    accentColor: '#3366cc',
-    language: 'en',
-    rememberOpenTabsOnQuit: true,
-    minimizeToTray: false,
-    themePreference: 'auto' as const,
-    userName: '',
+  const wrap = async <T>(
+    fn: () => Promise<T>,
+  ): Promise<{ ok: true; value: T } | { ok: false; error: { kind: string; message: string } }> => {
+    try {
+      const value = await fn();
+      return { ok: true, value };
+    } catch (err) {
+      return {
+        ok: false,
+        error: {
+          kind: 'UnknownError',
+          message: err instanceof Error ? err.message : String(err),
+        },
+      };
+    }
   };
+  const notImpl = (
+    op: string,
+  ): Promise<{ ok: false; error: { kind: string; message: string } }> =>
+    Promise.resolve({
+      ok: false,
+      error: { kind: 'NotImplementedError', message: `[mobile] ${op} not implemented yet` },
+    });
+  const noopUnsubscribe = (): (() => void) => () => {};
 
   return {
     state: {
       getInitial: () =>
-        okValue({
-          workspaces: [],
-          workspaceOrder: [],
-          settings: defaultSettings,
-          padHistory: {},
+        wrap(async () => {
+          const { workspaces, order } = await workspaceStore.list();
+          const settings = await settingsStore.get();
+          const padHistory = await padHistoryStore.loadAll(order);
+          return {
+            workspaces,
+            workspaceOrder: order,
+            settings,
+            padHistory,
+          };
         }),
     },
     workspace: {
-      list: () => okValue({ workspaces: [], order: [] }),
-      add: () => notImpl('workspace.add'),
-      update: () => notImpl('workspace.update'),
-      remove: () => notImpl('workspace.remove'),
-      reorder: () => notImpl('workspace.reorder'),
+      list: () => wrap(workspaceStore.list),
+      add: (input) => wrap(() => workspaceStore.add(input)),
+      update: (input) => wrap(() => workspaceStore.update(input)),
+      remove: (input) =>
+        wrap(async () => {
+          await workspaceStore.remove(input);
+          return { ok: true } as const;
+        }),
+      reorder: (input) => wrap(() => workspaceStore.reorder(input)),
     },
     tab: {
       open: () => notImpl('tab.open'),
@@ -68,15 +85,32 @@ export function createCapacitorPlatform(): Platform {
       setRailCollapsed: () => ok,
     },
     padHistory: {
-      list: () => okValue([]),
-      pin: () => notImpl('padHistory.pin'),
-      unpin: () => notImpl('padHistory.unpin'),
-      clearRecent: () => notImpl('padHistory.clearRecent'),
-      clearAll: () => notImpl('padHistory.clearAll'),
+      list: (input) => wrap(() => padHistoryStore.list(input)),
+      pin: (input) =>
+        wrap(async () => {
+          await padHistoryStore.pin(input);
+          return { ok: true } as const;
+        }),
+      unpin: (input) =>
+        wrap(async () => {
+          await padHistoryStore.unpin(input);
+          return { ok: true } as const;
+        }),
+      clearRecent: (input) =>
+        wrap(async () => {
+          await padHistoryStore.clearRecent(input);
+          return { ok: true } as const;
+        }),
+      clearAll: () =>
+        wrap(async () => {
+          await padHistoryStore.clearAll();
+          return { ok: true } as const;
+        }),
     },
     settings: {
-      get: () => okValue(defaultSettings),
-      update: () => notImpl('settings.update'),
+      get: () => wrap(settingsStore.get),
+      update: (patch) =>
+        wrap(() => settingsStore.update(patch as Parameters<typeof settingsStore.update>[0])),
     },
     httpLogin: {
       respond: () => notImpl('httpLogin.respond'),

packages/mobile/src/platform/capacitor.ts

@@ -0,0 +1,56 @@
+import type { PadHistoryEntry } from '@shared/types/pad-history';
+import { padHistoryFileSchema } from '@shared/validation/pad-history';
+import { listKeys, loadJson, removeKey, saveJson } from './preferences.js';
+
+const PREFIX = 'etherpad:padHistory:';
+const keyFor = (workspaceId: string): string => `${PREFIX}${workspaceId}`;
+
+async function load(workspaceId: string): Promise<PadHistoryEntry[]> {
+  const file = await loadJson(keyFor(workspaceId), padHistoryFileSchema);
+  // Cast at the boundary: Zod's `.optional()` infers `title: string | undefined`
+  // whereas `PadHistoryEntry.title` is `title?: string` (no `| undefined`)
+  // under `exactOptionalPropertyTypes: true`. Same boundary cast as desktop's
+  // pad-history-store.
+  return (file?.entries ?? []) as PadHistoryEntry[];
+}
+
+async function save(workspaceId: string, entries: PadHistoryEntry[]): Promise<void> {
+  await saveJson(keyFor(workspaceId), padHistoryFileSchema, { schemaVersion: 1, entries });
+}
+
+export async function list(input: { workspaceId: string }): Promise<PadHistoryEntry[]> {
+  return load(input.workspaceId);
+}
+
+export async function pin(input: { workspaceId: string; padName: string }): Promise<void> {
+  const entries = await load(input.workspaceId);
+  const e = entries.find((x) => x.padName === input.padName);
+  if (e) e.pinned = true;
+  await save(input.workspaceId, entries);
+}
+
+export async function unpin(input: { workspaceId: string; padName: string }): Promise<void> {
+  const entries = await load(input.workspaceId);
+  const e = entries.find((x) => x.padName === input.padName);
+  if (e) e.pinned = false;
+  await save(input.workspaceId, entries);
+}
+
+export async function clearRecent(input: { workspaceId: string }): Promise<void> {
+  const entries = (await load(input.workspaceId)).filter((e) => e.pinned);
+  await save(input.workspaceId, entries);
+}
+
+export async function clearAll(): Promise<void> {
+  const keys = await listKeys();
+  for (const key of keys) {
+    if (key.startsWith(PREFIX)) await removeKey(key);
+  }
+}
+
+/** Used by `state.getInitial()` to bundle history for every known workspace. */
+export async function loadAll(workspaceIds: string[]): Promise<Record<string, PadHistoryEntry[]>> {
+  const result: Record<string, PadHistoryEntry[]> = {};
+  for (const id of workspaceIds) result[id] = await load(id);
+  return result;
+}

packages/mobile/src/platform/storage/pad-history-store.ts

@@ -0,0 +1,42 @@
+import { Preferences } from '@capacitor/preferences';
+import type { ZodTypeAny, infer as zInfer } from 'zod';
+
+/**
+ * Read a Preferences key and parse it with the given Zod schema. Returns
+ * `null` when the key is absent or the stored JSON doesn't match the
+ * schema. Callers fall back to a default in that case rather than throw —
+ * preferable to crashing the app on boot if disk data is malformed.
+ */
+export async function loadJson<S extends ZodTypeAny>(
+  key: string,
+  schema: S,
+): Promise<zInfer<S> | null> {
+  const { value } = await Preferences.get({ key });
+  if (value === null) return null;
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    const result = schema.safeParse(parsed);
+    return result.success ? (result.data as zInfer<S>) : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function saveJson<S extends ZodTypeAny>(
+  key: string,
+  schema: S,
+  value: zInfer<S>,
+): Promise<void> {
+  // Validate before persisting so we never write a malformed blob.
+  schema.parse(value);
+  await Preferences.set({ key, value: JSON.stringify(value) });
+}
+
+export async function removeKey(key: string): Promise<void> {
+  await Preferences.remove({ key });
+}
+
+export async function listKeys(): Promise<string[]> {
+  const { keys } = await Preferences.keys();
+  return keys;
+}

packages/mobile/src/platform/storage/preferences.ts

@@ -0,0 +1,17 @@
+import type { Settings } from '@shared/types/settings';
+import { defaultSettings, settingsSchema } from '@shared/validation/settings';
+import { loadJson, saveJson } from './preferences.js';
+
+const KEY = 'etherpad:settings';
+
+export async function get(): Promise<Settings> {
+  const stored = await loadJson(KEY, settingsSchema);
+  return stored ?? defaultSettings;
+}
+
+export async function update(patch: Partial<Settings>): Promise<Settings> {
+  const current = await get();
+  const next: Settings = { ...current, ...patch, schemaVersion: 1 };
+  await saveJson(KEY, settingsSchema, next);
+  return next;
+}

packages/mobile/src/platform/storage/settings-store.ts

@@ -0,0 +1,80 @@
+import type { Workspace } from '@shared/types/workspace';
+import { workspacesFileSchema } from '@shared/validation/workspace';
+import { loadJson, saveJson } from './preferences.js';
+
+const KEY = 'etherpad:workspaces';
+
+export interface WorkspacesFile {
+  schemaVersion: 1;
+  workspaces: Workspace[];
+  order: string[];
+}
+
+async function load(): Promise<WorkspacesFile> {
+  const file = await loadJson(KEY, workspacesFileSchema);
+  return file ?? { schemaVersion: 1, workspaces: [], order: [] };
+}
+
+async function save(file: WorkspacesFile): Promise<void> {
+  await saveJson(KEY, workspacesFileSchema, file);
+}
+
+export async function list(): Promise<{ workspaces: Workspace[]; order: string[] }> {
+  const file = await load();
+  return { workspaces: file.workspaces, order: file.order };
+}
+
+export async function add(input: {
+  name: string;
+  serverUrl?: string;
+  color: string;
+  kind?: 'remote' | 'embedded';
+}): Promise<Workspace> {
+  const file = await load();
+  const ws: Workspace = {
+    id: crypto.randomUUID(),
+    name: input.name,
+    serverUrl: input.serverUrl ?? '',
+    color: input.color,
+    createdAt: Date.now(),
+    ...(input.kind ? { kind: input.kind } : {}),
+  };
+  file.workspaces.push(ws);
+  file.order.push(ws.id);
+  await save(file);
+  return ws;
+}
+
+export async function update(input: {
+  id: string;
+  name?: string;
+  serverUrl?: string;
+  color?: string;
+}): Promise<Workspace> {
+  const file = await load();
+  const ws = file.workspaces.find((w) => w.id === input.id);
+  if (!ws) throw new Error(`Workspace ${input.id} not found`);
+  if (input.name !== undefined) ws.name = input.name;
+  if (input.serverUrl !== undefined) ws.serverUrl = input.serverUrl;
+  if (input.color !== undefined) ws.color = input.color;
+  await save(file);
+  return ws;
+}
+
+export async function remove(input: { id: string }): Promise<void> {
+  const file = await load();
+  file.workspaces = file.workspaces.filter((w) => w.id !== input.id);
+  file.order = file.order.filter((id) => id !== input.id);
+  await save(file);
+}
+
+export async function reorder(input: { order: string[] }): Promise<string[]> {
+  const file = await load();
+  const known = new Set(file.workspaces.map((w) => w.id));
+  for (const id of input.order) {
+    if (!known.has(id)) throw new Error(`Unknown workspace ${id}`);
+  }
+  file.order = input.order;
+  await save(file);
+  return input.order;
+}