@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/_lib/svg_geometry.ts

@@ -0,0 +1,480 @@
+/**
+ * svg_geometry — the numeric readings over SVG geometry: path data, points
+ * lists, and the box of a statically-sized element.
+ *
+ * Split out of `svg_rules` because `svg_rules` crossed the 1,500-line
+ * source-size ceiling while the completion review of
+ * `road-to-svg-review-followups` was being remediated, and a ratchet only
+ * turns one way. This block is the extraction that costs nothing to read: it
+ * takes numbers and returns numbers, it reports no finding, and it shares no
+ * state with the rules — the two rules that consume it (`svg-geometry-outside-
+ * viewbox`, `svg-structure-unparseable-path`) stay where the other rules are.
+ *
+ * `SvgElement` is imported as a TYPE only, so the import is erased and the two
+ * modules carry no runtime edge in either direction.
+ */
+
+import type { SvgElement } from './svg_rules.js';
+
+export interface Box {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+
+/**
+ * The box of an element whose geometry is fully numeric and untransformed.
+ *
+ * Returns `null` for anything else — a transform, a percentage, a unit, a
+ * `path`. That conservatism is the rule's whole safety margin: a box this
+ * function guesses at is a box the "entirely outside" test would flag wrongly.
+ */
+export function staticBox(el: SvgElement): Box | null {
+    if (el.attrs['transform'] || el.attrs['style']?.includes('transform')) return null;
+    const num = (k: string): number | null => {
+        const v = el.attrs[k];
+        if (v === undefined) return null;
+        if (!/^-?\d+(\.\d+)?$/.test(v.trim())) return null;
+        return Number(v);
+    };
+    /**
+     * A coordinate that defaults to 0 when ABSENT — and refuses the element
+     * when present and unreadable.
+     *
+     * Finding 7 of this change's second completion review. `num(k) ?? 0`
+     * conflated the two, so `<rect x="50%" width="10" height="10"/>` read as
+     * `x = 0`: a percentage, which this function's own doc promises to refuse,
+     * silently became a number. The rule that reads this box then reported an
+     * element outside the viewBox that is not, and missed one that is — a
+     * wrong answer in both directions, from a function whose entire safety
+     * margin is that it returns `null` when it cannot be sure.
+     */
+    const originOr0 = (k: string): number | null => (el.attrs[k] === undefined ? 0 : num(k));
+    switch (el.name) {
+        case 'rect': {
+            const x = originOr0('x');
+            const y = originOr0('y');
+            const w = num('width');
+            const h = num('height');
+            if (x === null || y === null || w === null || h === null) return null;
+            return { minX: x, minY: y, maxX: x + w, maxY: y + h };
+        }
+        case 'circle': {
+            const cx = originOr0('cx');
+            const cy = originOr0('cy');
+            const r = num('r');
+            if (cx === null || cy === null || r === null) return null;
+            return { minX: cx - r, minY: cy - r, maxX: cx + r, maxY: cy + r };
+        }
+        case 'ellipse': {
+            const cx = originOr0('cx');
+            const cy = originOr0('cy');
+            const rx = num('rx');
+            const ry = num('ry');
+            if (cx === null || cy === null || rx === null || ry === null) return null;
+            return { minX: cx - rx, minY: cy - ry, maxX: cx + rx, maxY: cy + ry };
+        }
+        case 'line': {
+            const x1 = num('x1');
+            const y1 = num('y1');
+            const x2 = num('x2');
+            const y2 = num('y2');
+            if (x1 === null || y1 === null || x2 === null || y2 === null) return null;
+            return {
+                minX: Math.min(x1, x2),
+                minY: Math.min(y1, y2),
+                maxX: Math.max(x1, x2),
+                maxY: Math.max(y1, y2),
+            };
+        }
+        default:
+            return null;
+    }
+}
+
+/**
+ * The extent of a path's own points, with relative commands walked properly.
+ *
+ * Finding 2.1 of `road-to-svg-rules-in-the-dispatch-path`. The icon reference
+ * reader used to scrape `d` with `/(-?[\d.]+)[\s,]+(-?[\d.]+)/g`, which reads
+ * every number pair as an absolute coordinate — so `m 2 2 l 4 0` was read as
+ * the points (2,2) and (4,0) rather than (2,2) and (6,2). That is not a
+ * rounding error: a path drawn entirely with relative commands reports an
+ * extent anchored at the origin.
+ *
+ * APPROXIMATE, AND DELIBERATELY SO. Curve control points are included rather
+ * than the curve's true hull, which can over-estimate a Bézier's extent by
+ * the control polygon. The alternative is a full flattener, and the consumer
+ * here is a padding comparison against other icons measured exactly the same
+ * way — a shared conservative bound is a comparison; a precise bound on one
+ * side and a loose one on the other is finding 2.2.
+ *
+ * Returns null for an empty or unparseable `d`, which is a separate finding
+ * (`pathDataError`) and not this function's to report.
+ */
+export function pathExtent(d: string): Box | null {
+    const tokens = tokenisePath(d);
+    if (!tokens) return null;
+    const argCount: Record<string, number> = { m: 2, l: 2, t: 2, h: 1, v: 1, c: 6, s: 4, q: 4, a: 7, z: 0 };
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    const see = (x: number, y: number): void => {
+        if (!Number.isFinite(x) || !Number.isFinite(y)) return;
+        minX = Math.min(minX, x);
+        maxX = Math.max(maxX, x);
+        minY = Math.min(minY, y);
+        maxY = Math.max(maxY, y);
+    };
+    // Current point, and the subpath start `Z` returns to.
+    let cx = 0;
+    let cy = 0;
+    let sx = 0;
+    let sy = 0;
+    let i = 0;
+    let cmd = '';
+    let rel = false;
+    while (i < tokens.length) {
+        const tok = tokens[i] as string;
+        if (/^[a-zA-Z]$/.test(tok)) {
+            cmd = tok.toLowerCase();
+            rel = tok === tok.toLowerCase();
+            i += 1;
+            if (cmd === 'z') {
+                cx = sx;
+                cy = sy;
+                continue;
+            }
+            if (!(cmd in argCount)) return null;
+        } else if (cmd === '' || cmd === 'z') {
+            // A number where no repeatable command is open.
+            return null;
+        }
+        const need = argCount[cmd] as number;
+        if (need === 0) continue;
+        const args: number[] = [];
+        while (args.length < need && i < tokens.length && !/^[a-zA-Z]$/.test(tokens[i] as string)) {
+            args.push(Number(tokens[i]));
+            i += 1;
+        }
+        if (args.length < need) return null;
+        switch (cmd) {
+            case 'h': {
+                cx = rel ? cx + (args[0] as number) : (args[0] as number);
+                break;
+            }
+            case 'v': {
+                cy = rel ? cy + (args[0] as number) : (args[0] as number);
+                break;
+            }
+            case 'a': {
+                // rx ry rotation large-arc sweep x y — only the last pair is a
+                // point, and the SWEEP between the two is most of the shape.
+                //
+                // Finding 4 of the fourth completion review: this used to take
+                // the endpoints alone, so `M 10 12 A 20 20 0 0 1 90 12` read as
+                // a flat box of zero height while the curve reaches y = -28.
+                // Everything downstream is a comparison — the icon-grid padding
+                // on both sides, and the `data-hole` and translucent masks the
+                // grounds reading excludes by box — so a too-small extent is a
+                // wrong NUMBER, not a missing one, which is the failure this
+                // branch keeps finding in its own work.
+                const ex = rel ? cx + (args[5] as number) : (args[5] as number);
+                const ey = rel ? cy + (args[6] as number) : (args[6] as number);
+                for (const [px, py] of arcExtremes(
+                    cx,
+                    cy,
+                    ex,
+                    ey,
+                    args[0] as number,
+                    args[1] as number,
+                    args[2] as number,
+                    (args[3] as number) !== 0,
+                    (args[4] as number) !== 0,
+                )) {
+                    see(px, py);
+                }
+                cx = ex;
+                cy = ey;
+                break;
+            }
+            default: {
+                // Every remaining command is a run of (x, y) pairs; the last
+                // pair is the new current point and the earlier ones are
+                // control points, which are included as the bound above says.
+                for (let k = 0; k + 1 < args.length; k += 2) {
+                    const px = rel ? cx + (args[k] as number) : (args[k] as number);
+                    const py = rel ? cy + (args[k + 1] as number) : (args[k + 1] as number);
+                    see(px, py);
+                    if (k + 2 >= args.length) {
+                        cx = px;
+                        cy = py;
+                    }
+                }
+                break;
+            }
+        }
+        see(cx, cy);
+        if (cmd === 'm') {
+            // `m`/`M` opens a subpath at its FIRST pair; `Z` returns there, not
+            // to wherever the run ended. One `need`-sized group is read per
+            // iteration, so this pair is that start.
+            sx = cx;
+            sy = cy;
+            // A repeated `m` argument group is an implicit lineto, per the path
+            // grammar — so the command for the next group is `l`, not `m`.
+            cmd = 'l';
+        }
+    }
+    if (!Number.isFinite(minX)) return null;
+    return { minX, minY, maxX, maxY };
+}
+
+/**
+ * Path-data tokens, with the two shapes a number-or-letter alternation misses.
+ *
+ * Finding 17 of this change's completion review. `a 5 5 0 0130 30` is valid:
+ * `large-arc-flag` and `sweep-flag` are single digits and the grammar lets
+ * them run together with what follows. The old regex read `0130` as ONE
+ * number, shifted every argument of that command and every relative command
+ * after it, and produced a silently WRONG extent rather than `null` — so the
+ * grid padding degraded to a wrong number instead of to `unverified`. A
+ * leading `+`, also legal, was dropped by the same alternation.
+ *
+ * So the arc command is tokenised positionally: four numbers, then two single
+ * digits, then two numbers. Everything else keeps the general form.
+ */
+export function tokenisePath(d: string): string[] | null {
+    const NUM = /[+-]?(?:\d*\.\d+|\d+\.?)(?:[eE][+-]?\d+)?/y;
+    const FLAG = /[01]/y;
+    const SEP = /[\s,]*/y;
+    const out: string[] = [];
+    const text = d.trim();
+    let i = 0;
+    let cmd = '';
+    const eat = (re: RegExp): string | null => {
+        re.lastIndex = i;
+        const m = re.exec(text);
+        if (m === null) return null;
+        i = re.lastIndex;
+        return m[0];
+    };
+    const skip = (): void => {
+        void eat(SEP);
+    };
+    while (i < text.length) {
+        skip();
+        if (i >= text.length) break;
+        const ch = text[i] as string;
+        if (/[a-zA-Z]/.test(ch)) {
+            cmd = ch;
+            out.push(ch);
+            i += 1;
+            continue;
+        }
+        if (cmd.toLowerCase() === 'a') {
+            // rx ry rotation | large-arc sweep | x y
+            for (let k = 0; k < 3; k += 1) {
+                skip();
+                const n = eat(NUM);
+                if (n === null) return null;
+                out.push(n);
+            }
+            for (let k = 0; k < 2; k += 1) {
+                skip();
+                const f = eat(FLAG);
+                if (f === null) return null;
+                out.push(f);
+            }
+            for (let k = 0; k < 2; k += 1) {
+                skip();
+                const n = eat(NUM);
+                if (n === null) return null;
+                out.push(n);
+            }
+            continue;
+        }
+        const n = eat(NUM);
+        if (n === null) return null;
+        out.push(n);
+    }
+    return out.length > 0 ? out : null;
+}
+
+/**
+ * The axis extremes an elliptical arc actually reaches, endpoints included.
+ *
+ * The endpoint parameterisation SVG writes is converted to the centre
+ * parameterisation the geometry needs (F.6.5 of the SVG 1.1 implementation
+ * notes), and then each of the four axis-aligned extremes of the ellipse is
+ * kept when its angle lies inside the swept range. For a rotated ellipse the
+ * extremes are not at the axis endpoints, so the angles are derived from the
+ * rotation rather than assumed.
+ *
+ * Degenerate input — a zero radius, or coincident endpoints — is a straight
+ * line per the spec, and the endpoints are then the whole extent.
+ */
+function arcExtremes(
+    x1: number,
+    y1: number,
+    x2: number,
+    y2: number,
+    rxIn: number,
+    ryIn: number,
+    rotationDeg: number,
+    largeArc: boolean,
+    sweep: boolean,
+): Array<[number, number]> {
+    const ends: Array<[number, number]> = [
+        [x1, y1],
+        [x2, y2],
+    ];
+    let rx = Math.abs(rxIn);
+    let ry = Math.abs(ryIn);
+    if (rx === 0 || ry === 0 || (x1 === x2 && y1 === y2)) return ends;
+
+    const phi = (rotationDeg * Math.PI) / 180;
+    const cosP = Math.cos(phi);
+    const sinP = Math.sin(phi);
+    const dx2 = (x1 - x2) / 2;
+    const dy2 = (y1 - y2) / 2;
+    const x1p = cosP * dx2 + sinP * dy2;
+    const y1p = -sinP * dx2 + cosP * dy2;
+
+    // Scale the radii up when they are too small to span the endpoints (F.6.6).
+    const lambda = (x1p * x1p) / (rx * rx) + (y1p * y1p) / (ry * ry);
+    if (lambda > 1) {
+        const k = Math.sqrt(lambda);
+        rx *= k;
+        ry *= k;
+    }
+
+    const num = rx * rx * ry * ry - rx * rx * y1p * y1p - ry * ry * x1p * x1p;
+    const den = rx * rx * y1p * y1p + ry * ry * x1p * x1p;
+    if (den === 0) return ends;
+    const coef = (largeArc === sweep ? -1 : 1) * Math.sqrt(Math.max(0, num / den));
+    const cxp = (coef * rx * y1p) / ry;
+    const cyp = (-coef * ry * x1p) / rx;
+    const ccx = cosP * cxp - sinP * cyp + (x1 + x2) / 2;
+    const ccy = sinP * cxp + cosP * cyp + (y1 + y2) / 2;
+
+    const angleOf = (px: number, py: number): number => {
+        const ux = (cosP * (px - ccx) + sinP * (py - ccy)) / rx;
+        const uy = (-sinP * (px - ccx) + cosP * (py - ccy)) / ry;
+        return Math.atan2(uy, ux);
+    };
+    const start = angleOf(x1, y1);
+    const end = angleOf(x2, y2);
+    const TAU = Math.PI * 2;
+    // Normalised sweep, in the direction the flag names.
+    let delta = end - start;
+    if (sweep && delta < 0) delta += TAU;
+    if (!sweep && delta > 0) delta -= TAU;
+
+    const within = (theta: number): boolean => {
+        let t = theta - start;
+        if (sweep) {
+            while (t < 0) t += TAU;
+            return t <= delta + 1e-9;
+        }
+        while (t > 0) t -= TAU;
+        return t >= delta - 1e-9;
+    };
+    const at = (theta: number): [number, number] => [
+        ccx + rx * Math.cos(theta) * cosP - ry * Math.sin(theta) * sinP,
+        ccy + rx * Math.cos(theta) * sinP + ry * Math.sin(theta) * cosP,
+    ];
+
+    const out: Array<[number, number]> = [...ends];
+    // The parameter angles at which x and y are stationary on the rotated
+    // ellipse; each has a partner half a turn away.
+    const tx = Math.atan2(-ry * sinP, rx * cosP);
+    const ty = Math.atan2(ry * cosP, rx * sinP);
+    for (const base of [tx, ty]) {
+        for (const theta of [base, base + Math.PI]) {
+            if (within(theta)) out.push(at(theta));
+        }
+    }
+    return out;
+}
+
+/** Extent of a `points` list (`<polygon>`, `<polyline>`). Absolute by definition. */
+export function pointsExtent(points: string): Box | null {
+    const nums = points.trim().match(/-?\d*\.?\d+(?:[eE][-+]?\d+)?/g);
+    if (!nums || nums.length < 2) return null;
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i + 1 < nums.length; i += 2) {
+        const x = Number(nums[i]);
+        const y = Number(nums[i + 1]);
+        if (!Number.isFinite(x) || !Number.isFinite(y)) continue;
+        minX = Math.min(minX, x);
+        maxX = Math.max(maxX, x);
+        minY = Math.min(minY, y);
+        maxY = Math.max(maxY, y);
+    }
+    return Number.isFinite(minX) ? { minX, minY, maxX, maxY } : null;
+}
+
+/**
+ * One element's own extent in user units, whichever way it was drawn.
+ *
+ * The union of `staticBox` (rect, circle, ellipse, line), `pathExtent` and
+ * `pointsExtent`. Finding 2.1's first half: a reference icon drawn with
+ * primitives used to yield no extent at all and was dropped from the set
+ * SILENTLY — after which the reading reported "no icon reference set was
+ * supplied" although one was.
+ *
+ * Returns null for a transformed element, inheriting `staticBox`'s refusal to
+ * guess at a transform, and for anything that carries no geometry.
+ */
+export function elementExtent(el: SvgElement): Box | null {
+    if (el.closing) return null;
+    if (el.attrs['transform'] || el.attrs['style']?.includes('transform')) return null;
+    if (el.name === 'path') return pathExtent(el.attrs['d'] ?? '');
+    if (el.name === 'polygon' || el.name === 'polyline') return pointsExtent(el.attrs['points'] ?? '');
+    return staticBox(el);
+}
+
+export function pathDataError(d: string): string | null {
+    const trimmed = d.trim();
+    if (!trimmed) return 'empty d attribute';
+    if (!/^[mM]/.test(trimmed)) return 'path data does not start with a moveto command';
+    const argCount: Record<string, number> = {
+        m: 2, l: 2, t: 2, h: 1, v: 1, c: 6, s: 4, q: 4, a: 7, z: 0,
+    };
+    // The SAME tokeniser `pathExtent` reads. Finding 5 of this change's second
+    // completion review: this one kept the superseded letter-or-number
+    // alternation, so `M 0 0 a 5 5 0 0130 30` — valid path data whose two arc
+    // flags are written without separators — read as five arguments where the
+    // arc takes seven, and was reported as an UNPARSEABLE PATH. Worse than
+    // finding 17's wrong extent: a finding against a correct file, from the
+    // rule whose job is to say a file cannot be read.
+    const tokens = tokenisePath(trimmed);
+    if (!tokens) {
+        return 'path data could not be read — a coordinate, an arc flag or a command letter is malformed';
+    }
+    let i = 0;
+    while (i < tokens.length) {
+        const tok = tokens[i] as string;
+        if (!/^[a-zA-Z]$/.test(tok)) return `unexpected token "${tok}" where a command letter was required`;
+        const cmd = tok.toLowerCase();
+        if (!(cmd in argCount)) return `unknown path command "${tok}"`;
+        const need = argCount[cmd] as number;
+        i += 1;
+        if (need === 0) continue;
+        let consumed = 0;
+        while (i < tokens.length && !/^[a-zA-Z]$/.test(tokens[i] as string)) {
+            i += 1;
+            consumed += 1;
+        }
+        if (consumed === 0 || consumed % need !== 0) {
+            return `command "${tok}" takes ${need} coordinate(s) per repetition, got ${consumed}`;
+        }
+    }
+    return null;
+}

package/src/scripts/_lib/svg_motion.ts

@@ -0,0 +1,208 @@
+/**
+ * svg_motion — the ONE reading of "does this file's reduced-motion route
+ * actually reach its SMIL animation".
+ *
+ * Two linters need the same answer and would otherwise disagree about it:
+ * `lint_svg_asset` (standalone `.svg`, step 1.1 of `road-to-svg-with-a-witness`)
+ * and `lint_design_quality`'s DQ4 (inline SVG inside HTML, step 1.3). A
+ * standalone file and an inline graphic hitting different definitions of
+ * "covered" is how a consumer ends up with one linter clearing what the other
+ * reds, for the same bytes.
+ *
+ * The measurement behind the `css-only` verdict (R4 of that roadmap): under an
+ * emulated `prefers-reduced-motion: reduce`, a page-level
+ * `svg * { animation: none !important }` left an `<animate>` moving `cx` from
+ * 20.2 to 76.8 in 700 ms. CSS `animation` and `transition` properties do not
+ * reach SMIL at all, so a file whose only route is one of them is covered by
+ * nothing — and reads, to a human and to a naive linter, exactly like a file
+ * that is covered.
+ */
+
+/** SMIL animation elements. `<set>` is included: it animates too. */
+export const SMIL_TAGS: ReadonlySet<string> = new Set([
+    'animate',
+    'animatetransform',
+    'animatemotion',
+    'animatecolor',
+    'set',
+]);
+
+const SMIL_MARKUP_RE = /<(animate|animateTransform|animateMotion|animateColor|set)\b/i;
+const REDUCED_MOTION_RE = /@media[^{]*prefers-reduced-motion/i;
+
+/** True when the markup carries any SMIL animation element. */
+export function hasSmilMarkup(content: string): boolean {
+    return SMIL_MARKUP_RE.test(content);
+}
+
+/** True when the markup carries any CSS/WAAPI animation. */
+export function hasCssAnimation(content: string): boolean {
+    return /@keyframes\s+[\w-]+/i.test(content) || /\banimation(?:-name)?\s*:/i.test(content);
+}
+
+/** True when a `prefers-reduced-motion` media query exists anywhere. */
+export function hasReducedMotionQuery(content: string): boolean {
+    return REDUCED_MOTION_RE.test(content);
+}
+
+// ---------------------------------------------------------------------------
+// A minimal CSS reader — enough to answer "what does this block declare"
+// ---------------------------------------------------------------------------
+
+export interface CssRule {
+    selector: string;
+    body: string;
+    /** 1-based line of the selector in the ORIGINAL document. */
+    line: number;
+    /** The nearest enclosing at-rule prelude, or `''`. */
+    atRule: string;
+}
+
+function lineIndexer(content: string): (offset: number) => number {
+    const starts: number[] = [0];
+    for (let i = 0; i < content.length; i++) if (content[i] === '\n') starts.push(i + 1);
+    return (offset: number): number => {
+        let lo = 0;
+        let hi = starts.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if ((starts[mid] as number) <= offset) lo = mid;
+            else hi = mid - 1;
+        }
+        return lo + 1;
+    };
+}
+
+function matchBrace(css: string, open: number): number {
+    let depth = 0;
+    for (let i = open; i < css.length; i++) {
+        if (css[i] === '{') depth += 1;
+        else if (css[i] === '}') {
+            depth -= 1;
+            if (depth === 0) return i;
+        }
+    }
+    return -1;
+}
+
+function collectRules(
+    css: string,
+    base: number,
+    atRule: string,
+    lineOf: (o: number) => number,
+    out: CssRule[],
+): void {
+    let i = 0;
+    while (i < css.length) {
+        const brace = css.indexOf('{', i);
+        if (brace === -1) break;
+        const prelude = css.slice(i, brace).trim();
+        const end = matchBrace(css, brace);
+        if (end === -1) break;
+        const body = css.slice(brace + 1, end);
+        if (prelude.startsWith('@')) {
+            collectRules(body, base + brace + 1, prelude, lineOf, out);
+        } else if (prelude) {
+            out.push({ selector: prelude, body, line: lineOf(base + i), atRule });
+        }
+        i = end + 1;
+    }
+}
+
+/** Every rule inside every `<style>` element, with its enclosing at-rule. */
+export function readCssRules(content: string): CssRule[] {
+    const rules: CssRule[] = [];
+    const lineOf = lineIndexer(content);
+    const styleRe = /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi;
+    let sm: RegExpExecArray | null;
+    while ((sm = styleRe.exec(content)) !== null) {
+        // Blank out comments while preserving newlines, so line numbers hold.
+        const css = (sm[1] ?? '').replace(/\/\*[\s\S]*?\*\//g, (c) => c.replace(/[^\n]/g, ' '));
+        const base = sm.index + (sm[0] ?? '').indexOf(sm[1] ?? '');
+        collectRules(css, base, '', lineOf, rules);
+    }
+    return rules;
+}
+
+/** Every rule of a bare stylesheet (a `.css` file, no `<style>` wrapper). */
+export function readStylesheetRules(css: string): CssRule[] {
+    const rules: CssRule[] = [];
+    const lineOf = lineIndexer(css);
+    const blanked = css.replace(/\/\*[\s\S]*?\*\//g, (c) => c.replace(/[^\n]/g, ' '));
+    collectRules(blanked, 0, '', lineOf, rules);
+    return rules;
+}
+
+/** Declarations of one rule body, lower-cased property → value. */
+export function declarationsOf(body: string): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const decl of body.split(';')) {
+        const idx = decl.indexOf(':');
+        if (idx === -1) continue;
+        const prop = decl.slice(0, idx).trim().toLowerCase();
+        if (!prop || prop.startsWith('@') || prop.includes('{')) continue;
+        out[prop] = decl.slice(idx + 1).trim();
+    }
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// The verdict
+// ---------------------------------------------------------------------------
+
+export type SmilVerdict =
+    /** No SMIL in this file — DQ4's CSS half still applies, this half does not. */
+    | 'no-smil'
+    /** SMIL with a route that can actually take effect on it. */
+    | 'routed'
+    /** SMIL with no `prefers-reduced-motion` query at all. */
+    | 'no-route'
+    /** SMIL whose only route writes `animation`/`transition` — which never reaches it (R4). */
+    | 'css-only';
+
+/**
+ * Does a reduced-motion route exist that can take effect on a SMIL subtree?
+ *
+ * Two kinds can: a declaration that is not an animation shorthand (a
+ * `display`/`visibility` switch, a swapped `fill`, a `d` override removes or
+ * replaces the animating subtree), and a `begin="indefinite"`, which says the
+ * animation does not start on its own.
+ *
+ * Deliberately generous in the "routed" direction. This rule ships advisory,
+ * and the cost of a false red here is a linter the agent learns to ignore —
+ * Risk 1 of the parent roadmap.
+ */
+export function reducedMotionReachesSmil(content: string): boolean {
+    const scoped = readCssRules(content).filter((r) => /prefers-reduced-motion/i.test(r.atRule));
+    for (const rule of scoped) {
+        for (const prop of Object.keys(declarationsOf(rule.body))) {
+            if (prop === 'animation' || prop.startsWith('animation-')) continue;
+            if (prop === 'transition' || prop.startsWith('transition-')) continue;
+            return true;
+        }
+    }
+    // A `<set>` is NOT a route, and treating it as one was a hole: `<set>` is
+    // itself a SMIL animation — it is in `SMIL_TAGS` — so a file that animates
+    // with one was its own reduced-motion branch, and both this rule and DQ4's
+    // SMIL half went silent on exactly the R4 case they exist to catch.
+    // `begin="indefinite"` stays, because it says something a `<set>` does not:
+    // the animation does not start on its own.
+    if (/begin\s*=\s*["']indefinite["']/i.test(content)) return true;
+    return false;
+}
+
+/** The whole SMIL reduced-motion reading for one document's bytes. */
+export function smilVerdict(content: string): SmilVerdict {
+    if (!hasSmilMarkup(content)) return 'no-smil';
+    if (!hasReducedMotionQuery(content)) return 'no-route';
+    return reducedMotionReachesSmil(content) ? 'routed' : 'css-only';
+}
+
+/** The first line carrying a SMIL element, 1-based; `1` when none is found. */
+export function firstSmilLine(content: string): number {
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        if (SMIL_MARKUP_RE.test(lines[i] ?? '')) return i + 1;
+    }
+    return 1;
+}