@webspatial/react-sdk 1.6.1 → 2.0.0

package/README.md

@@ -13,3 +13,273 @@ The React SDK from the WebSpatial SDK makes the WebSpatial API immediately avail
 - [Quick Example](https://webspatial.dev/docs/quick-example)
 - [Core Concepts](https://webspatial.dev/docs/core-concepts)
 - [Development Guide](https://webspatial.dev/docs/development-guide)
+
+## Web-first, spatial-enhanced
+
+`@webspatial/react-sdk` v1 ships as a **lean default entry plus a dynamically loaded spatial chunk**. Plain web users (Chrome, Safari, Firefox — anywhere `navigator.userAgent` does not match a WebSpatial runtime) pay only the small default bundle and see the documented per-component fallback markup. The spatial implementation is fetched over the network only when the application opts in via `bootSpatial()` from a WebSpatial-capable runtime (Apple Vision Pro / PICO OS WebSpatial shells).
+
+**Recommended (React):** wrap spatial UI in `<SpatialBoot>` — the SDK calls `bootSpatial()` after mount and mounts `children` only after boot succeeds. On `WebSpatialBootError`, handle `onError`; `children` stay unmounted.
+
+```tsx
+import { SpatialBoot, WebSpatialBootError } from '@webspatial/react-sdk'
+
+export function AppRoot() {
+  return (
+    <SpatialBoot
+      onError={(err: WebSpatialBootError) => {
+        // show error UI; retry with bootSpatial() if needed
+        console.error(err)
+      }}
+    >
+      <App />
+    </SpatialBoot>
+  )
+}
+```
+
+While boot is in flight, `children` are not mounted (render nothing). Show loading UI in your app layout around `<SpatialBoot>` if needed.
+
+**CSR-only optimization:** you may `await bootSpatial()` before `createRoot().render(<SpatialBoot>…)` to shorten the blank period; Next.js / Remix typically use `<SpatialBoot>` inside a `'use client'` subtree instead.
+
+```ts
+import { bootSpatial } from '@webspatial/react-sdk'
+
+await bootSpatial() // plain web: immediate; WebSpatial: loads chunk
+createRoot(el).render(
+  <SpatialBoot>
+    <App />
+  </SpatialBoot>,
+)
+```
+
+Advanced: imperative `bootSpatial()` / `onSpatialLoadError`; `useSpatialReady()` for custom capability UI without `<SpatialBoot>`. See `docs/design/spatial-boot-component.md`.
+
+### Default fallbacks per component
+
+Every facade in the default entry has a documented fallback rendered in plain web / SSR / pre-boot:
+
+| Public name                                                                    | Fallback rendering in non-WebSpatial browsers                               |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| `Model`                                                                        | Native `<model>` element (with spatial-only event props stripped)           |
+| `Reality`                                                                      | Single `<div aria-hidden="true">` placeholder preserving the layout box     |
+| `Entity` / `Box` / `Sphere` / `Cone` / `Cylinder` / `Plane` / `*Entity` family | `null` (children NOT mounted)                                               |
+| `Material` / `Texture` / `ModelAsset` / `AttachmentAsset` / `UnlitMaterial`    | `null`                                                                      |
+| `SceneGraph` / `World`                                                         | `null` (children NOT mounted)                                               |
+
+The full normative table lives in [`openspec/changes/lazy-load-spatial-runtime/specs/spatial-lazy-load/spec.md`](../../openspec/changes/lazy-load-spatial-runtime/specs/spatial-lazy-load/spec.md) — search for "Component facades" and "Hook placeholders".
+
+> The factory HOCs `withSpatialized2DElementContainer` and `withSpatialMonitor` are **internal-only** in v2 — the documented public mechanism for wrapping intrinsic elements is the `enable-xr` / `enable-xr-monitor` JSX marker (see "JSX markers" below). For the rare case where you need a wrapped component as a value (e.g. to compose with another HOC like react-spring's `animated(...)`), use the recipe in "Advanced: composing with third-party HOCs" further down.
+
+### Custom wrappers (escape hatch)
+
+Facades intentionally do NOT accept a generic `fallback` prop in v1; the per-component defaults above are fixed. If you need a different fallback (e.g. a CSS-only 3D preview while the spatial chunk loads), write a small wrapper:
+
+```tsx
+import { Model, useSpatialReady } from '@webspatial/react-sdk'
+
+function MyModelOrSkeleton(props: ComponentProps<typeof Model>) {
+  const ready = useSpatialReady()
+  if (!ready) {
+    // Your custom fallback. Render any HTML you like here; once `ready`
+    // flips true the next React commit mounts the real <Model />.
+    return <div className="model-skeleton" />
+  }
+  return <Model {...props} />
+}
+```
+
+`useSpatialReady()` is hydration-safe (`useSyncExternalStore` with a stable server snapshot), so this pattern works in CSR, SSR, and React Server Components alike.
+
+### Advanced: composing with third-party HOCs
+
+The JSX marker `<div enable-xr>` covers ~all consumer needs, but it produces a JSX element at the call site — not a _component type_ you can pass to a third-party HOC like `animated(...)`, `motion(...)`, or `styled(...)`. Wrap your own `forwardRef` shim around the marker and pass _that_ to the third-party HOC:
+
+```tsx
+import { forwardRef } from 'react'
+import { animated, useSpring } from '@react-spring/web'
+
+// `tsconfig.json` MUST set `"jsxImportSource": "@webspatial/react-sdk"` for
+// `enable-xr` to compile into the real spatial wrapper.
+const SpatialDiv = forwardRef<
+  HTMLDivElement,
+  React.ComponentPropsWithRef<'div'>
+>(function SpatialDiv(props, ref) {
+  return <div enable-xr ref={ref} {...props} />
+})
+SpatialDiv.displayName = 'SpatialDiv'
+
+const AnimatedDiv = animated(SpatialDiv)
+
+export function MyPanel() {
+  const [style] = useSpring(() => ({ '--xr-back': '40' }))
+  return <AnimatedDiv style={style} className="my-panel" />
+}
+```
+
+Why a shim is required: the spatial wrapping logic lives in the SDK's JSX runtime (resolved via `tsconfig.jsxImportSource`), so it only fires when the JSX _call site_ is parsed by your bundler. A `forwardRef` shim moves that call site into a component module the bundler compiles, then exposes the resulting component as a stable value for the third-party HOC.
+
+### React 18+ peer dependency
+
+`react` and `react-dom` are **required** peer dependencies (`>=18.0`). The SDK uses `useSyncExternalStore` for hydration-safe readiness; older React versions are unsupported in v1.
+
+### Bundler compatibility
+
+The SDK relies on three bundler capabilities to deliver its size budget: ESM resolution, the `exports` package.json field, and dynamic `import()` with code-splitting. **Tested-target list (non-normative)**: Vite ≥ 4, Webpack ≥ 5, Rollup ≥ 3, Rspack ≥ 1 (covered by `apps/spatial-rspack-min`), esbuild ≥ 0.18 with `splitting: true`, Next.js App Router (Webpack mode), Next.js Pages Router, React Router 7 (Remix-style SSR + Vite — `apps/spatial-remix-min`). See the [migration guide](../../docs/migration/lazy-load-spatial-runtime.md#bundler-compatibility) for environments that are out of scope for v1 (Module Federation, Next.js Turbopack, Webpack 4, CommonJS-only pipelines).
+
+### Two distribution forms: default vs eager
+
+The package publishes two entry roots with the **same export names**, so you can switch by changing only the import path:
+
+| Entry              | Import                        | Choose when                                                                                                                                                                                                                                             |
+| ------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Default (lazy)** | `@webspatial/react-sdk`       | Web-first progressive enhancement; **SSR**, streaming SSR, or any page whose **server-rendered HTML** should include façade fallbacks for spatial primitives. Smallest synchronous footprint (~5 KB marginal delta in the SDK’s §9.2 fixture).          |
+| **Eager**          | `@webspatial/react-sdk/eager` | Spatial-first apps (fixed WebSpatial shells, internal AVP / PICO surfaces) where you want **one network request** and no real `bootSpatial()` work — at the cost of inlining the full spatial implementation (roughly the same bytes as lazy-loading `dist/spatial.js`; no separate product size cap). |
+
+**SSR / CSR routing**
+
+- Hydration-safe façade SSR (`useSpatialReady` + stable server snapshot → fallback on server and during the hydration pass) is the contract for **`@webspatial/react-sdk`** only.
+- Spatial primitives imported from **`@webspatial/react-sdk/eager`** MUST mount on the **client** only. Server-rendering those components is **not** a supported configuration: use the default entry for SSR pages, or CSR-gate the subtree (for example Next.js `dynamic(..., { ssr: false })`, or render spatial UI only after `typeof window !== 'undefined'`).
+
+**Other rules**
+
+- Migrating between entries is **import-root-only**; on eager, `bootSpatial()` / `isSpatialReady()` / `useSpatialReady()` are **compatibility stubs** (`bootSpatial()` resolves immediately; readiness always reports ready).
+- **Do not** mix both entry roots in one application bundle — the same symbol name may refer to façade vs real implementation and behavior is undefined.
+
+Normative detail: [`openspec/changes/lazy-load-spatial-runtime/specs/spatial-lazy-load/spec.md`](../../openspec/changes/lazy-load-spatial-runtime/specs/spatial-lazy-load/spec.md) — search for "Entry routing" and "CSR-only for spatial primitives".
+
+### Stateless utility APIs
+
+A subset of the public API works without `bootSpatial()` ever being called and is included in the default-entry size budget:
+
+| API                                                                                                         | Behavior                                                                                                                                                                       |
+| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `WebSpatialRuntime.supports(name, tokens?)`                                                                 | Re-exported from `@webspatial/core-sdk/runtime` (inlined into the default-entry bundle at build time); see `openspec/specs/runtime-capabilities/spec.md`                          |
+| `bootSpatial()` / `isSpatialReady()` / `useSpatialReady()` / `onSpatialLoadError()` / `WebSpatialBootError` | Boot bridge — see "Web-first, spatial-enhanced" above                                                                                                                          |
+| `initScene(name, callback, options?)`                                                                       | No-op without a WebSpatial session; routes to `getSession().initScene(...)` after boot                                                                                         |
+| `convertCoordinate(position, { from, to })`                                                                 | Throws `WebSpatialRuntimeError` when `supports('convertCoordinate')` is false or before `bootSpatial()` resolves; converts via the spatial scene when ready                    |
+| `enableDebugTool()`                                                                                         | SSR-safe no-op; in browsers attaches `inspectCurrentSpatialScene` and `getSpatialized2DElement` to `window` (the diagnostics themselves require `bootSpatial()` to be awaited) |
+| `version`                                                                                                   | Package version constant (build-time injected)                                                                                                                                 |
+
+The full normative contract lives in [`openspec/changes/lazy-load-spatial-runtime/specs/spatial-lazy-load/spec.md`](../../openspec/changes/lazy-load-spatial-runtime/specs/spatial-lazy-load/spec.md) — search for "Stateless utility APIs and pure re-exports". Internal `Model` / `SpatializedContainer` host wrappers use `useSyncExternalStore` for SSR + hydration — you do **not** wrap the app in a provider for that.
+
+### Spatial hooks
+
+Import stable hooks from the default entry and experimental animation hooks from the experimental entry:
+
+```ts
+import { useMetrics } from '@webspatial/react-sdk'
+import { useAnimation } from '@webspatial/react-sdk/experimental'
+```
+
+`useMetrics()` has a stable web placeholder. A component instance that first
+invokes it before `bootSpatial()` resolves keeps that placeholder until it
+unmounts and remounts.
+
+`useAnimation(config)` has no web fallback. Call it only from components that
+mount after spatial readiness, such as children of `<SpatialBoot>` or a tree
+rendered after an explicit `await bootSpatial()`. Calling it before readiness
+throws `WebSpatialRuntimeError` with capability `useAnimation`.
+
+### RSC, server requests, and runtime detection
+
+The default entry carries `'use client'` at the top of its emitted `dist/index.js`. Frameworks that support React Server Components treat imports from `@webspatial/react-sdk` as a **client boundary**: you can still **render** facade components from a Server Component file (they become client components), but you cannot **call** hook-style APIs from server-only modules.
+
+If you need to **branch server-rendered HTML** on the incoming request (e.g. different hero for WebSpatial-capable shells vs plain browsers), base that decision on the **HTTP `User-Agent`** string and the **official WebSpatial documentation** for how to interpret it — for example [Introduction](https://webspatial.dev/docs/introduction) and [Development Guide](https://webspatial.dev/docs/development-guide). **Do not rely on undocumented SDK helpers** for environment detection in application code.
+
+## SpatialDiv lifecycle differs from a plain `<div>`
+
+A `<div enable-xr>` (SpatialDiv) is **not** a plain `<div>`. In a WebSpatial runtime the SDK renders your content into a portal whose host DOM node is created, and may be **recreated**, by the SDK — and the hidden layout box you see in the React tree is **not necessarily the same DOM node** as the visible portal host. In plain-web fallback it renders a single host element.
+
+Because of this, **do not reach into child DOM refs inside an `enable-xr` container to synchronize layout or attach an external renderer** (Three.js, a `<canvas>` 2D context, a video player, etc.). Those child nodes may be detached/recreated under you, so a one-shot `useEffect([])` that captures `ref.current` will silently attach to a stale node.
+
+### `onSpatialContentReady` fires only in a WebSpatial runtime
+
+`onSpatialContentReady` is a **spatial-content-host signal**: it is invoked (in `useLayoutEffect` timing) **only when a real WebSpatial spatial content host exists** — i.e. in a WebSpatial runtime after the spatial content has committed. `ctx.host` is always that connected spatial host, and you can return a cleanup that runs on teardown / re-ready.
+
+It does **NOT** fire on plain web (no WebSpatial runtime), nor before `bootSpatial()` has produced a spatial host. For the flat-web presentation, attach your renderer with your **own** `ref` + effect on your **own** element (see the second example), optionally branching on `useSpatialReady()`.
+
+### Do — spatial path via `onSpatialContentReady` (+ cleanup)
+
+```tsx
+<div
+  enable-xr
+  onSpatialContentReady={(ctx) => {
+    // Runs ONLY in a WebSpatial runtime. ctx.host is the connected spatial host.
+    const renderer = new THREE.WebGLRenderer()
+    renderer.setSize(ctx.host.clientWidth, ctx.host.clientHeight)
+    ctx.host.appendChild(renderer.domElement)
+
+    // Returned cleanup runs on unmount / before the next ready edge.
+    return () => {
+      renderer.dispose()
+      renderer.domElement.remove()
+    }
+  }}
+/>
+```
+
+### Do — flat-web path via your own `ref` + effect
+
+```tsx
+// Plain web (no WebSpatial runtime): onSpatialContentReady does NOT fire, so
+// initialize the flat presentation from YOUR OWN element with a normal effect.
+function FlatRenderer() {
+  const slotRef = useRef<HTMLDivElement>(null)
+  const ready = useSpatialReady() // true only in a WebSpatial runtime
+
+  useLayoutEffect(() => {
+    if (ready) return // spatial runtime is handled by onSpatialContentReady
+    const el = slotRef.current
+    if (!el) return
+    const renderer = new THREE.WebGLRenderer()
+    el.appendChild(renderer.domElement)
+    return () => {
+      renderer.dispose()
+      renderer.domElement.remove()
+    }
+  }, [ready])
+
+  return (
+    <div enable-xr onSpatialContentReady={(ctx) => attachSpatial(ctx.host)}>
+      <div ref={slotRef} /> {/* your own element, your own ref — flat path */}
+    </div>
+  )
+}
+```
+
+### Don't — capture a child ref in `useEffect([])` assuming a spatial host
+
+```tsx
+// ANTI-PATTERN: fragile. The captured node may be recreated or split across
+// a hidden layout host and a visible portal host, so `el` can become stale
+// and the renderer attaches to a detached/wrong node. It also conflates the
+// spatial and flat-web paths into one runtime-blind effect.
+function Broken() {
+  const ref = useRef<HTMLDivElement>(null)
+  useEffect(() => {
+    const el = ref.current!
+    const renderer = new THREE.WebGLRenderer()
+    el.appendChild(renderer.domElement) // ← may attach to a stale node
+  }, [])
+  return (
+    <div enable-xr>
+      <div ref={ref} /> {/* child DOM ref is NOT a supported spatial attach point */}
+    </div>
+  )
+}
+```
+
+For layout/size changes prefer **declarative React updates** (props/state) rather than imperative DOM measurement of child refs.
+
+### Nested ordering note
+
+`onSpatialContentReady` ordering guarantees are runtime-scoped:
+
+- In a WebSpatial runtime, the parent `SpatialDiv` callback runs **before** the child callback on the same ready edge.
+- In non-WebSpatial fallback (plain web DOM), parent/child ordering is **not** a guaranteed contract and should be treated as unspecified.
+
+Recommended practice: initialize imperative renderers from each container's own `ctx.host` and avoid coupling setup logic to parent/child callback sequence in fallback web mode.
+
+## SpatialDiv CSS and transforms
+
+Spatial transforms are sampled from an off-screen **probe** DOM node, not from the visible portal surface. Tag/class selectors, probe vs. host split, and workarounds are documented in [WebSpatial Quirks — SpatialDiv / `enable-xr` and CSS](../../docs/webspatial-quirks.md). Maintainer architecture notes live in [`src/spatialized-container/ARCHITECTURE.md`](src/spatialized-container/ARCHITECTURE.md).

package/dist/Model-DO5ps8NA.d.ts

@@ -0,0 +1,35 @@
+import * as React$1 from 'react';
+import * as _webspatial_core_sdk from '@webspatial/core-sdk';
+import { S as SpatializedMotionBinding } from './motionBindingTypes-CjxIC5bP.js';
+import { S as SpatializedStatic3DContainerProps, a as SpatializedStatic3DElementRef, b as SpatialTapEvent, c as SpatialDragStartEvent, d as SpatialDragEvent, e as SpatialDragEndEvent, f as SpatialRotateEvent, g as SpatialRotateEndEvent, h as SpatialMagnifyEvent, i as SpatialMagnifyEndEvent, M as ModelLoadEvent, j as SpatialEventOptions } from './Reality-BDyKL6th.js';
+
+type ModelProps = SpatializedStatic3DContainerProps & {
+    'enable-xr'?: boolean;
+};
+type ModelRef = SpatializedStatic3DElementRef;
+declare const Model: React$1.ForwardRefExoticComponent<{
+    onSpatialTap?: ((event: SpatialTapEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialDragStart?: ((event: SpatialDragStartEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialDrag?: ((event: SpatialDragEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialDragEnd?: ((event: SpatialDragEndEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialRotate?: ((event: SpatialRotateEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialRotateEnd?: ((event: SpatialRotateEndEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialMagnify?: ((event: SpatialMagnifyEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialMagnifyEnd?: ((event: SpatialMagnifyEndEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+} & Omit<Omit<React$1.DetailedHTMLProps<React$1.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "onLoad" | "onError"> & {
+    src?: string;
+    poster?: string;
+    autoPlay?: boolean;
+    loop?: boolean;
+    loading?: _webspatial_core_sdk.ModelLoadingMode;
+    stagemode?: _webspatial_core_sdk.StageMode;
+    children?: React.ReactNode;
+    onLoad?: (event: ModelLoadEvent) => void;
+    onError?: (event: ModelLoadEvent) => void;
+    spatialEventOptions?: SpatialEventOptions;
+    'xr-animation'?: SpatializedMotionBinding;
+} & {
+    'enable-xr'?: boolean;
+} & React$1.RefAttributes<SpatializedStatic3DElementRef>>;
+
+export { Model as M, type ModelProps as a, type ModelRef as b };

package/dist/Reality-BDyKL6th.d.ts

@@ -0,0 +1,256 @@
+import React__default, { ElementType } from 'react';
+import { S as SpatializedMotionBinding } from './motionBindingTypes-CjxIC5bP.js';
+import * as _webspatial_core_sdk from '@webspatial/core-sdk';
+import { Vec3, SpatialTapEvent as SpatialTapEvent$1, SpatialDragStartEvent as SpatialDragStartEvent$1, SpatialDragEvent as SpatialDragEvent$1, SpatialDragEndEvent as SpatialDragEndEvent$1, SpatialRotateEvent as SpatialRotateEvent$1, SpatialRotateEndEvent as SpatialRotateEndEvent$1, SpatialMagnifyEvent as SpatialMagnifyEvent$1, SpatialMagnifyEndEvent as SpatialMagnifyEndEvent$1, ModelLoadingMode, StageMode, SpatialObject, SpatialSession, SpatializedDynamic3DElement, SpatialEntity, AnimatedProps, Quaternion } from '@webspatial/core-sdk';
+
+/** Connected content root for imperative mounting (portal root or web fallback host). */
+type SpatialContentReadyContext = {
+    host: HTMLElement;
+};
+type SpatialContentReadyCallback = (ctx: SpatialContentReadyContext) => void | (() => void);
+/** Options for spatial pointer/gesture behavior (not DOM attributes). */
+type SpatialEventOptions = {
+    /**
+     * Direction vector for rotate gesture constraint. `[0, 0, 0]` or omit = unconstrained.
+     */
+    constrainedToAxis?: Vec3 | readonly [number, number, number];
+};
+type SpatialEventProps<T extends SpatializedElementRef> = {
+    onSpatialTap?: (event: SpatialTapEvent<T>) => void;
+    onSpatialDragStart?: (event: SpatialDragStartEvent<T>) => void;
+    onSpatialDrag?: (event: SpatialDragEvent<T>) => void;
+    onSpatialDragEnd?: (event: SpatialDragEndEvent<T>) => void;
+    onSpatialRotate?: (event: SpatialRotateEvent<T>) => void;
+    onSpatialRotateEnd?: (event: SpatialRotateEndEvent<T>) => void;
+    onSpatialMagnify?: (event: SpatialMagnifyEvent<T>) => void;
+    onSpatialMagnifyEnd?: (event: SpatialMagnifyEndEvent<T>) => void;
+};
+type Spatialized2DElementContainerProps<P extends ElementType> = SpatialEventProps<SpatializedElementRef> & React__default.ComponentPropsWithRef<'div'> & {
+    component: P;
+    spatialEventOptions?: SpatialEventOptions;
+    onSpatialContentReady?: SpatialContentReadyCallback;
+};
+type SpatializedStatic3DContainerProps = SpatialEventProps<SpatializedStatic3DElementRef> & Omit<React__default.ComponentPropsWithoutRef<'div'>, 'onLoad' | 'onError'> & {
+    src?: string;
+    poster?: string;
+    autoPlay?: boolean;
+    loop?: boolean;
+    loading?: ModelLoadingMode;
+    stagemode?: StageMode;
+    children?: React__default.ReactNode;
+    onLoad?: (event: ModelLoadEvent) => void;
+    onError?: (event: ModelLoadEvent) => void;
+    spatialEventOptions?: SpatialEventOptions;
+    /** Native root-transform motion binding from `useAnimation()` via `xr-animation`. */
+    'xr-animation'?: SpatializedMotionBinding;
+};
+type SpatializedElementRef<T extends HTMLElement = HTMLElement> = T;
+type SpatializedDivElementRef = SpatializedElementRef<HTMLDivElement>;
+type SpatializedStatic3DElementRef = SpatializedDivElementRef & {
+    currentSrc: string;
+    ready: Promise<ModelLoadEvent>;
+    entityTransform: DOMMatrixReadOnly;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    readonly paused: boolean;
+    readonly duration: number;
+    playbackRate: number;
+    currentTime: number;
+};
+type CurrentTarget<T extends SpatializedElementRef> = {
+    currentTarget: T;
+};
+type SpatialTapEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialTapEvent$1 & CurrentTarget<T> & {
+    readonly offsetX: number;
+    readonly offsetY: number;
+    readonly offsetZ: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly clientZ: number;
+};
+type SpatialDragStartEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialDragStartEvent$1 & CurrentTarget<T> & {
+    readonly offsetX: number;
+    readonly offsetY: number;
+    readonly offsetZ: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly clientZ: number;
+};
+type SpatialDragEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialDragEvent$1 & CurrentTarget<T> & {
+    readonly translationX: number;
+    readonly translationY: number;
+    readonly translationZ: number;
+};
+type SpatialDragEndEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialDragEndEvent$1 & CurrentTarget<T>;
+type SpatialRotateEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialRotateEvent$1 & CurrentTarget<T> & {
+    readonly quaternion: _webspatial_core_sdk.Quaternion;
+};
+type SpatialRotateEndEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialRotateEndEvent$1 & CurrentTarget<T>;
+type SpatialMagnifyEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialMagnifyEvent$1 & CurrentTarget<T> & {
+    readonly magnification: number;
+};
+type SpatialMagnifyEndEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialMagnifyEndEvent$1 & CurrentTarget<T>;
+type ModelSpatialTapEvent = SpatialTapEvent<SpatializedStatic3DElementRef>;
+type ModelSpatialDragStartEvent = SpatialDragStartEvent<SpatializedStatic3DElementRef>;
+type ModelSpatialDragEvent = SpatialDragEvent<SpatializedStatic3DElementRef>;
+type ModelSpatialDragEndEvent = SpatialDragEndEvent<SpatializedStatic3DElementRef>;
+type ModelSpatialRotateEvent = SpatialRotateEvent<SpatializedStatic3DElementRef>;
+type ModelSpatialRotateEndEvent = SpatialRotateEndEvent<SpatializedStatic3DElementRef>;
+type ModelSpatialMagnifyEvent = SpatialMagnifyEvent<SpatializedStatic3DElementRef>;
+type ModelSpatialMagnifyEndEvent = SpatialMagnifyEndEvent<SpatializedStatic3DElementRef>;
+type ModelLoadEvent<T extends EventTarget = EventTarget> = CustomEvent & {
+    target: T;
+    currentTarget: SpatializedStatic3DElementRef;
+};
+
+/**
+ * Tracks spatial resources (textures, materials, entities, …) by string id under one Reality.
+ *
+ * Native creation is async (`createTexture`, `createUnlitMaterial`, …). The map
+ * stores `Promise<SpatialObject>` so `add(id, pendingCreation)` can run after `get(id)` — sibling
+ * JSX order does not need to match registration order. Callers are responsible for using the
+ * correct id for each resource kind (same as with string ids today).
+ *
+ * `get(id)` before `add()` is fine — resolves when `add()` runs.
+ * `has(id)` is true only after `add()`, not after `get()` alone.
+ *
+ * `subscribe` / `notify`: run when a resource settles, is removed, or updates in place (e.g. texture URL).
+ */
+declare class ResourceRegistry {
+    /** Every id maps to a promise — either the real resource from add(), or a placeholder until then. */
+    private resources;
+    /** ids registered via add(), not get()-only waiters */
+    private registered;
+    /** If get() ran first, we stash resolve/reject so add() can complete the waiting promise. */
+    private deferreds;
+    /** Subscribers are notified whenever an id gets a fresh resolved or failed resource attempt. */
+    private listeners;
+    add<T extends SpatialObject>(id: string, resource: Promise<T>): void;
+    subscribe(id: string, listener: () => void): () => void;
+    notify(id: string): void;
+    has(id: string): boolean;
+    get(id: string): Promise<SpatialObject>;
+    remove(id: string): void;
+    removeAndDestroy(id: string): void;
+    destroy(): void;
+}
+
+type ContainerEntry = {
+    instanceId: string;
+    container: HTMLElement;
+};
+type ContainersChangeCallback = (containers: ContainerEntry[]) => void;
+declare class AttachmentRegistry {
+    private containers;
+    private listeners;
+    addContainer(name: string, instanceId: string, container: HTMLElement): void;
+    removeContainer(name: string, instanceId: string): void;
+    getContainers(name: string): ContainerEntry[];
+    onContainersChange(name: string, cb: ContainersChangeCallback): () => void;
+    private notifyListeners;
+    destroy(): void;
+}
+
+type RealityContextValue = {
+    session: SpatialSession;
+    reality: SpatializedDynamic3DElement;
+    resourceRegistry: ResourceRegistry;
+    attachmentRegistry: AttachmentRegistry;
+} | null;
+
+interface EntityRefShape {
+    convertFromEntityToEntity: (fromEntityId: string, toEntityId: string, position: Vec3) => Promise<Vec3>;
+    convertFromEntityToReality: (entityId: string, position: Vec3) => Promise<Vec3>;
+    convertFromRealityToEntity: (entityId: string, position: Vec3) => Promise<Vec3>;
+    id: string | undefined;
+    name: string | undefined;
+    entity: SpatialEntity | null;
+}
+declare class EntityRef implements EntityRefShape {
+    private _entity;
+    private _ctx;
+    constructor(entity?: SpatialEntity | null, ctx?: RealityContextValue | null);
+    updateEntity(entity?: SpatialEntity | null): void;
+    updateCtx(ctx?: RealityContextValue | null): void;
+    destroy(): void;
+    get entity(): SpatialEntity | null;
+    get id(): string | undefined;
+    get name(): string | undefined;
+    convertFromEntityToEntity(fromEntityId: string, toEntityId: string, position: Vec3): Promise<Vec3>;
+    convertFromEntityToReality(entityId: string, position: Vec3): Promise<Vec3>;
+    convertFromRealityToEntity(entityId: string, position: Vec3): Promise<Vec3>;
+}
+
+type EntityProps = {
+    id?: string;
+    name?: string;
+    position?: Vec3;
+    rotation?: Vec3;
+    scale?: Vec3;
+    enableInput?: boolean;
+    /** Animation prop returned by useEntityAnimation(). */
+    animation?: AnimatedProps;
+};
+type allTarget<T extends EntityRefShape> = {
+    target: T;
+    currentTarget: T;
+};
+type SpatialTapEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialTapEvent$1 & allTarget<T> & {
+    readonly offsetX: number;
+    readonly offsetY: number;
+    readonly offsetZ: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly clientZ: number;
+};
+type SpatialDragStartEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialDragStartEvent$1 & allTarget<T> & {
+    readonly offsetX: number;
+    readonly offsetY: number;
+    readonly offsetZ: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly clientZ: number;
+};
+type SpatialDragEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialDragEvent$1 & allTarget<T> & {
+    readonly translationX: number;
+    readonly translationY: number;
+    readonly translationZ: number;
+};
+type SpatialDragEndEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialDragEndEvent$1 & allTarget<T>;
+type SpatialRotateEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialRotateEvent$1 & allTarget<T> & {
+    readonly quaternion: Quaternion;
+};
+type SpatialRotateEndEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialRotateEndEvent$1 & allTarget<T>;
+type SpatialMagnifyEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialMagnifyEvent$1 & allTarget<T> & {
+    readonly magnification: number;
+};
+type SpatialMagnifyEndEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialMagnifyEndEvent$1 & allTarget<T>;
+type EntityEventHandler = {
+    onSpatialTap?: (event: SpatialTapEntityEvent) => void;
+    onSpatialDragStart?: (event: SpatialDragStartEntityEvent) => void;
+    onSpatialDrag?: (event: SpatialDragEntityEvent) => void;
+    onSpatialDragEnd?: (event: SpatialDragEndEntityEvent) => void;
+    spatialEventOptions?: SpatialEventOptions;
+    onSpatialRotate?: (event: SpatialRotateEntityEvent) => void;
+    onSpatialRotateEnd?: (event: SpatialRotateEndEntityEvent) => void;
+    onSpatialMagnify?: (event: SpatialMagnifyEntityEvent) => void;
+    onSpatialMagnifyEnd?: (event: SpatialMagnifyEndEntityEvent) => void;
+};
+declare const eventMap: {
+    readonly onSpatialTap: "spatialtap";
+    readonly onSpatialDragStart: "spatialdragstart";
+    readonly onSpatialDrag: "spatialdrag";
+    readonly onSpatialDragEnd: "spatialdragend";
+    readonly onSpatialRotate: "spatialrotate";
+    readonly onSpatialRotateEnd: "spatialrotateend";
+    readonly onSpatialMagnify: "spatialmagnify";
+    readonly onSpatialMagnifyEnd: "spatialmagnifyend";
+};
+
+type RealityProps = Omit<React__default.ComponentPropsWithRef<'div'>, 'onSpatialContentReady'> & EntityEventHandler & {
+    /** Native root-transform motion on the Reality container (`SpatializedDynamic3DElement`). */
+    'xr-animation'?: SpatializedMotionBinding;
+};
+declare const Reality: React__default.ForwardRefExoticComponent<Omit<RealityProps, "ref"> & React__default.RefAttributes<HTMLElement>>;
+
+export { type SpatialDragStartEntityEvent as A, type SpatialMagnifyEndEntityEvent as B, type SpatialMagnifyEntityEvent as C, type SpatialRotateEndEntityEvent as D, type EntityEventHandler as E, type SpatialRotateEntityEvent as F, type SpatialTapEntityEvent as G, type SpatializedDivElementRef as H, type SpatializedElementRef as I, type Spatialized2DElementContainerProps as J, eventMap as K, type ModelLoadEvent as M, Reality as R, type SpatializedStatic3DContainerProps as S, type SpatializedStatic3DElementRef as a, type SpatialTapEvent as b, type SpatialDragStartEvent as c, type SpatialDragEvent as d, type SpatialDragEndEvent as e, type SpatialRotateEvent as f, type SpatialRotateEndEvent as g, type SpatialMagnifyEvent as h, type SpatialMagnifyEndEvent as i, type SpatialEventOptions as j, type EntityProps as k, EntityRef as l, type EntityRefShape as m, type ModelSpatialDragEndEvent as n, type ModelSpatialDragEvent as o, type ModelSpatialDragStartEvent as p, type ModelSpatialMagnifyEndEvent as q, type ModelSpatialMagnifyEvent as r, type ModelSpatialRotateEndEvent as s, type ModelSpatialRotateEvent as t, type ModelSpatialTapEvent as u, type RealityProps as v, type SpatialContentReadyCallback as w, type SpatialContentReadyContext as x, type SpatialDragEndEntityEvent as y, type SpatialDragEntityEvent as z };

package/dist/Reality-DO-itiWW.d.ts

@@ -0,0 +1,33 @@
+import * as React$1 from 'react';
+import * as _webspatial_core_sdk from '@webspatial/core-sdk';
+import { S as SpatializedMotionBinding } from './motionBindingTypes-CjxIC5bP.js';
+import { b as SpatialTapEvent, a as SpatializedStatic3DElementRef, c as SpatialDragStartEvent, d as SpatialDragEvent, e as SpatialDragEndEvent, f as SpatialRotateEvent, g as SpatialRotateEndEvent, h as SpatialMagnifyEvent, i as SpatialMagnifyEndEvent, M as ModelLoadEvent, j as SpatialEventOptions, v as RealityProps } from './Reality-BDyKL6th.js';
+
+declare const Model: React$1.ForwardRefExoticComponent<{
+    onSpatialTap?: ((event: SpatialTapEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialDragStart?: ((event: SpatialDragStartEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialDrag?: ((event: SpatialDragEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialDragEnd?: ((event: SpatialDragEndEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialRotate?: ((event: SpatialRotateEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialRotateEnd?: ((event: SpatialRotateEndEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialMagnify?: ((event: SpatialMagnifyEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+    onSpatialMagnifyEnd?: ((event: SpatialMagnifyEndEvent<SpatializedStatic3DElementRef>) => void) | undefined;
+} & Omit<Omit<React$1.DetailedHTMLProps<React$1.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "onLoad" | "onError"> & {
+    src?: string;
+    poster?: string;
+    autoPlay?: boolean;
+    loop?: boolean;
+    loading?: _webspatial_core_sdk.ModelLoadingMode;
+    stagemode?: _webspatial_core_sdk.StageMode;
+    children?: React.ReactNode;
+    onLoad?: (event: ModelLoadEvent) => void;
+    onError?: (event: ModelLoadEvent) => void;
+    spatialEventOptions?: SpatialEventOptions;
+    'xr-animation'?: SpatializedMotionBinding;
+} & {
+    'enable-xr'?: boolean;
+} & React$1.RefAttributes<SpatializedStatic3DElementRef>>;
+
+declare const Reality: React$1.ForwardRefExoticComponent<Omit<RealityProps, "ref"> & React$1.RefAttributes<HTMLElement>>;
+
+export { Model as M, Reality as R };