935 lines
54 KiB
Markdown
935 lines
54 KiB
Markdown
# 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.
|