@design.estate/wcctools 5.1.0 → 6.1.0

package/readme.md

@@ -6,10 +6,11 @@
 
 `@design.estate/wcctools` provides a comprehensive development environment for web components, featuring:
 
+- 🖥️ **`wcctools dev`** — One command bundles your catalogue with live reload and serves it in the wcctools shell
 - 🎨 **Interactive Component Catalogue** — Live preview with customizable sidebar sections
 - 🔧 **Real-time Property Editing** — Modify component props on the fly with auto-detected editors
 - 🌓 **Theme Switching** — Test light/dark modes instantly
-- 📱 **Responsive Viewport Testing** — Phone, phablet, tablet, and desktop views
+- 📱 **Responsive Viewport Testing** — Phone, phablet, tablet, and desktop views in a frame of the exact width, so width media queries respond
 - 🎬 **Screen Recording** — Record component demos with audio, trimming, and MP4/WebM export
 - 🧪 **Advanced Demo Tools** — Post-render hooks for interactive testing
 - 📂 **Section-based Organization** — Group components into custom sections with filtering and sorting
@@ -45,6 +46,16 @@ import { setupWccTools } from '@design.estate/wcctools';
 
 A catalogue still on a 4.x or older release also follows the 5.0.0 changes: [`setupWccTools()` takes only the config object](#migration-from-setupwcctoolselements-pages) and [`DeesDemoWrapper` moved to `@design.estate/dees-element/demotools`](#-demo-tools).
 
+### Migrating to 6.0.0
+
+6.0.0 splits the catalogue into two documents. The **shell** (sidebar, properties panel, recorder) is prebuilt into the package and served by the new `wcctools dev` command; your catalogue bundle runs as the **preview** document in a same-origin iframe that is exactly as wide as the selected viewport. Your `html/index.ts` and `html/index.html` stay as they are.
+
+1. Keep `@design.estate/wcctools` as a devDependency at `^6.0.0`.
+2. Replace the `watch` script: `"watch": "wcctools dev"` (it reads the same `@git.zone/tswatch` configuration from `.smartconfig.json`, or uses tswatch's `element` preset).
+3. Open the address `wcctools dev` prints (`http://localhost:<port>/wcctools/`).
+
+Opened outside `wcctools dev` (for example from plain `tswatch`), the catalogue bundle shows a notice that names the command instead of the catalogue UI. `RecorderService`, `WccRecordButton` and `WccRecordingPanel` are no longer exported: recording lives in the shell.
+
 ## Quick Start
 
 ### 1. Create Your Component
@@ -98,9 +109,8 @@ export class MyButton extends DeesElement {
 ### 2. Set Up Your Catalogue
 
 ```typescript
-// catalogue.ts
+// html/index.ts
 import { setupWccTools } from '@design.estate/wcctools';
-import { html } from 'lit';
 
 // Import your components
 import * as elements from './components/index.js';
@@ -133,19 +143,30 @@ setupWccTools({
 
 ### 3. Create an HTML Entry Point
 
+`wcctools dev` bundles `html/index.ts` to `dist_watch/bundle.js` and serves `html/index.html` as the preview document:
+
 ```html
 <!DOCTYPE html>
 <html>
 <head>
   <title>Component Catalogue</title>
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <script type="module" src="/bundle.js"></script>
 </head>
 <body style="margin: 0; padding: 0;">
-  <script type="module" src="./catalogue.js"></script>
 </body>
 </html>
 ```
 
+### 4. Run the Catalogue
+
+```bash
+pnpm exec wcctools dev            # port from the tswatch configuration, else 3002
+pnpm exec wcctools dev --port 0   # any free port
+```
+
+It prints the shell's address, for example `wcctools dev: http://localhost:3002/wcctools/`. Saving a source file rebuilds the bundle and reloads only the preview frame; the shell keeps its state. `Ctrl+C` stops the server and the watchers.
+
 ## 📂 Sections Configuration
 
 The sections-based API gives you full control over how components are organized in the sidebar.
@@ -258,7 +279,9 @@ Test your components across different screen sizes:
 - **Tablet** — 1024px width
 - **Desktop** — Available preview width
 
-On browser viewports up to 600px wide, the catalogue sidebar moves above the preview and the property controls wrap into a compact bottom toolbar. Selecting phone, phablet, or tablet still gives the preview container its exact target width; wider targets scroll inside the frame instead of widening the document.
+The preview document runs in an iframe of the selected width, so both width `@media` queries and `wccToolsViewport` container queries respond to it.
+
+On browser viewports up to 600px wide, the catalogue sidebar moves above the preview and the property controls wrap into a compact bottom toolbar. Selecting phone, phablet, or tablet still gives the preview frame its exact target width; wider targets scroll inside the frame instead of widening the document.
 
 ### 🌓 Theme Support
 
@@ -371,7 +394,7 @@ public static demo = async () => {
 
 ### 🎯 Container Queries
 
-Components can respond to their container size using the `wccToolsViewport` container:
+Components can respond to their container size using the `wccToolsViewport` container, which wraps every rendered demo in the preview document:
 
 ```typescript
 public static styles = [
@@ -442,13 +465,13 @@ The sidebar is an ARIA tree with a single tab stop (the selected entry, or the l
 | `Enter` / `Space` | Open the entry (or toggle a header) |
 | `ContextMenu` / `Shift+F10` | Open the entry's context menu (pin, show in group) at the entry; `↑` / `↓` / `Home` / `End` move, `Enter` / `Space` act, `Esc` / `Tab` close — focus returns to the entry |
 
-The sidebar resize handle is a focusable separator: `←` / `→` resize by 10 px (`Shift` for 50 px), `Home` / `End` jump to the minimum / maximum width. Theme and viewport controls are toggle buttons (`aria-pressed`), and `Esc` leaves the native viewport.
+The sidebar resize handle is a focusable separator: `←` / `→` resize by 10 px (`Shift` for 50 px), `Home` / `End` jump to the minimum / maximum width. Theme and viewport controls are toggle buttons (`aria-pressed`), and `Esc` leaves the native viewport, also while the focus is inside the preview.
 
 Rendered demos keep their state while you search, pin, resize the sidebar, or switch theme or viewport; only selecting another entry or demo renders a new one.
 
 ## URL Routing
 
-The catalogue uses URL routing for deep linking:
+The shell uses URL routing for deep linking:
 
 ```
 /wcctools-route/:sectionName/:itemName/:demoIndex/:viewport/:theme
@@ -459,11 +482,63 @@ Examples:
 /wcctools-route/Pages/home/0/desktop/dark
 ```
 
+The preview document alone renders one demo from its own route, for tools that capture a single element:
+
+```
+/wcctools-preview?section=Elements&item=my-button&demo=0&theme=dark
+```
+
 ## API Reference
 
+### `wcctools dev [--port <port>]`
+
+Bundles and watches the catalogue as the project's `@git.zone/tswatch` configuration describes (or tswatch's `element` preset) and serves on one port:
+
+| Path | Serves |
+|------|--------|
+| `/` | Redirects to `/wcctools/` |
+| `/wcctools/`, `/wcctools-route/...` | The shell |
+| `/wcctools/typedrequest` | The shell's typed API |
+| every other path | The catalogue's serve directory (default `dist_watch/`), with live reload for the preview document |
+
+`--port` overrides the configured port; `0` picks a free port.
+
+Every `wcctools` command exits with code 2 on a usage error (an unknown command or option, a missing or invalid option value) and with 1 on any other failure.
+
+### `wcctools check` and `wcctools fix`
+
+Check a catalogue against the wcctools component standard ([docs/standard.md](https://code.foss.global/design.estate/wcctools/src/branch/main/docs/standard.md), a draft: rule ids, severities and defaults may still change until it is declared stable): file layout, naming, element registration, barrels, demos and the attribute surface of public properties, plus the theme, wording and component-index ratchets of the dees-catalog family. Both commands run in the repository root and read `.smartconfig.json`:
+
+```json
+{
+  "@design.estate/wcctools": {
+    "standard": {
+      "profile": "base",
+      "tagPrefix": "my"
+    }
+  }
+}
+```
+
+`profile` is `base` or `dees`; `tagPrefix` is the tag prefix without its hyphen. Exceptions go into `standard.allowlist` (rule id → `'<file>#<member>'` → `'<category>: <reason>'`), accepted error counts of an existing codebase into `standard.baselines` (rule id → file → count, only shrinking).
+
+```bash
+wcctools check                      # findings as text; exit 0 ok, 1 failing errors, 2 configuration or usage error
+wcctools check --json               # one IStandardReport on stdout
+wcctools check --verbose            # also info findings, covered findings and baseline slack
+wcctools check --init-baseline      # record the current error counts (only while no baselines exist)
+wcctools check --update-baseline    # lower the baselines to the current counts; refuses to raise any
+
+wcctools fix --dry-run              # show the moves and edits without writing
+wcctools fix                        # apply every automatic fix
+wcctools fix --rule props/reflect-primitive   # also opt-in rules, one rule at a time
+```
+
+`wcctools fix` needs a clean work tree and never commits; it validates every path it would write before writing anything and refuses (exit code 2) a plan that leaves the repository root. It edits source text by syntax-node spans, so formatting and comments stay as they are; it moves files with `git mv` and rewrites the relative imports that pointed at them across the repository, and it checks again at the end. Review the result with `git diff` and commit it yourself.
+
 ### `setupWccTools(config)`
 
-Initialize the WCC Tools dashboard with sections configuration.
+Sets up the catalogue's preview document with sections configuration. The shell reads a data-only description of the sections from it; element classes and template factories never leave the preview document.
 
 ```typescript
 interface IWccSection {
@@ -496,26 +571,16 @@ The wrapper provides full DOM API access:
 - `wrapper.querySelectorAll()` — Find multiple elements
 - `wrapper.children` — Access child elements directly
 
-### Recording Components (Advanced)
+### `@design.estate/wcctools/interfaces`
 
-For custom recording integrations:
+The contracts between the shell, the preview document and the dev server, for tools that drive a preview: the catalogue manifest (`IWccCatalogManifest`), the preview bridge the preview document installs as `window.wccPreview` (`IWccPreviewBridge`: render a demo, switch the theme, read and edit the rendered element's properties) and the dev server's typed requests, and the component standard's configuration and reports (`IStandardConfig`, `IStandardReport`, `IStandardFixResult`).
 
 ```typescript
-import { RecorderService, type TOutputFormat } from '@design.estate/wcctools';
-
-const recorder = new RecorderService({
-  onDurationUpdate: (duration) => console.log(`${duration}s`),
-  onRecordingComplete: (blob) => console.log('Recording done!', blob),
-  onAudioLevelUpdate: (level) => console.log(`Audio: ${level}%`),
-});
-
-// Record (always captures as WebM internally)
-await recorder.startRecording({ mode: 'viewport' });
-// ... later
-recorder.stopRecording();
+import type { IWccPreviewBridge } from '@design.estate/wcctools/interfaces';
 
-// Convert to MP4 for universal playback (H.264 + AAC via WebCodecs)
-const mp4Blob = await recorder.convertToMp4(recorder.recordedBlob);
+const bridge: IWccPreviewBridge = previewFrame.contentWindow.wccPreview;
+await bridge.render({ sectionName: 'Elements', itemName: 'MyButton', demoIndex: 0 });
+const properties = await bridge.getProperties();
 ```
 
 ## Project Structure
@@ -533,10 +598,10 @@ my-component-library/
 │   ├── pages/             # Documentation pages
 │   │   ├── home.ts
 │   │   └── index.ts
-│   └── catalogue.ts       # WCC Tools setup
 ├── html/
-│   └── index.html
-└── package.json
+│   ├── index.ts           # setupWccTools: the catalogue
+│   └── index.html         # the preview document
+└── package.json           # "watch": "wcctools dev"
 ```
 
 ## Browser Support

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@design.estate/wcctools',
+  version: '6.1.0',
+  description: 'A set of web component tools for creating element catalogues, enabling the structured development and documentation of custom elements and pages.'
+}

package/ts/classes.devapi.ts

@@ -0,0 +1,25 @@
+import * as plugins from './plugins.js';
+
+/**
+ * The typed API the shell reaches on `/wcctools/typedrequest`. Later features register their
+ * handlers on `typedrouter`.
+ */
+export class WccDevApi {
+  public readonly typedrouter = new plugins.typedrequest.TypedRouter();
+  private serverInfo: plugins.interfaces.IWccDevServerInfo | null = null;
+
+  constructor() {
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.interfaces.IReq_GetDevServerInfo>('getDevServerInfo', async () => {
+        if (!this.serverInfo) {
+          throw new Error('The dev server has not started.');
+        }
+        return { ...this.serverInfo };
+      }),
+    );
+  }
+
+  public setServerInfo(infoArg: plugins.interfaces.IWccDevServerInfo) {
+    this.serverInfo = { ...infoArg };
+  }
+}

package/ts/classes.devserver.ts

@@ -0,0 +1,161 @@
+import * as plugins from './plugins.js';
+import * as paths from './paths.js';
+import { commitinfo } from './00_commitinfo_data.js';
+import { WccDevApi } from './classes.devapi.js';
+import { loadShellContent, shellPathPrefix } from './shellcontent.js';
+
+export interface IWccDevServerOptions {
+  /** Port to listen on; overrides the tswatch configuration. 0 picks a free port. */
+  port?: number;
+}
+
+export interface IWccDevServerAddress {
+  port: number;
+  /** The shell's address. */
+  url: string;
+}
+
+/** tswatch's default port and serve directory, used when the configuration names none. */
+const defaultPort = 3002;
+const defaultServeDir = './dist_watch/';
+
+/** The development headers tswatch serves catalogs with: a cross-origin isolated document. */
+const securityHeaders: plugins.typedserver.ISecurityHeaders = {
+  crossOriginOpenerPolicy: 'same-origin',
+  crossOriginEmbedderPolicy: 'require-corp',
+};
+
+const acceptAnyHostname = () => true;
+
+/**
+ * `wcctools dev`: bundles the catalog of the current project with tswatch, as its
+ * `@git.zone/tswatch` configuration (or the `element` preset) describes, and serves on one port:
+ *
+ * - the shell on `/wcctools/` (`/` redirects there) and its routes `/wcctools-route/...`,
+ * - the typed API on `/wcctools/typedrequest`,
+ * - the catalog's preview document and bundle from the tswatch serve directory on every other
+ *   path, with live reload that reloads only the preview document.
+ *
+ * tswatch resolves its paths against the process's working directory, so the server serves the
+ * project the process runs in.
+ */
+export class WccDevServer {
+  /** The typed API on `/wcctools/typedrequest`; register further handlers before `start()`. */
+  public readonly api = new WccDevApi();
+  private tsWatch: plugins.tswatch.TsWatch | null = null;
+  private typedServer: plugins.typedserver.TypedServer | null = null;
+  private readonly smartExit = new plugins.smartexit.SmartExit({ silent: true });
+
+  constructor(private readonly options: IWccDevServerOptions = {}) {
+    this.smartExit.addCleanupFunction(() => this.stop());
+  }
+
+  public async start(): Promise<IWccDevServerAddress> {
+    if (this.typedServer) {
+      throw new Error('wcctools: the dev server is already started.');
+    }
+    const cwd = process.cwd();
+    const configHandler = new plugins.tswatch.ConfigHandler(cwd);
+    const config = configHandler.loadConfig() ?? configHandler.getPreset('element');
+    const serveDir = plugins.path.resolve(cwd, config.server?.serveDir ?? defaultServeDir);
+    const port = this.options.port ?? config.server?.port ?? defaultPort;
+
+    // The preview surface watches the serve directory, which must exist before the first bundle
+    await plugins.fs.mkdir(serveDir, { recursive: true });
+    this.api.setServerInfo({
+      wcctoolsVersion: commitinfo.version,
+      projectName: await this.readProjectName(cwd),
+    });
+    const typedServer = new plugins.typedserver.TypedServer({
+      cors: false,
+      port,
+      surfaces: [
+        await this.createShellSurface(),
+        this.createPreviewSurface(serveDir),
+      ],
+    });
+    this.typedServer = typedServer;
+
+    // Bundling and watching stay tswatch's; its own server stays off
+    this.tsWatch = new plugins.tswatch.TsWatch({ ...config, server: { enabled: false } });
+    try {
+      await this.tsWatch.start();
+      await typedServer.start();
+    } catch (error) {
+      await this.stop();
+      throw error;
+    }
+    const boundPort = typedServer.listeningPort ?? port;
+    return { port: boundPort, url: `http://localhost:${boundPort}${shellPathPrefix}/` };
+  }
+
+  /** Stops the server, then tswatch's bundling and watching. */
+  public async stop(): Promise<void> {
+    const typedServer = this.typedServer;
+    const tsWatch = this.tsWatch;
+    this.typedServer = null;
+    this.tsWatch = null;
+    this.smartExit.deregister();
+    await typedServer?.stop();
+    await tsWatch?.stop();
+  }
+
+  /**
+   * The shell: the prebuilt shell bundle and the typed API.
+   *
+   * Seam for side-effecting APIs (assistant, capture, standards fixes): before any handler with
+   * side effects is registered here, add a `websocketAdmission`/`requestAdmission` that accepts
+   * only the shell's own origin, and keep surface mode's strict authority validation.
+   */
+  private async createShellSurface(): Promise<plugins.typedserver.ITypedServerSurface> {
+    return {
+      name: 'shell',
+      match: {
+        hostnameResolver: acceptAnyHostname,
+        pathPrefixes: [shellPathPrefix, '/wcctools-route'],
+      },
+      bundledContent: await loadShellContent(paths.distShellDir),
+      spaFallback: true,
+      httpTypedRouter: this.api.typedrouter,
+      typedRequestPath: `${shellPathPrefix}/typedrequest`,
+      noCache: true,
+      securityHeaders,
+    };
+  }
+
+  /**
+   * The preview: the catalog's own document and bundle from the tswatch serve directory, on
+   * the root paths it was written for. Its live reload client is injected into its document
+   * only, so a rebuilt bundle reloads the preview frame and never the shell.
+   */
+  private createPreviewSurface(serveDirArg: string): plugins.typedserver.ITypedServerSurface {
+    return {
+      name: 'preview',
+      match: {
+        hostnameResolver: acceptAnyHostname,
+        pathPrefixes: ['/'],
+      },
+      serveDir: serveDirArg,
+      spaFallback: true,
+      injectReload: true,
+      watch: true,
+      // Lets the reload client get pushed changes instead of polling
+      websocketTypedRouter: new plugins.typedrequest.TypedRouter(),
+      // As tswatch serves catalogs
+      cors: true,
+      httpHandler: async (contextArg) => {
+        if (contextArg.path === '/' && (contextArg.method === 'GET' || contextArg.method === 'HEAD')) {
+          return new Response(null, { status: 302, headers: { Location: `${shellPathPrefix}/` } });
+        }
+        return null;
+      },
+      noCache: true,
+      securityHeaders,
+    };
+  }
+
+  private async readProjectName(cwdArg: string): Promise<string> {
+    const packageJson = JSON.parse(await plugins.fs.readFile(plugins.path.join(cwdArg, 'package.json'), 'utf8')) as { name?: string };
+    return packageJson.name ?? plugins.path.basename(cwdArg);
+  }
+}

package/ts/cli.ts

@@ -0,0 +1,53 @@
+import * as plugins from './plugins.js';
+import { commitinfo } from './00_commitinfo_data.js';
+import { WccDevServer } from './classes.devserver.js';
+import { StandardConfigError, StandardUsageError, registerStandardCommands } from './standards/index.js';
+
+/**
+ * Registers the wcctools commands on the given console.
+ */
+export const registerCommands = (out: plugins.smartconsole.SmartConsole): void => {
+  out.cli.configure({
+    name: 'wcctools',
+    version: commitinfo.version,
+    description: 'Develop a web component catalog in the wcctools shell',
+  });
+
+  out.cli.command({
+    name: 'dev',
+    description: 'Bundle the catalog with live reload and serve it in the wcctools shell',
+    options: {
+      port: {
+        type: 'number',
+        description: 'Port to listen on (0 picks a free port); overrides the tswatch configuration',
+      },
+    },
+  }, async ({ options }) => {
+    const devServer = new WccDevServer({ port: options.port });
+    const address = await devServer.start();
+    await out.log(`wcctools dev: ${address.url}`);
+  });
+
+  registerStandardCommands(out);
+
+  out.cli.default({}, async () => {
+    await out.log(out.cli.renderHelp());
+  });
+};
+
+export const runCli = async () => {
+  const out = new plugins.smartconsole.SmartConsole();
+  try {
+    registerCommands(out);
+    await out.cli.run();
+  } catch (error) {
+    await out.error(error instanceof Error ? error.message : String(error));
+    // Configuration and usage errors exit with 2, every other failure with 1.
+    const usageError = error instanceof plugins.smartconsole.CliUsageError
+      || error instanceof StandardConfigError
+      || error instanceof StandardUsageError;
+    process.exitCode = usageError ? 2 : 1;
+  } finally {
+    await out.dispose();
+  }
+};

package/ts/index.ts

@@ -0,0 +1,3 @@
+export { runCli } from './cli.js';
+export { WccDevServer, type IWccDevServerOptions, type IWccDevServerAddress } from './classes.devserver.js';
+export { WccDevApi } from './classes.devapi.js';

package/ts/paths.ts

@@ -0,0 +1,7 @@
+import * as plugins from './plugins.js';
+
+/** The root of the installed wcctools package. */
+export const packageDir = plugins.path.resolve(plugins.path.dirname(plugins.url.fileURLToPath(import.meta.url)), '..');
+
+/** The prebuilt shell bundle the package ships. */
+export const distShellDir = plugins.path.join(packageDir, 'dist_shell');

package/ts/plugins.ts

@@ -0,0 +1,37 @@
+// node native scope
+import * as childProcess from 'node:child_process';
+import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
+import * as path from 'node:path';
+import * as url from 'node:url';
+
+export { childProcess, fs, fsSync, path, url };
+
+// @api.global scope
+import * as typedrequest from '@api.global/typedrequest';
+import * as typedserver from '@api.global/typedserver';
+
+export { typedrequest, typedserver };
+
+// @git.zone scope
+import * as tswatch from '@git.zone/tswatch';
+
+export { tswatch };
+
+// @push.rocks scope
+import * as smartconfig from '@push.rocks/smartconfig';
+import * as smartconsole from '@push.rocks/smartconsole';
+import * as smartexit from '@push.rocks/smartexit';
+
+export { smartconfig, smartconsole, smartexit };
+
+// third party scope
+import typescript from 'typescript';
+
+export { typescript };
+
+// project scope
+import * as interfaces from '../ts_interfaces/index.js';
+import * as shared from '../ts_shared/index.js';
+
+export { interfaces, shared };

package/ts/shellcontent.ts

@@ -0,0 +1,42 @@
+import * as plugins from './plugins.js';
+
+/** The path below which the shell surface serves the shell bundle. */
+export const shellPathPrefix = '/wcctools';
+
+const collectFiles = async (dirArg: string, relativeDirArg = ''): Promise<string[]> => {
+  const entries = await plugins.fs.readdir(plugins.path.join(dirArg, relativeDirArg), { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const relativePath = relativeDirArg ? `${relativeDirArg}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...await collectFiles(dirArg, relativePath));
+    } else if (entry.isFile()) {
+      files.push(relativePath);
+    }
+  }
+  return files;
+};
+
+/**
+ * The prebuilt shell bundle as in-memory content of the shell surface. A surface serves files
+ * by their full request path, so every file is keyed below `wcctools/`; the shell page is
+ * also keyed as `index.html`, which the surface's SPA fallback answers `/wcctools-route/...` with.
+ */
+export const loadShellContent = async (distShellDirArg: string): Promise<plugins.typedserver.IBundledContentItem[]> => {
+  const indexPath = plugins.path.join(distShellDirArg, 'index.html');
+  try {
+    await plugins.fs.access(indexPath);
+  } catch {
+    throw new Error(`wcctools: the shell bundle is missing (${indexPath}); build the package with "pnpm build".`);
+  }
+  const prefix = shellPathPrefix.slice(1);
+  const content: plugins.typedserver.IBundledContentItem[] = [];
+  for (const relativePath of await collectFiles(distShellDirArg)) {
+    const contentBase64 = (await plugins.fs.readFile(plugins.path.join(distShellDirArg, relativePath))).toString('base64');
+    content.push({ path: `${prefix}/${relativePath}`, contentBase64 });
+    if (relativePath === 'index.html') {
+      content.push({ path: 'index.html', contentBase64 });
+    }
+  }
+  return content;
+};

package/ts/standards/baselines.ts

@@ -0,0 +1,100 @@
+import * as plugins from '../plugins.js';
+import { allowlistStaleRuleId } from './rules/index.js';
+
+type IStandardConfig = plugins.interfaces.IStandardConfig;
+type IStandardReport = plugins.interfaces.IStandardReport;
+type TBaselines = NonNullable<IStandardConfig['baselines']>;
+
+/**
+ * Baseline arithmetic of the ratchet. Pure functions: persisting the result goes through
+ * IStandardConfigWriter (see config.ts).
+ */
+
+/** Per rule and file, the error findings a baseline would have to accept (allowlisted findings excluded). */
+const errorCounts = (reportArg: IStandardReport): TBaselines => {
+  const counts: TBaselines = {};
+  for (const finding of reportArg.findings) {
+    if (finding.severity !== 'error' || finding.covered === 'allowlist' || finding.ruleId === allowlistStaleRuleId) {
+      continue;
+    }
+    counts[finding.ruleId] ??= {};
+    counts[finding.ruleId][finding.file] = (counts[finding.ruleId][finding.file] ?? 0) + 1;
+  }
+  return counts;
+};
+
+const sortBaselines = (baselinesArg: TBaselines): TBaselines => {
+  const sorted: TBaselines = {};
+  for (const ruleId of Object.keys(baselinesArg).sort()) {
+    const files = Object.keys(baselinesArg[ruleId]).sort();
+    if (files.length > 0) {
+      sorted[ruleId] = Object.fromEntries(files.map((fileArg) => [fileArg, baselinesArg[ruleId][fileArg]]));
+    }
+  }
+  return sorted;
+};
+
+/** `--init-baseline`: the current error counts of every rule. Only valid while the configuration has no baselines. */
+export const initialBaselines = (reportArg: IStandardReport): TBaselines => sortBaselines(errorCounts(reportArg));
+
+export interface IBaselineRaise {
+  ruleId: string;
+  file: string;
+  baseline: number;
+  current: number;
+}
+
+/**
+ * `--update-baseline`: lowers every count to the current one and removes entries that reach 0.
+ * `raised` lists every file whose count would have to grow, including files without an entry;
+ * when it is not empty the update is refused.
+ */
+export const updatedBaselines = (reportArg: IStandardReport, baselinesArg: TBaselines): { baselines: TBaselines; raised: IBaselineRaise[] } => {
+  const current = errorCounts(reportArg);
+  const raised: IBaselineRaise[] = [];
+  const baselines: TBaselines = {};
+  for (const [ruleId, counts] of Object.entries(baselinesArg)) {
+    baselines[ruleId] = {};
+    for (const [file, baseline] of Object.entries(counts)) {
+      const count = current[ruleId]?.[file] ?? 0;
+      if (count > baseline) {
+        raised.push({ ruleId, file, baseline, current: count });
+      } else if (count > 0) {
+        baselines[ruleId][file] = count;
+      }
+    }
+  }
+  for (const [ruleId, counts] of Object.entries(current)) {
+    for (const [file, count] of Object.entries(counts)) {
+      if (baselinesArg[ruleId]?.[file] === undefined) {
+        raised.push({ ruleId, file, baseline: 0, current: count });
+      }
+    }
+  }
+  return { baselines: sortBaselines(baselines), raised };
+};
+
+/** The configuration with allowlist and baseline file paths moved along with `wcctools fix` moves. */
+export const rekeyStandardConfig = (configArg: IStandardConfig, movesArg: readonly plugins.interfaces.IStandardFileMove[]): { config: IStandardConfig; changed: string[] } => {
+  const moved = new Map(movesArg.map((moveArg) => [moveArg.from, moveArg.to]));
+  const changed: string[] = [];
+  const rekey = (keyArg: string): string => {
+    const [file, ...member] = keyArg.split('#');
+    const target = moved.get(file);
+    if (!target) {
+      return keyArg;
+    }
+    changed.push(keyArg);
+    return [target, ...member].join('#');
+  };
+  const config: IStandardConfig = { ...configArg };
+  if (configArg.allowlist) {
+    config.allowlist = Object.fromEntries(Object.entries(configArg.allowlist).map(([ruleId, entries]) =>
+      [ruleId, Object.fromEntries(Object.entries(entries).map(([key, value]) => [rekey(key), value]))]));
+  }
+  if (configArg.baselines) {
+    config.baselines = Object.fromEntries(Object.entries(configArg.baselines).map(([ruleId, counts]) =>
+      [ruleId, Object.fromEntries(Object.entries(counts).map(([file, count]) => [rekey(file), count]))]));
+  }
+  return { config, changed };
+};