# Viewer loading and memory

Fetch the component LOD manifest first and load super-low by default. Fetch higher detail only when projected component size justifies it. Keep the coarse model visible while a higher level loads; ignore/cancel stale requests if the camera moves away. Avoid loading all high levels and merely hiding them: that still retains CPU/GPU memory and can freeze the user's shared desktop.

Use Babylon's native LOD mechanism where compatible with the model structure; a multi-node component with markings and terminals must change detail as one coherent unit. Screen coverage is usually a better signal than world distance because package size, camera FOV, viewport size and scaffold scale vary. Keep consistent transforms across levels. Test the chosen Babylon version, including instancing and node hierarchy limitations.

Add hysteresis and a short settle period so a component near a threshold does not repeatedly swap or download. Share downloaded geometry/materials by asset hash across identical MPN instances while retaining per-instance component reference, hover, LED state and joint transforms. Do not let joining geometry destroy those identities. Use bounded concurrent requests and retain explicit ownership/refcounts for shared resources.

Test the actual selection/highlight API with the chosen representation. Babylon's HighlightLayer in the tested Babylon 9 integration cannot accept InstancedMesh in the same way as Mesh: adding an instance failed on a missing observable. Mesh clones that share geometry and materials provided independent reference highlighting in that integration. This is a compatibility observation, not permission to duplicate all vertex buffers. Verify sharing and disposal with the installed viewer version. Multi-node parts may need an explicit whole-hierarchy selector around AssetContainer rather than independent per-mesh LOD switches; report which mechanism the app actually implements.

Deduplicate by content hash, not only MPN or filename. Several simple coarse parts can share identical geometry while their high versions carry different exact MPNs. Keep the reference's own manifest for selecting its next level. Request cancellation must check whether ANY live reference wants the hash, including references with another component record. Bound retries and keep the current visible detail while reporting a failed high-detail request; do not repeatedly fetch a missing file every animation frame.

Selection, residency and rendering are separate controls:

- Native LOD decides what draws.
- An asset cache decides what is downloaded/decoded and resident. Evict inactive expensive levels by a documented budget/LRU policy. Dispose unused GPU buffers, textures, materials and asset containers only when no instance needs them. Keep the super-low fallback available. Removing a mesh from the view is not proof that memory was freed.
- A render scheduler draws only when there is motion, interaction, changing telemetry or an invalidated view. Stop hidden/offscreen views and idle render loops. Cap active frame rate appropriately for a CAD work surface, and resume on pointer/camera changes, resizing or real animation. Pause background recording/rendering when the user reports slowdown.

When replacing Babylon's `engine.runRenderLoop` with an on-demand scheduler, preserve the engine frame lifecycle: `engine.beginFrame(); try { scene.render(); } finally { engine.endFrame(); }`. Calling only `scene.render()` leaves the engine frame counter unchanged in the tested integration. ObjectRenderer then keeps allocating per-frame scene uniform buffers for shadow/highlight passes instead of resetting their reuse index. This bug can survive perfect component-cache eviction tests. Check engine frame advancement and live WebGL buffer counts across repeated interaction, not only the app's asset registry. Do not patch the shared installed viewer to fix one app; change and validate the app-owned scheduler, then report reusable improvements to the owning project.

Choose explicit startup, resident-memory, triangle, draw-call, texture and concurrent-load budgets for the actual deployment. Report limits and observations to the AI. Do not label an estimate as measured GPU memory. Include loaded level per reference, in-flight requests, cache hits, resident asset counts/bytes, evictions, scene mesh/primitive counts, frame timing and render-paused state in a read-only diagnostic endpoint. Budget refusal should explain what to reduce or regenerate; never silently drop expected chips or hide lost markings as a performance fix.

Runtime/source version, generated assets, installed package and painted UI are separate evidence. Do not claim streaming/eviction works merely because `addLODLevel` was called.

Primary reference: [Babylon LOD](https://doc.babylonjs.com/features/featuresDeepDive/mesh/LOD/).

## Image-first component-page LOD widget

Show cached PNG/WebP previews of the actual four board-use LOD files by default. Use the same camera, framing and lighting to make comparison meaningful; record the corresponding GLB hash in each preview entry and invalidate stale screenshots. No WebGL context, Babylon import or GLB downloads until the user enables the interactive preview.

On enable, use one viewer starting with super-low, then load/swap detail as the user zooms with hysteresis and eviction. Show the active level truthfully. Turn off must abort pending loads and dispose the scene, engine and GPU resources. Release on hidden tab, offscreen widget or disconnect, and coordinate to avoid multiple active previews. Test repeated enable/zoom/disable cycles and actual live wiki authentication, CSP and module-loading behavior. A passing local harness does not establish live wiki behavior.

## Wiki sandbox and private component files

Use the current `component-widgets` skill for authenticated on-demand loading. The registered widget receives server-inlined JSON; that does not authorize credentialed GLB fetch from its opaque origin. Component-owned `*.frame.html` transports can load under normal wiki page authorization only when requested, transfer the selected GLB bytes to the exact parent request, and be removed immediately. Verify source iframe, nonce, SHA-256, size and cancellation; pass verified bytes directly to Babylon instead of fetching a disallowed blob URL. Never weaken the sandbox or expose private models publicly. The direct GLB remains the canonical reusable board file.

Web Storage can be unavailable in sandboxed frames. Use ephemeral preferences only when real storage access throws. Shared-viewer environment textures and ready/error reporting require explicit sandbox checks. Local model/resource tests and the actual deployed viewer's appearance are separate evidence. Wiki frames may be lazy-loaded: reveal the relevant section and wait for the actual frame/context before interacting. Preserve the user's editor pane and foreground.