#Views and split panes
Several webviews in one window as split panes with draggable dividers, each with its own route and permission scope, and how requests bind to their view.
Experimental. Part of Krate Native. Views are tested on Linux (WebKitGTK), macOS (
NSSplitView) and Windows (several WebView2 controllers in one window) by the CI native job; dragging a divider with a real pointer is not tested on the last two.
A window normally holds one webview. A window can hold several, laid out as split panes that the user resizes by dragging the dividers: an editor beside a preview, a sidebar page next to the main page, a terminal under both. Each view loads its own route of the app and can have its own permission scope. All views of an app share one web process (see Memory).
import { main, pane, split, onViewMessage } from "@krate/app/window";
const win = main();
const sidebar = await win.addView({ path: "/sidebar", side: "left", size: 0.25, minWidth: 180 });
const logs = await win.addView({ path: "/logs", side: "bottom", size: 0.3, minHeight: 100,
permissions: ["kv"] }); // a narrower scope
await sidebar.post({ open: "/tasks/3" }); // view to view
onViewMessage(({ from, data }) => console.log(from, data)); // in the receiving page
const layout = await win.layout(); // ratios after a drag
await win.setLayout(split("horizontal", pane(sidebar), split("vertical", pane(win.id), pane(logs), 0.7), 0.25));import "github.com/kratejs/krate/packages/native/sdk/window"
w := window.Main()
side, _ := w.AddView(window.ViewOptions{Path: "/sidebar", Side: window.Left, Size: 0.25, MinWidth: 180})
side.Post(map[string]any{"open": "/tasks/3"})
l, _ := w.Layout() // *window.Layout with the ratios the user dragged to
w.SetLayout(window.Split("horizontal", 0.25, window.Pane(side.ID), window.Pane(w.ID)))The operations need the window permission, like the rest of the window API.
#Views
Every window has a primary view, the one it was created with. Its id is the
window's id ("main", "w1"). addView creates more; each has an id ("v1",
"v2", or the id you pass: letters, digits, _ and -, at most 32, unique
among all window and view ids). Ids are never reused.
| Operation | Does |
|---|---|
window.addView(options) |
Splits a new view off an existing one. Returns the view. |
view.remove() |
Removes a view; the pane next to it takes its space. The primary view cannot be removed: close the window. |
window.views(), views() |
Lists views (id, window, path, primary), primary first. |
window.setLayout(layout), window.layout() |
Replaces the layout, or reads it back with the current ratios. |
view.focus() |
Gives the view keyboard focus. |
view.navigate(path) |
Loads another route in the view. (window.navigate still navigates the primary view.) |
view.post(data) |
Posts a message to the view; see Messages. |
onViewEvent(fn) |
Added, removed, navigated and closed events. |
addView options: path (default "/"), beside (the view to split; default
the primary view), side ("right" default, "left", "top", "bottom": where the
new view goes relative to beside), size (the share of the split the new view gets,
between 0 and 1, default 0.5), minWidth and minHeight (pixels, the smallest the
pane may be dragged to), permissions and id.
#Layout
A layout is a tree of splits. A leaf is a pane showing a view; a split puts two
subtrees side by side ("horizontal": first on the left) or one above the other
("vertical": first on top), with a ratio that is the share of the space the
first subtree gets (default 0.5, exclusive of the divider). Splits have two
halves; nest them for three panes or more.
split("horizontal", pane("main"), split("vertical", pane(a), pane(b), 0.6), 0.5)
// +---------+---------+
// | | a |
// | main +---------+
// | | b |
// +---------+---------+
setLayoutmust name every view of the window exactly once, with ratios in [0, 1) (zero is one half) and at most 16 nested splits. It fails withbad_argsotherwise and changes nothing. The pages do not reload.addViewandview.remove()edit the layout for you: adding replaces the pane ofbesideby a split of it and the new view; removing replaces the removed pane's split by its sibling.- Minimum sizes.
minWidth/minHeightbelong to a pane. A divider cannot be dragged past them, and a split's minimum is the sum of its panes' (plus the divider) along its axis. If a window is made smaller than the minimums allow, the space is shared in proportion to them. - Dividers are draggable by the user.
layout()returns the ratios the dividers have now, so an app can save them andsetLayoutthem on the next run. Ratios survive a resize (the panes grow and shrink together) and release.
The layout arithmetic (tree to rectangles, divider hit-testing, drag to ratio,
minimum sizes) is plain Go in platform/caps/layout.go with unit tests that run on
every OS; the Windows implementation uses it directly to place its controllers,
and the Linux and macOS ones use it to edit the tree and validate layouts while
GTK's GtkPaned and AppKit's NSSplitView draw the dividers.
#Scopes and identity
Each view has a permission scope of its own, keyed by its id. A view opened with
permissions: [...] may use only that list, which must be a subset of the
caller's scope; without the option it inherits the scope of the view that opened
it, exactly like window.open. A
window opened with a narrow scope keeps that scope for its primary view.
A page cannot choose its scope. The platform layer tags every request with
the webview it came from, and the shell maps that webview to a window or view id
and its scope. The x-krate-window header a page sets is ignored in a native
window. So a view with permissions: ["kv"] cannot reach fs by sending the
id of a wider view or window, and a message's from field (below) is the real
sender. A request from a webview the shell cannot place gets a scope that allows
nothing. An id names exactly one window or view from the moment it is chosen: a
view id that a window or view holds, or that window.open has handed out, is
refused with already_exists, and window.open skips ids that views took, so
closing a window never removes the scope of a view. Event streams and gated
signals follow the same identity: a stream started from one view can be read only
from that view.
Two limits remain. Every view of every window is on the same origin
(krate://app, https://app.localhost), so pages can read each other's
localStorage and cookies, and a scope is not an isolation boundary for content
you do not trust. And in browser mode (krate native dev --browser) there are no
native webviews: the header is the identity there, and a script in a tab can send
another window's id. Scopes in browser mode catch mistakes; they are not a
security boundary.
#Messages
view.post(data) delivers data (JSON-compatible, at most 1 MiB) to another view
of the app, in any window. The receiving page gets a DOM event:
window.addEventListener("krate:view-message", (e) => {
const { from, data } = (e as CustomEvent).detail; // from: the sender's view id
});
// or: onViewMessage(({ from, data }) => ...)
from is set by the shell from the sender's native identity; it is "" for a
message sent from host code. A message to a view that does not exist rejects with
not_found; one to a view of a released window rejects with an error (show the window
first, see Memory). Messages are not queued: a page that has not
loaded yet does not get them. Posting needs only the window permission on the
sender; the receiving page decides what to trust.
#Events
onViewEvent (stream krate/window.viewEvents; Go window.OnViewEvent) delivers
{ view, window, kind, path }:
| Kind | When |
|---|---|
added |
A view was created (path is its route). |
navigated |
A page finished loading in the view (path). Fires for the first load too. |
removed |
view.remove() took it out. |
closed |
Its page called window.close() (the view is removed), or its window closed. A window's views are announced closed before the window's own closed event. |
Events for a view are delivered after added, in order. The primary view of a
window gets navigated and closed events under the window's id.
#Memory
- One web process. On Linux every view is created with
webkit_web_view_new_with_related_viewof a live one, so all views of all windows share the app's single WebKitWebProcess; a test asserts the process count. Measured on Linux (WebKitGTK 2.54,balancedprofile, blank pages): about 1 MB of web process memory and 0.2 MB of shell memory per extra view in a window, against about 4 to 8 MB for an extra window (the GTK window and its compositing surfaces). See Measured. - Settings. Every view gets the developer tools (in dev), the memory profile and the navigation lock when it is created, the same as a window's first view.
- HMR and the dev inspector work per page, so every view hot-reloads.
krate native devevaluates itsevalcommand in every view of every window. - Release.
hide({ release: true })andnative.window.keepAliverelease the whole window: all its views are asked for their route and scroll position, then all webviews are destroyed (when every window is released the web process exits).show()recreates them all, with their routes, scroll positions, ids and layout ratios. While a window is releasedaddView,remove()andsetLayoutfail (show it first), and so doespostto its views. A window that is hidden without release gives every view thekrate:memory-pressureevent. - Closing a window destroys its views.
#Measured
Linux x86-64, WebKitGTK 2.54.0, Xvfb, balanced profile; PSS after settling:
| web process | shell process | |
|---|---|---|
| 1 view | 34 to 42 MB | 43 to 47 MB |
| 7 views in one window | 40 to 49 MB | 44 to 48 MB |
| per extra view | about 1 MB | about 0.2 MB |
| per extra window | 3.5 to 8 MB | 1 to 5 MB |
The per-view figure depends on the GL stack, because each page gets its own compositing buffers. On GitHub's ubuntu-24.04 runner (WebKitGTK 2.52.6, Mesa software GL, compositing on) every extra page costs about 40 MB of web process memory, whether it is a view or a window (37 to 62 MB per window, about 42 MB per view over several runs). A GPU keeps most of that in video memory. Views always share the one web process and need no extra GTK window.
Real pages cost what their DOM and scripts cost; the figure is the per-view overhead.
#Platform notes
| Linux | macOS | Windows | |
|---|---|---|---|
| Panes | nested GtkPaned; children keep their size request, which carries the minimum sizes |
nested NSSplitView; minimum sizes are Auto Layout constraints on each web view |
one WebView2 controller per view in the window, bounds from the Go layout |
| Divider drag | native GtkPaned handle |
native NSSplitView divider |
the window procedure hit-tests the divider (6 px, with a 3 px grab margin), shows the resize cursor and drags |
| Identity | webkit_uri_scheme_request_get_web_view |
the webView argument of webView:startURLSchemeTask: |
the sender of WebResourceRequested, one registration per controller |
| Web process | related views | one WKProcessPool |
one ICoreWebView2Environment |
A divider drag changes the ratio but fires no event; read it with layout(). On
macOS a page's window.close() does not remove a secondary view yet (Linux and
Windows remove it and send closed).
The examples/native-views app uses all of this: a main page with a sidebar view
and a log view, and a sidebar that posts to the log.
Last updated: 2026-11-17
Contributors: Noinkin