geoai 1.0.6 → 1.0.7

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.7] - 2026-07-17
+
+### Added
+- OpenAerialMap (OAM) map provider — HOT Imagery STAC + TiTiler (`provider: "oam"`)
+- `examples/07-oam-quickstart` — Rome orthophoto draw-to-detect demo
+- OAM option in `live-examples-nextjs` (flies to Rome; mosaic tiles)
+
+### Fixed
+- Docs Vercel prebuild: ship `remark` deps with docs and run `generate-llms-txt` from `docs/scripts/` so module resolution works when the Vercel root is `docs/`
+
 ## [1.0.6] - 2026-07-16
 
 ### Added

package/README.md

@@ -40,12 +40,12 @@ You can also use GeoAI directly in the browser via CDN:
 
 #### Unpkg CDN
 ```html
-<script src="https://unpkg.com/geoai@1.0.6/geoai.js"></script>
+<script src="https://unpkg.com/geoai@1.0.7/geoai.js"></script>
 ```
 
 #### jsDelivr CDN
 ```html
-<script src="https://cdn.jsdelivr.net/npm/geoai@1.0.6/geoai.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/geoai@1.0.7/geoai.min.js"></script>
 ```
 
 When using CDN, the library is available globally as `geoai`.
@@ -186,6 +186,17 @@ const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
 });
 ```
 
+### OpenAerialMap (OAM)
+Community aerial imagery via HOT Imagery STAC + TiTiler — no API key.
+
+```javascript
+const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
+  provider: "oam",
+  // itemId: "67826781a07cc20001818cdb", // optional pin
+  // mosaic: true, // optional: collection mosaic only
+});
+```
+
 ### ESRI
 ESRI World Imagery - no API key required.
 
@@ -231,6 +242,39 @@ const pipeline = await geoai.pipeline([{ task: "object-detection" }], {
 - [Slides (PDF)](https://geobase-docs.s3.amazonaws.com/geobase-ai-assets/talks/lightning-talk-webgpu-geoai.pdf)
 - [Slide source (Marp)](talks/lightning-talk-webgpu-geoai.md)
 
+## Agents & LLMs
+
+### Install the GeoAI agent skill
+
+Use the [Skills CLI](https://skills.sh/) so coding agents (Cursor, Claude Code, Codex, etc.) load GeoAI.js integration guidance automatically:
+
+```bash
+# Install into the current project (recommended)
+npx skills add decision-labs/geoai.js --skill geoai -y
+
+# Or install globally for all projects
+npx skills add decision-labs/geoai.js --skill geoai -g -y
+```
+
+List what you have installed:
+
+```bash
+npx skills list
+```
+
+Use the skill once without installing (pipes a prompt into an agent):
+
+```bash
+npx skills use decision-labs/geoai.js@geoai
+```
+
+Source: [`skills/geoai`](skills/geoai) — pipeline API, task picker, providers, and Web Worker patterns for background inference.
+
+### LLM-readable docs
+
+- **Index**: [docs.geobase.app/geoai/llms.txt](https://docs.geobase.app/geoai/llms.txt)
+- **Full corpus**: [docs.geobase.app/geoai/llms-full.txt](https://docs.geobase.app/geoai/llms-full.txt) — regenerate with `pnpm docs:llms`
+
 ## Links
 
 - **Documentation**: [docs.geobase.app/geoai](https://docs.geobase.app/geoai) - Comprehensive documentation, examples, and API reference

package/geoai.js

@@ -390,7 +390,7 @@ const postProcessYoloOutput = (model_outputs, pixel_values, rawImage, id2label)
   return model_output;
 };
 const parametersChanged = (instance, model_id, providerParams, modelParams) => {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r;
   if (instance.model_id !== model_id) {
     return true;
   }
@@ -425,6 +425,11 @@ const parametersChanged = (instance, model_id, providerParams, modelParams) => {
         return true;
       }
       break;
+    case "oam":
+      if (((_m = instance.providerParams) == null ? void 0 : _m.stacUrl) !== (providerParams == null ? void 0 : providerParams.stacUrl) || ((_n = instance.providerParams) == null ? void 0 : _n.rasterUrl) !== (providerParams == null ? void 0 : providerParams.rasterUrl) || ((_o = instance.providerParams) == null ? void 0 : _o.collection) !== (providerParams == null ? void 0 : providerParams.collection) || ((_p = instance.providerParams) == null ? void 0 : _p.asset) !== (providerParams == null ? void 0 : providerParams.asset) || ((_q = instance.providerParams) == null ? void 0 : _q.itemId) !== (providerParams == null ? void 0 : providerParams.itemId) || ((_r = instance.providerParams) == null ? void 0 : _r.mosaic) !== (providerParams == null ? void 0 : providerParams.mosaic)) {
+        return true;
+      }
+      break;
   }
   if (modelParams) {
     const instanceModelParams = instance.modelParams || {};
@@ -1380,6 +1385,175 @@ class Wms extends MapSource {
     );
   }
 }
+const DEFAULT_OAM_STAC_URL = "https://api.imagery.hotosm.org/stac";
+const DEFAULT_OAM_RASTER_URL = "https://api.imagery.hotosm.org/raster";
+const DEFAULT_OAM_COLLECTION = "openaerialmap";
+const DEFAULT_OAM_ASSET = "visual";
+function buildOamMosaicTileUrlTemplate(rasterUrl = DEFAULT_OAM_RASTER_URL, collection = DEFAULT_OAM_COLLECTION, asset = DEFAULT_OAM_ASSET) {
+  const base = rasterUrl.replace(/\/$/, "");
+  return `${base}/collections/${encodeURIComponent(collection)}/tiles/WebMercatorQuad/{z}/{x}/{y}?assets=${encodeURIComponent(asset)}`;
+}
+function buildOamItemTileUrlTemplate(itemId, rasterUrl = DEFAULT_OAM_RASTER_URL, collection = DEFAULT_OAM_COLLECTION, asset = DEFAULT_OAM_ASSET) {
+  const base = rasterUrl.replace(/\/$/, "");
+  return `${base}/collections/${encodeURIComponent(collection)}/items/${encodeURIComponent(itemId)}/tiles/WebMercatorQuad/{z}/{x}/{y}@1x?assets=${encodeURIComponent(asset)}`;
+}
+function pickBestOamItem(features) {
+  if (!features.length) return void 0;
+  return features.slice().sort((a, b) => {
+    var _a, _b, _c, _d, _e, _f;
+    const gsdA = typeof ((_a = a.properties) == null ? void 0 : _a.gsd) === "number" ? a.properties.gsd : Number.POSITIVE_INFINITY;
+    const gsdB = typeof ((_b = b.properties) == null ? void 0 : _b.gsd) === "number" ? b.properties.gsd : Number.POSITIVE_INFINITY;
+    if (gsdA !== gsdB) return gsdA - gsdB;
+    const dateA = Date.parse(
+      String(((_c = a.properties) == null ? void 0 : _c.created) || ((_d = a.properties) == null ? void 0 : _d.datetime) || 0)
+    );
+    const dateB = Date.parse(
+      String(((_e = b.properties) == null ? void 0 : _e.created) || ((_f = b.properties) == null ? void 0 : _f.datetime) || 0)
+    );
+    return dateB - dateA;
+  })[0];
+}
+async function searchOamItems(bbox2, options = {}) {
+  const stacUrl = (options.stacUrl || DEFAULT_OAM_STAC_URL).replace(/\/$/, "");
+  const collection = options.collection || DEFAULT_OAM_COLLECTION;
+  const limit = options.limit ?? 10;
+  const fetchImpl = options.fetchImpl || fetch;
+  const response = await fetchImpl(`${stacUrl}/search`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/geo+json",
+      ...options.headers || {}
+    },
+    body: JSON.stringify({
+      collections: [collection],
+      bbox: bbox2,
+      limit
+    })
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(
+      `OAM STAC search failed (${response.status}): ${body || response.statusText}`
+    );
+  }
+  const data = await response.json();
+  return data.features || [];
+}
+class Oam extends MapSource {
+  constructor(config = {}) {
+    super();
+    __publicField(this, "stacUrl");
+    __publicField(this, "rasterUrl");
+    __publicField(this, "collection");
+    __publicField(this, "asset");
+    __publicField(this, "itemId");
+    __publicField(this, "mosaic");
+    __publicField(this, "attribution");
+    __publicField(this, "tileSize");
+    __publicField(this, "headers");
+    /** Resolved XYZ template with `{z}/{x}/{y}` placeholders. */
+    __publicField(this, "tileUrlTemplate");
+    __publicField(this, "resolvedForBboxKey");
+    this.stacUrl = (config.stacUrl || DEFAULT_OAM_STAC_URL).replace(/\/$/, "");
+    this.rasterUrl = (config.rasterUrl || DEFAULT_OAM_RASTER_URL).replace(
+      /\/$/,
+      ""
+    );
+    this.collection = config.collection || DEFAULT_OAM_COLLECTION;
+    this.asset = config.asset || DEFAULT_OAM_ASSET;
+    this.itemId = config.itemId;
+    this.mosaic = config.mosaic === true;
+    this.attribution = config.attribution || "OpenAerialMap / HOT Imagery";
+    this.tileSize = config.tileSize || 256;
+    this.headers = config.headers;
+    if (this.itemId) {
+      this.tileUrlTemplate = buildOamItemTileUrlTemplate(
+        this.itemId,
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+    } else if (this.mosaic) {
+      this.tileUrlTemplate = buildOamMosaicTileUrlTemplate(
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+    } else {
+      this.tileUrlTemplate = buildOamMosaicTileUrlTemplate(
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+    }
+  }
+  /**
+   * Resolve tile URL template for an AOI via STAC (unless mosaic/itemId pin).
+   */
+  async resolveTileTemplate(polygon2) {
+    if (this.itemId) {
+      this.tileUrlTemplate = buildOamItemTileUrlTemplate(
+        this.itemId,
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+      return this.tileUrlTemplate;
+    }
+    if (this.mosaic) {
+      this.tileUrlTemplate = buildOamMosaicTileUrlTemplate(
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+      return this.tileUrlTemplate;
+    }
+    const bbox$1 = bbox(polygon2);
+    const bboxKey = bbox$1.map((n) => n.toFixed(6)).join(",");
+    if (this.resolvedForBboxKey === bboxKey && this.tileUrlTemplate) {
+      return this.tileUrlTemplate;
+    }
+    const features = await searchOamItems(bbox$1, {
+      stacUrl: this.stacUrl,
+      collection: this.collection,
+      headers: this.headers
+    });
+    const best = pickBestOamItem(features);
+    if (best == null ? void 0 : best.id) {
+      this.itemId = best.id;
+      this.tileUrlTemplate = buildOamItemTileUrlTemplate(
+        best.id,
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+    } else {
+      this.tileUrlTemplate = buildOamMosaicTileUrlTemplate(
+        this.rasterUrl,
+        this.collection,
+        this.asset
+      );
+    }
+    this.resolvedForBboxKey = bboxKey;
+    return this.tileUrlTemplate;
+  }
+  async getImage(polygon2, bands, expression, zoomLevel, requiresSquare = false, stitch = true) {
+    await this.resolveTileTemplate(polygon2);
+    return super.getImage(
+      polygon2,
+      bands,
+      expression,
+      zoomLevel,
+      requiresSquare,
+      stitch
+    );
+  }
+  getTileUrlFromTileCoords(tileCoords, instance) {
+    const [x, y, z] = tileCoords;
+    return instance.tileUrlTemplate.replaceAll("{z}", z.toString()).replaceAll("{x}", x.toString()).replaceAll("{y}", y.toString());
+  }
+}
 class BaseModel {
   constructor(model_id, providerParams, modelParams) {
     __publicField(this, "providerParams");
@@ -1449,6 +1623,19 @@ class BaseModel {
           extraParams: this.providerParams.extraParams
         });
         break;
+      case "oam":
+        this.dataProvider = new Oam({
+          stacUrl: this.providerParams.stacUrl,
+          rasterUrl: this.providerParams.rasterUrl,
+          collection: this.providerParams.collection,
+          asset: this.providerParams.asset,
+          itemId: this.providerParams.itemId,
+          mosaic: this.providerParams.mosaic,
+          attribution: this.providerParams.attribution,
+          tileSize: this.providerParams.tileSize,
+          headers: this.providerParams.headers
+        });
+        break;
       case "sentinel":
         throw new Error("Sentinel provider not implemented yet");
       default:

package/index.d.ts

@@ -198,10 +198,59 @@ declare class Wms extends MapSource {
 		number
 	], instance: Wms): string;
 }
+export interface OamConfig {
+	/** STAC API root (default HOT Imagery STAC). */
+	stacUrl?: string;
+	/** TiTiler / raster API root. */
+	rasterUrl?: string;
+	/** STAC collection id. */
+	collection?: string;
+	/** Asset key used for RGB tiles (default `visual`). */
+	asset?: string;
+	/**
+	 * Pin to a specific STAC item id. Skips search.
+	 * Item tiles: `/collections/{collection}/items/{itemId}/tiles/...`
+	 */
+	itemId?: string;
+	/**
+	 * When true, use the collection mosaic tile endpoint (no STAC search).
+	 * When false (default) and `itemId` is unset, search STAC for the AOI and
+	 * use the best matching item's tiles (fallback to mosaic if none found).
+	 */
+	mosaic?: boolean;
+	attribution?: string;
+	tileSize?: number;
+	headers?: Record<string, string>;
+}
+declare class Oam extends MapSource {
+	stacUrl: string;
+	rasterUrl: string;
+	collection: string;
+	asset: string;
+	itemId?: string;
+	mosaic: boolean;
+	attribution: string;
+	tileSize: number;
+	headers?: Record<string, string>;
+	/** Resolved XYZ template with `{z}/{x}/{y}` placeholders. */
+	tileUrlTemplate: string;
+	private resolvedForBboxKey?;
+	constructor(config?: OamConfig);
+	/**
+	 * Resolve tile URL template for an AOI via STAC (unless mosaic/itemId pin).
+	 */
+	resolveTileTemplate(polygon: GeoJSON.Feature): Promise<string>;
+	getImage(polygon: any, bands?: number[], expression?: string, zoomLevel?: number, requiresSquare?: boolean, stitch?: boolean): Promise<GeoRawImage | GeoRawImage[][]>;
+	protected getTileUrlFromTileCoords(tileCoords: [
+		number,
+		number,
+		number
+	], instance: Oam): string;
+}
 declare abstract class BaseModel {
 	protected static instance: BaseModel | null;
 	protected providerParams: ProviderParams;
-	protected dataProvider: Mapbox | Geobase | Esri | Tms | Wms | undefined;
+	protected dataProvider: Mapbox | Geobase | Esri | Tms | Wms | Oam | undefined;
 	protected model_id: string;
 	protected initialized: boolean;
 	protected modelParams?: PretrainedModelOptions;
@@ -568,6 +617,24 @@ export type WmsParams = {
 	headers?: Record<string, string>;
 	extraParams?: Record<string, string>;
 };
+export type OamParams = {
+	provider: "oam";
+	/** STAC API root (default https://api.imagery.hotosm.org/stac). */
+	stacUrl?: string;
+	/** Raster/TiTiler API root (default https://api.imagery.hotosm.org/raster). */
+	rasterUrl?: string;
+	/** STAC collection id (default openaerialmap). */
+	collection?: string;
+	/** Asset key for RGB tiles (default visual). */
+	asset?: string;
+	/** Pin to a specific STAC item id (skips search). */
+	itemId?: string;
+	/** Use collection mosaic tiles instead of per-item STAC search. */
+	mosaic?: boolean;
+	attribution?: string;
+	tileSize?: number;
+	headers?: Record<string, string>;
+};
 export interface InferenceInputs {
 	polygon: GeoJSON.Feature;
 	classLabel?: string;
@@ -586,7 +653,7 @@ export interface InferenceParams {
 	postProcessingParams?: PostProcessingParams;
 	mapSourceParams?: MapSourceParams;
 }
-export type ProviderParams = MapboxParams | SentinelParams | GeobaseParams | EsriParams | TmsParams | WmsParams;
+export type ProviderParams = MapboxParams | SentinelParams | GeobaseParams | EsriParams | TmsParams | WmsParams | OamParams;
 export type HuggingFaceModelTask = "mask-generation" | "zero-shot-object-detection" | "zero-shot-image-classification" | "object-detection" | "oriented-object-detection" | "image-feature-extraction";
 export type GeobaseAiModelTask = "damage-assessment" | "vegetation-classification" | "land-cover-classification" | "land-use-classification" | "land-cover-change-detection" | "land-use-change-detection" | "solar-panel-detection" | "ship-detection" | "car-detection" | "wetland-segmentation" | "building-detection" | "oil-storage-tank-detection" | "building-footprint-segmentation";
 export type ModelInstance = MaskGeneration | ZeroShotObjectDetection | ObjectDetection | OrientedObjectDetection | LandCoverClassification | SolarPanelDetection | ShipDetection | CarDetection | WetLandSegmentation | BuildingDetection | ChangeStarBuildingSegmentation | OilStorageTankDetection | BuildingFootPrintSegmentation | ImageFeatureExtraction;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geoai",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "A JavaScript library for running Geo AI models in frontend applications",
   "keywords": [
     "geoai",
@@ -63,6 +63,7 @@
     "test": "vitest",
     "test:coverage": "vitest --coverage",
     "test:build": "pnpm run build && vitest run test/build.test.ts",
+    "docs:llms": "node ./docs/scripts/generate-llms-txt.mjs",
     "lint:scripts": "eslint . --ext .ts",
     "lint:styles": "stylelint ./**/*.{css,scss}",
     "format:scripts": "prettier . --write",