@live-change/frontend-template 0.9.200 → 0.9.203

package/.cursor/rules/live-change-backend-models-and-relations.mdc

@@ -249,6 +249,39 @@ indexes: {
 
 Poza serwisem indeks bywa widoczny pod nazwą z prefiksem serwisu, np. `myService_Model_byDeviceAndStatus`.
 
+### Indeksy `function` dla pól wyliczanych
+
+Gdy część klucza indeksu nie istnieje jako zwykłe pole modelu (np. `month` wyliczany z `date`), użyj indeksu `function` zamiast `property`.
+
+Zasady:
+
+- buduj stabilny klucz jako `JSON.stringify(part1):JSON.stringify(part2):... + '_' + id`
+- zwracaj obiekty `{ id, to }`, gdzie `to` wskazuje źródłowy rekord
+- preferuj `table.map(mapper).to(output)` zamiast ręcznego `.onChange(...output.change...)`
+- `map()` automatycznie odfiltrowuje `null`, więc mapper może zwracać tylko docelowy obiekt
+
+```js
+indexes: {
+  byBankAccountAndMonthAndDate: {
+    function: async (input, output, { tableName }) => {
+      const table = await input.table(tableName)
+      const mapper = obj => ({
+        id: [
+          obj.bankAccount,
+          obj.date?.slice(0, 7),
+          obj.date
+        ].map(v => JSON.stringify(v)).join(':') + '_' + obj.id,
+        to: obj.id
+      })
+      await table.map(mapper).to(output)
+    },
+    parameters: {
+      tableName: definition.name + '_BankTransaction'
+    }
+  }
+}
+```
+
 ## Access control na relacjach
 
 - Zawsze ustawiaj `readAccessControl` i `writeAccessControl` na relacjach (`userItem`, `itemOf`, `propertyOf`), zamiast polegać na domyślnym zachowaniu.

package/.cursor/rules/live-change-frontend-e2e-lifecycle.mdc

@@ -0,0 +1,15 @@
+---
+description: Stable node:test E2E lifecycle with env, withBrowser and e2eSuite
+globs: **/e2e/**/*.{js,ts}
+alwaysApply: false
+---
+
+# Frontend E2E lifecycle
+
+- Keep teardown out of shared `e2e/env.ts`.
+- Never use `after(...process.exit(...))` in `env.ts`.
+- Add `disposeTestEnv()` in `env.ts` and call it from `process.on('beforeExit', ...)`.
+- Put `after(async () => { await disposeTestEnv(); process.exit(0) })` in `e2eSuite.ts`.
+- Wrap each `e2e/*.test.ts` file in one `e2eSuite('<suite-name>', () => { ... })`.
+- Keep startup failure `process.exit(1)` in `getTestEnv()` catch.
+- Run test commands with `fnm exec -- ...`.

package/.cursor/rules/live-change-frontend-i18n-locales.mdc

@@ -0,0 +1,26 @@
+---
+description: Keep all locale files under front/locales in sync when adding or changing i18n strings
+globs: **/front/locales/**/*.{json,js,ts}, **/front/src/**/*.{vue,js,ts}
+alwaysApply: false
+---
+
+# Frontend i18n – every file in `front/locales`
+
+When you add or change **user-visible strings** (labels, messages, buttons, errors, page titles, etc.) that go through **vue-i18n** or the project’s locale files, you must update **every** locale resource in that app’s **`front/locales/`** directory — not only one language.
+
+## Required workflow
+
+1. **Identify the app root** for the frontend you are editing (the folder whose tree contains `front/src` and `front/locales`).
+2. **List all locale files** in `front/locales/` for that app (`en.json`, `pl.json`, `en.js`, `pl.js`, `landing-en.json`, … — whatever exists).
+3. **Add or update the same keys** in **each** of those files. Structure and nesting must stay consistent across languages (same key paths).
+4. **Do not** add a new key to a single locale file and leave others missing — that breaks builds or shows raw keys at runtime.
+
+## Translations you are unsure about
+
+- Prefer a correct string in the primary locales (e.g. `en` + `pl`) when the product supports them.
+- For other files, use a sensible placeholder, copy from English, or add a clearly marked temporary string — but **still add the key** everywhere so nothing is omitted.
+
+## Scope
+
+- Applies to any work under `front/src` that introduces or changes translated text, and to direct edits in `front/locales`.
+- If a project uses multiple locale formats (`.json` and `.js`), update **all** files that participate in i18n for that app, not only one extension.

package/.cursor/rules/live-change-frontend-vue-primevue.mdc

@@ -6,6 +6,10 @@ alwaysApply: false
 
 # Frontend na live-change-stack – Vue 3 + PrimeVue + Tailwind
 
+## i18n i `front/locales`
+
+Za każdym razem gdy dodajesz lub zmieniasz teksty pod tłumaczenia, stosuj **`live-change-frontend-i18n-locales`**: te same klucze muszą trafić do **wszystkich** plików w **`front/locales/`** danej aplikacji (każdy język / wariant — nie tylko jeden plik).
+
 ## Stack
 
 - Vue 3 + TypeScript
@@ -207,6 +211,27 @@ path.blog.articles({})
 
 Dostęp: `article.authorProfile?.firstName`. Działa zarówno z `live()` jak i `RangeViewer`.
 
+## Listy zakresowe z reaktywnymi filtrami
+
+Jeśli `pathFunction` dla listy zakresowej zależy od reaktywnych filtrów (np. miesiąc/status/szukaj), preferuj `ReactiveRangeViewer`.
+
+Zasady:
+
+- nie polegaj na samej zmianie `pathFunction` w `RangeViewer`
+- nie rozrzucaj workaroundów typu ręczne `:key` po stronach
+- użyj `sourceKey` jako jawnego triggera przeładowania
+- gdy UX wymaga stabilności układu, ustaw `preserveHeightOnReload`
+
+```vue
+<ReactiveRangeViewer
+  :pathFunction="transactionsPathRange"
+  :sourceKey="JSON.stringify({ accountId, month: filterByMonth ? month : null })"
+  :preserveHeightOnReload="true"
+  :canLoadTop="false"
+  canDropBottom
+/>
+```
+
 ## WorkingZone dla akcji asynchronicznych
 
 `ViewRoot` opakowuje każdą stronę w `<WorkingZone>`. Używaj `inject('workingZone')` dla akcji przycisków poza formularzami:

package/.cursor/rules/live-change-node-toolchain-fnm.mdc

@@ -0,0 +1,40 @@
+---
+description: Run Node, npm, npx, tsx with fnm exec using project .node-version or .nvmrc
+alwaysApply: true
+---
+
+# Node.js toolchain – use `fnm exec`
+
+Do **not** rely on whatever Node.js version the agent sandbox or shell happens to use. That often differs from the project and breaks the LiveChange stack, tests, and `describe`.
+
+Use **fnm** so the version from the project dotfiles (`.node-version` or `.nvmrc`) is selected.
+
+## Required pattern
+
+Work in the directory that contains the relevant `.node-version` or `.nvmrc` (app or package root). Prefix **every** `node`, `npm`, `npx`, `corepack`, or `tsx` invocation with:
+
+```bash
+fnm exec -- <command and arguments>
+```
+
+Examples:
+
+```bash
+fnm exec -- node server/start.js describe --service myService --output yaml
+fnm exec -- npm test
+fnm exec -- npm run build
+fnm exec -- npx eslint .
+fnm exec -- tsx scripts/example.ts
+```
+
+If the dotfile lives only under a subfolder (e.g. `auto-firma/app/`), `cd` there first, then run `fnm exec -- ...`.
+
+## When this applies
+
+- Tests, CI scripts, linters, builds
+- Framework CLI: `describe`, dev servers, migrations, anything touching `@live-change/*`
+- Any `npm` / `node` / `npx` / `tsx` for this monorepo or its subprojects
+
+## If `fnm` is unavailable
+
+Tell the user to install fnm or align the environment; do not proceed assuming an arbitrary `node` on `PATH` is correct.

package/.cursor/skills/create-skills-and-rules.md

@@ -137,6 +137,22 @@ globs: **/front/src/**/*.{vue,js,ts}
 | `description` | What this rule covers (used for matching) |
 | `globs` | File patterns that trigger this rule (e.g. `**/*.js`, `**/services/**/*.js`) |
 
+### Backend / LiveChange service rules — standard `globs`
+
+Rules for **server-side** LiveChange code (models, actions, triggers, service layout) should use a **comma-separated** `globs` line so they still match when a project stores services under different folder names (many teams copy `.cursor/rules` into other repos):
+
+```yaml
+globs: **/services/**/*.js, **/server/**/*.js, server/**/*.js
+```
+
+| Pattern | Covers |
+|---|---|
+| `**/services/**/*.js` | Trees such as `live-change-stack/services/<service>/` |
+| `**/server/**/*.js` | Any nested `server/` directory (e.g. `app/server/`, `packages/foo/server/`) |
+| `server/**/*.js` | Backend rooted at top-level `server/` |
+
+Frontend rules keep their own globs (e.g. `**/front/src/**/*.{vue,js,ts}`). Do not drop the `server` variants for backend-only rules — otherwise Cursor will miss files after a layout change.
+
 ### Body structure
 
 ```markdown
@@ -181,6 +197,7 @@ alwaysApply: false
 - Do NOT quote glob patterns in frontmatter
 - Keep rules short (target 25 lines, max 50 lines for best Cursor performance)
 - The `.mdc` extension is required for Cursor
+- For **backend** LiveChange rules, use the same **`globs`** standard as in Claude rules: `**/services/**/*.js, **/server/**/*.js, server/**/*.js`
 
 ## Step 5 – Register rules in OpenCode (`opencode.json`)
 
@@ -198,8 +215,12 @@ OpenCode reads `.claude/skills/<name>/SKILL.md` natively for skills (no extra st
 
 When you **create a new rule**, add its path to the `instructions` array in `opencode.json`.
 
+Project rule **`live-change-node-toolchain-fnm`** should stay **first** (or early) in `instructions` so agents always load the requirement to run `node`, `npm`, `npx`, and `tsx` via `fnm exec` using `.node-version` / `.nvmrc`.
+
 When you **create a new skill**, no `opencode.json` change is needed — OpenCode discovers skills from `.claude/skills/<name>/SKILL.md` automatically.
 
+When a skill or rule shows shell examples that invoke **`node`**, **`npm`**, **`npx`**, or **`tsx`**, use the **`fnm exec -- …`** form (see `.claude/rules/live-change-node-toolchain-fnm.md` and skill `live-change-node-toolchain-fnm`).
+
 **Important:** OpenCode ignores the `globs` frontmatter from Claude Code rules. All instructions listed in `opencode.json` are always loaded.
 
 ## Step 6 – Mirror Cursor skills (`.cursor/skills/<name>.md`)
@@ -239,10 +260,12 @@ done
 
 ## Checklist
 
+- [ ] Shell examples for Node/npm use `fnm exec --` per `live-change-node-toolchain-fnm`
 - [ ] Directory created: `.claude/skills/<name>/SKILL.md`
 - [ ] Frontmatter has both `name` (matching dir) and `description`
 - [ ] `.cursor/skills/<name>.md` mirrored (flat file, same content)
 - [ ] `.claude/rules/*.md` created (if rule)
 - [ ] `.cursor/rules/*.mdc` created with `globs` + `alwaysApply` (if rule)
+- [ ] Backend rules use standard `globs`: `**/services/**/*.js, **/server/**/*.js, server/**/*.js` (when the rule targets LiveChange server code)
 - [ ] `opencode.json` `instructions` array updated (if new rule)
 - [ ] Sub-projects updated (automation, auto-firma)

package/.cursor/skills/live-change-design-actions-views-triggers.md

@@ -7,6 +7,12 @@ description: Design actions, views, triggers with indexes and batch processing p
 
 Use this skill to design **actions, views, and triggers** in LiveChange services while making good use of indexes and avoiding full-table scans.
 
+## Reads vs writes (CQRS-like)
+
+**Frontend (Vue):** load data with `usePath` + `live` / `useFetch` on **views**. Do **not** use `api.command` or `useActions()` only to fetch, preview, or compute display-only values — add a `definition.view` on the server and read it on the client.
+
+**Backend (services):** **`definition.view`** is the read surface (including computed or preview data). From triggers/actions use **`app.viewGet`** / **`app.serviceViewGet`** when you need the same view layer as the client, or direct model/index reads where appropriate. **Actions and triggers** change state via **`emit`** / **`trigger`** / **`triggerService`**, not via fake “read-only actions.”
+
 ## When to use
 
 - You add or change actions on existing models.

package/.cursor/skills/live-change-frontend-command-forms.md

@@ -19,15 +19,16 @@ Before using this skill, pick the right approach:
 |---|---|
 | `editorData` | **Editing model records** (create/update). Drafts, validation, `AutoField`. See `live-change-frontend-editor-form` skill. |
 | `actionData` | **One-shot action forms** (not CRUD). Submit once → done. See `live-change-frontend-action-form` skill. |
-| `api.command` | **Single button or programmatic calls** (no form fields). This skill, Step 1. |
+| `api.command` | **Mutations only** — single button or programmatic calls that **change persisted state** (no form fields). This skill, Step 1. Not for loading or previewing data (use views + `live` / `useFetch`; see `live-change-frontend-data-views`). |
 | `<command-form>` | **Avoid.** Legacy. Only for trivial prototypes without drafts or `AutoField`. This skill, Step 2. |
 
 **Decision flow:**
 
-1. Does the user fill in form fields? → **No**: use `api.command` (this skill).
-2. Is it editing a model record? → **Yes**: use `editorData`.
-3. Is it a one-shot action? → **Yes**: use `actionData`.
-4. Only use `<command-form>` for the simplest throwaway cases.
+1. Do you only need to **read** data (including previews)? → **Use views** (`live` / `useFetch`), not this skill.
+2. Does the user fill in form fields? → **No**: use `api.command` (this skill) **only if** the operation **mutates** state.
+3. Is it editing a model record? → **Yes**: use `editorData`.
+4. Is it a one-shot action? → **Yes**: use `actionData`.
+5. Only use `<command-form>` for the simplest throwaway cases.
 
 ## Step 1 – Use `api.command` directly
 

package/.cursor/skills/live-change-frontend-data-views.md

@@ -14,6 +14,8 @@ Use this skill when you build **reactive data views** using `usePath`, `live`, `
 - You need to load related objects alongside the main data.
 - You need to restrict data loading for unauthenticated users.
 
+**Do not use `api.command` / `useActions()` to load data.** Commands are for **mutations**. For every read (lists, details, previews, “next number”), use **views** with `live` or `useFetch` as in this skill.
+
 ## Step 1 – Basic data loading with computed paths
 
 When paths depend on reactive values (route params, props), wrap them in `computed()`:

package/.cursor/skills/live-change-frontend-e2e-lifecycle.md

@@ -0,0 +1,82 @@
+---
+name: live-change-frontend-e2e-lifecycle
+description: Set up stable node:test E2E lifecycle with env, withBrowser and e2eSuite
+---
+
+# Skill: live-change-frontend-e2e-lifecycle
+
+Use this skill when creating or refactoring LiveChange frontend E2E tests.
+
+## Goal
+
+Avoid flaky teardown where only the first test file runs because shared env teardown calls `process.exit`.
+
+## Step 1 - Build shared env helper
+
+Create `e2e/env.ts` with:
+
+- `getTestEnv()` that starts `TestServer` once and memoizes with `envPromise`
+- `disposeTestEnv()` that resets memoized state and disposes server
+- fallback cleanup:
+
+```ts
+process.on('beforeExit', () => {
+  void disposeTestEnv()
+})
+```
+
+Keep startup failure `process.exit(1)` inside `getTestEnv()` catch.
+
+Do not add `after(...process.exit(...))` to this file.
+
+## Step 2 - Isolate browser per test
+
+Create `e2e/withBrowser.ts` with Playwright setup/teardown in `try/finally`:
+
+- call `getTestEnv()` once per test execution
+- open browser/context/page
+- close context and browser in `finally`
+
+## Step 3 - Add suite-level teardown
+
+Create `e2e/e2eSuite.ts`:
+
+```ts
+import { after, describe } from 'node:test'
+import { disposeTestEnv } from './env.js'
+
+export function e2eSuite(name: string, define: () => void): void {
+  describe(name, () => {
+    after(async () => {
+      await disposeTestEnv()
+      process.exit(0)
+    })
+    define()
+  })
+}
+```
+
+## Step 4 - Wrap tests
+
+Each `e2e/*.test.ts` file should use one wrapper:
+
+```ts
+import test from 'node:test'
+import { e2eSuite } from './e2eSuite.js'
+
+e2eSuite('example-suite', () => {
+  test('renders page', async () => {
+    // test body
+  })
+})
+```
+
+## Step 5 - Verify
+
+Run from project root with `fnm exec`:
+
+```bash
+fnm exec -- npm run e2e
+```
+
+Confirm multiple test files execute and process exits only after full suite teardown.

package/.cursor/skills/live-change-frontend-range-list.md

@@ -127,3 +127,27 @@ Iterate in the template:
   </div>
 </template>
 ```
+
+## Step 5 – Reactive filters and safe reloads
+
+When your `pathFunction` depends on changing filters (month, status, company, search), prefer `ReactiveRangeViewer`.
+
+Why:
+
+- reactivity in `pathFunction` can be subtle and lead to stale bucket state
+- ad-hoc `:key` resets spread fragile logic in pages
+- `ReactiveRangeViewer` centralizes reload logic and can preserve list height while reloading
+
+```vue
+<ReactiveRangeViewer
+  :pathFunction="transactionsPathRange"
+  :sourceKey="JSON.stringify({ accountId, month: filterByMonth ? month : null })"
+  :preserveHeightOnReload="true"
+  :canLoadTop="false"
+  canDropBottom
+>
+  <template #default="{ item }">
+    <BankTransactionListItem :transaction="item" />
+  </template>
+</ReactiveRangeViewer>
+```

package/.cursor/skills/live-change-node-toolchain-fnm.md

@@ -0,0 +1,44 @@
+---
+name: live-change-node-toolchain-fnm
+description: Run node, npm, npx, tsx and framework CLI with fnm exec so .node-version and .nvmrc are respected
+---
+
+# Skill: Node toolchain with fnm
+
+Use this skill whenever you run **Node**, **npm**, **npx**, **tsx**, or **corepack** in this repo (tests, `describe`, dev servers, scripts). Agents must not use the default sandbox Node; use **fnm exec** so the version from dotfiles applies.
+
+## When to use
+
+- Running `npm test`, `npm run …`, linters, builds
+- `node server/start.js describe` or any framework entry
+- `tsx` for TypeScript scripts
+- Any subprocess that would invoke `node` or `npm` for a project with `.node-version` / `.nvmrc`
+
+## Step 1 – Find the right directory
+
+Locate the nearest project root that has `.node-version` or `.nvmrc` for the task (often the app folder, e.g. `auto-firma/app/`).
+
+`cd` to that directory before running commands so fnm reads the correct file.
+
+## Step 2 – Prefix with fnm exec
+
+```bash
+fnm exec -- node server/start.js describe --service myService --output yaml
+fnm exec -- npm test
+fnm exec -- npx vitest
+fnm exec -- tsx ./tools/something.ts
+```
+
+The part after `--` is the same command you would run manually with the correct Node active.
+
+## Step 3 – Nested monorepo paths
+
+If you are in the repo root but the dotfile is only under `some-app/`:
+
+```bash
+cd some-app && fnm exec -- npm test
+```
+
+## If fnm is missing
+
+Do not fall back to bare `node` / `npm` for framework work. Report that fnm is required (or document a one-off alternative the user approved).

package/.node-version

@@ -0,0 +1 @@
+20.19.2

package/.nvmrc

@@ -0,0 +1 @@
+20.19.2

package/README.md

@@ -69,3 +69,21 @@ Typowy flow tworzenia nowej aplikacji:
 
 Dokładny „manual” tego flow znajdzie się w sekcji `frontend/01-getting-started.md` dokumentacji.
 
+### E2E starter (node:test + Playwright)
+
+Szablon zawiera przykładowy zestaw E2E w katalogu `e2e/`:
+
+- `env.ts` - lazy start `TestServer` i `disposeTestEnv()`
+- `withBrowser.ts` - lifecycle przeglądarki per test
+- `e2eSuite.ts` - wrapper `describe` + `after` z finalnym teardown
+- `homepage.test.ts`, `client-session.test.ts` - przykładowe testy
+
+Uruchamianie:
+
+```bash
+fnm exec -- npm run e2e
+fnm exec -- npm run e2e:headed
+```
+
+Ważne: nie rejestruj `after(...process.exit(...))` w `e2e/env.ts`. Finalny `process.exit(0)` powinien być tylko w `e2eSuite.ts`.
+

package/e2e/client-session.test.ts

@@ -0,0 +1,17 @@
+import test from 'node:test'
+import assert from 'node:assert'
+import { withBrowser } from './withBrowser.js'
+import { e2eSuite } from './e2eSuite.js'
+
+e2eSuite('client-session', () => {
+  test('frontend initializes api client session', async () => {
+    await withBrowser(async (page, env) => {
+      await page.goto(env.url + '/', { waitUntil: 'networkidle' })
+      const session = await page.evaluate(() => {
+        const root = window as unknown as { api?: { client?: { value?: { session?: string } } } }
+        return root.api?.client?.value?.session
+      })
+      assert.ok(typeof session === 'string' && session.length > 0, 'session id is present')
+    })
+  })
+})

package/e2e/e2eSuite.ts

@@ -0,0 +1,12 @@
+import { after, describe } from 'node:test'
+import { disposeTestEnv } from './env.js'
+
+export function e2eSuite(name: string, define: () => void): void {
+  describe(name, () => {
+    after(async () => {
+      await disposeTestEnv()
+      process.exit(0)
+    })
+    define()
+  })
+}

package/e2e/env.ts

@@ -0,0 +1,130 @@
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { TestServer } from '@live-change/server'
+import appConfig from '../server/app.config.js'
+import * as services from '../server/services.list.js'
+
+const READY_TIMEOUT_MS = 60000
+const READY_POLL_MS = 2000
+
+async function waitForServerReady(url: string): Promise<void> {
+  const deadline = Date.now() + READY_TIMEOUT_MS
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url)
+      if (res.ok) return
+    } catch {
+      // not ready yet
+    }
+    await new Promise((r) => setTimeout(r, READY_POLL_MS))
+  }
+  throw new Error(`Server at ${url} did not become ready within ${READY_TIMEOUT_MS}ms`)
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const serverDir = path.join(__dirname, '..', 'server')
+const frontDir = path.join(__dirname, '..', 'front')
+
+for (const serviceConfig of appConfig.services) {
+  const name = (serviceConfig as { name: string }).name
+  ;(serviceConfig as { module?: unknown }).module = (services as Record<string, unknown>)[name]
+}
+;(appConfig as { init?: (s: unknown) => Promise<void> }).init = (services as { init: (s: unknown) => Promise<void> }).init
+
+export type TestEnv = {
+  server: InstanceType<typeof TestServer>
+  url: string
+  haveService: (name: string) => { name: string; models: Record<string, { get: (id: string) => Promise<unknown> }>; views: Record<string, unknown>; actions: Record<string, unknown>; triggers: Record<string, unknown> }
+  haveModel: (serviceName: string, modelName: string) => { get: (id: string) => Promise<unknown>; create: (data: unknown) => Promise<unknown>; update: (id: string, data: unknown) => Promise<unknown>; delete: (id: string) => Promise<unknown>; indexObjectGet: (index: string, key: unknown, opts?: unknown) => Promise<unknown>; indexRangeGet: (index: string, key: unknown) => Promise<unknown[]>; definition: { properties: Record<string, { preFilter: (v: unknown) => unknown }> } }
+  haveView: (serviceName: string, viewName: string) => unknown
+  haveAction: (serviceName: string, actionName: string) => unknown
+  haveTrigger: (serviceName: string, triggerName: string) => unknown
+  grabObject: (serviceName: string, modelName: string, id: string) => Promise<unknown>
+}
+
+type TestServerInstance = InstanceType<typeof TestServer>
+
+let envPromise: Promise<TestEnv> | null = null
+let testServer: TestServerInstance | null = null
+
+export async function disposeTestEnv(): Promise<void> {
+  const s = testServer
+  testServer = null
+  envPromise = null
+  if (s) await s.dispose()
+}
+
+function haveService(server: TestServerInstance, name: string) {
+  const service = server.apiServer.services.services.find((s: { name: string }) => s.name === name)
+  if (!service) throw new Error('service ' + name + ' not found')
+  return service
+}
+
+function haveModel(server: TestServerInstance, serviceName: string, modelName: string) {
+  const service = haveService(server, serviceName)
+  const model = service.models[modelName]
+  if (!model) throw new Error('model ' + modelName + ' not found')
+  return model
+}
+
+export async function getTestEnv(): Promise<TestEnv> {
+  if (envPromise) return envPromise
+  envPromise = (async () => {
+    const server = new TestServer({
+      dev: true,
+      enableSessions: true,
+      port: 0,
+      ssrRoot: frontDir,
+      initScript: path.join(serverDir, 'init.js'),
+      services: appConfig
+    })
+    console.log('starting test server')
+    try {
+      await server.start()
+    } catch (error) {
+      console.error((error as Error).stack)
+      process.exit(1)
+    }
+    console.log('Test server started at', server.url)
+    console.log('waiting for front to be ready...')
+    await waitForServerReady(server.url!)
+    console.log('front ready')
+
+    testServer = server
+
+    process.on('beforeExit', () => {
+      void disposeTestEnv()
+    })
+
+    const url = server.url!
+    return {
+      server,
+      url,
+      haveService: (name: string) => haveService(server, name),
+      haveModel: (serviceName: string, modelName: string) => haveModel(server, serviceName, modelName),
+      haveView: (serviceName: string, viewName: string) => {
+        const service = haveService(server, serviceName)
+        const view = service.views[viewName]
+        if (!view) throw new Error('view ' + viewName + ' not found')
+        return view
+      },
+      haveAction: (serviceName: string, actionName: string) => {
+        const service = haveService(server, serviceName)
+        const action = service.actions[actionName]
+        if (!action) throw new Error('action ' + actionName + ' not found')
+        return action
+      },
+      haveTrigger: (serviceName: string, triggerName: string) => {
+        const service = haveService(server, serviceName)
+        const trigger = service.triggers[triggerName]
+        if (!trigger) throw new Error('trigger ' + triggerName + ' not found')
+        return trigger
+      },
+      grabObject: async (serviceName: string, modelName: string, id: string) => {
+        const model = haveModel(server, serviceName, modelName)
+        return await model.get(id)
+      }
+    }
+  })()
+  return envPromise
+}

package/e2e/homepage.test.ts

@@ -0,0 +1,17 @@
+import test from 'node:test'
+import assert from 'node:assert'
+import { withBrowser } from './withBrowser.js'
+import { e2eSuite } from './e2eSuite.js'
+
+e2eSuite('homepage', () => {
+  test('homepage responds and renders html', async () => {
+    await withBrowser(async (page, env) => {
+      const response = await page.goto(env.url + '/', { waitUntil: 'networkidle' })
+      assert.ok(response, 'navigation returned response')
+      assert.ok(response!.ok(), 'homepage responds with success status')
+
+      const html = await page.content()
+      assert.ok(html.includes('<html'), 'page content contains html tag')
+    })
+  })
+})

package/e2e/steps.ts

@@ -0,0 +1,3 @@
+export async function sleep(ms: number): Promise<unknown> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/e2e/withBrowser.ts

@@ -0,0 +1,18 @@
+import { chromium } from 'playwright'
+import type { Page } from 'playwright'
+import { getTestEnv, type TestEnv } from './env.js'
+
+export async function withBrowser(
+  fn: (page: Page, env: TestEnv) => Promise<void>
+): Promise<void> {
+  const env = await getTestEnv()
+  const browser = await chromium.launch({ headless: process.env.SHOW_BROWSER ? false : true })
+  const context = await browser.newContext()
+  const page = await context.newPage()
+  try {
+    await fn(page, env)
+  } finally {
+    await context.close()
+    await browser.close()
+  }
+}