feat(browser): add NativeKit-powered PiP overlay#2011
Open
zerob13 wants to merge 9 commits into
Open
Conversation
Contributor
📝 WalkthroughWalkthroughThe PR adds NativeKit 0.6.0 as the preferred Agent Browser PiP surface on supported runtimes, preserves Canvas fallback behavior, introduces native overlay lifecycle and frame routing, updates typed contracts and renderer handling, validates packaged prebuilds, and documents the migration. ChangesNativeKit Agent Browser PiP
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant AgentBrowserPiP
participant BrowserClient
participant YoBrowserPresenter
participant AgentBrowserNativeOverlay
participant NativeKit
AgentBrowserPiP->>BrowserClient: setPreviewMode
BrowserClient->>YoBrowserPresenter: invoke preview mode route
YoBrowserPresenter->>AgentBrowserNativeOverlay: prepare native target
YoBrowserPresenter->>AgentBrowserNativeOverlay: present JPEG frame
AgentBrowserNativeOverlay->>NativeKit: push image
NativeKit-->>AgentBrowserNativeOverlay: activate or dismiss action
AgentBrowserNativeOverlay-->>YoBrowserPresenter: forward scoped action
YoBrowserPresenter-->>BrowserClient: emit browser.preview.action
BrowserClient-->>AgentBrowserPiP: deliver preview action
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
…ndow # Conflicts: # src/renderer/src/lib/icons/icon-collections.generated.ts
zerob13
marked this pull request as ready for review
July 23, 2026 10:56
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/architecture/nativekit-agent-browser-pip/spec.md`:
- Around line 19-22: Refresh the NativeKit implementation evidence in the spec
to use version 0.5.5 throughout: update the Electron/native addon smoke,
upstream demo prebuild regression, and packaged artifact references from 0.5.4
to the current tarball, and replace obsolete nativekit.napi.node evidence with
node.napi.node while preserving the existing runtime and capability conclusions.
- Around line 114-115: Resolve the contract mismatch for xwayland-satellite by
updating the PiP movement requirements and corresponding goals, performance, and
acceptance sections to explicitly document its host-bound clipping, or by making
that runtime satisfy unrestricted out-of-window dragging before marking the
capability matrix and contract complete. Keep the behavior consistent across all
referenced sections.
In `@docs/features/agent-browser-pip/spec.md`:
- Around line 56-60: Scope the architecture statements in the “V1 Critical
Architecture Correction” section, including the PiP-in-conversation goal and
renderer-owned Canvas surface constraints, explicitly to the renderer-canvas
fallback runtime. Preserve the one-page, read-only mirror invariant while
clarifying that these constraints do not apply to the shipped NativeKit path.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 76ee1a9f-6cd4-408b-ad63-cd1ed03cb004
📒 Files selected for processing (27)
docs/architecture/nativekit-agent-browser-pip/plan.mddocs/architecture/nativekit-agent-browser-pip/spec.mddocs/architecture/nativekit-agent-browser-pip/tasks.mddocs/features/agent-browser-pip/spec.mdelectron-builder.ymlpackage.jsonpnpm-workspace.yamlresources/model-db/providers.jsonscripts/afterPack.jssrc/main/desktop/browser/AgentBrowserNativeOverlay.tssrc/main/desktop/browser/YoBrowserPresenter.tssrc/main/desktop/routes.tssrc/renderer/api/BrowserClient.tssrc/renderer/src/components/browser/AgentBrowserPiP.vuesrc/shared/contracts/events.tssrc/shared/contracts/events/browser.events.tssrc/shared/contracts/routes/browser.routes.tssrc/shared/types/browser.tssrc/shared/types/desktop.tstest/main/build/electronBuilderConfig.test.tstest/main/desktop/browser/AgentBrowserNativeOverlay.test.tstest/main/desktop/browser/YoBrowserPresenter.test.tstest/main/routes/contracts.test.tstest/main/scripts/afterPack.test.tstest/renderer/api/clients.test.tstest/renderer/components/AgentBrowserPiP.test.tstest/setup.ts
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/features/agent-browser-pip/spec.md (1)
11-17: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAlign all out-of-window claims with the xwayland-satellite limitation.
The architecture explicitly supports xwayland-satellite but limits it to host bounds, so “supported runtimes” cannot universally promise work-area-only, out-of-window movement.
docs/features/agent-browser-pip/spec.md#L11-L17: qualify the status statement to exclude host-bounded xwayland-satellite.docs/architecture/nativekit-agent-browser-pip/spec.md#L28-L31: propagate the exception through the goals, performance, and acceptance wording.docs/features/agent-browser-pip/spec.md#L107-L108: preserve the same exception in the non-goal.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/features/agent-browser-pip/spec.md` around lines 11 - 17, Qualify the out-of-window support claims to exclude host-bounded xwayland-satellite: update docs/features/agent-browser-pip/spec.md lines 11-17 and 107-108, and docs/architecture/nativekit-agent-browser-pip/spec.md lines 28-31, preserving the stated native behavior for other supported runtimes while explicitly limiting xwayland-satellite movement to host bounds.
🧹 Nitpick comments (1)
docs/architecture/nativekit-agent-browser-pip/tasks.md (1)
8-20: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winRecord explicit validation for the shipped NativeKit version.
The checklist only names v0.5.4/v0.5.5 reviews, while this migration changes the dependency to 0.6.0, including controls and prebuild filenames. Add explicit 0.6.0 source/demo/prebuild validation or label the older items as historical prerequisites.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/architecture/nativekit-agent-browser-pip/tasks.md` around lines 8 - 20, Update the documentation checklist to explicitly record validation of the shipped NativeKit v0.6.0 source, upstream demo control flow, controls, and prebuild filenames; alternatively, clearly label the existing v0.5.4/v0.5.5 entries as historical prerequisites and add the corresponding v0.6.0 validation evidence.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/architecture/nativekit-agent-browser-pip/spec.md`:
- Around line 558-572: Update
docs/architecture/nativekit-agent-browser-pip/spec.md lines 558-572 to replace
the historical 0.5.4 evidence and obsolete nativekit.napi.node filename with the
completed NativeKit 0.6.0 smoke results and current arm64/x64 prebuild
filenames. Update docs/architecture/nativekit-agent-browser-pip/tasks.md lines
90-95 to mark macOS arm64 validation complete only based on those 0.6.0 checks.
---
Outside diff comments:
In `@docs/features/agent-browser-pip/spec.md`:
- Around line 11-17: Qualify the out-of-window support claims to exclude
host-bounded xwayland-satellite: update docs/features/agent-browser-pip/spec.md
lines 11-17 and 107-108, and
docs/architecture/nativekit-agent-browser-pip/spec.md lines 28-31, preserving
the stated native behavior for other supported runtimes while explicitly
limiting xwayland-satellite movement to host bounds.
---
Nitpick comments:
In `@docs/architecture/nativekit-agent-browser-pip/tasks.md`:
- Around line 8-20: Update the documentation checklist to explicitly record
validation of the shipped NativeKit v0.6.0 source, upstream demo control flow,
controls, and prebuild filenames; alternatively, clearly label the existing
v0.5.4/v0.5.5 entries as historical prerequisites and add the corresponding
v0.6.0 validation evidence.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: a1f043fe-0ba4-4b01-b2ef-3154077f5a87
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (9)
docs/architecture/nativekit-agent-browser-pip/plan.mddocs/architecture/nativekit-agent-browser-pip/spec.mddocs/architecture/nativekit-agent-browser-pip/tasks.mddocs/features/agent-browser-pip/spec.mdpackage.jsonresources/acp-registry/registry.jsonsrc/main/desktop/browser/AgentBrowserNativeOverlay.tstest/main/build/electronBuilderConfig.test.tstest/main/desktop/browser/AgentBrowserNativeOverlay.test.ts
🚧 Files skipped from review as they are similar to previous changes (4)
- package.json
- docs/architecture/nativekit-agent-browser-pip/plan.md
- test/main/desktop/browser/AgentBrowserNativeOverlay.test.ts
- src/main/desktop/browser/AgentBrowserNativeOverlay.ts
Comment on lines
+558
to
+572
| - `@zerob13/nativekit` is pinned to `0.6.0`, remains external to the main bundle, and its prebuilds | ||
| are unpacked from ASAR. | ||
| - NativeKit 0.6.0 configures `open-panel` and `close` controls, emits their IDs through `control`, | ||
| sizes the native panel to 360 x 225 DIP, and keeps root-level sizing independent of host bounds. | ||
| - The published 0.5.5 tarball uses `node.napi.node` for all five prebuilds. This matches | ||
| `@electron/rebuild` on x64, but its arm64 lookup requires `node.napi.armv8.node`; the missing | ||
| match caused the Linux arm64 install to fall back to `node-gyp` and fail on unavailable X11 | ||
| development packages. | ||
| - NativeKit 0.5.6 uses the architecture-specific filenames expected by `@electron/rebuild`: | ||
| `node.napi.armv8.node` for arm64 and `node.napi.node` for x64. | ||
| - Installing the published 0.6.0 package on macOS arm64 completes | ||
| `electron-builder install-app-deps`, resolves the arm64 prebuild with `PREBUILDS_ONLY=1`, and | ||
| creates no NativeKit `build/Release` fallback binary. | ||
| - Loading the published 0.6.0 arm64 prebuild and calling | ||
| `start({ controls: [open-panel, close] }) -> stop` succeeds. |
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Base completed validation claims on NativeKit 0.6.0 artifacts.
The current evidence and checklist still rely on 0.5.4 smoke/package results and the obsolete nativekit.napi.node filename.
docs/architecture/nativekit-agent-browser-pip/spec.md#L558-L572: replace historical evidence with the 0.6.0 smoke and current arm64/x64 filenames.docs/architecture/nativekit-agent-browser-pip/tasks.md#L90-L95: only mark macOS arm64 validation complete after those 0.6.0 checks pass.
📍 Affects 2 files
docs/architecture/nativekit-agent-browser-pip/spec.md#L558-L572(this comment)docs/architecture/nativekit-agent-browser-pip/tasks.md#L90-L95
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/architecture/nativekit-agent-browser-pip/spec.md` around lines 558 -
572, Update docs/architecture/nativekit-agent-browser-pip/spec.md lines 558-572
to replace the historical 0.5.4 evidence and obsolete nativekit.napi.node
filename with the completed NativeKit 0.6.0 smoke results and current arm64/x64
prebuild filenames. Update
docs/architecture/nativekit-agent-browser-pip/tasks.md lines 90-95 to mark macOS
arm64 validation complete only based on those 0.6.0 checks.
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
1 participant
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
@zerob13/nativekitto0.6.0controlIDs to the existing typedactivate/dismissflowWhy
NativeKit 0.6.0 replaces fixed product-semantic controls with up to two caller-configured controls and emits their IDs through
control. It also decouples root-level overlay sizing and anchoring from host-window bounds. DeepChat can therefore own the button semantics while NativeKit owns native window movement and rendering.UI / interaction
[▯]: open the existing Browser side panel[×]: dismiss PiP for the current Agent runValidation
pnpm installpnpm run formatpnpm run i18npnpm run lintpnpm run typecheckpnpm run buildPREBUILDS_ONLY=1resolved the published macOS arm64node.napi.armv8.nodestart({ controls: [...] }) -> stoppassedgit diff --checkDependency review
v0.6.0, commit02cdbcfDev sync
The branch contains current
origin/devatf4525e66cand was 0 commits behind when this update was pushed.