@webspatial/core-sdk 1.6.1 → 2.0.0

package/src/runtime/capability-data.ts

@@ -0,0 +1,213 @@
+/**
+ * Versioned capability rows transcribed from the product matrix (`capability-matrix.template.md`).
+ * visionOS **WSAppShell/1.5.0** & **1.6.0** & **1.7.0** & **1.8.0**; picoOS **PicoWebApp/0.1.1** & **0.1.2** & **0.2.2** & **0.3.1** & **0.4.90** — 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
+  // Container useAnimation is not supported until WSAppShell/1.8.0.
+  flags['useAnimation'] = false
+  // Placement-shaped attachment protocol lands in picoOS PicoWebApp/0.4.90
+  // (OTA0); no visionOS shell decodes it yet.
+  flags['AttachmentEntity:placement'] = false
+  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
+  // Container useAnimation is not supported until WSAppShell/1.8.0.
+  flags['useAnimation'] = false
+  // Placement-shaped attachment protocol lands in picoOS PicoWebApp/0.4.90
+  // (OTA0); no visionOS shell decodes it yet.
+  flags['AttachmentEntity:placement'] = false
+  return flags
+}
+
+/**
+ * visionOS **WSAppShell/1.7.0** — entity transform animation support.
+ * Container `useAnimation` remains unavailable in this row.
+ */
+function matrixVision_1_7_0_Flags(): Record<string, boolean> {
+  const flags = matrixVision_1_6_0_Flags()
+  flags['Model:currentTime'] = true
+  flags['Model:loading'] = true
+  flags['Model:poster'] = true
+  return flags
+}
+
+/**
+ * visionOS **WSAppShell/1.8.0**.
+ */
+function matrixVision_1_8_0_Flags(): Record<string, boolean> {
+  const flags = matrixVision_1_7_0_Flags()
+  flags['useAnimation'] = 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** — beta2.0 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
+  flags['Model:currentTime'] = true
+  flags['Model:poster'] = true
+  return flags
+}
+
+/**
+ * picoOS **PicoWebApp/0.2.2** — entity transform animation support.
+ * Container `useAnimation` remains unavailable in this row.
+ */
+function matrixPico_0_2_2_Flags(): Record<string, boolean> {
+  const flags = matrixPico_0_1_2_Flags()
+  return flags
+}
+
+/**
+ * picoOS **PicoWebApp/0.3.1** — beta2.1
+ */
+function matrixPico_0_3_1_Flags(): Record<string, boolean> {
+  const flags = matrixPico_0_2_2_Flags()
+  flags['Model:loading'] = true
+  return flags
+}
+
+/**
+ * picoOS **PicoWebApp/0.4.90** — OTA0 container animation support.
+ */
+function matrixPico_0_4_90_Flags(): Record<string, boolean> {
+  const flags = matrixPico_0_3_1_Flags()
+  flags['useAnimation'] = true
+  flags['AttachmentEntity:placement'] = true
+  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 visionOsRow_1_7_0(): CapabilityVersionRow {
+  return { version: '1.7.0', flags: matrixVision_1_7_0_Flags() }
+}
+
+/**
+ * Build the capability row for visionOS **WSAppShell/1.8.0**.
+ */
+function visionOsRow_1_8_0(): CapabilityVersionRow {
+  return { version: '1.8.0', flags: matrixVision_1_8_0_Flags() }
+}
+
+function picoOsRow_0_1_1(): CapabilityVersionRow {
+  return { version: '0.1.1', flags: matrixPico_0_1_1_Flags() }
+}
+
+// Pico OS 6.0 Beta 2.0
+function picoOsRow_0_1_2(): CapabilityVersionRow {
+  return { version: '0.1.2', flags: matrixPico_0_1_2_Flags() }
+}
+
+function picoOsRow_0_2_2(): CapabilityVersionRow {
+  return { version: '0.2.2', flags: matrixPico_0_2_2_Flags() }
+}
+
+// Pico OS 6.0 Beta 2.1
+function picoOsRow_0_3_1(): CapabilityVersionRow {
+  return { version: '0.3.1', flags: matrixPico_0_3_1_Flags() }
+}
+
+/**
+ * Build the capability row for picoOS **PicoWebApp/0.4.90** OTA0.
+ */
+function picoOsRow_0_4_90(): CapabilityVersionRow {
+  return { version: '0.4.90', flags: matrixPico_0_4_90_Flags() }
+}
+
+export const CAPABILITY_TABLE: {
+  visionos: CapabilityVersionRow[]
+  picoos: CapabilityVersionRow[]
+} = {
+  visionos: [
+    visionOsRow_1_5_0(),
+    visionOsRow_1_6_0(),
+    visionOsRow_1_7_0(),
+    visionOsRow_1_8_0(),
+  ],
+  picoos: [
+    picoOsRow_0_1_1(),
+    picoOsRow_0_1_2(),
+    picoOsRow_0_2_2(),
+    picoOsRow_0_3_1(),
+    picoOsRow_0_4_90(),
+  ],
+}

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,17 @@
+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'

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,140 @@
+/**
+ * Canonical `supports(name)` key registry (OpenSpec `review.md` §3).
+ * Aliases are normalized before lookup (see `normalizeCapabilityName`).
+ *
+ * @internal SDK contract data — not part of the public `@webspatial/react-sdk`
+ * surface. Import via `@webspatial/core-sdk/runtime/keys` only for SDK demos,
+ * contract tests, and capability-matrix tooling.
+ */
+
+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 ANIMATION_KEYS = ['useAnimation'] 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,
+  ...ANIMATION_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'],
+  // Placement-shaped attachment JSB protocol (placementId + Vec3 transform +
+  // meter width/height). Runtimes without it take the legacy payload
+  // (parentEntityId + tuple position + point size).
+  AttachmentEntity: ['placement'],
+  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
+}