WebSpatial App
A Web App that uses the WebSpatial API becomes a spatial app when it runs as a standalone app on a spatial computing platform and enables spatial computing capabilities with the help of the WebSpatial Runtime. This is called a WebSpatial App.
A WebSpatial App is an enhancement of a standard Web App, and that enhancement is activated only under suitable conditions.
If the same Web App runs on platforms that do not support spatial computing, such as browsers on desktop computers or phones, it is still a normal webpage or PWA with no spatial computing effects, and WebSpatial does not affect it.
For the same Web App to run as a WebSpatial App and enable spatial computing capabilities, the operating system must support spatial computing and unified rendering, and the runtime environment must also include WebSpatial Runtime. Current browser UIs are designed for screen-based devices and for efficiently browsing multiple 2D webpages. They conflict with spatial app UI patterns such as transparent backgrounds and UI elements that float or protrude in space. Because of that, those browsers, such as Safari on visionOS and the default browser on PICO OS 6, cannot currently include WebSpatial Runtime and will run such a Web App as a normal webpage.
If the same Web App runs independently outside the browser on PICO OS 6 through the Web App Runtime, or is packaged with WebSpatial Builder as a Packaged Hybrid App and run on visionOS, it gains a runtime environment with WebSpatial Runtime, becomes a WebSpatial App, and enables spatial computing capabilities.
WebXR content can be "contained" inside a WebSpatial App, because a WebSpatial App is still a standard Web App composed of normal webpages. A webpage in the app can start a WebXR session through JS APIs, take over the entire space, and render WebXR content with low-level 3D graphics APIs such as WebGL or WebGPU. But that space is not Full Space, and it is not unified rendering. Rendering is handled independently by the WebXR code itself. Once a WebXR session starts, the original webpages and spatialized UI of the WebSpatial App are hidden and are not shown at the same time.
Because WKWebView on visionOS does not currently support WebXR, Packaged WebSpatial Apps on visionOS cannot start a WebXR session for now.
Web App
Broadly speaking, any website that provides complete app functionality is a Web App.
But a traditional website is just a set of webpages or URLs linked to one another. These pages or URLs run as separate tabs in a browser and have weak relationships with each other. There is no standardized way for a page to expose information about the entire Web App, such as the app name, app icon, or which URLs belong to the app.
The Web App Manifest, which was added to Web standards as part of the PWA standard, lets webpages provide information about the Web App they belong to. This allows the Web App to run independently outside the browser, be installed like a native app, and gain more native-like experiences and capabilities.
So in WebSpatial documentation, "Web App" specifically means PWA. A website only needs to include a Web App Manifest to become a PWA; other PWA technologies are not required.
Web Runtime
Web Runtime refers to a runtime that can run Web Apps, webpages, and Web code such as HTML/CSS/JS according to Web standards. This runtime is composed of the browser engine and other native implementations.
Safari and WKWebView on visionOS are both Web Runtimes. A Packaged WebSpatial App generated by WebSpatial Builder that includes WebSpatial Runtime renders webpages and all HTML/CSS/JS code through WKWebView, so these hybrid apps are also Web Runtimes.
The Web App Runtime on PICO OS 6, which includes WebSpatial Runtime, is also a kind of Web Runtime and uses the same Chromium core as the PICO browser.
In other words, WebSpatial Runtime is always built into a Web Runtime and is part of that Web Runtime. That is why a WebSpatial App retains the original capabilities of a standard Web App and inherits the code and development model of a standard Web App.
WebSpatial Runtime
WebSpatial Runtime builds on top of a Web Runtime and additionally implements the WebSpatial API. It exposes the operating system's spatial computing capabilities to standard Web Apps, so those apps are enhanced when running on such systems.
Eventually, WebSpatial Runtime will be implemented entirely inside browser engines. But at the current stage, to make the proposed WebSpatial standards available immediately, the implementation combines browser engines and hybrid techniques, and must be used together with the WebSpatial SDK.
Some spatial computing operating systems include WebSpatial Runtime, such as PICO OS 6. On those platforms, standard Web Apps that use WebSpatial SDK can run independently by URL and enable spatial computing directly.
Some spatial computing operating systems do not include WebSpatial Runtime, such as visionOS. To enable spatial computing on those platforms, a standard Web App that uses WebSpatial SDK must be packaged with WebSpatial Builder as a Packaged WebSpatial App that includes WebSpatial Runtime.
The WebSpatial Runtime implementations for those specific platforms, which can be packaged into hybrid apps, are provided as separate npm packages. For example, WebSpatial SDK provides @webspatial/platform-visionos for visionOS.
Packaged WebSpatial App
A Packaged WebSpatial App is a native spatial app that includes both WebSpatial Runtime and Web Runtime. It is effectively a native app shell that runs a Web App, behaving much like an installed PWA running independently. Based on the Web App Manifest, it loads the start page in its own standalone window and also supports opening more pages from the same Web App in additional windows. If the Web App uses the WebSpatial API through the WebSpatial SDK, spatial computing is automatically enabled in this environment.
Such an app can be previewed and debugged on the official simulator and test devices for the target spatial computing platform, such as visionOS, and can also be submitted to app stores. The target spatial computing platform itself does not need to include WebSpatial Runtime, but the environment used for packaging the app must have the required WebSpatial Runtime prepared in advance. For visionOS, for example, the project must install @webspatial/platform-visionos.
To obtain a Packaged WebSpatial App, you first need a website project integrated with WebSpatial SDK, and you use a Web Build Tool to compile it into website output files that can be deployed to a server. At that point, you can already package it directly with WebSpatial Builder. Builder will automatically copy the website output into the app bundle, and at runtime the app will load HTML/CSS/JS and other Web files locally from the bundle instead of over the network. If you additionally serve the output from the Web Build Tool as a website and get a URL that the simulator or spatial computing device can access, then pass that URL to WebSpatial Builder, you can generate an app bundle that does not include the website output itself, and the app will load HTML/CSS/JS and other Web files online during runtime.
Web Build Tool
A Web Build Tool refers to tools such as Vite, Rspack, and Webpack that compile and build source code based on Web frameworks into the HTML pages, CSS, JS, and other static Web files actually served by a Web server.
Web frameworks such as Next.js include their own Web Build Tool.
At the current stage, the WebSpatial SDK needs a Web framework (React) and a Web Build Tool in order to let developers use the WebSpatial API in source code.
WebSpatial Builder
WebSpatial SDK provides a development tool called WebSpatial Builder (package name @webspatial/builder) to simplify generating, previewing, and distributing a Packaged WebSpatial App.
This tool provides three commands: