the signals and their derived score are provisional and subject to change.
validate manually before sharing.
a51c164306c5e292501852fc4df3bec0a114fcfdnone
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Commands
```bash
npm run build # Compile TypeScript → es6/, lib/ (CommonJS), browser/
npm test # Prettier check + Jest (also runs build first via pretest)
npm run format # Auto-fix formatting with Prettier
```
Run a single test file:
```bash
npm test -- tests/unit/parser.spec.ts
```
Run tests matching a pattern:
```bash
npm test -- --testNamePattern "block with tags---
name: merging-devtools-module
description: Workflow for merging a DevTools submodule into its parent module. Covers BUILD.gn consolidation and updating devtools_grd_files.gni.
---
# Workflow: Merging a DevTools Submodule into its Parent
This document outlines the process for merging a submodule (e.g., `panels/timeline/extensions`) into its parent module (e.g., `panels/timeline`) within the DevTools build system. The goal is to simplify the build configuration by consolidating `BUILD.gn` files while ke---
name: migrate-chromium-test
description: Use when migrating Chromium layout tests to DevTools unit tests or API tests.
---
## Workflow
### 1. Identify the Test to Move
- You should have already received the issue ID, the test title, and the exact local paths of the downloaded legacy test file (`.js`) and its expectation file (`-expected.txt`) in your initial prompt.
- Refer to these local copies as you write the new modern test.
### 2. Determine Target Location & Test Suite Type
Investigate what fi---
name: devtools-model-management
description: Guidelines for creating, migrating, and registering models in front_end/models/. Covers BUILD.gn, devtools_grd_files.gni, and entrypoints.
---
# Creating or Migrating a Model in DevTools
This guide outlines the standard procedure for creating a new model or migrating an existing one to `front_end/models/`.
## 0. Preparation (Before you start)
* **Baseline:** Run existing tests for the code you are moving to ensure they pass *before* you touch anything.
---
name: devtools-ui-widgets
description: Guidelines for building UI widgets using the MVP architecture in DevTools. Covers Widget lifecycle, lit-html views, and state management.
---
## UI Widget Framework Guide (MVP Architecture)
Adhere strictly to the Model-View-Presenter (MVP) architecture.
* **Models** (`front_end/models/`): Handle business logic and application state. MUST NOT have knowledge of the UI.
* **Presenters (`Widget`)**: Orchestrate data flow, manage UI-specific state, and handle interac---
name: devtools-setting-migration
description: "Workflow for splitting an existing SettingRegistration into a SettingDescriptor (placed in the lowest layer where used: core/, models/, or ui/settings/) and SettingUIDescriptor (registered in a higher-level -meta.ts file, outside of core/ and models/)."
---
# DevTools Setting Migration Guide
This skill guide describes how to migrate an existing legacy `SettingRegistration` in DevTools by splitting it into a `SettingDescriptor` (non-UI descriptor) and a `S---
name: ui-eng-vision-test-scaffolder
description: Scaffolds unit tests and screenshot tests to establish visual and functional rendering baselines for views before refactoring.
allowed-tools: code_search open_urls
---
# Subskill: Test Scaffolder
This subskill establishes the safety net of existing and new visual/functional
tests before any codebase modifications occur, ensuring that no rendering or
logical regressions are introduced during modernization.
--------------------------------------------------
name: foundation-test-migration
description: Migrating unit tests to foundation unit tests using TestUniverse and devtools_foundation_module. Use when moving tests away from DOM-heavy helpers like describeWithEnvironment or describeWithMockConnection.
---
# Foundation Test Migration
This skill provides guidance on migrating DevTools unit tests to the "foundation" pattern, which is lighter, avoids global singletons, and is compatible with both Node and Browser runtimes (Isomorphic).
## Core Concepts
---
name: devtools-ux-writing-refactor
description: >-
Refactor user-facing UIStrings and localization comments in a DevTools module folder according to UX writing guidelines (child task of b/40799900). Use when simplifying wording, checking sentence case, or improving L10n comments in UIStrings for a specific folder or issue. Don’t use for general code changes or non-UIStrings files.
---
# DevTools UX writing refactoring workflow
Use this skill when addressing a single UX writing refactoring task (on---
name: fix-tests
description: Use this skill to reproduce and fix flaky and disabled tests.
---
# Workflow
This skill outlines the workflow for reproducing and fixing a flaky test in the DevTools codebase. The work should be divided into sub-agents that should only be started when certain criteria are met.
- You will be given as input, either a Chromium bug link (e.g. `crbug.com/1234567`), or a name of a test file and (optionally) the test name.
- For example: e2e/extensions/debugger-language-plugins.---
name: devtools-imports
description: Conventions for importing code in Devtools to avoid build errors. Covers cross-module imports, internal imports, and the "import * as" requirement.
---
# Imports
This codebase follows a special convention for importing code that must be followed to avoid build errors.
In DevTools each folder of code is considered a *module*:
- `front_end/models/trace` is the *trace module*.
- `front_end/panels/timeline` is the *timeline module*.
Within each module there are multi---
name: devtools-source-maps
description: Guidelines for utilizing source maps and structured stack traces in DevTools. Covers DebuggerWorkspaceBinding, StackTrace, SymbolizedError, and related UI widgets.
---
# Utilizing Source Maps & Structured Stack Traces in DevTools
This skill guides you on how to correctly map runtime coordinates to original
source locations and render structured stack traces or symbolized errors in the
DevTools frontend.
---
## 1. Primary Rules
1. **Never parse raw error stack---
name: ui-eng-vision-logic-consolidator
description: Consolidates manual DOM creation, updates, and constructors into private helper methods and structured state interfaces.
allowed-tools: code_search open_urls
---
# Subskill: Logic Consolidator (Pass 1)
This subskill extracts manual layout building, attribute modifications, and
rendering loops out of the constructor and scattered event handlers,
consolidating them into private helper methods with explicit data contracts.
--------------------------------
name: ui-eng-vision-widget-promoter
description: Promotes legacy views to modern UI.Widget classes, hooks up performUpdate() rendering, and exports default views.
allowed-tools: code_search open_urls
---
# Subskill: Widget Promoter (Pass 3)
This subskill completes the architectural transition, upgrading the component
from legacy base classes (like `SimpleView` or custom wrapper layouts) into
clean `UI.Widget` classes that use native update rendering delegates.
-------------------------------------------
name: code-review
description: Generic checklist for reviewing DevTools CLs (your own before upload, or someone else's on Gerrit). Covers test correctness (tautological/vacuous tests, cleanup, leaks), code clarity, CL hygiene, and points to the specialized skills to consult for imports, UI, testing, strings, models, and verification. Use when asked to review a CL, a diff, a patch, or to self-review before `git cl upload`.
---
# Code Review
This checklist comes from recurring reviewer feedback on lande---
name: devtools-version-control
description: Use when starting a new task, creating a branch, switching branches, managing branches, creating and uploading CLs, handling stacked changes, or checking release and roll status in the DevTools Gerrit-based workflow. ALWAYS use this instead of running standard git checkout/switch commands for branch creation.
---
# DevTools Version Control
> [!IMPORTANT]
> **DO NOT use standard Git commands like `git checkout -b` or `git switch -c` to create branches.**
> In---
name: ui-eng-vision-local-lit-renderer
description: Migrates legacy imperative DOM construction to local declarative Lit-html templates rendered inside existing containers.
allowed-tools: code_search open_urls
---
# Subskill: Local Lit-HTML Renderer (Pass 2)
This subskill converts consolidated imperative DOM construction helper methods
into reactive, declarative Lit-html templates, rendering them locally inside the
existing element containers.
------------------------------------------------------------
name: devtools-testing-guidance
description: Guidance on selecting the appropriate test suite (Unit, API, or E2E tests) when writing new tests in Chrome DevTools. MUST be used when writing new tests.
---
# Testing Guidance
This guide outlines when and how to select the appropriate test suite when writing new tests in Chrome DevTools.
> [!NOTE]
> This skill provides guidance on **which** test suite to choose when writing tests. To learn **how** to run tests, build targets, or execute linters, refer to---
name: ui-eng-vision-orchestrator
description: High-level orchestrator for managing multi-pass migration of Chrome DevTools legacy components to the modern UI engineering vision (UI.Widget & Lit-html).
allowed-tools: code_search open_urls search_changelists data_analysis import_skill close_skill invoke_subagent send_message
---
# UI Engineering Vision Orchestrator: Meta-Skill Instructions
This meta-skill acts as the central coordinator for modernizing legacy Chrome
DevTools views into declarative `UI.W---
name: devtools-verification
description: "MANDATORY: Activate this skill ANY TIME you need to build the project, run tests, or verify code health in DevTools. You MUST use this skill before executing commands like npm test, npm run build, autoninja, or linters, as it contains critical, repository-specific instructions on how to correctly format these commands, filter test runs, and interpret failures."
---
# Instructions on how to verify your changes
## Testing
- To test a file, you can run `npm run ---
name: devtools-unicode-escaping
description: Guidelines for escaping strings and handling user-controlled data in DevTools to prevent layout bleed-through, XSS, and security issues.
---
# Unicode Escaping and User-Controlled Data Guidelines
When displaying inspected data, user-controlled strings, or untrusted input in the DevTools UI (e.g., console messages, object properties, DOM tree nodes, or UI titles/descriptions), you must ensure they are properly escaped to prevent layout bleed-through (such asnode_modules/
/third_party/
front_end/core/i18n/locales/*.json
front_end/third_party/lighthouse/locales/*.json
front_end/panels/timeline/fixtures/traces/
.gitignorezed*.rules