These were removed when browser start was introduced. Now that
browser start is deprecated, restore the original manual Chrome
launch commands and tab-capture flags documentation.
- Add 'browser' to VM sandbox context so user code can call
browser.contexts() to access pages from different Chrome profiles
- Update resetPlaywright to also refresh browser reference
- Document in skill.md: --direct gives access to all profiles via
browser.contexts(), add browser to context variables list
- skill.md: remove 'playwriter --direct' from MCP examples, use env var only
- MCP.md: add Direct CDP section with PLAYWRITER_DIRECT config example
- CHANGELOG.md: add 0.0.101 entry, fix stale 'playwriter --direct' in 0.0.98
- Bump version to 0.0.101
Chrome 136+ with chrome://inspect debugging returns 404 on all HTTP
endpoints (/json/version, /json, /json/list) but still accepts WebSocket
connections on /devtools/browser/*. The first WS connection triggers a
user-approval dialog in Chrome.
Previously, discoverChromeInstances() and resolveDirectInput() treated
HTTP 404 as 'blocked' and either returned nothing or threw an error,
making --direct unusable without manually constructing a ws:// URL.
Changes:
- discoverChromeInstances() now returns a synthetic instance for 'blocked'
probes with a base ws:// URL, so browser list shows detected Chrome
- resolveDirectInput() returns a ws URL instead of throwing on 'blocked'
- appendSessionToWsUrl() appends session ID to bare /devtools/browser/
paths for unique WS connections; leaves full GUID paths (from live
probes) untouched
- Relay appends CLI session ID, MCP appends crypto.randomUUID()
- Removed --direct from root CLI command (only on session new now);
MCP users configure via PLAYWRITER_DIRECT env var
- browser list shows connect hint when direct instances are detected
Discovery never triggers a WebSocket connection, so Chrome's approval
dialog only appears when the user explicitly runs a command.
resizeImageForAgent() defaulted to JPEG when no format was specified,
causing image/png vs image/jpeg mismatch errors when MCP clients
(like Anthropic API) validated the media type against the actual image data.
All playwriter images are now consistently PNG unless explicitly
overridden with format: 'jpeg'.
Non-root tree items (visualLevel > 0) now use 4px vertical padding
instead of 2px, giving nested headings more breathing room while
keeping root-level items compact.
- Add FullWidth marker component that spans both content and aside grid
columns (lg:col-[2/-1]). Extracted at parse time like Aside/Hero.
FullWidth sections get my-5 vertical margin to match content rhythm.
- Fix auto-expand: clicking an expandable TOC item now expands it.
Previously only ancestors were expanded, not the item itself.
- TOC tree prefix characters use 1.2em font size with negative margin
so they don't inflate line height. Prefix indentation reduced to 1
char per level.
- Use FullWidth for the hero screenshot in index.mdx as demo.
- Add SVG ChevronIcon component for expandable items, shown on the right
- Toggle expand only on chevron click, not the whole row
- Remove width: fit-content from aside so it fills its column
- Add 6px margin between root-level TOC groups
- Use regular font weight (400) for all tree items
- Remove lowercase text-transform from tree items
- Remove line-height override from TocLink (inherits from parent)
Removed fontSize from the shared proseStyle object and added it to all
slot-main containers instead. Prose elements (P, OL, List) now inherit
font-size from their parent container rather than setting it explicitly,
so inside the aside they respect --type-toc-size (13px) instead of
overriding it with --type-body-size (14px).
- SectionRow aside and SidebarBanner now use a border instead of bg fill
- font size changed from --type-toc-size (13px) to --type-body-size (14px)
- line height aligned with prose style (1.6)
When AGENT_GRAPHICS=kitty is set, the CLI now emits screenshots and resized
images as Kitty Graphics Protocol APC escape sequences to stdout. Agents with
kitty-graphics-agent (or compatible parsers) automatically extract PNG images
and pass them to the LLM as media parts — no extra tool call needed.
Key changes:
- **Screenshots → PNG**: screenshotWithAccessibilityLabels() now captures PNG
instead of JPEG. PNG is lossless and the only format extracted by the Kitty
Graphics Protocol (f=100). resizeImage() gains a format option ('jpeg'|'png').
- **kitty-graphics.ts**: New utility with canEmitKittyGraphics() (checks
AGENT_GRAPHICS env var) and emitKittyImage() (writes chunked APC escape
sequences to stdout at 4096 bytes per chunk per the Kitty spec).
- **resizeImage → resizeImageForAgent**: Renamed to clarify intent. The wrapper
in executor.ts now collects resized images into result.images so they are
emitted via Kitty Graphics in the CLI and included as image parts in MCP.
Old resizeImage name kept as backward-compatible alias in the sandbox.
- **CLI deduplication**: Uses a Set<base64> to avoid emitting the same image
twice (screenshots appear in both result.screenshots and result.images).
- **10 new tests** including round-trip validation with kitty-graphics-agent
parser to verify emitted sequences can be parsed back correctly.
Version 0.0.98 → 0.0.99
The 80ms setTimeout debounce blocked the input from reflecting keystrokes
while the TOC re-render was in progress. useTransition splits the work:
setQuery is urgent (input stays responsive), while setSearchState is
deferred and interruptible — new keystrokes cancel in-progress renders.
Input opacity drops to 0.5 during isPending as a subtle loading signal.
Replace flat TocItem/PreparedTocItem/TocGroup types with a recursive
TocTreeNode -> FlatTocItem pipeline that supports arbitrary page nesting.
**Types:**
- TocNodeType = 'page' | 'h1'-'h6' — heading level encoded in type field,
no separate headingDepth. Smaller objects, self-descriptive.
- TocTreeNode = { label, href, type, children } — recursive tree, the wire format.
- FlatTocItem = { label, href, type, visualLevel, prefix, parentHref, pageHref }
— flat rendering item with depth clamped to 0-3.
**Depth clamping:**
flattenTocTree() walks the recursive tree and clamps visual depth to max 4
levels (0-3). When pages nest deeply, headings flatten to siblings at level 3.
Formula: visualLevel = min(pageDepth + headingDepth, 3). Preserves correct
visual gap for skipped markdown levels (## -> ####) via the h-type encoding.
**Component changes:**
- TableOfContents accepts FlatTocItem[], renders with visibility filtering
instead of two-tier TocGroup. Expand/collapse works at any depth by
tracking expanded hrefs and computing visibility from parentHref chain.
- Search expand override merged into visibility computation so matched items
inside collapsed branches become visible during search.
- search.ts operates directly on FlatTocItem[] — removed SearchEntry and
buildSearchEntries(). Walks parentHref chain for ancestor expansion.
**Extraction:**
slugify, extractText, generateTocTree moved to toc-tree.ts (side-effect-free)
so they can be tested without importing the page module.
**Tests:**
21 vitest tests covering slugify, extractText, tree building (nested, skipped
levels, pop-back), flattening (prefixes, depth clamping, page wrapping,
parentHref/pageHref tracking), and full mdast -> tree -> flat pipeline.
**Remaining for multi-page:**
- Multi-page data source (multiple MDX files / manifest)
- Route-aware active tracking (pathname for page, IntersectionObserver for
headings on current page only)
- Cross-page navigation (SPA or full page load)
Add <Hero> component that gets auto-extracted from MDX at parse time
(same pattern as <Aside>) and rendered above the 3-column grid, aligned
with the center content column.
Layout changes:
- slot-page uses flex column with gap-[--layout-gap] for uniform spacing
between navbar, hero, and content grid
- --layout-gap (21px) is the single source of truth for both the flex gap
(flow spacing) and --sticky-top offset (viewport-relative sticky offset)
- Remove --content-top-gap variable and all its usage (spacer divs,
sidebar padding-top) — the flex gap handles all vertical spacing now
- Hero accepts arbitrary div props for extensibility
Hero extraction pipeline:
- isHeroNode() detects <Hero> mdxJsxFlowElement nodes in the mdast
- Hero nodes are filtered out before TOC generation and section grouping
- Rendered via RenderNodes through SafeMdxRenderer with full component map
- EditorialPage receives hero as a prop, renders it in a matching grid
(same column widths) so content aligns with the center column
- Sticky sidebar container gets maxHeight + flex column so TOC scrolls
when it exceeds viewport height
- Search input stays pinned at top (flexShrink: 0), nav scrolls below
- Nav gets paddingRight 4px for scrollbar gap
- Search input padding-y reduced from 4px to 2px
- Search-to-tree gap set to 12px
Adds a search input above the left sidebar table of contents powered by
Orama (in-memory, typo-tolerant, ~20μs per query).
**search.ts** — flat SearchEntry[] data model with parent/group references,
Orama DB creation, searchToc() that returns matched/dimmed/focusable hrefs
and group expand overrides. Reference: mintlify.com/oramasearch/orama/quickstart.md
**markdown.tsx** changes:
- TocLink: new props dimmed (opacity 0.3 + tabindex=-1), isHighlighted
(code-bg background), linkRef (scroll-into-view)
- TableOfContents: search input with F hotkey badge, 80ms debounced Orama
search, arrow key navigation through matched results, Enter navigates
to section anchor, Escape clears and blurs
- Groups containing matches auto-expand, non-matching items dimmed at 0.3
- IntersectionObserver scroll lock via ref to prevent activeId bouncing
during programmatic smooth scroll (scrollend + safety timeout)
- Global F key listener focuses search (skips input/textarea/contenteditable)
The built-in vite:asset load hook uses a regex that doesn't match when
query params get normalized to ?raw= (URLSearchParams.toString() adds
the =). This pre-load plugin handles ?raw imports for non-JS files
explicitly.
- Wrap subscribe, getSnapshot, getServerSnapshot in useCallback to prevent
React from tearing down and recreating the IntersectionObserver on every render
- Move window.location.hash read from render into subscribe, keeping render pure
- Add emit() helper that deduplicates ref writes and only notifies React on change
- Initialize activeRef with fallbackId; hash is read on first subscribe
Replaces useState + useEffect with a single useSyncExternalStore that:
- Initializes activeRef from window.location.hash to fix flash on first paint
- Uses IntersectionObserver in subscribe to track scroll position
- Returns fallbackId as server snapshot to prevent hydration errors
One less state hook (no useState, no useEffect for the observer).
No-op subscribe meant useSyncExternalStore was effectively a constant.
Replaced with a direct window.location.hash read in the useState
initializer, guarded by typeof window for SSR. One less hook.
Previously the TOC always initialized activeId to the first item's href,
causing a visible flash when the page loaded with a hash (e.g. #getting-started)
until the IntersectionObserver corrected it.
Now useLocationHash() reads location.hash synchronously during hydration via
useSyncExternalStore, so the first render already highlights the correct section.
The hook also subscribes to hashchange events for anchor link clicks.
- Add pnpm.onlyBuiltDependencies for esbuild/sharp (need native builds)
- Add pnpm.ignoredBuiltDependencies for bufferutil/electron (skip builds)
- Update CI workflow to pnpm 10 to match local version
- Remove .npmrc (strict-builds setting wasn't picked up in CI)
pnpm v10 defaults strict-builds to true, which errors on packages with
unapproved build scripts (esbuild, sharp, electron, etc). Disabling it
allows CI installs to succeed without maintaining an approval list.
The page layout grid previously used 5 explicit columns to embed spacing:
grid-cols: [210px] [50px] [520px] [50px] [210px]
TOC gap content gap sidebar
col1 col2 col3 col4 col5
The two gap columns (2 and 4) were real grid tracks, not CSS gap. This meant:
- Column references were off-by-two (sidebar = col 5, main = col 3)
- SectionRow subgrid spans referenced col-[3/-1] to skip the gap column
- slot-main had overflow:hidden to prevent content from bleeding into the
adjacent gap column — this later caused visible clipping of content
New layout uses 3 columns + CSS gap-x:
grid-cols: [210px] [520px] [210px] gap-x: 50px (--grid-gap)
TOC content sidebar
col1 col2 col3
Changes:
- markdown.tsx: grid template from 5 cols to 3 cols + lg:gap-x-(--grid-gap)
- SectionRow: col-[3/-1] → col-[2/-1], aside col-[3] → col-[2]
- inline subgrid (section-based layout): col-[3/-1] → col-[2/-1]
- flat layout slot-main: col-[3] → col-[2]
- globals.css: slot-sidebar-right grid-column 5 → 3
- globals.css: remove overflow:hidden from slot-main — no longer needed
since there is no adjacent gap column for content to bleed into
- AGENTS.md: update layout diagram to reflect the 3-column structure
and note that spacing comes from CSS gap-x, not a slot
--grid-max-width calc and --grid-gap variable are unchanged; the total
computed width (1040px) is identical.
cli.ts — session new --direct:
Previously, a --direct string value was passed verbatim as the CDP endpoint,
which silently broke when the user passed 'localhost:9222' instead of a full
ws:// URL. Now resolveDirectInput() is called first: it normalises host:port
to a WebSocket URL via /json/version probe, passes ws:// URLs through as-is,
and surfaces a clear error for blocked or dead endpoints before any session
is created.
cli.ts — browser list command:
The old implementation only listed raw CDP instances from discoverChromeInstances
(DevToolsActivePort / port scan). Rewritten to show both:
- Extension-connected browsers (fetched from relay / waitForConnectedExtensions)
- Direct CDP instances on port 9222 (from discoverChromeInstances)
The relay server is started if needed so extensions can connect before the
2-second poll window. Output uses the shared printBrowserTable() formatter.
TYPE column now shows '--direct' instead of 'direct' to hint at the flag name.
Empty state message updated with actionable instructions for each connection type.
mcp.ts — getDirectCdpConfig:
PLAYWRITER_DIRECT='auto'/'1'/'true' → auto-discover on port 9222 (unchanged behaviour).
PLAYWRITER_DIRECT='ws://...' or 'host:port' → now routed through resolveDirectInput
instead of an ad-hoc string check, which also covers the new host:port format.
The previous implementation used two layered strategies:
1. Glob for DevToolsActivePort files across `~/Library/Application Support`,
`~/.config`, `%LOCALAPPDATA%` — walks the directory tree up to depth 3,
reads the file to get port + WS path, then reads `Local State` for profiles.
2. Port scan 9222-9229 via GET /json/version — fills in any instances not found
by file scan, or verifies/updates live wsUrl for those that were.
This caused real-world issues:
- Stale DevToolsActivePort files left by previous Chrome sessions returned dead
instances that then failed at connection time.
- Reading `Local State` JSON and walking the directory tree is slow and fragile
on systems where the browser data dir is not in a standard location.
- The deduplication + merge logic between the two strategies was complex and
hard to reason about.
- Chrome 136+ on macOS does not expose /json/version on the default profile by
default, so the HTTP probe already returned null for many users.
New approach:
- `discoverChromeInstances()` probes only port 9222 via GET /json/version.
Returns one DiscoveredInstance if Chrome responds with webSocketDebuggerUrl,
otherwise returns []. No file I/O, no port range scan, no profile reading.
- `resolveDirectInput(input)` is a new export that normalises a --direct value
into a WebSocket URL:
- ws:// or wss:// → returned as-is
- host:port → probed via /json/version; wsUrl returned if live,
'blocked' (HTTP 200 but no CDP) gives actionable error,
'dead' (ECONNREFUSED) gives clear "nothing listening" message
- Internal `probePortStatus()` replaces `probePort()` with a richer union type
{type: 'live'|'blocked'|'dead'} so callers can distinguish between "Chrome is
there but inaccessible" vs "nothing running at all".
- `probePort()` is kept as a thin public wrapper (live → wsUrl+browser, else null)
for backward compatibility with external callers.
- Removed exports: getChromeProfiles, deriveBrowserName, getDataDirParents,
findDevToolsActivePortFiles (and internal scanForActivePort).
- Tests updated: remove describe blocks for the deleted functions
(deriveBrowserName, getDataDirParents, getChromeProfiles), keep
parseDevToolsActivePort tests since that helper is still used.
- swap cac import for goke, add zod import
- remove manual type annotations from action callbacks (goke infers from schema)
- typed options with z.number().default(10000) for --timeout and z.string().default('0.0.0.0') for serve --host; plain string descriptions everywhere else
- removed @xmorse/cac from dependencies
Tommy D. Rossi