vercel-labs / vercel-labs/native

bridge flag for scene-declared webview shell views

Open
#103 0 comments 1 reaction 0 assignees View on GitHub

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
    a reload_token to force navigation when we need the page to pick up
    new state.
  • web → native: the page does a loopback fetch back 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.)

  • ShellView type has no bridge field:
    src/primitives/app_manifest/types.zig:383–411.
  • ViewOptions.bridge_enabled defaults to false
    (src/platform/types.zig:780) and webViewOptions() forwards it
    unchanged (types.zig:783–792); shell webview creation flows through
    src/platform/macos/root.zig:1119createWebView
    native_sdk_appkit_create_webview, and the ObjC
    createWebViewInWindow:...bridgeEnabled: installs the
    nativeSdkBridge script handler only when bridgeEnabled is set
    (appkit_host.m:7298–7326).
  • Contrast: native-sdk.webview.create (JS API for child webviews)
    accepts bridge: true and those webviews do get window.zero.
  • Repro app: spike/canvas-web/UiApp.Options.web_panes /
    scene-declared .webview shell 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.