ui-debug

Files (1)

• SKILL.md

SKILL.md (first lines)

# UI Debug Skill

This skill connects to the running Deep Cuts dev server with whichever browser automation is available. Use Chrome MCP when available; in Codex, prefer the in-app Browser plugin for localhost/file targets. The goal is the same in every environment: inspect the live UI, read DOM/accessibility structure, capture computed styles, take screenshots, and diff styles before/after a change.

## Prerequisites

- The app must be running: `npm run tauri dev` (or just `npm run dev` for frontend-only)
- A browser inspection tool must be available: Chrome MCP, Codex in-app Browser, Playwright, or a manual browser fallback
- For realistic data, use the `?local_debug=1` query parameter (see below)

## The local_debug mode

Navigating to `http://localhost:1420/?local_debug=1` activates mock IPC data
(5 fixture tracks, 2 playlists) so the full UI renders in Chrome without needing
the Tauri backend. Use this URL for all CSS/Svelte debugging. Without the param,
the library will be empty because `window.__TAURI__` is not injected in Chrome.

## Setup sequence — Chrome MCP

Run this once per session before any inspection tools:

```
1. mcp__Claude_in_Chrome__list_connected_browsers   → get deviceId
2. mcp__Claude_in_Chrome__select_browser            → connect to it
3. mcp__Claude_in_Chrome__tabs_context_mcp          → get tabId (createIfEmpty: true)
4. mcp__Claude_in_Chrome__navigate                  → http://localhost:1420/?local_debug=1
   (skip if already on that URL)
```

After setup, reuse the same `tabId` for all subsequent calls.

## Setup sequence — Codex in-app Browser

When working in Codex with the Browser plugin available:

1. Start `npm run dev` for frontend-only inspection, or `npm run tauri dev` for full Tauri behavior.
2. Navigate the in-app Browser to `http://localhost:1420/?local_debug=1` for mock IPC data.
3. Use screenshots and DOM inspection to verify the changed surface at desktop and narrow widths.
4. If a component depends on real Tauri APIs not represented by local-debug mocks, add or update the mock in `src/lib/ipc.ts` before judging the UI.

## Fallback A — Codex / no-MCP browser

Use this when no Chrome MCP extension is connected but a browser can be opened
(e.g. the Codex environment with its in-app Browser plugin).

**Start the dev server:**
```bash
# Full Tauri stack (required for Rust IPC commands):
npm run tauri

# Frontend only (sufficient for CSS / Svelte component work):
npm run dev
```

**Navigate to the mock-data URL:**
```
http://localhost:1420/?local_debug=1   # Tauri dev server default port
http://localhost:5173/?local_debug=1   # Vite-only (npm run dev)
```

The `?local_debug=1` flag activates built-in mock IPC data (5 fixture tracks,
2 playlists) so the full UI renders without a running Tauri backend.

**What to verify:**
- The five mock tracks appear in the track list with correct title / artist / duration.
- Selecting a track populates the right detail pane (cover art, metadata fields).
- The player bar renders at the bottom with transport controls visible.
- No red error banners or "Library is empty" placeholder are shown.
- Repeat at a narrow viewport (~900 px) to confirm panels don't overflow.
- Check that the theme (dark / light) matches what was changed — the CSS custom
  properties in `src/app.css` drive all colours; a single token regression shows
  everywhere.

If a component depends on a Tauri API not yet covered by local-debug mocks, add
or update the fixture in `src/lib/ipc.ts` before judging the UI.

---

## Fallback B — Playwright screenshot / DOM assertion

Use this when no interactive browser MCP is available but Node.js is present.

**One-shot screenshot** (no config file needed):
```bash
npx --yes playwright@latest screenshot \
  --browser chromium \
  "http://localhost:1420/?local_debug=1" \
  /tmp/deep-cuts-ui.png
```

Read the resulting image with the `Read` tool to inspect it visually.

**Inline script for DOM assertions** (save as `/tmp/check-ui.mjs`, run once):
```js
import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('http://localhost:1420/?local_debug=1');
await page.waitForSelector('.track-row', { timeout: 5000 });

const trackCount  = await page.locator('.track-row').count();
const detailPane  = await page.locator('[data-region="detail"]').isVisible();
const playerBar   = await page.locator('[data-region="player"]').isVisible();
const consoleErrs = [];
page.on('console', m => { if (m.type() === 'error') consoleErrs.push(m.text()); });

console.log({ trackCount, detailPane, playerBar, consoleErrs });
await browser.close();
```

```bash
node /tmp/check-ui.mjs
```

**What to verify:**
- `trackCount` equals the number of fixture tracks (5 for the default mock set).
- `detailPane` and `playerBar` are both `true`.
- `consoleErrs` is empty — any entry is a regression worth investigating.

From robertolupi/deep-cuts, AGPL-3.0.

More from robertolupi/deep-cuts