Instrument builder restore performance

This commit is contained in:
eust-w 2026-06-25 13:55:36 +08:00
parent ba5ad4402b
commit 51cea16cab
3 changed files with 256 additions and 70 deletions

View File

@ -661,12 +661,16 @@ Control evidence:
- Active state endpoint: full `/state` returned `602` bodies; active
`/state?bodies=active` returned `34` bodies in `49ms`, filtered `568` fixed
bodies, and retained `4/4` composed dynamic bodies.
- Scene Builder UI compose: representative run `3601ms` end to end with real
- Scene Builder UI compose: representative run `3882ms` end to end with real
backend diagnostics.
- Share-link restore: observed full browser restore range `15053-20946ms`
across the latest two release gates.
- Config import restore: observed full browser restore range `9628-13213ms`
across the latest two release gates.
- Share-link restore: representative full browser restore `15178ms`; builder
telemetry splits it into `compose=315ms`, `preview=8279ms`,
`state=7ms`, synchronous `stats=1ms`, asynchronous
`pixelWait=1954ms`, and `pixel=1371ms`.
- Config import restore: representative full browser restore `11689ms`; builder
telemetry splits it into `compose=117ms`, `preview=4523ms`,
`state=8ms`, synchronous `stats=1ms`, asynchronous
`pixelWait=2117ms`, and `pixel=1580ms`.
- Composed object body edit: `56ms`.
- Fixed inventory edit rejection: `56ms`.
- Dynamic composed object drop: `0.47846m`.
@ -791,9 +795,11 @@ Current performance boundaries:
restore, asset setup, and screenshots. The next tier is material reduction,
LODs, static asset manifests, and eventually moving repeated fixed inventory
into a backend static-state channel.
- Runtime stats no longer perform repeated WebGL pixel readback. Pixel proof is
sampled once after manifest load and screenshot/debug export, while ordinary
stats refresh reads the cached value.
- Runtime stats no longer perform repeated or load-blocking WebGL pixel
readback. Pixel proof is scheduled after manifest load, sampled once, and
cached; ordinary stats refresh reads the cached value. The latest gate shows
the load-path stats render at `1ms` while pixel proof runs in the separate
`pixel` telemetry stage.
## Handoff Criteria

View File

@ -659,6 +659,8 @@ async function readBrowserStats(page) {
total: numberData("acceptanceTotal"),
},
runState: text("#viewport-run-state"),
builderSceneTelemetry: window.__motrixPreviewDebug?.getBuilderSceneTelemetry?.()
?? window.__motrixBuilderSceneTelemetry?.current,
physicsTiers: {
backendDynamic: numberData("physicsBackendDynamic"),
backendFixed: numberData("physicsBackendFixed"),
@ -784,6 +786,44 @@ async function readBrowserStats(page) {
});
}
function numberOrDash(value) {
return Number.isFinite(Number(value)) ? Math.round(Number(value)) : "-";
}
function builderSceneTelemetryDetail(telemetry) {
if (!telemetry) {
return "telemetry=missing";
}
return [
`telemetry=${numberOrDash(telemetry.totalMs)}ms`,
`compose=${numberOrDash(telemetry.composeMs)}ms`,
`preview=${numberOrDash(telemetry.previewLoadMs)}ms`,
`state=${numberOrDash(telemetry.stateConnectMs)}ms`,
`stats=${numberOrDash(telemetry.statsRenderMs)}ms`,
`pixelWait=${numberOrDash(telemetry.pixelProofWaitMs)}ms`,
`pixel=${numberOrDash(telemetry.pixelProofMs)}ms`,
`load=${numberOrDash(telemetry.loadResolvedManifestMs)}ms`,
`drag=${numberOrDash(telemetry.dragSetupMs)}ms`,
`reset=${numberOrDash(telemetry.resetMs)}ms`,
`cached=${telemetry.cached ?? "-"}`,
`resetApplied=${telemetry.resetApplied ?? "-"}`,
].join(" ");
}
function hasValidBuilderSceneTelemetry(telemetry) {
return telemetry
&& telemetry.schema === "motrixsim-web.builder-scene-telemetry.v1"
&& telemetry.backendCompose === true
&& Number(telemetry.totalMs) > 0
&& Number(telemetry.composeMs) >= 0
&& Number(telemetry.previewLoadMs) > 0
&& Number(telemetry.loadResolvedManifestMs) >= Number(telemetry.previewLoadMs)
&& Number(telemetry.statsRenderMs) >= 0
&& Number(telemetry.pixelProofMs) > 0
&& telemetry.resetApplied === true
&& !telemetry.error;
}
async function waitForStableBodyStateCache(page) {
await page.waitForFunction(([minBindings]) => {
const skipped = Number(document.documentElement.dataset.skippedBodyStateCount ?? "0");
@ -1460,6 +1500,7 @@ async function restoreBuilderConfigFile(browser, configExport) {
const stats = await readBrowserStats(page);
const restoredConfig = await readBuilderConfig(page);
const elapsedMs = Math.round(performance.now() - started);
const telemetryOk = hasValidBuilderSceneTelemetry(stats.builderSceneTelemetry);
const restoreOk = sameBuilderConfig(restoredConfig, configExport.config)
&& /后端物理组合|physical backend composed/i.test(stats.builderStatus)
&& !/组合中|composing/i.test(stats.builderStatus)
@ -1468,11 +1509,12 @@ async function restoreBuilderConfigFile(browser, configExport) {
&& stats.diagnostics.source.includes("外部仿真")
&& stats.physics.includes("后端物理")
&& numericText(stats.objects) >= thresholds.minObjects
&& numericText(stats.bindings) >= thresholds.minBodyBindings;
&& numericText(stats.bindings) >= thresholds.minBodyBindings
&& telemetryOk;
check(
"browser-builder-config-import-restore",
restoreOk,
`${elapsedMs}ms click=${clickMs}ms skippedDefaultLoad=${skippedDefaultLoad}; initial=${initialStatus || "-"}; workspace=${await page.evaluate(() => document.querySelector("#workspace-status")?.textContent?.trim() ?? "")}; props=${stats.summaryProps}; objects=${stats.objects}; control=${stats.diagnostics.controlUrl}`,
`${elapsedMs}ms click=${clickMs}ms skippedDefaultLoad=${skippedDefaultLoad}; ${builderSceneTelemetryDetail(stats.builderSceneTelemetry)}; initial=${initialStatus || "-"}; workspace=${await page.evaluate(() => document.querySelector("#workspace-status")?.textContent?.trim() ?? "")}; props=${stats.summaryProps}; objects=${stats.objects}; control=${stats.diagnostics.controlUrl}`,
);
const screenshot = await captureConfigImportRestoreScreenshot(
page,
@ -1516,6 +1558,7 @@ async function restoreBuilderShareLink(browser, shareLink) {
const stats = await readBrowserStats(page);
const restoredConfig = await readBuilderConfig(page);
const elapsedMs = Math.round(performance.now() - started);
const telemetryOk = hasValidBuilderSceneTelemetry(stats.builderSceneTelemetry);
const restoreOk = sameBuilderConfig(restoredConfig, shareLink.originalConfig)
&& /后端物理组合|physical backend composed/i.test(stats.builderStatus)
&& !/组合中|composing/i.test(stats.builderStatus)
@ -1524,11 +1567,12 @@ async function restoreBuilderShareLink(browser, shareLink) {
&& stats.diagnostics.source.includes("外部仿真")
&& stats.physics.includes("后端物理")
&& numericText(stats.objects) >= thresholds.minObjects
&& numericText(stats.bindings) >= thresholds.minBodyBindings;
&& numericText(stats.bindings) >= thresholds.minBodyBindings
&& telemetryOk;
check(
"browser-share-link-restore",
restoreOk,
`${elapsedMs}ms status=${stats.builderStatus}; workspace=${await page.evaluate(() => document.querySelector("#workspace-status")?.textContent?.trim() ?? "")}; props=${stats.summaryProps}; objects=${stats.objects}; control=${stats.diagnostics.controlUrl}`,
`${elapsedMs}ms ${builderSceneTelemetryDetail(stats.builderSceneTelemetry)}; status=${stats.builderStatus}; workspace=${await page.evaluate(() => document.querySelector("#workspace-status")?.textContent?.trim() ?? "")}; props=${stats.summaryProps}; objects=${stats.objects}; control=${stats.diagnostics.controlUrl}`,
);
const screenshot = await captureShareRestoreScreenshot(
page,

View File

@ -138,6 +138,32 @@ interface AcceptanceTelemetryEntry {
total: number;
}
interface BuilderSceneTelemetryEntry {
schema: "motrixsim-web.builder-scene-telemetry.v1";
runId: number;
startedAt: string;
statusKey: string;
sceneId: string;
robotId: string;
backendCompose: boolean;
propCount: number;
objectCount?: number;
cached?: boolean;
resetApplied?: boolean;
composeMs?: number;
createManifestMs?: number;
previewLoadMs?: number;
stateConnectMs?: number;
statsRenderMs?: number;
pixelProofWaitMs?: number;
pixelProofMs?: number;
loadResolvedManifestMs?: number;
dragSetupMs?: number;
resetMs?: number;
totalMs?: number;
error?: string;
}
interface AcceptanceCheck {
id: string;
label: string;
@ -280,6 +306,7 @@ interface RuntimeDiagnostics {
failCount: number;
total: number;
};
lastBuilderScene?: BuilderSceneTelemetryEntry;
}
interface LocalAssetBundle {
@ -834,6 +861,7 @@ const activityLog: ActivityEntry[] = [];
let lastLivePanelRefreshAt = 0;
let lastDiagnosticsPanelRefreshAt = 0;
let controlRequestSerial = 0;
let builderSceneRunSerial = 0;
const textElementCache = new Map<string, HTMLElement>();
let textWriteCount = 0;
let textWriteSkipCount = 0;
@ -845,6 +873,8 @@ let statsRefreshTimer: number | undefined;
let statsRefreshRenderCount = 0;
let statsRefreshSkipCount = 0;
let lastStatsRefreshIntervalMs = STATS_REFRESH_MS;
let pixelProofRefreshHandle = 0;
let pixelProofRefreshSerial = 0;
let builderPanelDragDirty = false;
let builderPanelRenderCount = 0;
let builderPanelDeferredRenderCount = 0;
@ -867,6 +897,7 @@ let builderPhysicsProfileCacheHitCount = 0;
let builderPhysicsProfileCacheMissCount = 0;
const controlTelemetry: { current?: ControlTelemetryEntry; history: ControlTelemetryEntry[] } = { history: [] };
const acceptanceTelemetry: { current?: AcceptanceTelemetryEntry; history: AcceptanceTelemetryEntry[] } = { history: [] };
const builderSceneTelemetry: { current?: BuilderSceneTelemetryEntry; history: BuilderSceneTelemetryEntry[] } = { history: [] };
document.documentElement.lang = currentLocale;
@ -1448,6 +1479,27 @@ function publishAcceptanceTelemetry(entry: AcceptanceTelemetryEntry): void {
renderDiagnosticsPanel(undefined, { force: true });
}
function publishBuilderSceneTelemetry(entry: BuilderSceneTelemetryEntry): void {
const data = document.documentElement.dataset;
data.builderSceneRunId = String(entry.runId);
data.builderSceneBackendCompose = String(entry.backendCompose);
data.builderSceneCached = entry.cached === undefined ? "" : String(entry.cached);
data.builderSceneResetApplied = entry.resetApplied === undefined ? "" : String(entry.resetApplied);
data.builderSceneComposeMs = entry.composeMs === undefined ? "" : String(Math.round(entry.composeMs));
data.builderSceneCreateManifestMs = entry.createManifestMs === undefined ? "" : String(Math.round(entry.createManifestMs));
data.builderScenePreviewLoadMs = entry.previewLoadMs === undefined ? "" : String(Math.round(entry.previewLoadMs));
data.builderSceneStateConnectMs = entry.stateConnectMs === undefined ? "" : String(Math.round(entry.stateConnectMs));
data.builderSceneStatsRenderMs = entry.statsRenderMs === undefined ? "" : String(Math.round(entry.statsRenderMs));
data.builderScenePixelProofWaitMs = entry.pixelProofWaitMs === undefined ? "" : String(Math.round(entry.pixelProofWaitMs));
data.builderScenePixelProofMs = entry.pixelProofMs === undefined ? "" : String(Math.round(entry.pixelProofMs));
data.builderSceneLoadResolvedManifestMs = entry.loadResolvedManifestMs === undefined ? "" : String(Math.round(entry.loadResolvedManifestMs));
data.builderSceneDragSetupMs = entry.dragSetupMs === undefined ? "" : String(Math.round(entry.dragSetupMs));
data.builderSceneResetMs = entry.resetMs === undefined ? "" : String(Math.round(entry.resetMs));
data.builderSceneTotalMs = entry.totalMs === undefined ? "" : String(Math.round(entry.totalMs));
data.builderSceneError = entry.error ?? "";
(window as unknown as { __motrixBuilderSceneTelemetry?: typeof builderSceneTelemetry }).__motrixBuilderSceneTelemetry = builderSceneTelemetry;
}
function startControlTelemetry(action: ControlAction, requestId: number, expectedPaused?: boolean): ControlTelemetryEntry {
const entry: ControlTelemetryEntry = {
requestId,
@ -1636,7 +1688,8 @@ async function loadManifest(url: string): Promise<void> {
await loadResolvedManifest(manifest);
}
async function loadResolvedManifest(manifest: SceneManifest): Promise<void> {
async function loadResolvedManifest(manifest: SceneManifest, telemetry?: BuilderSceneTelemetryEntry): Promise<void> {
const startedAt = performance.now();
stateClient.disconnect();
latestFrame = undefined;
currentManifest = manifest;
@ -1650,7 +1703,13 @@ async function loadResolvedManifest(manifest: SceneManifest): Promise<void> {
renderJointControls();
renderActuatorControls();
renderInputAvailability();
const previewLoadStartedAt = performance.now();
await previewer.loadManifest(manifest);
if (telemetry) {
telemetry.previewLoadMs = performance.now() - previewLoadStartedAt;
publishBuilderSceneTelemetry(telemetry);
}
const stateConnectStartedAt = performance.now();
const stateConnect = stateClient.connect(manifest.state);
const inferredEditableObjectIds = inferDefaultEditableObjectIds(manifest, { requireBody: Boolean(controlUrl) });
previewer.setDragOptions({
@ -1666,8 +1725,18 @@ async function loadResolvedManifest(manifest: SceneManifest): Promise<void> {
addActivity("activity.manifestLoaded", { count: manifest.objects.length }, "ok");
pendingCameraFit = true;
await stateConnect;
renderStats({ forceDiagnostics: true, samplePixels: true });
if (telemetry) {
telemetry.stateConnectMs = performance.now() - stateConnectStartedAt;
}
const statsStartedAt = performance.now();
renderStats({ forceDiagnostics: true });
if (telemetry) {
telemetry.statsRenderMs = performance.now() - statsStartedAt;
telemetry.loadResolvedManifestMs = performance.now() - startedAt;
publishBuilderSceneTelemetry(telemetry);
}
scheduleStatsRefresh();
schedulePixelProofRefresh(telemetry);
}
function resolveManifestUrls(manifest: SceneManifest, manifestUrl: string): SceneManifest {
@ -1864,6 +1933,32 @@ function runScheduledStatsRefresh(): void {
scheduleStatsRefresh();
}
function schedulePixelProofRefresh(telemetry?: BuilderSceneTelemetryEntry): void {
const serial = ++pixelProofRefreshSerial;
if (pixelProofRefreshHandle !== 0) {
window.clearTimeout(pixelProofRefreshHandle);
}
const scheduledAt = performance.now();
window.requestAnimationFrame(() => {
if (serial !== pixelProofRefreshSerial) {
return;
}
pixelProofRefreshHandle = window.setTimeout(() => {
if (serial !== pixelProofRefreshSerial) {
return;
}
pixelProofRefreshHandle = 0;
const proofStartedAt = performance.now();
renderStats({ forceDiagnostics: true, samplePixels: true });
if (telemetry && builderSceneTelemetry.current?.runId === telemetry.runId) {
telemetry.pixelProofWaitMs = proofStartedAt - scheduledAt;
telemetry.pixelProofMs = performance.now() - proofStartedAt;
publishBuilderSceneTelemetry(telemetry);
}
}, 0);
});
}
function renderFrameStatus(frame: PreviewFrame | undefined = latestFrame): void {
if (!frame) {
renderRunState();
@ -2779,6 +2874,7 @@ function currentRuntimeDiagnostics(
total: acceptanceTelemetry.current.total,
}
: undefined,
lastBuilderScene: builderSceneTelemetry.current,
};
}
@ -3635,74 +3731,112 @@ async function importBuilderConfigFile(file: File): Promise<void> {
}
async function buildAndLoadBuilderScene(savedStatusKey: MessageKey = "status.workspace.saved"): Promise<void> {
const startedAt = performance.now();
const scenePreset = selectedScenePreset();
const robotPreset = selectedRobotPreset();
const useBackendCompose = canUseBackendCompose(scenePreset);
const hasCustomUploadedProps = builderProps.some((item) => isCustomUploadedPropId(item.presetId));
const telemetry: BuilderSceneTelemetryEntry = {
schema: "motrixsim-web.builder-scene-telemetry.v1",
runId: ++builderSceneRunSerial,
startedAt: new Date().toISOString(),
statusKey: savedStatusKey,
sceneId: scenePreset.id,
robotId: robotPreset.id,
backendCompose: useBackendCompose,
propCount: builderProps.length,
};
builderSceneTelemetry.current = telemetry;
builderSceneTelemetry.history.push(telemetry);
builderSceneTelemetry.history = builderSceneTelemetry.history.slice(-20);
publishBuilderSceneTelemetry(telemetry);
saveBuilderDraft(savedStatusKey);
setText("#builder-status", t("status.builder.composing"));
const composedScene = useBackendCompose
? await composePhysicalScene(scenePreset, robotPreset)
: undefined;
const manifest = composedScene?.manifest ?? await createBuilderManifest(scenePreset, robotPreset, builderRobotPose);
if (!useBackendCompose) {
manifestInput.value = `builder://${scenePreset.id}+${robotPreset.id}`;
}
await loadResolvedManifest(manifest);
previewer.setRobotPose(builderRobotPose);
const editableObjectIds = new Set([
...inferDefaultEditableObjectIds(manifest, { requireBody: Boolean(controlUrl) }),
...builderProps.map((item) => item.id),
]);
previewer.setDragOptions({
editableObjectIds,
robotId: robotPreset.id,
robotPrefix: robotPreset.id === "none" ? undefined : `robot_${robotPreset.id}`,
onDrag: (event) => {
if (event.kind === "robot") {
builderRobotPose = event.source;
if (event.end) {
setWorkspaceStatus("status.workspace.saved");
saveBuilderDraft();
recordBuilderHistory();
}
} else if (event.kind === "prop") {
const prop = builderProps.find((candidate) => candidate.id === event.id || candidate.id === event.body);
if (prop) {
prop.position = event.source;
try {
let composedScene: ComposeSceneResult | undefined;
let manifest: SceneManifest;
if (useBackendCompose) {
const composeStartedAt = performance.now();
composedScene = await composePhysicalScene(scenePreset, robotPreset);
telemetry.composeMs = performance.now() - composeStartedAt;
telemetry.cached = composedScene.cached;
telemetry.resetApplied = composedScene.resetApplied;
manifest = composedScene.manifest;
} else {
const createManifestStartedAt = performance.now();
manifest = await createBuilderManifest(scenePreset, robotPreset, builderRobotPose);
telemetry.createManifestMs = performance.now() - createManifestStartedAt;
manifestInput.value = `builder://${scenePreset.id}+${robotPreset.id}`;
}
telemetry.objectCount = manifest.objects.length;
publishBuilderSceneTelemetry(telemetry);
await loadResolvedManifest(manifest, telemetry);
const dragSetupStartedAt = performance.now();
previewer.setRobotPose(builderRobotPose);
const editableObjectIds = new Set([
...inferDefaultEditableObjectIds(manifest, { requireBody: Boolean(controlUrl) }),
...builderProps.map((item) => item.id),
]);
previewer.setDragOptions({
editableObjectIds,
robotId: robotPreset.id,
robotPrefix: robotPreset.id === "none" ? undefined : `robot_${robotPreset.id}`,
onDrag: (event) => {
if (event.kind === "robot") {
builderRobotPose = event.source;
if (event.end) {
flushBuilderPanelRender();
recordBuilderHistory();
setWorkspaceStatus("status.workspace.saved");
saveBuilderDraft();
} else {
scheduleBuilderPanelRender();
recordBuilderHistory();
}
} else if (event.kind === "prop") {
const prop = builderProps.find((candidate) => candidate.id === event.id || candidate.id === event.body);
if (prop) {
prop.position = event.source;
if (event.end) {
flushBuilderPanelRender();
recordBuilderHistory();
saveBuilderDraft();
} else {
scheduleBuilderPanelRender();
}
}
if (event.end && event.body && controlUrl) {
void commitDraggedBodyPose(event);
return;
}
}
if (event.end && event.body && controlUrl) {
void commitDraggedBodyPose(event);
return;
if (event.end) {
setWorkspaceStatus("status.workspace.saved");
}
}
if (event.end) {
setWorkspaceStatus("status.workspace.saved");
}
},
});
const composeAlreadyInitializedRuntime = composedScene?.resetApplied === true || composedScene?.cached === false;
if (controlUrl && (robotPreset.id !== "none" || scenePreset.physical) && !composeAlreadyInitializedRuntime) {
await sendControl("reset");
},
});
telemetry.dragSetupMs = performance.now() - dragSetupStartedAt;
const composeAlreadyInitializedRuntime = composedScene?.resetApplied === true || composedScene?.cached === false;
if (controlUrl && (robotPreset.id !== "none" || scenePreset.physical) && !composeAlreadyInitializedRuntime) {
const resetStartedAt = performance.now();
await sendControl("reset");
telemetry.resetMs = performance.now() - resetStartedAt;
}
const modeKey: MessageKey = useBackendCompose
? "mode.physicalComposed"
: hasCustomUploadedProps
? "mode.visualComposition"
: robotPreset.id === "none" && scenePreset.physical
? "mode.physicalBackend"
: robotPreset.id === "none" && scenePreset.manifestUrl
? "mode.sourceBackend"
: "mode.visualComposition";
setText("#builder-status", t("status.builder.result", { mode: t(modeKey), count: manifest.objects.length }));
addActivity("activity.sceneBuilt", { mode: t(modeKey), count: manifest.objects.length }, "ok");
telemetry.totalMs = performance.now() - startedAt;
publishBuilderSceneTelemetry(telemetry);
} catch (error) {
telemetry.error = (error as Error).message;
telemetry.totalMs = performance.now() - startedAt;
publishBuilderSceneTelemetry(telemetry);
throw error;
}
const modeKey: MessageKey = useBackendCompose
? "mode.physicalComposed"
: hasCustomUploadedProps
? "mode.visualComposition"
: robotPreset.id === "none" && scenePreset.physical
? "mode.physicalBackend"
: robotPreset.id === "none" && scenePreset.manifestUrl
? "mode.sourceBackend"
: "mode.visualComposition";
setText("#builder-status", t("status.builder.result", { mode: t(modeKey), count: manifest.objects.length }));
addActivity("activity.sceneBuilt", { mode: t(modeKey), count: manifest.objects.length }, "ok");
}
interface ComposeSceneResponse {
@ -5034,6 +5168,7 @@ declare global {
getManifestUrl: () => string;
getControlUrl: () => string | undefined;
getRuntimeDiagnostics: () => RuntimeDiagnostics;
getBuilderSceneTelemetry: () => BuilderSceneTelemetryEntry | undefined;
capturePng: () => string;
getObjectScreenPoint: (id: string) => { x: number; y: number; visible: boolean } | undefined;
};
@ -5050,6 +5185,7 @@ window.__motrixPreviewDebug = {
getManifestUrl: () => manifestInput.value,
getControlUrl: () => controlUrl,
getRuntimeDiagnostics: () => currentRuntimeDiagnostics(),
getBuilderSceneTelemetry: () => builderSceneTelemetry.current,
capturePng: () => previewer.capturePng(),
getObjectScreenPoint: (id: string) => previewer.objectScreenPoint(id),
};