#Compatibility Matrix
The public Krate compatibility matrix for React source components, Preact islands, SSR, the browser conformance corpus, and Krate Native per operating system.
This is the support contract for React compatibility. A surface is only marked supported or stable when the referenced tests pass. Known divergences are listed instead of silently hidden.
Last verified: 2026-11-13. See the roadmap for phase status and the React compatibility guide for usage.
#Status key
- Stable - covered by the corpus and the cross-browser gate.
- Supported - implemented and backed by the tests listed under Evidence, which run in CI; edge cases may still change before v1.
- Partial - a documented subset works; unsupported patterns must produce a diagnostic.
- Planned - not part of the supported surface yet.
- Untested - Krate Native only: the code exists and builds for that OS, but no test has run there. The row's known limits say what has and has not been checked.
- n/a - not applicable; for Krate Native it can mean the API answers
ErrUnsupportedon that OS.
#Surfaces
| Surface | Source | Islands | SSR | v1 target |
|---|---|---|---|---|
| Hooks: state and reducers | Supported | Supported | n/a | React 18 parity |
| Hooks: effects and memo | Supported | Supported | n/a | React 18 parity |
| Context and refs | Supported | Supported | n/a | Stable |
| Transitions and deferred values | Supported | Supported | n/a | Documented semantics |
| Class components | Supported | n/a | n/a | Full common subset |
| Error boundaries | Supported | Supported | Partial | Source and island |
| Per-segment not-found and error pages | Supported | n/a | Supported | Next.js not-found.tsx and error.tsx |
| Children, keys, and refs | Partial | Partial | n/a | Documented semantics |
| Events | Supported | Supported | n/a | React 18 parity |
| Forms and inputs | Supported | Supported | n/a | React 18 parity |
| Portals | Supported | Supported | n/a | SSR-safe |
| Suspense | Supported | Supported | n/a | SSR-safe |
| React 19 actions and forms | Supported | Partial | n/a | Source semantics |
| React 19.2: useId, useEffectEvent, Activity, ViewTransition | Supported | n/a | n/a | Source semantics |
| Custom elements | Supported | n/a | n/a | React 19 semantics |
| Component tiers: client APIs, conflicts and higher-order components | Supported | n/a | n/a | Krate semantics |
| Server actions | Supported | n/a | Supported | Progressive enhancement |
| Data cache and revalidation | Supported | n/a | Supported | next/cache parity |
| Compiled React packages | n/a | Supported | Supported | Documented compat |
| shadcn-style dashboard | Supported | n/a | n/a | Stable |
| Next.js app corpus | Supported | n/a | n/a | Migration-ready |
| Local components in islands | n/a | Supported | n/a | Supported |
| npm React hook libraries (zustand, react-hook-form, SWR, TanStack Query, ...) | n/a | Supported | Supported | Run as Preact islands |
| Compiled React packages in async pages, layouts and server components (lucide-react, Radix) | n/a | Supported | Supported | Client boundaries rendered with Preact |
| CSS-in-JS (styled-components, emotion, MUI) | n/a | Partial | Partial | Client-only islands |
| Island hydration control (client:visible, client:idle) | n/a | Supported | n/a | Astro-style directives |
| Real-React islands (react-reconciler libraries) | n/a | Supported | n/a | Opt-in real React |
| @krate/three (react-three-fiber API) | Supported | n/a | Partial | @react-three/fiber 9 API without React |
| @react-three/fiber | n/a | Partial | n/a | Real-React island |
| @react-three/drei | n/a | Partial | n/a | Real-React island |
| @krate/konva (react-konva API) | Supported | n/a | Partial | react-konva 19 API without React |
| react-konva | n/a | Partial | n/a | Real-React island |
| SSR island hydration | n/a | Supported | Supported | Hydration-safe |
| Supported Preact versions | n/a | Supported | n/a | 10.20 through current |
| Browser differential corpus | Supported | n/a | n/a | No P0/P1 divergence |
| React 19 reference app | Supported | n/a | n/a | Same browser suite as React 18 |
| Serverless and Node deployment | n/a | n/a | Supported | Vercel, Netlify, Cloudflare and Node hosting |
| Metadata routes and ImageResponse | Supported | n/a | Supported | Next.js sitemap.ts, robots.ts, manifest.ts, opengraph-image and twitter-image |
| Code highlighting (build, request time, browser) | Supported | Supported | Supported | chroma parity |
| sonner (toasts) | n/a | Supported | Supported | Run as Preact islands |
| cmdk (command menu) | n/a | Supported | Supported | Run as Preact islands |
| embla-carousel-react | n/a | Supported | Supported | Run as Preact islands |
| @dnd-kit/core and @dnd-kit/sortable | n/a | Supported | Supported | Run as Preact islands |
| @tanstack/react-table (v8) | n/a | Supported | Supported | Run as Preact islands |
| next-themes | n/a | Supported | Supported | Run as Preact islands |
| motion v12+ (motion/react) | n/a | Supported | Supported | Run as Preact islands |
#Krate Native
Krate Native is experimental: its API, app.json fields and SDK can change between
releases. It targets Linux (GTK 3 and WebKitGTK 4.1 through purego), macOS (WKWebView)
and Windows (WebView2), on x64 and arm64. The CI native job runs the GUI tests on
all of them and blocks the pull request. A cell says Supported when tests that drive
a real window on that OS pass there, and Untested when none do or the relevant ones
skip. Real hardware (cameras, suspend), screen readers, notarization and store
submission are listed as limits in the details.
| Surface | Linux | macOS | Windows | v1 target |
|---|---|---|---|---|
| Native: window and custom scheme | Supported | Partial | Supported | Krate Native v1 |
| Native: streaming responses | Supported | Supported | Supported | Krate Native v1 |
| Native: host calls, streams and signals | Supported | Supported | Supported | Krate Native v1 |
| Native: Go host code | Supported | Supported | Supported | Krate Native v1 |
| Native: TypeScript host code on QuickJS | Supported | Supported | Supported | Krate Native v1 |
| Native: Node, Bun and Deno host children | Supported | Partial | Partial | Krate Native v1 |
| Native: SDK data areas (kv, db, fs, net, os) | Supported | Partial | Partial | Krate Native v1 |
| Native: SDK windows | Partial | Partial | Partial | Krate Native v1 |
| Native: requests are bound to the webview they came from | Supported | Supported | Supported | Krate Native v1 |
| Native: views and split panes | Supported | Supported | Supported | Krate Native v1 |
| Native: print, PDF, find, zoom and capture of a view | Supported | Untested | Untested | Krate Native v1 |
| Native: downloads started by the page | Supported | Supported | Supported | Krate Native v1 |
| Native: cookies and site data | Supported | Supported | Supported | Krate Native v1 |
| Native: remote views cannot reach the app | Supported | Untested | Untested | Krate Native v1 |
| Native: remote storage partitions | Supported | Supported | Supported | Krate Native v1 |
| Native: request rules for remote views | Supported | Untested | Untested | Krate Native v1 |
| Native: remote user agent, proxy, certificates and logins | Supported | Untested | Untested | Krate Native v1 |
| Native: remote message channel | Supported | Supported | Supported | Krate Native v1 |
| Native: shared web process, release and background mode | Supported | Untested | Untested | Krate Native v1 |
| Native: lean pages and the dev Memory panel | Supported | Supported | Supported | Krate Native v1 |
| Native: SDK dialogs, clipboard and menus | Supported | Untested | Untested | Krate Native v1 |
| Native: rich clipboard formats | Supported | Supported | Supported | Krate Native round 4 |
| Native: webview context menu | Supported | Untested | Untested | Krate Native round 4 |
| Native: debugging in krate native dev | Supported | Supported | Untested | Krate Native round 4 |
| Native: SDK notifications | Supported | Partial | Partial | Krate Native v1 |
| Native: camera, microphone, screen capture and location permissions | Supported | Supported | Supported | Krate Native v1 |
| Native: media permissions derived from the UI, usage descriptions and capabilities | Supported | Untested | Untested | Krate Native v1 |
| Native: operating system consent for camera, microphone, screen and location | Partial | Supported | Supported | Krate Native v1 |
| Native: screen and window capture sources | Partial | Supported | Supported | Krate Native v1 |
| Native: SDK tray and global shortcuts | Partial | Partial | Partial | Krate Native v1 |
| Native: SDK app lifecycle | Supported | Partial | Partial | Krate Native v1 |
| Native: file associations | Partial | Untested | Untested | Krate Native v1 |
| Native: opening files | Supported | Supported | Supported | Krate Native v1 |
| Native: dropped file paths | Supported | Supported | Untested | Krate Native v1 |
| Native: release as a single executable | Supported | Supported | Supported | Krate Native v1 |
| Native: prebuilt shell for apps without Go | Supported | Partial | Partial | Krate Native v1 |
| Native: krate native doctor | Supported | Supported | Supported | Krate Native v1 |
| Native: krate native test and the app driver | Supported | Supported | Supported | Krate Native v1 |
| Native: migration guides and the worked Electron port | Supported | Supported | Supported | Krate Native v1 |
| Native: plugins | Supported | Supported | Supported | Krate Native v1 |
| Native: packaging formats | Partial | Supported | Supported | Krate Native v1 |
| Native: signing and notarization | Partial | Partial | Partial | Krate Native v1 |
| Native: macOS universal apps | Supported | Untested | Supported | Krate Native round 4 |
| Native: Flatpak | Partial | Planned | Planned | Krate Native round 4 |
| Native: Snap | Partial | Planned | Planned | Krate Native round 4 |
| Native: Mac App Store | Planned | Supported | Planned | Krate Native round 4 |
| Native: Microsoft Store | Supported | Supported | Untested | Krate Native round 4 |
| Native: updater | Supported | Supported | Supported | Krate Native v1 |
| Native: app icon badge and progress | Supported | Supported | Supported | Krate Native round 3 |
| Native: displays | Supported | Supported | Supported | Krate Native round 3 |
| Native: power, idle and sleep blockers | Supported | Untested | Supported | Krate Native round 3 |
| Native: launch at login | Supported | Supported | Supported | Krate Native round 3 |
| Native: system theme | Supported | Supported | Supported | Krate Native round 3 |
| Native: crash reports | Supported | Supported | Supported | Krate Native round 3 |
| Native: size, start-up and memory budgets | Supported | Supported | Supported | Krate Native v1 |
| Native: custom title bars, drag regions and transparency | Supported | Untested | Untested | Krate Native v1 |
| Native: Mica, Acrylic, vibrancy, caption overlay and traffic lights | n/a | Supported | Supported | Krate Native v1 |
| Native: tabs, sheets, document state, share menu, dock, thumbnail buttons and jump lists | n/a | Supported | Supported | Krate Native v1 |
| Native: worker processes | Supported | Supported | Supported | Krate Native v1 |
| Native: message ports between views, windows and workers | Supported | Supported | Supported | Krate Native v1 |
| Native: offscreen rendering | Supported | Supported | Supported | Krate Native v1 |
| Native: remote debugging and automation | Supported | Supported | Supported | Krate Native v1 |
| Native: browser extensions | n/a | Untested | Untested | Krate Native v1 |
| Native: accessibility of the shell's own UI | Supported | Supported | Supported | Krate Native v1 |
#Details
#Hooks: state and reducers
Source: Supported - Islands: Supported - SSR: n/a
useState and useReducer lower to signals with React render snapshots (handlers and effects read the committed state, functional updaters the latest), Object.is bail-out, lazy initializers (inline or named), useReducer init, a stable dispatch, and React's update lanes (discrete events commit in a microtask, other updates in a later task).
Evidence: TestReactUseReducerBuild, TestRewriteReactUseReducer, browser:/react-effects/
#Hooks: effects and memo
Source: Supported - Islands: Supported - SSR: n/a
Effects run in React's commit order (insertion, layout before paint, passive after paint or synchronously after discrete events; children before parents; cleanups before re-runs; parent-first unmount) with Object.is deps, and setups/cleanups read the state and props of their own commit. useMemo/useCallback honour deps synchronously. A component in one conditional branch unmounts and remounts with fresh state; one stateful component type in both branches of a ternary (or chain, or early returns) keeps its instance and switches its props. Effects without deps re-run on the component's own state/props changes only; each divergence has a KR2xxx diagnostic.
Known limits:
- A same-type pair that cannot be lowered to one element (render-prop children, a differing ref or spread, a wrapper element built by each branch) restarts the component on the flip and warns with KR8360.
- A stateless component or an external island in both branches is not merged: uncontrolled DOM state inside it resets on the flip.
Diagnostics: KR8360
Evidence: TestEffectPhasesLowerToCreateEffectDeps, TestSameTypeBranchesBuildOneInstance, browser:/react-effects/, browser:/react-branches/
#Context and refs
Source: Supported - Islands: Supported - SSR: n/a
Context resolves at the reader's position like React: Provider, React 19
Evidence: TestUseContextTranspile, TestContextReact19ProviderAndConsumer, browser:/react-events/
#Transitions and deferred values
Source: Supported - Islands: Supported - SSR: n/a
useTransition and startTransition support async actions: isPending stays true until the action, its awaited work and overlapping transitions settle, and a transition keeps revealed Suspense content. useDeferredValue (with React 19 initialValue) catches up in a later task; useSyncExternalStore follows the store by Object.is and unsubscribes on teardown. Updates after an await are ordinary updates, as in React 19.
Evidence: TestRewriteReactUseTransitionLowered, browser:/react-suspense/, fixture:examples/src/pages/react-suspense.tsx
#Class components
Source: Supported - Islands: n/a - SSR: n/a
Lowered onto a runtime instance with React 18 ordering: batched setState with callbacks, forceUpdate, componentDidMount/DidUpdate (props and state, children first)/WillUnmount on branch removal, shouldComponentUpdate, PureComponent, getDerivedStateFromProps, getSnapshotBeforeUpdate, defaultProps, contextType, accessors, private members, and instance refs. UNSAFE_componentWillMount, legacy context and other statics are rejected with KR3xxx diagnostics.
Evidence: TestClassComponentLowering, browser:/react-class/, fixture:examples/src/pages/react-class.tsx
#Error boundaries
Source: Supported - Islands: Supported - SSR: Partial
Classes with getDerivedStateFromError/componentDidCatch catch errors from descendants' render, bindings, lifecycles and effects (not event handlers or async code), unmount the failed subtree, and recover on reset. A throw while the page is built renders the boundary fallback (KR3009). Uncaught errors unmount only the failing component. Each Preact island has its own error boundary and marks a fallback placeholder when rendering fails.
Known limits:
- Build-time boundary fallback for a browser-only island subtree is client-only; the island error boundary handles the client render failure.
- Island error boundaries catch Preact render errors, not event-handler or asynchronous errors.
Diagnostics: KR3008, KR3009
Evidence: browser:/react-class/, browser:/react-demo/
#Per-segment not-found and error pages
Source: Supported - Islands: n/a - SSR: Supported
404.tsx or not-found.tsx and error.tsx or 500.tsx in any pages directory are that segment's pages. The nearest not-found page answers an unmatched URL, a closed dynamic route's unknown param and notFound() (status 404, inside the segment's layouts); the nearest error page answers an uncaught server error (status 500, sanitized message plus a digest) and, as a client error boundary around the segment's children, render, effect and reactive errors, with reset() and a hand-over to the next boundary up when an error page itself fails. The router swaps either page in place and keeps shared layouts. Pages are noindex and stay out of the sitemap and the route list.
Known limits:
- A page that throws while it is prerendered still fails the build (KR3010); the segment error page is not baked in as a build-time fallback.
- A 404, 403 or 401 page can render per request (ssr, async, runtime components) with its status; error pages are always prerendered and ignore request-time modes with KR9003.
- In the server-rendered error page, error.message and error.digest are filled into the HTML before hydration; text derived from them at render time appears once the page hydrates.
Diagnostics: KR9001, KR9002, KR9003
Evidence: TestBuildWritesSegmentPagesAndManifest, TestSegmentPagesServe, TestNestedNotFoundBecomesSegmentPage, TestServerlessNodeParity, TestPlatformDeploysKeepSegmentPages, TestSegmentPageRendersPerRequest, TestSegmentPageRendersPerRequestOnNodeTarget, browser:/r18/boundary_reset_state/, browser:/r18/boundary_fallback_throws/
#Children, keys, and refs
Source: Partial - Islands: Partial - SSR: n/a
Static Children helpers and cloneElement fold at build time. Lists reconcile by key with React semantics: rows keep DOM, input and focus state, component state, effects and refs across reorder, insert and removal (minimal moves), unkeyed lists match by index, items update in place, duplicate keys warn, and a changed key on a single element remounts it. Hydration adopts server-rendered rows by key. Missing, duplicate and partial keys are diagnosed (KR6001-KR6003). Refs in lists attach per item and detach when an item is removed.
Known limits:
- Some dynamic Children helpers and cloneElement calls cannot be folded at build time and use the compat runtime.
- List key inference is conservative for computed keys; rows without a stable key may be adopted by position.
Diagnostics: KR6001, KR6002, KR6003
Evidence: TestEventHandlersUseReactPropNames, TestKeyedListKeyExtraction, browser:/react-keys/
#Events
Source: Supported - Islands: Supported - SSR: n/a
React 17+ root delegation with capture then bubble order, native listener interleaving, stopPropagation, the synthetic event surface, React onChange semantics, focus/blur bubbling, per-element enter/leave, media and composition events. Unknown or lowercase event props are diagnosed (KR5001, KR5002).
Known limits:
- Island event handlers run on Preact's event system, so Krate's source-level event diagnostics do not apply inside a compiled package.
- Controlled pointer/focus state in a compiled package is the package's responsibility; Krate only bridges page signals and callbacks.
Diagnostics: KR5001, KR5002
Evidence: TestEventDelegationBubbles, TestEventHandlersUseReactPropNames, browser:/react-events/, browser:/react-demo/
#Forms and inputs
Source: Supported - Islands: Supported - SSR: n/a
Controlled text, select (single and multiple), checkbox, radio group, textarea, number and range inputs restore to state after onChange; uncontrolled defaultValue/defaultChecked only set defaults; form reset and value={undefined} follow React. Form diagnostics: KR5004 to KR5007. React 19 form actions (action/formAction functions, reset after success) run in the browser gate. No-JS server action posts reach the server and redirect back; the returned state is carried in a short-lived flash cookie that useActionState reads on the next page, but a pre-rendered page is not re-rendered with it without script.
Known limits:
- Controlled controls inside a compiled package use Preact's controlled-input behavior; Krate's form diagnostics apply to source components only.
- Server action forms remain source-level; a compiled package receives the action runtime but not Krate's form lowering.
Diagnostics: KR5004, KR5005, KR5006, KR5007
Evidence: TestFormControlBindings, browser:/react-forms/, browser:/react-events/, TestReactActionFormsCompile, browser:/react-actions/, browser:/react-demo/
#Portals
Source: Supported - Islands: Supported - SSR: n/a
createPortal and Portal mount into document.body or a resolved container after hydration, follow conditional branches, unmount with their component, and bubble React events to the portal's React ancestors. Like React, portal content is not part of the server-rendered HTML.
Evidence: TestPortalRendersAndMounts
#Suspense
Source: Supported - Islands: Supported - SSR: n/a
Boundaries show their fallback while use(promise), a resource or a lazy component inside is pending, reveal siblings together with React's 300ms reveal throttle, and nest independently (innermost wins). Content that cannot resolve at build time ships the fallback and hydrates into the content. A non-transition update that suspends hides the content in place and shows the fallback; a transition keeps the revealed content. lazy() (static import or a loader resolving to a local component) shows the fallback until its separately loaded hydration chunk or loader is ready. Matches React in the browser differential suspense fixtures.
Evidence: TestSuspenseUseRendersFallbackAndTemplatesContent, TestLazyLowersToImportAndMarker, browser:/react-suspense/, fixture:examples/src/pages/react-suspense.tsx
#React 19 actions and forms
Source: Supported - Islands: Partial - SSR: n/a
Source useActionState (queued, previous state over the action transport, permalink no-JS fallback), useFormStatus (form-scoped), useOptimistic (revert on settle), requestFormReset, and function form actions are lowered and run in the browser gate. Compiled packages get the same useActionState/useOptimistic runtime; their useFormStatus is idle. use() and async startTransition are tracked under Suspense and transitions.
Known limits:
- Compiled packages get useActionState and useOptimistic through the compat runtime; useFormStatus is idle inside an island.
- Use() and async transitions in compiled packages follow Preact compat behavior, not the source-component transition lowering.
- React 19 action hooks run in source components; a compiled island gets the compat runtime subset (useFormStatus is idle).
Diagnostics: KR7001
Evidence: TestLowerUseActionState, TestReactBrowserDifferential, TestReactActionFormsCompile, browser:/react-actions/
#React 19.2: useId, useEffectEvent, Activity, ViewTransition
Source: Supported - Islands: n/a - SSR: n/a
useId gives every component instance (children, nested children, lists, repeated components, conditional branches, layouts, rows added at runtime) an id that is the same in the static HTML and the hydration code, so htmlFor and id pairs match. useEffectEvent lowers to a stable function that reads the latest props and state and does not subscribe the effect that calls it.
Diagnostics: KR8031
Evidence: TestReact19Browser
#Custom elements
Source: Supported - Islands: n/a - SSR: n/a
Strings and numbers render as attributes, true as an empty attribute and false is omitted. Objects, arrays and functions render no attribute on the server and are set as properties on the client, also when the element class is defined after the page loads. Components that render such props hydrate so the property is set.
Evidence: TestReact19Browser
#Component tiers: client APIs, conflicts and higher-order components
Source: Supported - Islands: n/a - SSR: n/a
A server, static or runtime component that uses state, effects or event handlers fails the build (KR7110) with the fix, instead of shipping a dead page. Two tier sources that disagree for one component fail (KR7115). A tier decorator on an HOC-wrapped default export classifies the component and the HOC is applied, also when it is declared in another module; an HOC that cannot be inlined fails (KR8030).
Diagnostics: KR7110, KR7115, KR8030
Evidence: TestBuildTimeTierRejectsClientAPIs, TestTierConflictRule
#Server actions
Source: Supported - Islands: n/a - SSR: Supported
File-level "use server" modules compile to hashed POST endpoints with client proxies, bound arguments, no-JS form posts, SSR forms, registry validation, origin checks, body limits, and no-store responses. Enhanced forms return results without reloading; errors use a {message, digest} envelope; actions read headers() and cookies() and can redirect(). Exports built by a wrapper (createAction(...)) are checked when the module loads. Inline "use server" functions in server components are hoisted into generated actions, with the values they close over sealed per request (async components); in a client module they are a coded build error (KR7001).
Evidence: TestPrepareActionsBuildsManifestAndBundle, TestRewriteActionImports, TestActionSidecarTransport, TestActionHandlerSecurity, TestWrapperBuiltActionsRunInSidecar, TestInlineServerActionsE2E, TestInlineServerActionStaticPage, fixture:examples/src/pages/react-actions.tsx, browser:/react-actions/
#Data cache and revalidation
Source: Supported - Islands: n/a - SSR: Supported
@krate/runtime/cache provides revalidatePath, revalidateTag, unstable_cache and unstable_noStore; server fetch honors next.tags/next.revalidate/cache options; pages accept export const revalidate and export const dynamic. Revalidation is applied across the SSR renderer workers, Go region cache, QuickJS and Node API data caches before an action or API route responds; static (SSG) targets are reported as skipped (KR8603).
Known limits:
- Caches are in memory per server process; multiple krate serve instances do not share them.
- Static (SSG) pages cannot be revalidated at runtime; revalidatePath reports them as skipped.
- Tags are recorded for data read during the page render; region renders and Go components do not record tags.
Diagnostics: KR8601, KR8602, KR8603
Evidence: TestRevalidateHostAuth, TestSSRInternalProxyLockdown, TestRevalidateTagAndPathE2E
#Compiled React packages
Source: n/a - Islands: Supported - SSR: Supported
Radix and other compiled packages run as Preact islands with live props, callbacks, portals, controlled primitives, per-island entries bundled with shared modules, server-rendered initial markup, hydration, and an island error boundary. Known Preact limits: an uncontrolled Radix Tooltip closes right after it opens, and a layer opened inside another layer's portal content dismisses the outer layer; both have documented workarounds.
Evidence: TestIslandSignalPropBridge, TestIslandLocalComponent, TestIslandSSREscapesTextProps, browser:/react-demo/
#shadcn-style dashboard
Source: Supported - Islands: n/a - SSR: n/a
Copied shadcn source components, cva/cn folding, cards, controlled filters, and derived lists run in the browser corpus.
Evidence: TestShadcnButtonFoldsVariantsAndSpread, browser:/react-dashboard/
#Next.js app corpus
Source: Supported - Islands: n/a - SSR: n/a
The benchmark Next App Router fixture is the migration-shaped corpus. It is source-corpus coverage today, not a browser-run Krate app.
Evidence: fixture:packages/benchmark/fixtures/next
#Local components in islands
Source: n/a - Islands: Supported - SSR: n/a
Imported local React-compatible modules can be used as tags inside a compiled island and are bundled with it. Same-file Krate functions are diagnosed because they cannot cross the Krate/Preact runtime boundary.
Diagnostics: KR8007
Evidence: TestIslandLocalComponent, browser:/react-demo/
#npm React hook libraries (zustand, react-hook-form, SWR, TanStack Query, ...)
Source: n/a - Islands: Supported - SSR: Supported
A user module that calls a hook of an npm package built on React (or a store hook made by its factory, or a custom hook wrapping one) is bundled for Preact (react resolves to preact/compat, CommonJS require of react is bridged), rendered on the server and hydrated in place. The islands of all pages are bundled together with code splitting, so a store module is one store for the whole site and its state survives client-side navigation, forward and back; a leaving island unmounts and releases its subscriptions. A provider a layout wraps around its children (a query client, a Redux store, a theme) is lifted into the islands, one instance for every island of the page, with nested layouts composing; a provider that cannot be lifted is reported (KR8015, KR8016). Pages rendered per request (SSR, ISR) answer with the islands' build-time markup and hydrate. Checked by hand in Chromium against zustand 5.0.16, TanStack Query 5.105.3, react-redux 9.3.1 with Redux Toolkit 2.14.0 and styled-components 6.6.0 (ThemeProvider), and earlier against valtio 2, jotai 2, react-hook-form 7, SWR 2, TanStack Table 8, react-i18next 15 and usehooks-ts 3; the repository tests use stand-in packages with the same import shapes and behavior.
Known limits:
- A layout, template or server-rendered page cannot call these hooks outside a "use client" module; the build fails with KR8013. Their components (icons, Radix primitives) render in async pages, layouts and components as client boundaries.
- A layout provider whose props read the layout's params, a signal or a state setter, or that renders markup of its own, cannot reach the islands (KR8015, KR8016).
- State inside a component resets when its island unmounts on navigation; module-level state is kept.
- A page that is itself such an island cannot take route props (KR8013) or use Krate-only APIs in the same module.
- An island in a page rendered per request is server-rendered from build-time props; a prop known only per request makes it client-only.
- Only Chromium was run for the browser check.
Diagnostics: KR8013, KR8015, KR8016
Evidence: TestReactHookLibraryPageIsland, TestBrowserReactLibraryIslands, TestLayoutProvidersReachIslands
#Compiled React packages in async pages, layouts and server components (lucide-react, Radix)
Source: n/a - Islands: Supported - SSR: Supported
The components a server module imports from a package built on React are client boundaries: rendered with Preact on the server, plain HTML when they have no state or effects (an icon), a hydrating island otherwise. Parts of a compound component (Radix Dialog.Root with its Trigger and Content) stay in one Preact tree. Async layouts render per request with the page below them, so a layout can read a session and gate its subtree with redirect() or notFound(). Checked in Chromium against lucide-react 1.28 and radix-ui 1.6 (checkbox, dialog).
Known limits:
- Props follow the "use client" rules: serializable values and server actions, no inline functions.
- A synchronous (static) layout cannot host compiled components; make it async (KR8013).
- Server components placed between the parts of a compound component render to HTML, so the parts around one do not share a tree.
- Only Chromium was run for the browser check.
Diagnostics: KR7101, KR8013
Evidence: TestAsyncPageRendersCompiledReactComponents, TestCompiledReactComponentsBrowser, TestAsyncLayouts
#CSS-in-JS (styled-components, emotion, MUI)
Source: n/a - Islands: Partial - SSR: Partial
Components built with styled-components, @emotion/styled, the emotion css prop (with the jsxImportSource pragma) or MUI run as Preact islands and are styled in the browser. They are client-only because the styles are created while rendering, so the server HTML holds an empty placeholder (KR8008 notice). A css prop without emotion's runtime is reported (KR8014). A ThemeProvider in a layout reaches them. Checked by hand in Chromium against styled-components 6, @emotion/styled and @emotion/react 11 and MUI 9.
Known limits:
- No server-rendered markup or styles: content appears when the island mounts.
- A project-wide jsxImportSource for emotion in tsconfig is not supported; use the per-file pragma.
Diagnostics: KR8008, KR8014
Evidence: TestBrowserReactLibraryIslands
#Island hydration control (client:visible, client:idle)
Source: n/a - Islands: Supported - SSR: n/a
client:visible and client:idle on an island's root tag defer mounting until the island is near the viewport or the browser is idle. The server markup stays; the chunk is neither preloaded nor fetched before then, and the directive never reaches the component. client:load is the default.
Diagnostics: KR8012
Evidence: TestBrowserReactLibraryIslands
#Real-React islands (react-reconciler libraries)
Source: n/a - Islands: Supported - SSR: n/a
A user module that imports a package built on react-reconciler (detected from its dependencies) or listed in react.islands runs in a client-rendered island bundled with real react and react-dom, with no Preact alias in its subtree. The server emits a placeholder (client:fallback text). All islands of a page mount from one entry, and the pages of a site share one React chunk that only pages with such an island load. Signal props bridge in as for other islands.
Known limits:
- Client-rendered only: no server markup beyond the fallback text.
- Adds react and react-dom (about 60 KB gzipped) plus the library to the pages that use it.
- Layout providers are not applied; Krate components cannot be passed in as children (same-file ones are diagnosed with KR8007).
- Async pages and layouts host them as client-rendered boundaries (props and children must be serializable); synchronous layouts cannot (KR8013).
Evidence: TestRealReactIsland, TestBrowserRealReactIsland, TestRealReactConfigPackage, TestReconcilerLibraryOnPreactIsland, TestRealReactInAsyncPages
#@krate/three (react-three-fiber API)
Source: Supported - Islands: n/a - SSR: Partial
@krate/three renders three.js scenes from JSX compiled with the page: Canvas (an @renderer component), every three class as an element with args, attach, pierced props and primitives, reactive props that update objects in place, conditionals and keyed lists, pointer events with raycasting, bubbling and capture, useFrame, useThree, useLoader with Suspense, the Krate-style createFrame, createThree, createLoader and createGraph accessors, portals, extend, createRoot and the frame loop exports. @krate/three/drei provides drei's OrbitControls, Environment (Lightformer children or a map) and useGLTF. In a "use client" component of a server-rendered page (a Preact island) the build resolves @krate/three to its island build, the same React-style API rendered by Preact; TestBrowserThreeIsland checks it in Chromium (model, picking, orbit, zoom, pause, error boundary, no React chunk). React-style and Krate-style (createSignal) scenes are checked in Chromium with WebGL by TestBrowserThree; the engine has Vitest coverage in packages/three.
Known limits:
- Only the canvas wrapper is server-rendered; the scene mounts in the browser.
- Other libraries built on @react-three/fiber, and drei beyond OrbitControls, Environment (no HDR files, presets or ground), Lightformer and useGLTF, need the real-React island instead (row react-three-fiber).
- In a Preact island the Krate-style create* primitives are not available (use the hooks), and a mounted subtree that suspends again is unmounted and remounted (preact/compat Suspense) rather than hidden.
Evidence: TestBrowserThree, TestBrowserThreeIsland, TestMigrateReactThreeFiberToKrateThree, fixture:packages/compiler/internal/build/testdata/three, fixture:packages/compiler/internal/build/testdata/three-island
#@react-three/fiber
Source: n/a - Islands: Partial - SSR: n/a
A module using Canvas, useFrame and the other fiber APIs runs as a real-React island (fiber depends on react-reconciler, so it is detected without configuration). Verified by hand: Canvas with a mesh renders a WebGL scene under three 0.170 and @react-three/fiber 9.8.
Known limits:
- The mechanism is tested in CI with a minimal react-reconciler renderer; the library itself was verified by hand in Chromium (@react-three/fiber 9.8, three 0.170, React 19.3) and is not installed in CI.
- WebGL output is client-only; there is no server rendering.
Evidence: TestRealReactIsland, TestBrowserRealReactIsland
#@react-three/drei
Source: n/a - Islands: Partial - SSR: n/a
drei peer-depends on @react-three/fiber, so a module importing it runs as a real-React island with no configuration. Verified by hand: OrbitControls inside a fiber Canvas under @react-three/drei 10.7. krate migrate nextjs moves code that only uses OrbitControls, Environment (Lightformer children or a map), Lightformer and useGLTF to @krate/three/drei (row krate-three), which needs no React.
Known limits:
- The mechanism is tested in CI with a minimal react-reconciler renderer; the library itself was verified by hand in Chromium (@react-three/drei 10.7) and is not installed in CI.
- Only OrbitControls was exercised; other helpers have not been tried.
Evidence: TestRealReactIsland, TestBrowserRealReactIsland, TestMigrateReactThreeKeepsFiberForUnsupportedAPIs
#@krate/konva (react-konva API)
Source: Supported - Islands: n/a - SSR: Partial
@krate/konva renders Konva stages from JSX with react-konva's API: Stage (an @renderer component compiled with the page), every Konva shape (Layer, Group, Rect, Line, Circle, Ellipse, Path, Text, Image, Arrow, Shape with sceneFunc/hitFunc, Transformer and the rest of react-konva's list), props applied in place with react-konva's rules (listening, dash, hitStrokeWidth, shadow*, dragBoundFunc, strict mode), on* event props bound as Konva events, draggable, refs to Konva nodes (Krate variables, useRef objects, callbacks), keyed lists, conditionals and context through the Stage. In a "use client" component of a server-rendered page (a Preact island) the build resolves @krate/konva to its island build, the same API rendered by Preact. TestBrowserKonva drives a react-konva-style editor as a Krate page and as a Preact island, and a Krate-style (createSignal) page, in Chromium: reactive props, click and hover hit-testing, drag with dragBoundFunc, the Transformer (nodes, keepRatio, boundBoxFunc), double-click, keyed reorders, refs, context, and no React chunk. krate migrate nextjs moves react-konva imports to it. The engine has Vitest coverage in packages/konva.
Known limits:
- Only the Stage's container div is server-rendered; the shapes are drawn in the browser.
- KonvaRenderer (the React reconciler) is not provided; a module that uses it, an internal react-konva subpath or a package built on react-konva keeps react-konva in a real-React island (row react-konva).
- In a Krate page a spread prop on a shape is read once.
Evidence: TestBrowserKonva, TestKonvaIslandKind, TestMigrateReactKonvaToKrateKonva, TestMigrateReactKonvaKeepsReactKonvaForUnsupportedAPIs, fixture:packages/compiler/internal/build/testdata/konva
#react-konva
Source: n/a - Islands: Partial - SSR: n/a
react-konva depends on react-reconciler, so a module using Stage, Layer and the shape components runs as a real-React island with no configuration. Verified by hand: a Rect moves when island state changes under react-konva 19.3 and konva 9.3. krate migrate nextjs moves code that only uses the react-konva API @krate/konva provides to @krate/konva (row krate-konva), which needs no React.
Known limits:
- The mechanism is tested in CI with a minimal react-reconciler renderer; the library itself was verified by hand in Chromium (react-konva 19.3, konva 9.3) and is not installed in CI.
- The canvas is client-only; there is no server rendering.
Evidence: TestRealReactIsland, TestBrowserRealReactIsland, TestKonvaIslandKind
#SSR island hydration
Source: n/a - Islands: Supported - SSR: Supported
Islands with build-time-known props are server-rendered with Preact and hydrated in place. The island entries of all pages are bundled together, so modules pages share are shared files. Unknown props, browser-only components, and portals fall back to client-only with a warning. A page rendered per request (SSR, ISR, streaming) answers with the placeholders and build-time markup of its islands instead of running them in the Node renderer; request-time props for an island are not supported.
Diagnostics: KR8008, KR8009
Evidence: TestIslandSignalPropBridge, TestIslandSSREscapesTextProps, browser:/react-demo/, TestBrowserReactLibraryIslands
#Supported Preact versions
Source: n/a - Islands: Supported - SSR: n/a
The island build warns below 10.20. The conformance jobs exercise the minimum, an intermediate version, and the workspace version.
Evidence: ci:preact-conformance
#Browser differential corpus
Source: Supported - Islands: n/a - SSR: n/a
124 source-component fixtures (React 18 corpus plus the React 19 reference app) run in real React 19 and in Krate in Chromium, Firefox, and WebKit; DOM, form state, focus, and effect/lifecycle/ref ordering are compared after every step. Known divergences are tracked with a severity, and KRATE_REACT_EXIT=1 fails while P0/P1 entries remain.
Known limits:
- Four P2 render-count/useId formatting differences remain documented in testdata/reactbrowser/divergences.json.
Evidence: TestReactBrowserDifferential, ci:browser-conformance
#React 19 reference app
Source: Supported - Islands: n/a - SSR: n/a
Fixtures for useActionState, useOptimistic, useFormStatus, form and button actions with auto-reset, use(promise) and use(context), ref as a prop, ref cleanup callbacks, async transitions, useDeferredValue initial values, document metadata, and server actions under the real server.
Evidence: TestReactBrowserDifferential, fixture:packages/compiler/internal/build/testdata/reactbrowser/r19/app_reference.tsx
#Serverless and Node deployment
Source: n/a - Islands: n/a - SSR: Supported
krate deploy bundles the portable server handler (SSR, ISR, streaming, async server components, JS/TS API routes, server actions, middleware, redirects, rewrites, headers) into one self-contained module for --target node, vercel, netlify and cloudflare. Per-segment not-found and error pages and middleware on prerendered pages work on every target. A request matrix gives the same status, security and cache headers, redirects and bodies as krate start; Go API routes, Go components and sidecars are refused at deploy time.
Known limits:
- ISR, region and data caches are per instance on serverless targets; revalidatePath/revalidateTag only reach the instance that handled the request (reported under skipped). Pass an isrStore to createKrateHandler to share the page cache.
- With middleware, Vercel and Netlify send every page request to the function, which serves prerendered HTML from the bundle (bundle size grows with static pages); assets keep going to the CDN. A public file without an extension is treated as a page there.
- Legacy (req, res) API handlers, Go API routes, Go components, the API sidecar and community plugin serve hooks are not supported on serverless targets.
- Cloudflare bundles fail at build time for Node built-ins outside nodejs_compat (fs, vm, net, child_process).
Evidence: TestServerlessNodeParity, TestVercelServerOutput, TestCloudflareServerOutput, TestServerBundleHasNoSecrets, TestPlatformDeploysKeepSegmentPages
#Metadata routes and ImageResponse
Source: Supported - Islands: n/a - SSR: Supported
sitemap.ts, robots.ts and manifest.ts build sitemap.xml, robots.txt and manifest.webmanifest; opengraph-image and twitter-image files (including per-segment and per-generateStaticParams ones) build real PNGs from ImageResponse JSX with a pure Go renderer (flex layout, text and fonts, colours, gradients, images), and feed og:image and twitter:image. Anything the renderer cannot draw is a build error (KR7131). A file wins over a plugin (KR7133). Per-request ImageResponse works in Node API routes under krate start only; Workers and serverless functions have no renderer. krate migrate nextjs maps these files natively. Not supported: CSS grid, transform, filter, SVG, icon and apple-icon files, opengraph-image.alt.txt.
Evidence: TestMetadataRouteFilesBuild
#Code highlighting (build, request time, browser)
Source: Supported - Islands: Supported - SSR: Supported
Code is highlighted by chroma at build time, by the same lexers in the Node renderer for request-time code, and by the same lexers loaded on demand for code that changes in the browser. The lexers are exported from the binary's own chroma and run token for token (the markup is identical), in light and dark from one stylesheet, with a size, line and time limit that leaves text plain instead of stalling.
Known limits:
- Request-time highlighting runs in the Node renderer; serverless deploy targets write plain text.
- The browser and request-time highlighters ship 16 languages; other languages are highlighted at build time only.
- A Markdown fence that names a language outside the shipped set leaves the snippet plain.
Diagnostics: KR7150, KR7151
Evidence: TestParityCorpus, TestTranspiledRegexesMatchRegexp2, TestAdversarialInputs, TestThemeCSSMatchesChromaPerMode, TestSSRCodeHighlightingE2E, ci:code highlighting size budget
#Native: window and custom scheme
Linux: Supported - macOS: Partial - Windows: Supported
The shell opens a window around the system webview (WebKitGTK 4.1 through purego on Linux, WKWebView on macOS, WebView2 on Windows) and serves the built UI from an in-process custom scheme with a content security policy. Navigation away from the app origin is blocked, paths cannot escape the asset directory, and browser mode serves the same app on a loopback port behind a session token.
Known limits:
- Linux GUI tests need a display and WebKitGTK 2.40 or newer (KRATE_NATIVE_GUI=1); CI runs them under Xvfb.
- WebView2 on Windows needs the Evergreen runtime installed; krate native doctor reports it.
- macOS and Windows: the CI native job runs the platform GUI tests on both (macOS TestScenario, Windows TestGUIRoundTrip: page load, request body echo, incremental streaming, secure context), TestGUIShell and TestNativeE2EGUI through a real WKWebView and WebView2. Blocking an in-window navigation to another origin has a real-window test on Windows (TestGUIRoundTrip) but none on macOS, where the navigation delegate is covered only by reading the code.
Evidence: TestGUIPage, TestGUINavigationLock, TestGUIShell, TestStaticResolution, TestStaticRejectsTraversal, TestDefaultCSPShape, TestBrowserMode, TestNativeE2EGUI
#Native: streaming responses
Linux: Supported - macOS: Supported - Windows: Supported
Responses are streamed to the webview as the handler writes them: headers go out first, body chunks are flushed as they come, a handler panic before the first byte becomes a 500, and closing the reader cancels the handler's context. Server-sent streams from host code use the same path.
Known limits:
- macOS and Windows: incremental delivery through a real WKWebView and WebView2 is checked by the platform GUI tests (at least 3 reads spread over 100 ms), and the response writers (macOS task writer: panic before the header, cancel when the task stops; Windows: flush, abort, block buffer) have unit tests that run on both. A reader closed by the page cancelling a real request is driven through a real window on Linux only (TestGUIRequestAbort).
Evidence: TestServeStreamsChunks, TestStreamValuesThenEnd, TestGUIRequestAbort
#Native: host calls, streams and signals
Linux: Supported - macOS: Supported - Windows: Supported
The page calls host functions by id over the scheme: unary calls, server streams and signals (a value with change notifications that reconnects with the current value). Calls are cancellable, errors map to stable codes, concurrency is bounded, and permissions gate which SDK ids a page may reach.
Known limits:
- The scheme package is pure Go and identical on every OS; its tests run on Linux, macOS and Windows in CI, and TestGUIShell sends calls, streams and signals from a real WKWebView and WebView2 to host code.
Evidence: TestInvoke, TestBatchFastResultArrivesBeforeSlow, TestErrorMapping, TestEveryIDIsRegisteredAndGated
#Native: Go host code
Linux: Supported - macOS: Supported - Windows: Supported
Go host code (functions, streams and signals in .go files next to the pages) runs in a child process under krate native dev and krate native build, and is linked into the single executable in a release build. The child restarts after a crash and reconnects subscriptions.
Known limits:
- Needs the Go toolchain on the build machine (krate native doctor reports it).
- macOS and Windows: the child process lifecycle (TestChildLifecycle) runs on both in CI, TestGUIShell replaces the Go host binary and restarts the child in a real window, and TestNativeReleaseE2EGUI runs a release executable with Go host code. TestNativeReleaseE2EBrowser (the browser variant) runs on Linux only. On Windows a running Go host binary cannot be replaced, so a Go edit under krate native dev reports that.
Evidence: TestChildLifecycle, fixture:examples/native-tasks
#Native: TypeScript host code on QuickJS
Linux: Supported - macOS: Supported - Windows: Supported
TypeScript host code (*.host.ts files and @host functions) is bundled to one script and runs in the embedded QuickJS engine with no external runtime. Stack traces map back to the TypeScript sources, a watchdog stops runaway synchronous code, and the globals follow the published runtime compatibility ledger.
Known limits:
- QuickJS is not Node: only the globals in the runtime compatibility ledger exist; code that needs more selects a node, bun or deno host.
- macOS and Windows: the embedded QuickJS engine is pure Go and its tests (calls, streams, the compatibility ledger, runaway recursion) run on both in CI. A TypeScript-only release executable is not run there.
Evidence: TestCalls, fixture:examples/native-tasks
#Native: Node, Bun and Deno host children
Linux: Supported - macOS: Partial - Windows: Partial
TypeScript host code can run as a child process of the shell under Node, Bun or Deno (native.host.runtime, or native.host.islands for single packages). Deno gets permission flags derived from the app's permissions (including its own unix socket, which recent Deno versions treat as network access); a release build compiles the child into an executable (Node SEA, bun build --compile, deno compile).
Known limits:
- Linux: Node children run end to end through the real krate-shell (TestHostChildNode, TestNativeHostChildNodeEndToEnd); Bun and Deno children are covered by the hostchild call tests. Node and Bun release builds are verified; the Deno release command line (deno compile with plain --allow-net for unix targets) is not tested, and the Bun and Node compile tests skip when the tool is missing.
- Deno must be recent enough to take unix:
in --allow-net (verified with 2.9.8); older versions reject the entry, and the dev command line is not adapted to them. - macOS: Node children run in CI (TestHostChildNode, TestNativeHostChildNodeEndToEnd and the hostchild tests on macos-latest) over a Unix socket. Bun and Deno children are not run through the real shell there.
- Windows: Node, Bun and Deno cannot use AF_UNIX there, so the shell uses loopback TCP with a random token. The transport tests (TestTCPHandshake, TestGuardEmptyTokenRejects) and the hostchild tests run on windows-latest, and TestHostChildNode starts a Node child there. Bun and Deno children are not run through the real shell there.
- arm64: Bun and Deno publish no Windows on ARM builds, so the windows-11-arm CI job skips those two (KRATE_SKIP_RUNTIMES) and runs Node only; Linux arm64 and macOS run all three.
Evidence: TestHostChildNode, TestNativeHostChildNodeEndToEnd, TestReleaseBunCompiled, TestReleaseNodeSEA, TestTCPHandshake, TestRunTCPToken, TestRemoteTCPSendsToken
#Native: SDK data areas (kv, db, fs, net, os)
Linux: Supported - macOS: Partial - Windows: Partial
The key-value store, SQLite database, scoped file access, HTTP client with secrets, and OS information, directories, secrets and openExternal are available to the page and to Go and TypeScript host code, each behind its permission. Two processes can share a database and a store.
Known limits:
- Linux secrets use the freedesktop Secret Service over D-Bus (verified against a fake service); without a provider os.secret answers unsupported.
- macOS and Windows: the key-value store, SQLite, scoped files, HTTP client and OS information tests run on both in CI. os.secret (Keychain on macOS, Credential Manager on Windows) and os.openExternal have no test on either: only the Linux Secret Service is exercised.
Evidence: TestTwoProcesses, TestTraversalIsDenied, TestSymlinkEscapeIsDenied, TestSecretNotForwardedAcrossHosts, TestUIDefaultsAndDenials
#Native: SDK windows
Linux: Partial - macOS: Partial - Windows: Partial
Extra windows on routes, title and size, fullscreen, maximize, minimize, frameless windows, close-requested interception and per-window permission scopes bound to the webview, not to anything the page sends. A window can hold several webviews (native-views).
Known limits:
- Per-window permission scopes are enforced against the native webview a request came from (see native-view-identity). In browser mode the page's own x-krate-window header is the identity, so a script there can name another window's scope.
- Wayland: a client cannot place windows or keep them above others, so SetPosition and SetAlwaysOnTop are accepted and ignored there and the capability report says unsupported. The GUI test packages run under weston (GDK_BACKEND=wayland, weston nested on Xvfb) on full CI runs; no test checks the ignored placement. Window position and always-on-top were verified on X11 only.
- Fullscreen, maximize and minimize are verified with openbox on Xvfb (KRATE_NATIVE_WM=1), not on a full desktop environment.
- macOS and Windows: window creation, title and size, two windows and per-window scopes bound to the webview run in CI (platform GUI tests, TestGUIScopedWindowCannotForgeAWiderScope). Fullscreen, maximize, minimize, frameless windows, window position, always-on-top and close-requested interception have no test on either OS.
Evidence: TestWindowOpenScopes, TestWindowScopeNarrowsCalls
#Native: requests are bound to the webview they came from
Linux: Supported - macOS: Supported - Windows: Supported
The platform layer tags every request on the app scheme with the webview that made it (WebKitGTK webkit_uri_scheme_request_get_web_view, the webView of WKURLSchemeHandler, one WebView2 WebResourceRequested handler per view) and the shell maps that view to its window or view id and permission scope. The x-krate-window header that page script can set is ignored in a native window, so a scoped page cannot claim a wider scope. A request from a webview the shell cannot place gets a scope that allows nothing.
Known limits:
- Browser mode (krate native dev --browser) has no native webviews, so the page's x-krate-window header is the identity there and a script can send another window's id; scopes in browser mode only catch mistakes.
- A scope limits what a page may ask the host to do; it does not isolate the page. Every window and view shares one origin, so pages of different scopes can read each other's localStorage and cookies.
- macOS and Windows: TestGUIScopedWindowCannotForgeAWiderScope (shell) and TestNativeE2EViewsGUI run in CI against a real WKWebView and WebView2 and check that requests are tagged with the window or view they came from and that the page header is ignored. On Windows the identity is the handler object registered for the view, not a pointer comparison of the sender.
Evidence: TestIdentify, TestGUIScopedWindowCannotForgeAWiderScope, TestGUIViewIdentity, TestViewScopes
#Native: views and split panes
Linux: Supported - macOS: Supported - Windows: Supported
A window can hold several webviews laid out as a tree of horizontal and vertical splits with draggable dividers, minimum pane sizes and ratios that can be read back after a drag. Views are added, removed, focused, navigated and given their own permission scope; they report added, navigated, removed and closed events and can post messages to each other. All views share the app's one web process; an extra view costs about what a page costs (about 1 MB of web process memory on the WebKitGTK 2.54 sysroot, about 40 MB with software-GL compositing on the CI runner). Layout arithmetic is pure Go and tested on every OS; the real-window view tests and the native-views example run in CI on Linux, macOS and Windows.
Known limits:
- Divider drags on Linux are verified by calling gtk_paned_set_position, which is what the handle does, not by moving a real pointer.
- macOS (nested NSSplitView, Auto Layout minimum sizes) and Windows (several WebView2 controllers in one HWND, dividers hit-tested in the window procedure) run TestNativeE2EViewsGUI in the CI native job. Divider drags on those two are not driven with a real pointer, and the Windows splitter hit-testing and DPI scaling have no tests. The WebView2 NavigationCompleted and WindowCloseRequested handler GUIDs are written from memory of WebView2.h; no platform test asserts the navigated or closed view events on Windows or macOS.
- On macOS a page's window.close() does not remove a secondary view (no closed event for it); Linux and Windows do.
- Release applies to a whole window, not to one view. While a window is released, adding, removing or re-laying out its views fails.
- A divider drag fires no event; read the ratios with layout().
- Messages are JSON up to 1 MiB, not queued for a page that has not loaded, and carry the sender's view id only when the sender is a page.
Evidence: TestNativeE2EViewsGUI, fixture:examples/native-views/src/pages/index.tsx
#Native: print, PDF, find, zoom and capture of a view
Linux: Supported - macOS: Untested - Windows: Untested
Per view (a window's primary view or any added view): the system print dialog, PDF output with page size, margins, orientation and backgrounds, find in page with match counts and stepping, a zoom factor with the Ctrl or Cmd plus, minus and 0 keys kept working, and a PNG capture of the view. WebKitGTK uses GtkPrintOperation, WebKitFindController, the zoom level and webkit_web_view_get_snapshot; WKWebView printOperationWithPrintInfo, findString:withConfiguration:, pageZoom and takeSnapshot; WebView2 ShowPrintUI, PrintToPdf, put_ZoomFactor and CapturePreview.
Known limits:
- The print dialog test on Linux closes the GTK dialog programmatically; macOS and Windows open it only with KRATE_NATIVE_PRINT_DIALOG=1 because a test cannot close a system dialog.
- The PDF page size and orientation are asserted on Linux only. macOS and Windows tests check for a PDF.
- WebKitGTK reports the match count but not the highlighted index (Krate follows it as you step); WKWebView reports only found or not, and WebView2 has no find interface in the WebView2.h Krate builds against, so macOS counts in the visible text and Windows runs window.find and counts the same way.
- WebView2 PrintToPdf takes portrait paper dimensions with an orientation, as GTK does; that reading of the settings is untested on Windows.
- macOS and Windows: untested. The code is written against the platform APIs, builds for both, and the same GUI tests run in CI on macos-latest and windows-latest.
Evidence: TestNativeE2EPageGUI, TestPageNeedsPermission, fixture:examples/native-page/src/pages/index.tsx
#Native: downloads started by the page
Linux: Supported - macOS: Supported - Windows: Supported
Downloads from a link with the download attribute, a blob URL or an attachment response get a destination (the native save dialog by default, or a configured folder with free file names), report started, progress, completed, cancelled and failed events with the final path, and can be cancelled. WebKitGTK uses the download signals, WKWebView WKDownload and WebView2 DownloadStarting. WebKit cannot download the app's custom scheme, so those downloads are fetched from the app handler by the shell and report the same events.
Known limits:
- A download of a page of the app origin is requested once more than the page made it, and the file name comes from the link's download attribute only when the link is in the DOM at the time.
- Downloads need the downloads area to be linked (the app imports @krate/app/downloads); otherwise the engine's default applies, and downloads of the app's own scheme do nothing.
- Windows hands the app origin to WebView2's own download path, which has not been run.
Evidence: TestSchemeDownloadCompletes, TestSafeFileName, TestNativeE2EPageGUI
#Native: cookies and site data
Linux: Supported - macOS: Supported - Windows: Supported
List, get, set and delete cookies by URL, and clear cookies, the cache and storage. WebKitGTK uses WebKitCookieManager and WebKitWebsiteDataManager (cookies persist in the app data directory), WKWebView WKHTTPCookieStore and WKWebsiteDataStore, WebView2 ICoreWebView2CookieManager and ClearBrowsingData.
Known limits:
- WebKit keeps no cookies for the app's custom scheme (document.cookie is inert on krate://app and the jar refuses a single-label host such as app), so on Linux and macOS cookie calls for the app origin answer unsupported; pass the URL of an http(s) site. On Windows the app origin is https://app.localhost and has cookies.
- An older WebView2 runtime without ICoreWebView2Profile2 can only clear cookies.
- Windows on ARM: ClearBrowsingData never finished clearing DOM storage on the windows-11-arm runner's WebView2 and left the webview unusable, so on arm64 the app origin's DOM storage (local storage, IndexedDB, cache storage, service workers, file systems) is cleared through the DevTools protocol (Storage.clearDataForOrigin) instead; storage of other origins in the profile is not cleared there.
Evidence: TestNativeE2EPageGUI
#Native: remote views cannot reach the app
Linux: Supported - macOS: Untested - Windows: Untested
Remote content (web pages) lives in views and windows created as remote (@krate/app/remote). A remote view has its own web context, configuration or profile with no handler for the app scheme and no bridge, so fetches, iframes, images, window.open and navigations to the app fail; the shell gives requests from a remote view the empty scope; navigation is limited to the start origin plus an allowlist, with everything else opened in the system browser or dropped; permissions are denied and downloads cancelled.
Known limits:
- Windows resolves https://app.localhost to the loopback address, so that host is refused as a remote URL, allowed origin and navigation target.
- Subframes follow the allowlist but never open the system browser. On WebKitGTK the policy callback does not tell main frames from frames, so a refused frame navigation of a remote page is reported with the same verdict as a top-level one.
- Opening needs a WebView2 runtime with ICoreWebView2Environment10 (profiles) on Windows.
- macOS and Windows: untested. The same GUI tests (gui_remote_test.go) run in CI on macos-latest and windows-latest.
Evidence: TestGUIRemoteCannotReachApp, TestRemoteDecide, TestRemoteResolveErrors, TestRemoteViewsHaveNoScope, TestRemoteNeedsPermission, TestNativeE2ERemoteGUI
#Native: remote storage partitions
Linux: Supported - macOS: Supported - Windows: Supported
Remote content gets its own storage partition: the default one (persistent, never the app's), named persistent ones (persist:name) and in-memory ones (name). Cookies, local storage, caches, logins and certificate decisions are not shared between partitions or with the app, and a partition can be cleared on its own.
Known limits:
- WebKitGTK in-memory partitions use a temporary directory removed at exit rather than WebKit's ephemeral managers, whose certificate exceptions leak between partitions.
- macOS before 14 has no named persistent data stores: persist:name answers unsupported and the default partition is in-memory.
- Windows clears a profile through an open view of it.
Evidence: TestNativeE2ERemoteGUI
#Native: request rules for remote views
Linux: Supported - macOS: Untested - Windows: Untested
Declarative request rules per partition (block, redirect, add headers, with URL match patterns) and a request stream, with capability reporting. WebKitGTK blocks with a user content filter and rewrites main-frame navigations; WKWebView with a content rule list and navigation decisions; WebView2 with WebResourceRequested on the remote view.
Known limits:
- WebKitGTK and WKWebView cannot redirect or add headers to subresources, and WKWebView does not observe them; capabilities() reports the level per feature.
- Block rules on WebKit follow the content-blocker regular expression subset.
- macOS and Windows: untested. The same GUI tests (gui_remote_test.go) run in CI on macos-latest and windows-latest.
Evidence: TestGUIRemoteInterception, TestNativeE2ERemoteGUI
#Native: remote user agent, proxy, certificates and logins
Linux: Supported - macOS: Untested - Windows: Untested
A user agent per partition or view, a proxy per partition (WebKitGTK, macOS 14), certificate errors that end the load unless the app accepts the host for that partition, HTTP basic and digest logins answered by the app, and client certificates from PEM files (Linux).
Known limits:
- Windows has no per-partition proxy (WebView2 takes --proxy-server for the whole environment) and no client certificates from files; macOS has no client certificates (they need a keychain identity). Those calls answer unsupported.
- macOS reports every certificate error as untrusted.
- macOS and Windows: untested. The same GUI tests (gui_remote_test.go) run in CI on macos-latest and windows-latest.
Evidence: TestGUIRemoteTLS, TestNativeE2ERemoteGUI
#Native: remote message channel
Linux: Supported - macOS: Supported - Windows: Supported
The app and a remote page talk only through an opt-in channel: the page calls krateRemote.postMessage, the app gets the engine-reported origin; the app posts to a target origin and the page receives a message event with the app's origin. Messages carry a per-view token, so a frame that never ran the view's script cannot forge one.
Evidence: TestNativeE2ERemoteGUI
#Native: shared web process, release and background mode
Linux: Supported - macOS: Untested - Windows: Untested
All windows of an app, and all webviews of a window, share one web process (related web views on Linux, one WebView2 environment on Windows). A window can release its webview (hide with release) and get it back on the same route and scroll position; native.window.keepAlive keeps a tray app running with no window; hidden and minimized pages get a krate:memory-pressure event.
Known limits:
- macOS and Windows: the pure-Go parts (view state, park on close, quit when empty) run in CI, and one web process per app is not asserted on either OS. No test releases and restores a webview on macOS or Windows, and none tests keepAlive or the memory-pressure event there; the Linux GUI tests are the only run. On macOS the single-web-process switch is a private WebKit selector guarded by respondsToSelector; on Windows ICoreWebView2_19 memory targets need a recent runtime and are skipped without it.
- A hidden page that is not released keeps its web process memory; only the page's own handlers of krate:memory-pressure and the shell's heap trim run. Release is what returns the web process memory.
- The network process of WebKitGTK stays alive while the app runs, so a released Linux app still holds it.
- Release destroys every webview of a window and restores them all with their routes and layout ratios; there is no per-view release.
Evidence: TestGUIReleaseRestore
#Native: lean pages and the dev Memory panel
Linux: Supported - macOS: Supported - Windows: Supported
Native builds ship no script on a page without client code and do not preload lazy chunks; krate native check and native builds warn (KR7270 to KR7274) about oversized images, large inlined data: URLs, web fonts, compositing CSS effects and long lists without windowing; krate native dev has a Memory panel with PSS, private dirty, DOM nodes and the JS heap where the engine exposes it.
Known limits:
- The checks are static: sizes set from CSS classes, values chosen at run time and data fetched later are not seen. The web font check is a heuristic.
- WebKit has no JS heap size API, so the Memory panel shows the heap as unavailable on Linux and macOS and points at the web process row.
- macOS and Windows: the checks are build-time and platform independent (their tests run on both in CI). Per-process numbers on macOS and Windows come from the memory report of the full CI runs, which is informational (see native-budgets).
Evidence: TestLeanOversizedImage, TestNativeDocsSiteE2E, TestGUIRequestBodyStress
#Native: SDK dialogs, clipboard and menus
Linux: Supported - macOS: Untested - Windows: Untested
Open, save, folder and message dialogs, clipboard text, PNG image and file list, and the menu bar and context menus with click events delivered to Go and to the page.
Known limits:
- A native dialog cannot be clicked headlessly: the tests check that it is created with the right options and answer it programmatically.
- Windows menu accelerators are shown but not active; Windows message boxes do not support custom button labels.
- macOS and Windows: untested. No test creates a native dialog, reads or writes the clipboard or builds a menu there.
Evidence: TestGUIMenus, TestNativeE2EFilesGUI
#Native: rich clipboard formats
Linux: Supported - macOS: Supported - Windows: Supported
clipboard.write puts text, HTML and RTF on the clipboard together; readHtml, readRtf, formats, readFormat and writeFormat read and write by MIME name (UTIs on macOS, registered formats with the CF_HTML header on Windows).
Known limits:
- HTML is stored as given on Linux, without a charset declaration.
Evidence: TestGUIClipboardRich
#Native: webview context menu
Linux: Supported - macOS: Untested - Windows: Untested
native.window.contextMenu and menu.setContextMenu disable, replace (custom: event with kind, link, image, selection, spelling; answered with menu items) or extend the engine's context menu per app, window or view; built-in krate: actions for editing, spelling and Inspect Element.
Known limits:
- Spelling suggestions and Add to Dictionary are not exercised by any test: no spelling dictionary is available to the Linux test environment.
- macOS and Windows: untested; the context menu has a real-window test on Linux only (TestGUIContextMenuCustom). Windows suggestions and Add to Dictionary are best effort.
- Inspect Element from a custom menu opens the inspector without selecting the element on WebKitGTK.
Evidence: TestGUIContextMenuCustom
#Native: debugging in krate native dev
Linux: Supported - macOS: Supported - Windows: Untested
krate native dev --debug-go builds the Go host with -N -l and runs it under a headless Delve; breakpoints in src/lib/*.go hit and a Go edit restarts it on the same address. --debug-host starts node, bun and deno host children with --inspect. --debug-config vscode writes attach configurations.
Known limits:
- Needs dlv installed; the integration tests skip without it unless KRATE_REQUIRE_E2E is set.
- A debugger has to attach again after a Go edit; breakpoints are not carried over.
- Windows: untested (the child-wrapping test skips on the CI runner); the Delve integration tests pass on macOS and Windows in CI.
Evidence: TestNativeDebugGoHostRestart
#Native: SDK notifications
Linux: Supported - macOS: Partial - Windows: Partial
Desktop notifications with actions. On Linux they use org.freedesktop.Notifications over D-Bus; on macOS UNUserNotificationCenter; on Windows, WinRT toasts.
Known limits:
- Verified against a real dunst daemon on a private session bus (text, icon, urgency, replacement by id, close from the app and from the daemon with the NotificationClosed reason, default action and action buttons, expiry, daemon gone) and against a fake service for protocol edge cases. Other daemons (GNOME Shell, KDE Plasma) were not run. Without a service that owns org.freedesktop.Notifications the call returns ErrUnsupported.
- macOS: no CI test sends a notification there; the bundle planning and the UNUserNotificationCenter path are covered by reading the code. That a notification banner appears and that clicking it or its actions reaches the app are manual checks. It needs an app bundle with a bundle identifier; krate native dev runs the shell from a generated
.dev bundle under .krate/dev. The first notification asks for permission and a refusal is a permission_denied error. Icon and Timeout are ignored, and critical urgency is only time-sensitive (the critical level needs an Apple entitlement). - Windows: no CI test shows a toast; the toast activation URI is tested (TestURIRoundTrip). Clicking a toast and seeing the banner are manual checks. An unpackaged app registers its AppUserModelID under HKCU; a packaged app uses its package identity.
- Windows: a toast click uses protocol activation with a per-app URL scheme (HKCU registration for an unpackaged app, NSIS and MSIX registration too), not a COM activator. With the app running, the new process hands the click to it (WM_COPYDATA); with no instance, the click is kept and delivered when the page subscribes (the event that started the app). Unit tests cover the URL, the payload, the registry values and the manifest; the Windows CI job relaunches the test binary with the URL to prove both paths and checks the registration (first run pending), but a real click on a real toast, Action Center after a reboot and the packaged (MSIX) path are not confirmed. Windows has no per-toast timeout or urgency levels, and Show succeeding does not prove a banner was drawn (Focus assist and per-app settings can suppress it).
Evidence: TestRealDunstShowsNotification, TestRealDunstActionButton, TestURIRoundTrip
#Native: camera, microphone, screen capture and location permissions
Linux: Supported - macOS: Supported - Windows: Supported
The page's getUserMedia, getDisplayMedia and geolocation requests go to the SDK instead of the engine's own policy. A request is denied when its window or view scope lacks media or location; otherwise a remembered decision, the request stream (onRequest in TypeScript, media.OnRequest in Go), the native.media policy (allow, deny or a native prompt) and the operating system's consent decide. Decisions are remembered per app (stored) and per view. The UI half is @krate/app/media.
Known limits:
- Linux: verified in a real WebKitGTK 2.54 with the mock capture devices (KRATE_NATIVE_MOCK_CAPTURE): a camera or microphone request reaches the handler with the right kinds and view, allow yields a stream, deny yields NotAllowedError, no handler denies, geolocation deny is PERMISSION_DENIED, and a getDisplayMedia request arrives as kind screen. Real cameras and microphones were not used; no CI runner has one. An allowed geolocation request fails with POSITION_UNAVAILABLE without GeoClue, which the tests accept.
- macOS: implemented as a WKUIDelegate (media capture on macOS 12+, a private method for display capture, geolocation where WebKit calls it) and run in CI on macos-latest. A runner has no camera, so the test calls the delegate methods of the real web view with its own blocks. Notification and clipboard requests have no public delegate.
- Windows: implemented with PermissionRequested under a deferral and ScreenCaptureStarting (ICoreWebView2_27, absent from older runtimes, which leaves screen capture ungated), with SavesInProfile off so the runtime never answers from its profile. Run in CI on windows-latest; the test runs Chromium's fake devices. getUserMedia with audio and video raises two requests there.
- Pointer lock, website data access and the other WebKitGTK request types, and the sensor, download, file and MIDI kinds of WebView2, are left to the engine.
Evidence: TestGUIPermissionNoHandlerDenies, TestScopeWithoutPermissionDenies, TestPromptRemembersAnswers, TestMediaScopeAndPermissionGates, TestNativeE2EMediaGUI, TestGUIPermissionDelegate, TestGUIPermissionCamera
#Native: media permissions derived from the UI, usage descriptions and capabilities
Linux: Supported - macOS: Untested - Windows: Untested
The build scans the built UI for getUserMedia, getDisplayMedia and navigator.geolocation and grants media and location in a derived build (reported as KR7210 against native.permissions), and in dev for an app without a permission list. Packaging writes the macOS usage descriptions and device entitlements and the MSIX device capabilities from what the UI uses, and the build reports KR7290 when a macOS usage description is missing.
Known limits:
- The scan is textual: a call whose API name is built at run time is not found, and a library that mentions getUserMedia asks for the permission. The Info.plist, entitlements and MSIX output are unit-tested as text; no signed macOS app or MSIX package was run.
Evidence: TestScanUses, TestMacEntitlementsForDevices
#Native: operating system consent for camera, microphone, screen and location
Linux: Partial - macOS: Supported - Windows: Supported
An allowed request is checked against the operating system: AVCaptureDevice, CGPreflightScreenCaptureAccess and CLLocationManager on macOS, the capability consent store on Windows (read only), and the Camera portal under Flatpak or Snap on Linux. media.osStatus reads the state and media.osRequest shows the system prompt where one exists. A refusal denies the request.
Known limits:
- Linux: outside a sandbox there is no consent switch for the camera or microphone, and the screen and location go through the ScreenCast portal and GeoClue inside WebKitGTK; only the Camera portal is driven by the SDK, and only against a fake portal in the tests.
- macOS: screen recording reads as granted or not yet granted, and a grant takes effect after a restart. Windows: an unpackaged app cannot be shown a consent prompt, so osRequest only reports the state. Both run in CI on their OS, reading the state; no consent prompt is answered there.
Evidence: TestOSConsent, TestGUIPrivacyAndSources, TestNativeE2EMediaGUI
#Native: screen and window capture sources
Linux: Partial - macOS: Supported - Windows: Supported
media.sources lists capturable screens and windows with PNG thumbnails on macOS (CoreGraphics) and Windows (EnumDisplayMonitors, EnumWindows, GDI). No engine accepts a source chosen by the app, so media.chooseSource returns unsupported everywhere and getDisplayMedia always shows the system picker; the SDK can only allow or deny the capture request.
Known limits:
- Linux has no list (media.sources returns unsupported, so the row is partial): WebKitGTK reaches the screen through the ScreenCast portal and PipeWire, whose picker is the only list. ScreenCaptureKit is not used on macOS. Window titles and thumbnails on macOS need the Screen Recording permission. The listing runs in CI on macOS and Windows.
Evidence: TestMediaSources, TestGUIPrivacyAndSources, TestNativeE2EMediaGUI
#Native: SDK tray and global shortcuts
Linux: Partial - macOS: Partial - Windows: Partial
A tray icon with a menu (StatusNotifierItem and dbusmenu on Linux with a legacy XEmbed tray fallback, NSStatusItem on macOS, Shell_NotifyIconW on Windows) and global keyboard shortcuts (XGrabKey or the portal on Linux, Carbon RegisterEventHotKey on macOS, RegisterHotKey on Windows).
Known limits:
- The tray uses the StatusNotifierItem protocol when a StatusNotifier host exists and falls back to the legacy XEmbed system tray (GtkStatusIcon) when only an XEmbed tray manager owns _NET_SYSTEM_TRAY_S
(X11 only). Stock GNOME with neither returns ErrUnsupported with a hint to install the AppIndicator extension. Verified against stalonetray (XEmbed, with real clicks and menu selection through XTEST) and against the Ayatana application indicator service as a real StatusNotifierWatcher and host; KDE Plasma, GNOME Shell with the extension and other panels were not run. - Linux shortcuts are verified on X11 (XGrabKey, TestGUIGlobalShortcut). On Wayland they need the org.freedesktop.portal.GlobalShortcuts portal, which no test exercises, and return ErrUnsupported without it. No portal backend that implements GlobalShortcuts can run headless here: the GNOME backend needs a running gnome-shell/mutter session, the KDE backend needs KGlobalAccel in a Plasma session, the Hyprland and COSMIC backends are not packaged for Debian or Ubuntu, and xdg-desktop-portal-wlr does not implement the interface.
- macOS: TestTrayItemAndMenu runs in CI on macos-latest (a real NSStatusItem with its menu). Carbon hot keys have no test there. Clicking the real status item and pressing a real hot key are manual checks (platform/darwin/MANUAL_TEST.md). With a tray menu any click opens the menu and is reported as click; right-click and double-click are only reported without a menu. Radio items show a checkmark. Single-tone gray icons become template images.
- macOS shortcuts use Carbon RegisterEventHotKey (no Accessibility permission). Keys are ANSI key positions, so other layouts differ, and macOS 15 ignores hot keys whose only modifiers are Option and/or Shift. A combination that is already registered is an error. Pressing a real hot key and clicking the real status item are manual checks (platform/darwin/MANUAL_TEST.md).
- Windows: on windows-latest TestGUITrayLifecycle adds, modifies and removes a tray icon (it skips when the runner desktop has no taskbar). Hotkey registration and the TaskbarCreated recovery after an explorer restart have no tests. The icon's appearance, its menu behavior, a real explorer.exe restart and real key presses are manual checks. An elevated app is allowed to receive TaskbarCreated with ChangeWindowMessageFilterEx.
- Windows: a shortcut another app or Windows holds fails with an 'already registered by another app' error; many Win+ combinations are reserved by the system. The tray menu has no accelerators and one icon per app.
Evidence: TestGUIGlobalShortcut, TestGUITrayLifecycle, TestTrayItemAndMenu
#Native: SDK app lifecycle
Linux: Supported - macOS: Partial - Windows: Partial
Single instance, deep links and the Linux .desktop entry that registers the app's URL schemes.
Known limits:
- URL scheme registration is a packaging step on macOS (Info.plist) and Windows (registry); the runtime code is shared.
- macOS and Windows: single-instance locking, stale socket replacement and URL extraction from arguments run in CI on both. No test registers a scheme with the OS or opens a deep link there; the Linux .desktop entry has a test only on its own platform.
Evidence: TestSingleInstance
#Native: file associations
Linux: Partial - macOS: Untested - Windows: Untested
native.fileAssociations is validated (extensions, media types, roles, icons) and packaged as macOS CFBundleDocumentTypes with exported UTIs, MSIX file type associations, NSIS ProgID and OpenWithProgids registry entries removed again on uninstall, and a Linux MimeType with a shared-mime-info file in the deb, rpm and AppImage.
Known limits:
- Only the generated files are checked: no package was installed on a desktop, so Launch Services, the Windows registry and update-mime-database never read them. The NSIS script was not compiled with makensis and the MSIX was not installed.
- An installed app is not made the default handler of a type another program owns, and the viewer role has no Windows equivalent.
- macOS and Windows: untested. The same Go code is built for them (cross-compile checks in CI) and the CI native job runs go test on both, but no result of a run against a real WKWebView or WebView2 window has been confirmed.
Evidence: TestInfoPlistDocumentTypes, TestRequireLinksAnAreaTheCodeNeverReaches
#Native: opening files
Linux: Supported - macOS: Supported - Windows: Supported
Files on the command line of the first launch, handed over by a second launch through the single-instance lock, or sent by macOS to the app delegate reach app.onOpenFile and openedFiles (page and Go) with absolute paths, raise the window, and are granted to the fs scope like a dialog pick.
Known limits:
- On Linux a first launch with a file and a second launch handing over another were run through the real shell and a real webview (TestNativeE2EFilesGUI); no desktop environment launched the app from a double click.
- macOS: the delegate method is called by the test, not by Launch Services. Windows and Linux file-manager launches were not tried.
Evidence: TestNativeE2EFilesGUI
#Native: dropped file paths
Linux: Supported - macOS: Supported - Windows: Untested
Files dropped from the desktop onto a view are reported with absolute paths (window.onFileDrop, Go window.OnFileDrop) and granted to the fs scope, while the page keeps its HTML5 drop events: GTK drag signals on Linux, a WKWebView subclass reading the dragging pasteboard on macOS, postMessageWithAdditionalObjects and ICoreWebView2File on Windows.
Known limits:
- Linux: a real drag between two GTK windows with synthesized pointer events (xdotool, needs a window manager) delivers the path and the page's drop event. In that setup WebKitGTK offers no File objects to the page with or without the watcher, so File contents were not checked. Without xdotool the real drag test skips; the signal-level tests use plain GTK widgets.
- macOS: the drop path is checked with a fake NSDraggingInfo and the class registration; a real Finder drag was not tried.
- Windows: the injected script runs against the real WebView2 with a script-made File (which has no path); the COM walk that reads paths is tested with Go fakes of the WebView2.h layouts. A drag from Explorer was not tried and needs a WebView2 Runtime with ICoreWebView2WebMessageReceivedEventArgs2.
- Windows: untested. The synthetic drop test skips on the windows-latest runner, so no drop into a real WebView2 window has been confirmed; macOS runs the drop tests against a real WKWebView in CI.
Evidence: TestGUIFileDropFromARealDrag, TestNativeE2EFilesGUI
#Native: release as a single executable
Linux: Supported - macOS: Supported - Windows: Supported
krate native build --release links the shell, the UI, the host code and only the SDK areas the app uses into one executable per target (CGO_ENABLED=0, stripped, with a report of linked and left-out areas). Cross-compiling to the other OSes is covered; an executable built on its own OS runs in the CI native job on macOS and Windows.
Known limits:
- TestNativeReleaseE2EGUI builds a release executable on macos-latest and windows-latest and drives it in a real window, and the release tests that need no window run there too. Cross-compiling to another OS is checked for the executable format only; such an executable is never launched.
- Needs Go on the build machine; without it (native.release.compile auto) the build falls back to the prebuilt-shell layout.
Evidence: TestNativeReleaseDerivesPermissionsAndReport, TestNativeReleaseE2EGUI
#Native: prebuilt shell for apps without Go
Linux: Supported - macOS: Partial - Windows: Partial
The @krate/core-
Known limits:
- The Linux test uses a stand-in shell executable placed next to a copy of the test krate binary and a PATH with no go command; it proves the layout and packaging, not a launch.
- The packages for all seven platforms are built by scripts/build-platform-packages.mjs and checked by pnpm check:release; the npm install of them (scripts/smoke-install.mjs) runs in the release workflow.
- Alpine (musl): the @krate/core-linux-x64-musl shell is linked with musl's loader (/lib/ld-musl-x86_64.so.1) instead of glibc's, so it starts and
krate-shell --doctorruns; the install smoke test checks this on node:alpine in CI. A window needs WebKitGTK 4.1 from the distribution, which was not run on Alpine. - macOS and Windows: the lookup order, layout and packaging tests run in CI on both with a stand-in shell, and the install smoke test installs the @krate/core-
package on macos-latest and windows-latest and runs its krate-shell --doctor. A dist-native build with the prebuilt shell is not launched there.
Evidence: TestLocateNativeShellOrder, TestNativePrebuiltShellWithoutGo
#Native: krate native doctor
Linux: Supported - macOS: Supported - Windows: Supported
Reports the Go toolchain, the shell binary and its path, the system webview (WebKitGTK 4.1 version and library paths and display on Linux, the OS version on macOS, the WebView2 runtime version on Windows, through krate-shell --doctor), the packaging and signing tools, and the host runtime the config selects. Exits 1 when something the config needs is missing.
Known limits:
- The report logic is tested with injected probes (TestHealthyTypeScriptOnlyLinuxWithoutGo, TestGoRequiredForGoHostAndCompileAlways). The install smoke test runs krate-shell --doctor from the installed platform package on macos-latest and windows-latest. No test checks what the macOS and Windows probes report for a missing or too old webview.
Evidence: TestHealthyTypeScriptOnlyLinuxWithoutGo, TestGoRequiredForGoHostAndCompileAlways
#Native: krate native test and the app driver
Linux: Supported - macOS: Supported - Windows: Supported
krate native test builds the app like native dev, bundles the project's *.native.test.ts files with esbuild and runs them with node --test. The @krate/app/driver module launches the real shell (--dev) per test file with isolated data directories and drives pages over the dev control channel: evaluate, click, fill, press, text, waitFor, url, errors, calls of host functions and SDK ids, several windows and views, and injected tray, menu and shortcut events for app logic behind native events. Input is DOM-level; real operating-system input is out of scope.
Known limits:
- Clicks, typing and key presses are synthesized DOM events (isTrusted is false); native dialogs, the real tray icon, menu bars and notifications cannot be operated, only their events injected.
- page.screenshot() is not available: the platform layer has no webview capture API yet.
- No --browser mode for tests; they drive the native shell.
- The macOS and Windows runs happen only in the CI native job (a desktop session is needed); the per-OS data-directory isolation (HOME on macOS, APPDATA and LOCALAPPDATA on Windows) has not been tried by hand.
Evidence: TestRunNativeTestRunsNodeWithEnvironment, fixture:examples/native-tasks/tests/tasks.native.test.ts, fixture:examples/native-views/tests/views.native.test.ts
#Native: migration guides and the worked Electron port
Linux: Supported - macOS: Supported - Windows: Supported
Migration guides from Electron and from Tauri v2 map concepts, APIs, security, packaging, updates, testing and debugging to Krate Native. examples/native-from-electron is a small Electron app (electron/, pinned, not run by CI) and its port: host functions and a host signal for ipcMain and webContents.send, an application menu, a tray, dialogs, scoped file reads and writes, a notification, a kv settings store and a second window. krate native test drives the port through the real shell.
Known limits:
- The Electron original is a reference and is not built or run in CI.
- Native dialogs and notification banners cannot be clicked headlessly: the test calls the code behind the dialogs and accepts 'sent' or 'unsupported' for the notification and tray (Linux without a notification service or tray host answers unsupported).
- The macOS and Windows runs happen only in the CI native job.
Evidence: fixture:examples/native-from-electron/tests/port.native.test.ts
#Native: plugins
Linux: Supported - macOS: Supported - Windows: Supported
A plugin is a Go package plus a krate-plugin.json (name, Go import path, permissions with descriptions, ops, minimum Krate). native.plugins enables local directories, npm packages and Go modules; ops are callable as plugin/
Known limits:
- The plugin runtime and the build are exercised on all three OSes: TestNativePluginGUI builds a per-app shell and checks a granted call in a real window (the full CI runs add -run Plugin on macos-latest and windows-latest), TestNativePluginAllowlist checks the allowlist, and the shell and plugin package tests check namespaces and the permission gate. The system-info example's own tests run on all three on full runs; its macOS CPU load (ps) and Windows (GetSystemTimes) readings are checked for shape, not for accuracy.
- Plugins are trusted Go code in the shell process; the namespace and permissions limit what a page can reach through them, not what the plugin does.
- Plugin ops are callable from pages; TypeScript host code reaches them only by id (__krateHost.call). A go: plugin needs network or a populated module cache for the first build.
- Editing a local plugin's Go code restarts native dev instead of hot-reloading it.
Evidence: TestInstallEnforcesNamespace, TestInstallRegistersGatedOps, TestSignalGate, TestParseManifestErrors, TestPluginNamedImports, TestNativePluginGUI
#Native: packaging formats
Linux: Partial - macOS: Supported - Windows: Supported
krate native package builds .tar.gz, .deb, .rpm and AppImage on Linux, .app, .zip and .dmg on macOS, and .zip, NSIS installer and MSIX on Windows, from a release executable or the prebuilt-shell layout, with icons, desktop entries and update files. The Windows installer checks for the WebView2 Runtime and, by native.bundle.windows.webview2, downloads or embeds Microsoft's bootstrapper or ships a Fixed Version runtime folder; the app shows a message box with the download link when the runtime is missing.
Known limits:
- On Linux the .deb, .rpm and AppImage of examples/native-tasks are built, and the .deb contents and AppImage were launched and checked to serve the first page (scripts/native-smoke.mjs; the CI native job installs the .deb with dpkg and runs the AppImage). The .rpm is checked for structure and not installed.
- macOS: the CI native job builds the .app, .zip and .dmg of examples/native-tasks, verifies and mounts the .dmg, copies the app out, checks its signature (ad hoc) and launches it (version, first page, window open for 8 seconds). Windows: it builds the .zip, the NSIS installer and the MSIX, runs the NSIS installer silently (registry entry, launch, uninstall) and installs the MSIX with Add-AppxPackage, signed with a test certificate. Dragging the .dmg to Applications, the installer UI and Start menu entries are manual checks; the NSIS installer needs makensis.
- arm64 packages are built for linux/arm64, windows/arm64 and darwin/arm64 (deb and rpm architecture, MSIX ProcessorArchitecture, AppImage ARCH, Windows resources) and checked by unit tests; the CI native job also runs on ubuntu-24.04-arm and windows-11-arm, where the packaging steps run natively. Those two jobs have not run yet, and makensis, the Windows SDK and appimagetool may be missing on the Windows on ARM image (each is skipped with a notice, not failed).
- WebView2: the registry check and the stand-in bootstrapper run are exercised by a full-run CI step (scripts/native-smoke.mjs windows webview2); the message box shown when the runtime is missing has no test. The Fixed Version runtime loader path uses the runtime type value from open reimplementations of the loader and is not confirmed. An MSIX cannot declare the Evergreen runtime as a dependency (it is not a framework package), so an MSIX app relies on the runtime being present (Windows 11, current Edge) and on the message box.
Evidence: TestLinuxTarGzAndDeb, TestMacAppAndZip, TestWindowsZipAndNSIS, TestNativePackageEndToEnd
#Native: signing and notarization
Linux: Partial - macOS: Partial - Windows: Partial
krate native sign and notarize drive codesign and notarytool on macOS, signtool or osslsigncode for Windows, and gpg for Linux packages, and rebuild the archives around the signed payload. CI signs for real with throwaway keys (gpg on Linux, a self-signed identity in a temporary keychain and an ad hoc signature on macOS, a self-signed code-signing certificate on Windows) and verifies with gpg --verify, codesign --verify --deep --strict, signtool verify /pa and Get-AuthenticodeSignature.
Known limits:
- Unit tests replace the signing tools with stand-ins (command lines, ordering and secret redaction). The CI native job also signs for real with throwaway certificates (scripts/native-smoke.mjs): macOS ad hoc and with a self-signed identity in a temporary keychain (codesign --verify --deep --strict), Windows with a self-signed Authenticode certificate (signtool verify /pa), Linux packages with a generated gpg key (gpg --verify, and a tampered copy must fail). Ad hoc signing and the Windows test certificate ran green on macos-latest and windows-latest; the temporary-keychain identity, signtool verify /pa and the gpg step are new and their first CI run is pending.
- Notarization needs an Apple Developer account and stays manual, as do Developer ID identities, certificates from a CA (EV or OV Authenticode), timestamps from a paid authority and hardware or cloud signing services.
Evidence: TestSignMacAppDeepSignsInnerFirst, ci:native-smoke-sign
#Native: macOS universal apps
Linux: Supported - macOS: Untested - Windows: Supported
krate native build --release --arch universal compiles darwin/arm64 and darwin/amd64 and package merges them in pure Go into one .app: the executable and every shared Mach-O file (Go host child, compiled Bun and Deno hosts, Node single executables) become fat binaries with FAT_MAGIC, one fat_arch per slice and 2^14 alignment. The update target is darwin-universal (zip, latest-darwin-universal.json), which the running app learns from a krate-dist.json marker. The Linux and Windows columns mean the merge runs there (a cross build from any OS).
Known limits:
- The fat Mach-O is written by Krate and read back with debug/macho (TestPackageUniversalMacApp). Running both slices (native, and x86_64 under Rosetta) and lipo -info are checked by the universal app packaging step of the full CI runs on macos-latest only.
- A Node host needs a node binary per architecture (KRATE_NODE_DARWIN_ARM64 / KRATE_NODE_DARWIN_AMD64); Bun and Deno cross-compile by themselves. The prebuilt-shell layout holds one platform, so a universal app needs the compiled-executable layout.
Evidence: TestPackageUniversalMacApp, TestDetect
#Native: Flatpak
Linux: Partial - macOS: Planned - Windows: Planned
krate native package --format flatpak writes a flatpak-builder manifest on org.gnome.Platform (WebKitGTK 4.1) with finish-args derived from the app's permissions, a desktop file, AppStream metainfo (validated with appstreamcli when installed), icons named by the app id and a Flathub manifest that builds from a source archive with a sha256. With flatpak-builder installed it builds a .flatpak bundle. Inside the sandbox the shell opens links and sends notifications through the portals, uses the file chooser portal (GTK_USE_PORTAL), names its tray item below its own id and keeps data in the sandbox XDG directories.
Known limits:
- The manifest, metainfo and portal calls are tested without Flatpak (command lines, files, a fake D-Bus). Building the bundle and running the app inside a real sandbox needs flatpak-builder and the GNOME runtime and has not been done; the first CI run of that step is pending. appstreamcli validation of the generated metainfo has not run on any machine yet.
- Flathub prefers apps built from source; a prebuilt-binary submission is reviewed case by case, and screenshots must be added to the metainfo by hand.
Evidence: TestFlatpakFinishArgsFollowPermissions
#Native: Snap
Linux: Partial - macOS: Planned - Windows: Planned
krate native package --format snap writes snap/snapcraft.yaml (core24, gnome extension, libwebkit2gtk-4.1-0 staged, plugs derived from the app's permissions) with the app and icon, and builds the .snap with snapcraft when it is installed. Inside a snap the shell uses the OpenURI and notification portals, GTK_USE_PORTAL and the snap's XDG directories, and has no self-updater.
Known limits:
- The snapcraft.yaml is checked as text; building it with snapcraft and running the snap under strict confinement has not been done. The exact plugs a WebKitGTK app needs under strict confinement (for example for the tray) are unconfirmed.
Evidence: TestDetect
#Native: Mac App Store
Linux: Planned - macOS: Supported - Windows: Planned
krate native package --target mas builds a sandboxed .app: com.apple.security.app-sandbox with network.client, user-selected files, camera, microphone and location entitlements derived from the app, inherit-only entitlements for helper executables, the embedded provisioning profile (checked against TEAMID.appId), codesign with a 3rd Party Mac Developer Application or Apple Distribution identity (ad hoc without one) and a productbuild .pkg signed with the installer identity. native.updater is removed and the running sandboxed app refuses updater calls.
Known limits:
- The entitlements, Info.plist, tool command lines and failure cases are unit tested on any OS. TestNativeMASSandboxGUI signs the example ad hoc with the sandbox entitlement and runs its GUI flows inside the container on macOS; it passes in CI on macos-latest. Uploading to App Store Connect, a real distribution identity and App Store validation have not been tried.
- Access to a file the user picked lasts for that run; security-scoped bookmarks are not used.
Evidence: TestMASEntitlementsFollowPermissions, TestNativeMASSandboxGUI
#Native: Microsoft Store
Linux: Supported - macOS: Supported - Windows: Untested
krate native package --format msix-store builds the Store variant of the MSIX with the Partner Center identity (name, publisher id, publisher display name), no self-updater and a static check of the full-trust rules, plus a .msixupload; --arch universal --target windows/amd64 bundles x64 and arm64 into an .msixbundle (AppxBundleManifest.xml, block map, uncompressed packages) and its .msixupload. The Linux and macOS columns mean the package is built and checked there.
Known limits:
- The bundle manifest offsets are consistent with the zip layout (tested), but neither makeappx nor the Windows App Certification Kit nor Partner Center has opened a package; the Windows column stays untested until a runner does (makeappx unbundle, Add-AppxPackage of a signed copy).
Evidence: TestPackageStoreMSIX
#Native: updater
Linux: Supported - macOS: Supported - Windows: Supported
In-app updates: an Ed25519-signed feed, resumable verified downloads, signed delta updates (pure Go bsdiff patches for the install tree, macOS bundle and AppImage, with fallback to the full file), staged rollouts with halt/critical/min_version, channels, and an apply step that replaces the executable and app directory (Linux, AppImage, macOS bundle, Windows ordering) with rollback on failure and rollback of a version that fails its first start.
Known limits:
- The macOS bundle and Windows apply, delta and rollback steps are file-system logic tested on Linux (the delta and rollback tests run the macOS bundle and Windows wrapper layouts with GOOS overridden); replacing a running Windows executable has not been tried on Windows. scripts/native-smoke.mjs runs, for each OS, a real update 1.0.0 to 1.1.0 of an installed packaged app (TestSmokeUpdateInstalledApp, which must now be a delta), a confirmed healthy start, and a 1.1.0 build whose host exits early being rolled back on its second launch (TestSmokeRollbackState). The full update passed in the CI native job on Linux, macOS and Windows before deltas and rollback were added; the delta and rollback flows have run on Linux only so far.
- First-start protection does not see a crash before the shell's start-up check runs (a loader error, a panic in a package init), and the first update from a version built without it is not protected. An installer-based install (NSIS, MSIX, deb, rpm) does not take delta updates or rollbacks: the updater replaces an install directory, a bundle or an AppImage.
Evidence: TestSignatureGoodBadWrongKey, TestCheck, TestDownloadVerifiesAndProgress, TestApplyLinuxReplacesExecutableAndAppDir, TestApplyRollsBackOnFailure, TestApplyMacBundle, TestSmokeUpdateInstalledApp, TestDeltaUpdateEveryKind, TestPatchRejectsHostilePaths, TestPatchSignatureBindsMeta, TestBsdiffRoundTrip, TestCheckGatesOnRollout, TestRollbackAfterFailedFirstStart, TestWatchdogTimeoutMakesNextLaunchRollBack, TestBootRollsBackAfterUnconfirmedStart, TestSmokeRollbackState
#Native: app icon badge and progress
Linux: Supported - macOS: Supported - Windows: Supported
krate/badge.* sets a badge (count or short text), a progress value (none, normal, indeterminate, error, paused) and an urgent flag on the app icon. Linux emits the Unity LauncherEntry D-Bus signal that GNOME Dash to Dock, KDE and Plank read; macOS uses NSDockTile with a progress bar in the tile; Windows uses ITaskbarList3 progress and an overlay icon the SDK draws.
Known limits:
- Linux launchers show numbers only (other text is refused as unsupported) and no indeterminate state; the signal was verified with a listener on a private D-Bus session, not in a real dock.
- macOS draws error and paused as normal progress.
- macOS and Windows: the same Go code is built for them; TestNativeE2ESystemGUI calls the badge API there and accepts a working call or an unsupported answer, so what the OS shows is not checked.
Evidence: TestNativeE2ESystemGUI
#Native: displays
Linux: Supported - macOS: Supported - Windows: Supported
krate/screen.* lists displays (bounds, work area, scale, primary, refresh rate), finds the display of a window, centers a window on a display and reports display changes. GDK monitors on Linux, NSScreen on macOS, EnumDisplayMonitors and GetDpiForMonitor on Windows.
Known limits:
- Linux was run against Xvfb, which has one monitor; multi-monitor layouts are covered by the pure geometry tests, not a real second monitor.
- Display change events are wired to GDK monitors-changed, NSApplicationDidChangeScreenParametersNotification and WM_DISPLAYCHANGE; no test drives a display change.
Evidence: TestNativeE2EProcsGUI
#Native: power, idle and sleep blockers
Linux: Supported - macOS: Untested - Windows: Supported
krate/power.* reports on-battery, idle time and lock state, delivers suspend, resume, lock, unlock, battery, AC, idle and active events, and holds sleep blockers. Linux uses logind, UPower, Mutter IdleMonitor or the ScreenSaver service, and the GNOME session manager or PowerManagement inhibitors; macOS NSWorkspace, IOKit and IOPMAssertion; Windows WM_POWERBROADCAST, WTS session notifications and SetThreadExecutionState.
Known limits:
- Linux was tested against fake services on private buses, never a real suspend or lock.
- logind's Inhibit returns a file descriptor, which the SDK's D-Bus client cannot receive, so it is not used.
- Battery and idle events come from sampling every three seconds while an event stream is open.
- macOS: untested (only the event tracker is tested there). Windows runs the GUI power test in CI. A real suspend was never tried on any OS.
Evidence: TestNativeE2ESystemGUI
#Native: launch at login
Linux: Supported - macOS: Supported - Windows: Supported
krate/login.get and set register the app to start at login: an XDG autostart entry on Linux, SMAppService with a LaunchAgent fallback on macOS, the HKCU Run key on Windows.
Known limits:
- A packaged (MSIX) Windows app declares a startupTask extension instead; the calls answer unsupported because toggling a StartupTask from code is not implemented.
- macOS: SMAppService needs a signed bundle and was never run; the LaunchAgent fallback writes the plist but does not call launchctl, so it takes effect at the next login.
- macOS and Windows run the temp-HOME and temp-registry-key round trips in CI.
Evidence: TestNativeE2ESystemGUI
#Native: system theme
Linux: Supported - macOS: Supported - Windows: Supported
krate/theme.* reads the system appearance (light or dark, high contrast), reports changes and makes native title bars follow it or a fixed choice: the desktop portal and gtk-application-prefer-dark-theme on Linux, NSApp.appearance on macOS, the Personalize registry key and DWMWA_USE_IMMERSIVE_DARK_MODE on Windows.
Known limits:
- Linux was tested against a fake portal and by reading back the GTK setting; whether a given desktop redraws its title bars is up to the window manager (client-side GTK decorations follow it).
- macOS observes AppleInterfaceThemeChangedNotification, not KVO on effectiveAppearance.
Evidence: TestNativeE2ESystemGUI
#Native: crash reports
Linux: Supported - macOS: Supported - Windows: Supported
A Go panic or fatal error in the shell or the Go host is written to a JSON report under the app's log directory (runtime/debug.SetCrashOutput, collected on the next launch), and a crashed or killed webview process is reported as an event and a report; krate/crash.* lists, reads and deletes reports, and can reload a crashed view automatically (at most three times in 30 seconds). WebKitGTK web-process-terminated, WKWebView webViewWebContentProcessDidTerminate: and WebView2 ProcessFailed.
Known limits:
- A crash of the shell itself is reported on the next launch, not live.
- Nothing is uploaded; the app reads the reports and sends them where it likes.
- WKWebView does not say why its process ended, so macOS reports the reason as crashed.
Evidence: TestRealCrashBecomesAReport, TestIDsCannotEscapeTheDirectory, TestNativeE2ESystemGUI
#Native: size, start-up and memory budgets
Linux: Supported - macOS: Supported - Windows: Supported
packages/native/budgets.json limits the stripped shell, Go-only, TypeScript-only and example release executables (bytes), the cold start of the example in a real window (ms) and its resident memory (KB). Limits are the measured value plus 25 percent. linux-amd64, linux-arm64, darwin-arm64, windows-amd64 and windows-arm64 have entries; a platform with entries is enforced by the same measured-plus-headroom rule, one without only reports and prints a paste-ready BUDGET-RECORD block.
Known limits:
- linux-amd64 was measured on a developer machine; linux-arm64, darwin-arm64, windows-amd64 and windows-arm64 were recorded from one green CI run on the GitHub-hosted runners, so they describe those runners rather than typical user machines.
- CI multiplies every cold-start limit by 3 (KRATE_BUDGET_SCALE): hosted runners vary a lot in start-up time. Memory limits are not scaled; only appMinusFloor private dirty entries fail the job; PSS moves with how shared pages are split and only warns.
- darwin-amd64 (Intel Macs) has no hosted runner in the CI matrix and no entries, so it only reports.
Evidence: TestNativeBudgetSizes, TestNativeBudgetGUI
#Native: custom title bars, drag regions and transparency
Linux: Supported - macOS: Untested - Windows: Untested
native.window.titleBar hidden or none removes the system title bar; the page marks drag regions with data-krate-drag, -webkit-app-region or app-region (read from its style sheets, or by WebView2 itself) and a press starts the native move, a double press maximizes, and frameless windows keep resize edges (GTK draws them in the page, Windows hit-tests them, AppKit keeps its own). The window and webview can be transparent. The request that starts a move names no window: the shell finds it from the webview that sent it.
Known limits:
- Linux: the drag and resize tests press a real pointer with XTEST under openbox on X11; Wayland compositors decide where a dragged window goes and are untested. Transparency needs an RGBA visual and, to show the desktop, a compositing window manager.
- macOS and Windows: untested. The code compiles for them, the hit test, colors and style arithmetic are unit-tested on every OS, and GUI tests that read AppKit and Win32 state back run in the CI native job; nothing here has run on a Mac or a Windows PC by hand.
- Windows draws the caption buttons of a hidden title bar itself, over the extended frame, so the page must leave that corner clear; the WebView2 non-client region support needs a recent runtime and falls back to the page script without it.
- CSS regions are read from style sheets as text: nesting and @import are not followed, and the nearest marked ancestor wins rather than CSS specificity.
Evidence: TestNativeE2EChromeGUI, fixture:examples/native-chrome/src/pages/index.tsx
#Native: Mica, Acrylic, vibrancy, caption overlay and traffic lights
Linux: n/a - macOS: Supported - Windows: Supported
Windows 11 22H2 system backdrops (Mica, Mica Alt, Acrylic) behind a transparent webview, the caption buttons Windows draws over a hidden title bar with Snap Layouts on the maximize button (WM_NCHITTEST returns HTMAXBUTTON) and their colors, and on macOS an NSVisualEffectView with any current material behind a transparent WKWebView and a movable traffic light position. Calls the platform lacks reject with unsupported.
Known limits:
- The WebView2 vtables for ICoreWebView2Controller2 and ICoreWebView2Settings9 are generated from WebView2.h and checked against it.
- Backdrops need Windows 11 22H2 (build 22621); earlier builds reject them. A backdrop shows only where the page is transparent.
- Vibrancy attaches the effect view to the window's frame view, below the content view, which AppKit allows but does not document.
Evidence: TestNativeE2EChromeGUI
#Native: tabs, sheets, document state, share menu, dock, thumbnail buttons and jump lists
Linux: n/a - macOS: Supported - Windows: Supported
macOS: document-edited and represented-file title bar state, windows as sheets, native window tabs with merge, move and new-tab events, the share picker for text, URLs and files, and menu-bar-only apps (activation policy at run time, LSUIElement in Info.plist from native.bundle.macos.agent, dock icon show and hide). Windows: taskbar thumbnail toolbar buttons with click events and jump list tasks that relaunch the app with arguments.
Known limits:
- The macOS tab test skips when the CI session does not merge windows into tabs, and the share picker is validated but not shown in CI.
- Thumbnail buttons need Explorer to create the taskbar button; without a shell session they stay pending. The jump list is committed through ICustomDestinationList and checked by its return codes, not by reading the shell's list back.
- A new-tab event is delivered through the window delegate's newWindowForTab: action, the way AppKit sends it from the tab bar's plus button.
Evidence: TestQuoteArgsRoundTrip, TestNativeE2EChromeGUI
#Native: worker processes
Linux: Supported - macOS: Supported - Windows: Supported
Background worker processes declared in native.workers (a TypeScript module on Node, Bun or Deno, a Go main package, or a prebuilt executable) are started by name from a page or host code, with their own SDK endpoint whose permissions are narrowed per worker, stdout and stderr in the app log, a restart policy with backoff, crash and restart events, and two-way messages over the wire codec (binary, Date, Map, Set). The supervisor and policy are pure Go and tested on every OS; the shell tests run real Node and Go workers.
Known limits:
- macOS and Windows compile and share the portable supervisor and the host child transport (loopback TCP with a token for JavaScript workers on Windows); the worker tests and the procs end-to-end test run in CI on Linux, macOS and Windows.
- A release build ships worker scripts under host/workers next to the executable and needs Node, Bun or Deno on the user's machine for a TypeScript worker; a Go worker is compiled for the build machine's platform only.
- Permissions narrow the SDK ids a worker can call; a worker is still an ordinary process with the user's file and network access.
Evidence: TestCrashRestartsOnFailure, TestNativeE2EProcsGUI, fixture:examples/native-procs/src/workers/echo.ts
#Native: message ports between views, windows and workers
Linux: Supported - macOS: Supported - Windows: Supported
A channel has two ends; whoever creates it can hand each end to a window, view or worker, and messages (JSON, binary, Date, Map, Set) then flow directly between the ends without host code relaying them, in order, with a bounded queue (1024 messages, 16 MiB) and backpressure errors. An end can only be handed to a scope that has port:receive. The page object is a Port in @krate/app/port backed by the shell.
Known limits:
- The engines give two top-level webviews no way to share a real MessagePort, so a port is a shell-backed object, not a transferable MessagePort; inside one page the browser's MessageChannel is untouched.
- The pure broker is tested on every OS; the page-to-page and page-to-worker round trips run in CI on Linux, macOS and Windows.
Evidence: TestPostIsDeliveredInOrderToTheOtherEnd, TestOnlyTheHolderMayUseAnEnd, TestNativeE2EProcsGUI, fixture:examples/native-procs/src/pages/peer.tsx
#Native: offscreen rendering
Linux: Supported - macOS: Supported - Windows: Supported
No system webview streams offscreen frames. The closest equivalent: a window that is never shown (a GtkOffscreenWindow on Linux, a window parked off every display on Windows and macOS) whose page renders normally, plus snapshots (webkit_web_view_get_snapshot, WKWebView takeSnapshot, WebView2 CapturePreview) delivered as PNG or raw premultiplied BGRA, one at a time at a requested rate up to 60 per second, with dropped frames counted instead of queued.
Known limits:
- This is polling, not a paint callback: frames are snapshots, so the rate depends on page complexity and engine; the measured Linux numbers are in docs native/processes.
- Windows and macOS run the capture and parked-window code in the CI native job.
- An open offscreen window counts as a window: close it, or the app does not quit when the last visible window closes.
Evidence: TestNativeE2EProcsGUI
#Native: remote debugging and automation
Linux: Supported - macOS: Supported - Windows: Supported
An endpoint for tests and debugging, on in dev and with native.debug and never in a release build otherwise: WebView2 serves the Chrome DevTools Protocol (Playwright connectOverCDP, Puppeteer connect) and krate can send one CDP method or subscribe to an event in process; WebKitGTK serves the WebKit remote inspector over HTTP (WEBKIT_INSPECTOR_HTTP_SERVER), which is not CDP; WKWebView is inspectable from Safari's Develop menu. CDP answers unsupported where the engine does not speak it.
Known limits:
- Playwright and Puppeteer attach only to WebView2; they cannot drive WebKitGTK or WKWebView. Microsoft documents --remote-debugging-port with Edge WebDriver's DebuggerAddress for WebView2; attaching Playwright through connectOverCDP to the same port is standard Chromium CDP but was not run here.
- The WebView2 CDP command and event code is checked against WebView2.h and compiled; it runs only in the CI native job.
Evidence: TestNativeE2EProcsGUI
#Native: browser extensions
Linux: n/a - macOS: Untested - Windows: Untested
native.extensions packages unpacked extension folders loaded at start and by name: WebView2 through ICoreWebView2Profile7 AddBrowserExtension with AreBrowserExtensionsEnabled, WKWebView through WKWebExtensionController on macOS 15.4 and later. WebKitGTK has no extension API and answers unsupported.
Known limits:
- Linux is unsupported by the engine.
- WebView2 and macOS are written and compiled and never run by the author. On macOS the API's match patterns cover http, https and file pages, so a content script is not expected to run on the app's own krate:// pages.
Evidence: TestNativeE2EProcsGUI
#Native: accessibility of the shell's own UI
Linux: Supported - macOS: Supported - Windows: Supported
The UI the shell draws or configures is checked through each platform's accessibility API: window names in every title bar style, the webview reachable in native, hidden, frameless, transparent, split and remote windows, menus and context menus (roles, names, checked, disabled, accelerators), message and file dialogs, tray, notification, thumbnail button and jump list names, split-pane dividers, and offscreen windows kept out of the tree. Fixes: offscreen windows hidden (Linux AT-SPI, macOS AX), message dialog titles reach the accessible name, split panes and dividers named, tray and notification action and thumbnail button names never empty, Windows message box labels spelled out in the text, macOS alert default button, and drag regions no longer swallow presses on ARIA widgets and focusable elements.
Known limits:
- Linux is checked through AT-SPI on X11 with a private accessibility bus and keys synthesized by at-spi2-registryd (needs the at-spi2-core package and a window manager); Wayland and a real screen reader were not used.
- macOS is checked in process through NSAccessibility (no permission needed); the AX API tests skip unless the test process is trusted for accessibility, which CI runners are not. Runs in the CI native job.
- Windows is checked through UI Automation; runs in the CI native job. The caption buttons of a hidden title bar are reported, not required; the notification area, taskbar thumbnails and jump lists are not read by tests (names come from unit-tested helpers).
- Windows: split-pane dividers are mouse-only, frameless windows have no system menu, offscreen windows stay in the UI Automation tree marked offscreen, and a two-button message box cannot be closed with Esc.
- macOS: an alert is dismissed with Esc only through a button titled Cancel; the split divider is reachable by VoiceOver but not by a plain keyboard.
- No screen reader (Orca, VoiceOver, Narrator, NVDA, JAWS) was used on any platform; web content inside the webview is exposed by the engine and not tested here.
Evidence: TestWindowIsNamedByItsTitle, TestGUIAccessibilityWindowIsNamedInEveryChrome, TestGUIUIAWindowAndWebviewInEveryChrome
#sonner (toasts)
Source: n/a - Islands: Supported - SSR: Supported
A
Known limits:
- A layout that hosts an island is swapped on client-side navigation instead of being kept mounted, so toasts still on screen disappear when the page changes.
- A static layout hosts the Toasters of sonner and react-hot-toast as islands (a fixed list); another library's component in a static layout is compiled by Krate and does not share state with islands. Async layouts have no such limit: their client boundaries are built in the island graph.
- A plain function of a React package called from a module that is not an island (no "use client", not in an event handler) is bundled into the page script with its own copy of the package's state.
Evidence: TestBrowserEcosystemLibraries, TestLayoutToasterSharesStoreWithPageIslands, TestAsyncLayoutToasterSharesStore, fixture:packages/compiler/internal/build/testdata/ecosystem_libs
#cmdk (command menu)
Source: n/a - Islands: Supported - SSR: Supported
Command, Command.Input, Command.List, Command.Item and Command.Empty render, filter as you type and show the empty state (cmdk 1.1.1). Checked in Chromium by TestBrowserEcosystemLibraries against the real package (the test needs KRATE_ECOSYSTEM_LIBS or KRATE_ECOSYSTEM_INSTALL=1 and is skipped otherwise).
Evidence: TestBrowserEcosystemLibraries, fixture:packages/compiler/internal/build/testdata/ecosystem_libs
#embla-carousel-react
Source: n/a - Islands: Supported - SSR: Supported
useEmblaCarousel initializes on mount, reports its snap list and scrolls on api.scrollNext() (embla-carousel-react 8.6.0). Checked in Chromium by TestBrowserEcosystemLibraries against the real package (the test needs KRATE_ECOSYSTEM_LIBS or KRATE_ECOSYSTEM_INSTALL=1 and is skipped otherwise).
Evidence: TestBrowserEcosystemLibraries, fixture:packages/compiler/internal/build/testdata/ecosystem_libs
#@dnd-kit/core and @dnd-kit/sortable
Source: n/a - Islands: Supported - SSR: Supported
DndContext, SortableContext and useSortable with the pointer sensor reorder a list through a real drag (@dnd-kit/core 6.3.1, @dnd-kit/sortable 10.0.0, @dnd-kit/utilities 3.2.2). Checked in Chromium by TestBrowserEcosystemLibraries against the real package (the test needs KRATE_ECOSYSTEM_LIBS or KRATE_ECOSYSTEM_INSTALL=1 and is skipped otherwise).
Evidence: TestBrowserEcosystemLibraries, fixture:packages/compiler/internal/build/testdata/ecosystem_libs
#@tanstack/react-table (v8)
Source: n/a - Islands: Supported - SSR: Supported
useReactTable with the core and sorted row models, column helpers and flexRender render the table on the server and re-sort on a header click (8.21.3). The v9 API (react-table 9) was not checked. Checked in Chromium by TestBrowserEcosystemLibraries against the real package (the test needs KRATE_ECOSYSTEM_LIBS or KRATE_ECOSYSTEM_INSTALL=1 and is skipped otherwise).
Evidence: TestBrowserEcosystemLibraries, fixture:packages/compiler/internal/build/testdata/ecosystem_libs
#next-themes
Source: n/a - Islands: Supported - SSR: Supported
A ThemeProvider in a layout is lifted into the islands of its pages and useTheme in a client component switches the class on and updates the theme state (next-themes 0.4.6). The provider's anti-flash script is part of each island's server markup. Checked in Chromium by TestBrowserEcosystemLibraries against the real package (the test needs KRATE_ECOSYSTEM_LIBS or KRATE_ECOSYSTEM_INSTALL=1 and is skipped otherwise).
Known limits:
- Each island renders its own ThemeProvider (the lifted chain wraps every island) and next-themes keeps its state in the provider, so the theme state is per island: setTheme in one island changes the class on and the stored value but does not re-render useTheme in other islands (checked in Chromium with two islands).
- The server markup renders the theme as undefined until the island hydrates, as it does with React.
Diagnostics: KR8016
Evidence: TestBrowserEcosystemLibraries, TestLayoutProviderWithScriptIsLifted, fixture:packages/compiler/internal/build/testdata/ecosystem_libs
#motion v12+ (motion/react)
Source: n/a - Islands: Supported - SSR: Supported
motion.div with initial/animate/transition, and AnimatePresence with an exit animation, run and unmount their element (motion 14.14.0, imported from motion/react). The older framer-motion package and the vanilla Motion engine config key are separate rows. Checked in Chromium by TestBrowserEcosystemLibraries against the real package (the test needs KRATE_ECOSYSTEM_LIBS or KRATE_ECOSYSTEM_INSTALL=1 and is skipped otherwise).
Known limits:
- Building a page that imports motion/react logs the warning KR7116 (two motion-dom modules export scrapeMotionValuesFromProps); it does not affect the result.
Evidence: TestBrowserEcosystemLibraries, fixture:packages/compiler/internal/build/testdata/ecosystem_libs
#How claims are verified
The compiler and runtime suites pin lowering, diagnostics, and runtime primitives. The browser corpus runs Chromium, Firefox, and WebKit against the same built output, including the React demo, shadcn-style dashboard, forms, islands, styles, and event interactions. The Preact jobs cover the minimum, intermediate, and workspace versions.
Corpus:
- Radix suite and compiled-package islands:
examples/src/pages/react-demo.tsx - shadcn-style dashboard and derived lists:
examples/src/pages/react-dashboard.tsx - Forms and controlled inputs:
examples/src/pages/react-forms.tsx - Class components:
examples/src/pages/react-demo.tsx - Next.js App Router fixture:
packages/benchmark/fixtures/next
A documented limitation is acceptable; a silent one is a bug. Report a divergence with a minimal component and a browser.
Last updated: 2026-11-17
Contributors: Noinkin