@tileflow/static 0.1.0-alpha.20 → 0.1.0-alpha.21

package/README.md

@@ -20,7 +20,7 @@ import {
 const scene = validateStaticScene({
   map: 'madrid',
   theme: 'dark',
-  camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
+  camera: {type: 'auto', padding: 24},
   size: {width: 1200, height: 800},
   overlays: [marker({coordinate: [-3.7038, 40.4168]})],
 });
@@ -33,6 +33,43 @@ await precacheStaticMap(scene.scene, {
 });
 ```
 
+## Automatic framing
+
+`camera.type: 'auto'` fits the complete nominal footprint of every declared marker, circle, line,
+and polygon. It works with Mercator and Globe styles when the geometry can be shown. It never clips
+silently.
+
+```ts
+camera: {
+  type: 'auto',
+  padding: {top: 24, right: 240, bottom: 24, left: 24},
+  maxZoom: 16,
+  bearing: 0,
+}
+```
+
+Padding uses logical CSS pixels. A number applies to every side; omitted sides in an object are
+zero. Without `padding`, Tileflow uses `min(32, ceil(5% * min(width, height)))`. `maxZoom` defaults
+to 16 and `bearing` to 0. A single position still honors asymmetric padding, so its apparent center
+can move away from the viewport center.
+
+Point-like overlays around ±180° use the shortest longitude interval. Tileflow never reinterprets
+vertices inside a line or polygon: an ambiguous crossing returns an error. Represent a correctly
+cut `MultiLineString` or `MultiPolygon` as several `line` or `polygon` overlays with identical
+styles; auto-fit may move each complete component to an adjacent world copy.
+
+Current overlay primitives use MapLibre's GeoJSON pipeline and require
+`abs(latitude) <= MAX_OVERLAY_LATITUDE` (`85.051129`). Tileflow rejects larger latitudes instead of
+clamping them. A Globe basemap may display polar regions even though these overlay primitives cannot
+yet be drawn there.
+
+Deterministic request failures return `422`, set `retryable: false`, and preserve a stable code,
+reason, and bounded details. `validateStaticScene` returns that document; request helpers throw
+`StaticMapRequestError` either locally or from the Hosted response. The reasons distinguish an empty
+scene, an ambiguous antimeridian path, an out-of-range overlay latitude, an insufficient viewport,
+a Globe visibility conflict, an unresolvable camera, and failed post-fit containment. Correct the
+scene; do not retry it unchanged.
+
 The package has four deliberately separate surfaces, all available from the root for compatibility:
 
 - scene validation and normalization: `staticSceneSchema`, `validateStaticScene`, and

package/dist/{chunk-QCR76BUO.js → chunk-A23RC4BE.js}

@@ -1,10 +1,12 @@
 import {
+  StaticMapRequestError,
+  staticMapRequestErrorResponseSchema,
   validateStaticScene
-} from "./chunk-ROBEGDDY.js";
+} from "./chunk-NHQK5UZ2.js";
 import {
   isSafeHttpUrl,
   stableStringify
-} from "./chunk-YUG3PBK2.js";
+} from "./chunk-MGQCHCU3.js";
 
 // src/client.ts
 import { z } from "zod";
@@ -44,6 +46,10 @@ function createStaticMapIdempotencyKey() {
 function prepareStaticMapRequest(scene) {
   const validation = validateStaticScene(scene);
   if (!validation.ok) {
+    if (isStaticMapRequestFailure(validation)) {
+      const { ok: _ok, ...response } = validation;
+      throw new StaticMapRequestError(response);
+    }
     throw new Error(`Invalid Tileflow static scene: ${validation.error}`);
   }
   const prepared = Object.freeze({
@@ -103,8 +109,11 @@ async function requestStaticMapUntilReady(request, options) {
       });
       throwIfAborted(signal);
       if (!response.ok) {
-        await discardBoundedResponse(response, 8 * 1024);
+        const requestError = response.status === 422 ? await readStaticMapRequestErrorResponse(response, 8 * 1024) : await discardBoundedResponse(response, 8 * 1024);
         throwIfAborted(signal);
+        if (requestError) {
+          throw new StaticMapRequestError(requestError, response.status);
+        }
         throw new Error(`Tileflow static map failed (${response.status}).`);
       }
       const json = await readJsonResponse(response);
@@ -148,11 +157,26 @@ async function readJsonResponse(response) {
     throw new Error("Tileflow static map returned an invalid response: expected JSON");
   }
 }
+async function readStaticMapRequestErrorResponse(response, maximumBytes) {
+  try {
+    const source = await readBoundedResponseText(response, maximumBytes, `${maximumBytes} bytes`);
+    const parsed = staticMapRequestErrorResponseSchema.safeParse(JSON.parse(source));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
 async function discardBoundedResponse(response, maximumBytes) {
   try {
     await readBoundedResponseText(response, maximumBytes, `${maximumBytes} bytes`);
   } catch {
   }
+  return null;
+}
+function isStaticMapRequestFailure(value) {
+  if (!("code" in value)) return false;
+  const { ok: _ok, ...response } = value;
+  return staticMapRequestErrorResponseSchema.safeParse(response).success;
 }
 async function readBoundedResponseText(response, maximumBytes, displayLimit) {
   if (!response.body) return "";

package/dist/{chunk-LGEYA6FQ.js → chunk-KPT7PASB.js}

@@ -1,6 +1,7 @@
 import {
-  normalizeStaticOverlay
-} from "./chunk-YUG3PBK2.js";
+  normalizeStaticOverlay,
+  roundNumber
+} from "./chunk-MGQCHCU3.js";
 
 // src/overlays.ts
 function line(input) {
@@ -15,15 +16,23 @@ function marker(input) {
 function polygon(input) {
   return normalizeStaticOverlay({ ...input, type: "polygon" });
 }
-function compileStaticOverlays(overlays) {
+function compileStaticOverlays(overlays, options = {}) {
+  if (options.longitudeOffsets !== void 0 && (options.longitudeOffsets.length !== overlays.length || options.longitudeOffsets.some(
+    (offset) => !Number.isInteger(offset) || Math.abs(offset) > 360 || offset % 360 !== 0
+  ))) {
+    throw new Error(
+      "Static overlay longitude offsets must contain one -360, 0, or 360 per overlay"
+    );
+  }
   const sources = {};
   const layers = [];
   for (const [index, overlay] of overlays.entries()) {
+    const longitudeOffset = options.longitudeOffsets?.[index] ?? 0;
     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),
+        data: feature("LineString", shiftLongitudes(overlay.coordinates, longitudeOffset)),
         type: "geojson"
       };
       layers.push({
@@ -41,7 +50,7 @@ function compileStaticOverlays(overlays) {
     }
     if (overlay.type === "polygon") {
       sources[sourceId] = {
-        data: feature("Polygon", overlay.coordinates),
+        data: feature("Polygon", shiftLongitudes(overlay.coordinates, longitudeOffset)),
         type: "geojson"
       };
       layers.push({
@@ -68,7 +77,7 @@ function compileStaticOverlays(overlays) {
       continue;
     }
     sources[sourceId] = {
-      data: feature("Point", overlay.coordinate),
+      data: feature("Point", shiftLongitudes(overlay.coordinate, longitudeOffset)),
       type: "geojson"
     };
     layers.push({
@@ -86,6 +95,13 @@ function compileStaticOverlays(overlays) {
   }
   return { layers, sources };
 }
+function shiftLongitudes(value, offset) {
+  if (!Array.isArray(value)) return value;
+  if (value.length === 2 && typeof value[0] === "number" && typeof value[1] === "number") {
+    return [roundNumber(value[0] + offset), value[1]];
+  }
+  return value.map((entry) => shiftLongitudes(entry, offset));
+}
 function feature(type, coordinates) {
   return {
     geometry: { coordinates, type },

package/dist/{chunk-YUG3PBK2.js → chunk-MGQCHCU3.js}

@@ -49,6 +49,7 @@ function base64Url(bytes) {
 // src/scene-contract.ts
 import { z } from "zod";
 var staticSceneSchemaVersion = 1;
+var MAX_OVERLAY_LATITUDE = 85.051129;
 var staticSceneLimits = {
   maxDimension: 1280,
   maxGeoJsonBytes: 96e3,
@@ -60,6 +61,12 @@ var staticSceneLimits = {
 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 overlayCoordinateSchema = coordinateSchema.refine(
+  ([, latitude]) => Math.abs(latitude) <= MAX_OVERLAY_LATITUDE,
+  {
+    message: `Static overlay latitude must be within \xB1${MAX_OVERLAY_LATITUDE}\xB0`
+  }
+);
 var colorSchema = z.string().regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, {
   message: "Expected a hex color like #C6A15B"
 });
@@ -99,9 +106,30 @@ var boundsCameraSchema = z.object({
 }).refine((camera) => camera.bounds[3] > camera.bounds[1], {
   message: "Bounds north must be greater than south"
 });
+var staticPaddingSchema = z.object({
+  bottom: z.number().int().nonnegative(),
+  left: z.number().int().nonnegative(),
+  right: z.number().int().nonnegative(),
+  top: z.number().int().nonnegative()
+}).strict();
+var autoPaddingInputSchema = z.union([
+  z.number().int().nonnegative(),
+  z.object({
+    bottom: z.number().int().nonnegative().optional(),
+    left: z.number().int().nonnegative().optional(),
+    right: z.number().int().nonnegative().optional(),
+    top: z.number().int().nonnegative().optional()
+  }).strict()
+]);
+var autoCameraSchema = z.object({
+  bearing: z.number().finite().min(-180).max(180).optional(),
+  maxZoom: z.number().finite().min(0).max(22).optional(),
+  padding: autoPaddingInputSchema.optional(),
+  type: z.literal("auto")
+});
 var lineOverlaySchema = z.object({
   color: colorSchema.default("#C6A15B"),
-  coordinates: z.array(coordinateSchema).min(2).max(staticSceneLimits.maxPathCoordinates),
+  coordinates: z.array(overlayCoordinateSchema).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"),
@@ -109,7 +137,7 @@ var lineOverlaySchema = z.object({
 });
 var circleOverlaySchema = z.object({
   color: colorSchema.default("#C6A15B"),
-  coordinate: coordinateSchema,
+  coordinate: overlayCoordinateSchema,
   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),
@@ -119,14 +147,14 @@ var circleOverlaySchema = z.object({
 });
 var markerOverlaySchema = z.object({
   color: colorSchema.default("#C6A15B"),
-  coordinate: coordinateSchema,
+  coordinate: overlayCoordinateSchema,
   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 polygonRingSchema = z.array(coordinateSchema).min(4).max(staticSceneLimits.maxPathCoordinates).refine(
+var polygonRingSchema = z.array(overlayCoordinateSchema).min(4).max(staticSceneLimits.maxPathCoordinates).refine(
   (ring) => {
     const first = ring[0];
     const last = ring[ring.length - 1];
@@ -150,7 +178,7 @@ var staticOverlaySchema = z.discriminatedUnion("type", [
   polygonOverlaySchema
 ]);
 var staticSceneSchema = z.object({
-  camera: z.discriminatedUnion("type", [centerCameraSchema, boundsCameraSchema]),
+  camera: z.discriminatedUnion("type", [centerCameraSchema, boundsCameraSchema, autoCameraSchema]),
   map: portableIdSchema,
   overlays: z.array(staticOverlaySchema).max(staticSceneLimits.maxOverlays).default([]),
   size: sizeSchema,
@@ -190,7 +218,9 @@ export {
   hashStableValue,
   isSafeHttpUrl,
   staticSceneSchemaVersion,
+  MAX_OVERLAY_LATITUDE,
   staticSceneLimits,
+  staticPaddingSchema,
   staticOverlaySchema,
   staticSceneSchema,
   normalizeStaticOverlay,