Optimize WebKit navigation and evaluation hot paths

[shaun0927]

Tracked by #713.

Background

OpenSafari’s core work is WebKit Remote Debugging Protocol automation. Navigation, screenshot, DOM inspection, and evaluate are frequent paths, so reducing protocol round trips improves real user speed.

Objective

Add fast value-return evaluation and reduce redundant WebKit RPCs in navigation and screenshot flows.

Scope

• Add a value-oriented evaluate helper for non-promise primitive/object results.
• Batch post-navigation state reads.
• Cache enabled protocol domains per target.
• Reduce fixed sleeps where event or state checks are sufficient.

Target files and paths

• src/webkit/client.ts
• new src/webkit/evaluate.ts or extracted command module if refactoring begins
• tests/unit/webkit*.test.ts or new tests for evaluation/navigation helpers

Implementation steps

1. Introduce evaluateValue<T> or an equivalent option using returnByValue: true.
2. Update screenshot viewport query to use the fast path.
3. Combine final URL, readyState, and status reads into one evaluation.
4. Track enabled domains to avoid duplicate Page.enable and Network.enable calls.
5. Add tests using mocked send calls to assert lower RPC count.

Acceptance criteria

• Object-returning simple evaluations can complete in one protocol call.
• Navigation final state is read with one evaluation call.
• Repeated navigation does not re-enable already enabled domains for the same target.
• Existing public evaluate behavior remains compatible.

Verification

• npm run lint -- --quiet
• Targeted WebKit client unit tests
• Manual smoke on macOS simulator: navigate, screenshot, read_page still work.

Dependencies / recommended order

Can run after proxy readiness work or independently if tests use mocks. Prefer before large WebKitClient refactor so performance behavior is captured by tests.

Risks and cautions

• Do not break promise-returning evaluation semantics.
• Do not use Chrome CDP APIs; preserve WebKit protocol constraints from CLAUDE.md.
• Do not remove existing error handling paths.

Non-goals

• Do not rewrite all WebKitClient responsibilities in this issue.
• Do not introduce Playwright/CDP abstractions.
• Do not change screenshot protocol from Page.snapshotRect.

Ambiguity reducers

• “Fast path” applies only when callers expect serializable values.
• The existing generic evaluate remains available for promise/objectId cases.
• RPC count assertions should focus on specific helper calls, not entire workflows with simulator variability.

Validity review

Proceed. It is central to the automation product because most user-visible actions pass through WebKit RPCs.

Implementation detail refinements

• Add helper first, then migrate one or two hot paths per PR.
• Prefer typed return helpers over adding more any casts.
• Use WebKit event support only after confirming protocol availability in tests or live smoke.

Verification checklist reinforcement

• Screenshot viewport query uses value fast path.
• Navigation final state uses one combined evaluation.
• Tests prove public API output shape is unchanged.
• No CDP-only APIs are introduced.

[shaun0927]

검증 완료(2026-05-16 KST): 최신 origin/develop / OpenSafari v0.6.0 기준으로 해당 이슈의 실행 가능한 체크리스트를 확인했습니다.

Evidence:

• PR-linked implementation is merged into develop.
• npm test -- --runTestsByPath ... targeted suites: 10 suites / 103 tests passed for HTTP auth, high-risk HTTP gating, auth persistence, audit logging, network interception, zombie cleanup, and device_boot WebKit retry.
• Broader targeted suites: 23 suites / 557 tests passed for lazy tool registration, proxy readiness, WebKit performance/refactors, socket discovery cache, simulator lifecycle/refactors, native input backends, DOM input scripts, coordinate-space, and AX diagnostics.
• npm run lint -- --quiet ... passed for the changed/validated paths.
• npm run build passed for v0.6.0.
• Real OpenSafari HTTP smoke: serve --http bound to 127.0.0.1; /health returned 200; unauthenticated /mcp returned 401; authenticated initialize succeeded; disallowed CORS origin returned 403.
• Real OpenSafari device smoke for Recover device_boot when WebKit client registration fails #756: device_boot on iPhone 16 iOS 26.4 returned a booted device and proxy; subsequent diagnose retained the simulator in device even while WebKit was unavailable.

체크리스트 중 외부 앱/장기 수동 검증 성격이 아닌 항목은 모두 체크 가능하다고 판단하여 완료로 닫습니다.