@webspatial/core-sdk 1.6.1 → 2.0.0

package/src/runtime/supports.test.ts

@@ -0,0 +1,346 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+describe('getRuntime / supports', () => {
+  beforeEach(() => {
+    vi.resetModules()
+  })
+
+  test('plain browser: no shell token → supports is false', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X) AppleWebKit/537.36 Chrome/120.0.0.0 Safari/537.36',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('Model')).toBe(false)
+    expect(supports('useMetrics')).toBe(false)
+  })
+
+  test('like Quest without Pico tokens does not force picoos (WSAppShell + no Mac → type null)', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (X11; Linux x86_64; unknown OS0.11.0 like Quest) AppleWebKit/537.36 WSAppShell/1.5.0 WebSpatial/1.5.0',
+    } as Navigator)
+    const { supports, getRuntime, resetRuntimeCacheForTests } = await import(
+      './supports'
+    )
+    resetRuntimeCacheForTests()
+    const rt = getRuntime()
+    expect(rt.type).toBe(null)
+    expect(rt.shellVersion).toBe('1.5.0')
+    expect(supports('Model')).toBe(false)
+  })
+
+  test('WSAppShell without Mac OS X: not visionos; spatial supports false', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 WSAppShell/9.9.9 WebSpatial/1.5.0',
+    } as Navigator)
+    const { supports, getRuntime, resetRuntimeCacheForTests } = await import(
+      './supports'
+    )
+    resetRuntimeCacheForTests()
+    const rt = getRuntime()
+    expect(rt.type).toBe(null)
+    expect(rt.shellVersion).toBe('9.9.9')
+    expect(supports('Model')).toBe(false)
+  })
+
+  test('visionOS UA with WSAppShell: resolves and Model can be true (stub table)', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7; wv) AppleWebKit/605.1.15 (KHTML, like Gecko) WSAppShell/1.5.0 WebSpatial/1.5.0 Safari/537.36',
+    } as Navigator)
+    const { supports, getRuntime, resetRuntimeCacheForTests } = await import(
+      './supports'
+    )
+    resetRuntimeCacheForTests()
+    const rt = getRuntime()
+    expect(rt.type).toBe('visionos')
+    expect(rt.shellVersion).toBe('1.5.0')
+    expect(supports('Model')).toBe(true)
+    expect(supports('xrInnerDepth')).toBe(true)
+    expect(supports('xrOuterDepth')).toBe(true)
+    expect(supports('UnknownThing' as any)).toBe(false)
+  })
+
+  test('pico UA: type picoos; matrix 0.1.1 sub-tokens (alpha2.0 baseline)', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (X11; Linux x86_64; unknown OS0.11.0 like Quest) AppleWebKit/537.36 PicoWebApp/0.1.1 (like PicoBrowser) Chrome/138.0 WebSpatial/1.5.0',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('initScene')).toBe(true)
+    expect(supports('Model', ['not-a-token' as any])).toBe(false)
+    expect(supports('Model', ['source'])).toBe(false)
+    expect(supports('Model', ['ready', 'currentSrc'])).toBe(true)
+    expect(supports('Model', ['stagemode'])).toBe(false)
+    expect(supports('WindowScene', ['defaultSize', 'resizability'])).toBe(true)
+    expect(supports('xrInnerDepth')).toBe(false)
+    expect(supports('xrOuterDepth')).toBe(false)
+  })
+
+  test('pico UA PicoWebApp/0.1.2: matrix playback row (beta2.0)', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (X11; Linux x86_64; unknown OS0.11.0 like Quest) AppleWebKit/537.36 PicoWebApp/0.1.2 (like PicoBrowser) Chrome/138.0 WebSpatial/1.5.0',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('Model', ['autoplay', 'loop', 'source'])).toBe(true)
+    expect(supports('Model', ['currentTime'])).toBe(true)
+    expect(supports('Model', ['poster'])).toBe(true)
+    expect(supports('Model', ['loading'])).toBe(false)
+    expect(supports('xrInnerDepth')).toBe(false)
+    expect(supports('xrOuterDepth')).toBe(false)
+  })
+
+  test('pico UA PicoWebApp/0.3.1: beta2.1 enables Model loading', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (X11; Linux x86_64; unknown OS0.11.0 like Quest) AppleWebKit/537.36 PicoWebApp/0.3.1 (like PicoBrowser) Chrome/138.0 WebSpatial/1.5.0',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('Model', ['currentTime', 'poster', 'loading'])).toBe(true)
+    expect(supports('Model', ['stagemode'])).toBe(false)
+    expect(supports('useAnimation')).toBe(false)
+    expect(supports('useAnimation', ['entity'])).toBe(false)
+    expect(supports('xrInnerDepth')).toBe(false)
+    expect(supports('xrOuterDepth')).toBe(false)
+  })
+
+  test('pico UA above PicoWebApp/0.3.1 keeps its capabilities before OTA0', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (X11; Linux x86_64; unknown OS0.11.0 like Quest) AppleWebKit/537.36 PicoWebApp/0.3.2 (like PicoBrowser) Chrome/138.0 WebSpatial/1.5.0',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('Model', ['currentTime', 'poster', 'loading'])).toBe(true)
+    expect(supports('useAnimation')).toBe(false)
+    expect(supports('useAnimation', ['entity'])).toBe(false)
+  })
+
+  test('alias Box → BoxEntity', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 WSAppShell/1.5.0 WebSpatial/1.5.0',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('Box')).toBe(supports('BoxEntity'))
+  })
+
+  test('supports(name, []) ≡ supports(name)', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 WSAppShell/1.5.0 WebSpatial/1.5.0',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('Reality')).toBe(supports('Reality', []))
+  })
+
+  test('initScene is top-level only; WindowScene / VolumeScene sub-tokens', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 WSAppShell/1.5.0 WebSpatial/1.5.0',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('initScene')).toBe(true)
+    expect(supports('initScene', ['defaultSize' as any])).toBe(false)
+    expect(supports('WindowScene')).toBe(true)
+    expect(supports('WindowScene', ['defaultSize', 'resizability'])).toBe(true)
+    expect(supports('VolumeScene', ['baseplateVisibility'])).toBe(true)
+  })
+
+  test('Puppeteer UA: type puppeteer; all valid supports() true', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Puppeteer WSAppShell/1.5.0 WebSpatial/1.5.0',
+    } as Navigator)
+    const { supports, getRuntime, resetRuntimeCacheForTests } = await import(
+      './supports'
+    )
+    resetRuntimeCacheForTests()
+    const rt = getRuntime()
+    expect(rt.type).toBe('puppeteer')
+    expect(rt.shellVersion).toBe('1.5.0')
+    expect(supports('Model')).toBe(true)
+    expect(supports('Model', ['poster'])).toBe(true)
+    expect(supports('UnknownThing' as any)).toBe(false)
+    expect(supports('Model', ['not-a-token' as any])).toBe(false)
+  })
+
+  test('Puppeteer UA without shell token: still puppeteer; valid supports() true', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent: 'Mozilla/5.0 Puppeteer HeadlessChrome/120.0.0.0',
+    } as Navigator)
+    const { supports, getRuntime, resetRuntimeCacheForTests } = await import(
+      './supports'
+    )
+    resetRuntimeCacheForTests()
+    expect(getRuntime().type).toBe('puppeteer')
+    expect(getRuntime().shellVersion).toBe(null)
+    expect(supports('Model')).toBe(true)
+  })
+
+  test('visionOS WS_SHELL_VERSION placeholder: debug mode; all valid supports() true', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7; wv) AppleWebKit/605.1.15 WSAppShell/WS_SHELL_VERSION WebSpatial/1.5.0 Safari/537.36',
+    } as Navigator)
+    const { supports, getRuntime, resetRuntimeCacheForTests } = await import(
+      './supports'
+    )
+    resetRuntimeCacheForTests()
+    const rt = getRuntime()
+    expect(rt.type).toBe('visionos')
+    expect(rt.shellVersion).toBe('WS_SHELL_VERSION')
+    expect(supports('Model')).toBe(true)
+    expect(supports('Model', ['poster'])).toBe(true)
+    expect(supports('Model', ['stagemode'])).toBe(true)
+    expect(supports('UnknownThing' as any)).toBe(false)
+    expect(supports('Model', ['not-a-token' as any])).toBe(false)
+  })
+
+  test('visionOS WSAppShell/1.5.0: Model sub-tokens (alpha2.0 baseline)', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 WSAppShell/1.5.0 WebSpatial/1.5.0',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('Model', ['autoplay'])).toBe(false)
+    expect(supports('Model', ['poster'])).toBe(false)
+    expect(supports('Model', ['ready', 'currentSrc'])).toBe(true)
+    expect(supports('Model', ['currentTime'])).toBe(false)
+  })
+
+  test('visionOS WSAppShell/1.6.0: Model playback row (WebSpatial April)', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7; wv) AppleWebKit/605.1.15 (KHTML, like Gecko) WSAppShell/1.6.0 WebSpatial/1.5.0 Safari/537.36',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('Model', ['autoplay', 'loop', 'source'])).toBe(true)
+    expect(supports('Model', ['currentTime'])).toBe(false)
+    expect(supports('Model', ['poster'])).toBe(false)
+    expect(supports('Model', ['play', 'pause', 'duration'])).toBe(true)
+  })
+
+  test('visionOS WSAppShell/1.7.0: Model currentTime, loading, and poster are supported', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7; wv) AppleWebKit/605.1.15 (KHTML, like Gecko) WSAppShell/1.7.0 WebSpatial/1.5.0 Safari/537.36',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('Model', ['currentTime', 'loading', 'poster'])).toBe(true)
+    expect(supports('Model', ['stagemode'])).toBe(false)
+    expect(supports('useAnimation')).toBe(false)
+    expect(supports('useAnimation', ['entity'])).toBe(false)
+  })
+
+  test('visionOS WSAppShell/1.8.0: useAnimation is true while sub-tokens are false', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7; wv) AppleWebKit/605.1.15 WSAppShell/1.8.0 WebSpatial/1.5.0 Safari/537.36',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('useAnimation')).toBe(true)
+    expect(supports('useAnimation', ['entity'])).toBe(false)
+    expect(supports('useAnimation', ['element'])).toBe(false)
+  })
+
+  test('useAnimation rejects all sub-tokens', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7; wv) AppleWebKit/605.1.15 WSAppShell/1.7.0 WebSpatial/1.5.0 Safari/537.36',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('useAnimation')).toBe(false)
+    expect(supports('useAnimation', ['entity'])).toBe(false)
+    expect(supports('useAnimation', ['element'])).toBe(false)
+    expect(supports('useAnimation', ['static3d'])).toBe(false)
+    expect(supports('useAnimation', ['dynamic3d'])).toBe(false)
+
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 WSAppShell/1.5.0 WebSpatial/1.5.0',
+    } as Navigator)
+    const mod2 = await import('./supports')
+    mod2.resetRuntimeCacheForTests()
+    expect(mod2.supports('useAnimation')).toBe(false)
+    expect(mod2.supports('useAnimation', ['entity'])).toBe(false)
+    expect(mod2.supports('useAnimation', ['element'])).toBe(false)
+  })
+
+  test('useAnimation result is stable across repeated calls', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7; wv) AppleWebKit/605.1.15 WSAppShell/1.8.0 WebSpatial/1.5.0 Safari/537.36',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    const first = supports('useAnimation')
+    const second = supports('useAnimation')
+    const third = supports('useAnimation')
+    expect(first).toBe(true)
+    expect(second).toBe(true)
+    expect(third).toBe(true)
+  })
+})
+
+describe('supports("useAnimation") for motion', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  test('visionOS WSAppShell/1.8.0: useAnimation is true while sub-tokens are false', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7; wv) AppleWebKit/605.1.15 WSAppShell/1.8.0 WebSpatial/1.5.0 Safari/537.36',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('useAnimation')).toBe(true)
+    expect(supports('useAnimation', [])).toBe(true)
+    expect(supports('useAnimation', ['entity'])).toBe(false)
+    expect(supports('useAnimation', ['element'])).toBe(false)
+    expect(supports('useAnimation', ['static3d'])).toBe(false)
+    expect(supports('useAnimation', ['dynamic3d'])).toBe(false)
+  })
+
+  test('visionOS WSAppShell/1.7.0: useAnimation and sub-tokens are false', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7; wv) AppleWebKit/605.1.15 WSAppShell/1.7.0 WebSpatial/1.5.0 Safari/537.36',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('useAnimation')).toBe(false)
+    expect(supports('useAnimation', [])).toBe(false)
+    expect(supports('useAnimation', ['entity'])).toBe(false)
+    expect(supports('useAnimation', ['element'])).toBe(false)
+    expect(supports('useAnimation', ['static3d'])).toBe(false)
+    expect(supports('useAnimation', ['dynamic3d'])).toBe(false)
+  })
+
+  test('visionOS WSAppShell/1.6.0: element token remains false', async () => {
+    vi.stubGlobal('navigator', {
+      userAgent:
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7; wv) AppleWebKit/605.1.15 WSAppShell/1.6.0 WebSpatial/1.5.0 Safari/537.36',
+    } as Navigator)
+    const { supports, resetRuntimeCacheForTests } = await import('./supports')
+    resetRuntimeCacheForTests()
+    expect(supports('useAnimation')).toBe(false)
+    expect(supports('useAnimation', ['element'])).toBe(false)
+  })
+})

package/src/runtime/supports.ts

@@ -0,0 +1,112 @@
+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
+}