Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

perf(spaces-web): no layout shift while Spaces and Settings load; CI check for layout shift (CUA-1951) (#5633)

ddupont15fa9a4c0cab
diff --git a/.github/workflows/ci-cua-spaces-web.yml b/.github/workflows/ci-cua-spaces-web.yml
index 839ada9842..7bac641153 100644
--- a/.github/workflows/ci-cua-spaces-web.yml
+++ b/.github/workflows/ci-cua-spaces-web.yml
@@ -118,6 +118,11 @@ jobs:
run: |
npx playwright install --with-deps chromium
pnpm parity
+ # Layout shift of every route's first load (CUA-1951): fails at 0.05 or more, or a first render over its loose budget.
+ - name: Layout shift per route
+ if: matrix.host == 'browser'
+ working-directory: apps/cua-spaces-web
+ run: pnpm perf --shift
- name: Parity flows and the bridge on the Electron shell (demo mode)
if: matrix.host == 'electron'
working-directory: apps/cua-spaces-web
diff --git a/apps/cua-spaces-web/README.md b/apps/cua-spaces-web/README.md
index d93ac4da0e..7d0d787d50 100644
--- a/apps/cua-spaces-web/README.md
+++ b/apps/cua-spaces-web/README.md
@@ -13,6 +13,7 @@ pnpm build # app core wasm, then dist/
pnpm typecheck
pnpm test # vitest; builds the core first when Rust is available
pnpm core # just the app core wasm (src/bridge/core/wasm/, gitignored)
+pnpm perf --shift # layout shift and first render of every route (CI); pnpm perf also checks bundle sizes
pnpm screenshots # every route, light and dark, demo mode, into docs/screenshots/ (gitignored)
```
diff --git a/apps/cua-spaces-web/perf-budget.json b/apps/cua-spaces-web/perf-budget.json
index 7b45ae9c28..f8f5765442 100644
--- a/apps/cua-spaces-web/perf-budget.json
+++ b/apps/cua-spaces-web/perf-budget.json
@@ -20,5 +20,6 @@
"totalJs": 1321984,
"totalCss": 69632,
"wasm": 4806656,
- "firstRenderMs": 200
+ "cls": 0.05,
+ "firstRenderMs": 600
}
diff --git a/apps/cua-spaces-web/scripts/perf.mjs b/apps/cua-spaces-web/scripts/perf.mjs
index 5337e34507..f4b69ca714 100644
--- a/apps/cua-spaces-web/scripts/perf.mjs
+++ b/apps/cua-spaces-web/scripts/perf.mjs
@@ -10,6 +10,7 @@
// pnpm perf --update write new budgets: current sizes plus 15%
// pnpm perf --no-build reuse dist/ (it must have .vite/manifest.json)
// pnpm perf --no-timing sizes only
+// pnpm perf --shift only the loading checks (CI): first render time and layout shift per route
//
// A route's size is what opening it adds on top of the entry: its own chunk
// plus the shared chunks it imports that the entry doesn't already load.
@@ -22,6 +23,7 @@ const root = fileURLToPath(new URL("..", import.meta.url));
const dist = `${root}dist/`;
const budgetFile = `${root}perf-budget.json`;
const args = new Set(process.argv.slice(2));
+const SHIFT_ONLY = args.has("--shift");
const HEADROOM = 1.15;
const RUNS = 3;
@@ -102,10 +104,16 @@ async function measureTiming() {
for (const route of routes.map((r) => r.name).filter((n) => !n.includes("$"))) {
const firstRender = [];
const fcp = [];
+ const cls = [];
for (let i = 0; i < RUNS; i++) {
// A fresh context each run, so nothing is cached.
const context = await browser.newContext({ viewport: { width: 1440, height: 900 } });
await context.addInitScript(() => {
+ // Layout shift the person didn't cause (CUA-1951): the sum of the page's layout-shift entries.
+ window.__cls = 0;
+ new PerformanceObserver((list) => {
+ for (const e of list.getEntries()) if (!e.hadRecentInput) window.__cls += e.value;
+ }).observe({ type: "layout-shift", buffered: true });
// The first time the page's <main> has content: the route rendered.
new MutationObserver((_, observer) => {
if (document.querySelector("main > *")) {
@@ -118,15 +126,18 @@ async function measureTiming() {
await page.goto(`${base}/${route}`);
await page.waitForFunction(() => window.__firstRender !== undefined, null, { timeout: 15_000 });
await page.waitForFunction(() => performance.getEntriesByName("first-contentful-paint").length > 0, null, { timeout: 3_000 }).catch(() => {});
+ await page.waitForTimeout(1200); // late arrivals shift too
const t = await page.evaluate(() => ({
+ cls: window.__cls,
render: window.__firstRender,
fcp: performance.getEntriesByName("first-contentful-paint")[0]?.startTime ?? null,
}));
firstRender.push(t.render);
+ cls.push(t.cls);
if (t.fcp !== null) fcp.push(t.fcp);
await context.close();
}
- out[route] = { firstRenderMs: Math.round(median(firstRender)), fcpMs: fcp.length ? Math.round(median(fcp)) : null };
+ out[route] = { firstRenderMs: Math.round(median(firstRender)), fcpMs: fcp.length ? Math.round(median(fcp)) : null, cls: Math.round(median(cls) * 10000) / 10000 };
}
} finally {
await browser.close();
@@ -159,6 +170,8 @@ if (args.has("--update")) {
totalJs: up(sizes.totalJs.raw),
totalCss: up(sizes.totalCss.raw),
wasm: up(sizes.wasm.raw),
+ // Layout shift of a route's first load (the Cumulative Layout Shift sum): under 0.05 is "good".
+ cls: 0.05,
firstRenderMs: timing ? Math.ceil((Math.max(...Object.values(timing).map((t) => t.firstRenderMs)) * 2) / 50) * 50 : 1000,
};
writeFileSync(budgetFile, `${JSON.stringify(budget, null, 2)}\n`);
@@ -171,6 +184,7 @@ const warnings = [];
const rows = [];
const row = (name, s, limit) => {
const over = limit !== undefined && s.raw > limit;
+ if (SHIFT_ONLY) return;
if (over) failures.push(`${name} is ${kb(s.raw)}, over its ${kb(limit)} budget`);
if (limit === undefined) warnings.push(`${name} has no budget; run \`pnpm perf --update\` to add one`);
rows.push([name, kb(s.raw), kb(s.gzip), limit === undefined ? "none" : kb(limit), over ? "OVER" : limit === undefined ? "" : `${Math.round((s.raw / limit) * 100)}%`]);
@@ -183,15 +197,17 @@ row("total CSS", sizes.totalCss, budget.totalCss);
row("app core wasm", sizes.wasm, budget.wasm);
const widths = [34, 11, 11, 11, 6];
-console.log(`\n${pad("Chunk", widths[0])}${lpad("Size", widths[1])}${lpad("Gzip", widths[2])}${lpad("Budget", widths[3])}${lpad("Used", widths[4] + 2)}`);
-for (const r of rows) console.log(`${pad(r[0], widths[0])}${lpad(r[1], widths[1])}${lpad(r[2], widths[2])}${lpad(r[3], widths[3])}${lpad(r[4], widths[4] + 2)}`);
+if (!SHIFT_ONLY) console.log(`\n${pad("Chunk", widths[0])}${lpad("Size", widths[1])}${lpad("Gzip", widths[2])}${lpad("Budget", widths[3])}${lpad("Used", widths[4] + 2)}`);
+for (const r of SHIFT_ONLY ? [] : rows) console.log(`${pad(r[0], widths[0])}${lpad(r[1], widths[1])}${lpad(r[2], widths[2])}${lpad(r[3], widths[3])}${lpad(r[4], widths[4] + 2)}`);
if (timing) {
- console.log(`\n${pad("Time to first render (median of " + RUNS + ")", widths[0])}${lpad("Render", widths[1])}${lpad("FCP", widths[2])}${lpad("Budget", widths[3])}`);
+ console.log(`\n${pad("Time to first render (median of " + RUNS + ")", widths[0])}${lpad("Render", widths[1])}${lpad("FCP", widths[2])}${lpad("Budget", widths[3])}${lpad("CLS", widths[4] + 4)}`);
for (const [route, t] of Object.entries(timing)) {
const over = budget.firstRenderMs !== undefined && t.firstRenderMs > budget.firstRenderMs;
if (over) failures.push(`/${route} first rendered after ${t.firstRenderMs} ms, over the ${budget.firstRenderMs} ms budget`);
- console.log(`${pad("/" + route, widths[0])}${lpad(t.firstRenderMs + " ms", widths[1])}${lpad(t.fcpMs === null ? "n/a" : t.fcpMs + " ms", widths[2])}${lpad((budget.firstRenderMs ?? "none") + " ms", widths[3])}${over ? " OVER" : ""}`);
+ const shifted = budget.cls !== undefined && t.cls >= budget.cls;
+ if (shifted) failures.push(`/${route} shifted by ${t.cls} while loading, over the ${budget.cls} layout-shift budget`);
+ console.log(`${pad("/" + route, widths[0])}${lpad(t.firstRenderMs + " ms", widths[1])}${lpad(t.fcpMs === null ? "n/a" : t.fcpMs + " ms", widths[2])}${lpad((budget.firstRenderMs ?? "none") + " ms", widths[3])}${lpad(t.cls, widths[4] + 4)}${over || shifted ? " OVER" : ""}`);
}
}
diff --git a/apps/cua-spaces-web/src/hooks/use-quiet.test.tsx b/apps/cua-spaces-web/src/hooks/use-quiet.test.tsx
new file mode 100644
index 0000000000..1dc1e10764
--- /dev/null
+++ b/apps/cua-spaces-web/src/hooks/use-quiet.test.tsx
@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useQuiet } from "./use-quiet";
+
+describe("useQuiet", () => {
+ beforeEach(() => vi.useFakeTimers());
+ afterEach(() => vi.useRealTimers());
+
+ it("waits until the signature stops changing", () => {
+ const { result, rerender } = renderHook(({ sig }) => useQuiet(sig, 100, 1000), { initialProps: { sig: "a" } });
+ expect(result.current).toBe(false);
+ act(() => void vi.advanceTimersByTime(80));
+ rerender({ sig: "b" }); // another read answered: the wait starts over
+ act(() => void vi.advanceTimersByTime(80));
+ expect(result.current).toBe(false);
+ act(() => void vi.advanceTimersByTime(30));
+ expect(result.current).toBe(true);
+ });
+
+ it("gives up waiting at the cap, however much keeps changing", () => {
+ const { result, rerender } = renderHook(({ sig }) => useQuiet(sig, 100, 400), { initialProps: { sig: "0" } });
+ for (let i = 1; i <= 6; i++) {
+ act(() => void vi.advanceTimersByTime(70));
+ rerender({ sig: String(i) });
+ }
+ expect(result.current).toBe(true);
+ });
+
+ it("stays true after later changes, so they update in place", () => {
+ const { result, rerender } = renderHook(({ sig }) => useQuiet(sig, 50, 500), { initialProps: { sig: "a" } });
+ act(() => void vi.advanceTimersByTime(60));
+ expect(result.current).toBe(true);
+ rerender({ sig: "b" });
+ expect(result.current).toBe(true);
+ });
+});
diff --git a/apps/cua-spaces-web/src/hooks/use-quiet.ts b/apps/cua-spaces-web/src/hooks/use-quiet.ts
new file mode 100644
index 0000000000..57372cd84c
--- /dev/null
+++ b/apps/cua-spaces-web/src/hooks/use-quiet.ts
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+import { useEffect, useState } from "react";
+
+/**
+ * True once `signature` (a string of everything the page reads from the host) has stopped changing for
+ * `quietMs`, or after `capMs` at the latest. A page's cards and lists come from several host reads that
+ * answer one after another; drawn as each arrives they push each other down. A page that draws its body when
+ * this turns true shows the finished layout in one step (CUA-1951). It stays true afterwards, so later
+ * updates change content in place as before.
+ */
+export function useQuiet(signature: string, quietMs = 120, capMs = 700): boolean {
+ const [quiet, setQuiet] = useState(false);
+ useEffect(() => {
+ if (quiet) return;
+ const t = setTimeout(() => setQuiet(true), quietMs);
+ return () => clearTimeout(t);
+ }, [signature, quiet, quietMs]);
+ useEffect(() => {
+ const t = setTimeout(() => setQuiet(true), capMs);
+ return () => clearTimeout(t);
+ }, [capMs]);
+ return quiet;
+}
diff --git a/apps/cua-spaces-web/src/routes/settings/index.tsx b/apps/cua-spaces-web/src/routes/settings/index.tsx
index 1d40a8171b..8f26d3f6d2 100644
--- a/apps/cua-spaces-web/src/routes/settings/index.tsx
+++ b/apps/cua-spaces-web/src/routes/settings/index.tsx
@@ -66,7 +66,9 @@ const fail = toastError;
* Keyvault, AI agents), with this UI's own rows (appearance, keyboard shortcuts);
* without the core, the same settings drawn by hand. */
function SettingsPage() {
- const { data: settings } = useSettings();
+ const { data: settings, isLoading } = useSettings();
+ // Not the hand-drawn fallback while the host's answer is still on its way: it would be replaced by the core's page, and everything would move.
+ if (isLoading && !settings) return null;
return settings?.page ? <CoreGeneralPage page={settings.page} /> : <FallbackSettingsPage />;
}
diff --git a/apps/cua-spaces-web/src/routes/spaces/index.tsx b/apps/cua-spaces-web/src/routes/spaces/index.tsx
index 80684deb77..9821d3a774 100644
--- a/apps/cua-spaces-web/src/routes/spaces/index.tsx
+++ b/apps/cua-spaces-web/src/routes/spaces/index.tsx
@@ -20,6 +20,7 @@ import { SpaceCanvas } from "@/components/space-canvas";
import { StateLabel } from "@/components/state-dot";
import { useTileVideo } from "@/components/video/tile-video";
import { useNewSpace } from "@/hooks/use-new-space";
+import { useQuiet } from "@/hooks/use-quiet";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Segmented } from "@/components/ui/segmented";
@@ -74,6 +75,11 @@ function SpacesPage() {
const runHere = readySpace && !agentRan ? readySpace : undefined;
const [runOpen, setRunOpen] = useState(false);
const [connectOpen, setConnectOpen] = useState(false);
+ // The cards above the list (ready, checklist, computers) and the list come from separate host reads. Draw them
+ // together once those have answered, not one by one with the page jumping at each (CUA-1951).
+ const settled = useQuiet(
+ [isLoading, all.length, machines.length, Object.keys(checklist.done).length, checklist.dismissed, agents?.runs.length, agents?.agents.length, resources ? 1 : 0].join("|"),
+ );
return (
<Page>
@@ -86,6 +92,8 @@ function SpacesPage() {
</Button>
}
/>
+ {settled ? (
+ <>
<FirstRunTodosCard />
{runHere ? <SpaceReadyCard space={runHere} onRun={() => setRunOpen(true)} /> : null}
{firstRunTodos ? null : <GettingStarted onRunAgent={runHere ? () => setRunOpen(true) : undefined} />}
@@ -163,6 +171,8 @@ function SpacesPage() {
))}
</ul>
)}
+ </>
+ ) : null}
</Page>
);
}