The API tour

This is not generated API documentation. Go already gives you that, and it is good here — the house rule is that reasoning goes in the doc comment, so go doc ./widget Gestures is several pages of why. What go doc cannot tell you is which of the module's packages you should ever open, and in what order. That is this page.

The packages, in four tiers

Grouped by when you first need them, not alphabetically. Most apps only ever import the first tier.

Tier 1 — you import these on day one

Tier 2 — once the app is real

Tier 3 — specialised, and most apps never open them

Tier 4 — never. These are not public API.

Everything under internal/ is off limits, and Go enforces it. Two are worth naming because you will see them in stack traces and wonder:

• internal/gfx/ is a vendored fork of a pure-Go WebGPU and 2D-rendering substrate — about 350,000 lines of it, under an MIT lineage (see THIRD_PARTY.md). It is not this project's API and should not be treated as one. Its comments cite ADR-NNN documents that live upstream and are not readable in this repository; that is expected.
• internal/scene records and diffs the draw-command stream to compute a damage rectangle. It implements paint.Canvas, which is why a custom painter's measurements come back identical whether the frame is being recorded or drawn.

The public surface is measured: internal/apisurface generates a manifest of every exported name and the build fails when the tree drifts from it. Worth knowing what that does and does not buy you — it records names and kinds but not signatures, so a signature-only break can pass a green build.

How one tap becomes one frame

The thing generated docs cannot show you: what actually happens, in order, and which package owns each step. Follow a tap on a button in a list.

  1. shell        a platform backend delivers a Pointer event to the Handler
  2. widget       hit testing walks the layout boxes; the deepest
                 Interactive whose rect contains the point wins
  3. your code    its OnTap closure runs — SetState(func(){ s.n++ })
  4. widget       SetState marks that element dirty and asks for a frame
        ↓                (nothing has been rebuilt or drawn yet)
  5. app          the next vsync tick starts a frame; tickers advance first,
                 so animations can dirty more elements
        ↓
  6. widget       build — dirty elements call Build again and the
                 reconciler diffs the returned values against the tree,
                 matching on concrete type, sibling position and key.
                 An unchanged subtree stops the walk; state survives a
                 match and is disposed on a miss.
        ↓
  7. layout       layout — Constraints flow down, sizes flow up, parents
                 position children. One pass. A node whose constraints
                 did not move is a relayout boundary and is skipped.
        ↓
  8. paint        paint — boxes record draw commands into a Canvas.
                 internal/scene diffs that command stream against the
                 previous frame's and produces a damage rectangle — from
                 real glyph ink, not advance boxes.
        ↓
  9. internal/gfx composite — the layer tree becomes GPU commands
                 (Metal, Vulkan, OpenGL ES, or the CPU rasterizer)
        ↓
 10. shell        present: the damaged region is handed to the platform
                 in physical pixels

Two consequences are worth drawing out, because they explain most of what feels unusual here.

Build is not a draw call. It returns a fresh description and nothing more. That is what makes rebuilding a whole subtree on every tap cheap, and it is why a widget tree can be constructed, compared and asserted on in a test with no window anywhere near it. If you catch yourself wanting to know where a widget is during Build, you want LayoutBuilder or LayoutObserver, because the answer does not exist yet.

Only what changed is redone, and that is the architecture rather than an optimisation on top of it. Each of the three phases has its own boundary: a rebuild stops where the description is unchanged, a relayout stops at a node whose constraints did not move, a repaint stops at the layer whose damage rectangle covers it. Typing a character in a field does not re-lay-out the page around it.

The trap: logical pixels above, physical below

If you remember one thing from this page, make it this one. It is invisible at 1× and wrong at 2×, and it has shipped in this repository before.

• Logical pixels — everything in geom, everything in the widget tree, Config.Size, every coordinate in a gesture callback, every rect a widget.Canvas draws into.
• Physical pixels — the painter's surface, damage rectangles handed to a presenter, and anything touching a texture. Physical is logical multiplied by the device scale factor.

Mixing them is correct at 1× and wrong at 2×, where a logical rectangle names the top-left quadrant of a physical surface. The symptom when this went wrong on the web presenter was that half the height of every frame was uploaded and the rest kept showing the previous frame — which does not look like a units bug to anyone debugging it.

For application code the rule is simple, because the boundary is not yours: stay in logical pixels and never multiply by a scale factor. If a number you are holding came from geom or from a callback, it is logical, and the framework converts once at the presenter. You only need the distinction when reading an image back out, or when writing a shell.

Four things that are not where you would guess

The ten names to learn first

If the catalog feels large: it is, and you do not need most of it. These ten cover the great majority of real code.

And the one habit that matters more than any of them: check rather than guess. The catalog is intentionally small and composed from primitives, so a plausible-sounding widget frequently does not exist. go doc ./widget lists all of it in one screen.

The cookbook →  ·  Architecture, in more depth  ·  Coming from Flutter or Compose