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

package/dist/chunk-HVVIAOBE.js

@@ -0,0 +1,175 @@
+import {
+  normalizeStaticOverlay,
+  roundNumber
+} from "./chunk-6DWVCK64.js";
+
+// src/overlays.ts
+function line(input) {
+  return normalizeStaticOverlay({ ...input, type: "line" });
+}
+function circle(input) {
+  return normalizeStaticOverlay({ ...input, type: "circle" });
+}
+function marker(input) {
+  return normalizeStaticOverlay({ ...input, type: "marker" });
+}
+function polygon(input) {
+  return normalizeStaticOverlay({ ...input, type: "polygon" });
+}
+function symbol(input) {
+  return normalizeStaticOverlay({ ...input, type: "symbol" });
+}
+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 = [];
+  const placements = {};
+  const symbols = [];
+  const pushLayer = (layer, overlay) => {
+    const layerId = String(layer.id);
+    layers.push(layer);
+    placements[layerId] = overlay.placement ?? "above-labels";
+  };
+  for (const [index, overlay] of overlays.entries()) {
+    const longitudeOffset = options.longitudeOffsets?.[index] ?? 0;
+    const id = safeLayerId(`tileflow-static-overlay-${index + 1}-${overlay.id ?? overlay.type}`);
+    const sourceId = `${id}-source`;
+    if (overlay.type === "line") {
+      sources[sourceId] = {
+        data: feature("LineString", shiftLongitudes(overlay.coordinates, longitudeOffset)),
+        type: "geojson"
+      };
+      pushLayer(
+        {
+          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"
+        },
+        overlay
+      );
+      continue;
+    }
+    if (overlay.type === "polygon") {
+      sources[sourceId] = {
+        data: feature("Polygon", shiftLongitudes(overlay.coordinates, longitudeOffset)),
+        type: "geojson"
+      };
+      pushLayer(
+        {
+          id,
+          paint: {
+            "fill-color": overlay.fill,
+            "fill-opacity": overlay.opacity
+          },
+          source: sourceId,
+          type: "fill"
+        },
+        overlay
+      );
+      if (overlay.stroke && overlay.strokeWidth > 0) {
+        pushLayer(
+          {
+            id: `${id}-stroke`,
+            layout: { "line-cap": "round", "line-join": "round" },
+            paint: {
+              "line-color": overlay.stroke,
+              "line-width": overlay.strokeWidth
+            },
+            source: sourceId,
+            type: "line"
+          },
+          overlay
+        );
+      }
+      continue;
+    }
+    sources[sourceId] = {
+      data: feature("Point", shiftLongitudes(overlay.coordinate, longitudeOffset)),
+      type: "geojson"
+    };
+    if (overlay.type === "symbol") {
+      const composed = overlay.label !== void 0;
+      const imageId = composed ? safeLayerId(`__tileflow-static-symbol-${index + 1}-${overlay.id}`) : overlay.icon;
+      const alwaysVisible = overlay.collision === "always-visible";
+      const iconSize = composed ? 1 : overlay.scale;
+      const iconOffset = composed ? overlay.offset : overlay.offset.map((value) => roundNumber(value / overlay.scale));
+      pushLayer(
+        {
+          id,
+          layout: {
+            "icon-allow-overlap": alwaysVisible,
+            "icon-anchor": overlay.anchor,
+            "icon-ignore-placement": alwaysVisible,
+            "icon-image": imageId,
+            "icon-offset": iconOffset,
+            "icon-pitch-alignment": "viewport",
+            "icon-rotation-alignment": "viewport",
+            "icon-size": iconSize,
+            "symbol-placement": "point",
+            "symbol-z-order": "source"
+          },
+          paint: { "icon-opacity": overlay.opacity },
+          source: sourceId,
+          type: "symbol"
+        },
+        overlay
+      );
+      symbols.push({ imageId, overlayIndex: index });
+      continue;
+    }
+    pushLayer(
+      {
+        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"
+      },
+      overlay
+    );
+  }
+  return { layers, placements, sources, symbols };
+}
+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 },
+    properties: {},
+    type: "Feature"
+  };
+}
+function safeLayerId(value) {
+  return value.replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 80);
+}
+
+export {
+  line,
+  circle,
+  marker,
+  polygon,
+  symbol,
+  compileStaticOverlays
+};

package/dist/{chunk-MSQ4OLKA.js → chunk-N63IFMFM.js}

@@ -1,21 +1,23 @@
 import {
+  StaticMapError,
   StaticMapRequestError,
+  staticMapErrorResponseSchema,
   staticMapRequestErrorResponseSchema,
   validateStaticScene
-} from "./chunk-EMCKSFZV.js";
+} from "./chunk-TBI5AED6.js";
 import {
   isSafeHttpUrl,
   jsonByteLength,
   stableStringify
-} from "./chunk-NM2JSFUF.js";
+} from "./chunk-6DWVCK64.js";
 
 // src/client.ts
 import { z } from "zod";
 var maxStaticMapResponseBytes = 64 * 1024;
 var staticMapIdempotencyKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/;
-var STATIC_MAP_RESULT_V2_MEDIA_TYPE = "application/vnd.tileflow.static-map-result+json;version=2";
+var STATIC_MAP_RESULT_MEDIA_TYPE = "application/vnd.tileflow.static-map-result+json;version=1";
 var preparedStaticMapRequestBodies = /* @__PURE__ */ new WeakMap();
-var staticMapReadyResultSchema = z.object({
+var staticMapReadyResultBaseSchema = z.object({
   cached: z.boolean(),
   hash: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
   imageUrl: z.string().trim().url().max(2048).refine(isSafeHttpUrl, { message: "Expected an http(s) URL without credentials" }),
@@ -53,9 +55,9 @@ var staticMapAttributionResultSchema = z.object({
     context.addIssue({ code: "custom", message: "Attribution result exceeds 32 KiB" });
   }
 });
-var staticMapHostedResultSchema = staticMapReadyResultSchema.extend({
+var staticMapHostedResultSchema = staticMapReadyResultBaseSchema.extend({
   attribution: staticMapAttributionResultSchema,
-  resultVersion: z.literal(2)
+  resultVersion: z.literal(1)
 }).strict();
 var staticMapProcessingResultSchema = z.object({
   operationId: z.string().min(20).max(68),
@@ -127,7 +129,7 @@ async function requestStaticMapUntilReady(request, options) {
   const fetcher = options.fetch ?? fetch;
   const createUrl = normalizeStaticMapEndpointUrl(options.createUrl);
   const headers = {
-    Accept: STATIC_MAP_RESULT_V2_MEDIA_TYPE,
+    Accept: STATIC_MAP_RESULT_MEDIA_TYPE,
     "Content-Type": "application/json",
     "Idempotency-Key": idempotency.key
   };
@@ -145,10 +147,17 @@ async function requestStaticMapUntilReady(request, options) {
       });
       throwIfAborted(signal);
       if (!response.ok) {
-        const requestError = response.status === 422 ? await readStaticMapRequestErrorResponse(response, 8 * 1024) : await discardBoundedResponse(response, 8 * 1024);
+        const errorBody = await readStaticMapErrorBody(response, 8 * 1024);
         throwIfAborted(signal);
-        if (requestError) {
-          throw new StaticMapRequestError(requestError, response.status);
+        if (response.status === 422) {
+          const requestError = staticMapRequestErrorResponseSchema.safeParse(errorBody);
+          if (requestError.success) {
+            throw new StaticMapRequestError(requestError.data, response.status);
+          }
+        }
+        const structured = staticMapErrorResponseSchema.safeParse(errorBody);
+        if (structured.success) {
+          throw new StaticMapError(structured.data, response.status);
         }
         throw new Error(`Tileflow static map failed (${response.status}).`);
       }
@@ -199,22 +208,14 @@ async function readJsonResponse(response) {
     throw new Error("Tileflow static map returned an invalid response: expected JSON");
   }
 }
-async function readStaticMapRequestErrorResponse(response, maximumBytes) {
+async function readStaticMapErrorBody(response, maximumBytes) {
   try {
     const source = await readBoundedResponseText(response, maximumBytes, `${maximumBytes} bytes`);
-    const parsed = staticMapRequestErrorResponseSchema.safeParse(JSON.parse(source));
-    return parsed.success ? parsed.data : null;
+    return JSON.parse(source);
   } 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;
@@ -359,8 +360,7 @@ function hasControlCharacter(value) {
 }
 
 export {
-  STATIC_MAP_RESULT_V2_MEDIA_TYPE,
-  staticMapReadyResultSchema,
+  STATIC_MAP_RESULT_MEDIA_TYPE,
   staticMapAttributionEntrySchema,
   staticMapAttributionResultSchema,
   staticMapHostedResultSchema,

package/dist/{chunk-EMCKSFZV.js → chunk-TBI5AED6.js}

@@ -1,5 +1,6 @@
 import {
   MAX_OVERLAY_LATITUDE,
+  isSupportedStaticSymbolCodePoint,
   jsonByteLength,
   normalizeStaticCoordinate,
   normalizeStaticOverlay,
@@ -8,90 +9,166 @@ import {
   staticSceneLimits,
   staticSceneSchema,
   stripUndefined
-} from "./chunk-NM2JSFUF.js";
+} from "./chunk-6DWVCK64.js";
 
 // src/auto-fit.ts
+import { z as z2 } from "zod";
+
+// src/errors.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"])
+var safeErrorTextSchema = z.string().min(1).max(512).refine(hasNoControlCharacters, { message: "Expected no control characters" });
+var safeErrorIdentifierSchema = z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/u);
+var staticMapErrorResponseSchema = z.object({
+  code: safeErrorIdentifierSchema.optional(),
+  error: safeErrorTextSchema,
+  remainingUnits: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+  requestId: safeErrorIdentifierSchema.optional(),
+  retryable: z.boolean().optional()
+}).strip();
+var StaticMapError = class extends Error {
+  code;
+  remainingUnits;
+  requestId;
+  response;
+  retryable;
+  status;
+  constructor(response, status) {
+    const parsed = staticMapErrorResponseSchema.parse(response);
+    super(parsed.error);
+    this.name = "StaticMapError";
+    this.code = parsed.code ?? null;
+    this.remainingUnits = parsed.remainingUnits ?? null;
+    this.requestId = parsed.requestId ?? null;
+    this.response = Object.freeze(parsed);
+    this.retryable = parsed.retryable ?? null;
+    this.status = status;
+  }
+};
+function hasNoControlCharacters(value) {
+  return !Array.from(value).some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint <= 31 || codePoint === 127;
+  });
+}
+
+// src/auto-fit.ts
+var autoFitOverlayReferenceSchema = z2.object({
+  id: z2.string().min(1).max(64),
+  index: z2.number().int().min(0).max(23),
+  type: z2.enum(["circle", "line", "marker", "polygon", "symbol"])
 }).strict();
-var autoFitViewportSchema = z.object({
-  height: z.number().int().min(64).max(1280),
-  width: z.number().int().min(64).max(1280)
+var autoFitViewportSchema = z2.object({
+  height: z2.number().int().min(64).max(1280),
+  width: z2.number().int().min(64).max(1280)
 }).strict();
-var autoFitDetailsSchema = z.object({
+var autoFitDetailsSchema = z2.object({
   overlay: autoFitOverlayReferenceSchema.optional(),
   padding: staticPaddingSchema.optional(),
-  projection: z.enum(["globe", "mercator"]).optional(),
+  projection: z2.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(),
+  ringIndex: z2.number().int().min(0).max(15).optional(),
+  segmentIndex: z2.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),
+var staticOverlayInvalidDetailsSchema = z2.object({
+  latitude: z2.number().finite(),
+  limit: z2.literal(MAX_OVERLAY_LATITUDE),
   overlay: autoFitOverlayReferenceSchema
 }).strict();
+var staticLabelUnsupportedDetailsSchema = z2.object({
+  codePoint: z2.number().int().min(0).max(1114111),
+  overlay: autoFitOverlayReferenceSchema.extend({ type: z2.literal("symbol") }).strict()
+}).strict();
+var staticIconUnavailableDetailsSchema = z2.object({
+  icon: z2.string().max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/u),
+  overlay: autoFitOverlayReferenceSchema.extend({ type: z2.literal("symbol") }).strict()
+}).strict();
+var staticSymbolTooLargeDetailsSchema = z2.object({
+  height: z2.number().finite().positive().max(16384),
+  limit: z2.literal(2048),
+  overlay: autoFitOverlayReferenceSchema.extend({ type: z2.literal("symbol") }).strict(),
+  width: z2.number().finite().positive().max(16384)
+}).strict();
 var autoFitErrorBase = {
-  error: z.string().min(1).max(512),
-  retryable: z.literal(false)
+  error: z2.string().min(1).max(512),
+  retryable: z2.literal(false)
 };
-var staticMapRequestErrorResponseSchema = z.discriminatedUnion("code", [
-  z.object({
+var staticMapRequestErrorResponseSchema = z2.discriminatedUnion("code", [
+  z2.object({
     ...autoFitErrorBase,
-    code: z.literal("AUTO_FIT_EMPTY"),
-    reason: z.literal("NO_FITTABLE_OVERLAYS")
+    code: z2.literal("AUTO_FIT_EMPTY"),
+    reason: z2.literal("NO_FITTABLE_OVERLAYS")
   }).strict(),
-  z.object({
+  z2.object({
     ...autoFitErrorBase,
-    code: z.literal("AUTO_FIT_AMBIGUOUS"),
+    code: z2.literal("AUTO_FIT_AMBIGUOUS"),
     details: autoFitDetailsSchema,
-    reason: z.literal("ANTIMERIDIAN_WRAP_REQUIRED")
+    reason: z2.literal("ANTIMERIDIAN_WRAP_REQUIRED")
   }).strict(),
-  z.object({
+  z2.object({
     ...autoFitErrorBase,
-    code: z.literal("AUTO_FIT_IMPOSSIBLE"),
+    code: z2.literal("AUTO_FIT_IMPOSSIBLE"),
     details: autoFitDetailsSchema.optional(),
-    reason: z.enum([
+    reason: z2.enum([
       "GLOBE_NOT_SIMULTANEOUSLY_VISIBLE",
       "INSUFFICIENT_VIEWPORT",
       "CAMERA_UNRESOLVABLE",
       "PROJECTED_FOOTPRINT_OUTSIDE_VIEWPORT"
     ])
   }).strict(),
-  z.object({
+  z2.object({
     ...autoFitErrorBase,
-    code: z.literal("STATIC_OVERLAY_INVALID"),
+    code: z2.literal("STATIC_OVERLAY_INVALID"),
     details: staticOverlayInvalidDetailsSchema,
-    reason: z.literal("OVERLAY_LATITUDE_OUT_OF_RANGE")
+    reason: z2.literal("OVERLAY_LATITUDE_OUT_OF_RANGE")
+  }).strict(),
+  z2.object({
+    ...autoFitErrorBase,
+    code: z2.literal("STATIC_MAP_LABEL_UNSUPPORTED"),
+    details: staticLabelUnsupportedDetailsSchema,
+    reason: z2.literal("UNSUPPORTED_GLYPH")
   }).strict(),
-  z.object({
+  z2.object({
     ...autoFitErrorBase,
-    code: z.literal("STATIC_MAP_ATTRIBUTION_UNSUPPORTED"),
-    reason: z.enum(["UNSUPPORTED_DECLARATION", "UNSUPPORTED_GLYPH"])
+    code: z2.literal("STATIC_MAP_ICON_UNAVAILABLE"),
+    details: staticIconUnavailableDetailsSchema,
+    reason: z2.enum(["ICON_NOT_FOUND", "MANAGED_SPRITE_REQUIRED"])
   }).strict(),
-  z.object({
+  z2.object({
     ...autoFitErrorBase,
-    code: z.literal("STATIC_MAP_ATTRIBUTION_TOO_LARGE"),
-    reason: z.literal("CONTENT_LIMIT_EXCEEDED")
+    code: z2.literal("STATIC_MAP_PLACEMENT_UNAVAILABLE"),
+    reason: z2.literal("MAP_REDEPLOY_REQUIRED")
   }).strict(),
-  z.object({
+  z2.object({
     ...autoFitErrorBase,
-    code: z.literal("STATIC_MAP_ATTRIBUTION_DOES_NOT_FIT"),
-    reason: z.literal("BLOCK_DOES_NOT_FIT")
+    code: z2.literal("STATIC_MAP_SYMBOL_TOO_LARGE"),
+    details: staticSymbolTooLargeDetailsSchema,
+    reason: z2.literal("COMPOSED_IMAGE_TOO_LARGE")
+  }).strict(),
+  z2.object({
+    ...autoFitErrorBase,
+    code: z2.literal("STATIC_MAP_ATTRIBUTION_UNSUPPORTED"),
+    reason: z2.enum(["UNSUPPORTED_DECLARATION", "UNSUPPORTED_GLYPH"])
+  }).strict(),
+  z2.object({
+    ...autoFitErrorBase,
+    code: z2.literal("STATIC_MAP_ATTRIBUTION_TOO_LARGE"),
+    reason: z2.literal("CONTENT_LIMIT_EXCEEDED")
+  }).strict(),
+  z2.object({
+    ...autoFitErrorBase,
+    code: z2.literal("STATIC_MAP_ATTRIBUTION_DOES_NOT_FIT"),
+    reason: z2.literal("BLOCK_DOES_NOT_FIT")
   }).strict()
 ]);
-var StaticMapRequestError = class extends Error {
+var StaticMapRequestError = class extends StaticMapError {
   code;
   details;
   reason;
   retryable = false;
   status;
   constructor(response, status = 422) {
-    super(response.error);
+    super(response, status);
     this.name = "StaticMapRequestError";
     this.code = response.code;
     this.details = "details" in response ? response.details : void 0;
@@ -99,14 +176,14 @@ var StaticMapRequestError = class extends Error {
     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)
+var staticAutoFitPlanSchema = z2.object({
+  bounds: z2.tuple([
+    z2.number().finite(),
+    z2.number().finite().min(-90).max(90),
+    z2.number().finite(),
+    z2.number().finite().min(-90).max(90)
   ]),
-  longitudeOffsets: z.array(z.number().int().min(-360).max(360)).max(24),
+  longitudeOffsets: z2.array(z2.number().int().min(-360).max(360)).max(24),
   nominalInsets: staticPaddingSchema,
   requiredInsets: staticPaddingSchema
 }).strict();
@@ -214,7 +291,7 @@ function failure(response) {
   return { ...response, ok: false };
 }
 function overlayCoordinates(overlay) {
-  if (overlay.type === "circle" || overlay.type === "marker") {
+  if (overlay.type === "circle" || overlay.type === "marker" || overlay.type === "symbol") {
     return [overlay.coordinate];
   }
   if (overlay.type === "line") {
@@ -223,7 +300,8 @@ function overlayCoordinates(overlay) {
   return overlay.coordinates.flat();
 }
 function findAmbiguousSegment(overlay) {
-  if (overlay.type === "circle" || overlay.type === "marker") return null;
+  if (overlay.type === "circle" || overlay.type === "marker" || overlay.type === "symbol")
+    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) {
@@ -243,6 +321,7 @@ function nominalOverlayExpansion(overlay) {
   if (overlay.type === "circle" || overlay.type === "marker") {
     return overlay.radius + overlay.strokeWidth;
   }
+  if (overlay.type === "symbol") return 0;
   if (overlay.type === "line") {
     return overlay.width / 2 + 0.5;
   }
@@ -335,8 +414,8 @@ function findStaticOverlayLatitudeFailure(input) {
     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);
+    if (!["circle", "line", "marker", "polygon", "symbol"].includes(String(type))) continue;
+    const coordinates = type === "circle" || type === "marker" || type === "symbol" ? [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;
@@ -362,6 +441,38 @@ function findStaticOverlayLatitudeFailure(input) {
   }
   return null;
 }
+function findStaticSymbolLabelGlyphFailure(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;
+    if (overlay.type !== "symbol") continue;
+    const label = overlay.label;
+    const text = typeof label === "string" ? label : label && typeof label === "object" && !Array.isArray(label) ? label.text : void 0;
+    if (typeof text !== "string") continue;
+    const unsupported = Array.from(text).find(
+      (character) => !isSupportedStaticSymbolCodePoint(character.codePointAt(0))
+    );
+    if (!unsupported) continue;
+    const codePoint = unsupported.codePointAt(0);
+    const id = typeof overlay.id === "string" && overlay.id.trim() ? overlay.id.trim() : `overlay-${index + 1}`;
+    return {
+      code: "STATIC_MAP_LABEL_UNSUPPORTED",
+      details: {
+        codePoint,
+        overlay: { id: id.slice(0, 64), index, type: "symbol" }
+      },
+      error: `Overlay overlays.${index} label contains unsupported glyph U+${codePoint.toString(16).toUpperCase().padStart(4, "0")}`,
+      ok: false,
+      reason: "UNSUPPORTED_GLYPH",
+      retryable: false
+    };
+  }
+  return null;
+}
 function overlayCoordinateCandidates(type, value) {
   if (!Array.isArray(value)) return [];
   if (type === "line") {
@@ -376,6 +487,8 @@ function overlayCoordinateCandidates(type, value) {
 function validateStaticScene(input) {
   const overlayLatitudeFailure = findStaticOverlayLatitudeFailure(input);
   if (overlayLatitudeFailure) return overlayLatitudeFailure;
+  const labelGlyphFailure = findStaticSymbolLabelGlyphFailure(input);
+  if (labelGlyphFailure) return labelGlyphFailure;
   const parsed = staticSceneSchema.safeParse(input);
   if (!parsed.success) {
     return {
@@ -402,6 +515,11 @@ function normalizeStaticScene(scene) {
     const { ok: _ok, ...response } = overlayLatitudeFailure;
     throw new StaticMapRequestError(response);
   }
+  const labelGlyphFailure = findStaticSymbolLabelGlyphFailure(scene);
+  if (labelGlyphFailure) {
+    const { ok: _ok, ...response } = labelGlyphFailure;
+    throw new StaticMapRequestError(response);
+  }
   const normalized = normalizeParsedStaticScene(staticSceneSchema.parse(scene));
   if (normalized.camera.type === "auto") {
     const analysis = analyzeStaticAutoFit(normalized);
@@ -468,6 +586,8 @@ function normalizeAutoPadding(padding, size) {
 }
 
 export {
+  staticMapErrorResponseSchema,
+  StaticMapError,
   staticMapRequestErrorResponseSchema,
   StaticMapRequestError,
   staticAutoFitPlanSchema,