summer-engine 3.1.0 → 3.2.0

package/dist/core/capabilities/audit/math.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Pure math behind summer_scene_audit: everything the judgment side needs
+ * that is worth testing without an engine. The in-engine kernel
+ * (assets/audit/scene_audit.gd) only measures; these functions decide.
+ *
+ * Conventions match the engine: +Y up, a basis is three COLUMN vectors
+ * (x, y, z), a transform maps local to world as origin + basis * v.
+ */
+import { type Vec3 } from "../seeing/math.js";
+export type { Vec3 };
+/** Basis as the kernel writes it: [x.x, x.y, x.z, y.x, y.y, y.z, z.x, z.y, z.z]. */
+export type Basis9 = readonly number[];
+export declare function basisColumns(b: Basis9): [Vec3, Vec3, Vec3];
+/** Rotation angle (degrees) between two bases, scale removed. */
+export declare function basisAngleDegrees(a: Basis9, b: Basis9): number;
+/** Horizontal direction along a wall whose (horizontal) normal is n. */
+export declare function wallDirection(normal: Vec3): Vec3;
+/** Angle in [0, 90] degrees between an axis and a line (sign-free). */
+export declare function lineAngleDegrees(axis: Vec3, line: Vec3): number;
+/** Camera defaults when the scene has no perspective camera (Godot's Camera3D). */
+export declare const DEFAULT_NEAR = 0.05;
+export declare const DEFAULT_FAR = 4000;
+/** Compatibility / WebGL2 depth buffer. */
+export declare const DEPTH_BITS = 24;
+/** The distance a surface is judged at when no viewpoint is known. */
+export declare const TYPICAL_VIEW_M = 30;
+/** Float noise in world transforms: never call a smaller gap resolvable. */
+export declare const MIN_ZFIGHT_TOLERANCE = 0.0001;
+/**
+ * World distance one depth-buffer step spans at `distance` from a perspective
+ * camera: z^2 (f - n) / (f n 2^bits). It grows with the square of the
+ * distance and shrinks with a larger near plane.
+ */
+export declare function depthResolution(distance: number, near?: number, far?: number, bits?: number): number;
+/** Two faces closer than this flicker: twice the depth step at `distance`. */
+export declare function zFightTolerance(distance: number, near?: number, far?: number, factor?: number, bits?: number): number;
+export type Vec2 = readonly [number, number];
+/**
+ * Ratio of the two singular values of the 3x2 Jacobian d(world)/d(uv): how
+ * much more world distance one UV direction covers than the other. 1 = square
+ * texels, 8 = a texel stretched 8:1. Collapsed UVs (zero UV area) are
+ * Infinity: the texture is smeared into a strip.
+ */
+export declare function uvStretchRatio(p0: Vec3, p1: Vec3, p2: Vec3, t0: Vec2, t1: Vec2, t2: Vec2): number;
+export declare function triangleArea(p0: Vec3, p1: Vec3, p2: Vec3): number;
+export interface Sample2 {
+    u: number;
+    v: number;
+}
+/**
+ * Connected groups of samples: two samples are neighbours when both
+ * coordinates differ by at most `reach` (1.5 x the grid spacing joins the
+ * 8-neighbourhood and off-grid seam samples). Returns groups of indices,
+ * largest first. Uses a bucket grid, so it is linear in practice.
+ */
+export declare function clusterSamples(samples: readonly Sample2[], reach: number): number[][];
+/** One down-ray sample and the ground it stands for: a grid cell, 10 cm of a
+ *  seam across its width, or one step of a strip along a wall base. */
+export interface Footprint {
+    x: number;
+    z: number;
+    sx: number;
+    sz: number;
+    area: number;
+}
+export interface FootprintExtent {
+    x0: number;
+    x1: number;
+    z0: number;
+    z1: number;
+    w: number;
+    d: number;
+    /** The longer and the shorter side (a seam is 8.4 x 0.04 m). */
+    long: number;
+    short: number;
+    area: number;
+}
+/**
+ * Bounds and area of a cluster of missed rays. The area is the sum of the
+ * samples' own footprints, never more than their bounding box: a 4 cm seam
+ * walked by 84 rays is 0.34 m2, not 84 grid cells.
+ */
+export declare function footprintExtent(cells: readonly Footprint[]): FootprintExtent;
+/** The most frequent value (ties: the first seen); `fallback` when empty. */
+export declare function mostCommon(values: readonly number[], fallback?: number): number;
+export declare function median(values: readonly number[]): number;
+export declare function percentile(values: readonly number[], p: number): number;
+/** Median centre and the distance beyond which a piece is "far out". */
+export declare function robustBounds(points: readonly Vec3[]): {
+    center: Vec3;
+    radius: number;
+    limit: number;
+};
+/** Distance along `dir` (unit) from `p` to the point where it would be seen. */
+export declare function fitCameraDistance(size: number, fovDegrees: number, fill?: number): number;
+/** World axis label of a vector's dominant component ("+X", "-Y", ...). */
+export declare function axisName(v: Vec3): string;
+/** The local axis of a piece (basis columns) that a world direction runs along. */
+export declare function localAxisName(b: readonly number[], v: Vec3): string;
+export interface Box {
+    lo: Vec3;
+    hi: Vec3;
+}
+export declare function makeBox(a: Vec3, b: Vec3): Box;
+export declare function growBox(b: Box, g: number): Box;
+export declare function boxCenter(b: Box): Vec3;
+/** Overlap of two boxes, or null when they do not overlap (touching counts). */
+export declare function boxIntersection(a: Box, b: Box): Box | null;
+/** Shortest distance between two boxes (0 when they touch or overlap). */
+export declare function boxDistance(a: Box, b: Box): number;

package/dist/core/capabilities/audit/math.js

@@ -0,0 +1,263 @@
+/**
+ * Pure math behind summer_scene_audit: everything the judgment side needs
+ * that is worth testing without an engine. The in-engine kernel
+ * (assets/audit/scene_audit.gd) only measures; these functions decide.
+ *
+ * Conventions match the engine: +Y up, a basis is three COLUMN vectors
+ * (x, y, z), a transform maps local to world as origin + basis * v.
+ */
+import { dot, length, normalize, scale, sub } from "../seeing/math.js";
+export function basisColumns(b) {
+    return [
+        [b[0], b[1], b[2]],
+        [b[3], b[4], b[5]],
+        [b[6], b[7], b[8]],
+    ];
+}
+/** Rotation angle (degrees) between two bases, scale removed. */
+export function basisAngleDegrees(a, b) {
+    const ca = basisColumns(a).map((c) => normalize(c));
+    const cb = basisColumns(b).map((c) => normalize(c));
+    // trace(A^T B) = sum of column dot products for orthonormal bases.
+    const trace = dot(ca[0], cb[0]) + dot(ca[1], cb[1]) + dot(ca[2], cb[2]);
+    const c = Math.min(1, Math.max(-1, (trace - 1) / 2));
+    return (Math.acos(c) * 180) / Math.PI;
+}
+// ---------------------------------------------------------------------------
+// orientation: parallelism of a long axis to a wall
+// ---------------------------------------------------------------------------
+/** Horizontal direction along a wall whose (horizontal) normal is n. */
+export function wallDirection(normal) {
+    return normalize([-normal[2], 0, normal[0]]);
+}
+/** Angle in [0, 90] degrees between an axis and a line (sign-free). */
+export function lineAngleDegrees(axis, line) {
+    const a = normalize([axis[0], 0, axis[2]]);
+    const l = normalize([line[0], 0, line[2]]);
+    const c = Math.min(1, Math.abs(dot(a, l)));
+    return (Math.acos(c) * 180) / Math.PI;
+}
+// ---------------------------------------------------------------------------
+// z_fight: depth precision decides how close is "coplanar"
+// ---------------------------------------------------------------------------
+/** Camera defaults when the scene has no perspective camera (Godot's Camera3D). */
+export const DEFAULT_NEAR = 0.05;
+export const DEFAULT_FAR = 4000;
+/** Compatibility / WebGL2 depth buffer. */
+export const DEPTH_BITS = 24;
+/** The distance a surface is judged at when no viewpoint is known. */
+export const TYPICAL_VIEW_M = 30;
+/** Float noise in world transforms: never call a smaller gap resolvable. */
+export const MIN_ZFIGHT_TOLERANCE = 0.0001;
+/**
+ * World distance one depth-buffer step spans at `distance` from a perspective
+ * camera: z^2 (f - n) / (f n 2^bits). It grows with the square of the
+ * distance and shrinks with a larger near plane.
+ */
+export function depthResolution(distance, near = DEFAULT_NEAR, far = DEFAULT_FAR, bits = DEPTH_BITS) {
+    const n = Math.max(1e-4, near);
+    const f = Math.max(n * 1.0001, far);
+    return (distance * distance * (f - n)) / (f * n * 2 ** bits);
+}
+/** Two faces closer than this flicker: twice the depth step at `distance`. */
+export function zFightTolerance(distance, near = DEFAULT_NEAR, far = DEFAULT_FAR, factor = 2, bits = DEPTH_BITS) {
+    return Math.max(MIN_ZFIGHT_TOLERANCE, factor * depthResolution(distance, near, far, bits));
+}
+/**
+ * Ratio of the two singular values of the 3x2 Jacobian d(world)/d(uv): how
+ * much more world distance one UV direction covers than the other. 1 = square
+ * texels, 8 = a texel stretched 8:1. Collapsed UVs (zero UV area) are
+ * Infinity: the texture is smeared into a strip.
+ */
+export function uvStretchRatio(p0, p1, p2, t0, t1, t2) {
+    const e1 = sub(p1, p0);
+    const e2 = sub(p2, p0);
+    const u1 = [t1[0] - t0[0], t1[1] - t0[1]];
+    const u2 = [t2[0] - t0[0], t2[1] - t0[1]];
+    const det = u1[0] * u2[1] - u2[0] * u1[1];
+    if (Math.abs(det) < 1e-12)
+        return Number.POSITIVE_INFINITY;
+    const inv = 1 / det;
+    const du = scale(sub(scale(e1, u2[1]), scale(e2, u1[1])), inv);
+    const dv = scale(sub(scale(e2, u1[0]), scale(e1, u2[0])), inv);
+    const aa = dot(du, du);
+    const bb = dot(dv, dv);
+    const ab = dot(du, dv);
+    const disc = Math.sqrt(Math.max(0, (aa - bb) * (aa - bb) + 4 * ab * ab));
+    const s1 = (aa + bb + disc) / 2;
+    const s2 = (aa + bb - disc) / 2;
+    if (s2 <= 1e-14)
+        return Number.POSITIVE_INFINITY;
+    return Math.sqrt(s1 / s2);
+}
+export function triangleArea(p0, p1, p2) {
+    const e1 = sub(p1, p0);
+    const e2 = sub(p2, p0);
+    const c = [e1[1] * e2[2] - e1[2] * e2[1], e1[2] * e2[0] - e1[0] * e2[2], e1[0] * e2[1] - e1[1] * e2[0]];
+    return length(c) / 2;
+}
+/**
+ * Connected groups of samples: two samples are neighbours when both
+ * coordinates differ by at most `reach` (1.5 x the grid spacing joins the
+ * 8-neighbourhood and off-grid seam samples). Returns groups of indices,
+ * largest first. Uses a bucket grid, so it is linear in practice.
+ */
+export function clusterSamples(samples, reach) {
+    const parent = samples.map((_, i) => i);
+    const find = (i) => {
+        while (parent[i] !== i) {
+            parent[i] = parent[parent[i]];
+            i = parent[i];
+        }
+        return i;
+    };
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent[ra] = rb;
+    };
+    const cell = Math.max(reach, 1e-6);
+    const buckets = new Map();
+    const key = (i, j) => `${i},${j}`;
+    samples.forEach((s, idx) => {
+        const i = Math.floor(s.u / cell);
+        const j = Math.floor(s.v / cell);
+        for (let di = -1; di <= 1; di++) {
+            for (let dj = -1; dj <= 1; dj++) {
+                for (const other of buckets.get(key(i + di, j + dj)) ?? []) {
+                    const o = samples[other];
+                    if (Math.abs(o.u - s.u) <= reach + 1e-9 && Math.abs(o.v - s.v) <= reach + 1e-9)
+                        union(idx, other);
+                }
+            }
+        }
+        const k = key(i, j);
+        const list = buckets.get(k);
+        if (list)
+            list.push(idx);
+        else
+            buckets.set(k, [idx]);
+    });
+    const groups = new Map();
+    samples.forEach((_, i) => {
+        const r = find(i);
+        const g = groups.get(r);
+        if (g)
+            g.push(i);
+        else
+            groups.set(r, [i]);
+    });
+    return [...groups.values()].sort((a, b) => b.length - a.length || a[0] - b[0]);
+}
+/**
+ * Bounds and area of a cluster of missed rays. The area is the sum of the
+ * samples' own footprints, never more than their bounding box: a 4 cm seam
+ * walked by 84 rays is 0.34 m2, not 84 grid cells.
+ */
+export function footprintExtent(cells) {
+    if (!cells.length)
+        return { x0: 0, x1: 0, z0: 0, z1: 0, w: 0, d: 0, long: 0, short: 0, area: 0 };
+    let x0 = Infinity;
+    let x1 = -Infinity;
+    let z0 = Infinity;
+    let z1 = -Infinity;
+    let sum = 0;
+    for (const c of cells) {
+        x0 = Math.min(x0, c.x - c.sx / 2);
+        x1 = Math.max(x1, c.x + c.sx / 2);
+        z0 = Math.min(z0, c.z - c.sz / 2);
+        z1 = Math.max(z1, c.z + c.sz / 2);
+        sum += Math.max(0, c.area);
+    }
+    const w = x1 - x0;
+    const d = z1 - z0;
+    return { x0, x1, z0, z1, w, d, long: Math.max(w, d), short: Math.min(w, d), area: Math.min(sum, w * d) };
+}
+/** The most frequent value (ties: the first seen); `fallback` when empty. */
+export function mostCommon(values, fallback = -1) {
+    const counts = new Map();
+    for (const v of values)
+        counts.set(v, (counts.get(v) ?? 0) + 1);
+    let best = fallback;
+    let n = 0;
+    for (const [v, c] of counts) {
+        if (c > n) {
+            best = v;
+            n = c;
+        }
+    }
+    return best;
+}
+// ---------------------------------------------------------------------------
+// Robust bounds for "far out of bounds"
+// ---------------------------------------------------------------------------
+export function median(values) {
+    if (!values.length)
+        return 0;
+    const s = [...values].sort((a, b) => a - b);
+    const m = Math.floor(s.length / 2);
+    return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+}
+export function percentile(values, p) {
+    if (!values.length)
+        return 0;
+    const s = [...values].sort((a, b) => a - b);
+    const idx = Math.min(s.length - 1, Math.max(0, Math.ceil((p / 100) * s.length) - 1));
+    return s[idx];
+}
+/** Median centre and the distance beyond which a piece is "far out". */
+export function robustBounds(points) {
+    const center = [median(points.map((p) => p[0])), median(points.map((p) => p[1])), median(points.map((p) => p[2]))];
+    const radius = percentile(points.map((p) => length(sub(p, center))), 95);
+    return { center, radius, limit: Math.max(3 * radius, radius + 50) };
+}
+/** Distance along `dir` (unit) from `p` to the point where it would be seen. */
+export function fitCameraDistance(size, fovDegrees, fill = 0.55) {
+    const half = Math.tan((fovDegrees * Math.PI) / 360);
+    return size / (2 * half * fill);
+}
+// ---------------------------------------------------------------------------
+// Axis labels (z_fight: which way to nudge)
+// ---------------------------------------------------------------------------
+/** World axis label of a vector's dominant component ("+X", "-Y", ...). */
+export function axisName(v) {
+    const k = Math.abs(v[0]) >= Math.abs(v[1]) && Math.abs(v[0]) >= Math.abs(v[2]) ? 0 : Math.abs(v[1]) >= Math.abs(v[2]) ? 1 : 2;
+    return `${v[k] >= 0 ? "+" : "-"}${"XYZ"[k]}`;
+}
+/** The local axis of a piece (basis columns) that a world direction runs along. */
+export function localAxisName(b, v) {
+    const cols = basisColumns(b);
+    const local = [0, 1, 2].map((k) => {
+        const c = cols[k];
+        const L = length(c) || 1;
+        return (c[0] * v[0] + c[1] * v[1] + c[2] * v[2]) / L;
+    });
+    return axisName(local);
+}
+export function makeBox(a, b) {
+    return { lo: [Math.min(a[0], b[0]), Math.min(a[1], b[1]), Math.min(a[2], b[2])], hi: [Math.max(a[0], b[0]), Math.max(a[1], b[1]), Math.max(a[2], b[2])] };
+}
+export function growBox(b, g) {
+    return { lo: [b.lo[0] - g, b.lo[1] - g, b.lo[2] - g], hi: [b.hi[0] + g, b.hi[1] + g, b.hi[2] + g] };
+}
+export function boxCenter(b) {
+    return [(b.lo[0] + b.hi[0]) / 2, (b.lo[1] + b.hi[1]) / 2, (b.lo[2] + b.hi[2]) / 2];
+}
+/** Overlap of two boxes, or null when they do not overlap (touching counts). */
+export function boxIntersection(a, b) {
+    const lo = [Math.max(a.lo[0], b.lo[0]), Math.max(a.lo[1], b.lo[1]), Math.max(a.lo[2], b.lo[2])];
+    const hi = [Math.min(a.hi[0], b.hi[0]), Math.min(a.hi[1], b.hi[1]), Math.min(a.hi[2], b.hi[2])];
+    if (lo[0] > hi[0] || lo[1] > hi[1] || lo[2] > hi[2])
+        return null;
+    return { lo, hi };
+}
+/** Shortest distance between two boxes (0 when they touch or overlap). */
+export function boxDistance(a, b) {
+    let s = 0;
+    for (let k = 0; k < 3; k++) {
+        const d = a.hi[k] < b.lo[k] ? b.lo[k] - a.hi[k] : b.hi[k] < a.lo[k] ? a.lo[k] - b.hi[k] : 0;
+        s += d * d;
+    }
+    return Math.sqrt(s);
+}

package/dist/core/capabilities/audit/summary.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The compact audit result: counts per check, time per check, and ONE page of
+ * issues sorted by severity, never more than SUMMARY_CAP_BYTES of JSON. Agents
+ * cannot read results of tens of kilobytes, so the cap is enforced here by
+ * construction: issues are added while they fit, and the result names the
+ * offset of the next page.
+ */
+import { type AuditCheck, type Severity } from "./args.js";
+import type { AuditIssue } from "./judge.js";
+export declare const SUMMARY_CAP_BYTES = 5000;
+export declare function bytes(value: unknown): number;
+/** Severity first, then the check's place in the list, then magnitude. */
+export declare function sortIssues(issues: readonly AuditIssue[]): AuditIssue[];
+export declare function filterIssues(issues: readonly AuditIssue[], minSeverity?: Severity): AuditIssue[];
+export type CheckCounts = Partial<Record<Severity, number>> & {
+    partial?: number;
+    accepted?: number;
+};
+/** Per check: { error: n, warn: n, look: n } without zeros, plus `partial`
+ *  (the share of the check's samples it covered) when the editor-time budget
+ *  stopped it early. Checks that ran in full and found nothing are listed
+ *  in `clean`; a partial check never is. */
+export declare function countIssues(issues: readonly AuditIssue[], ran: readonly AuditCheck[], partial?: Partial<Record<AuditCheck, number>>, accepted?: readonly AuditIssue[]): {
+    counts: Record<string, CheckCounts>;
+    clean: AuditCheck[];
+};
+/** Kernel stages and the checks each one measures for. */
+export declare const STAGE_CHECKS: Readonly<Record<string, readonly AuditCheck[]>>;
+/**
+ * The kernel's partial stages ({stage: [done, planned]}) -> the share each
+ * requested check covered (the lowest of its stages, 2 decimals, never
+ * rounded up to 1), and the stages that are not checks (framing).
+ */
+export declare function partialChecks(raw: unknown, ran: readonly AuditCheck[]): {
+    checks: Partial<Record<AuditCheck, number>>;
+    other: Record<string, number>;
+};
+export interface CompactIssue {
+    n: number;
+    check: AuditCheck;
+    sev: Severity;
+    path: string;
+    pos: readonly number[];
+    why: string;
+    ev: Record<string, unknown>;
+    next: string;
+    /** Pass it in accept:[{key, reason}] to hide this item on later audits. */
+    key: string;
+    /** An accepted item (show_accepted) and the reason given. */
+    accepted?: string;
+    /** It was accepted, but its evidence changed. */
+    accept_stale?: string;
+}
+export declare function compactIssue(issue: AuditIssue, n: number): CompactIssue;
+export interface PageInput {
+    base: Record<string, unknown>;
+    issues: readonly AuditIssue[];
+    offset: number;
+    limit: number;
+    cap?: number;
+}
+export interface Page {
+    body: Record<string, unknown>;
+    shown: CompactIssue[];
+}
+/**
+ * One page: `base` (counts, timings, notes) plus issues[offset..] added one
+ * at a time while the JSON stays within `cap`. `next_offset` names where the
+ * next page starts; `trimmed_to_fit` says the byte cap (not `limit`) ended
+ * the page.
+ */
+export declare function buildPage({ base, issues, offset, limit, cap }: PageInput): Page;
+/** Kernel stage timings -> time per check (ms), plus setup and totals. */
+export declare function timingPerCheck(ms: Record<string, unknown> | undefined, extra: Record<string, number>): Record<string, number | string>;

package/dist/core/capabilities/audit/summary.js

@@ -0,0 +1,212 @@
+/**
+ * The compact audit result: counts per check, time per check, and ONE page of
+ * issues sorted by severity, never more than SUMMARY_CAP_BYTES of JSON. Agents
+ * cannot read results of tens of kilobytes, so the cap is enforced here by
+ * construction: issues are added while they fit, and the result names the
+ * offset of the next page.
+ */
+import { AUDIT_CHECKS, SEVERITIES } from "./args.js";
+import { issueKey } from "./accept.js";
+export const SUMMARY_CAP_BYTES = 5000;
+const SEVERITY_RANK = { error: 0, warn: 1, look: 2 };
+const CHECK_RANK = new Map(AUDIT_CHECKS.map((c, i) => [c, i]));
+export function bytes(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+/** Severity first, then the check's place in the list, then magnitude. */
+export function sortIssues(issues) {
+    return [...issues].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] ||
+        (CHECK_RANK.get(a.check) ?? 99) - (CHECK_RANK.get(b.check) ?? 99) ||
+        b.score - a.score ||
+        a.path.localeCompare(b.path));
+}
+export function filterIssues(issues, minSeverity = "look") {
+    const limit = SEVERITY_RANK[minSeverity];
+    return issues.filter((i) => SEVERITY_RANK[i.severity] <= limit);
+}
+/** Per check: { error: n, warn: n, look: n } without zeros, plus `partial`
+ *  (the share of the check's samples it covered) when the editor-time budget
+ *  stopped it early. Checks that ran in full and found nothing are listed
+ *  in `clean`; a partial check never is. */
+export function countIssues(issues, ran, partial = {}, accepted = []) {
+    const counts = {};
+    for (const i of issues) {
+        const c = (counts[i.check] ??= {});
+        c[i.severity] = (c[i.severity] ?? 0) + 1;
+    }
+    for (const i of accepted) {
+        const c = (counts[i.check] ??= {});
+        c.accepted = (c.accepted ?? 0) + 1;
+    }
+    const ordered = {};
+    for (const check of AUDIT_CHECKS) {
+        const share = ran.includes(check) ? partial[check] : undefined;
+        if (!counts[check] && share === undefined)
+            continue;
+        const c = {};
+        for (const s of SEVERITIES)
+            if (counts[check]?.[s])
+                c[s] = counts[check][s];
+        if (counts[check]?.accepted)
+            c.accepted = counts[check].accepted;
+        if (share !== undefined)
+            c.partial = share;
+        ordered[check] = c;
+    }
+    return { counts: ordered, clean: ran.filter((c) => !counts[c] && partial[c] === undefined) };
+}
+/** Kernel stages and the checks each one measures for. */
+export const STAGE_CHECKS = {
+    through_hole: ["through_hole", "z_fight"],
+    floor_gap: ["floor_gap", "z_fight"],
+    floating_sunken: ["floating", "sunken"],
+    interpenetration: ["interpenetration"],
+    orientation: ["orientation"],
+    uv_stretch: ["uv_stretch"],
+    z_fight_geometry: ["z_fight"],
+    gap_setup: ["exposed_edge", "open_fixture_end", "depth_step"],
+    exposed_edge: ["exposed_edge"],
+    open_fixture_end: ["open_fixture_end"],
+    depth_step: ["depth_step"],
+    lights: ["lights"],
+    resource: ["resource"],
+};
+/**
+ * The kernel's partial stages ({stage: [done, planned]}) -> the share each
+ * requested check covered (the lowest of its stages, 2 decimals, never
+ * rounded up to 1), and the stages that are not checks (framing).
+ */
+export function partialChecks(raw, ran) {
+    const checks = {};
+    const other = {};
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return { checks, other };
+    for (const [stage, value] of Object.entries(raw)) {
+        if (!Array.isArray(value))
+            continue;
+        const done = Number(value[0]);
+        const total = Number(value[1]);
+        if (!Number.isFinite(done) || !Number.isFinite(total) || total <= 0 || done >= total)
+            continue;
+        const share = Math.min(0.99, Math.floor((Math.max(0, done) / total) * 100) / 100);
+        const mapped = STAGE_CHECKS[stage];
+        if (!mapped) {
+            other[stage] = share;
+            continue;
+        }
+        for (const check of mapped) {
+            if (!ran.includes(check))
+                continue;
+            checks[check] = Math.min(checks[check] ?? 1, share);
+        }
+    }
+    return { checks, other };
+}
+export function compactIssue(issue, n) {
+    return {
+        n,
+        check: issue.check,
+        sev: issue.severity,
+        path: issue.path,
+        pos: issue.pos,
+        why: issue.why,
+        ev: issue.ev,
+        next: issue.next,
+        key: issueKey(issue),
+        ...(issue.accepted ? { accepted: issue.accepted } : {}),
+        ...(issue.acceptStale ? { accept_stale: issue.acceptStale } : {}),
+    };
+}
+/** A single issue that alone is too big for the page: cut its prose. */
+function shrink(issue, budget) {
+    let out = { ...issue, why: issue.why.slice(0, 200), next: issue.next.slice(0, 160) };
+    if (bytes(out) <= budget)
+        return out;
+    const ev = {};
+    for (const [k, v] of Object.entries(issue.ev).slice(0, 4))
+        ev[k] = typeof v === "string" ? v.slice(0, 80) : v;
+    out = { ...out, ev };
+    if (bytes(out) <= budget)
+        return out;
+    return { ...out, why: out.why.slice(0, 100), ev: {}, next: out.next.slice(0, 80) };
+}
+/**
+ * One page: `base` (counts, timings, notes) plus issues[offset..] added one
+ * at a time while the JSON stays within `cap`. `next_offset` names where the
+ * next page starts; `trimmed_to_fit` says the byte cap (not `limit`) ended
+ * the page.
+ */
+export function buildPage({ base, issues, offset, limit, cap = SUMMARY_CAP_BYTES }) {
+    const start = Math.min(Math.max(0, offset), issues.length);
+    const shown = [];
+    const frame = (list, extra = {}) => ({
+        ...base,
+        matching: issues.length,
+        offset: start,
+        shown: list.length,
+        ...extra,
+        issues: list,
+    });
+    let trimmed = false;
+    for (let i = start; i < issues.length && shown.length < limit; i++) {
+        const candidate = compactIssue(issues[i], i + 1);
+        // Fit against the largest tail the page can end with (a next offset AND
+        // the trimmed flag), so adding the flag afterwards never breaks the cap.
+        const tail = { next_offset: issues.length, trimmed_to_fit: true };
+        if (bytes(frame([...shown, candidate], tail)) <= cap) {
+            shown.push(candidate);
+            continue;
+        }
+        if (shown.length === 0) {
+            const room = cap - bytes(frame([], tail)) - 8;
+            const small = shrink(candidate, room);
+            if (bytes(frame([small], tail)) <= cap) {
+                shown.push(small);
+                trimmed = true;
+                continue;
+            }
+        }
+        trimmed = true;
+        break;
+    }
+    const end = start + shown.length;
+    const body = frame(shown, {
+        next_offset: end < issues.length ? end : null,
+        ...(trimmed ? { trimmed_to_fit: true } : {}),
+    });
+    // A base so large that nothing fits (should not happen): drop the notes.
+    if (bytes(body) > cap && Array.isArray(body.notes)) {
+        const lean = { ...body, notes: body.notes.slice(0, 1) };
+        return { body: lean, shown };
+    }
+    return { body, shown };
+}
+/** Kernel stage timings -> time per check (ms), plus setup and totals. */
+export function timingPerCheck(ms, extra) {
+    const m = (k) => (typeof ms?.[k] === "number" ? ms[k] : 0);
+    const out = {
+        setup: Math.round((m("collect") + m("roles") + m("mesh_pass") + m("physics_build")) * 10) / 10,
+        setup_parts: `walk ${Math.round(m("collect"))} + roles ${Math.round(m("roles"))} + meshes ${Math.round(m("mesh_pass"))} + physics ${Math.round(m("physics_build"))}`,
+    };
+    const map = [
+        ["through_hole", "through_hole"],
+        ["floor_gap", "floor_gap"],
+        ["floating_sunken", "floating+sunken"],
+        ["interpenetration", "interpenetration"],
+        ["orientation", "orientation"],
+        ["uv_stretch", "uv_stretch"],
+        ["z_fight_geometry", "z_fight_geometry"],
+        ["gap_setup", "gap_setup"],
+        ["exposed_edge", "exposed_edge"],
+        ["open_fixture_end", "open_fixture_end"],
+        ["depth_step", "depth_step"],
+        ["lights", "lights"],
+        ["resource", "resource"],
+        ["poses", "framing"],
+    ];
+    for (const [stage, name] of map)
+        if (typeof ms?.[stage] === "number")
+            out[name] = ms[stage];
+    out.editor_total = m("total");
+    return { ...out, ...extra };
+}