117 lines
4.8 KiB
Markdown
117 lines
4.8 KiB
Markdown
---
|
|
spec: docs/specs/platform/requirements/dev-preview-title-prefixes.md
|
|
created: 2026-08-09
|
|
status: complete
|
|
---
|
|
|
|
# Implementation Plan: Environment-specific browser tab title prefixes
|
|
|
|
## Overview
|
|
|
|
Reuse the merged PR #2459 title-prefix contract and supply environment-specific
|
|
defaults at the launch boundaries. The development profile will provide `Dev`,
|
|
the PR preview startup script will provide `Preview`, and the CLI supervisor
|
|
will preserve the prefix across restarts. Focused Go, CLI, browser, and docs
|
|
checks will cover the launcher contracts and the visible browser result.
|
|
|
|
## Backend and launchers
|
|
|
|
### Development profile
|
|
|
|
- `apps/backend/internal/profiles/profiles.yaml` (the target of the root
|
|
`profiles.yaml` symlink): add `KANDEV_WEB_TITLE_PREFIX` with an empty `prod`
|
|
and `e2e` value and `Dev` as the `dev` value.
|
|
- `apps/backend/internal/profiles/profiles_test.go`: assert the dev profile
|
|
supplies `Dev` while the existing profile precedence remains intact.
|
|
|
|
### PR preview launcher
|
|
|
|
- `apps/backend/cmd/preview/sprite_ops.go`: export
|
|
`KANDEV_WEB_TITLE_PREFIX=Preview` in the generated preview startup script.
|
|
- `apps/backend/cmd/preview/sprite_ops_test.go`: pin the generated script to
|
|
the `Preview` prefix alongside its existing startup assertions.
|
|
|
|
### Supervisor environment contract
|
|
|
|
- `apps/cli/src/supervisor/manifest.ts`: add `KANDEV_WEB_TITLE_PREFIX` to the
|
|
restart-manifest allowlist so any configured prefix survives a supervised
|
|
backend restart.
|
|
- `apps/cli/src/supervisor/manifest.test.ts`: verify the title-prefix variable
|
|
is retained while arbitrary variables remain excluded.
|
|
|
|
## Frontend and browser behavior
|
|
|
|
No new frontend implementation is required. The existing PR #2459 path already
|
|
renders the configured prefix in the server shell and applies it for the
|
|
`/api/v1/app-state` boot path.
|
|
|
|
Add `apps/web/e2e/tests/system/title-prefix.spec.ts` to restart the fixture
|
|
backend with the development profile and with an explicit preview prefix, then
|
|
assert both visible browser titles through the UI. The test restores the worker
|
|
environment afterward.
|
|
|
|
### Mobile parity contract
|
|
|
|
The affected surface is browser metadata (`document.title`), not layout,
|
|
navigation, touch input, scrolling, or viewport-bound UI. The desktop and
|
|
mobile outcomes are identical, so no mobile-specific interaction test is
|
|
needed; the E2E test and existing title helper contract cover the same
|
|
viewport-independent behavior.
|
|
|
|
## Public documentation
|
|
|
|
- `docs/public/configuration.md`: explain that `make dev` defaults the title
|
|
prefix to `Dev` and PR previews use `Preview`, while explicit environment
|
|
values still override defaults.
|
|
- `docs/configuration.md`: keep the internal configuration reference aligned.
|
|
|
|
## Tests
|
|
|
|
- **What:** the development profile resolves the title prefix to `Dev` and
|
|
leaves production/e2e defaults blank.
|
|
**File:** `apps/backend/internal/profiles/profiles_test.go`.
|
|
**How:** profile application unit test with isolated environment variables.
|
|
- **What:** the preview startup script exports `Preview`.
|
|
**File:** `apps/backend/cmd/preview/sprite_ops_test.go`.
|
|
**How:** generated-script contract assertion.
|
|
- **What:** the supervisor retains the title-prefix environment variable.
|
|
**File:** `apps/cli/src/supervisor/manifest.test.ts`.
|
|
**How:** allowlist unit test.
|
|
- **What:** a configured runtime prefix is visible in the browser title.
|
|
**File:** `apps/web/e2e/tests/system/title-prefix.spec.ts`.
|
|
**How:** worker backend restart plus Playwright UI assertion.
|
|
|
|
## E2E Tests
|
|
|
|
- **Scenarios:** GIVEN a fixture backend restarted with the development profile,
|
|
WHEN the browser opens Kandev, THEN the page title is `Dev Kandev`; GIVEN a
|
|
fixture backend restarted with `KANDEV_WEB_TITLE_PREFIX=Preview`, THEN the
|
|
page title is `Preview Kandev`.
|
|
- **File:** `apps/web/e2e/tests/system/title-prefix.spec.ts`.
|
|
- **What to verify:** the user-visible browser tab title after a fresh page
|
|
navigation.
|
|
|
|
## Verification Results
|
|
|
|
- `cd apps/backend && go test -tags fts5 ./internal/profiles ./cmd/preview` —
|
|
passed, 30 tests in 2 packages.
|
|
- `cd apps && pnpm --filter kandev test -- --run src/dev.test.ts src/supervisor/manifest.test.ts` —
|
|
passed, 2 files and 6 tests.
|
|
- `cd apps/web && pnpm e2e:run --project chromium tests/system/title-prefix.spec.ts` —
|
|
passed, 2 Playwright tests (`Dev Kandev` and `Preview Kandev`).
|
|
- `node --test scripts/validate-public-docs.test.mjs` — passed, 58 tests.
|
|
- `node scripts/validate-public-docs.mjs` — passed, 41 published pages.
|
|
- `pnpm exec prettier --check ...` — passed for the changed TypeScript files.
|
|
- `git diff --check` — passed.
|
|
|
|
## Implementation Waves And Parallel Candidates
|
|
|
|
Wave 1 (sequential; the launch contracts and their tests are one cohesive
|
|
change):
|
|
|
|
- [x] [task-01-launch-prefixes](task-01-launch-prefixes.md)
|
|
|
|
## Open Questions
|
|
|
|
None.
|