cabloy 5.1.141 → 5.1.142

package/.cabloy-version

@@ -1 +1 @@
-5.1.141
+5.1.142

package/.github/workflows/playwright-e2e.yml

@@ -27,7 +27,7 @@ jobs:
       - name: install Chromium
         run: npx playwright install --with-deps chromium
       - name: run Basic E2E baseline
-        run: npm run test:e2e:basic:clean
+        run: npm run test:e2e -- cabloy-basic account
       - name: upload Playwright artifacts
         if: failure()
         uses: actions/upload-artifact@v7
@@ -65,7 +65,7 @@ jobs:
       - name: synchronize Vona dependencies
         run: npm run deps:vona
       - name: run Commerce E2E baseline
-        run: npm run test:e2e:commerce:clean
+        run: npm run test:e2e a-commerce
       - name: upload Playwright artifacts
         if: failure()
         uses: actions/upload-artifact@v7

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 5.1.142
+
+### Features
+
+- Add commerce specifications and refund support.
+- Add address form and consumer URL support.
+- Add captcha support.
+- Add `LocalePattern` support.
+- Add Markdown code blocks, images, links, basic formatting, and tables.
+- Add `onFieldStateReady` documentation.
+
+### Bug Fixes
+
+- Fix JSX linting issues.
+
+### Improvements
+
+- Refactor end-to-end tests.
+- Regenerate the Vona lockfile.
+- Update account and type definitions.
+
 ## 5.1.141
 
 ### Features

package/cabloy-docs/frontend/form-guide.md

@@ -200,6 +200,53 @@ Use this when you need to:
 - intercept input and blur behavior yourself
 - mix Zova form state with a custom render contract
 
+### Initialize external state with `onFieldStateReady`
+
+A custom field sometimes has two state surfaces:
+
+- the `ControllerFormField` state owned by `ZForm`
+- state owned by the custom renderer or an external resource, such as a widget value or a challenge response
+
+Use `onFieldStateReady` when the custom field needs to synchronize those surfaces after Zova has prepared or reset the field:
+
+```tsx
+<ZFormField
+  name="externalValue"
+  onFieldStateReady={formField => {
+    if (this.externalValue !== undefined) {
+      formField.setValue(this.externalValue);
+    }
+  }}
+  slotDefault={({ props }, formField) => {
+    return (
+      <input
+        {...props}
+        value={formField.field.state.value ?? ''}
+        onInput={e => {
+          const value = (e.target as HTMLInputElement).value;
+          this.externalValue = value;
+          formField.setValue(value);
+        }}
+        onBlur={() => formField.handleBlur()}
+      ></input>
+    );
+  }}
+></ZFormField>
+```
+
+The callback receives the current `ControllerFormField` instance. It is a field-state lifecycle notification, not a DOM or VNode mounted hook, an asynchronous API-completion callback, or a general replacement for `nextTick`.
+
+Zova invokes it in two important situations:
+
+1. after the field controller has created its field binding and finished its initialization;
+2. after a schema-property change updates the field options and calls `resetField(this.name)`.
+
+The second timing is important: write the external value in the callback **after** the reset, because a write made before `resetField(...)` can be overwritten. If an external API later creates or refreshes the value, synchronize that API result explicitly as well; `onFieldStateReady` does not fetch, retry, or observe external resources for you.
+
+Use input handlers or `formField.setValue(...)` for ordinary value changes, `formField.handleBlur()` for blur state, and `onEffect` when the field needs a value-change effect. `onFieldStateReady` is a replay point for external state after field initialization or reset, not a per-value-change listener.
+
+For the source-level ordering and the relationship between field readiness and rendering, see [Zova Form Under the Hood](/frontend/zova-form-under-the-hood).
+
 ### `ZFormFieldBlank`
 
 Use `ZFormFieldBlank` when the row is **not** a real data field.

package/cabloy-docs/frontend/markdown-guide.md

@@ -16,6 +16,7 @@ Use this page together with:
 - [Component Guide](/frontend/component-guide)
 - [SSR ClientOnly](/frontend/ssr-client-only)
 - [Backend Markdown Guide](/backend/markdown-guide)
+- [Image Guide](/frontend/image-guide)
 
 > [!TIP]
 > **Choose the component by data contract**
@@ -63,12 +64,22 @@ export class EntityArticleContent {
 }
 ```
 
-The current resource options type does not add business-specific options. The renderer identifier is the important part of the contract:
+The field accepts an optional `imageScene` option. When it is omitted, the editor uploads through the public `a-markdown:markdown` scene supplied by the `a-markdown` module:
 
 ```typescript
 ZovaRender.field('basic-markdown:formFieldMarkdown');
 ```
 
+A business module can override that default when its images need resource-specific authorization, ownership metadata, delivery behavior, or upload limits:
+
+```typescript
+ZovaRender.field('basic-markdown:formFieldMarkdown', {
+  imageScene: 'article:bodyImage',
+});
+```
+
+The configured scene must be registered by the backend and must return a durable `http` or `https` URL. Define scene policy, authentication, provider, and upload constraints through the image contract described in the [Image Guide](/frontend/image-guide); do not construct storage URLs in the editor.
+
 The field value remains Markdown. It is not the editor's HTML output, and it should not be replaced with `innerHTML` or a browser DOM serialization.
 
 A field can keep the derived HTML hidden from the editor-facing form while still exposing it in a separate public DTO. The Commerce Catalog entity follows this shape:
@@ -90,11 +101,11 @@ The exact persistence and DTO design belongs to the business module. Markdown do
 
 `ZFormFieldMarkdown` is a Zova component with the normal Controller/Render/Style split.
 
-| Zova role  | Responsibility in this component                                                            |
-| ---------- | ------------------------------------------------------------------------------------------- |
-| Controller | Owns the TipTap `Editor`, Markdown `value`, `readonly` state, form callbacks, and lifecycle |
-| Render     | Composes the standard `ZFormField`, field shell, `ClientOnly`, and `EditorContent`          |
-| Style      | Creates the shared rich-text CSS class used by the editor and HTML display component        |
+| Zova role  | Responsibility in this component                                                                                    |
+| ---------- | ------------------------------------------------------------------------------------------------------------------- |
+| Controller | Owns the TipTap `Editor`, Markdown `value`, `readonly` state, toolbar commands/state, form callbacks, and lifecycle |
+| Render     | Composes the standard `ZFormField`, field shell, client-only toolbar, and `EditorContent`                           |
+| Style      | Creates the shared rich-text CSS class used by the editor and HTML display component                                |
 
 This is a Markdown editor integrated with `ZFormField`; it is not a generic HTML editor API.
 
@@ -103,7 +114,7 @@ This is a Markdown editor integrated with `ZFormField`; it is not a generic HTML
 The Controller creates the browser-dependent TipTap editor in `$controllerMounted`. Its extension set includes:
 
 - Markdown
-- StarterKit
+- StarterKit, with its plain code-block node replaced by `CodeBlockLowlight`
 - nested `TaskList` and `TaskItem`
 - Image
 - TableKit
@@ -119,6 +130,27 @@ editable: !this.readonly,
 
 The editor DOM receives the current component style class and a minimum-height/padding class. The outer field shell uses Cabloy Basic's DaisyUI-oriented classes and adds an error border when the host form field is invalid.
 
+### Toolbar
+
+When the field is editable, the same `ClientOnly` boundary renders a toolbar above the editor. It provides controls for:
+
+- undo and redo;
+- paragraph and heading levels 1–6;
+- bold, italic, strike-through, inline code, and highlight;
+- bullet, ordered, and task lists;
+- blockquotes, code blocks, and horizontal rules;
+- applying, updating, and removing links on the current text selection through a URL prompt;
+- uploading one image through the configured image scene and inserting the finalized image at the preserved selection;
+- inserting a table through an 8 × 8 floating size picker. Moving over a cell previews the rectangle from the top-left cell to that cell (for example, 2 × 3); clicking inserts that many rows and columns. Inserted tables retain a header row.
+
+The toolbar uses native buttons and a labelled block-style select, preserves the current editor selection while buttons are clicked, exposes active and unavailable states accessibly, and runs commands on the existing TipTap editor. Image upload delegates policy loading, validation, ordinary/direct transfer, and finalization to `basic-image`. Only a finalized URL using `http` or `https` is inserted, with the source filename as image alt text when available. The image node serializes through `getMarkdown()` just like every other editor command; it does not introduce an HTML value path. To add a link, select text and enter a URL; when the cursor is in an existing link, the same action edits its URL. Submitting an empty URL removes an existing link, while cancelling leaves the document unchanged. TipTap validates the URL before applying it, but backend Markdown rendering and sanitization remain the authoritative display security boundary. The table picker also supports keyboard navigation, Enter/Space to insert, and Escape to cancel. In readonly mode, TipTap remains visible but the toolbar and picker are omitted.
+
+When the selection is inside an editable table, a separate contextual toolbar appears above that table. It adds and deletes rows or columns around the current cell, and can delete the table. The menu shares the same `ClientOnly`, selection-preservation, accessibility, readonly, and Markdown-serialization guarantees as the persistent toolbar. Column resizing remains out of scope.
+
+When the cursor is inside an editable code block, a floating code-block toolbar appears above the block's `<pre>` element. It contains the language selector and supports Bash, CSS, C++, C#, Go, HTML, Java, JavaScript, JSON, Markdown, PHP, Python, Rust, Shell, SQL, and TypeScript, plus Plain text. The selector remains usable while focused and disappears after leaving the code block or entering readonly mode. Changing a language updates the fenced-code information string through TipTap's document attribute and persists as Markdown; lowlight token spans are an editor-only presentation detail and are never submitted as HTML. Existing unknown fence languages remain unchanged until the author explicitly selects a supported language or Plain text.
+
+The toolbars intentionally do not include remote image import, a color picker, or a configurable plugin registry. Use the configured image scene for uploads; remote-image import needs its own explicit authorization and persistence contract. Link editing uses the existing Markdown link and backend sanitization contracts.
+
 ### Editor-to-form flow
 
 When TipTap emits an update, the controller calls:
@@ -148,8 +180,8 @@ When the component is disposed, the controller calls `editor.destroy()` so TipTa
 TipTap's `EditorContent` is browser-dependent. The editor is therefore inside Zova's `ClientOnly` component:
 
 - SSR renders a minimum-height placeholder;
-- the browser creates the editor after mounting;
-- the editor should not be described as an SSR-rendered interactive control.
+- the browser creates the toolbar and editor after mounting;
+- the editor and toolbar should not be described as SSR-rendered interactive controls.
 
 The read-only HTML display path is different: it does not need TipTap or `ClientOnly` because it receives already-generated HTML.
 
@@ -223,7 +255,7 @@ const ready = true;
 ![Product image](https://example.com/product.png)
 ````
 
-The exact HTML output is governed by the backend renderer and sanitizer. Do not infer support for arbitrary raw HTML, iframe embeds, inline styles, `data:` URLs, or custom classes from the presence of a TipTap extension.
+The interactive editor decorates supported code blocks with lowlight token spans for syntax highlighting. The backend projection continues to render semantic `<code class="language-*">` output from Markdown; it does not persist editor token spans. Do not infer support for arbitrary raw HTML, iframe embeds, inline styles, `data:` URLs, or custom classes from the presence of a TipTap extension.
 
 ## Common mistakes
 
@@ -239,8 +271,8 @@ The exact HTML output is governed by the backend renderer and sanitizer. Do not
 4. **Expecting task checkboxes to be interactive**
    - The backend transforms rendered task inputs into disabled checkboxes for display.
 
-5. **Expecting a toolbar or upload workflow from this module**
-   - The module supplies an editor surface, not a toolbar specification, image upload service, remote image importer, or configurable plugin registry.
+5. **Expecting remote image import or unrelated plugin workflows from the toolbar**
+   - The toolbar supports configured image-scene uploads and Markdown link editing through a URL prompt, but it does not supply remote image import, a color picker, or a configurable plugin registry.
 
 6. **Treating browser validation or presentation CSS as security**
    - The backend renderer/sanitizer is the relevant content boundary. External image availability, privacy, CSP, and application authorization remain separate concerns.
@@ -252,10 +284,11 @@ Before integrating Markdown into a Zova feature, verify:
 1. The editable field is a string containing Markdown.
 2. The field metadata uses `basic-markdown:formFieldMarkdown`.
 3. The form value is updated through the editor's Markdown API, not HTML.
-4. Blur and readonly behavior still pass through the standard `ZFormField` contract.
-5. The interactive editor is inside the expected `ClientOnly` boundary.
-6. Public display uses `ZMarkdownHtml` only with server-derived sanitized HTML.
-7. Public DTOs do not expose editable Markdown unless that is intentional.
-8. The backend write path regenerates the HTML projection for every create, update, import, or backfill path that can change Markdown.
+4. Blur and readonly behavior still pass through the standard `ZFormField` contract, and readonly mode omits toolbar controls.
+5. Toolbar commands keep the value in Markdown through the editor API rather than creating an HTML submission path.
+6. The interactive toolbar and editor are inside the expected `ClientOnly` boundary.
+7. Public display uses `ZMarkdownHtml` only with server-derived sanitized HTML.
+8. Public DTOs do not expose editable Markdown unless that is intentional.
+9. The backend write path regenerates the HTML projection for every create, update, import, or backfill path that can change Markdown.
 
 For the backend API and security details, continue with [Backend Markdown Guide](/backend/markdown-guide).

package/cabloy-docs/frontend/route-alias-guide.md

@@ -54,6 +54,26 @@ The distinction matters after an alias has a documented reason:
 
 Do not introduce a static route name solely to use `routes.name`: a static exception can use `routes.path` instead.
 
+## Locale-aware aliases
+
+For a public route whose URL includes an optional locale segment, use the shared `LocalePattern` exported by Zova instead of hard-coding one language or copying a regular expression:
+
+```typescript
+import { LocalePattern } from 'zova';
+
+config.routes = {
+  name: {
+    'commerce-catalog:product': {
+      alias: `/:locale(${LocalePattern})?/product/:id`,
+    },
+  },
+};
+```
+
+The current pattern accepts the common `xx` and `xx-yy` forms, such as `en-us`, `zh-cn`, and `fr-fr`. It defines the URL shape; it is not a whitelist of installed languages. The languages that the application actually offers still come from `config.locale.items` and the corresponding locale resources. When adding a language, update those locale registrations and resources, but do not duplicate the language in each route alias.
+
+When the route declares `meta.locale: true`, `$router.getAliasPath(..., { params: { locale: true } })` uses the current locale and omits the configured default locale from an optional locale segment. Thus, with `en-us` as the default, the same alias can produce `/product/42` for `en-us` and `/zh-cn/product/42` for `zh-cn`.
+
 ## Generate a configured alias path
 
 When application code needs a user-facing URL for a named route, use the canonical route name with `$router.getAliasPath(...)`:

package/cabloy-docs/frontend/scripts.md

@@ -61,28 +61,26 @@ npm run build:zova:admin
 # Both default Basic sites, then a managed local run
 npm run build:zova
 npm run deps:vona
-npm run test:e2e:basic:clean
+npm run test:e2e cabloy-basic account
 ```
 
-The managed clean command resets Vona-managed test data and the local Redis namespace, starts one development Vona worker, and runs the complete suite by default. Browser commands consume already-built artifacts; they do not rebuild them.
+The managed clean command resets Vona-managed test data and the local Redis namespace, starts one development Vona worker, and runs the selected specs. Browser commands consume already-built artifacts; they do not rebuild them.
 
-The Basic and Commerce suite families use the same command shape:
+The unified runner uses two commands:
 
 ```text
-test:e2e:<suite>          complete suite
-test:e2e:<suite>:web      all @web surface scenarios
-test:e2e:<suite>:admin    all @admin surface scenarios
-test:e2e:<suite>:clean    managed clean local suite run
+npm run test:e2e                 clean local run with database reset
+npm run test:e2e:fast            fast run without automatic reset
 ```
 
-Use Playwright tags after npm's argument delimiter for scenario selection instead of adding one root script per scenario:
+Place flat spec basenames directly after the npm script name. Use npm's `--` delimiter before Playwright options. With no names, every spec in `e2e/specs` runs. Native `--grep` and `--grep-invert` remain available, and repeatable `--tag` values require all listed tags:
 
 ```bash
-npm run test:e2e:basic:clean -- --grep @flow
-npm run test:e2e:basic -- --grep ATP-BASIC-FLOW-01
+npm run test:e2e cabloy-basic account -- --grep @flow
+npm run test:e2e:fast a-commerce -- --tag @web --tag @smoke
 ```
 
-For the complete tag vocabulary, managed-runner argument boundaries, and externally managed-target examples, see [Repo Scripts](/reference/repo-scripts#ssr-browser-checks). For a separately managed Basic target, set `BASIC_E2E_BASE_URL`; Commerce commands use `COMMERCE_E2E_BASE_URL`. The caller owns external-target data, cache, and artifact freshness.
+For the complete tag vocabulary, managed-runner argument boundaries, and externally managed-target examples, see [Repo Scripts](/reference/repo-scripts#ssr-browser-checks). A separately managed target uses `E2E_BASE_URL` with `test:e2e:fast`; the caller owns external-target data, cache, and artifact freshness.
 
 ## Cabloy Start root wrappers
 

package/cabloy-docs/frontend/zova-form-under-the-hood.md

@@ -293,6 +293,31 @@ A practical reading takeaway is:
 - **the form owns the cross-field runtime**
 - **each field controller owns one field’s TanStack binding and render context**
 
+### Field-state readiness and custom synchronization
+
+The field options contract declares `onFieldStateReady` in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-form/src/types/formField.ts
+```
+
+Its callback receives the current `ControllerFormField<TParentData>` instance. The callback is owned by the field controller; it is not a DOM ref, a VNode mounted event, or a notification that an external API has completed.
+
+`ControllerFormField.__init__()` invokes the callback at the end of field initialization, after the field binding, computed props, behavior holder, and optional client-side `onEffect` watcher have been prepared. The same controller also watches the field's schema property. When that property changes materially, the sequence is:
+
+```text
+_getFormFieldOptions()
+  -> _formField.api.update(options)
+  -> form.resetField(name)
+  -> onFieldStateReady(formField)
+```
+
+The callback must follow `resetField(...)`. A custom field may hold a value outside the form controller—for example, a widget value or an externally created challenge object—and a value written before the reset can be replaced by the reset's default value. The callback provides the replay point where the custom field can write its current external value back through `formField.setValue(...)` or the owning form setter.
+
+This lifecycle is separate from external data changes. If an API creates or refreshes the external value later, synchronize that result in the API completion path too. Likewise, user input should continue to update the field through `formField.setValue(...)`, while value-change effects belong to the normal field effect/input surfaces. `onFieldStateReady` is not a per-value-change listener and does not fetch, retry, or wait for a renderer DOM node.
+
+For the public authoring shape and a renderer-neutral example, see [Initialize external state with `onFieldStateReady`](/frontend/form-guide#initialize-external-state-with-onfieldstateready).
+
 ## 7. How one field is configured
 
 The field controller builds its runtime configuration mainly through:

package/cabloy-docs/fullstack/parallel-worktree-environment.md

@@ -77,7 +77,7 @@ Use commands from the active repository root.
 
 | Edition      | Marker             | Frontend command                                   | Managed clean E2E              |
 | ------------ | ------------------ | -------------------------------------------------- | ------------------------------ |
-| Cabloy Basic | `__CABLOY_BASIC__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e:basic:clean` |
+| Cabloy Basic | `__CABLOY_BASIC__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e`             |
 | Cabloy Start | `__CABLOY_START__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e:start:clean` |
 
 Run one frontend command, not both, in each worktree. Both managed clean E2E workflows read Vona's effective local `SERVER_LISTEN_PORT`, then reset, start, and target that local runtime.

package/cabloy-docs/fullstack/quickstart.md

@@ -109,16 +109,17 @@ npm run upgrade:dry-run
 npm run upgrade
 ```
 
-In Cabloy Basic, upgrade synchronizes the framework-owned SSR browser E2E baseline, its suite/surface root `test:e2e:*` commands, and the `@playwright/test` development dependency. It does not add a root script for each individual E2E scenario. The framework reserves these paths:
+In Cabloy Basic, upgrade synchronizes the framework-owned SSR browser E2E baseline, the two root E2E scripts, and the `@playwright/test` development dependency. The framework owns these paths:
 
 ```text
 e2e/config/
 e2e/scripts/
-e2e/specs/cabloy-basic/
-e2e/specs/a-commerce/
+e2e/specs/cabloy-basic.spec.ts
+e2e/specs/account.spec.ts
+e2e/specs/a-commerce.spec.ts
 ```
 
-Keep project-owned browser tests outside those reserved paths, for example under `e2e/specs/my-project/`; upgrade overlays framework files without deleting project test paths. Projects whose previous upgrader predates this E2E synchronization may need to run `npm run upgrade` once more: the updated upgrader recognizes an incomplete Basic E2E baseline even when the version marker is already current.
+Keep additional project-owned browser specs under other filenames in `e2e/specs`. The current baseline is a fresh-project contract; unsupported legacy layouts are not repaired by the upgrader.
 
 ### Cabloy Start repository baseline
 

package/cabloy-docs/reference/repo-scripts.md

@@ -33,14 +33,8 @@ Cabloy Basic exposes these shared root scripts:
 - `npm run start:one`
 - `npm run test`
 - `npm run db:reset`
-- `npm run test:e2e:basic`
-- `npm run test:e2e:basic:web`
-- `npm run test:e2e:basic:admin`
-- `npm run test:e2e:basic:clean`
-- `npm run test:e2e:commerce`
-- `npm run test:e2e:commerce:web`
-- `npm run test:e2e:commerce:admin`
-- `npm run test:e2e:commerce:clean`
+- `npm run test:e2e`
+- `npm run test:e2e:fast`
 - `npm run tsc`
 - `npm run docs:dev`
 - `npm run docs:build`
@@ -88,11 +82,12 @@ Basic upgrade owns these browser baseline paths:
 ```text
 e2e/config/
 e2e/scripts/
-e2e/specs/cabloy-basic/
-e2e/specs/a-commerce/
+e2e/specs/cabloy-basic.spec.ts
+e2e/specs/account.spec.ts
+e2e/specs/a-commerce.spec.ts
 ```
 
-It also reconciles the framework Basic and Commerce `test:e2e:*` scripts and `@playwright/test` development dependency. Keep project browser tests outside those reserved paths. The upgrader merges framework baseline directories without deleting project-owned paths and can repair an incomplete Basic E2E baseline even when the framework version marker is already current.
+It also reconciles the two framework E2E scripts and the `@playwright/test` development dependency. Keep additional project browser specs under other filenames in `e2e/specs`; the upgrader updates only the listed framework files. The current fresh baseline is required and is not repaired for unsupported legacy project layouts.
 
 ### Cabloy Start private repository
 
@@ -108,44 +103,38 @@ The public-package upgrade flow does not source or reconcile the Start baseline,
 
 ## SSR browser checks
 
-The suites use this command family:
+The unified runner has two modes:
 
-- `test:e2e:<suite>` runs every browser scenario in the suite.
-- `test:e2e:<suite>:web` and `test:e2e:<suite>:admin` select `@web` and `@admin` scenarios.
-- `test:e2e:<suite>:clean` resets managed local state, starts one development Vona worker, then runs the suite or a Playwright-filtered subset.
+- `npm run test:e2e`: clean local run; checks the managed port, resets the database, starts one development Vona worker, and runs Playwright.
+- `npm run test:e2e:fast`: skips the reset for quick reruns and may target either the local managed server or an externally managed `E2E_BASE_URL`.
 
-The managed `:clean` runner requires port `7102` to be available. It owns the suite config and local lifecycle: it resets the database, and Playwright starts and stops `npm run dev:one`. It accepts normal Playwright selection and reporting options, but rejects external base URLs, `--config`, and positional spec paths. Use `--grep` or `--grep-invert` to narrow the run.
-
-Pass Playwright options after npm's `--` delimiter. `@web` and `@admin` are stable surface tags. Purpose tags depend on the suite: current scenarios use `@smoke`, while the Basic suite also uses `@flow`. ATP IDs remain in titles for exact evidence and failure reruns.
-
-### Cabloy Basic and Commerce
-
-The Basic suite exercises Web at `/` and Admin at `/admin` through Vona's SSR dispatcher. Prepare fresh SSR and REST artifacts explicitly when frontend output has changed:
+Place spec basenames directly after the npm script name; use npm's `--` delimiter only before Playwright options. Multiple spec names are allowed. With no names, every spec in `e2e/specs` is discovered:
 
 ```bash
-npm run build:zova
-npm run deps:vona
-npm run test:e2e:basic:clean
+npm run test:e2e cabloy-basic account
+npm run test:e2e a-commerce
+npm run test:e2e:fast account
+npm run test:e2e:fast a-commerce -- --grep ATP-SSR
+npm run test:e2e:fast a-commerce -- --grep-invert @admin
 ```
 
+Tags remain independent from filenames. Repeat `--tag` to require all tags, while native `--grep` and `--grep-invert` remain available:
+
 ```bash
-# Exact acceptance scenario
-npm run test:e2e:basic -- --grep ATP-BASIC-FLOW-01
+npm run test:e2e:fast a-commerce -- --tag @web --tag @smoke
+npm run test:e2e:fast account -- --grep @flow --tag @web
+```
 
-# Category or surface selection
-npm run test:e2e:basic:clean -- --grep @flow
-npm run test:e2e:basic:clean -- --grep @admin
+The existing tags include `@web`, `@admin`, `@smoke`, `@flow`, `@ssr`, `@theme`, and the business tags used by Commerce such as `@cart`, `@payment`, `@shipment`, and `@refund`. No suite tag is required. Clean runs are local-only and reject `E2E_BASE_URL`; fast runs against an external target do not reset, start, stop, or rebuild that target.
 
-# Compose tags with a Playwright regular expression
-npm run test:e2e:basic:clean -- --grep '(?=.*@admin)(?=.*@flow)'
-```
+### Cabloy Basic and Commerce
 
-For an externally managed Basic target, set `BASIC_E2E_BASE_URL` and use aggregate, surface, or forwarded-tag commands. These commands do not reset, start, stop, or rebuild the target:
+The Basic baseline exercises Web at `/` and Admin at `/admin` through Vona's SSR dispatcher. Prepare artifacts when frontend output has changed:
 
 ```bash
-BASIC_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:basic
-BASIC_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:basic:admin
-BASIC_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:basic -- --grep @flow
+npm run build:zova
+npm run deps:vona
+npm run test:e2e cabloy-basic account
 ```
 
 Commerce browser acceptance exercises Customer Web at `/commerce` and Operator Admin routing at `/commerce-admin`. Prepare its paired artifacts explicitly:
@@ -153,15 +142,13 @@ Commerce browser acceptance exercises Customer Web at `/commerce` and Operator A
 ```bash
 npm run build:zova:commerce
 npm run deps:vona
-npm run test:e2e:commerce:clean
+npm run test:e2e a-commerce
 ```
 
-For an externally managed Commerce target, set `COMMERCE_E2E_BASE_URL` and use the matching aggregate, surface, or forwarded-tag command. The target owner is responsible for data, cache, and artifact freshness:
+For a separately managed target, use the fast command:
 
 ```bash
-COMMERCE_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:commerce
-COMMERCE_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:commerce:web
-COMMERCE_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:commerce -- --grep @smoke
+E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:fast a-commerce -- --tag @smoke
 ```
 
 ### Cabloy Start

package/e2e/config/playwright.config.ts

@@ -0,0 +1,34 @@
+import { defineConfig } from '@playwright/test';
+
+import { E2E_LOCAL_BASE_URL, E2E_ROOT_DIR } from '../scripts/e2e.ts';
+
+const externalBaseURL = process.env.E2E_BASE_URL;
+const baseURL = externalBaseURL || E2E_LOCAL_BASE_URL;
+
+export default defineConfig({
+  testDir: `${E2E_ROOT_DIR}/e2e/specs`,
+  fullyParallel: false,
+  workers: 1,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  reporter: process.env.CI ? [['html', { open: 'never' }], ['list']] : 'list',
+  use: {
+    baseURL,
+    trace: 'on-first-retry',
+  },
+  webServer: externalBaseURL
+    ? undefined
+    : {
+        command: 'node e2e/scripts/startE2eVona.ts',
+        cwd: E2E_ROOT_DIR,
+        url: `${baseURL}/`,
+        timeout: 180_000,
+        reuseExistingServer: false,
+        stdout: 'pipe',
+        stderr: 'pipe',
+        gracefulShutdown: {
+          signal: 'SIGINT',
+          timeout: 10_000,
+        },
+      },
+});

package/e2e/scripts/e2e.ts

@@ -16,30 +16,5 @@ if (!Number.isInteger(e2ePort) || e2ePort <= 0 || e2ePort > 65535) {
 
 export const E2E_PORT = e2ePort;
 export const E2E_LOCAL_BASE_URL = `http://127.0.0.1:${E2E_PORT}`;
-
-const E2E_CONFIG_DIR = resolve(E2E_ROOT_DIR, 'e2e', 'config');
-const E2E_SPECS_DIR = resolve(E2E_ROOT_DIR, 'e2e', 'specs');
-
-const e2eSuites = {
-  basic: {
-    externalBaseUrlEnv: 'BASIC_E2E_BASE_URL',
-    configFile: resolve(E2E_CONFIG_DIR, 'playwright.basic.config.ts'),
-    testDir: resolve(E2E_SPECS_DIR, 'cabloy-basic'),
-    readinessPath: '/',
-  },
-  commerce: {
-    externalBaseUrlEnv: 'COMMERCE_E2E_BASE_URL',
-    configFile: resolve(E2E_CONFIG_DIR, 'playwright.commerce.config.ts'),
-    testDir: resolve(E2E_SPECS_DIR, 'a-commerce'),
-    readinessPath: '/commerce',
-  },
-} as const;
-
-export type E2eSuiteName = keyof typeof e2eSuites;
-
-export function getE2eSuite(name: string | undefined) {
-  if (name && name in e2eSuites) {
-    return e2eSuites[name as E2eSuiteName];
-  }
-  throw new Error(`Expected an E2E suite: ${Object.keys(e2eSuites).join(', ')}.`);
-}
+export const E2E_CONFIG_FILE = resolve(E2E_ROOT_DIR, 'e2e', 'config', 'playwright.config.ts');
+export const E2E_SPECS_DIR = resolve(E2E_ROOT_DIR, 'e2e', 'specs');

package/e2e/scripts/runE2e.ts

@@ -0,0 +1,62 @@
+import { execFileSync } from 'node:child_process';
+import { createServer } from 'node:net';
+import { resolve } from 'node:path';
+
+import {
+  E2E_CONFIG_FILE,
+  E2E_LOCAL_BASE_URL,
+  E2E_PORT,
+  E2E_ROOT_DIR,
+  E2E_SPECS_DIR,
+} from './e2e.ts';
+import { combineGreps, parseE2eArgs } from './runE2eArgs.ts';
+
+function run(command: string, args: string[]): void {
+  // eslint-disable-next-line no-console
+  console.log(`\n===> ${[command, ...args].join(' ')}`);
+  execFileSync(command, args, {
+    cwd: E2E_ROOT_DIR,
+    stdio: 'inherit',
+  });
+}
+
+async function assertPortAvailable(): Promise<void> {
+  const server = createServer();
+  await new Promise<void>((resolvePromise, reject) => {
+    server.once('error', reject);
+    server.listen(E2E_PORT, '127.0.0.1', () => {
+      server.close(error => {
+        if (error) reject(error);
+        else resolvePromise();
+      });
+    });
+  });
+}
+
+const parsed = parseE2eArgs(process.argv.slice(2), E2E_SPECS_DIR);
+if (parsed.mode === 'clean' && process.env.E2E_BASE_URL) {
+  throw new Error(
+    'The clean E2E run manages the local target and cannot be used with E2E_BASE_URL. Use test:e2e:fast for an external target.',
+  );
+}
+
+if (parsed.mode === 'clean') {
+  await assertPortAvailable();
+  run('npm', ['run', 'db:reset']);
+}
+
+const playwrightCommand = resolve(
+  E2E_ROOT_DIR,
+  'node_modules',
+  '.bin',
+  process.platform === 'win32' ? 'playwright.cmd' : 'playwright',
+);
+const specPaths = parsed.specNames.map(name => resolve(E2E_SPECS_DIR, `${name}.spec.ts`));
+const playwrightArgs = combineGreps(parsed.playwrightArgs, parsed.tags);
+run(playwrightCommand, ['test', '--config', E2E_CONFIG_FILE, ...specPaths, ...playwrightArgs]);
+
+// Keep this value referenced in the runner's startup output and make the local target explicit.
+if (!process.env.E2E_BASE_URL) {
+  // eslint-disable-next-line no-console
+  console.log(`E2E target: ${E2E_LOCAL_BASE_URL}`);
+}