ranger-compiler 3.5.0 → 3.5.2

package/dist/lib/evg/EVGMeasure.rgr

@@ -0,0 +1,1267 @@
+; SPDX-License-Identifier: MIT
+
+; ==============================================================================
+; EVGMeasure — lay a document out and answer, in numbers, what is wrong with it
+; ==============================================================================
+;
+; A model cannot see a screen. Asked whether a layout is right, it renders a
+; picture and describes what it expected to be there. This lays the document
+; out with the real engine and reports the geometry that decides the answer:
+; what overlaps and by how much, what left its parent or the page, how far each
+; element is from the next, and how much room is left at the bottom.
+;
+; --- WHY THIS IS NOT INSIDE THE CLI -------------------------------------------
+;
+; It was, and a second, weaker copy grew in the live-build server: off-page
+; only, no overlap, no distances. Two implementations of "is this layout
+; wrong?" answer differently, and the one the agent reads was the one that
+; knew less. The checks live here so both doors ask the same question.
+;
+; --- WHAT COUNTS AS A FINDING -------------------------------------------------
+;
+; A finding is a fact with a number in it, never an opinion about taste. Off
+; the page, out of a clipping parent, and two in-flow siblings on top of each
+; other are defects at any size. Crowding is reported separately as `tight`,
+; because 2px between two cards is a judgement call the caller makes; the
+; measurement is not.
+;
+; Absolutely positioned nodes are excluded from overlap and from the free-space
+; number: lying on top of the flow is what they are for, and a bottom bar would
+; otherwise report the page as full.
+; ==============================================================================
+
+Import "EVGElement.rgr"
+Import "EVGInspect.rgr"
+Import "EVGLayout.rgr"
+Import "EVGTreeJson.rgr"
+Import "EVGUnit.rgr"
+
+class EVGMeasure {
+    def findings:[string]
+    def tight:[string]
+    def align:[string]
+    ; Controls somebody DREW: a pill with a circle in it is a switch, a small
+    ; square with a tick in it is a checkbox. They are not defects — a picture
+    ; may want one — so they are not in `findings` and do not move `count`.
+    ; They are the one thing about a screen that a layout check can see and a
+    ; person cannot: it looks right, and nothing about it works.
+    def drawn:[string]
+    ; Controls that ARE the real thing and still cannot move: a switch whose
+    ; state is a fixed class word, or whose colours are written on the node.
+    ; The opposite mistake to `drawn` and a harder one to see, because the
+    ; picture is right — it is the only one of the two that survives "use the
+    ; host's control" and still does nothing when pressed.
+    def frozen:[string]
+    ; Set by a caller that is measuring a page whose holes a machine has
+    ; ALREADY filled — an app's page at check time. There a fixed state word
+    ; is the correct result of binding, not a control nailed shut, so that
+    ; half of the `frozen` check is off. Inline paint still counts: it
+    ; outranks the sheet whoever wrote it.
+    def boundView:boolean false
+    def boxes:[string]
+    def width:int 0
+    def height:int 0
+    def nodes:int 0
+    def bottomFree:double 0.0
+    def hasFlow:boolean false
+    def tightMore:int 0
+    def insp:EVGInspect
+
+    Constructor () {
+        insp = (new EVGInspect())
+    }
+
+    ; Lay out and collect. `at` narrows the box listing to one subtree; "" asks
+    ; for none, because the listing is the only part of this that grows with
+    ; the document and most callers want the findings alone.
+    fn look:void (root:EVGElement w:int h:int at:string) {
+        def fresh:[string]
+        findings = fresh
+        def fresh2:[string]
+        tight = fresh2
+        def fresh2b:[string]
+        align = fresh2b
+        def fresh2c:[string]
+        drawn = fresh2c
+        def fresh2d:[string]
+        frozen = fresh2d
+        def fresh3:[string]
+        boxes = fresh3
+        width = w
+        height = h
+        bottomFree = 0.0
+        hasFlow = false
+        tightMore = 0
+
+        def l (new EVGLayout())
+        l.setPageSize((to_double w) (to_double h))
+        l.layout(root)
+        insp.build(root)
+        nodes = (insp.count())
+
+        def pw:double (to_double w)
+        def ph:double (to_double h)
+        def lowest:double 0.0
+        def i:int 0
+        while (i < nodes) {
+            def path:string (insp.pathAt(i))
+            def hit@(optional):EVGElement (insp.elementAt(path))
+            if ((null? hit) == false) {
+                def el:EVGElement (unwrap hit)
+                this.checkOffPage(path el pw ph)
+                this.checkOverflow(path el)
+                this.checkSiblings(path el)
+                this.checkAlignment(path el)
+                this.checkAbsolutes(path el)
+                this.checkDrawnControl(path el)
+                this.checkDrawnSlider(path el)
+                this.checkFrozenControl(path el)
+                ; The free space is the room left under the CONTENT, so a top
+                ; level node is not counted: a root that is the page itself
+                ; would answer 0 for every document and mean nothing by it.
+                if ((EVGMeasure.lastSlash(path)) > 0) {
+                    if ((el.hasAbsolutePosition()) == false) {
+                        def bottom:double (el.calculatedY + el.calculatedHeight)
+                        if (bottom > lowest) {
+                            lowest = bottom
+                            hasFlow = true
+                        }
+                    }
+                }
+                if ((strlen at) > 0) {
+                    if (EVGMeasure.under(path at)) {
+                        this.addBox(path el)
+                    }
+                }
+            }
+            i = (i + 1)
+        }
+        bottomFree = (ph - lowest)
+    }
+
+    ; The whole answer. `pretty` is not decoration: the CLI prints this for a
+    ; model to read and puts one finding per line, while the live-build wire is
+    ; NDJSON and a newline inside an event ends the event. One writer, so the
+    ; two can never drift apart in content.
+    fn json:string (pretty:boolean) {
+        def out:string "{\"width\":"
+        out = (out + (to_string width))
+        out = ((out + ",\"height\":") + (to_string height))
+        out = ((out + ",\"nodes\":") + (to_string nodes))
+        out = ((out + ",\"findings\":") + (EVGMeasure.strArray(findings pretty)))
+        out = ((out + ",\"count\":") + (to_string (array_length findings)))
+        if hasFlow {
+            out = ((out + ",\"bottomFree\":") + (EVGMeasure.num(bottomFree)))
+        }
+        if ((array_length tight) > 0) {
+            out = ((out + ",\"tight\":") + (EVGMeasure.strArray(tight pretty)))
+            if (tightMore > 0) {
+                out = ((out + ",\"tightMore\":") + (to_string tightMore))
+            }
+        }
+        if ((array_length align) > 0) {
+            out = ((out + ",\"align\":") + (EVGMeasure.strArray(align pretty)))
+        }
+        if ((array_length drawn) > 0) {
+            out = ((out + ",\"drawn\":") + (EVGMeasure.strArray(drawn pretty)))
+        }
+        if ((array_length frozen) > 0) {
+            out = ((out + ",\"frozen\":") + (EVGMeasure.strArray(frozen pretty)))
+        }
+        if ((array_length boxes) > 0) {
+            out = (out + ",\"boxes\":[")
+            def i:int 0
+            while (i < (array_length boxes)) {
+                if (i > 0) {
+                    out = (out + ",")
+                }
+                if pretty {
+                    out = (out + "\n  ")
+                }
+                out = (out + (itemAt boxes i))
+                i = (i + 1)
+            }
+            if pretty {
+                out = (out + "\n")
+            }
+            out = (out + "]")
+        }
+        return (out + "}")
+    }
+
+    ; The same numbers small enough to ride along with something else — what
+    ; `patch` says about the document it just wrote. `limit` caps the findings
+    ; quoted; the count is always the real one.
+    fn summary:string (limit:int) {
+        def out:string "{\"nodes\":"
+        out = (out + (to_string nodes))
+        out = ((out + ",\"count\":") + (to_string (array_length findings)))
+        if hasFlow {
+            out = ((out + ",\"bottomFree\":") + (EVGMeasure.num(bottomFree)))
+        }
+        if ((array_length drawn) > 0) {
+            out = ((out + ",\"drawn\":") + (to_string (array_length drawn)))
+        }
+        ; A count would say "something is wrong" and nothing else, and the
+        ; whole value of this check is the sentence. One line costs little and
+        ; is the one an agent can act on.
+        if ((array_length frozen) > 0) {
+            out = ((out + ",\"frozen\":") + (to_string (array_length frozen)))
+            out = ((out + ",\"frozenFirst\":") + (EVGTreeJson.str((itemAt frozen 0))))
+        }
+        def n:int (array_length findings)
+        if (n > 0) {
+            def shown:int n
+            if (shown > limit) {
+                shown = limit
+            }
+            out = (out + ",\"findings\":[")
+            def i:int 0
+            while (i < shown) {
+                if (i > 0) {
+                    out = (out + ",")
+                }
+                out = (out + (EVGTreeJson.str((itemAt findings i))))
+                i = (i + 1)
+            }
+            out = (out + "]")
+            if (n > shown) {
+                out = ((out + ",\"more\":") + (to_string (n - shown)))
+            }
+        }
+        return (out + "}")
+    }
+
+    ; --- the checks -----------------------------------------------------------
+
+    ; --- a control somebody drew ----------------------------------------------
+    ; The one defect a layout check can see and a person cannot. A switch made
+    ; of a 48×28 pill with a 22px circle in it looks right in the picture and
+    ; is not a control: nothing presses it, it has no state to report, and a
+    ; reader is told about a box. Naming it is the whole job here — what to
+    ; use instead is the host's business, because this engine does not know
+    ; which kit is on the other side of it.
+
+    sfn radiusPx:double (el:EVGElement) {
+        def r:EVGUnit el.box.borderRadius
+        if r {
+            if r.isSet {
+                return r.pixels
+            }
+        }
+        return 0.0
+    }
+
+    ; Round enough that somebody meant a circle or a pill.
+    sfn isRound:boolean (el:EVGElement) {
+        def h:double el.calculatedHeight
+        if (h < 6.0) {
+            return false
+        }
+        return ((EVGMeasure.radiusPx(el)) >= ((h * 0.5) - 1.5))
+    }
+
+    sfn hasWords:boolean (el:EVGElement) {
+        if ((strlen (trim el.textContent)) > 0) {
+            return true
+        }
+        def i:int 0
+        while (i < (array_length el.children)) {
+            def c:EVGElement (itemAt el.children i)
+            if (EVGMeasure.hasWords(c)) {
+                return true
+            }
+            i = (i + 1)
+        }
+        return false
+    }
+
+    ; Whether something in this node's ancestry already SAYS it is a control.
+    ; A real one declares a role and hides its parts from the reader, and its
+    ; track is a pill with a knob in it like any drawn switch — the difference
+    ; is exactly that it said so.
+    fn claimedByControl:boolean (path:string el:EVGElement) {
+        if (el.a11yHidden) {
+            return true
+        }
+        def at:string path
+        def guard:int 0
+        while ((guard < 32) && ((strlen at) > 0)) {
+            def hit@(optional):EVGElement (insp.elementAt(at))
+            if (null? hit) {
+                return false
+            }
+            def node:EVGElement (unwrap hit)
+            if ((strlen node.role) > 0) {
+                return true
+            }
+            if (node.a11yFocusable) {
+                return true
+            }
+            at = (insp.parentOf(at))
+            guard = (guard + 1)
+        }
+        return false
+    }
+
+    fn checkDrawnControl:void (path:string el:EVGElement) {
+        if ((array_length el.children) != 1) {
+            return
+        }
+        if (this.claimedByControl(path el)) {
+            return
+        }
+        def kid:EVGElement (itemAt el.children 0)
+        def w:double el.calculatedWidth
+        def h:double el.calculatedHeight
+        def kw:double kid.calculatedWidth
+        def kh:double kid.calculatedHeight
+        if ((h < 12.0) || (h > 44.0)) {
+            return
+        }
+        if ((kh < 6.0) || (kw < 6.0)) {
+            return
+        }
+        ; A SWITCH: a pill about twice as wide as it is tall, with one round
+        ; knob inside it that nearly fills its height and says nothing.
+        if (EVGMeasure.isRound(el)) {
+            if (EVGMeasure.isRound(kid)) {
+                def ratio:double (w / h)
+                def fill:double (kh / h)
+                if ((ratio > 1.35) && (ratio < 2.6) && (fill > 0.55) && (fill < 0.95)) {
+                    if ((EVGMeasure.hasWords(kid)) == false) {
+                        push drawn (path + ": a pill with a knob in it is a drawn switch — use the host's switch control, not boxes")
+                        return
+                    }
+                }
+            }
+        }
+        ; A CHECKBOX: a small square-ish box with a tick drawn or typed in it.
+        def square:double (w / h)
+        if ((square > 0.75) && (square < 1.35) && (h >= 14.0) && (h <= 34.0)) {
+            def mark:boolean false
+            if ((strlen kid.svgPath) > 0) {
+                mark = true
+            }
+            def t:string (trim kid.textContent)
+            if ((t == "✓") || (t == "✔") || (t == "×") || (t == "x") || (t == "-") || (t == "–")) {
+                mark = true
+            }
+            if mark {
+                push drawn (path + ": a box with a tick in it is a drawn checkbox — use the host's checkbox control, not boxes")
+            }
+        }
+    }
+
+    ; --- a control that cannot move --------------------------------------------
+    ; `drawn` catches the screen that never asked for a control. This catches
+    ; the one that did and got a photograph of it.
+    ;
+    ; A control works in an app when two things are true of the document:
+    ;
+    ;   the state is a HOLE      class-name="ui-switch ui-switch-state-{wifi}"
+    ;   the paint is in the SHEET  .ui-switch-track-state-checked { … }
+    ;
+    ; The hole is what `evg_app init` reads to give the control a context key
+    ; and an event — with a fixed word there instead, the machine is written
+    ; without it and a press on it is not an event of any state. The sheet is
+    ; what the hole then switches; a colour written on the node is inline and
+    ; outranks every rule, so even a bound control repainted that way never
+    ; changes. Either one alone is enough to freeze it, and both together is
+    ; what an agent that wrote the document in one pass usually produces.
+    ;
+    ; Like `drawn` these are not defects — a picture of a settings screen is
+    ; allowed to be a picture — so they stay out of `findings` and out of
+    ; `count`, and say what to do instead.
+    fn checkFrozenControl:void (path:string el:EVGElement) {
+        def role:string el.role
+        def isCtl:boolean false
+        if (role == "switch") {
+            isCtl = true
+        }
+        if (role == "checkbox") {
+            isCtl = true
+        }
+        if (role == "radio") {
+            isCtl = true
+        }
+        if (isCtl == false) {
+            return
+        }
+        def cn:string el.className
+        def stateClass:string (EVGMeasure.stateClassIn(cn))
+        def bound:boolean ((indexOf cn "{") >= 0)
+        if boundView {
+            bound = true
+        }
+        def paint:string (EVGMeasure.inlinePaintIn(el 0))
+        def named:boolean ((strlen el.id) > 0)
+        ; A control with no state class at all is not claiming to have two
+        ; looks, so there is nothing here to call frozen.
+        if ((strlen stateClass) == 0) {
+            return
+        }
+        if (bound && ((strlen paint) == 0)) {
+            return
+        }
+        def why:string ""
+        if (bound == false) {
+            why = ((("its state is the fixed class " + stateClass) + " rather than ") + (EVGMeasure.holeFor(stateClass)))
+        }
+        if ((strlen paint) > 0) {
+            if ((strlen why) > 0) {
+                why = (why + ", and ")
+            }
+            why = (((why + "its ") + paint) + " is written on the node, which outranks every rule")
+        }
+        def who:string ((role + " \"") + el.id)
+        if (named == false) {
+            who = (role + " \"(no id)")
+        }
+        def fix:string " — put the state in a {key} and the colours in the sheet"
+        if (named == false) {
+            fix = " — and it has no id, so a press cannot reach it either"
+        }
+        push frozen ((((path + ": ") + who) + "\" cannot change: ") + (why + fix))
+    }
+
+    ; `ui-switch-state-checked` said the way a bound one would be.
+    sfn holeFor:string (stateClass:string) {
+        def cut:int (indexOf stateClass "-state-")
+        if (cut < 0) {
+            return stateClass
+        }
+        return ((substring stateClass 0 (cut + 7)) + "{key}")
+    }
+
+    ; The first class token carrying a state word, quoted back to whoever
+    ; wrote it. "" when there is none.
+    sfn stateClassIn:string (className:string) {
+        def n:int (strlen className)
+        def at:int 0
+        while (at < n) {
+            def rest:string (substring className at n)
+            def sp:int (indexOf rest " ")
+            def end:int n
+            if (sp >= 0) {
+                end = (at + sp)
+            }
+            def tok:string (substring className at end)
+            if ((indexOf tok "-state-") > 0) {
+                return tok
+            }
+            at = (end + 1)
+        }
+        return ""
+    }
+
+    ; The first paint property written on this element or on a part of it.
+    ; Only the ones a state switches are asked for: a width on a track is a
+    ; size the sheet is welcome to keep, a colour on it is the state.
+    sfn inlinePaintIn:string (el:EVGElement depth:int) {
+        if (el.hasInline("background-color")) {
+            return "background-color"
+        }
+        if (el.hasInline("stroke")) {
+            return "stroke"
+        }
+        if (el.hasInline("fill")) {
+            return "fill"
+        }
+        if (el.hasInline("transform")) {
+            return "transform"
+        }
+        if (el.hasInline("border-color")) {
+            return "border-color"
+        }
+        if (depth > 3) {
+            return ""
+        }
+        def i:int 0
+        while (i < (array_length el.children)) {
+            def sub:string (EVGMeasure.inlinePaintIn((itemAt el.children i) (depth + 1)))
+            if ((strlen sub) > 0) {
+                return sub
+            }
+            i = (i + 1)
+        }
+        return ""
+    }
+
+    ; A SLIDER: a long thin groove with one round knob standing proud of it.
+    ;
+    ; This is a separate check rather than a third case inside
+    ; `checkDrawnControl` because that one's shape guard — a box 12 to 44
+    ; pixels tall — is what a switch and a checkbox have and a slider does
+    ; not. A volume groove is four to eight pixels tall with a knob three
+    ; times that sitting on it, so every drawn slider ever made fell out of
+    ; the guard on the first line and nothing was ever said about it.
+    ;
+    ; What separates a knob from a progress bar's fill is that a knob is
+    ; ROUND, about as wide as it is tall, and TALLER than the groove. A fill
+    ; is as tall as the groove and as wide as the value, so it fails all
+    ; three, and a progress bar drawn by hand is not reported here.
+    fn checkDrawnSlider:void (path:string el:EVGElement) {
+        if ((array_length el.children) != 1) {
+            return
+        }
+        if (this.claimedByControl(path el)) {
+            return
+        }
+        def w:double el.calculatedWidth
+        def h:double el.calculatedHeight
+        if ((h < 2.0) || (h > 16.0)) {
+            return
+        }
+        if (w < 60.0) {
+            return
+        }
+        if ((w / h) < 4.0) {
+            return
+        }
+        def kid:EVGElement (itemAt el.children 0)
+        def kw:double kid.calculatedWidth
+        def kh:double kid.calculatedHeight
+        if ((kw < 10.0) || (kh < 10.0)) {
+            return
+        }
+        if (kh <= h) {
+            return
+        }
+        def square:double (kw / kh)
+        if ((square < 0.75) || (square > 1.35)) {
+            return
+        }
+        if ((EVGMeasure.isRound(kid)) == false) {
+            return
+        }
+        if (EVGMeasure.hasWords(kid)) {
+            return
+        }
+        push drawn (path + ": a groove with a knob standing proud of it is a drawn slider — use the host's slider control, not boxes")
+    }
+
+    fn checkOffPage:void (path:string el:EVGElement w:double h:double) {
+        ; A `path` carries its geometry in `d` and its box is 0x0, so every
+        ; check below would pass on a shape that is nowhere near the page. A
+        ; diagram exported from RangerFlow is ALL paths, which made this
+        ; silent on exactly the documents it was most wanted for.
+        if ((strlen el.svgPath) > 0) {
+            this.checkPathOffPage(path el w h)
+            return
+        }
+        def right:double (el.calculatedX + el.calculatedWidth)
+        def bottom:double (el.calculatedY + el.calculatedHeight)
+        if (right > (w + 0.5)) {
+            push findings ((((path + ": right edge ") + (EVGMeasure.num(right))) + " is past the page width ") + (EVGMeasure.num(w)))
+        }
+        if (bottom > (h + 0.5)) {
+            push findings ((((path + ": bottom edge ") + (EVGMeasure.num(bottom))) + " is past the page height ") + (EVGMeasure.num(h)))
+        }
+        if (el.calculatedX < (0.0 - 0.5)) {
+            push findings ((path + ": left edge ") + (EVGMeasure.num(el.calculatedX)))
+        }
+    }
+
+    ; The outer bound of a path, from the numbers in its `d`.
+    ;
+    ; Every coordinate a curve names — its control points included — lies
+    ; outside or on the curve, so the extremes of the whole list bound the
+    ; drawn shape. That is looser than the true bounds and it is the right kind
+    ; of loose here: a shape reported as on the page is definitely on it.
+    ;
+    ; Only M, L, C, Q and Z are read. `A` mixes radii and flags in among the
+    ; coordinates, and treating those as points would invent a bound rather
+    ; than widen one, so a path using anything else is left unchecked and said
+    ; to be.
+    fn checkPathOffPage:void (path:string el:EVGElement w:double h:double) {
+        if (EVGMeasure.hasUnreadCommand(el.svgPath)) {
+            return
+        }
+        def xs:[double]
+        def ys:[double]
+        EVGMeasure.coordsOf(el.svgPath xs ys)
+        if ((array_length xs) == 0) {
+            return
+        }
+        def minX:double (itemAt xs 0)
+        def maxX:double (itemAt xs 0)
+        def i:int 1
+        while (i < (array_length xs)) {
+            def v:double (itemAt xs i)
+            if (v < minX) {
+                minX = v
+            }
+            if (v > maxX) {
+                maxX = v
+            }
+            i = (i + 1)
+        }
+        def minY:double (itemAt ys 0)
+        def maxY:double (itemAt ys 0)
+        def k:int 1
+        while (k < (array_length ys)) {
+            def v:double (itemAt ys k)
+            if (v < minY) {
+                minY = v
+            }
+            if (v > maxY) {
+                maxY = v
+            }
+            k = (k + 1)
+        }
+        if (maxX > (w + 0.5)) {
+            push findings ((((path + ": the shape reaches ") + (EVGMeasure.num(maxX))) + ", past the page width ") + (EVGMeasure.num(w)))
+        }
+        if (maxY > (h + 0.5)) {
+            push findings ((((path + ": the shape reaches ") + (EVGMeasure.num(maxY))) + ", past the page height ") + (EVGMeasure.num(h)))
+        }
+        if (minX < (0.0 - 0.5)) {
+            push findings ((path + ": the shape starts at ") + (EVGMeasure.num(minX)))
+        }
+        if (minY < (0.0 - 0.5)) {
+            push findings ((path + ": the shape starts above the page, at ") + (EVGMeasure.num(minY)))
+        }
+    }
+
+    ; A child wider or taller than the box it is in. `overflow: visible` says
+    ; the author MEANT it to spill, so only a clipping parent is a finding —
+    ; otherwise every deliberate overhang is reported as a defect.
+    ; A child's address, the way `EVGInspect` writes it — the key when it has
+    ; one, the index otherwise. A finding that names "0/0/1" for a node whose
+    ; real address is "0/0/k:title" sends the reader to patch the wrong thing.
+    sfn segOf:string (kid:EVGElement i:int) {
+        if ((strlen kid.key) > 0) {
+            return ("k:" + kid.key)
+        }
+        return (to_string i)
+    }
+
+    fn checkOverflow:void (path:string el:EVGElement) {
+        if (el.overflow == "visible") {
+            return
+        }
+        def i:int 0
+        while (i < (array_length el.children)) {
+            def kid:EVGElement (itemAt el.children i)
+            def kidRight:double (kid.calculatedX + kid.calculatedWidth)
+            def myRight:double (el.calculatedX + el.calculatedWidth)
+            def kidBottom:double (kid.calculatedY + kid.calculatedHeight)
+            def myBottom:double (el.calculatedY + el.calculatedHeight)
+            def who:string ((path + "/") + (EVGMeasure.segOf(kid i)))
+            if (kidRight > (myRight + 0.5)) {
+                push findings ((who + " overflows its parent to the right by ") + (EVGMeasure.num((kidRight - myRight))))
+            }
+            if (kidBottom > (myBottom + 0.5)) {
+                push findings ((who + " overflows its parent below by ") + (EVGMeasure.num((kidBottom - myBottom))))
+            }
+            i = (i + 1)
+        }
+    }
+
+    ; --- WHY ALIGNMENT IS MEASURED AND NOT LEFT TO TASTE ----------------------
+    ;
+    ; A screen where nothing lines up passes every check above: no overlap, no
+    ; overflow, everything on the page, and it still looks like it fell down
+    ; the stairs. It is also the defect an agent is least able to catch, since
+    ; the markup it wrote says `padding: 16px` in six places and the picture
+    ; does not, and nothing in the document names the edge the eye is looking
+    ; for.
+    ;
+    ; So this asks the one question that has an answer: do these children share
+    ; an edge? A stack whose lefts agree is left-aligned, one whose centres
+    ; agree is centred, one whose rights agree is right-aligned — all three are
+    ; deliberate. A stack that agrees on NONE of them was not aligned to
+    ; anything, and that is what gets reported, with the spread in pixels.
+    ;
+    ; Two children a few pixels apart get their own line: 3px is never a design
+    ; decision, it is an edge somebody meant to share.
+    fn checkAlignment:void (path:string el:EVGElement) {
+        def kids:[EVGElement]
+        def names:[string]
+        def n:int (array_length el.children)
+        def i:int 0
+        while (i < n) {
+            def kid:EVGElement (itemAt el.children i)
+            if ((kid.hasAbsolutePosition()) == false) {
+                if ((kid.calculatedWidth > 0.0) && (kid.calculatedHeight > 0.0)) {
+                    push kids kid
+                    push names ((path + "/") + (EVGMeasure.segOf(kid i)))
+                }
+            }
+            i = (i + 1)
+        }
+        def k:int (array_length kids)
+        if (k < 3) {
+            return
+        }
+        ; A row is measured against its top edges, a column against its lefts.
+        ; Anything that is neither — a wrapped run, a grid — has no single edge
+        ; to be off, so it is left alone rather than guessed at.
+        def dir:string (EVGMeasure.stackOf(kids))
+        if (dir == "none") {
+            return
+        }
+        def starts:[double]
+        def middles:[double]
+        def ends:[double]
+        def j:int 0
+        while (j < k) {
+            def kid:EVGElement (itemAt kids j)
+            def a:double kid.calculatedX
+            def len:double kid.calculatedWidth
+            if (dir == "row") {
+                a = kid.calculatedY
+                len = kid.calculatedHeight
+            }
+            push starts a
+            push middles (a + (len / 2.0))
+            push ends (a + len)
+            j = (j + 1)
+        }
+        def edge:string "left"
+        if (dir == "row") {
+            edge = "top"
+        }
+        def sSpread:double (EVGMeasure.spreadOf(starts))
+        def mSpread:double (EVGMeasure.spreadOf(middles))
+        def eSpread:double (EVGMeasure.spreadOf(ends))
+        def best:double sSpread
+        if (mSpread < best) {
+            best = mSpread
+        }
+        if (eSpread < best) {
+            best = eSpread
+        }
+        if (best <= 0.5) {
+            ; Aligned to something on purpose. A near miss inside an otherwise
+            ; tidy stack is still worth a line.
+            this.nearMiss(names starts edge)
+            return
+        }
+        if (best <= 4.0) {
+            push align ((((((EVGMeasure.pathHead(names)) + ": ") + (to_string k)) + " children are ") + (EVGMeasure.num(best))) + "px off a shared edge — nothing lines up exactly")
+            this.nearMiss(names starts edge)
+            return
+        }
+        push align ((((((((EVGMeasure.pathHead(names)) + ": ") + (to_string k)) + " children share no edge — ") + edge) + " spread ") + (EVGMeasure.num(sSpread))) + "px")
+    }
+
+    ; --- WHY AN ABSOLUTE CHILD IS CHECKED SEPARATELY --------------------------
+    ;
+    ; An overlay is exempt from overlap and from the free-space number, and it
+    ; still has to line up with the column it floats over — a bottom bar 12px
+    ; to the right of every card under it is wrong, and no check above sees it,
+    ; because the bar is off the flow and lands on the page either way.
+    ;
+    ; The cause is nearly always the same, and it is worth naming rather than
+    ; only measuring: `left` on an absolute child is resolved from inside the
+    ; parent's padding, so a 12px padding plus `left: 12px` puts the child at
+    ; 24 while the flow starts at 12. The padding is already there; asking for
+    ; it again moves the child by exactly one padding.
+    fn checkAbsolutes:void (path:string el:EVGElement) {
+        def lefts:[double]
+        def rights:[double]
+        def n:int (array_length el.children)
+        def i:int 0
+        while (i < n) {
+            def kid:EVGElement (itemAt el.children i)
+            if ((kid.hasAbsolutePosition()) == false) {
+                if ((kid.calculatedWidth > 0.0) && (kid.calculatedHeight > 0.0)) {
+                    push lefts kid.calculatedX
+                    push rights (kid.calculatedX + kid.calculatedWidth)
+                }
+            }
+            i = (i + 1)
+        }
+        if ((array_length lefts) < 2) {
+            return
+        }
+        def leftShared:boolean ((EVGMeasure.spreadOf(lefts)) <= 0.5)
+        def rightShared:boolean ((EVGMeasure.spreadOf(rights)) <= 0.5)
+        if ((leftShared == false) && (rightShared == false)) {
+            return
+        }
+        def flowLeft:double (itemAt lefts 0)
+        def flowRight:double (itemAt rights 0)
+        def padLeft:double (flowLeft - el.calculatedX)
+        def k:int 0
+        while (k < n) {
+            def kid:EVGElement (itemAt el.children k)
+            if (kid.hasAbsolutePosition()) {
+                if ((kid.calculatedWidth > 0.0) && (kid.calculatedHeight > 0.0)) {
+                    def who:string ((path + "/") + (EVGMeasure.segOf(kid k)))
+                    if (leftShared) {
+                        this.offEdge(who "starts" kid.calculatedX flowLeft padLeft)
+                    }
+                    if (rightShared) {
+                        def mine:double (kid.calculatedX + kid.calculatedWidth)
+                        this.offEdge(who "ends" mine flowRight (0.0 - padLeft))
+                    }
+                }
+            }
+            k = (k + 1)
+        }
+    }
+
+    ; One edge of one overlay against the column it floats over.
+    fn offEdge:void (who:string verb:string mine:double theirs:double pad:double) {
+        def d:double (mine - theirs)
+        def size:double d
+        if (size < 0.0) {
+            size = (0.0 - size)
+        }
+        if (size <= 0.5) {
+            return
+        }
+        ; Past a screen's worth it is a different design, not a missed edge.
+        if (size > 24.0) {
+            return
+        }
+        if ((array_length align) >= 12) {
+            return
+        }
+        def line:string (((((((who + " ") + verb) + " at ") + (EVGMeasure.num(mine))) + ", the flow at ") + (EVGMeasure.num(theirs))) + " — ")
+        def padSize:double pad
+        if (padSize < 0.0) {
+            padSize = (0.0 - padSize)
+        }
+        def near:double (d - pad)
+        if (near < 0.0) {
+            near = (0.0 - near)
+        }
+        if ((padSize > 0.5) && (near <= 0.5)) {
+            push align (line + ("that is one padding: an absolute left/right is measured from inside the parent's padding, so asking for it again adds it twice"))
+            return
+        }
+        push align (line + ((EVGMeasure.num(size)) + "px off the shared edge"))
+    }
+
+    ; Two children that nearly agree. Reported by address, because "somewhere
+    ; in this stack" is not something anybody can act on.
+    fn nearMiss:void (names:[string] starts:[double] edge:string) {
+        def n:int (array_length starts)
+        def i:int 0
+        while (i < n) {
+            def j:int (i + 1)
+            while (j < n) {
+                def d:double ((itemAt starts i) - (itemAt starts j))
+                if (d < 0.0) {
+                    d = (0.0 - d)
+                }
+                if (d > 0.5) {
+                    if (d <= 4.0) {
+                        if ((array_length align) < 12) {
+                            push align ((((((itemAt names i) + " and ") + (itemAt names j)) + ": ") + edge) + ((" edges " + (EVGMeasure.num(d))) + "px apart — align them or mean it"))
+                        }
+                    }
+                }
+                j = (j + 1)
+            }
+            i = (i + 1)
+        }
+    }
+
+    ; Are these children a column, a row, or neither? Each one has to start
+    ; after the one before it on the same axis; a single exception makes it
+    ; neither, which is the honest answer for a wrap or a grid.
+    sfn stackOf:string (kids:[EVGElement]) {
+        def n:int (array_length kids)
+        def column:boolean true
+        def row:boolean true
+        def i:int 1
+        while (i < n) {
+            def prev:EVGElement (itemAt kids (i - 1))
+            def cur:EVGElement (itemAt kids i)
+            if (cur.calculatedY < ((prev.calculatedY + prev.calculatedHeight) - 0.5)) {
+                column = false
+            }
+            if (cur.calculatedX < ((prev.calculatedX + prev.calculatedWidth) - 0.5)) {
+                row = false
+            }
+            i = (i + 1)
+        }
+        if (column) {
+            return "column"
+        }
+        if (row) {
+            return "row"
+        }
+        return "none"
+    }
+
+    sfn spreadOf:double (vals:[double]) {
+        def n:int (array_length vals)
+        if (n == 0) {
+            return 0.0
+        }
+        def lo:double (itemAt vals 0)
+        def hi:double (itemAt vals 0)
+        def i:int 1
+        while (i < n) {
+            def v:double (itemAt vals i)
+            if (v < lo) {
+                lo = v
+            }
+            if (v > hi) {
+                hi = v
+            }
+            i = (i + 1)
+        }
+        return (hi - lo)
+    }
+
+    ; The parent's address, read off the first child's.
+    sfn pathHead:string (names:[string]) {
+        if ((array_length names) == 0) {
+            return "0"
+        }
+        def first:string (itemAt names 0)
+        def cut:int (EVGMeasure.lastSlash(first))
+        if (cut < 0) {
+            return first
+        }
+        return (substring first 0 cut)
+    }
+
+    ; Neighbours: what lies on top of what, and how far apart the rest are.
+    ;
+    ; The distance is the interesting half. "They do not overlap" is what a
+    ; renderer already guarantees; "these two cards are 2px apart and those two
+    ; are 24" is the thing a model cannot get from the document it wrote,
+    ; because the gap is the layout's answer, not the markup's.
+    fn checkSiblings:void (path:string el:EVGElement) {
+        def n:int (array_length el.children)
+        def i:int 0
+        while (i < n) {
+            def a:EVGElement (itemAt el.children i)
+            def j:int (i + 1)
+            while (j < n) {
+                def b:EVGElement (itemAt el.children j)
+                if (((a.hasAbsolutePosition()) == false) && ((b.hasAbsolutePosition()) == false)) {
+                    this.pair(path i a j b)
+                }
+                j = (j + 1)
+            }
+            i = (i + 1)
+        }
+    }
+
+    ; One pair of in-flow siblings, once their boxes are known.
+    fn pair:void (path:string i:int a:EVGElement j:int b:EVGElement) {
+        def nameA:string ((path + "/") + (EVGMeasure.segOf(a i)))
+        def nameB:string ((path + "/") + (EVGMeasure.segOf(b j)))
+        if (EVGMeasure.overlaps(a b)) {
+            def ax2:double (a.calculatedX + a.calculatedWidth)
+            def bx2:double (b.calculatedX + b.calculatedWidth)
+            def ay2:double (a.calculatedY + a.calculatedHeight)
+            def by2:double (b.calculatedY + b.calculatedHeight)
+            def overX:double (EVGMeasure.lower(ax2 bx2) - EVGMeasure.higher(a.calculatedX b.calculatedX))
+            def overY:double (EVGMeasure.lower(ay2 by2) - EVGMeasure.higher(a.calculatedY b.calculatedY))
+            push findings ((((((nameA + " and ") + nameB) + " overlap by ") + (EVGMeasure.num(overX))) + "×") + (EVGMeasure.num(overY)))
+            return
+        }
+        ; Only neighbours in the same run are worth a distance: the gap between
+        ; the first and the last child of a column is arithmetic, not news.
+        if (j != (i + 1)) {
+            return
+        }
+        def d:double (EVGMeasure.gapBetween(a b))
+        if (d < 0.0) {
+            return
+        }
+        if (d < 4.0) {
+            ; A document where everything touches would send its whole tree
+            ; down the wire one pair at a time. The count of what is not shown
+            ; is printed, because a list that stops without saying so reads as
+            ; a document with nothing else wrong.
+            if ((array_length tight) < 12) {
+                push tight ((((nameA + " → ") + nameB) + ": ") + ((EVGMeasure.num(d)) + " apart"))
+            } {
+                tightMore = (tightMore + 1)
+            }
+        }
+    }
+
+    ; The space between two boxes along the axis that separates them. Boxes
+    ; side by side answer with the horizontal gap, stacked ones the vertical;
+    ; two that share neither axis have no single distance and answer -1.
+    sfn gapBetween:double (a:EVGElement b:EVGElement) {
+        def ax2:double (a.calculatedX + a.calculatedWidth)
+        def ay2:double (a.calculatedY + a.calculatedHeight)
+        def bx2:double (b.calculatedX + b.calculatedWidth)
+        def by2:double (b.calculatedY + b.calculatedHeight)
+        def sharesRow:boolean ((ay2 > (b.calculatedY + 0.5)) && (by2 > (a.calculatedY + 0.5)))
+        def sharesCol:boolean ((ax2 > (b.calculatedX + 0.5)) && (bx2 > (a.calculatedX + 0.5)))
+        if sharesCol {
+            if (b.calculatedY >= ay2) {
+                return (b.calculatedY - ay2)
+            }
+            return (a.calculatedY - by2)
+        }
+        if sharesRow {
+            if (b.calculatedX >= ax2) {
+                return (b.calculatedX - ax2)
+            }
+            return (a.calculatedX - bx2)
+        }
+        return (0.0 - 1.0)
+    }
+
+    ; One node's box, and how far the next sibling starts from it.
+    fn addBox:void (path:string el:EVGElement) {
+        def out:string "{\"at\":"
+        out = (out + (EVGTreeJson.str(path)))
+        out = ((out + ",\"tag\":") + (EVGTreeJson.str(el.tagName)))
+        out = ((out + ",\"x\":") + (EVGMeasure.num(el.calculatedX)))
+        out = ((out + ",\"y\":") + (EVGMeasure.num(el.calculatedY)))
+        out = ((out + ",\"w\":") + (EVGMeasure.num(el.calculatedWidth)))
+        out = ((out + ",\"h\":") + (EVGMeasure.num(el.calculatedHeight)))
+        def next@(optional):EVGElement (this.nextSibling(path))
+        if ((null? next) == false) {
+            def sib:EVGElement (unwrap next)
+            def d:double (EVGMeasure.gapBetween(el sib))
+            if (d >= 0.0) {
+                out = ((out + ",\"gapNext\":") + (EVGMeasure.num(d)))
+            }
+        }
+        if ((strlen el.textContent) > 0) {
+            out = ((out + ",\"text\":") + (EVGTreeJson.str(EVGMeasure.clip(el.textContent 32))))
+        }
+        push boxes (out + "}")
+    }
+
+    ; The node after this one under the same parent. Walking the parent's
+    ; children rather than adding one to the address is what makes this work on
+    ; a keyed document, where the next node after "k:title" is not "k:title+1".
+    fn nextSibling@(optional):EVGElement (path:string) {
+        def none@(optional):EVGElement
+        def cut:int (EVGMeasure.lastSlash(path))
+        if (cut < 0) {
+            return none
+        }
+        def parentPath:string (substring path 0 cut)
+        def par@(optional):EVGElement (insp.elementAt(parentPath))
+        if (null? par) {
+            return none
+        }
+        def p:EVGElement (unwrap par)
+        def seg:string (substring path (cut + 1) (strlen path))
+        def n:int (array_length p.children)
+        def i:int 0
+        while (i < n) {
+            def kid:EVGElement (itemAt p.children i)
+            if ((EVGMeasure.segOf(kid i)) == seg) {
+                if ((i + 1) < n) {
+                    def nxt@(optional):EVGElement (itemAt p.children (i + 1))
+                    return nxt
+                }
+                return none
+            }
+            i = (i + 1)
+        }
+        return none
+    }
+
+    ; --- small things ---------------------------------------------------------
+
+    sfn overlaps:boolean (a:EVGElement b:EVGElement) {
+        def ax2:double (a.calculatedX + a.calculatedWidth)
+        def ay2:double (a.calculatedY + a.calculatedHeight)
+        def bx2:double (b.calculatedX + b.calculatedWidth)
+        def by2:double (b.calculatedY + b.calculatedHeight)
+        if ((a.calculatedWidth <= 0.0) || (b.calculatedWidth <= 0.0)) {
+            return false
+        }
+        if ((a.calculatedHeight <= 0.0) || (b.calculatedHeight <= 0.0)) {
+            return false
+        }
+        if (ax2 <= (b.calculatedX + 0.5)) {
+            return false
+        }
+        if (bx2 <= (a.calculatedX + 0.5)) {
+            return false
+        }
+        if (ay2 <= (b.calculatedY + 0.5)) {
+            return false
+        }
+        if (by2 <= (a.calculatedY + 0.5)) {
+            return false
+        }
+        return true
+    }
+
+    sfn hasUnreadCommand:boolean (d:string) {
+        def i:int 0
+        while (i < (strlen d)) {
+            def c:int (charAt d i)
+            def isLetter:boolean (((c >= 65) && (c <= 90)) || ((c >= 97) && (c <= 122)))
+            if isLetter {
+                if ((EVGMeasure.isReadCommand(c)) == false) {
+                    return true
+                }
+            }
+            i = (i + 1)
+        }
+        return false
+    }
+
+    sfn isReadCommand:boolean (c:int) {
+        if ((c == 77) || (c == 109)) {
+            return true
+        }
+        if ((c == 76) || (c == 108)) {
+            return true
+        }
+        if ((c == 67) || (c == 99)) {
+            return true
+        }
+        if ((c == 81) || (c == 113)) {
+            return true
+        }
+        if ((c == 90) || (c == 122)) {
+            return true
+        }
+        return false
+    }
+
+    ; The numbers in a path, taken in pairs. A trailing odd number would mean a
+    ; malformed path, and it is dropped rather than paired with nothing.
+    sfn coordsOf:void (d:string xs:[double] ys:[double]) {
+        def nums:[double]
+        def cur:string ""
+        def i:int 0
+        while (i < (strlen d)) {
+            def c:int (charAt d i)
+            def isNum:boolean (((c >= 48) && (c <= 57)) || (((c == 46) || (c == 45)) || (c == 43)))
+            if isNum {
+                ; A minus starts a new number unless it opens this one.
+                if ((c == 45) && ((strlen cur) > 0)) {
+                    def done@(optional):double (to_double cur)
+                    if done {
+                        push nums (unwrap done)
+                    }
+                    cur = ""
+                }
+                cur = (cur + (substring d i (i + 1)))
+            } {
+                if ((strlen cur) > 0) {
+                    def v@(optional):double (to_double cur)
+                    if v {
+                        push nums (unwrap v)
+                    }
+                    cur = ""
+                }
+            }
+            i = (i + 1)
+        }
+        if ((strlen cur) > 0) {
+            def last@(optional):double (to_double cur)
+            if last {
+                push nums (unwrap last)
+            }
+        }
+        def k:int 0
+        while ((k + 1) < (array_length nums)) {
+            push xs (itemAt nums k)
+            push ys (itemAt nums (k + 1))
+            k = (k + 2)
+        }
+    }
+
+    ; The document's own size in pixels, or the fallback when it does not say.
+    ; Measuring a document against a guessed page reports the guess: every
+    ; export came back "past the page width" for no reason but the default.
+    sfn sizeOf:int (root:EVGElement wide:boolean fallback:int) {
+        def u@(optional):EVGUnit root.height
+        if wide {
+            u = root.width
+        }
+        if (null? u) {
+            return fallback
+        }
+        def uu:EVGUnit (unwrap u)
+        if (uu.isSet == false) {
+            return fallback
+        }
+        if (uu.unitType != 0) {
+            return fallback
+        }
+        def px:int (to_int uu.value)
+        if (px <= 0) {
+            return fallback
+        }
+        return px
+    }
+
+    sfn under:boolean (path:string from:string) {
+        if (path == from) {
+            return true
+        }
+        def head:string (from + "/")
+        def n:int (strlen head)
+        if ((strlen path) <= n) {
+            return false
+        }
+        return ((substring path 0 n) == head)
+    }
+
+    sfn lastSlash:int (path:string) {
+        def at:int (0 - 1)
+        def i:int 0
+        while (i < (strlen path)) {
+            if ((charAt path i) == 47) {
+                at = i
+            }
+            i = (i + 1)
+        }
+        return at
+    }
+
+    sfn lower:double (a:double b:double) {
+        if (a < b) {
+            return a
+        }
+        return b
+    }
+
+    sfn higher:double (a:double b:double) {
+        if (a > b) {
+            return a
+        }
+        return b
+    }
+
+    sfn clip:string (s:string width:int) {
+        if ((strlen s) <= width) {
+            return s
+        }
+        return ((substring s 0 width) + "…")
+    }
+
+    sfn strArray:string (items:[string] pretty:boolean) {
+        def out:string "["
+        def i:int 0
+        while (i < (array_length items)) {
+            if (i > 0) {
+                out = (out + ",")
+            }
+            if pretty {
+                out = (out + "\n  ")
+            }
+            out = (out + (EVGTreeJson.str((itemAt items i))))
+            i = (i + 1)
+        }
+        if pretty {
+            if ((array_length items) > 0) {
+                out = (out + "\n")
+            }
+        }
+        return (out + "]")
+    }
+
+    sfn num:string (v:double) {
+        def whole:int (to_int v)
+        return (to_string whole)
+    }
+}