@qartisan/playwright-loupe 0.0.0-stage → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Before 1.0, minor versions may contain breaking changes. The JSON report has its own version (`schemaVersion`), see [`docs/schema/v1.md`](docs/schema/v1.md#versioning-policy).
+
+## [0.0.2] - 2026-10-15
+
+### Changed
+
+- **Error signatures change: failures are grouped differently from 0.0.1.** Normalization now also replaces e-mail addresses with `<email>` and cuid-like and nanoid-like identifiers (20+ characters mixing letters and digits) with `<id>`, so the same failure for different users or records gets one signature. A signature computed by 0.0.1 for a message containing such values no longer matches. The JSON shape is unchanged: `schemaVersion` stays `1`. See [Error signature](docs/schema/v1.md#error-signature).
+- **New built-in error categories**, evaluated after "Locator not found" and before "Network", "Assertion" and "Timeout": **Rate limited** (`Too Many Requests`, `rate limit`, a 429 in an HTTP context such as `status 429`, `HTTP 429` or `Response status: 429`) and **Server error** (a 500–599 status in the same contexts, or with its reason phrase such as `502 Bad Gateway`). Errors from `failOnStatusCode` and failed `expect(response).toBeOK()` that were "Uncategorized" or "Assertion" now land in these categories. A bare number (`429ms`, `Received: 500`) does not match. See [Error categories](docs/schema/v1.md#error-categories).
+- The package description now lists only what exists today.
+
+## [0.0.1] - 2026-10-13
+
+First public release. Work in progress: the reporter and its JSON model are usable, the HTML renderer is a minimal skeleton.
+
+### Added
+
+- **Playwright reporter** (`@qartisan/playwright-loupe`) that writes `report.json`, a self-contained `index.html` with the report injected, and the attachments under `data/`. Works with `playwright test` and `playwright merge-reports`, including sharded runs merged from blob reports.
+- **JSON report model, schema v1** (`schemaVersion: 1`), documented in [`docs/schema/v1.md`](docs/schema/v1.md) with a JSON Schema and exported TypeScript types (`import type { LoupeReport } from '@qartisan/playwright-loupe'`):
+  - stable test ids (project + file + title path), identical across sharded, merged and unsharded runs;
+  - run metadata: status, duration, Playwright version, git commit and branch, CI detection (GitHub Actions, GitLab, Azure Pipelines, CircleCI, Jenkins, Bitbucket, Buildkite, Travis), environment name, shard, workers;
+  - run scope (`full` | `partial`) with the reasons it was detected (file filter, grep, project filter, last-failed, `--only-changed`, `test.only`, `LOUPE_RUN_SCOPE`, and others);
+  - every attempt of every test (retries included), each with its errors, steps, annotations, stdout/stderr and attachments; screenshot comparisons are linked as expected / actual / diff;
+  - normalized error signatures that group the same failure across tests and runs (ANSI codes, call log, UUIDs, URLs, dates, paths, durations, hex strings and numbers removed or replaced);
+  - fields reserved for phase 2: `run.excluded` (always `null` in v1) and `notes` (always empty in v1).
+- **Run errors** (`run.errors`): errors reported outside any test (a spec file that fails to load, a failing global setup or teardown, a worker fixture failing in teardown), with location, signature and category. A run with zero tests still produces a valid report. Run errors survive `merge-reports`; the `(<tags>) ` prefix `merge-reports` adds for a shard config with a `tag` is ignored by signatures and category rules.
+- **Configuration**: `loupe.config.ts` (or `.mts`, `.js`, `.mjs`) next to `playwright.config.ts`, typed with `defineConfig()`, loaded through Playwright's own TypeScript transform. Options can also be passed inline in the reporter entry and through `LOUPE_*` environment variables (precedence: defaults < config file < inline options < environment variables). The config is validated at startup: an invalid option or an unknown key stops the run with an explicit message. See [`docs/config.md`](docs/config.md).
+- **Error categories**: ordered regex rules matched on the message, stack or failing step titles; built-in rules (locator not found, network, assertion, timeout); `extend` or `replace` mode; a visible uncategorized bucket.
+- **Dimensions**: automatic dimensions from prefixed tags (`@layer:api`), and configured dimensions from tags or annotations (`{ type: 'bug', description: 'BUG-1' }`), with optional expected values.
+- **Minimal HTML renderer**: a self-contained page with the run summary (status, counts, duration, scope, environment, commit) and the tests grouped by project and suite. Renderer settings: `title`, `theme`, `screenshots.defaultView`. The full dashboard and test details come in later releases.
+
+### Compatibility
+
+- Node.js **22.12 or later** (`engines.node`), needed to load ES module config files. CI tests the latest Node.js 22.x and 24.x.
+- `@playwright/test` **1.52 or later** (peer dependency). CI tests 1.52 (on Node.js 22) and the latest version. Playwright 1.52 hangs on recent Node.js 24 releases, independently of Loupe: see [Compatibility](README.md#compatibility).
+
+[Unreleased]: https://github.com/qartisan/playwright-loupe/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/qartisan/playwright-loupe/releases/tag/v0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gilles Capdivila
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# playwright-loupe
+Loupe — an HTML reporter for Playwright: run summary, tests grouped by project and suite, dimensions from tags and annotations, and detailed failures with every attempt, error categories and signatures. Native Playwright APIs only.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Status: work in progress — the JSON schema will change before 1.0.**
+
+Loupe is a reporter for Playwright, not affiliated with Microsoft.
+
+## Installation
+
+```sh
+npm install --save-dev @qartisan/playwright-loupe
+```
+
+Requires Node.js 22.12 or later and `@playwright/test` 1.52 or later. See [Compatibility](#compatibility).
+
+## Usage
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  reporter: [
+    ['list'],
+    ['@qartisan/playwright-loupe', { outputFolder: 'loupe-report', title: 'My suite' }],
+  ],
+});
+```
+
+After a run, open `loupe-report/index.html`. The raw data is in `loupe-report/report.json`, with attachments in `loupe-report/data/`. Its format is documented in [`docs/schema/v1.md`](docs/schema/v1.md), with a [JSON Schema](docs/schema/report-v1.schema.json) and TypeScript types (`import type { LoupeReport } from '@qartisan/playwright-loupe'`).
+
+Loupe requires `@playwright/test` 1.52 or later.
+
+A run that broke outside its tests (a spec file that fails to import, a failing global setup) is reported in `run.errors`, even when no test ran.
+
+## Configuration
+
+Put a `loupe.config.ts` next to `playwright.config.ts`:
+
+```ts
+// loupe.config.ts
+import { defineConfig } from '@qartisan/playwright-loupe';
+
+export default defineConfig({
+  title: 'My suite',
+  categories: {
+    rules: [{ name: 'Infra', match: [/ECONNRESET/, /ECONNREFUSED/] }],
+  },
+  dimensions: {
+    definitions: [
+      { name: 'Layer', from: 'tag', prefix: 'layer', values: ['api', 'ui', 'e2e'] },
+      { name: 'Bug', from: 'annotation', type: 'bug' },
+    ],
+  },
+});
+```
+
+Options can also be passed inline (`['@qartisan/playwright-loupe', { title: 'Nightly' }]`) and through `LOUPE_*` environment variables. Precedence: defaults < config file < inline options < environment variables. The config is validated at startup: an invalid option, or a typo in a key, stops the run with an explicit message.
+
+Every option, the lookup rules and the environment variables are documented in [`docs/config.md`](docs/config.md).
+
+## Compatibility
+
+| | Supported | Tested in CI |
+| --- | --- | --- |
+| Node.js | 22.12 or later | latest 22.x and 24.x |
+| `@playwright/test` | 1.52 or later | 1.52 (on Node.js 22) and the latest version |
+
+Node.js 22.12 is the minimum because ES module config files are loaded with `require(esm)`, see [`docs/config.md`](docs/config.md#how-config-files-are-loaded).
+
+> **Playwright 1.52 hangs on recent Node.js 24 releases.** `playwright test` never exits, even for a single passing test with the built-in `list` reporter and without Loupe: this is not caused by Loupe. Reproduced with Node.js 24.17.0; Node.js 24.11.1 is not affected, nor is Playwright 1.53 or later on Node.js 24.17.0. With Playwright 1.52, use Node.js 22, or upgrade Playwright.
+
+## Development
+
+| Command | What it does |
+| --- | --- |
+| `npm run build` | Builds the reporter (`dist/`) and the self-contained renderer template (`dist/renderer/index.html`). |
+| `npm run typecheck` | Type-checks the core, tests, fixtures and renderer. |
+| `npm test` | Builds, then runs the Vitest unit tests and the integration tests (fixture suite, and a sharded run merged with `merge-reports`). |
+| `npm run fixtures` | Builds, then runs the fixture suite into `loupe-report/`. Its failures are intentional, see [`fixtures/README.md`](fixtures/README.md). |
+| `npm run sample:update` | Runs the fixture suite and copies its report to `src/renderer/dev/sample.json`. |
+| `npm run dev:renderer` | Vite dev server for the renderer, fed with `src/renderer/dev/sample.json`, with hot reload. |
+
+Tests that drive a browser need Chromium: `npx playwright install chromium`.

package/dist/config/define.d.ts

@@ -0,0 +1,3 @@
+import type { LoupeConfig } from './types.js';
+/** Typed identity helper for `loupe.config.ts` and inline reporter options. */
+export declare function defineConfig(config: LoupeConfig): LoupeConfig;

package/dist/config/define.js

@@ -0,0 +1,4 @@
+/** Typed identity helper for `loupe.config.ts` and inline reporter options. */
+export function defineConfig(config) {
+    return config;
+}

package/dist/config/index.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedConfig } from './types.js';
+export type * from './types.js';
+export { defineConfig } from './define.js';
+export { LoupeConfigError } from './resolve.js';
+/**
+ * Finds, loads, validates and merges the Loupe config for a reporter instance.
+ * `options` are the raw reporter options, including the keys Playwright adds:
+ * `configDir` is the directory of the Playwright config file (of the merge
+ * config under `merge-reports`, the working directory when there is none).
+ */
+export declare function loadConfig(options: Record<string, unknown>, env?: Readonly<Record<string, string | undefined>>, cwd?: string): ResolvedConfig;

package/dist/config/index.js

@@ -0,0 +1,23 @@
+import { CONFIG_ENV, findConfigFile, loadConfigFile } from './load.js';
+import { resolveConfig, stripPlaywrightKeys } from './resolve.js';
+export { defineConfig } from './define.js';
+export { LoupeConfigError } from './resolve.js';
+/**
+ * Finds, loads, validates and merges the Loupe config for a reporter instance.
+ * `options` are the raw reporter options, including the keys Playwright adds:
+ * `configDir` is the directory of the Playwright config file (of the merge
+ * config under `merge-reports`, the working directory when there is none).
+ */
+export function loadConfig(options, env = process.env, cwd = process.cwd()) {
+    const baseDir = typeof options['configDir'] === 'string' ? options['configDir'] : cwd;
+    const inline = stripPlaywrightKeys(options);
+    const optionPath = typeof inline['configFile'] === 'string' ? inline['configFile'] : undefined;
+    const file = findConfigFile({ baseDir, cwd, envPath: env[CONFIG_ENV], optionPath });
+    return resolveConfig({
+        file: file ? { path: file, config: loadConfigFile(file) } : undefined,
+        inline,
+        env,
+        baseDir,
+        cwd,
+    });
+}

package/dist/config/load.d.ts

@@ -0,0 +1,30 @@
+/** Looked up in this order in the directory of the Playwright config file. */
+export declare const CONFIG_FILE_NAMES: readonly ['loupe.config.ts', 'loupe.config.mts', 'loupe.config.js', 'loupe.config.mjs'];
+export declare const CONFIG_ENV = "LOUPE_CONFIG";
+/**
+ * Path of the config file to load, or null when there is none.
+ *
+ * - `LOUPE_CONFIG` (relative to the working directory) wins over the
+ *   `configFile` reporter option (relative to the Playwright config's
+ *   directory). An explicit file that does not exist is an error.
+ * - Otherwise the first of CONFIG_FILE_NAMES found in `baseDir`.
+ */
+export declare function findConfigFile(options: {
+    baseDir: string;
+    cwd: string;
+    envPath: string | undefined;
+    optionPath: string | undefined;
+}): string | null;
+/**
+ * Loads a config file synchronously and returns its default export.
+ *
+ * Synchronous on purpose: the reporter constructor is the only place where an
+ * error stops the run (Playwright does not await `onBegin`). TypeScript works
+ * because Playwright has installed its own transform (Babel) before it builds
+ * any non-built-in reporter: `require()` of a `.ts` / `.mts` file outside
+ * `node_modules` goes through it, in normal runs and in `merge-reports`. ESM
+ * output is loaded through Node's `require(esm)` (Node 22.12+), so a config
+ * file cannot use top-level `await`. See "How config files are loaded" in
+ * docs/config.md.
+ */
+export declare function loadConfigFile(file: string): unknown;

package/dist/config/load.js

@@ -0,0 +1,78 @@
+import { existsSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { LoupeConfigError } from './resolve.js';
+/** Looked up in this order in the directory of the Playwright config file. */
+export const CONFIG_FILE_NAMES = ['loupe.config.ts', 'loupe.config.mts', 'loupe.config.js', 'loupe.config.mjs'];
+export const CONFIG_ENV = 'LOUPE_CONFIG';
+const require = createRequire(import.meta.url);
+/**
+ * Path of the config file to load, or null when there is none.
+ *
+ * - `LOUPE_CONFIG` (relative to the working directory) wins over the
+ *   `configFile` reporter option (relative to the Playwright config's
+ *   directory). An explicit file that does not exist is an error.
+ * - Otherwise the first of CONFIG_FILE_NAMES found in `baseDir`.
+ */
+export function findConfigFile(options) {
+    const envPath = options.envPath?.trim();
+    const explicit = envPath
+        ? { file: path.resolve(options.cwd, envPath), from: `${CONFIG_ENV}=${envPath}` }
+        : options.optionPath
+            ? { file: path.resolve(options.baseDir, options.optionPath), from: `reporter option configFile: "${options.optionPath}"` }
+            : null;
+    if (explicit) {
+        if (!existsSync(explicit.file) || !statSync(explicit.file).isFile()) {
+            throw new LoupeConfigError([`${explicit.from}: config file not found at ${explicit.file}`]);
+        }
+        return explicit.file;
+    }
+    for (const name of CONFIG_FILE_NAMES) {
+        const file = path.join(options.baseDir, name);
+        if (existsSync(file))
+            return file;
+    }
+    return null;
+}
+/**
+ * Loads a config file synchronously and returns its default export.
+ *
+ * Synchronous on purpose: the reporter constructor is the only place where an
+ * error stops the run (Playwright does not await `onBegin`). TypeScript works
+ * because Playwright has installed its own transform (Babel) before it builds
+ * any non-built-in reporter: `require()` of a `.ts` / `.mts` file outside
+ * `node_modules` goes through it, in normal runs and in `merge-reports`. ESM
+ * output is loaded through Node's `require(esm)` (Node 22.12+), so a config
+ * file cannot use top-level `await`. See "How config files are loaded" in
+ * docs/config.md.
+ */
+export function loadConfigFile(file) {
+    let loaded;
+    try {
+        // A long-lived process (watch mode, UI mode) reloads CommonJS output; ES modules stay cached by Node.
+        delete require.cache[file];
+        loaded = require(file);
+    }
+    catch (error) {
+        const code = error.code;
+        const hint = code === 'ERR_REQUIRE_ASYNC_MODULE'
+            ? ' A Loupe config file cannot use top-level await.'
+            : code === 'ERR_REQUIRE_ESM'
+                ? ' Loading an ES module config needs Node.js 22.12 or later.'
+                : code === 'ERR_UNKNOWN_FILE_EXTENSION'
+                    ? ' TypeScript config files are loaded through Playwright: use the reporter through `playwright test` or `playwright merge-reports`.'
+                    : '';
+        const message = error instanceof Error ? error.message.split('\n')[0] : String(error);
+        throw new LoupeConfigError([`${path.basename(file)}: cannot be loaded: ${message}.${hint}`]);
+    }
+    return defaultExport(loaded);
+}
+/** Unwraps the default export of an ES module namespace or of Babel's CommonJS interop; CommonJS exports are used as is. */
+function defaultExport(loaded) {
+    if (loaded !== null && typeof loaded === 'object') {
+        const module = loaded;
+        if (module.__esModule === true || module[Symbol.toStringTag] === 'Module')
+            return module.default;
+    }
+    return loaded;
+}

package/dist/config/resolve.d.ts

@@ -0,0 +1,50 @@
+import type { LoupeConfig, ResolvedConfig } from './types.js';
+type Env = Readonly<Record<string, string | undefined>>;
+export declare const DEFAULT_OUTPUT_FOLDER = "loupe-report";
+export declare const DEFAULT_TITLE = "Loupe report";
+export declare const DEFAULT_UNCATEGORIZED = "Uncategorized";
+/** Environment variables mapped onto config options. `LOUPE_CONFIG` and `LOUPE_RUN_SCOPE` are handled apart. */
+export declare const ENV_OPTIONS: {
+    readonly LOUPE_OUTPUT_FOLDER: 'outputFolder';
+    readonly LOUPE_TITLE: 'title';
+    readonly LOUPE_ENV: 'environment';
+};
+/** Thrown for any invalid configuration; the message lists every problem. */
+export declare class LoupeConfigError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/**
+ * Playwright adds its own keys to every reporter's options: `configDir`, and
+ * internal ones starting with `_` (`_mode`, `_commandHash`, `_isTestServer`).
+ * They are not Loupe options and are removed before validation.
+ */
+export declare function stripPlaywrightKeys(options: Record<string, unknown>): Record<string, unknown>;
+/** The environment layer: options set through `LOUPE_*` variables. Empty variables are ignored. */
+export declare function envLayer(env: Env): LoupeConfig;
+/**
+ * Merges `layer` over `base`: nested objects (`categories`, `dimensions`,
+ * `screenshots`) merge key by key; arrays and other values replace. An
+ * `undefined` value leaves the base untouched.
+ */
+export declare function mergeLayers<T extends object>(base: T, layer: object): T;
+export interface ConfigLayers {
+    /** Contents of the config file, unvalidated; undefined when there is none. */
+    file?: {
+        path: string;
+        config: unknown;
+    } | undefined;
+    /** Inline reporter options, Playwright's own keys already removed. */
+    inline: Record<string, unknown>;
+    env: Env;
+    /** Directory relative options are resolved from: the Playwright config's directory. */
+    baseDir: string;
+    cwd: string;
+}
+/**
+ * Validates each layer, then merges them: defaults < config file < inline
+ * options < environment variables. Throws a LoupeConfigError listing every
+ * problem of every layer.
+ */
+export declare function resolveConfig(layers: ConfigLayers): ResolvedConfig;
+export {};

package/dist/config/resolve.js

@@ -0,0 +1,116 @@
+import path from 'node:path';
+import { validateConfig } from './validate.js';
+export const DEFAULT_OUTPUT_FOLDER = 'loupe-report';
+export const DEFAULT_TITLE = 'Loupe report';
+export const DEFAULT_UNCATEGORIZED = 'Uncategorized';
+/** Environment variables mapped onto config options. `LOUPE_CONFIG` and `LOUPE_RUN_SCOPE` are handled apart. */
+export const ENV_OPTIONS = {
+    LOUPE_OUTPUT_FOLDER: 'outputFolder',
+    LOUPE_TITLE: 'title',
+    LOUPE_ENV: 'environment',
+};
+/** Thrown for any invalid configuration; the message lists every problem. */
+export class LoupeConfigError extends Error {
+    problems;
+    constructor(problems) {
+        super(`Loupe: invalid configuration.\n${problems.map((problem) => `  - ${problem}`).join('\n')}`);
+        this.problems = problems;
+        this.name = 'LoupeConfigError';
+    }
+}
+/**
+ * Playwright adds its own keys to every reporter's options: `configDir`, and
+ * internal ones starting with `_` (`_mode`, `_commandHash`, `_isTestServer`).
+ * They are not Loupe options and are removed before validation.
+ */
+export function stripPlaywrightKeys(options) {
+    return Object.fromEntries(Object.entries(options).filter(([key]) => key !== 'configDir' && !key.startsWith('_')));
+}
+/** Non-empty value of an environment variable, trimmed; undefined otherwise. */
+function envValue(env, name) {
+    const value = env[name]?.trim();
+    return value ? value : undefined;
+}
+/** The environment layer: options set through `LOUPE_*` variables. Empty variables are ignored. */
+export function envLayer(env) {
+    const layer = {};
+    for (const [variable, option] of Object.entries(ENV_OPTIONS)) {
+        const value = envValue(env, variable);
+        if (value !== undefined)
+            layer[option] = value;
+    }
+    return layer;
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof RegExp);
+}
+/**
+ * Merges `layer` over `base`: nested objects (`categories`, `dimensions`,
+ * `screenshots`) merge key by key; arrays and other values replace. An
+ * `undefined` value leaves the base untouched.
+ */
+export function mergeLayers(base, layer) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(layer)) {
+        if (value === undefined)
+            continue;
+        const current = result[key];
+        result[key] = isObject(current) && isObject(value) ? mergeLayers(current, value) : value;
+    }
+    return result;
+}
+/** Copies a pattern without the stateful `g` and `y` flags, so `test()` gives the same answer every time. */
+function stateless(pattern) {
+    return pattern.global || pattern.sticky ? new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, '')) : pattern;
+}
+function resolveRules(config) {
+    return (config.categories?.rules ?? []).map((rule) => ({
+        name: rule.name,
+        match: (Array.isArray(rule.match) ? rule.match : [rule.match]).map(stateless),
+        on: rule.on ?? 'all',
+        color: rule.color ?? null,
+    }));
+}
+function resolveDimensions(config) {
+    return (config.dimensions?.definitions ?? []).map((definition) => definition.from === 'tag'
+        ? { name: definition.name, from: 'tag', prefix: definition.prefix, values: definition.values ? [...definition.values] : null }
+        : { name: definition.name, from: 'annotation', type: definition.type, values: definition.values ? [...definition.values] : null });
+}
+/**
+ * Validates each layer, then merges them: defaults < config file < inline
+ * options < environment variables. Throws a LoupeConfigError listing every
+ * problem of every layer.
+ */
+export function resolveConfig(layers) {
+    const fileSource = layers.file ? path.basename(layers.file.path) : '';
+    const env = envLayer(layers.env);
+    const problems = [
+        ...(layers.file ? validateConfig(layers.file.config, fileSource) : []),
+        ...validateConfig(layers.inline, 'reporter options', { allowConfigFile: true }),
+    ];
+    if (problems.length > 0)
+        throw new LoupeConfigError(problems);
+    const { configFile: _configFile, ...inline } = layers.inline;
+    const merged = mergeLayers(mergeLayers((layers.file?.config ?? {}), inline), env);
+    const uncategorized = merged.categories?.uncategorized ?? DEFAULT_UNCATEGORIZED;
+    const rules = resolveRules(merged);
+    if (rules.some((rule) => rule.name === uncategorized)) {
+        throw new LoupeConfigError([
+            `merged config: categories.uncategorized "${uncategorized}" is also the name of a rule; use a name no rule uses`,
+        ]);
+    }
+    // LOUPE_OUTPUT_FOLDER is relative to the working directory, like Playwright's own *_OUTPUT_DIR variables.
+    const outputFolder = env.outputFolder !== undefined
+        ? path.resolve(layers.cwd, env.outputFolder)
+        : path.resolve(layers.baseDir, merged.outputFolder ?? DEFAULT_OUTPUT_FOLDER);
+    return {
+        configFile: layers.file?.path ?? null,
+        outputFolder,
+        title: merged.title ?? DEFAULT_TITLE,
+        environment: merged.environment ?? null,
+        categories: { mode: merged.categories?.mode ?? 'extend', rules, uncategorized },
+        dimensions: { auto: merged.dimensions?.auto ?? true, definitions: resolveDimensions(merged) },
+        screenshots: { defaultView: merged.screenshots?.defaultView ?? 'side-by-side' },
+        theme: merged.theme ?? 'system',
+    };
+}

package/dist/config/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Loupe configuration, as written in `loupe.config.ts` or passed inline as
+ * reporter options. Every option is optional; see docs/config.md.
+ */
+export declare const CATEGORY_MODES: readonly ['extend', 'replace'];
+export type CategoryMode = (typeof CATEGORY_MODES)[number];
+export declare const CATEGORY_TARGETS: readonly ['message', 'stack', 'step', 'all'];
+export type CategoryTarget = (typeof CATEGORY_TARGETS)[number];
+export declare const SCREENSHOT_VIEWS: readonly ['side-by-side', 'slider', 'overlay', 'diff'];
+export type ScreenshotView = (typeof SCREENSHOT_VIEWS)[number];
+export declare const THEMES: readonly ['system', 'light', 'dark'];
+export type Theme = (typeof THEMES)[number];
+export interface CategoryRuleConfig {
+    /** Category name. Several rules may share a name. */
+    name: string;
+    /** One pattern or a list; the rule matches when any pattern matches. */
+    match: RegExp | RegExp[];
+    /** What the patterns are tested against. Default: `'all'`. */
+    on?: CategoryTarget;
+    /** `#rrggbb`. Default: a color from Loupe's palette. */
+    color?: string;
+}
+export interface CategoriesConfig {
+    /** `extend` (default): rules run before the built-in ones. `replace`: built-in rules are dropped. */
+    mode?: CategoryMode;
+    rules?: CategoryRuleConfig[];
+    /** Name of the bucket for errors no rule matches. Default: `Uncategorized`. */
+    uncategorized?: string;
+}
+export interface TagDimensionConfig {
+    name: string;
+    from: 'tag';
+    /** Tag prefix, without `@` and `:`: `layer` for `@layer:api`. */
+    prefix: string;
+    /** Expected values. */
+    values?: string[];
+}
+export interface AnnotationDimensionConfig {
+    name: string;
+    from: 'annotation';
+    /** Annotation type; the annotation description is the value. */
+    type: string;
+    /** Expected values. */
+    values?: string[];
+}
+export type DimensionConfig = TagDimensionConfig | AnnotationDimensionConfig;
+export interface DimensionsConfig {
+    /** Keep the automatic dimensions built from prefixed tags. Default: `true`. */
+    auto?: boolean;
+    definitions?: DimensionConfig[];
+}
+export interface LoupeConfig {
+    /** Folder the report is written to, relative to the Playwright config file. Default: `loupe-report`. */
+    outputFolder?: string;
+    /** Report title. Default: `Loupe report`. */
+    title?: string;
+    /** Environment name written to `run.environment.name`. `LOUPE_ENV` overrides it. */
+    environment?: string;
+    categories?: CategoriesConfig;
+    dimensions?: DimensionsConfig;
+    screenshots?: {
+        /** Default comparison view in the test detail. Default: `side-by-side`. */
+        defaultView?: ScreenshotView;
+    };
+    /** Default theme of the report. Default: `system`. */
+    theme?: Theme;
+}
+/** Inline reporter options: a config, plus the path of the config file. */
+export interface LoupeReporterOptions extends LoupeConfig {
+    /** Config file to load instead of the default lookup, relative to the Playwright config file. */
+    configFile?: string;
+}
+/** A category rule with defaults applied; patterns never carry the `g` or `y` flag. */
+export interface ResolvedCategoryRule {
+    name: string;
+    match: RegExp[];
+    on: CategoryTarget;
+    color: string | null;
+}
+export type ResolvedDimension = {
+    name: string;
+    from: 'tag';
+    prefix: string;
+    values: string[] | null;
+} | {
+    name: string;
+    from: 'annotation';
+    type: string;
+    values: string[] | null;
+};
+/** The config after defaults and every layer are applied. */
+export interface ResolvedConfig {
+    /** Absolute path of the loaded config file, null when none. */
+    configFile: string | null;
+    /** Absolute. */
+    outputFolder: string;
+    title: string;
+    environment: string | null;
+    categories: {
+        mode: CategoryMode;
+        rules: ResolvedCategoryRule[];
+        uncategorized: string;
+    };
+    dimensions: {
+        auto: boolean;
+        definitions: ResolvedDimension[];
+    };
+    screenshots: {
+        defaultView: ScreenshotView;
+    };
+    theme: Theme;
+}

package/dist/config/types.js

@@ -0,0 +1,8 @@
+/**
+ * Loupe configuration, as written in `loupe.config.ts` or passed inline as
+ * reporter options. Every option is optional; see docs/config.md.
+ */
+export const CATEGORY_MODES = ['extend', 'replace'];
+export const CATEGORY_TARGETS = ['message', 'stack', 'step', 'all'];
+export const SCREENSHOT_VIEWS = ['side-by-side', 'slider', 'overlay', 'diff'];
+export const THEMES = ['system', 'light', 'dark'];

package/dist/config/validate.d.ts

@@ -0,0 +1,11 @@
+/** Optimal string alignment distance: Levenshtein plus adjacent transpositions (`titel` → `title` is 1). */
+export declare function editDistance(a: string, b: string): number;
+/** The closest known key, when it is close enough to be a typo. */
+export declare function suggestKey(key: string, known: readonly string[]): string | null;
+/**
+ * Validates one config layer. `source` names it in messages (`loupe.config.ts`,
+ * `reporter options`). `configFile` is only accepted in inline options.
+ */
+export declare function validateConfig(value: unknown, source: string, options?: {
+    allowConfigFile?: boolean;
+}): string[];