diff --git a/.github/workflows/desktop-storage-soak.yml b/.github/workflows/desktop-storage-soak.yml new file mode 100644 index 00000000..aca44f4d --- /dev/null +++ b/.github/workflows/desktop-storage-soak.yml @@ -0,0 +1,152 @@ +name: Desktop storage soak + +# Plan T1–T8 (P2.6): the storage worker on node:sqlite inside Electron, +# SIGKILLed during appends, compactions and migrations, quit with writes in +# flight, opened by an older app, and run through a simulated year with +# 1,000 documents. The verifier reopens every library with the engine on +# bun:sqlite. See tests/load/desktop-durability-soak.ts. +# +# Pull requests that touch storage run a short profile (20 kills per case); +# the nightly and manual runs use the plan's 200, and so does a pull request +# labelled `storage-soak-full` (workflow_dispatch needs the file on main). +# Not a required check. +# Read-only token and no secrets, like CI. + +on: + pull_request: + types: [opened, synchronize, reopened, labeled] + paths: + - desktop/storage/** + - desktop/storage-harness/** + - desktop/dev/bun-sqlite-driver.ts + - lib/platform/desktop/** + - lib/platform/doc-store.ts + - tests/helpers/doc-store-contract.ts + - tests/load/desktop-durability-soak.ts + - .github/workflows/desktop-storage-soak.yml + workflow_call: + inputs: + kills: + type: number + default: 200 + workflow_dispatch: + inputs: + kills: + description: Kills per kill case (T1, T2; T1-dense runs half) + type: number + default: 200 + +permissions: + contents: read + +concurrency: + group: desktop-storage-soak-${{ github.event.pull_request.number || github.ref }}-${{ github.event_name }} + cancel-in-progress: true + +jobs: + soak: + name: ${{ matrix.group.name }} (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 90 + permissions: + contents: read + strategy: + fail-fast: false + matrix: + os: [macos-26, windows-latest, ubuntu-24.04] + group: + - name: contract, T3–T6 + cases: contract,T3,T4,T5,T6 + - name: T1 kill during append + cases: T1,T1-dense + - name: T2 kill during compaction + cases: T2 + - name: T8 year and startup + cases: T8 + defaults: + run: + shell: bash + env: + KILLS: ${{ github.event_name != 'pull_request' && (inputs.kills || 200) || contains(github.event.pull_request.labels.*.name, 'storage-soak-full') && 200 || 20 }} + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Set up Bun + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + with: + bun-version-file: .tool-versions + + # The root install brings Yjs and the engine's dependencies; the + # harness has its own lockfile with Electron, whose binary downloads + # on first use. + - name: Install + run: | + bun install --frozen-lockfile + cd desktop/storage-harness + bun install --frozen-lockfile + bun -e 'require("electron")' + + # Everything after install runs on Bun. The runner image ships Node, + # so a stub makes any call to it fail loudly. Install comes first: + # lifecycle scripts (husky) call `node`. + - name: Block Node.js + run: | + mkdir -p "$RUNNER_TEMP/no-node" + cat > "$RUNNER_TEMP/no-node/node" <<'EOF' + #!/bin/sh + echo "::error::node was called: $*" >&2 + exit 1 + EOF + chmod +x "$RUNNER_TEMP/no-node/node" + echo "$RUNNER_TEMP/no-node" >> "$GITHUB_PATH" + + # Windows process spawns look for node.exe and never run the sh stub + # above, so put a compiled stub beside it (found in spike S3). + - name: Block Node.js (node.exe on Windows) + if: runner.os == 'Windows' + run: | + cat > "$RUNNER_TEMP/node-stub.ts" <<'EOF' + console.error(`::error::node was called: ${process.argv.slice(2).join(" ")}`); + process.exit(1); + EOF + bun build --compile "$RUNNER_TEMP/node-stub.ts" --outfile "$RUNNER_TEMP/no-node/node.exe" + if cmd.exe //d //c "node --version" > /dev/null 2>&1; then + echo "::error::the node.exe stub is not first on PATH" + exit 1 + fi + + - name: Audit the harness dependencies + working-directory: desktop/storage-harness + run: bun audit --audit-level=high + + - name: Typecheck and build the harness + working-directory: desktop/storage-harness + run: | + bun run typecheck + bun run build + + - name: Allow the Chromium sandbox (electron/electron#42510) + if: runner.os == 'Linux' + run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 + + - name: Soak + env: + CASES: ${{ matrix.group.cases }} + run: | + if [ "$RUNNER_OS" = Linux ]; then + xvfb-run -a bun tests/load/desktop-durability-soak.ts --case="$CASES" --kills="$KILLS" --out=soak-out + else + bun tests/load/desktop-durability-soak.ts --case="$CASES" --kills="$KILLS" --out=soak-out + fi + + - name: Upload results + if: always() + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: storage-soak-${{ matrix.os }}-${{ strategy.job-index }} + path: soak-out + if-no-files-found: ignore + retention-days: 30 diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 242b8b14..c8e95e8c 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -11,8 +11,13 @@ name: Nightly # from 3 clients against Hocuspocus (spec §7 abuse soak) # mixed-version N+1, release N and pre-N clients on one document with # the gate env at its default (spec §3.1 N+1 ship gate) +# desktop-renderer the desktop static export (bun run build:desktop) on +# Linux, where releases build it (#103), served with the +# protocol handler's path rules, under the desktop project # desktop-smoke the D-A12 Electron smoke (desktop-smoke.yml) on macOS, # Windows and Linux +# desktop-storage-soak plan T1–T8 against the storage worker in Electron +# (desktop-storage-soak.yml), 200 kills per case, 3 OSes # # Read-only token and no secrets, like CI. A red run means a regression in # offline editing, long sessions, concurrency or schema rollout safety that @@ -354,6 +359,70 @@ jobs: if-no-files-found: ignore retention-days: 7 + desktop-renderer: + name: Desktop renderer (static export) + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: read + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Set up Bun + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + with: + bun-version-file: .tool-versions + + - name: Install + run: bun install --frozen-lockfile + + - name: Install Chromium + run: bun playwright install --with-deps chromium + + # Fails if a web-only route or web metadata tag reaches out/, or on the + # Windows segment layout; leaves app/ as it was. + - name: Desktop export + run: NEXT_PUBLIC_HOCUS_URL=ws://127.0.0.1:1234 bun run build:desktop + + - name: Web-only files are back in app/ + run: git diff --exit-code --stat -- app + + # The renderer still syncs through Hocus until the dev bridge (P2.4, + # after P2.1 and P2.2) replaces it. + - name: Start servers + id: servers + run: | + PORT=3849 bun scripts/serve-desktop-export.ts > "$RUNNER_TEMP/serve.log" 2>&1 & + make dev-hocus > "$RUNNER_TEMP/hocus.log" 2>&1 & + for _ in $(seq 1 60); do + if curl -s -o /dev/null http://127.0.0.1:1234 && + curl -sf -o /dev/null http://127.0.0.1:3849/; then + exit 0 + fi + sleep 1 + done + echo "::error::servers did not start" + exit 1 + + - name: Run the desktop project + run: >- + DESKTOP_BASE_URL=http://127.0.0.1:3849 CI= + bun playwright test --project=desktop --trace retain-on-failure + + - name: Upload failure artifacts + if: failure() + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: nightly-desktop-renderer + path: | + test-results/ + ${{ runner.temp }}/*.log + if-no-files-found: ignore + retention-days: 7 + # D-A12: node:sqlite, WAL, a worker thread and a custom app protocol in the # pinned Electron build, on the nightly schedule (no cron of its own). desktop-smoke: @@ -361,3 +430,11 @@ jobs: permissions: contents: read uses: ./.github/workflows/desktop-smoke.yml + + desktop-storage-soak: + name: Desktop storage soak (T1–T8) + permissions: + contents: read + uses: ./.github/workflows/desktop-storage-soak.yml + with: + kills: 200 diff --git a/.gitignore b/.gitignore index e62721d3..946a7a1d 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,8 @@ # next.js /.next/ /out/ +# web metadata files parked during a desktop export (scripts/build-desktop.ts) +/.desktop-export-parked/ # production /build diff --git a/CHANGELOG.md b/CHANGELOG.md index d357f514..7cb26d24 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,161 @@ since the previous tag. ## [Unreleased] +### Desktop P2.6: the library storage worker + +The SQLite engine behind the desktop library, where documents, folders and +tags live, and the `worker_thread` that runs it inside Electron main (D-A1). +Nothing in the web app or its build uses it yet; P2.5's shell starts the +worker and P2.7 builds the files sidebar on it. + +#### Added + +- **Desktop:** `desktop/storage/engine/`, with no `node:`, `bun:` or + Electron imports, behind a `SqliteDriver` seam (`node:sqlite` in the + worker, `bun:sqlite` in tests and the dev host): + - the format-1 schema, so the Local release needs no later migration: + `docs` (lineage and a `NOT NULL` `link_key` minted at insert, `kind`, the + list columns), `folders`, `tags`, `doc_tags`, `doc_view(doc_id, width, + place, remote_images)`, `import_sources`, `snapshots` and `updates` with + an `AUTOINCREMENT` seq; + - the open order: cloud-synced folders refused, `library.lock` with a pid + check, WAL with `synchronous=FULL` (`fullfsync` on macOS), and the + `format_version` guard before any write, so a newer library opens + read-only and untouched; `quick_check` after an unclean exit; + - format migrations with a `VACUUM INTO` copy first (2 kept), one + transaction per step, and read-only on failure; + - appends and renderer-driven compaction in one transaction each, with + one window per document (`already_open`, `forbidden`, `document_open`); + - documents, folders, tags, Trash (emptied after 30 days) and the sidebar + snapshot, with a change feed: every change the sidebar shows, appends + included, moves `rev`, and the worker sends `index_changed` with the + changed rows; + - a daily `VACUUM INTO` copy on the first idle moment, keeping 7, and a + reader for restoring one document from a day; + - shutdown for the quit flush: WAL checkpoint, `unclean_exit` cleared, + lock released. +- **Desktop:** `desktop/storage/worker.ts` and `client.ts`: the worker + answers main one request at a time with `Result` envelopes and transferred + bytes; the client rejects pending calls with `worker_restarting` if the + worker dies and ends with a 2 s shutdown. +- **Platform:** `lib/doc-migrations/` (the open-time migration hook list, + empty so far, and `checkImport`, which refuses an import that is too + large, isn't Yjs, or carries a node, mark or root this build doesn't + know) and `lib/platform/desktop/rpc-doc-store.ts` (`DocStore` over worker + replies, for `IpcDocStore`). +- **Tests:** P2.1's shared `DocStore` contract on the engine, on + `bun:sqlite` under `bun test` and on `node:sqlite` inside the Electron + worker; engine suites (open, content, index and its change feed, daily + copies, codes, and a property test of random appends, compactions, + crashes and reopens); the import-boundary test's storage rows; and + `tests/load/desktop-durability-soak.ts` with its Electron harness in + `desktop/storage-harness/` for soak cases T1–T6 and T8. +- **CI:** `desktop-storage-soak.yml` on macOS, Windows and Linux: 20 kills + per case on pull requests that touch storage, 200 nightly or with the + `storage-soak-full` label. `bun run typecheck` also checks the new + `tsconfig.desktop-node.json`. + +#### Changed + +- **Docs:** the desktop architecture spec records where P2.6 put the engine + and the harness, the worker-side registry check and `claim`, the + import-boundary allowance for `lib/schema-names.ts`, and that T7 is covered + by `local-session`'s tests, not the storage soak. + +### Editor without a provider; WriteGate; the editor-chunk fence (P2.2) + +Desktop Phase 2, P2.2. The web editor behaves as before: it still gets its +provider, and nothing passes the new read-only prop. The editor chunk goes +from +15,284 B to +15,578 B (+294 B of P2.2's 300 B line in the D23 ledger), +and the budget drops from 23.5 KB to +16,864 B (`main` plus the 1,580 B +ledger), leaving 1,286 B for the ledger's other lines. No schema or protocol +change; no Deploy note. + +#### Added + +- **Editor:** `DocumentEditor` takes the session's Awareness and accepts no + provider. With none, the connection chip isn't rendered and no socket + opens. Carets use the Awareness directly, and the extension list depends + on it rather than on the provider, so attaching a provider later never + rebuilds the extensions (no `setOptions`). +- **Editor:** `WriteGate` (`extensions/write-gate/`), a `filterTransaction` + plugin over a ref. With the new `readOnly` prop, no local ProseMirror + change reaches the document, including the writes plugins make when a + document opens. Changes from collaborators still apply. The schema + guard's repair writes Yjs directly and is not gated yet; it must be when + something first sets `readOnly`. +- **Editor:** the decoration host (`extensions/decoration-host/`): declared + layers each get a plugin holding a `DecorationSet`, set by the meta-only + `setDecorationLayer` command, either mapped or cleared on document + changes. No layer is declared yet; comments and Find will declare theirs. + +#### Changed + +- **Build:** `scripts/check-editor-chunk-size.ts` budget is `main` at + P2.2 plus the D23 ledger (+16,864 B), and it prints exact bytes. + +### Desktop renderer export (P2.4) + +`bun run build:desktop` builds the desktop renderer: the static export the +Electron shell will load. The web build is unchanged. Its route table, client +chunks (names and sizes), manifests and every page apart from `/icon`'s URL +match `main`. The `/icon?` cache-buster changes because `app/icon.tsx` +gained `dynamic = "force-static"`; the PNG is byte-identical. + +#### Added + +- `bun run build:desktop` (`scripts/build-desktop.ts`) writes `out/` with + `NEXT_PUBLIC_APP_TARGET=desktop` and `output: "export"`. Desktop routes: + `/`, `/about`, `/_not-found`, `/icon`. It fails if a web-only route, a web + metadata tag or the Windows segment layout (#103) reaches `out/`. +- `desktop/shared/export-paths.ts`: the `app://` protocol handler's path rules + for P2.5. `/about` maps to `about.html`, RSC `.txt` files keep their + exported names, and the extension-less `/icon` is `image/png`. Unknown + types and traversal are refused. `scripts/serve-desktop-export.ts` serves + `out/` with them for tests. +- The `desktop` Playwright project runs on the export instead of `next start`. + It checks that every request the renderer makes is answered and none goes + to a web-only route. Nightly runs it on Linux (`desktop-renderer`). + +#### Changed + +- Web-only route handlers are `route.web.ts(x)` (`app/api/**`, `llms.txt`, + `pwa-icons/[id]`). `next.config.ts` switches `pageExtensions`, `output` and + `headers()` on the target flag. +- The export parks the five web metadata files and the `/privacy` and + `/offline` pages in `.desktop-export-parked/` for the build and puts them + back, as spike #115 measured is required. Renaming the pages would drop + their font preload on the web: Next 16.4.6 looks up `page.web` in a font + manifest keyed `page`. +- `next.config.ts` refuses a web build while anything is parked. +- The desktop build never registers the service worker, whose precache lists + `/privacy` (#117 follow-up). + +### Design: selection bubble and quick insert + +A draft design for the owner's review: a fuller one-row selection bubble, a +caret-local way to insert blocks, amendments to the "/" menu (Suggested, an +inline hint, a footer), and a phone Insert sheet. Documentation only; no app +or server change. + +#### Added + +- **Docs:** + - `docs/superpowers/specs/2026-11-17-bubble-and-quick-insert-design.md`: + the audit of today's bubble, Insert, "/" and phone surfaces; research + across eight editors (two rounds of owner references, including Notion's + panel and "/" menu) and the platform guidance; the proposed design with + owner decisions O1–O12; and a phased plan. + - `docs/design/2026-11-17-bubble-quick-insert-prototype.html`: a clickable + prototype with a switch for each decision, theme, RTL, reduced motion and + device. + - Screenshots of today's UI and of the prototype in + `docs/design/2026-11-17-bubble-quick-insert/`. +- **Finding:** the lazy selection bubble mounts Tiptap's React ``, + which calls `registerPlugin` from a lazy chunk. When the chunk lands it + rebuilds every plugin view (29 of 29 measured), after the editor is already + interactive. The spec's phase 0 replaces it. + ### Desktop P2.1b: `local-session`, the batcher and `MemoryDocStore` The second half of desktop plan P2.1: the platform-neutral storage path that diff --git a/README.md b/README.md index 27f3b898..60318913 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,7 @@ building; setting them at runtime has no effect. | `NEXT_PUBLIC_OFFLINE_CACHE` | on | `0` turns off offline document copies and deletes stored ones. | | `NEXT_PUBLIC_ACTION_PREVIEW` | on | `0` turns off colour previews: pointing at or arrowing to a swatch no longer shows it on the selection. | | `NEXT_PUBLIC_REMEMBER_CHOICES` | on | `0` stops the toolbar remembering choices (last colours, recent colours, list type, table size, Simplified toolbar) and the "Continue where you left off" place: it shows the defaults and writes nothing, and the Simplified toolbar item is disabled with the reason. Choices stay in this browser (`tinydocy-choices`, `tinydocy-ui`, `tinydocy-continue`) and never reach the document, the server, URLs or analytics. | -| `NEXT_PUBLIC_APP_TARGET` | `web` | `desktop` for the desktop app's build: Subscript moves to ⌘⇧, so ⌘, can open Settings; Privacy links to the website's page in a new window; X posts render as a link card with no X script, and the Embed dialog leaves X out. See arch §3.1 in the desktop architecture spec. | +| `NEXT_PUBLIC_APP_TARGET` | `web` | `desktop` for the desktop app's build: Subscript moves to ⌘⇧, so ⌘, can open Settings; Privacy links to the website's page in a new window; X posts render as a link card with no X script, and the Embed dialog leaves X out; the service worker never registers. `bun run build:desktop` sets it and writes the static export to `out/`, without the API, `/privacy`, `/offline`, `llms.txt`, the sitemap, robots, manifest and social images. See arch §3.1 in the desktop architecture spec. | | `NEXT_PUBLIC_BUILD_ID` | short git commit, else package version | Build identifier the client sends as `build=` on the socket URL; shows up in the server's per-minute `client_schema` log line. | | `NEXT_PUBLIC_MAX_EMBED_IMAGE_BYTES` | 262144 | Images are downscaled in the browser to this size before embedding. | | `NEXT_PUBLIC_MAX_TABS_PER_CLIENT` | 50 | Tab cap in the UI. | @@ -240,6 +240,7 @@ Release notes for each change, including deploy steps, are in the |---|---| | `make dev` | Next.js and Hocuspocus together. | | `bun run build` / `bun run start` | Production build and server. | +| `bun run build:desktop` | The desktop renderer: static export to `out/` (built on Linux for releases). | | `bun run test` | Unit tests with `bun test` (the stress probe runs with `test:stress`). | | `bun run test:e2e` | Playwright against `make dev` (set `CI=` to reuse running servers). | | `bun run test:pwa` | Service worker and offline tests against a production build (`PWA_BASE_URL`). | diff --git a/app/api/documents/[id]/route.ts b/app/api/documents/[id]/route.web.ts similarity index 100% rename from app/api/documents/[id]/route.ts rename to app/api/documents/[id]/route.web.ts diff --git a/app/api/documents/closed/route.ts b/app/api/documents/closed/route.web.ts similarity index 100% rename from app/api/documents/closed/route.ts rename to app/api/documents/closed/route.web.ts diff --git a/app/api/documents/restore/route.ts b/app/api/documents/restore/route.web.ts similarity index 100% rename from app/api/documents/restore/route.ts rename to app/api/documents/restore/route.web.ts diff --git a/app/icon.tsx b/app/icon.tsx index 86cbb190..485aa5ac 100644 --- a/app/icon.tsx +++ b/app/icon.tsx @@ -2,6 +2,8 @@ import { ImageResponse } from "next/og"; import { BrandMark } from "@/components/brand"; +// Static in both builds; the desktop export (output: "export") requires it. +export const dynamic = "force-static"; export const size = { width: 512, height: 512 }; export const contentType = "image/png"; diff --git a/app/llms.txt/route.ts b/app/llms.txt/route.web.ts similarity index 100% rename from app/llms.txt/route.ts rename to app/llms.txt/route.web.ts diff --git a/app/pwa-icons/[id]/route.tsx b/app/pwa-icons/[id]/route.web.tsx similarity index 100% rename from app/pwa-icons/[id]/route.tsx rename to app/pwa-icons/[id]/route.web.tsx diff --git a/components/document-editor/document-editor-config.ts b/components/document-editor/document-editor-config.ts index 484c94eb..de09cc58 100644 --- a/components/document-editor/document-editor-config.ts +++ b/components/document-editor/document-editor-config.ts @@ -31,6 +31,7 @@ import type { EditorState, Transaction } from "@tiptap/pm/state"; import { StarterKit } from "@tiptap/starter-kit"; import DOMPurify from "dompurify"; import { Marked, type marked } from "marked"; +import type { Awareness } from "y-protocols/awareness"; import type * as Y from "yjs"; import { HorizontalRule } from "@/components/tiptap-node/horizontal-rule-node/horizontal-rule-node-extension"; @@ -45,6 +46,7 @@ import { renderCaret, renderCaretSelection, } from "@/extensions/collaboration-caret/safe-caret-render"; +import { DecorationHost } from "@/extensions/decoration-host/decoration-host"; import { EditorActionShortcuts } from "@/extensions/editor-action-shortcuts"; import { HeadingDrag } from "@/extensions/heading-drag"; import { @@ -65,6 +67,7 @@ import { FastTableOfContents } from "@/extensions/table-of-contents"; import { FontSize, TextColor } from "@/extensions/text-style-marks"; import { TitleDocument } from "@/extensions/title-document"; import { TokenHighlight } from "@/extensions/token-highlight"; +import { WriteGate } from "@/extensions/write-gate/write-gate"; import { SUBSCRIPT_SHORTCUT } from "@/lib/app-shortcuts"; import { lowlight } from "@/lib/lowlight"; @@ -143,7 +146,15 @@ function createMarkedInstance(): typeof marked { interface BuildDocumentEditorExtensionsOptions { documentId: string; ydoc: Y.Doc; - provider: HocuspocusProvider; + /** + * The session's one Awareness. It outlives any provider, so attaching or + * detaching one never rebuilds the extensions (no `setOptions`). + */ + awareness: Awareness; + /** The provider of the moment, if any; read, never a dependency. */ + getProvider: () => HocuspocusProvider | null; + /** WriteGate's check: false blocks every local document change. */ + canWrite: () => boolean; onFoldChange: (foldedIds: Set) => void; onFilterChange: (state: HeadingFilterCallbackState) => void; onTocUpdate: (anchors: TableOfContentData) => void; @@ -176,7 +187,9 @@ function createHeadingFilterFoldAdapter() { export function buildDocumentEditorExtensions({ documentId, ydoc, - provider, + awareness, + getProvider, + canWrite, onFoldChange, onFilterChange, onTocUpdate, @@ -234,11 +247,22 @@ export function buildDocumentEditorExtensions({ CaretBlockVisible, RepeatFormatting, SlashTrigger, + // The caret reads only `provider.awareness` (3.x runtime), so it gets + // the session's Awareness and works with no provider at all. UniqueID + // finds this option too and waits for its "synced" event: forwarded to + // the provider of the moment, as before (none on desktop Local). CollaborationCaret.configure({ - provider, + provider: { + awareness, + on: (event: string, fn: () => void) => getProvider()?.on(event, fn), + off: (event: string, fn: () => void) => getProvider()?.off(event, fn), + }, render: renderCaret, selectionRender: renderCaretSelection, }), + WriteGate.configure({ canWrite }), + // Comment highlights and Find hits declare their layers here (rule 6). + DecorationHost, HorizontalRule, TextAlign.configure({ types: ["heading", "paragraph"] }), TaskList, diff --git a/components/document-editor/document-editor.tsx b/components/document-editor/document-editor.tsx index 4dfdd2d9..9491472b 100644 --- a/components/document-editor/document-editor.tsx +++ b/components/document-editor/document-editor.tsx @@ -14,6 +14,8 @@ import { useState, useSyncExternalStore, } from "react"; +import type { HocuspocusProvider } from "@hocuspocus/provider"; +import type { Awareness } from "y-protocols/awareness"; import type * as Y from "yjs"; import { focusRovingItem, Toolbar } from "@/components/ui/toolbar"; @@ -91,11 +93,20 @@ interface DocumentEditorProps { playgroundRegenerateTrigger?: number; /** The Playground tab's Regenerate, also run from the palette. */ onPlaygroundRegenerate?: () => void; + /** + * View only: no local ProseMirror change reaches the document, plugin + * writes on open included (WriteGate, details spec §1). The schema + * guard's Yjs repair is not gated yet. The web sandbox never sets it. + */ + readOnly?: boolean; } type DocumentEditorContentProps = DocumentEditorProps & { ydoc: Y.Doc; - provider: import("@hocuspocus/provider").HocuspocusProvider; + /** The session's one Awareness: carets and names, with or without a provider. */ + awareness: Awareness; + /** Null for a document with no server (desktop Local): nothing dials out. */ + provider: HocuspocusProvider | null; documentId: string; /** Why the server refuses edits (size, deleted, outdated…), if it does. */ rejectedReason: string | null; @@ -145,12 +156,14 @@ const EDITOR_PROPS = { function DocumentEditorContent({ ydoc, + awareness, provider, documentId, onTitleChange, initialContent, playgroundRegenerateTrigger, onPlaygroundRegenerate, + readOnly, rejectedReason, serverSynced, }: DocumentEditorContentProps) { @@ -191,22 +204,32 @@ function DocumentEditorContent({ // A repair deferred while refused (offline budget) runs now. if (rejectedReason === null) schemaGuard.onWritable(); }, [rejectedReason, schemaGuard]); + // Read by the extensions, never their deps: WriteGate on every + // transaction (from the first one on), UniqueID when it waits for a sync. + const liveRef = useRef({ provider, readOnly }); + useEffect(() => { + liveRef.current = { provider, readOnly }; + }, [provider, readOnly]); // `useEditor` compares its options on every render and, when any differ, // calls `editor.setOptions`: a full view update that also re-syncs the - // whole document to Yjs. Keep every option stable between renders. + // whole document to Yjs. Keep every option stable between renders: the + // deps hold the Awareness, never the provider, so attaching one later + // keeps this array. const extensions = useMemo( () => buildDocumentEditorExtensions({ documentId, ydoc, - provider, + awareness, + getProvider: () => liveRef.current.provider, + canWrite: () => !liveRef.current.readOnly, onFoldChange: setFoldedIds, onFilterChange: setFilterState, onTocUpdate: tocStore.set, onInvalidContent: schemaGuard.onInvalidContent, }), - [documentId, ydoc, provider, tocStore, schemaGuard], + [documentId, ydoc, awareness, tocStore, schemaGuard], ); const editor = useEditor({ @@ -235,8 +258,8 @@ function DocumentEditorContent({ // Stop accepting input the server would drop or the schema can't hold. useEffect(() => { - if (editor) editor.setEditable(reason === null); - }, [editor, reason]); + if (editor) editor.setEditable(reason === null && !readOnly); + }, [editor, reason, readOnly]); const headingFilter = useHeadingFilter({ editor, @@ -431,7 +454,8 @@ function DocumentEditorContent({ rejectedReason={rejectedReason} /> )} - + {/* Its connection state opens the shared socket: only with a provider. */} + {provider && } ); @@ -443,12 +467,13 @@ export function DocumentEditor({ initialContent, playgroundRegenerateTrigger, onPlaygroundRegenerate, + readOnly, }: DocumentEditorProps = {}) { const docId = documentId ?? "default"; - const { ydoc, provider, synced, serverSynced, rejectedReason } = + const { ydoc, awareness, provider, synced, serverSynced, rejectedReason } = useYjsDocument(docId); - if (!synced || !ydoc || !provider) { + if (!synced || !ydoc || !awareness) { return ( <> {/* Refused with no device copy: explain instead of loading forever. */} @@ -463,12 +488,14 @@ export function DocumentEditor({ return ( diff --git a/components/pwa/service-worker-registration.tsx b/components/pwa/service-worker-registration.tsx index 3f5b104d..7abb9f75 100644 --- a/components/pwa/service-worker-registration.tsx +++ b/components/pwa/service-worker-registration.tsx @@ -7,10 +7,13 @@ import { CACHE_PREFIX } from "@/lib/pwa/sw-config"; /** * Build-time switch, inlined by `bun run build`: NEXT_PUBLIC_SERVICE_WORKER=0 * unregisters the worker and deletes its caches on the next load. Development - * never registers, and removes a production worker left on localhost. + * never registers, and removes a production worker left on localhost. The + * desktop renderer never registers either: it is served from disk, and the + * worker precaches web-only pages (`SHELL_PATHS` has `/privacy`). */ -const SERVICE_WORKER_ENABLED = +export const SERVICE_WORKER_ENABLED = process.env.NODE_ENV === "production" && + process.env.NEXT_PUBLIC_APP_TARGET !== "desktop" && process.env.NEXT_PUBLIC_SERVICE_WORKER !== "0"; const IDLE_TIMEOUT_MS = 10_000; diff --git a/desktop/dev/bun-sqlite-driver.ts b/desktop/dev/bun-sqlite-driver.ts new file mode 100644 index 00000000..4e915202 --- /dev/null +++ b/desktop/dev/bun-sqlite-driver.ts @@ -0,0 +1,56 @@ +/** + * `SqliteDriver` over `bun:sqlite`, for unit tests and the dev storage host + * (architecture §11). Normalizes Bun's differences from `node:sqlite`: a + * missing row is `null` in Bun and `undefined` here, and integers stay + * numbers (`safeIntegers` off). + * + * `close` finalizes every cached statement first: Bun's `close()` leaves a + * connection with live statements open as a zombie that keeps the file + * handles, which on Windows blocks deleting or replacing the library. + */ +import { Database } from "bun:sqlite"; + +import type { + OpenSqlite, + SqliteDriver, + SqliteStatement, + SqlRow, + SqlValue, +} from "@/desktop/storage/engine/driver"; + +export const openBunSqlite: OpenSqlite = (path, { readOnly }) => { + const db = readOnly + ? new Database(path, { readonly: true }) + : new Database(path, { create: true }); + const cache = new Map(); + const statements: { finalize(): void }[] = []; + const driver: SqliteDriver = { + exec: (sql) => db.exec(sql), + prepare(sql) { + const cached = cache.get(sql); + if (cached) return cached; + const statement = db.prepare(sql); + statements.push(statement); + const wrapped: SqliteStatement = { + run: (...params) => { + const result = statement.run(...params); + return { + changes: result.changes, + lastInsertRowid: Number(result.lastInsertRowid), + }; + }, + get: (...params) => statement.get(...params) ?? undefined, + all: (...params) => statement.all(...params), + }; + cache.set(sql, wrapped); + return wrapped; + }, + close: () => { + for (const statement of statements) statement.finalize(); + statements.length = 0; + cache.clear(); + db.close(); + }, + }; + return driver; +}; diff --git a/desktop/shared/export-paths.ts b/desktop/shared/export-paths.ts new file mode 100644 index 00000000..00abee85 --- /dev/null +++ b/desktop/shared/export-paths.ts @@ -0,0 +1,87 @@ +/** + * Maps a request path on the desktop origin to a file in the static export + * (`out/`), the way the `app://tinydocy` protocol handler serves it + * (desktop architecture §3.1; hardening checklist P2.4). Pure: the caller + * says which files exist, so the Electron handler (P2.5) and the test + * server (`scripts/serve-desktop-export.ts`) share one rule set. + * + * - `/` → `index.html`, `/about` → `about.html` (a page has a `.html` file + * and a same-named directory of segment payloads). + * - RSC payloads are served as they were exported: `about.txt`, + * `about/__next.about.__PAGE__.txt`. Never renamed (#103: no Windows + * layout mapping). + * - Extension-less files get a type from `EXTENSIONLESS_TYPES`; others are + * refused, so nothing is served without a known type (`nosniff`). + * - Paths that decode to `..`, a backslash, a NUL or an empty segment are + * refused before any lookup. + */ + +export type ExportFile = { + /** Path relative to `out/`, with `/` separators. */ + file: string; + contentType: string; +}; + +const TYPES: Record = { + html: "text/html; charset=utf-8", + js: "text/javascript; charset=utf-8", + css: "text/css; charset=utf-8", + txt: "text/plain; charset=utf-8", + json: "application/json", + svg: "image/svg+xml", + png: "image/png", + ico: "image/x-icon", + woff2: "font/woff2", + woff: "font/woff", + wasm: "application/wasm", +}; + +/** Metadata images Next writes without an extension. */ +export const EXTENSIONLESS_TYPES: Record = { + icon: "image/png", +}; + +function extensionOf(file: string): string | null { + const name = file.slice(file.lastIndexOf("/") + 1); + const dot = name.lastIndexOf("."); + return dot > 0 ? name.slice(dot + 1).toLowerCase() : null; +} + +function typeOf(file: string): string | null { + const ext = extensionOf(file); + if (ext !== null) return TYPES[ext] ?? null; + return EXTENSIONLESS_TYPES[file] ?? null; +} + +/** + * The file to serve for `pathname` (the URL's path, still percent-encoded), + * or null for a 404. `isFile(rel)` reports whether `out/` is a file. + */ +export function resolveExportFile( + pathname: string, + isFile: (rel: string) => boolean, +): ExportFile | null { + let path: string; + try { + path = decodeURIComponent(pathname); + } catch { + return null; + } + if (!path.startsWith("/") || /[\\\0]/.test(path)) return null; + + const rel = path.slice(1).replace(/\/$/, ""); + const segments = rel === "" ? [] : rel.split("/"); + if (segments.some((s) => s === "" || s === "." || s === "..")) return null; + + const candidates = + rel === "" + ? ["index.html"] + : extensionOf(rel) === null + ? [`${rel}.html`, rel, `${rel}/index.html`] + : [rel]; + for (const file of candidates) { + const contentType = typeOf(file); + if (contentType && isFile(file)) return { file, contentType }; + } + return null; +} diff --git a/desktop/storage-harness/.gitignore b/desktop/storage-harness/.gitignore new file mode 100644 index 00000000..8225baa4 --- /dev/null +++ b/desktop/storage-harness/.gitignore @@ -0,0 +1,2 @@ +/node_modules +/dist diff --git a/desktop/storage-harness/build.ts b/desktop/storage-harness/build.ts new file mode 100644 index 00000000..194b77bd --- /dev/null +++ b/desktop/storage-harness/build.ts @@ -0,0 +1,25 @@ +/** + * Bundles the harness main and the real storage worker as CJS for + * Electron, the way `desktop/build/build.ts` (P2.5) will: `node:*` and + * `electron` stay external, everything else (Yjs, the engine) is inlined. + */ +import path from "node:path"; + +const root = import.meta.dir; +const result = await Bun.build({ + entrypoints: [ + path.join(root, "main.ts"), + path.join(root, "../storage/worker.ts"), + ], + outdir: path.join(root, "dist"), + target: "node", + format: "cjs", + external: ["electron"], + naming: "[name].cjs", +}); +if (!result.success) { + for (const log of result.logs) console.error(log); + process.exit(1); +} +for (const output of result.outputs) + console.log(`${path.relative(root, output.path)} ${output.size} B`); diff --git a/desktop/storage-harness/bun.lock b/desktop/storage-harness/bun.lock new file mode 100644 index 00000000..8fb81cc4 --- /dev/null +++ b/desktop/storage-harness/bun.lock @@ -0,0 +1,46 @@ +{ + "lockfileVersion": 2, + "configVersion": 1, + "workspaces": { + "": { + "name": "tinydocy-storage-harness", + "devDependencies": { + "@types/node": "24.19.2", + "electron": "45.3.2", + "typescript": "6.0.3", + }, + }, + }, + "trustedDependencies": [ + "electron", + ], + "packages": { + "@electron-internal/extract-zip": ["@electron-internal/extract-zip@1.0.8", "", {}, "sha512-8iajeLFbzNwM0m3AsQZSZgYREWglAImyGvvFSWU34FgMW8sHlzdwj9QKvv9dgN7jMP591EFUF/sLOC3Jl9YIjQ=="], + + "@electron/get": ["@electron/get@5.1.0", "", { "dependencies": { "debug": "^4.1.1", "env-paths": "^3.0.0", "graceful-fs": "^4.2.11", "progress": "^2.0.3", "semver": "^7.6.3", "sumchecker": "^3.0.1" }, "optionalDependencies": { "undici": "^7.24.4" } }, "sha512-3kSBtG8ObcTVfXanm5vVJ6UnBLEVmVsRk1M+vGqCuMBV+XLCbJYuWQful+yIy0GQDsSlK0kHEriEHn7SPk4EnA=="], + + "@types/node": ["@types/node@24.19.2", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-93d49wCWJkCyN87MxLpNN6KXPCwFw7bVUg79mGUV1OS40JGWwVCr8n61DXCSqz7CV6/VfPkb7xec7uP2M+QHWQ=="], + + "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" }, "peerDependencies": { "supports-color": "*" }, "optionalPeers": ["supports-color"] }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="], + + "electron": ["electron@45.3.2", "", { "dependencies": { "@electron-internal/extract-zip": "^1.0.1", "@electron/get": "^5.0.0", "@types/node": "^24.9.0" }, "bin": { "electron": "cli.js", "install-electron": "install.js" } }, "sha512-bPO0MMvJCdKdPfXgd3ES8zupu+ocr6XmSuRGwyZazTiigTz8jE7rwukSkck0iomS6UZeFuCwzu0uanMD/D34uw=="], + + "env-paths": ["env-paths@3.0.0", "", {}, "sha512-dtJUTepzMW3Lm/NPxRf3wP4642UWhjL2sQxc+ym2YMj1m/H2zDNQOlezafzkHwn6sMstjHTwG6iQQsctDW/b1A=="], + + "graceful-fs": ["graceful-fs@4.2.12", "", {}, "sha512-iuyGF2E4oafQfPsRrG2wtY2ILupMhvtdrhzrxB+0VcjsPpSPttpfYdjnGFGsTi5MaJFjI1jOKHPQ6UTbTj9TAw=="], + + "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="], + + "progress": ["progress@2.0.3", "", {}, "sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA=="], + + "semver": ["semver@7.8.6", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-9lpSSU4Mly3mrtruwLs1eLK6+gzbzqeBFwRNjIjE+9LuDpWdYctrQlQ3ej1Ilgi7gknpsTRnPoLP8DpCHqHIJw=="], + + "sumchecker": ["sumchecker@3.0.1", "", { "dependencies": { "debug": "^4.1.0" } }, "sha512-MvjXzkz/BOfyVDkG0oFOtBxHX2u3gKbMHIF/dXblZsgD3BWOFLmHovIpZY7BykJdAjcqRCBi1WYBNdEC9yI7vg=="], + + "typescript": ["typescript@6.0.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw=="], + + "undici": ["undici@7.30.2", "", {}, "sha512-mLyPQnHwUxaM/rideoK/+KL8DaAJLRl4aBCfmX444aCSLnIaomqPLtNRe2jdCYcsk5wZzXrDIQC8ZeYNRAYyIA=="], + + "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="], + } +} diff --git a/desktop/storage-harness/bunfig.toml b/desktop/storage-harness/bunfig.toml new file mode 100644 index 00000000..d968ccb5 --- /dev/null +++ b/desktop/storage-harness/bunfig.toml @@ -0,0 +1,15 @@ +# Supply-chain guardrail: only resolve package versions that have been +# public for at least 3 days (value in seconds). Gives the registry and the +# community time to catch and unpublish compromised releases before +# `bun add` / `bun update` (local or in CI) can pick them up. +[install] +minimumReleaseAge = 259200 + +# Run package bins (next, eslint, playwright, ...) on the Bun runtime +# instead of Node, for `bun run` scripts and `bun `. Plain `bunx` +# ignores this setting; use `bunx --bun` for packages that are not installed. +[run] +bun = true + +# `bun test`: unit tests only (Playwright specs live in tests/e2e), with a +# happy-dom window preloaded. diff --git a/desktop/storage-harness/format-steps.ts b/desktop/storage-harness/format-steps.ts new file mode 100644 index 00000000..7fa8ef63 --- /dev/null +++ b/desktop/storage-harness/format-steps.ts @@ -0,0 +1,18 @@ +/** + * Format steps for soak T5 (migration interrupted). Each step builds a + * table of {@link STEP_ROWS} rows, slow enough that a kill lands inside one. + * The Electron run and the Bun verifier use the same list. + */ +import type { FormatStep } from "../storage/engine/migrations"; + +export const STEP_ROWS = 150_000; +export const T5_TARGET = 4; + +export const T5_STEPS: FormatStep[] = [2, 3, 4].map((to) => ({ + to, + up(db) { + db.exec(`CREATE TABLE soak_step_${to} (n INTEGER NOT NULL) STRICT`); + const insert = db.prepare(`INSERT INTO soak_step_${to} (n) VALUES (?)`); + for (let n = 0; n < STEP_ROWS; n += 1) insert.run(n); + }, +})); diff --git a/desktop/storage-harness/gen.ts b/desktop/storage-harness/gen.ts new file mode 100644 index 00000000..9ea200d8 --- /dev/null +++ b/desktop/storage-harness/gen.ts @@ -0,0 +1,114 @@ +/** + * Deterministic edits for the durability soak, shared by the Electron churn + * and the Bun verifier. Edit `k` appends `";"` to the text `t`, so a + * stored document is valid exactly when its text is `1;2;…;K;` for some K: + * a lost or half-applied batch shows up as a gap or a short K. + * + * `pad` is filler that makes compactions heavy (the plan's 5 MB document) + * without touching `t`. + */ +import * as Y from "yjs"; + +export const TEXT = "t"; +export const PAD = "pad"; + +/** The K of a stored text, or null if it isn't `1;2;…;K;`. */ +export function editCount(text: string): number | null { + if (text === "") return 0; + const parts = text.split(";"); + if (parts.pop() !== "") return null; + for (const [i, part] of parts.entries()) + if (part !== String(i + 1)) return null; + return parts.length; +} + +export function padUpdate(bytes: number): Uint8Array { + const doc = new Y.Doc(); + // A plain repeated string compresses nothing in Yjs: one item. + doc.getText(PAD).insert(0, "x".repeat(bytes)); + return Y.encodeStateAsUpdate(doc); +} + +export type BatchTiming = { debounceMs: number; maxWaitMs: number }; + +/** The product's batching (architecture §5.2), or the dense soak variant. */ +export const PRODUCT_TIMING: BatchTiming = { debounceMs: 250, maxWaitMs: 1000 }; +export const DENSE_TIMING: BatchTiming = { debounceMs: 5, maxWaitMs: 20 }; + +/** + * A minimal batcher: merges updates, flushes `debounceMs` after the last or + * `maxWaitMs` after the first, and keeps one send in flight. Stand-in for + * P2.1's `lib/platform/batcher.ts`, which the real app uses. + */ +export class SoakBatcher { + private pending: Uint8Array[] = []; + private pendingEdits = 0; + private firstAt = 0; + private timer: ReturnType | null = null; + private inFlight: Promise | null = null; + + constructor( + private readonly timing: BatchTiming, + private readonly send: ( + update: Uint8Array, + lastEdit: number, + ) => Promise, + ) {} + + push(update: Uint8Array, edit: number) { + if (this.pending.length === 0) this.firstAt = performance.now(); + this.pending.push(update); + this.pendingEdits = edit; + this.schedule(); + } + + private schedule() { + if (this.timer) clearTimeout(this.timer); + const sinceFirst = performance.now() - this.firstAt; + const wait = Math.max( + 0, + Math.min(this.timing.debounceMs, this.timing.maxWaitMs - sinceFirst), + ); + this.timer = setTimeout(() => void this.flush(), wait); + } + + get busy(): Promise | null { + return this.inFlight; + } + + /** Sends what is queued, after any send in flight. */ + async flush(): Promise { + if (this.timer) clearTimeout(this.timer); + this.timer = null; + while (this.inFlight) await this.inFlight; + if (this.pending.length === 0) return; + const update = Y.mergeUpdates(this.pending); + const lastEdit = this.pendingEdits; + this.pending = []; + this.inFlight = this.send(update, lastEdit).finally(() => { + this.inFlight = null; + }); + await this.inFlight; + } +} + +/** Parses `--key=value` and `--flag` arguments. */ +export function parseArgs(argv: string[]): Record { + const out: Record = {}; + for (const arg of argv) { + const match = arg.match(/^--([\w-]+)(?:=(.*))?$/); + if (match?.[1]) out[match[1]] = match[2] ?? "1"; + } + return out; +} + +/** A small seeded PRNG (mulberry32), so a soak run can be replayed. */ +export function seededRandom(seed: number): () => number { + let a = seed | 0; + return () => { + a = (a + 0x6d2b79f5) | 0; + let t = Math.imul(a ^ (a >>> 15), 1 | a); + t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; + return ((t ^ (t >>> 14)) >>> 0) / 4294967296; + }; +} diff --git a/desktop/storage-harness/main.ts b/desktop/storage-harness/main.ts new file mode 100644 index 00000000..29715741 --- /dev/null +++ b/desktop/storage-harness/main.ts @@ -0,0 +1,321 @@ +/** + * Electron side of the storage soak (P2.6; plan T1–T8). Runs the real + * storage worker (`worker.cjs`, `node:sqlite`) from a windowless, + * dock-less Electron main. `tests/load/desktop-durability-soak.ts` (Bun) + * launches it, kills it, and verifies the library afterwards with the + * engine on `bun:sqlite`. + * + * Modes (`--mode=`): + * - `contract`: P2.1's shared `DocStore` contract over the worker + * (`CASE_OK` / `CASE_FAIL` lines). + * - `churn`: edits a document with product batching (or `--dense`) until + * killed; `--target=compaction` compacts after every ack; + * `--quit-after-ms` runs the quit flush instead (T4). The worker prints + * `BATCH_BEGIN` / `ACK ` / `COMPACT_BEGIN` / `COMPACT_ACK`; main + * prints `EDITS ` once it has the ack. + * - `migrate`: opens the library on main's thread with the T5 format steps. + * - `readonly`: opens a newer library (T6) and tries to write. + * - `commit-timing`: append round trips with `fullfsync` on or off (T3). + * - `startup`: worker spawn → ready → sidebar rows (T8, the §10 budget). + * + * An uncaught throw in Electron main opens a modal dialog, so every failure + * exits with `process.exit(1)` after printing `HARNESS_FAIL`. + */ +import { mkdtempSync, rmSync, writeSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; + +import { app } from "electron"; +import * as Y from "yjs"; + +import { createRpcDocStore } from "../../lib/platform/desktop/rpc-doc-store"; +import type { DocStore } from "../../lib/platform/doc-store"; +import { + DOC_STORE_CONTRACT, + type DocStoreHarness, +} from "../../tests/helpers/doc-store-contract"; +import { StorageClient } from "../storage/client"; +import { openNodeSqlite } from "../storage/drivers/node-sqlite"; +import { Library } from "../storage/engine/library"; +import { createNodeHost } from "../storage/node-host"; +import { T5_STEPS, T5_TARGET } from "./format-steps"; +import { + DENSE_TIMING, + editCount, + PRODUCT_TIMING, + parseArgs, + SoakBatcher, + seededRandom, + TEXT, +} from "./gen"; + +const args = parseArgs(process.argv.slice(1)); +const say = (line: string) => writeSync(1, `${line}\n`); +const fail = (detail: unknown): never => { + const text = + detail instanceof Error + ? `${detail.message}\n${detail.stack}` + : String(detail); + writeSync(2, `HARNESS_FAIL ${text}\n`); + process.exit(1); +}; +process.on("uncaughtException", fail); +process.on("unhandledRejection", fail); + +app.disableHardwareAcceleration(); +// Only app.exit ends a run; there are no windows to close. +app.on("window-all-closed", () => {}); + +// Not __dirname: Bun.build inlines the source directory (S1, S2). +const workerPath = () => path.join(app.getAppPath(), "worker.cjs"); +const dir = () => args.dir ?? fail("--dir is required"); + +/** Copies bytes before they are transferred, as IPC would. */ +function copied(value: T): T { + if (value instanceof Uint8Array) return value.slice() as T; + if (Array.isArray(value)) return value.map(copied) as T; + if (value && typeof value === "object") + return Object.fromEntries( + Object.entries(value).map(([k, v]) => [k, copied(v)]), + ) as T; + return value; +} + +function storeFor(client: StorageClient, owner: string): DocStore { + return createRpcDocStore((op, callArgs) => + op === "flush" + ? (client.call("flush", {}) as never) + : (client.call(op, { ...copied(callArgs), owner } as never) as never), + ); +} + +/** + * P2.1's shared DocStore contract on `node:sqlite` in the real worker: one + * worker and temp library per case, one owner id per connected client. + */ +async function contract() { + let passed = 0; + let failed = 0; + const harness: DocStoreHarness = { + exclusiveOpen: true, + async createLibrary() { + const libraryDir = mkdtempSync(path.join(tmpdir(), "contract-")); + const client = await StorageClient.start(workerPath(), { + dir: libraryDir, + }); + let clients = 0; + return { + connect: () => storeFor(client, `client-${++clients}`), + async createDoc(docId, schema) { + await client.call("createDoc", { id: docId, schema }); + }, + async dispose() { + await client.shutdown(); + rmSync(libraryDir, { + recursive: true, + force: true, + maxRetries: 10, + retryDelay: 200, + }); + }, + }; + }, + }; + for (const testCase of DOC_STORE_CONTRACT) { + if (testCase.requires && !harness[testCase.requires]) continue; + try { + await testCase.run(harness); + passed += 1; + say(`CASE_OK ${testCase.name}`); + } catch (error) { + failed += 1; + say(`CASE_FAIL ${testCase.name}: ${String(error)}`); + } + } + say(`CONTRACT ${passed} passed, ${failed} failed`); + if (failed > 0) fail(`${failed} contract case(s) failed`); +} + +async function churn() { + const docId = args.doc ?? fail("--doc is required"); + const random = seededRandom(Number(args.seed ?? 1)); + const client = await StorageClient.start(workerPath(), { + dir: dir(), + trace: true, + synchronous: args.synchronous === "OFF" ? "OFF" : "FULL", + fullfsync: args.fullfsync !== "0", + }); + const owner = "churn"; + const loaded = await client.call("load", { docId, owner }); + const doc = new Y.Doc(); + if (loaded.snapshot) Y.applyUpdate(doc, loaded.snapshot); + for (const update of loaded.updates) Y.applyUpdate(doc, update); + let k = + editCount(doc.getText(TEXT).toString()) ?? fail("stored text is broken"); + let ackedSeq = loaded.maxSeq; + const compactEvery = args.target === "compaction"; + + const batcher = new SoakBatcher( + args.dense ? DENSE_TIMING : PRODUCT_TIMING, + async (update, lastEdit) => { + ackedSeq = await client.call("append", { + docId, + owner, + record: { origin: "local", update }, + }); + say(`EDITS ${ackedSeq} ${lastEdit}`); + if (compactEvery) { + // Same task as the encode: no append is in flight (architecture §5.2). + const state = Y.encodeStateAsUpdate(doc); + await client.call("compact", { + docId, + owner, + state, + upToSeq: ackedSeq, + }); + } + }, + ); + let pendingEdit: Uint8Array | null = null; + doc.on("update", (update: Uint8Array) => { + pendingEdit = update; + }); + const quitAfter = args["quit-after-ms"] + ? Number(args["quit-after-ms"]) + : null; + const started = performance.now(); + say(`READY ${k}`); + for (;;) { + // A burst of 1–8 edits 2–10 ms apart, then a 260–400 ms pause. + const burst = 1 + Math.floor(random() * 8); + for (let i = 0; i < burst; i += 1) { + k += 1; + const text = doc.getText(TEXT); + text.insert(text.length, `${k};`); + if (pendingEdit) batcher.push(pendingEdit, k); + pendingEdit = null; + await new Promise((r) => setTimeout(r, 2 + random() * 8)); + } + if (quitAfter !== null && performance.now() - started >= quitAfter) break; + await new Promise((r) => setTimeout(r, 260 + random() * 140)); + } + // T4: the quit flush (architecture §8.2): flush every batch, then shut + // the worker down. + await batcher.flush(); + const outcome = await client.shutdown(); + say(`QUIT ${outcome} ${k} ${ackedSeq}`); +} + +async function migrate() { + say("READY"); + const library = Library.open({ + dir: dir(), + host: createNodeHost(), + openSqlite: openNodeSqlite, + formatVersion: T5_TARGET, + formatSteps: T5_STEPS, + }); + say(`MIGRATED ${library.status.formatVersion} ${library.status.readOnly}`); + library.shutdown(); +} + +async function readonly() { + const client = await StorageClient.start(workerPath(), { dir: dir() }); + say(`STATUS ${JSON.stringify(client.status)}`); + const sidebar = await client.call("sidebar", {}); + say(`SIDEBAR ${sidebar.docs.length}`); + try { + await client.call("createDoc", {}); + say("WRITE accepted"); + } catch (error) { + say(`WRITE refused ${(error as { code?: string }).code}`); + } + say(`SHUTDOWN ${await client.shutdown()}`); +} + +function percentile(sorted: number[], p: number) { + return ( + sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * p))] ?? 0 + ); +} + +async function commitTiming() { + const count = Number(args.count ?? 300); + const client = await StorageClient.start(workerPath(), { + dir: dir(), + fullfsync: args.fullfsync !== "0", + }); + const { id } = await client.call("createDoc", {}); + await client.call("load", { docId: id, owner: "timing" }); + const doc = new Y.Doc(); + const times: number[] = []; + for (let i = 0; i < count; i += 1) { + let update: Uint8Array = new Uint8Array(); + doc.once("update", (u: Uint8Array) => { + update = u; + }); + doc.getText(TEXT).insert(0, "y".repeat(4096)); + const t0 = performance.now(); + await client.call("append", { + docId: id, + owner: "timing", + record: { origin: "local", update }, + }); + times.push(performance.now() - t0); + } + times.sort((a, b) => a - b); + const stats = await client.call("stats", {}); + say( + `TIMING ${JSON.stringify({ + fullfsync: args.fullfsync !== "0", + count, + p50: percentile(times, 0.5), + p95: percentile(times, 0.95), + max: times.at(-1), + pragmas: stats.pragmas, + sqlite: stats.sqliteVersion, + })}`, + ); + await client.shutdown(); +} + +async function startup() { + // performance.now() counts from process start in Node and Electron main. + const spawnAt = performance.now(); + const client = await StorageClient.start(workerPath(), { dir: dir() }); + const readyAt = performance.now(); + const sidebar = await client.call("sidebar", {}); + const rowsAt = performance.now(); + say( + `STARTUP ${JSON.stringify({ + processToSpawnMs: spawnAt, + workerReadyMs: readyAt - spawnAt, + processToReadyMs: readyAt, + openMs: client.timings.openMs, + sidebarCallMs: rowsAt - readyAt, + processToSidebarMs: rowsAt, + spawnToSidebarMs: rowsAt - spawnAt, + docs: sidebar.docs.length, + folders: sidebar.folders.length, + uncleanExit: client.status.uncleanExit, + })}`, + ); + await client.shutdown(); +} + +const MODES: Record Promise> = { + contract, + churn, + migrate, + readonly, + "commit-timing": commitTiming, + startup, +}; + +app.whenReady().then(async () => { + app.dock?.hide(); + if (process.platform === "darwin") app.setActivationPolicy("accessory"); + const run = MODES[args.mode ?? ""] ?? fail(`unknown --mode=${args.mode}`); + await run(); + app.exit(0); +}, fail); diff --git a/desktop/storage-harness/package.json b/desktop/storage-harness/package.json new file mode 100644 index 00000000..ae4a58ab --- /dev/null +++ b/desktop/storage-harness/package.json @@ -0,0 +1,18 @@ +{ + "name": "tinydocy-storage-harness", + "private": true, + "type": "module", + "main": "dist/main.cjs", + "scripts": { + "build": "bun build.ts", + "typecheck": "tsc --noEmit -p ." + }, + "devDependencies": { + "@types/node": "24.19.2", + "electron": "45.3.2", + "typescript": "6.0.3" + }, + "trustedDependencies": [ + "electron" + ] +} diff --git a/desktop/storage-harness/tsconfig.json b/desktop/storage-harness/tsconfig.json new file mode 100644 index 00000000..bacd8dd1 --- /dev/null +++ b/desktop/storage-harness/tsconfig.json @@ -0,0 +1,15 @@ +{ + "compilerOptions": { + "target": "ES2023", + "lib": ["ES2023"], + "module": "Preserve", + "moduleResolution": "bundler", + "moduleDetection": "force", + "types": ["node"], + "strict": true, + "noEmit": true, + "skipLibCheck": true, + "paths": { "@/*": ["../../*"] } + }, + "include": ["main.ts", "gen.ts", "format-steps.ts"] +} diff --git a/desktop/storage/client.ts b/desktop/storage/client.ts new file mode 100644 index 00000000..42129d82 --- /dev/null +++ b/desktop/storage/client.ts @@ -0,0 +1,178 @@ +/** + * Main's handle on the storage worker (desktop architecture §2, §6.3). + * `doc-handlers` (P2.5) forwards validated `doc.*` and `index.*` calls + * through {@link StorageClient.call}; the quit coordinator ends with + * {@link StorageClient.shutdown}. + * + * Bytes in a request are transferred, not copied. If the worker dies, every + * pending call rejects with `worker_restarting`, which the renderer's + * batcher retries (resending an append is harmless). + */ +import { Worker } from "node:worker_threads"; + +import type { StorageErrorEnvelope } from "./engine/errors"; +import type { LibraryStatus } from "./engine/library"; +import type { IndexChange } from "./engine/library-index"; +import { + type StorageMessage, + type StorageOp, + type StorageOps, + type StorageWorkerOptions, + transferablesOf, +} from "./protocol"; + +export class StorageCallError extends Error { + readonly code: StorageErrorEnvelope["code"]; + readonly retryable: boolean; + constructor(envelope: StorageErrorEnvelope) { + super(envelope.message); + this.name = "StorageCallError"; + this.code = envelope.code; + this.retryable = envelope.retryable; + } +} + +type Pending = { resolve(value: unknown): void; reject(error: Error): void }; + +export type StorageClientEvents = { + onIndexChanged?: (rev: number, changes: IndexChange[]) => void; + /** The worker exited without being asked to (crash). */ + onExit?: (code: number) => void; +}; + +export class StorageClient { + readonly status: LibraryStatus; + /** Worker spawn to `ready`, and the open alone inside it. */ + readonly timings: { readyMs: number; openMs: number }; + private readonly worker: Worker; + private readonly pending = new Map(); + private nextId = 1; + private closing = false; + + private constructor( + worker: Worker, + status: LibraryStatus, + timings: { readyMs: number; openMs: number }, + events: StorageClientEvents, + ) { + this.worker = worker; + this.status = status; + this.timings = timings; + worker.on("message", (message: StorageMessage) => { + if (message.type === "reply") { + const pending = this.pending.get(message.id); + if (!pending) return; + this.pending.delete(message.id); + if (message.result.ok) pending.resolve(message.result.value); + else pending.reject(new StorageCallError(message.result.error)); + } else if (message.type === "index_changed") { + events.onIndexChanged?.(message.rev, message.changes); + } + }); + worker.on("exit", (code) => { + this.failPending(); + if (!this.closing) events.onExit?.(code); + }); + } + + /** + * Starts the worker and waits for `ready`. Rejects with the open error + * (`cloud_folder`, `locked_elsewhere`, `corrupt`…) if the library can't + * open; a read-only library still resolves, with `status.readOnly` set. + */ + static start( + workerPath: string, + options: StorageWorkerOptions, + events: StorageClientEvents = {}, + ): Promise { + const started = performance.now(); + const worker = new Worker(workerPath, { workerData: options }); + return new Promise((resolve, reject) => { + const onError = (error: Error) => reject(error); + worker.once("error", onError); + worker.once("message", (message: StorageMessage) => { + worker.off("error", onError); + if (message.type === "ready") { + resolve( + new StorageClient( + worker, + message.status, + { + readyMs: performance.now() - started, + openMs: message.openMs, + }, + events, + ), + ); + } else if (message.type === "open_failed") { + void worker.terminate(); + reject(new StorageCallError(message.error)); + } else { + void worker.terminate(); + reject(new Error(`unexpected first message ${message.type}`)); + } + }); + }); + } + + call( + op: K, + args: StorageOps[K]["args"], + ): Promise { + if (this.closing && op !== "shutdown") + return Promise.reject( + new StorageCallError({ + code: "library_unavailable", + retryable: false, + message: "the library is closing", + }), + ); + const id = this.nextId++; + return new Promise((resolve, reject) => { + this.pending.set(id, { + resolve: resolve as (value: unknown) => void, + reject, + }); + this.worker.postMessage({ id, op, args }, transferablesOf(args)); + }); + } + + /** + * The quit flush's last step (architecture §8.2): every call already sent + * commits first, then the worker checkpoints, clears `unclean_exit` and + * closes. After `timeoutMs` it is terminated; WAL keeps every committed + * row, and the next open runs `quick_check`. + */ + async shutdown(timeoutMs = 2000): Promise<"clean" | "terminated"> { + if (this.closing) return "clean"; + this.closing = true; + const exited = new Promise((resolve) => + this.worker.once("exit", () => resolve()), + ); + let timer: ReturnType | undefined; + const timeout = new Promise<"terminated">((resolve) => { + timer = setTimeout(() => resolve("terminated"), timeoutMs); + }); + const clean = this.call("shutdown", {}) + .then(() => exited) + .then(() => "clean" as const); + const outcome = await Promise.race([clean, timeout]).catch( + () => "terminated" as const, + ); + clearTimeout(timer); + if (outcome === "terminated") await this.worker.terminate(); + return outcome; + } + + private failPending() { + for (const pending of this.pending.values()) + pending.reject( + new StorageCallError({ + code: "worker_restarting", + retryable: true, + message: "the storage worker stopped", + }), + ); + this.pending.clear(); + } +} diff --git a/desktop/storage/drivers/node-sqlite.ts b/desktop/storage/drivers/node-sqlite.ts new file mode 100644 index 00000000..a3375a6c --- /dev/null +++ b/desktop/storage/drivers/node-sqlite.ts @@ -0,0 +1,64 @@ +/** + * `SqliteDriver` over `node:sqlite`, for the Electron storage worker + * (D-A1). `node:sqlite` returns `undefined` for a missing row and plain + * numbers by default, which is what the driver contract wants; BLOBs come + * back as fresh `Uint8Array`s. Loaded with `process.getBuiltinModule`, so a + * build of Electron without it fails here with a clear error (D-A12). + */ +import type { DatabaseSync } from "node:sqlite"; + +import type { + OpenSqlite, + SqliteDriver, + SqliteStatement, + SqlRow, + SqlValue, +} from "../engine/driver"; + +type NodeSqlite = typeof import("node:sqlite"); + +function loadNodeSqlite(): NodeSqlite { + const sqlite = process.getBuiltinModule("node:sqlite") as + | NodeSqlite + | undefined; + if (!sqlite) throw new Error("node:sqlite is not built into this runtime"); + return sqlite; +} + +function wrap(db: DatabaseSync): SqliteDriver { + const cache = new Map(); + return { + exec: (sql) => db.exec(sql), + prepare(sql) { + const cached = cache.get(sql); + if (cached) return cached; + const statement = db.prepare(sql); + const wrapped: SqliteStatement = { + run: (...params: SqlValue[]) => { + const result = statement.run(...params); + return { + changes: Number(result.changes), + lastInsertRowid: Number(result.lastInsertRowid), + }; + }, + get: (...params: SqlValue[]) => + statement.get(...params) as SqlRow | undefined, + all: (...params: SqlValue[]) => statement.all(...params) as SqlRow[], + }; + cache.set(sql, wrapped); + return wrapped; + }, + close: () => db.close(), + }; +} + +export const openNodeSqlite: OpenSqlite = (path, { readOnly }) => { + const { DatabaseSync } = loadNodeSqlite(); + return wrap( + new DatabaseSync(path, { + readOnly, + // The engine turns them on itself, the same on both drivers. + enableForeignKeyConstraints: false, + }), + ); +}; diff --git a/desktop/storage/engine/cloud-folder.ts b/desktop/storage/engine/cloud-folder.ts new file mode 100644 index 00000000..a87b1387 --- /dev/null +++ b/desktop/storage/engine/cloud-folder.ts @@ -0,0 +1,89 @@ +/** + * Refuses a library inside a cloud-synced folder (plan Appendix A, P2.6; + * architecture §5.4 `open.ts`). A sync client that uploads `library.sqlite` + * without its `-wal` file, or restores an older copy under a live + * connection, corrupts the library. `userData` never lives in one by + * default; this catches a moved home folder, OneDrive Known Folder Move and + * a `TINYDOCY_USER_DATA` override. + */ +import type { StorageHost } from "./host"; + +export type CloudProvider = + | "icloud" + | "onedrive" + | "dropbox" + | "google_drive" + | "box" + | "other"; + +// Folder names sync clients create. Compared case-insensitively against +// every path segment. +const SEGMENTS: ReadonlyArray<[RegExp, CloudProvider]> = [ + [/^mobile documents$/i, "icloud"], // ~/Library/Mobile Documents (iCloud Drive) + [/^icloud ?drive/i, "icloud"], // Windows iCloud for Windows + [/^onedrive( |$|-)/i, "onedrive"], // OneDrive, OneDrive - Contoso + [/^dropbox( |$|\()/i, "dropbox"], // Dropbox, Dropbox (Personal) + [/^google ?drive/i, "google_drive"], + [/^my drive$/i, "google_drive"], + [/^box( |$)/i, "box"], +]; + +// macOS File Provider puts every modern sync client under +// ~/Library/CloudStorage/-. +const CLOUD_STORAGE: ReadonlyArray<[RegExp, CloudProvider]> = [ + [/^onedrive/i, "onedrive"], + [/^dropbox/i, "dropbox"], + [/^googledrive/i, "google_drive"], + [/^box/i, "box"], + [/^icloud/i, "icloud"], +]; + +const ONEDRIVE_ENV = ["OneDrive", "OneDriveConsumer", "OneDriveCommercial"]; + +function segmentsOf(path: string): string[] { + return path.split(/[\\/]+/).filter(Boolean); +} + +function isUnder(path: string, root: string, caseInsensitive: boolean) { + const a = segmentsOf(path); + const b = segmentsOf(root); + if (b.length === 0 || b.length > a.length) return false; + return b.every((part, i) => + caseInsensitive + ? part.toLowerCase() === a[i]?.toLowerCase() + : part === a[i], + ); +} + +/** The cloud provider syncing `dir`, or null. Symlinks are resolved first. */ +export function cloudFolderOf( + dir: string, + host: Pick, +): CloudProvider | null { + const resolved = host.realpath(dir); + const caseInsensitive = host.platform !== "linux"; + // The home folder's own segments are a user name, not a sync folder: a + // person called "box" or "dropbox" must still be able to start the app. + const home = host.homeDir ? host.realpath(host.homeDir) : ""; + const skip = + home && isUnder(resolved, home, caseInsensitive) + ? segmentsOf(home).length + : 0; + for (const name of ONEDRIVE_ENV) { + const root = host.env[name]; + if (root && isUnder(resolved, root, caseInsensitive)) return "onedrive"; + } + const parts = segmentsOf(resolved); + for (const [i, part] of parts.entries()) { + if (i < skip) continue; + if (part.toLowerCase() === "cloudstorage") { + const next = parts[i + 1] ?? ""; + for (const [pattern, provider] of CLOUD_STORAGE) + if (pattern.test(next)) return provider; + return "other"; + } + for (const [pattern, provider] of SEGMENTS) + if (pattern.test(part)) return provider; + } + return null; +} diff --git a/desktop/storage/engine/content.ts b/desktop/storage/engine/content.ts new file mode 100644 index 00000000..b45ed2b5 --- /dev/null +++ b/desktop/storage/engine/content.ts @@ -0,0 +1,209 @@ +/** + * Document content: `load`, `append`, `compact` and `stateOf` (architecture + * §5.2, §5.4 `content.ts`). The renderer owns the Y.Doc and compacts it + * (D-A3); this module only stores bytes. It never parses an update, except + * in {@link stateOf}, which merges stored rows for export and restore. + * + * Rule one: a Yjs update is never dropped once acknowledged. `append` + * resolves only after COMMIT, and `compact` refuses an `upToSeq` that could + * cover a row the renderer has not seen. + */ +import * as Y from "yjs"; + +import type { SqliteDriver } from "./driver"; +import { StorageError } from "./errors"; +import { bumpRev, scalar, transaction } from "./sql"; + +/** The stored `updates.origin` values: `UPDATE_ORIGINS` in `lib/platform/doc-store.ts`. */ +export const STORED_ORIGINS = [ + "local", + "migration", + "remote", + "restore", +] as const; +export type StoredOrigin = (typeof STORED_ORIGINS)[number]; + +export type LoadedContent = { + snapshot: Uint8Array | null; + updates: Uint8Array[]; + maxSeq: number; + schema: number; +}; + +export type AppendInput = { + origin: StoredOrigin; + update: Uint8Array; + title?: string; + snippet?: string; + schemaTo?: number; +}; + +/** Title and snippet caps (architecture §7 `str(200)`; details spec §6.3). */ +export const MAX_TITLE_LENGTH = 200; +export const MAX_SNIPPET_LENGTH = 300; + +function docExists(db: SqliteDriver, docId: string): boolean { + return scalar(db, "SELECT 1 FROM docs WHERE id = ?", docId) !== undefined; +} + +function snapshotUpto(db: SqliteDriver, docId: string): number { + const value = scalar( + db, + "SELECT upto_seq FROM snapshots WHERE doc_id = ?", + docId, + ); + return typeof value === "number" ? value : 0; +} + +/** + * The highest seq this document has: of its rows, or of the rows its + * snapshot replaced. A compaction can't claim to cover more than this. + */ +function lastDocSeq(db: SqliteDriver, docId: string): number { + const value = scalar( + db, + "SELECT MAX(seq) FROM updates WHERE doc_id = ?", + docId, + ); + return Math.max( + typeof value === "number" ? value : 0, + snapshotUpto(db, docId), + ); +} + +export function load(db: SqliteDriver, docId: string): LoadedContent { + const doc = db.prepare("SELECT schema FROM docs WHERE id = ?").get(docId); + if (!doc) throw new StorageError("not_found", "no such document"); + const snap = db + .prepare("SELECT data, upto_seq FROM snapshots WHERE doc_id = ?") + .get(docId); + const upto = typeof snap?.upto_seq === "number" ? snap.upto_seq : 0; + const rows = db + .prepare( + "SELECT seq, data FROM updates WHERE doc_id = ? AND seq > ? ORDER BY seq", + ) + .all(docId, upto); + const last = rows.at(-1)?.seq; + return { + snapshot: snap ? (snap.data as Uint8Array) : null, + updates: rows.map((row) => row.data as Uint8Array), + maxSeq: typeof last === "number" ? last : upto, + schema: doc.schema as number, + }; +} + +function validateAppend(input: AppendInput) { + if (!STORED_ORIGINS.includes(input.origin)) + throw new StorageError("invalid_argument", "unknown origin"); + if (!(input.update instanceof Uint8Array) || input.update.byteLength === 0) + throw new StorageError("invalid_argument", "empty update"); + if ( + input.schemaTo !== undefined && + (!Number.isInteger(input.schemaTo) || input.schemaTo < 0) + ) + throw new StorageError("invalid_argument", "bad schemaTo"); +} + +/** + * One row, plus the document's list metadata, in one transaction. Returns + * the row's seq once committed. + */ +export function append( + db: SqliteDriver, + docId: string, + input: AppendInput, + now: number, +): number { + validateAppend(input); + return transaction(db, () => { + const updated = db + .prepare( + `UPDATE docs SET + modified_at = ?, + size_bytes = size_bytes + ?, + title = COALESCE(?, title), + snippet = COALESCE(?, snippet), + schema = COALESCE(?, schema) + WHERE id = ?`, + ) + .run( + now, + input.update.byteLength, + input.title === undefined + ? null + : input.title.slice(0, MAX_TITLE_LENGTH), + input.snippet === undefined + ? null + : input.snippet.slice(0, MAX_SNIPPET_LENGTH), + input.schemaTo ?? null, + docId, + ); + if (updated.changes === 0) + throw new StorageError("not_found", "no such document"); + // Title, snippet and modified time are on the sidebar (architecture §8.1). + bumpRev(db); + return db + .prepare( + "INSERT INTO updates (doc_id, data, origin, created_at) VALUES (?, ?, ?, ?)", + ) + .run(docId, input.update, input.origin, now).lastInsertRowid; + }); +} + +/** + * Stores `state` as the snapshot and deletes rows `seq ≤ upToSeq`, in one + * transaction (D-A3). A stale compaction (`upToSeq` below the stored + * snapshot's) changes nothing. An `upToSeq` past the document's last row + * is refused: it could claim rows the renderer has never seen. + */ +export function compact( + db: SqliteDriver, + docId: string, + state: Uint8Array, + upToSeq: number, +): void { + if (!Number.isInteger(upToSeq) || upToSeq < 0) + throw new StorageError("invalid_argument", "bad upToSeq"); + if (!(state instanceof Uint8Array) || state.byteLength === 0) + throw new StorageError("invalid_argument", "empty state"); + transaction(db, () => { + if (!docExists(db, docId)) + throw new StorageError("not_found", "no such document"); + if (upToSeq > lastDocSeq(db, docId)) + throw new StorageError( + "invalid_argument", + "upToSeq is past the document's rows", + ); + if (upToSeq < snapshotUpto(db, docId)) return; + db.prepare( + `INSERT INTO snapshots (doc_id, data, upto_seq) VALUES (?, ?, ?) + ON CONFLICT (doc_id) DO UPDATE SET data = excluded.data, upto_seq = excluded.upto_seq`, + ).run(docId, state, upToSeq); + db.prepare("DELETE FROM updates WHERE doc_id = ? AND seq <= ?").run( + docId, + upToSeq, + ); + db.prepare( + `UPDATE docs SET size_bytes = ? + COALESCE( + (SELECT SUM(LENGTH(data)) FROM updates WHERE doc_id = ?), 0) + WHERE id = ?`, + ).run(state.byteLength, docId, docId); + }); +} + +/** + * The document's whole state as one update (for `.tinydoc`, restore and + * the daily-copy reader). Merges without building a Y.Doc. + */ +export function stateOf(content: LoadedContent): Uint8Array { + const parts = content.snapshot + ? [content.snapshot, ...content.updates] + : content.updates; + if (parts.length === 0) return Y.encodeStateAsUpdate(new Y.Doc()); + return Y.mergeUpdates(parts); +} + +/** Rows waiting for compaction, for diagnostics and T8. */ +export function pendingRows(db: SqliteDriver): number { + return Number(scalar(db, "SELECT COUNT(*) FROM updates") ?? 0); +} diff --git a/desktop/storage/engine/daily-copy.ts b/desktop/storage/engine/daily-copy.ts new file mode 100644 index 00000000..884a4a70 --- /dev/null +++ b/desktop/storage/engine/daily-copy.ts @@ -0,0 +1,69 @@ +/** + * Daily copies (D-A6; architecture §5.4 `daily-copy.ts`): once a local day, + * on the first idle moment, `VACUUM INTO daily/library-.sqlite`, + * keeping the newest 7. They are the Local release's restore points + * ("Restore from a daily snapshot"), and its protection against a corrupt + * library. + * + * Each copy is written to `.partial` and renamed, so a kill mid-copy + * never leaves a half file under a real name. Retention is by count, so a + * clock jump can't delete good copies early. + */ +import type { SqliteDriver } from "./driver"; +import type { StorageHost } from "./host"; +import { readMeta, writeMeta } from "./sql"; + +export const DAILY_DIR = "daily"; +export const DAILY_KEEP = 7; +const DAILY = /^library-\d{4}-\d{2}-\d{2}\.sqlite$/; + +/** `YYYY-MM-DD` in local time: "today" is the person's day, not UTC's. */ +export function localDate(ms: number): string { + const date = new Date(ms); + const pad = (n: number) => String(n).padStart(2, "0"); + return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`; +} + +export function dailyCopyName(date: string): string { + return `library-${date}.sqlite`; +} + +export function listDailyCopies(host: StorageHost, dir: string): string[] { + return host + .list(host.join(dir, DAILY_DIR)) + .filter((file) => DAILY.test(file)) + .sort(); +} + +export function isDailyCopyDue(db: SqliteDriver, now: number): boolean { + return readMeta(db, "last_daily_copy") !== localDate(now); +} + +/** + * Writes today's copy if there isn't one yet. Returns the copy's file name, + * or null when it was already taken today. + */ +export function takeDailyCopy( + db: SqliteDriver, + host: StorageHost, + dir: string, + now: number, +): string | null { + if (!isDailyCopyDue(db, now)) return null; + const date = localDate(now); + const folder = host.join(dir, DAILY_DIR); + host.mkdirp(folder); + for (const file of host.list(folder)) + if (file.endsWith(".partial")) host.remove(host.join(folder, file)); + const name = dailyCopyName(date); + const target = host.join(folder, name); + const partial = `${target}.partial`; + db.prepare("VACUUM INTO ?").run(partial); + if (host.exists(target)) host.remove(target); + host.rename(partial, target); + writeMeta(db, "last_daily_copy", date); + const copies = listDailyCopies(host, dir); + for (const old of copies.slice(0, -DAILY_KEEP)) + host.remove(host.join(folder, old)); + return name; +} diff --git a/desktop/storage/engine/driver.ts b/desktop/storage/engine/driver.ts new file mode 100644 index 00000000..7f28044d --- /dev/null +++ b/desktop/storage/engine/driver.ts @@ -0,0 +1,96 @@ +/** + * The engine's only view of SQLite (desktop architecture §3, §12 "Mobile"). + * Two drivers implement it: `node:sqlite` in the Electron storage worker + * (`desktop/storage/drivers/node-sqlite.ts`) and `bun:sqlite` for unit tests + * and the dev storage host (`desktop/dev/bun-sqlite-driver.ts`). + * + * Drivers normalize what differs between the two runtimes, so the engine + * behaves the same on both: + * - a missing row is `undefined` (Bun returns `null`); + * - integers are numbers (no `bigint`); + * - a BLOB is a `Uint8Array` the caller owns; + * - parameters are positional `?` only; + * - a failure carries the SQLite extended result code (see + * {@link sqliteResultCode}). + */ +import { StorageError, type StorageErrorCode } from "./errors"; + +export type SqlValue = string | number | null | Uint8Array; +export type SqlRow = Record; + +export interface SqliteStatement { + run(...params: SqlValue[]): { changes: number; lastInsertRowid: number }; + get(...params: SqlValue[]): SqlRow | undefined; + all(...params: SqlValue[]): SqlRow[]; +} + +export interface SqliteDriver { + exec(sql: string): void; + prepare(sql: string): SqliteStatement; + close(): void; +} + +export type OpenSqlite = ( + path: string, + options: { readOnly: boolean }, +) => SqliteDriver; + +/** + * The SQLite extended result code of a driver error, or null when the error + * did not come from SQLite. Bun puts it in `errno`, Node in `errcode`. + */ +export function sqliteResultCode(error: unknown): number | null { + if (typeof error !== "object" || error === null) return null; + const { errno, errcode } = error as { errno?: unknown; errcode?: unknown }; + if (typeof errcode === "number") return errcode; + // Bun's SQLiteError: its constructor reports as Error, its name doesn't. + if (typeof errno === "number" && (error as Error).name === "SQLiteError") + return errno; + return null; +} + +// Primary result codes (https://sqlite.org/rescode.html). +const SQLITE_PERM = 3; +const SQLITE_BUSY = 5; +const SQLITE_LOCKED = 6; +const SQLITE_READONLY = 8; +const SQLITE_IOERR = 10; +const SQLITE_CORRUPT = 11; +const SQLITE_FULL = 13; +const SQLITE_CANTOPEN = 14; +const SQLITE_CONSTRAINT = 19; +const SQLITE_NOTADB = 26; + +/** Maps a driver failure to the storage error a caller sees. */ +export function storageErrorFrom(error: unknown): StorageError { + if (error instanceof StorageError) return error; + const code = sqliteResultCode(error); + const message = error instanceof Error ? error.message : String(error); + let mapped: StorageErrorCode = "io_error"; + switch (code === null ? null : code & 0xff) { + case SQLITE_FULL: + mapped = "disk_full"; + break; + case SQLITE_CORRUPT: + case SQLITE_NOTADB: + mapped = "corrupt"; + break; + case SQLITE_BUSY: + case SQLITE_LOCKED: + mapped = "locked_elsewhere"; + break; + case SQLITE_READONLY: + case SQLITE_PERM: + mapped = "library_read_only"; + break; + case SQLITE_CONSTRAINT: + // A duplicate tag name or link key: the caller's input, not the disk. + mapped = "invalid_argument"; + break; + case SQLITE_CANTOPEN: + case SQLITE_IOERR: + mapped = "io_error"; + break; + } + return new StorageError(mapped, message); +} diff --git a/desktop/storage/engine/errors.ts b/desktop/storage/engine/errors.ts new file mode 100644 index 00000000..3304884a --- /dev/null +++ b/desktop/storage/engine/errors.ts @@ -0,0 +1,66 @@ +/** + * Storage error codes (desktop architecture §9). The engine rejects with a + * {@link StorageError}; the worker sends `{ code, retryable }` across, never + * a thrown object. This list must stay a superset of `DOC_STORE_ERROR_CODES` + * in `lib/platform/doc-store.ts` minus the web library's `quota_exceeded` + * (a unit test compares them): the engine cannot import `lib/`. + */ +export const STORAGE_ERROR_CODES = [ + "invalid_argument", + "forbidden", + "not_found", + "already_open", + "document_open", + "library_read_only", + "library_too_new", + "migration_failed", + "disk_full", + "io_error", + "corrupt", + "locked_elsewhere", + "cloud_folder", + "worker_restarting", + "library_unavailable", + "import_too_large", + "unknown_schema", +] as const; + +export type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[number]; + +const RETRYABLE: ReadonlySet = new Set([ + "disk_full", + "io_error", + "worker_restarting", + "library_unavailable", +]); + +export class StorageError extends Error { + readonly code: StorageErrorCode; + readonly retryable: boolean; + + constructor(code: StorageErrorCode, message: string = code) { + super(message); + this.name = "StorageError"; + this.code = code; + this.retryable = RETRYABLE.has(code); + } +} + +/** What crosses the worker boundary in place of a thrown error. */ +export type StorageErrorEnvelope = { + code: StorageErrorCode; + retryable: boolean; + message: string; +}; + +export function toEnvelope(error: unknown): StorageErrorEnvelope { + const storage = + error instanceof StorageError + ? error + : new StorageError("io_error", String(error)); + return { + code: storage.code, + retryable: storage.retryable, + message: storage.message, + }; +} diff --git a/desktop/storage/engine/host.ts b/desktop/storage/engine/host.ts new file mode 100644 index 00000000..4269ad49 --- /dev/null +++ b/desktop/storage/engine/host.ts @@ -0,0 +1,32 @@ +/** + * What the engine needs from the operating system, injected so the engine + * imports no `node:*` or `bun:*` module (desktop architecture §3.3). The + * worker passes `createNodeHost()` (`desktop/storage/node-host.ts`); tests + * pass the same host with a fake clock, or a fake pid check. + */ +export interface StorageHost { + /** `process.platform`. */ + readonly platform: string; + /** This process's pid, written to `library.lock`. */ + readonly pid: number; + /** The home folder, used only to recognise cloud-synced folders. */ + readonly homeDir: string; + /** Environment variables (OneDrive sets `OneDrive*` on Windows). */ + readonly env: Readonly>; + /** Milliseconds since the epoch. */ + now(): number; + join(...parts: string[]): string; + /** Resolves symlinks; returns the path unchanged when it doesn't exist. */ + realpath(path: string): string; + mkdirp(path: string): void; + exists(path: string): boolean; + /** File names in `dir`, or `[]` when it doesn't exist. */ + list(dir: string): string[]; + remove(path: string): void; + rename(from: string, to: string): void; + readText(path: string): string | null; + /** Creates `path` with `text`; false when it already exists. */ + createExclusive(path: string, text: string): boolean; + /** Whether a process with this pid is running. */ + isPidAlive(pid: number): boolean; +} diff --git a/desktop/storage/engine/library-index.ts b/desktop/storage/engine/library-index.ts new file mode 100644 index 00000000..e0946e87 --- /dev/null +++ b/desktop/storage/engine/library-index.ts @@ -0,0 +1,398 @@ +/** + * The library's metadata: documents, folders and tags (architecture §5.4 + * `index.ts`; named `library-index.ts` so it isn't taken for a barrel). + * `IpcDocumentIndex` (P2.3's `DocumentIndex` port) sits on top of these + * operations; the row shapes here are the storage side and stay neutral. + * + * Every metadata write goes through this module (seam S10) and bumps + * `meta.rev` in the same transaction, so the change feed can say "changed + * since rev N". Inserting a document mints its `lineage` and `link_key` + * (seam S16): never lazily, so two synced devices can't mint different keys. + */ +import type { SqliteDriver, SqlRow } from "./driver"; +import { StorageError } from "./errors"; +import { bumpRev, randomHex32, readRev, scalar, transaction } from "./sql"; + +export type DocKind = "doc" | "template"; + +export type CreateDocInput = { + /** + * Minted (a UUID) when omitted. Main's IPC guard only lets UUIDs through; + * the engine accepts any {@link SAFE_ID}, which tests and imports use. + */ + id?: string; + /** `docs.schema`: `DOC_SCHEMA` for a new document, the file's on import. */ + schema?: number; + title?: string; + folderId?: string | null; + sortKey?: string; + kind?: DocKind; + /** Kept only by a backup restore (S8c); everything else gets a new one. */ + lineage?: string; + /** Kept only by a backup zip or `library.json` restore (S8c). */ + linkKey?: string; +}; + +export type CreatedDoc = { + id: string; + lineage: string; + linkKey: string; + rev: number; +}; + +export type SidebarFolder = { + id: string; + parentId: string | null; + name: string; + sortKey: string; + sort: string | null; + view: string | null; + group: string | null; +}; + +export type SidebarDoc = { + id: string; + title: string; + folderId: string | null; + sortKey: string; + pinKey: string | null; + pinned: boolean; + createdAt: number; + modifiedAt: number; + openedAt: number | null; + sizeBytes: number; + snippet: string; + kind: DocKind; + tagIds: string[]; +}; + +export type SidebarTag = { id: string; name: string; color: string | null }; + +/** + * One changed row, for the change feed (architecture §7 `index.changed`): + * a window patches that row instead of re-reading the whole library. + */ +export type IndexChange = { kind: "doc" | "folder" | "tag"; id: string }; + +/** Everything the files sidebar and lists paint from (P2.7a/b). */ +export type SidebarSnapshot = { + rev: number; + folders: SidebarFolder[]; + docs: SidebarDoc[]; + tags: SidebarTag[]; +}; + +/** Trash is emptied after this long (details spec §9). */ +export const TRASH_RETENTION_MS = 30 * 24 * 60 * 60 * 1000; + +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; +/** Ids that are safe in SQL, file names and logs. */ +export const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/; +const HEX32 = /^[0-9a-f]{32}$/; +export const MAX_NAME_LENGTH = 200; + +function requireId(id: string, what: string) { + if (!SAFE_ID.test(id)) + throw new StorageError("invalid_argument", `bad ${what}`); +} + +function requireUuid(id: string, what: string) { + if (!UUID.test(id)) throw new StorageError("invalid_argument", `bad ${what}`); +} + +function cleanName(name: string): string { + return name.trim().slice(0, MAX_NAME_LENGTH); +} + +/** Wraps a metadata write: one transaction, `rev` bumped, new rev returned. */ +function indexWrite(db: SqliteDriver, body: () => void): number { + return transaction(db, () => { + body(); + return bumpRev(db); + }); +} + +function requireChanged(changes: number, what: string) { + if (changes === 0) throw new StorageError("not_found", `no such ${what}`); +} + +export function createDoc( + db: SqliteDriver, + input: CreateDocInput, + now: number, +): CreatedDoc { + const id = input.id ?? crypto.randomUUID(); + requireId(id, "document id"); + const lineage = input.lineage ?? crypto.randomUUID(); + requireUuid(lineage, "lineage"); + const schema = input.schema ?? 0; + if (!Number.isInteger(schema) || schema < 0) + throw new StorageError("invalid_argument", "bad schema"); + const linkKey = input.linkKey ?? randomHex32(); + if (!HEX32.test(linkKey)) + throw new StorageError("invalid_argument", "bad link key"); + if (input.folderId) requireId(input.folderId, "folder id"); + const kind = input.kind ?? "doc"; + if (kind !== "doc" && kind !== "template") + throw new StorageError("invalid_argument", "bad kind"); + const rev = indexWrite(db, () => { + db.prepare( + `INSERT INTO docs (id, title, folder_id, sort_key, created_at, modified_at, + lineage, link_key, kind, schema) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, + ).run( + id, + cleanName(input.title ?? ""), + input.folderId ?? null, + input.sortKey ?? "", + now, + now, + lineage, + linkKey, + kind, + schema, + ); + }); + return { id, lineage, linkKey, rev }; +} + +export function createFolder( + db: SqliteDriver, + input: { + id?: string; + name: string; + parentId?: string | null; + sortKey?: string; + }, + now: number, +): { id: string; rev: number } { + const id = input.id ?? crypto.randomUUID(); + requireId(id, "folder id"); + if (input.parentId) requireId(input.parentId, "parent id"); + const rev = indexWrite(db, () => { + db.prepare( + `INSERT INTO folders (id, parent_id, name, sort_key, created_at, modified_at) + VALUES (?, ?, ?, ?, ?, ?)`, + ).run( + id, + input.parentId ?? null, + cleanName(input.name), + input.sortKey ?? "", + now, + now, + ); + }); + return { id, rev }; +} + +export function renameDoc(db: SqliteDriver, id: string, title: string): number { + return indexWrite(db, () => { + requireChanged( + db + .prepare("UPDATE docs SET title = ? WHERE id = ?") + .run(cleanName(title), id).changes, + "document", + ); + }); +} + +export function moveDoc( + db: SqliteDriver, + id: string, + folderId: string | null, + sortKey: string, +): number { + if (folderId) requireId(folderId, "folder id"); + return indexWrite(db, () => { + requireChanged( + db + .prepare("UPDATE docs SET folder_id = ?, sort_key = ? WHERE id = ?") + .run(folderId, sortKey, id).changes, + "document", + ); + }); +} + +export function markOpened(db: SqliteDriver, id: string, now: number): number { + return indexWrite(db, () => { + requireChanged( + db.prepare("UPDATE docs SET opened_at = ? WHERE id = ?").run(now, id) + .changes, + "document", + ); + }); +} + +export function trashDoc( + db: SqliteDriver, + id: string, + now: number, + group: string | null = null, +): number { + return indexWrite(db, () => { + requireChanged( + db + .prepare( + `UPDATE docs SET trashed_at = ?, trash_group = ?, trashed_from = folder_id + WHERE id = ? AND trashed_at IS NULL`, + ) + .run(now, group, id).changes, + "document", + ); + }); +} + +export function restoreDoc(db: SqliteDriver, id: string): number { + return indexWrite(db, () => { + requireChanged( + db + .prepare( + `UPDATE docs SET trashed_at = NULL, trash_group = NULL, + folder_id = CASE WHEN trashed_from IS NULL + OR EXISTS (SELECT 1 FROM folders WHERE id = docs.trashed_from AND trashed_at IS NULL) + THEN trashed_from ELSE NULL END, + trashed_from = NULL + WHERE id = ? AND trashed_at IS NOT NULL`, + ) + .run(id).changes, + "trashed document", + ); + }); +} + +/** + * Deletes a document and everything that cascades from it: rows, snapshot, + * tags, view and import source. The caller (`Library`) refuses a document + * that is open (`document_open`). + */ +export function purgeDoc(db: SqliteDriver, id: string): number { + return indexWrite(db, () => { + requireChanged( + db.prepare("DELETE FROM docs WHERE id = ?").run(id).changes, + "document", + ); + }); +} + +/** Ids of documents in Trash for longer than {@link TRASH_RETENTION_MS}. */ +export function expiredTrash(db: SqliteDriver, now: number): string[] { + return db + .prepare( + "SELECT id FROM docs WHERE trashed_at IS NOT NULL AND trashed_at <= ?", + ) + .all(now - TRASH_RETENTION_MS) + .map((row) => row.id as string); +} + +export function createTag( + db: SqliteDriver, + name: string, + color: string | null = null, +): { id: string; rev: number } { + const clean = cleanName(name); + if (!clean) throw new StorageError("invalid_argument", "empty tag name"); + const id = crypto.randomUUID(); + const rev = indexWrite(db, () => { + db.prepare("INSERT INTO tags (id, name, color) VALUES (?, ?, ?)").run( + id, + clean, + color, + ); + }); + return { id, rev }; +} + +export function setDocTags( + db: SqliteDriver, + docId: string, + tagIds: readonly string[], +): number { + for (const tagId of tagIds) requireId(tagId, "tag id"); + return indexWrite(db, () => { + if (scalar(db, "SELECT 1 FROM docs WHERE id = ?", docId) === undefined) + throw new StorageError("not_found", "no such document"); + db.prepare("DELETE FROM doc_tags WHERE doc_id = ?").run(docId); + const insert = db.prepare( + "INSERT INTO doc_tags (doc_id, tag_id) VALUES (?, ?)", + ); + for (const tagId of new Set(tagIds)) insert.run(docId, tagId); + }); +} + +const nullableString = (value: SqlRow[string]) => + typeof value === "string" ? value : null; +const nullableNumber = (value: SqlRow[string]) => + typeof value === "number" ? value : null; + +/** + * The files sidebar's whole picture in one read: every live (untrashed) + * folder and document, and the tags. Reads no BLOB column. P2.6's exit + * budget (architecture §10): populated within 600 ms on an M1 and 1.0 s on + * Windows with 1,000 documents. + */ +export function sidebarSnapshot(db: SqliteDriver): SidebarSnapshot { + const tagsByDoc = new Map(); + for (const row of db + .prepare( + `SELECT doc_tags.doc_id, doc_tags.tag_id FROM doc_tags + JOIN docs ON docs.id = doc_tags.doc_id WHERE docs.trashed_at IS NULL`, + ) + .all()) { + const docId = row.doc_id as string; + const list = tagsByDoc.get(docId); + if (list) list.push(row.tag_id as string); + else tagsByDoc.set(docId, [row.tag_id as string]); + } + const docs = db + .prepare( + `SELECT id, title, folder_id, sort_key, pin_key, pinned, created_at, + modified_at, opened_at, size_bytes, snippet, kind + FROM docs WHERE trashed_at IS NULL`, + ) + .all() + .map( + (row): SidebarDoc => ({ + id: row.id as string, + title: row.title as string, + folderId: nullableString(row.folder_id), + sortKey: row.sort_key as string, + pinKey: nullableString(row.pin_key), + pinned: row.pinned === 1, + createdAt: row.created_at as number, + modifiedAt: row.modified_at as number, + openedAt: nullableNumber(row.opened_at), + sizeBytes: row.size_bytes as number, + snippet: row.snippet as string, + kind: row.kind as DocKind, + tagIds: tagsByDoc.get(row.id as string) ?? [], + }), + ); + const folders = db + .prepare( + `SELECT id, parent_id, name, sort_key, sort, view, "group" + FROM folders WHERE trashed_at IS NULL`, + ) + .all() + .map( + (row): SidebarFolder => ({ + id: row.id as string, + parentId: nullableString(row.parent_id), + name: row.name as string, + sortKey: row.sort_key as string, + sort: nullableString(row.sort), + view: nullableString(row.view), + group: nullableString(row.group), + }), + ); + const tags = db + .prepare("SELECT id, name, color FROM tags") + .all() + .map( + (row): SidebarTag => ({ + id: row.id as string, + name: row.name as string, + color: nullableString(row.color), + }), + ); + return { rev: readRev(db), folders, docs, tags }; +} diff --git a/desktop/storage/engine/library.ts b/desktop/storage/engine/library.ts new file mode 100644 index 00000000..e36025d9 --- /dev/null +++ b/desktop/storage/engine/library.ts @@ -0,0 +1,578 @@ +/** + * One open library: the storage worker's whole state (architecture §5.4). + * The worker owns exactly one `Library`; tests and the dev storage host + * build one directly over `bun:sqlite`. + * + * **Open order** (architecture §5.4 `open.ts`, D-A6). Nothing that writes + * runs before the `format_version` check, so a library made by a newer app + * is never touched (soak T6): + * 1. refuse a cloud-synced folder (`cloud_folder`); + * 2. take `library.lock` (`locked_elsewhere`); + * 3. pragmas: WAL, `synchronous=FULL`, foreign keys, and on macOS + * `fullfsync` and `checkpoint_fullfsync`; + * 4. create the schema if the file is new (lineage and `library_id` from day + * one); + * 5. `format_version` newer than the app → reopen read-only, + * `library_too_new`; + * 6. `unclean_exit` still set → `quick_check`; a failure is read-only, + * `corrupt`; + * 7. older → pre-migration copy, then the format steps (`migration_failed` + * is read-only); + * 8. set `unclean_exit`; {@link Library.shutdown} clears it. + * + * **Registry** (architecture §5.2, §6.2): a document is open in at most one + * window (D-A3). `load` claims it for an owner (a window id) and rejects + * another owner with `already_open`; appends and compactions from any + * other owner are `forbidden` (and {@link Library.claim} re-registers holds + * after a worker restart); main's own content writes (purge, and P2.8's + * import-into and restore) refuse an open document with `document_open`. + */ +import { cloudFolderOf } from "./cloud-folder"; +import { + type AppendInput, + append, + compact, + type LoadedContent, + load, + pendingRows, + stateOf, +} from "./content"; +import { + DAILY_DIR, + dailyCopyName, + isDailyCopyDue, + listDailyCopies, + localDate, + takeDailyCopy, +} from "./daily-copy"; +import type { OpenSqlite, SqliteDriver } from "./driver"; +import { storageErrorFrom } from "./driver"; +import { StorageError } from "./errors"; +import type { StorageHost } from "./host"; +import * as index from "./library-index"; +import { acquireLock, releaseLock } from "./lock"; +import { + FORMAT_STEPS, + type FormatStep, + readFormatVersion, + runFormatSteps, +} from "./migrations"; +import { FORMAT_VERSION, SCHEMA_V1, YJS_ENCODING } from "./schema"; +import { readMeta, readRev, scalar, transaction, writeMeta } from "./sql"; + +export const LIBRARY_FILE = "library.sqlite"; +/** Idle jobs (daily copy, Trash purge) wait for this long without a write. */ +export const IDLE_MS = 30_000; + +export type ReadOnlyReason = "library_too_new" | "migration_failed" | "corrupt"; + +export type LibraryStatus = { + readOnly: ReadOnlyReason | null; + formatVersion: number; + /** The previous session did not shut down cleanly. */ + uncleanExit: boolean; + /** `quick_check`'s verdict after an unclean exit; null when it didn't run. */ + quickCheck: "ok" | string | null; + libraryId: string; +}; + +/** Protocol lines for the durability soak (written to fd 1 by the worker). */ +export type Trace = (line: string) => void; + +export type OpenLibraryOptions = { + dir: string; + host: StorageHost; + openSqlite: OpenSqlite; + /** Default on; the T3 control turns it off. macOS only. */ + fullfsync?: boolean; + /** Default `FULL`; the soak's atomicity control uses `OFF`. */ + synchronous?: "FULL" | "OFF"; + /** For tests: the format this "app" writes, and the steps that reach it. */ + formatVersion?: number; + formatSteps?: readonly FormatStep[]; + trace?: Trace; +}; + +function applyPragmas( + db: SqliteDriver, + host: StorageHost, + options: OpenLibraryOptions, +) { + db.exec("PRAGMA journal_mode = WAL"); + db.exec(`PRAGMA synchronous = ${options.synchronous ?? "FULL"}`); + db.exec("PRAGMA foreign_keys = ON"); + if (host.platform === "darwin" && options.fullfsync !== false) { + db.exec("PRAGMA fullfsync = 1"); + db.exec("PRAGMA checkpoint_fullfsync = 1"); + } +} + +function hasTable(db: SqliteDriver, name: string): boolean { + return ( + scalar( + db, + "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", + name, + ) !== undefined + ); +} + +function createLibrary(db: SqliteDriver, now: number) { + const tables = Number( + scalar(db, "SELECT COUNT(*) FROM sqlite_master WHERE type = 'table'"), + ); + if (tables > 0) + throw new StorageError("corrupt", "not a TinyDocy library (no meta)"); + transaction(db, () => { + db.exec(SCHEMA_V1); + writeMeta(db, "format_version", String(FORMAT_VERSION)); + writeMeta(db, "yjs_encoding", YJS_ENCODING); + writeMeta(db, "library_id", crypto.randomUUID()); + writeMeta(db, "created_at", String(now)); + writeMeta(db, "rev", "0"); + writeMeta(db, "unclean_exit", "0"); + }); +} + +function quickCheck(db: SqliteDriver): string { + const rows = db.prepare("PRAGMA quick_check").all(); + const messages = rows.map((row) => String(Object.values(row)[0])); + return messages.length === 1 && messages[0] === "ok" + ? "ok" + : messages.slice(0, 5).join("; "); +} + +export class Library { + readonly dir: string; + readonly path: string; + readonly status: LibraryStatus; + private db: SqliteDriver | null; + private readonly host: StorageHost; + private readonly openSqlite: OpenSqlite; + private readonly lockPath: string; + private readonly holders = new Map(); + private readonly trace: Trace | undefined; + private lastWriteAt: number; + private changes = new Map(); + private lastDailyCopyError: string | null = null; + + private constructor(fields: { + dir: string; + path: string; + status: LibraryStatus; + db: SqliteDriver; + host: StorageHost; + openSqlite: OpenSqlite; + lockPath: string; + trace: Trace | undefined; + }) { + this.dir = fields.dir; + this.path = fields.path; + this.status = fields.status; + this.db = fields.db; + this.host = fields.host; + this.openSqlite = fields.openSqlite; + this.lockPath = fields.lockPath; + this.trace = fields.trace; + this.lastWriteAt = fields.host.now(); + } + + static open(options: OpenLibraryOptions): Library { + const { dir, host, openSqlite } = options; + const target = options.formatVersion ?? FORMAT_VERSION; + host.mkdirp(dir); + const cloud = cloudFolderOf(dir, host); + if (cloud) throw new StorageError("cloud_folder", cloud); + const lockPath = acquireLock(host, dir); + const path = host.join(dir, LIBRARY_FILE); + let db: SqliteDriver | null = null; + try { + db = openSqlite(path, { readOnly: false }); + applyPragmas(db, host, options); + if (!hasTable(db, "meta")) createLibrary(db, host.now()); + const version = readFormatVersion(db); + const libraryId = readMeta(db, "library_id") ?? ""; + const status: LibraryStatus = { + readOnly: null, + formatVersion: version, + uncleanExit: false, + quickCheck: null, + libraryId, + }; + if (version > target) { + db.close(); + db = openSqlite(path, { readOnly: true }); + status.readOnly = "library_too_new"; + } else { + status.uncleanExit = readMeta(db, "unclean_exit") !== "0"; + if (status.uncleanExit) { + status.quickCheck = quickCheck(db); + if (status.quickCheck !== "ok") status.readOnly = "corrupt"; + } + if (!status.readOnly && version < target) { + try { + status.formatVersion = runFormatSteps( + db, + host, + dir, + target, + options.formatSteps ?? FORMAT_STEPS, + ); + } catch (error) { + if ( + !(error instanceof StorageError) || + error.code !== "migration_failed" + ) + throw error; + status.readOnly = "migration_failed"; + status.formatVersion = readFormatVersion(db); + } + } + if (!status.readOnly) writeMeta(db, "unclean_exit", "1"); + } + return new Library({ + dir, + path, + status, + db, + host, + openSqlite, + lockPath, + trace: options.trace, + }); + } catch (error) { + try { + db?.close(); + } catch { + // Already failing; the original error matters. + } + releaseLock(host, lockPath); + throw storageErrorFrom(error); + } + } + + private get conn(): SqliteDriver { + if (!this.db) + throw new StorageError("library_unavailable", "library is closed"); + return this.db; + } + + private assertWritable() { + if (this.status.readOnly) + throw new StorageError( + this.status.readOnly === "library_too_new" + ? "library_too_new" + : "library_read_only", + this.status.readOnly, + ); + } + + /** Content writes from the renderer: refused while another owner holds the doc. */ + /** + * Content writes from the renderer: only the window holding the document + * may write it (architecture §7: "the registry must hold docId open for + * this window"). Main checks this first; the worker checks again. + */ + private assertWriter(docId: string, owner: string) { + if (this.holders.get(docId) !== owner) + throw new StorageError( + "forbidden", + "this window has not opened the document", + ); + } + + /** Main's own content writes: refused while any window holds the doc. */ + private assertClosed(docId: string) { + if (this.holders.has(docId)) + throw new StorageError("document_open", "document is open"); + } + + private wrote() { + this.lastWriteAt = this.host.now(); + } + + private changed(kind: index.IndexChange["kind"], id: string) { + this.changes.set(`${kind}:${id}`, { kind, id }); + } + + /** + * The rows changed since the last call, with the current `rev`, or null + * when nothing changed. The worker drains this after every request and + * idle pass and sends `index_changed` (architecture §7, §8.1). + */ + takeIndexChanges(): { rev: number; changes: index.IndexChange[] } | null { + if (this.changes.size === 0 || !this.db) return null; + const changes = [...this.changes.values()]; + this.changes.clear(); + return { rev: readRev(this.conn), changes }; + } + + // ── Content (DocStore) ──────────────────────────────────────────────── + + load(docId: string, owner: string): LoadedContent { + const holder = this.holders.get(docId); + if (holder !== undefined && holder !== owner) + throw new StorageError("already_open", "document is open elsewhere"); + const content = load(this.conn, docId); + this.holders.set(docId, owner); + if (!this.status.readOnly) { + try { + index.markOpened(this.conn, docId, this.host.now()); + this.changed("doc", docId); + } catch { + // "Opened" sorting is a nicety; opening must not fail on it. + } + } + return content; + } + + append(docId: string, owner: string, input: AppendInput): number { + this.assertWritable(); + this.assertWriter(docId, owner); + this.trace?.(`BATCH_BEGIN ${docId}`); + const seq = append(this.conn, docId, input, this.host.now()); + this.trace?.(`ACK ${seq}`); + this.wrote(); + this.changed("doc", docId); + return seq; + } + + compact( + docId: string, + owner: string, + state: Uint8Array, + upToSeq: number, + ): { foreign: null } { + this.assertWritable(); + this.assertWriter(docId, owner); + this.trace?.(`COMPACT_BEGIN ${upToSeq} ${state.byteLength}`); + compact(this.conn, docId, state, upToSeq); + this.trace?.(`COMPACT_ACK ${upToSeq}`); + this.wrote(); + return { foreign: null }; + } + + /** + * Re-registers a hold without loading: after a worker restart, main + * replays its registry so the windows' resent batches are accepted. + */ + claim(docId: string, owner: string): void { + const holder = this.holders.get(docId); + if (holder !== undefined && holder !== owner) + throw new StorageError("already_open", "document is open elsewhere"); + if ( + scalar(this.conn, "SELECT 1 FROM docs WHERE id = ?", docId) === undefined + ) + throw new StorageError("not_found", "no such document"); + this.holders.set(docId, owner); + } + + close(docId: string, owner: string): void { + if (this.holders.get(docId) === owner) this.holders.delete(docId); + } + + /** A window closed or its renderer died: every hold it had is released. */ + releaseOwner(owner: string): void { + for (const [docId, holder] of this.holders) + if (holder === owner) this.holders.delete(docId); + } + + isOpen(docId: string): boolean { + return this.holders.has(docId); + } + + /** The whole state of a closed document, for export (P2.8). */ + stateOf(docId: string): Uint8Array { + return stateOf(load(this.conn, docId)); + } + + // ── Index ───────────────────────────────────────────────────────────── + + sidebar(): index.SidebarSnapshot { + return index.sidebarSnapshot(this.conn); + } + + createDoc(input: index.CreateDocInput = {}): index.CreatedDoc { + this.assertWritable(); + const created = index.createDoc(this.conn, input, this.host.now()); + this.wrote(); + this.changed("doc", created.id); + return created; + } + + createFolder(input: { name: string; parentId?: string | null }) { + this.assertWritable(); + const created = index.createFolder(this.conn, input, this.host.now()); + this.wrote(); + this.changed("folder", created.id); + return created; + } + + renameDoc(id: string, title: string): number { + this.assertWritable(); + const rev = index.renameDoc(this.conn, id, title); + this.changed("doc", id); + return rev; + } + + moveDoc(id: string, folderId: string | null, sortKey: string): number { + this.assertWritable(); + const rev = index.moveDoc(this.conn, id, folderId, sortKey); + this.changed("doc", id); + return rev; + } + + trashDoc(id: string, group: string | null = null): number { + this.assertWritable(); + const rev = index.trashDoc(this.conn, id, this.host.now(), group); + this.changed("doc", id); + return rev; + } + + restoreDoc(id: string): number { + this.assertWritable(); + const rev = index.restoreDoc(this.conn, id); + this.changed("doc", id); + return rev; + } + + purgeDoc(id: string): number { + this.assertWritable(); + this.assertClosed(id); + const rev = index.purgeDoc(this.conn, id); + this.wrote(); + this.changed("doc", id); + return rev; + } + + createTag(name: string, color: string | null = null) { + this.assertWritable(); + const created = index.createTag(this.conn, name, color); + this.changed("tag", created.id); + return created; + } + + setDocTags(docId: string, tagIds: readonly string[]): number { + this.assertWritable(); + const rev = index.setDocTags(this.conn, docId, tagIds); + this.changed("doc", docId); + return rev; + } + + // ── Restore points ──────────────────────────────────────────────────── + + listDailyCopies(): string[] { + return listDailyCopies(this.host, this.dir).map((file) => + file.slice("library-".length, -".sqlite".length), + ); + } + + /** One document's state in the daily copy of `date` (`YYYY-MM-DD`). */ + readDailyCopy(date: string, docId: string): Uint8Array { + if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) + throw new StorageError("invalid_argument", "bad date"); + const file = this.host.join(this.dir, DAILY_DIR, dailyCopyName(date)); + if (!this.host.exists(file)) + throw new StorageError("not_found", "no copy for that day"); + const copy = this.openSqlite(file, { readOnly: true }); + try { + return stateOf(load(copy, docId)); + } finally { + copy.close(); + } + } + + // ── Jobs and lifecycle ──────────────────────────────────────────────── + + /** + * Runs the idle jobs when nothing was written for {@link IDLE_MS}: today's + * daily copy, then Trash older than 30 days (skipping open documents). + * Returns what ran, for the worker's diagnostics. A failed daily copy is + * kept for `stats()` (app health `backups_failing`) and retried on the + * next idle pass; it never stops the purge. + */ + runIdleJobs(): { + dailyCopy: string | null; + dailyCopyMs: number | null; + purged: number; + } { + const now = this.host.now(); + const result = { + dailyCopy: null as string | null, + dailyCopyMs: null as number | null, + purged: 0, + }; + if (this.status.readOnly || now - this.lastWriteAt < IDLE_MS) return result; + if (isDailyCopyDue(this.conn, now)) { + const started = performance.now(); + try { + result.dailyCopy = takeDailyCopy(this.conn, this.host, this.dir, now); + this.lastDailyCopyError = null; + } catch (error) { + this.lastDailyCopyError = storageErrorFrom(error).code; + } + result.dailyCopyMs = performance.now() - started; + } + for (const id of index.expiredTrash(this.conn, now)) { + if (this.holders.has(id)) continue; + index.purgeDoc(this.conn, id); + this.changed("doc", id); + result.purged += 1; + } + return result; + } + + /** Forces today's daily copy now (diagnostics, tests). */ + takeDailyCopyNow(): string | null { + this.assertWritable(); + return takeDailyCopy(this.conn, this.host, this.dir, this.host.now()); + } + + stats() { + const db = this.conn; + return { + formatVersion: this.status.formatVersion, + docs: Number(scalar(db, "SELECT COUNT(*) FROM docs")), + pendingRows: pendingRows(db), + bytes: Number( + scalar( + db, + "SELECT page_count * page_size FROM pragma_page_count(), pragma_page_size()", + ), + ), + lastDailyCopy: readMeta(db, "last_daily_copy"), + lastDailyCopyError: this.lastDailyCopyError, + today: localDate(this.host.now()), + // Read back, as set (D-A6; S2 confirmed them on all three OSes). + pragmas: { + journalMode: scalar(db, "PRAGMA journal_mode"), + synchronous: scalar(db, "PRAGMA synchronous"), + fullfsync: scalar(db, "PRAGMA fullfsync"), + checkpointFullfsync: scalar(db, "PRAGMA checkpoint_fullfsync"), + foreignKeys: scalar(db, "PRAGMA foreign_keys"), + }, + sqliteVersion: scalar(db, "SELECT sqlite_version()"), + }; + } + + /** + * The quit flush's last step (architecture §8.2): every request queued + * before this one has already committed (the worker handles one message + * at a time), so checkpoint the WAL into the main file, clear + * `unclean_exit`, close and release the lock. Safe to call twice. + */ + shutdown(): void { + const db = this.db; + if (!db) return; + try { + if (!this.status.readOnly) { + writeMeta(db, "unclean_exit", "0"); + db.exec("PRAGMA wal_checkpoint(TRUNCATE)"); + } + } finally { + this.db = null; + db.close(); + releaseLock(this.host, this.lockPath); + } + } +} diff --git a/desktop/storage/engine/lock.ts b/desktop/storage/engine/lock.ts new file mode 100644 index 00000000..b67d704e --- /dev/null +++ b/desktop/storage/engine/lock.ts @@ -0,0 +1,34 @@ +/** + * `library.lock` (architecture §5.4 `open.ts`): one process opens a library + * at a time. The file holds the owner's pid; a lock whose pid is no longer + * running is stale (a crash or a SIGKILL) and is taken over. Electron's + * single-instance lock covers the usual case; this one also covers a second + * build (internal and release side by side) pointed at the same folder. + */ +import { StorageError } from "./errors"; +import type { StorageHost } from "./host"; + +export const LOCK_FILE = "library.lock"; + +export function acquireLock(host: StorageHost, dir: string): string { + const path = host.join(dir, LOCK_FILE); + for (let attempt = 0; attempt < 3; attempt += 1) { + if (host.createExclusive(path, String(host.pid))) return path; + const holder = Number.parseInt(host.readText(path) ?? "", 10); + if ( + Number.isInteger(holder) && + holder > 0 && + holder !== host.pid && + host.isPidAlive(holder) + ) { + throw new StorageError("locked_elsewhere", `library held by ${holder}`); + } + // Stale (dead pid, unreadable, or our own from a restarted worker). + host.remove(path); + } + throw new StorageError("locked_elsewhere", "could not take library.lock"); +} + +export function releaseLock(host: StorageHost, path: string) { + if (host.readText(path) === String(host.pid)) host.remove(path); +} diff --git a/desktop/storage/engine/migrations.ts b/desktop/storage/engine/migrations.ts new file mode 100644 index 00000000..efbac6a6 --- /dev/null +++ b/desktop/storage/engine/migrations.ts @@ -0,0 +1,100 @@ +/** + * The `format_version` runner (architecture §5.4 `migrations.ts`, D-A6). + * + * - **Newer than the app:** the library opens read-only with + * `library_too_new`, and nothing is written (checked before any other + * write; see `library.ts`). + * - **Older:** `VACUUM INTO library.pre-v-.sqlite` first (the last 2 + * are kept), then each step in its own transaction, which also bumps + * `format_version`. A failed step leaves the library read-only with + * `migration_failed`; a kill between steps resumes at the next one. + * + * Format 1 is the first, so {@link FORMAT_STEPS} is empty. Tests pass their + * own steps to exercise the runner (soak T5). + */ +import type { SqliteDriver } from "./driver"; +import { StorageError } from "./errors"; +import type { StorageHost } from "./host"; +import { readMeta, transaction, writeMeta } from "./sql"; + +export type FormatStep = { + /** The `format_version` this step produces. */ + to: number; + up(db: SqliteDriver): void; +}; + +/** Steps from format 1 to the current `FORMAT_VERSION`, in order. */ +export const FORMAT_STEPS: readonly FormatStep[] = []; + +export const PRE_MIGRATION_KEEP = 2; +const PRE_MIGRATION = /^library\.pre-v\d+-[0-9TZ]+\.sqlite$/; + +/** `20261117T031700Z`: sortable, and valid in a file name on every OS. */ +export function utcStamp(ms: number): string { + return new Date(ms).toISOString().replace(/[-:]/g, "").replace(/\.\d+/, ""); +} + +export function readFormatVersion(db: SqliteDriver): number { + const value = Number.parseInt(readMeta(db, "format_version") ?? "", 10); + if (!Number.isInteger(value) || value < 1) + throw new StorageError("corrupt", "meta.format_version is missing"); + return value; +} + +/** Takes the pre-migration copy and prunes older ones. */ +export function backUpBeforeMigration( + db: SqliteDriver, + host: StorageHost, + dir: string, + from: number, +): string { + const name = `library.pre-v${from}-${utcStamp(host.now())}.sqlite`; + const target = host.join(dir, name); + const partial = `${target}.partial`; + if (host.exists(partial)) host.remove(partial); + db.prepare("VACUUM INTO ?").run(partial); + host.rename(partial, target); + const copies = host + .list(dir) + .filter((file) => PRE_MIGRATION.test(file)) + .sort(); + for (const old of copies.slice(0, -PRE_MIGRATION_KEEP)) + host.remove(host.join(dir, old)); + return target; +} + +/** + * Migrates `db` from its `format_version` to `target`. Returns the version + * reached; throws `migration_failed` when a step fails (that step rolled + * back, earlier ones stay). + */ +export function runFormatSteps( + db: SqliteDriver, + host: StorageHost, + dir: string, + target: number, + steps: readonly FormatStep[], +): number { + let version = readFormatVersion(db); + if (version >= target) return version; + backUpBeforeMigration(db, host, dir, version); + for (const step of steps) { + if (step.to <= version) continue; + if (step.to > target) break; + try { + transaction(db, () => { + step.up(db); + writeMeta(db, "format_version", String(step.to)); + }); + } catch (error) { + throw new StorageError( + "migration_failed", + `step to v${step.to}: ${error instanceof Error ? error.message : String(error)}`, + ); + } + version = step.to; + } + if (version !== target) + throw new StorageError("migration_failed", `no step reaches v${target}`); + return version; +} diff --git a/desktop/storage/engine/schema.ts b/desktop/storage/engine/schema.ts new file mode 100644 index 00000000..ce6a6636 --- /dev/null +++ b/desktop/storage/engine/schema.ts @@ -0,0 +1,120 @@ +/** + * The library schema, `format_version` 1 (desktop architecture §5.3). + * + * Everything the Local release needs is created here, so no later migration + * is needed for it: `tags`, `doc_tags` and `doc_view` (D7, D10), the details + * spec §6.3 list columns, and the v7/v8 seams `docs.link_key` (NOT NULL, + * minted at insert), `docs.kind` and `import_sources`. `blobs` and + * `doc_blobs` arrive with P2.6b, and the Live release adds `remotes` and + * `versions`; each comes with a `format_version` step. + * + * `updates.seq` is `AUTOINCREMENT`, so a seq is never reused after + * compaction deletes the newest rows: a reused seq at or below a snapshot's + * `upto_seq` would be skipped on load. + */ +export const FORMAT_VERSION = 1; + +/** The Yjs update encoding of every stored BLOB (`meta.yjs_encoding`). */ +export const YJS_ENCODING = "v1"; + +export const SCHEMA_V1 = ` +CREATE TABLE meta ( + key TEXT PRIMARY KEY, + value TEXT NOT NULL +) STRICT; + +CREATE TABLE folders ( + id TEXT PRIMARY KEY, + parent_id TEXT, + name TEXT NOT NULL, + sort_key TEXT NOT NULL DEFAULT '', + created_at INTEGER NOT NULL, + modified_at INTEGER NOT NULL, + trashed_at INTEGER, + sort TEXT, + view TEXT, + "group" TEXT +) STRICT; + +CREATE TABLE docs ( + id TEXT PRIMARY KEY, + title TEXT NOT NULL DEFAULT '', + folder_id TEXT, + sort_key TEXT NOT NULL DEFAULT '', + pin_key TEXT, + pinned INTEGER NOT NULL DEFAULT 0, + created_at INTEGER NOT NULL, + modified_at INTEGER NOT NULL, + opened_at INTEGER, + trashed_at INTEGER, + trash_group TEXT, + trashed_from TEXT, + schema INTEGER NOT NULL DEFAULT 0, + lineage TEXT NOT NULL, + size_bytes INTEGER NOT NULL DEFAULT 0, + snippet TEXT NOT NULL DEFAULT '', + mirrored_at INTEGER, + link_key TEXT NOT NULL UNIQUE, + kind TEXT NOT NULL DEFAULT 'doc' CHECK (kind IN ('doc', 'template')) +) STRICT; + +CREATE TABLE import_sources ( + doc_id TEXT PRIMARY KEY REFERENCES docs(id) ON DELETE CASCADE, + relative_path TEXT, + source_app TEXT, + source_hash TEXT, + imported_at INTEGER +) STRICT; + +CREATE TABLE snapshots ( + doc_id TEXT PRIMARY KEY REFERENCES docs(id) ON DELETE CASCADE, + data BLOB NOT NULL, + upto_seq INTEGER NOT NULL +) STRICT; + +CREATE TABLE updates ( + seq INTEGER PRIMARY KEY AUTOINCREMENT, + doc_id TEXT NOT NULL REFERENCES docs(id) ON DELETE CASCADE, + data BLOB NOT NULL, + origin TEXT NOT NULL, + created_at INTEGER NOT NULL +) STRICT; + +CREATE TABLE tags ( + id TEXT PRIMARY KEY, + name TEXT NOT NULL UNIQUE COLLATE NOCASE, + color TEXT +) STRICT; + +CREATE TABLE doc_tags ( + doc_id TEXT NOT NULL REFERENCES docs(id) ON DELETE CASCADE, + tag_id TEXT NOT NULL REFERENCES tags(id) ON DELETE CASCADE, + PRIMARY KEY (doc_id, tag_id) +) STRICT, WITHOUT ROWID; + +CREATE TABLE doc_view ( + doc_id TEXT PRIMARY KEY REFERENCES docs(id) ON DELETE CASCADE, + width TEXT CHECK (width IS NULL OR width IN ('narrow', 'standard', 'wide', 'full')), + place TEXT, + remote_images INTEGER NOT NULL DEFAULT 0 +) STRICT; + +CREATE INDEX updates_doc_seq ON updates(doc_id, seq); +CREATE INDEX docs_folder_list ON docs(folder_id, trashed_at, opened_at); +CREATE INDEX folders_parent ON folders(parent_id); +CREATE INDEX doc_tags_tag ON doc_tags(tag_id); +CREATE INDEX import_sources_hash ON import_sources(source_hash); +`; + +/** Every table format 1 creates; the schema test checks the file against it. */ +export const TABLES_V1 = [ + "doc_tags", + "doc_view", + "docs", + "folders", + "import_sources", + "meta", + "snapshots", + "tags", + "updates", +] as const; diff --git a/desktop/storage/engine/sql.ts b/desktop/storage/engine/sql.ts new file mode 100644 index 00000000..c0b334a5 --- /dev/null +++ b/desktop/storage/engine/sql.ts @@ -0,0 +1,66 @@ +import type { SqliteDriver, SqlRow } from "./driver"; +import { storageErrorFrom } from "./driver"; + +/** + * Runs `body` in one `BEGIN IMMEDIATE … COMMIT`: one transaction, one fsync. + * Any throw rolls back, and a driver failure becomes a `StorageError`. + */ +export function transaction(db: SqliteDriver, body: () => T): T { + try { + db.exec("BEGIN IMMEDIATE"); + } catch (error) { + throw storageErrorFrom(error); + } + try { + const result = body(); + db.exec("COMMIT"); + return result; + } catch (error) { + try { + db.exec("ROLLBACK"); + } catch { + // The failed statement may already have rolled the transaction back. + } + throw storageErrorFrom(error); + } +} + +/** Reads one column of one row; undefined when there is no row. */ +export function scalar( + db: SqliteDriver, + sql: string, + ...params: (string | number | null)[] +): SqlRow[string] | undefined { + const row = db.prepare(sql).get(...params); + return row ? Object.values(row)[0] : undefined; +} + +export function readMeta(db: SqliteDriver, key: string): string | null { + const value = scalar(db, "SELECT value FROM meta WHERE key = ?", key); + return typeof value === "string" ? value : null; +} + +export function writeMeta(db: SqliteDriver, key: string, value: string) { + db.prepare( + "INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value", + ).run(key, value); +} + +/** `meta.rev`: moves on every change the files sidebar shows. */ +export function readRev(db: SqliteDriver): number { + return Number.parseInt(readMeta(db, "rev") ?? "0", 10); +} + +/** Bumps `meta.rev`; call inside the write's transaction. */ +export function bumpRev(db: SqliteDriver): number { + const rev = readRev(db) + 1; + writeMeta(db, "rev", String(rev)); + return rev; +} + +/** 32 lowercase hex characters from the platform CSPRNG (`link_key`). */ +export function randomHex32(): string { + const bytes = new Uint8Array(16); + crypto.getRandomValues(bytes); + return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(""); +} diff --git a/desktop/storage/node-host.ts b/desktop/storage/node-host.ts new file mode 100644 index 00000000..dd38fb3c --- /dev/null +++ b/desktop/storage/node-host.ts @@ -0,0 +1,88 @@ +/** + * The `StorageHost` the worker runs with: `node:fs`, `node:os` and + * `node:path`. Bun implements these modules too, so unit tests use the same + * host (with `now` or `isPidAlive` overridden where a test needs to). + */ +import { + existsSync, + mkdirSync, + readdirSync, + readFileSync, + realpathSync, + renameSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { homedir } from "node:os"; +import { join } from "node:path"; + +import type { StorageHost } from "./engine/host"; + +function isErrno(error: unknown, code: string): boolean { + return ( + typeof error === "object" && + error !== null && + (error as { code?: unknown }).code === code + ); +} + +export function createNodeHost( + overrides: Partial = {}, +): StorageHost { + return { + platform: process.platform, + pid: process.pid, + homeDir: homedir(), + env: process.env, + now: () => Date.now(), + join: (...parts) => join(...parts), + realpath(path) { + try { + return realpathSync.native(path); + } catch { + return path; + } + }, + mkdirp: (path) => { + mkdirSync(path, { recursive: true }); + }, + exists: (path) => existsSync(path), + list(dir) { + try { + return readdirSync(dir); + } catch (error) { + if (isErrno(error, "ENOENT")) return []; + throw error; + } + }, + remove: (path) => rmSync(path, { force: true }), + rename: (from, to) => renameSync(from, to), + readText(path) { + try { + return readFileSync(path, "utf8"); + } catch (error) { + if (isErrno(error, "ENOENT")) return null; + throw error; + } + }, + createExclusive(path, text) { + try { + writeFileSync(path, text, { flag: "wx" }); + return true; + } catch (error) { + if (isErrno(error, "EEXIST")) return false; + throw error; + } + }, + isPidAlive(pid) { + try { + process.kill(pid, 0); + return true; + } catch (error) { + // EPERM: it exists but belongs to someone else. + return isErrno(error, "EPERM"); + } + }, + ...overrides, + }; +} diff --git a/desktop/storage/protocol.ts b/desktop/storage/protocol.ts new file mode 100644 index 00000000..1d238cd3 --- /dev/null +++ b/desktop/storage/protocol.ts @@ -0,0 +1,208 @@ +/** + * Messages between main and the storage worker (desktop architecture §2, + * §7). Main has already validated every request at the IPC boundary; the + * worker trusts main. Nothing is thrown across: every reply is a `Result`. + * + * Bytes travel as `Uint8Array`s whose buffers are transferred, so a + * document crosses each boundary with one copy. + * + * No `node:*` imports: the dev storage host and unit tests dispatch to a + * `Library` in-process with {@link dispatch}. + */ +import type { AppendInput, LoadedContent } from "./engine/content"; +import { type StorageErrorEnvelope, toEnvelope } from "./engine/errors"; +import type { Library, LibraryStatus } from "./engine/library"; +import type { + CreateDocInput, + CreatedDoc, + IndexChange, + SidebarSnapshot, +} from "./engine/library-index"; + +/** Every request: `args` in, `result` out. */ +export type StorageOps = { + load: { args: { docId: string; owner: string }; result: LoadedContent }; + append: { + args: { docId: string; owner: string; record: AppendInput }; + result: number; + }; + compact: { + args: { docId: string; owner: string; state: Uint8Array; upToSeq: number }; + result: { foreign: null }; + }; + /** Main replays its registry after a worker restart. */ + claim: { args: { docId: string; owner: string }; result: null }; + close: { args: { docId: string; owner: string }; result: null }; + releaseOwner: { args: { owner: string }; result: null }; + /** Resolves after every request sent before it: all durable. */ + flush: { args: Record; result: null }; + stateOf: { args: { docId: string }; result: Uint8Array }; + sidebar: { args: Record; result: SidebarSnapshot }; + createDoc: { args: CreateDocInput; result: CreatedDoc }; + createFolder: { + args: { name: string; parentId?: string | null }; + result: { id: string; rev: number }; + }; + renameDoc: { args: { id: string; title: string }; result: number }; + moveDoc: { + args: { id: string; folderId: string | null; sortKey: string }; + result: number; + }; + trashDoc: { args: { id: string; group?: string | null }; result: number }; + restoreDoc: { args: { id: string }; result: number }; + purgeDoc: { args: { id: string }; result: number }; + createTag: { + args: { name: string; color?: string | null }; + result: { id: string; rev: number }; + }; + setDocTags: { args: { docId: string; tagIds: string[] }; result: number }; + listDailyCopies: { args: Record; result: string[] }; + readDailyCopy: { args: { date: string; docId: string }; result: Uint8Array }; + runIdleJobs: { + args: Record; + result: ReturnType; + }; + stats: { args: Record; result: ReturnType }; + /** The quit flush's last step: checkpoint, clear `unclean_exit`, close. */ + shutdown: { args: Record; result: null }; +}; + +export type StorageOp = keyof StorageOps; + +export type Result = + | { ok: true; value: T } + | { ok: false; error: StorageErrorEnvelope }; + +/** main → worker */ +export type StorageRequest = { + [K in StorageOp]: { id: number; op: K; args: StorageOps[K]["args"] }; +}[StorageOp]; + +/** worker → main */ +export type StorageMessage = + | { type: "ready"; status: LibraryStatus; openMs: number } + | { type: "open_failed"; error: StorageErrorEnvelope } + | { type: "reply"; id: number; result: Result } + /** Metadata changed (architecture §7 `index.changed`); main fans it out. */ + | { type: "index_changed"; rev: number; changes: IndexChange[] }; + +/** Options the worker is started with (`workerData`). */ +export type StorageWorkerOptions = { + dir: string; + fullfsync?: boolean; + synchronous?: "FULL" | "OFF"; + /** Durability soak only: protocol lines on fd 1. */ + trace?: boolean; + /** How often the worker looks for idle work, in ms (default 5000). */ + idlePollMs?: number; +}; + +function run(library: Library, request: StorageRequest): unknown { + switch (request.op) { + case "load": + return library.load(request.args.docId, request.args.owner); + case "append": + return library.append( + request.args.docId, + request.args.owner, + request.args.record, + ); + case "compact": + return library.compact( + request.args.docId, + request.args.owner, + request.args.state, + request.args.upToSeq, + ); + case "claim": + library.claim(request.args.docId, request.args.owner); + return null; + case "close": + library.close(request.args.docId, request.args.owner); + return null; + case "releaseOwner": + library.releaseOwner(request.args.owner); + return null; + case "flush": + return null; + case "stateOf": + return library.stateOf(request.args.docId); + case "sidebar": + return library.sidebar(); + case "createDoc": + return library.createDoc(request.args); + case "createFolder": + return library.createFolder(request.args); + case "renameDoc": + return library.renameDoc(request.args.id, request.args.title); + case "moveDoc": + return library.moveDoc( + request.args.id, + request.args.folderId, + request.args.sortKey, + ); + case "trashDoc": + return library.trashDoc(request.args.id, request.args.group ?? null); + case "restoreDoc": + return library.restoreDoc(request.args.id); + case "purgeDoc": + return library.purgeDoc(request.args.id); + case "createTag": + return library.createTag(request.args.name, request.args.color ?? null); + case "setDocTags": + return library.setDocTags(request.args.docId, request.args.tagIds); + case "listDailyCopies": + return library.listDailyCopies(); + case "readDailyCopy": + return library.readDailyCopy(request.args.date, request.args.docId); + case "runIdleJobs": + return library.runIdleJobs(); + case "stats": + return library.stats(); + case "shutdown": + library.shutdown(); + return null; + } +} + +/** Runs one request; a failure becomes an envelope, never a throw. */ +export function dispatch( + library: Library, + request: StorageRequest, +): Result { + try { + return { ok: true, value: run(library, request) }; + } catch (error) { + return { ok: false, error: toEnvelope(error) }; + } +} + +/** The `ArrayBuffer`s in a value that can move instead of being copied. */ +export function transferablesOf(value: unknown): ArrayBuffer[] { + const found: ArrayBuffer[] = []; + const seen = new Set(); + const visit = (item: unknown, depth: number) => { + if (depth > 3 || item === null || typeof item !== "object") return; + if (item instanceof Uint8Array) { + const { buffer } = item; + // Only a buffer the view owns whole; never a pooled or shared one. + if ( + buffer instanceof ArrayBuffer && + item.byteOffset === 0 && + item.byteLength === buffer.byteLength && + !seen.has(buffer) + ) { + seen.add(buffer); + found.push(buffer); + } + return; + } + if (Array.isArray(item)) { + for (const entry of item) visit(entry, depth + 1); + return; + } + for (const entry of Object.values(item)) visit(entry, depth + 1); + }; + visit(value, 0); + return found; +} diff --git a/desktop/storage/worker.ts b/desktop/storage/worker.ts new file mode 100644 index 00000000..f4020017 --- /dev/null +++ b/desktop/storage/worker.ts @@ -0,0 +1,115 @@ +/** + * The storage worker's entry (D-A1): a `worker_thread` inside Electron + * main, and the only SQLite connection to the library. Main starts it in + * parallel with the first window and sends it validated requests; it + * answers them one at a time, in order, so a `flush` or `shutdown` queued + * behind appends runs after they have committed. + * + * Messages: `ready` (or `open_failed`) once, then one `reply` per request, + * and `index_changed` after a metadata write. Idle jobs (daily copy, Trash) + * run between requests after 30 s without a write. + * + * With `trace`, the engine's protocol lines (`BATCH_BEGIN`, `ACK `, + * `COMPACT_BEGIN`, `COMPACT_ACK`) go straight to fd 1 with `writeSync`, so + * the durability soak knows what committed before it kills the process. + */ +import { writeSync } from "node:fs"; +import { parentPort, workerData } from "node:worker_threads"; + +import { openNodeSqlite } from "./drivers/node-sqlite"; +import { toEnvelope } from "./engine/errors"; +import { Library } from "./engine/library"; +import { createNodeHost } from "./node-host"; +import { + dispatch, + type StorageMessage, + type StorageRequest, + type StorageWorkerOptions, + transferablesOf, +} from "./protocol"; + +const port = parentPort; +if (!port) throw new Error("the storage worker must run in a worker_thread"); + +const options = workerData as StorageWorkerOptions; + +const post = (message: StorageMessage) => { + port.postMessage( + message, + message.type === "reply" && message.result.ok + ? transferablesOf(message.result.value) + : [], + ); +}; + +const line = (text: string) => { + writeSync(1, `${text}\n`); +}; + +let library: Library | null = null; +const started = performance.now(); +try { + library = Library.open({ + dir: options.dir, + host: createNodeHost(), + openSqlite: openNodeSqlite, + fullfsync: options.fullfsync, + synchronous: options.synchronous, + trace: options.trace ? line : undefined, + }); + post({ + type: "ready", + status: library.status, + openMs: performance.now() - started, + }); +} catch (error) { + post({ type: "open_failed", error: toEnvelope(error) }); +} + +/** Sends `index_changed` if anything the sidebar shows moved. */ +function announceChanges(open: Library) { + const changed = open.takeIndexChanges(); + if (changed) post({ type: "index_changed", ...changed }); +} + +let idleTimer: ReturnType | null = null; +if (library) { + const open = library; + idleTimer = setInterval(() => { + try { + open.runIdleJobs(); + } catch { + // Only the Trash purge can throw here; it retries on the next pass. + } + announceChanges(open); + }, options.idlePollMs ?? 5000); + idleTimer.unref(); +} + +port.on("message", (request: StorageRequest) => { + if (!library) { + post({ + type: "reply", + id: request.id, + result: { + ok: false, + error: { + code: "library_unavailable", + retryable: true, + message: "the library did not open", + }, + }, + }); + return; + } + const open = library; + const result = dispatch(open, request); + post({ type: "reply", id: request.id, result }); + if (request.op === "shutdown") { + if (idleTimer) clearInterval(idleTimer); + library = null; + port.close(); + return; + } + announceChanges(open); +}); diff --git a/docs/design/2026-11-17-bubble-quick-insert-prototype.html b/docs/design/2026-11-17-bubble-quick-insert-prototype.html new file mode 100644 index 00000000..ca3c2028 --- /dev/null +++ b/docs/design/2026-11-17-bubble-quick-insert-prototype.html @@ -0,0 +1,1114 @@ + + + + + +Bubble and quick insert prototype + + + + + +
+

Bubble & quick insert

+
Version
+
Device
+
Theme
+
Direction
+
Motion
+
Document
+
O11 bubble shape
+
O1 block type
+
O2 colour
+
O4 reactions
+
O5 desktop insert
+
O6 phone insert
+
O12 "/" Suggested
+
O7 keyboard selection
+
Select text with the mouse to see the bubble. Alt+F10 (⌥F10) moves focus into it; arrow keys move; Esc returns with the selection. Put the caret on an empty line for +, or type /. ⋯ in the row › Page width changes the page. Phone: select text for the selection cells; Aa and Insert open sheets.
+
+ +
+ +
+

Prototype only. It approximates editor behaviour with contenteditable; the app uses Tiptap and the action registry. Colours are the app's tokens; icons are lucide 0.469 (the app's set). Today's bubble is shown for comparison under Version › Today.

+
+ + + + diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-dark-02-bubble.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-dark-02-bubble.jpg new file mode 100644 index 00000000..2bc6c518 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-dark-02-bubble.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-dark-03-bubble-colour.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-dark-03-bubble-colour.jpg new file mode 100644 index 00000000..5097072b Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-dark-03-bubble-colour.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-dark-09-slash-query.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-dark-09-slash-query.jpg new file mode 100644 index 00000000..cc6099b1 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-dark-09-slash-query.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-02-bubble.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-02-bubble.jpg new file mode 100644 index 00000000..03349b0b Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-02-bubble.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-03-bubble-colour.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-03-bubble-colour.jpg new file mode 100644 index 00000000..62e2d815 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-03-bubble-colour.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-06-insert-menu.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-06-insert-menu.jpg new file mode 100644 index 00000000..97406fc6 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-06-insert-menu.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-07-more-menu.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-07-more-menu.jpg new file mode 100644 index 00000000..aea0d201 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-07-more-menu.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-08-slash.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-08-slash.jpg new file mode 100644 index 00000000..46ebad29 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-08-slash.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-10-palette.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-10-palette.jpg new file mode 100644 index 00000000..4501a973 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-10-palette.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-11-narrow-bubble.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-11-narrow-bubble.jpg new file mode 100644 index 00000000..3e4aeef6 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-11-narrow-bubble.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-12-bubble-title.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-12-bubble-title.jpg new file mode 100644 index 00000000..a043d153 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-12-bubble-title.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-14-alt-f10.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-14-alt-f10.jpg new file mode 100644 index 00000000..685e75aa Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-14-alt-f10.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-15-link-create.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-15-link-create.jpg new file mode 100644 index 00000000..8036afc1 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-15-link-create.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-16-link-preview.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-16-link-preview.jpg new file mode 100644 index 00000000..924d1c49 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/desktop-light-16-link-preview.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/phone-dark-02-selection-cells.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/phone-dark-02-selection-cells.jpg new file mode 100644 index 00000000..68b1c436 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/phone-dark-02-selection-cells.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/phone-dark-03-format-sheet.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/phone-dark-03-format-sheet.jpg new file mode 100644 index 00000000..68670193 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/phone-dark-03-format-sheet.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-01-bar.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-01-bar.jpg new file mode 100644 index 00000000..e01b01c5 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-01-bar.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-02-selection-cells.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-02-selection-cells.jpg new file mode 100644 index 00000000..cfc76e21 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-02-selection-cells.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-03-format-sheet.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-03-format-sheet.jpg new file mode 100644 index 00000000..cc4ec1af Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-03-format-sheet.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-04-insert.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-04-insert.jpg new file mode 100644 index 00000000..111cec27 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-04-insert.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-05-slash.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-05-slash.jpg new file mode 100644 index 00000000..6b02e2a1 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/phone-light-05-slash.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/phone320-dark-02-selection.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/phone320-dark-02-selection.jpg new file mode 100644 index 00000000..020a23b1 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/phone320-dark-02-selection.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/current/tablet-light-02-selection.jpg b/docs/design/2026-11-17-bubble-quick-insert/current/tablet-light-02-selection.jpg new file mode 100644 index 00000000..a10e12e1 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/current/tablet-light-02-selection.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p01-bubble.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p01-bubble.jpg new file mode 100644 index 00000000..d5cd2a56 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p01-bubble.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p02-style.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p02-style.jpg new file mode 100644 index 00000000..8c2aace7 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p02-style.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p03-colour.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p03-colour.jpg new file mode 100644 index 00000000..cdc76b47 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p03-colour.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p04-link.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p04-link.jpg new file mode 100644 index 00000000..c34c2be0 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p04-link.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p05-plus.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p05-plus.jpg new file mode 100644 index 00000000..f852c1f4 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p05-plus.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p06-plus-menu.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p06-plus-menu.jpg new file mode 100644 index 00000000..349c9571 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p06-plus-menu.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p07-slash.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p07-slash.jpg new file mode 100644 index 00000000..0c521766 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p07-slash.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p08-more-width.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p08-more-width.jpg new file mode 100644 index 00000000..d80da514 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p08-more-width.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p09-dark-comment.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p09-dark-comment.jpg new file mode 100644 index 00000000..d5fdaab5 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p09-dark-comment.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p10-rtl-bubble.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p10-rtl-bubble.jpg new file mode 100644 index 00000000..89b6213a Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p10-rtl-bubble.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p11-today.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p11-today.jpg new file mode 100644 index 00000000..3783d0e5 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p11-today.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p12-phone-insert.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p12-phone-insert.jpg new file mode 100644 index 00000000..7c5f1265 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p12-phone-insert.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p13-phone-aa.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p13-phone-aa.jpg new file mode 100644 index 00000000..164e3c94 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p13-phone-aa.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p14-tablet.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p14-tablet.jpg new file mode 100644 index 00000000..edd1f410 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p14-tablet.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p15-o1b-o2a-o4b.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p15-o1b-o2a-o4b.jpg new file mode 100644 index 00000000..83ecab9a Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p15-o1b-o2a-o4b.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p16-o5b.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p16-o5b.jpg new file mode 100644 index 00000000..121fd674 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p16-o5b.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p17-altf10.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p17-altf10.jpg new file mode 100644 index 00000000..0de1f6f5 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p17-altf10.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p18-o11b-panel.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p18-o11b-panel.jpg new file mode 100644 index 00000000..e8b20865 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p18-o11b-panel.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p19-o11b-turninto.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p19-o11b-turninto.jpg new file mode 100644 index 00000000..95a10d04 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p19-o11b-turninto.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p20-dark-colour.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p20-dark-colour.jpg new file mode 100644 index 00000000..6159e89d Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p20-dark-colour.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p21-slash-suggested.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p21-slash-suggested.jpg new file mode 100644 index 00000000..8a638b43 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p21-slash-suggested.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p22-slash-tip.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p22-slash-tip.jpg new file mode 100644 index 00000000..4b65d257 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p22-slash-tip.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p23-rtl-slash.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p23-rtl-slash.jpg new file mode 100644 index 00000000..11204ef0 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p23-rtl-slash.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p24-phone-insert-turninto.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p24-phone-insert-turninto.jpg new file mode 100644 index 00000000..f753f221 Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p24-phone-insert-turninto.jpg differ diff --git a/docs/design/2026-11-17-bubble-quick-insert/proposed/p25-phone-aa-pill.jpg b/docs/design/2026-11-17-bubble-quick-insert/proposed/p25-phone-aa-pill.jpg new file mode 100644 index 00000000..e825a3ac Binary files /dev/null and b/docs/design/2026-11-17-bubble-quick-insert/proposed/p25-phone-aa-pill.jpg differ diff --git a/docs/superpowers/plans/2026-11-17-bubble-and-quick-insert.md b/docs/superpowers/plans/2026-11-17-bubble-and-quick-insert.md new file mode 100644 index 00000000..9dda2a4b --- /dev/null +++ b/docs/superpowers/plans/2026-11-17-bubble-and-quick-insert.md @@ -0,0 +1,632 @@ +# Selection bubble and quick insert: implementation plan + +> **For agentic workers:** REQUIRED SUB-SKILL: use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task by task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Build the approved bubble, quick-insert and "/" design in six phases (P0–P5), one PR per phase. + +**Architecture:** +- The bubble stops registering a ProseMirror plugin. A lazy `BubbleController` listens to editor events and positions one reused root with `@floating-ui/dom`, keeping today's DOM contract. +- Every new surface reads labels, icons, shortcuts and reasons from `lib/editor-actions`, and lives in an existing lazy chunk: bubble, menus, colour, slash or phone. +- The eager editor chunk grows only where a step says so, and only by measured bytes. + +**Tech stack:** Next.js 16, React 19, Tiptap 3.33, ProseMirror, Yjs, `@floating-ui/dom` 1.8, Base UI, Bun (`bun test` with happy-dom), Playwright. + +**Spec:** [`docs/superpowers/specs/2026-11-17-bubble-and-quick-insert-design.md`](../specs/2026-11-17-bubble-and-quick-insert-design.md), approved by the owner on 2026-11-17 ("Approve as recommended"). Executors read the spec section each task cites. + +## Global Constraints + +- **Bun only:** `bun`, `bun run …`, `bun playwright …`; never npm, npx, yarn or pnpm. Run Playwright with `CI=` against running dev servers. +- **Commits:** + - Conventional Commits, atomic, imperative mood. + - **No AI, tool or Co-authored-by trailers.** + - Each PR adds its CHANGELOG entry under Unreleased. + - **Never rebase, force-push or merge.** Open the PR and report it. +- **Editor chunk:** + - `bun run build && bun scripts/check-editor-chunk-size.ts` after merging `origin/main` (P2.2, #123, moves the fence by about +294 B). + - Growth over ±16 B needs a D23 ledger amendment approved before merge. + - Every new surface is lazy. + - Never `registerPlugin` from a lazy chunk. + - Never subscribe the editor shell to editor state. Toolbar re-renders go through `useTiptapEditor`'s shared store. +- **Off-limits until their PRs land:** + - `components/document-editor/**` and the P2.2 area (#123); + - `lib/platform/**`; + - `hooks/use-yjs-document.ts` and `hooks/use-synced-tabs.ts`. + - The highlight and link colour tokens (#114, merged) are fine now. Check `phone.scss` ownership with `git log -1 -- components/smart-toolbar/phone/phone.scss` before P4. +- **UI:** + - shadcn/ui components and `lucide-react` icons through `lib/icons.tsx`, with RTL flips via `flipInRtl` there; + - named exports; title-case acronyms in PascalCase names. + - Targets are 28 px on a fine pointer and 44 px on a coarse one. +- **Copy:** one word per block type, "Text" (BQ11). Faces use H1–H6; menus and accessible names use "Heading 2". +- **Motion token (O10):** enter 120 ms (opacity, scale 0.98 → 1, `cubic-bezier(0.2,0,0,1)`); exit 80 ms (opacity only, linear); no animation under `prefers-reduced-motion` or `data-motion="reduce"`. +- **Verification:** + - screenshots from headless Playwright (no visible windows on the owner's Mac), light and dark, LTR and RTL where the surface exists; + - each visible phase gets the owner session's design review before merge. +- **Dev servers** for e2e: CI-like limits, `DOC_CREATION_RATE_LIMIT=2000 WS_CONNECTION_LIMIT=200 WS_SOCKETS_PER_IP=600 WS_UPGRADE_RATE_LIMIT=6000 HOCUS_THROTTLE=0`. Use ports other sessions don't hold (check with `lsof`). Next and Hocus share one `DB_PATH`. + +## Review Focus + +1. **Tab switch while the bubble is open.** The editor remounts (`key={activeTabId}`). The old controller must tear down once (StrictMode runs effects twice), and no root may stay in the old scroll container. **Test:** P0 Task 0.3, "tab switch with the bubble open leaves no root and no listeners". +2. **⌘A on a 500-heading document.** The anchor must be the first *visible* selected line, computed without laying out every `content-visibility`-skipped block, and the bubble must appear within one frame of the show delay. **Test:** P0 Task 0.3, "select all anchors to the first visible line". +3. **A remote edit deletes the selected text while the bubble or its colour menu is open.** It hides, and focus returns to the editor, never `body`. **Test:** P0 Task 0.3, "a collaborator deleting the selection hides the bubble" (it extends the existing collaboration helpers). +4. **IME composition.** No show, move or hide mid-composition; a re-check on `compositionend`. **Test:** P0 Task 0.2 (controller unit test with `view.composing` stubbed). +5. **Clicking 🔗 and pasting at once.** The selected text must survive. **Test:** P1 Task 1.6. + +--- + +# Phase P0: the bubble without `registerPlugin` (BQ2, BQ3) + +**Branch:** `feat/bubble-controller` from `origin/main`. **Visible change:** the anchor (BQ3) and whitespace-only hiding. Items are unchanged. A design review is needed. + +### Task 0.1: Pure anchor helpers and the whitespace rule + +**Files:** +- Modify: `components/smart-toolbar/bubble/bubble-rules.ts` +- Test: `tests/unit/components/selection-bubble-rules.test.ts` + +**Interfaces:** +- Produces: + - `firstLineRect(rects: readonly BubbleRect[], band: { top: number; bottom: number }): BubbleRect | null`; + - `lastLineRect(rects: readonly BubbleRect[], band: { top: number; bottom: number }): BubbleRect | null`; + - the `BUBBLE_LINE_SLACK = 2` export. +- `shouldShowBubble` now also returns `false` for a whitespace-only selection. + +- [ ] **Step 1: Write the failing tests** + +```ts +const r = (top: number, left: number, right: number, h = 20) => ({ top, bottom: top + h, left, right }); +test("firstLineRect unions the rects on the first visible line", () => { + const band = { top: 0, bottom: 1000 }; + expect(firstLineRect([r(100, 300, 500), r(101, 500, 520), r(130, 50, 400)], band)) + .toEqual({ top: 100, bottom: 121, left: 300, right: 520 }); +}); +test("firstLineRect skips lines above the band and zero-width rects", () => { + expect(firstLineRect([r(-40, 0, 300), r(10, 40, 40), r(30, 60, 90)], { top: 0, bottom: 800 })) + .toEqual({ top: 30, bottom: 50, left: 60, right: 90 }); +}); +test("firstLineRect is null when no line is in the band", () => { + expect(firstLineRect([r(900, 0, 10)], { top: 0, bottom: 800 })).toBeNull(); +}); +test("lastLineRect unions the rects on the last visible line", () => { + expect(lastLineRect([r(100, 300, 500), r(130, 50, 400), r(131, 400, 420)], { top: 0, bottom: 1000 })) + .toEqual({ top: 130, bottom: 151, left: 50, right: 420 }); +}); +test("hidden for a whitespace-only selection", () => { + // editor with "

a b

", select the three spaces + expect(shouldShowBubble(viewOf(editor), root, false)).toBe(false); +}); +``` + +- [ ] **Step 2: Run the tests** + +Run: `bun test tests/unit/components/selection-bubble-rules.test.ts`. Expected: FAIL, because `firstLineRect` is not exported. + +- [ ] **Step 3: Implement the helpers in `bubble-rules.ts`** + +- **Same line:** two rects are on one line when their tops differ by at most `BUBBLE_LINE_SLACK`. +- **Which rects count:** ignore rects with `right - left < 1`, and rects that don't intersect the band. +- **The result** is the bounding box of that line's rects. +- **In `shouldShowBubble`:** replace `doc.textBetween(from, to).length === 0` with `doc.textBetween(from, to).trim().length === 0`. + +- [ ] **Step 4: Run the tests** + +Run: `bun test tests/unit/components/selection-bubble-rules.test.ts`. Expected: PASS, including the existing cases. + +- [ ] **Step 5: Commit** + +```bash +git add components/smart-toolbar/bubble/bubble-rules.ts tests/unit/components/selection-bubble-rules.test.ts +git commit -m "feat(bubble): anchor helpers and hide on whitespace-only selections" +``` + +### Task 0.2: `BubbleController` (show, hide, position) and the anchor + +**Files:** +- Create: `components/smart-toolbar/bubble/bubble-controller.ts` +- Create: `components/smart-toolbar/bubble/bubble-anchor.ts` +- Test: `tests/unit/components/bubble-controller.test.ts` + +**Interfaces:** +- Consumes: `firstLineRect`, `lastLineRect` and `BubblePlacement` from Task 0.1. +- Produces: + +```ts +// bubble-controller.ts +export const BUBBLE_SHOW_DELAY_MS = 250; // Tiptap's updateDelay, kept +export const BUBBLE_RESIZE_DELAY_MS = 60; // Tiptap's resizeDelay, kept +export interface BubbleHost { + readonly root: HTMLElement; // reused; appended on show, removed on hide + shouldShow(): boolean; // the view's shouldShowBubble + suppression + getReferenceRect(placement: BubblePlacement): DOMRect; + onShow(): void; onHide(): void; onPosition(): void; +} +export interface BubbleController { + readonly visible: boolean; + update(): void; // re-evaluate now (no delay) + updatePosition(): void; + hide(): void; + setPlacement(placement: BubblePlacement): void; + destroy(): void; // idempotent +} +export function createBubbleController(editor: Editor, scrollTarget: HTMLElement, host: BubbleHost): BubbleController; + +// bubble-anchor.ts +export function bubbleReferenceRect(view: EditorView, scrollTarget: HTMLElement, placement: BubblePlacement): DOMRect; +``` + +- [ ] **Step 1: Write the failing controller tests** + +They use `createTestEditor` (`tests/helpers/create-test-editor.ts`), a `div` scroll target in `document.body`, a stub host whose `getReferenceRect` returns `new DOMRect(10, 10, 50, 20)`, and real timers with `await Bun.sleep(BUBBLE_SHOW_DELAY_MS + 50)`. + +```ts +test("shows after the delay for a non-empty selection and appends the root", async () => { /* select 1..4 */ + expect(host.root.isConnected).toBe(false); + await Bun.sleep(BUBBLE_SHOW_DELAY_MS + 50); + expect(host.root.parentElement).toBe(scrollTarget); expect(onShow).toHaveBeenCalledTimes(1); }); +test("hides synchronously on an empty selection and removes the root", async () => { + /* shown, then setTextSelection(2) */ expect(host.root.isConnected).toBe(false); expect(onHide).toHaveBeenCalledTimes(1); }); +test("typing with an empty selection never asks shouldShow", () => { + editor.commands.insertContent("abc"); expect(shouldShow).not.toHaveBeenCalled(); }); +test("no show while composing; shows after compositionend", async () => { + Object.defineProperty(editor.view, "composing", { configurable: true, get: () => true }); + /* select; sleep */ expect(host.root.isConnected).toBe(false); + Object.defineProperty(editor.view, "composing", { configurable: true, get: () => false }); + editor.view.dom.dispatchEvent(new Event("compositionend")); await Bun.sleep(BUBBLE_SHOW_DELAY_MS + 50); + expect(host.root.isConnected).toBe(true); }); +test("dragstart and contextmenu on the editor hide it", ...); +test("a pointer drag shows only after pointerup", ...); // pointerdown on view.dom, select, sleep: hidden; pointerup: shows after delay +test("blur to outside hides; a mousedown inside the root keeps it", ...); +test("setEditable(false) hides it (update event)", ...); +test("destroy is idempotent and detaches every listener", () => { + controller.destroy(); controller.destroy(); + /* select + sleep */ expect(host.root.isConnected).toBe(false); expect(onShow).not.toHaveBeenCalled(); }); +``` + +- [ ] **Step 2: Run the tests** + +Run: `bun test tests/unit/components/bubble-controller.test.ts`. Expected: FAIL (module missing). + +- [ ] **Step 3: Implement `createBubbleController`** + +These behaviours copy `node_modules/@tiptap/extension-bubble-menu/src/bubble-menu-plugin.ts`. Cite its line numbers in comments. + +- **Transactions:** one `editor.on("transaction")` handler. It begins with `if (!visible && editor.state.selection.empty) return`. + - A non-empty selection that changed (`!prev.selection.eq` or `!prev.doc.eq`) shows after `BUBBLE_SHOW_DELAY_MS`, with the timer reset on each change. + - An empty selection, or `!host.shouldShow()`, hides **at once**. + - It returns while `view.composing`. +- **Editor events:** + - `editor.on("focus")`: re-evaluate in a `setTimeout` (plugin :459). + - `editor.on("blur", { event })`: hide unless `preventHide` was set by a capture `mousedown` on `host.root`, `relatedTarget` is inside `host.root`, or it is `view.dom` (plugin :464-484). + - `editor.on("update")`: hide when `!editor.isEditable`. +- **DOM events on `view.dom`:** + - `dragstart` and `contextmenu` hide; + - `compositionend` re-evaluates in a `setTimeout`; + - `pointerdown` sets `dragging`, and `pointerup` clears it and re-evaluates. While `dragging`, never show. +- **Window:** `resize` repositions, debounced by `BUBBLE_RESIZE_DELAY_MS`. +- **`show()`:** + - `scrollTarget.appendChild(host.root)`, then `host.onShow()`; + - then `autoUpdate(reference, host.root, updatePosition, { ancestorScroll: false, elementResize: true })`, where `reference = { getBoundingClientRect: () => host.getReferenceRect(placement), contextElement: editor.view.dom }`. +- **`hide()`:** stop `autoUpdate`, `host.root.remove()` **synchronously**, then `host.onHide()`. +- **`updatePosition()`:** + - `computePosition(reference, host.root, { strategy: "absolute", placement: placement === "top" ? "top" : "bottom", middleware: [offset(BUBBLE_OFFSET), shift({ padding: 8 }), hide()] })`; + - on `hide.referenceHidden || hide.escaped`, set `style.visibility = "hidden"`; otherwise `visible`, `position`, `left`, `top`; + - then `host.onPosition()`. + - Ignore results after `destroy()` or when hidden. +- **Lifecycle:** keep controllers in a module `WeakMap`. `destroy()` removes every listener and timer, calls `hide()`, and deletes its entry. A second call does nothing. + +- [ ] **Step 4: Implement `bubbleReferenceRect` in `bubble-anchor.ts` (DOM; Task 0.3's e2e covers it)** + +1. **The band:** + - top: the sticky row's `getBoundingClientRect().bottom` (`':scope > [data-slot="toolbar"]'`), else the scroll target's top; + - bottom: the scroll target's bottom. +2. **The start position:** `a = from`. + - If `view.coordsAtPos(from).bottom < band.top`, use `view.posAtCoords({ left: view.dom.getBoundingClientRect().left + 1, top: band.top + 1 })?.pos`, clamped to `[from, to]`. +3. **The DOM range:** from `view.domAtPos(a)` to `view.domAtPos(Math.min(to, a + 300))`, then `firstLineRect([...range.getClientRects()], band)`. +4. **For `placement === "bottom"`:** use the range `[Math.max(from, b - 300), b]`, where `b` is `to`, or `view.posAtCoords` at `band.bottom - 1` when `to` is below the band. Then apply `lastLineRect`. +5. **Fallback:** if the helper returns null, or any step throws, return `posToDOMRect(view, from, to)` (`@tiptap/core`). + +- [ ] **Step 5: Run the tests** + +Run: `bun test tests/unit/components/bubble-controller.test.ts tests/unit/components/selection-bubble-rules.test.ts`. Expected: PASS. + +- [ ] **Step 6: Commit** + +```bash +git add components/smart-toolbar/bubble/bubble-controller.ts components/smart-toolbar/bubble/bubble-anchor.ts tests/unit/components/bubble-controller.test.ts +git commit -m "feat(bubble): add a plugin-free bubble controller and line anchor" +``` + +### Task 0.3: Switch `SelectionBubbleView` to the controller + +**Files:** +- Modify: `components/smart-toolbar/bubble/selection-bubble-view.tsx` +- Modify: `components/smart-toolbar/bubble/selection-bubble.scss`, only if the root's class or position rules move +- Test: `tests/e2e/selection-bubble.spec.ts` (new cases; every existing case must still pass) +- Modify: `docs/superpowers/specs/2026-11-13-smart-toolbar-v1-contract.md` §10 (amendment A18), `CHANGELOG.md` + +**Interfaces:** +- Consumes: `createBubbleController`, `BubbleHost` and `bubbleReferenceRect` from Task 0.2. +- The DOM contract is unchanged: + - the root has `className="st-bubble"`, `data-smart-bubble`, `data-state` and `data-placement`, and one `role="toolbar"` inside; + - the root is a direct child of `.document-editor-wrapper` while shown, and absent otherwise. + +- [ ] **Step 1: Write the failing e2e tests** (Chromium) + +- **"mounting the bubble chunk registers no plugin":** + - `holdChunk(page, CHUNK_MARKERS.bubble)`, then open the document. + - Record `editor.state.plugins.length` and mark every `editor.view.pluginViews` entry in a `WeakSet`. + - Release the chunk, `dragSelect`, and expect the bubble to be visible. + - Then expect the plugin count to be unchanged and every current plugin view to be in the set. +- **"a selection starting on a wrapped second line anchors to that line":** + - Use a heading followed by a long paragraph. Select from the start of the paragraph's **second visual line** for 12 characters. + - Expect the bubble's horizontal centre within 2 px of that selection's centre, or clamped by 8 px to the page column. + - Expect `bubble.bottom <= lineTop` and `bubble.bottom >= lineTop - 8 - bubble.height - 1`. +- **"select all anchors to the first visible line":** a 300-paragraph document scrolled to the middle, then ⌘A. Expect the bubble inside the viewport, within 60 px under the sticky row. +- **"a whitespace-only selection shows no bubble":** expect a count of 0. +- **"dragstart hides it":** `dispatchEvent('dragstart')` on `.tiptap`, then expect a count of 0. +- **"tab switch with the bubble open leaves no root and no listeners":** + - Open the bubble, switch to Playground and back 5 times. + - Expect `.document-editor-wrapper > [data-smart-bubble]` to have a count of 0 with an empty selection. + - Expect the listener counts back at baseline, using the `editor-leak.spec.ts` helpers. +- **"a collaborator deleting the selection hides the bubble":** + - A second page on the same document (`collaboration.spec.ts` helpers) deletes the selected paragraph. + - Expect a count of 0, and `document.activeElement` is not `body`. + +- [ ] **Step 2: Run the tests** + +Run: `CI= bun playwright test tests/e2e/selection-bubble.spec.ts --project=chromium`. Expected: the new cases FAIL (the plugin is registered, and the anchor is the union rect); the old ones pass. + +- [ ] **Step 3: Rewrite `BubbleView` on the controller** + +1. **Remove** the `BubbleMenu` import, `BUBBLE_KEY`, `dispatchMeta` and the `requestAnimationFrame` re-append effect (lines 207–222). +2. **Create the root once:** `useState(() => { const el = document.createElement("div"); el.className = "st-bubble"; el.dataset.smartBubble = ""; el.dataset.state = "closed"; return el; })`. This chunk is client-only, so there is no hydration concern. +3. **Effect:** `const c = createBubbleController(editor, scrollTarget, host); return () => c.destroy();`. The `host` maps today's code: + - `shouldShow` → `shouldShowBubble(view, root, suppressedRef.current)`; + - `getReferenceRect` → `bubbleReferenceRect(view, scrollTarget, placementRef.current)`; + - `onShow` and `onHide` → today's bodies; + - `onPosition` → today's `place()`, which calls `controller.setPlacement(next)` instead of `updateOptions`. +4. **Replace** each `dispatchMeta("hide")` with `controller.hide()`, and each `dispatchMeta("updatePosition")` with `controller.updatePosition()`. +5. **`chooseBubblePlacement`** receives the **first-line** rect, from `bubbleReferenceRect(view, scrollTarget, "top")`, as `selection`. +6. **Render:** `createPortal(shown ? : null, root)`. The children are exactly today's. +7. **Remove the old focus-out guard.** It reads `root.style.opacity === "0"` because of the plugin's hide; it is now unneeded, because `hide()` removes the root first and calls `onHide` after. +8. **Check** with `grep -rn "@tiptap/react/menus\|extension-bubble-menu" components lib extensions` that nothing else imports either module. If nothing does, the dependency stays installed, unused, and unimported. + +- [ ] **Step 4: Run the bubble suites** + +Run: `CI= bun playwright test tests/e2e/selection-bubble.spec.ts tests/e2e/lazy-surfaces.spec.ts tests/e2e/paint-format.spec.ts tests/e2e/toolbar-focus-guards.spec.ts tests/e2e/editor-leak.spec.ts --project=chromium`. Expected: all PASS. + +Then run `bun run test`, `bun run typecheck`, `bun run check` and `bun run lint`. Expected: clean. + +- [ ] **Step 5: Measure** + +Merge `origin/main` first (no rebase). Then run `bun run build && bun scripts/check-editor-chunk-size.ts`. Expected: within the budget, and ≤ +16 B against `origin/main` built the same way. + +For the bubble chunk: `for f in $(grep -l "st-bubble-panel" .next/static/chunks/*.js); do gzip -c $f | wc -c; done`, before and after. Expected: smaller. Record both in the PR. + +- [ ] **Step 6: Screenshots and docs** + +- **Screenshots:** headless Playwright, light and dark, of a two-line selection on (1) `main` and (2) the branch, plus RTL. +- **Contract:** add amendment A18 to the v1 contract §10. `BUBBLE_KEY` meta and the plugin are gone; the DOM contract is unchanged; the root is appended on show and removed on hide. +- **CHANGELOG:** add the entry. + +- [ ] **Step 7: Commit, push, open the PR** (`feat(bubble): …`), and report it. Don't merge. + +--- + +# Phase P1: bubble v2 (BQ1, BQ6, BQ10, BQ11, O1, O2, O3 slot, O7, O10) + +**Branch:** `feat/bubble-v2` from `main` after P0 merges. Visible; needs a design review. + +### Task 1.1: Block-type face + +**Files:** create `components/smart-toolbar/bubble/style-face.ts`; test `tests/unit/components/style-face.test.ts`. + +**Interfaces:** +- Produces: `type StyleFace = "Text" | "H1" | "H2" | "H3" | "H4" | "H5" | "H6" | "Title" | "List" | "Quote" | "Code" | "Mixed"`. +- Produces: `styleFace(state: EditorState): StyleFace`, which walks the top-level blocks the selection touches and **returns at the second distinct type**. + +**Tests:** +- paragraph → `"Text"`; H2 → `"H2"`; first H1 → `"Title"`; +- a bullet, ordered or task item → `"List"`; a blockquote → `"Quote"`; +- paragraph + H2 → `"Mixed"`; +- ⌘A including the title → `"Mixed"`; +- a 2,000-paragraph selection that changes type at block 2 visits ≤ 2 blocks (count with a spied `nodesBetween` callback). + +Commit: `feat(bubble): compute the Style face`. + +### Task 1.2: Turn-into menu body, shared by the bubble and the row (BQ10, BQ11) + +**Files:** +- create `components/smart-toolbar/row/turn-into-menu-items.tsx`, exported through `menu-bodies.ts`; +- modify `components/smart-toolbar/row/style-menu.tsx` (the face says "Text"; the items come from the shared body); +- modify `components/smart-toolbar/row/menu-items.tsx` (`ToolbarMenuContent` takes `side?: "top" | "bottom"` and `align?: "start" | "center" | "end"`); +- test `tests/e2e/toolbar-row.spec.ts`, `tests/unit/editor-actions/contract.test.ts`. + +**Interfaces:** +- Produces: `TURN_INTO_IDS = ["style.paragraph","style.heading1","style.heading2","style.heading3",/* More headings ▸ */"list.bullet","list.ordered","list.task","insert.quote","insert.codeBlock"] as const`. +- Produces: ``. +- Each row shows icon, label, `formatKeyCombo(shortcut)` (`kbd dir="ltr"`) and a trailing ✓ cell, in `grid-template-columns: 16px 1fr auto 16px`, with **no Markdown chips**. +- H4–H6 sit under "More headings ▸". +- The title disables every row with "Title is always H1." +- Your formats stays in the row's Style ▾ only, below a separator. + +**Tests:** +- the row face reads "Text" in a paragraph; +- Quote and Code block convert a paragraph, one undo step each; +- every id in `TURN_INTO_IDS` exists in `editorActions` (contract test). + +Commit: `feat(toolbar): turn-into menu shared by the bubble and the row`. + +### Task 1.3: Bubble layout v2 + +**Files:** modify `selection-bubble-view.tsx`, `bubble-rules.ts` (`BUBBLE_ACTION_IDS`), `selection-bubble.scss`, `color-controls.tsx` (the split chevron is 24 px); test `selection-bubble.spec.ts` (update "shows B, I, U…" and the bubble-in-row matrix). + +**Interfaces:** +- Produces: `BUBBLE_ACTION_IDS = ["mark.bold","mark.italic","mark.underline","mark.strike","mark.inlineCode","format.clear","color.text.apply","mark.link"]`. +- Layout: `StyleMenu face │ B I U S ‹› Tx │ A▁▾ 🔗 🖌 │ [comment slot]`. +- The comment slot is `ActionButton id="comment.add"`, which renders `null` until the comments PR registers the id. +- The Style face's width is measured once at mount, from the longest face word in `actionLabel` output, with a minimum of 64 px. If that is more than 96 px, the face is the icon plus a chevron. + +**CSS** (spec §7.1): +- light edge `oklch(0.87 0 0)`; +- dark `--bubble-surface: oklch(0.24 0 0)` and edge `oklch(1 0 0 / 36%)`; +- focus ring `outline-offset: -2px` inside the bubble; +- a dashed mixed bar; +- forced colours: a `CanvasText` edge. + +**Tests:** +- order and accessible names; +- inside inline code, B, I, U, S, colour, link and paint are `aria-disabled` and their described reason includes "Inline code"; +- the matrix covers every id in the row; +- forced colours keep the edge. + +Commit: `feat(bubble): fuller bubble with style, strike, code and clear`. + +### Task 1.4: Named colour rows on desktop (O2) + +**Files:** modify `components/smart-toolbar/color/color-panel.tsx` and `color-panel.scss`; create `components/smart-toolbar/color/color-order.ts`; tests `action-preview.spec.ts`, `toolbar-surfaces.spec.ts`. + +**Interfaces:** +- Produces: `ColorPanel` prop `layout: "rows" | "grid"`. + - The bubble and the row pass `"rows"`. + - The phone sheet passes `"grid"`, plus `caption="current"`. +- Produces: `FIRST_TEXT_COLORS = ["red","orange","green","blue","purple"]` and `FIRST_HIGHLIGHTS = ["yellow","green","blue","pink"]`. +- **Rows layout:** + - Recent first: up to 5 from `RECENT_COLORS_CHOICE`. + - Then two columns, Text | Highlight, as `role="group"` with `menuitemradio`. + - Default and No highlight use `Ban`. Text chips are 18 px "A" tiles in the token colour; highlight tiles are filled. + - "More colours ▸" and "More highlights ▸" hold the rest. + - Arrow keys: Up/Down within a column; Left/Right across columns, visual order in RTL (`visualStep` if P2.13 has landed, else `dir` from `getComputedStyle`). + - The hover preview calls `setActionPreview` on pointer enter and on focus. + +**Tests:** +- naming: the row named "Teal text" exists under More; +- a hover preview decorates the selection; +- Left/Right crosses columns; +- the phone sheet still shows the grid, and a tap shows the pill "Teal text" with Undo. + +Commit: `feat(color): named colour rows on desktop surfaces`. + +### Task 1.5: Keyboard-selection timing (O7) and motion (O10) + +**Files:** `bubble-controller.ts` (with an option), `selection-bubble-view.tsx`, `selection-bubble.scss`; tests `selection-bubble.spec.ts`. + +**Interfaces:** +- `BubbleHost.keyboardSettleMs = 300`. +- After a selection change caused by a `keydown` with Shift held, show only after `keyup` of Shift **and** 300 ms with no further selection change. Never show on auto-repeat. +- Alt+F10 (the `toolbar.focus` intent) calls `controller.update()` and shows at once. +- Motion follows the global constraint. + +**Tests:** +- Shift+Arrow ×5: no bubble while Shift is held, and a bubble 300–450 ms after Shift is released; +- Alt+F10 shows it at once; +- with reduced motion, `getAnimations()` is empty. + +Commit: `feat(bubble): settle keyboard selections before showing`. + +### Task 1.6: Link handoff and the pill reasons + +**Files:** `selection-bubble-view.tsx`; test `selection-bubble.spec.ts`. + +**Behaviour:** +- Clicking 🔗 runs `mark.link`, then `controller.hide()` in the **same task**. +- The Hyperlink popover takes focus on its first frame, and it opens below the selection (the package's fixed placement, spec §7.5). +- Applying ‹› over linked or coloured text announces "Link and colour removed" with Undo, through the status pill. + +**Tests:** +- **"click link and paste at once keeps the selected text":** click 🔗, then `page.keyboard.insertText("https://e.com")` with no wait. The document still contains the selected words, and they now carry the link. +- a URL pasted over a selection links it; +- a media URL pasted over a selection doesn't (`shouldAutoLink`). + +Commit: `feat(bubble): hand off to the link field without a gap`. + +Then: screenshots (spec Appendix C, bubble rows), CHANGELOG, PR. Report it; don't merge. + +--- + +# Phase P2: quick insert and the "/" amendments (O5, O12, BQ9, OB2) + +**Branch:** `feat/quick-insert` from `main` after P1. Visible. + +### Task 2.1: Suggested from recent insert kinds (O12 a) + +**Files:** +- `lib/remembered-choice.ts`: `INSERT_KIND_CHOICE.maxRecent` 0 → 3; +- `lib/slash-menu/slash-items.ts`; +- the v1 contract A18, extended; +- tests `tests/unit/lib/remembered-choice.test.ts`, `tests/unit/lib/slash-items.test.ts`. + +**Interfaces:** +- `SlashSection` gains `"Suggested"`. +- `buildSlashItems(ctx, actions, tableSize, recentKinds: readonly InsertKind[])` prepends up to 3 Suggested items when `recentKinds` is non-empty. Each also stays in its own section. +- `matchSlashItems` drops Suggested for a non-empty query, and breaks rank ties in favour of recent kinds. + +**Tests:** +- an old stored entry `{ last: "table", recent: [] }` reads as last "table" and recent []; +- after inserting table, image, divider, `recent` is `["divider","image","table"]`; +- a new writer sees no Suggested section; +- Forget clears it. + +Commit: `feat(slash): suggest recent insert kinds`. + +### Task 2.2: Ghost hint, footer and badges (BQ9) + +**Files:** `components/smart-toolbar/slash/slash-menu.tsx`; create `components/smart-toolbar/slash/slash-footer.tsx` and `lib/slash-menu/slash-badges.ts`; test `tests/e2e/slash-menu.spec.ts`. + +**Interfaces:** +- Produces: `NEW_UNTIL: Readonly> = {}` (it ships empty). +- Produces: `isNewItem(item: SlashItem, today: string, recentKinds: readonly string[]): boolean`. +- The menu is 320 px wide. +- **Ghost:** an `aria-hidden` element at `coordsAtPos(head)`, in the paragraph's computed `font`, coloured `--muted-foreground`. It shows only while the query is empty, nothing follows the caret in the block, and no composition is active. +- **Footer:** sticky, outside the scrolling list. + - Start: "Type `##` then space for Heading 2" for the active row's `hint`, else "↑ ↓ to move · ↵ to insert". Hidden on a coarse pointer. + - End: a button "Close" with `esc`. + +**Tests:** +- the ghost shows at an empty line and not mid-line; +- the tip follows ArrowDown; +- the Close button leaves "/" as text; +- a badge shows before the date and not after first use (inject `today`); +- RTL: the list's right edge is within 2 px of the "/" caret. + +Commit: `feat(slash): inline hint, footer tip and close button`. + +### Task 2.3: `+` on the empty line (O5 a) + +**Files:** +- create `components/smart-toolbar/slash/empty-line-plus.tsx`, exported from `slash-menu.tsx`'s module; +- modify `components/smart-toolbar/slash-menu-host.tsx`: when the module is loaded, render ``, eager, **measured inside the 1,000 B slash cap**; +- test `tests/e2e/slash-menu.spec.ts`. + +**Interfaces:** `EmptyLinePlus({ editor }: SurfaceProps)`. +- It shows on a fine pointer while the caret is in an empty paragraph (not the title, a list, a quote or a table cell), 300 ms after the last keystroke. +- It also shows on hover over an empty paragraph after a 150 ms dwell, detected from the DOM at most once per frame. +- It re-measures on `transaction` while shown, and hides from `compositionstart` to `compositionend`. +- `mousedown` → `preventDefault`. A click moves the caret into the paragraph and dispatches `tr.insertText("/")` with `addToHistory: false`. That is the trigger's own path. +- Esc with an empty query after a `+`-opened menu deletes the "/" (`addToHistory: false`). The host passes `origin: "plus"` through a module flag that the menu reads once. +- It has `aria-haspopup="listbox"`, `aria-label="Insert block"` and `tabIndex={-1}`. + +**Tests:** +- the `+` appears beside an empty paragraph and not beside the title; +- a click opens the "/" menu with the ghost; +- Esc leaves the paragraph empty and `editor.can().undo()` unchanged; +- a pick is one undo step; +- no `+` on a coarse pointer; +- the `+` hides during IME composition (CDP). + +Commit: `feat(slash): plus button on empty lines`. + +### Task 2.4: Insert alias hints, the placeholder, and the registry contract test + +**Files:** +- `insert/insert-menu-body.tsx`: the "/" alias as an end hint; +- `components/document-editor/document-editor-config.ts:94`: "Type / for blocks". **Only after #123 merges; else leave it for a follow-up and say so in the PR**; +- create `tests/unit/editor-actions/surface-labels.test.ts`. + +**Contract test:** +1. Every id named by the bubble, Turn-into, slash, Insert and phone surfaces exists in the registry. +2. Those surface files contain no hard-coded registry labels: grep for each of their ids' labels. +3. Every `markdownHint` shown in "/" triggers its block through the real input rules in `createTestEditor`. For example, typing `## ` makes `heading level 2`. + +Commit: `feat(slash): alias hints and a label contract test`. + +Then: screenshots, CHANGELOG, PR. + +--- + +# Phase P3: the row's ⋯ regroup (BQ4) and Page width (O9) + +**Branch:** `feat/overflow-groups`. + +### Task 3.1: Groups + +**Files:** `components/smart-toolbar/row/overflow-menu.tsx` and its body in `row/row-menu-bodies.tsx`; tests `toolbar-row.spec.ts`, `toolbar-a11y*.spec.ts`. + +- **Groups:** + - Text: Superscript, Subscript, Inline code, Clear formatting, Paint format; + - View: Simplified toolbar ☐, Appearance ▸; + - Help: All actions… ⌥/; + - then "Forget my choices…" alone. +- Each group is `role="group"` with `aria-label` and a visible heading. +- Every row has a 16 px leading slot. + +**Tests:** the group order and names; "Forget my choices…" is last. + +Commit: `feat(toolbar): group the row's more menu`. + +### Task 3.2: Page width ▸ (gated) + +**Gate:** start only when the preferences work (P2.9c) has merged `page.width` / `doc.width` (check the preferences spec rows 7–8 in the code). Until then, record "blocked on P2.9c" in the PR and skip this task. + +Then: View › Page width ▸ (Narrow, Standard, Wide, Full, with a ✓). In the web library, add "Use default (Standard)". In the sandbox, write the app-wide `ui.page.width`. Test each value's `data-page-width` and `data-doc-width`. + +Then: CHANGELOG, PR. + +--- + +# Phase P4: phone and tablet (O6, O8 a, §13.1) + +**Branch:** `feat/phone-insert-sheet`. **Gate:** phone file ownership is clear (Global Constraints). + +### Task 4.1: Insert sheet + +**Files:** create `components/smart-toolbar/phone/insert-sheet.tsx`; modify `phone/phone-menu-cells.tsx` (the Insert cell opens the sheet) and `lib/slash-menu/slash-items.ts` (export `groupSlashItems(items)` for grid rendering); test `tests/e2e/mobile-bar.spec.ts`. + +**Interfaces:** `InsertSheet({ editor, open, onOpenChange })` uses the `Sheet` component with swipe-to-close, `--safe-area-bottom` padding and a 16 px scroll fade. +- **Sections:** Suggested (optional), then "Blocks" or "Turn into" (by whether the caret's block is empty), then Insert. +- **Cells:** 44 px, two columns. +- **Steps:** table and embed open through `lazySurface(loadInsertStep)`; image opens the file picker. + +**Tests:** +- the section titles for an empty block and a non-empty block; +- a pick closes the sheet and the keyboard caret lands in the new block; +- axe is clean; +- 320 px fits with no horizontal scroll. + +Commit: `feat(phone): insert sheet`. + +### Task 4.2: Aa sheet order and the tablet stand-in words + +**Files:** `phone/format-sheet.tsx` (Style first, with a pressed current style and More headings ▸; colours as a 44 px grid with the current-value caption and the applied pill with Undo); the row's stand-ins (`collapse-menus.tsx`: words "Format", "Layout", "Block" at ≥ 768 px on a coarse pointer, CSS only); tests `mobile-bar*.spec.ts`, `toolbar-ladder.spec.ts`. + +Commit: `feat(phone): style first in the format sheet; words on tablet stand-ins`. + +Then: screenshots (390, 320, 820 px), CHANGELOG, PR. + +--- + +# Phase P5: comment wiring (O3, BQ10, §7.6) + +**Branch:** after the comments UI (P4.10) registers `comment.add`. + +### Task 5.1 + +**Files:** `bubble-rules.ts` (`BUBBLE_ACTION_IDS` gains `"comment.add"`), `insert/insert-menu-body.tsx` (Insert › Comment where `canComment()`), and the reading-mode comment-only bubble in `selection-bubble-view.tsx` (shown while `!editor.isEditable && canComment()`). + +**Tests:** +- 💬 is last, and absent in the Playground and the sandbox; +- the bubble-in-row matrix finds Insert › Comment; +- reading mode shows only 💬; +- ⌥⌘M opens the draft card (macOS). + +Commit and PR. + +--- + +## Self-review notes + +- **Spec coverage:** + - §7.1–7.6 → P1; + - §7.7 and §7.9 → nothing to build (decided "none"); + - §7.8 → P1, the row layout; + - §7.10 → P1 Tasks 2 and 4 (keyboard); + - §8.2, §8.5 → P2; + - §8.3, §13.1, §13.2 → P4; + - §9 → P3; + - §10 → P0 and P1; + - §11 → P1 Task 1.5; + - §12 → P0; + - §13.3 (contextmenu hide) → P0 Task 0.2; + - §13.4 RTL → P1 Task 1.4 and P2 Task 2.2; + - §14 → the tests per task; + - §16 → the per-phase tests. +- **Gated items,** each named in its task: Page width (P2.9c), the placeholder (#123), phone files (ownership), 💬 (P4.10). diff --git a/docs/superpowers/specs/2026-11-15-desktop-architecture.md b/docs/superpowers/specs/2026-11-15-desktop-architecture.md index 5356fb1a..a4775161 100644 --- a/docs/superpowers/specs/2026-11-15-desktop-architecture.md +++ b/docs/superpowers/specs/2026-11-15-desktop-architecture.md @@ -126,8 +126,13 @@ desktop/ main/ # index, windows, app-protocol, csp, doc-handlers, quit-coordinator, menus, # dialogs, deep-links, backups, updater (lazy), diagnostics storage/worker.ts # worker_thread entry + storage/client.ts # main's handle on the worker: start, call, shutdown (P2.6) + storage/protocol.ts # request and reply types, dispatch (no node:* imports) + storage/node-host.ts # the StorageHost (fs, pid check, clock) the engine is given storage/engine/ # SQL logic over a SqliteDriver; no electron, node:* or bun:* imports storage/drivers/node-sqlite.ts + storage-harness/ # the soak's Electron main (own lockfile), like smoke/ (P2.6) + dev/bun-sqlite-driver.ts # the SqliteDriver over bun:sqlite, for tests and the dev host dev/storage-host.ts # dev and test only: doc-handlers + engine on bun:sqlite over a localhost WebSocket build/build.ts, build/electron-builder.yml ``` @@ -140,10 +145,14 @@ desktop/ - The Privacy link goes to the website's page, `${SITE_URL}/privacy`, in a new window that the shell sends to the system browser, as a plain anchor that is never prefetched, because `/privacy` is web only (`components/site-page/privacy-link.tsx`, #101). - X posts render as a static link card: the kit's `x` node stays in the schema, so documents with X posts stay valid and a web client still embeds them, but its node view is replaced, so no oEmbed request and no `widgets.js` (`extensions/hyper-multimedia/x-link-card.ts`, #99). The spike's `X: false` would have dropped the node from the desktop schema. The card's stylesheet loads by `import()` inside the desktop branch: a static stylesheet import survives tree shaking and would ship to the web. - The Embed dialog neither lists nor accepts X; pasting an X URL into the document still makes the card (`use-media-embed.ts`, #99). - - The `desktop` Playwright project checks a desktop-flag production build: no request for `/privacy`, and none to X's hosts (`tests/e2e/desktop-seams.spec.ts`). - - `next.config.ts` switches three things on that literal: `output: "export"`, `headers()` (web only), and `pageExtensions`: web `["web.tsx", "web.ts", "tsx", "ts"]`, desktop `["desktop.tsx", "tsx", "ts"]`. + - The service worker never registers: it precaches web-only pages (`SHELL_PATHS` has `/privacy`), and the renderer loads from disk (`components/pwa/service-worker-registration.tsx`, P2.4). + - **The export** (P2.4): `bun run build:desktop` (`scripts/build-desktop.ts`) writes `out/` and fails if a web-only route, a web metadata tag (`rel="manifest"`, `og:image`, `twitter:image`, `apple-touch-icon`, `href="/privacy"`) or a `__next.*` directory reaches it. Desktop routes: `/`, `/about`, `/_not-found`, `/icon`. It skips Next's own type pass (`typescript.ignoreBuildErrors` on desktop only): with web-only files parked, the route types a `next dev` run left in `.next/dev/types` import files that aren't there, and `bun run typecheck` already checks every file. + - The `desktop` Playwright project runs on that export, served by `scripts/serve-desktop-export.ts` with the protocol handler's path rules (`desktop/shared/export-paths.ts`, which P2.5's handler reuses: `/about` → `about.html`, RSC `.txt` files under their exported names, `/icon` as `image/png`, unknown types and traversal refused). It checks that every request the renderer makes is answered and none goes to a web-only route, no request for `/privacy`, and none to X's hosts (`tests/e2e/desktop-seams.spec.ts`). Nightly runs it on Linux (`desktop-renderer`). + - `next.config.ts` switches three things on that literal: `output: "export"` (in the production build phase only: under `next dev`, as in the `local` project, the metadata files aren't parked, and exporting would make each a 500 that every page links), `headers()` (web only), and `pageExtensions`: web `["web.tsx", "web.ts", "tsx", "ts"]`, desktop `["desktop.tsx", "tsx", "ts"]`. The web-only route handlers are `route.web.ts(x)`: `app/api/**`, `llms.txt`, `pwa-icons/[id]`. + - **Web-only pages are parked, not renamed.** Next 16.4.6 drops the root layout's font preload from a `page.web.tsx`: `getPreloadableFonts` strips only the last extension, so it looks up `app/privacy/page.web` in a font manifest keyed `app/privacy/page`. Renaming `/privacy` and `/offline` would change their web HTML, so they join the parked metadata files below. - **S1 (2026-11-16):** Turbopack honours `pageExtensions` for `page` and `route` files but not for metadata files: in the web build `sitemap.web.ts` became the route `/sitemap.web`. So `sitemap`, `robots`, `opengraph-image`, `manifest` and `apple-icon` keep their plain names, and a prebuild step moves them out of `app/` for the desktop build and puts them back (the overlay fallback). - - It parks them inside the checkout: a rename across drives fails with `EXDEV` on Windows runners (#111, proved on `windows-latest` with the default temp dir). Before moving anything it puts back files that an interrupted run left parked; otherwise the next web build would silently lose them. + - It parks them inside the checkout, in `.desktop-export-parked/` (gitignored): a rename across drives fails with `EXDEV` on Windows runners (#111, proved on `windows-latest` with the default temp dir). Before moving anything it puts back files that an interrupted run left parked, and it puts them back in `finally` and on SIGINT or SIGTERM. A file both in `app/` and parked stops the build. + - `next.config.ts` refuses a web build while anything is parked, so a killed export (SIGKILL included) can't ship a web build without its sitemap, manifest or privacy page. - **The overlay stays in Phase 2** ([Windows export spike](../../research/2026-11-17-spike-windows-export.md), 2026-11-17). The desktop build flag alone can't replace it. Left in `app/`, the five files fail the export (`force-static` not configured). With `dynamic = "force-static"` the export passes, but every desktop page then carries ``, the web `og:image` and `apple-touch-icon`. Deleting the files from `out/` afterwards would leave those tags pointing at nothing. - **Built once, on Linux** (#103). Next 16.4.6 writes segment-prefetch files on Windows as `__next./__PAGE__.txt` instead of `__next..__PAGE__.txt`, so prefetch 404s (upstream vercel/next.js#85374, still unfixed in 16.5 canary). Windows never exports the renderer: the release and nightly pipelines build `out/` once, in a Linux job, and hand the same bytes to every OS's packaging job (test and release strategy §2.4). The PR job `electron-mac` may export on its own macOS runner. The protocol handler maps no names. - `icon.tsx` needs `export const dynamic = "force-static"`, and `tsconfig.json` excludes `out/` (the export copies the service worker's `.ts` source into `out/_next/static/media/`). @@ -176,7 +185,7 @@ These are enforced by one test, `tests/unit/ci/import-boundaries.test.ts`. It re |---|---| | `desktop/shared` | anything outside itself | | `desktop/storage/engine` | `electron`, `node:*`, `bun:*`, React, `@tiptap/*` | -| `desktop/main`, `desktop/storage` | React, `lib/**` (except `lib/security/content-security-policy.ts`, `lib/doc-migrations`, `lib/prefs/schema.ts`, and the pure `lib/comments/validate.ts` and `lib/assets` sniffers) | +| `desktop/main`, `desktop/storage` | React, `lib/**` (except `lib/security/content-security-policy.ts`, `lib/doc-migrations`, `lib/prefs/schema.ts`, the pure `lib/comments/validate.ts` and `lib/assets` sniffers, and `lib/schema-names.ts`, the name lists the import guard checks; P2.6) | | `desktop/preload` | anything except `desktop/shared` and `electron` | | `lib/platform/desktop` | `desktop/{main,preload,storage}` | | `app`, `components`, `hooks`, `lib` | `desktop/**` except `desktop/shared` types; `lib/platform/desktop/**` except from `components/desktop/desktop-root.tsx` | @@ -208,7 +217,7 @@ Each port has its own types-only file in `lib/platform/` (P2.1): `doc-session.ts **Shared editor changes** stay within their lines in the editor-chunk ledger (owner D23, ≈1,540 B gz in all, ≈1,580–1,660 B with D41's conditional phone line; P2.2's line, no provider plus `WriteGate` and the decoration-host stub, is 300 B; details spec §1 rule 5), checked by the chunk script on both targets, with `EDITOR_CHUNK_BUDGET_BYTES` lowered to `main` plus the ledger: -1. **`provider` becomes `HocuspocusProvider | null`.** `CollaborationCaret` is configured with the session's stable `awareness` (**decided in P2.2**, against the extension's runtime). The `useMemo` deps hold `awareness`, never the provider, so a provider attached later never rebuilds the extensions array. +1. **`provider` becomes `HocuspocusProvider | null`.** `CollaborationCaret` is configured with the session's stable `awareness` (**decided in P2.2**, against the extension's runtime: the caret reads only `provider.awareness`, so it gets `{ awareness, on, off }`; UniqueID also finds that option and waits for its `"synced"` event, so `on` and `off` forward to the provider of the moment through a ref, and with no provider nothing is waited for). The `useMemo` deps hold `awareness`, never the provider, so a provider attached later never rebuilds the extensions array. 2. **`CollabStatusGroup` renders only when `provider` is non-null.** Today it calls `useConnectionState`, which **creates the shared socket**, so a Local document would dial the server. The desktop chip is rendered by the desktop shell, outside the editor chunk. 3. **Seeding stays as it is.** `authoritative` feeds the existing `serverSynced` prop, and `local-session` sets it once hydrate finishes, because the library *is* the authority. The seed effect (`use-document-editor-effects.ts:78`) runs unchanged, and `data-server-synced` doubles as the readiness hook for the `local` and `electron` projects. (Live) A joined document becomes authoritative only after its first server sync. @@ -298,6 +307,14 @@ INDEX import_sources(source_hash) | `assets.ts` (P2.6b) | Owns `/assets/`: the temp-fsync-rename write order, dedupe, the startup `tmp/` sweep, `recount` and GC with a 30-day grace (image store §3.2–§3.4). | | `jobs.ts` | One queue. Foreground calls run first; daily copy and mirror run on idle, meaning 30 s without an append. Each job yields between documents. | +**As built in P2.6.** +- **Modules.** `index.ts` is `library-index.ts` (not a barrel). `library.ts` holds the open order, the registry and the lifecycle; `lock.ts`, `cloud-folder.ts`, `sql.ts`, `driver.ts` (the `SqliteDriver` seam and SQLite error mapping) and `host.ts` (an injected `StorageHost` for files, the pid check and the clock) keep the engine free of `node:*`. `jobs.ts` is two lines in the worker: idle jobs run between requests after 30 s without a write. `mirror.ts`, `filenames.ts` and `assets.ts` come with P2.10 and P2.6b. +- **Open order.** Cloud-folder refusal, lock, pragmas, schema creation for a new file, then `format_version` before any other write (a newer library is reopened read-only and never written), then `quick_check` if `unclean_exit` was set (a failure is read-only, `corrupt`), then migrations, then `unclean_exit` is set. +- **Registry in the worker too.** `load` claims a document for a window; another window's `load` is `already_open`; an append or compaction from any window that doesn't hold the document is `forbidden`, as §7 requires of main; purge (and P2.8's import-into and restore) is `document_open` while any window holds it. After a worker restart, main replays its registry with `claim(docId, owner)`. +- **Compaction guards.** A compaction older than the stored snapshot is a no-op. An `upToSeq` past the document's last row is `invalid_argument`. `updates.seq` is `AUTOINCREMENT`, so a seq is never reused after the newest rows are compacted away. +- **`docs.schema`** defaults to 0, which is `DOC_SCHEMA` while `lib/doc-migrations` lists no steps. +- **Import guard.** `checkImport` (`lib/doc-migrations/import-guard.ts`) refuses a state over 64 MiB (`import_too_large`), bytes that aren't Yjs (`corrupt`), and nodes, marks or roots the build doesn't know (`unknown_schema`; legacy `link` and `code` pass, the import migrations rename them; roots: `default`, plus `comments` in P4.11). P2.8 calls it before anything is written. + **Backup failures.** EPERM, EACCES and Defender blocks on the backup folder raise app health `backups_failing` (§6.1; plan §5.5 "Backups failing"). The library itself is never affected. --- @@ -584,7 +601,7 @@ sequenceDiagram | Compaction invariant | property test: random appends, compactions and reopens, with the Y.Doc state compared against a reference | engine on `bun:sqlite` | | Guards and `doc-handlers` | fuzz plus golden messages, sender and registry checks | pure modules | | Reducer and chip | a table row for each plan §5.5 state; "every refusal ends in a stop or a backoff" | pure | -| Durability T1–T8, T16–T18 | `tests/load/desktop-durability-soak.ts`: SIGKILL Electron during append, compaction, migration, asset writes and image migration; a year of image churn | packaged app | +| Durability T1–T8, T16–T18 | `tests/load/desktop-durability-soak.ts`: SIGKILL Electron during append, compaction, migration, asset writes and image migration; a year of image churn | the storage worker in a windowless Electron (`desktop/storage-harness`, P2.6), verified on `bun:sqlite`; the packaged app once P2.5 lands. T7 (slow hydrate) tests the session layer, not storage: P2.1 covers it in `local-session`'s tests, and W2 again over IndexedDB. | | `BlobStore` contract and asset GC | one suite plus a property test: GC never deletes a referenced blob | `MemoryBlobStore`; the worker on `bun:sqlite`; `IdbBlobStore` in the web library | | Preferences boot script | parity with `resolveBoot()` over about 40 stored payloads; the desktop CSP hash matches the script (build test) | happy-dom; build | | Main | `argv` filter, navigation and `window.open` denial, fuses | `_electron` | diff --git a/docs/superpowers/specs/2026-11-15-desktop-documents-and-editor-details.md b/docs/superpowers/specs/2026-11-15-desktop-documents-and-editor-details.md index f96b89cb..d160ac5f 100644 --- a/docs/superpowers/specs/2026-11-15-desktop-documents-and-editor-details.md +++ b/docs/superpowers/specs/2026-11-15-desktop-documents-and-editor-details.md @@ -56,7 +56,7 @@ These came out of the staff feasibility review. Each one was checked against the | Line | PR (owner) | Cap (gz) | |---|---|---| - | No provider, `WriteGate` and the decoration host | P2.2 | 300 B | + | No provider, `WriteGate` and the decoration host | P2.2 | 300 B (measured 294 B) | | Comments hook | P4.9 | 150 B | | Smart-quotes gate | P2.9c-1 | 150 B | | i18n core (`t()`, registry labels, `lang`/`dir`; also pays L3's `matchShortcut` / `visualStep` bytes, languages §3.7.1) | L1a | 400 B | @@ -68,7 +68,7 @@ These came out of the staff feasibility review. Each one was checked against the | Undo-gesture handler, **only if spike M18 shows native undo mutates the DOM** (D41, v8) | M19 | 80 B, conditional | | **Total** | | **1,580 B, or 1,660 B with the undo handler** | - - **Headroom:** 4,385 B real (the 24,064 B budget less `main` at 19,679 B, latest CHANGELOG entry). The ledger takes about a third of it, with or without the conditional line. + - **Headroom:** 4,385 B real when D23 was decided (the 24,064 B budget less `main` at 19,679 B). By P2.2, `main` had shrunk to +15,284 B (08b7663), so P2.2 set the fence at +16,864 B (15,284 + 1,580) in `scripts/check-editor-chunk-size.ts`; after P2.2 1,286 B remain for the other lines. - **Phones (D41):** M27's hardware-keyboard listener (shortcut glyphs) stays **out** of the editor chunk. - **Fencing:** P2.2 lowers `EDITOR_CHUNK_BUDGET_BYTES` to the size on `main` plus the ledger total, so unrelated work can't spend these bytes. Raising it needs an amendment to this rule. While D41's conditional 80 B undo line is unconfirmed, the fence is `main` + 1,580 B. If spike M18 confirms the line, the fence rises to `main` + 1,660 B with no further approval (pre-approved by D41). - **A PR that would go over its line** stops for a budget review. A line's unused bytes don't move to another line without an amendment. diff --git a/docs/superpowers/specs/2026-11-17-bubble-and-quick-insert-design.md b/docs/superpowers/specs/2026-11-17-bubble-and-quick-insert-design.md new file mode 100644 index 00000000..12520576 --- /dev/null +++ b/docs/superpowers/specs/2026-11-17-bubble-and-quick-insert-design.md @@ -0,0 +1,1278 @@ +# Selection bubble and quick insert: design + +- **Status:** **Approved by the owner, 2026-11-17** ("Approve as recommended"): every decision in §2 as recommended, including O11 a (one row), O1 a, O2 b, O4 a, O5 a + c, O6 a, O7 b, O8 a, O12 a and BQ1–BQ11. Plan: [`docs/superpowers/plans/2026-11-17-bubble-and-quick-insert.md`](../plans/2026-11-17-bubble-and-quick-insert.md). +- **Why now:** the owner shared two screenshots of another editor's selection bubble and bottom insert pill. They asked for a rethink of TinyDocy's bubble and quick-access surfaces that covers every state, edge case and platform. +- **Decides:** + - what lives in the bubble, the Insert surfaces, the row and the page menu; + - colour and highlight, block type and lists, links; + - the comment and reaction entry points; + - page-level actions; + - placement, collision, motion and shortcut hints; + - phone, tablet, desktop (Electron) and RTL behaviour; + - one engineering correction: how the bubble attaches to the editor. +- **Prototype:** [`docs/design/2026-11-17-bubble-quick-insert-prototype.html`](../../design/2026-11-17-bubble-quick-insert-prototype.html). It is clickable and has switches for each owner decision, theme, RTL, reduced motion and device. It is throwaway, not app code. +- **Screenshots of today's UI:** [`docs/design/2026-11-17-bubble-quick-insert/current/`](../../design/2026-11-17-bubble-quick-insert/current/). They were taken from `main` at `f9cfc3a` on `next dev`, headless Chromium, at 2× and 3×. +- **Parent and sibling documents.** This spec ties into each of them and amends some (the list at the end of §2): + - [Smart toolbar design](2026-11-12-smart-toolbar-design.md) and [design pass](2026-11-13-smart-toolbar-design-pass.md); + - [v1 contract](2026-11-13-smart-toolbar-v1-contract.md) (A9–A17); + - [Comments](2026-11-16-comments-design.md), [Preferences](2026-11-16-preferences-design.md) and [Phones and tablets](2026-11-16-phones-tablets-design.md); + - [Desktop UX](2026-11-15-desktop-ux-design.md) and [Documents and editor details](2026-11-15-desktop-documents-and-editor-details.md) (D23 ledger, rule 6); + - [Languages and RTL](2026-11-16-languages-rtl-design.md). +- **Evidence labels:** + - *measured* means run here, with the method given. + - *source* means read in the installed code. + - *[unverified]* was not checked. + +--- + +## 1. Summary + +Most of what the owner's reference shows is already in TinyDocy. Some of it is in the wrong place, some is hidden, and some stops short of the last detail. + +- **The bubble is too thin.** It has B, I, U, the colour split, Link and Paint format. Strike, inline code and the block type are absent, so changing "this heading to H3" means a trip to the row at the top of the window. +- **Quick insert is split three ways:** the row's `+ Insert`, the "/" menu, and List ▾. Only "/" sits near the caret, and "/" needs a key that some RTL phone keyboards hide. +- **Page-level and preference actions** are mixed into the row's ⋯ with superscript and "Forget my choices". + +The design keeps everything that works: +- the registry as the one source of actions; +- Alt+F10 into the bubble and Esc back out; +- hiding the bubble on typing; +- the hover preview; +- the remembered choices; +- the "/" menu; +- the phone bar with no scrolling. + +It then makes four moves, plus focused amendments to the "/" menu (§8.5) taken from the owner's second reference set (Notion): +1. **A fuller bubble with one fixed layout:** Style ▾ │ B I U S ‹› Tx │ Colour Link Paint │ Comment. It stays one row, not Notion's vertical panel (O11). +2. **One caret-local, non-typed way to insert on desktop:** a `+` on the empty line, which opens the same list as "/". +3. **A phone Insert sheet**, replacing today's desktop-style dropdown. +4. **The bubble attaches without registering a ProseMirror plugin.** Today's lazy `` breaks an AGENTS.md rule and rebuilds every plugin view late, after the editor is interactive. The measurement and its real, modest impact are in §4.1. + +The reference's bottom insert pill and "Make page wide" item are deliberately **not** copied on desktop. Why is in §8.4 and §9. + +--- + +## 2. Decisions to approve + +> **Approved by the owner, 2026-11-17: "Approve as recommended."** Each row below is decided as its Recommendation column says. + +Each row is either a proposal (BQ*n*) or an owner choice (O*n*). Each owner choice has options and a recommendation, and the prototype lets you switch between the options. + +| # | Decision | Recommendation | +|---|---|---| +| **BQ1** | **Bubble layout.** It is fixed and never reorders. Groups, with three separators: `Style ▾ │ B I U S ‹› Tx │ A▁▾ 🔗 🖌 │ 💬`. 💬 is present only where `canComment()` is true, at the trailing edge, so its absence never shifts anything else (§6). | Approve | +| **O1** | **Block type in the bubble.** (a) one **Style ▾** menu, also called "Turn into": Text, H1–H3, More headings ▸, Bulleted, Numbered, Task, Quote, Code block. (b) Two menus, **H ▾** and **List ▾**, as in the reference. (c) None, as today. | **(a)**: one decision, one target, and the face shows the current type | +| **O2** | **Colour menu.** (a) Today's swatch grid, plus a **live caption** naming the pointed or focused swatch, and a "Recent" row. (b) **Named rows** like the reference: Default plus five curated colours, then "More colours ▸" for the other five. Highlight the same way. | **(b) on every desktop surface**, the bubble and the row: one concept per job (dp principle 2). **Phones keep the grid**, with a caption naming the current value and a pill that names each applied colour, with Undo. Touch has no hover, so the caption can't name a swatch before it is tapped (§7.3). | +| **O3** | **Comment slot.** cm:467 says "last in the bubble"; the design pass ends with 🖌. Put 💬 after 🖌 and gate it on `canComment()`. | Approve as written. This amends dp:25. | +| **O4** | **Reactions.** (a) None in v1, as comments C12 has it. (b) A reaction is a comment thread whose first message is one emoji: no new storage, rendered as an emoji chip in the margin. (c) Dedicated `r:` keys in the `comments` map, with validator changes. | **(a) now, (b) as v1.1 candidate** | +| **O5** | **Desktop quick insert.** (a) A `+` button on the empty line under the caret (and on hover). Clicking it types the "/" for you, so it opens the ordinary "/" menu (§8.2). (b) A floating bottom pill like the reference. (c) Nothing new beyond the "Type / for blocks" placeholder (OB2). | **(a) + (c)**. (b) is rejected for desktop (§8.4). | +| **O6** | **Phone Insert.** (a) The Insert cell opens a bottom **sheet**: a two-column grid with icons and labels, built from the "/" menu's items. An optional Suggested section sits on top; the fixed sections below never move. 44 px targets. (b) Keep today's dropdown. | **(a)** | +| **O7** | **Keyboard selections.** (a) Show the bubble, as today. (b) Show it only after Shift is released and the selection has settled for 300 ms. (c) Never show it for keyboard selections; Alt+F10 still opens it. | **(b)** | +| **O8** | **Touch tablets (≥ 768 px, coarse pointer).** (a) Keep "no bubble, the row only" (ph:47), but give the row's stand-ins a fixed word: **Format**, **Layout** and **Block**. (b) A selection bar docked at the bottom, made of the phone selection cells. It needs a real-iPad spike for the iOS callout. | **(a) now; spike (b)** | +| **O9** | **Page width.** It is **not** a quick-access item. It goes in the row's ⋯ under a new "View" group and in the palette, routed to the preferences spec's `page.width` and `doc.width` (§9). "Make page wide" becomes the "Page width ▸" submenu. | Approve | +| **O10** | **Motion token.** One token for every editor popover, including the bubble: enter 120 ms (opacity, scale 0.98 → 1, `cubic-bezier(0.2,0,0,1)`); exit 80 ms (opacity, linear). Under reduced motion, no animation. This amends tb:116 (140/90 ms). | Approve | +| **BQ2** | **Engineering.** The bubble stops using Tiptap's React ``, which calls `registerPlugin` from the lazy chunk. Instead, the lazy chunk listens to editor events and positions with `@floating-ui/dom`, which is already one shared copy in the editor chunk. The editor-chunk change is a **measured gate**, expected ≤ 0 B; the bubble chunk should shrink (§4.1, §12). | Approve. This is phase 0 and ships first, on its own. | +| **BQ3** | **Anchor to the first selected line**, never the union rectangle (§10.1). The bubble and its menus **never cover the selection**. They may cover the line above it, as any bubble does. | Approve | +| **BQ4** | **The row's ⋯ becomes three labelled groups:** Text, View, Help, with "Forget my choices…" on its own at the end (§9.2). Nothing is removed. | Approve | +| **BQ5** | **Toggle (details) and Date blocks** are **out of this design's scope.** Both are schema additions (allowlist first, schema floor). They get their own spec if wanted. | Approve | +| **O11** | **Bubble shape** (second reference set: Notion's vertical panel). (a) **One row**, as in BQ1, plus Tx (clear formatting). (b) A **vertical sectioned panel**: a "Turn into" row with a side submenu; a 5 × 2 grid of marks; a Comment row; no AI section. | **(a)**. (b) covers 8–10 lines of the writer's context and doesn't fit above a selection in a 720 px window (§7.8). The prototype has both. | +| **BQ6** | **Clear formatting (Tx, ⌘\\) joins the bubble's marks group**, after ‹›. It keeps links, as the registry's `format.clear` does today. | Approve | +| **BQ7** | **No AI or "Skills" slot,** and no reserved space for one (§7.9). | Approve | +| **BQ8** | **Chrome follows the interface direction; position follows the text.** Item order, submenu side and arrow keys follow ``. The anchor follows the selected text's geometry, whatever its direction (§13.4). | Approve | +| **BQ10** | **Every bubble action keeps a twin in the row** (the bubble-in-row matrix test stays as it is). The row's Style ▾ gains **Quote** and **Code block** as conversions (today they are only inserts). 💬's twin is the row's **Insert › Comment** (cm:469), shown where `canComment()` is true. | Approve | +| **BQ11** | **One word per block type everywhere:** "Text" (the row's "Normal text" face becomes "Text"). Faces abbreviate headings to H1–H6 for width; menus and accessible names use the full label ("Heading 2"). | Approve | +| **O12** | **"/" menu, Suggested section.** (a) Up to 3 recent **insert kinds**, from the existing `INSERT_KIND_CHOICE`, with its `maxRecent` raised from 0 to 3. That is local only, never Yjs, and adds no new slot or write path. (b) A new `recentBlocks` slot written by every `style.*`, `list.*` and `insert.*` `run()`. (c) No Suggested section. | **(a)** (§8.5) | +| **BQ9** | **"/" menu details:** an inline "Type to search" ghost after the "/" (no search field, so focus never leaves the editor); a pinned footer with the highlighted row's Markdown tip and **Close menu · esc**; "New" badges that expire on a fixed date or on first use, with no storage (§8.5). | Approve | + +**On approval, these other specs change:** + +| Spec | Section | Change | +|---|---|---| +| Smart toolbar design | tb:116 | Bubble contents, timing (O10), anchor (BQ3) and attachment (BQ2) | +| Design pass | dp:25 | Bubble order: Style ▾ and S ‹› added; 💬 after 🖌 (O3) | +| Desktop UX | ux:679 | Its popover motion token now also covers the bubble, "/" and `+` (O10) | +| Phones and tablets | ph:47 | Touch tablets get stand-in words (O8 a) | +| Phones and tablets | Aa sheet | Style moves first (§13.1) | +| Phones and tablets | Insert cell | Opens a sheet (O6) | +| Comments | cm:467 | Confirmed: 💬 is last, after 🖌; a comment-only bubble in reading mode (§7.2) | +| v1 contract | §5.2, §6 | The DOM contract is unchanged (root attached on show, removed on hide). `BUBBLE_KEY` meta goes away (BQ2). `INSERT_KIND_CHOICE.maxRecent` 0 → 3 (O12). Both are recorded as amendment A18. | +| v1 contract | §5.1 (D1's row files) | The row's Style ▾ face says "Text", and the menu gains Quote and Code block as conversions (BQ10, BQ11). | +| Documents and editor details | dt:276 ("already strong, don't rebuild") | The "/" menu gains Suggested, the ghost hint, the footer and badges. These are amendments, not a rebuild (§8.5). | +| Comments | cm:469, §11 | The row's Insert › Comment is 💬's twin (BQ10). The draft card gains a "Suggest a change" toggle into P4.12's suggested replacement (§7.6). | +| Preferences | web ⋯ › Page… | Becomes ⋯ › View › Page width ▸ (O9, BQ4). | + +--- + +## 3. Is the reference TinyDocy? + +**No.** TinyDocy has no comment button, no reaction button, no H ▾ in the bubble, no list ▾ in the bubble, no floating bottom pill, no Date or Toggle block, and no "Make page wide". + +The reference is most likely Claude's Docs artifact viewer. Its public UI uses the same strings: "Make page wide", "Back to default width" and "Page is wide". It also ships an emoji picker and a comment rail. This identification is *[unverified]* visually. We use it only as a reference for interaction. We copy no code and no look. + +| Reference element | TinyDocy today | This design | +|---|---|---| +| 💬 comment in the bubble | none (comments not built) | 💬 trailing, `canComment()` only (O3) | +| ☺+ reaction in the bubble | none, and no spec | none in v1 (O4) | +| H3 ▾ in the bubble | row Style ▾ only | Style ▾ in the bubble (O1) | +| B I U S | B I U (S only in the row) | B I U S | +| `{}` inline code | ⋯ › Inline code | ‹› in the bubble | +| Palette ▾: Text section (Default + 5) and Highlight section (None + Yellow), named rows, ✓ on the current value | split face + a grid of 11 unlabelled swatches per section | named rows in the bubble (O2) | +| List ▾ in the bubble | row List ▾ | inside Style ▾ (O1) | +| Link | Link (opens the Hyperlink popover) | Link, with focus in the field on the first frame and a crossfade. In v1 it opens below the selection, because the package fixes the side (§7.5). | +| Bottom pill: Tt, table, image, checklist, toggle, ⋯ | phone bar: Undo, Aa, B, I, List ▾, Indent, Insert ▾ | desktop `+` on the empty line (O5); phone Insert sheet (O6) | +| ⋯: Bulleted, Numbered, Quote, Code block, Divider, Date, Make page wide | Insert: Image, Embed, Table, Quote, Code block, Diagram ▸, Divider | Insert unchanged; page width moves to ⋯ › Page (O9) | + +--- + +### 3.1 The second reference set: Notion + +The owner later added Notion's selection menu, Turn into, colour popover and "/" menu, all in dark mode over a Persian document. Notion's **interface stays LTR** while the text is RTL: +- the menu order is unchanged; +- the Turn-into submenu opens to the right; +- the "/" list aligns to the "/" at the left of the ghost. + +That separates two directions that this spec keeps apart (BQ8): the **interface** direction drives chrome, and the **content** direction drives anchoring. + +| Notion element | This design | +|---|---| +| Vertical sectioned panel | Considered as O11 b; one row recommended (§7.8) | +| "Normal Text ›" turn-into row with a side submenu | Style ▾ face word + menu (§7.4); the side submenu is used only in O11 b | +| Tx clear formatting, top level | Tx in the bubble (BQ6) | +| √x inline equation, ⋯ | No math in the schema; Superscript and Subscript stay in the row's ⋯ | +| Comment row + ☺+ + suggest-edit | 💬 trailing (O3); reactions O4; "Suggest a change" inside the comment card, which is comments P4.12's suggested replacement (§7.6) | +| Skills / Edit with AI | No AI slot (BQ7, §7.9) | +| Colour: Recently used, then a 5 × 2 text grid, then a 5 × 2 background grid | Recent first, then named rows in two columns (§7.3) | +| "/" ghost "Type to search", Suggested with a "New" badge, Markdown hints, "Close menu · esc" footer | §8.5 (O12, BQ9) | + +## 4. Current state: audit + +The screens are in `docs/design/2026-11-17-bubble-quick-insert/current/`. The file names below are relative to that folder. + +### 4.1 Engineering finding: the bubble registers a plugin from a lazy chunk + +**What the code does:** +- `components/smart-toolbar/bubble/selection-bubble-view.tsx` renders Tiptap's React ``. +- That component calls `editor.registerPlugin()` when it mounts and `unregisterPlugin()` when it unmounts (`@tiptap/react` 3.33.1, `src/menus/BubbleMenu.tsx:107,116`; *source*). +- `registerPlugin` reconfigures the state, and `updatePluginViews` destroys and rebuilds every plugin view when the plugin list changes (`@tiptap/core` `Editor.ts:407-417`, `prosemirror-view` `index.ts:256-267`; *source*). +- AGENTS.md says "never `registerPlugin` from a lazy chunk (it re-creates every plugin view)". + +**Measured** with a temporary Playwright probe: +- Setup: `next dev`, Chromium, a 200-paragraph document. The bubble chunk was held with `holdChunk`, then released. +- Before the release: 159 plugins and 29 plugin views. +- After it: 160 plugins and 30 views. **0 of 29 view objects were reused.** +- `view.updateState` took 0.5–0.6 ms in three runs. +- No transaction was dispatched, and the DOM was kept. y-tiptap's `_forceRerender` would replace the whole document, but this repo's `collaboration-render-once.ts:96-101` guard stops it. + +**How much this matters (corrected by the staff review):** +- **Every tab switch already rebuilds all plugin views.** Tiptap's `EditorContent` registers `mobileEnterPlugin` on each mount (`EditorContent.tsx:149,176`), and tabs remount the editor (`key={activeTabId}`). +- **The bubble adds** one late rebuild when its chunk lands, and one more at unmount. Its views tear down **after** the editor is already interactive. +- **The views that hold state:** + - heading drag; + - heading filter; + - heading fold (already mitigated with `keepViewOnReconfigure`); + - the hyperlink hover card; + - remote carets (yCursor); + - y-undo. Its `manager.destroy()` is undone by Collaboration's restore patch (`collaboration.ts:180-200`). +- The slash trigger and the TOC have no views. +- **Severity:** + - It is a rule violation with a small, real cost: a late rebuild while the writer may already be hovering a drag handle or a link card. + - It is **not** a performance problem. + - It is the cause of the `requestAnimationFrame` re-append workaround at lines 207–222 of that file. +- **The mitigations stay after BQ2:** `keepViewOnReconfigure`, the fold reschedule and the render-once guard. `mobileEnterPlugin` keeps rebuilding views on every mount, which is outside this design (§17). + +**Fix:** BQ2 (§12). + +### 4.2 The bubble on desktop + +Screens: `desktop-*-02-bubble`, `-03-bubble-colour`, `-11-narrow-bubble`, `-12-bubble-title` and `-14-alt-f10`. + +| # | Finding | Evidence | Severity | +|---|---|---|---| +| F1 | **No block type.** To make a selected line a heading or a list, the writer leaves the selection for the row, which can be far away. | 02 | High | +| F2 | **No Strike, no inline code.** Strike is in the row. Inline code sits in ⋯ beside Superscript, three clicks away. | 02, 07 | Medium | +| F3 | **The anchor is the union rectangle.** On a selection that starts mid-paragraph on its second line, the bubble centres on the union box. It covers the heading above, and its left edge sits left of the selected text. | 14 | High | +| F4 | **The colour popover is a grid of 11 + 11 "A" swatches with no visible names.** Names are only in `aria-label` and tooltips. Telling red, orange and pink apart, or a pale highlight from none, depends on seeing the colour (WCAG 1.4.1 risk). The ✓ badge sits on the swatch's corner. | 03 (both themes) | Medium | +| F5 | **The colour popover opens upward from a bubble that is already above the text.** The stack (popover, bubble) covers three lines of context above the selection and reaches the sticky row. | 03 | Low | +| F6 | **Keyboard selections open the bubble too.** Shift+Arrow shows it, and every further Shift+Arrow moves it. Word shows its mini toolbar only for mouse selections. | 14 | Low (O7) | +| F7 | **Link is a context switch.** Clicking 🔗 closes the bubble and opens the Hyperlink extension's own popover below the text, with a field and Apply. On a link, the hover card offers copy, edit and unlink, but no "open". | 15, 16 | Medium | +| F8 | **The title gets the full bubble**, which is correct. The row shows "Title" with a lock, but the bubble shows no hint that colour applies and size does not. | 12 | Low | +| F9 | **Good, and to keep:** hidden on typing, in code and in links; Alt+F10 lands on B, whose tooltip reads "Bold **text** ⌘B"; Esc returns with the selection; flips below the sticky row and remote caret labels; colour hover preview; recent colours. | 14 | — | + +### 4.3 Quick insert on desktop + +Screens: `desktop-light-06-insert-menu`, `-07-more-menu`, `-08-slash`, `-09-slash-query` and `-10-palette`. + +| # | Finding | Severity | +|---|---|---| +| F10 | **`+ Insert` sits at the far end of the row, top right.** It is the one block-insertion control a mouse user can find, and it is the farthest from the caret. Its rows show no shortcut or "/" hint. | Medium | +| F11 | **The three insert lists overlap but differ.** Insert has 7 kinds. List ▾ has 3 lists. "/" has Text, Lists, Insert and Diagrams. A writer who learned "/" finds headings and lists there, and not in Insert. | Low | +| F12 | **"/" is strong, but has three gaps against the second reference set:** no Suggested section, no hint in the line that it filters, and no close affordance for pointer users. Beyond those, **"/" is strong.** It has sections, Markdown hints (`#`, `##`, `-`, `1.`, `[ ]`), H4–H6 for search only, combobox semantics without `aria-expanded`, a polite live region, and flips above. Keep it. It is on the "already strong" list (dt:276). Its one gap is **finding it**: the placeholder says "Type something…", not "/". | Low | +| F13 | **The row's ⋯ mixes four kinds of thing.** Marks (Superscript, Subscript, Inline code), tools (Clear formatting, Paint format), memory (Forget my choices), help (All actions… ⌥/) and preferences (Simplified toolbar, Appearance ▸). | Medium | +| F14 | **The palette is good.** Its sections, shortcuts and ✓ states all come from the registry. | — | + +### 4.4 Phone (390 and 320 px, touch) + +Screens: `phone-*-01-bar`, `-02-selection-cells`, `-03-format-sheet`, `-04-insert`, `-05-slash` and `phone320-dark-02-selection`. + +| # | Finding | Severity | +|---|---|---| +| F15 | **Insert is a desktop dropdown anchored to the bar's last cell.** It covers the right half of the text. The presence pill's "1 use…" shows through at its left edge, which is a stacking-order bug. The rows are 44 px tall, but there are no recent items and no grid. | Medium | +| F16 | **The Aa sheet leads with 22 colour swatches.** Style (Normal text, H1…) starts below the fold of a sheet that covers about 60% of the screen. Style is used more than colour. | Medium | +| F17 | **The selection cells are good**: B I U A▁ ✎▁ 🔗 🖌 ✕, no scrolling. At 320 px, U moves to the sheet as designed. | — | +| F18 | **Two floating pills stack over the text above the bar**: presence, then Discord, GitHub and Privacy. Any phone quick-access design must not add a third. This is out of scope here; see the follow-ups (§15). | Low | +| F19 | **"/" works on phones** (44 px rows, above the bar). It has no non-typed twin near the caret, and on Arabic-101 and old Hebrew layouts "/" is not on the first keyboard page (Appendix A). | Low | + +### 4.5 Touch tablet (820 px, touch) + +Screen: `tablet-light-02-selection`. + +| # | Finding | Severity | +|---|---|---| +| F20 | **A selection shows nothing near the text** (by design, ph:47). The row at this width uses stand-ins whose icons don't explain themselves: `T ▾` (Aa), `¶ ▾` (paragraph) and `⫶ ▾` (slot). | Medium (O8) | + +### 4.6 Spec conflicts found + +These are already approved, and they disagree with each other. +1. The last slot in the bubble: the comments spec says 💬 (cm:467); the design pass says 🖌 (dp:25). Resolved by O3. +2. Motion: the bubble has 140/90 ms (tb:116); desktop popovers have 120/80 ms (ux:679); the pill 150 ms; sheets 200 ms; comment cards 120 ms. Resolved by O10, for editor popovers only. Sheets keep 200 ms. +3. Comments C11, §8 and CR7 still quote "the 600 B allowance", which D23 replaced. This spec quotes D23. + +--- + +## 5. Research summary + +The full digest, with sources, is Appendix A. These are the patterns that shaped the design. + +**Adopted:** +1. **The bubble holds only selection-scoped actions; block creation lives at the caret.** Notion, Craft, Linear, Medium. +2. **The block type is one control whose face shows the current type:** Notion's "Text ⌄", Coda's type tile, the reference's "H3 ⌄". +3. **One colour menu with labelled Text and Highlight sections**, an explicit Default and No highlight, and ✓ on the current value: the reference, Notion. +4. **Comment is the one collaboration verb on a selection**, with ⌥⌘M. Google Docs, Linear, Notion, Outline, Paper. +5. **No floating bubble on touch.** Phones use a bar above the keyboard, and its "+" swaps the keyboard for a block grid. Notion, Apple Notes and Pages, Bear, Paper. +6. **Every bubble action has a second route:** the row, a shortcut, the palette or a menu. Google Docs pairs its margin pill with Insert › Comment and Ctrl+Alt+M. +7. **A selection inside a code block, an IME composition or a drag hides the bubble.** Lexical; Confluence's IME bug as the counter-example. +8. **APG toolbar:** one Tab stop, arrows, Alt+F10 to enter (CKEditor precedent), Esc back. +9. **Anchor to the selected line, not the union box.** Floating UI `inline()`. + +**Rejected:** +1. **A floating insert pill on desktop.** It duplicates the sticky row, collides with the presence, footer and status pills, and covers the bottom lines while typing (WCAG 2.4.11). See §8.4. +2. **Usage-adaptive ordering.** Already rejected (tb:24); fixed faces stay. +3. **AI or promo buttons in the bubble.** Confluence's "Ask Rovo" drew heavy complaints. +4. **Reactions on whole blocks only.** Linear. If reactions come, they anchor to text like comments (O4b). +5. **Medium's repeat-click cycling** (one T button that cycles H → sub → plain). It is a changing face, which conflicts with dp principle 1. + +--- + +## 6. Principles + +1. **Three surfaces, one registry.** The bubble formats *this text*. Quick insert makes *a new block here*. The row and the palette hold *everything*. Every item in the bubble and in quick insert is also in the row or the palette, and the bubble-in-row matrix test stays. +2. **Fixed layout per context kind.** Nothing reorders by usage. An item that can't run is disabled with a reason. An item that never applies in this *document kind* (💬 in the sandbox) is absent, because the kind doesn't change while the document is open (ph:323). +3. **Near the caret, not near the chrome.** The two most frequent decisions, block type and insert, get a control within reach of the text. +4. **Never cover what the writer is working on.** Don't cover the selection, the caret line, a remote caret label or the focused control (WCAG 2.4.11). +5. **Zero eager bytes.** Every new surface is lazy. Nothing calls `registerPlugin` after the editor exists. Nothing subscribes the editor shell to editor state (D23, AGENTS.md). +6. **Names over swatches.** A colour is always shown with its name, either visible or in a live caption (WCAG 1.4.1). +7. **Platform-native where the platform has a convention:** the iOS callout, Android's floating toolbar, Electron's native context menu with spellcheck and Writing Tools. + +--- + +## 7. The selection bubble (desktop and fine pointer) + +### 7.1 Anatomy (BQ1, O1 a, O2 b, O3) + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ H2 ▾ │ B I U S ‹› Tx │ A▁▾ 🔗 🖌 │ 💬 │ +└──────────────────────────────────────────────────────────────────────┘ + style marks + clear colour link paint comment (canComment only) +``` + +| Slot | Control | Registry id | Face | Tooltip (fine pointer) | +|---|---|---|---|---| +| 1 | **Style ▾** (menu button) | `style.*`, `list.*`, `insert.quote`, `insert.codeBlock` | The current type as one fixed word: `Text`, `H1`–`H6`, `Title`, `List`, `Quote`, or `Mixed`. Width is fixed per locale, at least 64 px (§7.1 Sizes), so the face never moves the other items. | "Turn into" | +| 2 | Bold | `mark.bold` | B | Bold **text** ⌘B | +| 3 | Italic | `mark.italic` | I | Italic *text* ⌘I | +| 4 | Underline | `mark.underline` | U | Underline ⌘U | +| 5 | Strike | `mark.strike` | S | Strike ~~text~~ ⌘⇧S | +| 6 | Inline code | `mark.inlineCode` | ‹› | Inline code \`text\` ⌘E | +| 6b | Clear formatting (BQ6) | `format.clear` | Tx `RemoveFormatting` | Clear formatting ⌘\\ (keeps links) | +| 7 | **Colour** (split) | `color.text.apply`, `color.highlight.apply`, `*.unset` | A▁ shows the last text colour; ▾ opens the menu (§7.3) | Text colour: Red (the last colour, applied on click) | +| 8 | Link | `mark.link` | 🔗 | Link ⌘K | +| 9 | Paint format | `paint.*` (existing) | 🖌 | Paint format · Select text after clicking · Esc to cancel | +| 10 | Comment | `comment.add` (comments PR P4.10) | 💬 `MessageSquarePlus` | Comment ⌥⌘M (macOS) / Comment (other OSes: menu only, cm:466) | + +**Sizes:** +- Buttons are 28 × 28 px with 2 px gaps. +- The colour split's ▾ is **24 px** wide. At 18 px it would fail 2.5.8's spacing exception. +- Separators are 1 px with 4 px margins. +- **Style face width** is the longest face word in the active locale, measured once at mount, with a minimum of 64 px and `padding-inline: 8px 4px`. If a translated word would make it wider than 96 px, the face shows the type's icon plus a chevron instead of the word. The face never reflows while open. +- Measured in the prototype: 433 × 38 px with 💬, 392 × 38 px without. §16 keeps these as a screenshot check, not a hard number. + +**Shape and colour:** +- Radius `--radius` (0.45 rem) and `shadow-md`. +- **Light:** background `--popover`; the edge is `oklch(0.87 0 0)`, chosen on looks. +- **Dark:** a scoped `--bubble-surface: oklch(0.24 0 0)` for the bubble and its menus, with an edge of `oklch(1 0 0 / 36%)`. Today `--popover` and `--card` are both 0.205, so the bubble has no fill contrast against the page (UI review). +- **1.4.11 does not rest on the edge.** Measured: `oklch(0.80)` against the white card is only 1.87:1, and reaching 3:1 would need L ≤ 0.669, which is too heavy. Each control is identified by its own glyph. The parts 1.4.11 does cover are: + - the **focus ring**: `--focus-ring`, 7.8:1 in light and 12.1:1 in dark, drawn **inside** each button (`outline-offset: -2px`) so it never overlaps a neighbour across the 2 px gap; + - the **pressed bar**: `--foreground` on the surface, about 19.8:1. +- **Mixed** state is a 2 + 2 + 2 px dashed bar, never the same solid bar in grey. +- **Forced colours:** the edge is `CanvasText`, pressed is `Highlight`, and swatch chips keep their colour with `forced-color-adjust: none` (the chip only). + +**What is deliberately not in the bubble:** +- Size: headings scale on their own, and the stepper stays in the row. +- Align and indent: they apply to whole blocks, not the selected text. +- Superscript and subscript: rare; they stay in ⋯ and the palette. +- Lists as a separate menu: they are in Style ▾. +- AI: there isn't any. + +**Why 💬 is last** (O3): +- Its presence depends on the document kind: off in the sandbox and the Playground, on in library and desktop documents. At the end, its absence shifts nothing. +- cm:467 already asks for "last". +- Comment is about the text, not formatting, and the separator says so. + +### 7.2 Context variants (fixed per kind) + +| Context | What changes | Why | +|---|---|---| +| Paragraph | — | | +| Heading H1–H6 | Style face `H2`. All marks apply. | | +| **Title** (first H1) | Style face `Title`, menu disabled: "Title is always H1." Everything else as normal. | Schema title-first | +| List item | Style face `List`. The menu ✓s the current list type. | | +| Task item | Style face `List` with Task ✓. | | +| Blockquote | Style face `Quote`. | | +| **Selection across blocks of different types** | Style face `Mixed`. Choosing a type converts every selected block, as one undo step through the registry. | | +| **Selection across a list and paragraphs** | Same as Mixed. Converting to a list wraps every top-level block; Text unwraps. | `toggleList` semantics | +| Table cell (text selection) | As a paragraph. **CellSelection** spanning cells: **no bubble**, as today. The row's table slot handles cells. | | +| Inside inline code | Bubble shows. `inlineCode` has `excludes: "_"`, which excludes every mark, link and colour included. So B, I, U, S, colour, 🔗 and 🖌 are disabled with the reason "Inline code can't take other formatting." `setMark`'s `can()` already says no (`setMark.ts:60`, registry `inline.ts:217`). Tx, Style ▾ and 💬 stay enabled. | schema | +| ‹› over linked or coloured text | Applying inline code **removes** the link and colour marks in the range (`addMark` drops excluded marks). The pill says "Link and colour removed", with Undo. | schema | +| **Code block or Mermaid** | No bubble, as today. | | +| **Both ends inside one link** | No bubble. The link hover card takes over, as today. | | +| Part link, part plain text | Bubble shows. 🔗 is pressed and mixed (`aria-pressed="mixed"`). | | +| Node selection (image, embed, divider, Mermaid) | No bubble. The row's media slot handles it. | | +| **Whitespace-only selection** | No bubble. Change: today "no text" counts, so a selection of spaces shows it. | Lexical | +| **Read-only, outdated or deleted document** | No bubble. | #308 | +| **Reading mode with comments allowed** (cm:278) | A **comment-only bubble**: 💬 alone, same position rules. | cm:278 | +| View-link holder | No bubble. They read comments and never write (C5). | | +| Playground and web sandbox | No 💬. Everything else as normal. | C6 | +| During an IME composition | Never shows, moves or hides mid-composition. It re-evaluates on `compositionend`. | Confluence IME bug | +| During a pointer drag | Shows on `pointerup`, not while the drag extends. | Lexical, Word | +| Keyboard selection (O7 b) | Shows 300 ms after the last Shift keyup with a settled, non-empty selection. Never on auto-repeat. Alt+F10 still opens it at once. | Word Mini toolbar | +| Select all (⌘A) | Shows, anchored to the **first selected line that is visible** (§10.1), not to the top of the document. Style face `Mixed`. Turn into skips the title; the pill says "The title stays a heading." | | +| Selection scrolled out of view | Hidden. It comes back when any selected line is visible again. | Today's `hide` | +| Paint format armed | The bubble stays and 🖌 shows pressed. The next selection applies the format, then the bubble shows for that selection. | dp:41–63 | +| A collaborator deletes the selected text | Hidden. The selection maps to empty. | | +| A collaborator edits elsewhere | Repositions only if the anchor rectangle moved, at most once per animation frame. | | +| A collaborator converts or deletes the block while Style ▾ or Colour is open | The face and ✓ may be stale for a frame. A pick revalidates against the live doc (`runAction` does). If the selection maps to empty, the menus close and focus returns to the editor, never `body`. | contract §3.2 | +| The document turns read-only while a menu or the link field is open (`document_too_large`, the 512 KiB offline pause, deleted) | Everything closes. The pill gives the reason (#308). A typed but unapplied URL is dropped, and the pill says so. | #308 | +| Selection spans a table and paragraphs | Turn into skips the table cells. The pill says "Table cells keep their type." | | +| Turn into Code block | Marks and links in the range are removed (code holds plain text). The pill says "Formatting removed", with Undo. Comment anchors survive, because they are relative positions on the text (cm C2). | | +| Turn into Text on nested list items | The selected items become paragraphs at the top level, in order. The children of unselected items stay where they are (`toggleList` lift). | | +| Undo after Turn into | One step. The Yjs UndoManager restores the selection, and the bubble shows again. A collaborator's typing in between stays (only local steps are undone). | | +| Very long selection | The face is computed once per snapshot (`ctx.memo`), and it stops at the second distinct block type, so the cost is O(blocks until two types differ). | | +| Paint armed, then Style ▾ or Colour | They work and Paint stays armed. The Paint bundle carries marks only, never the block type (dp:41). | | +| Part-link selection, then 🔗 | The link field opens with the existing address. Apply extends the link to the whole selection; Remove removes it from the selection. *[unverified]* that the Hyperlink package supports both; phase 1 checks. | | +| Right-click on a selection (web and desktop) | The bubble hides while the context menu is open, and comes back on close if the selection is unchanged. | | + +### 7.3 Colour and highlight (O2) + +**Bubble (O2 b, named rows).** The colour split's ▾ opens a menu with **two columns side by side**. Stacked, the sections would be about 480 px tall; side by side they are about 290 px, which fits above or below a selection in a 720 px window. + +``` +Recent: A A ▆ A ▆ ← up to 5, first row, from the existing M3 memory (MAX_RECENT_COLORS = 5), text and highlight mixed +─────────────────────┬────────────────────── +Text │ Highlight +⊘ Default ✓ │ ⊘ No highlight ✓ +■ Red │ ■ Yellow +■ Orange │ ■ Green +■ Green │ ■ Blue +■ Blue │ ■ Pink +■ Purple │ More highlights ▸ → Gray, Brown, Red, Orange, Teal, Purple + More colours ▸ │ +``` + +**Chips** use one visual language on every surface: +- a **text colour** is an 18 px tile with an "A" in the token colour; +- a **highlight** is an 18 px tile filled with the highlight, with a `--foreground` "A"; +- **Default** and **No highlight** use lucide `Ban`. + +A solid square for a text colour would read as a highlight (UI review). **Recent** comes first, as in Notion's menu, because repeating a recent colour is the most common pick. + +**Keyboard:** Up and Down move within a column. Left and Right cross to the same row in the other column, in visual order in RTL. → on "More…" opens the submenu. + +**Which colours show first.** The first five per section are chosen for contrast spread and common meaning: +- Text: red (warning), orange, green (done), blue (info), purple. +- Highlight: yellow (the classic), green, blue, pink. + +The token list (`TEXT_COLOR_TOKENS`) is append-only and unchanged. This is only a **display order** constant in the lazy menu chunk. + +**Behaviour:** +- ✓ marks the current value. A mixed selection gets no ✓ and shows a `–` on the section label. +- The rows are `menuitemradio` inside two `group`s, so arrow keys move through both groups in order. +- The hover preview (A14) works on rows exactly as on swatches: `setActionPreview` on pointer enter and on focus. +- ⌘⇧H re-applies the last highlight (ux:501). + +**The row's colour menus** use the same named rows. Its two split buttons (text, highlight) each open their own column's rows plus Recent. This replaces today's grid on desktop. + +**Phone Aa sheet** keeps the grid: 44 px swatches, a 10 px gap, and six per row (6 × 44 + 5 × 10 = 314 px). Under the grid, a caption names the **current** value. Each tap shows a pill naming what was applied ("Teal text"), with Undo. A hover caption can't work on touch, because the name would arrive only after the tap applied the colour. + +**Dark mode.** The swatches render with the dark palette values (Appendix A of the toolbar spec). Highlight rows show the swatch on `--popover`, so a pale highlight is visible in both themes. + +### 7.4 Style ▾ ("Turn into") (O1 a) + +``` +Turn into +T Text ⌘⌥0 ✓ +H1 Heading 1 ⌘⌥1 +H2 Heading 2 ⌘⌥2 +H3 Heading 3 ⌘⌥3 +H More headings ▸ → H4, H5, H6 +───────── +• Bulleted list ⌘⇧8 +1. Numbered list ⌘⇧7 +☐ Task list ⌘⇧9 +───────── +❝ Quote ⌘⇧B +‹› Code block ⌘⌥C +``` + +**Columns:** +- Icon, then label. +- Shortcut, `kbd dir="ltr"`, then ✓, always the trailing cell: `grid-template-columns: 16px 1fr auto 16px`. +- **No Markdown chips here.** They teach in the "/" menu (§8.5), where typing is the point, and three clustered items per row read as noise (UI review). +- No hints at all on coarse pointers (dp:152). + +**Behaviour:** +- **One undo step** per pick, through `runAction`. +- In the title, the menu is disabled with the reason "Title is always H1." +- In a heading, list types stay enabled. The registry decides, as `toggleList` from a heading does today. +- **Mixed selection:** no ✓. +- The menu body is in the **menus chunk** (A13), next to the row's Style menu. **Phase 1 checks** that the bubble chunk can import it without pulling the menus chunk into the editor group (A13's MenuRoot lesson). + +**Why one menu (O1 a), not H ▾ plus List ▾ (O1 b):** +- A block has one type. A heading can't also be a bulleted item without a nested paragraph. +- Two menus on one block suggest you can pick one from each. +- One menu is also one target fewer. Notion's "Turn into" works this way. + +### 7.5 Link (§F7) + +- **🔗 with no link in the selection:** the bubble **hands off in place.** + - **Focus moves to the field in the same frame as the click.** Otherwise a writer who clicks 🔗 and types or pastes at once would be typing into the editor, over the selection (UX review). + - The bubble and popover **crossfade** (both 120 ms) instead of running in sequence. + - **Placement:** the Hyperlink package hard-codes `placement: "bottom"` against the selection's rectangle (`openCreateHyperlink`, package dist), and `reposition()` can't change the side. So: + - **v1:** the popover opens **below the selection**, as today. It never covers the selection. When the bubble was above, the handoff moves down a line, and the crossfade makes that read as one motion. + - **Later:** ask `@docs.plus` for a `placement`/reference option. With it, the popover's edge nearest the text pins to the bubble's, which keeps it in place when the bubble was below. + - Enter applies. Esc returns to the editor with the selection, and the bubble comes back. + - Test: click 🔗, paste at once, and the selected text is unchanged. + - The popover stays the extension's own (contract §4: `mark.link` is only a trigger). + - What changes is where it opens. Today it opens below the text. +- **Pasting a URL over a selection** makes a link. `linkOnPaste` is on: the package default is true and `document-editor-config.ts:199-212` doesn't override it (staff review). Phase 1 adds e2e tests: one for a web URL, and one for a media URL, which `shouldAutoLink` vetoes. Pasting a URL alone keeps today's behaviour (autolink). +- **A selection inside a link:** the hover card (copy, edit, unlink). **Ask the package owner for an "Open" (↗) action**; it is a request to `@docs.plus`, not a change here. +- ⌘K keeps working everywhere. Later (search-linking spec, LK1) the ⌘K popover gains Documents and "In this document" sections. This design doesn't change that. + +### 7.6 Comment entry (O3, comments spec §11.1) + +- 💬 runs `comment.add`. It opens the draft card beside the range, tints the range as a draft, and moves focus to the card (cm:473). The bubble hides while the card has focus. Esc in the card returns focus to the editor with the selection collapsed to the end of the range (cm:476). +- The tooltip copy is the comments spec's: "Comment (⌥⌘M)" on macOS (cm:583). +- Anywhere `canComment()` is false, 💬 is **absent, not disabled**, because the document kind doesn't change while it is open. A view-link holder sees no bubble at all (C5). +- The bubble takes no comment code. 💬 is an `ActionButton` for a registry id that the comments PR registers. Before then, `editorActions.has("comment.add")` is false and the slot renders nothing (contract §3.2). +- **Ordering dependency:** comments PR P4.10 depends on "the smart toolbar bubble" (cm:635). Phase 1 here lands first. +- **Suggest a change** (Notion's suggest-edit icon) is **not a second bubble button.** It is a toggle in the comment draft card, "Suggest a change", which turns the card into the comments spec's suggested replacement (P4.12, the v1 stand-in for suggestion mode, rm:336). The card prefills the selected text for editing. That keeps one collaboration verb, 💬, in the bubble. + +### 7.7 Reactions (O4) + +- **Recommended: none in v1.** C12 scopes comments to "no mentions, no notifications"; reactions are new scope. The prototype shows the slot only under O4 b. +- **If O4 b is chosen later** (v1.1): ☺+ sits **inside the 💬 group** and opens an emoji picker with six quick emoji and a search. + - The pick creates a thread whose first message is one emoji, flagged `reaction: true` in the message JSON. That is a new optional field in a `m:` value, so the comments validator must accept it before any client writes it (C9). + - It renders as an emoji chip in the margin, not as a card. + - The emoji picker data is its own lazy chunk (about 30–60 KB gz for emoji data, *[unverified]*), never in the bubble chunk. + +--- + +### 7.8 One row or a vertical panel? (O11) + +The owner's second reference set shows Notion's selection menu, in dark mode over a Persian document. From top to bottom it has: +- a "Normal Text ›" row, which opens Turn into to the side; +- a 5 × 2 icon grid: A, B, I, U, Tx / link, S, code, √x, ⋯; +- a "Comment" row with ☺+ and a suggest-edit icon; +- a scrolling "Skills" list (Improve writing, Proofread, Explain, Reformat…); +- a pinned "Edit with AI" row. + +Its colour popover has three sections: Recently used, Text colour as a 5 × 2 grid, and Background colour as a 5 × 2 grid. + +| | (a) One row (recommended) | (b) Vertical panel | +|---|---|---| +| Size | 433 × 38 px with 💬, 392 px without (measured in the prototype) | about 240 × 220 px without AI (Notion's is about 340 × 600 px with Skills) | +| Covers | One line of text above the selection | 6–9 lines, usually including the paragraph the writer is checking the change against | +| Fits above the selection in a 720 px window | Always (§10.1) | Often not. It then overlaps the selection's own block or flips far below | +| Remote carets and labels | Rarely covered; the flip rule handles them | Often covered | +| Room for words | Only the Style ▾ face word | Labelled rows (Turn into, Comment) | +| Growth | Fixed; anything new goes to the row, ⋯ or the palette | Invites new sections. Notion's Skills list is how panels grow | +| Pointer travel to B | 1 row | 2 rows | +| Keyboard | One toolbar, Left/Right | A menu with a grid inside: Up/Down between sections, 2-D arrows in the grid. Harder to learn, and a mixed APG pattern (§14) | + +**Recommendation: (a).** The reasons: +- TinyDocy's bubble formats the text the writer is looking at, and a panel hides that text. +- The panel's real advantage is room for words and sections. That room is what makes AI skills and promotional rows easy to add, and §7.9 rules those out. + +**What (a) borrows from the panel:** +- Tx (clear formatting) is top level (BQ6). +- Turn into shows the current type as a word (Style ▾ face). +- Comment sits in its own trailing group. +- Recently used colours come first in the colour menu (§7.3). +- The suggest-edit entry lives *inside* the comment card (§7.6), not as a second bubble button. + +The prototype's "O11" switch shows (b) built from the same items, so the owner can compare. + +**If (b) is chosen,** these rules apply: +- Turn into is the first row, and its submenu opens toward the interface's inline end (BQ8). +- Marks are a 5 × 2 grid with roving focus that is 2-D. Left and Right follow the visual order in RTL. +- Comment is a labelled row. +- There is no Skills section. +- The panel anchors to the first selected line, and flips with the same rules (§10.1). + +### 7.9 AI and "Skills" (BQ7) + +TinyDocy has no AI, and none of the v1 or post-v1 roadmap specs has any. This design: +- **Reserves no AI slot,** not even a disabled or "coming soon" one. An empty slot is a changing face, and a teaser is a promotional button. Confluence's un-dismissable "Ask Rovo" button is the cautionary example (Appendix A). +- **Says where AI would go if the owner ever decides to add it,** so nobody squeezes it into the bubble later: + - as **registry actions** in their own group, so they appear in the palette (Alt+/) and the "/" menu with labels, shortcuts and reasons like everything else; + - **behind a preference** that is off by default, as prefs principle 2 requires; + - in the bubble, at most **one** trailing item ("Ask…"), after 💬, that opens a lazy panel. Never a list of skills inside the bubble. + - Any AI feature also needs its own privacy, abuse and cost review, which is outside this design. + +### 7.10 Two-level menus from the bubble: keyboard + +These rules cover Style ▾ › More headings ▸ and Colour › More colours ▸. They also cover option (b)'s Turn into ▸. + +| Key | In the bubble | In a menu | In a submenu | +|---|---|---|---| +| Left / Right | Previous / next item (visual order) | In the colour menu, crosses columns; elsewhere nothing | — | +| Inline-end arrow (→ LTR, ← RTL) | — | On a "▸" row: opens the submenu and focuses its ✓ item, or else its first | — | +| Inline-start arrow (← LTR, → RTL) | — | — | Closes the submenu; focus returns to its "▸" row | +| Up / Down | — | Next / previous row, wrapping | Next / previous row, wrapping | +| Enter / Space | Activates; on a menu button, opens it and focuses its ✓ item | Picks and closes everything; focus returns to the editor with the selection | Same | +| Esc | Back to the editor with the selection | Closes this menu; focus returns to its trigger in the bubble | Closes the submenu only | +| Tab | Leaves the bubble for the editor (today) | Closes the menus and leaves the bubble for the editor | Same | +| Typing a letter | — | Moves to the next row starting with it (typeahead, APG menu) | Same | + +**Pointer:** a submenu opens on hover after 100 ms, or on click. A pointer moving diagonally toward an open submenu doesn't close it; Base UI's submenu safe-polygon handles that. A submenu that doesn't fit at the inline end opens at the inline start (§10.4). + +## 8. Quick insert + +### 8.1 Model + +| Where | Entry | Opens | +|---|---|---| +| Desktop, empty line | **`+` in the start margin** (O5 a), keyboard-free | Types the "/" for you, so it is the ordinary "/" menu (§8.2) | +| Desktop, anywhere | "/" typed at a block's start or after a space (unchanged) | The "/" list at the caret | +| Desktop, row | `+ Insert ▾` (unchanged, M10 face) | Insert menu | +| Desktop, keyboard | Alt+/ palette (unchanged) | Everything | +| Phone | Insert cell in the bar (O6) | **Insert sheet** | +| Phone | "/" (unchanged, ph:49) | The "/" list above the bar | +| Electron | the menu bar's Insert menu (ux §4) | The same kinds | + +The "/" list is the **one** list of block kinds, and the `+` reuses it **as is**, so there is no second mode and the lists can't drift apart. The phone Insert sheet renders the same items in a grid (§8.5). The row's Insert menu stays as M10 decided: inserts only, with lists in List ▾. Its rows gain the "/" alias as a hint, for example "Table /table". + +### 8.2 The `+` on the empty line (O5 a) + +**When it shows:** +- On a fine pointer, while the caret is in an **empty paragraph** that is not the title, not in a table cell and not in a list item. +- Also on pointer hover over an empty paragraph, after a **150 ms dwell**, only on the hovered line and never animated. Documents with many spacer paragraphs then don't shimmer as the pointer passes. +- Hidden from IME `compositionstart` until `compositionend`, along with the placeholder. +- It never shows on coarse pointers; phones have the Insert cell. +- The empty list item, quote and table cell cases are open, and the default is no. They have their own Enter behaviour. + +**Where it sits:** +- In the start margin, 28 × 28 px, vertically centred on the line. +- It lines up with the drag grip column on headings, so the margin has one column of controls. +- In RTL it is in the right margin. + +**Behaviour:** +- **Click inserts a "/" for you.** It moves the caret into that paragraph if it isn't there, then inserts "/" with `addToHistory: false`. That is exactly what the trigger watches for (one local "/" at the block start), so the ordinary "/" menu opens with its ghost hint. Typing after a click filters, as it would after a typed "/". Only one code path exists. + - **Esc after a `+`-opened menu** removes the "/" again, also outside the history, if the query is still empty. A pick replaces "/query" as today. + - The `+` has `aria-haspopup="listbox"` and the name "Insert block". +- It **is not in the Tab order.** Keyboard users already have "/" and Alt+/, and a Tab stop on every empty line would be noise. It has an accessible name, "Insert block", and a tooltip: "Insert block · or type /". +- Picking runs `runSlashPick` as one undo step. Focus never leaves the editor. +- **Empty or title-only document:** the title never gets a `+`. Enter from the title makes the first paragraph, which shows the placeholder and the `+`. + +**Engineering:** +- It lives in the **slash chunk**, which is already loaded on idle. +- It listens to `editor.on("transaction" | "focus" | "blur")` from that chunk. There is no plugin. +- **A little eager JSX in `SlashMenuHost`** (about 100–200 B, estimated), because the host renders chunk code only while the menu is open. It counts **inside** the existing 1,000 B slash cap. Measure it. +- It positions with `coordsAtPos`, not Floating UI: a third chunk importing Floating UI could split the editor group again. +- Pressing the `+` calls `preventDefault` on `mousedown`, so the editor keeps focus and the trigger never sees a `blur` meta. + +**The placeholder** for an empty paragraph becomes "Type / for blocks" (OB2, 10 B, already in the D23 ledger). + +### 8.3 Phone Insert sheet (O6 a) + +``` +┌ Insert ───────────────────────── Done ┐ +│ Suggested (only with recents) │ +│ [▦ Table 3 × 3] │ +│ Turn into / Blocks │ +│ [T Text] [H1 Heading 1] │ +│ [H2 Heading 2] [H3 Heading 3] │ +│ [• Bulleted] [1. Numbered] │ +│ [☐ Task list] [❝ Quote] │ +│ Media and more │ +│ [🖼 Image] [▶ Embed] │ +│ [▦ Table] [‹› Code block] │ +│ [⑂ Diagram ▸] [— Divider] │ +└────────────────────────────────────────┘ +``` + +**Layout:** +- A bottom sheet in the existing `Sheet` component, with swipe-to-close (M7) and `--safe-area-bottom` padding. +- A two-column grid of cells 44 px tall: icon and label, start-aligned. +- **The sections are the "/" menu's sections, in its order** (§8.5), from the same item builder. + - **Suggested** is optional and on top: up to 3 recent insert kinds (O12 a). + - The fixed sections below it never move, so the first fixed cell is always in the same place. + - A kind in Suggested also appears in its own section, as in the "/" menu. +- **What a Text, heading or list cell does depends on the caret's block:** + - if the block is empty, the section is titled "Blocks" and the cell converts that block; + - if the block has text, the section is titled "Turn into" and the cell converts the block the caret is in, exactly as the Aa sheet's Style does. + - Insert kinds (table, image…) always insert after the caret's block, as `insert.*` does today. + +**Behaviour:** +- **Picking closes the sheet.** The keyboard comes back with the caret in the new block, through the existing `actionsRef.close()` and focus return. +- **Kinds that need input:** + - **Table and embed** open their step inside the sheet, through `lazySurface(loadInsertStep)`. They are the only `InsertStepKind`s (`insert-step.tsx:22`). + - **Image** opens the system file picker, as it does today. +- Disabled kinds show their reason on a second line, as in the menus (dp:207). + +**Shipping:** +- Its own chunk next to the phone sheet. It reuses `buildSlashItems` from the slash chunk's `lib/slash-menu/` (pure modules, no components). +- `phone.scss` is off-limits until PR #102 merges, so this ships after #102. + +### 8.4 Why not a bottom insert pill on desktop (O5 b, rejected) + +1. **It duplicates the sticky row**, which already has `+ Insert` and, at narrow widths, the stand-ins. +2. **It collides** at the bottom right with the presence pill and the footer pill, and the status pill moves there too when the bubble is open (dp:99). +3. **It covers the bottom lines of the page** while you type at the end of a document. Avoiding that needs `scroll-padding` changes that touch every scroll rule (`SCROLL_CLEARANCE`). +4. **Electron** puts Insert in the menu bar (ux §4), so a pill is a third copy. + +**A narrow exception, recorded for later:** +- *Simplified toolbar plus focus mode* could, one day, hide the row and show a pill. +- No such mode exists. +- Under prefs principle 2 ("a new setting must replace one, or arrive with evidence", pr:62), it is not proposed. + +--- + +### 8.5 The "/" menu (O12, BQ9) + +The "/" menu is on the "already strong, don't rebuild" list (dt:276). This section **amends** it and does not rebuild it. + +**What stays:** +- The eager trigger, which keeps state only and stays under 1,000 B gz with the host. +- It opens only in a paragraph, at the block start or after whitespace. +- The query stays ordinary text in the document, and focus never leaves the editor. +- Combobox attributes go on `view.dom`, never `aria-expanded`. +- Keys are captured on the window only while the menu is open. +- A pick is one undo step (`runSlashPick`). +- The polite live region. +- H4–H6 are search-only. +- Disabled items explain themselves only when the query matches nothing else. +- The flip rules. + +**Reference:** Notion's "/" menu, dark mode, Persian document. It shows an inline "/ Type to search" ghost at the caret; "Suggested" (with a "New" badge) above "Basic blocks"; Markdown hints at the end of each row; and a pinned "Close menu · esc" footer. + +#### Anatomy (empty query) + +``` +/ Type to search ← ghost hint at the caret (empty query only) +┌──────────────────────────────────────────┐ +│ Suggested │ ← only with recents (O12 a) +│ ▦ Table 3 × 3 │ +│ ⑂ Diagram ▸ New │ +│ Text │ +│ T Text │ +│ H1 Heading 1 # │ +│ H2 Heading 2 ## │ +│ H3 Heading 3 ### │ +│ Lists │ +│ • Bulleted list - │ +│ 1. Numbered list 1. │ +│ ☐ Task list [ ] │ +│ Insert │ +│ ❝ Quote > │ +│ ‹› Code block ``` │ +│ ▦ Table 3 × 3 │ +│ 🖼 Image · ▶ Embed · ⑂ Diagram ▸ · — Divider │ +├──────────────────────────────────────────┤ +│ Type ## then space for Heading 2 esc Close │ ← pinned footer +└──────────────────────────────────────────┘ +``` + +#### Sections and order + +The order is **Suggested → Text → Lists → Insert → Diagrams** (Diagrams appears only when the templates are loaded, as today). +- **Suggested (O12 a)** holds up to 3 recent **insert kinds**, most recent first, read from `INSERT_KIND_CHOICE`. + - The slot's `maxRecent` goes from 0 to 3. That is a **v1 contract amendment** (§6, D2's memory file), recorded as A18. Its `last` value, which the row's Insert face reads, is unchanged. The stored shape stays compatible: the plan's first task checks that `readChoice` accepts both the old and the new shape. + - **Local only.** It lives in the existing `tinydocy-ui` memory, never in Yjs. Forget clears it, and `NEXT_PUBLIC_REMEMBER_CHOICES=0` disables it. + - **No new write path.** The insert actions' `run()` already writes this slot (contract §6). + - With no recents, the section is absent, so a new writer sees the same list every time. + - An item in Suggested also stays in its own section, because positions in the sections never move (fixed faces). +- **Why not (b), recents for every block type?** Headings and lists already have Markdown shortcuts and sit at the top of the list. Recording every `style.*` run (⌘⌥2 too) would fill Suggested with "Heading 2", and it would need eager write calls in the editor chunk. +- **With a query,** Suggested is not shown. Ranking is today's `matchSlashItems`, plus a tie-break: among equal ranks, a recent kind comes first. + +#### Empty-query hint (BQ9) + +- **Inline ghost:** "Type to search" sits right after the "/" while the query is empty. It is **not** a search field, so focus stays in the editor and the query stays document text. +- **How it renders:** + - The lazy menu renders it as an `aria-hidden` overlay at `coordsAtPos(head)`, in the paragraph's computed font and `--muted-foreground`. + - It is not a decoration, so it costs no eager bytes. +- **When it shows:** only when nothing follows the caret in the block, so it never overlaps the writer's text. Mid-line, the footer carries the hint instead ("Type to filter"). +- **When it hides:** on the first query character, on IME composition start, and when the menu closes. + +#### Teaching Markdown shortcuts + +- **Every row** keeps its Markdown hint at the inline end, as today. +- **The footer's start text** follows the highlighted row: + - a row with a Markdown hint: "Type `##` then space for Heading 2"; + - a row without one: "↑ ↓ to move · ↵ to insert". +- **No counters, no nags, no stored state.** The tip changes as the writer arrows. +- **Coarse pointers:** the footer tip is hidden (dp:152); only Close stays. + +#### "New" badges (BQ9) + +- **Declared** on the menu's own item table (a lazy chunk), as `newUntil: "YYYY-MM-DD"`, with **at most two items at a time**. +- **Hidden when:** + - the date has passed (local date), **or** + - the kind is in `INSERT_KIND_CHOICE`'s recents, which means this writer has used it. +- **No new storage,** and no server. +- **Accessible name:** the label gets ", new" (for example "Diagram, new"). +- **Ships empty.** The first feature that wants a badge sets a date at most 60 days after its release. + +#### Close affordance + +- **Esc** closes and leaves "/query" as text (today). +- The footer's **"Close · esc"** is a button for pointer users. It does the same, and keeps the caret where it was. +- **On phones** it is a 44 px "Close" button, the only footer item. +- **Clicking outside** closes it too (today). + +#### Placement + +Unchanged from today: +- below the "/" when it fits, else above if there is more room; +- the side sticks while typing; +- always inside the band between the sticky row and the phone bar or keyboard (`SCROLL_CLEARANCE`); +- never over the caret line. + +Changes: +- **Width** goes from 288 to **320 px**, to fit a badge, a note and a hint. +- **Below 640 px** the list still spans the screen with a 16 px gutter. +- **The footer is outside the scrolling list,** so it is always visible. A tall list scrolls under it, ending in a half row so the cut-off shows there is more (today's rule). + +#### RTL (BQ8) + +- **The list's chrome follows the interface direction:** label at the start, hint at the end, and the footer's tip and Close mirrored. +- **Horizontal anchor:** the list aligns to the "/" on the **content's** start side. + - In an RTL paragraph its right edge sits at the caret. + - In an LTR paragraph under a Persian interface, its left edge sits at the caret. + - It is clamped to the page column. +- **Markdown hints and the "/" stay `dir="ltr"`** (rtl:184). +- **Arabic and old-Hebrew layouts** don't have "/" on the base layer. Use the `+` (desktop) and the Insert cell (phones). No second trigger character (§13.4). + +#### Phone + +- "/" keeps working above the bar (ph:49), with 44 px rows. +- Suggested and the footer apply, but the footer is only Close. +- **The Insert sheet (O6) is the tap path, and it uses the same item builder.** `buildSlashItems` gains a `layout: "list" | "grid"` render mode. The sheet's sections are therefore the menu's sections, in the same order. +- The UX-review finding that "Recent first" would move the first cell is resolved the same way: Suggested is a separate, optional section at the top. The fixed sections below it never move. + +#### One registry, three surfaces + +Labels, icons, shortcuts, Markdown hints, keywords and disabled reasons come from `lib/editor-actions` alone. Each surface keeps only: +- which ids it shows; +- its sections and order; +- its badges; +- its display-only colour order (§7.3). + +| Surface | Reads | Renders with | +|---|---|---| +| Bubble | a const id list (§7.1) + `useActionView` | `ActionButton` | +| Style ▾ / Turn into | `style.*`, `list.*`, `insert.quote`, `insert.codeBlock` | menu rows: `label`, `icon`, `formatKeyCombo(shortcut)`, `markdownHint` | +| "/" menu, `+` popover, phone Insert sheet | `buildSlashItems(ctx, editorActions.list(), …)` | one item model, two layouts | +| Row Insert | `editorActions.list({ group: "insert" })` (today) | menu rows plus the "/" alias as a hint | +| Palette | the whole registry (today) | cmdk rows | + +**A new contract test** checks three things: +1. Every id any surface names exists in the registry. +2. No surface file contains a hard-coded label or shortcut string for a registry id. The check is a grep for the labels of the ids each surface names. +3. Every `markdownHint` shown in the "/" menu matches the input rule that the Markdown shortcut actually triggers. This last check is a **unit test against the real input rules** in a test editor. + +## 9. Page-level actions (O9) and the row's ⋯ (BQ4) + +### 9.1 Page width + +- **"Make page wide" is a per-viewer view preference, never a document edit.** Prefs rows 7–8: + - `page.width` is the app default: Narrow 30 em / Standard 33 em / Wide 46 em / Full. + - `doc.width` is per document, per viewer and per device, and exists on desktop and in the web library only. It is never written to Yjs. + - Below 640 px the page always fills the width. +- **So it doesn't belong in quick insert.** It goes where the preferences spec puts it: the Page popover, Settings › Page, View › Page Width on desktop, and the palette. +- On the web it goes in **the row's ⋯ › Page width ▸**: + - Narrow, Standard, Wide, Full, with a ✓ on the current one. + - "Use default (Standard)" when a per-document width is set, in the web library only. + - In the sandbox, the item sets the app-wide `ui.page.width` (C7). +- The copy follows the preferences spec's labels, not the reference's "Make page wide". +- **Shortcut:** none. It is changed rarely, and every key is spoken for. + +### 9.2 The row's ⋯, regrouped (BQ4) + +``` +Text + Superscript ⌘. + Subscript ⌘, (⌘⇧, on desktop, ux:462) + Inline code ⌘E + Clear formatting ⌘\ + Paint format +───────── +View + Page width ▸ Narrow · Standard ✓ · Wide · Full + ☐ Simplified toolbar + Appearance ▸ +───────── +Help + All actions… ⌥/ +───────── +Forget my choices… +``` + +- Nothing is added except Page width, and nothing is removed. "Forget my choices…" stands alone at the end: it is about memory, not help. +- Every row keeps a 16 px leading slot (icon or ✓/☐), so the labels line up. +- The groups are `role="group"` with `aria-label` and visible headings, matching the colour menu. +- Inline code stays in ⋯ as a second route (principle 1), even though it is now in the bubble. +- **Phone:** the Aa sheet gains a **Page** row (the preferences spec's name) (ph:77) only where width can change: at 640 px and wider, which phones never reach. So phones get no width control. That is correct, because the page always fills the width there. + +--- + +## 10. Placement and collision + +### 10.1 Anchor (BQ3) + +1. **The anchor rectangle is the first selected line's rectangle.** That is the first `DOMRect` of `range.getClientRects()` with a non-zero width, clipped to the selected part of that line. It is never the union box. + - For a forward multi-line selection, this is the top line, where the selection started. + - For a backward selection, it is still the top line, so the bubble doesn't jump to the bottom when you drag upward. + - Floating UI's `inline()` middleware does this. +2. **Horizontal:** centred on the anchor, then shifted to stay 8 px inside the **page column** (`.document-editor-content`), not the window. That keeps it out of the comment rail and the outline. +3. **Vertical:** + - **Above** the anchor, 8 px gap. + - Flip **below the last selected line** when any of these hold: + - (a) the band above starts under the sticky row (today's `topLimit`); + - (b) it overlaps a remote caret label (today); + - (c) it would be less than 8 px from the top of the visual viewport, when the window is short. + - The side, once chosen, **sticks for the life of that selection**. Typing, remote edits and scrolling never flip it back and forth. It is re-chosen only when the anchor moves more than 24 px or the band becomes blocked. + +### 10.2 Layers (z-order, low to high) + +`page text < remote carets < drag grip and + < status pill < bubble < bubble menus and popovers (portalled) < comment draft card < sheets and dialogs < toasts`. + +- The **status pill** moves beside the bubble when the bubble is open (dp:99, unchanged). +- The **comment rail** is outside the page column, so the bubble never overlaps it (§10.1 rule 2). +- The **presence and footer pills** are below the bubble in z-order and never move. The bubble can't reach them, because it sits next to text in the page column. + +### 10.3 Scrolling, resizing and zoom + +- The bubble lives in the scroll container (`.document-editor-wrapper`) and scrolls with the text without repositioning, as today. +- **Window resize, Electron zoom (⌘±, desktop only) and font loading** reposition it on the next frame. Linear shipped a fix for exactly this. +- **Sticky row covering:** when the bubble goes wholly under the sticky row while scrolling, it reads as `closed` for Alt+F10, and focus moves back to the editor (today's rule, kept). + +### 10.4 Menus from the bubble + +- Style ▾ and Colour ▾ open **on the side away from the text**: up when the bubble is above, down when it is below (today's `popoverSide`). +- **When the preferred side has less than `min(menu height, 240 px)` of room** in the band between the sticky row and the window's bottom, the menu opens on the other side. On that side it goes **below the selection's last line**, never over the selection, and its height is capped to the room with internal scrolling. + - The prototype shows this: on a heading near the top, Style ▾ opens under the heading. +- **Menus and submenus are bounded by the page column,** like the bubble (§10.1 rule 2), so they never land on the comment rail. A submenu that doesn't fit at the inline end opens at the inline start, over its parent menu, offset 4 px. Every menu is also clamped to the visual viewport with 8 px padding. +- While a menu is open, the bubble stays: today's `OPEN_POPOVER_TRIGGER` rule. + +--- + +## 11. Motion, shortcuts and hints + +### 11.1 Motion (O10) + +| What | Enter | Exit | Reduced motion | +|---|---|---|---| +| Bubble, its menus, the "/" list (also when opened by `+`), Insert, ⋯ | 120 ms, opacity 0→1, scale 0.98→1 from the anchor side, `cubic-bezier(0.2,0,0,1)` | 80 ms, opacity only (no scale), linear | none (instant) | +| Bubble repositioning | none, it jumps | — | — | +| Link handoff (§7.5) | crossfade, both 120 ms; focus moves in frame 1 | — | instant swap | +| Phone sheets | 200 ms slide (ph:257, unchanged) | 160 ms | no slide, fade 0 | +| Hover preview | none (it is a decoration) | — | — | + +**Rules:** +- **Never delay showing for an animation.** The bubble is interactive from frame 1. +- Reduced motion follows `data-motion="reduce"` **or** `prefers-reduced-motion`, through the preferences spec's one mixin (pr:773). + +### 11.2 Shortcuts and hints + +- **The registry is the source.** Tooltips show `label · Markdown hint · formatKeyCombo`, as the bubble does today ("Bold **text** ⌘B"). `aria-keyshortcuts` comes from `ariaKeyShortcuts`. +- **Coarse pointers:** no tooltips and no glyphs (dp:152). On an iPad, glyphs come back after the first hardware-keyboard modifier press (ph:379, `data-hardware-keyboard`). +- **`kbd dir="ltr"` always.** Glyphs are never translated (rtl:184). +- **New keys: none.** Everything in §7 already has one: ⌘B, I and U; ⌘⇧S; ⌘E; ⌘K; ⌘⌥0–6; ⌘⇧7, 8 and 9; ⌘⇧B; ⌘⌥C; ⌘⇧H; ⌥⌘M (macOS, from comments). +- **Teaching Alt+F10:** the palette's row "Focus formatting toolbar Alt+F10" already exists. Nothing new pops up. + +--- + +## 12. Engineering (BQ2) and budgets + +### 12.1 How the bubble attaches + +**Today:** +- An eager host, `selection-bubble.tsx`, lazy-loads `selection-bubble-view.tsx`. +- That view renders ``, which registers a plugin (§4.1). + +**Proposed:** a `BubbleController` in the lazy bubble chunk, one per editor. + +- **One `transaction` listener**, not `transaction` plus `selectionUpdate`. Both fire on every keystroke (`Editor.ts:730-740`). The handler starts with `if (!open && selection.empty) return`, which is cheaper than today's plugin `update`, whose `doc.eq` is O(top-level blocks). +- **Listeners for `focus`, `blur` and `update`.** `update` catches `setEditable`, which emits no transaction (`slash-menu-host.tsx:37`). +- **DOM listeners:** + - a capture `mousedown` on the bubble (`preventHide`); + - `dragstart` on `view.dom`, which hides; + - `pointerdown`/`pointerup`, for show-on-pointerup; + - `compositionstart`/`compositionend`. +- **What it reproduces from Tiptap's plugin** (`bubble-menu-plugin.ts`): + - the **250 ms show debounce** for a non-empty selection (`updateDelay`, :378); hide stays immediate; + - the `view.composing` skip and a `compositionend` re-check (:432, :589); + - the `relatedTarget` blur rules (:464-484); + - a `setTimeout` on focus so the selection has settled (:459); + - hide on `dragstart` (:427). +- **`shouldShowBubble()`** (`bubble-rules.ts`) is kept as a pure function, with its unit tests. It gains `isWhitespaceOnly` and a `firstVisibleLineRect` helper. +- **Position:** + - `@floating-ui/dom` `computePosition` with `offset(8)`, `shift({ padding: 8, boundary: page column })` and the side logic in §10.1. + - `autoUpdate` runs only while open, with `contextElement: view.dom` and **`ancestorScroll: false`**, because the bubble scrolls with the text inside the scroll container (§10.3). + - The **anchor comes from the viewport**, not `inline()` over the whole range. It is the first selected line rectangle that intersects the visible scroll area. `getClientRects` over a ⌘A range would lay out every `content-visibility`-skipped block, and `inline()` would anchor to an off-screen first line. +- **Caching:** while open, `textBetween`, whitespace and block-type checks are cached per `(state.doc, selection)` identity. Remote transactions are coalesced to one check per animation frame. The controller never caches DOM nodes or `Range`s, because remote Yjs steps replace whole blocks; it recomputes from positions. +- **The DOM contract is kept exactly:** + - one reused root element with `data-smart-bubble` and `data-state`; + - **appended to the scroll container on show and removed synchronously on hide**, as the plugin does today. + - About 15 e2e `toHaveCount(0)` assertions depend on it, and the status pill's observer needs the root as a direct child (`status-pill.tsx:29,106-133`). + - Removing it synchronously also ends the A9 rAF race, so lines 207–222 go. +- **No `registerPlugin`, `PluginKey` or `reconfigure`.** Nothing else uses `BUBBLE_KEY` (checked). +- **Lifecycle:** + - one controller per editor in a `WeakMap`; + - teardown is idempotent (editor `destroy` and the host's unmount may both run, and StrictMode runs effects twice), deletes its entry and removes the root synchronously. + - The contract §7 gate stays: listeners and heap back at baseline after 100 bubble cycles and 20 tab switches. +- **Electron and the web:** a `contextmenu` event hides the bubble. It comes back on close if the selection is unchanged. + +### 12.2 Budgets + +**Editor-chunk bytes are a measurement gate, not a promise.** Turbopack groups modules by the chunks that use them. A8 measured about 968 B of editor-group files when the bubble first imported the split button. Rules: +- Pass eager helpers in as props, as the continue chip does. The bubble chunk should import only modules the editor group already has, or its own folder. +- `scripts/check-editor-chunk-size.ts` runs on every phase. Growth over noise (±16 B) needs a D23 ledger amendment, approved before merge. + +| Surface | Chunk | Expected editor-chunk change | +|---|---|---| +| Bubble controller (BQ2) | bubble chunk | ≤ 0 B. The bubble chunk itself should **shrink**: `@tiptap/extension-bubble-menu` (729 lines) leaves. `@floating-ui/dom` is already one shared copy (1.8.0) in the editor chunk (`heading-drag`, the `@docs.plus` packages), so no duplicate is added. | +| Bubble v2 items: Style ▾ face, S, ‹›, Tx, 💬 slot | bubble chunk | ≤ 0 B. Measure: Style ▾ is the bubble's first use of `lazy-menu`/`action-menu`. | +| Turn-into menu body | menus chunk (A13), a new body (lists, quote, code; no Your formats) with side and anchor options (`ToolbarMenu` has neither today, `menu-items.tsx:53`) | measure | +| Colour named rows | colour chunk | 0 B | +| `+` on the empty line | slash chunk, plus **a little eager JSX in `SlashMenuHost`**, which renders chunk code only while the menu is open | about +100–200 B (estimate), **inside** the 1,000 B slash cap; measure | +| "/" Suggested, ghost hint, footer, badges | slash chunk; `INSERT_KIND_CHOICE.maxRecent` 0 → 3 is one constant | 0 to +4 B | +| Phone Insert sheet | phone chunk; the table and embed steps load only through `lazySurface(loadInsertStep)` (A9 measured +1.5 KB when phone imported menus statically) | 0 B | +| ⋯ regroup and Page width | menus chunk | 0 B | +| Comment button | comments PR's own ledger line (150 B) | — | + +### 12.3 Typing performance + +- **With no bubble open,** each keystroke costs one `transaction` callback and two field reads. +- **With the bubble open,** remote transactions cost one cached check per animation frame. +- **The `+`** listens only while the caret is in an empty paragraph. Typing elsewhere exits after one `parent.content.size` check. + - It doesn't show again until 300 ms after the last keystroke, so Enter-Enter doesn't make it flicker. + - It re-measures on `transaction` while shown, because a fold or a remote edit above moves it. + - Hover detection reads the DOM at most once per animation frame. The Placeholder decorates only the caret's node, so hover can't rely on its class. +- **Gate:** the perf project shows typing p95 within +10% with the bubble chunk loaded (tb:183), on 50 and 500 headings. + +## 13. Phone, tablet, desktop and RTL + +### 13.1 Phone (< 768 px) + +- **No floating bubble**, unchanged. The selection cells `B I U A▁ ✎▁ 🔗 🖌|💬 ✕` stay, with 🖌 swapped for 💬 where `canComment()` is true (ph:318). +- **Aa sheet order (amends the sheet layout, F16):** + 1. **Style** (Text, H1–H3, More ▸; Bulleted, Numbered, Task, Quote) as a two-column grid. + 2. **Colours** as the 44 px grid with the current-value caption and the applied-colour pill (§7.3). + - The Style section shows the current type as pressed and has a **More headings ▸** row, as today's sheet does. + - The sheet pads `calc(16px + var(--safe-area-bottom))` at the bottom and shows a 16 px fade when it scrolls. + - Done, swipe-down and a tap on the scrim all close it. + 3. Size, Align, and the rest, as today. +- **Insert:** the sheet (O6). +- "/" is unchanged. +- **Keyboard:** the bar rides `--keyboard-inset` (M20). The sheet replaces the keyboard while open, as today. + +### 13.2 Tablet (≥ 768 px) + +- **Fine pointer** (iPad with trackpad, Surface with mouse): the desktop bubble. The bubble keys on `pointerType`, not width (ph:380). A trackpad selection shows the bubble; a finger selection on the same device doesn't. +- **Coarse pointer** (O8 a): + - No bubble, unchanged. + - **The row's stand-ins get a visible word** at 768 px and wider on coarse pointers: `Aa Format ▾`, `¶ Layout ▾`, `⋯ Block ▾`. "Text" would collide with the Style value, and "Paragraph" reads as a block type (UX review). That follows the fixed-faces rule: one icon plus at most one fixed word (ux:46). +- **O8 b spike** (not built): on a real iPad, show the phone selection cells as a bar docked at the bottom while text is selected. Measure: + - whether the iOS callout and the WebKit r241971 avoidance stay clear of it; + - whether the hardware keyboard's shortcut bar collides with it. +- **iPad with a hardware keyboard:** Alt+F10 isn't available (Safari's Option+F10). ⌘ shortcuts work, and glyphs come back (ph:379). + +### 13.3 Desktop (Electron) + +- **The bubble is identical to the web.** +- **The native context menu stays native** (ux:256): spelling suggestions, Cut, Copy, Paste, Look Up, Link…, and Comment… (cm:468). + - The bubble **hides while the native context menu is open** (`contextmenu` event) and comes back on its close if the selection is unchanged. + - Writing Tools and Services need `menu.popup({ frame })` (Electron 36+). That is the desktop track's work; this spec only depends on the bubble hiding. +- **The menu bar** mirrors the registry (ux:220): + - Format: marks, Turn into ▸, Clear formatting. + - Insert: the same kinds as "/", plus Comment. + - View: Page Width ▸ (prefs). +- **Narrow windows** (the minimum width, ux): with a fine pointer below the phone breakpoint, the window is a phone layout with a mouse. + - Today the bubble is disabled there (`DESKTOP_QUERY`). + - Keep that: the phone bar is the formatting surface at that width, and with a fine pointer its cells are mouse-sized. +- **⌘, is Settings**, so Subscript is ⌘⇧, (ux:462). Labels come from the registry, so the bubble needs no change. + +### 13.4 RTL + +- **The bubble order reverses** through logical layout: Style ▾ at the right, 💬 at the left (rtl:290). +- **Keys:** Left and Right move visually through `visualStep()` (rtl:330); `bubble-rules.ts` is one of its six call sites. +- **Icons:** + - ▾ chevrons and the More ▸ chevrons flip, through `flipInRtl` in `lib/icons.tsx`. + - These don't flip: B, I, U, S, ‹›, 🔗, 🖌, 💬, and the colour A. + - List icons in Style ▾ flip; `ListOrdered` uses `ListOrderedRtl` (rtl:312). +- **Menus** open toward the inline start, with Floating UI `start` and `end` placements (rtl:293). +- **The `+`** sits in the right margin. +- **Anchor:** with bidi runs on the first line, `getClientRects()` returns several rectangles for that line. The anchor is their union **on that line only**. +- **"/" on RTL keyboards:** + - On Persian ISIRI 9147 it is on the same key as US (Shift gives ؟), so it works. + - On Arabic 101 and old Hebrew SI-1452, "/" isn't on the base layer. + - We **don't add a second trigger character.** That costs eager bytes in `slash-trigger.ts`, and LK3's `[[` already claims the next slot. Instead, the `+` on desktop and the Insert cell on phones are the non-typed paths. +- **Persian decimal "/":** the trigger opens only at a block's start or after a space (unchanged), so "۳/۵" never opens it. +- **Labels** go through `actionLabel(action)` (rtl:159). The link field is `dir="auto"`. + +--- + +## 14. Accessibility + +| Criterion | How | +|---|---| +| 2.1.1 Keyboard | Alt+F10 opens the bubble and focuses its first item (Style ▾), or the item focused last time in this bubble session (APG toolbar re-entry). Every bubble action also has a shortcut, the row or the palette. The `+` has "/" and Alt+/ as keyboard twins. | +| 2.4.3 Focus order | Inside the bubble: roving tabindex, Left/Right, Home/End, one Tab stop. Esc order: menu → its trigger in the bubble → editor with the selection kept → hide. Tab past the last item returns to the editor (today's rule). | +| 2.4.11 Focus not obscured | The bubble flips away from the sticky row and remote labels. It never covers the selected line (§10.1). The `+` popover clamps above the phone bar and keyboard (`SCROLL_CLEARANCE`, today's rule). | +| 2.5.8 Target size | 28 × 28 px on fine pointers and 44 × 44 px on coarse ones. Menu rows are 32 px fine and 44 px coarse. | +| 1.4.11 Non-text contrast | Controls carry the contrast: the 2 px `--focus-ring` (7.8:1 / 12.1:1), drawn inside each button, and the pressed bar (about 19.8:1). The container edge is not relied on (§7.1). **The focused or active menu row** gets an inset 2 px `--focus-ring` as well as the `--accent` fill, because `--accent` on `--popover` alone is only 1.07:1 in light and 1.19:1 in dark. This fixes the shared menu row style app-wide, not only in these menus. | +| 1.4.1 Use of colour | Colours are named in rows (O2 b) or a caption (O2 a). ✓ marks the current value. | +| 1.4.13 Hover or focus content | Tooltips and the hover preview close on Esc, can be hovered, and stay while hovered or focused (today). | +| 4.1.2 Name, role, value | The bubble is `role="toolbar"` with `aria-label="Selection formatting"`. Style ▾ and Colour ▾ are menu buttons (`aria-haspopup="menu"`, `aria-expanded`). Mark toggles use `aria-pressed`, including "mixed". The colour rows are `menuitemradio` with `aria-checked`. The `+` is `aria-haspopup="listbox"`, because it opens the "/" listbox. | +| 3.2.1 On focus | Focusing never applies anything. The hover preview is a decoration only (A14). | +| 4.1.3 Status messages | Picks announce through the existing polite live region, for example "Heading 2" or "Red text". | + +The **phone Insert sheet** is a `dialog` labelled "Insert". It has a heading per section and `role="group"` grids. Focus starts on the first Recent cell. While it is open, the page is `inert`, as with the Aa sheet. + +--- + +## 15. Phased plan (outline; the full plan follows `superpowers:writing-plans` after approval) + +| Phase | Scope | Depends on | Visible? | +|---|---|---|---| +| **P0** | BQ2: bubble controller without `registerPlugin`; BQ3 first-line anchor; whitespace-only hide; IME and drag guards. Same items as today. | — | Yes: anchor and edge contrast. UI review gate. | +| **P1** | BQ1 bubble v2: Style ▾ (O1), S, ‹›, colour named rows (O2), link handoff (§7.5), `linkOnPaste` check, empty 💬 slot, keyboard-selection timing (O7), motion token (O10) | P0 | Yes | +| **P2** | Quick insert: `+` on the empty line (O5), the "/" menu amendments (§8.5, O12, BQ9), Insert alias hints, placeholder (OB2 if not already shipped) | slash chunk | Yes | +| **P3** | Row ⋯ regroup (BQ4), Page width ▸ (O9) wired to prefs `page.width`/`doc.width` | prefs P2.9c | Yes | +| **P4** | Phone: Insert sheet (O6), Aa sheet reorder; tablet stand-in words (O8 a) | PR #102 merged (`phone.scss`) | Yes | +| **P5** | 💬 wiring: comments PR P4.10 registers `comment.add`; reading-mode comment-only bubble | comments v1 | Yes | +| **Spike** | O8 b iPad docked selection bar | real device | — | +| **Later** | O4 b reactions | owner | — | + +**Parallel tracks.** These have disjoint files: +- P2: the slash folder. +- P3: the row ⋯ files. +- P4: phone files, after #102. + +They can each run in a worktree once P0 lands. P1 owns the bubble folder. + +--- + +## 16. Tests and acceptance + +- **Unit tests:** + - `bubble-rules.ts`: whitespace-only, first-line rectangle, side stickiness, keyboard settle. + - The display-order constant contains only valid tokens. + - Every Style ▾ id is in the registry. +- **E2e:** extend `selection-bubble.spec.ts`. CI runs **Chromium**. WebKit is the by-hand project (`playwright.config.ts`), and these cases go on its manual list. CDP-only cases (IME through `Input.imeSetComposition`) are Chromium only. + - **Bubble rules:** + - no plugin is registered after the chunk loads. Assert `view.pluginViews` **identity** before and after a `holdChunk` release, as the §4.1 probe does; `plugins.length` alone can pass falsely. + - a two-line selection anchors below the heading. + - the existing `toHaveCount(0)` assertions still pass, because the root is removed on hide. + - **Style ▾:** turns a paragraph into H2, a task list and back, as one undo step each; Mixed face; Title disabled. + - **Colour:** named rows apply and preview; Recent. + - **Link:** handoff placement; paste a URL on a selection. + - **Keyboard and focus:** Shift-selection timing (O7); Alt+F10 lands on Style ▾; Esc ladder. + - **No bubble:** in reading mode, read-only, a code block, a whitespace selection, during IME (CDP `Input.imeSetComposition`) and during a drag. + - **RTL:** order and arrow keys. + - **Dark:** edge contrast ≥ 3:1 (`resolveRgb`). + - **Axe:** no serious violations in the bubble, its menus, the "/" menu with its footer, and the phone Insert sheet (`wcag22aa`). +- **"/" menu (§8.5):** + - Suggested is absent for a new writer and shows the last 3 insert kinds after use. + - Forget clears Suggested. + - The ghost shows only with an empty query and nothing after the caret, and never during IME. + - The footer tip follows the arrow keys. + - Close and Esc leave "/query" as text. + - A `+`-opened menu closed empty removes its "/" and leaves no undo step. + - A badge disappears after the date and after first use. + - The RTL anchor is on the content's start side. + - The contract test checks registry labels and Markdown hints against the input rules. +- **Perf:** typing p95 within +10% with the bubble chunk loaded (perf project). Listeners and heap at baseline after 100 bubble cycles. +- **Budget:** editor chunk +0 B per phase. +- **UI review gate:** screenshots of every state in Appendix C, in light, dark, RTL and both pointers, before each visible phase merges (memory: design review before UI merge). + +--- + +## 17. Out of scope and follow-ups + +- **`EditorContent` registers `mobileEnterPlugin` on every mount,** which rebuilds all plugin views on every tab switch (§4.1). That is a Tiptap-level behaviour; a separate investigation, not this design. +- **Toggle (details) and Date blocks (BQ5).** Each needs a schema addition, with the server allowlist first and a schema-floor review. A separate spec if the owner wants them. +- **Reactions (O4 b).** Later. +- **Phones:** the presence and footer pills over the text (F18). These belong to the shell; propose a phone placement in the phones spec. +- **Phones at 320 px:** the tab strip shows the active title as one letter ("B…") (`phone320-dark-02-selection`). Shell follow-up. +- **The Hyperlink hover card has no "Open" action** (§7.5). Request to `@docs.plus`. +- **Task checkboxes are invisible on `main`**, from Tiptap 3.33 TaskItem's styler span. This was found by the icons session (sibling notes), not here; listed so P2's Insert screenshots don't mistake it for a new bug. + +--- + +## Appendix A: Research digest + +**Sources** were checked on 2026-11-17. *[O]* marks a product observation not confirmed from a source. + +**Google Docs** +- There is no formatting bubble. A selection shows a pill in the right margin with Add comment, Add emoji reaction and Suggest edits ([help 65129](https://support.google.com/docs/answer/65129), [9to5google](https://9to5google.com/2022/04/05/google-docs-emoji-reactions/)). +- Every action in it also has another route: + - Insert › Comment and Insert › Emoji reaction; + - Ctrl+Alt+M; + - Alt+/ tool finder ([help 179738](https://support.google.com/docs/answer/179738)). +- "@" opens one list of people, files, dates and building blocks ([help 11276813](https://support.google.com/docs/answer/11276813)). +- On Android, Add comment and Add emoji reaction sit in the overflow of the system selection toolbar. + +**Apple Notes and Pages, Bear 2** +- **Notes:** an "Aa" button in the bar above the keyboard swaps the keyboard for a format panel ([iDB](https://www.idownloadblog.com/2020/10/26/format-text-quick-styles-notes-iphone/)). On a Mac there is no bubble. +- **Pages on iPhone:** a Quick Format bar above the keyboard holds styles, B/I, align, lists, date and page break. It can be turned off ([Apple](https://support.apple.com/guide/pages-iphone/tan83a228834/ios)). +- **Pages on iPad:** Comment is in the shortcut bar. +- **Bear 2:** a BIU button opens the formatting bar. Its launch had VoiceOver regressions ([podfeet](https://www.podfeet.com/blog/2023/07/bear-2/)). + +**Word** +- The desktop Mini toolbar appears on **mouse** selection, with an option to turn it off. Esc dismisses it ([MS](https://support.microsoft.com/en-US/Word/use-the-mini-toolbar-to-format-text)). +- Ctrl+Alt+M adds a comment. F6 cycles between regions. + +**Notion** +- **Bubble:** Ask AI · Comment · "Text ⌄" (turn into) · Link · B I U S · code · math · A⌄ · ⋯ *[O]*. +- **Colour:** one menu with Text and Background sections. ⌘⇧H re-applies the last colour; ⌘⇧M comments ([shortcuts](https://www.notion.com/help/keyboard-shortcuts)). +- **Mobile:** a bar above the keyboard. Its "+" swaps the keyboard for a grid of basic blocks; there is no "/" ([help](https://www.notion.com/help/writing-and-editing-basics)). + +**Craft** +- **Bubble:** highlighter ⌄ │ B I S code link math │ @ │ comment │ style ([docs](https://craft-support.mintlify.app/en/write-and-edit/formatting.md)). +- **"/" menu:** ←/→ open submenus. Dates offer Today, Tomorrow and Now ([slash menu](https://craft-support.mintlify.app/en/introduction/slash-menu.md)). +- ⌘⇧B re-applies the last colour. + +**Linear** +- **Bubble:** B I S U code link + comment (⌘⌥M). There are no colours ([editor](https://linear.app/docs/editor)). +- **"/" menu:** code, diagram, collapsible section, table, date and file. +- **Changelog fixes:** the toolbar didn't reposition on resize, was "hidden too aggressively", and opened under the side panel ([changelog](https://linear.app/changelog/2026-03-12-ui-refresh)). + +**Dropbox Paper** +- **Bubble:** Bold · Strike · Highlight · Link · Large and Medium header · Bullets · To-do · Comment ([help](https://help.dropbox.com/view-edit/formatting)). +- On mobile, highlight was reachable only through Comment. That is an anti-pattern. + +**Medium** +- **Bubble:** B i link │ T t quote. Clicking T again cycles header → subheader → plain. Link turns the bubble into an inline URL field ([help](https://help.medium.com/hc/en-us/articles/215194537)). + +**Outline** ([source](https://github.com/outline/outline/blob/main/app/editor/menus/formatting.tsx)) +- Items change with context: no marks in code, cell background in tables, indent only on touch, and Comment always. +- The highlight menu shows None only when a highlight is present, then presets, then colours already used, then Custom. + +**Lexical playground** ([source](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/plugins/FloatingTextFormatToolbarPlugin/index.tsx)) +- Hidden during IME, during a drag, on a whitespace-only selection and in code. + +**Confluence** +- Users choose between an inline and a fixed toolbar. +- Its un-dismissable "Ask Rovo" button drew heavy complaints ([community](https://community.atlassian.com/forums/Confluence-questions/how-can-i-get-rid-of-the-Ask-Rovo-popup/qaq-p/3150920)). +- The floating toolbar can't be reached by keyboard ([CONFCLOUD-85071](https://jira.atlassian.com/browse/CONFCLOUD-85071)). +- It pops up during Japanese IME input. + +**Platform** + +- **iOS Safari:** + - The text-selection callout can't be suppressed (`-webkit-touch-callout` affects links only). + - The avoidance heuristic (WebKit [r241971](https://trac.webkit.org/r241971)) has regressed on iOS 16, 17 and 26. + - The selection handles cover nearby buttons ([PM forum](https://discuss.prosemirror.net/t/unreachable-menu-item-due-to-selection-handle-on-ios/4958)). + - `interactive-widget` is unsupported (WebKit [259770](https://bugs.webkit.org/show_bug.cgi?id=259770)). Use `visualViewport`. +- **Android Chrome:** the system floating selection toolbar can't be extended by a page ([ActionMode](https://developer.android.com/reference/android/view/ActionMode)). +- **Electron:** spellcheck goes through `context-menu` params. Writing Tools and Services need `menu.popup({frame})` ([docs](https://www.electronjs.org/docs/latest/tutorial/context-menu)). +- **WAI-ARIA:** + - [Toolbar](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/), [menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) and [combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) patterns. + - On a `textbox`, `aria-activedescendant` is allowed and `aria-expanded` is not. + - NVDA with Chromium is flaky on `aria-activedescendant` in a contenteditable, so keep the live region. + - CKEditor uses Alt+F10 ([docs](https://ckeditor.com/docs/ckeditor5/latest/features/accessibility.html)). +- **RTL:** + - Apple's [RTL HIG](https://developer.apple.com/design/human-interface-guidelines/right-to-left) and Wikimedia [Codex](https://doc.wikimedia.org/codex/latest/style-guide/bidirectionality.html): flip direction and list icons, never letters, checkmarks or colour. + - Persian [ISIRI 9147](https://en.wikipedia.org/wiki/ISIRI_9147) has "/" on the US key. + - The Arabic 101 key there types ظ *[O]*. + - Old Hebrew SI-1452 has "/" on Q; SI-1452-2 moved it ([wiki](https://en.wikipedia.org/wiki/Hebrew_keyboard)). +- **Motion:** Base UI uses a 150 ms transition that can be cancelled ([handbook](https://base-ui.com/react/handbook/animation)). Apple: brief, and avoid motion on frequent interactions ([HIG](https://developer.apple.com/design/human-interface-guidelines/motion)). +- **Tiptap 3.33:** + - BubbleMenu plugin defaults: `updateDelay` 250, `resizeDelay` 60. It skips during composition. + - React `` registers and unregisters its plugin in `useEffect`. + - Its options effect dispatches `updateOptions` whenever the identity of `shouldShow` or `options` changes ([source](https://github.com/ueberdosis/tiptap/blob/main/packages/react/src/menus/BubbleMenu.tsx)). + +## Appendix B: Screenshot index (`docs/design/2026-11-17-bubble-quick-insert/current/`) + +| File | Shows | +|---|---| +| `desktop-light-02-bubble.jpg`, `desktop-dark-02-bubble.jpg` | Today's bubble on a heading selection | +| `desktop-light-03-bubble-colour.jpg`, `desktop-dark-03-bubble-colour.jpg` | Colour popover from the bubble | +| `desktop-light-14-alt-f10.jpg` | Keyboard selection on a second line, bubble over the heading, Alt+F10 focus and tooltip | +| `desktop-light-12-bubble-title.jpg` | Bubble on the title | +| `desktop-light-11-narrow-bubble.jpg` | 860 px window: row stand-ins and the bubble | +| `desktop-light-15-link-create.jpg`, `-16-link-preview.jpg` | Link popover, link hover card | +| `desktop-light-06-insert-menu.jpg`, `-07-more-menu.jpg` | Row Insert, row ⋯ | +| `desktop-light-08-slash.jpg`, `desktop-dark-09-slash-query.jpg` | "/" menu, filtered | +| `desktop-light-10-palette.jpg` | Alt+/ palette | +| `phone-light-01-bar.jpg` | Phone bar | +| `phone-*-02-selection-cells.jpg`, `phone320-dark-02-selection.jpg` | Selection cells at 390 and 320 px | +| `phone-*-03-format-sheet.jpg` | Aa sheet | +| `phone-light-04-insert.jpg` | Phone Insert dropdown (F15) | +| `phone-light-05-slash.jpg` | "/" on a phone | +| `tablet-light-02-selection.jpg` | Touch tablet selection, row stand-ins (F20) | + +## Appendix B2: Prototype screenshot index (`docs/design/2026-11-17-bubble-quick-insert/proposed/`) + +| File | Shows | +|---|---| +| `p01-bubble` | Proposed bubble on a heading: Style ▾ face "H2", marks with Tx, colour, link, paint, 💬 | +| `p02-style` | Turn into menu, opened under the heading because there's no room above | +| `p03-colour` | Two-column named colour menu with Recent first and the hover preview on the text | +| `p04-link` | Link handoff at the bubble's place, with focus in the field | +| `p05-plus`, `p06-plus-menu` | `+` on the empty line; after a click it is the "/" menu | +| `p07-slash` | "/" with a query | +| `p08-more-width` | Row ⋯ regrouped, with the Page width submenu | +| `p09-dark-comment` | Dark: comment draft card with the draft tint; page set to Wide | +| `p10-rtl-bubble` | RTL interface: mirrored order, unflipped mark glyphs | +| `p11-today` | Today's bubble, for comparison | +| `p12-phone-insert`, `p24-phone-insert-turninto` | Phone Insert sheet: Suggested, then "Blocks" or "Turn into" by caret, then Insert | +| `p13-phone-aa`, `p25-phone-aa-pill` | Aa sheet with Style first; the colour tap pill | +| `p14-tablet` | Touch-tablet row with the stand-in words | +| `p15-o1b-o2a-o4b` | The alternative options: H ▾ + List ▾, grid colours, reaction button | +| `p16-o5b` | The rejected bottom pill, colliding with the pills | +| `p17-altf10` | Alt+F10 then →: focus inside the bubble | +| `p18-o11b-panel`, `p19-o11b-turninto` | The O11 b vertical panel and its side submenu | +| `p20-dark-colour` | Dark colour menu on `--bubble-surface` | +| `p21-slash-suggested`, `p22-slash-tip` | "/" with the ghost, Suggested, the footer tip and Close | +| `p23-rtl-slash` | "/" in an RTL paragraph under an RTL interface | + +## Appendix C: State matrix for the UI review gate + +Every visible phase attaches screenshots of each cell: light and dark; LTR and RTL; fine and coarse pointer where the surface exists. + +| Surface | States | +|---|---| +| Bubble | paragraph · heading · title · list · task · quote · Mixed · part-link · inline code · two-line anchor · flipped below (sticky row) · flipped below (remote label) · menu open up · menu open down · with 💬 · without 💬 · comment-only (reading mode) · Paint armed · 860 px window · keyboard-focused (Alt+F10) | +| Style ▾ | each ✓ · Mixed · title disabled · More headings ▸ | +| Colour menu | Default ✓ · a colour ✓ · mixed · More ▸ · Recent · hover preview on text | +| Link | handoff above · handoff below · error (invalid URL, the extension's own message) | +| `+` | caret on an empty line · hover (after the dwell) · after a click (it is the "/" menu) · RTL margin | +| "/" menu | empty query with the ghost · Suggested (with recents) · without recents · a query · no match (reason note) · footer tip on a Markdown row · New badge · above the caret (no room below) · RTL paragraph · LTR paragraph under an RTL interface · phone | +| O11 b panel | only if chosen: panel · Turn into submenu at the inline end · flipped to the inline start | +| Phone | Insert sheet (Recent, all kinds, a step) · Aa sheet new order · selection cells with 💬 · 320 px | +| Tablet | coarse row with stand-in words · fine-pointer bubble | +| ⋯ | grouped · Page width ▸ (library vs sandbox) | diff --git a/eslint.config.mjs b/eslint.config.mjs index b5665bd6..05f3f6b7 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -11,6 +11,7 @@ const eslintConfig = defineConfig([ "build/**", "next-env.d.ts", "desktop/smoke/dist/**", + "desktop/storage-harness/dist/**", ]), { settings: { diff --git a/extensions/decoration-host/decoration-host.ts b/extensions/decoration-host/decoration-host.ts new file mode 100644 index 00000000..cd2eea07 --- /dev/null +++ b/extensions/decoration-host/decoration-host.ts @@ -0,0 +1,81 @@ +import { Extension } from "@tiptap/core"; +import { Plugin } from "@tiptap/pm/state"; +import { DecorationSet } from "@tiptap/pm/view"; + +export interface DecorationLayer { + /** The layer's name, e.g. "comments" or "find". */ + name: string; + /** + * Map the set through document changes (`DecorationSet.map`) instead of + * clearing it. Comments map; hits that are recomputed anyway clear. + */ + map?: boolean; +} + +export interface DecorationHostOptions { + layers: DecorationLayer[]; +} + +/** The meta every layer reads: `{ name, set }`. */ +const LAYER_META = "decorationLayer"; + +declare module "@tiptap/core" { + interface Commands { + decorationHost: { + /** + * Shows `set` (built against the current document) as layer `name`; + * `DecorationSet.empty` clears it. Meta-only: never the document, Yjs + * or undo. + */ + setDecorationLayer: (name: string, set: DecorationSet) => ReturnType; + }; + } +} + +/** + * Decoration host (details spec §1 rule 6), the `action-preview` pattern + * made general: each declared layer is one eager plugin whose only state + * is a `DecorationSet`, set by the meta-only `setDecorationLayer` command. + * All logic (finding hits, anchoring comments) lives in the layer's lazy + * chunk, which never calls `registerPlugin` (that re-creates every plugin + * view): a layer is declared here, in the extensions array, once. A local + * or remote document change maps a `map: true` layer and clears the rest. + */ +export const DecorationHost = Extension.create({ + name: "decorationHost", + + addOptions: () => ({ layers: [] }), + + addCommands: () => ({ + setDecorationLayer: + (name, set) => + ({ tr }) => { + // No steps, so no history entry and nothing for Yjs. + tr.setMeta(LAYER_META, { name, set }); + return true; + }, + }), + + addProseMirrorPlugins() { + return this.options.layers.map( + ({ name, map }) => + new Plugin({ + state: { + init: () => DecorationSet.empty, + apply(tr, set) { + const next = tr.getMeta(LAYER_META); + if (next?.name === name) return next.set; + // Mapping or clearing an empty set returns it unchanged. + if (!tr.docChanged) return set; + return map ? set.map(tr.mapping, tr.doc) : DecorationSet.empty; + }, + }, + props: { + decorations(state) { + return this.getState(state); + }, + }, + }), + ); + }, +}); diff --git a/extensions/write-gate/write-gate.ts b/extensions/write-gate/write-gate.ts new file mode 100644 index 00000000..d9e13ceb --- /dev/null +++ b/extensions/write-gate/write-gate.ts @@ -0,0 +1,36 @@ +import { Extension } from "@tiptap/core"; +import { isChangeOrigin } from "@tiptap/extension-collaboration"; +import { Plugin } from "@tiptap/pm/state"; + +export interface WriteGateOptions { + /** + * Whether this window may change the document. Required. Read on every + * transaction, so pass a function over a ref: it must not wait for + * `setEditable`, which runs in an effect after the editor is created. + */ + canWrite: () => boolean; +} + +/** + * Read-only enforced before a change exists (details spec §1 rules 1–2): a + * Yjs update is never dropped once made (later updates from the same + * client would strand), so a read-only document must not make one. Filters + * every local transaction that changes the document while `canWrite()` is + * false, appended ones included, so the plugins that write when a document + * opens (heading ids, the title, the trailing node, the outline) are gated + * too. Changes arriving from Yjs and meta-only transactions (folds, + * previews, decorations) always pass. `setEditable` still blocks typing. + */ +export const WriteGate = Extension.create({ + name: "writeGate", + + addProseMirrorPlugins() { + const { canWrite } = this.options; + return [ + new Plugin({ + filterTransaction: (tr) => + !tr.docChanged || isChangeOrigin(tr) || canWrite(), + }), + ]; + }, +}); diff --git a/hooks/use-yjs-document.ts b/hooks/use-yjs-document.ts index 4195a526..f788b4c2 100644 --- a/hooks/use-yjs-document.ts +++ b/hooks/use-yjs-document.ts @@ -51,6 +51,8 @@ export function useYjsDocument(documentId: string) { return { ydoc, + /** The session's one Awareness (DocSession shape); the provider's here. */ + awareness: providerRef?.awareness ?? null, provider: providerRef, synced, serverSynced, diff --git a/lib/doc-migrations/import-guard.ts b/lib/doc-migrations/import-guard.ts new file mode 100644 index 00000000..7547a6f4 --- /dev/null +++ b/lib/doc-migrations/import-guard.ts @@ -0,0 +1,96 @@ +/** + * The import guard (plan P2.6; architecture §3.3): checks a document's + * state before it enters the library from a `.tinydoc`, a web download or a + * backup. It rejects and never repairs; the import migrations + * ({@link import("./index")}) run only on a state that passed. + * + * Refused: + * - **size:** over {@link IMPORT_MAX_BYTES} (`import_too_large`); + * - **not Yjs:** bytes that don't decode (`corrupt`); + * - **unknown names:** a node or mark this build's schema doesn't know + * (`unknown_schema`). y-prosemirror would delete such content the moment + * the editor binds. The legacy `link` and `code` marks are allowed: the + * import migrations rename them; + * - **unknown roots:** a top-level type other than the editor fragment + * (`unknown_schema`). Comments add their `comments` root here, with their + * validator, in P4.11. + * + * Pure: Yjs and the schema name lists only, so main imports it. + */ +import * as Y from "yjs"; + +import { + isAllowedMarkKey, + isAllowedNodeName, + markNameFromKey, +} from "@/lib/schema-names"; + +/** The editor fragment, `EDITOR_FRAGMENT_NAME` in `lib/yjs-mark-migration.ts`. */ +const EDITOR_ROOT = "default"; + +/** + * 64 MiB: far above any document the editor stays responsive with, and + * low enough that a hostile file can't exhaust the worker's memory while it + * is decoded. + */ +export const IMPORT_MAX_BYTES = 64 * 1024 * 1024; + +export const IMPORT_ROOTS: readonly string[] = [EDITOR_ROOT]; + +export type ImportVerdict = + | { ok: true } + | { + ok: false; + code: "import_too_large" | "corrupt" | "unknown_schema"; + /** Up to five offending names, for the dialog and the log. */ + names: string[]; + }; + +export type ImportGuardOptions = { + maxBytes?: number; + roots?: readonly string[]; +}; + +const MAX_NAMES = 5; + +export function checkImport( + state: Uint8Array, + { + maxBytes = IMPORT_MAX_BYTES, + roots = IMPORT_ROOTS, + }: ImportGuardOptions = {}, +): ImportVerdict { + if (state.byteLength > maxBytes) + return { ok: false, code: "import_too_large", names: [] }; + const names = new Set(); + const note = (name: string) => { + if (names.size < MAX_NAMES) names.add(name.slice(0, 64)); + }; + const doc = new Y.Doc(); + try { + for (const struct of Y.decodeUpdate(state).structs) { + if (!(struct instanceof Y.Item)) continue; + const { content } = struct; + if ( + content instanceof Y.ContentType && + content.type instanceof Y.XmlElement && + !isAllowedNodeName(content.type.nodeName) + ) + note(content.type.nodeName); + else if ( + content instanceof Y.ContentFormat && + !isAllowedMarkKey(content.key) + ) + note(markNameFromKey(content.key)); + } + Y.applyUpdate(doc, state); + for (const root of doc.share.keys()) if (!roots.includes(root)) note(root); + } catch { + return { ok: false, code: "corrupt", names: [] }; + } finally { + doc.destroy(); + } + return names.size === 0 + ? { ok: true } + : { ok: false, code: "unknown_schema", names: [...names] }; +} diff --git a/lib/doc-migrations/index.ts b/lib/doc-migrations/index.ts new file mode 100644 index 00000000..0d645b1d --- /dev/null +++ b/lib/doc-migrations/index.ts @@ -0,0 +1,72 @@ +/** + * Document schema migrations (desktop architecture §5.1, D-A5): pure Yjs + * forward edits that bring a stored document up to {@link DOC_SCHEMA}. + * + * - **On open**, `local-session` runs them after hydrate and before the + * editor binds (y-prosemirror deletes runs whose marks the schema doesn't + * know, `lib/yjs-mark-migration.ts`). The composition root passes + * `DOC_SCHEMA` and `DOC_MIGRATIONS`; local-session runs each step in its + * own `MIGRATION_ORIGIN` transaction, outside undo, and appends it as + * origin `migration` with `schemaTo`, which the storage engine writes to + * `docs.schema` in the same transaction. + * - **At import** (P2.8), the same functions run on `.tinydoc` and web + * downloads. + * + * The list starts empty: schema 0 is today's documents. Each entry raises + * `DOC_SCHEMA` by one. A document whose schema is above `DOC_SCHEMA` was + * written by a newer app and opens read-only (`doc_too_new`). + */ +import type * as Y from "yjs"; + +export type DocMigration = { + /** The schema this step produces: the previous step's `to` plus one. */ + to: number; + /** Edits `doc` in place. Runs inside the caller's transaction. */ + migrate(doc: Y.Doc): void; +}; + +export const DOC_MIGRATIONS: readonly DocMigration[] = []; + +/** The schema documents written by this build are at. */ +export const DOC_SCHEMA: number = DOC_MIGRATIONS.at(-1)?.to ?? 0; + +export type MigrationPlan = + | { kind: "current" } + | { kind: "too_new" } + | { kind: "migrate"; steps: readonly DocMigration[]; schemaTo: number }; + +/** What opening a document stored at `schema` needs. */ +export function planDocMigrations( + schema: number, + migrations: readonly DocMigration[] = DOC_MIGRATIONS, +): MigrationPlan { + const current = migrations.at(-1)?.to ?? 0; + if (!Number.isInteger(schema) || schema < 0) + throw new RangeError(`bad document schema ${schema}`); + if (schema > current) return { kind: "too_new" }; + if (schema === current) return { kind: "current" }; + const steps = migrations.filter((step) => step.to > schema); + steps.forEach((step, i) => { + if (step.to !== schema + i + 1) + throw new RangeError(`migration to ${step.to} is out of order`); + }); + return { kind: "migrate", steps, schemaTo: current }; +} + +/** + * Runs the steps a plan lists in one transaction under `origin`, so they + * produce one update. For import, where a file migrates all or nothing; + * the open hook in local-session runs one transaction per step instead. + * Returns the schema reached, or null when there was nothing to do. + */ +export function runDocMigrations( + doc: Y.Doc, + plan: MigrationPlan, + origin: unknown, +): number | null { + if (plan.kind !== "migrate") return null; + doc.transact(() => { + for (const step of plan.steps) step.migrate(doc); + }, origin); + return plan.schemaTo; +} diff --git a/lib/platform/desktop/rpc-doc-store.ts b/lib/platform/desktop/rpc-doc-store.ts new file mode 100644 index 00000000..5ba12925 --- /dev/null +++ b/lib/platform/desktop/rpc-doc-store.ts @@ -0,0 +1,68 @@ +/** + * A `DocStore` over request/reply calls to the storage worker. `IpcDocStore` + * (P2.5) passes a `call` that goes through `window.tinydocy`; tests and the + * Electron soak pass one that goes to a `StorageClient` (adding the window's + * owner id) or dispatches in-process. + * + * A rejection that carries a storage `code` becomes a `DocStoreError`; + * anything else (a dead transport) becomes `library_unavailable`, which is + * retryable, so the batcher keeps the batch and retries it in order. + */ +import { + type AppendRecord, + type CompactResult, + DOC_STORE_ERROR_CODES, + type DocStore, + DocStoreError, + type DocStoreErrorCode, + type LoadedDoc, +} from "@/lib/platform/doc-store"; + +export type DocStoreCalls = { + load: [{ docId: string }, LoadedDoc]; + append: [{ docId: string; record: AppendRecord }, number]; + compact: [ + { docId: string; state: Uint8Array; upToSeq: number }, + CompactResult, + ]; + close: [{ docId: string }, null]; + flush: [Record, null]; +}; + +export type DocStoreCall = ( + op: K, + args: DocStoreCalls[K][0], +) => Promise; + +const CODES: ReadonlySet = new Set(DOC_STORE_ERROR_CODES); + +export function toDocStoreError(error: unknown): DocStoreError { + if (error instanceof DocStoreError) return error; + const code = (error as { code?: unknown } | null)?.code; + const message = error instanceof Error ? error.message : String(error); + if (typeof code === "string" && CODES.has(code)) + return new DocStoreError(code as DocStoreErrorCode, message); + return new DocStoreError("library_unavailable", message); +} + +export function createRpcDocStore(call: DocStoreCall): DocStore { + const wrap = async (run: () => Promise): Promise => { + try { + return await run(); + } catch (error) { + throw toDocStoreError(error); + } + }; + return { + load: (docId) => wrap(() => call("load", { docId })), + append: (docId, record) => wrap(() => call("append", { docId, record })), + compact: (docId, state, upToSeq) => + wrap(() => call("compact", { docId, state, upToSeq })), + close: async (docId) => { + await wrap(() => call("close", { docId })); + }, + flush: async () => { + await wrap(() => call("flush", {})); + }, + }; +} diff --git a/next.config.ts b/next.config.ts index 566f5910..6990e9fd 100644 --- a/next.config.ts +++ b/next.config.ts @@ -2,9 +2,11 @@ import { execSync } from "node:child_process"; import { readFileSync } from "node:fs"; import type { NextConfig } from "next"; +import { PHASE_PRODUCTION_BUILD } from "next/constants"; import { GA_MEASUREMENT_ID } from "./lib/analytics-config"; import { buildContentSecurityPolicy } from "./lib/security/content-security-policy"; +import { listParked, PARKING_DIR } from "./scripts/desktop-export"; function resolveBuildId(): string { const fromEnv = process.env.NEXT_PUBLIC_BUILD_ID?.trim(); @@ -25,6 +27,19 @@ function resolveBuildId(): string { return pkg.version; } +// The one build-time switch between the two renderers (desktop +// architecture §3.1 step 1). `bun run build:desktop` sets it. +const isDesktop = process.env.NEXT_PUBLIC_APP_TARGET === "desktop"; + +// A desktop export that was killed can leave web-only files parked; a web +// build now would ship without its sitemap, manifest or privacy page. +const parked = isDesktop ? [] : listParked(process.cwd()); +if (parked.length > 0) { + throw new Error( + `${parked.join(", ")} are parked in ${PARKING_DIR}/ by an interrupted desktop export. Run \`bun run build:desktop\` once (it puts them back first), or move them back into app/.`, + ); +} + const nextConfig: NextConfig = { env: { NEXT_PUBLIC_BUILD_ID: resolveBuildId(), @@ -32,39 +47,62 @@ const nextConfig: NextConfig = { // branches; an unset NEXT_PUBLIC_* stays a runtime lookup. NEXT_PUBLIC_APP_TARGET: process.env.NEXT_PUBLIC_APP_TARGET ?? "web", }, + // Web-only route handlers are `route.web.ts(x)`, which the desktop + // extensions don't match; `*.desktop.tsx` is the desktop-only + // counterpart. Web-only pages and metadata files are parked instead + // (scripts/desktop-export.ts). + pageExtensions: isDesktop + ? ["desktop.tsx", "tsx", "ts"] + : ["web.tsx", "web.ts", "tsx", "ts"], + // The export type-checks a tree with web-only files parked, which the + // route types `next dev` generated (.next/dev/types) still import. + // `bun run typecheck` checks every file, desktop ones included. + ...(isDesktop ? { typescript: { ignoreBuildErrors: true } } : {}), // Next 16.4+ rewrites AGENTS.md when it detects a coding agent; that file // holds curated repo conventions, so keep it hand-maintained. agentRules: false, poweredByHeader: false, - async headers() { - return [ - { - source: "/:path*", - headers: [ - { key: "X-Content-Type-Options", value: "nosniff" }, - { key: "X-Frame-Options", value: "DENY" }, - { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" }, - // Caps what embedded players can request, whatever `allow` a - // collaborator puts on the iframe. - { - key: "Permissions-Policy", - value: - "camera=(), microphone=(), geolocation=(), display-capture=(), clipboard-read=(), payment=(), usb=(), serial=(), hid=()", - }, - { - key: "Content-Security-Policy", - value: buildContentSecurityPolicy({ - nodeEnv: process.env.NODE_ENV, - hocusUrl: - process.env.NEXT_PUBLIC_HOCUS_URL?.trim() || - "ws://127.0.0.1:1234", - gaMeasurementId: GA_MEASUREMENT_ID, - }), - }, - ], - }, - ]; - }, + // A static export has no server to send headers; the desktop shell sets + // its own CSP (P2.5). + ...(isDesktop ? {} : { headers: webHeaders }), }; -export default nextConfig; +async function webHeaders() { + return [ + { + source: "/:path*", + headers: [ + { key: "X-Content-Type-Options", value: "nosniff" }, + { key: "X-Frame-Options", value: "DENY" }, + { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" }, + // Caps what embedded players can request, whatever `allow` a + // collaborator puts on the iframe. + { + key: "Permissions-Policy", + value: + "camera=(), microphone=(), geolocation=(), display-capture=(), clipboard-read=(), payment=(), usb=(), serial=(), hid=()", + }, + { + key: "Content-Security-Policy", + value: buildContentSecurityPolicy({ + nodeEnv: process.env.NODE_ENV, + hocusUrl: + process.env.NEXT_PUBLIC_HOCUS_URL?.trim() || + "ws://127.0.0.1:1234", + gaMeasurementId: GA_MEASUREMENT_ID, + }), + }, + ], + }, + ]; +} + +// Desktop is a static export loaded from app://tinydocy. Only the build +// exports: under `next dev` (the `local` Playwright project) the web +// metadata files aren't parked, and `output: "export"` would make each of +// them a 500 that every page links. +export default function config(phase: string): NextConfig { + return isDesktop && phase === PHASE_PRODUCTION_BUILD + ? { ...nextConfig, output: "export" } + : nextConfig; +} diff --git a/package.json b/package.json index 6b4393af..05f6aeff 100644 --- a/package.json +++ b/package.json @@ -11,9 +11,10 @@ "dev": "next dev", "hocus": "bun scripts/hocus-server.ts", "build": "next build", + "build:desktop": "bun scripts/build-desktop.ts", "start": "next start", "lint": "eslint .", - "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.sw.json", + "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.sw.json && tsc --noEmit -p tsconfig.desktop-node.json", "format": "biome format --write .", "format:check": "biome format .", "check": "biome check .", diff --git a/scripts/build-desktop.ts b/scripts/build-desktop.ts new file mode 100644 index 00000000..58830fff --- /dev/null +++ b/scripts/build-desktop.ts @@ -0,0 +1,62 @@ +/** + * Builds the desktop renderer into `out/`: the static export with + * NEXT_PUBLIC_APP_TARGET=desktop (desktop architecture §3.1 step 1). + * Release builds run it on Linux only (#103). How routes leave the export, + * and the parking rules: `scripts/desktop-export.ts`. + * + * bun run build:desktop + */ +import { join } from "node:path"; + +import { + checkDesktopExport, + parkWebOnlyFiles, + restoreParked, +} from "./desktop-export"; + +async function main(): Promise { + const root = process.cwd(); + const leftovers = restoreParked(root); + for (const rel of leftovers) { + console.log(`[desktop-export] put back ${rel}, left by an interrupted run`); + } + + const parked = parkWebOnlyFiles(root); + const putBack = () => { + const restored = restoreParked(root); + if (restored.length !== parked.length) { + console.error( + `[desktop-export] put back ${restored.length} of ${parked.length} files; check app/`, + ); + } + }; + const onSignal = (signal: NodeJS.Signals) => { + putBack(); + process.exit(signal === "SIGINT" ? 130 : 143); + }; + process.once("SIGINT", onSignal); + process.once("SIGTERM", onSignal); + + let code: number; + try { + const build = Bun.spawn(["bun", "next", "build"], { + cwd: root, + stdio: ["ignore", "inherit", "inherit"], + env: { ...process.env, NEXT_PUBLIC_APP_TARGET: "desktop" }, + }); + code = await build.exited; + } finally { + putBack(); + process.off("SIGINT", onSignal); + process.off("SIGTERM", onSignal); + } + if (code !== 0) return code; + + const problems = checkDesktopExport(join(root, "out")); + for (const problem of problems) console.error(`[desktop-export] ${problem}`); + if (problems.length > 0) return 1; + console.log("[desktop-export] out/ is a valid desktop renderer"); + return 0; +} + +if (import.meta.main) process.exit(await main()); diff --git a/scripts/check-editor-chunk-size.ts b/scripts/check-editor-chunk-size.ts index b8de46ff..604c9dff 100644 --- a/scripts/check-editor-chunk-size.ts +++ b/scripts/check-editor-chunk-size.ts @@ -1,8 +1,8 @@ /** - * Editor bundle gate (spec §7, contract §5.1): the lazy editor chunk group - * may grow by at most `EDITOR_CHUNK_BUDGET_BYTES` gzipped over the baseline - * measured on `58a9d22` (the `integrate/smart-toolbar-ab` tip, before any - * smart-toolbar v1 track merged). + * Editor bundle gate (spec §7, contract §5.1; desktop D23): the lazy editor + * chunk group may grow by at most `EDITOR_CHUNK_BUDGET_BYTES` gzipped over + * the baseline measured on `58a9d22` (the `integrate/smart-toolbar-ab` tip, + * before any smart-toolbar v1 track merged). * * The editor is a `next/dynamic` import (`components/editor-app`). Turbopack * emits a loader that fetches the editor's chunk group with @@ -21,14 +21,25 @@ import { join } from "node:path"; /** Gzipped bytes of the editor chunk group at `58a9d22`. */ export const EDITOR_CHUNK_BASELINE_BYTES = 377_888; /** - * Allowed growth for the whole smart toolbar v1. Spec §7 said +6 KB gz; - * owner decision O1 (contract §10 A9) lazy-loads what is not needed at - * first paint and sets the budget to the measured remainder (18.43 KB on - * the r2 integration), rounded up to the next 0.5 KB. A11 raises it to - * 20 KB for the r2 fix waves (owner, 2026-11-13), and A12 to 23.5 KB for - * PR E (owner, 2026-11-13). Raising it again needs a new contract amendment. + * Growth on `main` (08b7663) when P2.2 set the fence: the smart toolbar v1 + * and everything merged before the desktop work. Its old 23.5 KB budget + * (contract A12) is replaced by the fence below. */ -export const EDITOR_CHUNK_BUDGET_BYTES = 23.5 * 1024; +export const EDITOR_CHUNK_MAIN_GROWTH_BYTES = 15_284; +/** + * The D23 editor-chunk ledger (desktop details spec §1 rule 5): every line + * the desktop, library and v1 feature work may add to this chunk, each + * measured in its PR. While D41's conditional 80 B undo line is + * unconfirmed the total is 1,580 B; if spike M18 confirms it, this becomes + * 1,660 B with no further approval. + */ +export const EDITOR_CHUNK_LEDGER_BYTES = 1_580; +/** + * The fence (D23): `main` plus the ledger, so unrelated work can't spend + * the ledger's bytes. Raising it needs an amendment to that rule. + */ +export const EDITOR_CHUNK_BUDGET_BYTES = + EDITOR_CHUNK_MAIN_GROWTH_BYTES + EDITOR_CHUNK_LEDGER_BYTES; /** Only `document-editor.tsx` renders this string. */ const EDITOR_MARKER = "Main content area, start typing to enter text."; @@ -75,13 +86,13 @@ function main() { const nextDir = dirFlag === -1 ? ".next" : process.argv[dirFlag + 1]; const { files, gzipBytes } = measureEditorChunk(nextDir); const growth = gzipBytes - EDITOR_CHUNK_BASELINE_BYTES; - const kb = (bytes: number) => `${(bytes / 1024).toFixed(1)} KB`; + const bytes = (n: number) => `${n.toLocaleString("en-US")} B`; console.log( - `Editor chunk group (${files.length} files): ${kb(gzipBytes)} gz`, + `Editor chunk group (${files.length} files): ${bytes(gzipBytes)} gz`, ); for (const file of files) console.log(` ${file}`); console.log( - `Baseline ${kb(EDITOR_CHUNK_BASELINE_BYTES)}, growth ${growth >= 0 ? "+" : ""}${kb(growth)}, budget +${kb(EDITOR_CHUNK_BUDGET_BYTES)}`, + `Baseline ${bytes(EDITOR_CHUNK_BASELINE_BYTES)}, growth ${growth >= 0 ? "+" : ""}${bytes(growth)}, budget +${bytes(EDITOR_CHUNK_BUDGET_BYTES)} (${bytes(EDITOR_CHUNK_BUDGET_BYTES - growth)} left)`, ); if (growth > EDITOR_CHUNK_BUDGET_BYTES) { console.error( diff --git a/scripts/desktop-export.ts b/scripts/desktop-export.ts new file mode 100644 index 00000000..53f181e0 --- /dev/null +++ b/scripts/desktop-export.ts @@ -0,0 +1,134 @@ +/** + * Shared by `scripts/build-desktop.ts` and `next.config.ts`: what leaves the + * desktop static export (NEXT_PUBLIC_APP_TARGET=desktop) and how. No Bun + * APIs and no top-level await: `next.config.ts` imports it. + * + * What leaves the export, and how: + * - Web-only route handlers (`app/api`, `llms.txt`, `/pwa-icons`) are + * `route.web.ts(x)`. `next.config.ts` gives the desktop target page + * extensions that don't match them. No file moves. + * - The files in `WEB_ONLY_FILES` can't use that switch, so + * `bun run build:desktop` parks them for the build and puts them back: + * - Metadata files: Turbopack ignores `pageExtensions` for them (spike + * S1), and with `force-static` they would put the web manifest, + * `og:image` and `apple-touch-icon` tags into every desktop page (#115). + * - Pages: Next 16.4.6 drops the root layout's font preload from a + * `page.web.tsx` (`getPreloadableFonts` strips only `.tsx`, so it looks + * up `app/privacy/page.web` in a manifest keyed `app/privacy/page`). + * Renaming would change the web HTML. + * + * Parking rules (#111, #115): park inside the checkout (a rename across + * drives fails with EXDEV on Windows runners), put back what an interrupted + * run left first, put back in `finally` and on SIGINT/SIGTERM, and refuse to + * run if a file is both in `app/` and parked. `next.config.ts` refuses a web + * build while anything is parked, so a killed run can't ship a web build + * without its sitemap or its privacy page. + */ +import { + existsSync, + mkdirSync, + readdirSync, + readFileSync, + renameSync, + rmdirSync, +} from "node:fs"; +import { join, relative } from "node:path"; + +/** Web-only files parked during a desktop export, relative to the root. */ +export const WEB_ONLY_FILES = [ + "app/sitemap.ts", + "app/robots.ts", + "app/manifest.ts", + "app/opengraph-image.tsx", + "app/apple-icon.tsx", + "app/privacy/page.tsx", + "app/offline/page.tsx", +] as const; + +/** Where those files wait during a desktop export (gitignored). */ +export const PARKING_DIR = ".desktop-export-parked"; + +const parkedName = (rel: string) => rel.replaceAll("/", "__"); + +/** Files currently parked under `root`, as repo-relative paths. */ +export function listParked(root: string): string[] { + const dir = join(root, PARKING_DIR); + if (!existsSync(dir)) return []; + return readdirSync(dir).map((name) => name.replaceAll("__", "/")); +} + +/** Puts back every parked file. Throws if one also exists in `app/`. */ +export function restoreParked(root: string): string[] { + const restored: string[] = []; + for (const rel of listParked(root)) { + if (existsSync(join(root, rel))) { + throw new Error( + `${rel} is both in app/ and in ${PARKING_DIR}/; keep the right copy and delete the other`, + ); + } + renameSync(join(root, PARKING_DIR, parkedName(rel)), join(root, rel)); + restored.push(rel); + } + const dir = join(root, PARKING_DIR); + if (existsSync(dir)) rmdirSync(dir); + return restored; +} + +/** Moves `WEB_ONLY_FILES` out of `app/`. */ +export function parkWebOnlyFiles(root: string): string[] { + const dir = join(root, PARKING_DIR); + mkdirSync(dir, { recursive: true }); + const parked: string[] = []; + for (const rel of WEB_ONLY_FILES) { + if (!existsSync(join(root, rel))) continue; + renameSync(join(root, rel), join(dir, parkedName(rel))); + parked.push(rel); + } + return parked; +} + +/** Top-level names in `out/` that belong to the web build only. */ +const WEB_ONLY_OUTPUT = + /^(api|privacy|offline|pwa-icons|llms\.txt|sitemap|robots|manifest|opengraph-image|twitter-image|apple-icon)(\.|$)/; + +/** Head tags that file-convention metadata adds; none may reach desktop. */ +const WEB_ONLY_TAGS = [ + / void): void { + for (const entry of readdirSync(dir, { withFileTypes: true })) { + const path = join(dir, entry.name); + visit(path); + if (entry.isDirectory()) walk(path, visit); + } +} + +/** + * Problems with an exported `out/`, empty when it is a valid desktop + * renderer: no web-only route, no web metadata tag in any page, and the + * flat segment-prefetch layout (Windows writes `__next./`, #103). + */ +export function checkDesktopExport(outDir: string): string[] { + const problems: string[] = []; + for (const name of readdirSync(outDir)) { + if (WEB_ONLY_OUTPUT.test(name)) problems.push(`web-only output: ${name}`); + } + walk(outDir, (path) => { + const rel = relative(outDir, path); + const name = rel.split(/[\\/]/).at(-1) ?? ""; + if (name.startsWith("__next.") && !name.endsWith(".txt")) { + problems.push(`nested segment directory (Windows layout): ${rel}`); + } + if (!rel.endsWith(".html")) return; + const html = readFileSync(path, "utf8"); + for (const tag of WEB_ONLY_TAGS) { + if (tag.test(html)) problems.push(`${rel} has ${tag.source}`); + } + }); + return problems; +} diff --git a/scripts/serve-desktop-export.ts b/scripts/serve-desktop-export.ts new file mode 100644 index 00000000..60f21bf1 --- /dev/null +++ b/scripts/serve-desktop-export.ts @@ -0,0 +1,43 @@ +/** + * Serves the desktop static export (`out/`) over loopback HTTP, with the + * path rules of the `app://tinydocy` protocol handler + * (`desktop/shared/export-paths.ts`). For the `desktop` Playwright project + * until the Electron shell (P2.5) can run it; never a production server. + * + * bun run build:desktop && PORT=3849 bun scripts/serve-desktop-export.ts + */ +import { statSync } from "node:fs"; +import { join, resolve } from "node:path"; + +import { resolveExportFile } from "@/desktop/shared/export-paths"; + +const OUT_DIR = resolve(process.env.DESKTOP_OUT_DIR ?? "out"); +const PORT = Number(process.env.PORT ?? 3849); + +function isFile(rel: string): boolean { + try { + return statSync(join(OUT_DIR, rel)).isFile(); + } catch { + return false; + } +} + +const server = Bun.serve({ + hostname: "127.0.0.1", + port: PORT, + fetch(request) { + if (request.method !== "GET" && request.method !== "HEAD") { + return new Response("Method not allowed", { status: 405 }); + } + const found = resolveExportFile(new URL(request.url).pathname, isFile); + if (!found) return new Response("Not found", { status: 404 }); + return new Response(Bun.file(join(OUT_DIR, found.file)), { + headers: { + "content-type": found.contentType, + "x-content-type-options": "nosniff", + }, + }); + }, +}); + +console.log(`[serve-desktop-export] ${OUT_DIR} on ${server.url}`); diff --git a/tests/TESTING.md b/tests/TESTING.md index 0c6af8f3..2a49a375 100644 --- a/tests/TESTING.md +++ b/tests/TESTING.md @@ -57,11 +57,12 @@ tests/ │ ├── hooks/ # useSyncedTabs bootstrap + active-tab resolution (mocked Hocuspocus provider) │ ├── platform/ # DocumentIndex contract suite (`document-index-contract.ts`) on MemoryDocumentIndex and GlobalTabsIndex, plus the sandbox's own rules (Playground, bootstrap, poisoned entries) │ ├── api/ # Route handlers: DELETE rate limit; soft close, batch restore and Recently closed list (temp DB_PATH) -│ ├── scripts/ # Retention purge (stale and closed documents), operator delete-document, Hocus client gate and root sweep +│ ├── scripts/ # Retention purge (stale and closed documents), operator delete-document, Hocus client gate and root sweep, desktop export parking and output check │ ├── lib/ # Image embed planner and pipeline; `assets/` PNG, WebP and JPEG metadata stripper; security guardrails (incl. closed-documents store), import boundaries (server entries never reach `lib/tab-api` or `@hocuspocus/provider`), legacy Yjs mark migration (link/code → hyperlink/inlineCode), `addToHistory: false` kept with appended heading-id transactions (y-tiptap patch), design-token contrast (`token-contrast.test.ts`: `--primary-ink` ≥ 4.5:1 on every surface, no `text-primary`/`border-primary` utility in TSX and no `var(--primary)` text or border declaration in stylesheets, document link colour ≥ 4.5:1 on background and card in both themes), theme boot script and System theme (`theme.test.ts`), identity validation and blocked storage (`user-identity.test.ts`) │ ├── editor-actions/ # Action contract and core actions; shortcut-bindings.test.ts: every advertised key bound once, tab-bar keys kept out of the editor keymap, Subscript by build target; playground-regenerate.test.ts: Regenerate Playground offered in the Playground only │ ├── components/ # React components in happy-dom (toolbar button, menus, insert menu, ThemeToggle's phone cycle in `theme-toggle.test.tsx`); the identity dialog's inline name errors and the normalised broadcast (`user-identity-dialog.test.tsx`) │ ├── extensions/ # Render-once, CaretBlockVisible, fast TOC, incremental code highlighting, media controls kept across plugin view rebuilds, remote caret names and colours clamped at render (`safe-caret-render.test.ts`) +│ ├── desktop/ # Desktop shared modules: the static export's path rules (`export-paths.test.ts`) │ ├── ci/ # Workflow rules: read-only tokens, no persisted credentials, SHA-pinned actions │ ├── fuzz/ # Chaos fuzz (5000 ops) + structured schema fuzz (5000 ops) │ └── stress/ # Headless stress probe (binary search for heading ceiling) @@ -89,7 +90,7 @@ tests/ │ ├── offline-copies.spec.ts # IndexedDB copies: repeat visit, reload, deletion, clearing │ ├── tab-close-undo.spec.ts # Undo pill after closing, Recently closed, purge after the closed window │ ├── continue-chip.spec.ts # "Continue where you left off" chip (reopen, Go, dismissal, phone, leaks, axe) -│ ├── desktop-seams.spec.ts # Desktop-flag build: no /privacy request, X post as a link card, no X request (desktop project) +│ ├── desktop-seams.spec.ts # Desktop static export: every request answers, no web-only route or /privacy request, X post as a link card (desktop project) │ ├── toc-sidebar.spec.ts # TOC rendering + scroll-to-heading │ ├── toc-drag.spec.ts # TOC drag-and-drop reorder + level change │ ├── tabs.spec.ts # Tab bar: regenerate, Mod+Shift+R on the Playground aligns right, Alt+/ › Regenerate Playground (Playground only), new tab, close-all @@ -315,20 +316,23 @@ PWA_BASE_URL=http://localhost:3847 CI= bun run test:pwa Offline is simulated with `context.setOffline(true)`, which also cuts the worker's own fetches in Chromium. Unit tests for the routing rules live in `tests/unit/lib/pwa-sw-routing.test.ts`. -### Desktop-flag build +### Desktop renderer (static export) | Test | Project | Validates | |------|---------|-----------| -| `desktop-seams.spec.ts` | `desktop` (production build with `NEXT_PUBLIC_APP_TARGET=desktop`) | `/about` and the editor never request `/privacy` (the Privacy links go to the website's page in a new window); a pasted X post renders as the static link card, its button opens the post in a new window, and nothing is requested from X's hosts or loads `widgets.js` | +| `desktop-seams.spec.ts` | `desktop` (the desktop static export, `bun run build:desktop`, served with the `app://` protocol handler's path rules) | Every same-origin request the renderer makes on `/about`, a client navigation to `/` and a synced editor answers (pages as `.html`, RSC `.txt` payloads and segment prefetches, `/icon` as `image/png`), and none goes to a web-only route (manifest, Open Graph image, Apple icon, sitemap, robots, `/api`, `/privacy`, `/offline`); `/about` and the editor never request `/privacy` (the Privacy links go to the website's page in a new window); a pasted X post renders as the static link card, its button opens the post in a new window, and nothing is requested from X's hosts or loads `widgets.js` | -Prefetch runs only in production builds, so this needs one. Use free ports and localhost only: +Prefetch runs only in production builds, so this runs on the export. Nightly runs it on Linux (`desktop-renderer` in `nightly.yml`), where releases build the renderer (#103). Use free ports and localhost only: ```bash -NEXT_PUBLIC_APP_TARGET=desktop NEXT_PUBLIC_HOCUS_URL=ws://127.0.0.1:1296 bun run build && PORT=3849 bun run start +NEXT_PUBLIC_HOCUS_URL=ws://127.0.0.1:1296 bun run build:desktop +PORT=3849 bun scripts/serve-desktop-export.ts HOCUS_PORT=1296 HOCUS_THROTTLE=0 HOCUS_ALLOW_ISOLATED_TABS_DOCS=1 bun run hocus -DESKTOP_BASE_URL=http://localhost:3849 CI= bun playwright test --project=desktop +DESKTOP_BASE_URL=http://127.0.0.1:3849 CI= bun playwright test --project=desktop ``` +`bun run build:desktop` parks the web-only metadata files and pages for the build, puts them back, and fails if a web-only route, a web metadata tag or the Windows segment layout reaches `out/`. Its parking rules are unit tested in `tests/unit/scripts/desktop-export.test.ts`, the path rules in `tests/unit/desktop/export-paths.test.ts`, and the desktop build never registering the service worker in `tests/unit/components/service-worker-registration.test.ts`. + The web behaviour with the flag off, and the flag-on branches, are unit tested in `tests/unit/extensions/x-link-card.test.ts`, `tests/unit/helpers/media-embed.test.ts` and `tests/unit/components/privacy-link.test.tsx`. Manual install checklist (localhost production build): diff --git a/tests/e2e/desktop-seams.spec.ts b/tests/e2e/desktop-seams.spec.ts index 0c35417b..389c2db0 100644 --- a/tests/e2e/desktop-seams.spec.ts +++ b/tests/e2e/desktop-seams.spec.ts @@ -3,12 +3,13 @@ import { expect, type Page, test } from "@playwright/test"; import { EditorPage } from "./helpers/editor-page"; /** - * The desktop renderer's web seams (#99, #101), against a production build - * made with the desktop flag (prefetch runs only in production builds): - * NEXT_PUBLIC_APP_TARGET=desktop NEXT_PUBLIC_HOCUS_URL=ws://127.0.0.1:1296 bun run build - * PORT=3849 bun run start + * The desktop renderer (#99, #101, P2.4), against the desktop static export + * served with the protocol handler's path rules (prefetch runs only in + * production builds): + * NEXT_PUBLIC_HOCUS_URL=ws://127.0.0.1:1296 bun run build:desktop + * PORT=3849 bun scripts/serve-desktop-export.ts * HOCUS_PORT=1296 HOCUS_THROTTLE=0 HOCUS_ALLOW_ISOLATED_TABS_DOCS=1 bun run hocus - * DESKTOP_BASE_URL=http://localhost:3849 CI= bun playwright test --project=desktop + * DESKTOP_BASE_URL=http://127.0.0.1:3849 CI= bun playwright test --project=desktop */ test.skip(!process.env.DESKTOP_BASE_URL, "needs a desktop-flag build"); @@ -41,6 +42,50 @@ async function paste(page: Page, text: string): Promise { } test.describe("desktop build", () => { + test("the export answers every request the renderer makes", async ({ + page, + }) => { + const origin = new URL(test.info().project.use.baseURL ?? "").origin; + const failed: string[] = []; + page.on("response", (response) => { + const url = new URL(response.url()); + if (url.origin === origin && response.status() >= 400) { + failed.push(`${response.status()} ${url.pathname}${url.search}`); + } + }); + const urls = recordRequests(page); + + // The header links prefetch both pages' segments; the click is a + // client navigation that fetches the RSC payload (.txt). + await page.goto("/about"); + await page.waitForLoadState("networkidle"); + await page + .getByRole("navigation", { name: "Site" }) + .getByRole("link", { name: "Open the editor" }) + .click(); + await expect(page).toHaveURL(/\/$/); + await new EditorPage(page).waitForSync(); + await page.waitForLoadState("networkidle"); + + expect(failed).toEqual([]); + const paths = urls.map((url) => new URL(url).pathname); + expect(paths.some((path) => path.endsWith(".txt"))).toBe(true); + // The page links it; headless Chromium doesn't fetch icons itself. + const href = await page + .locator('link[rel="icon"][type="image/png"]') + .getAttribute("href"); + const icon = await page.request.get(href ?? ""); + expect(icon.status()).toBe(200); + expect(icon.headers()["content-type"]).toBe("image/png"); + expect( + paths.filter((path) => + /^\/(manifest\.webmanifest|opengraph-image|apple-icon|sitemap|robots|api\/|privacy|offline)/.test( + path, + ), + ), + ).toEqual([]); + }); + test("/about links to the website's privacy page and never fetches /privacy", async ({ page, }) => { diff --git a/tests/e2e/filter.spec.ts b/tests/e2e/filter.spec.ts index 0a9334ed..df3742a8 100644 --- a/tests/e2e/filter.spec.ts +++ b/tests/e2e/filter.spec.ts @@ -1,20 +1,7 @@ -import { expect, type Page, test } from "@playwright/test"; +import { expect, test } from "@playwright/test"; import { EditorPage } from "./helpers/editor-page"; -/** The headings must be on the server before a shared link opens. */ -async function waitForServerCopy(page: Page): Promise { - await page.waitForFunction(() => { - const caret = window.__tiptap_editor?.extensionManager.extensions.find( - (extension) => extension.name === "collaborationCaret", - ); - const provider = caret?.options.provider as - | { hasUnsyncedChanges: boolean } - | undefined; - return provider !== undefined && !provider.hasUnsyncedChanges; - }); -} - test.describe("heading filter", () => { let editorPage: EditorPage; @@ -48,7 +35,8 @@ test.describe("heading filter", () => { test("a ?filter= link applies the filter once the doc syncs", async ({ page, }) => { - await waitForServerCopy(page); + // The headings must be on the server before a shared link opens. + await editorPage.expectSavedToServer(); await page.goto("/?filter=alpha&mode=or"); await editorPage.waitForSync(); @@ -80,7 +68,8 @@ test.describe("heading filter", () => { test("a ?filter= link over the cap applies only its first 8 words", async ({ page, }) => { - await waitForServerCopy(page); + // The headings must be on the server before a shared link opens. + await editorPage.expectSavedToServer(); // Beta and Gamma come 9th and 10th, so they must be dropped unmatched. const kept = ["alpha", "w2", "w3", "w4", "w5", "w6", "w7", "w8"]; await page.goto(`/?filter=${[...kept, "beta", "gamma"].join("|")}&mode=or`); diff --git a/tests/e2e/helpers/editor-page.ts b/tests/e2e/helpers/editor-page.ts index 147b2a9f..25715da7 100644 --- a/tests/e2e/helpers/editor-page.ts +++ b/tests/e2e/helpers/editor-page.ts @@ -310,12 +310,25 @@ export class EditorPage { () => { const notice = document.querySelector(".document-size-notice"); if (notice) return { refusal: notice.textContent ?? "" }; + // The caret's `provider` option is the editor's Awareness holder, + // not the provider: its `on` forwards to the provider of the moment + // and returns what that returns, and `HocuspocusProvider.on` + // returns the provider itself (`this`). Null with no provider. const caret = window.__tiptap_editor?.extensionManager.extensions.find( (extension) => extension.name === "collaborationCaret", ); - const provider = caret?.options.provider as - | { isSynced: boolean; hasUnsyncedChanges: boolean } + const forward = caret?.options.provider as + | { on: (event: string, fn: () => void) => unknown } | undefined; + const probe = () => {}; + const provider = forward?.on("tinydocy:probe", probe) as + | { + isSynced: boolean; + hasUnsyncedChanges: boolean; + off: (event: string, fn: () => void) => void; + } + | undefined; + provider?.off("tinydocy:probe", probe); if (!provider?.isSynced || provider.hasUnsyncedChanges) return false; return { refusal: null }; }, diff --git a/tests/helpers/editor-schema.ts b/tests/helpers/editor-schema.ts index dcdbe60f..a2d17e31 100644 --- a/tests/helpers/editor-schema.ts +++ b/tests/helpers/editor-schema.ts @@ -1,6 +1,6 @@ -import type { HocuspocusProvider } from "@hocuspocus/provider"; import { getSchema } from "@tiptap/core"; import type { Schema } from "@tiptap/pm/model"; +import type { Awareness } from "y-protocols/awareness"; import * as Y from "yjs"; import { buildDocumentEditorExtensions } from "@/components/document-editor/document-editor-config"; @@ -11,7 +11,9 @@ export function getEditorSchema(): Schema { buildDocumentEditorExtensions({ documentId: "schema-test", ydoc: new Y.Doc(), - provider: {} as HocuspocusProvider, + awareness: {} as Awareness, + getProvider: () => null, + canWrite: () => true, onFoldChange() {}, onFilterChange() {}, onTocUpdate() {}, diff --git a/tests/helpers/engine-doc-store.ts b/tests/helpers/engine-doc-store.ts new file mode 100644 index 00000000..3dd5c287 --- /dev/null +++ b/tests/helpers/engine-doc-store.ts @@ -0,0 +1,48 @@ +/** + * `DocStore`s over a real storage engine, in-process on `bun:sqlite`: what + * the shared contract suite runs against on every PR (architecture §11). + * Each store is one window (`owner`); two stores over one library model two + * windows, for `already_open`. + * + * Requests go through the worker's own `dispatch`, so the in-process path + * and the Electron worker share every line but the transport. Bytes are + * copied on the way in, as IPC would. + */ +import type { Library } from "@/desktop/storage/engine/library"; +import { dispatch, type StorageRequest } from "@/desktop/storage/protocol"; +import { + createRpcDocStore, + type DocStoreCall, +} from "@/lib/platform/desktop/rpc-doc-store"; +import type { DocStore } from "@/lib/platform/doc-store"; + +function copyBytes(value: T): T { + if (value instanceof Uint8Array) return value.slice() as T; + if (Array.isArray(value)) return value.map(copyBytes) as T; + if (value && typeof value === "object") + return Object.fromEntries( + Object.entries(value).map(([k, v]) => [k, copyBytes(v)]), + ) as T; + return value; +} + +let nextId = 1; + +export function createEngineDocStore( + library: Library, + owner: string, +): DocStore { + const call: DocStoreCall = async (op, args) => { + const request = { + id: nextId++, + op, + args: op === "flush" ? {} : { ...copyBytes(args), owner }, + } as StorageRequest; + // A microtask boundary, as a real transport has. + await Promise.resolve(); + const result = dispatch(library, request); + if (!result.ok) throw result.error; + return copyBytes(result.value) as never; + }; + return createRpcDocStore(call); +} diff --git a/tests/helpers/storage-library.ts b/tests/helpers/storage-library.ts new file mode 100644 index 00000000..dc5d8f0a --- /dev/null +++ b/tests/helpers/storage-library.ts @@ -0,0 +1,68 @@ +/** + * Test helpers for the desktop storage engine on `bun:sqlite`: a temp + * library folder, a controllable clock, and an opener with test defaults. + */ +import { mkdtempSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { openBunSqlite } from "@/desktop/dev/bun-sqlite-driver"; +import type { StorageHost } from "@/desktop/storage/engine/host"; +import { + Library, + type OpenLibraryOptions, +} from "@/desktop/storage/engine/library"; +import { createNodeHost } from "@/desktop/storage/node-host"; + +export type TestClock = { now: number; advance(ms: number): void }; + +export function createClock( + start = Date.UTC(2026, 10, 17, 9, 0, 0), +): TestClock { + return { + now: start, + advance(ms) { + this.now += ms; + }, + }; +} + +export function createTempDir(prefix = "tinydocy-lib-"): { + dir: string; + cleanUp(): void; +} { + const dir = mkdtempSync(join(tmpdir(), prefix)); + return { dir, cleanUp: () => rmSync(dir, { recursive: true, force: true }) }; +} + +export function createTestHost( + clock: TestClock, + overrides: Partial = {}, +): StorageHost { + return createNodeHost({ now: () => clock.now, ...overrides }); +} + +export function openTestLibrary( + dir: string, + host: StorageHost, + options: Partial = {}, +): Library { + return Library.open({ + dir, + host, + openSqlite: openBunSqlite, + // Tests don't need F_FULLFSYNC's 4 ms per commit. + fullfsync: false, + ...options, + }); +} + +/** + * Simulates a crash: the library is dropped without `shutdown`, so + * `unclean_exit` stays set and the lock file stays behind. The lock's pid is + * this test process, which the next open treats as stale. + */ +export function crash(library: Library) { + (library as unknown as { db: { close(): void } | null }).db?.close(); + (library as unknown as { db: unknown }).db = null; +} diff --git a/tests/load/desktop-durability-soak.ts b/tests/load/desktop-durability-soak.ts new file mode 100644 index 00000000..5fa349ee --- /dev/null +++ b/tests/load/desktop-durability-soak.ts @@ -0,0 +1,876 @@ +/** + * Desktop durability and growth soak (plan §9 T1–T8, P2.6's exit row). + * + * Launches the real storage worker inside Electron (the harness in + * `desktop/storage-harness`, built first), SIGKILLs it at chosen moments + * (`TerminateProcess` on Windows), waits until the pid is gone, then + * reopens the library with the engine on `bun:sqlite`, which also proves + * the two drivers read each other's files. The shape follows spike S2's + * kill harness. + * + * bun tests/load/desktop-durability-soak.ts --case=all|contract|T1|T2|T3|T4|T5|T6|T8 + * [--kills=200] [--out=soak-out] [--verbose] + * + * T7 (slow-hydrate overwrite) is a web-library case: it tests the session + * layer, not storage, and runs with W2. + * + * Writes `/.json` and a Markdown table to `$GITHUB_STEP_SUMMARY`. + * Exits 1 if any case fails. Run it only on CI runners (it starts + * Electron); on a desktop machine the windows stay hidden but it still + * takes the CPU for minutes. + */ + +import { Database } from "bun:sqlite"; +import { createHash } from "node:crypto"; +import { + appendFileSync, + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + rmSync, + statSync, + writeFileSync, +} from "node:fs"; +import { createRequire } from "node:module"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import * as Y from "yjs"; + +import { openBunSqlite } from "@/desktop/dev/bun-sqlite-driver"; +import { DAILY_KEEP } from "@/desktop/storage/engine/daily-copy"; +import { + IDLE_MS, + LIBRARY_FILE, + Library, + type OpenLibraryOptions, +} from "@/desktop/storage/engine/library"; +import { LOCK_FILE } from "@/desktop/storage/engine/lock"; +import { createNodeHost } from "@/desktop/storage/node-host"; +import { + STEP_ROWS, + T5_STEPS, + T5_TARGET, +} from "@/desktop/storage-harness/format-steps"; +import { + editCount, + PAD, + padUpdate, + parseArgs, + seededRandom, + TEXT, +} from "@/desktop/storage-harness/gen"; + +const ROOT = join(import.meta.dir, "../.."); +const HARNESS = join(ROOT, "desktop/storage-harness"); +const args = parseArgs(process.argv.slice(2)); +const OUT = args.out ?? "soak-out"; +const KILLS = Number(args.kills ?? 200); +const isWindows = process.platform === "win32"; + +mkdirSync(OUT, { recursive: true }); + +const harnessMain = join(HARNESS, "dist", "main.cjs"); +/** The harness's own Electron (its package has the dependency, not the root). */ +function electronBinary(): string { + if (!existsSync(harnessMain)) + throw new Error( + "build the harness first: cd desktop/storage-harness && bun run build", + ); + return createRequire(join(HARNESS, "package.json"))("electron") as string; +} + +type CaseResult = { + name: string; + pass: boolean; + summary: string; + details: Record; + failures: string[]; +}; + +const note = (text: string) => { + if (args.verbose) console.log(text); +}; + +/** + * Removes a temp library. On Windows, Defender or the indexer may still hold + * a file for a moment; a cleanup failure is logged, never a failed case. + */ +function removeDir(dir: string) { + try { + rmSync(dir, { + recursive: true, + force: true, + maxRetries: 10, + retryDelay: 200, + }); + } catch (error) { + console.warn(`could not remove ${dir}: ${String(error)}`); + } +} + +// ── Engine access (bun:sqlite) ────────────────────────────────────────── + +function openEngine( + dir: string, + options: Partial = {}, +): Library { + return Library.open({ + dir, + host: createNodeHost(), + openSqlite: openBunSqlite, + fullfsync: false, + ...options, + }); +} + +function textOf(library: Library, docId: string, owner = "verify") { + const loaded = library.load(docId, owner); + const doc = new Y.Doc(); + if (loaded.snapshot) Y.applyUpdate(doc, loaded.snapshot); + for (const update of loaded.updates) Y.applyUpdate(doc, update); + library.close(docId, owner); + return { + text: doc.getText(TEXT).toString(), + padLength: doc.getText(PAD).length, + maxSeq: loaded.maxSeq, + }; +} + +function seedLibrary(dir: string, padBytes: number): string { + const library = openEngine(dir); + const { id } = library.createDoc({ title: "Soak" }); + if (padBytes > 0) { + library.load(id, "seed"); + const seq = library.append(id, "seed", { + origin: "local", + update: padUpdate(padBytes), + }); + const doc = new Y.Doc(); + Y.applyUpdate(doc, padUpdate(padBytes)); + library.compact(id, "seed", Y.encodeStateAsUpdate(doc), seq); + library.close(id, "seed"); + } + library.shutdown(); + return id; +} + +// ── Electron runs ─────────────────────────────────────────────────────── + +type Run = { + lines: string[]; + exitCode: number | null; + stderr: string; + pid: number; +}; + +function pidGone(pid: number): boolean { + if (isWindows) { + const out = Bun.spawnSync(["tasklist", "/FI", `PID eq ${pid}`, "/NH"]); + return !out.stdout.toString().includes(` ${pid} `); + } + try { + process.kill(pid, 0); + return false; + } catch (error) { + return (error as { code?: string }).code === "ESRCH"; + } +} + +/** + * Starts the harness and feeds each stdout line to `onLine`, which may + * return "kill" to SIGKILL the process. Resolves once the process exited + * and its pid is gone. + */ +async function runHarness( + harnessArgs: string[], + onLine: (line: string, kill: () => void) => void = () => {}, + timeoutMs = 120_000, +): Promise { + const proc = Bun.spawn([electronBinary(), harnessMain, ...harnessArgs], { + stdout: "pipe", + stderr: "pipe", + env: { ...process.env, ELECTRON_ENABLE_STACK_DUMPING: "1" }, + }); + let killed = false; + const kill = () => { + if (killed) return; + killed = true; + proc.kill("SIGKILL"); + }; + const timer = setTimeout(kill, timeoutMs); + const lines: string[] = []; + const decoder = new TextDecoder(); + let buffer = ""; + for await (const chunk of proc.stdout) { + buffer += decoder.decode(chunk, { stream: true }); + let newline = buffer.indexOf("\n"); + while (newline >= 0) { + const line = buffer.slice(0, newline).trimEnd(); + buffer = buffer.slice(newline + 1); + lines.push(line); + if (!killed) onLine(line, kill); + newline = buffer.indexOf("\n"); + } + } + const exitCode = await proc.exited; + clearTimeout(timer); + const stderr = await new Response(proc.stderr).text(); + for (let i = 0; i < 50 && !pidGone(proc.pid); i += 1) await Bun.sleep(100); + if (!pidGone(proc.pid)) throw new Error(`pid ${proc.pid} still running`); + return { lines, exitCode, stderr, pid: proc.pid, killed }; +} + +// ── contract: the engine DocStore cases inside the Electron worker ────── + +async function caseContract(): Promise { + const run = await runHarness(["--mode=contract"]); + const ok = run.lines.filter((l) => l.startsWith("CASE_OK")).length; + const failed = run.lines.filter((l) => l.startsWith("CASE_FAIL")); + return { + name: "contract", + pass: run.exitCode === 0 && failed.length === 0 && ok > 0, + summary: `P2.1's DocStore contract: ${ok} cases passed on node:sqlite in the Electron worker`, + details: { ok, exitCode: run.exitCode }, + failures: [ + ...failed, + ...(run.exitCode === 0 ? [] : [run.stderr.slice(0, 2000)]), + ], + }; +} + +// ── T1, T2, T3 control: kill during append or compaction ─────────────── + +type KillTarget = "append" | "compaction"; + +async function killLoop( + name: string, + target: KillTarget, + kills: number, + options: { dense?: boolean; synchronous?: "FULL" | "OFF" } = {}, +): Promise { + const dir = mkdtempSync(join(tmpdir(), `soak-${name}-`)); + const padBytes = target === "compaction" ? 5 * 1024 * 1024 : 64 * 1024; + const docId = seedLibrary(dir, padBytes); + const random = seededRandom(kills * 7919 + target.length); + const failures: string[] = []; + let inside = 0; + let afterFirstAck = 0; + let maxK = 0; + for (let i = 1; i <= kills; i += 1) { + let ackSeq = 0; + let ackedK = 0; + let last = ""; + let sawAck = false; + const delay = target === "append" ? 50 + random() * 1950 : random() * 20; + const run = await runHarness( + [ + "--mode=churn", + `--dir=${dir}`, + `--doc=${docId}`, + `--seed=${i}`, + `--target=${target}`, + `--synchronous=${options.synchronous ?? "FULL"}`, + ...(options.dense ? ["--dense"] : []), + ], + (line, kill) => { + const [word, a, b] = line.split(" "); + if (word === "ACK") { + ackSeq = Math.max(ackSeq, Number(a)); + sawAck = true; + } else if (word === "EDITS") ackedK = Math.max(ackedK, Number(b)); + if (/^(BATCH_BEGIN|ACK|COMPACT_BEGIN|COMPACT_ACK)$/.test(word ?? "")) + last = word ?? ""; + if (target === "append" && word === "READY") setTimeout(kill, delay); + if (target === "compaction" && word === "COMPACT_BEGIN") + setTimeout(kill, delay); + if (target === "compaction" && word === "READY") + setTimeout(kill, 15_000); // never compacted: still kill + }, + 60_000, + ); + if (!run.killed) { + failures.push( + `kill ${i}: exited by itself (${run.exitCode}) ${run.stderr.slice(0, 500)}`, + ); + continue; + } + if (last === "BATCH_BEGIN" || last === "COMPACT_BEGIN") inside += 1; + if (sawAck) afterFirstAck += 1; + try { + const library = openEngine(dir); + const { status } = library; + if (status.quickCheck !== null && status.quickCheck !== "ok") + failures.push(`kill ${i}: quick_check ${status.quickCheck}`); + const stored = textOf(library, docId); + library.shutdown(); + const k = editCount(stored.text); + if (k === null) failures.push(`kill ${i}: text has a gap or a torn edit`); + else { + maxK = k; + if (k < ackedK) + failures.push(`kill ${i}: lost acked edits (${k} < ${ackedK})`); + } + if (stored.maxSeq < ackSeq) + failures.push( + `kill ${i}: lost acked seq (${stored.maxSeq} < ${ackSeq})`, + ); + if (stored.padLength !== padBytes) + failures.push(`kill ${i}: pad is ${stored.padLength}, not ${padBytes}`); + } catch (error) { + failures.push(`kill ${i}: reopen failed: ${String(error)}`); + } + note( + `${name} ${i}/${kills} last=${last} acked=${ackedK} failures=${failures.length}`, + ); + } + removeDir(dir); + return { + name, + pass: failures.length === 0, + summary: `${kills} kills, ${afterFirstAck} after the first ack, ${inside} inside a transaction; ${failures.length} failures; final K ${maxK}`, + details: { kills, afterFirstAck, inside, maxK, target, ...options }, + failures: failures.slice(0, 50), + }; +} + +// ── T3: fullfsync on vs off, plus the synchronous=OFF control ───────── + +async function caseT3(): Promise { + const failures: string[] = []; + const timings: Record[] = []; + for (const fullfsync of ["1", "0"]) { + const dir = mkdtempSync(join(tmpdir(), "soak-t3-")); + const run = await runHarness([ + "--mode=commit-timing", + `--dir=${dir}`, + `--fullfsync=${fullfsync}`, + "--count=300", + ]); + removeDir(dir); + const line = run.lines.find((l) => l.startsWith("TIMING ")); + if (!line) { + failures.push( + `timing fullfsync=${fullfsync}: ${run.stderr.slice(0, 500)}`, + ); + continue; + } + const timing = JSON.parse(line.slice(7)) as { + pragmas: Record; + } & Record; + timings.push(timing); + const expectedFull = + process.platform === "darwin" && fullfsync === "1" ? 1 : 0; + if (timing.pragmas.journalMode !== "wal") + failures.push(`journal_mode ${timing.pragmas.journalMode}`); + if (timing.pragmas.synchronous !== 2) + failures.push(`synchronous ${timing.pragmas.synchronous}`); + if ( + process.platform === "darwin" && + timing.pragmas.fullfsync !== expectedFull + ) + failures.push( + `fullfsync ${timing.pragmas.fullfsync}, wanted ${expectedFull}`, + ); + } + const control = await killLoop("T3-control", "append", Math.min(KILLS, 50), { + synchronous: "OFF", + }); + failures.push(...control.failures); + return { + name: "T3", + pass: failures.length === 0, + summary: `pragmas read back as set; commit p50 ${timings + .map( + (t) => + `${Number(t.p50).toFixed(2)} ms (fullfsync ${t.fullfsync ? "on" : "off"})`, + ) + .join( + " vs ", + )}; synchronous=OFF control: ${control.summary}. Power loss itself needs owner hardware.`, + details: { timings, control: control.details }, + failures, + }; +} + +// ── T4: quit with writes in flight ───────────────────────────────────── + +async function caseT4(runs: number): Promise { + const dir = mkdtempSync(join(tmpdir(), "soak-t4-")); + const docId = seedLibrary(dir, 64 * 1024); + const random = seededRandom(4); + const failures: string[] = []; + let clean = 0; + for (let i = 1; i <= runs; i += 1) { + const quitAfter = Math.round(300 + random() * 2700); + const run = await runHarness([ + "--mode=churn", + `--dir=${dir}`, + `--doc=${docId}`, + `--seed=${100 + i}`, + `--quit-after-ms=${quitAfter}`, + ]); + const quit = run.lines.find((l) => l.startsWith("QUIT ")); + if (run.exitCode !== 0 || !quit) { + failures.push( + `run ${i}: exit ${run.exitCode} ${run.stderr.slice(0, 500)}`, + ); + continue; + } + const [, outcome, kText] = quit.split(" "); + if (outcome === "clean") clean += 1; + else failures.push(`run ${i}: shutdown ${outcome}`); + if (existsSync(join(dir, LOCK_FILE))) + failures.push(`run ${i}: lock left behind`); + const wal = join(dir, `${LIBRARY_FILE}-wal`); + if (existsSync(wal) && statSync(wal).size > 0) + failures.push(`run ${i}: WAL not checkpointed (${statSync(wal).size} B)`); + const library = openEngine(dir); + if (library.status.uncleanExit) + failures.push(`run ${i}: unclean_exit still set`); + const k = editCount(textOf(library, docId).text); + library.shutdown(); + if (k !== Number(kText)) + failures.push(`run ${i}: ${k} edits stored, ${kText} typed before quit`); + } + removeDir(dir); + return { + name: "T4", + pass: failures.length === 0, + summary: `${runs} quits with edits in flight: ${clean} clean shutdowns, every typed edit stored`, + details: { runs, clean }, + failures, + }; +} + +// ── T5: migration interrupted ────────────────────────────────────────── + +function stepTables(dir: string) { + const db = new Database(join(dir, LIBRARY_FILE)); + const counts: Record = {}; + for (const step of T5_STEPS) { + const exists = db + .query("SELECT 1 FROM sqlite_master WHERE name = ?") + .get(`soak_step_${step.to}`); + if (exists) + counts[step.to] = ( + db.query(`SELECT COUNT(*) AS n FROM soak_step_${step.to}`).get() as { + n: number; + } + ).n; + } + const check = ( + db.query("PRAGMA quick_check").get() as { quick_check: string } + ).quick_check; + db.close(); + return { counts, check }; +} + +async function caseT5(kills: number): Promise { + const failures: string[] = []; + const reached: Record = {}; + // Calibrate: how long a full migration takes on this runner. + const calibrationDir = mkdtempSync(join(tmpdir(), "soak-t5-")); + seedLibrary(calibrationDir, 0); + const t0 = performance.now(); + const calibration = await runHarness([ + "--mode=migrate", + `--dir=${calibrationDir}`, + ]); + const fullMs = performance.now() - t0; + if (!calibration.lines.some((l) => l === `MIGRATED ${T5_TARGET} null`)) + failures.push( + `calibration: ${calibration.lines.join(" | ")} ${calibration.stderr.slice(0, 500)}`, + ); + removeDir(calibrationDir); + const random = seededRandom(5); + for (let i = 1; i <= kills; i += 1) { + const dir = mkdtempSync(join(tmpdir(), "soak-t5-")); + const docId = seedLibrary(dir, 4096); + const delay = random() * fullMs; + await runHarness(["--mode=migrate", `--dir=${dir}`], (line, kill) => { + if (line === "READY") setTimeout(kill, delay); + }); + // As an app at format 1 sees it: a newer library opens read-only. + const probe = openEngine(dir); + const version = probe.status.formatVersion; + probe.shutdown(); + reached[version] = (reached[version] ?? 0) + 1; + const { counts, check } = stepTables(dir); + if (check !== "ok") failures.push(`kill ${i}: quick_check ${check}`); + for (const step of T5_STEPS) { + const rows = counts[step.to]; + if (step.to <= version && rows !== STEP_ROWS) + failures.push( + `kill ${i}: v${version} but step ${step.to} has ${rows} rows`, + ); + if (step.to > version && rows !== undefined) + failures.push( + `kill ${i}: v${version} but step ${step.to}'s table exists`, + ); + } + // The migrating app finishes the job. + const library = openEngine(dir, { + formatVersion: T5_TARGET, + formatSteps: T5_STEPS, + }); + if (library.status.formatVersion !== T5_TARGET || library.status.readOnly) + failures.push( + `kill ${i}: resume reached v${library.status.formatVersion} ${library.status.readOnly}`, + ); + const pad = textOf(library, docId).padLength; + library.shutdown(); + if (pad !== 4096) failures.push(`kill ${i}: document damaged (${pad})`); + removeDir(dir); + } + return { + name: "T5", + pass: failures.length === 0, + summary: `${kills} kills during a 3-step migration (${Math.round(fullMs)} ms); stopped at v1–v4: ${JSON.stringify(reached)}; each step all-or-nothing, every resume reached v${T5_TARGET}`, + details: { kills, fullMs, reached }, + failures, + }; +} + +// ── T6: a newer library is read-only ─────────────────────────────────── + +async function caseT6(): Promise { + const dir = mkdtempSync(join(tmpdir(), "soak-t6-")); + seedLibrary(dir, 1024); + const db = new Database(join(dir, LIBRARY_FILE)); + db.exec("UPDATE meta SET value = '9' WHERE key = 'format_version'"); + db.exec("PRAGMA wal_checkpoint(TRUNCATE)"); + db.close(); + const hash = () => + createHash("sha256") + .update(readFileSync(join(dir, LIBRARY_FILE))) + .digest("hex"); + const before = hash(); + const run = await runHarness(["--mode=readonly", `--dir=${dir}`]); + const after = hash(); + removeDir(dir); + const failures: string[] = []; + const status = run.lines.find((l) => l.startsWith("STATUS ")); + if (!status || JSON.parse(status.slice(7)).readOnly !== "library_too_new") + failures.push(`status: ${status}`); + if (!run.lines.includes("WRITE refused library_too_new")) + failures.push(`write: ${run.lines.find((l) => l.startsWith("WRITE"))}`); + if (!run.lines.includes("SIDEBAR 1")) + failures.push("the newer library's list didn't load"); + if (before !== after) failures.push("library.sqlite changed"); + if (run.exitCode !== 0) + failures.push(`exit ${run.exitCode} ${run.stderr.slice(0, 500)}`); + return { + name: "T6", + pass: failures.length === 0, + summary: + "a format-9 library opened read-only in the Electron worker: list shown, writes refused, file byte-identical", + details: { before, after }, + failures, + }; +} + +// ── T8: a year of editing, then startup with 1,000 documents ────────── + +/** + * Architecture §10 targets, from process start: "Worker ready" and + * "Sidebar populated" (Mac means an M1, Win a mid-range laptop; Linux uses + * the Windows row). CI applies §10's 1.5× slack to the sidebar gate. + */ +function budgets() { + return process.platform === "darwin" + ? { workerReadyMs: 150, sidebarMs: 600 } + : { workerReadyMs: 300, sidebarMs: 1000 }; +} + +async function caseT8(): Promise { + const docs = Number(args.docs ?? 1000); + const docBytes = Number(args["doc-bytes"] ?? 200 * 1024); + const days = Number(args.days ?? 365); + const dir = mkdtempSync(join(tmpdir(), "soak-t8-")); + const failures: string[] = []; + const clock = { now: Date.UTC(2026, 0, 1, 9) }; + const host = createNodeHost({ now: () => clock.now }); + const open = () => + Library.open({ dir, host, openSqlite: openBunSqlite, fullfsync: false }); + let library = open(); + const random = seededRandom(8); + const started = performance.now(); + + // Seed: 1,000 documents of about 200 KB in 30 folders, with tags. + const folders = Array.from( + { length: 30 }, + (_, i) => library.createFolder({ name: `Folder ${i}` }).id, + ); + const tags = Array.from( + { length: 20 }, + (_, i) => library.createTag(`tag-${i}`).id, + ); + const template = new Y.Doc(); + template.getText(PAD).insert(0, "p".repeat(docBytes)); + const templateState = Y.encodeStateAsUpdate(template); + const ids: string[] = []; + const createSeeded = () => { + const { id } = library.createDoc({ + title: `Document ${ids.length}`, + folderId: folders[Math.floor(random() * folders.length)] ?? null, + }); + library.load(id, "seed"); + library.compact(id, "seed", templateState, 0); + library.close(id, "seed"); + const picked = tags.filter(() => random() < 0.08); + if (picked.length) library.setDocTags(id, picked); + ids.push(id); + return id; + }; + for (let i = 0; i < docs; i += 1) createSeeded(); + const seededBytes = library.stats().bytes; + + // References for a few documents, checked at the end. + const watched = new Map( + ids.slice(0, 5).map((id) => [id, ""]), + ); + const monthly: Record[] = []; + // How long each daily VACUUM INTO blocked the worker: a quit flush queues + // behind it (D-A2's "a clean quit loses nothing" needs it under ~3 s). + const copyMs: number[] = []; + let appends = 0; + let compactions = 0; + let trashed = 0; + + for (let day = 0; day < days; day += 1) { + const today = new Set( + [...watched.keys()].filter(() => random() < 0.3), + ); + while (today.size < 20) + today.add(ids[Math.floor(random() * ids.length)] as string); + for (const id of today) { + // An editing session: hydrate, type in batches, compact on close. + const loaded = library.load(id, "w"); + const doc = new Y.Doc(); + if (loaded.snapshot) Y.applyUpdate(doc, loaded.snapshot); + for (const u of loaded.updates) Y.applyUpdate(doc, u); + let acked = loaded.maxSeq; + let rowsSinceSnapshot = loaded.updates.length; + const batches = 10 + Math.floor(random() * 30); + for (let b = 0; b < batches; b += 1) { + let update: Uint8Array = new Uint8Array(); + doc.once("update", (u: Uint8Array) => { + update = u; + }); + const words = `w${day}-${b} `.repeat(30); + doc.getText(TEXT).insert(doc.getText(TEXT).length, words); + acked = library.append(id, "w", { + origin: "local", + update, + title: `Document ${id.slice(0, 4)}`, + // A list-view snippet as long as the real one, so the sidebar + // payload is realistic. + snippet: words.repeat(2).slice(0, 200), + }); + appends += 1; + rowsSinceSnapshot += 1; + clock.now += 1000; + if (rowsSinceSnapshot > 500) { + library.compact(id, "w", Y.encodeStateAsUpdate(doc), acked); + compactions += 1; + rowsSinceSnapshot = 0; + } + } + library.compact(id, "w", Y.encodeStateAsUpdate(doc), acked); + compactions += 1; + library.close(id, "w"); + if (watched.has(id)) watched.set(id, doc.getText(TEXT).toString()); + } + // One new document a day, and one old one trashed (purged after 30 days). + createSeeded(); + const victim = ids.splice( + 5 + Math.floor(random() * (ids.length - 6)), + 1, + )[0]; + if (victim) { + library.trashDoc(victim); + trashed += 1; + } + // Idle: the daily copy and the Trash purge. + clock.now += IDLE_MS; + const idle = library.runIdleJobs(); + if (idle.dailyCopyMs !== null) copyMs.push(idle.dailyCopyMs); + if (idle.dailyCopy === null && idle.dailyCopyMs !== null) + failures.push( + `day ${day}: daily copy failed (${library.stats().lastDailyCopyError})`, + ); + // Restart now and then, sometimes uncleanly. + if (day % 30 === 29) { + if (random() < 0.5) library.shutdown(); + else (library as unknown as { db: { close(): void } }).db.close(); + library = open(); + if ( + library.status.quickCheck !== null && + library.status.quickCheck !== "ok" + ) + failures.push(`day ${day}: quick_check ${library.status.quickCheck}`); + } + if (day % 30 === 0 || day === days - 1) { + const stats = library.stats(); + monthly.push({ + day, + mb: +(stats.bytes / 1048576).toFixed(1), + docs: stats.docs, + pendingRows: stats.pendingRows, + dailyCopies: library.listDailyCopies().length, + }); + } + clock.now = Date.UTC(2026, 0, 2 + day, 9); + } + + const stats = library.stats(); + const dailies = library.listDailyCopies(); + if (dailies.length !== Math.min(DAILY_KEEP, days)) + failures.push(`${dailies.length} daily copies kept, wanted ${DAILY_KEEP}`); + if (stats.pendingRows !== 0) + failures.push(`${stats.pendingRows} rows left uncompacted`); + for (const [id, expected] of watched) { + if (!ids.includes(id)) continue; + const { text } = textOf(library, id); + if (text !== expected) failures.push(`watched document ${id} lost text`); + } + // Growth: the year's text is small next to the seed; the library must not + // keep history it no longer needs. + const growth = stats.bytes / seededBytes; + if (growth > 1.5) + failures.push(`library grew ${growth.toFixed(2)}× in a year`); + const liveDocs = library.sidebar().docs.length; + library.shutdown(); + const simMs = performance.now() - started; + + // Startup with the year-end library: worker ready and sidebar rows. + // `--no-electron` checks the simulation alone (local runs). + const startups: Record[] = []; + for (let i = 0; i < (args["no-electron"] ? 0 : 5); i += 1) { + const run = await runHarness(["--mode=startup", `--dir=${dir}`]); + const line = run.lines.find((l) => l.startsWith("STARTUP ")); + if (!line) { + failures.push(`startup ${i}: ${run.stderr.slice(0, 500)}`); + continue; + } + startups.push(JSON.parse(line.slice(8))); + } + const budget = budgets(); + const median = (key: string) => { + const values = startups.map((s) => Number(s[key])).sort((a, b) => a - b); + return values[Math.floor(values.length / 2)] ?? Number.NaN; + }; + const toSidebar = median("processToSidebarMs"); + const toWorkerReady = median("processToReadyMs"); + if (!args["no-electron"] && !(toSidebar <= budget.sidebarMs * 1.5)) + failures.push( + `sidebar rows ${toSidebar.toFixed(0)} ms after process start, budget ${budget.sidebarMs} ms (× 1.5 CI slack)`, + ); + if (startups.some((s) => s.docs !== liveDocs)) + failures.push( + `startup listed ${startups.map((s) => s.docs)} documents, wanted ${liveDocs}`, + ); + // §10 "After an unclean exit": quick_check runs inside the open. + let unclean: Record | null = null; + if (!args["no-electron"]) { + const db = new Database(join(dir, LIBRARY_FILE)); + db.exec("UPDATE meta SET value = '1' WHERE key = 'unclean_exit'"); + db.close(); + const run = await runHarness(["--mode=startup", `--dir=${dir}`]); + const line = run.lines.find((l) => l.startsWith("STARTUP ")); + if (line) unclean = JSON.parse(line.slice(8)); + if (!unclean?.uncleanExit) + failures.push(`unclean startup: ${line ?? run.stderr.slice(0, 500)}`); + else if (unclean.openMs > 2000) + failures.push( + `quick_check open took ${unclean.openMs.toFixed(0)} ms, budget 2 s`, + ); + } + const sortedCopies = [...copyMs].sort((a, b) => a - b); + const copyMedian = sortedCopies[Math.floor(sortedCopies.length / 2)] ?? 0; + const copyMax = sortedCopies.at(-1) ?? 0; + removeDir(dir); + return { + name: "T8", + pass: failures.length === 0, + summary: `${days} days, ${appends} appends, ${compactions} compactions, ${trashed} trashed; ${(seededBytes / 1048576).toFixed(0)} → ${(stats.bytes / 1048576).toFixed(0)} MB; ${dailies.length} daily copies (VACUUM INTO median ${copyMedian.toFixed(0)} ms, max ${copyMax.toFixed(0)} ms); ${liveDocs} documents: worker ready ${toWorkerReady.toFixed(0)} ms and sidebar rows ${toSidebar.toFixed(0)} ms after process start (median of 5; §10 ${budget.workerReadyMs} / ${budget.sidebarMs} ms; excludes renderer IPC and paint); unclean-exit open with quick_check ${unclean ? unclean.openMs.toFixed(0) : "n/a"} ms`, + details: { + days, + docs: liveDocs, + appends, + compactions, + trashed, + seededBytes, + finalBytes: stats.bytes, + monthly, + startups, + unclean, + budget, + dailyCopyMs: { median: copyMedian, max: copyMax, count: copyMs.length }, + simMs, + }, + failures, + }; +} + +// ── Main ──────────────────────────────────────────────────────────────── + +const CASES: Record Promise> = { + contract: caseContract, + T1: () => killLoop("T1", "append", KILLS), + "T1-dense": () => + killLoop("T1-dense", "append", Math.ceil(KILLS / 2), { dense: true }), + T2: () => killLoop("T2", "compaction", KILLS), + T3: caseT3, + T4: () => caseT4(Number(args.quits ?? 20)), + T5: () => caseT5(Number(args["migration-kills"] ?? 40)), + T6: caseT6, + T8: caseT8, +}; + +const selected = + !args.case || args.case === "all" + ? Object.keys(CASES) + : args.case.split(",").map((name) => name.trim()); + +const results: CaseResult[] = []; +for (const name of selected) { + const run = CASES[name]; + if (!run) throw new Error(`unknown case ${name}`); + const t0 = performance.now(); + let result: CaseResult; + try { + result = await run(); + } catch (error) { + result = { + name, + pass: false, + summary: "crashed", + details: {}, + failures: [String(error instanceof Error ? error.stack : error)], + }; + } + result.details.seconds = Math.round((performance.now() - t0) / 1000); + results.push(result); + writeFileSync(join(OUT, `${name}.json`), JSON.stringify(result, null, 2)); + console.log(`${result.pass ? "PASS" : "FAIL"} ${name}: ${result.summary}`); + for (const failure of result.failures.slice(0, 10)) + console.log(` - ${failure}`); +} + +const table = [ + `### Desktop storage soak (${process.platform}-${process.arch})`, + "", + "| Case | Result | Summary |", + "|---|---|---|", + ...results.map( + (r) => + `| ${r.name} | ${r.pass ? "pass" : "**fail**"} | ${r.summary.replace(/\|/g, "\\|")} |`, + ), + "", +].join("\n"); +if (process.env.GITHUB_STEP_SUMMARY) + appendFileSync(process.env.GITHUB_STEP_SUMMARY, table); +process.exit(results.every((r) => r.pass) ? 0 : 1); diff --git a/tests/unit/api/documents-close-restore.test.ts b/tests/unit/api/documents-close-restore.test.ts index e2143b20..21d43c8d 100644 --- a/tests/unit/api/documents-close-restore.test.ts +++ b/tests/unit/api/documents-close-restore.test.ts @@ -8,9 +8,9 @@ import { MAX_TABS_PER_CLIENT } from "@/lib/constants"; import { bootstrapDocumentActivityTable } from "@/lib/security/activity-store"; import { importFresh, resetModules } from "@/tests/helpers/import-fresh"; -type DeleteRoute = typeof import("@/app/api/documents/[id]/route"); -type RestoreRoute = typeof import("@/app/api/documents/restore/route"); -type ClosedRoute = typeof import("@/app/api/documents/closed/route"); +type DeleteRoute = typeof import("@/app/api/documents/[id]/route.web"); +type RestoreRoute = typeof import("@/app/api/documents/restore/route.web"); +type ClosedRoute = typeof import("@/app/api/documents/closed/route.web"); const ID = "11111111-1111-4111-8111-111111111111"; const DAY_MS = 86_400_000; @@ -69,11 +69,11 @@ function tombstone(name: string): void { } const loadDelete = () => - importFresh("@/app/api/documents/[id]/route"); + importFresh("@/app/api/documents/[id]/route.web"); const loadRestore = () => - importFresh("@/app/api/documents/restore/route"); + importFresh("@/app/api/documents/restore/route.web"); const loadClosed = () => - importFresh("@/app/api/documents/closed/route"); + importFresh("@/app/api/documents/closed/route.web"); function params(id: string) { return { params: Promise.resolve({ id }) }; diff --git a/tests/unit/api/documents-delete-rate-limit.test.ts b/tests/unit/api/documents-delete-rate-limit.test.ts index 2ef82446..0cbd327b 100644 --- a/tests/unit/api/documents-delete-rate-limit.test.ts +++ b/tests/unit/api/documents-delete-rate-limit.test.ts @@ -2,14 +2,14 @@ import { afterEach, describe, expect, it, vi } from "bun:test"; import { importFresh, resetModules } from "@/tests/helpers/import-fresh"; -type DeleteRouteModule = typeof import("@/app/api/documents/[id]/route"); +type DeleteRouteModule = typeof import("@/app/api/documents/[id]/route.web"); const INVALID_ID_PARAMS = { params: Promise.resolve({ id: "../bad-document-id" }), }; function loadDeleteRoute(): Promise { - return importFresh("@/app/api/documents/[id]/route"); + return importFresh("@/app/api/documents/[id]/route.web"); } function deleteRequest(headers: Record): Request { diff --git a/tests/unit/ci/import-boundaries.test.ts b/tests/unit/ci/import-boundaries.test.ts new file mode 100644 index 00000000..63e28f0d --- /dev/null +++ b/tests/unit/ci/import-boundaries.test.ts @@ -0,0 +1,129 @@ +/** + * Import boundaries (desktop architecture §3.3). Imports are read with + * `Bun.Transpiler().scanImports()` (type-only imports are dropped, as at + * runtime) and followed transitively through relative and `@/` paths. + * + * Rows checked so far: the storage engine, the storage worker, and + * `lib/platform/desktop`. P2.5 adds the main, preload and renderer rows. + */ +import { describe, expect, test } from "bun:test"; +import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"; +import { dirname, join, relative, resolve } from "node:path"; + +const ROOT = resolve(import.meta.dir, "../../.."); +const transpilers = { + ts: new Bun.Transpiler({ loader: "ts" }), + tsx: new Bun.Transpiler({ loader: "tsx" }), +}; + +function filesUnder(dir: string): string[] { + const out: string[] = []; + for (const entry of readdirSync(dir)) { + const path = join(dir, entry); + if (statSync(path).isDirectory()) out.push(...filesUnder(path)); + else if (/\.tsx?$/.test(entry) && !entry.endsWith(".d.ts")) out.push(path); + } + return out; +} + +function resolveLocal(from: string, specifier: string): string | null { + let base: string; + if (specifier.startsWith("@/")) base = join(ROOT, specifier.slice(2)); + else if (specifier.startsWith(".")) base = resolve(dirname(from), specifier); + else return null; + for (const candidate of [ + base, + `${base}.ts`, + `${base}.tsx`, + join(base, "index.ts"), + join(base, "index.tsx"), + ]) + if (existsSync(candidate) && statSync(candidate).isFile()) return candidate; + throw new Error(`cannot resolve ${specifier} from ${relative(ROOT, from)}`); +} + +/** Every module `entry` reaches at runtime: local files and bare specifiers. */ +function reach(entries: string[]): { + files: Set; + bare: Map; +} { + const files = new Set(); + const bare = new Map(); + const queue = [...entries]; + while (queue.length > 0) { + const file = queue.pop() as string; + if (files.has(file)) continue; + files.add(file); + const transpiler = file.endsWith(".tsx") ? transpilers.tsx : transpilers.ts; + for (const { path } of transpiler.scanImports(readFileSync(file, "utf8"))) { + const local = resolveLocal(file, path); + if (local) queue.push(local); + else if (!bare.has(path)) bare.set(path, relative(ROOT, file)); + } + } + return { files, bare }; +} + +const rel = (path: string) => relative(ROOT, path).split("\\").join("/"); + +describe("desktop/storage/engine", () => { + const { files, bare } = reach( + filesUnder(join(ROOT, "desktop/storage/engine")), + ); + + test("imports no electron, node:*, bun:*, React or Tiptap", () => { + const banned = [...bare.entries()].filter( + ([spec]) => + /^(electron|node:|bun:|react|react-dom|@tiptap\/)/.test(spec) || + /^(fs|path|os|worker_threads|child_process)$/.test(spec), + ); + expect(banned).toEqual([]); + }); + + test("stays inside desktop/storage/engine", () => { + const outside = [...files] + .map(rel) + .filter((file) => !file.startsWith("desktop/storage/engine/")); + expect(outside).toEqual([]); + }); +}); + +describe("desktop/storage", () => { + // Architecture §3.3: main and storage may reach only these parts of lib/. + const LIB_ALLOWED = [ + /^lib\/security\/content-security-policy\.ts$/, + /^lib\/doc-migrations\//, + /^lib\/prefs\/schema\.ts$/, + /^lib\/comments\/validate\.ts$/, + /^lib\/assets\//, + // Pure name lists the import guard checks against (amended in §3.3). + /^lib\/schema-names\.ts$/, + ]; + + test("reaches lib/ only through the allowlist, and never React", () => { + const { files, bare } = reach(filesUnder(join(ROOT, "desktop/storage"))); + const libFiles = [...files] + .map(rel) + .filter((file) => file.startsWith("lib/")) + .filter((file) => !LIB_ALLOWED.some((pattern) => pattern.test(file))); + expect(libFiles).toEqual([]); + expect([...bare.keys()].filter((spec) => /^react/.test(spec))).toEqual([]); + }); + + test("never imports bun:* (it runs inside Electron)", () => { + const { bare } = reach(filesUnder(join(ROOT, "desktop/storage"))); + expect([...bare.keys()].filter((spec) => spec.startsWith("bun:"))).toEqual( + [], + ); + }); +}); + +describe("lib/platform/desktop", () => { + test("never imports desktop/main, preload or storage", () => { + const { files } = reach(filesUnder(join(ROOT, "lib/platform/desktop"))); + const crossing = [...files] + .map(rel) + .filter((file) => /^desktop\/(main|preload|storage)\//.test(file)); + expect(crossing).toEqual([]); + }); +}); diff --git a/tests/unit/components/document-editor-markdown.test.ts b/tests/unit/components/document-editor-markdown.test.ts index d9b2c1d1..2b3ca9d0 100644 --- a/tests/unit/components/document-editor-markdown.test.ts +++ b/tests/unit/components/document-editor-markdown.test.ts @@ -1,18 +1,20 @@ import { describe, expect, it } from "bun:test"; -import type { HocuspocusProvider } from "@hocuspocus/provider"; import { Editor } from "@tiptap/core"; import { marked } from "marked"; +import type { Awareness } from "y-protocols/awareness"; import * as Y from "yjs"; import { buildDocumentEditorExtensions } from "@/components/document-editor/document-editor-config"; -/** The app's extensions, minus the two that need a live provider. */ +/** The app's extensions, minus the two collaboration ones (Yjs binding, carets). */ function buildEditor(): Editor { const extensions = buildDocumentEditorExtensions({ documentId: "markdown-test", ydoc: new Y.Doc(), - provider: {} as HocuspocusProvider, + awareness: {} as Awareness, + getProvider: () => null, + canWrite: () => true, onFoldChange() {}, onFilterChange() {}, onTocUpdate() {}, diff --git a/tests/unit/components/document-editor-no-provider.test.tsx b/tests/unit/components/document-editor-no-provider.test.tsx new file mode 100644 index 00000000..10a0488b --- /dev/null +++ b/tests/unit/components/document-editor-no-provider.test.tsx @@ -0,0 +1,179 @@ +import { + afterAll, + afterEach, + beforeAll, + describe, + expect, + it, + mock, + spyOn, +} from "bun:test"; + +import type { HocuspocusProvider } from "@hocuspocus/provider"; +import { Editor } from "@tiptap/core"; +import { act } from "react"; +import { createRoot, type Root } from "react-dom/client"; +import { Awareness } from "y-protocols/awareness"; +import * as Y from "yjs"; + +import * as yjsDocumentModule from "@/hooks/use-yjs-document"; +import * as hocuspocusModule from "@/lib/hocuspocus"; + +( + globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean } +).IS_REACT_ACT_ENVIRONMENT = true; + +type YjsDocument = ReturnType; + +/** What the mocked session hands the editor; tests change it, then render. */ +let session: YjsDocument; + +/** Calls that would create (or reuse) the shared WebSocket. */ +let socketRequests = 0; +const socketStub = { + status: "connected", + connect() {}, + on() {}, + off() {}, +}; + +// mock.module is process-wide: the real modules go back in afterAll. +const realUseYjsDocument = yjsDocumentModule.useYjsDocument; +const realGetSocket = hocuspocusModule.getSharedHocuspocusSocket; +mock.module("@/hooks/use-yjs-document", () => ({ + ...yjsDocumentModule, + useYjsDocument: () => session, +})); +mock.module("@/lib/hocuspocus", () => ({ + ...hocuspocusModule, + getSharedHocuspocusSocket: () => { + socketRequests++; + return socketStub; + }, +})); +afterAll(() => { + mock.module("@/hooks/use-yjs-document", () => ({ + ...yjsDocumentModule, + useYjsDocument: realUseYjsDocument, + })); + mock.module("@/lib/hocuspocus", () => ({ + ...hocuspocusModule, + getSharedHocuspocusSocket: realGetSocket, + })); +}); + +const { DocumentEditor } = await import( + "@/components/document-editor/document-editor" +); + +/** Counts WebSocket constructions, whatever creates them. */ +let socketsOpened = 0; +const RealWebSocket = globalThis.WebSocket; +beforeAll(() => { + globalThis.WebSocket = class extends EventTarget { + constructor() { + super(); + socketsOpened++; + } + } as unknown as typeof WebSocket; +}); +afterAll(() => { + globalThis.WebSocket = RealWebSocket; +}); + +/** `useEditor` calls it when an option changes: a full view update. */ +const setOptions = spyOn(Editor.prototype, "setOptions"); +afterAll(() => setOptions.mockRestore()); + +let root: Root | undefined; +let container: HTMLElement | undefined; +let awareness: Awareness | undefined; +afterEach(async () => { + await act(async () => root?.unmount()); + container?.remove(); + awareness?.destroy(); + root = undefined; + container = undefined; + awareness = undefined; + socketRequests = 0; + socketsOpened = 0; + setOptions.mockClear(); +}); + +function localSession() { + const ydoc = new Y.Doc(); + awareness = new Awareness(ydoc); + return { + ydoc, + awareness, + provider: null, + synced: true, + serverSynced: true, + rejectedReason: null, + }; +} + +/** A provider double sharing the session's Awareness, as Live attaches. */ +const providerFor = (shared: Awareness) => + ({ + awareness: shared, + isSynced: true, + on() {}, + off() {}, + }) as unknown as HocuspocusProvider; + +async function render() { + await act(async () => { + root?.render(); + }); + // Tiptap creates the editor in an effect and emits `create` on a timer. + await act(() => new Promise((resolve) => setTimeout(resolve, 30))); +} + +async function mount() { + container = document.createElement("div"); + document.body.append(container); + root = createRoot(container); + await render(); +} + +describe("DocumentEditor without a provider", () => { + it("mounts an editable editor and opens no socket", async () => { + session = localSession(); + await mount(); + expect(container?.querySelector(".document-editor")).not.toBeNull(); + expect(window.__tiptap_editor?.isEditable).toBe(true); + // The connection chip (and its socket) belongs to a provider only. + expect(container?.querySelector("[data-collab-status]")).toBeNull(); + expect(socketRequests).toBe(0); + expect(socketsOpened).toBe(0); + }); + + it("keeps its extensions when a provider attaches", async () => { + const local = localSession(); + session = local; + await mount(); + const editor = window.__tiptap_editor; + const optionCalls = setOptions.mock.calls.length; + + session = { ...local, provider: providerFor(local.awareness) }; + await render(); + expect(window.__tiptap_editor).toBe(editor); + expect(setOptions.mock.calls.length).toBe(optionCalls); + // With a provider, the chip and its connection come back. + expect(socketRequests).toBeGreaterThan(0); + }); + + it("would rebuild them for a new Awareness (control)", async () => { + const local = localSession(); + session = local; + await mount(); + const optionCalls = setOptions.mock.calls.length; + + const other = new Awareness(local.ydoc); + session = { ...local, awareness: other }; + await render(); + other.destroy(); + expect(setOptions.mock.calls.length).toBeGreaterThan(optionCalls); + }); +}); diff --git a/tests/unit/components/service-worker-registration.test.ts b/tests/unit/components/service-worker-registration.test.ts new file mode 100644 index 00000000..671263cd --- /dev/null +++ b/tests/unit/components/service-worker-registration.test.ts @@ -0,0 +1,57 @@ +/** + * The desktop renderer never registers the service worker (#117 follow-up): + * the worker precaches web-only pages (`SHELL_PATHS` has `/privacy`), and + * the desktop export has none of them. + */ +import { afterEach, describe, expect, it } from "bun:test"; + +import { importFresh, resetModules } from "@/tests/helpers/import-fresh"; + +type RegistrationModule = + typeof import("@/components/pwa/service-worker-registration"); + +const NODE_ENV = process.env.NODE_ENV; + +async function enabledWith(env: Record): Promise { + Object.assign(process.env, env); + const { SERVICE_WORKER_ENABLED } = await importFresh( + "@/components/pwa/service-worker-registration", + ); + return SERVICE_WORKER_ENABLED; +} + +afterEach(() => { + Object.assign(process.env, { NODE_ENV }); + delete process.env.NEXT_PUBLIC_APP_TARGET; + delete process.env.NEXT_PUBLIC_SERVICE_WORKER; + resetModules(); +}); + +describe("SERVICE_WORKER_ENABLED", () => { + it("web production build: on (unchanged)", async () => { + expect( + await enabledWith({ + NODE_ENV: "production", + NEXT_PUBLIC_APP_TARGET: "web", + }), + ).toBe(true); + }); + + it("desktop build: off", async () => { + expect( + await enabledWith({ + NODE_ENV: "production", + NEXT_PUBLIC_APP_TARGET: "desktop", + }), + ).toBe(false); + }); + + it("NEXT_PUBLIC_SERVICE_WORKER=0: off (unchanged)", async () => { + expect( + await enabledWith({ + NODE_ENV: "production", + NEXT_PUBLIC_SERVICE_WORKER: "0", + }), + ).toBe(false); + }); +}); diff --git a/tests/unit/desktop/export-paths.test.ts b/tests/unit/desktop/export-paths.test.ts new file mode 100644 index 00000000..6a9bbfe3 --- /dev/null +++ b/tests/unit/desktop/export-paths.test.ts @@ -0,0 +1,95 @@ +import { describe, expect, it } from "bun:test"; + +import { resolveExportFile } from "@/desktop/shared/export-paths"; + +/** The top of a real desktop export (`bun run build:desktop`). */ +const OUT = new Set([ + "index.html", + "index.txt", + "404.html", + "about.html", + "about.txt", + "about/__next.about.__PAGE__.txt", + "__next._tree.txt", + "icon", + "favicon.ico", + "_next/static/chunks/abc.js", + "_next/static/chunks/abc.css", + "_next/static/media/font.woff2", + "_next/static/media/service-worker.123.ts", +]); +const resolve = (path: string) => resolveExportFile(path, (f) => OUT.has(f)); + +describe("resolveExportFile", () => { + it("maps pages to their .html file", () => { + expect(resolve("/")).toEqual({ + file: "index.html", + contentType: "text/html; charset=utf-8", + }); + expect(resolve("/about")?.file).toBe("about.html"); + expect(resolve("/about/")?.file).toBe("about.html"); + }); + + it("serves RSC payloads under their exported names", () => { + expect(resolve("/about.txt")).toEqual({ + file: "about.txt", + contentType: "text/plain; charset=utf-8", + }); + expect(resolve("/about/__next.about.__PAGE__.txt")?.file).toBe( + "about/__next.about.__PAGE__.txt", + ); + expect(resolve("/__next._tree.txt")?.file).toBe("__next._tree.txt"); + }); + + it("gives the extension-less icon its image type", () => { + expect(resolve("/icon")).toEqual({ + file: "icon", + contentType: "image/png", + }); + expect(resolve("/favicon.ico")?.contentType).toBe("image/x-icon"); + }); + + it("types static assets", () => { + expect(resolve("/_next/static/chunks/abc.js")?.contentType).toBe( + "text/javascript; charset=utf-8", + ); + expect(resolve("/_next/static/chunks/abc.css")?.contentType).toBe( + "text/css; charset=utf-8", + ); + expect(resolve("/_next/static/media/font.woff2")?.contentType).toBe( + "font/woff2", + ); + }); + + it("refuses files with no known type", () => { + expect(resolve("/_next/static/media/service-worker.123.ts")).toBeNull(); + }); + + it("returns null for web-only and unknown routes", () => { + for (const path of ["/privacy", "/api/documents/x", "/sitemap.xml", "/x"]) { + expect(resolve(path)).toBeNull(); + } + }); + + it("refuses traversal and malformed paths before any lookup", () => { + const looked: string[] = []; + const spy = (f: string) => { + looked.push(f); + return true; + }; + for (const path of [ + "/../etc/passwd", + "/%2e%2e/etc/passwd", + "/_next/%2e%2e/%2e%2e/secret.txt", + "/a//b.js", + "/./index.html", + "/..%5csecret.txt", + "/%00.html", + "/%E0%A4%A", + "relative.html", + ]) { + expect(resolveExportFile(path, spy)).toBeNull(); + } + expect(looked).toEqual([]); + }); +}); diff --git a/tests/unit/desktop/storage/cloud-folder-and-codes.test.ts b/tests/unit/desktop/storage/cloud-folder-and-codes.test.ts new file mode 100644 index 00000000..7b522ba0 --- /dev/null +++ b/tests/unit/desktop/storage/cloud-folder-and-codes.test.ts @@ -0,0 +1,117 @@ +import { describe, expect, test } from "bun:test"; + +import { cloudFolderOf } from "@/desktop/storage/engine/cloud-folder"; +import { STORED_ORIGINS } from "@/desktop/storage/engine/content"; +import { storageErrorFrom } from "@/desktop/storage/engine/driver"; +import { STORAGE_ERROR_CODES } from "@/desktop/storage/engine/errors"; +import { + DOC_STORE_ERROR_CODES, + UPDATE_ORIGINS, +} from "@/lib/platform/doc-store"; + +const host = ( + platform: string, + env: Record = {}, + homeDir = "", +) => ({ + platform, + env, + homeDir, + realpath: (path: string) => path, +}); + +describe("cloudFolderOf", () => { + test("a user name that looks like a provider is not a sync folder", () => { + expect( + cloudFolderOf( + "/home/box/.config/TinyDocy", + host("linux", {}, "/home/box"), + ), + ).toBeNull(); + expect( + cloudFolderOf( + "/Users/dropbox/Library/Application Support/TinyDocy", + host("darwin", {}, "/Users/dropbox"), + ), + ).toBeNull(); + expect( + cloudFolderOf("/home/box/Dropbox/T", host("linux", {}, "/home/box")), + ).toBe("dropbox"); + expect( + cloudFolderOf("D:\\Dropbox\\TinyDocy", host("win32", {}, "C:\\Users\\a")), + ).toBe("dropbox"); + }); + + const cases: [string, string, Record, string | null][] = [ + ["darwin", "/Users/a/Library/Application Support/TinyDocy", {}, null], + [ + "darwin", + "/Users/a/Library/Mobile Documents/com~apple~CloudDocs/T", + {}, + "icloud", + ], + [ + "darwin", + "/Users/a/Library/CloudStorage/OneDrive-Contoso/T", + {}, + "onedrive", + ], + [ + "darwin", + "/Users/a/Library/CloudStorage/GoogleDrive-a@b.c/My Drive/T", + {}, + "google_drive", + ], + ["darwin", "/Users/a/Library/CloudStorage/SomethingNew/T", {}, "other"], + ["darwin", "/Users/a/Dropbox/T", {}, "dropbox"], + ["linux", "/home/a/.config/TinyDocy", {}, null], + ["linux", "/home/a/Dropbox (Personal)/T", {}, "dropbox"], + ["win32", "C:\\Users\\a\\AppData\\Local\\TinyDocy", {}, null], + [ + "win32", + "C:\\Users\\a\\Work Files\\TinyDocy", + { OneDriveCommercial: "c:\\users\\a\\work files" }, + "onedrive", + ], + ["win32", "C:\\Users\\a\\OneDrive - Contoso\\T", {}, "onedrive"], + ["win32", "C:\\Users\\a\\iCloudDrive\\T", {}, "icloud"], + ["win32", "D:\\OneDriveBackup\\T", {}, null], + ]; + for (const [platform, path, env, expected] of cases) + test(`${platform} ${path} → ${expected}`, () => { + expect(cloudFolderOf(path, host(platform, env))).toBe(expected as never); + }); +}); + +describe("codes and origins stay in step with the DocStore port", () => { + test("every DocStore code but the web library's is a storage code", () => { + const storage = new Set(STORAGE_ERROR_CODES); + const missing = DOC_STORE_ERROR_CODES.filter( + (code) => + !storage.has(code) && + code !== "quota_exceeded" && + code !== "build_mismatch", + ); + expect(missing).toEqual([]); + }); + + test("stored origins match UPDATE_ORIGINS", () => { + expect([...STORED_ORIGINS]).toEqual([...UPDATE_ORIGINS]); + }); +}); + +describe("storageErrorFrom", () => { + const nodeError = (errcode: number) => + Object.assign(new Error("x"), { errcode }); + test.each([ + [13, "disk_full"], + [11, "corrupt"], + [26, "corrupt"], + [19 | (8 << 8), "invalid_argument"], + [5, "locked_elsewhere"], + [8, "library_read_only"], + [10 | (12 << 8), "io_error"], + ])("SQLite %i → %s", (code, expected) => { + expect(storageErrorFrom(nodeError(code)).code).toBe(expected as never); + }); +}); diff --git a/tests/unit/desktop/storage/content.test.ts b/tests/unit/desktop/storage/content.test.ts new file mode 100644 index 00000000..8295eac7 --- /dev/null +++ b/tests/unit/desktop/storage/content.test.ts @@ -0,0 +1,416 @@ +import { afterEach, beforeEach, describe, expect, test } from "bun:test"; + +import * as Y from "yjs"; + +import { StorageError } from "@/desktop/storage/engine/errors"; +import type { Library } from "@/desktop/storage/engine/library"; +import { + crash, + createClock, + createTempDir, + createTestHost, + openTestLibrary, + type TestClock, +} from "@/tests/helpers/storage-library"; + +let temp: ReturnType; +let clock: TestClock; +let library: Library; +let docId: string; + +beforeEach(() => { + temp = createTempDir(); + clock = createClock(); + library = openTestLibrary(temp.dir, createTestHost(clock)); + docId = library.createDoc({ title: "Untitled" }).id; + library.load(docId, "w1"); +}); +afterEach(() => { + library.shutdown(); + temp.cleanUp(); +}); + +function edit(doc: Y.Doc, text: string): Uint8Array { + let update: Uint8Array = new Uint8Array(); + const capture = (u: Uint8Array) => { + update = u; + }; + doc.once("update", capture); + doc.getText("t").insert(doc.getText("t").length, text); + return update; +} + +function textOf(loaded: { + snapshot: Uint8Array | null; + updates: Uint8Array[]; +}) { + const doc = new Y.Doc(); + if (loaded.snapshot) Y.applyUpdate(doc, loaded.snapshot); + for (const update of loaded.updates) Y.applyUpdate(doc, update); + return doc.getText("t").toString(); +} + +function codeOf(run: () => unknown): string | undefined { + try { + run(); + } catch (error) { + if (error instanceof StorageError) return error.code; + throw error; + } + return undefined; +} + +describe("load and append", () => { + test("a new document loads empty at schema 0", () => { + expect(library.load(docId, "w1")).toEqual({ + snapshot: null, + updates: [], + maxSeq: 0, + schema: 0, + }); + }); + + test("appends come back in order with increasing seqs", () => { + const doc = new Y.Doc(); + library.load(docId, "w1"); + const a = library.append(docId, "w1", { + origin: "local", + update: edit(doc, "a"), + }); + const b = library.append(docId, "w1", { + origin: "local", + update: edit(doc, "b"), + }); + expect(b).toBeGreaterThan(a); + const loaded = library.load(docId, "w1"); + expect(loaded.updates).toHaveLength(2); + expect(loaded.maxSeq).toBe(b); + expect(textOf(loaded)).toBe("ab"); + }); + + test("seqs are global across documents", () => { + const other = library.createDoc().id; + library.load(other, "w2"); + const doc = new Y.Doc(); + const a = library.append(docId, "w1", { + origin: "local", + update: edit(doc, "a"), + }); + const b = library.append(other, "w2", { + origin: "local", + update: edit(doc, "b"), + }); + expect(b).toBe(a + 1); + }); + + test("an append updates the title, snippet, schema, size and modified time", () => { + clock.advance(5000); + const update = edit(new Y.Doc(), "hello"); + library.append(docId, "w1", { + origin: "migration", + update, + title: "Hello", + snippet: "hello world", + schemaTo: 2, + }); + const row = library.sidebar().docs[0]; + expect(row?.title).toBe("Hello"); + expect(row?.snippet).toBe("hello world"); + expect(row?.modifiedAt).toBe(clock.now); + expect(row?.sizeBytes).toBe(update.byteLength); + expect(library.load(docId, "w1").schema).toBe(2); + }); + + test("an append without a title keeps the old one; titles are capped", () => { + library.append(docId, "w1", { + origin: "local", + update: edit(new Y.Doc(), "x"), + title: "T".repeat(500), + }); + library.append(docId, "w1", { + origin: "local", + update: edit(new Y.Doc(), "y"), + }); + expect(library.sidebar().docs[0]?.title).toHaveLength(200); + }); + + test("appending the same bytes twice (a resend) changes nothing", () => { + const doc = new Y.Doc(); + const update = edit(doc, "once"); + library.append(docId, "w1", { origin: "local", update }); + library.append(docId, "w1", { origin: "local", update }); + expect(textOf(library.load(docId, "w1"))).toBe("once"); + }); + + test("refuses bad input and unknown documents", () => { + const update = edit(new Y.Doc(), "x"); + expect( + codeOf(() => + library.append(docId, "w1", { origin: "bogus" as "local", update }), + ), + ).toBe("invalid_argument"); + expect( + codeOf(() => + library.append(docId, "w1", { + origin: "local", + update: new Uint8Array(), + }), + ), + ).toBe("invalid_argument"); + expect( + codeOf(() => + library.append(crypto.randomUUID(), "w1", { origin: "local", update }), + ), + ).toBe("forbidden"); + expect(codeOf(() => library.load(crypto.randomUUID(), "w1"))).toBe( + "not_found", + ); + }); + + test("a failed append writes nothing", () => { + const update = edit(new Y.Doc(), "x"); + codeOf(() => + library.append(crypto.randomUUID(), "w1", { origin: "local", update }), + ); + expect(library.stats().pendingRows).toBe(0); + }); +}); + +describe("compaction (D-A3)", () => { + test("stores the snapshot and deletes the rows it covers", () => { + const doc = new Y.Doc(); + library.load(docId, "w1"); + library.append(docId, "w1", { origin: "local", update: edit(doc, "a") }); + const covered = library.append(docId, "w1", { + origin: "local", + update: edit(doc, "b"), + }); + const state = Y.encodeStateAsUpdate(doc); + const late = library.append(docId, "w1", { + origin: "local", + update: edit(doc, "c"), + }); + expect(library.compact(docId, "w1", state, covered)).toEqual({ + foreign: null, + }); + const loaded = library.load(docId, "w1"); + expect(loaded.updates).toHaveLength(1); + expect(loaded.maxSeq).toBe(late); + expect(textOf(loaded)).toBe("abc"); + expect(library.sidebar().docs[0]?.sizeBytes).toBe( + state.byteLength + (loaded.updates[0]?.byteLength ?? 0), + ); + }); + + test("maxSeq is the snapshot's when every row is folded in", () => { + const doc = new Y.Doc(); + const seq = library.append(docId, "w1", { + origin: "local", + update: edit(doc, "a"), + }); + library.compact(docId, "w1", Y.encodeStateAsUpdate(doc), seq); + expect(library.load(docId, "w1")).toMatchObject({ + updates: [], + maxSeq: seq, + }); + }); + + test("a seq is never reused after compaction deletes the newest rows", () => { + const doc = new Y.Doc(); + const seq = library.append(docId, "w1", { + origin: "local", + update: edit(doc, "a"), + }); + library.compact(docId, "w1", Y.encodeStateAsUpdate(doc), seq); + library.shutdown(); + library = openTestLibrary(temp.dir, createTestHost(clock)); + library.load(docId, "w1"); + const next = library.append(docId, "w1", { + origin: "local", + update: edit(doc, "b"), + }); + expect(next).toBeGreaterThan(seq); + expect(textOf(library.load(docId, "w1"))).toBe("ab"); + }); + + test("a stale compaction never moves the snapshot back", () => { + const doc = new Y.Doc(); + const first = library.append(docId, "w1", { + origin: "local", + update: edit(doc, "a"), + }); + const oldState = Y.encodeStateAsUpdate(doc); + const second = library.append(docId, "w1", { + origin: "local", + update: edit(doc, "b"), + }); + library.compact(docId, "w1", Y.encodeStateAsUpdate(doc), second); + library.compact(docId, "w1", oldState, first); + expect(textOf(library.load(docId, "w1"))).toBe("ab"); + }); + + test("refuses an upToSeq past the document's last row", () => { + const doc = new Y.Doc(); + const seq = library.append(docId, "w1", { + origin: "local", + update: edit(doc, "a"), + }); + expect( + codeOf(() => + library.compact(docId, "w1", Y.encodeStateAsUpdate(doc), seq + 1), + ), + ).toBe("invalid_argument"); + }); + + test("stateOf merges the snapshot and rows", () => { + const doc = new Y.Doc(); + const seq = library.append(docId, "w1", { + origin: "local", + update: edit(doc, "a"), + }); + library.compact(docId, "w1", Y.encodeStateAsUpdate(doc), seq); + library.append(docId, "w1", { origin: "local", update: edit(doc, "b") }); + const copy = new Y.Doc(); + Y.applyUpdate(copy, library.stateOf(docId)); + expect(copy.getText("t").toString()).toBe("ab"); + }); +}); + +describe("one window per document (registry)", () => { + test("a second window gets already_open; the first keeps working", () => { + library.load(docId, "w1"); + expect(codeOf(() => library.load(docId, "w2"))).toBe("already_open"); + expect(library.load(docId, "w1").schema).toBe(0); + }); + + test("another window can't append or compact an open document", () => { + library.load(docId, "w1"); + const update = edit(new Y.Doc(), "x"); + expect( + codeOf(() => library.append(docId, "w2", { origin: "local", update })), + ).toBe("forbidden"); + expect(codeOf(() => library.compact(docId, "w2", update, 0))).toBe( + "forbidden", + ); + }); + + test("close and a closed window release the document", () => { + library.load(docId, "w1"); + library.close(docId, "w1"); + expect(library.load(docId, "w2").schema).toBe(0); + library.releaseOwner("w2"); + expect(library.isOpen(docId)).toBe(false); + }); + + test("closing from another window does nothing", () => { + library.load(docId, "w1"); + library.close(docId, "w2"); + expect(library.isOpen(docId)).toBe(true); + }); + + test("main's content writes refuse an open document", () => { + library.load(docId, "w1"); + expect(codeOf(() => library.purgeDoc(docId))).toBe("document_open"); + library.close(docId, "w1"); + library.purgeDoc(docId); + expect(library.sidebar().docs).toEqual([]); + }); +}); + +describe("compaction property (architecture §11)", () => { + // A seeded PRNG keeps failures reproducible. + function mulberry32(seed: number) { + let a = seed; + return () => { + a = (a + 0x6d2b79f5) | 0; + let t = Math.imul(a ^ (a >>> 15), 1 | a); + t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; + return ((t ^ (t >>> 14)) >>> 0) / 4294967296; + }; + } + + for (const seed of [1, 2, 3, 4, 5]) { + test(`random appends, compactions, crashes and reopens (seed ${seed})`, () => { + const random = mulberry32(seed); + const reference = new Y.Doc(); + // The renderer's copy: rebuilt from storage on every reopen. + let session = new Y.Doc(); + let ackedSeq = 0; + const hydrate = () => { + const loaded = library.load(docId, "w1"); + session = new Y.Doc(); + if (loaded.snapshot) Y.applyUpdate(session, loaded.snapshot); + for (const u of loaded.updates) Y.applyUpdate(session, u); + ackedSeq = loaded.maxSeq; + }; + hydrate(); + for (let step = 0; step < 300; step += 1) { + const roll = random(); + if (roll < 0.7) { + const text = session.getText("t"); + const pos = Math.floor(random() * (text.length + 1)); + let update: Uint8Array = new Uint8Array(); + session.once("update", (u: Uint8Array) => { + update = u; + }); + if (text.length > 0 && random() < 0.25) + text.delete(Math.min(pos, text.length - 1), 1); + else + text.insert( + pos, + String.fromCharCode(97 + Math.floor(random() * 26)), + ); + Y.applyUpdate(reference, update); + ackedSeq = library.append(docId, "w1", { origin: "local", update }); + } else if (roll < 0.85) { + library.compact( + docId, + "w1", + Y.encodeStateAsUpdate(session), + ackedSeq, + ); + } else if (roll < 0.95) { + library.close(docId, "w1"); + library.shutdown(); + library = openTestLibrary(temp.dir, createTestHost(clock)); + hydrate(); + } else { + crash(library); + library = openTestLibrary(temp.dir, createTestHost(clock)); + hydrate(); + } + if (step % 25 === 0 || roll >= 0.85) { + const stored = library.load(docId, "w1"); + const rebuilt = new Y.Doc(); + if (stored.snapshot) Y.applyUpdate(rebuilt, stored.snapshot); + for (const u of stored.updates) Y.applyUpdate(rebuilt, u); + expect(rebuilt.getText("t").toString()).toBe( + reference.getText("t").toString(), + ); + expect(Y.encodeStateVector(rebuilt)).toEqual( + Y.encodeStateVector(reference), + ); + } + } + }); + } +}); + +describe("claim (registry replay after a worker restart)", () => { + test("lets the holding window write again without a load", () => { + library.shutdown(); + library = openTestLibrary(temp.dir, createTestHost(clock)); + const update = edit(new Y.Doc(), "x"); + expect( + codeOf(() => library.append(docId, "w1", { origin: "local", update })), + ).toBe("forbidden"); + library.claim(docId, "w1"); + expect( + library.append(docId, "w1", { origin: "local", update }), + ).toBeGreaterThan(0); + expect(codeOf(() => library.claim(docId, "w2"))).toBe("already_open"); + expect(codeOf(() => library.claim(crypto.randomUUID(), "w2"))).toBe( + "not_found", + ); + }); +}); diff --git a/tests/unit/desktop/storage/daily-copy.test.ts b/tests/unit/desktop/storage/daily-copy.test.ts new file mode 100644 index 00000000..fc4ba1a3 --- /dev/null +++ b/tests/unit/desktop/storage/daily-copy.test.ts @@ -0,0 +1,98 @@ +import { afterEach, beforeEach, describe, expect, test } from "bun:test"; + +import * as Y from "yjs"; + +import { DAILY_KEEP, localDate } from "@/desktop/storage/engine/daily-copy"; +import { IDLE_MS, type Library } from "@/desktop/storage/engine/library"; +import { + createClock, + createTempDir, + createTestHost, + openTestLibrary, + type TestClock, +} from "@/tests/helpers/storage-library"; + +const DAY = 24 * 60 * 60 * 1000; + +let temp: ReturnType; +let clock: TestClock; +let library: Library; + +beforeEach(() => { + temp = createTempDir(); + clock = createClock(); + library = openTestLibrary(temp.dir, createTestHost(clock)); +}); +afterEach(() => { + library.shutdown(); + temp.cleanUp(); +}); + +function write(docId: string, text: string) { + if (!library.isOpen(docId)) library.load(docId, "w1"); + const doc = new Y.Doc(); + doc.getText("t").insert(0, text); + library.append(docId, "w1", { + origin: "local", + update: Y.encodeStateAsUpdate(doc), + }); +} + +describe("daily copies (D-A6)", () => { + test("waits for 30 s without a write", () => { + write(library.createDoc().id, "x"); + clock.advance(IDLE_MS - 1); + expect(library.runIdleJobs().dailyCopy).toBeNull(); + clock.advance(1); + expect(library.runIdleJobs().dailyCopy).toBe( + `library-${localDate(clock.now)}.sqlite`, + ); + }); + + test("takes one copy a day and keeps the newest 7", () => { + const docId = library.createDoc().id; + const taken: string[] = []; + for (let day = 0; day < 10; day += 1) { + write(docId, `day ${day}`); + clock.advance(IDLE_MS); + const first = library.runIdleJobs().dailyCopy; + expect(first).not.toBeNull(); + taken.push(localDate(clock.now)); + expect(library.runIdleJobs().dailyCopy).toBeNull(); + clock.advance(DAY); + } + expect(library.listDailyCopies()).toEqual(taken.slice(-DAILY_KEEP)); + }); + + test("a copy restores one document's state as of that day", () => { + const docId = library.createDoc().id; + write(docId, "before"); + clock.advance(IDLE_MS); + library.runIdleJobs(); + const day = localDate(clock.now); + write(docId, "after"); + const restored = new Y.Doc(); + Y.applyUpdate(restored, library.readDailyCopy(day, docId)); + expect(restored.getText("t").toString()).toBe("before"); + }); + + test("survives a leftover partial copy", () => { + const host = createTestHost(clock); + host.mkdirp(host.join(temp.dir, "daily")); + const partial = host.join( + temp.dir, + "daily", + `library-${localDate(clock.now)}.sqlite.partial`, + ); + host.createExclusive(partial, "junk"); + clock.advance(IDLE_MS); + expect(library.runIdleJobs().dailyCopy).not.toBeNull(); + expect(host.exists(partial)).toBe(false); + }); + + test("refuses a malformed date", () => { + expect(() => + library.readDailyCopy("../../etc", crypto.randomUUID()), + ).toThrow(); + }); +}); diff --git a/tests/unit/desktop/storage/doc-store-contract.test.ts b/tests/unit/desktop/storage/doc-store-contract.test.ts new file mode 100644 index 00000000..89f4142c --- /dev/null +++ b/tests/unit/desktop/storage/doc-store-contract.test.ts @@ -0,0 +1,43 @@ +/** + * P2.1's shared `DocStore` contract (architecture §11) on the storage + * engine over `bun:sqlite`, through the same dispatch the worker uses. The + * Electron soak's `contract` case runs it again on `node:sqlite` inside the + * real worker. + */ +import { describe, it } from "bun:test"; + +import type { Library } from "@/desktop/storage/engine/library"; +import { defineDocStoreContract } from "@/tests/helpers/doc-store-contract"; +import { createEngineDocStore } from "@/tests/helpers/engine-doc-store"; +import { + createClock, + createTempDir, + createTestHost, + openTestLibrary, +} from "@/tests/helpers/storage-library"; + +defineDocStoreContract( + { describe, it }, + "DocStore contract on the engine (bun:sqlite)", + { + exclusiveOpen: true, + async createLibrary() { + const temp = createTempDir(); + const library: Library = openTestLibrary( + temp.dir, + createTestHost(createClock()), + ); + let clients = 0; + return { + connect: () => createEngineDocStore(library, `client-${++clients}`), + async createDoc(docId, schema) { + library.createDoc({ id: docId, schema }); + }, + async dispose() { + library.shutdown(); + temp.cleanUp(); + }, + }; + }, + }, +); diff --git a/tests/unit/desktop/storage/doc-store-engine.test.ts b/tests/unit/desktop/storage/doc-store-engine.test.ts new file mode 100644 index 00000000..5c1840b6 --- /dev/null +++ b/tests/unit/desktop/storage/doc-store-engine.test.ts @@ -0,0 +1,86 @@ +import { afterEach, beforeEach, describe, expect, test } from "bun:test"; + +import * as Y from "yjs"; + +import { IDLE_MS, type Library } from "@/desktop/storage/engine/library"; +import { TRASH_RETENTION_MS } from "@/desktop/storage/engine/library-index"; +import { dispatch } from "@/desktop/storage/protocol"; +import { + createClock, + createTempDir, + createTestHost, + openTestLibrary, +} from "@/tests/helpers/storage-library"; + +let temp: ReturnType; +let library: Library; + +beforeEach(() => { + temp = createTempDir(); + library = openTestLibrary(temp.dir, createTestHost(createClock())); +}); +afterEach(() => { + library.shutdown(); + temp.cleanUp(); +}); + +describe("dispatch", () => { + test("a failure comes back as an envelope, never a throw", () => { + expect( + dispatch(library, { + id: 2, + op: "load", + args: { docId: "nope", owner: "w1" }, + }), + ).toMatchObject({ + ok: false, + error: { code: "not_found", retryable: false }, + }); + }); +}); + +describe("the index change feed", () => { + test("an append that changes the title moves rev and names the document", () => { + const { id } = library.createDoc(); + library.load(id, "w1"); + library.takeIndexChanges(); + const before = library.sidebar().rev; + const doc = new Y.Doc(); + doc.getText("t").insert(0, "x"); + library.append(id, "w1", { + origin: "local", + update: Y.encodeStateAsUpdate(doc), + title: "New title", + }); + expect(library.takeIndexChanges()).toEqual({ + rev: before + 1, + changes: [{ kind: "doc", id }], + }); + expect(library.takeIndexChanges()).toBeNull(); + }); + + test("index writes report each changed row once", () => { + const folder = library.createFolder({ name: "A" }); + const { id } = library.createDoc({ folderId: folder.id }); + library.renameDoc(id, "x"); + library.moveDoc(id, null, "a"); + const tag = library.createTag("t"); + expect(library.takeIndexChanges()?.changes).toEqual([ + { kind: "folder", id: folder.id }, + { kind: "doc", id }, + { kind: "tag", id: tag.id }, + ]); + }); + + test("the idle Trash purge is announced", () => { + const clock = createClock(); + library.shutdown(); + library = openTestLibrary(temp.dir, createTestHost(clock)); + const { id } = library.createDoc(); + library.trashDoc(id); + library.takeIndexChanges(); + clock.advance(TRASH_RETENTION_MS + IDLE_MS); + expect(library.runIdleJobs().purged).toBe(1); + expect(library.takeIndexChanges()?.changes).toEqual([{ kind: "doc", id }]); + }); +}); diff --git a/tests/unit/desktop/storage/library-index.test.ts b/tests/unit/desktop/storage/library-index.test.ts new file mode 100644 index 00000000..0947972d --- /dev/null +++ b/tests/unit/desktop/storage/library-index.test.ts @@ -0,0 +1,219 @@ +import { Database } from "bun:sqlite"; +import { afterEach, beforeEach, describe, expect, test } from "bun:test"; +import { join } from "node:path"; + +import * as Y from "yjs"; + +import { StorageError } from "@/desktop/storage/engine/errors"; +import { + IDLE_MS, + LIBRARY_FILE, + type Library, +} from "@/desktop/storage/engine/library"; +import { TRASH_RETENTION_MS } from "@/desktop/storage/engine/library-index"; +import { + createClock, + createTempDir, + createTestHost, + openTestLibrary, + type TestClock, +} from "@/tests/helpers/storage-library"; + +let temp: ReturnType; +let clock: TestClock; +let library: Library; + +beforeEach(() => { + temp = createTempDir(); + clock = createClock(); + library = openTestLibrary(temp.dir, createTestHost(clock)); +}); +afterEach(() => { + library.shutdown(); + temp.cleanUp(); +}); + +function codeOf(run: () => unknown) { + try { + run(); + } catch (error) { + if (error instanceof StorageError) return error.code; + throw error; + } + return undefined; +} + +describe("creating documents", () => { + test("mints a UUID, a lineage and a 32-hex link key at insert", () => { + const a = library.createDoc(); + const b = library.createDoc(); + expect(a.id).toMatch(/^[0-9a-f-]{36}$/); + expect(a.lineage).toMatch(/^[0-9a-f-]{36}$/); + expect(a.linkKey).toMatch(/^[0-9a-f]{32}$/); + expect(a.lineage).not.toBe(b.lineage); + expect(a.linkKey).not.toBe(b.linkKey); + }); + + test("keeps a lineage and link key only when given (backup restore)", () => { + const lineage = crypto.randomUUID(); + const linkKey = "a".repeat(32); + expect(library.createDoc({ lineage, linkKey })).toMatchObject({ + lineage, + linkKey, + }); + expect(codeOf(() => library.createDoc({ linkKey }))).toBe( + "invalid_argument", + ); + }); + + test("refuses malformed ids, link keys and kinds", () => { + expect(codeOf(() => library.createDoc({ id: "../x" }))).toBe( + "invalid_argument", + ); + expect(codeOf(() => library.createDoc({ linkKey: "XYZ" }))).toBe( + "invalid_argument", + ); + expect(codeOf(() => library.createDoc({ kind: "page" as "doc" }))).toBe( + "invalid_argument", + ); + }); + + test("templates are stored with kind 'template'", () => { + library.createDoc({ kind: "template", title: "Weekly" }); + expect(library.sidebar().docs[0]?.kind).toBe("template"); + }); +}); + +describe("the sidebar snapshot", () => { + test("lists live folders, documents and tags; rev moves on every write", () => { + const start = library.sidebar().rev; + const folder = library.createFolder({ name: "Work" }); + const doc = library.createDoc({ title: "Plan", folderId: folder.id }); + const tag = library.createTag("urgent", "red"); + library.setDocTags(doc.id, [tag.id]); + const snapshot = library.sidebar(); + expect(snapshot.rev).toBe(start + 4); + expect(snapshot.folders.map((f) => f.name)).toEqual(["Work"]); + expect(snapshot.docs[0]).toMatchObject({ + id: doc.id, + title: "Plan", + folderId: folder.id, + tagIds: [tag.id], + pinned: false, + kind: "doc", + }); + expect(snapshot.tags).toEqual([ + { id: tag.id, name: "urgent", color: "red" }, + ]); + }); + + test("tag names are unique regardless of case", () => { + library.createTag("Urgent"); + expect(codeOf(() => library.createTag("urgent"))).toBe("invalid_argument"); + }); + + test("opening a document records opened_at", () => { + const doc = library.createDoc(); + clock.advance(1000); + library.load(doc.id, "w1"); + expect(library.sidebar().docs[0]?.openedAt).toBe(clock.now); + }); + + test("rename and move", () => { + const folder = library.createFolder({ name: "A" }); + const doc = library.createDoc({ title: "x" }); + library.renameDoc(doc.id, " Renamed "); + library.moveDoc(doc.id, folder.id, "m"); + expect(library.sidebar().docs[0]).toMatchObject({ + title: "Renamed", + folderId: folder.id, + sortKey: "m", + }); + expect(codeOf(() => library.renameDoc(crypto.randomUUID(), "y"))).toBe( + "not_found", + ); + }); +}); + +describe("Trash and purge", () => { + test("trash hides a document and restore brings it back to its folder", () => { + const folder = library.createFolder({ name: "A" }); + const doc = library.createDoc({ folderId: folder.id }); + library.trashDoc(doc.id); + expect(library.sidebar().docs).toEqual([]); + library.restoreDoc(doc.id); + expect(library.sidebar().docs[0]?.folderId).toBe(folder.id); + }); + + test("purge cascades to rows, snapshot, tags, view and import source", () => { + const doc = library.createDoc(); + const tag = library.createTag("t"); + library.setDocTags(doc.id, [tag.id]); + const ydoc = new Y.Doc(); + ydoc.getText("t").insert(0, "x"); + const update = Y.encodeStateAsUpdate(ydoc); + library.load(doc.id, "w1"); + const seq = library.append(doc.id, "w1", { origin: "local", update }); + library.compact(doc.id, "w1", update, seq); + library.append(doc.id, "w1", { origin: "local", update }); + library.shutdown(); + const raw = new Database(join(temp.dir, LIBRARY_FILE)); + raw.exec("PRAGMA foreign_keys = ON"); + raw + .prepare("INSERT INTO doc_view (doc_id, width) VALUES (?, 'wide')") + .run(doc.id); + raw + .prepare( + "INSERT INTO import_sources (doc_id, source_hash) VALUES (?, 'h')", + ) + .run(doc.id); + raw.close(); + library = openTestLibrary(temp.dir, createTestHost(clock)); + library.purgeDoc(doc.id); + library.shutdown(); + const check = new Database(join(temp.dir, LIBRARY_FILE)); + for (const table of [ + "updates", + "snapshots", + "doc_tags", + "doc_view", + "import_sources", + ]) { + const row = check.query(`SELECT COUNT(*) AS n FROM ${table}`).get() as { + n: number; + }; + expect(`${table}=${row.n}`).toBe(`${table}=0`); + } + check.close(); + library = openTestLibrary(temp.dir, createTestHost(clock)); + }); + + test("idle jobs empty Trash after 30 days, skipping open documents", () => { + const old = library.createDoc(); + const open = library.createDoc(); + const recent = library.createDoc(); + library.trashDoc(old.id); + library.trashDoc(open.id); + clock.advance(TRASH_RETENTION_MS - 1000); + library.trashDoc(recent.id); + library.load(open.id, "w1"); + clock.advance(IDLE_MS + 1000); + expect(library.runIdleJobs().purged).toBe(1); + expect(library.stats().docs).toBe(2); + }); +}); + +describe("ids and schema at creation", () => { + test("accepts any safe id and stores the given schema", () => { + const { id } = library.createDoc({ id: "doc-a_1", schema: 3 }); + expect(library.load(id, "w1").schema).toBe(3); + }); + + test("refuses ids that aren't safe in SQL, paths or logs", () => { + for (const id of ["", "../x", "a b", "a/b", "-x", "x".repeat(65)]) + expect(codeOf(() => library.createDoc({ id }))).toBe("invalid_argument"); + expect(codeOf(() => library.createDoc({ schema: -1 }))).toBe( + "invalid_argument", + ); + }); +}); diff --git a/tests/unit/desktop/storage/library-open.test.ts b/tests/unit/desktop/storage/library-open.test.ts new file mode 100644 index 00000000..42366f65 --- /dev/null +++ b/tests/unit/desktop/storage/library-open.test.ts @@ -0,0 +1,365 @@ +import { Database } from "bun:sqlite"; +import { afterEach, beforeEach, describe, expect, test } from "bun:test"; +import { readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; + +import { StorageError } from "@/desktop/storage/engine/errors"; +import { LIBRARY_FILE } from "@/desktop/storage/engine/library"; +import { LOCK_FILE } from "@/desktop/storage/engine/lock"; +import type { FormatStep } from "@/desktop/storage/engine/migrations"; +import { TABLES_V1 } from "@/desktop/storage/engine/schema"; +import { + crash, + createClock, + createTempDir, + createTestHost, + openTestLibrary, + type TestClock, +} from "@/tests/helpers/storage-library"; + +let temp: ReturnType; +let clock: TestClock; + +beforeEach(() => { + temp = createTempDir(); + clock = createClock(); +}); +afterEach(() => temp.cleanUp()); + +function raw(dir = temp.dir) { + return new Database(join(dir, LIBRARY_FILE)); +} + +function rejectsWith(code: string, run: () => unknown) { + let caught: unknown; + try { + run(); + } catch (error) { + caught = error; + } + expect(caught).toBeInstanceOf(StorageError); + expect((caught as StorageError).code).toBe(code as StorageError["code"]); +} + +describe("creating a library", () => { + test("creates every format-1 table and the meta rows", () => { + const library = openTestLibrary(temp.dir, createTestHost(clock)); + library.shutdown(); + const db = raw(); + const tables = db + .query( + "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name", + ) + .all() + .map((row) => (row as { name: string }).name); + expect(tables).toEqual([...TABLES_V1]); + const meta = Object.fromEntries( + db + .query("SELECT key, value FROM meta") + .all() + .map((row) => { + const { key, value } = row as { key: string; value: string }; + return [key, value]; + }), + ); + expect(meta.format_version).toBe("1"); + expect(meta.yjs_encoding).toBe("v1"); + expect(meta.library_id).toMatch(/^[0-9a-f-]{36}$/); + expect(meta.unclean_exit).toBe("0"); + db.close(); + }); + + test("the docs columns include the v7/v8 seams and the §6.3 list columns", () => { + openTestLibrary(temp.dir, createTestHost(clock)).shutdown(); + const db = raw(); + const columns = db + .query("SELECT name, \"notnull\" FROM pragma_table_info('docs')") + .all() as { name: string; notnull: number }[]; + const byName = new Map(columns.map((c) => [c.name, c.notnull])); + for (const name of [ + "lineage", + "link_key", + "kind", + "pin_key", + "size_bytes", + "snippet", + "trash_group", + "trashed_from", + "mirrored_at", + "schema", + ]) + expect(byName.has(name)).toBe(true); + expect(byName.get("link_key")).toBe(1); + expect(byName.get("lineage")).toBe(1); + const view = db + .query("SELECT name FROM pragma_table_info('doc_view')") + .all() + .map((row) => (row as { name: string }).name); + expect(view).toEqual(["doc_id", "width", "place", "remote_images"]); + db.close(); + }); + + test("sets WAL, synchronous=FULL and foreign keys", () => { + const library = openTestLibrary(temp.dir, createTestHost(clock)); + const db = ( + library as unknown as { + db: { + prepare(s: string): { get(): Record | undefined }; + }; + } + ).db; + expect(db.prepare("PRAGMA journal_mode").get()).toEqual({ + journal_mode: "wal", + }); + expect(db.prepare("PRAGMA synchronous").get()).toEqual({ synchronous: 2 }); + expect(db.prepare("PRAGMA foreign_keys").get()).toEqual({ + foreign_keys: 1, + }); + library.shutdown(); + }); + + test("turns on fullfsync on macOS", () => { + const library = openTestLibrary( + temp.dir, + createTestHost(clock, { platform: "darwin" }), + { fullfsync: true }, + ); + const db = ( + library as unknown as { + db: { + prepare(s: string): { get(): Record | undefined }; + }; + } + ).db; + expect(db.prepare("PRAGMA fullfsync").get()).toEqual({ fullfsync: 1 }); + expect(db.prepare("PRAGMA checkpoint_fullfsync").get()).toEqual({ + checkpoint_fullfsync: 1, + }); + library.shutdown(); + }); + + test("refuses a file that isn't a library", () => { + const db = raw(); + db.exec("CREATE TABLE other (x)"); + db.close(); + rejectsWith("corrupt", () => + openTestLibrary(temp.dir, createTestHost(clock)), + ); + // The lock is released on failure. + expect(() => readFileSync(join(temp.dir, LOCK_FILE))).toThrow(); + }); +}); + +describe("cloud folders", () => { + test("refuses a library inside a synced folder", () => { + const dir = join(temp.dir, "Dropbox", "TinyDocy"); + rejectsWith("cloud_folder", () => + openTestLibrary(dir, createTestHost(clock)), + ); + }); +}); + +describe("library.lock", () => { + test("refuses a library another running process holds", () => { + writeFileSync(join(temp.dir, LOCK_FILE), "424242"); + const host = createTestHost(clock, { isPidAlive: (pid) => pid === 424242 }); + rejectsWith("locked_elsewhere", () => openTestLibrary(temp.dir, host)); + }); + + test("takes over a stale lock", () => { + writeFileSync(join(temp.dir, LOCK_FILE), "424242"); + const host = createTestHost(clock, { isPidAlive: () => false }); + const library = openTestLibrary(temp.dir, host); + expect(readFileSync(join(temp.dir, LOCK_FILE), "utf8")).toBe( + String(process.pid), + ); + library.shutdown(); + expect(() => readFileSync(join(temp.dir, LOCK_FILE))).toThrow(); + }); +}); + +describe("unclean exit", () => { + test("a clean shutdown needs no quick_check", () => { + openTestLibrary(temp.dir, createTestHost(clock)).shutdown(); + const library = openTestLibrary(temp.dir, createTestHost(clock)); + expect(library.status.uncleanExit).toBe(false); + expect(library.status.quickCheck).toBeNull(); + library.shutdown(); + }); + + test("a crash runs quick_check on the next open", () => { + const first = openTestLibrary(temp.dir, createTestHost(clock)); + first.createDoc(); + crash(first); + const library = openTestLibrary(temp.dir, createTestHost(clock)); + expect(library.status.uncleanExit).toBe(true); + expect(library.status.quickCheck).toBe("ok"); + expect(library.status.readOnly).toBeNull(); + library.shutdown(); + }); + + test("shutdown checkpoints the WAL into the main file", () => { + const library = openTestLibrary(temp.dir, createTestHost(clock)); + library.createDoc({ title: "kept" }); + library.shutdown(); + const wal = join(temp.dir, `${LIBRARY_FILE}-wal`); + let walBytes = 0; + try { + walBytes = readFileSync(wal).byteLength; + } catch { + walBytes = 0; + } + expect(walBytes).toBe(0); + }); + + test("shutdown is idempotent", () => { + const library = openTestLibrary(temp.dir, createTestHost(clock)); + library.shutdown(); + expect(() => library.shutdown()).not.toThrow(); + }); +}); + +describe("format_version guard (T6)", () => { + function makeNewerLibrary() { + const library = openTestLibrary(temp.dir, createTestHost(clock)); + library.createDoc({ title: "from the future" }); + library.shutdown(); + const db = raw(); + db.exec("UPDATE meta SET value = '7' WHERE key = 'format_version'"); + db.exec("PRAGMA wal_checkpoint(TRUNCATE)"); + db.close(); + } + + test("a newer library opens read-only and is never written", () => { + makeNewerLibrary(); + const before = readFileSync(join(temp.dir, LIBRARY_FILE)); + const library = openTestLibrary(temp.dir, createTestHost(clock)); + expect(library.status.readOnly).toBe("library_too_new"); + expect(library.status.formatVersion).toBe(7); + expect(library.sidebar().docs.map((d) => d.title)).toEqual([ + "from the future", + ]); + rejectsWith("library_too_new", () => library.createDoc()); + const id = library.sidebar().docs[0]?.id ?? ""; + expect(library.load(id, "w1").updates).toEqual([]); + rejectsWith("library_too_new", () => + library.append(id, "w1", { + origin: "local", + update: new Uint8Array([1]), + }), + ); + library.shutdown(); + expect(readFileSync(join(temp.dir, LIBRARY_FILE)).equals(before)).toBe( + true, + ); + }); +}); + +describe("format migrations (T5)", () => { + const addColumn: FormatStep = { + to: 2, + up: (db) => db.exec("ALTER TABLE docs ADD COLUMN extra TEXT"), + }; + const addTable: FormatStep = { + to: 3, + up: (db) => db.exec("CREATE TABLE later (x INTEGER) STRICT"), + }; + + test("takes a pre-migration copy, then runs each step", () => { + openTestLibrary(temp.dir, createTestHost(clock)).shutdown(); + const library = openTestLibrary(temp.dir, createTestHost(clock), { + formatVersion: 3, + formatSteps: [addColumn, addTable], + }); + expect(library.status.formatVersion).toBe(3); + expect(library.status.readOnly).toBeNull(); + library.shutdown(); + const copies = createTestHost(clock) + .list(temp.dir) + .filter((f) => f.startsWith("library.pre-v1-")); + expect(copies).toHaveLength(1); + const copy = new Database(join(temp.dir, copies[0] ?? "")); + expect( + ( + copy + .query("SELECT value FROM meta WHERE key = 'format_version'") + .get() as { value: string } + ).value, + ).toBe("1"); + copy.close(); + }); + + test("a failed step leaves the library read-only at the last good version", () => { + openTestLibrary(temp.dir, createTestHost(clock)).shutdown(); + const library = openTestLibrary(temp.dir, createTestHost(clock), { + formatVersion: 3, + formatSteps: [ + addColumn, + { + to: 3, + up: (db) => { + db.exec("CREATE TABLE half (x)"); + throw new Error("boom"); + }, + }, + ], + }); + expect(library.status.readOnly).toBe("migration_failed"); + expect(library.status.formatVersion).toBe(2); + rejectsWith("library_read_only", () => library.createDoc()); + library.shutdown(); + const db = raw(); + expect( + db.query("SELECT 1 FROM sqlite_master WHERE name = 'half'").get(), + ).toBeNull(); + db.close(); + }); + + test("keeps the newest two pre-migration copies", () => { + openTestLibrary(temp.dir, createTestHost(clock)).shutdown(); + for (const to of [2, 3, 4]) { + clock.advance(60_000); + openTestLibrary(temp.dir, createTestHost(clock), { + formatVersion: to, + formatSteps: [ + { to: 2, up: () => {} }, + { to: 3, up: () => {} }, + { to: 4, up: () => {} }, + ], + }).shutdown(); + } + const copies = createTestHost(clock) + .list(temp.dir) + .filter((f) => f.startsWith("library.pre-v")) + .sort(); + expect(copies).toHaveLength(2); + expect(copies[0]).toStartWith("library.pre-v2-"); + expect(copies[1]).toStartWith("library.pre-v3-"); + }); +}); + +test("stats reads the pragmas back as set", () => { + const library = openTestLibrary(temp.dir, createTestHost(clock)); + // checkpoint_fullfsync's default differs between SQLite builds. + expect(library.stats().pragmas).toMatchObject({ + journalMode: "wal", + synchronous: 2, + fullfsync: 0, + foreignKeys: 1, + }); + library.shutdown(); +}); + +test("shutdown releases every file handle (Windows can delete the folder)", () => { + const lsof = Bun.which("lsof"); + if (!lsof) return; + const library = openTestLibrary(temp.dir, createTestHost(clock)); + library.createDoc({ title: "x" }); + library.sidebar(); + library.shutdown(); + const open = Bun.spawnSync([lsof, "-p", String(process.pid)]) + .stdout.toString() + .split("\n") + .filter((line) => line.includes(temp.dir)); + expect(open).toEqual([]); +}); diff --git a/tests/unit/editor-actions/shortcut-bindings.test.ts b/tests/unit/editor-actions/shortcut-bindings.test.ts index a390af10..9bc3faeb 100644 --- a/tests/unit/editor-actions/shortcut-bindings.test.ts +++ b/tests/unit/editor-actions/shortcut-bindings.test.ts @@ -8,7 +8,7 @@ */ import { afterEach, describe, expect, it } from "bun:test"; -import type { HocuspocusProvider } from "@hocuspocus/provider"; +import type { Awareness } from "y-protocols/awareness"; import * as Y from "yjs"; import type { buildDocumentEditorExtensions as BuildExtensions } from "@/components/document-editor/document-editor-config"; @@ -43,7 +43,9 @@ async function loadEditor(): Promise<{ const extensions = buildDocumentEditorExtensions({ documentId: "keys", ydoc: new Y.Doc(), - provider: {} as HocuspocusProvider, + awareness: {} as Awareness, + getProvider: () => null, + canWrite: () => true, onFoldChange() {}, onFilterChange() {}, onTocUpdate() {}, diff --git a/tests/unit/extensions/decoration-host.test.ts b/tests/unit/extensions/decoration-host.test.ts new file mode 100644 index 00000000..ab300a5a --- /dev/null +++ b/tests/unit/extensions/decoration-host.test.ts @@ -0,0 +1,86 @@ +import { afterEach, describe, expect, it } from "bun:test"; + +import { Editor } from "@tiptap/core"; +import { Decoration, DecorationSet } from "@tiptap/pm/view"; +import { StarterKit } from "@tiptap/starter-kit"; + +import { DecorationHost } from "@/extensions/decoration-host/decoration-host"; + +let editor: Editor | undefined; +afterEach(() => { + editor?.destroy(); + editor = undefined; +}); + +function create(layers: { name: string; map?: boolean }[]): Editor { + editor = new Editor({ + element: document.createElement("div"), + extensions: [ + StarterKit.configure({ undoRedo: false }), + DecorationHost.configure({ layers }), + ], + content: "

Hello world

", + }); + return editor; +} + +/** Highlights "world" (positions 7–12) in the current document. */ +const worldSet = (e: Editor) => + DecorationSet.create(e.state.doc, [ + Decoration.inline(7, 12, { class: "hit" }), + ]); + +/** The text under each drawn decoration. */ +const hits = (e: Editor) => + [...e.view.dom.querySelectorAll(".hit")].map((node) => node.textContent); + +describe("DecorationHost", () => { + it("adds one plugin per declared layer, none without", () => { + const count = (layers: { name: string }[]) => { + const e = new Editor({ + element: document.createElement("div"), + extensions: [DecorationHost.configure({ layers }), StarterKit], + }); + const plugins = e.state.plugins.length; + e.destroy(); + return plugins; + }; + expect(count([{ name: "a" }, { name: "b" }]) - count([])).toBe(2); + // The command is there for lazy layers; with none declared it is inert. + expect( + create([]).commands.setDecorationLayer("find", DecorationSet.empty), + ).toBe(true); + }); + + it("shows and clears a layer without touching the document or undo", () => { + const e = create([{ name: "find" }]); + const doc = e.state.doc; + e.commands.setDecorationLayer("find", worldSet(e)); + expect(hits(e)).toEqual(["world"]); + expect(e.state.doc).toBe(doc); + e.commands.setDecorationLayer("find", DecorationSet.empty); + expect(hits(e)).toEqual([]); + }); + + it("leaves other layers alone", () => { + const e = create([{ name: "find" }, { name: "comments", map: true }]); + e.commands.setDecorationLayer("comments", worldSet(e)); + e.commands.setDecorationLayer("find", worldSet(e)); + e.commands.setDecorationLayer("find", DecorationSet.empty); + expect(hits(e)).toEqual(["world"]); + }); + + it("clears a plain layer on a document change", () => { + const e = create([{ name: "find" }]); + e.commands.setDecorationLayer("find", worldSet(e)); + e.commands.insertContentAt(1, "Oh "); + expect(hits(e)).toEqual([]); + }); + + it("maps a map: true layer through a document change", () => { + const e = create([{ name: "comments", map: true }]); + e.commands.setDecorationLayer("comments", worldSet(e)); + e.commands.insertContentAt(1, "Oh "); + expect(hits(e)).toEqual(["world"]); + }); +}); diff --git a/tests/unit/extensions/write-gate.test.ts b/tests/unit/extensions/write-gate.test.ts new file mode 100644 index 00000000..811a94a7 --- /dev/null +++ b/tests/unit/extensions/write-gate.test.ts @@ -0,0 +1,203 @@ +import { afterEach, describe, expect, it } from "bun:test"; + +import type { HocuspocusProvider } from "@hocuspocus/provider"; +import { Editor, getSchema, type JSONContent } from "@tiptap/core"; +import { prosemirrorJSONToYDoc } from "@tiptap/y-tiptap"; +import { Awareness } from "y-protocols/awareness"; +import * as Y from "yjs"; + +import { buildDocumentEditorExtensions } from "@/components/document-editor/document-editor-config"; +import { headingFoldPluginKey } from "@/extensions/heading-fold"; + +const text = (value: string): JSONContent => ({ type: "text", text: value }); + +const heading = (level: number, value: string, id?: string): JSONContent => ({ + type: "heading", + attrs: id ? { level, id, "data-toc-id": id } : { level }, + content: [text(value)], +}); + +/** Unnamed headings: the outline names them when the editor is created. */ +const UNNAMED: JSONContent = { + type: "doc", + content: [heading(1, "Title"), heading(2, "Section")], +}; + +const NAMED: JSONContent = { + type: "doc", + content: [ + heading(1, "Title", "t"), + heading(2, "Section", "s"), + { type: "paragraph", content: [text("Body")] }, + ], +}; + +/** A provider stand-in: UniqueID only subscribes to "synced". */ +function fakeProvider() { + const listeners = new Map void>(); + // Like HocuspocusProvider's EventEmitter, `on` returns the provider. + const provider = { + on(event: string, fn: () => void) { + listeners.set(event, fn); + return provider; + }, + off: (event: string) => listeners.delete(event), + } as unknown as HocuspocusProvider; + return { provider, listeners, sync: () => listeners.get("synced")?.() }; +} + +interface OpenOptions { + canWrite?: () => boolean; + getProvider?: () => HocuspocusProvider | null; +} + +const extensionsFor = ( + ydoc: Y.Doc, + awareness: Awareness, + { canWrite = () => true, getProvider = () => null }: OpenOptions = {}, +) => + buildDocumentEditorExtensions({ + documentId: "write-gate", + ydoc, + awareness, + getProvider, + canWrite, + onFoldChange() {}, + onFilterChange() {}, + onTocUpdate() {}, + }); + +/** A Y.Doc holding `content` in the editor's fragment. */ +function seededDoc(content: JSONContent): Y.Doc { + const schema = getSchema(extensionsFor(new Y.Doc(), {} as Awareness)); + return prosemirrorJSONToYDoc(schema, content, "default"); +} + +let editor: Editor | undefined; +let awareness: Awareness | undefined; +afterEach(() => { + editor?.destroy(); + awareness?.destroy(); + editor = undefined; + awareness = undefined; +}); + +/** + * Opens the app's editor on `ydoc` and waits for `create` (Tiptap emits it + * on a timer); returns the Yjs updates it makes. + */ +async function open(ydoc: Y.Doc, options?: OpenOptions): Promise { + const updates: Uint8Array[] = []; + ydoc.on("update", (update: Uint8Array) => updates.push(update)); + awareness = new Awareness(ydoc); + editor = new Editor({ + element: document.createElement("div"), + extensions: extensionsFor(ydoc, awareness, options), + }); + await new Promise((resolve) => setTimeout(resolve, 20)); + return updates; +} + +const headingIds = () => { + const ids: unknown[] = []; + editor?.state.doc.forEach((node) => { + if (node.type.name === "heading") ids.push(node.attrs["data-toc-id"]); + }); + return ids; +}; + +const title = () => editor?.state.doc.firstChild?.textContent; + +describe("WriteGate", () => { + it("lets the opening writes through when writable", async () => { + await open(seededDoc(UNNAMED)); + // Control for the next test: the outline names both headings. + expect(headingIds().every((id) => typeof id === "string")).toBe(true); + }); + + it("blocks the opening writes when read-only", async () => { + const { provider, sync } = fakeProvider(); + const updates = await open(seededDoc(UNNAMED), { + canWrite: () => false, + getProvider: () => provider, + }); + // UniqueID's first-sync pass is gated too. + sync(); + expect(headingIds()).toEqual([null, null]); + expect(updates).toHaveLength(0); + // The content still renders from Yjs. + expect(editor?.state.doc.textContent).toBe("TitleSection"); + }); + + it("blocks local edits but not a collaborator's", async () => { + const ydoc = seededDoc(NAMED); + let writable = true; + const updates = await open(ydoc, { canWrite: () => writable }); + editor?.commands.insertContentAt(1, "My "); + expect(updates.length).toBeGreaterThan(0); + + writable = false; + const before = updates.length; + editor?.commands.insertContentAt(1, "Local "); + expect(updates.length).toBe(before); + expect(title()).toBe("My Title"); + + // A collaborator's change arrives through Yjs and is shown. + const remote = new Y.Doc(); + Y.applyUpdate(remote, Y.encodeStateAsUpdate(ydoc)); + const first = remote.getXmlFragment("default").get(0) as Y.XmlElement; + (first.get(0) as Y.XmlText).insert(0, "Remote "); + Y.applyUpdate( + ydoc, + Y.encodeStateAsUpdate(remote, Y.encodeStateVector(ydoc)), + ); + expect(title()).toBe("Remote My Title"); + }); + + it("lets meta-only transactions through", async () => { + await open(seededDoc(NAMED), { canWrite: () => false }); + // A fold is meta-only: it works on a read-only document. + editor?.commands.toggleFold("s"); + const folded = editor && headingFoldPluginKey.getState(editor.state); + expect([...(folded?.foldedIds ?? [])]).toEqual(["s"]); + }); +}); + +describe("no provider", () => { + it("opens and edits with the session's Awareness alone", async () => { + const ydoc = seededDoc(NAMED); + await open(ydoc); + editor?.commands.insertContentAt(1, "Local "); + expect(ydoc.getXmlFragment("default").toString()).toContain("Local Title"); + // The caret publishes this user on the session's Awareness. + editor?.commands.updateUser({ name: "Ada", color: "#000000" }); + expect(awareness?.getLocalState()?.user?.name).toBe("Ada"); + }); + + it("forwards UniqueID's wait for a sync to the provider of the moment", async () => { + let current: HocuspocusProvider | null = null; + const { provider, listeners } = fakeProvider(); + current = provider; + await open(seededDoc(UNNAMED), { getProvider: () => current }); + // As before this change: UniqueID waits on the real provider's sync. + expect(listeners.has("synced")).toBe(true); + listeners.get("synced")?.(); + expect(listeners.has("synced")).toBe(false); + }); + + it("hands back the provider from the caret's on (e2e helpers find it so)", async () => { + const { provider } = fakeProvider(); + let current: HocuspocusProvider | null = null; + await open(seededDoc(NAMED), { getProvider: () => current }); + const caret = editor?.extensionManager.extensions.find( + (extension) => extension.name === "collaborationCaret", + ); + const forward = caret?.options.provider as { + on: (event: string, fn: () => void) => unknown; + }; + const probe = () => {}; + expect(forward.on("probe", probe)).toBeUndefined(); + current = provider; + expect(forward.on("probe", probe)).toBe(provider); + }); +}); diff --git a/tests/unit/lib/doc-migrations/doc-migrations.test.ts b/tests/unit/lib/doc-migrations/doc-migrations.test.ts new file mode 100644 index 00000000..e4bcc1bc --- /dev/null +++ b/tests/unit/lib/doc-migrations/doc-migrations.test.ts @@ -0,0 +1,51 @@ +import { describe, expect, test } from "bun:test"; + +import * as Y from "yjs"; + +import { + DOC_MIGRATIONS, + DOC_SCHEMA, + type DocMigration, + planDocMigrations, + runDocMigrations, +} from "@/lib/doc-migrations"; + +const steps: DocMigration[] = [ + { to: 1, migrate: (doc) => doc.getMap("m").set("one", true) }, + { to: 2, migrate: (doc) => doc.getMap("m").set("two", true) }, +]; + +describe("document migrations", () => { + test("the list starts empty, so today's documents are current", () => { + expect(DOC_MIGRATIONS).toEqual([]); + expect(DOC_SCHEMA).toBe(0); + expect(planDocMigrations(0)).toEqual({ kind: "current" }); + }); + + test("a newer document is too new", () => { + expect(planDocMigrations(1)).toEqual({ kind: "too_new" }); + }); + + test("plans only the missing steps", () => { + const plan = planDocMigrations(1, steps); + expect(plan).toMatchObject({ kind: "migrate", schemaTo: 2 }); + expect(plan.kind === "migrate" && plan.steps.map((s) => s.to)).toEqual([2]); + }); + + test("refuses a gap in the list", () => { + expect(() => + planDocMigrations(0, [{ to: 2, migrate: () => {} }]), + ).toThrow(); + }); + + test("runs every step in one transaction under the given origin", () => { + const doc = new Y.Doc(); + const origin = Symbol("migration"); + const seen: unknown[] = []; + doc.on("update", (_u: Uint8Array, o: unknown) => seen.push(o)); + expect(runDocMigrations(doc, planDocMigrations(0, steps), origin)).toBe(2); + expect(seen).toEqual([origin]); + expect(doc.getMap("m").toJSON()).toEqual({ one: true, two: true }); + expect(runDocMigrations(doc, { kind: "current" }, origin)).toBeNull(); + }); +}); diff --git a/tests/unit/lib/doc-migrations/import-guard.test.ts b/tests/unit/lib/doc-migrations/import-guard.test.ts new file mode 100644 index 00000000..82678a37 --- /dev/null +++ b/tests/unit/lib/doc-migrations/import-guard.test.ts @@ -0,0 +1,92 @@ +import { describe, expect, test } from "bun:test"; + +import * as Y from "yjs"; + +import { checkImport } from "@/lib/doc-migrations/import-guard"; + +function docWith(build: (doc: Y.Doc) => void): Uint8Array { + const doc = new Y.Doc(); + build(doc); + return Y.encodeStateAsUpdate(doc); +} + +function paragraph(text: string, attrs?: Record) { + const p = new Y.XmlElement("paragraph"); + const t = new Y.XmlText(); + t.insert(0, text, attrs); + p.insert(0, [t]); + return p; +} + +describe("checkImport", () => { + test("accepts a document the editor can open", () => { + const state = docWith((doc) => { + const heading = new Y.XmlElement("heading"); + heading.setAttribute("level", "1"); + doc + .getXmlFragment("default") + .insert(0, [heading, paragraph("hi", { bold: true })]); + }); + expect(checkImport(state)).toEqual({ ok: true }); + }); + + test("accepts the legacy link and code marks (the import migrations rename them)", () => { + const state = docWith((doc) => { + doc + .getXmlFragment("default") + .insert(0, [ + paragraph("x", { link: { href: "https://a.b" } }), + paragraph("y", { code: true }), + ]); + }); + expect(checkImport(state)).toEqual({ ok: true }); + }); + + test("refuses unknown nodes and marks, naming them", () => { + const state = docWith((doc) => { + doc + .getXmlFragment("default") + .insert(0, [ + new Y.XmlElement("marquee"), + paragraph("x", { blink: true }), + ]); + }); + expect(checkImport(state)).toEqual({ + ok: false, + code: "unknown_schema", + names: ["marquee", "blink"], + }); + }); + + test("refuses unknown roots", () => { + const state = docWith((doc) => { + doc.getXmlFragment("default").insert(0, [paragraph("x")]); + doc.getMap("payload").set("a", 1); + }); + expect(checkImport(state)).toMatchObject({ + ok: false, + code: "unknown_schema", + names: ["payload"], + }); + }); + + test("refuses oversized states before decoding them", () => { + const state = docWith((doc) => { + doc.getXmlFragment("default").insert(0, [paragraph("x".repeat(100))]); + }); + expect(checkImport(state, { maxBytes: 10 })).toEqual({ + ok: false, + code: "import_too_large", + names: [], + }); + }); + + test("refuses bytes that aren't a Yjs update", () => { + expect( + checkImport(new Uint8Array([255, 255, 255, 255, 1, 2, 3])), + ).toMatchObject({ + ok: false, + code: "corrupt", + }); + }); +}); diff --git a/tests/unit/lib/import-boundaries.test.ts b/tests/unit/lib/import-boundaries.test.ts index 679e66f7..e8d5cdd8 100644 --- a/tests/unit/lib/import-boundaries.test.ts +++ b/tests/unit/lib/import-boundaries.test.ts @@ -40,9 +40,9 @@ function staticImports(entry: string): { // Server code: the API routes, the retention cron and the Hocus server must // never load the client tab API or the browser collaboration provider. const SERVER_ENTRIES = [ - "app/api/documents/[id]/route.ts", - "app/api/documents/restore/route.ts", - "app/api/documents/closed/route.ts", + "app/api/documents/[id]/route.web.ts", + "app/api/documents/restore/route.web.ts", + "app/api/documents/closed/route.web.ts", "scripts/purge-retention.ts", "scripts/delete-document.ts", "scripts/hocus-server.ts", diff --git a/tests/unit/scripts/desktop-export.test.ts b/tests/unit/scripts/desktop-export.test.ts new file mode 100644 index 00000000..68a14762 --- /dev/null +++ b/tests/unit/scripts/desktop-export.test.ts @@ -0,0 +1,157 @@ +/** + * The desktop export's move-aside and output check (scripts/desktop-export.ts). + * The export itself is `bun run build:desktop`; these cover the parts that + * would fail silently: a lost file, a web route leaking into desktop. + */ +import { afterEach, beforeEach, describe, expect, it } from "bun:test"; +import { + existsSync, + mkdirSync, + mkdtempSync, + readdirSync, + readFileSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; + +import { + checkDesktopExport, + listParked, + PARKING_DIR, + parkWebOnlyFiles, + restoreParked, + WEB_ONLY_FILES, +} from "@/scripts/desktop-export"; + +const REPO = join(import.meta.dir, "../../.."); + +let root: string; + +function write(rel: string, content = rel): void { + mkdirSync(dirname(join(root, rel)), { recursive: true }); + writeFileSync(join(root, rel), content); +} + +beforeEach(() => { + root = mkdtempSync(join(tmpdir(), "desktop-export-")); +}); + +afterEach(() => { + rmSync(root, { recursive: true, force: true }); +}); + +describe("parking web-only files", () => { + it("lists only files that exist in the repo", () => { + for (const rel of WEB_ONLY_FILES) { + expect(existsSync(join(REPO, rel))).toBe(true); + } + }); + + it("parks every file inside the checkout and puts each back unchanged", () => { + for (const rel of WEB_ONLY_FILES) write(rel); + + expect(parkWebOnlyFiles(root)).toEqual([...WEB_ONLY_FILES]); + for (const rel of WEB_ONLY_FILES) { + expect(existsSync(join(root, rel))).toBe(false); + } + expect(listParked(root).sort()).toEqual([...WEB_ONLY_FILES].sort()); + + expect(restoreParked(root).sort()).toEqual([...WEB_ONLY_FILES].sort()); + for (const rel of WEB_ONLY_FILES) { + expect(readFileSync(join(root, rel), "utf8")).toBe(rel); + } + expect(existsSync(join(root, PARKING_DIR))).toBe(false); + }); + + it("puts back what an interrupted run left before parking again", () => { + write("app/robots.ts"); + parkWebOnlyFiles(root); + // The run was killed here. The next one restores first. + expect(restoreParked(root)).toEqual(["app/robots.ts"]); + expect(parkWebOnlyFiles(root)).toEqual(["app/robots.ts"]); + }); + + it("refuses when a file is both in app/ and parked", () => { + write("app/robots.ts", "parked copy"); + parkWebOnlyFiles(root); + write("app/robots.ts", "new copy"); + + expect(() => restoreParked(root)).toThrow(/both in app\/ and in/); + expect(readFileSync(join(root, "app/robots.ts"), "utf8")).toBe("new copy"); + expect(listParked(root)).toEqual(["app/robots.ts"]); + }); + + it("finds nothing parked in a clean checkout", () => { + expect(listParked(root)).toEqual([]); + expect(restoreParked(root)).toEqual([]); + }); +}); + +describe("route handlers that leave the desktop export", () => { + // `route.web.ts(x)` is what keeps them out (next.config.ts pageExtensions). + // A plain `route.ts` here would join the desktop export, or fail it. + it("are all route.web.ts(x)", () => { + const routes: string[] = []; + for (const dir of ["app/api", "app/llms.txt", "app/pwa-icons"]) { + for (const name of readdirSync(join(REPO, dir), { recursive: true })) { + const file = String(name).split(/[\\/]/).at(-1) ?? ""; + if (file.startsWith("route.")) routes.push(`${dir}/${name}`); + } + } + expect(routes.length).toBeGreaterThan(0); + expect(routes.filter((path) => !/\/route\.web\.tsx?$/.test(path))).toEqual( + [], + ); + }); +}); + +describe("checkDesktopExport", () => { + const PAGE = ''; + + function validExport(): void { + write("out/index.html", PAGE); + write("out/about.html", PAGE); + write("out/about/__next.about.__PAGE__.txt", ""); + write("out/_next/static/chunks/a.js", ""); + } + + it("accepts a desktop renderer", () => { + validExport(); + expect(checkDesktopExport(join(root, "out"))).toEqual([]); + }); + + it("reports web-only routes", () => { + validExport(); + write("out/privacy.html", PAGE); + write("out/sitemap.xml", ""); + write("out/api/documents/x", ""); + expect(checkDesktopExport(join(root, "out")).sort()).toEqual([ + "web-only output: api", + "web-only output: privacy.html", + "web-only output: sitemap.xml", + ]); + }); + + it("reports web metadata tags and in-app /privacy links", () => { + validExport(); + write( + "out/index.html", + 'Privacy', + ); + expect(checkDesktopExport(join(root, "out"))).toEqual([ + 'index.html has { + validExport(); + write("out/about/__next.about/__PAGE__.txt", ""); + expect(checkDesktopExport(join(root, "out"))).toEqual([ + `nested segment directory (Windows layout): ${join("about", "__next.about")}`, + ]); + }); +}); diff --git a/tsconfig.desktop-node.json b/tsconfig.desktop-node.json new file mode 100644 index 00000000..d77f129c --- /dev/null +++ b/tsconfig.desktop-node.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "target": "ES2023", + "lib": ["es2023"], + "module": "esnext", + "moduleResolution": "bundler", + "strict": true, + "noEmit": true, + "skipLibCheck": true, + "isolatedModules": true, + "resolveJsonModule": true, + "types": ["node"] + }, + "include": [ + "desktop/storage/**/*.ts", + "desktop/main/**/*.ts", + "desktop/build/**/*.ts" + ] +} diff --git a/tsconfig.json b/tsconfig.json index 99c6bb37..ea09e62a 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -31,5 +31,14 @@ ".next/dev/types/**/*.ts", "**/*.mts" ], - "exclude": ["node_modules", "lib/pwa/service-worker.ts", "desktop/smoke"] + "exclude": [ + "node_modules", + "out", + "lib/pwa/service-worker.ts", + "desktop/smoke", + "desktop/storage-harness", + "desktop/storage", + "desktop/main", + "desktop/build" + ] }