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

package/README.md

@@ -20,43 +20,133 @@ import {
 const scene = validateStaticScene({
   map: 'madrid',
   theme: 'dark',
-  camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
-  size: {width: 1200, height: 800},
+  format: 'webp',
+  camera: {type: 'auto', padding: 24},
+  size: {width: 600, height: 400, dpr: 2},
   overlays: [marker({coordinate: [-3.7038, 40.4168]})],
 });
 
 if (!scene.ok) throw new Error(scene.error);
 
-await precacheStaticMap(scene.scene, {
+const result = await precacheStaticMap(scene.scene, {
   apiKey: process.env.TILEFLOW_API_KEY,
   idempotencyKey: createStaticMapIdempotencyKey(),
 });
+
+console.log(result.attribution.entries);
+```
+
+`width` and `height` are logical CSS pixels. `dpr` accepts 1 or 2 and defaults to 1, so a 600 by
+400 scene at DPR 2 produces a 1200 by 800 image without changing camera, padding, or overlay paint
+sizes. Logical dimensions may reach 2048 per axis; the physical budget permits 4096 by 4096 output,
+or 16,777,216 total pixels.
+
+`format` accepts `png`, `jpeg`, or `webp` and defaults to PNG. PNG's canonical default stays omitted,
+so explicit and omitted PNG requests share identity. JPEG and WebP use a fixed encoder quality;
+there is no public quality option.
+
+## Attribution
+
+New renders default to `attribution: {mode: 'embedded', position: 'auto'}` without adding that
+omitted default to the normalized scene. Hosted derives notices from the sources referenced by the
+exact selected Style and embeds a safe, compact block. Automatic placement prefers an unobstructed
+corner, then the least interfering corner among declared request overlays. Explicit center and
+bounds cameras never move.
+
+Choose a corner when composition requires it:
+
+```ts
+attribution: {mode: 'embedded', position: 'bottom-left'}
+```
+
+Or request structured external attribution:
+
+```ts
+const result = await createStaticMap(
+  {...scene.scene, attribution: {mode: 'external'}},
+  {
+    apiKey: process.env.TILEFLOW_API_KEY,
+    idempotencyKey: createStaticMapIdempotencyKey(),
+  },
+);
+
+for (const entry of result.attribution.entries) {
+  renderAttributionText(entry.text, entry.links);
+}
+```
+
+External mode leaves the image unchanged and returns `position: null`. The caller must retain and
+display every returned entry beside the image. Entries contain bounded plain text, safe HTTP(S)
+links, and `platform-notice` or `team-declared` authority; they never contain source HTML or private
+resource IDs. Embedded results return the resolved corner. Changing mode or requested position
+changes scene and artifact identity.
+
+## 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. Unsupported attribution grammar or glyphs, excessive attribution,
+and a block that cannot fit use the same non-retryable `422` boundary.
+
 The package has four deliberately separate surfaces, all available from the root for compatibility:
 
 - scene validation and normalization: `staticSceneSchema`, `validateStaticScene`, and
   `normalizeStaticScene`;
 - overlay authoring and MapLibre compilation: `line`, `circle`, `marker`, `polygon`, and
   `compileStaticOverlays`;
-- renderer identity: `createRenderManifest`, `validateStaticRenderManifest`,
-  `hashRenderManifest`, and `hashStaticSceneRequest`;
+- renderer identity: `createRenderManifestV1`, `createRenderManifestV2`,
+  `validateStaticRenderManifest`, `hashRenderManifest`, and `hashStaticSceneRequest`;
 - bounded Hosted transport: `prepareStaticMapRequest`, `createStaticMap`, `precacheStaticMap`, and
   `requestStaticMapUntilReady`.
 
 Applications that need only one surface can use `@tileflow/static/scene`, `/overlays`, `/manifest`,
 or `/client`. The root remains a compatibility entry point.
 
-`StaticRenderManifest` is the immutable input contract between a resolved Hosted style and a Static
-Maps renderer. Its top-level `mapId` identifies that resolved destination while `scene.map` retains
-the portable map name supplied by the application. It is unrelated to the runtime delivery manifest
-generated by application build or deploy workflows.
+`StaticRenderManifest` is the versioned immutable input contract between a resolved Hosted style and
+a Static Maps renderer. Manifest v1 remains the exact historical no-attribution contract; new Hosted
+work uses strict v2 with resolved safe entries and immutable provenance. `createRenderManifest`
+remains the v1 compatibility alias. Its top-level `mapId` identifies the resolved destination while
+`scene.map` retains the portable map name supplied by the application. It is unrelated to the
+runtime delivery manifest generated by application build or deploy workflows.
 
 Create one idempotency key per intentional create/precache action and retain it across network
 retries. Reusing the key with the same normalized scene returns the stored result; reusing it with a
 different scene returns 409. A successful paid operation reports `unitCost: 15`, shared
 `remainingUnits`, its durable `operationId`, cache reuse, hash, and immutable image URL. An
-unbounded Starter service reports `remainingUnits: null`. A live
+unbounded Starter service reports `remainingUnits: null`. Creation helpers request strict result v2,
+including `resultVersion: 2` and required attribution. They reject a legacy success rather than
+claiming notices that were never produced. A live
 equal-hash render may return `202`; the helper polls with the same body/key within its bounded wait.
 `maxWaitMs` is the total client completion budget, including network, response parsing, and polling
 delays; `signal` cancels the same complete operation. The helper aborts in-flight work when either
@@ -69,7 +159,7 @@ the same normalized scene for its `sceneKey` and HTTP body, so equivalent omitte
 deduplicate consistently without duplicating the polling implementation.
 
 Free cannot initiate Static Maps work. Starter consumes 15 shared API units for each successful
-logical operation, including a distinct-key cache reuse. Downloading the immutable PNG consumes
-zero units.
+logical operation, including a distinct-key cache reuse. Downloading an immutable PNG, JPEG, or WebP
+consumes zero units.
 
 Docs: https://tileflow.dev/docs

package/dist/chunk-EMCKSFZV.js

@@ -0,0 +1,477 @@
+import {
+  MAX_OVERLAY_LATITUDE,
+  jsonByteLength,
+  normalizeStaticCoordinate,
+  normalizeStaticOverlay,
+  roundNumber,
+  staticPaddingSchema,
+  staticSceneLimits,
+  staticSceneSchema,
+  stripUndefined
+} from "./chunk-NM2JSFUF.js";
+
+// src/auto-fit.ts
+import { z } from "zod";
+var autoFitOverlayReferenceSchema = z.object({
+  id: z.string().min(1).max(64),
+  index: z.number().int().min(0).max(23),
+  type: z.enum(["circle", "line", "marker", "polygon"])
+}).strict();
+var autoFitViewportSchema = z.object({
+  height: z.number().int().min(64).max(1280),
+  width: z.number().int().min(64).max(1280)
+}).strict();
+var autoFitDetailsSchema = z.object({
+  overlay: autoFitOverlayReferenceSchema.optional(),
+  padding: staticPaddingSchema.optional(),
+  projection: z.enum(["globe", "mercator"]).optional(),
+  requiredInsets: staticPaddingSchema.optional(),
+  ringIndex: z.number().int().min(0).max(15).optional(),
+  segmentIndex: z.number().int().min(0).max(1999).optional(),
+  viewport: autoFitViewportSchema.optional()
+}).strict();
+var staticOverlayInvalidDetailsSchema = z.object({
+  latitude: z.number().finite(),
+  limit: z.literal(MAX_OVERLAY_LATITUDE),
+  overlay: autoFitOverlayReferenceSchema
+}).strict();
+var autoFitErrorBase = {
+  error: z.string().min(1).max(512),
+  retryable: z.literal(false)
+};
+var staticMapRequestErrorResponseSchema = z.discriminatedUnion("code", [
+  z.object({
+    ...autoFitErrorBase,
+    code: z.literal("AUTO_FIT_EMPTY"),
+    reason: z.literal("NO_FITTABLE_OVERLAYS")
+  }).strict(),
+  z.object({
+    ...autoFitErrorBase,
+    code: z.literal("AUTO_FIT_AMBIGUOUS"),
+    details: autoFitDetailsSchema,
+    reason: z.literal("ANTIMERIDIAN_WRAP_REQUIRED")
+  }).strict(),
+  z.object({
+    ...autoFitErrorBase,
+    code: z.literal("AUTO_FIT_IMPOSSIBLE"),
+    details: autoFitDetailsSchema.optional(),
+    reason: z.enum([
+      "GLOBE_NOT_SIMULTANEOUSLY_VISIBLE",
+      "INSUFFICIENT_VIEWPORT",
+      "CAMERA_UNRESOLVABLE",
+      "PROJECTED_FOOTPRINT_OUTSIDE_VIEWPORT"
+    ])
+  }).strict(),
+  z.object({
+    ...autoFitErrorBase,
+    code: z.literal("STATIC_OVERLAY_INVALID"),
+    details: staticOverlayInvalidDetailsSchema,
+    reason: z.literal("OVERLAY_LATITUDE_OUT_OF_RANGE")
+  }).strict(),
+  z.object({
+    ...autoFitErrorBase,
+    code: z.literal("STATIC_MAP_ATTRIBUTION_UNSUPPORTED"),
+    reason: z.enum(["UNSUPPORTED_DECLARATION", "UNSUPPORTED_GLYPH"])
+  }).strict(),
+  z.object({
+    ...autoFitErrorBase,
+    code: z.literal("STATIC_MAP_ATTRIBUTION_TOO_LARGE"),
+    reason: z.literal("CONTENT_LIMIT_EXCEEDED")
+  }).strict(),
+  z.object({
+    ...autoFitErrorBase,
+    code: z.literal("STATIC_MAP_ATTRIBUTION_DOES_NOT_FIT"),
+    reason: z.literal("BLOCK_DOES_NOT_FIT")
+  }).strict()
+]);
+var StaticMapRequestError = class extends Error {
+  code;
+  details;
+  reason;
+  retryable = false;
+  status;
+  constructor(response, status = 422) {
+    super(response.error);
+    this.name = "StaticMapRequestError";
+    this.code = response.code;
+    this.details = "details" in response ? response.details : void 0;
+    this.reason = response.reason;
+    this.status = status;
+  }
+};
+var staticAutoFitPlanSchema = z.object({
+  bounds: z.tuple([
+    z.number().finite(),
+    z.number().finite().min(-90).max(90),
+    z.number().finite(),
+    z.number().finite().min(-90).max(90)
+  ]),
+  longitudeOffsets: z.array(z.number().int().min(-360).max(360)).max(24),
+  nominalInsets: staticPaddingSchema,
+  requiredInsets: staticPaddingSchema
+}).strict();
+function analyzeStaticAutoFit(scene) {
+  if (scene.camera.type !== "auto") {
+    throw new Error("Static auto-fit analysis requires an auto camera");
+  }
+  if (scene.overlays.length === 0) {
+    return failure({
+      code: "AUTO_FIT_EMPTY",
+      error: "Auto-fit requires at least one overlay",
+      reason: "NO_FITTABLE_OVERLAYS",
+      retryable: false
+    });
+  }
+  const components = [];
+  let south = Number.POSITIVE_INFINITY;
+  let north = Number.NEGATIVE_INFINITY;
+  let nominalExpansion = 0;
+  for (const [overlayIndex, overlay] of scene.overlays.entries()) {
+    const coordinates = overlayCoordinates(overlay);
+    const ambiguity = findAmbiguousSegment(overlay);
+    if (ambiguity) {
+      return failure({
+        code: "AUTO_FIT_AMBIGUOUS",
+        details: {
+          overlay: {
+            id: overlay.id ?? `overlay-${overlayIndex + 1}`,
+            index: overlayIndex,
+            type: overlay.type
+          },
+          ...ambiguity.ringIndex === void 0 ? {} : { ringIndex: ambiguity.ringIndex },
+          segmentIndex: ambiguity.segmentIndex
+        },
+        error: `Overlay overlays.${overlayIndex} requires an explicit antimeridian wrap decision`,
+        reason: "ANTIMERIDIAN_WRAP_REQUIRED",
+        retryable: false
+      });
+    }
+    const longitudes = coordinates.map(([longitude]) => longitude);
+    components.push({
+      east: Math.max(...longitudes),
+      overlayIndex,
+      west: Math.min(...longitudes)
+    });
+    for (const [, latitude] of coordinates) {
+      south = Math.min(south, latitude);
+      north = Math.max(north, latitude);
+    }
+    nominalExpansion = Math.max(nominalExpansion, nominalOverlayExpansion(overlay));
+  }
+  const longitudePlan = fitLongitudeComponents(components);
+  const nominalInset = Math.ceil(nominalExpansion);
+  const nominalInsets = allSides(nominalInset);
+  const padding = normalizedPadding(scene.camera.padding, scene.size);
+  if ([padding.bottom, padding.left, padding.right, padding.top].some(
+    (value) => !Number.isSafeInteger(value + nominalInset)
+  )) {
+    return failure({
+      code: "AUTO_FIT_IMPOSSIBLE",
+      details: {
+        padding,
+        viewport: { height: scene.size.height, width: scene.size.width }
+      },
+      error: "Auto-fit nominal footprint leaves no usable viewport",
+      reason: "INSUFFICIENT_VIEWPORT",
+      retryable: false
+    });
+  }
+  const requiredInsets = {
+    bottom: padding.bottom + nominalInset,
+    left: padding.left + nominalInset,
+    right: padding.right + nominalInset,
+    top: padding.top + nominalInset
+  };
+  if (requiredInsets.left + requiredInsets.right >= scene.size.width || requiredInsets.top + requiredInsets.bottom >= scene.size.height) {
+    return failure({
+      code: "AUTO_FIT_IMPOSSIBLE",
+      details: {
+        padding,
+        requiredInsets,
+        viewport: { height: scene.size.height, width: scene.size.width }
+      },
+      error: "Auto-fit nominal footprint leaves no usable viewport",
+      reason: "INSUFFICIENT_VIEWPORT",
+      retryable: false
+    });
+  }
+  return {
+    ok: true,
+    plan: {
+      bounds: [
+        roundNumber(longitudePlan.west),
+        roundNumber(south),
+        roundNumber(longitudePlan.east),
+        roundNumber(north)
+      ],
+      longitudeOffsets: longitudePlan.offsets,
+      nominalInsets,
+      requiredInsets
+    }
+  };
+}
+function failure(response) {
+  return { ...response, ok: false };
+}
+function overlayCoordinates(overlay) {
+  if (overlay.type === "circle" || overlay.type === "marker") {
+    return [overlay.coordinate];
+  }
+  if (overlay.type === "line") {
+    return overlay.coordinates;
+  }
+  return overlay.coordinates.flat();
+}
+function findAmbiguousSegment(overlay) {
+  if (overlay.type === "circle" || overlay.type === "marker") return null;
+  const paths = overlay.type === "line" ? [overlay.coordinates] : overlay.coordinates;
+  for (const [ringIndex, path] of paths.entries()) {
+    for (let segmentIndex = 0; segmentIndex < path.length - 1; segmentIndex += 1) {
+      const start = path[segmentIndex];
+      const end = path[segmentIndex + 1];
+      if (start && end && Math.abs(end[0] - start[0]) >= 180) {
+        return {
+          ...overlay.type === "polygon" ? { ringIndex } : {},
+          segmentIndex
+        };
+      }
+    }
+  }
+  return null;
+}
+function nominalOverlayExpansion(overlay) {
+  if (overlay.type === "circle" || overlay.type === "marker") {
+    return overlay.radius + overlay.strokeWidth;
+  }
+  if (overlay.type === "line") {
+    return overlay.width / 2 + 0.5;
+  }
+  return overlay.stroke && overlay.strokeWidth > 0 ? overlay.strokeWidth / 2 + 0.5 : 0;
+}
+function fitLongitudeComponents(components) {
+  const candidates = /* @__PURE__ */ new Set();
+  for (const component of components) {
+    candidates.add(toCircle(component.west));
+    candidates.add(toCircle(component.east));
+  }
+  let best;
+  for (const cut of [...candidates].sort((left, right) => left - right)) {
+    const assignedStarts = [];
+    let west = Number.POSITIVE_INFINITY;
+    let east = Number.NEGATIVE_INFINITY;
+    let valid = true;
+    for (const component of components) {
+      const width = component.east - component.west;
+      let start = toCircle(component.west);
+      if (start < cut) start += 360;
+      const end = start + width;
+      if (end > cut + 360 + 1e-9) {
+        valid = false;
+        break;
+      }
+      assignedStarts.push(start);
+      west = Math.min(west, start);
+      east = Math.max(east, end);
+    }
+    if (!valid) continue;
+    const span = east - west;
+    const canonicalWest2 = canonicalLongitude(west - 180);
+    const bestCanonicalWest = best ? canonicalLongitude(best.west - 180) : Number.POSITIVE_INFINITY;
+    if (!best || span < best.span - 1e-9 || Math.abs(span - best.span) <= 1e-9 && canonicalWest2 < bestCanonicalWest) {
+      best = { assignedStarts, east, span, west };
+    }
+  }
+  if (!best) {
+    const west = Math.min(...components.map((component) => component.west));
+    const east = Math.max(...components.map((component) => component.east));
+    return { east, offsets: components.map(() => 0), west };
+  }
+  const unshiftedWest = best.west - 180;
+  const canonicalWest = canonicalLongitude(unshiftedWest);
+  const globalOffset = canonicalWest - unshiftedWest;
+  const offsets = components.map((component, index) => {
+    const assignedLongitude = (best?.assignedStarts[index] ?? 0) - 180 + globalOffset;
+    return Math.round(assignedLongitude - component.west);
+  });
+  return {
+    east: canonicalWest + best.span,
+    offsets,
+    west: canonicalWest
+  };
+}
+function toCircle(longitude) {
+  const value = (longitude + 180) % 360;
+  return value < 0 ? value + 360 : value;
+}
+function canonicalLongitude(longitude) {
+  const value = ((longitude + 180) % 360 + 360) % 360;
+  return value - 180;
+}
+function allSides(value) {
+  return { bottom: value, left: value, right: value, top: value };
+}
+function normalizedPadding(padding, size) {
+  if (padding === void 0) {
+    return allSides(Math.min(32, Math.ceil(Math.min(size.width, size.height) * 0.05)));
+  }
+  if (typeof padding === "number") return allSides(padding);
+  return {
+    bottom: padding.bottom ?? 0,
+    left: padding.left ?? 0,
+    right: padding.right ?? 0,
+    top: padding.top ?? 0
+  };
+}
+function autoFitErrorResponse(failure2) {
+  const { ok: _ok, ...response } = failure2;
+  return response;
+}
+function findStaticOverlayLatitudeFailure(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return null;
+  const overlays = input.overlays;
+  if (!Array.isArray(overlays)) return null;
+  for (const [index, candidate] of overlays.entries()) {
+    if (index >= staticSceneLimits.maxOverlays) break;
+    if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) continue;
+    const overlay = candidate;
+    const type = overlay.type;
+    if (!["circle", "line", "marker", "polygon"].includes(String(type))) continue;
+    const coordinates = type === "circle" || type === "marker" ? [overlay.coordinate] : overlayCoordinateCandidates(type, overlay.coordinates);
+    for (const coordinate of coordinates) {
+      if (!Array.isArray(coordinate) || coordinate.length !== 2 || typeof coordinate[1] !== "number" || !Number.isFinite(coordinate[1]) || Math.abs(coordinate[1]) <= MAX_OVERLAY_LATITUDE) {
+        continue;
+      }
+      const id = typeof overlay.id === "string" && overlay.id.trim() ? overlay.id.trim() : `overlay-${index + 1}`;
+      const response = {
+        code: "STATIC_OVERLAY_INVALID",
+        details: {
+          latitude: coordinate[1],
+          limit: MAX_OVERLAY_LATITUDE,
+          overlay: {
+            id: id.slice(0, 64),
+            index,
+            type
+          }
+        },
+        error: `Overlay overlays.${index} latitude ${coordinate[1]} exceeds the supported \xB1${MAX_OVERLAY_LATITUDE}\xB0 range`,
+        reason: "OVERLAY_LATITUDE_OUT_OF_RANGE",
+        retryable: false
+      };
+      return { ...response, ok: false };
+    }
+  }
+  return null;
+}
+function overlayCoordinateCandidates(type, value) {
+  if (!Array.isArray(value)) return [];
+  if (type === "line") {
+    return value.slice(0, staticSceneLimits.maxPathCoordinates);
+  }
+  return value.slice(0, 16).flatMap(
+    (ring) => Array.isArray(ring) ? ring.slice(0, staticSceneLimits.maxPathCoordinates) : []
+  );
+}
+
+// src/scene.ts
+function validateStaticScene(input) {
+  const overlayLatitudeFailure = findStaticOverlayLatitudeFailure(input);
+  if (overlayLatitudeFailure) return overlayLatitudeFailure;
+  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
+    };
+  }
+  const scene = normalizeParsedStaticScene(parsed.data);
+  if (scene.camera.type === "auto") {
+    const analysis = analyzeStaticAutoFit(scene);
+    if (!analysis.ok) return analysis;
+  }
+  return { ok: true, scene };
+}
+function normalizeStaticScene(scene) {
+  const overlayLatitudeFailure = findStaticOverlayLatitudeFailure(scene);
+  if (overlayLatitudeFailure) {
+    const { ok: _ok, ...response } = overlayLatitudeFailure;
+    throw new StaticMapRequestError(response);
+  }
+  const normalized = normalizeParsedStaticScene(staticSceneSchema.parse(scene));
+  if (normalized.camera.type === "auto") {
+    const analysis = analyzeStaticAutoFit(normalized);
+    if (!analysis.ok) {
+      throw new StaticMapRequestError(autoFitErrorResponse(analysis));
+    }
+  }
+  return normalized;
+}
+function normalizeParsedStaticScene(parsed) {
+  return stripUndefined({
+    ...parsed.attribution && Object.keys(parsed.attribution).length > 0 ? {
+      attribution: parsed.attribution.mode === "external" ? { mode: "external" } : stripUndefined({
+        mode: parsed.attribution.mode,
+        position: parsed.attribution.position
+      })
+    } : {},
+    camera: parsed.camera.type === "center" ? {
+      bearing: roundNumber(parsed.camera.bearing ?? 0),
+      center: normalizeStaticCoordinate(parsed.camera.center),
+      type: "center",
+      zoom: roundNumber(parsed.camera.zoom)
+    } : parsed.camera.type === "bounds" ? {
+      bearing: roundNumber(parsed.camera.bearing ?? 0),
+      bounds: parsed.camera.bounds.map(roundNumber),
+      padding: parsed.camera.padding ?? 32,
+      type: "bounds"
+    } : {
+      bearing: roundNumber(parsed.camera.bearing ?? 0),
+      maxZoom: roundNumber(parsed.camera.maxZoom ?? 16),
+      padding: normalizeAutoPadding(parsed.camera.padding, parsed.size),
+      type: "auto"
+    },
+    ...parsed.format && parsed.format !== "png" ? { format: parsed.format } : {},
+    map: parsed.map,
+    overlays: parsed.overlays.map(
+      (overlay, index) => normalizeStaticOverlay({
+        ...overlay,
+        id: overlay.id ?? `overlay-${index + 1}`
+      })
+    ),
+    size: {
+      dpr: parsed.size.dpr ?? 1,
+      height: parsed.size.height,
+      width: parsed.size.width
+    },
+    theme: parsed.theme
+  });
+}
+function normalizeAutoPadding(padding, size) {
+  if (padding === void 0) {
+    const value = Math.min(32, Math.ceil(Math.min(size.width, size.height) * 0.05));
+    return { bottom: value, left: value, right: value, top: value };
+  }
+  if (typeof padding === "number") {
+    return { bottom: padding, left: padding, right: padding, top: padding };
+  }
+  return {
+    bottom: padding.bottom ?? 0,
+    left: padding.left ?? 0,
+    right: padding.right ?? 0,
+    top: padding.top ?? 0
+  };
+}
+
+export {
+  staticMapRequestErrorResponseSchema,
+  StaticMapRequestError,
+  staticAutoFitPlanSchema,
+  analyzeStaticAutoFit,
+  validateStaticScene,
+  normalizeStaticScene
+};

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

@@ -1,6 +1,7 @@
 import {
-  normalizeStaticOverlay
-} from "./chunk-YUG3PBK2.js";
+  normalizeStaticOverlay,
+  roundNumber
+} from "./chunk-NM2JSFUF.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 },