跪拜 Guibai
← All articles
Frontend · AI Programming · Chrome

Chrome's Modern Web Guidance 1.0, Torn Open: 0.77s Offline Retrieval, a Scanner Blind to Most Legacy Code, Telemetry On by Default

By Flynt ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Frontend AI agents now have an agreed cross-browser baseline with version-pinned fallbacks, and the cost of that consensus is default-on telemetry plus a scanner that only covers a fifth of the guidance corpus. Teams wiring agents into frontend workflows get free offline retrieval and precise findings, but must set one environment variable and keep low expectations for coverage.

Summary

Modern Web Guidance hit 1.0 on November 10 with Edge, Firefox, and MDN teams on the maintainer list, effectively settling a cross-browser baseline for what AI coding agents should treat as modern frontend practice. The npm package weighs 16.5MB and embeds int8-quantized embedding indexes, so semantic search runs fully offline. A search-plus-retrieve round trip completes in 0.77 seconds including npx startup time.

Guide entries follow a consistent shape: version-pinned browser support notes, hard directives like MANDATORY and DO NOT, and explicit fallback strategy written for agents to execute directly. SKILL.md forces agents to issue 2-to-5-word, action-oriented queries without framework names like React or Vue. The legacy scanner is deterministic rule matching with 35 rules across 33 guides, roughly 20% of the corpus, and file-level guards suppress valid findings: one standard scrollbar-width declaration in a stylesheet hides every ::-webkit-scrollbar hit in that file.

Telemetry defaults to on: isTelemetryEnabled() returns true unless DISABLE_TELEMETRY=1 is set, and the payload includes raw search query text, guide IDs, agent names, OS, and latency buckets sent to Google's clearcut endpoint. Releases lag the source repo, which holds 252 guides and 51 rules, so structured-clone detection exists upstream but is absent from the published package.

Takeaways
— Modern Web Guidance is a 16.5MB npm package at version 1.0.0 that embeds int8-quantized embedding indexes, making retrieval fully offline with no API key.
— A search-plus-retrieve round trip completes in 0.77 seconds, including npx package parsing time.
— The npm package ships 35 rules across 33 guides; the source repo holds 252 guides and 51 rules, so the official 203-guide count refers to the release-line figure.
— SKILL.md restricts agent queries to 2-to-5-word, action-oriented searches and bans framework names like React or Vue; compound requests must be split into two searches.
— The scanner runs deterministic rule matching with file-level guards: a single scrollbar-width or scrollbar-color property in a stylesheet suppresses every ::-webkit-scrollbar finding in that file.
— Telemetry defaults to on: isTelemetryEnabled() returns true unless DISABLE_TELEMETRY=1 is set, sending raw search queries, matched guide IDs, agent names (Claude Code, Codex, Devin are detected specifically), OS, and latency buckets to Google's clearcut endpoint.
— Each scanner hit carries keepWhen/dropWhen verification criteria for the agent or a human to double-check before acting.
— The structured-clone rule that recognizes JSON.parse(JSON.stringify()) exists in the source repo but is missing from the published package.
— Parsing failures in supported file formats must be visibly reported rather than silently counted as zero findings, though the skip-tracking code is not fully wired up yet.
— Google reports agent pass rates rising from about 50% to about 90% with the guides; Japan's note company reports 61% to 94%; neither figure was locally reproducible.
Conclusions

File-level guards that suppress webkit-prefixed findings once standard scrollbar properties exist are a deliberate anti-false-positive trade, but they mean a "0 findings" report on legacy code can hide issues the rules would otherwise catch; one modern declaration made an entire test file invisible.

Guide entries read as executable policy rather than documentation: version-pinned fallbacks, keepWhen/dropWhen verification, and explicit cross-references close the gap between what an agent can read and what it can act on without doing its own compatibility research.

Release trains lag the source repo: 252 guides and 51 rules upstream versus 35 rules in the published package means the official 203-guide count overstates what the shipped artifact actually enforces.

Default-on telemetry that collects raw search query text sits awkwardly next to a README claiming the CLI is "completely private and local"; the privacy posture hinges entirely on one environment variable.

Documenting unfinished internals, like the not-yet-wired skip statistics, reads as more credible than a cover page full of selling points.

Concepts & terms
light dismiss
Closing a modal dialog by clicking or tapping outside it instead of using an explicit close button; the subject of one of the guides the author searched first.
closedby="any"
An HTML dialog attribute that enables light dismiss on a modal; browser support is version-pinned in the guide, with Safari not listed as supporting it.
int8 quantization
Compressing embedding vectors to 8-bit integers per dimension, shrinking the offline semantic search index enough to fit inside the npm package.
structuredClone
A native JavaScript deep-clone API that replaces error-prone JSON.parse(JSON.stringify()) patterns; a rule to detect the old pattern exists in the source repo but not in the published package.
Baseline
A cross-browser feature availability tracking mechanism; the guide's fallback version numbers track this, so the knowledge layer expires as browsers catch up.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗