@tileflow/core 0.1.0-alpha.4 → 0.1.0-alpha.41

package/dist/native.d.ts

@@ -0,0 +1,365 @@
+/** Artistic presets; selecting one never starts a clock or moves the real sun. */
+declare const tileflowTimesOfDay: readonly ["day", "dawn", "dusk", "night"];
+type TileflowTimeOfDay = (typeof tileflowTimesOfDay)[number];
+/** A named theme family points to complete, already compiled themes. */
+type TileflowTimeOfDayVariants = Readonly<Record<string, Readonly<Partial<Record<TileflowTimeOfDay, string>>>>>;
+
+/** URL resolution for native clients, without a renderer or an ambient application origin. */
+declare const tileflowNativeUrlLimits: Readonly<{
+    maximumLength: 2048;
+}>;
+type TileflowNativeNetworkOptions = {
+    /** An exact HTTP development origin; never inferred from the device or environment. */
+    developmentOrigin?: string;
+};
+type TileflowNativeResourceUrlOptions = TileflowNativeNetworkOptions & {
+    /** The absolute URL of the document declaring this resource, after any approved redirects. */
+    documentUrl: string;
+    /** Preserve supported placeholders in the path or query, without expanding them. */
+    template?: 'tile' | 'glyphs';
+};
+type TileflowNativeUrlErrorCode = 'NATIVE_URL_INVALID' | 'NATIVE_URL_ABSOLUTE_REQUIRED' | 'NATIVE_URL_HTTPS_REQUIRED' | 'NATIVE_URL_DEVELOPMENT_ORIGIN_INVALID' | 'NATIVE_URL_TEMPLATE_INVALID';
+type TileflowNativeUrlField = 'manifestUrl' | 'documentUrl' | 'resourceUrl' | 'developmentOrigin';
+/** Safe to report without exposing URL credentials, query parameters or filesystem paths. */
+declare class TileflowNativeUrlError extends TypeError {
+    readonly code: TileflowNativeUrlErrorCode;
+    readonly field: TileflowNativeUrlField;
+    constructor(code: TileflowNativeUrlErrorCode, field: TileflowNativeUrlField);
+}
+
+/** Resolve an explicit manifest URL with the private WHATWG parser, not the ambient URL. */
+declare function resolveTileflowNativeManifestUrl(value: unknown, options?: TileflowNativeNetworkOptions): string;
+/** Resolve a resource against its owner without fetching it or authorizing requests. */
+declare function resolveTileflowNativeResourceUrl(value: unknown, options: TileflowNativeResourceUrlOptions): string;
+
+type TileflowColor = `#${string}`;
+type TileflowViewConfig = {
+    bearing?: number;
+    center?: readonly [number, number];
+    pitch?: number;
+    zoom?: number;
+};
+type MapLibreSprite = string | Array<{
+    id: string;
+    url: string;
+}>;
+type TileflowProjection = 'globe' | 'mercator';
+type TileflowLight = {
+    anchor?: 'map' | 'viewport';
+    color?: TileflowColor;
+    intensity?: number;
+    position?: readonly [number, number, number];
+};
+type MapLibreStyle = {
+    sky?: Record<string, unknown>;
+    version: 8;
+    name: string;
+    glyphs?: string;
+    light?: TileflowLight;
+    projection?: {
+        type: TileflowProjection;
+    };
+    sprite?: MapLibreSprite;
+    sources: Record<string, Record<string, unknown>>;
+    layers: Array<Record<string, unknown>>;
+    terrain?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+};
+
+/** Runtime-ready logical map with all relative theme resources already resolved. */
+type TileflowRuntimeManifestMap = TileflowRuntimeManifestMapEntry & {
+    apiUrl?: string;
+    name: string;
+};
+type TileflowResolvedRuntimeTheme = TileflowRuntimeManifestTheme & {
+    name: string;
+};
+type TileflowStyleFontFace = {
+    family: string;
+    source: string;
+    style?: 'italic' | 'normal' | 'oblique';
+    weight?: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
+};
+/**
+ * A continuous blend of named themes of one Tileflow map. `position` places the map between
+ * neighbouring themes: 0 is the first, 1 the second, and 1.25 a quarter of the way from the second
+ * to the third.
+ */
+type TileflowThemeBlendSelection = Readonly<{
+    /** From 0 to `themes.length - 1`. */
+    position: number;
+    /** Two to eight concrete theme names of the map, in blend order. */
+    themes: readonly string[];
+}>;
+declare const tileflowThemeBlendLimits: Readonly<{
+    maximumThemes: 8;
+    minimumThemes: 2;
+}>;
+declare function validateTileflowThemeBlendSelection(value: unknown): value is TileflowThemeBlendSelection;
+/** The theme nearest to a blend position, which a blend shows when it cannot blend. */
+declare function nearestTileflowBlendTheme(blend: TileflowThemeBlendSelection): string;
+
+/** The original public multi-theme runtime manifest contract. */
+declare const tileflowRuntimeManifestVersion: 1;
+/** V2 adds the optional time-of-day catalog; maps without it still publish V1. */
+declare const tileflowTimeOfDayManifestVersion: 2;
+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>;
+    timeOfDay?: TileflowTimeOfDayVariants;
+    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 | typeof tileflowTimeOfDayManifestVersion;
+};
+
+/** The adapter must honor the requested read bound, without first buffering an unbounded body. */
+type TileflowNativeManifestReader = {
+    read(maximumBytes: number): Promise<{
+        done: true;
+        value?: undefined;
+    } | {
+        done: false;
+        value: Uint8Array;
+    }>;
+    cancel(): void | Promise<void>;
+};
+type TileflowNativeManifestResponse = {
+    /** Absolute final URL after redirects approved by the acquisition adapter. */
+    url: string;
+    status: number;
+    reader: TileflowNativeManifestReader;
+};
+/** Cancellation must be available immediately, including before response headers arrive. */
+type TileflowNativeManifestOperation = {
+    response: Promise<TileflowNativeManifestResponse>;
+    cancel(): void | Promise<void>;
+};
+type TileflowNativeManifestAcquire = (url: string, options: Readonly<{
+    maximumBytes: number;
+}>) => TileflowNativeManifestOperation;
+/** No AbortController/EventTarget construction or reason inspection is required by Core. */
+type TileflowNativeAbortSignal = {
+    readonly aborted: boolean;
+    addEventListener(type: 'abort', listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: 'abort', listener: () => void): void;
+};
+type TileflowNativeManifestLoadOptions = TileflowNativeNetworkOptions & {
+    acquire: TileflowNativeManifestAcquire;
+    signal?: TileflowNativeAbortSignal;
+};
+/** A published Tileflow map with an explicit manifest URL. Does not create a renderer. */
+type TileflowNativeSource = {
+    map: string;
+    manifestUrl: string;
+    /** Exact HTTP origin permitted by this development source. HTTPS remains allowed. */
+    developmentOrigin?: string;
+};
+type TileflowNativeSourceOptions = {
+    theme?: string;
+    timeOfDay?: TileflowTimeOfDay;
+    /** Required only for theme="system"; no ambient appearance access. */
+    colorScheme?: TileflowRuntimeColorScheme;
+    signal?: TileflowNativeAbortSignal;
+};
+type Immutable<T> = T extends object ? {
+    readonly [K in keyof T]: Immutable<T[K]>;
+} : T;
+type TileflowNativeManifestResult = {
+    readonly manifestUrl: string;
+    readonly manifest: Immutable<TileflowRuntimeManifest>;
+};
+type TileflowNativeSourceState = {
+    readonly status: 'loading';
+    readonly generation: number;
+} | ({
+    readonly status: 'ready';
+    readonly generation: number;
+    readonly source: Readonly<TileflowNativeSource>;
+    readonly map: Immutable<TileflowRuntimeManifestMap>;
+    readonly theme: Immutable<TileflowResolvedRuntimeTheme>;
+} & TileflowNativeManifestResult) | {
+    readonly status: 'error';
+    readonly generation: number;
+    readonly error: TileflowNativeSourceError;
+};
+type TileflowNativeSourceController = {
+    /** Undefined until the first replacement. Disposed controllers retain their last snapshot. */
+    readonly state: TileflowNativeSourceState | undefined;
+    replace(source: TileflowNativeSource, options?: TileflowNativeSourceOptions): Promise<void>;
+    subscribe(listener: (state: TileflowNativeSourceState) => void): () => void;
+    dispose(): void;
+};
+declare const messages: {
+    readonly NATIVE_SOURCE_INVALID: "Expected a valid native source or renderer-neutral view.";
+    readonly NATIVE_SOURCE_ABORTED: "The source operation was cancelled.";
+    readonly NATIVE_SOURCE_DISPOSED: "The source controller has been disposed.";
+    readonly NATIVE_MANIFEST_URL_INVALID: "Expected a safe absolute manifest URL and an exact development origin.";
+    readonly NATIVE_MANIFEST_REQUEST_FAILED: "Manifest acquisition failed.";
+    readonly NATIVE_MANIFEST_RESPONSE_INVALID: "Expected a bounded byte reader and an explicit final response URL.";
+    readonly NATIVE_MANIFEST_ACCESS_DENIED: "Manifest access was denied.";
+    readonly NATIVE_MANIFEST_NOT_FOUND: "The manifest was not found.";
+    readonly NATIVE_MANIFEST_TOO_LARGE: "The manifest exceeds the 1 MiB limit.";
+    readonly NATIVE_MANIFEST_UTF8_INVALID: "The manifest body is not valid UTF-8.";
+    readonly NATIVE_MANIFEST_JSON_INVALID: "The manifest body is not valid JSON.";
+    readonly NATIVE_MANIFEST_INVALID: "The manifest does not satisfy the version-1 runtime contract.";
+    readonly NATIVE_MANIFEST_RESOURCE_INVALID: "A manifest resource URL is outside the native URL policy.";
+    readonly NATIVE_MAP_NOT_FOUND: "The requested map is not declared by the manifest.";
+    readonly NATIVE_THEME_INVALID: "Expected a declared concrete theme or an explicitly supplied system color scheme.";
+};
+type TileflowNativeSourceErrorCode = keyof typeof messages;
+type TileflowNativeSourceErrorField = 'source' | 'signal' | 'manifestUrl' | 'response' | 'body' | 'map' | 'theme' | 'view';
+/** Contains no body, URL, remote cause, parser details, or AbortSignal.reason. */
+declare class TileflowNativeSourceError extends Error {
+    readonly code: TileflowNativeSourceErrorCode;
+    readonly field: TileflowNativeSourceErrorField;
+    readonly kind: 'terminal' | 'cancelled';
+    constructor(code: TileflowNativeSourceErrorCode, field: TileflowNativeSourceErrorField);
+}
+
+declare const tileflowNativeManifestLimits: Readonly<{
+    maximumBytes: number;
+    maximumChunkBytes: number;
+    maximumDepth: 64;
+}>;
+/** Acquire only the manifest. There is no default network client, cache, retry or session. */
+declare function loadTileflowNativeManifest(manifestUrl: string, options: TileflowNativeManifestLoadOptions): Promise<TileflowNativeManifestResult>;
+
+/** A renderer-neutral lifecycle for an explicitly located Tileflow manifest. */
+declare function createTileflowNativeSourceController(options: {
+    acquire: TileflowNativeManifestAcquire;
+}): TileflowNativeSourceController;
+
+type TileflowNativeInitialView = Readonly<Required<TileflowViewConfig>>;
+/** Inputs are views, not renderer props. Validate all supplied levels before applying precedence. */
+type TileflowNativeInitialViewOptions = {
+    /** Highest precedence, supplied explicitly by the application. */
+    view?: TileflowViewConfig;
+    /** View values extracted by an adapter from its renderer options. */
+    mapOptionsView?: TileflowViewConfig;
+    /** The selected manifest map's view, when present. */
+    manifestView?: TileflowViewConfig;
+};
+/** Resolve once or repeatedly without changing source generations, themes or acquisition. */
+declare function resolveTileflowNativeInitialView(options?: TileflowNativeInitialViewOptions): TileflowNativeInitialView;
+
+/**
+ * Theme blending plans one MapLibre style that can show any point between the themes of one map.
+ *
+ * The themes of a Tileflow map compile to the same sources, layers, filters, and expressions; they
+ * differ only in token values: colours, numbers, and image names. A plan keeps the first theme's
+ * structure and records every value that differs as a template the browser fills in for a blend
+ * position: 0 is the first theme, 1 the second, and 1.25 a quarter of the way from the second to
+ * the third. Filling a template needs no expression parsing in the browser, so the renderer only
+ * receives plain values.
+ *
+ * Values that MapLibre evaluates per feature (data-driven values, such as a fill colour chosen by
+ * land-use class) are baked into tiles, and changing them re-lays the whole source out. A plan
+ * splits such a layer into one layer per branch that a feature can take through the value's
+ * decisions on feature data, each filtered to the features that take it, so each value depends
+ * only on zoom and the blend position. A value that reads feature data continuously is drawn once
+ * per theme instead, and the copies cross-fade by opacity. Images are mixed in their pixels.
+ * Values that read feature state cannot be split, because filters cannot read state; they switch
+ * when the dominant theme changes.
+ */
+/** A paint value that the browser sets as the blend moves. */
+type TileflowThemeBlendPaint = Readonly<{
+    layer: string;
+    property: string;
+    template: unknown;
+    /** Ground values follow the blend position; symbol values follow the label cross-fade. */
+    follows: TileflowThemeBlendClock;
+}>;
+/** Image names whose artwork differs between themes and is mixed in pixels. */
+type TileflowThemeBlendImage = Readonly<{
+    names: readonly string[];
+    follows: TileflowThemeBlendClock;
+}>;
+/** A value that can only change all at once, when the dominant theme changes. */
+type TileflowThemeBlendSwitch = Readonly<{
+    layer: string;
+    group: 'layout' | 'paint';
+    property: string;
+    values: readonly unknown[];
+}>;
+/**
+ * `position` values follow the blend; `dominant` values follow a short cross-fade that starts when
+ * the nearest theme changes. Labels use it because light lettering on a dark plate and dark
+ * lettering on a light plate meet in the same grey halfway.
+ */
+type TileflowThemeBlendClock = 'dominant' | 'position';
+type TileflowThemeBlendPlan = Readonly<{
+    /** Number of themes; blend positions run from 0 to `themes - 1`. */
+    themes: number;
+    paints: readonly TileflowThemeBlendPaint[];
+    images: readonly TileflowThemeBlendImage[];
+    switches: readonly TileflowThemeBlendSwitch[];
+    /** Root sky and light, when they differ between themes. */
+    sky?: unknown;
+    light?: unknown;
+    summary: Readonly<{
+        splitLayers: number;
+        copiedLayers: number;
+        /** Per-theme layers of which only the nearest theme's copy is shown. */
+        switchedLayers: number;
+        switchedValues: number;
+    }>;
+    /** The style at a blend position: every template filled, every switch at the nearest theme. */
+    styleAt(position: number): MapLibreStyle;
+}>;
+type TileflowThemeBlendOptions = Readonly<{
+    /**
+     * How icon images that differ between themes change. `mix` (the default) mixes their artwork in
+     * pixels under the first theme's image names. `switch` changes the image names when the nearest
+     * theme changes, for renderers that cannot replace an image's pixels while keeping its stretch
+     * and content metadata.
+     */
+    iconImages?: 'mix' | 'switch';
+    /**
+     * How values that read feature data change when they can be neither split nor cross-faded.
+     * `values` (the default) sets each value when the nearest theme changes. `layers` draws such a
+     * layer once per theme and shows only the nearest theme's copy, for renderers that cannot set
+     * data-driven values at run time reliably.
+     */
+    featureSwitches?: 'layers' | 'values';
+}>;
+declare class TileflowThemeBlendError extends Error {
+    name: string;
+}
+/** Plans a blend of two or more compiled themes of one map, in blend order. */
+declare function planTileflowThemeBlend(styles: readonly MapLibreStyle[], options?: TileflowThemeBlendOptions): TileflowThemeBlendPlan;
+/** Fills one blend template for a position. Plain values pass through unchanged. */
+declare function fillTileflowThemeBlendTemplate(template: unknown, position: number): unknown;
+
+export { type TileflowNativeAbortSignal, type TileflowNativeInitialView, type TileflowNativeInitialViewOptions, type TileflowNativeManifestAcquire, type TileflowNativeManifestLoadOptions, type TileflowNativeManifestOperation, type TileflowNativeManifestReader, type TileflowNativeManifestResponse, type TileflowNativeManifestResult, type TileflowNativeNetworkOptions, type TileflowNativeResourceUrlOptions, type TileflowNativeSource, type TileflowNativeSourceController, TileflowNativeSourceError, type TileflowNativeSourceErrorCode, type TileflowNativeSourceErrorField, type TileflowNativeSourceOptions, type TileflowNativeSourceState, TileflowNativeUrlError, type TileflowNativeUrlErrorCode, type TileflowNativeUrlField, type TileflowThemeBlendClock, TileflowThemeBlendError, type TileflowThemeBlendImage, type TileflowThemeBlendOptions, type TileflowThemeBlendPaint, type TileflowThemeBlendPlan, type TileflowThemeBlendSelection, type TileflowThemeBlendSwitch, type TileflowTimeOfDay, type TileflowTimeOfDayVariants, createTileflowNativeSourceController, fillTileflowThemeBlendTemplate, loadTileflowNativeManifest, nearestTileflowBlendTheme, planTileflowThemeBlend, resolveTileflowNativeInitialView, resolveTileflowNativeManifestUrl, resolveTileflowNativeResourceUrl, tileflowNativeManifestLimits, tileflowNativeUrlLimits, tileflowThemeBlendLimits, validateTileflowThemeBlendSelection };