DOCSEARCHbyAlgolia
Submit Docs

WebSpatial

website·Indexed 32 days ago

https://webspatial.dev/docs

A set of spatial APIs and an SDK designed to extend standard 2D web capabilities, providing integration patterns and installation procedures for web projects and platforms.

Tokens
16.7K
Snippets
63
Records
109
Agent score
9%

What's inside WebSpatial

  1. Overview of WebSpatial for Spatial Computing

    WebSpatial is a set of spatial APIs and a ready-to-use SDK designed to extend the standard 2D Web ecosystem to support spatial computing across platforms. It allows HTML and CSS-based web applications to achieve spatial capabilities comparable to native spatial apps (such as visionOS apps) while maintaining the advantages of the open web.

  2. Overview of WebSpatial capabilities

    WebSpatial provides minimal extensions to HTML, CSS, and DOM APIs, along with a polyfill-style SDK. It allows web developers to move from 2D layouts to spatial computing by enabling HTML content to have real volume, support natural spatial interactions, and integrate 3D programming while maintaining the standard web development workflow and cross-platform nature.

  3. Understand WebSpatial App requirements and behavior

    A WebSpatial App is a standard Web App (specifically a PWA with a Web App Manifest) that uses the WebSpatial API and runs within a WebSpatial Runtime. It enhances a normal webpage by enabling spatial computing capabilities (such as transparent backgrounds and floating UI elements) when running on a supported spatial computing platform.

    Key behaviors:

    • Fallback: If the app runs on a platform without spatial computing support (e.g., standard desktop or mobile browsers), it functions as a normal webpage/PWA with no spatial effects.
    • Runtime Requirement: To enable spatial features, the OS must support spatial computing and unified rendering, and the environment must include the WebSpatial Runtime.
    • WebXR Integration: WebXR content can be embedded within a WebSpatial App. However, starting a WebXR session takes over the entire space, hiding the original webpages and spatialized UI. Note that on visionOS, Packaged WebSpatial Apps currently cannot start WebXR sessions because WKWebView does not support WebXR.

  4. Understand Spatial App and Unified Rendering concepts

    WebSpatial follows a "2D containing 3D" development paradigm.

    • Spatial App: An app that runs in a Spatial OS (like visionOS or PICO OS 6) and is rendered in a unified way by the OS. A standard 2D Web App becomes a spatial app by implementing WebSpatial APIs to allow 2D content to enter 3D space or mix with volumetric 3D content.
    • Unified Rendering: The process where the Spatial OS manages 2D/3D content containers (spatial scenes) to ensure multiple apps share the same coordinate system, lighting, occlusion, and shadows.
    • Spatial Runtime: The single 3D rendering engine managed by the OS.
      • Shared Space: Multiple spatial apps coexist.
      • Full Space: One app exclusively occupies the space, allowing access to private data like eye tracking and hand movement after user authorization.

  5. WebSpatial SDK Overview and Compatibility

    The WebSpatial SDK provides a polyfill for proposed HTML/DOM/CSS spatial APIs, allowing developers to use Z-axis and spatial UI features immediately without waiting for native browser support.

    Key compatibility features include:

    • Cross-version compatibility: The SDK shields developers from instability as APIs enter Web standards, ensuring backward compatibility.
    • Cross-platform behavior: On spatial computing platforms, it enables unified spatial UI features. On non-spatial platforms (standard desktop/mobile browsers), the SDK automatically ignores WebSpatial APIs and skips loading the full implementation to avoid impacting performance.
    • Custom Logic: Developers can use feature detection and runtime detection to implement specific handling for JS/DOM API calls that cannot be automatically ignored.

  6. Initialize WebSpatial using the SpatialBoot component

    Wrap your application with the <SpatialBoot> component from @webspatial/react-sdk. This component activates spatial capabilities on supported platforms and allows the app to function as a standard website in ordinary browsers. For SSR projects, <SpatialBoot> must be placed within client-rendered code.
    import { createRoot } from "react-dom/client";
import { SpatialBoot } from "@webspatial/react-sdk";

createRoot(document.getElementById("root")).render(
  <SpatialBoot>
    <App />
  </SpatialBoot>,
);

  7. Apply true 3D Spatial Transforms to elements

    WebSpatial enhances standard CSS transform and transform-origin properties to produce true 3D spatial effects instead of 2D projections.

    Requirements:

    • The element must be marked as a spatialized HTML element.
    • 3D container elements like <Model> and <Reality> are automatically spatialized and can use these transforms as a backplate.

    Supported Functions:

    • translateZ() and translate3d(): Translate along the Z-axis perpendicular to the webpage.
    • rotateX(), rotateY(), rotateZ(), and rotate3d(): Rotate the 2D plane into 3D space.
    • scaleZ() and scale3d(): Scale parts of the element that have entered 3D space via rotation.

    Notes:

    • transform: perspective() and transform-style are ignored and no longer needed.
    • Spatial transforms do not change the element's actual layout position or its local coordinate system; they only change the visual appearance.
    .list-menu {
  position: fixed;
  top: 200px;
  left: 0;
  transform-origin: top left;
  transform: translateZ(320px) rotateY(80deg);
}

  8. Handle spatial interactions and mixed content

    WebSpatial extends interaction and alignment capabilities for 3D web environments:

    • Spatial Interaction Events: Supports 3D-aware events like tap, drag, and rotate on spatialized HTML elements and 3D mesh surfaces/bounding boxes, providing coordinates in a 3D system.
    • Mixed Content Integration: Provides APIs for coordinate and unit conversion to align and couple 2D CSS-based content with dynamic 3D engine content.

  9. Spatialized HTML elements using JSX markers

    The WebSpatial SDK can transform ordinary HTML elements into spatialized HTML elements. To do this, developers must add specific markers to the elements in JSX. There are three supported marking styles for the enable-xr marker:

    1. HTML Attribute: Pass enable-xr as an attribute.
    2. CSS Class: Add __enableXr__ to the className.
    3. Inline Style: Add enableXr: true to the style object.
    // 1. HTML Attribute
<div className="card" enable-xr></div>

// 2. CSS Class
<div className="card __enableXr__"></div>

// 3. Inline Style
<div className="card" style={{ enableXr: true, marginTop: "10px" }}></div>

  10. Integrate WebSpatial SDK into React Projects

    The WebSpatial SDK currently provides a React SDK. To enable WebSpatial APIs, the SDK must be integrated into the JSX Runtime.

    Project Requirements:

    • TypeScript Projects: Requires one line of configuration (though some build tools like Rspack may need extra steps).
    • JavaScript Projects: Configuration must be handled within the web build tool.

    Supported Build Tools:

    • Vite
    • Next.js, Remix (SSR is supported)
    • Rspack / Rsbuild / Webpack

    Known Limitation: The current version of the WebSpatial SDK does not support styled-components due to a bug.

  11. Manage spatialized elements in React

    When using the WebSpatial SDK with React, follow these constraints for spatialized HTML elements:

    1. Declarative Updates: CSS updates must be done via declarative code (e.g., changing className or style in JSX) following the Rules of React.
    2. DOM Access: To query the current state via DOM APIs, use useRef to obtain the DOM object. Direct queries like querySelector are not supported.
    3. Animations: CSS animations for spatial properties are not supported; use JS-based animation approaches instead.

  12. Create new Spatial Scenes via links

    WebSpatial Apps can create additional Spatial Scenes by opening links in new windows. The target URL must match the scope defined in the Web App Manifest to be opened as a Spatial Scene; otherwise, it opens as a standard third-party browser window. If the new scene has a name, the WebSpatial SDK's initScene API can be used to provide custom initialization properties before the scene is created.
    <!-- Open in a new scene -->
<a href={newSceneUrl} target="_blank">Open Scene</a>
<a href={newSceneUrl} target="newSceneName">Open Named Scene</a>

<script>
  // Programmatically open a scene
  window.open(newSceneUrl);
  window.open(newSceneUrl, "newSceneName");
</script>