ranger-compiler 3.5.0 → 3.5.2

package/dist/lib/evg/android/src/main/kotlin/fi/ranger/evg/EvgEngineThread.kt

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: MIT
+package fi.ranger.evg
+
+import java.util.concurrent.Executors
+import java.util.concurrent.atomic.AtomicBoolean
+
+/**
+ * The engine off the UI thread — Android, and the JVM.
+ *
+ * PLAN_NATIVE_HOSTS.md S1. A Ranger app compiled to Kotlin has no `android.*`
+ * in it, so nothing about it has to run on the UI thread; what has to is the
+ * `View` that receives touches and the `Canvas` that paints. So the app lives
+ * on ONE thread of its own, every call the host makes runs there in the order
+ * the host made it, and a call that changed the page produces a frame — laid
+ * out and listed on that thread — that is handed to the UI thread, which
+ * paints it and nothing else.
+ *
+ * Three verbs, and the discipline is that a host uses them and never touches
+ * the app directly:
+ *
+ *   post { app -> … }            run there; return true if a frame is owed
+ *   ask({ app -> … }) { v -> … } run there; answer on the UI thread
+ *   sync { app -> … }            run there and WAIT — for the one read the
+ *                                platform insists on synchronously
+ *                                (`onCheckIsTextEditor`)
+ *
+ * Frames are coalesced: a burst of posts that each say "a frame is owed"
+ * produces one build after the last of them, and a build asked for while one
+ * is running produces exactly one more when it finishes — never a queue of
+ * stale frames the UI thread has to draw through.
+ *
+ * This file is in the platform-free source set on purpose: `onMain` is how
+ * the host reaches its UI thread (`view::post` on Android, `SwingUtilities`
+ * or a plain call on a JVM check), so the same class serves both.
+ *
+ * @param app the Ranger app; make it BEFORE this, and never read it again
+ *   from the UI thread
+ * @param build the frame, run on the engine thread — `app.frame()` and
+ *   whatever the painter needs beside it
+ * @param onMain run a block on the UI thread
+ * @param deliver called on the UI thread with each built frame; keep it and
+ *   `invalidate()`
+ */
+class EvgEngineThread<App, Frame>(
+    private val app: App,
+    private val build: (App) -> Frame,
+    private val onMain: (Runnable) -> Unit,
+    private val deliver: (Frame) -> Unit,
+) {
+    private val exec = Executors.newSingleThreadExecutor { r ->
+        Thread(r, "evg-engine").apply { isDaemon = true }
+    }
+
+    // Touched on the engine thread only.
+    private var building = false
+    private var wanted = false
+    private val closed = AtomicBoolean(false)
+
+    /** Run `work` on the engine thread. A `true` result asks for a frame. */
+    fun post(work: (App) -> Boolean) {
+        if (closed.get()) return
+        exec.execute {
+            if (work(app)) requestFrameOnThread()
+        }
+    }
+
+    /** Run `work` on the engine thread and hand its answer to `then` on the UI thread. */
+    fun <T> ask(work: (App) -> T, then: (T) -> Unit) {
+        if (closed.get()) return
+        exec.execute {
+            val v = work(app)
+            onMain(Runnable { then(v) })
+        }
+    }
+
+    /**
+     * Run `work` on the engine thread and wait for it. For the reads the
+     * platform asks for synchronously and nothing else: it holds the caller
+     * for as long as whatever is already queued takes.
+     */
+    fun <T> sync(work: (App) -> T): T = exec.submit<T> { work(app) }.get()
+
+    /** A frame is owed — the clock ticked, the view resized. */
+    fun invalidate() {
+        if (closed.get()) return
+        exec.execute { requestFrameOnThread() }
+    }
+
+    fun close() {
+        closed.set(true)
+        exec.shutdown()
+    }
+
+    // On the engine thread.
+    private fun requestFrameOnThread() {
+        if (building) {
+            wanted = true
+            return
+        }
+        building = true
+        // Not inline: the posts already queued behind this one run first, so
+        // a press and the release that followed it are both in the frame.
+        exec.execute { buildOnThread() }
+    }
+
+    private fun buildOnThread() {
+        val f = build(app)
+        onMain(Runnable { deliver(f) })
+        building = false
+        if (wanted) {
+            wanted = false
+            requestFrameOnThread()
+        }
+    }
+}

package/dist/lib/evg/android/src/main/kotlin/fi/ranger/evg/EvgPainter.kt

@@ -0,0 +1,231 @@
+package fi.ranger.evg
+
+import fi.ranger.rgr.EVGDisplayList
+import fi.ranger.rgr.EVGDrawCmd
+
+/**
+ * The walk: an `EVGDisplayList` in, calls on an [EvgSurface] out.
+ *
+ * The display list's own comment says a sixth backend should not be a sixth
+ * copy of the traversal, and this is that rule applied one level down: Android
+ * and AWT differ in how they fill a rounded box, not in what a command *means*,
+ * so what a command means is decided exactly once, here.
+ *
+ * Two things this painter honours that the existing backends do not:
+ *
+ *  * **Gradients and shadows.** `EVGDisplayList.toJson` carries neither, so the
+ *    WebGL host cannot draw them and only the CPU rasteriser does. Reading the
+ *    objects directly — which is what a Kotlin host can do and a browser cannot
+ *    — brings both back.
+ *  * **Clipping and multi-ring paths.** The SoftCanvas painter ignores
+ *    `PUSH_CLIP` / `POP_CLIP` and flattens every path to one polygon, so a
+ *    ring-with-a-hole comes out solid. `save`/`clipRect`/`restore` and a real
+ *    even-odd fill are one line each on both surfaces here.
+ */
+object EvgPainter {
+
+    private const val RECT = 0
+    private const val BORDER = 1
+    private const val IMAGE = 2
+    private const val TEXT = 3
+    private const val PUSH_CLIP = 4
+    private const val POP_CLIP = 5
+    private const val PATH = 6
+    private const val STROKE = 7
+
+    /** Anything below this is invisible; drawing it is work for nothing. */
+    private const val MIN_ALPHA = 0.001
+
+    /**
+     * Paint every command in order. Returns how many were actually drawn, which
+     * is what a host puts in a debug overlay — a frame that draws 0 of 300
+     * commands is a bug you want to see rather than a black screen.
+     */
+    fun paint(list: EVGDisplayList, surface: EvgSurface): Int {
+        var drawn = 0
+        // A list that pushes more clips than it pops must not leave the surface
+        // with a clip nobody asked for, and one that pops more than it pushes
+        // must not restore past the state the host handed us. The depth counter
+        // is the whole of both guarantees.
+        var clipDepth = 0
+        val n = list.count()
+        var i = 0
+        while (i < n) {
+            val c = list.at(i)
+            i++
+            when (c.kind) {
+                PUSH_CLIP -> {
+                    surface.save()
+                    surface.clipRect(c.x.toFloat(), c.y.toFloat(), c.w.toFloat(), c.h.toFloat())
+                    clipDepth++
+                    continue
+                }
+                POP_CLIP -> {
+                    if (clipDepth > 0) {
+                        surface.restore()
+                        clipDepth--
+                    }
+                    continue
+                }
+            }
+
+            // A rotation turns the command about the point the display list
+            // names, and about the command's own box centre only when it names
+            // none. `EVGDisplayList` resolves `transform-origin` into
+            // rotOriginX/Y and sets hasRotOrigin, exactly because the centre is
+            // "right for a lone rotated label and wrong for everything else: a
+            // box, its text and its children have to turn about ONE point or
+            // they come apart".
+            //
+            // Ignoring it is what made RealTrainer's loading spinner a single
+            // small bar. Its twelve blades are one 8x26 box each, fanned into a
+            // ring by `transform: rotate(Ndeg)` about `transform-origin: 4px
+            // 54px` -- a point 41px BELOW each blade's own centre. Turned about
+            // their centres they all spin in place and land on top of each
+            // other. Wrapping it in save/restore keeps the clip stack above
+            // untouched.
+            val turned = c.rotate > 0.001 || c.rotate < -0.001
+            if (turned) {
+                surface.save()
+                surface.rotate(
+                    c.rotate.toFloat(),
+                    (if (c.hasRotOrigin) c.rotOriginX else c.x + c.w * 0.5).toFloat(),
+                    (if (c.hasRotOrigin) c.rotOriginY else c.y + c.h * 0.5).toFloat(),
+                )
+            }
+
+            if (drawOne(c, surface)) drawn++
+
+            if (turned) surface.restore()
+        }
+        while (clipDepth > 0) {
+            surface.restore()
+            clipDepth--
+        }
+        return drawn
+    }
+
+    private fun drawOne(c: EVGDrawCmd, surface: EvgSurface): Boolean {
+        when (c.kind) {
+            RECT -> {
+                val shadow = shadowOf(c)
+                val gradient = gradientOf(c)
+                if (c.a < MIN_ALPHA && gradient == null && shadow == null) return false
+                surface.fillRect(
+                    c.x.toFloat(), c.y.toFloat(), c.w.toFloat(), c.h.toFloat(),
+                    c.radius.toFloat(),
+                    colorOf(c),
+                    gradient,
+                    shadow,
+                )
+                return true
+            }
+            BORDER -> {
+                if (c.a < MIN_ALPHA) return false
+                // A border with no thickness is still a border: the display
+                // list leaves the default at 0 for a hairline, and a stroke of
+                // width 0 is invisible on both surfaces.
+                val t = if (c.thickness > 0.0) c.thickness.toFloat() else 1f
+                surface.strokeRect(
+                    c.x.toFloat(), c.y.toFloat(), c.w.toFloat(), c.h.toFloat(),
+                    c.radius.toFloat(), t,
+                    colorOf(c),
+                )
+                return true
+            }
+            IMAGE -> {
+                if (c.src.isEmpty()) return false
+                surface.drawImage(
+                    c.src,
+                    c.x.toFloat(), c.y.toFloat(), c.w.toFloat(), c.h.toFloat(),
+                    c.radius.toFloat(),
+                    c.flipH, c.flipV,
+                )
+                return true
+            }
+            TEXT -> {
+                if (c.text.isEmpty()) return false
+                if (c.a < MIN_ALPHA) return false
+                surface.drawTextRun(
+                    c.text,
+                    c.x.toFloat(), c.y.toFloat(),
+                    c.fontSize.toFloat(),
+                    c.fontFamily,
+                    isBold(c.fontWeight),
+                    // `addText` has nowhere else to record a slanted face, so
+                    // it writes "italic" into textAlign and `toJson` reads it
+                    // back out the same way. Not lovely, but it is the format.
+                    c.textAlign == "italic",
+                    colorOf(c),
+                )
+                return true
+            }
+            PATH -> {
+                if (c.a < MIN_ALPHA) return false
+                if (c.pts.size < 6) return false
+                surface.fillPath(c.pts, ringsOf(c), c.evenOdd, colorOf(c), shadowOf(c))
+                return true
+            }
+            STROKE -> {
+                if (c.a < MIN_ALPHA) return false
+                if (c.pts.size < 4) return false
+                val t = if (c.thickness > 0.0) c.thickness.toFloat() else 1f
+                surface.strokePath(c.pts, ringsOf(c), t, colorOf(c))
+                return true
+            }
+        }
+        return false
+    }
+
+    /**
+     * A path emitted by the SVG walk carries its ring boundaries; one emitted
+     * by `addPolygon` / `addPolyline` may not. A single implicit ring covering
+     * every point is the right reading of an empty `ringEnds` — it is what the
+     * polygon filler assumes.
+     */
+    private fun ringsOf(c: EVGDrawCmd): List<Int> =
+        if (c.ringEnds.isEmpty()) listOf(c.pts.size) else c.ringEnds
+
+    private fun gradientOf(c: EVGDrawCmd): EvgGradient? {
+        if (!c.hasGrad) return null
+        return EvgGradient(
+            color1 = argb(c.a, c.r, c.g, c.b),
+            color2 = argb(c.a2, c.r2, c.g2, c.b2),
+            // dir 0 = vertical (top to bottom), 1 = horizontal (left to right)
+            vertical = c.gradDir != 1,
+        )
+    }
+
+    private fun shadowOf(c: EVGDrawCmd): EvgShadow? {
+        if (!c.hasShadow) return null
+        if (c.shadowA < MIN_ALPHA) return null
+        return EvgShadow(
+            dx = c.shadowX.toFloat(),
+            dy = c.shadowY.toFloat(),
+            blur = c.shadowBlur.toFloat(),
+            color = argb(c.shadowA, c.shadowR, c.shadowG, c.shadowB),
+        )
+    }
+
+    private fun colorOf(c: EVGDrawCmd): Int = argb(c.a, c.r, c.g, c.b)
+
+    /** 0-255 channels and a 0-1 alpha, the way every command carries them. */
+    fun argb(alpha: Double, r: Int, g: Int, b: Int): Int {
+        val a = clamp255((alpha * 255.0 + 0.5).toInt())
+        return (a shl 24) or (clamp255(r) shl 16) or (clamp255(g) shl 8) or clamp255(b)
+    }
+
+    private fun clamp255(v: Int): Int = if (v < 0) 0 else if (v > 255) 255 else v
+
+    /**
+     * The display list writes the word, not the number — `addText` only ever
+     * says "bold" — but a stylesheet path could put a CSS weight here, so a
+     * number is read as one.
+     */
+    private fun isBold(weight: String): Boolean {
+        if (weight.isEmpty()) return false
+        if (weight == "bold" || weight == "bolder") return true
+        val n = weight.toIntOrNull() ?: return false
+        return n >= 600
+    }
+}

package/dist/lib/evg/android/src/main/kotlin/fi/ranger/evg/EvgSurface.kt

@@ -0,0 +1,117 @@
+package fi.ranger.evg
+
+/**
+ * Everything a backend has to be able to draw, and nothing else.
+ *
+ * `EVGDisplayList` is eight command kinds of absolute pixels and resolved
+ * colours — no tree, no units, no fonts to resolve. That is small enough that
+ * a backend is a page of delegation rather than a renderer, which is the point:
+ * `AndroidEvgSurface` paints with `android.graphics.Canvas`, `AwtEvgSurface`
+ * paints the same list with `java.awt.Graphics2D`, and the walk that decides
+ * what each command *means* ([EvgPainter]) is written once and shared.
+ *
+ * That second implementation is not decoration. An Android painter can only be
+ * checked on a device or an emulator; the same painter driven through AWT
+ * renders a deck to a PNG on any JVM, which is what makes the port testable in
+ * CI at all.
+ *
+ * Geometry is in the app's own pixels. A host that wants device pixels scales
+ * its canvas and leaves these numbers alone — text then rasterises at the
+ * panel's real resolution instead of being blown up from a small bitmap.
+ */
+interface EvgSurface {
+    /** Push the clip/transform stack. Paired with [restore]. */
+    fun save()
+
+    /** Pop back to the state the matching [save] recorded. */
+    fun restore()
+
+    /** Intersect the clip with this rectangle. Only ever inside a [save]. */
+    fun clipRect(x: Float, y: Float, w: Float, h: Float)
+
+    /** Turn the coordinate system `degrees` about (`px`, `py`). */
+    fun rotate(degrees: Float, px: Float, py: Float)
+
+    /**
+     * A filled box, possibly rounded, possibly a two-stop gradient, possibly
+     * under a drop shadow. The shadow is painted first and is the shape's own
+     * silhouette — a rounded box casts a rounded shadow.
+     */
+    fun fillRect(
+        x: Float, y: Float, w: Float, h: Float,
+        radius: Float,
+        color: Int,
+        gradient: EvgGradient?,
+        shadow: EvgShadow?,
+    )
+
+    /** A stroked outline, drawn as a band of `thickness` INSIDE the box. */
+    fun strokeRect(
+        x: Float, y: Float, w: Float, h: Float,
+        radius: Float, thickness: Float,
+        color: Int,
+    )
+
+    /**
+     * A filled vector outline. The rings are already flattened and already in
+     * page coordinates; `ringEnds` gives the index in `pts` one past each
+     * ring's last coordinate, so a shape with a hole arrives as two rings.
+     */
+    fun fillPath(
+        pts: List<Double>, ringEnds: List<Int>, evenOdd: Boolean,
+        color: Int,
+        shadow: EvgShadow?,
+    )
+
+    /** The same rings, stroked rather than filled. */
+    fun strokePath(
+        pts: List<Double>, ringEnds: List<Int>,
+        thickness: Float,
+        color: Int,
+    )
+
+    /**
+     * A picture, by the package part name the deck gave it. A surface that has
+     * no bytes for `src` should draw the placeholder rather than nothing — a
+     * missing texture and a blank slide look identical otherwise.
+     */
+    fun drawImage(
+        src: String,
+        x: Float, y: Float, w: Float, h: Float,
+        radius: Float,
+        flipH: Boolean, flipV: Boolean,
+    )
+
+    /**
+     * One run, on one line, in one face.
+     *
+     * `top` is the top of the LINE BOX, not the baseline: EVG measured the run
+     * with the same TrueType face the surface is about to draw it in, and the
+     * baseline sits one face-ascent below. Placing the ink at `top` instead
+     * lifts every run by the empty space above its capitals — a couple of
+     * pixels on a caption, most of a line on a heading. The surface owns that
+     * conversion because only it knows what its own font metrics say.
+     */
+    fun drawTextRun(
+        text: String,
+        x: Float, top: Float,
+        sizePx: Float,
+        family: String, bold: Boolean, italic: Boolean,
+        color: Int,
+    )
+}
+
+/** A two-stop linear gradient. `vertical` is EVG's `gradDir == 0`. */
+data class EvgGradient(
+    val color1: Int,
+    val color2: Int,
+    val vertical: Boolean,
+)
+
+/** An outer drop shadow: offset, blur radius, colour. */
+data class EvgShadow(
+    val dx: Float,
+    val dy: Float,
+    val blur: Float,
+    val color: Int,
+)

package/dist/lib/evg/android/src/main/kotlin/fi/ranger/evg/RecordingSurface.kt

@@ -0,0 +1,94 @@
+package fi.ranger.evg
+
+
+/**
+ * A surface that counts what it was asked to draw, and then draws it.
+ *
+ * "Every slide produced some ink" is a weak thing to check: a deck of nothing
+ * but grey boxes passes it, and so does a painter that has quietly stopped
+ * dispatching text. What a coverage run wants to know is which *kinds* of
+ * command reached a surface at all — whether the corpus exercises paths and
+ * clips and gradients and mirrored pictures, and whether the walk delivers
+ * them — so this wraps the real surface and keeps a tally on the way through.
+ */
+class RecordingSurface(private val inner: EvgSurface) : EvgSurface {
+
+    val calls = HashMap<String, Int>()
+
+    private fun bump(what: String) {
+        calls[what] = (calls[what] ?: 0) + 1
+    }
+
+    fun count(what: String): Int = calls[what] ?: 0
+
+    override fun save() {
+        bump("save"); inner.save()
+    }
+
+    override fun restore() {
+        bump("restore"); inner.restore()
+    }
+
+    override fun clipRect(x: Float, y: Float, w: Float, h: Float) {
+        bump("clipRect"); inner.clipRect(x, y, w, h)
+    }
+
+    override fun rotate(degrees: Float, px: Float, py: Float) {
+        bump("rotate"); inner.rotate(degrees, px, py)
+    }
+
+    override fun fillRect(
+        x: Float, y: Float, w: Float, h: Float,
+        radius: Float, color: Int, gradient: EvgGradient?, shadow: EvgShadow?,
+    ) {
+        bump("fillRect")
+        if (radius > 0.5f) bump("roundedRect")
+        if (gradient != null) bump("gradient")
+        if (shadow != null) bump("shadow")
+        inner.fillRect(x, y, w, h, radius, color, gradient, shadow)
+    }
+
+    override fun strokeRect(
+        x: Float, y: Float, w: Float, h: Float,
+        radius: Float, thickness: Float, color: Int,
+    ) {
+        bump("strokeRect"); inner.strokeRect(x, y, w, h, radius, thickness, color)
+    }
+
+    override fun fillPath(
+        pts: List<Double>, ringEnds: List<Int>, evenOdd: Boolean,
+        color: Int, shadow: EvgShadow?,
+    ) {
+        bump("fillPath")
+        if (ringEnds.size > 1) bump("multiRingPath")
+        if (evenOdd) bump("evenOddPath")
+        if (shadow != null) bump("shadow")
+        inner.fillPath(pts, ringEnds, evenOdd, color, shadow)
+    }
+
+    override fun strokePath(pts: List<Double>, ringEnds: List<Int>, thickness: Float, color: Int) {
+        bump("strokePath"); inner.strokePath(pts, ringEnds, thickness, color)
+    }
+
+    override fun drawImage(
+        src: String, x: Float, y: Float, w: Float, h: Float,
+        radius: Float, flipH: Boolean, flipV: Boolean,
+    ) {
+        bump("drawImage")
+        if (flipH || flipV) bump("mirroredImage")
+        inner.drawImage(src, x, y, w, h, radius, flipH, flipV)
+    }
+
+    override fun drawTextRun(
+        text: String, x: Float, top: Float, sizePx: Float,
+        family: String, bold: Boolean, italic: Boolean, color: Int,
+    ) {
+        bump("drawTextRun")
+        if (bold) bump("boldText")
+        if (italic) bump("italicText")
+        // A run outside the Latin block is what tells you the TrueType reader
+        // and the face pool are doing something rather than getting lucky.
+        if (text.any { it.code > 127 }) bump("nonAsciiText")
+        inner.drawTextRun(text, x, top, sizePx, family, bold, italic, color)
+    }
+}

package/dist/lib/evg/apple/README.md

@@ -0,0 +1,128 @@
+# `lib/evg/apple` — the EVG display list, painted with CoreGraphics
+
+**License: AGPL-3.0-or-later** (Gallery).
+
+The Apple sibling of [`lib/evg/android`](../android/README.md), and
+deliberately the same shape: an `EvgSurface` protocol of eight drawing calls,
+one `EvgPainter` that decides what each display-list command *means*, and a
+backend per drawing API.
+
+There is only one backend here, and that is the point. A `UIView` hands out a
+`CGContext` from `UIGraphicsGetCurrentContext()`; a SwiftUI `Canvas` hands one
+out from `GraphicsContext.withCGContext`; a bitmap or a PDF context is the same
+object again. So an iPhone, an iPad, an Apple Watch and an off-screen render all
+paint through `CoreGraphicsEvgSurface`, not through four surfaces that have to
+be kept in step.
+
+```
+   EVGDisplayList                    (Ranger, compiled to Swift)
+         │
+   EvgPainter.paint(list, into:)     what a command MEANS — written once
+         │
+   EvgSurface                        eight calls, and nothing else
+         │
+         ├── CoreGraphicsEvgSurface  CGContext   ← UIKit, SwiftUI, watchOS
+         └── RecordingSurface        counts what was dispatched
+```
+
+| File | Lines | What it is |
+| --- | --- | --- |
+| `Sources/EvgSurface.swift` | 163 | The protocol, and the colour/gradient/shadow types it takes |
+| `Sources/EvgPainter.swift` | 213 | The walk: a display list in, surface calls out |
+| `Sources/CoreGraphicsEvgSurface.swift` | 291 | Boxes, borders, paths, images and CoreText, on a `CGContext` |
+| `Sources/RecordingSurface.swift` | 110 | Draws nothing, counts everything |
+| `Sources/CoreTextMeasurer.swift` | 70 | CoreText measures the text the layout is made with — the same `CTFont` the surface draws with |
+| `Sources/EvgEngineQueue.swift` | 110 | The engine on its own serial queue: `post`, `ask`, `sync`, and frames coalesced and delivered to the main thread |
+
+## What the painter is careful about
+
+`EvgPainter` is a transliteration of the Kotlin one rather than a second reading
+of the format. Where the two disagree, one of them is wrong. Four things it
+carries that a JSON-fed backend cannot:
+
+* **Gradients and shadows.** `EVGDisplayList.toJson` carries neither, so a
+  browser host cannot draw them. Reading the objects directly brings both back.
+* **Clipping.** `save`/`clipRect`/`restore`, with a depth counter: a list that
+  pushes more clips than it pops must not leave the surface clipped for the rest
+  of the frame, and one that pops more than it pushes must not restore past the
+  state the host handed over. On CoreGraphics the first of those is a page with
+  most of it missing.
+* **Multi-ring paths.** `ringEnds` gives the index one past each ring's last
+  coordinate, so a shape with a hole is one path with two subpaths and a real
+  even-odd fill.
+* **Rotation about a command's own box centre**, wrapped in save/restore so the
+  clip stack above is untouched.
+
+## Three things CoreGraphics needs that Skia did not
+
+**Text is upside down unless you say otherwise.** The context is flipped —
+origin top left, y down, which is what UIKit and SwiftUI both hand you and what
+the display list is already in — and CoreText draws glyphs the other way up.
+`ctx.textMatrix = CGAffineTransform(scaleX: 1, y: -1)` is the fix, and it is one
+line in exactly one place.
+
+**`top` is not the baseline.** EVG measured the run and the baseline sits one
+face-ascent below the top of the line box. `CTFontGetAscent` is where that comes
+from, and the surface owns the conversion because only it knows what its own
+metrics say.
+
+**A border is a band INSIDE the box.** A CoreGraphics stroke straddles its path,
+so `strokeRect` insets by half the thickness and shrinks the corner radius to
+match. Without it a one-point hairline spills over the edge of a clipped scroll
+region.
+
+## Fonts
+
+`CTFont`, not `UIFont`: CoreText exists on every Apple platform including
+watchOS, so this is the same file there. The family name from the display list
+picks between a monospace face, a serif and the platform's own sans; bold and
+italic go through `CTFontCreateCopyWithSymbolicTraits`.
+
+No font files are bundled, and none are needed for the layout to be honest:
+`CoreTextMeasurer.install()` — one stored property in each host, declared
+above the app so it runs first — hands EVG's `EVGHostTextMeasurer` a function
+that measures a run with the SAME `CTFont` `EvgFontCache` gives the surface,
+`CTLineGetTypographicBounds` and all. So the page is laid out with the face it
+is drawn with, rather than with the table it used to guess from. The pptx port
+still bundles the deck's own faces, for the opposite reason: a deck is measured
+against the faces it was authored in.
+
+## What is checked, and where
+
+Nothing in this directory is compiled by this repository's CI, because Swift for
+Apple platforms needs a Mac. What IS checked, on any machine, is everything the
+painter is handed:
+[`gallery/ui/ios/ranger/check_ios.rgr`](../../../gallery/ui/ios/ranger/check_ios.rgr)
+asserts that the page reaches text, filled boxes, borders, rounded corners,
+clipping, a filled path and stroked paths — and that every clip pushed is
+popped, which is the invariant this painter exists to keep.
+
+`RecordingSurface` is the Mac-side half of that: wrap the real surface in one,
+paint a frame, and the tally says what the **painter** dispatched rather than
+what the page produced.
+
+## Scroll layers, and what this painter does not do yet
+
+A clip that can scroll arrives with `layer` set on its PUSH_CLIP — see
+`EVGDisplayList.refreshLayers`. An app that keeps its list across a scroll
+hands the painter the SAME list, with the commands inside that clip already
+moved to where the scroll put them, so this painter draws the right frame
+without knowing a layer from any other clip. What the host saves is the
+layout and the list build; what it still pays is rasterising every command
+in the layer, every frame.
+
+The next step, when a long page on a phone asks for it, is the one the
+browser painter took: keep what was made from the layer. Here that is a
+`CGLayer` (or a bitmap) the size of the layer's range, painted once per
+`buildSeq`, and blitted per frame at the layer's clip with
+`layerShiftX/Y` subtracted from the shift it was painted at — a scroll
+frame is then one `draw(layer, at:)` under the clip and the commands
+outside the layer. The list's `layerFirst`/`layerLast` give the command
+range; nothing else in the list has to change.
+
+## Related
+
+* [`lib/evg/android`](../android/README.md) — the same interface over
+  `android.graphics.Canvas` and `java.awt.Graphics2D`
+* [`gallery/ui/ios`](../../../gallery/ui/ios/README.md) — the dashboard demo through this
+  painter, on iPhone, iPad and Apple Watch