🍕 v2.0: full rewrite — MV3, TypeScript + React, Shadow DOM, FAB, cross-env tooling

[jjpaulino]

Summary

This PR is a full rewrite of clay-devtools (Clay Slip), delivered as a series of focused commits on top of the original 2018 Manifest V2 vanilla-JS extension.

It ships a modern, fully typed, fully tested Chrome extension built on Manifest V3 + TypeScript 6 + React 19 + Vite 8 + Vitest 4 + Zustand 5, runs on Node 24 LTS, fixes the original bugs, and adds a long list of new features tailored to both devs and product managers.

• ✅ 84 unit tests passing, 0 lint warnings, 0 type errors, 0 format issues
• ✅ GitHub Actions CI runs typecheck / lint / format / test / build on every PR
• ✅ Production build (npm run build) is load-unpacked-ready in dist/
• ✅ Every shortcut and capability of v1 is preserved

What's new (v2)

Floating button + panel

• Floating Clay button (FAB) in the bottom-right corner is the new default surface — one click opens the full panel, escape / collapse returns to the FAB. Lives in a Shadow DOM so the page can never style it.
• Resizable + dockable panel — drag the inner edge for width, the bottom edge for height, the corner for both; clamped to sensible bounds and persisted per user. Pick any of four corners or full-height left/right side dock.
• Auto / light / dark themes that respond to OS theme changes live.
• Toolbar badge with the count of [data-uri] elements on the current page (cleared on navigation).

Inspect & navigate

• Manifest V3 Chrome extension with a service worker.
• Shadow-DOM panel — React mounted in attachShadow({ mode: 'open' }) so host-page CSS never bleeds in.
• Component tree + breadcrumbs, click any row or page element to select & scroll.
• Inline JSON preview with syntax highlighting and per-(host, URI) caching.
• Click-through-aware selection — selects the component but lets real <a> / <button> / <input> clicks go through.
• Find-on-page — Tree search dims non-matches on the page, shows match counter, Enter cycles next, Shift+Enter previous, Esc clears.
• Recently viewed components persisted across sessions (configurable cap).
• Toggleable component outlines (eye icon, h shortcut) with configurable opacity slider.

Edit, share, screenshot

• Open in Clay editor — Edit button on the Page section opens the parent page in editor mode at the unpublished version (strips @published so the editor can actually save).
• Sticky-note annotations pinned to component URIs (chrome.storage.local); show as an orange dot on the page and a Notes tab listing every note across pages.
• Shareable selection links — Share button copies a ?clay-slip-select=… URL that auto-opens Slip and selects the same component on someone else's machine. Reads location.href at click time so SPA nav can never produce a stale link.
• Component screenshot to clipboard — captureVisibleTab + canvas crop scaled by devicePixelRatio, panel auto-hides during capture.

Cross-environment tooling

• Configurable site host mappings in Settings — declare prod / staging / qa hostnames per brand.
• "View on …" pills on the Page section jump to the equivalent URL on another env (preserving path / query / hash).
• Split Share button — when mappings are configured, a ▾ menu adds one entry per cross-env target, copying a share link rewritten to that env's host.
• Environment switcher pill + per-env host config in Settings; every link, fetch, cURL, and shortcut routes through the active env's host.
• Cross-environment diff — pick another configured env from the Compare: select to diff the same URI across hosts.

Compare & diff

• Published vs Draft diff for any @published selection.
• Cross-environment diff as above.

SEO & audit (PMs love these)

• SEO tab — <title> / description / canonical / robots / og:* / twitter:* / JSON-LD with Twitter + Facebook/Slack card previews and lints (length, missing og:image, duplicate <h1>, etc.); live updates via MutationObserver.
• Page audit export — Export ▾ button on the Inspect tab → JSON / CSV / Markdown of every component on the page, copied to clipboard (no file downloads — paste straight into a ticket).

Ergonomics

• Copy-as menu: URI / cURL / fetch() snippet / CSS selector — all env-host aware.
• Keyboard shortcut overlay triggered by ?. Shortcuts are gated by composedPath() so typing t in a note input doesn't switch tabs.
• Smart popup: friendly "Not a Clay page" popup on non-Clay pages, gets out of the way on Clay pages so the icon click toggles the panel.
• Full Options page for theme, dock side + width + height, env hosts, site host mappings, highlight intensity, recents history size, and shortcut toggle.

What it looks like

Inspect tab

Tree tab

Options page

Bugs fixed from the original Slip + audit

• Implicit globals in evaluateKeystroke (e.g. uri, opts) — entirely rewritten as a typed React hook.
• Duplicate hiddenInput declaration — gone, clipboard goes through navigator.clipboard.write[Text] with a tested legacy fallback.
• getPageInstance(...).replace(...) could throw on null — every URI utility is now a total function.
• Highlight palette only generated 5 of 6 colors — fixed.
• Imperative chrome.tabs.executeScript — replaced by an MV3-native content script + message-passing model.
• Outlines weren't painted on first page load — now applied during bootstrap.
• Auto-theme listener was a no-op when the OS theme changed — now actually re-renders.
• Click-to-select hijacked all link clicks — now respects <a> / <button> / <input> / contenteditable.
• Tree-row hover did nothing — now uses the highlighter's hover outline.
• Toolbar badge wasn't cleared on SPA / non-Clay navigation — tabs.onUpdated clears it now.
• Settings button was a no-op — chrome.runtime.openOptionsPage() isn't callable from a content script; routed through the service worker.
• Collapsed panel had no way to re-expand — replaced by the FAB, which is always available and one click away from the full panel.
• Edit button opened the published URL — now strips @published so the editor opens the editable version.
• Keyboard shortcuts fired while typing in notes — composedPath() now correctly detects inputs inside the Shadow DOM.
• FAB icon failed to load on host pages — image is now inlined as a base64 data URL via Vite's ?inline, so no cross-origin asset fetch.

Architecture

src/
├── manifest.ts             # MV3 manifest in TypeScript
├── background/
│   └── service-worker.ts   # Open tabs, badge, screenshot capture, popup toggling
├── content/
│   ├── index.ts            # Bootstrap + deep-link selection + message handling
│   ├── highlighter.ts      # Outline / hover / selected / annotated / match styling
│   ├── shadow-host.ts      # Mounts React app inside a Shadow DOM
│   ├── page-info.ts        # Reads Clay metadata
│   └── panel/              # The React panel UI
│       ├── App.tsx
│       ├── store.ts        # Zustand store
│       ├── theme.ts        # Light / dark tokens
│       ├── styles.css      # Shadow-scoped styles
│       ├── components/     # Fab, Tabs, Tree, JSON viewer, Diff, Breadcrumb,
│       │                   # SEO, Notes, Recents, Resize, Export, ShareMenu, ...
│       └── hooks/          # Drag, theme, shortcuts, selection
├── popup/                  # "Not a Clay page" popup
├── options/                # Full options page (incl. site host mappings UI)
├── assets/
│   └── clay-icon.png       # FAB + header logo (inlined as data URL at build time)
└── lib/                    # Pure utilities
    ├── clay-uri.ts         # parsing + buildUrl/buildEditorUrl/buildShareLink + copy-as helpers
    ├── clipboard.ts        # Modern + legacy clipboard
    ├── site-host.ts        # findMappingForHost / rewriteUrlToEnv / availableEnvsFor
    ├── storage.ts          # User preferences in chrome.storage.sync
    ├── annotations.ts      # Sticky notes per URI in chrome.storage.local
    ├── recents.ts          # Recently viewed history
    ├── exporter.ts         # Page manifest → JSON / CSV / Markdown
    ├── seo.ts              # Document head extractor + linter
    ├── screenshot.ts       # captureVisibleTab + crop → clipboard PNG
    └── types.ts            # Shared types + DEFAULT_PREFERENCES

Configuration: site host mappings

Open the Options page → Site host mappings to declare brand → env hostnames, e.g.:

Label	Prod	Staging	QA
Cut	www.thecut.com	stg.thecut.com	qa.thecut.com
Vulture	www.vulture.com	stg.vulture.com	qa.vulture.com

Once configured:

• PageInfo shows "View on: prod / staging / qa" pills that swap the host of the current URL.
• Share menu offers cross-env share links.
• Diff offers cross-env diffs.

Migration notes (1.0 → 2.0)

This release is a full rewrite, but no end-user features were dropped. The keyboard model (y+p / y+c / o+p / o+c) is preserved verbatim and now lives in the ? overlay alongside new bindings.

• Node 24 LTS (.nvmrc pinned, engines.node = ">=24")
• MV2 → MV3 (service worker, chrome.action, chrome.scripting)
• Vanilla JS → TypeScript 6 + React 19 inside Shadow DOM
• No build → npm install && npm run build
• 0 tests → 84 Vitest tests

Test plan

CI runs all of these on every push and PR:

• npm run typecheck (tsc --noEmit, strict)
• npm run lint (--max-warnings=0, react-hooks v7 strict rules)
• npm run format:check (Prettier)
• npm run test — 84 tests passing
• npm run build — valid dist/ with MV3 manifest

Manual smoke test (load unpacked from dist/):

• Visit a non-Clay page → click the icon → "Not a Clay page" popup
• Visit a Clay page → outlines appear immediately, badge shows count, FAB appears in bottom-right
• Click FAB → panel opens; click Collapse in the header → panel closes back to FAB
• Press h → outlines hide; press again → return
• Click an interactive <a> inside a component → navigation still works
• Tree tab → search dims non-matches on the page; Enter cycles
• Type letters into the Notes textarea → shortcuts do not fire (no tab switching)
• JSON tab → fetched, syntax-highlighted, copy works
• Diff tab → Published vs Draft on a @published selection
• Diff tab → Compare: switches to a configured env diff
• Page section Edit → opens the page in editor mode at the unpublished version (no @published)
• Component section: no Edit button (intentional)
• Component Share → toast confirms copy + correct URL on the clipboard
• With site mappings configured: Share ▾ shows cross-env entries; PageInfo shows View-on pills
• Screenshot button → PNG in clipboard; panel was hidden during capture
• Annotation note → saved → orange dot appears on the page → Notes tab lists it
• Export ▾ → JSON / CSV / MD all copy to clipboard
• SEO tab → previews populate, lint warnings are accurate
• Recently viewed → past selections persist across reloads
• Drag the panel inner edge → width resizes; drag bottom edge → height; drag corner → both
• Settings → dock to "Right side (full height)" → panel becomes a sidebar
• Settings → add site host mappings → cross-env pills + share entries appear
• OS theme switch in auto → panel re-themes live

Made with Cursor