@realsee/vr-cli 0.1.3

package/skills/realsee-vr-app/references/dnalogel-openapi-recipes.md

@@ -0,0 +1,818 @@
+# dnalogel OpenAPI-to-SDK implementation recipes
+
+External projects do not have the dnalogel or Five source repositories. This reference is self-contained: turn the user's product prompt into a server-side OpenAPI adapter and a browser-side Five/dnalogel feature without asking the developer to clone an SDK repository or locate a repository example.
+
+The generated manifest declares minimums `@realsee/dnalogel>=3.81.2` and `@realsee/five>=6.8.9`; its initial lockfile resolves the reviewed baseline versions. Confirm imports and calls against the target project's actual lockfile, installed `package.json`, `libs/index.d.ts`, and selected plugin declaration. The installed declaration wins when a project intentionally upgrades. Do not use TypeScript `paths` to bypass the package boundary.
+
+## Prompt-to-capability routing
+
+| User prompt or intent                                 | Authoritative source                                               | Browser implementation                                                                             | Required readiness                                                         |
+| ----------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| 热点、标签、图文点、视频点、音频点、VR 跳转、空间锚点 | `GET /open/v3/hot/list`                                            | parsed shared DTO -> sized media variants -> exact PanoTag `Tags` -> `PanoTagPlugin`               | Five Work loaded; model readiness only for model-dependent content/anchors |
+| 导览点、讲解点、预设视角、房间漫游点                  | `GET /open/v3/observerpicture/search`                              | validated records -> Five `Partial<State>` snapshots plus sized preview images                     | Work loaded and pano index present in `five.observers`                     |
+| 模型框选、模型区域、模型标注                          | `GET /open/v3/annotation/search`                                   | validated `{ list }` -> `ModelMakerPlugin`                                                         | model-capable Work; cancellable model readiness gate                       |
+| 路线、引导线、自动漫游、点位巡游、模型曲线移动        | `GET /open/v3/route/search`                                        | `GuideLinePlugin` rendering plus shape-selected `CruisePlugin` or `MovePlugin` playback            | branch-specific; see route recipe                                          |
+| 平面图、户型图                                        | `GET /open/v3/floorplan/plugins`, then `data.format_floorplan_url` | validated wrapper -> `ModelFloorplanPlugin`                                                        | Work/model and mounted plugin container                                    |
+| 点击模型选点、坐标拾取、可见性判断                    | no default persistence API                                         | Five-lifetime `PanoCursorRaycasterPlugin`; runtime-only unless an editor/API contract is supplied  | model loaded                                                               |
+| 虚拟屏、电视视频、空间 DOM、全景视频                  | data contract selected by behavior                                 | `ModelTVVideoPlugin`, PanoTag `MediaPlane`/`MediaModel`, `CSS3DRenderPlugin`, or `PanoVideoPlugin` | plugin-specific; media must be Work/API/user authorized                    |
+
+Do not route by a vague noun alone. Classify content, renderer, anchor, playback behavior, readiness, and persistence owner before selecting a capability. A screenshot or a field named `tags` is not an API contract.
+
+## Mandatory implementation sequence
+
+For every OpenAPI-backed prompt, perform these steps in order:
+
+1. **Resolve intent:** select one row in the routing table and state why it matches.
+2. **Define a browser-safe contract:** add a narrow JSON-safe capability DTO under `shared/`; do not expose the upstream envelope or SDK runtime objects.
+3. **Fetch server-side:** add the authenticated OpenAPI call in `server/realsee-open-api.ts`, reusing token cache, timeout, retry, and `code === 0` checks.
+4. **Parse and adapt:** treat upstream JSON as `unknown`; use a runtime parser with indexed field diagnostics; return only the shared discriminated DTO.
+5. **Expose through the BFF:** extend the service/envelope or add a same-origin `/api/...` route. Keep AK/SK and access tokens server-only.
+6. **Derive sized image variants:** every image URL that reaches a plugin or the DOM goes through the reviewed transform with a bounded size. Passing the upstream original is a defect, not a default.
+7. **Convert at the browser boundary:** exhaustively convert the DTO to the exact installed SDK type. Do not use a final `as Tags[...]` escape hatch.
+8. **Implement one focused feature:** create the plugin from the active native Five instance, serialize loads, and retain each hook/helper owner.
+9. **Clean up by ownership:** abort and invalidate first. An unregistered candidate is disposed directly; a registered instance is disposed by identity-safe `plugins.unregister(name, expected)` exactly once after pending work settles.
+10. **Isolate failure:** an API/schema/plugin failure disables that feature only; the base Viewer remains usable.
+11. **Validate:** run typecheck, lint, format check, build, verifier, the pinned declaration contract fixture, and a real browser scenario.
+
+## BFF extension pattern
+
+The generated `RealseeOpenApiClient` already owns access-token exchange, timeout, one authentication retry, and success-envelope checks. Add feature methods inside that class so they reuse `#requestAuthenticated`; never create a browser token flow.
+
+Use small unknown narrowers in the server adapter:
+
+```ts
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value && typeof value === "object" && !Array.isArray(value));
+
+const requireRecord = (value: unknown, label: string) => {
+  if (!isRecord(value)) throw new RealseeOpenApiError(`${label} 必须是对象。`);
+  return value;
+};
+
+const requireArray = (value: unknown, label: string): unknown[] => {
+  if (!Array.isArray(value)) {
+    throw new RealseeOpenApiError(`${label} 必须是数组。`);
+  }
+  return value;
+};
+```
+
+The authenticated call pattern is:
+
+```ts
+const query = new URLSearchParams({ resource_code: resourceCode });
+const payload = await this.#requestAuthenticated(
+  `/open/v3/hot/list?${query.toString()}`,
+  "获取空间热点",
+  signal,
+);
+const data = requireRecord(payload.data, "热点 data");
+```
+
+Never return `payload` directly. Validate required fields, remove unreviewed metadata, normalize nullable optional fields, and return only the browser capability. Fetch optional capabilities independently; log a server-side diagnostic and omit only the failed capability rather than failing the base Work request.
+
+## Recipe: tags, hotspots, and anchors
+
+### Shared discriminated DTO
+
+Do not put `RawRecord[]` in `WorkCapabilities`. Use a shared discriminated DTO that is serializable and narrower than PanoTag's runtime type. This starter contract covers common OpenAPI hotspot prompts and every anchor shape; add a content variant only together with its parser and converter arm.
+
+```ts
+// shared/pano-tag-capability.ts
+export type Vec3Dto = readonly [number, number, number];
+export type MediaItemDto =
+  | {
+      readonly type: "Image";
+      readonly url: string;
+      readonly thumbnail?: string;
+    }
+  | {
+      readonly type: "Video";
+      readonly url: string;
+      readonly videoCoverUrl?: string;
+    };
+
+export type PanoTagAnchorDto =
+  | { readonly stickType: "2DPoint"; readonly position: Vec3Dto }
+  | {
+      readonly stickType: "3DPoint";
+      readonly position: Vec3Dto;
+      readonly normal: Vec3Dto;
+    }
+  | {
+      readonly stickType: "Plane";
+      readonly position: readonly [Vec3Dto, Vec3Dto, Vec3Dto, Vec3Dto];
+    }
+  | {
+      readonly stickType: "Model";
+      readonly position: Vec3Dto;
+      readonly matrix: readonly number[];
+    }
+  | {
+      readonly stickType: "3DBox";
+      readonly position: {
+        readonly start: Vec3Dto;
+        readonly end: Vec3Dto;
+        readonly rotation: Vec3Dto;
+      };
+    }
+  | {
+      readonly stickType: "Polygon";
+      readonly position: readonly [Vec3Dto, Vec3Dto, Vec3Dto, ...Vec3Dto[]];
+    }
+  | {
+      readonly stickType: "Mask";
+      readonly position: Vec3Dto;
+      readonly mask: string;
+      readonly color: string | number | readonly [number, number, number];
+    };
+
+export type PanoTagContentDto =
+  | {
+      readonly contentType: "Text";
+      readonly data: { readonly title?: string; readonly description?: string };
+    }
+  | {
+      readonly contentType: "Audio";
+      readonly data: { readonly title?: string; readonly audioUrl: string };
+    }
+  | {
+      readonly contentType: "ImageText" | "Image" | "Video" | "Panorama";
+      readonly data: {
+        readonly title?: string;
+        readonly mediaData: readonly MediaItemDto[];
+      };
+    }
+  | {
+      readonly contentType: "Link" | "VRLink" | "Sticker" | "PanoLink";
+      readonly data: { readonly title?: string };
+    }
+  | {
+      readonly contentType: "Model";
+      readonly data: { readonly modelUrl: string };
+    };
+
+export type PanoTagDto = {
+  readonly id?: string | number;
+  readonly enabled?: boolean;
+} & PanoTagAnchorDto &
+  PanoTagContentDto;
+
+export interface PanoTagCapabilityDto {
+  readonly version?: string;
+  readonly tagList: readonly PanoTagDto[];
+}
+```
+
+The starter intentionally omits `globalConfig` and `contentTypeConfig`: the installed SDK config allows callbacks, DOM values, and Three objects that are not a safe BFF contract. Add an explicit JSON-safe whitelist DTO only when the product needs a specific config field. Canonical 3.81.2 content types not shown above (`Marketing`, `MediaPlane`, `MediaModel`, `Custom`, and `Unknown`) must be rejected until a product-specific serializable schema, parser arm, and converter arm are supplied. Never accept arbitrary `Custom`/`Unknown` objects by default.
+
+### Runtime parser
+
+Parse `GET /open/v3/hot/list` as `unknown`. The parser must switch on both `stickType` and `contentType`; validate finite coordinates, exact plane length, polygon minimum length, model matrix convention, 3D normal, media URLs, and required content fields. Keep the indexed path in every error.
+
+```ts
+const requireString = (value: unknown, path: string) => {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new RealseeOpenApiError(`${path} 必须是非空字符串。`);
+  }
+  return value;
+};
+
+const optionalString = (
+  record: Record<string, unknown>,
+  key: string,
+  path: string,
+) => {
+  const value = record[key];
+  return value === undefined
+    ? undefined
+    : requireString(value, `${path}.${key}`);
+};
+
+const requireFinite = (value: unknown, path: string) => {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new RealseeOpenApiError(`${path} 必须是有限数字。`);
+  }
+  return value;
+};
+
+const parseVec3 = (value: unknown, path: string): Vec3Dto => {
+  if (!Array.isArray(value) || value.length !== 3) {
+    throw new RealseeOpenApiError(`${path} 必须是三个坐标。`);
+  }
+  return [
+    requireFinite(value[0], `${path}[0]`),
+    requireFinite(value[1], `${path}[1]`),
+    requireFinite(value[2], `${path}[2]`),
+  ];
+};
+
+const parseColor = (
+  value: unknown,
+  path: string,
+): string | number | readonly [number, number, number] => {
+  if (typeof value === "string") return requireString(value, path);
+  if (typeof value === "number") return requireFinite(value, path);
+  return parseVec3(value, path);
+};
+
+const parseMediaItem = (value: unknown, path: string): MediaItemDto => {
+  const media = requireRecord(value, path);
+  switch (media.type) {
+    case "Image": {
+      const thumbnail = optionalString(media, "thumbnail", path);
+      return {
+        type: "Image",
+        url: requireString(media.url, `${path}.url`),
+        ...(thumbnail ? { thumbnail } : {}),
+      };
+    }
+    case "Video": {
+      const videoCoverUrl = optionalString(media, "videoCoverUrl", path);
+      return {
+        type: "Video",
+        url: requireString(media.url, `${path}.url`),
+        ...(videoCoverUrl ? { videoCoverUrl } : {}),
+      };
+    }
+    default:
+      throw new RealseeOpenApiError(`${path}.type 必须是 Image 或 Video。`);
+  }
+};
+
+const parseAnchor = (
+  record: Record<string, unknown>,
+  path: string,
+): PanoTagAnchorDto => {
+  switch (record.stickType) {
+    case "2DPoint":
+      return {
+        stickType: "2DPoint",
+        position: parseVec3(record.position, `${path}.position`),
+      };
+    case "3DPoint":
+      return {
+        stickType: "3DPoint",
+        position: parseVec3(record.position, `${path}.position`),
+        normal: parseVec3(record.normal, `${path}.normal`),
+      };
+    case "Plane": {
+      const points = requireArray(record.position, `${path}.position`);
+      if (points.length !== 4) {
+        throw new RealseeOpenApiError(`${path}.position 必须恰好有四个点。`);
+      }
+      return {
+        stickType: "Plane",
+        position: [
+          parseVec3(points[0], `${path}.position[0]`),
+          parseVec3(points[1], `${path}.position[1]`),
+          parseVec3(points[2], `${path}.position[2]`),
+          parseVec3(points[3], `${path}.position[3]`),
+        ],
+      };
+    }
+    case "Model": {
+      const matrix = requireArray(record.matrix, `${path}.matrix`).map(
+        (item, index) => requireFinite(item, `${path}.matrix[${index}]`),
+      );
+      if (matrix.length !== 16) {
+        throw new RealseeOpenApiError(`${path}.matrix 必须是 4x4 矩阵。`);
+      }
+      return {
+        stickType: "Model",
+        position: parseVec3(record.position, `${path}.position`),
+        matrix,
+      };
+    }
+    case "3DBox": {
+      const position = requireRecord(record.position, `${path}.position`);
+      return {
+        stickType: "3DBox",
+        position: {
+          start: parseVec3(position.start, `${path}.position.start`),
+          end: parseVec3(position.end, `${path}.position.end`),
+          rotation: parseVec3(position.rotation, `${path}.position.rotation`),
+        },
+      };
+    }
+    case "Polygon": {
+      const points = requireArray(record.position, `${path}.position`);
+      if (points.length < 3) {
+        throw new RealseeOpenApiError(`${path}.position 至少需要三个点。`);
+      }
+      return {
+        stickType: "Polygon",
+        position: [
+          parseVec3(points[0], `${path}.position[0]`),
+          parseVec3(points[1], `${path}.position[1]`),
+          parseVec3(points[2], `${path}.position[2]`),
+          ...points
+            .slice(3)
+            .map((point, index) =>
+              parseVec3(point, `${path}.position[${index + 3}]`),
+            ),
+        ],
+      };
+    }
+    case "Mask":
+      return {
+        stickType: "Mask",
+        position: parseVec3(record.position, `${path}.position`),
+        mask: requireString(record.mask, `${path}.mask`),
+        color: parseColor(record.color, `${path}.color`),
+      };
+    default:
+      throw new RealseeOpenApiError(
+        `${path}.stickType 不受当前 capability 支持。`,
+      );
+  }
+};
+
+const parseContent = (
+  record: Record<string, unknown>,
+  path: string,
+): PanoTagContentDto => {
+  const data = requireRecord(record.data, `${path}.data`);
+  const title = optionalString(data, "title", `${path}.data`);
+  switch (record.contentType) {
+    case "Text": {
+      const description = optionalString(data, "description", `${path}.data`);
+      return {
+        contentType: "Text",
+        data: {
+          ...(title ? { title } : {}),
+          ...(description ? { description } : {}),
+        },
+      };
+    }
+    case "Audio":
+      return {
+        contentType: "Audio",
+        data: {
+          ...(title ? { title } : {}),
+          audioUrl: requireString(data.audioUrl, `${path}.data.audioUrl`),
+        },
+      };
+    case "ImageText":
+    case "Image":
+    case "Video":
+    case "Panorama": {
+      const mediaData = requireArray(data.mediaData, `${path}.data.mediaData`);
+      if (mediaData.length === 0) {
+        throw new RealseeOpenApiError(`${path}.data.mediaData 不得为空。`);
+      }
+      return {
+        contentType: record.contentType,
+        data: {
+          ...(title ? { title } : {}),
+          mediaData: mediaData.map((item, index) =>
+            parseMediaItem(item, `${path}.data.mediaData[${index}]`),
+          ),
+        },
+      };
+    }
+    case "Link":
+    case "VRLink":
+    case "Sticker":
+    case "PanoLink":
+      return {
+        contentType: record.contentType,
+        data: { ...(title ? { title } : {}) },
+      };
+    case "Model":
+      return {
+        contentType: "Model",
+        data: {
+          modelUrl: requireString(data.modelUrl, `${path}.data.modelUrl`),
+        },
+      };
+    default:
+      throw new RealseeOpenApiError(
+        `${path}.contentType 不受当前 capability 支持。`,
+      );
+  }
+};
+
+const parsePanoTag = (value: unknown, index: number): PanoTagDto => {
+  const path = `热点 tagList[${index}]`;
+  const record = requireRecord(value, path);
+  const id = record.id;
+  if (id !== undefined && typeof id !== "string" && typeof id !== "number") {
+    throw new RealseeOpenApiError(`${path}.id 必须是字符串或数字。`);
+  }
+  if (record.enabled !== undefined && typeof record.enabled !== "boolean") {
+    throw new RealseeOpenApiError(`${path}.enabled 必须是布尔值。`);
+  }
+  return {
+    ...(id !== undefined ? { id } : {}),
+    ...(record.enabled !== undefined ? { enabled: record.enabled } : {}),
+    ...parseAnchor(record, path),
+    ...parseContent(record, path),
+  };
+};
+```
+
+The parser above implements every discriminator in the starter DTO and rejects all others rather than passing them through. Return `{ version?, tagList: data.tagList.map(parsePanoTag) }` only after the complete array parses. Validate optional `version` as a non-empty string when present.
+
+### Exhaustive browser conversion and feature ownership
+
+Convert readonly DTO arrays into mutable SDK arrays and declare the converter's return type as `Tags`; do not cast at the final boundary:
+
+```ts
+import {
+  PanoTagPlugin,
+  type PanoTagPluginExportInterface,
+  type Tags,
+} from "@realsee/dnalogel/libs/PanoTagPlugin";
+
+const cloneVec3 = (value: Vec3Dto): [number, number, number] => [
+  value[0],
+  value[1],
+  value[2],
+];
+
+const toSdkAnchor = (tag: PanoTagAnchorDto) => {
+  switch (tag.stickType) {
+    case "2DPoint":
+      return {
+        stickType: "2DPoint" as const,
+        position: cloneVec3(tag.position),
+      };
+    case "3DPoint":
+      return {
+        stickType: "3DPoint" as const,
+        position: cloneVec3(tag.position),
+        normal: cloneVec3(tag.normal),
+      };
+    case "Plane":
+      return {
+        stickType: "Plane" as const,
+        position: [
+          cloneVec3(tag.position[0]),
+          cloneVec3(tag.position[1]),
+          cloneVec3(tag.position[2]),
+          cloneVec3(tag.position[3]),
+        ] as [
+          [number, number, number],
+          [number, number, number],
+          [number, number, number],
+          [number, number, number],
+        ],
+      };
+    case "Model":
+      return {
+        stickType: "Model" as const,
+        position: cloneVec3(tag.position),
+        matrix: [...tag.matrix],
+      };
+    case "3DBox":
+      return {
+        stickType: "3DBox" as const,
+        position: {
+          start: cloneVec3(tag.position.start),
+          end: cloneVec3(tag.position.end),
+          rotation: cloneVec3(tag.position.rotation),
+        },
+      };
+    case "Polygon":
+      return {
+        stickType: "Polygon" as const,
+        position: tag.position.map(cloneVec3),
+      };
+    case "Mask":
+      return {
+        stickType: "Mask" as const,
+        position: cloneVec3(tag.position),
+        mask: tag.mask,
+        color:
+          typeof tag.color === "string" || typeof tag.color === "number"
+            ? tag.color
+            : cloneVec3(tag.color),
+      };
+  }
+};
+
+const toSdkMedia = (media: MediaItemDto) =>
+  media.type === "Image"
+    ? {
+        type: "Image" as const,
+        url: media.url,
+        ...(media.thumbnail ? { thumbnail: media.thumbnail } : {}),
+      }
+    : {
+        type: "Video" as const,
+        url: media.url,
+        ...(media.videoCoverUrl ? { videoCoverUrl: media.videoCoverUrl } : {}),
+      };
+
+const toSdkContent = (tag: PanoTagContentDto) => {
+  switch (tag.contentType) {
+    case "Text":
+      return {
+        ...(tag.data.title ? { title: tag.data.title } : {}),
+        ...(tag.data.description ? { description: tag.data.description } : {}),
+      };
+    case "Audio":
+      return {
+        ...(tag.data.title ? { title: tag.data.title } : {}),
+        audioUrl: tag.data.audioUrl,
+      };
+    case "ImageText":
+    case "Image":
+    case "Video":
+    case "Panorama":
+      return {
+        ...(tag.data.title ? { title: tag.data.title } : {}),
+        mediaData: tag.data.mediaData.map(toSdkMedia),
+      };
+    case "Link":
+    case "VRLink":
+    case "Sticker":
+    case "PanoLink":
+      return { ...(tag.data.title ? { title: tag.data.title } : {}) };
+    case "Model":
+      return { modelUrl: tag.data.modelUrl };
+  }
+};
+
+const toSdkTag = (tag: PanoTagDto): Tags["tagList"][number] => ({
+  ...(tag.id !== undefined ? { id: tag.id } : {}),
+  ...(tag.enabled !== undefined ? { enabled: tag.enabled } : {}),
+  ...toSdkAnchor(tag),
+  contentType: tag.contentType,
+  data: toSdkContent(tag),
+});
+
+const toSdkTags = (capability: PanoTagCapabilityDto): Tags => ({
+  ...(capability.version ? { version: capability.version } : {}),
+  tagList: capability.tagList.map(toSdkTag),
+});
+
+const candidate = PanoTagPlugin(five, { containerZIndex: 2 });
+let plugin: PanoTagPluginExportInterface;
+try {
+  plugin = plugins.register("dnalogel.panoTag", candidate);
+} catch (error) {
+  candidate.dispose(); // candidate was never registered
+  throw error;
+}
+
+const loading = plugin.load(toSdkTags(capability));
+await loading;
+```
+
+Serialize loads and retain hook unsubscribe functions. On cleanup, invalidate/abort and remove hooks immediately; after the current `load` settles, call `plugins.unregister("dnalogel.panoTag", plugin)` once. `SpatialPluginRegistry.unregister` removes by identity and invokes the registered instance's `dispose`; do not call `plugin.dispose()` afterward. Ordinary point/plane tags may load after `five.load`; wait for model readiness only for model-dependent content or anchors.
+
+## Recipe: sized image variants for feature media
+
+OpenAPI records carry full-resolution originals. Loading those directly into tags, tour previews, cards or DOM thumbnails is the most common performance defect in a generated project, and it is not fixed by CSS sizing: the browser still downloads the original. Every feature above that carries an image must derive a variant. Read `.agents/skills/realsee-image-resources/SKILL.md` for provenance, host policy and CORS; this section is only the wiring into a feature.
+
+Five 6.8.9 exports exactly `defaultImageURLTransform`, `ImageURLOptions`, `ImageURLMappings`, `ImageOptions` and `TextureOptions` from the package root. The size helpers (`replaceImageSize`, `getImageSizeFromURL`) live under `five/utils/imageURL` and are **not** root exports, so do not import them from `@realsee/five`. Five's own `ai_guides/features/image-options.md` documents the transform and the `cut` option.
+
+`ImageURLOptions` requires `key` and optionally takes `size`, `quality` (0–100), `format`, `cut`, `sharpen` (unsupported overseas), `forceUseExifOrientation` and `mappings`. Wrap it once in an application-owned adapter that validates the host before and after transforming, then call that adapter from features:
+
+```ts
+// src/vr/five/imageURL.ts
+import { defaultImageURLTransform, type ImageURLOptions } from "@realsee/five";
+
+export function imageURLTransform(source: string, options: ImageURLOptions) {
+  assertApprovedRealseeImageURL(source);
+  const transformed = defaultImageURLTransform(source, {
+    ...options,
+    mappings: { ...REALSEE_IMAGE_URL_MAPPINGS, ...options.mappings },
+  });
+  assertApprovedRealseeImageURL(transformed);
+  return transformed;
+}
+
+export const featureThumbnailURL = (source: string, size: 256 | 512 | 1024) =>
+  imageURLTransform(source, {
+    key: "default",
+    size,
+    quality: 80,
+    format: "webp",
+  });
+```
+
+Apply it at the DTO-to-SDK conversion boundary, where the display context is known:
+
+```ts
+const toSdkMedia = (media: MediaItemDto) =>
+  media.type === "Image"
+    ? {
+        type: "Image" as const,
+        // Popover artwork does not need the original.
+        url: featureThumbnailURL(media.url, 1024),
+        // A list thumbnail needs far less; fall back to the same source when absent.
+        thumbnail: featureThumbnailURL(media.thumbnail ?? media.url, 256),
+      }
+    : {
+        type: "Video" as const,
+        url: media.url, // video streams are not image-transform targets
+        ...(media.videoCoverUrl
+          ? { videoCoverUrl: featureThumbnailURL(media.videoCoverUrl, 512) }
+          : {}),
+      };
+```
+
+Per-capability targets:
+
+- **PanoTag:** `Image`/`ImageText`/`Panorama` `mediaData[].url` and `thumbnail`, `Video` `videoCoverUrl`, `Marketing` `headerPictureUrl`, and any icon artwork in `style.point.url`.
+- **Tour points:** the preview image of each observer-picture record, sized for its DOM list, not the panorama itself.
+- **Cards, drawers and status chrome:** every DOM `Image`/`<img>` source in the Vapor layer.
+
+Choose the size from the rendered box and device pixel ratio, prefer powers of two, and keep one bounded set of sizes rather than per-call numbers.
+
+Do not transform these:
+
+- pano, tile, texture and model resources consumed by Five itself: configure `FiveInitArgs.imageOptions`/`textureOptions` so Five applies its own pipeline, and never rewrite those URLs inside a feature;
+- video and audio stream URLs;
+- URLs on a host that is not an approved Realsee image host — reject instead of rewriting the hostname.
+
+A transform changes a URL only. It does not grant CORS access, authorize a source, or prove the derived object exists; validate the final URL in a browser and keep an explicit fallback if a derived variant fails.
+
+## Recipe: tour points as Five State
+
+`GET /open/v3/observerpicture/search` is a Five State feature, not a dnalogel route controller. Validate `data.list`; for every item:
+
+- read pose values from nested `data.pano_index`, `data.longitude`, `data.latitude`, and `data.fov`;
+- if top-level `pano_index` exists, require it to agree;
+- require finite values and confirm the pano index belongs to `five.observers`;
+- set `mode: "Panorama"` and the active `workCode` explicitly;
+- treat `offset: null` as absent; reconstruct a Three `Vector3` only from three finite components.
+
+```ts
+const state: Partial<State> = {
+  workCode,
+  mode: "Panorama",
+  panoIndex,
+  longitude,
+  latitude,
+  fov,
+};
+five.setState(state);
+```
+
+`five.setState` returns `void`; do not await it. Use `state.synced` or `five.ready()` only when the product needs a completion gate. Invalidate the Work/generation token before aborting so a late response cannot apply State to another Work.
+
+## Recipe: model annotations
+
+`GET /open/v3/annotation/search` succeeds only with `code === 0` and array `data.list`. Validate each record's `object_data` discriminator:
+
+- `box`: finite start/end points;
+- `triangles`: finite triangle points;
+- `prism`: finite polygon points and finite height.
+
+Preserve only reviewed identity/label metadata and assign a stable non-zero id. If an upstream list is non-empty but no valid records remain, return a schema error rather than silently loading an empty plugin. Pass only:
+
+```ts
+await modelMaker.load({ list: validatedItems });
+```
+
+Do not start this feature for a panorama-only Work. Guard model readiness with an AbortSignal or generation token. For a registration failure dispose only the unregistered candidate. For a registered instance, disable/clear and remove hooks as declared, wait for pending load, then call identity-safe `plugins.unregister(name, modelMaker)` once; unregister performs disposal.
+
+## Recipe: routes, rendering, and playback
+
+`GET /open/v3/route/search` records may contain `pano_group`, `path`, panorama/model style configs, and floor visibility. Rendering and playback use separate SDK inputs.
+
+### Choose one playback semantic
+
+- **Pano-index route:** require at least two integer indexes and confirm every index exists in `five.observers`. Load `CruisePlugin` with exactly one branch: `{ panoIndexList }` or `{ keyframes }`.
+- **Model-space route:** require a supported path with at least two finite points. Load `MovePlugin` with `{ path }`.
+- **Rendering:** separately adapt selected geometry/style to `GuideLinePlugin.load({ lines })` or a validated pano route to `load({ routes })`.
+
+If a record contains both `pano_group` and `path`, choose product semantics explicitly; never merge both into one controller input.
+
+```ts
+await cruise.load({
+  panoIndexList,
+  moveType: "justMove",
+  moveToFirstPanoEffect: "montage",
+});
+
+await move.load({ path: points, useGuildLine: false });
+await guideLine.load({ lines: validatedLines });
+```
+
+Do not pass raw OpenAPI records, GuideLine `PathItem` arrays, or style objects to Cruise/Move. Do not invent `RoutePlugin`, `PanoRove`, `stop()`, or `cruise.clear()`. GuideLine waits for model readiness; Cruise needs Work/observers; Move enters Model and awaits Five readiness when playback starts.
+
+Cleanup order:
+
+1. invalidate the active Work/generation and abort the request;
+2. pause the owned Cruise/Move controller with the declared API;
+3. remove playback hooks and call GuideLine `clear()` if declared;
+4. wait for each pending `load` to settle;
+5. call identity-safe `plugins.unregister(name, expected)` once per registered controller.
+
+Do not explicitly dispose a controller after successful unregister. Only a candidate that failed before registration is directly disposed.
+
+## Recipe: model floorplan
+
+The generated project already implements this recipe. Extend it rather than creating a second floor source of truth.
+
+1. Call `GET /open/v3/floorplan/plugins?resource_code=...` server-side.
+2. Read `data.format_floorplan_url`; do not substitute `format_model_url`.
+3. Fetch that external HTTPS URL without gateway `Authorization`, redirects, or unbounded response size/time.
+4. Validate the complete `{ version, data: FloorplanServerData }` wrapper.
+5. Return optional `capabilities.modelFloorplan` so failure does not block the base Work.
+6. Create `ModelFloorplanPlugin` with `autoShowEnable: false`, mount it with `appendTo(wrapper)`, then load.
+7. Add `平面图` only after successful validation/load. `漫游` maps to Panorama and `三维模型` to Mapview; Topview is not “地图”.
+8. Own model opacity while visible and restore it on hide, failure, and disposal. Let Five/plugin floor synchronization remain authoritative.
+
+## Recipe: runtime model picking without persistence
+
+For prompts such as “点击墙面选一个点” or “判断空间点是否可见”, use `PanoCursorRaycasterPlugin`. No OpenAPI call is required unless persistence is separately requested.
+
+The pinned 3.81.2 public declaration is version-specific:
+
+- import from the package root, not `@realsee/dnalogel/PanoCursorRaycasterPlugin`;
+- call `canSeePoint(point, distanceError?)` and `pointAxesHelper(point, length?, fixDistance?)` with positional arguments;
+- call `destroy()`, not the undeclared runtime `dispose` alias.
+
+3.81.2 also installs an internal anonymous `modelLoaded` listener that `destroy()` cannot remove. Therefore create one cursor owner before `five.load`, keep it for the Five instance lifetime, remove only business listeners/helpers when a feature turns off, and call `destroy()` exactly once immediately before `five.dispose()`. Do not load another Work/model between those two calls. An SDK version may support shorter feature ownership only when its declarations and implementation both remove every internal listener.
+
+```ts
+import type { Five } from "@realsee/five";
+import { PanoCursorRaycasterPlugin } from "@realsee/dnalogel";
+import type { Vector3 } from "three";
+
+export const createPanoCursorRuntime = (five: Five) => {
+  // Construct before the first five.load so 3.81.2 observes modelLoaded.
+  const cursor = PanoCursorRaycasterPlugin(five, {});
+  let helper: ReturnType<typeof cursor.pointAxesHelper> | undefined;
+  let select: ((point: Vector3) => void) | undefined;
+  let disposed = false;
+
+  const onTap = (): false | void => {
+    if (!select) return;
+    const hit = cursor.intersection();
+    if (!hit) return;
+
+    const point = hit.point.clone();
+    if (!cursor.canSeePoint(point.clone(), 0.05)) return;
+
+    helper?.clear();
+    helper = cursor.pointAxesHelper(point, 1.5, 0.2);
+    select(point.clone());
+    return false; // only a successful selection owns the tap
+  };
+
+  const onModelLoaded = () => {
+    if (disposed) return;
+    five.off("wantsTapGesture", onTap);
+    five.on("wantsTapGesture", onTap);
+  };
+
+  five.on("modelLoaded", onModelLoaded);
+
+  return {
+    install(onSelect: (point: Vector3) => void) {
+      select = onSelect;
+      return () => {
+        if (select === onSelect) select = undefined;
+        helper?.clear();
+        helper = undefined;
+      };
+    },
+    disposeBeforeFive() {
+      if (disposed) return;
+      disposed = true;
+      select = undefined;
+      five.off("modelLoaded", onModelLoaded);
+      five.off("wantsTapGesture", onTap);
+      helper?.clear();
+      helper = undefined;
+      cursor.destroy();
+    },
+  };
+};
+```
+
+All business listeners above have stable identities and are removed. Misses, pre-readiness calls, invisible points, and inactive features return `void`, preserving Five's default tap navigation; only a successful selection returns `false`. Clone visibility inputs because 3.81.2 may mutate the supplied vector while constructing its ray.
+
+Keep the result runtime-only unless an authoritative editor/API contract and explicit user intent define where it may be persisted.
+
+## Prompt handling examples
+
+- “给这个 VR 加几个视频热点”：use `/open/v3/hot/list`, parse a `Video` DTO, and convert to PanoTag; do not invent media URLs or browser credentials.
+- “按后台路线自动漫游”：use `/open/v3/route/search`; inspect whether the selected route is a pano group or model path, then choose Cruise or Move and keep GuideLine separate.
+- “展示讲解点并点击切换”：use `/open/v3/observerpicture/search`; adapt to Five State snapshots, not PanoTag or Cruise.
+- “显示模型标注”：use `/open/v3/annotation/search` and ModelMaker after geometry/model-readiness validation.
+- “加户型图”：extend the existing floorplan capability path; never add an unvalidated browser fetch.
+- “点墙面放一个临时标记”：use the Five-lifetime PanoCursor owner plus a feature-owned helper; persistence requires a separate explicit source contract.
+
+## Completion checklist
+
+Before claiming completion, verify:
+
+- the prompt maps to an explicit capability and authoritative data source;
+- browser code contains no AK/SK, access token, or authenticated OpenAPI call;
+- upstream `unknown` data passes a shared runtime parser before reaching the browser;
+- every feature image reaching a plugin or the DOM is a derived sized variant on an approved host, not the upstream original;
+- DTO-to-SDK conversion is exhaustive and contains no final unsafe cast;
+- imports and controller methods compile against the pinned installed npm declarations;
+- Work/model readiness matches the selected plugin;
+- requests, stale continuations, hooks, playback/media, registrations, helper meshes, and controllers are cleaned up by one owner;
+- registered instances are disposed only through identity-safe unregister, while failed unregistered candidates are disposed directly;
+- one feature failure leaves the base Viewer usable;
+- generated-project checks, the 3.81.2 contract fixture, and a real browser scenario pass.