From 9523e6e25d67dd9fc9cdb1adb8549f86dd3e5485 Mon Sep 17 00:00:00 2001
From: Jordan Paulino <jjpaulino@users.noreply.github.com>
Date: Wed, 13 May 2026 18:20:09 -0400
Subject: [PATCH] =?UTF-8?q?=F0=9F=8D=95=20feat(highlight):=20refined=20mod?=
 =?UTF-8?q?es=20+=20single=20accent=20+=20selection=20labels?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces the always-on, six-color, dashed-rainbow highlight pass with a
restrained four-mode model that defaults to "selection only" — closer to
Chrome DevTools' element inspector and a much friendlier baseline for
content-heavy editorial pages.

Why
---
On a typical New York Magazine page, the previous highlighter painted
every component all the time, in dashed pink/yellow/teal, with width
varying by sibling order. The result on a busy page was visually
overwhelming — three nested components share an edge and you get three
parallel dashes within 6px, with no encoding of *importance*. The
extension was strictly harder to read with than without.

Modes
-----
- off        — no ambient outlines anywhere. Hover + selection still
               render so click-to-inspect remains visible.
- selection  — ambient off, only hovered/selected elements outlined.
               NEW DEFAULT.
- editable   — ambient outlines on [data-editable] only. Useful for
               editorial / PM workflows.
- all        — ambient outlines on every component. The "give me the
               bird's-eye view" mode.

Visual language
---------------
- Single accent color (tailwind blue-600). State is encoded with width
  + opacity, not hue:
    ambient   → 1px @ 18% accent
    hover     → 2px @ 70% accent
    selected  → 2px @ 100% accent + top-left labelled badge
- Solid outlines (was: dashed/dotted/double). Reads as inspection,
  not "draft/error".
- The selection badge is a small pill anchored above the selected box
  rendering the component name from a new data-clay-slip-label attr.
- Find-on-page match outline kept as emerald green so it remains a
  *different signal* from the regular accent.

How mode gating works
---------------------
The stylesheet keys ambient rules off `html[data-clay-slip-mode]`, so
switching modes is one attribute write — no per-element walking, no
restyle pass. `mode='off'` writes the attribute explicitly so we can
add `[mode="off"]` rules later (e.g. for diagnostics) without code
changes.

Wiring
------
- HighlightMode type added to UserPreferences (default 'selection').
  loadPreferences() merges over DEFAULT_PREFERENCES so existing users
  get the new default for free without a migration.
- Store gains setHighlightMode + cycleHighlightMode actions; both
  persist to chrome.storage.sync. The boolean highlightEnabled state
  + toggleHighlights action are dropped — `mode === 'off'` covers it.
- Header eye button replaced with a HighlightModeMenu (native
  <details> popover) showing the four modes + descriptions with
  a click-outside-to-close handler for free.
- `h` keyboard shortcut now cycles modes.
- Options page gains a Highlight mode <select> above the existing
  intensity slider. The slider's help text is rewritten to explain
  the new "master multiplier" role.

Tests
-----
Adds tests/content/highlighter.test.ts (18 cases) covering:
- installHighlightStyles is idempotent and respects pre-set mode
- applyHighlights tags + labels in the right index, skips empty labels
- clearHighlights wipes every attribute we set, leaves data-editable
- setHighlightMode round-trips, falls back to 'selection' on garbage
- setHovered/setSelected toggle exactly one element at a time
- setHighlightOpacity clamps to [0, 1]

113 → 131 tests passing.

Version bump: 2.0.2 → 2.1.0 (UX-significant change, additive prefs).

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 README.md                                     |   8 +-
 package.json                                  |   2 +-
 src/content/highlighter.ts                    | 226 +++++++++++++----
 src/content/index.ts                          |   8 +-
 src/content/panel/App.tsx                     |   8 +-
 src/content/panel/components/Header.tsx       |  13 +-
 .../panel/components/HighlightModeMenu.tsx    |  99 ++++++++
 .../panel/hooks/useKeyboardShortcuts.ts       |   6 +-
 src/content/panel/store.ts                    |  29 ++-
 src/content/panel/styles.css                  |  97 +++++++
 src/lib/types.ts                              |  38 +++
 src/options/Options.tsx                       |  27 +-
 tests/content/highlighter.test.ts             | 236 ++++++++++++++++++
 13 files changed, 721 insertions(+), 76 deletions(-)
 create mode 100644 src/content/panel/components/HighlightModeMenu.tsx
 create mode 100644 tests/content/highlighter.test.ts

diff --git a/README.md b/README.md
index 503a900..8e0b46f 100644
--- a/README.md
+++ b/README.md
@@ -23,10 +23,10 @@ Clay annotates rendered HTML with `data-uri` attributes on every component, page
 - **SEO tab** — title / meta / og / twitter / JSON-LD with a Twitter + Facebook card preview and lints (length, missing image, duplicate `<h1>`, etc.)
 - **Recently viewed components** persisted across sessions, with one-click jump back
 - **Resizable + dockable panel** — drag the inner edges (or the inner-corner grabber) to resize width _and_ height; choose any of four corners or a full-height left/right side dock
-- **Toggleable component outlines** (button in the header, <kbd>h</kbd> shortcut) with a configurable opacity
+- **Refined highlight modes** — _Off_, _Selection only_ (default, like Chrome DevTools' element inspector), _Editable only_, or _All components_. Single accent color with state-based opacity instead of the old multi-color dashed rainbow. Selected component carries a labelled top-left badge. Switch modes from the panel header dropdown or with the <kbd>h</kbd> shortcut.
 - **Auto / light / dark themes** that respond to OS theme changes live
 - **Keyboard shortcuts** with a <kbd>?</kbd> overlay listing every binding
-- **Options page** for theme, dock side + width, environment hosts, highlight intensity, shortcut toggle, and recents history size
+- **Options page** for theme, dock side + width, environment hosts, highlight mode + intensity, shortcut toggle, and recents history size
 - **Floating Clay button (FAB)** on every Clay page — collapsed/idle state of the panel is a small circular button anchored to the user's preferred corner, with a live component-count badge. Click it to expand the full panel. The standard browser-extension chrome pattern (Sentry / Hotjar / Crisp / Intercom).
 - **Smart popup**: friendly "Not a Clay page" popup on non-Clay pages; on Clay pages the toolbar icon mounts/unmounts the entire extension as an escape hatch
 - **Toolbar badge** shows the count of Clay components on the current page (cleared on navigation)
@@ -75,7 +75,7 @@ Reload the extension in `chrome://extensions` after switching between `dev` and
 | Resize the panel         | Drag the inner vertical / horizontal edge — or the inner-corner grabber for both at once          |
 | Copy URI                 | Press <kbd>y</kbd> then <kbd>c</kbd> (component) or <kbd>p</kbd> (page)                           |
 | Open URI in new tab      | Press <kbd>o</kbd> then <kbd>c</kbd> or <kbd>p</kbd>                                              |
-| Toggle outlines on page  | Press <kbd>h</kbd> or click the eye icon in the header                                            |
+| Cycle highlight mode     | Press <kbd>h</kbd> (off → selection → editable → all) or pick from the eye-icon dropdown          |
 | Cycle environment        | Click the `env: …` pill at the bottom of the Inspect tab                                          |
 | Show shortcut overlay    | Press <kbd>?</kbd>                                                                                |
 | Toggle FAB ↔ panel       | Press <kbd>[</kbd> or click the collapse button / the FAB                                         |
@@ -124,7 +124,7 @@ src/
 │       ├── components/     # Tabs, tree, JSON viewer, diff, breadcrumb…
 │       └── hooks/          # Drag, theme, shortcuts, selection
 ├── popup/                  # "Not a Clay page" popup (active until a page sends CLAY_DETECTED)
-├── options/                # Full options page (env hosts, dock + width, intensity, recents, shortcuts)
+├── options/                # Full options page (env hosts, dock + width, highlight mode + intensity, recents, shortcuts)
 └── lib/                    # Pure utilities
     ├── clay-uri.ts         # URI parsing + buildUrl/buildEditorUrl/buildShareLink + copy-as helpers
     ├── clipboard.ts        # Modern + legacy clipboard
diff --git a/package.json b/package.json
index c7424ff..639b89a 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "clay-slip",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Modern devtools for Clay CMS pages: visualize component boundaries, inspect data, and navigate the page/layout hierarchy.",
   "private": true,
   "type": "module",
diff --git a/src/content/highlighter.ts b/src/content/highlighter.ts
index ec37aea..a601f76 100644
--- a/src/content/highlighter.ts
+++ b/src/content/highlighter.ts
@@ -1,34 +1,65 @@
 /**
- * Manages outline highlighting for Clay components in the host page.
- * Uses a single style element scoped via data-attribute selectors so we never
- * mutate inline styles on host elements.
+ * Manages the visual outlines Clay Slip paints over host-page components.
+ *
+ * Design rules — read first
+ * -------------------------
+ * 1. **Outline only.** We never set background, border, or position on host
+ *    elements except via two pseudo-elements (annotation dot + selection
+ *    label badge), each gated behind a tiny `position: relative` opt-in. CSS
+ *    `outline` is layout-neutral and overrides cleanly with `!important`.
+ *
+ * 2. **One accent color.** Old versions used a six-color rainbow keyed off a
+ *    component's sibling order. It looked busy and carried no real meaning
+ *    (siblings aren't more or less important than each other). The only
+ *    thing the highlight needs to communicate is **state**:
+ *      ambient    – "this is a Clay component"
+ *      hover      – "this is what you'd select right now"
+ *      selected   – "this is what the panel is currently inspecting"
+ *    State is encoded with width + opacity of a single accent, not with hue.
+ *
+ * 3. **Mode-gated ambient.** The "every component outlined all the time"
+ *    look turns the page into caution-tape soup on busy layouts. We default
+ *    to `selection` mode, where ambient outlines are off entirely. The user
+ *    opts up to `editable` (only `[data-editable]`) or `all` (every
+ *    component) when they want the bird's-eye view.
+ *
+ * 4. **Z-order budget.** All highlight effects live near the top of the
+ *    z-axis (just below the panel itself). We use 2147483645/6 — one short
+ *    of the int max — so panel UI can still sit on top with 2147483647.
  */
+import type { HighlightMode } from '@/lib/types';
+
 const STYLE_ID = 'clay-slip-highlight-styles';
+
 const HIGHLIGHT_ATTR = 'data-clay-slip-color';
 const SELECTED_ATTR = 'data-clay-slip-selected';
 const HOVER_ATTR = 'data-clay-slip-hover';
 const ANNOTATED_ATTR = 'data-clay-slip-annotated';
 const MATCH_ATTR = 'data-clay-slip-match';
 const FILTER_MODE_ATTR = 'data-clay-slip-filtering';
+const LABEL_ATTR = 'data-clay-slip-label';
+const MODE_ATTR = 'data-clay-slip-mode';
+
 const OPACITY_VAR = '--clay-slip-outline-opacity';
 const DEFAULT_OPACITY = 0.85;
 
-interface PaletteEntry {
-  readonly r: number;
-  readonly g: number;
-  readonly b: number;
-  readonly style: string;
-  readonly width: number;
-}
+/**
+ * Single accent color for ambient/hover/selected outlines.
+ * Picked to be readable against both light and dark editorial designs and
+ * to *not* visually clash with typical brand reds, magentas, or oranges (the
+ * colors most likely to appear in a Clay site's content). RGB triple is
+ * inlined into rgba() expressions since CSS `outline` only takes a single
+ * color and we vary opacity per state.
+ */
+const ACCENT_RGB = '37, 99, 235'; // tailwind blue-600
 
-const PALETTE: ReadonlyArray<PaletteEntry> = [
-  { r: 221, g: 161, b: 161, style: 'solid', width: 2 },
-  { r: 221, g: 221, b: 161, style: 'dashed', width: 3 },
-  { r: 176, g: 221, b: 161, style: 'dotted', width: 4 },
-  { r: 161, g: 221, b: 221, style: 'solid', width: 5 },
-  { r: 161, g: 161, b: 221, style: 'dashed', width: 4 },
-  { r: 221, g: 160, b: 221, style: 'double', width: 4 },
-];
+/** Element width/opacity tokens per state. Tweak these together. */
+const TOKENS = {
+  ambient: { width: 1, alpha: 0.18, offset: -1 },
+  hover: { width: 2, alpha: 0.7, offset: -2 },
+  selected: { width: 2, alpha: 1, offset: -2 },
+  match: { width: 2, alpha: 0.95, offset: -2 },
+} as const;
 
 export function installHighlightStyles(): void {
   if (document.getElementById(STYLE_ID)) return;
@@ -37,48 +68,132 @@ export function installHighlightStyles(): void {
   style.textContent = buildStyleSheet();
   document.head.appendChild(style);
   setHighlightOpacity(DEFAULT_OPACITY);
+  // Keep the previously-active mode if one was set before mount; otherwise
+  // start in 'selection' mode (also the prefs default), which keeps the page
+  // pristine until the user opts up.
+  if (!document.documentElement.hasAttribute(MODE_ATTR)) {
+    setHighlightMode('selection');
+  }
 }
 
 function buildStyleSheet(): string {
-  const colorRules = PALETTE.map(
-    (p, i) =>
-      `[${HIGHLIGHT_ATTR}="${i}"]{outline:${p.width}px ${p.style} rgba(${p.r},${p.g},${p.b},var(${OPACITY_VAR},${DEFAULT_OPACITY})) !important;outline-offset:-${p.width}px !important;}`
-  ).join('\n');
+  // We use the var() for opacity so the user's "intensity" slider can scale
+  // every outline at once without re-emitting the stylesheet.
+  const o = (alpha: number) =>
+    `rgba(${ACCENT_RGB}, calc(${alpha} * var(${OPACITY_VAR}, ${DEFAULT_OPACITY})))`;
 
   return `
-    ${colorRules}
-    [${HOVER_ATTR}]{outline:3px solid rgba(255,175,58,var(${OPACITY_VAR},${DEFAULT_OPACITY})) !important;outline-offset:-3px !important;}
-    [${SELECTED_ATTR}]{outline:5px solid rgba(226,44,44,var(${OPACITY_VAR},${DEFAULT_OPACITY})) !important;outline-offset:-5px !important;}
-    [${ANNOTATED_ATTR}]{position:relative;}
-    [${ANNOTATED_ATTR}]::before{
-      content:"";position:absolute;top:4px;right:4px;width:10px;height:10px;border-radius:50%;
-      background:rgba(245,158,11,0.95);box-shadow:0 0 0 2px rgba(255,255,255,0.85);
-      pointer-events:none;z-index:2147483646;
+    /* ── Ambient outlines: gated by html[data-clay-slip-mode] ────────────
+       Mode 'all'      → every [data-uri] gets a 1px ghost outline.
+       Mode 'editable' → only [data-editable] does.
+       Mode 'selection' or 'off' → no rule matches; nothing painted. */
+    html[${MODE_ATTR}="all"] [${HIGHLIGHT_ATTR}],
+    html[${MODE_ATTR}="editable"] [${HIGHLIGHT_ATTR}][data-editable] {
+      outline: ${TOKENS.ambient.width}px solid ${o(TOKENS.ambient.alpha)} !important;
+      outline-offset: ${TOKENS.ambient.offset}px !important;
+    }
+
+    /* Hover and selection always render regardless of mode (otherwise
+       click-to-inspect would be invisible in 'off'). */
+    [${HOVER_ATTR}] {
+      outline: ${TOKENS.hover.width}px solid ${o(TOKENS.hover.alpha)} !important;
+      outline-offset: ${TOKENS.hover.offset}px !important;
+    }
+
+    [${SELECTED_ATTR}] {
+      outline: ${TOKENS.selected.width}px solid ${o(TOKENS.selected.alpha)} !important;
+      outline-offset: ${TOKENS.selected.offset}px !important;
+      position: relative;
+    }
+
+    /* Selection label — a small pill in the top-left of the selected box
+       reading the component name from the data-clay-slip-label attribute.
+       Sits *outside* the box when there's room above it, otherwise tucks
+       inside via translateY(0). The negative-then-clamp trick keeps the
+       label visible at the very top of the page where translateY(-100%)
+       would scroll out of view. */
+    [${SELECTED_ATTR}][${LABEL_ATTR}]::before {
+      content: attr(${LABEL_ATTR});
+      position: absolute;
+      top: 0;
+      left: 0;
+      transform: translateY(-100%);
+      background: rgb(${ACCENT_RGB});
+      color: #ffffff;
+      font: 500 11px/1.4 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+      padding: 2px 6px;
+      border-radius: 3px 3px 3px 0;
+      white-space: nowrap;
+      max-width: 240px;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      pointer-events: none;
+      z-index: 2147483646;
+      box-shadow: 0 1px 2px rgba(0, 0, 0, 0.15);
+    }
+
+    /* Annotation dot — kept from the previous iteration, retuned to amber
+       so it doesn't blend with the new blue accent. */
+    [${ANNOTATED_ATTR}] { position: relative; }
+    [${ANNOTATED_ATTR}]::after {
+      content: "";
+      position: absolute;
+      top: 4px;
+      right: 4px;
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      background: rgba(245, 158, 11, 0.95);
+      box-shadow: 0 0 0 2px rgba(255, 255, 255, 0.85);
+      pointer-events: none;
+      z-index: 2147483646;
+    }
+
+    /* Find-on-page filter mode: dim non-matches, highlight matches. Match
+       outline uses an emerald green so it reads as a *different signal*
+       than the regular accent. */
+    html[${FILTER_MODE_ATTR}] [data-uri]:not([${MATCH_ATTR}]) {
+      opacity: 0.25 !important;
+      transition: opacity 0.12s;
+    }
+    [${MATCH_ATTR}] {
+      outline: ${TOKENS.match.width}px solid
+        rgba(34, 197, 94, calc(${TOKENS.match.alpha} * var(${OPACITY_VAR}, ${DEFAULT_OPACITY}))) !important;
+      outline-offset: ${TOKENS.match.offset}px !important;
     }
-    html[${FILTER_MODE_ATTR}] [data-uri]:not([${MATCH_ATTR}]){opacity:0.25 !important;transition:opacity 0.12s;}
-    [${MATCH_ATTR}]{outline:3px solid rgba(34,197,94,var(${OPACITY_VAR},${DEFAULT_OPACITY})) !important;outline-offset:-3px !important;}
   `;
 }
 
-export function applyHighlights(elements: HTMLElement[]): void {
-  let lastParent: ParentNode | null = null;
-  let colorIdx = 0;
-  for (const el of elements) {
-    if (lastParent && el.parentNode !== lastParent) {
-      colorIdx = (colorIdx + 1) % PALETTE.length;
-    }
-    el.setAttribute(HIGHLIGHT_ATTR, String(colorIdx));
-    lastParent = el.parentNode;
+/**
+ * Tag every component element so the ambient + state CSS selectors have
+ * something to target. Also stashes a human-readable label on the element
+ * so the selection badge can read it via `attr()`.
+ *
+ * The previous implementation also encoded a per-sibling color index here.
+ * That was the source of the rainbow look and we drop it — `[data-clay-slip-color]`
+ * is now just a presence flag.
+ */
+export function applyHighlights(
+  elements: readonly HTMLElement[],
+  labels?: readonly string[]
+): void {
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    if (!el) continue;
+    el.setAttribute(HIGHLIGHT_ATTR, '');
+    const label = labels?.[i];
+    if (label) el.setAttribute(LABEL_ATTR, label);
   }
 }
 
-export function clearHighlights(elements: HTMLElement[]): void {
+export function clearHighlights(elements: readonly HTMLElement[]): void {
   for (const el of elements) {
     el.removeAttribute(HIGHLIGHT_ATTR);
     el.removeAttribute(SELECTED_ATTR);
     el.removeAttribute(HOVER_ATTR);
     el.removeAttribute(ANNOTATED_ATTR);
     el.removeAttribute(MATCH_ATTR);
+    el.removeAttribute(LABEL_ATTR);
   }
   document.documentElement.removeAttribute(FILTER_MODE_ATTR);
 }
@@ -93,10 +208,29 @@ export function setHovered(prev: HTMLElement | null, next: HTMLElement | null):
   if (next) next.setAttribute(HOVER_ATTR, '');
 }
 
-export function setHighlightingEnabled(enabled: boolean): void {
-  const style = document.getElementById(STYLE_ID) as HTMLStyleElement | null;
-  if (!style) return;
-  style.disabled = !enabled;
+/**
+ * Switch the global ambient-outline mode by flipping a single attribute on
+ * `<html>`. The attribute is the join key the stylesheet uses for its mode
+ * gating, so this is the only function that needs to run when mode changes.
+ *
+ * `'off'` removes the attribute entirely so nothing matches the ambient
+ * rule — slightly cheaper than carrying an explicit `[mode="off"]` selector
+ * around, and means no ambient rule can ever fire by accident.
+ */
+export function setHighlightMode(mode: HighlightMode): void {
+  if (mode === 'off') {
+    document.documentElement.setAttribute(MODE_ATTR, 'off');
+  } else {
+    document.documentElement.setAttribute(MODE_ATTR, mode);
+  }
+}
+
+export function getHighlightMode(): HighlightMode {
+  const attr = document.documentElement.getAttribute(MODE_ATTR);
+  if (attr === 'off' || attr === 'selection' || attr === 'editable' || attr === 'all') {
+    return attr;
+  }
+  return 'selection';
 }
 
 export function setHighlightOpacity(opacity: number): void {
diff --git a/src/content/index.ts b/src/content/index.ts
index 2f13ae5..97e006b 100644
--- a/src/content/index.ts
+++ b/src/content/index.ts
@@ -17,7 +17,13 @@ function send(message: RuntimeMessage): void {
 function paintAndSync(): number {
   installHighlightStyles();
   const components = readComponents();
-  applyHighlights(components.map((c) => c.element));
+  applyHighlights(
+    components.map((c) => c.element),
+    // Selection badge label — passed down so the CSS pseudo-element can
+    // surface it via attr(). Falling back to component name keeps the
+    // badge useful when an instance ID isn't present.
+    components.map((c) => c.displayName || c.name)
+  );
   useStore.getState().setComponents(components);
   return components.length;
 }
diff --git a/src/content/panel/App.tsx b/src/content/panel/App.tsx
index bd9cc17..6a32db6 100644
--- a/src/content/panel/App.tsx
+++ b/src/content/panel/App.tsx
@@ -2,7 +2,7 @@ import { useEffect, useRef } from 'react';
 import { loadPreferences, onPreferencesChanged } from '@/lib/storage';
 import { listAnnotations, onAnnotationsChanged } from '@/lib/annotations';
 import { loadRecents, onRecentsChanged, pushRecent } from '@/lib/recents';
-import { setAnnotatedUris, setHighlightingEnabled, setHighlightOpacity } from '../highlighter';
+import { setAnnotatedUris, setHighlightMode, setHighlightOpacity } from '../highlighter';
 import { useStore } from './store';
 import { useDraggable } from './hooks/useDraggable';
 import { useKeyboardShortcuts } from './hooks/useKeyboardShortcuts';
@@ -32,7 +32,7 @@ export function App() {
   const panelWidth = useStore((s) => s.preferences.panelWidth);
   const panelHeight = useStore((s) => s.preferences.panelHeight);
   const highlightOpacity = useStore((s) => s.preferences.highlightOpacity);
-  const highlightEnabled = useStore((s) => s.highlightEnabled);
+  const highlightMode = useStore((s) => s.preferences.highlightMode);
   const setPrefs = useStore((s) => s.setPreferences);
   const setRecents = useStore((s) => s.setRecents);
   const setAnnotations = useStore((s) => s.setAnnotations);
@@ -68,8 +68,8 @@ export function App() {
   }, [highlightOpacity]);
 
   useEffect(() => {
-    setHighlightingEnabled(highlightEnabled);
-  }, [highlightEnabled]);
+    setHighlightMode(highlightMode);
+  }, [highlightMode]);
 
   // Sync the annotation dot indicators on the page whenever either set changes.
   useEffect(() => {
diff --git a/src/content/panel/components/Header.tsx b/src/content/panel/components/Header.tsx
index 4462566..543d281 100644
--- a/src/content/panel/components/Header.tsx
+++ b/src/content/panel/components/Header.tsx
@@ -2,6 +2,7 @@ import type { Ref } from 'react';
 import clayIconUrl from '@/assets/clay-icon.png?inline';
 import type { RuntimeMessage } from '@/lib/types';
 import { Icon } from './Icon';
+import { HighlightModeMenu } from './HighlightModeMenu';
 import { useStore } from '../store';
 
 interface HeaderProps {
@@ -12,8 +13,6 @@ export function Header({ ref }: HeaderProps) {
   const page = useStore((s) => s.page);
   const toggleCollapsed = useStore((s) => s.toggleCollapsed);
   const toggleShortcuts = useStore((s) => s.toggleShortcuts);
-  const toggleHighlights = useStore((s) => s.toggleHighlights);
-  const highlightEnabled = useStore((s) => s.highlightEnabled);
   const componentCount = useStore((s) => s.components.length);
 
   const openOptions = () => {
@@ -36,15 +35,7 @@ export function Header({ ref }: HeaderProps) {
           {page.isPublished ? 'Published' : 'Draft'}
         </span>
       )}
-      <button
-        className={`cs-icon-btn ${highlightEnabled ? '' : 'cs-icon-btn-off'}`}
-        onClick={toggleHighlights}
-        title={highlightEnabled ? 'Hide outlines (h)' : 'Show outlines (h)'}
-        aria-label={highlightEnabled ? 'Hide outlines' : 'Show outlines'}
-        aria-pressed={!highlightEnabled}
-      >
-        <Icon name={highlightEnabled ? 'eye' : 'eyeOff'} />
-      </button>
+      <HighlightModeMenu />
       <button
         className="cs-icon-btn"
         onClick={toggleShortcuts}
diff --git a/src/content/panel/components/HighlightModeMenu.tsx b/src/content/panel/components/HighlightModeMenu.tsx
new file mode 100644
index 0000000..3c7a2b4
--- /dev/null
+++ b/src/content/panel/components/HighlightModeMenu.tsx
@@ -0,0 +1,99 @@
+import { useEffect, useRef } from 'react';
+import {
+  HIGHLIGHT_MODE_DESCRIPTIONS,
+  HIGHLIGHT_MODE_LABELS,
+  HIGHLIGHT_MODE_ORDER,
+  type HighlightMode,
+} from '@/lib/types';
+import { Icon } from './Icon';
+import { useStore } from '../store';
+
+/**
+ * Header control that surfaces the four highlight modes
+ * (off / selection / editable / all). Uses a native `<details>` disclosure
+ * so we get click-outside-to-close, keyboard activation, and accessibility
+ * for free without a focus-trap library.
+ *
+ * The icon swaps based on the active mode:
+ *   off       → eyeOff (clear "nothing is being shown" affordance)
+ *   selection → eye    (default-state vibe)
+ *   editable  → eye    (also "watching", just narrower)
+ *   all       → eye    (full visibility)
+ *
+ * The mode label sits next to the icon so the active state is glanceable
+ * without opening the menu.
+ */
+export function HighlightModeMenu() {
+  const mode = useStore((s) => s.preferences.highlightMode);
+  const setHighlightMode = useStore((s) => s.setHighlightMode);
+  const detailsRef = useRef<HTMLDetailsElement>(null);
+
+  // Close the menu when the user clicks anywhere outside of it. Without
+  // this, the disclosure happily stays open until the next click on the
+  // summary itself, which feels like a bug compared to every other
+  // popover in the app.
+  useEffect(() => {
+    const onDocClick = (e: MouseEvent) => {
+      const el = detailsRef.current;
+      if (!el || !el.open) return;
+      const path = e.composedPath();
+      if (path.includes(el)) return;
+      el.open = false;
+    };
+    document.addEventListener('click', onDocClick);
+    return () => document.removeEventListener('click', onDocClick);
+  }, []);
+
+  const onPick = (next: HighlightMode) => {
+    setHighlightMode(next);
+    if (detailsRef.current) detailsRef.current.open = false;
+  };
+
+  return (
+    <details className="cs-mode-menu" ref={detailsRef}>
+      <summary
+        className={`cs-icon-btn cs-mode-trigger ${mode === 'off' ? 'cs-icon-btn-off' : ''}`}
+        title={`Highlight: ${HIGHLIGHT_MODE_LABELS[mode]} (h to cycle)`}
+        aria-label={`Highlight mode: ${HIGHLIGHT_MODE_LABELS[mode]}`}
+      >
+        <Icon name={mode === 'off' ? 'eyeOff' : 'eye'} />
+        <span className="cs-mode-trigger-label">{compactLabel(mode)}</span>
+      </summary>
+      <div className="cs-mode-popover" role="menu">
+        <div className="cs-mode-popover-header">Highlight mode</div>
+        {HIGHLIGHT_MODE_ORDER.map((m) => (
+          <button
+            key={m}
+            type="button"
+            role="menuitemradio"
+            aria-checked={mode === m}
+            className={`cs-mode-option ${mode === m ? 'cs-mode-option-active' : ''}`}
+            onClick={() => onPick(m)}
+          >
+            <span className="cs-mode-option-bullet" aria-hidden="true">
+              {mode === m ? '●' : '○'}
+            </span>
+            <span className="cs-mode-option-text">
+              <span className="cs-mode-option-label">{HIGHLIGHT_MODE_LABELS[m]}</span>
+              <span className="cs-mode-option-help">{HIGHLIGHT_MODE_DESCRIPTIONS[m]}</span>
+            </span>
+          </button>
+        ))}
+      </div>
+    </details>
+  );
+}
+
+/** Header real estate is tight, so we abbreviate the label next to the icon. */
+function compactLabel(mode: HighlightMode): string {
+  switch (mode) {
+    case 'off':
+      return 'Off';
+    case 'selection':
+      return 'Sel';
+    case 'editable':
+      return 'Edit';
+    case 'all':
+      return 'All';
+  }
+}
diff --git a/src/content/panel/hooks/useKeyboardShortcuts.ts b/src/content/panel/hooks/useKeyboardShortcuts.ts
index 8e16906..099f8ef 100644
--- a/src/content/panel/hooks/useKeyboardShortcuts.ts
+++ b/src/content/panel/hooks/useKeyboardShortcuts.ts
@@ -37,7 +37,7 @@ export function useKeyboardShortcuts(): void {
         selected,
         toggleShortcuts,
         toggleCollapsed,
-        toggleHighlights,
+        cycleHighlightMode,
         pushToast,
         setActiveTab,
       } = state;
@@ -61,7 +61,7 @@ export function useKeyboardShortcuts(): void {
       }
       if ((e.key === 'h' || e.key === 'H') && !e.metaKey && !e.ctrlKey && !e.altKey) {
         e.preventDefault();
-        toggleHighlights();
+        cycleHighlightMode();
         return;
       }
       if ((e.key === 't' || e.key === 'T') && !e.metaKey && !e.ctrlKey) {
@@ -119,7 +119,7 @@ export function useKeyboardShortcuts(): void {
 export const SHORTCUTS = [
   { keys: ['?'], description: 'Show this shortcut overlay' },
   { keys: ['['], description: 'Collapse / expand the panel' },
-  { keys: ['h'], description: 'Toggle component outlines' },
+  { keys: ['h'], description: 'Cycle highlight mode (off → selection → editable → all)' },
   { keys: ['i'], description: 'Switch to Inspect tab' },
   { keys: ['t'], description: 'Switch to Tree tab' },
   { keys: ['y', 'p'], description: 'Copy current page URI' },
diff --git a/src/content/panel/store.ts b/src/content/panel/store.ts
index 01b035c..5ac4511 100644
--- a/src/content/panel/store.ts
+++ b/src/content/panel/store.ts
@@ -3,10 +3,12 @@ import type {
   Annotation,
   ClayComponentInfo,
   ClayPageInfo,
+  HighlightMode,
   RecentComponent,
   UserPreferences,
 } from '@/lib/types';
-import { DEFAULT_PREFERENCES } from '@/lib/types';
+import { DEFAULT_PREFERENCES, HIGHLIGHT_MODE_ORDER } from '@/lib/types';
+import { savePreferences } from '@/lib/storage';
 import { readPageInfo } from '../page-info';
 
 export type PanelTab = 'inspect' | 'tree' | 'json' | 'diff' | 'seo' | 'notes';
@@ -32,7 +34,6 @@ interface StoreState {
   find: FindState;
   activeTab: PanelTab;
   showShortcuts: boolean;
-  highlightEnabled: boolean;
   preferences: UserPreferences;
   toasts: ToastMessage[];
   recents: RecentComponent[];
@@ -47,7 +48,17 @@ interface StoreState {
   setFind: (next: FindState) => void;
   setActiveTab: (tab: PanelTab) => void;
   toggleShortcuts: () => void;
-  toggleHighlights: () => void;
+  /**
+   * Update the ambient-outline mode. Persists to chrome.storage.sync so
+   * the choice survives reloads and propagates to other tabs.
+   */
+  setHighlightMode: (mode: HighlightMode) => void;
+  /**
+   * Cycle through the four modes in `HIGHLIGHT_MODE_ORDER`. Bound to the
+   * `h` keyboard shortcut for muscle memory with the old "toggle outlines"
+   * behavior.
+   */
+  cycleHighlightMode: () => void;
   setPreferences: (next: Partial<UserPreferences>) => void;
   setRecents: (next: RecentComponent[]) => void;
   setAnnotations: (next: Annotation[]) => void;
@@ -70,7 +81,6 @@ export const useStore = create<StoreState>()((set) => ({
   find: { query: '', index: 0 },
   activeTab: 'inspect',
   showShortcuts: false,
-  highlightEnabled: true,
   preferences: DEFAULT_PREFERENCES,
   toasts: [],
   recents: [],
@@ -85,7 +95,16 @@ export const useStore = create<StoreState>()((set) => ({
   setFind: (find) => set({ find }),
   setActiveTab: (activeTab) => set({ activeTab }),
   toggleShortcuts: () => set((s) => ({ showShortcuts: !s.showShortcuts })),
-  toggleHighlights: () => set((s) => ({ highlightEnabled: !s.highlightEnabled })),
+  setHighlightMode: (mode) => {
+    set((s) => ({ preferences: { ...s.preferences, highlightMode: mode } }));
+    void savePreferences({ highlightMode: mode });
+  },
+  cycleHighlightMode: () => {
+    const current = useStore.getState().preferences.highlightMode;
+    const idx = HIGHLIGHT_MODE_ORDER.indexOf(current);
+    const next = HIGHLIGHT_MODE_ORDER[(idx + 1) % HIGHLIGHT_MODE_ORDER.length] ?? 'selection';
+    useStore.getState().setHighlightMode(next);
+  },
   setPreferences: (prefs) => set((s) => ({ preferences: { ...s.preferences, ...prefs } })),
   setRecents: (recents) => set({ recents }),
   setAnnotations: (annotations) =>
diff --git a/src/content/panel/styles.css b/src/content/panel/styles.css
index 2201cf4..90bb1fa 100644
--- a/src/content/panel/styles.css
+++ b/src/content/panel/styles.css
@@ -188,6 +188,103 @@
   color: var(--cs-text-subtle);
 }
 
+/* ── Highlight-mode menu (header dropdown) ─────────────────────────────
+   Built on a native <details> for click-outside / keyboard / a11y for free.
+   The summary doubles as an .cs-icon-btn so it visually blends with the
+   sibling header buttons; the popover sits absolutely positioned beneath. */
+.cs-mode-menu {
+  position: relative;
+}
+
+.cs-mode-menu > summary {
+  list-style: none;
+  cursor: pointer;
+  gap: 4px;
+}
+
+.cs-mode-menu > summary::-webkit-details-marker {
+  display: none;
+}
+
+.cs-mode-trigger-label {
+  font-size: 11px;
+  font-weight: 500;
+  color: inherit;
+  letter-spacing: 0.01em;
+}
+
+.cs-mode-popover {
+  position: absolute;
+  top: calc(100% + 6px);
+  right: 0;
+  min-width: 240px;
+  background: var(--cs-bg);
+  border: 1px solid var(--cs-border);
+  border-radius: 8px;
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.06),
+    0 8px 24px rgba(0, 0, 0, 0.08);
+  padding: 6px;
+  z-index: 10;
+}
+
+.cs-mode-popover-header {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--cs-text-subtle);
+  padding: 4px 8px 6px;
+}
+
+.cs-mode-option {
+  display: flex;
+  gap: 8px;
+  width: 100%;
+  background: transparent;
+  border: none;
+  text-align: left;
+  padding: 6px 8px;
+  border-radius: 6px;
+  cursor: pointer;
+  color: var(--cs-text);
+  font: inherit;
+}
+
+.cs-mode-option:hover {
+  background: var(--cs-bg-hover);
+}
+
+.cs-mode-option-active {
+  background: var(--cs-accent-bg);
+}
+
+.cs-mode-option-bullet {
+  flex: 0 0 auto;
+  width: 12px;
+  text-align: center;
+  color: var(--cs-accent);
+  font-size: 10px;
+  line-height: 1.5;
+}
+
+.cs-mode-option-text {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  min-width: 0;
+}
+
+.cs-mode-option-label {
+  font-size: 12px;
+  font-weight: 500;
+}
+
+.cs-mode-option-help {
+  font-size: 11px;
+  color: var(--cs-text-muted);
+  line-height: 1.35;
+}
+
 .cs-tabs {
   display: flex;
   gap: 0;
diff --git a/src/lib/types.ts b/src/lib/types.ts
index 842bcf7..4693786 100644
--- a/src/lib/types.ts
+++ b/src/lib/types.ts
@@ -32,6 +32,42 @@ export type PanelPosition =
   | 'left-side'
   | 'right-side';
 
+/**
+ * Controls *which* components show an ambient outline on the page.
+ * Hover and selection always render their own highlight regardless of mode
+ * (otherwise click-to-inspect would be invisible).
+ *
+ * - `off`        – no ambient outlines at all. Hover + selection still highlight.
+ * - `selection`  – ambient is off; only the hovered/selected element is outlined.
+ *                  This is the new default — feels closest to Chrome DevTools.
+ * - `editable`   – ambient outlines on `[data-editable]` components only.
+ *                  Useful for editorial / PM workflows.
+ * - `all`        – ambient outlines on every component.
+ *                  The "give me the bird's-eye view of structure" mode.
+ */
+export type HighlightMode = 'off' | 'selection' | 'editable' | 'all';
+
+export const HIGHLIGHT_MODE_ORDER: readonly HighlightMode[] = [
+  'off',
+  'selection',
+  'editable',
+  'all',
+];
+
+export const HIGHLIGHT_MODE_LABELS: Readonly<Record<HighlightMode, string>> = {
+  off: 'Off',
+  selection: 'Selection only',
+  editable: 'Editable only',
+  all: 'All components',
+};
+
+export const HIGHLIGHT_MODE_DESCRIPTIONS: Readonly<Record<HighlightMode, string>> = {
+  off: 'No outlines anywhere. The panel still works for inspection.',
+  selection: 'Only the component you hover or click gets an outline.',
+  editable: 'Subtle outlines on every editable component.',
+  all: 'Subtle outlines on every Clay component.',
+};
+
 export interface UserPreferences {
   readonly theme: 'auto' | 'light' | 'dark';
   readonly panelPosition: PanelPosition;
@@ -39,6 +75,7 @@ export interface UserPreferences {
   readonly panelHeight: number;
   readonly defaultEnvironment: Environment;
   readonly environments: EnvironmentHosts;
+  readonly highlightMode: HighlightMode;
   readonly highlightOpacity: number;
   readonly enableShortcuts: boolean;
   readonly maxRecentComponents: number;
@@ -86,6 +123,7 @@ export const DEFAULT_PREFERENCES: UserPreferences = {
   panelHeight: 540,
   defaultEnvironment: 'prod',
   environments: DEFAULT_ENVIRONMENT_HOSTS,
+  highlightMode: 'selection',
   highlightOpacity: 0.85,
   enableShortcuts: true,
   maxRecentComponents: 20,
diff --git a/src/options/Options.tsx b/src/options/Options.tsx
index 159776c..a2fe77d 100644
--- a/src/options/Options.tsx
+++ b/src/options/Options.tsx
@@ -7,10 +7,14 @@ import {
   DEFAULT_PREFERENCES,
   ENVIRONMENT_LABELS,
   ENVIRONMENT_ORDER,
+  HIGHLIGHT_MODE_DESCRIPTIONS,
+  HIGHLIGHT_MODE_LABELS,
+  HIGHLIGHT_MODE_ORDER,
   SITE_ENV_LABELS,
   SITE_ENV_ORDER,
   type Environment,
   type EnvironmentHosts,
+  type HighlightMode,
   type PanelPosition,
   type SiteEnv,
   type SiteHostMapping,
@@ -162,11 +166,32 @@ export function Options() {
           />
         </label>
 
+        <label className="options-row">
+          <div className="options-label">
+            <span>Highlight mode</span>
+            <span className="options-help">
+              {HIGHLIGHT_MODE_DESCRIPTIONS[prefs.highlightMode]} You can also press <kbd>h</kbd> on
+              any Clay page to cycle through modes.
+            </span>
+          </div>
+          <select
+            value={prefs.highlightMode}
+            onChange={(e) => update('highlightMode', e.target.value as HighlightMode)}
+          >
+            {HIGHLIGHT_MODE_ORDER.map((m) => (
+              <option key={m} value={m}>
+                {HIGHLIGHT_MODE_LABELS[m]}
+              </option>
+            ))}
+          </select>
+        </label>
+
         <label className="options-row">
           <div className="options-label">
             <span>Highlight intensity</span>
             <span className="options-help">
-              Outline opacity for component boundaries on the page.
+              Master opacity multiplier for every outline. Useful for taming the &ldquo;all
+              components&rdquo; mode on dense pages without changing the mode itself.
             </span>
           </div>
           <input
diff --git a/tests/content/highlighter.test.ts b/tests/content/highlighter.test.ts
new file mode 100644
index 0000000..8651753
--- /dev/null
+++ b/tests/content/highlighter.test.ts
@@ -0,0 +1,236 @@
+/**
+ * Behavioral tests for the highlighter.
+ *
+ * The highlighter is mostly CSS, so most of these assertions check the
+ * *attributes* it sets (which the stylesheet keys off of) rather than
+ * computed style — happy-dom doesn't run our `!important` outline rules
+ * through a real layout engine, so testing computed style would be flaky.
+ *
+ * What we DO test:
+ *   - applyHighlights tags every element with the presence flag
+ *   - applyHighlights stashes the label for the selection badge to read
+ *   - clearHighlights wipes every highlight attribute we set
+ *   - setHighlightMode flips the documentElement attribute the CSS keys on
+ *   - setHovered / setSelected toggle exactly one element at a time
+ *   - setAnnotatedUris syncs based on the URI set, not element identity
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  applyHighlights,
+  clearHighlights,
+  getHighlightMode,
+  installHighlightStyles,
+  setAnnotatedUris,
+  setHighlightMode,
+  setHighlightOpacity,
+  setHovered,
+  setSelected,
+} from '@/content/highlighter';
+
+const HIGHLIGHT_ATTR = 'data-clay-slip-color';
+const SELECTED_ATTR = 'data-clay-slip-selected';
+const HOVER_ATTR = 'data-clay-slip-hover';
+const ANNOTATED_ATTR = 'data-clay-slip-annotated';
+const LABEL_ATTR = 'data-clay-slip-label';
+const MODE_ATTR = 'data-clay-slip-mode';
+
+function makeComponent(uri: string, opts: { editable?: boolean } = {}): HTMLElement {
+  const el = document.createElement('div');
+  el.setAttribute('data-uri', uri);
+  if (opts.editable) el.setAttribute('data-editable', '');
+  document.body.appendChild(el);
+  return el;
+}
+
+beforeEach(() => {
+  document.head.innerHTML = '';
+  document.body.innerHTML = '';
+  document.documentElement.removeAttribute(MODE_ATTR);
+  document.documentElement.style.cssText = '';
+});
+
+afterEach(() => {
+  // Tear down any styles we installed so each test starts fresh.
+  document.head.innerHTML = '';
+  document.body.innerHTML = '';
+  document.documentElement.removeAttribute(MODE_ATTR);
+});
+
+describe('installHighlightStyles', () => {
+  it('inserts a single style tag and is idempotent', () => {
+    installHighlightStyles();
+    installHighlightStyles();
+    installHighlightStyles();
+    expect(document.querySelectorAll('#clay-slip-highlight-styles')).toHaveLength(1);
+  });
+
+  it('starts in selection mode when no mode was previously set', () => {
+    installHighlightStyles();
+    expect(document.documentElement.getAttribute(MODE_ATTR)).toBe('selection');
+  });
+
+  it('preserves a pre-existing mode (so reinstall does not stomp the user choice)', () => {
+    setHighlightMode('all');
+    installHighlightStyles();
+    expect(document.documentElement.getAttribute(MODE_ATTR)).toBe('all');
+  });
+});
+
+describe('applyHighlights', () => {
+  it('tags every element with the presence flag', () => {
+    const a = makeComponent('a');
+    const b = makeComponent('b');
+    applyHighlights([a, b]);
+    expect(a.hasAttribute(HIGHLIGHT_ATTR)).toBe(true);
+    expect(b.hasAttribute(HIGHLIGHT_ATTR)).toBe(true);
+  });
+
+  it('writes labels in the same index as the element array', () => {
+    const a = makeComponent('a');
+    const b = makeComponent('b');
+    applyHighlights([a, b], ['Header', 'Story Tile']);
+    expect(a.getAttribute(LABEL_ATTR)).toBe('Header');
+    expect(b.getAttribute(LABEL_ATTR)).toBe('Story Tile');
+  });
+
+  it('skips the label attribute when no label is given', () => {
+    const a = makeComponent('a');
+    applyHighlights([a]);
+    expect(a.hasAttribute(LABEL_ATTR)).toBe(false);
+  });
+
+  it('does not write a label when the entry is empty string', () => {
+    // Useful invariant — the CSS uses `[selected][label]` to gate the badge,
+    // so an empty-string label would still match the selector and render
+    // an empty pill. We require non-empty.
+    const a = makeComponent('a');
+    applyHighlights([a], ['']);
+    expect(a.hasAttribute(LABEL_ATTR)).toBe(false);
+  });
+});
+
+describe('clearHighlights', () => {
+  it('removes every highlight-related attribute', () => {
+    const a = makeComponent('a');
+    applyHighlights([a], ['Header']);
+    setSelected(null, a);
+    setHovered(null, a);
+    a.setAttribute(ANNOTATED_ATTR, '');
+    clearHighlights([a]);
+    expect(a.hasAttribute(HIGHLIGHT_ATTR)).toBe(false);
+    expect(a.hasAttribute(SELECTED_ATTR)).toBe(false);
+    expect(a.hasAttribute(HOVER_ATTR)).toBe(false);
+    expect(a.hasAttribute(ANNOTATED_ATTR)).toBe(false);
+    expect(a.hasAttribute(LABEL_ATTR)).toBe(false);
+  });
+});
+
+describe('setHighlightMode / getHighlightMode', () => {
+  it('round-trips each valid mode', () => {
+    for (const m of ['off', 'selection', 'editable', 'all'] as const) {
+      setHighlightMode(m);
+      expect(getHighlightMode()).toBe(m);
+    }
+  });
+
+  it('falls back to selection when the attribute is absent or garbage', () => {
+    expect(getHighlightMode()).toBe('selection');
+    document.documentElement.setAttribute(MODE_ATTR, 'wat');
+    expect(getHighlightMode()).toBe('selection');
+  });
+
+  it('writes "off" as an explicit value (not removed) so the stylesheet can target it', () => {
+    // The current CSS only matches positive modes ("all", "editable"), so an
+    // absent attribute would also work — but writing "off" explicitly keeps
+    // the option open to add an `[mode="off"]` rule later (e.g. for diagnostics).
+    setHighlightMode('off');
+    expect(document.documentElement.getAttribute(MODE_ATTR)).toBe('off');
+  });
+});
+
+describe('setSelected / setHovered', () => {
+  it('moves the selected attribute from prev to next', () => {
+    const a = makeComponent('a');
+    const b = makeComponent('b');
+    setSelected(null, a);
+    expect(a.hasAttribute(SELECTED_ATTR)).toBe(true);
+    setSelected(a, b);
+    expect(a.hasAttribute(SELECTED_ATTR)).toBe(false);
+    expect(b.hasAttribute(SELECTED_ATTR)).toBe(true);
+  });
+
+  it('moves the hover attribute from prev to next', () => {
+    const a = makeComponent('a');
+    const b = makeComponent('b');
+    setHovered(null, a);
+    setHovered(a, b);
+    expect(a.hasAttribute(HOVER_ATTR)).toBe(false);
+    expect(b.hasAttribute(HOVER_ATTR)).toBe(true);
+  });
+
+  it('clears with a null next value', () => {
+    const a = makeComponent('a');
+    setSelected(null, a);
+    setSelected(a, null);
+    expect(a.hasAttribute(SELECTED_ATTR)).toBe(false);
+  });
+});
+
+describe('setAnnotatedUris', () => {
+  it('only flags elements whose URI is in the set', () => {
+    const a = makeComponent('a');
+    const b = makeComponent('b');
+    const c = makeComponent('c');
+    setAnnotatedUris([a, b, c], new Set(['a', 'c']));
+    expect(a.hasAttribute(ANNOTATED_ATTR)).toBe(true);
+    expect(b.hasAttribute(ANNOTATED_ATTR)).toBe(false);
+    expect(c.hasAttribute(ANNOTATED_ATTR)).toBe(true);
+  });
+
+  it('removes the flag when the URI drops out of the set', () => {
+    const a = makeComponent('a');
+    setAnnotatedUris([a], new Set(['a']));
+    setAnnotatedUris([a], new Set());
+    expect(a.hasAttribute(ANNOTATED_ATTR)).toBe(false);
+  });
+});
+
+describe('setHighlightOpacity', () => {
+  it('clamps to [0, 1] so a slider bug cannot push outlines off-screen', () => {
+    setHighlightOpacity(-5);
+    expect(document.documentElement.style.getPropertyValue('--clay-slip-outline-opacity')).toBe(
+      '0'
+    );
+    setHighlightOpacity(99);
+    expect(document.documentElement.style.getPropertyValue('--clay-slip-outline-opacity')).toBe(
+      '1'
+    );
+    setHighlightOpacity(0.42);
+    expect(document.documentElement.style.getPropertyValue('--clay-slip-outline-opacity')).toBe(
+      '0.42'
+    );
+  });
+});
+
+describe('mode + editable interaction (CSS gating contract)', () => {
+  // The actual visual gating happens in the stylesheet, but we can at least
+  // verify the *contract* the CSS depends on:
+  //   - 'all' mode: every component carries the presence attr
+  //   - 'editable' mode: editable components carry the presence attr AND
+  //     the data-editable attr (the CSS combines them)
+  //   - 'selection'/'off' modes: the CSS doesn't match; we don't have to
+  //     remove the presence flag.
+  it('preserves data-editable attribute through apply + clear cycles', () => {
+    const editable = makeComponent('e', { editable: true });
+    const plain = makeComponent('p');
+    applyHighlights([editable, plain], ['Editable', 'Plain']);
+    expect(editable.hasAttribute('data-editable')).toBe(true);
+    expect(plain.hasAttribute('data-editable')).toBe(false);
+
+    clearHighlights([editable, plain]);
+    // We deliberately do NOT touch data-editable in clearHighlights — that
+    // attribute is part of the host page's data contract, not ours.
+    expect(editable.hasAttribute('data-editable')).toBe(true);
+    expect(plain.hasAttribute('data-editable')).toBe(false);
+  });
+});