Skip to content

zero-dep vanilla viewer - #263

Draft
paulirish wants to merge 51 commits into
masterfrom
newview
Draft

zero-dep vanilla viewer#263
paulirish wants to merge 51 commits into
masterfrom
newview

Conversation

@paulirish

@paulirish paulirish commented Sep 8, 2026

Copy link
Copy Markdown
Member

Replaces the legacy static site generator stack (Eleventy, Rollup, Handlebars, Lit-HTML) with a zero-dependency client-side modern web app. Protocol is fetched and rendered dynamically, eliminating build-time html generation and maintenance issues.... and yet we still get backward compatibility for all existing external permalinks. (thx to 404.html trickery)

staged here: https://chromedevtools.github.io/debugger-protocol-viewer/

What Changed & Why

  • Killed the SSG build step: Dropped Eleventy, Rollup, and Handlebars entirely. The app is now a zero-dep static client that pulls protocol JSON directly from GitHub / CDN and renders in-browser. When new CDP domains land in Chromium, there is zero build or deploy dance required.
  • Isomorphic core in protocol-model.js: Protocol normalization, deterministic sorting (standard > experimental > deprecated), stabilization, and routing logic are pure functions with zero DOM baggage. They run identically in the browser and in Node for tests.
  • Type reverse-dependencies ("Used by"): Finally closes #183. We index $ref usages on the fly and render a direct "Used by" back-reference list on every type card pointing back to referencing commands, events, and types.
  • Zero-reload target switching: Pinned left-nav selector swaps datasets dynamically between Tip-of-Tree, Stable (1.3), and V8 Inspector (Node.js) in-memory without resetting scroll or tearing down the shell.
  • Rock-solid permalink preservation: We can't break ten years of incoming links across StackOverflow and chromium bugs.
    • Static stubs (tot/<Domain>/index.html) handle direct hits and unpack legacy hash anchors (#method-foo#/Page.navigate), with <noscript> trees for crawlers.
    • 404.html catches older version paths (/1-3/*, /1-2/*, /v8/*) and repo prefixes.
    • Route resolution is standardized on the native Web URLPattern API instead of hand-rolled regex string munging.
  • UI cleanup & search:
    • Sticky header with fuzzy search (src/search.js), instant keyboard activation (/ or Cmd+K), and arrow-key selection.
    • TOC refactored to native CSS columns (columns: 320px) with intrinsic pill widths and entity badges.
    • Dropped the pink .experimental-bg card tinting across methods/types (it was drowning out content) in favor of clean cards with discrete exp pills.
    • Mobile gets a proper accessible drawer overlay (< 800px).
  • Modern testing & toolchain: Switched to pnpm, oxlint (runs in 20ms), oxfmt, and buildless JSDoc typechecking via tsc --noEmit. The test suite runs entirely on native node:test —including autonomous E2E tests that spawn headless Chrome and drive CDP over raw WebSockets in ~1.4s. YEAH, straight CDP in our browser tests heck yess.

Visual Preview

Desktop Overview (#/Page) Clean Cards without Background Tinting (#/Audits)
viewer-page-desktop viewer-audits-clean-cards
Routing & Compatibility Matrix
Request URL / Legacy Permalink Destination Hash Route Handling Layer
/tot/Page/ #/Page tot/Page/index.html stub
/tot/Page/#method-navigate #/Page.navigate tot/Page/index.html stub
/tot/DOM/#type-Node #/DOM.Node tot/DOM/index.html stub
/tot/Network/#event-requestWillBeSent #/Network.requestWillBeSent tot/Network/index.html stub
/v8/Runtime/ #/v8/Runtime 404.html catch-all
/1-3/Page/#method-navigate #/stable/Page.navigate 404.html catch-all
/1-2/Network/ #/stable/Network 404.html catch-all
/devtools-protocol/tot/Page/#method-navigate #/Page.navigate 404.html catch-all
/debugger-protocol-viewer/tot/Page/#method-navigate #/Page.navigate 404.html catch-all
?Page.navigate #/Page.navigate parseRoute (URLPattern)

Thank you to lushnikov for making https://github.com/aslushnikov/vanilla-protocol-viewer/ forever ago.

Greetz https://github.com/ChromeDevTools/debugger-protocol-viewer/blob/c933752341238fbea6cef49fe1eed3dc3ae0270c/PLAN.md

@OrKoN

OrKoN commented Sep 9, 2026

Copy link
Copy Markdown
Collaborator

Switched to pnpm

Would it still work with npm?

Comment thread package.json
Comment on lines +29 to +31
"oxfmt": "^0.67.0",
"oxlint": "^1.82.0",
"statikk": "^3.1.0",

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we truly need these (we would have to keep them updated etc, work around issues or bugs): maybe we can drop these deps and not having a dedicated formatter/linter is not that bad?

Comment thread src/main.js
import { ProtocolRenderer } from './protocol_renderer.js';
import { Search } from './search.js';

const PROTOCOL_URLS = {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think maybe we should not use an external CDN? Can we use our own data?

Comment thread src/main.js
if (!this._activeDomains.has(domain)) {
const landingId = domain === 'http-endpoints' ? 'endpoints' : domain;
const landingTemplate = /** @type {HTMLTemplateElement|null} */ ($('#landing'));
if (landingTemplate && landingTemplate.content.querySelector('#' + landingId)) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably use getElementById or CSS.escape here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Include cross-references

2 participants