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
docs(skills): record how to measure a bug on the user's device
Elian Doran0cc85009e7d8
diff --git a/.claude/skills/building-client-ui/SKILL.md b/.claude/skills/building-client-ui/SKILL.mdindex 34bd1b40ef..a4516b3d24 100644--- a/.claude/skills/building-client-ui/SKILL.md+++ b/.claude/skills/building-client-ui/SKILL.md@@ -260,6 +260,7 @@ use parameter defaults.- **A `useEffect` cleanup that must run during the unmount** — it runs after paint; reporting to a host or reading a child instance belongs in a `useLayoutEffect` cleanup (see "Preact 11 conventions").- **Importing core names through `preact/compat`** — `createPortal`, hooks and types come from `preact` / `preact/hooks`; compat is for `memo`, `lazy`, `Suspense`, `flushSync`, `useSyncExternalStore`.- **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).+- **Reasoning about what a device's browser reports instead of measuring it** — a bug that lives in mobile Safari's keyboard or viewport cannot be reproduced here, and the specs do not predict WebKit's behavior. Log readings from the device into the dev server's log and replay them: [references/measuring-on-a-device.md](references/measuring-on-a-device.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.@@ -269,6 +270,7 @@ use parameter defaults.|---|---|| [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/measuring-on-a-device.md](references/measuring-on-a-device.md) | Diagnosing a bug that exists only on the user's device (mobile Safari's keyboard, the visual viewport): temporary `window.logInfo` readings into the dev server's log, what to log, and replaying the readings offline to verify a fix. || [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/measuring-on-a-device.md b/.claude/skills/building-client-ui/references/measuring-on-a-device.mdnew file mode 100644index 0000000000..07416e5117--- /dev/null+++ b/.claude/skills/building-client-ui/references/measuring-on-a-device.md@@ -0,0 +1,105 @@+# Measuring on the user's device++Some bugs exist only on a device that cannot be driven from this machine: mobile Safari's keyboard,+the visual viewport, touch scrolling. Playwright's WebKit opens no on-screen keyboard, and there is+no Mac to attach Safari's Web Inspector. Reasoning from the specs about what such a browser reports+has produced wrong models of it — Safari with the keyboard up scrolls the `position: fixed` page+itself, which no reading of the code predicted. Measure instead: have the device write readings to+the dev server's log, then read and replay them here.++## The channel: `window.logInfo` into the server log++The client already sends `logInfo(message)` over the WebSocket (`log-info`, `services/ws.ts`), and+the server writes it to its log as `JS Info: <message>`. Under `pnpm server:start`+(`TRILIUM_DATA_DIR=data`) that log is `apps/server/data/log/trilium-<YYYY-MM-DD>.log`, which you+can read directly. The user opens the dev server on the device over the LAN; nothing else is set+up, no route is added and no screenshot is needed.++This needs the server build in the device's browser. The Capacitor app and standalone run core in+a worker with no server log behind the WebSocket, so a bug only the app shows needs the native+side's logging instead (see the `developing-capacitor-mobile` skill).++## Adding the logging++Keep it temporary and uncommitted, and mark it so it is easy to find and remove:++```ts+// TEMPORARY: iOS Safari viewport diagnostics, sent to the server log as `JS Info: [ios-viewport] …`.+let viewportLogSequence = 0;+function logViewport(reason: string, element: HTMLElement | null, anchor?: HTMLElement | null) {+ const viewport = window.visualViewport;+ const round = (value: number | undefined) =>+ value === undefined ? undefined : Math.round(value * 10) / 10;+ const rect = (target: Element | null | undefined) => {+ if (!target) return undefined;+ const { top, bottom } = target.getBoundingClientRect();+ return { top: round(top), bottom: round(bottom) };+ };+ window.logInfo?.(`[ios-viewport] ${JSON.stringify({+ seq: ++viewportLogSequence,+ t: Math.round(performance.now()),+ reason,+ innerHeight: window.innerHeight,+ scrollY: round(window.scrollY),+ vv: viewport && {+ height: round(viewport.height), offsetTop: round(viewport.offsetTop),+ pageTop: round(viewport.pageTop), scale: round(viewport.scale)+ },+ root: rect(document.getElementById("root-widget")),+ anchor: rect(anchor),+ styleBottom: element?.style.bottom,+ elementRect: rect(element)+ })}`);+}+```++What makes the readings useful:++- **One JSON line per reading, behind a fixed tag** (`[ios-viewport]`), with a sequence number and+ a timestamp, so the lines can be extracted with one `grep` and parsed without ambiguity.+- **Raw inputs, not only the derived value.** Log every number the code computes from+ (`innerHeight`, `scrollY`, each `visualViewport` field) and, as well, the result as it landed+ (`style.bottom`, the element's own rect). With the inputs you can replay a candidate formula+ offline; with the landed rect you can see the error the user sees.+- **A reference element whose position you know.** `#root-widget` is fixed at the top of the page;+ its rect revealed that client coordinates moved with Safari's scroll (`root.top === -scrollY`),+ which is what the code had wrong.+- **The events the code listens to, and the neighbours it does not** — here `visualViewport` resize+ and scroll, plus window `scroll`, `focusin` and `focusout` — and a second reading some 600ms after+ a focus change, once the platform has finished moving things. A bug in which event is missing+ shows up only in the second group.+- **Which instance logged.** Several copies of a component can be mounted (hidden note splits, a+ popup editor kept in the DOM), and the hidden ones log `0/0` rects. Log the element's class and+ filter on a rendered anchor.+- **Always on for the platform under test, with no URL switch.** The user exercises the real app;+ gate only on what the bug needs (`isIOS()`).+- **`window.logInfo?.()`, optional.** Unit tests have no WebSocket and no `logInfo`, so a plain call+ breaks every spec that renders the component.++Then ask the user to reproduce — and, if another browser on the same device behaves, to repeat it+there, for a reading to compare against.++## Reading the log++Extract the tagged lines into JSON Lines in the scratchpad, then parse them in Python:++```bash+grep -o "\[ios-viewport\] {.*}" apps/server/data/log/trilium-<date>.log \+ | sed 's/^\[ios-viewport\] //' > "$SCRATCHPAD/vv.jsonl"+```++A few minutes of panning writes thousands of lines; do not read them by eye. Count them by+`reason` and by instance first, filter to the readings that matter (here: a rendered anchor and the+keyboard up, `innerHeight - vv.height > 150`), and print an evenly spaced sample as a table with a+derived column for the error — the gap between where the element landed and where it belongs.++## Closing the loop++- **Replay the readings through the candidate fix** before asking for another round on the device:+ compute where each logged reading would place the element under the new formula and report the+ spread. For the Safari toolbar, all 453 keyboard-up readings landed within 0.3px of the intended+ 6px margin, which was enough to trust the fix.+- **Turn one reading into a spec** with the logged numbers as its fixture, run it red against the+ old code, then green. The red run's error should equal the defect the log showed (here exactly+ the 118px scroll, counted twice).+- **Remove the logging** once the user confirms the fix on the device, and before committing.diff --git a/.claude/skills/developing-capacitor-mobile/SKILL.md b/.claude/skills/developing-capacitor-mobile/SKILL.mdindex 0fe910294c..5b2d42cfee 100644--- a/.claude/skills/developing-capacitor-mobile/SKILL.md+++ b/.claude/skills/developing-capacitor-mobile/SKILL.md@@ -213,6 +213,8 @@ The project needs `cap sync android` (or `cap update android`) once first, for t- **Only Android-free classes are testable.** Unit tests compile against `android.jar`, whose classes (`Uri`, `Handler`, `Log`, `Base64`, `WebResourceResponse`) are stubs that throw "Method not mocked". Logic therefore lives in classes that import none of them (`LocalRequestBroker`, `NativeHttpProxy`, `InterceptedResponse`), with the WebView, the main thread, base64 and logging passed in; the `Trilium*` classes and `MainActivity` are thin adapters with no tests, and the request-path ones (`TriliumRequestBridge`, `TriliumWebViewClient`, `MainActivity`) are listed under `ignore:` in `codecov.yml` so the patch check does not count them. Keep new native logic on the same side of that line, and a new adapter goes on that list.- **`org.json` comes from a `testImplementation` dependency**, since `android.jar`'s copy is a stub too. **`com.sun.net.httpserver` is not on the test classpath**, so `NativeHttpProxyTest` serves canned responses from a `ServerSocket` (`StubServer`).- **`minSdk` is 24**: `String.join` and `java.util.Base64` need API 26, so production code avoids them; tests can use them.++Client behavior that differs on the device itself (the keyboard, the visual viewport, touch scrolling) can't be reproduced by these suites or by Playwright. When the device's browser shows it against `pnpm server:start`, log readings into the dev server's log and replay them: the `building-client-ui` skill, `references/measuring-on-a-device.md`.The iOS request logic has XCTest tests in a Swift package, `apps/mobile/ios/RequestBroker/`:```bash