@webspatial/core-sdk 1.6.0 → 1.7.0

package/src/runtime/capability-data.ts

@@ -0,0 +1,113 @@
+/**
+ * Versioned capability rows transcribed from the product matrix (`capability-matrix.template.md`).
+ * visionOS **WSAppShell/1.5.0** & **1.6.0**; picoOS **PicoWebApp/0.1.1** & **0.1.2** — see matrix in OpenSpec / product docs.
+ *
+ * **picoOS** rows use dedicated builders (alpha2.0 / alpha2.1 subtokens); visionOS rows are separate.
+ */
+import { SUB_TOKENS_BY_NAME, TOP_LEVEL_KEYS } from './keys'
+
+export type CapabilityVersionRow = {
+  /** Semver string from `WSAppShell` / `PicoWebApp` (see `review.md` §4). */
+  version: string
+  /** Top-level keys and `name:subToken` compound keys. */
+  flags: Record<string, boolean>
+}
+
+function baseTrueFlags(): Record<string, boolean> {
+  const flags: Record<string, boolean> = {}
+  for (const k of TOP_LEVEL_KEYS) {
+    flags[k] = true
+  }
+  for (const [name, toks] of Object.entries(SUB_TOKENS_BY_NAME)) {
+    for (const t of toks) {
+      flags[`${name}:${t}`] = true
+    }
+  }
+  return flags
+}
+
+/**
+ * visionOS **WSAppShell/1.5.0**.
+ * Model: only `ready`, `currentSrc`, `entityTransform` among tracked sub-tokens are Y; SpatialRotateEvent:constrainedToAxis Y.
+ */
+function matrixVision_1_5_0_Flags(): Record<string, boolean> {
+  const flags = baseTrueFlags()
+  const modelNo = [
+    'autoplay',
+    'loop',
+    'stagemode',
+    'poster',
+    'loading',
+    'source',
+    'paused',
+    'duration',
+    'playbackRate',
+    'play',
+    'pause',
+    'currentTime',
+  ] as const
+  for (const t of modelNo) {
+    flags[`Model:${t}`] = false
+  }
+  flags['SpatialRotateEvent:constrainedToAxis'] = true
+  return flags
+}
+
+/**
+ * visionOS **WSAppShell/1.6.0** — WebSpatial April / playback expansion (see product matrix).
+ * Model: `stagemode`, `poster`, `loading`, `currentTime` remain N; rest of tracked Model sub-tokens Y.
+ */
+function matrixVision_1_6_0_Flags(): Record<string, boolean> {
+  const flags = baseTrueFlags()
+  for (const t of ['stagemode', 'poster', 'loading', 'currentTime'] as const) {
+    flags[`Model:${t}`] = false
+  }
+  flags['SpatialRotateEvent:constrainedToAxis'] = true
+  return flags
+}
+
+/**
+ * picoOS **PicoWebApp/0.1.1** — alpha2.0 baseline (product matrix).
+ * WindowScene / VolumeScene / Material subtokens Y; Model sub-tokens per matrix; **`xrInnerDepth` / `xrOuterDepth` N**.
+ */
+function matrixPico_0_1_1_Flags(): Record<string, boolean> {
+  const flags = matrixVision_1_5_0_Flags()
+  flags.xrInnerDepth = false
+  flags.xrOuterDepth = false
+  return flags
+}
+
+/**
+ * picoOS **PicoWebApp/0.1.2** — alpha2.1 playback expansion (product matrix).
+ * **`xrInnerDepth` / `xrOuterDepth` N** (same as 0.1.1).
+ */
+function matrixPico_0_1_2_Flags(): Record<string, boolean> {
+  const flags = matrixVision_1_6_0_Flags()
+  flags.xrInnerDepth = false
+  flags.xrOuterDepth = false
+  return flags
+}
+
+function visionOsRow_1_5_0(): CapabilityVersionRow {
+  return { version: '1.5.0', flags: matrixVision_1_5_0_Flags() }
+}
+
+function visionOsRow_1_6_0(): CapabilityVersionRow {
+  return { version: '1.6.0', flags: matrixVision_1_6_0_Flags() }
+}
+
+function picoOsRow_0_1_1(): CapabilityVersionRow {
+  return { version: '0.1.1', flags: matrixPico_0_1_1_Flags() }
+}
+
+function picoOsRow_0_1_2(): CapabilityVersionRow {
+  return { version: '0.1.2', flags: matrixPico_0_1_2_Flags() }
+}
+
+export const CAPABILITY_TABLE: {
+  visionos: CapabilityVersionRow[]
+  picoos: CapabilityVersionRow[]
+} = {
+  visionos: [visionOsRow_1_5_0(), visionOsRow_1_6_0()],
+  picoos: [picoOsRow_0_1_1(), picoOsRow_0_1_2()],
+}

package/src/runtime/contract-review.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test, vi, beforeEach } from 'vitest'
+import { ELEMENT_DOM_DEPTH_KEYS, WINDOW_DOM_DEPTH_KEYS } from './keys'
+
+describe('OpenSpec review.md §3.5.1 — Window DOM depth (xrInnerDepth / xrOuterDepth)', () => {
+  beforeEach(() => {
+    vi.resetModules()
+  })
+
+  test('plain browser UA: unsupported keys absent from window surface', 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()
+
+    for (const key of WINDOW_DOM_DEPTH_KEYS) {
+      expect(supports(key)).toBe(false)
+      expect(key in window).toBe(false)
+      expect(Object.prototype.hasOwnProperty.call(window, key)).toBe(false)
+    }
+  })
+})
+
+describe('OpenSpec review.md §3.5.2 — Element depth keys must not use Window surface', () => {
+  beforeEach(() => {
+    vi.resetModules()
+  })
+
+  test('plain browser: xrClientDepth / xrOffsetBack are not on window (live on spatialized ref)', 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()
+
+    for (const key of ELEMENT_DOM_DEPTH_KEYS) {
+      expect(supports(key)).toBe(false)
+      expect(key in window).toBe(false)
+      expect(Object.prototype.hasOwnProperty.call(window, key)).toBe(false)
+    }
+  })
+})

package/src/runtime/index.ts

@@ -0,0 +1,28 @@
+export type { WebSpatialRuntimeSnapshot, WebSpatialRuntimeType } from './types'
+export { WebSpatialRuntimeError } from './WebSpatialRuntimeError'
+export {
+  supports,
+  getRuntime,
+  resetRuntimeCacheForTests,
+  VISIONOS_DEBUG_SHELL_VERSION_PLACEHOLDER,
+} from './supports'
+export { compareSemver, parseSemverOrNull } from './semver'
+export { computeRuntimeFromUserAgent, parseShellToken } from './userAgent'
+export {
+  resolveJsbAdapterPlatform,
+  type JsbAdapterPlatformKind,
+} from './jsbAdapterPlatform'
+export type { CapabilityVersionRow } from './capability-data'
+export { CAPABILITY_TABLE } from './capability-data'
+export type { CapabilityKey } from './keys'
+export {
+  TOP_LEVEL_KEYS,
+  SUB_TOKENS_BY_NAME,
+  COMPONENT_KEYS,
+  CSS_KEYS,
+  GESTURE_KEYS,
+  JS_SCENE_KEYS,
+  DOM_DEPTH_KEYS,
+  ELEMENT_DOM_DEPTH_KEYS,
+  WINDOW_DOM_DEPTH_KEYS,
+} from './keys'

package/src/runtime/jsbAdapterPlatform.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from 'vitest'
+import { resolveJsbAdapterPlatform } from './jsbAdapterPlatform'
+
+describe('resolveJsbAdapterPlatform', () => {
+  test('Puppeteer UA maps to puppeteer', () => {
+    expect(
+      resolveJsbAdapterPlatform(
+        'Mozilla/5.0 Puppeteer Chrome/120 WSAppShell/1.5.0 WebSpatial/1.5.0',
+      ),
+    ).toBe('puppeteer')
+  })
+
+  test('PicoWebApp with WebSpatial > 0.0.1 maps to picoos', () => {
+    expect(
+      resolveJsbAdapterPlatform(
+        'Mozilla/5.0 PicoWebApp/0.1.1 WebSpatial/1.5.0',
+      ),
+    ).toBe('picoos')
+  })
+
+  test('Linux without Pico pico branch maps to visionos', () => {
+    expect(
+      resolveJsbAdapterPlatform(
+        'Mozilla/5.0 (X11; Linux x86_64) WSAppShell/1.5.0 WebSpatial/1.5.0',
+      ),
+    ).toBe('visionos')
+  })
+
+  test('Mac visionOS-class UA maps to visionos', () => {
+    expect(
+      resolveJsbAdapterPlatform(
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) WSAppShell/1.5.0 WebSpatial/1.5.0',
+      ),
+    ).toBe('visionos')
+  })
+})

package/src/runtime/jsbAdapterPlatform.ts

@@ -0,0 +1,51 @@
+import { computeRuntimeFromUserAgent } from './userAgent'
+
+function getWebSpatialVersion(ua: string): number[] | null {
+  const match = ua.match(/WebSpatial\/(\d+)\.(\d+)\.(\d+)/)
+  if (!match) {
+    return null
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3])]
+}
+
+function isVersionGreater(a: number[] | null, b: number[]): boolean {
+  if (!a) {
+    return false
+  }
+  for (let index = 0; index < 3; index += 1) {
+    const diff = a[index] - b[index]
+    if (diff > 0) {
+      return true
+    }
+    if (diff < 0) {
+      return false
+    }
+  }
+  return false
+}
+
+/**
+ * Which native JSB / protocol adapter to load in the browser.
+ * Derived from {@link computeRuntimeFromUserAgent} plus legacy fallbacks
+ * (Pico WebSpatial semver gate; otherwise default visionOS shell).
+ */
+export type JsbAdapterPlatformKind = 'puppeteer' | 'picoos' | 'visionos'
+
+export function resolveJsbAdapterPlatform(
+  userAgent: string,
+): JsbAdapterPlatformKind {
+  const rt = computeRuntimeFromUserAgent(userAgent)
+  if (rt.type === 'puppeteer') {
+    return 'puppeteer'
+  }
+
+  const webSpatialVersion = getWebSpatialVersion(userAgent)
+  if (
+    userAgent.includes('PicoWebApp') &&
+    isVersionGreater(webSpatialVersion, [0, 0, 1])
+  ) {
+    return 'picoos'
+  }
+
+  return 'visionos'
+}

package/src/runtime/keys.ts

@@ -0,0 +1,129 @@
+/**
+ * Canonical `supports(name)` keys (OpenSpec `review.md` §3).
+ * Aliases are normalized before lookup (see `normalizeCapabilityName`).
+ */
+
+export const COMPONENT_KEYS = [
+  'Model',
+  'Reality',
+  'Entity',
+  'BoxEntity',
+  'SphereEntity',
+  'ConeEntity',
+  'CylinderEntity',
+  'PlaneEntity',
+  'SceneGraph',
+  'ModelAsset',
+  'ModelEntity',
+  'UnlitMaterial',
+  'Material',
+  'AttachmentAsset',
+  'AttachmentEntity',
+] as const
+
+export const CSS_KEYS = [
+  '-xr-background-material',
+  '-xr-back',
+  '-xr-depth',
+  '-xr-transform',
+] as const
+
+export const GESTURE_KEYS = [
+  'SpatialTapEvent',
+  'SpatialDragStartEvent',
+  'SpatialDragEvent',
+  'SpatialDragEndEvent',
+  'SpatialRotateEvent',
+  'SpatialRotateEndEvent',
+  'SpatialMagnifyEvent',
+  'SpatialMagnifyEndEvent',
+] as const
+
+export const JS_SCENE_KEYS = [
+  'useMetrics',
+  'convertCoordinate',
+  'initScene',
+  'WindowScene',
+  'VolumeScene',
+] as const
+
+/**
+ * Spatialized container `ref` readbacks (`HTMLElement` / React `useDomProxy` Proxy).
+ * See `global.d.ts` (`HTMLElement`) and `useDomProxy.ts` (`has` / `get` traps).
+ */
+export const ELEMENT_DOM_DEPTH_KEYS = ['xrClientDepth', 'xrOffsetBack'] as const
+
+/**
+ * Scene / global readbacks on `Window` (`global.d.ts` → `Window`).
+ */
+export const WINDOW_DOM_DEPTH_KEYS = ['xrInnerDepth', 'xrOuterDepth'] as const
+
+export const DOM_DEPTH_KEYS = [
+  ...ELEMENT_DOM_DEPTH_KEYS,
+  ...WINDOW_DOM_DEPTH_KEYS,
+] as const
+
+/** Top-level names accepted by `supports(name)` (canonical keys after alias normalization). */
+export const TOP_LEVEL_KEYS = [
+  ...COMPONENT_KEYS,
+  ...CSS_KEYS,
+  ...GESTURE_KEYS,
+  ...JS_SCENE_KEYS,
+  ...DOM_DEPTH_KEYS,
+] as const
+
+/** Union of documented capability keys; unknown strings may still be passed to `supports` (returns `false`). */
+export type CapabilityKey = (typeof TOP_LEVEL_KEYS)[number]
+
+const ALIAS_TO_CANONICAL: Record<string, string> = {
+  Box: 'BoxEntity',
+  Sphere: 'SphereEntity',
+  Cone: 'ConeEntity',
+  Cylinder: 'CylinderEntity',
+  Plane: 'PlaneEntity',
+  World: 'SceneGraph',
+}
+
+export function normalizeCapabilityName(name: string): string {
+  return ALIAS_TO_CANONICAL[name] ?? name
+}
+
+/** Known sub-tokens per canonical top-level `name` (AND semantics). */
+export const SUB_TOKENS_BY_NAME: Readonly<Record<string, readonly string[]>> = {
+  Material: ['unlit'],
+  WindowScene: ['defaultSize', 'resizability'],
+  VolumeScene: [
+    'defaultSize',
+    'resizability',
+    'worldScaling',
+    'worldAlignment',
+    'baseplateVisibility',
+  ],
+  SpatialRotateEvent: ['constrainedToAxis'],
+  Model: [
+    'autoplay',
+    'loop',
+    'stagemode',
+    'poster',
+    'loading',
+    'source',
+    'ready',
+    'currentSrc',
+    'entityTransform',
+    'paused',
+    'duration',
+    'playbackRate',
+    'play',
+    'pause',
+    'currentTime',
+  ],
+}
+
+export function isKnownTopLevel(name: string): boolean {
+  return (TOP_LEVEL_KEYS as readonly string[]).includes(name)
+}
+
+export function isKnownSubToken(name: string, token: string): boolean {
+  const allowed = SUB_TOKENS_BY_NAME[name]
+  return allowed !== undefined && allowed.includes(token)
+}

package/src/runtime/semver.ts

@@ -0,0 +1,33 @@
+/**
+ * Minimal semver compare for capability table rows (`major.minor.patch`).
+ * Returns negative if a < b, zero if equal, positive if a > b.
+ */
+export function compareSemver(a: string, b: string): number {
+  const pa = parseSemverParts(a)
+  const pb = parseSemverParts(b)
+  if (!pa || !pb) {
+    return String(a).localeCompare(String(b))
+  }
+  const len = Math.max(pa.length, pb.length)
+  for (let i = 0; i < len; i++) {
+    const da = pa[i] ?? 0
+    const db = pb[i] ?? 0
+    if (da !== db) return da - db
+  }
+  return 0
+}
+
+function parseSemverParts(v: string): number[] | null {
+  const m = /^(\d+)(?:\.(\d+)(?:\.(\d+))?)?/.exec(v.trim())
+  if (!m) return null
+  const major = Number(m[1])
+  const minor = m[2] !== undefined ? Number(m[2]) : 0
+  const patch = m[3] !== undefined ? Number(m[3]) : 0
+  if ([major, minor, patch].some(n => Number.isNaN(n))) return null
+  return [major, minor, patch]
+}
+
+export function parseSemverOrNull(v: string): string | null {
+  const m = /^(\d+(?:\.\d+){0,2})/.exec(v.trim())
+  return m ? m[1] : null
+}

package/src/runtime/supports.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, test, vi, beforeEach } 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 (alpha2.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(false)
+    expect(supports('Model', ['poster'])).toBe(false)
+    expect(supports('xrInnerDepth')).toBe(false)
+    expect(supports('xrOuterDepth')).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)
+  })
+})