Modern Web Guidance: A Searchable Browser API Spec for Coding Agents
Daily Open Source Project #157 Modern Web Guidance: Let Agents Look Up Browser Capabilities On Demand
Date: 2026-11-12 GitHub Trending Daily Rank #3; snapshot taken at 16:00:35 Beijing time.
Ask a coding agent to write a delete confirmation dialog, and it will likely hand back a custom overlay: listening for Esc, looping through Tab, toggling inert on the background, and adding ARIA attributes to the popup. The code runs, but the browser's native <dialog> already handles a good portion of that work. Worse, switching directly to the native component can still miss cancel actions, scroll chaining, and older browser fallbacks.
Modern Web Guidance addresses exactly this gap. It organizes web development recommendations into searchable, topic-retrievable guides so an agent can look up a small piece of relevant knowledge before writing the implementation. The part worth unpacking is how local retrieval, compatibility strategy, and accompanying evaluation fit together, not just another prompt that says "write modern code."
📋 Project Overview
| Project | Details |
|---|---|
| Main repo | GoogleChrome/modern-web-guidance-src |
| Project name | Modern Web Guidance |
| Positioning | Web platform guides for coding agents, a search CLI, and tooling for authoring and evaluating guides |
| Distribution repo | GoogleChrome/modern-web-guidance |
| Snapshot Stars / Forks | 2,037 / 151 |
| Primary language | TypeScript |
| License | Apache-2.0; guides under guides/ additionally licensed CC BY 4.0 |
| Runtime requirement | Published CLI requires Node.js 22+; source dev checklist requires Node.js 22.18.0+ |
| Main entry points | search, retrieve, legacy-scan, plus build and evaluation tools for contributors |
The source repo and distribution repo are distinct: the former contains original guides, macro expansion, vector processing, scorers, and dashboards; the latter is the artifact installed on the agent side. An ordinary user doesn't need to set up the whole evaluation environment just to look up a CSS pattern. The README explains the responsibilities of both repos and the different licenses for software and guide content.
🔥 Why It's Worth Attention
Changes to the browser platform don't automatically sync with model knowledge. Legacy code makes up a large share of training corpora; even if an agent knows the name of a new API, it may not know the details of how it interacts with existing pages.
The dialog is a good example: showModal() gives native modal behavior, but show() and directly setting open are not the same thing; closedby can express a close policy, but it can't protect unsaved form data by itself in browsers that lack support for the attribute. Simply prompting "use HTML5" does almost nothing for these issues.
This project chooses to put knowledge retrieval inside tool calls. The agent first converts a business requirement into a short English query; search results return only guide IDs and descriptions. After judging relevance, it fetches the full text. This avoids keeping all documentation in context and leaves a visible trace of which recommendation the implementation actually referenced.
It also has an easily overlooked value: compatibility advice doesn't have to be hardcoded into prompts. The guide build process incorporates browser support data, and at runtime the target strategy is added based on the project's .mwgrc. However, at runtime it reads the generated guides from the package, not querying a browser database on every request. To get updated compatibility content, you still need to update the distribution artifact.
🏗️ Core Features
Find guides by task without stuffing the entire knowledge base into context
The skill entry point recommends 2–5 word, action-oriented English queries, e.g., confirmation modal dialog. It explicitly asks to split multi-topic tasks rather than mixing framework names, business page names, and several UI needs into one search term.
This relates to the underlying implementation. The query side uses an English vocabulary and lexical tokenization; it is not a conversational model that understands arbitrary long Chinese requests. For Chinese users, a reasonable division of labor is for the agent to translate and distill the query, rather than handing a full Chinese requirement directly to the retriever.
On a hit, retrieve returns concrete implementation advice, caveats, and fallback options. The skill's "review code against the guide" step is still performed by the agent; installing the tool doesn't automatically turn it into a compile check for every project.
Experimental capabilities are discoverable but not retrievable by default
Guides can be associated with Origin Trials or unstable single-engine features. The project writes this metadata into the guide index. The search phase preserves discoverability; the retrieve phase checks whether the project explicitly allows the capability.
This avoids a common misuse: a high search ranking is treated as a production-ready recommendation. Here, ranking indicates relevance, not a compatibility promise. The actual retrieval path also goes through policy checks.
Legacy scan only covers patterns with defined rules
legacy-scan is another entry point. It scans existing patterns in code, groups findings by guide, and outputs file, line, and rationale. The structured results can carry keepWhen and dropWhen to help the agent filter out false positives.
For example, a piece of JavaScript kept for older browser support does not necessarily need to be deleted. A hit on a legacy pattern only says "worth a look here," not that replacement is always correct. The skill also limits scanning to open-ended modernization scenarios; it does not require a full-repo scan before every new component.
Guides carry behavioral expectations; evaluation checks more than wording
The guide directory typically contains not just guide.md but also demos, behavioral expectations, and evaluation materials. Maintainers can have agents modify a base app with and without the guide, then use Playwright assertions to evaluate the generated results.
This chain is useful for guide authors: no matter how well-written the advice is, if the agent can't retrieve it, misunderstands it, or still fails to produce working code, the fix should go back into the content and task design. It tests a specific task and its assertions, not a one-time proof of overall frontend engineering quality.
🔬 Deep Dive into Technical Architecture
The project has two distinct work chains: maintainers produce guides, and users search and retrieve them. Drawing them together as a single "user request goes through an LLM and generates code" picture misses its most interesting implementation.
Guide author
guide.md / behavioral expectations / demos
│
├── Build: expand macros, parse Web Features, split retrieval chunks
│ │
│ ├── Full guide Markdown + guides.json
│ └── Chunk text + document vectors / quantization scales
│
└── Evaluation: base app → agent with/without guide → Playwright assertions
│
└── results and dashboard
Coding agent
short English query
│
▼
static vocabulary query vector ──→ per-chunk cosine match ──→ per-guide max
literal words in query ───→ BM25 chunk scoring ───→ per-guide max
│
▼
RRF merge → default top 10
│
Agent selects relevant guide ID
│
▼
retrieve → .mwgrc feature gating
│
project Baseline prompt
│
full guide enters context
1. Query vectors and document vectors don't use the same encoding path
StaticEmbedder runs in a restrained way: loads a vocabulary, Int8 word-vector table, and per-row scales; tokenizes the query; sums vectors of known words with weights; then L2-normalizes. The vector dimension is set to 256 by STATIC_DIMS.
Hyphenated words get special treatment. If the full word exists, it is used directly; only if not does it try splitting on hyphens and distributing weight across the matched parts. Unknown words do not trigger a remote model call.
The document side is different. The build tool reads pre-generated chunk-vector caches; the repo's retrieval notes describe it as generating document vectors with a teacher embedding model, then sharing a space with the distilled query vocabulary. Runtime therefore doesn't need to load a full Transformer to process a few query words.
The tradeoff is clear: queries are cheap and the distribution package is self-contained, but expressive power is limited by the vocabulary, tokenization, and pretrained space. It suits finding topics within a bounded set of Web guides; it should not be promoted as a general semantic search engine.
If cached vectors are missing at build time, the whole guide doesn't have to be thrown away. The default build keeps chunk text and uses empty vectors so it can still be found via BM25; a strict path with failOnMissingVectors rejects missing vectors. This is a degradation of retrieval quality, not automatic runtime online vector completion.
2. Two retrieval result sets are merged by rank, not by directly adding scores
search.ts iterates chunk vectors and computes dot products of normalized vectors. The same guide may have multiple chunks; it takes the best-matching chunk as that guide's dense similarity. It does not connect to a remote vector database at runtime, nor does it use an approximate nearest-neighbor index to skip most chunks.
The lexical side builds a BM25 index over descriptions and chunk content. Again, the highest chunk score per guide is taken, so a long guide doesn't get an advantage just because it has more chunks. Literal information like API names and abbreviations can be recovered by this path.
Then Reciprocal Rank Fusion is used with default k=60. Intuitively, the higher an item ranks on either list, the larger its contribution; a guide ranking well on both lists becomes more competitive. It merges ranks, so it doesn't need to assume BM25 scores and cosine similarity share the same scale.
Another important detail: the default 0.3 is a query-level threshold. Only when the highest dense similarity falls below the threshold AND BM25 has no hits does search return an empty array. If the dense maximum is insufficient but lexical hits exist, the dense list is dropped and lexical results are kept. It is not a per-guide filter enforcing similarity >= 0.3.
Internal functions return similarity and other info, but the CLI compresses output to {id, description}, up to ten items by default. This difference is practical for callers: you can't expect the command output to always include full scoring explanations.
3. Quantization saves distribution size, but runtime memory is a different number
Both query tables and chunk vectors use Int8 storage with floating-point scales. The quantization tool computes per-row scales and re-normalizes after decoding; zero-scale document rows return empty vectors, and search skips their dense matches.
For document chunks, loadVectors() reconstructs quantized data into Float32 vectors and caches the corpus and BM25 index. So "one-byte integers on disk" doesn't directly imply "each dimension occupies one byte in memory at search time." Cold start also pays for reading, decompressing, parsing, and index construction.
If the number of chunks is C and the vector dimension is D, each dense query still performs roughly C×D multiply-accumulates; the lexical path also walks its document representations. This is a cost judgment about the loop implementation, not a latency test on a particular machine. For a bounded, topic-specific document collection like this, a simple scan buys fewer deployment components; if expanded to a large enterprise knowledge base, you can't carry over its performance expectations.
4. .mwgrc hard gating and soft prompts need to be separated
retrieve.ts first finds IDs from the index, then reads project configuration. As long as a guide carries a gated feature class and the corresponding field is not strictly equal to boolean true, it throws a feature-gating error. The CLI writes errors to stderr; multi-ID retrieval allows successful guides to output, but if any error occurs, the final exit code is still 1.
This means automated callers can't assume "Markdown output exists" means the whole request succeeded. Read the exit code and identify which ID was blocked.
Configuration discovery is also more specific than "project file overrides user file." mwgrc.ts walks up from the current directory and stops at .mwgrc or .git; it does not merge ancestor configs. Only when no project boundary is encountered does it consider the user directory's .mwgrc. If you're already inside a Git project, you can't expect a user-level allow switch to inherit automatically. Corrupted JSON throws an error rather than silently becoming a default config.
Gating guards the normal retrieval interface, not a security sandbox. Files remain local, and an agent can still write code from its own knowledge; textual instructions to not bypass are still dependent on the caller following them.
The Baseline target mainly changes the prompt at the top of returned documents. The default strategy uses Widely available as the baseline; newly, limited, or year targets append corresponding notes. It does not read your output, block non-conforming CSS at compile time, or directly test your company's WebView.
5. Evaluation breaks "guide is useful" into checkable questions
The source repo includes guide-authoring, scorer generation, calibration, and agent evaluation tools. Per the Harness README, calibration aims to pass expected correct changes, fail a zero-pass-rate baseline, and then compare actual guided vs. unguided generation results.
But "calibration target" doesn't mean every generated scorer is inherently reliable. Scorers are also code that needs review, with coverage determined by the task and behavioral expectations.
The dialog behavioral expectations are very specific: does the native element have an accessible name; is it :modal when open; does focus return to the caller after closing; are unsaved contents protected; is there accidental dismissal when pressing inside the dialog and dragging to the backdrop to release; can the background still be focused or scrolled. These assertions are closer to actual user problems than merely checking that <dialog> appears in the source.
Evaluation configuration should also be read together with the actual adoption strategy. The source-defined guided default config allows Origin Trial and volatile features, which differs from the default retrieval policy for ordinary projects that disallow them. So maintainer-measured improvements cannot be unconditionally treated as expected gains for every conservative project. Model, task, assertion set, and allowed capabilities must all align before comparisons are meaningful.
📖 README Core Summary
The README offers several usage modes: install via npm CLI, or use plugin and skill entry points for different agents. For team integration, pay attention to these points first.
First, skills and tools have different roles. Skills tell the agent when to look up, how to organize queries, when to retrieve, and how to review; the CLI implements retrieval, reads configuration, and outputs. Installing a skill does not mean those recommendations have become mandatory rules in your repository's CI.
Second, compatibility data has a build-time and runtime boundary. The source depends on web-features and MDN browser compatibility data to generate specific guides. At runtime, retrieval reads local Markdown; bringing new browser changes into an agent requires updating the guide package, not just swapping in a new chat model.
Third, "local retrieval" and "the entire command never touches the network" are not the same thing. The core search and retrieve algorithms run locally; the first npx download, install subcommands, and default-enabled telemetry have their own network boundaries.
The telemetry implementation records search queries, hit guides, call success/failure, latency buckets, versions, and agent info. The README states raw user prompts are not collected, but agent-generated search queries may still contain business terms. Enterprise integration cannot automatically equate "offline search" with "no data leaves the network"; set DISABLE_TELEMETRY=1 in the invocation environment as needed, without needing to modify a global shell config just for a trial.
Finally, licenses must be viewed by content type. Software code is Apache-2.0; guide content is CC BY 4.0. When copying guides into company docs, derivative materials, or other distributions, you should preserve the relevant attribution and license information. Don't look only at the software license in the root directory and ignore the documentation licensing.
🚀 Quick Start
First, prepare Node.js 22 or higher. The following pins the published 1.0.0 version, and only searches and retrieves; it doesn't install an agent plugin or modify project policies.
node --version
DISABLE_TELEMETRY=1 npx --yes [email protected] --help
DISABLE_TELEMETRY=1 npx --yes [email protected] search "confirmation modal dialog"
DISABLE_TELEMETRY=1 npx --yes [email protected] retrieve dialog
The results in this set return guides such as dialog and declarative-dialog-popover-control. Callers should choose relevant items based on descriptions, not fetch all top ten. If the query topic changes to tables, animations, or forms, re-search rather than guessing an ID from memory.
If retrieve output exceeds 9,500 bytes and stdout is not a plain file, the CLI attempts to save the full content to a temporary Markdown file and prints the path. To continue reading that file, don't mistake a short path hint in the terminal for the full guide. To control output yourself, redirect to a file:
DISABLE_TELEMETRY=1 npx --yes [email protected] retrieve dialog > dialog-guide.md
A minimal implementation of a delete confirmation dialog
Below is a standalone example built around native modal semantics. Save it as an HTML page and check the interaction in a browser supported by the project. It uses showModal(), pulls in no dialog library, and relies on nothing newer like declarative Invoker Commands.
<button id="remove" type="button">Delete draft</button>
<p id="result" role="status"></p>
<dialog id="confirm" aria-labelledby="confirm-title">
<h2 id="confirm-title">Delete this draft?</h2>
<p>This example only shows the result, it does not perform a real deletion.</p>
<form method="dialog">
<button value="cancel" autofocus>Keep</button>
<button value="delete">Delete</button>
</form>
</dialog>
<style>
dialog:modal {
overscroll-behavior: contain;
}
dialog::backdrop {
background: rgb(0 0 0 / 40%);
overflow: hidden;
overscroll-behavior: contain;
}
</style>
<script type="module">
const trigger = document.querySelector('#remove');
const dialog = document.querySelector('#confirm');
const result = document.querySelector('#result');
trigger.addEventListener('click', () => dialog.showModal());
dialog.addEventListener('close', () => {
const choice = dialog.returnValue;
dialog.returnValue = '';
result.textContent = choice === 'delete'
? 'Deletion chosen; the business request should be handled separately here.'
: 'Draft kept.';
});
</script>
Here the initial focus is on the safe "Keep" button; form method="dialog" is responsible for ending the dialog; the close callback reads the result and clears returnValue to avoid accidentally reusing the previous choice on the next Esc close. The example does not manually redo focus trapping, nor does it redundantly add role="dialog" and aria-modal to the native modal.
The CSS handles scroll chaining per the guide. It's behavior that needs to be checked against target browsers: some browsers differ in scroll constraints for non-scrolling containers, so you can't just see that @supports accepts a property and assert the background won't scroll.
If you connect the example to a real delete endpoint, network failures, repeated clicks, server-side authorization, and page state after successful deletion all need separate design. A dialog closing correctly does not mean the business operation succeeded.
Use the other entry point when scanning legacy projects
Inside an opened target project directory, you can run:
DISABLE_TELEMETRY=1 npx --yes [email protected] legacy-scan . --json
It only returns modernization opportunities covered by rules; it does not automatically rewrite code. Check the keep and drop conditions for each finding before deciding whether to retrieve the corresponding guide. Existing compatibility fallbacks may also get hit; don't delete them just to make the scan result zero.
📊 Growth and Community Heat
In the 2026-11-12 snapshot, the source repo ranks #3 on the daily list, with 2,037 Stars and 151 Forks. This magnitude indicates it has attracted a following, but you cannot derive a daily growth rate from cumulative Stars, nor treat the ranking as a measure of adoption effectiveness.
When assessing the maintenance quality of such projects, more useful than a single total are: do guide changes have behavioral expectations, can browser support data updates flow into distribution artifacts, and are scorers recalibrated as requirements change. The source repo puts these pieces together; contributors can fix a specific error in a guide or add an assertion, rather than only submitting a stronger prompt.
Below is the full list recorded in that day's snapshot:
🎯 Applicable Scenarios
Agent integrations that work on Web UI are a good place to start. Teams can require agents to first search relevant guides when handling forms, dialogs, layouts, and performance tasks, and then reflect the actually adopted rules in the implementation. Reviews should look at the generated code and tests, not just whether the agent claims to have "referenced" the guide.
Maintaining an internal frontend knowledge base is also worth studying this build approach: separate raw content, compatibility metadata, retrieval chunks, and full documents; let a small entry point handle navigation, and on-demand retrieval provide detail. If you copy the retrieval algorithm, you need to re-validate your own vocabulary, corpus scale, and query language; do not carry over effect expectations from the Web guide domain.
Products with strict browser-version requirements should first define a support matrix, then decide how to use Baseline prompts. This is especially true for embedded Android WebViews, old devices, or specialized runtimes; the general support status of public browsers may not cover real users. Guides help write fallbacks, but do not replace validation on target devices.
If the team needs "block commits of incompatible code," this skill is not enough. You also need project-specific static rules, browser tests, or build constraints. It can improve the material agents get and the order of their work, but it does not take on the mandatory acceptance of final delivery.
💡 Summary
Modern Web Guidance breaks browser knowledge into a task-queryable tool: lightweight query vectors find relevant content, BM25 fills in literal matching, the retrieve interface enforces feature toggles, and specific guides explain implementation and fallback.
I value more that the source repo places guides and behavioral expectations on the same maintenance chain. It turns "the advice might be useful" into a continuously checkable engineering problem. When integrating, also preserve this boundary: finding a guide is only the starting point; ultimately real pages, target browsers, and business failure paths must be tested.