Repository Public
1# Web offline-first (SP Note 3.0)23Status: implemented on branch `next-p`, verified by `tests/unit/next-p-offline.test.ts` and `tests/e2e/next-p-offline.spec.ts`4(production build + service worker + `context.setOffline`). This file describes what the code does, not an intention.56## 1. What the owner can do without a connection78| Action | Offline | How |9|---|---|---|10| Open the app cold (new tab, reload, bookmark, installed PWA) | yes | the service worker answers the navigation with the static shell `/offline`, which reads the device replica |11| Read any note that was synced (content included) | yes | replica store `pages` |12| Search the notes on the device (title + text, substring) | yes | in memory over the replica; the server search index, semantic search and AI are **not** available |13| Edit a note (title, content) | yes | per-page versioned draft (`drafts`), sent on reconnect with `baseVersion` |14| Create a note | yes | client-chosen uuid, journal entry `page.create` |15| Pin / archive / move / rename (tree) / trash / restore, tags | yes | journal entries `page.update`, `page.trash`, `page.restore`, `page.tags` |16| Tasks: create, edit, complete, reopen, delete | yes | client-chosen uuid, `task.create` / `task.update` / `task.delete` |17| Quick capture (text, link) | yes | the existing capture outbox (idempotency key = item id) |18| Add an image to a note | yes, bounded | **10 MB per image, 100 MB queued in total**; kept as a blob, shown from the device, uploaded later under the same attachment id |19| Add another kind of file (PDF, audio…), record a voice note | no | refused with a clear message; needs a connection |20| Databases, canvases, graph, research, AI, settings, version history, conflict resolution | no (read-only notice) | they open when the connection returns. Database / canvas pages are listed but not rendered offline |2122Lazily loaded editor blocks (Mermaid, PDF viewer) work offline only if their code was loaded once online on this device (the worker23caches build assets on first use; the shell's own assets are pre-cached).2425## 2. Pieces2627| File | Role |28|---|---|29| `public/sw.js` (v3, cache `note-static-v4`) | navigation: network (12 s timeout) → fallback to the cached shell `/offline`; build assets cache-first; `/api/files/<id>`: network, and only when the server cannot answer with the file, the image still queued on the device; message `REFRESH_SHELL` re-caches the shell of the running build |30| `src/app/offline/page.tsx` + `src/components/offline/OfflineApp.tsx` | the static shell (no data in the HTML) and the offline app: home, note (real editor), inbox, tasks, capture; same addresses as online (`/`, `/p/<id>`, `/tasks`, `/inbox`, `/share`) |31| `src/lib/client/offline.ts` | IndexedDB `note-local` **version 2**: `drafts`, `outbox` (unchanged) + `pages`, `tasks`, `attachments`, `journal`, `blobs`, `meta`; `wipeLocalData()` clears all of them |32| `src/lib/client/replica.ts` | `pullReplica()` (change feed), `replicaTree()`, `verifyIntegrity()` |33| `src/lib/client/journal-core.ts` | pure rules: request mapping, coalescing, de-duplication, error classification, image bounds (unit-tested) |34| `src/lib/client/journal.ts` | `mutate()`, helpers (`createPage`, `updatePageMeta`, `trashPage`, `setPageTags`, `createTask`, `updateTask`, `deleteTask`, `queueImageUpload`), replay (`flushJournal`, `flushDrafts`, `syncNow`, `startSyncEngine`), `ensurePageReady`, `pendingState` |35| `src/lib/client/page-sync.ts` | unchanged autosave engine + 3 hooks: waits for the creation of a page made offline before its first save, keeps the replica current after each confirmed save, registers the open editor so the background replay leaves its draft alone |36| `src/components/offline/SyncStatus.tsx` | status pill (top bar, phone header, offline app) + inspector |37| `src/app/api/sync/integrity/route.ts`, `src/lib/stable-json.ts` | integrity fingerprints (new, additive route) |3839## 3. Replica4041Fed by `GET /api/sync?since=<cursor>&limit=200&kinds=task`, looped until `more` is false. Each window is written to IndexedDB (one42transaction per store) **before** the cursor is saved, so an interrupted sync resumes without skipping a revision. Stored: whole pages43in every state (live, inbox, archived, trash) with content and tags, attachment metadata (never the files), tasks, the tag list;44tombstones delete rows. `reset: true` or another workspace id → the replica is cleared and rebuilt from 0.45Runs at every start of the shell, when the network returns, when the tab becomes visible, every 2 minutes, and after each replay.46Reads that fall back to the replica when the network fails: the page tree of the shell (React Query `tree`), and everything in the47offline app. The replica is never the source of a save: a page save always carries the server version it was based on.4849## 4. Mutation journal5051Entry: `{ seq (auto-increment = replay order), id (idempotency key, constant across attempts), kind, entityId (client uuid), body,52createdAt, attempts, lastError, state: pending|failed }`.5354`mutate(kind, entityId, body)`: (1) apply the effect to the replica; (2) if online and nothing older is waiting, send now — success →55done; network error / 5xx / 408 / 425 / 429 → fall through; other 4xx → thrown to the caller as before (replica refreshed);56(3) otherwise write to the journal, merging with the last pending entry of the same entity when that cannot change the order of57effects (update+update, tags+tags, update folded into a create that was never attempted); a create whose id is already queued is skipped.5859Replay (`flushJournal`), oldest first, one request at a time, under the Web Lock `note-journal` (one tab at a time):60success → entry deleted; transient error (network, 5xx, 401, 408, 425, 429) → **stop**, same entry and same key next time;61404/410 on a deletion → done; any other 4xx (incl. 409) → entry parked as `failed` (visible in the inspector with Retry / Discard) and62the following entries go on. Duplicates are impossible by construction: creates carry the client id (the server answers the stored63row, `x-existing: 1`), every request carries its idempotency key, uploads carry the attachment id.6465Page text is not journaled keystroke by keystroke: it is the existing per-page draft (one coalesced `PATCH` with `baseVersion`).66`flushDrafts` sends the drafts of pages that are **not open in this tab** after the journal (a page is created before it is edited);67the open page is saved by its own editor, which first calls `ensurePageReady` (replays the journal if the page was created offline,68then adopts the created version). A page created offline has `version: 0` on the device until the server confirms it.6970## 5. Conflicts — never a silent overwrite7172A draft `PATCH` refused with `409 conflict`: if the server copy equals what the device wanted to write, the draft is dropped (our own73earlier save won); otherwise nothing is written, the draft stays on the device, and the conflict is recorded (`meta` key74`conflict:<pageId>`) and listed in the inspector with a link to the note. Opening the note online shows the **existing** conflict75banner (Compare / Keep mine / Keep theirs / Keep both → `POST /api/pages/<id>/resolve`), which keeps both versions (history or a76"(conflict copy)" page). The offline app shows a notice and hands over to the full app for the choice.7778## 6. Status and inspector7980Pill states: `Synced` · `N to sync` · `Offline` / `Offline · N waiting` · `N to review` (refused entries, conflicts). The inspector81shows: online/offline, last sync, replica size (notes, tasks, storage estimate), last sync error, the conflicts, every waiting item82(journal entries with their label, attempts and last error; page drafts; captures; queued images with the bound), **Sync now**, and83**Verify integrity**.8485## 7. Integrity check8687`GET /api/sync/integrity` → `{ algorithm: "sha256-stable-json-1", count, pages: [{ id, version, hash }] }` — `hash` = SHA-256 of the88canonical JSON of `content` (keys sorted). The device hashes each replica page the same way (WebCrypto): same version + different89hash → damaged copy, fetched again and replaced (`repaired`); different version / missing / extra → the replica is only behind90(counted, fixed by a sync); pages created on the device and not yet sent are left alone. The report is kept in `meta.integrity`.9192## 8. Privacy rules (unchanged, extended)9394- The HTTP cache (Cache Storage) holds only public files: the static shell `/offline`, the manifest, icons and hashed build assets.95 No API response, page HTML, RSC payload or uploaded file is ever cached (asserted by the e2e suite on the real cache content).96- The replica, the journal, drafts, captures and queued images live in IndexedDB `note-local`; not encrypted (same rationale as the97 drafts: a key readable by the same JavaScript adds nothing). **"Lock this device" / sign-out everywhere / removing the passkey of98 the current session erase all of it** (`wipeLocalData`), after which the offline app has nothing to show.99- A session that merely expires does not erase the device copy (that would lose unsent text); the next request answers 401 and the100 app goes to the sign-in page.101102## 9. PWA share target103104`manifest.webmanifest` declares `share_target` (GET `/share?title=&text=&url=`): online it opens the capture sheet prefilled; offline105the shell shows the same text in its capture form (outbox).106107## 10. Known limits108109- No Background Sync API: replay happens while the app is open (start, network back, tab visible, every 2 min).110- A rename done from the tree while offline is last-writer-wins (unversioned `PATCH`, as online); text and titles edited in the note111 itself are versioned.112- Offline search is a substring scan of the replica, not the server index.113- Only images are queued offline; other attachments need a connection.114- `navigator.onLine` can lie (captive portal): the offline app probes `GET /api/health` every 15 s before handing over.115