@craft-native/ts-maps 0.0.37

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 Stacks.js
+
+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

@@ -0,0 +1,76 @@
+# @craft-native/ts-maps
+
+Craft SDK bindings for the [ts-maps](https://github.com/stacksjs/ts-maps) interactive map runtime.
+
+This package is the TypeScript side of `MapProvider.ts_maps` in Craft's Zig core. It ships a `MapView` component you can drop into any Craft app (desktop, mobile, WebView) to get a cross-platform interactive map with zero API keys.
+
+## Install
+
+```bash
+bun add @craft-native/ts-maps
+```
+
+## Quick start
+
+```ts
+import { createMapView, defaultMapConfiguration, tsMapsProvider } from '@craft-native/ts-maps'
+
+const view = createMapView({
+  configuration: { ...defaultMapConfiguration, provider: tsMapsProvider },
+  initialCamera: {
+    center: { latitude: 37.7749, longitude: -122.4194 },
+    zoom: 12,
+    pitch: 0,
+    heading: 0,
+  },
+  markers: [
+    {
+      id: 1,
+      coordinate: { latitude: 37.7749, longitude: -122.4194 },
+      title: 'San Francisco',
+      subtitle: null,
+      color: 'red',
+      is_draggable: false,
+      is_selected: false,
+      custom_icon: null,
+      anchor_x: 0.5,
+      anchor_y: 1,
+    },
+  ],
+  onTap: (coord) => console.log('tapped', coord),
+  onMarkerTap: (id, coord) => console.log('marker', id, coord),
+})
+
+document.body.appendChild(view.container)
+```
+
+## API overview
+
+| Export | What it is |
+| --- | --- |
+| `createMapView(props)` | Factory returning a `MapViewInstance` with `id`, `container`, `map`, and imperative methods (`setCamera`, `addMarker`, `fitToMarkers`, …). |
+| `MapViewProps` / `MapViewInstance` | Types for the component. |
+| `Coordinate`, `MapRegion`, `MapCamera`, `MapMarker`, … | TypeScript mirrors of the structs in `packages/zig/src/maps.zig`. Field names match exactly so JSON round-trips are free. |
+| `craftCoordToLatLng`, `latLngToCraftCoord`, `craftRegionToBounds`, `craftCameraToOptions`, `craftMarkerToMarker`, … | Pure adapter functions between Craft and ts-maps types. |
+| `tsMapsProvider` | Constant `'ts_maps'` that matches the Zig enum tag. |
+| Everything from `ts-maps` | `TsMap`, `LatLng`, `Marker`, `Polyline`, `marker()`, `tileLayer()`, etc. are re-exported so you only need one import. |
+
+## Bridge protocol
+
+When running inside a Craft WebView, `createMapView` registers itself with `getBridge()` and listens for the methods declared in `./bridge-protocol`:
+
+- `setCamera`, `setRegion`, `addMarker`, `removeMarker`, `addPolyline`, `addPolygon`, `addCircle`, `fitToMarkers`, `selectMarker`, `deselectAll`, `setConfiguration`.
+
+It emits these events back:
+
+- `map:tap`, `map:markerTap`, `map:regionChanged`, `map:cameraChanged`.
+
+If no bridge is available (browser-only, tests, etc.) the component silently falls back to local-only behavior — event callbacks passed via props still fire.
+
+## Development
+
+```bash
+bun run typecheck
+bun test
+bunx --bun pickier .
+```

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@craft-native/ts-maps",
+  "version": "0.0.37",
+  "private": false,
+  "type": "module",
+  "description": "Craft SDK bindings for the ts-maps interactive map runtime. Provides a cross-platform MapView component backed by the MapProvider.ts_maps variant in the Zig core.",
+  "author": "Chris Breuer <chris@stacksjs.org>",
+  "license": "MIT",
+  "homepage": "https://github.com/home-lang/craft#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/home-lang/craft.git",
+    "directory": "packages/ts-maps"
+  },
+  "keywords": [
+    "craft",
+    "ts-maps",
+    "maps",
+    "webview",
+    "cross-platform",
+    "native"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters.d.ts",
+      "import": "./dist/adapters.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./bridge-protocol": {
+      "types": "./dist/bridge-protocol.d.ts",
+      "import": "./dist/bridge-protocol.js"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && bun build src/index.ts src/adapters.ts src/types.ts src/bridge-protocol.ts --outdir dist --format esm --target browser && bun run build:types",
+    "build:types": "bun --bun tsc -p tsconfig.build.json && bun scripts/finalize-types.ts",
+    "lint": "bunx --bun pickier lint . --config ../../pickier.config.ts --max-warnings 9999",
+    "lint:fix": "bunx --bun pickier lint . --fix --config ../../pickier.config.ts --max-warnings 9999",
+    "test": "bun test",
+    "typecheck": "bun --bun tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "ts-maps": "^0.2.7",
+    "very-happy-dom": "^0.1.4"
+  }
+}

package/src/FilesystemTileBackend.ts

@@ -0,0 +1,243 @@
+/**
+ * Filesystem-backed tile persistence for `ts-maps` `TileCache`.
+ *
+ * Wraps Craft's `fs` bridge (which transparently falls back to `node:fs`
+ * when running outside a Craft WebView) so that tile bytes for an
+ * offline region are written to an app-sandboxed directory rather than
+ * IndexedDB. Returned objects plug straight into `TileCache` via its
+ * `backend` option.
+ *
+ * Each cached tile is serialised as a single `.tsm` file containing:
+ *
+ *   magic      4 bytes    "TSMT"
+ *   version    1 byte     0x01
+ *   keyLen     4 bytes    little-endian uint32
+ *   mimeLen    4 bytes    little-endian uint32
+ *   reservedLen 4 bytes   little-endian uint32 (0)
+ *   addedAt    8 bytes    little-endian float64 (ms epoch)
+ *   reserved   8 bytes    little-endian float64 (0)
+ *   dataLen    4 bytes    little-endian uint32
+ *   key        keyLen bytes  UTF-8
+ *   mime       mimeLen bytes UTF-8
+ *   data       dataLen bytes payload
+ *
+ * Filenames are `<hash>.tsm` where `<hash>` is a 64-bit FNV-1a of the
+ * URL (two 32-bit passes with different seeds) rendered in base36. That
+ * keeps filenames short, URL-safe, and collision-resistant enough for
+ * the tile counts an offline region realistically produces.
+ *
+ * @module @craft-native/ts-maps/FilesystemTileBackend
+ */
+
+import type { Tile, TileCacheBackend } from 'ts-maps'
+// Import the fs helpers directly from their source module rather than from
+// the `craft-native` package root, matching how `MapView` talks to
+// the bridge — keeps the type graph narrow.
+import { fs, readBinaryFile, writeBinaryFile } from '../../typescript/src/api/fs'
+
+export interface FilesystemBackendOptions {
+  /**
+   * Directory where tile files are stored. Created on first write if it
+   * doesn't exist. On Craft apps this is typically something like
+   * `app.dataDir + '/tiles'` — the caller resolves the platform-specific
+   * path and passes it in.
+   */
+  baseDir: string
+}
+
+const MAGIC = [0x54, 0x53, 0x4D, 0x54] // "TSMT"
+const VERSION = 0x01
+const FILE_SUFFIX = '.tsm'
+
+/**
+ * Construct a {@link TileCacheBackend} that persists tiles under `baseDir`.
+ * Pass the returned object to `new TileCache({ backend })` (or to the
+ * cache used by `saveOfflineRegion`).
+ */
+export function createFilesystemBackend(opts: FilesystemBackendOptions): TileCacheBackend {
+  const baseDir = stripTrailingSlash(opts.baseDir)
+  let ensured = false
+
+  async function ensureDir(): Promise<void> {
+    if (ensured)
+      return
+    if (!(await fs.exists(baseDir)))
+      await fs.mkdir(baseDir)
+    ensured = true
+  }
+
+  function filePath(key: string): string {
+    return `${baseDir}/${hashKey(key)}${FILE_SUFFIX}`
+  }
+
+  return {
+    async get(key: string): Promise<Tile | undefined> {
+      const path = filePath(key)
+      if (!(await fs.exists(path)))
+        return undefined
+      try {
+        const bytes = await readBinaryFile(path)
+        const decoded = decodeTile(bytes)
+        // Guard against FNV collisions: if the stored key doesn't match
+        // the requested URL we treat it as a miss rather than serving the
+        // wrong payload.
+        if (decoded.key !== key)
+          return undefined
+        return decoded
+      }
+      catch {
+        return undefined
+      }
+    },
+
+    async put(tile: Tile): Promise<void> {
+      await ensureDir()
+      const payload = encodeTile(tile)
+      await writeBinaryFile(filePath(tile.key), payload)
+    },
+
+    async delete(key: string): Promise<void> {
+      const path = filePath(key)
+      try {
+        if (await fs.exists(path))
+          await fs.remove(path)
+      }
+      catch {
+        // swallow: a missing tile is not an error for our caller
+      }
+    },
+
+    async clear(): Promise<void> {
+      try {
+        if (!(await fs.exists(baseDir)))
+          return
+        const entries = await fs.readDir(baseDir)
+        for (const name of entries) {
+          if (!name.endsWith(FILE_SUFFIX))
+            continue
+          try {
+            await fs.remove(`${baseDir}/${name}`)
+          }
+          catch { /* ignore per-entry failure */ }
+        }
+      }
+      catch { /* ignore */ }
+    },
+
+    async all(): Promise<Tile[]> {
+      if (!(await fs.exists(baseDir)))
+        return []
+      let entries: string[]
+      try {
+        entries = await fs.readDir(baseDir)
+      }
+      catch {
+        return []
+      }
+      const out: Tile[] = []
+      for (const name of entries) {
+        if (!name.endsWith(FILE_SUFFIX))
+          continue
+        try {
+          const bytes = await readBinaryFile(`${baseDir}/${name}`)
+          out.push(decodeTile(bytes))
+        }
+        catch {
+          // skip unreadable / corrupt entries
+        }
+      }
+      return out
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Encoding
+// ---------------------------------------------------------------------------
+
+function encodeTile(tile: Tile): Uint8Array {
+  const enc = new TextEncoder()
+  const key = enc.encode(tile.key)
+  const mime = enc.encode(tile.mime)
+  const reserved = new Uint8Array()
+
+  const headerLen = 4 + 1 + 4 + 4 + 4 + 8 + 8 + 4
+  const total = headerLen + key.length + mime.length + reserved.length + tile.data.length
+  const buf = new Uint8Array(total)
+  const view = new DataView(buf.buffer)
+
+  let o = 0
+  buf[o++] = MAGIC[0]
+  buf[o++] = MAGIC[1]
+  buf[o++] = MAGIC[2]
+  buf[o++] = MAGIC[3]
+  buf[o++] = VERSION
+  view.setUint32(o, key.length, true); o += 4
+  view.setUint32(o, mime.length, true); o += 4
+  view.setUint32(o, reserved.length, true); o += 4
+  view.setFloat64(o, tile.addedAt, true); o += 8
+  view.setFloat64(o, 0, true); o += 8
+  view.setUint32(o, tile.data.length, true); o += 4
+
+  buf.set(key, o); o += key.length
+  buf.set(mime, o); o += mime.length
+  buf.set(reserved, o); o += reserved.length
+  buf.set(tile.data, o)
+
+  return buf
+}
+
+function decodeTile(bytes: Uint8Array): Tile {
+  if (bytes.length < 37)
+    throw new Error('truncated tile record')
+  if (bytes[0] !== MAGIC[0] || bytes[1] !== MAGIC[1] || bytes[2] !== MAGIC[2] || bytes[3] !== MAGIC[3])
+    throw new Error('bad tile magic')
+  if (bytes[4] !== VERSION)
+    throw new Error(`unsupported tile version ${bytes[4]}`)
+
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  let o = 5
+  const keyLen = view.getUint32(o, true); o += 4
+  const mimeLen = view.getUint32(o, true); o += 4
+  const reservedLen = view.getUint32(o, true); o += 4
+  const addedAt = view.getFloat64(o, true); o += 8
+  o += 8
+  const dataLen = view.getUint32(o, true); o += 4
+
+  const dec = new TextDecoder()
+  const key = dec.decode(bytes.subarray(o, o + keyLen)); o += keyLen
+  const mime = dec.decode(bytes.subarray(o, o + mimeLen)); o += mimeLen
+  o += reservedLen
+  const data = bytes.subarray(o, o + dataLen).slice()
+
+  return {
+    key,
+    data,
+    mime,
+    addedAt,
+    bytes: data.length,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hash. Two FNV-1a-32 passes with different seeds — effectively a 64-bit
+// hash. Good enough for tile-scale workloads; `get()` re-verifies the
+// stored key against the request to catch the collision case.
+// ---------------------------------------------------------------------------
+
+function hashKey(key: string): string {
+  let a = 0x811C9DC5 >>> 0
+  let b = 0xCBF29CE4 >>> 0
+  for (let i = 0; i < key.length; i++) {
+    const c = key.charCodeAt(i)
+    a ^= c
+    a = Math.imul(a, 0x01000193) >>> 0
+    b ^= c
+    b = Math.imul(b, 0x00000105) >>> 0
+  }
+  return `${a.toString(36)}${b.toString(36)}`
+}
+
+function stripTrailingSlash(path: string): string {
+  return path.replace(/\/+$/, '')
+}