Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
chore(skills): fold accumulated findings into CLAUDE.md and the skills
Elian Doran3882013d2f1e
diff --git a/.claude/skills/building-client-ui/SKILL.md b/.claude/skills/building-client-ui/SKILL.mdindex 0006c2c183..2fb18b5f1c 100644--- a/.claude/skills/building-client-ui/SKILL.md+++ b/.claude/skills/building-client-ui/SKILL.md@@ -1,6 +1,6 @@---name: building-client-ui-description: Use when building or changing any UI in the Trilium client (`apps/client`) — a dialog, a settings pane, a form, a toolbar, a badge, a dropdown menu, a type widget, a control floating over a note's content (map, mind map, image, diagram, presentation), or any component that reads/writes a note's title, label, relation, blob or option. Catalogues the froca-reactive hooks (useNoteProperty / useNoteLabel / useNoteBlob / useChildNotes / useTriliumOption / useNoteContext) and which `loadResults` filter each already wires, the reusable Preact components under `apps/client/src/widgets/react/` (which one to reach for instead of a hand-rolled `<input>`/`<button>`/pill), the `Dropdown` backdrop-blur rules (`noDropdownListStyle` / `portalToBody`), the `OverlayControlGroup` / `OverlayToolbar` contract for controls over a canvas, and the event-summoned Modal/LazyDialog wiring. The home for client UI guidance that outgrows CLAUDE.md.+description: Use when building or changing any UI in the Trilium client (`apps/client`) — a dialog, a settings pane, a form, a toolbar, a badge, a dropdown menu, a type widget, a control floating over a note's content (map, mind map, image, diagram, presentation), or any component that reads/writes a note's title, label, relation, blob or option. Catalogues the froca-reactive hooks (useNoteProperty / useNoteLabel / useNoteBlob / useChildNotes / useTriliumOption / useNoteContext) and which `loadResults` filter each already wires, the reusable Preact components under `apps/client/src/widgets/react/` (which one to reach for instead of a hand-rolled `<input>`/`<button>`/pill), the `Dropdown` backdrop-blur rules (`noDropdownListStyle` / `portalToBody`), the `OverlayControlGroup` / `OverlayToolbar` contract for controls over a canvas, the event-summoned Modal/LazyDialog wiring, and how to boot a login-free fixture instance to inspect real computed styles when a style, placement or stacking bug cannot be read off the stylesheets. The home for client UI guidance that outgrows CLAUDE.md.---# Building client UI@@ -108,6 +108,15 @@ Two rules that apply to all of them:- Pass **`portalToBody`** instead when the menu is fine but an *ancestor* establishes a containment/backdrop root (`container-type`, `transform`, `filter` — e.g. the peeked right pane), which flattens the blur into a flat tint.- If a menu looks transparent rather than frosted, check these two before reaching for CSS overrides.+### A transformed ancestor also breaks placement and stacking++`portalToBody` has a second, unrelated reason to exist. `body.mobile .dropdown-menu` forces `position: fixed`, and the settings dialog's `.modal-dialog` carries a `transform` (the mobile master-detail slide between the page list and the page). A transformed ancestor is both:++1. the **containing block** for `position: fixed`, so a menu left to place itself lands adrift — measured at 160×160 at x=209, mid-page, on a Pixel 7 viewport; and+2. a **stacking context**, so the menu's `z-index: 3000` is confined inside the modal's own `z-index: 1055`. `#context-menu-cover` (the `mobileBackdrop`) is a `<body>` child at `z-index: 2500`, so it paints above the *whole* modal — dimming the menu along with the page behind it.++Both symptoms read as CSS bugs rather than containing-block ones. A mobile menu inside a modal wants `portalToBody` **plus** `dropdownContainerClassName="mobile-bottom-menu"` — see `CollapsedChoice` in `apps/client/src/widgets/react/SegmentedChoice.tsx`. Diagnose by walking the menu's ancestors for `transform` / `filter` / `container-type` in the running app rather than reasoning about the stylesheets.+## Controls floating over a note's contentAny control laid **over** a note's own content — a geo map, a mind map, an image, a video, a diagram, a presentation, and whatever comes next — goes on one of two shared components. **Never hand-roll a `<button>` with `tn-overlay-*` classes**: those classes are the components' business, and a site that writes them itself also has to write the ref, the tooltip, the `aria-label` and the `type="button"` that the component already owns.@@ -168,6 +177,7 @@ Full prop reference, `LazyDialog` mechanics and the eager exceptions: [reference- **Bootstrap utility classes or inline static styles on `Form*` components** — use the sibling per-component `.css` scoped under a root class.- **Hand-rolled overlay buttons** — `tn-overlay-*` classes at a call site instead of `OverlayControlGroup` / `OverlayControlButton`.- **Copying the jQuery lifecycle** (`doRenderBody` / `refreshWithNote` / `this.$widget`) into new `.tsx` — use `useLegacyWidget` only to embed an existing widget.+- **Diagnosing a style or placement bug from the stylesheets** — the load order in a hand-built test page does not match the app's, so the bug can fail to reproduce and send you after the wrong cause. Measure computed styles in a running instance: [references/inspecting-the-running-app.md](references/inspecting-the-running-app.md).> Not a footgun here: `isElectron()` / `isMac()` from `apps/client/src/services/utils.ts` are runtime checks safe at module load. The "call only after init" trap is a **trilium-core** concern (`utils/index.ts` → `getPlatform()`), not client UI.@@ -177,5 +187,6 @@ Full prop reference, `LazyDialog` mechanics and the eager exceptions: [reference|---|---|| [references/hooks-catalog.md](references/hooks-catalog.md) | All 60 `use*` hooks grouped by purpose, one line each with the `loadResults` filter it wires — the anti-re-derivation asset. || [references/dialogs.md](references/dialogs.md) | Full `Modal` prop reference, the 5-step summon→register recipe, `LazyDialog` mechanics, the four eager exceptions, the `sort_child_notes.tsx` walkthrough. |+| [references/inspecting-the-running-app.md](references/inspecting-the-running-app.md) | Booting a login-free instance on the e2e fixture document (in memory, no build, no password) to measure real computed styles, plus how to read a cascade or stacking problem in the running app. Reach for it whenever the answer depends on what actually won, not on what the stylesheets say. |Related skills: **writing-unit-tests** (rendering these components and testing hooks with the easy-froca fixtures), **analyzing-coverage** (measuring client coverage), **working-with-translations** (adding the English strings these components display).diff --git a/.claude/skills/building-client-ui/references/inspecting-the-running-app.md b/.claude/skills/building-client-ui/references/inspecting-the-running-app.mdnew file mode 100644index 0000000000..a8b68b8732--- /dev/null+++ b/.claude/skills/building-client-ui/references/inspecting-the-running-app.md@@ -0,0 +1,59 @@+# Inspecting the running app++Some UI questions cannot be answered from the stylesheets — which rule actually won, why a menu+landed where it did, whether a blur is real or a flat tint. Reasoning about the cascade from the+sources is unreliable enough to have produced wrong diagnoses more than once, because the load+order in a hand-built test page does not match the app's. Measure `getComputedStyle` in a real+instance instead.++## Boot a login-free instance on the e2e fixture++Run the server against the e2e fixture document, entirely in memory, so there is no production+build, no password, and no risk to the user's own data:++```bash+cd apps/server && NODE_ENV=development TRILIUM_ENV=dev TRILIUM_PORT=37999 \+ TRILIUM_DATA_DIR=spec/db \+ TRILIUM_DOCUMENT_PATH=../../packages/trilium-core/src/test/fixtures/document.db \+ TRILIUM_INTEGRATION_TEST=memory TRILIUM_RESOURCE_DIR=src npx tsx ./src/main.ts+```++`TRILIUM_INTEGRATION_TEST=memory` keeps every write in RAM, so `spec/db` stays clean. There is no+login screen. Append `/?mobile` to the URL to force the mobile layout.++**Do not assume the user's own instance is usable instead.** Ports 8080 and 37840 are typically a+share-only server and the *installed* Trilium, not the repo build — and two processes can share one+data directory, which makes cross-process writes look like cache corruption.++## Driving it++Use Playwright imported by **absolute path**+(`file:///…/node_modules/playwright/index.mjs`) — a script written into the scratchpad cannot+resolve `playwright` by name.++Fixture gotchas:++- It opens on a **protected** note, so click another note first.+- It runs the **new layout**, so there is no ribbon — the attributes editor opens from the+ `… attributes` button in `.status-bar`.++## Stopping it++Killing the backgrounded `npx tsx` wrapper leaves the node child alive and still holding the port,+so the next boot fails with "Port 37999 is already in use". Kill the listener:++```powershell+Get-NetTCPConnection -LocalPort 37999 -State Listen | % { Stop-Process -Id $_.OwningProcess -Force }+```++## What to measure once it is up++- **A rule that seems not to apply** — dump `getComputedStyle` on the element, then scan the+ stylesheets with `el.matches(rule.selectorText)` to find what actually set the property. If no+ rule matches, suspect a global selector from the CKEditor theme CSS, which Vite injects app-wide+ the first time a text note renders (see the **ckeditor5-plugin-development** skill,+ `references/conventions.md`). That is the usual cause of "this UI breaks only after opening a+ note".+- **A mispositioned or self-dimming fixed-position menu** — walk the ancestors for `transform`,+ `filter` and `container-type` rather than reading the stylesheets; any of them creates a+ containing block and a stacking context (see "Dropdown menus and the backdrop blur" in `SKILL.md`).diff --git a/.claude/skills/ckeditor5-plugin-development/references/conventions.md b/.claude/skills/ckeditor5-plugin-development/references/conventions.mdindex 78c34476f7..ed9a1e56b2 100644--- a/.claude/skills/ckeditor5-plugin-development/references/conventions.md+++ b/.claude/skills/ckeditor5-plugin-development/references/conventions.md@@ -49,6 +49,17 @@ Follow the existing files in the package you touch; don't add or strip headers w`ck-toolbar__group_collapsed` (single underscore); key-value `ck-dropdown-menu_theme_lark`.IDs follow the same rules with `ck-` prefix. CSS vars inside `.ck-content` must be`--ck-content-*` (`ck-content-variable-name`).+- **Theme CSS is global — scope every selector.** Vite injects `packages/ckeditor5/src/theme/*.css`+ app-wide the first time any text note renders (including the geo map's detail pane mounting+ `NoteDetail` on a text note). There is no scoping boundary, and `!important` there beats even+ Popper's inline styles on Bootstrap tooltips and popovers. A selector that is not anchored to+ `.ck`, `ML__` or `data-ml-*` silently restyles unrelated UI everywhere — and only *after* an+ editor has mounted, which presents as a "works until you open X" bug in a feature that has+ nothing to do with the editor. Real case: `[role="tooltip"] { position: fixed !important }` in+ `math_form.css` collapsed the geomap marker preview (a MapLibre popup wrapping the app tooltip)+ to a 0×0 box, and read as a MapLibre/Firefox positioning bug. When debugging that symptom, dump+ `getComputedStyle` on the broken element and scan stylesheets with `el.matches(rule.selectorText)`+ — pay particular attention to bare tag and attribute selectors.## Imports & modulesdiff --git a/.claude/skills/ckeditor5-plugin-development/references/ui-and-localization.md b/.claude/skills/ckeditor5-plugin-development/references/ui-and-localization.mdindex ae665e0a46..7b74c54f71 100644--- a/.claude/skills/ckeditor5-plugin-development/references/ui-and-localization.md+++ b/.claude/skills/ckeditor5-plugin-development/references/ui-and-localization.md@@ -234,6 +234,35 @@ collection, uses `submitHandler({ view: this })` in `render()` to turn native su`submit` event, delegates button events (`cancelButtonView.delegate('execute').to(this,'cancel')`),and exposes a `focus()` method. Add `tabindex: '-1'` and the `ck` class to UI roots.+### Custom DOM inside a balloon needs `ck-reset_all-excluded`++CKEditor wraps every floating UI root — balloons, mention panels, dropdown panels — in+`.ck.ck-reset_all`. Its companion rule++```css+.ck-reset_all :not(.ck-reset_all-excluded, .ck-reset_all-excluded *) { … }+```++matches **every** descendant and forces `border: 0; width: auto; height: auto; padding: 0;+margin: 0; background: none; color: var(--ck-color-text); font: …`. It has specificity (0,2,0)+and `ckeditor5.css` loads after the client stylesheets, so ordinary client rules and shared+Preact component styles (e.g. `.ext-badge` from `apps/client/src/widgets/react/Badge.css`)+silently lose inside a balloon.++The symptom reads as a missing stylesheet rather than a cascade conflict: the element keeps its+classes and keeps every property the reset does **not** name (`display`, `border-radius`, `gap`),+so only some of its styling disappears.++**Fix:** put `ck-reset_all-excluded` on the outermost custom element — a mention feed+`itemRenderer` root, a custom `View`'s element, anything wrapped in `MentionDomWrapperView`. The+`:not()` covers the whole subtree, so one class exempts everything inside it. Do **not**+out-specify the reset instead: winning a specificity war means restating the borrowed component's+internals, which then drift from it.++Diagnosing this from the sources is a trap — load `ckeditor5.css` *first* in a static test page+and the client rules win, so the bug does not reproduce. Inspect `getComputedStyle` in the real+app instead.+## Dialogs & modalsThe `Dialog` plugin shows views in a dialog (`isModal: false`) or modal (`isModal: true`,diff --git a/.claude/skills/ckeditor5-testing/SKILL.md b/.claude/skills/ckeditor5-testing/SKILL.mdindex 90f7d4487c..91e9d01d87 100644--- a/.claude/skills/ckeditor5-testing/SKILL.md+++ b/.claude/skills/ckeditor5-testing/SKILL.md@@ -230,7 +230,7 @@ into later specs.) See `references/patterns.md` for the recipe.|------|-----------|| `references/test-utilities.md` | Testing against a real `ClassicEditor` (lifecycle, `licenseKey: 'GPL'`), and the `_setModelData`/`_getModelData`/`_getViewData` helpers from `'ckeditor5'` + the `[]`/`{}` selection syntax. || `references/patterns.md` | Idiomatic recipes per concern (schema, conversion round-trips, commands, UI, keystrokes, events, async), all against a real editor; the `glob`/clipboard/jQuery-`$` stubbing recipe (via the globals kit's `installGlobMock`/`mockClipboard`); note on the 100% coverage gate for browser-mode packages. |-| `references/running-and-config.md` | The WebdriverIO `vitest.config.ts` shape, `pnpm --filter` commands, the debug command, `pnpm test:parallel`/`test:sequential` (ckeditor5 + math sequential), coverage thresholds. |+| `references/running-and-config.md` | The WebdriverIO `vitest.config.ts` shape, `pnpm --filter` commands, the debug command, `pnpm test:parallel`/`test:sequential` (ckeditor5 + math sequential), coverage thresholds, and troubleshooting a session that never starts (staged-Chrome/chromedriver version mismatch, the worktree dep-optimizer hang, orphaned headless Chrome). || `references/test-conventions.md` | Trilium test **conventions & gotchas**: real-browser event timing, real-editor teardown, the both-assertion-styles note, unreachable code vs. the 100% gate, and the pointer to `writing-unit-tests`. |## Quick review checklistdiff --git a/.claude/skills/ckeditor5-testing/references/running-and-config.md b/.claude/skills/ckeditor5-testing/references/running-and-config.mdindex ddc4b4a3bb..5e879698d5 100644--- a/.claude/skills/ckeditor5-testing/references/running-and-config.md+++ b/.claude/skills/ckeditor5-testing/references/running-and-config.md@@ -118,6 +118,57 @@ coverage: {`reporter: ['text', 'lcov']` + that `reportsDirectory` are what the `analyzing-coverage`analyzer (`lcov.info`) and Codecov consume — keep them when adding coverage to a package.+## When the session never starts++Two failure modes look like a broken suite but are environmental.++### "This version of ChromeDriver only supports Chrome version N"++webdriverio auto-manages the driver by detecting the installed Chrome's version. When Chrome has a+**staged update** — a `new_chrome.exe` and a new version folder sitting in the install directory,+waiting for a browser restart — detection reads the *staged* version and downloads that+chromedriver, while the `chrome.exe` that actually launches is still the old major. Every run then+dies at session start.++Restarting Chrome fixes it permanently. To run before then, point wdio at the matching driver+already in its cache (`%TEMP%\chromedriver\win64-<version>\` on Windows) by editing+`packages/ckeditor5/vitest.config.ts` — at the **provider factory** level, because+`@vitest/browser-webdriverio` drops per-instance options and only the factory's reach `remote()`:++```ts+provider: webdriverio({+ capabilities: {+ "wdio:chromedriverOptions": { binary: "<cached>/chromedriver-win64/chromedriver.exe" }+ }+}),+```++**Revert that edit after the run — never commit it.** `browserVersion` pins do not help at either+level; wdio still resolves the local binary.++### The run hangs at `[vite] [optimizer] bundling dependencies...`++In a fresh git worktree the browser-mode suite reliably stalls there and never runs a test,+eventually reporting "Browser connection was closed" or "no tests" — even after clearing+`node_modules/.vite` and killing stray browsers. The cold Vite dep-optimize for the very large+CKEditor dep set does not complete (it may be contending with the editor's own Vitest extension+workers). The same spec runs in seconds from the **main checkout**, where that cache is warm.++So validate browser-mode specs from the main checkout: copy the new `*.ts` + `*.spec.ts` into+`<main>/packages/ckeditor5/src/plugins/`, run them there (add+`--coverage.enabled --coverage.include='<file>'` to check the 100 % gate against just that file),+then delete the temporary copies. A spec that imports the plugin directly does not need the+`plugins.ts` / toolbar wiring to be present in main. Client (`apps/client`) happy-dom tests are+unaffected — this is browser-mode only.++### After an aborted run++Killed runs leave **orphaned headless Chrome** processes (`--test-type=webdriver`, a `scoped_dir`+user-data directory) holding resources. Kill those, and only those — never the user's interactive+Chrome, and never the editor's Vitest extension workers or its Vite dev server. Also don't pipe+vitest through `Select-Object -Last N`: it buffers everything until exit, so you lose all progress+output.+## DebuggingBrowser-mode packages support an inspector + visible browser:diff --git a/.claude/skills/cutting-a-release/SKILL.md b/.claude/skills/cutting-a-release/SKILL.mdindex bc6fdc76da..1904a1f32a 100644--- a/.claude/skills/cutting-a-release/SKILL.md+++ b/.claude/skills/cutting-a-release/SKILL.md@@ -1,6 +1,6 @@---name: cutting-a-release-description: Use when cutting, preparing, or debugging a Trilium release — bumping the monorepo version, tagging, or diagnosing a failed "Release" workflow run. Covers the ordered bump recipe (edit root package.json → chore:update-version → commit → v-prefixed tag → push), which of the TWO divergent version scripts to use (update-version for releases vs update-nightly-version for CI nightlies), why the CI version-consistency gate validates only 5 of the 8 files update-version writes, the exact `docs/Release Notes/Release Notes/<tag>.md` path the publish step hard-requires, the substring-based rc/beta "latest" labeling, and the RELEASE_PAT (not GITHUB_TOKEN) dependency. Bundles a pre-flight verifier that catches what the CI gate misses before you push the tag.+description: Use when cutting, preparing, or debugging a Trilium release — bumping the monorepo version, tagging, or diagnosing a failed "Release" workflow run. Covers the ordered bump recipe (edit root package.json → chore:update-version → commit → v-prefixed tag → push), which of the TWO divergent version scripts to use (update-version for releases vs update-nightly-version for CI nightlies), why the CI version-consistency gate validates only 5 of the 8 files update-version writes, the exact `docs/Release Notes/Release Notes/<tag>.md` path the publish step hard-requires, the substring-based rc/beta "latest" labeling, and the RELEASE_PAT (not GITHUB_TOKEN) dependency. Also covers dispatching `nightly.yml` on a branch to test packaging on real CI runners (publish is gated on `main`; other refs upload artifacts). Bundles a pre-flight verifier that catches what the CI gate misses before you push the tag.---# Cutting a Trilium release@@ -87,6 +87,28 @@ This isn't theoretical — real release-prep commits touched *different* file su- **Don't hand-edit child package.jsons** — let `update-version` propagate from root, or they desync silently past the 5-file gate.- **`update-version` is idempotent but partial in the diff** — it rewrites all 8 unconditionally; only the previously-stale ones show up in `git status`. "Only 6 files changed" is normal and not a sign you missed one.+## Testing packaging on CI: dispatching `nightly.yml` on a branch++Dispatching the nightly workflow on a branch (`gh workflow run "Nightly Release" --ref <branch>`)+is the only way to exercise real packaging on CI runners without merging. That is safe now: every+publish step is gated on `github.ref == 'refs/heads/main'` (`nightly.yml:103` desktop,+`nightly.yml:144` mobile), and any other ref — a `workflow_dispatch` on a branch, a+`renovate/electron-forge*` push, a PR — uploads its desktop, mobile APK and server outputs as+**workflow artifacts** instead (`nightly.yml:115,154`).++The main ref is written as a literal string on purpose: the `schedule` event payload is minimal,+so deriving the default branch from it is unreliable.++Before this landed (PR #10614), a branch dispatch sprayed branch-named assets onto the public+`nightly` release. On a checkout predating it, clean up with:++```bash+gh release view nightly --repo TriliumNext/Trilium --json assets --jq '.assets[].name'+gh release delete-asset nightly "<name>" --yes+```++Filter on the branch slug — the real nightly assets come from `main`.+## Hotfix variantSame recipe, different branch. Per `docs/Developer Guide/Developer Guide/Branching strategy.md:20-30`: create a `hotfix` branch **from the release tag**, cherry-pick the needed fixes from `main`, bump + release from `hotfix` (the recipe above), then merge `hotfix` back into `main` via PR. The tag still triggers `release.yml` the same way — nothing about the bump/notes/labeling rules changes.diff --git a/.claude/skills/developing-standalone/SKILL.md b/.claude/skills/developing-standalone/SKILL.mdindex 6aec76d421..7028e6bd3d 100644--- a/.claude/skills/developing-standalone/SKILL.md+++ b/.claude/skills/developing-standalone/SKILL.md@@ -67,6 +67,16 @@ The worker's top-level imports **are** its startup cost — prefer dynamic impor- 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/`.+### Where a dynamic import actually splits — and where it does nothing++Core is not code-split the way its module layout suggests. Rollup folds the `packages/trilium-core` modules into a **single ~2 MB chunk** (named after an arbitrary constituent, e.g. `abstract_provider-<hash>.js`) that ~33 core modules — `becca_loader`, `browser_routes`, `crypto_provider`, the migrations — import statically, and the worker pulls in at startup. Anything reachable from that graph lands in the eager chunk no matter how the leaf that uses it imports it.++So converting a static `import` to `await import()` **inside a core module** often defers nothing. Lazy-loading `sax` in `enex.ts` produced a **byte-for-byte identical** standalone bundle — same chunk content hash, same total — because `sax` was reachable statically elsewhere in the eager graph. The prediction that it would save ~12–15 KB came from reasoning by analogy to another module; it did not survive an A/B build, and was reverted.++It is not a universal no-op, though. `await import("officeparser")` inside `services/office_preview.ts` **did** split out (`officeparser.browser-<hash>.js`, ~2.6 MB, fetched lazily), because nothing else in the eager graph imported officeparser — that one dynamic import was the dep's only path in.++The rule: a dynamic import inside core splits a dep out **only if the dep has no other static importer in the core graph**. Deferring at the route or service boundary (the `import.ts` route that statically imports `enex.js`) is the reliable lever. Either way, confirm with an A/B build — compare chunk hashes and `grep` the built output for a real `import(` — and don't bother at all for a ~40 KB dep inside a chunk that always loads.+## Running```bashdiff --git a/.claude/skills/writing-unit-tests/SKILL.md b/.claude/skills/writing-unit-tests/SKILL.mdindex 39ef3c99a3..489a41144a 100644--- a/.claude/skills/writing-unit-tests/SKILL.md+++ b/.claude/skills/writing-unit-tests/SKILL.md@@ -71,11 +71,12 @@ coverage: {- **Do NOT use `all: true`** — it was removed in Vitest 4 and is a type error; `include` already pulls in untested files.- If a config sets Vite `root: "src"` (e.g. `apps/standalone`), coverage `include` globs resolve **relative to `src`**, so use `["**/*.{ts,tsx}"]`, not `["src/**/…"]`.- **Files outside the project `root` need `coverage.allowExternal: true`.** v8 defaults it to `false`, which **silently drops** every out-of-root file — so an `include` glob alone (e.g. `../../packages/trilium-core/src/**`) is ignored and contributes nothing. `trilium-core` has no runner of its own; its coverage is measured *through* `apps/server` and `apps/standalone`, and both **must** set `allowExternal: true` **plus** a core glob in `coverage.include` whose `../` depth matches that suite's `root`: `../../packages/trilium-core/src/**` for server (root `apps/server`), `../../../packages/trilium-core/src/**` for standalone (root `apps/standalone/src`). Without `allowExternal` core never reaches the lcov or Codecov. The lcov writes these as `../…/packages/…` paths; `codecov.yml`'s `fixes:` entries strip the `../` so they map onto the repo tree.-- For provably-unreachable defensive branches, mark them with `/* v8 ignore next */` / `/* v8 ignore start */…/* v8 ignore stop */` and a one-line reason — don't delete the guard or write a fake test.+- For provably-unreachable defensive branches, mark them with `/* v8 ignore next */` / `/* v8 ignore start */…/* v8 ignore stop */` and a one-line reason — don't delete the guard or write a fake test. `/* v8 ignore next */` does **not** reliably suppress a branch sitting on a `} else if (…) {` line — use the `start`/`stop` form there. Better still, check whether the arm is dead because the code can be simplified: a trailing `else if (name) { … } return []` where `name` is provably truthy collapses to a direct `return`, removing the branch honestly instead of hiding it. Project style is a plain `/* v8 ignore next -- reason */` — no `@preserve`.- **Checking one file's coverage:** the v8 **text** reporter crashes (`PARSE_ERROR` while remapping unrelated uncovered core files) on single-spec `--coverage` runs. Produce `lcov`/`json`/`json-summary` instead and parse it with the **analyzing-coverage** skill's `coverage.mjs` (`… summary` for pct/aggregate, `… gaps --filter <file>` for the uncovered line list). The full-suite text report (run over a directory) is fine. Don't hand-roll a coverage parser — that script already handles all three formats and the Windows footguns.## Universal gotchas+- **A green Vitest run is not proof the spec compiles.** Vitest strips types with esbuild, so specs are never type-checked by the run itself — and `apps/client/tsconfig.app.json` deliberately **excludes** `src/**/*.spec.ts(x)`. They are checked by `tsconfig.spec.json`, which `pnpm typecheck` reaches through the project references, so **`pnpm typecheck` is the only thing that catches a broken spec** — but run it **once, after the whole batch of specs is written**, never per file or per edit. It walks the project references and costs real time; spending that repeatedly is the single easiest way to make a test-writing session slow. Passing tests routinely hide mechanical type errors that then fail CI. The recurring ones: `act(() => someExpression)` returning a value where a `void` callback is expected, `Component | undefined` passed where the context wants `| null`, and mock-froca helpers whose default `getNote = vi.fn(async () => undefined)` infers `Promise<undefined>` and rejects a caller's `vi.fn(async () => someNote)` — type such params loosely (`(...args: unknown[]) => Promise<unknown>`).- **No non-null assertions (`!`)** — never use the TypeScript postfix `!` operator, even in tests. Narrow instead: `becca.getNoteOrThrow(id)`/`getAttachmentOrThrow(id)` instead of `becca.getNote(id)!`; `value?.prop ?? fallback` then assert; or capture into a const after an `expect(x).toBeDefined()`/null check. (Project rule — see `CLAUDE.md` Code Style.)- **`vi.mock` is hoisted** above imports. Put component/module imports *after* the `vi.mock(...)` calls; mock factories can't reference outer non-hoisted variables. Partial-mock with `async (importOriginal) => ({ ...(await importOriginal()), onlyThis: vi.fn() })`.- **Don't assert on translated (i18n) strings** — assert structure/keys/behavior (classes, counts, ids), not human-readable English.diff --git a/CLAUDE.md b/CLAUDE.mdindex 79adfd2dfc..ae4f4ce985 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -20,9 +20,9 @@ pnpm typecheck # all projects, native compiler, a fewpnpm dev:format-check | dev:format-fix # stylistic formatting```-- **Never run ESLint** (`dev:linter-check`, `dev:linter-fix`, `npx eslint`) — it dies with an out-of-memory error, so a run tells you nothing. CI lints. (`packages/*` is ignored by the ESLint config anyway.)+- **Never run ESLint** (`dev:linter-check`, `dev:linter-fix`, `npx eslint`) — it dies with an out-of-memory error, so a run tells you nothing. CI does not lint either — there is no `eslint`/`linter-check` step anywhere in `.github/workflows/`, so lint findings never block a merge; the gates are `pnpm typecheck` and the per-package `test --coverage` runs. (`packages/*` is ignored by the ESLint config anyway.)- **Never run `pnpm test:all`, `test:parallel`, `test:sequential`, or a whole-package `coverage`** during development — CI runs them on every push. Run the **narrowest** suite that covers what you touched: `pnpm --filter <pkg> test <pattern>` (Vitest treats the trailing argument as a substring filter over spec paths). Core specs need **two** runs, server and standalone (see Testing). Only reach for a full suite if the user asks or wants a final check.-- **Typecheck with `pnpm typecheck`, not a raw `tsc`** — it resolves the project references a hand-written `tsc -p …` gets wrong, and is cheap enough to run after every change.+- **Typecheck with `pnpm typecheck`, not a raw `tsc`** — it resolves the project references a hand-written `tsc -p …` gets wrong, and is far cheaper than a test suite. Still, run it **once, after a piece of work is finished** — not after every edit: it builds the project references, and repeating it is a common way to lose minutes across a session.- **Two TypeScript versions, on purpose**: root `package.json` has `typescript` 6.x (the JS compiler API that TypeDoc, typescript-eslint and the browser-bundled language service in `packages/codemirror` load) and `@typescript/native` (7, drives `pnpm typecheck` and owns the `tsc` bin). Do **not** bump `typescript` to 7, dedupe them, or switch to the `@typescript/typescript6` shim (no `lib.*.d.ts` → client build breaks). Reasoning: `docs/Developer Guide/Developer Guide/Environment Setup.md`, "TypeScript".## Git Workflow@@ -30,6 +30,8 @@ pnpm dev:format-check | dev:format-fix # stylistic formatting- **Committing directly on `main` is allowed and expected** for small fixes and self-contained features — do **not** create a branch first for those. The default "branch before committing on the default branch" rule does not apply to this repository.- **Large or risky work goes on a branch**: multi-commit features, migrations, refactors spanning many packages, anything that needs review or a PR before landing.- Only commit when explicitly asked to **in that message**, and the ask covers only the step it accompanies — a later step is left uncommitted until asked again. A remark like "commits go on main" is about branch choice, not standing permission to commit. Otherwise leave changes staged/unstaged for review.+- **The issue-closing keyword goes in the commit/PR subject**, not the body — `fix(markdown): wrap imported tables (closes #10270)`.+- **`git rm` is not a neutral delete.** It leaves the deletion staged, so a commit made before the matching reference updates are staged lands a `HEAD` pointing at a module that no longer exists. When removing a file whose references are edited in the same pass, delete it from the filesystem instead, or land the deletion and the reference updates together — never leave the index in a state that is broken on its own.## Monorepo Structure@@ -173,9 +175,10 @@ Use `note.getOwnedAttribute()` for direct, `note.getAttribute()` for inherited.- 4-space indent, semicolons, double quotes, max line 100, Unix line endings (the format config enforces these). Imports sorted per `eslint-plugin-simple-import-sort` (packages before relative, alphabetical within a group) — only ESLint checks that and it isn't run locally, so sort by hand.- **Never use the non-null assertion `!`**, tests included. Narrow instead: `?.`, `?? fallback`, an explicit check, or an `*OrThrow` accessor (`becca.getNoteOrThrow(id)`).+- **Never use `Array.prototype.forEach`** — write a `for...of` loop instead, and iterate `array.entries()` when the index is needed (`for (const [index, item] of arr.entries())`). It reads better and allows `break`/`continue`/`await`.- **Helpers go below the primary export** they support (or in another module), never between the imports and the main definition — the entry point reads first.- **No ~10-SLOC modules.** A component, hook or helper of about ten lines of substance joins an existing module that owns the same concept (e.g. `OverlayFullscreenButton` lives in `OverlayControlGroup.tsx`, its tests in that spec); a file of its own costs a module boundary and an import per call site and buys nothing. Split out once it has grown.-- **Comments** — Google developer-documentation style: plain English, present tense, active voice, real identifiers (`froca.getNote()`, not "the cache lookup"); *can*/*might*/*must* used precisely, never *may*. Say what the code does or why it is shaped so, not what changed.+- **Comments** — Google developer-documentation style: plain English, present tense, active voice, real identifiers (`froca.getNote()`, not "the cache lookup"); *can*/*might*/*must* used precisely, never *may*. Say what the code does or why it is shaped so, not what changed. Keep it to a line or two — the reproduction, the measurements and the before/after belong in the commit body, which is the place to be thorough. A comment narrating a defect ("at 375px those ran 28px past the card") ages the moment the layout moves, and the next reader needs only the constraint that still binds, not the investigation.- **CSS comments** never narrate a change (`/* was 8px */`, `/* moved from the toolbar */`) — that is the commit message. Comment only what is non-obvious in place: a browser workaround, a value that must match one elsewhere, a `z-index` in a stacking contract.## Testing