diff --git a/.dockerignore b/.dockerignore
index 5b1aea136..25672b03f 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -32,6 +32,5 @@ server/tests/
server/vitest.config.ts
**/*.test.ts
**/*.spec.ts
-wiki/
scripts/
charts/
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 67fc0f9fa..f2a420429 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -8,11 +8,11 @@ body:
attributes:
label: Pre-flight checklist
options:
- - label: I have searched [existing issues](https://github.com/mauriceboe/TREK/issues) and this bug has not been reported yet
+ - label: I have searched [existing issues](https://github.com/liketrek/TREK/issues) and this bug has not been reported yet
required: true
- label: I am running the latest available version of TREK
required: true
- - label: I have read the [Troubleshooting guide](https://github.com/mauriceboe/TREK/wiki/Troubleshooting) and my issue is not covered there
+ - label: I have read the [Troubleshooting guide](https://github.com/liketrek/TREK/wiki/Troubleshooting) and my issue is not covered there
required: true
- type: input
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index a1e0f7bb9..4ec777110 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,11 +1,11 @@
blank_issues_enabled: false
contact_links:
- name: Documentation
- url: https://github.com/mauriceboe/TREK/wiki
+ url: https://github.com/liketrek/TREK/wiki
about: Check the docs before opening an issue
- name: Feature Request
- url: https://github.com/mauriceboe/TREK/discussions/new?category=feature-requests
+ url: https://github.com/liketrek/TREK/discussions/new?category=feature-requests
about: Suggest a new feature or improvement in Discussions
- name: Questions & Help
- url: https://github.com/mauriceboe/TREK/discussions
+ url: https://github.com/liketrek/TREK/discussions
about: For questions and general help, use Discussions instead
\ No newline at end of file
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index be0f9d72e..bcb8250db 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -13,8 +13,8 @@
- [ ] Documentation update
## Checklist
-- [ ] I have read the [Contributing Guidelines](https://github.com/mauriceboe/TREK/wiki/Contributing)
-- [ ] My branch is [up to date with `dev`](https://github.com/mauriceboe/TREK/wiki/Development-environment#3-keep-your-fork-up-to-date)
+- [ ] I have read the [Contributing Guidelines](https://github.com/liketrek/TREK/wiki/Contributing)
+- [ ] My branch is [up to date with `dev`](https://github.com/liketrek/TREK/wiki/Development-environment#3-keep-your-fork-up-to-date)
- [ ] This PR targets the `dev` branch, not `main` *(wiki-only PRs are exempt)*
- [ ] I have tested my changes locally
- [ ] I have added/updated tests that prove my fix is effective or that my feature works
diff --git a/.github/workflows/close-stale-invalid-titles.yml b/.github/workflows/close-stale-invalid-titles.yml
index 9eb1ce338..93ea61037 100644
--- a/.github/workflows/close-stale-invalid-titles.yml
+++ b/.github/workflows/close-stale-invalid-titles.yml
@@ -9,7 +9,7 @@ permissions:
jobs:
close-stale:
- if: github.repository == 'mauriceboe/TREK'
+ if: github.repository == 'liketrek/TREK'
runs-on: ubuntu-latest
steps:
- name: Close stale invalid-title issues
diff --git a/.github/workflows/close-stale-wrong-branch.yml b/.github/workflows/close-stale-wrong-branch.yml
index c1a41a3cd..1859f7018 100644
--- a/.github/workflows/close-stale-wrong-branch.yml
+++ b/.github/workflows/close-stale-wrong-branch.yml
@@ -10,7 +10,7 @@ permissions:
jobs:
close-stale:
- if: github.repository == 'mauriceboe/TREK'
+ if: github.repository == 'liketrek/TREK'
runs-on: ubuntu-latest
steps:
- name: Close stale wrong-base-branch PRs
diff --git a/.github/workflows/close-untitled-issues.yml b/.github/workflows/close-untitled-issues.yml
index 0cd817682..f5ada9b6a 100644
--- a/.github/workflows/close-untitled-issues.yml
+++ b/.github/workflows/close-untitled-issues.yml
@@ -9,7 +9,7 @@ permissions:
jobs:
check-title:
- if: github.repository == 'mauriceboe/TREK'
+ if: github.repository == 'liketrek/TREK'
runs-on: ubuntu-latest
steps:
- name: Flag or redirect issue
@@ -77,7 +77,7 @@ jobs:
body: [
'## Wrong place for feature requests',
'',
- 'Feature requests should be submitted in [Discussions](https://github.com/mauriceboe/TREK/discussions/new?category=feature-requests), not as issues.',
+ 'Feature requests should be submitted in [Discussions](https://github.com/liketrek/TREK/discussions/new?category=feature-requests), not as issues.',
'',
'This issue has been closed. Feel free to re-submit your idea in the right place!',
].join('\n'),
diff --git a/.github/workflows/docker-dev.yml b/.github/workflows/docker-dev.yml
index d2e3ed070..9ea4b6bf2 100644
--- a/.github/workflows/docker-dev.yml
+++ b/.github/workflows/docker-dev.yml
@@ -18,7 +18,7 @@ concurrency:
jobs:
version-bump:
- if: github.repository == 'mauriceboe/TREK'
+ if: github.repository == 'liketrek/TREK'
runs-on: ubuntu-latest
outputs:
version: ${{ steps.bump.outputs.VERSION }}
@@ -98,7 +98,7 @@ jobs:
with:
context: .
platforms: ${{ matrix.platform }}
- outputs: type=image,name=mauriceboe/trek,push-by-digest=true,name-canonical=true,push=true
+ outputs: type=image,name=mauriceboe/TREK,push-by-digest=true,name-canonical=true,push=true
no-cache: true
build-args: |
APP_VERSION=${{ needs.version-bump.outputs.version }}
@@ -145,16 +145,16 @@ jobs:
working-directory: /tmp/digests
run: |
VERSION="${{ needs.version-bump.outputs.version }}"
- mapfile -t digests < <(printf 'mauriceboe/trek@sha256:%s\n' *)
+ mapfile -t digests < <(printf 'mauriceboe/TREK@sha256:%s\n' *)
MAJOR_TAG="$(echo "$VERSION" | cut -d. -f1)-pre"
docker buildx imagetools create \
- -t "mauriceboe/trek:latest-pre" \
- -t "mauriceboe/trek:$MAJOR_TAG" \
- -t "mauriceboe/trek:$VERSION" \
+ -t "mauriceboe/TREK:latest-pre" \
+ -t "mauriceboe/TREK:$MAJOR_TAG" \
+ -t "mauriceboe/TREK:$VERSION" \
"${digests[@]}"
- name: Inspect manifest
- run: docker buildx imagetools inspect mauriceboe/trek:latest-pre
+ run: docker buildx imagetools inspect mauriceboe/TREK:latest-pre
- name: Push git tag
run: |
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index bd31e32f3..5f9837396 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -1,17 +1,6 @@
name: Build & Push Docker Image
on:
- push:
- branches: [main]
- paths-ignore:
- - 'docs/**'
- - '**/*.md'
- - 'wiki/**'
- - '.github/workflows/**'
- - '.github/ISSUE_TEMPLATE/**'
- - '.github/FUNDING.yml'
- - '.github/PULL_REQUEST_TEMPLATE.md'
- - 'plugin-sdk/**'
workflow_dispatch:
inputs:
bump:
@@ -33,7 +22,7 @@ concurrency:
jobs:
version-bump:
- if: github.repository == 'mauriceboe/TREK'
+ if: github.repository == 'liketrek/TREK'
runs-on: ubuntu-latest
outputs:
version: ${{ steps.bump.outputs.VERSION }}
@@ -149,7 +138,7 @@ jobs:
with:
context: .
platforms: ${{ matrix.platform }}
- outputs: type=image,name=mauriceboe/trek,push-by-digest=true,name-canonical=true,push=true
+ outputs: type=image,name=mauriceboe/TREK,push-by-digest=true,name-canonical=true,push=true
no-cache: true
build-args: |
APP_VERSION=${{ needs.version-bump.outputs.version }}
@@ -194,16 +183,16 @@ jobs:
working-directory: /tmp/digests
run: |
VERSION="${{ needs.version-bump.outputs.version }}"
- mapfile -t digests < <(printf 'mauriceboe/trek@sha256:%s\n' *)
+ mapfile -t digests < <(printf 'mauriceboe/TREK@sha256:%s\n' *)
MAJOR_TAG="$(echo "$VERSION" | cut -d. -f1)"
docker buildx imagetools create \
- -t "mauriceboe/trek:latest" \
- -t "mauriceboe/trek:$MAJOR_TAG" \
- -t "mauriceboe/trek:$VERSION" \
+ -t "mauriceboe/TREK:latest" \
+ -t "mauriceboe/TREK:$MAJOR_TAG" \
+ -t "mauriceboe/TREK:$VERSION" \
"${digests[@]}"
- name: Inspect manifest
- run: docker buildx imagetools inspect mauriceboe/trek:latest
+ run: docker buildx imagetools inspect mauriceboe/TREK:latest
release-helm:
runs-on: ubuntu-latest
diff --git a/.github/workflows/enforce-target-branch.yml b/.github/workflows/enforce-target-branch.yml
index 54e3a0ecb..36f127d81 100644
--- a/.github/workflows/enforce-target-branch.yml
+++ b/.github/workflows/enforce-target-branch.yml
@@ -6,7 +6,7 @@ on:
jobs:
check-target:
- if: github.repository == 'mauriceboe/TREK'
+ if: github.repository == 'liketrek/TREK'
runs-on: ubuntu-latest
permissions:
pull-requests: write
diff --git a/.github/workflows/publish-plugin-sdk.yml b/.github/workflows/publish-plugin-sdk.yml
index 705771351..72ed168df 100644
--- a/.github/workflows/publish-plugin-sdk.yml
+++ b/.github/workflows/publish-plugin-sdk.yml
@@ -14,7 +14,7 @@ permissions:
jobs:
publish:
- if: github.repository == 'mauriceboe/TREK'
+ if: github.repository == 'liketrek/TREK'
runs-on: ubuntu-latest
defaults:
run:
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
index af22f82a0..5b2cfe08b 100644
--- a/.github/workflows/security.yml
+++ b/.github/workflows/security.yml
@@ -13,7 +13,7 @@ jobs:
scout:
# Docker Hub secrets are not exposed to pull requests from forks, so the
# Scout login can never succeed there.
- if: github.repository == 'mauriceboe/TREK' && github.event.pull_request.head.repo.fork != true
+ if: github.repository == 'liketrek/TREK' && github.event.pull_request.head.repo.fork != true
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
diff --git a/.github/workflows/wiki.yml b/.github/workflows/wiki.yml
index 8c6974520..e36ada88d 100644
--- a/.github/workflows/wiki.yml
+++ b/.github/workflows/wiki.yml
@@ -17,7 +17,7 @@ concurrency:
jobs:
deploy:
- if: github.repository == 'mauriceboe/TREK'
+ if: github.repository == 'liketrek/TREK'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
diff --git a/.gitignore b/.gitignore
index fef272b87..a83917a19 100644
--- a/.gitignore
+++ b/.gitignore
@@ -66,5 +66,3 @@ test-data
.run
.full-review
-# Wiki offline snapshot is baked in at build, not committed (duplicates wiki/)
-server/assets/wiki/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 73def1e0d..2c4cf649a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,7 +10,7 @@ Thanks for your interest in contributing! Please read these guidelines before op
4. **Target the `dev` branch** — All PRs must be opened against `dev`, not `main`. Exception: PRs that only modify files under `wiki/` may target any branch
5. **Match the existing style** — No reformatting, no linter config changes, no "while I'm here" cleanups
6. **Tests** — Your changes must include tests. The project maintains 80%+ coverage; PRs that drop it will be closed
-7. **Branch up to date** — Your branch must be [up to date with `dev`](https://github.com/mauriceboe/TREK/wiki/Development-environment#3-keep-your-fork-up-to-date) before submitting a PR
+7. **Branch up to date** — Your branch must be [up to date with `dev`](https://github.com/liketrek/TREK/wiki/Development-environment#3-keep-your-fork-up-to-date) before submitting a PR
## Pull Requests
@@ -39,8 +39,8 @@ feat(budget): add CSV export for expenses
## Development Environment
-See the [Developer Environment page](https://github.com/mauriceboe/TREK/wiki/Development-environment) for more information on setting up your development environment.
+See the [Developer Environment page](https://github.com/liketrek/TREK/wiki/Development-environment) for more information on setting up your development environment.
## More Details
-See the [Contributing wiki page](https://github.com/mauriceboe/TREK/wiki/Contributing) for the full tech stack, architecture overview, and detailed guidelines.
+See the [Contributing wiki page](https://github.com/liketrek/TREK/wiki/Contributing) for the full tech stack, architecture overview, and detailed guidelines.
diff --git a/Dockerfile b/Dockerfile
index c05da667a..ba5a9c4c0 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -71,6 +71,10 @@ COPY --from=server-builder /app/server/dist ./server/dist
# only emits dist, so these must be copied explicitly or the features silently
# degrade to empty in the image.
COPY --from=server-builder /app/server/assets ./server/assets
+# The in-app help pages (/help) read this straight from disk at runtime, so the
+# docs always match the version running. Without it, wikiService falls back to
+# fetching the GitHub wiki, which tracks main and needs network access.
+COPY wiki ./wiki
# tsconfig-paths/register reads this at runtime to resolve MCP SDK paths.
COPY server/tsconfig.json ./server/
# Encryption-key rotation is run on demand via tsx (a prod dep) straight from the
diff --git a/README.md b/README.md
index 92ac2e637..2f4fdcf8f 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ A self-hosted, real-time collaborative travel planner — with maps, budgets, pa
-
+
@@ -31,9 +31,9 @@ A self-hosted, real-time collaborative travel planner — with maps, budgets, pa
-
-
-
+
+
+
@@ -41,7 +41,7 @@ A self-hosted, real-time collaborative travel planner — with maps, budgets, pa
-
+
@@ -176,7 +176,7 @@ A self-hosted, real-time collaborative travel planner — with maps, budgets, pa
```bash
ENCRYPTION_KEY=$(openssl rand -hex 32) docker run -d -p 3000:3000 \
-e ENCRYPTION_KEY=$ENCRYPTION_KEY \
- -v ./data:/app/data -v ./uploads:/app/uploads mauriceboe/trek
+ -v ./data:/app/data -v ./uploads:/app/uploads mauriceboe/TREK
```
Open `http://localhost:3000`. On first boot TREK seeds an admin account — if you set `ADMIN_EMAIL`/`ADMIN_PASSWORD` those are used, otherwise the credentials are printed to the container log (`docker logs trek`).
@@ -217,7 +217,7 @@ Real-time sync via WebSocket (`ws`). Backend on NestJS 11. State with Zustand. A
```yaml
services:
app:
- image: mauriceboe/trek:latest
+ image: mauriceboe/TREK:latest
container_name: trek
read_only: true
security_opt:
@@ -280,7 +280,7 @@ helm repo update
helm install trek trek/trek
```
-See [`charts/README.md`](https://github.com/mauriceboe/TREK/blob/main/charts/README.md) for values.
+See [`charts/README.md`](https://github.com/liketrek/TREK/blob/main/charts/README.md) for values.
Install as App (PWA)
@@ -305,9 +305,9 @@ docker compose pull && docker compose up -d
**Docker run** — reuse the original volume paths:
```bash
-docker pull mauriceboe/trek
+docker pull mauriceboe/TREK
docker rm -f trek
-docker run -d --name trek -p 3000:3000 -v ./data:/app/data -v ./uploads:/app/uploads --restart unless-stopped mauriceboe/trek
+docker run -d --name trek -p 3000:3000 -v ./data:/app/data -v ./uploads:/app/uploads --restart unless-stopped mauriceboe/TREK
```
> Not sure which paths you used? `docker inspect trek --format '{{json .Mounts}}'` before removing the container.
@@ -331,6 +331,8 @@ The script creates a timestamped DB backup before making changes and prompts for
For production, put TREK behind a TLS-terminating reverse proxy. TREK uses WebSockets for real-time sync, so the proxy **must** support WebSocket upgrades on `/ws`.
+If you use the MCP addon, the proxy must also pass the `Mcp-Session-Id` header through in both directions on `/mcp` — Nginx and Caddy do this by default, but a proxy that strips it makes every tool call open a new session instead of reusing one. See the [Reverse Proxy wiki page](https://github.com/liketrek/TREK/wiki/Reverse-Proxy) for details.
+
Nginx
@@ -368,6 +370,19 @@ server {
proxy_set_header Host $host;
proxy_read_timeout 86400;
}
+
+ # Only needed if you use the MCP addon. Responses are Server-Sent Events,
+ # so buffering must be off or tool results arrive late.
+ location /mcp {
+ proxy_pass http://localhost:3000;
+ proxy_http_version 1.1;
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_buffering off;
+ proxy_read_timeout 3600s;
+ }
}
```
@@ -403,6 +418,7 @@ Caddy handles TLS and WebSockets automatically.
| `ENCRYPTION_KEY` | At-rest encryption key for stored secrets (API keys, MFA, SMTP, OIDC). Recommended: generate with `openssl rand -hex 32`. If unset, falls back to `data/.jwt_secret` (existing installs) or auto-generates a key (fresh installs). | Auto |
| `TZ` | Timezone for logs, reminders and cron jobs (e.g. `Europe/Berlin`) | `UTC` |
| `LOG_LEVEL` | `info` = concise user actions, `debug` = verbose details | `info` |
+| `TREK_WIKI_DIR` | Where the in-app Help pages (`/help`) read their content from. TREK ships its wiki and serves it from disk, so Help always matches the version you are running — you should not need to set this. Point it at your own directory to serve custom docs. If the path does not exist, Help falls back to fetching the public GitHub wiki (needs outbound network, and tracks the latest release). | bundled `wiki/` |
| `DEFAULT_LANGUAGE` | Default language on the login page for users with no saved preference. Browser/OS language is auto-detected first; this is the fallback. Supported: `de`, `en`, `es`, `fr`, `hu`, `nl`, `br`, `cs`, `pl`, `ru`, `zh`, `zh-TW`, `it`, `ar`, `id`, `tr`, `ja`, `ko`, `uk`, `gr` | `en` |
| `ALLOWED_ORIGINS` | Comma-separated origins for CORS and email links | same-origin |
| `FORCE_HTTPS` | Optional. When `true`: 301-redirects HTTP to HTTPS, sends HSTS, adds CSP `upgrade-insecure-requests`, forces the session cookie `secure` flag. Useful behind a TLS-terminating reverse proxy. Requires `TRUST_PROXY`. | `false` |
@@ -430,7 +446,7 @@ Caddy handles TLS and WebSockets automatically.
| `DEMO_MODE` | Enable demo mode (hourly data resets) | `false` |
| `UNSPLASH_ACCESS_KEY` | Optional Unsplash Access Key for trip-cover and place-image search. Without one, TREK uses Unsplash's unauthenticated endpoint, which some datacenter/VPS IPs are blocked from. Get a free key at [unsplash.com/developers](https://unsplash.com/developers). Overrides any per-admin key set in Admin > Settings (where it can also be configured instead). | — |
| `MCP_RATE_LIMIT` | Max MCP API requests per user per minute | `300` |
-| `MCP_MAX_SESSION_PER_USER` | Max concurrent MCP sessions per user | `20` |
+| `MCP_MAX_SESSION_PER_USER` | Max concurrent MCP sessions per user. At the cap, the least-recently-active session is closed to make room | `20` |
diff --git a/SECURITY.md b/SECURITY.md
index e2ce04147..59ba0a367 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -21,6 +21,6 @@ You will receive a response within 48 hours. Once confirmed, a fix will be relea
## Scope
-This policy covers the TREK application and its Docker image (`mauriceboe/trek`).
+This policy covers the TREK application and its Docker image (`mauriceboe/TREK`).
Third-party dependencies are monitored via GitHub Dependabot.
diff --git a/ca_profile.xml b/ca_profile.xml
index 1c129c1ed..e14a9270f 100644
--- a/ca_profile.xml
+++ b/ca_profile.xml
@@ -1,9 +1,9 @@
TREK is a self-hosted, real-time collaborative travel planner. Plan trips together with interactive maps, budgets, bookings, packing lists, day-by-day itineraries and file management — every change syncs instantly across everyone in your group. Includes OIDC/SSO, TOTP MFA, dark mode, PWA support, multi-language UI and a modular addon system (Vacay, Atlas, Collab, Budget, Packing, Journey). Maintained by mauriceboe — support and bug reports via GitHub Issues.
- https://raw.githubusercontent.com/mauriceboe/TREK/main/docs/trek-icon.png
- https://github.com/mauriceboe/TREK
- https://github.com/mauriceboe/TREK/issues
+ https://raw.githubusercontent.com/liketrek/TREK/main/docs/trek-icon.png
+ https://github.com/liketrek/TREK
+ https://github.com/liketrek/TREK/issueshttps://ko-fi.com/mauriceboeSupport TREK development
diff --git a/charts/trek/templates/configmap.yaml b/charts/trek/templates/configmap.yaml
index 5cecc9d86..d6d6e8c86 100644
--- a/charts/trek/templates/configmap.yaml
+++ b/charts/trek/templates/configmap.yaml
@@ -13,6 +13,9 @@ data:
{{- if .Values.env.LOG_LEVEL }}
LOG_LEVEL: {{ .Values.env.LOG_LEVEL | quote }}
{{- end }}
+ {{- if .Values.env.TREK_WIKI_DIR }}
+ TREK_WIKI_DIR: {{ .Values.env.TREK_WIKI_DIR | quote }}
+ {{- end }}
{{- if .Values.env.ALLOWED_ORIGINS }}
ALLOWED_ORIGINS: {{ .Values.env.ALLOWED_ORIGINS | quote }}
{{- end }}
diff --git a/charts/trek/values.yaml b/charts/trek/values.yaml
index 150e89851..0f50114f4 100644
--- a/charts/trek/values.yaml
+++ b/charts/trek/values.yaml
@@ -1,6 +1,6 @@
image:
- repository: mauriceboe/trek
+ repository: liketrek/TREK
# tag: latest
pullPolicy: IfNotPresent
@@ -24,6 +24,12 @@ env:
# Timezone for logs, reminders, and cron jobs (e.g. Europe/Berlin).
# LOG_LEVEL: "info"
# "info" = concise user actions, "debug" = verbose details.
+ # TREK_WIKI_DIR: "/app/wiki"
+ # Where the in-app Help pages (/help) read their content from. Leave unset: the
+ # image ships the wiki at /app/wiki and finds it automatically, so Help matches
+ # the version you are running. Only set this to serve your own docs from a mounted
+ # volume. If the path does not exist, Help falls back to fetching the public GitHub
+ # wiki, which needs egress and tracks the latest release rather than your version.
# DEFAULT_LANGUAGE: "en"
# Default language on the login page for users with no saved preference.
# Browser/OS language is auto-detected first; this is the fallback when no match is found.
diff --git a/client/e2e/create-trip.spec.ts b/client/e2e/create-trip.spec.ts
index 6c264c927..42a4e5720 100644
--- a/client/e2e/create-trip.spec.ts
+++ b/client/e2e/create-trip.spec.ts
@@ -1,4 +1,5 @@
import { test, expect } from '@playwright/test'
+import { dismissSystemNotices } from './helpers'
// Trip lifecycle (core): from the dashboard, open the new-trip modal, name the
// trip, submit, and confirm it shows up on the dashboard. Exercises the whole
@@ -7,18 +8,23 @@ import { test, expect } from '@playwright/test'
test('create a trip and see it on the dashboard', async ({ page }) => {
await page.goto('/dashboard')
+ // The release notice greets a freshly seeded user and its backdrop eats the click below.
+ await dismissSystemNotices(page)
+
// The "+ New Trip" card is always rendered in the default (planned) filter.
await page.locator('.add-trip-card').click()
- // Scope to the shared Modal (.modal-backdrop). Its form has no in-form submit
- // button (the primary action lives in the footer), so click it explicitly
- // rather than pressing Enter. The Create button is the slate primary button;
- // Cancel is the bordered one.
- const modal = page.locator('.modal-backdrop')
+ // Scope to the shared Modal (.trek-modal-backdrop — namespaced so content blockers
+ // don't hide a generic .modal-backdrop). Its form has no in-form submit button (the
+ // primary action lives in the footer), so click it explicitly rather than pressing
+ // Enter. The Create button is the slate primary button; Cancel is the bordered one.
+ const modal = page.locator('.trek-modal-backdrop')
await expect(modal).toBeVisible()
+ // Target Title by placeholder: the cover-image search inputs sit above it, so
+ // input[type=text].first() is the photo search box, not the field we want.
const title = `E2E Trip ${Date.now()}`
- await modal.locator('input[type="text"]').first().fill(title)
+ await modal.getByPlaceholder('e.g. Summer in Japan').fill(title)
await modal.getByRole('button', { name: 'Create New Trip' }).click()
await expect(page.getByText(title).first()).toBeVisible({ timeout: 15_000 })
diff --git a/client/e2e/helpers.ts b/client/e2e/helpers.ts
new file mode 100644
index 000000000..c91d48152
--- /dev/null
+++ b/client/e2e/helpers.ts
@@ -0,0 +1,22 @@
+import type { Page } from '@playwright/test'
+
+/**
+ * Dismiss the release-notice modal (SystemNoticeHost), which greets a freshly seeded
+ * user on first load and covers the dashboard — its backdrop swallows clicks aimed at
+ * anything underneath, `.add-trip-card` included.
+ *
+ * The X only appears on the notice's last page, so page through first. Dismissal is
+ * persisted server-side per user, but each spec gets a fresh DB, so every spec that
+ * touches the dashboard has to clear it.
+ */
+export async function dismissSystemNotices(page: Page): Promise {
+ const next = page.getByRole('button', { name: /next/i })
+ for (let i = 0; i < 6 && (await next.isVisible().catch(() => false)); i++) {
+ if (!(await next.isEnabled())) break
+ await next.click()
+ }
+
+ const dismiss = page.getByRole('button', { name: 'Dismiss' })
+ if (await dismiss.isVisible().catch(() => false)) await dismiss.click()
+ await dismiss.waitFor({ state: 'detached' }).catch(() => {})
+}
diff --git a/client/e2e/ipad-scroll-1432.spec.ts b/client/e2e/ipad-scroll-1432.spec.ts
new file mode 100644
index 000000000..55631b4ce
--- /dev/null
+++ b/client/e2e/ipad-scroll-1432.spec.ts
@@ -0,0 +1,79 @@
+import { test, expect, devices } from '@playwright/test'
+import { dismissSystemNotices } from './helpers'
+
+// Tablet regression guard for #1432 — the places list must scroll under a touch swipe.
+//
+// A tablet is a coarse-pointer device at a *desktop* viewport width, so the width-based
+// "is this mobile" check that 3.2.1 shipped left `draggable` armed on iPad: the swipe
+// became an HTML5 drag and raised the drop-to-import overlay instead of scrolling. Drag
+// is now gated on `(pointer: coarse)` (useIsTouch), and only a real device context proves
+// it — a jsdom unit test cannot express "coarse pointer at 834px".
+//
+// Needs WebKit (`npx playwright install webkit`, plus libmanette-0.2-0 and libwoff1 on
+// Debian/Ubuntu). WebKit is the right engine here, not a nicety: every browser on iPadOS
+// is WebKit underneath, which is why the reporter saw this in all three they tried.
+test.use({ ...devices['iPad Pro 11'] })
+
+test('#1432 iPad: places list is scrollable, not draggable', async ({ page }) => {
+ await page.goto('/dashboard')
+
+ await dismissSystemNotices(page)
+
+ await page.locator('.add-trip-card').click()
+ const createBtn = page.getByRole('button', { name: 'Create New Trip' })
+ await expect(createBtn).toBeVisible()
+ const title = `iPad 1432 ${Date.now()}`
+ await page.getByPlaceholder('e.g. Summer in Japan').fill(title)
+ await createBtn.click()
+
+ await page.getByText(title).first().click()
+ await expect(page).toHaveURL(/\/trips\/\d+/)
+ await expect(page.locator('.leaflet-container')).toBeVisible({ timeout: 20_000 })
+
+ const tripId = page.url().match(/\/trips\/(\d+)/)![1]
+
+ // Seed enough places for the list to overflow and actually need scrolling.
+ for (let i = 1; i <= 25; i++) {
+ const res = await page.request.post(`/api/trips/${tripId}/places`, {
+ data: { name: `Place ${i}`, lat: 48.85 + i * 0.01, lng: 2.35 + i * 0.01 },
+ })
+ expect(res.ok(), `seed place ${i}`).toBeTruthy()
+ }
+ await page.reload()
+ await expect(page.locator('.leaflet-container')).toBeVisible({ timeout: 20_000 })
+ await expect(page.getByText('Place 1').first()).toBeVisible({ timeout: 20_000 })
+
+ // The context must really be the one from the bug report: coarse pointer, desktop
+ // width. If either is wrong, everything below proves nothing.
+ const env = await page.evaluate(() => ({
+ coarse: window.matchMedia('(pointer: coarse)').matches,
+ width: window.innerWidth,
+ }))
+ expect(env.coarse, 'iPad reports a coarse primary pointer').toBe(true)
+ expect(env.width, 'iPad sits above the 768px "mobile" breakpoint').toBeGreaterThanOrEqual(768)
+
+ // 1. Rows must not be draggable — a draggable row is what swallowed the scroll gesture.
+ const row = page.locator('div[draggable]').filter({ hasText: 'Place 1' }).first()
+ await expect(row).toHaveAttribute('draggable', 'false')
+
+ // 2. The list must scroll, and no drop-to-import overlay may appear.
+ const scroller = page.locator('div[draggable]').first().locator('xpath=ancestor::div[@class="trek-stagger"]')
+ const before = await scroller.evaluate(el => el.scrollTop)
+ const box = (await scroller.boundingBox())!
+ await page.touchscreen.tap(box.x + box.width / 2, box.y + 40)
+ await scroller.evaluate(el => el.scrollBy(0, 200))
+ const after = await scroller.evaluate(el => el.scrollTop)
+ expect(after, 'places list scrolled').toBeGreaterThan(before)
+ await expect(page.getByText('Drop to import')).toHaveCount(0)
+
+ // 3. Drag being off means the arrow buttons are the only reorder affordance left —
+ // they must be visible (they were opacity:0 above 767px).
+ const arrowOpacity = await page.evaluate(() => {
+ const el = document.querySelector('.reorder-buttons')
+ return el ? getComputedStyle(el).opacity : 'absent'
+ })
+ expect(['1', 'absent']).toContain(arrowOpacity)
+
+ // 4. The iPad must still get the desktop two-pane layout — isMobile stayed width-based.
+ await expect(page.locator('.leaflet-container')).toBeVisible()
+})
diff --git a/client/e2e/reorder-arrows.spec.ts b/client/e2e/reorder-arrows.spec.ts
new file mode 100644
index 000000000..d0fca0c1a
--- /dev/null
+++ b/client/e2e/reorder-arrows.spec.ts
@@ -0,0 +1,61 @@
+import { test, expect } from '@playwright/test'
+import { dismissSystemNotices } from './helpers'
+
+// The day-plan reorder arrows are hover-revealed on desktop. The rule that did that was
+// dead for a long time — it targeted `.place-row .reorder-btns`, neither of which exists
+// (the component renders `.reorder-buttons` inside an unclassed row), so the buttons sat
+// at opacity:0 with no way to reveal them.
+//
+// That is not merely "invisible": opacity:0 still hit-tests, so every itinerary row and
+// note carried an invisible, fully clickable target that silently reordered the trip.
+// These cases pin both halves — hidden means non-interactive, hover means visible.
+test('desktop: reorder arrows are hidden-and-inert until the row is hovered', async ({ page }) => {
+ await page.goto('/dashboard')
+ await dismissSystemNotices(page)
+
+ await page.locator('.add-trip-card').click()
+ const modal = page.locator('.trek-modal-backdrop')
+ await expect(modal).toBeVisible()
+ const title = `Reorder ${Date.now()}`
+ await modal.getByPlaceholder('e.g. Summer in Japan').fill(title)
+ await modal.getByRole('button', { name: 'Create New Trip' }).click()
+
+ await page.getByText(title).first().click()
+ await expect(page).toHaveURL(/\/trips\/\d+/)
+ await expect(page.locator('.leaflet-container')).toBeVisible({ timeout: 20_000 })
+
+ // Two places on day 1, so the day plan renders rows carrying reorder arrows.
+ const tripId = page.url().match(/\/trips\/(\d+)/)![1]
+ const daysRes = await (await page.request.get(`/api/trips/${tripId}/days`)).json()
+ const dayId = (daysRes.days ?? daysRes)[0].id
+ for (const name of ['Alpha', 'Beta']) {
+ const res = await page.request.post(`/api/trips/${tripId}/places`, {
+ data: { name, lat: 48.85, lng: 2.35 },
+ })
+ const body = await res.json()
+ await page.request.post(`/api/trips/${tripId}/days/${dayId}/assignments`, {
+ data: { place_id: body.place?.id ?? body.id },
+ })
+ }
+ await page.reload()
+ await expect(page.locator('.leaflet-container')).toBeVisible({ timeout: 20_000 })
+
+ const row = page.locator('.dp-row').filter({ hasText: 'Alpha' }).first()
+ await expect(row).toBeVisible({ timeout: 20_000 })
+ const arrows = row.locator('.reorder-buttons')
+
+ // Unhovered: invisible AND inert — a click there must not land on the button.
+ const idle = await arrows.evaluate(el => {
+ const cs = getComputedStyle(el)
+ const r = el.getBoundingClientRect()
+ const hit = document.elementFromPoint(r.x + r.width / 2, r.y + r.height / 2)
+ return { opacity: cs.opacity, hitsArrow: !!hit?.closest('.reorder-buttons') }
+ })
+ expect(idle.opacity, 'arrows hidden until hover').toBe('0')
+ expect(idle.hitsArrow, 'hidden arrows must not swallow clicks').toBe(false)
+
+ // Hovered: revealed and clickable.
+ await row.hover()
+ await expect(arrows).toHaveCSS('opacity', '1')
+ await expect(arrows).toHaveCSS('pointer-events', 'auto')
+})
diff --git a/client/e2e/screenshots/auth.shot.ts b/client/e2e/screenshots/auth.shot.ts
new file mode 100644
index 000000000..528d017e3
--- /dev/null
+++ b/client/e2e/screenshots/auth.shot.ts
@@ -0,0 +1,26 @@
+import { test, expect } from './shot'
+
+/**
+ * Unauthenticated surfaces. `storageState: undefined` drops the admin session
+ * this project otherwise inherits, so these render as a logged-out visitor sees
+ * them — which is the entire point of the login and registration pages.
+ */
+test.use({ storageState: undefined })
+
+test('login page', async ({ page, shot }) => {
+ await page.goto('/login')
+ await expect(page.locator('input[type="email"]')).toBeVisible()
+ await shot.page_('Login')
+})
+
+test('registration page', async ({ page, shot }) => {
+ await page.goto('/register')
+ await page.waitForTimeout(500)
+ await shot.page_('Registration')
+})
+
+test('forgot password', async ({ page, shot }) => {
+ await page.goto('/forgot-password')
+ await page.waitForTimeout(500)
+ await shot.page_('PasswordReset')
+})
diff --git a/client/e2e/screenshots/collab.shot.ts b/client/e2e/screenshots/collab.shot.ts
new file mode 100644
index 000000000..7d30c685c
--- /dev/null
+++ b/client/e2e/screenshots/collab.shot.ts
@@ -0,0 +1,69 @@
+import { test, clearNotices, expect } from './shot'
+import type { Page, Locator } from '@playwright/test'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Collab surfaces, one capture each.
+ *
+ * Until now a single Collab.png illustrated four different wiki pages — chat,
+ * notes, polls and the What's Next widget — so at most one of them showed the
+ * feature its page described.
+ *
+ * The Collab view is NOT tabbed: CollabPanel renders chat in a fixed 380px left
+ * column and the other panels beside it, all visible at once (CollabPanel.tsx:94).
+ * So each capture targets its own card element rather than clicking a tab.
+ */
+
+const seed = JSON.parse(
+ readFileSync(path.join(process.cwd(), 'e2e', '.tmp', 'seed.json'), 'utf8'),
+) as { tripId: number }
+
+/**
+ * The panel card containing a given piece of seeded content — see cardClass in
+ * CollabPanel.tsx:20.
+ *
+ * Matching on content rather than the panel heading is deliberate: the headings
+ * render uppercase through CSS while the DOM text is "Notes" / "Polls", and
+ * those same words also appear in the mobile tab bar, so a heading match is both
+ * wrong-cased and ambiguous.
+ */
+function card(page: Page, contains: string): Locator {
+ return page
+ .locator('div.bg-surface-card.rounded-2xl')
+ .filter({ hasText: contains })
+ .last()
+}
+
+test.beforeEach(async ({ page }) => {
+ await page.goto(`/trips/${seed.tripId}`)
+ await clearNotices(page)
+ await page.getByRole('button', { name: 'Collab', exact: true }).first().click()
+ await page.waitForTimeout(1200)
+})
+
+test('collab chat', async ({ page, shot }) => {
+ // Seeded as three different people; a single-voice log would misrepresent it.
+ // The chat auto-scrolls to the newest message, so assert on the last line of
+ // the seeded conversation rather than the first — the first is off-screen.
+ await expect(page.getByText('kaiseki', { exact: false }).first()).toBeVisible()
+ await shot.element('CollabChat', card(page, 'kaiseki'))
+})
+
+test('collab notes', async ({ page, shot }) => {
+ await expect(page.getByText('Rail passes', { exact: false })).toBeVisible()
+ await shot.element('CollabNotes', card(page, 'Rail passes'))
+})
+
+test('collab polls', async ({ page, shot }) => {
+ await expect(page.getByText('free for Nara', { exact: false })).toBeVisible()
+ await shot.element('CollabPolls', card(page, 'free for Nara'))
+})
+
+test("what's next widget", async ({ page, shot }) => {
+ await shot.element('WhatsNext', card(page, "What's Next"))
+})
+
+test('collab overview', async ({ page, shot }) => {
+ await shot.page_('Collab')
+})
diff --git a/client/e2e/screenshots/detail.shot.ts b/client/e2e/screenshots/detail.shot.ts
new file mode 100644
index 000000000..fa09d7a26
--- /dev/null
+++ b/client/e2e/screenshots/detail.shot.ts
@@ -0,0 +1,88 @@
+import { test, clearNotices, expect } from './shot'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Detail pages and the surfaces that need a couple of clicks to reach.
+ *
+ * Each capture asserts something specific to the surface before shooting, so a
+ * navigation that quietly lands on a fallback (or an addon that is off) fails
+ * the run instead of producing a screenshot of the wrong screen.
+ */
+
+const seed = JSON.parse(
+ readFileSync(path.join(process.cwd(), 'e2e', '.tmp', 'seed.json'), 'utf8'),
+) as { tripId: number; collectionId?: number; journeyId?: number }
+
+test('collection detail', async ({ page, shot }) => {
+ test.skip(!seed.collectionId, 'collections addon unavailable during seed')
+ await page.goto(`/collections/${seed.collectionId}`)
+ await clearNotices(page)
+ await shot.page_('CollectionDetail')
+})
+
+test('journey detail', async ({ page, shot }) => {
+ test.skip(!seed.journeyId, 'journey addon unavailable during seed')
+ await page.goto(`/journey/${seed.journeyId}`)
+ await clearNotices(page)
+ await shot.page_('JourneyDetail')
+})
+
+test('mcp access — admin', async ({ page, shot }) => {
+ await page.goto('/admin')
+ await clearNotices(page)
+ await page.getByRole('button', { name: 'MCP Access', exact: true }).first().click()
+ await page.waitForTimeout(700)
+ await shot.page_('MCPAccess')
+})
+
+test('two-factor setup', async ({ page, shot }) => {
+ await page.goto('/settings')
+ await clearNotices(page)
+ await page.getByRole('button', { name: 'Account', exact: true }).first().click()
+ await page.waitForTimeout(600)
+ // The enrolment flow is behind a button whose label varies with state; match
+ // loosely and fall back to capturing the tab itself.
+ const enable = page.getByRole('button', { name: /two-factor|2fa|authenticator/i }).first()
+ if (await enable.isVisible().catch(() => false)) {
+ await enable.click()
+ await page.waitForTimeout(900)
+ }
+ await shot.page_('2FA')
+})
+
+/**
+ * Settle-up.
+ *
+ * WARNING for anyone extending this file: the "Settle up" button in the Costs
+ * toolbar is not a view — it RECORDS the settling transfers. An earlier version
+ * of this test clicked it, which zeroed every balance and left the capture
+ * showing "Everyone's square". Because all screenshot specs share one database
+ * and this file sorts before planner.shot.ts, it also poisoned Costs.png in the
+ * same run.
+ *
+ * Screenshot specs must not mutate state. Capture the "Add payment" dialog
+ * instead — same surface, no side effect — and close it again.
+ */
+test('costs — record a settle-up payment', async ({ page, shot }) => {
+ await page.goto(`/trips/${seed.tripId}`)
+ await clearNotices(page)
+ await page.getByRole('button', { name: 'Costs', exact: true }).first().click()
+ await page.waitForTimeout(800)
+
+ const addPayment = page.getByRole('button', { name: /add payment/i }).first()
+ test.skip(!(await addPayment.isVisible().catch(() => false)), 'no add-payment entry point rendered')
+ await addPayment.click()
+ await page.waitForTimeout(700)
+
+ const modal = page.locator('.trek-modal-backdrop > div').first()
+ await expect(modal).toBeVisible()
+ await shot.element('CostsSettleUp', modal)
+})
+
+test('trip files', async ({ page, shot }) => {
+ await page.goto(`/trips/${seed.tripId}/files`)
+ await clearNotices(page)
+ await expect(page).toHaveURL(/files/)
+ await shot.page_('Documents')
+})
diff --git a/client/e2e/screenshots/dialogs.shot.ts b/client/e2e/screenshots/dialogs.shot.ts
new file mode 100644
index 000000000..865bd9676
--- /dev/null
+++ b/client/e2e/screenshots/dialogs.shot.ts
@@ -0,0 +1,42 @@
+import { test, clearNotices, expect } from './shot'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Modals and dialogs.
+ *
+ * Captured as element screenshots (not full page) so the wiki gets the dialog
+ * itself rather than a dimmed backdrop with a small box in the middle. Each one
+ * asserts the dialog is actually open first — a missed click would otherwise
+ * silently produce a screenshot of the page behind it.
+ */
+
+const seed = JSON.parse(
+ readFileSync(path.join(process.cwd(), 'e2e', '.tmp', 'seed.json'), 'utf8'),
+) as { tripId: number }
+
+/**
+ * The shared Modal (client/src/components/shared/Modal.tsx) sets neither
+ * role="dialog" nor aria-modal, so there is no accessible role to query — the
+ * backdrop class is the only stable hook. Target its child, which is the panel
+ * itself, so the capture excludes the dimmed backdrop.
+ */
+function dialog(page: import('@playwright/test').Page) {
+ return page.locator('.trek-modal-backdrop > div').first()
+}
+
+test('create trip modal — with the new currency field', async ({ page, shot }) => {
+ await page.goto('/dashboard')
+ await clearNotices(page)
+ await page.getByRole('button', { name: /new trip/i }).first().click()
+ await expect(dialog(page)).toBeVisible()
+ await shot.element('TripCreate', dialog(page))
+})
+
+test('share dialog', async ({ page, shot }) => {
+ await page.goto(`/trips/${seed.tripId}`)
+ await clearNotices(page)
+ await page.getByRole('button', { name: /share/i }).first().click()
+ await expect(dialog(page)).toBeVisible()
+ await shot.element('Share', dialog(page))
+})
diff --git a/client/e2e/screenshots/pages.shot.ts b/client/e2e/screenshots/pages.shot.ts
new file mode 100644
index 000000000..52d096d05
--- /dev/null
+++ b/client/e2e/screenshots/pages.shot.ts
@@ -0,0 +1,67 @@
+import { test, clearNotices } from './shot'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Top-level navigable surfaces. One capture per route; anything that needs a
+ * dialog opened or a tab clicked lives in its own spec so a failure there
+ * cannot take these down with it.
+ *
+ * Names are the target filenames in wiki/assets/ — see docs/screenshot-map.md
+ * for which wiki page consumes which file.
+ */
+
+const seed = JSON.parse(
+ readFileSync(path.join(process.cwd(), 'e2e', '.tmp', 'seed.json'), 'utf8'),
+) as { tripId: number; collectionId?: number; journeyId?: number }
+
+test.beforeEach(async ({ page }) => {
+ await page.goto('/dashboard')
+ await clearNotices(page)
+})
+
+test('dashboard', async ({ page, shot }) => {
+ await page.goto('/dashboard')
+ await clearNotices(page)
+ await shot.page_('DashboardWidgets')
+})
+
+test('trip planner', async ({ page, shot }) => {
+ await page.goto(`/trips/${seed.tripId}`)
+ await shot.page_('TripPlanner')
+})
+
+test('atlas', async ({ page, shot }) => {
+ await page.goto('/atlas')
+ await shot.page_('Atlas')
+})
+
+test('vacay', async ({ page, shot }) => {
+ await page.goto('/vacay')
+ await shot.page_('Vacay')
+})
+
+test('collections', async ({ page, shot }) => {
+ await page.goto('/collections')
+ await shot.page_('Collections')
+})
+
+test('journey', async ({ page, shot }) => {
+ await page.goto('/journey')
+ await shot.page_('Journey')
+})
+
+test('notifications inbox', async ({ page, shot }) => {
+ await page.goto('/notifications')
+ await shot.page_('NotificationsInbox')
+})
+
+test('in-app help', async ({ page, shot }) => {
+ await page.goto('/help')
+ await shot.page_('HelpInApp')
+})
+
+test('files', async ({ page, shot }) => {
+ await page.goto(`/trips/${seed.tripId}/files`)
+ await shot.page_('Files')
+})
diff --git a/client/e2e/screenshots/planner.shot.ts b/client/e2e/screenshots/planner.shot.ts
new file mode 100644
index 000000000..b7507b4ab
--- /dev/null
+++ b/client/e2e/screenshots/planner.shot.ts
@@ -0,0 +1,47 @@
+import { test, clearNotices } from './shot'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Trip-planner tabs and dialogs.
+ *
+ * Tabs are reached by their visible label rather than a test id, deliberately:
+ * if a label is renamed (as Budget → Costs was in 3.3.0) this run fails loudly
+ * instead of silently capturing the wrong panel — which is exactly how the
+ * current wiki ended up with screenshots the text contradicts.
+ */
+
+const seed = JSON.parse(
+ readFileSync(path.join(process.cwd(), 'e2e', '.tmp', 'seed.json'), 'utf8'),
+) as { tripId: number }
+
+test.beforeEach(async ({ page }) => {
+ await page.goto(`/trips/${seed.tripId}`)
+ await clearNotices(page)
+})
+
+async function openTab(page: import('@playwright/test').Page, label: string) {
+ await page.getByRole('button', { name: label, exact: true }).first().click()
+ await page.waitForTimeout(700)
+}
+
+test('costs panel', async ({ page, shot }) => {
+ await openTab(page, 'Costs')
+ await shot.page_('Costs')
+})
+
+test('lists — packing', async ({ page, shot }) => {
+ await openTab(page, 'Lists')
+ await shot.page_('PackingList')
+})
+
+test('transports', async ({ page, shot }) => {
+ await openTab(page, 'Transports')
+ await shot.page_('Transports')
+})
+
+test('bookings', async ({ page, shot }) => {
+ await openTab(page, 'Book')
+ await shot.page_('Bookings')
+})
+
diff --git a/client/e2e/screenshots/promote.mjs b/client/e2e/screenshots/promote.mjs
new file mode 100644
index 000000000..d34b7c991
--- /dev/null
+++ b/client/e2e/screenshots/promote.mjs
@@ -0,0 +1,59 @@
+// Moves captured screenshots from the staging directory into wiki/assets/,
+// downscaling and re-encoding on the way.
+//
+// Captures are taken at 1440px CSS width with deviceScaleFactor 2, i.e. 2880px
+// of raw pixels. The wiki renders images at roughly 800–1000px, so shipping
+// 2880px costs ~10x the bytes for detail nobody sees — that is how the existing
+// assets reached 26 MB (one GIF alone is 9.1 MB). 1600px keeps the image sharp
+// on HiDPI displays at the size it is actually shown.
+//
+// Usage: node e2e/screenshots/promote.mjs [--dry]
+import sharp from 'sharp'
+import { readdirSync, mkdirSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+const SRC = path.join(process.cwd(), 'e2e', '.tmp', 'shots')
+const DEST = path.join(process.cwd(), '..', 'wiki', 'assets')
+const MAX_WIDTH = 1600
+const dry = process.argv.includes('--dry')
+
+mkdirSync(DEST, { recursive: true })
+
+const files = readdirSync(SRC).filter(f => f.endsWith('.png'))
+if (!files.length) {
+ console.error(`No screenshots in ${SRC} — run \`npm run shots\` first.`)
+ process.exit(1)
+}
+
+let before = 0
+let after = 0
+
+for (const file of files.sort()) {
+ const src = path.join(SRC, file)
+ const dest = path.join(DEST, file)
+ const srcBytes = statSync(src).size
+ before += srcBytes
+
+ const img = sharp(src)
+ const { width } = await img.metadata()
+
+ const pipeline = sharp(src)
+ .resize({ width: Math.min(width ?? MAX_WIDTH, MAX_WIDTH), withoutEnlargement: true })
+ .png({ compressionLevel: 9, effort: 10 })
+
+ const buf = await pipeline.toBuffer()
+ after += buf.length
+
+ const pct = Math.round((1 - buf.length / srcBytes) * 100)
+ console.log(
+ `${dry ? '[dry] ' : ''}${file.padEnd(28)} ${kb(srcBytes).padStart(8)} → ${kb(buf.length).padStart(8)} (-${pct}%)`,
+ )
+ if (!dry) await sharp(buf).toFile(dest)
+}
+
+console.log(`\n${files.length} files: ${kb(before)} → ${kb(after)} (-${Math.round((1 - after / before) * 100)}%)`)
+if (dry) console.log('Dry run — nothing written. Drop --dry to promote into wiki/assets/.')
+
+function kb(bytes) {
+ return bytes > 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${Math.round(bytes / 1024)} KB`
+}
diff --git a/client/e2e/screenshots/seed.setup.ts b/client/e2e/screenshots/seed.setup.ts
new file mode 100644
index 000000000..ef092ee54
--- /dev/null
+++ b/client/e2e/screenshots/seed.setup.ts
@@ -0,0 +1,37 @@
+import { test as setup, expect } from '@playwright/test'
+import { writeFileSync, mkdirSync } from 'node:fs'
+import path from 'node:path'
+import { seedDemoData } from './seed'
+
+/**
+ * Populates the throwaway E2E database with the demo trip before any screenshot
+ * runs. Its own Playwright project so it executes exactly once, after `setup`
+ * (which produces the authenticated storageState) and before `screenshots`.
+ *
+ * The resulting ids are written to disk because Playwright projects do not
+ * share memory — the capture specs read them back.
+ */
+setup('seed the demo trip', async ({ page, playwright }) => {
+ // page.request carries the storageState cookie, so this is authenticated as
+ // the admin. The factory hands the seeder throwaway contexts for the other
+ // members — see the comment in seed.ts on why they must not share one.
+ const result = await seedDemoData(page.request, token =>
+ playwright.request.newContext({
+ baseURL: 'http://localhost:5173',
+ // MUST be explicit: newContext otherwise picks up the project's
+ // storageState, i.e. the admin's trek_session cookie — and the server
+ // reads the cookie BEFORE the Authorization header
+ // (server/src/middleware/auth.ts:9), so every "member" write would be
+ // recorded as the admin while still returning 200.
+ storageState: undefined,
+ extraHTTPHeaders: token ? { Authorization: `Bearer ${token}` } : {},
+ }),
+ )
+
+ expect(result.tripId, 'trip was created').toBeTruthy()
+ expect(result.placeIds.length, 'places were created').toBeGreaterThan(0)
+
+ const dir = path.join(process.cwd(), 'e2e', '.tmp')
+ mkdirSync(dir, { recursive: true })
+ writeFileSync(path.join(dir, 'seed.json'), JSON.stringify(result, null, 2))
+})
diff --git a/client/e2e/screenshots/seed.ts b/client/e2e/screenshots/seed.ts
new file mode 100644
index 000000000..898b73193
--- /dev/null
+++ b/client/e2e/screenshots/seed.ts
@@ -0,0 +1,347 @@
+import path from 'node:path'
+import type { APIRequestContext } from '@playwright/test'
+
+/**
+ * Demo data for the documentation screenshots.
+ *
+ * Seeded over the REST API (not the DB) so it exercises the same paths a real
+ * user would and stays honest about validation. The session cookie comes from
+ * the storageState that auth.setup.ts writes, so `page.request` is already
+ * authenticated as the seeded admin.
+ *
+ * Design notes that matter for the screenshots:
+ * - The trip is in **JPY**, deliberately. A EUR trip hides the entire v3.4.0
+ * currency rework (per-trip currency, frozen FX rates, foreign-currency
+ * settle-up) — the reader would see nothing new.
+ * - Two extra members exist so splits, avatars and sharing tiers render with
+ * real names instead of a lonely single-user state.
+ * - Dates sit ~2 months out so "upcoming" surfaces (What's Next, reservations)
+ * have something to show.
+ */
+
+const TRIP = {
+ title: 'Autumn in Japan',
+ description: 'Two weeks chasing momiji season from Tokyo down to Kyoto.',
+ start_date: '2026-09-12',
+ end_date: '2026-09-21',
+ currency: 'JPY',
+ reminder_days: 3,
+}
+
+const MEMBERS = [
+ { username: 'mira', email: 'mira@example.com', password: 'DemoSeed12345!', role: 'user' },
+ { username: 'jonas', email: 'jonas@example.com', password: 'DemoSeed12345!', role: 'user' },
+]
+
+/** Real coordinates — the map surfaces are a big part of what we're capturing. */
+const PLACES = [
+ { name: 'Senso-ji Temple', lat: 35.7148, lng: 139.7967, address: '2-3-1 Asakusa, Taito City, Tokyo',
+ description: "Tokyo's oldest temple, approached through the Nakamise shopping street.",
+ notes: 'Go before 08:00 — the gate is empty and the light is better.',
+ duration_minutes: 90, price: 0, currency: 'JPY', day: 0 },
+ { name: 'teamLab Planets', lat: 35.6486, lng: 139.7900, address: '6-1-16 Toyosu, Koto City, Tokyo',
+ description: 'Immersive digital art museum you walk through barefoot.',
+ notes: 'Timed entry — book at least a week ahead.',
+ duration_minutes: 120, price: 3800, currency: 'JPY', day: 0 },
+ { name: 'Shibuya Crossing', lat: 35.6595, lng: 139.7005, address: 'Shibuya City, Tokyo',
+ description: 'The scramble. Best viewed from the Shibuya Sky observation deck.',
+ duration_minutes: 45, price: 0, currency: 'JPY', day: 1 },
+ { name: 'Meiji Jingu', lat: 35.6764, lng: 139.6993, address: '1-1 Yoyogikamizonocho, Shibuya City, Tokyo',
+ description: 'Forest shrine in the middle of the city.',
+ duration_minutes: 75, price: 0, currency: 'JPY', day: 1 },
+ { name: 'Fushimi Inari Taisha', lat: 34.9671, lng: 135.7727, address: '68 Fukakusa Yabunouchicho, Fushimi Ward, Kyoto',
+ description: 'Thousands of vermilion torii gates climbing Mount Inari.',
+ notes: 'The crowds thin out after the first 20 minutes of climbing.',
+ duration_minutes: 150, price: 0, currency: 'JPY', day: 4 },
+ { name: 'Arashiyama Bamboo Grove', lat: 35.0170, lng: 135.6716, address: 'Ukyo Ward, Kyoto',
+ description: 'Bamboo path leading to the Okochi Sanso villa gardens.',
+ duration_minutes: 60, price: 0, currency: 'JPY', day: 5 },
+ { name: 'Nishiki Market', lat: 35.0050, lng: 135.7649, address: 'Nakagyo Ward, Kyoto',
+ description: "Five covered blocks of food stalls — 'Kyoto's kitchen'.",
+ notes: 'Come hungry. Try the tamagoyaki.',
+ duration_minutes: 90, price: 2500, currency: 'JPY', day: 5 },
+]
+
+const EXPENSES = [
+ { name: 'Flights FRA → HND', category: 'transport', total_price: 890, currency: 'EUR',
+ expense_date: '2026-09-12', note: 'Booked with miles, taxes only.' },
+ { name: 'Ryokan in Hakone', category: 'accommodation', total_price: 48000, currency: 'JPY',
+ expense_date: '2026-09-15', note: '2 nights, kaiseki dinner included.' },
+ { name: 'JR Pass (14 days)', category: 'transport', total_price: 80000, currency: 'JPY',
+ expense_date: '2026-09-12', note: 'Green car, activated on arrival.' },
+ { name: 'teamLab Planets tickets', category: 'activities', total_price: 11400, currency: 'JPY',
+ expense_date: '2026-09-13' },
+ { name: 'Dinner at Nishiki', category: 'food', total_price: 7200, currency: 'JPY',
+ expense_date: '2026-09-17' },
+]
+
+const PACKING = [
+ { category: 'Documents', items: ['Passport', 'JR Pass voucher', 'Travel insurance'] },
+ { category: 'Clothing', items: ['Rain jacket', 'Walking shoes', 'Light layers'] },
+ { category: 'Electronics', items: ['Type-A adapter', 'Power bank', 'Camera'] },
+]
+
+const TODOS = [
+ { name: 'Book teamLab Planets slot', category: 'Before departure', due_date: '2026-08-15', priority: 2 },
+ { name: 'Activate JR Pass', category: 'On arrival', due_date: '2026-09-12', priority: 1 },
+ { name: 'Reserve ryokan dinner', category: 'Before departure', due_date: '2026-08-20' },
+]
+
+export interface SeedResult {
+ tripId: number
+ memberIds: number[]
+ dayIds: number[]
+ placeIds: number[]
+ collectionId?: number
+ journeyId?: number
+}
+
+/** Throws with the response body on failure — a silent 4xx here would produce
+ * a screenshot of an empty screen, which is worse than a loud crash. */
+async function call(api: APIRequestContext, method: 'post' | 'put' | 'get' | 'patch',
+ path: string, body?: unknown): Promise {
+ const res = await api[method](path, body === undefined ? {} : { data: body })
+ if (!res.ok()) {
+ throw new Error(`${method.toUpperCase()} ${path} → ${res.status()}\n${await res.text()}`)
+ }
+ return (await res.json()) as T
+}
+
+export type ContextFactory = (token?: string) => Promise
+
+export async function seedDemoData(
+ api: APIRequestContext,
+ newContext?: ContextFactory,
+): Promise {
+ // 1. Addons first — the Collections and Journey guards run ahead of auth, so
+ // every later call to those modules 403s until these are flipped.
+ for (const id of ['collections', 'journey', 'packing', 'budget', 'atlas', 'vacay', 'mcp', 'documents', 'collab']) {
+ await call(api, 'put', `/api/admin/addons/${id}`, { enabled: true })
+ }
+ await call(api, 'put', '/api/admin/bag-tracking', { enabled: true }).catch(() => {})
+
+ // 1b. Units, pinned explicitly so the screenshots don't silently change meaning
+ // when a default does. They match the current defaults (ba3733da made
+ // celsius/metric/24h consistent across the store and the settings UI) —
+ // stating them here keeps the captures reproducible either way.
+ await call(api, 'post', '/api/settings/bulk', {
+ settings: { temperature_unit: 'celsius', distance_unit: 'metric' },
+ })
+
+ // 2. Extra members. Ignore 409 so a re-run against a warm DB still works.
+ const memberIds: number[] = []
+ for (const m of MEMBERS) {
+ const res = await api.post('/api/admin/users', { data: m })
+ if (res.ok()) {
+ const { user } = (await res.json()) as { user: { id: number } }
+ memberIds.push(user.id)
+ } else if (res.status() !== 409) {
+ throw new Error(`create user ${m.username} → ${res.status()}\n${await res.text()}`)
+ }
+ }
+
+ // 3. The trip, in JPY.
+ const { trip } = await call<{ trip: { id: number } }>(api, 'post', '/api/trips', TRIP)
+ const tripId = trip.id
+
+ for (const m of MEMBERS) {
+ await call(api, 'post', `/api/trips/${tripId}/members`, { identifier: m.email }).catch(() => {})
+ }
+
+ // 4. Days are auto-generated by trip creation — read them back for assignment.
+ const days = await call | { days: Array<{ id: number }> }>(
+ api, 'get', `/api/trips/${tripId}/days`)
+ const dayIds = (Array.isArray(days) ? days : days.days).map(d => d.id)
+
+ // 5. Places, then pin each onto its day.
+ const placeIds: number[] = []
+ for (const p of PLACES) {
+ const { day, ...payload } = p
+ const { place } = await call<{ place: { id: number } }>(
+ api, 'post', `/api/trips/${tripId}/places`, payload)
+ placeIds.push(place.id)
+ const dayId = dayIds[day]
+ if (dayId) {
+ await call(api, 'post', `/api/trips/${tripId}/days/${dayId}/assignments`,
+ { place_id: place.id }).catch(() => {})
+ }
+ }
+
+ // 6. A day note, so the itinerary shows more than places.
+ if (dayIds[0]) {
+ await call(api, 'post', `/api/trips/${tripId}/days/${dayIds[0]}/notes`, {
+ text: 'Pick up the JR Pass at the airport counter before taking the train in.',
+ time: '08:15', icon: 'train',
+ }).catch(() => {})
+ }
+
+ // 7. Costs. Split across everyone so the settle-up view has real balances.
+ // NOTE: never send exchange_rate — the server freezes the FX rate itself,
+ // and a hand-supplied one fights the settlement maths.
+ const allMembers = [1, ...memberIds]
+ for (const e of EXPENSES) {
+ await call(api, 'post', `/api/trips/${tripId}/budget`, {
+ ...e,
+ payers: [{ user_id: 1, amount: e.total_price }],
+ member_ids: allMembers,
+ }).catch(() => {})
+ }
+
+ // A foreign-currency settle-up payment — the v3.4.0 feature worth showing.
+ if (memberIds[0]) {
+ await call(api, 'post', `/api/trips/${tripId}/budget/settlements`, {
+ from_user_id: memberIds[0], to_user_id: 1, amount: 120, currency: 'EUR',
+ }).catch(() => {})
+ }
+
+ // 8. Packing — category is free text on the item, there is no category resource.
+ for (const group of PACKING) {
+ for (const name of group.items) {
+ await call(api, 'post', `/api/trips/${tripId}/packing`, {
+ name, category: group.category, visibility: 'common',
+ }).catch(() => {})
+ }
+ }
+
+ for (const t of TODOS) {
+ await call(api, 'post', `/api/trips/${tripId}/todo`, t).catch(() => {})
+ }
+
+ // 9. A multi-leg flight. Coordinates are mandatory — endpoints without them
+ // are silently dropped by the server, leaving a booking with no route.
+ await call(api, 'post', `/api/trips/${tripId}/reservations`, {
+ title: 'LH716 FRA → HND',
+ type: 'flight',
+ reservation_time: '2026-09-12T13:05:00',
+ reservation_end_time: '2026-09-13T08:25:00',
+ confirmation_number: 'X7K2QP',
+ status: 'confirmed',
+ location: 'Frankfurt Airport',
+ metadata: { airline: 'Lufthansa', flight_number: 'LH716',
+ departure_airport: 'FRA', arrival_airport: 'HND' },
+ endpoints: [
+ { role: 'from', sequence: 0, name: 'Frankfurt Airport', code: 'FRA',
+ lat: 50.0379, lng: 8.5622, timezone: 'Europe/Berlin',
+ local_date: '2026-09-12', local_time: '13:05' },
+ { role: 'to', sequence: 1, name: 'Tokyo Haneda', code: 'HND',
+ lat: 35.5494, lng: 139.7798, timezone: 'Asia/Tokyo',
+ local_date: '2026-09-13', local_time: '08:25' },
+ ],
+ }).catch(() => {})
+
+ // 10. A collection, populated from the trip's own places.
+ let collectionId: number | undefined
+ try {
+ const created = await call<{ id: number } | { collection: { id: number } }>(
+ api, 'post', '/api/addons/collections',
+ { name: 'Kyoto shortlist', description: 'Places we want to reach on the second week.',
+ color: '#ef4444', icon: 'MapPin' })
+ collectionId = 'id' in created ? created.id : created.collection.id
+ for (const placeId of placeIds.slice(4)) {
+ await call(api, 'post', '/api/addons/collections/places/from-trip', {
+ collection_id: collectionId, source_trip_id: tripId, source_place_id: placeId, force: true,
+ }).catch(() => {})
+ }
+ } catch { /* collections addon unavailable — screenshots for it will be skipped */ }
+
+ // 11. Journey. Entries are generated server-side from the trip, then filled in.
+ let journeyId: number | undefined
+ try {
+ const j = await call<{ id: number } | { journey: { id: number } }>(
+ api, 'post', '/api/journeys',
+ { title: 'Autumn in Japan', subtitle: 'Momiji season, Tokyo to Kyoto', trip_ids: [tripId] })
+ journeyId = 'id' in j ? j.id : j.journey.id
+ } catch { /* journey addon unavailable */ }
+
+ // 11b. Collab: chat, notes and polls.
+ //
+ // Chat is only convincing with more than one voice, and every collab
+ // write is attributed to the acting user — so messages and votes are
+ // posted as the members themselves, via their own bearer tokens, not as
+ // the admin. A single-speaker chat log would misrepresent the feature.
+ // Each member gets its OWN request context. Logging in through the shared
+ // one would set the trek_session cookie on it, and extractToken()
+ // (server/src/middleware/auth.ts:9) reads the cookie BEFORE the
+ // Authorization header — so every later write, including the admin's,
+ // would silently be attributed to whoever logged in last.
+ const members: Record = {}
+ for (const m of MEMBERS) {
+ if (!newContext) break
+ const anon = await newContext()
+ const res = await anon.post('/api/auth/login', { data: { email: m.email, password: m.password } })
+ if (!res.ok()) { await anon.dispose(); continue }
+ const { token } = (await res.json()) as { token?: string }
+ await anon.dispose()
+ if (token) members[m.username] = await newContext(token)
+ }
+ /** The member's own context, or the admin's as a visible fallback. */
+ const as = (username: string): APIRequestContext => members[username] ?? api
+
+ const collab = `/api/trips/${tripId}/collab`
+
+ for (const n of [
+ { title: 'Rail passes', category: 'Transport', color: '#3b82f6',
+ content: 'The 14-day JR Pass covers the Tokyo–Kyoto legs. Activate it at the airport counter on arrival, not before.' },
+ { title: 'Ryokan etiquette', category: 'Accommodation', color: '#ef4444',
+ content: 'Shoes off at the entrance, yukata for dinner. Dinner is served at 18:30 sharp — being late is genuinely rude.' },
+ { title: 'Rainy-day alternatives', category: 'Ideas', color: '#22c55e',
+ content: 'teamLab Planets, the Kyoto Railway Museum and Nishiki Market all work in bad weather.' },
+ ]) {
+ await api.post(`${collab}/notes`, { data: n }).catch(() => {})
+ }
+
+ const pollRes = await api.post(`${collab}/polls`, {
+ data: {
+ question: 'Which day should we keep free for Nara?',
+ options: ['Wed, Sep 16', 'Thu, Sep 17', 'Sat, Sep 19'],
+ multiple: false,
+ },
+ })
+ if (pollRes.ok()) {
+ const { poll } = (await pollRes.json()) as { poll: { id: number | string } }
+ await api.post(`${collab}/polls/${poll.id}/vote`, { data: { option_index: 1 } }).catch(() => {})
+ await as('mira').post(`${collab}/polls/${poll.id}/vote`, { data: { option_index: 1 } }).catch(() => {})
+ await as('jonas').post(`${collab}/polls/${poll.id}/vote`, { data: { option_index: 2 } }).catch(() => {})
+ }
+ await api.post(`${collab}/polls`, {
+ data: { question: 'Ryokan or city hotel in Hakone?', options: ['Ryokan with onsen', 'City hotel'], multiple: false },
+ }).catch(() => {})
+
+ const conversation: Array<[string, string]> = [
+ ['admin', 'Flights are booked — we land at Haneda 08:25 on the 13th.'],
+ ['mira', 'Nice. Should we go straight to the hotel or drop bags and head out?'],
+ ['jonas', 'Drop bags. I want to be at Senso-ji before the crowds.'],
+ ['admin', "Agreed. I've put it on day 1 with a note to go before 08:00."],
+ ['mira', 'Booked the teamLab slot for the 13th, 14:00. Tickets are in the Files tab.'],
+ ['jonas', 'Do we need to reserve the ryokan dinner separately?'],
+ ['admin', "It's included — kaiseki, 18:30. Added it to the to-dos so we don't forget to confirm."],
+ ]
+ for (const [who, text] of conversation) {
+ const ctx = who === 'admin' ? api : as(who)
+ await ctx.post(`${collab}/messages`, { data: { text } }).catch(() => {})
+ }
+
+ for (const ctx of Object.values(members)) await ctx.dispose()
+
+ // 12. Plugins, installed from the community registry.
+ //
+ // Registry install is the ONLY path that produces a representative
+ // screenshot. Dev-link and sideload both stamp the plugin card with a
+ // badge ("Dev-Link" / "Sideloaded", AdminPluginsPanel.tsx:307,361) that no
+ // ordinary install shows, and TREK_PLUGINS_DEV_LINK additionally reveals a
+ // "Link a local plugin" row in the panel. Documenting either would show
+ // readers a UI they will never have.
+ //
+ // Needs network. If the registry is unreachable the plugin screenshots are
+ // skipped loudly rather than silently captured in a misleading state.
+ for (const id of ['koffi', 'trip-doctor']) {
+ const res = await api.post('/api/admin/plugins/install', { data: { id } })
+ if (!res.ok()) {
+ console.log(`PLUGIN INSTALL FAILED ${id} → ${res.status()} ${await res.text()}`)
+ continue
+ }
+ await api.post(`/api/admin/plugins/${id}/activate`, { data: {} })
+ }
+
+ return { tripId, memberIds, dayIds, placeIds, collectionId, journeyId }
+}
diff --git a/client/e2e/screenshots/settings.shot.ts b/client/e2e/screenshots/settings.shot.ts
new file mode 100644
index 000000000..59faf3b54
--- /dev/null
+++ b/client/e2e/screenshots/settings.shot.ts
@@ -0,0 +1,105 @@
+import { test, clearNotices } from './shot'
+import type { Page } from '@playwright/test'
+
+/**
+ * Settings and Admin tabs.
+ *
+ * Both pages use the shared PageSidebar with client-side tab state (no URL
+ * segment per tab), so each capture clicks its way in. Labels come from
+ * shared/src/i18n/en — note "General" is the tab the wiki still calls
+ * "Display", which is one of the corrections this screenshot run supports.
+ */
+
+async function openSidebarTab(page: Page, label: string) {
+ await page.getByRole('button', { name: label, exact: true }).first().click()
+ await page.waitForTimeout(600)
+}
+
+test.describe('user settings', () => {
+ test.beforeEach(async ({ page }) => {
+ await page.goto('/settings')
+ await clearNotices(page)
+ })
+
+ // Filename kept as UsrSettings.png — the wiki already references it.
+ test('general tab', async ({ page, shot }) => {
+ await openSidebarTab(page, 'General')
+ await shot.page_('UsrSettings')
+ })
+
+ test('appearance tab', async ({ page, shot }) => {
+ await openSidebarTab(page, 'Appearance')
+ await shot.page_('UsrSettingsAppearance')
+ })
+
+ test('map tab', async ({ page, shot }) => {
+ await openSidebarTab(page, 'Map')
+ await shot.page_('UsrSettingsMap')
+ })
+
+ test('notifications tab', async ({ page, shot }) => {
+ await openSidebarTab(page, 'Notifications')
+ await shot.page_('NotifSettings')
+ })
+
+ test('offline tab', async ({ page, shot }) => {
+ await openSidebarTab(page, 'Offline')
+ await shot.page_('SettingsOffline')
+ })
+
+ test('account tab', async ({ page, shot }) => {
+ await openSidebarTab(page, 'Account')
+ await shot.page_('SettingsAccount')
+ })
+})
+
+test.describe('admin panel', () => {
+ test.beforeEach(async ({ page }) => {
+ await page.goto('/admin')
+ await clearNotices(page)
+ })
+
+ test('users', async ({ page, shot }) => {
+ await openSidebarTab(page, 'Users')
+ await shot.page_('UsersAndInvites')
+ })
+
+ test('user defaults', async ({ page, shot }) => {
+ await openSidebarTab(page, 'User Defaults')
+ await shot.page_('AdminUserDefaults')
+ })
+
+ test('personalization', async ({ page, shot }) => {
+ await openSidebarTab(page, 'Personalization')
+ await shot.page_('CategoryManager')
+ })
+
+ test('addons', async ({ page, shot }) => {
+ await openSidebarTab(page, 'Addons')
+ await shot.page_('Addons-Overview')
+ })
+
+ test('plugins', async ({ page, shot }) => {
+ await openSidebarTab(page, 'Plugins')
+ await shot.page_('AdminPlugins')
+ })
+
+ test('github releases', async ({ page, shot }) => {
+ await openSidebarTab(page, 'GitHub')
+ await shot.page_('GithubReleases')
+ })
+
+ test('backup', async ({ page, shot }) => {
+ await openSidebarTab(page, 'Backup')
+ await shot.page_('Backup')
+ })
+
+ test('audit log', async ({ page, shot }) => {
+ await openSidebarTab(page, 'Audit')
+ await shot.page_('Audit')
+ })
+
+ test('admin panel overview', async ({ page, shot }) => {
+ await shot.page_('AdminPanel')
+ })
+})
diff --git a/client/e2e/screenshots/shot.ts b/client/e2e/screenshots/shot.ts
new file mode 100644
index 000000000..1b6040986
--- /dev/null
+++ b/client/e2e/screenshots/shot.ts
@@ -0,0 +1,119 @@
+import { test as base, expect, type Page, type Locator } from '@playwright/test'
+import { mkdirSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Shared plumbing for the documentation screenshot run (`npm run shots`).
+ *
+ * These are not assertions about behaviour — they drive the app to a known
+ * state and capture it for the wiki. They live behind their own Playwright
+ * project (`screenshots`, testMatch /\.shot\.ts/) so a normal `npm run e2e`
+ * never pays for them.
+ *
+ * Output goes to a staging directory, NOT straight into wiki/assets/, so a
+ * bad run can never clobber good artwork. Promote with `npm run shots:promote`.
+ */
+
+// Playwright runs from the client workspace root, matching how
+// playwright.config.ts spells `storageState: 'e2e/.tmp/state.json'`.
+export const OUT_DIR = path.join(process.cwd(), 'e2e', '.tmp', 'shots')
+
+/** Desktop capture size. 2x scale keeps text crisp; images are squeezed on promote. */
+export const VIEWPORT = { width: 1440, height: 900 }
+
+export const test = base.extend<{ shot: Shot }>({
+ // Overriding `page` (rather than doing this inside the `shot` fixture) is
+ // deliberate: fixtures initialise lazily, so a route registered in `shot`
+ // lands AFTER any beforeEach hook has already navigated — too late to
+ // intercept the config request.
+ page: async ({ page }, use) => {
+ await page.setViewportSize(VIEWPORT)
+ await hideDevOnlyUi(page)
+ await use(page)
+ },
+ shot: async ({ page }, use) => {
+ mkdirSync(OUT_DIR, { recursive: true })
+ await use(new Shot(page))
+ },
+})
+
+/**
+ * The E2E backend runs with NODE_ENV=development, so /auth/app-config reports
+ * `dev_mode: true` (authService.ts) and the admin sidebar grows a
+ * "Dev: Notifications" tab that no real deployment ever shows.
+ *
+ * Rewriting the response is the surgical fix. Flipping the server to
+ * NODE_ENV=production would also enable HSTS (globalMiddleware.ts), and an
+ * HSTS header on localhost would upgrade the run to https and break it.
+ */
+async function hideDevOnlyUi(page: Page): Promise {
+ await page.route('**/api/auth/app-config', async route => {
+ const res = await route.fetch()
+ const body = await res.json()
+ await route.fulfill({ response: res, json: { ...body, dev_mode: false } })
+ })
+}
+
+export { expect }
+
+export class Shot {
+ constructor(private readonly page: Page) {}
+
+ /**
+ * Capture the full viewport. `name` is the target filename in wiki/assets/
+ * (without extension) so the mapping from screenshot to doc page is literal.
+ */
+ async page_(name: string): Promise {
+ await this.settle()
+ await this.page.screenshot({ path: path.join(OUT_DIR, `${name}.png`) })
+ }
+
+ /** Capture one element — preferred for dialogs, panels and cards. */
+ async element(name: string, target: Locator): Promise {
+ await this.settle()
+ await expect(target).toBeVisible()
+ await target.screenshot({ path: path.join(OUT_DIR, `${name}.png`) })
+ }
+
+ /**
+ * Quiet the page before capturing: fonts loaded, images decoded, animations
+ * finished, no pending network. Without this, screenshots catch skeleton
+ * loaders and half-faded modals, which is exactly how the current wiki
+ * assets ended up inconsistent.
+ */
+ private async settle(): Promise {
+ // Bounded: TREK holds a WebSocket open at /ws, so the network never goes
+ // fully idle and an unbounded wait would burn the whole test timeout.
+ await this.page.waitForLoadState('networkidle', { timeout: 5_000 }).catch(() => {})
+ // Await, but return nothing — the resolved FontFaceSet is not serialisable.
+ await this.page.evaluate(async () => { await document.fonts.ready })
+ await this.page.evaluate(async () => {
+ await Promise.all(
+ Array.from(document.images)
+ .filter(img => !img.complete)
+ .map(img => new Promise(res => { img.onload = img.onerror = res })),
+ )
+ })
+ // Let CSS transitions land (modal fade-in, sidebar slide).
+ await this.page.waitForTimeout(400)
+ }
+}
+
+/**
+ * Dismiss the first-run system notice. Copied in spirit from e2e/helpers.ts,
+ * but tolerant: on a seeded DB the notice may already be cleared.
+ */
+export async function clearNotices(page: Page): Promise {
+ const next = page.getByRole('button', { name: /next/i })
+ for (let i = 0; i < 6 && (await next.isVisible().catch(() => false)); i++) {
+ if (!(await next.isEnabled().catch(() => false))) break
+ await next.click().catch(() => {})
+ }
+ for (const label of ['Dismiss', 'OK']) {
+ const btn = page.getByRole('button', { name: label, exact: true })
+ for (let i = 0; i < 4 && (await btn.isVisible().catch(() => false)); i++) {
+ await btn.click().catch(() => {})
+ await page.waitForTimeout(300)
+ }
+ }
+}
diff --git a/client/e2e/trip-planner.spec.ts b/client/e2e/trip-planner.spec.ts
index 9a4b8b2ce..754145ca3 100644
--- a/client/e2e/trip-planner.spec.ts
+++ b/client/e2e/trip-planner.spec.ts
@@ -1,4 +1,5 @@
import { test, expect } from '@playwright/test'
+import { dismissSystemNotices } from './helpers'
// Open a trip into the planner: create a trip, open it from the dashboard, and
// confirm the trip planner (TripPlannerPage — the app's largest page) actually
@@ -6,12 +7,17 @@ import { test, expect } from '@playwright/test'
test('open a trip and land in the planner with a map', async ({ page }) => {
await page.goto('/dashboard')
+ // The release notice greets a freshly seeded user and its backdrop eats the click below.
+ await dismissSystemNotices(page)
+
// Create a trip to open.
await page.locator('.add-trip-card').click()
- const modal = page.locator('.modal-backdrop')
+ const modal = page.locator('.trek-modal-backdrop')
await expect(modal).toBeVisible()
+ // Target Title by placeholder: the cover-image search inputs sit above it, so
+ // input[type=text].first() is the photo search box, not the field we want.
const title = `E2E Planner ${Date.now()}`
- await modal.locator('input[type="text"]').first().fill(title)
+ await modal.getByPlaceholder('e.g. Summer in Japan').fill(title)
await modal.getByRole('button', { name: 'Create New Trip' }).click()
// Open it from the dashboard.
diff --git a/client/package.json b/client/package.json
index fc565ff80..12140bf69 100644
--- a/client/package.json
+++ b/client/package.json
@@ -20,6 +20,8 @@
"theme:lint": "node scripts/theme-lint.mjs",
"theme:lint:strict": "node scripts/theme-lint.mjs --strict",
"e2e": "playwright test",
+ "shots": "playwright test --project=screenshots",
+ "shots:promote": "node e2e/screenshots/promote.mjs",
"e2e:report": "playwright show-report",
"format": "prettier --write \"src/**/*.tsx\" \"src/**/*.css\"",
"format:check": "prettier --check \"src/**/*.tsx\" \"src/**/*.css\""
diff --git a/client/playwright.config.ts b/client/playwright.config.ts
index e6868a43c..f2c71453e 100644
--- a/client/playwright.config.ts
+++ b/client/playwright.config.ts
@@ -35,6 +35,28 @@ export default defineConfig({
use: { ...devices['Desktop Chrome'], storageState: 'e2e/.tmp/state.json' },
dependencies: ['setup'],
},
+ // Documentation screenshots (`npm run shots`). Excluded from the normal e2e
+ // run by its own testMatch — these capture artwork for wiki/assets/, they
+ // assert nothing. 2x scale keeps text crisp at the sizes the wiki renders.
+ // Populates the demo trip the screenshots are taken of. Separate project so
+ // it runs exactly once, between auth and capture.
+ {
+ name: 'seed',
+ testMatch: /seed\.setup\.ts/,
+ use: { ...devices['Desktop Chrome'], storageState: 'e2e/.tmp/state.json' },
+ dependencies: ['setup'],
+ },
+ {
+ name: 'screenshots',
+ testMatch: /\.shot\.ts/,
+ use: {
+ ...devices['Desktop Chrome'],
+ storageState: 'e2e/.tmp/state.json',
+ viewport: { width: 1440, height: 900 },
+ deviceScaleFactor: 2,
+ },
+ dependencies: ['seed'],
+ },
],
webServer: [
{
diff --git a/client/src/api/client.ts b/client/src/api/client.ts
index b3f05d041..d2f716143 100644
--- a/client/src/api/client.ts
+++ b/client/src/api/client.ts
@@ -31,7 +31,7 @@ import {
type PlaceBulkUpdateRequest,
type DayNoteCreateRequest, type DayNoteUpdateRequest,
type PackingImportRequest, type PackingBagMembersRequest, type PackingUpdateBagRequest,
- type PackingCategoryAssigneesRequest,
+ type PackingCategoryAssigneesRequest, type PackingApplyTemplateRequest,
type BudgetUpdateMembersRequest, type BudgetToggleMemberPaidRequest, type BudgetReorderCategoriesRequest,
type TodoCategoryAssigneesRequest,
type CollabNoteCreateRequest, type CollabNoteUpdateRequest, type CollabPollCreateRequest,
@@ -449,7 +449,7 @@ export const packingApi = {
getCategoryAssignees: (tripId: number | string) => apiClient.get(`/trips/${tripId}/packing/category-assignees`).then(r => r.data),
setCategoryAssignees: (tripId: number | string, categoryName: string, userIds: number[]) => apiClient.put(`/trips/${tripId}/packing/category-assignees/${encodeURIComponent(categoryName)}`, { user_ids: userIds } satisfies PackingCategoryAssigneesRequest).then(r => r.data),
listTemplates: (tripId: number | string) => apiClient.get(`/trips/${tripId}/packing/templates`).then(r => r.data),
- applyTemplate: (tripId: number | string, templateId: number) => apiClient.post(`/trips/${tripId}/packing/apply-template/${templateId}`).then(r => r.data),
+ applyTemplate: (tripId: number | string, templateId: number, visibility: 'common' | 'personal' = 'common') => apiClient.post(`/trips/${tripId}/packing/apply-template/${templateId}`, { visibility } satisfies PackingApplyTemplateRequest).then(r => r.data),
saveAsTemplate: (tripId: number | string, name: string) => apiClient.post(`/trips/${tripId}/packing/save-as-template`, { name }).then(r => r.data),
setBagMembers: (tripId: number | string, bagId: number, userIds: number[]) => apiClient.put(`/trips/${tripId}/packing/bags/${bagId}/members`, { user_ids: userIds } satisfies PackingBagMembersRequest).then(r => r.data),
listBags: (tripId: number | string) => apiClient.get(`/trips/${tripId}/packing/bags`).then(r => r.data),
@@ -502,6 +502,11 @@ export const adminApi = {
pluginActivate: (id: string, consent?: boolean) => apiClient.post(`/admin/plugins/${id}/activate`, consent ? { consent: true } : {}).then(r => r.data),
pluginDeactivate: (id: string) => apiClient.post(`/admin/plugins/${id}/deactivate`).then(r => r.data),
pluginUpdate: (id: string) => apiClient.post(`/admin/plugins/${id}/update`).then(r => r.data),
+ // Re-trust a ROTATED author signing key and update, in ONE call. `publicKey` is the
+ // full key the admin was shown (not a fingerprint): the server compares it exactly, so
+ // it can refuse if the registry entry was re-keyed again since the dialog rendered.
+ pluginRetrust: (id: string, version: string, publicKey: string) =>
+ apiClient.post(`/admin/plugins/${id}/retrust`, { version, publicKey }).then(r => r.data),
pluginUninstall: (id: string, deleteData: boolean) => apiClient.post(`/admin/plugins/${id}/uninstall`, { deleteData }).then(r => r.data),
pluginRescan: () => apiClient.post('/admin/plugins/rescan').then(r => r.data),
pluginUpload: (file: File) => { const fd = new FormData(); fd.append('file', file); return postMultipart('/admin/plugins/upload', fd) },
@@ -739,8 +744,8 @@ export const airtrailApi = {
sync: (): Promise<{ changed: number }> => apiClient.post('/integrations/airtrail/sync').then(r => r.data),
// flights + import are added with the trip-planner import (P2)
flights: () => apiClient.get('/integrations/airtrail/flights').then(r => r.data),
- import: (tripId: number, flightIds: string[]) =>
- apiClient.post(`/trips/${tripId}/reservations/import/airtrail`, { flightIds }).then(r => r.data),
+ import: (tripId: number, flightIds: string[], connections?: string[][]) =>
+ apiClient.post(`/trips/${tripId}/reservations/import/airtrail`, connections?.length ? { flightIds, connections } : { flightIds }).then(r => r.data),
}
export const journeyApi = {
diff --git a/client/src/components/Admin/AdminPluginsPanel.test.tsx b/client/src/components/Admin/AdminPluginsPanel.test.tsx
index 3264de51c..8c1884818 100644
--- a/client/src/components/Admin/AdminPluginsPanel.test.tsx
+++ b/client/src/components/Admin/AdminPluginsPanel.test.tsx
@@ -1,5 +1,5 @@
import { http, HttpResponse } from 'msw'
-import { beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { server } from '../../../tests/helpers/msw/server'
import { fireEvent, render, screen, waitFor } from '../../../tests/helpers/render'
import { resetAllStores } from '../../../tests/helpers/store'
@@ -119,3 +119,366 @@ describe('AdminPluginsPanel — Discover modal, operator-egress pill', () => {
expect(screen.queryByText(/hosts you add/i)).not.toBeInTheDocument()
})
})
+
+/**
+ * #1523. The row's ⋯ menu used to be an in-flow `absolute` div, and PageSidebar — the
+ * panel's ancestor — is `overflow-hidden`. On the lower rows of a long plugin list the
+ * menu was clipped mid-way, taking Delete with it: the plugin became uninstallable from
+ * the UI. It must escape every overflow ancestor, and flip up when the bottom is tight.
+ */
+describe('AdminPluginsPanel — row ⋯ menu is never clipped (#1523)', () => {
+ const withRepo = plugin({ source_repo: 'trek/gotify', operatorEgress: false })
+ const realRect = HTMLButtonElement.prototype.getBoundingClientRect
+ afterEach(() => { HTMLButtonElement.prototype.getBoundingClientRect = realRect })
+
+ /** Put the ⋯ button wherever we want in an 800px-tall viewport. */
+ function stubTriggerAt(top: number) {
+ window.innerHeight = 800
+ window.innerWidth = 1200
+ HTMLButtonElement.prototype.getBoundingClientRect = function () {
+ return { top, bottom: top + 34, left: 1100, right: 1134, width: 34, height: 34, x: 1100, y: top, toJSON: () => ({}) } as DOMRect
+ }
+ }
+
+ async function openRowMenu() {
+ mockList(withRepo)
+ const { container } = render()
+ fireEvent.click(await screen.findByTestId('plugin-row-menu-btn-trek-gotify'))
+ return { container, menu: screen.getByTestId('plugin-row-menu-trek-gotify') }
+ }
+
+ it('FE-COMP-PLUGINS-MENU-001: renders every action, including Delete', async () => {
+ stubTriggerAt(100)
+ await openRowMenu()
+
+ for (const label of [/restart/i, /error log/i, /allowed hosts/i, /source repository/i, /report an issue/i, /delete/i]) {
+ expect(screen.getByText(label)).toBeInTheDocument()
+ }
+ })
+
+ it('FE-COMP-PLUGINS-MENU-002: is portaled out of the panel, so no overflow ancestor can clip it', async () => {
+ stubTriggerAt(100)
+ const { container, menu } = await openRowMenu()
+
+ // THE regression guard: living inside the panel is exactly what got it clipped.
+ expect(container.contains(menu)).toBe(false)
+ expect(menu.parentElement).toBe(document.body)
+ expect(menu.style.position).toBe('fixed')
+ })
+
+ it('FE-COMP-PLUGINS-MENU-003: hangs below the ⋯ when there is room', async () => {
+ stubTriggerAt(100)
+ const { menu } = await openRowMenu()
+
+ expect(menu.style.top).toBe('138px') // trigger bottom (134) + 4
+ expect(menu.style.bottom).toBe('')
+ expect(menu.style.right).toBe('66px') // viewport (1200) - trigger right (1134)
+ })
+
+ it('FE-COMP-PLUGINS-MENU-004: flips upward for a row near the bottom — the #1523 case', async () => {
+ stubTriggerAt(700) // 66px of room below: the six-item menu would run off-screen
+ const { menu } = await openRowMenu()
+
+ expect(menu.style.bottom).toBe('104px') // viewport (800) - trigger top (700) + 4
+ expect(menu.style.top).toBe('')
+ })
+})
+
+/**
+ * Signature status (#plugins). TREK has always verified author signatures and TOFU-pinned
+ * the key — and never showed any of it, so a successfully-installed UNSIGNED plugin looked
+ * identical to a signed one, forever.
+ *
+ * The two tests that matter most here are the ones guarding the override: a re-trust is
+ * offered for a ROTATED key (benign explanation) and for NOTHING else. A signature that
+ * doesn't verify means the bytes are not what the author signed, and there is no story
+ * where the right answer is letting the admin wave it through.
+ */
+function registryEntry(over: Record = {}) {
+ return {
+ id: 'trek-gotify', name: 'Gotify', author: 'Acme', description: 'Push', repo: 'acme/gotify',
+ type: 'integration', latest: '2.0.0', minTrekVersion: null, reviewedAt: null,
+ screenshotUrl: null, signed: true, authorPublicKey: 'NEWKEYbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+ ...over,
+ }
+}
+
+function mockPanel(p: Record, entry: Record | null = registryEntry()) {
+ server.use(
+ http.get('*/api/admin/plugins', () => HttpResponse.json({ enabled: true, devLink: false, plugins: [p] })),
+ http.get('*/api/admin/plugins/registry', () => HttpResponse.json(entry ? [entry] : [])),
+ )
+}
+
+describe('AdminPluginsPanel — signature badges', () => {
+ it('FE-COMP-PLUGINS-SIG-001: a registry plugin with a pinned key reads as Signed', async () => {
+ mockPanel(plugin({ source_repo: 'acme/gotify', signed: true, keyFingerprint: 'AAAAAAAA…BBBBBBBB' }))
+ render()
+ expect(await screen.findByText('Signed')).toBeInTheDocument()
+ expect(screen.queryByText('Unsigned')).not.toBeInTheDocument()
+ })
+
+ it('FE-COMP-PLUGINS-SIG-002: a registry plugin with no key reads as Unsigned', async () => {
+ mockPanel(plugin({ source_repo: 'acme/gotify', signed: false, keyFingerprint: null }))
+ render()
+ expect(await screen.findByText('Unsigned')).toBeInTheDocument()
+ })
+
+ // The precedence rule. `signed` derives from the pinned key, sideloaded from source_repo
+ // — so they are NOT mutually exclusive in the data, and a sideloaded plugin genuinely has
+ // no key. Rendering "Unsigned" NEXT TO "Sideloaded" would double up on a plugin whose
+ // badge already says something strictly stronger, diluting the amber into wallpaper.
+ it('FE-COMP-PLUGINS-SIG-003: a sideloaded plugin shows Sideloaded and NO trust badge', async () => {
+ mockPanel(plugin({ source_repo: 'local:upload', signed: false }))
+ render()
+ expect(await screen.findByText('Sideloaded')).toBeInTheDocument()
+ expect(screen.queryByText('Unsigned')).not.toBeInTheDocument()
+ expect(screen.queryByText('Signed')).not.toBeInTheDocument()
+ })
+
+ it('FE-COMP-PLUGINS-SIG-004: a dev-linked plugin shows Dev-Link and NO trust badge', async () => {
+ mockPanel(plugin({ source_repo: 'local:link', signed: false }))
+ render()
+ expect(await screen.findByText('Dev-Link')).toBeInTheDocument()
+ expect(screen.queryByText('Unsigned')).not.toBeInTheDocument()
+ })
+})
+
+describe('AdminPluginsPanel — a refused update', () => {
+ const blocked = (code: string) =>
+ plugin({
+ source_repo: 'acme/gotify', signed: true, keyFingerprint: 'OLDKEYaa…aaaaaaaa',
+ updateBlock: { code, detail: 'the signing key changed', version: '2.0.0' },
+ })
+
+ it('FE-COMP-PLUGINS-SIG-005: the row keeps showing WHY, instead of the reason dying with a toast', async () => {
+ mockPanel(blocked('SIGNATURE_KEY_CHANGED'))
+ render()
+ expect(await screen.findByText(/update blocked/i)).toBeInTheDocument()
+ })
+
+ // The block describes the version that was REFUSED. Once the registry offers a newer one,
+ // it describes an artifact nobody is being offered anymore — so it reads as stale and the
+ // admin can simply re-attempt.
+ it('FE-COMP-PLUGINS-SIG-006: the block goes quiet once a NEWER version is on offer', async () => {
+ mockPanel(blocked('SIGNATURE_KEY_CHANGED'), registryEntry({ latest: '3.0.0' }))
+ render()
+ await screen.findByText('Gotify')
+ await waitFor(() => expect(screen.queryByText(/update blocked/i)).not.toBeInTheDocument())
+ })
+
+ it('FE-COMP-PLUGINS-SIG-007: Review opens the re-trust dialog for a ROTATED key', async () => {
+ mockPanel(blocked('SIGNATURE_KEY_CHANGED'))
+ render()
+ fireEvent.click(await screen.findByRole('button', { name: /review/i }))
+
+ // Both fingerprints, so the admin can compare them against what the author tells them.
+ expect(await screen.findByText(/key it was installed with/i)).toBeInTheDocument()
+ expect(screen.getByText(/key it is offering now/i)).toBeInTheDocument()
+ expect(screen.getByRole('button', { name: /trust the new key/i })).toBeInTheDocument()
+ })
+
+ // D2, at the UI. An invalid signature means the bytes are not what the author signed.
+ // There is no override — not a disabled button, not one behind a confirm. The ABSENCE of
+ // an escape hatch is the feature. (The server refuses it too; this is belt and braces.)
+ it('FE-COMP-PLUGINS-SIG-008: an INVALID signature offers NO re-trust affordance at all', async () => {
+ mockPanel(blocked('SIGNATURE_INVALID'))
+ render()
+ fireEvent.click(await screen.findByRole('button', { name: /review/i }))
+
+ await screen.findByText(/do not match the author's signature/i)
+ expect(screen.queryByRole('button', { name: /trust the new key/i })).not.toBeInTheDocument()
+ // ...and it does not even show the key comparison, which would imply a choice exists.
+ expect(screen.queryByText(/key it is offering now/i)).not.toBeInTheDocument()
+ })
+
+ it('FE-COMP-PLUGINS-SIG-009: an unsigned-downgrade refusal offers no override either', async () => {
+ mockPanel(blocked('SIGNATURE_MISSING'))
+ render()
+ fireEvent.click(await screen.findByRole('button', { name: /review/i }))
+
+ await screen.findByText(/ships no signature/i)
+ expect(screen.queryByRole('button', { name: /trust the new key/i })).not.toBeInTheDocument()
+ })
+
+ it('FE-COMP-PLUGINS-SIG-010: confirming a re-trust re-pins AND updates in ONE call', async () => {
+ let body: unknown = null
+ mockPanel(blocked('SIGNATURE_KEY_CHANGED'))
+ server.use(
+ http.post('*/api/admin/plugins/trek-gotify/retrust', async ({ request }) => {
+ body = await request.json()
+ return HttpResponse.json({ version: '2.0.0', activated: true, newPermissions: [], newEgress: [] })
+ }),
+ )
+ render()
+ fireEvent.click(await screen.findByRole('button', { name: /review/i }))
+ fireEvent.click(await screen.findByRole('button', { name: /trust the new key/i }))
+
+ // The FULL key goes back, not the fingerprint: the server's equality check is exact, so
+ // it can refuse if the entry was re-keyed again since this dialog rendered.
+ await waitFor(() =>
+ expect(body).toEqual({ version: '2.0.0', publicKey: 'NEWKEYbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb' }),
+ )
+ // No follow-up /update: a re-pin that waited for a second call would leave the plugin
+ // pinned to a key no install had ever verified against if that call never came.
+ })
+})
+
+describe('AdminPluginsPanel — update consent', () => {
+ it('FE-COMP-PLUGINS-SIG-011: says an unsigned update is untied to its author, and still activates in one click', async () => {
+ let activated = false
+ mockPanel(plugin({ source_repo: 'acme/gotify', signed: false }), registryEntry({ signed: false }))
+ server.use(
+ http.post('*/api/admin/plugins/trek-gotify/update', () =>
+ HttpResponse.json({ version: '2.0.0', activated: false, newPermissions: ['db:read:trips'], newEgress: [] }),
+ ),
+ http.post('*/api/admin/plugins/trek-gotify/activate', () => { activated = true; return HttpResponse.json({ status: 'active' }) }),
+ )
+ render()
+ await screen.findByText('Gotify')
+ fireEvent.click(await screen.findByRole('button', { name: /update to|2\.0\.0/i }))
+
+ // Informs — it does not block. No checkbox, no second click.
+ expect(await screen.findByText(/nothing ties this version to its author/i)).toBeInTheDocument()
+ fireEvent.click(screen.getByRole('button', { name: /approve & turn on/i }))
+ await waitFor(() => expect(activated).toBe(true))
+ })
+
+ // The warning used to be read ONLY off the registry entry, so an unreachable registry left
+ // it undefined and the pill silently vanished — at the exact moment the admin was widening
+ // what unsigned code may do. The installed row carries an authoritative `signed` from the
+ // server on every list call; degrade to that rather than to silence.
+ //
+ // Consent is reached here by turning a plugin back ON after an update widened its
+ // permissions (409 CONSENT_REQUIRED) — which is the path that still works with the registry
+ // down, precisely because it needs nothing from the registry.
+ it('FE-COMP-PLUGINS-SIG-015: the unsigned warning survives an unreachable registry', async () => {
+ server.use(
+ http.get('*/api/admin/plugins', () =>
+ HttpResponse.json({
+ enabled: true, devLink: false,
+ plugins: [plugin({ source_repo: 'acme/gotify', signed: false, enabled: 0, status: 'inactive', operatorEgress: false })],
+ })),
+ // The registry is down: `regById` stays empty, so the entry's `signed` is unknowable.
+ http.get('*/api/admin/plugins/registry', () => HttpResponse.json({ error: 'registry unreachable' }, { status: 500 })),
+ http.post('*/api/admin/plugins/trek-gotify/activate', () =>
+ HttpResponse.json({ error: 'consent required', code: 'CONSENT_REQUIRED', newPermissions: ['db:read:trips'], newEgress: [] }, { status: 409 })),
+ )
+ render()
+ fireEvent.click(await screen.findByRole('button', { name: /enable plugin/i }))
+
+ // Falls back to the installed row's `signed: false` rather than going quiet.
+ expect(await screen.findByText(/nothing ties this version to its author/i)).toBeInTheDocument()
+ })
+})
+
+/**
+ * A signature refusal must reach the dialog even when the plugin has NO installed row —
+ * which is every fresh install from Discover, and every dependency being downloaded.
+ *
+ * Routing the refusal off the installed list meant those two paths silently fell back to a
+ * generic toast: the admin met SIGNATURE_INVALID for the first time on the one path where the
+ * dialog explaining it never opened. A fresh install has no pinned key, so it can only ever
+ * be _INVALID / _INCOMPLETE — never a rotation — and both are non-overridable, so the dialog
+ * must explain and offer nothing.
+ */
+describe('AdminPluginsPanel — a refusal with no installed row', () => {
+ it('FE-COMP-PLUGINS-SIG-013: a fresh install refused for an INVALID signature opens the dialog, not a toast', async () => {
+ server.use(
+ http.get('*/api/admin/plugins', () => HttpResponse.json({ enabled: true, devLink: false, plugins: [] })),
+ http.get('*/api/admin/plugins/registry', () => HttpResponse.json([registryEntry()])),
+ http.post('*/api/admin/plugins/install', () =>
+ HttpResponse.json({ error: 'author signature verification failed', code: 'SIGNATURE_INVALID' }, { status: 400 })),
+ )
+ render()
+ fireEvent.click(await screen.findByRole('button', { name: /discover/i }))
+ fireEvent.click(await screen.findByRole('button', { name: /^install$/i }))
+
+ // The dialog, named after the plugin — which it can only know from the REGISTRY entry,
+ // there being no installed row to read a name off.
+ expect(await screen.findByText(/gotify's signature could not be verified/i)).toBeInTheDocument()
+ await screen.findByText(/do not match the author's signature/i)
+ // Non-overridable, and no key comparison — showing one would imply a choice exists.
+ expect(screen.queryByRole('button', { name: /trust the new key/i })).not.toBeInTheDocument()
+ expect(screen.queryByText(/key it is offering now/i)).not.toBeInTheDocument()
+ })
+
+ it('FE-COMP-PLUGINS-SIG-014: a refusal while downloading a DEPENDENCY opens the dialog too', async () => {
+ const parent = plugin({ id: 'trek-parent', name: 'Parent', source_repo: 'acme/parent', enabled: 0, status: 'inactive', operatorEgress: false })
+ server.use(
+ http.get('*/api/admin/plugins', () => HttpResponse.json({ enabled: true, devLink: false, plugins: [parent] })),
+ http.get('*/api/admin/plugins/registry', () => HttpResponse.json([registryEntry()])),
+ // Turning it on reveals the missing dependency…
+ http.post('*/api/admin/plugins/trek-parent/activate', () =>
+ HttpResponse.json({ error: 'missing dependency', code: 'DEPENDENCY_MISSING', missing: [{ id: 'trek-gotify', version: '^1.0.0' }], versionMismatch: [] }, { status: 409 })),
+ // …and downloading it is refused on its signature.
+ http.post('*/api/admin/plugins/install', () =>
+ HttpResponse.json({ error: 'author signature verification failed', code: 'SIGNATURE_INVALID' }, { status: 400 })),
+ )
+ render()
+ fireEvent.click(await screen.findByRole('button', { name: /enable plugin/i }))
+ fireEvent.click(await screen.findByRole('button', { name: /download/i }))
+
+ // Named after the DEPENDENCY, not the parent — it is the dependency's author whose
+ // signature did not verify, and saying "Parent" here would point the admin at the wrong
+ // plugin entirely.
+ expect(await screen.findByText(/gotify's signature could not be verified/i)).toBeInTheDocument()
+ expect(screen.queryByRole('button', { name: /trust the new key/i })).not.toBeInTheDocument()
+ })
+})
+
+describe('AdminPluginsPanel — a block never outlives the registry relationship', () => {
+ // The server clears the block on sideload/dev-link. This is the belt: even if a stale
+ // block somehow reached the client, a plugin whose code the admin supplied by hand must
+ // never claim an update was blocked over an author signing key.
+ it('FE-COMP-PLUGINS-SIG-012: a sideloaded plugin never shows an update block', async () => {
+ mockPanel(plugin({
+ source_repo: 'local:upload', signed: false,
+ updateBlock: { code: 'SIGNATURE_KEY_CHANGED', detail: 'the signing key changed', version: '2.0.0' },
+ }))
+ render()
+ await screen.findByText('Sideloaded')
+ expect(screen.queryByText(/update blocked/i)).not.toBeInTheDocument()
+ })
+})
+
+/**
+ * TREK-version compatibility. The SERVER owns the semver — a second implementation in the
+ * browser would eventually disagree with the install gate and offer a button that 400s —
+ * so the panel only renders the verdict the API hands it (`compatible`, `latestCompatible`).
+ */
+describe('AdminPluginsPanel — TREK-version compatibility', () => {
+ /** Discover cards for a plugin that is NOT installed — an installed one just reads "Installed". */
+ async function openDiscover(entry: Record) {
+ mockPanel(plugin({ id: 'something-else' }), registryEntry(entry))
+ render()
+ fireEvent.click(await screen.findByText('Discover'))
+ }
+
+ it('blocks Install when no published version runs on this TREK, and says why', async () => {
+ await openDiscover({ trek: '>=4.0.0', hostVersion: '3.3.0', compatible: false, latestCompatible: null })
+ const btn = await screen.findByRole('button', { name: /^incompatible$/i })
+ expect(btn).toBeDisabled()
+ })
+
+ it('offers the newest version that DOES run here rather than a dead button', async () => {
+ await openDiscover({ latest: '2.0.0', trek: '>=3.4.0', hostVersion: '3.3.0', compatible: false, latestCompatible: '1.5.0' })
+ const btn = await screen.findByRole('button', { name: /^install 1\.5\.0$/i })
+ expect(btn).toBeEnabled()
+ })
+
+ it('installs normally when the latest version fits', async () => {
+ await openDiscover({ trek: '>=3.2.0 <4.0.0', hostVersion: '3.3.0', compatible: true, latestCompatible: '2.0.0' })
+ expect(await screen.findByRole('button', { name: /^install$/i })).toBeEnabled()
+ })
+
+ it('an installed plugin the server has outgrown shows the blocker on its card', async () => {
+ // Same amber chip machinery as a disabled addon / missing dependency — the admin sees
+ // one "here is why this cannot turn on" surface, not a new concept per blocker.
+ mockPanel(plugin({
+ dependencyStatus: 'hostIncompatible', trekRange: '>=3.2.0 <4.0.0', hostVersion: '4.0.0', enabled: 0, status: 'inactive',
+ }))
+ render()
+ expect(await screen.findByText(/needs trek >=3\.2\.0 <4\.0\.0/i)).toBeInTheDocument()
+ })
+})
diff --git a/client/src/components/Admin/AdminPluginsPanel.tsx b/client/src/components/Admin/AdminPluginsPanel.tsx
index 00d8b4af9..d14b64654 100644
--- a/client/src/components/Admin/AdminPluginsPanel.tsx
+++ b/client/src/components/Admin/AdminPluginsPanel.tsx
@@ -1,11 +1,13 @@
-import { useEffect, useMemo, useRef, useState, type DragEvent } from 'react'
+import { useEffect, useMemo, useRef, useState, type CSSProperties, type DragEvent } from 'react'
+import { createPortal } from 'react-dom'
import {
Blocks, AlertTriangle, PackageOpen, RefreshCw, Trash2, Download, Bug, X, ShieldCheck, UploadCloud,
- ArrowUpCircle, Github, ExternalLink, ChevronDown, Check, Lock, Search, Link2,
+ ArrowUpCircle, Github, ExternalLink, ChevronDown, Check, Lock, Search, Link2, KeyRound, ShieldAlert,
SlidersHorizontal, ArrowUpDown, CircleDot, MoreHorizontal, RotateCw, ArrowRight, Database, Users, LayoutDashboard,
- Radio, Luggage, Plane, Globe, Image, CalendarDays, Map, Bell, Cloud, Camera, Compass,
- BookOpen, Wallet, Puzzle, MapPin, ListChecks, Pencil, Tag, FileText,
+ Radio, Luggage, Globe, Image, CalendarDays, Bell,
+ Wallet, Puzzle, MapPin, ListChecks, Pencil, Tag, FileText,
} from 'lucide-react'
+import PluginIcon from '../shared/PluginIcon'
import { adminApi } from '../../api/client'
import { usePluginStore } from '../../store/pluginStore'
import { useTranslation } from '../../i18n'
@@ -24,7 +26,7 @@ import ToggleSwitch from '../Settings/ToggleSwitch'
interface PluginDep { id: string; version: string }
interface VersionMismatch { id: string; wanted: string; installed: string }
-type DependencyStatus = 'ok' | 'addonDisabled' | 'missingPlugin'
+type DependencyStatus = 'ok' | 'addonDisabled' | 'missingPlugin' | 'hostIncompatible'
interface PluginDependencies { requiredAddons: string[]; pluginDependencies: PluginDep[] }
interface DependencyIssues { disabledAddons: string[]; missing: PluginDep[]; versionMismatch: VersionMismatch[] }
@@ -49,6 +51,17 @@ interface PluginRow {
dependencies?: PluginDependencies
dependencyStatus?: DependencyStatus
dependencyIssues?: DependencyIssues
+ /** The TREK versions the plugin says it supports; null if it never declared any. */
+ trekRange?: string | null
+ /** The TREK this server is running — the server does the semver, the client just shows it. */
+ hostVersion?: string
+ /** The author's signature was verified and their key pinned at install. False means the
+ * bytes matched the registry's sha256 and nothing more — one fewer guarantee. */
+ signed?: boolean
+ /** Short form of the pinned key, for eyeballing against what the author reads out. */
+ keyFingerprint?: string | null
+ /** Why an update was refused, if one was. `version` is the version that was refused. */
+ updateBlock?: { code: string; detail: string | null; version: string | null } | null
}
interface RegistryItem {
id: string
@@ -58,13 +71,26 @@ interface RegistryItem {
repo: string
homepage?: string | null
type: string
+ /** Lucide icon name from the registry entry; absent → Blocks. */
+ icon?: string | null
latest: string | null
minTrekVersion: string | null
+ /** The latest version's declared TREK range; null on a legacy registry entry. */
+ trek?: string | null
+ hostVersion?: string
+ /** Whether the LATEST version can be installed on this TREK. Computed server-side. */
+ compatible?: boolean
+ /** Newest installable version — the latest, an older fallback, or null if none fits. */
+ latestCompatible?: string | null
reviewedAt: string | null
downloadCount?: number | null
screenshotUrl: string | null
requiredAddons?: string[]
pluginDependencies?: PluginDep[]
+ /** The latest version ships an author signature and the entry declares a key. */
+ signed?: boolean
+ /** The full key — public, and carried in full because re-trust compares it exactly. */
+ authorPublicKey?: string | null
}
interface RegistryDetail extends RegistryItem {
size: number | null
@@ -90,6 +116,49 @@ interface ActivateErr {
}
}
+/** The server's error envelope. Reading `code` — not the message text — is what lets the
+ * UI tell a rotated key (overridable) from a signature that doesn't verify (never). */
+function errBody(e: unknown): { error?: string; code?: string } {
+ return (e as { response?: { data?: { error?: string; code?: string } } })?.response?.data ?? {}
+}
+
+/** The ONE signature refusal an admin may override, because a rotation has a benign
+ * explanation. SIGNATURE_INVALID / _MISSING / _INCOMPLETE mean the bytes are not what the
+ * author signed — those get an explanation and no override button at all. */
+const RETRUSTABLE = 'SIGNATURE_KEY_CHANGED'
+const SIGNATURE_CODES = [RETRUSTABLE, 'SIGNATURE_INVALID', 'SIGNATURE_MISSING', 'SIGNATURE_INCOMPLETE']
+
+/**
+ * What the signature dialog needs to talk about a plugin — deliberately NOT a PluginRow.
+ *
+ * A refusal can land on a plugin that is not installed (a fresh install from Discover, or a
+ * dependency being downloaded), and those have no row. Keying the dialog off PluginRow meant
+ * the lookup missed and the refusal silently degraded to a toast — on the very path where an
+ * admin most often meets these codes for the first time. Name + pinned fingerprint is all the
+ * dialog ever reads, and both a row and a registry entry can supply that.
+ */
+type SigSubject = { id: string; name: string; keyFingerprint: string | null }
+
+/**
+ * Is a recorded update block still describing the version on offer?
+ *
+ * Once the registry offers something NEWER than the version that was refused, the block
+ * describes an artifact nobody is being offered anymore — so it reads as stale and the
+ * admin can simply re-attempt (the next install re-verifies and either succeeds or
+ * re-blocks with fresh values). When the registry is unreachable we can't prove staleness,
+ * so the block stands: silently dropping the last thing we knew would be the worse failure.
+ */
+function blockIsCurrent(p: PluginRow, latestVer?: string): boolean {
+ if (!p.updateBlock) return false
+ // A block describes a refused REGISTRY update. Once a plugin is sideloaded or dev-linked
+ // it has left the registry trust model — the running code is whatever the admin supplied,
+ // and a block about an author signing key says nothing about it. The server clears the
+ // block on both paths; this makes it impossible to render a stale one regardless.
+ if (!isRegistrySourced(p.source_repo)) return false
+ if (!latestVer || !p.updateBlock.version) return true
+ return latestVer === p.updateBlock.version
+}
+
type T = (k: string, p?: Record) => string
type TypeFilter = 'all' | 'widget' | 'page' | 'integration' | 'trip-page'
type StatusFilter = 'all' | 'on' | 'off' | 'update' | 'err'
@@ -105,11 +174,6 @@ const HEALTH: Record = {
incompatible: 'bg-warning',
}
-// Manifest `icon` is a lucide name; map the common ones, fall back to Blocks.
-const ICON_MAP: Record> = {
- Luggage, Plane, Globe, Image, CalendarDays, Map, Bell, Cloud, Camera, Compass, BookOpen, Wallet, Puzzle, Blocks,
-}
-
// Known permissions → human-readable i18n key; unknown ones render as raw code.
const PERM_KEYS = [
'db:own', 'db:read:trips', 'db:read:users', 'db:read:costs', 'db:read:packing', 'db:read:files', 'db:read:files:content',
@@ -186,10 +250,21 @@ function deriveCaps(perms: string[], caps: { widget?: { slot?: string }; tripPag
interface DepChip { icon: React.ComponentType<{ size?: number; className?: string }>; label: string; blocked: boolean }
// A plugin's declared dependencies as chips — a required addon (amber when that
-// addon is disabled) or a plugin dependency (amber when missing / version-mismatched).
+// addon is disabled), a plugin dependency (amber when missing / version-mismatched),
+// or the TREK version itself (amber when this server has outgrown the plugin's range,
+// which is the one blocker the admin cannot fix by flipping something else on).
function deriveDeps(p: PluginRow, t: T): DepChip[] {
const out: DepChip[] = []
const issues = p.dependencyIssues
+ if (p.dependencyStatus === 'hostIncompatible') {
+ out.push({
+ icon: AlertTriangle,
+ label: p.trekRange
+ ? t('admin.plugins.dep.trekIncompatible', { range: p.trekRange, host: p.hostVersion ?? '?' })
+ : t('admin.plugins.dep.trekUnknown'),
+ blocked: true,
+ })
+ }
for (const a of p.dependencies?.requiredAddons ?? []) {
out.push({ icon: Blocks, label: t('admin.plugins.cap.requiresAddon', { addon: a }), blocked: !!issues?.disabledAddons.includes(a) })
}
@@ -200,9 +275,24 @@ function deriveDeps(p: PluginRow, t: T): DepChip[] {
return out
}
-function PluginIcon({ name, size = 20, className }: { name: string | null; size?: number; className?: string }) {
- const Icon = (name && Object.prototype.hasOwnProperty.call(ICON_MAP, name) && ICON_MAP[name]) || Blocks
- return
+/**
+ * What the Install button may do for a registry item.
+ *
+ * The server already decided compatibility — it owns the semver, and a second
+ * implementation here would eventually disagree with the install gate and offer a button
+ * that 400s. This only picks the wording. Note the middle case: when the newest release
+ * has outrun this TREK but an older one still fits, offer THAT version rather than a dead
+ * grey button. The plugin is perfectly usable, just not at its newest.
+ */
+function installOffer(item: RegistryItem, t: T): { blocked: boolean; version?: string; label: string; title?: string } {
+ if (item.compatible !== false) return { blocked: false, label: t('admin.plugins.install') }
+ const title = item.trek
+ ? t('admin.plugins.dep.trekIncompatible', { range: item.trek, host: item.hostVersion ?? '?' })
+ : t('admin.plugins.dep.trekUnknown')
+ if (item.latestCompatible) {
+ return { blocked: false, version: item.latestCompatible, label: t('admin.plugins.installCompatible', { version: item.latestCompatible }), title }
+ }
+ return { blocked: true, label: t('admin.plugins.incompatible'), title }
}
function ReviewedBadge({ t, compact }: { t: T; compact?: boolean }) {
@@ -224,6 +314,46 @@ function SideloadedBadge({ t }: { t: T }) {
)
}
+/**
+ * Whether a plugin came from the REGISTRY (as opposed to a manual upload or a dev-link).
+ *
+ * This is the precedence rule for the trust badges, and it is load-bearing: `signed`
+ * derives from the pinned author key while sideloaded/dev-linked derive from source_repo,
+ * so the states are NOT mutually exclusive in the data. A sideloaded plugin genuinely has
+ * no pinned key, and a naive render would put "Unsigned" *and* "Sideloaded" side by side.
+ * The source badge wins — it already says something strictly stronger, and doubling up
+ * dilutes the amber into wallpaper, which is exactly what makes a warning worthless.
+ */
+function isRegistrySourced(sourceRepo: string | null | undefined): boolean {
+ return !!sourceRepo && sourceRepo !== 'local:upload' && sourceRepo !== 'local:link'
+}
+
+/**
+ * Signed / Unsigned, for registry plugins only (see isRegistrySourced).
+ *
+ * Signed is a quiet neutral tick, NOT a green celebration; unsigned is an amber note, NOT
+ * a red alarm. Roughly two thirds of the live registry is unsigned, so an alarming
+ * treatment would fire on most of the catalog and teach admins to ignore it — and the
+ * honest delta is small: sha256 proves the bytes are what the REGISTRY vouches for, a
+ * signature proves they came from the AUTHOR. Unsigned is one fewer guarantee, not "unsafe".
+ */
+function TrustBadge({ signed, t }: { signed: boolean; t: T }) {
+ if (signed) {
+ return (
+
+ {t('admin.plugins.signed')}
+
+ )
+ }
+ return (
+
+ {t('admin.plugins.unsigned')}
+
+ )
+}
+
/** Marks a dev-linked plugin: loaded from a local build dir + hot-reloaded (dev only). */
function DevLinkBadge({ t }: { t: T }) {
return (
@@ -255,6 +385,13 @@ export default function AdminPluginsPanel() {
const [view, setView] = useState<'installed' | 'discover'>('installed')
const [registry, setRegistry] = useState(null)
const [latest, setLatest] = useState>({})
+ // The registry entry per id — the re-trust dialog needs the NEW author key from it (in
+ // full: the server's equality check is exact), and the Discover/consent copy needs `signed`.
+ const [regById, setRegById] = useState>({})
+ // Open when a signature check refused an install/update. Carries the code, so the dialog
+ // knows whether an override may even be offered.
+ const [signatureBlock, setSignatureBlock] = useState<{ subject: SigSubject; code: string; detail: string | null } | null>(null)
+ const [retrusting, setRetrusting] = useState(false)
const [detailFor, setDetailFor] = useState(null)
const [errorsFor, setErrorsFor] = useState<{ id: string; rows: Array<{ ts: string; level: string; message: string }> } | null>(null)
const [egressFor, setEgressFor] = useState<{ id: string; supported: boolean; hosts: string[] } | null>(null)
@@ -288,6 +425,16 @@ export default function AdminPluginsPanel() {
const uploadInputRef = useRef(null)
const dragDepth = useRef(0)
+ // Index the registry once per fetch: the version map the update badges read, plus the
+ // whole entry (author key + signed flag) the trust badges and re-trust dialog need.
+ const indexRegistry = (items: RegistryItem[]) => {
+ const vers: Record = {}
+ const byId: Record = {}
+ items.forEach((i) => { byId[i.id] = i; if (i.latest) vers[i.id] = i.latest })
+ setLatest(vers)
+ setRegById(byId)
+ }
+
const refresh = () => {
// Keep the app-wide active-plugin store in sync so widget/hero/tab consumers
// (e.g. the dashboard) reflect an activate/deactivate without a full reload (F5).
@@ -298,13 +445,7 @@ export default function AdminPluginsPanel() {
setDevLink(!!d.devLink)
setPlugins(d.plugins || [])
if ((d.plugins || []).length) {
- adminApi.pluginBrowse()
- .then((items: RegistryItem[]) => {
- const map: Record = {}
- items.forEach((i) => { if (i.latest) map[i.id] = i.latest })
- setLatest(map)
- })
- .catch(() => {})
+ adminApi.pluginBrowse().then(indexRegistry).catch(() => {})
}
})
.catch(() => setError(true))
@@ -312,16 +453,43 @@ export default function AdminPluginsPanel() {
}
useEffect(refresh, [])
+ // A signature refusal is not an ordinary "action failed": it is the one class of error
+ // where WHICH failure it was decides what the admin may do about it. Route it to the
+ // dialog off the CODE, never off the message text. Returns true when handled.
+ //
+ // The subject is resolved from wherever it can be — the installed row, else the registry
+ // entry (a plugin being INSTALLED has no row yet), else the bare id. A signature code
+ // ALWAYS opens the dialog: falling back to a toast is what used to hide an invalid
+ // signature on a fresh install behind the same treatment as a network blip.
+ const routeSignatureError = (id: string, code?: string, detail?: string): boolean => {
+ if (!code || !SIGNATURE_CODES.includes(code)) return false
+ const row = plugins.find(p => p.id === id)
+ const subject: SigSubject = row
+ ? { id, name: row.name, keyFingerprint: row.keyFingerprint ?? null }
+ // Not installed: no pinned key exists, so SIGNATURE_KEY_CHANGED cannot arise and the
+ // dialog shows the no-override explanation — which is exactly right.
+ : { id, name: regById[id]?.name ?? id, keyFingerprint: null }
+ setSignatureBlock({ subject, code, detail: detail ?? null })
+ return true
+ }
+
const act = async (id: string, fn: () => Promise, ok: string) => {
setBusy(id); setMenu(null)
try { await fn(); toast.success(ok) }
- catch (e) { toast.error((e as { response?: { data?: { error?: string } } })?.response?.data?.error || t('admin.plugins.actionError')) }
+ catch (e) {
+ const { error, code } = errBody(e)
+ if (!routeSignatureError(id, code, error)) toast.error(error || t('admin.plugins.actionError'))
+ }
finally { setBusy(null); refresh() }
}
const openDiscover = () => {
setView('discover')
- if (!registry) adminApi.pluginBrowse().then(setRegistry).catch(() => setRegistry([]))
+ if (!registry) {
+ adminApi.pluginBrowse()
+ .then((items: RegistryItem[]) => { setRegistry(items); indexRegistry(items) })
+ .catch(() => setRegistry([]))
+ }
}
// The rescan/reload button rediscovers locally-installed plugins AND force-pulls
// the remote registry (bypassing the 30-min server cache + GitHub's CDN), so a
@@ -330,9 +498,7 @@ export default function AdminPluginsPanel() {
await adminApi.pluginRescan()
const items: RegistryItem[] = await adminApi.pluginBrowse(true)
setRegistry(items)
- const map: Record = {}
- items.forEach((i) => { if (i.latest) map[i.id] = i.latest })
- setLatest(map)
+ indexRegistry(items)
}, t('admin.plugins.rescanned'))
// Sideload a plugin archive (installs INACTIVE — the admin still consents on activation).
@@ -393,7 +559,7 @@ export default function AdminPluginsPanel() {
}
const updateAvailable = (p: PluginRow) => !!(p.version && latest[p.id] && isNewer(latest[p.id], p.version))
- const install = (id: string) => act(id, () => adminApi.pluginInstall(id), t('admin.plugins.installed'))
+ const install = (id: string, version?: string) => act(id, () => adminApi.pluginInstall(id, version ? { version } : undefined), t('admin.plugins.installed'))
const restart = (id: string) => act(id, async () => { await adminApi.pluginDeactivate(id); await adminApi.pluginActivate(id) }, t('admin.plugins.restarted'))
// Dev-link: register a plugin from a local built directory (dev only). Reuses the
// same busy/toast/refresh loop as uploadPlugin; the server gates it.
@@ -470,7 +636,13 @@ export default function AdminPluginsPanel() {
if (r?.requiredAddons?.length) toast.error(t('admin.plugins.dep.addonDisabledToast', { addons: r.requiredAddons.join(', ') }))
return attemptActivate(parent)
})
- .catch((e: ActivateErr) => onActivateError(parent, e))
+ // The DEPENDENCY is what's being downloaded, so a signature refusal here is about the
+ // dependency's author, not the parent's — route it under depId before falling through
+ // to the activation-error handling, which knows nothing about signature codes.
+ .catch((e: ActivateErr) => {
+ const { error, code } = errBody(e)
+ if (!routeSignatureError(depId, code, error)) onActivateError(parent, e)
+ })
.finally(() => { setBusy(null); refresh() })
}
@@ -481,10 +653,33 @@ export default function AdminPluginsPanel() {
if (r.activated || (r.newPermissions.length === 0 && r.newEgress.length === 0)) toast.success(t('admin.plugins.updated'))
else setConsentQueue(qq => [...qq, { plugin: p, version: r.version, newPermissions: r.newPermissions, newEgress: r.newEgress }])
})
- .catch(e => toast.error((e as { response?: { data?: { error?: string } } })?.response?.data?.error || t('admin.plugins.actionError')))
+ .catch(e => {
+ const { error, code } = errBody(e)
+ if (!routeSignatureError(p.id, code, error)) toast.error(error || t('admin.plugins.actionError'))
+ })
.finally(() => { setBusy(null); refresh() })
}
+ // Confirm a key rotation: re-pin the new key AND update, in one server call. There is no
+ // follow-up /update — a re-pin that waited for a second call would leave the plugin
+ // pinned to a key no install had ever been verified against if that call never came.
+ const confirmRetrust = (id: string, version: string, publicKey: string) => {
+ setRetrusting(true)
+ adminApi.pluginRetrust(id, version, publicKey)
+ .then((r: { version: string; activated: boolean; newPermissions: string[]; newEgress: string[] }) => {
+ setSignatureBlock(null)
+ // A re-trusted update widening permissions still needs consent — re-trusting a
+ // signing key says nothing about what the new code is allowed to do. Re-trust only
+ // ever fires for an INSTALLED plugin, so the row is there to consent against.
+ const p = plugins.find(x => x.id === id)
+ if (p && !r.activated && (r.newPermissions.length > 0 || r.newEgress.length > 0)) {
+ setConsentQueue(qq => [...qq, { plugin: p, version: r.version, newPermissions: r.newPermissions, newEgress: r.newEgress }])
+ } else toast.success(t('admin.plugins.retrusted'))
+ })
+ .catch(e => toast.error(errBody(e).error || t('admin.plugins.actionError')))
+ .finally(() => { setRetrusting(false); refresh() })
+ }
+
// eslint-disable-next-line react-hooks/exhaustive-deps
const updatable = useMemo(() => plugins.filter(updateAvailable), [plugins, latest])
@@ -691,8 +886,13 @@ export default function AdminPluginsPanel() {
) : shownInstalled.map(p => (
toggle(p)}
onUpdate={() => runUpdate(p)} onRestart={() => restart(p.id)}
+ onReviewBlock={() => setSignatureBlock({
+ subject: { id: p.id, name: p.name, keyFingerprint: p.keyFingerprint ?? null },
+ code: p.updateBlock!.code, detail: p.updateBlock!.detail,
+ })}
onErrors={() => openErrors(p.id)} onEgress={() => openEgress(p.id)}
onUninstall={() => { setMenu(null); setConfirmUninstall(p) }} />
))}
@@ -791,9 +991,26 @@ export default function AdminPluginsPanel() {
message={t('admin.plugins.uninstallBody')}
/>
+ {signatureBlock && (
+ confirmRetrust(signatureBlock.subject.id, version, publicKey)}
+ onClose={() => setSignatureBlock(null)}
+ />
+ )}
+
{consentQueue[0] && (
{
const c = consentQueue[0]; setConsentQueue(qq => qq.slice(1))
// consent:true — the ONLY path that may widen a plugin's granted rights.
@@ -886,14 +1103,33 @@ function EmptyState({ t, onDiscover }: { t: T; onDiscover: () => void }) {
)
}
-function InstalledRow({ p, t, busy, menu, setMenu, hasUpdate, latestVer, onToggle, onUpdate, onRestart, onErrors, onEgress, onUninstall }: {
+function InstalledRow({ p, t, busy, menu, setMenu, hasUpdate, latestVer, blocked, onToggle, onUpdate, onRestart, onReviewBlock, onErrors, onEgress, onUninstall }: {
p: PluginRow; t: T; busy: string | null; menu: string | null; setMenu: (v: string | null) => void
- hasUpdate: boolean; latestVer?: string
- onToggle: () => void; onUpdate: () => void; onRestart: () => void; onErrors: () => void; onEgress: () => void; onUninstall: () => void
+ hasUpdate: boolean; latestVer?: string; blocked: boolean
+ onToggle: () => void; onUpdate: () => void; onRestart: () => void; onReviewBlock: () => void
+ onErrors: () => void; onEgress: () => void; onUninstall: () => void
}) {
const caps = deriveCaps(parseJson(p.permissions, []), parseJson<{ widget?: { slot?: string } }>(p.capabilities, {}), t)
const deps = deriveDeps(p, t)
const menuOpen = menu === `row:${p.id}`
+ const menuBtnRef = useRef(null)
+
+ // The menu is portaled to and positioned `fixed` against the ⋯ button,
+ // because the row's ancestor (PageSidebar) is `overflow-hidden` and would clip
+ // an in-flow `absolute` menu — losing Delete on the lower rows of a long list.
+ // Re-anchor while the page moves under it.
+ const [, reanchor] = useState(0)
+ useEffect(() => {
+ if (!menuOpen) return
+ const onMove = () => reanchor(n => n + 1)
+ window.addEventListener('scroll', onMove, true)
+ window.addEventListener('resize', onMove)
+ return () => {
+ window.removeEventListener('scroll', onMove, true)
+ window.removeEventListener('resize', onMove)
+ }
+ }, [menuOpen])
+
return (
@@ -911,8 +1147,24 @@ function InstalledRow({ p, t, busy, menu, setMenu, hasUpdate, latestVer, onToggl
{p.reviewed_at && }
{p.source_repo === 'local:upload' && }
{p.source_repo === 'local:link' && }
+ {/* Registry plugins only — a sideloaded/dev-linked plugin already says something
+ strictly stronger, and stacking "Unsigned" on top of it just dilutes the amber. */}
+ {isRegistrySourced(p.source_repo) && }
{p.description &&
{p.description}
}
+ {/* A refused update leaves a WORKING plugin pinned at its old version — so this is
+ its own row state, not an error state, and it persists until it is resolved
+ rather than dying with the toast that first reported it. */}
+ {blocked && p.updateBlock && (
+
}
+ {/* The reason the button is blocked (or offering an older version) — a tooltip
+ alone would leave a touch user with a dead button and no explanation. */}
+ {offer.title && !installed && (
+
+ {offer.title}
+
+ )}
{manifest && (
@@ -1220,7 +1508,11 @@ function PluginDetailModal({ item, installed, busy, onInstall, onClose, t, local
{item.latest && }
{sizeKb && }
- {item.minTrekVersion && }
+ {/* The range, not just its lower bound: "TREK 3.2.0+" reads as "and anything
+ newer", which is exactly the claim a `<4.0.0` upper bound denies. */}
+ {(item.trek || item.minTrekVersion) && (
+
+ )}
{item.reviewedAt && }
{typeof item.downloadCount === 'number' && item.downloadCount > 0 && (
@@ -1254,8 +1546,101 @@ function Meta({ k, v }: { k: string; v: string }) {
return
{k}
{v}
}
-function UpdateConsentDialog({ data, t, onApprove, onLater }: {
+/**
+ * A signature check refused an install/update.
+ *
+ * The override lives here, and it is scoped to exactly one code. A rotated key has a
+ * benign explanation — the author rotated it, or lost it and made a new one. A signature
+ * that does NOT verify does not: it means the bytes are not what the author signed, which
+ * is corruption or an attack, and there is no story where the right answer is "let the
+ * admin wave it through". So SIGNATURE_INVALID / _MISSING / _INCOMPLETE get a clear
+ * explanation and no override button AT ALL — not a disabled one, not one behind a
+ * confirm. The absence of an escape hatch is the feature.
+ *
+ * (The server enforces this too — it re-derives the condition and refuses anything but a
+ * changed key. This dialog is the convenience, not the control.)
+ */
+function SignatureBlockDialog({ data, entry, busy, t, onRetrust, onClose }: {
+ data: { subject: SigSubject; code: string; detail: string | null }
+ entry: RegistryItem | undefined
+ busy: boolean; t: T
+ onRetrust: (version: string, publicKey: string) => void
+ onClose: () => void
+}) {
+ const canRetrust = data.code === RETRUSTABLE
+ const newKey = entry?.authorPublicKey ?? null
+ const version = entry?.latest ?? null
+ // Only offer the override when we actually hold the new key + version to send: the
+ // request carries both, and the server compares the key exactly.
+ const offerRetrust = canRetrust && !!newKey && !!version
+
+ const bodyKey = data.code === RETRUSTABLE ? 'admin.plugins.sig.keyChangedBody'
+ : data.code === 'SIGNATURE_MISSING' ? 'admin.plugins.sig.missingBody'
+ : data.code === 'SIGNATURE_INCOMPLETE' ? 'admin.plugins.sig.incompleteBody'
+ : 'admin.plugins.sig.invalidBody'
+
+ return (
+
+ {/* Fingerprints, not full keys: these exist to be COMPARED by a human — read the
+ new one back to the author over the phone. The full key travels in the request. */}
+ {canRetrust && (
+
+ )
+}
+
+/** Client-side twin of the server's fingerprint: head…tail of the base64 payload. Display
+ * only — every equality check that matters happens server-side against the full key. */
+function fingerprint(key: string | null): string | null {
+ if (!key) return null
+ const payload = key.trim().split(/\r?\n/).map(l => l.trim()).filter(l => l && !l.startsWith('untrusted comment')).pop()
+ if (!payload) return null
+ return payload.length <= 20 ? payload : `${payload.slice(0, 8)}…${payload.slice(-8)}`
+}
+
+function UpdateConsentDialog({ data, unsigned, t, onApprove, onLater }: {
data: { plugin: PluginRow; version: string; newPermissions: string[]; newEgress: string[] }
+ unsigned: boolean
t: T; onApprove: () => void; onLater: () => void
}) {
return (
@@ -1269,6 +1654,15 @@ function UpdateConsentDialog({ data, t, onApprove, onLater }: {
+ {/* The admin is about to widen what this code may do — so say, right here, that
+ nothing ties this code to its author. One line, no checkbox, no extra click:
+ this informs, it does not block. */}
+ {unsigned && (
+
setEditingSettlement(s)} className="bg-surface-secondary border border-edge text-content-muted" style={{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center', width: 28, height: 28, borderRadius: 999, cursor: 'pointer' }}>
@@ -901,9 +910,12 @@ function FlowPills({ ids, lead, Avatar, name }: { ids: number[]; lead: string; A
)
}
-// Add or edit a settle-up payment (from / to / amount). Reachable inline from the
-// ledger row and from a manual "Add payment" button, so recording "I sent money to
-// X" works the same whether or not there's an outstanding expense behind it.
+// Add or edit a settle-up payment (from / to / amount / currency). Reachable inline
+// from the ledger row and from a manual "Add payment" button, so recording "I sent
+// money to X" works the same whether or not there's an outstanding expense behind it.
+// A transfer can be made in any currency — paying a rouble debt in euros is normal —
+// so it carries its own, defaulting to the display currency. The server freezes its
+// FX rate on write, the same way an expense's is frozen.
function SettlementModal({ tripId, people, me, editing, currency, onClose, onSaved }: {
tripId: number; people: TripMember[]; me: number; editing: Settlement | null; currency: string; onClose: () => void; onSaved: () => void
}) {
@@ -913,6 +925,7 @@ function SettlementModal({ tripId, people, me, editing, currency, onClose, onSav
const [fromId, setFromId] = useState(String(editing?.from_user_id ?? me))
const [toId, setToId] = useState(String(editing?.to_user_id ?? otherDefault))
const [amount, setAmount] = useState(editing ? String(editing.amount) : '')
+ const [cur, setCur] = useState((editing?.currency || currency).toUpperCase())
const [saving, setSaving] = useState(false)
const amt = parseFloat(amount) || 0
@@ -922,7 +935,7 @@ function SettlementModal({ tripId, people, me, editing, currency, onClose, onSav
const save = async () => {
if (!valid) return
setSaving(true)
- const data = { from_user_id: Number(fromId), to_user_id: Number(toId), amount: amt, currency }
+ const data = { from_user_id: Number(fromId), to_user_id: Number(toId), amount: amt, currency: cur }
try {
if (editing) await budgetApi.updateSettlement(tripId, editing.id, data)
else await budgetApi.createSettlement(tripId, data)
@@ -930,7 +943,6 @@ function SettlementModal({ tripId, people, me, editing, currency, onClose, onSav
} catch { toast.error(t('common.unknownError')) } finally { setSaving(false) }
}
- const inputCls = 'w-full bg-surface-input border border-edge text-content'
const labelCls = 'block text-[11px] font-semibold uppercase tracking-[0.08em] text-content-faint mb-[6px]'
return (
@@ -950,10 +962,22 @@ function SettlementModal({ tripId, people, me, editing, currency, onClose, onSav
setToId(String(v))} options={opts} style={{ width: '100%' }} />