docs: mockup Examples tab for Stagehand cookbooks - #2789
Draft
antonvishal wants to merge 8 commits into
Draft
Conversation
|
Contributor
|
This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run. |
github-actions
Bot
added
external-contributor
…erbase#2785) ## Problem Unversioned docs paths redirect to **v3** even when a v4 page exists. ``` docs.stagehand.dev/best-practices/caching → /v3/best-practices/caching ``` The v3 caching page still documents `serverCache: false` and `env: "BROWSERBASE"` — the pre-v4 API. The v4 page at `/v4/best-practices/caching` documents the current `cache` option, but you only reach it by clicking a version-pinned link. The cause isn't the default version (that's already v4 — `docs.stagehand.dev/` lands on `/v4/first-steps/introduction`). It's the `redirects` table in `packages/docs/docs.json`, which was written when v4 had only a handful of pages. Broad catch-alls like `/best-practices/:slug*` → `/v3/best-practices/:slug*` have been shadowing v4 pages as they landed. ## Change Add explicit v4 redirects for every unversioned path that now has a v4 page. Mintlify matches redirects top-down, so the v3 catch-alls stay last and continue to serve pages that only exist in v3. | Section | Now → v4 | Still → v3 (v3-only pages) | | --- | --- | --- | | `best-practices` | caching, cost-optimization, deployments, mcp-integrations, prompting-best-practices, speed-optimization, usecase-observe, user-data, using-multiple-tabs | agent-fallbacks, computer-use, deterministic-agent, history | | `configuration` | catch-all → v4 (v4 has all four pages) | — | | `basics` | + webmcp (act/extract/observe already were) | agent, evals | | `migrations` | playwright, v3 | python, v2 | `first-steps` and `reference` already pointed at v4 and are unchanged. ## E2E Test Matrix | Command / flow | Observed output | Confidence / sufficiency | | --- | --- | --- | | `mint validate` (in `packages/docs`, catalog-pinned version) | `success build validation passed` — 24 OpenAPI definitions valid | Proves `docs.json` parses and the nav/redirect config is structurally valid. Does not prove the redirects point anywhere useful. | | `mint broken-links --check-anchors --check-redirects --check-snippets` | `success no broken links found` | This is the load-bearing row: `--check-redirects` resolves every redirect destination. Confirms all 15 new concrete destinations exist and no existing link broke. | | Script over `docs.json` + the `v3/**` / `v4/**` MDX tree | `concrete redirects checked: 15` / `BROKEN: none` / `missing explicit redirect (would fall through to v3): none` | Independently confirms the v4 best-practices set is fully covered (9/9) and enumerates the 4 v3-only pages that intentionally still fall through. Cross-checks the mint result against the actual file tree. | | `curl -sIL docs.stagehand.dev/best-practices/caching` (live, pre-merge) | `final: .../v3/best-practices/caching` | Reproduces the bug on production. Post-merge behavior is not yet observable — that needs a deploy, so it remains unproven here. | Redirect behavior on the deployed site can only be confirmed after this merges and the docs redeploy. ## Notes - Docs-only, no changeset. - Scope note: the report that kicked this off was about `/best-practices/caching` specifically. I extended it to `configuration`, `basics/webmcp`, and `migrations` because they are the same bug and the same one-line-each fix. Happy to trim to `best-practices` only if you'd rather keep the diff minimal. <!-- This is an auto-generated description by cubic. --> --- ## Summary by cubic Unversioned docs paths that have a v4 page now redirect to v4 instead of v3, so users land on current content. v3-only pages still redirect to v3. Addresses Linear AP-2887. - Added explicit v4 redirects in `packages/docs/docs.json` for `best-practices` (caching, cost-optimization, deployments, mcp-integrations, prompting-best-practices, speed-optimization, usecase-observe, user-data, using-multiple-tabs), `configuration` (catch-all), `basics/webmcp`, and `migrations` (playwright, v3). - Kept v3 catch-alls last; these still resolve to v3: `best-practices` (agent-fallbacks, computer-use, deterministic-agent, history), `basics` (agent, evals), `migrations` (python, v2). - Validated with `mint validate` and `mint broken-links --check-redirects`; production behavior updates after the docs deploy. <sup>Written for commit e27ff99. Summary will update on new commits.</sup> <a href="https://cubic.dev/pr/browserbase/stagehand/pull/2785?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
…rowserbase#2786) ## Why On `v3`, every push published a snapshot of `@browserbasehq/stagehand` as `<next>-alpha-<sha>` under the `alpha` dist-tag (`release-canary` script + `snapshot` changesets config + a "Publish Canary" step in `release.yml`). The v4 release rewrite (browserbase#2671) dropped all three, so nothing newer than `4.0.0-alpha-49bc5b6…` has shipped to npm since. ## What Port the v3 behavior onto the v4 release tooling: - `.changeset/config.json` — restore `snapshot: { useCalculatedVersion, prereleaseTemplate: "alpha-{commit}" }` (the v3 `snapshot.tag` key was never part of the schema; the dist-tag comes from `--tag alpha` on publish). - `justfile` — new `_publish-typescript-alpha` recipe: `changeset version --snapshot` → build `sdk-ts` → `changeset publish --tag alpha --no-git-tag`. - `.github/workflows/release.yml` — new `publish-typescript-alpha` job after `release-typescript`. It's a separate job (rather than a trailing step as on v3) so an alpha failure can't block the Python/Go release jobs, and it only needs the node toolchain (`turbo run build --filter=@browserbasehq/stagehand` covers protocol → extension → sdk-ts). Behavior matches v3: only packages with pending changesets are versioned, so the push that cuts a stable release is a no-op for the alpha job. Verified locally that `changeset version --snapshot` yields `4.0.3-alpha-8b75044ee9163dc3c0d18fb11eed4a12246b4a03`. No changeset — CI/release infra only. ## Follow-up Python alphas (`<next>a0.dev<N>` on PyPI — PEP 440 can't carry the sha) are coming in a separate PR. Go needs nothing: `go get …/sdk-go/v4@<sha>` already works via pseudo-versions. <!-- This is an auto-generated description by cubic. --> --- ## Summary by cubic Restores commit-addressed alpha releases for the TypeScript SDK. v3 published `<next>-alpha-<sha>` to the `alpha` dist-tag on pushes; v4 dropped it. This brings back automated alphas without affecting stable releases. - Restores Changesets snapshot config: `useCalculatedVersion` with `prereleaseTemplate: "alpha-{commit}"`. - Adds `just _publish-typescript-alpha`: `changeset version --snapshot` → build `sdk-ts` → `changeset publish --tag alpha --no-git-tag`. - Adds a separate `publish-typescript-alpha` job in `release.yml` after `release-typescript`; builds `@browserbasehq/stagehand` via `turbo` and does not block Python/Go if it fails. - Behavior matches v3: publishes `<next>-alpha-<sha>` only when there are pending changesets; no-op on the stable-release commit; no git tags; CI-only. Aligns with Linear AP-2885. <sup>Written for commit d98d0e4. Summary will update on new commits.</sup> <a href="https://cubic.dev/pr/browserbase/stagehand/pull/2786?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. -->
![https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source](https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source){kind=link}
![https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img](https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img){kind=link}
![https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a](https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a){kind=link}
Adds a "Migrate Browser Use to v4" guide under `packages/docs/v4/migrations/`, modeled on the existing v3 and Playwright migration guides in that directory. The guide frames the core migration story: Browser Use is an autonomous-agent framework (`Agent(task=..., llm=...).run()`), and Stagehand v4 has no agent object — so, like the v3 guide's "why agent() is gone" narrative, it steers users to **code mode** (an assistant writes a script once) and **tool calling** (a model drives the full Stagehand API as tools). It leads with Python (Browser Use is Python-first) and includes TypeScript tabs. Covered: - Side-by-side hello world, code mode, and tool calling - Breaking-change diffs: initialization/teardown, the task string, models (`ChatOpenAI`/`ChatBrowserUse` → `model`), structured output (`output_model_schema` → `extract()`), sensitive data (`sensitive_data` → `variables`), custom tools (`@tools.action`), and `Browser(...)` / `@sandbox` config - A quick-reference mapping table and troubleshooting section - Registered the page in `docs.json` under the v4 Migration guide group Browser Use API details were grounded against the browser-use/browser-use repo's own reference docs; Stagehand v4 API against the existing v4 reference pages. All cross-links and deep anchors were verified to resolve, and `docs.json` validates as JSON. - `jq` confirms `docs.json` is valid JSON - Verified all 13 cross-linked v4 pages exist and the `models#model-gateway` / `act#secure-your-automations` anchors resolve - Confirmed all Python/TypeScript API idioms used (`browserbase.launch`, `local_browser.launch`, `new_page`, `wait_for_load_state`, `ModelConfig`, `data.extraction`, etc.) match usage elsewhere in the v4 docs - Recommend running `just check` (Mint config + link validation) in CI Requested by: sophie@browserbase.com Linear: https://linear.app/browserbase/issue/STG-2850/add-browser-use-to-v4-migration-guide Slack thread: https://browserbase.slack.com/archives/D0AH75TNSF9/p1786985811934049 --------- Co-authored-by: shriyatheunicorn <shriavj@gmail.com> Co-authored-by: Alyssa Keimach <7604716+akeimach@users.noreply.github.com>
…README (browserbase#2777) ## Summary - mark `BROWSERBASE_PROJECT_ID` optional in every example README (env tables + setup exports) — only the API key is required now - rewrite `packages/integrations/README.md` with a structure overview and a one-liner per subdirectory (it previously described only the code-mode scaffold and deepagents) ## Why The SDK patch made the project ID optional; the READMEs implied it was required in three examples and the package README predated the facade work entirely. ## Testing - `pnpm run fmt:check` clean; docs-only change <!-- This is an auto-generated description by cubic. --> --- ## Summary by cubic Removes `BROWSERBASE_PROJECT_ID` from all integration READMEs and expands the integrations package overview so docs match the SDK: only `BROWSERBASE_API_KEY` is required. Runtime behavior is unchanged. - Docs: delete project ID rows/exports in `claude-code`, `codex` (simplify table), `crewai`, `eve`, `mastra`, `pi`, and `vercel-ai`; show only the API key. - Docs: rewrite `packages/integrations/README.md` with a structure overview of the facade tools (`run`, `snapshot`, `screenshot`), the single contract in `core/` published as `@browserbasehq/stagehand-integrations`, a per-directory table (adds `fx/`, fixes Pi casing), and TS vs Python consumption notes. - Migration: remove `BROWSERBASE_PROJECT_ID` from local envs if present. <sup>Written for commit 3e7c0c5. Summary will update on new commits.</sup> <a href="https://cubic.dev/pr/browserbase/stagehand/pull/2777?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. -->
…rbase#2791) The fx harness added in browserbase#2776 can miss all three Stagehand tools during dynamic search and then invent legacy navigate tool names. Inline full-page PNG responses can also exceed the fx raw MCP frame cap before tool-result truncation runs, which closes the RPC connection. - add deterministic fx project guidance with the exact three tool names and explicit page.goto navigation - make the facade run and screenshot descriptions easier to discover and harder to misinterpret - add an fx-specific 60 KB screenshot payload budget that defaults to viewport JPEG, retries progressively smaller JPEGs, and returns a small tool error if no image fits - document the distinction between the raw response-frame cap and max_tool_result_bytes - add focused contract, transport-budget, and fx configuration tests - pnpm --filter @browserbasehq/stagehand-extension build - pnpm --filter @browserbasehq/stagehand build - pnpm --filter @browserbasehq/stagehand-integrations typecheck - pnpm --filter @browserbasehq/stagehand-integrations test - pnpm exec oxlint on all changed TypeScript files - pnpm exec oxfmt --check on all changed files - git diff --check <!-- This is an auto-generated description by cubic. --> --- Hardens fx Stagehand facade tool discovery and screenshot transport to prevent stalled runs and dropped MCP connections, and publishes a complete fx integration guide. Previously fx could return no tools and models invented legacy navigate names; full‑page PNG screenshots could exceed fx’s raw frame cap and close the connection. Now discovery is deterministic and screenshots respect a configurable base64 budget with safe, clamped JPEG retries. - Deterministic discovery and navigation: pins exactly three tools (“run”, “snapshot”, “screenshot”) with updated descriptions; there is no separate navigate/start tool. `packages/integrations/fx/AGENTS.md`, the `skills/stagehand-facade` skill, and new docs (`/v4/integrations/fx`) instruct agents to call `mcp_stagehand_run`, `mcp_stagehand_snapshot`, and `mcp_stagehand_screenshot` directly and navigate with `await page.goto(...)`. - Transport-safe screenshots: the facade enforces a base64 budget (`--max-screenshot-base64-bytes=...`). The fx template sets `--max-screenshot-base64-bytes=60000`, defaults unspecified screenshots to a viewport JPEG (quality 40), retries with smaller JPEG qualities (40 → 25 → 10) without ever increasing a requested JPEG quality, and returns a small tool error if none fit. Docs clarify the raw response-frame cap vs `max_tool_result_bytes`. - Tests: add contract, transport-budget, and fx configuration tests, including quality clamping during screenshot retries. - Required for custom fx setups: add `--max-screenshot-base64-bytes=60000` (or a suitable value) to the Stagehand MCP command; run fx from `packages/integrations/fx` so it loads the project guidance; prefer `{"type":"jpeg","quality":40,"fullPage":false}` for screenshots. <sup>Written for commit 9c5d64a. Summary will update on new commits.</sup> <a href="https://cubic.dev/pr/browserbase/stagehand/pull/2791?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. -->
Unlists the Browser Use → v4 migration guide (follow-up to browserbase#2756): - Removes `v4/migrations/browser-use` from the Migration guide nav group in `packages/docs/docs.json` - Adds `noindex: true` to the page frontmatter so search engines skip it The page remains reachable at https://docs.stagehand.dev/v4/migrations/browser-use by direct link — it's just no longer in the sidebar or indexed. - `jq empty packages/docs/docs.json` passes (valid JSON) Requested by: shriya@browserbase.com Linear: https://linear.app/browserbase/issue/AP-2892/unlist-browser-use-v4-migration-guide-from-docs-nav
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
4 participants
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
This PR is a mockup for a dedicated Examples section in the Stagehand docs.
The goal is to make Stagehand-specific examples more discoverable and easier for both developers and coding agents to understand and reference. Rather than relying primarily on the broader Browserbase Templates page, this would give Stagehand its own structured surface for showcasing different combinations, patterns, and use cases.
The examples could eventually cover things like:
This is intentionally just a docs/navigation mockup for now. The content is placeholder and the next step would be to flesh out the actual example categories and content if the direction gets a green light.
Mockup
Notes
Would love feedback on: