# Maintainers Guide

This document contains procedures exclusive to project maintainers. Community contributions that modify baselines or reference configurations will not be accepted.

## Quick Reference

### Scripts

| Script                           | Description                                      |
| -------------------------------- | ------------------------------------------------ |
| `npm run vrt:generate-reference` | Clone & build official KERN-UX Storybook         |
| `npm run vrt:baseline`           | Capture baselines from KERN-UX reference         |
| `npm run vrt:clean`              | Remove all VRT artifacts                         |

### Key Files

| File | Purpose |
| ---- | ------- |
| [package.json](package.json) | `@kern-ux/native` version (CSS build) |
| [scripts/generate-reference-storybook.ts](scripts/generate-reference-storybook.ts) | VRT reference branch/tag config |
| [tests/vrt/component-mapping.ts](tests/vrt/component-mapping.ts) | Maps Drupal SDC → KERN-UX story IDs |
| [playwright.config.ts](playwright.config.ts) | VRT settings (thresholds, themes) |

## Common Tasks

### First-Time Setup

```bash
npm install && npx playwright install
npm run vrt:generate-reference
npm run vrt:baseline
npm run vrt
```

### Updating KERN-UX Version

> **Important:** Both versions must be pinned and kept in sync. Using semver ranges (e.g., `^2.3.2`) would cause CSS to drift ahead of the VRT reference, resulting in false test failures.

Update **both** files to the same version:

1. `package.json` → `"@kern-ux/native": "X.Y.Z"` (no caret)
2. `scripts/generate-reference-storybook.ts` → `branch: "vX.Y.Z"`

Then run:

```bash
npm install && npm run build
npm run vrt:generate-reference
npm run vrt:baseline
npm run vrt
```

Submit updated baselines for internal review.

### Adding New Component Mappings

1. Find Drupal SDC story ID from `storybook-static/index.json`
2. Find KERN-UX story ID from `tests/vrt/reference-storybook/index.json`
3. Add mapping to `tests/vrt/component-mapping.ts`
4. Run `npm run vrt:baseline` and `npm run vrt`

### Viewing Reference Storybook

```bash
npx serve tests/vrt/reference-storybook -l 6008 --cors
# Open http://localhost:6008
```

## Reference Storybook Details

The `npm run vrt:generate-reference` script:
- Clones official `kern-ux-plain` repository
- Builds and copies Storybook to `tests/vrt/reference-storybook/`
- Auto-patches CSS injection and dark mode theme handling
- Records version in `reference-metadata.json`

The reference Storybook is `.gitignore`d and can be regenerated anytime.

## Troubleshooting

### Corrupted Baselines (1px tall or empty)

CSS not loading. Run `npm run vrt:generate-reference` to regenerate with auto-patched CSS.

### Dark Mode Shows Light Theme

Theme script not patched. Run `npm run vrt:generate-reference` to regenerate with auto-patched theme handling.

**Manual fallback** (if auto-patch fails): See `scripts/reference-storybook-css-fix.patch` or manually edit `tests/vrt/reference-storybook/iframe.html`.

## Directory Structure

```
scripts/
├── generate-reference-storybook.ts   # Builds & patches reference Storybook
└── reference-storybook-css-fix.patch # Manual fallback patch

tests/vrt/
├── vrt.spec.ts                       # Main test file
├── component-mapping.ts              # Drupal → KERN-UX mapping
├── reference-storybook/              # Generated (gitignored)
└── snapshots/                        # Baselines (git tracked)
```
