Skip to content
sachahjklPublic

About

A small Windows browser where WebAssembly runs everything.

Topics

Resources

Contributing

Accessibility

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

2,940 Commits

Folders and files

Repository files navigation

Wren logo

Wren

CI latest release PolyForm Strict license Windows x64

A small web browser where WebAssembly runs everything, JavaScript included.

Wren is a browser written in Odin where WebAssembly is the only execution engine. Pages can be written two ways, and both run inside the same Wasm sandbox:

  • Ordinary JavaScript. The scripts of a page run in an engine written in Odin, compiled to a WebAssembly module and run by Wasmtime, one instance per page and per worker, with a memory cap and a deadline like any other module. Its DOM and web APIs are bindings generated from the official Web IDL of the specifications (webref). There is no native JavaScript engine in the browser.
  • WebAssembly directly. A page names its modules with <script type="application/wasm" src="…">; the web APIs those modules call (DOM, events, timers, fetch, storage, workers, WebSocket…) are Wasm imports resolved by the browser itself. Every import is described once, in a Web IDL dialect (api/*.widl), and a generator produces the host bindings, the guest SDK, the documentation and the conformance tests from it.

Everything else is a real browser engine: HTML parsed by Lexbor, a CSS engine with the modern cascade, shadow DOM, block, inline, flex, grid and table layout, incremental and parallel, painted by a retained GPU compositor on Direct3D 11, with text shaped by Fontations, HarfRust and ICU4X. The window and its chrome are built with gui_toolkit, an immediate-mode UI toolkit by the same author. The network stack and the image decoders are built in too (Rust, the same on every system); the platform gives Direct3D 11, Media Foundation, WASAPI, UI Automation and BCrypt.

Wren rendering the CSS effects demo: filters, backdrop-filter, mix-blend-mode

Status: beta. Wren is a research project, not a daily browser. It runs the JavaScript of real sites, but through an interpreter, with part of the web platform still missing, and its releases are Windows-only. See Status and limits.

Contents

Screenshots

The start page about:demos
about:home, the start page: an ordinary document, styled by the engine about:demos: every demo and test page that comes with the browser, by theme
A page of plain JavaScript Shadow DOM
JavaScript, inside WebAssembly: a plain HTML and JS page, run by the engine written in Odin, compiled to Wasm (JS in the status bar) Shadow DOM: declarative shadow roots (they render with JavaScript off), slots, :host, ::slotted(), ::part(), custom elements
odin-lang.org in Wren A page whose behaviour is a Wasm module
odin-lang.org, a real site over HTTPS, its scripts running (JS in the status bar) A page written in Wasm: the counter and the clock are an Odin module, no JavaScript at all
CSS transforms CSS Grid
Transforms: rotated text, forms and scroll boxes, nested rounded clips, group opacity, 7,000 animated nodes Grid: areas, auto-fill / minmax, dense packing, alignment, nesting, subgrid
Gradients and shadows Masks, background-clip text, legends, color glyphs
Gradients: linear, radial, conic, repeating, interpolation in sRGB / Oklab / Oklch / Lab / Lch / HSL Paint: mask-image, background-clip: text, fieldset legends, rounded images, COLRv1 / sbix / OT-SVG color glyphs
webassembly.org in Wren sacha.house in Wren
webassembly.org, in its dark color scheme sacha.house: a Tailwind stylesheet, background-clip: text, a fieldset legend, COLRv1 emoji from a web font
Frame statistics panel about:config
Frame statistics (Ctrl+Shift+B): phases per frame, display pacing, compositor, Wasm and memory counters about:config: every setting of the browser, documented, searchable and editable
Tabs in the title bar Text: fallback, emoji, OpenType, scripts
Tabs in the title bar with favicons and loading indicators, next to the window buttons (Snap Layouts kept) Text on DirectWrite: per-character fallback, color emoji, ligatures and OpenType features, bidi
Find in page Selection and its context menu
Find in page (Ctrl+F) with a match count Text selection and context menus
The Daylight palette The developer tools
The Daylight palette of the interface (appearance.theme) Developer tools (F12): document tree and styles, console, requests, storage
The command palette about:wren
The command palette (Ctrl+Shift+P) about:wren: version, licence, signed updates
The content blocker panel
The content blocker's panel: switches and per-site matrix

The demo pages are in examples/site; about:demos lists them all (see Try it). Screenshots show the whole window and are all taken in one pass by wrentool shots (README and site), each the browser's own render of its window. These are of Wren 0.6.25.

Features

Everything below exists in the code today and is covered by the tests of src/tools/test_all.

WebAssembly, the only execution engine

  • A content blocker, built in (docs/blocker.md): advertising, tracking and malware are stopped before the request leaves the machine, in a few microseconds each (a filter engine in Odin for the Adblock Plus / uBlock Origin / AdGuard syntax, compiled to a compact index that loads in milliseconds), the elements ads leave behind are hidden before the first paint, scriptlets defuse anti-blocker scripts, and the interface is native: a shield at the end of the address bar with its panel and �bout:blocker. Lists are downloaded, never shipped; nothing is reported anywhere.
  • Wasmtime 49 (official C API, statically linked; Cranelift, or Winch via wasm.wasmtime.compiler). Any number of modules per document, fetched concurrently, run in document order, each in its own instance sharing the DOM; memory64 modules supported.
  • Compiled code is cached in memory and in an HMAC-authenticated disk cache in the profile.
  • Every host-to-guest call has a wall-clock deadline (epoch interruption, optionally fuel): a spinning module is stopped, its instance lives on. Guest memory is capped.
  • Dedicated workers: a module on a thread of its own with its own store, messages and transferable buffers.

JavaScript, inside WebAssembly (native/js)

  • An engine written in Odin (the toolkit's gt:js, in ext/gui_toolkit/src/js: parser, bytecode interpreter, a JIT for hot code, ES2023 and later; 99.92 % of the test262 tests it runs pass), compiled to a WebAssembly module linked by Odin's own wasm-ld (no C compiler, no C library) and pre-initialized at build time: the interfaces and prototypes of the web platform are already built in the image (5.8 MiB, embedded in wren.exe), so a new realm starts in about 1.3 ms.
  • The same sandbox as any module: one Wasm instance per page and per JavaScript worker, a heap cap (javascript.max_heap_bytes), a script that runs too long is stopped cleanly (javascript.slow_script_ms) and a hard deadline behind it (wasm.max_call_ms); a crash of the engine loses that page's scripts, never the browser.
  • Bindings generated from the specifications: src/tools/bindgen reads the Web IDL of webref (native/js/webref, pinned) and writes the glue with Web IDL's rules (conversions, dictionaries, unions, overloads, [Reflect], iterables, named and indexed properties). 3,821 of 5,310 members are implemented; a member that is not is absent, so feature detection sees the truth. docs/js/coverage.md lists every interface and member.
  • The DOM: tree and mutations, live collections, innerHTML, selectors, CSSOM and getComputedStyle, geometry, UI events, MutationObserver, IntersectionObserver, PerformanceObserver, ranges and traversal, custom elements, shadow DOM.
  • Script loading as HTML specifies it: parser order, defer / async, document.write, dynamic scripts, ES modules and import maps, inline event handlers, javascript: URLs, <noscript>, CSP for scripts (eval, inline), timers, JavaScript workers, structuredClone.
  • Web APIs: fetch / Request / Response / Headers, XMLHttpRequest, streams, Blob / FormData, URL, encoding, AbortController, Web Storage, IndexedDB (pages and dedicated workers, storage buckets), history and location, navigator, performance, crypto with crypto.subtle, matchMedia, WebSocket, EventSource, MessageChannel, service workers and the Cache API, shared workers, Web Animations, ResizeObserver, Canvas 2D, WebCodecs decoders, the WebAssembly JavaScript API, a minimal Intl.
  • WebGL and WebGL 2 (docs/js/webgl.md), in pages and in workers (transferControlToOffscreen too): drawn through wgpu in a GPU process, started by the first context of the browser, with lowered rights, that ends with its parent. A crash or a hang in a driver costs contexts (webglcontextlost, then webglcontextrestored from a new process), never the browser.
  • Compiled scripts are kept in a bytecode cache, in memory and in the profile.
  • On or off, globally or per site: javascript.enabled, javascript.sites.disabled, javascript.sites.enabled. The status bar shows JS on pages that run scripts. Off, pages show their <noscript> content and their Wasm modules still run.

The web API of Wasm pages: one description, everything generated (api/, docs/api)

  • 58 modules, 1,482 functions: DOM, events, document, forms, timers and requestAnimationFrame, fetch (with streams), AbortController, URL, TextEncoder / TextDecoder, crypto (getRandomValues, digests), Web Storage, history, performance, images, EventSource, WebSocket, workers, console, and what the JavaScript engine needs from the browser.
  • src/tools/bindgen turns api/*.widl into: host trampolines defined directly on the Wasmtime linker (every address checked against the guest's memory, UTF-8 validated, handles looked up by kind), the Odin guest SDK (sdk/odin), the reference documentation (docs/api) and generated conformance tests (bad addresses, bad UTF-8, dead handles, enums out of range, buffers too small, for every function).
  • Promises, microtasks and EventTarget for host objects, as the web platform defines them.

HTML, CSS and layout

  • HTML5 parsing with Lexbor, charset sniffing and decoding, quirks mode, the presentational attributes of old HTML (bgcolor, align, <font>, table attributes…), view-source:.
  • Shadow DOM: attachShadow and declarative shadow roots (<template shadowrootmode>, which render without JavaScript), named and manual slots, encapsulated styles with :host, :host-context(), ::slotted(), ::part() and exportparts, :state(), constructable stylesheets and adoptedStyleSheets, event retargeting, delegatesFocus.
  • CSS: cascade layers, custom properties and @property, nesting-era selectors (:is, :where, :has, :not…), media and container queries, Color 4 / 5 (Oklab, Oklch, color-mix…), math functions, @font-face with WOFF and WOFF2, transitions and animations, scroll-driven animations (animation-timeline, scroll(), view(), ScrollTimeline), color-scheme and system colors. Style is computed in parallel on large documents and restyled incrementally (invalidation sets, Bloom filter).
  • Layout: block and inline (bidi, line breaking, text placed vertically as Chromium places it: font metrics, half-leading, vertical-align), floats, positioning (absolute, fixed, sticky), flexbox, grid (with subgrid), tables, multi-column layout, vertical writing modes (docs/multicol-writing-modes.md), replaced elements, scroll containers. Incremental relayout from DOM and style journals (checked against a full pass), paragraphs pre-laid out on several threads on page load.
  • HTML forms: every control, constraint validation, FormData, submission in its three encodings.

Painting and text

  • CSS Text Decoration 3 and 4: every line of every decorating box with its own style, colour and thickness, text-decoration-skip-ink from glyph outlines, text-underline-position, text-decoration-skip-spaces, text-decoration-inset, text-emphasis, -webkit-text-stroke, in rows, columns and right to left. Highlights as CSS Pseudo 4 paints them: ::selection, ::target-text (text fragments), ::spelling-error, ::grammar-error and ::highlight(), each with its own cascade, stacked by overlay and priority. Left out, no browser having them: text-decoration-skip-self, text-decoration-skip-box, the text-decoration-skip shorthand.
  • A retained compositor: the display list is recorded into GPU-side pictures and replayed; scrolling and transform animations change matrices only. Shaders are precompiled: the first frame of the start page is drawn about 0.3 s after launch (1.8 s before).
  • CSS transforms, rounded clips, opacity groups, filter, backdrop-filter, mix-blend-mode, isolation, clip-path, box shadows (exact gaussian, in the shader), gradients of every kind, mask-image and -webkit-mask-*, background-clip: text.
  • Colors blended on sRGB values as browsers do (with Chromium's text contrast settings), gamma-correct where it should.
  • Text on Fontations, HarfRust and ICU4X, the same on every machine (a build with WREN_TEXT=dwrite uses DirectWrite instead): per-character font fallback, OpenType shaping, bidi, synthetic italics, color emoji and color fonts in every format (COLRv1, sbix, CBDT, OT-SVG, rasterized off the UI thread).
  • Images decoded off the UI thread by a built-in Rust library, the same on every system: PNG, JPEG, GIF, BMP, ICO, TIFF, WebP, AVIF and SVG (image, image-webp, rav1d, resvg); HEIF through WIC where its codec is installed; ICC profiles and CICP color management (qcms); srcset, <picture>, lazy loading, inline <svg>.
  • <video> and <audio>: MP4 and WebM (progressive files and fragmented ones): H.264, HEVC and AAC through Media Foundation, AV1 and VP9 in software when the system has no decoder, Opus, Vorbis, FLAC, MP3 and PCM; on the GPU where it can: the picture stays in video memory and is drawn like an image (border-radius, object-fit, filters and transforms apply), the sound goes to WASAPI, the clock follows the audio. Built-in controls, the HTMLMediaElement state machine (events, buffered, seekable, play() and the autoplay policy) and Media Source Extensions (MediaSource, SourceBuffer, URL.createObjectURL) for adaptive streaming. Preferences: media.*.

Network and security

  • HTTP/1.1, HTTP/2, HTTP/3 and WebSockets on a built-in Rust stack (hyper, rustls, quinn, tungstenite; network.backend, WinHTTP stays selectable), asynchronous, with per-host and global queues, back-pressure and cancellation; an HTTP cache in memory and on disk (network.cache.*).
  • A Fetch Standard policy layer: CORS with preflight cache (checked on every redirect), credentials modes, referrer policy, mixed content blocking, Fetch Metadata, bad ports, MIME checks.
  • Cookies (RFC 6265bis: SameSite, prefixes, Public Suffix List) and storage partitioned by top-level site (storage.partitioned), with the Storage Access API, HSTS, Content Security Policy 3 (script-src governs JavaScript and Wasm modules), secure contexts.
  • A file: page may read only its own directory tree (paths are checked again once the file is open: no escape through junctions, links or device names); web pages never read local files.

The browser around the page

  • Tabs in the title bar with favicons, loading indicators, drag to reorder, middle-click to close; history, address bar with search, find in page (Ctrl+F), text selection (word, paragraph, Shift+click), context menus, page zoom, keyboard navigation everywhere in the chrome.
  • Error pages by cause (DNS, refused, timeout, TLS, missing file), downloads (Content-Disposition, types that cannot be shown) straight to a folder you choose, with a toolbar button and about:downloads (Ctrl+J), optional session restore.
  • Local files as in other browsers: the address bar takes Windows paths, files and folders can be dropped on the window, a folder opens its index.html or a sortable list of its files.
  • Frame pacing on the display's exact refresh rate (60 to 180 Hz and beyond), vblank-aligned animation clock, smooth scrolling, one frame in flight; a status bar with a live frame graph and a statistics panel.
  • Everything is configurable: every subsystem declares its preferences (type, bounds, unit, description); they are layered defaults < profile file < command line (--pref name=value) < policy file and edited live in about:config.
  • Draws only when something changes: an idle page costs no frames.

Try it

Download wren-<version>-windows-x64.exe from the latest release and run it: the program is that one file (its licenses are in it, about:licenses; wren.exe --setup installs it). It needs Windows 10 or 11 (x64) with a Direct3D 11 GPU; nothing else to install.

On Linux, download wren-<version>-linux-x64.tar.gz, unpack it and run ./wren; its README.txt lists what it needs from the distribution (glibc 2.39 or later, libopus, libasound, libfontconfig; for a window, libwayland-client and libxkbcommon or libxcb, and a Vulkan or OpenGL driver).

With Nix: nix run git+https://github.com/sachahjkl/wren builds Wren from the sources and runs it, and nix profile add git+https://github.com/sachahjkl/wren installs it with its menu entry (the address is git+https://, not github:: the build needs the submodules, and GitHub's archives, which github: fetches, never hold them). nix develop gives what build.sh needs, and nix flake check builds the package and runs the pre-commit hooks. On NixOS, the downloaded release starts with steam-run, and its Setup makes the installed copy start without it (docs/desktop-integration.md).

The download is the program and nothing else. The demo and test pages (examples\site), the examples and the small test server (tools\testserver, Go) belong to the repository: clone it to get them (wrentool package -Extras also packs them as a zip to extract beside wren.exe).

The start page links to about:demos, the index of every demo and test page. They are in demos\ next to wren.exe (or examples\site in a checkout), and most open straight from disk: demos\index.html is the same index as a page (opening the folder shows it). The few that need a server (network images, forms, CSP, workers, the script loading and web API demos) are marked; run demo.bat (it starts testserver.exe on 127.0.0.1:8765 and opens about:demos), or start them yourself:

testserver.exe                                   # http://127.0.0.1:8765, https://127.0.0.1:8766 (self-signed)
wren.exe http://127.0.0.1:8765/site/effects.html
wren.exe demos                                   # a folder: its index.html, else the list of its files
wren.exe demos\js.html                           # a page of plain JavaScript

The address bar takes Windows paths as well as URLs (C:\pages\a.html, S:/site, \\server\share, ~\Documents), and files or folders dropped on the window open. A folder opens its index.html (file.directory.index), else a list of its files (file.directory.* in about:config); about:about lists the built-in pages.

Useful command-line options: --profile DIR (another profile directory; the default is %APPDATA%\FromentSoftware\Wren, ~/.config/FromentSoftware/Wren on Linux), --pref name=value (any preference of about:config, for example --pref javascript.enabled=false), --policy FILE (without it, policies.txt beside wren.exe is read, never one in the working directory).

Keys: Ctrl+T / Ctrl+W tabs, Ctrl+L address bar, Ctrl+F find, Ctrl+Plus / Minus / 0 zoom, Ctrl+U view source, Ctrl+B status bar, Ctrl+Shift+B frame statistics, F11 full screen. The tabs sit in the title bar (window.system_title = true brings back the Windows one).

Building from source

Requirements (CI installs the same: .github/actions/setup):

Tool Version Used for
Windows 10 or 11, x64 the only platform
Odin dev-2026-11 (dev-2026-11-nightly:9a69916) the browser and its tools
Visual Studio 2022 or later (or its Build Tools) "Desktop development with C++": MSVC x64 and a Windows SDK (CI: the runner's Visual Studio) Odin's linker, Lexbor and the C shims
Rust 1.99.1 (CI's pinned version; any recent stable works), x86_64-pc-windows-msvc the built-in image and font decoders, the network stack, the text backend and the accessibility adapter (native/)
Go ≥ 1.25.6 only the test server (tools/testserver)
Git any submodules, the commit shown in About

NASM is downloaded by the build itself, pinned by SHA-256 (the JavaScript engine is linked by the wasm-ld that ships with Odin).

git clone --recurse-submodules https://github.com/sachahjkl/wren.git
cd wren
build.bat            &:: optimized build -> build\wren.exe
build.bat debug      &:: debug build
build.bat profile    &:: optimized + PDB + the built-in profiler -> build\wren_prof.exe
build.bat check      &:: debug build tracking every allocation, a leak report at exit -> build\wren_check.exe
build.bat release    &:: optimized build of the release channel (what the release workflow packages)

Every build but build.bat release is a development build: a blueprint icon instead of the amber one (exe, window, taskbar, tab strip), and "development build" with the commit on the start page and in the menu.

build.bat only runs wrentool build (src/tools/wrentool/builder; build\wrentool build help lists the variants and the environment variables it reads). What it does, each step skipped when it is already up to date:

  1. wrentool fetch wasmtime downloads the official Wasmtime 49.0.3 C API release (SHA-256 pinned) into build\wasmtime; its static wasmtime.lib is linked into the exe.
  2. wrentool build lexbor compiles Lexbor v3.0.1 (ext/lexbor) and the C shims of src/shim with MSVC into build\lexbor\lexbor.lib.
  3. wrentool build native builds the Cargo workspace native/ with Cargo (--locked, every crate pinned by version and hash), downloads NASM 2.16.03 (SHA-256 pinned) for rav1d's assembly, adds the llvm-tools rustup component on first use, and produces build\native\wren_native.lib, the one Rust library of wren.exe: the image and font decoders (native/media), the network stack (native/net) and the toolkit's text backend and accessibility adapter (about 1 minute the first time; build.bat release and profile link it with fat LTO, 2 minutes; see docs/architecture.md, "The Rust library").
  4. src/tools/bindgen regenerates the web API bindings, SDK and docs from api/*.widl, and the JavaScript bindings and their coverage from the Web IDL of native/js/webref (only what changed).
  5. src\tools\buildjs compiles the engine and the browser's bindings (Odin) to one wasm32 object, links it with Odin's wasm-ld and pre-initializes it into build\js\wren_js.wasm.
  6. odin build src/tools/wrencom builds build\wren.com, the console launcher that makes wren ctl ... behave in a terminal (docs/console-launcher.md); wren.exe embeds it.
  7. odin build src/browser links everything into one self-contained build\wren.exe, the JavaScript engine included (no DLL beyond the system's and the Visual C++ runtime that Windows ships).

Run it with build\wren.exe [URL]. For the demo pages that need a server, build and start the test server first:

cd tools\testserver && go build -o ..\..\build\testserver.exe ./cmd/testserver && cd ..\..
build\testserver.exe

Tests

odin build src/tools/test_all -collection:wb=src -collection:toolkit=ext/gui_toolkit/src -out:build/test_all.exe
build\test_all.exe -Quick   # every suite but the long network stress
build\test_all.exe          # everything
build\test_all.exe -CI      # what continuous integration runs (see below)

The suite runs the unit tests of every package (odin test src/<package> -vet), checks that the generated web API and JavaScript bindings are up to date (bindgen -check), runs the generated API conformance cases, the graphics toolkit's pixel tests on an offscreen WARP renderer, and end-to-end tests that drive real pages, Wasm guests and scripts against the local test server (network policy, DOM and events, web platform APIs, forms, workers, EventSource and WebSocket, style animations, images and image formats, local files, the JavaScript engine, its DOM, script loading and web APIs). None of them needs the internet, and with -Quick none opens a window.

Memory. Every unit test fails on a leak or a bad free (Odin's test runner, ODIN_TEST_FAIL_ON_BAD_MEMORY). The end-to-end tools are built with -define:WREN_TRACK_MEMORY=true: every allocation of the process, whatever the thread (the Wasm host calls and the network callbacks included), goes through one tracker (src/base/memory.odin), and a tool fails when anything is still allocated once it has shut down (src/testenv/memory.odin). Code without an Odin context of its own starts from base.process_context(); what is kept for the life of the process on purpose comes from base.permanent_allocator() and is never reported. build.bat check builds the browser the same way, with a script driver (WREN_MEMCHECK_SCRIPT, src/browser/memcheck.odin) that runs whole sessions without the desktop's input: src\tools\e2e\memcheck.odin (tabs, scripts, images, forms, the back/forward cache, the palette, history, then a normal exit with nothing left) and src/tools/endurance (400 tabs and 2,000 navigations: the tracked bytes, the private bytes and the kernel, GDI and USER handles must stop growing). src/tools/test_all/asan.odin builds the unit tests and the browser with AddressSanitizer. -CI and full runs include the check build's session and a short endurance run. The check build and the end-to-end tools also poison what is freed and keep it out of the heap, arenas and the C heap included: a read of it ends the run with a crash report (docs/testing.md).

Two standard conformance suites run too, pinned by commit and checked against committed expectations, so that any regression fails the run:

  • test262, the ECMAScript suite (src/tools/test262): the engine compiled to Wasm passes 99.92 % of 82,220 runs (what fails: Atomics.pause and growable SharedArrayBuffer, without threads in WASI). test_all runs a sample of it.
  • web-platform-tests (src/tools/wpt, wpt/suites.txt): the tests of 48 folders (DOM, HTML, URL, encoding, Fetch, XHR, streams, storage, workers, shadow DOM, custom elements…), of which more than 130,000 subtests pass (wpt/expectations, docs/conformance.md).

-CI is -Quick for shared build machines: end-to-end timeouts are tripled and a failed step's whole output is shown, one step at a time on the default ports. Locally, steps run several at a time (-Jobs n) and the test server listens on ports of the run (-BasePort n), so several checkouts can test at once. No step is ever run twice: tests check properties, never wall-clock durations. GitHub Actions runs it on windows-2025 for every push and pull request.

Writing a page for Wren

In JavaScript, as for any browser: Wren runs the page's scripts, inline or external, classic or modules. examples/site/js.html and js-dom.html are small examples. What is implemented is listed in docs/js/coverage.md; what is not is absent, so if ("ResizeObserver" in window) takes the fallback.

In WebAssembly, without JavaScript: a page module is any Wasm module that imports the functions of docs/api and exports wb_main. The Odin SDK is sdk/odin, the wren collection: one generated package per area of the API (wren:dom, wren:fetch, wren:canvas...; wren:core holds the errors, host objects, promises and events every other one uses). A page:

<!doctype html>
<title>Counter</title>
<script type="application/wasm" src="counter.wasm"></script>
<p>Value: <b id="count">0</b> <button id="inc">+1</button></p>

and its module (examples/counter is the full version):

package counter

import "wren:console"
import "wren:core"
import "wren:dom"

count: i64
count_node: dom.Element

on_click :: proc "contextless" (user: i32, ev: core.Event) {
	count += i64(user)
	buf: [24]u8
	n := len(buf)
	for v := count; ; v /= 10 { n -= 1; buf[n] = u8('0' + v % 10); if v < 10 { break } }
	dom.Node_setTextContent(count_node, string(buf[n:]))
}

@(export)
wb_main :: proc "contextless" () {
	count_node = dom.Document_getElementById("count")
	core.EventTarget_addEventListener(dom.Document_getElementById("inc"), "click", on_click, 1)
	console.log("counter ready")
}
odin build examples/counter -target:freestanding_wasm32 -no-entry-point -default-to-nil-allocator ^
    -collection:wren=sdk/odin -out:examples/site/counter.wasm -o:size

Conventions (the full ABI is in docs/api/README.md): handles are i64, strings are UTF-8 (pointer, length), strings returned by the browser go into a caller buffer and the result is the length needed, callbacks are function-table indices with a user value, errors are negative i32. Any language that compiles to Wasm can implement them; only the Odin SDK is generated today. A new API starts as a few lines in api/<module>.widl: build.bat regenerates the trampoline and tells you, through a compile error, which host procedure to write.

A page may use both: its Wasm modules and its scripts share the same DOM.

Project layout

api/            the web API, described once (*.widl): source of the bindings, SDK, docs and conformance tests
assets/         logo and icon
docs/api/       generated API reference (with the ABI)        docs/architecture.md: design rules and security model
docs/js/        generated coverage of the JavaScript bindings
examples/       Wasm guest pages (counter, forms, workers, conformance...), JavaScript test pages, site/: the demo pages
ext/            submodules: gui_toolkit (window, UI, renderer, text), lexbor (HTML, URLs, encodings)
native/js/      the JavaScript engine module: the engine layer, hand-written members, preludes,
                generated bindings, the Web IDL of webref
native/         Cargo workspace of the one Rust static library of wren.exe (native/wren_native, the assembly crate,
                picks native/media, native/net and the toolkit's native/text and native/a11y)
native/media/   raster images (image), SVG (resvg), WebP (image-webp), AVIF (rav1d), color (qcms), WOFF2 (brotli)
native/net/     the network stack: HTTP/1.1, HTTP/2, HTTP/3, WebSockets, TLS
sdk/odin/       generated Odin guest SDK (the `wren` collection: a package per area of the API)
src/
  base/         scopes (ownership tree with cleanups) and generational handle pools
  host/         event loop, thread-safe posts, timers, blocking-work pool
  net/          transport: HTTP(S) and WebSocket on native/net, or WinHTTP; no policy
  url/ http/    WHATWG URLs, origins, Public Suffix List; headers and MIME types
  cookies/ csp/ the cookie jar (RFC 6265bis) and Content Security Policy 3
  fetch/        the policy layer (Fetch Standard): CORS, credentials, redirects, HSTS, referrer, mixed content, file:
  html/ dom/    HTML parsing (Lexbor), charsets; the document tree, shadow trees, events and the mutation journal
  css/ style/   tokenizer, parser, selectors, values; the style engine (cascade, layers, shadow scopes, animations)
  layout/       box tree, block / inline / flex / grid / table layout, incremental and parallel passes, display list
  images/ webfont/  image decoding threads (native/media; WIC for HEIF); web font unpacking (WOFF, WOFF2)
  media/        MP4 / WebM parsers, track stores, Media Foundation decoders, WASAPI output, the player (audio clock)
  forms/        HTML form controls as a model: values, validation, editing, submission
  wasm/         the Wasm engine (Wasmtime): instances, linker, deadlines, limits, caches, WASI, pre-initialization
  js/           JavaScript preferences, the bytecode cache, the embedded engine image
  page/         one document = DOM + Wasm instances + JavaScript realm + requests + timers; the imports' implementations
  config/       the preference registry behind about:config
  browser/      the shell: window, tabs, chrome, painter and compositor, pacing, status bar, about: pages
  shim/         C shims over Lexbor
  tools/        bindgen, end-to-end test drivers, test262 and WPT runners, benchmarks
tools/          build, test, screenshot and measurement scripts; testserver/ (Go)
wpt/            the web-platform-tests Wren runs: folders, manifest, expectations

docs/architecture.md explains the rules that hold it together (one ownership tree, handles across every boundary, a single UI thread, mechanism separate from policy, a bound on everything) and the security model.

Status and limits

Wren is a beta. It is meant to show how far a browser with a single, sandboxed execution engine can go, not to replace one. Known limits:

  • JavaScript is mostly interpreted (a bytecode interpreter in Wasm, with a JIT for hot loops and hot functions without loops of their own: numbers, properties, calls, objects and strings made, DOM attributes read; a function with loops is compiled loop by loop): far slower than Edge on script-heavy benchmarks, and a DOM call crosses the Wasm boundary. Pages that run a lot of script are slow.
  • Each document has its own heap. The DOM of a same-origin frame and its globals are reachable (contentDocument, parent.foo()), through handles and a bridge of proxies, not one heap: a native function refuses another realm's typed array or Blob, built-ins read from another window are the caller's, and a node moved between documents loses its shadow tree and a form control's typed value (details).
  • Part of the web platform is missing: about 72 % of the members of the specifications' Web IDL are implemented (docs/js/coverage.md). Among what pages notice: no WebGPU or WebRTC, no video or audio encoder in WebCodecs; Canvas 2D is software-drawn; Intl follows English conventions whatever the locale. Applications that rely on these show little or nothing.
  • Linux is newer than Windows: releases for Linux x86-64 need glibc 2.39 or later (Ubuntu 24.04, Debian 13, Fedora 40); what is checked and what is not is in docs/portability.md.
  • No HTTP authentication; CSP violations are reported to the console only.
  • No IME composition; no captureStream, Encrypted Media Extensions (DRM), Ogg, MP3 or WAV files in <audio>.
  • The Wasm GC proposal is off by default. A page has WebAssembly threads and SharedArrayBuffer under cross-origin isolation (docs/shared-memory.md).
  • Response bodies are bounded (max_body and a per-page ceiling).

Releases

Binaries are built by GitHub Actions from a version tag and attached to the releases with their SHA-256 sums; CHANGELOG.md sums up each version. To make one (see CONTRIBUTING.md):

build\wrentool changelog -Assemble -Version X.Y.Z
git commit -am "Wren X.Y.Z" && git push
git tag -a vX.Y.Z -m "Wren X.Y.Z"
git push origin vX.Y.Z

(wrentool changelog -Assemble turns the fragments of changelog.d/ into the version's section and writes APP_VERSION.)

License and credits

Wren's source is public, under the PolyForm Strict License 1.0.0: you may read it and use the program for noncommercial purposes (personal use, charities, schools, public bodies, research); you may not redistribute it, sell it, or make changes or new works from it, and commercial use needs the author's agreement (contact@froment.software). The libraries below keep their own licenses. Wren stands on:

  • Odin by Ginger Bill and contributors;

  • gui_toolkit (MIT), whose design follows the UI layers of the RAD Debugger (MIT, Epic Games Tools);

  • Wasmtime (Apache-2.0 with LLVM exception, Bytecode Alliance);

  • QuickJS-ng (MIT), after Fabrice Bellard's QuickJS: the engine in Odin ports its number conversion and Unicode code and follows its bytecode format;

  • emmalloc (MIT / NCSA, Emscripten), through Odin's base:runtime, the heap of the JavaScript module; FreeBSD's e_exp.c (fdlibm, Sun's permissive notice), the exp of the engine;

  • webref (MIT), the Web IDL of the specifications, from which the JavaScript bindings are generated;

  • Lexbor (Apache-2.0);

  • resvg, image-webp, rav1d (BSD-2-Clause), zenavif-parse (MPL-2.0), qcms (MIT), brotli-decompressor and the crates they depend on;

  • hyper, rustls, quinn and tungstenite, the network stack; Fontations, HarfRust and ICU4X, fonts, shaping and line breaks; AccessKit, the accessibility tree;

  • NASM (build time only), the Public Suffix List (MPL-2.0);

  • the test suites test262 and web-platform-tests (BSD-3-Clause; fetched at a pinned commit for the tests, not shipped).

  • Slug by Eric Lengyel (MIT; the patent is in the public domain): the shaders and the algorithm of the optional text.renderer = slug (glyphs drawn from their outlines on the GPU), through gui_toolkit.

  • Noto Color Emoji (COLR v1, Google; SIL OFL 1.1), the built-in emoji font (unless appearance.text.emoji_font names another), compiled into wren.exe; and Unicode's emoji-data.txt (Unicode License v3), which tells emoji characters from the others. Fonts used by the demo pages and tests come with their licenses next to them (examples/site/fonts, native/media/tests/fonts). THIRD_PARTY.md lists every component linked into wren.exe.

About

A small Windows browser where WebAssembly runs everything.

Topics

Resources

Contributing

Accessibility

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages