# Editor-side bug investigation

For bugs where the block editor renders differently from the frontend (fonts, colors, layout that appear only in the editor view), the first investigation step is identifying which CSS file actually loads in the block editor. Theme editor styles can be registered via multiple mechanisms, and they don't all reach the block editor.

## Three editor-style registration patterns

Check `functions.php` for each:

1. **`add_editor_style( 'file.css' )` + `add_theme_support( 'editor-styles' )`**
   - Loads `file.css` in the block editor
   - Auto-scoped to `.editor-styles-wrapper` by Gutenberg
   - Also loads in the legacy classic TinyMCE editor

2. **`add_editor_style( 'file.css' )` WITHOUT `add_theme_support( 'editor-styles' )`**
   - Loads `file.css` in the legacy classic editor only
   - **Does NOT reach the block editor** — a common cause of editor-vs-frontend bugs on older classic themes

3. **`wp_enqueue_style( ..., 'editor-blocks.css' )` via `enqueue_block_editor_assets` action**
   - Loads the file in the block editor
   - **Selectors are NOT auto-scoped** — rules apply to the whole editor admin page (including Gutenberg chrome) unless manually scoped to `.editor-styles-wrapper`

A single theme may use multiple patterns. The block editor only loads CSS via patterns 1 or 3.

## Verifying which file actually loads

Code inspection alone is not enough — verify in the editor:

1. Open the block editor on the affected theme's sandbox.
2. DevTools → switch context to the `editor-canvas` iframe (right-click an element in the editor canvas → Inspect).
3. In the Console, run:
   ```js
   ({
     stylesheets: [...document.querySelectorAll('link[rel=stylesheet]')].map(l => l.href),
     inlineStyles: [...document.querySelectorAll('style')]
       .filter(s => s.textContent.includes('font-family') || s.textContent.includes('editor-styles-wrapper'))
       .map(s => s.textContent.slice(0, 300))
   })
   ```
4. Identify which theme file is in the `stylesheets` list (or `inlineStyles` if loaded as `<style>` block).

If a file you expected to load isn't there, the registration mechanism is wrong — see patterns above.

## Scoping rules added via pattern 3

When adding CSS via `enqueue_block_editor_assets`-loaded files, always scope to `.editor-styles-wrapper`:

```css
.editor-styles-wrapper {
    font-family: "Body Font", sans-serif;
}

.editor-styles-wrapper h1,
.editor-styles-wrapper h2,
.editor-styles-wrapper h3,
.editor-styles-wrapper .wp-block-heading {
    font-family: "Heading Font", serif;
}
```

A bare `body { font-family: ... }` or `h1 { font-family: ... }` rule will leak into Gutenberg's admin chrome (sidebar, toolbar, panel titles).

## Custom-fonts caveat (separate concern)

Customer-customized fonts set via Customizer (often served by Jetpack Custom Fonts) commonly inject CSS only on the frontend, not into the block editor iframe. Even when the theme's editor-side CSS is correct, customers with custom fonts may see theme defaults in the editor while their custom fonts apply on the frontend.

Treat this as a separate concern from theme-side editor CSS gaps — it's a Jetpack/wpcom-side issue. Don't conflate the two when classifying.

## Skill limitation — visual verification required

The skill cannot inspect the block editor's DOM, network requests, or computed styles. Editor-side fixes are not fully verifiable from code alone. When proposing an editor-side fix:

- Note in the investigation comment that visual verification on a sandbox is required before merging
- Recommend specific checks: which selectors should render which fonts, whether Gutenberg chrome is unaffected, whether frontend rendering is unchanged
- Do not claim a fix is "verified" if it has not been visually checked

## Reference

This guide was added based on investigation of THEME-121 (Baskerville 2 — editor fonts differ from live site), which surfaced the editor-style.css vs editor-blocks.css distinction. The bug was that the theme's `editor-blocks.css` (loaded via pattern 3) lacked heading and body font rules; the existing `editor-style.css` (loaded via pattern 2) was unreachable from the block editor. Fix: wpcom-themes#157277.