54 KiB
MotrixSim Web Product Readiness
This document is the handoff checklist for the real backend product path. It is written for demos, acceptance testing, and day-to-day development. The goal is to prove that the browser is previewing and controlling a real MotrixSim runtime, not a mock, screenshot, or front-end-only animation.
Architecture
flowchart LR
Browser["Browser UI\nScene Builder + Three.js"] --> Manifest["GET /manifest\nreal MJCF scene manifest"]
Browser --> State["GET /state\nfull body poses"]
Browser --> Compact["GET /state?compact=1\ncontrol status only"]
Browser --> Control["POST /control\npause/resume/edit commands"]
Browser --> Compose["POST /compose\nbackend MJCF composition"]
Manifest --> Bridge["Headless MotrixSim bridge\nWuying Linux host"]
State --> Bridge
Compact --> Bridge
Control --> Bridge
Compose --> Bridge
Bridge --> Runtime["MotrixSim runtime\nG1 + stocked shelf backend physics scene"]
Important properties:
- Physics and collision are owned by the MotrixSim backend.
- Three.js renders real manifest assets and applies real runtime body poses.
- Pause, resume, reset, step, joint edits, and body pose edits are sent to
/control; the UI does not invent physics results. - Store shelf frames, plates, and pre-stocked products are fixed environment collision bodies. This prevents the shelf scene from toppling or avalanching when the simulator resumes.
- Backend-compatible added props remain real dynamic bodies when the backend
/composeadapter creates them. Uploaded mesh assets are blocked in the product physics scene until the backend explicitly turns them into simulation bodies. - Object physics tiers are surfaced in the UI and evidence artifacts:
backend dynamic bodies, backend fixed bodies, backend state-only bodies, and
visual-only objects. Product acceptance requires
visualOnly=0; uploaded meshes are not silently promoted to physics bodies unless a backend/composeadapter creates real MJCF bodies for them. - Large-scene state polling is adaptive: running scenes keep a low-latency active-body stream for smoother robot/dynamic-object preview, while paused scenes back off polling so object placement, dragging, and diagnostics have less background network and JSON work competing on the browser main thread.
- Large-scene rendering freezes static visual subtrees, reuses primitive
geometries, caps DPR, disables shadows, uses cached pick targets for
hover/drag raycasts, skips unchanged backend body states before transform
application with numeric pose caches instead of per-body string signatures,
switches high-frequency state polling to active robot/dynamic bodies after
the first full frame, caches UI physics-profile summaries, and targets
45 fpsduring camera and drag interaction while keeping idle rendering on demand. - Hot runtime paths avoid avoidable allocation churn: state frames iterate body
maps without
Object.entries, coordinate conversion can write into reusable vectors/quaternions, and pointer drag/camera-fit math reuses scratch objects. - Repeated UI refreshes avoid unnecessary DOM churn: health and acceptance
panels compare generated content before touching
innerHTML, and active-body polling reuses the computed/state?bodies=activeURL after the first full state frame. - Repeated paused state frames use conditional
/staterequests. The browser sendsIf-None-Match, the backend can return304 Not Modifiedwith no JSON body, and the older semantic frame comparison remains as a fallback after parsing. - Large JSON responses are gzip-compressed by the bridge when the client
advertises support.
/composeinline manifests and/manifestexposeX-Motrix-Json-Bytes,X-Motrix-Wire-Bytes, andX-Motrix-Encoding, making tunnel transfer cost measurable in real backend tests. - Large mesh assets served from
/assets/...are gzip-compressed for compressible geometry formats such as STL/OBJ/MTL/glTF when the browser advertises support. Asset responses exposeX-Motrix-Asset-Bytes,X-Motrix-Asset-Wire-Bytes,X-Motrix-Asset-Encoding, andX-Motrix-Asset-Cache, and the real-backend verifier fetches a real mesh asset before browser acceptance so asset transport optimization cannot silently regress. - Controlled
/assets/...OBJ sources use a narrow fast parser for the commonv/vt/vn/fmesh path, with Three.jsOBJLoaderretained as fallback and as the default for local uploaded/custom OBJ assets. The product gate checksobjFast,objLines,objStream, andfallbackcounters so this optimization remains measurable. - Controlled
/assets/...binary STL sources use a narrow triangle-buffer parser for standard robot meshes, with Three.jsSTLLoaderretained as fallback and as the default for uploaded/custom STL assets. The release gate checksstlFast,stlTris,stlBytes, andfallbackcounters so robot mesh parse cost remains observable instead of hidden inside loader work. - Large-scene diagnostics use adaptive stats refresh: user-visible events still force an immediate panel update, while background periodic refreshes drop to a lower cadence for large or paused scenes so long diagnostic strings do not compete with WebGL interaction on the main thread.
- Large-scene camera controls skip idle
OrbitControls.update()work when the camera is not dirty and the damping tail has settled. The controls still wake onstart/change/endevents and programmatic camera changes, whilecontrols update/skipdiagnostics make idle main-thread savings observable. - Dragging objects in the scene no longer rebuilds the builder object list, scene outline, and inspector on every pointer event. Position edits are coalesced during drag and flushed immediately on drag end, keeping WebGL movement responsive while preserving accurate saved coordinates.
- Large-scene 3D drag updates are explicitly throttled to
30 Hz. High-rate pointer streams update the latest pending pose, then apply only the most recent pose on the next allowed frame; drag end still flushes the final pose before backend commit. - Backend-composed objects may render under generated geometry ids while their MuJoCo bodies keep the builder ids. Drag lookup therefore accepts either the render object id or body id, so physical objects remain synchronized with the builder configuration and backend pose commit path.
- Config-import startup uses a lightweight ready workspace when no manifest is supplied, so importing a saved builder config does not first load and discard the default large scene.
Stable Local Topology
Default demo topology:
- Frontend:
http://127.0.0.1:5173 - Real backend tunnel:
http://127.0.0.1:18090 - Product manifest:
http://127.0.0.1:18090/manifest - Wuying host:
39.106.101.95 - Remote bridge scene:
/tmp/motrixsim-web-composed/active_g1_store_scene.xml
Do not use the old 39.96.56.117:22 host.
Daily Startup
npm install
npm run real-backend:up
npm run dev -- --port 5173
Open:
http://127.0.0.1:5173/?manifest=http%3A%2F%2F127.0.0.1%3A18090%2Fmanifest
real-backend:up performs the repeatable backend setup:
- Syncs
server/headless_motrix_bridge.pyto the Wuying host. - Restarts the active composed physical scene paused.
- Ensures the local SSH tunnel on port
18090. - Runs the real backend editing verifier.
Release Gate
Run this before handoff:
npm run product:release-check
This expands to:
npm run typecheck
npm run build
npm run verify:bundle
MOTRIXSIM_PRODUCT_FRONTEND_MODE=preview MOTRIXSIM_PRODUCT_FORCE_FRONTEND=1 \
MOTRIXSIM_PRODUCT_FAIL_ON_WARN=1 \
npm run product:acceptance
The release gate serves the already-built dist/ output through vite preview
on an isolated localhost port. This is stricter than the quick
product:acceptance path, which may reuse an existing Vite dev server while
iterating locally. Release checks also fail on warnings; demo-only warning
states should be handled before handoff.
For local Wuying-backed manifests, the product gate first runs the repeatable
real-backend startup path. This syncs the current bridge script, restarts the
remote MotrixSim bridge, verifies /control editing, and then proceeds with
browser acceptance. That keeps performance gates from accidentally measuring a
stale remote bridge process.
The product acceptance gate must pass with zero failures. It checks:
- Production frontend preview availability during release checks.
- Production bundle budget: max JavaScript gzip chunk <=
170 KiB, total JavaScript gzip <=230 KiB. - Wuying SSH, remote Python, MotrixSim imports, current synced bridge, and health.
- Real backend
/composefor the product G1 stocked shelf physical scene. - Frontend Scene Builder
启用物理属性switch plus构建 / 更新场景action triggering backend/composethrough the product UI. - Single-robot free composition guard: the builder keeps one robot slot, allows
any scene/robot/object selection to build a preview, and only uses backend
/composewhen the selected robot is supported by that scene adapter. - Browser share-link workflow: click the product copy-link action, read the real clipboard value, reopen the URL in a clean browser context, and verify the restored builder config reaches the same backend physics scene.
- Browser config workflow: click the product export-config action, save the downloaded JSON, import it through a real file chooser in a clean browser context, and verify the restored builder config reaches the same backend physics scene.
- Real backend editing through
/control, including a controlled legacy dynamic-body pose sync, fixed inventory protection, dynamic drop after resume, and fixed shelf anchor stability. - Scene Builder compose, share-link restore, config import restore, desktop, and mobile browser screenshots.
- Chinese default UI.
- External simulation label (
外部仿真) and backend physics label (后端物理). - Object physics-tier diagnostics, proving the product scene has backend fixed
bodies, backend state-only robot links, and
visualOnly=0. - Builder physics coverage, proving the default stocked shelf path has no added props and therefore no builder visual-only objects.
- Upload boundary, proving a locally uploaded OBJ asset is blocked until a backend adapter exists instead of being inserted as a visual-only object.
- 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.
- Runtime body-state apply/skip diagnostics, proving unchanged fixed shelf and inventory states are not repeatedly applied to the scene graph.
- Runtime state-hash diagnostics, proving unchanged
/stateframes can be skipped before JSON parsing while paused. The gate also requires real304 Not Modifiedresponses so unchanged frames do not resend JSON bodies. The semantic duplicate-frame check remains as a compatibility fallback for older bridges that do not exposeX-Motrix-State-Hash. - WebGL readback policy, proving the renderer does not keep
preserveDrawingBufferenabled during normal runtime and only renders for explicit screenshot or pixel-readback requests. - Backend compose-cache diagnostics, proving repeated identical physical scene compose requests reuse the active runtime manifest instead of rebuilding the simulator.
- Nonblank WebGL rendering.
- Expected object, mesh, and body binding counts.
- Product-owned acceptance telemetry in the diagnostics panel.
- Full mobile scene loading and mobile acceptance panel.
- Pause/resume backend state and visible UI latency.
- Auditable evidence manifest with screenshot byte size, capture strategy, and sha256 hashes.
- UI-downloaded JSON acceptance package and HTML acceptance report, including parsed schema/content checks and sha256 hashes.
- Browser-rendered screenshot of the downloaded HTML acceptance report.
- Git provenance for the code that produced the evidence.
Evidence is written under:
test-results/product-readiness/
The directory is intentionally ignored by git. Preserve the generated files for handoff or upload them to the external report system when needed.
Release checks write these artifacts:
product-readiness-report.json: full run report, checks, backend evidence, browser evidence, screenshots, and diagnostics.product-readiness-builder-config.json: JSON file downloaded by clicking the product UI export-config button, then imported back through a browser file chooser in a clean context.product-readiness-acceptance-package.json: JSON file downloaded by clicking the product UI export button, then parsed and validated by Playwright.product-readiness-acceptance-report.html: HTML file downloaded by clicking the product UI report export button, then parsed for backend physics and control endpoint evidence.product-readiness-acceptance-report.jpg: screenshot captured after opening the downloaded HTML report in the browser.product-readiness-share-restore.jpg: viewport screenshot captured after opening the copied share URL in a clean browser context, restoring the backend physical scene, and scrolling the workspace status into view.product-readiness-config-import-restore.jpg: screenshot captured after importing the downloaded builder config in a clean browser context and restoring the backend physical scene.product-readiness-visual-only-boundary.jpg: screenshot captured after uploading a local OBJ asset to the physical preset. This boundary evidence must show the upload is blocked, builder visual-only count stays0, and in-page acceptance remains11/0/0.product-readiness-debug-capture.png: PNG captured through the product debug capture path. This verifies screenshot export still works withpreserveDrawingBufferdisabled in the normal renderer.product-readiness-evidence.json: compact handoff manifest with the report hash, git branch/commit/dirty state/remotes, screenshot/export paths, byte sizes, capture strategy, builder/share/config-import status, canvas metadata, parsed export and rendered-report summaries, and sha256 hashes.
The git field in the report and evidence manifest binds visual/export
evidence to a code state:
commit,shortCommit,branch,upstream, andcommittedAtdirtyplusdirtyFilesat the moment the gate ran- configured fetch/push remotes, including the GitHub and Gitea push targets
Current Acceptance Baseline
Representative product gate baseline for the current thresholds:
- Result:
49 passed / 0 warned / 0 failed - Frontend mode:
previewfor release handoff throughnpm run product:release-check. - Fail on warning:
truefor release handoff. - Frontend URL:
http://127.0.0.1:4173/?manifest=http%3A%2F%2F127.0.0.1%3A18090%2Fmanifest&v=product-readiness - Manifest:
http://127.0.0.1:18090/manifest - Real backend doctor:
14 passed / 0 warned / 0 failed - Real backend startup: synced and restarted the Wuying bridge, checked the local tunnel, and passed the editing verifier before browser acceptance.
- Real backend compose/editing:
51 passed / 0 warned / 0 failed - Physical compose:
/composereturned the stocked shelf backend scene with631browser objects,631body bindings, and0added builder props for the default product path. - JSON transport compression:
/composeinline manifest compressed from257063bytes to11221bytes (ratio=0.044), cached/composefrom257062to11214, and/manifestfrom256695to11042. - Mesh asset transport compression: the real backend editing gate fetches a
selected STL/OBJ mesh asset with
Accept-Encoding: gzipand requiresX-Motrix-Asset-Wire-Bytes < X-Motrix-Asset-Bytes, proving large static mesh transfer is compressed by the Wuying bridge before browser acceptance starts. The current proof fetchedtorso_link_rev_1_0.STLand compressed2570584bytes to1046563bytes (ratio=0.407). - Repeated physical compose cache: a second identical
/composerequest returnscached=truewith the same compose key; the current real-backend verification measured54ms. - Static shelf stability: selected shelf anchors had
max drift 0.00000mafter a 2500 ms resume window, preventing the shelf-toppling regression. - Fixed inventory protection: a pre-stocked product body returned HTTP
400forset_body_pose, proving fixed stock is not accidentally treated as a movable free body. - Legacy dynamic-object drop: a lifted user-added test prop dropped
0.48012mafter resume, proving dynamic props still use backend physics. - Active state payload: full
/statereturns602MotrixSim body/link poses for initial binding, while/state?bodies=activereturns34active poses after the first frame and filters568fixed shelf/inventory bodies. The active payload still includes4/4user dynamic bodies. - State hash validation: full paused
/stateexposesX-Motrix-State-Hash/ETag, and repeated paused full-state fetches kept the same hash prefixc1338a5c3a5c. The active-state response exposed hash prefix6c59c3f69e9e. - Conditional state validation: the real-backend verifier sends
If-None-Matchwith the paused full-state ETag and expects HTTP304with an empty body before browser acceptance starts. - Object physics tiers: the diagnostics panel and exported acceptance artifacts
count backend dynamic, backend fixed, backend state-only, and visual-only
objects. The product physical scene currently reports
dynamic=0,fixed=568,stateOnly=63, andvisualOnly=0. - Product UI compose: the Scene Builder physics switch workflow reaches
后端物理组合场景, loads the stocked shelf backend scene without extra test props, exposes/control, and shows外部仿真 / 后端物理diagnostics. - Builder physics coverage: the product UI and exported acceptance package show
builderDynamic=0,builderVisual=0,total=0,ready=truefor the no-extra-prop stocked shelf path. - Upload boundary: the gate uploads a local OBJ asset in a separate clean
browser context. The uploaded asset is blocked from insertion until backend
adaptation exists, with
builderVisual=0and in-page acceptance at11/0/0. - Product share link: the gate clicks
复制分享链接, confirms the copied URL has abuilderpayload and nomanifestoverride, then opens it in a clean browser context. The restored page keeps0added props, reaches631objects, exposeshttp://127.0.0.1:18090/control, and shows工作区:已从分享链接恢复. - Product config import: the gate clicks
导出配置, savesproduct-readiness-builder-config.json, imports it through a clean browser file chooser, and verifies工作区:配置已导入with0added props,631objects, and/controlendpoint. - Evidence manifest:
test-results/product-readiness/product-readiness-evidence.json. This generated file is the source of truth for the latest report hash, screenshot hashes, git commit, and dirty state. - Scene Builder compose screenshot:
test-results/product-readiness/product-readiness-builder-compose.jpg(strategy=page; shows the product UI after enabling physics and building the scene reaches构建器:后端物理组合场景,631 个对象) - Share-link restore screenshot:
test-results/product-readiness/product-readiness-share-restore.jpg(strategy=page; viewport capture after loading the copied share URL in a clean browser context and exposing the restored workspace status) - Config import restore screenshot:
test-results/product-readiness/product-readiness-config-import-restore.jpg(strategy=page; viewport capture after importing the downloaded builder config in a clean browser context and exposing the imported workspace status) - Desktop screenshot:
test-results/product-readiness/product-readiness-desktop.jpg(strategy=canvas; exact bytes and sha256 are in the evidence manifest) - Debug PNG capture:
test-results/product-readiness/product-readiness-debug-capture.png(strategy=debug-capture; latest representative gate recorded173 KiBimage/png) - Mobile screenshot:
test-results/product-readiness/product-readiness-mobile.jpg(strategy=canvas; exact bytes and sha256 are in the evidence manifest) - UI-downloaded acceptance package:
test-results/product-readiness/product-readiness-acceptance-package.json(schema=motrixsim-web.acceptance-package.v1; state, object count, and control endpoint are parsed by the gate) - UI-downloaded builder config:
test-results/product-readiness/product-readiness-builder-config.json(version=1, backend stocked-shelf scene,robotPose=1.85,-0.95,0,props=0; parsed and re-imported by the gate) - UI-downloaded HTML acceptance report:
test-results/product-readiness/product-readiness-acceptance-report.html(the gate checks for backend physics and/controlevidence in the report) - Rendered HTML report screenshot:
test-results/product-readiness/product-readiness-acceptance-report.jpg(the gate opens the downloaded HTML report in Chromium and verifies title, verdict, case rows, check rows, backend physics, and/controlevidence)
Scene evidence:
- Objects:
631 - Body bindings:
631 - Meshes:
627 - Editable groups:
4 / 568 - Fallback meshes:
0 - Desktop acceptance:
11 通过 / 0 警告 / 0 失败,共 11 项 - Desktop acceptance telemetry:
0 ms / 11-0-0 - Desktop performance diagnostics: large-scene mode targeted
45 fps, capped DPR at1.00, kept shadows off, instanced568fixed objects into16batches, fast-parsed16controlled OBJ shelf/product sources with0fallback parses, and reduced state polling to34/602active poses after the first full frame. - Conditional state skip: recent large-scene desktop runs recorded
hash=5-6polls with3-4hash-level skips and3-4real304 Not Modifiedresponses, avoiding JSON body retransmission while paused. - Drag coalescing: the paused builder drag check records
28pointer moves and reduces them to about15-17scene pose applications with25-26coalesced/throttled move events. - Control latency: recent release gates measured resume and pause visible UI
confirmations in the
55-211msrange, well below the3000mstarget. - Mobile preview:
631 objects / 631 bindings / 30 pixels - Mobile acceptance:
11 通过 / 0 警告 / 0 失败,共 11 项 - Mobile acceptance telemetry:
0 ms / 11-0-0 - UI acceptance package export:
schema=motrixsim-web.acceptance-package.v1,state=pass,objects=631,builderDynamic=0,builderVisual=0,control=http://127.0.0.1:18090/control - UI HTML report export: title includes
MotrixSim Web 预览验收报告, backend physics evidence is present, and/controlis present. - UI HTML report render: the downloaded report opens in Chromium with a visible
verdict, acceptance-case rows, acceptance-check rows, backend physics, and
/controlevidence. - Share-link copy: copied/generated browser URL has
builder=true,manifest=false, andv=builder-share. - Share-link restore: clean-context reload reaches backend physical scene with
0restored props,631objects,631body bindings,4 / 568editable groups, and/controlavailable. - Config import restore: clean-context file import reaches backend physical
scene with
0restored props,631objects,631body bindings,4 / 568editable groups, and/controlavailable. The config-import route now reportsskippedDefaultLoad=trueand initial status准备就绪, proving it did not load the default manifest before the file chooser import. - Backend compose cache: repeated identical physical compose requests reuse the active runtime manifest. This improves backend repeat-compose latency, while full share/config restore still includes browser page load and mesh setup.
- Frontend mesh source cache: parsed GLTF/OBJ/STL sources are retained across
scene rebuilds, while scene-owned clones still release their non-retained
resources. Controlled backend OBJ sources also use the fast parser before the
retained source enters the cache, and controlled binary STL robot meshes use
the dedicated triangle-buffer parser. The release gate now checks mesh cache
hit/miss plus
objFast/objLines/objStream/fallbackandstlFast/stlTris/stlBytes/fallbackdiagnostics. - Camera-fit bounds cache: object world bounds are captured while creating
cached pick targets, so camera fitting no longer performs a second deep
Box3.setFromObjecttraversal across the full scene. - Mesh pick bounds cache: source mesh bounds are computed once per retained mesh source, and repeated mesh targets are created from cached bounds instead of re-traversing the whole cloned subtree.
- Pre-frozen mesh clone cache: retained mesh sources are frozen once after load. Repeated clone construction reuses that frozen state and skips the per-clone static-subtree traversal and spin scan when the source has no animated nodes.
- Fixed repeated mesh instancing: in large scenes, repeated fixed mesh assets
render through shared
InstancedMeshbatches while each manifest object keeps its body binding, cached bounds, editable group, and backend sync path. Fixed instances now use a virtual identity root instead of one detached Three.js root per shelf/product item. This reduces initialization matrix/object work without turning the objects into frontend-only decorations. - Instanced local-pose/root elision: repeated fixed mesh assets no longer
allocate a persistent local-pose
Object3Dor per-item root for every shelf/product item. Each item keeps a cached local transform matrix plus source bounds, and the instanced matrix is computed directly fromlocalMatrix * sourceMatrixfor fixed virtual-root instances. This keeps backend bindings intact while removing hundreds of Three.js nodes and inverse bounds transforms from the large-scene build path. - Finalized instanced batch culling: after all instance matrices are written,
each
InstancedMeshcomputes a batch bounding box/sphere, switches its instance buffer to static usage, and re-enables frustum culling. The release gate checks this for every instanced draw unit. - Bounds-only picking: hover and drag picking now ray-test cached
Box3targets directly instead of adding one invisible Three.js mesh per object. Fixed instanced objects keep detached data roots for backend sync, while only the shared instanced batches enter the render scene. - Hover target pruning: large scenes keep all object bounds for camera fitting, diagnostics, drag binding, and backend sync, but the high-frequency hover list excludes repeated fixed inventory products while preserving shelf fixtures, robots, and editable dynamic objects for user feedback.
- Cached hover/drag bounds: hover focus, hover outline, and drag highlight use
the existing pick target bounds through a
Box3Helperwhen present, so hovering or dragging a large shelf/product group does not callBoxHelper.setFromObjecton the full visual subtree and does not allocate cloned focus vectors every animation frame. - Scratch bounds transforms: pick-target bounds construction reuses
Box3,Matrix4, and cornerVector3scratch objects for cached mesh bounds instead of allocating transformed bounds for every repeated shelf/product object. - 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
sceneBuildYieldCountso this cannot silently regress back to one long main thread task. - Deferred state polling during scene load: manifest state streaming starts
after the Three.js scene graph has finished constructing. This prevents the
first full
/statepayload parse and body-map merge from competing with the large-scene asset/object build on the same browser main thread. - Fixed-body state elision: fixed shelf and inventory bodies stay bound for diagnostics and selection, but full-state frames do not re-apply those poses to static roots. This avoids uploading hundreds of duplicate instanced matrices immediately after a large scene finishes loading.
- Active-state polling: after the first full state frame, large scenes poll
/state?bodies=active. The preview merges partial active frames into the initial full body map, so fixed shelf/inventory bindings remain available while high-frequency payloads only carry robot and dynamic body poses. - Adaptive paused polling: large scenes keep the running active-body poll at
50-80mswhen the backend is unpaused, but schedule paused follow-up polls at2000msor slower. Direct control confirmation still uses compact/state?compact=1, so pause/resume latency stays independent of the background paused poll cadence. - Semantic duplicate-state elision:
/stateframes are parsed into a semantic signature that ignores volatile transport telemetry such asserver_time. When the signature is unchanged, the state client counts the poll but does not forward the frame to the Three.js preview, avoiding body merge, binding traversal, matrix checks, diagnostics writes, and render dirties for repeated paused-state frames. - Conditional state elision: the MotrixSim bridge emits
X-Motrix-State-HashandETagfor/stateresponses. The browser sendsIf-None-Matchon later polls, accepts304 Not Modifiedas a duplicate frame, and avoids both JSON body transfer andresponse.json()parsing. If an older bridge only returns200, the browser still uses the hash header to skip parsing unchanged frames. - Incremental body-state merge: active-state frames mutate the retained body map
by payload key instead of spreading/copying the full
602-body map on every poll, reducing steady-state allocation and GC pressure while preserving full bindings for fixed shelf and inventory objects. - O(1) runtime stats aggregation: body-binding count, grouped editable-object
count, and last merged body count are maintained during scene build/state
merge instead of re-scanning
Mapvalues orObject.keys(602 bodies)on every diagnostics/acceptance stats read. - UI diagnostics cache: object physics tiers and Scene Builder physics summaries are computed once per stats refresh and cached until the manifest, physics mode, selected scene, or prop list changes. The product gate now checks these UI cache hit/miss counters so the diagnostics panel cannot regress into full scene rescans on every render.
- Stable side panels: health and acceptance sections only rewrite their DOM when the generated content changes, reducing repeated list reconstruction during normal state polling and diagnostics refreshes.
- Body-state cache: unchanged backend poses are compared numerically instead of allocating string signatures for every body in every full state frame.
- Scratch coordinate conversion: pose application, backend body-state updates, drag pointer math, and camera-fit bounds use reusable Three.js math objects rather than allocating transient vectors/quaternions during hot paths.
- Stable-frame render gate: repeated state frames that do not change any body
transform or run metadata are counted as
unchanged framesand do not dirty the WebGL renderer. - WebGL readback gate: normal runtime rendering leaves
preserveDrawingBuffer=false, avoiding the persistent framebuffer retention cost. Pixel sampling and exported PNG screenshots call an explicit readback render, and positive pixel evidence is cached until the next scene reload. - Manual and virtual root matrices: dynamic/stateful manifest objects keep manual roots with automatic matrix updates disabled, while repeated fixed instanced inventory uses virtual identity roots. Runtime state, drag, and robot-offset changes explicitly update only the roots that actually move.
- Safe physical template pose:
/composeapplies the builderrobotPoseto the included G1 MJCF before loading MotrixSim, and the default physical template exportsrobotPose=1.85,-0.95,0. The backend editing gate checks the livepelvispose after compose, so the default robot cannot silently return to the shelf interior.
Bundle evidence:
- JavaScript chunks:
4 - App entry chunk:
227.23 kB raw / 58.14 kB gzip - Largest JavaScript gzip chunk:
140.96 KiB / 170.00 KiB - Total JavaScript gzip:
221.61 KiB / 230.00 KiB - Large-scene performance mode:
large-scene, target45 fps, actual idle render rate0.5-0.7 fps, DPR cap observed at1.00in release gate,preserveDrawingBuffer=false,1explicit readback render, shadowsoff, hover picking throttled to32ms,546-664empty frames skipped,135static visual nodes frozen,568instanced local-pose nodes elided,59remaining mesh clones using pre-frozen source state,627repeated spin scans skipped,568repeated fixed mesh objects rendered as16instanced batches with16instanced draw units,568matrix uploads, and all16draw units finalized with frustum culling plus static instance matrices,7primitive geometry shapes cached, mesh source loading observed with a24source scheduling ceiling and peak concurrency16within that ceiling,51mesh source assets retained,24/51mesh cache hit/miss in the primary large scene,16/0fast OBJ parse/fallback in the controlled backend asset path,568virtual fixed instance roots,68manual roots,631cached object bounds,627fast pick-target bounds from51cached source bounds, real hover proofhoverProxy 2with cached bounds andfallback 0, with0camera-fit traversals,4/84progressive scene root batches under the computed84root cap and5batch cap,152-195no-op loading frames suppressed during the primary load,26browser event-loop yields during scene construction, active state payload34/602with1-2reduced frames and3incremental body-map merges, semantic poll forwarding2/2/4parsed/forwarded/duplicate-skip, state-hash polling around5-6hash frames with3-4hash skips and3-4real304 Not Modifiedresponses, UI physics-profile cache around25-27/3hit/miss, UI builder-profile cache around28-30/1hit/miss, UI text write gating above100writes and400skips, text selector cache above470/46hit/miss, scratch bounds transforms695, diagnostics panel throttling around19renders with scheduled skips,83/631hover targets over cached bounds used for bounds-only ray tests, and a stable paused backend state cache reportedmanual roots 68 updates 67withstate apply 0/skip 67. - Mesh cache lifecycle evidence: the Scene Builder compose switch reported
cumulative
99/51mesh cache hit/miss with51retained geometries and17retained materials, avoiding repeated parser/network work for duplicate shelf and product assets. - Scene-load phase telemetry: the large-scene gate now captures phase timings
directly from the browser. Recent cold default scene loads report
load=1843-3089ms, with nearly all time inobjects,prewarm=0/0-1ms,finalize=1ms, andcamera=0ms, proving object/asset construction dominates even after transport compression. Warm Scene Builder compose reportsload=324-463ms,objects=318-456ms,prewarm=16/0ms, andfinalize=0ms, proving retained mesh sources turn the same 631-object scene into a sub-second rebuild path. - Instanced batch prewarm policy: batch prewarm is intentionally enabled only
when the mesh source is already retained in the local browser cache. A cold
prewarm probe increased asset contention, so the cold path stays demand
loaded while warm rebuilds still seed all
16instanced batches. - Asset payload diagnosis: the current Wuying-backed product manifest exposes
51unique mesh source URLs totaling about24.12 MiBby realGETtransfer, split roughly into18.76 MiBSTL robot assets and5.37 MiBOBJ store assets. The largest robot meshes are multi-megabyte STL files, so the remaining cold-start card is primarily asset transfer/parse/scene-object construction rather than pause/resume control latency. The bridge now compresses compressible mesh responses and exposes raw/wire byte counts, so transfer savings are separated from the browser-side parse and object-build cost in gate evidence. - Controlled OBJ fast parse gate:
browser-large-scene-performance-modenow requiresobjFast > 0,objLines > 0,objStream > 0, andobjLoaderFallbackCount = 0for the Wuying-backed store scene. The latest product release gate recordedobjFast=16,objLines=173670,objStream=53/5628890B, andfallback=0, while uploaded/custom OBJ assets keep the full Three.jsOBJLoaderpath for compatibility. - Controlled STL fast parse gate: the same performance gate requires
stlFast > 0,stlTris > 0,stlBytes > 0, andstlLoaderFallbackCount = 0for Wuying-backed standard binary STL robot meshes. The latest product release gate recordedstlFast=35,stlTris=393270,stlBytes=19666440B, andfallback=0. Uploaded/custom STL assets keep the full Three.jsSTLLoaderpath for compatibility with ASCII STL, non-standard binary STL, and color-bearing variants. - Fast OBJ parser allocation hygiene: controlled OBJ parsing stores source
positions, UVs, and normals in flat numeric arrays and triangulates faces
without per-triangle temporary arrays. It also scans the OBJ text one line at
a time and consumes
Response.bodywithTextDecoderchunks instead of materializing a fullresponse.text()string ortext.split(...)line array, keeping the optimization focused on browser main-thread parse/GC pressure rather than changing asset semantics. - Material construction hygiene: Three.js material creation now omits the
optional
mapparameter unless a texture actually exists. The quick browser performance check recorded0THREE.Material: parameter 'map'warnings, keeping console noise from hiding real asset/runtime issues. - Active-state gate:
browser-large-scene-performance-modenow checksstate payload 34/602with at least one reduced state frame, proving fixed shelf/inventory bodies are not repeatedly shipped in the high-frequency polling path. - Incremental body merge gate:
browser-large-scene-performance-modeandbrowser-body-state-cachenow require an incremental merge count above zero, proving active-state frames are not rebuilt by full body-map spreading. - Adaptive state-polling gate:
browser-adaptive-state-pollingwaits for a real paused poll and checks running/paused poll telemetry, proving the browser uses a low-latency active stream while running and a slower cadence after pausing. - Semantic duplicate-state gate: the same browser gate still tracks parsed, forwarded, and skipped poll frames as a fallback for older backends without hash headers, proving repeated paused state does not reach the renderer and UI panels.
- State-hash/304 gate: the large-scene and adaptive-polling checks require
hashed state frames, at least one hash-level duplicate skip, at least one
304 Not Modified, and fewer parsed frames than actual poll requests, proving unchanged frames are discarded before JSON transfer/parsing when the backend supports conditional state requests. - UI refresh gate:
browser-large-scene-performance-modenow checks duplicate text-write skips, stable text-selector cache hits, and diagnostics-panel refresh skips, proving high-frequency/statepolling does not force unchanged diagnostics DOM writes or repeated selector queries every frame. - Stats refresh gate:
browser-large-scene-performance-modenow checks the adaptive stats refresh interval reaches the large-scene low-frequency cadence and that at least one scheduled weak refresh ran during real browser validation. - Builder panel telemetry:
browser-builder-drag-panel-coalescingperforms a real paused-scene drag on a dynamic builder object and requires deferred plus coalesced panel refresh counters to increase. It also requires 3D drag coalescing telemetry to show more raw pointer moves than applied scene updates (dragMoveEventCount > dragAppliedMoveCount) and at least one coalesced move. The large-scene performance detail carries both builder panel render/defer/coalesce counters anddrag=move/applied/coalesced. - WebGL readback gate:
browser-large-scene-performance-modenow checksbuffer=falseandreadback=1, andbrowser-debug-capture-pngchecks the exported PNG path (172 KiB image/png) so debug screenshot export remains covered after removing the persistent drawing buffer. - Body-state cache gate:
browser-body-state-cachewaits for the paused scene to use a reduced active payload and still skip unchanged active poses. The current run passed withstate apply 0/skip 67,statePayload=34/602, andincremental=2. - Robot safe-pose gate:
verify-real-backend-editingnow checksrobot-safe-initial-pose, with the latest composed scene reportingpelvis=1.850,-0.950,0.793, proving the default G1 starts outside the shelf interior after MotrixSim loads the generated MJCF. - Camera-fit traversal gate:
browser-large-scene-performance-modenow checksbounds cache 631andcamera traversals 0. - Pick-proxy bounds gate:
browser-large-scene-performance-modenow checksfast=627,scratch=695, andsource=51, proving repeated mesh pick bounds are served from cached source bounds, with fixed instanced objects taking the virtual-root one-transform path instead of the older root inverse path. - Pre-frozen mesh clone gate:
browser-large-scene-performance-modenow checksprefrozen + instanced >= repeated mesh thresholdandspinSkip=627, proving repeated mesh assets avoid re-traversing static visual subtrees and non-spinning clone trees. - Instanced mesh gate:
browser-large-scene-performance-modenow checksinstanced=568/16/16,matrices=568,cull=16,static=16,elidedLocal=568,virtualRoots=568, and that instanced draw units are fewer than instanced objects, proving repeated fixed inventory renders through shared GPU batches with virtual per-item roots and safe frustum culling instead of one cloned render tree per item. The same gate also requiresfrozen + elidedLocal >= 500, so removing local-pose nodes cannot be mistaken for losing static-scene optimization coverage. - Hover bounds gate:
browser-hover-proxy-boundsmoves the mouse over the real canvas and now checks bothhoverProxyand cached hover bounds increase whilefallback=0, proving hover highlight uses the pruned cached bounds list instead of traversing the visual root. The current proof hits the shelf fixture atpoint=0.35,0.50with固定物理体: geom_64. - Progressive scene-load batching gate:
browser-large-scene-performance-modenow checksscene batches 4/84,maxSceneRoots=84,maxBatches=5, andyields 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
1geometry,10materials, and2textures from non-retained scene graph resources while preserving cached mesh sources.
Control evidence:
- Cold compose endpoint:
366ms,4/4composed object bodies synced, withresetApplied=truewhen requested by the Scene Builder restore path. - Repeated compose cache:
54ms,cached=true, same compose key, andresetApplied=true, so the frontend no longer needs a second/control resetrequest after a cached compose restore. - JSON transport compression:
/composeand/manifestwire payloads are about11 KiBafter gzip instead of about257 KiBuncompressed. - Mesh transport compression:
/assets/...responses for compressible geometry formats expose raw and wire byte counts and are verified with a real asset fetch byverify-real-backend-editing; the current STL proof is2570584 -> 1046563 bytes. The bridge also exposesX-Motrix-Asset-Cache; the verifier now requires the selected GET probe to reportcache=hitafter HEAD prewarming, proving repeated compressed asset responses do not re-read and re-gzip the large source file. - Active state endpoint: full
/statereturned602bodies; active/state?bodies=activereturned34bodies in58ms, filtered568fixed bodies, and retained4/4composed dynamic bodies. - Scene Builder UI compose: representative run
3817msend to end with real backend diagnostics. - Share-link restore: representative full browser restore
9513ms; builder telemetry splits it intocompose=292ms,preview=2045ms,state=6ms, synchronousstats=0ms, asynchronouspixelWait=2174ms, andpixel=1470ms. - Config import restore: representative full browser restore
17433ms; builder telemetry splits it intocompose=551ms,preview=4815ms,state=9ms, synchronousstats=1ms, asynchronouspixelWait=6276ms, andpixel=2325ms. - Composed object body edit:
47ms. - Fixed inventory edit rejection:
63ms. - Dynamic composed object drop:
0.48012m. - Static shelf anchor stability:
max drift 0.00000mafter a 2500 ms resume window. - Resume backend state:
71ms paused=false - Resume visible UI state:
50ms - Pause backend state:
74ms paused=true - Pause visible UI state:
59ms - Desktop acceptance wait: product telemetry
0ms - Mobile acceptance wait: product telemetry
0ms - Runtime diagnostics panel:
state=http://127.0.0.1:18090/state,control=http://127.0.0.1:18090/control,latency=响应 55-211 ms / 确认 55-211 ms / 可见 55-211 ms,acceptanceLatency=0 ms / 11-0-0,binding=631/631; 4/568,builderPhysics=已添加物体 0: 后端动态 0 / 仅视觉 0,renderPerformance=large-scene; target 45 fps; dpr 1.00; buffer preserved false; readback renders 1; shadows off; bounds cache 631; state payload 30/598; poll 50/2000ms; pick targets 83/631. - Evidence screenshot artifacts:
builder page; share page; import page; visual-only boundary canvas; desktop canvas; debug PNG; mobile canvas - Evidence export artifacts:
config 1 KiB v1; package 15 KiB motrixsim-web.acceptance-package.v1; report 17 KiB; rendered screenshot recorded
Visible UI control sync is the product interaction SLA and must stay under the
current 3000ms target. Backend state polling can take longer when the remote
physical scene is finishing a large step; it must still confirm within the
6000ms max gate.
Control Plane Design
The product control path is separated from heavy state streaming:
GET /statereturns full body poses for visual synchronization.GET /state?bodies=activereturns robot/state bodies and user dynamic bodies after the first full frame, avoiding repeated fixed shelf/inventory payloads.GET /state?compact=1returns lightweight control status.POST /controlsupports compact responses for controls and edits.- Pause/resume/toggle use a fast backend control path.
- The frontend records direct compact
/controlresponses as immediate confirmation when the response already contains the expected paused state. - The frontend aborts/suspends full visual polling while a control command is in flight.
- The frontend briefly suspends WebGL rendering while applying the control response, then resumes rendering.
- The frontend rejects stale runtime frames by
server_time, so older full state responses cannot overwrite a newer control result. - Control latency telemetry is published on
document.documentElement.datasetandwindow.__motrixControlTelemetryfor acceptance and diagnostics. - Acceptance self-check telemetry is published on
document.documentElement.datasetandwindow.__motrixAcceptanceTelemetry. This separates product-owned self-check cost from Playwright or renderer scheduling delays in release automation.
Acceptance Debugging
If product:acceptance fails, inspect in this order:
npm run real-backend:doctornpm run verify:real-backend -- http://127.0.0.1:18090/manifesttest-results/product-readiness/product-readiness-report.json- Browser screenshots in
test-results/product-readiness/includeproduct-readiness-builder-compose.jpg,product-readiness-desktop.jpg, andproduct-readiness-mobile.jpg. - UI export artifacts in
test-results/product-readiness/includeproduct-readiness-acceptance-package.jsonandproduct-readiness-acceptance-report.html. - Rendered report evidence includes
product-readiness-acceptance-report.jpg. - Remote bridge log:
/tmp/motrix_bridge_18090.logon the Wuying host
Typical root causes:
- SSH tunnel is stale or missing.
- Remote bridge is running an older script.
- The active composed MJCF scene was replaced or deleted.
- The frontend was opened with a stale manifest URL.
- Large-scene asset loading is still in progress when interacting manually.
Product Boundary
This is a real interactive 3D preview backed by MotrixSim physics, not a server-side video stream and not a fake browser-only physics simulation.
Current supported product path:
- G1 + stocked shelf backend physical scene.
- Real backend physical composition through
/composefor backend-adapted objects. - Product UI physical composition through the Scene Builder
启用物理属性switch and构建 / 更新场景action. - Single robot scene composition: unsupported robot/scene backend combinations are blocked from product physics instead of being claimed as backend physics.
- Real backend pause/resume/reset/step.
- Real backend dynamic body pose editing while paused for backend-adapted objects.
- Fixed shelf and stock inventory protection with product grouping metadata for inspection and stability checks.
- Upload of local meshes/manifests for staging and backend adaptation.
- Backend-adapted objects can be composed into the backend physical scene.
Current limits:
- Uploaded arbitrary mesh assets are blocked from the product physical scene by default. They do not become backend collision geoms unless converted through a backend compose adapter.
- The current backend
/composeadapter is scoped to the product G1 + stocked shelf scene with the scene built-in/G1 robot and backend-compatible added props. Other single-robot combinations are previewable, but not claimed as full backend collision physics. - Full
/statestreaming for 600+ bodies is for visual synchronization, not high-frequency control. The control plane uses compact state. - Private assets sent to the browser are visible to that browser. Use server-side rendered video/images if assets must never leave the server.
- Mobile rendering is supported for inspection, but the primary layout/editing workflow is desktop-first.
Current performance boundaries:
- The product scene intentionally contains
631objects and627meshes, so first load, Scene Builder compose, share restore, and config import restore still include browser asset creation and scene graph setup time. - The real backend control path is not the observed bottleneck in the current
gate: resume and pause visible UI confirmation have stayed in the
55-211msrange across recent release checks, and repeated compose cache with reset is about55ms. - State connection now starts in parallel with browser scene construction. If a
real backend frame arrives before all visual objects are built, the frontend
reapplies the latest backend frame after
loadManifest()completes instead of synthesizing any pose locally. - The remaining high-impact optimization area is asset-level rendering and
static-scene packaging: the current virtual-root instancing path reduces
per-item scene construction (
virtualRoots=568,manualRoots=68), and mesh gzip plus controlled OBJ fast parsing reduce cold network/parse cost, but the latest gates still spend about9-18send to end in full browser page load, compose restore, asset setup, pixel proof, and screenshots. Internal builder telemetry is lower: share restore reports roughlytelemetry=2.0-2.4s,compose=0.29-0.31s,preview=1.7-2.1s,state=6-8ms,stats=0ms; config import reports roughlytelemetry=2.0-5.4s,compose=0.09-0.55s,preview=1.8-4.9s,state=4-9ms,stats=0-1ms. The next tier is asset format conversion to GLB/Draco or quantized geometry, material reduction, LODs, static asset manifests, and eventually moving repeated fixed inventory into a backend static-state channel. - 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
0mswhile pixel proof runs in the separatepixeltelemetry stage.
Handoff Criteria
Before calling a build acceptable for demo or review:
npm run product:release-checkpasses.- The generated report has
0 failedand0 warned. - Scene Builder compose screenshot shows the real product UI after the backend physical composition workflow.
- Desktop screenshot shows a nonblank real 3D scene.
- The UI shows
外部仿真and后端物理. - Pause/resume visible state latency is below
3000ms. - The browser gate shows the Scene Builder physics switch workflow reaches backend physical composition.
- The browser gate proves UI export buttons download a valid JSON acceptance package and HTML acceptance report.
- The browser gate proves the downloaded HTML acceptance report renders with readable acceptance evidence.
verify:real-backendshows real/compose, composed object body sync, fixed inventory protection, dynamic object drop, and fixed shelf stability.- Any new physical asset type has an explicit backend compose/export path.