@tileflow/core 0.1.0-alpha.16 → 0.1.0-alpha.18

package/README.md

@@ -235,7 +235,8 @@ adds it as `archiveVersion` to the TileJSON URL and records it as
 
 ## Public API
 
-Use the package root only:
+Application config, compilation, runtime resolution, and capture-scene APIs come from the package
+root:
 
 ```ts
 import {
@@ -254,6 +255,37 @@ Capture scene schemas, types, normalization, limits, and schema version are also
 package root. See the [local visual capture contract](https://tileflow.dev/docs/agent-workflow) for
 the CLI workflow and readiness boundary.
 
-Subpaths under `src/`, `themes/`, `templates/`, and `modules/` are internal implementation details and can change during alpha releases.
+Framework adapters can import the browser-only lifecycle kernel explicitly:
+
+```ts
+import {
+  attachTileflowMapLifecycle,
+  createTileflowMarkerController,
+  createTileflowSessionStarter,
+  createTileflowTransformRequest,
+} from '@tileflow/core/browser';
+```
+
+The browser subpath is not re-exported from the root. It is safe to import during SSR, does not
+depend on MapLibre, and reads no browser globals during module evaluation. Adapter authors inject
+their frame scheduler plus MapLibre event and marker operations after mount. The package contract
+is documented in
+[`docs/contracts/framework-browser-runtime.md`](../../docs/contracts/framework-browser-runtime.md).
+
+## Hosted session authorization
+
+The framework adapters use `createTileflowSessionController` to obtain one short-lived session
+grant before eligible hosted style, tile, font, or sprite requests. Concurrent resources share the
+same preflight, grants are attached only to reviewed HTTP(S) origins, and an expired unused session
+rotates once when the server requests it. A controller also rotates after six hours or 10,000
+eligible requests. The preflight has a 10-second client timeout by default; direct controller users
+can set `grantTimeoutMs` from 1 to 120,000 milliseconds.
+
+`analytics.enabled: false` disables only the optional analytics beacon. It does not disable this
+server-owned commercial authorization. User `transformRequest` callbacks still run first; Tileflow
+then decorates only the resulting eligible URL and preserves the other request options.
+
+Other subpaths under `src/`, `themes/`, `templates/`, and `modules/` are internal implementation
+details and can change during alpha releases.
 
 Docs: https://tileflow.dev/docs

package/dist/browser.d.ts

@@ -0,0 +1,77 @@
+import { T as TileflowAnalytics, a as TileflowSessionController } from './runtime-Bg--GMWM.js';
+import 'zod';
+
+type TileflowMapReadinessState = 'error' | 'idle' | 'loading';
+type TileflowMapLifecycleEvent = 'dataloading' | 'error' | 'idle' | 'load' | 'styledataloading';
+type TileflowFrameScheduler<TFrame> = {
+    cancelFrame: (frame: TFrame) => void;
+    requestFrame: (callback: () => void) => TFrame;
+};
+type TileflowMapLifecycleSubscriber<TMap> = (map: TMap, event: TileflowMapLifecycleEvent, listener: () => void) => () => void;
+type TileflowSessionSender = (analytics: TileflowAnalytics | undefined, input: {
+    mapId?: string;
+    sessionId: string;
+    source: string;
+    styleId?: string;
+}) => void;
+type TileflowSessionStarter = {
+    clear: () => void;
+    start: (analytics: TileflowAnalytics | undefined, styleId?: string) => boolean;
+};
+type TileflowMapLifecycleAttachment = {
+    dispose: () => void;
+    invalidate: (state?: TileflowMapReadinessState) => void;
+};
+type TileflowTransformRequestParameters = {
+    url: string;
+};
+type TileflowComposedRequest<TRequest extends TileflowTransformRequestParameters> = Pick<TRequest, 'url'> & Partial<Omit<TRequest, 'url'>>;
+type TileflowTransformRequest<TRequest extends TileflowTransformRequestParameters, TResourceType> = (url: string, resourceType?: TResourceType) => Promise<TileflowComposedRequest<TRequest>> | TileflowComposedRequest<TRequest> | undefined;
+type TileflowUserTransformRequest<TRequest extends TileflowTransformRequestParameters, TResourceType> = (url: string, resourceType?: TResourceType) => Promise<TRequest> | TRequest | undefined;
+type TileflowAsyncAnalyticsTiming = 'request' | 'resolution';
+type TileflowMarkerController<TMap, TDefinition, TMarker> = {
+    clear: () => void;
+    dispose: () => void;
+    replace: (map: TMap, definitions: readonly TDefinition[]) => void;
+};
+declare function createTileflowSessionStarter(options: {
+    getSessionId?: () => string;
+    sessionId: string;
+    source: string;
+    startSession?: TileflowSessionSender;
+}): TileflowSessionStarter;
+declare function attachTileflowMapLifecycle<TMap, TFrame>(options: {
+    getSession?: () => {
+        analytics: TileflowAnalytics | undefined;
+        styleId?: string;
+    };
+    map: TMap;
+    onLoad?: (map: TMap) => void;
+    scheduler: TileflowFrameScheduler<TFrame>;
+    sessionStarter?: TileflowSessionStarter;
+    setState: (state: TileflowMapReadinessState) => void;
+    subscribe: TileflowMapLifecycleSubscriber<TMap>;
+}): TileflowMapLifecycleAttachment;
+declare function createTileflowTransformRequest<TRequest extends TileflowTransformRequestParameters = TileflowTransformRequestParameters, TResourceType = unknown>(options: {
+    always: true;
+    asyncAnalyticsTiming?: TileflowAsyncAnalyticsTiming;
+    getAnalytics: () => TileflowAnalytics | undefined;
+    sessionController?: TileflowSessionController;
+    sessionId: string;
+    transformRequest?: TileflowUserTransformRequest<TRequest, TResourceType>;
+}): TileflowTransformRequest<TRequest, TResourceType>;
+declare function createTileflowTransformRequest<TRequest extends TileflowTransformRequestParameters = TileflowTransformRequestParameters, TResourceType = unknown>(options: {
+    always?: boolean;
+    asyncAnalyticsTiming?: TileflowAsyncAnalyticsTiming;
+    getAnalytics: () => TileflowAnalytics | undefined;
+    sessionController?: TileflowSessionController;
+    sessionId: string;
+    transformRequest?: TileflowUserTransformRequest<TRequest, TResourceType>;
+}): TileflowTransformRequest<TRequest, TResourceType> | undefined;
+declare function createTileflowMarkerController<TMap, TDefinition, TMarker>(options: {
+    attach: (marker: TMarker, map: TMap, definition: TDefinition) => void;
+    create: (definition: TDefinition) => TMarker;
+    remove: (marker: TMarker) => void;
+}): TileflowMarkerController<TMap, TDefinition, TMarker>;
+
+export { type TileflowAsyncAnalyticsTiming, type TileflowComposedRequest, type TileflowFrameScheduler, type TileflowMapLifecycleAttachment, type TileflowMapLifecycleEvent, type TileflowMapLifecycleSubscriber, type TileflowMapReadinessState, type TileflowMarkerController, type TileflowSessionSender, type TileflowSessionStarter, type TileflowTransformRequest, type TileflowTransformRequestParameters, type TileflowUserTransformRequest, attachTileflowMapLifecycle, createTileflowMarkerController, createTileflowSessionStarter, createTileflowTransformRequest };

package/dist/browser.js

@@ -0,0 +1,337 @@
+// src/runtime.ts
+var maxStaticImagePixels = 1280 * 1280;
+var manifestCache = new globalThis.Map();
+function normalizeTileflowUrl(value) {
+  return value.replace(/\/+$/, "");
+}
+function resolveTileflowAnalyticsRequestUrl(url, analytics, sessionId) {
+  if (!analytics || analytics.enabled === false) {
+    return void 0;
+  }
+  const apiUrl = getTileflowAnalyticsApiUrl(analytics);
+  if (!apiUrl || !isTileflowTileUrl(url, apiUrl)) {
+    return void 0;
+  }
+  const nextUrl = new URL(url);
+  nextUrl.searchParams.set("session", sessionId);
+  if (analytics.mapId) {
+    nextUrl.searchParams.set("map", analytics.mapId);
+  }
+  if (analytics.styleId) {
+    nextUrl.searchParams.set("styleId", analytics.styleId);
+  }
+  return nextUrl.toString();
+}
+function startTileflowSession(analytics, input) {
+  if (!analytics || analytics.enabled === false || !input.mapId || typeof navigator === "undefined") {
+    return;
+  }
+  const endpoint = analytics.endpoint ?? `${getTileflowAnalyticsApiUrl(analytics)}/v1/sessions/analytics`;
+  const payload = JSON.stringify({
+    mapId: input.mapId,
+    metadata: analytics.metadata,
+    referrer: typeof document === "undefined" ? void 0 : document.referrer || "",
+    sdkVersion: analytics.sdkVersion,
+    sessionId: input.sessionId,
+    source: analytics.source ?? input.source,
+    styleId: input.styleId,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const blob = new Blob([payload], { type: "application/json" });
+  if (navigator.sendBeacon?.(endpoint, blob)) {
+    return;
+  }
+  void fetch(endpoint, {
+    body: payload,
+    credentials: "omit",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    keepalive: true,
+    method: "POST"
+  }).catch(() => void 0);
+}
+function getTileflowAnalyticsApiUrl(analytics) {
+  if (analytics.apiUrl) {
+    return normalizeTileflowUrl(analytics.apiUrl);
+  }
+  if (analytics.endpoint) {
+    try {
+      const url = new URL(analytics.endpoint, getTileflowLocationOrigin());
+      return url.origin;
+    } catch {
+      return "https://api.tileflow.dev";
+    }
+  }
+  return "https://api.tileflow.dev";
+}
+function isTileflowTileUrl(url, apiUrl) {
+  try {
+    const parsedUrl = new URL(url);
+    const parsedApiUrl = new URL(apiUrl);
+    return parsedUrl.origin === parsedApiUrl.origin && isTilePath(parsedUrl);
+  } catch {
+    return false;
+  }
+}
+function isTilePath(url) {
+  return url.pathname.startsWith("/tiles/") || url.pathname.startsWith("/v1/tiles/");
+}
+function getTileflowLocationOrigin() {
+  if (typeof window === "undefined") {
+    return "http://localhost";
+  }
+  return window.location.origin;
+}
+
+// src/browser.ts
+function createTileflowSessionStarter(options) {
+  const starts = /* @__PURE__ */ new Set();
+  const send = options.startSession ?? startTileflowSession;
+  return {
+    clear() {
+      starts.clear();
+    },
+    start(analytics, styleId) {
+      const mapId = analytics?.mapId;
+      const sessionId = options.getSessionId?.() ?? options.sessionId;
+      if (!mapId) {
+        return false;
+      }
+      const key = `${sessionId}:${mapId}:${styleId ?? ""}`;
+      if (starts.has(key)) {
+        return false;
+      }
+      starts.add(key);
+      send(analytics, {
+        mapId,
+        sessionId,
+        source: options.source,
+        styleId
+      });
+      return true;
+    }
+  };
+}
+function attachTileflowMapLifecycle(options) {
+  let disposed = false;
+  let generation = 0;
+  const frames = /* @__PURE__ */ new Set();
+  const unsubscribers = [];
+  const cancelFrames = () => {
+    for (const frame of frames) {
+      options.scheduler.cancelFrame(frame);
+    }
+    frames.clear();
+  };
+  const invalidate = (state) => {
+    generation += 1;
+    cancelFrames();
+    if (state) {
+      options.setState(state);
+    }
+  };
+  const scheduleFrame = (callback) => {
+    const frame = options.scheduler.requestFrame(() => {
+      frames.delete(frame);
+      callback();
+    });
+    frames.add(frame);
+  };
+  const handleLoad = () => {
+    if (disposed) {
+      return;
+    }
+    options.onLoad?.(options.map);
+    const session = options.getSession?.();
+    if (session) {
+      options.sessionStarter?.start(session.analytics, session.styleId);
+    }
+  };
+  const handleLoading = () => {
+    if (!disposed) {
+      invalidate("loading");
+    }
+  };
+  const handleIdle = () => {
+    if (disposed) {
+      return;
+    }
+    generation += 1;
+    cancelFrames();
+    const run = generation;
+    scheduleFrame(() => {
+      if (disposed || generation !== run) {
+        return;
+      }
+      scheduleFrame(() => {
+        if (!disposed && generation === run) {
+          options.setState("idle");
+        }
+      });
+    });
+  };
+  const handleError = () => {
+    if (!disposed) {
+      invalidate("error");
+    }
+  };
+  invalidate("loading");
+  try {
+    for (const [event, listener] of [
+      ["load", handleLoad],
+      ["dataloading", handleLoading],
+      ["styledataloading", handleLoading],
+      ["idle", handleIdle],
+      ["error", handleError]
+    ]) {
+      unsubscribers.push(options.subscribe(options.map, event, listener));
+    }
+  } catch (error) {
+    disposed = true;
+    generation += 1;
+    cancelFrames();
+    try {
+      disposeFunctions(unsubscribers);
+    } catch {
+    }
+    throw error;
+  }
+  return {
+    dispose() {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      generation += 1;
+      cancelFrames();
+      disposeFunctions(unsubscribers);
+    },
+    invalidate(state) {
+      if (!disposed) {
+        invalidate(state);
+      }
+    }
+  };
+}
+function createTileflowTransformRequest(options) {
+  if (!options.always && !options.transformRequest) {
+    const analytics = options.getAnalytics();
+    const requiresCommercialSession = Boolean(options.sessionController && analytics?.mapId);
+    if (!requiresCommercialSession && (!analytics || analytics.enabled === false)) {
+      return void 0;
+    }
+  }
+  const asyncAnalyticsTiming = options.asyncAnalyticsTiming ?? "request";
+  return (url, resourceType) => {
+    const request = options.transformRequest?.(url, resourceType);
+    const analyticsAtRequest = asyncAnalyticsTiming === "request" ? options.getAnalytics() : void 0;
+    if (isPromiseLike(request)) {
+      return request.then(
+        (resolvedRequest) => applyTileflowRequest(
+          url,
+          resolvedRequest,
+          asyncAnalyticsTiming === "resolution" ? options.getAnalytics() : analyticsAtRequest,
+          options.sessionId,
+          options.sessionController
+        ) ?? resolvedRequest
+      );
+    }
+    return applyTileflowRequest(
+      url,
+      request,
+      asyncAnalyticsTiming === "resolution" ? options.getAnalytics() : analyticsAtRequest,
+      options.sessionId,
+      options.sessionController
+    );
+  };
+}
+function createTileflowMarkerController(options) {
+  let markers = [];
+  const clear = () => {
+    const previousMarkers = markers;
+    markers = [];
+    removeMarkers(previousMarkers, options.remove);
+  };
+  return {
+    clear,
+    dispose: clear,
+    replace(map, definitions) {
+      clear();
+      const nextMarkers = [];
+      try {
+        for (const definition of definitions) {
+          const marker = options.create(definition);
+          nextMarkers.push(marker);
+          options.attach(marker, map, definition);
+        }
+      } catch (error) {
+        try {
+          removeMarkers(nextMarkers, options.remove);
+        } catch {
+        }
+        throw error;
+      }
+      markers = nextMarkers;
+    }
+  };
+}
+function applyTileflowRequest(url, request, analytics, sessionId, sessionController) {
+  const requestUrl = request?.url ?? url;
+  if (sessionController) {
+    return sessionController.resolveRequestUrl(requestUrl, analytics).then(
+      (nextUrl) => composeTileflowRequest(url, request, nextUrl, true) ?? { url }
+    );
+  }
+  return composeTileflowRequest(
+    url,
+    request,
+    resolveTileflowAnalyticsRequestUrl(requestUrl, analytics, sessionId),
+    false
+  );
+}
+function composeTileflowRequest(originalUrl, request, nextUrl, ensureRequest) {
+  if (!nextUrl) {
+    return request ?? (ensureRequest ? { url: originalUrl } : void 0);
+  }
+  return request ? { ...request, url: nextUrl } : { url: nextUrl };
+}
+function disposeFunctions(disposers) {
+  let firstError;
+  let failed = false;
+  for (const dispose of disposers.splice(0).reverse()) {
+    try {
+      dispose();
+    } catch (error) {
+      if (!failed) firstError = error;
+      failed = true;
+    }
+  }
+  if (failed) {
+    throw firstError;
+  }
+}
+function isPromiseLike(value) {
+  return Boolean(value && typeof value.then === "function");
+}
+function removeMarkers(markers, remove) {
+  let firstError;
+  let failed = false;
+  for (const marker of markers) {
+    try {
+      remove(marker);
+    } catch (error) {
+      if (!failed) firstError = error;
+      failed = true;
+    }
+  }
+  if (failed) {
+    throw firstError;
+  }
+}
+export {
+  attachTileflowMapLifecycle,
+  createTileflowMarkerController,
+  createTileflowSessionStarter,
+  createTileflowTransformRequest
+};