@preference-sl/pref-viewer 2.18.0 → 3.0.0-beta.1

package/README.md

@@ -6,7 +6,7 @@
 
 - Native custom elements: `<pref-viewer>`, `<pref-viewer-2d>`, `<pref-viewer-3d>`, `<pref-viewer-dialog>`, and `<pref-viewer-menu-3d>`.
 - Babylon.js-based 3D visualization for glTF and GLB assets.
-- Default-enabled, draggable 3D ViewCube with 26 selectable orientations: click a face, edge or corner for a smooth, model-fitted view, or drag the cube to orbit the model. It follows the camera in real time, including its projection: the cube is orthographic for an orthographic viewer camera and perspective, with the same vertical FOV, for a perspective one.
+- Default-enabled, selectable SVG or Canvas 3D ViewCube with 26 selectable orientations: click a face, edge or corner for a smooth, model-fitted view, or drag the cube to orbit the model. It follows the camera in real time, including its projection: the cube is orthographic for an orthographic viewer camera and perspective, with the same vertical FOV, for a perspective one.
 - Model-only, geometry-dependent orbital zoom protection with near-plane sampling, independent of ViewCube visibility.
 - Viewer dialogs above the render menu and ViewCube, with background pointer-input protection.
 - Proportional mouse-wheel zoom for unlocked orbital cameras: increments decrease as the camera approaches its target, using Babylon's native input without an additional viewer zoom increment. Wheel sensitivity is currently an internal setting, not a public attribute or option.
@@ -20,6 +20,36 @@
 - Export helpers for model, scene, or combined model + scene downloads.
 - Type declarations for TypeScript and JSX usage.
 
+## AR support
+
+| Browser/platform | Viewer route |
+| --- | --- |
+| Android Chrome with confirmed `immersive-ar` and native plane hit-test support | WebXR AR at authored metre scale |
+| Eligible Safari on iOS/iPadOS without WebXR AR support | AR Quick Look using a client-generated USDZ of the current visible model |
+| Other browsers without a supported AR route | No AR action |
+| iPhone VR | Not implemented |
+| visionOS WebXR VR | Platform capability; this viewer does not implement `immersive-vr` |
+
+Android WebXR preserves the glTF's authored metre dimensions, including existing unit-conversion transforms. It never fits the model to the screen or permits pinch scaling. Assets must encode their dimensions in metres and orient their interior toward the viewer's existing Inner (+Z) direction; the viewer cannot infer an interior face or correct arbitrary source units. The upstream exporter owns those asset conventions.
+
+During Android WebXR AR, model materials using physical transmission/refraction or translucency temporarily use alpha blending so the camera background can show through the glass. This is a scalar approximation: full transmission uses 0.35 opacity, combined with existing geometric opacity; linked-refraction alpha is interpreted as transmission rather than geometric opacity. Colors, textures and reflection parameters remain unchanged, but physical camera refraction, blur and transmission texture masks are not reproduced. Opaque and existing ordinary alpha-transparent materials are left alone. Original glass values are restored on exit/cancellation, model or material replacement and teardown; normal 3D and Quick Look preparation outside WebXR retain their original materials. The fallback also applies to the no-floor preview. Shared material objects are adapted once and restored together. Real Android glass appearance still requires a device check.
+
+On AR entry, the virtual environment is hidden. If no qualifying floor is available, the first finite native camera pose centres the preview two metres along its view ray, retaining the authored dimensions, with Inner facing the phone horizontally. The preview retains its initial world position and yaw instead of following the phone, and cannot be dragged. It is not a verified physical anchor or calibrated 1:1 measurement; erroneous native camera motion can still change its apparent size and position. Pending, failed or empty hit tests do not prevent this preview. A missing native camera pose still prevents initial placement. When a native horizontal-plane hit below the phone becomes available and the phone has a usable horizontal heading, the preview transitions to floor placement: its bottom centre is placed on that height, with its phone-facing orientation corrected by the minimum yaw to align model axis lines with the detected floor axes (nearest multiple of 90 degrees, at most 45 degrees correction). The preferred initial distance is three horizontal metres ahead. Optional native plane detection supplies a floor contour; the viewer checks the full horizontal bounding footprint at its authored scale and initial yaw. If it cannot fit at three metres, it uses the farthest fitting centre on the same forward segment up to three metres. If contours are unavailable/unusable or no full fit exists, it provisionally places the model at three metres without a fit guarantee. Later contour changes never reposition an already placed model. This transition can move the model visibly. It stays in world space as the user moves. The detected horizontal plane pose supplies the grid axes independently of contour-fit availability: a contour containing the accepted hit takes priority, otherwise the horizontal pose below the camera nearest in height to that hit is used (horizontal proximity breaks ties). Without a usable native pose, the X/Z axes of the WebXR tracking reference space provide the reported fallback. Pose-only orientation never changes the retained floor height or guarantees that the footprint fits. Diagnostics report `floorAlignmentSource`, `floorAlignmentStatus`, `floorAlignmentYaw` and `floorAlignmentHeightDifference`. The grid is frozen for model initial placement and gesture feedback; later camera/contour changes do not re-snap the model. Touch the model and drag with one finger to translate it on the retained floor plane, keeping the grab offset. A short tap outside the model places its bottom centre at the tapped point on that plane. Placement commits on release; moving the finger by more than one degree of ray direction cancels an off-model tap, even if it returns to its starting point. Adding a second tracked finger cancels translation or a pending floor tap and starts two-finger rotation around the vertical bottom-centre axis. Rotate the two fingers to change yaw (the rotation sense is inverted from the preceding implementation); pinching never changes scale. The bottom anchor stays fixed. Lifting either finger, a third finger or lost input cancels rotation; lift all fingers before starting another translation. This requires the Android runtime to expose both screen input sources. Fresh surface hits are not required after floor detection: other-height surfaces do not change the retained height. Missing/invalid input tracking, rays parallel to the floor or intersections behind the camera retain the last placement. This uses the mathematical plane at the observed height and does not verify its physical extent or rule out obstacles. WebXR does not universally distinguish a floor from a table. A contour fit checks the reported approximate surface, not obstacles or physical room boundaries; provisional placement provides no contour-fit guarantee. Leaving AR restores the authored model transforms and environment. `getDebugInfo().ar` reports placement state, metre units, initial distance, position and drag state. The diagnostic state `preview` distinguishes the camera-based fallback from `placed` on a detected floor; the fallback does not claim a detected floor or solve native calibration/tracking failures. Large models may extend beyond the viewport because their authored scale is preserved. The no-floor preview remains centred two metres along the initial camera ray.
+
+After floor placement, a reticle marks a pending off-model floor tap and briefly confirms a committed destination. Four floor-space arrows indicate model dragging, with movement direction highlighted using the current primary style (`styles.colorPrimary`, scoped to the owning viewer), including runtime updates; curved arrows indicate rotation and highlight its actual direction with the same primary style. A committed floor tap briefly highlights the entire reticle. Reticles and arrows are flat, double-sided surfaces without tubular sections or side walls. Reticle circle/cross strokes are 8/2 cm wide, retaining the 40 cm centreline circle diameter and 16 cm total cross span. Both use exterior-only 1 cm contours; the cross is one joined surface. Translation/rotation arrow bands are 8 cm wide with filled heads measuring 24 cm across the base and 10 cm from base to tip. Each arrow uses one continuous shaft-and-tip surface and an exterior-only contour offset by 1 cm, preventing accumulated transparency at the join. Indicators use black outlines at 40% opacity and fully opaque white/primary foregrounds, with a narrower reticle stroke and wider arrow shafts. Their materials bypass scene exposure, tone mapping, postprocess linear-color output and fog to preserve UI sRGB colors; portions hidden by opaque model geometry remain faintly visible without changing model transparency. Feedback clears on release/cancellation or lost tracking and is excluded from model and full-scene downloads. These markers use the retained mathematical plane and do not certify new surface coverage or obstacle clearance. Native Android rotation and camera-overlay appearance still require physical-device validation.
+
+The stationary fallback preserves authored dimensions but cannot compensate unreliable native tracking or guarantee constant projected appearance. Native calibration/tracking remains necessary for reliable physical scale and spatial anchoring.
+
+Android placement and gestures have automated coverage using real Babylon geometry and simulated native XR frames. AR entry wakes the idle renderer and keeps Babylon's native frame pump running through entry, AR and exit; ordinary 3D can become idle again afterward. Observed floor height is retained while lifting the phone to a usable heading, even if the centre ray stops hitting that floor; a reference-space change or session exit discards it. `getDebugInfo().ar.floorHeight` reports the observed height. A regression check exercises the installed Babylon session manager through model visibility on a simulated floor hit. Galaxy Tab S8 Ultra captures confirm accepted floor placement and native transient-hit dragging in depth after correcting the finger subscription. Lateral hits on other levels exposed the limits of fresh-hit-only dragging; the user selected retained-plane dragging and off-model tap placement. The user confirms lateral dragging and off-model floor taps work on the Galaxy. A subsequent native retry delivered three detected planes and exercised provisional three-metre placement when no full fit existed. Successful bounded fits are covered by automated native-contour fixtures; physical dimensions and camera alignment remain separate acceptance checks.
+
+While AR waits for floor placement (including `preview`), `getDebugInfo().ar.diagnostics` distinguishes delivered XR frames (`frames`), tracked poses (`trackedFrames`), native source setup (`hitTestStatus`), the current wait stage (`phase`) and placement hit counts (`lastHitCount`/`maxHitCount`). `lastSurface` records the latest checked plane position, normal, camera height and acceptance/rejection reason; `lastError` records a source-setup failure. `sessionActive`, `referenceSpaceReady` and `floorSourceActive` report current resource availability. These diagnostics are bounded snapshots, with no frame history. After exit, `diagnostics.ended` is true and the last attempt remains inspectable until the next entry; placement and scene state still reset normally. `floorHeight: null` alone cannot distinguish missing native hits from surfaces rejected by the filter. `ar.initialDistance` is the preferred floor distance (3 m); `diagnostics.placementDistance` records the actual initial floor distance. `placementStatus` is `bounded-fit`, `provisional-no-contour`, `provisional-no-fit` or `not-placed`; `floorBoundsStatus` and `detectedPlaneCount` explain contour availability at initial placement. Those diagnostics do not change when a user later repositions the model. `floorAlignmentSource` distinguishes `detected-plane`, `reference-space` and `not-placed`; `floorAlignmentYaw` and `initialYaw` record the frozen floor-frame and initial model yaw in radians.
+
+On eligible Safari, the AR control uses the existing XR appearance and position. The viewer prepares USDZ after model/material loading; the control becomes usable when that preparation finishes. Updates invalidate the previous file. A failed preparation offers a retry through the same control. No new public method or configuration is required, and the existing USDZ download methods remain downloads.
+
+The link uses `rel="ar"`, `download="model.usdz"` and a `model/vnd.usdz+zip` Blob URL with the `#allowsContentScaling=0` fragment, so its native navigation runs directly on the user tap and Quick Look keeps the authored real-world size (no pinch scaling, as on Android WebXR). Only model meshes with supported materials and current visibility are exported. Environment and viewer overlays are excluded. Physical transmission glass is exported with an equivalent alpha opacity, because USDZ has no transmission. The viewer bundles the `fflate` helper the exporter needs, so no request to `unpkg.com` is made.
+
+Manual iOS Quick Look validation has been reported: its AR button remains usable even when the Babylon 3D view is empty. The empty scene/model failure has also been reproduced on an iPhone and remains unresolved; Quick Look validation does not establish successful in-page 3D rendering. Device/browser versions and itemized scale, glass, texture, close/reopen, iPad and production-iframe results were not supplied, so those details remain unconfirmed. Safari remote inspection is unavailable in the current test setup because no macOS system is available. An iframe must permit the browser's native AR/navigation behavior; no automatic top-level redirect or parent-message protocol is added. Used Blob URLs are retained through model replacement/detach until an observed browser return; if Safari emits no return signal, their lifetime ends with the document.
+
 ## Installation
 
 ```bash
@@ -96,7 +126,7 @@ viewer.setOptions({
 
 ## Configuration model
 
-The main `config` payload can include model, scene, materials, drawing, options, culture, styles, and boolean `showRenderMenu` / `showViewCube` flags.
+The main `config` payload can include model, scene, materials, drawing, options, culture, styles, boolean `showRenderMenu` / `showViewCube` flags, and optional `viewCubeRenderer` (`svg`/`canvas`).
 
 When a queued configuration is processed, explicit boolean flags update the corresponding `show-render-menu` and `show-view-cube` attributes before its assets load. Omitted or non-boolean flags preserve the current settings. Explicit processed flags override the corresponding current attributes; subsequent direct attribute changes remain effective. Reapplying an equal attribute value does not recreate the render menu. The same rules apply to `loadConfig(config)`, the `config` property setter and the JSON `config` attribute; flags follow existing task ordering, including during pending asset loads. These fields belong to the root config, alongside `culture` and `styles`.
 
@@ -234,8 +264,10 @@ Storage descriptors are passed through `model.storage`, `scene.storage`, `materi
 | `show-model` | Shows or hides the current 3D model. Use `true` or `false`. |
 | `show-scene` | Shows or hides the current 3D scene/environment. Use `true` or `false`. |
 | `show-render-menu` | Shows the floating 3D render settings menu when absent or `"true"`; `"false"` hides it. Also configurable through boolean `config.showRenderMenu`. See [ViewCube layout](#viewcube-layout-and-lifecycle). |
+| `view-cube-renderer` | `canvas` (default) or `svg`. Also available as the `viewCubeRenderer` property on root and standalone 3D. Invalid/missing values select Canvas. Changes replace only the cube, preserving model/camera state and visibility. |
+| `controls-density` | `auto` (default), `compact`, or `comfortable`. Auto uses comfortable controls for a primary coarse pointer. Changes apply immediately without reloading assets. Also supported on standalone `<pref-viewer-3d>`; nested 3D inherits the root preference. Invalid/missing values use auto. |
 | `show-view-cube` | Shows the orientation cube in 3D. Enabled by default; only literal `"false"` disables it. Also configurable through boolean `config.showViewCube`. Runtime toggles preserve loaded assets and camera state. See [ViewCube](#viewcube). |
-| `styles` | JSON string with supported style overrides. Currently supports `colorPrimary`, applies it as `--pref-viewer-color-primary`, updates `PrefViewerStyleVariables.colorPrimary`, and persists it in `localStorage`. |
+| `styles` | JSON primary/ViewCube appearance patch; same schema as `setStyles()` and `config.styles`. Null leaves/groups reset customizations. See [Runtime styles](#runtime-styles). |
 
 ## ViewCube
 
@@ -258,7 +290,7 @@ The inner view is the principal model view. English ViewCube face labels read `I
 
 The cube is drawn on its own small canvas, with a separate Babylon.js engine and virtual scene, in a PrefSketch-style look: six square labelled faces, thin bars on the twelve edges and small spheres on the eight corners; there are no chamfers. Every part of an edge or corner selects the same orientation. The cube follows the projection and FOV of the viewer camera: it is drawn with an orthographic camera when the viewer camera is orthographic, and with a perspective camera using the same vertical FOV when it is perspective (the cube keeps the same on-screen size either way, and an FOV change redraws it). Apart from that it follows only the direction of the camera, independent of model zoom. It lives in its own scene, so it adds nothing to the model scene, to model picking or to exports.
 
-Hover paints the region under the pointer with `styles.colorPrimary` (`--pref-viewer-color-primary`). Any CSS colour syntax is accepted: hex, `rgb()`, `hsl()` or a named colour. The angularly nearest of the 26 views is shown as the current region, painted with the primary colour mixed 25% into the face fill; hover takes precedence until the pointer leaves. A primary-colour change is picked up within 250 ms, or immediately after a resize, a culture change or re-enabling the cube. The rest of the palette (face fill, borders, label text, edge bars and corner spheres) is a fixed light palette and is not configurable. There are no region tooltips.
+Hover paints the region with the configured hover color (primary by default), using 50% blend strength; the nearest of 26 orientations is active at 15%. Hover takes precedence. Palette and label typography are configurable through `styles.viewCube` for both renderers, including runtime updates while idle. Canvas neutralizes base hue before highlight blending, then applies its own lighting. No region tooltips are provided. See [Runtime styles](#runtime-styles).
 
 Edges and corners are thin, so selection has a tolerance: a front-facing edge or corner whose centre is within 8 CSS pixels of the pointer is picked ahead of the face under it, corners before edges. On cubes smaller than 96 px the tolerance shrinks to a twelfth of the cube side so face centres stay selectable. Hover and click use the same pick, so the highlighted region is the one a click selects.
 
@@ -266,7 +298,7 @@ Edges and corners are thin, so selection has a tolerance: a front-facing edge or
 
 Press on the cube and move the pointer more than 3 CSS pixels to drag it. Dragging orbits the viewer camera around its target at 0.012 radians per pixel, in the same direction as dragging the model with the mouse on the main canvas: the model follows the pointer, and the cube follows the camera. Elevation stops just short of the poles and the camera keeps world +Y as up. Dragging works with ArcRotateCamera, FreeCamera and UniversalCamera; authored alpha/beta limits of an ArcRotateCamera keep being enforced by Babylon on the next frame.
 
-The whole cube canvas is the drag surface, including its transparent corners, and a press on it never starts a gesture on the main camera. A press that moves 3 pixels or less is a click. A drag never selects a region, even if it ends where it started, and it cancels a running click transition. Locked cameras, active XR tracked cameras and unsupported camera classes keep the cube display-only. The cursor is `grab` over the cube, `pointer` over a selectable region and `grabbing` while dragging.
+The whole cube canvas is the drag surface, including its transparent corners, and a press on it never starts a gesture on the main camera. A press that moves 3 pixels or less is a click. A drag never selects a region, even if it ends where it started, and it cancels a running click transition. Locked cameras, active XR tracked cameras and unsupported camera classes keep the cube display-only. The cursor is the default outside selectable regions, `pointer` over a selectable region, and the shared custom rotation cursor during dragging.
 
 ### ViewCube accessibility
 
@@ -274,15 +306,9 @@ The cube canvas has `role="img"` and one localized accessible name (`View orient
 
 ### ViewCube layout and lifecycle
 
-The cube is a square at the top right of the 3D view: **top 0px**, **right 0px** unless the host sets the inset below. Its side, in CSS pixels, is `min(clamp(22% of min(viewer width, viewer height), 96, 180), 40% of min(viewer width, viewer height))`, rounded to an integer. For example, a viewer whose smaller side is 300 px gets a 96 px cube, 600 px gets 132 px, 900 px or more gets the 180 px maximum, and a 200 px viewer gets 80 px (the 40% cap). A viewer without a usable size shows no cube.
-
-Hosts can inset the cube from the right edge with the CSS custom property `--pref-viewer-view-cube-inset-right` (default `0px`). Set it on `<pref-viewer>` or on any ancestor; it inherits into the viewer:
+Both variants are square widgets at the top right of the 3D view: **top 0px**, **right 0px** by default. Both variants use the same CSS square size: 120 px compact and 140 px comfortable, capped to the smaller available viewer dimension. A viewer without a usable size shows no cube.
 
-```css
-pref-viewer {
-  --pref-viewer-view-cube-inset-right: 24px;
-}
-```
+External CSS inset tokens are no longer a supported customization mechanism on `<pref-viewer>`. Control layout is managed internally.
 
 When both overlays are enabled, the render-menu top equals the **measured side of the cube canvas** and updates when that size changes; the menu offset is measured, not a fixed value. Without the cube, the menu returns to its style-defined default top. The cube remains below the menu's layer, and viewer modals cover both. The internal `view-cube-layout` event carries `{ offset, height }` in CSS pixels: `offset` is the measured cube side (0 when there is no cube) and `height` is the scene viewport height.
 
@@ -290,7 +316,9 @@ Cube resources are created only while enabled in a visible 3D view. Disabling it
 
 Rapid selections retarget the transition from the displayed pose. Canvas pointer/wheel/key interaction, resize, projection change, camera/model replacement, locking, disabling or disposal cancels pending navigation; unlocking/reactivation does not replay it. Transitions use the existing demand-rendering scheduler and release their activity when finished without stopping unrelated model animations.
 
-## 3D camera and wheel zoom
+## 3D camera, wheel and touch zoom
+
+Unlocked orbital cameras use Babylon's native distance-proportional zoom for both the mouse wheel and two-finger pinch. The same pinch movement produces a smaller absolute increment as the camera approaches its target. Both inputs retain native inertia and the existing model geometry zoom guard. Two-finger touch uses an internal pointers-input class that compares accumulated separation and midpoint movement, batching finger events per camera frame. Motion is deferred while ambiguous: separation changes of at least 3 CSS pixels favor pinch; parallel translation needs at least 6 CSS pixels with relatively stable separation. Intent is confirmed for 32ms before movement is applied, then stays fixed until release. For cameras with mouse-location zoom enabled (including the default camera), a pinch uses the midpoint between the fingers as its focal position: radius and target move together toward the visible model surface there, with the same target-plane fallback as the mouse wheel on a miss. The focal point stays at the same screen position for a stationary midpoint. Authored cameras with mouse-location zoom disabled retain radial pinch; their preference is preserved. Parallel movement remains a separate pan gesture without zoom and cancels any remaining focal-zoom glide. Focus loss or input detachment also cancels that glide; ordinary finger release retains native inertia. Pending movement is discarded on cancellation/focus loss/detachment. Babylon still calculates proportional zoom and panning; its per-event 20px onset threshold is not used. One-finger orbit and mouse panning remain available. Their internal sensitivities are separate: `BabylonJSController.config.camera.wheelDeltaPercentage` defaults to `0.015`, and `pinchDeltaPercentage` to `0.001`, because Babylon measures pinch changes using squared finger separation rather than wheel deltas. Natural pinch's direct-radius override is disabled when an orbital camera becomes interactive. These are internal runtime settings, not new viewer attributes or public options.
 
 The default orbital camera starts on the **Inner (+Z)** side before the ViewCube is created, so the loading indicator does not first show Outer and then switch to Inner when model framing completes. The initial fit uses the same model bounds and projection-aware calculation as the ViewCube, with the shared framing factor (`BabylonJSController.config.camera.fitMarginFactor`) of 0.15. The resulting fit matches a cube destination for the same orientation, projection and canvas dimensions; the initial orientation is exact Inner, with no elevation, so selecting Inner immediately after loading preserves the view. The initial fit preserves its orbit angles; later model reloads preserve the user's current orientation. Explicitly selected cameras from the model or environment retain their authored view, which may differ from Inner.
 
@@ -309,7 +337,7 @@ Increasing the factor makes the fitted model smaller. The other axis can have mo
 
 The default orbital camera starts without `lowerBetaLimit` or `upperBetaLimit` and disables upside-down orbiting, whether or not the cube is enabled. ViewCube navigation keeps the camera up direction on world **+Y**, including top/bottom views and subsequent orbiting. Automatic loading preserves authored camera composition and navigation limits; an explicit unlocked cube action may relax incompatible orbit limits and adjust clipping/radius ranges to reach and fit the selected view. Locked cameras retain their view and limits.
 
-Use the mouse wheel over the 3D canvas to zoom an unlocked orbital camera. The default camera uses Babylon's native `zoomToMouseLocation` focused on the visible model surface under the pointer: the picked model point stays at the same screen pixel as you zoom, and the target moves toward it, with the ViewCube shown or hidden. Only visible, enabled, pickable model meshes supply the focus; environment geometry never does. When the pointer is not over the model, the focus falls back to Babylon's native plane through the current target. Selecting any cube preset, including the current view, cancels pending wheel motion and recenters the target on the visible model's world-bounds center using the existing fit.
+Use the mouse wheel over the 3D canvas to zoom an unlocked orbital camera. The default camera uses Babylon's native `zoomToMouseLocation` focused on the visible model surface under the pointer: the picked model point stays at the same screen pixel as you zoom, and the target moves toward it, with the ViewCube shown or hidden. Only visible, enabled, pickable model meshes supply the focus; environment geometry never does. When the pointer is not over the model, the focus falls back to Babylon's native plane through the current target. Selecting any cube preset, including the current view, cancels pending wheel or focal-pinch motion and recenters the target on the visible model's world-bounds center using the existing fit.
 
 Babylon's native input applies a radius-proportional increment once, so the same wheel input moves less at a smaller radius. Input wakes idle rendering, which continues until native wheel inertia settles. Named imported orbital cameras retain their existing input settings, and Free/Universal wheel navigation remains unchanged. The internal orbital wheel sensitivity (`wheelDeltaPercentage`) is 0.015. Wheel sensitivity has no public attribute or config option.
 
@@ -331,7 +359,8 @@ These are sampled ray checks, not continuous volume collision. Small surfaces be
 | `loadMaterials(materials)` | Queues a materials update. |
 | `loadDrawing(drawing)` | Queues a 2D drawing update. |
 | `setOptions(options)` | Queues camera, material, IBL, lighting, animation-menu, highlight, and render option updates. |
-| `setStyles(styles)` | Queues supported runtime style overrides. Currently supports `{ colorPrimary }`, persists it in `localStorage`, updates `PrefViewerStyleVariables.colorPrimary`, and applies `--pref-viewer-color-primary`. |
+| `setStyles(styles)` | Queues validated primary/ViewCube appearance patches with null resets and optional versioned persistence. |
+| `clearPersistedStyles()` | Removes only the configured saved style entry, preserving appearance. Returns success as boolean. |
 | `setIBL(ibl)` | Convenience wrapper for `setOptions({ ibl })`. |
 | `setCulture(culture)` | Changes the active UI locale and persists it in `localStorage`. |
 | `setMode(mode)` | Switches between `2d` and `3d`. |
@@ -389,8 +418,13 @@ The turnable methods store and publish semantic state for host integration. They
 
 Opening animations are discovered from paired glTF animation groups named `animation_open_<name>` and `animation_close_<name>`. State values are `0` (paused), `1` (closed), `2` (opened), `3` (opening) and `4` (closing). Enable `options.render.showAnimationMenu` to create the animation controller. Disabling that setting releases the controller: `getAnimations()` returns an empty array and imperative animation actions return `false`. A controller that is enabled can still receive imperative actions while its controls are closed.
 
+Open the animation controls with a **right mouse click** on an animated opening or, on touch screens, **hold one finger still on it for about half a second**. A short tap keeps its existing model selection/deselection behavior. Moving more than the click tolerance, adding another finger, cancelling the touch or losing window focus cancels the pending hold. After a recognized hold, lifting the finger leaves the menu open and does not emit a model-selection click. If highlight is enabled, the opening is temporarily highlighted while the hold is pending. That feedback disappears when the half-second hold completes, on early release or on cancellation. Touch-generated movement never acts as persistent mouse hover; a brief tap can show feedback while the finger is down, but cannot leave it highlighted. Real mouse hover remains available, including on hybrid devices. Touch the playback buttons normally; a normal canvas tap dismisses the menu. Pending holds are also cancelled on reload/disable and do not open controls over a modal or while the viewer is hidden/in XR.
+
+
 ### Dialogs and downloads
 
+Dialogs opened with `openDialog()`, including the **Ctrl+Alt+D** download dialog, inherit the viewer's `controls-density`. Comfortable presentation uses 16px text, an 18px title and at least 48px-high actions and option labels. Compact keeps smaller controls. Open dialogs adapt immediately when density changes without resetting selections. Dialogs stay within the viewer, scroll when its height is limited, and wrap download choices and footer buttons in narrow layouts, including iframes. Shared `--pref-viewer-controls-dialog-*` values initialize the local variables in `PrefViewerDialogStyles`.
+
 | Method | Description |
 | --- | --- |
 | `openDialog(title, content, footer)` | Opens a modal above viewer content, including the render menu and ViewCube. Its backdrop intercepts background pointer input. Returns the dialog element on success or `null` if opening fails. |
@@ -409,13 +443,15 @@ These setters are convenience bridges for framework bindings and property-based
 
 | Property | Description |
 | --- | --- |
+| `viewCubeRenderer` | Read/write `canvas` (default) or `svg`; reflects `view-cube-renderer` and changes only the active cube. Also available on standalone 3D. |
 | `config` | Forwards an object or JSON string to `loadConfig(value)`, including boolean overlay flags with the same queue ordering and omission rules. |
 | `model` | Forwards to `loadModel(value)`. |
 | `scene` | Forwards to `loadScene(value)`. |
 | `materials` | Forwards to `loadMaterials(value)`. |
 | `drawing` | Forwards to `loadDrawing(value)`. |
 | `options` | Forwards to `setOptions(value)`. |
-| `styles` | Forwards to `setStyles(value)`. |
+| `styles` | Read/write appearance patches; getter returns a detached merged snapshot. |
+| `stylesPersistence` | Read/write `{ enabled, key }`; configure before insertion when disabling persistence. |
 | `culture` | Forwards to `setCulture(value)`. |
 | `mode` | Forwards to `setMode(value)`. |
 
@@ -542,21 +578,104 @@ Directional and spot lights that come with the scene glTF (`KHR_lights_punctual`
 
 ## Runtime styles
 
-Runtime styles can be passed through the `styles` attribute, the `styles` property setter, `setStyles(styles)`, or `loadConfig({ styles })`.
+`setStyles(patch)`, the `styles` property/JSON attribute, and `config.styles` accept one schema. The root `<pref-viewer>` owns and validates these values per instance; changing one mounted viewer does not mutate another viewer's defaults. Updates use the existing sequential task queue and do not reload assets or reset the camera.
 
-```html
-<pref-viewer styles='{"colorPrimary":"#0055cc"}'></pref-viewer>
+```js
+viewer.styles = {
+  colorPrimary: "#0055cc",
+  viewCube: {
+    colors: {
+      face: "#eef0f3", edge: "#d5d5da", corner: "#c8c6c8",
+      border: "#78838f", text: "#29323b",
+      hover: "#0055cc", active: "#0055cc"
+    },
+    hoverOpacity: 0.5,
+    activeOpacity: 0.15,
+    typography: {
+      fontFamily: "Arial, sans-serif", fontSize: 10, fontWeight: 600,
+      letterSpacing: 1, textTransform: "uppercase"
+    }
+  }
+};
+
+// Partial updates preserve unrelated leaves.
+viewer.setStyles({ viewCube: { colors: { corner: "#b8b8c0" } } });
+// Same schema through configuration or JSON attributes:
+viewer.loadConfig({ styles: { colorPrimary: "#0055cc" } });
+viewer.setAttribute("styles", JSON.stringify({ viewCube: { hoverOpacity: 0.4 } }));
+
+// Reset a leaf/group. Hover/active colors follow colorPrimary again when reset.
+viewer.setStyles({ viewCube: { colors: { hover: null } } });
+viewer.setStyles({ viewCube: null });
+const snapshot = viewer.styles; // detached merged overrides plus effective colorPrimary
 ```
 
+| Field | Default / validation | Applies to |
+| --- | --- | --- |
+| `colorPrimary` | `#ff6700`; valid CSS color | UI accents, default cube highlights, animation-opening highlight and AR feedback |
+| `viewCube.colors.face` | `#eef0f3`; valid CSS color | SVG shell and Canvas faces |
+| `viewCube.colors.border` | `#78838f`; valid CSS color | SVG outlines only |
+| `viewCube.colors.edge` | `#d5d5da`; valid CSS color | Canvas edge prisms |
+| `viewCube.colors.corner` | `#c8c6c8`; valid CSS color | Canvas corner spheres |
+| `viewCube.colors.text` | `#29323b`; valid CSS color | Both renderers' labels |
+| `viewCube.colors.hover`, `active` | Follow `colorPrimary`; valid CSS colors | Both renderers |
+| `viewCube.hoverOpacity`, `activeOpacity` | `0.5`, `0.15`; numbers in 0..1 | Highlight blend strength, not material transparency |
+| `viewCube.typography.fontFamily` | Viewer default Roboto/system stack; valid CSS font family | Both renderers |
+| `viewCube.typography.fontSize` | 9 compact / 10 comfortable; positive numeric reference pixels | Both renderers; scaled to Canvas texture pixels |
+| `viewCube.typography.fontWeight` | 600; integer 1..1000 | Both renderers |
+| `viewCube.typography.letterSpacing` | 1; nonnegative numeric reference pixels | Both renderers |
+| `viewCube.typography.textTransform` | `uppercase`; `none`, `uppercase`, `lowercase` | Both renderers |
+
+Unknown fields and invalid leaves are ignored independently. Colors/families cannot reference external CSS (`var()`, `env()`, `currentColor`, inheritance/reset keywords). A null leaf or group removes its customizations, including stored ones, restoring current internal defaults. An omitted leaf preserves its value. Getter snapshots omit uncustomized leaves except `colorPrimary`; modifying a snapshot does not change the viewer. A malformed JSON string throws. `setStyles()` returns void for queued objects (not a Promise), or false for a non-object payload.
+
+Changing the primary color synchronizes animation-opening highlights, including an active highlight, without changing whether highlighting is enabled. The render-menu color control stays synchronized. An explicit `options.render.highlightColor` remains supported; a later primary style update replaces it. Canvas applies its material lighting, highlights and SSAO after resolving the palette; displayed tones can differ from the flat SVG. Renderer selection remains on the existing separate `viewCubeRenderer` API. Canvas lighting, material/specular settings, SSAO and other rendering internals are not exposed through styles.
+
+### Style persistence
+
+Persistence defaults to `{ enabled: true, key: "pref-viewer/styles" }`, preserving the existing default storage location. Configure it per instance before insertion to avoid reading storage when disabled:
+
 ```js
-viewer.setStyles({
-  colorPrimary: "#0055cc",
-});
+const viewer = document.createElement("pref-viewer");
+viewer.stylesPersistence = { enabled: true, key: "my-app/product-preview/styles" };
+viewer.styles = { colorPrimary: "#0055cc" };
+document.querySelector("#preview").append(viewer);
+
+// When the application owns persistence:
+viewer.stylesPersistence = { enabled: false };
 ```
 
-The ViewCube uses this same primary color for its hover feedback and, mixed into the face fill, for its current-orientation feedback. Changing `colorPrimary` through `styles` or `config` attributes, `setStyles`, or `loadConfig({ styles })` also updates animation-opening highlight color, including an opening currently highlighted, without reloading the model or changing whether highlighting is enabled. The render menu color control stays synchronized. Persisted primary styles are applied to highlights when the viewer connects. `options.render.highlightColor` can still set an explicit highlight color; a later primary-style update replaces it.
+Only supported overrides are saved, not a snapshot of defaults:
 
-Only `colorPrimary` is currently supported. The value updates `PrefViewerStyleVariables.colorPrimary`, is exposed on the host as `--pref-viewer-color-primary`, and is persisted in `localStorage` under `pref-viewer/styles`. Persisted styles are restored when a new `<pref-viewer>` instance is created and connected.
+```json
+{"version":1,"styles":{"colorPrimary":"#0055cc","viewCube":{"colors":{"corner":"#b8b8c0"}}}}
+```
+
+Defaults are overlaid by saved preferences, then explicit application patches. Explicit values and null resets retain priority when switching storage keys or reconnecting. Switching keys/enabling storage restores that key without automatically writing it; disabling removes the saved layer from the current appearance and preserves explicit patches. Accepted style patches write the merged overrides when persistence is enabled. Resetting a group/leaf removes it from the next saved envelope.
+
+Keys are exact `localStorage` keys scoped to the page origin. The default key is shared: instances using it read the same saved preferences on restoration; choose distinct keys for isolation. Mounted viewers do not automatically synchronize across instances/tabs. Legacy `{ "colorPrimary": "..." }` records are restored and converted to version 1 on the next accepted patch. Invalid records, unsupported versions and blocked/full storage do not prevent rendering.
+
+```js
+viewer.clearPersistedStyles(); // true on successful removal, false if disabled/unavailable
+```
+
+Clearing removes only the configured key and preserves the current appearance; a future patch can save it again. It does not erase locale, render settings or other storage. Use null style resets to restore appearance as well. Getter `stylesPersistence` returns a detached copy.
+
+### Migration from external CSS
+
+**Breaking change:** inherited CSS variables are no longer a supported styling API for controls inside root `<pref-viewer>`. The shadow wrapper initializes internal tokens and typography; CSS on the host or its ancestors cannot override controls through old `--pref-viewer-*` tokens or internal aliases. Use the style object instead:
+
+```js
+// Replaces host CSS: --pref-viewer-view-cube-corner-color: #b8b8c0
+viewer.setStyles({ viewCube: { colors: { corner: "#b8b8c0" } } });
+```
+
+Legacy `fill-color` maps to `viewCube.colors.face`, `border/text/edge/corner/hover/active-color` map to the corresponding `viewCube.colors` keys, and `text-font-*`, `text-letter-spacing`, `text-transform` map to `viewCube.typography`. Size and spacing inputs use numeric pixels in the API. This API belongs to root `<pref-viewer>`; standalone low-level components do not gain an independent style/persistence facade.
+
+Applications still control the host's width, height, position and visibility. Encapsulation is not a security boundary: JavaScript can access the open shadow root, and arbitrary HTML supplied to dialogs is application-owned.
+
+### Confluence publication checklist
+
+On the next requested PrefViewer Confluence documentation update, include this unified schema, defaults, partial/null reset semantics, validation, queue behavior, keyed persistence/migration/clearing, CSS encapsulation and migration examples. Also cover SVG/Canvas selection via its existing API, shared/custom colors and typography, compact/comfortable presentation, gestures/cursor, and the distinction between palette values and Canvas lighting/material/SSAO internals. This repository change does not publish to Confluence.
 
 ## Localization
 
@@ -601,7 +720,7 @@ The playground is available from `playground/index.html` at `http://localhost:80
 
 JavaScript classes, methods and named helper functions outside tests are documented with JSDoc, including parameters and return values where applicable. This also covers existing helpers and webpack configuration callbacks. Keep those comments and this README aligned with the current implementation. Edited code files use Windows CRLF line endings.
 
-Shared calculations live in the static `RenderMath` and `MaterialUtils` classes. `I18n` owns the shared locale and translation subscribers, with private lookup helpers and public static methods. These modules export their classes only; viewer components and tests call their static methods directly. Former named function/constant exports and utility reexports from `BabylonJSController` have been removed. These helpers are internal modules, not additional package-root API exports. `BabylonJSController` encapsulates resize application, metadata path parsing and debug serialization as private methods, passing scene mesh snapshots explicitly to material diagnostics.
+Shared calculations live in the static `BabylonJSRenderMath` and `MaterialUtils` classes. `I18n` owns the shared locale and translation subscribers, with private lookup helpers and public static methods. These modules export their classes only; viewer components and tests call their static methods directly. Former named function/constant exports and utility reexports from `BabylonJSController` have been removed. These helpers are internal modules, not additional package-root API exports. `BabylonJSController` encapsulates resize application, metadata path parsing and debug serialization as private methods, passing scene mesh snapshots explicitly to material diagnostics.
 
 `BabylonJSAnimationOverlayController` owns one opening-highlight group: its utility scene, cached overlay bases, transformed presentation meshes and observers. It creates clones directly in the utility scene, hides geometry bases used only by instances, and releases only its own resources through an idempotent `dispose()`. These animation overlays remain separate from semantic 3D selection overlays. The temporary legacy storage module and opening-control callbacks retain their existing structure.
 
@@ -609,20 +728,25 @@ Focused regressions for this work live in `tests/babylonjs-selection-controller.
 
 ### Camera implementation and maintenance
 
-- `src/babylonjs-view-cube-controller.js`: dedicated `BabylonJSViewCubeController` for pointer interaction (hover, click, drag), camera reading and writing, click transitions, size, colours and cleanup. It delegates model bounds and destination-fit calculations to BabylonJSCameraFraming and the drawing to the renderer. Cube-only helpers and constants remain private; region generation remains a public static utility. Its constructor JSDoc documents the host object and callbacks.
-- `src/babylonjs-view-cube-renderer.js`: `BabylonJSViewCubeRenderer`, the cube's own Babylon.js engine and virtual scene with its 26 region meshes, picking and painting. It owns no render loop and no interaction logic; the controller renders it from the host loop.
-- `src/view-cube-orbit-math.js`: pure helpers for orbit angles, the 26 view directions, drag deltas and the cube size rule, without Babylon or DOM dependencies.
+- `src/babylonjs-view-cube-controller.js`: `BabylonJSViewCubeController` facade selecting one implementation and owning replacement/disposal. `babylonjs-view-cube-svg-controller.js` preserves the SVG widget; `babylonjs-view-cube-canvas-controller.js` preserves the independent Babylon Canvas widget. Each implementation handles its input, navigation, synchronization and resource lifecycle using the same callback-based host contract and shared camera-framing utilities.
+- `src/babylonjs-view-cube-canvas-renderer.js`: `BabylonJSViewCubeCanvasRenderer`, the cube's own Babylon.js engine and virtual scene with its 26 region meshes, picking and painting. It owns no render loop and no interaction logic; the controller renders it from the host loop.
+- `src/babylonjs-view-cube-canvas-orbit-math.js`: `BabylonJSViewCubeCanvasOrbitMath` encapsulates static pure calculations for orbit angles, the 26 view directions, drag deltas and legacy adaptive sizing calculations (the current overlay size comes from shared CSS). Numerical constants and region construction are private; the polar margin and immutable directions have read-only getters. It has no Babylon or DOM dependencies.
 - `src/babylonjs-camera-framing.js`: stateless `BabylonJSCameraFraming` with static `getModelBounds`, `calculateCameraFit` and `isCameraSupported` utilities. Bounds use only visible, enabled geometry in the supplied model container; fit calculations preserve camera state and projection, use the shared camera margin and return a destination for the caller to apply. Default-camera automatic fitting uses these same utilities, preserving the current orientation and applying the destination immediately.
 - `src/babylonjs-camera-zoom-controller.js`: independent `BabylonJSCameraZoomController` for model-only dynamic radius protection and authored-floor restoration. It works without cube resources.
 - `src/babylonjs-camera-wheel-motion.js`: internal boundary for inspecting and cancelling the coupled native wheel inertia during rendering, geometry protection and camera lifecycle changes, and for focusing the native mouse-location zoom on the model surface under the pointer. Babylon computes the zoom; this boundary isolates version-sensitive native input state.
 - `src/babylonjs-controller.js`: owns the scene, active camera, containers, native wheel settings and render scheduler; coordinates both controllers.
 - `src/pref-viewer-3d.js` and `src/pref-viewer.js`: bridge lazy visibility, queued config, localization and measured menu layout. The root stores the layout callback in `#handlers` and removes its listener during teardown. Shared styles place dialogs above viewer overlays.
 
-ViewCube class members are ordered as properties, constructor, static methods, private methods and public methods/getters. New classes and new/modified methods carry JSDoc describing their parameters, return values and current lifecycle/side effects. JavaScript `if` and `for` bodies always use braces, including single-statement bodies. Focused tests live in `tests/babylonjs-camera-framing.test.js`, `tests/babylonjs-view-cube-controller.test.js`, `tests/babylonjs-view-cube-renderer.test.js`, `tests/view-cube-orbit-math.test.js`, `tests/babylonjs-camera-zoom-controller.test.js`, `tests/babylonjs-controller-wheel.test.js` and `tests/pref-viewer.test.js`. Browser checks in the existing playground remain necessary for cube rendering, hover regions, dragging, focus and cursor behavior, and modal stacking, because the tests run on a null engine.
+ViewCube class members are ordered as properties, constructor, static methods, private methods and public methods/getters. New classes and new/modified methods carry JSDoc describing their parameters, return values and current lifecycle/side effects. JavaScript `if` and `for` bodies always use braces, including single-statement bodies. Focused tests live in `tests/babylonjs-camera-framing.test.js`, `tests/babylonjs-view-cube-controller.test.js`, `tests/babylonjs-view-cube-canvas-renderer.test.js`, `tests/babylonjs-view-cube-canvas-orbit-math.test.js`, `tests/babylonjs-camera-zoom-controller.test.js`, `tests/babylonjs-controller-wheel.test.js` and `tests/pref-viewer.test.js`. Browser checks in the existing playground remain necessary for cube rendering, hover regions, dragging, focus and cursor behavior, and modal stacking, because the tests run on a null engine.
 
 ### ViewCube rendering maintenance
 
-The cube's visual constants (the light palette, face label font and size, edge and corner sizes, lighting) are internal to `src/babylonjs-view-cube-renderer.js`. They are not properties supported by `setStyles` or `config.styles`; only `colorPrimary` reaches the cube, through the hover and current colours. The renderer module also contains a dark palette constant; it is not exported from the package and is not part of the public API.
+Canvas currently enables an experimental SSAO2 contact-shading pass when its own engine supports SSAO2, draw buffers and renderable float/half-float textures. Settings are localized in `BabylonJSViewCubeCanvasRenderer`: `#SSAO_ENABLED` and `#SSAO_SETTINGS` (8 samples, half-resolution geometry/first blur stage, radius 0.12 cube units, strength 0.6). Only the 26 solid surfaces enter the geometry buffer; transparent labels are excluded. Composition preserves the transparent background and FXAA runs last. Unsupported engines retain the normal render, including NullEngine tests. The pipeline and geometry buffer are disposed with the cube and use its existing demand-render loop. This is a visual trial; real-device performance has not been benchmarked.
+
+
+Both ViewCubes use the palette defined once by `PrefViewerViewCubePalette` in `src/styles.js`: face fill `#eef0f3`, border `#78838f` and text `#29323b`, primary-color hover at 50% and current-view tint at 15%. SVG applies CSS directly; Canvas reads the same computed variables and composites highlight tints over a neutral gray derived from each base color using RGB luminance weights (0.2126 R + 0.7152 G + 0.0722 B). This removes the base hue from hover/current highlights; unhighlighted surfaces retain their original colors and hover takes precedence over current. Canvas currently uses lit surface materials without emission, light intensity 1.0 and neutral hemispheric lower fill (0.75, 0.75, 0.75) for moderate contrast between faces. A white lower directional support light, tilted along (-0.4, 1, 0.4) at intensity 0.16, illuminates Bottom (-Y), Left (+X) and Outer (-Z) with white specular highlights while preserving the hemispheric fill; both lights belong to the isolated cube scene. Light specular strength is 0.75 per channel to soften highlights, especially in Top; lighting and specular highlights still affect the displayed tones. Faces, edge prisms and corner spheres all use solid diffuseColor with no emission, giving their base colors the same lighting path. Each face has a separate, non-pickable label plane with a transparent 512 px glyph texture and an unlit alpha-blended material for readability. Labels inherit face orientation, sit 0.0005 units outward with a depth bias to avoid flickering, and retain depth testing/back-face culling so rear labels stay hidden. The six extra meshes and materials belong to the private cube scene and are disposed with it. Hover and current-view tints affect the solid surfaces, while CSS controls label color and typography. Edge prisms use `#d5d5da` and corner spheres use `#c8c6c8`, independent of SVG borders. Both base colors are darkened proportionally by 5% per RGB channel from the original edge/corner palette, with rounding to whole channel values, then given a 5-point blue-channel boost. The cube engine requests native antialiasing and its own camera also uses FXAA; both stay isolated from the model scene. All 26 surface materials use specular color (0.5, 0.5, 0.5); faces and edges use specularPower 64, while corner spheres use 32 for broader highlights; the six label materials have no specular highlights. Geometry sizes remain renderer-specific. Both renderers share label typography from CSS: the viewer font family, weight 600, uppercase and 1 px letter spacing, with a reference font size of 9 px in compact and 10 px in comfortable. Canvas scales font size and letter spacing from the 62-unit frontal SVG face to its 512 px texture; these are texture pixels, independent of device pixel ratio. Face textures use mipmaps, trilinear sampling and anisotropic filtering (level 8, limited by the GPU) for sharper labels at oblique angles. Typography changes repaint existing textures, including while the main scene is idle. Public `styles.viewCube.typography` overrides are projected onto internal tokens shared by both renderers.
+
+Public customization uses the unified [Runtime styles](#runtime-styles) schema. The CSS tokens in `PrefViewerViewCubePalette` and `PrefViewerViewCubeTypography` are internal implementation details projected inside the shadow boundary. Palette defaults are centralized; Canvas resolves the computed internal values and falls back for invalid colors. The optional internal dark palette is not automatically selected or a package-root export.
 
 Keep these rules when changing the renderer: the cube scene stays virtual and its engine stays out of `EngineStore.Instances` while it is alive (otherwise the viewer can create resources on the cube's WebGL context); Babylon input stays detached from the cube canvas (otherwise the cursor and keyboard focus are disturbed); and the engine keeps `loseContextOnDispose` so its WebGL context is released.
 
@@ -637,9 +761,62 @@ ViewCube listener registration, drag handling and hover updates are private inst
 | `npm run build:prefweb:dev` | Creates a development webpack UMD build with external source maps for PrefWeb/browser debugging. Source map module names point back to project source paths. |
 | `npm start` | Builds the standard bundle and starts a local HTTP server on port `8080`. |
 | `npm test` | Runs the Vitest test suite. |
+| `npm run test:e2e:install` | Installs the WebKit browser matching the pinned Playwright version. |
+| `npm run test:e2e` | Builds the ESM bundle and runs WebKit compatibility tests with iPhone/iPad profiles. |
+| `npm run test:e2e:report` | Opens the last HTML compatibility-test report. |
 | `npm run release` | Creates a standard-version release. |
 | `npm run release:beta` | Creates a beta prerelease with standard-version. |
 
+## WebKit compatibility tests
+
+On Windows 11, run `npm ci`, `npm run test:e2e:install`, then `npm run test:e2e`.
+The browser installation is stored under ignored `node_modules` by default; `PLAYWRIGHT_BROWSERS_PATH`
+can override it. The configuration in `playwright.config.js` uses WebKit with the iPhone 13 and
+iPad Pro 11 device profiles. Filter runs with, for example, `npm run test:e2e -- --project=webkit-iphone`.
+
+Tests detect this repository's running server on ports 8080–8090, 3000 or 5173 (and `PORT` if set),
+or start and stop an in-process local server on a free port. To use a different running local port,
+set `PLAYWRIGHT_BASE_URL`, for example `$env:PLAYWRIGHT_BASE_URL='http://localhost:8095'` in PowerShell.
+The server must serve this repository root, including `/dist/` and `/tests/e2e/fixtures/`.
+The deterministic viewer and iframe fixtures use that same local origin; they do not edit the playground.
+
+The suite checks actual model pixels, touch-pointer camera handling, trusted touch taps, AR anchor
+layout, USDZ ZIP contents/MIME/download, model replacement, visibility, localization, export retry,
+modal protection, iframe delivery and orientation/hidden resize. Unexpected JavaScript errors,
+console errors, failed requests and HTTP errors fail tests. Google Fonts CSS is explicitly fulfilled
+with an empty stylesheet to exercise the system-font fallback without external certificate/network
+dependencies. The fixture supplies the real `fflate` development dependency locally; it does not
+validate production access to the exporter's CDN. A further fixture generates real Draco-compressed
+glTF in memory and loads it over HTTP; the real Draco 1.5.7 decoder/WASM is supplied from the
+`draco3dgltf` development dependency through an explicit CDN route. This tests decoding, HTTP/cache
+loading and USDZ export independently of external certificate/network availability. Export-failure
+injection is confined to its negative test.
+
+Failures retain screenshots, videos and traces under `test-results/`. The HTML report is in
+`playwright-report/` and includes browser errors and `getDebugInfo()` diagnostics. Open a trace with
+`node tests/e2e/run.mjs show-trace <path-to-trace.zip>`. These output directories are ignored by Git.
+
+Playwright is temporarily pinned to `1.65.0-alpha-2026-10-15` (WebKit build 2376) because stable
+`1.64.1`/WebKit 2370 produces blank WebGL captures after buffer resize on Windows:
+[upstream issue #42885](https://github.com/microsoft/playwright/issues/42885).
+The newer browser is a test-only dependency. Recheck the visual suite before replacing this pin with
+a stable release containing the fix; do not bypass the assertion or change production rendering to
+work around a Windows test-browser capture bug.
+
+These are **WebKit compatibility emulations on Windows, not Safari on real iOS/iPadOS**.
+The `rel="ar"` action downloads USDZ here; it cannot launch or validate Apple's native AR Quick Look,
+camera permissions, placement/scale/material fidelity, real mobile GPU behavior, or production
+cross-origin iframe policies. Those checks still require actual iPhone/iPad devices. The minimal
+fixtures also do not cover textured production-asset fidelity or Android WebXR sessions.
+
+The viewer now loads optional font CSS without blocking its local shadow styles. Hidden canvases
+skip engine resize, and resize notifications defer buffer/layout changes to a later animation frame.
+Deferring resize work reduces repeated intrinsic-buffer scaling and observer feedback loops;
+unexpected observer errors remain browser-test failures. The existing render-effect settings and
+demand-rendering policy are preserved.
+Cache writes also observe the IndexedDB request and transaction promises together, so a failed write
+does not leak an unhandled transaction-abort rejection while the existing loading fallback proceeds.
+
 ## TypeScript and JSX
 
 The package ships `index.d.ts`, including JSX support for `<pref-viewer>`.
@@ -678,3 +855,62 @@ export function ProductViewer() {
 Proprietary. Copyright (c) 2026 Preference S.L. All rights reserved.
 
 This package is published for authorized Preference S.L. customers and partners. Use, distribution, and access are governed by the applicable commercial agreement with Preference S.L. See [LICENSE.md](./LICENSE.md).
+
+## Responsive controls
+
+`controls-density="auto"` selects comfortable controls for a primary coarse pointer and compact controls otherwise. Set `compact` or `comfortable` explicitly to override this, including on hybrid devices. Each viewer owns its capability/resize subscriptions; multiple instances and same-origin iframe layouts are independent. Display pixel ratio affects rendering sharpness, not control target sizes. Changing density does not reload the scene or change model scale.
+
+```html
+<pref-viewer controls-density="auto" mode="3d"></pref-viewer>
+<!-- Standalone 3D also accepts the attribute. -->
+<pref-viewer-3d controls-density="comfortable"></pref-viewer-3d>
+```
+
+Comfortable presentation uses 40px playback buttons, 48px settings actions, a 140px ViewCube in either renderer and a 48×48px AR action with the same padding/background as the settings trigger and no added AR text. Settings use 16/14px text. In both densities, the animation menu fits the available viewer width and buttons wrap onto multiple rows when necessary. Compact retains 32px playback buttons. Space below is reserved only when a visible AR button overlaps horizontally; otherwise the menu uses the normal bottom margin. The playback container adds no background, corner rounding or padding; its slider retains the original fill, border, thumb and spacing in both densities. Settings stay open after touch and can be closed with the gear, close action or Escape. Narrow comfortable viewers open settings in a bounded scrolling bottom panel. A compact override on a touch device still exposes settings without requiring hover. The cube’s face/edge/corner regions are not individually guaranteed to be 48px targets. Very small viewers constrain how many controls can be visible concurrently.
+
+In both densities, AR is circular and shares the settings trigger's width, height, background, hover color, border and padding, without growing on hover. The AR glyph shows an isometric cube surrounded by scanning corners; its square SVG matches the settings glyph's width (24px compact, 28px comfortable). Compact AR measures 46×46px. Native WebXR and Quick Look actions use the same 16px edge spacing. Shared values are grouped in `ViewerControlsPresentationStyles` with the `--pref-viewer-controls-` prefix, including `toggle-bg-color`, `toggle-bg-hover-color`, `toggle-border-color`, `toggle-border-width`, `toggle-height`, `toggle-radius`, `toggle-spacing`, `toggle-icon-size`, `toggle-transition-duration`, `panel-bg-color`, and `edge-spacing`. `PrefViewerMenu3DStyles` keeps its local variables (such as `--toggle-bg-color` and `--panel-bg-color`), initialized from those shared values with standalone defaults. AR width and label size use `--pref-viewer-controls-ar-width` and `--pref-viewer-controls-ar-font-size`.
+
+For the SVG variant, with an unlocked `ArcRotateCamera`, hold the left mouse button or press with one finger on a ViewCube face, edge or corner and drag to orbit the scene, without a long-press delay. This works independently of canvas camera input attachment and keeps the target, radius, projection and angular limits. Touch presses use the same fill and outline as mouse hover before dragging, with native blue tap highlighting disabled; feedback clears as soon as the drag threshold is crossed, or on release/cancellation. Short clicks and taps still select predefined views; dragging does not refit the model or select a view on release. During dragging a cube-with-orbit-arrows cursor identifies ViewCube rotation (CSS variable `--cube-rotation-cursor`, with `grabbing` fallback). Capture continues outside the cube and ends on cancellation, focus loss, Escape, camera/projection changes, hiding or disposal. Full camera lock and AR prevent navigation. Free/Universal cameras retain view-selection clicks; orbital dragging supports mouse and single-finger touch. A second touch on the cube cancels rotation, and SVG touch-action prevents browser scrolling/zoom from taking over that gesture.
+
+SVG and Canvas ViewCube dimensions come from `--cube-size` in `PrefViewerViewCubeStyles`, initialized from `--pref-viewer-controls-cube-size` with a 120px fallback. Density defaults are 120px compact and 140px comfortable. CSS owns width/height; the controller only caps the square to the available viewport. The settings trigger and panel move to the upper right, immediately left of the ViewCube when the normal trigger position below the cube would exceed the viewer height or overlap a visible AR action (including the shared control gap). They return to the right when space becomes available. This is evaluated from the normal right-side position to avoid alternating sides after a move, and responds to viewer/control resizing, cube visibility and AR insertion/removal/visibility in both densities.
+
+Render settings suppress the browser's native tap flash throughout the gear and panel. Touch presses use the same feedback as mouse hover: the gear and panel buttons change background, while enabled switches and sliders receive a light outline. Feedback clears on release/cancellation, a second touch, window blur or menu removal; keyboard focus remains visible. Coarse-pointer devices do not retain simulated mouse-hover styling after tapping.
+
+Viewer dialogs use the same temporary touch feedback for buttons, radios, checkboxes and other form controls, including controls supplied through `openDialog`. Pressing a radio/checkbox label highlights its associated input; native selection and keyboard focus remain available. Radios and checkboxes use the viewer's primary accent color. Dialog content replacement and removal also clear owned press state.
+
+Animation playback, loop and animation-selection buttons also suppress native tap flash and share hover/press feedback. Pressed active controls retain their active theme; disabled playback controls are inactive. Progress dragging keeps the original track styling and highlights the thumb while pressed, with visible keyboard focus. Release/cancellation, another touch, window blur, disabling a pressed control and menu disposal clear transient feedback.
+
+The embedding page still needs `<meta name="viewport" content="width=device-width, initial-scale=1">` for mobile layout; the viewer never inserts or changes page viewport metadata. Keep browser zoom available. Automated WebKit compatibility tests do not establish native iOS AR behavior or physical touch comfort; real Android/iOS validation remains useful.
+
+For failed repositioning, inspect `getDebugInfo().ar.diagnostics.drag` after attempting a one-finger drag. `selectStarts` counts received native selections; `selectEnds` counts releases/removals. `lastInputMode`, `status`, `pickedMesh` and `lastError` distinguish missing input/poses, floor-intersection rejection, pending/cancelled/placed taps and active dragging. `hitTestStatus: "retained-floor"` means gestures use the previously observed plane without another native subscription; the drag `lastHitCount` remains zero. `frames` and `moves` count processed input frames and applied horizontal position changes across the session. Status describes the last gesture outcome and survives release/exit until another gesture or session starts; `ar.dragging` separately reports current activity. These bounded counters do not establish a device root cause or successful physical dragging.
+
+
+### Touch gesture reference
+
+| Touch location and gesture | Behavior |
+| --- | --- |
+| Main 3D scene: separate or bring two fingers together | Proportional zoom around their midpoint when the camera uses focal wheel zoom; focus is the visible model surface or the same target-plane fallback as the wheel. |
+| Main 3D scene: move two fingers in parallel | Pan after intent recognition, without zoom; stops any preceding focal-zoom glide. |
+| SVG or Canvas ViewCube: press a selectable region | Show hover feedback immediately, without a long-press delay. A short release over the same region selects that view. |
+| SVG or Canvas ViewCube: press and move more than 3 CSS pixels | Orbit the camera, clear hover and keep only active-orientation feedback. Releasing after a drag does not select a view. |
+| ViewCube: release or cancel touch | Clear touch hover; later camera updates do not restore it. Mouse hover remains available on hybrid devices. |
+
+These scene-navigation gestures do not change Android AR model placement/rotation gestures or add model pinch scaling in AR. Windows WebKit checks verify emulated interactions and rendering; physical-device comfort remains a separate check.
+
+### Selectable ViewCube renderers
+
+`<pref-viewer>` and standalone `<pref-viewer-3d>` support two orientation widgets. Canvas is the default. Explicitly selecting SVG keeps the vector cube, touch/mouse drag, rotation cursor and CSS sizing (120 px compact, 140 px comfortable). Canvas uses a real 3D cube in a dedicated Babylon Engine/Scene, including the projection, picking, DPR and context-restoration behavior from PWB-7397. It shares the SVG CSS dimensions: 120 px compact and 140 px comfortable, capped to the available viewport. Both use the same SVG rotation cursor, including its shadow and hotspot, during mouse drag. On touch, pressing a selectable region shows its hover feedback until the drag threshold is crossed; rotation then shows only the active orientation. Release or cancellation clears touch hover, while ordinary mouse hover remains available on hybrid devices. Exactly one implementation is active per viewer; switching releases the previous widget's graphics and input resources. The Canvas engine/scene stay outside Babylon's global registries. Top and Bottom synchronization preserves the polar view rather than applying the drag safety margin; the private camera uses only a 1e-7 rad numerical offset, so those faces remain centered and square. Its camera frames a bounding sphere that includes all faces, edge bars and corner spheres, with 2% padding. Orthographic extents and perspective distance fit this envelope without changing during rotation; the host field of view is retained and the whole cube stays inside the viewport.
+
+```html
+<!-- Canvas is selected when the attribute is omitted. -->
+<pref-viewer></pref-viewer>
+<pref-viewer view-cube-renderer="svg"></pref-viewer>
+<pref-viewer view-cube-renderer="canvas"></pref-viewer>
+```
+
+```js
+viewer.viewCubeRenderer = "canvas";
+viewer.loadConfig({ viewCubeRenderer: "svg", model: { storage: { url: "/model.glb" } } });
+```
+
+The reflected `viewCubeRenderer` property accepts `svg`/`canvas`; invalid values and removing the attribute resolve to Canvas. `loadConfig` applies an explicitly supplied preference in queue order before asset loading; omission preserves the current preference. Direct changes do not reload assets or reframe/change the main camera. `show-view-cube` still controls visibility independently. Changes while disconnected, in 2D or disabled retain the preference without creating a cube. Separate viewers can use different variants. Both variants retain camera locking/XR restrictions and cube drag independent of scene rotation input. The render menu uses the actual widget dimensions to avoid overlaps. Only the Canvas variant allocates a second WebGL context, which is released on replacement/disable/disposal. Applications that require the vector widget without that additional graphics context must explicitly select `svg`; there is no automatic device-based renderer selection.