ranger-compiler 3.5.1 → 3.5.2

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

@@ -0,0 +1,225 @@
+// SPDX-License-Identifier: MIT
+//
+// The walk: an `EVGDisplayList` in, calls on an `EvgSurface` out.
+//
+// Android and Apple differ in how they fill a rounded box, not in what a
+// command *means*, so what a command means is decided exactly once — here —
+// and this file is a transliteration of `lib/evg/android`'s `EvgPainter`
+// rather than a second reading of the format. Where the two disagree, one of
+// them is wrong.
+//
+// Two things this painter honours that a JSON-fed backend cannot:
+//
+//  * **Gradients and shadows.** `EVGDisplayList.toJson` carries neither, so a
+//    browser host cannot draw them. Reading the objects directly — which is
+//    what a Swift host can do — brings both back.
+//  * **Clipping and multi-ring paths.** `save`/`clipRect`/`restore` and a real
+//    even-odd fill are one line each on CoreGraphics.
+
+import CoreGraphics
+
+enum EvgPainter {
+
+    private static let RECT = 0
+    private static let BORDER = 1
+    private static let IMAGE = 2
+    private static let TEXT = 3
+    private static let PUSH_CLIP = 4
+    private static let POP_CLIP = 5
+    private static let PATH = 6
+    private static let STROKE = 7
+
+    /// Anything below this is invisible; drawing it is work for nothing.
+    private static let MIN_ALPHA = 0.001
+
+    /// Paint every command in order. Answers how many were actually drawn,
+    /// which is what a host puts in a debug overlay — a frame that draws 0 of
+    /// 350 commands is a bug you want to see rather than a black screen.
+    @discardableResult
+    static func paint(_ list: EVGDisplayList, into 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
+        let n = list.count()
+        var i = 0
+        while i < n {
+            let c = list.at(i: i)
+            i += 1
+
+            if c.kind == PUSH_CLIP {
+                surface.save()
+                surface.clipRect(
+                    x: CGFloat(c.x), y: CGFloat(c.y),
+                    w: CGFloat(c.w), h: CGFloat(c.h)
+                )
+                clipDepth += 1
+                continue
+            }
+            if c.kind == POP_CLIP {
+                if clipDepth > 0 {
+                    surface.restore()
+                    clipDepth -= 1
+                }
+                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.
+            let turned = c.rotate > 0.001 || c.rotate < -0.001
+            if turned {
+                surface.save()
+                surface.rotate(
+                    degrees: CGFloat(c.rotate),
+                    px: c.hasRotOrigin ? CGFloat(c.rotOriginX) : CGFloat(c.x + c.w * 0.5),
+                    py: c.hasRotOrigin ? CGFloat(c.rotOriginY) : CGFloat(c.y + c.h * 0.5)
+                )
+            }
+
+            if drawOne(c, surface) { drawn += 1 }
+
+            if turned { surface.restore() }
+        }
+        while clipDepth > 0 {
+            surface.restore()
+            clipDepth -= 1
+        }
+        return drawn
+    }
+
+    private static func drawOne(_ c: EVGDrawCmd, _ surface: EvgSurface) -> Bool {
+        switch c.kind {
+        case RECT:
+            let shadow = shadowOf(c)
+            let gradient = gradientOf(c)
+            if c.a < MIN_ALPHA && gradient == nil && shadow == nil { return false }
+            surface.fillRect(
+                x: CGFloat(c.x), y: CGFloat(c.y), w: CGFloat(c.w), h: CGFloat(c.h),
+                radius: CGFloat(c.radius),
+                color: colorOf(c),
+                gradient: gradient,
+                shadow: shadow
+            )
+            return true
+
+        case 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.
+            let t = c.thickness > 0.0 ? CGFloat(c.thickness) : 1.0
+            surface.strokeRect(
+                x: CGFloat(c.x), y: CGFloat(c.y), w: CGFloat(c.w), h: CGFloat(c.h),
+                radius: CGFloat(c.radius), thickness: t,
+                color: colorOf(c)
+            )
+            return true
+
+        case IMAGE:
+            if c.src.isEmpty { return false }
+            surface.drawImage(
+                src: c.src,
+                x: CGFloat(c.x), y: CGFloat(c.y), w: CGFloat(c.w), h: CGFloat(c.h),
+                radius: CGFloat(c.radius),
+                flipH: c.flipH, flipV: c.flipV
+            )
+            return true
+
+        case TEXT:
+            if c.text.isEmpty { return false }
+            if c.a < MIN_ALPHA { return false }
+            surface.drawTextRun(
+                text: c.text,
+                x: CGFloat(c.x), top: CGFloat(c.y),
+                sizePx: CGFloat(c.fontSize),
+                family: c.fontFamily,
+                bold: 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.
+                italic: c.textAlign == "italic",
+                color: colorOf(c)
+            )
+            return true
+
+        case PATH:
+            if c.a < MIN_ALPHA { return false }
+            if c.pts.count < 6 { return false }
+            surface.fillPath(
+                pts: c.pts, ringEnds: ringsOf(c), evenOdd: c.evenOdd,
+                color: colorOf(c), shadow: shadowOf(c)
+            )
+            return true
+
+        case STROKE:
+            if c.a < MIN_ALPHA { return false }
+            if c.pts.count < 4 { return false }
+            let t = c.thickness > 0.0 ? CGFloat(c.thickness) : 1.0
+            surface.strokePath(
+                pts: c.pts, ringEnds: ringsOf(c), thickness: t, color: colorOf(c)
+            )
+            return true
+
+        default:
+            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 static func ringsOf(_ c: EVGDrawCmd) -> [Int] {
+        c.ringEnds.isEmpty ? [c.pts.count] : c.ringEnds
+    }
+
+    private static func gradientOf(_ c: EVGDrawCmd) -> EvgGradient? {
+        if !c.hasGrad { return nil }
+        return EvgGradient(
+            color1: EvgColor(r: c.r, g: c.g, b: c.b, a: c.a),
+            color2: EvgColor(r: c.r2, g: c.g2, b: c.b2, a: c.a2),
+            // dir 0 = vertical (top to bottom), 1 = horizontal (left to right)
+            vertical: c.gradDir != 1
+        )
+    }
+
+    private static func shadowOf(_ c: EVGDrawCmd) -> EvgShadow? {
+        if !c.hasShadow { return nil }
+        if c.shadowA < MIN_ALPHA { return nil }
+        return EvgShadow(
+            dx: CGFloat(c.shadowX),
+            dy: CGFloat(c.shadowY),
+            blur: CGFloat(c.shadowBlur),
+            color: EvgColor(r: c.shadowR, g: c.shadowG, b: c.shadowB, a: c.shadowA)
+        )
+    }
+
+    private static func colorOf(_ c: EVGDrawCmd) -> EvgColor {
+        EvgColor(r: c.r, g: c.g, b: c.b, a: c.a)
+    }
+
+    /// 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.
+    static func isBold(_ weight: String) -> Bool {
+        if weight.isEmpty { return false }
+        if weight == "bold" || weight == "bolder" { return true }
+        guard let n = Int(weight) else { return false }
+        return n >= 600
+    }
+}

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

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: MIT
+//
+// 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:
+// `CoreGraphicsEvgSurface` paints with a `CGContext` (so a `UIView` on iOS and
+// a SwiftUI `Canvas` on watchOS share one implementation), `RecordingSurface`
+// counts what was dispatched without drawing anything, and the walk that
+// decides what each command *means* — `EvgPainter` — is written once.
+//
+// This is the Apple sibling of `lib/evg/android`, and the interface is
+// deliberately the same one: a port that diverges here would make the two
+// painters two programs to keep in step rather than one idea with two
+// backends.
+//
+// Geometry is in the app's own points. A host that wants device pixels scales
+// its context and leaves these numbers alone — text then rasterises at the
+// panel's real resolution instead of being blown up from a bitmap made at some
+// other size.
+
+import CoreGraphics
+
+/// A colour as the display list carries it: 0-255 channels and a 0-1 alpha.
+struct EvgColor {
+    let r: Int
+    let g: Int
+    let b: Int
+    let a: Double
+
+    init(r: Int, g: Int, b: Int, a: Double) {
+        self.r = r
+        self.g = g
+        self.b = b
+        self.a = a
+    }
+
+    private static func clamp255(_ v: Int) -> CGFloat {
+        if v < 0 { return 0 }
+        if v > 255 { return 1 }
+        return CGFloat(v) / 255.0
+    }
+
+    var cgColor: CGColor {
+        let alpha = a < 0 ? 0 : (a > 1 ? 1 : a)
+        return CGColor(
+            srgbRed: EvgColor.clamp255(r),
+            green: EvgColor.clamp255(g),
+            blue: EvgColor.clamp255(b),
+            alpha: CGFloat(alpha)
+        )
+    }
+
+    /// The same colour with the alpha replaced, for a shadow that carries its
+    /// own.
+    func withAlpha(_ alpha: Double) -> EvgColor {
+        EvgColor(r: r, g: g, b: b, a: alpha)
+    }
+}
+
+/// A two-stop linear gradient. `vertical` is EVG's `gradDir == 0`.
+struct EvgGradient {
+    let color1: EvgColor
+    let color2: EvgColor
+    let vertical: Bool
+
+    init(color1: EvgColor, color2: EvgColor, vertical: Bool) {
+        self.color1 = color1
+        self.color2 = color2
+        self.vertical = vertical
+    }
+}
+
+/// An outer drop shadow: offset, blur radius, colour.
+struct EvgShadow {
+    let dx: CGFloat
+    let dy: CGFloat
+    let blur: CGFloat
+    let color: EvgColor
+
+    init(dx: CGFloat, dy: CGFloat, blur: CGFloat, color: EvgColor) {
+        self.dx = dx
+        self.dy = dy
+        self.blur = blur
+        self.color = color
+    }
+}
+
+protocol EvgSurface: AnyObject {
+
+    /// Push the clip/transform stack. Paired with `restore`.
+    func save()
+
+    /// Pop back to the state the matching `save` recorded.
+    func restore()
+
+    /// Intersect the clip with this rectangle. Only ever inside a `save`.
+    func clipRect(x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat)
+
+    /// Turn the coordinate system `degrees` about (`px`, `py`).
+    func rotate(degrees: CGFloat, px: CGFloat, py: CGFloat)
+
+    /// 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.
+    func fillRect(
+        x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat,
+        radius: CGFloat,
+        color: EvgColor,
+        gradient: EvgGradient?,
+        shadow: EvgShadow?
+    )
+
+    /// A stroked outline, drawn as a band of `thickness` INSIDE the box.
+    func strokeRect(
+        x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat,
+        radius: CGFloat, thickness: CGFloat,
+        color: EvgColor
+    )
+
+    /// 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.
+    func fillPath(
+        pts: [Double], ringEnds: [Int], evenOdd: Bool,
+        color: EvgColor,
+        shadow: EvgShadow?
+    )
+
+    /// The same rings, stroked rather than filled.
+    func strokePath(
+        pts: [Double], ringEnds: [Int],
+        thickness: CGFloat,
+        color: EvgColor
+    )
+
+    /// A picture, by the name the page gave it. A surface that has no bytes for
+    /// `src` should draw the placeholder rather than nothing — a missing
+    /// texture and a blank card look identical otherwise.
+    func drawImage(
+        src: String,
+        x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat,
+        radius: CGFloat,
+        flipH: Bool, flipV: Bool
+    )
+
+    /// One run, on one line, in one face.
+    ///
+    /// `top` is the top of the LINE BOX, not the baseline: EVG measured the run
+    /// with its own width estimate 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 points 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.
+    func drawTextRun(
+        text: String,
+        x: CGFloat, top: CGFloat,
+        sizePx: CGFloat,
+        family: String, bold: Bool, italic: Bool,
+        color: EvgColor
+    )
+}

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

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: MIT
+//
+// A surface that draws nothing and counts everything.
+//
+// Wrap a real surface in one of these and the frame is painted exactly as it
+// would be, with a tally of what was dispatched on the other side. "Some ink
+// appeared" is a weak check — a painter that had quietly stopped drawing text
+// would pass it — so a check asserts the counts instead: this page reaches
+// text, filled boxes, borders, rounded corners, clipping, a filled path and
+// stroked paths, and every `save` is matched by a `restore`.
+//
+// The Ranger side of this port counts the same things one step earlier, on the
+// display list itself (`gallery/ui/ios/ranger/check_ios.rgr`), because that can
+// run without a Mac. This is for the half that cannot: it says whether the
+// PAINTER dispatched them, not merely whether the page produced them.
+
+import CoreGraphics
+
+final class RecordingSurface: EvgSurface {
+
+    private(set) var calls: [String: Int] = [:]
+    private let inner: EvgSurface?
+
+    init(wrapping inner: EvgSurface? = nil) {
+        self.inner = inner
+    }
+
+    func count(_ kind: String) -> Int {
+        calls[kind] ?? 0
+    }
+
+    private func note(_ kind: String) {
+        calls[kind, default: 0] += 1
+    }
+
+    var summary: String {
+        calls.keys.sorted().map { "\($0)=\(calls[$0]!)" }.joined(separator: "  ")
+    }
+
+    func save() {
+        note("save")
+        inner?.save()
+    }
+
+    func restore() {
+        note("restore")
+        inner?.restore()
+    }
+
+    func clipRect(x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat) {
+        note("clipRect")
+        inner?.clipRect(x: x, y: y, w: w, h: h)
+    }
+
+    func rotate(degrees: CGFloat, px: CGFloat, py: CGFloat) {
+        note("rotate")
+        inner?.rotate(degrees: degrees, px: px, py: py)
+    }
+
+    func fillRect(
+        x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat,
+        radius: CGFloat, color: EvgColor,
+        gradient: EvgGradient?, shadow: EvgShadow?
+    ) {
+        note("fillRect")
+        if radius > 0 { note("roundedRect") }
+        if gradient != nil { note("gradient") }
+        if shadow != nil { note("shadow") }
+        inner?.fillRect(x: x, y: y, w: w, h: h, radius: radius, color: color, gradient: gradient, shadow: shadow)
+    }
+
+    func strokeRect(
+        x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat,
+        radius: CGFloat, thickness: CGFloat, color: EvgColor
+    ) {
+        note("strokeRect")
+        inner?.strokeRect(x: x, y: y, w: w, h: h, radius: radius, thickness: thickness, color: color)
+    }
+
+    func fillPath(
+        pts: [Double], ringEnds: [Int], evenOdd: Bool,
+        color: EvgColor, shadow: EvgShadow?
+    ) {
+        note("fillPath")
+        if shadow != nil { note("shadow") }
+        inner?.fillPath(pts: pts, ringEnds: ringEnds, evenOdd: evenOdd, color: color, shadow: shadow)
+    }
+
+    func strokePath(pts: [Double], ringEnds: [Int], thickness: CGFloat, color: EvgColor) {
+        note("strokePath")
+        inner?.strokePath(pts: pts, ringEnds: ringEnds, thickness: thickness, color: color)
+    }
+
+    func drawImage(
+        src: String, x: CGFloat, y: CGFloat, w: CGFloat, h: CGFloat,
+        radius: CGFloat, flipH: Bool, flipV: Bool
+    ) {
+        note("drawImage")
+        inner?.drawImage(src: src, x: x, y: y, w: w, h: h, radius: radius, flipH: flipH, flipV: flipV)
+    }
+
+    func drawTextRun(
+        text: String, x: CGFloat, top: CGFloat, sizePx: CGFloat,
+        family: String, bold: Bool, italic: Bool, color: EvgColor
+    ) {
+        note("drawTextRun")
+        if italic { note("italicText") }
+        inner?.drawTextRun(text: text, x: x, top: top, sizePx: sizePx, family: family, bold: bold, italic: italic, color: color)
+    }
+}

package/dist/lib/evg/bench/EvgLayoutBench.rgr

@@ -0,0 +1,34 @@
+; SPDX-License-Identifier: MIT
+
+; ==============================================================================
+; EvgLayoutBench — the layout engine, exported so a harness can drive it
+; ==============================================================================
+; The benchmark and the conformance probe beside this file are JavaScript,
+; because the other side of both comparisons is a browser and the case list has
+; to be written once. This module exists only so `-nodemodule` publishes the
+; engine's classes: the harness builds `EVGElement` trees itself, calls
+; `setAttribute` with CSS property names, and reads `calculated*` back.
+;
+; Nothing here is part of the engine. The one function is the count a harness
+; would otherwise have to re-derive, and it is here rather than in JS so the
+; tree walk is the engine's own.
+; ==============================================================================
+
+Import "../EVGElement.rgr"
+Import "../EVGUnit.rgr"
+Import "../EVGLayout.rgr"
+Import "../EVGDisplayList.rgr"
+
+class EvgLayoutBench {
+
+    sfn countElements:int (el:EVGElement) {
+        def n:int 1
+        def i:int 0
+        while (i < (array_length el.children)) {
+            def kid:EVGElement (itemAt el.children i)
+            n = (n + (EvgLayoutBench.countElements(kid)))
+            i = (i + 1)
+        }
+        return n
+    }
+}

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

@@ -0,0 +1,64 @@
+# `bench/` — the same CSS, two engines
+
+Two harnesses. Both drive the compiled engine from JavaScript, which is worth
+saying on its own: `-nodemodule` publishes `EVGElement`, `EVGLayout` and the
+rest, so a tree is `new EVGElement()`, `setAttribute` with CSS property names,
+`addChild`, `layout()` — no Ranger, no JSX, no stylesheet in the way.
+
+```sh
+npm run evg:layout:conformance     # box for box against Chromium
+npm run evg:layout:bench           # 1k / 10k / 100k, three fixtures
+```
+
+## `layout-conformance.mjs` — where an EVG document and its CSS disagree
+
+The cases in `layout-cases.mjs` are written ONCE, as CSS text. The runner
+splits that text into `setAttribute` calls for EVG and drops it verbatim into a
+`style=` attribute for Chromium, so a differing box is a difference between the
+engines and not between two transcriptions of the same intent.
+
+This is a measurement, not a test suite: Chromium is the definition of what the
+CSS says, and a case that differs names a place where a document written as CSS
+does not lay out as CSS. The report separates the deliberate divergences —
+EVG's initial values for `flex-direction`, `flex-wrap` and `align-items`, which
+are documented choices — from the rest, and says for each whether **the engine
+said anything about it**. That last column is the one that mattered: of the
+nineteen divergences the first run found, eighteen were silent.
+
+The three text cases are not compared pixel for pixel. EVG's default measurer
+is a heuristic and the browser's is a real face, so a diff there would measure
+the fixture; what is asserted instead is that text participates in layout at
+all. Font parity has its own suite (`evg:measure:web`, the textbox oracle).
+
+## `layout-bench.mjs` — what it costs at size
+
+Three fixtures, because "layout" is not one cost: nested flex (an application
+UI's shape, four levels), a wide flat grid (track sizing at size), and the flex
+fixture with text in it. Sizes 1k / 10k / 100k. `layout` is a RE-layout of a
+tree that already exists — what a resize costs, not what a first paint does.
+
+Chromium is timed on the same tree with a forced reflow. Read it as an
+order-of-magnitude reference for a production C++ layout engine on the same
+boxes, not a like-for-like race: the browser is doing line layout and paint
+invalidation that this pass is not, and it is not paying for a heuristic text
+measurer either.
+
+`--ab` builds a second copy of the engine from the pre-change sources
+(`EvgLayoutBenchBase.cjs`, compiled from a `git archive` of the tree you are
+comparing against) and alternates the two inside one process, best-of-runs with
+`--min`. A laptop's noise floor on these fixtures is a few per cent and two runs
+taken minutes apart cannot see through it; alternating can.
+
+```sh
+git archive HEAD lib/evg | tar -x -C /tmp/base
+cp lib/evg/bench/EvgLayoutBench.rgr /tmp/base/lib/evg/bench/
+RANGER_LIB=./compiler/Lang.rgr:./lib/stdops.rgr node dist/rgrc.js -es6 -nodemodule \
+  /tmp/base/lib/evg/bench/EvgLayoutBench.rgr -d=./lib/evg/bin -o=EvgLayoutBenchBase.cjs
+node --expose-gc lib/evg/bench/layout-bench.mjs --ab --min --no-browser
+```
+
+## What it needs
+
+`playwright-core` and a Chromium on disk. The harness takes whatever revision is
+actually installed rather than the one `playwright-core` was built against,
+because those drift; `--no-browser` skips the browser half entirely.