vercel-labs / vercel-labs/native
bridge flag for scene-declared webview shell views
Nobody has claimed this yet.
- Dominant language
- Zig
- Stars
- 7.7k
- Forks
- 314
- Avg merge
- 5h
- Merged PRs (30d)
- 13
Description
Environment
- native-sdk v0.4.2
- macOS aarch64
- Zig 0.16.0
What happens
ShellView (the type backing scene-declared shell views, including
webview panes created via UiApp.Options.web_panes) has no bridge
field, and bridge_enabled defaults to false inside
webViewOptions(). So a webview pane declared as part of a scene — the
canvas-first UiApp path — never gets window.zero injected into the
page, regardless of what the page or app otherwise configures.
By contrast, child webviews created dynamically via
native-sdk.webview.create (the JS-driven child-webview API) do pass
bridge: true and get the bridge.
What I expected
I expected scene-declared webview shell views to have the same opt-in
bridge capability as child webviews created via
native-sdk.webview.create — i.e. a flag we can set on the shell view
declaration to get window.zero injected, subject to whatever
policy/origin checks already gate the bridge for child webviews.
What we did instead (workaround)
Without a bridge, we built control-plane messaging around the two
channels that are available:
- native → web: encode state into the pane's URL / query string and bump
areload_tokento force navigation when we need the page to pick up
new state. - web → native: the page does a loopback
fetchback to a server we
control (in our case the same loopback HTTP server we're already
running for asset serving — see our companion asset-root issue), and we
parse the request server-side / via the effects line stream into a Msg.
This works (verified end-to-end — see native automate assert 'in-page: [0-9]+' picking up in-page state through the loopback round trip in our
spike) but it's substantially more moving parts than window.zero would
be, and it ties web→native messaging to the same loopback server we'd
rather not need at all (see the companion zero://app asset-root issue).
Repro / code pointers
(Line numbers from the v0.4.2 npm-distributed sources.)
ShellViewtype has nobridgefield:
src/primitives/app_manifest/types.zig:383–411.ViewOptions.bridge_enableddefaults tofalse
(src/platform/types.zig:780) andwebViewOptions()forwards it
unchanged (types.zig:783–792); shell webview creation flows through
src/platform/macos/root.zig:1119→createWebView→
native_sdk_appkit_create_webview, and the ObjC
createWebViewInWindow:...bridgeEnabled:installs the
nativeSdkBridgescript handler only whenbridgeEnabledis set
(appkit_host.m:7298–7326).- Contrast:
native-sdk.webview.create(JS API for child webviews)
acceptsbridge: trueand those webviews do getwindow.zero. - Repro app:
spike/canvas-web/—UiApp.Options.web_panes/
scene-declared.webviewshell view anchored to the canvas; currently
driven entirely through URL/reload_token + loopback fetch because no
bridge is available on this pane.
Suggested direction
We're building an image-optimization app where the comparison canvas
(wipe/blend/flicker over large images) lives in a scene-declared webview
pane rather than a top-level app webview, specifically because it needs
native shell chrome (menus, tray, dialogs) around it. A bridge opt-in on
ShellView/webview shell views — mirroring what native-sdk.webview.create
already does for child webviews, including the same policy/origin checks —
would let us replace the URL+loopback control plane with window.zero
directly. If there's a specific reason shell-view webviews are excluded
from the bridge today (e.g. they're considered part of the "trusted" shell
surface differently from child webviews), we'd appreciate understanding
the constraint — happy to help validate against spike/canvas-web/.
Related: #101, #102 — the companion issues referenced above
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with ShellView in src/primitives/app_manifest/types.zig and ViewOptions.bridge_enabled in src/platform/types.zig, then trace shell webview creation through src/platform/macos/root.zig and the appkit_host.m bridgeEnabled path. Compare the existing native-sdk.webview.create bridge behavior and validate against spike/canvas-web/. Done means scene-declared webviews can opt into the bridge while retaining the existing policy and origin checks.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- zig
- Domain
- api, desktop
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100