tinybeeai 0.0.0-stage → 0.16.1

package/dist/view-spec.js

@@ -0,0 +1,894 @@
+// Validation for composed chat views (KAT-366, docs/CHAT-UI.md "Composed views"). The model composes a view from our
+// own components: layout nodes (column, row, tabs, section), short text, and the answer blocks. This file is the one
+// registry of those components and the checks every spec goes through. The server runs it before it binds a view to
+// tool results, and the client runs it again before it renders, with the same rules as parseChatBlock:
+//
+// - A component or a prop that is not in the registry is dropped and counted. There is no HTML, no CSS, no class name,
+//   no color (only a tone from an enum, which the client maps to theme tokens), and no action: a button comes from a
+//   block, and the client wires it to the same routes as any block.
+// - Depth, node, child, and step counts are capped. Strings are trimmed and capped, and a string that holds an HTML
+//   tag is dropped. Links must be http or https.
+// - A dataset whose pipeline has one bad step is dropped whole, and so is every node that reads it, because a pipeline
+//   with a skipped step would show wrong numbers.
+//
+// Pure and dependency free, so the client imports the same file (`@view-spec`).
+import { clean, isObj, num, oneOf, safeHttpUrl, str } from './chat-parse-util.js';
+export const MAX_VIEW_DEPTH = 4;
+export const MAX_VIEW_NODES = 40;
+export const MAX_VIEW_CHILDREN = 12;
+export const MAX_VIEW_TABS = 6;
+export const MAX_VIEW_DATASETS = 8;
+export const MAX_VIEW_STEPS = 8;
+export const MAX_VIEW_VARS = 12;
+export const MAX_VIEW_TILES = 6;
+export const MAX_VIEW_COLUMNS = 6;
+export const MAX_VIEW_SERIES = 4;
+export const MAX_VIEW_CONDITIONS = 6;
+export const MAX_VIEW_AGGS = 6;
+export const MAX_VIEW_NOTES = 12;
+/** Rows of one source table the server sends to the client, and cells in all of them. */
+export const MAX_SOURCE_ROWS = 2000;
+export const MAX_SOURCE_CELLS = 12_000;
+export const MAX_SOURCE_COLUMNS = 12;
+/** Characters of a text cell that go to the client. */
+export const MAX_CELL_TEXT = 120;
+const CAP = { title: 80, label: 60, text: 600, finding: 240, tileValue: 60, tileSub: 120, unit: 12, cell: 120 };
+export const VIEW_LAYOUT_TYPES = ['column', 'row', 'section', 'tabs', 'text'];
+export const VIEW_RECORD_TYPES = [
+    'runs',
+    'pulls',
+    'approvals',
+    'defects',
+    'probes',
+    'memory',
+    'ticket_review',
+    'test_cases',
+    'cards',
+    'release_call',
+];
+/** Every component a view may hold: the 14 answer blocks (all but `view`) and the layout nodes. */
+export const VIEW_NODE_TYPES = [...VIEW_LAYOUT_TYPES, ...VIEW_RECORD_TYPES, 'triage', 'table', 'stats', 'chart'];
+export const VIEW_FORMATS = ['text', 'number', 'percent', 'duration', 'hour', 'weekday', 'day', 'spec'];
+export const VIEW_BUCKETS = ['hour', 'hour_of_day', 'day', 'weekday', 'week', 'month'];
+const COMPARES = ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'contains'];
+const AGG_FNS = ['count', 'sum', 'avg', 'min', 'max', 'distinct'];
+const EXPR_FNS = ['ratio', 'percent', 'change', 'diff'];
+const SCALAR_FNS = ['count', 'sum', 'avg', 'min', 'max', 'cell'];
+const CHART_TYPES = ['bar', 'stacked_bar', 'line'];
+const TRIAGE_WINDOWS = ['last_merge', 'today', 'recent'];
+const TONES = ['ok', 'attention', 'bad'];
+const title = { kind: 'string', max: CAP.title };
+const limit = (max) => ({ kind: 'int', min: 1, max });
+/** One entry per component. Names, types, and allowed values of every prop a node may carry; nothing else passes. */
+export const VIEW_COMPONENTS = {
+    column: { summary: 'Stacks its children.', props: { children: { kind: 'nodes', required: true } } },
+    row: { summary: 'Puts its children side by side when there is room, else stacks them.', props: { children: { kind: 'nodes', required: true } } },
+    section: { summary: 'A heading over its children.', props: { title: { ...title, required: true }, children: { kind: 'nodes', required: true } } },
+    tabs: { summary: 'One tab shows at a time.', props: { tabs: { kind: 'tabs', required: true } } },
+    text: {
+        summary: 'A short line of prose.',
+        props: { text: { kind: 'string', max: CAP.text, required: true }, tone: { kind: 'enum', values: ['muted'] }, href: { kind: 'url' } },
+    },
+    runs: { summary: 'Test runs, from a list_runs or runs_in_progress result.', props: recordProps() },
+    pulls: { summary: 'Open pull requests, from an open_prs result.', props: recordProps() },
+    approvals: { summary: 'Drafts that wait for approval, from a pending_approvals result.', props: recordProps() },
+    defects: { summary: 'Defects, from a recent_defects result.', props: recordProps() },
+    probes: { summary: 'Probe status, from a probe_status result.', props: recordProps() },
+    memory: { summary: 'What the dot remembers, from a get_memory result.', props: recordProps() },
+    ticket_review: { summary: 'A ticket review, from a list_tickets_reviewed or get_ticket result.', props: recordProps() },
+    test_cases: { summary: 'Test cases, from a list_cases result.', props: recordProps() },
+    cards: { summary: 'The card of a ticket, from a get_ticket result.', props: recordProps() },
+    release_call: { summary: 'The release call of a lead, from a release_call result.', props: recordProps() },
+    triage: {
+        summary: 'Failed and flaky tests of recent runs, grouped by cause, built from the stored runs.',
+        props: { window: { kind: 'enum', values: TRIAGE_WINDOWS }, title },
+    },
+    table: {
+        summary: 'A table of a dataset, or of a result that is already a table.',
+        props: { title, data: { kind: 'dataset' }, from: { kind: 'result' }, columns: { kind: 'columns' }, limit: limit(50) },
+    },
+    stats: {
+        summary: 'Big-number tiles. Each value is text, and {name} marks take values from vars.',
+        props: { title, tiles: { kind: 'tiles' }, from: { kind: 'result' } },
+    },
+    chart: {
+        summary: 'A bar, stacked bar, or line chart of a dataset, or of a result that is already a chart.',
+        props: {
+            title,
+            from: { kind: 'result' },
+            data: { kind: 'dataset' },
+            chartType: { kind: 'enum', values: CHART_TYPES },
+            x: { kind: 'field' },
+            xFormat: { kind: 'enum', values: VIEW_FORMATS },
+            series: { kind: 'series' },
+            unit: { kind: 'string', max: CAP.unit },
+            finding: { kind: 'string', max: CAP.finding },
+            limit: limit(31),
+        },
+    },
+};
+function recordProps() {
+    return {
+        from: { kind: 'result', required: true },
+        nth: { kind: 'int', min: 0, max: 9 },
+        title,
+        limit: limit(50),
+    };
+}
+/** The component names, for tests and for the tool description. */
+export const VIEW_COMPONENT_NAMES = Object.keys(VIEW_COMPONENTS);
+// ---------- Names, fields, strings ----------
+const RESULT_ID = /^r\d{1,3}$/;
+const DATASET_NAME = /^[a-z][A-Za-z0-9_]{0,23}$/;
+const FIELD = /^[A-Za-z_][A-Za-z0-9_]{0,39}(?:\.[A-Za-z_][A-Za-z0-9_]{0,39}){0,2}$/;
+const BAD_SEGMENT = /(?:^|\.)(?:__proto__|constructor|prototype)(?:\.|$)/;
+/** Names an object already has from its prototype. A dataset or var with one of them would shadow a built-in, so none is allowed. */
+const RESERVED_NAMES = new Set([
+    'constructor',
+    'prototype',
+    'toString',
+    'valueOf',
+    'hasOwnProperty',
+    'isPrototypeOf',
+    'propertyIsEnumerable',
+    'toLocaleString',
+    'toJSON',
+]);
+// A `<` that opens a tag, a closing tag, a comment, or a processing mark. The `>` is not needed: `<img src=x onerror=alert(1)` with
+// no closing bracket is still the start of a tag, and a prose line has no reason to put a letter right after a `<`.
+const MARKUP = /<\/?[a-zA-Z]|<[!?]/;
+const PLACEHOLDER = /\{([a-z][A-Za-z0-9_]{0,23})\}/g;
+/** A look-back window, which the model sets itself in the tool call, so it may say it. */
+const WINDOW = /\b(?:last|past|previous)\s+\d{1,3}\s+(?:hour|day|week|month)s?\b/gi;
+/** A word that is a number: digits with separators, an optional sign, and a percent sign or a short unit after them. */
+const TYPED_NUMBER = /^[+-]?\d[\d,.:/-]*(?:%|[a-zA-Z]{0,7})$/;
+export const isResultId = (v) => typeof v === 'string' && RESULT_ID.test(v);
+function fieldName(v) {
+    return typeof v === 'string' && v.length <= 82 && FIELD.test(v) && !BAD_SEGMENT.test(v) ? v : undefined;
+}
+/** The names a string asks the vars to fill: "Peak {peak}" asks for peak. */
+export function placeholdersIn(s) {
+    return [...s.matchAll(PLACEHOLDER)].map((m) => m[1]);
+}
+function note(ctx, text) {
+    if (ctx.notes.length < MAX_VIEW_NOTES)
+        ctx.notes.push(text);
+}
+/**
+ * The first number in a text that is typed out by hand: a word made of digits, with a sign, separators, a percent sign, or a short
+ * unit (`1234`, `99.9%`, `1,234`, `12ms`, `#58`). A {name} mark is a number the view computed, so it is not counted, and neither is a
+ * window the model asked the tool for ("the last 14 days"). The check looks at digits only: a number spelled out in words is not caught, and neither is a claim with no number in it.
+ */
+export function typedNumber(s) {
+    for (const raw of s.replace(PLACEHOLDER, ' ').replace(WINDOW, ' ').split(/\s+/)) {
+        const word = raw.replace(/^[("'*_~#<>=[]+|[)"'*_~\],.:;!?]+$/g, '');
+        if (word && TYPED_NUMBER.test(word))
+            return word;
+    }
+    return undefined;
+}
+/**
+ * A string prop: trimmed and capped. One that holds an HTML tag is dropped, so the page never gets markup from a view. With
+ * `figures: false` (prose, tile values, findings) one that holds a number typed by hand is dropped too: the numbers on screen come
+ * from tool results, through vars, and never from the model's own text.
+ */
+function text(ctx, path, v, max, opts = {}) {
+    if (v === undefined)
+        return undefined;
+    const s = str(v, max);
+    if (s === undefined) {
+        note(ctx, `${path} is not a text`);
+        return undefined;
+    }
+    if (MARKUP.test(s)) {
+        note(ctx, `${path} holds markup, which a view never carries`);
+        return undefined;
+    }
+    if (opts.figures === false) {
+        const typed = typedNumber(s);
+        if (typed) {
+            note(ctx, `${path} holds the number ${typed}, which comes from no tool result. Put it in vars and write {name} instead`);
+            return undefined;
+        }
+    }
+    for (const name of placeholdersIn(s))
+        if (!ctx.vars.has(name))
+            note(ctx, `${path} uses {${name}}, which is not in vars`);
+    return s;
+}
+function int(v, min, max) {
+    const n = num(v);
+    return n !== undefined && Number.isInteger(n) && n >= min && n <= max ? n : undefined;
+}
+// ---------- Datasets: conditions, steps, scalars ----------
+function parseCondition(o) {
+    if (!isObj(o))
+        return null;
+    const field = fieldName(o.field);
+    const is = oneOf(o.is, COMPARES);
+    if (!field || !is)
+        return null;
+    const v = o.value;
+    if (is === 'in') {
+        if (!Array.isArray(v) || !v.length || v.length > 20)
+            return null;
+        const list = v.filter((x) => (typeof x === 'string' && x.length <= CAP.cell) || (typeof x === 'number' && Number.isFinite(x)));
+        return list.length === v.length ? { field, is, value: list } : null;
+    }
+    if (is === 'contains')
+        return typeof v === 'string' && v && v.length <= CAP.cell ? { field, is, value: v } : null;
+    if (typeof v === 'string' && v.length <= CAP.cell)
+        return { field, is, value: v };
+    if (typeof v === 'number' && Number.isFinite(v))
+        return { field, is, value: v };
+    if (typeof v === 'boolean')
+        return { field, is, value: v };
+    return null;
+}
+function parseConditions(v, max = MAX_VIEW_CONDITIONS) {
+    if (!Array.isArray(v) || !v.length || v.length > max)
+        return null;
+    const out = v.map(parseCondition);
+    return out.every((c) => c !== null) ? out : null;
+}
+function parseExpr(o) {
+    if (!isObj(o))
+        return null;
+    const of = fieldName(o.of);
+    if (!of)
+        return null;
+    if (o.fn === 'bucket') {
+        const by = oneOf(o.by, VIEW_BUCKETS);
+        return by ? { fn: 'bucket', of, by } : null;
+    }
+    const fn = oneOf(o.fn, EXPR_FNS);
+    if (!fn)
+        return null;
+    const over = typeof o.over === 'number' && Number.isFinite(o.over) ? o.over : fieldName(o.over);
+    return over === undefined ? null : { fn, of, over };
+}
+function parseAgg(o) {
+    if (!isObj(o))
+        return null;
+    const as = typeof o.as === 'string' && /^[A-Za-z_][A-Za-z0-9_]{0,39}$/.test(o.as) && !BAD_SEGMENT.test(o.as) ? o.as : undefined;
+    const fn = oneOf(o.fn, AGG_FNS);
+    if (!as || !fn)
+        return null;
+    const of = o.of === undefined ? undefined : fieldName(o.of);
+    if ((o.of !== undefined && !of) || (fn !== 'count' && !of))
+        return null;
+    const where = o.where === undefined ? undefined : parseConditions(o.where, 4);
+    if (o.where !== undefined && !where)
+        return null;
+    return clean({ as, fn, of, where: where ?? undefined });
+}
+function parseStep(o) {
+    if (!isObj(o))
+        return null;
+    switch (o.op) {
+        case 'filter': {
+            const where = parseConditions(o.where);
+            return where ? { op: 'filter', where } : null;
+        }
+        case 'derive': {
+            const as = typeof o.as === 'string' && /^[A-Za-z_][A-Za-z0-9_]{0,39}$/.test(o.as) && !BAD_SEGMENT.test(o.as) ? o.as : undefined;
+            const expr = parseExpr(o.expr);
+            return as && expr ? { op: 'derive', as, expr } : null;
+        }
+        case 'group': {
+            const by = Array.isArray(o.by) ? o.by.map(fieldName) : [];
+            if (!by.length || by.length > 3 || !by.every((b) => Boolean(b)))
+                return null;
+            if (!Array.isArray(o.agg) || !o.agg.length || o.agg.length > MAX_VIEW_AGGS)
+                return null;
+            const agg = o.agg.map(parseAgg);
+            if (!agg.every((a) => a !== null))
+                return null;
+            const names = [...by, ...agg.map((a) => a.as)];
+            if (new Set(names).size !== names.length)
+                return null;
+            const fill = o.fill === undefined ? undefined : oneOf(o.fill, ['hour_of_day', 'weekday']);
+            if (o.fill !== undefined && !fill)
+                return null;
+            return clean({ op: 'group', by, agg, fill });
+        }
+        case 'sort': {
+            const by = fieldName(o.by);
+            const dir = o.dir === undefined ? undefined : oneOf(o.dir, ['asc', 'desc']);
+            return by && (o.dir === undefined || dir) ? clean({ op: 'sort', by, dir }) : null;
+        }
+        case 'limit': {
+            const n = int(o.n, 1, 500);
+            return n ? { op: 'limit', n } : null;
+        }
+        case 'pick': {
+            if (!Array.isArray(o.fields) || !o.fields.length || o.fields.length > 12)
+                return null;
+            const fields = o.fields.map(fieldName);
+            return fields.every((f) => Boolean(f)) ? { op: 'pick', fields } : null;
+        }
+        default:
+            return null;
+    }
+}
+function parseDatasets(raw, ctx) {
+    if (raw === undefined)
+        return undefined;
+    if (!isObj(raw)) {
+        note(ctx, 'datasets is not an object');
+        return undefined;
+    }
+    const out = {};
+    for (const [name, d] of Object.entries(raw).slice(0, MAX_VIEW_DATASETS)) {
+        const bad = (why) => note(ctx, `dataset ${name} dropped: ${why}`);
+        if (!DATASET_NAME.test(name) || RESULT_ID.test(name) || RESERVED_NAMES.has(name)) {
+            bad('a dataset name starts with a lowercase letter and is not like r1');
+            continue;
+        }
+        if (!isObj(d)) {
+            bad('it is not an object');
+            continue;
+        }
+        // Each dataset reads a tool result or an earlier dataset, so a loop is not possible.
+        const from = typeof d.from === 'string' ? d.from : '';
+        const fromResult = RESULT_ID.test(from);
+        if (!fromResult && !Object.hasOwn(out, from)) {
+            bad(`from "${from.slice(0, 24)}" is not a result id or an earlier dataset`);
+            continue;
+        }
+        if (fromResult && ctx.bound && !ctx.sources.has(from)) {
+            bad(`no rows of ${from} came with the view`);
+            continue;
+        }
+        const stepsRaw = d.steps === undefined ? [] : d.steps;
+        if (!Array.isArray(stepsRaw) || stepsRaw.length > MAX_VIEW_STEPS) {
+            bad(`steps must be a list of at most ${MAX_VIEW_STEPS}`);
+            continue;
+        }
+        const steps = stepsRaw.map(parseStep);
+        const badAt = steps.findIndex((s) => s === null);
+        // A step that fails the check drops the dataset: a pipeline with a skipped step would show wrong numbers.
+        if (badAt >= 0) {
+            bad(`step ${badAt + 1} is not valid`);
+            continue;
+        }
+        out[name] = { from, ...(steps.length ? { steps: steps } : {}) };
+        ctx.datasets.add(name);
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+function parseVars(raw, ctx) {
+    if (raw === undefined)
+        return undefined;
+    if (!isObj(raw)) {
+        note(ctx, 'vars is not an object');
+        return undefined;
+    }
+    const out = {};
+    for (const [name, v] of Object.entries(raw).slice(0, MAX_VIEW_VARS)) {
+        const bad = (why) => note(ctx, `var ${name} dropped: ${why}`);
+        if (!DATASET_NAME.test(name) || RESERVED_NAMES.has(name)) {
+            bad('a var name starts with a lowercase letter');
+            continue;
+        }
+        if (!isObj(v)) {
+            bad('it is not an object');
+            continue;
+        }
+        const of = typeof v.of === 'string' ? v.of : '';
+        const fn = oneOf(v.fn, SCALAR_FNS);
+        const field = v.field === undefined ? undefined : fieldName(v.field);
+        const format = v.format === undefined ? undefined : oneOf(v.format, VIEW_FORMATS);
+        const row = v.row === undefined ? undefined : int(v.row, 0, 499);
+        if (!ctx.datasets.has(of))
+            bad(`dataset "${of.slice(0, 24)}" is not defined`);
+        else if (!fn)
+            bad('fn is not one of count, sum, avg, min, max, cell');
+        else if ((fn !== 'count' && !field) || (v.field !== undefined && !field))
+            bad('field is missing or not a field name');
+        else if ((v.format !== undefined && !format) || (v.row !== undefined && row === undefined))
+            bad('format or row is not valid');
+        else {
+            out[name] = clean({ of, fn, field, row, format });
+            ctx.vars.add(name);
+        }
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+// ---------- Nodes ----------
+const ALLOWED_KEYS = (type, ctx) => new Set(['type', ...Object.keys(VIEW_COMPONENTS[type].props), ...(ctx.bound && isBlockNode(type) ? ['block'] : [])]);
+const isBlockNode = (type) => VIEW_RECORD_TYPES.includes(type) || ['triage', 'table', 'stats', 'chart'].includes(type);
+/** Notes every prop of a node that the registry does not know, so the model hears what was dropped. */
+function noteUnknown(o, type, path, ctx) {
+    const allowed = ALLOWED_KEYS(type, ctx);
+    for (const k of Object.keys(o))
+        if (!allowed.has(k))
+            note(ctx, `${path}: ${k} is not a prop of ${type}, dropped`);
+}
+function parseChildren(raw, depth, path, ctx) {
+    if (!Array.isArray(raw))
+        return [];
+    if (raw.length > MAX_VIEW_CHILDREN)
+        note(ctx, `${path} holds at most ${MAX_VIEW_CHILDREN} children, the rest are dropped`);
+    const out = [];
+    raw.slice(0, MAX_VIEW_CHILDREN).forEach((c, i) => {
+        const n = parseNode(c, depth, `${path}[${i}]`, ctx);
+        if (n)
+            out.push(n);
+    });
+    return out;
+}
+function tiles(raw, path, ctx) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const [i, t] of raw.slice(0, MAX_VIEW_TILES).entries()) {
+        if (!isObj(t))
+            continue;
+        const label = text(ctx, `${path}.tiles[${i}].label`, t.label, CAP.label);
+        const value = text(ctx, `${path}.tiles[${i}].value`, typeof t.value === 'number' && Number.isFinite(t.value) ? String(t.value) : t.value, CAP.tileValue, {
+            figures: false,
+        });
+        if (!label || !value) {
+            note(ctx, `${path}.tiles[${i}] needs a label and a value`);
+            continue;
+        }
+        // A tile shows a number the view computed. A value with no {name} in it is something the model wrote, so the tile goes.
+        if (!placeholdersIn(value).length) {
+            note(ctx, `${path}.tiles[${i}].value must be a {name} from vars: a tile never shows a figure the model wrote`);
+            continue;
+        }
+        out.push(clean({ label, value, sub: text(ctx, `${path}.tiles[${i}].sub`, t.sub, CAP.tileSub, { figures: false }), tone: oneOf(t.tone, TONES) }));
+    }
+    if (raw.length > MAX_VIEW_TILES)
+        note(ctx, `${path}.tiles holds at most ${MAX_VIEW_TILES} tiles`);
+    return out;
+}
+function columns(raw, path, ctx) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = [];
+    for (const [i, c] of raw.slice(0, MAX_VIEW_COLUMNS).entries()) {
+        const field = isObj(c) ? fieldName(c.field) : undefined;
+        if (!isObj(c) || !field) {
+            note(ctx, `${path}.columns[${i}] needs a field`);
+            continue;
+        }
+        out.push(clean({ field, label: text(ctx, `${path}.columns[${i}].label`, c.label, CAP.label), format: oneOf(c.format, VIEW_FORMATS) }));
+    }
+    return out.length ? out : undefined;
+}
+function series(raw, path, ctx) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const [i, s] of raw.slice(0, MAX_VIEW_SERIES).entries()) {
+        const field = isObj(s) ? fieldName(s.field) : undefined;
+        if (!isObj(s) || !field) {
+            note(ctx, `${path}.series[${i}] needs a field`);
+            continue;
+        }
+        out.push(clean({ field, name: text(ctx, `${path}.series[${i}].name`, s.name, CAP.label) }));
+    }
+    return out;
+}
+/** In a bound view a block node carries the block the server built; it must be a valid block of the node's kind. */
+function boundBlock(o, kind, path, ctx) {
+    const b = ctx.parseBlock?.(o.block) ?? null;
+    if (!b || b.kind !== kind) {
+        note(ctx, `${path}: the ${kind} block is missing or not valid`);
+        return null;
+    }
+    return b;
+}
+function resultRef(ctx, path, v) {
+    if (v === undefined)
+        return undefined;
+    if (!isResultId(v)) {
+        note(ctx, `${path}.from must be a result id such as r1`);
+        return undefined;
+    }
+    return v;
+}
+function datasetRef(ctx, path, v) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'string' || !ctx.datasets.has(v)) {
+        note(ctx, `${path}.data names "${String(v).slice(0, 24)}", which is not a dataset of this view`);
+        return undefined;
+    }
+    return v;
+}
+function parseNode(raw, depth, path, ctx) {
+    if (!isObj(raw)) {
+        note(ctx, `${path} is not an object`);
+        return null;
+    }
+    const type = oneOf(raw.type, VIEW_NODE_TYPES);
+    if (!type) {
+        note(ctx, `${path}: "${String(raw.type ?? '').slice(0, 24)}" is not a component, dropped`);
+        return null;
+    }
+    if (depth > MAX_VIEW_DEPTH) {
+        note(ctx, `${path} is nested deeper than ${MAX_VIEW_DEPTH} levels, dropped`);
+        return null;
+    }
+    if (ctx.nodes >= MAX_VIEW_NODES) {
+        if (!ctx.nodeLimitNoted)
+            note(ctx, `a view holds at most ${MAX_VIEW_NODES} nodes, the rest are dropped`);
+        ctx.nodeLimitNoted = true;
+        return null;
+    }
+    ctx.nodes++;
+    noteUnknown(raw, type, path, ctx);
+    switch (type) {
+        case 'column':
+        case 'row': {
+            const children = parseChildren(raw.children, depth + 1, `${path}.children`, ctx);
+            return children.length || ctx.bound ? { type, children } : (note(ctx, `${path}: a ${type} with no valid child is dropped`), null);
+        }
+        case 'section': {
+            const t = text(ctx, `${path}.title`, raw.title, CAP.title);
+            const children = parseChildren(raw.children, depth + 1, `${path}.children`, ctx);
+            if (!t || !children.length)
+                return (note(ctx, `${path}: a section needs a title and a valid child`), null);
+            return { type, title: t, children };
+        }
+        case 'tabs': {
+            const out = [];
+            const list = Array.isArray(raw.tabs) ? raw.tabs : [];
+            if (list.length > MAX_VIEW_TABS)
+                note(ctx, `${path}.tabs holds at most ${MAX_VIEW_TABS} tabs`);
+            for (const [i, t] of list.slice(0, MAX_VIEW_TABS).entries()) {
+                const label = isObj(t) ? text(ctx, `${path}.tabs[${i}].label`, t.label, CAP.label) : undefined;
+                const children = isObj(t) ? parseChildren(t.children, depth + 1, `${path}.tabs[${i}].children`, ctx) : [];
+                if (label && children.length)
+                    out.push({ label, children });
+                else
+                    note(ctx, `${path}.tabs[${i}] needs a label and a valid child`);
+            }
+            return out.length ? { type, tabs: out } : (note(ctx, `${path}: tabs with no valid tab is dropped`), null);
+        }
+        case 'text': {
+            const t = text(ctx, `${path}.text`, raw.text, CAP.text, { figures: false });
+            if (!t)
+                return null;
+            const href = raw.href === undefined ? undefined : safeHttpUrl(raw.href);
+            if (raw.href !== undefined && !href)
+                note(ctx, `${path}.href is not an http or https link, dropped`);
+            return clean({ type, text: t, tone: oneOf(raw.tone, ['muted']), href });
+        }
+        case 'triage': {
+            const block = ctx.bound ? boundBlock(raw, 'triage', path, ctx) : undefined;
+            if (ctx.bound && !block)
+                return null;
+            return clean({ type, window: oneOf(raw.window, TRIAGE_WINDOWS), title: text(ctx, `${path}.title`, raw.title, CAP.title), block: block ?? undefined });
+        }
+        case 'table': {
+            const from = resultRef(ctx, path, raw.from);
+            const data = datasetRef(ctx, path, raw.data);
+            if ((from === undefined) === (data === undefined))
+                return (note(ctx, `${path}: a table reads one of data or from`), null);
+            const block = ctx.bound && from ? boundBlock(raw, 'table', path, ctx) : undefined;
+            if (ctx.bound && from && !block)
+                return null;
+            return clean({
+                type,
+                title: text(ctx, `${path}.title`, raw.title, CAP.title),
+                data,
+                from,
+                columns: data ? columns(raw.columns, path, ctx) : undefined,
+                limit: int(raw.limit, 1, 50),
+                block: block ?? undefined,
+            });
+        }
+        case 'stats': {
+            const from = resultRef(ctx, path, raw.from);
+            const list = from ? [] : tiles(raw.tiles, path, ctx);
+            if (!from && !list.length)
+                return (note(ctx, `${path}: stats needs tiles or a from`), null);
+            const block = ctx.bound && from ? boundBlock(raw, 'stats', path, ctx) : undefined;
+            if (ctx.bound && from && !block)
+                return null;
+            return clean({ type, title: text(ctx, `${path}.title`, raw.title, CAP.title), from, tiles: list.length ? list : undefined, block: block ?? undefined });
+        }
+        case 'chart': {
+            const from = resultRef(ctx, path, raw.from);
+            const title = text(ctx, `${path}.title`, raw.title, CAP.title);
+            if (from) {
+                const block = ctx.bound ? boundBlock(raw, 'chart', path, ctx) : undefined;
+                if (ctx.bound && !block)
+                    return null;
+                return clean({ type, title, from, block: block ?? undefined });
+            }
+            const data = datasetRef(ctx, path, raw.data);
+            const chartType = oneOf(raw.chartType, CHART_TYPES);
+            const x = fieldName(raw.x);
+            const list = series(raw.series, path, ctx);
+            if (!data || !chartType || !x || !list.length)
+                return (note(ctx, `${path}: a chart needs data, chartType, x, and series, or a from`), null);
+            return clean({
+                type,
+                title,
+                data,
+                chartType,
+                x,
+                xFormat: oneOf(raw.xFormat, VIEW_FORMATS),
+                series: list,
+                unit: text(ctx, `${path}.unit`, raw.unit, CAP.unit),
+                finding: text(ctx, `${path}.finding`, typeof raw.finding === 'string' ? raw.finding.replace(/\s+/g, ' ') : raw.finding, CAP.finding, {
+                    figures: false,
+                }),
+                limit: int(raw.limit, 1, 31),
+            });
+        }
+        default: {
+            // The record blocks: the server builds the block from the result named by `from`.
+            const from = resultRef(ctx, path, raw.from);
+            if (!from)
+                return (note(ctx, `${path}: ${type} needs a from, the id of a tool result`), null);
+            const block = ctx.bound ? boundBlock(raw, type, path, ctx) : undefined;
+            if (ctx.bound && !block)
+                return null;
+            return clean({
+                type: type,
+                from,
+                nth: int(raw.nth, 0, 9),
+                title: text(ctx, `${path}.title`, raw.title, CAP.title),
+                limit: int(raw.limit, 1, 50),
+                block: block ?? undefined,
+            });
+        }
+    }
+}
+// ---------- Sources (set by the server) ----------
+function cellOf(v) {
+    if (typeof v === 'string')
+        return v.length > CAP.cell ? `${v.slice(0, CAP.cell - 1)}…` : v;
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? v : null;
+    return typeof v === 'boolean' ? v : null;
+}
+function parseSources(raw, ctx) {
+    if (!isObj(raw))
+        return undefined;
+    const out = {};
+    let cells = 0;
+    for (const [id, t] of Object.entries(raw)) {
+        if (!RESULT_ID.test(id) || !isObj(t) || !Array.isArray(t.columns) || !Array.isArray(t.rows))
+            continue;
+        const cols = t.columns.map((c) => fieldName(c));
+        if (!cols.length || cols.length > MAX_SOURCE_COLUMNS || !cols.every((c) => Boolean(c)))
+            continue;
+        const rows = [];
+        for (const r of t.rows.slice(0, MAX_SOURCE_ROWS)) {
+            if (!Array.isArray(r) || cells + cols.length > MAX_SOURCE_CELLS)
+                break;
+            rows.push(cols.map((_, i) => cellOf(r[i])));
+            cells += cols.length;
+        }
+        if (rows.length < t.rows.length)
+            note(ctx, `${id}: only ${rows.length} of ${t.rows.length} rows came with the view`);
+        const more = int(t.more, 1, 1_000_000_000);
+        out[id] = { columns: cols, rows, ...(more ? { more } : {}) };
+        ctx.sources.add(id);
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/** Checks a whole view. Invalid nodes, props, and datasets are dropped and noted; a view with no valid node is refused. */
+export function parseViewTree(raw, opts = {}) {
+    const ctx = {
+        bound: opts.bound === true,
+        notes: [],
+        nodes: 0,
+        nodeLimitNoted: false,
+        datasets: new Set(),
+        vars: new Set(),
+        sources: new Set(),
+        ...(opts.parseBlock ? { parseBlock: opts.parseBlock } : {}),
+    };
+    if (!isObj(raw))
+        return { ok: false, reason: 'the view is not an object', notes: ctx.notes };
+    if (raw.root === undefined)
+        return { ok: false, reason: 'the view has no root', notes: ctx.notes };
+    const known = new Set(['v', 'title', 'datasets', 'vars', 'root', ...(ctx.bound ? ['sources', 'total', 'tzOffsetMin'] : [])]);
+    for (const k of Object.keys(raw))
+        if (!known.has(k))
+            note(ctx, `${k} is not a prop of a view, dropped`);
+    const sources = ctx.bound ? parseSources(raw.sources, ctx) : undefined;
+    const datasets = parseDatasets(raw.datasets, ctx);
+    // Vars read datasets, and a text may name a var, so the vars come before the nodes.
+    const vars = parseVars(raw.vars, ctx);
+    const node = parseNode(raw.root, 1, 'root', ctx);
+    if (!node)
+        return { ok: false, reason: 'the view has no valid node', notes: ctx.notes };
+    const root = { type: 'column', children: node.type === 'column' ? node.children : [node] };
+    const total = ctx.bound ? int(raw.total, 0, MAX_VIEW_CHILDREN) : undefined;
+    const tz = ctx.bound ? int(raw.tzOffsetMin, -840, 840) : undefined;
+    const view = clean({
+        v: 1,
+        title: text(ctx, 'title', raw.title, CAP.title),
+        sources,
+        datasets,
+        vars,
+        tzOffsetMin: tz,
+        root,
+        total,
+    });
+    return { ok: true, view, notes: ctx.notes, nodes: ctx.nodes };
+}
+/**
+ * The title, datasets, and vars of a view on their own. The server reads them while the model is still writing the nodes, so it can
+ * send the shell of the view and then each node as it closes. The same checks as parseViewTree, so a head that passes here passes there.
+ */
+export function parseViewHead(raw) {
+    const ctx = { bound: false, notes: [], nodes: 0, nodeLimitNoted: false, datasets: new Set(), vars: new Set(), sources: new Set() };
+    const o = isObj(raw) ? raw : {};
+    const datasets = parseDatasets(o.datasets, ctx);
+    const vars = parseVars(o.vars, ctx);
+    return clean({ title: text(ctx, 'title', o.title, CAP.title), datasets, vars, notes: ctx.notes });
+}
+/** One node on its own, for a streamed `view_node` event. The datasets and vars of the view it joins say which names are known. */
+export function parseViewNode(raw, view, opts = {}) {
+    const ctx = {
+        bound: opts.bound === true,
+        notes: [],
+        nodes: 0,
+        nodeLimitNoted: false,
+        datasets: new Set(Object.keys(view.datasets ?? {})),
+        vars: new Set(Object.keys(view.vars ?? {})),
+        sources: new Set(),
+        ...(opts.parseBlock ? { parseBlock: opts.parseBlock } : {}),
+    };
+    // A node of the root is at depth 2: the root column is depth 1.
+    return parseNode(raw, 2, 'node', ctx);
+}
+// ---------- Fallback, and walking a view ----------
+/**
+ * Every object in a raw tree that looks like a node (it has a string `type`), in document order. Used when a spec fails the
+ * check: the blocks inside it still show (docs/CHAT-UI.md, Composed views: Fallback). A spec fails often because it nests too deep,
+ * so this reads deeper than the check allows: 16 levels of objects, and 80 nodes.
+ */
+export function rawNodes(raw, max = 80) {
+    const out = [];
+    const walk = (v, depth) => {
+        if (out.length >= max || depth > 16)
+            return;
+        if (Array.isArray(v)) {
+            // A list is not a level: the nodes in it sit at the depth of the object that holds the list.
+            for (const x of v)
+                walk(x, depth);
+            return;
+        }
+        if (!isObj(v))
+            return;
+        if (typeof v.type === 'string')
+            out.push(v);
+        for (const k of ['root', 'children', 'tabs'])
+            if (k in v)
+                walk(v[k], depth + 1);
+    };
+    walk(raw, 0);
+    return out;
+}
+/** The nodes of a view in document order, nested ones included. */
+export function viewNodes(node) {
+    const out = [node];
+    if ('children' in node)
+        for (const c of node.children)
+            out.push(...viewNodes(c));
+    if (node.type === 'tabs')
+        for (const t of node.tabs)
+            for (const c of t.children)
+                out.push(...viewNodes(c));
+    return out;
+}
+/** The blocks a bound view embeds. */
+export function viewBlocks(view) {
+    const out = [];
+    for (const n of viewNodes(view.root))
+        if ('block' in n && n.block)
+            out.push(n.block);
+    return out;
+}
+/** What a view is built of, for the chat eval and for logs: the kinds of its nodes, in document order. */
+export function viewKinds(view) {
+    return viewNodes(view.root)
+        .map((n) => n.type)
+        .filter((t) => t !== 'column');
+}
+/** The fields a view's datasets, vars, and nodes name, so the server can send only those columns of a result. */
+export function fieldsUsed(spec) {
+    const out = new Set();
+    const cond = (c) => out.add(c.field);
+    for (const d of Object.values(spec.datasets ?? {})) {
+        for (const s of d.steps ?? []) {
+            if (s.op === 'filter')
+                s.where.forEach(cond);
+            else if (s.op === 'derive') {
+                out.add(s.expr.of);
+                if (s.expr.fn !== 'bucket' && typeof s.expr.over === 'string')
+                    out.add(s.expr.over);
+            }
+            else if (s.op === 'group') {
+                s.by.forEach((b) => out.add(b));
+                for (const a of s.agg) {
+                    if (a.of)
+                        out.add(a.of);
+                    a.where?.forEach(cond);
+                }
+            }
+            else if (s.op === 'sort')
+                out.add(s.by);
+            else if (s.op === 'pick')
+                s.fields.forEach((f) => out.add(f));
+        }
+    }
+    for (const v of Object.values(spec.vars ?? {}))
+        if (v.field)
+            out.add(v.field);
+    if (spec.root)
+        for (const n of viewNodes(spec.root)) {
+            if (n.type === 'chart') {
+                if (n.x)
+                    out.add(n.x);
+                n.series?.forEach((s) => out.add(s.field));
+            }
+            if (n.type === 'table')
+                n.columns?.forEach((c) => out.add(c.field));
+        }
+    return out;
+}
+// ---------- What the model is told ----------
+const EXAMPLE = {
+    title: 'Flaky tests by hour of day',
+    datasets: {
+        byHour: {
+            from: 'r2',
+            steps: [
+                { op: 'derive', as: 'hour', expr: { fn: 'bucket', of: 'at', by: 'hour_of_day' } },
+                { op: 'group', by: ['hour'], agg: [{ as: 'flaky', fn: 'count' }], fill: 'hour_of_day' },
+            ],
+        },
+        peak: { from: 'byHour', steps: [{ op: 'sort', by: 'flaky', dir: 'desc' }] },
+    },
+    vars: { peakHour: { of: 'peak', fn: 'cell', field: 'hour', row: 0, format: 'hour' }, peakCount: { of: 'peak', fn: 'cell', field: 'flaky', row: 0 } },
+    root: {
+        type: 'column',
+        children: [
+            { type: 'stats', tiles: [{ label: 'Busiest hour', value: '{peakHour}', sub: '{peakCount} flaky results', tone: 'attention' }] },
+            {
+                type: 'chart',
+                data: 'byHour',
+                chartType: 'bar',
+                x: 'hour',
+                xFormat: 'hour',
+                series: [{ field: 'flaky', name: 'Flaky results' }],
+                finding: 'Flaky results cluster at **{peakHour}**.',
+            },
+        ],
+    },
+};
+/** The description of compose_view: the format in the words the model needs, one registry entry per component. */
+export function viewSpecGuide() {
+    const props = (type) => Object.entries(VIEW_COMPONENTS[type].props)
+        .map(([k, p]) => `${k}${p.required ? '' : '?'}`)
+        .join(', ');
+    const kinds = (types) => types.map((t) => `${t} {${props(t)}}`).join('; ');
+    return [
+        'Compose one view that arranges several blocks, or numbers a lookup does not give, from our own components. Use it only when no single block answers the question; a question one tool answers gets that tool and no view.',
+        'The input is JSON: { title?, datasets?, vars?, root }. root is a column of nodes, nested at most 4 levels, at most 40 nodes. There is no HTML, CSS, color, or action: buttons come from the blocks, and only the actions those blocks already have exist.',
+        'Data comes only from tool results of this turn. Each lookup result carries a resultId such as "r1". Filter in the tool call (days, branch, status), never in the view; the view arranges and computes over what came back. Set context to true on a list lookup whose rows you only arrange here, so it does not also show alone.',
+        `Layout and text: ${kinds(['column', 'row', 'section', 'tabs', 'text'])}. A tab is { label, children }.`,
+        `Blocks localdost builds from a result id: ${kinds(VIEW_RECORD_TYPES)}; ${kinds(['triage'])}. A result with no row for that block gives no block.`,
+        `Blocks built from your data: ${kinds(['stats', 'chart', 'table'])}. stats, chart, and table also take from: "<resultId>" for a result that is already tiles, a chart, or a table (pass_rate, flaky_by_spec). A tile is { label, value, sub?, tone? ok|attention|bad }, a column is { field, label?, format? }, a series is { field, name? }, chartType is bar, stacked_bar, or line.`,
+        'datasets: { name: { from: "<resultId>" or an earlier dataset, steps: [...] } }. Steps run in order:',
+        '{op:"filter", where:[{field, is: eq|ne|gt|gte|lt|lte|in|contains, value}]}; {op:"derive", as, expr:{fn:"bucket", of, by: hour|hour_of_day|day|weekday|week|month} or {fn: ratio|percent|change|diff, of, over}} (over is a field or a number; percent is of/over*100, change is (of/over-1)*100); {op:"group", by:[fields], agg:[{as, fn: count|sum|avg|min|max|distinct, of?, where?}], fill?: hour_of_day|weekday}; {op:"sort", by, dir?: asc|desc}; {op:"limit", n}; {op:"pick", fields}.',
+        'vars: { name: { of: dataset, fn: count|sum|avg|min|max|cell, field?, row?, format? } }. {name} in a text, a tile value or sub, or a finding takes the value. formats: text, number, percent, duration (ms), hour, weekday, day, spec (a test file path without .spec.ts).',
+        'Never type a number. Every figure on screen comes from a tool result through vars: a tile value is always a {name}, and a text, a tile sub, or a finding that holds a number you typed is dropped. A look-back window such as "the last 7 days" may be typed, and so may a title or a label.',
+        'A result that says `more` holds only part of the data: the view computes over the rows it has and shows a notice. Narrow the filter in the tool call (fewer days, one branch, one spec) so the view counts everything, or say in your sentence that the numbers cover part of the data.',
+        'A step or a field that is not valid drops the whole dataset and every node that reads it, and the answer says what was dropped. Write one or two sentences of judgement after the view, and do not repeat its numbers.',
+        `Example: ${JSON.stringify(EXAMPLE)}`,
+    ].join('\n');
+}
+//# sourceMappingURL=view-spec.js.map