feat(validatePreviewUrl): add studioPreviewPerspective

packages/preview-url-secret/src/parsePreviewUrl.ts

@@ -1,4 +1,8 @@
-import {urlSearchParamPreviewPathname, urlSearchParamPreviewSecret} from './constants'
+import {
+  urlSearchParamPreviewPathname,
+  urlSearchParamPreviewPerspective,
+  urlSearchParamPreviewSecret,
+} from './constants'
 import type {ParsedPreviewUrl} from './types'
 
 /**
@@ -10,11 +14,12 @@ export function parsePreviewUrl(unsafeUrl: string): ParsedPreviewUrl {
   if (!secret) {
     throw new Error('Missing secret')
   }
+  const studioPreviewPerspective = url.searchParams.get(urlSearchParamPreviewPerspective)
   let redirectTo = undefined
   const unsafeRedirectTo = url.searchParams.get(urlSearchParamPreviewPathname)
   if (unsafeRedirectTo) {
     const {pathname, search, hash} = new URL(unsafeRedirectTo, 'http://localhost')
     redirectTo = `${pathname}${search}${hash}`
   }
-  return {secret, redirectTo}
+  return {secret, redirectTo, studioPreviewPerspective}
 }

packages/preview-url-secret/src/types.ts

@@ -49,12 +49,19 @@ export interface PreviewUrlValidateUrlResult {
    * If the URL is valid, and the studio URL is known and valid, then its origin will be here
    */
   studioOrigin?: string
+  /**
+   * The initial perspective the Studio was using when starting to load the preview.
+   * It can change over time and should also be handled with `postMessage` listeners.
+   * The value can be arbitrary and has to be validated to make sure it's a valid perspective.
+   */
+  studioPreviewPerspective?: string | null
 }
 
 /** @internal */
 export interface ParsedPreviewUrl {
   secret: string
   redirectTo?: string
+  studioPreviewPerspective: string | null
 }
 
 /** @public */

packages/preview-url-secret/src/validatePreviewUrl.ts

@@ -37,6 +37,7 @@ export async function validatePreviewUrl(
     disableCacheNoStore,
   )
   const redirectTo = isValid ? parsedPreviewUrl.redirectTo : undefined
+  const studioPreviewPerspective = isValid ? parsedPreviewUrl.studioPreviewPerspective : undefined
   let studioOrigin: string | undefined
   if (isValid) {
     try {
@@ -52,7 +53,7 @@ export async function validatePreviewUrl(
     }
   }
 
-  return {isValid, redirectTo, studioOrigin}
+  return {isValid, redirectTo, studioOrigin, studioPreviewPerspective}
 }
 
 export type {PreviewUrlValidateUrlResult, SanityClientLike}