Skip to content

docs: simplify README, fix the site, and embed a working demo on the homepage - #52

Merged
attson merged 7 commits into
mainfrom
feat/docs-and-embedded-demo
Aug 18, 2026
Merged

docs: simplify README, fix the site, and embed a working demo on the homepage#52
attson merged 7 commits into
mainfrom
feat/docs-and-embedded-demo

Conversation

@attson

@attson attson commented Aug 18, 2026

Copy link
Copy Markdown
Owner

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.md and the English install page all still told users to fill in ws://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.md and advanced/recorder.md, rewrites mcp-bridge.md around 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 callTool against 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 the MockLlmClient that 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 document with no root parameter — sharing one document would let takeSnapshot enumerate 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 AppShell mounts 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 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. 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 typecheck clean; pnpm test 1171 passing (was 1128); pnpm build clean
  • pnpm -F @atwebpilot/extension build:demo produces docs-site/public/demo/, and the built demo serves with correct asset paths
  • docs-site builds with the new pages and no dead links
  • Scenario executes end to end: the scripted rounds drive runChatSession, and the product's own click tool really expands the comment list in the mock page
  • Harness runs real content tools, refuses runJS, serves canned results for extension-only tools, and propagates tool errors rather than swallowing them
  • Bridge pairs concurrent requests by id and ignores stray results
  • chrome shim answers unknown requests instead of hanging (the panel retries four times on a missing receiver)
  • Real AppShell mounts under the shim and exposes an input and a send button autoplay can find
  • No 8787 instructions remain anywhere in the site
  • Manual: open the built site locally and watch the demo play through in a real browser — iframe composition, layout, and autoplay timing against the live panel are not covered by tests
  • Manual: confirm the demo degrades acceptably on a narrow viewport

attson 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.
@attson
attson merged commit 5e32615 into main Aug 18, 2026
2 checks passed
@attson
attson deleted the feat/docs-and-embedded-demo branch August 18, 2026 08:41
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.

1 participant