AGENTS.md

1# Frontend Guidelines
2 
3**Last Updated:** July 28, 2026
4 
5## Dependencies & Pins
6 
7- [`frontend/README.md`](README.md) is the canonical doc for dependency pin rationale, the `overrides` layer, ESM-only upgrade blockers, and the orphan-audit pattern.
8- **Pins are intentional.** When a version has no caret (e.g., `"axios": "1.17.0"`, `"vuetify": "3.12.2"`), check `frontend/README.md` and `git log -p -S "<pkg>" -- frontend/package.json` for the reason before changing it.
9- npm is a workspace; run `npm install --ignore-scripts --no-audit --no-fund --no-update-notifier` from the **repo root** (not `frontend/`) so the root `package-lock.json` updates.
10- After dep changes run `make audit`, `make build-js`, `make test-js`, and `make notice`.
11- Before adding a new dep — and especially before declaring an existing one "unused" — verify with `rg -nF "<pkg>" frontend …` plus `npm ls <pkg> --all` that no consumer or peer-dep needs it.
12 
13## Frontend Linting & Test Entry Points
14 
15- Run `make -C frontend help` for an overview of the most common frontend targets, and `make -C frontend list` to see all of them.
16- Use the lint and format scripts declared in `frontend/package.json`; all added JS, Vue, and frontend tests must follow those standards.
17- Frontend unit tests use Vitest. Common entry points are `make test-js`, `make vitest-watch`, and `make vitest-coverage`.
18- New JavaScript functions, including helpers, should be tested whenever practical; update existing tests or add new ones as needed.
19- New Vue components should have component-test coverage, and existing component tests should be updated as needed when component behavior changes.
20- Acceptance tests use the `acceptance-*` targets in the root `Makefile`.
21- For one-off TestCafe checks, keep startup and cleanup in the repository root: `make storage/acceptance`, `make acceptance-sqlite-restart`, `make wait-2`, then `(cd frontend && npm run testcafe -- "chrome --headless=new --use-gl=angle --use-angle=swiftshader --disable-features=LocalNetworkAccessChecks" --config-file ./testcaferc.json --test-meta mode=public,type=short,testID=components-001 "tests/acceptance")`, then `make acceptance-sqlite-stop`.
22- If a command temporarily changes into `frontend/`, return to the repository root before running `make acceptance-sqlite-stop`.
23 
24## Templates, Session Bootstrap & Browser Baseline
25 
26- HTML entry points live under `assets/templates/`; the key files are `index.gohtml`, `app.gohtml`, `app.js.gohtml`, and `splash.gohtml`.
27- Browser checks live in `assets/static/js/browser-check.js` and must load before the main bundle from `app.js.gohtml`. Do not add `defer` or `async` unless you restore guarded loading.
28- OIDC completion is bridged through `assets/templates/auth.gohtml` and must stay aligned with `frontend/src/common/session.js`, `frontend/src/common/storage.js`, and `frontend/src/page/auth/login.vue`. Preserve the `session` storage preference across the callback so `sessionStorage` logins survive redirect.
29- When touching frontend session bootstrap, verify that `frontend/src/common/session.js` resolves `storageNamespace` from the real client config shape (`window.__CONFIG__` or `config.values`), not only from simplified mocks. Include a focused test that would fail if restore fell back to `pp:root:`.
30- The loader partial is reused in `pro/assets/templates/index.gohtml`, `plus/assets/templates/index.gohtml`, and `portal/assets/templates/index.gohtml`; whenever you change `app.js.gohtml` or bundle loading, verify those files still include the shared partial.
31- Splash styles live in `frontend/src/css/splash.css`; add new splash elements there so public and private editions stay aligned.
32- Browser baseline: the `browserslist` query in `frontend/package.json` is authoritative — `.babelrc` sets no explicit `targets`, so `@babel/preset-env` compiles to that set. Resolve it with `(cd frontend && npx browserslist)` rather than quoting fixed versions, which go stale as caniuse data updates. Update the message in `assets/templates/app.js.gohtml` and matching CSS if the support matrix changes.
33 
34## Translations
35 
36- Translation extraction source of truth is the root `make gettext-extract`, which runs `scripts/gettext-extract.sh` across `frontend/src` and any available `plus`, `pro`, or `portal` overlays.
37- Compatibility targets such as `make -C plus gettext-extract` delegate to the root target.
38- Avoid punctuation-only gettext keys such as `$gettext("—")`; they create noisy entries in `frontend/src/locales/translations.pot`.
39- Case conventions: tooltips, labels, buttons, placeholders, and short imperative phrases use **Title Case** (`Zoom In`, `Toggle Thumbnails`, `Add to Album`); running prose, full sentences, and notifications use **sentence case** (`Failed to save changes`). Lowercase only articles, short conjunctions, and ≤3-letter prepositions when not first. The forced-as-is Vuetify 3 UI messages in `frontend/src/locales.js` are adopted verbatim — exempt, and not a casing reference to copy. Full rules: `specs/frontend/translations.md` §"Case Conventions".
40 
41## Focus Management
42 
43- Dialogs must follow the shared focus pattern documented in `frontend/src/common/README.md`.
44- Always expose `ref="dialog"` on `<v-dialog>` overlays, call `$view.enter` and `$view.leave` in `@after-enter` and `@after-leave`, and avoid positive `tabindex` values.
45- Persistent dialogs must handle Escape via `@keydown.esc.exact` so Vuetify's rejection animation is suppressed; keep other shortcuts on `@keyup` so inner inputs can cancel them first.
46- Global shortcuts flow through `onShortCut(ev)` in `common/view.js`; it forwards only Escape and `ctrl` or `meta` combinations.
47- When a dialog opens nested menus such as combobox suggestion lists, verify they still cooperate with the global trap.
48 
49## Playwright MCP Usage
50 
51- Default endpoint is `http://localhost:2342/`; default login routes are `/library/login` for CE, Plus, and Pro, and `/portal/login` for Portal.
52- Use the local compose admin credentials; if login fails, inspect the active compose environment.
53- Desktop sessions default to `1280x900`; mobile sessions should use the mobile Playwright server with `375x667`.
54- Close the browser tab after scripted interactions.
55- Prefer waits over sleeps, click only visible and enabled elements, and use role, label, or text selectors instead of brittle XPath selectors.
56- Keep screenshots small and reproducible: prefer JPEG, visible viewport, deterministic `.local/screenshots/<case>/<step>__<viewport>.jpg` names, and no large inline screenshots.
57- If `npx` fetches an MCP server at runtime, add `--yes` or preinstall it to avoid prompts.
58 
59## Frontend Test Gotchas
60 
61- Hidden-route UI checks under `/library/hidden` or `/portal/hidden` require both `files.file_error` and `photos.photo_quality = -1`; `file_error` alone will not surface the row.
62