@yavqo/streets 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yavqo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# Yavqo Streets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Real street-level imagery of any place, in the browser.
+
+```bash
+npm i @yavqo/streets
+```
+
+## Quick start
+
+```html
+<div id="streets" style="width:100vw;height:100vh"></div>
+```
+
+```js
+import { YavqoStreets } from '@yavqo/streets';
+import '@yavqo/streets/style.css';
+
+const streets = new YavqoStreets({
+  container: 'streets',
+  center: [-73.9857, 40.7484], // [lng, lat]
+});
+
+streets.on('ready', () => console.log('Streets loaded'));
+streets.on('error', (e) => console.error(e));
+```
+
+Drag to look around, click or use the arrow keys to move along the street.
+
+## Options
+
+| Option        | Type                    | Description                                      |
+| ------------- | ----------------------- | ------------------------------------------------ |
+| `container`   | `string \| HTMLElement` | Element or element id (required)                 |
+| `center`      | `[lng, lat]`            | Start at the closest imagery to this point       |
+| `imageId`     | `string`                | Start at a specific image (instead of `center`)  |
+
+One of `center` or `imageId` is required.
+
+## Navigation
+
+```js
+await streets.setPosition([2.3522, 48.8566]);  // nearest imagery; rejects with NoCoverageError if none
+await streets.moveTo('IMAGE_ID');
+
+await streets.next();          // next photo along the street  → true, or false at the end of the line
+await streets.prev();
+await streets.moveForward();   // step to the photo ahead of / behind where you are looking
+await streets.moveBackward();
+
+await streets.setHeading(90);  // face east (0 = north) → resolves to the bearing reached
+await streets.lookAt([2.2945, 48.8584]);       // face a point
+
+await streets.setZoom(1.5);    // 0 (wide) to 3 (close)
+await streets.toggleFullscreen();
+```
+
+Flat (non-360°) photos only cover part of the circle, so `setHeading` and `lookAt` stop at the edge of the photo and resolve to the bearing actually reached.
+
+## Coverage
+
+```js
+await streets.hasCoverage([lng, lat]);                       // within 30 m by default
+await streets.findNearby([lng, lat], { radius: 150, limit: 10 });
+// → [{ id, lngLat, distance, heading, capturedAt, isPano }], closest first
+
+streets.on('no-coverage', ({ lngLat, nearest }) => {
+  // nearest = closest imagery within 2 km, or null
+  if (nearest) streets.moveTo(nearest.id);
+});
+```
+
+## Connecting to a map
+
+The `view` event fires whenever the position, direction or field of view changes. It carries everything a map needs to draw a "you are here" marker and view cone.
+
+```js
+import { viewCone } from '@yavqo/streets/geo';
+
+streets.on('view', (view) => {
+  // view = { lngLat, heading, tilt, fov, imageId }
+  marker.setLngLat(view.lngLat);
+  marker.setRotation(view.heading);
+  map.getSource('cone').setData(viewCone(view, 40)); // GeoJSON polygon, 40 m long
+});
+
+map.on('click', (e) => streets.setPosition([e.lngLat.lng, e.lngLat.lat]).catch(() => {}));
+```
+
+## Other API
+
+```js
+await streets.ready();
+await streets.getPosition();   // { id, lngLat, heading, tilt, capturedAt, isPano }
+await streets.getView();       // same shape as the `view` event
+streets.resize();              // after the container changes size
+streets.on('image', ({ id, lngLat, heading, capturedAt, isPano }) => {});
+streets.on('bearing', (degrees) => {});
+streets.on('fullscreen', (active) => {});
+streets.on('error', (e) => {});
+streets.destroy();
+```
+
+## Try it
+
+```bash
+npm run demo     # http://localhost:3000 — controls for every feature plus a self-test
+```
+
+## Notes
+
+- Imagery is contributed by the community and coverage varies by location.
+- The viewer shows a Yavqo Streets footer: Yavqo Streets, Privacy Policy, and Terms of Use.
+- Requires a modern browser with WebGL.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@yavqo/streets",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Yavqo Streets \u2014 real street-level imagery of any place, for the browser.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./geo": {
+      "types": "./src/geo.d.ts",
+      "default": "./src/geo.js"
+    },
+    "./package.json": "./package.json",
+    "./style.css": "./src/style.css"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "./src/style.css"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "demo": "node demo/server.js",
+    "prepublishOnly": "node scripts/check-token.js && npm test"
+  },
+  "keywords": [
+    "yavqo",
+    "streets",
+    "street-view",
+    "street level",
+    "maps",
+    "panorama",
+    "3d"
+  ],
+  "author": "Yavqo",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "mapillary-js": "^4.1.2"
+  }
+}

package/src/config.js

@@ -0,0 +1 @@
+export const ENDPOINT = 'https://graph.mapillary.com';

package/src/coverage.js

@@ -0,0 +1,68 @@
+import { destination, distance, clamp, isLngLat } from './geo.js';
+
+const SEARCH_RADII_M = [30, 120, 500];
+const PAGE = 2000; // the API returns at most this many per request, in no particular order
+const FIELDS = 'id,computed_geometry,computed_compass_angle,captured_at,is_pano';
+
+export class NoCoverageError extends Error {
+  constructor(lngLat, nearest) {
+    super('YavqoStreets: no street-level imagery found near that location.');
+    this.name = 'NoCoverageError';
+    this.lngLat = lngLat;
+    this.nearest = nearest;
+  }
+}
+
+export function assertLngLat(v) {
+  if (!isLngLat(v)) throw new TypeError('YavqoStreets: expected a [lng, lat] pair.');
+}
+
+/** Raw imagery inside a square of `radius` meters around a point, each with its distance. */
+export async function search(endpoint, lngLat, radius, limit = PAGE, fetchImpl = globalThis.fetch) {
+  assertLngLat(lngLat);
+  const [w] = destination(lngLat, 270, radius);
+  const [e] = destination(lngLat, 90, radius);
+  const [, s] = destination(lngLat, 180, radius);
+  const [, n] = destination(lngLat, 0, radius);
+  const url = `${endpoint}/images?fields=${FIELDS}&limit=${limit}&bbox=${w},${s},${e},${n}`;
+  const res = await fetchImpl(url);
+  if (!res.ok) throw new Error(`YavqoStreets: lookup failed (${res.status}).`);
+  const { data = [] } = await res.json();
+  const out = [];
+  for (const img of data) {
+    const c = img.computed_geometry?.coordinates;
+    if (!c) continue;
+    out.push({
+      id: img.id,
+      lngLat: [c[0], c[1]],
+      distance: distance(lngLat, c),
+      heading: img.computed_compass_angle ?? null,
+      capturedAt: img.captured_at ?? null,
+      isPano: Boolean(img.is_pano),
+    });
+  }
+  return out.sort((a, b) => a.distance - b.distance);
+}
+
+/**
+ * Imagery near a point, closest first.
+ * The API caps each response and does not sort it, so a wide search in a dense area could miss the
+ * nearest photos. Search in growing rings instead: a ring that comes back under the cap is complete.
+ */
+export async function findNearby(endpoint, lngLat, { radius = 100, limit = 25 } = {}, fetchImpl) {
+  radius = clamp(radius, 1, 5000);
+  limit = clamp(Math.floor(limit), 1, 200);
+  for (let r = Math.min(25, radius); ; r = Math.min(r * 4, radius)) {
+    const found = (await search(endpoint, lngLat, r, PAGE, fetchImpl)).filter((i) => i.distance <= r);
+    if (found.length >= limit || r >= radius) return found.slice(0, limit);
+  }
+}
+
+/** Closest image, widening the search a few times. Returns null if there is none. */
+export async function nearestImage(endpoint, lngLat, fetchImpl) {
+  for (const radius of SEARCH_RADII_M) {
+    const [best] = await search(endpoint, lngLat, radius, PAGE, fetchImpl);
+    if (best) return best;
+  }
+  return null;
+}

package/src/geo.d.ts

@@ -0,0 +1,19 @@
+export type LngLat = [number, number];
+export function clamp(v: number, min: number, max: number): number;
+export function normalizeBearing(deg: number): number;
+export function destination(from: LngLat, bearing: number, meters: number): LngLat;
+export function distance(a: LngLat, b: LngLat): number;
+export function bearingTo(a: LngLat, b: LngLat): number;
+export function isLngLat(v: unknown): v is LngLat;
+export function angleDiff(to: number, from: number): number;
+export interface ViewCone {
+  type: 'Feature';
+  properties: Record<string, never>;
+  geometry: { type: 'Polygon'; coordinates: LngLat[][] };
+}
+/** GeoJSON polygon of what the viewer can see. Pass the payload of the `view` event. */
+export function viewCone(
+  view: { lngLat: LngLat; heading: number; fov: number },
+  radius?: number,
+  steps?: number,
+): ViewCone;

package/src/geo.js

@@ -0,0 +1,74 @@
+const EARTH_RADIUS_M = 6371008.8;
+const toRad = (d) => (d * Math.PI) / 180;
+const toDeg = (r) => (r * 180) / Math.PI;
+
+export const clamp = (v, min, max) => Math.min(max, Math.max(min, v));
+
+/** Normalise a bearing into [0, 360). */
+export function normalizeBearing(deg) {
+  return ((deg % 360) + 360) % 360;
+}
+
+/** Point reached by travelling `meters` from [lng, lat] along `bearing` degrees. */
+export function destination([lng, lat], bearing, meters) {
+  const d = meters / EARTH_RADIUS_M;
+  const b = toRad(bearing);
+  const φ1 = toRad(lat);
+  const λ1 = toRad(lng);
+  const φ2 = Math.asin(Math.sin(φ1) * Math.cos(d) + Math.cos(φ1) * Math.sin(d) * Math.cos(b));
+  const λ2 =
+    λ1 +
+    Math.atan2(Math.sin(b) * Math.sin(d) * Math.cos(φ1), Math.cos(d) - Math.sin(φ1) * Math.sin(φ2));
+  return [((toDeg(λ2) + 540) % 360) - 180, toDeg(φ2)];
+}
+
+/** Great-circle distance in meters. */
+export function distance([lng1, lat1], [lng2, lat2]) {
+  const φ1 = toRad(lat1);
+  const φ2 = toRad(lat2);
+  const a =
+    Math.sin((φ2 - φ1) / 2) ** 2 +
+    Math.cos(φ1) * Math.cos(φ2) * Math.sin(toRad(lng2 - lng1) / 2) ** 2;
+  return 2 * EARTH_RADIUS_M * Math.asin(Math.min(1, Math.sqrt(a)));
+}
+
+/** Initial bearing in degrees from one point to another. */
+export function bearingTo([lng1, lat1], [lng2, lat2]) {
+  const φ1 = toRad(lat1);
+  const φ2 = toRad(lat2);
+  const Δλ = toRad(lng2 - lng1);
+  const y = Math.sin(Δλ) * Math.cos(φ2);
+  const x = Math.cos(φ1) * Math.sin(φ2) - Math.sin(φ1) * Math.cos(φ2) * Math.cos(Δλ);
+  return normalizeBearing(toDeg(Math.atan2(y, x)));
+}
+
+/** True when `v` looks like a [lng, lat] pair. */
+export function isLngLat(v) {
+  return (
+    Array.isArray(v) &&
+    v.length >= 2 &&
+    Number.isFinite(v[0]) &&
+    Number.isFinite(v[1]) &&
+    Math.abs(v[0]) <= 180 &&
+    Math.abs(v[1]) <= 90
+  );
+}
+
+/** Signed shortest rotation (degrees) that takes bearing `from` to bearing `to`, in (-180, 180]. */
+export function angleDiff(to, from) {
+  const d = ((to - from + 540) % 360) - 180;
+  return d === -180 ? 180 : d;
+}
+
+/**
+ * GeoJSON polygon of the area a viewer can see, ready to hand to a map's data source.
+ * `view` is the payload of the `view` event: { lngLat, heading, fov }.
+ */
+export function viewCone({ lngLat, heading, fov }, radius = 40, steps = 12) {
+  const ring = [lngLat];
+  for (let i = 0; i <= steps; i++) {
+    ring.push(destination(lngLat, heading - fov / 2 + (fov * i) / steps, radius));
+  }
+  ring.push(lngLat);
+  return { type: 'Feature', properties: {}, geometry: { type: 'Polygon', coordinates: [ring] } };
+}

package/src/index.d.ts

@@ -0,0 +1,115 @@
+import type { LngLat } from './geo.js';
+
+export type { LngLat };
+
+export interface StreetsOptions {
+  /** Element or element id to render into. */
+  container: string | HTMLElement;
+  /** Start at the closest imagery to this [lng, lat]. */
+  center?: LngLat;
+  /** Start at a specific image id (alternative to `center`). */
+  imageId?: string;
+  /** Advanced viewer component options. */
+  component?: Record<string, unknown>;
+}
+
+export interface StreetsImage {
+  id: string;
+  lngLat: LngLat;
+  /** Direction the photo was taken, degrees from north. */
+  heading: number;
+  /** Capture time, milliseconds since the epoch. */
+  capturedAt: number;
+  /** True for 360° photos. */
+  isPano: boolean;
+}
+
+export interface StreetsPosition extends StreetsImage {
+  /** Current look direction in degrees (0 = north). */
+  heading: number;
+  tilt: number;
+}
+
+/** What a map needs to draw the viewer: position, direction and view cone. */
+export interface StreetsView {
+  lngLat: LngLat;
+  /** Look direction in degrees (0 = north). */
+  heading: number;
+  tilt: number;
+  /** Horizontal field of view in degrees. */
+  fov: number;
+  imageId: string;
+}
+
+export interface NearbyImage {
+  id: string;
+  lngLat: LngLat;
+  /** Meters from the search point. */
+  distance: number;
+  heading: number | null;
+  capturedAt: number | null;
+  isPano: boolean;
+}
+
+export interface NoCoverageEvent {
+  lngLat: LngLat;
+  /** Closest imagery within 2 km, if any. */
+  nearest: NearbyImage | null;
+}
+
+export class NoCoverageError extends Error {
+  lngLat: LngLat;
+  nearest: NearbyImage | null;
+}
+
+export class YavqoStreets {
+  constructor(options: StreetsOptions);
+  /** The underlying viewer instance (available after `ready()`), for advanced use. */
+  readonly viewer: any;
+  ready(): Promise<this>;
+
+  /* navigation */
+  /** Rejects with NoCoverageError when there is no imagery nearby. */
+  setPosition(lngLat: LngLat): Promise<void>;
+  moveTo(imageId: string): Promise<void>;
+  /** Next / previous photo along the street. Resolve to false when there is nowhere to go. */
+  next(): Promise<boolean>;
+  prev(): Promise<boolean>;
+  moveForward(): Promise<boolean>;
+  moveBackward(): Promise<boolean>;
+  /** Turn to a compass bearing. Resolves to the bearing actually reached. */
+  setHeading(bearing: number): Promise<number>;
+  /** Turn to face a point. Resolves to the bearing reached. */
+  lookAt(lngLat: LngLat): Promise<number>;
+  /** 0 (widest) to 3 (closest). */
+  getZoom(): Promise<number>;
+  setZoom(level: number): Promise<void>;
+  isFullscreen(): boolean;
+  toggleFullscreen(): Promise<boolean>;
+  resize(): void;
+
+  /* coverage */
+  hasCoverage(lngLat: LngLat, radius?: number): Promise<boolean>;
+  findNearby(lngLat: LngLat, options?: { radius?: number; limit?: number }): Promise<NearbyImage[]>;
+
+  /* state */
+  getPosition(): Promise<StreetsPosition>;
+  getView(): Promise<StreetsView>;
+
+  /* events */
+  on(type: 'ready', fn: () => void): this;
+  on(type: 'image', fn: (image: StreetsImage) => void): this;
+  /** Fires whenever position, direction or field of view changes. Use it to drive a map. */
+  on(type: 'view', fn: (view: StreetsView) => void): this;
+  on(type: 'bearing', fn: (bearing: number) => void): this;
+  on(type: 'no-coverage', fn: (event: NoCoverageEvent) => void): this;
+  on(type: 'fullscreen', fn: (active: boolean) => void): this;
+  on(type: 'error', fn: (error: unknown) => void): this;
+  off(
+    type: 'ready' | 'image' | 'view' | 'bearing' | 'no-coverage' | 'fullscreen' | 'error',
+    fn: (...args: any[]) => void,
+  ): this;
+  destroy(): void;
+}
+
+export default YavqoStreets;

package/src/index.js

@@ -0,0 +1,372 @@
+import { Viewer, GraphDataProvider, NavigationDirection } from 'mapillary-js';
+import { ENDPOINT } from './config.js';
+import { TOKEN } from './token.js';
+import { angleDiff, bearingTo, clamp, normalizeBearing } from './geo.js';
+import { NoCoverageError, assertLngLat, findNearby, nearestImage } from './coverage.js';
+
+export { NoCoverageError };
+
+const toRad = (d) => (d * Math.PI) / 180;
+const toDeg = (r) => (r * 180) / Math.PI;
+
+export class YavqoStreets {
+  /**
+   * @param {object} options
+   * @param {string|HTMLElement} options.container Element or element id.
+   * @param {[number, number]} [options.center] Start near this [lng, lat].
+   * @param {string} [options.imageId] Start at this exact image instead.
+   */
+  constructor(options = {}) {
+    if (!options.container) throw new Error('YavqoStreets: `container` is required.');
+    if (!options.center && !options.imageId) {
+      throw new Error('YavqoStreets: provide `center` ([lng, lat]) or `imageId`.');
+    }
+    if (options.center) assertLngLat(options.center);
+
+    this.options = options;
+    if (!TOKEN) throw new Error('YavqoStreets: no access token is built in (src/token.js).');
+    this._endpoint = ENDPOINT;
+    this._fetch = (url) => fetch(url, { headers: { Authorization: `OAuth ${TOKEN}` } });
+    this._listeners = new Map();
+    this._viewQueued = false;
+    this.viewer = null;
+    this._footer = null;
+    this._mountFooter();
+
+    this._ready = this._init();
+    this._ready.catch((err) => {
+      if (!err.handled) this._emit('error', err);
+    });
+  }
+
+  async _init() {
+    const imageId = this.options.imageId ?? (await this._resolve(this.options.center));
+
+    this.viewer = new Viewer({
+      dataProvider: new GraphDataProvider({ endpoint: this._endpoint, accessToken: TOKEN }),
+      container: this.options.container,
+      imageId,
+      component: { cover: false, ...this.options.component, attribution: true },
+    });
+    this._mountFooter();
+
+    const v = this.viewer;
+    v.on('image', ({ image }) => this._emit('image', this._describe(image)));
+    v.on('bearing', ({ bearing }) => this._emit('bearing', bearing));
+    v.on('load', () => this._emit('ready'));
+    for (const type of ['image', 'pov', 'fov', 'position']) v.on(type, () => this._scheduleView());
+
+    this._onFullscreen = () => {
+      this.resize();
+      this._emit('fullscreen', this.isFullscreen());
+    };
+    document.addEventListener('fullscreenchange', this._onFullscreen);
+    return v;
+  }
+
+  _describe(image) {
+    return {
+      id: image.id,
+      lngLat: [image.lngLat.lng, image.lngLat.lat],
+      heading: image.computedCompassAngle ?? image.compassAngle,
+      capturedAt: image.capturedAt,
+      isPano: image.cameraType === 'spherical',
+    };
+  }
+
+  _container() {
+    const container =
+      typeof this.options.container === 'string'
+        ? document.getElementById(this.options.container)
+        : this.options.container;
+    if (!container) throw new Error('YavqoStreets: container not found.');
+    return container;
+  }
+
+  _mountFooter() {
+    const container = this._container();
+    let footer = container.querySelector(':scope > .yavqo-streets-footer');
+    if (!footer) {
+      footer = document.createElement('footer');
+      footer.className = 'yavqo-streets-footer';
+      footer.setAttribute('aria-label', 'Yavqo Streets');
+
+      const brand = document.createElement('span');
+      brand.textContent = 'Yavqo Streets';
+
+      const privacy = document.createElement('a');
+      privacy.href = 'https://yavqo.com/privacy-policy';
+      privacy.target = '_blank';
+      privacy.rel = 'noopener noreferrer';
+      privacy.textContent = 'Privacy Policy';
+
+      const terms = document.createElement('a');
+      terms.href = 'https://yavqo.com/terms-of-use';
+      terms.target = '_blank';
+      terms.rel = 'noopener noreferrer';
+      terms.textContent = 'Terms Of Use';
+
+      for (const node of [brand, this._separator(), privacy, this._separator(), terms]) {
+        footer.append(node);
+      }
+      container.append(footer);
+    } else {
+      container.append(footer);
+    }
+    this._footer = footer;
+  }
+
+  _separator() {
+    const sep = document.createElement('span');
+    sep.className = 'yavqo-streets-footer-sep';
+    sep.setAttribute('aria-hidden', 'true');
+    sep.textContent = '|';
+    return sep;
+  }
+
+  /* ------------------------------------------------------------- coverage */
+
+  /** Image id closest to [lng, lat]. Emits `no-coverage` and throws NoCoverageError if there is none. */
+  async _resolve(lngLat) {
+    const best = await nearestImage(this._endpoint, lngLat, this._fetch);
+    if (best) return best.id;
+
+    const nearest = await findNearby(this._endpoint, lngLat, { radius: 2000, limit: 1 }, this._fetch).then(
+      (r) => r[0] ?? null,
+      () => null,
+    );
+    const err = new NoCoverageError(lngLat, nearest);
+    err.handled = (this._listeners.get('no-coverage')?.size ?? 0) > 0;
+    this._emit('no-coverage', { lngLat, nearest });
+    throw err;
+  }
+
+  /** Is there imagery within `radius` meters (default 30) of [lng, lat]? */
+  async hasCoverage(lngLat, radius = 30) {
+    return (await findNearby(this._endpoint, lngLat, { radius, limit: 1 }, this._fetch)).length > 0;
+  }
+
+  /**
+   * Imagery around a point, closest first.
+   * Each item: { id, lngLat, distance, heading, capturedAt, isPano }.
+   */
+  findNearby(lngLat, { radius = 100, limit = 25 } = {}) {
+    return findNearby(this._endpoint, lngLat, { radius, limit }, this._fetch);
+  }
+
+  /* ----------------------------------------------------------- navigation */
+
+  /** Resolves once the viewer is created. */
+  async ready() {
+    await this._ready;
+    return this;
+  }
+
+  /** Jump to the image closest to [lng, lat]. Rejects with NoCoverageError if there is no imagery nearby. */
+  async setPosition(lngLat) {
+    assertLngLat(lngLat);
+    await this._ready;
+    const image = await this.viewer.moveTo(await this._resolve(lngLat));
+    await this._untilCurrent(image.id);
+  }
+
+  /** Jump to a specific image by id. */
+  async moveTo(imageId) {
+    await this._ready;
+    const image = await this.viewer.moveTo(imageId);
+    await this._untilCurrent(image.id);
+  }
+
+  /** The viewer reports a move as done slightly before it reports the new image as current. */
+  async _untilCurrent(id) {
+    for (let i = 0; i < 25; i++) {
+      if (!this.viewer || (await this.viewer.getImage()).id === id) return;
+      await new Promise((r) => setTimeout(r, 80));
+    }
+  }
+
+  async _move(direction) {
+    await this._ready;
+    let image;
+    try {
+      image = await this.viewer.moveDir(direction);
+    } catch {
+      return false; // nothing to move to in that direction
+    }
+    await this._untilCurrent(image.id);
+    return true;
+  }
+
+  /** Next / previous photo along the street. Resolve to false at the end of the line. */
+  next() {
+    return this._move(NavigationDirection.Next);
+  }
+  prev() {
+    return this._move(NavigationDirection.Prev);
+  }
+  /** Step to the nearest photo ahead of / behind where you are looking. */
+  moveForward() {
+    return this._move(NavigationDirection.StepForward);
+  }
+  moveBackward() {
+    return this._move(NavigationDirection.StepBackward);
+  }
+
+  /**
+   * Turn to face a compass bearing (0 = north). Resolves to the bearing reached.
+   * Flat (non-panoramic) photos only cover part of the circle, so the view may stop short.
+   */
+  async setHeading(bearing) {
+    await this._ready;
+    const target = normalizeBearing(bearing);
+    const spherical = (await this.viewer.getImage()).cameraType === 'spherical';
+    let slope = spherical ? 1 / 360 : 1 / 70; // basic-coordinate change per degree; refined as we go
+    let scale = 1; // shrinks when the viewer ignores a step that would leave the photo
+
+    for (let i = 0; i < 9; i++) {
+      const pov = await this.viewer.getPointOfView();
+      const delta = angleDiff(target, pov.bearing);
+      if (Math.abs(delta) <= 1) return pov.bearing;
+
+      const [cx, cy] = await this.viewer.getCenter();
+      const raw = cx + delta * slope * scale;
+      const nx = spherical ? ((raw % 1) + 1) % 1 : clamp(raw, 0, 1);
+      if (nx === cx) return pov.bearing; // already at the edge of a flat photo
+
+      this.viewer.setCenter([nx, cy]);
+      const after = await this._settle();
+      const moved = angleDiff(after.bearing, pov.bearing);
+      if (Math.abs(moved) > 0.5) {
+        slope = (nx - cx) / moved;
+        scale = 1;
+      } else if (spherical) {
+        continue;
+      } else {
+        scale /= 2;
+        if (scale < 0.05) return after.bearing; // furthest this flat photo can turn
+      }
+    }
+    return (await this.viewer.getPointOfView()).bearing;
+  }
+
+  /** Turn to face a [lng, lat] point from where you are standing. */
+  async lookAt(lngLat) {
+    assertLngLat(lngLat);
+    await this._ready;
+    const p = await this.viewer.getPosition();
+    return this.setHeading(bearingTo([p.lng, p.lat], lngLat));
+  }
+
+  /** Wait for the viewer's pan animation to finish, then return the resting point of view. */
+  async _settle() {
+    let last = await this.viewer.getPointOfView();
+    for (let i = 0; i < 25; i++) {
+      await new Promise((r) => setTimeout(r, 60));
+      const now = await this.viewer.getPointOfView();
+      const still = Math.abs(angleDiff(now.bearing, last.bearing)) < 0.05 && Math.abs(now.tilt - last.tilt) < 0.05;
+      last = now;
+      if (still && i > 0) break;
+    }
+    return last;
+  }
+
+  /** Zoom level, 0 (widest) to 3 (closest). */
+  async getZoom() {
+    await this._ready;
+    return this.viewer.getZoom();
+  }
+
+  async setZoom(level) {
+    await this._ready;
+    this.viewer.setZoom(clamp(level, 0, 3));
+  }
+
+  isFullscreen() {
+    return Boolean(this.viewer) && document.fullscreenElement === this.viewer.getContainer();
+  }
+
+  /** Enter or leave fullscreen. Resolves to the new state. */
+  async toggleFullscreen() {
+    await this._ready;
+    const el = this.viewer.getContainer();
+    if (document.fullscreenElement === el) await document.exitFullscreen();
+    else if (el.requestFullscreen) await el.requestFullscreen();
+    return this.isFullscreen();
+  }
+
+  /* ----------------------------------------------------------------- views */
+
+  /** Current photo and view direction. */
+  async getPosition() {
+    await this._ready;
+    const [image, pov] = await Promise.all([this.viewer.getImage(), this.viewer.getPointOfView()]);
+    return { ...this._describe(image), heading: pov.bearing, tilt: pov.tilt };
+  }
+
+  /**
+   * Everything a map needs to show where the viewer is and what it can see:
+   * { lngLat, heading, tilt, fov, imageId }. `fov` is the horizontal field of view in degrees.
+   */
+  async getView() {
+    await this._ready;
+    const v = this.viewer;
+    const [pos, pov, vfov, image] = await Promise.all([
+      v.getPosition(),
+      v.getPointOfView(),
+      v.getFieldOfView(),
+      v.getImage(),
+    ]);
+    const el = v.getContainer();
+    const aspect = el.clientWidth / Math.max(1, el.clientHeight);
+    const fov = clamp(toDeg(2 * Math.atan(Math.tan(toRad(vfov) / 2) * aspect)), 1, 180);
+    return { lngLat: [pos.lng, pos.lat], heading: pov.bearing, tilt: pov.tilt, fov, imageId: image.id };
+  }
+
+  _scheduleView() {
+    if (this._viewQueued) return;
+    this._viewQueued = true;
+    // A timer, not rAF: rAF stops in background tabs and would leave this flag stuck.
+    setTimeout(async () => {
+      this._viewQueued = false;
+      if (!this.viewer) return;
+      try {
+        this._emit('view', await this.getView());
+      } catch {
+        /* viewer was removed mid-update */
+      }
+    }, 16);
+  }
+
+  /** Call after the container changes size. */
+  resize() {
+    this.viewer?.resize();
+  }
+
+  /* ---------------------------------------------------------------- events */
+
+  on(type, fn) {
+    if (!this._listeners.has(type)) this._listeners.set(type, new Set());
+    this._listeners.get(type).add(fn);
+    return this;
+  }
+
+  off(type, fn) {
+    this._listeners.get(type)?.delete(fn);
+    return this;
+  }
+
+  _emit(type, payload) {
+    this._listeners.get(type)?.forEach((fn) => fn(payload));
+  }
+
+  destroy() {
+    if (this._onFullscreen) document.removeEventListener('fullscreenchange', this._onFullscreen);
+    this._listeners.clear();
+    this._footer?.remove();
+    this._footer = null;
+    this.viewer?.remove();
+    this.viewer = null;
+  }
+}
+
+export default YavqoStreets;

package/src/style.css

@@ -0,0 +1,41 @@
+@import "mapillary-js/dist/mapillary.css";
+
+.mapillary-viewer .mapillary-attribution-container {
+  visibility: hidden !important;
+  opacity: 0 !important;
+  pointer-events: none !important;
+  user-select: none !important;
+}
+
+.yavqo-streets-footer {
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 30;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 22px;
+  margin: 0;
+  padding: 0 10px;
+  box-sizing: border-box;
+  background: rgba(0, 0, 0, 0.55);
+  color: #fff;
+  font: 11px/22px system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  pointer-events: auto;
+  user-select: none;
+}
+
+.yavqo-streets-footer a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.yavqo-streets-footer a:hover {
+  text-decoration: underline;
+}
+
+.yavqo-streets-footer-sep {
+  opacity: 0.7;
+}

package/src/token.js

@@ -0,0 +1,2 @@
+// Paste your client token between the quotes before publishing. Not configurable by users.
+export const TOKEN = 'MLY|32264721886507012|55bfaa4af6bcc175ea21c8c28fc75c68';