MotrixSimWeb/docs/product-readiness.md

54 KiB
Raw Permalink Blame History

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 /compose adapter 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 /compose adapter 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 fps during 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=active URL after the first full state frame.
  • Repeated paused state frames use conditional /state requests. The browser sends If-None-Match, the backend can return 304 Not Modified with 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. /compose inline manifests and /manifest expose X-Motrix-Json-Bytes, X-Motrix-Wire-Bytes, and X-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 expose X-Motrix-Asset-Bytes, X-Motrix-Asset-Wire-Bytes, X-Motrix-Asset-Encoding, and X-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 common v/vt/vn/f mesh path, with Three.js OBJLoader retained as fallback and as the default for local uploaded/custom OBJ assets. The product gate checks objFast, objLines, objStream, and fallback counters so this optimization remains measurable.
  • Controlled /assets/... binary STL sources use a narrow triangle-buffer parser for standard robot meshes, with Three.js STLLoader retained as fallback and as the default for uploaded/custom STL assets. The release gate checks stlFast, stlTris, stlBytes, and fallback counters 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 on start/change/end events and programmatic camera changes, while controls update/skip diagnostics 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:

  1. Syncs server/headless_motrix_bridge.py to the Wuying host.
  2. Restarts the active composed physical scene paused.
  3. Ensures the local SSH tunnel on port 18090.
  4. 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 /compose for the product G1 stocked shelf physical scene.
  • Frontend Scene Builder 启用物理属性 switch plus 构建 / 更新场景 action triggering backend /compose through 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 /compose when 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 /state frames can be skipped before JSON parsing while paused. The gate also requires real 304 Not Modified responses so unchanged frames do not resend JSON bodies. The semantic duplicate-frame check remains as a compatibility fallback for older bridges that do not expose X-Motrix-State-Hash.
  • WebGL readback policy, proving the renderer does not keep preserveDrawingBuffer enabled 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 stays 0, and in-page acceptance remains 11/0/0.
  • product-readiness-debug-capture.png: PNG captured through the product debug capture path. This verifies screenshot export still works with preserveDrawingBuffer disabled 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, and committedAt
  • dirty plus dirtyFiles at 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: preview for release handoff through npm run product:release-check.
  • Fail on warning: true for 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: /compose returned the stocked shelf backend scene with 631 browser objects, 631 body bindings, and 0 added builder props for the default product path.
  • JSON transport compression: /compose inline manifest compressed from 257063 bytes to 11221 bytes (ratio=0.044), cached /compose from 257062 to 11214, and /manifest from 256695 to 11042.
  • Mesh asset transport compression: the real backend editing gate fetches a selected STL/OBJ mesh asset with Accept-Encoding: gzip and requires X-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 fetched torso_link_rev_1_0.STL and compressed 2570584 bytes to 1046563 bytes (ratio=0.407).
  • Repeated physical compose cache: a second identical /compose request returns cached=true with the same compose key; the current real-backend verification measured 54ms.
  • Static shelf stability: selected shelf anchors had max drift 0.00000m after a 2500 ms resume window, preventing the shelf-toppling regression.
  • Fixed inventory protection: a pre-stocked product body returned HTTP 400 for set_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.48012m after resume, proving dynamic props still use backend physics.
  • Active state payload: full /state returns 602 MotrixSim body/link poses for initial binding, while /state?bodies=active returns 34 active poses after the first frame and filters 568 fixed shelf/inventory bodies. The active payload still includes 4/4 user dynamic bodies.
  • State hash validation: full paused /state exposes X-Motrix-State-Hash/ETag, and repeated paused full-state fetches kept the same hash prefix c1338a5c3a5c. The active-state response exposed hash prefix 6c59c3f69e9e.
  • Conditional state validation: the real-backend verifier sends If-None-Match with the paused full-state ETag and expects HTTP 304 with 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, and visualOnly=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=true for 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=0 and in-page acceptance at 11/0/0.
  • Product share link: the gate clicks 复制分享链接, confirms the copied URL has a builder payload and no manifest override, then opens it in a clean browser context. The restored page keeps 0 added props, reaches 631 objects, exposes http://127.0.0.1:18090/control, and shows 工作区:已从分享链接恢复.
  • Product config import: the gate clicks 导出配置, saves product-readiness-builder-config.json, imports it through a clean browser file chooser, and verifies 工作区:配置已导入 with 0 added props, 631 objects, and /control endpoint.
  • 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 recorded 173 KiB image/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 /control evidence 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 /control evidence)

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 at 1.00, kept shadows off, instanced 568 fixed objects into 16 batches, fast-parsed 16 controlled OBJ shelf/product sources with 0 fallback parses, and reduced state polling to 34/602 active poses after the first full frame.
  • Conditional state skip: recent large-scene desktop runs recorded hash=5-6 polls with 3-4 hash-level skips and 3-4 real 304 Not Modified responses, avoiding JSON body retransmission while paused.
  • Drag coalescing: the paused builder drag check records 28 pointer moves and reduces them to about 15-17 scene pose applications with 25-26 coalesced/throttled move events.
  • Control latency: recent release gates measured resume and pause visible UI confirmations in the 55-211ms range, well below the 3000ms target.
  • 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 /control is present.
  • UI HTML report render: the downloaded report opens in Chromium with a visible verdict, acceptance-case rows, acceptance-check rows, backend physics, and /control evidence.
  • Share-link copy: copied/generated browser URL has builder=true, manifest=false, and v=builder-share.
  • Share-link restore: clean-context reload reaches backend physical scene with 0 restored props, 631 objects, 631 body bindings, 4 / 568 editable groups, and /control available.
  • Config import restore: clean-context file import reaches backend physical scene with 0 restored props, 631 objects, 631 body bindings, 4 / 568 editable groups, and /control available. The config-import route now reports skippedDefaultLoad=true and 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/fallback and stlFast/stlTris/stlBytes/fallback diagnostics.
  • Camera-fit bounds cache: object world bounds are captured while creating cached pick targets, so camera fitting no longer performs a second deep Box3.setFromObject traversal 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 InstancedMesh batches 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 Object3D or 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 from localMatrix * sourceMatrix for 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 InstancedMesh computes 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 Box3 targets 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 Box3Helper when present, so hovering or dragging a large shelf/product group does not call BoxHelper.setFromObject on 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 corner Vector3 scratch 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 sceneBuildYieldCount so 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 /state payload 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-80ms when the backend is unpaused, but schedule paused follow-up polls at 2000ms or 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: /state frames are parsed into a semantic signature that ignores volatile transport telemetry such as server_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-Hash and ETag for /state responses. The browser sends If-None-Match on later polls, accepts 304 Not Modified as a duplicate frame, and avoids both JSON body transfer and response.json() parsing. If an older bridge only returns 200, 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 Map values or Object.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 frames and 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: /compose applies the builder robotPose to the included G1 MJCF before loading MotrixSim, and the default physical template exports robotPose=1.85,-0.95,0. The backend editing gate checks the live pelvis pose 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, target 45 fps, actual idle render rate 0.5-0.7 fps, DPR cap observed at 1.00 in release gate, preserveDrawingBuffer=false, 1 explicit readback render, shadows off, hover picking throttled to 32ms, 546-664 empty frames skipped, 135 static visual nodes frozen, 568 instanced local-pose nodes elided, 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 draw units, 568 matrix uploads, and all 16 draw units finalized with frustum culling plus static instance matrices, 7 primitive geometry shapes cached, mesh source loading observed with a 24 source scheduling ceiling and peak concurrency 16 within that ceiling, 51 mesh source assets retained, 24/51 mesh cache hit/miss in the primary large scene, 16/0 fast OBJ parse/fallback in the controlled backend asset path, 568 virtual fixed instance roots, 68 manual roots, 631 cached object bounds, 627 fast pick-target bounds from 51 cached source bounds, real hover proof hoverProxy 2 with 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, 152-195 no-op loading frames suppressed during the primary load, 26 browser event-loop yields during scene construction, active state payload 34/602 with 1-2 reduced frames and 3 incremental body-map merges, semantic poll forwarding 2/2/4 parsed/forwarded/duplicate-skip, state-hash polling around 5-6 hash frames with 3-4 hash skips and 3-4 real 304 Not Modified responses, UI physics-profile cache around 25-27/3 hit/miss, UI builder-profile cache around 28-30/1 hit/miss, UI text write gating above 100 writes and 400 skips, text selector cache above 470/46 hit/miss, scratch bounds transforms 695, diagnostics panel throttling around 19 renders with scheduled skips, 83/631 hover targets over cached bounds used for bounds-only ray tests, and a stable paused backend state cache reported manual roots 68 updates 67 with state apply 0/skip 67.
  • Mesh cache lifecycle evidence: the Scene Builder compose switch reported 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.
  • 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 in objects, prewarm=0/0-1ms, finalize=1ms, and camera=0ms, proving object/asset construction dominates even after transport compression. Warm Scene Builder compose reports load=324-463ms, objects=318-456ms, prewarm=16/0ms, and finalize=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 16 instanced batches.
  • Asset payload diagnosis: the current Wuying-backed product manifest exposes 51 unique mesh source URLs totaling about 24.12 MiB by real GET transfer, split roughly into 18.76 MiB STL robot assets and 5.37 MiB OBJ 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-mode now requires objFast > 0, objLines > 0, objStream > 0, and objLoaderFallbackCount = 0 for the Wuying-backed store scene. The latest product release gate recorded objFast=16, objLines=173670, objStream=53/5628890B, and fallback=0, while uploaded/custom OBJ assets keep the full Three.js OBJLoader path for compatibility.
  • Controlled STL fast parse gate: the same performance gate requires stlFast > 0, stlTris > 0, stlBytes > 0, and stlLoaderFallbackCount = 0 for Wuying-backed standard binary STL robot meshes. The latest product release gate recorded stlFast=35, stlTris=393270, stlBytes=19666440B, and fallback=0. Uploaded/custom STL assets keep the full Three.js STLLoader path 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.body with TextDecoder chunks instead of materializing a full response.text() string or text.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 map parameter unless a texture actually exists. The quick browser performance check recorded 0 THREE.Material: parameter 'map' warnings, keeping console noise from hiding real asset/runtime issues.
  • Active-state gate: browser-large-scene-performance-mode now checks state payload 34/602 with 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-mode and browser-body-state-cache now 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-polling waits 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-mode now checks duplicate text-write skips, stable text-selector cache hits, and diagnostics-panel refresh skips, proving high-frequency /state polling does not force unchanged diagnostics DOM writes or repeated selector queries every frame.
  • Stats refresh gate: browser-large-scene-performance-mode now 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-coalescing performs 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 and drag=move/applied/coalesced.
  • WebGL readback gate: browser-large-scene-performance-mode now checks buffer=false and readback=1, and browser-debug-capture-png checks 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-cache waits for the paused scene to use a reduced active payload and still skip unchanged active poses. The current run passed with state apply 0/skip 67, statePayload=34/602, and incremental=2.
  • Robot safe-pose gate: verify-real-backend-editing now checks robot-safe-initial-pose, with the latest composed scene reporting pelvis=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-mode now checks bounds cache 631 and camera traversals 0.
  • Pick-proxy bounds gate: browser-large-scene-performance-mode now checks fast=627, scratch=695, and source=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-mode now checks prefrozen + instanced >= repeated mesh threshold and spinSkip=627, proving repeated mesh assets avoid re-traversing static visual subtrees and non-spinning clone trees.
  • Instanced mesh gate: browser-large-scene-performance-mode now checks instanced=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 requires frozen + elidedLocal >= 500, so removing local-pose nodes cannot be mistaken for losing static-scene optimization coverage.
  • Hover bounds gate: browser-hover-proxy-bounds moves the mouse over the real canvas and now checks both hoverProxy and cached hover bounds increase while 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.
  • 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.

Control evidence:

  • Cold compose endpoint: 366ms, 4/4 composed object bodies synced, with resetApplied=true when requested by the Scene Builder restore path.
  • Repeated compose cache: 54ms, cached=true, same compose key, and resetApplied=true, so the frontend no longer needs a second /control reset request after a cached compose restore.
  • JSON transport compression: /compose and /manifest wire payloads are about 11 KiB after gzip instead of about 257 KiB uncompressed.
  • Mesh transport compression: /assets/... responses for compressible geometry formats expose raw and wire byte counts and are verified with a real asset fetch by verify-real-backend-editing; the current STL proof is 2570584 -> 1046563 bytes. The bridge also exposes X-Motrix-Asset-Cache; the verifier now requires the selected GET probe to report cache=hit after HEAD prewarming, proving repeated compressed asset responses do not re-read and re-gzip the large source file.
  • Active state endpoint: full /state returned 602 bodies; active /state?bodies=active returned 34 bodies in 58ms, filtered 568 fixed bodies, and retained 4/4 composed dynamic bodies.
  • Scene Builder UI compose: representative run 3817ms end to end with real backend diagnostics.
  • Share-link restore: representative full browser restore 9513ms; builder telemetry splits it into compose=292ms, preview=2045ms, state=6ms, synchronous stats=0ms, asynchronous pixelWait=2174ms, and pixel=1470ms.
  • Config import restore: representative full browser restore 17433ms; builder telemetry splits it into compose=551ms, preview=4815ms, state=9ms, synchronous stats=1ms, asynchronous pixelWait=6276ms, and pixel=2325ms.
  • Composed object body edit: 47ms.
  • Fixed inventory edit rejection: 63ms.
  • Dynamic composed object drop: 0.48012m.
  • Static shelf anchor stability: max drift 0.00000m after 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 /state returns full body poses for visual synchronization.
  • GET /state?bodies=active returns robot/state bodies and user dynamic bodies after the first full frame, avoiding repeated fixed shelf/inventory payloads.
  • GET /state?compact=1 returns lightweight control status.
  • POST /control supports compact responses for controls and edits.
  • Pause/resume/toggle use a fast backend control path.
  • The frontend records direct compact /control responses 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.dataset and window.__motrixControlTelemetry for acceptance and diagnostics.
  • Acceptance self-check telemetry is published on document.documentElement.dataset and window.__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:

  1. npm run real-backend:doctor
  2. npm run verify:real-backend -- http://127.0.0.1:18090/manifest
  3. test-results/product-readiness/product-readiness-report.json
  4. Browser screenshots in test-results/product-readiness/ include product-readiness-builder-compose.jpg, product-readiness-desktop.jpg, and product-readiness-mobile.jpg.
  5. UI export artifacts in test-results/product-readiness/ include product-readiness-acceptance-package.json and product-readiness-acceptance-report.html.
  6. Rendered report evidence includes product-readiness-acceptance-report.jpg.
  7. Remote bridge log: /tmp/motrix_bridge_18090.log on 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 /compose for 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 /compose adapter 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 /state streaming 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 631 objects and 627 meshes, 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-211ms range across recent release checks, and repeated compose cache with reset is about 55ms.
  • 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 about 9-18s end to end in full browser page load, compose restore, asset setup, pixel proof, and screenshots. Internal builder telemetry is lower: share restore reports roughly telemetry=2.0-2.4s, compose=0.29-0.31s, preview=1.7-2.1s, state=6-8ms, stats=0ms; config import reports roughly telemetry=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 0ms while pixel proof runs in the separate pixel telemetry stage.

Handoff Criteria

Before calling a build acceptable for demo or review:

  1. npm run product:release-check passes.
  2. The generated report has 0 failed and 0 warned.
  3. Scene Builder compose screenshot shows the real product UI after the backend physical composition workflow.
  4. Desktop screenshot shows a nonblank real 3D scene.
  5. The UI shows 外部仿真 and 后端物理.
  6. Pause/resume visible state latency is below 3000ms.
  7. The browser gate shows the Scene Builder physics switch workflow reaches backend physical composition.
  8. The browser gate proves UI export buttons download a valid JSON acceptance package and HTML acceptance report.
  9. The browser gate proves the downloaded HTML acceptance report renders with readable acceptance evidence.
  10. verify:real-backend shows real /compose, composed object body sync, fixed inventory protection, dynamic object drop, and fixed shelf stability.
  11. Any new physical asset type has an explicit backend compose/export path.