Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
// ESM only. Pure functions for parsing, summarizing, checking, and formatting perf reports.
// Shapes live in perf-report.d.ts; this file stays implementation-only.
const REQUIRED_TIMING_FIELDS = [
"fcpMs",
"lcpMs",
"tbtMs",
"cls",
"maxLongTaskMs",
"firstLoadJsBytes",
];
/**
* Validates and parses a performance report JSON or object.
* Requires schemaVersion === 1, non-empty runs array, and every run to have
* a valid string label and numeric-or-null timing fields.
* Fails closed on missing fields instead of silently coercing to zero.
*
* @param {unknown} json - Raw JSON string or parsed object
* @returns {PerfReport} Validated report object
*/
export function parsePerfReport(json) {
let report = json;
if (typeof json === "string") {
try {
report = JSON.parse(json);
} catch (err) {
throw new Error(`Invalid JSON for perf report: ${err instanceof Error ? err.message : String(err)}`);
}
}
if (!report || typeof report !== "object" || Array.isArray(report)) {
throw new Error("Report must be a non-null object");
}
if (report.schemaVersion !== 1) {
throw new Error(`Invalid or missing schemaVersion: expected 1, received ${report.schemaVersion}`);
}
if (!Array.isArray(report.runs) || report.runs.length === 0) {
throw new Error("Report missing valid runs: expected non-empty array");
}
for (let index = 0; index < report.runs.length; index++) {
const run = report.runs[index];
if (!run || typeof run !== "object" || Array.isArray(run)) {
throw new Error(`Run at index ${index} must be a non-null object`);
}
if (!("label" in run) || typeof run.label !== "string" || !run.label.trim()) {
throw new Error(`Run at index ${index} missing valid string label`);
}
for (const field of REQUIRED_TIMING_FIELDS) {
if (!(field in run) || run[field] === undefined) {
throw new Error(`Run "${run.label}" missing required field: ${field}`);
}
const val = run[field];
if (val !== null && (typeof val !== "number" || !Number.isFinite(val))) {
throw new Error(`Run "${run.label}" field "${field}" must be a finite number or null`);
}
}
}
return report;
}
/**
* Returns a compact summary projection of all runs in the report.
*
* @param {{ runs?: Array<Record<string, unknown>> }|string} report - The performance report
* @returns {PerfSummary[]}
*/
export function summarize(report) {
const data = typeof report === "string" ? JSON.parse(report) : report;
if (!data?.runs || !Array.isArray(data.runs)) {
return [];
}
return data.runs.map((run) => ({
label: run.label,
fcpMs: run.fcpMs,
lcpMs: run.lcpMs,
tbtMs: run.tbtMs,
cls: run.cls,
firstLoadJsBytes: run.firstLoadJsBytes,
maxLongTaskMs: run.maxLongTaskMs,
}));
}
/**
* Helper to resolve baseline tbtMs for a run label.
* Supports map keyed by label { [label]: { tbtMs } } or { [label]: number },
* as well as report shape { runs: [{ label, tbtMs }] }.
*/
function getBaselineTbt(baseline, label) {
if (!baseline || typeof baseline !== "object") return null;
const direct = baseline[label];
if (typeof direct === "number" && Number.isFinite(direct)) {
return direct;
}
if (direct && typeof direct.tbtMs === "number" && Number.isFinite(direct.tbtMs)) {
return direct.tbtMs;
}
if (Array.isArray(baseline.runs)) {
const run = baseline.runs.find((r) => r?.label === label);
if (run && typeof run.tbtMs === "number" && Number.isFinite(run.tbtMs)) {
return run.tbtMs;
}
}
return null;
}
/**
* Evaluates performance violations against budget and optional baseline.
*
* Note: Contract text in Phase 0 specifies two arguments (report, budget), but
* baseline is accepted as the third argument to keep the function pure and
* dependency-free as specified in the contract ownership rules.
*
* @param {{ runs?: Array<Record<string, unknown>>, host?: { loadAvg1?: number } }|string} report - The performance report (partial reports are valid input: the point is to report what is missing)
* @param {any} budget - The performance budget
* @param {any|null} [baseline] - Optional baseline measurements
* @returns {string[]} List of human-readable violation messages
*/
export function perfViolations(report, budget, baseline = null) {
const failures = [];
const data = typeof report === "string" ? JSON.parse(report) : report;
const runs = Array.isArray(data?.runs) ? data.runs : [];
const runByLabel = new Map(runs.map((r) => [r?.label, r]));
// 1. Enforce firstLoadJsBytes caps per label
const enforcedBytes = budget?.enforce?.firstLoadJsBytes;
if (enforcedBytes && typeof enforcedBytes === "object") {
for (const [label, cap] of Object.entries(enforcedBytes)) {
const run = runByLabel.get(label);
const actual = run?.firstLoadJsBytes;
if (actual === null || actual === undefined || !Number.isFinite(actual)) {
failures.push(`${label}: missing measurement`);
} else if (Number.isFinite(cap) && actual > cap) {
failures.push(`${label}: firstLoadJsBytes ${actual} > ${cap}`);
}
}
}
// 2. Enforce TBT blowup factor against baseline
// Baseline absent or null skips the check entirely (no baseline is not a violation).
//
// Load gate: TBT is wall-clock inside a browser, so it tracks host load, not just the
// bundle. On this box the same commit measured 138 ms at load ~1 and 794 ms at load ~13,
// a 6x swing that no blowup factor can attribute honestly. The baseline was taken on an
// idle host, so a run above the ceiling below is comparing apples to a different machine
// and the TBT comparison is skipped with an explicit note instead of failing or silently
// passing. A real regression at idle still fails.
const maxLoad = Number(budget?.enforce?.maxLoadAvg1ForTiming);
const reportLoad = data?.host?.loadAvg1;
const loadComparable =
!Number.isFinite(maxLoad) || !Number.isFinite(reportLoad) || reportLoad <= maxLoad;
// Same instrument check: a different core count is a different machine, and TBT is
// wall-clock. Comparing across it produces a failure that says nothing about the commit.
const baseCpus = Number(baseline?.host?.cpus);
const runCpus = Number(data?.host?.cpus);
const hostComparable =
!Number.isFinite(baseCpus) || !Number.isFinite(runCpus) || baseCpus === runCpus;
const blowupFactor = budget?.enforce?.tbtMsBlowupFactor;
if (loadComparable && hostComparable && baseline && blowupFactor !== null && blowupFactor !== undefined && Number.isFinite(blowupFactor)) {
for (const run of runs) {
if (!run?.label) continue;
const baseTbt = getBaselineTbt(baseline, run.label);
if (baseTbt !== null && Number.isFinite(baseTbt)) {
if (run.tbtMs === null || run.tbtMs === undefined || !Number.isFinite(run.tbtMs)) {
// A null tbtMs means the probe never attributed a long task, which on a
// shell that has already painted is a measurement bug, not a fast page.
// Passing it would turn the gate off precisely when instrumentation
// breaks, so it is a violation rather than a skip.
failures.push(`${run.label}: missing tbtMs measurement`);
} else if (run.tbtMs > baseTbt * blowupFactor) {
failures.push(`${run.label}: tbtMs ${run.tbtMs}ms > ${blowupFactor}x baseline ${baseTbt}ms`);
}
}
}
}
// Targets (budget.targets) are advisory and never produce violations
return failures;
}
/**
* Formats report runs into a table with stable fixed-width aligned columns.
* Produces pure string output without ANSI color escapes.
*
* @param {{ runs?: Array<Record<string, unknown>> }|string} report - The performance report
* @returns {string} Fixed-width aligned table text
*/
export function formatTable(report) {
const data = typeof report === "string" ? JSON.parse(report) : report;
const runs = Array.isArray(data?.runs) ? data.runs : [];
if (runs.length === 0) return "";
const headers = ["label", "fcp", "lcp", "tbt", "cls", "maxTask", "jsKB"];
const rows = runs.map((run) => [
String(run.label ?? "n/a"),
run.fcpMs != null ? `${run.fcpMs}ms` : "n/a",
run.lcpMs != null ? `${run.lcpMs}ms` : "n/a",
run.tbtMs != null ? `${run.tbtMs}ms` : "n/a",
typeof run.cls === "number" ? run.cls.toFixed(3) : "n/a",
run.maxLongTaskMs != null ? `${run.maxLongTaskMs}ms` : "n/a",
run.firstLoadJsBytes != null ? `${(run.firstLoadJsBytes / 1024).toFixed(1)}KB` : "n/a",
]);
const allRows = [headers, ...rows];
const colWidths = headers.map((_, colIdx) =>
Math.max(...allRows.map((row) => row[colIdx].length))
);
return allRows
.map((row) =>
row
.map((cell, colIdx) => (colIdx === row.length - 1 ? cell : cell.padEnd(colWidths[colIdx])))
.join(" ")
)
.join("\n");
}