@tileflow/core 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/runtime-C4MtSzkB.d.ts

@@ -0,0 +1,223 @@
+import { z } from 'zod';
+import { T as TileflowViewConfig, M as MapLibreStyle } from './types-DlUGI6LC.js';
+
+/** The first and only public multi-theme runtime manifest contract. */
+declare const tileflowRuntimeManifestVersion: 1;
+declare const tileflowRuntimeManifestLimits: Readonly<{
+    maximumBytes: number;
+}>;
+type TileflowRuntimeColorScheme = 'dark' | 'light';
+type TileflowRuntimeManifestTheme = {
+    colorScheme: TileflowRuntimeColorScheme;
+    /** Complete font closure for this compiled theme. */
+    fontFaces?: TileflowStyleFontFace[];
+    /** Content or deployment revision used for cache identity and receipts. */
+    revision?: string;
+    /** Hosted style identity, when different from the logical map identity. */
+    styleId?: string;
+    styleUrl: string;
+};
+type TileflowRuntimeSystemThemes = {
+    dark: string;
+    light: string;
+};
+type TileflowRuntimeManifestMapEntry = {
+    apiUrl?: string;
+    defaultTheme: string;
+    environment?: string;
+    mapId?: string;
+    systemThemes?: TileflowRuntimeSystemThemes;
+    themes: Record<string, TileflowRuntimeManifestTheme>;
+    usageMode?: 'session';
+    view?: TileflowViewConfig;
+    worldGeneration?: 'v1';
+};
+/**
+ * One logical map catalog for local and Hosted delivery.
+ *
+ * Delivery-specific fields are optional metadata on a map. The wire shape never forks into
+ * self-hosted and Hosted variants, so every runtime follows the same theme resolution path.
+ */
+type TileflowRuntimeManifest = {
+    apiUrl?: string;
+    maps: Record<string, TileflowRuntimeManifestMapEntry>;
+    version: typeof tileflowRuntimeManifestVersion;
+};
+declare const tileflowRuntimeManifestSchema: z.ZodType<TileflowRuntimeManifest>;
+declare function parseTileflowRuntimeManifest(input: unknown): TileflowRuntimeManifest;
+declare function safeParseTileflowRuntimeManifest(input: unknown): z.ZodSafeParseResult<TileflowRuntimeManifest>;
+
+declare const defaultTileflowManifestUrl = "/tileflow/manifest.json";
+declare const defaultTileflowRuntimeView: Readonly<{
+    bearing: 0;
+    center: readonly [number, number];
+    pitch: 0;
+    zoom: 2;
+}>;
+type TileflowAnalytics = {
+    apiUrl?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    mapId?: string;
+    metadata?: Record<string, unknown>;
+    projectId?: string;
+    sdkVersion?: string;
+    source?: string;
+    styleId?: string;
+};
+type TileflowSessionGrantResponse = {
+    billingEnabled?: false;
+    disposition?: 'ordinary' | 'unbilled_fail_open';
+    expiresAt?: string;
+    grant?: string;
+    meterMode?: 'disabled' | 'shadow' | 'enforced';
+    ok: boolean;
+    resourceOrigins?: string[];
+    sessionId: string;
+    usageMode?: 'session';
+    code?: string;
+    retryWithNewSession?: boolean;
+};
+type TileflowSessionController = {
+    readonly sessionId: string;
+    resolveRequestUrl(url: string, analytics: TileflowAnalytics | undefined): Promise<string | undefined>;
+};
+type TileflowMapMarker = {
+    id: string;
+    coordinates: [number, number];
+    color?: string;
+    label?: string;
+};
+type TileflowMapMode = 'interactive' | 'image';
+type TileflowMapModeOptions = {
+    mode?: TileflowMapMode;
+};
+/** Runtime-ready logical map with all relative theme resources already resolved. */
+type TileflowRuntimeManifestMap = TileflowRuntimeManifestMapEntry & {
+    apiUrl?: string;
+    name: string;
+};
+/** `system` is a selector and therefore reserved as a published theme name. */
+type TileflowThemeSelection = string | 'system';
+type TileflowResolvedRuntimeTheme = TileflowRuntimeManifestTheme & {
+    name: string;
+};
+type TileflowRuntimeStyle = {
+    analytics?: TileflowAnalytics;
+    colorScheme?: TileflowRuntimeColorScheme;
+    /** An explicit empty array means the manifest declares that no web fonts are required. */
+    fontFaces?: TileflowStyleFontFace[];
+    revision?: string;
+    style: MapLibreStyle | string;
+    theme?: string;
+};
+declare const tileflowStyleFontFacesMetadataKey: "tileflow:fontFaces";
+declare const tileflowStyleFontFaceLimits: Readonly<{
+    maximumCount: 16;
+    maximumSourceLength: 2048;
+}>;
+type TileflowStyleFontFace = {
+    family: string;
+    source: string;
+    style?: 'italic' | 'normal' | 'oblique';
+    weight?: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
+};
+/** Browser input is either one published Tileflow map or one direct MapLibre style. */
+type TileflowRuntimeSource = {
+    kind: 'tileflow';
+    manifestUrl?: string;
+    map: string;
+} | {
+    kind: 'maplibre';
+    style: MapLibreStyle | string;
+};
+type TileflowRuntimeStyleOptions = {
+    colorScheme?: TileflowRuntimeColorScheme;
+    manifestMap?: TileflowRuntimeManifestMap | null;
+    source: TileflowRuntimeSource;
+    theme?: TileflowThemeSelection;
+};
+type TileflowRuntimeSourceValidation = {
+    ok: true;
+} | {
+    code: 'invalid-source' | 'missing-source';
+    error: string;
+    ok: false;
+};
+type TileflowManifestLoadOptions = {
+    source: TileflowRuntimeSource;
+};
+type TileflowManifestFetchOptions = {
+    /** Successful manifests are shared for this duration. Set to 0 to bypass the cache. */
+    cacheTtlMs?: number;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+    /** Hard request timeout in milliseconds. Defaults to 10 seconds and is capped at 60 seconds. */
+    timeoutMs?: number;
+};
+type TileflowRuntimeViewOptions = TileflowViewConfig & {
+    fallback?: TileflowViewConfig;
+    manifestMap?: TileflowRuntimeManifestMap | null;
+};
+type TileflowRuntimeCenterLike = readonly [number, number] | {
+    lat: number;
+    lng: number;
+} | {
+    lat: number;
+    lon: number;
+};
+declare function shouldLoadTileflowManifest(options: TileflowManifestLoadOptions): boolean;
+declare function validateTileflowRuntimeSource(source: unknown): TileflowRuntimeSourceValidation;
+/** Validate the only runtime selection grammar: one concrete portable name or `system`. */
+declare function validateTileflowThemeSelection(value: unknown): value is TileflowThemeSelection;
+declare function assertValidTileflowRuntimeSource(source: unknown): asserts source is TileflowRuntimeSource;
+declare function resolveTileflowRuntimeStyle(options: TileflowRuntimeStyleOptions): TileflowRuntimeStyle | null;
+/** Resolve one concrete published theme without consulting ambient browser state. */
+declare function resolveTileflowRuntimeTheme(map: TileflowRuntimeManifestMap, selection: TileflowThemeSelection | undefined, colorScheme?: TileflowRuntimeColorScheme): TileflowResolvedRuntimeTheme;
+/** Strictly reads Tileflow-owned web-font metadata from a compiled MapLibre style. */
+declare function getTileflowStyleFontFaces(style: Pick<MapLibreStyle, 'metadata'>): TileflowStyleFontFace[];
+declare function normalizeTileflowUrl(value: string): string;
+declare function createTileflowSessionId(): string;
+declare function createTileflowSessionController(input: {
+    fetch?: typeof fetch;
+    grantTimeoutMs?: number;
+    now?: () => Date;
+    sessionIdFactory?: () => string;
+    source: string;
+}): TileflowSessionController;
+declare function resolveTileflowAnalyticsRequestUrl(url: string, analytics: TileflowAnalytics | undefined, sessionId: string): string | undefined;
+declare function startTileflowSession(analytics: TileflowAnalytics | undefined, input: {
+    mapId?: string;
+    sessionId: string;
+    source: string;
+    styleId?: string;
+}): void;
+declare function getTileflowAnalyticsApiUrl(analytics: TileflowAnalytics): string;
+declare function mergeTileflowAnalytics(userAnalytics: TileflowAnalytics | undefined, runtimeAnalytics: TileflowAnalytics | undefined): TileflowAnalytics | undefined;
+declare function resolveTileflowMapMode(options: TileflowMapModeOptions): TileflowMapMode;
+declare function resolveTileflowRuntimeView(options: TileflowRuntimeViewOptions): TileflowViewConfig;
+declare function normalizeTileflowRuntimeCenter(center: TileflowRuntimeCenterLike | undefined, fallback?: readonly [number, number]): [number, number];
+declare function loadTileflowManifest(url: string, options?: TileflowManifestFetchOptions): Promise<TileflowRuntimeManifest | null>;
+declare function clearTileflowManifestCache(url?: string): void;
+declare function resolveTileflowManifestMap(manifest: TileflowRuntimeManifest, mapName: string): TileflowRuntimeManifestMap | null;
+declare function resolveTileflowStaticImageUrl(input: {
+    center: [number, number];
+    colorScheme?: TileflowRuntimeColorScheme;
+    imageSize: {
+        height: number;
+        width: number;
+    } | null;
+    manifestMap: TileflowRuntimeManifestMap | null;
+    theme?: TileflowThemeSelection;
+    zoom: number;
+}): string | undefined;
+declare function normalizeTileflowStaticImageSize(input: {
+    height: number;
+    width: number;
+}): {
+    height: number;
+    width: number;
+};
+declare function inferTileflowAnalyticsFromStyleUrl(styleUrl: string): TileflowAnalytics | undefined;
+
+export { validateTileflowRuntimeSource as $, defaultTileflowManifestUrl as A, defaultTileflowRuntimeView as B, getTileflowAnalyticsApiUrl as C, getTileflowStyleFontFaces as D, inferTileflowAnalyticsFromStyleUrl as E, loadTileflowManifest as F, mergeTileflowAnalytics as G, normalizeTileflowRuntimeCenter as H, normalizeTileflowStaticImageSize as I, normalizeTileflowUrl as J, parseTileflowRuntimeManifest as K, resolveTileflowAnalyticsRequestUrl as L, resolveTileflowManifestMap as M, resolveTileflowMapMode as N, resolveTileflowRuntimeStyle as O, resolveTileflowRuntimeTheme as P, resolveTileflowRuntimeView as Q, resolveTileflowStaticImageUrl as R, safeParseTileflowRuntimeManifest as S, type TileflowAnalytics as T, shouldLoadTileflowManifest as U, startTileflowSession as V, tileflowRuntimeManifestLimits as W, tileflowRuntimeManifestSchema as X, tileflowRuntimeManifestVersion as Y, tileflowStyleFontFaceLimits as Z, tileflowStyleFontFacesMetadataKey as _, type TileflowStyleFontFace as a, validateTileflowThemeSelection as a0, type TileflowRuntimeStyle as b, type TileflowSessionController as c, type TileflowRuntimeColorScheme as d, type TileflowRuntimeManifest as e, type TileflowManifestFetchOptions as f, type TileflowManifestLoadOptions as g, type TileflowMapMarker as h, type TileflowMapMode as i, type TileflowMapModeOptions as j, type TileflowResolvedRuntimeTheme as k, type TileflowRuntimeCenterLike as l, type TileflowRuntimeManifestMap as m, type TileflowRuntimeManifestMapEntry as n, type TileflowRuntimeManifestTheme as o, type TileflowRuntimeSource as p, type TileflowRuntimeSourceValidation as q, type TileflowRuntimeStyleOptions as r, type TileflowRuntimeSystemThemes as s, type TileflowRuntimeViewOptions as t, type TileflowSessionGrantResponse as u, type TileflowThemeSelection as v, assertValidTileflowRuntimeSource as w, clearTileflowManifestCache as x, createTileflowSessionController as y, createTileflowSessionId as z };

package/dist/runtime.d.ts

@@ -0,0 +1,3 @@
+export { T as TileflowAnalytics, f as TileflowManifestFetchOptions, g as TileflowManifestLoadOptions, h as TileflowMapMarker, i as TileflowMapMode, j as TileflowMapModeOptions, k as TileflowResolvedRuntimeTheme, l as TileflowRuntimeCenterLike, d as TileflowRuntimeColorScheme, e as TileflowRuntimeManifest, m as TileflowRuntimeManifestMap, n as TileflowRuntimeManifestMapEntry, o as TileflowRuntimeManifestTheme, p as TileflowRuntimeSource, q as TileflowRuntimeSourceValidation, b as TileflowRuntimeStyle, r as TileflowRuntimeStyleOptions, s as TileflowRuntimeSystemThemes, t as TileflowRuntimeViewOptions, c as TileflowSessionController, u as TileflowSessionGrantResponse, a as TileflowStyleFontFace, v as TileflowThemeSelection, w as assertValidTileflowRuntimeSource, x as clearTileflowManifestCache, y as createTileflowSessionController, z as createTileflowSessionId, A as defaultTileflowManifestUrl, B as defaultTileflowRuntimeView, C as getTileflowAnalyticsApiUrl, D as getTileflowStyleFontFaces, E as inferTileflowAnalyticsFromStyleUrl, F as loadTileflowManifest, G as mergeTileflowAnalytics, H as normalizeTileflowRuntimeCenter, I as normalizeTileflowStaticImageSize, J as normalizeTileflowUrl, L as resolveTileflowAnalyticsRequestUrl, M as resolveTileflowManifestMap, N as resolveTileflowMapMode, O as resolveTileflowRuntimeStyle, P as resolveTileflowRuntimeTheme, Q as resolveTileflowRuntimeView, R as resolveTileflowStaticImageUrl, U as shouldLoadTileflowManifest, V as startTileflowSession, Z as tileflowStyleFontFaceLimits, _ as tileflowStyleFontFacesMetadataKey, $ as validateTileflowRuntimeSource, a0 as validateTileflowThemeSelection } from './runtime-C4MtSzkB.js';
+import './types-DlUGI6LC.js';
+import 'zod';