@event4u/agent-config 16.4.0 → 17.0.0

package/dist/cli/commands/uiRender.js

@@ -23,14 +23,18 @@
  * `b-page-capture-primitive` closed as a recorded null. This supplies the
  * primitive, so that null's own reopening condition fires.
  *
- * Playwright is a devDependency (`package.json:97`) and is therefore NOT
+ * Playwright is a devDependency (`package.json:111`) and is therefore NOT
  * guaranteed present in a consumer install. The import is dynamic and the
  * absence path is a clean, explained exit rather than a stack trace — and it
  * reports `verification: unverified` instead of writing an empty manifest that
  * would read as a successful capture of nothing.
  */
+import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { runAssetRender } from './uiRenderAsset.js';
+import { scanHostHtml, scanSvg } from '../../scripts/lint_svg_asset.js';
+import { EXIT_RENDERER_ABSENT, RENDER_REL, renderSlug } from '../../scripts/_lib/asset_render_record.js';
 /** The three viewports E3.1 names. Widths are the contract, not a preference. */
 export const VIEWPORTS = [
     { name: 'desktop', width: 1440, height: 900 },
@@ -48,14 +52,78 @@ export const CAPTURED_PROPERTIES = [
     'overflow-x',
     'overflow-y',
 ];
-export const RENDER_REL = path.join('agents', 'runtime', 'state', 'render');
-export function slugify(target) {
-    return (target
-        .replace(/^https?:\/\//, '')
-        .replace(/[^a-z0-9]+/gi, '-')
-        .replace(/^-+|-+$/g, '')
-        .toLowerCase()
-        .slice(0, 60) || 'render');
+// Where the manifest lands, the exit that means "no renderer" and the slug rule
+// live with the turn-end gate's render recorder, which must agree with this
+// command on all three to find the manifest a render left.
+export { RENDER_REL, EXIT_RENDERER_ABSENT, renderSlug as slugify };
+/**
+ * The families whose ERROR means the file is broken, as opposed to improvable.
+ *
+ * Finding 4 of the third completion review, reproduced by running `scanSvg`:
+ * an ordinary stroke icon with no `<title>` yields exactly one error —
+ * `svg-a11y-no-accessible-name` — so `errors` was never 0, the static-only
+ * discharge never fired, and a consumer with no Playwright was refused by a
+ * BLOCKING turn-end gate on every `.svg` they wrote, with no way out. That is
+ * the opposite of the path's stated purpose, which the obligation module's own
+ * header spells out: it exists so a Playwright-less install is not refused
+ * forever.
+ *
+ * `structure` is "this file does not parse or does not resolve" and `safety`
+ * is "this file does something it should not". Both are brokenness, and both
+ * SHOULD stop a discharge taken without a render. Accessibility, motion and
+ * geometry are readings about a file that works — they are reported by the
+ * design pass in their own right, and a missing title is not a reason to
+ * refuse a turn on a machine that could not render.
+ */
+const BLOCKING_FAMILIES = ['svg-structure-', 'svg-safety-'];
+/**
+ * The static witness, bound to the bytes it read.
+ *
+ * `errors` counts `severity: 'error'` findings in the blocking families only —
+ * see `BLOCKING_FAMILIES` for which, and for the refusal that made the
+ * distinction necessary. A warning is a reading, not a refusal, and the
+ * static-only discharge in the turn-end gate is about whether the file is
+ * BROKEN. The digest is of the SAME bytes, so a later reader can tell whether
+ * this reading describes the file in front of it.
+ */
+export function staticWitness(absFile, delivery) {
+    // THE DIGEST IS OF THE BYTES, the scan is of the decoded text.
+    //
+    // Finding 2 of the sixth completion review: three places hash "the file"
+    // and two of them hashed the UTF-8 DECODED string while the render hashed
+    // the raw buffer. For any file the decode is not byte-exact over — a BOM,
+    // a lone surrogate, an invalid sequence replaced by U+FFFD — the two
+    // digests differ forever, so the gate never matches a render to the file
+    // it rendered and the obligation can never be discharged. One definition,
+    // and it is the one a digest normally means.
+    let bytes;
+    try {
+        bytes = fs.readFileSync(absFile);
+    }
+    catch {
+        return null;
+    }
+    const content = bytes.toString('utf8');
+    const digest = crypto.createHash('sha256').update(bytes).digest('hex');
+    // The DELIVERY MODE is threaded through. Finding 6 of this change's second
+    // completion review: `scanSvg` grades an undeclared mode as `inline`, the
+    // strictest, because that is the safe default for a file whose embedding
+    // nobody stated. Here the embedding WAS stated — `--delivery img` is on the
+    // same command line — so defaulting raised the safety family to `error` for
+    // an asset that cannot execute anything, and a correct `img`-delivered file
+    // was refused the static-only discharge it qualifies for.
+    // AN HTML HOST IS SCANNED AS A HOST, NOT AS A GRAPHIC.
+    //
+    // Finding 1 of the fourth completion review, reproduced on this repo's own
+    // `hosts/img-delivery-static.html` fixture: `scanSvg` over a host document
+    // reports `svg-structure-not-well-formed` for every HTML void element —
+    // `<meta>` and `<img>` never close, which is correct HTML and malformed
+    // XML — so the witness read 2 errors where `scanHostHtml` over the same
+    // bytes reports none. Under the blocking-family count those are structure
+    // errors, so a correct host document could not discharge its obligation.
+    const scan = /\.html?$/i.test(absFile) ? scanHostHtml : scanSvg;
+    const errors = scan(content, path.basename(absFile), { delivery }).filter((f) => f.severity === 'error' && BLOCKING_FAMILIES.some((fam) => f.rule.startsWith(fam))).length;
+    return { errors, digest };
 }
 /** Colour-ish computed values, normalised. Used to build the palette snapshot. */
 export function collectPalette(styleRecords) {
@@ -70,6 +138,23 @@ export function collectPalette(styleRecords) {
     }
     return [...out].sort();
 }
+/**
+ * The families that actually painted text, read from the `painted-family` each
+ * sampled node that carries its own text records in `<viewport>.styles.json`
+ * (step 1.3 of road-to-type-with-a-witness). Beside the declared list, never
+ * instead of it: the A1.5 threshold and the preserve check in `ui_authority.ts`
+ * keep reading `type_families`, and the manifest gains no key — its page-profile
+ * key set is pinned (E8), so the painted reading lives per node.
+ */
+export function collectPaintedFamilies(styleRecords) {
+    const out = new Set();
+    for (const rec of styleRecords) {
+        const fam = rec['painted-family'];
+        if (fam)
+            out.add(fam);
+    }
+    return [...out].sort();
+}
 /** First-choice families only — the A1.5 threshold is about the family that wins. */
 export function collectTypeFamilies(styleRecords) {
     const out = new Set();
@@ -88,13 +173,22 @@ export async function runUiRender(opts) {
         process.stderr.write(`[ui:render] path not found: ${abs}\n`);
         return 1;
     }
-    const slug = opts.slug ?? slugify(opts.target);
+    const slug = opts.slug ?? renderSlug(opts.target);
     const outDir = path.join(projectRoot, RENDER_REL, slug);
+    const isAsset = opts.profile === 'asset';
     let chromium;
     try {
         ({ chromium } = await import('@playwright/test'));
     }
     catch {
+        // Step 2.3, and the reason the absence path sits ABOVE the profile
+        // branch rather than inside either one: both profiles reach it by
+        // construction, so there is no second absence path to keep honest.
+        // Step 2.1(i): on the ASSET profile the renderer-absent path runs the
+        // static witness itself and binds it to the same digest, so the gate's
+        // static-only discharge reads ONE file and never depends on how a
+        // separate lint run was named or stored.
+        const staticReading = isAsset && !isUrl ? staticWitness(abs, opts.delivery) : null;
         const manifest = {
             schema: 1,
             generated_at: new Date().toISOString(),
@@ -104,6 +198,8 @@ export async function runUiRender(opts) {
             palette: [],
             type_families: [],
             verification: 'unverified',
+            ...(isAsset ? { profile: 'asset', reason: 'renderer-absent', goal: 'unassessed' } : {}),
+            ...(staticReading ? { static: staticReading } : {}),
             degradation_reason: '@playwright/test is not installed — it is a devDependency, so a consumer install has no browser. ' +
                 'Install it, or scope any verdict to the static checks that actually ran.',
         };
@@ -111,11 +207,27 @@ export async function runUiRender(opts) {
         process.stderr.write(`[ui:render] ${manifest.degradation_reason}\n`);
         if (opts.json)
             process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
-        // Exit 0, deliberately: an absent devDependency is a capability fact,
-        // not a failure of this command. The manifest carries the honest state.
-        return 0;
+        // The PAGE profile keeps exit 0: an absent devDependency is a
+        // capability fact, not a failure of that command, and the manifest
+        // carries the honest state.
+        //
+        // The ASSET profile exits NON-ZERO (step 2.1(a), review claim C2). The
+        // turn-end gate's transcript path never sees an exit code, so a
+        // non-zero exit alone does not close the hole — but the record path
+        // reads one, and a bare `ui:render --profile asset` that rendered
+        // nothing must not look like a check that passed. The code is distinct
+        // from 1, which this command already uses for an internal error such as
+        // a missing path or a URL handed to the asset profile.
+        return isAsset ? EXIT_RENDERER_ABSENT : 0;
     }
     fs.mkdirSync(outDir, { recursive: true });
+    if (isAsset) {
+        if (isUrl) {
+            process.stderr.write('[ui:render] --profile asset reads a file on disk, not a URL\n');
+            return 1;
+        }
+        return runAssetProfile({ ...opts, projectRoot, abs, slug, outDir }, chromium);
+    }
     const captures = [];
     const allStyles = [];
     let browser = null;
@@ -130,12 +242,61 @@ export async function runUiRender(opts) {
             const domPath = path.join(outDir, `${vp.name}.dom.html`);
             fs.writeFileSync(domPath, dom);
             const styles = await page.evaluate((props) => {
+                // The family that PAINTED, beside the one declared (step 1.3 of
+                // road-to-type-with-a-witness). Walked in stack order: a generic
+                // family always paints; a family registered through @font-face
+                // paints only when one of its faces loaded; any other family
+                // paints when it measures differently from an absent one.
+                const GENERIC = ['serif', 'sans-serif', 'monospace', 'cursive', 'fantasy', 'system-ui', 'math', 'emoji'];
+                const faces = Array.from(document.fonts);
+                const ctx = document.createElement('canvas').getContext('2d');
+                const unquote = (f) => f.trim().replace(/^["']|["']$/g, '').toLowerCase();
+                const painted = new Map();
+                const paintedOf = (stack) => {
+                    const cached = painted.get(stack);
+                    if (cached !== undefined)
+                        return cached;
+                    let out = '';
+                    for (const fam of stack.split(',').map(unquote)) {
+                        if (fam === '')
+                            continue;
+                        if (GENERIC.includes(fam) || fam.startsWith('ui-')) {
+                            out = fam;
+                            break;
+                        }
+                        const own = faces.filter((f) => unquote(f.family) === fam);
+                        if (own.length > 0) {
+                            if (own.some((f) => f.status === 'loaded')) {
+                                out = fam;
+                                break;
+                            }
+                            continue;
+                        }
+                        if (!ctx)
+                            continue;
+                        ctx.font = `32px "${fam}", monospace`;
+                        const a = ctx.measureText('Hamburgefonstiv').width;
+                        ctx.font = '32px "__agent_config_absent_family__", monospace';
+                        if (Math.abs(a - ctx.measureText('Hamburgefonstiv').width) > 0.01) {
+                            out = fam;
+                            break;
+                        }
+                    }
+                    painted.set(stack, out);
+                    return out;
+                };
                 const rows = [];
                 for (const el of Array.from(document.querySelectorAll('*')).slice(0, 1500)) {
                     const cs = window.getComputedStyle(el);
                     const rec = { selector: el.tagName.toLowerCase() };
                     for (const p of props)
                         rec[p] = cs.getPropertyValue(p);
+                    // `<style>` and `<script>` carry text and paint none of it.
+                    const NO_PAINT = ['style', 'script', 'title', 'head', 'noscript', 'template'];
+                    const ownText = !NO_PAINT.includes(rec['selector'] ?? '') &&
+                        Array.from(el.childNodes).some((n) => n.nodeType === Node.TEXT_NODE && (n.textContent ?? '').trim() !== '');
+                    if (ownText)
+                        rec['painted-family'] = paintedOf(cs.fontFamily);
                     rows.push(rec);
                 }
                 return rows;
@@ -199,6 +360,97 @@ export async function runUiRender(opts) {
     }
     return 0;
 }
+/**
+ * The asset profile. Same manifest, same output directory, same Class-A
+ * boundary — the browser is closed in a `finally` on every path including a
+ * throw, exactly as the page profile closes its own.
+ */
+async function runAssetProfile(opts, chromium) {
+    let browser = null;
+    try {
+        browser = await chromium.launch({ headless: true });
+        const result = await runAssetRender(browser, {
+            file: opts.abs,
+            projectRoot: opts.projectRoot,
+            outDir: opts.outDir,
+            assetClass: opts.assetClass,
+            delivery: opts.delivery,
+            thresholdsFile: opts.thresholds,
+            iconSet: opts.iconSet,
+            compareTo: opts.compareTo,
+            registration: opts.registration,
+        });
+        // Finding 8 of this change's completion review: ONE evaluation. The
+        // spread below used to call this twice — once as the truthiness guard,
+        // once for the value — so the verified path re-read the file, re-hashed
+        // it and re-ran the whole rule suite, and the two reads could disagree
+        // if the file moved between them.
+        const staticReading = staticWitness(opts.abs, opts.delivery);
+        const manifest = {
+            schema: 1,
+            generated_at: new Date().toISOString(),
+            target: opts.target,
+            slug: opts.slug,
+            captures: [],
+            palette: [],
+            type_families: [],
+            verification: result.verification,
+            profile: 'asset',
+            // Step 2.3. Written on EVERY asset render, by the only layer that
+            // could plausibly be mistaken for the one deciding it. A reader who
+            // sees `verification: verified` and no goal field has to supply the
+            // missing half themselves, which is exactly how `verified` came to
+            // be read as "the graphic is right".
+            goal: 'unassessed',
+            asset: result.reading,
+            // The static witness on the same digest, on the verified path too —
+            // the gate's digest-match discharge reads the ASSET reading, but a
+            // human comparing two manifests should not have to tell whether the
+            // static layer ran from which path produced the file.
+            ...(staticReading ? { static: staticReading } : {}),
+            ...(result.degradationReason ? { degradation_reason: result.degradationReason } : {}),
+            ...(result.verification === 'verified' ? {} : { reason: 'render-failed' }),
+        };
+        writeManifest(opts.outDir, manifest);
+        if (opts.json)
+            process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+        else {
+            const r = result.reading;
+            process.stdout.write(`✅  ui:render --profile asset — ${r.asset_class}` +
+                `${r.asset_class_inferred ? ' (inferred)' : ''}, ${r.sizes.length} capture(s), ` +
+                `${r.findings.length} finding(s), ${r.network.aborted} request(s) aborted\n` +
+                `    ${path.relative(opts.projectRoot, opts.outDir)}\n` +
+                r.findings.map((f) => `    ⚠️  ${f.rule} — ${f.detail}\n`).join(''));
+        }
+        return 0;
+    }
+    catch (err) {
+        const manifest = {
+            schema: 1,
+            generated_at: new Date().toISOString(),
+            target: opts.target,
+            slug: opts.slug,
+            captures: [],
+            palette: [],
+            type_families: [],
+            verification: 'degraded',
+            profile: 'asset',
+            // A renderer that RAN and failed, which is not the same fact as a
+            // renderer that is absent — the turn-end gate discharges an SVG
+            // obligation on the second and never on the first.
+            reason: 'render-failed',
+            goal: 'unassessed',
+            degradation_reason: `asset capture failed: ${String(err)}`,
+        };
+        writeManifest(opts.outDir, manifest);
+        process.stderr.write(`[ui:render] ${manifest.degradation_reason}\n`);
+        return 1;
+    }
+    finally {
+        // The Class-A boundary, same clause as the page profile's.
+        await browser?.close();
+    }
+}
 function writeManifest(outDir, manifest) {
     fs.mkdirSync(outDir, { recursive: true });
     fs.writeFileSync(path.join(outDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);