@navaramap/three-plugins 0.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 MapLibre contributors
+
+This project is dual-licensed under either of
+
+- Apache License, Version 2.0 (see LICENSE-APACHE)
+- MIT license (see LICENSE-MIT)
+
+at your option.

package/README.md

@@ -0,0 +1,58 @@
+# @navaramap/three-plugins
+
+Optional feature plugins for `@navaramap/three`. Each plugin packages a self-contained capability on top of the core view:
+
+- **`PersonViewPlugin`** — first-person walk mode with a controllable character (GLTF model, animations, key bindings, teleport, view-mode switching).
+- **`OverlayPlugin`** — anchors DOM elements to geographic positions and keeps them projected to screen space as the camera moves.
+- **`CesiumIonPlugin`** — resolves a Cesium Ion asset endpoint and registers the asset as a quantized-mesh terrain layer via `addTerrain()`.
+- **`TileJsonPlugin`** — fetches a TileJSON 3.0.0 document and registers it as a Navara source, surfacing its attribution through the view's built-in credit UI.
+
+## Usage
+
+Like all Navara plugins, add them before `view.init()`:
+
+```typescript
+import ThreeView from "@navaramap/three";
+import {
+  DefaultPlugin,
+  type DefaultDescriptions,
+} from "@navaramap/three-default-plugin";
+import { OverlayPlugin, moveOverlayElement } from "@navaramap/three-plugins";
+
+const view = new ThreeView<DefaultDescriptions>();
+view.addPlugin(new DefaultPlugin());
+const overlay = new OverlayPlugin();
+view.addPlugin(overlay); // must happen before init()
+await view.init();
+
+// Basemap, credited through the built-in attribution UI.
+const source = view.addSource({
+  type: "raster-tile",
+  url: "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
+  maxZoom: 18,
+});
+view.addLayer({ type: "raster", source });
+view.attribution?.add([
+  {
+    attribution: "© OpenStreetMap contributors",
+    attributionUrl: "https://www.openstreetmap.org/copyright",
+  },
+]);
+
+// Anchor a DOM element to a geographic position.
+overlay.setPositions([{ id: "tokyo", lng: 139.77, lat: 35.68, alt: 0 }]);
+overlay.onUpdate(({ projected }) => {
+  const pos = projected.get("tokyo");
+  if (pos) moveOverlayElement(markerElement, pos.x, pos.y);
+});
+```
+
+`@navaramap/three`, `@navaramap/three-default-plugin`, and `three` are peer dependencies.
+
+## Documentation
+
+Each plugin's options and events are documented at https://navara-docs.netlify.app/.
+
+## License
+
+MIT OR Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,504 @@
+import { default as default_2 } from '@navaramap/three';
+import { DefaultDescriptions } from '@navaramap/three-default-plugin';
+import { Layer } from '@navaramap/three';
+import { Plugin as Plugin_2 } from '@navaramap/three';
+import { QuantizedMeshSource } from '@navaramap/three';
+import { Source } from '@navaramap/three';
+import { TerrainSourceLayer } from '@navaramap/three';
+import { ViewContext } from '@navaramap/three';
+
+/**
+ * Animation configuration for the model.
+ * Clip names are model-specific — check your GLTF file for available clips.
+ */
+export declare type AnimationConfig = {
+    /** Clip name played while the model is idle (no movement keys held). */
+    idleClip: string;
+    /**
+     * Clip name played while the model is moving without dashing.
+     * Omit to keep `idleClip` playing while walking — useful for models
+     * that only ship with idle + dash animations.
+     */
+    walkClip?: string;
+    /** Clip name played while the model is dashing (dash key held). */
+    dashClip: string;
+    /** Playback speed multiplier. */
+    speed: number;
+    /** Duration in seconds for cross-fade transitions between clips. */
+    crossfadeDuration: number;
+};
+
+export declare type CesiumIonConfig = {
+    /** Cesium Ion asset id. */
+    assetId: number | string;
+    /** Cesium Ion access token used to resolve the asset endpoint. */
+    accessToken: string;
+    endpoint?: string;
+};
+
+export declare class CesiumIonPlugin extends Plugin_2<View_3, ViewContext> {
+    private view?;
+    private readonly config;
+    private endpoint?;
+    constructor(config: CesiumIonConfig);
+    init(view: View_3, _ctx: ViewContext): Promise<void>;
+    /**
+     * Register the resolved Cesium Ion asset as a quantized-mesh terrain layer.
+     * Must be called after `view.init()`.
+     *
+     * Internally this creates an implicit quantized-mesh source for the asset and
+     * a terrain layer that references it. The source is owned by the returned
+     * layer: deleting the layer reclaims the source too, so callers only manage
+     * the layer handle.
+     */
+    addTerrain(options?: CesiumIonTerrainOptions): Layer;
+}
+
+/**
+ * Quantized-mesh fetch/decode options forwarded to the source.
+ * The `url` and `token` fields are provided by the plugin from the resolved
+ * Cesium Ion endpoint.
+ */
+declare type CesiumIonSourceOptions = Omit<QuantizedMeshSource, "type" | "url" | "token" | "id">;
+
+/**
+ * Options for {@link CesiumIonPlugin.addTerrain}. A flat object combining the
+ * quantized-mesh source's fetch/decode options with the terrain layer's render
+ * options; the plugin routes each field to the source or the layer.
+ */
+export declare type CesiumIonTerrainOptions = CesiumIonSourceOptions & CesiumIonTerrainRenderOptions;
+
+/** Terrain mesh rendering options forwarded to the terrain layer. */
+declare type CesiumIonTerrainRenderOptions = NonNullable<TerrainSourceLayer["terrain"]>;
+
+export declare type CharacterConfig = {
+    /** URL of the GLTF model to load. */
+    modelUrl: string;
+    /** Animation clip configuration. */
+    animation: AnimationConfig;
+    /** Rotation offset to correct the model's default orientation. */
+    modelRotationOffset?: ModelRotationOffset;
+    modelScale?: number;
+    /** Hide the model while the camera is in FPV. Defaults to true. */
+    hideModelInFpv?: boolean;
+    /** Whether the character casts shadows. Defaults to false. */
+    castShadow?: boolean;
+    /** Whether the character receives shadows. Defaults to false. */
+    receiveShadow?: boolean;
+};
+
+/**
+ * Keyboard bindings. Each entry takes an array of `KeyboardEvent.code`
+ * values (e.g. `["KeyW"]`, `["ArrowUp", "ControlLeft"]`) so multiple
+ * keys can trigger the same action.
+ */
+export declare type KeyBindings = {
+    forward?: string[];
+    backward?: string[];
+    turnLeft?: string[];
+    turnRight?: string[];
+    ascend?: string[];
+    descend?: string[];
+    dash?: string[];
+    /** Hold to enable free camera (orbit) while allowCameraControl is false. */
+    orbitCamera?: string[];
+    /** Toggle between TPV and FPV. */
+    toggleView?: string[];
+};
+
+/**
+ * Model rotation offset applied to the loaded GLTF model.
+ * Different models face different directions by default, so this
+ * allows you to correct the orientation.
+ */
+export declare type ModelRotationOffset = {
+    x: number;
+    y: number;
+    z: number;
+};
+
+/**
+ * Position an absolutely-positioned HTML element using a GPU-accelerated
+ * CSS `translate()` transform.
+ */
+export declare function moveOverlayElement(el: HTMLElement, x: number, y: number): void;
+
+export declare type OverlayConfig = {
+    /** Positions farther than this (in meters) are skipped. @defaultValue `100_000` (100 km) */
+    maxDistance?: number;
+};
+
+/**
+ * Projects geographic positions to screen coordinates on every render frame.
+ *
+ * Register via `view.addPlugin(overlayPlugin)` **before** `view.init()`.
+ * The `preRender` hook is attached automatically during initialization.
+ */
+export declare class OverlayPlugin extends Plugin_2<View_2, ViewContext> {
+    private view?;
+    private maxDistance;
+    private positions;
+    private projected;
+    private listeners;
+    private boundHandler;
+    constructor(config?: OverlayConfig);
+    init(view: View_2, _ctx: ViewContext): Promise<void>;
+    /**
+     * Replace the set of world positions to track.
+     * Positions are re-projected on the next render frame automatically.
+     */
+    setPositions(positions: WorldPosition[]): void;
+    onUpdate(fn: UpdateListener): () => void;
+    dispose(): void;
+    private worldToScreen;
+    private handlePreRender;
+}
+
+export declare type OverlayState = {
+    projected: Map<string, ProjectedPosition>;
+};
+
+export declare type PersonViewConfig = {
+    character?: CharacterConfig;
+    /** When true, the camera is always free (no Alt-hold required). */
+    allowCameraControl?: boolean;
+    /** Initial view mode. */
+    initialView?: ViewMode;
+    /** m/s */
+    moveSpeed?: number;
+    /** deg/frame */
+    rotationSpeed?: number;
+    /** m/s */
+    altSpeed?: number;
+    minAlt?: number;
+    maxAlt?: number;
+    cameraDistance?: number;
+    /**
+     * Downward camera pitch in radians for **TPV**. `0` keeps the camera
+     * behind the model at eye level; positive values orbit the camera up and
+     * over so it looks down at the model while keeping it centered. Has no
+     * effect while the free camera is active (Alt-hold or `allowCameraControl`),
+     * where mouse drag controls the pitch instead.
+     */
+    cameraPitch?: number;
+    cameraLerpSpeed?: number;
+    /** Forward offset (meters) applied to the FPV eye position. */
+    fpvForwardOffset?: number;
+    /**
+     * Eye-line height offset (meters) added to the position. Used in FPV for the
+     * eye position and in TPV as the shared eye-line height the camera orbits
+     * around and aims at.
+     */
+    fpvHeightOffset?: number;
+    /**
+     * Downward camera pitch in radians for **FPV**. `0` looks straight ahead
+     * (horizontal); positive values tilt the view down in place without moving
+     * the eye. Has no effect while the free camera is active.
+     */
+    fpvPitch?: number;
+    startLat?: number;
+    startLng?: number;
+    startHeight?: number;
+    /** radians */
+    startHeading?: number;
+    keys?: KeyBindings;
+};
+
+/**
+ * Register via `view.addPlugin(plugin)` **before** `view.init()`,
+ * then call `start()` after initialization completes.
+ *
+ * ### Default controls
+ *
+ * | Key | Action |
+ * |-----|--------|
+ * | W / S | Forward / backward |
+ * | A / D | Turn left / right |
+ * | Arrow Up / Space | Climb |
+ * | Arrow Down / Ctrl | Descend |
+ * | Shift | Dash (2.5x speed) |
+ * | Alt | Free camera (when allowCameraControl is false) |
+ * | V | Toggle TPV / FPV |
+ */
+export declare class PersonViewPlugin extends Plugin_2<View, ViewContext> {
+    private view?;
+    private config;
+    private character;
+    private keys;
+    private keyToAction;
+    private handle;
+    private modelRef;
+    private animId;
+    private lastTime;
+    private state;
+    private listeners;
+    private heldActions;
+    private dashMultiplier;
+    private orbitKeyHeld;
+    private orbitLatched;
+    private currentAnimState;
+    private modelHeading;
+    private cameraHeading;
+    private viewMode;
+    /** Set to `true` to ignore all movement keys (e.g. while a modal is open). */
+    movementSuppressed: boolean;
+    private boundKeyDown;
+    private boundKeyUp;
+    private _curPos;
+    private _east;
+    private _north;
+    private _worldForward;
+    private _offset;
+    private _headingMatrix;
+    private _characterFrame;
+    constructor(config?: PersonViewConfig);
+    init(view: View, _ctx: ViewContext): Promise<void>;
+    start(): void;
+    /** Instantly move to a new geographic position. */
+    teleport(options: TeleportOptions): void;
+    getState(): PersonViewState;
+    onStateChange(fn: StateListener): () => void;
+    setViewMode(mode: ViewMode): void;
+    toggleViewMode(): void;
+    setAllowCameraControl(value: boolean): void;
+    /**
+     * Rotate the character to the given heading in radians (0 = north,
+     * increasing clockwise) without changing position. Snaps the chase camera to
+     * match; in free-camera mode only the model rotates.
+     */
+    setHeading(radians: number): void;
+    /** Current character heading in radians. */
+    getHeading(): number;
+    /**
+     * Set the downward TPV camera pitch in radians (0 = behind at eye level,
+     * positive orbits up and over the model). Takes effect immediately for the
+     * chase / locked camera.
+     */
+    setCameraPitch(radians: number): void;
+    /** Current downward TPV camera pitch in radians. */
+    getCameraPitch(): number;
+    /**
+     * Set the downward FPV camera pitch in radians (0 = horizontal, positive
+     * tilts the view down in place). Takes effect immediately for the chase /
+     * locked camera.
+     */
+    setFpvPitch(radians: number): void;
+    /** Current downward FPV camera pitch in radians. */
+    getFpvPitch(): number;
+    /**
+     * Set the FPV eye height offset in meters (added to the position to get the
+     * eye height). Also used as the shared eye-line height in TPV. Takes effect
+     * immediately for the chase / locked camera.
+     */
+    setFpvHeightOffset(meters: number): void;
+    /** Current FPV eye height offset in meters. */
+    getFpvHeightOffset(): number;
+    dispose(): void;
+    private resolveCharacter;
+    private buildKeyMap;
+    private isFreeCamera;
+    private isMovementAction;
+    private applyModelVisibility;
+    private applyInitialCamera;
+    /**
+     * Chase / locked camera placement. Caller supplies the heading (radians)
+     * to use — lerped during the per-frame loop, snapped on teleport / init.
+     *
+     * Pitch is per-mode: FPV uses `fpvPitch` and tilts the view down in place
+     * (the eye stays fixed); TPV uses `cameraPitch` and orbits the camera around
+     * the model, staying aimed at it so the model remains centered.
+     */
+    private placeChaseCamera;
+    /**
+     * Compose the character's world matrix as `ENU * Rz(-heading)`.
+     *
+     * The ENU frame already places the model at the right spot on the
+     * globe with +Z pointing world-up. Multiplying by a Z-rotation of
+     * `-heading` (negated because three.js Rz is counter-clockwise when
+     * viewed from +Z, while our heading convention is clockwise from
+     * north) bakes the heading into the world matrix.
+     *
+     * The character's `rotation` field is therefore left as the static
+     * `modelRotationOffset` only — its job is to position the model in
+     * its "facing-north, upright" rest pose. Heading then rotates the
+     * already-upright model around world-up, regardless of which axis
+     * the GLTF treats as forward.
+     */
+    private composeCharacterFrame;
+    /** Advance a (lat,lng) point by `meters` along the given ENU heading. */
+    private advanceLatLng;
+    private notify;
+    private onKeyDown;
+    private onKeyUp;
+    private tick;
+    private hasStateChanged;
+}
+
+export declare type PersonViewState = {
+    lng: number;
+    lat: number;
+    alt: number;
+    /** Heading in radians — 0 = north, increasing clockwise. */
+    heading: number;
+    speed: number;
+    /** Current animation clip name, or null when no character is configured. */
+    animationState: string | null;
+    mode: ViewMode;
+};
+
+export declare type ProjectedPosition = {
+    x: number;
+    y: number;
+    /** Distance from the camera in meters (ECEF euclidean). */
+    distance: number;
+};
+
+declare type StateListener = (s: PersonViewState) => void;
+
+/** Options for {@link PersonViewPlugin.teleport}. */
+export declare type TeleportOptions = {
+    /** Longitude in degrees. */
+    lng: number;
+    /** Latitude in degrees. */
+    lat: number;
+    /** Altitude in meters. */
+    alt: number;
+    /**
+     * Heading in radians (0 = north, increasing clockwise). If omitted, the
+     * current camera heading is kept. (Use `setHeading` to rotate in place
+     * without moving, and `setCameraPitch` / `setFpvPitch` for camera pitch.)
+     */
+    heading?: number;
+};
+
+/**
+ * The subset of a TileJSON 3.0.0 document this plugin consumes. Other spec
+ * fields (`bounds`, `center`, `grids`, ...) are ignored.
+ */
+export declare type TileJson = {
+    /** Semver of the TileJSON spec the document conforms to, e.g. `"3.0.0"`. */
+    tilejson: string;
+    /** Tile URL templates (`{z}/{x}/{y}`). Required and non-empty per the spec. */
+    tiles: string[];
+    /** Attribution/credit HTML shown through the view's attribution UI. */
+    attribution?: string;
+    /** Minimum zoom level. Applied to raster sources only. @defaultValue 0 */
+    minzoom?: number;
+    /** Maximum zoom level. @defaultValue 30 */
+    maxzoom?: number;
+    /** Tiling scheme. `"tms"` flips the Y axis (raster sources only). @defaultValue "xyz" */
+    scheme?: "xyz" | "tms";
+};
+
+/** Detail passed to the {@link TileJsonPlugin} `loaded` event. */
+export declare type TileJsonLoadedEvent = {
+    /** The Navara source created for the document. */
+    source: Source;
+    /** The fetched and validated TileJSON document. */
+    tilejson: TileJson;
+    /** The document's `attribution` HTML, when it declares one. */
+    attribution?: string;
+};
+
+export declare class TileJsonPlugin extends Plugin_2<View_4, ViewContext> {
+    private view?;
+    private readonly events;
+    /** Credits pushed into `view.attribution`, tracked so dispose() can drop them. */
+    private readonly credits;
+    init(view: View_4, _ctx: ViewContext): Promise<void>;
+    /**
+     * Subscribe to a plugin event. Use `loaded` to receive each document's
+     * attribution (and the created source) for a custom credit UI.
+     */
+    on<E extends keyof TileJsonPluginEventMap>(event: E, listener: TileJsonPluginEventMap[E]): void;
+    /** Subscribe to a plugin event for a single emission, then auto-unsubscribe. */
+    once<E extends keyof TileJsonPluginEventMap>(event: E, listener: TileJsonPluginEventMap[E]): void;
+    /** Remove a previously registered listener. */
+    off<E extends keyof TileJsonPluginEventMap>(event: E, listener: TileJsonPluginEventMap[E]): void;
+    /**
+     * Fetch a TileJSON document and register it as a single Navara source.
+     *
+     * `desc.url` is the TileJSON document URL; the plugin fetches it, then creates
+     * one source of the requested `desc.type` using the document's first tile
+     * endpoint, `minzoom`/`maxzoom`, and `scheme`. The document's `attribution` is
+     * surfaced through the view's built-in attribution UI (`view.attribution`), and
+     * a `loaded` event is emitted carrying the source, document, and attribution.
+     *
+     * A TileJSON `tiles` array lists mirror endpoints for the same tileset (as in
+     * MapLibre, which shards requests across them). Navara sources take a single
+     * URL, so only the first endpoint is used; extra endpoints are ignored with a
+     * warning.
+     *
+     * Must be called after `view.init()`. Returns the created {@link Source}
+     * handle; layers can reference it by handle or by `desc.id`.
+     */
+    addSource(desc: TileJsonSourceDescription): Promise<Source>;
+    dispose(): void;
+    private fetchTileJson;
+    /**
+     * Add a credit to the view's built-in attribution UI, deduped so repeated or
+     * shared credits render once. No-op when the built-in UI is disabled
+     * (`defaultAttribution: false`) — those callers use the `loaded` event instead.
+     */
+    private addCredit;
+}
+
+/**
+ * Events emitted by {@link TileJsonPlugin}. Subscribe via
+ * {@link TileJsonPlugin.on} / {@link TileJsonPlugin.once}.
+ */
+export declare type TileJsonPluginEventMap = {
+    /**
+     * Fired once per successful {@link TileJsonPlugin.addSource}, after the source
+     * is registered. Carries the created source, the parsed document, and its
+     * attribution so callers can drive a custom credit UI.
+     */
+    loaded: (event: TileJsonLoadedEvent) => void;
+};
+
+/**
+ * Describes a TileJSON tile source to register via {@link TileJsonPlugin.addSource}.
+ * Mirrors the shape of {@link ThreeView.addSource}, except `url` is the TileJSON
+ * document URL (not a tile template) — the plugin fetches it and derives the tile
+ * URL, zoom range, and attribution from the document.
+ */
+export declare type TileJsonSourceDescription = {
+    /** Navara source type to create, as in `addSource`. */
+    type: TileJsonSourceType;
+    /** URL of the TileJSON 3.0.0 document to fetch and expand. */
+    url: string;
+    /**
+     * Optional caller-provided source id. Handy for referencing the source from
+     * layers by id (`addLayer({ source: "<id>" })`) without holding the returned
+     * handle. When omitted, the engine generates one.
+     */
+    id?: string;
+};
+
+/**
+ * Which Navara source type a TileJSON document is materialized into. Declared by
+ * the caller because TileJSON has no field that reliably distinguishes raster
+ * imagery from vector tiles.
+ */
+export declare type TileJsonSourceType = "raster-tile" | "vector-tile";
+
+declare type UpdateListener = (state: OverlayState) => void;
+
+declare type View = default_2<DefaultDescriptions>;
+
+declare type View_2 = default_2<DefaultDescriptions>;
+
+declare type View_3 = default_2<DefaultDescriptions>;
+
+declare type View_4 = default_2<DefaultDescriptions>;
+
+export declare type ViewMode = "tpv" | "fpv";
+
+export declare type WorldPosition = {
+    id: string;
+    lng: number;
+    lat: number;
+    alt: number;
+};
+
+export { }