@ethlete/agent-rules 0.1.0-next.0 → 0.1.0-next.10

package/content/skills/api-source/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: api-source
+description: How to read the source of the API an app in this repo talks to, from a local backend checkout named in ethlete-agents.config.local.json. Read when a response shape, a status code, an error body, an enum or an auth rule has to be confirmed rather than guessed - and never edit that checkout as part of work in this repo.
+kind: skill
+scope: consumer
+---
+
+# Reading the API source
+
+The client's types describe what the frontend _expects_. When the two disagree, the
+server is right, so a question about the contract is answered in the API repository -
+not by reading the frontend's own models harder.
+
+Reach for the checkout when:
+
+- a response arrives with a field, a shape or a `null` the frontend types do not allow
+- you need the exact status code, error body or validation message for a failure path
+- an enum, a permission or a filter parameter has to match the server's list exactly
+- a request fails and you cannot tell whether the client or the server is wrong
+- you are about to report or fix something in the API itself
+
+Do not read it to design frontend code that the API does not serve yet. An endpoint in
+the checkout is not deployed until the API team ships it.
+
+## 1. Resolve the checkout for your app
+
+One repository can hold several apps, each with its own API, so the paths are a map from
+app to checkout. They are per machine, so the map lives in the gitignored
+`ethlete-agents.config.local.json` at the repo root:
+
+```json
+{
+  "apiRepoPaths": {
+    "hub": "../fut-hub-backend"
+  }
+}
+```
+
+Read that file before searching anywhere. The rules:
+
+- **The key is the app** as this repo names it - the workspace project name, which is
+  normally also the folder under `apps/`. Match the app you are working in.
+- **A relative path resolves from the repo root**, not from the app folder.
+- **One entry means one API.** If the map holds a single entry, use it whatever it is
+  called.
+- **No matching entry - stop and ask.** Do not guess a sibling folder and do not clone
+  the repository. Say which app you needed the API for and offer the snippet above; the
+  file is gitignored, so adding it changes nothing for anyone else.
+
+Without a checkout, fall back to what the running API tells you: the generated API
+description if the project serves one (`/openapi.json`, `/swagger`, `/api/doc`), and the
+real response body of the call you are debugging.
+
+## 2. Check the branch before you read anything
+
+A checkout sits on whatever branch its developer left it on, and the code you would
+quote must be the code that serves this app:
+
+```bash
+git -C <apiRepoPath> fetch --quiet     # read-only, safe
+git -C <apiRepoPath> status -sb        # branch, ahead/behind, dirty files
+```
+
+**The state to expect is the API's own development branch, up to date with its remote.**
+Anything else, and you are describing a different API than the one the app calls.
+
+When it is not in that state, **say so and ask** - never switch, pull, stash or reset it
+yourself:
+
+- **On another branch** - name it and ask. A feature branch may be exactly the endpoint
+  you were sent to look at, but it is not what the app talks to today.
+- **Behind its remote** - report how far. The behaviour you are about to call a bug may
+  already be fixed upstream.
+- **Dirty** - it holds someone's work in progress. Say so rather than quoting it as API
+  behaviour.
+
+## 3. The checkout is not the environment the app calls
+
+Even a clean, current checkout is only the source. The app talks to a deployed
+environment, which can lag it:
+
+- Read the app's API base URL from its environment config, and say which environment
+  your answer is about.
+- When the source and the observed response disagree, **the observed response wins** for
+  what the app has to handle today. Report the difference instead of writing client code
+  against the newer source.
+
+## 4. Search it, don't read it whole
+
+The stack is whatever the API team chose, so search by the thing you already know - the
+path, the field name, the error message - rather than by an expected file layout:
+
+```bash
+rg -n "api/v1/matches" <apiRepoPath> --glob '!*test*'   # the route
+rg -n "kickoffAt" <apiRepoPath>                         # a field of the payload
+rg -n "MATCH_NOT_FOUND" <apiRepoPath>                   # an error code you received
+```
+
+Two things to find first, because they answer most questions on their own:
+
+- **The API description** the project generates or checks in (OpenAPI, Swagger, GraphQL
+  schema, `.http` files). It is the contract, and it is cheaper to read than the code.
+- **The serializer, resource or DTO** for the entity - the field list the client sees,
+  which is usually a subset of the database model, and the place where a name is
+  rewritten between the two.
+
+The API's own tests describe intended behaviour more directly than the implementation:
+they name the status code and the body for each case.
+
+## 5. The checkout is read-only from here
+
+It is a different repository with its own branch, review and release process. Never edit
+it while working on a task in this repo, and never change its git state without being
+asked (`fetch` is fine).
+
+When the fix belongs in the API, say so precisely: the endpoint, the field, and the
+behaviour it should have. Then handle the API as it is today - a client workaround for a
+server bug is a decision for the user, and it needs a comment naming what it waits on.

package/content/skills/figma-export/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: figma-export
+description: Reconcile a component against a Figma export - which exports to ask the designer for (an .svg frame and its "copy as CSS" dump), how to dump the geometry out of each, which of their numbers are authoritative, and how to measure the real rendered result against them headlessly. Use whenever a design export is dropped next to a component and the component has to be matched to it.
+kind: skill
+scope: both
+---
+
+# Reconcile a component against a Figma export
+
+Three things arrive from Figma, and each answers a different question:
+
+| Export                    | Gives you                                                                     | Cannot tell you                             |
+| ------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------- |
+| **`.svg`** (Export frame) | Exact geometry with nesting, exact fills, and a picture once you rasterise it | Layer names, auto-layout intent, font sizes |
+| **`.css`** (Copy as CSS)  | Named layers, auto-layout properties, typography metrics, design-token names  | Any hierarchy at all — the dump is flat     |
+| **`.png`** (a screenshot) | Figma's own blue measurement overlays, and what the designer chose to frame   | Nothing machine-readable                    |
+
+**Ask for the `.svg` and the `.css` together, and do not start until you have both.** The two
+are complements, not alternatives: the SVG is the only export you can both look at and
+measure, and the CSS is the only one that names layers and records type. A PNG earns its place
+only when it is a _screenshot_ carrying dev-mode annotations — a PNG _render_ of the same frame
+adds nothing the SVG does not. None of the three tells you the colours.
+
+Say what you are missing and what it would settle, in one line — "I have the SVG; the `.css`
+export would give me the font sizes and whether these cards Hug or Fill" — and wait. Every
+number in your diff has to trace back to something in an export or to a token; a plausible
+`17px` you inferred from a 12px outlined glyph is worse than an open question, because it
+survives review as though it had been specified. If the pair genuinely cannot be produced, say
+in the write-up which numbers are therefore guesses.
+
+## 1. Read the export before touching code
+
+### From an `.svg` — look at it, then measure it
+
+Rasterise it and actually open the image. Figma outlines text on export, so this needs no
+webfonts and matches the frame exactly:
+
+```bash
+magick -density 144 <export.svg> <scratch>/frame.png    # then read frame.png
+```
+
+(If the render looks wrong, ImageMagick fell back to its own SVG renderer — check for
+`RSVG` in `magick -list format | grep SVG`, or screenshot the file in Playwright instead.)
+
+Then dump the geometry with {%resource:dump-figma-svg.py%} — every shape in document order,
+indented by group nesting, with absolute coordinates:
+
+```bash
+python3 dump-figma-svg.py <export.svg>
+```
+
+It closes with two summaries worth reading first: repeated rect sizes, which say _one
+component rendered N times_ where the CSS dump would show N unrelated frames; and the measured
+gaps between rects that share a top edge, which is the auto-layout gap without having to
+believe a label.
+
+What the SVG does **not** carry:
+
+- **Layer names.** Nothing is called `Card` or `Badge`; you match shapes to the picture.
+- **Auto-layout intent.** `Hug` vs `Fixed` vs `Fill` is gone, so a width you read off is the
+  width _at this one size_, not a rule. Derive padding and gaps from the coordinates, and
+  treat a child width as content-driven until the picture or the CSS dump says otherwise.
+- **Typography.** Outlined text is a `<path>`; the dumper labels the wide ones `text?` and
+  boxes them, which places a text run but tells you nothing about `font-size` or
+  `line-height`. If the designer exported with _Outline Text_ off, `<text>` nodes survive and
+  the dumper prints their font metrics and strings — take them when you get them.
+
+Two numbers to read carefully: a **stroke is centred**, so a 32px circle with a 1px border
+exports as `31 × 31` at `.5` offsets — add the stroke width back before comparing. And an
+**outlined glyph box is the ink**, not the line box: a 17px/20px title measures ~12px tall,
+the same cap-trim the CSS dump reports, so never match a text node's height.
+
+### From a `.css` dump — names, intent and type metrics
+
+Never grep the raw file — its layout defeats naive parsing (see the traps below). Run
+{%resource:dump-figma-layers.py%}:
+
+```bash
+python3 dump-figma-layers.py <export.css>                    # every layer, artwork dropped
+python3 dump-figma-layers.py <export.css> '^(Widget|Frame|Card)'   # only what you name
+```
+
+Then work out the frame's box model top-down — outer frame width and padding, then each
+child's `width`/`gap`/`flex-grow` — and write the ladder down before you start editing, so you
+can tell a deliberate design decision from a Figma artefact.
+
+### Whatever you have, look at the picture before you decide what to build
+
+The CSS dump is a **flat** sequence of layers with no nesting whatsoever, so the tree is not in
+it; the SVG has the tree but no names. The image is what disambiguates:
+
+- **Hierarchy and reading order** — which layer contains which. The only other clue in the CSS
+  is `order:` inside a sibling run, which does not cross frames.
+- **Repetition vs distinct layers.** Six blocks with identical declarations are one component
+  rendered six times. The CSS looks like six unrelated frames.
+- **Multiple states in one board.** Frames are routinely laid out side by side as
+  default / hover / selected / empty, with a pink cursor marking the interaction. The CSS
+  gives you every state flattened together with nothing saying which is which, so a number
+  read blind may belong to a hover state you are not building.
+- **Figma's own measurement overlays.** Blue annotations like `396 × 401 Hug` or `347 × 23`
+  are authoritative and frequently _absent_ from the CSS — `Hug` in particular tells you a
+  dimension is content-driven, which no declaration in the export records. These live only in
+  a canvas _screenshot_; a frame export of any format drops them.
+- **What is decoration.** Cursors, callout arrows and section captions painted on the board
+  are not part of the component, but they do emit layers.
+
+### Traps in the `.css` export itself
+
+- **Sub-comments carry the real properties.** Figma writes `/* Auto layout */`,
+  `/* Inside auto layout */`, `/* or 16px */` and token names like
+  `/* Brand/Chalk White/500 */` _between_ a layer's declarations. A parser that starts a new
+  layer at every comment reports frames with **zero properties** and swallows the geometry.
+  The dumper folds them in — it decides by the blank line that follows a real layer name, not
+  by the name, so component layers called `Profile/Badge` survive.
+- **Frame labels lie.** A frame _named_ "Widget 636px" routinely has `width: 640px`, and a
+  label like "8 rows = 564px" often does not reconcile with the grid it sits in. Trust the
+  declarations, never the label.
+- **Text heights are cap-trimmed.** With `leading-trim: both; text-edge: cap`, a 17px/20px
+  title reports `height: 12px`. Compare `font-size`, `line-height` and `letter-spacing`;
+  never compare a text node's height.
+- **Absolute `left`/`top`** are canvas coordinates of the whole board. Only the _differences_
+  within one frame mean anything.
+
+## 2. Decide what the export is allowed to dictate
+
+- **Authoritative:** geometry and typography metrics — widths, padding, gaps, `flex-grow`,
+  border radius, font size / weight / line-height / letter-spacing, and the breakpoints at
+  which the layout changes.
+- **Never authoritative: colour.** Backgrounds, text, borders and interaction states resolve
+  from the surface and colour theming tokens — see {%skill:theming%}. A hex in the
+  export is information about the _designer's_ palette, not a value to paste. Where the
+  export's colour and the token disagree, keep the token and note the delta for the design
+  review; the export can be wrong about contrast in a way the tokens are not. This holds
+  hardest for an SVG, whose fills are exact and therefore tempting: an exact wrong answer is
+  still wrong.
+- **Radius and spacing snap to the scale.** Round to the nearest token rather than emitting an
+  arbitrary value, and say so if the export's number is more than a step away.
+
+## 3. Ask before making a structural choice
+
+Matching numbers is mechanical; the choices around them are not. Stop and ask when the export
+implies:
+
+- a **breakpoint strategy** — container queries with an exact ladder vs a retuned
+  `auto-fill`/`auto-fit` grid;
+- **shared-component churn** — a new variant on a component other screens already use, vs a
+  local override;
+- a **scroll region** — which part scrolls and what stays pinned;
+- **fixed sizing** where the component is currently fluid, or the reverse;
+- anything the export shows that the API does not yet return.
+
+Colour deltas are informational — report them, do not block on them.
+
+## 4. Measure the real thing, don't eyeball it
+
+A build passing proves nothing about geometry. Render the component's real markup against the
+**production stylesheet** and read the computed boxes back. {%resource:measure-template.mjs%}
+is a working starting point; copy it into a scratch directory with the compiled stylesheet
+beside it:
+
+```bash
+# whatever your build emits — the point is a real, fully compiled stylesheet
+cp dist/apps/<app>/browser/styles-*.css <scratch>/styles.css
+node <scratch>/measure-template.mjs
+```
+
+Confirm the arbitrary utilities you wrote actually compiled — a typo in
+`@min-[392px]` fails silently:
+
+```bash
+grep -oE '@container \(width >= [0-9]+px\)|\.(h-15|rounded-sm)\{[^}]*\}' dist/apps/<app>/browser/styles-*.css | sort -u
+```
+
+Harness gotchas, each of which will cost you an hour:
+
+- **`page.setContent()` renders on `about:blank`, which blocks `file://` subresources** — the
+  stylesheet silently never loads. Write a real HTML file and `page.goto('file://…')`.
+- **Never lay the probes out in a flex _row_.** They shrink, and container queries then report
+  results for a width the component would never see. Stack them in a column at explicit widths.
+- **The harness has no webfonts** unless you copy the `@font-face` sources too. Text runs
+  ~1px wide of reality, so a label that wraps in the harness may well fit in the app. Check
+  before calling a wrap a defect.
+- Playwright is CommonJS and unresolvable from a scratch directory — `createRequire` against
+  the repo root, as the template does. The same applies when driving a story:
+  {%skill:verify-in-storybook%}.
+
+## 5. Close the loop
+
+Report the measured numbers next to the export's, per width — not "matches the design". Say
+explicitly which parts of the export you deliberately did **not** implement and why (colour
+kept as tokens, a label the product decided never to render, a field the API lacks). Then
+delete the export files once their component is signed off, so the folder always shows only
+what is still outstanding.

package/content/skills/figma-export/dump-figma-layers.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Dump the properties of every layer in a Figma "copy as CSS" export, in document order.
+
+    python3 dump-figma-layers.py <export.css> ['<name regex>']
+
+Without a regex every layer is printed except obvious vector artwork. With one, only the
+layers whose name matches it.
+
+Figma emits sub-comments — `/* Auto layout */`, `/* Inside auto layout */`, `/* or 16px */`
+and design-token names like `/* Brand/Chalk White/500 (base) */` — that carry properties
+belonging to the layer named above them. They are folded into that layer rather than treated
+as new ones: a parser that splits on every comment reports frames with zero properties.
+"""
+
+import re
+import sys
+
+COMMENT = re.compile(r'^/\* (.+) \*/$')
+LAYOUT_NOTE = re.compile(r'^(Auto layout|Inside auto layout|or [\d.]+px|Hug|Fixed|Fill|Effect style)$')
+ARTWORK = re.compile(
+    r'^(Polygon|Vector|Ellipse|Rectangle \d|Star|Union|Subtract|Group|Mask|Clip'
+    r'|Texture|Frame \d{6,})'
+)
+
+
+def read_blocks(path):
+    """Yield ('comment', name) and ('prop', text), skipping Figma's multi-line prose notes."""
+    lines = [line.rstrip('\n') for line in open(path)]
+    index, total = 0, len(lines)
+
+    while index < total:
+        stripped = lines[index].strip()
+
+        if stripped.startswith('/*') and not stripped.endswith('*/'):
+            while index < total and not lines[index].rstrip().endswith('*/'):
+                index += 1
+            index += 1
+            continue
+
+        comment = COMMENT.match(stripped)
+
+        if comment:
+            following = lines[index + 1].strip() if index + 1 < total else ''
+            yield 'comment', comment.group(1), following
+        elif ':' in stripped and not stripped.startswith('/*'):
+            yield 'prop', stripped, ''
+
+        index += 1
+
+
+def main():
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+
+    path = sys.argv[1]
+    match = re.compile(sys.argv[2]).search if len(sys.argv) > 2 else None
+    show, index = False, 0
+
+    for kind, text, following in read_blocks(path):
+        if kind == 'prop':
+            if show:
+                print(f'    {text}')
+            continue
+
+        # A layer name is followed by a blank line; a sub-comment sits directly on top of the
+        # declarations it annotates. The name list covers the few notes Figma writes before
+        # another comment, where that spacing rule cannot decide.
+        is_declaration = ':' in following and not following.startswith('/*')
+
+        if is_declaration or LAYOUT_NOTE.match(text):
+            if show:
+                print(f'    /* {text} */')
+            continue
+
+        index += 1
+        show = match(text) is not None if match else not ARTWORK.match(text)
+
+        if show:
+            print(f'\n--- [{index}] {text}')
+
+
+if __name__ == '__main__':
+    main()

package/content/skills/figma-export/dump-figma-svg.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Dump the box tree of a Figma SVG export: every shape with absolute coordinates.
+
+    python3 dump-figma-svg.py <export.svg>
+
+Prints one line per drawn element in document order, indented by group nesting, then a
+summary of repeated shapes and of the gaps between shapes that share a row.
+
+An SVG export has no layer names and — because Figma outlines text on export — no strings
+or font metrics. What it does have is exact geometry: every rect carries its own x/y/
+width/height/rx, so padding and gaps are differences you can read off rather than numbers
+you have to trust a label for. Outlined text is measured by the bounding box of its path
+coordinates, which runs a fraction of a pixel wide because Bezier control points sit
+outside the curve — enough to place a text run, not to size a glyph.
+"""
+
+import re
+import sys
+import xml.etree.ElementTree as ET
+
+SVG_NS = '{http://www.w3.org/2000/svg}'
+TRANSLATE = re.compile(r'translate\(\s*([-\d.]+)[\s,]+([-\d.]+)\s*\)')
+TOKEN = re.compile(r'([MmLlHhVvCcSsQqTtAaZz])|(-?\d*\.?\d+(?:e[-+]?\d+)?)', re.IGNORECASE)
+ARITY = {'m': 2, 'l': 2, 'h': 1, 'v': 1, 'c': 6, 's': 4, 'q': 4, 't': 2, 'a': 7, 'z': 0}
+SKIP = {'defs', 'clipPath', 'mask', 'filter', 'linearGradient', 'radialGradient', 'pattern'}
+
+
+def tag_of(element):
+    return element.tag[len(SVG_NS) :] if element.tag.startswith(SVG_NS) else element.tag
+
+
+def number(element, name, fallback=0.0):
+    try:
+        return float(element.get(name, fallback))
+    except ValueError:
+        return fallback
+
+
+def translation(element):
+    match = TRANSLATE.search(element.get('transform') or '')
+
+    return (float(match.group(1)), float(match.group(2))) if match else (0.0, 0.0)
+
+
+def path_points(data):
+    """Every point a path visits, control points included. `H`/`V`/`A` take counts of their
+    own, so pairing the numbers off two at a time reports a box the shape never occupies."""
+    tokens = TOKEN.findall(data)
+    index, command, x, y = 0, 'm', 0.0, 0.0
+
+    while index < len(tokens):
+        letter, value = tokens[index]
+
+        if letter:
+            command = letter
+            index += 1
+
+            if command.lower() == 'z':
+                continue
+
+        arity = ARITY[command.lower()]
+        args = [float(tokens[index + step][1]) for step in range(arity) if index + step < len(tokens)]
+
+        if len(args) < arity:
+            return
+
+        index += arity
+        relative = command.islower()
+
+        if command.lower() == 'h':
+            x = x + args[0] if relative else args[0]
+        elif command.lower() == 'v':
+            y = y + args[0] if relative else args[0]
+        else:
+            pairs = [(args[5], args[6])] if command.lower() == 'a' else list(zip(args[0::2], args[1::2]))
+
+            for point_x, point_y in pairs:
+                yield (x + point_x, y + point_y) if relative else (point_x, point_y)
+
+            x, y = (x + pairs[-1][0], y + pairs[-1][1]) if relative else pairs[-1]
+
+        yield x, y
+
+        if command == 'M':
+            command = 'L'
+        elif command == 'm':
+            command = 'l'
+
+
+def path_box(data):
+    points = list(path_points(data))
+    xs, ys = [point[0] for point in points], [point[1] for point in points]
+
+    if not xs:
+        return None
+
+    return min(xs), min(ys), max(xs) - min(xs), max(ys) - min(ys)
+
+
+def box_of(element):
+    name = tag_of(element)
+
+    if name in ('rect', 'image'):
+        return number(element, 'x'), number(element, 'y'), number(element, 'width'), number(element, 'height')
+
+    if name == 'path':
+        return path_box(element.get('d') or '')
+
+    if name in ('polygon', 'polyline'):
+        return path_box('M' + (element.get('points') or ''))
+
+    if name == 'circle':
+        radius = number(element, 'r')
+
+        return number(element, 'cx') - radius, number(element, 'cy') - radius, radius * 2, radius * 2
+
+    if name == 'ellipse':
+        rx, ry = number(element, 'rx'), number(element, 'ry')
+
+        return number(element, 'cx') - rx, number(element, 'cy') - ry, rx * 2, ry * 2
+
+    if name == 'line':
+        x1, y1 = number(element, 'x1'), number(element, 'y1')
+
+        return x1, y1, number(element, 'x2') - x1, number(element, 'y2') - y1
+
+    return None
+
+
+def trim(value):
+    return f'{value:.3f}'.rstrip('0').rstrip('.')
+
+
+def walk(element, offset, depth, boxes):
+    for child in element:
+        name = tag_of(child)
+
+        if name in SKIP:
+            continue
+
+        dx, dy = translation(child)
+        origin = (offset[0] + dx, offset[1] + dy)
+
+        if name in ('g', 'svg'):
+            print(f'{"  " * depth}<{name}>' + (f' translate({trim(dx)} {trim(dy)})' if (dx or dy) else ''))
+            walk(child, origin, depth + 1, boxes)
+            continue
+
+        if name == 'text':
+            content = ' '.join(''.join(child.itertext()).split())
+            metrics = ' '.join(
+                f'{key}={child.get(key)}'
+                for key in ('font-family', 'font-size', 'font-weight', 'letter-spacing')
+                if child.get(key)
+            )
+            x, y = number(child, 'x') + origin[0], number(child, 'y') + origin[1]
+            print(f'{"  " * depth}{"text":<6} {trim(x):>9} {trim(y):>8}  {metrics}  "{content}"')
+            continue
+
+        box = box_of(child)
+
+        if box is None:
+            continue
+
+        x, y, width, height = box[0] + origin[0], box[1] + origin[1], box[2], box[3]
+        radius = child.get('rx') if name == 'rect' else None
+        paint = child.get('fill') or child.get('stroke') or ''
+        detail = f' r={radius}' if radius else ''
+        detail += f' {"stroke" if child.get("stroke") else "fill"}={paint}' if paint and paint != 'none' else ''
+        label = 'text?' if name == 'path' and width >= height * 3 else name
+
+        print(f'{"  " * depth}{label:<6} {trim(x):>9} {trim(y):>8}  {trim(width):>8} × {trim(height):<8}{detail}'.rstrip())
+        boxes.append((x, y, width, height, name, radius, paint))
+
+
+def summarise(boxes):
+    shapes = {}
+
+    for x, y, width, height, name, radius, paint in boxes:
+        if name != 'rect':
+            continue
+
+        shapes.setdefault((round(width, 2), round(height, 2), radius), []).append((x, y, paint))
+
+    repeats = {key: hits for key, hits in shapes.items() if len(hits) > 1}
+
+    if repeats:
+        print('\nRepeated rects — one component rendered N times, not N designs:')
+
+        for (width, height, radius), hits in sorted(repeats.items(), key=lambda item: -len(item[1])):
+            fills = {paint for _, _, paint in hits}
+            varies = f', {len(fills)} fills' if len(fills) > 1 else ''
+            print(f'  {len(hits)}× {trim(width)} × {trim(height)}' + (f' r={radius}' if radius else '') + varies)
+
+    rows = {}
+
+    for x, y, width, height, name, _, _ in boxes:
+        if name == 'rect':
+            rows.setdefault(round(y, 2), set()).add((x, width))
+
+    printed = False
+
+    for y, hits in sorted(rows.items()):
+        spans, edge = [], None
+
+        for x, width in sorted(hits):
+            if edge is not None and x >= edge:
+                spans.append(round(x - edge, 2))
+
+            edge = max(edge or 0, x + width)
+
+        if not spans:
+            continue
+
+        if not printed:
+            print('\nGaps between rects sharing a top edge — the auto-layout gap, measured:')
+            printed = True
+
+        print(f'  y={trim(y):<8} {len(spans) + 1} columns, gaps: {", ".join(trim(span) for span in spans)}')
+
+
+def main():
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+
+    root = ET.parse(sys.argv[1]).getroot()
+    boxes = []
+
+    print(f'canvas {root.get("width")} × {root.get("height")}  viewBox={root.get("viewBox")}\n')
+    walk(root, (0.0, 0.0), 0, boxes)
+    summarise(boxes)
+
+
+if __name__ == '__main__':
+    main()