@tileflow/core 0.1.0-alpha.26 → 0.1.0-alpha.27

package/dist/native.d.ts

@@ -20,12 +20,203 @@ declare class TileflowNativeUrlError extends TypeError {
     readonly field: TileflowNativeUrlField;
     constructor(code: TileflowNativeUrlErrorCode, field: TileflowNativeUrlField);
 }
-/** Resolve a native manifest URL. There is intentionally no browser-relative default. */
+
+/** 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 TileflowViewConfig = {
+    bearing?: number;
+    center?: readonly [number, number];
+    pitch?: number;
+    zoom?: number;
+};
+
+/** 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';
+};
+
+/** The first and only public multi-theme runtime manifest contract. */
+declare const tileflowRuntimeManifestVersion: 1;
+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';
+};
 /**
- * Resolve a resource against its owning manifest, style or TileJSON document.
- * This checks URL policy only: it neither fetches resources nor authorizes requests.
+ * 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.
  */
-declare function resolveTileflowNativeResourceUrl(value: unknown, options: TileflowNativeResourceUrlOptions): string;
+type TileflowRuntimeManifest = {
+    apiUrl?: string;
+    maps: Record<string, TileflowRuntimeManifestMapEntry>;
+    version: typeof tileflowRuntimeManifestVersion;
+};
+
+/** 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;
+    /** 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;
 
-export { type TileflowNativeNetworkOptions, type TileflowNativeResourceUrlOptions, TileflowNativeUrlError, type TileflowNativeUrlErrorCode, type TileflowNativeUrlField, resolveTileflowNativeManifestUrl, resolveTileflowNativeResourceUrl, tileflowNativeUrlLimits };
+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, createTileflowNativeSourceController, loadTileflowNativeManifest, resolveTileflowNativeInitialView, resolveTileflowNativeManifestUrl, resolveTileflowNativeResourceUrl, tileflowNativeManifestLimits, tileflowNativeUrlLimits };