fix(types): connect() returns a typed Page handle (v0.20.0)

[hamr0]

Summary

connect() was typed Promise<object>, so TypeScript adopters could not dereference page.goto / page.snapshot / page.click / page.close off the returned handle without casting — the entire interactive surface was unusable from types. Relayed from a peer session that found it scanning the published type surface; the publish adopter gate missed it because its quickstart only dereferences browse()'s string, never the connect() handle.

Fix

• Drop connect()'s @returns {Promise<object>} so tsc infers the shape structurally from the returned object literals; re-export it as a named Page type (Awaited<ReturnType<typeof connect>>) — no hand-maintained interface to drift.
• Page is a union of the two engine shapes (Chromium/CDP, Firefox/BiDi). Shared interaction methods dereference directly; an engine-specific escape hatch (cdp/createTab/dialogLog on Chromium, bidi/context on Firefox) is reached by narrowing (if ('cdp' in page)). Union is sound where an intersection would falsely claim a page carries both engines' hatches.
• The always-optional option params on snapshot() / type() / injectCookies() are typed optional (= {} defaults) with named, member-checked shapes (exported SnapshotOptions / TypeOptions / CookieOptions), so page.snapshot() compiles and snapshot({ mdoe: 'read' }) is now a compile error, not a silent no-op.
• browse() → Promise<string> unchanged.

Behavior-preserving: each method reads its opts via ?., and cdpType already defaults opts = {}. The Firefox type() default even removes a latent !!typeOpts.clear deref-on-undefined crash.

Validation

• Packed the tarball, installed into a clean strict / nodenext / skipLibCheck:false consumer, compiled a quickstart dereferencing the real page methods → green after, red before (mutation check: no Page export, cdp/createTab inaccessible). Valid options compile; typos red.
• tsc --noEmit exit 0 · full suite 254/254 · /security clean · /code-review medium → 1 minor finding (weak option types), fixed.

Bumps to v0.20.0 (minor: new public type exports). The [0.20.0] CHANGELOG entry also carries the already-unreleased CI entries (publish gate, npm@11 pin, scratch de-track).

🤖 Generated with Claude Code