@worldmesh/runtime 0.2.1 → 0.2.3

package/src/avatar/share.ts

@@ -0,0 +1,196 @@
+import { parseAvatarShare, type AvatarDescriptor, type SignedAvatarShare } from './descriptor.js';
+
+/**
+ * Which avatar other players may see, keeping its link fresh, and checking the
+ * links other players send.
+ *
+ * Other players download a model straight from the platform, so a link must
+ * never be one a player made up: a server of their own would learn the IP
+ * address of everyone in the room. So only links the WorldMesh hub signed
+ * (Ed25519) when it resolved the avatar are sent, and a link from someone
+ * else is downloaded only if its signature checks out against the hub's
+ * public key. The hub signs Sketchfab links and at3d links on Bluesky's hosts;
+ * never VRoid Hub (its license needs "Multiplay" approval for other players)
+ * or a self-hosted AT Protocol server.
+ *
+ * Links and signatures expire (Sketchfab's links within minutes), so the owner
+ * asks for a fresh one before the old runs out; someone joining later still
+ * gets a working link. Players who already loaded the model keep it.
+ */
+
+/** Never shown to other players, even if a hub signed it. */
+const PRIVATE_PROVIDERS: readonly string[] = ['vroid'];
+/** Ask for a new link this long before the old one expires. */
+const REFRESH_EARLY_MS = 45_000;
+const MIN_REFRESH_MS = 30_000;
+const SHARE_CONTEXT = 'worldmesh-avatar-share-v1';
+
+/** The hub-signed link other players may be shown, or null when there is none. */
+export function shareableAvatar(descriptor: AvatarDescriptor | null): SignedAvatarShare | null {
+  if (!descriptor || PRIVATE_PROVIDERS.includes(descriptor.provider)) return null;
+  return parseAvatarShare(descriptor.share);
+}
+
+/** Same avatar, possibly a different link. */
+function sameAvatar(a: AvatarDescriptor, b: AvatarDescriptor): boolean {
+  if (a.avatarId || b.avatarId) return a.provider === b.provider && a.avatarId === b.avatarId;
+  return a.modelUrl === b.modelUrl;
+}
+
+/**
+ * The avatar this visitor shows other players. Set it whenever the local
+ * avatar changes; with `resolve` (asks the hub again), it keeps the signed
+ * link current, and fetches one if the descriptor came without.
+ */
+export class SharedAvatarLink {
+  private descriptor: AvatarDescriptor | null = null;
+  private shared: SignedAvatarShare | null = null;
+  private timer = 0;
+  private turn = 0;
+
+  constructor(private resolve: (() => Promise<AvatarDescriptor | null>) | null) {}
+
+  set(descriptor: AvatarDescriptor | null): void {
+    this.turn += 1;
+    window.clearTimeout(this.timer);
+    this.descriptor = descriptor;
+    this.shared = shareableAvatar(descriptor);
+    // Handed over without a signed link (e.g. by an older hub): ask for one now.
+    if (descriptor && !this.shared && !PRIVATE_PROVIDERS.includes(descriptor.provider) && descriptor.share === undefined && this.resolve) {
+      const turn = this.turn;
+      this.timer = window.setTimeout(() => void this.refresh(turn), 0);
+      return;
+    }
+    this.schedule();
+  }
+
+  get(): SignedAvatarShare | null {
+    return this.shared;
+  }
+
+  dispose(): void {
+    this.turn += 1;
+    window.clearTimeout(this.timer);
+    this.resolve = null;
+  }
+
+  private schedule(): void {
+    const descriptor = this.descriptor;
+    const shared = this.shared;
+    if (!this.resolve || !shared || !descriptor) return;
+    const linkExpires = descriptor.expiresAt ? Date.parse(descriptor.expiresAt) : Infinity;
+    const expires = Math.min(shared.x * 1000, Number.isFinite(linkExpires) ? linkExpires : Infinity);
+    const delay = Math.max(MIN_REFRESH_MS, expires - Date.now() - REFRESH_EARLY_MS);
+    const turn = this.turn;
+    this.timer = window.setTimeout(() => void this.refresh(turn), delay);
+  }
+
+  private async refresh(turn: number): Promise<void> {
+    if (turn !== this.turn || !this.resolve) return;
+    // Nobody new sees a hidden tab's link expire; ask again once it is back.
+    if (document.hidden) {
+      this.timer = window.setTimeout(() => void this.refresh(turn), MIN_REFRESH_MS);
+      return;
+    }
+    let fresh: AvatarDescriptor | null = null;
+    try {
+      fresh = await this.resolve();
+    } catch {
+      // The hub could not be reached just now. Ask again shortly, or the link
+      // runs out for anyone joining later.
+      if (turn === this.turn) this.timer = window.setTimeout(() => void this.refresh(turn), MIN_REFRESH_MS);
+      return;
+    }
+    if (turn !== this.turn || !this.descriptor) return;
+    // A different avatar (picked on the hub since) is not swapped in here; the
+    // body this visitor sees and the one others see stay the same.
+    if (!fresh || !sameAvatar(fresh, this.descriptor)) return;
+    this.descriptor = fresh;
+    this.shared = shareableAvatar(fresh);
+    this.schedule();
+  }
+}
+
+/** The exact bytes the hub signs (workers/auth/src/avatars/share.ts). */
+function sharePayload(share: SignedAvatarShare): Uint8Array<ArrayBuffer> {
+  return new TextEncoder().encode(`${SHARE_CONTEXT}\n${share.u}\n${share.f}\n${share.i}\n${share.x}`);
+}
+
+const verifiers = new Map<string, (share: SignedAvatarShare) => Promise<boolean>>();
+/** After the hub's key failed to load, wait this long before asking for it again. */
+const KEY_RETRY_MS = 30_000;
+
+/**
+ * Checks links other players send against the public key of the hub at
+ * `hubUrl` (fetched once from its resolve endpoint). Says no when the hub has
+ * no key or the browser cannot check Ed25519, so nothing unchecked is ever
+ * downloaded. Throws when the key could not be fetched just now (offline for a
+ * moment, the hub mid-deploy): the link may well be fine, so ask again later.
+ */
+export function createShareVerifier(hubUrl: string): (share: SignedAvatarShare) => Promise<boolean> {
+  let endpoint: string;
+  try {
+    endpoint = new URL('/api/account/avatar/resolve', hubUrl).toString();
+  } catch {
+    return async () => false;
+  }
+  const existing = verifiers.get(endpoint);
+  if (existing) return existing;
+
+  // Resolves to null when links can never be checked here; rejects when the key could not be fetched.
+  let key: Promise<CryptoKey | null> | null = null;
+  let failedAt = 0;
+  const loadKey = (): Promise<CryptoKey | null> => {
+    // After a failure, fetch again a little later rather than for every link.
+    if (key && !(failedAt && Date.now() - failedAt > KEY_RETRY_MS)) return key;
+    failedAt = 0;
+    key = (async () => {
+      let x: string | null;
+      try {
+        const response = await fetch(endpoint, { method: 'GET', mode: 'cors', credentials: 'omit', referrerPolicy: 'no-referrer' });
+        if (!response.ok) throw new Error(`Key request failed (${response.status})`);
+        const body = (await response.json()) as { key?: { kty?: unknown; crv?: unknown; x?: unknown } | null };
+        const jwk = body.key;
+        if (jwk === null) x = null;
+        else if (!jwk || jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || typeof jwk.x !== 'string') throw new Error('Unexpected share key');
+        else x = jwk.x;
+      } catch (error) {
+        failedAt = Date.now();
+        console.warn('[worldmesh] Cannot load the hub’s avatar key yet; showing default bodies for now.', error);
+        throw error;
+      }
+      if (!x) {
+        console.warn('[worldmesh] This hub does not vouch for avatar links; showing default bodies.');
+        return null;
+      }
+      try {
+        return await crypto.subtle.importKey('jwk', { kty: 'OKP', crv: 'Ed25519', x }, { name: 'Ed25519' }, false, ['verify']);
+      } catch (error) {
+        console.warn('[worldmesh] This browser cannot check other players’ avatar links; showing default bodies.', error);
+        return null;
+      }
+    })();
+    return key;
+  };
+
+  const verify = async (share: SignedAvatarShare): Promise<boolean> => {
+    // Throws while the key cannot be fetched: the caller tries again later.
+    const publicKey = await loadKey();
+    if (!publicKey) return false;
+    try {
+      return await crypto.subtle.verify({ name: 'Ed25519' }, publicKey, fromBase64url(share.s), sharePayload(share));
+    } catch {
+      return false;
+    }
+  };
+  verifiers.set(endpoint, verify);
+  return verify;
+}
+
+function fromBase64url(text: string): Uint8Array<ArrayBuffer> {
+  const base64 = text.replace(/-/g, '+').replace(/_/g, '/');
+  const binary = atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}

package/src/camera/cameraRig.ts

@@ -31,6 +31,8 @@ export class CameraRig {
   private offset = new Vector3();
   /** Smoothed boom length so the camera does not pop when it clears a wall. */
   private currentBoom: number;
+  /** After snapBoom: ease back out slowly, a pull-back rather than a jump. */
+  private gentle = false;
 
   constructor(options: CameraRigOptions) {
     this.camera = options.camera;
@@ -61,6 +63,12 @@ export class CameraRig {
     if (mode === 'third') this.currentBoom = this.distance;
   }
 
+  /** Put the third-person camera this far back right now; it eases back to `distance` from there. */
+  snapBoom(length: number): void {
+    this.currentBoom = clamp(length, 0.4, this.maxDistance);
+    this.gentle = true;
+  }
+
   toggleMode(): ViewMode {
     this.setMode(this.mode === 'first' ? 'third' : 'first');
     return this.mode;
@@ -83,8 +91,9 @@ export class CameraRig {
     const wanted = this.collision.castDistance(this.target, this.offset, this.distance + 0.3) - 0.3;
     const boom = clamp(wanted, 0.4, this.distance);
     // Snap in fast, ease out slowly: popping into geometry is worse than lag.
-    const rate = boom < this.currentBoom ? 1 : 1 - Math.exp(-8 * dt);
+    const rate = boom < this.currentBoom ? 1 : 1 - Math.exp(-(this.gentle ? 1.6 : 8) * dt);
     this.currentBoom += (boom - this.currentBoom) * rate;
+    if (this.gentle && (boom < this.currentBoom || this.currentBoom > boom - 0.05)) this.gentle = false;
     this.camera.position.copy(this.target).addScaledVector(this.offset, this.currentBoom);
   }
 

package/src/camera/viewHandoff.ts

@@ -0,0 +1,67 @@
+import type { ViewMode } from '../types.js';
+
+/**
+ * Remembering the visitor's camera view (first or third person) between worlds.
+ *
+ * Worlds live on different origins, so storage alone cannot carry it: travel
+ * URLs add it to the fragment (`#wm-view=third`), and each world also keeps it
+ * in localStorage so it holds across reloads and later visits.
+ *
+ * Only a view the visitor picked (or was handed) is carried. Until then every
+ * world opens in its own default.
+ */
+
+export const VIEW_PARAM = 'wm-view';
+export const VIEW_STORAGE_KEY = 'worldmesh.view';
+
+let current: ViewMode | null = null;
+
+function isViewMode(value: unknown): value is ViewMode {
+  return value === 'first' || value === 'third';
+}
+
+/** Moves a view from this page's URL fragment into storage, and returns the remembered one. */
+export function takeViewHandoff(): ViewMode | null {
+  const hash = window.location.hash.slice(1);
+  if (hash) {
+    const params = new URLSearchParams(hash);
+    const view = params.get(VIEW_PARAM);
+    if (view !== null) {
+      params.delete(VIEW_PARAM);
+      const rest = params.toString();
+      history.replaceState(history.state, '', `${window.location.pathname}${window.location.search}${rest ? `#${rest}` : ''}`);
+      if (isViewMode(view)) rememberView(view);
+    }
+  }
+  if (!current) {
+    try {
+      const stored = localStorage.getItem(VIEW_STORAGE_KEY);
+      if (isViewMode(stored)) current = stored;
+    } catch {
+      // Storage blocked: the view still follows through travel URLs.
+    }
+  }
+  return current;
+}
+
+export function getRememberedView(): ViewMode | null {
+  return current;
+}
+
+export function rememberView(mode: ViewMode): void {
+  current = mode;
+  try {
+    localStorage.setItem(VIEW_STORAGE_KEY, mode);
+  } catch {
+    // Storage blocked: the view still follows through travel URLs.
+  }
+}
+
+/** Adds the remembered view to a destination URL's fragment, next to any other WorldMesh handoff. */
+export function withView(url: URL): URL {
+  if (!current || !/^https?:$/.test(url.protocol)) return url;
+  const params = new URLSearchParams(url.hash.slice(1));
+  params.set(VIEW_PARAM, current);
+  url.hash = params.toString();
+  return url;
+}

package/src/controls/input.ts

@@ -42,6 +42,18 @@ export class Input {
   private onEscape?: () => boolean | void;
   private touch?: TouchControls;
   private disposed = false;
+  /** Letting go of the cursor to leave the page, not to pause. */
+  private releasing = false;
+  private xrSession: XRSession | null = null;
+  private xrMoveX = 0;
+  private xrMoveZ = 0;
+  private xrTurn = 0;
+  private xrSprint = false;
+  private xrJumpHeld = false;
+  private xrInteractHeld = false;
+  /** Movement carried over from outside (a hub's joystick, still held as the visitor walked in). */
+  private carriedX = 0;
+  private carriedZ = 0;
 
   constructor(options: InputOptions) {
     this.element = options.element;
@@ -81,7 +93,7 @@ export class Input {
   }
 
   requestPointerLock(touchTriggered = false): void {
-    if (this.disposed || this.locked) return;
+    if (this.disposed || this.locked || this.xrSession) return;
 
     // Mobile / touch devices do not support pointer lock. Enter directly.
     if (touchTriggered || isTouchDevice()) {
@@ -135,12 +147,91 @@ export class Input {
     }
   }
 
+  /**
+   * Free the cursor without bringing up the pause screen, for leaving the page.
+   * With moveBeforeLock the visitor stays walking, so coming back with the
+   * browser's back button finds them in the world instead of on the menu.
+   */
+  release(): void {
+    if (!this.moveBeforeLock) {
+      this.exitPointerLock();
+      return;
+    }
+    this.pressed.clear();
+    this.justPressed.clear();
+    this.touch?.reset();
+    if (document.pointerLockElement === this.element) {
+      this.releasing = true;
+      document.exitPointerLock();
+    }
+  }
+
   triggerAction(action: InputAction): void {
     this.justPressed.add(action);
   }
 
+  /** WebXR controllers join the same move / jump / interact actions as the keyboard. */
+  setXrSession(session: XRSession | null): void {
+    this.xrSession = session;
+    this.xrMoveX = 0;
+    this.xrMoveZ = 0;
+    this.xrTurn = 0;
+    this.xrSprint = false;
+    this.xrJumpHeld = false;
+    this.xrInteractHeld = false;
+    if (session) this.touch?.setVisible(false);
+    else this.touch?.setVisible(this.locked && isTouchDevice());
+  }
+
+  /**
+   * Read XR gamepads for this frame. Left stick walks, right stick turns,
+   * trigger or A/X jumps, squeeze interacts.
+   */
+  pollXr(dt: number): void {
+    this.xrMoveX = 0;
+    this.xrMoveZ = 0;
+    this.xrTurn = 0;
+    this.xrSprint = false;
+    let jump = false;
+    let interact = false;
+    if (this.xrSession) {
+      for (const source of this.xrSession.inputSources) {
+        const pad = source.gamepad;
+        if (!pad) continue;
+        const stick = readThumbstick(pad);
+        if (source.handedness === 'right') {
+          this.xrTurn += stick.x * XR_TURN_SPEED * dt;
+        } else {
+          this.xrMoveX += stick.x;
+          this.xrMoveZ += stick.y;
+        }
+        if (pad.buttons[0]?.pressed || pad.buttons[4]?.pressed) jump = true;
+        if (pad.buttons[1]?.pressed) interact = true;
+        if (pad.buttons[3]?.pressed) this.xrSprint = true;
+      }
+      const length = Math.hypot(this.xrMoveX, this.xrMoveZ);
+      if (length > 1) {
+        this.xrMoveX /= length;
+        this.xrMoveZ /= length;
+      }
+    }
+    if (jump && !this.xrJumpHeld) this.justPressed.add('jump');
+    if (interact && !this.xrInteractHeld) this.justPressed.add('interact');
+    this.xrJumpHeld = jump;
+    this.xrInteractHeld = interact;
+  }
+
+  /** Radians to apply to the XR play-space this frame (right stick). */
+  readXrTurn(): number {
+    const turn = this.xrTurn;
+    this.xrTurn = 0;
+    return turn;
+  }
+
   isDown(action: InputAction): boolean {
     if (this.touch?.isDown(action)) return true;
+    if (action === 'sprint' && this.xrSprint) return true;
+    if (action === 'jump' && this.xrJumpHeld) return true;
     for (const code of this.keymap[action]) if (this.pressed.has(code)) return true;
     return false;
   }
@@ -160,6 +251,12 @@ export class Input {
     return digit;
   }
 
+  /** Keep moving this way (same axes as getMoveAxis) until told otherwise; 0, 0 stops. */
+  carry(x: number, z: number): void {
+    this.carriedX = Number.isFinite(x) ? Math.max(-1, Math.min(1, x)) : 0;
+    this.carriedZ = Number.isFinite(z) ? Math.max(-1, Math.min(1, z)) : 0;
+  }
+
   /** Movement intent on the local XZ plane, already normalized. */
   getMoveAxis(): { x: number; z: number } {
     let x = (this.isDown('right') ? 1 : 0) - (this.isDown('left') ? 1 : 0);
@@ -170,6 +267,10 @@ export class Input {
       x += touchAxis.x;
       z += touchAxis.z;
     }
+    x += this.xrMoveX;
+    z += this.xrMoveZ;
+    x += this.carriedX;
+    z += this.carriedZ;
 
     const length = Math.hypot(x, z);
     if (length === 0) return { x: 0, z: 0 };
@@ -251,6 +352,7 @@ export class Input {
   private handleBlur = (): void => {
     this.pressed.clear();
     this.justPressed.clear();
+    this.touch?.reset();
   };
 
   /**
@@ -288,6 +390,12 @@ export class Input {
 
   private handlePointerLockChange = (): void => {
     const isLocked = document.pointerLockElement === this.element;
+    if (!isLocked && this.releasing) {
+      // Quiet: the overlay keeps its walking state.
+      this.releasing = false;
+      this.locked = false;
+      return;
+    }
     if (isLocked) {
       this.setLocked(true);
     } else if (!isTouchDevice()) {
@@ -304,6 +412,16 @@ export class Input {
   };
 }
 
+const XR_TURN_SPEED = 2.4;
+const XR_DEADZONE = 0.18;
+
+function readThumbstick(pad: Gamepad): { x: number; y: number } {
+  const x = pad.axes.length >= 4 ? pad.axes[2] : (pad.axes[0] ?? 0);
+  const y = pad.axes.length >= 4 ? pad.axes[3] : (pad.axes[1] ?? 0);
+  if (Math.hypot(x, y) < XR_DEADZONE) return { x: 0, y: 0 };
+  return { x, y };
+}
+
 function isTypingTarget(target: EventTarget | null): boolean {
   if (!(target instanceof HTMLElement)) return false;
   const tag = target.tagName;

package/src/controls/touch.ts

@@ -102,6 +102,19 @@ const TOUCH_CSS = `
   font-size: 14px;
   opacity: 0.85;
 }
+.wm-btn-sprint {
+  width: 48px;
+  height: 48px;
+}
+.wm-btn-sprint svg {
+  display: block;
+  pointer-events: none;
+}
+/* Run is a toggle, not a hold: both thumbs are busy steering and looking. */
+.wm-btn-sprint.wm-on {
+  background: rgba(255, 255, 255, 0.85);
+  color: #080b10;
+}
 .wm-touch-menu-btn {
   position: absolute;
   top: 14px;
@@ -156,6 +169,8 @@ export class TouchControls {
   private lookDelta = { dx: 0, dy: 0 };
 
   private actionsDown = new Set<InputAction>();
+  private sprintBtn: HTMLButtonElement;
+  private sprinting = false;
   private justPressed = new Set<InputAction>();
 
   private disposed = false;
@@ -186,7 +201,21 @@ export class TouchControls {
     const interactBtn = this.createActionButton('E', 'interact', 'wm-btn-interact', 'Interact');
     const jumpBtn = this.createActionButton('▲', 'jump', 'wm-btn-jump', 'Jump');
 
-    buttons.append(viewBtn, interactBtn, jumpBtn);
+    this.sprintBtn = document.createElement('button');
+    this.sprintBtn.type = 'button';
+    this.sprintBtn.className = 'wm-touch-btn wm-btn-sprint';
+    // An SVG, not a '»' glyph: font metrics push text off the circle's centre.
+    this.sprintBtn.innerHTML =
+      '<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 17 5-5-5-5"/><path d="m13 17 5-5-5-5"/></svg>';
+    this.sprintBtn.title = 'Run';
+    this.sprintBtn.setAttribute('aria-pressed', 'false');
+    this.sprintBtn.addEventListener('pointerdown', (e) => {
+      e.stopPropagation();
+      e.preventDefault();
+      this.setSprinting(!this.sprinting);
+    });
+
+    buttons.append(viewBtn, interactBtn, this.sprintBtn, jumpBtn);
     this.root.appendChild(buttons);
 
     // Menu / Pause button (top right)
@@ -213,8 +242,24 @@ export class TouchControls {
     window.addEventListener('pointermove', this.handlePointerMove);
     window.addEventListener('pointerup', this.handlePointerUp);
     window.addEventListener('pointercancel', this.handlePointerUp);
+    window.addEventListener('pagehide', this.handlePageLeave);
+    window.addEventListener('pageshow', this.handlePageLeave);
+    document.addEventListener('visibilitychange', this.handleVisibilityChange);
   }
 
+  /**
+   * Walking through a door while holding the stick leaves the page mid-drag, so
+   * its pointerup never arrives. Back-button restores the page as it was left,
+   * stick still held. Let go whenever the page is left or comes back.
+   */
+  private handlePageLeave = (): void => {
+    this.reset();
+  };
+
+  private handleVisibilityChange = (): void => {
+    if (document.visibilityState === 'hidden') this.reset();
+  };
+
   private createActionButton(
     label: string,
     action: InputAction,
@@ -316,6 +361,8 @@ export class TouchControls {
     if (e.pointerId === this.movePointerId) {
       this.movePointerId = null;
       this.moveAxis = { x: 0, z: 0 };
+      // Like most mobile games, stopping ends the run.
+      this.setSprinting(false);
       this.restJoystick();
     }
     if (e.pointerId === this.lookPointerId) {
@@ -334,6 +381,7 @@ export class TouchControls {
   }
 
   isDown(action: InputAction): boolean {
+    if (action === 'sprint' && this.sprinting) return true;
     return this.actionsDown.has(action);
   }
 
@@ -362,9 +410,16 @@ export class TouchControls {
     this.lookDelta = { dx: 0, dy: 0 };
     this.actionsDown.clear();
     this.justPressed.clear();
+    this.setSprinting(false);
     this.restJoystick();
   }
 
+  private setSprinting(on: boolean): void {
+    this.sprinting = on;
+    this.sprintBtn.classList.toggle('wm-on', on);
+    this.sprintBtn.setAttribute('aria-pressed', String(on));
+  }
+
   private restJoystick(): void {
     this.joystickBase.classList.add('wm-idle');
     this.joystickBase.style.left = '';
@@ -378,6 +433,9 @@ export class TouchControls {
     window.removeEventListener('pointermove', this.handlePointerMove);
     window.removeEventListener('pointerup', this.handlePointerUp);
     window.removeEventListener('pointercancel', this.handlePointerUp);
+    window.removeEventListener('pagehide', this.handlePageLeave);
+    window.removeEventListener('pageshow', this.handlePageLeave);
+    document.removeEventListener('visibilitychange', this.handleVisibilityChange);
     this.root.remove();
   }
 }