vercel-labs / vercel-labs/native

Add typed Cmd.navigateWebView for TypeScript cores

Open
#290 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

Problem

TypeScript Native apps can declare child WebViews in app.zon, but their compiled core cannot navigate those WebViews after startup.

The existing native-sdk.webview.navigate command is available only to WebView JavaScript through window.zero. Zig UiApp apps can use WebViewPane.url, but TypeScript cores have no equivalent.

Proposed API
Cmd.navigateWebView(
  label: string,
  url: Uint8Array,
): Cmd<never>

Example:

Cmd.navigateWebView(
  "preview",
  asciiBytes("http://127.0.0.1:43110/preview"),
);
Semantics
  • Runs after the model commits during normal command processing.
  • Targets an existing child WebView by label.
  • Reuses the existing runtime navigation path.
  • Enforces security.navigation.allowed_origins.
  • Rejects navigation to the main WebView.
  • Does not create or destroy WebViews.
  • Requires no additional permission beyond the existing WebView capability and navigation policy.
  • Is fire-and-forget, like Cmd.showWindow.
  • Invalid targets or denied URLs are logged without crashing the update loop.
  • Fake and replay hosts can record the requested navigation without requiring a platform WebView.
Acceptance criteria
  • TypeScript cores can compile and emit the command.
  • URL navigation works for declared child WebViews.
  • Same-URL navigation can be requested explicitly to force a reload.
  • Disallowed origins are rejected.
  • Missing labels and attempts to navigate the main WebView fail safely.
  • Runtime tests cover real and fake execution paths.
  • No generated app-runner changes are required.

Related: #15 covers a lower-level thread-safe runtime reload API for sidecar respawn scenarios.

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 by tracing the existing native-sdk.webview.navigate path and the Zig UiApp WebViewPane.url implementation, then compare Cmd.showWindow's fire-and-forget behavior. Follow how TypeScript cores emit commands and how real, fake, and replay hosts execute them. Done means declared child WebViews navigate safely, policy and invalid-target cases are covered, and runtime tests pass without generated app-runner changes.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript, zig
Domain
api, desktop
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.