Skip to content

Build your personal knowledge base with Trilium Notes

docs(claude): standalone skill; sqlite-wasm, not sql.js

Elian Doran1416dad833a0
diff --git a/.claude/skills/adding-internal-api-route/SKILL.md b/.claude/skills/adding-internal-api-route/SKILL.md
index 4484c32d31..275802fcba 100644
--- a/.claude/skills/adding-internal-api-route/SKILL.md
+++ b/.claude/skills/adding-internal-api-route/SKILL.md
@@ -1,6 +1,6 @@
---
name: adding-internal-api-route
-description: Use when adding, moving, or wiring an internal REST endpoint in Trilium (a new `/api/*` route) — choosing between a core-shared handler (`packages/trilium-core/src/routes/index.ts` `buildSharedApiRoutes`, ~140 routes that ALSO run in the standalone sql.js WASM build) and a server-only one (`apps/server/src/routes/routes.ts`), picking the `apiRoute` vs `asyncApiRoute` vs `route`/`asyncRoute` wrapper, and getting the implicit return conventions (object→200, `undefined`→204, `[status, body]` tuple→that status) and `convertEntitiesToPojo`'s narrow entity-unwrapping right. Most routes are core-shared (and run under WASM); `apps/server/src/routes/api/` is the minority case. Pairs with writing-unit-tests for the cross-runtime CoreApiTester spec.
+description: Use when adding, moving, or wiring an internal REST endpoint in Trilium (a new `/api/*` route) — choosing between a core-shared handler (`packages/trilium-core/src/routes/index.ts` `buildSharedApiRoutes`, ~140 routes that ALSO run in the standalone sqlite-wasm build) and a server-only one (`apps/server/src/routes/routes.ts`), picking the `apiRoute` vs `asyncApiRoute` vs `route`/`asyncRoute` wrapper, and getting the implicit return conventions (object→200, `undefined`→204, `[status, body]` tuple→that status) and `convertEntitiesToPojo`'s narrow entity-unwrapping right. Most routes are core-shared (and run under WASM); `apps/server/src/routes/api/` is the minority case. Pairs with writing-unit-tests for the cross-runtime CoreApiTester spec.
---
# Adding an internal API route in Trilium
@@ -33,7 +33,7 @@ A route you add only in `routes.ts` is **invisible to the standalone build and c
The server-only set is small and specific — clipper, database, llm_chat, ocr, metrics, sender, totp, fonts, link_embed, recovery_codes, system_info, etapi_tokens, plus a few `files` extras. See the `register()` body in `routes.ts` (the shared set is wired by `buildSharedApiRoutes` at `routes.ts:97`). Everything else is core.
-**Browser-safe rule for core handlers:** no `process.env`, no `node:path`/`import path`, no Node built-ins — they run in the sql.js WASM standalone build. (`script.ts:75,86` reads `process.env.TRILIUM_SAFE_MODE` directly — that is a **latent violation**, not a pattern to copy.)
+**Browser-safe rule for core handlers:** no `process.env`, no `node:path`/`import path`, no Node built-ins — they run in the sqlite-wasm standalone build. (`script.ts:75,86` reads `process.env.TRILIUM_SAFE_MODE` directly — that is a **latent violation**, not a pattern to copy.)
## Step 2 — Pick the wrapper
diff --git a/.claude/skills/developing-capacitor-mobile/SKILL.md b/.claude/skills/developing-capacitor-mobile/SKILL.md
index 57733933c4..ad2bc97861 100644
--- a/.claude/skills/developing-capacitor-mobile/SKILL.md
+++ b/.claude/skills/developing-capacitor-mobile/SKILL.md
@@ -73,7 +73,7 @@ CI: `mobile.yml` (pull requests) builds a debug APK via `.github/actions/build-m
## Testing
-Everything JS-side is under the standalone Vitest suite (happy-dom + sql.js):
+Everything JS-side is under the standalone Vitest suite (happy-dom + real sqlite-wasm):
```bash
pnpm --filter standalone test ios-interceptors # iOS interceptors
diff --git a/.claude/skills/developing-standalone/SKILL.md b/.claude/skills/developing-standalone/SKILL.md
new file mode 100644
index 0000000000..6aec76d421
--- /dev/null
+++ b/.claude/skills/developing-standalone/SKILL.md
@@ -0,0 +1,84 @@
+---
+name: developing-standalone
+description: Use when working on Trilium's standalone in-browser build (`apps/standalone`, deployed at app.triliumnotes.org and embedded by the mobile app) — the service worker (`sw.ts`), the leader-tab election and multi-tab request forwarding, the SQLite worker (`local-server-worker.ts`, `@sqlite.org/sqlite-wasm` on OPFS SAHPool), the `lightweight/*` provider implementations that `initializeCore()` needs in the browser, standalone-only routes, `window.standaloneApi`, backup/restore in OPFS, the Vite bundle stubs (officeparser, pdfjs, sqlite wasm copies), startup errors, or running/testing/deploying it. Also load it when a change to `packages/trilium-core` adds a provider, a Node import, or a top-level side effect — standalone is where that breaks.
+---
+
+# Developing the standalone (in-browser) build
+
+`apps/standalone` runs the **entire Trilium stack in the browser** with no server: the ordinary `apps/client` UI on the page, and `@triliumnext/core` — plain JS, the same code the server runs — inside a **dedicated Web Worker** on top of **SQLite compiled to WASM** (`@sqlite.org/sqlite-wasm`, not sql.js) persisted in the origin's **OPFS** through the SAHPool VFS. It ships as a PWA to **app.triliumnotes.org** (Cloudflare Pages, `deploy-app.yml`, PR previews included) and is the `webDir` of the Capacitor mobile app (`developing-capacitor-mobile` skill). There is no `apps/standalone-desktop`.
+
+## Layout
+
+```
+apps/standalone/
+ src/index.html, main.ts # page bootstrap: SW registration, leadership claim, worker start, standaloneApi
+ src/desktop.ts # re-exports apps/client/src/desktop — the client entry
+ src/sw.ts # service worker: caches assets, forwards local API requests to the leader tab
+ src/leader_election.ts # Web Lock decides which tab owns the database worker
+ src/local-bridge.ts # page ⇄ worker protocol (LOCAL_REQUEST/RESPONSE, WS_MESSAGE, HTTP_REQUEST, backup/restore)
+ src/local-server-worker.ts # the worker: opens SQLite, initializeCore(), routes requests
+ src/ios-interceptors.ts # iOS Capacitor only (see mobile skill)
+ src/error-overlay.ts # full-screen surface for fatal startup failures
+ src/lightweight/ # browser implementations of every core provider + standalone-only routes
+ src/services/ # image provider, Capacitor HTTP handler
+ src/stubs/ # officeparser entry + Buffer polyfill, empty stubs for pdfjs/tesseract/puppeteer
+ src/test_setup.ts # boots core with the real lightweight providers under vitest/happy-dom
+ public/_headers, manifest.webmanifest, favicon.ico
+ e2e/multi_tab.spec.ts, extra_window.spec.ts
+ vite.config.mts # root is src/; aliases, stubs, asset copies, worker + SW build, vitest config
+```
+
+## Request flow
+
+1. **`main.ts`** requires a service worker (secure context: HTTPS or localhost — otherwise it throws a message explaining that), registers `./sw.js` with scope `/`, reloads once if the SW installed but doesn't control the page yet, and exposes `window.standaloneApi` (`restore.importBackup`, `backup.downloadDatabase`) — the client's escape hatch for things carrying a whole file, the twin of desktop's `window.electronApi`.
+2. **Leader election** (`leader_election.ts`): the OPFS SAHPool VFS takes *exclusive* sync-access handles, and `createSyncAccessHandle` exists only in a dedicated worker, so exactly one tab per origin can own the database. A **Web Lock** (`trilium-standalone-db`, held for the tab's lifetime) picks it; only the winner calls `startLocalServerWorker()`; when it closes the browser releases the lock and a waiting tab is promoted. Where Web Locks are missing (some WebViews) the tab assumes it is alone.
+3. **Service worker** (`sw.ts`): cache-first for hashed assets, network-first otherwise; requests under `LOCAL_API_PREFIXES` (`/bootstrap`, `/api/`, `/sync/`, `/search/`, from `local-bridge.ts`) are forwarded with `LOCAL_FETCH` to the **leader** client, found via a cached id, `WHO_IS_LEADER` / `LEADER_REPLY` probing, and one retry on `NOT_LEADER` (leadership can flip while a request is in flight). Backup downloads stream over a `MessageChannel` from the leader. It must **let `/_trilium_native_http/` fall through** (Android native proxy) and has a defensive guard for `capacitor://`.
+4. **The worker** (`local-server-worker.ts`): installs the SAHPool VFS (falls back to an in-memory DB when OPFS is unavailable or in `TRILIUM_INTEGRATION_TEST=memory` builds, where it seeds a fixture), calls `initializeCore({...})` with the `lightweight/*` providers, registers `createConfiguredRouter()` (`BrowserRouter` mimicking Express, path params + query strings), then answers `LOCAL_REQUEST` messages. `DbLock` (`lightweight/db_lock.ts`) serialises `createAsyncRoute` handlers (imports) that hold a transaction across `await`s against the single connection — synchronous routes keep a zero-overhead path. `WS_MESSAGE` replaces the WebSocket in both directions. Anything that escapes after startup is reported as `WORKER_ERROR` for one background task; before startup it means the app never came up and `error-overlay.ts` paints it (the async worker init is invisible to `main.ts`'s try/catch).
+
+## The provider set (`src/lightweight/`)
+
+`initializeCore()` takes every environment-specific capability as a provider; the browser build supplies its own for each. **A new provider or provider method in core needs an implementation here, or standalone will not boot** — the server-side one in `apps/server/src/*_provider.ts` is the pair to mirror.
+
+| Provider | File | Notes |
+|---|---|---|
+| SQL | `sql_provider.ts` | wraps sqlite-wasm statements to core's `Statement` interface; SAHPool VFS install; nested transactions become SAVEPOINTs |
+| Execution context (CLS) | `cls_provider.ts` | per-request context stack with a grace period for unawaited promises |
+| Crypto | `crypto_provider.ts` | WebCrypto + `scrypt-js` (pure JS, slow under coverage) |
+| Zip / export | `zip_provider.ts`, `zip_export_provider_factory.ts` | bytes only — no filesystem `path` source |
+| Request (outbound HTTP, sync) | `request_provider.ts` (`fetch`), `bridged_request_provider.ts` (Capacitor native, via `HTTP_REQUEST` to the page) | |
+| Messaging | `messaging_provider.ts` | `postMessage` in place of WS |
+| Backup / restore | `backup_provider.ts`, `backup-stream.ts`, `backup-download.ts`, `database_restore.ts` | SAH pool has no rename: restore writes the new DB beside the old one and swaps the *pointer* the next start opens; stale pool entries from interrupted backups are swept |
+| Setup marker | `setup_marker.ts` | `setup.json` in the origin's private FS, read **before** the DB is opened; a page reload is "restart" here |
+| Platform | `platform_provider.ts` | `?safeMode` → `TRILIUM_SAFE_MODE` etc.; `isElectron/isMac/isWindows` false |
+| Translations | `translation_provider.ts` | i18next in the worker with `ns: "server"`, fetching `server-assets/translations/{{lng}}/server.json` |
+| In-app help | `in_app_help_provider.ts` | pre-built `assets/help_meta.json` from edit-docs; the User Guide itself is **not** in this build |
+| Log | `log_provider.ts` | OPFS log file |
+| Image | `services/image_provider.ts` | format sniffing only, no resize/compression |
+| LLM | `llm_skills.ts` | this build's half of the LLM stack (`registerStandaloneLlmExtensions`), dynamically imported so skill sheets don't join the startup bundle |
+
+Standalone-only routes (integrity checks, the LLM channel, upload handling that arrives as a buffer instead of a temp file) are registered in `lightweight/browser_routes.ts`; everything else is core's shared route table (`adding-internal-api-route` skill).
+
+## Bundle discipline (`vite.config.mts`)
+
+The worker's top-level imports **are** its startup cost — prefer dynamic imports for anything not needed to answer `/bootstrap` (the LLM skills and restore paths already do this).
+
+- `officeparser` is aliased to `src/stubs/officeparser_entry.ts`, which loads the package's Node ESM entry plus the `buffer` polyfill (`buffer_polyfill.ts`, must be imported first) instead of the prebuilt browser monolith that inlines pdfjs (2.7 MB → 0.4 MB); `pdfjs-dist`, `tesseract.js`, `puppeteer` are aliased to `stubs/empty.ts`. `office_preview.spec.ts` guards the alias against upstream layout changes.
+- `@sqlite.org/sqlite-wasm` and `@triliumnext/core` are excluded from `optimizeDeps`; the sqlite `.wasm` and OPFS async proxy are copied **unhashed** so the worker can resolve them by convention; `apps/server/src/assets/**` (minus the User Guide) is copied to `server-assets/`.
+- The service worker keeps a stable `sw.js` URL (registering a hashed one would orphan the old worker); everything else under `src/` is content-hashed. `public/_headers` matches: `immutable` for `/src/*`, `must-revalidate` for `/sw.js`, plus `Cross-Origin-Opener-Policy: same-origin`.
+- Vite `root` is `src/`, `base` is `""` — paths in config and coverage globs resolve relative to `src/`.
+
+## Running
+
+```bash
+pnpm standalone:start # vite dev
+pnpm --filter standalone build # dist/ (needs NODE_OPTIONS=--max-old-space-size=4096, set by the script)
+pnpm --filter standalone start-prod # build + vite preview on :8888
+TRILIUM_INTEGRATION_TEST=memory pnpm --filter standalone build # in-memory DB seeded from a fixture (what e2e uses)
+pnpm --filter standalone e2e # Playwright: multi-tab leader handoff, extra windows
+```
+
+`?safeMode` and other `TRILIUM_*` toggles are passed as URL query parameters (`platform_provider.ts`).
+
+## Testing
+
+`pnpm --filter standalone test <pattern>` — Vitest, happy-dom, **real sqlite-wasm**. `test_setup.ts` shims wasm loading (happy-dom's `fetch` refuses `file://` and its `Response` breaks `instantiateStreaming`) and boots core with the real lightweight providers, so a spec exercises the same code path as the browser. `local-server-worker.ts` is excluded from coverage on purpose (it boots a second core). This suite is also the **second runtime for every `packages/trilium-core` spec** — green under `pnpm --filter server test` is not proof; the cross-runtime traps (capability gaps, provider differences, `serialize()`, backup) are in the `writing-unit-tests` skill.
diff --git a/.claude/skills/writing-unit-tests/server-and-core.md b/.claude/skills/writing-unit-tests/server-and-core.md
index 8bce87ea99..df40f5fe7e 100644
--- a/.claude/skills/writing-unit-tests/server-and-core.md
+++ b/.claude/skills/writing-unit-tests/server-and-core.md
@@ -5,10 +5,10 @@
`trilium-core` cannot run tests standalone (its `test` script just prints a note — it needs a host runtime's platform providers). Its specs run **through** `apps/server` (and `apps/standalone`), which list `../../packages/trilium-core/src/**` in their test `include`. For that core code to actually count toward coverage, each host also sets `coverage.allowExternal: true` and lists core in `coverage.include` (v8 drops out-of-root files otherwise — see the coverage rules in `SKILL.md`). Add core specs next to the core source or under `apps/server/spec` — both feed the same coverage number, reported under the `server`/`standalone` Codecov flags. A dedicated core vitest project is **not** needed.
### ⚠️ A core spec runs under BOTH runtimes — verify both before calling it done
-The same `packages/trilium-core/src/**` spec executes under the **server** suite (vitest env `node`, better-sqlite3 + `NodejsCryptoProvider`) **and** the **standalone** suite (env `happy-dom`, sql.js WASM + `Browser*Provider`). Passing `pnpm --filter server exec vitest run <spec>` is **not enough** — also run `pnpm --filter standalone exec vitest run <spec>`. A spec green on server can fail on standalone because the providers differ. Known cross-runtime traps:
+The same `packages/trilium-core/src/**` spec executes under the **server** suite (vitest env `node`, better-sqlite3 + `NodejsCryptoProvider`) **and** the **standalone** suite (env `happy-dom`, sqlite-wasm + `Browser*Provider`). Passing `pnpm --filter server exec vitest run <spec>` is **not enough** — also run `pnpm --filter standalone exec vitest run <spec>`. A spec green on server can fail on standalone because the providers differ. Known cross-runtime traps:
- **`BNote.getContent()` of a non-string note** is a `Buffer` on Node (`.toString()` → UTF-8) but a `Uint8Array` on WASM (`.toString()` → `"40,40,..."`). Decode portably: `unwrapStringOrBuffer(note.getContent())` (import from a **relative** path like `./utils/binary.js`, never `@triliumnext/core` — self-import fails inside core).
-- **Provider implementation details differ** and are NOT cross-runtime contracts: e.g. better-sqlite3 caches raw vs non-raw statements as distinct objects (sql.js may not); `crypto.hmac` of `Uint8Array` vs `string` inputs differs on Node but not in the browser provider. Don't assert these — assert the portable contract.
-- **Capability gaps**: `getSql().serialize()` throws on better-sqlite3 (Node) but works on sql.js (WASM); `BrowserZipProvider.createFileStream()` throws (no file streams in the browser) and its streaming/finalize model differs (Node-style `pipe`→`end` never fires). For genuinely runtime-specific behavior, gate with `const isBrowserRuntime = typeof window !== "undefined";` + `it.skipIf(isBrowserRuntime)` / `describe.skipIf(...)` and a one-line reason — but prefer a portable assertion or capability-aware branch over skipping when the behavior is actually the same.
+- **Provider implementation details differ** and are NOT cross-runtime contracts: e.g. better-sqlite3 caches raw vs non-raw statements as distinct objects (sqlite-wasm may not); `crypto.hmac` of `Uint8Array` vs `string` inputs differs on Node but not in the browser provider. Don't assert these — assert the portable contract.
+- **Capability gaps**: `getSql().serialize()` throws on better-sqlite3 (Node) but works on sqlite-wasm; `BrowserZipProvider.createFileStream()` throws (no file streams in the browser) and its streaming/finalize model differs (Node-style `pipe`→`end` never fires). For genuinely runtime-specific behavior, gate with `const isBrowserRuntime = typeof window !== "undefined";` + `it.skipIf(isBrowserRuntime)` / `describe.skipIf(...)` and a one-line reason — but prefer a portable assertion or capability-aware branch over skipping when the behavior is actually the same.
There are **two distinct HTTP code paths** — testing one does not cover the other:
- **ETAPI** (`apps/server/src/etapi/*`): basic-auth token, helpers in `spec/etapi/utils.ts`.
@@ -18,7 +18,7 @@ There are **two distinct HTTP code paths** — testing one does not cover the ot
## Pattern 0 — the cross-runtime core route driver (`CoreApiTester`) — PREFER THIS for core routes
-For specs under `packages/trilium-core/src/routes/api/*.spec.ts`, use the in-process, transport-agnostic driver `packages/trilium-core/src/test/api_tester.ts`. It registers the exact handlers from `routes.buildSharedApiRoutes` and runs them **without Express/HTTP**, so the same spec runs under **both** the node (better-sqlite3) and standalone (sql.js WASM) suites. It exercises the real lifecycle: param/query parsing, cls + SQL transaction wrapping, `convertEntitiesToPojo`, the `[status, body]`/`undefined→204` conventions, `HttpError`→status mapping, and JSON round-tripping. It deliberately skips platform middleware (auth/CSRF/rate-limit/multipart) — those are server concerns (Pattern 1).
+For specs under `packages/trilium-core/src/routes/api/*.spec.ts`, use the in-process, transport-agnostic driver `packages/trilium-core/src/test/api_tester.ts`. It registers the exact handlers from `routes.buildSharedApiRoutes` and runs them **without Express/HTTP**, so the same spec runs under **both** the node (better-sqlite3) and standalone (sqlite-wasm) suites. It exercises the real lifecycle: param/query parsing, cls + SQL transaction wrapping, `convertEntitiesToPojo`, the `[status, body]`/`undefined→204` conventions, `HttpError`→status mapping, and JSON round-tripping. It deliberately skips platform middleware (auth/CSRF/rate-limit/multipart) — those are server concerns (Pattern 1).
```ts
import { beforeAll, describe, expect, it } from "vitest";
diff --git a/CLAUDE.md b/CLAUDE.md
index 8a6aa98e50..79adfd2dfc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -38,10 +38,9 @@ apps/
client/ # Preact frontend (+ legacy jQuery widgets); shared by server, desktop, standalone
server/ # Node.js backend (Express, better-sqlite3); serves the client, REST/WebSocket
desktop/ # Electron: server + client in one process (see developing-electron-desktop skill)
- standalone/ # whole stack in the browser: core compiled to WASM (sql.js) in a worker, no Node
- standalone-desktop/ # standalone desktop variant
+ standalone/ # whole stack in the browser: core in a Web Worker on SQLite WASM + OPFS, no Node (see developing-standalone skill)
mobile/ # Capacitor shell around standalone (see developing-capacitor-mobile skill)
- web-clipper/, website/, db-compare/, dump-db/, edit-docs/, build-docs/, icon-pack-builder/
+ web-clipper/, website/, db-compare/, dump-db/, edit-docs/, build-docs/, icon-pack-builder/, script-deployer/
packages/
trilium-core/ # entities, services, SQL, sync, most API routes — shared by server, desktop, standalone
commons/ # types + utilities shared with the client
@@ -125,12 +124,15 @@ Shared components live in `apps/client/src/widgets/react/` — **always** reuse
### Electron Desktop App
`apps/desktop` runs server + client in one Electron process; the renderer loads over the `trilium-app://` custom protocol and talks to main only through the preload bridge (`window.electronApi`, typed by `packages/commons/src/lib/electron_api_interface.ts`). `nodeIntegration` is off, `contextIsolation` is on, `@electron/remote` is gone — never `require("electron")` in client code. Adding an API means interface + `preload.ts` + an `ipcMain` handler in the owning service + a spec. Load the **`developing-electron-desktop` skill** for the recipe, the security model, running/launch errors and testing.
+### Standalone (in-browser) app
+`apps/standalone` runs the client on the page and `@triliumnext/core` — plain JS — in a dedicated Web Worker over `@sqlite.org/sqlite-wasm` persisted in OPFS; a Web Lock elects the one tab that owns the database and the service worker forwards other tabs' API calls to it. Every core provider has a browser twin in `apps/standalone/src/lightweight/` — **a new provider or Node import in core breaks this build first.** Load the **`developing-standalone` skill** before touching `sw.ts`, `main.ts`, `local-server-worker.ts`, `lightweight/*` or `vite.config.mts`.
+
### Mobile (Capacitor) app
`apps/mobile` wraps the standalone WASM build in a Capacitor WebView — no network backend. Android runs at `https://localhost` and routes API calls through the service worker; iOS runs at `capacitor://localhost`, where no service worker can register, so `apps/standalone/src/ios-interceptors.ts` stands in. **`iosScheme: "https"` is a no-op and must not be re-added, and the iOS interceptor path is not dead code.** Load the **`developing-capacitor-mobile` skill** before touching `apps/mobile`, `ios-interceptors.ts`, `capacitor_http_handler.ts` or the `capacitor:` branches of `sw.ts`/`main.ts`.
### Database
-SQLite (`better-sqlite3` on Node, sql.js in standalone) behind `packages/trilium-core/src/services/sql/` (`DatabaseProvider`, prepared-statement cache, transactions). Schema: `packages/trilium-core/src/assets/schema.sql`; migrations: integer-versioned entries in the descending `MIGRATIONS` array in `packages/trilium-core/src/migrations/migrations.ts` (inline SQL or a `NNNN__description.ts` module) — load the **`evolving-the-data-model` skill** before adding a column or migration.
+SQLite (`better-sqlite3` on Node, `@sqlite.org/sqlite-wasm` on OPFS in standalone) behind `packages/trilium-core/src/services/sql/` (`DatabaseProvider`, prepared-statement cache, transactions). Schema: `packages/trilium-core/src/assets/schema.sql`; migrations: integer-versioned entries in the descending `MIGRATIONS` array in `packages/trilium-core/src/migrations/migrations.ts` (inline SQL or a `NNNN__description.ts` module) — load the **`evolving-the-data-model` skill** before adding a column or migration.
### Internationalization
@@ -180,7 +182,7 @@ Use `note.getOwnedAttribute()` for direct, `note.getAttribute()` for inherited.
- **Server tests** (`apps/server/spec/`): Vitest, must run sequentially (shared DB), forks pool, max 6 workers
- **Client tests** (`apps/client/src/`): Vitest with happy-dom environment, can run in parallel
-- **Core tests** (`packages/trilium-core/src/**/*.spec.ts`): `trilium-core` has no runner of its own — the **server and standalone suites both include** its specs (`apps/server/vite.config.mts`, `apps/standalone/vite.config.mts`) and run them against different platform providers (node + better-sqlite3 vs. happy-dom + sql.js WASM). Green under `pnpm --filter server test` is **not** proof; run `pnpm --filter standalone test` as well. See the `writing-unit-tests` skill for the cross-runtime traps
+- **Core tests** (`packages/trilium-core/src/**/*.spec.ts`): `trilium-core` has no runner of its own — the **server and standalone suites both include** its specs (`apps/server/vite.config.mts`, `apps/standalone/vite.config.mts`) and run them against different platform providers (node + better-sqlite3 vs. happy-dom + sqlite-wasm). Green under `pnpm --filter server test` is **not** proof; run `pnpm --filter standalone test` as well. See the `writing-unit-tests` skill for the cross-runtime traps
- **E2E tests** (`packages/trilium-e2e/`): Shared Playwright tests, run via `pnpm --filter server e2e` or `pnpm --filter standalone e2e`
- **ETAPI tests** (`apps/server/spec/etapi/`): External API contract tests
- **Browser-mode tests** (`packages/ckeditor5`) drive a real headless Chrome via `@vitest/browser-webdriverio`; where its downloaded Chrome cannot run (NixOS), point `CHROME_BIN`/`CHROMEDRIVER_PATH` at a matching system pair — never start a chromedriver by hand or add a local override config. See the `ckeditor5-testing` skill