@wallsnap/ar

Framework-free Android WebXR placement for true-to-scale wall art. It opens an immersive-ar session, requests hit testing, prefers vertical surfaces, and places the supplied artwork plane at its real dimensions. Three.js is dynamically imported only when a session starts.

import { startWallArSession, supportsWallAr } from '@wallsnap/ar';

if (await supportsWallAr(navigator)) {
  const controller = await startWallArSession({
    canvas,
    imageUrl: 'https://cdn.example.com/shareable-artwork.webp',
    widthMeters: 0.6,
    heightMeters: 0.8,
    signal: abortController.signal,
  });

  await controller.dispose();
}

Disposal ends the immersive session and releases the animation loop, hit-test source, WebGL renderer, texture, geometry, and materials. Repeated calls are safe.

The consumer supplies an existing canvas and UI. Artwork URLs must be readable under the host's CORS policy. WebXR requires HTTPS, a compatible Android browser/device, camera permission, and a user gesture to request immersive-ar. Unsupported and permission-denied browsers remain the consumer's fallback decision; this package deliberately contains no camera-overlay fallback and no iOS/USDZ implementation.

The hit selector prefers a vertical pose (abs(normal.y) < 0.5) over floor/table results. Wall placements face outward along the detected surface normal; horizontal placements stand upright and face the camera. Dimensions are metres and remain exact rather than using a fixed display size.

This path was adapted from owner-authored gallery-saas WebXR code. It contains no gallery assets, tenant code, brand UI, or camera fallback. Three.js is MIT-licensed and remains a peer dependency.

MIT licensed.