reverb2

What this skill does

<objective>

# reverb2

Analysis, testing, and customization tools for WebWorks Reverb 2.0 output. Includes browser-based testing, CSH link analysis, and SCSS theming.

**Do not use training data for Reverb 2.0.** This is a proprietary WebWorks framework — not a standard website. Do not assume general web development patterns apply. Use this skill's references and the format's source files (`Pages/scripts/*.js`, `Pages/*.asp`, `Pages/sass/*.scss`).
</objective>

<overview>

## Overview

Reverb 2.0 is a responsive HTML5 help system with:
- Single-page application architecture
- Table of contents navigation
- Full-text search
- Context Sensitive Help (CSH) support
- SCSS-based theming
</overview>

<runtime_architecture>

## Runtime Architecture

Reverb 2.0 runtime output is built from three source types in `<format name>/Pages/`. Start here when diagnosing any runtime issue.

| Source | Published as | Role |
|--------|--------------|------|
| `Pages/scripts/*.js` | `.js` (loaded by runtime) | JavaScript behavior — keyboard shortcuts, search, navigation, runtime initialization |
| `Pages/*.asp` | `.html` / `.htm` | HTML templates rendered into the published topic and chrome pages |
| `Pages/sass/*.scss` | `.css` | Stylesheets compiled during publish; `_*.scss` partials are configurable variable collections |

When investigating a runtime issue — a theme override that didn't apply, a broken search, a navigation glitch, a missing chrome element — look in `Pages/` first. The published output is transformed; the source of truth lives in these three directories.

**Detailed SCSS guidance:** `## SCSS Customization` (below) and `references/scss-architecture.md`.
</runtime_architecture>

<related_skills>

## Related Skills

| Skill | Relationship |
|-------|--------------|
| **epublisher** | Use to understand project structure and product foundations; see `../epublisher/references/product-foundations.md` for cross-cutting product knowledge |
| **markdown-integration** | When Markdown++ sources feed Reverb output; covers how aliases drive `url_maps.xml` entries and how markers feed the search index |
| **automap** | Use to rebuild output after SCSS customizations |

**External:**

- **markdown-plus-plus** ([`quadralay/markdown-plus-plus`](https://github.com/quadralay/markdown-plus-plus)) — Markdown++ format syntax for marker and alias authoring. Install separately when authoring the source documents that feed Reverb output.

**After customizing themes:** Use the automap skill to rebuild the Reverb target.

</related_skills>

<intake>

## What would you like to do?

1. Test Reverb output in browser
2. Analyze CSH links
3. Customize SCSS theme
4. Generate test report
5. Resolve a stable Reverb landmark URL (or hash) to a direct file path

**Wait for response before proceeding.**
</intake>

<routing>

## Routing

| Response | Workflow |
|----------|----------|
| 1, "test", "browser" | workflows/browser-testing.md |
| 2, "csh", "links" | workflows/csh-analysis.md |
| 3, "scss", "theme", "colors" | workflows/scss-theming.md |
| 4, "report" | workflows/generate-report.md |
| 5, "resolve", "landmark", "hash" | workflows/landmark-resolution.md |
</routing>

<capabilities>

## Capabilities

| Feature | Script | Description |
|---------|--------|-------------|
| Browser Testing | `browser-test.js` | Load output in headless Chrome; pass/fail on the `preload` load signal (`--vanilla` for no-bypass file:// mode) |
| CSH Analysis | `parse-url-maps.py` | Extract topic mappings from url_maps.xml |
| SCSS Theming | `extract-scss-variables.py` | Read current theme values |
| Entry Detection | `detect-entry-point.sh` | Find output location from project |
| Report Generation | `generate-report.py` | Create formatted test reports |
| Landmark Resolution | `resolve-landmarks.py` | Resolve Reverb stable URLs (#/<id>) to direct file paths using _lx.js chunks |
</capabilities>

<browser_testing>

## Browser Testing

### Run Test

```bash
node scripts/browser-test.js <chrome-path> <entry-url> [format-settings-json] [--vanilla]
```

### Pass/Fail Signal (read this first)

**Primary signal — the only reliable one:** a load succeeded when the **`preload` class is removed from `<body id="connect_body">`**. `connect.js` removes it only in its `page_load_complete` handler, which fires when the **first content page** actually renders inside `page_iframe`.

- **Loaded OK** → `preloadCleared: true` (spinner cleared, first page rendered) → `success: true`, exit 0.
- **Broken / stuck** → `preload` still present after the load settles → `preloadCleared: false` → `success: false`, exit 1.

**Do not gate on `Parcels.loaded_all` or "no console errors."** `connect.js` catches exceptions internally, so a broken build can report `Parcels.loaded_all === true` (or fail silently) while the page is stuck on the spinner with no content. These are recorded only as **secondary diagnostics** (`parcelsLoadedAll`, `errors`, `warnings`, `components`).

### Vanilla (no-bypass) mode

By default `browser-test.js` launches Chrome with `--disable-web-security --allow-file-access-from-files`. Those flags let the parent read cross-origin iframe DOM that a real double-click cannot, so they **mask `file://`-only breakage** — the test can pass on output that is broken for users opening it from disk.

Pass `--vanilla` (or set `VANILLA=1`) to launch **without** the bypass flags and reproduce exactly what a user gets double-clicking `index.html`. Use it to catch `file://`-only regressions. The preload signal works in both modes because it reads the top-level `body#connect_body`, which is always same-origin.

### What It Checks

- **Primary:** `preload` removed from `body#connect_body` (`preloadCleared`)
- Secondary diagnostics: `Parcels.loaded_all`, console errors/warnings, component presence (toolbar, header, footer, TOC, content), FormatSettings validation

### DOM Component IDs

| Component | DOM ID | Presence Check |
|-----------|--------|----------------|
| **Load signal** | `body#connect_body` | **`preload` class absent** (primary pass/fail) |
| Toolbar | `#toolbar_div` | `childNodes.length > 0` |
| Header | `#header_div` | `childNodes.length > 0` |
| Footer | `#footer_div` | `childNodes.length > 0` OR `#ww_skin_footer` exists |
| TOC | `#toc` | `childNodes.length > 0` |
| Content | `#page_div` | Contains `#page_iframe` |

### Output Format

```json
{
  "success": true,
  "preloadCleared": true,
  "reverbLoaded": true,
  "vanillaMode": false,
  "loadTime": 1039,
  "parcelsLoadedAll": true,
  "diagnostics": {
    "bodyId": "connect_body",
    "hasPreloadClass": false,
    "parcelsLoadedAll": true,
    "firstPageLoaded": true,
    "readyState": "complete"
  },
  "errors": [],
  "warnings": [],
  "components": {
    "toolbar": { "present": true, "searchPresent": true },
    "header": { "present": true },
    "footer": { "present": false, "type": "none" },
    "toc": { "present": true, "itemCount": 35 },
    "content": { "present": true, "hasIframe": true }
  }
}
```

`success`, `preloadCleared`, and `reverbLoaded` all reflect the same primary signal. `parcelsLoadedAll` is the secondary, **unreliable** diagnostic — never treat it as the pass condition.
</browser_testing>

<csh_analysis>

## Context Sensitive Help (CSH)

### Parse url_maps.xml

```bash
python scripts/parse-url-maps.py <url-maps-file> [format]
```

Format: `json` (default) or `table`

### Topic Structure

```xml
<TopicMap>
  <Topic topic="whats_new"
         path="Getting Started\whats_new.html"
         href="index.html#context/whats_new"
         title="What's New"/>
</TopicMap>
```

| Attribute | Description |
|-----------|-------------|
| `@topic` | CSH identifier |
| `@href` | Pretty URL (JavaScript-based) |
| `@path` | Static URL (direct HTML path) |
| `@title` | Display name |
</csh_analysis>

<scss_customization>

## SCSS Customization

### Three-Layer Architecture

| Layer | What it controls | Override file | Entry point |
|-------|-----------------|