MotrixSimWeb/docs/product-readiness.md

935 lines
54 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
```mermaid
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
```bash
npm install
npm run real-backend:up
npm run dev -- --port 5173
```
Open:
```text
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:
```bash
npm run product:release-check
```
This expands to:
```bash
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:
```text
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.