docs: simplify README, fix the site, and embed a working demo on the homepage - #52
Merged
Conversation
added 7 commits
August 18, 2026 14:20
The README carried 366 lines of detail that belongs on the docs site, and duplicated it badly. It is now the same shape as atterm/atstarter: what it is, where to get it, how to run it, and links. The site was actively misleading: install and mcp-bridge still told users to fill in ws://127.0.0.1:8787/worker, which the pairing flow replaced, and Plans 32-33 had no coverage at all. Adds pages for multi-session pairing and the page-event recorder, rewrites mcp-bridge around pairing and the 54-tool surface, and regenerates the tool reference (41 -> 57).
Kept as a regression test: the demo's headline claim is that it runs the real side panel, so a silent failure to mount would make the homepage lie rather than merely break.
The docs site had no way to show what this does — an extension cannot be tried online, so the homepage asked people to download a zip and configure an API key before forming any impression. The demo runs the actual side panel and the actual content tools: the scripted conversation drives callTool against a mock product page, so the highlight and the expanded comments are produced by the same code that runs on a real site. Only the LLM is faked, through the MockLlmClient that already existed for deterministic chat tests, injected via a Vite alias so the product keeps no demo-only branches. The panel sits in a nested iframe because the content tools query document with no root — sharing one would let takeSnapshot enumerate the panel's own controls. That split also mirrors production, where the panel and the page really are separate documents. The homepage says plainly that this is a canned page, not an online trial.
The send button is <button aria-label="发送">↑</button>, so matching on textContent found nothing and the demo would have sat idle on the homepage. The unit tests passed because they built their own markup with a text label — a shape the real UI does not have. Adds an integration assertion against the actually-rendered AppShell, so a markup change that hides the input or the send button fails a test instead of quietly breaking the homepage.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The README was 366 lines of detail that belongs on the docs site, and duplicated it badly. It now follows the same shape as
atterm/atstarter: what it is, where to get it, how to run it, and links out. 57 lines.The site was actively misleading, not merely stale.
guide/install.md,advanced/mcp-bridge.mdand the English install page all still told users to fill inws://127.0.0.1:8787/worker— the instruction the pairing flow replaced two releases ago. Plans 32 and 33 had no coverage at all: searching the site for 配对 / recorder / consoleMessages / 多会话 returned nothing.Adds
advanced/pairing.mdandadvanced/recorder.md, rewritesmcp-bridge.mdaround pairing and the 54-tool surface, and regenerates the tool reference (41 → 57 tools, picking up everything Plans 32-33 added).The homepage now runs a working AtWebPilot. It is the real side panel driving a real DOM through the real content tools — the scripted conversation calls
callToolagainst a mock product page, so the highlight and the expanded comments are produced by the same code that runs on a live site. Only the LLM is faked, via theMockLlmClientthat already existed for deterministic chat tests, injected through a Vite alias so the product keeps no demo-only branches.The panel sits in a nested iframe because the content tools query
documentwith no root parameter — sharing one document would lettakeSnapshotenumerate the panel's own controls. That split also mirrors production, where the panel and the page genuinely are separate documents with the service worker between them; here a harness plays that role.The homepage states plainly that this is a canned page, not an online trial. An extension cannot be tried in a browser it is not installed in, and implying otherwise would be a promise the demo cannot keep.
Two things the process caught
A probe task verified up front that the real
AppShellmounts under the demo shim. It does — so "the real side panel" is an honest claim. Had it not, the demo would have narrowed to the chat view and the spec and homepage copy with it.The send button is an icon —
<button aria-label="发送">↑</button>— so matching ontextContentfound nothing and the demo would have sat idle on the homepage. The unit tests passed because they built their own markup with a text label, a shape the real UI does not have. Fixed, with an integration assertion against the actually-rendered panel so a markup change fails a test instead of quietly breaking the page.Test plan
pnpm typecheckclean;pnpm test1171 passing (was 1128);pnpm buildcleanpnpm -F @atwebpilot/extension build:demoproducesdocs-site/public/demo/, and the built demo serves with correct asset pathsdocs-sitebuilds with the new pages and no dead linksrunChatSession, and the product's ownclicktool really expands the comment list in the mock pagerunJS, serves canned results for extension-only tools, and propagates tool errors rather than swallowing themAppShellmounts under the shim and exposes an input and a send button autoplay can find8787instructions remain anywhere in the site