@craft-native/ts-maps 0.0.37

package/src/bridge-protocol.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared protocol constants and types for the bridge between the Zig
+ * `MapView` core and the ts-maps runtime.
+ *
+ * @module @craft-native/ts-maps/bridge-protocol
+ */
+
+import type {
+  Coordinate,
+  MapCamera,
+  MapCircle,
+  MapConfiguration,
+  MapMarker,
+  MapPolygon,
+  MapPolyline,
+  MapRegion,
+} from './types'
+
+/**
+ * Namespace used when emitting and listening for bridge messages. Matches
+ * the Zig enum tag for `MapProvider.ts_maps`.
+ */
+export const BRIDGE_NAMESPACE = 'ts_maps' as const
+
+/** Method names the Zig core can invoke on the TypeScript side. */
+export type MapBridgeMethod =
+  | 'setCamera'
+  | 'setRegion'
+  | 'addMarker'
+  | 'removeMarker'
+  | 'addPolyline'
+  | 'addPolygon'
+  | 'addCircle'
+  | 'fitToMarkers'
+  | 'selectMarker'
+  | 'deselectAll'
+  | 'setConfiguration'
+
+/**
+ * Typed request envelope. The `method` discriminates the `params` shape.
+ * The union below gives per-method type narrowing.
+ */
+export interface MapBridgeRequest {
+  method: MapBridgeMethod
+  params: Record<string, unknown>
+}
+
+/** Strongly typed request variants for each supported method. */
+export type TypedMapBridgeRequest =
+  | { method: 'setCamera', params: { camera: MapCamera, animated?: boolean } }
+  | { method: 'setRegion', params: { region: MapRegion, animated?: boolean } }
+  | { method: 'addMarker', params: { marker: MapMarker } }
+  | { method: 'removeMarker', params: { id: number } }
+  | { method: 'addPolyline', params: { polyline: MapPolyline } }
+  | { method: 'addPolygon', params: { polygon: MapPolygon } }
+  | { method: 'addCircle', params: { circle: MapCircle } }
+  | { method: 'fitToMarkers', params: { padding?: number } }
+  | { method: 'selectMarker', params: { id: number } }
+  | { method: 'deselectAll', params: Record<string, never> }
+  | { method: 'setConfiguration', params: { configuration: MapConfiguration } }
+
+/** Events emitted by the ts-maps runtime back to the Zig core. */
+export type MapBridgeEvent =
+  | { type: 'tap', coordinate: Coordinate }
+  | { type: 'markerTap', markerId: number, coordinate: Coordinate }
+  | { type: 'regionChanged', region: MapRegion }
+  | { type: 'cameraChanged', camera: MapCamera }
+
+/**
+ * Build the full event name used on the bridge (e.g. `map:tap`).
+ * Centralized so both sides agree on the exact string.
+ */
+export function mapEventName(type: MapBridgeEvent['type']): string {
+  return `map:${type}`
+}

package/src/capabilities.ts

@@ -0,0 +1,99 @@
+/**
+ * Runtime capability probe for Craft apps hosting `ts-maps` inside a
+ * WebView. The map renderer prefers WebGL2 and falls back to Canvas2D
+ * when it isn't available; this helper exposes the probe so the host
+ * app can pick the right renderer up front (and surface the decision to
+ * users on older devices).
+ *
+ * All checks are side-effect-free and safe to call during render: the
+ * probe creates a throw-away canvas, asks for the relevant context, and
+ * discards it.
+ *
+ * @module @craft-native/ts-maps/capabilities
+ */
+
+export interface MapRendererCapabilities {
+  /** WebGL2 context is obtainable. */
+  webgl2: boolean
+  /** WebGL1 context is obtainable (fallback). */
+  webgl1: boolean
+  /** `OffscreenCanvas` exists on the global scope. */
+  offscreenCanvas: boolean
+  /** `navigator.hardwareConcurrency` — tile-worker parallelism hint. */
+  hardwareConcurrency: number
+  /** `window.devicePixelRatio` — retina-like displays report >1. */
+  devicePixelRatio: number
+  /** Pointer events are supported (required for the two-finger gestures). */
+  pointerEvents: boolean
+  /** Touch events are supported (used as a pointer-event fallback). */
+  touchEvents: boolean
+  /** Best renderer given the probe result. */
+  preferredRenderer: 'webgl' | 'canvas2d'
+}
+
+/**
+ * Probe the host runtime. Safe to call in any environment — when neither
+ * `window` nor `document` is available (Node / SSR) the probe returns a
+ * conservative zero-capabilities object.
+ */
+export function probeCapabilities(): MapRendererCapabilities {
+  if (typeof document === 'undefined' || typeof window === 'undefined') {
+    return {
+      webgl2: false,
+      webgl1: false,
+      offscreenCanvas: false,
+      hardwareConcurrency: 1,
+      devicePixelRatio: 1,
+      pointerEvents: false,
+      touchEvents: false,
+      preferredRenderer: 'canvas2d',
+    }
+  }
+
+  const canvas = document.createElement('canvas')
+  // Narrow-scope try/catch per context kind — some browsers throw
+  // `SecurityError` when a context type is blocked by a permission policy.
+  let webgl2 = false
+  let webgl1 = false
+  try {
+    const gl2 = canvas.getContext('webgl2')
+    webgl2 = gl2 !== null && gl2 !== undefined
+  }
+  catch { /* webgl2 unavailable */ }
+  if (!webgl2) {
+    try {
+      const gl1 = canvas.getContext('webgl') ?? canvas.getContext('experimental-webgl')
+      webgl1 = gl1 !== null && gl1 !== undefined
+    }
+    catch { /* webgl1 unavailable */ }
+  }
+
+  const offscreenCanvas = typeof (globalThis as any).OffscreenCanvas === 'function'
+  const nav = (globalThis as any).navigator as Navigator | undefined
+  const hardwareConcurrency = Math.max(1, Math.floor(nav?.hardwareConcurrency ?? 1))
+  const devicePixelRatio = Math.max(1, (window as any).devicePixelRatio ?? 1)
+  const pointerEvents = typeof (globalThis as any).PointerEvent === 'function'
+  const touchEvents = 'ontouchstart' in window
+    || (nav !== undefined && (nav as any).maxTouchPoints > 0)
+
+  return {
+    webgl2,
+    webgl1,
+    offscreenCanvas,
+    hardwareConcurrency,
+    devicePixelRatio,
+    pointerEvents,
+    touchEvents,
+    preferredRenderer: webgl2 ? 'webgl' : 'canvas2d',
+  }
+}
+
+/**
+ * True when the probe thinks this host can run the WebGL-backed renderer
+ * comfortably. Callers typically use this to gate advanced features like
+ * fill-extrusion or hillshade on cheap older phones.
+ */
+export function supportsAdvancedRendering(caps?: MapRendererCapabilities): boolean {
+  const probe = caps ?? probeCapabilities()
+  return probe.webgl2 && probe.hardwareConcurrency >= 2 && probe.pointerEvents
+}

package/src/index.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Smoke tests for `@craft-native/ts-maps`. Runs under Bun's `bun:test`
+ * with `very-happy-dom` providing a DOM shim (see `test/preload.ts`).
+ */
+
+import { describe, expect, it } from 'bun:test'
+import {
+  cameraToCamera,
+  coordinateFromLatLng,
+  craftCoordToLatLng,
+  latLngFromCoordinate,
+  latLngToCraftCoord,
+  regionFromBounds,
+  tsMapsProvider,
+} from './index'
+import { LatLng } from 'ts-maps'
+
+describe('tsMapsProvider', () => {
+  it('matches the Zig MapProvider.ts_maps tag', () => {
+    expect(tsMapsProvider).toBe('ts_maps')
+  })
+})
+
+describe('adapters.craftCoordToLatLng', () => {
+  it('produces a LatLng at the right coordinates', () => {
+    const ll = craftCoordToLatLng({ latitude: 40, longitude: -74 })
+    expect(ll).toBeInstanceOf(LatLng)
+    expect(ll.lat).toBe(40)
+    expect(ll.lng).toBe(-74)
+  })
+
+  it('round-trips losslessly via latLngToCraftCoord', () => {
+    const coord = { latitude: 37.7749, longitude: -122.4194 }
+    const back = latLngToCraftCoord(craftCoordToLatLng(coord))
+    expect(back.latitude).toBeCloseTo(coord.latitude, 10)
+    expect(back.longitude).toBeCloseTo(coord.longitude, 10)
+  })
+})
+
+describe('spec-named aliases', () => {
+  it('latLngFromCoordinate is an alias for craftCoordToLatLng', () => {
+    const ll = latLngFromCoordinate({ latitude: 10, longitude: 20 })
+    expect(ll.lat).toBe(10)
+    expect(ll.lng).toBe(20)
+  })
+
+  it('coordinateFromLatLng is an alias for latLngToCraftCoord', () => {
+    const coord = coordinateFromLatLng(new LatLng(1, 2))
+    expect(coord.latitude).toBe(1)
+    expect(coord.longitude).toBe(2)
+  })
+})
+
+describe('adapters.cameraToCamera', () => {
+  it('converts camera fields and re-maps heading -> bearing', () => {
+    const opts = cameraToCamera({
+      center: { latitude: 10, longitude: 20 },
+      zoom: 12,
+      pitch: 45,
+      heading: 90,
+    })
+    expect(opts.zoom).toBe(12)
+    expect(opts.pitch).toBe(45)
+    expect(opts.bearing).toBe(90)
+    expect(opts.center.lat).toBe(10)
+    expect(opts.center.lng).toBe(20)
+  })
+})
+
+describe('regionFromBounds', () => {
+  it('returns null for an empty list', () => {
+    expect(regionFromBounds([])).toBeNull()
+  })
+
+  it('centers on the midpoint and spans the delta', () => {
+    const region = regionFromBounds([
+      { latitude: 0, longitude: 0 },
+      { latitude: 10, longitude: 10 },
+    ])
+    expect(region).not.toBeNull()
+    expect(region!.center.latitude).toBe(5)
+    expect(region!.center.longitude).toBe(5)
+    expect(region!.span.latitude_delta).toBe(10)
+    expect(region!.span.longitude_delta).toBe(10)
+  })
+})
+
+describe('createMapView', () => {
+  // The DOM shim occasionally has loading issues (see preload.ts); if
+  // `document` isn't available we skip this block rather than fail.
+  const hasDom = typeof document !== 'undefined'
+  const maybe = hasDom ? it : it.skip
+
+  maybe('returns an instance with id, container, and map', async () => {
+    // Dynamic import keeps the module from being evaluated when the DOM
+    // shim couldn't register, which avoids noisy module-load errors in
+    // environments where `very-happy-dom` fails to bootstrap.
+    const { createMapView } = await import('./MapView')
+    const instance = createMapView()
+    expect(typeof instance.id).toBe('string')
+    // `very-happy-dom` returns a `VirtualElement` proxying `HTMLDivElement`,
+    // so `instanceof HTMLDivElement` fails. Feature-check the shape instead.
+    expect(instance.container).toBeDefined()
+    expect(typeof instance.container.appendChild).toBe('function')
+    expect(instance.container.tagName).toBe('DIV')
+    expect(instance.map).toBeDefined()
+    instance.destroy()
+  })
+})

package/src/index.ts

@@ -0,0 +1,109 @@
+/**
+ * `@craft-native/ts-maps` — SDK binding that lets Craft apps render
+ * interactive maps via the in-house `ts-maps` runtime. Pairs with the
+ * `MapProvider.ts_maps` variant in `packages/zig/src/maps.zig`.
+ *
+ * Re-exports the full ts-maps public API plus Craft-native helpers
+ * (`createMapView`, type mirrors, adapters, bridge protocol).
+ *
+ * @module @craft-native/ts-maps
+ */
+
+// Re-export the full ts-maps runtime so consumers only need to install a
+// single package. Consumers can `import { TsMap, marker } from '@craft-native/ts-maps'`.
+export * from 'ts-maps'
+
+// Craft-native MapView component.
+export {
+  createMapView,
+  type ComponentProps,
+  type MapViewInstance,
+  type MapViewProps,
+} from './MapView'
+
+// Type mirrors of the Zig structs.
+export {
+  defaultMapCamera,
+  defaultMapConfiguration,
+  markerColorHex,
+  strokePatternDashes,
+  type BoundingBox,
+  type Coordinate,
+  type CoordinateSpan,
+  type MapCamera,
+  type MapCircle,
+  type MapConfiguration,
+  type MapEvent,
+  type MapMarker,
+  type MapPolygon,
+  type MapPolyline,
+  type MapProvider,
+  type MapRegion,
+  type MapType,
+  type MarkerColor,
+  type StrokePattern,
+  type UserTrackingMode,
+} from './types'
+
+// Adapters (pure fns) for round-tripping between Craft and ts-maps types.
+export {
+  boundsToCraftRegion,
+  cameraToCamera,
+  craftBoundingBoxToBounds,
+  craftCameraToOptions,
+  craftCircleToCircle,
+  craftCoordToLatLng,
+  craftMarkerToMarker,
+  craftPolygonToPolygon,
+  craftPolylineToPolyline,
+  craftRegionToBounds,
+  latLngToCraftCoord,
+  regionFromBounds,
+  type TsMapsCameraOptions,
+} from './adapters'
+
+// Bridge protocol constants/types.
+export {
+  BRIDGE_NAMESPACE,
+  mapEventName,
+  type MapBridgeEvent,
+  type MapBridgeMethod,
+  type MapBridgeRequest,
+  type TypedMapBridgeRequest,
+} from './bridge-protocol'
+
+// Sandbox-filesystem tile persistence + offline region helpers.
+export {
+  createFilesystemBackend,
+  type FilesystemBackendOptions,
+} from './FilesystemTileBackend'
+export {
+  createFilesystemTileCache,
+  saveOfflineRegionToFilesystem,
+  type FilesystemOfflineRegionOptions,
+} from './offlineRegion'
+
+// Runtime capability probe — tells the host app which renderer the
+// device can realistically drive.
+export {
+  probeCapabilities,
+  supportsAdvancedRendering,
+  type MapRendererCapabilities,
+} from './capabilities'
+
+// createMap is the underlying ts-maps factory; re-export under its original
+// name for parity with the spec which mentions `createMap` as a Craft export.
+export { createMap } from 'ts-maps'
+
+/**
+ * Provider tag matching `MapProvider.ts_maps` in the Zig core. Useful when
+ * building a `MapConfiguration` programmatically without magic strings.
+ */
+export const tsMapsProvider = 'ts_maps' as const
+
+/**
+ * Alias preserved for callers that imported the two helpers by spec name.
+ * `coordinateFromLatLng(LatLng) -> Coordinate`, `latLngFromCoordinate(Coordinate) -> LatLng`.
+ */
+export { latLngToCraftCoord as coordinateFromLatLng } from './adapters'
+export { craftCoordToLatLng as latLngFromCoordinate } from './adapters'

package/src/offlineRegion.ts

@@ -0,0 +1,93 @@
+/**
+ * Thin Craft-specific wrapper around ts-maps' `saveOfflineRegion` that
+ * writes tile bytes to the app's sandboxed filesystem via the
+ * {@link createFilesystemBackend} adapter.
+ *
+ * Typical usage from a Craft app:
+ *
+ *   ```ts
+ *   import { saveOfflineRegionToFilesystem } from '@craft-native/ts-maps'
+ *   import { app } from 'craft-native'
+ *
+ *   await saveOfflineRegionToFilesystem({
+ *     baseDir: `${await app.dataDir()}/tiles`,
+ *     tileUrl: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
+ *     bounds: mapViewBounds,
+ *     zoomRange: [10, 14],
+ *   })
+ *   ```
+ *
+ * The download runs with bounded concurrency and respects `AbortSignal`,
+ * so a user canceling the region pre-cache tears the job down cleanly.
+ *
+ * @module @craft-native/ts-maps/offlineRegion
+ */
+
+import type {
+  OfflineRegionResult,
+  TileCacheOptions,
+} from 'ts-maps'
+import { saveOfflineRegion, TileCache } from 'ts-maps'
+import { createFilesystemBackend } from './FilesystemTileBackend'
+
+export type OfflineBoundsLike =
+  | { west: number, south: number, east: number, north: number }
+  | readonly [west: number, south: number, east: number, north: number]
+
+export interface OfflineProgressEmitter {
+  fire: (type: string, data?: Record<string, unknown>) => unknown
+}
+
+export interface FilesystemOfflineRegionOptions {
+  /** Sandbox directory for tile files. Created on first write. */
+  baseDir: string
+  /** Tile URL template — `{z}/{x}/{y}` placeholders are substituted. */
+  tileUrl: string
+  bounds: OfflineBoundsLike
+  zoomRange: [minZ: number, maxZ: number]
+  concurrency?: number
+  signal?: AbortSignal
+  /** Optional overrides for the `TileCache` wrapping the filesystem backend. */
+  cacheOptions?: Omit<TileCacheOptions, 'backend'>
+}
+
+/**
+ * Pre-download every tile inside `bounds` across `zoomRange` and persist
+ * it to disk under `baseDir`. Returns counts of saved / cached-already /
+ * failed tiles.
+ */
+export function saveOfflineRegionToFilesystem(
+  opts: FilesystemOfflineRegionOptions,
+  emitter?: OfflineProgressEmitter,
+): Promise<OfflineRegionResult> {
+  const cache = new TileCache({
+    ...opts.cacheOptions,
+    backend: createFilesystemBackend({ baseDir: opts.baseDir }),
+  })
+  return saveOfflineRegion(
+    {
+      bounds: opts.bounds,
+      zoomRange: opts.zoomRange,
+      tileUrl: opts.tileUrl,
+      concurrency: opts.concurrency,
+      signal: opts.signal,
+      cache,
+    },
+    emitter,
+  )
+}
+
+/**
+ * Build a standalone {@link TileCache} whose persistence layer is the
+ * Craft sandbox filesystem. Useful when a map instance needs to serve
+ * pre-saved tiles at runtime (not just pre-download them).
+ */
+export function createFilesystemTileCache(
+  baseDir: string,
+  cacheOptions?: Omit<TileCacheOptions, 'backend'>,
+): TileCache {
+  return new TileCache({
+    ...cacheOptions,
+    backend: createFilesystemBackend({ baseDir }),
+  })
+}