@skrr-ai/cli 0.1.102 → 0.1.104

package/dist/lib/widgetCheck.js

@@ -0,0 +1,998 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WIDGET_CHECK_MAX_INPUT_CHARS = exports.WIDGET_CHECK_HEURISTIC_NOTE = exports.WIDGET_CHECK_REPORT_VERSION = void 0;
+exports.inputErrorReport = inputErrorReport;
+exports.checkWidgetInput = checkWidgetInput;
+exports.renderWidgetFences = renderWidgetFences;
+exports.formatWidgetCheckReport = formatWidgetCheckReport;
+/**
+ * Generative UI — the offline widget self-check behind `skrr widgets check`.
+ *
+ * WHY IT EXISTS. A widget is rejected AFTER the message is sent: the ingest
+ * refuses a block with a bad header, a section named twice or an oversize
+ * stylesheet, the person sees an error state, and only then does the harness
+ * learn it. Everything that can be known before sending is known here, so a
+ * harness can run this in Bash, read the answer, and fix the block while fixing
+ * it is still free.
+ *
+ * ONE GRAMMAR, ONE CONTRACT. Nothing here re-implements either. A fence block is
+ * judged by the shared incremental parser (`createUiWidgetFenceParser`, the same
+ * state machine the server ingest and the client's streaming display import), a
+ * JSON widget by the contract's own Zod schemas, and every limit is read from
+ * `UI_WIDGET_LIMITS`. A rule changed in data-provider changes this check with no
+ * edit here, which is the only way an offline check stays honest. (A boundary
+ * spec in data-provider fails CI if this tree spells the fence name or a section
+ * marker as a literal, so even the examples are generated.)
+ *
+ * WHAT IS CERTAIN AND WHAT IS NOT. Grammar, schema and size findings are exact:
+ * they are the ingest's own verdict. A JavaScript syntax error is exact too, as a
+ * classic script (that is how the frame runs the js section). The static findings
+ * (`widgetStaticScan.ts`) are a HEURISTIC read of the source, and are tagged so.
+ *
+ * Pure: strings in, a plain JSON-able report out. No network, no files, no
+ * credentials, and the JavaScript is compiled (`vm.Script`), never run.
+ */
+const vm = __importStar(require("node:vm"));
+const data_provider_1 = require("@skrr-ai/data-provider");
+const widgetStaticScan_1 = require("./widgetStaticScan");
+// ── report types (the `--json` shape; stable) ───────────────────────────────
+exports.WIDGET_CHECK_REPORT_VERSION = 1;
+exports.WIDGET_CHECK_HEURISTIC_NOTE = 'Grammar, schema, size and JavaScript syntax findings are exact. Static findings are a heuristic ' +
+    'scan of the source, not a run in the sandbox: one can be a false positive, and none proves the widget works. ' +
+    'The frame decides.';
+/** More than this is refused unread: six widgets at their caps are about 1.2 MB. */
+exports.WIDGET_CHECK_MAX_INPUT_CHARS = 8 * 1024 * 1024;
+const LIMIT_MAX = {
+    css: data_provider_1.UI_WIDGET_LIMITS.cssMax,
+    html: data_provider_1.UI_WIDGET_LIMITS.htmlMax,
+    js: data_provider_1.UI_WIDGET_LIMITS.jsMax,
+    total: data_provider_1.UI_WIDGET_LIMITS.totalMax,
+    title: data_provider_1.UI_WIDGET_LIMITS.titleMax,
+    fallback: data_provider_1.UI_WIDGET_LIMITS.fallbackTextMax,
+};
+/** A stylesheet, markup or script this close to its limit has no room left to edit. */
+const NEAR_LIMIT_PERCENT = 75;
+// ── small helpers ───────────────────────────────────────────────────────────
+const numberFormat = new Intl.NumberFormat('en-US');
+const fmt = (n) => numberFormat.format(n);
+function usageOf(used, max, parserOverflow = false) {
+    return {
+        used,
+        max,
+        percent: Math.round((used / max) * 1000) / 10,
+        over: parserOverflow || used > max,
+        ...(parserOverflow ? { atLeast: true } : {}),
+    };
+}
+function sizeBlock(parts, overflow) {
+    const css = parts.css.length;
+    const html = parts.html.length;
+    const js = parts.js.length;
+    const byteLength = (s) => Buffer.byteLength(s, 'utf8');
+    const bytes = {
+        css: byteLength(parts.css),
+        html: byteLength(parts.html),
+        js: byteLength(parts.js),
+        total: 0,
+    };
+    bytes.total = bytes.css + bytes.html + bytes.js;
+    return {
+        bytes,
+        limits: {
+            css: usageOf(css, LIMIT_MAX.css, overflow === 'css'),
+            html: usageOf(html, LIMIT_MAX.html, overflow === 'html'),
+            js: usageOf(js, LIMIT_MAX.js, overflow === 'js'),
+            total: usageOf(css + html + js, LIMIT_MAX.total, overflow === 'total'),
+            title: usageOf(parts.title.trim().length, LIMIT_MAX.title, false),
+            fallback: usageOf(parts.fallback.trim().length, LIMIT_MAX.fallback, overflow === 'fallback'),
+        },
+    };
+}
+function limitsExceeded(limits) {
+    return Object.keys(limits).filter((key) => limits[key].over);
+}
+const LIMIT_SUBJECT = {
+    css: 'the css section',
+    html: 'the html section',
+    js: 'the js section',
+    total: 'css + html + js together',
+    title: 'the title',
+    fallback: 'the fallback text',
+};
+function limitIssue(key, usage) {
+    const what = LIMIT_SUBJECT[key];
+    const size = usage.atLeast
+        ? `is longer than ${fmt(usage.max)} characters`
+        : `is ${fmt(usage.used)} characters; the limit is ${fmt(usage.max)}`;
+    return {
+        severity: 'error',
+        source: 'limit',
+        code: `limit/${key}`,
+        section: key,
+        message: `${what[0].toUpperCase()}${what.slice(1)} ${size}. Over a limit the widget is refused, never trimmed.`,
+        fix: key === 'total' || key === 'css' || key === 'html' || key === 'js'
+            ? `Shorten it or split the idea into several widgets (a message carries at most ${data_provider_1.UI_WIDGET_LIMITS.perMessageMax}). Aim for under a quarter of each limit.`
+            : `Shorten it to at most ${fmt(usage.max)} characters.`,
+    };
+}
+function nearLimitIssues(limits) {
+    const out = [];
+    for (const key of Object.keys(limits)) {
+        if (key === 'title' || key === 'fallback') {
+            continue;
+        }
+        const usage = limits[key];
+        if (!usage.over && usage.percent >= NEAR_LIMIT_PERCENT) {
+            out.push({
+                severity: 'warn',
+                source: 'limit',
+                code: `near-limit/${key}`,
+                section: key,
+                message: `${key === 'total' ? 'css + html + js' : `The ${key} section`} uses ${usage.percent}% of its ${fmt(usage.max)}-character limit.`,
+                fix: 'A small edit could push it over. Trim it, or split the idea into two widgets.',
+            });
+        }
+    }
+    return out;
+}
+// ── JavaScript syntax (compile only) ────────────────────────────────────────
+const SYNTAX_FIXES = [
+    [
+        /Cannot use import statement/,
+        "A static import is not allowed in a classic script. Use `const lib = await import('d3')` inside an async function, by bare library name.",
+    ],
+    [
+        /await is only valid/,
+        'The js section is a classic script: no top-level await. Put the await inside an async function and call it.',
+    ],
+    [
+        /Illegal return statement/,
+        'A classic script has no top-level return; wrap the code in a function.',
+    ],
+];
+/**
+ * The message of anything thrown. Duck-typed, not `instanceof Error`: an error
+ * thrown by `vm.Script` or `JSON.parse` can come from another realm (a jest
+ * context, a worker), where `instanceof` is false and the real message is lost.
+ */
+function errorMessage(err) {
+    const message = err?.message;
+    return typeof message === 'string' ? message : String(err);
+}
+function syntaxIssue(script, section, firstLine) {
+    try {
+        // Compile only. `vm.Script` parses and reports early errors; it never runs the code.
+        new vm.Script(script, { filename: 'widget.js' });
+        return null;
+    }
+    catch (err) {
+        const message = errorMessage(err);
+        const stack = err?.stack;
+        const head = typeof stack === 'string' ? stack.split('\n')[0] : '';
+        const at = /^widget\.js:(\d+)/.exec(head);
+        const fix = SYNTAX_FIXES.find(([pattern]) => pattern.test(message))?.[1];
+        return {
+            severity: 'error',
+            source: 'syntax',
+            code: 'syntax/js',
+            section,
+            line: firstLine + (at ? Number(at[1]) - 1 : 0),
+            message: `JavaScript syntax error: ${message}. The script would stop before running.`,
+            ...(fix ? { fix } : {}),
+        };
+    }
+}
+function staticIssue(finding) {
+    return {
+        severity: finding.severity,
+        source: 'static',
+        code: `static/${finding.code}`,
+        section: finding.section,
+        line: finding.line,
+        message: finding.message,
+        ...(finding.fix ? { fix: finding.fix } : {}),
+        heuristic: true,
+    };
+}
+/** Syntax and static findings for the three sections. Only call it on sections within the limits. */
+function contentIssues(parts) {
+    const issues = [];
+    if (parts.js.trim() !== '') {
+        const syntax = syntaxIssue(parts.js, 'js', 1);
+        if (syntax) {
+            issues.push(syntax);
+        }
+    }
+    const scan = (0, widgetStaticScan_1.scanWidgetSource)(parts);
+    for (const script of scan.inlineScripts) {
+        const syntax = syntaxIssue(script.content, 'html', script.line);
+        if (syntax) {
+            issues.push(syntax);
+        }
+    }
+    for (const finding of scan.findings) {
+        issues.push(staticIssue(finding));
+    }
+    return issues;
+}
+// ── finishing a widget ──────────────────────────────────────────────────────
+/** The order a person reads a widget in. The section names come from the contract, not from here. */
+const SECTION_ORDER = [
+    'header',
+    'title',
+    ...data_provider_1.UI_WIDGET_FENCE.sections,
+    'fallbackText',
+    'total',
+];
+function sectionRank(section) {
+    const at = section === undefined ? -1 : SECTION_ORDER.indexOf(section);
+    return at === -1 ? SECTION_ORDER.length : at;
+}
+/** Errors before warnings, then in the order a person reads the source: section, then line. */
+function sortIssues(issues) {
+    return issues
+        .map((issue, index) => ({ issue, index }))
+        .sort((a, b) => Number(b.issue.severity === 'error') - Number(a.issue.severity === 'error') ||
+        sectionRank(a.issue.section) - sectionRank(b.issue.section) ||
+        (a.issue.line ?? 0) - (b.issue.line ?? 0) ||
+        a.index - b.index)
+        .map(({ issue }) => issue);
+}
+function finishWidget(widget, strict) {
+    const hasError = widget.issues.some((i) => i.severity === 'error');
+    const hasWarn = widget.issues.some((i) => i.severity === 'warn');
+    return {
+        ...widget,
+        issues: sortIssues(widget.issues),
+        ok: widget.accepted && !hasError && !(strict && hasWarn),
+    };
+}
+// ── fence input ─────────────────────────────────────────────────────────────
+/** The opener, generated from the contract so this file never spells the grammar. */
+function exampleOpener() {
+    return (0, data_provider_1.renderUiWidgetFence)({ title: 'Short title', initialHeight: 420 }).split('\n')[0];
+}
+function grammarFix(reason, message) {
+    const order = data_provider_1.UI_WIDGET_FENCE.markers.join(', ');
+    switch (reason) {
+        case 'invalid-header':
+            return `Write the opening line like ${exampleOpener()}: the title in quotes, height an integer, nothing after the closing brace.`;
+        case 'invalid-payload':
+            if (/more than once/.test(message)) {
+                return `Use each section at most once (${order}; the platform reads them in any order). Any of them may be left out.`;
+            }
+            if (/no html or js/.test(message)) {
+                return 'Add an html section or a js section; a stylesheet alone is refused.';
+            }
+            if (/before the first section marker/.test(message)) {
+                return `Start the first line after the opening line with a section marker (${order}).`;
+            }
+            return undefined;
+        case 'oversize':
+            return `Limits: css ${fmt(data_provider_1.UI_WIDGET_LIMITS.cssMax)}, html ${fmt(data_provider_1.UI_WIDGET_LIMITS.htmlMax)}, js ${fmt(data_provider_1.UI_WIDGET_LIMITS.jsMax)}, ${fmt(data_provider_1.UI_WIDGET_LIMITS.totalMax)} in all. Shorten it or split it into several widgets.`;
+        case 'too-many':
+            return `A message carries at most ${data_provider_1.UI_WIDGET_LIMITS.perMessageMax} widgets. Merge ideas or drop the extras.`;
+        case 'truncated':
+            return 'Close the block with a line of colons at least as long as the opening line. If the reply was cut off by a length limit, write a shorter widget.';
+        default:
+            return undefined;
+    }
+}
+function overflowKey(message) {
+    for (const section of data_provider_1.UI_WIDGET_FENCE.sections) {
+        if (message.startsWith(`${section} exceeds`)) {
+            return section;
+        }
+    }
+    return 'total';
+}
+function fenceReportFromPartial(partial) {
+    return {
+        css: partial?.css ?? '',
+        html: partial?.html ?? '',
+        js: partial?.js ?? '',
+        title: partial?.title ?? '',
+        fallback: partial?.fallbackText ?? '',
+    };
+}
+function checkFenceText(text, strict) {
+    // CR and CRLF each count as one line break in the grammar, and inside a block
+    // they are normalised to LF anyway, so normalising first changes no verdict.
+    const normalised = text.replace(/\r\n?/g, '\n');
+    const trailingBreak = normalised.endsWith('\n');
+    const lines = normalised.split('\n');
+    if (trailingBreak) {
+        lines.pop();
+    }
+    const parser = (0, data_provider_1.createUiWidgetFenceParser)();
+    const open = new Map();
+    const widgets = [];
+    let outside = '';
+    let sawOpener = false;
+    const handle = (event, lineNo, atEnd) => {
+        switch (event.type) {
+            case 'text':
+                outside += event.text;
+                break;
+            case 'widget-open':
+                sawOpener = true;
+                open.set(event.id, { id: event.id, title: event.title, line: lineNo, sections: new Set() });
+                break;
+            case 'widget-section':
+                open.get(event.id)?.sections.add(event.section);
+                break;
+            case 'widget-complete': {
+                sawOpener = true;
+                const block = open.get(event.id);
+                const payload = event.payload;
+                const sized = sizeBlock({
+                    css: payload.css,
+                    html: payload.html,
+                    js: payload.js,
+                    title: payload.title,
+                    fallback: payload.fallbackText ?? '',
+                });
+                const issues = [];
+                if (!block?.sections.has('fallback')) {
+                    issues.push({
+                        severity: 'warn',
+                        source: 'content',
+                        code: 'no-fallback',
+                        section: 'fallback',
+                        message: 'No fallback text, so the title stands in for it. Search, notifications, voice, chat integrations and older apps show only that.',
+                        fix: `Add a ${data_provider_1.UI_WIDGET_FENCE.markers[3]} section with one or two plain sentences saying what the widget shows.`,
+                    });
+                }
+                issues.push(...nearLimitIssues(sized.limits), ...contentIssues(payload));
+                widgets.push(finishWidget({
+                    id: payload.id,
+                    title: payload.title,
+                    kind: 'fence',
+                    ...(block ? { line: block.line } : {}),
+                    complete: true,
+                    measured: true,
+                    accepted: true,
+                    ...sized,
+                    issues,
+                }, strict));
+                break;
+            }
+            case 'widget-error': {
+                sawOpener = true;
+                const block = open.get(event.id);
+                const message = event.message ?? event.reason;
+                const overflow = event.reason === 'oversize' ? overflowKey(message) : undefined;
+                const sized = sizeBlock(fenceReportFromPartial(event.partial), overflow);
+                const startLine = block?.line ?? lineNo;
+                let where = `${message}.`;
+                if (event.reason === 'truncated') {
+                    where = `The block that starts at line ${startLine} never closed${atEnd ? ' before the input ended' : ''}.`;
+                }
+                else if (block) {
+                    where = `In the block that starts at line ${block.line}: ${message}.`;
+                }
+                const issues = [
+                    {
+                        severity: 'error',
+                        source: 'grammar',
+                        code: `fence/${event.reason}`,
+                        ...(event.reason === 'invalid-header' || !block ? { section: 'header' } : {}),
+                        line: event.reason === 'truncated' ? startLine : lineNo,
+                        message: where,
+                        ...(grammarFix(event.reason, message)
+                            ? { fix: grammarFix(event.reason, message) }
+                            : {}),
+                    },
+                ];
+                if (event.reason === 'oversize' && overflow) {
+                    issues.push(limitIssue(overflow, sized.limits[overflow]));
+                }
+                widgets.push(finishWidget({
+                    id: event.id,
+                    title: block?.title ?? null,
+                    kind: 'fence',
+                    line: startLine,
+                    complete: false,
+                    measured: event.partial !== undefined,
+                    accepted: false,
+                    ...sized,
+                    issues,
+                }, strict));
+                break;
+            }
+            default:
+                break;
+        }
+    };
+    if (normalised.length > 0) {
+        lines.forEach((line, index) => {
+            const last = index === lines.length - 1;
+            const chunk = last && !trailingBreak ? line : `${line}\n`;
+            for (const event of parser.push(chunk)) {
+                handle(event, index + 1, false);
+            }
+        });
+    }
+    for (const event of parser.end()) {
+        handle(event, Math.max(lines.length, 1), true);
+    }
+    return { widgets, sawOpener, residue: outside.includes(data_provider_1.UI_WIDGET_FENCE.name) };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringField(value, key) {
+    const field = value[key];
+    return typeof field === 'string' ? field : '';
+}
+function allowedKeys(schema) {
+    const shape = schema.shape;
+    return shape ? Object.keys(shape).join(', ') : '';
+}
+/** Zod's complaint, made plain. Size findings are reported by `limitIssue`, so those are skipped. */
+function schemaIssues(issues, schema, handled) {
+    const out = [];
+    for (const issue of issues) {
+        const field = typeof issue.path[0] === 'string' ? issue.path[0] : undefined;
+        if (issue.code === 'too_big' && field && handled.has(field)) {
+            continue;
+        }
+        if (issue.code === 'custom' && /exceeds .* characters/.test(issue.message)) {
+            continue;
+        }
+        let message;
+        let fix;
+        if (issue.code === 'unrecognized_keys') {
+            const allowed = allowedKeys(schema);
+            message = `Unknown field${(issue.keys?.length ?? 0) === 1 ? '' : 's'}: ${(issue.keys ?? []).join(', ')}. The widget shape is strict.`;
+            fix = allowed ? `Allowed fields: ${allowed}.` : undefined;
+        }
+        else if (field === 'title' && issue.code === 'too_small') {
+            message = `title is required (1 to ${data_provider_1.UI_WIDGET_LIMITS.titleMax} characters).`;
+        }
+        else if (field === 'initialHeight') {
+            message = `initialHeight must be an integer from ${data_provider_1.UI_WIDGET_LIMITS.heightMin} to ${data_provider_1.UI_WIDGET_LIMITS.heightHardMax}.`;
+        }
+        else if (field === 'fallbackText' && issue.code === 'custom') {
+            message = 'A complete widget must carry fallbackText.';
+            fix =
+                'Add one or two plain sentences saying what the widget shows: search, notifications, voice and older apps show it instead of the markup.';
+        }
+        else if (field === 'v') {
+            message = 'v must be 1.';
+        }
+        else {
+            message = `${issue.path.length > 0 ? `${issue.path.map(String).join('.')}: ` : ''}${issue.message}`;
+        }
+        out.push({
+            severity: 'error',
+            source: 'schema',
+            code: `schema/${issue.code}`,
+            ...(field ? { section: field } : {}),
+            message,
+            ...(fix ? { fix } : {}),
+        });
+    }
+    return out;
+}
+const SIZED_FIELDS = new Set([
+    ...data_provider_1.UI_WIDGET_FENCE.sections.filter((section) => section !== 'fallback'),
+    'title',
+    'fallbackText',
+]);
+function unwrapPart(value) {
+    if (isRecord(value) &&
+        value.type === data_provider_1.UI_WIDGET_PART_TYPE &&
+        isRecord(value[data_provider_1.UI_WIDGET_PART_TYPE])) {
+        return value[data_provider_1.UI_WIDGET_PART_TYPE];
+    }
+    return value;
+}
+function checkJsonWidget(raw, index, strict) {
+    const fallbackId = `w${index + 1}`;
+    const value = unwrapPart(raw);
+    if (!isRecord(value)) {
+        return {
+            report: finishWidget({
+                id: fallbackId,
+                title: null,
+                kind: 'payload',
+                complete: false,
+                measured: false,
+                accepted: false,
+                ...sizeBlock({ css: '', html: '', js: '', title: '', fallback: '' }),
+                issues: [
+                    {
+                        severity: 'error',
+                        source: 'schema',
+                        code: 'schema/invalid_type',
+                        message: `Element ${index + 1} is ${Array.isArray(value) ? 'an array' : typeof value}; a widget is a JSON object.`,
+                        fix: 'Pass a widget payload, a ui_widget part, or the ui_widget_render tool arguments.',
+                    },
+                ],
+            }, strict),
+        };
+    }
+    const isPayload = 'v' in value || 'id' in value || 'complete' in value || 'source' in value;
+    const kind = isPayload ? 'payload' : 'tool-input';
+    const schema = isPayload ? data_provider_1.UiWidgetPayloadSchema : data_provider_1.UiWidgetToolInputSchema;
+    const parts = {
+        css: stringField(value, 'css'),
+        html: stringField(value, 'html'),
+        js: stringField(value, 'js'),
+        title: stringField(value, 'title'),
+        fallback: stringField(value, 'fallbackText'),
+    };
+    const sized = sizeBlock(parts);
+    const issues = [];
+    for (const key of limitsExceeded(sized.limits)) {
+        issues.push(limitIssue(key, sized.limits[key]));
+    }
+    const parsed = schema.safeParse(value);
+    const accepted = parsed.success;
+    if (!parsed.success) {
+        issues.push(...schemaIssues(parsed.error.issues, schema, SIZED_FIELDS));
+    }
+    const complete = isPayload ? value.complete === true : true;
+    if (isPayload && value.complete === false) {
+        issues.push({
+            severity: 'warn',
+            source: 'content',
+            code: 'incomplete',
+            section: 'complete',
+            message: 'complete is false: this widget is still being written, so a surface shows it unfinished.',
+            fix: 'Send the final widget with complete: true and a fallbackText.',
+        });
+    }
+    if (parts.html.trim() === '' && parts.js.trim() === '') {
+        issues.push({
+            severity: 'warn',
+            source: 'content',
+            code: 'empty-widget',
+            message: 'No html and no js: the frame would be empty. (A fence block with neither is refused.)',
+            fix: 'Add markup or a script that builds the page.',
+        });
+    }
+    // Content checks read the source; skip them when a size limit is already broken,
+    // because the widget is refused anyway and the scan's cost should stay bounded.
+    const withinLimits = limitsExceeded(sized.limits).length === 0;
+    if (withinLimits) {
+        issues.push(...nearLimitIssues(sized.limits), ...contentIssues(parts));
+    }
+    else {
+        issues.push({
+            severity: 'warn',
+            source: 'content',
+            code: 'content-not-checked',
+            message: 'Syntax and static checks were skipped because a size limit is exceeded. Fix the size first.',
+        });
+    }
+    const id = isPayload && typeof value.id === 'string' && value.id !== '' ? value.id : fallbackId;
+    const render = {
+        title: parts.title.trim(),
+        css: parts.css,
+        html: parts.html,
+        js: parts.js,
+        ...(parts.fallback.trim() ? { fallbackText: parts.fallback.trim() } : {}),
+        ...(typeof value.initialHeight === 'number' ? { initialHeight: value.initialHeight } : {}),
+        ...(isPayload && typeof value.id === 'string' && value.id !== '' ? { id: value.id } : {}),
+    };
+    return {
+        report: finishWidget({
+            id,
+            title: parts.title.trim() || null,
+            kind,
+            complete,
+            measured: true,
+            accepted,
+            ...sized,
+            issues,
+        }, strict),
+        ...(accepted ? { render } : {}),
+    };
+}
+function tooManyWidget(index) {
+    return {
+        id: `w${index + 1}`,
+        title: null,
+        kind: 'payload',
+        complete: false,
+        measured: false,
+        accepted: false,
+        ok: false,
+        ...sizeBlock({ css: '', html: '', js: '', title: '', fallback: '' }),
+        issues: [
+            {
+                severity: 'error',
+                source: 'grammar',
+                code: TOO_MANY_CODE,
+                message: `Widget ${index + 1} is over the per-message limit: at most ${data_provider_1.UI_WIDGET_LIMITS.perMessageMax} widgets per message, and the rest are refused.`,
+                fix: `Merge ideas or drop the extras (a message carries at most ${data_provider_1.UI_WIDGET_LIMITS.perMessageMax}).`,
+            },
+        ],
+    };
+}
+const TOO_MANY_CODE = 'fence/too-many';
+/**
+ * Keep the first block past the per-message cap and fold the rest into its
+ * message: a hostile input with a hundred thousand blocks must not become a
+ * hundred thousand report entries, and the person needs one line, not all of them.
+ */
+function collapseTooMany(widgets) {
+    const out = [];
+    let first;
+    let extra = 0;
+    for (const widget of widgets) {
+        if (widget.issues[0]?.code !== TOO_MANY_CODE) {
+            out.push(widget);
+        }
+        else if (!first) {
+            first = widget;
+            out.push(widget);
+        }
+        else {
+            extra += 1;
+        }
+    }
+    if (first) {
+        noteExcess(first, extra);
+    }
+    return out;
+}
+function noteExcess(widget, extra) {
+    if (extra <= 0) {
+        return;
+    }
+    const issue = widget.issues[0];
+    widget.issues[0] = {
+        ...issue,
+        message: `${issue.message} ${fmt(extra)} more after it ${extra === 1 ? 'is' : 'are'} refused too.`,
+    };
+}
+/** `JSON.parse`, and one more round when the result is a string: tool arguments often arrive that way. */
+function parseJsonInput(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (err) {
+        return { ok: false, message: errorMessage(err) };
+    }
+    if (typeof value === 'string') {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            return {
+                ok: false,
+                message: 'the JSON value is a string, and that string is not itself valid JSON',
+            };
+        }
+    }
+    return { ok: true, value };
+}
+function finalize(format, widgets, errors, warnings, strict) {
+    const widgetErrors = widgets.reduce((n, w) => n + w.issues.filter((i) => i.severity === 'error').length, 0);
+    const widgetWarnings = widgets.reduce((n, w) => n + w.issues.filter((i) => i.severity === 'warn').length, 0);
+    return {
+        reportVersion: exports.WIDGET_CHECK_REPORT_VERSION,
+        ok: errors.length === 0 &&
+            widgets.length > 0 &&
+            widgets.every((w) => w.ok) &&
+            !(strict && warnings.length > 0),
+        format,
+        widgets,
+        errors,
+        warnings,
+        summary: {
+            widgets: widgets.length,
+            accepted: widgets.filter((w) => w.accepted).length,
+            ok: widgets.filter((w) => w.ok).length,
+            errors: errors.length + widgetErrors,
+            warnings: warnings.length + widgetWarnings,
+        },
+        heuristic: exports.WIDGET_CHECK_HEURISTIC_NOTE,
+    };
+}
+/** The report for an input that could not even be read (a missing file, a terminal as stdin). */
+function inputErrorReport(error) {
+    return finalize('unknown', [], [error], [], false);
+}
+function noWidgetError(text, jsonMessage, forced = false) {
+    if (jsonMessage) {
+        return {
+            code: 'input/invalid-json',
+            message: forced
+                ? `The input is not valid JSON: ${jsonMessage}.`
+                : `No widget block found, and the input does not parse as JSON either (${jsonMessage}).`,
+            fix: 'Pass a widget payload or the ui_widget_render tool arguments as one JSON value, or a text file that contains a widget block.',
+        };
+    }
+    if (text.trim() === '') {
+        return {
+            code: 'input/empty',
+            message: 'The input is empty, so there is no widget to check.',
+        };
+    }
+    if (text.includes(data_provider_1.UI_WIDGET_FENCE.name)) {
+        return {
+            code: 'input/no-widget',
+            message: 'The text names the widget fence but contains no block the parser recognises. A block must start at the first column of a line, with four or more colons, outside any code fence, list or quote.',
+            fix: `Open with ${exampleOpener()} at column 0, and close with a line of at least as many colons.`,
+        };
+    }
+    return {
+        code: 'input/no-widget',
+        message: 'No widget block found in the input.',
+        fix: `A widget block opens with a line like ${exampleOpener()} at column 0. For JSON input, pass a widget payload or the ui_widget_render arguments.`,
+    };
+}
+/**
+ * Check one input: a file's text that contains a widget block, or a JSON widget.
+ * Total: never throws, whatever the input.
+ */
+function checkWidgetInput(raw, options = {}) {
+    const strict = options.strict === true;
+    const format = options.format ?? 'auto';
+    const none = [];
+    const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    if (text.length > exports.WIDGET_CHECK_MAX_INPUT_CHARS) {
+        return {
+            report: finalize('unknown', [], [
+                {
+                    code: 'input/too-large',
+                    message: `The input is ${fmt(text.length)} characters; the check reads at most ${fmt(exports.WIDGET_CHECK_MAX_INPUT_CHARS)}. A message carries at most ${data_provider_1.UI_WIDGET_LIMITS.perMessageMax} widgets of ${fmt(data_provider_1.UI_WIDGET_LIMITS.totalMax)} characters.`,
+                },
+            ], [], strict),
+            renderable: none,
+        };
+    }
+    const firstChar = text.trimStart().charAt(0);
+    const looksJson = firstChar === '{' || firstChar === '[' || firstChar === '"';
+    const asJson = format === 'json' || (format === 'auto' && looksJson);
+    let jsonFailure;
+    if (asJson) {
+        const parsed = parseJsonInput(text);
+        if (parsed.ok) {
+            const elements = Array.isArray(parsed.value) ? parsed.value : [parsed.value];
+            if (elements.length === 0) {
+                return {
+                    report: finalize('json', [], [
+                        {
+                            code: 'input/no-widget',
+                            message: 'The JSON array is empty, so there is no widget to check.',
+                        },
+                    ], [], strict),
+                    renderable: none,
+                };
+            }
+            const widgets = [];
+            const renderable = [];
+            const warnings = [];
+            const seen = new Set();
+            let excess = 0;
+            elements.forEach((element, index) => {
+                if (index >= data_provider_1.UI_WIDGET_LIMITS.perMessageMax) {
+                    excess += 1;
+                    if (excess === 1) {
+                        widgets.push(tooManyWidget(index));
+                    }
+                    return;
+                }
+                const result = checkJsonWidget(element, index, strict);
+                if (seen.has(result.report.id)) {
+                    result.report.issues.push({
+                        severity: 'warn',
+                        source: 'content',
+                        code: 'duplicate-id',
+                        section: 'id',
+                        message: `Another widget in this input already uses the id "${result.report.id}".`,
+                        fix: 'Give each widget of a message its own id.',
+                    });
+                    result.report.ok = result.report.ok && !strict;
+                }
+                seen.add(result.report.id);
+                widgets.push(result.report);
+                if (result.render) {
+                    renderable.push({ index, input: result.render });
+                }
+            });
+            if (excess > 1) {
+                noteExcess(widgets[widgets.length - 1], excess - 1);
+            }
+            return { report: finalize('json', widgets, [], warnings, strict), renderable };
+        }
+        jsonFailure = parsed.message;
+        if (format === 'json') {
+            return {
+                report: finalize('json', [], [noWidgetError(text, jsonFailure, true)], [], strict),
+                renderable: none,
+            };
+        }
+    }
+    const outcome = checkFenceText(text, strict);
+    if (outcome.widgets.length === 0) {
+        return {
+            report: finalize(looksJson ? 'json' : 'fence', [], [noWidgetError(text, looksJson && !outcome.sawOpener ? jsonFailure : undefined)], [], strict),
+            renderable: none,
+        };
+    }
+    const warnings = outcome.residue
+        ? [
+            {
+                code: 'input/fence-name-in-text',
+                message: 'The text outside the recognised blocks still names the widget fence. If one of those is a block that is indented, in a list or quote, or inside a code fence, it is not recognised and will show as plain text.',
+                fix: 'Write every real block at the first column, outside code fences. Ignore this if the text is only describing the syntax.',
+            },
+        ]
+        : [];
+    return {
+        report: finalize('fence', collapseTooMany(outcome.widgets), [], warnings, strict),
+        renderable: none,
+    };
+}
+/**
+ * Serialise the JSON widgets that passed the schema to correctly delimited fence
+ * blocks, and prove each one: the block is parsed back with the same parser the
+ * ingest uses and must yield the same title, sections and fallback. The colon
+ * count is chosen by `renderUiWidgetFence`, so a widget whose code contains a line
+ * of colons still gets a closing line it cannot end early.
+ */
+function renderWidgetFences(result) {
+    const fences = [];
+    const errors = [];
+    if (result.report.format !== 'json') {
+        errors.push({
+            code: 'render/needs-json',
+            message: 'There is nothing to render: the input is not a JSON widget (it is already text).',
+            fix: 'Pass a widget payload or the ui_widget_render arguments as JSON.',
+        });
+        return { fences, errors };
+    }
+    for (const { index, input } of result.renderable) {
+        const label = `widget ${index + 1}`;
+        let block;
+        try {
+            block = (0, data_provider_1.renderUiWidgetFence)(input);
+        }
+        catch (err) {
+            errors.push({
+                code: 'render/unrepresentable',
+                message: `${label}: ${errorMessage(err)}`,
+                fix: 'Reword or indent the offending line of code.',
+            });
+            continue;
+        }
+        const back = (0, data_provider_1.parseUiWidgetFences)(block);
+        const widget = back.widgets[0];
+        const css = (input.css ?? '').replace(/\r\n?/g, '\n');
+        const html = (input.html ?? '').replace(/\r\n?/g, '\n');
+        const js = (input.js ?? '').replace(/\r\n?/g, '\n');
+        const matches = back.errors.length === 0 &&
+            back.widgets.length === 1 &&
+            widget.title === input.title &&
+            widget.css === css &&
+            widget.html === html &&
+            widget.js === js &&
+            widget.fallbackText === (input.fallbackText ?? input.title);
+        if (!matches) {
+            errors.push({
+                code: 'render/roundtrip',
+                message: `${label}: the rendered block does not parse back to the same widget${back.errors[0]?.message ? ` (${back.errors[0].message})` : ''}.`,
+                fix: 'Check the widget with `skrr widgets check` on the JSON first and fix what it reports.',
+            });
+            continue;
+        }
+        fences.push(block);
+    }
+    if (fences.length === 0 && errors.length === 0 && result.report.errors.length === 0) {
+        errors.push({
+            code: 'render/nothing',
+            message: 'No widget in the input passed the schema, so there is nothing to render.',
+            fix: 'Run the check on the JSON and fix what it reports.',
+        });
+    }
+    return { fences, errors };
+}
+// ── human output ────────────────────────────────────────────────────────────
+function usageLine(label, usage) {
+    const used = usage.atLeast ? `over ${fmt(usage.max)}` : fmt(usage.used);
+    const flag = usage.over ? '  OVER LIMIT' : '';
+    return `  ${label.padEnd(9)} ${used.padStart(9)} / ${fmt(usage.max).padEnd(9)} ${usage.atLeast ? '' : `${usage.percent}%`}${flag}`.trimEnd();
+}
+function issueLines(issue) {
+    const where = [issue.section, issue.line !== undefined ? `line ${issue.line}` : undefined]
+        .filter(Boolean)
+        .join(' ');
+    const tag = issue.severity === 'error' ? 'error' : 'warn ';
+    const lines = [
+        `  ${tag}  ${where ? `${where}: ` : ''}${issue.message}${issue.heuristic ? ' (heuristic)' : ''}`,
+    ];
+    if (issue.fix) {
+        lines.push(`         fix: ${issue.fix}`);
+    }
+    return lines;
+}
+function verdict(widget) {
+    if (!widget.accepted) {
+        return 'would be REFUSED: the message would show an error state instead of the widget';
+    }
+    const errors = widget.issues.filter((i) => i.severity === 'error');
+    if (errors.length > 0) {
+        return `would be accepted, but ${errors.length} finding${errors.length === 1 ? '' : 's'} predict${errors.length === 1 ? 's' : ''} a failure inside the frame`;
+    }
+    return 'would be accepted';
+}
+/** The report as lines of plain text, for a person or a model reading a terminal. */
+function formatWidgetCheckReport(report) {
+    const out = [];
+    for (const widget of report.widgets) {
+        const origin = widget.line !== undefined ? `, line ${widget.line}` : '';
+        out.push(`Widget ${widget.id}${widget.title ? ` "${widget.title}"` : ''} (${widget.kind}${origin})`);
+        if (widget.measured) {
+            out.push(usageLine('css', widget.limits.css));
+            out.push(usageLine('html', widget.limits.html));
+            out.push(usageLine('js', widget.limits.js));
+            out.push(usageLine('total', widget.limits.total));
+            out.push(usageLine('title', widget.limits.title));
+            out.push(usageLine('fallback', widget.limits.fallback));
+        }
+        else {
+            out.push('  size: not measured (the content was never read)');
+        }
+        for (const issue of widget.issues) {
+            out.push(...issueLines(issue));
+        }
+        out.push(`  ${verdict(widget)}.`);
+        out.push('');
+    }
+    for (const error of report.errors) {
+        out.push(`error: ${error.message}`);
+        if (error.fix) {
+            out.push(`  fix: ${error.fix}`);
+        }
+    }
+    for (const warning of report.warnings) {
+        out.push(`warn: ${warning.message}`);
+        if (warning.fix) {
+            out.push(`  fix: ${warning.fix}`);
+        }
+    }
+    const { widgets, accepted, ok, errors, warnings } = report.summary;
+    out.push(`${report.ok ? 'OK' : 'NOT OK'}: ${widgets} widget${widgets === 1 ? '' : 's'} checked, ${accepted} accepted, ${ok} clean; ${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'}.`);
+    out.push(report.heuristic);
+    return out;
+}