@event4u/agent-config 16.4.0 → 17.0.0

package/dist/cli/commands/uiRenderAssetGrounds.js

@@ -0,0 +1,323 @@
+import { HOST_BASENAME, MIN_CONTRAST_RATIO, } from './uiRenderAssetTypes.js';
+/**
+ * The per-ground readings — steps 4.1 and 4.2 of
+ * `road-to-svg-from-a-live-session`.
+ *
+ * Three images, read in one scratch page so nothing is decoded twice:
+ *
+ *   transparent  the file on no ground at all, which is where its own
+ *                silhouette comes from. A silhouette taken from the light
+ *                capture would lose every white part of the graphic, which is
+ *                precisely the paint these two readings are about.
+ *   light / dark the two captures the profile already wrote.
+ *
+ * Inside that silhouette, two counts per ground. A pixel whose contrast ratio
+ * against the ground is below 3:1 is hard to see there (4.2) — a wordmark in
+ * dark violet shipped unreadable on a dark ground and the variant was never
+ * built. A pixel whose colour sits within the anti-alias band of the ground is
+ * the ground showing THROUGH the graphic (4.1) — the hairline seams between
+ * abutting traced segments, invisible on white and obvious on black.
+ *
+ * Holes are excluded by declaration, never by geometry: a ring's middle is
+ * ground on purpose, and only the author can say which gaps are intended.
+ */
+/**
+ * What FRACTION of the capture the graphic covers, width and height.
+ *
+ * Finding 4 of this change's second completion review. The capture is the
+ * VIEWPORT, floored at 64 px, while the page is `margin:0` with
+ * `body>svg{width:cssWidth}` — so the graphic sits in the top-left corner and
+ * covers only part of the image whenever `cssWidth` is smaller. Every icon is
+ * such a case: the sizes are 16/24/48 against a floor of 64. Mapping a
+ * user-unit box across the whole capture therefore put every declared hole and
+ * every declared-translucent shape 4/3 too far out, and the exclusions the
+ * author declared were applied to the wrong part of their own file.
+ *
+ * A FRACTION rather than a pixel count, because the image's size is known only
+ * inside the page while everything this needs is known outside it — which is
+ * also what makes the arithmetic testable without a renderer. Clamped to 1:
+ * `cssWidth` above the viewport is the graphic filling the capture, not
+ * overflowing the coordinate space.
+ */
+export function graphicFraction(spec) {
+    if (spec.width <= 0 || spec.height <= 0 || spec.cssWidth <= 0)
+        return { w: 1, h: 1 };
+    const w = Math.min(1, spec.cssWidth / spec.width);
+    const vb = spec.viewBox;
+    if (!vb || vb.w <= 0)
+        return { w, h: 1 };
+    // The rendered height follows the viewBox aspect from the rendered width.
+    const cssHeight = spec.cssWidth * (vb.h / vb.w);
+    return { w, h: Math.min(1, cssHeight / spec.height) };
+}
+export async function readGrounds(context, openPage, spec) {
+    // The transparent render: `omitBackground` leaves alpha 0 where the file
+    // paints nothing, which is the only honest source for a silhouette.
+    const clear = await openPage(context, {
+        url: spec.url,
+        hostHtml: spec.hostHtml,
+        hostBasename: HOST_BASENAME,
+        width: spec.width,
+        height: spec.height,
+        background: 'transparent',
+        cssWidth: spec.cssWidth,
+        blocked: spec.blocked,
+    });
+    let silhouette;
+    try {
+        silhouette = await clear.screenshot({ omitBackground: true });
+    }
+    finally {
+        await clear.close();
+    }
+    const out = [];
+    for (const mode of ['light', 'dark']) {
+        const colour = spec.backgrounds[mode];
+        const page = await openPage(context, {
+            url: spec.url,
+            hostHtml: spec.hostHtml,
+            hostBasename: HOST_BASENAME,
+            width: spec.width,
+            height: spec.height,
+            background: colour,
+            cssWidth: spec.cssWidth,
+            blocked: spec.blocked,
+        });
+        let shot;
+        try {
+            shot = await page.screenshot();
+        }
+        finally {
+            await page.close();
+        }
+        const scratch = await context.newPage();
+        try {
+            await scratch.setContent('<!doctype html><body></body>');
+            const counts = await scratch.evaluate(async (args) => {
+                const load = async (b64) => {
+                    const img = new Image();
+                    img.src = `data:image/png;base64,${b64}`;
+                    try {
+                        await img.decode();
+                    }
+                    catch {
+                        return null;
+                    }
+                    return img;
+                };
+                const a = await load(args.silhouette);
+                const b = await load(args.ground);
+                if (!a || !b)
+                    return null;
+                const w = Math.min(a.naturalWidth, b.naturalWidth);
+                const h = Math.min(a.naturalHeight, b.naturalHeight);
+                if (w === 0 || h === 0)
+                    return null;
+                const read = (img) => {
+                    const c = document.createElement('canvas');
+                    c.width = w;
+                    c.height = h;
+                    const cx = c.getContext('2d', { willReadFrequently: true });
+                    if (!cx)
+                        return null;
+                    cx.clearRect(0, 0, w, h);
+                    cx.drawImage(img, 0, 0);
+                    return cx.getImageData(0, 0, w, h).data;
+                };
+                const alpha = read(a);
+                const px = read(b);
+                if (!alpha || !px)
+                    return null;
+                const hex = args.colour.trim();
+                const parse = (v) => {
+                    const m3 = /^#([0-9a-f])([0-9a-f])([0-9a-f])$/i.exec(v);
+                    if (m3) {
+                        return [
+                            parseInt(m3[1].repeat(2), 16),
+                            parseInt(m3[2].repeat(2), 16),
+                            parseInt(m3[3].repeat(2), 16),
+                        ];
+                    }
+                    // 4 and 8 digits carry an ALPHA the ground does not
+                    // need; 6 is the plain case. Finding 5 of the fifth
+                    // completion review: this handled 3 and 6 while the
+                    // token reader that produces the value accepts 3 to 8,
+                    // so a `#rrggbbaa` background fell through to the
+                    // white fallback and every contrast ratio on that
+                    // ground was computed against a colour nobody chose —
+                    // silently, because white is a plausible answer.
+                    const m68 = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})(?:[0-9a-f]{2})?$/i.exec(v);
+                    if (m68) {
+                        return [
+                            parseInt(m68[1], 16),
+                            parseInt(m68[2], 16),
+                            parseInt(m68[3], 16),
+                        ];
+                    }
+                    const m4 = /^#([0-9a-f])([0-9a-f])([0-9a-f])[0-9a-f]$/i.exec(v);
+                    if (m4) {
+                        return [
+                            parseInt(m4[1].repeat(2), 16),
+                            parseInt(m4[2].repeat(2), 16),
+                            parseInt(m4[3].repeat(2), 16),
+                        ];
+                    }
+                    const rgb = /rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)/.exec(v);
+                    if (rgb) {
+                        return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
+                    }
+                    return [255, 255, 255];
+                };
+                const ground = parse(hex);
+                const lum = (c) => {
+                    const f = (v) => {
+                        const x = v / 255;
+                        return x <= 0.03928 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4;
+                    };
+                    return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]);
+                };
+                const groundLum = lum(ground);
+                const ratio = (c) => {
+                    const l = lum(c);
+                    const hi = Math.max(l, groundLum);
+                    const lo = Math.min(l, groundLum);
+                    return (hi + 0.05) / (lo + 0.05);
+                };
+                // Declared holes and translucent shapes, mapped from user
+                // units into this image.
+                //
+                // The graphic's own extent in IMAGE pixels, which is what a
+                // user-unit coordinate maps into — not the capture's. The
+                // page is `margin:0` with `body>svg{width:cssWidth}`, so it
+                // sits at the top-left corner and the height follows the
+                // viewBox aspect. A file with no viewBox is not mapped at
+                // all (the guard below), so there is no aspect to miss.
+                const gW = w * args.graphic.w;
+                const gH = h * args.graphic.h;
+                const within = (boxes, x, y) => {
+                    if (!args.vb || boxes.length === 0)
+                        return false;
+                    if (gW <= 0 || gH <= 0 || x >= gW || y >= gH)
+                        return false;
+                    const ux = args.vb.x + (x / gW) * args.vb.w;
+                    const uy = args.vb.y + (y / gH) * args.vb.h;
+                    return boxes.some((box) => ux >= box.x && ux <= box.x + box.w && uy >= box.y && uy <= box.y + box.h);
+                };
+                const inHole = (x, y) => within(args.holes, x, y);
+                const inSoft = (x, y) => within(args.soft, x, y);
+                // The OUTER silhouette: flood the transparent region
+                // inwards from the border. What the flood cannot reach is
+                // inside the graphic — including the hairline gaps between
+                // abutting shapes, which is the thing step 4.1 counts and
+                // which an `alpha >= 200` definition excludes by
+                // construction (measured: 0 bleed pixels on the planted
+                // fixture before this).
+                const opaque = (i) => alpha[i * 4 + 3] >= 200;
+                const outside = new Uint8Array(w * h);
+                const stack = [];
+                const push = (i) => {
+                    if (outside[i] === 1 || opaque(i))
+                        return;
+                    outside[i] = 1;
+                    stack.push(i);
+                };
+                for (let x = 0; x < w; x += 1) {
+                    push(x);
+                    push((h - 1) * w + x);
+                }
+                for (let y = 0; y < h; y += 1) {
+                    push(y * w);
+                    push(y * w + (w - 1));
+                }
+                while (stack.length > 0) {
+                    const i = stack.pop();
+                    const x = i % w;
+                    const y = (i - x) / w;
+                    if (x > 0)
+                        push(i - 1);
+                    if (x + 1 < w)
+                        push(i + 1);
+                    if (y > 0)
+                        push(i - w);
+                    if (y + 1 < h)
+                        push(i + w);
+                }
+                let sil = 0;
+                let painted = 0;
+                let low = 0;
+                let bleed = 0;
+                for (let i = 0; i < w * h; i += 1) {
+                    if (outside[i] === 1)
+                        continue;
+                    sil += 1;
+                    const c = [
+                        px[i * 4],
+                        px[i * 4 + 1],
+                        px[i * 4 + 2],
+                    ];
+                    // Contrast is asked of PAINTED pixels only: the ratio
+                    // of a gap against the ground showing through it is the
+                    // ratio of the ground against itself.
+                    if (opaque(i)) {
+                        painted += 1;
+                        if (ratio(c) < args.minContrast)
+                            low += 1;
+                    }
+                    // Bleed is an INTERIOR pixel the graphic does not fully
+                    // cover, so the ground shows through it.
+                    //
+                    // Measured, and this is the second definition: comparing
+                    // the pixel's colour against the ground within a
+                    // tolerance read 0 on the planted fixture, because a
+                    // half-covered seam composites to a BLEND of the two
+                    // greys and the ground — nowhere near the ground itself.
+                    // Alpha is the thing that is actually wrong, and it is
+                    // the same number whatever colour the ground is, which
+                    // is why the finding fires on the dark row: that is the
+                    // capture where the consequence is visible.
+                    // Finding 7: a legitimately TRANSLUCENT interior is
+                    // not a seam. A `fill-opacity="0.5"` shape is excluded
+                    // from `painted` and would otherwise be counted as
+                    // near-total bleed against a 0.002 threshold — a
+                    // warning on a correct file, which is the Risk 1
+                    // failure this whole concern is shaped around. The
+                    // caller passes those shapes' extents the same way it
+                    // passes declared holes, because "is this coverage
+                    // intended" is again a question only the author
+                    // answers.
+                    const x = i % w;
+                    const y = Math.floor(i / w);
+                    if (!opaque(i) && !inHole(x, y) && !inSoft(x, y))
+                        bleed += 1;
+                }
+                return { silhouette: sil, painted, low, bleed };
+            }, {
+                silhouette: silhouette.toString('base64'),
+                ground: shot.toString('base64'),
+                colour,
+                holes: spec.holeBoxes,
+                soft: spec.softBoxes,
+                vb: spec.viewBox,
+                minContrast: MIN_CONTRAST_RATIO,
+                graphic: graphicFraction(spec),
+            });
+            if (counts === null)
+                continue;
+            out.push({
+                background: mode,
+                background_color: colour,
+                silhouette_px: counts.silhouette,
+                painted_px: counts.painted,
+                low_contrast_px: counts.low,
+                low_contrast_share: counts.painted === 0 ? 0 : counts.low / counts.painted,
+                bleed_px: counts.bleed,
+                bleed_share: counts.silhouette === 0 ? 0 : counts.bleed / counts.silhouette,
+            });
+        }
+        finally {
+            await scratch.close();
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=uiRenderAssetGrounds.js.map

package/dist/cli/commands/uiRenderAssetIsolation.js

@@ -0,0 +1,85 @@
+/**
+ * Isolation of the asset under test — which is untrusted input — during its
+ * own witness (16.5.0 release review).
+ *
+ * Scripts are disabled for the whole browser context, so a `<script>` or `on*`
+ * handler in the asset never runs; that is also what keeps WebSocket and
+ * WebRTC closed, since `page.route` intercepts neither. A request is allowed
+ * only on the `file:`, `data:`, `blob:` and `about:` schemes, and a `file:`
+ * request only when it resolves inside the project root or the asset's own
+ * directory, so an asset cannot pull an arbitrary local file into a capture.
+ * The comparison pages inline everything they read, so they allow no `file:`.
+ *
+ * The cost, accepted: a host document that builds its visual state with
+ * JavaScript is witnessed as its static markup, not as it would run.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ALLOWED_SCHEMES } from './uiRenderAssetTypes.js';
+/** The directories a `file:` request may resolve into for this asset. */
+export function fileRootsFor(projectRoot, file) {
+    return [projectRoot, path.dirname(path.resolve(file))];
+}
+/** True unless `url` is a `file:` URL resolving outside `root` (symlinks followed). */
+export function fileInside(url, root) {
+    if (!url.startsWith('file:'))
+        return true;
+    const real = (p) => {
+        try {
+            return fs.realpathSync(p);
+        }
+        catch {
+            return path.resolve(p);
+        }
+    };
+    let target;
+    try {
+        target = real(fileURLToPath(url));
+    }
+    catch {
+        return false;
+    }
+    const base = real(root);
+    return target === base || target.startsWith(base + path.sep);
+}
+/**
+ * May the witness page load `url`? A `file:` URL needs a root it resolves
+ * inside; with no roots — a page that inlines everything it reads — none does.
+ */
+export function requestAllowed(url, fileRoots) {
+    if (!ALLOWED_SCHEMES.some((s) => url.startsWith(s)))
+        return false;
+    return !url.startsWith('file:') || fileRoots.some((root) => fileInside(url, root));
+}
+/**
+ * Route every request of `page` through `requestAllowed`, recording what was
+ * refused. One opener for every witness page, so no page confines less than
+ * another (16.5.0 review: the comparison pages checked the scheme only).
+ */
+export async function confinePage(page, blocked, fileRoots, fulfil) {
+    await page.route('**/*', async (route) => {
+        if (fulfil && (await fulfil(route)))
+            return;
+        const url = route.request().url();
+        if (!requestAllowed(url, fileRoots)) {
+            blocked.push(url);
+            await route.abort();
+            return;
+        }
+        await route.continue();
+    });
+}
+/**
+ * Add a stylesheet to the page. Not `page.addStyleTag`: it waits on a
+ * page-script `onload`, which never fires with scripts disabled, while
+ * `evaluate` runs outside the page's own scripts.
+ */
+export async function injectStyle(page, css) {
+    await page.evaluate((text) => {
+        const style = document.createElement('style');
+        style.textContent = text;
+        (document.head ?? document.documentElement).appendChild(style);
+    }, css);
+}
+//# sourceMappingURL=uiRenderAssetIsolation.js.map

package/dist/cli/commands/uiRenderAssetTypes.js

@@ -0,0 +1,133 @@
+// ---------------------------------------------------------------------------
+// Declared constants — every one of them pre-registered in step 0.3
+// ---------------------------------------------------------------------------
+export const ASSET_CLASSES = ['icon', 'mark', 'illustration', 'diagram', 'animated'];
+/**
+ * Per class, never global. A file is loose BELOW its class threshold.
+ * Overridden by a `fill_ratio_thresholds` block in `--thresholds <file>`.
+ */
+export const DEFAULT_FILL_RATIO_THRESHOLDS = {
+    icon: 0.3,
+    mark: 0.45,
+    illustration: 0.4,
+    diagram: 0.35,
+    animated: 0.35,
+};
+/** Step 2.6's tolerances. Overridden by `geometry_tolerances` in `--thresholds`. */
+export const DEFAULT_GEOMETRY_TOLERANCES = {
+    icon: { silhouette_iou_min: 0.98, max_boundary_distance_units: 1 },
+    mark: { silhouette_iou_min: 0.98, max_boundary_distance_units: 2 },
+    illustration: { silhouette_iou_min: 0.96, max_boundary_distance_units: 3 },
+    diagram: { silhouette_iou_min: 0.97, max_boundary_distance_units: 2 },
+    animated: { silhouette_iou_min: 0.97, max_boundary_distance_units: 2 },
+};
+/**
+ * Used ONLY when no `tokens.json` resolves. The manifest records
+ * `source: "fallback"` whenever these are used, because a reader cannot
+ * otherwise tell a project's own background from this module's guess.
+ */
+export const FALLBACK_BACKGROUNDS = { light: '#ffffff', dark: '#111111' };
+/**
+ * The four paths the brand resolver searches, in its order. First hit wins.
+ *
+ * Re-exported from the one declaration. The copy that stood here built its last
+ * entry with `path.join`, so on Windows this module searched a back-slash path
+ * the scaffold never wrote — two answers to what counts as the project's brand.
+ */
+export { BRAND_TOKEN_PATHS } from '../../shared/brandTokenPaths.js';
+/** Icon sizes are the three the incumbent sets ship at. Other classes: 1x and 2x. */
+export const ICON_SIZES = [16, 24, 48];
+/**
+ * A `mark` is captured here too — step 4.3 of
+ * `road-to-svg-from-a-live-session`.
+ *
+ * A review sent an accepted mark back because its face turned to mush at
+ * 32 px, and a simplified small-size variant was built. Nothing in the profile
+ * produced a capture at those sizes, so the only way to know was to look at
+ * something that did not exist. 16 and 32 are the two the review named.
+ */
+export const MARK_SMALL_SIZES = [16, 32];
+/**
+ * Below this, a draw-on animation is not reported. The planted row reads
+ * 0.283 (a 300-unit dash on a 215-unit path) and its twin reads 0.0, so the
+ * band between them is wide; 0.05 is inside it with room on both sides.
+ */
+export const DRAW_ON_DEAD_TIME_THRESHOLD = 0.05;
+/** A channel at or above this, with alpha 1, counts as near-white paint. */
+export const NEAR_WHITE_CHANNEL = 237;
+/**
+ * The synthetic host document. Fulfilled by the route handler at a URL inside
+ * the asset's OWN directory, so a relative `href` inside the asset resolves
+ * exactly as it would in place — without this module ever writing into the
+ * directory it is reading.
+ */
+export const HOST_BASENAME = '__agent-config-asset-host__.html';
+/** Schemes a page may reach. Everything else is aborted and counted. */
+export const ALLOWED_SCHEMES = ['file:', 'data:', 'blob:', 'about:'];
+/**
+ * How a shape declares that a gap in the silhouette is DELIBERATE.
+ *
+ * Step 4.1. A ring has a hole in the middle and the ground shows through it on
+ * purpose; without a way to say so, every ring reads as a seam. By attribute
+ * rather than by geometry, because "is this gap intended" is a question only
+ * the author can answer.
+ */
+export const HOLE_ATTRIBUTE = 'data-hole';
+/**
+ * The bleed share above which `geometry/background-bleed-inside-silhouette`
+ * fires, pre-registered in `fixtures/svg-assets/README.md` before the reading
+ * was written.
+ *
+ * A seam is a hairline: one or two pixels wide along a shared edge. The
+ * overlap twin — the same two shapes overlapping by one unit — reads 0. The
+ * threshold sits between them with room on both sides.
+ *
+ * IT DOES MOVE WITH THE RENDER SIZE, and this doc used to claim it does not.
+ * Finding 7 of the third completion review. A share is scale-free only when
+ * both terms scale together: a seam whose width is a fraction of a USER UNIT
+ * grows with the capture and its share is stable, but one that is an
+ * anti-aliasing artefact stays one or two DEVICE pixels wide at every size, so
+ * its count grows with the perimeter while the denominator grows with the
+ * area — the share falls roughly as 1/width. The planted fixture is the second
+ * kind (a ring of inner radius 20 against a disc of radius 20), so this number
+ * is pre-registered against the capture sizes THIS PROFILE TAKES, which top
+ * out at 2x the intrinsic width. A caller rendering the same file at several
+ * thousand pixels would read a share below the threshold on a file that still
+ * has the seam.
+ *
+ * Not re-derived here: fixing it means making the reading a function of the
+ * seam's width in user units rather than of its pixel count, which is a
+ * different measurement and a larger change than a remediation should take.
+ * Stated so a reader is not told the opposite.
+ */
+export const BLEED_SHARE_THRESHOLD = 0.002;
+/**
+ * Above this share of the registered source's painted pixels lying OUTSIDE the
+ * subject, `geometry/foreign-content-in-frame` fires.
+ *
+ * Finding 14 of this change's completion review: it was an inline `0.02` beside
+ * two named, documented, pre-registered thresholds. 2 % is the band an
+ * anti-aliased outline can occupy on a small mark without anything foreign
+ * being in the frame — it is a NOISE FLOOR, not a measured quality line, and
+ * saying so is the difference between a number a reader can argue with and one
+ * they cannot find.
+ */
+export const FOREIGN_CONTENT_SHARE_THRESHOLD = 0.02;
+/** Below this contrast ratio against its ground, a painted pixel is hard to see. */
+export const MIN_CONTRAST_RATIO = 3;
+/**
+ * The share of painted pixels below {@link MIN_CONTRAST_RATIO} above which
+ * `accessibility/low-contrast-on-background` fires.
+ *
+ * Half the mark, not a few anti-aliased edge pixels: an edge blends into its
+ * ground by construction, and a rule that fired on that would fire on every
+ * file. Pre-registered with the bleed threshold above.
+ */
+export const LOW_CONTRAST_SHARE_THRESHOLD = 0.5;
+/**
+ * The square sample grid both the profile and the comparison rasterise into.
+ * One constant because a comparison taken at a different resolution than the
+ * reading it is compared against is not a comparison.
+ */
+export const SAMPLE_RES = 256;
+//# sourceMappingURL=uiRenderAssetTypes.js.map

package/dist/cli/initRouting.js

@@ -4,7 +4,7 @@
  *
  * `init` is the consumer install entry point. When the browser wizard can
  * actually be used, `init` opens it and lets it drive the whole install via
- * `/api/v1/wizard/apply` → `scripts/install.py --apply-payload` — no CLI
+ * `/api/v1/wizard/apply` → `src/scripts/install.ts --apply-payload` — no CLI
  * tool-picker, one installer. Otherwise `init` falls back to the bash CLI
  * install. These pure helpers make that decision (and the GUI option mapping)
  * unit-testable, separate from the self-executing CLI entry point.

package/dist/cli/main.js

@@ -23,6 +23,7 @@ import { runDoctorShell } from './commands/doctorShell.js';
 import { runRtkDetect } from './commands/rtkDetect.js';
 import { runUiAudit } from './commands/uiAudit.js';
 import { runUiRender } from './commands/uiRender.js';
+import { parseRegistration } from './commands/uiRenderAssetCompare.js';
 import { runUiServe } from './commands/uiServe.js';
 import { shouldInitLaunchGui, buildInitGuiOptions, buildProjectInitDelegation, findInitGuiConflict, withoutGuiFlag } from './initRouting.js';
 import { maybePrintFirstRunNotice } from './firstRunNotice.js';
@@ -125,8 +126,53 @@ async function main(rawArgv) {
         .option('--json', 'Print the manifest on stdout as well as writing it')
         .option('--project-root <path>', 'Override the project root')
         .option('--slug <name>', 'Override the output directory name')
+        .option('--profile <name>', 'page (default) or asset — a single SVG, per class, light and dark')
+        .option('--class <name>', 'Asset class: icon | mark | illustration | diagram | animated')
+        .option('--delivery <mode>', 'Delivery mode: inline | document | img | css-bg')
+        .option('--thresholds <file>', 'JSON carrying fill_ratio_thresholds / geometry_tolerances')
+        .option('--icon-set <paths>', 'Comma-separated incumbent icon SVGs, read for their own grid')
+        .option('--compare <file>', 'Second render of the same frame to compare against')
+        .option('--registration <spec>', 'Raster source region as x,y,w,h[@scale]')
         .action(async (target, opts) => {
-        process.exitCode = await runUiRender({ target, ...opts });
+        // Validated, not cast. A cast let `--class Icon` through as an
+        // AssetClass that matches no threshold key, so
+        // `fill_ratio_threshold` came out `undefined`,
+        // `structure/loose-viewbox` could never fire, and the key
+        // vanished from the manifest — a silent downgrade of a reading
+        // to nothing. `lint_svg_asset` validates the same two
+        // vocabularies and exits 1; so does this.
+        const ASSET_CLASS_NAMES = ['icon', 'mark', 'illustration', 'diagram', 'animated'];
+        const DELIVERY_NAMES = ['inline', 'document', 'img', 'css-bg'];
+        if (opts.class !== undefined && !ASSET_CLASS_NAMES.includes(opts.class)) {
+            process.stderr.write(`[ui:render] unknown --class "${opts.class}"; expected one of ${ASSET_CLASS_NAMES.join(', ')}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.delivery !== undefined && !DELIVERY_NAMES.includes(opts.delivery)) {
+            process.stderr.write(`[ui:render] unknown --delivery "${opts.delivery}"; expected one of ${DELIVERY_NAMES.join(', ')}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.profile !== undefined && opts.profile !== 'page' && opts.profile !== 'asset') {
+            process.stderr.write(`[ui:render] unknown --profile "${opts.profile}"; expected page or asset\n`);
+            process.exitCode = 1;
+            return;
+        }
+        process.exitCode = await runUiRender({
+            target,
+            ...(opts.json === undefined ? {} : { json: opts.json }),
+            ...(opts.projectRoot === undefined ? {} : { projectRoot: opts.projectRoot }),
+            ...(opts.slug === undefined ? {} : { slug: opts.slug }),
+            ...(opts.profile === 'asset' ? { profile: 'asset' } : {}),
+            ...(opts.class === undefined ? {} : { assetClass: opts.class }),
+            ...(opts.delivery === undefined ? {} : { delivery: opts.delivery }),
+            ...(opts.thresholds === undefined ? {} : { thresholds: opts.thresholds }),
+            ...(opts.iconSet === undefined ? {} : { iconSet: opts.iconSet.split(',').map((s) => s.trim()) }),
+            ...(opts.compare === undefined ? {} : { compareTo: opts.compare }),
+            ...(parseRegistration(opts.registration) === null
+                ? {}
+                : { registration: parseRegistration(opts.registration) }),
+        });
     });
     program
         .command('ui:serve')