diff --git a/docs/product-readiness.md b/docs/product-readiness.md index 3528608..856302e 100644 --- a/docs/product-readiness.md +++ b/docs/product-readiness.md @@ -374,9 +374,11 @@ Scene evidence: - Scratch bounds transforms: pick-target bounds construction reuses `Box3`, `Matrix4`, and corner `Vector3` scratch objects for cached mesh bounds instead of allocating transformed bounds for every repeated shelf/product object. -- Scene-load render gating: large scene roots are batched into one Three.js - insertion after object preparation, and the render loop skips partial scene - frames while the batch is still loading. +- Progressive scene-load batching: large scene roots are mounted into the + Three.js scene in bounded batches during object preparation, while instanced + mesh batches still wait until their matrices and bounds are finalized. The + render loop only paints loading frames when a new batch is ready, so scene + import provides visible progress without returning to per-object scene churn. - Scene-build yielding: large scene object construction periodically yields to the browser event loop during load; the release gate checks `sceneBuildYieldCount` so this cannot silently regress back to one long main @@ -419,13 +421,13 @@ Scene evidence: Bundle evidence: - JavaScript chunks: `4` -- App entry chunk: `200.56 kB raw / 51.84 kB gzip` +- App entry chunk: `200.90 kB raw / 51.95 kB gzip` - Largest JavaScript gzip chunk: `140.96 KiB / 170.00 KiB` -- Total JavaScript gzip: `215.45 KiB / 230.00 KiB` +- Total JavaScript gzip: `215.56 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, `preserveDrawingBuffer=false`, `1` explicit readback render, shadows - `off`, hover picking throttled to `32ms`, `36` empty frames + `off`, hover picking throttled to `32ms`, `39` empty frames skipped, `703` static visual nodes frozen, `59` remaining mesh clones using pre-frozen source state, `627` repeated spin scans skipped, `568` repeated fixed mesh objects rendered as `16` instanced batches with `16` instanced @@ -434,21 +436,21 @@ Bundle evidence: cached, `51` mesh source assets retained, `24/51` mesh cache hit/miss in the primary large scene, `636` cached object bounds, `627` fast pick-target bounds from `51` cached source bounds, real hover proof `hoverProxy 1` with - cached bounds and `fallback 0`, with `0` camera-fit traversals, `1/84` - scene root batch insertion under the computed `84` root cap, `347` - partial render frames + cached bounds and `fallback 0`, with `0` camera-fit traversals, `4/84` + progressive scene root batches under the computed `84` root cap and `5` + batch cap, `259` no-op loading frames suppressed during the primary load, `26` browser event-loop yields during scene construction, active state payload `34/602` with `3` reduced frames and `4` incremental body-map merges, UI physics-profile cache `31/3` hit/miss, UI builder-profile cache `34/1` - hit/miss, UI text write gating `108/464` write/skip, text selector cache - `526/46` hit/miss, scratch bounds transforms `1263`, diagnostics panel - throttling `20/7` render/skip, `88/636` + hit/miss, UI text write gating `114/504` write/skip, text selector cache + `572/46` hit/miss, scratch bounds transforms `1263`, diagnostics panel + throttling `21/6` render/skip, `88/636` hover targets over cached bounds used for bounds-only ray tests, and a stable paused backend state cache reported `manual roots 636 updates 67` with `state apply 0/skip 67`. - Mesh cache lifecycle evidence: the Scene Builder compose switch reported - cumulative `1203/51` mesh cache hit/miss with `51` retained geometries and + cumulative `99/51` mesh cache hit/miss with `51` retained geometries and `17` retained materials, avoiding repeated parser/network work for duplicate shelf and product assets. - Active-state gate: `browser-large-scene-performance-mode` now checks @@ -494,10 +496,10 @@ Bundle evidence: `fallback=0`, proving hover highlight uses the pruned cached bounds list instead of traversing the visual root. The current proof hits the shelf fixture at `point=0.35,0.50` with `固定物理体: geom_64`. -- Scene-load batching gate: `browser-large-scene-performance-mode` now checks - `scene batches 1/84`, `maxSceneRoots=84`, and `yields 26`, proving fixed - instanced object roots stay detached from the Three scene while object - construction still yields to the browser event loop during load. +- Progressive scene-load batching gate: `browser-large-scene-performance-mode` + now checks `scene batches 4/84`, `maxSceneRoots=84`, `maxBatches=5`, and + `yields 26`, proving large scene import mounts bounded visible batches while + repeated fixed inventory still renders through finalized instanced batches. - Resource lifecycle on a real Scene Builder compose switch: released `1` geometry, `10` materials, and `2` textures from non-retained scene graph resources while preserving cached mesh sources. @@ -518,8 +520,8 @@ Control evidence: - Dynamic composed object drop: `0.48012m`. - Static shelf anchor stability: `max drift 0.00000m` after a 2500 ms resume window. -- Resume backend state: `58ms paused=false` -- Resume visible UI state: `60ms` +- Resume backend state: `61ms paused=false` +- Resume visible UI state: `62ms` - Pause backend state: `50ms paused=true` - Pause visible UI state: `39ms` - Desktop acceptance wait: `1243ms` total, product telemetry `0ms` @@ -527,11 +529,11 @@ Control evidence: - Runtime diagnostics panel: `state=http://127.0.0.1:18090/state`, `control=http://127.0.0.1:18090/control`, - `latency=响应 38 ms / 确认 38 ms / 可见 39 ms`, + `latency=响应 39 ms / 确认 39 ms / 可见 39 ms`, `acceptanceLatency=0 ms / 11-0-0`, `binding=635/636; 4/568`, `builderPhysics=已添加物体 4: 后端动态 4 / 仅视觉 0`, - `renderPerformance=large-scene; target 45 fps; actual 0.9 fps; dpr 1.00; buffer preserved false; readback renders 1; shadows off; skipped 36; hover 32ms; frozen 703 prefrozen 59 spinSkip 627; instanced 568/16/16 matrices 568 cull 16 static 16; manual roots 636 updates 67; primitive geometries 7; mesh cache 51 sources 24/51 hit/miss retained 51g/17m; bounds cache 636 fast 627 scratch 1263 source 51 hoverProxy 1 cached 1/fallback 0 camera traversals 0; scene batches 1/84 suppressed 347 yields 26; state payload 34/602 reduced 3 incremental 4; ui cache physics 31/3 builder 34/1 text 112/494 selector 560/46 diagnostics 21/6; pick targets 88/636; state apply 0/skip 67; unchanged frames 1; released 0g/0m/0t`. + `renderPerformance=large-scene; target 45 fps; actual 0.8 fps; dpr 1.00; buffer preserved false; readback renders 1; shadows off; skipped 39; hover 32ms; frozen 703 prefrozen 59 spinSkip 627; instanced 568/16/16 matrices 568 cull 16 static 16; manual roots 636 updates 67; primitive geometries 7; mesh cache 51 sources 24/51 hit/miss retained 51g/17m; bounds cache 636 fast 627 scratch 1263 source 51 hoverProxy 1 cached 1/fallback 0 camera traversals 0; scene batches 4/84 suppressed 259 yields 26; state payload 34/602 reduced 3 incremental 4; ui cache physics 31/3 builder 34/1 text 112/494 selector 560/46 diagnostics 21/6; pick targets 88/636; state apply 0/skip 67; unchanged frames 1; released 0g/0m/0t`. - Evidence screenshot artifacts: `builder page; share page; import page; visual-only boundary canvas; desktop canvas; debug PNG; mobile canvas` - Evidence export artifacts: diff --git a/scripts/product-readiness-gate.mjs b/scripts/product-readiness-gate.mjs index 14a1284..bb1baae 100644 --- a/scripts/product-readiness-gate.mjs +++ b/scripts/product-readiness-gate.mjs @@ -1655,6 +1655,7 @@ async function verifyBrowser() { - (renderPerformance.instancedMeshObjectCount ?? 0) + (renderPerformance.instancedMeshBatchCount ?? 0), ); + const maxProgressiveSceneRootBatches = Math.max(2, Math.ceil(maxInstancedSceneRoots / 24) + 1); const maxHoverPickTargets = Math.max(100, Math.ceil(objectCount * 0.18)); check( "browser-large-scene-performance-mode", @@ -1693,7 +1694,8 @@ async function verifyBrowser() { && (renderPerformance.statePayloadBodyCount ?? Number.POSITIVE_INFINITY) < (renderPerformance.mergedBodyStateCount ?? 0) && (renderPerformance.mergedBodyStateCount ?? 0) >= thresholds.minBodyBindings && (renderPerformance.batchedSceneRootCount ?? Number.POSITIVE_INFINITY) <= maxInstancedSceneRoots - && (renderPerformance.sceneRootBatchCount ?? 0) === 1 + && (renderPerformance.sceneRootBatchCount ?? 0) > 1 + && (renderPerformance.sceneRootBatchCount ?? Number.POSITIVE_INFINITY) <= maxProgressiveSceneRootBatches && (renderPerformance.objectPhysicsProfileCacheHitCount ?? 0) > 0 && (renderPerformance.builderPhysicsProfileCacheHitCount ?? 0) > 0 && (renderPerformance.textWriteSkipCount ?? 0) > 0 @@ -1707,7 +1709,7 @@ async function verifyBrowser() { && (renderPerformance.hoverPickTargetCount ?? Number.POSITIVE_INFINITY) <= maxHoverPickTargets && (renderPerformance.skippedBodyStateCount ?? 0) > 0 && desktopStats.diagnostics.renderPerformance.includes("large-scene"), - `mode=${renderPerformance.largeSceneMode} fps=${renderPerformance.targetRenderFps ?? "-"} dpr=${renderPerformance.renderPixelRatio ?? "-"} buffer=${renderPerformance.preserveDrawingBufferEnabled} readback=${renderPerformance.readbackRenderCount ?? "-"} shadows=${renderPerformance.shadowsEnabled} hover=${renderPerformance.hoverPickIntervalMs ?? "-"} skipped=${renderPerformance.renderSkipCount ?? "-"} frozen=${renderPerformance.frozenStaticObjectCount ?? "-"} prefrozen=${renderPerformance.preFrozenMeshCloneCount ?? "-"} spinSkip=${renderPerformance.spinningScanSkippedCount ?? "-"} instanced=${renderPerformance.instancedMeshObjectCount ?? "-"}/${renderPerformance.instancedMeshBatchCount ?? "-"}/${renderPerformance.instancedMeshDrawCount ?? "-"} matrices=${renderPerformance.instancedMeshMatrixUpdateCount ?? "-"} cull=${renderPerformance.instancedMeshFrustumCulledCount ?? "-"} static=${renderPerformance.instancedMeshStaticMatrixCount ?? "-"} manualRoots=${renderPerformance.manualMatrixRootCount ?? "-"} manualUpdates=${renderPerformance.manualMatrixUpdateCount ?? "-"} primitiveGeometries=${renderPerformance.primitiveGeometryCount ?? "-"} meshCache=${renderPerformance.meshCacheSourceCount ?? "-"} hit=${renderPerformance.meshCacheHitCount ?? "-"} miss=${renderPerformance.meshCacheMissCount ?? "-"} retained=${renderPerformance.retainedMeshGeometryCount ?? "-"}g/${renderPerformance.retainedMeshMaterialCount ?? "-"}m bounds=${renderPerformance.sceneObjectBoundsCount ?? "-"} fast=${renderPerformance.fastPickProxyBoundsCount ?? "-"} scratch=${renderPerformance.pickBoundsScratchTransformCount ?? "-"} source=${renderPerformance.meshSourceBoundsCount ?? "-"} hoverProxy=${renderPerformance.hoverProxyBoundsHitCount ?? "-"} cached=${renderPerformance.hoverCachedBoundsHitCount ?? "-"}/fallback=${renderPerformance.hoverRootBoundsFallbackCount ?? "-"} cameraTraversals=${renderPerformance.cameraFitTraversalCount ?? "-"} sceneBatches=${renderPerformance.sceneRootBatchCount ?? "-"}/${renderPerformance.batchedSceneRootCount ?? "-"} maxSceneRoots=${maxInstancedSceneRoots} suppressed=${renderPerformance.sceneLoadSuppressedRenderCount ?? "-"} yields=${renderPerformance.sceneBuildYieldCount ?? "-"} statePayload=${renderPerformance.statePayloadBodyCount ?? "-"}/${renderPerformance.mergedBodyStateCount ?? "-"} reduced=${renderPerformance.reducedStateFrameCount ?? "-"} incremental=${renderPerformance.incrementalBodyMergeCount ?? "-"} uiCache=physics ${renderPerformance.objectPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.objectPhysicsProfileCacheMissCount ?? "-"} builder ${renderPerformance.builderPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.builderPhysicsProfileCacheMissCount ?? "-"} text ${renderPerformance.textWriteCount ?? "-"}/${renderPerformance.textWriteSkipCount ?? "-"} selector ${renderPerformance.textSelectorCacheHitCount ?? "-"}/${renderPerformance.textSelectorCacheMissCount ?? "-"} diagnostics ${renderPerformance.diagnosticsPanelRenderCount ?? "-"}/${renderPerformance.diagnosticsPanelSkipCount ?? "-"} pickTargets=${renderPerformance.hoverPickTargetCount ?? "-"}/${renderPerformance.pickProxyCount ?? "-"} hoverBudget=${maxHoverPickTargets} stateApply=${renderPerformance.appliedBodyStateCount ?? "-"}/skip=${renderPerformance.skippedBodyStateCount ?? "-"} unchanged=${renderPerformance.unchangedFrameCount ?? "-"} released=${renderPerformance.releasedGeometryCount ?? "-"}g/${renderPerformance.releasedMaterialCount ?? "-"}m/${renderPerformance.releasedTextureCount ?? "-"}t; ${desktopStats.diagnostics.renderPerformance}`, + `mode=${renderPerformance.largeSceneMode} fps=${renderPerformance.targetRenderFps ?? "-"} dpr=${renderPerformance.renderPixelRatio ?? "-"} buffer=${renderPerformance.preserveDrawingBufferEnabled} readback=${renderPerformance.readbackRenderCount ?? "-"} shadows=${renderPerformance.shadowsEnabled} hover=${renderPerformance.hoverPickIntervalMs ?? "-"} skipped=${renderPerformance.renderSkipCount ?? "-"} frozen=${renderPerformance.frozenStaticObjectCount ?? "-"} prefrozen=${renderPerformance.preFrozenMeshCloneCount ?? "-"} spinSkip=${renderPerformance.spinningScanSkippedCount ?? "-"} instanced=${renderPerformance.instancedMeshObjectCount ?? "-"}/${renderPerformance.instancedMeshBatchCount ?? "-"}/${renderPerformance.instancedMeshDrawCount ?? "-"} matrices=${renderPerformance.instancedMeshMatrixUpdateCount ?? "-"} cull=${renderPerformance.instancedMeshFrustumCulledCount ?? "-"} static=${renderPerformance.instancedMeshStaticMatrixCount ?? "-"} manualRoots=${renderPerformance.manualMatrixRootCount ?? "-"} manualUpdates=${renderPerformance.manualMatrixUpdateCount ?? "-"} primitiveGeometries=${renderPerformance.primitiveGeometryCount ?? "-"} meshCache=${renderPerformance.meshCacheSourceCount ?? "-"} hit=${renderPerformance.meshCacheHitCount ?? "-"} miss=${renderPerformance.meshCacheMissCount ?? "-"} retained=${renderPerformance.retainedMeshGeometryCount ?? "-"}g/${renderPerformance.retainedMeshMaterialCount ?? "-"}m bounds=${renderPerformance.sceneObjectBoundsCount ?? "-"} fast=${renderPerformance.fastPickProxyBoundsCount ?? "-"} scratch=${renderPerformance.pickBoundsScratchTransformCount ?? "-"} source=${renderPerformance.meshSourceBoundsCount ?? "-"} hoverProxy=${renderPerformance.hoverProxyBoundsHitCount ?? "-"} cached=${renderPerformance.hoverCachedBoundsHitCount ?? "-"}/fallback=${renderPerformance.hoverRootBoundsFallbackCount ?? "-"} cameraTraversals=${renderPerformance.cameraFitTraversalCount ?? "-"} sceneBatches=${renderPerformance.sceneRootBatchCount ?? "-"}/${renderPerformance.batchedSceneRootCount ?? "-"} maxSceneRoots=${maxInstancedSceneRoots} maxBatches=${maxProgressiveSceneRootBatches} suppressed=${renderPerformance.sceneLoadSuppressedRenderCount ?? "-"} yields=${renderPerformance.sceneBuildYieldCount ?? "-"} statePayload=${renderPerformance.statePayloadBodyCount ?? "-"}/${renderPerformance.mergedBodyStateCount ?? "-"} reduced=${renderPerformance.reducedStateFrameCount ?? "-"} incremental=${renderPerformance.incrementalBodyMergeCount ?? "-"} uiCache=physics ${renderPerformance.objectPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.objectPhysicsProfileCacheMissCount ?? "-"} builder ${renderPerformance.builderPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.builderPhysicsProfileCacheMissCount ?? "-"} text ${renderPerformance.textWriteCount ?? "-"}/${renderPerformance.textWriteSkipCount ?? "-"} selector ${renderPerformance.textSelectorCacheHitCount ?? "-"}/${renderPerformance.textSelectorCacheMissCount ?? "-"} diagnostics ${renderPerformance.diagnosticsPanelRenderCount ?? "-"}/${renderPerformance.diagnosticsPanelSkipCount ?? "-"} pickTargets=${renderPerformance.hoverPickTargetCount ?? "-"}/${renderPerformance.pickProxyCount ?? "-"} hoverBudget=${maxHoverPickTargets} stateApply=${renderPerformance.appliedBodyStateCount ?? "-"}/skip=${renderPerformance.skippedBodyStateCount ?? "-"} unchanged=${renderPerformance.unchangedFrameCount ?? "-"} released=${renderPerformance.releasedGeometryCount ?? "-"}g/${renderPerformance.releasedMaterialCount ?? "-"}m/${renderPerformance.releasedTextureCount ?? "-"}t; ${desktopStats.diagnostics.renderPerformance}`, ); check( "browser-debug-capture-png", diff --git a/src/preview/UniversalPreviewer.ts b/src/preview/UniversalPreviewer.ts index a2d20d3..b676015 100644 --- a/src/preview/UniversalPreviewer.ts +++ b/src/preview/UniversalPreviewer.ts @@ -18,6 +18,9 @@ import type { } from "../types"; import { CoordinateConverter } from "../utils/coordinates"; +const LARGE_SCENE_ROOT_BATCH_SIZE = 24; +const LARGE_SCENE_LOADING_RENDER_INTERVAL_MS = 1000 / 20; + type InteractionMode = "idle" | "inspect" | "hover" | "dragging"; type PointerLikeEvent = PointerEvent | MouseEvent; @@ -56,6 +59,11 @@ interface PickBoundsTarget { worldBounds: THREE.Box3; } +interface SceneBuildRoots { + visible: THREE.Object3D[]; + instanced: THREE.Object3D[]; +} + export interface DragTargetPose { id: string; source: [number, number, number]; @@ -629,18 +637,21 @@ export class UniversalPreviewer { private animate = (): void => { this.animationHandle = requestAnimationFrame(this.animate); - if (this.sceneLoadInProgress) { + const now = performance.now(); + if (this.sceneLoadInProgress && !this.renderDirty) { this.sceneLoadSuppressedRenderCount += 1; return; } - if (performance.now() < this.renderSuspendedUntil) { + if (now < this.renderSuspendedUntil) { return; } - const now = performance.now(); const controlsChanged = this.controls.update(); const focusChanged = this.updateFocusMarker(); const spinChanged = this.updateSpinningObjects(this.clock.getElapsedTime()); - const enoughTimeElapsed = this.targetRenderIntervalMs <= 0 || now - this.lastRenderAt >= this.targetRenderIntervalMs; + const renderIntervalMs = this.sceneLoadInProgress + ? Math.max(this.targetRenderIntervalMs, LARGE_SCENE_LOADING_RENDER_INTERVAL_MS) + : this.targetRenderIntervalMs; + const enoughTimeElapsed = renderIntervalMs <= 0 || now - this.lastRenderAt >= renderIntervalMs; if (!enoughTimeElapsed || (!this.renderDirty && !controlsChanged && !focusChanged && !spinChanged)) { this.renderSkipCount += 1; return; @@ -1845,7 +1856,7 @@ export class UniversalPreviewer { object: PreviewObject, root: THREE.Object3D, token: number, - sceneRoots: THREE.Object3D[], + sceneRoots: SceneBuildRoots, ): Promise<{ local: THREE.Object3D } | undefined> { if (!this.isInstancedMeshCandidate(object)) { return undefined; @@ -1890,7 +1901,7 @@ export class UniversalPreviewer { geometry: MeshGeometry, materialId: string | undefined, key: string, - sceneRoots: THREE.Object3D[], + sceneRoots: SceneBuildRoots, ): Promise { const pending = this.instancedMeshBatches.get(key); if (pending) { @@ -1901,7 +1912,7 @@ export class UniversalPreviewer { .then(({ source }) => this.createInstancedMeshBatch(key, source, capacity)); this.instancedMeshBatches.set(key, created); const batch = await created; - sceneRoots.push(batch.root); + sceneRoots.instanced.push(batch.root); return batch; } @@ -1972,7 +1983,7 @@ export class UniversalPreviewer { } } - private async addObject(object: PreviewObject, token: number, sceneRoots: THREE.Object3D[]): Promise { + private async addObject(object: PreviewObject, token: number, sceneRoots: SceneBuildRoots): Promise { const root = new THREE.Group(); root.name = object.name ?? object.id; root.visible = object.visible !== false; @@ -2015,7 +2026,7 @@ export class UniversalPreviewer { } this.freezeObjectRootMatrix(root); if (!instancedVisual) { - sceneRoots.push(root); + sceneRoots.visible.push(root); } this.registerSpinningObjects(root, visual); if (instancedVisual) { @@ -2055,7 +2066,10 @@ export class UniversalPreviewer { private async addObjects(objects: PreviewObject[], token: number): Promise { let nextIndex = 0; let builtSinceYield = 0; - const sceneRoots: THREE.Object3D[] = []; + const sceneRoots: SceneBuildRoots = { + visible: [], + instanced: [], + }; const workerCount = Math.min(24, Math.max(1, objects.length)); const workers = Array.from({ length: workerCount }, async () => { while (token === this.loadToken) { @@ -2067,6 +2081,7 @@ export class UniversalPreviewer { } await this.addObject(object, token, sceneRoots); builtSinceYield += 1; + this.flushSceneRootBatch(sceneRoots.visible); if (this.largeSceneMode && builtSinceYield >= 24) { builtSinceYield = 0; await this.yieldDuringSceneBuild(token); @@ -2077,18 +2092,29 @@ export class UniversalPreviewer { if (token !== this.loadToken) { return; } + this.flushSceneRootBatch(sceneRoots.visible, true); await this.finalizeInstancedMeshBatches(); if (token !== this.loadToken) { return; } - if (sceneRoots.length > 0) { - this.root.add(...sceneRoots); - this.batchedSceneRootCount += sceneRoots.length; - this.sceneRootBatchCount += 1; - } + this.flushSceneRootBatch(sceneRoots.instanced, true); this.refreshEditablePickTargets(); } + private flushSceneRootBatch(sceneRoots: THREE.Object3D[], force = false): void { + if (sceneRoots.length === 0) { + return; + } + if (!force && sceneRoots.length < LARGE_SCENE_ROOT_BATCH_SIZE) { + return; + } + const batch = sceneRoots.splice(0, sceneRoots.length); + this.root.add(...batch); + this.batchedSceneRootCount += batch.length; + this.sceneRootBatchCount += 1; + this.markRenderDirty(); + } + private async yieldDuringSceneBuild(token: number): Promise { this.sceneBuildYieldCount += 1; await new Promise((resolve) => window.setTimeout(resolve, 0));