@goway.to/maps 0.0.0-stage → 0.1.0

package/dist/cameraReports.web.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The web canvas's camera reports: MapLibre's `load`, `movestart`, `move` and
+ * `moveend` turned into `MapViewProps.onCameraChanged`.
+ *
+ * Its own module so it runs against a fake engine in a test (the real one
+ * needs WebGL); `MapCanvas.web.tsx` attaches it to every map it builds.
+ *
+ *  - `load`: the camera the map opened at, by the rule both forks share
+ *    (`loadedCamera.ts`).
+ *  - `move`: the live camera, throttled, never settled.
+ *  - `moveend`: a settled camera, unless it ends a frame of a caller-driven
+ *    animation (`MapCameraOptions.transient`), which `move` already reported.
+ *
+ * `source` comes from the marker GoWay puts on its own camera commands: a
+ * marked move is `programmatic` and never arms "Search this area"; so is a
+ * container resize (`moveSourceOf`).
+ */
+import type { Map as MapLibreMap } from 'maplibre-gl';
+import { PROGRAMMATIC, PROGRAMMATIC_TRANSIENT } from './moveMarkers';
+export { PROGRAMMATIC, PROGRAMMATIC_TRANSIENT };
+import type { MapMoveSource, MapCameraChange } from './types';
+/** Streaming viewport updates while a drag is in progress. */
+export declare const MOVE_THROTTLE_MS = 100;
+/**
+ * Who moved the camera: GoWay (a marked command), the engine itself because
+ * its container changed size, or — anything else — the reader.
+ *
+ * A container resize keeps the centre and zoom and changes only how much is
+ * on screen; nobody chose it, so it must neither arm "Search this area" nor
+ * end what a reader's move ends (a landmark tour).
+ */
+export declare function moveSourceOf(event: unknown): MapMoveSource;
+/**
+ * A move MapLibre made because its container was resized. Its ResizeObserver
+ * hands the observer's entries to `resize()` as the event data, so the move's
+ * events carry them — the test MapLibre's own GeolocateControl uses
+ * (`event[0] instanceof ResizeObserverEntry`).
+ */
+export declare function isContainerResize(event: unknown): boolean;
+/** A camera move a pointer, wheel, key or touch caused (MapLibre attaches it). */
+export declare function isGestureMove(event: unknown): boolean;
+export declare function isTransientMove(event: unknown): boolean;
+/** The part of a MapLibre map the reports read and listen to. */
+export type CameraEngine = Pick<MapLibreMap, 'on' | 'off' | 'getCenter' | 'getBounds' | 'getZoom' | 'getBearing' | 'getPitch'>;
+/**
+ * Report `map`'s camera to whatever `listener()` answers at the time — `null`
+ * for a caller with no `onCameraChanged` (the embed), which costs nothing.
+ * Returns the detach.
+ */
+export declare function attachCameraReports(map: CameraEngine, listener: () => ((change: MapCameraChange) => void) | null | undefined, now?: () => number): () => void;

package/dist/cameraReports.web.js

@@ -0,0 +1,117 @@
+import { createLoadedCameraReporter } from './loadedCamera';
+import { PROGRAMMATIC, PROGRAMMATIC_TRANSIENT } from './moveMarkers';
+import { runEngineCommand } from './shared';
+export { PROGRAMMATIC, PROGRAMMATIC_TRANSIENT };
+/** Streaming viewport updates while a drag is in progress. */
+export const MOVE_THROTTLE_MS = 100;
+/**
+ * Who moved the camera: GoWay (a marked command), the engine itself because
+ * its container changed size, or — anything else — the reader.
+ *
+ * A container resize keeps the centre and zoom and changes only how much is
+ * on screen; nobody chose it, so it must neither arm "Search this area" nor
+ * end what a reader's move ends (a landmark tour).
+ */
+export function moveSourceOf(event) {
+    const marked = event;
+    if (marked?.gowayProgrammatic === true)
+        return 'programmatic';
+    return isContainerResize(event) ? 'programmatic' : 'user';
+}
+/**
+ * A move MapLibre made because its container was resized. Its ResizeObserver
+ * hands the observer's entries to `resize()` as the event data, so the move's
+ * events carry them — the test MapLibre's own GeolocateControl uses
+ * (`event[0] instanceof ResizeObserverEntry`).
+ */
+export function isContainerResize(event) {
+    if (typeof ResizeObserverEntry === 'undefined')
+        return false;
+    return event?.[0] instanceof ResizeObserverEntry;
+}
+/** A camera move a pointer, wheel, key or touch caused (MapLibre attaches it). */
+export function isGestureMove(event) {
+    return event?.originalEvent != null;
+}
+export function isTransientMove(event) {
+    return event?.gowayTransient === true;
+}
+/**
+ * Report `map`'s camera to whatever `listener()` answers at the time — `null`
+ * for a caller with no `onCameraChanged` (the embed), which costs nothing.
+ * Returns the detach.
+ */
+export function attachCameraReports(map, listener, now = Date.now) {
+    let lastMoveReport = 0;
+    // This engine's one loaded-camera report (`loadedCamera.ts`). A command
+    // issued before `load` starts and ends its move before `load` too (`jumpTo`
+    // fires both synchronously; `easeTo` is still moving), so the reporter knows
+    // at `load` whether the camera is settled.
+    const loaded = createLoadedCameraReporter();
+    // `getCenter`/`getBounds` BUILD `LngLat`s out of the live transform, so a
+    // camera that has gone non-finite throws HERE — and this runs from the
+    // engine's own `move` event, which `jumpTo` fires synchronously inside
+    // whatever effect commanded it. Not reporting a viewport is a stale
+    // "Search this area"; throwing is the error boundary.
+    const read = () => {
+        let reading = null;
+        runEngineCommand('getViewport', () => {
+            const center = map.getCenter();
+            const bounds = map.getBounds();
+            reading = {
+                viewport: {
+                    latitude: center.lat,
+                    longitude: center.lng,
+                    zoom: map.getZoom(),
+                    bearing: map.getBearing(),
+                    pitch: map.getPitch(),
+                },
+                bounds: {
+                    west: bounds.getWest(),
+                    south: bounds.getSouth(),
+                    east: bounds.getEast(),
+                    north: bounds.getNorth(),
+                },
+            };
+        });
+        return reading;
+    };
+    const report = (changeOf) => {
+        const change = listener();
+        if (!change)
+            return;
+        const reading = read();
+        if (!reading)
+            return;
+        const next = changeOf(reading);
+        if (next)
+            change(next);
+    };
+    const handleLoad = () => loaded.loaded(read, listener);
+    const handleMoveStart = () => loaded.moveStarted();
+    const handleMove = (event) => {
+        const at = now();
+        if (at - lastMoveReport < MOVE_THROTTLE_MS)
+            return;
+        lastMoveReport = at;
+        report((reading) => ({ ...reading, source: moveSourceOf(event), isFinal: false }));
+    };
+    const handleMoveEnd = (event) => {
+        const transient = isTransientMove(event);
+        loaded.moveEnded(transient);
+        if (transient)
+            return;
+        lastMoveReport = 0;
+        report((reading) => ({ ...reading, source: moveSourceOf(event), isFinal: true }));
+    };
+    map.on('load', handleLoad);
+    map.on('movestart', handleMoveStart);
+    map.on('move', handleMove);
+    map.on('moveend', handleMoveEnd);
+    return () => {
+        map.off('load', handleLoad);
+        map.off('movestart', handleMoveStart);
+        map.off('move', handleMove);
+        map.off('moveend', handleMoveEnd);
+    };
+}

package/dist/cameraTarget.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The VALUE a `<Camera>` target stands for, as a string a binding can key on.
+ *
+ * A box or a point arrives as a fresh object on every render of a screen that
+ * derives it; keying on the object would re-frame the camera on every render,
+ * under a reader who has panned away. Keying on its numbers re-frames it only
+ * when the target really changed. `null` is "no target".
+ */
+import type { GeoBoundingBox, GeoCoordinate } from './types';
+export declare function cameraTargetKey(target: {
+    bounds?: GeoBoundingBox | null;
+    center?: GeoCoordinate | null;
+    zoom?: number;
+}): string | null;

package/dist/cameraTarget.js

@@ -0,0 +1,8 @@
+export function cameraTargetKey(target) {
+    const { bounds, center, zoom } = target;
+    if (bounds)
+        return `b:${bounds.west},${bounds.south},${bounds.east},${bounds.north}`;
+    if (center)
+        return `c:${center.latitude},${center.longitude},${zoom ?? ''}`;
+    return null;
+}

package/dist/chromeLift.d.ts

@@ -0,0 +1,15 @@
+import type { SharedValue } from 'react-native-reanimated';
+export interface MapChromeLift {
+    /** px to translate up, on the UI thread. */
+    lift: SharedValue<number>;
+    /** 0 … 1, on the UI thread. */
+    opacity: SharedValue<number>;
+    /**
+     * px the screen keeps for its own controls at the bottom-right ("My
+     * location"), which a full-width piece of map chrome — the time-of-day
+     * scrubber — leaves free so the two never overlap.
+     */
+    rightClearance: number;
+}
+export declare const MapChromeLiftContext: import("react").Context<MapChromeLift | null>;
+export declare function useMapChromeLift(): MapChromeLift | null;

package/dist/chromeLift.js

@@ -0,0 +1,15 @@
+/**
+ * The live lift a screen with a bottom sheet hands the map's own bottom chrome
+ * — the data credit (`MapAttribution`) — so it stays above the sheet's CURRENT
+ * top edge rather than only above its resting claim.
+ *
+ * Optional by design: a map with no provider lays the credit out against
+ * Bloom's bottom edge
+ * exactly as before. A provider can move the credit; nothing can hide it but
+ * the sheet itself covering the map.
+ */
+import { createContext, useContext } from 'react';
+export const MapChromeLiftContext = createContext(null);
+export function useMapChromeLift() {
+    return useContext(MapChromeLiftContext);
+}

package/dist/clusters.d.ts

@@ -0,0 +1,57 @@
+/**
+ * What `<Markers>` draws at a zoom: each marker, or the cluster that holds it.
+ *
+ * Mapbox clusters by SOURCE OPTIONS — `cluster`, `clusterRadius` (50),
+ * `clusterMaxZoom` (14) — and draws the result as GL layers. `<Markers>` takes
+ * the same options with the same defaults, but its markers are Bloom
+ * components (buttons with a name and a pressed state), which neither engine
+ * can draw: the GL layer's clustered features never come back to JS in time to
+ * become React views. So the clustering runs here, with Supercluster —
+ * Mapbox's own clustering library, the one Mapbox GL's `cluster: true` uses —
+ * over the same 512 px tile grid MapLibre's zoom levels are defined against,
+ * which is what makes `clusterRadius` mean the same pixels it means there.
+ *
+ * Pure, and derived in render from the data and the integer zoom: a cluster is
+ * a function of what is shown and how far in, never a piece of state.
+ *
+ * ## A pin sits where its data put it
+ *
+ * A point is drawn at the coordinate it arrived with, looked up by id — never
+ * at a position recomputed from an index — so a published coordinate is drawn
+ * at exactly the precision it was published with. A cluster has no position of
+ * its own, so its centroid is the only place it can be drawn.
+ */
+import Supercluster from 'supercluster';
+import type { GeoCoordinate, MapMarkerData, MapMarkerItem } from './types';
+export interface ClusterOptions {
+    radius: number;
+    maxZoom: number;
+    minPoints: number;
+}
+/** Mapbox's defaults (`clusterRadius` 50, `clusterMaxZoom` 14), and two points make a cluster. */
+export declare const DEFAULT_CLUSTER_OPTIONS: ClusterOptions;
+/** One thing to draw, keyed stably for React and for the engine's marker. */
+export interface MarkerSlot {
+    key: string;
+    coordinate: GeoCoordinate;
+    item: MapMarkerItem;
+    /** For a cluster: the zoom at which it splits. */
+    expansionZoom?: number;
+}
+type PointProperties = {
+    id: string;
+};
+export interface MarkerIndex {
+    /** Every marker by id. */
+    byId: ReadonlyMap<string, MapMarkerData>;
+    /** `null` when clustering is off. */
+    clusters: Supercluster<PointProperties, Supercluster.AnyProps> | null;
+}
+/** Build the index once per data set and option set. */
+export declare function indexMarkers(data: readonly MapMarkerData[], options: ClusterOptions | null): MarkerIndex;
+/**
+ * What to draw at `zoom`, with Bloom's states: the selected marker (and the
+ * cluster holding it) `active`, markers pressed before `visited`.
+ */
+export declare function markerSlotsAt(index: MarkerIndex, zoom: number, selectedId: string | null | undefined, visited: ReadonlySet<string>): MarkerSlot[];
+export {};

package/dist/clusters.js

@@ -0,0 +1,102 @@
+/**
+ * What `<Markers>` draws at a zoom: each marker, or the cluster that holds it.
+ *
+ * Mapbox clusters by SOURCE OPTIONS — `cluster`, `clusterRadius` (50),
+ * `clusterMaxZoom` (14) — and draws the result as GL layers. `<Markers>` takes
+ * the same options with the same defaults, but its markers are Bloom
+ * components (buttons with a name and a pressed state), which neither engine
+ * can draw: the GL layer's clustered features never come back to JS in time to
+ * become React views. So the clustering runs here, with Supercluster —
+ * Mapbox's own clustering library, the one Mapbox GL's `cluster: true` uses —
+ * over the same 512 px tile grid MapLibre's zoom levels are defined against,
+ * which is what makes `clusterRadius` mean the same pixels it means there.
+ *
+ * Pure, and derived in render from the data and the integer zoom: a cluster is
+ * a function of what is shown and how far in, never a piece of state.
+ *
+ * ## A pin sits where its data put it
+ *
+ * A point is drawn at the coordinate it arrived with, looked up by id — never
+ * at a position recomputed from an index — so a published coordinate is drawn
+ * at exactly the precision it was published with. A cluster has no position of
+ * its own, so its centroid is the only place it can be drawn.
+ */
+import Supercluster from 'supercluster';
+/** Mapbox's defaults (`clusterRadius` 50, `clusterMaxZoom` 14), and two points make a cluster. */
+export const DEFAULT_CLUSTER_OPTIONS = { radius: 50, maxZoom: 14, minPoints: 2 };
+/** Build the index once per data set and option set. */
+export function indexMarkers(data, options) {
+    const byId = new Map();
+    for (const marker of data)
+        byId.set(marker.id, marker);
+    if (!options)
+        return { byId, clusters: null };
+    const clusters = new Supercluster({
+        radius: options.radius,
+        maxZoom: options.maxZoom,
+        minPoints: options.minPoints,
+        // MapLibre's zoom is defined on 512 px tiles: a radius in this extent is
+        // the same number of pixels on screen.
+        extent: 512,
+    });
+    clusters.load(data.map((marker) => ({
+        type: 'Feature',
+        geometry: {
+            type: 'Point',
+            coordinates: [marker.coordinate.longitude, marker.coordinate.latitude],
+        },
+        properties: { id: marker.id },
+    })));
+    return { byId, clusters };
+}
+const WORLD = [-180, -85.051129, 180, 85.051129];
+/**
+ * What to draw at `zoom`, with Bloom's states: the selected marker (and the
+ * cluster holding it) `active`, markers pressed before `visited`.
+ */
+export function markerSlotsAt(index, zoom, selectedId, visited) {
+    const pointState = (id) => id === selectedId ? 'active' : visited.has(id) ? 'visited' : 'default';
+    if (!index.clusters) {
+        return [...index.byId.values()].map((marker) => ({
+            key: `point:${marker.id}`,
+            coordinate: marker.coordinate,
+            item: { kind: 'point', marker, state: pointState(marker.id) },
+        }));
+    }
+    const slots = [];
+    for (const feature of index.clusters.getClusters(WORLD, Math.floor(zoom))) {
+        const properties = feature.properties;
+        if (properties.cluster && typeof properties.cluster_id === 'number') {
+            const clusterId = properties.cluster_id;
+            const leaves = index.clusters.getLeaves(clusterId, Number.POSITIVE_INFINITY);
+            const markerIds = leaves.map((leaf) => String(leaf.properties.id));
+            const [longitude, latitude] = feature.geometry.coordinates;
+            const cluster = {
+                id: `cluster:${clusterId}`,
+                coordinate: { latitude, longitude },
+                count: properties.point_count ?? markerIds.length,
+                markerIds,
+            };
+            slots.push({
+                key: cluster.id,
+                coordinate: cluster.coordinate,
+                item: {
+                    kind: 'cluster',
+                    cluster,
+                    state: selectedId != null && markerIds.includes(selectedId) ? 'active' : 'default',
+                },
+                expansionZoom: index.clusters.getClusterExpansionZoom(clusterId),
+            });
+            continue;
+        }
+        const marker = properties.id !== undefined ? index.byId.get(properties.id) : undefined;
+        if (!marker)
+            continue;
+        slots.push({
+            key: `point:${marker.id}`,
+            coordinate: marker.coordinate,
+            item: { kind: 'point', marker, state: pointState(marker.id) },
+        });
+    }
+    return slots;
+}

package/dist/commands.web.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The web map's camera commands — the `MapViewRef` and `<Camera>` both move
+ * the camera through these, so the guards below are the only route a camera
+ * change takes into maplibre-gl.
+ *
+ * Every command is marked PROGRAMMATIC (`cameraReports.web.ts`), so the camera
+ * it produces is reported as the app's move and never as the reader's.
+ */
+import type { Map as MapLibreMap } from 'maplibre-gl';
+import type { MapViewRef } from './types';
+/** Zoom used when a fit has nothing with area to fit — see `isDegenerateBounds`. */
+export declare const DEGENERATE_FIT_ZOOM = 15;
+/** Breathing room, in px, around a fitted box. */
+export declare const DEFAULT_FIT_PADDING = 48;
+export declare const DEFAULT_CAMERA_DURATION_MS = 500;
+export declare function createWebMapApi(getMap: () => MapLibreMap | null): MapViewRef;

package/dist/commands.web.js

@@ -0,0 +1,158 @@
+import { boundsCenter, boundsOf, isDegenerateBounds } from '@goway.to/sdk/geo';
+import { PROGRAMMATIC, PROGRAMMATIC_TRANSIENT } from './cameraReports.web';
+import { asFinite, describeNumbers, isDrawableBounds, isDrawableCoordinate, isViewport, optionalScalar, reportMapDefect, resolvePadding, runEngineCommand, toBoundsArray, toLngLat, } from './shared';
+/** Zoom used when a fit has nothing with area to fit — see `isDegenerateBounds`. */
+export const DEGENERATE_FIT_ZOOM = 15;
+/** Breathing room, in px, around a fitted box. */
+export const DEFAULT_FIT_PADDING = 48;
+export const DEFAULT_CAMERA_DURATION_MS = 500;
+export function createWebMapApi(getMap) {
+    const api = {
+        moveTo(target, options) {
+            const map = getMap();
+            if (!map)
+                return false;
+            const coordinate = isViewport(target)
+                ? { latitude: target.latitude, longitude: target.longitude }
+                : target;
+            // Leaving the camera where it is beats throwing out of the handler that
+            // asked for the move.
+            if (!isDrawableCoordinate(coordinate)) {
+                reportMapDefect('moveTo', `Ignored moveTo: target is not drawable (${describeNumbers(coordinate)}).`);
+                return false;
+            }
+            const viewport = isViewport(target) ? target : undefined;
+            // `asFinite` on every scalar: a NaN zoom makes `transform.worldSize` NaN,
+            // and the next `getBounds()` throws `Invalid LngLat object: (NaN, NaN)`.
+            const duration = asFinite(options?.duration) ?? DEFAULT_CAMERA_DURATION_MS;
+            const marker = options?.transient ? PROGRAMMATIC_TRANSIENT : PROGRAMMATIC;
+            const camera = {
+                center: toLngLat(coordinate),
+                zoom: asFinite(options?.zoom) ?? asFinite(viewport?.zoom) ?? map.getZoom(),
+                bearing: asFinite(options?.bearing) ?? asFinite(viewport?.bearing) ?? map.getBearing(),
+                pitch: asFinite(options?.pitch) ?? asFinite(viewport?.pitch) ?? map.getPitch(),
+            };
+            // A narrower lens (and back); range-checked so a bad value leaves the
+            // lens alone rather than inverting the camera.
+            const fov = asFinite(options?.fieldOfView);
+            if (fov !== undefined && fov >= 10 && fov <= 60 && fov !== map.getVerticalFieldOfView()) {
+                runEngineCommand('setVerticalFieldOfView', () => map.setVerticalFieldOfView(fov, marker));
+            }
+            if (duration <= 0) {
+                return runEngineCommand('jumpTo', () => map.jumpTo(camera, marker));
+            }
+            return runEngineCommand('easeTo', () => map.easeTo({ ...camera, duration }, marker));
+        },
+        fitBounds(bounds, options) {
+            const map = getMap();
+            if (!map)
+                return;
+            // `isDegenerateBounds` answers `false` for a NaN box — every comparison
+            // against NaN is false — so this check comes FIRST.
+            if (!isDrawableBounds(bounds)) {
+                reportMapDefect('fitBounds', `Ignored fitBounds: box is not drawable (${describeNumbers(bounds)}).`);
+                return;
+            }
+            const padding = resolvePadding(options?.padding, DEFAULT_FIT_PADDING);
+            if (!padding)
+                return;
+            // A canvas with no size is a real state (the first frame before layout,
+            // a hidden tab): `cameraForBoxAndBearing` divides the free viewport by
+            // the box, so zero pixels is `0 / 0` and a NaN centre that throws.
+            const container = map.getContainer();
+            if (!container.clientWidth || !container.clientHeight) {
+                reportMapDefect('fitBounds:noCanvas', 'Ignored fitBounds: the canvas has no size yet.');
+                return;
+            }
+            // `maxZoom` goes straight into `Math.min(computedZoom, maxZoom)`, and
+            // `Math.min(x, undefined)` is NaN — so an absent cap must be an ABSENT
+            // key, never a present-and-undefined one (`optionalScalar`).
+            const maxZoom = asFinite(options?.maxZoom);
+            const duration = asFinite(options?.duration) ?? DEFAULT_CAMERA_DURATION_MS;
+            if (isDegenerateBounds(bounds)) {
+                const centre = boundsCenter(bounds);
+                runEngineCommand('easeTo', () => map.easeTo({
+                    center: toLngLat(centre),
+                    zoom: Math.min(maxZoom ?? DEGENERATE_FIT_ZOOM, DEGENERATE_FIT_ZOOM),
+                    duration,
+                }, PROGRAMMATIC));
+                return;
+            }
+            const [west, south, east, north] = toBoundsArray(bounds);
+            runEngineCommand('fitBounds', () => map.fitBounds([
+                [west, south],
+                [east, north],
+            ], { padding, duration, ...optionalScalar('maxZoom', maxZoom) }, PROGRAMMATIC));
+        },
+        fitCoordinates(coordinates, options) {
+            const bounds = boundsOf(coordinates);
+            if (!bounds)
+                return;
+            api.fitBounds(bounds, options);
+        },
+        setBearing(bearing, options) {
+            const heading = asFinite(bearing);
+            if (heading === undefined) {
+                reportMapDefect('setBearing', `Ignored setBearing: ${String(bearing)} is not a bearing.`);
+                return;
+            }
+            const map = getMap();
+            if (!map)
+                return;
+            runEngineCommand('easeTo', () => map.easeTo({
+                bearing: heading,
+                duration: asFinite(options?.duration) ?? DEFAULT_CAMERA_DURATION_MS,
+            }, PROGRAMMATIC));
+        },
+        resetNorth(options) {
+            const map = getMap();
+            if (!map)
+                return;
+            runEngineCommand('easeTo', () => map.easeTo({
+                bearing: 0,
+                pitch: 0,
+                duration: asFinite(options?.duration) ?? DEFAULT_CAMERA_DURATION_MS,
+            }, PROGRAMMATIC));
+        },
+        async getViewport() {
+            const map = getMap();
+            if (!map)
+                return null;
+            const center = map.getCenter();
+            return {
+                latitude: center.lat,
+                longitude: center.lng,
+                zoom: map.getZoom(),
+                bearing: map.getBearing(),
+                pitch: map.getPitch(),
+            };
+        },
+        async getBounds() {
+            const map = getMap();
+            if (!map)
+                return null;
+            const bounds = map.getBounds();
+            return {
+                west: bounds.getWest(),
+                south: bounds.getSouth(),
+                east: bounds.getEast(),
+                north: bounds.getNorth(),
+            };
+        },
+        captureFrames(draw) {
+            const map = getMap();
+            if (!map)
+                return () => { };
+            // `render` fires right after MapLibre drew the frame, in the same task —
+            // the one moment a WebGL canvas without a preserved drawing buffer can
+            // still be read.
+            const onRender = () => draw({ canvas: map.getCanvas() });
+            map.on('render', onRender);
+            map.triggerRepaint();
+            return () => {
+                map.off('render', onRender);
+            };
+        },
+    };
+    return api;
+}

package/dist/compactCredit.d.ts

@@ -0,0 +1,52 @@
+/**
+ * When the map's data credit is spelled out and when it is folded into an ⓘ
+ * button — the OSMF Attribution Guidelines' compact form
+ * (https://osmfoundation.org/wiki/Licence/Attribution_Guidelines): the credit
+ * is VISIBLE when the map loads, and may collapse once the reader has had it —
+ * after {@link CREDIT_AUTO_COLLAPSE_MS}, or at their first interaction with
+ * the map (pan, zoom, rotate, tap) — into a control in the same corner that
+ * shows it again.
+ *
+ * Pure, so "visible at load, collapsed only by those triggers" is a test
+ * (`test/compactCredit.test.ts`). `MapView` (both forks) runs it and renders
+ * `MapAttribution` from it, with no prop to turn the credit off.
+ */
+/** How long the credit stays spelled out after the map has loaded. */
+export declare const CREDIT_AUTO_COLLAPSE_MS = 5000;
+export type CreditEvent = 
+/** {@link CREDIT_AUTO_COLLAPSE_MS} have passed since the map loaded. */
+{
+    type: 'elapsed';
+}
+/** The reader moved or tapped the map (never a move the app made). */
+ | {
+    type: 'mapInteraction';
+}
+/** The reader pressed the ⓘ (or the credit's own collapse control). */
+ | {
+    type: 'toggle';
+};
+export interface CreditState {
+    expanded: boolean;
+    /**
+     * Still in the opening period, where the timer may fold it. Once the reader
+     * has pressed the control or touched the map, only they decide.
+     */
+    auto: boolean;
+}
+export declare const INITIAL_CREDIT_STATE: CreditState;
+export declare function creditReducer(state: CreditState, event: CreditEvent): CreditState;
+/**
+ * What the credit shows of a disclosure it carries (a label for simulated
+ * content, say): spelled out, the
+ * whole label as its first line; folded, its one word beside the ⓘ. In
+ * neither state is it hidden, so whatever folds the credit can never hide the
+ * label; without a disclosure, nothing.
+ */
+export declare function creditDisclosure(expanded: boolean, disclosure: {
+    text: string;
+    short: string;
+} | null): {
+    line: string | null;
+    tag: string | null;
+};

package/dist/compactCredit.js

@@ -0,0 +1,40 @@
+/**
+ * When the map's data credit is spelled out and when it is folded into an ⓘ
+ * button — the OSMF Attribution Guidelines' compact form
+ * (https://osmfoundation.org/wiki/Licence/Attribution_Guidelines): the credit
+ * is VISIBLE when the map loads, and may collapse once the reader has had it —
+ * after {@link CREDIT_AUTO_COLLAPSE_MS}, or at their first interaction with
+ * the map (pan, zoom, rotate, tap) — into a control in the same corner that
+ * shows it again.
+ *
+ * Pure, so "visible at load, collapsed only by those triggers" is a test
+ * (`test/compactCredit.test.ts`). `MapView` (both forks) runs it and renders
+ * `MapAttribution` from it, with no prop to turn the credit off.
+ */
+/** How long the credit stays spelled out after the map has loaded. */
+export const CREDIT_AUTO_COLLAPSE_MS = 5000;
+export const INITIAL_CREDIT_STATE = { expanded: true, auto: true };
+export function creditReducer(state, event) {
+    switch (event.type) {
+        case 'elapsed':
+            // A credit the reader opened themselves is not folded under them.
+            return state.auto ? { expanded: false, auto: false } : state;
+        case 'mapInteraction':
+            // Back to the map: the credit gets out of the way (and stays reachable).
+            return state.expanded || state.auto ? { expanded: false, auto: false } : state;
+        case 'toggle':
+            return { expanded: !state.expanded, auto: false };
+    }
+}
+/**
+ * What the credit shows of a disclosure it carries (a label for simulated
+ * content, say): spelled out, the
+ * whole label as its first line; folded, its one word beside the ⓘ. In
+ * neither state is it hidden, so whatever folds the credit can never hide the
+ * label; without a disclosure, nothing.
+ */
+export function creditDisclosure(expanded, disclosure) {
+    if (!disclosure)
+        return { line: null, tag: null };
+    return expanded ? { line: disclosure.text, tag: null } : { line: null, tag: disclosure.short };
+}

package/dist/creditHeight.d.ts

@@ -0,0 +1,3 @@
+import type { SharedValue } from 'react-native-reanimated';
+export declare const MapCreditHeightContext: import("react").Context<SharedValue<number> | null>;
+export declare function useMapCreditHeight(): SharedValue<number> | null;