suit

Widgets

2026-06-07T03:28:13.464209126Z

import io.github.edadma.suit.widgets.*

A small library of reusable controls composed from the DSL primitives and vdom hooks. A widget is an ordinary vdom component, so its interaction state (hover, pressed) lives in useState and survives re-renders, and it reconciles in place exactly like an application component. Each widget is purely declarative output over box / text / row / stack; the render tree, layout, and input routing underneath give it pixels and behaviour.

Note

These widgets are pointer- and keyboard-driven only. A text field needs text-input support in the SDL binding, and a scroll view needs renderer clip-rects; until those land in sdl3, TextField and ScrollView are deliberately absent rather than approximated. The focus and keyboard infrastructure they need already exists.

Button

val Button: Component2[String, () => Unit]

A push button: a labelled, focusable rectangle that calls onPressed when clicked (a press and release on the button) or activated from the keyboard (Space or Enter while focused). It tints on hover and while held.

Button("Increment", () => setCount(count + 1))

Checkbox

val Checkbox: Component2[Boolean, Boolean => Unit]

A small focusable square that toggles, calling onChange with the new state on a click or on Space while focused. It is controlled — it draws the checked it is given and never holds the value itself, so the parent owns the state. The check is a filled inner square (no glyph-font dependency).

val (checked, setChecked, _) = useState(false)
Checkbox(checked, setChecked)

Slider

val Slider: Component2[Double, Double => Unit]

A horizontal slider over the range 0..1: a full-width track with a draggable thumb. It is controlled — it renders the value it is given and reports a new value through onChange on a press, a drag, or the arrow keys while focused. The new value comes from the press position in the slider’s own coordinate space (local.x / size.width), which is why the handlers live on the outer track, not the thumb (see pointer capture).

val (level, setLevel, _) = useState(0.4)
box(width = 240)(
  Slider(level, setLevel),
)

Theme

object Theme:
  val primary, primaryHover, primaryActive, onPrimary: Color
  val surface, border, accent, track: Color

The default palette the built-in widgets paint with — a small dark-on-accent theme. It is just a set of named Colors; applications can ignore it and pass their own, but the widgets read from it so a stock control looks consistent.

Because Checkbox and Slider are controlled, the pattern is always the same: hold the value in useState, render the widget with it, and pass the setter as onChange.

val App = view {
  val (on, setOn, _)       = useState(true)
  val (level, setLevel, _) = useState(0.5)

  col(spacing = 16)(
    row(crossAxisAlignment = CrossAxisAlignment.Center, spacing = 8)(
      Checkbox(on, setOn),
      text(if on then "on" else "off", color = Color.white),
    ),
    text(s"${(level * 100).toInt}%", color = Color.white),
    box(width = 240)(Slider(level, setLevel)),
  )
}

Quick Start

2026-06-07T03:28:13.464209126Z

A complete suit program: define a component with hooks, lay it out with the DSL, and run it in a native window.

A counter

import io.github.edadma.suit.*
import io.github.edadma.suit.dsl.*
import io.github.edadma.suit.widgets.*

// A component is an ordinary vdom view: its state lives in hooks and survives
// re-renders, and it reconciles in place when state changes.
val App = view {
  val (count, setCount, _) = useState(0)

  col(spacing = 16, mainAxisAlignment = MainAxisAlignment.Center, crossAxisAlignment = CrossAxisAlignment.Center)(
    text(s"count: $count", size = 24, color = Color.white),
    row(spacing = 8)(
      Button("−", () => setCount(count - 1)),
      Button("+", () => setCount(count + 1)),
    ),
  )
}

@main def main(): Unit =
  Suit.run("counter", 320, 200)(App())

Run it with sbt suitNative/run (the call blocks on the frame loop for the window’s lifetime). sbt suitNative/nativeLink just produces the binary without launching it.

How a frame happens

Suit.run opens the SDL window, installs the vdom host and the scheduler seams, mounts your app, and runs the frame loop. A state change flows like this:

An event handler calls a useState setter.
vdom enqueues a re-render on the microtask seam.
The loop drains the queue: the reconciler re-renders and mutates the render tree in place.
The change bubbles a dirty flag to the root.
The next loop iteration repaints — and only then, so an idle UI costs nothing but event polling.

You never call “render” or “repaint” yourself; you change state and the tree follows.

Laying things out

The DSL mirrors the constraint-layout primitives. A quick taste:

// A header bar over a flexible body — the body expands to fill the leftover height.
col()(
  box(bg = Color.rgb(0x222831), height = 48, padding = EdgeInsets.all(12))(
    text("My App", size = 20, color = Color.white),
  ),
  box(flex = 1, padding = EdgeInsets.all(20))(
    text("Body fills the rest.", color = Color.white),
  ),
)

spacer() eats leftover space (the replacement for flex-grow); flex = n on a child makes it claim a share of the leftover main-axis space; stack/align/center position children by fractional alignment. See the layout guide for the full model and the DSL reference for every builder.

Choosing a font

Text is rendered through Cairo. Suit.run uses the Inter font bundled into the binary by default — no installed font required, identical on every OS. Pass fontPath to load a specific TrueType/OpenType file through FreeType instead:

Suit.run("my app", 640, 480, fontPath = "/path/to/MyFont.ttf")(App())

Handling input

Widgets are pointer- and keyboard-driven out of the box. To handle raw input yourself, the box builder takes typed handlers:

box(
  width = 100, height = 100, bg = Color.rgb(0x4dabf7),
  focusable   = true,
  onClick     = e => println(s"clicked at ${e.localX}, ${e.localY}"),
  onMouseEnter = _ => println("hover in"),
  onMouseLeave = _ => println("hover out"),
  onKeyDown   = e => if e.scancode == Key.Space then println("space"),
)()

See the input guide for bubbling, pointer capture, and focus.

Layout

2026-06-07T03:28:13.464209126Z

suit lays out with the protocol Flutter and SwiftUI both adopted — two greenfield frameworks that independently rejected flexbox for the same idea:

Constraints go down, sizes come up, the parent sets positions.

A parent hands each child a Constraints (the range of sizes it may take); the child chooses its own Size within that range; the parent then positions the child by writing its offset. One rule, applied recursively — no monolithic multi-property solver.

Constraints

Constraints is a min/max range on each axis:

final case class Constraints(minWidth: Double, maxWidth: Double, minHeight: Double, maxHeight: Double)

The tight vs loose distinction is the load-bearing one:

An axis is tight when its min equals its max — the parent is dictating that dimension (“be exactly this wide”). Constraints.tight(size) forces both axes.
An axis is loose when its min is 0 — the child may be as small as its natural size, up to the max (“be as big as you need, no larger”). Constraints.loose(size) and the .loosen method drop the minimums to zero.

That single distinction is what later expresses “fill the leftover space” versus “shrink to fit” — the basis of spacers and flexible children.

Useful operations:

c.constrain(size)             // clamp a size into the range
c.tighten(width, height)      // force one/both axes to an explicit extent (clamped)
c.deflate(insets)             // shrink the room by padding on each side
c.loosen                      // min → 0, keep max (turn "fill" into "at most")
c.biggest / c.smallest        // the largest / smallest allowed size

How each primitive sizes itself

Every render object applies the one rule its own way. Knowing each makes layouts predictable.

box

A styled container. An axis with an explicit width/height takes that value; otherwise the axis fills the space offered under a tight constraint and shrinks to its content under a loose one.

A box at the root fills the window; the same box inside a row wraps its contents — the difference is entirely the constraint its parent handed it.

It lays its single child in the room left after padding (loosened, so the child sizes to content), places it inside the padding, and reports the child’s size grown by the insets.

row / col (RenderFlex)

Children are laid end to end along the main axis (horizontal for row, vertical for col) and sized across the cross axis, in two passes:

Inflexible children (flex = 0) are laid out at their natural main size.
The leftover main space, after the inflexible children and the fixed spacing gaps, is divided among the flexible children in proportion to their flex; each gets a tight main constraint equal to its share.

Then:

mainAxisSize — Max fills the parent along the main axis, Min wraps the children.
mainAxisAlignment — distributes any remaining slack: Start / End / Center clump the children; SpaceBetween / SpaceAround / SpaceEvenly spread the gap.
crossAxisAlignment — places each child across: Start / End / Center, or Stretch to force every child to the full cross extent.

When the main axis is unbounded (e.g. a row inside a horizontally-loose parent) there is nothing to distribute, so flexible children are treated as inflexible.

spacer

A flexible empty gap — the replacement for flex-grow. Inside a row or column it eats leftover space in proportion to its flex, pushing its siblings apart. It is just a box with no appearance and a flex factor.

sizedBox (RenderConstrained)

Forces a fixed size onto its child (SwiftUI’s .frame, Flutter’s SizedBox). Each given axis becomes a tight constraint on the child; an unset axis passes the parent’s constraint straight through. It has no appearance — pure layout.

padding

Insets its child by padding on each side: the child is laid out in the parent’s constraints deflated by the insets, placed at the top-left inside the padding, and this object reports the child’s size grown by the insets.

stack / align / center

A z-ordered overlay: children stack back-to-front in declaration order, each positioned by an Alignment. The stack fills bounded space, otherwise wraps its largest child. align is a one-child stack at a chosen alignment; center is align(Alignment.center). This is the basis for modals, tooltips, and badges once portals layer on top.

text

Sizes itself by asking the installed TextMeasurer how big its string is in its TextStyle, clamped into the parent’s constraints. Layout is single-line for now.

Alignment

Alignment(x, y) is a fractional coordinate independent of box size: (-1, -1) is the top-left corner, (0, 0) the centre, (1, 1) the bottom-right. The same value positions a child in a container of any size — exactly what stacks, centring, and a slider thumb need. Named constants cover the nine compass points (Alignment.topLeft, .center, .bottomRight, …).

A worked example

col()(                                            // fills the window (tight from root)
  box(bg = header, height = 48)(                  // fixed-height bar
    text("Title", color = Color.white),
  ),
  row(flex = 1)(                                  // body claims the leftover height
    box(width = 200, bg = sidebar)(),             // fixed-width sidebar
    box(flex = 1, bg = content)(),                // content fills the rest of the width
  ),
)

The column gets a tight constraint from the root, so it fills the window. The header takes its fixed 48px; the row, with flex = 1, claims the remaining height. Inside the row the sidebar takes its fixed 200px and the content box, with flex = 1, fills what’s left.

Installation

2026-06-07T03:28:13.464209126Z

suit targets Scala Native and renders through SDL3, so there are three things to have in place: the Scala Native toolchain, the native SDL3 libraries, and the suit sources themselves.

Note

suit is in active development and is not yet published to Maven Central. You build and run it from the repository checkout. The sections below describe that workflow; published artifacts and a one-line dependency will come once the API stabilises.

Requirements

Scala 3 with sbt
The sbt-scala-native and sbt-scala-native-crossproject plugins
LLVM/Clang (the Scala Native toolchain)
The SDL3, Cairo, and FreeType shared libraries on your system

Install the native libraries

suit’s runtime links against system libraries via @link: SDL3 (window, input, present, through the sdl3 bindings), Cairo (the drawing engine), and FreeType (font loading). On macOS with Homebrew:

brew install sdl3 cairo

Cairo depends on FreeType, so Homebrew pulls it in alongside. On Linux, install the SDL3, Cairo, and FreeType development packages from your distribution (or build them from source).

Get the sources

suit depends on two sibling repositories, both checked out next to it:

riposte — supplies the vdom core. suit consumes its JVM and Native cross-targets as a source dependency (vdomJVM / vdomNative), because those targets are not published; only vdom.js is on Central.
sdl3, libcairo, and freetype — the SDL3, Cairo, and FreeType bindings, pulled from Maven Central.

git clone https://github.com/edadma/riposte.git
git clone https://github.com/edadma/suit.git

The expected layout is the two repos side by side:

dev/
├── riposte/      # provides vdomJVM / vdomNative (source dependency)
└── suit/         # this repo

suit’s build.sbt references riposte by relative path:

.jvmConfigure(_.dependsOn(ProjectRef(file("../riposte"), "vdomJVM")))
.nativeConfigure(_.dependsOn(ProjectRef(file("../riposte"), "vdomNative")))

and pulls SDL3 from Central:

.nativeSettings(
  libraryDependencies ++= Seq(
    "io.github.edadma" %%% "sdl3"     % "0.2.2",
    "io.github.edadma" %%% "libcairo" % "0.0.4",
    "io.github.edadma" %%% "freetype" % "0.0.4",
  ),
)

Verify the setup

Run the headless layout suite on the JVM — it needs no window, no device, and no native toolchain, because the layout engine is pure Scala:

sbt suitJVM/test

Then build the native demo and run it (see the quick start):

sbt suitNative/run

If a window opens showing the widget demo, the toolchain and SDL3 are wired correctly.

Input

2026-06-07T03:28:13.464209126Z

Input is the bridge from raw device events to the render tree’s handlers. The runtime polls SDL for mouse, wheel, and keyboard events and feeds them to a set of routers; the routers hit-test the tree (for pointer events) or consult the focus owner (for key events) and fire the matching handler. Like layout, all of this is pure Scala — it needs only hitTest, the parent chain, and the handler maps — so the dispatch model is unit-tested on the JVM.

Bubbling

Dispatch bubbles. A hit-test lands on the deepest object under the cursor, but handlers are usually registered on a composite’s outer object — a button’s frame, a slider’s track — while the cursor actually sits over an inner decoration with no handler of its own.

So an event walks up the parent chain from the hit to the nearest ancestor with a handler for that event, and fires there. This is the analogue of DOM event bubbling, in the single-listener-per-object form suit uses.

The event’s coordinates are resolved against the receiving object, not the raw hit:

final case class PointerEvent(position: Offset, local: Offset, size: Size, button: Int = 0):
  def x: Double; def y: Double            // absolute (window) coordinates
  def localX: Double; def localY: Double  // relative to the receiving object's top-left

position is the absolute window coordinate.
local is that point relative to the receiving object’s top-left, and size is that object’s size.

Together they let a handler work in its own coordinate space — a slider maps local.x / size.width to a fraction, measured against its whole track no matter which inner pixel was hit.

Pointer capture (drag)

A press captures the pointer at the hit object. While captured, every subsequent move goes to the capturing object — even after the cursor leaves its bounds — until the button comes up. This is what makes dragging work: a slider keeps receiving mousemove while you drag past its edge. During a capture drag, button carries the held button so a handler can tell a drag from a plain hover (if e.button != 0 then …).

A click fires on button-up only if the press and the release resolve to the same click handler — i.e. the release landed on the widget the press started on. Pressing a button and releasing off it does not click.

Hover

Hover is tracked per owner, not per pixel. The router finds the nearest ancestor that takes part in hover (has a mouseenter or mouseleave handler) and fires mouseleave / mouseenter only when that owner changes — so moving the cursor across a button’s inner label does not spam enter/leave, and a widget styles itself on hover cleanly.

Keyboard focus

FocusManager owns which object currently has keyboard focus:

A press routes focus to the nearest focusable ancestor of the hit object (the target itself if it is focusable), or clears focus if the press landed on nothing focusable. Clicking a widget takes focus; clicking empty space drops it.
Focus changes fire focus / blur handlers (no payload) so a widget can re-style itself.
KeyRouter delivers keydown / keyup only to the focused object.

Mark an object focusable in the DSL with focusable = true; the built-in widgets set it on their outer object.

final case class KeyEvent(scancode: Int, repeat: Boolean = false)

scancode is the physical key as a standard USB-HID usage code — a stable cross-platform numbering, not an SDL detail. The Key object names the common ones:

Key.Enter  Key.Escape  Key.Backspace  Key.Tab  Key.Space
Key.Left   Key.Right   Key.Up         Key.Down
Key.Home   Key.End     Key.Delete     Key.PageUp  Key.PageDown

repeat is true for the auto-repeat events a held key produces. Text entry — the Unicode a key press produces under the active layout — is a separate concern (text-input events), not derived from scancodes here.

Wheel

A wheel turn bubbles a ScrollEvent to the nearest wheel handler at the cursor.

final case class ScrollEvent(position: Offset, deltaX: Double, deltaY: Double)

Positive deltaY is a downward/away scroll, matching SDL’s convention.

Handlers on box

All of this is reached through the typed handlers on the box builder:

box(
  focusable    = true,
  onClick      = (e: PointerEvent) => ...,
  onMouseDown  = (e: PointerEvent) => ...,
  onMouseUp    = (e: PointerEvent) => ...,
  onMouseMove  = (e: PointerEvent) => ...,
  onMouseEnter = (e: PointerEvent) => ...,
  onMouseLeave = (e: PointerEvent) => ...,
  onWheel      = (e: ScrollEvent)  => ...,
  onKeyDown    = (e: KeyEvent)     => ...,
  onKeyUp      = (e: KeyEvent)     => ...,
  onFocus      = () => ...,
  onBlur       = () => ...,
)(children*)

The widget library is built entirely on these — reading the Button, Checkbox, and Slider sources is the best way to see the model in practice.

DSL

2026-06-07T03:28:13.464209126Z

import io.github.edadma.suit.dsl.*

The declarative surface — the builders that produce vdom VNodes, the render-tree equivalent of riposte’s HTML DSL. Each builder emits an element whose tag selects a RenderObject kind and whose props are typed values (a Color, an EdgeInsets, an Alignment, a layout enum), never strings.

Configuration goes in the first parameter list and children in the second, so nesting reads cleanly:

col(spacing = 8)(
  box(bg = Color.rgb(0x222831))(text("hi")),
  spacer(),
  box(bg = Color.rgb(0x222831))(text("bye")),
)

Sizes are plain Doubles; Double.NaN means “unset” (left to the layout), so call sites stay free of Some(...).

box

The styled container — suit’s workhorse rectangle.

def box(
    bg:          Color | Null     = null,
    border:      Color | Null     = null,
    borderWidth: Double           = 0.0,
    width:       Double           = Double.NaN,
    height:      Double           = Double.NaN,
    padding:     EdgeInsets | Null = null,
    flex:        Int              = 0,
    focusable:   Boolean          = false,
    // pointer / wheel / key / focus handlers — see the Input guide
    onClick: (PointerEvent => Unit) | Null = null,
    /* onMouseDown, onMouseUp, onMouseMove, onMouseEnter, onMouseLeave,
       onWheel, onKeyDown, onKeyUp, onFocus, onBlur */
)(children: VNode*): VNode

bg / border / borderWidth give it appearance; width / height fix its size (omit to fill a tight parent or wrap a loose one); padding insets its child; flex makes it expand inside a row/column. See the input guide for the handlers.

text

def text(content: String, size: Double = 16.0, color: Color = Color(0, 0, 0)): VNode

A single line of text in color at point size. It measures and paints as one line through the installed TextMeasurer and the canvas.

row / col

def row(
    mainAxisAlignment:  MainAxisAlignment  = MainAxisAlignment.Start,
    crossAxisAlignment: CrossAxisAlignment = CrossAxisAlignment.Start,
    mainAxisSize:       MainAxisSize       = MainAxisSize.Max,
    spacing:            Double             = 0.0,
    flex:               Int                = 0,
)(children: VNode*): VNode

def col(/* same parameters */)(children: VNode*): VNode

A horizontal (row) or vertical (col) stack. Children are laid along the main axis; flexible children share the leftover space. The enums:

MainAxisAlignment — Start, End, Center, SpaceBetween, SpaceAround, SpaceEvenly
CrossAxisAlignment — Start, End, Center, Stretch
MainAxisSize — Min (wrap children), Max (fill parent)

See the layout guide for how the two passes distribute space.

spacer

def spacer(flex: Int = 1): VNode

A flexible empty gap — the replacement for flex-grow. Inside a row or column it eats leftover space in proportion to flex, pushing its siblings apart.

padding

def padding(insets: EdgeInsets)(children: VNode*): VNode

Insets its child by insets on each side.

sizedBox

def sizedBox(width: Double = Double.NaN, height: Double = Double.NaN)(children: VNode*): VNode

A fixed-size box with no appearance: forces width/height onto its child (or occupies that size with no child). Omit an axis to leave it to the parent.

stack / align / center

def stack(alignment: Alignment = Alignment.topLeft)(children: VNode*): VNode
def align(alignment: Alignment)(children: VNode*): VNode
def center(children: VNode*): VNode

stack is a z-ordered overlay: children stack back-to-front, each positioned by alignment. align positions a single child at an alignment (a one-child stack); center is align(Alignment.center).

Geometry & colour values

The DSL takes these plain value types (all pure, no SDL dependency):

Offset(x, y)                         // a 2-D position or displacement
Size(width, height)
Rect(x, y, width, height)            // .contains(px, py), right/bottom-exclusive
EdgeInsets(top, right, bottom, left) // .all(v), .symmetric(horizontal, vertical)
Alignment(x, y)                      // fractional: (-1,-1) topLeft … (1,1) bottomRight
Color(r, g, b, a = 255)              // .rgb(0xRRGGBB), .parse("#rrggbb[aa]"), .toHex, .withAlpha

Color provides black, white, transparent, and Color.rgb(hex) for packed literals.

Architecture

2026-06-07T03:28:13.464209126Z

suit is one layer of a three-layer system, the same division of labour Flutter draws between its widgets, its elements, and its render objects. Two of those layers already exist in vdom; suit builds the third.

Three trees

 Widgets / VNodes     ── what you write: col(...)(box(...), text(...))      ← vdom
 Elements             ── the reconciled, stateful instance tree            ← vdom
 RenderObjects        ── layout, paint, hit-test                           ← suit

The VNode tree is the declarative description your component returns. It is cheap and rebuilt freely. vdom’s DSL produces it; suit’s DSL (box, row, col, …) is just a vocabulary of VNodes whose tags name render-object kinds.
The element tree is vdom’s reconciler at work: it diffs successive VNode trees, holds hook state (useState), and decides the minimal set of host mutations. This is entirely vdom — suit adds nothing here.
The RenderObject tree is suit. Each node lays itself out, paints itself, and answers hit-tests. The reconciler creates and mutates these nodes through a HostConfig; every opaque host node it holds is really a RenderObject.

vdom is host-agnostic: the same reconciler and hooks drive the browser DOM in riposte and the screen here. The only thing that changes per host is the HostConfig binding and the leaf layer underneath it.

You never import vdom directly. suit re-exports its consumer-facing surface — view, component, the hooks (useState, useEffect, …), and the VNode model — under io.github.edadma.suit, so an application imports only io.github.edadma.suit.* (plus suit.dsl.* / suit.widgets.*). vdom is an implementation detail, the way the browser’s DOM engine is to a web page.

The host binding

SuitHostConfig is the single seam where vdom meets suit’s renderer — the analogue of riposte’s DOM host config, but creating retained render objects instead of DOM nodes. The reconciler calls it to create elements, edit the tree, set properties, and register listeners:

def createElement(tag: String, namespace: String | Null): AnyRef = tag match
  case "box"      => new RenderBox
  case "row"      => new RenderFlex(Axis.Horizontal)
  case "col"      => new RenderFlex(Axis.Vertical)
  case "padding"  => new RenderPadding
  case "sizedBox" => new RenderConstrained
  case "stack"    => new RenderStack
  case "text"     => new RenderText("")
  case _          => new RenderBox

Properties travel as typed values, not strings. vdom’s PropValue channel carries a Color, an EdgeInsets, an Alignment, or a layout enum with its real type straight to the matching render-object field; nothing is stringified and re-parsed. DOM-shaped HostConfig methods (setStyle with CSS, setInnerHtml, namespaces) have no meaning on a pixel canvas and are no-ops.

What a RenderObject does

Every render object implements three jobs:

abstract class RenderObject:
  def layout(constraints: Constraints): Unit                    // size self, position children
  def paint(canvas: Canvas, origin: Offset): Unit               // draw back-to-front
  def hitTest(point: Offset, origin: Offset): RenderObject|Null // deepest object under a point

The kinds map one-to-one onto the DSL: RenderBox (styled container), RenderFlex (row / column), RenderPadding, RenderConstrained (sized box), RenderStack (z-stack / align / center), RenderText, plus a RenderRoot at the top and a RenderAnchor for vdom’s fragment/portal/empty placeholders.

The paint seam

Painting goes through a Canvas trait — the boundary between what to draw and how:

trait Canvas:
  def fillRect(rect: Rect, color: Color): Unit
  def strokeRect(rect: Rect, color: Color, width: Double): Unit
  def fillCircle(center: Offset, radius: Double, color: Color): Unit
  def line(a: Offset, b: Offset, width: Double, color: Color): Unit
  def drawText(origin: Offset, text: String, style: TextStyle): Unit

On Native, CairoCanvas draws through Cairo — a real 2D vector engine, so every fill, stroke, and glyph is anti-aliased by its coverage rasteriser. SDL3 only creates the window, reads input, and presents the finished frame. In tests, RecordingCanvas captures the same calls so paint output can be asserted on. The same trait split lets TextMeasurer size text off-device (a deterministic fake in tests, a Cairo-backed measurer at runtime), which keeps the whole layout pass JVM-testable.

Why JVM-testable matters

The layout engine, the render tree, and the geometry are pure Scala with no SDL dependency — they live in shared/ and cross to a JVM target whose only purpose is tests. So sbt suitJVM/test exercises real layout, paint (against RecordingCanvas), and input routing with no window and no native toolchain, the same way vdom’s reconciler is tested headlessly. This is the whole reason the layout engine was kept FFI-free: no Yoga, no C solver, just a recursive constraint negotiation you can step through in a debugger.

The runtime

Suit.run is the Native entry point. It owns the SDL window and renderer, installs the host binding and the two scheduler seams (a microtask queue for re-renders, a macrotask queue for passive effects), mounts the app, and runs the frame loop. The loop is the bridge between vdom’s React-style batched updates and a game-style render loop: vdom never paints on its own — it enqueues work, the loop drains it, the tree is marked dirty, and the loop repaints only when something changed.

One rendering detail is worth knowing: Cairo draws the frame into an in-memory ARGB32 image surface, which is uploaded to an SDL streaming texture and blitted to the window each iteration (re-drawn only when the tree is dirty). Cairo’s ARGB32 layout is byte-identical to SDL’s ARGB8888 on a little-endian host, so the upload is a straight copy with no conversion. SDL never draws a shape and Cairo never touches the OS — the clean split between the graphics engine and the platform layer.

suit

Widgets

Button

Checkbox

Slider

Theme

A controlled-widget example

Quick Start

A counter

How a frame happens

Laying things out

Choosing a font

Handling input

Layout

Constraints

How each primitive sizes itself

box

row / col (RenderFlex)

spacer

sizedBox (RenderConstrained)

padding

stack / align / center

text

Alignment

A worked example

Installation

Requirements

Install the native libraries

Get the sources

Verify the setup

Input

Bubbling

Pointer capture (drag)

Hover

Keyboard focus

Wheel

Handlers on box

DSL

box

text

row / col

spacer

padding

sizedBox

stack / align / center

Geometry & colour values

Architecture

Three trees

The host binding

What a RenderObject does

The paint seam

Why JVM-testable matters

The runtime