ranger-compiler 3.5.0 → 3.5.2

package/dist/lib/evg/apple/Sources/CoreGraphicsEvgSurface.swift

@@ -0,0 +1,329 @@
+// SPDX-License-Identifier: MIT
+//
+// The display list, painted with CoreGraphics.
+//
+// One backend for every Apple platform, on purpose. A `UIView` hands out a
+// `CGContext` from `UIGraphicsGetCurrentContext()`, a SwiftUI `Canvas` hands
+// one out from `GraphicsContext.withCGContext`, and a PDF or a bitmap context
+// is the same object again — so an iPhone, an iPad, an Apple Watch and an
+// off-screen render all go through this file rather than through four.
+//
+// The context is assumed FLIPPED: origin top left, y increasing downwards,
+// which is what UIKit and SwiftUI both hand you and what the display list is
+// already in. The one place that has to know is the text, because CoreText
+// draws glyphs the other way up unless the text matrix says otherwise.
+//
+// Text is CoreText rather than UIKit for one reason: `CTFont` exists on every
+// Apple platform including watchOS, and this file is the same file there.
+
+import CoreGraphics
+import CoreText
+import Foundation
+
+/// Faces, kept for the life of the process rather than the life of a surface.
+///
+/// A surface wraps the `CGContext` the system hands to `draw(_:)`, and that is
+/// a different object every frame — so a surface is made per frame, and a cache
+/// owned by one is a cache thrown away sixty times a second. That is exactly
+/// what the cache exists to prevent: a page draws around 190 text runs a frame
+/// and asks for about six distinct faces, and `CTFontCreateUIFontForLanguage`
+/// plus `CTFontCreateCopyWithSymbolicTraits` are not cheap enough to run per
+/// run. Tapping a tab took most of a second on a phone with this cache being
+/// discarded.
+///
+/// A `CTFont` is immutable and safe to share. The lock is here because the type
+/// is `Sendable` by assertion and a future host may paint off the main thread;
+/// it is uncontended in the one-thread case that actually happens.
+final class EvgFontCache: @unchecked Sendable {
+
+    static let shared = EvgFontCache()
+
+    private var faces: [String: CTFont] = [:]
+    private let lock = NSLock()
+
+    func face(size: CGFloat, family: String, bold: Bool, italic: Bool) -> CTFont {
+        let key = "\(family)|\(size)|\(bold)|\(italic)"
+        lock.lock()
+        if let cached = faces[key] {
+            lock.unlock()
+            return cached
+        }
+        lock.unlock()
+
+        let made = EvgFontCache.make(size: size, family: family, bold: bold, italic: italic)
+        lock.lock()
+        faces[key] = made
+        lock.unlock()
+        return made
+    }
+
+    private static func make(size: CGFloat, family: String, bold: Bool, italic: Bool) -> CTFont {
+        let lower = family.lowercased()
+        var base: CTFont
+        if lower.contains("mono") || lower.contains("courier") || lower.contains("consol") {
+            base = CTFontCreateWithName("Menlo" as CFString, size, nil)
+        } else if lower.contains("serif") && !lower.contains("sans") {
+            base = CTFontCreateWithName("Georgia" as CFString, size, nil)
+        } else {
+            // The platform's own sans. `gallery/ui` lays out with EVG's width
+            // estimate rather than a face, exactly as the browser build does,
+            // so bundling a TrueType file here would make the picture *less*
+            // like the one the demo is checked against, not more.
+            base = CTFontCreateUIFontForLanguage(.system, size, nil)
+                ?? CTFontCreateWithName("Helvetica" as CFString, size, nil)
+        }
+
+        var traits: CTFontSymbolicTraits = []
+        if bold { traits.insert(.traitBold) }
+        if italic { traits.insert(.traitItalic) }
+        if !traits.isEmpty {
+            if let styled = CTFontCreateCopyWithSymbolicTraits(base, size, nil, traits, traits) {
+                base = styled
+            }
+        }
+        return base
+    }
+}
+
+final class CoreGraphicsEvgSurface: EvgSurface {
+
+    private let ctx: CGContext
+
+    init(context: CGContext) {
+        self.ctx = context
+    }
+
+    // MARK: - state
+
+    func save() {
+        ctx.saveGState()
+    }
+
+    func restore() {
+        ctx.restoreGState()
+    }
+
+    func clipRect(x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat) {
+        ctx.clip(to: CGRect(x: x, y: y, width: w, height: h))
+    }
+
+    func rotate(degrees: CGFloat, px: CGFloat, py: CGFloat) {
+        ctx.translateBy(x: px, y: py)
+        ctx.rotate(by: degrees * .pi / 180.0)
+        ctx.translateBy(x: -px, y: -py)
+    }
+
+    // MARK: - boxes
+
+    private func boxPath(x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat, radius: CGFloat) -> CGPath {
+        let rect = CGRect(x: x, y: y, width: w, height: h)
+        if radius <= 0.0 {
+            return CGPath(rect: rect, transform: nil)
+        }
+        // A radius larger than half the box is a pill, and CoreGraphics draws
+        // something wrong rather than a pill if it is not clamped.
+        let r = min(radius, min(w, h) * 0.5)
+        return CGPath(roundedRect: rect, cornerWidth: r, cornerHeight: r, transform: nil)
+    }
+
+    private func applyShadow(_ shadow: EvgShadow?) {
+        guard let s = shadow else { return }
+        ctx.setShadow(offset: CGSize(width: s.dx, height: s.dy), blur: s.blur, color: s.color.cgColor)
+    }
+
+    func fillRect(
+        x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat,
+        radius: CGFloat,
+        color: EvgColor,
+        gradient: EvgGradient?,
+        shadow: EvgShadow?
+    ) {
+        if w <= 0 || h <= 0 { return }
+        let path = boxPath(x: x, y: y, w: w, h: h, radius: radius)
+
+        guard let grad = gradient else {
+            ctx.saveGState()
+            applyShadow(shadow)
+            ctx.addPath(path)
+            ctx.setFillColor(color.cgColor)
+            ctx.fillPath()
+            ctx.restoreGState()
+            return
+        }
+
+        // A gradient cannot be a fill colour, so the shape becomes a clip and
+        // the gradient is drawn through it. The shadow is the SHAPE's, not the
+        // gradient's, so it is painted first as a flat fill of the first stop —
+        // a gradient box under a shadow casts the box's silhouette.
+        if shadow != nil {
+            ctx.saveGState()
+            applyShadow(shadow)
+            ctx.addPath(path)
+            ctx.setFillColor(grad.color1.cgColor)
+            ctx.fillPath()
+            ctx.restoreGState()
+        }
+
+        ctx.saveGState()
+        ctx.addPath(path)
+        ctx.clip()
+        let space = CGColorSpaceCreateDeviceRGB()
+        let colors = [grad.color1.cgColor, grad.color2.cgColor] as CFArray
+        if let cg = CGGradient(colorsSpace: space, colors: colors, locations: [0.0, 1.0]) {
+            let start = CGPoint(x: x, y: y)
+            let end = grad.vertical ? CGPoint(x: x, y: y + h) : CGPoint(x: x + w, y: y)
+            ctx.drawLinearGradient(cg, start: start, end: end, options: [.drawsBeforeStartLocation, .drawsAfterEndLocation])
+        }
+        ctx.restoreGState()
+    }
+
+    func strokeRect(
+        x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat,
+        radius: CGFloat, thickness: CGFloat,
+        color: EvgColor
+    ) {
+        if w <= 0 || h <= 0 { return }
+        // EVG's border is a band INSIDE the box, and a CoreGraphics stroke
+        // straddles the path. Insetting by half the thickness puts the band
+        // where the layout said it was — which is what keeps a one-point
+        // hairline from spilling over the edge of a clipped scroll region.
+        let half = thickness * 0.5
+        let inset = CGRect(x: x + half, y: y + half, width: max(0, w - thickness), height: max(0, h - thickness))
+        let r = radius > 0 ? max(0, min(radius - half, min(inset.width, inset.height) * 0.5)) : 0
+        let path = r > 0
+            ? CGPath(roundedRect: inset, cornerWidth: r, cornerHeight: r, transform: nil)
+            : CGPath(rect: inset, transform: nil)
+        ctx.saveGState()
+        ctx.addPath(path)
+        ctx.setStrokeColor(color.cgColor)
+        ctx.setLineWidth(thickness)
+        ctx.strokePath()
+        ctx.restoreGState()
+    }
+
+    // MARK: - vector outlines
+
+    /// `pts` is flat — x, y, x, y — and `ringEnds` holds the index one past
+    /// each ring's last coordinate, so a shape with a hole arrives as two
+    /// rings and is filled as one path with two subpaths.
+    private func buildPath(pts: [Double], ringEnds: [Int], close: Bool) -> CGPath {
+        let path = CGMutablePath()
+        var start = 0
+        for rawEnd in ringEnds {
+            let end = min(rawEnd, pts.count)
+            if end - start >= 4 {
+                path.move(to: CGPoint(x: pts[start], y: pts[start + 1]))
+                var i = start + 2
+                while i + 1 < end {
+                    path.addLine(to: CGPoint(x: pts[i], y: pts[i + 1]))
+                    i += 2
+                }
+                if close { path.closeSubpath() }
+            }
+            start = max(start, end)
+        }
+        return path
+    }
+
+    func fillPath(
+        pts: [Double], ringEnds: [Int], evenOdd: Bool,
+        color: EvgColor,
+        shadow: EvgShadow?
+    ) {
+        let path = buildPath(pts: pts, ringEnds: ringEnds, close: true)
+        if path.isEmpty { return }
+        ctx.saveGState()
+        applyShadow(shadow)
+        ctx.addPath(path)
+        ctx.setFillColor(color.cgColor)
+        if evenOdd {
+            ctx.fillPath(using: .evenOdd)
+        } else {
+            ctx.fillPath(using: .winding)
+        }
+        ctx.restoreGState()
+    }
+
+    func strokePath(
+        pts: [Double], ringEnds: [Int],
+        thickness: CGFloat,
+        color: EvgColor
+    ) {
+        // Not closed: a stroked ring in this page is an icon outline or the
+        // chart's line, and closing it would draw a chord from the last point
+        // back to the first one.
+        let path = buildPath(pts: pts, ringEnds: ringEnds, close: false)
+        if path.isEmpty { return }
+        ctx.saveGState()
+        ctx.addPath(path)
+        ctx.setStrokeColor(color.cgColor)
+        ctx.setLineWidth(thickness)
+        ctx.setLineJoin(.round)
+        ctx.setLineCap(.round)
+        ctx.strokePath()
+        ctx.restoreGState()
+    }
+
+    // MARK: - images
+
+    /// This page reaches no images, and a surface that drew nothing for one
+    /// would be indistinguishable from a surface that drew it wrong. A visible
+    /// placeholder is the honest answer until an image cache is wired in.
+    func drawImage(
+        src: String,
+        x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat,
+        radius: CGFloat,
+        flipH: Bool, flipV: Bool
+    ) {
+        if w <= 0 || h <= 0 { return }
+        let path = boxPath(x: x, y: y, w: w, h: h, radius: radius)
+        ctx.saveGState()
+        ctx.addPath(path)
+        ctx.setFillColor(EvgColor(r: 220, g: 220, b: 226, a: 1.0).cgColor)
+        ctx.fillPath()
+        ctx.addPath(path)
+        ctx.setStrokeColor(EvgColor(r: 150, g: 150, b: 160, a: 1.0).cgColor)
+        ctx.setLineWidth(1.0)
+        ctx.strokePath()
+        ctx.move(to: CGPoint(x: x, y: y))
+        ctx.addLine(to: CGPoint(x: x + w, y: y + h))
+        ctx.strokePath()
+        ctx.restoreGState()
+    }
+
+    // MARK: - text
+
+    private func fontFor(size: CGFloat, family: String, bold: Bool, italic: Bool) -> CTFont {
+        EvgFontCache.shared.face(size: size, family: family, bold: bold, italic: italic)
+    }
+
+    func drawTextRun(
+        text: String,
+        x: CGFloat, top: CGFloat,
+        sizePx: CGFloat,
+        family: String, bold: Bool, italic: Bool,
+        color: EvgColor
+    ) {
+        if text.isEmpty || sizePx <= 0 { return }
+        let font = fontFor(size: sizePx, family: family, bold: bold, italic: italic)
+        // CoreText's own attribute names, spelled the long way round.
+        // `kCTFontAttributeName` is a `CFString`; `NSAttributedString.Key` is
+        // not, and UIKit's `.foregroundColor` is a DIFFERENT string that
+        // CoreText does not read.
+        let attributes: [NSAttributedString.Key: Any] = [
+            NSAttributedString.Key(kCTFontAttributeName as String): font,
+            NSAttributedString.Key(kCTForegroundColorAttributeName as String): color.cgColor,
+        ]
+        let line = CTLineCreateWithAttributedString(
+            NSAttributedString(string: text, attributes: attributes)
+        )
+        ctx.saveGState()
+        // `top` is the top of the line box; the baseline is one ascent below
+        // it. And the text matrix is flipped because the context is: without
+        // it CoreText draws every glyph upside down in a UIKit context.
+        ctx.textMatrix = CGAffineTransform(scaleX: 1.0, y: -1.0)
+        ctx.textPosition = CGPoint(x: x, y: top + CTFontGetAscent(font))
+        CTLineDraw(line, ctx)
+        ctx.restoreGState()
+    }
+}

package/dist/lib/evg/apple/Sources/CoreTextMeasurer.swift

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: MIT
+//
+// CoreText measures, EVG breaks the lines.
+//
+// PLAN_NATIVE_HOSTS.md S0, the Apple half. `EVGHostTextMeasurer` (Ranger,
+// compiled into the app's generated Swift) takes ONE function from the
+// platform — a run's width, and a face's ascent, descent and leading — and
+// every layout the app builds then measures with it. Before this the layout
+// measured with the advance table, a snapshot of one browser's sans, and
+// `CoreGraphicsEvgSurface` drew with whatever `EvgFontCache` resolved: two
+// faces, and a caret or a label's box placed from the wrong one.
+//
+// The face is the SAME `CTFont` the surface draws with — `EvgFontCache.shared`
+// is asked with the same four arguments `drawTextRun` asks it with — so the
+// width the layout measured is the width `CTLineDraw` puts on the screen.
+// `CTLineGetTypographicBounds` is the advance CoreText itself lays the line
+// out to, kerning and all, which is what makes this exact rather than close.
+//
+// Install once, before the app's `start`, on any thread: `CTFont` is
+// immutable and the cache is locked, so the layout may run off the main
+// actor (S1) and measure where it lays out.
+//
+// Nothing here is compiled by this repository's CI — Swift for Apple needs a
+// Mac — which is the same standing as the rest of this directory.
+
+import CoreGraphics
+import CoreText
+import Foundation
+
+enum CoreTextMeasurer {
+
+    /// Make the measurer, attach CoreText to it and make it the default every
+    /// `EVGLayout` and `EVGTextEngine` in the process starts from.
+    ///
+    /// Idempotent in effect: a second call installs a second measurer, which
+    /// answers the same numbers from the same cache.
+    @discardableResult
+    static func install() -> EVGHostTextMeasurer {
+        let measurer = EVGHostTextMeasurer()
+        measurer.attach(f: metric, name: "coretext")
+        EVGDefaultMeasurer.install(m: measurer)
+        return measurer
+    }
+
+    /// The one function. `kind` 0 is the width of `text`; 1, 2 and 3 are the
+    /// face's ascent, descent and leading, for which `text` is empty.
+    static func metric(_ kind: Int, _ text: String, _ family: String,
+                       _ size: Double, _ bold: Bool, _ italic: Bool) -> Double {
+        let font = EvgFontCache.shared.face(size: CGFloat(size), family: family, bold: bold, italic: italic)
+        switch kind {
+        case 0:
+            if text.isEmpty { return 0 }
+            let attributes: [NSAttributedString.Key: Any] = [
+                NSAttributedString.Key(kCTFontAttributeName as String): font,
+            ]
+            let line = CTLineCreateWithAttributedString(
+                NSAttributedString(string: text, attributes: attributes)
+            )
+            return CTLineGetTypographicBounds(line, nil, nil, nil)
+        case 1:
+            return Double(CTFontGetAscent(font))
+        case 2:
+            return Double(CTFontGetDescent(font))
+        default:
+            // The face's own line gap. `line-height: normal` is ascent +
+            // descent + this, which is what CoreText's own layout uses too.
+            return Double(CTFontGetLeading(font))
+        }
+    }
+}

package/dist/lib/evg/apple/Sources/EvgEngineQueue.swift

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: MIT
+//
+// The engine off the main thread — Apple.
+//
+// PLAN_NATIVE_HOSTS.md S1. A Ranger app compiled to Swift is a value: no
+// UIKit in it, no view, nothing that has to be on the main actor. What has
+// to be on the main actor is the view that receives touches and the context
+// that paints. So the app lives on ONE serial queue, 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 the queue — that is
+// handed to the main 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 in … }            run there; return true if a frame is owed
+//   ask({ app in … }) { v in … } run there; answer on the main thread
+//   sync { app in … }            run there and WAIT — for the one read UIKit
+//                                insists on synchronously (`canBecomeFirstResponder`)
+//
+// 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 that is asked for
+// while one is running produces exactly one more when it finishes — never a
+// queue of stale frames the main thread has to draw through.
+//
+// `Frame` is whatever the host paints from: the display list alone, or the
+// list with the viewport numbers the painter needs beside it, read on the
+// queue so the main thread reads the app for nothing.
+
+import Foundation
+
+final class EvgEngineQueue<App, Frame> {
+
+    private let queue = DispatchQueue(label: "fi.ranger.evg.engine", qos: .userInteractive)
+    private let app: App
+    private let build: (App) -> Frame
+    private let deliver: (Frame) -> Void
+
+    // Touched on the queue only.
+    private var building = false
+    private var wanted = false
+
+    /// - Parameters:
+    ///   - app: the Ranger app; make it BEFORE this, and never read it again
+    ///     from the main thread
+    ///   - build: the frame, run on the queue — `app.frame()` and whatever
+    ///     the painter needs beside it
+    ///   - deliver: called on the MAIN thread with each built frame; keep it
+    ///     and `setNeedsDisplay`
+    init(app: App, build: @escaping (App) -> Frame, deliver: @escaping (Frame) -> Void) {
+        self.app = app
+        self.build = build
+        self.deliver = deliver
+    }
+
+    /// Run `work` on the engine queue. A `true` result asks for a frame.
+    func post(_ work: @escaping (App) -> Bool) {
+        queue.async { [self] in
+            if work(app) { requestFrameOnQueue() }
+        }
+    }
+
+    /// Run `work` on the engine queue and hand its answer to `then` on the
+    /// main thread.
+    func ask<T>(_ work: @escaping (App) -> T, then: @escaping (T) -> Void) {
+        queue.async { [self] in
+            let v = work(app)
+            DispatchQueue.main.async { then(v) }
+        }
+    }
+
+    /// Run `work` on the engine queue and wait for it. For the reads UIKit
+    /// asks for synchronously and nothing else: it holds the caller for as
+    /// long as whatever is already on the queue takes.
+    func sync<T>(_ work: (App) -> T) -> T {
+        return queue.sync { work(app) }
+    }
+
+    /// A frame is owed — the clock ticked, the window resized.
+    func invalidate() {
+        queue.async { [self] in requestFrameOnQueue() }
+    }
+
+    // On the queue.
+    private func requestFrameOnQueue() {
+        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.
+        queue.async { [self] in buildOnQueue() }
+    }
+
+    private func buildOnQueue() {
+        let f = build(app)
+        DispatchQueue.main.async { [self] in deliver(f) }
+        building = false
+        if wanted {
+            wanted = false
+            requestFrameOnQueue()
+        }
+    }
+}