vercel-labs / vercel-labs/native
Add typed Cmd.navigateWebView for TypeScript cores
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
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 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