diff --git a/docs/product-readiness.md b/docs/product-readiness.md index e8cc083..0714262 100644 --- a/docs/product-readiness.md +++ b/docs/product-readiness.md @@ -136,6 +136,9 @@ The product acceptance gate must pass with zero failures. It checks: passing as real collision physics. - Runtime diagnostics panel with manifest, state, control, latency, binding, and asset health evidence. +- Runtime resource-lifecycle diagnostics, proving scene switches release old + geometries, materials, and textures instead of accumulating stale GPU + resources. - Nonblank WebGL rendering. - Expected object, mesh, and body binding counts. - Product-owned acceptance telemetry in the diagnostics panel. @@ -196,7 +199,7 @@ evidence to a code state: Representative product gate baseline for the current thresholds: -- Result: `42 passed / 0 warned / 0 failed` +- Result: `43 passed / 0 warned / 0 failed` - Frontend mode: `preview` for release handoff through `npm run product:release-check`. - Fail on warning: `true` for release handoff. @@ -307,31 +310,33 @@ Scene evidence: Bundle evidence: - JavaScript chunks: `4` -- App entry chunk: `173.17 kB raw / 45.26 KiB gzip` +- App entry chunk: `174.93 kB raw / 45.75 KiB gzip` - Largest JavaScript gzip chunk: `141.04 KiB / 170.00 KiB` -- Total JavaScript gzip: `209.10 KiB / 230.00 KiB` +- Total JavaScript gzip: `209.58 KiB / 230.00 KiB` - Large-scene performance mode: `large-scene`, target `45 fps`, actual idle render rate `0.8 fps`, DPR cap observed at `1.00` in release - gate, shadows `off`, hover picking throttled to `32ms`, `304` empty frames + gate, shadows `off`, hover picking throttled to `32ms`, `301` empty frames skipped, `1839` static visual nodes frozen, and `7` primitive geometry shapes cached. +- Resource lifecycle on a real Scene Builder compose switch: released `52` + geometries, `27` materials, and `17` textures from the replaced scene graph. Control evidence: -- Compose endpoint: `273ms`, `4/4` composed object bodies synced. -- Scene Builder UI compose: representative run `4067ms` end to end with real +- Compose endpoint: `269ms`, `4/4` composed object bodies synced. +- Scene Builder UI compose: representative run `4206ms` end to end with real backend diagnostics. -- Composed object body edit: `59ms`. -- Fixed inventory edit rejection: `62ms`. +- Composed object body edit: `53ms`. +- Fixed inventory edit rejection: `57ms`. - Dynamic composed object drop: `0.48012m`. - Static shelf anchor stability: `max drift 0.00000m` after a 2500 ms resume window. -- Resume backend state: `226ms paused=false` -- Resume visible UI state: `58ms` -- Pause backend state: `49ms paused=true` -- Pause visible UI state: `40ms` -- Desktop acceptance wait: `5ms` total, product telemetry `0ms` -- Mobile acceptance wait: `358ms` total, product telemetry `0ms` +- Resume backend state: `59ms paused=false` +- Resume visible UI state: `46ms` +- Pause backend state: `235ms paused=true` +- Pause visible UI state: `52ms` +- Desktop acceptance wait: `2ms` total, product telemetry `0ms` +- Mobile acceptance wait: `429ms` total, product telemetry `2ms` - Runtime diagnostics panel: `state=http://127.0.0.1:18090/state`, `control=http://127.0.0.1:18090/control`, @@ -339,7 +344,7 @@ Control evidence: `acceptanceLatency=0 ms / 11-0-0`, `binding=635/636; 4/568`, `builderPhysics=已添加物体 4: 后端动态 4 / 仅视觉 0`, - `renderPerformance=large-scene; target 45 fps; actual 0.8 fps; dpr 1.00; shadows off; skipped 304; hover 32ms; frozen 1839; primitive geometries 7`. + `renderPerformance=large-scene; target 45 fps; actual 0.8 fps; dpr 1.00; shadows off; skipped 301; hover 32ms; frozen 1839; primitive geometries 7; released 0g/0m/0t`. - Evidence screenshot artifacts: `builder page; share page; import page; visual-only boundary canvas; desktop canvas; mobile canvas` - Evidence export artifacts: diff --git a/scripts/product-readiness-gate.mjs b/scripts/product-readiness-gate.mjs index 455cb92..9be7eab 100644 --- a/scripts/product-readiness-gate.mjs +++ b/scripts/product-readiness-gate.mjs @@ -629,6 +629,9 @@ async function readBrowserStats(page) { hoverPickIntervalMs: numberData("hoverPickIntervalMs"), frozenStaticObjectCount: numberData("frozenStaticObjectCount"), primitiveGeometryCount: numberData("primitiveGeometryCount"), + releasedGeometryCount: numberData("releasedGeometryCount"), + releasedMaterialCount: numberData("releasedMaterialCount"), + releasedTextureCount: numberData("releasedTextureCount"), }, diagnostics: { manifestUrl: text("#diag-manifest-url"), @@ -1004,6 +1007,7 @@ async function runBuilderPhysicalCompose(page) { builderStatus: stats.builderStatus, summaryProps: stats.summaryProps, physics: stats.physics, + renderPerformance: stats.renderPerformance, diagnostics: stats.diagnostics, viewport: stats.canvas ? { @@ -1515,7 +1519,16 @@ async function verifyBrowser() { && (renderPerformance.frozenStaticObjectCount ?? 0) >= 500 && (renderPerformance.primitiveGeometryCount ?? 0) > 0 && desktopStats.diagnostics.renderPerformance.includes("large-scene"), - `mode=${renderPerformance.largeSceneMode} fps=${renderPerformance.targetRenderFps ?? "-"} dpr=${renderPerformance.renderPixelRatio ?? "-"} shadows=${renderPerformance.shadowsEnabled} hover=${renderPerformance.hoverPickIntervalMs ?? "-"} skipped=${renderPerformance.renderSkipCount ?? "-"} frozen=${renderPerformance.frozenStaticObjectCount ?? "-"} primitiveGeometries=${renderPerformance.primitiveGeometryCount ?? "-"}; ${desktopStats.diagnostics.renderPerformance}`, + `mode=${renderPerformance.largeSceneMode} fps=${renderPerformance.targetRenderFps ?? "-"} dpr=${renderPerformance.renderPixelRatio ?? "-"} shadows=${renderPerformance.shadowsEnabled} hover=${renderPerformance.hoverPickIntervalMs ?? "-"} skipped=${renderPerformance.renderSkipCount ?? "-"} frozen=${renderPerformance.frozenStaticObjectCount ?? "-"} primitiveGeometries=${renderPerformance.primitiveGeometryCount ?? "-"} released=${renderPerformance.releasedGeometryCount ?? "-"}g/${renderPerformance.releasedMaterialCount ?? "-"}m/${renderPerformance.releasedTextureCount ?? "-"}t; ${desktopStats.diagnostics.renderPerformance}`, + ); + const builderRelease = builderCompose.renderPerformance ?? {}; + check( + "browser-resource-lifecycle", + (builderRelease.releasedGeometryCount ?? 0) > 0 + && (builderRelease.releasedMaterialCount ?? 0) > 0 + && (builderRelease.releasedTextureCount ?? 0) > 0 + && builderCompose.diagnostics.renderPerformance.includes("released"), + `released=${builderRelease.releasedGeometryCount ?? "-"}g/${builderRelease.releasedMaterialCount ?? "-"}m/${builderRelease.releasedTextureCount ?? "-"}t; ${builderCompose.diagnostics.renderPerformance}`, ); check( "browser-builder-compose-ui", diff --git a/src/main.ts b/src/main.ts index e2002ab..f8a6269 100644 --- a/src/main.ts +++ b/src/main.ts @@ -169,6 +169,9 @@ interface RuntimeDiagnostics { hoverPickIntervalMs: number; frozenStaticObjectCount: number; primitiveGeometryCount: number; + releasedGeometryCount: number; + releasedMaterialCount: number; + releasedTextureCount: number; editableGroups: number; groupedObjects: number; meshes: number; @@ -2412,6 +2415,9 @@ function currentRuntimeDiagnostics(): RuntimeDiagnostics { hoverPickIntervalMs: stats.hoverPickIntervalMs, frozenStaticObjectCount: stats.frozenStaticObjectCount, primitiveGeometryCount: stats.primitiveGeometryCount, + releasedGeometryCount: stats.releasedGeometryCount, + releasedMaterialCount: stats.releasedMaterialCount, + releasedTextureCount: stats.releasedTextureCount, editableGroups: stats.editableGroupCount, groupedObjects: stats.groupedObjectCount, meshes: stats.loadedMeshCount, @@ -2470,7 +2476,7 @@ function currentDiagnosticsReport(): string { function renderPerformanceLabel(stats: RuntimeDiagnostics["stats"]): string { const mode = stats.largeSceneMode ? "large-scene" : "standard"; const shadows = stats.shadowsEnabled ? "shadows on" : "shadows off"; - return `${mode}; target ${stats.targetRenderFps} fps; actual ${stats.actualRenderFps.toFixed(1)} fps; dpr ${stats.renderPixelRatio.toFixed(2)}; ${shadows}; skipped ${stats.renderSkipCount}; hover ${stats.hoverPickIntervalMs}ms; frozen ${stats.frozenStaticObjectCount}; primitive geometries ${stats.primitiveGeometryCount}`; + return `${mode}; target ${stats.targetRenderFps} fps; actual ${stats.actualRenderFps.toFixed(1)} fps; dpr ${stats.renderPixelRatio.toFixed(2)}; ${shadows}; skipped ${stats.renderSkipCount}; hover ${stats.hoverPickIntervalMs}ms; frozen ${stats.frozenStaticObjectCount}; primitive geometries ${stats.primitiveGeometryCount}; released ${stats.releasedGeometryCount}g/${stats.releasedMaterialCount}m/${stats.releasedTextureCount}t`; } function renderDiagnosticsPanel(): void { @@ -2495,6 +2501,9 @@ function renderDiagnosticsPanel(): void { data.hoverPickIntervalMs = String(diagnostics.stats.hoverPickIntervalMs); data.frozenStaticObjectCount = String(diagnostics.stats.frozenStaticObjectCount); data.primitiveGeometryCount = String(diagnostics.stats.primitiveGeometryCount); + data.releasedGeometryCount = String(diagnostics.stats.releasedGeometryCount); + data.releasedMaterialCount = String(diagnostics.stats.releasedMaterialCount); + data.releasedTextureCount = String(diagnostics.stats.releasedTextureCount); setText("#diag-manifest-url", diagnostics.manifestUrl); setText("#diag-state-url", endpointLabel(diagnostics.stateUrl)); setText("#diag-control-url", endpointLabel(diagnostics.controlUrl)); diff --git a/src/preview/UniversalPreviewer.ts b/src/preview/UniversalPreviewer.ts index 11758b6..8ca51ad 100644 --- a/src/preview/UniversalPreviewer.ts +++ b/src/preview/UniversalPreviewer.ts @@ -128,6 +128,9 @@ export class UniversalPreviewer { private renderWindowFrameCount = 0; private measuredRenderFps = 0; private frozenStaticObjectCount = 0; + private releasedGeometryCount = 0; + private releasedMaterialCount = 0; + private releasedTextureCount = 0; private loadedMeshCount = 0; private fallbackCount = 0; private lastPixelSampleAt = 0; @@ -330,6 +333,9 @@ export class UniversalPreviewer { hoverPickIntervalMs: this.hoverPickIntervalMs, frozenStaticObjectCount: this.frozenStaticObjectCount, primitiveGeometryCount: this.primitiveGeometryCache.size, + releasedGeometryCount: this.releasedGeometryCount, + releasedMaterialCount: this.releasedMaterialCount, + releasedTextureCount: this.releasedTextureCount, loadedMeshCount: this.loadedMeshCount, fallbackCount: this.fallbackCount, editableGroupCount: this.editableGroups.size, @@ -789,6 +795,7 @@ export class UniversalPreviewer { } private clearScene(): void { + this.disposeSceneGraphResources(this.root); this.root.clear(); this.disposeMaterials(); this.meshCache.clear(); @@ -820,15 +827,96 @@ export class UniversalPreviewer { this.markRenderDirty(); } + private disposeSceneGraphResources(root: THREE.Object3D): void { + const cachedPrimitiveGeometries = new Set(this.primitiveGeometryCache.values()); + const ownedMaterials = new Set(this.materials.values()); + const disposedGeometries = new Set(); + const disposedMaterials = new Set(); + const disposedTextures = new Set(); + root.traverse((child) => { + const renderable = child as THREE.Object3D & { + geometry?: THREE.BufferGeometry; + material?: THREE.Material | THREE.Material[]; + }; + const geometry = renderable.geometry; + if (geometry instanceof THREE.BufferGeometry && !cachedPrimitiveGeometries.has(geometry) && !disposedGeometries.has(geometry)) { + geometry.dispose(); + disposedGeometries.add(geometry); + this.releasedGeometryCount += 1; + } + if (!renderable.material) { + return; + } + for (const material of this.materialList(renderable.material)) { + if (!ownedMaterials.has(material) && !disposedMaterials.has(material)) { + this.disposeMaterial(material, disposedTextures); + disposedMaterials.add(material); + } + } + }); + } + private disposeMaterials(): void { + const disposedTextures = new Set(); for (const material of this.materials.values()) { - const mapped = material as THREE.MeshStandardMaterial; - mapped.map?.dispose(); - material.dispose(); + this.disposeMaterial(material, disposedTextures); } this.materials.clear(); } + private disposeMaterial(material: THREE.Material, disposedTextures: Set): void { + for (const texture of this.materialTextures(material)) { + if (!disposedTextures.has(texture)) { + texture.dispose(); + disposedTextures.add(texture); + this.releasedTextureCount += 1; + } + } + material.dispose(); + this.releasedMaterialCount += 1; + } + + private materialList(material: THREE.Material | THREE.Material[]): THREE.Material[] { + return Array.isArray(material) ? material : [material]; + } + + private materialTextures(material: THREE.Material): THREE.Texture[] { + const textureKeys = [ + "alphaMap", + "aoMap", + "bumpMap", + "clearcoatMap", + "clearcoatNormalMap", + "clearcoatRoughnessMap", + "displacementMap", + "emissiveMap", + "envMap", + "iridescenceMap", + "iridescenceThicknessMap", + "lightMap", + "map", + "metalnessMap", + "normalMap", + "roughnessMap", + "sheenColorMap", + "sheenRoughnessMap", + "specularColorMap", + "specularIntensityMap", + "specularMap", + "thicknessMap", + "transmissionMap", + ] as const; + const textures: THREE.Texture[] = []; + const fields = material as unknown as Record; + for (const key of textureKeys) { + const value = fields[key]; + if (value instanceof THREE.Texture) { + textures.push(value); + } + } + return textures; + } + private isRobotManifestObject(id: string): boolean { if (!this.dragOptions.robotPrefix) { return false; diff --git a/src/types.ts b/src/types.ts index e49cca7..af238c0 100644 --- a/src/types.ts +++ b/src/types.ts @@ -197,6 +197,9 @@ export interface RendererStats { hoverPickIntervalMs: number; frozenStaticObjectCount: number; primitiveGeometryCount: number; + releasedGeometryCount: number; + releasedMaterialCount: number; + releasedTextureCount: number; loadedMeshCount: number; fallbackCount: number; editableGroupCount: number;