@ericchen1990/pano-view 3.9.0 → 4.0.0

package/README.md

@@ -230,17 +230,18 @@ Store this content structure in `project.json`; store media as separate files. P
 
 ```tsx
 import { useState } from "react";
-import { PanoViewer, ProjectScenes, type LoadedPanoProject, type ProjectPopupDefinition } from "@ericchen1990/pano-view";
+import { PanoOverlay, PanoViewer, ProjectScenes, type LoadedPanoProject, type ProjectPopupDefinition } from "@ericchen1990/pano-view";
 import { ProjectPopupDialog } from "@ericchen1990/pano-view/ui";
 import "@ericchen1990/pano-view/ui/styles.css";
 
 export function Tour({ project }: { project: LoadedPanoProject }) {
   const [popup, setPopup] = useState<ProjectPopupDefinition | null>(null);
-  return <PanoViewer renderOverlay={() => (
-    <ProjectPopupDialog popup={popup} onOpenChange={(open) => { if (!open) setPopup(null); }} />
-  )}>
+  return <PanoViewer>
     <ProjectScenes project={project} onPopupRequest={({ popup }) => setPopup(popup)}
       onActiveSceneIdChange={() => setPopup(null)} />
+    <PanoOverlay>
+      <ProjectPopupDialog popup={popup} onOpenChange={(open) => { if (!open) setPopup(null); }} />
+    </PanoOverlay>
   </PanoViewer>;
 }
 ```
@@ -258,12 +259,14 @@ An optional project-level `map` places scene spots on one floor image. Projects
   "maxScale": 4,
   "iconSize": 28,
   "presentation": {
-    "mode": "docked",
-    "corner": "bottom-left",
+    "mode": "panel",
+    "anchor": {
+      "align": "bottom-left",
+      "axis": "horizontal",
+      "inset": 16
+    },
     "width": 240,
-    "height": 180,
-    "offsetX": 16,
-    "offsetY": 16
+    "height": 180
   },
   "controls": { "collapse": true, "zoom": true },
   "sector": {
@@ -289,70 +292,70 @@ An optional project-level `map` places scene spots on one floor image. Projects
 
 `image` is a project-relative path or an absolute URL. `spots` is required. Spot IDs are unique, and each `sceneId` must name a scene in the project. `x` and `y` are normalized image coordinates in [0, 1], with the origin at the top-left. `heading` is clockwise degrees from image-up when viewer yaw is 0; the drawn sector uses `heading + yaw`. Several spots may share a scene. The sector is drawn on the first spot whose `sceneId` matches the active scene. `icon` is optional; a spot without one uses the built-in marker.
 
-`interaction` is `"fixed"` (the default) or `"zoom"`. Fixed mode fits the image in the panel and ignores the wheel, drag-pan, and zoom buttons. Zoom mode allows wheel zoom, and drag-pan once the scale is above the fitted size. Wheel events on the map do not scroll the page. `maxScale` is the maximum multiple of that fitted size, at least 1, default 8. `dragMotion` controls pan inertia and edge bounce while zoomed (both on by default). Set `false` to disable both, or `{ inertia?: boolean; bounce?: boolean }` to toggle either flag. Spot and heading edits stay direct. `controls.zoom` shows the zoom buttons only when interaction is `"zoom"`. `controls.collapse` shows expand and collapse on a docked panel. `iconSize` is the marker edge in CSS pixels, default 28. Icons and the sector keep that screen size while the floor image zooms.
+`interaction` is `"fixed"` (the default) or `"zoom"`. Fixed mode fits the image in the panel and ignores the wheel, drag-pan, and zoom buttons. Zoom mode allows wheel zoom, and drag-pan once the scale is above the fitted size. Wheel events on the map do not scroll the page. `maxScale` is the maximum multiple of that fitted size, at least 1, default 8. `dragMotion` controls pan inertia and edge bounce while zoomed (both on by default). Set `false` to disable both, or `{ inertia?: boolean; bounce?: boolean }` to toggle either flag. Spot and heading edits stay direct. `controls.zoom` shows the zoom buttons only when interaction is `"zoom"`. `controls.collapse` shows an edge tab that slides a panel off-screen. `iconSize` is the marker edge in CSS pixels, default 28. Icons and the sector keep that screen size while the floor image zooms.
 
 `sector` is optional. `angle` is the opening in degrees, greater than 0 and less than 360. `radius` is CSS pixels and does not scale with the image. `followFov` replaces `angle` with the horizontal field of view derived from the viewer FOV and the map panel's aspect ratio. Without `gradient`, the fill is solid `color` (default `#ffffff`) at `opacity` (default 0.55). `gradient.type` is `"radial"` or `"linear"`, with at least two stops. Each stop has `offset` in [0, 1], `color`, and an optional `opacity`. Stop opacities describe only the fade shape. `sector.opacity` scales the whole fill in both solid and gradient mode. `strokeColor`, `strokeWidth`, and `strokeOpacity` draw an outline when the width is greater than 0. The outline width stays in CSS pixels.
 
-`presentation.mode` is `"docked"` (the default) or `"dialog"`. Both accept `corner` (`top-left`, `top-right`, `bottom-left`, or `bottom-right`; default `bottom-left`), `offsetX` and `offsetY` (default 16), plus `width` and `height`. A docked panel defaults to 220×160. Dialog mode docks a launcher (48×48 when width and height are omitted) and opens the same map in a viewer-local dialog. Choosing a spot closes that dialog. The chrome is positioned on the full viewer overlay, so scrolling a parent page does not move or resize it.
+`presentation.mode` is `"panel"` (the default) or `"dialog"`. Both accept `anchor`, plus `width` and `height`. `anchor` is the shared overlay anchor: `align` is `top`, `bottom`, `left`, `right`, or one of the four corners (default `bottom-left`); `axis` is `"horizontal"` or `"vertical"` and applies only to corners (default `"horizontal"`); `inset` is a number, a CSS length string, or `{ top, right, bottom, left }` (default `16`). Safe-area insets are added on top. A panel defaults to 220×160. Dialog mode places a launcher (48×48 when width and height are omitted) and opens the same map in a viewer-local dialog. Choosing a spot closes that dialog. The chrome is positioned on the full viewer overlay, so scrolling a parent page does not move or resize it. Edges center a sized box on that edge. Corners pin to both adjacent edges. Collapsing keeps the panel size and slides it off the outer edge: edges slide toward that edge, and corners slide vertically when `axis` is horizontal or horizontally when `axis` is vertical. The tab stays on the inner side of that edge.
 
-The document stores saved defaults (`image`, `spots`, `sector`, `presentation`, `interaction`, `maxScale`, `dragMotion`, `controls`, `iconSize`). Mount-time props on `PanoMapOverlay` override presentation and zoom for that render without cloning the map. Priority is built-in defaults → map document → `presentationOverride` (same shape as `map.presentation`) → individual props. Spot geometry and sector styling stay in the document. `selectedSpotId` / `onSelectedSpotIdChange` are forwarded to the inner `PanoMap`. Docked collapse state is owned by the overlay; dialog mode and `editorSurface` force collapse controls off, so `collapsed` cannot be driven from outside.
+The document stores saved defaults (`image`, `spots`, `sector`, `presentation`, `interaction`, `maxScale`, `dragMotion`, `controls`, `iconSize`). Mount-time props on `PanoMapOverlay` override presentation and zoom for that render without cloning the map. Priority is built-in defaults → map document → `presentationOverride` (same shape as `map.presentation`) → individual props. Spot geometry and sector styling stay in the document. `selectedSpotId` / `onSelectedSpotIdChange` are forwarded to the inner `PanoMap`. Panel collapse state is owned by the overlay; dialog mode and `editorSurface` force the edge tab off. `PanoMap`'s own `collapsed` prop still hides the surface inside a host-owned frame.
 
 #### Mounting `PanoMapOverlay`
 
-Mount it from `PanoViewer.renderOverlay` and pass the same `activeSceneId` you pass to `ProjectScenes`. Import `@ericchen1990/pano-view/styles.css` for the built-in `pano-map-*` classes. The overlay reads yaw and FOV from the viewer. It does not change scenes by itself: set the active scene from `onSelectScene`. Pass `view` when the camera state comes from outside the viewer; outside the viewer with no `view`, the surface stays at yaw `0`, pitch `0`, fov `75`. `PanoMap` is the surface alone, for a host-owned frame.
+Mount it inside `PanoOverlay` and pass the same `activeSceneId` you pass to `ProjectScenes`. Import `@ericchen1990/pano-view/styles.css` for the built-in `pano-map-*` classes. The overlay reads yaw and FOV from the viewer. It does not change scenes by itself: set the active scene from `onSelectScene`. Pass `view` when the camera state comes from outside the viewer; outside the viewer with no `view`, the surface stays at yaw `0`, pitch `0`, fov `75`. `PanoMap` is the surface alone, for a host-owned frame.
 
-`PanoMap` also accepts controlled selection and collapse: `selectedSpotId` / `onSelectedSpotIdChange` (internal selection defaults to `null`); `collapsed` / `onCollapsedChange` (uncontrolled starts expanded); `renderChrome` to draw host controls above the surface. `showZoomControls` / `showCollapseControl` work on `PanoMap` the same way as on the overlay. `className` / `style` attach to the surface root.
+`PanoMap` also accepts controlled selection and collapse: `selectedSpotId` / `onSelectedSpotIdChange` (internal selection defaults to `null`); `collapsed` / `onCollapsedChange` (uncontrolled starts expanded and hides the surface inside the host frame); `renderChrome` to draw host controls above the surface. On `PanoMapOverlay`, `showCollapseControl` shows the shared edge tab instead. `className` / `style` attach to the surface root.
 
 ```tsx
 import { useState } from "react";
 import {
-  PanoViewer, ProjectScenes, PanoMapOverlay, type LoadedPanoProject,
+  PanoOverlay, PanoViewer, ProjectScenes, PanoMapOverlay, type LoadedPanoProject,
 } from "@ericchen1990/pano-view";
 import "@ericchen1990/pano-view/styles.css";
 
 export function Tour({ project }: { project: LoadedPanoProject }) {
   const [activeSceneId, setActiveSceneId] = useState(project.initialSceneId);
   const map = project.map;
-  return <PanoViewer style={{ height: 600 }} renderOverlay={map ? () => (
-    <PanoMapOverlay
-      map={map}
-      activeSceneId={activeSceneId}
-      onSelectScene={setActiveSceneId}
-    />
-  ) : undefined}>
+  return <PanoViewer style={{ height: 600 }}>
     <ProjectScenes
       project={project}
       activeSceneId={activeSceneId}
       onActiveSceneIdChange={setActiveSceneId}
     />
+    {map ? (
+      <PanoOverlay>
+        <PanoMapOverlay
+          map={map}
+          activeSceneId={activeSceneId}
+          onSelectScene={setActiveSceneId}
+        />
+      </PanoOverlay>
+    ) : null}
   </PanoViewer>;
 }
 ```
 
-#### Size, corner, and inset
+#### Size, align, and inset
 
-- `presentation` — `"docked"` | `"dialog"` (defaults from the document, otherwise `"docked"`).
-- `corner` — `"top-left"` | `"top-right"` | `"bottom-left"` | `"bottom-right"` (default `"bottom-left"`).
-- `width` / `height` — docked panel size, or the dialog launcher size, in CSS pixels. Docked defaults to 220×160; the dialog launcher defaults to 48×48.
-- `offsetX` / `offsetY` — inset from the chosen corner in CSS pixels (default 16).
+- `presentation` — `"panel"` | `"dialog"` (defaults from the document, otherwise `"panel"`).
+- `anchor` — shared `PanoOverlayAnchor`. `align` is one of eight positions (default `"bottom-left"`). `axis` is used for corners. `inset` defaults to `16`.
+- `width` / `height` — panel size, or the dialog launcher size, in CSS pixels. Panel defaults to 220×160; the dialog launcher defaults to 48×48.
 
 ```tsx
 <PanoMapOverlay
   map={map}
   activeSceneId={activeSceneId}
   onSelectScene={setActiveSceneId}
-  presentation="docked"
-  corner="bottom-right"
+  presentation="panel"
+  anchor={{ align: "bottom-right", axis: "vertical", inset: 20 }}
   width={280}
   height={200}
-  offsetX={20}
-  offsetY={20}
 />
 ```
 
 #### Dialog mode
 
-Dialog mode docks a launcher button and opens the map in a viewer-local modal. Launcher size uses `width` / `height` (and `corner` / offsets). The dialog body uses a separate pair:
+Dialog mode places a launcher button and opens the map in a viewer-local modal. Launcher size uses `width` / `height`, and the launcher uses the same `anchor`. The dialog body uses a separate pair:
 
 - `dialogWidth` / `dialogHeight` — preferred dialog size in CSS pixels (default 720×520). Both are clamped to the viewer with a 16 px margin on each side.
 - `openLabel` / `closeLabel` / `title` — launcher accessible name, close button label, and dialog heading (defaults `"Map"`, `"Close"`, `"Map"`).
@@ -365,7 +368,7 @@ Choosing a spot closes the dialog.
   activeSceneId={activeSceneId}
   onSelectScene={setActiveSceneId}
   presentation="dialog"
-  corner="bottom-left"
+  anchor={{ align: "bottom-left", inset: 16 }}
   width={52}
   height={52}
   dialogWidth={640}
@@ -401,6 +404,36 @@ These props override the map document for the current mount:
 />
 ```
 
+`toggle` replaces the panel edge-tab icon or restyles that button. Dialog mode has no edge tab. Omit `toggle` to keep the default chevron. Pass an element (`<Icon />`) for `icon`, not a component type. When the glyph depends on the collapsed state, pass a function of `{ collapsed }`. `className` is appended to the button. `style` overrides background, border, color, and size. Position and `transform` belong to the edge layout; do not set them in `style`. The default chevron uses `currentColor`, so `style.color` recolors it without replacing the icon.
+
+```tsx
+<PanoMapOverlay
+  map={map}
+  activeSceneId={activeSceneId}
+  onSelectScene={setActiveSceneId}
+  showCollapseControl
+  toggle={{ style: { color: "#7dd3fc" } }}
+/>
+```
+
+```tsx
+<PanoMapOverlay
+  map={map}
+  activeSceneId={activeSceneId}
+  onSelectScene={setActiveSceneId}
+  showCollapseControl
+  toggle={{
+    className: "map-tab",
+    style: {
+      background: "#0c4a6e",
+      color: "#7dd3fc",
+      border: "1px solid #7dd3fc",
+    },
+    icon: ({ collapsed }) => (collapsed ? "+" : "–"),
+  }}
+/>
+```
+
 #### Edit mode
 
 `mode="edit"` is the authoring surface: with `placementSceneId` set, a click adds a spot whose heading is the negation of the current yaw, so the sector points image-up at that yaw; dragging a spot moves it, and dragging the sector sets `heading`. `onEditChange` reports `{ spots?, selectedSpotId? }`. Visitor playback stays on the default `mode="view"`. `editorSurface` enlarges the panel for authoring; pass `width` / `height` to size that surface, otherwise it scales with the viewer.
@@ -679,14 +712,15 @@ Presets and hotspot rendering are in [Scenes](#scenes).
 ### Events and chrome
 
 - [`PanoEvents`](#panoevents) — viewer-level lifecycle and interaction callbacks
+- [`PanoOverlay`](#dom-overlays-and-dialogs) — screen-plane DOM wrapper for fullscreen-safe UI
 - [`PanoContextMenu`](#panocontextmenu) — right-click reset / fullscreen menu
-- [`PanoSceneMenu`](#panoscenemenu) — scrollable thumbnail scene picker for `renderOverlay`
+- [`PanoSceneMenu`](#panoscenemenu) — scrollable thumbnail scene picker for `PanoOverlay`
 - [`PanoVideoControls`](#panovideo) — playback chrome for `PanoVideo` (mounted by default)
 
 ### Floor plan
 
 - [`PanoMap`](#floor-plan-maps) — floor image, scene spots, and the yaw-linked sector
-- [`PanoMapOverlay`](#floor-plan-maps) — docked panel or dialog launcher for `renderOverlay`
+- [`PanoMapOverlay`](#floor-plan-maps) — panel or dialog launcher for `PanoOverlay`
 
 ### Hotspots
 
@@ -711,7 +745,25 @@ Presets and hotspot rendering are in [Scenes](#scenes).
 
 ## DOM overlays and dialogs
 
-Use `PanoViewer.renderOverlay` for ordinary DOM UI outside the Three.js tree. Call `usePanoOverlay()` inside the `renderOverlay` subtree to get `portalContainer`, `size` (viewer width/height), `visibleRect`, and `isFullscreen`. `usePanoModal(open)` holds that viewer's modal lock while `open === true` (pauses input and auto-rotate, marks the backdrop inert, closes the context menu); it does not trap focus. `PanoOverlayPortalProvider` takes a required `container` and `children` and only remaps `portalContainer` for descendants; `size` / `visibleRect` still describe the whole viewer. Field meanings, reference counting, and third-party Dialog wiring live in the separate **[Dialog and styling guide](./docs/dialogs.md)**. The optional `/ui` entry provides `PanoDialog` and composable parts. The guide ships in the npm package; run `pnpm dev` and open `/overlays` for local examples.
+Prefer `PanoOverlay` for ordinary DOM UI outside the Three.js tree. It mounts on the viewer plane inside the fullscreen root, so chrome stays visible when the viewer goes fullscreen. Place it as a direct child of `PanoViewer` (or inside a Fragment under it) beside scene content. `renderOverlay` remains supported for callback-style mounts.
+
+```tsx
+<PanoViewer style={{ height: 560 }}>
+  <Sphere src="/pano.jpg" />
+  <PanoOverlay>
+    <PanoSceneMenu items={items} activeId={id} onSelect={setId} />
+    <button
+      type="button"
+      style={{ position: "absolute", right: 16, bottom: 16, pointerEvents: "auto" }}
+      onClick={() => void viewer.toggleFullscreen()}
+    >
+      Fullscreen
+    </button>
+  </PanoOverlay>
+</PanoViewer>
+```
+
+The overlay layer is `position: absolute; inset: 0; pointer-events: none`. Position children yourself and set `pointerEvents: "auto"` on interactive nodes. When both are used, `renderOverlay` renders first and each `PanoOverlay` follows in document order. Call `usePanoOverlay()` inside `PanoOverlay` (or `renderOverlay`) to get `portalContainer`, `size` (viewer width/height), `visibleRect`, and `isFullscreen`. `usePanoModal(open)` holds that viewer's modal lock while `open === true` (pauses input and auto-rotate, marks the backdrop inert, closes the context menu); it does not trap focus. `PanoOverlayPortalProvider` takes a required `container` and `children` and only remaps `portalContainer` for descendants; `size` / `visibleRect` still describe the whole viewer. Field meanings, reference counting, and third-party Dialog wiring live in the separate **[Dialog and styling guide](./docs/dialogs.md)**. The optional `/ui` entry provides `PanoDialog` and composable parts. The guide ships in the npm package; run `pnpm dev` and open `/overlays` for local examples.
 
 ### Default dialog
 
@@ -798,7 +850,7 @@ which use their spherical center. Hotspot ids must be unique within a viewer.
 
 **Scenes** (requires `<Scenes />`) — `setScene(id)`, `nextScene`, `previousScene`, `getActiveSceneId`, `getSceneIds`, `isSceneTransitioning`. `Scenes` accepts `defaultActiveSceneId` (uncontrolled) or `activeSceneId` (controlled). In controlled mode imperative calls invoke `onActiveSceneIdChange`.
 
-**WebVR** (requires `<WebVR />`) — `enterVR`, `exitVR`, `toggleVR`, `isVRAvailable`, `isVREnabled`, `getVRMode`, `requestVRPermission`.
+**WebVR** (requires `<WebVR />`) — `enterVR`, `exitVR`, `toggleVR`, `isVRAvailable`, `isVREnabled`, `getVRMode`, `getVRState`, `subscribeVR`, `requestVRPermission`. Use `subscribeVR` with `useSyncExternalStore` for reactive Enter / Exit buttons; the built-in chrome no longer renders an Enter VR control.
 
 **Video** (requires `<PanoVideo />`) — `getVideo` returns the `PanoVideoController`, `subscribeVideo` subscribes to video controller and playback-state changes, plus convenience aliases `playVideo`, `pauseVideo`, `toggleVideo`, `seekVideo`, `setVideoVolume`, `setVideoMuted`, `toggleVideoMuted`.
 
@@ -814,7 +866,7 @@ which use their spherical center. Hotspot ids must be unique within a viewer.
 - `cursors` — `true` / omit uses grab / grabbing / pointer / move; `false` leaves the canvas cursor unchanged; an object overrides those four states.
 - `contextMenu` — `true` / omit mounts Reset view + Fullscreen; `false` skips the default menu; an object can change appearance or `items` / `prepend` / `append`. See [PanoContextMenu](#panocontextmenu).
 - `mediaActivation` — enabled by default when a mounted child intends to play; `false` disables automatic activation.
-- `renderOverlay` — DOM UI outside the Three.js tree and inside fullscreen; the callback receives `portalContainer`, `size`, `visibleRect`, and `isFullscreen`.
+- `renderOverlay` — optional callback-style DOM UI outside the Three.js tree and inside fullscreen; the callback receives `portalContainer`, `size`, `visibleRect`, and `isFullscreen`. Prefer `<PanoOverlay>` as a child.
 - `onViewChange` — `{ yaw, pitch, fov }` in degrees.
 - `onPanoramaClick` / `onPanoramaDoubleClick` / `onPanoramaPointerMove` — panorama pointer events with `position` (yaw / pitch), `nativeEvent`, `button`, `buttons`, `clientX`, `clientY`, and optional `pointerId`.
 - Other standard `div` props (`className`, `style`, `id`, …) are accepted; conflicting `onChange` and `contextMenu` are omitted from the type.
@@ -913,25 +965,29 @@ function SceneExample() {
 ### WebVR
 
 `enterVR` and `requestVRPermission` must be called from a user gesture.
+Drive entry from host UI with `getVRState` / `subscribeVR`; session chrome only
+shows Exit VR and MobileVR Setup (which fade after a few idle seconds).
 
 ```tsx
+import { useSyncExternalStore } from "react";
 import { PanoViewer, Sphere, WebVR, usePanoViewer } from "@ericchen1990/pano-view";
 
 function VRExample() {
   const viewer = usePanoViewer();
+  const vr = useSyncExternalStore(
+    viewer.subscribeVR,
+    viewer.getVRState,
+    viewer.getVRState,
+  );
 
   return (
     <>
       <button
-        onClick={async () => {
-          await viewer.requestVRPermission();
-          await viewer.enterVR();
-        }}
+        disabled={!vr.available}
+        onClick={() => void (vr.enabled ? viewer.exitVR() : viewer.enterVR())}
       >
-        Enter VR
+        {vr.enabled ? "Exit VR" : "Enter VR"}
       </button>
-      <button onClick={() => void viewer.exitVR()}>Exit VR</button>
-      <button onClick={() => console.log(viewer.getVRMode())}>Mode?</button>
       <PanoViewer ref={viewer.ref} style={{ height: 560 }}>
         <WebVR />
         <Sphere src="/panoramas/room.webp" previewUrl="preview.webp" />
@@ -1470,8 +1526,8 @@ Scene `viewLimits` are covered in the FAQ; `yawOffset` matches the source compon
 ## PanoSceneMenu
 
 `PanoSceneMenu` is a scrollable thumbnail strip for switching scenes. Mount it
-from `PanoViewer.renderOverlay` so it stays inside the viewer (including
-fullscreen). Import `@ericchen1990/pano-view/styles.css` for the default layout.
+inside `PanoOverlay` so it stays inside the viewer (including fullscreen).
+Import `@ericchen1990/pano-view/styles.css` for the default layout.
 
 The menu is host-driven: you pass `items`, `activeId`, and `onSelect`. It does
 not read `Scenes` state or scene `previewUrl`. Cube `previewUrl` values are
@@ -1485,6 +1541,7 @@ Keep one controlled scene id and share it with `Scenes`:
 ```tsx
 import { useState } from "react";
 import {
+  PanoOverlay,
   PanoSceneMenu,
   PanoViewer,
   Scenes,
@@ -1509,21 +1566,19 @@ export function Tour() {
   const [activeSceneId, setActiveSceneId] = useState("lobby");
 
   return (
-    <PanoViewer
-      style={{ height: 560 }}
-      renderOverlay={() => (
-        <PanoSceneMenu
-          activeId={activeSceneId}
-          items={menuItems}
-          onSelect={setActiveSceneId}
-        />
-      )}
-    >
+    <PanoViewer style={{ height: 560 }}>
       <Scenes
         scenes={scenes}
         activeSceneId={activeSceneId}
         onActiveSceneIdChange={setActiveSceneId}
       />
+      <PanoOverlay>
+        <PanoSceneMenu
+          activeId={activeSceneId}
+          items={menuItems}
+          onSelect={setActiveSceneId}
+        />
+      </PanoOverlay>
     </PanoViewer>
   );
 }
@@ -1535,18 +1590,21 @@ active item gets a selection ring above the thumbnail and `data-active="true"`.
 Scene names sit on a dark translucent bar at the bottom of each thumbnail;
 use `appearance.labelAlign` for `"center"` or `"end"` alignment.
 
-### Placement, inset, and size
+### Align, inset, and size
+
+`anchor` is the shared `PanoOverlayAnchor` used by the scene menu and the floor-plan map.
 
-- `placement` — `"top"` | `"bottom"` | `"left"` | `"right"` (default `"bottom"`).
-  Top/bottom render a horizontal strip; left/right render a vertical strip.
-- `align` — `"start"` | `"center"` | `"end"` (default `"center"`). When the menu
-  is smaller than the available dock space, aligns it along that edge. Short
-  lists are also aligned inside the strip the same way.
-- `inset` — gap from the viewer edges (default `12`). A number is pixels; a
+- `anchor.align` — `"top"` | `"bottom"` | `"left"` | `"right"` | `"top-left"` | `"top-right"` | `"bottom-left"` | `"bottom-right"` (default `"bottom"`).
+  Top and bottom are horizontal strips. Left and right are vertical strips.
+  A corner uses `anchor.axis`.
+- `anchor.axis` — `"horizontal"` | `"vertical"`. Edges ignore it. Corners default to `"horizontal"`: a horizontal strip slides up or down, and a vertical strip slides left or right.
+- `anchor.inset` — gap from the viewer edges (default `12`). A number is pixels; a
   string keeps units such as `"1rem"`; an object sets `top` / `right` /
-  `bottom` / `left` independently.
+  `bottom` / `left` independently. Safe-area insets are added.
 - `width` / `height` — menu size. A number is pixels; a string is used as CSS as-is,
   including `%`, `rem`, `calc()`, `min()`, `max()`, and `clamp()`.
+  On an edge, a set main-axis size is centered and a missing one stretches between the cross-axis insets. A corner pins to both edges and shrinks to content when a size is omitted.
+  Short lists pack toward the corner, or stay centered on an edge.
 - `dragMotion` — scroll inertia and edge bounce. Omit for both on (custom pointer
   scrolling, including desktop drag). Set `false` for native overflow scroll.
   Pass `{ inertia?: boolean; bounce?: boolean }` to toggle either flag. A short
@@ -1554,9 +1612,7 @@ use `appearance.labelAlign` for `"center"` or `"end"` alignment.
 
 ```tsx
 <PanoSceneMenu
-  placement="bottom"
-  align="center"
-  inset={16}
+  anchor={{ align: "bottom", inset: 16 }}
   width="min(720px, 100%)"
   items={menuItems}
   activeId={activeSceneId}
@@ -1564,9 +1620,11 @@ use `appearance.labelAlign` for `"center"` or `"end"` alignment.
 />
 
 <PanoSceneMenu
-  placement="right"
-  align="start"
-  inset={{ top: 24, right: 12, bottom: 24, left: 12 }}
+  anchor={{
+    align: "top-left",
+    axis: "vertical",
+    inset: { top: 24, right: 12, bottom: 24, left: 12 },
+  }}
   height="70%"
   width={160}
   items={menuItems}
@@ -1575,8 +1633,8 @@ use `appearance.labelAlign` for `"center"` or `"end"` alignment.
 />
 ```
 
-If you omit `width` on a top/bottom menu, the strip stretches between the left
-and right insets. If you omit `height` on a left/right menu, it stretches between
+If you omit `width` on a top or bottom menu, the strip stretches between the left
+and right insets. If you omit `height` on a left or right menu, it stretches between
 the top and bottom insets. The menu also applies a max size that subtracts
 `inset` and safe-area insets, so `100%` still stays inside the viewer.
 
@@ -1585,9 +1643,8 @@ Use `style` when you need one-off positioning overrides on top of these props.
 ### Collapsible menu and arrows
 
 By default the menu stays open. Set `collapsible` to show a toggle centered on
-the inner edge of the strip (above a bottom menu, below a top menu, toward the
-viewer for left/right). Collapsing slides the list off-screen along the dock
-edge and leaves only the expand button on the safe-area edge:
+the inner side of the collapse edge. Collapsing slides the list off-screen by
+its size plus that edge's inset, and leaves the expand button on the viewer edge:
 
 ```tsx
 <PanoSceneMenu
@@ -1623,7 +1680,7 @@ via `label`. When collapsible, `defaultExpanded` defaults to `true`.
   showArrows
   loop
   collapsible
-  placement="bottom"
+  anchor={{ align: "bottom" }}
   width="min(720px, 100%)"
   items={menuItems}
   activeId={activeSceneId}
@@ -1677,6 +1734,43 @@ The root also exposes `data-placement`, `data-align`, `data-orientation`
 (`horizontal` | `vertical`), `data-expanded`, and `data-collapsible`. The active
 item has `data-active="true"`.
 
+When `collapsible` is set, `toggle` replaces the edge-tab icon or restyles that
+button. Omit `toggle` to keep the default chevron. Pass an element (`<Icon />`)
+for `icon`, not a component type. When the glyph depends on the collapsed
+state, pass a function of `{ collapsed }` (`collapsed` is `false` while the
+menu is expanded). `className` is appended to the button. `style` overrides
+background, border, color, and size. Position and `transform` belong to the
+edge layout; do not set them in `style`. The default chevron uses
+`currentColor`, so `style.color` recolors it without replacing the icon.
+
+```tsx
+<PanoSceneMenu
+  collapsible
+  toggle={{ style: { color: "#7dd3fc" } }}
+  items={menuItems}
+  activeId={activeSceneId}
+  onSelect={setActiveSceneId}
+/>
+```
+
+```tsx
+<PanoSceneMenu
+  collapsible
+  toggle={{
+    className: "scene-tab",
+    style: {
+      background: "#0c4a6e",
+      color: "#7dd3fc",
+      border: "1px solid #7dd3fc",
+    },
+    icon: ({ collapsed }) => (collapsed ? "+" : "–"),
+  }}
+  items={menuItems}
+  activeId={activeSceneId}
+  onSelect={setActiveSceneId}
+/>
+```
+
 ## PanoFilter
 
 Render `PanoFilter` inside `PanoViewer` to color-grade or stylize the panorama
@@ -1908,8 +2002,9 @@ These are props on `Gyro` itself. `PanoEvents` `onGyro*` callbacks subscribe to
 `WebVR` adds immersive viewing to the nearest `PanoViewer`. It prefers an
 `immersive-vr` WebXR session on supported headsets. On phones without WebXR it
 uses a stereoscopic split-screen view with device orientation, and on desktop
-it can provide a mouse-driven simulated VR preview. The built-in chrome includes
-Enter VR, Exit VR, and MobileVR setup controls.
+it can provide a mouse-driven simulated VR preview. Host apps provide Enter VR
+through the viewer handle; the built-in chrome only shows Exit VR and MobileVR
+setup controls while a session is active (they fade after idle interaction).
 
 ```tsx
 import { useRef } from "react";
@@ -1939,19 +2034,28 @@ export function WebVRExample() {
 ```
 
 The handle exposes `enterVR()`, `exitVR()`, `toggleVR()`, `isAvailable()`,
-`isEnabled()`, `getMode()`, and `requestPermission()`. Modes are `"webxr"`,
-`"mobilevr"`, and `"fake"`. `profile` accepts `"none"`, `"cardboard-v1"`,
-`"cardboard-v2"`, `"gear-vr"`, `"daydream"`, or a custom
-`{ fov, ipdMm, k1, k2 }` lens profile. MobileVR setup values are versioned and
-stored in the current origin's `localStorage`. In VR, a center reticle shows a
-crosshair; looking at an interactive hotspot draws a clockwise ring that fills
-over `cursorDwellMs` (default 1500), then the hotspot click handler runs. Set
-`cursorDwellMs={0}` to keep the reticle without auto-click. Simulated desktop
-VR (`fake` mode) requests pointer lock by default (`mousePointerLock`) so the
-cursor hides and mouse movement looks around; click the view again if the
-browser releases the lock. Fallback sessions keep the screen awake
-(`wakelock`) with the Screen Wake Lock API, or a looping hidden video on
-browsers that lack it.
+`isEnabled()`, `getMode()`, `getState()`, `subscribe()`, `requestPermission()`,
+and `resetSettings()`. Modes are `"webxr"`, `"mobilevr"`, and `"fake"`.
+`profile` accepts `"none"`, `"cardboard-v1"`, `"cardboard-v2"`, `"gear-vr"`,
+`"daydream"`, or a custom `{ fov, ipdMm, k1, k2, screenToLensMm?, trayDistanceMm? }`
+lens profile. When the physical screen size is known, MobileVR places each eye's
+optical axis with the inter-lens distance and optional tray-to-lens height
+(`trayDistanceMm`; Cardboard V1 uses `35`). `0` or omitted keeps the vertical
+center. When `screensize` is `"auto"`, MobileVR loads the Cardboard Device
+Parameter Database (`databaseUrl`, default Google's public DPDB) to estimate
+diagonal inches; pass `""` or `null` to skip the request. Unknown devices fire
+`onUnknownDevice` and keep the lens-profile FOV (no tray offset until a size is
+known). MobileVR setup values are versioned and stored in the current origin's
+`localStorage`; `resetSettings()` clears that storage and restores prop or
+built-in defaults (also available from the Setup panel Reset control). In VR, a
+center reticle shows a crosshair; looking at an interactive hotspot draws a
+clockwise ring that fills over `cursorDwellMs` (default 1500), then the hotspot
+click handler runs. Set `cursorDwellMs={0}` to keep the reticle without
+auto-click. Simulated desktop VR (`fake` mode) requests pointer lock by default
+(`mousePointerLock`) so the cursor hides and mouse movement looks around; click
+the view again if the browser releases the lock. Fallback sessions keep the
+screen awake (`wakelock`) with the Screen Wake Lock API, or a looping hidden
+video on browsers that lack it.
 
 WebXR requires HTTPS and a user gesture. Mobile sensor access also requires
 HTTPS and may require an explicit iOS permission prompt. Embedded viewers need
@@ -1962,19 +2066,27 @@ interactive through the default WebXR controller rays.
 
 ### Props
 
-- `chrome` — default `true` mounts Enter / Exit / Setup UI. An appearance object may set `background` (default `rgba(16, 24, 32, 0.78)`), `color` (`#ffffff`), `accent` (`#7dd3fc`), `borderRadius` (`6`), `fontSize` (`14`), and optional `setupTitle`.
+- `chrome` — default `true` mounts session Exit / Setup UI (no Enter VR button). An appearance object may set `background` (default `rgba(16, 24, 32, 0.78)`), `color` (`#ffffff`), `accent` (`#7dd3fc`), `borderRadius` (`6`), `fontSize` (`14`), and optional `setupTitle`. Session buttons fade after ~3s idle and return on pointer / wheel / keyboard interaction with the viewer.
 - `mobileVr` — default `true`.
 - `desktopSupport` — default `false` (independent of the same-named `Gyro` prop).
 - `fakeSupport` — default `true` for mouse-driven desktop simulation.
 - `screensize` — `"auto"` (factory / omitted storage default) or inches; numbers are clamped to **3–20** with one decimal place.
-- `profile` — omitted values use stored settings; factory default is `"cardboard-v1"`. Also accepts `"none"`, `"cardboard-v2"`, `"gear-vr"`, `"daydream"`, or a custom `{ fov, ipdMm, k1, k2, screenToLensMm?, label?, id? }`.
+- `databaseUrl` — Cardboard DPDB URL for `"auto"` screensize. Default `https://storage.googleapis.com/cardboard-dpdb/dpdb.json`. Pass `""` or `null` to disable the online lookup.
+- `profile` — omitted values use stored settings; factory default is `"cardboard-v1"`. Also accepts `"none"`, `"cardboard-v2"`, `"gear-vr"`, `"daydream"`, or a custom `{ fov, ipdMm, k1, k2, screenToLensMm?, trayDistanceMm?, label?, id? }`. `trayDistanceMm` is millimetres from the headset tray bottom to the lens center; `0` / omitted keeps the vertical optical axis at screen center.
+- `absolute` — default `false`. Compass-oriented MobileVR heading (no effect in WebXR).
+- `north` — default `0`. Panorama yaw that represents North when `absolute` is enabled.
+- `friction` — default `0` (range `0–0.99`). MobileVR gyro smoothing; keep `0` for normal viewing.
+- `touchSupport` — default `false`. When `true`, allows horizontal touch dragging to correct MobileVR heading (`horizontaloffset`). Disabled by default because headset trays can trigger false touches.
+- `oversampling` — default `1`, clamped to **0.5–2**. Scales the MobileVR distortion render target only (viewports unchanged). For WebXR, sets the framebuffer scale factor before the session starts (cannot change mid-session).
+- `foveation` — optional WebXR fixed foveation in **0–1**. Omit to keep the device default; `0` is full resolution, `1` is maximum edge downsampling.
+- `frameRate` — optional WebXR target rate: `"low" | "mid" | "high"` or a numeric Hz (closest supported rate). Omit to keep the store default (`"high"`).
 - `cursor` — default `true`; `false` hides the center reticle.
 - `cursorDwellMs` — default `1500`; `0` disables auto-click.
 - `wakelock` / `mousePointerLock` — both default to `true`.
 - `onAvailable` / `onUnavailable` — VR capability changes.
 - `onEnterVR` / `onExitVR` — mode `"webxr" | "mobilevr" | "fake"`.
 - `onDenied` — permission or session denial, optional `error`.
-- `onUnknownDevice` — when screen / lens parameters cannot be identified.
+- `onUnknownDevice` — when `"auto"` screensize cannot be resolved from the DPDB (disabled URL, no match, or fetch failure).
 
 ## Mouse, touch, and keyboard controls