@webspatial/core-sdk 1.6.0 → 1.7.0

package/src/runtime/supports.ts

@@ -0,0 +1,110 @@
+import { CAPABILITY_TABLE, type CapabilityVersionRow } from './capability-data'
+import { compareSemver, parseSemverOrNull } from './semver'
+import type { WebSpatialRuntimeSnapshot } from './types'
+import { computeRuntimeFromUserAgent } from './userAgent'
+import {
+  type CapabilityKey,
+  isKnownSubToken,
+  isKnownTopLevel,
+  normalizeCapabilityName,
+} from './keys'
+
+/**
+ * Unsubstituted shell version placeholder from visionOS manifest / Xcode template
+ * (`manifest.swift`). When still present in `WSAppShell/<version>`, treat as debug
+ * build: {@link supports} returns true for every valid capability query.
+ */
+export const VISIONOS_DEBUG_SHELL_VERSION_PLACEHOLDER = 'WS_SHELL_VERSION'
+
+let runtimeCache: WebSpatialRuntimeSnapshot | undefined
+
+/** Test helper: clear cached UA/runtime snapshot between Vitest cases. */
+export function resetRuntimeCacheForTests(): void {
+  runtimeCache = undefined
+}
+
+/**
+ * Internal runtime snapshot (not part of the public `@webspatial/react-sdk` surface).
+ */
+export function getRuntime(): WebSpatialRuntimeSnapshot {
+  if (runtimeCache !== undefined) return runtimeCache
+  if (typeof navigator === 'undefined') {
+    runtimeCache = { type: null, shellVersion: null }
+    return runtimeCache
+  }
+  runtimeCache = computeRuntimeFromUserAgent(navigator.userAgent)
+  return runtimeCache
+}
+
+function selectRow(
+  type: 'visionos' | 'picoos',
+  shellVersion: string,
+): CapabilityVersionRow | null {
+  const norm = parseSemverOrNull(shellVersion)
+  if (!norm) return null
+  const rows = CAPABILITY_TABLE[type]
+  if (!rows.length) return null
+  const sorted = [...rows].sort((a, b) => compareSemver(a.version, b.version))
+  const minV = sorted[0].version
+  if (compareSemver(norm, minV) < 0) return null
+
+  let chosen: CapabilityVersionRow | null = null
+  for (const row of sorted) {
+    if (compareSemver(row.version, norm) <= 0) {
+      chosen = row
+    } else {
+      break
+    }
+  }
+  return chosen
+}
+
+/**
+ * Public capability probe (`WebSpatialRuntime.supports` re-exports this from React SDK).
+ */
+export function supports(
+  name: CapabilityKey,
+  tokens?: readonly string[],
+): boolean
+export function supports(name: string, tokens?: readonly string[]): boolean
+export function supports(name: string, tokens?: readonly string[]): boolean {
+  if (typeof name !== 'string') return false
+  const canonical = normalizeCapabilityName(name)
+  if (!isKnownTopLevel(canonical)) return false
+
+  const tokList =
+    tokens === undefined ? [] : Array.isArray(tokens) ? [...tokens] : []
+  if (tokList.some(t => typeof t !== 'string')) return false
+
+  for (const t of tokList) {
+    if (!isKnownSubToken(canonical, t)) return false
+  }
+
+  const rt = getRuntime()
+  if (rt.type === 'puppeteer') {
+    return true
+  }
+  if (rt.type === null) return false
+  if (rt.shellVersion === null) return false
+
+  if (
+    rt.type === 'visionos' &&
+    rt.shellVersion === VISIONOS_DEBUG_SHELL_VERSION_PLACEHOLDER
+  ) {
+    return true
+  }
+
+  const parsedShell = parseSemverOrNull(rt.shellVersion)
+  if (!parsedShell) return false
+
+  if (rt.type !== 'visionos' && rt.type !== 'picoos') return false
+
+  const row = selectRow(rt.type, parsedShell)
+  if (!row) return false
+
+  if (tokList.length === 0) {
+    return row.flags[canonical] === true
+  }
+  if (row.flags[canonical] !== true) return false
+  return tokList.every(t => row.flags[`${canonical}:${t}`] === true)
+}

package/src/runtime/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Internal runtime classification (see OpenSpec `review.md`).
+ * `puppeteer`: automation / test harness UA — not a product matrix row; see `supports()`.
+ */
+export type WebSpatialRuntimeType = 'visionos' | 'picoos' | 'puppeteer' | null
+
+/** Snapshot returned by internal `getRuntime()` (not a public app API). */
+export type WebSpatialRuntimeSnapshot = {
+  type: WebSpatialRuntimeType
+  shellVersion: string | null
+}

package/src/runtime/userAgent.ts

@@ -0,0 +1,64 @@
+import type { WebSpatialRuntimeSnapshot } from './types'
+
+/**
+ * Parse shell token from UA:
+ * - packaged/hybrid runtimes use `WSAppShell/<version>`
+ * - browser-mode runtime on Pico OS uses `PicoWebApp/<version>`
+ *
+ * Keep `WSAppShell` precedence when both appear in one UA.
+ */
+export function parseShellToken(ua: string): {
+  version: string | null
+  source: 'wsapp' | 'picoapp' | null
+} {
+  const ws = /\bWSAppShell\/([\w.-]+)/i.exec(ua)
+  if (ws?.[1]) return { version: ws[1], source: 'wsapp' }
+  const pico = /\bPicoWebApp\/([\w.-]+)/i.exec(ua)
+  if (pico?.[1]) return { version: pico[1], source: 'picoapp' }
+  return { version: null, source: null }
+}
+
+/** Pico runtime: require explicit Pico tokens (do not treat generic `like Quest` VR UAs as picoos). */
+function inferPicoOs(ua: string): boolean {
+  return /\bPicoWebApp\//i.test(ua) || /\bPicoBrowser\b/i.test(ua)
+}
+
+/** visionOS-class WebView UAs include a Mac OS X platform token; `WSAppShell` alone is not enough. */
+function inferVisionOsFromUa(ua: string): boolean {
+  return /Mac OS X/i.test(ua)
+}
+
+/**
+ * Resolve internal runtime snapshot from `navigator.userAgent`.
+ * SSR / no navigator → `{ type: null, shellVersion: null }` (no throw).
+ */
+export function computeRuntimeFromUserAgent(
+  userAgent: string | undefined,
+): WebSpatialRuntimeSnapshot {
+  if (userAgent === undefined || userAgent === '') {
+    return { type: null, shellVersion: null }
+  }
+  // Must run before the shell-token gate: Puppeteer UAs may omit WSAppShell/PicoWebApp.
+  if (userAgent.includes('Puppeteer')) {
+    const { version } = parseShellToken(userAgent)
+    return { type: 'puppeteer', shellVersion: version }
+  }
+
+  const { version, source } = parseShellToken(userAgent)
+  if (!version) {
+    return { type: null, shellVersion: null }
+  }
+
+  if (source === 'picoapp' || inferPicoOs(userAgent)) {
+    return { type: 'picoos', shellVersion: version }
+  }
+
+  if (source === 'wsapp') {
+    if (inferVisionOsFromUa(userAgent)) {
+      return { type: 'visionos', shellVersion: version }
+    }
+    return { type: null, shellVersion: version }
+  }
+
+  return { type: null, shellVersion: version }
+}

package/src/scene-polyfill.manifest.test.ts

@@ -1,12 +1,14 @@
 import { describe, it, expect, vi } from 'vitest'
 
+vi.mock('./spatial-host', () => ({
+  openSpatialSceneSync: vi.fn().mockReturnValue({
+    success: true,
+    data: { id: 'scene-1', windowProxy: {} },
+  }),
+}))
+
 vi.mock('./JSBCommand', () => {
   return {
-    createSpatialSceneCommand: vi.fn().mockImplementation(() => ({
-      executeSync: vi.fn().mockReturnValue({
-        data: { id: 'scene-1', windowProxy: {} },
-      }),
-    })),
     FocusScene: vi.fn().mockImplementation(() => ({
       execute: vi.fn().mockResolvedValue(undefined),
     })),

package/src/scene-polyfill.test.ts

@@ -4,6 +4,7 @@ import {
   initScene,
   injectSceneHook,
   __getSceneConfigSnapshotForTest,
+  hijackWindowATag,
 } from './scene-polyfill'
 import { SpatialSceneCreationOptions } from './types/types'
 import { pointToPhysical } from './physicalMetrics'
@@ -464,3 +465,62 @@ describe('initScene callback chaining', () => {
     expect(cb2).toHaveBeenCalledWith(firstReturn)
   })
 })
+
+describe('hijackWindowATag', () => {
+  afterEach(() => {
+    document.body.innerHTML = ''
+    document.onclick = null
+    vi.restoreAllMocks()
+  })
+
+  it('handles clicks on nested elements inside anchor tags', () => {
+    const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null)
+    hijackWindowATag(window)
+
+    const anchor = document.createElement('a')
+    anchor.href = 'https://example.com/detail'
+    anchor.target = '_blank'
+
+    const image = document.createElement('img')
+    anchor.appendChild(image)
+    document.body.appendChild(anchor)
+
+    image.dispatchEvent(
+      new MouseEvent('click', { bubbles: true, cancelable: true }),
+    )
+
+    expect(openSpy).toHaveBeenCalledWith('https://example.com/detail', '_blank')
+  })
+})
+
+describe('hijackWindowATag – defaultPrevented', () => {
+  afterEach(() => {
+    document.body.innerHTML = ''
+    document.onclick = null
+    vi.restoreAllMocks()
+  })
+
+  it('does not open a new window when the click was already preventDefault-ed', () => {
+    const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null)
+    hijackWindowATag(window)
+
+    const anchor = document.createElement('a')
+    anchor.href = 'https://example.com/detail'
+    anchor.target = '_blank'
+
+    const span = document.createElement('span')
+    anchor.appendChild(span)
+    document.body.appendChild(anchor)
+
+    // Simulate an app-level handler that cancels the click before the polyfill sees it.
+    span.addEventListener('click', ev => {
+      ev.preventDefault()
+    })
+
+    span.dispatchEvent(
+      new MouseEvent('click', { bubbles: true, cancelable: true }),
+    )
+
+    expect(openSpy).not.toHaveBeenCalled()
+  })
+})

package/src/scene-polyfill.ts

@@ -1,4 +1,5 @@
-import { createSpatialSceneCommand, FocusScene } from './JSBCommand'
+import { FocusScene } from './JSBCommand'
+import { openSpatialSceneSync } from './spatial-host'
 import { SpatialScene } from './SpatialScene'
 import {
   SpatialSceneCreationOptions,
@@ -221,8 +222,12 @@ class SceneManager {
       cfg = { ...ans, type: 'window' }
     }
 
-    const cmd = new createSpatialSceneCommand(url!, cfg, target, features)
-    const result = cmd.executeSync()
+    const result = openSpatialSceneSync(
+      url!,
+      cfg as SpatialSceneCreationOptionsInternal,
+      target,
+      features,
+    )
 
     const id = result.data?.id
 
@@ -429,8 +434,6 @@ export function formatSceneConfig(
   // defaultSize should format into px if window
   // defaultSize should format into m if volume
 
-  const defaultSceneConfig = getSceneDefaultConfig(sceneType)
-
   const errors: string[] = []
 
   const isWindow = sceneType === 'window'
@@ -523,23 +526,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
@@ -548,18 +550,17 @@ 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
   }
 }
 

package/src/spatial-host.ts

@@ -0,0 +1,25 @@
+import type { WebSpatialProtocolResult } from './platform-adapter/interface'
+import { getPlatform, getPlatformSync } from './platform-runtime'
+import type { SpatialSceneCreationOptionsInternal } from './types/internal'
+import type { AttachmentEntityOptions } from './types/types'
+
+export async function createNativeSpatialDiv(): Promise<WebSpatialProtocolResult> {
+  const platform = await getPlatform()
+  return platform.createNativeSpatialDiv()
+}
+
+export async function createNativeAttachment(
+  options: AttachmentEntityOptions,
+): Promise<WebSpatialProtocolResult> {
+  const platform = await getPlatform()
+  return platform.createNativeAttachment(options)
+}
+
+export function openSpatialSceneSync(
+  url: string,
+  config: SpatialSceneCreationOptionsInternal | undefined,
+  target?: string,
+  features?: string,
+): WebSpatialProtocolResult {
+  return getPlatformSync().openSpatialSceneSync(url, config, target, features)
+}

package/src/types/{global.d.ts → global.ts}

@@ -1,7 +1,8 @@
 import type { PhysicalMetricsValueShape } from '../physicalMetrics'
+import type { SpatialSceneCreationOptions, SpatialSceneType } from './types'
 
 declare global {
-  declare const __WEBSPATIAL_CORE_SDK_VERSION__: string
+  const __WEBSPATIAL_CORE_SDK_VERSION__: string
 
   interface Window {
     xrCurrentSceneType: SpatialSceneType
@@ -41,13 +42,17 @@ declare global {
       physicalMetrics?: PhysicalMetricsValueShape
     }
 
-    xrInnerDepth: number
-    xrOuterDepth: number
+    /** Present when `supports('xrInnerDepth')` is true; otherwise `undefined`. */
+    xrInnerDepth?: number
+    /** Present when `supports('xrOuterDepth')` is true; otherwise `undefined`. */
+    xrOuterDepth?: number
   }
 
   interface HTMLElement {
-    xrOffsetBack: number
-    xrClientDepth: number
+    /** Present when `supports('xrOffsetBack')` is true for element readbacks. */
+    xrOffsetBack?: number
+    /** Present when `supports('xrClientDepth')` is true for element readbacks. */
+    xrClientDepth?: number
   }
 }
 

package/src/types/types.ts

@@ -100,6 +100,8 @@ export interface ModelSource {
   type?: string
 }
 
+export type ModelLoadingMode = 'eager' | 'lazy'
+
 export interface SpatializedStatic3DElementProperties
   extends SpatializedElementProperties {
   modelURL: string
@@ -109,6 +111,9 @@ export interface SpatializedStatic3DElementProperties
   loop?: boolean
   animationPaused?: boolean
   playbackRate?: number
+  currentTime?: number
+  posterURL?: string
+  loading?: ModelLoadingMode
 }
 
 export interface SpatialSceneCreationOptions {
@@ -262,6 +267,10 @@ export interface SpatialUnlitMaterialOptions {
   opacity?: number
 }
 
+export interface SpatialTextureResourceOptions {
+  url: string
+}
+
 export interface ModelComponentOptions {
   mesh: SpatialGeometry
   materials: SpatialMaterial[]

package/src/platform-adapter/android/AndroidPlatform.ts

@@ -1,133 +0,0 @@
-import { PlatformAbility, CommandResult } from '../interface'
-import {
-  CommandResultFailure,
-  CommandResultSuccess,
-} from '../CommandResultUtils'
-import { CheckWebViewCanCreateCommand } from '../../JSBCommand'
-import { SpatialWebEvent } from '../../SpatialWebEvent'
-
-interface JSBResponse {
-  success: boolean
-  data: any
-}
-type JSBError = {
-  code: string
-  message: string
-}
-
-let creatingElementCount = 0
-
-let requestId = 0
-
-const MAX_ID = 100000
-
-function nextRequestId() {
-  requestId = (requestId + 1) % MAX_ID
-  return `rId_${requestId}`
-}
-
-export class AndroidPlatform implements PlatformAbility {
-  async callJSB(cmd: string, msg: string): Promise<CommandResult> {
-    // android JS Bridge interface only support sync invoking
-    // in order to implement promise API, register every request by requestId and remove when resolve/reject.
-    return new Promise((resolve, reject) => {
-      try {
-        const rId = nextRequestId()
-
-        SpatialWebEvent.addEventReceiver(rId, (result: JSBResponse) => {
-          SpatialWebEvent.removeEventReceiver(rId)
-          if (result.success) {
-            resolve(CommandResultSuccess(result.data))
-          } else {
-            const { code, message } = result.data as JSBError
-            resolve(CommandResultFailure(code, message))
-          }
-        })
-
-        const ans = window.webspatialBridge.postMessage(rId, cmd, msg)
-        if (ans !== '') {
-          SpatialWebEvent.removeEventReceiver(rId)
-          // sync call
-          const result = JSON.parse(ans) as JSBResponse
-          if (result.success) {
-            resolve(CommandResultSuccess(result.data))
-          } else {
-            const { code, message } = result.data as JSBError
-            resolve(CommandResultFailure(code, message))
-          }
-        }
-      } catch (error: unknown) {
-        console.error(
-          `AndroidPlatform cmd: ${cmd}, msg: ${msg} error: ${error}`,
-        )
-        const { code, message } = error as JSBError
-        resolve(CommandResultFailure(code, message))
-      }
-    })
-  }
-
-  async callWebSpatialProtocol(
-    command: string,
-    query?: string,
-    target?: string,
-    features?: string,
-  ): Promise<CommandResult> {
-    // Waiting for request to create spatial div
-    await new Promise(resolve => setTimeout(resolve, 16 * creatingElementCount))
-    // Count the current total number of created spatial div queues
-    creatingElementCount++
-    // Create a spatial div through JSB polling request
-    let canCreate = await new CheckWebViewCanCreateCommand().execute()
-    while (!canCreate.data.can) {
-      await new Promise(resolve => setTimeout(resolve, 16))
-      canCreate = await new CheckWebViewCanCreateCommand().execute()
-    }
-    // Request successful, call window.open
-    const { windowProxy } = this.openWindow(command, query, target, features)
-    // Polling waiting for windowProxy to convert into a real window object
-    while (!windowProxy?.open) {
-      await new Promise(resolve => setTimeout(resolve, 16))
-    }
-    // Make the page renderable through window.open
-    windowProxy?.open('about:blank', '_self')
-    // Polling to check if SpatialId injection is successful
-    while (!windowProxy?.__SpatialId) {
-      await new Promise(resolve => setTimeout(resolve, 16))
-    }
-    let spatialId = windowProxy?.__SpatialId
-    creatingElementCount--
-    return Promise.resolve(
-      CommandResultSuccess({ windowProxy: windowProxy, id: spatialId }),
-    )
-  }
-
-  callWebSpatialProtocolSync(
-    command: string,
-    query?: string,
-    target?: string,
-    features?: string,
-  ): CommandResult {
-    const { spatialId: id = '', windowProxy } = this.openWindow(
-      command,
-      query,
-      target,
-      features,
-    )
-
-    return CommandResultSuccess({ windowProxy, id })
-  }
-
-  private openWindow(
-    command: string,
-    query?: string,
-    target?: string,
-    features?: string,
-  ) {
-    const windowProxy = window.open(
-      `webspatial://${command}?${query || ''}`,
-      target,
-      features,
-    )
-    return { spatialId: '', windowProxy }
-  }
-}