@tileflow/static 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,16 @@
+# @tileflow/static
+
+Static map schemas, overlay helpers, and request utilities for Tileflow static map rendering.
+
+```ts
+import { marker, validateStaticScene } from "@tileflow/static";
+
+const scene = validateStaticScene({
+  map: "madrid",
+  camera: { type: "center", center: [-3.7038, 40.4168], zoom: 12 },
+  size: { width: 1200, height: 800 },
+  overlays: [marker({ coordinate: [-3.7038, 40.4168] })],
+});
+```
+
+Docs: https://tileflow.dev/docs

package/dist/index.d.ts

@@ -0,0 +1,247 @@
+import { z } from 'zod';
+
+declare const staticSceneSchemaVersion = 1;
+declare const staticRendererSchemaVersion = 1;
+declare const staticSceneLimits: {
+    readonly maxDimension: 1280;
+    readonly maxGeoJsonBytes: 96000;
+    readonly maxOverlays: 24;
+    readonly maxPathCoordinates: 2000;
+    readonly maxPhysicalPixels: number;
+    readonly minDimension: 64;
+};
+declare const coordinateSchema: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+declare const lineOverlaySchema: z.ZodObject<{
+    color: z.ZodDefault<z.ZodString>;
+    coordinates: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    id: z.ZodOptional<z.ZodString>;
+    opacity: z.ZodDefault<z.ZodNumber>;
+    type: z.ZodLiteral<"line">;
+    width: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+declare const circleOverlaySchema: z.ZodObject<{
+    color: z.ZodDefault<z.ZodString>;
+    coordinate: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    id: z.ZodOptional<z.ZodString>;
+    opacity: z.ZodDefault<z.ZodNumber>;
+    radius: z.ZodDefault<z.ZodNumber>;
+    strokeColor: z.ZodOptional<z.ZodString>;
+    strokeWidth: z.ZodDefault<z.ZodNumber>;
+    type: z.ZodLiteral<"circle">;
+}, z.core.$strip>;
+declare const markerOverlaySchema: z.ZodObject<{
+    color: z.ZodDefault<z.ZodString>;
+    coordinate: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    id: z.ZodOptional<z.ZodString>;
+    radius: z.ZodDefault<z.ZodNumber>;
+    strokeColor: z.ZodDefault<z.ZodString>;
+    strokeWidth: z.ZodDefault<z.ZodNumber>;
+    type: z.ZodLiteral<"marker">;
+}, z.core.$strip>;
+declare const polygonOverlaySchema: z.ZodObject<{
+    coordinates: z.ZodArray<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+    fill: z.ZodDefault<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+    opacity: z.ZodDefault<z.ZodNumber>;
+    stroke: z.ZodOptional<z.ZodString>;
+    strokeWidth: z.ZodDefault<z.ZodNumber>;
+    type: z.ZodLiteral<"polygon">;
+}, z.core.$strip>;
+declare const staticOverlaySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    color: z.ZodDefault<z.ZodString>;
+    coordinates: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    id: z.ZodOptional<z.ZodString>;
+    opacity: z.ZodDefault<z.ZodNumber>;
+    type: z.ZodLiteral<"line">;
+    width: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    color: z.ZodDefault<z.ZodString>;
+    coordinate: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    id: z.ZodOptional<z.ZodString>;
+    opacity: z.ZodDefault<z.ZodNumber>;
+    radius: z.ZodDefault<z.ZodNumber>;
+    strokeColor: z.ZodOptional<z.ZodString>;
+    strokeWidth: z.ZodDefault<z.ZodNumber>;
+    type: z.ZodLiteral<"circle">;
+}, z.core.$strip>, z.ZodObject<{
+    color: z.ZodDefault<z.ZodString>;
+    coordinate: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    id: z.ZodOptional<z.ZodString>;
+    radius: z.ZodDefault<z.ZodNumber>;
+    strokeColor: z.ZodDefault<z.ZodString>;
+    strokeWidth: z.ZodDefault<z.ZodNumber>;
+    type: z.ZodLiteral<"marker">;
+}, z.core.$strip>, z.ZodObject<{
+    coordinates: z.ZodArray<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+    fill: z.ZodDefault<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+    opacity: z.ZodDefault<z.ZodNumber>;
+    stroke: z.ZodOptional<z.ZodString>;
+    strokeWidth: z.ZodDefault<z.ZodNumber>;
+    type: z.ZodLiteral<"polygon">;
+}, z.core.$strip>], "type">;
+declare const staticSceneSchema: z.ZodObject<{
+    camera: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        bearing: z.ZodOptional<z.ZodNumber>;
+        center: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+        type: z.ZodLiteral<"center">;
+        zoom: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        bearing: z.ZodOptional<z.ZodNumber>;
+        bounds: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        padding: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"bounds">;
+    }, z.core.$strip>], "type">;
+    map: z.ZodString;
+    overlays: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        color: z.ZodDefault<z.ZodString>;
+        coordinates: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        id: z.ZodOptional<z.ZodString>;
+        opacity: z.ZodDefault<z.ZodNumber>;
+        type: z.ZodLiteral<"line">;
+        width: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        color: z.ZodDefault<z.ZodString>;
+        coordinate: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+        id: z.ZodOptional<z.ZodString>;
+        opacity: z.ZodDefault<z.ZodNumber>;
+        radius: z.ZodDefault<z.ZodNumber>;
+        strokeColor: z.ZodOptional<z.ZodString>;
+        strokeWidth: z.ZodDefault<z.ZodNumber>;
+        type: z.ZodLiteral<"circle">;
+    }, z.core.$strip>, z.ZodObject<{
+        color: z.ZodDefault<z.ZodString>;
+        coordinate: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+        id: z.ZodOptional<z.ZodString>;
+        radius: z.ZodDefault<z.ZodNumber>;
+        strokeColor: z.ZodDefault<z.ZodString>;
+        strokeWidth: z.ZodDefault<z.ZodNumber>;
+        type: z.ZodLiteral<"marker">;
+    }, z.core.$strip>, z.ZodObject<{
+        coordinates: z.ZodArray<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+        fill: z.ZodDefault<z.ZodString>;
+        id: z.ZodOptional<z.ZodString>;
+        opacity: z.ZodDefault<z.ZodNumber>;
+        stroke: z.ZodOptional<z.ZodString>;
+        strokeWidth: z.ZodDefault<z.ZodNumber>;
+        type: z.ZodLiteral<"polygon">;
+    }, z.core.$strip>], "type">>>;
+    size: z.ZodObject<{
+        dpr: z.ZodOptional<z.ZodLiteral<1>>;
+        height: z.ZodNumber;
+        width: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+declare const staticRenderManifestSchema: z.ZodObject<{
+    mapId: z.ZodString;
+    rendererVersion: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    scene: z.ZodObject<{
+        camera: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            bearing: z.ZodOptional<z.ZodNumber>;
+            center: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+            type: z.ZodLiteral<"center">;
+            zoom: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            bearing: z.ZodOptional<z.ZodNumber>;
+            bounds: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+            padding: z.ZodOptional<z.ZodNumber>;
+            type: z.ZodLiteral<"bounds">;
+        }, z.core.$strip>], "type">;
+        map: z.ZodString;
+        overlays: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            color: z.ZodDefault<z.ZodString>;
+            coordinates: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            id: z.ZodOptional<z.ZodString>;
+            opacity: z.ZodDefault<z.ZodNumber>;
+            type: z.ZodLiteral<"line">;
+            width: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            color: z.ZodDefault<z.ZodString>;
+            coordinate: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+            id: z.ZodOptional<z.ZodString>;
+            opacity: z.ZodDefault<z.ZodNumber>;
+            radius: z.ZodDefault<z.ZodNumber>;
+            strokeColor: z.ZodOptional<z.ZodString>;
+            strokeWidth: z.ZodDefault<z.ZodNumber>;
+            type: z.ZodLiteral<"circle">;
+        }, z.core.$strip>, z.ZodObject<{
+            color: z.ZodDefault<z.ZodString>;
+            coordinate: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+            id: z.ZodOptional<z.ZodString>;
+            radius: z.ZodDefault<z.ZodNumber>;
+            strokeColor: z.ZodDefault<z.ZodString>;
+            strokeWidth: z.ZodDefault<z.ZodNumber>;
+            type: z.ZodLiteral<"marker">;
+        }, z.core.$strip>, z.ZodObject<{
+            coordinates: z.ZodArray<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
+            fill: z.ZodDefault<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            opacity: z.ZodDefault<z.ZodNumber>;
+            stroke: z.ZodOptional<z.ZodString>;
+            strokeWidth: z.ZodDefault<z.ZodNumber>;
+            type: z.ZodLiteral<"polygon">;
+        }, z.core.$strip>], "type">>>;
+        size: z.ZodObject<{
+            dpr: z.ZodOptional<z.ZodLiteral<1>>;
+            height: z.ZodNumber;
+            width: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    styleId: z.ZodOptional<z.ZodString>;
+    styleRevision: z.ZodString;
+    styleUrl: z.ZodString;
+}, z.core.$strip>;
+type StaticCoordinate = z.infer<typeof coordinateSchema>;
+type StaticSceneInput = z.input<typeof staticSceneSchema>;
+type StaticScene = z.infer<typeof staticSceneSchema>;
+type StaticOverlayInput = z.input<typeof staticOverlaySchema>;
+type StaticOverlay = z.infer<typeof staticOverlaySchema>;
+type StaticRenderManifest = z.infer<typeof staticRenderManifestSchema>;
+type StaticMapResult = {
+    cached: boolean;
+    hash: string;
+    imageUrl: string;
+    status: "ready";
+};
+type StaticMapCreateOptions = {
+    apiKey?: string;
+    apiUrl?: string;
+    fetch?: typeof fetch;
+};
+declare function line(input: Omit<z.input<typeof lineOverlaySchema>, "type">): StaticOverlay;
+declare function circle(input: Omit<z.input<typeof circleOverlaySchema>, "type">): StaticOverlay;
+declare function marker(input: Omit<z.input<typeof markerOverlaySchema>, "type">): StaticOverlay;
+declare function polygon(input: Omit<z.input<typeof polygonOverlaySchema>, "type">): StaticOverlay;
+declare function validateStaticScene(input: unknown): {
+    ok: true;
+    scene: StaticScene;
+} | {
+    error: string;
+    ok: false;
+};
+declare function validateStaticRenderManifest(input: unknown): {
+    manifest: StaticRenderManifest;
+    ok: true;
+} | {
+    error: string;
+    ok: false;
+};
+declare function normalizeStaticScene(scene: StaticSceneInput): StaticScene;
+declare function createRenderManifest(input: {
+    mapId: string;
+    rendererVersion: string;
+    scene: StaticSceneInput;
+    styleId?: string;
+    styleRevision: string;
+    styleUrl: string;
+}): StaticRenderManifest;
+declare function hashRenderManifest(manifest: StaticRenderManifest): Promise<string>;
+declare function compileStaticOverlays(overlays: StaticOverlay[]): {
+    layers: Record<string, unknown>[];
+    sources: Record<string, Record<string, unknown>>;
+};
+declare function createStaticMap(scene: StaticSceneInput, options?: StaticMapCreateOptions): Promise<StaticMapResult>;
+declare function stableStringify(value: unknown): string;
+
+export { type StaticCoordinate, type StaticMapCreateOptions, type StaticMapResult, type StaticOverlay, type StaticOverlayInput, type StaticRenderManifest, type StaticScene, type StaticSceneInput, circle, compileStaticOverlays, createRenderManifest, createStaticMap, hashRenderManifest, line, marker, normalizeStaticScene, polygon, stableStringify, staticOverlaySchema, staticRenderManifestSchema, staticRendererSchemaVersion, staticSceneLimits, staticSceneSchema, staticSceneSchemaVersion, validateStaticRenderManifest, validateStaticScene };

package/dist/index.js

@@ -0,0 +1,410 @@
+// src/index.ts
+import { z } from "zod";
+var staticSceneSchemaVersion = 1;
+var staticRendererSchemaVersion = 1;
+var staticSceneLimits = {
+  maxDimension: 1280,
+  maxGeoJsonBytes: 96e3,
+  maxOverlays: 24,
+  maxPathCoordinates: 2e3,
+  maxPhysicalPixels: 1280 * 1280,
+  minDimension: 64
+};
+var coordinateSchema = z.tuple([z.number().finite(), z.number().finite()]).refine(
+  ([lng, lat]) => lng >= -180 && lng <= 180 && lat >= -90 && lat <= 90,
+  {
+    message: "Expected [lng, lat] within world bounds"
+  }
+);
+var colorSchema = z.string().regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, {
+  message: "Expected a hex color like #C6A15B"
+});
+var sizeSchema = z.object({
+  dpr: z.literal(1).optional(),
+  height: z.number().int().min(staticSceneLimits.minDimension).max(staticSceneLimits.maxDimension),
+  width: z.number().int().min(staticSceneLimits.minDimension).max(staticSceneLimits.maxDimension)
+}).refine(
+  (size) => size.width * size.height * (size.dpr ?? 1) <= staticSceneLimits.maxPhysicalPixels,
+  {
+    message: "Static map exceeds the maximum render pixel budget"
+  }
+);
+var centerCameraSchema = z.object({
+  bearing: z.number().finite().min(-180).max(180).optional(),
+  center: coordinateSchema,
+  type: z.literal("center"),
+  zoom: z.number().finite().min(0).max(22)
+});
+var boundsCameraSchema = z.object({
+  bearing: z.number().finite().min(-180).max(180).optional(),
+  bounds: z.tuple([
+    z.number().finite(),
+    z.number().finite(),
+    z.number().finite(),
+    z.number().finite()
+  ]).refine(
+    ([west, south, east, north]) => west >= -180 && west <= 180 && east >= -180 && east <= 180 && south >= -90 && south <= 90 && north >= -90 && north <= 90 && west !== east && south !== north,
+    { message: "Expected bounds as [west, south, east, north]" }
+  ),
+  padding: z.number().int().min(0).max(256).optional(),
+  type: z.literal("bounds")
+}).refine((camera) => camera.bounds[3] > camera.bounds[1], {
+  message: "Bounds north must be greater than south"
+});
+var lineOverlaySchema = z.object({
+  color: colorSchema.default("#C6A15B"),
+  coordinates: z.array(coordinateSchema).min(2).max(staticSceneLimits.maxPathCoordinates),
+  id: z.string().trim().min(1).max(64).optional(),
+  opacity: z.number().finite().min(0).max(1).default(1),
+  type: z.literal("line"),
+  width: z.number().finite().min(0.5).max(32).default(4)
+});
+var circleOverlaySchema = z.object({
+  color: colorSchema.default("#C6A15B"),
+  coordinate: coordinateSchema,
+  id: z.string().trim().min(1).max(64).optional(),
+  opacity: z.number().finite().min(0).max(1).default(1),
+  radius: z.number().finite().min(1).max(64).default(6),
+  strokeColor: colorSchema.optional(),
+  strokeWidth: z.number().finite().min(0).max(16).default(0),
+  type: z.literal("circle")
+});
+var markerOverlaySchema = z.object({
+  color: colorSchema.default("#C6A15B"),
+  coordinate: coordinateSchema,
+  id: z.string().trim().min(1).max(64).optional(),
+  radius: z.number().finite().min(2).max(64).default(8),
+  strokeColor: colorSchema.default("#ffffff"),
+  strokeWidth: z.number().finite().min(0).max(16).default(2),
+  type: z.literal("marker")
+});
+var polygonOverlaySchema = z.object({
+  coordinates: z.array(
+    z.array(coordinateSchema).min(4).max(staticSceneLimits.maxPathCoordinates)
+  ).min(1).max(16),
+  fill: colorSchema.default("#C6A15B"),
+  id: z.string().trim().min(1).max(64).optional(),
+  opacity: z.number().finite().min(0).max(1).default(0.28),
+  stroke: colorSchema.optional(),
+  strokeWidth: z.number().finite().min(0).max(16).default(0),
+  type: z.literal("polygon")
+});
+var staticOverlaySchema = z.discriminatedUnion("type", [
+  lineOverlaySchema,
+  circleOverlaySchema,
+  markerOverlaySchema,
+  polygonOverlaySchema
+]);
+var staticSceneSchema = z.object({
+  camera: z.discriminatedUnion("type", [
+    centerCameraSchema,
+    boundsCameraSchema
+  ]),
+  map: z.string().trim().min(1).max(128),
+  overlays: z.array(staticOverlaySchema).max(staticSceneLimits.maxOverlays).default([]),
+  size: sizeSchema
+});
+var staticRenderManifestSchema = z.object({
+  mapId: z.string().trim().min(1).max(128),
+  rendererVersion: z.string().trim().min(1).max(64),
+  schemaVersion: z.literal(staticRendererSchemaVersion),
+  scene: staticSceneSchema,
+  styleId: z.string().trim().min(1).max(128).optional(),
+  styleRevision: z.string().trim().min(1).max(128),
+  styleUrl: z.string().trim().url().max(512).refine((value) => /^https?:\/\//.test(value), {
+    message: "Expected an http(s) style URL"
+  })
+});
+function line(input) {
+  return normalizeOverlay({ ...input, type: "line" });
+}
+function circle(input) {
+  return normalizeOverlay({ ...input, type: "circle" });
+}
+function marker(input) {
+  return normalizeOverlay({ ...input, type: "marker" });
+}
+function polygon(input) {
+  return normalizeOverlay({ ...input, type: "polygon" });
+}
+function validateStaticScene(input) {
+  const parsed = staticSceneSchema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      error: parsed.error.issues.map((issue) => `${issue.path.join(".") || "scene"}: ${issue.message}`).join("; "),
+      ok: false
+    };
+  }
+  if (jsonByteLength(parsed.data.overlays) > staticSceneLimits.maxGeoJsonBytes) {
+    return {
+      error: `overlays exceed ${staticSceneLimits.maxGeoJsonBytes} bytes`,
+      ok: false
+    };
+  }
+  return { ok: true, scene: normalizeStaticScene(parsed.data) };
+}
+function validateStaticRenderManifest(input) {
+  const parsed = staticRenderManifestSchema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      error: parsed.error.issues.map(
+        (issue) => `${issue.path.join(".") || "manifest"}: ${issue.message}`
+      ).join("; "),
+      ok: false
+    };
+  }
+  const sceneValidation = validateStaticScene(parsed.data.scene);
+  if (!sceneValidation.ok) {
+    return sceneValidation;
+  }
+  return {
+    manifest: {
+      ...parsed.data,
+      scene: sceneValidation.scene
+    },
+    ok: true
+  };
+}
+function normalizeStaticScene(scene) {
+  const parsed = staticSceneSchema.parse(scene);
+  return stripUndefined({
+    camera: parsed.camera.type === "center" ? {
+      bearing: roundNumber(parsed.camera.bearing ?? 0),
+      center: normalizeCoordinate(parsed.camera.center),
+      type: "center",
+      zoom: roundNumber(parsed.camera.zoom)
+    } : {
+      bearing: roundNumber(parsed.camera.bearing ?? 0),
+      bounds: parsed.camera.bounds.map(roundNumber),
+      padding: parsed.camera.padding ?? 32,
+      type: "bounds"
+    },
+    map: parsed.map,
+    overlays: parsed.overlays.map(
+      (overlay, index) => normalizeOverlay({
+        ...overlay,
+        id: overlay.id ?? `overlay-${index + 1}`
+      })
+    ),
+    size: {
+      dpr: parsed.size.dpr ?? 1,
+      height: parsed.size.height,
+      width: parsed.size.width
+    }
+  });
+}
+function createRenderManifest(input) {
+  return staticRenderManifestSchema.parse(
+    stripUndefined({
+      mapId: input.mapId,
+      rendererVersion: input.rendererVersion,
+      schemaVersion: staticRendererSchemaVersion,
+      scene: normalizeStaticScene({
+        ...input.scene,
+        map: input.mapId
+      }),
+      styleId: input.styleId,
+      styleRevision: input.styleRevision,
+      styleUrl: input.styleUrl
+    })
+  );
+}
+async function hashRenderManifest(manifest) {
+  const normalized = staticRenderManifestSchema.parse({
+    ...manifest,
+    scene: normalizeStaticScene(manifest.scene)
+  });
+  const bytes = new TextEncoder().encode(stableStringify(normalized));
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return base64Url(new Uint8Array(digest));
+}
+function compileStaticOverlays(overlays) {
+  const sources = {};
+  const layers = [];
+  for (const [index, overlay] of overlays.entries()) {
+    const id = safeLayerId(
+      `overlay-${index + 1}-${overlay.id ?? overlay.type}`
+    );
+    const sourceId = `${id}-source`;
+    if (overlay.type === "line") {
+      sources[sourceId] = {
+        data: feature("LineString", overlay.coordinates),
+        type: "geojson"
+      };
+      layers.push({
+        id,
+        layout: { "line-cap": "round", "line-join": "round" },
+        paint: {
+          "line-color": overlay.color,
+          "line-opacity": overlay.opacity,
+          "line-width": overlay.width
+        },
+        source: sourceId,
+        type: "line"
+      });
+      continue;
+    }
+    if (overlay.type === "polygon") {
+      sources[sourceId] = {
+        data: feature("Polygon", overlay.coordinates),
+        type: "geojson"
+      };
+      layers.push({
+        id,
+        paint: {
+          "fill-color": overlay.fill,
+          "fill-opacity": overlay.opacity
+        },
+        source: sourceId,
+        type: "fill"
+      });
+      if (overlay.stroke && overlay.strokeWidth > 0) {
+        layers.push({
+          id: `${id}-stroke`,
+          layout: { "line-cap": "round", "line-join": "round" },
+          paint: {
+            "line-color": overlay.stroke,
+            "line-width": overlay.strokeWidth
+          },
+          source: sourceId,
+          type: "line"
+        });
+      }
+      continue;
+    }
+    sources[sourceId] = {
+      data: feature("Point", overlay.coordinate),
+      type: "geojson"
+    };
+    layers.push({
+      id,
+      paint: {
+        "circle-color": overlay.color,
+        "circle-opacity": overlay.type === "circle" ? overlay.opacity : 1,
+        "circle-radius": overlay.radius,
+        "circle-stroke-color": overlay.strokeColor ?? overlay.color,
+        "circle-stroke-width": overlay.strokeWidth
+      },
+      source: sourceId,
+      type: "circle"
+    });
+  }
+  return { layers, sources };
+}
+async function createStaticMap(scene, options = {}) {
+  const validation = validateStaticScene(scene);
+  if (!validation.ok) {
+    throw new Error(`Invalid Tileflow static scene: ${validation.error}`);
+  }
+  const fetcher = options.fetch ?? fetch;
+  const apiUrl = normalizeUrl(options.apiUrl ?? "https://api.tileflow.dev");
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (options.apiKey) {
+    headers.Authorization = `Bearer ${options.apiKey}`;
+  }
+  const response = await fetcher(`${apiUrl}/v1/static/maps`, {
+    body: JSON.stringify(validation.scene),
+    headers,
+    method: "POST"
+  });
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Tileflow static map failed: ${response.status} ${error}`);
+  }
+  return await response.json();
+}
+function stableStringify(value) {
+  return JSON.stringify(sortJson(value));
+}
+function normalizeOverlay(overlay) {
+  const parsed = staticOverlaySchema.parse(overlay);
+  const normalized = stripUndefined({ ...parsed });
+  if ("coordinate" in normalized) {
+    normalized.coordinate = normalizeCoordinate(
+      normalized.coordinate
+    );
+  }
+  if ("coordinates" in normalized) {
+    normalized.coordinates = normalizeCoordinates(normalized.coordinates);
+  }
+  return normalized;
+}
+function normalizeCoordinates(value) {
+  if (!Array.isArray(value)) {
+    return value;
+  }
+  if (value.length === 2 && typeof value[0] === "number" && typeof value[1] === "number") {
+    return normalizeCoordinate(value);
+  }
+  return value.map(normalizeCoordinates);
+}
+function normalizeCoordinate(coordinate) {
+  return [roundNumber(coordinate[0]), roundNumber(coordinate[1])];
+}
+function roundNumber(value) {
+  return Number(value.toFixed(6));
+}
+function stripUndefined(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== void 0)
+  );
+}
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJson);
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, sortJson(entry)])
+    );
+  }
+  return value;
+}
+function feature(type, coordinates) {
+  return {
+    geometry: { coordinates, type },
+    properties: {},
+    type: "Feature"
+  };
+}
+function safeLayerId(value) {
+  return value.replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 80);
+}
+function jsonByteLength(value) {
+  return new TextEncoder().encode(JSON.stringify(value)).length;
+}
+function base64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function normalizeUrl(value) {
+  return value.replace(/\/+$/, "");
+}
+export {
+  circle,
+  compileStaticOverlays,
+  createRenderManifest,
+  createStaticMap,
+  hashRenderManifest,
+  line,
+  marker,
+  normalizeStaticScene,
+  polygon,
+  stableStringify,
+  staticOverlaySchema,
+  staticRenderManifestSchema,
+  staticRendererSchemaVersion,
+  staticSceneLimits,
+  staticSceneSchema,
+  staticSceneSchemaVersion,
+  validateStaticRenderManifest,
+  validateStaticScene
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@tileflow/static",
+  "version": "0.1.0-alpha.0",
+  "description": "Static map request schemas and helpers for Tileflow.",
+  "type": "module",
+  "homepage": "https://tileflow.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tileflow/tileflow.git",
+    "directory": "packages/static"
+  },
+  "bugs": {
+    "url": "https://github.com/tileflow/tileflow/issues"
+  },
+  "keywords": [
+    "tileflow",
+    "maps",
+    "static-maps",
+    "maplibre",
+    "tiles"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  }
+}