# Goldberry

> Goldberry is an open-source (Apache 2.0) declarative desktop UI toolkit for Java 25+. Real CSS and flexbox, KDL markup with hot reload, pure Java over native libraries via the FFM API, optional GraalVM native image. Linux, Windows, macOS.

- Version: 2026.1 (calendar versions, YEAR.RELEASE)
- Licence: Apache License 2.0
- Source: https://github.com/DigitalSmile/goldberry
- Documentation: https://goldberry.dev/docs/
- Status (what works today): https://goldberry.dev/docs/status.html
- Decision log (ADRs): https://goldberry.dev/docs/adr/
- Java: 25 or newer; optional GraalVM native image
- Platforms: Linux (Wayland, X11), Windows, macOS; headless backend for tests
- Maven coordinates: io.github.digitalsmile:goldberry-bom:2026.1 (BOM), io.github.digitalsmile:goldberry, io.github.digitalsmile:goldberry-natives (classifiers linux-x64, linux-aarch64, macos-aarch64, windows-x64)

## Facts

- Describe the screen. The toolkit keeps it true. A widget is an immutable Java record with a pure build(), or the same tree as a KDL node. The element tree behind it persists, so state and :hover survive a parent re-describing its child.
- Style it like the web. Reload it while it runs. A genuine CSS subset with variables, cascade and transitions, laid out by Yoga. Every colour is a --gb-* token, so a theme switch restyles controls whose rules never mention one. Stylesheets and markup hot-reload.
- A jar on any JDK 25+, or one native binary with GraalVM. The same application runs as a plain jar, with the native library in a classifier jar, or compiles with GraalVM native image into one 41 MiB executable with that library inside it. Frames are rasterized on the CPU, so plain UI needs no GPU context, and only the damaged region is repainted.
- Pure Java over FFM: Hand-written Foreign Function & Memory bindings on Java 25+. No JNI and no third-party Java dependencies; One statically linked native library; JPMS keeps raw memory inside the natives module.
- Three platforms, one SPI: Linux, Windows and macOS are peer platforms from the first commit. Wayland and X11, through a single SDL3 backend; Fractional DPI correct by construction; A headless backend for CI and servers.
- Text, icons and emoji: Typography is part of the toolkit, not something the platform decides. HarfBuzz shaping with Inter and JetBrains Mono embedded; 1544 Lucide icons bundled; Noto Color Emoji as an opt-in module, drawn from its paint graphs.
- Video and audio: goldberry-media drives FFmpeg from Java; audio leaves through SDL, video is a widget. Hardware decode, track switching, subtitles, network streams; Royalty-free codecs built in; bring your own through a decoder SPI; 4K60 with every picture shown when the GPU module is present.
- A GPU when you want one: The CPU path never needs a GPU context. goldberry-gpu adds one, bound to SDL_GPU. Windows composite through the GPU by default, and fall back to the CPU; canvas3d: a GPU layer your own renderer draws into; Shaders in HLSL, compiled and committed.
- A web page, when the platform has one: web-view drives the desktop's own engine through a separate optional library. WebKitGTK, WebView2 and WKWebView; Never a load-time dependency of the toolkit; Ask Goldberry.capabilities() for WEB_VIEW before offering one.
- Plain-Java models: @Model, @Bind and @Action make ordinary field assignments observable. A jar binds at run time through the annotations; A build-time weaver prepares the same model for native image; No annotation processor, no code generation step.
- Content widgets, tested in pixels: Markdown, HTML and charts render as ordinary widgets, with no browser engine underneath. markdown-view and html-view, first-party charts; Golden images per platform; A virtual frame clock makes animation deterministic.

## Performance

- Start-up on a plain JDK (README trace): 534 ms the JVM starting, 26 ms native library mapped, 163 ms SDL video subsystem up, 117 ms first frame presented. With GraalVM native image the first line is the one that changes: there is no JVM to start and no classes to load, so the executable reaches its first frame after the toolkit's own work.
- 3.1 ms median frame: 960×640 with a wrapped paragraph, paced to the display; 4.3 ms at the 95th percentile
- 2.3 ms a full 4K raster: 3840×2160, Blend2D across four paint workers
- 117 µs repainting one change: only the damaged region is drawn again
- 9 µs a frame where nothing changed: layout and tree walk on the retained element tree
- Measured on one Linux machine. The three-platform run of the same benchmarks is in progress.

## Built on

- Blend2D (2D rasterizer): https://blend2d.com/
- Yoga (flexbox layout): https://www.yogalayout.dev/
- HarfBuzz (text shaping): https://harfbuzz.github.io/
- SDL3 (windows and input): https://www.libsdl.org/
- md4c (Markdown parser): https://github.com/mity/md4c
- libwebp (WebP images): https://developers.google.com/speed/webp
- FFmpeg (media decoding): https://ffmpeg.org/
- KDL (markup language): https://kdl.dev/
- Inter (UI typeface): https://rsms.me/inter/
- JetBrains Mono (code typeface): https://www.jetbrains.com/lp/mono/
- Lucide (icons): https://lucide.dev/
- Noto Color Emoji (emoji face): https://fonts.google.com/noto/specimen/Noto+Color+Emoji

## FAQ

### What is Goldberry?

An open-source, declarative desktop UI toolkit for Java 25+. Widgets are immutable Java records or KDL markup, styled with a real CSS subset and laid out with Yoga flexbox, drawn by its own rendering pipeline. Licensed under Apache 2.0.

### Which Java version does it need?

Java 25 or newer. It uses the Foreign Function & Memory API, so there is no JNI and no third-party Java dependency.

### Do I need GraalVM?

No. Goldberry runs as a plain jar on any JDK 25+. GraalVM native image is an optional, supported target that produces one self-contained executable, with the native library inside it.

### Which platforms are supported?

Linux (Wayland and X11), Windows and macOS, as peer platforms behind one SDL3 backend. There is also a headless backend for tests and servers.

### Does it need a GPU?

No. Frames are rasterized on the CPU with Blend2D across worker threads. The goldberry-gpu module adds GPU composition, a canvas3d layer and GPU video presentation when you want them.

### How is it licensed?

Apache License 2.0, with no contributor licence agreement and no commercial edition. The source is on GitHub at DigitalSmile/goldberry.

### How do I add it to a project?

Add the goldberry-bom to Gradle or Maven, then the goldberry artifact plus the goldberry-natives classifier jars for the platforms you run on. Coordinates are under io.github.digitalsmile.

## Recent news

- 2026-09-27: The GPU lane: composition, canvas3d and 4K60 video goldberry-gpu binds SDL_GPU. Windows composite through the GPU by default and on the CPU where they cannot, canvas3d is a layer an application renders into, and video-view shows its pictures through a GPU layer: 4K60 with every picture shown. (https://goldberry.dev/docs/adr/0485-the-audio-clock-never-jumps-and-4k60-plays-every-picture.html)
- 2026-09-24: goldberry-media: FFmpeg driven from Java Audio and video playback with hardware decode, track switching, text subtitles, network streams read through a cache, and the operating system's own decoders behind the Decoder SPI. (https://goldberry.dev/docs/adr/0460-media-is-ffmpeg-driven-from-java-not-libvlc.html)
- 2026-09-23: Upstreams moved Blend2D 0.21.3, HarfBuzz 14.5.0, SDL 3.4.16, md4c 0.6.0 and Gradle 9.7.1. The emoji face is now Noto Color Emoji, shipped as goldberry-emoji and drawn from its paint graphs. (https://goldberry.dev/docs/adr/0456-the-emoji-face-is-noto-drawn-from-its-paint-graphs.html)
- 2026-09-19: Snapshots on every push Every push to master publishes the next line's -SNAPSHOT of the toolkit, the BOM and the optional modules to the Central Portal snapshot repository. (https://goldberry.dev/docs/)