@tileflow/static 0.1.0-alpha.3 → 0.1.0-alpha.30

package/dist/manifest.js

@@ -0,0 +1,339 @@
+import {
+  analyzeStaticAutoFit,
+  normalizeStaticScene,
+  staticAutoFitPlanSchema,
+  validateStaticScene
+} from "./chunk-ALFVZ3PC.js";
+import {
+  hashStableValue,
+  isSafeHttpUrl,
+  jsonByteLength,
+  stableStringify,
+  staticOverlayPlacements,
+  staticSceneSchema,
+  stripUndefined
+} from "./chunk-6DWVCK64.js";
+
+// src/manifest.ts
+import { z } from "zod";
+var staticRendererSchemaVersion = 1;
+var staticAttributionPlanSchemaVersion = 1;
+var staticRenderCompositionSchemaVersion = 1;
+var staticAttributionLimits = {
+  maxBytes: 32 * 1024,
+  maxEntries: 18,
+  maxLinksPerEntry: 8,
+  maxTextLength: 16384,
+  maxUrlLength: 2048
+};
+var sha256HexSchema = z.string().regex(/^[0-9a-f]{64}$/u);
+var sourceIdSchema = z.string().min(1).max(128);
+var boundedIdentitySchema = z.string().min(1).max(512).refine(hasNoControlCharacters, {
+  message: "Expected no control characters"
+});
+var staticResolvedAttributionPositionSchema = z.enum([
+  "top-left",
+  "top-right",
+  "bottom-left",
+  "bottom-right"
+]);
+var staticAttributionSegmentSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("text"),
+    text: z.string().min(1).max(staticAttributionLimits.maxTextLength).refine(hasNoControlCharacters, { message: "Attribution text contains control characters" })
+  }).strict(),
+  z.object({
+    kind: z.literal("link"),
+    label: z.string().min(1).max(staticAttributionLimits.maxTextLength).refine(hasNoControlCharacters, {
+      message: "Attribution link label contains control characters"
+    }),
+    url: z.string().trim().url().max(staticAttributionLimits.maxUrlLength).refine(isSafeHttpUrl, {
+      message: "Expected an http(s) URL without credentials or a fragment"
+    })
+  }).strict()
+]);
+var attributionSourceSchema = z.object({
+  sourceId: sourceIdSchema,
+  sourceSelectionIdentity: boundedIdentitySchema
+}).strict();
+var attributionSourcesSchema = z.array(attributionSourceSchema).min(1).max(18).refine(isUniqueSortedSources, {
+  message: "Attribution sources must be unique and sorted"
+});
+var staticAttributionProvenanceSchema = z.discriminatedUnion("authority", [
+  z.object({
+    authority: z.literal("platform-notice"),
+    noticeId: boundedIdentitySchema,
+    noticeSha256: sha256HexSchema,
+    resource: z.enum(["terrain", "world"]),
+    sources: attributionSourcesSchema
+  }).strict(),
+  z.object({
+    authority: z.literal("team-declared"),
+    sources: z.array(
+      attributionSourceSchema.extend({
+        mapRevision: boundedIdentitySchema,
+        resourceId: boundedIdentitySchema
+      }).strict()
+    ).min(1).max(18).refine(isUniqueSortedSources, {
+      message: "Attribution sources must be unique and sorted"
+    })
+  }).strict()
+]);
+var staticAttributionEntrySchema = z.object({
+  authority: z.enum(["platform-notice", "team-declared"]),
+  provenance: staticAttributionProvenanceSchema,
+  segments: z.array(staticAttributionSegmentSchema).min(1).max(17)
+}).strict().superRefine((entry, context) => {
+  if (entry.authority !== entry.provenance.authority) {
+    context.addIssue({
+      code: "custom",
+      message: "Attribution entry authority must match its provenance",
+      path: ["authority"]
+    });
+  }
+  const links = entry.segments.filter((segment) => segment.kind === "link").length;
+  if (links > staticAttributionLimits.maxLinksPerEntry) {
+    context.addIssue({
+      code: "custom",
+      message: `Attribution entries can contain at most ${staticAttributionLimits.maxLinksPerEntry} links`,
+      path: ["segments"]
+    });
+  }
+});
+var staticAttributionPlanSchema = z.object({
+  entries: z.array(staticAttributionEntrySchema).max(staticAttributionLimits.maxEntries),
+  mode: z.enum(["embedded", "external"]),
+  position: z.union([z.literal("auto"), staticResolvedAttributionPositionSchema, z.null()]),
+  schemaVersion: z.literal(staticAttributionPlanSchemaVersion)
+}).strict().superRefine((plan, context) => {
+  if (plan.mode === "external" && plan.position !== null || plan.mode === "embedded" && plan.position === null) {
+    context.addIssue({
+      code: "custom",
+      message: "Attribution position must match its mode",
+      path: ["position"]
+    });
+  }
+  if (jsonByteLength(plan) > staticAttributionLimits.maxBytes) {
+    context.addIssue({
+      code: "custom",
+      message: `Attribution plan exceeds ${staticAttributionLimits.maxBytes} bytes`
+    });
+  }
+});
+var placementAnchorsSchema = z.object({
+  "above-water": z.string().min(1).max(256).nullable(),
+  "below-roads": z.string().min(1).max(256).nullable(),
+  "above-roads": z.string().min(1).max(256).nullable(),
+  "above-buildings": z.string().min(1).max(256).nullable(),
+  "below-labels": z.string().min(1).max(256).nullable(),
+  "above-labels": z.null()
+}).strict().refine(anchorsHaveTerminalNulls, {
+  message: "Placement anchors may become null only at the end of semantic order"
+});
+var iconCoordinate = z.number().int().nonnegative().max(2048);
+var iconStretchRegions = z.array(z.tuple([iconCoordinate, iconCoordinate])).min(1).max(2048);
+var iconLayoutSchema = z.object({
+  stretchX: iconStretchRegions.optional(),
+  stretchY: iconStretchRegions.optional(),
+  content: z.tuple([iconCoordinate, iconCoordinate, iconCoordinate, iconCoordinate]).optional()
+}).strict();
+var resolvedIconSchema = z.object({
+  layout: iconLayoutSchema.optional(),
+  // Verified asset defaults supplied by the manifest producer, never scene input.
+  appearance: z.object({
+    representation: z.literal("sdf"),
+    defaults: z.object({
+      color: z.string().min(1).max(128).refine(hasNoControlCharacters),
+      haloColor: z.string().min(1).max(128).refine(hasNoControlCharacters),
+      haloWidth: z.number().finite().min(0).max(2),
+      haloBlur: z.number().finite().min(0).max(1)
+    }).strict()
+  }).strict().optional(),
+  height: z.number().int().positive().max(2048),
+  icon: z.string().max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/u),
+  overlayIndex: z.number().int().min(0).max(23),
+  width: z.number().int().positive().max(2048)
+}).strict().superRefine((icon, context) => {
+  const layout = icon.layout;
+  if (!layout) return;
+  let valid = Object.values(layout).some((value) => value !== void 0);
+  const content = layout.content;
+  if (content)
+    valid &&= content[0] < content[2] && content[1] < content[3] && content[2] <= icon.width && content[3] <= icon.height;
+  for (const [axis, bound, low, high] of [
+    ["stretchX", icon.width, content?.[0], content?.[2]],
+    ["stretchY", icon.height, content?.[1], content?.[3]]
+  ]) {
+    let end = 0;
+    for (const [from, to] of layout[axis] ?? []) {
+      valid &&= from >= end && from < to && to <= bound;
+      end = to;
+    }
+    if (layout[axis] && low !== void 0 && high !== void 0)
+      valid &&= layout[axis].some(([from, to]) => from < high && to > low);
+  }
+  if (!valid)
+    context.addIssue({
+      code: "custom",
+      path: ["layout"],
+      message: "Invalid icon layout for the resolved sprite dimensions"
+    });
+});
+var staticRenderCompositionSchema = z.object({
+  anchors: placementAnchorsSchema,
+  icons: z.array(resolvedIconSchema).max(24),
+  schemaVersion: z.literal(staticRenderCompositionSchemaVersion)
+}).strict().refine(
+  (composition) => composition.icons.every(
+    (icon, index) => index === 0 || composition.icons[index - 1].overlayIndex < icon.overlayIndex
+  ),
+  { message: "Resolved symbol icons must be unique and sorted by overlay index" }
+);
+var staticRenderManifestBaseShape = {
+  attribution: staticAttributionPlanSchema,
+  autoFit: staticAutoFitPlanSchema.optional(),
+  composition: staticRenderCompositionSchema,
+  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(isSafeHttpUrl, {
+    message: "Expected an http(s) style URL without credentials or a fragment"
+  })
+};
+var staticRenderManifestSchema = z.object(staticRenderManifestBaseShape).strict();
+function validateStaticRenderManifest(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return { error: "manifest: Expected an object", ok: false };
+  }
+  if (input.schemaVersion !== staticRendererSchemaVersion) {
+    return { error: "manifest.schemaVersion: Unsupported renderer schema version", ok: false };
+  }
+  const rawScene = input.scene;
+  const sceneValidation = validateStaticScene(rawScene);
+  if (!sceneValidation.ok) return sceneValidation;
+  const parsed = staticRenderManifestSchema.safeParse({
+    ...input,
+    scene: sceneValidation.scene
+  });
+  if (!parsed.success) return zodFailure(parsed.error);
+  const autoFit = expectedAutoFit(sceneValidation.scene);
+  if (autoFit === void 0 !== (parsed.data.autoFit === void 0) || autoFit !== void 0 && stableStringify(autoFit) !== stableStringify(parsed.data.autoFit)) {
+    return { error: "manifest.autoFit: Expected the exact plan derived from scene", ok: false };
+  }
+  if (!attributionMatchesScene(parsed.data.attribution, sceneValidation.scene)) {
+    return {
+      error: "manifest.attribution: Expected the exact request resolved from scene",
+      ok: false
+    };
+  }
+  if (!compositionMatchesScene(parsed.data.composition, sceneValidation.scene)) {
+    return {
+      error: "manifest.composition: Expected exact resolved symbol icon references",
+      ok: false
+    };
+  }
+  return {
+    manifest: {
+      ...parsed.data,
+      ...autoFit === void 0 ? {} : { autoFit },
+      scene: sceneValidation.scene
+    },
+    ok: true
+  };
+}
+function createRenderManifest(input) {
+  const scene = normalizeStaticScene(input.scene);
+  const autoFit = expectedAutoFit(scene);
+  return staticRenderManifestSchema.parse(
+    stripUndefined({
+      attribution: input.attribution,
+      autoFit,
+      composition: input.composition,
+      mapId: input.mapId,
+      rendererVersion: input.rendererVersion,
+      schemaVersion: staticRendererSchemaVersion,
+      scene,
+      styleId: input.styleId,
+      styleRevision: input.styleRevision,
+      styleUrl: input.styleUrl
+    })
+  );
+}
+async function hashRenderManifest(manifest) {
+  const validation = validateStaticRenderManifest(manifest);
+  if (!validation.ok) throw new Error(`Invalid Tileflow render manifest: ${validation.error}`);
+  return hashStableValue(validation.manifest);
+}
+async function hashStaticSceneRequest(scene) {
+  const validation = validateStaticScene(scene);
+  if (!validation.ok) throw new Error(`Invalid Tileflow static scene: ${validation.error}`);
+  return hashStableValue(validation.scene);
+}
+function attributionMatchesScene(plan, scene) {
+  const request = scene.attribution;
+  const expectedMode = request?.mode === "external" ? "external" : "embedded";
+  const expectedPosition = expectedMode === "external" ? null : request && "position" in request ? request.position ?? "auto" : "auto";
+  return plan.mode === expectedMode && plan.position === expectedPosition;
+}
+function compositionMatchesScene(composition, scene) {
+  const expected = scene.overlays.flatMap(
+    (overlay, overlayIndex) => overlay.type === "symbol" && overlay.icon ? [{ icon: overlay.icon, overlayIndex }] : []
+  );
+  return expected.length === composition.icons.length && expected.every(
+    (icon, index) => composition.icons[index]?.icon === icon.icon && composition.icons[index]?.overlayIndex === icon.overlayIndex
+  );
+}
+function expectedAutoFit(scene) {
+  if (scene.camera.type !== "auto") return void 0;
+  const analysis = analyzeStaticAutoFit(scene);
+  if (!analysis.ok) throw new Error(`Invalid Tileflow auto-fit scene: ${analysis.error}`);
+  return analysis.plan;
+}
+function anchorsHaveTerminalNulls(anchors) {
+  let sawNull = false;
+  for (const placement of staticOverlayPlacements) {
+    const anchor = anchors[placement];
+    if (anchor === null) sawNull = true;
+    else if (sawNull) return false;
+  }
+  return true;
+}
+function hasNoControlCharacters(value) {
+  return !Array.from(value).some((character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    return codePoint <= 31 || codePoint === 127;
+  });
+}
+function isUniqueSortedSources(values) {
+  return values.every(
+    (value, index) => index === 0 || compareCodeUnits(values[index - 1].sourceId, value.sourceId) < 0
+  );
+}
+function compareCodeUnits(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function zodFailure(error) {
+  return {
+    error: error.issues.map((issue) => `${issue.path.join(".") || "manifest"}: ${issue.message}`).join("; "),
+    ok: false
+  };
+}
+export {
+  createRenderManifest,
+  hashRenderManifest,
+  hashStaticSceneRequest,
+  staticAttributionEntrySchema,
+  staticAttributionLimits,
+  staticAttributionPlanSchema,
+  staticAttributionPlanSchemaVersion,
+  staticAttributionProvenanceSchema,
+  staticAttributionSegmentSchema,
+  staticRenderCompositionSchema,
+  staticRenderCompositionSchemaVersion,
+  staticRenderManifestSchema,
+  staticRendererSchemaVersion,
+  validateStaticRenderManifest
+};

package/dist/overlays.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { c as circleOverlaySchema, b as StaticOverlay, l as lineOverlaySchema, m as markerOverlaySchema, p as polygonOverlaySchema, s as symbolOverlaySchema } from './scene-contract-NFnIcQtt.js';
+export { d as StaticOverlayInput, e as staticOverlaySchema } from './scene-contract-NFnIcQtt.js';
+
+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 symbol(input: Omit<z.input<typeof symbolOverlaySchema>, 'type'>): StaticOverlay;
+declare function compileStaticOverlays(overlays: StaticOverlay[], options?: {
+    longitudeOffsets?: readonly number[];
+}): {
+    layers: Record<string, unknown>[];
+    placements: Record<string, "above-buildings" | "above-labels" | "above-roads" | "above-water" | "below-labels" | "below-roads">;
+    sources: Record<string, Record<string, unknown>>;
+    symbols: {
+        imageId: string;
+        overlayIndex: number;
+    }[];
+};
+
+export { StaticOverlay, circle, compileStaticOverlays, line, marker, polygon, symbol };

package/dist/overlays.js

@@ -0,0 +1,176 @@
+import {
+  normalizeStaticOverlay,
+  roundNumber,
+  staticOverlaySchema
+} 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 {
+  circle,
+  compileStaticOverlays,
+  line,
+  marker,
+  polygon,
+  staticOverlaySchema,
+  symbol
+};