@ericchen1990/pano-view 3.5.0 → 3.6.0

package/README.md

@@ -17,6 +17,7 @@ Try the components in the [live playground](https://pano-view-playground.vercel.
 - [Examples](#examples)
 - [Exported components](#exported-components)
 - [PanoViewer](#panoviewer)
+- [DOM overlays and dialogs](#dom-overlays-and-dialogs)
 - [Sphere](#sphere)
 - [PanoVideo](#panovideo)
 - [Tile](#tile)
@@ -200,6 +201,50 @@ export function Tour() {
 
 Configured `initialView` values apply at `onSceneReady`, defaulting missing fields to yaw 0, pitch 0, fov 75. With no view configured, the current view is retained. Hotspots hide during transitions. Control selection with `activeSceneId` / `onActiveSceneIdChange`. Call `event.preventDefault()` in `onHotspotClick` to cancel the default action. `onHotspotError` receives the scene, hotspot and original error (media errors may be events containing an `error` field). `renderHotspot(hotspot, context)` returns `undefined` for the default renderer or `null` to hide an item. Context includes `sceneId`, `playing`, `onClick`, `togglePlayback`, `reportError` and `renderDefault`.
 
+### Hotspot actions and shared popup content
+
+`ProjectHotspotAction` is a discriminated union. Keep `{ type: "scene", sceneId }` for navigation. Use `{ type: "view", view: { yaw, pitch, fov }, duration?: number }` to animate the current scene (700 ms by default, 0 for immediate movement), or `{ type: "popup", popupId }` to request shared content. Narrow `action.type` before reading `sceneId`. Explicit actions take priority over media playback and can all be cancelled with `onHotspotClick(event).preventDefault()`.
+
+Add an optional project-level `popups: ProjectPopupDefinition[]`. Each entry has a unique `id`, a nonempty `title`, and ordered `blocks` with unique IDs within that popup:
+
+```json
+{
+  "id": "story",
+  "title": "About this place",
+  "blocks": [
+    { "id": "intro", "type": "text", "text": "Plain text, including line breaks." },
+    { "id": "photo", "type": "image", "src": "media/photo.webp", "alt": "The main hall" },
+    { "id": "film", "type": "video", "src": "media/movie.mp4", "poster": "media/photo.webp" },
+    { "id": "voice", "type": "audio", "src": "media/story.mp3" }
+  ]
+}
+```
+
+Store this content structure in `project.json`; store media as separate files. Popup paths resolve from the project directory, independently of each panorama's `viewer.json`. `loadPanoProject` returns resolved `popups`; its optional `resolvePopupAssetUrl(path, context)` receives `{ defaultUrl, popupId, blockId, field }`, where field is `src` or `poster`. Like the existing resolver, return an absolute URL or site-root path. Existing `resolveAssetUrl` callbacks continue to receive only their scene/hotspot resources. `resolveProjectPopupAssets` is also exported from `/data` for custom loaders. Request credentials for JSON do not automatically protect media.
+
+`ProjectScenes.onPopupRequest({ sceneId, hotspot, popup })` delegates display to your overlay. A missing handler or missing popup reports through `onHotspotError`. The optional UI entry supplies `ProjectPopupDialog` without adding Dialog dependencies to the viewer core:
+
+```tsx
+import { useState } from "react";
+import { 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); }} />
+  )}>
+    <ProjectScenes project={project} onPopupRequest={({ popup }) => setPopup(popup)}
+      onActiveSceneIdChange={() => setPopup(null)} />
+  </PanoViewer>;
+}
+```
+
+`ProjectPopupDialog` accepts `popup` (or `null` to close), `onOpenChange`, optional `closeLabel` and `onMediaError(block)`. It renders text as text, uses native audio/video controls without autoplay, and releases media when content closes or changes. It inherits `PanoDialog` fullscreen, sizing and focus behavior. Replace this component with your own overlay to customize rendering.
+
+The schema remains version 1 and old projects remain valid. Projects using new actions require a viewer that supports them. `parsePanoProject(input, { draft: true })` is for authoring only: it permits empty scene lists and unfinished popup titles/media. Loading, saving and package export validate strictly. Host applications may save the same document in a database or map it to tables; the viewer has no database connection.
+
 For individual panoramas and existing configs use the pure data entry. Next.js viewer components need a client boundary; server-side data loading uses `/data`:
 
 ```ts
@@ -492,6 +537,22 @@ Presets and hotspot rendering are in [Scenes](#scenes).
 - Context menu helpers — `createPanoContextMenuPresets`, `composePanoContextMenuItems`, and related APIs ([`PanoContextMenu`](#panocontextmenu))
 - Polygon / polyline validation — `validatePolygonVertices`, `validatePolylineVertices`, `unwrapPolygonVertices`
 
+## DOM overlays and dialogs
+
+Use `PanoViewer.renderOverlay` for ordinary DOM UI outside the Three.js tree. `usePanoOverlay()` supplies its stable Portal target, measured viewer/visible dimensions and fullscreen state. The optional `/ui` entry provides `PanoDialog` and composable parts; your application can also integrate an existing Dialog.
+
+See the separate **[Dialog and styling guide](./docs/dialogs.md)** for complete examples, CSS variable defaults and placement, custom layouts, third-party integration, nested portals, lifecycle, API tables and troubleshooting. The guide is included in the npm package. Run `pnpm dev` and open `/overlays` for the local examples.
+
+### Default dialog
+
+Start with [Quick start](./docs/dialogs.md#quick-start), then [customize the default appearance](./docs/dialogs.md#customize-the-default-appearance). Default styling is an optional import from `@ericchen1990/pano-view/ui/styles.css`.
+
+For multiple hotspots, use the [complete scene/hotspot-to-content example](./docs/dialogs.md#choose-content-by-hotspot): five content definitions, one shared dialog, matching project JSON and scene-local IDs.
+
+### Compose parts or integrate an existing Dialog
+
+Use [composable parts](./docs/dialogs.md#compose-a-different-layout) for a custom header/body/footer, or [connect an existing Dialog](./docs/dialogs.md#use-an-existing-dialog) through the local Portal container and `usePanoModal(open)`. Fullscreen belongs in viewer-level UI, not in dialog content.
+
 ## PanoViewer
 
 `PanoViewer` owns the canvas, perspective camera, and controls. Give its container an explicit size and place one panorama source inside it.
@@ -2065,6 +2126,8 @@ Playback uses Web Audio via Howler.js (bundled; hosts do not install
 format. `src` may be a string or an array of fallback URLs. The component uses Web Audio rather than HTML5
 streaming to retain stereo panning.
 
+For extensionless sources such as `blob:` URLs, pass `format="mp3"` (or an array of container hints in source order). The optional `format` field is also supported by audio definitions in `project.json`.
+
 `playing` is controlled like `VideoHotspot`. `loop` defaults to `false`,
 `muted` to `false`, `volume` to `1`, and `pauseWhenHidden` to `true` (pause
 when the tab is hidden, resume if `playing` is still true). A first user
@@ -2361,3 +2424,33 @@ Start playback from a click or keyboard gesture, check supported formats and per
 Serve files over local HTTP(S), rather than double-clicking `file://` HTML. HTTPS pages should load HTTPS assets. Use versioned asset directories and coordinate JSON/image caching so stale configs do not target replaced files. `UNSUPPORTED_SCHEMA_VERSION` requires a supported config version. Planar conversions have no `viewer.json` and need a planar viewer.
 
 For conversion failures see [converter error codes and troubleshooting](../converter/README.md#error-codes-and-troubleshooting).
+
+### Camera-center limits
+
+`PanoViewer`, every `Scenes` scene, and each `project.json` scene accept optional `viewLimits`:
+
+```ts
+viewLimits: {
+  yaw: { min: 170, max: -170 },
+  pitch: { min: -30, max: 45 },
+  fov: { min: 40, max: 90 },
+}
+```
+
+Angles are degrees. Yaw bounds are within −180…180; min > max crosses the seam. −180…180 allows a full circle. Pitch bounds are within −90…90, FOV within 1…179; both require min ≤ max. Equal bounds lock an axis. Scene axes override viewer axes individually; omitted axes inherit viewer settings, with existing `minFov` / `maxFov` (30 / 100 by default) as the FOV fallback. Bounds apply to the camera center, including pointer, touch, keyboard, inertia, auto rotation, gyro and view navigation APIs; they do not keep the entire visible image inside the bounds. Explicit axes have hard boundaries even with `bouncingLimits`. Limited yaw animations stay in the permitted arc, overriding a shorter path through forbidden angles. Immersive WebXR remains controlled by the headset.
+
+Scene limits take effect when the incoming scene takes over, before its initial view. Live changes cancel navigation and inertia and constrain the current view without rewriting authored initial views or reloading textures. Removing scene limits restores viewer limits.
+
+### Hotspot interaction events and custom actions
+
+`events` maps `click`, `pointerenter`, and `pointerleave` to one action each. Every event supports `scene`, `view`, `popup`, and `{ type: "custom", actionId, params? }`. `params` is a JSON object; functions, credentials, API implementations and form definitions belong to the host. Parameter strings are not resolved or packaged as assets.
+
+```json
+{"events":{"click":{"type":"scene","sceneId":"hall"},"pointerenter":{"type":"custom","actionId":"product.preview","params":{"visible":true}},"pointerleave":{"type":"custom","actionId":"product.preview","params":{"visible":false}}}}
+```
+
+Legacy `action` remains a click fallback; `events.click` wins. Editing or clearing click removes the legacy fallback. Loading a project does not migrate it. New event configurations require an updated viewer (project schemaVersion remains 1). Media without a click action still toggles playback; hover has no default action.
+
+`ProjectScenes.onHotspotEvent(event)` receives `trigger`, `sceneId`, `hotspot`, `interaction` and `preventDefault()`. On clicks it runs before the existing `onHotspotClick`; either callback can cancel the action. `onCustomAction(event)` additionally receives `action` and may return a Promise. Dispatch by the stable `action.actionId`, validate business parameters and throw for unknown actions. Missing handlers, synchronous exceptions and rejected Promises reach `onHotspotError` with `trigger`. Requests, authentication, cancellation, duplicate prevention and response ordering are host responsibilities; events dispatch independently without automatic retries.
+
+Hover runs once per logical hotspot boundary, skips touch and keyboard focus, and respects visibility and pointer interaction settings. Scene changes, hiding and unmounting clear hover state without executing leave actions. Existing tooltip behavior is independent. Custom renderers must forward `context.onHoverChange(hovered, interaction)` as well as `context.onClick`; `context.renderDefault()` wires both automatically.

package/README.zh-CN.md

@@ -17,6 +17,7 @@
 - [示例](#示例)
 - [导出组件](#导出组件)
 - [PanoViewer](#panoviewer)
+- [DOM Overlay 与弹窗](#dom-overlay-与弹窗)
 - [Sphere](#sphere)
 - [PanoVideo](#panovideo)
 - [Tile](#tile)
@@ -196,6 +197,50 @@ export function Tour() {
 
 配置了 `initialView` 的场景在 `onSceneReady` 时应用视角，缺省字段为 yaw 0、pitch 0、fov 75；未配置时保持当前视角。过渡期间热点隐藏。使用 `activeSceneId` / `onActiveSceneIdChange` 可控制当前场景。`onHotspotClick(event)` 中调用 `event.preventDefault()` 可取消默认动作；`onHotspotError` 提供场景、热点和原始错误；媒体的原始错误可能是带有 `error` 字段的事件。`renderHotspot(hotspot, context)` 返回 `undefined` 使用默认渲染，返回 `null` 隐藏；context 包含 `sceneId`、`playing`、`onClick`、`togglePlayback`、`reportError` 和 `renderDefault`。
 
+### 热点动作与共享弹窗内容
+
+`ProjectHotspotAction` 是可辨别联合类型。场景跳转保持 `{ type: "scene", sceneId }`；`{ type: "view", view: { yaw, pitch, fov }, duration?: number }` 调整当前场景视角，默认动画 700 毫秒，0 表示立即应用；`{ type: "popup", popupId }` 请求共享内容。读取 `sceneId` 前先判断 `action.type`。显式动作优先于媒体播放，三种动作均可由 `onHotspotClick(event).preventDefault()` 取消。
+
+项目新增可选 `popups: ProjectPopupDefinition[]`。每项包含唯一 `id`、非空 `title` 和有序 `blocks`；内容块 ID 在弹窗内唯一：
+
+```json
+{
+  "id": "story",
+  "title": "About this place",
+  "blocks": [
+    { "id": "intro", "type": "text", "text": "Plain text, including line breaks." },
+    { "id": "photo", "type": "image", "src": "media/photo.webp", "alt": "The main hall" },
+    { "id": "film", "type": "video", "src": "media/movie.mp4", "poster": "media/photo.webp" },
+    { "id": "voice", "type": "audio", "src": "media/story.mp3" }
+  ]
+}
+```
+
+内容结构存在 `project.json`，媒体保留为独立文件。弹窗路径相对项目目录解析，不跟随各全景的 `viewer.json`。`loadPanoProject` 返回解析后的 `popups`；新增可选 `resolvePopupAssetUrl(path, context)`，上下文是 `{ defaultUrl, popupId, blockId, field }`，field 为 `src` 或 `poster`；返回绝对 URL 或站点根路径。原有 `resolveAssetUrl` 回调继续只处理场景/热点资源。自定义加载器也可使用 `/data` 导出的 `resolveProjectPopupAssets`。JSON 请求的凭证不会自动保护媒体资源。
+
+`ProjectScenes.onPopupRequest({ sceneId, hotspot, popup })` 将展示交给宿主 Overlay。缺少处理器或目标弹窗时通过 `onHotspotError` 报错。独立 UI 入口提供 `ProjectPopupDialog`，查看器主入口不引入 Dialog 依赖：
+
+```tsx
+import { useState } from "react";
+import { 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); }} />
+  )}>
+    <ProjectScenes project={project} onPopupRequest={({ popup }) => setPopup(popup)}
+      onActiveSceneIdChange={() => setPopup(null)} />
+  </PanoViewer>;
+}
+```
+
+`ProjectPopupDialog` 接收 `popup`（null 关闭）、`onOpenChange`，以及可选 `closeLabel` 和 `onMediaError(block)`。文字按纯文本展示，音视频使用原生控件且不自动播放；关闭或切换内容时释放媒体。全屏、尺寸和焦点行为复用 `PanoDialog`。需要自定义渲染时可替换成自己的 Overlay。
+
+继续使用 schemaVersion 1，旧项目仍可读取，包含新动作的项目需使用支持它们的新版查看器。`parsePanoProject(input, { draft: true })` 仅用于编辑草稿，允许空场景列表及未完成的弹窗标题/媒体；加载、保存和导出仍严格校验。宿主可将同一份文档存入数据库或映射到表，查看器不直接连接数据库。
+
 单图和已有配置可用纯数据入口；Next.js 的查看器组件需位于客户端边界，服务端加载数据则使用 `/data`：
 
 ```ts
@@ -467,6 +512,22 @@ export function Tour() {
 - 右键菜单辅助 — `createPanoContextMenuPresets`、`composePanoContextMenuItems` 及相关 API（[`PanoContextMenu`](#panocontextmenu)）
 - 多边形 / 折线校验 — `validatePolygonVertices`、`validatePolylineVertices`、`unwrapPolygonVertices`
 
+## DOM Overlay 与弹窗
+
+普通 DOM 界面使用 `PanoViewer.renderOverlay`，位于 Three.js 渲染树之外。`usePanoOverlay()` 提供稳定的 Portal 容器、viewer/可见区域尺寸和全屏状态。可选 `/ui` 入口提供 `PanoDialog` 与组成组件，也可以接入应用已有的 Dialog。
+
+独立的 **[弹窗使用与自定义样式指南](./docs/dialogs.zh-CN.md)** 包含完整示例、CSS 变量默认值与放置位置、布局组合、第三方接入、二级 Portal、生命周期、API 表和排错说明。指南随 npm 包分发。在本仓库运行 `pnpm dev`，打开 `/overlays` 可体验示例。
+
+### 默认弹窗
+
+从[快速开始](./docs/dialogs.zh-CN.md#quick-start)接入，再[定制默认外观](./docs/dialogs.zh-CN.md#customize-the-default-appearance)。默认外观单独导入 `@ericchen1990/pano-view/ui/styles.css`，也可不导入。
+
+多个热点使用[场景/热点到内容的完整映射示例](./docs/dialogs.zh-CN.md#choose-content-by-hotspot)：五份内容、一个共享弹窗、对应项目 JSON，以及场景内热点 ID 的处理。
+
+### 组成组件与已有 Dialog 接入
+
+自定义标题栏、内容区和底部操作使用[组成组件](./docs/dialogs.zh-CN.md#compose-a-different-layout)；已有 Dialog 使用本地 Portal 容器与 `usePanoModal(open)` [完成接入](./docs/dialogs.zh-CN.md#use-an-existing-dialog)。全屏功能放在 viewer 全局界面，不放入弹窗内容。
+
 ## PanoViewer
 
 `PanoViewer` 负责画布、透视相机与控件。为其容器指定明确尺寸，并在内部放置一个全景源。
@@ -1761,6 +1822,8 @@ import { VideoHotspot } from "@ericchen1990/pano-view";
 
 音频通过 Howler.js 的 Web Audio 模式播放（Howler.js 已包含在本包构建产物中，宿主无需另行安装）。文件需完成解码后才能开始播放，可使用 MP3 格式。`src` 可以是字符串或回退 URL 数组。组件不使用 HTML5 流式音频模式，以保留立体声像控制。
 
+对于 `blob:` 等没有扩展名的音频地址，可传 `format="mp3"`，或按素材顺序传格式数组。`project.json` 中的音频定义也支持可选 `format` 字段。
+
 `playing` 与 `VideoHotspot` 一样受控。`loop` 默认 `false`，`muted` 默认 `false`，`volume` 默认 `1`，`pauseWhenHidden` 默认 `true`（标签页隐藏时暂停，`playing` 仍为 `true` 时，在标签页恢复可见后继续播放）。首次用户手势会解锁音频；若自动播放被阻止，会报告 `"blocked"`，并在 `playing` 仍为 true 时于下一次指针或按键后重试 `play()`。
 
 默认标记在 **停止**（扬声器）与 **播放**（扬声器 + 声波）之间切换。可用 `icon` 自定义停止图标、`playingIcon` 自定义播放图标。只设 `icon` 时两种状态共用该图。`marker={false}` 隐藏标记，仍保留定点声源。整个导览共用或按场景切换的非空间背景音频请使用 [`BackgroundAudio`](#backgroundaudio)。
@@ -1999,3 +2062,33 @@ CORS 不授予对象读取权限。使用 CDN 时也需确保实际响应带有
 通过本地 HTTP(S) 服务预览，不使用 `file://`。HTTPS 页面使用 HTTPS 资源。采用带版本的资源目录，并协调项目 JSON 与图片的缓存，避免旧配置请求新目录。`UNSUPPORTED_SCHEMA_VERSION` 需要匹配支持的配置版本；平面图没有 `viewer.json`，需要平面查看器。
 
 转换阶段的问题另见 [converter 错误码与故障排查](../converter/README.zh-CN.md#错误码与故障排查)。
+
+### 相机中心范围
+
+`PanoViewer`、`Scenes` 的每个场景及 `project.json` 的每个场景均支持可选的 `viewLimits`：
+
+```ts
+viewLimits: {
+  yaw: { min: 170, max: -170 },
+  pitch: { min: -30, max: 45 },
+  fov: { min: 40, max: 90 },
+}
+```
+
+角度单位为度。Yaw 上下限在 −180…180 内；min > max 表示跨接缝，−180…180 表示完整一圈。Pitch 在 −90…90、FOV 在 1…179 内，均要求 min ≤ max。相等时锁定该轴。场景逐轴覆盖播放器设置；未配置的轴继承播放器，FOV 最后回退到原有 `minFov` / `maxFov`（默认 30 / 100）。范围限制相机中心，覆盖鼠标、触摸、键盘、惯性、自动旋转、陀螺仪及视角导航 API，不保证整个可见画面不超界。显式配置的轴即使启用 `bouncingLimits` 也使用硬边界。Yaw 动画沿允许区间插值，不走穿过禁区的最短路径；沉浸式 WebXR 继续由头显控制姿态。
+
+新场景接管画面时先应用范围，再设置初始视角。实时修改会取消导航与惯性、收回越界视角，不修改保存的初始视角或重新加载纹理。移除场景范围时恢复播放器设置。
+
+### 热点交互事件与自定义动作
+
+`events` 为 `click`、`pointerenter`、`pointerleave` 分别绑定一个动作。三个事件均支持 `scene`、`view`、`popup` 和 `{ type: "custom", actionId, params? }`。`params` 是 JSON 对象；函数、凭据、API 实现和表单定义由宿主维护。参数内的字符串不作为素材解析或打包。
+
+```json
+{"events":{"click":{"type":"scene","sceneId":"hall"},"pointerenter":{"type":"custom","actionId":"product.preview","params":{"visible":true}},"pointerleave":{"type":"custom","actionId":"product.preview","params":{"visible":false}}}}
+```
+
+旧 `action` 继续作为点击动作的后备，`events.click` 优先；编辑或清除点击时移除旧字段。打开项目不自动迁移。新事件配置需要升级后的播放器，项目 schemaVersion 仍为 1。没有点击动作的媒体继续切换播放，悬停没有默认动作。
+
+`ProjectScenes.onHotspotEvent(event)` 提供 `trigger`、`sceneId`、`hotspot`、`interaction` 和 `preventDefault()`。点击时先调用它，再调用原有 `onHotspotClick`，任一回调均可取消动作。`onCustomAction(event)` 额外提供 `action`，支持返回 Promise。宿主按稳定的 `action.actionId` 分发，校验业务参数，对未知动作抛出错误。缺少执行器、同步异常和 Promise 拒绝进入附带 `trigger` 的 `onHotspotError`。请求、鉴权、取消、防重复和迟到响应由宿主负责；各事件独立分发，不自动重试。
+
+悬停按整个热点的边界触发一次，跳过触屏和键盘焦点，并遵循可见性、指针交互设置。切换场景、隐藏和卸载仅清理状态，不执行离开动作。原有 tooltip 行为独立保留。自定义渲染器需同时转发 `context.onHoverChange(hovered, interaction)` 和 `context.onClick`；调用 `context.renderDefault()` 会自动接线。

package/dist/data.cjs

@@ -21,10 +21,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var data_exports = {};
 __export(data_exports, {
   PanoDataError: () => PanoDataError,
+  hotspotAction: () => hotspotAction,
   loadPanoProject: () => loadPanoProject,
   loadSceneFromJson: () => loadSceneFromJson,
   parsePanoProject: () => parsePanoProject,
-  sceneFromViewerConfig: () => sceneFromViewerConfig
+  projectHotspotTriggers: () => projectHotspotTriggers,
+  resolveProjectHotspotAssets: () => resolveHotspotAssets,
+  resolveProjectPopupAssets: () => resolveProjectPopupAssets,
+  sceneFromViewerConfig: () => sceneFromViewerConfig,
+  setHotspotAction: () => setHotspotAction
 });
 module.exports = __toCommonJS(data_exports);
 
@@ -301,7 +306,152 @@ async function loadSceneFromJson(url, options) {
   });
 }
 
+// src/view-limits.ts
+function parseViewLimits(value) {
+  if (value === void 0) return void 0;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("viewLimits: expected an object");
+  const result = {};
+  for (const axis of ["yaw", "pitch", "fov"]) {
+    const input = value[axis];
+    if (input === void 0) continue;
+    if (!input || typeof input !== "object" || Array.isArray(input))
+      throw new Error(`viewLimits.${axis}: expected min and max`);
+    const { min, max } = input;
+    const lower = axis === "yaw" ? -180 : axis === "pitch" ? -90 : 1;
+    const upper = axis === "yaw" ? 180 : axis === "pitch" ? 90 : 179;
+    if (typeof min !== "number" || typeof max !== "number" || !Number.isFinite(min) || !Number.isFinite(max) || min < lower || min > upper || max < lower || max > upper)
+      throw new Error(`viewLimits.${axis}: expected finite min and max from ${lower} to ${upper}`);
+    if (axis !== "yaw" && min > max)
+      throw new Error(`viewLimits.${axis}: min must not exceed max`);
+    result[axis] = { min, max };
+  }
+  return result;
+}
+
+// src/data/popups.ts
+function parsePopups(value, draft = false) {
+  if (value === void 0) return void 0;
+  try {
+    if (!Array.isArray(value)) throw new Error("popups: expected an array");
+    const ids = /* @__PURE__ */ new Set();
+    const string = (input, field, allowEmpty = false) => {
+      if (typeof input !== "string" || !allowEmpty && !input.trim())
+        throw new Error(`${field}: expected a ${allowEmpty ? "string" : "nonempty string"}`);
+      return input;
+    };
+    return value.map((entry, index) => {
+      const field = `popups[${index}]`;
+      if (!isRecord(entry)) throw new Error(`${field}: expected an object`);
+      const id = requiredString(entry.id, `${field}.id`);
+      if (ids.has(id)) throw new Error(`${field}.id: duplicate popup ID`);
+      ids.add(id);
+      const title = string(entry.title, `${field}.title`, draft);
+      if (!Array.isArray(entry.blocks)) throw new Error(`${field}.blocks: expected an array`);
+      const blockIds = /* @__PURE__ */ new Set();
+      const blocks = entry.blocks.map((block, i) => {
+        const path = `${field}.blocks[${i}]`;
+        if (!isRecord(block)) throw new Error(`${path}: expected an object`);
+        const id2 = requiredString(block.id, `${path}.id`);
+        if (blockIds.has(id2)) throw new Error(`${path}.id: duplicate block ID`);
+        blockIds.add(id2);
+        if (block.type === "text") return { id: id2, type: "text", text: string(block.text, `${path}.text`, true) };
+        const src = string(block.src, `${path}.src`, draft);
+        if (src) resolveResource("https://popup.invalid/", src);
+        if (block.type === "image") return {
+          id: id2,
+          type: "image",
+          src,
+          ...block.alt === void 0 ? {} : { alt: string(block.alt, `${path}.alt`, true) }
+        };
+        if (block.type === "audio") return { id: id2, type: "audio", src };
+        if (block.type === "video") {
+          const poster = block.poster === void 0 ? void 0 : string(block.poster, `${path}.poster`, true);
+          if (poster) resolveResource("https://popup.invalid/", poster);
+          return { id: id2, type: "video", src, ...poster ? { poster } : {} };
+        }
+        throw new Error(`${path}.type: unsupported content block`);
+      });
+      return { id, title, blocks };
+    });
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : "Invalid popup content";
+    throw new PanoDataError("INVALID_PROJECT", message, { field: message.split(":")[0], cause });
+  }
+}
+function resolveProjectPopupAssets(popup, baseUrl, resolver) {
+  return { ...popup, blocks: popup.blocks.map((block) => {
+    if (block.type === "text") return { ...block };
+    const resolve = (path, field) => {
+      if (!path) throw new PanoDataError("INVALID_PROJECT", `${popup.id}/${block.id}.${field}: choose a resource`);
+      const context = { defaultUrl: resolveResource(baseUrl, path), popupId: popup.id, blockId: block.id, field };
+      const result = resolver ? resolver(path, context) : context.defaultUrl;
+      if (typeof result !== "string" || !result.startsWith("/") && !/^(https?:|blob:|data:)/i.test(result))
+        throw new PanoDataError("INVALID_CONFIG", "resolvePopupAssetUrl must return an absolute URL or a site-root path");
+      return result;
+    };
+    return { ...block, src: resolve(block.src, "src"), ...block.type === "video" && block.poster ? { poster: resolve(block.poster, "poster") } : {} };
+  }) };
+}
+
+// ../../shared/cursor-assets.ts
+function mapCursorAssets(cursor, resolve) {
+  return cursor.replace(
+    /url\(\s*(?:"((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)'|((?:\\.|[^)\\])*?))\s*\)/gi,
+    (_match, double, single, bare) => {
+      const path = (double ?? single ?? bare ?? "").replace(
+        /\\([\da-f]{1,6}\s?|.)/gi,
+        (_escape, value) => /^[\da-f]/i.test(value) ? String.fromCodePoint(
+          Math.min(parseInt(value.trim(), 16), 1114111)
+        ) : value
+      );
+      return `url(${JSON.stringify(resolve(path))})`;
+    }
+  );
+}
+
 // src/data/hotspots.ts
+var projectHotspotTriggers = ["click", "pointerenter", "pointerleave"];
+function hotspotAction(hotspot, trigger) {
+  return hotspot.events?.[trigger] ?? (trigger === "click" ? hotspot.action : void 0);
+}
+function setHotspotAction(hotspot, trigger, action) {
+  const events = { ...hotspot.events };
+  const next = { ...hotspot, events };
+  if (trigger === "click") delete next.action;
+  if (action) events[trigger] = action;
+  else delete events[trigger];
+  if (!Object.keys(events).length) delete next.events;
+  return next;
+}
+function jsonValue(value, seen = /* @__PURE__ */ new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value !== "object" || !value || seen.has(value)) throw new Error("params: expected JSON data");
+  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new Error("params: expected JSON data");
+  seen.add(value);
+  const result = Array.isArray(value) ? value.map((item) => jsonValue(item, seen)) : Object.fromEntries(Object.entries(value).map(([key, item]) => [key, jsonValue(item, seen)]));
+  seen.delete(value);
+  return result;
+}
+function parseAction(action) {
+  if (!isRecord(action)) throw new Error("action: expected an object");
+  if (action.type === "scene") return { type: "scene", sceneId: requiredString(action.sceneId, "action.sceneId") };
+  if (action.type === "popup") return { type: "popup", popupId: requiredString(action.popupId, "action.popupId") };
+  if (action.type === "custom") {
+    if (action.params !== void 0 && (!isRecord(action.params) || Array.isArray(action.params))) throw new Error("action.params: expected an object");
+    return { type: "custom", actionId: requiredString(action.actionId, "action.actionId"), ...action.params === void 0 ? {} : { params: jsonValue(action.params) } };
+  }
+  if (action.type === "view") {
+    const position = parsePosition(action.view, "action.view");
+    const fov = finite(action.view.fov, "action.view.fov");
+    if (fov <= 0 || fov >= 180) throw new Error("action.view.fov: expected 0 < fov < 180");
+    const duration = action.duration === void 0 ? void 0 : finite(action.duration, "action.duration");
+    if (duration !== void 0 && duration < 0) throw new Error("action.duration: expected a nonnegative number");
+    return { type: "view", view: { ...position, fov }, ...duration === void 0 ? {} : { duration } };
+  }
+  throw new Error("action.type: unsupported action");
+}
 var common = [
   "label",
   "visible",
@@ -344,6 +494,7 @@ var fields = {
   ],
   audio: [
     "src",
+    "format",
     "playing",
     "loop",
     "muted",
@@ -612,9 +763,10 @@ function parseHotspot(value, sceneId, field) {
         result[key] = n;
       } else if (key === "fontWeight" && typeof item === "number")
         result[key] = finite(item, key);
-      else if (key === "src" && kind === "audio" && Array.isArray(item)) {
-        if (!item.length) throw new Error("src: expected audio sources");
-        result[key] = item.map((src, i) => requiredString(src, `src[${i}]`));
+      else if ((key === "src" || key === "format") && kind === "audio" && Array.isArray(item)) {
+        if (!item.length)
+          throw new Error(`${key}: expected audio ${key === "src" ? "sources" : "formats"}`);
+        result[key] = item.map((entry, i) => requiredString(entry, `${key}[${i}]`));
       } else {
         if (typeof item !== "string")
           throw new Error(`${key}: expected a string`);
@@ -633,13 +785,19 @@ function parseHotspot(value, sceneId, field) {
       throw new Error("text: required");
     if (kind === "sequence" && !result.frameCount)
       throw new Error("frameCount: required");
-    if (value.action !== void 0) {
-      if (!isRecord(value.action) || value.action.type !== "scene")
-        throw new Error("action: expected a scene action");
-      result.action = {
-        type: "scene",
-        sceneId: requiredString(value.action.sceneId, "action.sceneId")
-      };
+    if (value.action !== void 0) result.action = parseAction(value.action);
+    if (value.events !== void 0) {
+      if (!isRecord(value.events)) throw new Error("events: expected an object");
+      const events = {};
+      for (const key of Object.keys(value.events)) {
+        if (!projectHotspotTriggers.includes(key)) throw new Error(`events.${key}: unsupported trigger`);
+        try {
+          events[key] = parseAction(value.events[key]);
+        } catch (error) {
+          throw new Error(`events.${key}.${error instanceof Error ? error.message : "invalid action"}`);
+        }
+      }
+      result.events = events;
     }
     return result;
   } catch (cause) {
@@ -663,6 +821,11 @@ function resolveHotspotAssets(hotspot, baseUrl, sceneId, resolver) {
     resolver
   ) : path;
   const result = { ...hotspot };
+  if (result.cursor) result.cursor = mapCursorAssets(result.cursor, resolve);
+  if (result.tooltipAppearance?.background) result.tooltipAppearance = {
+    ...result.tooltipAppearance,
+    background: mapCursorAssets(result.tooltipAppearance.background, resolve)
+  };
   if ("src" in result)
     result.src = Array.isArray(result.src) ? result.src.map(resolve) : resolve(result.src);
   if ("poster" in result && result.poster)
@@ -685,7 +848,7 @@ function resolveHotspotAssets(hotspot, baseUrl, sceneId, resolver) {
 function optionalString(record, key) {
   return record[key] === void 0 ? void 0 : requiredString(record[key], key);
 }
-function parsePanoProject(value) {
+function parsePanoProject(value, options = {}) {
   if (!isRecord(value))
     throw new PanoDataError("INVALID_PROJECT", "Expected a project object");
   if (value.schemaVersion !== 1)
@@ -695,7 +858,8 @@ function parsePanoProject(value) {
       { field: "schemaVersion" }
     );
   try {
-    if (!Array.isArray(value.scenes) || !value.scenes.length)
+    const popups = parsePopups(value.popups, options.draft);
+    if (!Array.isArray(value.scenes) || !options.draft && !value.scenes.length)
       throw new Error("scenes: expected a nonempty array");
     const ids = /* @__PURE__ */ new Set();
     const scenes = value.scenes.map(
@@ -719,6 +883,7 @@ function parsePanoProject(value) {
             viewerUrl: requiredString(src.viewerUrl, "source.viewerUrl"),
             baseUrl
           } : { viewerConfig: parseConfig(src.viewerConfig), baseUrl };
+          const viewLimits = parseViewLimits(entry.viewLimits);
           let initialView;
           if (entry.initialView !== void 0) {
             if (!isRecord(entry.initialView))
@@ -756,6 +921,7 @@ function parsePanoProject(value) {
             title: optionalString(entry, "title"),
             source,
             initialView,
+            ...viewLimits === void 0 ? {} : { viewLimits },
             hotspots
           };
         } catch (cause) {
@@ -773,8 +939,8 @@ function parsePanoProject(value) {
         }
       }
     );
-    const initialSceneId = optionalString(value, "initialSceneId") ?? scenes[0].id;
-    if (!ids.has(initialSceneId))
+    const initialSceneId = optionalString(value, "initialSceneId") ?? scenes[0]?.id;
+    if (initialSceneId !== void 0 && !ids.has(initialSceneId))
       throw new PanoDataError(
         "INVALID_REFERENCE",
         "initialSceneId: scene does not exist",
@@ -782,22 +948,31 @@ function parsePanoProject(value) {
       );
     for (const [index, scene] of scenes.entries()) {
       for (const [i, hotspot] of (scene.hotspots ?? []).entries()) {
-        if (hotspot.action && !ids.has(hotspot.action.sceneId))
-          throw new PanoDataError(
-            "INVALID_REFERENCE",
-            "Hotspot target scene does not exist",
-            {
+        for (const trigger of projectHotspotTriggers) {
+          const action = hotspotAction(hotspot, trigger);
+          if (action?.type === "popup" && !popups?.some((popup) => popup.id === action.popupId))
+            throw new PanoDataError("INVALID_REFERENCE", "Hotspot target popup does not exist", {
               sceneId: scene.id,
-              field: `scenes[${index}].hotspots[${i}].action.sceneId`
-            }
-          );
+              field: `scenes[${index}].hotspots[${i}].${hotspot.events?.[trigger] ? `events.${trigger}` : "action"}.popupId`
+            });
+          if (action?.type === "scene" && !ids.has(action.sceneId))
+            throw new PanoDataError(
+              "INVALID_REFERENCE",
+              "Hotspot target scene does not exist",
+              {
+                sceneId: scene.id,
+                field: `scenes[${index}].hotspots[${i}].${hotspot.events?.[trigger] ? `events.${trigger}` : "action"}.sceneId`
+              }
+            );
+        }
       }
     }
     return {
       schemaVersion: 1,
       title: optionalString(value, "title"),
       initialSceneId,
-      scenes
+      scenes,
+      ...popups === void 0 ? {} : { popups }
     };
   } catch (cause) {
     if (cause instanceof PanoDataError) throw cause;
@@ -858,6 +1033,7 @@ async function loadPanoProject(source, options = {}) {
           baseUrl: sourceBase ?? root
         });
         aborted(controller.signal);
+        if (item.viewLimits !== void 0) scene.viewLimits = item.viewLimits;
         scenes[index] = {
           scene,
           title: item.title,
@@ -894,7 +1070,8 @@ async function loadPanoProject(source, options = {}) {
     return {
       title: definition.title,
       initialSceneId: definition.initialSceneId,
-      scenes
+      scenes,
+      ...definition.popups === void 0 ? {} : { popups: definition.popups.map((popup) => resolveProjectPopupAssets(popup, root, options.resolvePopupAssetUrl)) }
     };
   } finally {
     signal?.removeEventListener("abort", cancel);