@webspatial/core-sdk 1.6.0 → 1.7.0

package/src/coverage-boost.test.ts

@@ -263,115 +263,6 @@ describe('platform adapters', () => {
     vi.unmock('./JSBCommand')
   })
 
-  // it('AndroidPlatform.callJSB resolves from async SpatialWebEvent callback', async () => {
-  //   const postMessage = vi.fn((rId: string) => {
-  //     expect(rId.startsWith('rId_')).toBe(true)
-  //     return ''
-  //   })
-  //   ;(window as any).webspatialBridge = { postMessage }
-
-  //   const { AndroidPlatform } = await import(
-  //     './platform-adapter/android/AndroidPlatform'
-  //   )
-  //   const { SpatialWebEvent: SpatialWebEventInstance } = await import(
-  //     './SpatialWebEvent'
-  //   )
-  //   const platform = new AndroidPlatform()
-  //   const p = platform.callJSB('c', '{"a":1}')
-
-  //   const rId = postMessage.mock.calls[0]?.[0] as string
-  //   SpatialWebEventInstance.eventReceiver[rId]({
-  //     success: true,
-  //     data: { ok: true },
-  //   })
-
-  //   await expect(p).resolves.toEqual({
-  //     success: true,
-  //     data: { ok: true },
-  //     errorCode: '',
-  //     errorMessage: '',
-  //   })
-  // })
-
-  // it('AndroidPlatform.callJSB handles sync bridge response and failures', async () => {
-  //   ;(window as any).webspatialBridge = {
-  //     postMessage: vi.fn(() =>
-  //       JSON.stringify({
-  //         success: false,
-  //         data: { code: 'E_SYNC', message: 'bad' },
-  //       }),
-  //     ),
-  //   }
-
-  //   const { AndroidPlatform } = await import(
-  //     './platform-adapter/android/AndroidPlatform'
-  //   )
-  //   const platform = new AndroidPlatform()
-  //   await expect(platform.callJSB('c', '{}')).resolves.toEqual({
-  //     success: false,
-  //     data: undefined,
-  //     errorCode: 'E_SYNC',
-  //     errorMessage: 'bad',
-  //   })
-  // })
-
-  // it('AndroidPlatform.callWebSpatialProtocol polls and returns injected SpatialId', async () => {
-  //   vi.useFakeTimers()
-
-  //   let canCount = 0
-  //   vi.doMock('./JSBCommand', () => {
-  //     return {
-  //       CheckWebViewCanCreateCommand: vi.fn().mockImplementation(() => ({
-  //         execute: vi.fn().mockImplementation(() => {
-  //           canCount += 1
-  //           return Promise.resolve({
-  //             success: true,
-  //             data: { can: canCount >= 2 },
-  //             errorCode: '',
-  //             errorMessage: '',
-  //           })
-  //         }),
-  //       })),
-  //     }
-  //   })
-
-  //   const windowProxy: any = {}
-  //   const openFn = vi.fn()
-  //   ;(window as any).open = vi.fn(() => windowProxy)
-
-  //   setTimeout(() => {
-  //     windowProxy.open = openFn
-  //   }, 20)
-
-  //   const { AndroidPlatform } = await import(
-  //     './platform-adapter/android/AndroidPlatform'
-  //   )
-  //   const { SpatialWebEvent: SpatialWebEventInstance } = await import(
-  //     './SpatialWebEvent'
-  //   )
-  //   const platform = new AndroidPlatform()
-  //   const p = platform.callWebSpatialProtocol('open', 'x=1', '_blank', '')
-
-  //   const receiverIds = Object.keys(SpatialWebEventInstance.eventReceiver)
-  //   const createdId = receiverIds[0] as string
-  //   const loadedId = receiverIds[1] as string
-  //   SpatialWebEventInstance.eventReceiver[createdId]?.({ spatialId: 'temp' })
-  //   await vi.advanceTimersByTimeAsync(100)
-  //   SpatialWebEventInstance.eventReceiver[loadedId]?.({
-  //     spatialId: 'spatial-1',
-  //   })
-
-  //   await vi.advanceTimersByTimeAsync(200)
-
-  //   const result = await p
-  //   expect(result.success).toBe(true)
-  //   expect(result.data.id).toBe('spatial-1')
-  //   expect(result.data.windowProxy).toBe(windowProxy)
-  //   const call = openFn.mock.calls[0] as unknown as [string, string | undefined]
-  //   expect(call?.[0]).toMatch(/^about:blank\?rid=/)
-  //   expect(call?.[1]).toBe('_self')
-  // })
-
   it('SSRPlatform returns successful no-op results', async () => {
     const { SSRPlatform } = await import('./platform-adapter/ssr/SSRPlatform')
     const platform = new SSRPlatform()
@@ -379,12 +270,7 @@ describe('platform adapters', () => {
     await expect(platform.callJSB('c', '{}')).resolves.toMatchObject({
       success: true,
     })
-    await expect(
-      platform.callWebSpatialProtocol('s', '', '', ''),
-    ).resolves.toMatchObject({
-      success: true,
-    })
-    expect(platform.callWebSpatialProtocolSync('s', '', '', '')).toMatchObject({
+    expect(platform.openSpatialSceneSync('s', undefined)).toMatchObject({
       success: true,
     })
   })
@@ -437,7 +323,7 @@ describe('platform adapters', () => {
       './platform-adapter/vision-os/VisionOSPlatform'
     )
     const platform = new VisionOSPlatform()
-    const r = await platform.callWebSpatialProtocol('open', 'a=1')
+    const r = await platform.createNativeSpatialDiv()
 
     expect(r.success).toBe(true)
     expect(r.data.id).toBe(uuid)
@@ -584,6 +470,14 @@ describe('SpatializedElementCreator', () => {
     const windowProxy: any = {
       document: { head: { innerHTML: '' } },
     }
+    vi.doMock('./spatial-host', () => ({
+      createNativeSpatialDiv: vi.fn().mockResolvedValue({
+        success: true,
+        data: { id: 'w1', windowProxy },
+        errorCode: '',
+        errorMessage: '',
+      }),
+    }))
 
     vi.doMock('./JSBCommand', () => {
       class OkCommand {
@@ -649,6 +543,15 @@ describe('SpatializedElementCreator', () => {
   })
 
   it('createSpatialized2DElement throws when command fails', async () => {
+    vi.doMock('./spatial-host', () => ({
+      createNativeSpatialDiv: vi.fn().mockResolvedValue({
+        success: false,
+        data: undefined,
+        errorCode: 'E',
+        errorMessage: 'bad',
+      }),
+    }))
+
     vi.doMock('./JSBCommand', () => {
       class OkCommand {
         execute() {
@@ -1052,9 +955,25 @@ describe('platform-adapter', () => {
     })
 
     const { createPlatform } = await import('./platform-adapter')
-    const p = createPlatform() as any
+    const p = await createPlatform()
     expect(typeof p.callJSB).toBe('function')
-    expect(typeof p.callWebSpatialProtocol).toBe('function')
-    expect(typeof p.callWebSpatialProtocolSync).toBe('function')
+    expect(typeof p.openSpatialSceneSync).toBe('function')
+    expect(typeof p.createNativeSpatialDiv).toBe('function')
+    expect(typeof p.createNativeAttachment).toBe('function')
+  })
+
+  it('createPlatformSync uses SSR sync noop in SSR env', async () => {
+    vi.resetModules()
+    vi.doMock('./ssr-polyfill', () => {
+      return { isSSREnv: () => true }
+    })
+
+    const { createPlatformSync } = await import(
+      './platform-adapter/createPlatformSync'
+    )
+    const p = createPlatformSync()
+    const r = p.openSpatialSceneSync('https://x', undefined)
+    expect(r.success).toBe(true)
+    expect(r.data).toBeUndefined()
   })
 })

package/src/index.ts

@@ -1,3 +1,5 @@
+export type {} from './types/global'
+
 export { SpatialObject } from './SpatialObject'
 export { Spatial } from './Spatial'
 export { SpatialSession } from './SpatialSession'
@@ -10,7 +12,7 @@ export * as PhysicalMetrics from './physicalMetrics'
 
 export * from './reality'
 export * from './types/types'
-export * from './types/global.d'
+export * from './runtime'
 
 // side effects
 import { injectSceneHook } from './scene-polyfill'

package/src/jsbcommand.coverage.test.ts

@@ -55,12 +55,14 @@ class DOMMatrixPolyfill {
 
 const platformSpy = {
   callJSB: vi.fn(),
-  callWebSpatialProtocol: vi.fn(),
-  callWebSpatialProtocolSync: vi.fn(),
+  openSpatialSceneSync: vi.fn(),
+  createNativeSpatialDiv: vi.fn(),
+  createNativeAttachment: vi.fn(),
 }
 
 vi.mock('./platform-adapter', () => ({
-  createPlatform: () => platformSpy,
+  createPlatform: () => Promise.resolve(platformSpy),
+  createPlatformSync: () => platformSpy,
 }))
 
 function ok(data: any = {}) {
@@ -72,23 +74,20 @@ function ok(data: any = {}) {
   })
 }
 
-function parseQuery(q?: string) {
-  const sp = new URLSearchParams(q ?? '')
-  const out: Record<string, string> = {}
-  for (const [k, v] of sp.entries()) out[k] = v
-  return out
-}
-
 describe('JSBCommand', () => {
   beforeEach(() => {
     platformSpy.callJSB.mockReset()
-    platformSpy.callWebSpatialProtocol.mockReset()
-    platformSpy.callWebSpatialProtocolSync.mockReset()
+    platformSpy.openSpatialSceneSync.mockReset()
+    platformSpy.createNativeSpatialDiv.mockReset()
+    platformSpy.createNativeAttachment.mockReset()
     platformSpy.callJSB.mockImplementation(() => ok({ id: 'id-1' }))
-    platformSpy.callWebSpatialProtocol.mockImplementation(() =>
+    platformSpy.createNativeSpatialDiv.mockImplementation(() =>
+      ok({ windowProxy: {}, id: 'spatial-1' }),
+    )
+    platformSpy.createNativeAttachment.mockImplementation(() =>
       ok({ windowProxy: {}, id: 'spatial-1' }),
     )
-    platformSpy.callWebSpatialProtocolSync.mockImplementation(() => ({
+    platformSpy.openSpatialSceneSync.mockImplementation(() => ({
       success: true,
       data: { windowProxy: {}, id: 'spatial-1' },
       errorCode: '',
@@ -192,40 +191,6 @@ describe('JSBCommand', () => {
       JSON.stringify({ id: 'so-1', color: '#fff' }),
     )
   })
-
-  it('creates query string and calls WebSpatialProtocol', async () => {
-    const mod = await import('./JSBCommand')
-    const { createSpatialSceneCommand, createSpatialized2DElementCommand } = mod
-
-    await new createSpatialized2DElementCommand().execute()
-    expect(platformSpy.callWebSpatialProtocol).toHaveBeenCalledWith(
-      'createSpatialized2DElement',
-      '',
-      undefined,
-      undefined,
-    )
-
-    const cmd = new createSpatialSceneCommand(
-      'https://example.com/a?b=c',
-      { type: 'window', defaultSize: { width: 1, height: 2 } } as any,
-      '_self',
-      'popup=1',
-    )
-    await cmd.execute()
-    const call = platformSpy.callWebSpatialProtocol.mock.calls.at(-1)
-    expect(call?.[0]).toBe('createSpatialScene')
-    expect(call?.[2]).toBe('_self')
-    expect(call?.[3]).toBe('popup=1')
-    const q = parseQuery(call?.[1])
-    expect(q.url).toBe('https://example.com/a?b=c')
-    expect(JSON.parse(q.config)).toEqual({
-      type: 'window',
-      defaultSize: { width: 1, height: 2 },
-    })
-
-    cmd.executeSync()
-    expect(platformSpy.callWebSpatialProtocolSync).toHaveBeenCalled()
-  })
 })
 
 describe('SpatialObject', () => {
@@ -272,6 +237,7 @@ describe('realityCreator', () => {
       if (cmd === 'CreateModelComponent') return ok({ id: 'cmp-1' })
       if (cmd === 'CreateSpatialModelEntity') return ok({ id: 'ment-1' })
       if (cmd === 'CreateModelAsset') return ok({ id: 'asset-1' })
+      if (cmd === 'CreateTexture') return ok({ id: 'tex-1' })
       return ok({ id: 'id-1' })
     })
   })
@@ -282,6 +248,7 @@ describe('realityCreator', () => {
     const mat = await import('./reality/material/SpatialUnlitMaterial')
     const cmp = await import('./reality/component/ModelComponent')
     const asset = await import('./reality/resource/SpatialModelAsset')
+    const tex = await import('./reality/resource/SpatialTextureResource')
     const ent = await import('./reality/entity/SpatialEntity')
     const modelEnt = await import('./reality/entity/SpatialModelEntity')
 
@@ -311,6 +278,10 @@ describe('realityCreator', () => {
       creator.createModelAsset({ url: 'https://example.com/a.glb' }),
     ).resolves.toBeInstanceOf(asset.SpatialModelAsset)
 
+    await expect(
+      creator.createSpatialTexture({ url: 'https://example.com/tex.png' }),
+    ).resolves.toBeInstanceOf(tex.SpatialTextureResource)
+
     await expect(
       creator.createSpatialModelEntity(
         { modelAssetId: 'asset-1' },

package/src/platform-adapter/CommandResultUtils.ts

@@ -1,6 +1,6 @@
 import { CommandResult } from './interface'
 
-export function CommandResultSuccess(data: any): CommandResult {
+export function CommandResultSuccess<TData>(data: TData): CommandResult<TData> {
   return {
     success: true,
     data,
@@ -12,7 +12,7 @@ export function CommandResultSuccess(data: any): CommandResult {
 export function CommandResultFailure(
   errorCode: string,
   errorMessage = '',
-): CommandResult {
+): CommandResult<undefined> {
   return {
     success: false,
     data: undefined,

package/src/platform-adapter/createPlatformSync.ts

@@ -0,0 +1,34 @@
+import { resolveJsbAdapterPlatform } from '../runtime/jsbAdapterPlatform'
+import { isSSREnv } from '../ssr-polyfill'
+import { PlatformAbility } from './interface'
+import { PicoOSPlatform } from './pico-os/PicoOSPlatform'
+import { PuppeteerPlatform } from './puppeteer/PuppeteerPlatform'
+import { SSRPlatform } from './ssr/SSRPlatform'
+import { VisionOSPlatform } from './vision-os/VisionOSPlatform'
+
+function assertNever(_: never): never {
+  throw new Error('Unhandled jsb adapter platform kind')
+}
+
+/**
+ * Construct the JSB platform synchronously (static imports).
+ * Used by getPlatformSync (e.g. scene-polyfill openSpatialSceneSync) and kept
+ * consistent with async createPlatform so paths share one implementation.
+ */
+export function createPlatformSync(): PlatformAbility {
+  if (isSSREnv()) {
+    return new SSRPlatform()
+  }
+  const userAgent = window.navigator.userAgent
+  const kind = resolveJsbAdapterPlatform(userAgent)
+  switch (kind) {
+    case 'puppeteer':
+      return new PuppeteerPlatform()
+    case 'picoos':
+      return new PicoOSPlatform()
+    case 'visionos':
+      return new VisionOSPlatform()
+    default:
+      return assertNever(kind)
+  }
+}

package/src/platform-adapter/index.ts

@@ -1,53 +1,7 @@
-import { isSSREnv } from '../ssr-polyfill'
-import { PlatformAbility } from './interface'
-import { SSRPlatform } from './ssr/SSRPlatform'
+export { createPlatformSync } from './createPlatformSync'
+import { createPlatformSync } from './createPlatformSync'
+import type { PlatformAbility } from './interface'
 
-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
-}
-
-export function createPlatform(): PlatformAbility {
-  if (isSSREnv()) {
-    return new SSRPlatform()
-  }
-  const userAgent = window.navigator.userAgent
-  const webSpatialVersion = getWebSpatialVersion(userAgent)
-  if (window.navigator.userAgent.includes('Puppeteer')) {
-    const PuppeteerPlatform =
-      require('./puppeteer/PuppeteerPlatform').PuppeteerPlatform
-    return new PuppeteerPlatform()
-  } else if (
-    userAgent.includes('PicoWebApp') &&
-    isVersionGreater(webSpatialVersion, [0, 0, 1])
-  ) {
-    const PicoOSPlatform = require('./pico-os/PicoOSPlatform').PicoOSPlatform
-    return new PicoOSPlatform()
-  } else if (userAgent.includes('Android') || userAgent.includes('Linux')) {
-    const AndroidPlatform = require('./android/AndroidPlatform').AndroidPlatform
-    return new AndroidPlatform()
-  } else {
-    const VisionOSPlatform =
-      require('./vision-os/VisionOSPlatform').VisionOSPlatform
-    return new VisionOSPlatform()
-  }
+export async function createPlatform(): Promise<PlatformAbility> {
+  return createPlatformSync()
 }

package/src/platform-adapter/interface.ts

@@ -1,36 +1,48 @@
-export interface CommandResult {
-  success: boolean
-  data: any
-  errorCode: string | undefined
-  errorMessage: string | undefined
-}
+import type { SpatialSceneCreationOptionsInternal } from '../types/internal'
+import type { AttachmentEntityOptions } from '../types/types'
 
-export interface WebSpatialProtocolResult extends CommandResult {
+export interface CommandResult<TData = any> {
   success: boolean
-  data:
-    | {
-        windowProxy: WindowProxy
-        id: string
-      }
-    | undefined
+  data: TData
   errorCode: string | undefined
   errorMessage: string | undefined
 }
 
+export type WebSpatialProtocolResult = CommandResult<
+  | {
+      // Platform-dependent window proxy shape:
+      // - browser WindowProxy (visionOS/PICO)
+      // - puppeteer simulated window object
+      // Keep broad to avoid over-constraining platform adapters/callers.
+      windowProxy: any
+      id: string
+    }
+  | undefined
+>
+
+/**
+ * Host/runtime bridge: JSB plus explicit spatial host capabilities.
+ * Implementations may use webspatial://, iframes, native events, etc.
+ */
 export interface PlatformAbility {
   callJSB(cmd: string, msg: string): Promise<CommandResult>
-  callWebSpatialProtocol(
-    schema: string,
-    query?: string,
-    target?: string,
-    features?: string,
-  ): Promise<WebSpatialProtocolResult>
 
-  callWebSpatialProtocolSync(
-    schema: string,
-    query?: string,
+  /**
+   * Open a spatial scene synchronously (e.g. window.open polyfill).
+   * Implementations may use webspatial://createSpatialScene under the hood.
+   */
+  openSpatialSceneSync(
+    url: string,
+    config: SpatialSceneCreationOptionsInternal | undefined,
     target?: string,
     features?: string,
-    resultCallback?: (result: CommandResult) => void,
   ): WebSpatialProtocolResult
+
+  /** Create a native-backed spatial 2D surface (spatial div). */
+  createNativeSpatialDiv(): Promise<WebSpatialProtocolResult>
+
+  /** Create a native attachment surface; options reserved for future protocol fields. */
+  createNativeAttachment(
+    options?: AttachmentEntityOptions,
+  ): Promise<WebSpatialProtocolResult>
 }