ranger-compiler 3.5.1 → 3.5.2

package/dist/lib/evg/VectorViewBox.rgr

@@ -0,0 +1,380 @@
+; SPDX-License-Identifier: MIT
+
+; ==============================================================================
+; VectorViewBox.rgr — the one place that decides what vector coordinates mean
+; ==============================================================================
+; PLAN_VECTOR_IR.md §2.1 and §5 Stage 0.
+;
+; Before this file, each renderer answered "where on the page does user unit
+; (10, 20) land?" for itself, and they answered differently:
+;
+;   PDF   fitted the path's BOUNDING BOX to the element box with independent X
+;         and Y scale factors, and ignored viewBox entirely — so a non-square
+;         icon was stretched, and deliberate padding inside the viewBox was
+;         cropped away.
+;   HTML  handed viewBox to the browser, which applied real SVG semantics:
+;         uniform scale, centred, letterboxed.
+;
+; Same document, two geometries. The fix is not to patch either renderer but to
+; have exactly one implementation of the SVG rule, which every renderer calls.
+;
+; The rule implemented here is SVG 1.1 viewBox / preserveAspectRatio: derive a
+; scale from viewport/viewBox on each axis, collapse the two to one (min for
+; `meet`, max for `slice`) unless alignment is `none`, then translate so the
+; requested alignment point of the scaled viewBox meets the same point of the
+; viewport.
+;
+; Nothing here renders. It returns a Matrix2D, so PDF can emit it as a `cm`
+; operand, raster can transform points before flattening, and a test can assert
+; the numbers directly against the spec — no image comparison needed.
+; ==============================================================================
+
+; ------------------------------------------------------------------------------
+; Matrix2D — a 2D affine transform in SVG/PDF operand order.
+;
+;   | a  c  e |     x' = a*x + c*y + e
+;   | b  d  f |     y' = b*x + d*y + f
+;   | 0  0  1 |
+;
+; Deliberately the same six-number layout as an SVG `matrix(...)` and a PDF `cm`
+; operator, so handing it to either renderer needs no reordering.
+; ------------------------------------------------------------------------------
+class Matrix2D {
+    def a:double 1.0
+    def b:double 0.0
+    def c:double 0.0
+    def d:double 1.0
+    def e:double 0.0
+    def f:double 0.0
+
+    sfn identity:Matrix2D () {
+        def m (new Matrix2D())
+        return m
+    }
+
+    sfn create:Matrix2D (ma:double mb:double mc:double md:double me:double mf:double) {
+        def m (new Matrix2D())
+        m.a = ma
+        m.b = mb
+        m.c = mc
+        m.d = md
+        m.e = me
+        m.f = mf
+        return m
+    }
+
+    sfn translate:Matrix2D (tx:double ty:double) {
+        return (Matrix2D.create(1.0 0.0 0.0 1.0 tx ty))
+    }
+
+    sfn scale:Matrix2D (sx:double sy:double) {
+        return (Matrix2D.create(sx 0.0 0.0 sy 0.0 0.0))
+    }
+
+    fn applyX:double (x:double y:double) {
+        def v:double (((a * x) + (c * y)) + e)
+        return v
+    }
+
+    fn applyY:double (x:double y:double) {
+        def v:double (((b * x) + (d * y)) + f)
+        return v
+    }
+
+    ; this ∘ other — apply `other` first, then this.
+    fn multiply:Matrix2D (o:Matrix2D) {
+        def na:double ((a * o.a) + (c * o.b))
+        def nb:double ((b * o.a) + (d * o.b))
+        def nc:double ((a * o.c) + (c * o.d))
+        def nd:double ((b * o.c) + (d * o.d))
+        def ne:double (((a * o.e) + (c * o.f)) + e)
+        def nf:double (((b * o.e) + (d * o.f)) + f)
+        return (Matrix2D.create(na nb nc nd ne nf))
+    }
+
+    fn isIdentity:boolean () {
+        def flat:boolean true
+        if ((a == 1.0) == false) { flat = false }
+        if ((b == 0.0) == false) { flat = false }
+        if ((c == 0.0) == false) { flat = false }
+        if ((d == 1.0) == false) { flat = false }
+        if ((e == 0.0) == false) { flat = false }
+        if ((f == 0.0) == false) { flat = false }
+        return flat
+    }
+}
+
+; ------------------------------------------------------------------------------
+; ViewBoxRect — a parsed `viewBox="minX minY width height"`.
+;
+; `isSet` is false for a missing or malformed viewBox. Callers must check it:
+; per spec a negative or zero width/height disables rendering rather than
+; silently meaning something else, so guessing here would hide a document bug.
+; ------------------------------------------------------------------------------
+class ViewBoxRect {
+    def minX:double 0.0
+    def minY:double 0.0
+    def width:double 0.0
+    def height:double 0.0
+    def isSet:boolean false
+
+    sfn create:ViewBoxRect (x:double y:double w:double h:double) {
+        def r (new ViewBoxRect())
+        r.minX = x
+        r.minY = y
+        r.width = w
+        r.height = h
+        r.isSet = true
+        return r
+    }
+
+    ; Back to the attribute form, for renderers that emit SVG rather than
+    ; consume it. Round-trips through parseViewBox.
+    fn asAttribute:string () {
+        def s:string ((to_string minX) + " " + (to_string minY))
+        s = (s + " " + (to_string width) + " " + (to_string height))
+        return s
+    }
+}
+
+; ------------------------------------------------------------------------------
+; VectorViewBox — viewBox + preserveAspectRatio → Matrix2D.
+; ------------------------------------------------------------------------------
+class VectorViewBox {
+
+    ; Alignment codes. X and Y are independent in SVG, so they are kept apart
+    ; rather than enumerating the nine combined keywords.
+    ;   0 = Min (left / top), 1 = Mid (centre), 2 = Max (right / bottom)
+    ; `none` is signalled separately, because it is the one case where the two
+    ; axes keep independent scales.
+
+    sfn splitTokens:[string] (s:string) {
+        def parts:[string]
+        def current:string ""
+        def i:int 0
+        def n:int (strlen s)
+        while (i < n) {
+            def ch:int (charAt s i)
+            def isSep:boolean false
+            if (ch == 32) { isSep = true }
+            if (ch == 9) { isSep = true }
+            if (ch == 10) { isSep = true }
+            if (ch == 13) { isSep = true }
+            if (ch == 44) { isSep = true }
+            if isSep {
+                if ((strlen current) > 0) {
+                    push parts current
+                    current = ""
+                }
+            } {
+                current = (current + (strfromcode ch))
+            }
+            i = (i + 1)
+        }
+        if ((strlen current) > 0) {
+            push parts current
+        }
+        return parts
+    }
+
+    ; "minX minY width height", separated by whitespace and/or commas.
+    ;
+    ; Returns an unset rect when the list is not four numbers, or when width or
+    ; height is not positive. SVG 1.1: a negative value is an error and zero
+    ; disables rendering of the element — either way there is no transform to
+    ; compute, and the caller decides what to do about it.
+    sfn parseViewBox:ViewBoxRect (s:string) {
+        def out (new ViewBoxRect())
+        def parts:[string] (VectorViewBox.splitTokens(s))
+        if ((array_length parts) != 4) {
+            return out
+        }
+        def vals:[double]
+        def i:int 0
+        while (i < 4) {
+            def tok:string (itemAt parts i)
+            def num@(optional):double (to_double tok)
+            if num {
+                push vals (unwrap num)
+            } {
+                return out
+            }
+            i = (i + 1)
+        }
+        def w:double (itemAt vals 2)
+        def h:double (itemAt vals 3)
+        if (w <= 0.0) {
+            return out
+        }
+        if (h <= 0.0) {
+            return out
+        }
+        out.minX = (itemAt vals 0)
+        out.minY = (itemAt vals 1)
+        out.width = w
+        out.height = h
+        out.isSet = true
+        return out
+    }
+
+    ; preserveAspectRatio → the three things the transform needs.
+    ;
+    ; Grammar: [defer] <align> [meet | slice], where align is "none" or one of
+    ; the nine xM..YM.. keywords. `defer` only applies to <image> referencing
+    ; another SVG, so it is accepted and ignored. An unrecognised value falls
+    ; back to the spec default rather than failing: an odd string should not
+    ; make an icon vanish.
+    sfn alignX:int (par:string) {
+        def parts:[string] (VectorViewBox.splitTokens(par))
+        def i:int 0
+        while (i < (array_length parts)) {
+            def tok:string (itemAt parts i)
+            if ((indexOf tok "xMin") == 0) { return 0 }
+            if ((indexOf tok "xMid") == 0) { return 1 }
+            if ((indexOf tok "xMax") == 0) { return 2 }
+            i = (i + 1)
+        }
+        return 1
+    }
+
+    sfn alignY:int (par:string) {
+        def parts:[string] (VectorViewBox.splitTokens(par))
+        def i:int 0
+        while (i < (array_length parts)) {
+            def tok:string (itemAt parts i)
+            if ((indexOf tok "YMin") > 0) { return 0 }
+            if ((indexOf tok "YMid") > 0) { return 1 }
+            if ((indexOf tok "YMax") > 0) { return 2 }
+            i = (i + 1)
+        }
+        return 1
+    }
+
+    sfn isNone:boolean (par:string) {
+        def parts:[string] (VectorViewBox.splitTokens(par))
+        def i:int 0
+        while (i < (array_length parts)) {
+            def tok:string (itemAt parts i)
+            if (tok == "none") { return true }
+            i = (i + 1)
+        }
+        return false
+    }
+
+    sfn isSlice:boolean (par:string) {
+        def parts:[string] (VectorViewBox.splitTokens(par))
+        def i:int 0
+        while (i < (array_length parts)) {
+            def tok:string (itemAt parts i)
+            if (tok == "slice") { return true }
+            i = (i + 1)
+        }
+        return false
+    }
+
+    ; The transform mapping viewBox user units onto a viewport of viewW x viewH
+    ; whose origin is (0, 0). Callers translate that origin into place
+    ; themselves — for PDF that means composing with the page flip, which is why
+    ; this stays viewport-local.
+    ;
+    ; SVG 1.1, in order:
+    ;   1. scale-x = viewW / vb.width, scale-y = viewH / vb.height
+    ;   2. unless align is `none`, collapse to one scale: min for meet (the
+    ;      whole viewBox fits, with letterboxing), max for slice (the viewport
+    ;      is covered, with overflow)
+    ;   3. translate by -minX/-minY scaled, then by the alignment offset
+    sfn resolve:Matrix2D (vb:ViewBoxRect viewW:double viewH:double par:string) {
+        if (vb.isSet == false) {
+            return (Matrix2D.identity())
+        }
+        if (viewW <= 0.0) {
+            return (Matrix2D.identity())
+        }
+        if (viewH <= 0.0) {
+            return (Matrix2D.identity())
+        }
+
+        def scaleX:double (viewW / vb.width)
+        def scaleY:double (viewH / vb.height)
+
+        if ((VectorViewBox.isNone(par)) == false) {
+            def uniform:double scaleX
+            if (VectorViewBox.isSlice(par)) {
+                if (scaleY > uniform) {
+                    uniform = scaleY
+                }
+            } {
+                if (scaleY < uniform) {
+                    uniform = scaleY
+                }
+            }
+            scaleX = uniform
+            scaleY = uniform
+        }
+
+        def tx:double (0.0 - (vb.minX * scaleX))
+        def ty:double (0.0 - (vb.minY * scaleY))
+
+        def slackX:double (viewW - (vb.width * scaleX))
+        def slackY:double (viewH - (vb.height * scaleY))
+
+        def ax:int (VectorViewBox.alignX(par))
+        def ay:int (VectorViewBox.alignY(par))
+
+        if (ax == 1) {
+            tx = (tx + (slackX / 2.0))
+        }
+        if (ax == 2) {
+            tx = (tx + slackX)
+        }
+        if (ay == 1) {
+            ty = (ty + (slackY / 2.0))
+        }
+        if (ay == 2) {
+            ty = (ty + slackY)
+        }
+
+        return (Matrix2D.create(scaleX 0.0 0.0 scaleY tx ty))
+    }
+
+    ; Which viewBox actually governs an element, given what the document
+    ; declared and where the path's ink turned out to be.
+    ;
+    ; An explicit viewBox always wins — that is the author saying what the
+    ; coordinate system is. When there is none, SVG proper would draw at 1:1 and
+    ; clip, but EVG's <Path> has always been sized by its `width`/`height` and
+    ; every existing document relies on the art being fitted to that box. So the
+    ; fallback synthesises a viewBox from the path bounds, which keeps those
+    ; documents working AND — the point of doing it here rather than in one
+    ; renderer — gives every renderer the same fallback. Previously PDF fitted
+    ; the bounds while HTML drew at 1:1, so the two disagreed on exactly the
+    ; documents that never set a viewBox, which is all of them.
+    ;
+    ; Degenerate ink (a horizontal line has zero height) yields an unset rect,
+    ; and the caller falls back to identity rather than dividing by zero.
+    sfn effectiveViewBox:ViewBoxRect (declared:string boundsX:double boundsY:double boundsW:double boundsH:double) {
+        def explicit:ViewBoxRect (VectorViewBox.parseViewBox(declared))
+        if explicit.isSet {
+            return explicit
+        }
+        def synth (new ViewBoxRect())
+        if (boundsW <= 0.0) {
+            return synth
+        }
+        if (boundsH <= 0.0) {
+            return synth
+        }
+        return (ViewBoxRect.create(boundsX boundsY boundsW boundsH))
+    }
+
+    ; Convenience: parse and resolve in one step, with the SVG default
+    ; preserveAspectRatio when none was given on the element.
+    sfn resolveString:Matrix2D (viewBox:string viewW:double viewH:double par:string) {
+        def effective:string par
+        if ((strlen effective) == 0) {
+            effective = "xMidYMid meet"
+        }
+        def vb:ViewBoxRect (VectorViewBox.parseViewBox(viewBox))
+        return (VectorViewBox.resolve(vb viewW viewH effective))
+    }
+}

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

@@ -0,0 +1,290 @@
+# `evg_agent` — the tool surface
+
+Four verbs over an EVG document. An agent with a shell already has everything
+it needs to edit one; MCP, a widget and an editor panel are transports over
+exactly these, added when something needs them. The plan they belong to is
+[`PLAN_AI_BRIDGE.md`](../../../docs/plans/PLAN_AI_BRIDGE.md).
+
+```bash
+npm run agent -- outline <doc.evg.json> [--depth=N] [--at=PATH]
+npm run agent -- query   <doc.evg.json> <.class | #id | tag | path>
+npm run agent -- patch   <doc.evg.json> <ops.json> [--out=FILE]
+npm run agent -- measure <doc.evg.json> [--width=N] [--height=N]
+```
+
+## outline — the addresses
+
+```
+$ npm run agent -- outline lib/evg/agent/fixtures/card.evg.json --depth=1
+0                     div .page  width=600px  height=400px  background-color=rgb(246,247,249) …
+0/0                     div .card  width=320px  height=120px  background-color=rgb(255,255,255) …
+0/1                     div .card  width=320px  height=120px  background-color=rgb(255,255,255) …
+
+… 3 deeper nodes not shown — raise --depth or pass --at to go into one
+```
+
+The only verb that does not print JSON, because it is the only one meant to be
+**read** rather than parsed. One line per node — its address, what it is, and
+just the properties it actually sets — costs a fraction of the same tree as
+JSON while carrying the addresses every other verb takes.
+
+A truncated outline says so. A model that cannot see there is more will
+confidently describe a document it has only the top of.
+
+Addresses are `EVGInspect` paths: `0` is the root, `0/3` its fourth child,
+`0/3/k:share` a child with a `key`. Keyed children survive a sibling being
+inserted above them; unkeyed ones do not, which is the reason to key anything
+an edit will come back to.
+
+## query — finding one
+
+```
+$ npm run agent -- query lib/evg/agent/fixtures/card.evg.json .card
+{"matches":[
+  {"at":"0/0","tag":"div","props":{"class-name":"card","width":"320px", …},"children":2},
+  {"at":"0/1","tag":"div","props":{"class-name":"card","width":"320px", …},"children":1}
+],"count":2}
+```
+
+`.class`, `#id`, a bare tag, or a path. Not a selector engine — a compound
+selector belongs to `EVGStyleSheet`, and a second weaker implementation of one
+here would be worth less than the honest limit.
+
+## patch — the edit
+
+Ops are the only way to change a document. Each is addressed by a path,
+validated against the engine's real property set, and carries its own inverse.
+
+```json
+{"ops":[
+  {"op":"set-text","at":"0/0/k:title","value":"Invoices"},
+  {"op":"set-prop","at":"0/0","prop":"background-color","value":"rgb(255,251,235)"},
+  {"op":"insert","at":"0/0","index":2,"tag":"span"},
+  {"op":"remove","at":"0/1"},
+  {"op":"move","at":"0/0/k:sub","to":"0/1","index":0}
+]}
+```
+
+```
+$ npm run agent -- patch doc.evg.json ops.json
+{"ok":true,"applied":4,"wrote":"doc.evg.json","inverse":[
+  {"op":"set-text","at":"0/0/k:title","value":"Orders"},
+  {"op":"set-prop","at":"0/0","prop":"background-color","value":"rgb(255,255,255)"},
+  {"op":"remove","at":"0/0/2"}
+]}
+```
+
+`patch` answers with `layout` too — the same summary, without being asked:
+
+```
+{"ok":true,"applied":1,"wrote":"doc.evg.json",
+ "layout":{"nodes":30,"count":1,"bottomFree":-13,
+           "findings":["0/8: bottom edge 856 is past the page height 844"]},
+ "inverse":[…]}
+```
+
+An agent that patches and stops has changed a picture it cannot see. One
+layout pass here costs less than the round trip it would skip.
+
+The `inverse` list is a **runnable ops file**: save it, run `patch` with the
+ops in reverse order, and the document is what it was. That is the difference
+between "here is how to undo it" and "here is a description of the undo".
+
+Four rules worth knowing before writing ops:
+
+- **A rejected op fails the whole batch.** Nothing is applied and the document
+  is untouched. "3 of 5 applied" hands you a document nobody designed.
+- **An op can apply and leave no trace.** A file carries only what differs from
+  a fresh element of that tag, and EVG's defaults are not CSS's — a div is
+  `flex-direction: column`. Setting a property to its default therefore removes
+  a line rather than adding one, and the node changed anyway. `patch` names
+  those ops in `atDefault` so that re-reading the file is not read as the edit
+  having been dropped:
+
+  ```
+  {"ok":true,"applied":1,"wrote":"doc.evg.json","atDefault":[
+    {"at":"0/0","prop":"flex-direction","value":"column","tag":"div"}
+  ],"note":"applied — but those values are the tag default …","inverse":[…]}
+  ```
+
+- **A property that cannot be read back cannot be patched.** The patchable set
+  is `EVGPatch.patchableNames()` — which is also exactly what a document file
+  can carry, so nothing can be written down that an edit would silently drop.
+- **`remove`'s inverse is in-process only.** It names a subtree the patch that
+  removed it is holding. A file cannot replay it; keep the pre-patch document
+  if you want that undo across two runs.
+
+## measure — the part a model cannot do for itself
+
+```
+$ npm run agent -- measure lib/evg/agent/fixtures/broken.evg.json --width=600 --height=300
+{"width":600,"height":300,"nodes":5,"findings":[
+  "0/0 and 0/1 overlap by 100×40",
+  "0/0/0 overflows its parent to the right by 200",
+  "0/2: right edge 820 is past the page width 600",
+  "0/2: bottom edge 320 is past the page height 300"
+],"count":4,"bottomFree":200}
+```
+
+It lays the document out and answers, in numbers, whether the result is wrong.
+A screenshot asks a model to *see* that — badly, and for a thousand times the
+tokens. This reads it off the boxes layout already computed.
+
+What it checks today: a node past the page, a child spilling out of a parent
+that clips, and two in-flow siblings on top of each other — with the overlap
+in pixels, because "they overlap" and "they overlap by 1" are different bugs.
+`overflow: visible` is not a finding — the author meant it to spill. Absolutely
+positioned nodes are not checked for overlap; overlapping is what they are for.
+
+Two numbers come back on a sound document as well, because "nothing is wrong"
+is not the same as "this is what it looks like":
+
+- **`bottomFree`** — the room left under the content, absolutes excluded. A
+  screen that grew by a card and reports the same free space did not put the
+  card where you think.
+- **`tight`** — neighbours less than 4px apart. Not a defect; the measurement
+  of one, for a caller who can decide whether 2px between two cards was meant.
+- **`align`** — what does not line up. Children that share a left edge are
+  aligned, children whose centres agree are centred, children that agree on
+  neither were aligned to nothing, and the spread says by how much. This is
+  the defect every other check misses: a screen where each row starts at a
+  different x has no overlap, no overflow, and is plainly wrong to look at.
+  An absolutely positioned child is compared against the flow it floats over,
+  because it is exempt from every other check and still has to line up; when
+  it is off by exactly the parent's padding, the report says so, since `left`
+  on an absolute child is resolved from inside that padding and asking for it
+  again adds it twice.
+
+### Distances, when spacing is the question
+
+```
+$ npm run agent -- measure doc.evg.json --boxes --at=0/2
+{…,"boxes":[
+  {"at":"0/2","tag":"div","x":16,"y":113,"w":358,"h":64,"gapNext":8},
+  {"at":"0/2/0","tag":"span","x":32,"y":122,"w":65,"h":29,"gapNext":4,"text":"1,284"}
+]}
+```
+
+Where each node really is, and how far the next sibling starts from it.
+`gapNext` is the layout's answer, not the markup's: it is what `gap`, the
+margins and `flex` actually produced, which is the thing a model cannot work
+out from the document it just wrote. The listing is the only part of `measure`
+that grows with the document, so it costs nothing until `--boxes` asks for it,
+and `--at` narrows it to one subtree.
+
+The same checks run inside the live-build server (`EVGMeasure`), so the numbers
+the agent reads and the numbers the page shows cannot drift apart.
+
+A `path` has no box — its geometry is the `d` string — so its page bounds are
+read from the coordinates in `d`, control points included. That bound is looser
+than the shape, which is the right way round: a shape reported as on the page
+is on it. A path using `A` is left unchecked, because arc flags among the
+coordinates would invent a bound rather than widen one.
+
+**What it does NOT check, on a diagram.** A document exported from RangerFlow
+is entirely absolute positions and paths, so the overlap and parent-overflow
+checks have nothing to work with: a label that no longer fits the shape drawn
+behind it is not a finding, because nothing in the document says the two belong
+together. Off-page is caught; fit is not. Look at a diagram before believing a
+count of zero.
+
+## A bitmap in — `evg_image_tool`
+
+```
+$ npm run agent:image                       # once, to build it
+$ node lib/evg/bin/evg_image_tool.js photo.png --out=photo --width=180
+{"width":320,"height":221,"layers":8,"rings":126,"colors":[
+  {"hex":"#E3C8A6","share":0.223},
+  {"hex":"#F0E9D4","share":0.214},
+  {"hex":"#0E184D","share":0.108}
+],"wrote":{"svg":"photo.svg","ops":"photo.ops.json"},
+ "insertsAt":"0/0","placed":"180x124"}
+```
+
+A model handed a photograph can describe it and cannot put it on a screen. The
+bridge — `EvgBitmapTracer`, the same one the live tracer page uses —
+has been here all along with nothing pointing an agent at it. This turns an
+image into the two things an agent can act on:
+
+- **the picture**, traced to flat colour layers and written out as an ops file,
+  so `npm run agent -- patch doc.evg.json photo.ops.json` puts it in the
+  document. It goes in as an `svg` node: vector, painted by the browser, the
+  rasteriser and the PDF backend alike, with no image loading anywhere.
+- **the colours**, each with its share of the pixels — counted over the image,
+  not inferred from how many paths a layer produced, because one huge
+  background region and four hundred specks of the same colour say opposite
+  things about which colour the picture *is*.
+
+The ops file is the point. A traced photograph is tens of kilobytes of
+coordinates, and printing them would put every one through a model's context on
+the way back into a patch. `--at` and `--index` say where the picture is
+inserted, `--width` what it is placed at, and `--preset` picks how it is traced
+(lineart, poster, photo, broken, print — see `EvgTraceTypes.rgr`).
+
+## Getting a real document in, and a picture out
+
+The four verbs read `.evg.json`. Two neighbours in `gallery/pdf_writer/src/tools`
+connect that to everything else — and both of them read either format, so
+nothing below is a special path for agents:
+
+```bash
+# a .tsx document (with its stylesheet resolved in) -> the editable format
+npm run agent:import -- page.tsx page.evg.json -css themes/showcase.css -theme editorial
+
+# the editable format -> a picture to look at
+npm run agent:render -- page.evg.json page.png
+npm run agent:html   -- page.evg.json page.html
+```
+
+These build the tool if it is not there and then run it — the compiled
+JavaScript under `gallery/pdf_writer/bin/` is not in the repository, because a
+regenerated bundle is 40 000 lines of diff nobody can review. Running the tool
+directly with `node` works too, once something has built it.
+
+There is no `render` verb here, and that is deliberate: the painters already
+exist and adding a second entry point to them would be two things to keep
+working instead of one.
+
+**The conversion is checked, not asserted.** `evg_json_tool` lays the original
+out, reads its own output back, lays that out too, and compares — the boxes,
+and then the draw commands the two produce. It also names anything it had to
+drop. `-strict` turns that report into a refusal, which is what a build step
+wants.
+
+**Stylesheets are resolved in.** Whatever `-css` decides becomes inline props
+in the output, so the agent edits one document rather than a tree plus a
+cascade it cannot see. The cost is that theming is baked: re-theming means
+converting again from the source.
+
+**Asset paths move with the document.** A `src` is resolved against the file it
+is written in, so the converter re-anchors every one for wherever the output is
+going. When the two places have no expressible relation — one absolute, one not
+— it says so instead of writing a path that resolves somewhere else.
+
+## The document format
+
+[`EVGTreeJson`](../EVGTreeJson.rgr). A node says its tag, identity, text, and
+`props` — and `props` is exactly the patchable set. Only what differs from a
+fresh element **of the same tag** is written, so a file stays short and a span
+and a div can disagree about their defaults.
+
+It is not a lossless container for an arbitrary EVG tree: a `path` element's
+`d`, an image's `alt`, a `viewBox` — the engine has them and this format does
+not. A converter into this format from JSX or a `.fig` has to say what it drops
+rather than round-trip through here and call it identity.
+
+## Running the tests
+
+```bash
+npm run evg:patch:test    # EVGPatch and EVGTreeJson — 81 assertions
+npm run agent:smoke       # the four verbs, against the fixtures
+npm run agent:roundtrip   # every showcase page, converted and re-rendered
+```
+
+`agent:roundtrip` is the one that matters most and the one that found every
+loss so far. It converts all seventeen showcase pages and requires the PNG
+rendered from the conversion to be **byte-identical** to the PNG rendered from
+the original. It asks nothing and compares everything, which is why it caught
+three properties the format was missing — `grid-row`, an imported SVG's source,
+and the `emoji-color` tint — each of which the converter's own audit had called
+clean.