Files
workinf_Blender_Wasm/docs/web/KNOWN_LIMITATIONS.md
mes123456 4eb08faf31 chore(web): checkpoint export fixes, operator routing and three-domain evidence
- Web engine CMake: apply WITH_WEB_USD_PYTHON to blender_web_engine_core,
  embed /usd resources, link pxr Python bindings after the core archive and
  whole-archive the monolithic OpenUSD archive. Fixes the wm.usd_export abort
  and restores Alembic/USD embedded export.
- ?ui=web menus: fix inverted localOnly gating and route queueLocalDesktopOperator
  and nativeAdd through the desktop operator channel with a VIEW_3D context;
  non-mesh edit-mode selection uses the native VIEW3D_SELECT bridge.
- Refresh WebEngine wasm/js artifacts, manual/course pages and the complete
  course video asset.
- Record focused Chromium probes for Add/F3/parameters/modifier/UV/curve/deform,
  scene operations, OPFS save/reopen and worker restart. Evidence is NOT_CLAIMED.

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-11-14 06:12:44 +08:00

70 lines
4.6 KiB
Markdown

# Web Blender Modeler V1 Known Limitations
These limits apply to `0.1.0-rc.1`. A successful bounded gate is scoped to the declared operation,
fixture, resource budget and browser configuration. The capability claim is the 31/31 support
matrix in `tools/web/manual/feature-matrix.json` (local or official server/native backend), enforced
by `tools/web/check-parity-claim.mjs`. See [V1_SCOPE.md](V1_SCOPE.md) for the normative product
boundary; the legacy `parity-ledger.json` is historical planning data.
## Browser and deployment
- Chromium is the only V1 browser baseline. Firefox, WebKit, mobile browsers, touch, pen, IME and
non-Chromium accessibility compatibility are not release claims.
- Production requires HTTPS. `http://127.0.0.1` is allowed for local verification; public plain HTTP
and `file://` are unsupported. All app, Worker and engine assets must remain same-origin.
- The base viewport uses WebGL2. OffscreenCanvas is a second tested production path. WebGPU is used
only for the declared bounded NanoVDB path and is subject to adapter availability and limits.
## Single-thread and pthread selection
- `AUTO` selects pthread only when `crossOriginIsolated`, `SharedArrayBuffer` and Worker capability
gates are all ready. Otherwise it selects the single-thread variant and reports the pthread gate.
- A pthread initialization failure under `AUTO` is cleaned up before one single-thread attempt. A
resource request failure outside this path remains an error.
- A JS, WASM or pthread Worker SHA-256 mismatch is fatal
(`ENGINE_VARIANT_INTEGRITY_FAILED`): there is no integrity fallback and no project is opened.
- `PTHREAD_REQUIRED` blocks when its platform gate is not ready. `SINGLE_REQUIRED` never attempts
pthread. A mixed app/manifest `releaseId` returns `REFRESH_REQUIRED` before engine initialization or
project open; a full reload is required.
- Both variants declare 256 initial WebAssembly pages (16 MiB) and a 32,768-page ceiling (2 GiB).
This is a manifest ceiling, not a memory reservation or availability guarantee; Chromium, the OS or
the device can reject growth earlier.
## Project storage
- OPFS and IndexedDB are bound to the exact scheme, host and port. Moving between origins does not
migrate projects. Clearing site data or a browser profile deletes locally stored projects and caches.
- Chromium and the operating system control quota. V1 reserves no minimum capacity and cannot infer
that `navigator.storage.estimate()` free space will remain available through a save.
- Atomic save preserves the last committed revision on quota failure, but the new revision is not
durable until save succeeds. Export critical projects before upgrades and before deleting caches.
- IndexedDB schema migration is forward-only. OPFS project manifest schema has no general reverse
migration. An older app is blocked when it cannot read the current schema.
## CPU, WASM and GPU budgets
- The RC gates cover 100k, 1M and 10M geometry fixtures; they are not an unlimited scene-size claim.
Imports and operations can block earlier when their own vertex, element, transfer, time or memory
budgets are exceeded.
- A texture asset is limited by protocol to 64 MiB, 16,384 pixels per dimension and 256 requested
assets per scene. The actual WebGL `MAX_TEXTURE_SIZE`, address space and GPU memory may be lower.
The release gate exercised 4K and 8K textures, not every format or 16K residency combination.
- VDB input is bounded to 512 MiB, a NanoVDB bundle to 1 GiB, each chunk to 16 MiB and declared GPU
residency to at most 512 MiB. Actual `maxStorageBufferBindingSize` and `maxBufferSize` may be lower.
- NanoVDB pages are explicit and LRU-bounded. Automatic viewport page-fault feedback, depth-composed
production demand paging and an unbounded multi-grid material system are not included in V1.
- GPU device loss or budget failure releases and recreates viewport resources where supported; it does
not modify Blender Main or OPFS project bytes. A reduced scene or budget may still be required.
## Blender feature scope
Complete PBVH sculpt/paint, arbitrary Geometry Nodes and Shader evaluation, full physics solvers,
Cycles, final video encoding, Python/Text autorun, add-ons and native GPU backends are either bounded,
server-only or excluded. The exact family slices and stable blockers are in
[parity-ledger.json](parity-ledger.json); unsupported data must be preserved or explicitly blocked,
not reported as executed.
Use [DEPLOYMENT.md](DEPLOYMENT.md) for installation and rollback requirements, and
[operations-diagnostics.json](operations-diagnostics.json) for stable failure signals and data-safe
recovery boundaries.