@webspatial/core-sdk 1.5.0 → 1.6.1

package/src/scene-polyfill.ts

@@ -9,8 +9,13 @@ import {
   isValidWorldScalingType,
   isValidWorldAlignmentType,
   isValidBaseplateVisibilityType,
+  PWAManifest,
+  XRSpatialSceneConfig,
+  XRSpatialSceneDefaults,
 } from './types/types'
 import { SpatialSceneCreationOptionsInternal } from './types/internal'
+import { deepCloneJSON } from './utils'
+import { pointToPhysical, physicalToPoint } from './physicalMetrics'
 
 const defaultSceneConfig: SpatialSceneCreationOptions = {
   defaultSize: {
@@ -21,17 +26,80 @@ const defaultSceneConfig: SpatialSceneCreationOptions = {
 
 const defaultSceneConfigVolume: SpatialSceneCreationOptions = {
   defaultSize: {
-    width: 0.94,
-    height: 0.94,
-    depth: 0.94,
+    width: '0.94m',
+    height: '0.94m',
+    depth: '0.94m',
   },
 }
 
+let xr_window_defaults: SpatialSceneCreationOptions = {
+  ...defaultSceneConfig,
+}
+let xr_volume_defaults: SpatialSceneCreationOptions = {
+  ...defaultSceneConfigVolume,
+}
+
 const INTERNAL_SCHEMA_PREFIX = 'webspatial://'
 
+/**
+ * Deep-merge two plain object trees (no arrays, no special classes).
+ * - Creates a shallow clone of base, then recursively merges properties from over.
+ * - When both sides at a key are plain objects, merges recursively; otherwise, replaces with over.
+ * - Ignores arrays (treated as replace).
+ * Intended for small configuration objects like manifest overrides.
+ */
+function deepMergePlain<
+  T extends Record<string, any>,
+  U extends Record<string, any> | undefined,
+>(base: T, over: U): T & (U extends undefined ? {} : U) {
+  if (!over) return { ...(base || {}) } as any
+  const out: any = { ...(base || {}) }
+  for (const k of Object.keys(over)) {
+    const bv = out[k]
+    const ov = (over as any)[k]
+    if (
+      ov &&
+      typeof ov === 'object' &&
+      !Array.isArray(ov) &&
+      bv &&
+      typeof bv === 'object' &&
+      !Array.isArray(bv)
+    ) {
+      out[k] = deepMergePlain(bv, ov)
+    } else {
+      out[k] = ov
+    }
+  }
+  return out
+}
+
+/**
+ * Normalize XRSpatialSceneDefaults (manifest shape) into SpatialSceneCreationOptions (runtime shape).
+ * - Only remap default_size -> defaultSize when present.
+ * - Leaves other keys (resizability, worldScaling, etc.) unchanged.
+ * - Units are left as-is; downstream formatting is handled by formatSceneConfig.
+ */
+function normalizeXRDefaultsToSceneOptions(
+  src: XRSpatialSceneDefaults | Record<string, any>,
+): SpatialSceneCreationOptions {
+  const out: any = { ...(src || {}) }
+  const ds =
+    (src as any).defaultSize !== undefined
+      ? (src as any).defaultSize
+      : (src as any).default_size
+  if (ds !== undefined) {
+    out.defaultSize = ds
+  }
+  if ('default_size' in out) {
+    delete out.default_size
+  }
+  return out
+}
+
 class SceneManager {
   private originalOpen: any
   private static instance: SceneManager
+  private manifestReady: Promise<void> | null = null
   static getInstance() {
     if (!SceneManager.instance) {
       SceneManager.instance = new SceneManager()
@@ -40,16 +108,26 @@ class SceneManager {
   }
 
   init(window: WindowProxy) {
+    this.manifestReady = this.setupManifest()
     this.originalOpen = window.open.bind(window)
     ;(window as any).open = this.open
   }
 
-  private configMap: Record<string, SpatialSceneCreationOptionsInternal> = {} // name=>config
+  // Stores the latest formatted config used by the platform (per scene name).
+  // This object contains normalized values and is safe for internal consumption.
+  private configMap: Record<string, SpatialSceneCreationOptionsInternal> = {}
+  // Stores the raw callback return value (per scene name) to feed into the next initScene call as `pre`.
+  // We keep this unformatted so developers receive exactly what they last returned.
+  private callbackReturnMap: Record<string, SpatialSceneCreationOptions> = {}
   private getConfig(name?: string) {
     if (name === undefined || !this.configMap[name]) return undefined
     return this.configMap[name]
   }
 
+  waitManifest(): Promise<void> {
+    return this.manifestReady ?? Promise.resolve()
+  }
+
   // Ensure URL is absolute; only convert when a relative path is provided
   // - Keep external and special schemes untouched (http, https, data, blob, about, file, mailto, etc.)
   // - Handle protocol-relative URLs (//example.com/path)
@@ -73,15 +151,48 @@ class SceneManager {
     }
   }
 
+  private async setupManifest() {
+    const manifest = await this.getPWAManifest()
+    try {
+      const xr = manifest?.xr_spatial_scene
+      if (!xr || typeof xr !== 'object') return
+      const { overrides, ...topLevel } = xr as XRSpatialSceneConfig
+      // Merge top-level defaults with per-scene overrides.
+      const windowRaw = deepMergePlain(topLevel, overrides?.window_scene)
+      const volumeRaw = deepMergePlain(topLevel, overrides?.volume_scene)
+      const windowNext = normalizeXRDefaultsToSceneOptions(windowRaw)
+
+      const volumeNext = normalizeXRDefaultsToSceneOptions(volumeRaw)
+      if (windowNext && Object.keys(windowNext).length > 0) {
+        xr_window_defaults = windowNext
+      }
+      if (volumeNext && Object.keys(volumeNext).length > 0) {
+        xr_volume_defaults = volumeNext
+      }
+    } catch (error: any) {
+      console.warn(
+        'SceneManager.setupManifest failed; using built-in defaults.',
+        error?.message || error,
+      )
+    }
+  }
+
   private open = (url?: string, target?: string, features?: string) => {
     // bypass internal
     if (url?.startsWith(INTERNAL_SCHEMA_PREFIX)) {
-      if (url.includes('createSpatialized2DElement')) {
-        const token = window.webSpatial?.genToken?.()
+      if (
+        url.includes('createSpatialized2DElement') ||
+        url.includes('createAttachment')
+      ) {
+        const token = //@ts-ignore
+          (window.webSpatial || window.__webspatialShell__)?.genToken?.()
         if (token) {
+          const command = url.includes('createAttachment')
+            ? 'createAttachment'
+            : 'createSpatialized2DElement'
           const host = window.location.host
           const protocol = window.location.protocol
-          const finalURL = `${protocol}//${host}/${token}/?command=createSpatialized2DElement`
+          const finalURL = `${protocol}//${host}/${token}/?command=${command}`
           const rid = new URL(url).searchParams.get('rid')
           const final = new URL(finalURL)
           if (rid) final.searchParams.set('rid', rid)
@@ -100,7 +211,16 @@ class SceneManager {
       return newWindow
     }
 
-    const cfg = target ? this.getConfig(target) : undefined
+    let cfg = target ? this.getConfig(target) : undefined
+
+    if (cfg === undefined) {
+      // if no config, use default window config
+      const preFormatted = deepCloneJSON(getSceneDefaultConfig('window'))
+
+      const [ans] = formatSceneConfig(preFormatted, 'window')
+      cfg = { ...ans, type: 'window' }
+    }
+
     const cmd = new createSpatialSceneCommand(url!, cfg, target, features)
     const result = cmd.executeSync()
 
@@ -120,25 +240,137 @@ class SceneManager {
     options?: { type: SpatialSceneType },
   ) {
     const sceneType = options?.type ?? 'window'
-    const defaultConfig = getSceneDefaultConfig(sceneType)
-    const rawReturnVal = callback({ ...defaultConfig })
-    const [formattedConfig, errors] = formatSceneConfig(rawReturnVal, sceneType)
+    const defaultConfigRaw = getSceneDefaultConfig(sceneType)
+    const previousOrDefault =
+      this.callbackReturnMap[name] ??
+      ((): SpatialSceneCreationOptions => {
+        // Clone default config to avoid mutating shared defaults during formatting.
+        const cloned = deepCloneJSON(defaultConfigRaw)
+        return cloned
+      })()
+    const rawReturnVal = callback(previousOrDefault)
+    const sanitizedReturnVal = sanitizeSceneOptionsUnits(
+      deepCloneJSON(rawReturnVal),
+    )
+    const clonedForFormat = deepCloneJSON(sanitizedReturnVal)
+    // Merge normalized user return with scene-type defaults before final formatting.
+    // This ensures missing fields fall back to the appropriate xr_window_defaults / xr_volume_defaults.
+    const baseDefaults = deepCloneJSON(getSceneDefaultConfig(sceneType))
+    const mergedForFormat = deepMergePlain(baseDefaults, clonedForFormat)
+
+    const [formattedConfig, errors] = formatSceneConfig(
+      mergedForFormat,
+      sceneType,
+    )
+
     if (errors.length > 0) {
       console.warn(`initScene ${name} with errors: ${errors.join(', ')}`)
     }
+    this.callbackReturnMap[name] = sanitizedReturnVal
     this.configMap[name] = {
       ...formattedConfig,
       type: sceneType,
     }
   }
+  /**
+   * Resolve and load a PWA manifest as JSON:
+   * 1) Determine href:
+   *    - Prefer explicit manifestUrl if provided;
+   *    - Fallback to <link rel="manifest">, preferring the raw attribute over computed href.
+   * 2) Normalize href to absolute using ensureAbsoluteUrl (respects <base href>).
+   * 3) Handle data URLs inline:
+   *    - data:...;base64,... → atob then JSON.parse
+   *    - data:...,... → decodeURIComponent then JSON.parse
+   * 4) Fetch with credentials same-origin first; if that fails (e.g., CORS), attempt unauthenticated fetch.
+   * 5) Parse as JSON; if response body is text, parse the text as JSON.
+   */
+  async getPWAManifest(manifestUrl?: string): Promise<PWAManifest | undefined> {
+    let href: string | undefined = manifestUrl
+    if (!href) {
+      const el = document.querySelector(
+        'link[rel="manifest"]',
+      ) as HTMLLinkElement | null
+      href = el?.getAttribute('href') || el?.href
+    }
+    if (!href) return
+    href = this.ensureAbsoluteUrl(href)
+    if (!href) return
+    if (href.startsWith('data:')) {
+      // Inline data URL manifest: data:[<mediatype>][;base64],<data>
+      try {
+        const comma = href.indexOf(',')
+        if (comma < 0) return
+        const meta = href.slice(5, comma)
+        const data = href.slice(comma + 1)
+        const isBase64 = /;base64/i.test(meta)
+        const decoded = isBase64 ? atob(data) : decodeURIComponent(data)
+        return JSON.parse(decoded)
+      } catch {
+        return
+      }
+    }
+    try {
+      // Same-origin fetch with credentials first.
+      const res = await fetch(href, { credentials: 'same-origin' })
+      if (!res.ok) throw new Error(String(res.status))
+      try {
+        return await res.json()
+      } catch {
+        const t = await res.text()
+        return JSON.parse(t)
+      }
+    } catch {
+      try {
+        // Fallback: unauthenticated fetch (may help when same-origin credentials fail due to CORS).
+        const res = await fetch(href)
+        if (!res.ok) return
+        try {
+          return await res.json()
+        } catch {
+          const t = await res.text()
+          return JSON.parse(t)
+        }
+      } catch {
+        return
+      }
+    }
+  }
+}
+
+function sanitizeSceneOptionsUnits(
+  val: SpatialSceneCreationOptions,
+): SpatialSceneCreationOptions {
+  if (val?.defaultSize) {
+    const keys = ['width', 'height', 'depth'] as const
+    for (const k of keys) {
+      if (
+        k in (val.defaultSize as any) &&
+        !isValidSceneUnit((val.defaultSize as any)[k])
+      ) {
+        delete (val.defaultSize as any)[k]
+      }
+    }
+  }
+  if (val?.resizability) {
+    const keys = ['minWidth', 'minHeight', 'maxWidth', 'maxHeight'] as const
+    for (const k of keys) {
+      if (
+        k in (val.resizability as any) &&
+        !isValidSceneUnit((val.resizability as any)[k])
+      ) {
+        delete (val.resizability as any)[k]
+      }
+    }
+  }
+  return val
 }
 
 function pxToMeter(px: number): number {
-  return px / 1360
+  return pointToPhysical(px)
 }
 
 function meterToPx(meter: number): number {
-  return meter * 1360
+  return physicalToPoint(meter)
 }
 
 function formatToNumber(
@@ -215,12 +447,11 @@ export function formatSceneConfig(
         ;(config.defaultSize as any)[k] = formatToNumber(
           (config.defaultSize as any)[k],
           isWindow ? 'px' : 'm',
-          isWindow ? 'px' : 'm',
+          'px',
         )
       } else {
-        ;(config.defaultSize as any)[k] = (
-          defaultSceneConfig.defaultSize as any
-        )[k]
+        // delete invalid unit
+        delete (config.defaultSize as any)[k]
         errors.push(`defaultSize.${k}`)
       }
     }
@@ -235,10 +466,11 @@ export function formatSceneConfig(
         ;(config.resizability as any)[k] = formatToNumber(
           (config.resizability as any)[k],
           'px',
-          isWindow ? 'px' : 'm',
+          'px',
         )
       } else {
-        ;(config.resizability as any)[k] = undefined
+        // delete invalid unit
+        delete (config.resizability as any)[k]
         errors.push(`resizability.${k}`)
       }
     }
@@ -277,6 +509,13 @@ export function initScene(
   return SceneManager.getInstance().initScene(name, callback, options)
 }
 
+export function __getSceneConfigSnapshotForTest(
+  name: string,
+): SpatialSceneCreationOptionsInternal | undefined {
+  const mgr = SceneManager.getInstance() as any
+  return mgr?.configMap?.[name]
+}
+
 export function hijackWindowOpen(window: WindowProxy) {
   SceneManager.getInstance().init(window)
 }
@@ -284,23 +523,22 @@ export function hijackWindowOpen(window: WindowProxy) {
 export function hijackWindowATag(openedWindow: WindowProxy) {
   openedWindow!.document.onclick = function (e) {
     let element = e.target as HTMLElement | null
-    let found = false
 
     // Look for <a> element in the clicked elements parents and if found override navigation behavior if needed
-    while (!found) {
-      if (element && element.tagName == 'A') {
+    while (element) {
+      if (element.tagName == 'A') {
         // When using libraries like react route's <Link> it sets an onclick event, when this happens we should do nothing and let that occur
 
         // if onClick is set for the element, the raw onclick will be noop() trapped so the onclick check is no longer trustable
         // we handle all the scenarios
 
-        if (handleATag(e)) {
+        if (handleATag(e, element as HTMLAnchorElement)) {
           return false // prevent default action and stop event propagation
         }
 
         return true
       }
-      if (element && element.parentElement) {
+      if (element.parentElement) {
         element = element.parentElement
       } else {
         break
@@ -309,23 +547,24 @@ export function hijackWindowATag(openedWindow: WindowProxy) {
   }
 }
 
-function handleATag(event: MouseEvent) {
-  const targetElement = event.target as HTMLElement
-  if (targetElement.tagName === 'A') {
-    const link = targetElement as HTMLAnchorElement
-    const target = link.target
-    const url = link.href
-
-    if (target && target !== '_self') {
-      event.preventDefault()
-      window.open(url, target)
-      return true
-    }
+function handleATag(event: MouseEvent, link: HTMLAnchorElement) {
+  // Respect clicks that have already been cancelled (e.g. by app/router handlers).
+  if (event.defaultPrevented) return false
+  // Use the anchor found during bubbling so nested clicks like <a><img /></a> are handled correctly.
+  const target = link.target
+  const url = link.href
+
+  if (target && target !== '_self') {
+    event.preventDefault()
+    window.open(url, target)
+    return true
   }
 }
 
 function getSceneDefaultConfig(sceneType: SpatialSceneType) {
-  return sceneType === 'window' ? defaultSceneConfig : defaultSceneConfigVolume
+  return sceneType === 'window'
+    ? xr_window_defaults || defaultSceneConfig
+    : xr_volume_defaults || defaultSceneConfigVolume
 }
 
 async function injectScenePolyfill() {
@@ -348,13 +587,16 @@ async function injectScenePolyfill() {
   }
 
   onContentLoaded(async () => {
-    let provideDefaultSceneConfig = getSceneDefaultConfig(
-      window.xrCurrentSceneType ?? 'window',
-    )
-    let cfg = provideDefaultSceneConfig
+    await SceneManager.getInstance().waitManifest()
+    const sceneType = window.xrCurrentSceneType ?? 'window'
+    const rawDefault = getSceneDefaultConfig(sceneType)
+    // Provide a formatted 'pre' to the callback for consistent units and types.
+    const pre = deepCloneJSON(rawDefault)
+
+    let cfg = pre
     if (typeof window.xrCurrentSceneDefaults === 'function') {
       try {
-        cfg = await window.xrCurrentSceneDefaults?.(provideDefaultSceneConfig)
+        cfg = await window.xrCurrentSceneDefaults?.(pre)
       } catch (error) {
         console.error(error)
       }
@@ -366,17 +608,19 @@ async function injectScenePolyfill() {
       }, 1000)
     })
 
-    const sceneType = window.xrCurrentSceneType ?? 'window'
-    const [formattedConfig, errors] = formatSceneConfig(cfg, sceneType)
+    // Merge callback return with base defaults to ensure missing fields are filled.
+    const mergedCfg = deepMergePlain(deepCloneJSON(rawDefault), cfg)
+    const [formattedConfig, errors] = formatSceneConfig(mergedCfg, sceneType)
     if (errors.length > 0) {
       console.warn(
         `window.xrCurrentSceneDefaults with errors: ${errors.join(', ')}`,
       )
     }
-    await SpatialScene.getInstance().updateSceneCreationConfig({
+    const finalCfg = {
       ...formattedConfig,
       type: sceneType,
-    })
+    }
+    await SpatialScene.getInstance().updateSceneCreationConfig(finalCfg)
   })
 }
 

package/src/types/global.d.ts

@@ -26,6 +26,9 @@ declare global {
     webSpatial?: {
       genToken?: () => string
     }
+    __webspatialShell__?: {
+      genToken?: () => string
+    }
 
     // Will be removed in favor of __WebSpatialData
     WebSpatailNativeVersion: string

package/src/types/types.ts

@@ -95,10 +95,20 @@ export interface Spatialized2DElementProperties
   scrollEdgeInsetsMarginRight: number
 }
 
+export interface ModelSource {
+  src: string
+  type?: string
+}
+
 export interface SpatializedStatic3DElementProperties
   extends SpatializedElementProperties {
   modelURL: string
+  sources?: ModelSource[]
   modelTransform?: number[]
+  autoplay?: boolean
+  loop?: boolean
+  animationPaused?: boolean
+  playbackRate?: number
 }
 
 export interface SpatialSceneCreationOptions {
@@ -411,3 +421,64 @@ export interface AttachmentEntityUpdateOptions {
   position?: [number, number, number]
   size?: { width: number; height: number }
 }
+
+// manifest
+
+export type SceneUnitPx = `${number}px`
+export type SceneUnitM = `${number}m`
+export type SceneUnit = number | SceneUnitPx | SceneUnitM
+
+export interface XRSceneSize {
+  width: SceneUnit
+  height: SceneUnit
+  depth?: SceneUnit
+}
+
+export interface XRSceneResizability {
+  minWidth?: SceneUnit
+  minHeight?: SceneUnit
+  maxWidth?: SceneUnit
+  maxHeight?: SceneUnit
+}
+
+export interface XRMainSceneConfig extends XRSpatialSceneDefaults {
+  type?: SpatialSceneType
+}
+
+export interface XRSpatialSceneDefaults {
+  default_size?: XRSceneSize
+  resizability?: XRSceneResizability
+  worldScaling?: WorldScalingType
+  worldAlignment?: WorldAlignmentType
+  baseplateVisibility?: BaseplateVisibilityType
+}
+
+export interface XRSpatialSceneOverrides {
+  window_scene?: XRSpatialSceneDefaults
+  volume_scene?: XRSpatialSceneDefaults
+}
+
+export interface XRSpatialSceneConfig extends XRSpatialSceneDefaults {
+  overrides?: XRSpatialSceneOverrides
+}
+
+export interface XRPrdConfig {
+  xr_main_scene?: XRMainSceneConfig
+  xr_spatial_scene?: XRSpatialSceneConfig
+}
+
+export interface PWAManifest extends XRPrdConfig {
+  name?: string
+  short_name?: string
+  start_url?: string
+  display?: string
+  icons?: Array<{
+    src: string
+    sizes?: string
+    type?: string
+    purpose?: string
+  }>
+  id?: string
+  scope?: string
+  [key: string]: any
+}

package/src/utils.ts

@@ -59,3 +59,24 @@ export function composeSRT(position: Vec3, rotation: Vec3, scale: Vec3) {
   m = m.scale(sx, sy, sz)
   return m
 }
+
+/**
+ * Deep-clone a plain JSON-serializable object by value.
+ *
+ * Notes:
+ * - Only use for data composed of primitives, arrays, and plain objects.
+ * - Functions, Dates, Maps/Sets, DOM nodes, and circular structures are not supported.
+ */
+export function deepCloneJSON<T>(value: T): T {
+  const sc = (globalThis as any).structuredClone as
+    | ((v: any) => any)
+    | undefined
+  if (typeof sc === 'function') {
+    try {
+      return sc(value)
+    } catch {
+      // fall through to JSON method
+    }
+  }
+  return JSON.parse(JSON.stringify(value))
+}