@event4u/agent-config 16.4.0 → 17.0.0

package/dist/cli/commands/uiRenderAssetFonts.js

@@ -0,0 +1,158 @@
+/**
+ * Which face painted each `<text>` — steps 1.1 and 1.2 of
+ * `road-to-type-with-a-witness`.
+ *
+ * The sentinel in `readAssetInPage` tells a family that resolved from one that
+ * did not, by comparing a measured width against an absent family. It cannot
+ * tell a face whose file failed from a face that never loaded, and it cannot
+ * see a requested weight the face does not carry. Both are read here from
+ * `document.fonts`, the renderer's own record of the faces it registered.
+ *
+ * No added wait. Measured on Chromium: a face the page uses holds the `load`
+ * event (a 2,000 ms delayed face, `load` at 2,019 ms, status `loaded`), so the
+ * navigation the witness already performs is the wait. One bounded
+ * `document.fonts.ready` wait runs ONLY when a declared face still reads
+ * `loading` — the face only a later script asks for — and a wait that ends
+ * with the face still loading is reported as `timeout`, never as a fallback.
+ */
+/** The bounded wait, in milliseconds, for a face still `loading` after `load`. */
+export const FACE_WAIT_MS = 3_000;
+/**
+ * In-page: for every `<text>`, the first family of its computed stack that
+ * registers an `@font-face`, and that family's state. A text whose stack names
+ * no registered family is not reported — the resolved flag already covers it.
+ *
+ * Self-contained: `page.evaluate` ships the source.
+ */
+function readFacesInPage() {
+    const svg = document.querySelector('svg');
+    if (!svg)
+        return [];
+    const unquote = (s) => s.trim().replace(/^["']|["']$/g, '').toLowerCase();
+    const faces = Array.from(document.fonts);
+    const all = Array.from(svg.querySelectorAll('*'));
+    const out = [];
+    for (let i = 0; i < all.length; i++) {
+        const el = all[i];
+        if (el.tagName.toLowerCase() !== 'text')
+            continue;
+        // Layout first: a face is requested by the layout that needs it, so a
+        // stack changed after `load` reads `unloaded` until something lays out.
+        try {
+            el.getBBox();
+        }
+        catch {
+            // An element that cannot be measured still has a computed style.
+        }
+        const cs = window.getComputedStyle(el);
+        const stack = cs.fontFamily.split(',').map(unquote);
+        let family = '';
+        let own = [];
+        for (const name of stack) {
+            const match = faces.filter((f) => unquote(f.family) === name);
+            if (match.length > 0) {
+                family = match[0]?.family.replace(/^["']|["']$/g, '') ?? name;
+                own = match;
+                break;
+            }
+        }
+        if (own.length === 0)
+            continue;
+        const statuses = own.map((f) => f.status);
+        let state = 'unloaded';
+        if (statuses.includes('loaded'))
+            state = 'loaded';
+        else if (statuses.includes('loading'))
+            state = 'loading';
+        else if (statuses.includes('error'))
+            state = 'error';
+        if (state === 'loaded') {
+            // Synthesis (1.2). Matching is on the @font-face DESCRIPTORS, which
+            // is what the renderer matches on. Emboldening runs when 600 or
+            // more is requested and no loaded face reaches 600; an oblique is
+            // synthesised when italic is requested and no loaded face is
+            // italic or oblique. `font-synthesis: none` turns both off.
+            const loaded = own.filter((f) => f.status === 'loaded');
+            const maxWeight = (w) => {
+                const parts = w.trim().split(/\s+/).map((p) => (p === 'bold' ? 700 : p === 'normal' ? 400 : Number(p)));
+                return Math.max(...parts.filter((n) => Number.isFinite(n)), 0);
+            };
+            const synthOff = (axis) => {
+                const longhand = cs.getPropertyValue(`font-synthesis-${axis}`).trim();
+                if (longhand !== '')
+                    return longhand === 'none';
+                return !cs.getPropertyValue('font-synthesis').includes(axis);
+            };
+            const requested = Number(cs.fontWeight) || 400;
+            const fauxBold = requested >= 600 && loaded.every((f) => maxWeight(f.weight) < 600) && !synthOff('weight');
+            const wantsSlant = cs.fontStyle !== 'normal';
+            const fauxSlant = wantsSlant && loaded.every((f) => f.style.trim() === 'normal') && !synthOff('style');
+            if (fauxBold || fauxSlant)
+                state = 'synthesised';
+        }
+        out.push({ index: i, family, state });
+    }
+    return out;
+}
+/** Resolves `true` when every face settled inside `ms`, `false` on the bound. */
+function waitForFacesInPage(ms) {
+    const ready = document.fonts.ready.then(() => true);
+    return Promise.race([ready, new Promise((r) => setTimeout(() => r(false), ms))]);
+}
+/**
+ * The face state of every `<text>` on the page, with the bounded wait applied
+ * only when a face still reads `loading`. `waited` says whether it ran.
+ */
+export async function readFaceStates(page, indices, waitMs = FACE_WAIT_MS) {
+    let raw = await page.evaluate(readFacesInPage);
+    let waited = false;
+    if (raw.some((r) => r.state === 'loading')) {
+        waited = true;
+        await page.evaluate(waitForFacesInPage, waitMs);
+        raw = await page.evaluate(readFacesInPage);
+    }
+    const wanted = indices ? new Set(indices) : null;
+    const readings = raw
+        .filter((r) => wanted === null || wanted.has(r.index))
+        .map((r) => ({ index: r.index, family: r.family, state: r.state === 'loading' ? 'timeout' : r.state }));
+    return { readings, waited };
+}
+/** Attach the face state to the text readings `applyGeometry` already made. */
+export async function applyFaceStates(page, reading) {
+    if (reading.texts.length === 0)
+        return;
+    const { readings } = await readFaceStates(page, reading.texts.map((t) => t.index));
+    const byIndex = new Map(readings.map((r) => [r.index, r]));
+    for (const t of reading.texts) {
+        const r = byIndex.get(t.index);
+        if (!r)
+            continue;
+        t.face_family = r.family;
+        t.face_state = r.state;
+    }
+}
+/** Findings for a face that did not paint as declared. */
+export function faceFindings(r) {
+    const out = [];
+    for (const t of r.texts) {
+        const label = `<text>${t.id ? ` #${t.id}` : ''}`;
+        if (t.face_state === 'error' || t.face_state === 'timeout' || t.face_state === 'unloaded') {
+            out.push({
+                rule: 'geometry/font-face-error',
+                severity: 'warning',
+                detail: `${label} declares "${t.face_family}" through @font-face, and that face reads ` +
+                    `${t.face_state}: the text was painted by a fallback, not by the declared face`,
+            });
+        }
+        else if (t.face_state === 'synthesised') {
+            out.push({
+                rule: 'geometry/font-synthesised',
+                severity: 'warning',
+                detail: `${label} requests a weight or style no loaded face of "${t.face_family}" carries, so the ` +
+                    'renderer synthesised it; load that face, or set `font-synthesis: none` on purpose',
+            });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=uiRenderAssetFonts.js.map

package/dist/cli/commands/uiRenderAssetGrid.js

@@ -0,0 +1,265 @@
+/**
+ * uiRenderAssetGrid — the incumbent icon grid, read from the set's own SVGs.
+ *
+ * Step E6 of `road-to-svg-with-a-witness`, carrying findings 2.1 and 2.2 of
+ * `road-to-svg-rules-in-the-dispatch-path`. Its own module because
+ * `uiRenderAsset.ts` is over the source-size budget and this is the most
+ * self-contained reading in it: no browser, no page, no shared state — bytes
+ * in, one grading out, which is also why its two findings are exercisable
+ * without a render.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { elementExtent, parseElements, readViewBox } from '../../scripts/lint_svg_asset.js';
+/**
+ * Elements whose contents DEFINE something rather than paint it.
+ *
+ * A shape inside one of these never appears on the canvas on its own, so it
+ * must not contribute to the graphic's extent. `<pattern>` and `<symbol>` join
+ * the three obvious ones for the same reason.
+ */
+const NON_RENDERING = new Set(['defs', 'clippath', 'mask', 'symbol', 'marker', 'pattern']);
+/**
+ * The elements that actually paint: everything outside a transformed subtree
+ * and outside a non-rendering container.
+ *
+ * Extracted by finding 9 of this change's second completion review. The extent
+ * reading did this walk and the stroke-width reading did not, so an icon whose
+ * clip path carried `stroke-width="8"` reported 8 as its stroke while its
+ * padding was measured from the 1.5 the viewer sees. Two readings of the same
+ * file disagreeing about which elements are in it is the shape a shared walk
+ * removes by construction — the previous fix widened the extent half and left
+ * the other, which is exactly how the pair came to disagree.
+ */
+function renderingElements(elements) {
+    const out = [];
+    const openSkips = [];
+    let skipDepth = 0;
+    for (const el of elements) {
+        if (el.closing) {
+            const was = openSkips.pop();
+            if (was === true)
+                skipDepth -= 1;
+            continue;
+        }
+        const carries = Boolean(el.attrs['transform'] || el.attrs['style']?.includes('transform')) ||
+            NON_RENDERING.has(el.name);
+        if (!el.selfClosing) {
+            openSkips.push(carries);
+            if (carries)
+                skipDepth += 1;
+        }
+        if (skipDepth > 0 || (el.selfClosing && carries))
+            continue;
+        out.push(el);
+    }
+    return out;
+}
+/**
+ * The centreline extent of one graphic's own geometry, in user units.
+ *
+ * Shared by the references and by the candidate — finding 2.2 is precisely
+ * that the two used to be measured by different methods, so the one thing this
+ * function must never grow is a second caller-specific branch.
+ *
+ * A TRANSFORM ANYWHERE ABOVE A SHAPE DISQUALIFIES IT, not only one on the
+ * shape. `elementExtent` refuses an element that carries its own `transform`,
+ * and a flat element list makes it easy to miss that a `<g transform="…">`
+ * moves everything inside it — measured here: a rect inside a rotated group
+ * read as if the group were not there, and the file reported a padding it does
+ * not have. The depth stack below is what carries the inheritance; without it
+ * the refusal is a half-refusal, which is worse than none because it looks
+ * like a reading.
+ */
+export function centrelineExtent(elements) {
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    // Two reasons to skip a subtree, tracked on one stack: an ancestor carries
+    // a transform, or an ancestor DOES NOT RENDER.
+    //
+    // The second is finding 3 of this change's completion review. Geometry
+    // inside `<defs>`, `<clipPath>`, `<mask>`, `<symbol>`, `<marker>` or
+    // `<pattern>` is a definition, not paint — and a clip path is usually a
+    // full-bleed rect, so an exported icon reported padding 0 on BOTH sides
+    // and the comparison finding 2.2 exists to make meaningful compared two
+    // zeroes. The old `d`-scraping reader had the same blind spot; reading
+    // primitives widened it, because clip and mask shapes are rects and
+    // circles.
+    for (const el of renderingElements(elements)) {
+        const box = elementExtent(el);
+        if (!box)
+            continue;
+        minX = Math.min(minX, box.minX);
+        maxX = Math.max(maxX, box.maxX);
+        minY = Math.min(minY, box.minY);
+        maxY = Math.max(maxY, box.maxY);
+    }
+    return Number.isFinite(minX) ? { minX, minY, maxX, maxY } : null;
+}
+/** Smallest distance from a viewBox edge to an extent. Negative when it overflows. */
+export function paddingFromExtent(vb, ext) {
+    return Math.min(ext.minX - vb.x, ext.minY - vb.y, vb.x + vb.w - ext.maxX, vb.y + vb.h - ext.maxY);
+}
+/**
+ * Stroke width and padding of each reference icon, read from its own bytes.
+ * Padding is the smallest distance from a viewBox edge to the drawn geometry.
+ * Nothing is declared here and no grid table is vendored (E6, Non-goals).
+ *
+ * Finding 2.1 of `road-to-svg-rules-in-the-dispatch-path`, both halves. This
+ * used to scrape `d` with a loose number-pair regex, so:
+ *
+ *   · a reference drawn with `<rect>` / `<circle>` / `<line>` yielded no
+ *     extent, was dropped, and — when every reference was drawn that way —
+ *     the reading then said "no icon reference set was supplied" although one
+ *     was. It now reads every primitive, and a file it still cannot read is
+ *     returned in `skipped` with the reason rather than vanishing.
+ *   · relative commands were read as absolute, so a path drawn with `m`/`l`
+ *     reported an extent anchored near the origin. `pathExtent` walks the
+ *     current point.
+ *
+ * The reading degrades to `unverified` rather than to a pass, so no verdict
+ * was wrong before this — but the reason given for the degradation was.
+ */
+export function readIconReferencesDetailed(files) {
+    const refs = [];
+    const skipped = [];
+    for (const file of files) {
+        if (!fs.existsSync(file)) {
+            skipped.push({ file, reason: 'file does not exist' });
+            continue;
+        }
+        const content = fs.readFileSync(file, 'utf8');
+        const elements = parseElements(content);
+        const root = elements.find((el) => el.name === 'svg' && !el.closing);
+        const vb = readViewBox(root);
+        if (!vb) {
+            skipped.push({ file, reason: 'no readable viewBox' });
+            continue;
+        }
+        // The SAME walk the candidate's stroke reading uses. Finding 5 of the
+        // third completion review: the candidate side was moved onto
+        // `renderingElements` and the reference side was not, so a reference
+        // icon's clip path contributed a stroke the viewer never sees.
+        // Reproduced: two byte-identical files reported 1.5 against [1.5, 8].
+        // The same defect as finding 9 of the previous round, in the other
+        // half of the same pair — which is what a defect-pattern sweep over
+        // the construct, rather than over the one reported site, is for.
+        const strokes = new Set();
+        for (const el of renderingElements(elements)) {
+            const sw = Number(el.attrs['stroke-width']);
+            if (Number.isFinite(sw) && sw > 0)
+                strokes.add(sw);
+        }
+        const ext = centrelineExtent(elements.filter((el) => el.name !== 'svg'));
+        if (!ext) {
+            skipped.push({ file, reason: 'no element in it carries readable geometry (every shape transformed, or none drawn)' });
+            continue;
+        }
+        refs.push({
+            file,
+            viewBox: vb,
+            strokeWidths: [...strokes].sort((a, b) => a - b),
+            padding: paddingFromExtent(vb, ext),
+        });
+    }
+    return { refs, skipped };
+}
+/** The list-only form, kept because every existing caller wants exactly that. */
+export function readIconReferences(files) {
+    return readIconReferencesDetailed(files).refs;
+}
+/**
+ * Graded against the incumbent set, both sides measured the same way (2.2).
+ *
+ * Exported so the grading can be exercised without launching a browser: the
+ * two findings it carries are a padding-method mismatch and a reference set
+ * dropped silently, and neither needs a render to reproduce.
+ */
+export function gradeIconGrid(file, vb, elements, iconSet, 
+/**
+ * The RENDERED painted box. Kept in the signature and deliberately unread:
+ * it is what the candidate's padding used to come from (finding 2.2), and
+ * dropping the parameter would make a caller that still passes it look
+ * correct while silently changing which argument lands where. Named with a
+ * leading underscore so the linter agrees it is not used.
+ */
+_paintedBox) {
+    const self = path.resolve(file);
+    const { refs, skipped } = readIconReferencesDetailed(iconSet.map((f) => path.resolve(f)).filter((f) => f !== self));
+    const comparable = vb ? refs.filter((r) => r.viewBox.w === vb.w && r.viewBox.h === vb.h) : [];
+    const strokes = new Set();
+    for (const el of renderingElements(elements)) {
+        const sw = Number(el.attrs['stroke-width']);
+        if (Number.isFinite(sw) && sw > 0)
+            strokes.add(sw);
+    }
+    const strokeWidth = strokes.size > 0 ? Math.max(...strokes) : null;
+    /**
+     * Finding 2.2: BOTH sides are centreline extents now.
+     *
+     * The candidate's padding used to come from `painted_box`, a RENDERED box
+     * that includes half the stroke and the caps, while the references came
+     * from raw coordinates. A candidate matching a reference exactly therefore
+     * measured one half-stroke less padding than it — latent rather than live
+     * only because the shipped icon pair happens to sit outside the band, so a
+     * new fixture at a different stroke width would have made it fire on a
+     * clean twin (Risk 7).
+     *
+     * Fixed by measuring, not by widening a threshold: `centrelineExtent` is
+     * the same function the references go through. `painted_box` keeps its own
+     * meaning everywhere else in the reading — it is simply not the thing to
+     * compare against a centreline.
+     */
+    const selfExt = centrelineExtent(elements.filter((el) => el.name !== 'svg'));
+    const padding = vb && selfExt ? paddingFromExtent(vb, selfExt) : null;
+    if (comparable.length === 0) {
+        const unreadable = skipped.length
+            ? ` ${String(skipped.length)} supplied file(s) could not be read: ${skipped
+                .map((s) => `${path.basename(s.file)} (${s.reason})`)
+                .join('; ')}.`
+            : '';
+        return {
+            status: 'unverified',
+            reference_files: refs.map((r) => path.basename(r.file)),
+            reference_stroke_widths: [],
+            reference_padding: [],
+            stroke_width: strokeWidth,
+            padding,
+            reason: refs.length === 0
+                ? (refs.length === 0 && skipped.length === 0 && iconSet.length > 0
+                    ? 'every file in the supplied icon reference set is the file under test, so there is ' +
+                        'nothing to compare against'
+                    : iconSet.length === 0
+                        ? 'no icon reference set was supplied, so the incumbent grid was never read (E6)'
+                        : 'an icon reference set was supplied but no file in it yielded a reading, so there ' +
+                            'is no grid to compare against') + unreadable
+                : vb === null
+                    ? // Finding 8 of the fifth completion review: a CANDIDATE
+                        // with no readable viewBox reached the same branch as a
+                        // reference set that shares no size, and was told that
+                        // no reference shares its viewBox — a statement about
+                        // the references, when the unreadable thing is the file
+                        // in front of the author. The reason has to name what
+                        // is actually missing or the author fixes the wrong
+                        // file.
+                        'this file has no readable viewBox, so its grid cannot be compared against any ' +
+                            'reference' + unreadable
+                    : 'no reference icon shares this viewBox size, so there is no grid to compare against' +
+                        unreadable,
+        };
+    }
+    const refStrokes = [...new Set(comparable.flatMap((r) => r.strokeWidths))].sort((a, b) => a - b);
+    const refPadding = [...new Set(comparable.map((r) => r.padding))].sort((a, b) => a - b);
+    return {
+        status: 'read',
+        reference_files: comparable.map((r) => path.basename(r.file)),
+        reference_stroke_widths: refStrokes,
+        reference_padding: refPadding,
+        stroke_width: strokeWidth,
+        padding,
+        reason: `read from ${comparable.length} incumbent SVG(s)`,
+    };
+}
+//# sourceMappingURL=uiRenderAssetGrid.js.map